/migrating-pi-to-pydantic-ai

name: migrating-pi-to-pydantic-ai
description: Migrate TypeScript Pi coding-agent applications, extensions, or packages to Python with Pydantic AI and Pydantic AI Harness. Use when source code imports `@earendil-works/pi-*`, calls `createAgentSession`, registers Pi extensions, or relies on Pi tools, hooks, skills, sessions, compaction, providers, TUI, RPC, or packages.

Migrate Pi to Pydantic AI

Preserve observable behavior, not Pi's TypeScript API. Migrate the smallest complete caller path and keep product/host infrastructure in the application.

Trace the source before choosing a target

1. Read repository instructions, `package.json`, Pi settings, tests, extension/package manifests, and runtime entrypoints. Record the installed Pi, Pydantic AI, and Harness versions. 2. Trace one real request from the Pi CLI, RPC boundary, or `createAgentSession().prompt()` through resource discovery, system instructions, tools, extensions, model requests, messages, compaction/retry, events, session entries, UI/RPC output, and side effects. Establish a focused baseline or characterization test. 3. Inventory every active extension factory and package resource. For each `pi.on(...)`, `registerTool`, `registerCommand`, provider registration, renderer/UI contribution, skill, prompt, and persisted entry, record its firing point, trusted inputs, mutations, output, state owner, and caller-visible effect. 4. Separate these contracts when present:

• model messages, append-only session entries/tree branches, compaction summaries, and extension state;
• model-chosen tool input, trusted host context, project trust, approval, authorization, and OS isolation;
• token deltas, tool lifecycle, Pi extension events, capability events, RPC events, and terminal rendering;
• agent-loop behavior, CLI/TUI host behavior, provider transport, package distribution, and external side effects.

5. Record each observed contract, its owner, semantic difference, and executable proof. An installed but inactive Pi package feature is not migration scope.

Read [Research and concept mapping](references/RESEARCH-AND-MAPPING.md) for the detected features. Read [Verification and cutover](references/VERIFICATION-AND-CUTOVER.md) before implementation.

Treat extensions as capability candidates

A Pi extension is the closest source concept to a Pydantic AI capability, but it is broader. An extension can combine agent behavior with terminal UI, commands, provider registration, resource discovery, and host lifecycle. **Port responsibilities, not the extension file:**

1. Map reusable model-facing behavior—tools, instructions, model settings, history/event processing, guardrails, and agent-loop hooks—to an existing Core or Harness capability when its lifecycle matches. 2. Bundle related instructions and tools in core `Capability`; subclass `AbstractCapability` only for reusable behavior that needs lifecycle hooks, adaptive models/settings, native tools, or typed capability events. 3. Keep CLI commands, flags, keyboard shortcuts, TUI renderers/dialogs, session selection, project trust, package installation, and provider credential setup in the Python application or interface adapter. They are not agent capabilities merely because a Pi extension owns them. 4. Split mixed extensions at that seam. A permission extension may become a `ToolGuardrail` or approval capability plus an application-owned approver UI; a coding package may become `Coder` plus host configuration; a provider extension remains a model/provider integration. 5. Preserve order only where evidence shows it matters. Pi handler load order and Pydantic AI capability/hook ordering are different contracts.

Choose the smallest target

• **Core:** use `pydantic_ai.Agent` for the agent loop, typed dependencies, tools/toolsets, outputs, normalized messages, capabilities/hooks, streaming, approvals, usage limits, instrumentation, MCP, and provider/model integration.
• **Harness:** use `Coder` for Pi's ordinary coding tools only when its exact composition fits. Add focused capabilities such as `FileSystem`, `Shell`, `Skills`, `Planning`, `SubAgents`, guardrails, compaction, tool-output limits, or step persistence only for observed behavior.
• **Application/interface:** retain or replace CLI/TUI/RPC, auth, project trust, settings, provider login/catalogs, session browsing, package management, deployment, and transport deliberately.
• **Graph:** use plain async Python or `pydantic_graph` for deterministic workflows; do not encode them in prompts or subagents.
• **Gap:** name behavior with no supported public seam, explain its impact, and test a bounded adapter. Do not clone Pi's extension bus or JSONL format just to claim parity.

The normal embedded migration is one reusable `Agent`, `Coder` or a smaller capability composition, application services in typed dependencies, an application-owned message/session store, and a thin adapter at the existing RPC or UI boundary.

Apply high-risk gates

• `ctx`, project trust, credentials, session managers, and service handles are trusted host context. Put equivalents in typed dependencies or application services, never model-chosen tool arguments.
• Pi session JSONL is an append-only branching host log containing more than model context. `result.all_messages()` preserves model history, not tree navigation, labels, extension entries, compaction records, model changes, queues, or abandoned branches. Choose and test conversion, a compatibility store, or an accepted fresh start.
• Pi compaction, context interception, steering/follow-up queues, retries, and branch summaries have specific timing. Select matching core/Harness seams independently and test ordering; generic message history or summarization is not automatic parity.
• Map `tool_call` permission gates by effect. Use guardrails for validation/block/redaction and deferred tools for an action that must await approval. Keep identity, authorization, UI, audit, persistence,