Pi Durable Dev Rules

@earendil-works/pi-durable is a durable agent harness: conversations, model turns, tool calls, tasks, and your own documents are committed to storage before anything is shown, so a process that dies mid-turn is picked up where it stopped. It ships in the pi monorepo next to @earendil-works/pi-ai (model access, tools, messages) and @earendil-works/chord (tracked JSON state).

Two things about it decide most design choices:

• The API is experimental. Version 1.2.0 tracks the monorepo; breaking changes land in every release. Quote and write against the version you have installed, and treat a signature difference as a version difference rather than a mistake.
• It is a library for building agentic applications, not a coding-agent CLI. For the Pi CLI, its extensions, skills, MCP, and SDK, use the sibling skill pi-dev-rules.

When to use this skill

• Writing or reviewing code that imports @earendil-works/pi-durable or @earendil-works/pi-ai.
• Assembling a harness: storage backend choice, HarnessOptions, settings, the registry, and an execution environment.
• Conversations: submit/wait, the busy inbox (steer, follow-up, write), reset and handoff, forks, per-conversation agent changes.
• Tools: TypeBox schemas, three output channels, nested calls with executeTool(), callers, deferred tools and tool search, replay safety, output limits, image handling.
• Durable tasks: phases and checkpoints, ownership, waiting and failFast, abort, recovery, migration.
• Subagents and child tasks, foreground versus background, reporting answers back.
• Documents: scopes, history and fork semantics, migrations, checkpoints, observation.
• Code mode (QuickJS scripts over the conversation's tools), hooks and guards, compaction, usage.
• Runtime questions: what survives a crash, why an input is still queued, why a task is blocked or orphaned, how an abort cascades, why a partial answer is visible or missing.
• Extending the harness: storage backends and execution environments verified with the conformance suites, custom tasks and prompt sections.

Reference index: load the file you need

Cheat sheet

npm install @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chord
node --conditions=source --experimental-strip-types app.ts     # run TS directly against the source

import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
import { builtinModels } from "@earendil-works/pi-ai/providers/all";
import { createRegistry, Harness, AssistantEntry } from "@earendil-works/pi-durable";
import { openNodeSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/node";

const context = BACKGROUND_CONTEXT;
const harness = await Harness.open(await openNodeSqliteStorage("./session.sqlite"), {
	models: builtinModels(), registry: createRegistry(), env: (target) => new NodeExecutionEnv({ cwd: target.cwd ?? process.cwd() }),
}, context);
const root = await harness.root(context, { agent: { model: { provider: "openai", modelId: "gpt-6-sol" } } });

harness.resume();                                              // continue unfinished work from a previous process
const submission = await root.submit({ type: "input", content: "Hello", requestId: "greeting-1" }, context);
const settled = await submission.wait(context);                // "done" | "unanswered"
if (settled.status === "done" && settled.type === "input") {
	const answer = await root.commit((tx) => tx.entry(AssistantEntry, settled.answer), context);
}
await harness.close(context);

Storage: MemoryStorage (nothing persisted), openNodeSqliteStorage(path) (the default for anything long-running; WAL, commits survive process crashes), openNodeJsonlStorage(directory, context) (append-only, keeps the whole history in memory), openDurableObjectSqliteStorage(ctx.storage). One process owns a storage at a time.

Hard rules

• Writes go through one commit line, and nothing is shown before its commit is stored. Inside a commit callback read only through tx; read every table row you need before the first table write (ReadAfterWrite), and never await slow work there: no models, tools, processes, network, humans, nested commits, or session waiters.
• Every asynchronous call takes a Context. Cancelling it cancels only that call or wait, never the durable work. Use BACKGROUND_CONTEXT where nothing should cancel, and withCancel() at a host boundary. withoutAbortSignal() is for mandatory cleanup such as close().
• Report what you did only after it is committed. The pattern for a task step is: commit the intent, perform the effect, commit the result. A crash between the effect and the commit reruns that step, so make steps idempotent, use runtime.memo() for first-writer-wins decisions, and set replay: "safe" on a tool only when a rerun is genuinely safe. An unsafe tool that is interrupted gives the model an interrupted error result with the output committed so far.
• A tool has three output channels. output is what the model reads, structuredOutput is what programs calling the tool read (validated against structuredOutputSchema, required unless the result is an error), details is for the host UI. Only output and details enter the transcript.
• Every tool call is its own durable task owned by its caller. Nested calls made with api.executeTool() return their result to the caller instead of the transcript and reuse a key on rerun; cancelling the context stops only the wait. A nested result's usage is already counted under its own tool, so forwarding it double-counts it.
• Ownership decides lifetime. Every task names its owner at creation; every conversation is ownerless or owned by a task. Abort flows down; a task finishes only once its ordinary owned work drained (stored as completing until then); a background: true task is a boundary that ordinary aborts and idle waits skip. Never create owned work from an abort handler (the task is abort-marked): compensate inline, or use background conversation-owned tasks with runtime.waitForTask().
• A run owns its own writes. Do not append raw entries to a conversation with an active run: use a write submission, which a raw tx.appendEntry() cannot replace and which runs the stale check.
• pi.-prefixed names belong to the built-ins for task names, document kinds, and entry kinds (pi.user, pi.assistant, pi.system, pi.tool-result, pi.reset, pi.compaction, pi.agent, pi.provider, pi.live, pi.inbox, pi.usage, pi.generation, pi.tool). Nothing enforces this and reusing one collides with harness behavior.
• A storage error ends the harness. The failing call rejects, every later call and pending wait rejects with SessionFailed, watches end with session_failed, and onReport gets the error once. Nothing is retried; reopen to recover and resubmit with the same requestId. An invalid request fails only that call (StorageRequestError), and your own code fails only its own unit.
• Documents are addressed by kind, not by object. Kinds and visible names are persisted protocol: a value migration cannot rename a kind (copy and retire), and a stored version newer than the code, or older without migrate, fails access. Only a typed tx.doc() creates an absent document.
• Values from snapshot(), document states, and watches are tracked containers. Never mutate them; copy first. A watch keeps at most 100 undelivered frames before collapsing into one full-value replacement, so a consumer that must see every transition has to journal it itself.
• Extensions are selected whole. Hooks and wrappers apply only where their extension is selected, so a conversation that selects tools as an explicit array and omits a guard runs without it. Wrappers are pure; uninstalling an extension stops new use but does not free resources of a running call.
• Prompt sections must be stable. A section whose text changes without a real content change (a clock, a random value) appends a pi.system entry on every request and defeats provider prompt caching. Settings can be getters: they are read at every use and never stored.
• The API is experimental, and the Pico5 specification is a design document. Read references/durable-guide.md for behavior, references/durable-spec.md when a rule matters, and section 12 (API footguns) of the spec before shipping.