feat(runtime): add default-off RuntimeAdapter seam

[Michaelyklam]

Thinking Path

• RFC: Make WebUI a thin observability/control client over Hermes Agent runtime #1925 has now shipped the Slice 1 run-journal/replay layer and PR docs: define runtime adapter seam contract #2416 merged the Slice 2 seam contract.
• The accepted next step is a narrow, reversible RuntimeAdapter seam over the still-legacy journaled path — not a runner, sidecar, control migration, or execution-ownership move.
• The highest-risk failure mode is recreating STREAMS / CANCEL_FLAGS / cached AIAgent / approval/clarify queues under new names, so this PR keeps the adapter as a protocol translator with injected legacy delegates.
• The default WebUI path remains legacy-direct; the new path is opt-in with HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal.

What Changed

• Added api/runtime_adapter.py with:
  • RuntimeAdapter protocol
  • StartRunRequest, RunStartResult, RunEventStream, RunStatus, and ControlResult payload classes
  • runtime_adapter_mode() / runtime_adapter_enabled() defaulting safely to legacy-direct
  • LegacyJournalRuntimeAdapter facade over the existing legacy streaming path and run journal
• Routed /api/chat/start through the adapter only when HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal; otherwise it uses the exact existing direct _start_chat_stream_for_session(...) path.
• Added regression coverage for the interface, feature-flag default/revert behavior, delegated start/control calls, journal-backed observation/status, and route selection.
• Added an Unreleased changelog entry.

Refs #1925.

Why It Matters

This is the first code seam after the accepted Slice 2 contract. It gives the WebUI a concrete adapter boundary to test and review while preserving the current execution backend and avoiding a parallel runtime. Future slices can migrate controls or runner ownership behind this boundary, but this PR deliberately does not move those responsibilities yet.

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
5 passed in 1.62s

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_run_journal.py tests/test_run_journal_routes.py tests/test_turn_journal.py tests/test_stale_stream_pending_recovery.py -q
33 passed in 1.93s

/home/michael/.hermes/hermes-agent/venv/bin/python -m py_compile api/runtime_adapter.py api/routes.py tests/test_runtime_adapter_seam.py
git diff --check
passed

env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/ -q
5804 passed, 6 skipped, 3 xpassed, 8 subtests passed in 90.85s

Risks / Follow-ups

• The adapter flag is intentionally default-off. Review should focus on the seam shape before any default behavior changes.
• cancel_run, respond_approval, and respond_clarify are present as delegated legacy controls only; their ownership migration remains deferred to later control-specific slices.
• This does not make active execution survive a WebUI process restart. The runner/sidecar gate remains deferred.
• Exact module/class naming can still be adjusted if maintainers prefer a different package layout.

Model Used

OpenAI Codex / GPT-5.5 via Hermes Agent, with shell, file edit, GitHub CLI, and local pytest verification.

[Michaelyklam]

I checked this against the current #1925 map and the merged #2416 Slice 2 seam contract.

LGTM for the first code seam:

• Scope stays default-off: legacy-direct remains the normal path, and the adapter route only activates under HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal.
• LegacyJournalRuntimeAdapter is a protocol-translator facade over the existing start path + run journal; it does not introduce a runner/sidecar, new stream queues, cached agents, cancellation registries, approval queues, or clarify queues under new names.
• Controls are represented in the interface but still delegated to legacy handlers, which preserves the RFC: Make WebUI a thin observability/control client over Hermes Agent runtime #1925 guardrail that control migration is a later slice.
• The route-level change is narrow: /api/chat/start constructs a StartRunRequest and unwraps the adapter result back into the existing response shape, so the feature flag is the revert path.
• Tests cover the interface, safe default/invalid-mode fallback, delegated start/control behavior, journal observation/status, and the route selection seam.

Verification from an isolated PR worktree:

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_run_journal.py tests/test_run_journal_routes.py tests/test_turn_journal.py tests/test_stale_stream_pending_recovery.py -q
33 passed in 1.78s

git diff --check origin/master...HEAD
clean

No #1925 blocker from me. I would keep the next slice after this just as narrow: either adapter-backed observation/status wiring or one control-specific migration, not runner/sidecar execution ownership yet.

[nesquena-hermes]

@nesquena Ready for independent review when you have a moment. CI is green; staging this for the next batch release once approved.

[nesquena]

Review — end-to-end ✅ (clean APPROVE, no fix pushed)

What this ships

First concrete Slice 2 implementation of the RuntimeAdapter seam, immediately following the RFC contract merged in PR #2416.

• api/runtime_adapter.py (+223 new): RuntimeAdapter protocol + 5 frozen dataclass payload types + 2 mode helpers (runtime_adapter_mode, runtime_adapter_enabled) + LegacyJournalRuntimeAdapter facade.
• api/routes.py (+49/-9): /api/chat/start forks on runtime_adapter_enabled(); flag-off path is byte-identical to pre-PR; flag-on path wraps the same _start_chat_stream_for_session call in adapter shape.
• tests/test_runtime_adapter_seam.py (+121 new, 5 tests).
• CHANGELOG.md (+4).

Refs #1925, builds on #2283 (run-journal) and #2416 (seam contract). CI green on 3.11/3.12/3.13.

Traced against upstream hermes-agent

Pulled a fresh tarball. No cross-tool surface — the adapter facade delegates entirely to existing WebUI handlers (_start_chat_stream_for_session) and reads from the existing api/run_journal (#2283). No agent-side API change, no config.yaml schema change.

End-to-end trace

Mode parsing at api/runtime_adapter.py:177-181 — strict allow-list:

def runtime_adapter_mode(environ: dict[str, str] | None = None) -> str:
    source = os.environ if environ is None else environ
    raw = str(source.get(_RUNTIME_ADAPTER_ENV, _RUNTIME_ADAPTER_DIRECT) or "").strip().lower()
    return raw if raw in _VALID_RUNTIME_ADAPTER_MODES else _RUNTIME_ADAPTER_DIRECT

Defaults safely to legacy-direct for: env-unset, empty string, whitespace, typos (journal, sidecar, anything outside {legacy-direct, legacy-journal}). Case-insensitive (.lower()), whitespace-trimmed (.strip()), optional environ for testability.

Route fork at api/routes.py:7734-7783 — same call surface, two branches:

from api.runtime_adapter import (LegacyJournalRuntimeAdapter, StartRunRequest, runtime_adapter_enabled)

if runtime_adapter_enabled():
    def _legacy_start_run(request: StartRunRequest) -> dict:
        return _start_chat_stream_for_session(s, msg=request.message, ...)
    adapter = LegacyJournalRuntimeAdapter(start_run_delegate=_legacy_start_run)
    result = adapter.start_run(StartRunRequest(...))
    response = dict(result.payload)
    response.setdefault("stream_id", result.stream_id)  # fallback chain
    ...
else:
    response = _start_chat_stream_for_session(s, msg=msg, ...)   # IDENTICAL to pre-PR

The else branch is byte-identical to the pre-PR direct path (verified line-by-line). Default-off semantic is preserved exactly.

setdefault fallback chain at lines 67-71: the wrapper merges result.payload first (which is the dict returned by _legacy_start_run), then setdefaults for stream_id/session_id/run_id/status/active_controls. setdefault only fills missing keys, so the delegate's response shape is preserved.

LegacyJournalRuntimeAdapter at api/runtime_adapter.py:209-314 — protocol-translator facade:

• start_run requires a start_run_delegate callable. Returns RunStartResult wrapping the delegate's dict output.
• observe_run reads from api.run_journal.read_run_events with cursor → after-seq translation. Pure reader.
• get_run combines live_stream_lookup (caller-injected predicate) with journal summary. Pure reader.
• cancel_run, respond_approval, respond_clarify each require a callable delegate; without one, return ControlResult(accepted=False, status="unsupported", safe_message="..."). No queue, no callback registry.

RFC non-goal compliance — the adapter module owns:

• ✅ Zero module-level locks
• ✅ Zero module-level dicts (no agent cache, no cancellation registry, no callback queue)
• ✅ Zero module-level threads
• ✅ Zero module-level queues

Verified via reflection: [n for n in dir(api.runtime_adapter) if 'lock|dict|thread|queue' in n.lower()] returns empty lists for every category. The PR honors the RFC's explicit non-goals from #2416.

Other audit — things that are correct already

Security

• os.environ read is the only external input. No user-controlled data flows into mode selection.
• _cursor_to_after_seq parses a string with int() inside a try/except (TypeError, ValueError) → defaults to 0 (safe — replays from beginning). Cursor comes from journal (server-controlled), but defensive coding is good.
• No new file writes, no new sockets, no new subprocesses. Pure in-process facade.

Auth gate

• /api/chat/start continues to flow through existing handler chain. The fork happens AFTER the existing auth + workspace resolution at routes.py:7700-7730. No bypass.

Default-off invariant

• Test 1 test_runtime_adapter_interface_and_legacy_journal_methods_exist pins: runtime_adapter_mode({}) == "legacy-direct", runtime_adapter_enabled({}) is False, mode({"...": "sidecar"}) == "legacy-direct". Unknown values silently default to safe.
• Test 5 pins the route uses runtime_adapter_enabled() (not inline env check) AND retains the direct _start_chat_stream_for_session( call. Negative assertion: "HERMES_WEBUI_RUNTIME_ADAPTER" not in start_body — catches future drift where someone replaces the helper with os.environ.get(...).

Reversibility

• Flip the env var back to legacy-direct (or unset it entirely) → next request takes the else branch → byte-identical to pre-PR behavior. No data migration, no schema change, no session-file format change. Operationally boring revert per the RFC.

Per-request adapter construction

• adapter = LegacyJournalRuntimeAdapter(start_run_delegate=_legacy_start_run) constructed inside the handler. No module-level singleton, no caching. Adapter is stateless; GC'd after handler returns. Pattern is correct.

Local import inside handler

• from api.runtime_adapter import ... is a local import inside _handle_chat_start. First call imports; subsequent calls hit sys.modules cache. The module has no expensive top-level work (just dataclass definitions and constants). Negligible overhead.

Behavioural harness

=== Mode parsing (8/8 ✓) ===
  env unset                                → legacy-direct, enabled=False
  env=""                                   → legacy-direct, enabled=False
  env="legacy-direct"                      → legacy-direct, enabled=False
  env="legacy-journal"                     → legacy-journal, enabled=True
  env="LEGACY-JOURNAL"                     → legacy-journal, enabled=True   (case-insensitive)
  env="journal"                            → legacy-direct, enabled=False   (typo guard)
  env="sidecar"                            → legacy-direct, enabled=False   (unknown guard)
  env="  legacy-journal  "                 → legacy-journal, enabled=True   (whitespace trim)

=== start_run passthrough ===
  ✓ delegate called once with the request object
  ✓ run_id=abc-123, stream_id=abc-123, session_id=s1
  ✓ extra_field preserved in payload (no key loss)
  ✓ default active_controls populated when delegate omits

=== Missing-delegate failure modes ===
  ✓ start_run without delegate → NotImplementedError (loud, fail-fast)
  ✓ cancel_run without delegate → ControlResult(accepted=False, status="unsupported")
  ✓ respond_approval without delegate → ControlResult(accepted=False, status="unsupported")
  ✓ respond_clarify without delegate → ControlResult(accepted=False, status="unsupported")

=== No new persistent state ===
  ✓ module-level locks/dicts/threads/queues: all empty (RFC non-goal honored)

Edge-case trace

Scenario	Expected	Actual
Env var unset	direct path (byte-identical to pre-PR)	✅ harness + test
Env var = "legacy-journal"	adapter path	✅ test 5
Env var = typo / unknown	direct path	✅ harness
Env var = whitespace-padded	trimmed and matched	✅ harness
Adapter without start_delegate	NotImplementedError	✅ harness
Adapter without cancel_delegate	ControlResult(unsupported)	✅ harness
Adapter response missing stream_id	falls back to result.run_id	✅ setdefault chain
Adapter response with extra payload fields	preserved (dict merge)	✅ harness
Mid-process env flip	next request picks up new mode	✅ no caching
Existing run_journal API	unchanged	✅ read-only consumer
Existing _start_chat_stream_for_session	unchanged	✅ delegate calls verbatim
Cross-tool: CLI hits same routes	unaffected (default off)	✅

Tests

• PR-targeted: 5/5 pass (tests/test_runtime_adapter_seam.py).
• Full local suite (Python 3.14): 5683 passed, 63 skipped, 3 xpassed, 0 failed.
• CI: 3.11/3.12/3.13 all green.
• Behavioural harness: 8/8 mode-parsing scenarios + 4/4 passthrough/failure-mode scenarios + RFC non-goal compliance verified.

Minor observations (non-blocking)

1. runtime_adapter_enabled() reads os.environ per call. Mid-process env flips take effect on the next request. Useful for live rollback; could cause diagnostic confusion if the env state diverges from initial boot. A small print() or logger.info on flag detection would help operators. Not blocking.
2. response.setdefault("stream_id", result.stream_id) is the right shape because result.payload is dict(self._start_run_delegate(request) or {}) — so the delegate's keys are already in response. setdefault only fills if absent. Defensive against future delegate-shape drift.
3. active_controls = payload.get("active_controls") then if not isinstance(active_controls, list): active_controls = ["cancel"] if stream_id else [] — sensible default. Matches the RFC's "controls are present even before they're migrated" stance.
4. CHANGELOG entry says **PR #TBD** — pre-merge placeholder, idiomatic per project convention (release agent stamps final number). Same pattern as PR #2416.
5. _handle_chat_start is the only route forked. /api/chat/stream, /api/chat/cancel, /api/chat/approval, /api/chat/clarify still use the direct path even when the flag is enabled. That's intentional — Slice 2 scope says only start is wrapped; full observe/cancel/approval/clarify migration is Slice 3. The PR description correctly calls this out.

Recommendation

Approved. Tight Slice 2 implementation that honors every non-goal from the #2416 RFC: protocol-translator only, no new state owned by the adapter, byte-identical default-off path, strict env-flag allow-list. Test pins both the interface AND the route shape (with negative assertion against inline env checks). Behavioural harness confirms all parsing edge cases and RFC non-goal compliance.

✅ Parked at approval — ready for the release agent's merge/tag pipeline.

[nesquena-hermes]

Shipped in v0.51.81 (Release BE, stage-374) — thanks @Michaelyklam!

Squash-merged via stage commit 9fec727c (full merge: stage-374 → master at c45895d6).

Release notes:

• feat(runtime): add default-off RuntimeAdapter seam (refs RFC: Make WebUI a thin observability/control client over Hermes Agent runtime #1925)

Pre-release gate:

• pytest: 5814 passed, 6 skipped, 3 xpassed in 115s
• Opus advisor (claude-opus-4-7 with thinking): VERDICT ship as-is
• All pre-Opus checks (JS syntax, Python ast.parse, merge marker scan, CHANGELOG placeholder scan, agent self-verify on risk-class PRs) clean

Release: https://github.com/nesquena/hermes-webui/releases/tag/v0.51.81

v0.51.82 follow-up filed: #2435 — tighten /api/chat/start response shape parity when adapter flag is on