cotutor 0.3.0 → 0.4.0

package/dist/brain/cli/run.js

@@ -1,256 +0,0 @@
-/**
- * 脑执行的 CLI 实现:按 cotutor.json 的运行时起老师进程(qwen 之类,读输出、关工具、环境都在同目录的适配器 adapters.ts 与各家的文件),
- * stream-json 落 <日期>.<job>.log、stderr 落 .err.log;每行读成统一事件,一行只解析一次,同一批事件给拼正文、工具、会话 id 用。
- * - 预热(./warm.ts):消息走 stdin 的运行时,下一轮的进程提前起好,对得上就接过来
- * - 断流看门狗:stall.ms 没吐一个字节、也没有工具在跑 → 杀掉,resume 同一个会话接着写(最多 stall.retries 次)。
- *   CLI 自己的断流重试可能要等很久(2026-09-21 真跑一轮连断两次,等了 6 分钟)
- * - 回复停在写成正文的工具调用上(这轮没给它那个工具,qwen 照自己的格式写出来):resume 同一个会话告诉它不会有结果、接着回孩子,只一次
- * - 收尾:从 .log 读整轮转录;断流接着跑的,断在半截的那段拼回最后一段前面
- */
-import { spawn } from 'node:child_process';
-import { closeSync, createWriteStream, openSync, writeSync } from 'node:fs';
-import { appendFile, mkdir, readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
-import { parserOf, prepareCli, processEnv, toolsOf, unexpectedTools } from "./adapters.js";
-import { planRun, stallPrompt, toolLeakPrompt } from "./run-plan.js";
-import { createPartialReader } from "../stream.js";
-import { parseTranscript, toolCalls, toolSummary } from "../transcript.js";
-import { WarmPool } from "./warm.js";
-const cliName = (p) => p.argv[0].slice(p.argv[0].lastIndexOf('/') + 1);
-export class CliBrain {
-    spares;
-    workspace;
-    /** 起子进程用的环境(测试注入);缺省 process.env */
-    env;
-    constructor(opts) {
-        this.workspace = opts.workspace;
-        this.env = opts.env;
-        this.spares = new WarmPool({ idleMs: opts.warmIdleMs });
-    }
-    plan(req) {
-        const { config, root } = this.workspace();
-        return planRun(config, { session: req.session }, { agent: req.agent, prompt: req.prompt, agentBody: req.agentBody, systemBody: req.systemBody, boardFile: req.boardFile, runtime: req.runtime, effort: req.effort, tools: req.tools, root, readDirs: req.readDirs });
-    }
-    prepare(plan) {
-        return prepareCli(plan.cli, this.workspace().root).catch(() => { });
-    }
-    canWarm(runtime) {
-        return Boolean(runtime.stdin);
-    }
-    warm(tutor, slot, plan, key) {
-        this.spares.warm(tutor, slot, { argv: plan.argv, env: plan.env, ...key }, this.processEnv(plan));
-    }
-    warmed(tutor, slot) {
-        return this.spares.has(tutor, slot);
-    }
-    dropWarm(tutor, slot) {
-        this.spares.drop(tutor, slot);
-    }
-    close() {
-        this.spares.dropAll();
-    }
-    processEnv(p) {
-        return processEnv(p, { ...(this.env ?? process.env), COTUTOR_WORKSPACE: this.workspace().root });
-    }
-    start(req, plan, ctx, hooks) {
-        // 预热的进程:resume 的接那个位置(对得上 = 这个话题从它起来之后没人写过),新开的接 fresh;对不上(或这轮不走 stdin)就杀掉
-        const spare = this.spares.claim(ctx.tutor, plan.resume ? 'resume' : 'fresh', { argv: plan.argv, env: plan.env, ...ctx.key });
-        // 断流接着跑:carried = 被杀那次已经拼出的正文(接着跑的那次换新读取器,正文 = carried + 新的);
-        // open = 断在半截、没进会话的那段(递回给老师,收尾时拼在最后一段前面)
-        let reader = createPartialReader();
-        let carried = '';
-        let open = '';
-        const liveText = () => { const t = reader.text(); return !carried ? t : !t ? carried : open ? carried + t : `${carried}\n\n${t}`; };
-        const resumePlan = (id, prompt) => this.plan({ ...req, runtime: plan.runtime, session: { id, runtime: plan.runtime }, prompt });
-        const stall = ctx.stall;
-        const files = ctx.files;
-        const cwd = ctx.key.cwd;
-        const go = async () => {
-            await mkdir(cwd, { recursive: true });
-            const out = createWriteStream(files.log);
-            const err = openSync(files.err, 'w');
-            hooks.onStart({ cli: cliName(plan), runtime: plan.runtime, resume: plan.resume, ...(spare ? { warmBornAt: spare.bornAt } : {}) });
-            // 工具调用回报一条(子代理的标 sub);顺手记哪些顶层工具还没回结果:工具在跑时进程不吐字是正常的,断流看门狗不算这段
-            const parse = parserOf(plan.cli);
-            let lineBuf = '';
-            const toolsRunning = new Set();
-            // 消息走 stdin 的运行时:看到收尾就关 stdin,进程自己退(每次 runOnce 换一个)
-            let onResult = null;
-            // 进程起来报的工具表里不该有的(适配器核对;不带工具那轮却有工具 = 关工具的旗标失效了,CLI 升版本最先坏的地方)
-            let unexpected = [];
-            let session = plan.session;
-            // 新会话要等模型开始回了(开始回复、吐字、在想、整条回复)才在盘上、才 resume 得了
-            // (2026-09-22 真跑:init 吐了会话 id 就被杀,resume 报 No conversation found;吐过三个字再杀,盘上有这条用户消息)
-            let persisted = plan.resume;
-            let stalls = 0;
-            // warm:预热好的进程(只给第一次;断流接着跑的那次照旧冷起)
-            const runOnce = (p, warm = null) => new Promise((resolveExit) => {
-                // 被杀的那次没收完的半行不要了
-                lineBuf = '';
-                const child = warm?.child ?? spawn(p.argv[0], p.argv.slice(1), {
-                    cwd,
-                    env: this.processEnv(p),
-                    stdio: [p.stdin ? 'pipe' : 'ignore', 'pipe', err],
-                });
-                if (warm) {
-                    // 预热的进程 stderr 是管道(起它时还没有这轮的 err.log):攒下的和之后的都写进来(池子交出来时暂停着,这里 resume)
-                    const toErr = (c) => { try {
-                        writeSync(err, c);
-                    }
-                    catch { /* err.log 已关 */ } };
-                    warm.stderr.forEach(toErr);
-                    child.stderr?.on('data', toErr);
-                    child.stderr?.resume();
-                }
-                if (p.stdin) {
-                    child.stdin?.on('error', () => { });
-                    child.stdin?.write(p.stdin);
-                    onResult = () => { onResult = null; child.stdin?.end(); };
-                }
-                else
-                    onResult = null;
-                let stalled = false;
-                let idle = null;
-                let lastByte = Date.now();
-                const arm = () => {
-                    if (idle)
-                        clearTimeout(idle);
-                    if (!stall.ms)
-                        return;
-                    idle = setTimeout(() => {
-                        idle = null;
-                        if (toolsRunning.size)
-                            return arm();
-                        stalled = true;
-                        child.kill('SIGTERM');
-                        setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
-                            child.kill('SIGKILL'); }, 2000).unref();
-                    }, stall.ms);
-                };
-                arm();
-                child.stdout?.on('data', (chunk) => {
-                    lastByte = Date.now();
-                    arm();
-                    out.write(chunk);
-                    lineBuf += chunk.toString('utf8');
-                    const lines = lineBuf.split('\n');
-                    lineBuf = lines.pop() ?? '';
-                    let changed = false;
-                    for (const line of lines) {
-                        const events = parse(line);
-                        for (const e of events) {
-                            if (e.kind === 'session') {
-                                if (!session)
-                                    session = e.id;
-                            }
-                            else if (e.kind === 'init')
-                                unexpected = unexpectedTools(plan.cli, plan.tools, e.tools);
-                            else if (e.kind === 'result')
-                                onResult?.();
-                            else if (e.kind === 'results') {
-                                if (!e.sub)
-                                    for (const r of e.results)
-                                        toolsRunning.delete(r.id);
-                            }
-                            else {
-                                if (e.kind === 'start' || e.kind === 'delta' || e.kind === 'thinking' || e.kind === 'assistant')
-                                    persisted = true;
-                                if (e.kind === 'assistant')
-                                    for (const tool of toolsOf(e.parts)) {
-                                        if (!e.sub && tool.id)
-                                            toolsRunning.add(tool.id);
-                                        hooks.onTool({ name: toolSummary(tool.name, tool.input), sub: e.sub });
-                                    }
-                            }
-                        }
-                        if (reader.apply(events))
-                            changed = true;
-                    }
-                    if (changed)
-                        hooks.onText();
-                });
-                const done = (r) => {
-                    if (idle)
-                        clearTimeout(idle);
-                    resolveExit({ ...r, ...(stalled ? { stalled: true } : {}) });
-                };
-                child.once('error', (e) => done({ code: null, spawnError: e }));
-                child.once('close', (code) => { if (stalled)
-                    void appendFile(files.err, `cotutor: ${Date.now() - lastByte}ms 没有输出,当断流杀掉\n`).catch(() => { }); done({ code }); });
-                if (warm) {
-                    // 开口前吐的按顺序补喂,再放开暂停;接手之前就退了的,close 已经错过,直接收尾
-                    for (const c of warm.stdout)
-                        child.stdout?.emit('data', c);
-                    child.stdout?.resume();
-                    if (warm.closed())
-                        done({ code: child.exitCode });
-                }
-            });
-            let exit = await runOnce(plan, spare);
-            while (exit.stalled) {
-                stalls++;
-                if (persisted)
-                    open += reader.current();
-                else {
-                    session = plan.session;
-                    open = '';
-                }
-                const retry = stalls <= stall.retries ? stalls : 0;
-                hooks.onStall({ idleMs: stall.ms, retry, kept: Array.from(open).length });
-                if (!retry)
-                    break;
-                carried = persisted ? liveText() : '';
-                reader = createPartialReader();
-                toolsRunning.clear();
-                // 会话还没落盘(进程起来就卡住、一条整的回复都没有):原样从头再起一次;落了盘就 resume 接着写
-                const next = persisted && session ? resumePlan(session, stallPrompt(open)) : plan;
-                hooks.onStart({ cli: cliName(next), runtime: next.runtime, resume: next.resume });
-                exit = await runOnce(next);
-            }
-            // 回复停在写成正文的工具调用上(板书解析器已剥掉,孩子没看到):老师在等结果,resume 同一个会话告诉它不会有结果、接着回孩子,只一次。
-            // 这次的正文接在前面那段后面
-            let leaked = '';
-            if (!exit.stalled && exit.code === 0 && session && req.stuckOnTool?.(liveText())) {
-                leaked = liveText();
-                carried = leaked;
-                open = '';
-                reader = createPartialReader();
-                toolsRunning.clear();
-                const next = resumePlan(session, toolLeakPrompt());
-                hooks.onStart({ cli: cliName(next), runtime: next.runtime, resume: next.resume });
-                exit = await runOnce(next);
-            }
-            hooks.onExit(Date.now());
-            await new Promise((r) => out.end(r));
-            closeSync(err);
-            if (exit.spawnError)
-                await appendFile(files.err, `cotutor: 起不来 ${plan.argv[0]}:${exit.spawnError.message}\n`);
-            const logText = await readFile(files.log, 'utf8').catch(() => '');
-            const transcript = parseTranscript(logText, parse);
-            // 断流接着跑的:断在半截的那段没进会话、也不在最后的 result 里,拼回最后一段前面(老师是从断处接着写的)
-            // (result 的正文被 trim 过,断在句末 / 围栏上的补回换行,免得两句粘成一行)
-            if (open && transcript.final?.text)
-                transcript.final.text = open + (/[。!！?？;；`\n]\s*$/.test(open) ? '\n' : '') + transcript.final.text;
-            if (leaked && transcript.final?.text)
-                transcript.final.text = `${leaked}\n\n${transcript.final.text}`;
-            if (exit.stalled && !transcript.final)
-                transcript.final = { text: null, ok: false, reason: `stalled:${stalls} 次断流(每次 ${stall.ms}ms 没输出),接着跑的次数用完了` };
-            // 这轮用了哪些工具、读了什么:从 .log 抽出来物化(家长端「看原文」一站、cotutor show)
-            const tools = toolCalls(logText, parse).slice(0, 200);
-            if (!transcript.final) {
-                // 进程退了但没有 result 事件:起不来、被杀、或 CLI 崩了;标 error,原因指向 err.log
-                transcript.final = { text: null, ok: false, reason: exit.spawnError ? `spawn:${exit.spawnError.message}` : `exit:${exit.code ?? 'signal'}` };
-                transcript.items.push({ kind: 'done', text: `本轮没有收尾(${transcript.final.reason}),看 ${basename(files.err)}` });
-            }
-            const warnings = [];
-            if (unexpected.length)
-                warnings.push(`${plan.cli} 起来时带着这轮不该有的工具:${unexpected.join('、')}(${plan.tools === 'off' ? '这轮应该一个工具都不带' : '这轮只该带只读的几样'});关工具的旗标可能随 CLI 升级失效了,看 src/brain/cli/${plan.cli}.ts`);
-            if (leaked)
-                warnings.push('老师把工具调用写成了正文、停在那里等结果(板上没出、嘴没念),应用 resume 同一个会话叫它直接回孩子');
-            if (stalls)
-                warnings.push(`API 流断了 ${stalls} 次(每次 ${stall.ms / 1000} 秒没动静),应用杀掉进程、resume 会话接着写的${exit.stalled ? ';次数用完还断,这轮没收尾' : ''}`);
-            return { transcript: { ...transcript, final: transcript.final }, tools, warnings };
-        };
-        return { warm: Boolean(spare), text: liveText, done: go() };
-    }
-}

package/dist/brain/cli/types.js

@@ -1,3 +0,0 @@
-/** 一条回复的正文段 / 工具调用 */
-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

@@ -1,53 +0,0 @@
-/**
- * 预热:消息走 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

@@ -1,103 +0,0 @@
-/**
- * 预热:消息走 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();
-}