durable@earendil-works/pi-durable

要点Key points

• 11 个导入路径让宿主只加载需要的部分：例如 ./storage/sqlite 与 ./storage/jsonl 的可移植核心不依赖 Node API，可以跑在 Bun 或 Cloudflare Durable Object 上。11 import paths let a host load only what it needs: the portable cores ./storage/sqlite and ./storage/jsonl, for example, need no Node APIs and run on Bun or in Cloudflare Durable Objects.
• 最大的文件是 harness/scheduler.ts：它拥有所有活任务的调度、恢复、所有权与中止。The largest file is harness/scheduler.ts: it owns scheduling, recovery, ownership and abort for every live task.
• 包根会加载 TypeBox（工具参数校验用 pi-ai 的 validateToolArguments()）；README 给出的代价约 23 MB 峰值 RSS，tree-shaken 打包后约 4 MB。The package root loads TypeBox (tool arguments are validated with pi-ai's validateToolArguments()); the README puts the cost at about 23 MB of peak RSS, about 4 MB tree-shaken.

工作原理How it works

1. const harness = await Harness.open(storage, { models, registry }, ctx)。const harness = await Harness.open(storage, { models, registry }, ctx).
2. const root = await harness.root(ctx, { agent })，然后 root.submit({ type: "input", content }, ctx)。const root = await harness.root(ctx, { agent }), then root.submit({ type: "input", content }, ctx).
3. await (await …submit(…)).wait(ctx) 得到 done 或带原因的 unanswered。await (await …submit(…)).wait(ctx) gives done or unanswered with a reason.

要点Key points

• conversation.commit(tx => …) 可以在一次原子写入里追加条目、改文档、建任务——要么全部存下，要么全不存。conversation.commit(tx => …) can append entries, edit documents and create tasks in one atomic write — all of it is stored or none of it.
• Conversation 句柄不持有状态，按 id 比较；模型只看到最新一个 pi.reset 之后的条目，旧条目仍留在存储里。A Conversation handle holds no state; compare by id. The model sees entries from the newest pi.reset on; older ones stay in storage.
• Registry 不被存储：扩展被卸载后，选它的会话只是暂时拿不到它，名字仍保留，重新安装就恢复。The Registry is not stored: after an extension is uninstalled, conversations that select it just stop getting it; the name stays and reinstalling restores it.
• settings（重试、压缩、进度间隔、排队模式…）每次使用时读取、从不存储，所以可以用 getter 让它实时生效。settings (retry, compaction, progress intervals, queue modes…) are read at every use and never stored, so getters make them live.

工作原理How it works

1. defineEntry("app.note")、defineDoc({ kind, version, scope, history, fork, initial }) 定义你自己的记录。defineEntry("app.note") and defineDoc({ kind, version, scope, history, fork, initial }) define your own records.
2. root.configure({ model, tools, cwd, … }, ctx) 在一次提交里改 pi.agent；null 把字段清回宿主默认。root.configure({ model, tools, cwd, … }, ctx) changes pi.agent in one commit; null clears a field back to the host default.
3. harness.createConversation() / root.fork(entryId, …) 建更多会话；分叉拿到新的 provider 会话 ID。harness.createConversation() / root.fork(entryId, …) create more conversations; a fork gets a fresh provider session ID.

要点Key points

• generation 的检查点阶段：prepare → request → retry（退避重试，默认最多 3 次）→ poll（延迟回答，默认每 5000 ms）→ tools。Generation checkpoint phases: prepare → request → retry (back-off, up to 3 by default) → poll (deferred answers, every 5000 ms by default) → tools.
• pi.tool 在运行 execute() 前先提交意图。崩溃后只有声明 replay: "safe" 的工具会重跑；其余给模型一个 interrupted 错误结果，附带已提交的输出。pi.tool commits its intent before execute() runs. After a crash only tools declared replay: "safe" rerun; others give the model an interrupted error result with the output committed so far.
• 部分回答和工具输出默认最多每 100 ms 提交一次，所以崩溃最多丢这么一个窗口。Partial answers and tool output are committed at most every 100 ms by default, so a crash loses at most that window.
• 上下文过长被拒时，generation 先压缩再重试一次；reserveTokens 之上的请求会等一次压缩完成。When a provider rejects a request for being too long, generation compacts and retries once; above reserveTokens, the next request waits for a compaction.

工作原理How it works

1. 重启：用同一个存储 Harness.open()，harness.root(ctx) 拿到同一个根会话，harness.resume() 启动调度器。Restart: Harness.open() on the same storage, harness.root(ctx) returns the same root, harness.resume() starts the scheduler.
2. 提交时带 requestId：重启后同一个请求再提交会拿到原来那个 submission，不会提交两次。Submit with a requestId: after a restart the same request returns the existing submission instead of submitting twice.
3. harness.submission(id) 按 ID 重新拿到一个 submission，再 wait()。harness.submission(id) reacquires a submission by ID; then wait().

要点Key points

• 每次状态转换都在 Session 的提交线上串行完成；重启后 running 的任务显示为 pending，直到再次运行。Every transition is serialized on the Session's commit line; after a restart, tasks that were running show as pending until they run again.
• orphaned 表示定义或迁移不可用（例如扩展没装回来）；faulted 是运行时发现的违约，如未捕获的异常或没有持久进展。orphaned means the definition or migration is unavailable (e.g. the extension was not reinstalled); faulted is a contract failure the runtime detects, such as an uncaught throw or no durable progress.
• 中止自下而上：先中止它拥有的工作，等那些结束后才运行它自己的 abort 处理——每个任务只撤销自己的效果。Abort runs bottom-up: owned work is aborted first and the task's own abort handler runs only once that is done — each task undoes its own effects.
• { background: true } 的任务是边界：它拥有的工作不受父中止影响，也不让父会话忙碌（subagent 的后台模式就靠它）。A { background: true } task is a boundary: its work survives the parent's abort and does not keep the parent busy (background subagents rely on it).

工作原理How it works

1. defineTask({ name, version, initial, phases, abort, migrate? }) 定义任务：每个阶段返回下一个状态（running / waiting / terminal）；abort 在中止标记后必须提交一个终态结果。defineTask({ name, version, initial, phases, abort, migrate? }) defines a task: each phase returns the next state (running / waiting / terminal); abort must commit a terminal outcome after an abort mark.
2. 在 runtime.commit() 里 tx.createTask(Kind, input, { ownership: { kind: "task", taskId } }) 建子任务，再返回 { status: "waiting", on, policy }。Inside runtime.commit(), tx.createTask(Kind, input, { ownership: { kind: "task", taskId } }) creates children; then return { status: "waiting", on, policy }.
3. harness.taskGraph(ctx) 把所有活任务显示为一个 chord state；harness.inspect() 报告被缺失定义阻塞的任务。harness.taskGraph(ctx) shows every live task as one chord state; harness.inspect() reports tasks blocked by a missing definition.

要点Key points

• steeringMode / followUpMode 默认 "one-at-a-time"：每轮放一条；设为 "all" 时一次放入全部排队项。steeringMode / followUpMode default to "one-at-a-time": one per turn; "all" places every queued item at once.
• run 失败时排队项留在 inbox，等下一次提交时按先后放入。If a run fails, queued items stay in the inbox until the next submission places them, oldest first.
• root.abort(ctx) 撤回排队的输入（排队的写入保留）、中止当前工作的所有任务，并在会话空闲时返回。root.abort(ctx) withdraws queued inputs (queued writes stay), aborts every task of the current work and resolves once the conversation is idle.
• reset() 忙时也像写入一样排队；在工具轮中放入时会结束当前 run。工具可以用 control: { handoff } 请求同样的事。reset() is queued like a write while busy; placed during a tool round, it ends the current run. A tool can request the same with control: { handoff }.

工作原理How it works

1. root.submit({ type: "input", content, whenBusy: "steer" }, ctx)。root.submit({ type: "input", content, whenBusy: "steer" }, ctx).
2. UI 直接从 view.docs["pi.inbox"] 画出排队区；submission.abort(ctx) 撤回一条。A UI draws its queue straight from view.docs["pi.inbox"]; submission.abort(ctx) withdraws one.
3. 内部：admitSubmission() 判断忙闲 → 写入 inbox；每个轮次边界 prepareBoundary() / applyBoundary() 决定放入哪些。Internally: admitSubmission() checks busy → writes the inbox; at each turn boundary prepareBoundary() / applyBoundary() decide what is placed.

要点Key points

• history: "rewindable" 的文档可以用 snapshotAsOf() 读旧值；fork 决定分叉时的初值：initial、current 或 asOf。Documents with history: "rewindable" can be read as of the past with snapshotAsOf(); fork decides a fork's start value: initial, current or asOf.
• 慢的 watch() 消费者最多积压 100 帧，之后整队换成一帧完整的最新视图；迟到或重连的客户端从当前视图开始，不重放历史。A slow watch() consumer keeps at most 100 undelivered frames, then they become one frame with the whole newest view; late or reconnecting clients start from the current view, nothing is replayed.
• watchEvents()（实验性）把提交转换成 coding-agent 风格的事件（message_start、tool_execution_start…）；落后超过 100 批时收到一个新的 snapshot 事件。watchEvents() (experimental) turns commits into coding-agent style events (message_start, tool_execution_start…); more than 100 batches behind, it delivers a fresh snapshot event.
• HarnessOptions.conversationCreated(tx, conversation) 在每个创建或分叉会话的提交里运行，适合给每个会话放上你自己的文档。HarnessOptions.conversationCreated(tx, conversation) runs in every commit that creates or forks a conversation — the place to give every conversation your own documents.

工作原理How it works

1. const view = await root.viewState(ctx); view.subscribe(v => render(v))。const view = await root.viewState(ctx); view.subscribe(v => render(v)).
2. const w = await root.watch(ctx); render(w.value); w.start(async (value, ops) => send(ops))——把 op 发给远端客户端重放。const w = await root.watch(ctx); render(w.value); w.start(async (value, ops) => send(ops)) — ship ops to a remote client to replay.
3. 自己的文档：(await tx.doc(Todos, root.id)).items.push("…")；读：harness.snapshot(Todos, root.id, ctx)。Your own document: (await tx.doc(Todos, root.id)).items.push("…"); read: harness.snapshot(Todos, root.id, ctx).

要点Key points

• SQLite：journal_mode = WAL、synchronous = NORMAL、wal_autocheckpoint 1000 页、busy 超时 5000 ms——提交能挺过进程崩溃，断电可能丢最新一个。SQLite: journal_mode = WAL, synchronous = NORMAL, wal_autocheckpoint 1000 pages, a 5000 ms busy timeout — commits survive process crashes; power loss may drop the newest.
• JSONL：每次提交在 main.jsonl 追加一行 { format: 1, type: "commit", seq, writes } 标记；任务与文档的大内容写进 task-<id>.jsonl / doc-<id>.jsonl 旁路文件；{ fsync: true } 在标记前刷盘。JSONL: each commit appends one { format: 1, type: "commit", seq, writes } marker to main.jsonl; task and document payloads go to task-<id>.jsonl / doc-<id>.jsonl sidecars; { fsync: true } flushes before the marker.
• 同一时刻只有一个进程拥有一个存储，没有跨进程锁。One process owns a storage at a time; there is no cross-process locking.
• 自定义后端可以用 registerStorageConformance() 跑共享的一致性套件，任何 Vitest / Jest 兼容的 runner 都行。A custom backend can run the shared suite with registerStorageConformance() under any Vitest- or Jest-compatible runner.

工作原理How it works

1. openNodeSqliteStorage("./session.sqlite") 或 openNodeJsonlStorage(dir, ctx)，交给 Harness.open()。openNodeSqliteStorage("./session.sqlite") or openNodeJsonlStorage(dir, ctx), passed to Harness.open().
2. 非 Node 环境：给可移植核心一个异步的 SqliteDatabase 外观（exec / run / get / all / transaction / close）或一个 FileSystem。Outside Node: give a portable core an async SqliteDatabase facade (exec / run / get / all / transaction / close) or a FileSystem.
3. Cloudflare：openDurableObjectSqliteStorage(ctx.storage)。Cloudflare: openDurableObjectSqliteStorage(ctx.storage).

要点Key points

• 钩子：generation 有 beforeRequest、afterResponse、onYield（{ continue } 让 run 继续）、afterTools；工具有 beforeTool（{ block } 或改参数）、afterTool；压缩有 beforeCompact。Hooks: generation has beforeRequest, afterResponse, onYield ({ continue } keeps the run going), afterTools; tools have beforeTool ({ block } or rewrite arguments), afterTool; compaction has beforeCompact.
• 段与工具的变化存成转录里按位置的 pi.system 条目，只重发变化的部分，让 provider 的提示缓存保持命中；每次都变的段会破坏缓存。Section and tool changes are stored as positional pi.system entries, and only changes are resent, keeping provider prompt caches warm; a section that changes every time defeats that.
• 同名工具后安装的覆盖先安装的；wrapTool() 装饰最后胜出的那个。工具结果带 control: { terminate: true } 且整轮都这样时，run 不再请求模型就结束。A later extension's same-name tool replaces an earlier one; wrapTool() decorates whichever won. When every result of a round returns control: { terminate: true }, the run ends without another model request.
• 重载：同名 install() 原地替换。已开始的工作保留它拿到的代码；每个任务阶段开始时从 Registry 解析一次钩子与 agent，下一阶段才用新代码。Reload: install() with an installed name replaces in place. Started work keeps the code it took; each task phase resolves hooks and the agent once at its start, and the next phase uses the new code.

工作原理How it works

1. defineExtension({ name, tools: [defineTool({ name, parameters, execute })], sections: [section("cwd", i => i.env?.cwd)] })。defineExtension({ name, tools: [defineTool({ name, parameters, execute })], sections: [section("cwd", i => i.env?.cwd)] }).
2. registry.install(ext)；只想在部分会话生效时，用 configure({ extensions: { add: [Ext] } }) 选上。registry.install(ext); to limit it to some conversations, select it with configure({ extensions: { add: [Ext] } }).
3. @earendil-works/pi-durable/tools 的 CodingTools 一次装上 read、write、edit、bash，它们只通过调用的执行环境访问文件与进程。CodingTools from @earendil-works/pi-durable/tools installs read, write, edit and bash at once; they touch files and processes only through the call's environment.