PysolateExplained
打开文档导航
本科生解释查看 Markdown 源文件

Broker、Approval 与唯一 dispatch

一句话

每次 capability call 都必须经过同一套 Broker authority seam。具体 Broker instance 绑定一个 Run/attempt 的 Plan、调用身份和预算，并协调 Approval Controller 后才能 dispatch handler。

先看一个例子

设想一个 Agent 准备调用“发布报告”。这个操作需要人工批准。

Agent 提交请求后，系统不能把“等待批准”和“执行发布”交给两个互不知情的组件。否则可能出现：审批页面显示已批准，网络重试又发布一次；或者请求已取消，另一个线程仍然开始执行。

Pysolate 把过程排成一条窄通道：先验票，再等待批准，最后在一个明确时刻把请求交给 handler。批准只表示“现在可以进入执行门”，不表示报告已经发布。

真实机制

Broker 的 live call 顺序可以简化为：

Guest request
   ↓
检查 frame、call identity、origin、预算和 Plan lookup
   ↓
按 input schema canonicalize arguments
   ↓
需要时进入 Approval Controller 等待决定
   ↓
BeginDispatch：把批准与实际启动线性化
   ↓
每个跨过 BeginDispatch 的 call 至多发起一次 live handler attempt
   ↓
校验 result/effect evidence，生成 receipt

Approval Controller 拥有 proposal、lease、approve/reject 和 approval state，不直接执行 handler。Broker 咨询它，并在批准后调用 BeginDispatch。如果 lease 已过期或 context 在这个点之前取消，handler 调用次数为零；跨过该点的 call 至多发起一次 live handler attempt。一旦 dispatch 已 commit，后来的取消不能被解释成“外部操作肯定没有发生”，这里也不构成 external exactly-once 保证。

WASM Guest 通过 agent_runtime_v1.host_call 进入本次 Wazero Broker。Native Guest 先经过带 invocation、execution、credential 和 Plan identity 检查的 Unix HTTP channel，再调用该 native attempt 专属的 Broker。Instance 不同，Broker implementation 和 authority seam 相同。

对于 native transport，同一 call_id 的已完成响应可以被重新取得；仍在执行或结果未知时返回 ambiguous。这个机制避免 transport retry 再次调用 handler，但它不是跨任意崩溃场景的通用 exactly-once 保证。

为什么重要

技术上： admission、approval 和 dispatch 的顺序由一个 owner 维护。系统可以区分“尚未获准”“获准但尚未开始”“已经开始”和“结果不确定”，减少并发、取消和重试造成的重复 effect。

产品和业务上： 需要人工审批或严格预算的 Agent 操作可以停在真正执行之前。审批记录与调用身份绑定，操作者批准的是某次具体请求，而不是给整个 Python 进程永久放行。

不能推出什么

  • Approval 不等于 effect 已发生；只有 BeginDispatch 后 handler 才可能开始。
  • Cancel 不能撤销已经 dispatch 的外部 effect。
  • 两条 transport 共用 Broker 语义，不代表它们的 response、进程生命周期和 evidence 实现逐字节相同。

术语卡

  • Broker：一个 Run/attempt 的 capability admission 与 dispatch coordinator；approval state 由 Controller 拥有。
  • Approval：Host 对具体调用作出的有期限决定。
  • Admission：在 handler 启动前执行的身份、预算与 schema 检查。
  • BeginDispatch：批准状态与 handler 启动之间的线性化点。
  • Handler：真正执行 capability 的 Host 代码。

继续阅读