feat!: swap provider harness to pi

[colinds]

Replaces agentry's hand-written Anthropic and OpenAI adapters (src/providers/, 1,404 lines) with pi (@earendil-works/pi-ai), then reworks its execution mechanics while keeping the JSX API. Agentry keeps its reconciler, engine, handles, conditions and subagents; pi owns the wire.

Net −3,700 lines.

What you get

• ~35 providers instead of 2, selected by string; OAuth subscription auth; usage.costUSD
• MCP on every provider — agentry is now the MCP client, so it no longer needs a provider-native connector
• Thinking signatures survive replay. The old Anthropic adapter dropped them, so multi-turn thinking was silently lossy
• The model is told when its tools change — previously the tool set could change between turns with no signal

Verification

I captured a live smoke baseline against the old adapters before touching anything, then re-ran the identical scenarios after and diffed: no regressions. Same tool round-trips, same event types, no lost usage keys. The only differences are the three predicted in writing beforehand — stopReason end_turn→stop, tool results becoming first-class toolResult messages, and betas disappearing (pi manages beta headers).

Also verified against real API calls: MCP end-to-end against @modelcontextprotocol/server-filesystem, NL conditions, dynamic tools unlocking mid-run, and cross-provider subagents. 151 tests pass; typecheck, lint, format, build clean.

Breaking changes (0.2.0)

• Single entry point — agentry/anthropic and agentry/openai are gone
• provider/model are plain strings; run/createAI take an optional pi Models collection, defaulting to pi's full catalog so zero-config works
• Tool schemas are TypeBox, not Zod (Type is re-exported from agentry; zod peer dep dropped)
• Removed: <WebSearch>, <CodeExecution>, <Memory>, <Agent websocket>, <System cache>, betas, stopSequences
• <MCP> now takes type: 'stdio' | 'url'

Why some things were removed rather than ported

pi ships no MCP and no provider-native tools by design. onPayload can inject {type: 'web_search_20250305'} into the request, but pi's Anthropic parser handles four block types with no fallthrough — server_tool_use and friends are dropped and vanish from replayed history. Works for one turn, corrupts the conversation after. So MCP is client-side instead (strictly better: every provider). Agentry now ships no built-in tools at all — search needs a third-party API, code execution is a sandboxing project, and memory is a few lines over storage you already own. All three are better written as ordinary tools.

Post-migration hardening

The migration used a minimal slice of pi — enough not to break anything. These commits close what that left.

Failure modes pi already solved that agentry was re-suffering. isContextOverflow (already in pi, unused) encodes overflow detection for ~18 providers across three modes, so a context blowout now raises a distinct AgentryContextOverflowError instead of an opaque provider error — and triggers a compact-and-retry. retryAssistantCall classifies what is worth retrying (529 retries; 401 fails fast without burning attempts). timeoutMs/headers/samplingParams are now reachable: before this, every run silently inherited the Anthropic SDK's 10-minute default with no way to change it. cacheRetention was declared and read but never set — permanently undefined until now.

Compaction rewritten. It used to replace the entire transcript with one summary, taking the model's recent context away exactly when it was deepest in a task. It now keeps a recent window verbatim, and the cut is forced onto a turn boundary — splitting an assistant message from the tool results answering it produces a transcript providers reject.

Context inspection (concept borrowed from pi-context-view): handle.describeContext() reports what is filling the window — system prompt, per-tool cost sorted largest first, messages. Calibrating against the live API showed a naive estimate runs ~6x under the provider's reported tokens (providers prepend scaffolding a client never sees), so the report carries reportedInputTokens for absolutes and confines section shares to attribution.

A real bug, found by writing the test the plan asked for: when an MCP server left the tree its connection closed but its tools stayed registered, so the model kept being offered tools whose server was gone.

Also: images may now be returned from tools (pi carried them end-to-end; agentry's own ToolResult type was the only thing blocking screenshot/chart tools), thinking levels are clamped to what a model supports, and deferred/pending stop reasons throw rather than silently ending a run with empty output.

Deliberately not built: background/detached subagent runs. Concurrent subagents already work — each handle has its own store, container and session id — and that is now documented. Cross-turn deferral would need a serializable agent identity, but <AgentTool agent={...}> is a closure, which is the point of the JSX API.

Review notes

Commits are split for readability, not bisectability — only HEAD is green, since the message-type change forces src/tests/examples to move together. Start with the core swap and the execution-mechanics commit. The last commit acts on a structural review; its notable finding was that conditions.ts still called pi directly, breaking the "one path to a model" invariant one commit after it was documented.

Test count 178 → 177: ~2,900 lines of provider-wire tests covered deleted code; new suites cover MCP (against a real stdio server), robustness, resource diffing, context usage and the pi facade.

Acting on the code review

A review of the finished branch found four real defects, all now fixed and covered:

• MCP leaked a server process per message. The handle builds a fresh engine per run(), and the engine owned the connection set — so every sendMessage reconnected each server and orphaned the previous ones, while close() reaped only the last. Measured: three messages, three live processes, two surviving close. Cross-run state now lives on an AgentSession owned by the handle.
• retry did nothing in the default configuration. Agents default to stream: true, but only the non-streaming path went through pi's retry helper. Streaming now retries failures that arrive before the first token; past that a retry would replay output the caller has already seen, so it stays terminal.
• <MCP> prop changes were silently dropped — three causes stacked: no reconciler branch for MCP instances, the instance aliasing React's frozen props object (so the write threw inside the commit phase, where it is swallowed), and connections keyed on server name alone.
• usage reported the final turn while documented as a run total, under-reporting a ten-turn loop tenfold.

Two review findings were checked and dismissed with evidence rather than fixed: the compaction summary request sends tool_use blocks with no tools param, which Anthropic accepts (verified live), and pi's own token estimator is unreachable — dist/utils/* has no entry in its exports map.

Also fixed: MCP tool handlers tested the abort signal from the turn they connected on, dead from turn two onward; close() could throw from a finally and mask the run's result; MCP servers connected serially; and two TurnRequest retry fields no caller ever set.