@botlearn-course/daemon 0.0.1

package/dist/runtimes/hermes-agent.js

@@ -0,0 +1,173 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { AcpRuntimeAdapter, } from "./acp-stream.js";
+import { firstExistingPath, readCommandVersion, resolveCommandOnPath, resolveHomePath, } from "./probe.js";
+import { wrapEngineAdapter, } from "./engine.js";
+/**
+ * `hermes-acp` 不在 PATH 上时的已知绝对位置。上游 `scripts/install.sh`
+ * （curl|bash 安装器）把私有 virtualenv 装到 `~/.hermes/hermes-agent/venv/`，
+ * 只把用户可见的 `hermes` 命令软链进 `~/.local/bin/` —— `hermes-acp` 入口
+ * 留在 venv 里，没有回退就会漏掉所有按 README 推荐脚本安装的用户。
+ */
+const HERMES_ACP_FALLBACK_RELATIVE_PATHS = [
+    path.join(".hermes", "hermes-agent", "venv", "bin", "hermes-acp"),
+];
+const HERMES_ACP_FALLBACK_SYSTEM_PATHS = ["/opt/hermes/hermes-agent/venv/bin/hermes-acp"];
+/**
+ * 解析 `hermes-acp` 可执行文件：env 覆盖 → PATH → 安装脚本的私有 venv 位置。
+ */
+export function resolveHermesAcpCommand(deps = {}) {
+    const explicit = (deps.env ?? process.env).BOTLEARN_HERMES_AGENT_BIN;
+    if (explicit && explicit.length > 0)
+        return explicit;
+    const onPath = resolveCommandOnPath("hermes-acp", deps);
+    if (onPath)
+        return onPath;
+    return firstExistingPath([
+        ...HERMES_ACP_FALLBACK_RELATIVE_PATHS.map((p) => resolveHomePath(p, deps)),
+        ...HERMES_ACP_FALLBACK_SYSTEM_PATHS,
+    ], deps);
+}
+export function probeHermesAgent(deps = {}) {
+    const command = resolveHermesAcpCommand(deps);
+    if (!command)
+        return { available: false };
+    return {
+        available: true,
+        path: command,
+        version: readCommandVersion(command, [], deps) ?? undefined,
+    };
+}
+/**
+ * Hermes Agent 引擎。驱动 `hermes-acp`（`pip install "hermes-agent[acp]"`
+ * 附带的 ACP stdio adapter），复用用户本机 `~/.hermes` 的已登录凭据与配置
+ * （不再切换 HERMES_HOME）。
+ *
+ * ## systemContext 注入
+ *
+ * hermes 从 spawn cwd 向上发现 `AGENTS.md`。cwd 即本 run 的隔离工作区，
+ * spawn 前把 `opts.systemContext` 原子写入 `<cwd>/AGENTS.md`。注意这是
+ * **首轮注入**：hermes 把 system prompt 持久化在会话库里，续轮不重读该文件
+ * （course run 单轮执行，不受影响）。
+ *
+ * ## 权限姿态
+ *
+ * `HERMES_INTERACTIVE=1` 让 hermes 把危险工具调用经 ACP
+ * `session/request_permission` 反向请求。course run 在 owner 本机的隔离
+ * 工作区内执行，视为 owner 信任 —— 一律选 `allow_*` 选项。
+ */
+export class HermesAgentAdapter extends AcpRuntimeAdapter {
+    id = "hermes-agent";
+    explicitBinary;
+    resolvedBinary = null;
+    constructor(opts) {
+        super(opts?.logger);
+        this.explicitBinary = opts?.binary ?? process.env.BOTLEARN_HERMES_AGENT_BIN;
+    }
+    resolveBinary() {
+        if (this.explicitBinary)
+            return this.explicitBinary;
+        if (this.resolvedBinary)
+            return this.resolvedBinary;
+        this.resolvedBinary = resolveHermesAcpCommand() ?? "hermes-acp";
+        return this.resolvedBinary;
+    }
+    /**
+     * hermes-acp 无位置参数 —— ACP 是纯 stdio JSON-RPC。不转发
+     * `opts.extraArgs`：hermes-acp 不接受运行时配置 flag，模型等配置在
+     * 用户 `~/.hermes` 的 `.env` / config.yaml 里。
+     */
+    buildArgs(_opts) {
+        return [];
+    }
+    spawnEnv(_opts) {
+        return {
+            ...process.env,
+            // 保持 ACP stdout 无 ANSI 码。
+            NO_COLOR: "1",
+            // 危险工具调用走 ACP request_permission。
+            HERMES_INTERACTIVE: "1",
+        };
+    }
+    /** spawn 前把 systemContext 原子写入 `<cwd>/AGENTS.md`（tmp 0600 + rename）。 */
+    prepareTurn(opts) {
+        mkdirSync(opts.cwd, { recursive: true, mode: 0o700 });
+        const target = path.join(opts.cwd, "AGENTS.md");
+        const tmp = path.join(opts.cwd, `.AGENTS.md.${process.pid}.tmp`);
+        writeFileSync(tmp, opts.systemContext ?? "", { mode: 0o600 });
+        renameSync(tmp, target);
+    }
+    /**
+     * 把 ACP `session/update` 通知翻译成 StreamBlock + assistant 文本。
+     *
+     * `agent_thought_chunk` 刻意只映射为 `thinking.updated` 状态事件、不发
+     * block：其 payload 没有可渲染字段，发 `system` block 只会产生空块。
+     * 其余未知类型按 `other` 透传，便于下游自行 introspect。
+     */
+    onUpdate(params, ctx) {
+        const update = params.update ?? {};
+        const kind = typeof update.sessionUpdate === "string" ? update.sessionUpdate : "";
+        if (kind === "agent_thought_chunk") {
+            ctx.emitStatus({ kind: "thinking", phase: "updated", label: "Thinking" });
+            return;
+        }
+        let blockKind = "other";
+        let assistantTextSeen = false;
+        if (kind === "agent_message_chunk") {
+            const content = update.content;
+            if (content && content.type === "text" && typeof content.text === "string") {
+                ctx.appendAssistantText(content.text);
+                assistantTextSeen = content.text.length > 0;
+            }
+            blockKind = "assistant_text";
+        }
+        else if (kind === "tool_call" || kind === "tool_call_update") {
+            blockKind = "tool_use";
+        }
+        else if (kind === "user_message_chunk") {
+            blockKind = "other";
+        }
+        // 状态提示先于 block 发出，让下游先看到带 label 的 thinking 帧。
+        const status = hermesStatusEvent(kind, update, assistantTextSeen);
+        if (status)
+            ctx.emitStatus(status);
+        ctx.emitBlock({ raw: params, kind: blockKind, seq: ctx.seq });
+    }
+    /**
+     * owner 信任：选第一个 `kind` 以 `allow_` 开头的选项，没有再退回第一个
+     * 选项；连选项都没有则 cancel（ACP DeniedOutcome 不携带 reason）。
+     */
+    async onPermissionRequest(req, _opts) {
+        const options = Array.isArray(req.options) ? req.options : [];
+        const allow = options.find((o) => typeof o.kind === "string" && o.kind.startsWith("allow_")) ?? options[0];
+        if (allow?.optionId) {
+            return { outcome: { outcome: "selected", optionId: allow.optionId } };
+        }
+        return { outcome: { outcome: "cancelled" } };
+    }
+}
+/**
+ * 把 ACP `session/update` payload 映射为状态事件。只返回带 label 或
+ * 表达 dispatcher 无法从 block kind 推断的转变的事件。
+ */
+function hermesStatusEvent(kind, update, assistantTextSeen) {
+    // `agent_thought_chunk` 在 onUpdate 内联处理（status-only 路径）。
+    if (kind === "tool_call" || kind === "tool_call_update") {
+        const tool = update.toolCall;
+        const name = typeof tool?.name === "string" && tool.name ? tool.name : "tool";
+        return { kind: "thinking", phase: "updated", label: name };
+    }
+    if (kind === "agent_message_chunk" && assistantTextSeen) {
+        return { kind: "thinking", phase: "stopped" };
+    }
+    return undefined;
+}
+export const hermesAgentModule = {
+    id: "hermes-agent",
+    displayName: "Hermes Agent",
+    binary: "hermes-acp",
+    envVar: "BOTLEARN_HERMES_AGENT_BIN",
+    installHint: 'pip install "hermes-agent[acp]" (or set BOTLEARN_HERMES_AGENT_BIN)',
+    probe: async () => probeHermesAgent(),
+    create: () => wrapEngineAdapter("hermes-agent", new HermesAgentAdapter()),
+};

package/dist/runtimes/index.d.ts

@@ -0,0 +1,15 @@
+import type { CourseRuntime, RuntimeModule, RuntimeProbeEntry } from "../types.js";
+export declare const DEFAULT_RUNTIME_ID = "codex";
+export declare const RUNTIME_MODULES: readonly RuntimeModule[];
+export declare function fakeRuntimeEnabled(): boolean;
+export declare function getRuntimeModule(id: string): RuntimeModule | null;
+export declare function listRuntimeIds(opts?: {
+    includeHidden?: boolean;
+}): string[];
+export declare function envVarForRuntime(id: string): string;
+export declare function createRuntime(id: string): CourseRuntime;
+export declare function detectRuntimes(opts?: {
+    includeHidden?: boolean;
+}): Promise<RuntimeProbeEntry[]>;
+/** capabilities 上报用：available 且非 hidden；fake 仅在显式启用时加入。 */
+export declare function detectAvailableRuntimeIds(): Promise<string[]>;

package/dist/runtimes/index.js

@@ -0,0 +1,74 @@
+import { claudeCodeModule } from "./claude-code.js";
+import { codexModule } from "./codex.js";
+import { deepseekTuiModule } from "./deepseek-tui.js";
+import { fakeModule } from "./fake.js";
+import { geminiModule } from "./gemini.js";
+import { hermesAgentModule } from "./hermes-agent.js";
+import { kimiCliModule } from "./kimi.js";
+import { openclawAcpModule } from "./openclaw-acp.js";
+export const DEFAULT_RUNTIME_ID = "codex";
+export const RUNTIME_MODULES = [
+    codexModule,
+    claudeCodeModule,
+    geminiModule,
+    openclawAcpModule,
+    kimiCliModule,
+    deepseekTuiModule,
+    hermesAgentModule,
+    fakeModule,
+];
+const BY_ID = new Map(RUNTIME_MODULES.map((m) => [m.id, m]));
+// fake runtime 仅测试/演示用：显式开关，避免误入 capabilities 上报。
+export function fakeRuntimeEnabled() {
+    return process.env.BOTLEARN_DAEMON_ENABLE_FAKE_RUNTIME === "1";
+}
+export function getRuntimeModule(id) {
+    return BY_ID.get(id) ?? null;
+}
+export function listRuntimeIds(opts = {}) {
+    return RUNTIME_MODULES.filter((m) => opts.includeHidden || !m.hidden).map((m) => m.id);
+}
+export function envVarForRuntime(id) {
+    const mod = getRuntimeModule(id);
+    if (mod?.envVar)
+        return mod.envVar;
+    return `BOTLEARN_${id.toUpperCase().replace(/-/g, "_")}_BIN`;
+}
+export function createRuntime(id) {
+    const mod = getRuntimeModule(id);
+    if (!mod)
+        throw new Error(`unknown runtime: ${id}`);
+    return mod.create();
+}
+export async function detectRuntimes(opts = {}) {
+    const out = [];
+    for (const mod of RUNTIME_MODULES) {
+        if (mod.hidden && !opts.includeHidden)
+            continue;
+        let result;
+        try {
+            result = await mod.probe();
+        }
+        catch {
+            result = { available: false };
+        }
+        const entry = {
+            id: mod.id,
+            displayName: mod.displayName,
+            binary: mod.binary,
+            result,
+        };
+        if (mod.installHint)
+            entry.installHint = mod.installHint;
+        out.push(entry);
+    }
+    return out;
+}
+/** capabilities 上报用：available 且非 hidden；fake 仅在显式启用时加入。 */
+export async function detectAvailableRuntimeIds() {
+    const entries = await detectRuntimes();
+    const ids = entries.filter((e) => e.result.available).map((e) => e.id);
+    if (fakeRuntimeEnabled())
+        ids.push(fakeModule.id);
+    return ids;
+}

package/dist/runtimes/kimi.d.ts

@@ -0,0 +1,35 @@
+import { NdjsonStreamAdapter, type NdjsonEventCtx } from "./ndjson-stream.js";
+import { type ProbeDeps } from "./probe.js";
+import { type EngineRunOptions, type EngineRunResult } from "./engine.js";
+import type { Logger } from "../log.js";
+import type { RuntimeModule, RuntimeProbe } from "../types.js";
+/** 在 PATH 上解析 kimi 可执行文件。 */
+export declare function resolveKimiCommand(deps?: ProbeDeps): string | null;
+/** 探测 kimi CLI 是否安装并读取版本。 */
+export declare function probeKimi(deps?: ProbeDeps): RuntimeProbe;
+/**
+ * Kimi CLI adapter — spawn：
+ *
+ *   kimi [--work-dir <cwd>] --print --output-format stream-json --session <sid> --afk --prompt <text>
+ *
+ * `--session <sid>` 会 resume 已有会话或用该 id 新建会话，所以首轮由
+ * adapter 在客户端生成 UUID 并持久化供后续轮次使用。kimi 没有 Codex 式的
+ * per-invocation AGENTS.md 载体，动态 systemContext 走 prompt 的
+ * <system-reminder> 前缀。注意 kimi 会冻结每个会话的系统提示 ——
+ * 若复用会话，systemContext 更新可能需要新会话才生效。
+ */
+export declare class KimiAdapter extends NdjsonStreamAdapter {
+    readonly id: "kimi-cli";
+    private readonly explicitBinary;
+    private resolvedBinary;
+    constructor(opts?: {
+        binary?: string;
+        logger?: Logger;
+    });
+    run(opts: EngineRunOptions): Promise<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 kimiCliModule: RuntimeModule;

package/dist/runtimes/kimi.js

@@ -0,0 +1,335 @@
+// 权限姿态：--afk（自动批准全部工具调用）——daemon 无审批中继，
+// 且每个 run 的工作区已按 agent_run_id 隔离。
+import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { NdjsonStreamAdapter } from "./ndjson-stream.js";
+import { readCommandVersion, resolveCommandOnPath } from "./probe.js";
+import { wrapEngineAdapter, } from "./engine.js";
+function isValidKimiSessionId(sessionId) {
+    if (sessionId.length === 0 || sessionId.length > 512)
+        return false;
+    if (sessionId.startsWith("-"))
+        return false;
+    for (const ch of sessionId) {
+        const code = ch.codePointAt(0);
+        if (code === undefined || code < 0x20 || code === 0x7f)
+            return false;
+    }
+    return true;
+}
+function invalidKimiSessionIdError() {
+    return "kimi-cli: invalid sessionId (expected non-control text not starting with '-')";
+}
+const KIMI_EXTRA_FLAGS_WITH_VALUE = new Set([
+    "--add-dir",
+    "--agent",
+    "--agent-file",
+    "--config",
+    "--config-file",
+    "--max-ralph-iterations",
+    "--max-retries-per-step",
+    "--max-steps-per-turn",
+    "--mcp-config",
+    "--mcp-config-file",
+    "--model",
+    "--skills-dir",
+    "-m",
+]);
+const KIMI_EXTRA_BOOLEAN_FLAGS = new Set([
+    "--afk",
+    "--auto-approve",
+    "--debug",
+    "--no-thinking",
+    "--plan",
+    "--thinking",
+    "--verbose",
+    "--yes",
+    "--yolo",
+    "-y",
+]);
+// adapter 独占的 flag：daemon 依赖 kimi 的非交互 stream-json 契约、
+// cwd 隔离、prompt 位置与会话路由，不允许 extraArgs 覆盖。
+const KIMI_ADAPTER_OWNED_FLAGS = new Set([
+    "--acp",
+    "--command",
+    "--continue",
+    "--final-message-only",
+    "--help",
+    "--input-format",
+    "--output-format",
+    "--print",
+    "--prompt",
+    "--quiet",
+    "--resume",
+    "--session",
+    "--version",
+    "--wire",
+    "--work-dir",
+    "-C",
+    "-S",
+    "-V",
+    "-c",
+    "-h",
+    "-p",
+    "-r",
+    "-w",
+]);
+const kimiWorkDirSupport = new Map();
+function flagName(arg) {
+    if (!arg.startsWith("-"))
+        return arg;
+    const eq = arg.indexOf("=");
+    return eq === -1 ? arg : arg.slice(0, eq);
+}
+function nextValue(args, index) {
+    const next = args[index + 1];
+    if (typeof next !== "string")
+        return undefined;
+    if (!next.startsWith("-"))
+        return next;
+    // 负数值（如 -1）不是 flag。
+    return /^-\d/.test(next) ? next : undefined;
+}
+// allowlist 式净化（四个 CLI adapter 中最严格）：未知 flag 连同其值一起丢弃。
+function sanitizeKimiExtraArgs(extraArgs) {
+    if (!extraArgs?.length)
+        return [];
+    const out = [];
+    for (let i = 0; i < extraArgs.length; i += 1) {
+        const arg = extraArgs[i];
+        const name = flagName(arg);
+        if (KIMI_ADAPTER_OWNED_FLAGS.has(name)) {
+            if (!arg.includes("=") && nextValue(extraArgs, i) !== undefined)
+                i += 1;
+            continue;
+        }
+        if (KIMI_EXTRA_FLAGS_WITH_VALUE.has(name)) {
+            if (arg.includes("=")) {
+                out.push(arg);
+                continue;
+            }
+            const value = nextValue(extraArgs, i);
+            if (value !== undefined) {
+                out.push(arg, value);
+                i += 1;
+            }
+            // 缺值的 value flag 直接丢弃，避免传出非法 argv。
+            continue;
+        }
+        if (KIMI_EXTRA_BOOLEAN_FLAGS.has(name)) {
+            out.push(arg);
+            continue;
+        }
+        if (arg.startsWith("-") && !arg.includes("=") && nextValue(extraArgs, i) !== undefined) {
+            i += 1;
+        }
+    }
+    return out;
+}
+function parseKimiVersionMajor(version) {
+    const match = version?.match(/\b(\d+)\.(\d+)\.(\d+)\b/);
+    if (!match)
+        return null;
+    return Number.parseInt(match[1], 10);
+}
+// `--work-dir` 只有较新的 kimi 才支持：用 `--help` 输出探测（5s 超时），
+// 探测失败时退回「主版本号 ≥ 1」的启发式；结果按二进制路径缓存。
+function probeKimiSupportsWorkDir(command) {
+    const cached = kimiWorkDirSupport.get(command);
+    if (cached !== undefined)
+        return cached;
+    let supported = false;
+    try {
+        const help = execFileSync(command, ["--help"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 5000,
+        });
+        supported = /(?:^|\s)--work-dir(?:[=\s,]|$)/.test(help);
+    }
+    catch {
+        const major = parseKimiVersionMajor(readCommandVersion(command));
+        supported = major !== null && major >= 1;
+    }
+    kimiWorkDirSupport.set(command, supported);
+    return supported;
+}
+/** 在 PATH 上解析 kimi 可执行文件。 */
+export function resolveKimiCommand(deps = {}) {
+    return resolveCommandOnPath("kimi", deps);
+}
+/** 探测 kimi CLI 是否安装并读取版本。 */
+export function probeKimi(deps = {}) {
+    const command = resolveKimiCommand(deps);
+    if (!command)
+        return { available: false };
+    return {
+        available: true,
+        path: command,
+        version: readCommandVersion(command, [], deps) ?? undefined,
+    };
+}
+/**
+ * Kimi CLI adapter — spawn：
+ *
+ *   kimi [--work-dir <cwd>] --print --output-format stream-json --session <sid> --afk --prompt <text>
+ *
+ * `--session <sid>` 会 resume 已有会话或用该 id 新建会话，所以首轮由
+ * adapter 在客户端生成 UUID 并持久化供后续轮次使用。kimi 没有 Codex 式的
+ * per-invocation AGENTS.md 载体，动态 systemContext 走 prompt 的
+ * <system-reminder> 前缀。注意 kimi 会冻结每个会话的系统提示 ——
+ * 若复用会话，systemContext 更新可能需要新会话才生效。
+ */
+export class KimiAdapter extends NdjsonStreamAdapter {
+    id = "kimi-cli";
+    explicitBinary;
+    resolvedBinary = null;
+    constructor(opts) {
+        super(opts?.logger);
+        this.explicitBinary = opts?.binary ?? process.env.BOTLEARN_KIMI_CLI_BIN;
+    }
+    async run(opts) {
+        if (opts.sessionId && !isValidKimiSessionId(opts.sessionId)) {
+            // 返回空 newSessionId 作为删除信号（不抛），让调用方丢弃过期条目。
+            return { text: "", newSessionId: "", error: invalidKimiSessionIdError() };
+        }
+        const sessionId = opts.sessionId || randomUUID();
+        return super.run({ ...opts, sessionId });
+    }
+    resolveBinary() {
+        if (this.explicitBinary)
+            return this.explicitBinary;
+        if (this.resolvedBinary)
+            return this.resolvedBinary;
+        this.resolvedBinary = resolveKimiCommand() ?? "kimi";
+        return this.resolvedBinary;
+    }
+    buildArgs(opts) {
+        const sessionId = opts.sessionId || randomUUID();
+        if (!isValidKimiSessionId(sessionId))
+            throw new Error(invalidKimiSessionIdError());
+        const args = ["--print", "--output-format", "stream-json", "--session", sessionId, "--afk"];
+        if (probeKimiSupportsWorkDir(this.resolveBinary()))
+            args.unshift("--work-dir", opts.cwd);
+        args.push(...sanitizeKimiExtraArgs(opts.extraArgs));
+        args.push("--prompt", promptWithSystemContext(opts.text, opts.systemContext));
+        return args;
+    }
+    spawnEnv(opts) {
+        return {
+            ...super.spawnEnv(opts),
+            // 无论用户终端设置如何都保持 stream-json 干净。
+            FORCE_COLOR: "0",
+            NO_COLOR: "1",
+        };
+    }
+    handleEvent(raw, ctx) {
+        const obj = raw;
+        const status = kimiStatusEvent(obj);
+        if (status)
+            ctx.emitStatus(status);
+        ctx.emitBlock(normalizeBlock(obj, ctx.seq));
+        const sessionId = kimiSessionId(obj);
+        if (sessionId)
+            ctx.state.newSessionId = sessionId;
+        if (obj.role === "assistant") {
+            const text = extractText(obj.content);
+            if (text) {
+                ctx.appendAssistantText(text);
+                // 每条 assistant 消息整体覆盖 finalText —— 最后一条获胜。
+                ctx.state.finalText = text;
+            }
+            return;
+        }
+        const err = kimiErrorText(obj);
+        if (err)
+            ctx.state.errorText = err;
+    }
+}
+function promptWithSystemContext(text, systemContext) {
+    if (!systemContext)
+        return text;
+    return `<system-reminder>\n${systemContext}\n</system-reminder>\n\n${text}`;
+}
+function extractText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((part) => part?.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("");
+}
+function hasThinking(content) {
+    return Array.isArray(content)
+        ? content.some((part) => part?.type === "think" && typeof part.think === "string" && part.think)
+        : false;
+}
+function firstToolName(toolCalls) {
+    const name = toolCalls?.find((t) => typeof t.function?.name === "string")?.function?.name;
+    return name || "tool";
+}
+function kimiSessionId(obj) {
+    return typeof obj.session_id === "string" && obj.session_id ? obj.session_id : undefined;
+}
+function kimiErrorText(obj) {
+    if (typeof obj.error === "string" && obj.error)
+        return obj.error;
+    if (obj.error && typeof obj.error === "object") {
+        const message = obj.error.message;
+        if (typeof message === "string" && message)
+            return message;
+    }
+    if (obj.type === "error" && typeof obj.message === "string" && obj.message) {
+        return obj.message;
+    }
+    if (obj.severity === "error") {
+        return [obj.title, obj.body].filter(Boolean).join(": ") || "kimi-cli error";
+    }
+    return undefined;
+}
+function kimiStatusEvent(obj) {
+    if (obj.role === "assistant" && hasThinking(obj.content)) {
+        return { kind: "thinking", phase: "started", label: "Thinking" };
+    }
+    if (obj.role === "assistant" && obj.tool_calls?.length) {
+        return { kind: "thinking", phase: "updated", label: firstToolName(obj.tool_calls) };
+    }
+    if (obj.role === "assistant" && extractText(obj.content)) {
+        return { kind: "thinking", phase: "stopped" };
+    }
+    if (obj.role === "tool") {
+        return { kind: "thinking", phase: "updated", label: "Tool result" };
+    }
+    return undefined;
+}
+function normalizeBlock(obj, seq) {
+    let kind = "other";
+    if (obj.role === "assistant") {
+        if (obj.tool_calls?.length)
+            kind = "tool_use";
+        else if (extractText(obj.content))
+            kind = "assistant_text";
+        else if (hasThinking(obj.content))
+            kind = "other";
+    }
+    else if (obj.role === "tool") {
+        kind = "tool_result";
+    }
+    else if (obj.file_path && typeof obj.content === "string") {
+        kind = "other";
+    }
+    else if (obj.category || obj.severity) {
+        kind = "system";
+    }
+    return { raw: obj, kind, seq };
+}
+export const kimiCliModule = {
+    id: "kimi-cli",
+    displayName: "Kimi CLI",
+    binary: "kimi",
+    envVar: "BOTLEARN_KIMI_CLI_BIN",
+    probe: async () => probeKimi(),
+    create: () => wrapEngineAdapter("kimi-cli", new KimiAdapter()),
+};

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

@@ -0,0 +1,51 @@
+import { type EngineAdapter, type EngineRunOptions, type EngineRunResult, type RuntimeStatusEvent, type StreamBlock } from "./engine.js";
+import type { Logger } from "../log.js";
+/** 单轮执行期间穿过事件回调的可变状态；基类据此组装最终 EngineRunResult。 */
+export interface NdjsonRunState {
+    /** 供 resume 持久化的会话 id。以传入的 sessionId 起始。 */
+    newSessionId: string;
+    /** 终态 "result"/"completed" 事件报告的最终文本（若有）。 */
+    finalText: string;
+    /** 流式 assistant 文本块；finalText 为空时拼接兜底。 */
+    assistantTextChunks: string[];
+    assistantTextBytes: number;
+    /** 命中单轮文本上限后为 true；后续块直接丢弃。 */
+    assistantTextCapped: boolean;
+    costUsd?: number;
+    errorText?: string;
+    /** 部分 CLI 会报告用量（如 Codex turn.completed.usage）；仅本地诊断用。 */
+    usage?: {
+        inputCacheHitTokens?: number;
+        inputCacheMissTokens?: number;
+        outputTokens?: number;
+    };
+}
+/** ndjson 分发循环递给子类的逐事件上下文。 */
+export interface NdjsonEventCtx {
+    state: NdjsonRunState;
+    /** 本轮 1-based 序号，与 onBlock 看到的一致。 */
+    seq: number;
+    emitBlock: (block: StreamBlock) => void;
+    /** 推入流式 assistant 文本（尊重单轮字节上限）；子类勿直接 push state。 */
+    appendAssistantText: (text: string) => void;
+    /** 转发 typing/thinking 状态事件；回调抛错会被吞掉。 */
+    emitStatus: (event: RuntimeStatusEvent) => void;
+}
+/**
+ * 输出 newline-delimited JSON 的 CLI adapter 公共骨架。子类只需提供：
+ *   - resolveBinary() — 要 spawn 的可执行文件
+ *   - buildArgs()     — argv 尾部（不含二进制本身）
+ *   - handleEvent()   — 如何解释一条已解析的 JSON 事件
+ * spawn、abort、stderr 收集、行切分与 exit-code 错误合成由基类处理。
+ */
+export declare abstract class NdjsonStreamAdapter implements EngineAdapter {
+    abstract readonly id: string;
+    protected readonly log: Logger;
+    constructor(logger?: Logger);
+    protected abstract resolveBinary(opts: EngineRunOptions): string;
+    protected abstract buildArgs(opts: EngineRunOptions): string[];
+    protected abstract handleEvent(obj: unknown, ctx: NdjsonEventCtx): void;
+    /** 覆盖以调整 env（FORCE_COLOR=0、NO_COLOR=1 等）。 */
+    protected spawnEnv(_opts: EngineRunOptions): NodeJS.ProcessEnv;
+    run(opts: EngineRunOptions): Promise<EngineRunResult>;
+}