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
-
If the
Storageinterface or record shapes in packages/…/types.ts change, update every backend underpackages/durable/src/storage/**and the conformance suite in packages/…/storage-conformance.ts. The session and scheduler rely on backend behavior such as commit receipts before resolution, fork-aware entry visibility, document copy/refusal semantics, and globally monotonic IDs; a backend that accepts the old shape can make recovery or fork reads silently wrong. -
If task statuses or document semantics change in packages/…/types.ts, update SQLite schema/migrations in packages/…/migrations.ts, IndexedDB object stores/indexes in packages/…/indexeddb.ts, JSONL validation/recovery in packages/…/storage.ts, Chord Store table/index mapping in packages/…/tables.ts, and
MemoryStorageindexes in packages/…/memory.ts. Backends index statuses and document address fields independently rather than deriving them from a shared schema at runtime. -
If commit publication, deferred persistence, or group-commit rules change in packages/…/session.ts, also review packages/…/writer.ts, packages/…/transaction.ts, packages/…/scheduler.ts, and packages/…/storage.ts. The scheduler's decision regions and StoreStorage's
publishing()integration assume publications occur in line order and that reads wait on unpublished writers by key. -
If generation run state in packages/…/live.ts changes, update packages/…/generation.ts, packages/…/tool.ts, packages/…/compaction.ts, packages/…/submissions.ts, packages/…/context.ts, and UI-facing views in packages/…/view.ts.
pi.liveis both scheduler bookkeeping and presentation state, and deferred progress commits rely on its checkpoint policy staying small when no generation/tool is running. -
If the tool result contract in packages/…/types.ts or packages/…/tool.ts changes, update built-in tools in
packages/durable/src/tools/**, code mode result mapping in packages/…/codemode.ts, image fitting hook in packages/…/fit.ts, and README tool docs. Model-facing output, program-facingstructuredOutput, UIdetails, diagnostics, replay policy, parks, and nested-call storage are deliberately separate channels. -
If
ExecutionEnvchanges in packages/…/index.ts, update packages/…/node.ts, packages/…/node-watch.ts, built-in tools inpackages/durable/src/tools/**, JSONL storage in packages/…/storage.ts, code mode output file writing in packages/…/output.ts, and env conformance in packages/…/env-conformance.ts. The env API is the only file/process boundary for tools and JSONL persistence. -
If image limits or processor behavior changes in packages/…/image-processor.ts, also update packages/…/read.ts, packages/…/index.ts, packages/…/fit.ts, packages/…/node.ts, and image tests under packages/…/images-*.test.ts and packages/…/tools-images.test.ts. The read tool and fit-images hook both depend on the same
ImageProcessorcontract but apply it at different points: file read vs pre-commit transcript fitting. -
If registry/agent resolution changes in packages/…/agent.ts or packages/…/registry.ts, check packages/…/tool-search.ts and packages/…/describe.ts. Deferred tools and extension namespaces are resolved from selected extensions, and code mode snapshots tool declarations at script start for deterministic replay.
-
If code mode replay data changes in packages/…/codemode.ts, bump
CODEMODE_MODULE_VERSIONand update tests in packages/…/codemode*.test.ts. Oldpi.codemode.run/pi.codemode.journaldocuments are interpreted during replay; replaying with different result mapping, globals, sandbox input, or declaration generation can cause scripts to continue along a path they did not originally take. -
If Cloudflare wake behavior changes in packages/…/scheduler.ts or
HarnessOptions.onWakein packages/…/types.ts, update the README's Durable Object example and packages/…/worker.ts. Hosts using alarms must arm a recovery wake before calls that can start work; otherwise sleeping or just-admitted work can be stranded after eviction.
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, causingConversation.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.restartsor 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.