Introducing a new way to review your PRs.

Read the announcement

earendil-works / pi

AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI

View on GitHub

13 documents · Updated Nov 19, 2026

docs / durable-runtime

Durable Runtime

Overview

Path-routing coverage: this doc owns packages/durable/**. Route changes under this glob here, including runtime code in packages/durable/src/**, package docs in packages/…/README.md and packages/durable/docs/**, storage and environment adapters, coding tools/code mode/images/tool search, test helpers, packages/durable/test/**, and Cloudflare worker fixtures in packages/durable/test-workers/**.

packages/durable is @earendil-works/pi-durable, a durable conversation, task, and document runtime. Public exports are gathered in packages/…/index.ts and subpath exports are declared in packages/…/package.json: the root runtime, ./env, ./codemode, ./tool-search, ./tools, ./images, storage backends, and ./testing. The package is organized around three layers: the generic durable kernel in packages/…/types.ts, packages/…/documents.ts, packages/…/entries.ts, packages/…/tasks.ts, packages/…/signals.ts, and packages/durable/src/session/**; the agent harness and built-in tasks in packages/durable/src/harness/**; and host-facing integrations in packages/durable/src/env/**, packages/durable/src/storage/**, packages/durable/src/tools/**, packages/durable/src/codemode/**, packages/durable/src/tool-search/**, packages/durable/src/images/**, and packages/durable/src/testing/**.

The core data model is defined in packages/…/types.ts. Every storage backend implements the Storage interface: a global numeric ID namespace, conversations, immutable entries, submissions, tasks, and scoped documents. defineDoc() and defineDocFamily() in packages/…/documents.ts define typed JSON documents with session, conversation, or task scope, optional family keys, migration, and checkpoint policies. Conversation documents can be latest-only or rewindable; fork behavior is encoded in the document semantics and enforced when packages/…/forks.ts prepares fork document copies. defineEntry() in packages/…/entries.ts defines typed immutable transcript records; built-ins include pi.user, pi.assistant, pi.system, pi.tool-result, pi.reset, and pi.compaction. defineTask() in packages/…/tasks.ts wraps durable state machines whose records move through pending/running/waiting/sleeping/completing/terminal states.

packages/…/session.ts is the mutation-line kernel. createSession() opens a SessionImpl over a Storage, serializes commit callbacks, stages table/document changes through packages/…/transaction.ts, and sends durable writes through packages/…/writer.ts. The writer groups several logical commits into one backend Storage.commit() call while preserving publication order. Reads that touch keys written by an unpublished commit wait for publication, so session memory never observes admitted-but-unstored state. The session also owns loaded document trackers, document watches/observers, commit observers, deferred document-only commits, and document retention. packages/…/cached-storage.ts wraps writable storage with hot caches for conversations, live/awaited tasks, and recently written submissions; read-only sessions bypass it because another process may write the storage.

packages/…/harness.ts extends SessionImpl into the public Harness. Harness.open() checks that createRegistry() supplied built-in task definitions, opens/reconciles live tasks, and returns conversation handles. The root and created conversations get built-in docs in the creation commit: pi.live from packages/…/live.ts, pi.inbox from packages/…/inbox.ts, pi.usage from packages/…/usage.ts, pi.provider from packages/…/provider.ts, and pi.agent from packages/…/agent.ts. HarnessOptions in packages/…/types.ts supplies model access, registry, dynamic settings, an optional env builder, timers/wake handling, telemetry/reporting, and read-only mode.

Submissions are admitted by packages/…/submissions.ts. A public Conversation.submit() or transaction-form submit validates request IDs, writes a SubmissionRecord, either appends display-only writes immediately or queues model-affecting work in pi.inbox, and starts a run by creating a pi.generation task when the conversation is idle. packages/…/inbox.ts owns boundary placement: queued writes are placed before user items, steer/follow-up modes choose one or all queued inputs, resets start a new active range, and stale head-targeted writes settle unanswered.

The scheduler in packages/…/scheduler.ts runs durable tasks. It mirrors all live task records from stored commit publications, maintains ownership indexes across tasks and task-owned conversations, reserves runnable tasks on the session line, runs phase handlers off the line, and writes each transition back in a serialized decision region. On open, it scans live tasks, changes surviving running records back to pending with an incremented restart count, wakes sleeping gate checks, marks abandoned restart-only children, schedules cascades/finalization, and drives Harness.wake()/onWake. It handles sleeps, waits, signals, fail-fast joins, abort marks and cascades, orphaned tasks whose definition is missing or unmigratable, restart limits, idle waiters, and retained context ranges for faster model-context reads.

The built-in agent loop is a set of durable tasks. packages/…/generation.ts defines pi.generation, which prepares the model request by resolving pi.agent, rendering prompt sections, adding positional pi.system entries, checking automatic compaction thresholds, streaming partial output into pi.live, sending or polling pi-ai requests, retrying model errors, classifying terminal responses, creating pi.tool tasks for tool calls, running afterTools/onYield/afterRun hooks, and settling submissions through endRun() in packages/…/live.ts. packages/…/tool.ts defines pi.tool, which resolves the called tool from the phase agent, validates arguments, runs beforeTool/afterTool hooks, records durable intent before executing, publishes running output/details/diagnostics into pi.live, supports nested api.executeTool() calls using task-scoped pi.tool.nested-call documents, parks on sleeps or owned tasks, and applies replay policy after recovery. packages/…/compaction.ts defines pi.compaction, which selects old context ranges, lets hooks decline or supply a summary, otherwise summarizes with a model, then appends a pi.compaction entry directly for blocking compactions or via a write submission for conversation-owned compactions.

Extensions are installed into an application-owned registry. packages/…/registry.ts keeps immutable snapshots and always includes built-in tasks; packages/…/define.ts provides defineExtension, defineTool, section, hook, hookTask, wrapTool, and wrapSection. packages/…/agent.ts stores per-conversation agent choices as names in pi.agent, resolves them against the current registry snapshot and settings, composes tools/sections/wrappers in extension order, filters model-callable vs tool-callable tools, and tracks deferred tools. packages/…/tool-search.ts provides the tool_search extension/tool: it ranks currently deferred tools with BM25 from packages/…/search.ts, returns matches, and uses control.addTools so the next generation commits those tools into pi.agent.modelTools.

Execution environments live behind packages/…/index.ts. An ExecutionEnv is both a portable filesystem and shell: reads return Result objects instead of throwing, file handles support positional binary reads and line scans, watchers report path/overflow/failure changes, and shell execution streams output with optional retained-tail windows and spill files. packages/…/node.ts implements this for local Node/Bun: path resolution handles ~ and file URLs; exec() runs string commands through bash/sh or array commands directly, kills process trees on abort/timeout, streams stdout/stderr, and spills complete output after thresholds; filesystem methods provide binary readers, directory readers, listFiles, temp files, cleanup, and canonical paths. packages/…/node-watch.ts implements robust native-or-polling watchers by snapshot comparison, switching to polling on Windows and unreliable filesystems; packages/…/line-scan.ts computes decoded line ranges in bounded memory.

The built-in coding tools in packages/durable/src/tools/** all require an environment from HarnessOptions.env. packages/…/index.ts exports CodingTools/createCodingTools() with read, write, edit, and bash. read in packages/…/read.ts resolves model-aware path variants, opens a stable binary reader, detects supported image types, returns text with line/byte truncation diagnostics or one image block, and optionally uses an ImageProcessor. write and edit in packages/…/write.ts and packages/…/edit.ts serialize per-file mutations through packages/…/file-mutation-queue.ts; edit normalizes line endings, supports exact/fuzzy replacements from packages/…/edit-diff.ts, writes a unified patch in details, and refuses ambiguous or no-op replacements. bash and powershell in packages/…/bash.ts run commands through ExecutionEnv.exec(), retain tail output, expose structured { output, truncated, fullOutputPath?, exitCode }, and return nonzero exits as error results rather than thrown exceptions. packages/…/path-utils.ts normalizes model-produced paths such as @file and Unicode-space variants.

Code mode is implemented in packages/durable/src/codemode/**. createCodemodeExtension() in packages/…/codemode.ts installs a replay-safe codemode tool plus a codemode prompt section generated by packages/…/describe.ts. The tool runs JavaScript in a host-supplied @earendil-works/pi-codemode sandbox; scripts call tools.<name>(), searchTools(), describeTool(), describeNamespace(), store()/load(), output helpers, and optional models.* globals. To survive restarts, pi.codemode.run stores deterministic start data, sandbox fingerprint, output directory, and final outcome; pi.codemode.journal stores delivered results and acknowledged call counts; pi.codemode.store is a rewindable conversation document for script state. Nested tool calls use keys c<VM call id> so replays reattach to existing pi.tool tasks. packages/…/models.ts maps paid models.classify() and models.generateImages() script calls to hidden internal durable tools with usage accounting, while catalog lookups are journaled globals. packages/…/output.ts formats script output, cuts to token budgets, writes full output/images to temp files through the environment, and warns when generated images were not shown.

Image handling has two entry points. packages/…/index.ts builds a Photon/WASM ImageProcessor that decodes images, applies EXIF orientation from packages/…/exif.ts, resizes to model limits, and re-encodes PNG/JPEG until the base64 size fits. packages/…/node.ts loads Photon WASM on Node and normally runs image preparation in a worker thread from packages/…/node-worker.ts, falling back in-process if a worker cannot start. packages/…/cloudflare.ts imports the compiled WASM module for Workers. packages/…/fit.ts provides fitImage()/fitImages() for host inputs and createFitImagesExtension(), an afterTool hook that fits images in model-facing tool results before they are committed.

Storage backends all implement the same contract from packages/…/types.ts, and the conformance suite in packages/…/storage-conformance.ts verifies ID ownership, receipt ordering, atomic rollback, fork-aware entry/document reads, document histories, scans/cursors, submissions, and detached JSON. packages/…/memory.ts is the detached reference implementation, cloning/freezeing retained writes and returned records. packages/…/storage.ts stores records and document revisions in SQLite tables declared by packages/…/schema.ts; migrations in packages/…/migrations.ts create the schema and add sleeping task status. Node and Cloudflare adapters are packages/…/node.ts and packages/…/cloudflare.ts. packages/…/storage.ts layers persistent append-only JSONL files on top of MemoryStorage: main.jsonl holds commit markers and small/terminal records, live tasks and document contents go to sidecar files, read-only opens skip repair and retry races with writers, and any append failure after memory advanced poisons the storage. packages/…/indexeddb.ts is the browser IndexedDB backend. packages/…/storage.ts integrates with Chord Store by claiming owner-scoped tables and document namespaces; packages/…/commit.ts translates each durable commit into a store series commit with explicit checks and table/document writes.

Testing support is exported from packages/…/index.ts. packages/…/commit-writes.ts commits raw StorageWrite batches; packages/…/runner.ts registers runner-independent storage/env conformance cases with Vitest/Jest-style runners; packages/…/env-conformance.ts verifies ExecutionEnv file, shell, listing, watch, symlink, abort, spill, and cleanup semantics. packages/durable/test/** contains extensive unit/e2e coverage for sessions, storage backends, tools, images, code mode, harness scheduling, recovery, signals, telemetry, and benchmarks. packages/…/worker.ts is a Cloudflare Durable Object fixture that opens Harness over openDurableObjectSqliteStorage(), uses onWake to arm alarms, resumes in constructor/alarm, scripts faux model responses in object storage, and tests eviction/wake behavior.

The package docs in packages/…/README.md describe the public API, concepts, persistence/resume behavior, tools, code mode, signals, compaction, hooks, storage, and Cloudflare wake patterns. Design notes under packages/durable/docs/** cover group commit and durable/suspendable specs and should be kept aligned with changes to packages/durable/src/session/**, packages/…/scheduler.ts, packages/…/tool.ts, and packages/…/generation.ts.

Coupling

Risks

  • packages/…/session.ts and packages/…/writer.ts are sensitive to ordering: if a commit outcome resolves before its publication has updated caches, observers, and scheduler listeners, then waiters may read stale task/submission/document state or miss a wake. The large comments in both files document this invariant, and storage conformance in packages/…/storage-conformance.ts only validates backend receipts, not every higher-level publication ordering consequence.

  • packages/…/scheduler.ts relies on in-memory ownership indexes being updated from every stored task/conversation publication. If a commit path creates tasks or task-owned conversations without writing the membership keys returned by membershipKeys(), abort cascades and idle waits can miss live work, causing Conversation.waitForIdle() to resolve early or a cancelled owner to leave children running.

  • packages/…/generation.ts treats a crash during a model request or deferred poll as a failed attempt, not as an automatic resend, while packages/…/tool.ts reruns interrupted tools only when replay-safe. If recovery bookkeeping around TaskRecord.restarts or checkpoints is changed incorrectly, providers can be double-charged for model work or unsafe tools can execute side effects twice.

  • packages/…/storage.ts intentionally lets memory run ahead of files during commit append and poisons the storage after any append failure once a batch applied. If callers keep using a poisoned instance or if recovery accepts an unconfirmed sidecar tail, reads can expose state that was never confirmed by main.jsonl.

  • packages/…/codemode.ts depends on deterministic sandbox replay and journal ordering. If a global produces non-deterministic output without being journaled, or a nested call is launched before its issued-count acknowledgment is committed, a restart can either diverge incorrectly or run a tool call under the wrong key.

  • packages/…/node-watch.ts cannot guarantee native watcher semantics on every filesystem and falls back to polling for known unreliable cases. If a host forces native mode on network/FUSE-like filesystems, changes may be missed until another event or rescan, affecting code that relies on ExecutionEnv.watch() for resource reloads.

  • packages/…/index.ts and packages/…/node.ts load Photon WASM, whose memory does not shrink in-process. Using createPhotonImages() directly or disabling the Node worker for large images can retain large WASM memory in long-lived processes; createNodePhotonImages() mitigates this by idling out the worker.