Session
来源:modules/sandboxes/lifecycle.ts。
Run
来源:modules/execution/runs.ts。
Runtime binding
来源:modules/execution/worker.ts。
Sandbox 资源
来源:modules/sandboxes/connector.ts。
资源操作
来源:modules/sandboxes/operations.ts。
转换与观察
正常 Run 由 queued → provisioning → running → completed。失败、授权、审批、取消与 worker 恢复会产生其他分支;这不是只能顺序前进的 UI 进度条。run.claimed 描述 worker 领取及 generation,不是一个名为 claimed 的 Run 状态。run.recovery_needed 可以在保留当前状态时写入恢复错误,不是新终态。
Runtime 进程调用还有自己的 starting、running、cancelling、exited、cancelled、failed、interrupted 状态,见 Runtime。exited 只表示进程退出,worker 仍需解析结果并导出产物,不能直接映射为 Run completed。数据库 Runtime binding 与该调用状态也不是同一个字段。
转换条件与分对象状态示例
以下示例分别摘取不同对象的字段,不是一个组合 API 响应,也不是真实执行记录。判断下一步动作时应读取当前记录。
普通 Run 路径为
queued → provisioning → running → completed。worker 的转换方法还允许 queued、provisioning、running、两种等待状态及 cancelling 进入 failed。授权、审批和 Tool 处理器另有等待/恢复转换,不能把 worker 的转换表当作完整状态机。取消已终态或已在 cancelling 的 Run 时保留原状态。
暂停/恢复已经处于匹配的目标状态时直接返回,不启动另一次转换;暂停 scope 不同则冲突。同 scope 的未完成转换进入对账路径。原生暂停/恢复结果不确定时,控制平面检查原资源,不盲目重复远程操作。Provider 管理的自动待机与显式暂停计算资源也需要分别判断。
到期清理与显式关闭不同:它可以先隔离活动 Run 的执行权、使待定审批过期,并记录带有 reason: sandbox_expired 的 run.cancelling,再完成资源清理。因此,关闭按钮与到期 worker 的前置条件并不相同。
session.pausing、session.paused、session.resuming、session.resumed 持久化在独立的内部 session_lifecycle_events 表中。它们不是下文 Run 事件 API 承诺提供的事件。观察生命周期操作时,应刷新 Session 记录。
来源:Session 生命周期、Run 转换与取消、Runtime worker、镜像准备与清理、Tool broker。
事件 envelope 与游标
{events:[...]},每条包含 id、type、data、created_at;SSE 在 id/event/data 字段传递事件,SDK 解析结果不附加数据库 created_at 字段。SSE 片段:
after 优先于 Last-Event-ID,默认 0。应用按 Run/id 去重,在同一事务保存事件和游标。只在收到数据后更新游标不足以保证应用持久化。
每约 15 秒可能收到无数据的 keepalive 注释。终态且事件排空后发送 stream.end,payload 为 {state: ...},没有 id,不是持久事件。客户端断开只停止观察,不取消 Run。空页不证明终态,流结束后查询 Run。实现见 HTTP SSE与 Runs。
主要事件及 payload
字段由生成路径决定,不把示意列当作严格 JSON schema。Tool 事件来源:broker、reconciliation;产物见 artifacts。
tool.outcome_unknown 表示需要调查的外部结果,不等于新的审批请求;查询原 tool call 的 hash、策略和状态再操作。
模型与受保护 API 的传输事件
model.response 和 protected_api.response 记录与 Run 关联的授权访问所产生的认证传输事实。data 包含 connection_id、可为空的 HTTP status、transport(已知状态时为 received,否则为 failed),以及提供时的 connection_version。生成器不写入请求头、prompt 或响应正文。未绑定 Run ID 的公共访问授权不会产生此 Run 事件。
status: 200 只证明收到 HTTP 响应,不证明模型完成任务或 Tool 写入成功。status: null 则保留远程结果的不确定性。这些事件不同于 ToolBroker 的 tool.completed,也不同于最终 run.completed。依据:ConnectionAccess.recordModelOutcome。
Runtime 与派生活动事件
Runtime ingest 用来源键去重保存事件,再可能从harness.stdout 派生一条规范化活动事件。新增事件有独立的持久事件 ID,不代表第二个 Runtime cursor。这些是可观察的进程与输出记录,不是模型私有推理。
活动投影函数只接受完整、以换行结尾且不超过 65536 个 JavaScript code units 的 JSON 字符串。它识别选定的 OpenClaw、item 类和 tool/text 事件结构,不会规范化任意输出或全部 Harness。名称截断为 256、ID 为 512、消息文本为 32768 个单位。没有规范化活动不等于没有执行工作。不要无条件拼接
agent.message 和 agent.message.delta,也不要用它们覆盖 Run 的权威输出。
来源 envelope 由 Runtime生成;text 内的原生 JSON 仍与 Harness 版本有关。安全保留未知记录,解释时查询对应 Harness 契约。本节示例用于说明源码定义的 payload,不是实际任务日志。
根据关联记录选择操作
例如,
{"type":"tool.outcome_unknown","data":{"call_id":"example-call"}} 应引导界面进入调查,它没有审批 ID。而 {"type":"approval.required","data":{"id":"example-approval","action":{"summary":"illustrative operation"}}} 指向一个决策记录,action 的结构取决于生成路径。这些是 payload 示意,不是 UUID 合法、可直接重放的请求。
事件描述已经发生的事;判断当前可执行动作需要查询对象现状。broker 和决策处理器在部分路径直接更新 Run 状态,因此不能只去掉事件名称的 run. 前缀来推算当前状态。
消费端要求
对未知事件类型保留或忽略展示,不崩溃,不凭它制造状态转换;按实际 payload 判别,不无条件读取字段。Tool completed 可能携带错误结果或代表拒绝后的交付,不能直接当成副作用成功。caller_verified 是人工核实结论,不是服务端再次访问 Provider 的证明。 重连原 Run,别重新提交;结果未知先对账。分别展示 Run 终态、Session 状态、连接可达性与清理状态,避免一个绿色成功标签掩盖未知资源。 恢复模型见持久事件,运维检查见可观测性。SDK 事件解析实现分别位于 Python 与 TypeScript。按事件列出的 payload 示例
以下示例按源码结构覆盖前文当前固定事件类别,包括无编号的传输结束标记。每行只展示data,不是完整 envelope。ID、摘要、时间和内容都是示意;全零哈希是占位符,不是字节完整性回执。这些行不构成一次按时间排序的执行记录。转换 data 为空是合法情况;恢复诊断、审批 action 和原生输出可能包含路径特定的其他字段。仍需安全处理未来或 Provider 特定的未知事件。
事件发出边界与开放的事件类型
上方固定 payload 示例覆盖 35 个持久事件名称,以及单独的stream.end 传输标记。这是当前源码清单,不是封闭的事件类型枚举:Runs.ingest 按 Runtime 提供的 type 保存记录,共享 Runtime 契约也可能演进。未知事件类型必须能安全保存或忽略,不能由新名称推导一个新的 Run 状态。
Session 生命周期事件另存在一张表中,不因此成为 Run 流的一部分。事件发出位置必须与直接状态更新一起审阅:审批、拒绝授权或完成 Tool 调用都可能改变 Run 状态,而没有对应的
run.running 事件。
每个状态值的最小样例
每个单元格中都是相互独立的示意投影,不是某个同时包含多个候选状态的响应;省略了必要标识和其他字段。结合上文转换条件阅读,不能把样例当成强制设置状态的命令。
Sandbox 状态仍是开放的 Provider 字符串。还需区分控制平面的一个投影:Session 成功关闭时,若此前有 Sandbox 对象,保存的对象会写入
{"state":"destroyed"}。这是保留的生命周期投影,不是新获取的 Provider inspect 响应,也不是所有供应商的统一枚举。连接器的 inspect(id) === null 另表示缺失结果,不是一个 state 等于 null 的资源。参见关闭逻辑。
生命周期动作是有条件的转换
同一种 Session 状态可能对应不同计算策略。需结合pause_scope、声明能力和持久操作回执判断。以下说明动作前提与观察规则,不是可代替服务端校验的客户端状态机。
依据:changePause、checkpointTransition、worker 准备流程。
审阅状态不等于操作结果已确认
只有当前为unknown 的操作接受以下审阅动作。审阅历史与调度修改先持久化,再按需执行对账。HTTP 成功响应仍可能包含 reconciliation_error;读取返回的操作结果,不能把状态码当作清理回执。
即使 Session 仍处于 closing,
completed、rejected 或 deleted 的操作也不会因此变得可审阅。找到实际未决操作,并保留其私有标识。依据:ResourceOperations.review;操作流程见资源对账。
默认值与参数化状态写入
新记录的初始值分别为 Sessionopen、Run queued、Runtime binding reserved、资源操作 pending;操作审阅初始值为 automatic。依据是初始 schema、Runtime binding schema与审阅 schema。大部分生命周期状态列是 text,不是数据库强制约束的枚举;本页描述当前实现会写入的值。客户端需能容纳未来值,但不能自行推导转换。
关闭对账与采用资源继续执行的条件不同。provision / restore 需要唯一匹配;close 可以将原操作的多个精确匹配保存在
reconciled_ids,并尝试清理这些归属明确的资源,零匹配仍保留创建未确认。在这一清理对账过程中将原 create 操作标记 completed,不证明 Agent invocation 成功,也不代表独立的 delete 操作已经完成。依据:closeSession。
状态写入源码清单记录了当前非测试 TypeScript 应用 / 模块 / 集成中,这四张表的 45 处插入或状态更新查询;动态查询表达式另列供审阅。这证明源码覆盖范围,不代表所有转换都已在数据库或 Provider 上实际执行。
下一步:事件流指南、恢复、对账。