Pify
How-to guides

Build an experimental Durable Agent

Build a Pi 1.0.0 Durable host with accurate recovery, replay, ownership, Documents, and observation boundaries.

Experimental. @earendil-works/pi-durable is the new experimental package in Pi 1.0.0. Its API can change without notice between releases. Pin the version and rehearse storage recovery before upgrading.

Pi Durable is a storage-backed orchestration substrate for agent applications. It makes conversation state, Task checkpoints, and application Documents part of one commit stream. This guide builds a small offline host, then shows where a production host must supply models, execution environments, external idempotency, and client policy.

Status and product boundary

Durable does not replace Coding Agent. Coding Agent remains the terminal product for one person working on a local or remote machine. Durable is a separate experimental harness for applications that need long-running conversations, restart recovery, or several clients steering the same work. It shares Pi AI and design ideas with Coding Agent, but it is neither a stable Agent Core API nor a drop-in SessionManager replacement. Pick it because your application owns a persistent scheduler and storage lifecycle, not because a short model call needs another wrapper.

The release makes admitted work recoverable; it does not guarantee exactly-once external side effects. A card charge, deploy, email, or remote write can complete before the process records its outcome. A retryable Task phase may execute at least once and may execute again; an external effect may occur zero, one, or multiple times depending on where failure occurred. Resolve uncertainty through the external service's idempotency key or reconciliation API. Do not infer a transaction across the model provider, Tool environment, and Durable storage from the word “durable.”

Harness, Conversation, run, and Task

A Harness opens one Session over one storage backend, serializes commits, and schedules Tasks. A Conversation is a stateless handle identified by id. Its immutable Entries form a transcript: user inputs, assistant responses, Tool results, system changes, reset and compaction markers, or application-defined kinds. A Commit atomically publishes Entries, Document edits, Task creation, and submission changes. An observer sees a completed commit, never its intermediate edits.

A run starts with admitted input and spans all model turns until a final answer or failure. One turn is a model response and its Tool round. pi.generation is a checkpointed Task; it owns pi.tool Tasks and waits for their results. Custom Tasks use the same checkpoint and ownership machinery. A Conversation is busy only while its pi.live.run exists; a non-generation Task may make its ownership scope non-idle without making it busy. Every Task has either a Conversation or Task owner. A Conversation may instead be ownerless.

Every asynchronous call receives a Chord Context. BACKGROUND_CONTEXT is useful for controlled examples but never cancels. Cancelling a waiter only stops that wait; the admitted Task continues. Use a Submission, Conversation, or Task abort operation when the durable work itself must stop. Invocation-bound handles passed to a Task or Tool must not escape that invocation.

Storage ownership and execution environments

MemoryStorage is deterministic and disappears with the process. openNodeSqliteStorage(file) persists one database file; its WAL with synchronous = NORMAL survives a process crash but may lose the newest commit after power or host failure. openNodeJsonlStorage(directory, context, options) stores append-only files; fsync: true strengthens its commit-marker flush at a throughput cost. These are backend-specific durability boundaries, not an external side-effect guarantee. One process owns a storage instance at a time; Durable does not provide cross-process locking. Route several clients to the one storage-owning process.

The portable SQLite and JSONL cores can run in other JavaScript runtimes when the host supplies their database or filesystem adapter. Tool filesystem and shell access is separate from storage: HarnessOptions.env builds an ExecutionEnv for each Tool call, prompt section, or explicit runtime request from the Conversation ID, its cwd, and committed reads. Without an environment the built-in coding Tools report an error. A remote container can therefore execute a Tool while the Harness and storage remain on another machine. The host must make environment IDs stable where equal paths refer to the same files.

This first executable example is synchronized with the Pi 1.0.0 contract fixture. It opens an offline Harness, configures host-wide compaction through settings, observes the root, and closes it. It intentionally makes no provider request.

import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
import { createModels } from "@earendil-works/pi-ai/models";
import {
  createRegistry,
  defineDoc,
  defineEntry,
  defineExtension,
  Harness,
  MemoryStorage,
  watchEvents,
  type Conversation,
} from "@earendil-works/pi-durable";

export async function verifyPi1000DurableContracts(): Promise<number> {
  const context = BACKGROUND_CONTEXT;
  const harness = await Harness.open(
    new MemoryStorage(),
    {
      models: createModels(),
      registry: createRegistry(),
      settings: {
        compaction: {
          enabled: true,
          reserveTokens: 16_384,
          keepRecentTokens: 20_000,
          backgroundTokens: 32_768,
        },
      },
    },
    context,
  );

  try {
    const root: Conversation = await harness.root(context);
    const view = await root.viewState(context);
    try {
      void view.value;
    } finally {
      view.dispose();
    }
    return root.id;
  } finally {
    await harness.close(context);
  }
}

Harness.open() turns surviving running Tasks into recoverable pending work. root() creates reserved Conversation ID 1 on first use or returns that existing root after a reopen. close() seals admission, joins active invocations, and closes storage; unfinished durable work is left for a later open. Always close in finally.

Submissions and requestId deduplication

Once the host supplies a real provider and model, root.submit({ type: "input", content, requestId }, context) admits an input and returns a Submission. An idle input with an empty inbox is placed in the admission Commit: its pi.user Entry, generation Task, and live run appear together. A busy input enters pi.inbox and is placed at a later boundary. A passive type: "write" submission appends an Entry without asking the model. Submission.wait() resolves to done or unanswered; status() observes without waiting, and harness.submission(id, context) reacquires a Submission after reopening.

Use a stable requestId for a caller that may retry after timeout or restart. The same ID within one Conversation returns the existing Submission rather than admitting a second request. Persist it in the caller's own record. A new ID creates new work, and the key does not deduplicate across Conversations or at an external provider. Even an exactly-once admission claim concerns this local storage record, never arbitrary remote effects.

When busy, followUp waits for the current answer and starts the next run; steer joins the active run after its current Tool round; reject throws ConversationBusy without writing. Host settings choose whether one or all queued steers or follow-ups are placed at a boundary. If a run fails, queued work remains until a later submission places it oldest first. Submission.abort() can withdraw either queued input or write, while Conversation.abort() withdraws queued inputs only. Neither can retract an Entry already placed.

Checkpoint recovery and interrupted model calls

Every Task phase commits a next checkpoint or a terminal outcome. Reopening persistent storage reconciles an interrupted running Task to pending; resume() starts scheduling. A new submission or progress wait also starts it. The model request is not a storage transaction: if interrupted, the generation Task may send it again from its last checkpoint. Previously committed partial output remains visible with an aborted marker, while an uncommitted partial window can be lost. This is recovery from a checkpoint, not replay of the entire conversation from scratch.

Persist Submission.id and inspect its original settlement after restart. harness.inspect(context) distinguishes ready and blocked work; missing Task code, an older Task definition, or failed migration can leave a Task blocked. Install the matching definitions before resuming, or choose an explicit abort/migration policy. Treat a process close like an interruption of active invocations; it does not settle every pending Task as successful.

Provider timeouts and retry policy require the same discipline. One model attempt can have provider-level retries, while a durable generation attempt has its own checkpoint. Record request IDs, attempt numbers, and the last committed phase in host logs. A cancelled waiting Context does not cancel the model or the durable run; call the scope's abort API when that is the intended user action.

Tool replay safety boundary

Each Tool call is a Task whose intent is committed before execute(). Only a Tool explicitly declared replay: "safe" may rerun on recovery. The default is unsafe: an interrupted unsafe call yields an interrupted error result with output committed so far, and unsafe Tools never replay automatically. Mark a Tool safe only when its entire execution is repeatable, or its external system uses a stable idempotency protocol. “Read only” Tools can still be unsafe if a read advances a cursor or acknowledges a message.

Imagine charging a card and crashing before the receipt Commit. A local checkpoint cannot tell whether the charge happened. Use a provider idempotency key derived from stable Task identity and reconcile the receipt before settling; otherwise return the uncertainty to the model or operator. Tool output, details, and diagnostics may stream into pi.live, but the terminal pi.tool-result Entry and Tool usage are committed together later. A thrown Tool error becomes a result the model can see. control.terminate and control.handoff change run flow, not replay safety.

beforeTool can block or change arguments before intent; afterTool can replace the result. A Tool's prepareArguments must be pure because it can be rerun before intent is recorded. External effects in any of these phases need their own idempotency story. Never label a payment or deploy “safe” merely because its function catches errors.

Concurrent Conversations and forks

One Harness schedules concurrent Conversations, so an idle thread can progress while another Conversation waits on a Tool or a model. A busy boundary serializes inputs within one Conversation; it does not lock the whole Harness. This supports a channel and a thread, parallel reviewers, or several workers' conversations with one process owning storage. Apply application-level access control before admitting inputs from different people.

fork(entryId, { ownership }, context) creates a branch at a concrete visible Entry. The fork child sees parent Entries through the fork point, then advances independently. It does not copy the parent's transcript into a second mutable log. Fork-aware Entry scans walk branch ancestry. The child starts with the parent's agent as it was at that Entry; a later parent change does not silently alter the fork. A fresh createConversation() instead starts without transcript ancestry; a Task-owned child starts with its owner's Conversation agent.

Ownership and ancestry are different edges. An ownerless thread is included in Harness-wide idle checks and needs its own lifecycle. A Task-owned child belongs to that Task's abort and idle scope. On replay of a subagent Tool, query the ownership index for an existing child before creating one, then submit with a stable request ID. That prevents a second child when the Tool resumes.

Per-Conversation Agent configuration

Each Conversation stores its Agent choices in the pi.agent Document: model, thinking level, extension selection, Tool filtering, extra instructions, and working directory. Conversation.configure(change, context) commits a change; agent(context) resolves stored names against the Registry and current host defaults. An array of extensions selects exactly those extensions in order; { add, remove } edits the default. A Tool array selects exactly those Tools; { remove } filters. null clears a stored field back to the host default. There is no single process-global “current Agent” that must serve every Conversation.

The model, offered Tools, and prompt for a request are fixed when that request is prepared. A configuration change affects the next request. Tool calls and hooks resolve the Agent at their own Task phase; a changed cwd or extension can affect a call the model has already issued but which has not started execution. Account for this when changing safety policy during a run. Host-wide settings are read at each use and are not stored; after restart, the host must supply a compatible policy.

The execution environment follows the resolved Conversation cwd. A reviewer can use a cheaper model and read-only Tools in another checkout while the main agent retains its own choices. Store only public names and JSON choices; credentials and provider objects belong to host configuration, not a Document copied into forks.

Extensions, sections, Tools, and wraps

A named extension bundles sections, Tools, hooks, wraps, and Tasks. Install it in the application's Registry, then select it per Conversation. By default every installed extension is selected in install order. The Conversation persists extension and Tool names, not executable code. A missing name after restart simply stops contributing behavior until the host installs it again, so treat extension deployment as part of recovery.

Prompt sections render before each request from the resolved Agent, environment, and committed Documents. Durable records positional system changes in the transcript so a fork or restart sees what the model saw; avoid volatile sections such as a timestamp that needlessly invalidate provider prompt caches. The Conversation's instructions render last. defineTool() validates arguments against its TypeBox schema. Built-in CodingTools provide read, write, edit, and bash through the supplied environment, and can be omitted or overridden per Conversation.

A later selected Tool with the same name wins. wrapTool() decorates whichever Tool won, and wrapSection() does likewise for a prompt section. Wrappers should preserve the wrapped Tool's replay classification and report errors clearly. The Registry can change while running, but a Tool invocation already in progress keeps the implementation it started with.

Hooks and durable memo decisions

Hooks run in defined Task phases rather than as a global event bus. Generation exposes beforeRequest, afterResponse, onYield, and afterTools; Tool execution exposes beforeTool and afterTool; Compaction exposes beforeCompact. Selected extensions' hooks run as a chain in Conversation order. beforeTool's first block wins, onYield's first continuation wins, and observer hooks run through the chain. A thrown beforeTool hook blocks the call; other hook failures are reported while the chain continues.

A hook may run again after crash recovery. Its api.memo(name, candidate, context) stores a small JSON decision with the asking Task; the first write wins. Read the memo before asking for approval again. The memo makes a local decision durable, but cannot retroactively undo an external notification sent before the memo Commit. If approval is supplied by Slack or another service, use that service's request identity and reconcile duplicates.

Hook APIs expose committed Document reads, so policy can depend on application state as of the phase. A new Registry version affects the next Task phase, not a hook already executing. Keep side effects out of read-only hooks where possible, and record the precise phase and Task ID when debugging a policy decision.

Custom Tasks, waiting policy, and ownership tree

defineTask() declares a name, version, initial checkpoint, phase handlers, and abort handler. Register custom Tasks before recovery. A phase should commit its next checkpoint or terminal result; timers and sleeps are not substitutes for a persisted checkpoint. A Task may create child Tasks or Conversations inside its Commit. The ownership tree, not a detached Promise array, decides which work joins and which abort traverses.

A waiting checkpoint lists Task IDs in on and chooses allSettled or failFast. The waiter resumes only when all listed Tasks are terminal. on can name an already terminal Task or one it does not own, but a non-owned Task requires allSettled. failFast is allowed only when every listed Task is an owned child; the first failure aborts siblings. A Task whose own outcome is decided can remain completing until ordinary owned work drains. A failed or aborted owner first aborts reached descendants.

The Task graph exposes live nodes with owner edges and status for debugging. Its node list is not a permanent history: terminal Tasks leave the graph. harness.inspect() separately reports whether a pending Task is blocked by unavailable code. Waiters should use waitForTask() when they need a terminal receipt, and should pass a cancellable Context when the UI may detach without aborting the Task.

Foreground and background abort reach

Foreground Task-owned work keeps its owner from becoming terminal until it joins. Ordinary idle traversal and abort reach through foreground descendants. A background Task is different: background: true is valid only for a Conversation-owned Task and forms an abort and idle boundary for everything it owns. The Task remains owned by that Conversation; “background” does not make it ownerless.

An ordinary Conversation abort stops reached foreground work and withdraws queued inputs, but ordinary Conversation abort does not kill background descendants. abort(context, { background: true }) crosses background boundaries that already exist when the abort is admitted. It does not promise to catch new background work created later. Abort runs bottom-up: reached descendants settle before an owner Task's abort handler starts, allowing the handler to clean up only its own effect.

Use a foreground child when a Tool must return its answer and failure should stop it. A persistent reporter or subagent can live behind a Conversation-owned background anchor Task; the host then needs a separate stop command for it. waitForIdle() uses ordinary scope and may resolve while background work remains. To shut down fully, explicitly stop background work and await its receipts before closing the Harness.

Background and manual compaction, overflow retry

Compaction changes the model's active context, not the stored transcript: compaction retains old Entries. A pi.compaction head marker contains a summary and the first Entry kept verbatim. Host settings.compaction controls automatic behavior: reserveTokens sets a blocking threshold below context capacity, keepRecentTokens estimates the recent verbatim tail, and backgroundTokens begins summarization before that threshold. Setting backgroundTokens to zero disables background compaction only. Manual compact() remains available even when automatic compaction is disabled.

Background compaction runs while the Conversation works. Its summary is placed immediately when idle or at the next turn boundary when busy. compact(instructions, context) returns a Task ID; its terminal result may point to a write Submission whose settlement reports whether placement succeeded or became stale. A later summary with an obsolete cut cannot replace a newer active head. Summarization usage contributes to pi.usage, and pi.live.compactions exposes attempts and retry backoff.

If the next request exceeds the threshold and a background summary is not ready, generation performs blocking compaction. A provider context-overflow response may trigger one compaction and one retry only if automatic compaction is enabled, a valid cut exists, and no earlier overflow or blocking compaction has exhausted that path. Otherwise the error is recorded without retry. The retry resends a model request; it is not permission to repeat a completed Tool effect.

Reset, handoff, and retained history

reset(handoff, context) admits a pi.reset Entry. The model sees only the active context from that marker onward; older Entries remain in storage and can still be inspected through history APIs. A handoff string becomes a user message in the new context. A Tool may request the same flow with control.handoff. A reset queued while busy is placed at a boundary; when placed during a Tool round it ends the current run.

A reset is not deletion, a privacy purge, or a fork. It changes which messages contribute to future model requests. A compaction marker also changes context while retaining source Entries, but carries a summary and a cut point rather than an optional user handoff. Keep retention policy and access control at the storage and application layer. Do not promise users that a reset removes old content from backups or prior client snapshots.

After a restart, the reset marker remains part of the committed transcript. A late client should build its display from committed Entries and head markers rather than assuming the UI's in-memory list defines what the model currently sees.

Atomic Documents and fork policy

Documents and Entries commit atomically. A typed Document can hold application state beside the transcript, so a visible audit Entry, state change, and new Task can describe one business transition. defineDoc() or defineDocFamily() declares kind, version, scope, history, fork behavior, and initializer. Update through tx.doc() in a Commit; read through a snapshot or attached state. Choose history: "rewindable" when historical values are needed; latest avoids retaining old Document values.

For a Conversation Document, fork: "initial" starts the child fresh, fork: "current" copies the parent's current value, and fork: "asOf" copies the value at the fork point. The latter requires rewindable history. Choose deliberately: a private draft may need a fresh child, while a task list tied to the transcript may need asOf. A fork's Entry ancestry and Document-copy policy are separate rules. The snippet below builds on the imports above and is synchronized with the offline fixture. It forks after one atomic Document-plus-Entry Commit, then changes the parent while three live observers are attached. It checks the asOf child against the later parent state, observes the new Entry, replaces the installed extension, and releases every observer.

const NoteEntry = defineEntry<{ text: string }>("app.note");
const Notes = defineDoc<{ items: string[] }>({
  kind: "app.notes",
  version: 1,
  scope: "conversation",
  history: "rewindable",
  fork: "asOf",
  initial: () => ({ items: [] }),
});

function signal<T>() {
  let resolve!: (value: T) => void;
  const promise = new Promise<T>((done) => {
    resolve = done;
  });
  return { promise, resolve };
}

async function within<T>(promise: Promise<T>, label: string): Promise<T> {
  let timeout: ReturnType<typeof setTimeout> | undefined;
  try {
    return await Promise.race([
      promise,
      new Promise<never>((_, reject) => {
        timeout = setTimeout(
          () => reject(new Error(`Timed out: ${label}`)),
          5000,
        );
      }),
    ]);
  } finally {
    if (timeout !== undefined) clearTimeout(timeout);
  }
}

export async function verifyPi1000DurableStateContracts() {
  const context = BACKGROUND_CONTEXT;
  const registry = createRegistry();
  registry.install(
    defineExtension({
      name: "notes",
      sections: [{ key: "notes_initial", render: () => "Initial notes" }],
    }),
  );
  const firstRegistry = registry.snapshot();
  const harness = await Harness.open(
    new MemoryStorage(),
    { models: createModels(), registry },
    context,
  );
  try {
    const root = await harness.root(context);
    const marker = await root.commit(async (tx) => {
      (await tx.doc(Notes, root.id)).items.push("write docs");
      return tx.appendEntry(NoteEntry, root.id, { data: { text: "saved" } });
    }, context);
    const fork = await root.fork(
      marker.id,
      { ownership: { kind: "ownerless" } },
      context,
    );
    const view = await root.viewState(context);
    try {
      const watch = await root.watch(context);
      try {
        const events = await watchEvents(harness, root.id, context);
        try {
          const viewBefore = view.value.entries.length;
          const watchBefore = watch.value.entries.length;
          const viewUpdate = signal<number>();
          const watchUpdate = signal<number>();
          const appended = signal<{ id: number; text: string }>();
          const unsubscribe = view.subscribe((value, _context, delivery) => {
            if (
              delivery.kind === "update" &&
              value.entries.length > viewBefore
            ) {
              viewUpdate.resolve(value.entries.length);
            }
          });
          try {
            watch.start(async (value) => {
              if (value.entries.length > watchBefore) {
                watchUpdate.resolve(value.entries.length);
              }
            });
            events.start(async (batch) => {
              for (const event of batch) {
                if (
                  event.type === "entry_appended" &&
                  event.entry.kind === "app.note" &&
                  event.entry.data !== undefined &&
                  event.entry.data !== null &&
                  typeof event.entry.data === "object" &&
                  !Array.isArray(event.entry.data) &&
                  typeof event.entry.data.text === "string"
                ) {
                  appended.resolve({
                    id: event.entry.id,
                    text: event.entry.data.text,
                  });
                }
              }
            });
            const later = await root.commit(async (tx) => {
              (await tx.doc(Notes, root.id)).items.push("later update");
              return tx.appendEntry(NoteEntry, root.id, {
                data: { text: "later update" },
              });
            }, context);
            const [viewUpdateEntries, watchUpdateEntries, appendedEntry] =
              await within(
                Promise.all([
                  viewUpdate.promise,
                  watchUpdate.promise,
                  appended.promise,
                ]),
                "Durable live view, watch, and event updates",
              );
            registry.install(
              defineExtension({
                name: "notes",
                sections: [
                  { key: "notes_revised", render: () => "Revised notes" },
                ],
              }),
            );
            const agent = await root.agent(context);
            return {
              rootId: root.id,
              rootItems: (await harness.snapshot(Notes, root.id, context))
                ?.items,
              forkItems: (await harness.snapshot(Notes, fork.id, context))
                ?.items,
              viewBefore,
              watchBefore,
              viewUpdateEntries,
              watchUpdateEntries,
              laterEntryId: later.id,
              appendedEventId: appendedEntry.id,
              appendedEventText: appendedEntry.text,
              initialSection:
                firstRegistry.extension("notes")?.sections?.[0]?.key,
              replacedSection: registry.snapshot().extension("notes")
                ?.sections?.[0]?.key,
              priorSnapshotSection:
                firstRegistry.extension("notes")?.sections?.[0]?.key,
              resolvedSection: agent.sections.find((section) =>
                section.key.startsWith("notes_"),
              )?.key,
            };
          } finally {
            unsubscribe();
          }
        } finally {
          await events.stop();
        }
      } finally {
        await watch.stop();
      }
    } finally {
      view.dispose();
    }
  } finally {
    await harness.close(context);
  }
}

The fixture performs no model or provider call. In a real host, conversationCreated and init can create application Documents in the same creation Commit, including raw child creation inside a Tool transaction. An exception rolls the whole Commit back; observers never see a Task without its corresponding state.

Registry replacement and malleability

The Registry contains executable code, while Conversations persist its names. Installing an extension under an existing name replaces it in place and publishes a new Registry snapshot; uninstalling removes the installed name. This is malleability at Task-phase boundaries, not mutation of code already executing. A running Tool finishes with the implementation it took. The next request, Task phase, or Tool call resolves new code. If an extension disappears on restart, its pending custom Tasks may be blocked until it is installed again.

Duplicate Tool names among selected extensions resolve in selection order, with the later Tool winning, and wraps decorate the winner. A missing extension name in pi.agent contributes nothing until reinstalled. This means a deployment that renames a Tool can change an existing Conversation's offered capabilities. Review stored names and Task versions during rollout, and use inspect() to surface blocked work rather than silently reporting a healthy agent.

Registry replacement is process-local. It does not migrate storage records, change already committed Entries, or propagate code to another process. The one-owner storage rule still applies if several clients observe or steer the same Conversation.

viewState, watch, and watchEvents for multiple viewers

viewState() returns an attached read-only structural Chord state; inspect value, subscribe for updates, and call dispose() when done. watch() gives the current view plus serialized callbacks with exact Chord operations for each later Commit; call stop() to release it. watchEvents() is an experimental adapter that derives coding-agent-style event batches from committed changes and begins with a snapshot. It is useful for a familiar UI, but it is not a replayable event-history log.

Several viewers can attach to one Conversation, including a client that joins mid-run. Every client starts from a current snapshot, then receives changes. A slow structural watch holds at most 100 pending frames before replacing them with one latest full view; a slow event stream similarly replaces pending batches with a snapshot after 100. Consumers must accept a reset to authoritative state, not assume every intermediate delta will arrive. Partial model and Tool output is committed at most every 100 ms, so the newest partial window may disappear on a crash.

The view exposes active Entries, pi.live generation and Tool progress, pi.inbox, pi.agent, and pi.usage. It does not grant permission to steer. Authenticate clients and authorize their submissions in the host, then send committed views through a transport. Dispose or stop all attachments when a browser tab or socket leaves.

Failure modes and exact pinned sources

Exercise failure cases before accepting production traffic. Crash after submission admission, during a model request, and during safe and unsafe Tool calls; reopen the same backend and observe the original Submission. Retry a stable requestId, then deliberately change it to see why a new admission is possible. Cancel a waiter and verify its Task continues. Abort a foreground child, ordinary Conversation scope, and explicit background scope separately. Force a missing custom Task definition and inspect the blocked state. Fork at an Entry after a Document edit and compare initial, current, and asOf policies. Force background, blocking, manual, and overflow compaction while verifying source Entries remain stored.

Log Conversation and Task IDs, kind, phase, attempt, outcome, and retry decision. Redact prompt content, Tool arguments, credentials, and sensitive Document fields. A durable transcript is application data that may remain in backend files and backups. Monitor provider usage separately from committed pi.usage during outages; a failed or aborted attempt may still incur cost. Match crash and power-loss expectations to the backend and do not open the same storage from competing processes.

This guide was reviewed on 2026-10-06 against Pi 1.0.0, tag v1.0.0, exact commit a13d35a742c6ef8462812a28fbe1d8c8b7431c32. The Durable README, CHANGELOG, package export map, root exports, Harness implementation, and public Harness types determine signatures and edge behavior. The launch article explains the motivation and examples; the exact tag controls this guide's contracts.

On this page