brt — обзор CLI

brt — единственный исполняемый developer CLI платформы. Он связывает TypeScript-проект, workspace на сервере и два независимых target: dev для быстрой разработки и production для явного deploy.

@holocronlab/botruntime-adk — библиотека генерации и runtime, которую вызывает brt внутри agent workflow. Это не второй CLI и не отдельная команда, которую нужно устанавливать или запускать рядом.

Главная граница проста:

• brt dev запускает код локально и подключает к нему отдельного dev-бота через tunnel;
• brt deploy --adk собирает agent-проект и обновляет production-бота;
• brt deploy --adk --watch — явно выбранный постоянный cloud redeploy, а не скрытая семантика команды dev;
• brt bots deployments abort безопасно завершает застрявший pre-schema deploy, сохраняя активную production-версию.

Как связаны проект и окружения

agent.json — каноническая production-привязка агентного проекта, которую можно хранить в Git. agent.local.json хранит локальные настройки и привязку dev-бота и не должен попадать в Git. bot.json остаётся совместимым fallback для классических и старых проектов; в новом агентном проекте он не может переопределить agent.json.

Командная карта

Практические сигнатуры и основные флаги находятся в справочнике; полный набор конкретной версии печатает brt <command> --help. Пошаговая модель окружений и разбор ошибок — на странице «Рабочий цикл: dev → production».

brt traces читает полные трейсы выбранного conversation, точного trace ID либо time-bounded workflow/action. В production команда берёт canonical workspace и bot из project link, в dev — проверенный opaque runtime target, созданный brt dev. Оба режима аутентифицируются PAT выбранного профиля и не позволяют path, query или header переопределить его workspace authority. Ответ API содержит исходные attributes и payload, включая tool input/output и LLM request/response. CLI всегда показывает tool input/output, а LLM-контент — только с --include-llm. Для error span команда показывает runtime message, с --verbose — stack и attributes/payload выбранного режима. Платформа не редактирует сохранённое содержимое: разработчик бота отвечает за данные, которые его runtime отправляет в telemetry.

brt conversations list показывает только bounded metadata диалогов: ID, timestamps, channel, integration и message count. brt conversations show <id> не читает весь диалог: по умолчанию команда запрашивает максимум 20 сырых trace rows и только затем группирует их в turns. Окно задаётся через since, until и limit как tokens или одноимённые флаги. Если доступна более старая часть, CLI возвращает resumable nextToken для --next-token.

Timeline остаётся metadata-only. Conversation tags, prompts, model responses, tool input/output, message/document payloads и неотфильтрованные attrs в вывод не попадают. Production/dev target и PAT authority имеют ту же fail-loud семантику, что у brt traces.

brt eval [name] (или явный brt eval run [name]) синхронизирует локальный eval manifest/fixtures, провижинит first-party Chat при необходимости и запускает задеплоенный builtin_eval_runner; brt eval runs читает hosted history. Production использует canonical numeric bot и сохранённый per-bot key, dev — PAT, суженный attested opaque runtime bot. Вывод содержит только typed verdict, timing и assertion metadata: prompts, сообщения, model responses, evidence и raw workflow/evaluator errors не печатаются. Каждый ход при этом несёт opaque conversationId и traceId, а execution failure — стабильные code/phase/turn. Поэтому brt eval runs <id> --verbose даёт готовый переход к brt traces --conversation-id <id> без раскрытия сообщений или stack trace. Повторные независимые runs включаются через --repeat, bounded concurrency — через --max-concurrency, а CI-порог — через --min-pass-rate.

Одноразовые agent scripts

brt run <scriptPath> [scriptArgs..] запускает TypeScript-файл локально в контексте выбранного agent target. В отличие от brt dev, команда не поднимает worker, watcher, reverse tunnel или callback receiver и возвращает exit code самого процесса.

# Attested development target, ранее подготовленный brt dev
brt run scripts/reconcile.ts claimant-42

# Перегенерировать target-specific artifacts
brt run scripts/reconcile.ts --force

# Canonical production target из agent.json
brt run scripts/audit.ts --prod

Dev-режим получает публичную конфигурацию target с тем же приоритетом, что worker: Cloud, локальное окружение, immutable runtime identity. Ошибка авторизации, сети или attestation останавливает команду до пользовательского кода. Сохранённые production secrets на машину разработчика не скачиваются.

Durable workflows

brt workflows run создаёт durable workflow идемпотентно; brt workflows list возвращает cursor-paginated историю, brt workflows show читает одну ограниченную проекцию, а brt workflows wait продолжает наблюдение:

brt workflows run collectDocuments --input-file ./input.json
brt workflows list --status listening --limit 20
brt workflows show wkflow_0123456789abcdef01234567 --steps
brt workflows wait wkflow_0123456789abcdef01234567 --timeout 300000

У create есть idempotency key и fingerprint запроса. Если сетевой исход неизвестен, нужно повторить тот же запрос к тому же target с напечатанным ключом; новый ключ означает новый workflow. --timeout ограничивает только ожидание CLI и никогда не отменяет durable process. Отдельный --workflow-timeout задаёт persisted deadline исполнения.

По умолчанию list/show/wait не раскрывают произвольные input, output, tags, сырые причины ошибок и step outputs. --include-data явно добавляет только workflow input/output/tags, а --steps — bounded metadata и безопасную диагностику. Все четыре команды принимают --dev для attested development target.

Профиль и авторизация

Профиль хранит endpoint, выбранный воркспейс и PAT в ~/.brt/profiles.json. brt login по умолчанию запускает device authorization в браузере и обращается к облачной платформе https://botruntime.ru.

Для ручной вставки PAT используйте --no-device. Для CI передайте --token и --workspace-id. Необязательный --api-url нужен только для прокси, staging и разработки платформы. В обычном входе его указывать не нужно.

brt login
brt profiles active
brt profiles use team-b

Токен профиля и per-bot key решают разные задачи:

brt logs использует workspace/profile PAT и вложенный маршрут конкретного бота. Тот же device-login профиль, которым выполняется deploy, сразу подходит для чтения логов; per-bot key для этой команды не нужен. brt logs --dev проверяет opaque runtime target из dev cache и читает связанный numeric bot; передавать runtime UUID через production-флаг --bot-id не нужно.

Первый deploy --adk может сам создать production-бота и безопасно сохранить выданный per-bot key. Для существующего бота используйте brt link:

export BOT_ID='42'
printf '%s' "$BOT_KEY" | brt link --bot-id "$BOT_ID" --key-stdin

CLI сначала сохраняет ключ и только затем link-файл: аварийный обрыв не оставит проект с привязкой, для которой потеряны данные доступа.

Dev и production

brt dev создаёт отдельный dev target в облачной платформе и запускает код на вашей машине. Production-бот при этом не изменяется.

В консоли этот target показывается как Development-окружение того же бота. Повторный brt dev переиспользует target из agent.local.json без смены его ID и без переноса данных: история Evals остаётся в исходном окружении. Отдельный checkout получает собственный Development-runtime того же проекта.

brt deploy --adk собирает проект и обновляет production target. Связь проекта с ботом хранится в agent.json или bot.json.

Если staged deployment не может завершить drain, CLI оставляет traffic fence и показывает незавершённые units. После reconciliation повторите тот же deploy. Если staged-версию нужно окончательно отбросить до любых изменений схемы, выполните brt bots deployments abort <deploymentId> --confirm. Команда повторно проверяет phase и schemaMutated, после подтверждения читает актуальный fence generation из Cloud и выполняет CAS-abort. Активный bundle сохраняется, traffic fence снимается, а повторный вызов безопасно возвращает тот же terminal result.

Основной путь

# 1. отдельный dev-бот + локальный процесс/tunnel
brt dev

# 2. из второго терминала — конфигурация именно dev-бота
printf '%s' "$DEV_EXTERNAL_API_KEY" | brt secret set EXTERNAL_API_KEY --dev

# 3. первый production deploy создаёт target и загружает текущий код
brt deploy --adk --name "Мой бот"

# 4. production-интеграция настраивается без --dev
printf '{"botToken":"%s"}' "$PROD_TELEGRAM_TOKEN" \
  | brt integrations install botruntime/telegram@1.1.3 --config-stdin
export PROD_WEBHOOK_ID='wh_replace_from_install_output'
brt integrations register "$PROD_WEBHOOK_ID"

# 5. обязательный второй deploy включает новое состояние Cloud в bundle
brt deploy --adk

# 6. следующая версия переключает ту же installation; новый install не нужен
brt integrations upgrade botruntime/telegram@1.2.0 --alias telegram
brt deploy --adk

install/register меняют интеграции и обновляют локальное production-отражение зависимостей, но не генерируют и не загружают bundle. Приёмочная проверка production начинается после второго deploy. В dev такое обновление с --dev замечает уже запущенный watcher и сам повторяет генерацию.

brt integrations upgrade <name@version> атомарно переключает существующую installation на точную SemVer-версию, сохраняя её alias, webhook, конфиг, статус и секреты. CLI выбирает ровно один effective alias и не вызывает install или register. Для production после успешного переключения также обязателен brt deploy --adk; в dev watcher подхватывает обновлённый snapshot. Флаг --wait пока завершается до сетевого запроса: Cloud ещё не публикует readiness runtime-host.

Если соединение оборвалось, Cloud вернул 5xx или успешный ответ нельзя строго проверить, результат repoint считается неизвестным. Сначала прочитайте текущий ref installation и только затем решайте, нужен ли симметричный rollback. CLI не меняет локальный snapshot и не предлагает создавать вторую installation.

Для Telegram используйте разные dev/prod Bot API токены: Telegram держит один активный webhook на токен, поэтому разделить только ботов внутри платформы недостаточно.

Гарантии безопасности

• каждый dev и deploy --adk сверяет точное authoritative-состояние target с Cloud до генерации и сборки;
• dev --check остаётся read-only gate подготовленного dev target: не создаёт target и не исправляет drift;
• настройки, секреты и интеграции dev/prod изолированы;
• значения для config set, secret set и конфигурации интеграции читаются из stdin или файла, а не из value-аргумента;
• секретные поля схемы интеграции запечатываются сервером; обычный config хранится как JSONB и не должен содержать секреты;
• удаление таблиц, колонок или смена их типов требуют отдельного --allow-destructive-table-changes; общий -y/--confirm эту защиту не обходит.

Дальше