04 — pi.dev runner (`pi`)

[gewenyu99]

🔄 Reorientation — 2026-06-19 (depends on #688, #522 · THE headline deliverable)

This is the goal: a feature-flagged pi backend on the #688 abstraction, built on pi.dev
(@earendil-works/pi-coding-agent). The earlier @openai/agents build was a wrong turn and is scrapped
(PRs #586/#587/#590 closed). Re-spec:

• Land under runner/backends/pi/, implementing AgentBackend.run(session, config, programConfig, boot)
  (the 01 — Runner seam + multivariate wizard-runner flag (anthropic | pi) #521 interface) — a drop-in for runLinearProgram, consuming the 02 — Shared runner contract + adapters (gateway, MCP, prompt, tools, stream→TUI) #522 shared substrate + BootstrapResult.
• Selected at wizard-runner=pi, inside linear.ts. v1 is linear-only; per-task backend selection in
  orchestrator mode is a later follow-up.
• Pi uses typebox, not zod — re-evaluate / revert the zod-4 bump that existed only for @openai/agents.

---

Epic: #520 · Behavior change: none (flag off) · Depends on: #522

Summary

Implement the pi backend on pi.dev (@earendil-works/pi-coding-agent) — a Claude-Code-style coding
agent that owns its own tool loop and ships Read/Write/Edit/Bash. It speaks the PostHog gateway directly via
a registered anthropic-messages provider, runs the same commandments + skills as anthropic, and streams
onto the shared TUI bridge. Selected at wizard-runner=pi.

Scope

• Deps: @earendil-works/pi-coding-agent, @earendil-works/pi-ai. No @openai/agents, no aisdk adapter.
• Gateway provider — registerProvider(name, { baseUrl: getLlmGatewayUrlFromHost(host), apiKey: <posthog token>, api: 'anthropic-messages', headers: <Bedrock-fallback + wizard metadata/flags> }) (reuse 02 — Shared runner contract + adapters (gateway, MCP, prompt, tools, stream→TUI) #522's header builder). Model via getModel(provider, id) from @earendil-works/pi-ai, same id as the anthropic backend for a clean A/B.
• Session — createAgentSession({ model, resourceLoader: new DefaultResourceLoader({ systemPromptOverride: <commandments> }), customTools, cwd: <install dir>, sessionManager: <in-memory> }); run via session.prompt(prompt).
• Stream → TUI — map session.subscribe events (message_update text/thinking deltas, tool_execution_start|update|end, turn_*, agent_end) onto the 02 — Shared runner contract + adapters (gateway, MCP, prompt, tools, stream→TUI) #522 stream→TUI bridge (status, todos, dashboard/notebook markers) and the run log.
• Errors — map terminal/loop errors to AgentErrorType; honor [ABORT]. Degrade gracefully when a dependency (e.g. local MCP) is unavailable.

Acceptance criteria

• A text-only and a tool-using run complete end-to-end against the gateway through the registered provider.
• Streaming + markers + todos reach the TUI.
• Flag stays 0% pi; anthropic unaffected.
• Unit tests for backend wiring (mocked provider) incl. the abort/stop guard.

Open questions

• Does Pi's provider append /v1/messages to baseUrl, or is the full path needed?
• How does Pi resolve a custom-provider model without interactive auth in headless/CI runs?
• Does Pi mount MCP servers, or are PostHog data ops better as custom defineTool tools? (see Epic: Pluggable model-agnostic agent runners (anthropic | pi) #520)

Files

• src/lib/agent/runner/backends/pi/

Notes

Skills load via Pi's native file-based discovery — drop the resolved framework SKILL.md into a Pi-scanned
dir (.pi/skills / .agents/skills) before the run (progressive disclosure, the context-mill model). Wizard
capabilities (env-file ops, wizard_ask, PostHog data ops) ride as defineTool custom tools. Per-tool
gating (canUseTool + YARA) is #525.