Files
crank/docs/development/rmcp106-tools-adapter.md
T
bsodfather 1c256e6c75
CI / Rust Checks (pull_request) Failing after 40s
CI / Rust Feature Validation (pull_request) Skipped
CI / UI Checks (pull_request) Successful in 12s
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Failing after 2s
CI / Deploy (pull_request) Skipped
Add isolated rmcp Tools adapter prototype
2026-11-06 07:56:21 +00:00

15 KiB
Raw Permalink Blame History

Изолированный rmcp Tools adapter (#106)

Граница кандидата

База: e4953abcd2f5320e1729249221ce9472a175c5f1 (принятый main 4.5). W: /home/codex/code/crank-worktrees/rmcp106-tools-adapter. Основание: #106, comment 2277 и отдельное разрешение владельца 05.11.2026 на этап 1. Это работающий изолированный опыт, не завершённая миграция и не production endpoint. Независимая QA и решение TL следуют после DEV-проверок; документ не заменяет их.

app/rmcp_http.rs создаёт один настоящий StreamableHttpService и LocalSessionManager на один явно заданный Agent route. Это test-only router, запускаемый wire-набором через настоящий TCP loopback; в build_app_inner он не подключён. Отдельный manager на Agent делает session/route ownership явным без новой session database. Все проверки доступа (POST/GET/DELETE), scopes, rate admission, Origin, envelope/revision/session carrier используют существующие Crank helpers. SDK получает только проверенный snapshot текущего запроса через HTTP Parts.extensions, не credential из initialize.

app/rmcp_tools.rs реализует официальный ServerHandler, но делегирует list/call существующему handle_tools_command: опубликованный каталог, runtime, REST mapping, security и error contracts не заменяются. Перезапись публикации и фоновые бизнес-workflows не добавлены. Новый handler рекламирует только Tools и две поддерживаемые revisions.

SDK закреплён как rmcp = "=3.7.0", HTTP server feature включён, зависимость только dev/test. Cargo.lock сохраняется вместе с кандидатом; фактический transitive rmcp-macros — 3.9.0 по semver SDK. Автоматического обновления rmcp нет. Существующие package versions не повышались; lock содержит новые SDK-зависимости и переразрешённые dependency edges.

Исполняемые результаты

Команды выполняются в W с CARGO_BUILD_JOBS=2 CARGO_INCREMENTAL=0 SQLX_OFFLINE=true, HERMES_KANBAN_TASK=t_fdcc7df8, HERMES_KANBAN_BOARD=crank.

  • cargo test --locked -p crank-community-mcp --lib rmcp_ -- --nocapture --test-threads=1: exit 0, 20 passed, 0 ignored; 15 wire-тестов и 5 прежних direct-handler/manager проверок. Финальный тестовый прогон — 56.07 s, без полной workspace suite.
  • cargo test --locked -p crank-community-mcp --lib app::lifecycle -- --test-threads=1: exit 0, 7 passed, 0 ignored. Подтверждает существующие progress queue=8, token bound=128, cancellation table=256 и full-table/cleanup семантику. Это existing GREEN, не новый transport benchmark.
  • Wire positive control: legacy initialize/initialized/session и modern discover/stateless; dynamic list после публикации Agent v2 без reinitialize; реальные calls с проверяемым output и outbound counter. Modern single response — JSON; progress — SSE в обеих revisions.
  • Реальная проверка invalid/revoked/expired/scope-changed credentials после initialize, чужого route, Origin, неверной revision/name, конфликтующего modern session carrier и body overflow. Rejected calls не достигают upstream. Два валидных ключа могут использовать одну session, без credential pinning.
  • Progress отражает только три реально пройденные фазы (tool_resolved, authorization_resolved, execution_dispatched), token возвращается клиенту. Tool input-validation error остаётся isError, не JSON-RPC protocol error.
  • Cancel проверен до SDK по session + platform_api_key_id + typed requestId: чужой ключ/другая session не отменяют оригинал, одинаковые ids двух sessions независимы. Своё уведомление прекращает pending execution; modern disconnect прекращает future и возвращает stream permit. Эти факты не доказывают отсутствие внешнего бизнес-эффекта; повторного dispatch нет.
  • Live SDK manager допускает GET reconnect и последующий call. Новый manager со старым SDK id получает 404. Отдельно существующий PostgreSQL session store переживает пересоздание, его запись не удаляется SDK-опытом, но SDK не может обслужить такой durable id.
  • Небольшой admission smoke: удержанные 16 stream permits дают 429 до dispatch; освобождение восстанавливает call. QA дополнительно выявила обход при legacy disconnect: response body освобождал permit, пока SDK execution продолжался. Correction F1 делит один permit между body и request-local HTTP Parts SDK; слот освобождается только после завершения обеих жизней. Owned cancel проходит до admission, поэтому доступен и при заполненном бюджете. Регрессия использует реальные slow upstream calls с закрытием response, а не ручной захват semaphore. Настроенный существующий rate limiter даёт 429 без outbound. Request body ограничен прежним Axum default 2 MiB; ceilings не увеличены.
  • Correlation oracle сначала реально упал (exit 101): сервер подменял x-request-id сгенерированным UUID. После подключения существующего request-context middleware два конкурентных запроса сохраняют каждый свой id/output, тест GREEN. Это behavioral RED, не compile/setup failure. Для первоначального Tools positive control ранний behavioral RED не записан; последующие успешные проверки не выдаются за исторический RED.

Correction F1 после первой независимой QA: cargo test --locked -p crank-community-mcp --lib rmcp_http_ -- --nocapture --test-threads=1 — exit 0, 16 passed, 0 ignored, 50.94 s (отдельно 2m05s пересборки). Включены legacy disconnect/admission regression, восстановление всех 16 permits после owned cancel и новый реальный call с output/counter; также owned/foreign cancel, reconnect, modern disconnect и обычные list/call. Исходный behavioral RED QA (17 продолжающихся executions при 16 свободных slots) переиспользован, не подменён setup failure. Beam t_c21c9876 усилил этот же oracle; DEV проверил cleanup до assertions и исполнил итоговый файл. Повторные affected clippy и все перечисленные cheap gates — exit 0. Неизменённые 5 direct/manager и 7 lifecycle tests переиспользованы; нового full suite нет.

Исходные native logs и обновлённый SHA-256 manifest точной дельты приложены к Kanban handoff. Первоначальные setup/compile ошибки и исправленная тестовая ошибка с добавлением второго Authorization header не считаются behavioral RED.

Дешёвые gates финального кандидата: cargo clippy --locked -p crank-community-mcp -p crank-test-support --all-targets -- -D warnings, cargo fmt --all -- --check, git diff --check, bash -n scripts/ci-story-checks.sh, scripts/check-rust-code-health.sh, scripts/check-rust-boundaries.sh (включая config/migration/metrics/execution boundaries), явный Community-scope scan всех 11 изменённых/новых Rust files — exit 0. Clippy findings исправлены без suppressions. Labels test fixture передаются явно, без чтения environment вне crank-config. Story CI получил тот же непустой rmcp_ selector; остальные required selectors не удалены. Full workspace, нагрузочная кампания и UI не запускались: production/UI/runtime execution logic не менялись.

Конкретные несовместимости — не включать опыт в production

  1. Хранение сессий — не drop-in. TransportSessionStore хранит Crank-generated id, revision, initialized, elicitation flag, route и TTL; SDK SessionStore требует SDK-generated id и полные InitializeRequestParams (clientInfo/capabilities). Их нельзя без потерь восстановить из существующего DTO. LocalSessionManager умеет restore, но это не совместимость с Crank store: runtime oracle выше отдельно показывает live reconnect, потерю session новым manager и сохранность Crank PostgreSQL state. Last-Event-ID replay и восстановление in-flight execution не доказаны.
  2. Legacy JSON-only — несовместимость. Реальный Accept: application/json получает 406 у SDK legacy session path, тогда как modern simple call возвращает JSON. json_response=true не исправляет legacy mode. Не скрывать это преобразующим transport framework без отдельного решения.
  3. Legacy cancelled terminal frame — несовместимость. Владение отменой и остановка future работают. Однако при завершении handler с ошибкой SDK пишет request cancelled JSON-RPC error frame, а действующий Crank lifecycle заканчивает отменённый stream без terminal frame. Это явно asserted gap, не объявленная wire parity. Бесконечно pending handler ради подавления frame не используется: он удерживал бы execution/память.
  4. Budgets SDK требуют дальнейшего решения. Сохранены Crank limits и bounded queue перед forwarding; SDK channel capacity явно 16, EventStore не включён. SDK session map, request-router/cache и completed-cache TTL (60 s), idle keepalive (300 s) не дают автоматически прежний durable TTL 24 h или доказанный общий memory budget. Smoke выше не является long-run/slow-reader/load qualification. Await SDK notification delivery также требует проверки backpressure до общего включения.

Минимальные варианты для TL после независимой QA: сохранить Crank endpoint/session/lifecycle и применять SDK на request-scoped dispatch/model seam (вариант ARC), либо отдельно согласовать тонкую persistence mapping и точную transport parity перед #107. Не заменять PostgreSQL in-memory хранилищем, не ослаблять JSON/cancel contract и не строить новый общий framework молча. Текущий опыт доказывает работоспособность Tools, но не даёт GO на замену transport.

Остальные MCP-функции и ближайший потребитель

  • Resources/read/list/templates, Prompts/get/list, completion и composition не перенесены; их существующие shared services остаются будущими границами SDK handlers.
  • Catalog change notifications, subscriptions/listen, resume/replay и logging policy не подключены. Наличие SDK traits не означает parity; эти capabilities не рекламируются новым handler.
  • Background/adaptive Tasks, input continuation/elicitation, approval flows и Tasks extension этим router не реализованы. ContinuationSupport=false — явная граница опыта; сохранённый 4.3–4.5 task state/runtime не меняется. Подтверждён только synchronous shared Tools path.
  • Ближайший реальный потребитель — #107: build_app_inner и действующие endpoint/era adapters могли бы подключить SDK на проверенной typed-command границе после решения по перечисленным gaps. #107/#108/4.7 не запущены и требуют отдельного разрешения. Production NO_GO, blockers3.3/P4/auth3.20 остаются.

Передача и сохранность

Переиспользованы вклады Ornith t_1597bde6/t_de107aae (частичный Tools handler), Beam t_c5472eeb (direct negative tests), Beam t_1a3e54ff (два manager tests), Ornith t_c5611492 (частичная acceptance-plan правка), решение ARC t_e76984d9. HTTP поручение t_bf7332df осталось superseded partial, не готовой реализацией. Неделимую admission/Parts/cancel/HTTP интеграцию и wire oracle завершил DEV: повторное поручение с запретом integration paths уже приводило к deadlock.

Общий acceptance plan содержит ограниченный canonical amendment FR-25/FR-26/AR9 по live #34: business reconciliation отменена, не PASS; input/unknown safety сохранены. Исторические архивы PRD/epics не force-added, R WIP не перенесён. План rmcp остаётся планом этапов 2/3.

Новые loopback servers принадлежат RAII guards и abort при выходе теста; SDK cancellation token связан с lifetime router. Test PostgreSQL получает disposable/task/board labels и удаляется существующим atexit cleanup. Пример одного из проверенных прогонов: контейнер 9737b010c3dd (task t_fdcc7df8, board crank, disposable=true). Чужие контейнеры не затрагиваются. app.rs.orig/app.rs.rej сохранены как прежний WIP, не входят в delivery manifest.