agent-fleet/openspec/changes/adapter-cross-machine-revision/specs/task-assignment-protocol/spec.md at master

Zer4tul e39a16498c feat: dual execution model (SSH CLI + HTTP pull)

- ExecutionMode enum: SshCli (orchestrator dispatches) | HttpPull (agent pulls)
- SSH CLI executor: spawn remote agents via ssh + CLI template
- Local subprocess as SSH special case (localhost)
- HostConfig with capability matching and load-based selection
- Dispatch loop: scan created tasks → select host → execute → update
- CliAdapterConfig: CLI templates for Codex and Claude Code
- Structured prompt construction (Issue → goal/constraints/validation)
- Output parsers: Codex JSON, Claude Code JSON, raw fallback
- TaskStatus::ReviewPending + review_count loop limit
- Forgejo webhook: pull_request (opened→review_pending, merged→completed)
- Forgejo webhook: push events (task/* branch → last_activity_at)
- HTTP API: dequeue only returns http_pull tasks
- HTTP API: status update only for http_pull mode
- Token auth config for http_pull agents
- Adapter module rewritten: AgentAdapter trait removed → config-driven CLI templates
- New fields: execution_mode, assigned_host, branch_name, pr_title, last_activity_at, review_count
- 30/30 tests pass

2026-05-12 14:07:56 +08:00

3.1 KiB

Raw Permalink Blame History

ADDED Requirements

Requirement: Agent task dequeue (pull model)

Agent SHALL 通过 POST /api/v1/tasks/dequeue 主动拉取任务。Orchestrator 根据 Agent 声明的 capabilities 匹配最优任务，原子性地分配给该 Agent。

Scenario: Agent dequeues a matching task

WHEN Agent worker-03 发送 POST /api/v1/tasks/dequeue，body 包含 {agent_id: "worker-03", capabilities: ["code:rust", "review"]}
THEN Orchestrator SHALL 在单个事务中找到 status=created 且匹配 capabilities 的最高优先级任务
AND 将该任务状态转为 assigned，assigned_agent_id 设为 worker-03
AND 返回任务详情 JSON

Scenario: No matching task available

WHEN Agent 发送 dequeue 但无匹配任务
THEN Orchestrator SHALL 返回 204 No Content

Requirement: Agent task status update

Agent 执行过程中 SHALL 通过 POST /api/v1/tasks/{task_id}/status 更新任务状态。

Scenario: Agent starts execution

WHEN Agent 开始执行任务，发送 POST /api/v1/tasks/org/repo#42/status body {status: "running"}
THEN Orchestrator SHALL 将任务状态更新为 running，记录 started_at

Scenario: Agent reports progress

WHEN Agent 发送状态更新但任务已不在 assigned 给该 Agent
THEN Orchestrator SHALL 返回 403 Forbidden

Requirement: Single task detail query

Orchestrator SHALL 提供 GET /api/v1/tasks/{task_id} 返回单个任务详情。

Scenario: Query existing task

WHEN 发送 GET /api/v1/tasks/org/repo#42
THEN 返回任务完整信息 JSON（包含所有字段和事件历史）

Scenario: Query non-existent task

WHEN 发送 GET /api/v1/tasks/nonexistent
THEN 返回 404 Not Found

Requirement: Agent authentication

Agent 调用任务相关 API（dequeue、status update、receipt）时 SHALL 携带注册时获得的 token。Orchestrator SHALL 验证 token 有效性。

Scenario: Valid token

WHEN Agent 携带有效 token 调用 dequeue
THEN 请求正常处理

Scenario: Invalid or missing token

WHEN Agent 不携带 token 或 token 无效
THEN 返回 401 Unauthorized

Requirement: Non-PR task completion endpoint

对于不产生 PR 的任务（research、review 等），Agent SHALL 通过 POST /api/v1/tasks/{task_id}/complete 显式提交完成，并附带 receipt。

Scenario: Agent completes a non-PR task

WHEN Agent 发送 POST /api/v1/tasks/org/repo#42/complete，附带 receipt
THEN Orchestrator SHALL 验证 receipt（与 POST /api/v1/receipts 相同验证逻辑）
AND 任务状态转为 completed

Scenario: Non-owner attempts to complete

WHEN 非 assigned Agent 尝试 complete
THEN 返回 403 Forbidden

Requirement: Review loop limit

任务在 running ↔ review_pending 之间循环 SHALL 有最大次数限制，防止死循环。

Scenario: Review loop exceeds limit

WHEN 任务的 review 循环次数超过 max_retries
THEN Orchestrator SHALL 将任务标记为 failed
AND 在对应 Issue 添加评论说明超限原因

3.1 KiB Raw Permalink Blame History Unescape Escape