6.2 KiB
Live console Protocol and Demo Server
Scope
This is the lowest Live console layer. It extends the package-local Codex driver, typed harness contract, deterministic fixtures, and mock-core demo server. It does not import or change Paperclip server, UI, database, or production routes.
The browser boundary is HTTP plus server-sent events. The browser sends typed
actions to the demo server. Only the server starts codex app-server, reads
the existing Codex login, owns the working directory, and resumes provider
threads. No provider or Paperclip credential is serialized to browser state.
Deterministic fixture
protocol/fixtures/codex-driver/driver-conformance.json records the exact Codex
0.132.0 wire shapes used by conformance tests:
- command, file, permission, user-input, and MCP elicitation requests;
- accept, accept-for-session, decline, cancel, and submitted answers;
- goal get, set, pause, resume, and clear calls;
- subagent parent/child thread source metadata;
- same-turn and stale-turn controls;
- interrupt-before-start and terminal-race outcomes;
- stable reconnect identities and source cursor; and
- hostile diagnostic strings that must be redacted.
The fixture loader rejects missing cases, duplicate request identities, incomplete goal operations, and incomplete lineage or recovery identity.
Browser-resolved requests
The driver no longer automatically declines supported runtime requests. It
emits runtime_request.created, keeps the JSON-RPC response pending, and waits
for resolveRuntimeRequest.
| Upstream request | Canonical kind | Allowed response shape |
|---|---|---|
item/commandExecution/requestApproval |
command_approval |
accept, session accept, decline, cancel |
item/fileChange/requestApproval |
file_approval |
accept, session accept, decline, cancel |
item/permissions/requestApproval |
permission_approval |
empty safe permission grant for turn or session |
item/tool/requestUserInput |
user_input |
typed answer map, decline, cancel |
mcpServer/elicitation/request |
elicitation |
typed content, decline, cancel |
The permission response cannot widen the skillless filesystem or network boundary. A stale turn, duplicate response, provider cleanup, terminal turn, protocol failure, close, or reconnect settles the pending request exactly once. Only the resolution action enters the canonical event; submitted secrets or answers do not enter the acknowledgement payload.
Steering and interruption
Successful same-turn steering emits a completed
steering_acknowledgement item. A different or child identity is rejected
with HarnessStaleTurnError and stale_turn_rejected; direct child steering
is never emulated.
An interrupt received while turn/start is waiting for a provider turn ID is
queued and sent as soon as the ID arrives. After a terminal fact wins the race,
further steering or interruption returns already_terminal. A successful
interrupt request emits an interrupt_acknowledgement item without replacing
the session.
Goals and lineage
The driver probes thread/goal/get after create or resume. Success enables
get, set, pause, resume, and clear. A method-not-found response disables goals
and advertises the precise unsupported capability. The installed Codex 0.132.0
binary generated goal bindings but did not enable the method at runtime in the
recorded real session, so the evidence correctly shows goals: false.
Root and child threads use thread.id, thread.sessionId, forkedFromId, and
source.subAgent.thread_spawn to build lineage. Child start, status, and close
notifications become canonical thread_lineage items. Unrelated thread
notifications are ignored instead of being attached to the active session.
Demo-server API
Start it with:
pnpm --filter @paperclipai/paperclip-runner demo:live-console -- \
--host 127.0.0.1 --port 4174
The transport fails before binding unless --host is an explicit loopback
address. The standalone server and Vite middleware use the same admission
guard. It requires loopback local and remote sockets, the exact configured
loopback Host plus listening port, same-origin Fetch Metadata, a matching
browser Origin on mutations and streams, and application/json on every
mutation. Server-side automation uses a random per-launch bearer capability;
it is never returned by an API response or browser state.
Important routes:
GET /api/liveConsole/healthPOST /api/liveConsole/sessionsGET /api/liveConsole/sessions/:idGET /api/liveConsole/sessions/:id/events?after=:cursorGET /api/liveConsole/sessions/:id/stream?after=:cursorPOST /api/liveConsole/sessions/:id/steerPOST /api/liveConsole/sessions/:id/interruptPOST /api/liveConsole/sessions/:id/requests/:requestId/resolvePOST /api/liveConsole/sessions/:id/goal/:operationPOST /api/liveConsole/sessions/:id/reconnectPOST /api/liveConsole/sessions/:id/close
The server chooses the working directory. A create body cannot override it.
Provider, Paperclip, cookie, and bearer credential fields in create bodies are
rejected. Runtime-request resolution must match the pending request, its turn,
and the session named by the route; stale, cross-scope, and duplicate responses
fail with 409 before reaching the driver.
Every JSON and event response passes a second bounded redaction layer. Replay
uses the same validated PRP events and reducer as the live view.
The demo keeps at most 16 active sessions and four SSE subscribers per session by default. Call the close route (the browser does this on reset) to release a session immediately; server shutdown closes every remaining session and subscriber. Configuration may lower these limits and is hard-capped at 64 sessions and 16 subscribers.
Residual risk: a loopback service is still reachable by untrusted local processes, which can reproduce browser headers. The Codex sandbox and approval policy remain the final execution boundary; this demo transport is not a multi-user authorization boundary.
Verification
Run deterministic conformance first, then the real Codex boundary:
pnpm --filter @paperclipai/paperclip-runner exec vitest run \
src/drivers/codex/codex-app-server-driver.test.ts \
src/mock-core/live-console-demo-server.test.ts