Pi Coding Agent

Pi SDK: Under the Hood

Comprehensive technical documentation for building sandboxed autonomous agent workflows with the @earendil-works/pi-coding-agent, @earendil-works/pi-agent-core, and @earendil-works/pi-ai SDK packages.

Documentation Map

🎓 Tutorial: Build Your First Autonomous Agent

We are going to build a headless agent that sends a prompt to an LLM, streams the response token-by-token, executes tool calls, and logs every lifecycle event to a JSONL file. By the end, you will have a working autonomous agent script you can extend for any sandboxed workflow.

Prerequisites

We will use the following:

• Node.js 20+
• TypeScript with ESM ("type": "module" in package.json)
• An API key for a supported provider (we will use Google Gemini)

Step 1: Set up the project

Create a new directory and initialize it.

mkdir pi-agent-sandbox && cd pi-agent-sandbox
npm init -y
npm install @earendil-works/pi-coding-agent @earendil-works/pi-ai

Add "type": "module" to your package.json. We will write our agent in index.ts.

Step 2: Import the SDK primitives

Open index.ts. We need four things from the SDK: credential storage, a model registry, a session manager, and the session factory.

import {
  AuthStorage,
  createAgentSession,
  ModelRegistry,
  SessionManager,
} from "@earendil-works/pi-coding-agent";
import { getModel } from "@earendil-works/pi-ai";

Notice that we import getModel from pi-ai — this is the model catalog. Everything else comes from pi-coding-agent, which is the orchestration layer.

Step 3: Initialize the runtime

We need to set up the credential pipeline and select a model. AuthStorage manages API keys, and ModelRegistry resolves them at call time.

const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);
const model = getModel("google", "gemini-3-flash-preview");

Now we create the session. SessionManager.inMemory() gives us a session that lives only in process memory — no files on disk, perfect for ephemeral sandbox runs.

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
  model,
});

The createAgentSession factory returns an object containing the session (an AgentSession instance). This is the primary handle for all agent operations.

Step 4: Subscribe to lifecycle events

Before we send a prompt, we subscribe to the event stream. This is how we observe everything the agent does.

import { appendFile } from "node:fs/promises";
import { mkdirSync, existsSync } from "node:fs";

const logsDir = "./logs";
if (!existsSync(logsDir)) mkdirSync(logsDir);

session.subscribe(async (event) => {
  // Log every event to a JSONL file
  await appendFile(
    `${logsDir}/${session.sessionId}.jsonl`,
    JSON.stringify(event) + "\n"
  );

  // Stream text deltas to stdout
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

Every agent event flows through this subscription — agent_start, turn_start, message_start, message_update, tool_execution_start, tool_execution_end, turn_end, agent_end. We will explore these in detail in the Explanation: Agent Lifecycle section.

Step 5: Send a prompt

await session.prompt("List the files in the current directory and describe what you see.");
console.log("\n--- Agent finished ---");

Run it:

npx tsx index.ts

You will see the LLM response streaming to your terminal. If the agent has tools enabled (it does by default — bash, read, edit, write, grep, find, ls), it will execute an ls or bash command and describe the output.

Step 6: Inspect the log

Open the JSONL file in ./logs/. Each line is a single AgentEvent. You will see the full lifecycle: the agent started, a turn began, the LLM generated a message with tool calls, the tools executed, and the agent ended.

Congratulations. You now have a functioning autonomous agent. The next sections show you how to sandbox it, steer it mid-run, and extend it with custom tools.

🔧 How-to Guides

How to Build a Sandboxed Agent Pipeline

Restrict the working directory

To confine all file operations to a specific directory, set the cwd option. All built-in tools (bash, read, edit, write, grep, find, ls) resolve paths relative to this directory.

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
  model,
  cwd: "/tmp/sandbox-workspace",
});

Restrict the tool set

To limit which tools the agent can use, pass tools or readOnlyTools:

import { createReadOnlyTools } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
  model,
  cwd: "/tmp/sandbox-workspace",
  readOnlyTools: true,  // Only read, grep, find, ls — no bash, edit, write
});

For fine-grained control, provide explicit customTools:

import { createToolDefinition } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession({
  // ...
  customTools: [
    createToolDefinition("read", "/tmp/sandbox-workspace"),
    createToolDefinition("grep", "/tmp/sandbox-workspace"),
  ],
});

Use file-backed sessions for persistence

Replace SessionManager.inMemory() with a file-backed session to persist conversation state across process restarts:

const sessionManager = SessionManager.create("/path/to/sessions-dir");

const { session } = await createAgentSession({
  sessionManager,
  // ...
});

The session manager writes an append-only JSONL file. On restart, it replays entries to reconstruct state.

Inject a custom system prompt

const { session } = await createAgentSession({
  // ...
  systemPrompt: "You are a security auditor. Only analyze code for vulnerabilities.",
  appendSystemPrompt: ["Never execute destructive commands."],
});

systemPrompt replaces the default. appendSystemPrompt adds additional rules after the default system prompt.

How to Steer and Follow Up During a Run

Steer the agent mid-turn

Steering messages are injected after the current assistant turn finishes, before the next LLM call. Use this to redirect the agent while it is working.

// While the agent is streaming...
session.steer("Focus on the authentication module, not the UI.");

Queue a follow-up

Follow-up messages are delivered only after the agent would otherwise stop (no more tool calls, no steering messages). Use this for chained tasks.

session.followUp("Now write unit tests for the code you just created.");

Control queue draining

By default, all queued messages drain at once. To process them one at a time:

session.steeringMode = "one-at-a-time";
session.followUpMode = "one-at-a-time";

Abort a running agent

session.abort();

This sends an abort signal to the active run. Tool executions receive the signal and should terminate gracefully. The agent emits agent_end after abort.

Wait for the agent to finish

await session.waitForIdle();
// Safe to read state, send new prompts, or shut down

How to Register Custom Tools and Extensions

Register a tool via extension factory

If using createAgentSession with extensions enabled, provide an ExtensionFactory:

import { Type } from "typebox";
import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";

const myExtension: ExtensionFactory = (pi) => {
  pi.registerTool({
    name: "count_lines",
    label: "Count Lines",
    description: "Counts lines in a file",
    parameters: Type.Object({
      filePath: Type.String({ description: "Path to the file" }),
    }),
    async execute(toolCallId, params, signal) {
      const { execSync } = await import("node:child_process");
      const count = execSync(`wc -l < "${params.filePath}"`)
        .toString()
        .trim();
      return {
        content: [{ type: "text", text: `${count} lines` }],
        details: { lineCount: parseInt(count) },
      };
    },
  });
};

Hook into lifecycle events

const auditExtension: ExtensionFactory = (pi) => {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command.includes("rm ")) {
      return { block: true, reason: "Destructive commands are blocked." };
    }
  });

  pi.on("agent_end", async (event, ctx) => {
    console.log(`Agent completed. ${event.messages.length} messages produced.`);
  });
};

Send messages from extensions

const notifierExtension: ExtensionFactory = (pi) => {
  pi.on("tool_execution_end", async (event, ctx) => {
    if (event.isError) {
      pi.sendMessage({
        customType: "error_notification",
        content: `Tool ${event.toolName} failed.`,
        display: `⚠️ ${event.toolName} error`,
      });
    }
  });
};

📖 Reference

Core API Reference

createAgentSession(options)

Factory function. Returns { session: AgentSession }.

AgentSession

Primary interface for controlling the agent. Extends Agent from @earendil-works/pi-agent-core.

Properties

Methods

Queue Modes

AgentState

AgentEvent (Union)

Events emitted by Agent.subscribe().

SessionManager

Manages append-only conversation history as a tree of entries.

Static Constructors

Key Methods

Entry Types

AgentSessionRuntime

Orchestrates session transitions and CWD-bound services.

ModelRegistry

Resolves API keys and manages provider configurations.

AuthStorage

Persistent credential storage.

SettingsManager

Manages global and project-level settings.

Key settings categories: compaction, retry, transport, thinking budgets, terminal display, model filtering, shell configuration.

Extension System Reference

ExtensionFactory

type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;

A factory function that receives the ExtensionAPI and registers handlers, tools, commands, and shortcuts.

ExtensionAPI

The registration surface available inside ExtensionFactory.

Event Registration

pi.on(eventName, handler)

Tool Registration

pi.registerTool(toolDefinition)

Command & Shortcut Registration

pi.registerCommand(name, { description?, handler, getArgumentCompletions? })
pi.registerShortcut(keyId, { description?, handler })
pi.registerFlag(name, { description?, type, default? })

Messaging

pi.sendMessage(message, options?)    // Custom message
pi.sendUserMessage(content, options?) // User message (triggers turn)
pi.appendEntry(customType, data?)     // Persistence-only entry

Provider Registration

pi.registerProvider(name, config)
pi.unregisterProvider(name)

State Queries

pi.getFlag(name)              // Get CLI flag value
pi.getActiveTools()           // Get active tool names
pi.getAllTools()               // Get all tools with metadata
pi.setActiveTools(toolNames)  // Set active tools
pi.getCommands()              // Get slash commands
pi.setModel(model)            // Set current model
pi.getThinkingLevel()         // Get thinking level
pi.setThinkingLevel(level)    // Set thinking level

ExtensionContext

Context passed to event handlers. Provides read access to session state and control methods.

ToolDefinition<TParams, TDetails, TState>

Schema for registering a custom LLM-callable tool.

AgentToolResult<T>

Return value from tool execution.

Tool System Reference

Built-in Tools

Tool Factory Functions

Tool Execution Modes

AgentLoopConfig Hooks

ResourceLoader / DefaultResourceLoader

Loads extensions, skills, prompt templates, themes, and project context files.

💡 Explanation

Explanation: The Agent Lifecycle

What happens when you call session.prompt()?

Because the Pi SDK is designed for autonomous operation, understanding the lifecycle is essential for building predictable, debuggable pipelines. The lifecycle is not a simple request-response — it is a multi-turn loop with interleaving tool execution, steering injection, and follow-up continuation.

flowchart TD
    A["prompt()"] --> B["agent_start"]
    B --> C["turn_start"]
    C --> D["LLM Call"]
    D --> E["message_start → message_update* → message_end"]
    E --> F{"Tool calls?"}
    F -->|Yes| G["tool_execution_start → tool_execution_end"]
    G --> H["turn_end"]
    H --> I{"shouldStopAfterTurn?"}
    I -->|Yes| J["agent_end"]
    I -->|No| K{"Steering messages?"}
    K -->|Yes| L["Inject steering → turn_start"]
    L --> D
    K -->|No| M{"Follow-up messages?"}
    M -->|Yes| N["Inject follow-up → turn_start"]
    N --> D
    M -->|No| J
    F -->|No| H

The turn loop

A single prompt() call can produce multiple turns. Each turn consists of one LLM call and zero or more tool executions. The agent continues looping until one of three exit conditions is met:

1. Natural stop: The LLM produces a response with no tool calls, and no messages are queued.
2. Graceful stop: shouldStopAfterTurn returns true.
3. Abort: The abort signal is triggered via session.abort().

Tool execution within a turn

When the LLM response contains tool calls, they are executed according to the toolExecution mode:

• Parallel (default): Tool calls are prepared sequentially (for argument validation and beforeToolCall hooks), then executed concurrently. Results are emitted in completion order for tool_execution_end, but tool-result messages are assembled back in the original assistant source order for the next LLM context.
• Sequential: Tool calls are fully processed one at a time.

Individual tools can override this via their executionMode field. A tool marked "sequential" in a parallel batch causes the entire batch to fall back to sequential mode.

Steering vs. follow-up: the two queues

The agent maintains two distinct message queues, and the distinction is critical for autonomous workflows:

• Steering queue: Drained between turns. If the agent just finished a turn and there are steering messages, they are injected into the context and the agent starts a new LLM call immediately. This is for redirecting the agent while it works.
• Follow-up queue: Drained only when the agent would otherwise stop. If there are no tool calls and no steering messages, the follow-up queue is checked. This is for chaining sequential tasks.

Both queues support "all" mode (drain everything at once) and "one-at-a-time" mode (drain one message, then re-enter the turn loop).

Event emission order

For a typical multi-tool turn, the precise emission order is:

agent_start
  turn_start
    message_start (assistant)
    message_update* (streaming deltas)
    message_end (assistant)
    tool_execution_start (tool A)
    tool_execution_start (tool B)   // parallel mode
    tool_execution_end (whichever finishes first)
    tool_execution_end (the other)
  turn_end
  // steering check → follow-up check
  turn_start   // if messages queued
    ...
  turn_end
agent_end

The agent_end contract

agent_end is always the last event. However, the agent does not become idle until all awaited agent_end listeners have settled. This means a subscriber can perform async cleanup in its agent_end handler and the caller's await session.prompt() or await session.waitForIdle() will wait for it.

Explanation: Session Tree & Persistence

Why sessions are trees, not arrays

A naive conversation store would be a flat array of messages. The Pi SDK uses a tree for a reason: it enables branching. When a user (or an autonomous agent) realizes a conversation path was wrong, they can fork from any earlier point without losing the original history.

Each session entry has a unique ID and a parent ID. The "current conversation" is always a linear path from the root to the current leaf. Branching creates a sibling entry that starts a new path.

graph TD
    A["Root"] --> B["User: Analyze this file"]
    B --> C["Assistant: I see a bug in line 42"]
    C --> D["User: Fix it"]
    C --> E["User: Actually, focus on tests"]
    D --> F["Assistant: Fixed"]
    E --> G["Assistant: Writing tests..."]

In this tree, entries D/F and E/G are separate branches from the same parent C. The session manager tracks which leaf is active.

JSONL: the append-only format

Session files are JSONL (one JSON object per line). Every mutation is an append — entries are never modified or deleted. This makes the format:

1. Crash-safe: A partial write corrupts at most the last line.
2. Streamable: Entries can be tailed in real time.
3. Auditable: The full history is always available.

On load, the session manager replays all entries to reconstruct the tree in memory.

Context compaction

As conversations grow, they exceed the model's context window. The compaction system addresses this:

1. The session_before_compact event fires, giving extensions a chance to cancel or provide custom compaction.
2. Old messages are summarized into a single CompactionEntry.
3. The summary replaces the old messages in the active branch's context, but the original entries remain in the JSONL file.

Extensions can control compaction via settings: reserveTokens (how many tokens to keep free), keepRecentTokens (how many recent tokens to preserve verbatim).

Branch summaries

When navigating from one branch to another, the session can optionally produce a BranchSummaryEntry — a summary of the branch being left. This preserves context without carrying the full history into the new branch.

Explanation: The Three-Package Stack

Why three packages?

The SDK is split into three NPM packages, each at a different abstraction level. Understanding this layering is essential for knowing which imports to use and where extension points live.

graph BT
    A["@earendil-works/pi-ai<br/><i>Model catalog, message protocol, streaming</i>"] --> B["@earendil-works/pi-agent-core<br/><i>Agent loop, state, events, tool execution</i>"]
    B --> C["@earendil-works/pi-coding-agent<br/><i>Session orchestration, tools, extensions, persistence</i>"]

@earendil-works/pi-ai — The foundation

This is the model-agnostic abstraction layer. It defines:

• Model<Api>: A model instance with provider, ID, context window size, cost, and capabilities.
• Message: The union of UserMessage, AssistantMessage, and ToolResultMessage — the canonical LLM message protocol.
• AssistantMessageEvent: Streaming events (text_delta, thinking_delta, tool_call_start, etc.).
• streamSimple: The low-level function that sends a context to a provider and returns an event stream.
• getModel(provider, id): Model catalog lookup.

This package knows nothing about agents, sessions, or tools. It is pure model interaction.

@earendil-works/pi-agent-core — The agent loop

This package adds autonomous behavior on top of pi-ai:

• Agent: The stateful wrapper that owns the transcript, executes tools, and emits lifecycle events.
• agentLoop / agentLoopContinue: The low-level loop that drives the LLM → tools → LLM cycle.
• AgentTool: The tool interface with execute(), parameter schemas, and execution mode.
• AgentEvent: The event union (agent_start, turn_start, message_update, tool_execution_end, etc.).
• Steering and follow-up queues: The two-queue message injection system.

This package has no concept of sessions, files, or extensions. It is a pure in-memory agent runtime.

@earendil-works/pi-coding-agent — The orchestration layer

This is the package you import in application code. It composes the lower layers into a complete system:

• createAgentSession: The factory that wires everything together — model registry, session manager, tools, extensions.
• AgentSession: Extends Agent with session management, model cycling, and runtime services.
• AgentSessionRuntime: Manages session transitions (switch, fork, new) and CWD-bound services.
• SessionManager: The append-only tree persistence layer.
• ExtensionRunner / ExtensionAPI: The extension system that allows dynamic tool registration, event hooks, and command definitions.
• Built-in tools: bash, read, edit, write, grep, find, ls — all CWD-scoped.
• ResourceLoader: Discovers and loads extensions, skills, prompts, and themes from the filesystem.
• SettingsManager: Global and project-level configuration.

The data flow

When session.prompt("Fix the bug") is called:

1. pi-coding-agent assembles the system prompt (from settings, skills, context files), converts the prompt string to an AgentMessage, and passes it to the Agent.
2. pi-agent-core enters the agent loop: it calls convertToLlm to transform AgentMessage[] to Message[], then invokes streamSimple.
3. pi-ai sends the HTTP request to the provider, streams back AssistantMessageEvent deltas.
4. pi-agent-core assembles the deltas into an AssistantMessage. If it contains tool calls, it executes them via AgentTool.execute().
5. pi-coding-agent provides the tool implementations (bash runs a shell command, read opens a file, etc.), fires extension events (tool_call, tool_result), and persists everything via SessionManager.
6. Control returns to step 2 for the next turn, or the loop exits.

This layering means you can use pi-ai alone for simple model calls, pi-agent-core for custom agent loops without the coding-agent opinion, or pi-coding-agent for the full batteries-included experience.