feat: add Pi RPC adapter

[ziahm6638]

Summary

Adds a native pi adapter that runs the Pi coding agent in headless RPC mode.

• spawns pi --mode rpc and sends ORCH prompts as JSONL prompt commands
• maps Pi RPC events into ORCH AgentEvents
• preserves Pi sessions by default for long-running context and auto-compaction
• leaves Pi extensions/skills/context enabled by default and ignores UI-only extension events
• supports config.model via --model and config.effort via --thinking
• registers pi in the adapter registry, model tiers, TUI wizard, init/agent help, and docs

Verification

• npm run typecheck
• npm test — 112 files, 1942 passing, 2 skipped
• npm run build
• Manual built-CLI smoke test: initialized temp project with --adapter pi, ran a Pi task, and verified it wrote smoke.txt containing PI_ORCH_ADAPTER_OK

Notes

The adapter intentionally preserves Pi's own harness prompt by passing ORCH's system prompt through --append-system-prompt rather than replacing it. Pi RPC extension_ui_request events are ignored so extensions/tools can stay enabled without polluting ORCH logs.

[github-actions]

🎉 Thanks for your first PR to ORCH! We're excited to review your contribution.

Our CI will run automatically:

• ✅ TypeScript strict mode check (tsc --noEmit)
• ✅ Full test suite (1493+ tests via Vitest)
• ✅ ESM build verification

A maintainer will review your changes shortly. In the meantime, check the Contributing Guide to make sure everything is in order.

⭐ If you enjoy working with ORCH, a star on the repo goes a long way!

[oxgeneral]

Thanks for the contribution — the adapter is well-structured, the tests are solid (especially the 20K-character agent_end case that drove the v2 line-reader fix), and all the registration points are covered correctly.

I ran npm run typecheck and npm test against this branch — both green (1942 passed, 1 unrelated flaky TUI test that also passes in isolation on main).

I have a few correctness concerns around stream lifecycle that I'd like addressed before merge. None of them are about the overall design — that's right.

Blockers (correctness)

B1 — Pi may hang waiting for stdin EOF

src/infrastructure/adapters/pi.ts:71-77

After writing the prompt JSONL, proc.stdin is left open. Many CLIs in --mode rpc keep reading stdin and won't terminate without EOF. If Pi has that behavior, the agent_end event never arrives, the generator hangs, and the orchestrator only recovers via the kill-on-done path that never fires.

if (proc.stdin) {
  proc.stdin.write(JSON.stringify({ ... }) + '\n');
  proc.stdin.end();   // <-- add this
}

If Pi RPC actually expects multiple stdin commands per session, please confirm with a code comment — but for ORCH's one-shot model, a single prompt + EOF is the intended pattern.

B2 — Generator can hang on AbortSignal

src/infrastructure/adapters/pi.ts:101-132

When signal.aborted triggers and we break out of the for await loop, control falls into await exitPromise while the Pi process is still alive (kill is only called on the done branch). The orchestrator will eventually call stop() from the outside, but until then the generator holds a pending Promise and the registered 'close' / 'error' listeners pin the proc object.

Suggestion: in the finally block, if signal?.aborted && !gotDoneEvent, kick off processManager.killWithGrace(pid, 1_000).catch(() => {}) before awaiting exitPromise.

B3 — Unhandled stream error before first byte

src/infrastructure/adapters/pi.ts:108

for await (const line of readPiRpcLines(proc.stdout)) doesn't catch errors emitted on the stream. If Pi crashes immediately or stdout errors before producing output, the 'error' event propagates out of the async generator as an unhandled rejection. claude.ts routes through createStreamingEvents in adapters/utils.ts, which handles this — the Pi adapter takes its own path and reintroduces the gap.

Suggestion: wrap the for await in try/catch, classify with classifyAdapterError, and yield an error event before letting the exit-handling logic run. A test for "stdout emits 'error' before any line" would be valuable too.

B4 / B5 — Release artifacts (maintainer side)

CHANGELOG.md entry and readme.md test-count badge are part of the project's release checklist (see docs/RELEASING.md) — I'll handle those as part of the next release. No action needed from you.

Important

I1 — Dead branch in extractPassiveUpdate

src/infrastructure/adapters/pi.ts:315

return state.finalText ? null : null;

Both branches return null, and the function never propagates anything when there are no tokens. If the intent was just "no event when no tokens", the whole helper simplifies:

function extractPassiveUpdate(parsed: Record<string, unknown>): ParsedPiEvent | null {
  const tokens = extractPiTokensFromMessage(parsed);
  return tokens ? { tokens } : null;
}

(The state parameter then drops from the signature.)

I3 — Buffer<ArrayBufferLike> generic

src/infrastructure/adapters/pi.ts:388

let pending: Buffer<ArrayBufferLike> = Buffer.alloc(0);

The generic form of Buffer<T> only landed in @types/node 22+. This project pins ^20.17.0. It compiles on some installs because npm hoists a newer transitive copy, but at the floor of the range it fails. Plain Buffer is enough:

let pending = Buffer.alloc(0);

I4 — as any in test mock

test/unit/infrastructure/pi-adapter.test.ts:43

spawn: vi.fn(() => ({ process: proc as any, pid: proc.pid })),

CLAUDE.md rules out any. Cast to ChildProcess (or define a narrow shape with the fields actually used). Other adapter tests follow this convention.

I6 — Token alias spread

src/infrastructure/adapters/pi.ts:363-375

Eight different aliases for five fields (cacheRead / cache_read / cache_read_input_tokens, etc.). Are all of these emitted by Pi across versions, or is some of it defensive against shapes Pi never produces? A short comment + reduction to the names actually observed would help future readers. If they really all appear, consider a small alias map:

const ALIASES = {
  input:       ['input', 'input_tokens'],
  output:      ['output', 'output_tokens'],
  reasoning:   ['reasoning', 'reasoning_tokens'],
  cache_read:  ['cacheRead', 'cache_read', 'cache_read_input_tokens'],
  cache_write: ['cacheWrite', 'cache_write', 'cache_creation_input_tokens'],
};

I8 — Silent stderr

src/infrastructure/adapters/pi.ts:88

proc.stderr?.resume() drains stderr without surfacing it. If Pi prints auth or extension-load errors there, they vanish. claude.ts / codex.ts either pipe stderr into events or surface the tail on non-zero exit. Worth aligning.

Out of scope for this PR

• I2 — deduplicating createPiRpcEvents against createStreamingEvents in adapters/utils.ts. The right fix is to extend the shared helper with an afterDone hook so all adapters benefit. I'll do that as a follow-up after this lands.
• assets/adapters-{dark,light}.svg and landing/index.html — visual assets, maintainer side.

Once B1-B3 and I1, I3, I4 are addressed I'll re-review and we can ship. Thanks again for the careful work — the RPC line-buffer fix was a real find.

[oxgeneral]

@ziahm6638 — pushed three follow-up commits addressing the review. Everything ran clean: npm run typecheck ✅, npm test ✅ (1952 passed, 2 skipped — up from 1947 with 5 new assertions).

Review feedback

Blockers

• ✅ B1 — proc.stdin.end() is now called after writing the prompt JSONL so Pi --mode rpc sees EOF and emits agent_end. Added a test: closes stdin after writing prompt so Pi RPC sees EOF.
• ✅ B2 — the finally block now schedules killWithGrace(pid, 1_000) whenever we leave without a done event (abort or stream error). The dangling 'close' / 'error' listeners no longer pin the ChildProcess. Test: kills the process when the abort signal fires before a done event.
• ✅ B3 — the stdout for await is wrapped in try/catch; pre-first-byte stream errors are classified via classifyAdapterError and yielded as an error AgentEvent instead of escaping as an unhandled rejection. Test: yields an error event when stdout emits an error before any line.

Important

• ✅ I1 — extractPassiveUpdate simplified; the unused ParseState argument is gone, and the dead state.finalText ? null : null branch is now a single return tokens ? { tokens } : null.
• ✅ I3 — dropped the Buffer<ArrayBufferLike> generic in readPiRpcLines. Switched the buffer to a Buffer | null sentinel so the type checks cleanly on @types/node ^20.x floor.
• ✅ I4 — the mock processManager.spawn no longer uses as any; it casts through unknown to ChildProcess. Matches the convention in other adapter tests.
• ✅ I6 — the eight token alias ?? chains are collapsed into a single PI_TOKEN_ALIASES map with a comment explaining the three sources of variation (Pi-native, snake_case shims, Anthropic-style fallthrough).
• ✅ I8 — proc.stderr?.resume() is replaced by createStderrTailCapture(), which keeps the last 4 KB of stderr and appends it to the error message on non-zero exit. Auth and extension-load failures no longer vanish. Test: appends stderr tail to error message on non-zero exit.

Out of scope (maintainer side, per your review)

• B4 / B5 — CHANGELOG.md and the readme test-count badge will be handled with the release.
• I2 — extending createStreamingEvents with an afterDone hook and porting Pi onto it: tracked as a follow-up; doesn't block this PR.
• Visual assets and landing/index.html.

Extra polish in this push

While auditing the PR for completeness, I also added:

1. Parametrized adapter tests (test(pi): parameterized adapter coverage for pi)

   • agent-factory.test.ts already enumerated claude/codex/shell/opencode/unknown — added the matching pi rows (model resolves to openai-codex/gpt-5.5, MCP skills filtered).
   • commands-init.test.ts already enumerated claude/opencode/codex for getDefaultAgents() — added pi.
   • wizard-effort.test.ts already tested effort step shown for claude / skipped for codex/shell/opencode/cursor — added the pi case (shown, matches EFFORT_ADAPTERS = { 'claude', 'pi' }).

2. Agents-tab onboarding tip (fix(tui): mention pi and opencode in agents onboarding tip)

   • The empty-state tip read "Each agent uses an adapter (claude, codex, cursor, shell)" — it predates opencode and now pi. New users on the Agents tab couldn't discover them.
   • Updated to enumerate all six. Exported ONBOARDING_AGENTS and added a regression test (onboarding-agents.test.ts) asserting every SUPPORTED_ADAPTERS entry is present, so the next adapter PR is forced to update the tip.

Ready for re-review whenever you have time. Thanks again for the RPC adapter — the line-buffer fix really is a real find.

[oxgeneral]

B1 update — live-tested against pi 0.73.1 and reverted.

While smoke-running the adapter today (orch run → pi --mode rpc → openrouter/anthropic/claude-sonnet-4.6), I hit a hard regression caused by the B1 fix:

• With proc.stdin.end() after the prompt JSONL write — pi emits {"type":"response","command":"prompt","success":true} (preflight), then agent_start → turn_start → user message_start → user message_end, and stalls. No assistant message_start, no message_update, no agent_end. The orchestrator timed out the run with only the echoed user message_start in run.jsonl. The task was marked succeeded with files_changed=null, tokens=null, no hello.md on disk.
• Without stdin.end() — same prompt, full event stream (text_delta deltas, tool_execution_start, tool_execution_end for write, turn_end, agent_end with usage), hello.md written on disk, tokens populated on the Run, task transitions todo → in_progress → review → done on attempt 1/3.

Root cause: pi-coding-agent 0.73.1 — dist/modes/rpc/rpc-mode.js — explicitly implements --mode rpc as a persistent server-mode session. case "prompt" schedules session.prompt(...) asynchronously and emits the preflight response back through stdout; closing stdin between the prompt write and the streaming response severs that. The original PR design (long-lived process killed via processManager.killWithGrace(pid, 1000) from createPiRpcEvents when the terminal done arrives) was right.

Pushed c6274fc reverting the B1 change:

• pi.ts: drop proc.stdin.end(); comment explains why and pins the verified pi version (0.73.1).
• pi-adapter.test.ts: the test that asserted stdin.end() was called now asserts it is not called, with the same rationale.
• pi-adapter.e2e.test.ts: matching update — the "B1 invariant" assertion was inverted.

B2 (abort/kill) and B3 (stream-error try/catch) stay — both still correct.

npm run typecheck clean, npm test 1953 passed, live smoke writes hello.md end-to-end. Sorry for the back-and-forth — the original review intuition was reasonable for a one-shot CLI, but pi 0.73.1 is firmly persistent-session. Happy to add a code comment about specific pi versions known to behave this way if useful.

[oxgeneral]

All blockers from the initial review are addressed, plus a few extras after live-testing:

Blockers

• B1 — initially fixed with proc.stdin.end(), then reverted in c6274fc after live testing on pi-coding-agent 0.73.1 revealed that pi --mode rpc is a persistent server-mode session. Closing stdin stalls the LLM call after user-message_end. Long-lived kill via processManager.killWithGrace(pid, 1000) on the done event (the original design) is correct. Inline reproduction + commit message: c6274fc.
• B2 — finally block now schedules killWithGrace(pid, 1000) whenever the generator exits without a done event (abort or stream error). Test: "kills the process when the abort signal fires before a done event".
• B3 — stdout for await is wrapped in try/catch; pre-first-byte stream errors are classified via classifyAdapterError and yielded as an error AgentEvent. Test: "yields an error event when stdout emits an error before any line".

Important (I1, I3, I4, I6, I8) — all applied; see 55e3929 for the consolidated change.

Extras on top

• Parameterized adapter coverage for pi in agent-factory, commands-init, wizard-effort (0a52296).
• Agents-tab onboarding tip now lists all six adapters, with a regression test asserting it stays in sync with SUPPORTED_ADAPTERS (fa007c7 + 57ad2e3 — extracted to src/tui/onboarding-config.ts).
• Integration test through real Orchestrator + state machine + JSONL storage (86a18f5).
• Integration test for TUI lifecycle via ink-testing-library (9bc41dc).
• /simplify pass: hot-path O(n²)→O(n) in readPiRpcLines, O(n) shift → O(1) subarray in stderr capture, leaky-export cleanup (57ad2e3); plus Buffer.from(subarray) to release oversized backing on stderr overflow (6fe17be).

npm test 1954 passed, npm run typecheck clean, CI green. Live smoke against pi 0.73.1 + openrouter wrote the target file end-to-end and transitioned through todo → in_progress → review → done on attempt 1/3.

Thanks @ziahm6638 for the careful work — the line-buffer fix and the RPC stream design were both solid. Merging.