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

SDK: Run the SDK Console and Mini Consumer

What this phase is

SDK makes the accepted browser tracer reusable. It has a browser client, a React hook, reusable components, one reference console, and one small second consumer.

The two apps use public package imports. They do not import the old demo UI. Provider credentials stay in the local server.

The reference console starts in Regular chat mode. Type a message in the composer to create a direct Codex session. Open Protocol inspector to see the event stream and reducer state. Select another flow only when you want a deterministic protocol fixture.

What this phase proves

This tutorial proves that a second app can use the SDK without a private import. It also proves that live events and replay events reduce to the same state. You can run every hard state with the fake driver. You can then run a safe turn with your real local Codex login.

Run commands from the repository root.

1. Run the small SDK tests

pnpm --filter @paperclipai/paperclip-runner test:sdk
pnpm --filter @paperclipai/paperclip-runner check:browser-tokens
pnpm --filter @paperclipai/paperclip-runner check:forbidden-imports

These tests check reducer parity, components, tokens, and package boundaries.

2. Open both apps with the fake driver

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

Open these pages:

• http://127.0.0.1:4181/reference-console/
• http://127.0.0.1:4181/mini-consumer/

The page header shows 🖇️ v0.1.2. Use this marker to confirm this iteration.

The fake driver is the default. It does not need a provider login.

3. Check the reference console

Use the manifest list. Run these flows:

1. Run Completion. Read the streaming and terminal messages.
2. Expand a Terminal row, then expand Debug details. Confirm the folded section contains canonical event metadata and provider payloads for the command without leaving the chat transcript. Assistant text should reveal progressively. For a real Codex semantic completion, read the clear summary first and expand Debug payload to inspect the exact structured JSON.
3. Run Same-turn steering. Type a new message while the turn is active. The button says Steer. Check the acknowledgement.
4. Run each interrupt flow. Confirm that the visible outcome names the race.
5. Run Command and file approvals. Resolve one request. Confirm that the card locks after the first click and later shows the canonical result.
6. Run Goal lifecycle. Set and clear the goal from the Goal menu.
7. Press Drop connection. Watch reconnect and gap recovery use the same session.
8. Enter replay. Step with Left and Right. Confirm the inspector says the replay matches live state.
9. Run Item and turn failure. Confirm that the exact server diagnostic is part of the transcript.

The clear response is a presentation of canonical provider output, not a second result model. The raw event stream remains in Protocol inspector.

Resize the browser to 390 by 844. Chat and the composer must remain the primary view. Open Menu to reach session controls, the protocol inspector, and replay. The app must not create a second hidden transcript or a horizontal page scrollbar.

4. Check the mini consumer

The mini app is intentionally small. Run a turn, steer it, stop it, resolve a request, set and clear a goal, drop the connection, and enter replay.

Look for these proof points:

• Mini renderer shows the custom item-body renderer.
• Mini detail shows the custom request-detail renderer.
• Set goal and Clear goal use the two Composer slots.
• The blue accent is a local --pcr-* token override.
• Fetch and EventSource are injected by the app.
• Replay parity: match appears after durable history is complete.

If the real driver says goals are unavailable, the two goal buttons stay disabled. This is correct. The SDK must not pretend the provider supports a feature.

5. Run the browser acceptance tests

On a machine with Playwright system libraries:

pnpm --filter @paperclipai/paperclip-runner test:browser:sdk

On a minimal Debian or Ubuntu machine without root access:

cd packages/paperclip-runner
bash scripts/verify-rootless-linux.sh pnpm run test:browser:sdk

This runs keyboard, accessibility, reconnect, gap-recovery, replay, fake driver, viewport measurement, and screenshot checks.

6. Run a real Codex session

Use a machine where the local Codex CLI is already authenticated.

cd packages/paperclip-runner
bash scripts/verify-rootless-linux.sh pnpm run record:sdk:codex

The test runs a safe completion through both public consumers. It checks that the browser contains no bearer token or auth.json path. The mini consumer then drops and reconnects the transport, enters replay, and confirms parity.

Real provider timing is not used to prove every race. The deterministic fake driver proves steering, interrupt, requests, and goal branches. The real run proves the same public transport and identity boundary against Codex.

7. Run the package acceptance command

pnpm --filter @paperclipai/paperclip-runner verify

Use verify:rootless if the host needs package-local browser libraries.

Expected result

All commands exit with status 0. The fake and real apps use public imports. Reconnect keeps run, session, and provider identity. Replay reports match. Provider credentials do not appear in browser state, DOM text, events, or diagnostics.