nexus-agentd 0.1.0

package/dist/server.js

@@ -0,0 +1,170 @@
+import { timingSafeEqual } from 'node:crypto';
+import http from 'node:http';
+import { SessionNotFoundError } from './session.js';
+export function createAgentdServer(config, sessions) {
+    return http.createServer((request, response) => {
+        void handleRequest(config, sessions, request, response).catch((error) => {
+            if (response.headersSent) {
+                response.destroy(error instanceof Error ? error : undefined);
+                return;
+            }
+            const status = error instanceof SessionNotFoundError
+                ? 404
+                : error instanceof RequestError
+                    ? error.status
+                    : 500;
+            writeJson(response, status, {
+                error: error instanceof Error ? error.message : String(error)
+            });
+        });
+    });
+}
+async function handleRequest(config, sessions, request, response) {
+    const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname === '/health' && request.method === 'GET') {
+        writeJson(response, 200, { ok: true });
+        return;
+    }
+    authenticate(request, config.authToken);
+    if (url.pathname === '/v1/agents' && request.method === 'GET') {
+        writeJson(response, 200, { agents: await sessions.listAgents() });
+        return;
+    }
+    if (url.pathname === '/v1/sessions' && request.method === 'POST') {
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['agentId', 'workspace']);
+        const agentId = requiredString(body.agentId, 'agentId');
+        const workspace = requiredString(body.workspace, 'workspace');
+        writeJson(response, 201, await sessions.create(agentId, workspace));
+        return;
+    }
+    const match = url.pathname.match(/^\/v1\/sessions\/([^/]+)(?:\/(message|cancel|events))?$/);
+    if (!match)
+        throw new RequestError(404, 'Route not found');
+    const sessionId = decodeURIComponent(match[1]);
+    const action = match[2];
+    if (!action && request.method === 'GET') {
+        writeJson(response, 200, sessions.get(sessionId));
+        return;
+    }
+    if (action === 'message' && request.method === 'POST') {
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['message']);
+        writeJson(response, 202, await sessions.message(sessionId, requiredString(body.message, 'message')));
+        return;
+    }
+    if (action === 'cancel' && request.method === 'POST') {
+        if (Number(request.headers['content-length'] || 0) > 0) {
+            const body = await readJsonBody(request, config.maxRequestBytes);
+            assertOnlyKeys(body, []);
+        }
+        writeJson(response, 200, await sessions.cancel(sessionId));
+        return;
+    }
+    if (action === 'events' && request.method === 'GET') {
+        streamEvents(request, response, sessions, sessionId, url.searchParams.get('after') ||
+            stringHeader(request.headers['last-event-id']));
+        return;
+    }
+    throw new RequestError(405, 'Method not allowed');
+}
+function streamEvents(request, response, sessions, sessionId, after) {
+    sessions.get(sessionId);
+    response.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no'
+    });
+    response.flushHeaders?.();
+    for (const event of sessions.eventsAfter(sessionId, after)) {
+        writeEvent(response, event);
+    }
+    const unsubscribe = sessions.subscribe(sessionId, (event) => writeEvent(response, event));
+    const heartbeat = setInterval(() => response.write(': heartbeat\n\n'), 15_000);
+    const close = () => {
+        clearInterval(heartbeat);
+        unsubscribe();
+    };
+    request.once('close', close);
+    response.once('close', close);
+}
+function writeEvent(response, event) {
+    if (response.destroyed || response.writableEnded)
+        return;
+    response.write(`id: ${event.id}\n`);
+    response.write(`event: ${event.type}\n`);
+    response.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+function authenticate(request, expected) {
+    const value = stringHeader(request.headers.authorization);
+    if (!value.startsWith('Bearer ')) {
+        throw new RequestError(401, 'Bearer token is required');
+    }
+    const actual = value.slice(7);
+    const left = Buffer.from(actual);
+    const right = Buffer.from(expected);
+    if (left.length !== right.length || !timingSafeEqual(left, right)) {
+        throw new RequestError(401, 'Invalid Bearer token');
+    }
+}
+async function readJsonBody(request, maxBytes) {
+    const declared = Number(request.headers['content-length']);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        throw new RequestError(413, 'Request body is too large');
+    }
+    const chunks = [];
+    let total = 0;
+    for await (const value of request) {
+        const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
+        total += chunk.length;
+        if (total > maxBytes)
+            throw new RequestError(413, 'Request body is too large');
+        chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString('utf8');
+    if (!raw.trim())
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('body must be an object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new RequestError(400, `Invalid JSON body: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function assertOnlyKeys(body, allowed) {
+    const accepted = new Set(allowed);
+    const unknown = Object.keys(body).filter((key) => !accepted.has(key));
+    if (unknown.length) {
+        throw new RequestError(400, `Unsupported request fields: ${unknown.join(', ')}`);
+    }
+}
+function requiredString(value, name) {
+    const text = typeof value === 'string' ? value.trim() : '';
+    if (!text)
+        throw new RequestError(400, `${name} is required`);
+    return text;
+}
+function stringHeader(value) {
+    return Array.isArray(value) ? value[0] || '' : value || '';
+}
+function writeJson(response, status, value) {
+    const body = `${JSON.stringify(value)}\n`;
+    response.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(body),
+        'Cache-Control': 'no-store'
+    });
+    response.end(body);
+}
+class RequestError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}

package/dist/session-contract.d.ts

@@ -0,0 +1,12 @@
+import type { AgentdEventType, AgentdPendingRequest, AgentdSessionState } from './types.js';
+export interface AcpSessionSink {
+    readonly id: string;
+    readonly state: AgentdSessionState;
+    readonly acpSessionId?: string;
+    setAcpSessionId(id: string): void;
+    setState(state: AgentdSessionState, error?: string): void;
+    appendOutput(text: string): void;
+    setPending(request: AgentdPendingRequest): void;
+    clearPending(): void;
+    emit(type: AgentdEventType, data?: unknown): void;
+}

package/dist/session-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/session.d.ts

@@ -0,0 +1,26 @@
+import type { AgentDriver } from './drivers/index.js';
+import type { WorkspacePolicy } from './workspace.js';
+import type { AgentdAgentView, AgentdConfig, AgentdEvent, AgentdSessionView } from './types.js';
+export declare class SessionManager {
+    private readonly config;
+    private readonly workspacePolicy;
+    private readonly drivers;
+    private sessions;
+    private cleanupTimer?;
+    constructor(config: AgentdConfig, workspacePolicy: WorkspacePolicy, drivers: Map<string, AgentDriver>);
+    startCleanup(): void;
+    listAgents(): Promise<AgentdAgentView[]>;
+    create(agentId: string, workspaceInput: string): Promise<AgentdSessionView>;
+    get(id: string): AgentdSessionView;
+    message(id: string, message: string): Promise<AgentdSessionView>;
+    cancel(id: string): Promise<AgentdSessionView>;
+    eventsAfter(id: string, after?: string): AgentdEvent[];
+    subscribe(id: string, listener: (event: AgentdEvent) => void): () => boolean;
+    shutdown(): Promise<void>;
+    private require;
+    private cleanup;
+}
+export declare class SessionNotFoundError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}

package/dist/session.js

@@ -0,0 +1,210 @@
+import { randomUUID } from 'node:crypto';
+import { SessionEventLog } from './events.js';
+import { AcpProcessRuntime } from './acp/runtime.js';
+class ManagedSession {
+    agentId;
+    workspace;
+    maxOutputChars;
+    id = randomUUID();
+    createdAt = Date.now();
+    events;
+    state = 'created';
+    updatedAt = this.createdAt;
+    acpSessionId;
+    output = '';
+    error;
+    pendingRequest;
+    runtime;
+    constructor(agentId, workspace, maxEvents, maxOutputChars) {
+        this.agentId = agentId;
+        this.workspace = workspace;
+        this.maxOutputChars = maxOutputChars;
+        this.events = new SessionEventLog(this.id, maxEvents);
+        this.events.append('session_state', { state: this.state });
+    }
+    attach(runtime) {
+        this.runtime = runtime;
+    }
+    setAcpSessionId(id) {
+        this.acpSessionId = id;
+        this.updatedAt = Date.now();
+    }
+    setState(state, error) {
+        this.state = state;
+        this.error = error;
+        this.updatedAt = Date.now();
+        const type = state === 'completed'
+            ? 'completed'
+            : state === 'failed'
+                ? 'failed'
+                : state === 'canceled'
+                    ? 'canceled'
+                    : 'session_state';
+        this.events.append(type, { state, ...(error ? { error } : {}) });
+    }
+    appendOutput(text) {
+        if (!text)
+            return;
+        this.output = `${this.output}${text}`;
+        if (this.output.length > this.maxOutputChars) {
+            this.output = `…[truncated by nexus-agentd]\n${this.output.slice(-this.maxOutputChars)}`;
+        }
+        this.updatedAt = Date.now();
+    }
+    setPending(request) {
+        this.pendingRequest = structuredClone(request);
+        this.state = request.kind === 'permission' ? 'permission_required' : 'input_required';
+        this.updatedAt = Date.now();
+        this.events.append(request.kind === 'permission'
+            ? 'permission_required'
+            : 'input_required', request);
+    }
+    clearPending() {
+        this.pendingRequest = undefined;
+        this.updatedAt = Date.now();
+    }
+    emit(type, data) {
+        this.updatedAt = Date.now();
+        this.events.append(type, data);
+    }
+    async message(message) {
+        if (!this.runtime)
+            throw new Error('ACP runtime is unavailable');
+        if (this.pendingRequest) {
+            await this.runtime.respondPending(message);
+            return;
+        }
+        if (this.state === 'running') {
+            throw new Error('ACP session is already processing a prompt');
+        }
+        this.output = '';
+        this.error = undefined;
+        this.updatedAt = Date.now();
+        void this.runtime.prompt(message).catch((error) => {
+            if (this.state !== 'canceled')
+                this.setState('failed', errorMessage(error));
+        });
+    }
+    async cancel() {
+        await this.runtime?.cancel();
+    }
+    async dispose() {
+        await this.runtime?.dispose();
+    }
+    snapshot() {
+        return {
+            id: this.id,
+            acpSessionId: this.acpSessionId,
+            agentId: this.agentId,
+            workspace: this.workspace,
+            state: this.state,
+            output: this.output || undefined,
+            error: this.error,
+            artifacts: [],
+            pendingRequest: this.pendingRequest
+                ? structuredClone(this.pendingRequest)
+                : undefined,
+            lastEventId: this.events.lastId,
+            createdAt: this.createdAt,
+            updatedAt: this.updatedAt
+        };
+    }
+}
+export class SessionManager {
+    config;
+    workspacePolicy;
+    drivers;
+    sessions = new Map();
+    cleanupTimer;
+    constructor(config, workspacePolicy, drivers) {
+        this.config = config;
+        this.workspacePolicy = workspacePolicy;
+        this.drivers = drivers;
+    }
+    startCleanup() {
+        if (this.cleanupTimer)
+            return;
+        this.cleanupTimer = setInterval(() => void this.cleanup(), 60_000);
+        this.cleanupTimer.unref?.();
+    }
+    async listAgents() {
+        return Promise.all(Array.from(this.drivers.values()).map((driver) => driver.probe()));
+    }
+    async create(agentId, workspaceInput) {
+        const driver = this.drivers.get(agentId);
+        if (!driver)
+            throw new Error(`Configured ACP agent not found: ${agentId}`);
+        const workspace = await this.workspacePolicy.resolve(workspaceInput);
+        const session = new ManagedSession(agentId, workspace, this.config.maxEventsPerSession, this.config.maxOutputChars);
+        this.sessions.set(session.id, session);
+        const runtime = new AcpProcessRuntime(driver, session);
+        session.attach(runtime);
+        try {
+            await runtime.start(workspace);
+            return session.snapshot();
+        }
+        catch (error) {
+            session.setState('failed', errorMessage(error));
+            await session.dispose();
+            throw error;
+        }
+    }
+    get(id) {
+        return this.require(id).snapshot();
+    }
+    async message(id, message) {
+        const text = String(message || '');
+        if (!text.trim())
+            throw new Error('message is required');
+        const session = this.require(id);
+        await session.message(text);
+        return session.snapshot();
+    }
+    async cancel(id) {
+        const session = this.require(id);
+        await session.cancel();
+        return session.snapshot();
+    }
+    eventsAfter(id, after) {
+        return this.require(id).events.after(after);
+    }
+    subscribe(id, listener) {
+        return this.require(id).events.subscribe(listener);
+    }
+    async shutdown() {
+        if (this.cleanupTimer)
+            clearInterval(this.cleanupTimer);
+        this.cleanupTimer = undefined;
+        await Promise.allSettled(Array.from(this.sessions.values()).map((session) => session.dispose()));
+        this.sessions.clear();
+    }
+    require(id) {
+        const session = this.sessions.get(id);
+        if (!session)
+            throw new SessionNotFoundError(id);
+        return session;
+    }
+    async cleanup() {
+        const cutoff = Date.now() - this.config.sessionTtlMs;
+        for (const [id, session] of this.sessions) {
+            if (session.updatedAt > cutoff ||
+                session.state === 'running' ||
+                session.state === 'permission_required' ||
+                session.state === 'input_required') {
+                continue;
+            }
+            await session.dispose();
+            this.sessions.delete(id);
+        }
+    }
+}
+export class SessionNotFoundError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`Nexus Gateway session not found: ${sessionId}`);
+        this.sessionId = sessionId;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+export type AgentdSessionState = 'created' | 'running' | 'input_required' | 'permission_required' | 'completed' | 'failed' | 'canceled';
+export type PermissionPolicy = 'ask' | 'deny';
+export declare const agentdDriverKinds: readonly ["opencode", "claude", "codex", "pi", "openclaw"];
+export type AgentdDriverKind = (typeof agentdDriverKinds)[number];
+export interface AgentdDriverConfig {
+    driver: AgentdDriverKind;
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    command?: string;
+    args?: string[];
+    inheritEnv?: string[];
+    env?: Record<string, string>;
+    permissionPolicy?: PermissionPolicy;
+    permissionTimeoutMs?: number;
+}
+export interface AgentdConfig {
+    listen: {
+        host: string;
+        port: number;
+    };
+    authToken: string;
+    workspaceRoots: string[];
+    maxRequestBytes: number;
+    maxEventsPerSession: number;
+    maxOutputChars: number;
+    sessionTtlMs: number;
+    agents: Record<string, AgentdDriverConfig>;
+}
+export interface AgentdAgentView {
+    id: string;
+    name: string;
+    description?: string;
+    protocol: 'acp';
+    ready: boolean;
+    version?: string;
+    error?: string;
+}
+export interface AgentdPendingRequest {
+    id: string;
+    kind: 'permission' | 'input';
+    prompt: string;
+    options?: Array<{
+        id: string;
+        name: string;
+        kind?: string;
+    }>;
+}
+export interface AgentdArtifact {
+    id?: string;
+    name?: string;
+    description?: string;
+    text?: string;
+    url?: string;
+    filename?: string;
+    mediaType?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentdSessionView {
+    id: string;
+    acpSessionId?: string;
+    agentId: string;
+    workspace: string;
+    state: AgentdSessionState;
+    output?: string;
+    error?: string;
+    artifacts: AgentdArtifact[];
+    pendingRequest?: AgentdPendingRequest;
+    lastEventId?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export type AgentdEventType = 'session_state' | 'assistant_chunk' | 'thought_chunk' | 'plan' | 'tool_call' | 'tool_update' | 'terminal_output' | 'file_activity' | 'permission_required' | 'input_required' | 'completed' | 'failed' | 'canceled';
+export interface AgentdEvent {
+    id: string;
+    sessionId: string;
+    type: AgentdEventType;
+    timestamp: number;
+    data?: unknown;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+export const agentdDriverKinds = [
+    'opencode',
+    'claude',
+    'codex',
+    'pi',
+    'openclaw'
+];

package/dist/workspace.d.ts

@@ -0,0 +1,7 @@
+export declare class WorkspacePolicy {
+    private readonly roots;
+    private constructor();
+    static create(configuredRoots: string[]): Promise<WorkspacePolicy>;
+    resolve(input: string): Promise<string>;
+    listRoots(): string[];
+}

package/dist/workspace.js

@@ -0,0 +1,34 @@
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+export class WorkspacePolicy {
+    roots;
+    constructor(roots) {
+        this.roots = roots;
+    }
+    static async create(configuredRoots) {
+        const roots = await Promise.all(configuredRoots.map(async (root) => normalize(await realpath(root))));
+        return new WorkspacePolicy(Array.from(new Set(roots)));
+    }
+    async resolve(input) {
+        if (!input?.trim())
+            throw new Error('workspace is required');
+        const candidate = normalize(await realpath(input));
+        const allowed = this.roots.some((root) => isWithin(root, candidate));
+        if (!allowed)
+            throw new Error(`workspace is outside the configured allowlist: ${input}`);
+        return candidate;
+    }
+    listRoots() {
+        return [...this.roots];
+    }
+}
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === '' ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== '..' &&
+            !path.isAbsolute(relative)));
+}
+function normalize(value) {
+    return path.resolve(value);
+}

package/nexus-agentd.example.json

@@ -0,0 +1,43 @@
+{
+  "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"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "nexus-agentd",
+  "version": "0.1.0",
+  "description": "Local Nexus Gateway daemon that exposes allowlisted Coding Agents through HTTP/SSE and ACP",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nexus-agentd": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "nexus-agentd.example.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "lumia1998",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lumia1998/koishi-plugin-agent-nexus.git",
+    "directory": "packages/nexus-agentd"
+  },
+  "bugs": {
+    "url": "https://github.com/lumia1998/koishi-plugin-agent-nexus/issues"
+  },
+  "homepage": "https://github.com/lumia1998/koishi-plugin-agent-nexus/tree/main/packages/nexus-agentd#readme",
+  "keywords": [
+    "agent-client-protocol",
+    "acp",
+    "agent",
+    "gateway",
+    "coding-agent"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.3.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT"
+}