cotutor 0.2.0 → 0.3.0

package/dist/brain/cli/stream-json.js

@@ -0,0 +1,86 @@
+const blocks = (c) => (Array.isArray(c) ? c : []);
+/** 结果块的文字:字符串原样,块数组拼各块的 text */
+export const blockText = (c) => (typeof c === 'string' ? c : blocks(c).map((b) => (typeof b.text === 'string' ? b.text : '')).join(''));
+const num = (v) => (typeof v === 'number' ? v : undefined);
+/** 输入 = 没命中的 + 缓存读 + 缓存写;一样都没报 → undefined */
+const inputOf = (u) => [u.input_tokens, u.cache_read_input_tokens, u.cache_creation_input_tokens].reduce((s, v) => (typeof v === 'number' ? (s ?? 0) + v : s), undefined);
+function finalOf(e) {
+    const failed = Boolean(e.is_error) || Boolean(e.subtype && e.subtype !== 'success');
+    const text = typeof e.result === 'string' && e.result.trim() ? e.result.trim() : null;
+    const u = e.usage;
+    const inTokens = u ? inputOf(u) : undefined;
+    return {
+        ok: !failed,
+        text,
+        reason: failed ? (e.subtype && e.subtype !== 'success' ? e.subtype : (e.terminal_reason ?? '未知')) : null,
+        numTurns: num(e.num_turns),
+        ...(num(u?.output_tokens) !== undefined ? { outTokens: num(u?.output_tokens) } : {}),
+        ...(inTokens !== undefined ? { inTokens } : {}),
+    };
+}
+export function parseStreamJson(line) {
+    if (!line.trim())
+        return [];
+    let e;
+    try {
+        e = JSON.parse(line);
+    }
+    catch {
+        return [];
+    }
+    if (!e || typeof e !== 'object')
+        return [];
+    const out = [];
+    if (typeof e.session_id === 'string' && e.session_id)
+        out.push({ kind: 'session', id: e.session_id });
+    const sub = typeof e.parent_tool_use_id === 'string' && e.parent_tool_use_id.length > 0;
+    switch (e.type) {
+        case 'system':
+            if (Array.isArray(e.tools))
+                out.push({ kind: 'init', tools: e.tools.filter((t) => typeof t === 'string') });
+            break;
+        case 'stream_event': {
+            const ev = e.event;
+            if (ev?.type === 'message_start')
+                out.push({ kind: 'start', sub });
+            else if (ev?.type === 'content_block_delta' && ev.delta?.type === 'text_delta' && typeof ev.delta.text === 'string' && ev.delta.text)
+                out.push({ kind: 'delta', text: ev.delta.text, sub });
+            else if (ev?.type === 'content_block_delta' && ev.delta?.type === 'thinking_delta')
+                out.push({ kind: 'thinking', sub });
+            break;
+        }
+        case 'assistant': {
+            if (!Array.isArray(e.message?.content))
+                break;
+            const parts = [];
+            for (const b of blocks(e.message.content)) {
+                if (b.type === 'text' && typeof b.text === 'string')
+                    parts.push({ type: 'text', text: b.text });
+                else if (b.type === 'tool_use' && b.name)
+                    parts.push({ type: 'tool', tool: { ...(b.id ? { id: b.id } : {}), name: b.name, ...(b.input ? { input: b.input } : {}) } });
+            }
+            const u = e.message.usage;
+            const id = typeof e.message.id === 'string' ? e.message.id : typeof e.uuid === 'string' ? e.uuid : null;
+            const inTok = u ? inputOf(u) : undefined;
+            out.push({ kind: 'assistant', parts, sub, ...(u && id && inTok !== undefined ? { usage: { id, in: inTok, out: num(u.output_tokens) ?? 0, cached: num(u.cache_read_input_tokens) ?? 0 } } : {}) });
+            break;
+        }
+        case 'user': {
+            const results = [];
+            for (const b of blocks(e.message?.content))
+                if (b.type === 'tool_result' && b.tool_use_id)
+                    results.push({ id: b.tool_use_id, ok: !b.is_error, text: blockText(b.content) });
+            if (results.length)
+                out.push({ kind: 'results', results, sub });
+            break;
+        }
+        case 'result':
+            out.push({ kind: 'result', final: finalOf(e) });
+            break;
+    }
+    return out;
+}
+/** stream-json 输入的一条用户消息(`--input-format stream-json` 一行一条) */
+export function streamJsonUserMessage(prompt) {
+    return `${JSON.stringify({ type: 'user', message: { role: 'user', content: prompt } })}\n`;
+}

package/dist/brain/cli/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * CLI 适配器:一个 agent CLI 一个文件,写「这个 CLI 怎么说话」——
+ * 输出流怎么读、消息怎么写进 stdin、工具叫什么怎么关、思考量怎么调、起进程要什么环境、出厂模板长什么样。
+ * 选哪个模型、预算、时限还在 cotutor.json 的运行时模板里(数据);应用的其余部分只认这里的统一事件,不认哪家的 JSON。
+ * 接一个新 CLI:照 qwen.ts 写一个文件,在 index.ts 的 ADAPTERS 里登记。
+ */
+import type { CliRuntime, Policy } from '../../schema/index.ts';
+/** 工具的类别:应用要知道「读了哪个文件」「是不是用技能回读板书写法」时按类别认,不比工具名 */
+export type ToolKind = 'read' | 'shell' | 'search' | 'edit' | 'skill' | 'other';
+/**
+ * 这轮带不带工具(政策 tools 与消息种类定):off 一个不带;read 只读(看照片、读 vault、查教材);
+ * on 与 read 一样只读,不提供 shell 与写入工具
+ */
+export type ToolSet = 'off' | 'read' | 'on';
+export interface ToolUse {
+    /** 和工具结果配对用;有的 CLI 可能不给 */
+    id?: string;
+    name: string;
+    input?: Record<string, unknown>;
+}
+export interface ToolResult {
+    id: string;
+    ok: boolean;
+    /** 结果的文字(图片等非文字块不算) */
+    text: string;
+}
+/** 一条整的回复里的一段:正文或一次工具调用 */
+export type AssistantPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool';
+    tool: ToolUse;
+};
+/** 一条回复的正文段 / 工具调用 */
+export declare const textsOf: (parts: readonly AssistantPart[]) => string[];
+export declare const toolsOf: (parts: readonly AssistantPart[]) => ToolUse[];
+/** 一次模型请求的 token:in 含缓存读、缓存写,cached 是其中命中缓存的;id 是那条回复的消息 id */
+export interface RequestUsage {
+    id: string;
+    in: number;
+    out: number;
+    cached: number;
+}
+/** 一轮的收尾 */
+export interface CliFinal {
+    ok: boolean;
+    /** 最终正文(孩子视图只看它);没有就是 null */
+    text: string | null;
+    /** 不 ok 时的原因 */
+    reason: string | null;
+    numTurns?: number;
+    /** 这一轮的 token:输入(含缓存读、缓存写)与输出;记账按它(报的钱数不认,src/shared/tokens.ts)。
+     *  CLI 收尾报的可能是整个会话的累计(qwen 续会话时就是),parseTranscript 有每次请求的 usage 就按它们加总 */
+    inTokens?: number;
+    outTokens?: number;
+    /** 输入里命中缓存的那部分(API 运行时报;CLI 有每次请求的 usage 时也有) */
+    cachedTokens?: number;
+    /** 这一轮最后一次请求的输入 = 这一轮结束时上下文多大(API 运行时报;过 32k 整段压缩看它) */
+    contextTokens?: number;
+}
+/**
+ * 统一事件:一行输出读出零到几条。sub = 来自子代理(老师不派子代理,有也不算老师的话)。
+ * - session:这行带着会话 id(取第一次见到的)
+ * - init:进程起来报的工具表(用来核对「不带工具」真的一个没有)
+ * - start:开始新的一条回复(增量模式)
+ * - delta:回复正文的一小段(增量模式)
+ * - thinking:模型在想(增量模式,只说明模型开始回了)
+ * - assistant:一条整的回复:正文段与工具调用,按原来的先后;usage = 这一次请求自己的 token(消息 id 去重用,同一条回复可能分几行出)
+ * - results:工具结果
+ * - result:一轮收尾
+ */
+export type CliEvent = {
+    kind: 'session';
+    id: string;
+} | {
+    kind: 'init';
+    tools: string[];
+} | {
+    kind: 'start';
+    sub: boolean;
+} | {
+    kind: 'delta';
+    text: string;
+    sub: boolean;
+} | {
+    kind: 'thinking';
+    sub: boolean;
+} | {
+    kind: 'assistant';
+    parts: AssistantPart[];
+    sub: boolean;
+    usage?: RequestUsage;
+} | {
+    kind: 'results';
+    results: ToolResult[];
+    sub: boolean;
+} | {
+    kind: 'result';
+    final: CliFinal;
+};
+/** 运行时模板里与适配器有关的占位能拿到的值 */
+export interface PlanContext {
+    /** workspace 根(适配器的私有文件放在它的 .cotutor/ 下);测试与不关心的调用可以不给 */
+    root?: string;
+    effort: Policy['effort'];
+    /** 这轮带不带工具 */
+    tools: ToolSet;
+}
+export interface CliAdapter {
+    /** 适配器名:运行时的 cli 字段,或 run[0] 的文件名 */
+    name: string;
+    /** 一行原始输出 → 统一事件;读不懂的行返回 [] */
+    parse(line: string): CliEvent[];
+    /** stdin 模式(运行时 stdin: "stream-json")下写进 stdin 的那一行用户消息,带换行 */
+    stdinMessage(prompt: string): string;
+    /** 模板里 `{tools}` 填什么(一个参数里的文字) */
+    toolList(set: ToolSet): string;
+    /** 模板里独占一个参数的 `{toolArgs}` 展开成哪几个参数(可以是零个);readDirs = 这轮该读得到的目录(workspace 根、vault),会话 cwd 是老师目录,它们在 cwd 外面 */
+    toolArgs(set: ToolSet, ctx: {
+        readDirs: readonly string[];
+    }): string[];
+    toolKind(name: string): ToolKind;
+    /** 这轮带或不带工具时,进程起来报的工具表(init 事件)应该正好是哪几样;多出来的记提醒(CLI 升版本会带进新工具)。不给 = 不核对 */
+    expectedTools?(set: ToolSet): readonly string[];
+    /** 起进程前把这个 CLI 在 workspace 里要的机器文件备好(幂等,内容一样就不写) */
+    prepare?(root: string): Promise<void>;
+    /** 由这轮的计划定下来的环境变量(进预热的比对:变了的备用进程不能用);没有就不写 */
+    planEnv?(ctx: PlanContext): Record<string, string>;
+    /** 起进程前最后过一遍环境(认证等);不改就原样返回 */
+    env(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+    /** cotutor doctor 查这个 CLI 时多看几样(version 是 `--version` 的第一行);不给就只查装没装 */
+    check?(ctx: {
+        version: string;
+        env: NodeJS.ProcessEnv;
+    }): {
+        name: string;
+        ok: boolean;
+        detail: string;
+        fix?: string;
+    }[];
+    /** 出厂运行时模板:键是运行时名 */
+    runtimes(): Record<string, CliRuntime>;
+}

package/dist/brain/cli/types.js

@@ -0,0 +1,3 @@
+/** 一条回复的正文段 / 工具调用 */
+export const textsOf = (parts) => parts.flatMap((p) => (p.type === 'text' ? [p.text] : []));
+export const toolsOf = (parts) => parts.flatMap((p) => (p.type === 'tool' ? [p.tool] : []));

package/dist/brain/cli/warm.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 预热:消息走 stdin 的运行时,下一轮的老师进程提前起好、在 stdin 上等着;
+ * 孩子开口时对得上就接过来写消息,省掉起进程与读会话(真跑冷起中位 1.8 秒,预热约 0.07 秒)。
+ * 一位老师两个位置:resume(接某个话题的会话)与 fresh(新开会话:新话题、接着上次)。
+ * 对得上 = argv、适配器定的环境变量、cwd、日期、**这个话题**末条 job 都和它起来时一样(fresh 没有会话,末条记 null):
+ * argv 管换话题 / 会话 / 老师正文 / effort / cotutor.json,末条 job 管「会话被别的进程写过」(它起来时读的会话就旧了,拿它写会分叉)。
+ * 对不上、闲置超时、自己退了,都杀掉,调用方走冷起。开口前吐的字节先攒着,接过来时交出去。
+ */
+import { type ChildProcess } from 'node:child_process';
+/** 备用进程闲置多久杀掉(闲着不花钱,只占内存,真跑一个约 64MB) */
+export declare const WARM_IDLE_MS: number;
+/** resume:接某个话题的会话;fresh:新开会话 */
+export type Slot = 'resume' | 'fresh';
+export declare const SLOTS: readonly Slot[];
+/** 对得上才用:argv、适配器定的环境变量、cwd、日期、这个话题末条 job(fresh 为 null) */
+export interface SpareKey {
+    argv: readonly string[];
+    /** 计划里适配器定的环境变量(qwen 按 effort 选的配置之类);不给当空 */
+    env?: Readonly<Record<string, string>>;
+    cwd: string;
+    date: string;
+    lastJob: string | null;
+}
+export interface Spare {
+    child: ChildProcess;
+    /** 起来的时刻(Date.now()) */
+    bornAt: number;
+    /** 接过来之前 stdout / stderr 吐的 */
+    stdout: Buffer[];
+    stderr: Buffer[];
+    /** 进程已经 close(或起不来)了:接手之前就发生的 close 接手的等不到,看这个 */
+    closed: () => boolean;
+}
+export declare class WarmPool {
+    private readonly held;
+    private readonly idleMs;
+    constructor(opts?: {
+        idleMs?: number;
+    });
+    /** 这位老师这个位置(不给 = 任一位置)有没有活着的备用进程 */
+    has(tutor: string, slot?: Slot): boolean;
+    /** 在这个位置起一个备用进程;已有一个对得上的就不动,对不上的先杀 */
+    warm(tutor: string, slot: Slot, key: SpareKey, env: NodeJS.ProcessEnv): void;
+    /**
+     * 接过这个位置的备用进程:对得上就交出去(不再归池子管);对不上 / 已经退了就杀掉,返回 null。没有也返回 null。另一个位置不动。
+     * 交出去时 stdout / stderr 摘掉池子的监听并**暂停**:接手的挂好监听、先喂攒下的,再 resume(中间一个字节不丢)。
+     * 池子挂的 error / close 监听留着(接手之前进程出错不至于成了没人接的 error 事件);进程可能在接手之前就退了,接手的看 closed()。
+     */
+    claim(tutor: string, slot: Slot, key: SpareKey): Spare | null;
+    /** 杀掉这位老师这个位置(不给 = 两个位置)的备用进程 */
+    drop(tutor: string, slot?: Slot): void;
+    dropAll(): void;
+}

package/dist/brain/cli/warm.js

@@ -0,0 +1,103 @@
+/**
+ * 预热:消息走 stdin 的运行时,下一轮的老师进程提前起好、在 stdin 上等着;
+ * 孩子开口时对得上就接过来写消息,省掉起进程与读会话(真跑冷起中位 1.8 秒,预热约 0.07 秒)。
+ * 一位老师两个位置:resume(接某个话题的会话)与 fresh(新开会话:新话题、接着上次)。
+ * 对得上 = argv、适配器定的环境变量、cwd、日期、**这个话题**末条 job 都和它起来时一样(fresh 没有会话,末条记 null):
+ * argv 管换话题 / 会话 / 老师正文 / effort / cotutor.json,末条 job 管「会话被别的进程写过」(它起来时读的会话就旧了,拿它写会分叉)。
+ * 对不上、闲置超时、自己退了,都杀掉,调用方走冷起。开口前吐的字节先攒着,接过来时交出去。
+ */
+import { spawn } from 'node:child_process';
+/** 备用进程闲置多久杀掉(闲着不花钱,只占内存,真跑一个约 64MB) */
+export const WARM_IDLE_MS = 60 * 60_000;
+export const SLOTS = ['resume', 'fresh'];
+const keyOf = (k) => JSON.stringify([k.argv, Object.entries(k.env ?? {}).sort(), k.cwd, k.date, k.lastJob]);
+const at = (tutor, slot) => `${tutor}\n${slot}`;
+export class WarmPool {
+    held = new Map();
+    idleMs;
+    constructor(opts = {}) {
+        this.idleMs = opts.idleMs ?? WARM_IDLE_MS;
+    }
+    /** 这位老师这个位置(不给 = 任一位置)有没有活着的备用进程 */
+    has(tutor, slot) {
+        return (slot ? [slot] : SLOTS).some((s) => {
+            const h = this.held.get(at(tutor, s));
+            return Boolean(h && !h.exited);
+        });
+    }
+    /** 在这个位置起一个备用进程;已有一个对得上的就不动,对不上的先杀 */
+    warm(tutor, slot, key, env) {
+        const id = at(tutor, slot);
+        const k = keyOf(key);
+        const cur = this.held.get(id);
+        if (cur && !cur.exited && cur.key === k)
+            return;
+        this.drop(tutor, slot);
+        const child = spawn(key.argv[0], key.argv.slice(1), { cwd: key.cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
+        const h = { child, bornAt: Date.now(), stdout: [], stderr: [], key: k, exited: false, idle: setTimeout(() => this.drop(tutor, slot), this.idleMs) };
+        h.idle.unref();
+        child.stdout?.on('data', (c) => h.stdout.push(c));
+        child.stderr?.on('data', (c) => h.stderr.push(c));
+        // 写 stdin 时进程已经退了(EPIPE)不该把服务带倒
+        child.stdin?.on('error', () => { });
+        const gone = () => {
+            h.exited = true;
+            clearTimeout(h.idle);
+            if (this.held.get(id) === h)
+                this.held.delete(id);
+        };
+        child.once('error', gone);
+        child.once('close', gone);
+        this.held.set(id, h);
+    }
+    /**
+     * 接过这个位置的备用进程:对得上就交出去(不再归池子管);对不上 / 已经退了就杀掉,返回 null。没有也返回 null。另一个位置不动。
+     * 交出去时 stdout / stderr 摘掉池子的监听并**暂停**:接手的挂好监听、先喂攒下的,再 resume(中间一个字节不丢)。
+     * 池子挂的 error / close 监听留着(接手之前进程出错不至于成了没人接的 error 事件);进程可能在接手之前就退了,接手的看 closed()。
+     */
+    claim(tutor, slot, key) {
+        const id = at(tutor, slot);
+        const h = this.held.get(id);
+        if (!h)
+            return null;
+        this.held.delete(id);
+        clearTimeout(h.idle);
+        if (h.exited || h.key !== keyOf(key)) {
+            kill(h.child);
+            return null;
+        }
+        for (const s of [h.child.stdout, h.child.stderr]) {
+            s?.removeAllListeners('data');
+            s?.pause();
+        }
+        return { child: h.child, bornAt: h.bornAt, stdout: h.stdout, stderr: h.stderr, closed: () => h.exited };
+    }
+    /** 杀掉这位老师这个位置(不给 = 两个位置)的备用进程 */
+    drop(tutor, slot) {
+        for (const s of slot ? [slot] : SLOTS) {
+            const id = at(tutor, s);
+            const h = this.held.get(id);
+            if (!h)
+                continue;
+            this.held.delete(id);
+            clearTimeout(h.idle);
+            kill(h.child);
+        }
+    }
+    dropAll() {
+        for (const h of this.held.values()) {
+            clearTimeout(h.idle);
+            kill(h.child);
+        }
+        this.held.clear();
+    }
+}
+/** 关 stdin 让它自己退;2 秒还在就 SIGKILL */
+function kill(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    child.stdin?.end();
+    child.kill('SIGTERM');
+    setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+        child.kill('SIGKILL'); }, 2000).unref();
+}

package/dist/brain/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 脑执行:一轮教学里「让脑想、写出正文」的那一步。
+ * runner 拼好上下文包与系统提示交到这里;这里起老师(或接预热好的)、读输出、断流接着跑,随流回报正文与工具,收尾给出整轮的转录。
+ * 执行完不等于这一轮交付完:板书解析、配音、记忆与日记的收尾归 runner。
+ * 两种实现,按 cotutor.json 里这轮的运行时分:{run, resume} 起 CLI(./cli/run.ts,各家方言在 ./cli/ 的适配器);{api, model} 应用直连模型(./api.ts)。
+ */
+import { type CliEvent } from './cli/adapters.ts';
+import { type RunPlan } from './cli/run-plan.ts';
+import type { ToolCall, Transcript } from './transcript.ts';
+import { type CotutorConfig, type Policy, type Runtime } from '../schema/index.ts';
+import type { ToolSet } from './cli/adapters.ts';
+import type { Slot } from './cli/warm.ts';
+export type { ToolSet } from './cli/adapters.ts';
+export type { Slot } from './cli/warm.ts';
+/**
+ * CLI 那一家给外面用的几样(经 brain 的出口给,外面不直接引 clis/):工具名属于哪一类(家长端看原文、板书写法有没有被读);
+ * 出厂的运行时模板(init 写 cotutor.json);doctor 体检 CLI 运行时用的(退役没有、适配器、读输出、备机器文件、起进程的环境)
+ */
+export { adapterFor, factoryRuntimes, parserOf, prepareCli, processEnv, runtimeIssue, toolKind, type ToolKind } from './cli/adapters.ts';
+export { FACTORY_API_RUNTIMES } from './api.ts';
+/** 一轮要脑做的:哪个运行时、接哪个会话、系统提示的几样、这条消息(上下文包 + 孩子的话)、思考量、工具 */
+export interface BrainRequest {
+    /** 运行时名,缺省 cotutor.json 的 runtimes.default */
+    runtime?: string;
+    /** 接着的会话;null = 新开 */
+    session: {
+        id: string;
+        runtime: string;
+    } | null;
+    agent: string;
+    prompt: string;
+    agentBody?: string;
+    systemBody?: string;
+    boardFile?: string;
+    effort?: Policy['effort'];
+    tools: ToolSet;
+    /** 老师该读得到、在会话 cwd 外面的目录 */
+    readDirs: readonly string[];
+    /** 本轮附的照片(绝对路径):API 直接附成图;CLI 不用它,老师按上下文包里的路径自己读 */
+    images?: readonly string[];
+    /** 整段压缩(API 运行时;上一轮结束时上下文过了 32k):之前的模型历史不再发,digest 是应用照索引拼的前情;prompt 这一轮带笔记全文。CLI 不用它 */
+    compact?: {
+        digest: string;
+    };
+    /** 回复停在写成正文的工具调用上了吗(板书的规矩,runner 交进来);CLI 据此 resume 一次告诉老师不会有结果,没给就不查。API 不用它 */
+    stuckOnTool?: (text: string) => boolean;
+}
+/** 接预热好的进程要对得上的:老师目录(进程 cwd)、日期、这个话题末条 job(新开记 null) */
+export interface WarmKey {
+    cwd: string;
+    date: string;
+    lastJob: string | null;
+}
+export interface BrainHooks {
+    /** 起了一次(第一次、断流接着跑、工具调用写成正文后接着跑);warmBornAt = 接过来的预热进程起来的时刻 */
+    onStart(s: {
+        cli: string;
+        runtime: string;
+        resume: boolean;
+        warmBornAt?: number;
+    }): void;
+    /** 当前回复的正文变了(读 BrainRun.text()) */
+    onText(): void;
+    onTool(t: {
+        name: string;
+        sub: boolean;
+    }): void;
+    onStall(s: {
+        idleMs: number;
+        retry: number;
+        kept: number;
+    }): void;
+    /** 进程都退了,还没读日志收尾;at = Date.now() */
+    onExit(at: number): void;
+}
+export interface BrainRun {
+    /** 接的是预热好的进程 */
+    warm: boolean;
+    /** 当前这条回复的正文(断流接着跑的,含被杀那次已经写出的) */
+    text(): string;
+    done: Promise<BrainResult>;
+}
+export interface BrainResult {
+    /** final 总有:进程退了没有收尾的,记成没成(原因指向 err.log) */
+    transcript: Transcript & {
+        final: NonNullable<Transcript['final']>;
+    };
+    /** 这轮用了哪些工具、读了什么(最多 200 条) */
+    tools: ToolCall[];
+    /** 给家长端这一轮的提醒,按出现顺序 */
+    warnings: string[];
+}
+/** 这一轮落在哪:原始输出(CLI 的 stream-json / API 的统一事件)、stderr、这个话题的模型历史(API 用;CLI 的历史在它自己的会话里) */
+export interface BrainFiles {
+    log: string;
+    err: string;
+    history: string;
+}
+export interface BrainExecutor {
+    /** 定这一轮怎么跑。现在就是 CLI 的命令规划(run 文件照记命令行);API 脑进来时再分出共同的 runtime / resume / session 与各家私有的 */
+    plan(req: BrainRequest): RunPlan;
+    /** 这一轮在 workspace 里要的机器文件(qwen 的隔离家目录);备不好照起,原因进 err.log */
+    prepare(plan: RunPlan): Promise<void>;
+    /**
+     * 跑一轮。同步返回:接预热进程在调用的这一拍里(调用方查完 busy 到这里之间不能有 await)。
+     * files:原始输出与 stderr 落哪;stall:断流看门狗
+     */
+    start(req: BrainRequest, plan: RunPlan, ctx: {
+        tutor: string;
+        key: WarmKey;
+        files: BrainFiles;
+        stall: Policy['stall'];
+    }, hooks: BrainHooks): BrainRun;
+    /** 这个运行时能不能预热(消息走 stdin 的才行) */
+    canWarm(runtime: Runtime): boolean;
+    /** 给下一轮起好进程;这个位置已有对得上的就不动 */
+    warm(tutor: string, slot: Slot, plan: RunPlan, key: WarmKey): void;
+    warmed(tutor: string, slot?: Slot): boolean;
+    dropWarm(tutor: string, slot?: Slot): void;
+    /** 杀掉所有预热的进程(测试收尾;服务退出时它们的 stdin 断了会自己退) */
+    close(): void;
+}
+/**
+ * auth:百炼按量 key,知道的话带业务空间 id(API 运行时用;runner 给的是和实时那边同一条查找链);endpoint:测试与探针指到假百炼(…/compatible-mode/v1)
+ */
+export declare function createBrain(opts: {
+    workspace: () => {
+        config: CotutorConfig;
+        root: string;
+    };
+    env?: NodeJS.ProcessEnv;
+    warmIdleMs?: number;
+    auth?: () => {
+        key: string;
+        workspaceId: string | null;
+    } | null;
+    endpoint?: string;
+}): BrainExecutor;
+/** 这个运行时关得住工具吗:关得住的,孩子那轮不带工具时,只有工具才用得上的路径(refs、vault)不进上下文包 */
+export declare function controlsTools(runtime: Runtime): boolean;
+/**
+ * 读一轮的 .log:API 的轮次是一行一条统一事件,CLI 的按运行时的适配器读(运行时后来删了或改了按 stream-json)。
+ * 两种行长得不一样(统一事件以 {"kind": 开头),一行一行认,运行时从 CLI 换成 API 以后,以前的轮次照样读得出
+ */
+export declare function logParser(runtimes: Readonly<Record<string, unknown>>, name: string | undefined): (line: string) => CliEvent[];

package/dist/brain/index.js

@@ -0,0 +1,74 @@
+/**
+ * 脑执行:一轮教学里「让脑想、写出正文」的那一步。
+ * runner 拼好上下文包与系统提示交到这里;这里起老师(或接预热好的)、读输出、断流接着跑,随流回报正文与工具,收尾给出整轮的转录。
+ * 执行完不等于这一轮交付完:板书解析、配音、记忆与日记的收尾归 runner。
+ * 两种实现,按 cotutor.json 里这轮的运行时分:{run, resume} 起 CLI(./cli/run.ts,各家方言在 ./cli/ 的适配器);{api, model} 应用直连模型(./api.ts)。
+ */
+import { controlsTools as cliControlsTools, parserForRuntime } from "./cli/adapters.js";
+import { getRuntime } from "./cli/run-plan.js";
+import { isApiRuntime } from "../schema/index.js";
+import { API_CLI, ApiBrain, parseEventLine } from "./api.js";
+import { CliBrain } from "./cli/run.js";
+/**
+ * CLI 那一家给外面用的几样(经 brain 的出口给,外面不直接引 clis/):工具名属于哪一类(家长端看原文、板书写法有没有被读);
+ * 出厂的运行时模板(init 写 cotutor.json);doctor 体检 CLI 运行时用的(退役没有、适配器、读输出、备机器文件、起进程的环境)
+ */
+export { adapterFor, factoryRuntimes, parserOf, prepareCli, processEnv, runtimeIssue, toolKind } from "./cli/adapters.js";
+export { FACTORY_API_RUNTIMES } from "./api.js";
+/**
+ * auth:百炼按量 key,知道的话带业务空间 id(API 运行时用;runner 给的是和实时那边同一条查找链);endpoint:测试与探针指到假百炼(…/compatible-mode/v1)
+ */
+export function createBrain(opts) {
+    return new Brains(opts.workspace, new CliBrain(opts), new ApiBrain({ workspace: opts.workspace, auth: opts.auth ?? (() => null), endpoint: opts.endpoint }));
+}
+/** 按这轮的运行时分给 CLI 或 API;预热只有 CLI 有 */
+class Brains {
+    workspace;
+    cli;
+    api;
+    constructor(workspace, cli, api) {
+        this.workspace = workspace;
+        this.cli = cli;
+        this.api = api;
+    }
+    plan(req) {
+        return isApiRuntime(getRuntime(this.workspace().config, req.runtime).runtime) ? this.api.plan(req) : this.cli.plan(req);
+    }
+    prepare(plan) {
+        return plan.cli === API_CLI ? Promise.resolve() : this.cli.prepare(plan);
+    }
+    start(req, plan, ctx, hooks) {
+        return plan.cli === API_CLI ? this.api.start(req, plan, ctx, hooks) : this.cli.start(req, plan, ctx, hooks);
+    }
+    canWarm(runtime) {
+        return !isApiRuntime(runtime) && this.cli.canWarm(runtime);
+    }
+    warm(tutor, slot, plan, key) {
+        if (plan.cli !== API_CLI)
+            this.cli.warm(tutor, slot, plan, key);
+    }
+    warmed(tutor, slot) {
+        return this.cli.warmed(tutor, slot);
+    }
+    dropWarm(tutor, slot) {
+        this.cli.dropWarm(tutor, slot);
+    }
+    close() {
+        this.cli.close();
+    }
+}
+/** 这个运行时关得住工具吗:关得住的,孩子那轮不带工具时,只有工具才用得上的路径(refs、vault)不进上下文包 */
+export function controlsTools(runtime) {
+    return isApiRuntime(runtime) || cliControlsTools(runtime);
+}
+/**
+ * 读一轮的 .log:API 的轮次是一行一条统一事件,CLI 的按运行时的适配器读(运行时后来删了或改了按 stream-json)。
+ * 两种行长得不一样(统一事件以 {"kind": 开头),一行一行认,运行时从 CLI 换成 API 以后,以前的轮次照样读得出
+ */
+export function logParser(runtimes, name) {
+    const cli = parserForRuntime(runtimes, name);
+    return (line) => {
+        const e = parseEventLine(line);
+        return e.length ? e : cli(line);
+    };
+}

package/dist/brain/stream.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 流式:老师还在说的时候,从 CLI 的输出事件里拼出「当前这条顶层回复的正文」,给板书的 partial 解析用。
+ * 有增量的 CLI(claude 加 `--include-partial-messages`、qwen 0.25 同)每个字来一条 delta,每条新回复前有 start;没有增量开关的只有整条 assistant——两种都认:
+ * delta 往当前文本上追加,start 时当前段带围栏或 H2 就留下(与 kid-view 的 kidSource 同一条规则:老师板书完再用工具,卡不丢)、否则丢掉,
+ * 新段从空开始;顶层 assistant 的正文直接当作当前段(与拼出来的一样)。text() = 留下的段 + 当前段。
+ * 子代理的一律跳过。读哪家的输出由 CLI 适配器定(src/brain/cli/),这里只认统一事件。
+ */
+import { type CliEvent } from './cli/types.ts';
+export interface PartialReader {
+    /** 喂一块 stdout(原始字节,行没收完的先攒着);返回文本有没有变 */
+    feed(chunk: string): boolean;
+    /** 喂已经读好的事件(runner 自己切行、解析一次,同一批事件还要给工具与会话用);返回文本有没有变 */
+    apply(events: readonly CliEvent[]): boolean;
+    /** 当前这条顶层回复的正文(还在长) */
+    text(): string;
+    /** 只要当前这段(还没收到整条 assistant 的那段;断流时它没进会话,要递回给老师) */
+    current(): string;
+}
+/** parse:一行输出 → 统一事件(CLI 适配器的 parse);缺省按 stream-json 读 */
+export declare function createPartialReader(parse?: (line: string) => CliEvent[]): PartialReader;