Macro Agent Harness 会话评审决策接口:深入解析 DecideSessionReviewErrors 的 403 与 409
Macro Agent Harness 会话评审决策接口:深入解析 DecideSessionReviewErrors 的 403 与 409
DecideSessionReviewErrors 是 Macro Agent Harness OpenAPI 生成类型中一个看似精简、却直接决定客户端重试策略的类型:它为 POST /agent-sessions/{session_id}/reviews/{review_id} 明确声明了 403 与 409 两种失败语义。本文以该类型定义为骨架,结合 agent_code_mode crate 的服务端实现与 Macro TypeScript SDK 的调用封装,讲清“谁可以决策”“为什么会产生冲突”“冲突后如何安全恢复”,以及评审栈的容量与超时边界。
类型定义原文与上下文
该文档给出的定义极其紧凑:
type DecideSessionReviewErrors = {
403: unknown;
409: unknown;
};
它属于 packages/sdk-docs/reference/generated/agent-harness/types.gen 这一生成目录,是 OpenAPI 文档经类型生成器产出的产物,原始定义见 DecideSessionReviewErrors.md。同一接口族的相邻类型构成了完整契约:
| 类型 | 含义 | 文件 |
|---|---|---|
DecideSessionReviewData |
请求结构:path{a session_id, review_id}、body: ReviewDecision、query?: never、url 字面量 |
DecideSessionReviewData.md |
DecideSessionReviewErrors |
错误响应:403、409 |
DecideSessionReviewErrors.md |
DecideSessionReviewResponses |
成功响应:200: ReviewRecord |
DecideSessionReviewResponses.md |
DecideSessionReviewResponse |
上述响应联合的索引别名 | DecideSessionReviewResponse.md |
ReviewDecision |
三种决策分支:edit / submit / dismiss |
ReviewDecision.md |
ReviewRecord |
完整持久化记录(含 revision、items、decision) |
ReviewRecord.md |
注意 503、500 并未出现在该类型中:生成器只为该 operation 显式声明的状态码建类型,DecideSessionReviewErrors 的“只有两个键”本身就是一份契约声明——客户端应当把这两类错误当作可预期的业务分支处理,而不是笼统的失败。
请求与响应的形状
DecideSessionReviewData 的 url 是字面量 "/agent-sessions/{session_id}/reviews/{review_id}",query? 被固定为 never,说明所有参数都在路径与 body 中。body 是判别联合(discriminated union),以 action 字段区分:
type ReviewDecision =
| { action: 'edit'; revision: number; item: string; draft: unknown }
| { action: 'submit'; revision: number; items: string[] }
| { action: 'dismiss'; revision: number; items: string[] };
三个分支共享 revision,这是乐观并发控制(compare-and-swap)的令牌;items: [] 的语义是“选择全部 pending 项”,这一点在 ReviewDecision.md 中有明确描述。
服务端契约:OpenAPI 声明与错误映射
路由声明位于 axum_router.rs:
#[utoipa::path(post, path = "/agent-sessions/{session_id}/reviews/{review_id}",
operation_id = "decide_session_review", params((...)),
request_body = ReviewDecision,
responses((status = 200, body = ReviewRecord), (status = 403), (status = 409)))]
这正是 DecideSessionReviewErrors 只有 403 和 409 两个键的源头。处理函数要求两重提取器:
AgentSessionAccessLevelExtractor<EditAccessLevel, ...>:调用方必须对目标AgentSession实体具备编辑级访问权;MacroAuthorizationExtractor<Auth, UserOnly>:调用者身份必须是登录用户(bot 等非用户主体被排除)。
随后进入 CodeExecutionApiError 的统一映射(axum_router.rs):
| 领域错误 | HTTP 状态 | 响应体 |
|---|---|---|
CodeModeError::Forbidden |
403 |
forbidden |
CodeModeError::NotFound |
404 |
code execution not found |
CodeModeError::Conflict |
409 |
review changed; reload before acting |
CodeModeError::Invalid(msg) |
400 |
具体消息 |
| 其他 | 500 |
could not read code execution |
一个值得注意的细节:NotFound 在 OpenAPI 注解里并未为决策接口声明(注解只列了 200/403/409),但实现层仍可能返回 404。由于 ReviewStore::get 使用 WHERE id = $1 AND agent_session_id = $2 查询,跨会话的评审 ID 只会表现为“查不到”,因此 404 实际承担了“该评审不属于这个会话”的语义。
403 Forbidden:授权失败的全部来源
403 的响应体是纯文本 forbidden,但这一个状态码背后至少有五个不同的判定点,全部集中在 reviews.rs 与决策入口:
- 会话已归档:
owner()在读取会话状态时,若state.archived为真即返回Forbidden。 - 实体类型不是 AgentSession:
session_id()会对EntityType::AgentSession做严格校验,其他实体类型的访问凭据一律拒绝,即使 UUID 恰好可解析(reviews.rs)。 - 凭据主体与调用者不一致:
authorize()比较access.acting_user_id() != Some(actor)。 - 评审归属账户与调用者不一致:
decide_owned()中record_actor(&record) != actor即拒绝。所谓record_actor,是record.acting_user,若为空则回退为会话所有者——因此历史记录(早于多账户评审的旧数据)按会话所有者校验。 - 聊天入口的额外约束:通过
decide_for_session(Agent 工具路径)决策时,还要求当前轮次由真实的用户提示驱动:prompter.kind == PrompterKind::User且prompter.user == actor。代码注释写得很直白:“A system event cannot approve itself.”——系统事件无法自我批准评审。
这解释了为什么 403 在客户端侧不可重试:它不是竞态,而是身份或生命周期问题。唯一的处理方式是提示用户检查权限、确认会话未归档,或者用正确的账户身份重新发起。
409 Conflict:修订号不匹配与状态不可决策
409 的语义在服务端被统一收敛为“review changed; reload before acting”。判定逻辑位于 reviews.rs:
if revision != record.revision
|| record.presented_at.is_none()
|| record.items.iter().any(|i| i.status == ReviewItemStatus::Submitting)
{
return Err(CodeModeError::Conflict);
}
三个条件:
revision过期:ReviewRecord.revision是 compare-and-swap 版本号,每次保存自增(record.revision += 1)。客户端拿到的是旧快照,服务端已推进过版本。- 评审尚未被呈现:
presented_at为空意味着该评审尚未完成 presentation 写入,此时任何决策都视为非法(正常情况下present会先补齐)。 - 仍有提交中的条目:任一条目处于
submitting,说明上一批动作仍在执行,禁止并发提交。
进入类型分支后还有两类冲突:
edit指向的条目不存在或已非 pending:find(|e| e.id == item && e.status == Pending).ok_or(Conflict)?。submit/dismiss的items含非 pending 条目:只要有一个 ID 不满足status == Pending即冲突。
此外,存储层的乐观锁本身也会产生冲突:save 的 SQL 为 UPDATE ... WHERE id = $1 AND agent_session_id = $2 AND revision = $3,若 rows_affected() != 1 就返回 Conflict(outbound/reviews.rs)。所以即使同一进程内两次并发 submit,也只会有一个成功——测试 double_submit_claims_before_work_and_never_repeats_an_action 断言了“恰好一个成功、另一个 Conflict、动作只执行一次”。
为什么 409 必须“先刷新再重试”
如果对 409 直接原样重发(带着旧 revision),由于 revision 永远不会回到旧值,请求会持续 409。SDK 的实现正体现了这一点:review.ts 中的私有 decide() 每次都先 await this.detail.get() 读取当前 revision,再用 mutate 提交;而 submitAll() 的文档直接写着 “Never retries a conflict or ambiguous send.”(review.ts)。语义上,409 只是“你的视图过期了”,不是“请求有问题”。
决策链路:从 claim 到后台执行
理解 403/409 之后,才能正确解读 200 的含义。decide_owned 的执行顺序是:
- 读取并校验归属(可能 403);
- 校验 revision / presented / submitting(可能 409);
edit分支:校验草稿大小与结构,写入draft、置edited = true,检查所有条目草稿总字节数不超过MAX_INPUT_BYTES(1 MiB),保存后立即返回,不执行任何动作;submit/dismiss分支:把选中项状态改为Submitting或Dismissed,写入ReviewDecisionContext{by, via, revision, items},持久化并发出NotificationEvent::ReviewDecided;tokio::spawn后台执行:对submit逐项调用actions.execute(),每项外层套ACTION_TIMEOUT(60 秒)。成功则置Completed并记录result;超时或失败则置Unknown并写入告警文案 “The submission outcome could not be confirmed. Check the destination before retrying.”。
因此 200 只代表“决策已被原子地认领”,不代表邮件已发出。响应体是当时的 ReviewRecord 快照(response = record.clone() 在 spawn 之前完成),后续状态需要轮询或依赖 review.settled 通知。这也是 409 中“仍有 submitting 条目”这一条件的必要性:它避免了客户端在动作飞行途中再次提交。
result 还有 8 KiB 的截断保护(MAX_RESULT_BYTES):超出时替换为 {"outputOmitted": true, "reason": "..."},避免把巨大的后端响应写进记录。
SDK 侧:如何正确调用 decideSessionReview
SessionReview 是对 ReviewRecord 的实体句柄,继承自 MacroEntity,详情记录惰性加载、任何变更后失效。核心调用如下:
import type { SessionReview } from './packages/sdk/src/entities/agent-sessions/review';
// 提交全部 pending 项(items: [] 表示“全选”)
await review.submitAll();
// 逐项操作
const items = await review.items();
await items[0].edit({ subject: '改后的主题', body: '...' });
await items[1].dismiss();
// 冲突后:先刷新,再重试
await review.refresh();
await review.submitAll();
refresh() 的实现是 this.detail.clear(); await this.detail.get();,配合 Lazy 缓存即可拿到新 revision。由于 items() 返回的 ReviewItem 句柄携带的是创建时的快照,在长时间停留的界面上,item.status 可能已过期;判断是否可提交应以 refresh() 后的记录为准。
对于“共享同一评审的多个入口”(卡片、聊天、收件箱),DecisionVia 枚举记录了来源:"card" | "chat" | "inbox"(DecisionVia.md)。该值会写入 ReviewDecisionContext.via,并参与通知去重键的构造:
dedupe_key: format!("{}:{}:{}", event.kind(), record.id.0, decision.revision)
也就是说,同一评审的同一决策版本只产生一条通知,重复的播报不会打扰用户。
状态机与错误处理速查
ReviewItemStatus 只有五个取值:pending | submitting | completed | dismissed | unknown(ReviewItemStatus.md)。据此可以写出对齐服务端语义的客户端分支:
| 客户端观察 | 建议动作 |
|---|---|
403 |
不重试。检查会话是否归档、当前登录账户是否等于 review.actingUser(为空时为会话所有者)、是否以用户而非系统事件/机器人身份发起 |
409 |
不原样重发。refresh() 后用新 revision 重试一次;若用户已无意操作则放弃 |
200 且条目为 submitting |
等待 review.settled 或轮询至非 submitting,期间禁止再提交 |
条目为 unknown |
去目标系统(邮箱已发件箱、日历)核实后再决定是否重发,切勿盲目重试 |
条目为 dismissed |
终态,不可再提交 |
关于 unknown 的自动修复:refresh() 会扫描“updated_at 距今超过 STALE_SUBMISSION_MS(300000 ms,即 5 分钟)且仍有 submitting 条目”的记录,将其改写为 unknown 并附加提示 “Submission was interrupted; check the destination before retrying.”,同时补写一次 ReviewDecisionContext(针对没有决策上下文的旧记录)并发出 ReviewSettled 事件。这解决的是“副本被杀导致界面永远转圈”和“允许盲目重试”两个问题(reviews.rs)。
硬性边界:评审栈的容量与体积限制
DecideSessionReviewErrors 没写 400,但决策路径确实可能返回 400(CodeModeError::Invalid),主要来自草稿校验与体积上限。理解这些常量有助于解释为何某些“合法请求”会被拒(reviews.rs):
| 常量 | 值 | 作用 |
|---|---|---|
MAX_REVIEWS_PER_SESSION |
100 | 单个会话的评审栈上限,创建时通过 SELECT ... FOR UPDATE 锁会话行后计数 |
MAX_DRAFT_BYTES |
128 KiB | 单条草稿序列化后的上限 |
MAX_RECORD_BYTES |
2 MiB | 整条 ReviewRecord 保存时的上限 |
MAX_INPUT_BYTES |
1 MiB | 创建请求体与“所有条目的草稿总和”的上限 |
STALE_SUBMISSION_MS |
300000 | submitting 被视为中断的阈值(5 分钟) |
ACTION_TIMEOUT |
60 s | 单个条目执行动作的超时 |
MAX_RESULT_BYTES |
8192 | 保存执行结果的上限,超出则省略 |
创建时还有形状约束:title 去空白后不能为空且长度 ≤ 256;drafts 数量必须在 1–100;kind == import 时必须恰好一条草稿。这些检查在 create_owned 中一次性完成(reviews.rs),edit 分支则复用 validate_draft 并重算总量。
权限模型小结:谁拥有评审
评审引入了“会话所有者”与“评审账户”两套身份。acting_user 是不可变字段(创建时写入 Some(actor)),后续所有动作都以它为准;而 present() 写会话 transcript 的能力属于会话所有者,因此呈现用所有者身份、动作用 acting_user 身份。这一分离使得“代表他人邮箱起草并发送”的场景既能在 UI 上呈现,又不会被代理身份越权执行。
create_for_session 与 decide_for_session 这一对“会话内工具入口”进一步限定:创建允许会话所有者或当前轮次的实际行动用户;决策则只允许真实用户提示驱动。这套规则让 Agent 可以“发起评审”,但不能“批准自己的评审”。
结语
DecideSessionReviewErrors 这个只有两行的类型别名,实际上是 Macro Agent Harness 会话评审机制的接口边界:403 编码了“身份、归属与生命周期”的静态约束,409 编码了“基于版本号的并发控制”的动态约束。把 403 当最终失败、把 409 当作“刷新令牌后重试”的信号,并牢记 200 只代表“认领成功”而非“动作完成”,就能在卡片、聊天与收件箱三种入口上实现一致且安全的决策行为。要深入细节,建议依次阅读 领域服务、PostgreSQL 存储、HTTP 路由 与 SDK 封装。