test(examples): pi end-to-end verification runbook

[ross-rl]

What

• examples/combined-app/docs/pi-e2e-runbook.md (new) — the operator procedure for verifying the Pi path end to end: preconditions → blueprint build → the pi_json mount JSON inline → app start → provision a Pi agent → streaming turn → interrupt → steer/follow-up → session state and idle-suspend/resume → reconnect-with-replay → feature-compat. Each step lists the expected timeline events so a failure localises to one hop, and a closing section says what the runbook deliberately does not cover.
• examples/combined-app/README.md — a Docs section linking the runbook (and the existing architecture doc).
• single-prompt.ts — asserts the turn settled on agent_settled (not on the agent_end that can precede it) and that getState().isStreaming is false afterwards.
• session-resume-pi.ts — asserts new_session does not reuse session A's transcript file and that switch_session restores it.

Why

PR 5 of the Pi sub-plan, on top of #156. The repo has no e2e or integration suite — every sdk/src/**/*.test.ts is a unit test against __test-utils__/mock-axon.ts, and the only live-agent CI is the repository_dispatch at runloopai/remote-agents-sdk-smoke-tests. So this codifies the Pi e2e as a reproducible runbook plus assertions in the repo's existing live-agent automation (feature-examples), rather than smuggling new browser-driving CI infrastructure in under a test label.

What was actually executed — and what was not

Not executed: the vbrowser run. I could not perform it, and none of the runbook's live steps have been run. Three independent blockers, all present:

1. runloopai/runloop #10256 (feat(broker): plumb Pi protocol selection) is open, not merged, so no broker in any environment accepts a pi_json mount yet.
2. No credentials on this machine: RUNLOOP_API_KEY, NEBIUS_API_KEY and NEBIUS_BASE_URL are all unset, and there is no Nebius endpoint access.
3. No browser to drive: no vbrowser, chromium or playwright binary is available here.

There are therefore no screenshots of a streamed turn, an interrupted turn, or a post-resume turn. I am not claiming verification I did not perform.

Executed:

bun run check                                          # pass
bun run typecheck                                      # pass
bun run build                                          # pass
bun run test                                           # 659 passed (29 files)
bun run --filter 'feature-examples' typecheck           # pass
bun run --filter '@runloop/example-*' typecheck         # pass
bun run --filter '@runloop/example-combined-app' build  # pass
bun run dev:server                                      # boots; logs "NEBIUS_API_KEY: NOT SET, NEBIUS_BASE_URL: NOT SET (Pi agents need both)"

Against that running server I confirmed the Pi wiring that does not need credentials: POST /api/pi/state with an unknown agent returns 404 {"error":"Agent nope not found"}, and POST /api/start with agentType: "pi" returns 401 {"error":"RUNLOOP_API_KEY not set in server .env"} — i.e. the routes are registered and the credential guard fires before any devbox is created. That is the whole of the live evidence.

What remains to be verified, and how

Once #10256 is merged and deployed, an operator with RUNLOOP_API_KEY + NEBIUS_API_KEY + NEBIUS_BASE_URL should:

1. Run the runbook start to finish against that environment, driving the UI in vbrowser, and attach the three screenshots it asks for (streamed turn with thinking + text blocks; interrupted turn; post-resume turn with the devbox.suspended/devbox.resumed events visible).
2. Confirm step 5's turn-boundary claim specifically: agent_end arrives, streaming may continue, and the composer re-enables only at agent_settled.
3. Run the full bun run feature-compat (no filters) and commit the regenerated compatibility.md. It is deliberately not regenerated in this PR or in feat(examples): add Pi agent to blueprint, feature examples, and combined app #156: its rows are live-run results, and regenerating without credentials would replace every real pass with skip. Until then bun run feature-compat --validate reports one issue — [compatibility.md] Use case "session-resume-pi" not found in table. llms.txt was regenerated in feat(examples): add Pi agent to blueprint, feature examples, and combined app #156, because it derives from USE_CASES alone. CI does not run --validate, so this does not turn CI red.
4. Expect pass for pi on single-prompt, agent-via-blueprint and session-resume-pi; any row that cannot pass needs a written reason in the use case, per the elicitation-acp convention.

A follow-up issue for adding the Pi case to the release smoke suite is filed against runloopai/remote-agents-sdk-smoke-tests (linked in the comments).

PR title format

test(examples): Pi end-to-end verification runbook

Checklist

• PR title follows <type>(<scope>): <description> format
• bun run check passes (lint + format)
• bun run build passes
• bun run test passes
• SDK documentation updated (if applicable) — no sdk/ changes here

[ross-rl]

Smoke-suite follow-up filed: runloopai/remote-agents-sdk-smoke-tests#6 ("Add Pi (pi_json) case to the release smoke suite").

[ross-rl]

Review summary

Findings: 1 minor.

• [TEST] minor — This stacked PR also receives no build/typecheck job because its base is not main; only conventional-commit ran. It changes feature-example TypeScript in addition to the runbook, so please obtain a CI typecheck result or broaden the workflow trigger before landing.

No functional runbook finding. The procedure correctly distinguishes prompt acceptance from completion, treats agent_settled (not agent_end) as the boundary, documents broker-owned launch arguments, and explicitly states that live coverage is not automated.

[ross-rl]

From the SDK side (#155): the missing-CI finding on this PR is addressed by #158, ci(project): run CI on pull requests with any base, which drops the branches: [main] filter from ci.yml's pull_request trigger so every PR gets check (Node 22 and 24) and audit whatever its base. #158 is green. Once it merges, this PR picks up a real typecheck/build result on its next push — nothing to change here.

Until then, worth stating in the body that only conventional-commit ran, so a one-item check list is not read as a passing build. Flagging one related SDK change in case the runbook mentions it: the Pi pull queue is now bounded (maxQueuedFrames, default 1000, oldest dropped), and a rejected-prompt ack only terminates receiveTurn() for the prompt it belongs to.