04 — pi.dev runner (`pi`)

[gewenyu99]

🔄 Re-spec — 2026-06-26 (a RUNNERS entry; selected by the existing wizard-runner flag)

The pi runner is a leaf engine registered into RUNNERS (see #521), not a mode. It is reached when a
route resolves the runner to pi or the existing wizard-runner=pi flag overrides it. It consumes the
resolved pair's model as an input (model: string) rather than hardcoding one. Built on pi.dev
(@earendil-works/pi-coding-agent); the earlier @openai/agents build was scrapped (PRs #586/#587/#590
closed). Pi uses typebox, not zod — re-evaluate/revert the zod-4 bump that existed only for
@openai/agents.

Epic: #520 · Behavior change: none (wizard-runner default-off) · Depends on: #521, #522

Summary

Implement the pi runner on pi.dev — 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.

Scope

• Deps: @earendil-works/pi-coding-agent, @earendil-works/pi-ai. No @openai/agents, no aisdk adapter.
• Register into RUNNERS as pi, implementing AgentRunner.run(inputs & { model }).
• 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). Resolve the model from the pair's model input (getModel(provider, id)), not
  a local constant — so a future pi + opus differs only by the resolved pair.
• 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 onto 02 — Shared runner contract + adapters (gateway, MCP, prompt, tools, stream→TUI) #522's bridge (status, todos, markers) and the log.
• Errors — terminal/loop errors → 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 through the registered provider when
  wizard-runner=pi (or a route resolves the runner to pi).
• Streaming + markers + todos reach the TUI.
• wizard-runner stays default anthropic; anthropic unaffected.
• Unit tests for runner 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?

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. Wizard capabilities ride as defineTool custom tools.
Per-tool gating (canUseTool + YARA) is #525.

[gewenyu99]

Done in #701 — the pi.dev runner is built and evaluator-validated at 5/5 (sonnet + gpt-5-mini) on app-router apps.