sdlc-hub/openspec/changes/archive/2026-10-14-agent-self-update/proposal.md

Why

Мост в ежедневной работе с 13.10.2026, агент меняется часто: v2 → v3 → v4 за два дня. Каждое обновление — ручная процедура на виртуалке банка: положить agent.py в корень общей папки, остановить старый процесс, скопировать файл в ~/jira-agent-bundle, check, run. Хаб уже знает версию агента (agent_version в claim, предупреждение по min_agent_version), но доставлять код не умеет; падение агента никто не поднимает — он запущен в терминале.

Решения владельца 14.10.2026 (brainstorming):

• доставка через хаб (вариант A): явная публикация jira-hub agent publish, версия в ответе claim, файл — по GET /agent/release; работает и по HTTP, и через общую папку;
• перезапуск и откат — маленький постоянный запускатель run.py рядом с agent.py (вариант 2): подмена файла, пробный период, откат на прежнюю версию, перезапуск после падения;
• код в общую папку не кладётся: агент получает файл через API хаба, пишет и запускает его в каталоге run.py на виртуалке (~/jira-agent-bundle);
• хаб правится параллельно с web-app (#21), без пересечения требований спек;
• после этого change ручное обновление на виртуалке — одно последнее (v5 + run.py); дальше агент обновляется сам после публикации, которую делает Claude в чеклисте закрытия PR агента.

What Changes

• jira-hub:
  • команда jira-hub agent publish <agent.py>: версия из строки AGENT_VERSION = N, sha256, только вверх; файл и manifest.json в <данные>/release/ (права 0700); схема БД не меняется;
  • ответ POST /agent/claim — поле agent_release: {version, sha256} | null;
  • POST /agent/claim принимает update_state и launcher_version; хаб держит последние значения в памяти;
  • маршрут GET /agent/release (агентский токен) → {version, sha256, content}; 404 no_release;
  • GET /agent и MCP agent_status: опубликованная версия, состояние обновления, версия запускателя, подсказка «агент запущен без run.py».
• jira-agent (версия 5):
  • новый файл run.py (Python 3.9, stdlib): дочерний agent.py run, код 75 — подмена файла, пробный период до первого успешного claim (10 мин), откат, перезапуск после падения с паузой 5…300 с, своя блокировка run.py.lock;
  • agent.py: в паузе между командами (ответ claim без команды) видит agent_release новее себя, скачивает, проверяет sha256, компиляцию и версию в файле, запускает agent.py.new selftest, выходит с кодом 75; отвергнутую версию не повторяет; без запускателя только пишет в лог раз в час; выключатель auto_update в agent.json;
  • новая команда agent.py selftest; update.json — состояние обновления рядом с agent.py;
  • README: запуск через run.py, последнее ручное обновление, публикация.

Capabilities

New Capabilities

Modified Capabilities

• agent: состав (запускатель, auto_update, selftest), доставка и запуск; новые требования — самообновление и запускатель.
• hub-api: маршруты агента (agent_release, update_state, GET /agent/release); новое требование — публикация версии агента.
• mcp: agent_status показывает публикацию и состояние обновления.

Non-Goals

• подпись файла ключом (целостность — sha256; доверие — как сейчас, см. design R-9);
• снятие публикации и откат «вниз» по команде — откат делается публикацией старого кода с новой версией;
• самообновление run.py — обновляется вручную, меняется редко;
• изменение схемы БД хаба и min_agent_version (не поднимается);
• показ публикации в веб-приложении (#21) — после его merge, отдельно.

Impact

• jira-hub: release.py (новый), cli.py, api.py (h_claim, маршрут, h_agent_get), queue.agent_view не меняется, mcp_server.fmt_agent, README, ARCHITECTURE.md, CLAUDE.md. Пересечение с веткой feat/21-web-app — только api.py (разные места); дельта hub-api web-app трогает «Процесс и доступ», эта — «Маршруты агента».
• jira-agent: src/agent.py (v5), src/run.py (новый), тесты, README, ARCHITECTURE.md, CLAUDE.md.
• Выкатка: хаб — pull + kickstart; агент — последнее ручное обновление (v5 + run.py), затем живая проверка публикацией v6, сломанной v7 (откат) и v8.