pi examples on Programmer.ie: Modern AI programming

Watch the agent loop call a tool

Mon, 01 Jan 0001 00:00:00 +0000

You can observe the loop without credentials. The provider scripts the assistant’s responses; the real Agent executes the tool and emits the events. This proves orchestration, not a real model’s choice of tool or interpretation of its result.

Run it

Use Node.js 22.18 or later with built-in TypeScript stripping. In an empty folder:

npm init -y
npm pkg set type=module
npm install @earendil-works/pi-agent-core@1.0.4 @earendil-works/pi-ai@1.0.4

npm init -y
npm pkg set type=module
npm install @earendil-works/pi-agent-core@1.0.4 @earendil-works/pi-ai@1.0.4

Save the complete file below as agent-core.ts, then run node agent-core.ts. It is an exact copy of the book’s canonical example, not a replacement harness.

Resolve a provider credential in precedence order

Mon, 01 Jan 0001 00:00:00 +0000

Pi resolves a provider credential from four sources and uses the first one that yields a value: a runtime API key, a stored auth.json credential, an apiKey in models.json, then the provider’s environment variable. This is a configuration and decision-table walkthrough of the Chapter 3 tests; every key below is a placeholder, and it resolves no real credential.

The four sources, in order

Order	Source	Where it comes from
1	runtime key	`--api-key`, or a runtime API call
2	stored credential	`<agent-dir>/auth.json`
3	model key	`apiKey` on the provider in `<agent-dir>/models.json`
4	environment	the provider’s environment variable

The order surprises people: a key in models.json sits below a stored credential, not above it. It exists to give a custom or self-hosted model its key; it does not override a key you already logged in with.

Calculate a context budget

Mon, 01 Jan 0001 00:00:00 +0000

The compaction reference pinned to Pi 1.0.4 documents the trigger as contextTokens > contextWindow - reserveTokens; the default reserve is 16,384. The Chapter 4 tests use a scripted model with a 100,000-token window. These are the inputs below: the window is a test model’s capacity, not every provider’s.

Copy the calculation

Save this educational calculation as budget.py and run python budget.py. It evaluates the documented inequality; it does not call or imitate Pi’s compaction implementation.

Read a session file and its tree

Mon, 01 Jan 0001 00:00:00 +0000

A persistent Pi session is a plain JSONL file you can open in any editor. The first line is a header, every later line is a tree entry with an id and a parentId, and the model only ever sees the active branch. This is an illustrative trace plus a directory-name calculation, grounded in the Chapter 5 tests; it is a drawing of the shape, not a transcript from your machine.

See which tools Pi declares to the model

Mon, 01 Jan 0001 00:00:00 +0000

Pi declares an active tool set to the model; that set is what the model may ask for. Three inputs compose it: built-in tools, tools registered by extensions, and MCP tools. defaultTools edits the user’s selection, --tools replaces it for one invocation, and the same syntax means different things in the two places.

The default selection and its two edits

settings.md defaults defaultTools to read, bash, edit, and write. Within a settings list a plain name replaces the selection, +name adds, and -name removes, in order:

Merge user and project settings

Mon, 01 Jan 0001 00:00:00 +0000

Pi merges two files: user-level <agent-dir>/settings.json and, after you trust the project, <project>/.pi/settings.json. Scalars follow ordinary override, but defaultTools has its own rule, and an untrusted project’s settings are not read at all. The fragments below are small illustrative settings; the Chapter 7 tests assert each result on real files.

Scalar settings: project wins

User file:

{
  "compaction": { "reserveTokens": 1000, "keepRecentTokens": 5000 }
}

{
  "compaction": { "reserveTokens": 1000, "keepRecentTokens": 5000 }
}

Project .pi/settings.json:

Decide whether to trust a project

Mon, 01 Jan 0001 00:00:00 +0000

Pi asks a project-trust question only when the working directory holds something that would load, and the answer decides which protected resources load. The order is command-line flag, then a project_trust extension, then a saved decision, then defaultProjectTrust. Context files such as AGENTS.md are not a trigger and load either way. This is a decision-table walkthrough of the Chapter 8 tests.

What triggers a decision

Present from the working directory	Decision required
`.pi/settings.json`	yes
`.pi/mcp.json`	yes
`.pi/extensions`, `.pi/skills`, `.pi/prompts`, `.pi/themes`	yes
`.pi/SYSTEM.md`, `.pi/APPEND_SYSTEM.md`	yes
`.agents/skills` in this or an ancestor directory	yes
a bare `.pi` directory	no
`AGENTS.md` or `CLAUDE.md`	no — a context file

Trust is requested because something would load, not merely because .pi exists. A context file carries instructions and arrives regardless of the answer, which is why declining trust does not stop it.

Inspect the shell prefix and session environment

Mon, 01 Jan 0001 00:00:00 +0000

Use Pi 1.0.4 and its built-in Bash tool. You will compare the model’s command with your own ! command. The configuration and manual commands below are an educational adaptation of the existing Chapter 9 tests; the tests remain the canonical executable evidence.

Configure a visible prefix

Merge this fragment into <project>/.pi/settings.json, then run /reload:

{
  "shellCommandPrefix": "export FROM_PREFIX=yes"
}

{
  "shellCommandPrefix": "export FROM_PREFIX=yes"
}

Pi prepends this prefix to both its built-in bash tool and user-entered ! or !! commands. It runs again before every command. On native Windows, use Git Bash; if needed set shellPath to C:\Program Files\Git\bin\bash.exe with escaped backslashes in JSON. Do not set it to an interactive profile.

Decide which Pi mechanism a requirement needs

Mon, 01 Jan 0001 00:00:00 +0000

Two requirements that sound alike are different kinds of requirement. “Confirm before anything under migrations/” asks a person. “No force pushes” must hold whether or not a person is there to be asked. Only an extension can act on a tool call before it runs, so both belong in one tool_call handler — but they need different code.

Run it

Use Pi 1.0.4 and one of the example repository’s test runners. The file below is the chapter’s canonical extension, reproduced exactly:

Turn a Markdown file into a /review command

Mon, 01 Jan 0001 00:00:00 +0000

The /review from chapter 11 is a four-line Markdown file. This page writes the smallest prompt template that matters, expands it for a bare /review and for one argument, and then shows the two ordering rules behind “my template does not expand”. This is documented Pi 1.0.4 behaviour, confirmed by a session test.

Write the template

Save this as ~/.pi/agent/prompts/review.md (or <project>/.pi/prompts/review.md), then run /reload in an active session. It is the chapter’s template, unescaped for readability:

Advertise a skill by description, load the body on demand

Mon, 01 Jan 0001 00:00:00 +0000

A prompt template waits until you type it. A skill begins when Pi recognises the kind of task. The whole mechanism turns on one field: the system prompt carries every skill’s name, description and path, never the body, so the description is the entire routing surface. This page writes a SKILL.md and shows exactly what the model is told.

Write the skill

A skill is a directory containing SKILL.md:

review-guard/
└── SKILL.md

review-guard/
└── SKILL.md

---
name: review-guard
description: Reviews changed code against this repository's conventions and runs its own checks. Use when reviewing a diff, a pull request, or uncommitted changes.
---

# Review guard

1. Run `scripts/run-checks.sh` and read the output before reviewing anything.
2. Read `references/checklist.md` and apply it to the diff.
3. Report findings ordered by severity, each with a file path.

---
name: review-guard
description: Reviews changed code against this repository's conventions and runs its own checks. Use when reviewing a diff, a pull request, or uncommitted changes.
---

# Review guard

1. Run `scripts/run-checks.sh` and read the output before reviewing anything.
2. Read `references/checklist.md` and apply it to the diff.
3. Report findings ordered by severity, each with a file path.

Place it in your user or project skills directory and run Pi from a location where it is discoverable. The description states both what the skill does and when it applies; “Reviews code” gives the model nothing to match against “implement this”, while the text above does.

Give a skill files and a check script it can run

Mon, 01 Jan 0001 00:00:00 +0000

The review guard’s checklist is forty items; inlining it in SKILL.md would load all forty every time the skill fires. Bundle it as a file the body names instead. A bundled file is a file on disk — it reaches the context only when the model reads it with its own tool. The bundled script in this example needs a POSIX shell, so on Windows run it under Git Bash.

Register a tool and a command from an extension

Mon, 01 Jan 0001 00:00:00 +0000

An extension is a TypeScript module whose default export receives ExtensionAPI. Registering a tool makes it active and declared to the model, while registering a command adds a / command beside the built-ins. This page loads both the smallest command extension and the running example’s review_scope tool; the only substitution is the model, a faux provider replaying a script.

Run it

Pi 1.0.4 loads local TypeScript with jiti, so there is no build step. The command extension below is the whole file, reproduced exactly:

Block a force push with a tool_call handler

Mon, 01 Jan 0001 00:00:00 +0000

A tool_call handler runs before the tool it names, so it can refuse the call. The guard on this page blocks destructive git commands — force pushes, reset --hard, and git clean -f — and when there is no UI to ask, it refuses rather than allowing silently. The cases run through a faux provider in a real session, so you see the guard, not a real model.

Run it

The guard is the whole file, reproduced exactly:

Return structured tool results and route nested calls

Mon, 01 Jan 0001 00:00:00 +0000

A tool that executes returns data as well as text: a machine-readable structuredContent for scripts alongside the content the model reads. This page’s tools declare risk with annotations and run one another through ctx.executeTool(), and those nested calls pass through the same tool_call gate as model-issued calls. The behaviour below is observed through a real session; the model is a faux provider replaying a script.

Run it

A non-zero exit is a result, not a failed tool: runCommand in tools.ts catches exec’s rejection and returns the exit code as data. When the result is data, declare an outputSchema and return a matching structuredContent; the caller below reads the value back from outcome.result. Annotations are hints a permission extension can read — with no hints, needsApproval is true (approval.ts):

Make what the model knows follow the active tools

Mon, 01 Jan 0001 00:00:00 +0000

Registering run_checks has not told the model it exists. This example derives prompt guidance from pi.getActiveTools() and bounds a settle guard to a single nudge — all observed over a scripted model, not a real one.

Run it

Use Pi 1.0.4 with the example repository’s test runner. These are excerpts of the canonical extensions:

	pi.on("before_agent_start", (event) => {
		// getActiveTools(), not getAllTools(). getAllTools() reports every
		// *registered* tool, so a tool the session disabled would still be
		// described here — and the model would be told to use something it
		// cannot call. The active set is what is declared to the model.
		const active = pi.getActiveTools();
		if (!active.includes("run_checks")) {
			// Delete rather than leave stale: a section written for a previous
			// turn outlives the condition that produced it.
			delete event.systemPromptOptions.sections.review_guard;
			return;
		}

		event.systemPromptOptions.sections.review_guard =
			"- `run_checks` runs this repository's type check and unit tests. " +
			"Use it instead of running a command yourself before reporting on a change. " +
			"- Force pushes are blocked by an extension. If a push is refused, do not retry with a different form.";
	});

	pi.on("before_agent_start", (event) => {
		// getActiveTools(), not getAllTools(). getAllTools() reports every
		// *registered* tool, so a tool the session disabled would still be
		// described here — and the model would be told to use something it
		// cannot call. The active set is what is declared to the model.
		const active = pi.getActiveTools();
		if (!active.includes("run_checks")) {
			// Delete rather than leave stale: a section written for a previous
			// turn outlives the condition that produced it.
			delete event.systemPromptOptions.sections.review_guard;
			return;
		}

		event.systemPromptOptions.sections.review_guard =
			"- `run_checks` runs this repository's type check and unit tests. " +
			"Use it instead of running a command yourself before reporting on a change. " +
			"- Force pushes are blocked by an extension. If a push is refused, do not retry with a different form.";
	});

The section tracks the active set, not the registered one: pi.getAllTools() reports every tool the session has defined, so a disabled tool would still be described. The same handler can write a tool_guidance section for the built-in tools, dropping it when nothing matches.

Persist a guard's block count as a session entry

Mon, 01 Jan 0001 00:00:00 +0000

A module-level let dies with the process: /reload and resume both reset it. The fix is to use the durable store Pi already hands you. This example logs every blocked write as a custom session entry that the model never sees, and rebuilds the count from the active branch at session_start and on navigation. The claims are observed over a scripted model and a recording UI.

Run it

Use Pi 1.0.4 and one of the example repository’s test runners. The file below is an excerpt of the chapter’s canonical guard-blocks.ts:

Add a slash command and a custom screen that respect the mode rule

Mon, 01 Jan 0001 00:00:00 +0000

Whether a command can do anything at all depends on its mode: dialogs need ctx.hasUI, custom screens need a real terminal. This example is the smallest /guard command, that two-guard rule, and a column-sized component — all observed on a scripted model.

Run it

Use Pi 1.0.4 and one of the example repository’s test runners. The smallest command is one registration, loaded with pi -e ./guard.ts:

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

export default function (pi: ExtensionAPI) {
	pi.registerCommand("guard", {
		description: "Inspect and configure the path guard",
		handler: async (args, ctx) => {
			ctx.ui.notify(`guard received: "${args}"`, "info");
		},
	});
}

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

export default function (pi: ExtensionAPI) {
	pi.registerCommand("guard", {
		description: "Inspect and configure the path guard",
		handler: async (args, ctx) => {
			ctx.ui.notify(`guard received: "${args}"`, "info");
		},
	});
}

The full command, from guard-ui.ts, branches on the two questions — dialogs work wherever ctx.hasUI is true, and with no UI it says so on the way out:

Gate MCP tools by their full mcp__ name and treat annotations as hints

Mon, 01 Jan 0001 00:00:00 +0000

An MCP server’s tool arrives as mcp__<server>__<tool>, so a tool_call gate keyed on the bare tool name silently lets every remote call through. This example is a deny-list gate that keys on the full name, the registration pair that adds a server for one session, and the difference between annotations a server declares about itself and the exposure that decides whether the model is told the tool exists. Only the far end and the model are faked; naming, exposure and gating are Pi’s.

Ship an extension, skills, and prompts as one Pi package

Mon, 01 Jan 0001 00:00:00 +0000

A Pi package is the distribution unit for everything you have written: an extension, its skills, prompts and themes arrive as one directory or npm package instead of a zip of a .pi folder that breaks on someone else’s machine. There is no standalone code file for this chapter, so this page is a command walkthrough with placeholder names, grounded in what the shipped-binary test asserts.

Install, list, remove

pi install npm:@example/pi-tools@1.0.0              # pinned npm version
pi install git:github.com/example/pi-tools@v1       # cloned, reconciled to the ref
pi install ./local-package                          # loaded from its path; nothing copied
pi list                                             # what resolves, as one instance
pi remove <source>                                  # and its resources stop loading
pi -e npm:@example/pi-tools                         # try one invocation; no settings write
pi install --local ./local-package                  # writes the project's .pi/settings.json

pi install npm:@example/pi-tools@1.0.0              # pinned npm version
pi install git:github.com/example/pi-tools@v1       # cloned, reconciled to the ref
pi install ./local-package                          # loaded from its path; nothing copied
pi list                                             # what resolves, as one instance
pi remove <source>                                  # and its resources stop loading
pi -e npm:@example/pi-tools                         # try one invocation; no settings write
pi install --local ./local-package                  # writes the project's .pi/settings.json

A local install records a path relative to the settings file and copies nothing; --local writes under the project’s .pi and loads only after project trust is granted. Identity by resolved path — a local package by its absolute path, a git package by repository URL without the ref — means the same package listed twice loads once.

Take over compaction summarization

Mon, 01 Jan 0001 00:00:00 +0000

Compaction changes what the next model request is built from, never what the session file holds. On Pi 1.0.4 an extension can supply the summary through session_before_compact while Pi still chooses the cut point; every entry stays in the file, and navigating back before the compaction sends the originals again.

Supply the summary, keep the cut point

An excerpt of custom-summary.ts: it serialises the messages Pi is about to replace, returns them as the summary, and echoes back Pi’s own firstKeptEntryId.

Branch the session tree

Mon, 01 Jan 0001 00:00:00 +0000

A stored session is a tree of entries linked by id and parentId, and the current position is the leaf. /tree moves inside that tree, /fork starts a new session from an earlier prompt, and /clone copies the active branch into a new session. The trace below is illustrative; the claims it draws are the ones branching.test.ts asserts on 1.0.4, with /fork and /clone on the shipped binary.

Choose the command

Action	Result	Use it when
`/tree`	moves within the current session file	related alternatives belong together
`/fork`	new session from an earlier user prompt	the alternative becomes separate work
`/clone`	copy of the active branch in a new session	you want a separate copy of current state

A tiny branch, as entries

The shared history is linear until question B is edited. Submitting the edited prompt creates a sibling — two children of the same parent, one session file. The abandoned branch is not sent, and is not gone:

Steer a run without interrupting it

Mon, 01 Jan 0001 00:00:00 +0000

Typing while Pi works is not an interruption: a steering message enters after the current turn’s tool calls and before the next request, a follow-up waits until the agent would otherwise stop, and Escape aborts and returns your queued text. The walkthrough below mirrors ch25-queue/queue.test.ts on 1.0.4, which queues messages into a real session running a deliberately slow tool with a scripted provider.

The timeline

turn 1   prompt "start"
         the model asks for the slow tool; its tool calls run
         you type steer "change direction"      → queued, not yet readable by the model
turn_end after the last tool result
         next request  system | user:start | assistant | toolResult | user:change direction
turn 2   the model answers the correction
         a follow-up queued earlier is still waiting
agent_settled  nothing left outstanding → the follow-up is finally delivered

turn 1   prompt "start"
         the model asks for the slow tool; its tool calls run
         you type steer "change direction"      → queued, not yet readable by the model
turn_end after the last tool result
         next request  system | user:start | assistant | toolResult | user:change direction
turn 2   the model answers the correction
         a follow-up queued earlier is still waiting
agent_settled  nothing left outstanding → the follow-up is finally delivered

The request shape in the middle is exactly what the test asserts: steering landed after the tool result and before the next prompt (shape() in the test omits the system message). One ordering you cannot guess from the keys: steering drains before follow-ups, even when the follow-up was queued first.

Name the eight message roles

Mon, 01 Jan 0001 00:00:00 +0000

Pi uses the AgentMessage union in SDK state, lifecycle events, RPC responses, and persisted session entries — one type across four surfaces. On 1.0.4 the coding agent extends it with four roles, and applications can add still more by declaration merging. The declaration below reproduces the exported types from ch26-message-types/declared.ts; assert-equal.ts checks those reproductions two ways against the real exports.

The eight roles

Role	What it is for
`system`	the prompt and tool state; later system messages patch it
`user`	a prompt: a string or an array of text/image blocks
`assistant`	content blocks, `usage`, `stopReason`, the three-way model identity
`toolResult`	a tool’s result, joined to its call by `toolCallId`
`bashExecution`	a direct shell command — not an LLM tool result
`custom`	an extension context message, converted to a user message
`branchSummary`	the summary a `branch_summary` entry becomes in context
`compactionSummary`	the summary a `compaction` entry becomes in context

The declaration that carries the caveat

SystemMessage is the role with the book’s most famous mismatch, so it is the one worth showing. An excerpt of the declared reproduction — a declaration, not executable code:

Read a session file with the chapter's program

Mon, 01 Jan 0001 00:00:00 +0000

A Pi session is a JSONL file: one JSON object per line, a session header first, then entries linked by id and parentId. This format is the shared source for the session claims in Chapters 5, 6, 23 and 24 — they reference its declaration rather than redefining it — so a working reader is the most direct way to see what they all mean. Below is Chapter 27’s own reading program on 1.0.4, reproduced exactly.

Separate discovery from admission in the context pipeline

Mon, 01 Jan 0001 00:00:00 +0000

“the model read my AGENTS.md” hides four facts: the file exists, Pi discovered it, something admitted it, and it is in the request the model receives. Each fails on its own and each has a different owner. The excerpts below ran as the Chapter 28 tests against a temporary tree — default loader, no model.

Discovery: a walk up, not a scan down

Starting Pi in repo/src/billing, discovery walks up from the working directory to the agent directory — never sideways or down, so repo/docs/AGENTS.md does not apply to work started in repo/src/billing even though both are in one repository:

Normalise a provider's overflow message so Pi can recover

Mon, 01 Jan 0001 00:00:00 +0000

A failed request has three different answers: repeat it (transient), repair the context and retry once (overflow), or stop. Pi recognises its own overflow signal; a custom provider’s message may not. The extension below maps only that provider’s overflow text onto the marker Pi recognises, so recovery can run. Everything here was observed on 1.0.4 against a scripted provider in a session with compaction enabled — a real AgentSession, no real model.

Drive one agent through three interfaces

Mon, 01 Jan 0001 00:00:00 +0000

The terminal is one of five ways to drive the agent, and switching drivers changes how you watch it, not what it is. Two tiny drivers below put that claim in front of the same agent-core agent, and a shipped-binary test pushes it across print, JSON and RPC. Everything here ran on 1.0.4 under a scripted model — it exercises how each interface observes the agent, not a provider’s output.

Run Pi with no person attached

Mon, 01 Jan 0001 00:00:00 +0000

A CI job and a pre-commit hook both need Pi with no terminal. The mode determines how input enters the agent, how output is exposed and how a failure is reported. Every claim below was observed on 1.0.4 by driving the shipped pi binary as a child process with a scripted model — the real command line, mode selection and exit codes, with no credential and no provider.

Pick the mode

pi --print "Summarize the changes"                        # one final string, then exit
pi --mode json "Review this repository" > events.jsonl    # events on stdout
git diff | pi --print "Review this change"                # piped stdin, prepended to the prompt
pi --mode json "@notes.md" "summarise"                    # @path includes a text file
pi --mode json -- "-5 degrees is cold"                    # -- stops option parsing
pi --print "Review this change" --tools read,grep,find,ls --no-session

pi --print "Summarize the changes"                        # one final string, then exit
pi --mode json "Review this repository" > events.jsonl    # events on stdout
git diff | pi --print "Review this change"                # piped stdin, prepended to the prompt
pi --mode json "@notes.md" "summarise"                    # @path includes a text file
pi --mode json -- "-5 degrees is cold"                    # -- stops option parsing
pi --print "Review this change" --tools read,grep,find,ls --no-session

With terminal stdin and stdout, Pi opens the terminal UI unless a mode is selected. When either stream is redirected and neither JSON nor RPC is selected, it chooses print mode — so a script that merely pipes input and captures output gets print mode implicitly. Be explicit anyway; a script that relies on TTY detection changes behaviour when run from an interactive shell.

Read the JSON event stream record by record

Mon, 01 Jan 0001 00:00:00 +0000

pi --mode json is not a single JSON result: it is a stream of records, each one JSON object terminated by LF, with stdout carrying nothing else. The records below are illustrative drawings of that shape — the calling conventions themselves were observed on 1.0.4 by running the shipped binary under a scripted model and inspecting the stream.

Framing rules

Split only on LF; strip an optional preceding carriage return so CRLF input parses.
U+2028 inside a string is legal JSON, not a record boundary. A readline-style reader splits a record in half; the test demonstrates this on real output.
The first record is the session header, version 3, and it is not part of the tree.
Read stdout continuously — a reader that stops consuming records can stall Pi when the pipe buffer fills. Stdout carries JSONL only; diagnostics go to stderr.

Illustrative records

{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/project"}
{"type":"agent_start"}
{"type":"message_update","usage":{},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"the quick "}}
{"type":"tool_execution_start","toolCallId":"c1","toolName":"bash","args":{"command":"echo hi"}}
{"type":"tool_execution_end","toolCallId":"c1","toolName":"bash","result":{"content":[{"type":"text","text":"hi"}]},"isError":false}
{"type":"message_end","message":{"role":"assistant","content":[{"type":"text","text":"hi"}],"stopReason":"stop"}}

{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/project"}
{"type":"agent_start"}
{"type":"message_update","usage":{},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"the quick "}}
{"type":"tool_execution_start","toolCallId":"c1","toolName":"bash","args":{"command":"echo hi"}}
{"type":"tool_execution_end","toolCallId":"c1","toolName":"bash","result":{"content":[{"type":"text","text":"hi"}]},"isError":false}
{"type":"message_end","message":{"role":"assistant","content":[{"type":"text","text":"hi"}],"stopReason":"stop"}}

These are illustrative: ids, timestamps and text are placeholders; the fields follow the asserted contracts, not a captured transcript.

Embed an agent in your process with SDK sessions

Mon, 01 Jan 0001 00:00:00 +0000

An SDK session moves the agent into your own Node.js or Bun process: createAgentSession() returns a typed AgentSession, and the events you once parsed out of a pipe arrive as objects that keep the cumulative partial snapshots the JSON stream strips. Inside your process, rules the terminal used to handle silently become yours to state. Everything here is observed — sdk.test.ts drives a real AgentSession whose provider is scripted, on Pi 1.0.4.

Drive a live Pi subprocess over JSONL

Mon, 01 Jan 0001 00:00:00 +0000

RPC keeps Pi in a separate process and talks to it as newline-delimited JSON, so you decide the lifetime of the child — across a process you wait for an event, not a promise. The price is a protocol: command and response records, a stream of session events that carry no command id, and a fourth family, extension UI records, that travels in both directions. Everything below is observed against the shipped binary, on Pi 1.0.4, by a hand-written client that splits on LF only.

Get one typed answer from one model call

Mon, 01 Jan 0001 00:00:00 +0000

Most of what an application needs from a model is one question and one answer. assess.ts is that rung — layer 1, model/provider access, the floor of the five-rung stack: one request, no loop, no session, no terminal. A tool declaration is a schema the model fills in, and validateToolCall() makes the answer a typed value or an exception, all observed under scripted responses on Pi 1.0.4.

Run it

Use Pi 1.0.4 and the example repository’s test runner. The file below is the chapter’s canonical source, reproduced exactly:

Run the agent loop on its own with a corpus tool

Mon, 01 Jan 0001 00:00:00 +0000

research-agent.ts wraps pi-agent-core’s Agent — the class the coding agent is built on — with one corpus-reading tool and an injected stream function: layer 2, the agent core, with the coding agent’s sessions, trust gate, extensions and terminal absent. Unlike chapter 1’s self-contained printing script, this is a library function: the corpus, model and stream function come from the caller, and the transcript is data you assert on. All below is observed under scripted responses on Pi 1.0.4.

Return a schema-valid value from a bounded model loop

Mon, 01 Jan 0001 00:00:00 +0000

A stochastic step is a typed function: text in, a value that matches your TypeBox schema out, and no third outcome. The model can only finish by calling a submit tool whose parameters are that schema, so prose cannot leak past the seam. This page runs the canonical step.ts on pi-agent-core 1.0.4 with a scripted provider.

Run it

The only way out is the submit tool; terminate: true is the hint that ends the loop (excerpt of the canonical step.ts, full file linked below):

Map each agent-core hook by what it can still decide

Mon, 01 Jan 0001 00:00:00 +0000

A hook is a real seam only for decisions it can still make when it fires. beforeToolCall is the one hook that can refuse an effect; afterToolCall rewrites the story but cannot undo the deed. This page reproduces the observed order on pi-agent-core 1.0.4, then the seam matrix that says which decisions are still cheap where.

The order, observed

One tool-using run, a recorder on every hook — the exact assertion from the test:

Compose a pipeline with the weakest component at each position

Mon, 01 Jan 0001 00:00:00 +0000

Composition does not imply agency. A claim checker needs four kinds of component — a plain function, a typed model call, a membership check and an agent — and each one is used only where the weaker ones cannot decide. This page shows the load-bearing parts of the canonical examples/ch40-composition/pipeline.ts, run on Pi 1.0.4 with a scripted provider.

Run it

The two deterministic pieces need no model at all — and one of them is the check the model’s output must pass:

Measure agent reliability with pass@1 and pass^k

Mon, 01 Jan 0001 00:00:00 +0000

Three activities all get called “testing”: scripted (a response you chose), structural (assert on events, not wording) and evaluation (how often the whole thing works over repeated runs). This page is the evaluation harness — the measuring parts of eval.ts, excerpted — on Pi 1.0.4. The “model” below is a seeded 85% coin, so this measures the harness’s arithmetic, not any provider; the ledger contains no real-model evidence.

Run it

The chapter’s canonical eval.ts is a self-contained file (types included); these are its load-bearing pieces. evaluate() runs every task k times, counts a thrown run as a failure, and returns the two rates:

Read a self-declared annotation as a claim, not a control

Mon, 01 Jan 0001 00:00:00 +0000

Capability is not authority, and almost nothing you can write is a boundary — an operating-system boundary is. This page shows the point on Pi 1.0.4 with AgentTool.replay: a field a tool fills in about itself, and nothing in the type verifies it.

The declaration, and the scan

write_file declares itself replay: "safe" — nothing in the declaration checks the claim:

// The tool chooses its own recovery policy. Nothing here checks that the choice is true.
const writeFile: AgentTool<typeof Params> = {
	name: "write_file",
	label: "write_file",
	description: "write a file",
	parameters: Params,
	replay: "safe", // a claim by the inspected party
	async execute() {
		return { content: [{ type: "text", text: "ok" }], details: undefined };
	},
};

// The tool chooses its own recovery policy. Nothing here checks that the choice is true.
const writeFile: AgentTool<typeof Params> = {
	name: "write_file",
	label: "write_file",
	description: "write a file",
	parameters: Params,
	replay: "safe", // a claim by the inspected party
	async execute() {
		return { content: [{ type: "text", text: "ok" }], details: undefined };
	},
};

The companion test scans the four packages’ shipped JavaScript for readers: