@ dougbots/ avenor-core (英语)

控制套接字客户端,主管生命周期,以及针对复仇者代理跑者的工具执行.

Avenor是运行AI代理会话的CLI守护进程. 这个软件包管理守护进程,并围绕它的JSON-RPC控制套接字提供打入的包装器——用于产卵运行,检查状态,跟踪会话,并清理关闭一切的接口.

这是一个 私营 工作空间软件包 @dougbots/avenor-mcp 财务报告和审定财务报表 @dougbots/avenor-opencode。不发布到 npm.

二进制发现

复仇者二进制通过三步倒置定位:

1. AVENOR_BIN 环境变量
2. avenor 打开 PATH (通过) which avenor(中文(简体) )
3. ~/.botfiles/bin/avenor

导出助手 findAvenorBinary() 运行这个发现。 这个 Supervisor 如果没有明确的,则自动调用 binaryPath 给出.

核心概念

客户端

dial(socketPath) 连接到向导控制套接字并返回 a Client编辑 Client 在Unix套接字上讲JSON-RPC 并揭露方法如 spawn(), (中文(简体) ), status(), (中文(简体) ), list(), (中文(简体) ), shutdown(), (中文(简体) ), answerPermission(), (中文(简体) ), prompt(),以及 cancel()。它也提供了一个可同步的 events() 用于流出运行时的事件.

主管

Supervisor.get() 单子能保证一个复仇者 stable 进程正在运行,绑定到每个 PID 控制套接字。 它从二进制开始 avenor stable --control-socket <path> --idle-timeout 30m并登记信号处理器清理出口.

相接跑被跟踪到内存(label ~ runtime ID, sentinel路径,事件日志路径),因此后续和状态检查可以解决正确的跑出时间.

工具

包会导出六个自成一体的工具函数. 每个都用于嵌入MCP服务器或CLI处理器.

spawnTool

启动新代理运行 .

import { spawnTool } from '@dougbots/avenor-core'

const result = await spawnTool({
  agent: 'codex',
  prompt: 'Write a function to reverse a string',
  label: 'reverse-string',
  model: 'claude-sonnet-4',
  backend: 'opencode-http',
  serverUrl: 'http://127.0.0.1:4096',
})
// { run_id: '...', label: 'reverse-string', supervisor_id: '/path/to/socket' }

接受 agent, (中文(简体) ), prompt, (中文(简体) ), promptFile, (中文(简体) ), label, (中文(简体) ), dir, (中文(简体) ), timeout, (中文(简体) ), model, (中文(简体) ), thinking, (中文(简体) ), backend, (中文(简体) ), rosterFile, (中文(简体) ), rosterEntry, (中文(简体) ), serverUrl, (中文(简体) ), sessionId,以及 supervisorId (瞄准特定的套接字).

名册选择

rosterFile 是高级JSON名册地图的路径 rosterEntry 是从中选择的密钥。 每个条目必须包含 backend 其中至少一个 agent 或者说 model数字 :

{
  "planner": {
    "backend": "opencode-acp",
    "model": "provider/planner"
  }
}

直接的名册既能产生选择者,也不能提供 agent, (中文(简体) ), model,或 backend。没有名册的直接模式允许独立省略其中的每个身份字段,包括仅后端请求;选定的运行时间供应默认省略值. thinking 是运行级别,而不是名册字段,并对照有效的后端检查。 共享选择器验证拒绝缺失选择器对,混合直接/旋转字段,以及未知选择器密钥. 名册文件加载拒绝延迟输入字段,例如 system· ; thinking 仍然是有效的运行级别选项,但从未从名册条目中读取.

await spawnTool({
  prompt: 'Analyze the repository',
  dir: '/repo',
  rosterFile: '/repo/roster.json',
  rosterEntry: 'planner',
})

名册阶段的选择由Avenor的"去"工作流程跑者解决. 名册条目可以覆盖后端/代理/模型每个阶段。 CLI工作流程回落和嵌入式花名册继承是只使用CLI;稳定的嵌入保持了它现有的行为. 续会必须使用与原届会相同的有效后端.

statusTool

一个或全部运行的报告状态 。 何时 runId 省略它列出主管的每行记录.

import { statusTool } from '@dougbots/avenor-core'

const status = await statusTool({ runId: 'reverse-string', view: 'lifecycle' })
// { run_id: 'reverse-string', label: 'reverse-string', status: 'running', ... }

状态值 : running, (中文(简体) ), waiting, (中文(简体) ), done, (中文(简体) ), failed, (中文(简体) ), timeout, (中文(简体) ), killed,以及 unknown 当主管不报告任何状况或本套件不承认时. done, (中文(简体) ), failed, (中文(简体) ), timeout 财务报告和审定财务报表 killed 终端; unknown 没有。 如果等待许可申请,结果包括: pending_permission 附有可供选择的选项。 这个 lifecycle 视图省去最后输出和诊断元数据; full 仍然是兼容性的默认值.

resultTool

等待一跑完成并返回其完整的最终输出而无需记录或事件细节.

import { resultTool } from '@dougbots/avenor-core'

const result = await resultTool({ runId: 'reverse-string', timeout: '5m' })
// { run_id: 'reverse-string', status: 'done', ready: true, output: '...' }

设定 wait: false 进行无阻断可用性检查。 立即返回等待许可; 过期结果等待返回 ready: false 财务报告和审定财务报表 timed_out: true 没有停止运行.

answerPermissionTool

回答待决的运行许可请求。 若为 requestId 中,它自动查找当前待决请求.

import { answerPermissionTool } from '@dougbots/avenor-core'

await answerPermissionTool({ runId: 'my-run', optionId: 'allow-once' })
// { ok: true }

messageTool

运行间每个消息的一个工具 : tell, (中文(简体) ), ask, (中文(简体) ), reply, (中文(简体) ), resume, (中文(简体) ), withdraw 财务报告和审定财务报表 control_reply它需要约束 MessageProvider,它提供谁的呼叫 说,一个目标如何解决, 并且只有表面可以执行的行动.

import { messageTool } from '@dougbots/avenor-core'

await messageTool({ action: 'resume', target: 'reverse-string', message: 'Now optimize it for speed' }, provider)
// { action: 'resume', outcome: 'resumed', text: '...', runId: '...', label: '...' }

peersTool

列表已连接运行, 重命名运行的显示标签, 或读取对等方最后一个代理消息 。 喜欢 messageTool,它通过绑定的提供者读取.

import { peersTool } from '@dougbots/avenor-core'

const result = await peersTool({ action: 'list' }, provider)
console.log(result.text)

eventsTool

从一跑的上盘事件日志读取最近的事件. 按事件类型选择过滤并限制计数(默认为50,最大为1000).

import { eventsTool } from '@dougbots/avenor-core'

const events = await eventsTool({ runId: 'my-run', types: ['tool_use', 'error'], limit: 20 })

QQ 只通过单通支持 Supervisor - 通过一项明确的 supervisorId 会投出.

shutdownTool

关闭了复仇者守护进程。 过 force: true 以立即杀死而不是优雅的终止。 清除用于跟踪运行的监控文件和事件日志 .

import { shutdownTool } from '@dougbots/avenor-core'

const result = await shutdownTool({ force: false })
// { ok: true, cleaned_up: ['/path/to/sentinel.done', ...] }

快开始

import { Supervisor, resultTool, spawnTool, shutdownTool } from '@dougbots/avenor-core'

// 1. The supervisor auto-starts avenor. Call get() early — it's a singleton.
const sup = await Supervisor.get()

// 2. Spawn a run
const { run_id } = await spawnTool({
  agent: 'codex',
  prompt: 'Review src/app.ts for security issues',
  label: 'security-review',
})

// 3. Wait for the complete final output
const result = await resultTool({ runId: run_id })
console.log(result) // { run_id, label, status: 'done', ready: true, output: '...' }

// 4. Clean up
await shutdownTool()

出口