@bbigbang/runtime-acp 0.1.0

package/dist/gateway/toolAuth.js

@@ -0,0 +1,372 @@
+import path from 'node:path';
+import { resolveWorkspacePath } from '../tools/workspace.js';
+export const TOOL_KINDS = [
+    'read',
+    'edit',
+    'delete',
+    'move',
+    'search',
+    'execute',
+    'think',
+    'fetch',
+    'switch_mode',
+    'other',
+];
+export function parseToolKind(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return TOOL_KINDS.includes(normalized)
+        ? normalized
+        : null;
+}
+const PATH_PREFIX_TOOL_KINDS = new Set([
+    'read',
+    'edit',
+    'delete',
+    'move',
+]);
+export class ToolAuth {
+    db;
+    onceGrants = new Map();
+    constructor(db) {
+        this.db = db;
+    }
+    grantOnce(sessionKey, toolKind, count = 1) {
+        const perSession = this.onceGrants.get(sessionKey) ?? new Map();
+        perSession.set(toolKind, (perSession.get(toolKind) ?? 0) + count);
+        this.onceGrants.set(sessionKey, perSession);
+    }
+    setPersistentPolicy(bindingKey, toolKind, policy) {
+        const now = Date.now();
+        this.db
+            .prepare(`
+        INSERT INTO tool_policies(binding_key, tool_kind, policy, created_at, updated_at)
+        VALUES(?, ?, ?, ?, ?)
+        ON CONFLICT(binding_key, tool_kind) DO UPDATE SET
+          policy = excluded.policy,
+          updated_at = excluded.updated_at
+        `)
+            .run(bindingKey, toolKind, policy, now, now);
+    }
+    getPersistentPolicy(bindingKey, toolKind) {
+        const row = this.db
+            .prepare('SELECT policy FROM tool_policies WHERE binding_key = ? AND tool_kind = ? LIMIT 1')
+            .get(bindingKey, toolKind);
+        return row?.policy ?? null;
+    }
+    listPersistentPolicies(bindingKey, policy) {
+        const rows = policy
+            ? this.db
+                .prepare(`
+            SELECT tool_kind as toolKind, policy
+            FROM tool_policies
+            WHERE binding_key = ? AND policy = ?
+            ORDER BY tool_kind ASC
+            `)
+                .all(bindingKey, policy)
+            : this.db
+                .prepare(`
+            SELECT tool_kind as toolKind, policy
+            FROM tool_policies
+            WHERE binding_key = ?
+            ORDER BY tool_kind ASC
+            `)
+                .all(bindingKey);
+        return rows
+            .map((row) => {
+            const toolKind = parseToolKind(row.toolKind);
+            if (!toolKind)
+                return null;
+            return { toolKind, policy: row.policy };
+        })
+            .filter(Boolean);
+    }
+    clearPersistentPolicy(bindingKey, toolKind, policy) {
+        const result = policy
+            ? this.db
+                .prepare(`
+            DELETE FROM tool_policies
+            WHERE binding_key = ? AND tool_kind = ? AND policy = ?
+            `)
+                .run(bindingKey, toolKind, policy)
+            : this.db
+                .prepare(`
+            DELETE FROM tool_policies
+            WHERE binding_key = ? AND tool_kind = ?
+            `)
+                .run(bindingKey, toolKind);
+        return result.changes > 0;
+    }
+    clearPersistentPolicies(bindingKey, policy) {
+        const result = policy
+            ? this.db
+                .prepare(`
+            DELETE FROM tool_policies
+            WHERE binding_key = ? AND policy = ?
+            `)
+                .run(bindingKey, policy)
+            : this.db
+                .prepare(`
+            DELETE FROM tool_policies
+            WHERE binding_key = ?
+            `)
+                .run(bindingKey);
+        return result.changes;
+    }
+    setAllowPrefixRule(bindingKey, toolKind, argPrefix) {
+        const normalizedPrefix = normalizeStoredPrefix(toolKind, argPrefix);
+        if (!normalizedPrefix) {
+            throw new Error('Invalid allow prefix.');
+        }
+        const now = Date.now();
+        this.db
+            .prepare(`
+        INSERT INTO tool_allow_prefixes(binding_key, tool_kind, arg_prefix, created_at, updated_at)
+        VALUES(?, ?, ?, ?, ?)
+        ON CONFLICT(binding_key, tool_kind, arg_prefix) DO UPDATE SET
+          updated_at = excluded.updated_at
+        `)
+            .run(bindingKey, toolKind, normalizedPrefix, now, now);
+    }
+    listAllowPrefixRules(bindingKey, toolKind) {
+        const rows = toolKind
+            ? this.db
+                .prepare(`
+            SELECT tool_kind as toolKind, arg_prefix as argPrefix
+            FROM tool_allow_prefixes
+            WHERE binding_key = ? AND tool_kind = ?
+            ORDER BY tool_kind ASC, arg_prefix ASC
+            `)
+                .all(bindingKey, toolKind)
+            : this.db
+                .prepare(`
+            SELECT tool_kind as toolKind, arg_prefix as argPrefix
+            FROM tool_allow_prefixes
+            WHERE binding_key = ?
+            ORDER BY tool_kind ASC, arg_prefix ASC
+            `)
+                .all(bindingKey);
+        return rows
+            .map((row) => {
+            const parsedKind = parseToolKind(row.toolKind);
+            if (!parsedKind)
+                return null;
+            const normalizedPrefix = normalizeStoredPrefix(parsedKind, row.argPrefix);
+            if (!normalizedPrefix)
+                return null;
+            return {
+                toolKind: parsedKind,
+                argPrefix: normalizedPrefix,
+            };
+        })
+            .filter(Boolean);
+    }
+    clearAllowPrefixRule(bindingKey, toolKind, argPrefix) {
+        const normalizedPrefix = normalizeStoredPrefix(toolKind, argPrefix);
+        if (!normalizedPrefix)
+            return false;
+        const result = this.db
+            .prepare(`
+        DELETE FROM tool_allow_prefixes
+        WHERE binding_key = ? AND tool_kind = ? AND arg_prefix = ?
+        `)
+            .run(bindingKey, toolKind, normalizedPrefix);
+        return result.changes > 0;
+    }
+    clearAllowPrefixRules(bindingKey, toolKind) {
+        const result = toolKind
+            ? this.db
+                .prepare(`
+            DELETE FROM tool_allow_prefixes
+            WHERE binding_key = ? AND tool_kind = ?
+            `)
+                .run(bindingKey, toolKind)
+            : this.db
+                .prepare(`
+            DELETE FROM tool_allow_prefixes
+            WHERE binding_key = ?
+            `)
+                .run(bindingKey);
+        return result.changes;
+    }
+    evaluatePersistentPolicy(bindingKey, toolKind, context) {
+        const policy = this.getPersistentPolicy(bindingKey, toolKind);
+        if (policy === 'reject')
+            return 'reject';
+        if (policy === 'allow')
+            return 'allow';
+        return this.matchesAllowPrefixRule(bindingKey, toolKind, context)
+            ? 'allow'
+            : null;
+    }
+    consume(sessionKey, toolKind, context) {
+        const bindingRow = this.db
+            .prepare('SELECT binding_key as bindingKey FROM bindings WHERE session_key = ? LIMIT 1')
+            .get(sessionKey);
+        if (!bindingRow)
+            return false;
+        const persistent = this.evaluatePersistentPolicy(bindingRow.bindingKey, toolKind, context);
+        if (persistent === 'reject')
+            return false;
+        if (persistent === 'allow')
+            return true;
+        const perSession = this.onceGrants.get(sessionKey);
+        const remaining = perSession?.get(toolKind) ?? 0;
+        if (remaining <= 0)
+            return false;
+        perSession.set(toolKind, remaining - 1);
+        return true;
+    }
+    matchesAllowPrefixRule(bindingKey, toolKind, context) {
+        if (!context)
+            return false;
+        const rules = this.listAllowPrefixRules(bindingKey, toolKind);
+        if (rules.length === 0)
+            return false;
+        const candidates = extractMatchCandidates(toolKind, context);
+        if (candidates.length === 0)
+            return false;
+        for (const rule of rules) {
+            if (candidates.some((candidate) => prefixMatches(toolKind, candidate, rule.argPrefix))) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+function extractMatchCandidates(toolKind, context) {
+    const out = [];
+    const seen = new Set();
+    const push = (raw) => {
+        if (typeof raw !== 'string')
+            return;
+        const normalized = normalizeCandidate(toolKind, raw, context.workspaceRoot);
+        if (!normalized || seen.has(normalized))
+            return;
+        seen.add(normalized);
+        out.push(normalized);
+    };
+    const params = asRecord(context.params);
+    const method = String(context.method ?? '').trim();
+    if (method === 'fs/read_text_file' || method === 'fs/write_text_file') {
+        push(params?.path);
+    }
+    if (method === 'terminal/create') {
+        push(formatCommandLine(params?.command, params?.args));
+    }
+    const toolCall = asRecord(context.toolCall);
+    if (toolCall) {
+        push(toolCall.path);
+        push(getPathValue(toolCall, 'arguments.path'));
+        push(getPathValue(toolCall, 'input.path'));
+        push(formatCommandLine(toolCall.command, toolCall.args));
+        push(formatCommandLine(getPathValue(toolCall, 'arguments.command'), getPathValue(toolCall, 'arguments.args')));
+        push(extractTargetFromToolTitle(toolKind, toolCall.title));
+    }
+    if (PATH_PREFIX_TOOL_KINDS.has(toolKind)) {
+        push(params?.file);
+        push(params?.target);
+        push(params?.uri);
+    }
+    else if (toolKind === 'execute') {
+        push(params?.command);
+    }
+    else {
+        push(params?.path);
+        push(params?.query);
+        push(params?.pattern);
+        push(params?.text);
+    }
+    return out;
+}
+function normalizeCandidate(toolKind, raw, workspaceRoot) {
+    if (PATH_PREFIX_TOOL_KINDS.has(toolKind)) {
+        return normalizePathPrefix(raw, workspaceRoot);
+    }
+    return normalizeTextPrefix(raw);
+}
+function normalizeStoredPrefix(toolKind, raw) {
+    if (PATH_PREFIX_TOOL_KINDS.has(toolKind)) {
+        return normalizePathPrefix(raw);
+    }
+    return normalizeTextPrefix(raw);
+}
+function normalizePathPrefix(raw, workspaceRoot) {
+    const trimmed = raw.trim();
+    if (!trimmed || !path.isAbsolute(trimmed))
+        return null;
+    if (workspaceRoot) {
+        try {
+            return resolveWorkspacePath(workspaceRoot, trimmed);
+        }
+        catch {
+            return null;
+        }
+    }
+    return path.resolve(trimmed);
+}
+function normalizeTextPrefix(raw) {
+    const normalized = raw.replace(/\s+/g, ' ').trim();
+    return normalized || null;
+}
+function prefixMatches(toolKind, candidate, prefix) {
+    if (PATH_PREFIX_TOOL_KINDS.has(toolKind)) {
+        return pathPrefixMatches(candidate, prefix);
+    }
+    return candidate.startsWith(prefix);
+}
+function pathPrefixMatches(candidate, prefix) {
+    const normalizedCandidate = path.resolve(candidate);
+    const normalizedPrefix = path.resolve(prefix);
+    if (normalizedCandidate === normalizedPrefix)
+        return true;
+    return normalizedCandidate.startsWith(normalizedPrefix + path.sep);
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function getPathValue(source, pathExpr) {
+    const parts = pathExpr.split('.');
+    let current = source;
+    for (const part of parts) {
+        const obj = asRecord(current);
+        if (!obj)
+            return undefined;
+        current = obj[part];
+    }
+    return current;
+}
+function formatCommandLine(commandRaw, argsRaw) {
+    if (typeof commandRaw !== 'string' || !commandRaw.trim())
+        return null;
+    const command = commandRaw.trim();
+    const args = Array.isArray(argsRaw)
+        ? argsRaw.filter((item) => typeof item === 'string')
+        : [];
+    const full = args.length > 0 ? `${command} ${args.join(' ')}` : command;
+    return normalizeTextPrefix(full);
+}
+function extractTargetFromToolTitle(toolKind, titleRaw) {
+    if (typeof titleRaw !== 'string')
+        return null;
+    const title = titleRaw.trim();
+    if (!title)
+        return null;
+    if (PATH_PREFIX_TOOL_KINDS.has(toolKind)) {
+        const match = title.match(/^(?:read|edit|delete|move)\s*:\s*(.+)$/i);
+        if (match) {
+            return match[1]?.trim() ?? null;
+        }
+        return null;
+    }
+    if (toolKind === 'execute') {
+        const match = title.match(/^run\s*:\s*(.+)$/i);
+        if (match) {
+            return match[1]?.trim() ?? null;
+        }
+    }
+    return null;
+}

package/dist/gateway/types.d.ts

@@ -0,0 +1,79 @@
+export type DeliveryState = {
+    text: string;
+    messageId: string | null;
+};
+export type UiMode = 'verbose' | 'summary';
+export type ToolUiStage = 'start' | 'update' | 'complete';
+export type PermissionUiRequest = {
+    uiMode: UiMode;
+    sessionKey: string;
+    requestId: string;
+    toolTitle: string;
+    toolKind: string | null;
+    toolName?: string;
+    toolArgs?: unknown;
+    approvalKind?: 'tool' | 'plan' | 'question';
+    title?: string;
+    description?: string;
+    input?: unknown;
+    actions?: Array<{
+        id: string;
+        label: string;
+        variant?: 'primary' | 'secondary' | 'danger';
+        requiresInput?: boolean;
+        inputPlaceholder?: string;
+    }>;
+};
+export type UiEvent = {
+    kind: 'plan' | 'task';
+    mode: UiMode;
+    title: string;
+    detail?: string;
+    silent?: boolean;
+} | {
+    kind: 'plan_phase';
+    mode: UiMode;
+    phase: 'planning' | 'implementation';
+} | {
+    kind: 'usage';
+    mode: UiMode;
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    reasoningOutputTokens?: number;
+    totalTokens?: number;
+    currentInputTokens?: number;
+    currentCachedInputTokens?: number;
+    modelContextWindow?: number;
+    metadata?: Record<string, unknown>;
+} | {
+    kind: 'compact';
+    mode: UiMode;
+    threadId: string;
+    turnId: string;
+    itemId?: string;
+    source: 'thread_compacted' | 'raw_response_item' | 'thread_item';
+    eventKey: string;
+} | {
+    kind: 'tool';
+    mode: UiMode;
+    title: string;
+    detail?: string;
+    input?: unknown;
+    output?: string;
+    toolCallId?: string;
+    stage?: ToolUiStage;
+    status?: string;
+    metadata?: Record<string, unknown>;
+};
+export type OutboundSink = {
+    sendAgentText?: (text: string) => Promise<void>;
+    sendActivityText?: (text: string) => Promise<void>;
+    sendThinkingText?: (text: string) => Promise<void>;
+    sendText: (text: string) => Promise<void>;
+    breakTextStream?: () => Promise<void>;
+    flush?: () => Promise<void>;
+    getDeliveryState?: () => DeliveryState;
+    requestPermission?: (req: PermissionUiRequest) => Promise<void>;
+    sendUi?: (event: UiEvent) => Promise<void>;
+};

package/dist/gateway/types.js

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

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export { AcpClient } from './acp/client.js';
+export type { PermissionRequest, PermissionDecision, AcpClientEvents, ClientToolEvent } from './acp/client.js';
+export { spawnAcpAgent } from './acp/stdio.js';
+export type { StdioProcess } from './acp/stdio.js';
+export { isRequest, isResponse, isNotification, } from './acp/jsonrpc.js';
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, JsonRpcMessage, } from './acp/jsonrpc.js';
+export type { InitializeParams, InitializeResult, NewSessionParams, NewSessionResult, PromptParams, PromptResult, ContentBlock, RequestPermissionParams, McpServerEntry, } from './acp/types.js';
+export { BindingRuntime } from './gateway/bindingRuntime.js';
+export type { RuntimeConfig } from './gateway/bindingRuntime.js';
+export { createSession, createRun, finishRun, getSession, getBinding, upsertBinding, updateAcpSessionId, updateSessionRuntimeState, clearAcpSessionId, updateLoadSupported, updateClaudeSessionControls, insertClaudeSessionUserMessage, getLatestClaudeSessionUserMessage, bindingKeyFromConversationKey, SHARED_CHAT_SCOPE_USER_ID, } from './gateway/sessionStore.js';
+export type { Platform, ConversationKey, SessionBinding, StoredClaudeSessionModeId } from './gateway/sessionStore.js';
+export { ToolAuth, parseToolKind, TOOL_KINDS } from './gateway/toolAuth.js';
+export type { ToolKind } from './gateway/toolAuth.js';
+export { buildReplayContextFromRecentRuns } from './gateway/history.js';
+export type { OutboundSink, PermissionUiRequest, UiEvent, UiMode, ToolUiStage, DeliveryState, } from './gateway/types.js';
+export { openDb } from './db/db.js';
+export type { Db } from './db/db.js';
+export { migrate } from './db/migrations.js';
+export { getUiMode, setUiMode } from './db/uiPrefStore.js';
+export { upsertDeliveryCheckpoint, getDeliveryCheckpoint, } from './db/deliveryCheckpointStore.js';
+export { acquireProcessLock } from './runtime/lock.js';
+export type { ProcessLock } from './runtime/lock.js';
+export { WorkspaceLockManager } from './runtime/workspaceLockManager.js';
+export type { WorkspaceLockLease } from './runtime/workspaceLockManager.js';
+export { resolveWorkspacePath } from './tools/workspace.js';
+export { log } from './logging.js';

package/dist/index.js

@@ -0,0 +1,19 @@
+// ACP protocol layer
+export { AcpClient } from './acp/client.js';
+export { spawnAcpAgent } from './acp/stdio.js';
+export { isRequest, isResponse, isNotification, } from './acp/jsonrpc.js';
+// Gateway / runtime layer
+export { BindingRuntime } from './gateway/bindingRuntime.js';
+export { createSession, createRun, finishRun, getSession, getBinding, upsertBinding, updateAcpSessionId, updateSessionRuntimeState, clearAcpSessionId, updateLoadSupported, updateClaudeSessionControls, insertClaudeSessionUserMessage, getLatestClaudeSessionUserMessage, bindingKeyFromConversationKey, SHARED_CHAT_SCOPE_USER_ID, } from './gateway/sessionStore.js';
+export { ToolAuth, parseToolKind, TOOL_KINDS } from './gateway/toolAuth.js';
+export { buildReplayContextFromRecentRuns } from './gateway/history.js';
+// Database layer
+export { openDb } from './db/db.js';
+export { migrate } from './db/migrations.js';
+export { getUiMode, setUiMode } from './db/uiPrefStore.js';
+export { upsertDeliveryCheckpoint, getDeliveryCheckpoint, } from './db/deliveryCheckpointStore.js';
+// Utilities
+export { acquireProcessLock } from './runtime/lock.js';
+export { WorkspaceLockManager } from './runtime/workspaceLockManager.js';
+export { resolveWorkspacePath } from './tools/workspace.js';
+export { log } from './logging.js';

package/dist/logging.d.ts

@@ -0,0 +1,7 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare const log: {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};

package/dist/logging.js

@@ -0,0 +1,28 @@
+const levelOrder = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+const currentLevel = process.env.LOG_LEVEL ?? 'info';
+function shouldLog(level) {
+    return levelOrder[level] >= levelOrder[currentLevel];
+}
+export const log = {
+    debug: (...args) => {
+        if (shouldLog('debug'))
+            console.log('[debug]', ...args);
+    },
+    info: (...args) => {
+        if (shouldLog('info'))
+            console.log('[info]', ...args);
+    },
+    warn: (...args) => {
+        if (shouldLog('warn'))
+            console.warn('[warn]', ...args);
+    },
+    error: (...args) => {
+        if (shouldLog('error'))
+            console.error('[error]', ...args);
+    },
+};

package/dist/runtime/lock.d.ts

@@ -0,0 +1,5 @@
+export type ProcessLock = {
+    path: string;
+    release: () => void;
+};
+export declare function acquireProcessLock(lockPath: string): ProcessLock;

package/dist/runtime/lock.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function acquireProcessLock(lockPath) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    try {
+        const fd = fs.openSync(lockPath, 'wx');
+        try {
+            fs.writeFileSync(fd, JSON.stringify({
+                pid: process.pid,
+                startedAt: Date.now(),
+            }, null, 2) + '\n', 'utf8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return {
+            path: lockPath,
+            release: () => {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // ignore
+                }
+            },
+        };
+    }
+    catch (err) {
+        if (err?.code !== 'EEXIST')
+            throw err;
+        // If lock exists, verify the process is alive.
+        const existing = readLockFile(lockPath);
+        if (existing?.pid && isPidAlive(existing.pid)) {
+            throw new Error(`Another instance is running (pid=${existing.pid})`, {
+                cause: err,
+            });
+        }
+        // Stale lock.
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch {
+            // ignore
+        }
+        // Retry once.
+        const fd = fs.openSync(lockPath, 'wx');
+        try {
+            fs.writeFileSync(fd, JSON.stringify({
+                pid: process.pid,
+                startedAt: Date.now(),
+            }, null, 2) + '\n', 'utf8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return {
+            path: lockPath,
+            release: () => {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // ignore
+                }
+            },
+        };
+    }
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLockFile(lockPath) {
+    try {
+        const raw = fs.readFileSync(lockPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/runtime/workspaceLockManager.d.ts

@@ -0,0 +1,23 @@
+export type WorkspaceLockLease = {
+    key: string;
+    waited: boolean;
+    release: () => void;
+};
+type WorkspaceLockHooks = {
+    onWaitStart?: () => void;
+    onAcquired?: (params: {
+        waited: boolean;
+    }) => void;
+    signal?: AbortSignal;
+};
+export declare class WorkspaceLockManager {
+    private readonly locks;
+    normalizeKey(workspaceRoot: string): string;
+    acquire(workspaceRoot: string, hooks?: WorkspaceLockHooks): Promise<WorkspaceLockLease>;
+    runExclusive<T>(workspaceRoot: string, action: () => Promise<T> | T, hooks?: WorkspaceLockHooks): Promise<T>;
+    runAfterPendingWrites<T>(workspaceRoot: string, action: () => Promise<T> | T, hooks?: WorkspaceLockHooks): Promise<T>;
+    waitForPendingWrites(workspaceRoot: string, hooks?: WorkspaceLockHooks): Promise<void>;
+    private getState;
+    private release;
+}
+export {};