cotutor 0.1.0 → 0.3.0

package/dist/runtime/journal/mix.js

@@ -0,0 +1,88 @@
+/**
+ * 录像的声音(口语课、实时老师共用):两边的声音照到达的时刻摆成一条对齐墙钟的单声道(24k),和孩子当时听到的、说的一样。纯函数。
+ *   孩子的块(16k)到了服务端才记时刻,声音是那之前 100 毫秒录的:往前挪一块的长度,升到 24k。
+ *   老师的块照孩子端 A.play 的排法排:上一块放完或到达 + 60 毫秒,取晚的;flush(孩子插嘴、换段)那一刻还没放完的截掉,队列从头排。
+ * 同时给出老师在出声的时段(录像里画「老师在说 / 轮到你」用)、孩子有声的时段(跳过空白时别把孩子说话剪掉)。
+ */
+import { rms } from "../../shared/wav.js";
+export const MIX_RATE = 24000;
+/** 孩子的一块响过这个算有声(同 read-flow 的门限下限) */
+const KID_VOICE = 0.015;
+const KID_RATE = 16000;
+/** 孩子端排队的起步(A.play 里的 0.06 秒) */
+const LEAD_MS = 60;
+const samplesOf = (pcm) => pcm.length >> 1;
+/** 老师的块排成段:[开始, 结束, pcm],flush 截断;时间都是毫秒 */
+export function scheduleTutor(chunks, flushes) {
+    const evs = [...chunks.map((c) => ({ k: 'c', t: c.t, c })), ...flushes.map((t) => ({ k: 'f', t }))];
+    // 同一刻先 flush 再排新块(孩子端先清队列、再收到新回答)
+    evs.sort((a, b) => a.t - b.t || (a.k === 'f' ? -1 : 1));
+    const out = [];
+    let queueEnd = 0;
+    for (const e of evs) {
+        if (e.k === 'f') {
+            for (let i = out.length - 1; i >= 0 && out[i].end > e.t; i--) {
+                const seg = out[i];
+                if (seg.start >= e.t) {
+                    out.splice(i, 1);
+                    continue;
+                }
+                const keep = Math.round(((e.t - seg.start) * MIX_RATE) / 1000);
+                seg.pcm = seg.pcm.subarray(0, keep * 2);
+                seg.end = e.t;
+            }
+            queueEnd = 0;
+            continue;
+        }
+        const start = Math.max(e.t + LEAD_MS, queueEnd);
+        const end = start + (samplesOf(e.c.pcm) * 1000) / MIX_RATE;
+        out.push({ start, end, pcm: e.c.pcm });
+        queueEnd = end;
+    }
+    return out;
+}
+/** 老师出声的时段:挨着的段(间隔不到 150 毫秒)并成一段 */
+export function playingOf(segs) {
+    const out = [];
+    for (const s of [...segs].sort((a, b) => a.start - b.start)) {
+        const last = out[out.length - 1];
+        if (last && s.start - last[1] < 150)
+            last[1] = Math.max(last[1], s.end);
+        else
+            out.push([Math.round(s.start), Math.round(s.end)]);
+    }
+    return out.map(([a, b]) => [Math.round(a), Math.round(b)]);
+}
+/** 两边混成一条(PCM16 单声道 24k,长到 ms 为止;挂断那一刻还没放完的老师的声音不要) */
+export function mixCall(o) {
+    const n = Math.max(0, Math.round((o.ms * MIX_RATE) / 1000));
+    const acc = new Float32Array(n);
+    const put = (at, i16, len) => {
+        const base = Math.round((at * MIX_RATE) / 1000);
+        for (let k = 0; k < len; k++) {
+            const j = base + k;
+            if (j >= 0 && j < n)
+                acc[j] += i16(k);
+        }
+    };
+    for (const c of o.kid) {
+        const m = samplesOf(c.pcm);
+        if (!m)
+            continue;
+        const len = Math.floor((m * MIX_RATE) / KID_RATE);
+        const at = c.t - (m * 1000) / KID_RATE;
+        put(at, (k) => {
+            const x = (k * KID_RATE) / MIX_RATE, i = Math.floor(x), f = x - i;
+            const a = c.pcm.readInt16LE(Math.min(i, m - 1) * 2), b = c.pcm.readInt16LE(Math.min(i + 1, m - 1) * 2);
+            return a + (b - a) * f;
+        }, len);
+    }
+    const segs = scheduleTutor(o.tutor, o.flushes).filter((s) => s.start < o.ms);
+    for (const s of segs)
+        put(s.start, (k) => s.pcm.readInt16LE(k * 2), samplesOf(s.pcm));
+    const pcm = Buffer.alloc(n * 2);
+    for (let j = 0; j < n; j++)
+        pcm.writeInt16LE(Math.max(-32768, Math.min(32767, Math.round(acc[j]))), j * 2);
+    const voiced = o.kid.filter((c) => rms(c.pcm) >= KID_VOICE).map((c) => ({ start: c.t - (samplesOf(c.pcm) * 1000) / KID_RATE, end: c.t }));
+    return { pcm, playing: playingOf(segs.map((s) => ({ start: s.start, end: Math.min(s.end, o.ms) }))), kidVoice: playingOf(voiced) };
+}

package/dist/runtime/journal/mouth-index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 字幕重放:一轮里嘴照念的几段声音按先后接成一份,和讲稿每句在这份里从哪开始。纯函数。
+ * 嘴出声比放快(一段字 1.9 秒出完、声音要放 11.6 秒),孩子按下时没放的多半已经出完:出了的都算,不管孩子端放没放;
+ * 脑写了还没交给嘴、脑还没写的几句没有声音,不在里面。
+ * 每句的起点:一段出齐了,按字数比例摊(同 call.ts 的 readRest,孩子端的字幕就是这么亮的);
+ * 没出齐就停了(孩子按下时嘴还在出、连接断了),按这段已经出的嘴的字幕字数算一个字多长,只摊到已经出了声的那几句。
+ */
+/** 一段:交给嘴的那几句、出了多少字节的声音、嘴的字幕出了几个字、出齐没有 */
+export interface MouthSeg {
+    lines: number[];
+    texts: string[];
+    bytes: number;
+    heard: number;
+    done: boolean;
+}
+export interface MouthStart {
+    line: number;
+    ms: number;
+}
+/** 落盘的那份(<日期>.<job>.mouth.json):声音多长、每句的起点(毫秒,升序) */
+export interface MouthIndex {
+    v: 1;
+    ms: number;
+    lines: MouthStart[];
+}
+export declare function mouthIndex(segs: readonly MouthSeg[], bytesPerMs: number): MouthIndex;

package/dist/runtime/journal/mouth-index.js

@@ -0,0 +1,34 @@
+/**
+ * 字幕重放:一轮里嘴照念的几段声音按先后接成一份,和讲稿每句在这份里从哪开始。纯函数。
+ * 嘴出声比放快(一段字 1.9 秒出完、声音要放 11.6 秒),孩子按下时没放的多半已经出完:出了的都算,不管孩子端放没放;
+ * 脑写了还没交给嘴、脑还没写的几句没有声音,不在里面。
+ * 每句的起点:一段出齐了,按字数比例摊(同 call.ts 的 readRest,孩子端的字幕就是这么亮的);
+ * 没出齐就停了(孩子按下时嘴还在出、连接断了),按这段已经出的嘴的字幕字数算一个字多长,只摊到已经出了声的那几句。
+ */
+export function mouthIndex(segs, bytesPerMs) {
+    const lines = [];
+    const seen = new Set();
+    let at = 0;
+    for (const s of segs) {
+        if (s.bytes <= 0)
+            continue;
+        const segMs = s.bytes / bytesPerMs;
+        const lens = s.texts.map((x) => Math.max(1, x.length));
+        const total = lens.reduce((a, b) => a + b, 0);
+        // 没出齐:一个字多长按已经出的字幕算;字幕一个字都没来,只算这段第一句
+        const perChar = s.done ? segMs / total : s.heard > 0 ? segMs / s.heard : null;
+        let before = 0;
+        for (let k = 0; k < s.lines.length; k++) {
+            const off = perChar === null ? (k === 0 ? 0 : Infinity) : before * perChar;
+            before += lens[k];
+            if (k > 0 && off >= segMs)
+                break;
+            if (seen.has(s.lines[k]))
+                continue;
+            seen.add(s.lines[k]);
+            lines.push({ line: s.lines[k], ms: Math.round(at + off) });
+        }
+        at += segMs;
+    }
+    return { v: 1, ms: Math.round(at), lines };
+}

package/dist/runtime/journal/mouth.d.ts

@@ -0,0 +1,54 @@
+import type { RunEvent } from '../../schema/index.ts';
+import type { Beat } from '../delivery/queue.ts';
+import { type MouthSeg } from './mouth-index.ts';
+/** 嘴这一道的一条(没有 t;补进事件时按那一轮的起点换) */
+export type MouthEvent = Extract<RunEvent, {
+    lane: 'mouth';
+}> extends infer E ? (E extends RunEvent ? Omit<E, 't'> : never) : never;
+export declare class MouthEvents {
+    /** 每一轮老师进程起来的墙钟(换相对毫秒用)、日期 */
+    private readonly runT0;
+    /** 还没到那一轮的(墙钟) */
+    private pre;
+    private readonly note;
+    constructor(note: (date: string, job: string, event: RunEvent) => void);
+    /** 记一条:那一轮起来了就补进它的事件,还不知道是哪一轮(job = null)就先攒着 */
+    record(job: string | null, at: number, ev: MouthEvent): void;
+    /** 新起一轮的头几条(按下、松手…):攒着的换成这几条 */
+    begin(evs: {
+        at: number;
+        ev: MouthEvent;
+    }[]): void;
+    /** 这一轮的老师进程起来了:攒着的按它的起点补进它的事件 */
+    started(job: string, date: string, t0: number): void;
+    /** 接住说完了:攒着的那条接住补上字 */
+    caught(text: string): void;
+}
+type Seg = MouthSeg & {
+    key: object;
+    pcm: Buffer[];
+};
+export declare class MouthTakes {
+    private readonly takes;
+    private readonly conversations;
+    private readonly tutor;
+    private readonly keep;
+    private readonly bytesPerMs;
+    private readonly rate;
+    constructor(opts: {
+        conversations: () => string;
+        tutor: string;
+        keep: number;
+        bytesPerMs: number;
+        rate: number;
+    });
+    /** 这一轮的声音从这里接;更早的几轮落过盘了,内存里只留最近几轮 */
+    open(job: string, date: string): void;
+    /** 这次照念(key 认那一次)在它那一轮里的那一段(第一块声音到时开;make = false 只找不开);那一轮不在内存里的不留 */
+    seg(key: object, beat: Beat, make?: boolean): Seg | null;
+    /** 一段出完了(done)/ 被掐了、断了:这一轮整份重落一次(接在前面的落盘后面,不并发写) */
+    end(key: object, beat: Beat, done: boolean): void;
+    /** 等这几轮都落完(挂电话时) */
+    flush(): Promise<void>;
+}
+export {};

package/dist/runtime/journal/mouth.js

@@ -0,0 +1,102 @@
+/**
+ * 实时那一轮的两样记录(从 call.ts 拆出来,2026-10-29,行为不变):
+ * - MouthEvents:嘴这一道的事件(按下、松手、接住、第几句开始放、打断)补进那一轮的 events.jsonl(Runner.noteEvent)。
+ *   按下、松手、接住在脑起来之前,先攒着,等那一轮的老师进程起来(main:start)再按它的起点换成相对毫秒(负的)
+ * - MouthTakes:字幕重放。嘴照念的声音按轮另留一份,出了的都留(孩子按下时清掉、没放出来的也在);
+ *   一段出完(或被掐、断了)就落 <日期>.<job>.mouth.wav 与每句的起点 .mouth.json(src/runtime/journal/mouth-index.ts);接住那句不在里面。内存里只留最近几轮
+ */
+import { writeFile } from 'node:fs/promises';
+import { conversationFiles } from "../../schema/index.js";
+import { mouthIndex } from "./mouth-index.js";
+import { wavOfPcm } from "../../shared/wav.js";
+export class MouthEvents {
+    /** 每一轮老师进程起来的墙钟(换相对毫秒用)、日期 */
+    runT0 = new Map();
+    /** 还没到那一轮的(墙钟) */
+    pre = [];
+    note;
+    constructor(note) {
+        this.note = note;
+    }
+    /** 记一条:那一轮起来了就补进它的事件,还不知道是哪一轮(job = null)就先攒着 */
+    record(job, at, ev) {
+        const r = job ? this.runT0.get(job) : undefined;
+        if (job && r)
+            this.note(r.date, job, { t: at - r.t0, ...ev });
+        else if (!job)
+            this.pre.push({ at, ev });
+    }
+    /** 新起一轮的头几条(按下、松手…):攒着的换成这几条 */
+    begin(evs) {
+        this.pre = evs;
+    }
+    /** 这一轮的老师进程起来了:攒着的按它的起点补进它的事件 */
+    started(job, date, t0) {
+        this.runT0.set(job, { t0, date });
+        for (const x of this.pre.splice(0))
+            this.record(job, x.at, x.ev);
+    }
+    /** 接住说完了:攒着的那条接住补上字 */
+    caught(text) {
+        const c = [...this.pre].reverse().find((x) => x.ev.kind === 'catch');
+        if (c && c.ev.kind === 'catch')
+            c.ev.text = text;
+    }
+}
+export class MouthTakes {
+    takes = new Map();
+    conversations;
+    tutor;
+    keep;
+    bytesPerMs;
+    rate;
+    constructor(opts) {
+        this.conversations = opts.conversations;
+        this.tutor = opts.tutor;
+        this.keep = opts.keep;
+        this.bytesPerMs = opts.bytesPerMs;
+        this.rate = opts.rate;
+    }
+    /** 这一轮的声音从这里接;更早的几轮落过盘了,内存里只留最近几轮 */
+    open(job, date) {
+        this.takes.set(job, { date, segs: [], writing: Promise.resolve() });
+        for (const old of [...this.takes.keys()].slice(0, -this.keep))
+            this.takes.delete(old);
+    }
+    /** 这次照念(key 认那一次)在它那一轮里的那一段(第一块声音到时开;make = false 只找不开);那一轮不在内存里的不留 */
+    seg(key, beat, make = true) {
+        const take = this.takes.get(beat.job);
+        if (!take)
+            return null;
+        const last = take.segs[take.segs.length - 1];
+        if (last?.key === key)
+            return last;
+        if (!make)
+            return null;
+        const seg = { lines: [...beat.lines], texts: [...beat.texts], bytes: 0, heard: 0, done: false, key, pcm: [] };
+        take.segs.push(seg);
+        return seg;
+    }
+    /** 一段出完了(done)/ 被掐了、断了:这一轮整份重落一次(接在前面的落盘后面,不并发写) */
+    end(key, beat, done) {
+        const seg = this.seg(key, beat, false);
+        if (!seg)
+            return;
+        seg.done = done;
+        const job = beat.job;
+        const take = this.takes.get(job);
+        const pcm = Buffer.concat(take.segs.flatMap((s) => s.pcm));
+        const index = mouthIndex(take.segs, this.bytesPerMs);
+        const f = conversationFiles(this.conversations(), this.tutor, take.date);
+        take.writing = take.writing
+            .then(async () => {
+            await writeFile(f.mouth(job, 'wav'), wavOfPcm(pcm, this.rate));
+            await writeFile(f.mouth(job, 'json'), JSON.stringify(index));
+        })
+            .catch((err) => console.error('live: 嘴的声音落盘失败', err));
+    }
+    /** 等这几轮都落完(挂电话时) */
+    async flush() {
+        await Promise.all([...this.takes.values()].map((x) => x.writing));
+    }
+}

package/dist/runtime/journal/recorder.d.ts

@@ -0,0 +1,46 @@
+export type ReelMsg = [number, 'o' | 'i', Record<string, unknown>];
+/** reel.json:消息、老师出声的时段、孩子有声的时段、屏幕多大;声音另在 call.wav(24k 单声道) */
+export interface CallReel {
+    v: 1;
+    startedAt: string;
+    ms: number;
+    view: [number, number] | null;
+    msgs: ReelMsg[];
+    playing: [number, number][];
+    kidVoice: [number, number][];
+}
+export interface CallTake {
+    ms: number;
+    reel: CallReel;
+    /** 两边按时刻混好的一条(MIX_RATE) */
+    callPcm: Buffer;
+    /** 两边各自首尾相接(孩子 16k、老师 24k),没有时刻 */
+    kidPcm: Buffer;
+    tutorPcm: Buffer;
+}
+export declare class CallRecorder {
+    readonly startedAt: Date;
+    private readonly now;
+    private readonly msgs;
+    private readonly kidChunks;
+    private readonly tutorChunks;
+    private readonly flushes;
+    private size;
+    constructor(now?: () => Date);
+    /** 离开始多少毫秒 */
+    ms(): number;
+    /** 发给孩子端的一条;{t:'flush'} 同时记下清队列的时刻 */
+    out(m: Record<string, unknown>): void;
+    /** 孩子端发来的一条 */
+    in(m: Record<string, unknown>, t?: number): void;
+    /** 孩子端清了播放队列,但没有一条 flush 消息(比如换段时页面自己清) */
+    flush(): void;
+    /** 孩子的一块声音(16k);t 缺省现在(开口前垫上的那几块带自己到的时刻) */
+    kid(pcm: Buffer, t?: number): void;
+    /** 老师的一块声音(24k) */
+    tutor(pcm: Buffer): void;
+    /** 孩子端报的屏幕尺寸;不像样的不记 */
+    view(w: unknown, h: unknown): void;
+    /** 收:混声音、拼录像的数据(ms 缺省现在) */
+    finish(ms?: number): CallTake;
+}

package/dist/runtime/journal/recorder.js

@@ -0,0 +1,58 @@
+/**
+ * 一次通话的录像记录(录数据,不录屏幕):口语课与实时老师共用。
+ * 发给孩子端(o)/ 孩子端发来(i)的每条消息带离开始的毫秒;两边的声音每块带到达的毫秒;孩子端清播放队列的时刻;屏幕多大。
+ * 挂了 finish:两边按到达时刻混成一条(src/runtime/journal/mix.ts),给出录像的数据(reel.json 的形状)与要落盘的声音;落在哪、还落什么由调用方定。
+ */
+import { mixCall } from "./mix.js";
+export class CallRecorder {
+    startedAt;
+    now;
+    msgs = [];
+    kidChunks = [];
+    tutorChunks = [];
+    flushes = [];
+    size = null;
+    constructor(now = () => new Date()) {
+        this.now = now;
+        this.startedAt = now();
+    }
+    /** 离开始多少毫秒 */
+    ms() { return this.now().getTime() - this.startedAt.getTime(); }
+    /** 发给孩子端的一条;{t:'flush'} 同时记下清队列的时刻 */
+    out(m) {
+        const t = this.ms();
+        this.msgs.push([t, 'o', m]);
+        if (m.t === 'flush')
+            this.flushes.push(t);
+    }
+    /** 孩子端发来的一条 */
+    in(m, t = this.ms()) {
+        // 一直听时孩子那一句的开口 / 说完(补记的 hold / release)要记回它当时的时刻,按时刻插进去,录像按顺序读
+        let i = this.msgs.length;
+        while (i > 0 && this.msgs[i - 1][0] > t)
+            i--;
+        this.msgs.splice(i, 0, [t, 'i', m]);
+    }
+    /** 孩子端清了播放队列,但没有一条 flush 消息(比如换段时页面自己清) */
+    flush() { this.flushes.push(this.ms()); }
+    /** 孩子的一块声音(16k);t 缺省现在(开口前垫上的那几块带自己到的时刻) */
+    kid(pcm, t = this.ms()) { this.kidChunks.push({ t, pcm }); }
+    /** 老师的一块声音(24k) */
+    tutor(pcm) { this.tutorChunks.push({ t: this.ms(), pcm }); }
+    /** 孩子端报的屏幕尺寸;不像样的不记 */
+    view(w, h) {
+        if (typeof w === 'number' && typeof h === 'number' && w > 0 && h > 0)
+            this.size = [Math.round(w), Math.round(h)];
+    }
+    /** 收:混声音、拼录像的数据(ms 缺省现在) */
+    finish(ms = this.ms()) {
+        const mix = mixCall({ kid: this.kidChunks, tutor: this.tutorChunks, flushes: this.flushes, ms });
+        return {
+            ms,
+            reel: { v: 1, startedAt: this.startedAt.toISOString(), ms, view: this.size, msgs: this.msgs, playing: mix.playing, kidVoice: mix.kidVoice },
+            callPcm: mix.pcm,
+            kidPcm: Buffer.concat(this.kidChunks.map((c) => c.pcm)),
+            tutorPcm: Buffer.concat(this.tutorChunks.map((c) => c.pcm)),
+        };
+    }
+}

package/dist/runtime/journal/store.d.ts

@@ -0,0 +1,123 @@
+import { type CardAssets, type CardStateFile, type CardStates } from '../../schema/index.ts';
+import { type Transcript } from '../../brain/transcript.ts';
+import { type ConversationIndex } from '../../schema/index.ts';
+import { type ThreadUndo } from '../../memory/vault.ts';
+import type { Workspace } from '../../schema/index.ts';
+export declare class IndexError extends Error {
+    constructor(file: string, cause: string);
+}
+export declare function readIndex(ws: Workspace, tutor: string, date: string): Promise<ConversationIndex>;
+/** 先写 .tmp 再 rename:进程半路死掉不会留下半份索引 */
+export declare function writeIndex(ws: Workspace, index: ConversationIndex): Promise<void>;
+/** 有过对话的日期,新的在前 */
+export declare function listDates(ws: Workspace, tutor: string): Promise<string[]>;
+/** runtime:这轮的运行时名(消息上记着),按它的 CLI 适配器读;不给按 stream-json */
+export declare function readTranscript(ws: Workspace, tutor: string, date: string, job: string, runtime?: string): Promise<Transcript | null>;
+/**
+ * 一天里卡的目录 <date>.<job>.cards/ 全扫一遍:<n>.json 是孩子做的事(坏文件跳过,孩子端不报),<n>/<k>.mp3 是后台生成好的资产。
+ */
+export declare function scanCards(ws: Workspace, tutor: string, date: string): Promise<{
+    states: CardStates;
+    assets: CardAssets;
+}>;
+/** 只要孩子做的事(发消息时挑「上一轮之后改过的」) */
+export declare function readCardStates(ws: Workspace, tutor: string, date: string): Promise<CardStates>;
+/** 存一张卡的状态(先 .tmp 再 rename);turn = 存的时候索引里最后一条的 job */
+export declare function writeCardState(ws: Workspace, tutor: string, date: string, job: string, n: number, file: CardStateFile): Promise<void>;
+/** 画板导出的 png:<date>.<job>.cards/<n>.png;返回相对 conversations/<老师>/ 的名字 */
+export declare function writeCardImage(ws: Workspace, tutor: string, date: string, job: string, n: number, png: Buffer): Promise<string>;
+/**
+ * 作业照片(R5,2026-09-14):落 workspace 的 captures/<日期>/<HHMM>-<n>.<ext>(paths.captures,相对 workspace 根),
+ * 不落 vault。返回相对 workspace 根的路径(消息的 photos、上下文包的 photos: 段、/api/kid/image?p= 都用它)。
+ */
+export declare function writeCapture(ws: Workspace, at: Date, data: Buffer, ext: 'jpg' | 'png'): Promise<string>;
+/** 消息里的照片路径合不合法:相对 workspace 根、落在 paths.captures 里、文件在 */
+export declare function capturePathOk(ws: Workspace, rel: string): Promise<boolean>;
+/**
+ * 这一轮真发出去的东西(<date>.<job>.run.json):上下文包与完整命令行。
+ * 跑完就丢的话「老师为什么没看见孩子选了 C」永远查不了,所以落一份;只有家长端「看原文」读它。
+ */
+/** 这轮用的老师文件与技能的快照(2026-09-15):文件后来改了就查不回当时那份,所以记正文与 hash;技能只记 hash,变没变一眼看 */
+export interface RunSources {
+    agent: {
+        file: string;
+        hash: string;
+        body: string;
+    } | null;
+    /** 技能名 → SKILL.md 的 hash(workspace .agents/skills/ 下有的全部) */
+    skills: Record<string, string>;
+    /** 这轮上下文包里带了原文的笔记(守则、档案、记忆、口径……):role、路径、带进去那段的 hash 与字数、截没截(2026-10-30;续话题「未变」的不在这里) */
+    notes?: {
+        role: string;
+        path: string;
+        hash: string;
+        chars: number;
+        cut?: true;
+    }[];
+    /** 替老师查的(memory/retrieval.ts):文件(相对 vault 根)、整篇的 hash、为什么查 */
+    retrieved?: {
+        path: string;
+        hash: string;
+        why: string;
+    }[];
+}
+export interface RunFile {
+    at: string;
+    /** 拼好的上下文包(消息正文在最后) */
+    prompt: string;
+    runtime: string;
+    /** 完整命令行,argv[0] 是可执行文件 */
+    argv: string[];
+    resume: boolean;
+    session: string | null;
+    /** 老师文件与技能的快照;2026-09-15 之前的轮次没有 */
+    sources?: RunSources;
+    /** 这个运行时把老师正文塞进了命令行({agentBody} / {systemBody}) */
+    agentBody: boolean;
+}
+export declare function writeRunFile(ws: Workspace, tutor: string, date: string, job: string, r: {
+    at: string;
+    prompt: string;
+    plan: {
+        runtime: string;
+        argv: string[];
+        resume: boolean;
+        session: string | null;
+    };
+    agentBody: boolean;
+    sources?: RunSources;
+}): Promise<void>;
+export declare function readRunFile(ws: Workspace, tutor: string, date: string, job: string): Promise<RunFile | null>;
+export declare function readErrLog(ws: Workspace, tutor: string, date: string, job: string): Promise<string>;
+/** 这轮起跑时老师文件与技能长什么样(记进 run.json;读不到的就 null / 空,不拦这一轮) */
+export declare function snapshotSources(ws: Workspace, name: string): Promise<RunSources>;
+/** 老师文件正文(系统提示),给 {agentBody} / {systemBody};从 agents/<name>.md 读(所有运行时都从这里拿) */
+export declare function readAgentBody(ws: Workspace, name: string): Promise<string>;
+/** 给一个话题打星(1–5;null 清掉):话题要在这天的索引里;写回索引 */
+export declare function rateThread(ws: Workspace, tutor: string, date: string, thread: string, rating: number | null): Promise<ConversationIndex>;
+export { readDiaries, readTextbooks, scanVault, undoThreadVault, writeDiary, type ThreadUndo, type Vault } from '../../memory/vault.ts';
+/**
+ * 删掉一天里的一个话题(家长板书页清单上的「删」,2026-09-22):索引里它的消息、会话、星、记账标记都去掉,
+ * 这些轮的文件(转录、run、事件、配音、卡的状态与资产)按 <日期>.<job>.* 整个删。
+ * 这个话题留下的痕迹一起撤(2026-10-05,家长在孩子端试过再删):各轮写进 vault 记忆的行(memoryLines)倒着撤、记账写进日记的那段(diaryBlock)摘掉;
+ * 写到一半断了的(还带着 pending)先对照文件补记,写成了的一样撤。不动的:captures/ 里的照片。跑着的轮由路由先挡(409)。
+ */
+export declare function deleteThread(ws: Workspace, tutor: string, date: string, thread: string): Promise<{
+    index: ConversationIndex;
+    undo: ThreadUndo;
+}>;
+/** 话题写进 vault 的一笔:memory = 这位老师(或这个 activity)的记忆,child = 孩子的记忆,diary = 记账写进日记的那段 */
+export type VaultWrite = {
+    job: string;
+    kind: 'memory' | 'child' | 'diary';
+    n: number;
+};
+/**
+ * 撤回一个话题写进 vault 的一笔(家长端「记录」的「撤回」,2026-10-30,《vault重构方案》§8):n = 那一轮 memoryLines / childLines 的第几条(diary 不用)。
+ * 撤法同删话题(undoThreadVault):家长后来改过那行就找不到,不动,回 misses。撤成了就从那一轮的记录里去掉(删话题时不再撤一遍);
+ * 日记那段撤了 booked 照留,不再自动记它。写到一半断了的先补记。跑着的轮由路由先挡(409)。
+ */
+export declare function undoVaultWrite(ws: Workspace, tutor: string, date: string, thread: string, w: VaultWrite): Promise<{
+    index: ConversationIndex;
+    undo: ThreadUndo;
+}>;