npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@haowei0520/acp-connector

v0.17.1

Published

Single-WebSocket ACP connector: connects local ACP stdio agents (opencode, claude code) to AgentNexus over /ws/acp.

Readme

@haowei0520/acp-connector

语言: English | 中文

在本地运行 ACP stdio Agent(OpenCode、Claude Code 或任意 Agent Client Protocol Agent),通过单一 /ws/acp WebSocket 接入 AgentNexus 服务端。控制帧与更新 流共用一条连接,不再有独立的 control/data 通道。

适用于 AgentNexus 部署在服务器上、而 ACP Agent 必须运行在开发者工作站、私有 机器或其他能访问本地凭据与项目文件的环境中的场景。

核心能力:

| 领域 | 行为 | | --- | --- | | 传输 | 每账号一条经认证的 /ws/acp WebSocket(?token=…&boot=…),自动重连(抖动退避),断线期间帧按序排队、重连后补发。服务端连续拒绝握手(HTTP 4xx,如 bot token 失效)达到预算(默认 10 次)后停止重连,状态页显示 handshake_rejected;网络故障与 5xx 响应不计入,会一直重试。 | | 会话 | 后端用进程级 boot id 协商续聊:本进程无法应答的会话轮换为 session/new,绝不加载过期会话。 | | MCP 工具 | 本地反向代理为每个回合提供独立端点(/mcp/{turnToken});身份来自 URL 而非猜测——无法确定归属的工具调用会被拒绝。 | | 入站文件 | 后端下发附件引用,由经授权的 Core MCP 工具读取内容;Connector 不再暂存下载。 | | 委托 | 回合的 delegate token 作为尽力而为的旁路激活/释放;失败只推迟 MCP 可用性,绝不阻塞 ACP 帧。 | | 运维 | 支持前台运行与命名守护进程模式(本地日志与状态命令)。 |

大模型 Token 计量

配置 llmUpstreamBaseUrl,并将 Agent 的模型请求路由到 Connector 的 /llm 入口后,0.12.4 会随 usage 上报可选的 cache_read_input_tokens(缓存读取)和 cache_creation_input_tokens(缓存写入)。Backend schema revision 81 将其保存到 每次调用的 usage_events,并汇总到用户回合的 usage_ledger;个人及管理员账单 API 都返回这两个字段。以上是本次源码版本,不代表已经发布或部署。

OpenAI Chat Completions 的 prompt_tokens 已包含缓存输入,其 prompt_tokens_details.cached_tokens 是缓存读取细分;Anthropic Messages 的 input_tokens 不包含缓存读写,因此 Connector 将三项相加一次,统一为总输入。 支持 JSON 和 SSE;Anthropic 初始 usage 与后续累计输出合并,不逐帧累加。

历史数据、旧 Connector 或上游未返回的维度保留未知(数据库 NULL),明确返回 的 0 保存为 0。只有回合中每条已收到的调用都报告该维度,回合汇总才给出数值。 缓存属于总输入的细分,不再重复叠加。积分仍按配置的输入/输出单价计算;缓存 独立定价及计量通知丢失后的可靠补账不在本次修改范围内。

配置

{
  "accounts": {
    "opencode-main": {
      "botToken": "agb_xxx",
      "acpUrl": "wss://agentnexus.example.com/ws/acp",
      "agent": {
        "transport": "stdio",
        "command": "opencode",
        "args": ["acp", "--cwd", "/Users/me/project"],
        "cwd": "/Users/me/project",
        "clickTheRequest": { "mode": "ask", "responder": "owner_or_requester" },
        "env": {
          "OPENCODE_CONFIG_CONTENT": "$OPENCODE_CONFIG_CONTENT"
        }
      }
    }
  }
}

| 字段 | 默认值 | 说明 | | --- | --- | --- | | botToken | 必填 | Bot 凭据;用于 WS query token 与 API 调用。 | | acpUrl | 必填 | ws(s)://host/ws/acp。0.1.x 的 controlUrl/dataUrl 会被拒绝——这些端点在服务端从未存在。 | | httpBaseUrl | 由 acpUrl 推导 | MCP/委托/文件调用的 HTTP base。 | | mcpUrl | ${httpBaseUrl}/api/v1/mcp | 本地代理的上游 MCP 端点。 | | localMcpPort | 28888 | 本地 MCP 反向代理端口(只绑 127.0.0.1)。 | | maxSessionProcesses | capacity,否则 10 | 常驻 Session 子进程上限,并作为连接并发容量通告;另有一个控制进程。满载时拒绝新建,不杀活动任务。 | | sessionIdleTimeoutMs | 300000 | 空闲回收时间;通过 resume/load 恢复原会话,长时间无输出的活动 prompt 不回收。 | | agent.requestTimeoutMs | 120000 | 本地准备超时回退值,范围 1–3,600,000ms;Backend 随请求下发的预算优先。覆盖资源分配、初始化、恢复和配置;prompt 转发后解除。 | | perSessionMcp | true | 在 session/new/session/load 中通告每回合独立 MCP 端点。 | | promptKeepaliveMs | 2000 | 回合流式期间的 agent 思考保活(解除后端流空闲看门狗)。0 关闭。 | | pingIntervalMs | 15000 | WS ping 心跳。 | | handshakeFailureMaxAttempts | 10 | 连续 HTTP 4xx 握手被拒的容忍次数,超过后 connector 停止重连(状态页显示 handshake_rejected)。0 表示永不放弃。修好 token 后用状态页「立即重连」或重启守护进程恢复。 |

agentnexus-acp-connector --config ./agentnexus-acp.json

Connector 0.15.1 通告 setupTimeoutV1。配套 Core/Bot 将 Bot 页面保存的 Request timeout(5–3,600 秒)传到执行请求;未配置时使用 ACP_SESSION_SETUP_TIMEOUT_SECONDS(默认 120 秒)。每条准备 RPC 的预算包含 内部冷恢复,不在初始化、恢复、配置之间重新计时。无 Backend 预算的发现/准备请求 使用上述本地回退值。过期或取消会移除排队请求并忽略迟到响应;已发出的配置不能据此 宣称撤销,取消也不证明远端执行已停止。消除旧的两层限制需要配套升级 Core/Bot 和 Connector。旧 promptTimeoutMs 字段不在当前承载运行时启用总执行期限;执行限时仍需显式配置。

Pi 默认预设

connect --agent pi 使用 @openma/pi-acp(命令 openma-pi-acp),交互安装固定为 0.1.8。需要 Node.js 22.19 或更高版本:

npm install -g @openma/[email protected]

此适配器按会话接收 ACP 注入的 HTTP / stdio MCP。Connector 自动提供 AgentNexus 端点和凭据,无需修改共享 mcp.json。此预设不支持旧式 SSE。

已有账号保留原来的启动命令。迁移时先备份配置,把对应账号的 agent.command 改为 openma-pi-acp、agent.args 改为 [],保留其他设置,再重启对应 Connector 并新建会话。自定义适配器仍可通过 --agent-cmd <command> 接入。

安装固定版本适配器后,可在此包目录运行 npm run test:pi,或通过 PI_ACP_BIN=/path/to/openma-pi-acp 指向临时安装。此可选本地合同测试使用真实适配器、 Connector relay、会话进程池和 MCP 代理,模型与上游 MCP 为确定性的回环服务。 覆盖双会话并发、工具发现/调用/结果返回、下一任务凭据和无共享 mcp.json 写入。 测试使用临时 Pi 配置,无需外部模型账号,不代表 Kubernetes 或生产环境验收。

本地接入流程

  1. 在 AgentNexus 中创建 Agent Bridge Bot(系统管理 → Agent 桥接,或用个人令牌 调 POST /api/v1/bots),复制页面给出的配置片段;它已指向 /ws/acp。
  2. 保存为本地 JSON 文件,按需调整 agent 部分(命令、工作区、环境变量)。
  3. 在运行 Agent 的机器上启动 connector:
agentnexus-acp-connector start --config ./agentnexus-acp.json --name opencode-main
  1. 在 AgentNexus 中把 Bot 拉入频道或私聊,发送 @opencode-main hello。

npm CLI 与守护进程

npm install -g @haowei0520/acp-connector
agentnexus-acp-connector start --config ./agentnexus-acp.json --name opencode-main
agentnexus-acp-connector status --name opencode-main
agentnexus-acp-connector logs --name opencode-main --lines 200
agentnexus-acp-connector restart --name opencode-main
agentnexus-acp-connector stop --name opencode-main

守护进程元数据与日志位于 ~/.agentnexus/acp-connector/<name>/(可用 --home 或 AGENTNEXUS_ACP_HOME 覆盖)。

一个回合的完整流程

  1. 后端发送 session/new/session/load,_meta.agentnexus 携带调度上下文 (频道、任务、turn token、delegate token)。
  2. relay 剥离 _meta,通告本回合的本地 MCP 端点 (http://127.0.0.1:{port}/mcp/{turnToken}),并登记身份。
  3. session/prompt 到达:文本(当回合已委托授权且 Agent 声明了对应 prompt 能力时,还带附件引用列表)。relay 预置 [Context: channel_id=…, task_id=…] 指令,把拉取到的附件落盘为 resource_link 块,再转发给 Agent。
  4. Agent 的 session/update 流按 chunk 透传;终结 agent_message 会被改写为 agent_message_chunk(后端把终结 ACP 响应分类为回合结果)。
  5. ping 探测在本地应答。Agent 发起的 session/request_permission 使用 worker 隔离的 ID 转发到后端;WebSocket 离线时在本地取消。Session 错误结束 当前 Task,不自动重放 prompt 或工具副作用。
  6. 取消全走标准 ACP:后端自行将消息解析为 session/cancel,连接器仅做 session id 双向映射后转发,不再有自定义取消帧。

从 0.1.x 迁移

  • 把 controlUrl/dataUrl 换成单一 acpUrl(wss://host/ws/acp)。携带旧键 的配置会立即报错并指明改法,而不是对着 404 永久重连。
  • 本地会话状态文件(statePath)已移除;WS query 中的 boot id 取代之。
  • @haowei0520/bridge-client 已退役,不再是依赖。

发布

发布从 develop 最终提交手工执行:包版本随代码同一变更集内升级,合并到 develop 后在该提交上打注解 tag,再基于同一棵树发布产物:

git tag -a agentnexus-acp-connector-v0.2.0 -m "agentnexus-acp-connector v0.2.0"
git push origin agentnexus-acp-connector-v0.2.0
npm publish --access public
# 构建并推送容器化 runtime:
# harbor.epichust.com/ai/agentnexus-opencode-bot:<version>

tag 必须与 package.json 完全一致(agentnexus-acp-connector-v<version>)。

升级至 0.12.0

升级前先等待当前任务结束。每个常驻 ACP Session 使用独立 Agent 进程, 保留原业务 cwd;MCP 注册名固定为 agentnexus,地址在 Session 生命周期内固定。存活 Session 每轮直接 prompt,不再 resume/load; Shadow 在收到 HTTP 请求时固定当前 Task 凭据,私有元数据在转给 Agent 前删除。 平台 Token 保存在 Connector,不放入模型提示词。已进入 Shadow 的请求固定旧身份;用户已接受尚未抵达的旧调用按抵达时当前轮次授权。 跨 Session 独立入口与上下文,空闲时拒绝工具调用。

每次模型请求只有一份 MCP 工具定义与说明,不随历史 Task 或其他 Session 累积。 模型 API 仍可能要求每次携带 schema 并计费;不承诺整个会话只计一次 token。 容量默认 10 个 Session 子进程,另有控制进程,需评估内存。空闲进程回收后仅通过 resume/load 恢复会话,不重跑失败任务;Agent 不支持恢复时会明确失败。 初始化 401/403 返回明确鉴权错误,不包装为可重试的普通代理故障。

npm run test:opencode 使用真实 OpenCode 和本地模型/Core 替身验证线协议, 不调用外部模型,不代表已通过 Kubernetes/UAT 端到端验收。

OpenCode 的控制进程与各 Session 使用独立 OPENCODE_DB 文件,避免首次 WAL 初始化锁竞争; 原业务 cwd、配置及账户凭据目录保留。此运行期覆盖也适用于包装命令,优先于用户提供的 共享 OPENCODE_DB。数据库位于账户私有临时目录,空闲恢复保留,正常停止 Connector 后删除。 Session 元数据上限 4,096;工具目录变更需新建 Session,每次调用仍由 Core 检查实时权限。

clickTheRequest 以 Core 中由 Bot Owner 管理的设置为准。本地配置与旧标量别名仅兼容读取,不会授予审批权限或覆盖平台策略;需要无人值守时,请在 Bot 设置中明确选择自动策略。默认询问当前有频道访问权的 Owner 或原始任务发起人。