| 1 | # ADR 013: Localhost status surface (AgentNotesStatus) |
| 2 | |
| 3 | **Статус:** Accepted · Implemented |
| 4 | **Дата:** 2026-05-16 |
| 5 | **Обновлено:** 2026-05-16 — фазы 1–2: HTTP loopback, HTML/JSON, ring buffer, `/hot-preview`, `--status-only`. |
| 6 | |
| 7 | **Канонический текст (KB):** `knowledge/adr/013-agent-notes-mcp-local-settings-toml-v1.md` (секция status). |
| 8 | |
| 9 | ## Связанные ADR |
| 10 | |
| 11 | | ADR | Роль | |
| 12 | |-----|------| |
| 13 | | [008](008-workspace-scope-map-resolution.md) | резолв `active_scope` для `/hot-preview` | |
| 14 | | [014](014-agent-notes-local-settings-toml-v1.md) | секция **`[status]`** в TOML (`--config`, MCP 2.0) | |
| 15 | |
| 16 | ### Вне scope |
| 17 | |
| 18 | Remote operator / PWA / Operator Gateway (Cascade IDE) — другие ADR и продукты. |
| 19 | |
| 20 | ## Резюме |
| 21 | |
| 22 | - Опциональный **HTTP на loopback** в процессе `agent-notes-mcp` для отладки без лишних MCP round-trip. |
| 23 | - Endpoints: `/`, `/status.json`, `/health`, `/hot-preview` (см. §2.1). |
| 24 | - По умолчанию **выключено** — `[status].enabled` в TOML из **`--config`** ([014](014-agent-notes-local-settings-toml-v1.md)). |
| 25 | - `bind` в v1 — только `127.0.0.1`. |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## 1. Контекст |
| 30 | |
| 31 | **agent-notes-mcp** — stdio MCP. При настройке канона неочевидно, что реально резолвит **этот** процесс (canon, scope, `memory_health`), особенно при нескольких workspace и legacy env. |
| 32 | |
| 33 | Ответы только через MCP-tools из чата — лишние round-trip при отладке. |
| 34 | |
| 35 | --- |
| 36 | |
| 37 | ## 2. Решение |
| 38 | |
| 39 | ### 2.1. AgentNotesStatus |
| 40 | |
| 41 | Опциональный **HTTP на loopback** (`127.0.0.1`) в том же процессе `agent-notes-mcp`: |
| 42 | |
| 43 | | Endpoint | Назначение | |
| 44 | |----------|------------| |
| 45 | | `GET /` | HTML-сводка | |
| 46 | | `GET /status.json` | JSON для скриптов | |
| 47 | | `GET /health` | `200 OK` | |
| 48 | | `GET /hot-preview` | JSON: размеры hot-секций (`?workspace_path=` или `[status.preview].workspace`) | |
| 49 | |
| 50 | По умолчанию **выключено** — см. **`[status].enabled`** в TOML из **`--config`** ([014](014-agent-notes-local-settings-toml-v1.md)). |
| 51 | |
| 52 | ### 2.2. Конфигурация status |
| 53 | |
| 54 | **Не** отдельный файл и **не** env. Секция в том же TOML, путь к которому задан в `mcp.json` как у DBHub: |
| 55 | |
| 56 | ```toml |
| 57 | [status] |
| 58 | enabled = true |
| 59 | port = 17341 |
| 60 | bind = "127.0.0.1" |
| 61 | |
| 62 | [status.preview] |
| 63 | # workspace = "..." # для превью scope на странице (KB ADR 013) |
| 64 | ``` |
| 65 | |
| 66 | `bind` в v1: только `127.0.0.1`; иное — warning и принудительно loopback. |
| 67 | |
| 68 | **Runtime** (не конфиг): `{workspace}/.cascade-ide/agent-notes-status.runtime.json` — `pid`, `port`, `url`, `config_source`. |
| 69 | |
| 70 | ### 2.3. Содержимое страницы (read-only) |
| 71 | |
| 72 | | Блок | Источник | |
| 73 | |------|----------| |
| 74 | | Версия MCP, PID, uptime | процесс | |
| 75 | | `config_path` | абсолютный путь из **`--config`** ([014](014-agent-notes-local-settings-toml-v1.md)) | |
| 76 | | Primary knowledge root / notes path | TOML `[knowledge]` + legacy `AGENT_NOTES_*` («present / overridden») | |
| 77 | | Scope, `memory_health` | существующий код; `?workspace_path=` или `[status.preview].workspace` | |
| 78 | | Карта workspace | метаданные (N правил), без полного дампа путей в HTML | |
| 79 | | Tools | `ToolCatalog` | |
| 80 | | Read-only knowledge roots | `[[knowledge.read_only]]` настроен / нет ([012] в KB) | |
| 81 | |
| 82 | **Не входит:** запись в KB/hot через HTTP; прокси всех tools; LAN/WAN. |
| 83 | |
| 84 | ### 2.4. Безопасность |
| 85 | |
| 86 | Loopback only; без `personal/`, hot ниже `public-cut`, секретов; `?verbose=1` для полных путей в JSON. |
| 87 | |
| 88 | ### 2.5. Несколько процессов MCP |
| 89 | |
| 90 | У каждого workspace — свой TOML (`status.port`) и свой `agent-notes-status.runtime.json`. Страница описывает **текущий** процесс. |
| 91 | |
| 92 | --- |
| 93 | |
| 94 | ## 3. Реализация |
| 95 | |
| 96 | | Фаза | Содержание | |
| 97 | |------|------------| |
| 98 | | 0 | ADR + README | |
| 99 | | 1 | Зависит от [014](014-agent-notes-local-settings-toml-v1.md) фаза 1 (Tomlyn); Kestrel minimal API; `[status]` | |
| 100 | | 2 | Ring buffer последних tool calls (в `status.json` + HTML); `GET /hot-preview`; CLI `--status-only` (только HTTP, без stdio MCP) | |
| 101 | |
| 102 | --- |
| 103 | |
| 104 | ## 4. Альтернативы |
| 105 | |
| 106 | | Вариант | Почему нет | |
| 107 | |---------|------------| |
| 108 | | Только tool `debug_status` | нет браузера в один клик | |
| 109 | | Env `AGENT_NOTES_STATUS_*` | дублирует TOML [014] | |
| 110 | | IDE / PWA status | другой продукт | |
| 111 | |
| 112 | --- |
| 113 | |
| 114 | ## 5. Критерии принятия |
| 115 | |
| 116 | - `[status].enabled = true` + `--config` → браузер: версия MCP, primary KB root, scope, `memory_health`, `config_path`. |
| 117 | - `enabled = false` → порт не слушается. |
| 118 | - Smoke-тесты loopback. |
| 119 | |
| 120 | --- |
| 121 | |
| 122 | ## 6. Открытые вопросы |
| 123 | |
| 124 | 1. HTML: embedded resource vs генерация в коде. |
| 125 | 2. Порядок с [014]: status HTTP сразу после Tomlyn loader или отдельным PR. |
| 126 | |