oh-my-agent-web 0.2.0 → 0.4.0

package/dist/server/session/turn-finish.js

@@ -0,0 +1,79 @@
+/**
+ * 回合收尾（从 runtime 抽出来：400 行护栏）。
+ *
+ * 要做的事按顺序：
+ *   1. 从 turns 里摘掉这个会话的回合（并行时别的会话不受影响）
+ *   2. state.running 只复位"当前会话"（ADR-0030 §2）
+ *   3. 排空该会话的排队消息（ADR-0030 的「排队」）
+ *   4. 审批状态收尾（ADR-0006：悬着的审批按拒绝处理）
+ *   5. 助手消息整条落盘 + 建议标记解析（ADR-0022）
+ *   6. 刷新统计与 pi 会话列表，推快照
+ */
+import { emptyRunning } from "../snapshot/state.js";
+import { settleTurnMarkers } from "./turn-markers.js";
+export function createTurnFinisher(deps) {
+    return async (conversationId, reason) => {
+        const turn = deps.turns.get(conversationId);
+        deps.turns.delete(conversationId);
+        const { [conversationId]: _gone, ...rest } = deps.state.runningByConversation;
+        deps.state.runningByConversation = rest;
+        if (conversationId === deps.state.activeId) {
+            const keepError = reason === "error" || deps.state.running.status === "error";
+            deps.state.running = { ...emptyRunning(), status: keepError ? "error" : "idle" };
+        }
+        deps.refreshStats();
+        const next = deps.shiftQueued(conversationId);
+        if (next)
+            deps.sendNext(next, conversationId);
+        deps.state.pendingApproval = null;
+        deps.cancelPending();
+        if (turn)
+            deps.settle({ conversationId, messageId: turn.messageId, rawText: turn.rawText });
+        deps.touchConversation(conversationId);
+        deps.refreshProjects();
+        if (reason === "interrupted")
+            deps.notice("回合已中断", "info");
+        deps.pushSnapshot();
+    };
+}
+/**
+ * runtime 侧的整套收尾装配（落盘 + 队列排空 + 推送回调）。
+ * 抽出来是为了让 runtime 只留一行：它自己的业务（推送通知）用 onTurnFinished 注入。
+ */
+export function createRuntimeTurnFinisher(options) {
+    return createTurnFinisher({
+        state: options.state,
+        turns: options.turns,
+        shiftQueued: options.shiftQueued,
+        sendNext: options.sendNext,
+        cancelPending: options.cancelPending,
+        settle: (info) => {
+            settleWith(options.state, options.nextId, options.now)(info);
+            const conversation = options.state.conversations.find((item) => item.id === info.conversationId);
+            options.onTurnFinished?.({
+                conversationId: info.conversationId,
+                title: conversation?.title ?? "会话",
+                workspace: conversation?.workspace ?? options.state.workspace,
+                failed: false,
+            });
+        },
+        touchConversation: options.touchConversation,
+        refreshStats: options.refreshStats,
+        refreshProjects: options.refreshProjects,
+        notice: options.notice,
+        pushSnapshot: options.pushSnapshot,
+    });
+}
+/** 把 settleTurnMarkers 的调用签名收成上面那个形状（避免 runtime 里再写一段） */
+export function settleWith(state, nextId, now) {
+    return (input) => settleTurnMarkers({ state, ...input, nextId, at: now?.() });
+}
+/** 维护 runningByConversation（并行时侧栏可以同时多行转圈） */
+export function setRunning(state, conversationId, value) {
+    if (value === null) {
+        const { [conversationId]: _gone, ...rest } = state.runningByConversation;
+        state.runningByConversation = rest;
+        return;
+    }
+    state.runningByConversation = { ...state.runningByConversation, [conversationId]: value };
+}

package/dist/server/session/turn-markers.js

@@ -0,0 +1,26 @@
+/**
+ * 回合结束时的标记收尾（ADR-0022）：从 runtime 拆出（400 行护栏第六次咬人）。
+ *
+ * 两件事：
+ *   1. 把流式过滤器里还扣着的尾巴放出来（此时它已经不可能是标记）；
+ *   2. 对最终的助手文本做完整解析：剥离标记 → 建议项进快照。
+ */
+import { applyMarkersToMessage, reduceActionMarkers } from "../markers/actions.js";
+export function settleTurnMarkers(input) {
+    const { state, conversationId, messageId } = input;
+    // 1) 建议从**原始文本**里收（ADR-0022）：流式过滤器为了不漏语法已经把标记丢掉了，
+    //    所以回合结束必须回看原始文本，否则建议永远收不到。
+    const reduced = reduceActionMarkers(input.rawText, state.actions, () => input.nextId("act"));
+    state.actions = reduced.actions;
+    // 2) 消息正文收尾：剥掉可能漏网的标记 + 收拾残留空行（applyMarkersToMessage 是幂等的）
+    const assistant = (state.messages[conversationId] ?? []).find((message) => message.id === messageId);
+    if (!assistant)
+        return;
+    const applied = applyMarkersToMessage(assistant, state.actions, () => input.nextId("act"));
+    state.actions = applied.actions;
+    const endedAt = input.at ?? Date.now();
+    const blocksChanged = applied.blocks !== assistant.blocks;
+    if (blocksChanged || assistant.endedAt !== endedAt) {
+        state.messages[conversationId] = (state.messages[conversationId] ?? []).map((message) => message.id === messageId ? { ...message, blocks: applied.blocks, endedAt } : message);
+    }
+}

package/dist/server/session/turn-queue.js

@@ -0,0 +1,111 @@
+export function createTurnQueue() {
+    const entries = [];
+    return {
+        push(entry) {
+            entries.push(entry);
+            return toViews(entries);
+        },
+        /** 取走某会话的队首（没有就返回 null） */
+        shift(conversationId) {
+            const index = entries.findIndex((entry) => entry.conversationId === conversationId);
+            if (index < 0)
+                return null;
+            return entries.splice(index, 1)[0] ?? null;
+        },
+        /** 取消一条（按 id）；返回是否真的删掉了 */
+        remove(id) {
+            const index = entries.findIndex((entry) => entry.id === id);
+            if (index < 0)
+                return false;
+            entries.splice(index, 1);
+            return true;
+        },
+        /** 删掉某个会话的全部排队项（会话被删时用） */
+        removeConversation(conversationId) {
+            for (let i = entries.length - 1; i >= 0; i -= 1) {
+                if (entries[i]?.conversationId === conversationId)
+                    entries.splice(i, 1);
+            }
+        },
+        views: () => toViews(entries),
+    };
+}
+function toViews(entries) {
+    return entries.map(({ id, conversationId, text }) => ({ id, conversationId, text }));
+}
+export function createBusyHandler(deps) {
+    return async (mode, text, promptText, _images, attachments) => {
+        const conversationId = deps.activeId();
+        if (!conversationId)
+            return { ok: false, error: { code: "session.none", message: "先打开一个会话" } };
+        if (mode === "queue") {
+            const depth = deps.queue(conversationId, text, attachments);
+            deps.notice(`已排队（第 ${depth} 条）：这一轮结束后自动发送`, "info");
+            deps.pushSnapshot();
+            return { ok: true };
+        }
+        if (mode === "steer") {
+            await deps.steer(conversationId, promptText);
+            deps.appendUser(conversationId, text, true);
+            deps.notice("已引导：插进当前这一轮", "info");
+            deps.pushSnapshot();
+            return { ok: true };
+        }
+        deps.notice("另一个回合还在跑，先等它结束或点「停止」", "warn");
+        return { ok: false, error: { code: "session.busy", message: "同一会话已有回合在跑" } };
+    };
+}
+/** 队列 + 快照同步（runtime 里只留三个一行调用） */
+export function createQueueController(options) {
+    const sync = () => {
+        options.state.queued = options.turnQueue.views();
+        options.onChanged();
+    };
+    return {
+        push(conversationId, text, attachments) {
+            const views = options.turnQueue.push({
+                id: options.nextId("q"),
+                conversationId,
+                text,
+                ...(attachments ? { attachments } : {}),
+            });
+            sync();
+            return views.filter((view) => view.conversationId === conversationId).length;
+        },
+        shift(conversationId) {
+            const next = options.turnQueue.shift(conversationId);
+            sync();
+            return next;
+        },
+        cancel(queueId) {
+            const removed = options.turnQueue.remove(queueId);
+            sync();
+            return removed;
+        },
+    };
+}
+/** runtime 的队列/忙碌处理装配（一行调用，runtime 守 400 行） */
+export function createTurnPlumbing(options) {
+    const queue = createQueueController({
+        turnQueue: createTurnQueue(),
+        state: options.state,
+        nextId: options.nextId,
+        onChanged: options.pushSnapshot,
+    });
+    const busy = createBusyHandler({
+        activeId: () => options.state.activeId,
+        steer: (id, prompt) => options.engine.sendMessage(id, prompt, () => { }, { streamingBehavior: "steer" }),
+        queue: (id, text, attachments) => queue.push(id, text, attachments),
+        appendUser: options.appendUser,
+        notice: options.notice,
+        pushSnapshot: options.pushSnapshot,
+    });
+    return { queue, busy };
+}
+/** 取消一条排队消息的对外动作（runtime 里只留一行） */
+export function cancelQueuedWith(queue, queueId, notice) {
+    if (!queue.cancel(queueId))
+        return { ok: false, error: { code: "queue.not_found", message: "这条排队消息已经不在了" } };
+    notice("已取消排队", "info");
+    return { ok: true };
+}

package/dist/server/session/turn-send.js

@@ -0,0 +1,88 @@
+import { createMarkerStreamFilter } from "../markers/actions.js";
+import { appendText, createMessage } from "../snapshot/messages.js";
+import { resolveAttachments } from "./attachment-resolve.js";
+import { setRunning } from "./turn-finish.js";
+import { applyEngineEvent } from "./turn-events.js";
+export function createTurnSender(deps) {
+    const { state } = deps;
+    return async (text, attachments, mode = "steer", targetConversationId, clientId, options = {}) => {
+        const resolved = await resolveAttachments(text, attachments, deps.uploadStore);
+        for (const name of resolved.missing)
+            deps.notice(`附件已失效（可能过期被清理）：${name}`, "warn");
+        if (resolved.images.length > 0)
+            deps.notice(`已附加 ${resolved.images.length} 张图片（视觉注入）`, "info");
+        if (state.activeId !== null && deps.turns.has(state.activeId)) {
+            const handled = await deps.busy(mode, text, resolved.promptText, resolved.images, attachments);
+            if (handled)
+                return handled;
+        }
+        let conversationId = null;
+        let failed = false;
+        try {
+            // 没有任何会话时懒建一个（空实例的第一次发消息）；建了就把发起者的视图指过去
+            const existing = targetConversationId ?? state.activeId;
+            const created = existing ? null : await deps.createConversation(text);
+            if (created && clientId)
+                deps.clientView.setActive(clientId, created);
+            const conv = (existing ?? created); // 两者必有一个（ADR-0033）
+            conversationId = conv;
+            if (!deps.isOpen(conv)) {
+                const opened = await deps.openConversation(conv, (force) => deps.refreshProjects(force));
+                if (opened === null)
+                    throw new Error(`会话打不开：${conv}`);
+                state.messages[conv] = opened;
+                await deps.refreshModels(conv);
+                await deps.refreshThinking(conv);
+            }
+            const ts = deps.now();
+            const userMessage = appendText(createMessage(deps.nextId("msg"), "user", ts), text);
+            const assistantMessage = createMessage(deps.nextId("msg"), "assistant", ts);
+            // 隐藏回合（「想一想」）：不落任何消息，只靠 rawText 收标记
+            if (!options.hidden) {
+                const isFirstMessage = (state.messages[conv] ?? []).length === 0;
+                if (isFirstMessage)
+                    deps.touchConversation(conv, { title: text.replace(/\s+/g, " ").trim().slice(0, deps.titleChars) });
+                state.messages[conv] = [...(state.messages[conv] ?? []), userMessage, assistantMessage];
+            }
+            if (conv === state.activeId) {
+                const running = {
+                    status: "streaming",
+                    conversationId: conv,
+                    turnStartedAt: ts,
+                    streamingText: "",
+                    activeTool: null,
+                };
+                state.running = running;
+            }
+            state.actions = [];
+            deps.turns.set(conv, { messageId: assistantMessage.id, filter: createMarkerStreamFilter(), rawText: "" });
+            setRunning(state, conv, { status: "streaming", turnStartedAt: ts });
+            deps.watchdog.start(conv);
+            if (!options.hidden)
+                deps.touchConversation(conv);
+            deps.pushSnapshot();
+            await deps.engine.sendMessage(conv, resolved.promptText, (event) => {
+                applyEngineEvent(deps.turnContext, { conversationId: conv, messageId: assistantMessage.id, event });
+            }, resolved.images.length > 0 ? { images: resolved.images } : undefined);
+            return { ok: true };
+        }
+        catch (error) {
+            failed = true;
+            const message = error instanceof Error ? error.message : String(error);
+            deps.notice(`回合执行失败：${message}`, "error");
+            return { ok: false, error: { code: "session.turn_failed", message } };
+        }
+        finally {
+            if (conversationId !== null) {
+                deps.watchdog.stop(conversationId);
+                // 引擎的 sendMessage 已经返回（成功或抛错）= 这一轮在引擎侧结束了。它要是没吐 turn_end
+                // （provider 掉线 / 流被掐断 / 异常），这里必须补一次收尾：否则 turns 里留一个永不结束的
+                // 条目 → isBusy() 恒为真 → 切引擎报 engine.busy，界面上还一直是「工作中」。
+                // 异常分支以前先 `turns.delete` 了，这里就成了死代码 —— 那个会话的排队消息永久卡住、
+                // 助手消息也永远不打 endedAt。统一交给 finishTurn，语义靠 reason 区分。
+                if (deps.turns.has(conversationId))
+                    await deps.finishTurn(conversationId, failed ? "error" : "done");
+            }
+        }
+    };
+}

package/dist/server/session/turn-watchdog.js

@@ -0,0 +1,77 @@
+/**
+ * 回合看门狗（ADR-0023）。
+ *
+ * 为什么必须有：回合卡住时，界面看起来像死了（ADR-0005 时期是全局 1 路，影响整个应用）。于是「某个命令卡住」
+ * 不是「那一轮慢」，而是**整个应用不能再用** —— 新消息全被 `session.busy` 拒掉。
+ * （真事：模型自己去跑了一条会挂住的 bash，回合卡了 7 分钟，界面看起来像死了。）
+ *
+ * 规则：
+ *   1. 回合开始时计时；超时 → 中断该回合 + 给一条明确提示（不是静默杀掉）；
+ *   2. **等待用户审批时不计时**（ADR-0006：那是人的时间，不该被机器打断）→ 重新计时；
+ *   3. 时间由外部注入（`setTimer`/`clearTimer`），单测可以确定性地触发超时。
+ */
+/** 给人看的时长格式（提示语用：「20 分钟」/「10 秒」） */
+export function formatDuration(ms) {
+    if (ms < 60_000)
+        return `${Math.max(1, Math.round(ms / 1000))} 秒`;
+    return `${Math.round(ms / 60_000)} 分钟`;
+}
+export const DEFAULT_TURN_TIMEOUT_MS = 20 * 60 * 1000;
+/**
+ * 每个会话一个定时器（ADR-0030 ①）：并行回合上线后，A 卡住不能连带把 B 的超时也清掉。
+ * 现在虽然还只允许一个回合并行，但结构先准备好 —— 行为完全不变。
+ */
+export function createTurnWatchdog(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
+    const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+    const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    const timers = new Map();
+    const clear = (conversationId) => {
+        const handle = timers.get(conversationId);
+        if (handle !== undefined)
+            clearTimer(handle);
+        timers.delete(conversationId);
+    };
+    const arm = (conversationId) => {
+        clear(conversationId);
+        const handle = setTimer(() => {
+            timers.delete(conversationId);
+            if (options.isWaitingForUser()) {
+                arm(conversationId); // 人在犹豫：继续等，不算卡住
+                return;
+            }
+            options.onTimeout(conversationId);
+        }, timeoutMs);
+        timers.set(conversationId, handle);
+    };
+    return {
+        start: (conversationId) => arm(conversationId),
+        stop(conversationId) {
+            if (conversationId === undefined) {
+                for (const id of timers.keys())
+                    clear(id);
+                return;
+            }
+            clear(conversationId);
+        },
+        armed: (conversationId) => (conversationId === undefined ? timers.size > 0 : timers.has(conversationId)),
+        count: () => timers.size,
+    };
+}
+/**
+ * runtime 侧的便捷包装：把「超时 → 提示 + 中断」这套接线收在这里，
+ * 免得每个调用点都重复写一遍（也让 runtime 守住 400 行护栏）。
+ */
+export function createRuntimeTurnWatchdog(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
+    return createTurnWatchdog({
+        timeoutMs,
+        isWaitingForUser: options.isWaitingForUser,
+        ...(options.setTimer ? { setTimer: options.setTimer } : {}),
+        ...(options.clearTimer ? { clearTimer: options.clearTimer } : {}),
+        onTimeout: (conversationId) => {
+            options.notice(`回合超过 ${formatDuration(timeoutMs)}没结束，已自动中断（常见原因：某条命令卡住）`, "warn");
+            void options.engine.interrupt(conversationId);
+        },
+    });
+}

package/dist/server/sessions/session-routes.js

@@ -0,0 +1,17 @@
+export function registerSessionRoutes(app, options) {
+    app.post("/api/sessions/delete", async (request, response) => {
+        const body = request.body;
+        const id = typeof body?.id === "string" ? body.id : "";
+        if (id === "") {
+            response.status(400).json({ error: { code: "session.no_id", message: "缺少会话 id" } });
+            return;
+        }
+        const result = await options.deleteSession(id);
+        if (!result.ok) {
+            const status = result.error.code === "session.not_found" ? 404 : 500;
+            response.status(status).json({ error: result.error });
+            return;
+        }
+        response.json({ ok: true, mode: result.mode, ...(result.movedTo ? { movedTo: result.movedTo } : {}) });
+    });
+}

package/dist/server/skills/skill-routes.js

@@ -0,0 +1,28 @@
+import { createSkillStore } from "./skill-store.js";
+export function registerSkillRoutes(app, options = {}) {
+    const skills = options.skills ?? createSkillStore();
+    app.get("/api/skills", async (_request, response) => {
+        response.json({ skills: await skills.list() });
+    });
+    app.post("/api/skills/enabled", async (request, response) => {
+        const body = request.body;
+        const ids = Array.isArray(body?.ids) ? body.ids.filter((item) => typeof item === "string") : [];
+        if (ids.length === 0) {
+            response.status(400).json({ error: { code: "skills.no_ids", message: "没有指定要操作的技能" } });
+            return;
+        }
+        const enabled = body?.enabled === true;
+        const result = await skills.setEnabled(ids, enabled);
+        options.onChange?.();
+        response.json({ ...result, skills: await skills.list() });
+    });
+    app.get("/api/skills/:id/file", async (request, response) => {
+        const relPath = typeof request.query.path === "string" ? request.query.path : "";
+        const result = await skills.readFile(request.params.id, relPath);
+        if (!result.ok) {
+            response.status(400).json({ error: { code: "skills.read_failed", message: result.error } });
+            return;
+        }
+        response.json(result);
+    });
+}

package/dist/server/skills/skill-store.js

@@ -0,0 +1,134 @@
+/**
+ * 技能列表与启停（P8）。
+ *
+ * 技能目录：`~/.agents/skills/<目录名>/SKILL.md`（frontmatter 里有 name / description），
+ * 目录里还可能有 `scripts/`、`references/` 等。
+ *
+ * **启停的实现方式（刻意选择）**：把 `SKILL.md` 改名成 `.SKILL.md.disabled`。
+ *   - pi 扫描技能只认 `SKILL.md`，改名即"看不见"，这是真正生效的禁用；
+ *   - 不动其它文件、不动目录结构，一条 mv 就能复原，**不产生第二份状态文件**
+ *     （两处状态必然不一致，这是 ADR-0021 的教训）。
+ */
+import { readdir, readFile, rename, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readPreview } from "../files/file-service.js";
+export const SKILL_ENTRY = "SKILL.md";
+export const SKILL_ENTRY_DISABLED = ".SKILL.md.disabled";
+export function defaultSkillsDir() {
+    return join(homedir(), ".agents", "skills");
+}
+/** 纯函数：从 SKILL.md 的 frontmatter 里抠 name / description（不引 yaml 依赖） */
+export function parseFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!match)
+        return { name: "", description: "" };
+    const body = match[1] ?? "";
+    const read = (key) => {
+        const line = new RegExp(`^${key}:\\s*(.+)$`, "m").exec(body);
+        if (!line)
+            return "";
+        return (line[1] ?? "").trim().replace(/^["']/, "").replace(/["']$/, "");
+    };
+    return { name: read("name"), description: read("description") };
+}
+/** 递归列目录里的文件（相对路径），有上限，避免某个技能塞几千个文件把界面拖死 */
+export async function listFiles(root, prefix = "", out = []) {
+    if (out.length >= 200)
+        return out;
+    let entries;
+    try {
+        entries = await readdir(join(root, prefix), { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (out.length >= 200)
+            break;
+        if (entry.name === "cache" || entry.name.startsWith("."))
+            continue;
+        const rel = join(prefix, entry.name);
+        if (entry.isDirectory())
+            await listFiles(root, rel, out);
+        else
+            out.push(rel);
+    }
+    return out;
+}
+function safeId(id) {
+    // 目录名白名单：不允许穿越、不允许以点开头（那是内部文件）
+    return /^[A-Za-z0-9._-]{1,80}$/.test(id) && !id.startsWith(".");
+}
+export function createSkillStore(options = {}) {
+    const root = options.dir ?? defaultSkillsDir();
+    const resolve = (id) => (safeId(id) ? join(root, id) : null);
+    return {
+        async list() {
+            let names = [];
+            try {
+                names = (await readdir(root, { withFileTypes: true }))
+                    .filter((entry) => entry.isDirectory())
+                    .map((entry) => entry.name);
+            }
+            catch {
+                return [];
+            }
+            const skills = [];
+            for (const id of names.sort()) {
+                const dir = join(root, id);
+                const enabled = await stat(join(dir, SKILL_ENTRY))
+                    .then(() => true)
+                    .catch(() => false);
+                const entryPath = join(dir, enabled ? SKILL_ENTRY : SKILL_ENTRY_DISABLED);
+                const text = await readFile(entryPath, "utf8").catch(() => "");
+                if (text === "")
+                    continue; // 既没有 SKILL.md 也没有 .disabled 的目录不是技能
+                const meta = parseFrontmatter(text);
+                skills.push({
+                    id,
+                    name: meta.name !== "" ? meta.name : id,
+                    description: meta.description,
+                    enabled,
+                    files: await listFiles(dir),
+                });
+            }
+            return skills;
+        },
+        async setEnabled(ids, enabled) {
+            const changed = [];
+            const errors = [];
+            for (const id of ids) {
+                const dir = resolve(id);
+                if (!dir) {
+                    errors.push(`非法技能 id：${id}`);
+                    continue;
+                }
+                const from = join(dir, enabled ? SKILL_ENTRY_DISABLED : SKILL_ENTRY);
+                const to = join(dir, enabled ? SKILL_ENTRY : SKILL_ENTRY_DISABLED);
+                const exists = await stat(from)
+                    .then(() => true)
+                    .catch(() => false);
+                if (!exists)
+                    continue; // 已经是目标状态
+                try {
+                    await rename(from, to);
+                    changed.push(id);
+                }
+                catch (error) {
+                    errors.push(`${id}：${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            return { changed, errors };
+        },
+        async readFile(id, relPath) {
+            const dir = resolve(id);
+            if (!dir)
+                return { ok: false, error: "非法技能 id" };
+            const result = await readPreview(dir, relPath);
+            if (!result.ok)
+                return { ok: false, error: result.error };
+            return { ok: true, text: result.text, binary: result.binary, bytes: result.bytes };
+        },
+    };
+}

package/dist/server/snapshot/fan-out.js

@@ -0,0 +1,10 @@
+export function fanOutSnapshot(snapshot, targets) {
+    const shared = JSON.stringify({ type: "event", event: "snapshot", snapshot });
+    for (const socket of targets.sockets) {
+        if (socket.readyState === socket.OPEN)
+            socket.send(shared);
+    }
+    for (const [clientId, sink] of targets.sinks) {
+        sink(JSON.stringify({ type: "event", event: "snapshot", snapshot: targets.snapshotFor(clientId) }));
+    }
+}

package/dist/server/snapshot/messages.js

@@ -0,0 +1,75 @@
+/**
+ * 消息块的纯函数工具（ADR-0012：消息由块构成）。
+ *
+ * 全部是纯函数（不改入参），便于单测覆盖「文本追加 / 工具卡状态流转 / 摘录截断」。
+ */
+import { TOOL_EXCERPT_CHARS } from "../protocol.js";
+export function createMessage(id, role, ts) {
+    return { id, role, ts, blocks: [] };
+}
+/** 追加文本：接到最后一个文本块后面（保持「说一句 → 调工具 → 再说一句」的交错顺序） */
+export function appendText(message, text) {
+    const blocks = [...message.blocks];
+    const last = blocks[blocks.length - 1];
+    if (last && last.kind === "text")
+        blocks[blocks.length - 1] = { kind: "text", text: last.text + text };
+    else
+        blocks.push({ kind: "text", text });
+    return { ...message, blocks };
+}
+export function startTool(message, input) {
+    const block = {
+        kind: "tool",
+        toolCallId: input.toolCallId,
+        name: input.name,
+        argsSummary: input.argsSummary,
+        // 摘要已经够短就不重复带一份：界面靠「有没有 argsFull」判断要不要显示「完整命令」
+        ...(input.argsFull && input.argsFull !== input.argsSummary ? { argsFull: input.argsFull } : {}),
+        status: "running",
+        outputExcerpt: "",
+        truncated: false,
+        startedAt: input.startedAt,
+    };
+    return { ...message, blocks: [...message.blocks, block] };
+}
+/** 摘录预算（ADR-0004 §5）：超限截断并打标记，而不是把 200KB 塞进快照 */
+export function truncateExcerpt(output, limit = TOOL_EXCERPT_CHARS) {
+    if (output.length <= limit)
+        return { outputExcerpt: output, truncated: false };
+    return { outputExcerpt: output.slice(0, limit), truncated: true };
+}
+export function finishTool(message, input) {
+    const { outputExcerpt, truncated } = truncateExcerpt(input.output);
+    const blocks = message.blocks.map((block) => {
+        if (block.kind !== "tool" || block.toolCallId !== input.toolCallId)
+            return block;
+        return {
+            ...block,
+            status: input.status,
+            outputExcerpt,
+            truncated,
+            endedAt: input.endedAt,
+            ...(input.exitCode === undefined ? {} : { exitCode: input.exitCode }),
+        };
+    });
+    return { ...message, blocks };
+}
+export function appendError(message, code, text) {
+    return { ...message, blocks: [...message.blocks, { kind: "error", code, message: text }] };
+}
+/** 快照里最后一条消息的纯文本（给状态栏/调试用） */
+export function messageText(message) {
+    return message.blocks
+        .map((block) => block.kind === "text" ? block.text : block.kind === "error" ? `[${block.code}] ${block.message}` : "")
+        .join("");
+}
+/** 追加思考文本（与正文分开：正文说结论，思考说过程） */
+export function appendThinking(message, text) {
+    const blocks = [...message.blocks];
+    const last = blocks[blocks.length - 1];
+    if (last && last.kind === "thinking")
+        blocks[blocks.length - 1] = { kind: "thinking", text: last.text + text };
+    else
+        blocks.push({ kind: "thinking", text });
+    return { ...message, blocks };
+}