paperclip/packages/paperclip-runner/docs/live-console.md

Live console Live Console

Scope

This is the browser layer of Live console. It adds a Live console mode to the existing standalone devtool in devtools/browser/. It builds on the protocol and demo server and follows the approved interaction map and component decision record.

Every file lives under packages/paperclip-runner/. The console does not import or change Paperclip server, UI, database, or control-plane code.

Start it

pnpm --filter @paperclipai/paperclip-runner console:live-console

Then open http://127.0.0.1:4180/ and choose Live console.

Live console is deliberately loopback-only. A wildcard or LAN --host fails startup because this developer console can start provider-backed turns and resolve approvals. There is no unauthenticated remote mode.

Two environment variables change the driver behind the console:

Variable	Default	Effect
PAPERCLIP_LIVE_CONSOLE_DRIVER	demo	codex starts the real codex app-server driver behind the same routes
PAPERCLIP_LIVE_CONSOLE_CHUNK_DELAY_MS	45	Milliseconds between streamed chunks in the demo driver

Where state comes from

The console has one data contract: the canonical PRP event stream and the SessionSnapshot the shared reducer produces from it. There is no second event model, no message store, and no client-side session cache.

• The browser reduces the events it receives with the same applyPrpEvent the server and the CLI use, so a live session and a replayed session project identically. The inspector's Session tab reports that comparison as match or mismatch.
• Transcript order is the reducer timeline order. Nothing is re-sorted.
• Lineage, goal state, pending requests, and the durable cursor come from the demo server's public state, which is refreshed whenever new events arrive.
• The steering chip is the only local UI intent. It resolves to acknowledged, rejected, or failed from canonical facts and never merges text into the transcript before an acknowledgement.

Surfaces

Surface	Source of truth	Notes
Transcript	reducer timeline and items	user messages come from turn.submitted payload text
Composer	composer state machine	one visible primary action: Send, Steer, or Stop
Steering chip	steering_acknowledgement item or a rejection code	rejected text stays recoverable with Send as new message
Request card	runtime_request.* events	renders only the actions the upstream request offers
Goal banner and menu	capability snapshot and goal events	unsupported verbs are disabled with the exact diagnostic
Lineage tree	driver thread lineage	child steering is shown as unsupported, never emulated
Connection block	transport status and durable cursor	includes a deliberate connection-loss control
Inspector	raw canonical events	four tabs: Events, Requests, Capabilities, Session
Replay stepper	recorded canonical events	marked with a REPLAY eyebrow badge

Interruption races

The console distinguishes all three races the spec requires:

Race	What the console shows
interrupt before start	the pending turn resolves to Cancelled before start; no assistant item is ever created
interrupt during generation	the stream stops in place, the partial text stays, and an interrupted divider is added
interrupt during a tool call	the tool item keeps its last known status with no fabricated result

Escape in the composer moves focus to Stop. It never interrupts directly, because a destructive action needs an explicit activation.

Demo chats

The demo server owns the manifest catalogue and serves it at GET /api/liveConsole/manifests. Each manifest names the scenario it proves and the observations a human should confirm; the console renders that list as a checklist rather than restating it in the UI.

Manifest	Proves
completion	streaming, reasoning, tool, answer, structured result
steering	same-turn steering acknowledgement and stale-turn rejection
interrupt-before-start	cancellation before the provider accepts the turn
interrupt-during-generation	preserved partial text
interrupt-during-tool	preserved tool status with no fabricated result
approvals	command and file-change approvals, single-response guarantee
user-input	typed answers and request expiry
subagents	parent/child lineage and unsupported child steering
goals	set, view, pause, resume, clear
goals-unsupported	exact capability diagnostic instead of a hidden control
failure	failed item and failed turn inside the record

Manifests run in any order. Reset demo state names exactly what it discards and leaves recorded evidence files untouched.

Credentials

No provider or Paperclip credential reaches the browser. The Node process owns the driver, the working directory, and any provider login. Every JSON and event frame passes the demo server's redaction layer, and the inspector renders redaction markers verbatim without attempting to reconstruct them.

The live console and standalone server share one transport admission guard: exact loopback Host/port, loopback sockets, same-origin Origin and Fetch Metadata, plus JSON-only mutations. Browser reset closes the server session; active sessions and SSE subscribers are hard-capped. Local untrusted processes remain a residual risk, and the Codex sandbox/approval policy is the final execution boundary.

Components

Adapted from shadcn/ui and Vercel AI Elements source, rewritten in the package's local idiom, with zero new runtime dependencies:

• AI Elements: conversation, message, composer, reasoning-item, tool-item.
• shadcn/ui: tabs, menu, dialog, tooltip, banner.

scripts/check-forbidden-imports.mjs fails the build if anything under devtools/browser/ imports ai, @ai-sdk/*, zod, radix-ui, cmdk, streamdown, shiki, use-stick-to-bottom, class-variance-authority, tailwindcss, or nanoid. scripts/check-browser-tokens.mjs fails if a component file carries a raw colour, pixel, or font value.

Verification

pnpm --filter @paperclipai/paperclip-runner exec vitest run \
  src/mock-core/live-console-scripted-driver.test.ts \
  src/mock-core/live-console-demo-server.test.ts \
  devtools/browser/src/live/transcript-model.test.ts
pnpm --filter @paperclipai/paperclip-runner test:browser
pnpm --filter @paperclipai/paperclip-runner check:browser-tokens
pnpm --filter @paperclipai/paperclip-runner check:forbidden-imports

See the tutorial.