agent-fleet/openspec/changes/adapter-cross-machine-revision/proposal.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

2.3 KiB

Raw Permalink Blame History

Why

当前 adapter interface 设计基于 spawn 本地进程 模式（execute(task) 由 orchestrator 主动调用 Agent），这无法满足跨机协同的核心目标：

spawn 只能本机执行：无法调度远程机器上的 Agent
ACP 只能同实例通信：无法跨 OpenClaw 实例
主动推送模式不可靠：Orchestrator 无法主动通知远端 Agent 执行任务（可能离线、网络不通）

此外，通知机制缺失是一个实际遇到的生产问题：Codex 写完代码后，Jeeves 没有可靠的方式收到完成通知，导致任务卡住直到人工干预。

agent-fleet 的核心价值是跨机 Agent 协同，需要一个基于 HTTP 的、可靠的 pull + push 混合模式。

What Changes

BREAKING: AgentAdapter trait 中的 execute(task) 方法移除。Orchestrator 不主动调用 Agent 执行，而是 Agent 主动拉取任务
新增 Agent pull 模式：POST /api/v1/tasks/dequeue — Agent 主动请求领取任务
新增 Git-based 状态追踪：Agent 执行完成后推送代码到 Forgejo → Forgejo PR webhook 触发状态更新 → 替代 unreliable 的直接通知
新增 任务状态查询：GET /api/v1/tasks/{task_id} — Agent 可轮询任务状态
保留 receipt 提交（POST /api/v1/receipts）作为最终确认
Adapter config 从"本地执行参数"改为"远程 Agent 连接信息"

Capabilities

New Capabilities

task-assignment-protocol: Agent 任务拉取协议（dequeue + 状态更新 + receipt 确认）
notification-via-forgejo: 基于 Git/Forgejo 的状态追踪和通知机制（PR webhook → 状态同步）

Modified Capabilities

agent-adapter: 从"本地 spawn 执行"改为"远程 Agent 通过 HTTP API 自主交互"。Adapter interface 不再包含 execute()，改为 Agent 侧的客户端 SDK 协议
agent-registry: 补充 Agent 认证机制（registry token），确保只有注册的 Agent 能领取任务

Impact

代码：src/adapters/mod.rs 重写（AgentAdapter trait → AgentClient SDK 协议描述）
API：新增 POST /api/v1/tasks/dequeue，新增 GET /api/v1/tasks/{task_id}
通知机制：利用现有 Forgejo PR webhook 作为状态追踪和通知通道，无需新增基础设施
配置：adapter config 从本地参数改为 Agent 连接信息

2.3 KiB Raw Permalink Blame History Unescape Escape

Why