Server（服务端）

English

Web 应用放在这里。本包把供应商无关的 Agent Engine、常驻的 Python 和 R 内核、Host 能力边界与 SQLite 仓储组合成一个 HTTP/WebSocket 服务，全部只用标准库写成。领域逻辑属于本目录里那些职责收敛的 service；gateway.py 是把它们组合起来的兼容与传输门面。

在架构中的位置

浏览器
  |  REST 请求 + WebSocket 事件
  v
gateway.py
  |-- 会话领域服务与只读投影
  |-- AgentEngine 适配器（agent_run.py）
  |-- FIFO 执行所有权（execution_coordinator.py）
  `-- 会话拥有、惰性启动且彼此独立的 Python/R 内核 slot
         |
         `-- HostDispatcher -> 权限、工具、Artifact、数据与委派

• Gateway 组合。 gateway.py 建起标准库的 ThreadingHTTPServer，把其余部分都装配进去：路由、REST handler、WebSocket frame 的编解码与续传、会话 runner、各个 service、存储和静态资源。新增算法通常应该放进职责收敛的模块，而不是塞进门面。
• REST 与 WebSocket。 REST 负责有界的请求/响应操作，并提供会话领域的读模型。WebSocket 通道承载实时流：Agent 文本、Action 与 Cell 生命周期、审批、Notebook 更新和终止事件，并做缓冲，让重连的浏览器可以续传。
• 会话服务与投影。 mutation service 管理计划、审阅、Artifact、分支、恢复、会话包、Skill 与删除。projection service 把规范 Ledger、执行、血缘、Context 和 Security 状态转成经脱敏、可以安全交给浏览器的 DTO。投影只是一个视图，它永远不是底层的终止信号或事务信号。
• 内核所有权。 每个 Web 会话通过 SessionRunner 拥有一个 Python slot 和一个 R slot，两者相互独立、惰性启动。execution_coordinator.py 发放 FIFO ticket，让 Agent、用户 REPL、恢复和生命周期这几类写入方不会互相压到一起；中断只会打到持有那把 lease 的确切 owner。Tool-only 路由不会启动前台的会话 slot，不过个别工具可以自己管理一个专用 worker。
• 持久化边界。 持久事实经 Store 仓储写入。WebSocket 状态和活着的内核命名空间只存在于进程内。没有任何事务能同时覆盖 SQLite、工作区文件、内核进程和 socket 投递这四者。

版本化的对外接口

• 只有一个前缀，没有旧别名。 所有对外可达的东西都在 /api/v1 之下，而 API_ROOT 只在 contract.py 里定义一次，因为有两类完全不同的调用方要用它：gateway 按它路由，CLI 按它拼出 daemon 的 URL。它们真的漂移过——openai4s share 把 /api/ 写死，于是它的每一条子命令都撞上 daemon 自己那句「API 是版本化的」拒绝而 404。现在没有版本号的 /api/... 会明确收到那句拒绝，而不是掉进 SPA 外壳、以 200 回一段 HTML。
• 凭据是必需的，不是可选的。 daemon 能执行代码，所以哪怕在 loopback 上，没有 token 也不作答；只有 /health 和 /api/v1/auth/status 例外，后者存在是因为：不能用一个客户端无权读取的响应去告诉它「你需要 token」。?token= 只允许在根页面上换成 cookie——这是白名单，不是做减法：旧的减法规则让 /preview/<id>?token=… 变成一个既种下持久 cookie、又把文件本身交出去的链接。
• 失败只有一种信封。 一次失败带着它一直都有的人类可读 error 文本，外加一个稳定的机器 code，以及把它和结构化日志系在一起的 request_id；这层增补是追加式的，所以只读 error 的客户端不受影响。GatewayError 的文本原样透出，因为 409/413/429 这类拒绝里写的正是用户据以行动的信息。任意异常则是在边界处被投影成安全形态，而不是在信封里被过滤掉：过滤器必须去猜哪些消息是安全的，而它会朝着毁掉那些好消息的方向猜错。
• 读取分页，事件编号。 会话列表是 keyset 分页：一个不透明游标（解析它就等于和排序键耦合）、一个观察出来而非推断出来的 has_more，以及读不出来的游标直接 400，而不是悄悄从第一页重来。WebSocket 事件带一个会话内单调递增的 seq；重连的客户端从自己的游标续传，整段回放包在 replay_begin/replay_end 之间；而一个无法定位到本 daemon 这条流上的游标——epoch 不同，或者根本没有 epoch——会被判成缺口，而不是被采信。
• 一轮由它的 execution 标识。 frame 活得比 turn 长，两个 turn 会重叠，客户端也可以合法地复用 X-Request-Id，所以 processing、两个终止事件和续传窗口上带的都是 execution_id。一个请求也只产出一条权威的失败：内外两层处理器按 job id 交接，所以收尾阶段再出故障，也不会追加第二条与第一条相矛盾的终止记录。
• 一次准入是一条持久记录，不是一种指望。 一条钉住的评论只会被恰好一轮消费，而 reservation id 由客户端在发送之前铸出——服务端铸的 id 对一个丢了 202 的浏览器来说根本不存在，也就无从追问。GET /api/v1/frames/{id}/admissions/{reservation} 会回答它后来怎么了，于是丢了应答的客户端既不必重发（重复干活），也不必放弃这些评论（静默丢失）。状态是从 pin 推出来的——那才是一轮真正消费掉的东西；ledger 只提供关联信息。启动时仍处于 reserved 的，都是崩溃留下的滞留项，会被释放。

完成、Notebook 与恢复边界

• Cell 的结果是回到外层循环的一条 observation，它本身不代表任务完成。要完成，必须有一个单独且有效的、由 Engine 拥有的 finalize_response，或者 Python Cell 内部调用的 host.submit_output(...)。R Cell 根本无法完成任务。
• Stage 1 trusted delivery 开启时，completion 链接只由一个 URL helper 根据精确的不可变 version id 生成。服务端先验证快照作用域、大小和 checksum，再把最终 assistant 消息与 delivery manifest 放进同一事务提交，最后才发带稳定 delivery_id 的链接 text_chunk。若 socket 发布丢失，普通 REST reopen 仍会恢复已提交消息；committed 行与稳定 id 也为未来或运维显式重放提供依据，但 Stage 1 的 delivery ledger 不会自行驱动重发。普通的有界 WS 序列缓冲在 turn 仍存活时可能重放；终态或重启后以 REST 为准。验证或审计失败则不发布成功链接。
• 再次捕获当前 head 的相同字节会复用 version，同时追加一条限定作用域的 capture observation，保留新的 producing Cell 与 lineage；原 version 的 producer/provenance 不会被改写。Stage 1 的 observation 只在本地，Session package、share 与 export 还不会序列化它。
• Stage 1 的 standard-profile 准入完全在本地且没有副作用。普通 turn 仍可走原生工具或结构化完成；一旦路由出 Code Cell，系统会在应用 pending environment、分配身份/attempt、运行安全检查或启动 runtime 之前拒绝。直接 Cell 共用同一边界；批准/恢复的科学 plan 仍在状态切换前检查。UI 持久显示 banner 与只复制不执行的受管修复卡。修复会先构建并验证新的 Python/R generation，再移动指针。
• 只包含 host.submit_output 协议调用的 Cell 照样会执行，也会留在原始执行历史与审计记录里，但实时和重新打开的 Notebook 投影会把它过滤掉。.ipynb exporter 读的是没有套用该过滤的不可变执行历史，所以它导出的是 raw/audit 版本，可能带上这个系统 Cell。
• 恢复执行已经接入 REST/UI、FIFO 所有权和 Python/R 候选内核流水线，但仍然是 Partial：不安全或非确定性的 Cell 会被归类为 never；系统不会去序列化任意的历史命名空间；某个语言的候选内核如果无法变为 active，整个恢复可以就此停下并给出显式的 Partial 结果。

文件

子目录

修改注意事项

• gateway.py 要一直是组合与兼容门面，只做外科式修改。新的领域行为放到真正拥有它的那个 service 里。
• 只要动到内核生命周期、WebSocket 流、执行所有权或 Artifact 捕获，除了跑聚焦测试，还必须在真实浏览器里端到端跑一遍。
• 交给浏览器的 DTO 必须有界且脱敏。原始供应商 payload、工具参数、凭据和不受限的文件系统路径都不该出现在投影里。

另见仓库架构指南、Web 应用指南与 webui/ README。