fix: 统一 session send 续跑入口

2026-06-11 21:57:29 +08:00
parent 4a5b298a30
commit 64b824911f
6 changed files with 341 additions and 107 deletions
@@ -135,7 +135,9 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
 | `executionPolicy` | 必填或由 manager 显式补齐默认值，至少包含 sandbox、approval、timeout、network 和 secretScope。 |
 | `traceSink` | 字段必须存在；可以为 `null` 或显式 sink。 |

-`POST /api/v1/runs/:runId/commands` 必须支持 idempotency key。相同 key 且 payload hash 相同应返回既有 command；相同 key 但 payload hash 不同必须结构化失败。`type=turn` 是普通对话 command；`type=steer` 是面向同 run active turn 的运行中引导 command，payload 必须包含非空 `prompt`、`message` 或 `text`，普通 runner poll 不得把它当作新 turn 执行；`type=interrupt` 只保留 durable command 语义，业务 cancel 仍以 run/command cancel API 为权威。
+`POST /api/v1/sessions/:sessionId/send` 是用户级 Session 续跑的唯一 REST 入口。客户端只提交 prompt/payload、可选 run base 和 runner job override；manager 必须读取 durable session/run/command 状态后自动决定内部行为：只有 active `turn` command 已被 runner ack、run 处于 claimed/running 且 lease 未过期，才创建 `type=steer` command；pending/waiting-runner、stale lease、terminal 或无 active command 都必须创建新 run、`type=turn` command，并按请求创建 runner job。响应必须暴露 `decision`、`internalCommandType`、run/command/runnerJob 摘要、activeBefore 和 `valuesPrinted=false`。带 `dryRun=true` 时只返回 non-mutating plan，不得创建 session、PVC、run、command 或 runner job。
+
+`POST /api/v1/runs/:runId/commands` 必须支持 idempotency key。相同 key 且 payload hash 相同应返回既有 command；相同 key 但 payload hash 不同必须结构化失败。`type=turn` 是普通对话 command；`type=steer` 是面向同 run active turn 的运行中引导 command，payload 必须包含非空 `prompt`、`message` 或 `text`，普通 runner poll 不得把它当作新 turn 执行；`type=interrupt` 只保留 durable command 语义，业务 cancel 仍以 run/command cancel API 为权威。`turn` / `steer` 是 manager 内部 command type 和低层诊断资源，不是用户级 CLI 分叉。

 ## Tenant Policy Boundary

@@ -165,6 +167,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB
 | `terminalStatus` | `completed`、`failed`、`blocked` 或 `cancelled`；没有 terminal event 时为 `null` 或 equivalent running 状态。 |
 | `completed` / `terminalSource` | `completed=true` 只能来自 terminal completed；`terminalSource` 标明来自 `terminal_status` event、run record 或暂无 terminal。 |
 | `reply` / `finalResponse` | 从 `assistant_message` 聚合的最终用户可见文本；若存在 `replyAuthority=true` 或 `final=true` 的 `assistant_message`，必须取最后一条作为 authoritative reply。没有 authoritative final 时，result 可以 fallback 到 terminal 前最后一条非空 assistant 文本，但必须在 `finalResponse` 暴露 `seq`、`source`、`replyAuthority`、`final`、`textTruncated` 和 `outputTruncated`，让消费侧知道它是可见性 fallback，不是 backend final authority。没有 terminal completed 时不得伪造 completed reply。 |
+| `finalResponseAuthority` / `finalResponseFallback` / `needsContinuation` / `completionEvidence` | 必须在 result 顶层暴露最终回复权威性。`finalResponseAuthority` 只能是 `authoritative`、`fallback` 或 `missing`；terminal completed 但没有 authoritative final 时，`needsContinuation=true`，`completionEvidence` 必须说明原因并给出同 session 的 `sessions send` 恢复入口。 |
 | `finalAssistantSeq` / `finalAssistantSource` | 必须指向 result 本次选中的 assistant event；长 trace、steer 或 progress snapshot 场景不能让早期 assistant row 继续冒充最终摘要。 |
 | `finalAssistantTextTruncated` / `finalAssistantOutputTruncated` | 必须原样暴露被选中 assistant event 的截断标记；被选中的最终摘要截断时，消费侧应继续读 events 或 trace，而不是把截断隐藏成完整 final。 |
 | `failureKind` / `blocker` | 结构化失败分类和摘要；必须 redacted。 |
@@ -180,7 +183,7 @@ Manager 只承接 HWLAB v0.2 Code Agent 的通用执行事实，不承接 HWLAB

 `GET /api/v1/sessions/:sessionId` 作为 session status 入口，必须在存在 active/last run 时透出同一套 `liveness` 和 `supervisor` 摘要；该摘要是观测辅助，不能替代 command terminal、run terminal 或 raw events 的事实来源。

-当 command 因 idle timeout、provider stream disconnect、runner stdio inactive 或其他非业务终态失败时，manager 的恢复建议必须面向指挥官而不是要求 worker 自行读 trace。指挥官应先读取 `result`、`events` 或 `sessions/:id/trace` 确认最后有效 activity、已完成修改和卡点；若 run/task 有可继续的 `sessionRef`，后续 prompt 必须用同一个 AgentRun session 通过 `send session/<sessionId>` 或 `steer session/<sessionId>` 续跑，并在 prompt 中写入管理者从 trace 得出的下一步。只有旧任务没有 `sessionRef`、session 已 evicted、或同 session 已证明不可恢复时，才创建带管理者摘要的新任务。
+当 command 因 idle timeout、provider stream disconnect、runner stdio inactive、completed-without-authoritative-final 或其他非业务终态失败时，manager 的恢复建议必须面向指挥官而不是要求 worker 自行读 trace。指挥官应先读取 `result`、`events` 或 `sessions/:id/trace` 确认最后有效 activity、已完成修改和卡点；若 run/task 有可继续的 `sessionRef`，后续 prompt 必须用同一个 AgentRun session 通过 `sessions send <sessionId>` 续跑，并在 prompt 中写入管理者从 trace 得出的下一步。只有旧任务没有 `sessionRef`、session 已 evicted、或同 session 已证明不可恢复时，才创建带管理者摘要的新任务。

 当 `commandId` 已指定，result envelope 必须只聚合该 command 的 assistant/output/error/terminal 事件；同一 run 的其他 command reply 不能串入当前 command result。未指定 `commandId` 时可默认选择最新 command。