agent-fleet/openspec/changes/adapter-cross-machine-revision/specs/agent-adapter/spec.md at 48c93e2ce960aa707614aafcf7d37fd0f49fa9d1

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

2 KiB

Raw Blame History

MODIFIED Requirements

Requirement: Unified adapter interface

系统 SHALL 定义统一的 Agent 客户端协议（非 trait），描述远程 Agent 如何通过 HTTP API 与 Orchestrator 交互。Agent 可以运行在任何机器上，只要能访问 Orchestrator 的 HTTP 端点。

协议 SHALL 包含：

POST /api/v1/agents/register — 注册到 Registry
POST /api/v1/agents/heartbeat — 发送心跳
POST /api/v1/tasks/dequeue — 主动拉取任务（替代被动的 execute）
POST /api/v1/tasks/{task_id}/status — 更新任务状态
GET /api/v1/tasks/{task_id} — 查询任务详情
POST /api/v1/receipts — 提交 receipt
POST /api/v1/agents/deregister — 注销

Scenario: Remote Agent on different machine

WHEN Agent worker-03 运行在 host-worker-02（与 Orchestrator 不同机器）
THEN Agent SHALL 通过 HTTP 调用 Orchestrator API 完成注册、领取任务、提交 receipt
AND 无需 SSH、无需共享文件系统、无需同一 OpenClaw 实例

Scenario: OpenClaw-managed Agent

WHEN Agent 由 OpenClaw 管理（如 Jeeves 调度 Codex）
THEN OpenClaw Agent SHALL 作为 Orchestrator 的客户端，通过 HTTP API 调用
AND 任务的实际执行由 OpenClaw 内部的 ACP 机制完成

Requirement: Adapter configuration

每个 Agent 实例 SHALL 通过配置文件指定 Orchestrator 连接信息、自身身份、工作参数。

Scenario: Remote Agent configuration

WHEN Agent 在远程机器上配置
THEN 配置 SHALL 包含：{orchestrator_url: "http://arm0:9090", agent_id: "worker-03", token: "xxx", capabilities: ["code:rust"], work_dir: "/path/to/repo"}

REMOVED Requirements

Requirement: Adapter health check

Reason: Orchestrator 不再主动连接 Agent。健康检查通过心跳机制实现——Agent 主动发心跳，Orchestrator 检测超时。 Migration: 已有心跳机制（POST /api/v1/agents/heartbeat + TimeoutChecker）覆盖此需求。

2 KiB Raw Blame History Unescape Escape