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

Live console: Run the Live Codex Protocol Console

What this is

This tutorial runs the Live console browser console. The protocol demo server tutorial used curl. This one uses the real user interface.

What this proves

The console shows one live session. You can chat with it, steer it, stop it, answer its requests, change its goal, watch its child threads, break its connection, refresh the page, and replay the whole record. Every screen reads the canonical protocol. Nothing in the browser holds a provider login.

Before you start

Run every command from the repository root. You do not need a Codex account for this tutorial. The default driver replays deterministic demo chats.

Step 1: Run the deterministic checks

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

Expected result: all three files pass. They cover the demo driver, the server routes, and the pure transcript model the console renders.

Step 2: Start the console

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

Keep this terminal open. Open http://127.0.0.1:4180/ in a browser and press Live console.

Expected screen: an empty transcript that says Pick a demo chat or start a blank session, a list of demo chats on the left, and a disabled Send button.

Step 3: Run one clean turn

1. Press Completion in the demo chat list.
2. Press Run this demo chat.

Expected facts:

• The connection badge says connected.
• Your own message appears first.
• A collapsed Reasoning block appears and opens while it streams.
• A Tool block shows its input and then its output.
• The answer streams into view with a blinking cursor.
• The turn ends with a Turn completed badge.

Step 4: Steer a running turn

1. Press Same-turn steering, then Run this demo chat.
2. While the turn runs, the primary button says Steer.
3. Type Keep it to one sentence. and press Enter.

Expected facts:

• A steering chip appears as pending and then becomes acknowledged.
• The chip never merges into the answer before the acknowledgement.

Now type text while the turn is running, wait for Turn completed, and press the button. The chip becomes rejected — turn already ended and offers Send as new message. Your text is never discarded.

Step 5: Stop a turn in three ways

Run each demo chat and press Stop:

Demo chat	When to press Stop	Expected result
Interrupt before start	right away	Cancelled before start, and no answer item is created
Interrupt during generation	while text streams	the stream stops, the partial text stays, and an interrupted divider appears
Interrupt during a tool call	while the tool runs	the tool keeps its last status and shows no result

The session is never replaced. After a stop you can simply send again.

Step 6: Answer requests

1. Press Command and file approvals, then Run this demo chat.

Expected facts:

• A blue banner above the composer says 1 request waiting — Review.
• The command card offers Approve, Approve for session, Reject, and Cancel, because the request offers those four actions.
• After you press Approve, the whole action row locks until the resolved event arrives. A second click cannot answer twice.
• The resolved card collapses to one line that names the action you chose.
• The next card offers only Approve and Reject, because that request offers only two actions.

2. Press User input and expiry, then Run this demo chat.

Type an answer and press Submit. Leave the second request alone. After a few seconds it becomes expired before response and stays in the record.

Step 7: Change the goal

1. Press Goal lifecycle, then Run this demo chat.
2. Press Goal, then Set goal…, type an objective, and confirm.
3. Press Goal, then Pause.

Expected facts: the banner shows the objective, the state, and the time of the last change. Resume is disabled while the goal is active, and Pause is disabled while it is paused.

Now press Goals unsupported and run it. The Goal button is disabled, not hidden, and it names the exact upstream reason: Goal operations unsupported: app-server 0.132.0 does not advertise the goals capability. Open the Protocol inspector and the Capabilities tab. The same string appears there.

Step 8: Watch child threads

Press Parent and child threads, then Run this demo chat.

Expected facts:

• The Threads panel lists the root session and two child threads.
• One child ends Completed and one ends Failed. Both stay in the tree.
• Selecting a child shows a breadcrumb and a disabled composer that says Direct steering of child threads is not supported by this app-server.

Step 9: Break the connection and recover

1. Run any demo chat and wait for it to finish.
2. Press Simulate connection loss.

Expected facts: a banner says the connection was lost, and the composer is disabled.

3. Press Retry now.

Expected facts: the badge returns to connected and the transcript is exactly what it was before the drop. Nothing is lost and nothing is duplicated.

Now reload the page and press Live console again. The same session returns with its full transcript.

Step 10: Replay the record

Press Replay.

Expected facts: a REPLAY badge appears, the transcript resets, and a stepper appears. Press Step forward to walk the session forward one event at a time. Press Play to run it. Press Exit replay to return to live.

Step 11: Inspect the protocol

Press Protocol inspector.

• Events: every canonical event with its sequence, type, and full payload. Filter by text or by event type.
• Requests: every runtime request with its lifecycle.
• Capabilities: what this app-server supports, with a reason for each unsupported row.
• Session: identities, cursors, gap state, and the live-versus-replay reducer comparison. It should read match.

Check the Credentials in browser row. It must read no.

Step 12: Check the keyboard

• Tab reaches every control, including the inspector and the dialogs.
• Enter sends. Shift and Enter add a line.
• Escape while a turn runs moves focus to Stop. It never stops the turn on its own.
• Arrow keys move between inspector tabs and between threads.
• End jumps the transcript to the newest item.

Step 13: Use the real Codex driver

This step needs a working Codex login on the machine.

PAPERCLIP_LIVE_CONSOLE_DRIVER=codex \
  pnpm --filter @paperclipai/paperclip-runner console:live-console

The routes and the screens are the same. The demo chat list still appears, but the manifest only supplies the first message; the real model produces the rest. The Codex login stays on the server.

Step 14: Clean up

Stop the console with Ctrl+C. The server-owned working directory is a temporary directory and is not part of your repository.

Where to go next

• Cumulative end-to-end tutorial
• Live console reference
• Live console interaction map