clearclaw 0.6.1 → 0.8.0

package/dist/engine/acp.js

@@ -0,0 +1,519 @@
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+import log from "../logger.js";
+import { AsyncQueue } from "./async-queue.js";
+import { serveMcpOverHttp } from "./mcp-http.js";
+export class AcpEngine {
+    name;
+    spawnConfig;
+    constructor(name, spawnConfig) {
+        this.name = name;
+        this.spawnConfig = spawnConfig;
+    }
+    async *runTurn(opts) {
+        const { sessionId, cwd, prompt: textPrompt, attachments, permissionMode, onPermissionRequest, signal, } = opts;
+        let proc;
+        const bridges = [];
+        const queue = new AsyncQueue();
+        const toolCalls = {};
+        let contextUsed = 0;
+        let contextWindow = 0;
+        let model = null;
+        // tool_call events carry content that requestPermission lacks — cache by ID
+        const pendingTools = new Map();
+        // ACP 0.16 does not reject pending setup requests when the process exits.
+        let stop;
+        const stopped = new Promise((_resolve, reject) => { stop = reject; });
+        void stopped.catch(() => { });
+        let cancelSession;
+        const onAbort = () => {
+            cancelSession?.();
+            stop(new DOMException("Turn cancelled", "AbortError"));
+            queue.close();
+        };
+        try {
+            signal?.throwIfAborted();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            proc = spawnAgent(this.spawnConfig, opts);
+            proc.once("error", stop);
+            // Log stderr for debugging
+            proc.stderr?.on("data", (chunk) => {
+                log.debug("[acp:%s] %s", this.name, chunk.toString().trim());
+            });
+            // If the process dies unexpectedly, close the queue
+            proc.on("exit", (code) => {
+                log.info("[acp:%s] process exited with code %d", this.name, code ?? -1);
+                stop(new Error(`ACP process exited during session setup (${code ?? "signal"})`));
+                queue.close();
+            });
+            // Build Client — sessionUpdate pushes to queue after session setup
+            let live = false;
+            const client = {
+                // Newer adapters send optional auth/status extensions. Ignore unsupported
+                // notifications instead of letting the SDK print account metadata.
+                extNotification: async () => { },
+                requestPermission: async (params) => {
+                    return handlePermission(params, permissionMode, onPermissionRequest, pendingTools);
+                },
+                sessionUpdate: async (notification) => {
+                    if (notification.update.sessionUpdate === "config_option_update") {
+                        model = modelConfigOption(notification.update.configOptions)?.currentValue ?? null;
+                        return;
+                    }
+                    // Usage is session state, including updates sent during session loading.
+                    if (notification.update.sessionUpdate === "usage_update") {
+                        contextUsed = notification.update.used;
+                        contextWindow = notification.update.size;
+                        // Loaded history is not a fresh account observation.
+                        if (live) {
+                            const windows = codexPlanUsage(notification.update._meta);
+                            if (windows.length)
+                                queue.push({ type: "plan_usage", windows });
+                        }
+                        return;
+                    }
+                    if (!live)
+                        return; // Suppress replay events from loadSession
+                    const event = mapSessionUpdate(notification, toolCalls, pendingTools);
+                    if (event)
+                        queue.push(event);
+                },
+            };
+            // Create ACP connection over ndjson stdio
+            const stream = ndJsonStream(Writable.toWeb(proc.stdin), Readable.toWeb(proc.stdout));
+            const conn = new ClientSideConnection((_agent) => client, stream);
+            // Initialize and read agent capabilities
+            const initResponse = await Promise.race([conn.initialize({
+                    protocolVersion: PROTOCOL_VERSION,
+                    clientInfo: { name: "clearclaw", version: "0.4.0" },
+                    clientCapabilities: {},
+                }), stopped]);
+            const supportsImages = initResponse.agentCapabilities?.promptCapabilities?.image ?? false;
+            // Hand the agent every server it advertises a transport for; skip the rest.
+            const httpCapable = initResponse.agentCapabilities?.mcpCapabilities?.http ?? false;
+            const mcpServers = [];
+            for (const [name, server] of Object.entries(opts.mcpServers ?? {})) {
+                signal?.throwIfAborted();
+                if (server.type === "sdk" || server.type === "http") {
+                    // ponytail: agents without HTTP MCP run toolless, as every ACP engine did before.
+                    if (!httpCapable) {
+                        log.warn("[acp:%s] skipping MCP server %s: agent does not support HTTP", this.name, name);
+                        continue;
+                    }
+                    if (server.type === "sdk") {
+                        const bridge = await serveMcpOverHttp(name, server);
+                        bridges.push(bridge);
+                        mcpServers.push(bridge.config);
+                    }
+                    else {
+                        mcpServers.push({ type: "http", name, url: server.url,
+                            headers: Object.entries(server.headers ?? {}).map(([name, value]) => ({ name, value })) });
+                    }
+                }
+                else if (server.type === "sse") {
+                    // ClearClaw never configures SSE; no reason to build a passthrough for it.
+                    log.warn("[acp:%s] skipping MCP server %s: SSE is not supported", this.name, name);
+                }
+                else {
+                    mcpServers.push({ name, command: server.command, args: server.args ?? [],
+                        env: Object.entries(server.env ?? {}).map(([name, value]) => ({ name, value })) });
+                }
+            }
+            signal?.throwIfAborted();
+            // Create or resume session
+            let acpSessionId;
+            let configOptions;
+            if (sessionId) {
+                const loadedSession = await Promise.race([conn.loadSession({ sessionId, cwd, mcpServers }), stopped]);
+                configOptions = loadedSession.configOptions;
+                acpSessionId = sessionId;
+            }
+            else {
+                const newSession = await Promise.race([conn.newSession({ cwd, mcpServers }), stopped]);
+                acpSessionId = newSession.sessionId;
+                configOptions = newSession.configOptions;
+            }
+            if (configOptions)
+                model = modelConfigOption(configOptions)?.currentValue ?? null;
+            // Persist before model selection so a rejected selection doesn't lose the session.
+            yield { type: "session", sessionId: acpSessionId };
+            if (opts.model) {
+                signal?.throwIfAborted();
+                const modelOption = modelConfigOption(configOptions);
+                if (!modelOption)
+                    throw new Error(`${this.name} did not advertise a model selector`);
+                const selected = await Promise.race([conn.setSessionConfigOption({
+                        sessionId: acpSessionId, configId: modelOption.id, value: opts.model,
+                    }), stopped]);
+                model = modelConfigOption(selected.configOptions)?.currentValue ?? null;
+            }
+            // Now start accepting live events
+            live = true;
+            // Wire cancellation
+            cancelSession = () => {
+                conn.cancel({ sessionId: acpSessionId }).catch(() => { });
+            };
+            signal?.throwIfAborted();
+            // Build prompt content blocks: text + any image attachments
+            const promptBlocks = [
+                { type: "text", text: textPrompt },
+            ];
+            for (const att of attachments ?? []) {
+                const name = att.filename ?? att.mimeType;
+                const isImage = att.mimeType.startsWith("image/");
+                if (isImage && supportsImages) {
+                    promptBlocks.push({ type: "image", data: att.buffer.toString("base64"), mimeType: att.mimeType });
+                    const label = att.savedAs
+                        ? `[Attachment: ${name} — saved to ${att.savedAs}. Content already included; do not re-read from disk.]`
+                        : `[Attachment: ${name}]`;
+                    promptBlocks.push({ type: "text", text: label });
+                }
+                else {
+                    // Content not included (unsupported format or agent lacks image support)
+                    const reason = isImage ? "agent does not support images" : "unsupported format";
+                    const label = att.savedAs
+                        ? `[Attachment: ${name} (${reason}) — saved to ${att.savedAs}]`
+                        : `[Attachment: ${name} (${reason})]`;
+                    promptBlocks.push({ type: "text", text: label });
+                }
+            }
+            // Send prompt — resolves when turn completes
+            const promptResponse = conn.prompt({
+                sessionId: acpSessionId,
+                prompt: promptBlocks,
+            });
+            // When prompt completes, push done event and close queue
+            promptResponse
+                .then(() => {
+                queue.push({
+                    type: "done",
+                    sessionId: acpSessionId,
+                    stats: { model, contextUsed, contextWindow, toolCalls },
+                });
+                queue.close();
+            })
+                .catch((err) => {
+                queue.push({
+                    type: "error",
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                queue.close();
+            });
+            // Yield events as they arrive
+            yield* queue;
+        }
+        catch (err) {
+            if (!signal?.aborted && !(err instanceof Error && err.name === "AbortError")) {
+                yield {
+                    type: "error",
+                    message: errorMessage(err),
+                };
+            }
+            queue.close();
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+            if (proc && !proc.killed) {
+                proc.kill();
+            }
+            const closed = await Promise.allSettled(bridges.map((bridge) => bridge.close()));
+            for (const result of closed) {
+                if (result.status === "rejected")
+                    log.error({ err: result.reason }, "[mcp] failed to close turn transport");
+            }
+        }
+    }
+    async getSessionMessages(opts) {
+        const messages = [];
+        let previousId;
+        let previousRole;
+        const client = {
+            extNotification: async () => { },
+            requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+            sessionUpdate: async ({ sessionId, update }) => {
+                if (sessionId !== opts.sessionId)
+                    return;
+                if (update.sessionUpdate !== "user_message_chunk" && update.sessionUpdate !== "agent_message_chunk") {
+                    // A tool/thought between text chunks ends the adjacent text segment.
+                    previousRole = undefined;
+                    return;
+                }
+                const role = update.sessionUpdate === "user_message_chunk" ? "user" : "assistant";
+                if (update.content.type !== "text") {
+                    previousRole = undefined;
+                    previousId = undefined;
+                    return;
+                }
+                const last = messages.at(-1);
+                // ACP message IDs preserve separate consecutive messages from the same role.
+                // Older agents without IDs can only be normalized into adjacent role segments.
+                if (last && previousRole === role && previousId === update.messageId) {
+                    last.text += update.content.text;
+                }
+                else {
+                    messages.push({ role, text: update.content.text });
+                }
+                previousId = update.messageId;
+                previousRole = role;
+            },
+        };
+        await this.readSessionData(opts, client, async (conn, init) => {
+            if (!init.agentCapabilities?.loadSession) {
+                throw new Error(`${this.name} does not support loading session history`);
+            }
+            await conn.loadSession({ sessionId: opts.sessionId, cwd: opts.cwd, mcpServers: [] });
+        });
+        return messages.filter((message) => message.text.length > 0);
+    }
+    async listSessions(cwd) {
+        return this.readSessionData({ cwd }, {
+            extNotification: async () => { },
+            requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+            sessionUpdate: async () => { },
+        }, async (conn, init, signal) => {
+            // Listing is optional in ACP. Unsupported agents deliberately have no picker entries.
+            if (!init.agentCapabilities?.sessionCapabilities?.list)
+                return [];
+            // ACP does not promise page ordering; sort only after exhausting the cursor.
+            const sessions = new Map();
+            const cursors = new Set();
+            let cursor;
+            do {
+                signal.throwIfAborted();
+                const page = await conn.listSessions({ cwd, ...(cursor !== undefined ? { cursor } : {}) });
+                for (const session of page.sessions) {
+                    if (session.cwd !== cwd)
+                        continue; // Never mix sibling worktrees into this picker.
+                    const timestamp = session.updatedAt ? Date.parse(session.updatedAt) : NaN;
+                    sessions.set(session.sessionId, {
+                        sessionId: session.sessionId,
+                        // ACP offers a title, not a last-prompt summary or a standard git branch.
+                        summary: session.title?.trim() || session.sessionId,
+                        lastModified: Number.isFinite(timestamp) ? timestamp : 0,
+                    });
+                }
+                cursor = page.nextCursor ?? undefined;
+                if (cursor === undefined)
+                    break;
+                if (cursors.has(cursor))
+                    throw new Error(`${this.name} repeated a session list cursor`);
+                cursors.add(cursor);
+            } while (cursor !== undefined);
+            return [...sessions.values()].sort((a, b) => b.lastModified - a.lastModified).slice(0, 10);
+        });
+    }
+    /** Short-lived, read-only ACP queries share one deadline and always release the child. */
+    async readSessionData(opts, client, query) {
+        opts.signal?.throwIfAborted();
+        const signal = AbortSignal.any([
+            ...(opts.signal ? [opts.signal] : []),
+            AbortSignal.timeout(30_000),
+        ]);
+        const proc = spawnAgent(this.spawnConfig, {
+            ...opts,
+            sessionId: opts.sessionId ?? null,
+            prompt: "",
+            permissionMode: "default",
+            onPermissionRequest: async () => ({ decision: "deny", message: "Session queries cannot run tools" }),
+        });
+        let rejectStopped;
+        const stopped = new Promise((_resolve, reject) => { rejectStopped = reject; });
+        const onAbort = () => rejectStopped(signal.reason);
+        const onError = (err) => rejectStopped(err);
+        const onExit = () => rejectStopped(new Error(`${this.name} exited while querying sessions`));
+        signal.addEventListener("abort", onAbort, { once: true });
+        proc.once("error", onError);
+        proc.once("exit", onExit);
+        // Drain stderr so verbose adapters cannot block waiting for a full pipe.
+        proc.stderr?.resume();
+        try {
+            const conn = new ClientSideConnection(() => client, ndJsonStream(Writable.toWeb(proc.stdin), Readable.toWeb(proc.stdout)));
+            const init = await Promise.race([stopped, conn.initialize({
+                    protocolVersion: PROTOCOL_VERSION, clientCapabilities: {},
+                })]);
+            signal.throwIfAborted();
+            const result = await Promise.race([stopped, query(conn, init, signal)]);
+            signal.throwIfAborted();
+            return result;
+        }
+        catch (err) {
+            if (err instanceof Error)
+                throw err;
+            throw new Error(errorMessage(err));
+        }
+        finally {
+            signal.removeEventListener("abort", onAbort);
+            proc.removeListener("error", onError);
+            proc.removeListener("exit", onExit);
+            proc.stdin?.end();
+            proc.kill();
+        }
+    }
+}
+// --- Helpers ---
+function modelConfigOption(options) {
+    // Categories are optional; accept an advertised "model" ID as a fallback.
+    const option = options?.find((option) => option.category === "model")
+        ?? options?.find((option) => option.id === "model" && !option.category);
+    return option?.type === "select" ? option : undefined;
+}
+function errorMessage(err) {
+    if (err && typeof err === "object" && "message" in err && typeof err.message === "string")
+        return err.message;
+    return String(err);
+}
+function spawnAgent(config, opts) {
+    const extraEnv = typeof config.env === "function" ? config.env(opts) : config.env;
+    const [command, ...args] = config.command;
+    const proc = spawn(command, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
+    });
+    proc.on("error", (err) => {
+        log.error({ err }, "[acp] failed to spawn %s", command);
+    });
+    if (!proc.stdin || !proc.stdout) {
+        throw new Error(`Failed to spawn ${command} — stdin/stdout not available`);
+    }
+    return proc;
+}
+function mapSessionUpdate(notification, toolCalls, pendingTools) {
+    const update = notification.update;
+    switch (update.sessionUpdate) {
+        case "agent_message_chunk": {
+            const content = update.content;
+            if (content.type === "text") {
+                return { type: "text_chunk", text: content.text };
+            }
+            return null;
+        }
+        case "tool_call": {
+            const kind = update.kind ?? "tool";
+            toolCalls[kind] = (toolCalls[kind] ?? 0) + 1;
+            const tool = acpToolCall(update.title, update.toolCallId, kind, update.locations, update.content);
+            pendingTools.set(update.toolCallId, tool);
+            return { type: "tool_use", tool };
+        }
+        case "tool_call_update":
+            return null;
+        default:
+            return null;
+    }
+}
+/** Map ACP tool call fields to ToolCall. */
+function acpToolCall(title, toolCallId, kind, locations, content) {
+    const toolName = title;
+    const toolUseId = toolCallId;
+    const paths = locations?.map((l) => l.line ? `${l.path}:${l.line}` : l.path);
+    switch (kind) {
+        case "edit": {
+            const diff = findDiff(content);
+            return {
+                action: "edit", toolName, toolUseId,
+                path: diff?.path ?? paths?.[0] ?? "",
+                before: diff?.oldText ?? "",
+                after: diff?.newText ?? "",
+            };
+        }
+        case "write": {
+            const diff = findDiff(content);
+            return {
+                action: "write", toolName, toolUseId,
+                path: diff?.path ?? paths?.[0] ?? "",
+                content: diff?.newText ?? "",
+            };
+        }
+        case "read":
+            return { action: "read", toolName, toolUseId, paths: paths ?? [] };
+        case "execute":
+            return { action: "execute", toolName, toolUseId, command: title };
+        case "search":
+            return { action: "search", toolName, toolUseId, pattern: title, paths };
+        case "fetch":
+            return { action: "fetch", toolName, toolUseId, url: title };
+        default: {
+            const detail = findTextContent(content);
+            return { action: kind, toolName, toolUseId, paths, detail };
+        }
+    }
+}
+/** Find the first diff content block from ACP tool call content. */
+function findDiff(content) {
+    const entry = content?.find((c) => c.type === "diff");
+    return entry?.type === "diff" ? entry : undefined;
+}
+/** Extract text from the first content block. */
+function findTextContent(content) {
+    const entry = content?.find((c) => c.type === "content");
+    if (entry?.type === "content" && entry.content.type === "text")
+        return entry.content.text;
+    return undefined;
+}
+async function handlePermission(params, permissionMode, onPermissionRequest, pendingTools) {
+    const allowOption = params.options.find((o) => o.kind === "allow_once");
+    const rejectOption = params.options.find((o) => o.kind === "reject_once");
+    // Auto-approve in bypass mode
+    if (permissionMode === "bypassPermissions" || permissionMode === "dontAsk") {
+        return {
+            outcome: allowOption
+                ? { outcome: "selected", optionId: allowOption.optionId }
+                : { outcome: "cancelled" },
+        };
+    }
+    // Use cached tool_call data (has content/locations) over the sparse permission request
+    const toolCall = params.toolCall;
+    const tool = pendingTools.get(toolCall.toolCallId)
+        ?? acpToolCall(toolCall.title ?? "Unknown tool", toolCall.toolCallId, toolCall.kind ?? "other", toolCall.locations, toolCall.content);
+    const resp = await onPermissionRequest(tool);
+    if (resp.decision === "allow" && allowOption) {
+        return {
+            outcome: { outcome: "selected", optionId: allowOption.optionId },
+        };
+    }
+    if (rejectOption) {
+        return {
+            outcome: { outcome: "selected", optionId: rejectOption.optionId },
+        };
+    }
+    return { outcome: { outcome: "cancelled" } };
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : undefined;
+}
+function finite(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** PR #334's provider extension. Never treat standard ACP used/size as plan usage. */
+export function codexPlanUsage(meta) {
+    const limits = object(meta)?.["_codex/rateLimits"];
+    if (!Array.isArray(limits))
+        return [];
+    const windows = [];
+    for (const value of limits) {
+        const limit = object(value);
+        if (!limit || typeof limit.limitId !== "string")
+            continue;
+        const prefix = limit.limitId === "codex" ? "" : `${limit.limitId.replace(/[\r\n|]/g, " ").slice(0, 24)} `;
+        for (const key of ["primary", "secondary"]) {
+            const window = object(limit[key]);
+            if (!window)
+                continue;
+            const minutes = finite(window.windowDurationMins);
+            const percent = finite(window.usedPercent);
+            const reset = finite(window.resetsAt);
+            if (minutes === undefined || minutes <= 0)
+                continue;
+            const duration = minutes % 1440 === 0 ? `${minutes / 1440}d`
+                : minutes % 60 === 0 ? `${minutes / 60}h` : `${minutes}m`;
+            windows.push({
+                id: `${limit.limitId}/${key}`, label: `${prefix}${duration}`,
+                usedPercent: percent !== undefined && percent >= 0 && percent <= 100 ? percent : undefined,
+                resetsAt: reset !== undefined && reset > 0 ? reset : undefined,
+            });
+        }
+    }
+    return windows;
+}
+//# sourceMappingURL=acp.js.map

package/dist/engine/async-queue.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bridges callback-driven event producers to AsyncIterable consumers.
+ *
+ * Used by AcpEngine to convert ACP's sessionUpdate callbacks into
+ * the AsyncIterable<EngineEvent> that ClearClaw's Engine interface requires.
+ */
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    private buffer;
+    private waiting;
+    private closed;
+    push(value: T): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/engine/async-queue.js

@@ -0,0 +1,45 @@
+/**
+ * Bridges callback-driven event producers to AsyncIterable consumers.
+ *
+ * Used by AcpEngine to convert ACP's sessionUpdate callbacks into
+ * the AsyncIterable<EngineEvent> that ClearClaw's Engine interface requires.
+ */
+export class AsyncQueue {
+    buffer = [];
+    waiting = [];
+    closed = false;
+    push(value) {
+        if (this.closed)
+            return;
+        const waiter = this.waiting.shift();
+        if (waiter) {
+            waiter({ value, done: false });
+        }
+        else {
+            this.buffer.push(value);
+        }
+    }
+    close() {
+        this.closed = true;
+        for (const waiter of this.waiting) {
+            waiter({ value: undefined, done: true });
+        }
+        this.waiting.length = 0;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.buffer.length > 0) {
+                    return Promise.resolve({ value: this.buffer.shift(), done: false });
+                }
+                if (this.closed) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve) => {
+                    this.waiting.push(resolve);
+                });
+            },
+        };
+    }
+}
+//# sourceMappingURL=async-queue.js.map

package/dist/engine/claude-code.d.ts

@@ -1,6 +1,25 @@
-import type { Engine, EngineEvent, RunTurnOpts, SessionInfo } from "../types.js";
+import { type SDKRateLimitInfo } from "@anthropic-ai/claude-agent-sdk";
+import type { Engine, EngineEvent, PlanUsageWindow, RunTurnOpts, SessionInfo, SessionHistoryOpts, SessionMessage } from "../types.js";
 export declare class ClaudeCodeEngine implements Engine {
+    private readonly executablePath?;
+    private readonly configPath?;
     name: string;
+    readonly planUsageWindows: readonly PlanUsageWindow[];
+    constructor(executablePath?: string | undefined, configPath?: string | undefined);
+    getSessionMessages({ sessionId, cwd, signal }: SessionHistoryOpts): Promise<SessionMessage[]>;
     listSessions(cwd: string): Promise<SessionInfo[]>;
     runTurn(opts: RunTurnOpts): AsyncIterable<EngineEvent>;
 }
+/** Claude runtime fields newer than the bundled SDK declarations. */
+type ClaudeRateLimitInfo = Omit<SDKRateLimitInfo, "rateLimitType"> & {
+    rateLimitType?: string;
+    unifiedWindows?: Record<string, {
+        utilization: number;
+        resetsAt: number;
+    }>;
+};
+export declare const CLAUDE_PLAN_WINDOWS: readonly PlanUsageWindow[];
+export declare function claudePlanUsage(info: ClaudeRateLimitInfo): Extract<EngineEvent, {
+    type: "plan_usage";
+}>;
+export {};