codex-app-server/docs/marker-tools.md

# 任务内标记工具（marker tools）

适用基线：main d129f7b 上的 feat-marker-tools 分支（本地提交，未推、
未建 PR、未部署）。本批只做四类标记工具，不要把本文档读成
“所有 Codex app 线程工具都已实现”：handoff、worktree 创建状态、
PR 检查诊断、automation、clock-sleep 都不在本批；MCP 真工具路
（同轮函数返回）也不在本批。

## 一句话原理

agent 不用联网、不用凭证。agent 在回合输出里写标记块，本地与
Docker 执行器都经 sandbox 的结果解析提取标记块（与 task-message
同款两处解析），可信的 worker 在 completed 轮次后执行。

异步语义（必须先讲清，否则会被当成函数调用）：

- 写块 → 回合结束 → worker 执行 → 报告拼成一条后续消息、
  下一轮才回到父任务。不是同轮函数返回。
- 轮询与等待在 worker 执行期间循环查库、占 worker 槽位（与
  协调员等齐同款代价）；超时或父任务被取消时中止。
- 只有 completed 轮次的块被执行；失败 / 超时 / 取消 / 配额中断
  的轮次不执行；父任务执行期间被取消时也不执行。
- 拒绝只记报告与审计、不炸任务、不改目标状态。

## 边界：谁能用、谁不能用

- 能用：普通任务。普通任务当项目经理、自己派生员工、轮询员工、
  等一批员工、取消或重试员工，走的就是这批工具。
- 不能用：goal 任务与协调员任务不解析这些标记块（只收不发）。
  协调员任务本身不跑模型回合，等齐循环也不会在中途排空后续
  消息做判断，所以协调员 PM 不能因此获得任务内工具。
- 容易混淆的一点：协调员的子任务本身是普通任务（不是协调员
  任务），它写标记块会被解析；它的派生代数从 0 计（见“派生护栏”）。

## 四个工具的标记格式

### task-create：新建平级主线任务

```text
```task-create
{"name": "test-xxx", "prompt": "...", "model": null,
 "effort": null, "executor": "docker"}
```
```

- 新任务是平级主线，不是子代理、不是 fork；不继承父任务历史；
  环境基线继承父任务的 environment_id，但 worker 给它独立的
  tenant/worktree，不动父任务的 cwd；父任务未提交的改动不会
  自动带过去。
- prompt 必填、1-20000 字；name 可选、1-100 字（仅用于派生报告，
  tasks 表没有 name 列，不落库、不改 prompt）；model 不做白名单；
  effort 只能是 low / medium / high / xhigh / max；executor 只能是
  local / docker / cloud，未指定时继承父任务。
- 只建普通任务：不通过标记建协调员任务与 goal 任务。
- 每轮最多 5 块，多余的忽略；非法 JSON、prompt 缺失/空串/超长、
  name 超长、effort/executor 非法时整块跳过；正文里的行首围栏
  会把块截断成非法 JSON 而被跳过（与 task-message 同款非贪婪匹配）。

### task-poll / task-read：按任务 id 轮询阅读

```text
```task-poll
{"task_id": "<目标任务 id>", "interval_seconds": 5,
 "timeout_seconds": 300, "chars": 2000}
```

```task-read
{"task_id": "<目标任务 id>", "wait_seconds": 30}
```
```

- task-read 是 task-poll 的别名；read-thread / read_thread 也是
  同款别名。不传 wait_seconds 时立即读一次快照；传了则等这么久
  再读一次（等价于 interval = timeout = wait_seconds）。
- interval 钳制 1-60 秒，timeout 钳制 0-3600 秒（0 = 立即快照），
  chars 钳制 200-8000 字；各类块合计每轮最多 5 块。
- 轮询目标不存在、跨项目、轮询自己时，报告里写清拒绝原因，
  不改任何状态。轮询目标是只读的，goal 任务也可以被轮询。

### wait-threads：一次等多个目标任务

```text
```wait-threads
{"task_ids": ["B", "C"], "interval_seconds": 5,
 "timeout_seconds": 300, "chars": 2000}
```
```

- wait_threads 是同款写法；task_ids 也接受 thread_ids / threads
  两个别名；去重保序。
- 每块最多 8 个目标，每轮最多 2 块。8 这个数是刻意与服务端
  POST /tasks/{id}/wait 的“一次最多 8 个线程”对齐的；spawn
  分支原先的每块 10 个在本批收紧到 8 个，不要再用 10。
- 并行查库：每轮查一次全部目标，不是逐个串行等超时相加；
  全部终态或超时后把每目标快照一起排回父任务。
- 缺失、跨项目、等待自己的目标当场记为已处理（写清原因），
  不让它们把整批拖到超时；其余目标继续等到终态或超时。
- 超时口径与服务端 /wait 不同，且是故意的：服务端 /wait 是给
  外部调用方持 HTTP 连接等的，上限 120 秒；标记 wait 是 worker
  在回合后直连库循环查，不持 HTTP 连接，超时钳制与 task-poll
  同款（0-3600 秒），占的是 worker 槽位而不是 HTTP 连接。
  两者不要混用、不要互抄上限。

### task-cancel / task-retry：取消 / 重试已存在的任务

```text
```task-cancel
{"task_id": "<目标任务 id>"}
```

```task-retry
{"task_id": "<目标任务 id>"}
```
```

- task_cancel / task_retry 是同款写法；task_id 也接受 to /
  to_task_id / thread_id 别名；每种每轮最多 5 块。
- 取消复用 worker 现有的取消路径语义：取消后状态为 interrupted，
  正在跑的进程组 / 容器按现有取消路径真杀，不只改库状态。
- 重试与服务端 POST /tasks/{id}/retry 对齐：仅 failed /
  interrupted / merge-failed 可重试，重试时清空上一轮
  result_text / error_text / actual_model、状态回 queued、
  prompt 与模型等原样保留、记审计。重试本身不花模型钱，
  重试后的新一轮照常计费。
- 执行顺序：创建 → 取消 → 重试 → 轮询 → 等待。创建在前让同一轮
  刚创建的任务立刻能被轮询；控制操作在快照之前让轮询/等待读到
  取消或重试后的新状态。

## 门禁（task-cancel / task-retry，缺一不可）

纯函数层（cloud/marker_tools.py check_control_gate）与 worker
权限层（worker.py _deliver_marker_tools）两道，拒绝时只记报告
与审计、不改目标状态：

1. 目标存在；同项目；不是自己。
2. 非 goal 任务（verify_command 非空或 goal_mode 为真都算 goal）。
3. 取消要求目标非终态；重试要求目标仅为 failed / interrupted /
   merge-failed。已合并（merged）两者都拒绝；merge-failed 本身
   是终态，所以取消拒绝、重试接受。
4. 关系二选一：目标在发送方派生链上（沿 parent_task_id 链最多
   32 步能追溯到发送方），或目标 created_by 与发送方 created_by
   相同。“同项目猜到 id 就能取消任何人的任务”在此被挡住。
5. 权限层：取消要求发送方创建人有项目 create_task 权限（与
   服务端取消口径同款），重试要求有 approve_merge 权限（与
   服务端重试口径同款）。权限检查本身抛异常时收紧到仅派生链内
   可用，同创建人-only 的目标一律拒绝，并把原因写进报告。

## 派生护栏与费用

- 派生深度上限 3 代（父任务本身是派生任务时逐代计；协调员子任务
  的代数从 0 计，见“边界”）；单个父任务直接派生上限 20 个
  （不含协调员子任务）；超限的块跳过。
- 派生任务是独立主线：父任务完成或取消都不自动杀派生任务；
  想停派生任务，用 task-cancel 或控制台 / API 显式取消它。
  协调员孤儿收口只扫 coordinator_part 非空的协调员子任务，
  不扫派生任务。
- 费用与配额：派生任务 created_by 跟父任务走，认领时照常过
  key 门与配额门；创建时 worker 先查一次父任务配额，超限时
  整轮创建跳过（排队本身不花钱，但不让超限方再批量排队）。

## 诚实边界（与服务端口径不一致处，逐条列出）

- 重试的 goal 拒绝比服务端严：服务端 POST /tasks/{id}/retry
  没有单独的 goal 检查，标记重试为了不破坏 goal 循环语义，
  明确拒绝 goal 目标。这是标记口径比服务端口径严，不是遗漏。
- 取消的 goal 拒绝同理：服务端取消也没有单独的 goal 检查，
  标记取消同样拒绝 goal 目标。
- 服务端重试是双人门（触发人与原任务创建人任一超限即拦，
  且触发人须有 approve_merge 权限）；标记重试的触发方是发送
  方任务本身，其 created_by 与派生任务的 created_by 天然相同
  （派生时跟父任务走），所以 worker 侧只查发送方创建人这一道
  approve_merge，效果与双人门在派生链内等价；同创建人-only
  的目标同样只查这一道，权限查不到时则收紧到仅派生链内。
- wait 的超时口径与服务端 /wait 不同（见上文），数量口径已
  对齐到 8 个；不要把标记 wait 的 3600 秒上限套到 HTTP /wait 上。
- 本批没有 MCP 真工具：标记工具永远是异步的（下一轮才拿到
  报告），做不到同轮函数返回；想做同轮返回要另搭任务级鉴权的
  MCP 服务器，不在本批。
- 签名门残留：worker 的 _code_signature 只签 worker / sandbox /
  coordinator / cost / server / host 共 6 个文件，新模块
  marker_tools.py 不在签名候选里。本批部署时 worker.py 与
  sandbox.py 本身都变了，签名门照常生效；但将来只改
  marker_tools.py 的补丁不会单独触发签名门，届时要么把
  marker_tools.py 加进签名候选并同步改单测的 6 个断言，要么
  接受这一处缺口——本批不顺手改签名，避免动无关安全测试的
  预期。
- spawn 分支的未提交半成品没有原样合并进来：本批只移植了
  已提交的 task-create / task-poll / task-read 实现与未提交的
  wait 解析（收紧到 8 个后接通执行），handoff / worktree /
  PR 检查 / automation / clock-sleep 的解析与 send-message-to-thread
  别名均未移植；spawn 工作区本身未动。

## 关键实现位置

- cloud/marker_tools.py：纯逻辑（解析、校验、快照格式化、
  门禁、派生代数与直接上限计数），单测不需要 worker/server。
- cloud/sandbox.py：本地 _result_from_runner 与 Docker
  _parse_host_result 两处提取五种标记块，worker 侧按结果
  dict 里的 task_creates / task_polls / wait_threads /
  task_cancels / task_retries 执行。
- cloud/worker.py：_deliver_marker_tools（5 处投递点，与
  _deliver_peer_messages 同款位置）、_poll_task_snapshot、
  _wait_task_targets、_queue_self_followup、_marker_auth。
- cloud/tests/test_marker_tools.py：解析上限与钳制、非法块跳过、
  跨项目拒绝、自操作拒绝、已终态拒绝、goal / 已合并拒绝、
  重试仅三态且清空旧结果、wait 多目标终态与超时快照、派生
  深度与直接上限、权限检查失败收紧。