feat(pi): add a pi --mode rpc adapter

[dviejokfs]

Outcome

Adds Provider::Pi and providers::Pi, behind a new default pi feature, which drive the pi coding agent through pi --mode rpc (JSONL over stdio). Embedders get pi as a fourth first-class harness next to Claude Code, Codex and OpenCode, with:

• streamed text and thinking deltas, the tool lifecycle, usage with cost and context-window occupancy, compaction start/completion/failure, and auto-retry warnings;
• session start and resume. A resume of a session pi does not have fails as pi::session_not_found, and one whose messageCount pi does not report as a valid count fails as pi::session_unconfirmed, both before the prompt is written, so a stale id never silently starts a new conversation;
• cooperative cancellation through pi's abort command;
• extension dialogs (confirm, select, input, editor) delivered to the interaction handler as approvals and questions;
• discovery: the model catalog, read over RPC with --no-session and including per-model thinking levels, plus a credential check through pi --list-models;
• skill discovery and management for pi's user and project skill directories.

pi's end-of-run events (agent_end, turn_end) repeat the whole conversation, so on long turns they outgrow the event-line limit. To keep those turns working without raising the limit:

• as soon as a frame crosses the limit, the runtime asks the new AgentAdapter::accepts_oversized_frame with the frame's first 512 bytes. The default declines, which fails the turn at once, so other adapters behave as before;
• an accepted frame is consumed without being buffered, and AgentAdapter::parse_oversized_frame receives an OversizedFrame with its first and last 512 bytes;
• pi drops the redundant frames. An oversized tool result is reported with its output omitted, but with the outcome pi wrote in isError, which pi places after the result. If that outcome cannot be read, the call is reported as failed, never as succeeded.

Fix included: event lines are now held to max_event_line_bytes exactly. Previously a CRLF-terminated line at the limit was rejected, and an unterminated final line one byte over it was accepted.

Not included yet:

• process retention, steering and live messages;
• turn-scoped MCP servers. They are rejected before spawning, and strict MCP maps to --no-extensions;
• pi MCP listing and management (reported as unsupported);
• native image attachments.

Protocol and security impact

• CLI version: tested against pi 1.0.0.
• Permissions:
  • pi runs tools without asking, so the adapter accepts only FullAccess (--no-approve) and Plan, which passes pi's read-only tools (read, grep, find, ls) through --tools, intersected with allowed_tools.
  • Default, AcceptEdits and custom modes fail before spawning instead of silently running with full access.
  • Approvals only come from pi extensions' UI requests.
• Argument injection: model, thinking level, session id and tool names are validated before they reach pi's argv. Values starting with -, empty values, and tool names containing , are rejected.
• Environment: PI_CODING_AGENT_DIR and PI_CODING_AGENT_SESSION_DIR join the local, SSH and Temps sandbox environment allowlists, like CLAUDE_HOME. PI_SKIP_VERSION_CHECK=1 stops pi from contacting its update server on every turn.
• Bounded output: tool output, interaction text, warnings, session titles and the set of running tools are all bounded. Retry warnings do not echo the provider's error text.
• Compatibility: Provider is #[non_exhaustive], so Provider::Pi is additive. accepts_oversized_frame and parse_oversized_frame have default implementations. Default discovery now reports four harnesses instead of three; the fullstack example now enables only the three agents its UI implements.

Verification

• cargo fmt --all -- --check
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test --all-features: 382 lib tests plus every integration suite, including the new tests/pi_rpc.rs (12 tests against a scripted pi RPC fixture: tool turn, retained resume, missing session, rejected prompt, extension confirm, cancel/abort, oversized summaries, an oversized failing tool result, an oversized answer, rejected modes and turn-scoped MCP, discovery)
• Fullstack example: cargo clippy and the full Playwright e2e suite (19 passed)
• Feature combinations checked: --no-default-features, --no-default-features --features pi, and cargo +1.88 check --all-features --all-targets --locked (MSRV)
• Documentation and changelog updated: README, API reference (new pi section and capability column), events, architecture, discovery, tailnets, quickstart, site
• python3 scripts/check-package.py and cargo package --locked

Manual: examples/pi_smoke.rs drives the real pi 1.0.0 binary against a local mock of the Anthropic Messages API. All scenarios passed:

• readiness and discovery;
• a bash tool turn;
• resume of the same session without a second SessionStarted;
• the missing-session rejection;
• plan mode blocking bash;
• a turn under a 4 KiB event limit;
• a failing bash call whose output exceeds that limit, reported as failed from isError;
• cancellation in about 0.5 s.

To run it against a real model, set PI_SMOKE_ENVIRONMENT to the names of the provider key variables to forward:

cargo run --example pi_smoke --features pi -- [provider/model]

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds a new pi coding agent adapter.

The PR appears safe to merge; no new actionable issue remains.

Summary

The PR adds pi as a default-enabled provider and extends bounded event reading to let adapters handle oversized frames. The changes since the previous review add early rejection of unrecognized oversized frames, preserve oversized tool outcomes, and reject resumes whose session count cannot be confirmed.

• Adds pi RPC turns, discovery, permissions, interactions, and session handling.
• Adds focused tests for oversized frames, failed tools, and unconfirmed resumes.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Pi RPC stdout] --> B{Frame within limit?}
    B -->|Yes| C[Parse complete event]
    B -->|No| D{Adapter accepts prefix?}
    D -->|No| E[Fail turn promptly]
    D -->|Yes| F[Consume frame; retain first and last 512 bytes]
    F --> G[Parse oversized summary or tool outcome]

Loading

_{Reviews (2) · Last reviewed commit: "fix(pi): keep oversized tool failures fa..."}