feat(runtime): route goal through adapter seam

[Michaelyklam]

Thinking Path

• RFC: Make WebUI a thin observability/control client over Hermes Agent runtime #1925 has shipped the journal/replay baseline, default-off RuntimeAdapter seam, cancel routing, and approval/clarify routing.
• PR docs(runtime): define queue goal control gate #2509 / v0.51.90 accepted the Slice 3c queue/continue + goal gate before implementation.
• The safe next code slice is still a protocol translator: add the queue/goal adapter methods and route the accepted legacy goal control path through RuntimeAdapter.update_goal(...) when HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal is enabled.
• Queue remains explicitly scoped to the existing browser-side /queue drain into /api/chat/start; this PR does not invent a backend queue or continuation scheduler.

What Changed

• Added queue_message(...) and update_goal(...) to the RuntimeAdapter protocol and LegacyJournalRuntimeAdapter.
• Added delegate wiring for queue and goal controls without adding new long-lived queues, callback registries, cached agents, runner processes, or sidecars.
• Routed /api/goal through LegacyJournalRuntimeAdapter.update_goal(...) only under the default-off legacy-journal adapter flag.
• Preserved the public /api/goal response shape by returning the legacy goal payload rather than adapter-only fields.
• Updated the RFC: Make WebUI a thin observability/control client over Hermes Agent runtime #1925 RFC status and CHANGELOG.md for the Slice 3c implementation.
• Replaced the docs-only guard test from docs(runtime): define queue goal control gate #2509 with implementation tests for the new adapter methods and goal route.

Why It Matters

This advances #1925’s control-plane migration without jumping to runner/sidecar execution ownership. Goal controls now cross the same adapter seam as cancel, approval, and clarify under the opt-in flag, while post-turn goal evaluation and continuation remain owned by the existing agent conversation loop until the later runner/sidecar slice.

Verification

• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_runtime_adapter_seam.py -q → 15 passed
• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_runtime_adapter_seam.py tests/test_goal_command_webui.py tests/test_issue_1932_goal_hook_unrelated_turns.py tests/test_stage326_pending_goal_continuation_race.py tests/test_1062_busy_input_modes.py tests/test_cmd_idle_fallback.py -q → 83 passed
• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/ -q → 5956 passed, 6 skipped, 3 xpassed, 8 subtests passed in 92.72s
• /home/michael/.hermes/hermes-agent/venv/bin/python -m py_compile api/runtime_adapter.py api/routes.py tests/test_runtime_adapter_seam.py tests/test_goal_command_webui.py
• git diff --check

Risks / Follow-ups

• /queue remains browser-side queued input that drains through the existing chat-start path; this PR adds the adapter delegate seam but does not create a backend queue API or durable scheduler.
• update_goal(...) controls goal state mutations only. Post-turn goal evaluation and continuation still live in the existing agent loop, per the docs(runtime): define queue goal control gate #2509 gate.
• No runner/sidecar, no execution-survives-WebUI-restart behavior, and no durable pending queue/goal scheduler are introduced here.

Model Used

OpenAI Codex GPT-5.5 via Hermes Agent, with terminal/file tools for code changes, tests, git, and GitHub PR workflow.

Refs #1925

[Michaelyklam]

CI is green on the amended Slice 3c implementation head b23fb6c.

Verification recap:

• GitHub Actions: test (3.11), test (3.12), and test (3.13) all passed.
• Local focused queue/goal/runtime-adapter suite: 83 passed.
• Local full suite: 5956 passed, 6 skipped, 3 xpassed, 8 subtests passed.
• py_compile and git diff --check passed.

Scope remains intentionally narrow: adapter delegate methods plus /api/goal flag-gated routing only. No backend queue scheduler, goal scheduler, runner/sidecar ownership move, or public response-shape expansion.

[nesquena-hermes]

Reviewing head b23fb6c: api/runtime_adapter.py diff, api/routes.py:7798-7910 for the goal route, the two new tests, and the RFC update.

The slice does what it advertises and the response‑shape preservation test at tests/test_goal_command_webui.py:233-273 is the right gate ("no run_id, no active_controls leaking into the public body"). The agent‑side contract is unchanged because the route never calls into the agent for goal updates — it's all goal_command_payload(...) under api/goals.py:421. So the layering is clean: WebUI‑only seam, no agent‑repo coupling introduced.

A few observations worth weighing before merge.

1. Under the flag, the adapter is a structural no‑op — accepted / safe_message are computed and discarded

The route at api/routes.py:7895-7902 unwraps the ControlResult by reading control_result.payload:

if runtime_adapter_enabled():
    adapter = LegacyJournalRuntimeAdapter(goal_delegate=_legacy_goal_update)
    control_result = adapter.update_goal(
        s.session_id,
        _runtime_adapter_goal_action(goal_args),
        goal_args,
    )
    payload = dict(control_result.payload)
else:
    payload = _legacy_goal_update(s.session_id, _runtime_adapter_goal_action(goal_args), goal_args)

Then payload.get("ok", True) controls the HTTP status. The accepted: bool / safe_message: str | None fields that _active_control_result(value) populates at runtime_adapter.py:118-126 are computed but never read by the consumer. That's consistent with the Slice 3c "preserve response shape" goal, but it does mean the seam isn't actually mediating anything under the flag — it's a passthrough that happens to box and unbox a dict.

That's a real cost: anyone reading this in six months will assume ControlResult.accepted carries semantic weight here. Suggest a one‑line comment at routes.py:7895 making explicit that the dict pass‑through is intentional and accepted isn't read, e.g.:

# Slice 3c: the adapter is a structural seam; we deliberately use the
# legacy payload (not control_result.accepted / .safe_message) so the
# public /goal response shape is identical with and without the flag.

2. _runtime_adapter_goal_action(goal_args) is computed twice and then discarded

The action label is passed into both the adapter call and the legacy branch:

adapter.update_goal(s.session_id, _runtime_adapter_goal_action(goal_args), goal_args)
# and
payload = _legacy_goal_update(s.session_id, _runtime_adapter_goal_action(goal_args), goal_args)

The delegate signature is _legacy_goal_update(session_id, _action, text) and the action parameter is prefixed _ because it's deliberately ignored — goal_command_payload(session_id, text, ...) parses the action out of text itself at goals.py:447-499. So the action mapping is currently a typed contract for a future runner but not exercised anywhere. That's fine; just consider whether the RFC update at docs/rfcs/hermes-run-adapter-contract.md should add a note clarifying that Slice 3c maps actions for the protocol surface only and that legacy action parsing still wins.

A small bug shadow here: _runtime_adapter_goal_action("set foo") returns "set", which is correct, but _runtime_adapter_goal_action("status") returns "status" — both rely on text being the full goal_args to do the real work. If a future slice routes through _action instead of text, "set foo" loses the "foo" body. Worth a test case asserting that swap is not yet attempted.

3. queue_message is added to the protocol + adapter + tests but has no caller in this PR

Routes diff shows only the goal route is wired. grep queue_message api/ returns only api/runtime_adapter.py. That's OK if the next PR adds /api/chat/queue or similar, but a dangling protocol method is more confusing to next contributors than a TODO comment. Two cheap options: (a) drop queue_message from this PR and add it in the slice that uses it; (b) keep it and add a one‑sentence note in the RFC ("queue_message added to the contract here; routing PR follows in Slice 3c.2") so the staging is explicit.

4. Minor — _active_control_result(value) semantics

# api/runtime_adapter.py:118-126
if isinstance(value, dict):
    accepted = bool(value.get("ok", True))
    return ControlResult(
        accepted=accepted,
        status=str(value.get("status") or value.get("action") or ("accepted" if accepted else "not-active")),
        safe_message=value.get("message") if not accepted else None,
        payload=dict(value),
    )

Two small things:

• payload=dict(value) is a shallow copy. If a delegate returns a dict containing nested mutable state (e.g. lists of pending controls), a downstream consumer could mutate the legacy state object. Today goal_command_payload returns scalars + small dicts only, so it's safe, but a copy.deepcopy or an explicit "payload is read‑only" docstring would future‑proof this once a delegate returns nested structures.
• The status fallback chain value.get("status") or value.get("action") collapses two different concepts (HTTP‑ish status vs goal action verb). For the goal payload that's deliberate (you want "status"/"pause"/"set" to surface as status), but the same shape applied to a cancel or approval delegate would conflate them. Consider naming this _goal_control_result if it stays goal‑specific, or documenting the conflation.

What looks great

• The _runtime_adapter_goal_action whitelist (set / pause / resume / clear / status / edit) matches goal_command_payload's real action space at goals.py:448-510 — no stray verbs.
• Test at test_runtime_adapter_seam.py:115-135 exercises both delegates and asserts call shape, which is exactly what the seam needs.
• RFC update accurately marks Slice 3c shipped in v0.51.90 via docs(runtime): define queue goal control gate #2509 and frames this PR as the implementation of the previously accepted gate.

Test plan suggestions beyond what's there: (a) flag on + args="set foo" to confirm _runtime_adapter_goal_action returns "set" but the legacy parser sees the full "set foo" and creates the goal; (b) flag on + delegate returning {"ok": False, "error": "agent_running"} produces HTTP 409 (the existing 409 branch at routes.py:7906 should still fire because we read payload.get("ok"), not control_result.accepted).

[Michaelyklam]

Thanks — I pushed follow-up commit 6a68bab1 to address the review notes before merge.

What changed:

• Added an explicit route comment that the legacy-journal /api/goal path intentionally passes through the legacy payload instead of deriving public HTTP behavior from ControlResult.accepted / .safe_message.
• Computes _runtime_adapter_goal_action(goal_args) once and reuses the bounded label for both branches.
• Clarified in the RFC that queue_message(...) is staged into the protocol before route wiring, and that update_goal(...) keeps the full legacy text authoritative for set <goal text> semantics.
• Documented _active_control_result(...) status semantics so the status/action fallback is visibly an adapter summary, not public-route behavior.
• Added the two suggested regressions:
  • adapter flag + args="set foo" preserves the full set foo text through the legacy goal parser / kickoff payload;
  • adapter flag + active stream returns the legacy agent_running payload as HTTP 409 by reading payload["ok"], not ControlResult.accepted.

Verification:

• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_runtime_adapter_seam.py tests/test_goal_command_webui.py -q → 28 passed
• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_runtime_adapter_seam.py tests/test_goal_command_webui.py tests/test_issue_1932_goal_hook_unrelated_turns.py tests/test_stage326_pending_goal_continuation_race.py tests/test_1062_busy_input_modes.py tests/test_cmd_idle_fallback.py -q → 85 passed
• py_compile on touched Python files/tests → passed
• git diff --check → passed

No scope expansion: still no backend queue scheduler, goal scheduler, runner/sidecar ownership move, new runtime-surrogate state, or public response-shape expansion.

[Michaelyklam]

Follow-up CI is green on head 6a68bab1.

• test (3.11) passed
• test (3.12) passed
• test (3.13) passed
• mergeable: MERGEABLE

So the review-feedback follow-up is ready for maintainer review/release batching.