Files
archie/.scratch/explore-agentexec-protocol.md
T
sam bb2193e5e4 feat: add optional NATS JetStream task distribution
Adds optional NATS-based task distribution alongside the existing
SQLite flow. When [nats] is absent from config, zero behaviour change.

New internal/nats package:
- Subject constants matching PRD §2 (archie.task.{bug,feature,default,bootstrap})
- Client: Connect (stream + durable pull consumer), PublishTask
  (Nats-Msg-Id dedup), Fetch, DecodeTask
- Tests with embedded NATS server (connect/publish, dedup, subject routing)

Config: NATSConfig{URL, TokenEnv} on Config, commented-out [nats] block
in config.example.toml

Store: ClaimByIssue atomic claim by owner/repo/number for NATS consumer

Daemon: Nats client field, poll() branches to pollNATS/pollSQLite,
Cycle() branches to drainNATS/drainSQLite (NATS fetch then SQLite
ClaimNext fallback for requeued tasks), processNATSTask
(decode → EnqueueIssue → ClaimByIssue → process → Ack)

Scratch: explorer and plan agent outputs from parallel-explore phase
2026-07-22 02:02:09 +10:00

12 KiB
Raw Blame History

agentexec-protocol

我现在掌握了所有需要的信息。以下是完整的报告。


报告:Archie 核心中的代理执行协议和 Runner 架构

1. Runner 接口

定义位置:/work/apps/archie-core/internal/agentexec/inprocess.go,第 20-22 行

type Runner interface {
    Run(ctx context.Context, workspace string, req Request) (Result, error)
}

一个单一方法接口: Run 接受一个上下文、一个工作目录路径(字符串)和一个 Request,返回一个 Result 和一个错误。工作目录路径与请求分开传递,供容器运行器将主机路径映射到内部文件系统。

该接口有两个具体实现:

  • InProcessRunner (/work/apps/archie-core/internal/agentexec/inprocess.go,第 29-33 行) -- 拥有一个 *runtime.Runtime、一个 *slog.Logger 和一个 loopFunc 字段(默认为 agentloop.Run)。它在与 archied 相同的进程空间中运行代理循环。

  • SubprocessRunner (/work/apps/archie-core/internal/agentexec/subprocess.go,第 17-27 行) -- 拥有 Command、Args、Environ、AdditionalEnv、Diagnostics io.Writer 和 Providers。它将完整的 Invocation 序列化到 stdin,启动一个 archie-agent 二进制文件,并从 stdout 解码 Response。

2. 线路协议

所有消息类型都定义在 /work/apps/archie-core/internal/agentexec/protocol.go 中。

Invocation (第 139-144 行) -- 被 archie-agent 接受的完整请求:

type Invocation struct {
    Version   int                 `json:"version"`
    Workspace string              `json:"workspace"`
    Request   Request             `json:"request"`
    Providers map[string]Provider `json:"providers"`
}

Request (第 59-74 行) -- 代理阶段的有效载荷:

type Request struct {
    Version      int           `json:"version"`
    TaskID       int64         `json:"task_id"`
    Attempt      int           `json:"attempt"`
    Stage        string        `json:"stage"`
    Model        string        `json:"model"`
    Mission      string        `json:"mission"`
    ExtraRules   string        `json:"extra_rules,omitempty"`
    ReadOnly     bool          `json:"read_only,omitempty"`
    Budget       Budget        `json:"budget"`
    Gate         Gate          `json:"gate"`
    Preflight    []Command     `json:"preflight,omitempty"`
    Protection   Protection    `json:"protection"`
    Notes        string        `json:"notes,omitempty"`
    CaptureTools []CaptureTool `json:"capture_tools,omitempty"`
}

Result (第 97-111 行) -- 输出:

type Result struct {
    Version       int                          `json:"version"`
    TaskID        int64                        `json:"task_id"`
    Attempt       int                          `json:"attempt"`
    Stage         string                       `json:"stage"`
    Status        string                       `json:"status"`
    StopReason    string                       `json:"stop_reason,omitempty"`
    Changes       []string                     `json:"changes,omitempty"`
    Iterations    int                          `json:"iterations,omitempty"`
    TokensUsed    int                          `json:"tokens_used,omitempty"`
    Summary       string                       `json:"summary,omitempty"`
    Detail        string                       `json:"detail,omitempty"`
    AppendedNotes []string                     `json:"appended_notes,omitempty"`
    Captures      map[string][]json.RawMessage `json:"captures,omitempty"`
}

Response (第 168-172 行) -- 从 archie-agent 返回的顶层信封:

type Response struct {
    Version int    `json:"version"`
    Result  Result `json:"result"`
    Error   string `json:"error,omitempty"`
}

辅助类型:

  • Command (第 18-22 行):Name、Argv、ExpectFailure
  • Gate (第 25-28 行):Commands、MaxConsecutiveFailures
  • Budget (第 31-35 行):MaxSteps、MaxTokens、WallClock
  • Protection (第 38-41 行):Suffixes、Globs
  • CaptureTool (第 45-53 行):Name、Description、Parameters、RequiredFields、NonEmptyStrings、BooleanFields、MaxCalls
  • Provider (第 115-119 行):Class、APIKeyEnv、BaseURL

协议通过 JSON 在 stdin/stdout 上使用。ServeOne (worker.go,第 16-43 行) 解码一个 Invocation,验证它,构建一个 InProcessRunner,运行它,然后将单个 Response 写入 stdout。ServeOne 不会循环——它处理一个调用然后返回。

3. cmd/archied 如何连接 Runner

在 /work/apps/archie-core/cmd/archied/main.go 中,第 109-125 行:

providers := executionProviders(cfg)
llm := agentexec.NewRuntime(providers)
var agentRunner agentexec.Runner
if llm != nil {
    switch cfg.Agent.Mode {
    case "subprocess":
        agentRunner = &agentexec.SubprocessRunner{
            Command:       cfg.Agent.Command,
            Environ:       os.Environ(),
            AdditionalEnv: cfg.Agent.Env,
            Diagnostics:   os.Stderr,
            Providers:     providers,
        }
    case "inprocess":
        agentRunner = agentexec.NewInProcessRunner(llm, log)
    }
}

运行器模式由 cfg.Agent.Mode 控制,它来自配置 TOML。有两个 case:

  • "subprocess":创建一个 SubprocessRunner,将完整的环境、一个可执行文件命令(来自 cfg.Agent.Command,通常是 archie-agent 二进制文件的路径)以及提供者映射传递给它。
  • "inprocess":通过 NewInProcessRunner(llm, log) 创建一个 InProcessRunner,其中 llm 是 runtime.NewRuntime(providers) 的结果。

然后,agentRunner 被放入 Daemon 结构体 (/work/apps/archie-core/internal/daemon/daemon.go,第 33 行) 作为 Agent agentexec.Runner。守护进程的 process 方法 (第 356-377 行) 将其传递到 TaskContext:

workflow.Run(ctx, wf, &workflow.TaskContext{
    Task:         task,
    Repo:         repo,
    ...
    Agent:        d.Agent,
    ...
})

如果 cfg.Agent.Mode 既不是 "subprocess" 也不是 "inprocess",或者如果 llm 是 nil(没有提供者),则 agentRunner 保持为 nil。当 Agent 为 nil 时,AgentStage.Stage() 方法 (agent.go,第 49-50 行) 返回一个合适的错误。

4. TaskContext 和 Agent 字段

定义位置:/work/apps/archie-core/internal/workflow/workflow.go,第 26-57 行。

type TaskContext struct {
    Task  *store.Task
    Repo  config.Repo
    Cfg   config.Config
    Forge forge.Forge
    Store *store.Store
    Trees *worktree.Manager
    Agent agentexec.Runner          // <-- 第 33 行
    Bus   *events.Bus
    Log   *slog.Logger
    CustomStages func(dir string) ([]Stage, error)
    Dir    string
    Branch string
    BuildSummary string
    ReproProof string
    decision *decision
    Outcome Outcome
}

Agent 字段是 agentexec.Runner。工作流通过 AgentStage.Stage() (agent.go,第 47-148 行) 调用它。核心调用顺序是:

  1. AgentStage.Stage() 从上下文字段 (agent.go,第 94-109 行) 构建一个 agentexec.Request。
  2. 调用 tc.Agent.Run(ctx, tc.Dir, req) (第 110 行)。
  3. 然后处理结果:验证 (ValidateFor,第 114 行)、追加笔记 (第 117-124 行)、累积代币/迭代次数 (第 129-130 行)、检查非 "passed" 状态 (第 136-141 行),以及分派给 OnResult 回调 (第 143-145 行)。

只有 InProcessRunner 使用 runtime.Runtime 直接调用 agentloop.Run。SubprocessRunner 构建一个 Invocation,通过提供者名称映射将完整的请求序列化,并通过 exec.CommandContext 启动一个子进程。

5. 使 archie-agent 成为长期运行的消息总线进程所需的变化

以下是关键的变化领域:

A. 入口点 (cmd/archie-agent/main.go)

  • 目前它调用 agentexec.ServeOne,后者解码一个 JSON 调用,执行,并将一个 JSON 响应写入 stdout。这严格是一次性的。
  • 要变为长期运行,main() 需要初始化一个消息总线客户端(例如,NATS、RabbitMQ、AMQP 甚至是简单的 gRPC 流),订阅一个主题/队列,并在每个传入的 Invocation 上循环调用 ServeOne(或者更确切地说,其核心逻辑)。
  • 信号处理需要优雅地等待进行中的工作完成,而不是在 SIGTERM 时直接退出。

B. worker.go 中的 ServeOne 函数

  • 目前它在全局范围内构建一个 InProcessRunner(将 NewRuntime(invocation.Providers) 传递给 NewInProcessRunner)。
  • 如果进程是长期运行的,则 runtime.Runtime 应该在启动时构造一次(可能来自配置或环境变量),而不是每个调用都动态构建。提供者配置会在进程的生命周期内保持不变,因此没有理由每次从 JSON 重新创建运行时。
  • protocol.go 中的 Invocation 类型包含 Providers——如果一个长期运行的 worker 已经在启动时知道其提供者,这可能就不需要了。工作区路径也有问题:对于长期运行的进程,工作区可能由消息路由到(或使用单独的 RPC 调用来准备),而不是嵌入在调用请求中。

C. 线路协议适配

  • 当前协议是 request/reply(1 个 JSON 值用于输入,1 个用于输出)。对于总线,Response 会被发布到单独的回复主题/队列,而不是写入 stdout。
  • 运行器接口本身 (Runner.Run(ctx, workspace, req)) 是同步的,这很适合总线——每个消息都可以通过 Run 处理,结果被发布出去。
  • 调用/响应帧中的 Version、TaskID、Attempt、Stage 字段提供了足够的路由/关联上下文——Response 中的 TaskID 和 Stage 使得在回复主题上正确路由变得简单。

D. 环境架构

  • 目前,SubprocessRunner 通过继承的环境变量传递 API 密钥,并使用 WorkerEnvironment 进行过滤(subprocess.go,第 155-162 行)。一个长期运行的进程已经在进行中,但需要能够更新/重新加载提供者凭证而不重新启动(例如,密钥轮换)。这可能需要一个控制通道或一个动态重新加载配置的方法。

E. 配置和工作目录

  • 目前,Invocation 承载 Workspace,并且每个路径都是请求的一部分。一个基于总线的 worker 可能希望要么:
    • 在工作区已经准备就绪时接收带外消息(例如,一个单独的“准备”RPC),或者
    • 除了运行代理之外,还执行一些较小的设置步骤(克隆 repo)。
  • 守护进程当前通过 worktree.Manager (steps.go,第 22-30 行) 处理工作目录准备。如果 archie-agent 处理其自己的工作目录设置,这会创建一个职责划分问题。

F. SubprocessRunner 对 agentexec 包的依赖

  • SubprocessRunner 是 archied 端的替代品——它从 archied 启动 archie-agent。如果 archie-agent 是一个长期运行的进程,archied 不会直接启动它;连接成为出站消息总线连接。SubprocessRunner 可能会变得过时或需要重构为一个“远程”运行器,该运行器通过总线发送消息而不是生成子进程。

G. 错误处理和死信队列

  • 目前,cmd.Run() 中的进程退出代码表示协议失败。对于长期运行的进程,反序列化故障或无效调用应发布到死信队列主题。

总而言之,Runner 接口 (Run(ctx, workspace, req)) 本身不需要改变。然而,它的调用方式会改变:

  • cmd/archie-agent/main.go 将从一次性 stdin/stdout 变为总线主题订阅循环。
  • cmd/archied/main.go 将使用一个基于总线的远程运行器,而不是 SubprocessRunner。
  • 提供者查找和运行时生命周期管理将从每次调用(worker.go 中的 ServeOne)移动到进程启动时。