hermes-web-ui/docs/agent-runner.md

# Agent Runner Gateway

This directory is the planning and implementation home for a unified agent run
gateway. The goal is to make Claude Code, Codex, and internal Web UI runs share
one protocol pipeline, one stream subscription model, and one persistence path.

## Goals

- Provide shared protocol plumbing that can be used by:
  - Claude Code local proxy routes.
  - Codex local proxy routes.
  - Hidden Coding Agent sessions launched from the Web UI Chat surface.
- Normalize upstream provider streams into one internal event shape.
- Let subscribers consume the same stream for HTTP/SSE responses, Socket.IO
  events, database persistence, usage accounting, and logs.
- Keep existing session storage under the current Web UI SQLite session tables.
- Keep Koa route handlers thin.

## Non-goals

- Do not rewrite the Hermes bridge runner in the first pass.
- Do not change the sessions/messages schema until a missing field is proven.
- Do not mix provider credential storage changes into the first refactor.
- Do not make one large class that owns Koa, Socket.IO, provider fetches, and DB
  writes at the same time.

## Current Facts

- `proxies/claude-code-proxy.ts` exposes an Anthropic-compatible local proxy for
  Claude Code.
- `proxies/codex-proxy.ts` exposes a Responses-compatible local proxy for Codex.
- `run-chat/handle-bridge-run.ts` is the active Web UI Hermes bridge path.
- `run-chat/handle-api-run.ts` already contains a Responses-stream persistence
  path, but it remains separate from the Coding Agent runner.
- `run-chat/response-stream.ts` already maps Responses events into in-memory
  session messages and flushes assistant/tool messages to the DB.
- `coding-agent-run-manager.ts` owns hidden Claude/Codex process lifecycle for
  Chat-driven Coding Agent sessions.

## Architecture

Use Responses-style stream events as the canonical internal event format.

```
Provider protocol
  -> ProtocolAdapter
  -> CanonicalAgentEvent stream
  -> Subscribers
       -> HTTP SSE serializer
       -> Socket.IO emitter
       -> DB persistence subscriber
       -> Usage subscriber
       -> Debug/log subscriber
```

### Components

#### TargetRegistry

Owns local proxy targets and internal run targets.

Responsibilities:

- Normalize provider/model/base URL/api mode.
- Generate route keys and local proxy tokens.
- Keep upstream API keys out of launched agent config files.
- Optionally bind a target to profile/session metadata.

#### EndpointResolver

Builds upstream endpoint URLs for each API mode.

Responsibilities:

- Avoid duplicated URL rules in Claude and Codex proxy services.
- Support base URLs that already include API roots such as `/v1`,
  `/v1beta/openai`, `/api/paas/v4`, or `/openai`.
- Build paths for `chat/completions`, `responses`, and `messages`.

#### ProtocolAdapter

Converts request and stream shapes.

Initial adapters:

- `anthropic_messages <-> canonical responses events`
- `chat_completions <-> canonical responses events`
- `codex_responses <-> canonical responses events`

The adapter layer must not know about Koa, Socket.IO, or SQLite.

#### AgentRunGateway

The facade used by routes and internal chat code.

Responsibilities:

- Accept an `AgentRunRequest`.
- Select the correct target and adapter.
- Call upstream with `fetch`.
- Yield `CanonicalAgentEvent` values.
- Respect abort signals.
- Surface provider errors in one structured shape.

#### StreamSerializers

Serialize canonical events for client-specific protocols.

Initial serializers:

- Responses SSE for Codex.
- Anthropic Messages SSE for Claude Code.
- Socket.IO event payloads for Web UI chat.

#### RunPersistenceSubscriber

Consumes canonical events and writes to existing session tables.

Responsibilities:

- Create sessions when needed.
- Insert user messages once.
- Accumulate assistant text deltas.
- Insert assistant tool calls and tool results.
- Update session stats and usage at terminal events.

This should reuse or extract the existing behavior from
`run-chat/response-stream.ts`.

## Canonical Event Contract

The internal stream should preserve the subset of Responses events already used
by `run-chat/response-stream.ts`:

- `response.created`
- `response.output_text.delta`
- `response.output_text.done`
- `response.output_item.added`
- `response.function_call_arguments.delta`
- `response.output_item.done`
- `response.completed`
- `response.failed`

Each event should carry:

- `type`
- `response_id` or `run_id` when available
- `model`
- `output_index` and `item_id` when applicable
- `usage` on terminal events when available
- provider error details on failure events

## External Proxy Flow

Claude Code:

1. Route authenticates local target token.
2. Route passes Anthropic request body to `AgentRunGateway`.
3. Gateway normalizes upstream output to canonical events.
4. Optional persistence subscriber records the run when session metadata exists.
5. Route serializes canonical events back to Anthropic SSE or JSON.

Codex:

1. Route authenticates local target token.
2. Route passes Responses request body to `AgentRunGateway`.
3. Gateway normalizes upstream output to canonical events.
4. Optional persistence subscriber records the run when session metadata exists.
5. Route serializes canonical events back to Responses SSE or JSON.

## Internal Web UI Flow

1. Chat creates or reuses a hidden Coding Agent session.
2. The session launches Claude Code or Codex in the existing scoped
   `profile/provider/agent` config/workspace layout.
3. Chat input is written to the hidden process stdin.
4. The process calls a local Claude/Codex proxy instead of the upstream
   provider directly.
5. The proxy tees provider SSE: one branch goes back to the CLI, the other is
   normalized to canonical Responses events for DB persistence and Chat events.
6. Hidden sessions are recycled after 30 minutes of inactivity and on service
   shutdown.

## Session Binding

External proxy requests do not naturally know the Web UI session. The first
implementation should support optional binding in this order:

1. Target metadata created during agent launch.
2. `X-Hermes-Session-Id` request header.
3. Request body metadata, only for internal callers.

If no session ID is present, the proxy should not write to the chat DB.

## Security Rules

- Never expose upstream API keys to launched Claude/Codex processes.
- Keep local proxy tokens per route target.
- Do not accept arbitrary session writes without validating target token first.
- Do not let external request bodies override upstream provider/model unless the
  target explicitly allows it.

## Migration Plan

### Phase 1: Shared utilities

- Extract target registration/token validation.
- Extract endpoint URL building.
- Extract SSE frame parsing and make it CRLF-safe.
- Add focused tests around URL building and SSE parsing.

Status:

- Added `target-registry.ts`, `endpoint-resolver.ts`, and `sse.ts`.
- Moved Claude/Codex proxy implementations under `agent-runner/proxies/`.
- Updated `run-chat/sse-utils.ts` to reuse the shared CRLF-safe parser.
- Kept old service import paths as re-export shims.

### Phase 2: Canonical adapters

- Move existing Claude/Codex conversion functions behind adapter interfaces.
- Keep old route behavior unchanged.
- Add tests that compare old route output to adapter output.

Status:

- Added `adapters/responses.ts` for non-streaming Codex proxy conversions:
  - Responses request body to OpenAI Chat request body.
  - Responses request body to Anthropic Messages request body.
  - OpenAI Chat response to Responses response.
  - Anthropic Messages response to Responses response.
- Added `adapters/responses-stream.ts` for streaming Codex proxy conversions:
  - OpenAI Chat SSE to canonical Responses events.
  - Anthropic Messages SSE to canonical Responses events.
  - Native Responses SSE to canonical Responses events.
- Added `adapters/anthropic.ts` for non-streaming Claude proxy conversions:
  - Anthropic request body to OpenAI Chat request body.
  - Anthropic request body to OpenAI Responses request body.
  - OpenAI Chat response to Anthropic message.
  - OpenAI Responses response to Anthropic message.
- Added `adapters/anthropic-stream.ts` for streaming Claude proxy conversions:
  - OpenAI Chat SSE to Anthropic Messages events.
  - OpenAI Responses SSE to Anthropic Messages events.
- Added focused adapter tests.
- Codex proxy stream-state adapters now live outside the proxy file.
- Claude proxy non-streaming adapters now live outside the proxy file.
- Claude proxy stream-state adapters now live outside the proxy file.

### Phase 3: Gateway facade

- Add `AgentRunGateway.stream()` and `AgentRunGateway.complete()`.
- Make Claude and Codex proxy routes call the gateway.
- Preserve existing auth responses and model endpoints.

Status:

- Added `gateway.ts` with `completeJson()` and `streamBytes()`.
- Gateway centralizes upstream POST, bearer auth, provider JSON error parsing,
  and empty stream checks.
- Codex proxy now uses the gateway for non-streaming and streaming upstream
  calls.
- Claude proxy now uses the gateway for non-streaming and streaming upstream
  calls.

### Phase 4: Persistence subscriber

- Extract DB persistence from `run-chat/response-stream.ts`.
- Add optional persistence to proxy requests when session metadata is present.
- Add tests for assistant text, tool call, tool result, usage, and failure.

Status:

- Internal Web UI API runs reuse the existing `run-chat/response-stream.ts`
  persistence path by consuming canonical Responses events.
- External proxy request persistence remains intentionally disabled until
  session binding is added.

### Phase 5: Internal API run

- Keep `handleApiRun` separate from Coding Agent execution.
- Add a dedicated hidden Coding Agent runner class.
- Launch Claude/Codex with scoped provider config and local proxy targets.
- Capture proxy SSE into Chat DB and realtime events.

Status:

- Added `coding-agent-run-manager.ts` with hidden process start/send/stop,
  30-minute idle recycling, and shutdown cleanup.
- `prepareCodingAgentLaunch()` can bind proxy targets to an `agentSessionId`
  and Chat `sessionId`.
- Codex now routes `codex_responses` providers through the local proxy too, so
  native Responses streams can be captured.
- Added protected API helpers for hidden run start, input, and stop.

### Phase 6: Cleanup

- Thin `claude-code-proxy.ts` and `codex-proxy.ts` into route adapters.
- Remove duplicated conversion and SSE parsing code.
- Revisit naming and export boundaries.

## Implementation Notes

Gateway adoption is complete for the current proxy and internal API-run paths:

- Claude and Codex proxy route handlers remain responsible for local auth, Koa
  response shape, and target lookup.
- `AgentRunGateway` owns upstream POSTs, bearer auth, stream validation, and
  provider error shape.
- `run-stream.ts` chooses the provider protocol and returns canonical Responses
  events to Web UI runs.
- Persistence stays optional and disabled for external proxy requests unless a
  session binding is provided.

Compatibility constraints:

- Claude Code expects Anthropic-shaped errors and Messages SSE events.
- Codex expects OpenAI/Responses-shaped errors and Responses SSE events.
- Some OpenAI-compatible providers expect `/v1/chat/completions`.
- Some providers already include a non-`/v1` OpenAI root path in `baseUrl`.
- Endpoint resolver behavior should be driven by provider-preset tests, not
  only regexes.

The next safe extraction is a persistence subscriber for external proxy request
session binding. Internal Web UI runs already persist through
`run-chat/response-stream.ts`.

## Validation

Minimum checks for each phase:

- Focused server tests for changed services.
- `npm run test -- tests/server/coding-agents-launch.test.ts`
- `npm run test -- tests/server/run-chat-content-blocks.test.ts` when touching
  chat input conversion.
- `npm run build` before merging shared TypeScript contracts.

For chat session behavior changes, also add a fragment under
`docs/chat-chain-changes/` according to the repository validation guide.