nexus-agentd 0.1.0

package/README.md

@@ -0,0 +1,253 @@
+# nexus-agentd
+
+`nexus-agentd` 运行在 Coding Agent 所在机器，通过 Bearer Token 保护的 HTTP/SSE Gateway
+向 AgentNexus 暴露本机白名单 Agent。当前支持 OpenCode、Claude Code、Codex、Pi 和
+OpenClaw ACP Driver；Hermes 使用其原生 A2A Server，不经过 agentd。
+
+当前部署目标是 Linux/Unix Agent 主机。
+
+```text
+AgentNexus
+    │ HTTP/SSE
+    ▼
+nexus-agentd
+    │ ACP stdio
+    ▼
+OpenCode / Claude Code / Codex / Pi / OpenClaw
+```
+
+## 安装与启动
+
+```bash
+npm install -g nexus-agentd
+curl -fsSL \
+  https://raw.githubusercontent.com/lumia1998/koishi-plugin-agent-nexus/main/packages/nexus-agentd/nexus-agentd.example.json \
+  -o nexus-agentd.json
+export NEXUS_AGENTD_TOKEN='TOKEN'
+nexus-agentd --config nexus-agentd.json
+```
+
+OpenCode 和 OpenClaw 自带 ACP 入口。Claude Code、Codex、Pi 需要先安装对应 adapter：
+
+```bash
+npm install -g \
+  @agentclientprotocol/claude-agent-acp \
+  @agentclientprotocol/codex-acp \
+  pi-acp
+```
+
+还需要分别完成各 Agent 自身的登录或 API Key 配置。`claude-agent-acp` 当前要求 Node.js 22
+或更高版本；其他 adapter 的版本要求以各自发布包为准。
+
+也可以设置配置路径：
+
+```bash
+export NEXUS_AGENTD_CONFIG=/etc/agent-nexus/nexus-agentd.json
+nexus-agentd
+```
+
+从仓库开发：
+
+```bash
+npm install
+npm run build
+node dist/cli.js --config nexus-agentd.json
+```
+
+## 配置
+
+```json
+{
+  "listen": {
+    "host": "127.0.0.1",
+    "port": 8787
+  },
+  "authToken": "env:NEXUS_AGENTD_TOKEN",
+  "workspaceRoots": [
+    "/data/repos"
+  ],
+  "agents": {
+    "opencode": {
+      "driver": "opencode",
+      "command": "opencode",
+      "args": ["acp"],
+      "permissionPolicy": "ask",
+      "inheritEnv": [
+        "OPENAI_API_KEY",
+        "ANTHROPIC_API_KEY"
+      ]
+    },
+    "claude": {
+      "driver": "claude",
+      "command": "claude-agent-acp",
+      "permissionPolicy": "ask"
+    },
+    "codex": {
+      "driver": "codex",
+      "command": "codex-acp",
+      "permissionPolicy": "ask"
+    },
+    "pi": {
+      "driver": "pi",
+      "command": "pi-acp",
+      "permissionPolicy": "ask"
+    },
+    "openclaw": {
+      "driver": "openclaw",
+      "command": "openclaw",
+      "args": ["acp"],
+      "permissionPolicy": "ask"
+    }
+  }
+}
+```
+
+主要字段：
+
+| 字段 | 说明 |
+|---|---|
+| `listen.host` | 默认 `127.0.0.1`；LAN 访问需显式改为内网地址或 `0.0.0.0` |
+| `listen.port` | HTTP/SSE 监听端口，默认 `8787` |
+| `authToken` | 必填 Bearer Token，支持 `env:VAR` |
+| `workspaceRoots` | 允许启动 ACP Session 的目录根列表 |
+| `agents` | daemon 本地 Agent 白名单 |
+| `driver` | `opencode`、`claude`、`codex`、`pi` 或 `openclaw` |
+| `permissionPolicy` | `ask` 或 `deny`，默认 `ask` |
+| `permissionTimeoutMs` | 权限或输入请求等待时间 |
+| `inheritEnv` | 额外允许传给 Agent 子进程的本机环境变量名 |
+| `env` | 显式环境变量，值支持 `env:VAR` |
+
+默认入口：
+
+| Driver | 默认命令 | 说明 |
+|---|---|---|
+| `opencode` | `opencode acp` | OpenCode 原生 ACP Server |
+| `claude` | `claude-agent-acp` | `@agentclientprotocol/claude-agent-acp` |
+| `codex` | `codex-acp` | `@agentclientprotocol/codex-acp`，自带兼容 Codex 依赖 |
+| `pi` | `pi-acp` | adapter 再启动本机 `pi --mode rpc` |
+| `openclaw` | `openclaw acp` | OpenClaw 原生 Gateway ACP Bridge |
+
+OpenClaw Gateway 必须已运行并可被 `openclaw acp` 访问。可通过 OpenClaw 本机配置保存 Gateway
+地址和凭据，也可在 `args` 中使用 `--url` 与 `--token-file`。不要把明文 Token 提交到仓库。
+
+Pi Driver 会同时探测 `pi-acp` 和底层 `pi`。如果 Pi 可执行文件不是默认名称，通过
+`env.PI_ACP_PI_COMMAND` 指定。
+
+`command` 和 `args` 只从 agentd 本机配置读取。HTTP 客户端不能覆盖它们。
+
+## API
+
+```text
+GET  /health
+GET  /v1/agents
+POST /v1/sessions
+GET  /v1/sessions/:id
+POST /v1/sessions/:id/message
+POST /v1/sessions/:id/cancel
+GET  /v1/sessions/:id/events
+```
+
+除 `/health` 外都要求：
+
+```http
+Authorization: Bearer TOKEN
+```
+
+创建 Session 的请求只接受：
+
+```json
+{
+  "agentId": "claude",
+  "workspace": "/data/repos/project"
+}
+```
+
+发送消息只接受：
+
+```json
+{
+  "message": "检查并修复测试"
+}
+```
+
+额外字段会返回 `400`，因此客户端不能传入 command、argv 或 shell payload。
+
+## Session 与事件
+
+一个 Gateway Session 对应一个 ACP 子进程和一个 ACP Session。Session 完成后再次发送消息，
+会续接同一 ACP Session；每轮输出单独保存，不与上一轮文本拼接。
+
+状态：
+
+```text
+created
+running
+input_required
+permission_required
+completed
+failed
+canceled
+```
+
+SSE 事件包括：
+
+```text
+session_state
+assistant_chunk
+thought_chunk
+plan
+tool_call
+tool_update
+terminal_output
+file_activity
+permission_required
+input_required
+completed
+failed
+canceled
+```
+
+`/events` 支持 `after` 查询参数和 `Last-Event-ID`，用于重放内存事件日志中的后续事件。
+
+Session 当前保存在内存中。agentd 重启会终止 ACP 子进程，旧 Gateway Session 不可恢复。
+
+## 权限与输入
+
+`permissionPolicy=ask` 时，ACP permission request 会进入 `permission_required`，Session 响应
+包含问题和选项。AgentNexus 通过 `message` 返回：
+
+- 选项序号，例如 `1`
+- option ID
+- option name
+- `deny`、`cancel`、`拒绝` 或 `取消`
+
+ACP elicitation 会进入 `input_required`。简单单字段表单可直接回复文本、数字、布尔值或列表；
+多字段结构化输入使用 JSON object。
+
+`permissionPolicy=deny` 会选择协议提供的拒绝选项，或在没有拒绝选项时取消请求。
+
+## Workspace 安全
+
+workspace 在启动 ACP 子进程前执行：
+
+1. `realpath(workspace)`。
+2. `realpath` 每个 `workspaceRoots`。
+3. 使用路径边界检查确认 workspace 位于允许根内。
+
+这会拒绝 `../` 逃逸、允许根之外的绝对路径和 symlink/junction 逃逸。workspace 必须已经存在。
+
+## 网络建议
+
+- 默认保持 `127.0.0.1`。
+- LAN 监听时使用强随机 Token 和主机防火墙限制 Koishi 来源 IP。
+- 不要直接暴露到公网；需要跨网络时在前面部署 HTTPS/mTLS 反向代理。
+- 使用权限受限的专用系统账号运行 agentd。
+
+## 验证
+
+```bash
+npm test
+npm run typecheck
+npm run build
+npm pack --dry-run --json
+```

package/dist/acp/runtime.d.ts

@@ -0,0 +1,26 @@
+import type { AgentDriver } from '../drivers/index.js';
+import type { AcpSessionSink } from '../session-contract.js';
+export declare class AcpProcessRuntime {
+    private readonly driver;
+    private readonly sink;
+    private process?;
+    private connection?;
+    private pending?;
+    private pendingInput?;
+    private disposed;
+    private prompting;
+    constructor(driver: AgentDriver, sink: AcpSessionSink);
+    start(workspace: string): Promise<void>;
+    prompt(message: string): Promise<void>;
+    respondPending(message: string): Promise<void>;
+    cancel(): Promise<void>;
+    dispose(): Promise<void>;
+    private requestPermission;
+    private finishPermission;
+    private requestInput;
+    private finishInput;
+    private sessionUpdate;
+    private captureStderr;
+    private onProcessFailure;
+    private requireSessionId;
+}

package/dist/acp/runtime.js

@@ -0,0 +1,420 @@
+import { randomUUID } from 'node:crypto';
+import { Readable, Writable } from 'node:stream';
+import * as acp from '@agentclientprotocol/sdk';
+export class AcpProcessRuntime {
+    driver;
+    sink;
+    process;
+    connection;
+    pending;
+    pendingInput;
+    disposed = false;
+    prompting = false;
+    constructor(driver, sink) {
+        this.driver = driver;
+        this.sink = sink;
+    }
+    async start(workspace) {
+        if (this.process)
+            throw new Error('ACP runtime is already started');
+        const child = this.driver.spawn(workspace);
+        this.process = child;
+        this.captureStderr(child);
+        child.once('error', (error) => this.onProcessFailure(error));
+        child.once('exit', (code, signal) => {
+            if (this.disposed)
+                return;
+            if (this.sink.state === 'canceled' || this.sink.state === 'completed')
+                return;
+            this.onProcessFailure(new Error(`ACP agent exited unexpectedly (${signal || code || 'unknown'})`));
+        });
+        const app = acp
+            .client({ name: 'nexus-agentd' })
+            .onRequest(acp.methods.client.session.requestPermission, ({ params }) => this.requestPermission(params))
+            .onRequest(acp.methods.client.elicitation.create, ({ params }) => this.requestInput(params))
+            .onNotification(acp.methods.client.session.update, ({ params }) => {
+            this.sessionUpdate(params);
+        });
+        const stream = acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+        this.connection = app.connect(stream);
+        const initialize = await this.connection.agent.request(acp.methods.agent.initialize, {
+            protocolVersion: acp.PROTOCOL_VERSION,
+            clientCapabilities: {
+                elicitation: {
+                    form: {},
+                    url: {}
+                }
+            },
+            clientInfo: {
+                name: 'nexus-agentd',
+                version: '0.1.0'
+            }
+        });
+        if (initialize.protocolVersion !== acp.PROTOCOL_VERSION) {
+            this.sink.emit('terminal_output', {
+                stream: 'system',
+                text: `ACP negotiated protocol ${initialize.protocolVersion}`
+            });
+        }
+        const session = await this.connection.agent.request(acp.methods.agent.session.new, {
+            cwd: workspace,
+            mcpServers: []
+        });
+        this.sink.setAcpSessionId(String(session.sessionId));
+        this.sink.setState('created');
+    }
+    async prompt(message) {
+        if (!this.connection)
+            throw new Error('ACP runtime is not connected');
+        if (this.prompting)
+            throw new Error('ACP session is already processing a prompt');
+        const sessionId = this.requireSessionId();
+        this.prompting = true;
+        this.sink.clearPending();
+        this.sink.setState('running');
+        try {
+            const response = await this.connection.agent.request(acp.methods.agent.session.prompt, {
+                sessionId,
+                prompt: [{ type: 'text', text: message }]
+            });
+            if (this.sink.state === 'canceled')
+                return;
+            if (response.stopReason === 'cancelled') {
+                this.sink.setState('canceled');
+            }
+            else if (response.stopReason === 'refusal') {
+                this.sink.setState('failed', 'ACP agent refused the prompt');
+            }
+            else {
+                this.sink.setState('completed');
+            }
+        }
+        catch (error) {
+            if (this.sink.state !== 'canceled') {
+                this.sink.setState('failed', error instanceof Error ? error.message : String(error));
+            }
+        }
+        finally {
+            this.prompting = false;
+        }
+    }
+    async respondPending(message) {
+        if (this.pendingInput) {
+            this.finishInput(message);
+            return;
+        }
+        const pending = this.pending;
+        if (!pending)
+            throw new Error('ACP session is not waiting for input');
+        const normalized = message.trim().toLowerCase();
+        const options = pending.request.options || [];
+        if (['cancel', 'deny', 'reject', '拒绝', '取消', '不同意'].includes(normalized)) {
+            this.finishPermission({ outcome: { outcome: 'cancelled' } });
+            return;
+        }
+        const numeric = Number(normalized);
+        const option = Number.isInteger(numeric) && numeric >= 1
+            ? options[numeric - 1]
+            : options.find((item) => item.id.toLowerCase() === normalized ||
+                item.name.toLowerCase() === normalized);
+        if (!option) {
+            throw new Error(`Permission answer must be an option id/name or index: ${options
+                .map((item, index) => `${index + 1}. ${item.name} (${item.id})`)
+                .join('; ')}`);
+        }
+        this.finishPermission({
+            outcome: {
+                outcome: 'selected',
+                optionId: option.id
+            }
+        });
+    }
+    async cancel() {
+        if (this.pending) {
+            this.finishPermission({ outcome: { outcome: 'cancelled' } });
+        }
+        if (this.pendingInput) {
+            this.finishInput('cancel');
+        }
+        if (this.connection && this.sink.state !== 'canceled') {
+            try {
+                await this.connection.agent.notify(acp.methods.agent.session.cancel, {
+                    sessionId: this.requireSessionId()
+                });
+            }
+            catch (error) {
+                this.sink.emit('terminal_output', {
+                    stream: 'system',
+                    text: `ACP cancellation notification failed: ${error instanceof Error ? error.message : String(error)}`
+                });
+            }
+        }
+        this.sink.setState('canceled');
+        await this.dispose();
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.pending) {
+            clearTimeout(this.pending.timer);
+            this.pending.reject(new Error('ACP runtime disposed'));
+            this.pending = undefined;
+        }
+        if (this.pendingInput) {
+            clearTimeout(this.pendingInput.timer);
+            this.pendingInput.resolve({ action: 'cancel' });
+            this.pendingInput = undefined;
+        }
+        this.connection?.close();
+        this.connection = undefined;
+        const child = this.process;
+        this.process = undefined;
+        if (child && child.exitCode === null && child.signalCode === null) {
+            child.kill();
+        }
+    }
+    requestPermission(params) {
+        if (this.driver.permissionPolicy === 'deny') {
+            const reject = params.options.find((option) => option.kind.startsWith('reject'));
+            return reject
+                ? {
+                    outcome: {
+                        outcome: 'selected',
+                        optionId: reject.optionId
+                    }
+                }
+                : { outcome: { outcome: 'cancelled' } };
+        }
+        if (this.pending) {
+            return { outcome: { outcome: 'cancelled' } };
+        }
+        const request = {
+            id: randomUUID(),
+            kind: 'permission',
+            prompt: params.toolCall.title ||
+                `Permission requested for tool ${params.toolCall.toolCallId}`,
+            options: params.options.map((option) => ({
+                id: option.optionId,
+                name: option.name,
+                kind: option.kind
+            }))
+        };
+        this.sink.setPending(request);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.pending?.request.id !== request.id)
+                    return;
+                this.pending = undefined;
+                this.sink.clearPending();
+                this.sink.setState('failed', 'ACP permission request timed out');
+                resolve({ outcome: { outcome: 'cancelled' } });
+            }, this.driver.permissionTimeoutMs);
+            this.pending = { request, resolve, reject, timer };
+        });
+    }
+    finishPermission(response) {
+        const pending = this.pending;
+        if (!pending)
+            return;
+        this.pending = undefined;
+        clearTimeout(pending.timer);
+        this.sink.clearPending();
+        this.sink.setState('running');
+        pending.resolve(response);
+    }
+    requestInput(params) {
+        if (this.pending || this.pendingInput) {
+            return Promise.resolve({ action: 'cancel' });
+        }
+        const request = {
+            id: randomUUID(),
+            kind: 'input',
+            prompt: params.mode === 'url'
+                ? `${params.message}\n${params.url}`
+                : params.message,
+            options: elicitationOptions(params)
+        };
+        this.sink.setPending(request);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (this.pendingInput?.request.id !== request.id)
+                    return;
+                this.pendingInput = undefined;
+                this.sink.clearPending();
+                this.sink.setState('failed', 'ACP input request timed out');
+                resolve({ action: 'cancel' });
+            }, this.driver.permissionTimeoutMs);
+            this.pendingInput = { request, params, resolve, timer };
+        });
+    }
+    finishInput(message) {
+        const pending = this.pendingInput;
+        if (!pending)
+            return;
+        const normalized = message.trim().toLowerCase();
+        let response;
+        if (['cancel', '取消'].includes(normalized)) {
+            response = { action: 'cancel' };
+        }
+        else if (['decline', '拒绝', '不同意'].includes(normalized)) {
+            response = { action: 'decline' };
+        }
+        else if (!isFormElicitation(pending.params)) {
+            response = { action: 'accept' };
+        }
+        else {
+            response = {
+                action: 'accept',
+                content: elicitationContent(pending.params, message)
+            };
+        }
+        this.pendingInput = undefined;
+        clearTimeout(pending.timer);
+        this.sink.clearPending();
+        this.sink.setState('running');
+        pending.resolve(response);
+    }
+    sessionUpdate(params) {
+        const update = params.update;
+        switch (update.sessionUpdate) {
+            case 'agent_message_chunk':
+                if (update.content.type === 'text') {
+                    this.sink.appendOutput(update.content.text);
+                    this.sink.emit('assistant_chunk', {
+                        messageId: update.messageId,
+                        content: update.content
+                    });
+                }
+                break;
+            case 'agent_thought_chunk':
+                this.sink.emit('thought_chunk', update);
+                break;
+            case 'tool_call':
+                this.sink.emit('tool_call', update);
+                if (update.locations?.length) {
+                    this.sink.emit('file_activity', {
+                        toolCallId: update.toolCallId,
+                        locations: update.locations
+                    });
+                }
+                break;
+            case 'tool_call_update':
+                this.sink.emit('tool_update', update);
+                if (update.locations?.length) {
+                    this.sink.emit('file_activity', {
+                        toolCallId: update.toolCallId,
+                        locations: update.locations
+                    });
+                }
+                break;
+            case 'plan':
+            case 'plan_update':
+            case 'plan_removed':
+                this.sink.emit('plan', update);
+                break;
+            default:
+                break;
+        }
+    }
+    captureStderr(child) {
+        let buffer = '';
+        child.stderr.on('data', (chunk) => {
+            buffer += String(chunk);
+            const lines = buffer.split(/\r?\n/);
+            buffer = lines.pop() || '';
+            for (const line of lines) {
+                if (line) {
+                    this.sink.emit('terminal_output', {
+                        stream: 'stderr',
+                        text: line
+                    });
+                }
+            }
+        });
+    }
+    onProcessFailure(error) {
+        if (this.disposed)
+            return;
+        this.sink.setState('failed', error instanceof Error ? error.message : String(error));
+    }
+    requireSessionId() {
+        const value = this.sink.acpSessionId;
+        if (typeof value !== 'string' || !value) {
+            throw new Error('ACP session has not been initialized');
+        }
+        return value;
+    }
+}
+function elicitationOptions(params) {
+    if (!isFormElicitation(params))
+        return undefined;
+    const properties = params.requestedSchema.properties || {};
+    if (Object.keys(properties).length !== 1)
+        return undefined;
+    const schema = Object.values(properties)[0];
+    if (schema.type !== 'string')
+        return undefined;
+    const oneOf = Array.isArray(schema.oneOf)
+        ? schema.oneOf
+        : [];
+    if (oneOf.length) {
+        return oneOf.map((option) => ({
+            id: String(option.const),
+            name: String(option.title),
+            kind: 'input'
+        }));
+    }
+    const values = Array.isArray(schema.enum)
+        ? schema.enum
+        : [];
+    return values.map((value) => ({
+        id: String(value),
+        name: String(value),
+        kind: 'input'
+    }));
+}
+function elicitationContent(params, message) {
+    try {
+        const parsed = JSON.parse(message);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch { }
+    const properties = params.requestedSchema.properties || {};
+    const entries = Object.entries(properties);
+    if (entries.length !== 1) {
+        throw new Error('Structured ACP input requires a JSON object');
+    }
+    const [key, schema] = entries[0];
+    if (schema.type === 'boolean') {
+        const value = message.trim().toLowerCase();
+        if (['true', 'yes', '1', '是'].includes(value))
+            return { [key]: true };
+        if (['false', 'no', '0', '否'].includes(value))
+            return { [key]: false };
+        throw new Error('Boolean ACP input must be true/false or yes/no');
+    }
+    if (schema.type === 'number' || schema.type === 'integer') {
+        const value = Number(message);
+        if (!Number.isFinite(value))
+            throw new Error('ACP input must be a number');
+        return { [key]: schema.type === 'integer' ? Math.trunc(value) : value };
+    }
+    if (schema.type === 'array') {
+        return {
+            [key]: message
+                .split(/[,，\n]/)
+                .map((item) => item.trim())
+                .filter(Boolean)
+        };
+    }
+    return { [key]: message };
+}
+function isFormElicitation(params) {
+    return (params.mode === 'form' &&
+        Boolean(params.requestedSchema &&
+            typeof params.requestedSchema ===
+                'object'));
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};