earendil-works/pi

The agent loop lives in packages/agent/ — a single-threaded, turn-based loop with no separate planner component. Single loop, no planner. The runLoop() function in packages/agent/src/agent-loop.ts (line 163) runs an inner loop processing assistant responses and tool calls, and an outer loop that checks for follow-up messages. There is no planning phase: every turn the model produces a response (text + optional tool calls) and the loop executes them. Tool-call schema. Tools are defined via AgentTool<T> in packages/agent/src/types.ts (line 464) with a name, parameters (typebox schema), execute() function, and optional prepareArguments/beforeToolCall/afterToolCall hooks. Tool calls from the model are validated against their schemas before execution; invalid calls produce error results. Execution can be "parallel" (default — concurrent) or "sequential" — see executeToolCalls() at line 508. Turn structure. Each turn: (1) pending messages (steering/follow-up) are emitted, (2) prepareRequest hook runs, (3) streamAssistantResponse() at line 381 converts AgentMessage[] to Message[] via convertToLlm, calls the LLM stream function, and emits streaming events (start, text_delta, toolcall_start, etc.), (4) any tool calls are executed with results pushed back to context, (5) finishTurn decides continuation. Stop conditions. A turn stops on stopReason === "error" or "aborted" (hard stop, line 245-256). Otherwise, if no tool calls remain, no steering/follow-up messages are queued, and finishTurn doesn't request continuation, the loop ends (line 310-318). Sub-agents. Pi explicitly chooses not to implement sub-agents (README line 19). Instead it supports nested tool calls via ctx.executeTool() in extensions (see packages/coding-agent/src/core/extensions/types.ts line 394), codemode scripts, and MCP tool delegation. Each model request is self-contained; the model may call tools that internally call other tools, but no child agent loops exist.

Pi gathers repo context from multiple sources and uses compaction (LLM-generated summaries) to stay within context windows. System prompt assembly. buildSystemPrompt() in packages/coding-agent/src/core/system-prompt.ts (line 88) constructs the system prompt from multiple sections: tool snippets, tool guidelines, skill descriptions, context files (.claude/ files), and an appendSystemPrompt setting. Context files are read via the resource loader as {path, content} pairs and wrapped in <project_instructions> tags. Tools for context gathering. Pi's built-in tools (read, grep, find, ls, bash) let the model explore the codebase. The read tool (packages/coding-agent/src/core/tools/read.ts) supports path, offset, and limit params. The grep tool provides regex search. Files are truncated to DEFAULT_MAX_BYTES / DEFAULT_MAX_LINES to avoid overflow. Compaction (summarization). When the estimated context tokens exceed contextWindow - reserveTokens (default 16k reserve), shouldCompact() in packages/coding-agent/src/core/compaction/compaction.ts (line 267) triggers compaction. The algorithm walks session entries from newest to oldest, accumulating tokens until keepRecentTokens (default 20k) are kept, then generates an LLM summary of the older conversation (line 645, generateSummary()). The summary uses a structured format (Goal, Progress, Key Decisions, Next Steps, Critical Context) and is inserted as a compactionSummary message in the session. After compaction, the older messages are hidden from the LLM context but remain in the session tree. No embeddings or vector store. Pi has no embeddings or RAG. All context comes from the system prompt, tool results, and conversation history. Context transform hook. Extensions can inject/modify context via the transformContext hook (defined in AgentLoopConfig, packages/agent/src/agent-loop.ts line 390), and Pi's session uses this to apply hidden tool declarations and forced prompts. Context overflow recovery. isContextOverflow() from the AI package detects when the provider rejects a request as too large; Pi then triggers _compactBeforeNextAssistantResponse() (packages/coding-agent/src/core/agent-session.ts around line 776) and retries.

Pi provides two file-editing tools — edit and write — plus a file-mutation-queue for concurrency safety. Edit tool (exact search/replace). The edit tool in packages/coding-agent/src/core/tools/edit.ts uses an edits array of {oldText, newText} pairs. Edits are matched against the original file content, not incrementally, and overlapping edits are rejected. Matching is exact by default but falls back to fuzzy matching (edit-diff.ts line 207): Unicode normalization (smart quotes to ASCII, dashes to hyphens, spaces normalized) and trailing-whitespace stripping. The original file is read, the BOM is stripped, line endings are detected, content is normalized to LF, edits are applied, and native line endings are restored before writing. A unified diff and display diff with line numbers are returned in the result. Write tool (whole file). The write tool (packages/coding-agent/src/core/tools/write.ts) creates or overwrites a file, auto-creating parent directories. It uses a simple {path, content} schema. Validation. Tools use typebox schemas for argument validation (e.g., editSchema at line 32 of edit.ts). The validateToolArguments() function from @earendil-works/pi-ai rejects invalid arguments before execution. Truncated responses with stopReason === "length" have all tool calls failed immediately (agent-loop.ts line 267) because their arguments may be incomplete. No linter or test runners. Pi does not automatically run linters or tests after edits. The model is expected to verify its work via bash commands. Git integration. Pi does not auto-commit or branch before edits. The hosted-git-info package is a dependency for repository detection, but git operations are manual via bash. File mutation queue. Both edit and write tools use withFileMutationQueue() in packages/coding-agent/src/core/tools/file-mutation-queue.ts (referenced at edit.ts line 163) to serialize operations on the same file, preventing concurrent edits from different tool calls from racing. Pluggable operations. Both tools accept custom ReadOperations/EditOperations/WriteOperations interfaces, so file editing can be delegated (e.g., to SSH or containers).

Pi explicitly states it "does not include a built-in permission system" (README line 90). Safety is provided through extensible checkpoints rather than built-in sandboxing. No built-in permission manager. By default, the bash tool (packages/coding-agent/src/core/tools/bash.ts) spawns child processes via spawn() with the same OS-level permissions as the Pi process. The filesystem tools (read, write, edit, grep, find) all operate with the process's user permissions. There is no allow/deny list, container, or landlock built in. Pluggable tool operations. Every built-in tool (bash, read, write, edit, grep, find, ls, powershell) defines an Operations interface (e.g., BashOperations at bash.ts line 75, EditOperations at edit.ts line 83). These can be overridden to delegate execution to remote systems, containers, or sandboxes. Containerization patterns are documented in packages/coding-agent/docs/containerization.md: (1) plain Docker runs the whole Pi process in a container, (2) Docker Sandboxes uses managed sandbox with credential proxy, (3) OpenShell provides policy-controlled sandboxes, (4) the Gondolin extension routes built-in tools into a local Linux micro-VM while keeping Pi and provider auth on the host. Abort signals. All tools accept an AbortSignal and check signal.aborted between operations, enabling responsive cancellation of long-running commands. The bash tool also kills the process tree on abort. Tool execution hooks. beforeToolCall and afterToolCall hooks (packages/agent/src/types.ts lines 66-104) allow extensions to block, modify, or monitor tool execution — effectively a permission callback. Bash output truncation. The bash executor (packages/coding-agent/src/core/bash-executor.ts) truncates output beyond DEFAULT_MAX_BYTES and writes full output to a temp file, preventing context overflow. Binary output is sanitized via sanitizeBinaryOutput(). Project trust. packages/coding-agent/src/core/project-trust.ts gates whether project-level settings and MCP server configurations are loaded, preventing untrusted projects from injecting tool configurations.

Pi supports many providers through the @earendil-works/pi-ai package. Providers. The AI package at packages/ai/src/ has provider implementations for Anthropic (anthropic-messages.ts), OpenAI (openai-completions.ts, openai-responses.ts), Google (google-generative-ai.ts), Mistral (mistral-conversations.ts), Bedrock (bedrock-converse-stream.ts), Azure OpenAI (azure-openai-responses.ts), Cloudflare Workers AI, llama.cpp, and a generic pi-messages.ts proxy. Each provider implements a streamSimple() function matching the StreamFn signature. Model catalog. Models are defined in a generated models.generated.ts and in model-catalog.ts, organized by provider with metadata (context window, cost, reasoning support, input types). The ModelRuntime class in packages/coding-agent/src/core/model-runtime.ts orchestrates providers, credentials, and model refresh. Local models. Pi directly integrates with llama.cpp via the router (/llama command). Compatible endpoints (Ollama, vLLM, SGLang, LM Studio) can be configured via models.json using existing API adapters (e.g., "api": "openai-completions"). Tool-calling vs text formats. Pi uses native tool-calling (function/tool schema) with all providers that support it. The constrainedSampling config on tools (edit.ts line 156) requests JSON Schema-guided generation when the provider supports it. For providers without native tool support, tools can be serialized as text instructions. Per-model prompt tuning. Tools contribute promptSnippet and promptGuidelines (e.g., editToolSystemPromptContribution at edit.ts line 43) that feed into the system prompt per active tool, allowing the model-specific prompt to be tuned. Cost tracking. Every assistant message carries a usage object with token counts and cost (packages/agent/src/agent.ts line 48-55). The usage-totals.ts module aggregates costs across the session. Default model IDs per provider are in model-resolver.ts (e.g., claude-opus-4-8, gpt-5.5, gemini-3.1-pro-preview).

Pi has four major extension mechanisms: Extensions (TypeScript). Extensions are TypeScript modules that export a default factory receiving ExtensionAPI (see docs at packages/coding-agent/docs/extensions.md and types at packages/coding-agent/src/core/extensions/types.ts). They can registerTool() (line 1634), registerCommand() (line 1643), registerProvider() (line 1821), registerMcpServer() (line 1857), subscribe to lifecycle events via pi.on(), send messages, and access UI. Extensions run inside the Pi process and can inspect all state. Reload support means they can be hot-replaced. MCP Protocol. Pi connects to MCP servers over stdio or streamable HTTP (packages/coding-agent/docs/mcp.md). Tools from MCP servers are surfaced to the model as mcp__<server>__<tool> with configurable exposure (direct, deferred, codemode, hidden). Resource tools (read_mcp_resource, list_mcp_resources) are also available. Skills. Per the Agent Skills specification, skills are directories with SKILD.md files. Pi scans configured skill locations and adds name/description to the system prompt; full instructions load on demand when the model invokes them. Pi Packages. Bundles of extensions, skills, prompt templates, themes, and context files distributed via npm or git (packages/coding-agent/docs/packages.md). Config/Instruction files. Pi reads settings.json for tool config, models.json for custom provider endpoints, mcp.json for MCP servers, and context files (.claude/ directory) as project instructions. Headless/SDK use. The @earendil-works/pi-coding-agent package exports a TypeScript SDK (packages/coding-agent/src/core/sdk.ts). The CreateAgentSessionOptions interface (line 48) allows programmatic session creation with custom tools, models, and configuration. There's also RPC mode accepting JSONL commands on stdin/stdout, JSON mode, and print mode. Prompt templates allow reusable message text expansion. Themes customize terminal colors.