@bbigbang/runtime-acp 0.1.0

package/dist/acp/jsonrpc.d.ts

@@ -0,0 +1,31 @@
+export type JsonRpcVersion = '2.0';
+export type JsonRpcId = number | string;
+export type JsonRpcError = {
+    code: number;
+    message: string;
+    data?: unknown;
+};
+export type JsonRpcRequest = {
+    jsonrpc: JsonRpcVersion;
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+};
+export type JsonRpcNotification = {
+    jsonrpc: JsonRpcVersion;
+    method: string;
+    params?: unknown;
+};
+export type JsonRpcResponse = {
+    jsonrpc: JsonRpcVersion;
+    id: JsonRpcId;
+    result: unknown;
+} | {
+    jsonrpc: JsonRpcVersion;
+    id: JsonRpcId;
+    error: JsonRpcError;
+};
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+export declare function isRequest(message: any): message is JsonRpcRequest;
+export declare function isNotification(message: any): message is JsonRpcNotification;
+export declare function isResponse(message: any): message is JsonRpcResponse;

package/dist/acp/jsonrpc.js

@@ -0,0 +1,18 @@
+export function isRequest(message) {
+    return (message &&
+        message.jsonrpc === '2.0' &&
+        typeof message.method === 'string' &&
+        'id' in message);
+}
+export function isNotification(message) {
+    return (message &&
+        message.jsonrpc === '2.0' &&
+        typeof message.method === 'string' &&
+        !('id' in message));
+}
+export function isResponse(message) {
+    return (message &&
+        message.jsonrpc === '2.0' &&
+        'id' in message &&
+        ('result' in message || 'error' in message));
+}

package/dist/acp/stdio.d.ts

@@ -0,0 +1,15 @@
+import type { JsonRpcMessage } from './jsonrpc.js';
+type StdioExitInfo = {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    error?: string;
+};
+export type StdioProcess = {
+    write: (message: JsonRpcMessage) => void;
+    onMessage: (cb: (message: JsonRpcMessage) => void) => void;
+    onStderr: (cb: (line: string) => void) => void;
+    onExit?: (cb: (info: StdioExitInfo) => void) => void;
+    kill: () => void;
+};
+export declare function spawnAcpAgent(command: string, args: string[], env?: NodeJS.ProcessEnv, cwd?: string): StdioProcess;
+export {};

package/dist/acp/stdio.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { log } from '../logging.js';
+const ACP_AGENT_COMMAND_FALLBACKS = {
+    'claude-code-acp': {
+        command: 'npx',
+        args: ['-y', '@zed-industries/claude-code-acp@latest'],
+    },
+    'codex-acp': {
+        command: 'npx',
+        args: ['-y', '@zed-industries/codex-acp@latest'],
+    },
+};
+const CODEX_RUNTIME_ENV_DENYLIST = [
+    'CODEX_SANDBOX_NETWORK_DISABLED',
+    'CODEX_THREAD_ID',
+];
+export function spawnAcpAgent(command, args, env, cwd) {
+    const childEnv = {
+        ...process.env,
+        // Unset vars that would prevent Claude Code from starting inside an existing Claude session
+        CLAUDECODE: undefined,
+        CLAUDE_CODE_ENTRYPOINT: undefined,
+        ...env,
+    };
+    if (isCodexAcpAgent(command, args)) {
+        for (const key of CODEX_RUNTIME_ENV_DENYLIST) {
+            delete childEnv[key];
+        }
+    }
+    const spawnPlan = resolveSpawnPlan(command, args, childEnv);
+    if (spawnPlan.fallbackFrom) {
+        log.warn('ACP agent command not found on PATH; falling back to npx package execution', {
+            requestedCommand: spawnPlan.fallbackFrom,
+            fallbackCommand: spawnPlan.command,
+            cwd,
+        });
+    }
+    const child = spawn(spawnPlan.command, spawnPlan.args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        ...(cwd ? { cwd } : {}),
+        env: childEnv,
+    });
+    const stdoutRl = child.stdout ? readline.createInterface({
+        input: child.stdout,
+        crlfDelay: Infinity,
+    }) : null;
+    const stderrRl = child.stderr ? readline.createInterface({
+        input: child.stderr,
+        crlfDelay: Infinity,
+    }) : null;
+    const messageHandlers = [];
+    const stderrHandlers = [];
+    const exitHandlers = [];
+    let exitInfo = null;
+    let stdinError = null;
+    stdoutRl?.on('line', (line) => {
+        if (!line.trim())
+            return;
+        try {
+            const msg = JSON.parse(line);
+            messageHandlers.forEach((h) => h(msg));
+        }
+        catch (error) {
+            log.error('ACP stdout non-JSON line (fatal):', line);
+            log.error(error);
+            child.kill('SIGKILL');
+        }
+    });
+    stderrRl?.on('line', (line) => {
+        stderrHandlers.forEach((h) => h(line));
+    });
+    const handleExit = (code, signal, error) => {
+        if (!exitInfo) {
+            exitInfo = { code, signal, ...(error ? { error } : {}) };
+        }
+        log.warn('ACP agent exited', exitInfo);
+        exitHandlers.forEach((h) => h(exitInfo));
+    };
+    child.on('error', (error) => {
+        log.error('ACP agent process error', error);
+        handleExit(null, null, error instanceof Error ? error.message : String(error));
+    });
+    child.stdin && 'on' in child.stdin && child.stdin.on('error', (error) => {
+        stdinError = error instanceof Error ? error : new Error(String(error));
+        log.warn('ACP agent stdin error', stdinError);
+        handleExit(null, null, stdinError.message);
+    });
+    child.stdout && 'on' in child.stdout && child.stdout.on('error', (error) => {
+        log.warn('ACP agent stdout error', error);
+        handleExit(null, null, error instanceof Error ? error.message : String(error));
+    });
+    child.stderr && 'on' in child.stderr && child.stderr.on('error', (error) => {
+        log.warn('ACP agent stderr error', error);
+        handleExit(null, null, error instanceof Error ? error.message : String(error));
+    });
+    child.on('exit', (code, signal) => {
+        handleExit(code, signal);
+    });
+    function write(message) {
+        if (exitInfo) {
+            const errorSuffix = exitInfo.error ? `, error=${exitInfo.error}` : '';
+            throw new Error(`ACP process is not running (code=${String(exitInfo.code)}, signal=${String(exitInfo.signal)}${errorSuffix})`);
+        }
+        if (stdinError) {
+            throw new Error(`ACP process stdin is not writable: ${stdinError.message}`);
+        }
+        if (!child.stdin || child.stdin.destroyed || !child.stdin.writable) {
+            throw new Error('ACP process stdin is not writable.');
+        }
+        const payload = JSON.stringify(message);
+        if (payload.includes('\n')) {
+            // JSON itself must be newline-delimited; embedded newlines here are a bug.
+            throw new Error('ACP message serialization produced newline');
+        }
+        child.stdin.write(payload + '\n', (error) => {
+            if (!error)
+                return;
+            stdinError = error instanceof Error ? error : new Error(String(error));
+            log.warn('ACP agent stdin write failed', stdinError);
+            handleExit(null, null, stdinError.message);
+        });
+    }
+    return {
+        write,
+        onMessage: (cb) => {
+            messageHandlers.push(cb);
+        },
+        onStderr: (cb) => {
+            stderrHandlers.push(cb);
+        },
+        onExit: (cb) => {
+            exitHandlers.push(cb);
+            if (exitInfo)
+                cb(exitInfo);
+        },
+        kill: () => {
+            child.kill('SIGTERM');
+        },
+    };
+}
+function isCodexAcpAgent(command, args) {
+    const basename = path.basename(command);
+    if (basename === 'codex-acp')
+        return true;
+    if (basename === 'codex' && args[0] === 'acp')
+        return true;
+    return args.some((arg) => arg.includes('codex-acp'));
+}
+function resolveSpawnPlan(command, args, env) {
+    if (hasPathSeparator(command) || isCommandOnPath(command, env)) {
+        return { command, args };
+    }
+    const fallback = ACP_AGENT_COMMAND_FALLBACKS[command];
+    if (!fallback)
+        return { command, args };
+    return {
+        command: fallback.command,
+        args: [...fallback.args, ...args],
+        fallbackFrom: command,
+    };
+}
+function isCommandOnPath(command, env) {
+    const rawPath = env.PATH ?? process.env.PATH ?? '';
+    if (!rawPath)
+        return false;
+    const candidates = rawPath
+        .split(path.delimiter)
+        .map((entry) => entry || '.')
+        .filter(Boolean);
+    const extensions = process.platform === 'win32'
+        ? (env.PATHEXT ?? process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM')
+            .split(';')
+            .filter(Boolean)
+        : [''];
+    for (const dir of candidates) {
+        for (const extension of extensions) {
+            const fileName = process.platform === 'win32' && hasKnownExtension(command)
+                ? command
+                : `${command}${extension}`;
+            const candidate = path.join(dir, fileName);
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                return true;
+            }
+            catch {
+                // keep probing PATH entries
+            }
+        }
+    }
+    return false;
+}
+function hasPathSeparator(command) {
+    return command.includes('/') || command.includes('\\');
+}
+function hasKnownExtension(command) {
+    const ext = path.extname(command);
+    return ext.length > 0;
+}

package/dist/acp/types.d.ts

@@ -0,0 +1,171 @@
+export type InitializeParams = {
+    protocolVersion: number;
+    clientCapabilities: {
+        fs?: {
+            readTextFile?: boolean;
+            writeTextFile?: boolean;
+        };
+        terminal?: boolean;
+    };
+    clientInfo?: {
+        name: string;
+        title?: string;
+        version?: string;
+    };
+};
+export type InitializeResult = {
+    protocolVersion: number;
+    agentCapabilities: {
+        loadSession?: boolean;
+        promptCapabilities?: {
+            image?: boolean;
+            audio?: boolean;
+            embeddedContext?: boolean;
+        };
+        mcpCapabilities?: {
+            http?: boolean;
+            sse?: boolean;
+        };
+    };
+    agentInfo?: {
+        name: string;
+        title?: string;
+        version?: string;
+    };
+    authMethods?: Array<{
+        id: string;
+        name: string;
+        description?: string;
+    }>;
+};
+export type McpServerEntry = {
+    name: string;
+    command: string;
+    args: string[];
+    env?: Array<{
+        name: string;
+        value: string;
+    }>;
+} | {
+    name: string;
+    type: string;
+    url: string;
+    headers?: Array<{
+        name: string;
+        value: string;
+    }>;
+};
+export type NewSessionParams = {
+    cwd: string;
+    mcpServers: McpServerEntry[];
+    _meta?: {
+        systemPrompt?: string | {
+            append: string;
+        };
+    };
+};
+export type NewSessionResult = {
+    sessionId: string;
+    availableModes?: Array<{
+        id: string;
+        name: string;
+        description?: string;
+    }>;
+    configOptions?: unknown[];
+};
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'resource_link';
+    uri: string;
+    name: string;
+    mimeType?: string;
+};
+export type PromptParams = {
+    sessionId: string;
+    prompt: ContentBlock[];
+};
+export type PromptResult = {
+    stopReason: string;
+};
+export type SessionUpdateNotification = {
+    sessionId: string;
+    update: any;
+};
+export type PermissionOption = {
+    optionId: string;
+    name: string;
+    kind: string;
+};
+export type RequestPermissionParams = {
+    sessionId: string;
+    toolCall: any;
+    options: PermissionOption[];
+};
+export type RequestPermissionOutcome = {
+    outcome: 'cancelled';
+} | {
+    outcome: 'selected';
+    optionId: string;
+};
+export type RequestPermissionResult = {
+    outcome: RequestPermissionOutcome;
+};
+export type FsReadTextFileParams = {
+    sessionId: string;
+    path: string;
+    line?: number;
+    limit?: number;
+};
+export type FsReadTextFileResult = {
+    content: string;
+};
+export type FsWriteTextFileParams = {
+    sessionId: string;
+    path: string;
+    content: string;
+};
+export type TerminalCreateParams = {
+    sessionId: string;
+    command: string;
+    args?: string[];
+    cwd?: string | null;
+    env?: Array<{
+        name: string;
+        value: string;
+    }>;
+    outputByteLimit?: number | null;
+};
+export type TerminalCreateResult = {
+    terminalId: string;
+};
+export type TerminalOutputParams = {
+    sessionId: string;
+    terminalId: string;
+};
+export type TerminalExitStatus = {
+    exitCode?: number | null;
+    signal?: string | null;
+};
+export type TerminalOutputResult = {
+    output: string;
+    truncated: boolean;
+    exitStatus?: TerminalExitStatus | null;
+};
+export type TerminalWaitForExitParams = {
+    sessionId: string;
+    terminalId: string;
+};
+export type TerminalWaitForExitResult = {
+    exitCode?: number | null;
+    signal?: string | null;
+};
+export type TerminalKillParams = {
+    sessionId: string;
+    terminalId: string;
+};
+export type TerminalReleaseParams = {
+    sessionId: string;
+    terminalId: string;
+};

package/dist/acp/types.js

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

package/dist/db/db.d.ts

@@ -0,0 +1,3 @@
+import Database from 'better-sqlite3';
+export type Db = Database.Database;
+export declare function openDb(dbPath: string): Db;

package/dist/db/db.js

@@ -0,0 +1,10 @@
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import path from 'node:path';
+export function openDb(dbPath) {
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    return db;
+}

package/dist/db/deliveryCheckpointStore.d.ts

@@ -0,0 +1,21 @@
+import type { Db } from './db.js';
+export type DeliveryCheckpointRow = {
+    bindingKey: string;
+    runId: string;
+    lastSeq: number;
+    messageId: string | null;
+    text: string;
+    createdAt: number;
+    updatedAt: number;
+};
+export declare function getDeliveryCheckpoint(db: Db, params: {
+    bindingKey: string;
+    runId: string;
+}): DeliveryCheckpointRow | null;
+export declare function upsertDeliveryCheckpoint(db: Db, params: {
+    bindingKey: string;
+    runId: string;
+    lastSeq: number;
+    messageId: string | null;
+    text: string;
+}): void;

package/dist/db/deliveryCheckpointStore.js

@@ -0,0 +1,28 @@
+export function getDeliveryCheckpoint(db, params) {
+    const row = db
+        .prepare(`
+      SELECT binding_key as bindingKey,
+             run_id as runId,
+             last_seq as lastSeq,
+             message_id as messageId,
+             text,
+             created_at as createdAt,
+             updated_at as updatedAt
+        FROM delivery_checkpoints
+       WHERE binding_key = ? AND run_id = ?
+      `)
+        .get(params.bindingKey, params.runId);
+    return row ?? null;
+}
+export function upsertDeliveryCheckpoint(db, params) {
+    const now = Date.now();
+    db.prepare(`
+    INSERT INTO delivery_checkpoints(binding_key, run_id, last_seq, message_id, text, created_at, updated_at)
+    VALUES(?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(binding_key, run_id) DO UPDATE SET
+      last_seq = excluded.last_seq,
+      message_id = excluded.message_id,
+      text = excluded.text,
+      updated_at = excluded.updated_at
+    `).run(params.bindingKey, params.runId, params.lastSeq, params.messageId, params.text, now, now);
+}

package/dist/db/migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Db } from './db.js';
+export declare function migrate(db: Db): void;