DesignCorp Docs

Appearance

Telegram Agent Chat ​

Назначение ​

Чистый Telegram control plane для общения owner с DesignCorp agents без tmux.

Контур ​

  • Repo: /home/admin/workspace/telegram-agent-chat
  • Runtime: Node.js long polling
  • Telegram token: только локальный .env, не в git
  • State: /home/admin/workspace/telegram-agent-chat/data/state.json
  • Raw runtime logs: /home/admin/workspace/telegram-agent-chat/data/runs/
  • Telegram uploads: /home/admin/workspace/telegram-agent-chat/data/uploads/

Принцип ​

Telegram message -> shared event history -> codex exec --json/resume -> normalized agent answer -> Telegram reply

В этом проекте нет:

  • tmux;
  • чтения terminal pane;
  • screen scraping;
  • /tail как основного UX;
  • запуска двух long-polling сервисов на одном bot token.

Роли ​

Роли задаются в /home/admin/workspace/telegram-agent-chat/agents.json:

  • orchestrator
  • designer
  • frontend
  • qa
  • security
  • deploy
  • docs

Каждая роль имеет собственный persistent Codex thread id в data/state.json. Контекст хранится по Telegram scope: chat_id + message_thread_id. В каждой теме отдельно живут brief, jobs, events, runs и Codex threads.

Команды ​

  • /whoami — показать Telegram user id.
  • /chatid — показать chat id.
  • /status — состояние сервиса.
  • /agents — список ролей.
  • /brief или /brief <text> — показать или обновить общий brief.
  • /active — показать текущие agent runs.
  • /runs [count] — показать последние завершённые/ошибочные runs.
  • /events [count] или /trace [count] — показать последние события общего журнала.
  • /files [count] — показать последние файлы текущей темы.
  • /state — короткая сводка статуса, активных runs и открытых jobs.
  • /topic list — показать темы, созданные или известные bot state.
  • /topic create <name> — создать Telegram forum topic и завести отдельный scope.
  • /ask <role> <message> — запустить роль через codex exec --json.
  • @orchestrator <message> — короткий direct-chat.
  • designer: <message> — короткий direct-chat.
  • /panel <message> — спросить несколько ролей из PANEL_ROLES.
  • /assign <role> <task> — создать job.
  • /jobs — список открытых jobs.
  • /job <id> — детали job.
  • /run <id> — запустить job.
  • /threads — показать Codex thread ids.
  • /reset <role|all> — сбросить thread.

Observability ​

  • Каждый запуск сразу возвращает run id и статус running.
  • Пока Codex работает, bot отправляет typing и периодические progress-сообщения.
  • Активные запуски хранятся в data/state.json -> activeRuns.
  • После завершения запуск переносится в runs со статусом completed, failed или interrupted.
  • Если service перезапущен во время активного запуска, старый activeRun помечается как interrupted при старте.
  • Agent execution запускается в background promise, поэтому polling не блокируется: во время работы агента /active, /state, /events и новые сообщения продолжают обрабатываться.

Topic Scope ​

  • Scope key: chat_id:message_thread_id, для основного чата используется chat_id:main.
  • /brief, /assign, /jobs, /job, /run, /threads, /reset, /runs, /events, /files работают в текущей теме.
  • /active по умолчанию показывает активные runs текущей темы; /active all показывает все активные runs.
  • /topic create <name> требует у Telegram bot права can_manage_topics.

Uploads ​

  • Сообщения Telegram с photo или document сохраняются в data/uploads/<scope>/.
  • В state сохраняются только метаданные и локальный путь, Telegram bot token в state не пишется.
  • Если у изображения есть caption с direct command (@designer ..., frontend: ..., /ask ...), путь к файлу добавляется в prompt агента.
  • Текущие image-вложения и последние image-файлы темы при явном запросе (оцени, посмотри, скрин, изображение, выше) передаются в codex exec через --image.
  • Если изображение отправлено без текста, bot сохраняет файл и отвечает локальным путём; после этого можно дать задачу текстом в этой же теме.

Runbook ​

Локальные проверки:

bash
corepack pnpm run check
corepack pnpm run smoke:runtime

Ручной запуск:

bash
corepack pnpm start

Cutover с текущего Telegram bot:

bash
sudo -n install -m 0644 deploy/telegram-agent-chat.service /etc/systemd/system/telegram-agent-chat.service
sudo -n systemctl daemon-reload
sudo -n systemctl stop agent-chat-telegram.service
sudo -n systemctl enable --now telegram-agent-chat.service
sudo -n systemctl status telegram-agent-chat.service --no-pager -l

Rollback:

bash
sudo -n systemctl stop telegram-agent-chat.service
sudo -n systemctl start agent-chat-telegram.service

Безопасность ​

  • Agent execution доступен только после заполнения TELEGRAM_ALLOWED_USER_IDS и TELEGRAM_ALLOWED_CHAT_IDS.
  • Setup-команды /whoami, /chatid, /status, /help доступны до allowlist.
  • Bot не печатает секреты и не должен раскрывать env values.
  • sudo, deploy, nginx/systemd, git push/merge/rebase/tag требуют явного owner approval.
  • По умолчанию в template CODEX_SANDBOX=workspace-write; активный local runtime сейчас работает с CODEX_SANDBOX=danger-full-access по решению owner.
  • Даже при danger-full-access hard rules запрещают sudo, deploy, nginx/systemd, git push/merge/rebase/tag без явного owner approval в Telegram.

Текущий статус ​

  • MVP scaffold создан.
  • Runtime smoke через codex exec --json проходит.
  • Service включён: telegram-agent-chat.service.
  • Legacy service остановлен и отключён: agent-chat-telegram.service.
  • Bot подключается как @designcorp_orchestrator_bot.
  • Добавлены /active, /runs, /events//trace, /state и progress-сообщения для наблюдения за agent runs.