RFC: Make WebUI a thin observability/control client over Hermes Agent runtime

[Michaelyklam]

Summary

Hermes WebUI currently gives a polished browser experience, but browser-originated chat runs are executed inside the WebUI server process. That means WebUI is more than an interface layer: it creates in-memory streams, starts background agent threads, instantiates/reuses AIAgent, and owns live cancellation/streaming state.

This RFC proposes shifting WebUI toward the thinnest possible client that still gives full parity features:

Hermes Agent owns execution, sessions, active runs, slash-command semantics, approvals, clarify, tools, models, and durable state. WebUI owns presentation, browser UX, and control/observability surfaces over Hermes.

The goal is not to reduce WebUI capability. The goal is to prevent WebUI from becoming a parallel Hermes runtime.

Current behavior / motivation

Today, the WebUI chat path roughly does this:

1. Browser calls POST /api/chat/start.
2. WebUI creates a stream_id and StreamChannel.
3. WebUI stores the stream in process-global STREAMS.
4. WebUI starts a daemon thread running _run_agent_streaming.
5. _run_agent_streaming constructs/reuses AIAgent and calls agent.run_conversation(...).
6. Agent callbacks push token/tool/reasoning/approval/clarify events back into WebUI-owned in-memory queues.

This has some nice properties: direct low-latency SSE, simple local deployment, and direct access to the live agent object. But it also creates real costs:

• WebUI restarts/updates can kill active browser-originated runs.
• Browser refresh/reconnect semantics depend on WebUI process memory.
• WebUI has to maintain runtime shims for Hermes behavior.
• Features such as slash commands, /goal, model/provider routing, approvals, clarify, queue/interrupt/steer, etc. risk being reimplemented in WebUI instead of inherited from Hermes.
• Active WebUI streams can block safe WebUI updates.
• WebUI cannot be treated as a disposable observability/control layer.

Design principle

For every feature, ask:

Is this Hermes behavior, or WebUI presentation?

Hermes behavior should be exposed from Hermes and consumed by WebUI. WebUI should own only browser-specific presentation and interaction.

Hermes should own

• agent execution
• sessions and transcript persistence
• active run lifecycle
• model/provider/toolset routing
• memory and skills
• slash command semantics/capabilities
• approvals and clarify lifecycle
• cancel/interrupt/queue/steer semantics
• background and goal continuation
• token/tool/reasoning events
• cron/gateway/session state

WebUI should own

• layout and navigation
• chat rendering
• stream visualization
• tool-call cards
• approval/clarify widgets
• session browser UX
• settings panels
• workspace picker UX
• themes/mobile/PWA/native-wrapper behavior
• adapting Hermes events into a great browser experience

Proposed direction

Move browser-originated execution out of WebUI-owned AIAgent threads and into Hermes Agent’s native runtime/API surface.

Hermes Agent already has an API server with run-like endpoints:

POST /v1/runs
GET  /v1/runs/{run_id}
GET  /v1/runs/{run_id}/events
POST /v1/runs/{run_id}/stop

WebUI should use Hermes-owned runtime APIs as the execution boundary rather than importing/instantiating AIAgent directly.

Target architecture:

Browser
  ↓
WebUI: UI, auth/session presentation, SSE/WebSocket adapter, controls
  ↓
Hermes Agent runtime/API: sessions, active runs, events, commands, approvals, tools
  ↓
AIAgent / tools / gateway / cron / state.db

Proposed phases

Phase 1: Document the boundary and current coupling

• Document the current WebUI-owned execution path.
• Document which runtime features WebUI currently reimplements or owns directly.
• Define the desired owner for each feature: Hermes vs WebUI.

Acceptance criteria:

• Maintainers agree on the boundary: WebUI should be a thin client over Hermes runtime, not a second runtime.

Phase 2: Adapter spike against Hermes /v1/runs

• Add a feature flag, e.g. HERMES_WEBUI_USE_HERMES_RUNS=1.
• Keep existing WebUI frontend event format initially.
• Internally route WebUI chat start to Hermes /v1/runs.
• Subscribe to /v1/runs/{run_id}/events and adapt Hermes events to current WebUI SSE events.
• Use Hermes /v1/runs/{run_id}/stop for cancellation.

Acceptance criteria:

• A browser-originated chat can run without WebUI instantiating AIAgent.
• Existing WebUI rendering continues working through an adapter.
• WebUI restart no longer kills a Hermes-owned run, assuming Hermes remains up.

Phase 3: Identify missing Hermes runtime API capabilities

While building the adapter, record missing pieces that force WebUI to keep private runtime state.

Likely needs:

• list active runs
• map session → active run(s)
• replay events from a cursor / Last-Event-ID
• approval request/response API
• clarify request/response API
• queue/interrupt/steer API
• command metadata with WebUI support/capability flags
• session/run status fields sufficient for reconnect UI

Acceptance criteria:

• Missing capabilities are tracked upstream in Hermes Agent rather than patched as WebUI-only runtime logic.

Phase 4: Delegate Hermes-native slash/control commands

• Continue using Hermes command metadata.
• Add capability metadata so WebUI can know which commands are supported on the WebUI surface.
• Delegate Hermes-owned commands to Hermes instead of reimplementing them in WebUI.
• Keep WebUI-local commands local, e.g. theme/layout/browser UI commands.

Examples:

Command / behavior	Desired owner
/goal	Hermes
/model / provider routing	Hermes
/reasoning	Hermes
/compress	Hermes
/status runtime status	Hermes
/theme	WebUI
workspace picker UX	WebUI presentation over Hermes/workspace config
terminal drawer UI	WebUI presentation

Acceptance criteria:

• WebUI no longer has to chase parity for Hermes-native behavior one command at a time.

Phase 5: Make WebUI restart/update safe by default

• WebUI restart should only drop the browser connection.
• Browser reconnect should discover the active Hermes run and resume event rendering.
• WebUI updates should not need to block on active Hermes-owned runs.
• Legacy WebUI-owned streams can remain blocked/drained during transition.

Acceptance criteria:

• Start a long-running run from WebUI.
• Restart hermes-webui.service.
• Reopen browser.
• The run is still active or completed in Hermes.
• WebUI catches up to current run/session state.

Non-goals

• Not a rewrite of the frontend.
• Not a new sidecar service by default.
• Not a requirement for Redis/Kafka/NATS.
• Not horizontal scaling in the first pass.
• Not removing rich WebUI features.
• Not exposing CLI-only or unsafe gateway-only commands blindly.

Open questions

1. Should WebUI talk to Hermes Agent API server directly, or through a small local adapter inside WebUI?
2. Which current WebUI behaviors must remain WebUI-local because they are presentation-only?
3. What is the minimal Hermes API surface needed for feature parity?
4. How should browser reconnect discover an active run for the currently viewed session?
5. Should Hermes event replay be durable immediately, or can phase 1 start with live Hermes SSE and add replay later?
6. How should Hermes Agent updates behave while a Hermes-owned run is active?
7. What command capability metadata is needed so WebUI can safely inherit Hermes-native slash commands?

Success criteria

This is successful when:

• WebUI does not import or instantiate AIAgent for normal chat.
• WebUI can be restarted without killing active Hermes-owned runs.
• Browser refresh/reconnect does not duplicate or lose runs.
• WebUI renders live token/tool/reasoning/approval/clarify state from Hermes events.
• WebUI sends control actions to Hermes rather than mutating live agent objects.
• Hermes-native slash command behavior is inherited where possible.
• WebUI remains rich, but its codebase becomes mostly UI/adapters instead of agent orchestration.

One-line north star

Build WebUI as the first-class Hermes client, not a second Hermes runtime.

[ai-ag2026]

I agree with the runtime concern, but I disagree with part of the implied product framing.

WebUI should not permanently become a second Hermes runtime. Agent execution, provider/model routing, durable run state, memory, tool semantics, approvals, clarify, and command behavior should ultimately belong to Hermes Agent itself.

But I do not think WebUI should become merely a thin presentation layer or a secondary companion client next to the native Dashboard.

For me, the value of this WebUI is exactly that it is the best surface for active work:

• sessions stay visible instead of disappearing into the background
• history is easy to inspect and resume
• workspace files are directly available in the same context
• tool calls, reasoning/progress, and agent activity are visible in detail
• long-running work remains observable, steerable, and recoverable

That makes WebUI more than a browser skin over Hermes. It is the actual workbench where agentic work happens.

I would also not want administrative/control functionality to live only in the native Dashboard. If users have to switch between WebUI for active work, Dashboard for admin/status/config, Workspaces for files, and another surface for sessions or runs, then we recreate the same fragmentation in a different form.

My preferred direction would be:

Hermes Agent Runtime = execution plane
WebUI                = primary user-facing workbench / cockpit
Native Dashboard     = reference/admin surface and upstream control-plane implementation

So yes, WebUI should consume Hermes-owned runtime APIs instead of owning execution threads and in-memory agent state forever.

But the product north star should not be "make WebUI thin".

It should be:

Make WebUI thin in execution ownership, not thin in product scope.

WebUI should remain the primary coherent surface for Hermes work: sessions, runs, history, workspace files, tool process, artifacts, and day-to-day control/admin in one place, while Hermes Agent owns the runtime underneath.

That means a /v1/runs migration should not be considered successful just because basic chat streaming works. It needs to preserve or improve the current WebUI experience:

• live streaming
• detailed tool cards
• reasoning/progress visibility
• session reattach and recovery
• workspace-aware chat
• simple history navigation
• stop / queue / interrupt / steer
• background / BTW workflows
• approval / clarify UI
• active/stale/failed/recovered run visibility
• model/provider/profile/toolset visibility and control
• logs, diagnostics, runtime status, and safe update/restart UX

Otherwise this would be a technical cleanup that regresses the actual product value of WebUI.

The risk I would want to avoid is replacing WebUI-owned runtime state with an adapter that still has to locally simulate missing Hermes runtime features. That would just move the complexity around and could leave us with two half-runtimes instead of one clean runtime boundary.

A safe path might be:

1. Document the current WebUI-owned execution path and coupling points.
2. Identify the missing Hermes runtime APIs needed for WebUI parity.
3. Add a /v1/runs adapter behind a feature flag.
4. Start with basic chat / stream / stop parity only.
5. Add active-run discovery, event replay/cursors, approval/clarify lifecycle, steer/queue/interrupt, and command capability metadata.
6. Only remove the current WebUI execution path once the workbench experience has real parity.
7. Treat admin/control features as part of the WebUI product vision too, so users do not need to juggle multiple Hermes UIs for normal daily operation.

So my position is:

I support moving execution ownership into Hermes Agent.

I do not support reducing WebUI to a thin companion UI or forcing users to operate multiple partially-overlapping Hermes browser tools. The long-term goal should be one strong daily WebUI surface backed by a clean Hermes runtime boundary.

[franksong2702]

I think the key distinction is:

WebUI should be thin in execution ownership, not thin in product scope.

Today WebUI is not only presenting Hermes work. For browser-originated chats, WebUI also owns a large part of the execution runtime: it creates in-memory streams, starts background threads, instantiates/reuses AIAgent, calls run_conversation(), and implements local control flows around that live agent object.

That shape explains many of the source-of-truth / parity issues we keep seeing.

Current Shape

flowchart TD
  B[Browser UI] --> W[Hermes WebUI Server]

  W --> S[WebUI STREAMS / active stream state]
  W --> T[WebUI background thread]
  T --> A[AIAgent inside WebUI process]
  A --> R[run_conversation]
  R --> X[Tools / model calls / approvals / clarify]

  R --> E[WebUI SSE events]
  E --> B

  W --> C[WebUI-owned controls<br/>stop / steer / queue / goal hooks]
  W --> P[WebUI-owned runtime shims<br/>provider / model / command parity]

Loading

This works, and the current WebUI experience is valuable. But the execution source of truth is split. WebUI is gradually becoming a second Hermes runtime.

Target Shape

flowchart TD
  B[Browser UI] --> W[Hermes WebUI]

  W --> UX[Rich Workbench UX<br/>chat / sessions / workspace / tool cards / controls]
  W --> AD[Runtime Adapter]

  AD --> H[Hermes Agent Runtime API]

  H --> R[Runs / run_id / lifecycle]
  H --> EV[Events / cursor / replay]
  H --> CMD[Command semantics]
  H --> CTRL[Stop / steer / queue / approval / clarify]
  H --> M[Provider / model / tool routing]
  H --> ST[Durable state]

  H --> AD --> W --> B

Loading

The target should not make WebUI a weak viewer. WebUI should remain the primary workbench. The change is that Hermes Agent Runtime owns execution, lifecycle, command semantics, and durable truth.

In short:

Hermes Agent Runtime = execution source of truth
WebUI                = rich user workbench over that runtime

Why I would avoid a direct swap

I would not start by replacing /api/chat/start directly with /v1/runs. The current WebUI experience depends on many behaviors around the execution path:

• token streaming
• tool cards
• reasoning/progress display
• approval and clarify UI
• stop / steer / queue / interrupt
• goal continuation
• provider/model routing visibility
• attachments and workspace context
• title / usage events
• reconnect and recovery behavior

A direct replacement risks getting "basic chat works" while regressing the workbench.

Safer Migration Shape

flowchart LR
  B[Browser UI] --> P[Stable WebUI Event Protocol]

  P --> F{Execution backend}

  F -->|default| L[Legacy WebUI-owned AIAgent path]
  F -->|feature flag| N[Hermes-owned run adapter]

  L --> E[Normalize to WebUI events]
  N --> E

  E --> B

Loading

Suggested phases:

1. Inventory current execution ownership.
2. Define the stable WebUI event contract.
3. List missing Hermes Runtime APIs.
4. Add a feature-flagged Hermes run adapter.
5. Make restart / reattach the first real success criterion.
6. Migrate controls one by one: stop, status, replay, approval, clarify, steer, queue, goal, commands.
7. Only remove WebUI-owned execution after parity is proven.

The important success metric should not be merely “WebUI no longer instantiates AIAgent.”

The success metric should be:

WebUI stops owning execution while preserving or improving the full workbench experience.

That avoids an in-flight engine swap. The legacy execution path keeps the product working while the Hermes-owned runtime path grows behind an adapter.

[Michaelyklam]

I think this is the right refinement. One constraint I would make explicit: the adapter should be a protocol translator, not a runtime surrogate.

The current code illustrates the trap pretty well: api/config.py owns STREAMS, CANCEL_FLAGS, AGENT_INSTANCES, partial/reasoning/tool buffers, and the cached agent objects; api/streaming.py registers approval/clarify callbacks, mutates per-run environment, starts checkpoint/recovery logic, constructs/reuses AIAgent, and eventually calls agent.run_conversation(...). If the Hermes-run adapter recreates that same shape with different names, WebUI still owns execution in practice.

So I would define the first spec slice as two artifacts:

1. WebUI event contract / compatibility layer

   • token/delta events
   • reasoning/progress events
   • tool start/update/done events
   • approval request/resolution events
   • clarify request/resolution events
   • title/usage/status/error/done events
   • reconnect fields: run_id, session_id, cursor / last event id, terminal state

2. Hermes Runtime API gap matrix

   • for every WebUI event/control, identify the Hermes /v1/runs event, run state field, or control endpoint that is authoritative
   • anything that cannot be mapped becomes a Hermes Runtime API gap, not a WebUI-only shim

That keeps the feature-flagged path honest. WebUI can keep its existing frontend event format initially, but the source of truth for lifecycle/control should be Hermes-owned: active run discovery, cursor replay, session→run mapping, stop/interrupt/steer/queue, approval/clarify response, command capability metadata, provider/model/tool routing, etc.

Short-term, a stable WebUI event protocol is useful to avoid frontend churn. Long-term, I would not want that to become another permanent divergent runtime protocol. It should be a browser-oriented view over Hermes runtime events.

I also like making restart/reattach the first real success criterion. “Basic chat streams through /v1/runs” is too weak. A better spike acceptance test is:

1. start a non-trivial WebUI run through the Hermes-owned path,
2. restart only hermes-webui,
3. reopen the browser/session,
4. rediscover the active or completed Hermes run,
5. replay/catch up enough events for the workbench to render the same state without WebUI having kept the agent object alive.

If that works, the architecture is actually moving toward Hermes as the execution source of truth instead of just swapping one streaming implementation for another.

[Michaelyklam]

I think the most useful next step is to turn this RFC into a small spec plus an implementation ladder, so the discussion does not stay at the architecture slogan level.

The framing I would suggest is:

WebUI should be thin in execution ownership, not thin in product scope.

So WebUI can still be the full workbench: sessions, files, activity, reasoning, tools, approvals, status, admin surfaces, etc. The boundary is that the Hermes-run adapter should be a protocol translator, not a runtime surrogate. If the adapter recreates STREAMS, cached AIAgent objects, local approval state, local clarify state, cancellation flags, and command semantics under different names, we have not really moved execution ownership.

A concrete spec could start with two artifacts:

1. WebUI event/control contract

Define the browser-facing compatibility contract WebUI needs, independent of which runtime produced it:

• token / delta events
• reasoning and progress events
• tool start / update / done events
• approval request / resolution events
• clarify request / resolution events
• title, usage, status, error, done events
• reconnect fields: run_id, session_id, cursor / last event id, terminal state
• controls: cancel, approve/deny, clarify response, queue/continue, goal status/control where supported

This lets us preserve the current WebUI product experience while making the runtime boundary explicit.

2. Hermes Runtime API gap matrix

For every event/control above, map it to one of:

• an existing Hermes /v1/runs event
• an existing Hermes run state field
• an existing Hermes control endpoint
• a missing Hermes API capability
• a temporary WebUI compatibility shim

That matrix is probably the key deliverable. It prevents “thin client” from becoming vague, and it prevents the adapter from quietly becoming a second runtime.

Digestible implementation slices

A natural order might be:

1. Inventory the current WebUI runtime-owned state and controls (STREAMS, AGENT_INSTANCES, cancel flags, approval/clarify buffers, tool/reasoning buffers, goal hooks, cached agent state).
2. Define the event/control contract in docs plus source-level tests or fixtures.
3. Build a read-only Hermes-run adapter/proxy that can subscribe to existing Hermes run events and emit WebUI-compatible events.
4. Add reconnect/cursor semantics and persisted terminal run state.
5. Map the control plane: cancel, approval, clarify, queue/continue, goal state.
6. Put one narrow chat path behind a feature flag using the adapter, with the current WebUI runtime still as fallback.
7. Add parity tests comparing legacy WebUI event streams to adapter event streams for the same synthetic run.
8. Expand feature coverage only after the contract holds.
9. Retire WebUI-owned AIAgent execution after parity is proven, not before.

That would make this issue actionable without requiring a big-bang rewrite.

[nesquena-hermes]

Aligned on the framing: WebUI thin in execution ownership, not thin in product scope. That's the right boundary, and @Michaelyklam's "protocol translator, not runtime surrogate" guardrail captures the failure mode I worry about most — the temptation to reproduce STREAMS / CANCEL_FLAGS / cached AIAgent shape behind a different API surface.

Concretely, the implementation ladder I'd want before this turns into code:

1. Spec the adapter surface first. A small protocol doc covering: start a run, observe a run (token / tool / reasoning / approval / clarify events), cancel, queue, and resume. Anything not in that spec is a parallel runtime by accident. The current STREAMS / STREAMS_LOCK / CANCEL_FLAGS triple in api.state_sync plus the agent-callback registration in api/streaming.py is what would migrate.

2. Hermes Agent has to own the run. This is the prerequisite. Until the agent exposes a stable IPC for "start run / observe run / cancel run" with the right semantics (idempotent reconnect, durable across short WebUI restarts), the adapter has nothing to call. That's an upstream change and predicates everything else.

3. Migration order. New runs first (greenfield, no compatibility burden). Existing/in-flight runs second, with a fallback to the current in-process path during transition. Approvals/clarify last because they're cross-cutting (gateway already has its own adapter shape).

4. Non-goals up-front. WebUI keeps its full product surface — sessions, files, activity, reasoning view, tools, approvals UI, admin. The adapter only takes over the execution slice. Settings, dashboard, slash command UI, workspace, voice mode, projects all stay where they are.

The friction with implementing this today is point (2): hermes-agent doesn't yet expose the IPC we'd need. Some of the substrate is there (gateway/session_context.py contextvars, the gateway approval queue model) but a stable run-observation protocol isn't. That makes this an upstream-change + hold issue for now — the work to do here is keep the spec sharp so when the agent-side primitives land, the adapter is straightforward to write rather than a guessing game.

Keeping this open as the architecture-direction tracker. Concrete migration PRs would link back here.

[Michaelyklam]

That makes sense to me. I would treat point (2) as the hard gate: WebUI can define the compatibility surface now, but the first implementation work should probably happen as an upstream Hermes runtime/API spec before WebUI starts moving execution out of process.

A concrete way to keep this from turning into another in-process runtime would be to split the next step into three artifacts:

1. Runtime API / IPC v0 contract in Hermes Agent

Minimum surface, deliberately small:

• start_run: create a durable run from a session/workspace/profile/model/tool context
• observe_run: ordered event stream with replay from cursor / last event id
• get_run: current lifecycle state, terminal result/error, active controls
• cancel_run / interrupt
• queue_or_continue: append follow-up work to a live or resumable run
• respond_approval
• respond_clarify

The important part is not HTTP vs stdio vs websocket yet. The important part is that Hermes owns the run id, lifecycle, event log/cursor, cancellation, approval/clarify state, and terminal state. WebUI should be able to disappear briefly and reattach without the run becoming orphaned.

2. WebUI event/control compatibility contract

Keep the browser-facing shape stable enough that the existing workbench UX does not churn:

• tokens / deltas
• reasoning / progress
• tool lifecycle
• approval request/resolution
• clarify request/resolution
• title / usage / status / error / done
• reconnect metadata: run_id, session_id, event cursor, terminal state
• controls: cancel, queue/continue, approval, clarify, and goal where supported

But this contract should be explicitly marked as a WebUI presentation contract over Hermes runtime events, not a second source of truth.

3. Gap matrix against current WebUI runtime state

For each current WebUI-owned primitive, decide whether it maps to Hermes runtime state, a Hermes control endpoint, or a temporary compatibility shim:

• STREAMS / STREAMS_LOCK
• CANCEL_FLAGS
• AGENT_INSTANCES
• partial/reasoning/tool buffers
• approval callbacks and queues
• clarify callbacks and queues
• command capability metadata
• session→active-run mapping
• reconnect/replay behavior

Anything that cannot be mapped cleanly becomes an upstream Hermes Runtime API gap, not something the WebUI adapter should recreate privately.

Suggested implementation ladder

1. Inventory PR/docs: document current WebUI runtime-owned state and the desired event/control contract.
2. Hermes Runtime API v0: upstream start / observe / get / cancel with durable run ids and replayable events.
3. WebUI adapter behind a feature flag: new runs only; fallback to current in-process path.
4. Restart/reattach milestone: prove a run continues through a short WebUI restart and the UI can replay from cursor.
5. Controls: move cancel/queue/approval/clarify over the Hermes-owned control plane.
6. Retire runtime surrogate state: remove WebUI ownership of AIAgent construction/caching and in-memory execution state for the new path.

I would make the first success criterion very concrete:

Start a run from WebUI, restart only the WebUI process mid-run, reload the browser, and reattach to the same Hermes-owned run with ordered event replay and working cancel.

If that works without WebUI owning an AIAgent instance, STREAMS, or local cancellation truth for that run, then the architecture is moving in the right direction. If it only works by rebuilding those concepts inside an adapter module, we have just renamed the runtime surrogate.

[alex-pathcourse]

You're right that browser-originated chat runs shouldn't require the WebUI to manage execution and streaming state. With PathCourse Health's observability module, you get full runtime control without owning active run state or cancellation logic in your client.

Working example: https://github.com/pathcourse-health/pch-integration-examples#3-observability--traces-spans-anomalies