archwall 把架构画全Every architecture, drawn in full

pi-durable：先把智能体进度存好再显示pi-durable: store agent progress before showing it

piagentsdurable-executionstorage

pi-durable: the parts: The host supplies an application UI, models, extensions and settings. Harness admits input and schedules generation, tool and compaction tasks. Session atomically commits transcripts, task checkpoints, submissions and Chord documents to a selected storage backend. Committed changes feed conversation views and agent events back to the host. Storage choices are memory, Node SQLite, JSONL and Cloudflare Durable Object SQLite. This package is experimental.

pi-durable 是 Pi 中的实验性智能体运行时。对话、任务检查点和 JSON 文档一起提交，提交成功后再更新界面。

输入启动模型或排队。生成任务准备上下文，经 pi-ai 调模型，再执行工具。结果进入下一轮，除非本轮结束运行；按设置自动压缩上下文。

A model and tool turn: Input is durably admitted and, when the conversation is busy, queued as a steer or follow-up. Generation prepares context, prompt sections and offered tools. Compaction summarizes older context when needed. pi-ai calls or polls the model; streamed progress and the response are committed. Tool calls become tasks with validated arguments and before/after hooks. Tool calls may use the host-provided ExecutionEnv; the built-in coding tools require it. Committed tool results feed the next model request unless the round ends the run; when every result of the round sets control.terminate = true, the run ends instead. An answer without further tool calls ends the turn. At the final boundary, the input settles unless an eligible onYield continuation starts a new generation. Retry and deferred-provider polling are generation phases.
一次模型与工具调用

外部执行前存意图，后存结果。重开恢复检查点，不派发任务；resume、新提交或等待才继续。工具已存和当前策略都允许安全重放才重跑，否则报中断。外部副作用仍需幂等。

Commit before publication: An external effect is surrounded by durable commits: first record its intent, then call a model or tool outside the Session transaction, then record the outcome and publish committed state. On reopening, surviving running tasks become pending at their stored checkpoint; it dispatches nothing. Resume, a submission or a wait starts the scheduler. An interrupted tool reruns only when its stored and current policies both say replay safe; otherwise it produces an interrupted error. Replay-safe external effects need their own idempotency. A storage failure closes the Harness; reopen consistent committed storage to recover.
提交、外部执行与重启恢复

分叉独立继续，重置保留历史。文档存配置、进度和应用状态；Chord 发布已提交变化。任务拥有子工作，后台标记形成取消边界。

State and owned work: Immutable entries form a conversation transcript. Forks inherit parent entries through a selected entry and continue independently. Reset changes the model context while retaining older stored entries. Compaction replaces older context with a summary. Typed JSON documents track live progress, inbox, agent configuration, provider identity, usage and application state. Chord delivers committed views and document changes; agent events and the task graph are derived views. Tasks may own child tasks or conversations; waiting and completing states keep ownership structured. Abort proceeds from owned children to parents. Background tasks form a boundary for parent abort and idle waits.
对话、文档与任务归属

宿主安装扩展、提供环境。编码工具需安装，图片处理、工具搜索与代码模式可选。代码模式需沙箱，用日志重放。重启需重装扩展代码。

What the host installs: The host installs named extensions into an in-memory registry. Extensions supply tools, prompt sections, hooks, wrappers and custom tasks. Conversations store names and agent choices, not extension code; reinstall code after restart. Reload replaces an extension in place; already running code keeps its implementation. CodingTools is installed explicitly and uses ExecutionEnv for files and processes. An optional Photon image processor converts and resizes read images. Optional tool-search loads deferred tools for a later model request. Optional codemode takes a host-provided sandbox: scripts discover and call nested tools, and start data plus a result journal let deterministic execution replay after a restart.
宿主安装的扩展

内存临时；SQLite、JSONL、Durable Object SQLite 持久化，本地断电仍可能丢最近提交。存储由单进程拥有，错误关闭运行时，重开恢复。

Storage backends and ownership: The host chooses a storage implementation. Memory is temporary and stores detached copies. Node SQLite stores records and document bases plus deltas; a SQL transaction is a Session commit. Its WAL and synchronous NORMAL settings cover process crashes, while a recent commit may be lost on host or power failure. Cloudflare uses the SQLite storage of a Durable Object with its transactions. JSONL writes prepared sidecars and then a main commit marker; recovery keeps confirmed records. JSONL fsync is optional and does not promise an acknowledged tail survives power failure. It also retains history in memory. A storage has one process owner and no cross-process locking. Custom backends and environments can use shared conformance tests.
存储后端与使用边界

pi-durable is an experimental agent runtime inside Pi. It commits conversations, task checkpoints and JSON documents together, then publishes progress to the UI.

Input starts a model run or enters its inbox. Generation prepares context and prompt sections, calls pi-ai, then schedules requested tools. Their results feed the next turn unless the round ends the run. Compaction summarizes older context; settings enable automatic compaction.

A model and tool turn: Input is durably admitted and, when the conversation is busy, queued as a steer or follow-up. Generation prepares context, prompt sections and offered tools. Compaction summarizes older context when needed. pi-ai calls or polls the model; streamed progress and the response are committed. Tool calls become tasks with validated arguments and before/after hooks. Tool calls may use the host-provided ExecutionEnv; the built-in coding tools require it. Committed tool results feed the next model request unless the round ends the run; when every result of the round sets control.terminate = true, the run ends instead. An answer without further tool calls ends the turn. At the final boundary, the input settles unless an eligible onYield continuation starts a new generation. Retry and deferred-provider polling are generation phases.
A turn: admit input, prepare context, call the model, run tools

External work sits between an intent commit and an outcome commit. Reopening loads stored checkpoints but dispatches nothing; resume, a new submission or a wait starts the scheduler. An interrupted tool reruns only when its stored and current replay policies both say safe; otherwise it returns an interruption error. External effects still need idempotency.

Commit before publication: An external effect is surrounded by durable commits: first record its intent, then call a model or tool outside the Session transaction, then record the outcome and publish committed state. On reopening, surviving running tasks become pending at their stored checkpoint; it dispatches nothing. Resume, a submission or a wait starts the scheduler. An interrupted tool reruns only when its stored and current policies both say replay safe; otherwise it produces an interrupted error. Replay-safe external effects need their own idempotency. A storage failure closes the Harness; reopen consistent committed storage to recover.
Intent, external work, outcome and recovery

Forks continue from a chosen entry. Reset keeps stored history. Documents hold configuration, progress and application state. Chord views and events expose committed changes. Tasks own child work; background tasks (background: true) form an abort boundary.

State and owned work: Immutable entries form a conversation transcript. Forks inherit parent entries through a selected entry and continue independently. Reset changes the model context while retaining older stored entries. Compaction replaces older context with a summary. Typed JSON documents track live progress, inbox, agent configuration, provider identity, usage and application state. Chord delivers committed views and document changes; agent events and the task graph are derived views. Tasks may own child tasks or conversations; waiting and completing states keep ownership structured. Abort proceeds from owned children to parents. Background tasks form a boundary for parent abort and idle waits.
Transcripts, documents, observation and owned work

The host installs extensions and supplies execution environments. CodingTools needs installation; image processing, tool-search and codemode are optional. Codemode needs a sandbox and journals results for deterministic replay. Reinstall extension code after restart.

What the host installs: The host installs named extensions into an in-memory registry. Extensions supply tools, prompt sections, hooks, wrappers and custom tasks. Conversations store names and agent choices, not extension code; reinstall code after restart. Reload replaces an extension in place; already running code keeps its implementation. CodingTools is installed explicitly and uses ExecutionEnv for files and processes. An optional Photon image processor converts and resizes read images. Optional tool-search loads deferred tools for a later model request. Optional codemode takes a host-provided sandbox: scripts discover and call nested tools, and start data plus a result journal let deterministic execution replay after a restart.
Host-installed extensions, environments and script execution

Memory is temporary. SQLite, JSONL and Durable Object SQLite provide persistence with different failure boundaries. Local persistence does not guarantee the latest commit survives power loss. One process owns a store. Storage errors close the Harness; reopen to recover.

Storage backends and ownership: The host chooses a storage implementation. Memory is temporary and stores detached copies. Node SQLite stores records and document bases plus deltas; a SQL transaction is a Session commit. Its WAL and synchronous NORMAL settings cover process crashes, while a recent commit may be lost on host or power failure. Cloudflare uses the SQLite storage of a Durable Object with its transactions. JSONL writes prepared sidecars and then a main commit marker; recovery keeps confirmed records. JSONL fsync is optional and does not promise an acknowledged tail survives power failure. It also retains history in memory. A storage has one process owner and no cross-process locking. Custom backends and environments can use shared conformance tests.
Backend choices and their persistence boundaries

来源Source: github.com

← 全部架构← All architectures