docs(sdk): add Pi connect sub-plan

[ross-rl]

What

Adds poss_plan_pi_sdk.md — the grounded, PR-by-PR plan for adding a native Pi connection (@runloop/remote-agents-sdk/pi) to this SDK, speaking the broker's pi_json protocol (proto AXON_ATTACH_PROTOCOL_PI = 6).

Docs only. No code changes.

The plan contains:

• The broker contract as the SDK sees it — input classification (turn/start / cancel / initialize / Control passthrough), the twelve outbound event_types, turn settlement at agent_settled (not agent_end, which can be followed by an auto-retry), the reserved broker- id prefix, and broker-owned resume via sessionFile + switch_session.
• Shared-primitive analysis — what in sdk/src/shared/ is reused as-is, the one 8-line relaxation worth making, and what should explicitly not be abstracted yet.
• File-by-file scope for sdk/src/pi/ (protocol/index.ts, types.ts, classify-pi-axon-event.ts, timeline-event-guards.ts, transport.ts, connection.ts), mirroring sdk/src/codex/.
• Five sequenced PRs, each with scope, exact files, acceptance criteria, and real verification commands from AGENTS.md.
• Thirteen open questions/risks, each with a recommendation and justification.

Headline decisions, for review:

1. The template's "lift shared primitives" PR is dropped. Codex already did the hoisting; AxonFrameTransport, runConnectionReadLoop, PendingRequestMap, createClassifier, resolveReplayTarget et al. are genuinely protocol-neutral and need no changes for Pi. The only lift worth doing is making the four replay-request callbacks on AxonFrameTransportOptions optional (Pi has no server-initiated requests, so it would otherwise pass four stubs) — ~8 lines, riding inside the connection PR rather than getting its own.
2. No BaseAxonConnection. The apparently-duplicated connect()/disconnect() residue across claude/codex/pi is not the same lines: Claude buffers control-request replay and requires initialize(), Codex sniffs threadId/currentTurnId, Pi captures sessionFile and has no handshake. Abstracting needs ~6 template hooks to save mechanical field declarations. Revisit at agent deps: Bump @vitejs/plugin-react from 4.7.0 to 6.0.1 in /examples/claude-app #4.
3. Hand-write the wire types; no @earendil-works/* dependency, no codegen. Pi does export RpcCommand/AgentEvent, but the type graph reaches @earendil-works/pi-ai and its five provider SDKs (openai, @anthropic-ai/sdk, @google/genai, @aws-sdk/client-bedrock-runtime, @mistralai/mistralai), and RpcResponse's members reference internal source paths that aren't addressable through any published subpath. Pi ships no JSON Schema, so codegen isn't an option either — same reason the broker hand-wrote pi-codes. Verified that pi-agent-core's AgentEvent union is field-for-field identical to pi-codes/src/events.rs, so structural parity with the crate is a reviewable property.
4. No initialize() on the Pi connection. Pi has no handshake, and the broker's Initialize input just re-issues get_state with no id — so its ack can't be correlated and an initialize() couldn't return the state it exists to fetch. getState(), publishing our own id-stamped get_state as a Control frame, is strictly more capable. Pi is the first module to break the "connect() then initialize()" pattern documented in sdk/AGENTS.md, so the absence gets called out there.
5. The e2e PR assumes no template, because there isn't one. There is no e2e or integration suite anywhere in this repo — sdk/vitest.config.ts globs only src/**/*.test.ts, all of which are unit tests over __test-utils__/mock-axon.ts; grep -ri vbrowser returns nothing; CI has no Runloop credentials and smoke-tests.yml only dispatches to runloopai/remote-agents-sdk-smoke-tests on release-please branches. Codex therefore has no e2e template to copy (and notably no timeline-event-guards.test.ts either, which claude and acp both have — so claude, not codex, is the test-layout parity target). The plan makes PR 5 a reproducible operator runbook plus feature-examples coverage, with vbrowser as the instrument for capturing evidence, rather than smuggling in new CI infrastructure under a test label.

Why

The PI workstream needs Pi driveable from Reflex through the Runloop broker, on open-source models served from Runloop's dedicated Nebius endpoint (glm-5.2). This SDK is the client half. Planning it up front, against the actual broker diffs rather than against guesses, keeps the implementation PRs small and independently reviewable — and surfaces the decisions worth arguing about (types source, abstraction boundary, e2e shape) before any code is written.

Companion broker-side work in runloopai/runloop: #10238 (merged — the pi-codes crate), #10243 (the Pi adapter), #10256 (protocol plumbing + the pi_json OpenAPI name).

PR title format

docs(sdk): add Pi connect sub-plan — type docs, scope sdk.

Checklist

• PR title follows the <type>(<scope>): <description> format
• bun run check passes
• bun run build passes
• bun run test passes — no new failures. Note: src/shared/pending-request-map.test.ts fails identically on main in my sandbox (7 fake-timer afterEach hook timeouts), so it is pre-existing and unrelated to this docs-only change.
• SDK docs updated — N/A for this PR; sdk/AGENTS.md and sdk/README.md updates are scoped into PR 3 of the plan.

[reflex-loop]

✅ Reflex agent status: Completed

The agent completed its work.

This PR was created by Reflex.

View the agent run →

_{This comment updates in place as the agent works.}