From 11bcf812e09badb56e0a9989817c5e75fca9c9c0 Mon Sep 17 00:00:00 2001 From: Michael Lam Date: Mon, 18 May 2026 16:34:16 -0700 Subject: [PATCH] docs(runtime): clarify queue adapter staging --- CHANGELOG.md | 4 +++ docs/rfcs/hermes-run-adapter-contract.md | 32 +++++++++++++++--------- tests/test_runtime_adapter_seam.py | 11 ++++++++ 3 files changed, 35 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed15eec371..02592b5c3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] +### Documentation + +- **PR #TBD** by @Michaelyklam (refs #1925) — Clarify the RuntimeAdapter Slice 3c state after #2544 shipped. The RFC now distinguishes shipped `/api/goal` routing through `RuntimeAdapter.update_goal(...)` from the still-staged `queue_message(...)` protocol method, and explicitly warns not to add a new server-side queue endpoint or queue scheduler merely for adapter symmetry while `/queue` remains browser-side queue/drain behavior. + ## [v0.51.91] — 2026-05-18 — Release BO (stage-384 — 5-PR full sweep batch — reasoning-replay history fix + archive-extract per-session inbox + fallback streaming warnings + sanitized custom-provider env hints + Slice 3c queue/goal adapter routing) ### Fixed diff --git a/docs/rfcs/hermes-run-adapter-contract.md b/docs/rfcs/hermes-run-adapter-contract.md index 1431a123fa..2a7031569c 100644 --- a/docs/rfcs/hermes-run-adapter-contract.md +++ b/docs/rfcs/hermes-run-adapter-contract.md @@ -52,7 +52,7 @@ The immediate goal is not to build a sidecar. The immediate goal is to define th browser contract, classify current runtime state, and gate the first reversible journal slice. -## Current Gate State — 2026-05-17 +## Current Gate State — 2026-05-18 Slice 1 is now past the first active validation gate: @@ -85,11 +85,19 @@ adapter-seam work: - #2487 shipped the Slice 3b approval/clarify gate, and #2496 shipped approval / clarify response routing through the adapter seam in v0.51.89. - #2509 shipped the Slice 3c queue/continue + goal gate in v0.51.90. - -The next gate is not the runner/sidecar yet. It is the Slice 3c implementation: -add the queue/goal adapter methods and route accepted legacy control paths -through them without moving goal evaluation, continuation scheduling, or -execution ownership out of the existing agent loop. +- #2544 shipped the first Slice 3c implementation in v0.51.91. The goal + route now uses `RuntimeAdapter.update_goal(...)` only when + `HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal` is enabled, while preserving the + legacy-direct response shape and leaving post-turn goal evaluation in the + existing agent loop. + +The next gate is still not the runner/sidecar by default. Slice 3c's goal route +is shipped, and `queue_message(...)` remains a staged protocol method. Queue / +continue routing needs an explicit follow-up contract because the legacy `/queue` +path is browser-side queue/drain behavior today; no new server-side queue endpoint +or queue scheduler should be added just for adapter symmetry. If maintainers want +queue/continue to move before Slice 4, that follow-up should specify the exact +legacy entry point, response shape, and ordering/idempotency contract first. ## Goals @@ -354,12 +362,12 @@ class RuntimeAdapter: ) -> ControlResult: ... ``` -`queue_message` is named for the legacy `/api/session/queue` payload: it -accepts follow-up chat text rather than arbitrary runtime input. The method name -does not require the HTTP route to change; it documents the adapter-level control -semantics that a later Slice 3c implementation should preserve. The method enters -the protocol before route wiring so queue/continue can land as a separate, small -control-routing follow-up instead of being coupled to goal routing. +`queue_message` is named for the legacy queued-message payload shape: it accepts +follow-up chat text rather than arbitrary runtime input. The method name does not +require a new HTTP route. Today `/queue` is primarily browser-side queue/drain +behavior; the adapter method enters the protocol so a later queue/continue slice +has a typed control surface, but route wiring remains deliberately staged until +the exact legacy entry point and ordering/idempotency contract are explicit. For `update_goal`, the `action` argument is the bounded adapter capability label. During the legacy-journal slice, the legacy goal parser still receives the full diff --git a/tests/test_runtime_adapter_seam.py b/tests/test_runtime_adapter_seam.py index 8c8ad1e5d1..ef1a795123 100644 --- a/tests/test_runtime_adapter_seam.py +++ b/tests/test_runtime_adapter_seam.py @@ -302,3 +302,14 @@ def test_chat_start_adapter_path_preserves_legacy_response_shape(): assert 'response.setdefault("run_id", result.run_id)' not in adapter_branch assert 'response.setdefault("status", result.status)' not in adapter_branch assert 'response.setdefault("active_controls", result.active_controls)' not in adapter_branch + + +def test_rfc_distinguishes_goal_routing_from_queue_route_staging(): + routes = importlib.import_module("api.routes") + rfc = (routes.Path(__file__).parent.parent / "docs" / "rfcs" / "hermes-run-adapter-contract.md").read_text(encoding="utf-8") + + assert "#2544 shipped the first Slice 3c implementation" in rfc + assert "route now uses `RuntimeAdapter.update_goal(...)`" in rfc + assert "`queue_message(...)` remains a staged protocol method" in rfc + assert "no new server-side queue endpoint" in rfc + assert "or queue scheduler should be added just for adapter symmetry" in rfc