/v1。请求文件必须填入真实标识、哈希和相应证据;示例不是执行记录。
列出审批
GET /v1/runs/{run_id}/approvals 返回 200、{approvals:[...]},按创建时间排序,无分页契约。每项包含 id、run_id、action(JSON)、state、可空 decision、created_at。State 包括 pending、approved、denied、expired;已记录的 decision 包含 {approved:boolean}。Run 不存在或属于其他租户时返回 404 run_not_found。
作出审批决定
POST /v1/approvals/{approval_id}/decision 接受严格 {approved:boolean}。成功返回 200、{id,run_id,state},不返回完整审批或外部执行结果。
409 stale_approval。审批不存在或属于其他租户时返回 404 approval_not_found。取消先锁定 Run,再使 pending 审批过期;过期决定不能被理解为创建替代写入的许可。
列出 Tool calls
GET /v1/runs/{run_id}/tool-calls 返回 200、{calls:[...]},按创建时间和 ID 排序,无分页。Run 不存在或属于其他租户时返回 404 run_not_found。
列表不返回完整 Tool result。Arguments、结果文本和证据应作为私有应用数据处理。
拒绝单次待补授权
POST /v1/runs/{run_id}/tool-calls/{call_id}/deny-authorization 接受严格 {request_hash:string}。哈希必须是与该调用匹配的 64 位小写十六进制。将实际哈希保存到 authorization-refusal.json:
{id,state:"completed",result}。Result 包含 isError:true、code:tool_authorization_denied 和解释拒绝原因的文本。此处 completed 表示调用已有可交付错误结果,不表示请求操作成功。接口不会发送进一步远端请求,也不撤销已存储的账户凭据。
新拒绝要求 call 为 waiting_authorization,Run 为 running、waiting_authorization 或 waiting_approval。接口将等待授权的 Run 恢复为 running,但保留其他调用的审批等待;持久化 authorization.denied 和 tool.completed。相同哈希的重复拒绝返回原结果。错误见下表。
确认未知远端结果
POST /v1/runs/{run_id}/tool-calls/{call_id}/resolve 记录你已独立核实的结果。接口不会代查 Provider、重发请求或撤销写入。使用前必须检查 Provider 实际记录,并与本次调用对应。
未知字段会被拒绝。使用真实证据填写 tool-resolution.json。以下只展示形状,不能原样提交:
{id,state:"completed",resolution}。Completed 和 failed 两种 outcome 都产生 completed Tool call;failed 会交付 isError:true。原 Run 变为 running。服务持久化包含 evidence 和 source:caller_verified 的 tool.outcome_resolved,再持久化 tool.completed。它不会将 Run 标记完成。
首次确认要求 call 为 unknown,Run 为 running、waiting_authorization 或 waiting_approval,不能将 cancelling 或终态 Run 恢复为活动工作。重复完全相同的 resolution 返回原记录而不重复转换;更改任何字段返回 409 tool_resolution_conflict。响应丢失时保留并重发精确请求体。匹配旧记录的检查先于活动状态校验,因此 Run 后续推进后仍可用相同请求找回已经保存的结果。
SDK:提交已验证的结果记录
在可信后端使用 owner 客户端。先从tool_calls / toolCalls 取得准确的 Run、调用 ID 和 request_hash,独立验证外部操作,并私下持久化上文定义的四个请求字段。以下函数原样转发已保存请求体,不推断结果,也不联系外部服务。
saved_resolution / savedResolution 的形状为 {request_hash, outcome, text, evidence}。text 是交给 Harness 的已验证结果,evidence 应说明对应外部记录和验证方法,不包含凭据。原始 request hash 必须来自正在调查的调用,不能为了消除冲突改取另一个 hash。如果外部结果仍不确定,不要猜测 completed 或 failed 后调用函数。
成功返回 {id, state: "completed", resolution},即使 resolution.outcome 为 failed 也是如此。这表示 Tool 调用记录已完成,不表示外部写入成功,也不表示 Run 已完成;继续观察原 Run。HTTP 或网络错误会向调用方传播,不会被转换为外部失败结果。
响应丢失后,为恢复这次结果登记,应使用相同 Run/调用 ID 和相同已保存请求体重放。网络重试时不要重新生成 evidence 文本或改变 outcome;已有记录时,字段不同会产生冲突。服务端检查原 hash、派发锁和允许状态,辅助函数不绕过这些条件。首次登记与匹配重放的状态前提不同,以上文契约为准。本地示例不能代替处理真实调用时所需的独立 Provider 证据。
错误与并发
请求体或 UUID 不合法返回400 invalid_request;未认证为 401,应用 Token 调用写接口为 403 owner_token_required。拒绝与确认接口的领域错误:
Advisory lock 阻止结果确认与仍在进行的远端请求竞争,即使 worker 租约已过期也如此。Unknown 表示需要证据,不代表可以重发副作用。参见对账与应用内审批。
来源:HTTP 投影与校验、审批决定与取消、Tool 恢复。本文经过源码审阅,不宣称发生了远端副作用或完成新一轮审批/恢复验收。