Durable Coding Agent with pi-durable

pi-durable is an agent harness that keeps an agent's state durable: its conversations, the tool calls in progress, forks, and documents all survive a crash. @hatchet-dev/pi-durable runs it on Hatchet, and gives it the rest of what a production coding agent needs:

  • One owner per session. Each session is owned by one run of a Hatchet task. If its worker dies, Hatchet retries the run on another worker, and the agent resumes from its storage.
  • A sandbox per conversation. The agent's read, write, edit and bash tools run in a Hatchet sandbox, not on the worker. A fork of a conversation gets its own sandbox, started from the snapshot taken at the fork point.
  • A way in and out. A client sends messages to a session and reads its live state from anywhere (a web server, a CLI, another task) over durable streams.

The agent loop and its model API key stay on your worker. Only the tool calls run in the sandbox, so the sandbox needs no credentials.

Sandboxes and durable streams are Labs features and may change in future releases. In the dashboard, open Settings, go to Labs Preview and turn on Sandboxes and Durable streams. Tenants on the free plan are asked to upgrade first.

pi-durable is experimental and may change in future releases. @hatchet-dev/pi-durable pins pi-durable to ~1.5.0, because a minor release of pi-durable can change its storage format or API.

Architecture

  • The session task owns the session. Its concurrency key is the session ID, with one run at a time, so a session never has two owners. When the session is idle for a while, the task returns, and the next message starts a new run.
  • The inbox is a durable stream topic the client publishes to. Each message carries a request ID, so a message delivered twice is applied once.
  • The view is a durable stream topic the session task publishes its state to after every change. A client that connects starts at the newest view.

Setup

Prepare your environment

You need:

  • A Hatchet tenant with Sandboxes and Durable streams turned on under Labs Preview, and a sandbox provider connected, as described in Sandbox Setup.
  • Node 22.19 or newer, @hatchet-dev/typescript-sdk 1.44.0 or newer, and @hatchet-dev/sandbox 0.1.5 or newer.
  • An ANTHROPIC_API_KEY environment variable on the worker.

Install the packages:

npm install @hatchet-dev/pi-durable @hatchet-dev/typescript-sdk @hatchet-dev/sandbox \
  @earendil-works/pi-durable@~1.5.0 @earendil-works/pi-ai@~1.5.0 @earendil-works/chord@~1.5.0

Set up the agent

Create the model registry and install the sandbox coding tools. sandboxCoding() gives the agent pi's read, write, edit and bash tools. The tools that can change the workspace record its snapshot after they run:

import { createModels } from "@earendil-works/pi-ai/models";
import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";
import { createRegistry } from "@earendil-works/pi-durable";
import { sandboxCoding } from "@hatchet-dev/pi-durable";
import { HatchetClient } from "@hatchet-dev/typescript-sdk/v1";

export const hatchet = HatchetClient.init();

export const models = createModels();
models.setProvider(anthropicProvider());

export const registry = createRegistry();
registry.install(
  sandboxCoding({
    instructions:
      "The repository is in /workspace. Run its tests with npm test.",
  }),
);

Define the session task

defineSessionTask makes the Hatchet task that owns a session. openHarness opens the session's pi-durable harness on its storage, with sandboxEnvs() as the environment, so each tool call runs in the sandbox of its conversation:

import { Harness } from "@earendil-works/pi-durable";
import { openNodeSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/node";
import { defineSessionTask, sandboxEnvs } from "@hatchet-dev/pi-durable";
import { hatchet, models, registry } from "./agent";

const TEMPLATE = "node:24"; // includes git

export const session = defineSessionTask(hatchet, {
  agent: {
    model: { provider: "anthropic", modelId: "claude-opus-5-5" },
    cwd: "/workspace",
  },
  sandbox: {
    template: TEMPLATE,
    // Fill each conversation's first sandbox, for example with a repository.
    // The workspace is not empty on Kubernetes, so fetch into it rather than `git clone .`.
    seed: async (sandbox) => {
      const result = await sandbox.exec(
        "git init -q && " +
          "git fetch -q --depth 1 https://github.com/acme/app.git && " +
          "git checkout -q FETCH_HEAD",
      );
      if (result.exitCode !== 0) throw new Error(result.stderr);
    },
  },
  maxSessionCostUsd: 3,
  openHarness: async (sessionId, onReport, context) =>
    Harness.open(
      await openNodeSqliteStorage(`.pi-data/${sessionId}.sqlite`),
      {
        models,
        registry,
        env: sandboxEnvs(hatchet, { template: TEMPLATE }),
        onReport,
      },
      context,
    ),
});

maxSessionCostUsd aborts every conversation of the session once it has spent that much, and rejects later inputs. A rejected input appears in the view's rejected list.

The session task does not store anything itself: failover reaches as far as the storage you open in openHarness. SQLite on the worker's disk only fails over to a worker on the same machine, or one with the same volume. pi-durable has no cross-process locking, so there must be one owner at a time, which the task's concurrency provides.

Start the worker

Register the session task with a worker:

import { hatchet } from "./agent";
import { session } from "./session";

const worker = await hatchet.worker("pi-worker", { workflows: [session] });
await worker.start();

Start two workers to see failover.

Talk to a session

SessionClient creates sessions, sends them messages and reads their views. It needs only a Hatchet client, so a web server or a CLI can use it:

import { SessionClient } from "@hatchet-dev/pi-durable";
import { hatchet } from "./agent";

const sessions = new SessionClient(hatchet);
const sessionId = await sessions.create();

// A session starts with one conversation, the root, whose ID is 1.
await sessions.send(sessionId, {
  type: "input",
  conversationId: 1,
  text: "Fix the failing test.",
});

for await (const view of sessions.views(sessionId)) {
  const root = view.conversations.find((c) => c.id === 1);
  console.log(root?.items.at(-1));
}

send takes one of these messages:

MessageEffect
{ type: 'input', conversationId, text, whenBusy? }Adds a user message. A busy conversation gets it after its current run (the default), or during it with whenBusy: 'steer'. A conversation's first input creates its sandbox.
{ type: 'fork', conversationId, entryId }Starts a new conversation from that entry, with a sandbox started from the snapshot of that point.
{ type: 'abort', conversationId }Stops the conversation's current run.

A message the session cannot apply, such as an input for a conversation that does not exist, is not dropped: the view's rejected list has it, with the reason.

Test failover

Send a task that takes a while, such as "Fix the failing test", and stop the worker that owns the session while a command is running. Once the engine sees that the worker is gone, which takes about 30 seconds, another run of the session task takes over on the other worker and resumes the session from its storage, in the same sandbox. The view shows the new run and its attempt.

The command that was running is not run again, because it may have partly run. The agent gets it back as an error, Tool bash was interrupted and may have partially run, and decides what to do next, for example run it again.

What the view contains

The session task publishes a SessionView after every change:

  • the run and attempt that owns the session;
  • for each conversation: its items, its live generation and tool output, its sandbox and latest snapshot, its token usage and cost, and why its last run failed, if it did;
  • the last 20 messages the session rejected.

A conversation's items are a window of its newest 50 to 100 entries. before is the ID of the entry just before the window, and is absent when the window starts at the beginning of the conversation.

Options

OptionDefault
namepi-sessionThe task's name, and the prefix of the session's stream topics. Give SessionClient the same taskName.
sandbox.workspace/workspaceThe sandbox's workspace. Tool paths outside it are refused.
sandbox.idleTimeoutMs30 minA sandbox idle this long stops. The next tool call restarts it from its latest workspace snapshot.
idleGraceMs20 sHow long an idle session task waits for the next message before it returns.
retries3Retries of the session task after a crash.
executionTimeout60mThe longest one run may own the session.

How tools behave in a sandbox

  • A command's output arrives when the command ends, not while it runs.
  • Aborting a conversation stops waiting for its command, but the command runs on in the sandbox until it ends or times out, and the sandbox's next call waits for it.
  • A sandbox runs one call at a time.

Next steps

Last updated on November 19, 2026

On this page