fix: 暴露 turn 活性与 steer 投递语义

This commit is contained in:
Codex
2026-06-09 23:56:39 +08:00
parent 63ae9e2543
commit 0247e42d70
7 changed files with 251 additions and 6 deletions
+4
View File
@@ -167,9 +167,13 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实,不承接 HWLAB
| `runId` / `commandId` / `attemptId` | 支持调用方持久关联和问题定位。 |
| `artifactSummary` | 第一阶段只放有界摘要、字节数、截断标记和必要引用;不内嵌大 stdout/stderr。 |
| `toolCallSummary` | 输出有界、脱敏的 tool call 状态摘要,至少包含 `count``statusCounts``exitCodeCounts` 和最近若干条 `items``method/toolName/type/status/exitCode/command`。消费侧必须用它区分 AgentRun command terminal、agent 内部工具执行和后置诊断,不得用单一 `hwpodExitCode` 覆盖 AgentRun 成功终态。 |
| `liveness` | 查询时派生的 supervisor 活性快照,不写入 durable event。必须暴露 `phase``active``lastSeq``lastEventAgeMs``lastCommandActivity`、lease/heartbeat 摘要和可执行恢复动作。`phase` 至少区分 `waiting-runner``waiting-model``waiting-tool``idle-after-tool``transport-disconnected``runner-heartbeat-stale``terminal`,避免调用方只能用外层超时猜测 backend 状态。 |
| `steerDelivery` | 仅在查询 `type=steer` command result 时出现。必须说明 steer 是否已被 runner ack、是否已转发并被 backend `turn/steer` RPC 接受、目标 `targetCommandId`、是否观察到 target command 后续事件,以及“steer command completed 不等于 target turn 已产生后续 assistant/tool 输出”的语义。 |
`assistant_message` partial、`command_output` 存在、stdout 非空、backend transport close 或 idle timeout 都不能单独让 result 进入 `completed`
`GET /api/v1/sessions/:sessionId` 作为 session status 入口,必须在存在 active/last run 时透出同一套 `liveness``supervisor` 摘要;该摘要是观测辅助,不能替代 command terminal、run terminal 或 raw events 的事实来源。
`commandId` 已指定,result envelope 必须只聚合该 command 的 assistant/output/error/terminal 事件;同一 run 的其他 command reply 不能串入当前 command result。未指定 `commandId` 时可默认选择最新 command。
长 trace / steer 场景的验收标准是:raw events 已有 terminal seq 时,`commands result``lastSeq``eventCount` 必须覆盖同一终态事件范围,`finalAssistantSeq` 必须指向 terminal 前最后一条可用 assistant 或 authoritative final,且 silent first-page truncation 一律视为 result 合同失败。
+1 -1
View File
@@ -122,7 +122,7 @@ claimed -> lease_lost
- lease heartbeat 必须通过 manager lease/status 可观察;不得把周期性心跳或 backend running tick 写成 durable trace event 刷屏。长 turn 只在 `backend-turn-finished` 中输出有界 progress 摘要;过期或冲突时写入 failure event 或明确退出原因。
- replacement runner 在 claim 时遇到 `runner-lease-conflict`,且 manager 响应显示旧 lease 未过期但可能来自已删除 pod 或失联 runner 时,不得立即把同一 HWLAB session 判为失败;应在 `AGENTRUN_RUNNER_CLAIM_RETRY_TIMEOUT_MS` 窗口内按 `AGENTRUN_RUNNER_CLAIM_RETRY_INTERVAL_MS` 等待旧 lease 过期并重试 claim。等待期间必须写入或输出 `runner-claim-waiting-for-stale-lease`,成功接管后写入 `runner-claim-recovered`;超过窗口才把 `runner-lease-conflict` 作为 terminal failureKind。并发双 runner 的正常冲突仍必须拒绝,不能抢占未 stale 的 active lease。
- command 只能从 manager poll;不得从本地文件或临时参数伪造正式 command。
- runner 的普通 poll 只选择 pending `turn`;当 backend adapter 暴露 active turn control 后,runner 才在同 run 内轮询 pending `steer` commandack 后调用 backend 的 steer 能力并单独终结该 steer command。active turn 结束后到达的 steer 必须结构化 blocked,不得启动新 turn,也不得把 run 标为 terminal。
- runner 的普通 poll 只选择 pending `turn`;当 backend adapter 暴露 active turn control 后,runner 才在同 run 内轮询 pending `steer` commandack 后调用 backend 的 steer 能力并单独终结该 steer command。`steer` completed 只表示 `turn/steer` RPC 已被 backend 接受,不表示 target turn 已产生后续 assistant/tool 事件;runner 事件必须携带 target command 和 delivery 语义,target 活性由 command result/session status 的 `liveness` 判断。active turn 结束后到达的 steer 必须结构化 blocked,不得启动新 turn,也不得把 run 标为 terminal。
- backend 产生的所有可见输出必须先经过 adapter normalization 和 redaction,再 append 到 managerbackend_status 至少包含 redacted profile/backendKind/protocol 摘要。
- 单个 command terminal 上报后 runner 不应立即退出,而应继续 poll 同一 run 的 pending command,直到 idle timeout、lease 冲突或 run terminal。退出码与 runner loop 终态必须一致或在日志中可解释。