@botlearn-course/daemon 0.0.1

package/dist/runtimes/acp-stream.d.ts

@@ -0,0 +1,96 @@
+import { type EngineAdapter, type EngineRunOptions, type EngineRunResult, type RuntimeStatusEvent, type StreamBlock } from "./engine.js";
+import type { Logger } from "../log.js";
+/** 本客户端目标的 ACP 协议版本。 */
+export declare const ACP_PROTOCOL_VERSION = 1;
+export interface AcpInitializeResult {
+    protocolVersion?: number;
+    agentInfo?: {
+        name?: string;
+        version?: string;
+    };
+    agentCapabilities?: Record<string, unknown>;
+    authMethods?: Array<{
+        id?: string;
+        name?: string;
+        description?: string;
+    }>;
+    [k: string]: unknown;
+}
+export interface AcpPermissionOption {
+    optionId: string;
+    name?: string;
+    /**
+     * ACP option kind，常见值 allow_once / allow_always / reject_once /
+     * reject_always。基类视为不透明字符串，由子类检查决定结果。
+     */
+    kind?: string;
+    [k: string]: unknown;
+}
+export interface AcpPermissionRequest {
+    sessionId: string;
+    toolCall?: {
+        name?: string;
+        rawInput?: unknown;
+        [k: string]: unknown;
+    };
+    options: AcpPermissionOption[];
+    [k: string]: unknown;
+}
+export type AcpPermissionResponse = {
+    outcome: {
+        outcome: "selected";
+        optionId: string;
+    };
+} | {
+    outcome: {
+        outcome: "cancelled";
+    };
+};
+export interface AcpUpdateParams {
+    sessionId: string;
+    update: {
+        sessionUpdate?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** 子类在一轮执行中响应入站流量的钩子。 */
+export interface AcpTurnHooks {
+    onUpdate(params: AcpUpdateParams, ctx: AcpUpdateCtx): void;
+    onPermissionRequest(req: AcpPermissionRequest): Promise<AcpPermissionResponse>;
+}
+export interface AcpUpdateCtx {
+    /** 追加本轮流式 assistant 文本（尊重字节上限）。 */
+    appendAssistantText(text: string): void;
+    emitBlock(block: StreamBlock): void;
+    /** 转发 typing/thinking 状态事件（如 thought chunk、tool 进度）。 */
+    emitStatus(event: RuntimeStatusEvent): void;
+    /** 本轮 1-based 序号。 */
+    seq: number;
+}
+export declare abstract class AcpRuntimeAdapter implements EngineAdapter {
+    abstract readonly id: string;
+    protected readonly log: Logger;
+    constructor(logger?: Logger);
+    protected abstract resolveBinary(opts: EngineRunOptions): string;
+    /** argv 尾部（不含二进制）。ACP server 通常不需要参数。 */
+    protected buildArgs(_opts: EngineRunOptions): string[];
+    protected abstract spawnEnv(opts: EngineRunOptions): NodeJS.ProcessEnv;
+    /** 子类钩子：响应一条 session/update 通知。 */
+    protected abstract onUpdate(params: AcpUpdateParams, ctx: AcpUpdateCtx): void;
+    /** 子类钩子：应答 session/request_permission 请求。 */
+    protected abstract onPermissionRequest(req: AcpPermissionRequest, opts: EngineRunOptions): Promise<AcpPermissionResponse>;
+    /** initialize 时发送的 clientCapabilities。 */
+    protected clientCapabilities(): Record<string, unknown>;
+    /** initialize 时发送的 clientInfo。 */
+    protected clientInfo(): {
+        name: string;
+        version: string;
+    };
+    /** spawn 之前同步调用；子类可借此把 systemContext 落盘（如 <cwd>/AGENTS.md）。 */
+    protected prepareTurn(_opts: EngineRunOptions): void;
+    /** 传给 ACP session/new / session/load 的 cwd。 */
+    protected sessionCwd(opts: EngineRunOptions): string;
+    run(opts: EngineRunOptions): Promise<EngineRunResult>;
+    private withTimeout;
+}

package/dist/runtimes/acp-stream.js

@@ -0,0 +1,488 @@
+import { spawn } from "node:child_process";
+import { sanitizeRuntimeFailureText } from "../redaction.js";
+import { sliceUtf8Bytes, utf8ByteLength } from "./text-cap.js";
+import { consoleLogger, } from "./engine.js";
+/**
+ * ACP（Agent Client Protocol）over stdio 的最小双向客户端基类
+ * （JSON-RPC 2.0，newline-delimited）。
+ *
+ * 为什么不用 NdjsonStreamAdapter：ACP 是双向 RPC —— agent 除了发通知
+ * （session/update）还会发起 server→client 请求（session/request_permission），
+ * daemon 必须应答否则 agent 卡死；单向事件流基类无法正确驱动。
+ */
+/** 保留用于错误报告的 stderr 尾部长度。 */
+const STDERR_TAIL_CAP = 8 * 1024;
+/** 合成错误里包含的 stderr 末尾长度。 */
+const STDERR_ERROR_SNIPPET = 500;
+/** 单轮流式 assistant 文本字节上限 —— 防失控 runtime。 */
+const ASSISTANT_TEXT_CAP = 1 * 1024 * 1024;
+/** abort 时 SIGTERM → SIGKILL 的宽限期。 */
+const KILL_GRACE_MS = 5_000;
+/** initialize 握手的最长等待。 */
+const INITIALIZE_TIMEOUT_MS = 30_000;
+/** prompt RPC 出错后等待迟到 session/update 块的短暂 drain 窗口。 */
+const PROMPT_ERROR_DRAIN_MS = 750;
+/** 本客户端目标的 ACP 协议版本。 */
+export const ACP_PROTOCOL_VERSION = 1;
+/** 子进程 stdio 之上的最小 newline-JSON-RPC 分帧。 */
+class AcpConnection {
+    child;
+    handlers;
+    logId;
+    log;
+    nextId = 1;
+    pending = new Map();
+    stdoutBuf = "";
+    closed = false;
+    closeReason = null;
+    constructor(child, handlers, logId, log) {
+        this.child = child;
+        this.handlers = handlers;
+        this.logId = logId;
+        this.log = log;
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => this.onStdout(chunk));
+        child.stdout.on("end", () => this.fail(new Error("stdout closed")));
+        child.on("close", (code) => this.fail(new Error(`process exited with code ${code ?? 0}`)));
+        child.on("error", (err) => this.fail(err));
+    }
+    onStdout(chunk) {
+        this.stdoutBuf += chunk;
+        let idx;
+        while ((idx = this.stdoutBuf.indexOf("\n")) !== -1) {
+            const line = this.stdoutBuf.slice(0, idx).trim();
+            this.stdoutBuf = this.stdoutBuf.slice(idx + 1);
+            if (!line)
+                continue;
+            this.dispatchLine(line);
+        }
+    }
+    dispatchLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            this.log.warn(`${this.logId} non-json acp line`, { line: line.slice(0, 200) });
+            return;
+        }
+        if (typeof msg !== "object" || msg === null)
+            return;
+        // 对客户端→服务端请求的响应
+        if (typeof msg.id === "number" && (msg.result !== undefined || msg.error !== undefined)) {
+            const pending = this.pending.get(msg.id);
+            if (!pending)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.error) {
+                const err = new Error(`acp error ${msg.error.code ?? "?"}: ${formatRpcError(msg.error)}`);
+                pending.reject(err);
+            }
+            else {
+                pending.resolve(msg.result ?? null);
+            }
+            return;
+        }
+        if (typeof msg.method === "string") {
+            // 服务端→客户端请求（带 id）或通知（无 id）
+            if (msg.id !== undefined) {
+                void this.handleServerRequest(msg.id, msg.method, msg.params);
+            }
+            else {
+                try {
+                    this.handlers.onNotification(msg.method, msg.params);
+                }
+                catch (err) {
+                    this.log.warn(`${this.logId} notification handler threw`, {
+                        method: msg.method,
+                        err: String(err),
+                    });
+                }
+            }
+        }
+    }
+    async handleServerRequest(id, method, params) {
+        let result;
+        let error = null;
+        try {
+            result = await this.handlers.onRequest(method, params);
+        }
+        catch (err) {
+            error = {
+                code: -32603,
+                message: err instanceof Error ? err.message : String(err),
+            };
+        }
+        const reply = error
+            ? { jsonrpc: "2.0", id, error }
+            : { jsonrpc: "2.0", id, result: result ?? null };
+        this.writeMessage(reply);
+    }
+    writeMessage(obj) {
+        if (this.closed)
+            return;
+        try {
+            this.child.stdin.write(JSON.stringify(obj) + "\n");
+        }
+        catch (err) {
+            this.fail(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    request(method, params) {
+        if (this.closed) {
+            return Promise.reject(this.closeReason ?? new Error("acp closed"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: (v) => resolve(v),
+                reject,
+            });
+            this.writeMessage({ jsonrpc: "2.0", id, method, params });
+        });
+    }
+    notify(method, params) {
+        this.writeMessage({ jsonrpc: "2.0", method, params });
+    }
+    fail(err) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.closeReason = err;
+        for (const [, p] of this.pending)
+            p.reject(err);
+        this.pending.clear();
+    }
+    isClosed() {
+        return this.closed;
+    }
+}
+export class AcpRuntimeAdapter {
+    log;
+    constructor(logger) {
+        this.log = logger ?? consoleLogger;
+    }
+    /** argv 尾部（不含二进制）。ACP server 通常不需要参数。 */
+    buildArgs(_opts) {
+        return [];
+    }
+    /** initialize 时发送的 clientCapabilities。 */
+    clientCapabilities() {
+        return { fs: { readTextFile: false, writeTextFile: false } };
+    }
+    /** initialize 时发送的 clientInfo。 */
+    clientInfo() {
+        return { name: "botlearn-course-daemon", version: "0.1" };
+    }
+    /** spawn 之前同步调用；子类可借此把 systemContext 落盘（如 <cwd>/AGENTS.md）。 */
+    prepareTurn(_opts) {
+        /* default: noop */
+    }
+    /** 传给 ACP session/new / session/load 的 cwd。 */
+    sessionCwd(opts) {
+        return opts.cwd;
+    }
+    async run(opts) {
+        if (opts.signal.aborted) {
+            return {
+                text: "",
+                newSessionId: opts.sessionId ?? "",
+                error: `${this.id} aborted before spawn`,
+            };
+        }
+        try {
+            this.prepareTurn(opts);
+        }
+        catch (err) {
+            this.log.warn(`${this.id} prepareTurn threw`, { err: String(err) });
+        }
+        const binary = this.resolveBinary(opts);
+        const args = this.buildArgs(opts);
+        this.log.debug(`${this.id} spawn`, {
+            cwd: opts.cwd,
+            sessionId: opts.sessionId,
+            argv: args,
+        });
+        const child = spawn(binary, args, {
+            cwd: opts.cwd,
+            env: this.spawnEnv(opts),
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let killTimer = null;
+        const onAbort = () => {
+            if (child.killed)
+                return;
+            try {
+                child.stdin.end();
+            }
+            catch {
+                /* best-effort */
+            }
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => {
+                if (!child.killed) {
+                    this.log.warn(`${this.id} did not exit after SIGTERM; sending SIGKILL`);
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }
+            }, KILL_GRACE_MS);
+            if (typeof killTimer.unref === "function")
+                killTimer.unref();
+        };
+        opts.signal.addEventListener("abort", onAbort, { once: true });
+        let stderrTail = "";
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderrTail = sanitizeRuntimeFailureText(stderrTail + chunk, STDERR_TAIL_CAP);
+        });
+        const state = {
+            finalText: "",
+            assistantTextChunks: [],
+            assistantTextBytes: 0,
+            assistantTextCapped: false,
+        };
+        const appendAssistantText = (text) => {
+            if (!text || state.assistantTextCapped)
+                return;
+            const budget = ASSISTANT_TEXT_CAP - state.assistantTextBytes;
+            if (budget <= 0) {
+                state.assistantTextCapped = true;
+                return;
+            }
+            const bytes = utf8ByteLength(text);
+            if (bytes > budget) {
+                const chunk = sliceUtf8Bytes(text, budget);
+                if (chunk) {
+                    state.assistantTextChunks.push(chunk);
+                    state.assistantTextBytes += utf8ByteLength(chunk);
+                }
+                state.assistantTextCapped = true;
+                return;
+            }
+            state.assistantTextChunks.push(text);
+            state.assistantTextBytes += bytes;
+        };
+        let seq = 0;
+        const conn = new AcpConnection(child, {
+            onNotification: (method, params) => {
+                if (method === "session/update") {
+                    seq += 1;
+                    this.onUpdate(params, {
+                        appendAssistantText,
+                        emitBlock: (b) => opts.onBlock?.(b),
+                        emitStatus: (e) => {
+                            try {
+                                opts.onStatus?.(e);
+                            }
+                            catch (err) {
+                                this.log.warn(`${this.id} onStatus threw`, { err: String(err) });
+                            }
+                        },
+                        seq,
+                    });
+                }
+            },
+            onRequest: async (method, params) => {
+                if (method === "session/request_permission") {
+                    return this.onPermissionRequest(params, opts);
+                }
+                // 未知的 server→client 请求：抛错经 AcpConnection 折叠成 JSON-RPC
+                // error 应答，让 server 自行决定。
+                const err = new Error(`unknown server request: ${method}`);
+                throw err;
+            },
+        }, this.id, this.log);
+        const childExit = new Promise((resolve) => {
+            child.on("close", (code) => {
+                resolve(code ?? 0);
+            });
+            child.on("error", () => {
+                /* close 仍会触发；error 本身不携带 exit code */
+            });
+        });
+        let newSessionId = opts.sessionId ?? "";
+        let promptStarted = false;
+        try {
+            // 1) initialize
+            await this.withTimeout(conn.request("initialize", {
+                protocolVersion: ACP_PROTOCOL_VERSION,
+                clientCapabilities: this.clientCapabilities(),
+                clientInfo: this.clientInfo(),
+            }), INITIALIZE_TIMEOUT_MS, "initialize");
+            // 2) session/load（resume 时）→ 失败可恢复则回退 session/new
+            const cwd = this.sessionCwd(opts);
+            let sessionId = "";
+            if (opts.sessionId) {
+                try {
+                    const loaded = (await conn.request("session/load", {
+                        sessionId: opts.sessionId,
+                        cwd,
+                        mcpServers: [],
+                    }));
+                    if (loaded !== null && loaded !== undefined) {
+                        // Hermes 的 load_session 不回传 session_id —— 复用请求的那个；
+                        // 若未来的 server 回传了，则优先用回传值。
+                        sessionId =
+                            (loaded && typeof loaded.sessionId === "string" ? loaded.sessionId : "") ||
+                                opts.sessionId;
+                    }
+                }
+                catch (err) {
+                    if (!isRecoverableSessionLoadError(err)) {
+                        throw new Error(`session/load failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    this.log.warn(`${this.id} session/load failed; falling back to new`, {
+                        err: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            if (!sessionId) {
+                const created = await conn.request("session/new", {
+                    cwd,
+                    mcpServers: [],
+                });
+                sessionId = created?.sessionId ?? "";
+            }
+            if (!sessionId) {
+                throw new Error("acp server did not return a sessionId");
+            }
+            newSessionId = sessionId;
+            // 3) session/prompt
+            promptStarted = true;
+            const promptResult = (await conn.request("session/prompt", {
+                sessionId,
+                prompt: [{ type: "text", text: opts.text }],
+            }));
+            const stopReason = promptResult?.stopReason ?? "end_turn";
+            if (stopReason === "refusal" || stopReason === "error") {
+                const tail = stderrTail.slice(-STDERR_ERROR_SNIPPET).trim();
+                state.errorText =
+                    state.errorText ??
+                        (tail ? `prompt stopped: ${stopReason}; stderr: ${tail}` : `prompt stopped: ${stopReason}`);
+            }
+            // 提前告知 dispatcher 推理循环已结束 —— 对没有产生
+            // agent_message_chunk 的轮次（纯工具副作用、refusal、error）尤为重要；
+            // 子进程退出可能还要等数秒。
+            try {
+                opts.onStatus?.({ kind: "thinking", phase: "stopped" });
+            }
+            catch (err) {
+                this.log.warn(`${this.id} onStatus(prompt-done) threw`, { err: String(err) });
+            }
+            // 礼貌地关 stdin 让 server 可以退出；不退出则由 abort 信号 SIGTERM。
+            try {
+                child.stdin.end();
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        catch (err) {
+            const baseMsg = err instanceof Error ? err.message : String(err);
+            const tail = stderrTail.slice(-STDERR_ERROR_SNIPPET).trim();
+            state.errorText = state.errorText ?? (tail ? `${baseMsg}; stderr: ${tail}` : baseMsg);
+            if (promptStarted && !opts.signal.aborted) {
+                await sleepUnlessAborted(PROMPT_ERROR_DRAIN_MS, opts.signal);
+            }
+            try {
+                child.stdin.end();
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        let code = 0;
+        try {
+            code = await childExit;
+        }
+        finally {
+            opts.signal.removeEventListener("abort", onAbort);
+            if (killTimer)
+                clearTimeout(killTimer);
+        }
+        if (code !== 0 && !state.errorText) {
+            state.errorText = `${this.id} exited with code ${code}: ${stderrTail.slice(-STDERR_ERROR_SNIPPET)}`;
+        }
+        const rawText = state.finalText || state.assistantTextChunks.join("").trim();
+        const text = utf8ByteLength(rawText) > ASSISTANT_TEXT_CAP
+            ? sliceUtf8Bytes(rawText, ASSISTANT_TEXT_CAP)
+            : rawText;
+        return {
+            text,
+            newSessionId,
+            ...(state.errorText ? { error: state.errorText } : {}),
+        };
+    }
+    withTimeout(p, ms, label) {
+        return new Promise((resolve, reject) => {
+            const t = setTimeout(() => reject(new Error(`${this.id} ${label} timed out after ${ms}ms`)), ms);
+            if (typeof t.unref === "function")
+                t.unref();
+            p.then((v) => {
+                clearTimeout(t);
+                resolve(v);
+            }, (e) => {
+                clearTimeout(t);
+                reject(e);
+            });
+        });
+    }
+}
+function formatRpcError(error) {
+    if (!error || typeof error !== "object")
+        return "(no message)";
+    const e = error;
+    const message = typeof e.message === "string" && e.message ? e.message : "(no message)";
+    const data = e.data;
+    if (data === undefined || data === null)
+        return message;
+    let detail = "";
+    if (typeof data === "string") {
+        detail = data;
+    }
+    else {
+        const dataObj = typeof data === "object" ? data : null;
+        const details = dataObj && typeof dataObj.details === "string" ? dataObj.details : "";
+        if (details) {
+            detail = details;
+        }
+        else {
+            try {
+                detail = JSON.stringify(data);
+            }
+            catch {
+                detail = String(data);
+            }
+        }
+    }
+    return detail ? `${message}: ${detail}` : message;
+}
+function isRecoverableSessionLoadError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return (isSessionNotFoundError(err) ||
+        /\bnot\s+found\b/i.test(msg) ||
+        /method\s+not\s+found|unknown\s+method|not\s+implemented/i.test(msg));
+}
+function isSessionNotFoundError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return /session(?:\s+[\w-]+)?\s+not\s+found|no\s+session\s+found|unknown\s+session/i.test(msg);
+}
+function sleepUnlessAborted(ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const t = setTimeout(done, ms);
+        if (typeof t.unref === "function")
+            t.unref();
+        function done() {
+            signal.removeEventListener("abort", done);
+            clearTimeout(t);
+            resolve();
+        }
+        signal.addEventListener("abort", done, { once: true });
+    });
+}

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

@@ -0,0 +1,41 @@
+import { NdjsonStreamAdapter, type NdjsonEventCtx } from "./ndjson-stream.js";
+import { type EngineRunOptions } from "./engine.js";
+import { type ProbeDeps } from "./probe.js";
+import type { Logger } from "../log.js";
+import type { RuntimeAuthProbe, RuntimeModule, RuntimeProbe } from "../types.js";
+export declare function scrubClaudeCodeAuthEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function sanitizeClaudeExtraArgs(extraArgs: string[] | undefined): string[];
+/** 通过 PATH 或 macOS 桌面 bundle 兜底解析 Claude Code CLI。 */
+export declare function resolveClaudeCommand(deps?: ProbeDeps): string | null;
+/** 探测 Claude Code CLI 是否安装并读取版本。 */
+export declare function probeClaude(deps?: ProbeDeps): RuntimeProbe;
+export interface ClaudeAuthProbeResult extends RuntimeAuthProbe {
+    message: string;
+}
+/** 用 `claude -p ping` 探测登录态；Claude Code 会把认证失败伪装成 success result。 */
+export declare function probeClaudeAuth(deps?: ProbeDeps): ClaudeAuthProbeResult;
+/**
+ * Claude Code adapter — spawn `claude -p "<text>" --output-format stream-json`
+ * （有会话时加 `--resume <sid>`）并解析 ndjson 流。
+ *
+ * stream-json 形状（节选）：
+ *   {type:"system", subtype:"init", session_id:"...", ...}
+ *   {type:"assistant", message:{content:[{type:"text", text:"..."} | {type:"tool_use", ...}]}}
+ *   {type:"user", message:{content:[{type:"tool_result", ...}]}}
+ *   {type:"result", subtype:"success", session_id:"...", total_cost_usd: 0.01, result:"final text"}
+ */
+export declare class ClaudeCodeAdapter extends NdjsonStreamAdapter {
+    readonly id: "claude-code";
+    private readonly explicitBinary;
+    private resolvedBinary;
+    constructor(opts?: {
+        binary?: string;
+        logger?: Logger;
+    });
+    run(opts: EngineRunOptions): Promise<import("./engine.js").EngineRunResult>;
+    protected resolveBinary(): string;
+    protected buildArgs(opts: EngineRunOptions): string[];
+    protected spawnEnv(opts: EngineRunOptions): NodeJS.ProcessEnv;
+    protected handleEvent(raw: unknown, ctx: NdjsonEventCtx): void;
+}
+export declare const claudeCodeModule: RuntimeModule;