berry-agent 0.1.0-alpha.1

package/dist/host/runtime.js

@@ -0,0 +1,209 @@
+/**
+ * host/runtime — 装配序生命周期骨架（04 篇 §1 进程模型；07 §1.1 表 #10 host 席）。
+ *
+ * 启动序：解析数据目录（memory 形豁免）→ 单活跃机占标记（先占标记再开库——
+ * 拒双开于开库之前）→ Persistence 开库（openStore 门禁序内嵌）→ 披露段组装。
+ * 退出序（04 §1 六步全序有界）：① abort 置位（在飞 run 收打断信号）→
+ * ② closer 队列 drain（有界 5s——在飞子代理/子进程结算，超时强杀）→
+ * ③ write-behind flush（durable 落盘）→ ④ session_shutdown 并行有界 2s
+ * （件级收口钩子）→ ⑤ 作用域 LIFO 回卷（dispose 全序）→ ⑥ 释放活跃标记 +
+ * 关库。一步崩不阻后续步（退出序容错——落盘步永达）。SIGINT②→130 /
+ * SIGTERM 同① / crash.log 崩溃取证 = 进程编舞归 CLI 分派层（批 12c）——
+ * 本件只提供编舞本体（不 process.exit，可测）。
+ *
+ * :memory: 同构纪律（05 §6.6/07 §5）：dump-config 类诊断不开真库、不动活跃
+ * 标记——memory 形走同一运行时装配入口、会话主库零落盘。
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { release as osRelease } from 'node:os';
+import { join } from 'node:path';
+import { AUDIT_MIGRATION, LOAD_GENERATIONS_MIGRATION, MEMORY_DB_PATH, Persistence, resolveDataDir, resolveDatabasePathIn, } from '../persist/index.js';
+// core: 表族迁移声明（05 §6.4 机械聚合——声明来自插件、执行在宿主；host 行
+// 拓扑边在册）。版本升序：scheduler v2 → goal v3 → memory v4-6·9·11 →
+// credentials v7 → audit v8 → load-generations v10 → goal v12（audit v8 与
+// load-generations v10 = 宿主域表——persist export-only 声明，非 core: 表族）。
+import { MEMORY_MIGRATIONS } from '../memory/index.js';
+import { GOAL_MIGRATION, GOAL_APPROVAL_MIGRATION } from '../goal/index.js';
+import { SCHEDULER_MIGRATION } from '../scheduler/index.js';
+import { CREDENTIALS_MIGRATION } from '../credentials/index.js';
+import { collectDate, collectPlatform, renderEnvironmentDisclosure } from './disclosure.js';
+import { acquireActiveMarker } from './single-instance.js';
+/**
+ * 宿主迁移链尾（core: 插件表族声明 + 审计流表——05 §6.4 机械聚合单源）。
+ * sessions-cmd 读侧/维护动词开库同源复用：开库门禁按链 head 校验
+ * user_version（降级运行拒开），读侧动词若带短链开真库会被同库拒——链必须
+ * 与运行时全同。
+ */
+export const HOST_MIGRATION_TAIL = [
+    SCHEDULER_MIGRATION,
+    GOAL_MIGRATION,
+    // 2026-09-13 f-1 批聚合（goals 增列 write_approved 人面批准位 v12——03 §10.5
+    // f-1 定形注①；goal 表族第二条迁移，号随注册序顺延）
+    GOAL_APPROVAL_MIGRATION,
+    ...MEMORY_MIGRATIONS,
+    // 2026-09-08 c-2 存储腿聚合（credentials 表 namespace 扩容 v7——03 §10.9；
+    // 声明在 core:credentials 件、执行在宿主——05 §6.4 机械聚合单源）
+    CREDENTIALS_MIGRATION,
+    // 2026-09-08 U3 落码批 U3-5 聚合（audit_events 进程级 durable 审计流 v8
+    // ——05 §9；宿主域表单写者 = 装配根，persist export-only 声明同形）
+    AUDIT_MIGRATION,
+    // 2026-09-09 装载史批 h-2 聚合（load_generations 宿主形态镜像落账面 v10
+    // ——05 §9；单写者 = 装配根〔boot 完成点 + /reload reapply 尾，h-3 接线〕，
+    // persist export-only 声明同形）
+    LOAD_GENERATIONS_MIGRATION,
+];
+/**
+ * 装配运行时（启动序一站式——分派层唯一入口）。
+ *
+ * 单活跃机拒入（HOST_DATA_DIR_BUSY）与开库失败（TOO_NEW/UNRECOGNIZED/密钥
+ * 不可读）都 fail-loud 抛出——半装配不留残（标记先占后开库，开库抛时标记
+ * 已释放）。
+ */
+export function createHostRuntime(options = {}) {
+    const memory = options.memory === true;
+    // memory 形 dataDir 两态：显式传入 = 同构诊断形（真数据目录读侧 + 主库
+    // :memory: + 不占标记——07 §5 dump-config 纪律）；未传 = 纯诊断测试形
+    const dataDir = memory ? (options.dataDir ?? null) : (options.dataDir ?? defaultDataDir());
+    if (dataDir === null && !memory)
+        throw new Error('不变式破坏：非 memory 形必有数据目录');
+    // 启动序①：单活跃机占标记（memory 形豁免——不开真库不动标记）
+    let lease = null;
+    if (!memory) {
+        lease = acquireActiveMarker(dataDir);
+    }
+    // 启动序②：开库（memory 形 dbPath 哨兵直通；失败释放标记不留残）
+    let persistence;
+    try {
+        persistence = Persistence.open({
+            ...(options.persistence ?? {}),
+            // 非 memory 形库路径锚定显式 dataDir（bug 回归锁位：原先只传 dataDir
+            // 而 Persistence 层 dbPath 缺省走 env 梯子——显式目录被无视，库开在
+            // env/家目录位、secret.key 与库分家；resolveDatabasePathIn 保
+            // BERRY_AGENT_DB_PATH 单文件覆盖恒赢——tier-2 不被目录锚定吞掉）
+            ...(memory
+                ? { dbPath: MEMORY_DB_PATH }
+                : { dbPath: resolveDatabasePathIn(dataDir), dataDir: dataDir }),
+            // 迁移链机械聚合（05 §6.4）：core: 插件表族声明并入宿主单链——调用方
+            // 迁移在前、追加件按版本升序插队（scheduler v2 → goal v3 先于 memory
+            // v4-6；调用方版本须全链严格递增——19c 追加件同律校验）
+            migrations: [...(options.persistence?.migrations ?? []), ...HOST_MIGRATION_TAIL],
+        });
+    }
+    catch (err) {
+        lease?.release();
+        throw err;
+    }
+    // 退出序基建：abort 柄 / closer 队列 / shutdown 钩子 / disposer 栈
+    const abortController = new AbortController();
+    const closers = [];
+    const shutdownHooks = [];
+    const disposers = [];
+    const closersMs = options.exitBudget?.closersMs ?? 5000;
+    const shutdownHooksMs = options.exitBudget?.shutdownHooksMs ?? 2000;
+    let shutDown = false;
+    const runtime = {
+        memory,
+        dataDir,
+        persistence,
+        get abortSignal() {
+            return abortController.signal;
+        },
+        disclosure: () => renderEnvironmentDisclosure({
+            platform: collectPlatform(() => osRelease(), process.platform),
+            cwd: process.cwd(),
+            date: collectDate(() => new Date()),
+            gitSummary: options.gitSummaryProvider?.() ?? null,
+            plugins: options.pluginsProvider?.() ?? null,
+        }),
+        registerCloser: (closer) => {
+            closers.push(closer);
+        },
+        registerShutdownHook: (hook) => {
+            shutdownHooks.push(hook);
+        },
+        registerDisposer: (fn) => {
+            disposers.push(fn);
+        },
+        shutdown: async () => {
+            if (shutDown)
+                return; // 幂等（SIGINT② 与优雅序并发到同一收口）
+            shutDown = true;
+            // ① abort 置位（在飞 run 收打断信号——不再收新输入）
+            abortController.abort();
+            // ② closer drain（注册序串行，有界 5s——超时强杀 = 放弃等待）
+            for (const closer of closers) {
+                try {
+                    await withTimeout(Promise.resolve(closer.fn()), closersMs, `closer ${closer.label}`);
+                }
+                catch (err) {
+                    console.error(`[exit] closer ${closer.label} 超时或抛错（强杀继续）: ${describe(err)}`);
+                }
+            }
+            // ③ write-behind flush（durable 落盘——退出序永达步）
+            try {
+                await persistence.flush();
+            }
+            catch (err) {
+                console.error(`[exit] write-behind flush 抛错（继续收口）: ${describe(err)}`);
+            }
+            // ④ session_shutdown 并行有界 2s（件级收口钩子）
+            await Promise.allSettled(shutdownHooks.map((hook) => withTimeout(Promise.resolve(hook()), shutdownHooksMs, 'session_shutdown 钩子').catch((err) => {
+                console.error(`[exit] shutdown 钩子超时或抛错（继续收口）: ${describe(err)}`);
+            })));
+            // ⑤ 作用域 LIFO 回卷（dispose 全序——后注册先回卷）
+            for (const dispose of disposers.reverse()) {
+                try {
+                    dispose();
+                }
+                catch (err) {
+                    console.error(`[exit] disposer 抛错（继续回卷）: ${describe(err)}`);
+                }
+            }
+            // ⑥ 释放活跃标记 + 关库（close 内含 write-behind 终批落账）
+            lease?.release();
+            await persistence.close();
+        },
+        writeCrashLog: (error) => {
+            if (memory || dataDir === null)
+                return; // memory 形无真库归属地——跳过
+            appendCrashLog(dataDir, error);
+        },
+    };
+    return runtime;
+}
+/**
+ * 崩溃取证直写（数据目录 crash.log 同步追加一行）。
+ *
+ * 独立于运行时导出——main 装配位在运行时尚未组装的前置窗口（解析/开库
+ * 阶段）也能取证；写失败静默（崩溃路径唯一允许——进程将退再抛无消费方）。
+ */
+export function appendCrashLog(dataDir, error) {
+    try {
+        mkdirSync(dataDir, { recursive: true });
+        appendFileSync(join(dataDir, 'crash.log'), `[${new Date().toISOString()}] ${describe(error)}\n`);
+    }
+    catch {
+        // 同上——崩溃路径唯一允许的静默
+    }
+}
+/** 数据目录缺省解析（persist 三级梯子真源——BERRY_AGENT_DATA_DIR > ~/.berry-agent） */
+function defaultDataDir() {
+    return resolveDataDir();
+}
+/** 错误速写（退出序 warn 载荷） */
+function describe(err) {
+    return err instanceof Error ? `${err.stack ?? err.message}` : String(err);
+}
+/** 有界等待（超时抛——超时后底层 promise 不取消，仅放弃等待 = 强杀语义）；导出共用于装载器三时钟（批 12d） */
+export function withTimeout(p, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} 超时（${ms}ms 帽——放弃等待）`)), ms);
+        p.then(() => {
+            clearTimeout(timer);
+            resolve();
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}

package/dist/host/scheduler-tick.js

@@ -0,0 +1,294 @@
+/**
+ * host/scheduler-tick — 甲案进程内 tick 执行腿（u-2 G0 修复笔——04 §12
+ * 「无人值守执行链定形注」①②的码面兑现）。
+ *
+ * 定位：RunnerFactory 接缝的**进程内第二实装**（第一实装 = runner.ts 进程
+ * spawn 形，乙案 OS cron 触发腿/CLI 手动形专用）。引擎编舞（抢占/闸评估/
+ * 墙钟/settle）零改动——只换装配位注入的 runner 真身：
+ *
+ * - **进程内推进律（定形注①）**：fire 不 spawn——宿主进程内经
+ *   conversation-stack 起 headless run（与 `run --read-only --tick` 同语义
+ *   链）。既有护栏全执法照常：RunLaneGate 宿主级 run 并发帽（经
+ *   stack.submitText 与前台 run 同池同帽）、§5 预算闸（settle 后记后台道
+ *   ——与 run-entry --background 记账律同形）、§9 审批（走宿主审批瀑布
+ *   ——无人应答时 unavailable fail-closed 语义不变）。
+ * - **builtin 行程序化分派律（定形注②）**：builtin 标记行按名程序化分派
+ *   件内处理器——零模型调用零 spawn；行 prompt 字段 = 审计呈现占位
+ *   （占位串不进模型面）。goal 挂钟行 → goal 件唤醒判定链、`issue-poll`
+ *   → IssueService.pollOnce、`memory-review` → 件内编排入口（v1 前瞻位
+ *   ——处理器缺席诚实 gated 拒）。
+ * - **墙钟守卫两形（定形注④）**：kill = stack.interrupt 协作中止
+ *   （driver.abort()——乙案 kill 形归 process runner 实装，两形互不代偿）。
+ *
+ * 分派处理器 fire 时动态解析（装载序无关——goal/issue 件可后装）；
+ * 处理器缺席 = 配置漂移形，gated 结局诚实拒（不动 last_fire_at——引擎
+ * settled 段按 reason==='gated' 分流 settleGated）。
+ */
+import { cwd as processCwd } from 'node:process';
+import { canonicalWorkspaceRoot } from '../context/index.js';
+/** 结局预览截断（process runner 同值——RunOutcome.finalTextPreview 帽） */
+const PREVIEW_CAP = 200;
+/**
+ * 进程内 tick runner 工厂。编舞三路：builtin 分派（零模型）/ goal 挂钟行
+ * （wake 判定 + 落地则提交 goal 会话）/ 用户行（到点跑其提示词）。
+ */
+export function createSchedulerTickRunner(deps) {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const warn = deps.warn ?? ((message) => console.error(message));
+    return {
+        async spawn(req) {
+            const { row, trigger } = req;
+            // —— builtin 行：程序化分派（零模型零 spawn——占位串不进模型面） ——
+            if (row.builtin) {
+                if (row.name === 'issue-poll')
+                    return spawnIssuePoll(row, trigger);
+                if (row.name.startsWith('goal-'))
+                    return spawnGoalRow(row, trigger);
+                if (row.name === 'memory-review')
+                    return spawnMemoryReview(row, trigger);
+                // 未知 builtin 名：行在册而分派表不识——配置漂移诚实拒（不猜处理器）
+                return settledHandle(trigger, {
+                    reason: 'gated',
+                    error: `未知 builtin 行「${row.name}」——分派表无此名（goal-<id>/issue-poll/memory-review 三员之外）`,
+                });
+            }
+            // —— 用户行：进程内 headless run（新建会话 + 行 prompt 提交） ——
+            return spawnUserRow(row, trigger);
+        },
+    };
+    /** 一次性结局句柄（零跑形态——gated 拒/spawn 同步失败等） */
+    function settledHandle(trigger, outcome) {
+        return {
+            pid: process.pid,
+            kill: () => { }, // 已收场——kill 幂等空放
+            settled: Promise.resolve({ ...outcome, trigger, finishedAt: now() }),
+        };
+    }
+    /** 在飞 run 句柄铸造（kill = 协作中止；killedReason 优先折结算局——trigger 已由 settle 载入 outcome） */
+    function inflightHandle(sessionId, settle) {
+        let killedReason = null;
+        const settled = settle().then((outcome) => {
+            // kill 已先行（墙钟超时/新实例抢占）——reason 折 kill 形（process runner 同律）
+            if (killedReason !== null) {
+                return {
+                    ...outcome,
+                    reason: killedReason,
+                    exitCode: undefined,
+                    error: `被中止（${killedReason === 'timeout' ? '墙钟超时' : '新实例抢占'}）`,
+                };
+            }
+            return outcome;
+        });
+        return {
+            pid: process.pid,
+            kill(reason) {
+                killedReason = reason;
+                if (sessionId !== null)
+                    deps.stack.interrupt(sessionId); // 协作中止（driver.abort()——定形注④甲案形）
+            },
+            settled,
+        };
+    }
+    /**
+     * 用户行编舞：新建会话 → submitText（source='schedule'）→ 三终态映射 + 后台道
+     * 记账。会话终态收口（04 §12 第 5 律）：用户行每次 fire 新建会话（fresh per
+     * fire）——settle 尾即 retire（dismantle + 摘登记），活体登记无界驻留收口；
+     * durable 面不受影响。goal 行复用 goal 绑定会话（广播唤醒依赖），不走此收口。
+     */
+    function spawnUserRow(row, trigger) {
+        const workspaceRoot = canonicalWorkspaceRoot(row.cwd ?? processCwd());
+        let sessionId;
+        try {
+            sessionId = deps.stack.manager.create({ workspaceRoot }).sessionId;
+        }
+        catch (err) {
+            return settledHandle(trigger, {
+                reason: 'spawn',
+                error: `会话创建失败：${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        const base = runSession(trigger, sessionId, row.prompt);
+        // settle 尾收口（finally 面——映射异常路径同样摘登记；kill 折叠序在先，
+        // retire 后 interrupt 对已摘行 = 可选链 no-op，幂等无害）
+        return {
+            ...base,
+            settled: base.settled.finally(() => {
+                deps.stack.manager.retire(sessionId);
+            }),
+        };
+    }
+    /** goal 挂钟行编舞：wake 判定先行（零模型）——落地则 goal 会话提交 promptSnapshot。判定段（毫秒级 DB 读）先于句柄铸造，kill 不可达窗可忽略 */
+    async function spawnGoalRow(row, trigger) {
+        const goalId = row.name.slice('goal-'.length);
+        const goal = deps.resolveGoal();
+        if (goal === undefined) {
+            // goal 行在册而 goal 件未装载——配置漂移（run-entry 同款诚实拒语义）
+            warn(`[SCHEDULER_GOAL_MISSING] goal 挂钟行「${row.name}」在册而 core:goal 件未装载——配置漂移，本轮诚实拒`);
+            return settledHandle(trigger, {
+                reason: 'gated',
+                error: 'goal 件未装载——挂钟行配置漂移（wake 判定链不可用）',
+            });
+        }
+        const decision = await goal.wake(goalId, {
+            // 引擎载体归因（与 run-entry --tick 形同串——tick:<行名> 可审计）
+            trigger: 'clock',
+            attribution: `tick:${row.name}`,
+        });
+        if (!decision.landed) {
+            // 诚实零跑：不落即本轮无事（inactive/stalled/wake_budget 各由 message 说明）
+            return settledHandle(trigger, {
+                reason: 'gated',
+                error: `goal「${goalId}」本轮未唤醒（${decision.reason}）：${decision.message}`,
+            });
+        }
+        // 唤醒起跑前池检（u-3——04 §5 定形注③第二形态）：wake 判定链只看 goal
+        // 自身（停滞/唤醒预算），日池尽在此拦——改停靠-唤醒（disable 挂钟行 +
+        // 会话落词 + 广播登记，budget_extended 恢复时同链唤醒），gated 零跑收场
+        const park = deps.resolveGoalPark?.();
+        if (park !== undefined && (await park(goalId))) {
+            return settledHandle(trigger, {
+                reason: 'gated',
+                error: `goal「${goalId}」唤醒落地而起跑前日池尽——预算停靠（挂钟停摆 + session/paused 落词，待 budget_extended 广播唤醒）`,
+            });
+        }
+        // 落地：goal 绑定会话幂等开驱动后提交 promptSnapshot（与 run-entry tick 形同链）
+        try {
+            const sessionId = deps.stack.manager.open(decision.goal.sessionId).sessionId;
+            return runSession(trigger, sessionId, row.prompt);
+        }
+        catch (err) {
+            return settledHandle(trigger, {
+                reason: 'spawn',
+                error: `goal 会话打开失败：${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    /** issue-poll 行编舞：直调 pollOnce（零模型——定形注②「占位串不进模型」正位） */
+    function spawnIssuePoll(row, trigger) {
+        void row; // 行 prompt 恒为占位——分派只认名，prompt 不消费
+        return inflightHandle(null, async () => {
+            const poller = deps.resolveIssuePoll();
+            if (poller === undefined) {
+                // issue-poll 行在册而 issue 件未装载——配置漂移（处理器缺席诚实拒）
+                warn('[SCHEDULER_POLL_MISSING] issue-poll 行在册而 core:issue 件未装载——配置漂移，本轮诚实拒');
+                return {
+                    trigger,
+                    reason: 'gated',
+                    error: 'issue 件未装载——轮询处理器缺席（pollOnce 不可达）',
+                    finishedAt: now(),
+                };
+            }
+            try {
+                const report = await poller.pollOnce();
+                const preview = `轮询 ${report.repos.length} 仓：候选 ${report.candidates}、入队 ${report.enqueued}、互斥 ${report.duplicates}、拒 ${report.rejected}`;
+                return {
+                    trigger,
+                    reason: 'exit_code',
+                    exitCode: 0,
+                    finalTextPreview: preview.slice(0, PREVIEW_CAP),
+                    finishedAt: now(),
+                };
+            }
+            catch (err) {
+                return {
+                    trigger,
+                    reason: 'exit_code',
+                    exitCode: 1,
+                    error: err instanceof Error ? err.message : String(err),
+                    finishedAt: now(),
+                };
+            }
+        });
+    }
+    /** memory-review 行编舞：前瞻位——编排入口装载态未提供，诚实 gated（定形注②第三员） */
+    function spawnMemoryReview(row, trigger) {
+        void row;
+        return inflightHandle(null, async () => {
+            const review = deps.resolveMemoryReview?.();
+            if (review === undefined) {
+                // v1 恒此路：件内编排入口未装载（行若在册即漂移）——零模型诚实拒
+                warn('[SCHEDULER_REVIEW_MISSING] memory-review 行在册而编排入口未装载——前瞻分派位诚实拒');
+                return {
+                    trigger,
+                    reason: 'gated',
+                    error: 'memory-review 编排入口未装载（v1 前瞻分派位）',
+                    finishedAt: now(),
+                };
+            }
+            try {
+                await review();
+                return { trigger, reason: 'exit_code', exitCode: 0, finishedAt: now() };
+            }
+            catch (err) {
+                return {
+                    trigger,
+                    reason: 'exit_code',
+                    exitCode: 1,
+                    error: err instanceof Error ? err.message : String(err),
+                    finishedAt: now(),
+                };
+            }
+        });
+    }
+    /**
+     * 会话 run 编舞共用（用户行/goal 落地形单源）：起跑前 seq 锚 →
+     * submitText（source='schedule' + backgroundLane 声明——04 §5 后台道
+     * 无头 run 的 run 级预警分族判据〔2026-09-13 修复批〕）→ 三终态映射 +
+     * 后台道记账。
+     */
+    function runSession(trigger, sessionId, prompt) {
+        const runPromise = deps.stack.submitText(sessionId, prompt, {
+            source: 'schedule',
+            backgroundLane: true,
+        });
+        if (runPromise === undefined) {
+            // 驱动缺席（open/create 与提交间被拆——理论不达防御，诚实失败）
+            return settledHandle(trigger, {
+                reason: 'spawn',
+                error: `会话 ${sessionId} 无驱动在册——提交序不可达`,
+            });
+        }
+        return inflightHandle(sessionId, async () => {
+            const result = await runPromise;
+            // 后台道记账已上移组合根 settled 桥接单点（04 §5 #41/#44——本 submit
+            // 已声明 backgroundLane: true，priority 由回执声明位承载；此处再扫即双计）
+            if (result.status === 'completed') {
+                const outcome = { reason: 'exit_code', exitCode: 0, trigger, finishedAt: now() };
+                const preview = lastAssistantText(sessionId);
+                if (preview !== undefined)
+                    outcome.finalTextPreview = preview.slice(0, PREVIEW_CAP);
+                return outcome;
+            }
+            if (result.status === 'failed') {
+                return {
+                    reason: 'exit_code',
+                    exitCode: 1,
+                    error: (result.errorMessage ?? 'run 失败（无错误说明）').slice(0, PREVIEW_CAP),
+                    trigger,
+                    finishedAt: now(),
+                };
+            }
+            // aborted（interrupt 协作中止——kill 未先行时为外部中止形）
+            return { reason: 'killed', error: 'run 中止（协作 abort）', trigger, finishedAt: now() };
+        });
+    }
+    /** 末条 assistant 文本（text 块拼接——run-entry 同律，thinking 不入产物） */
+    function lastAssistantText(sessionId) {
+        const events = deps.stack.driverOf(sessionId)?.session.events() ?? [];
+        for (let i = events.length - 1; i >= 0; i--) {
+            const ev = events[i];
+            if (ev === undefined || ev.type !== 'assistant/message')
+                continue;
+            const content = ev.data.content;
+            if (!Array.isArray(content))
+                return undefined;
+            const text = content
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text)
+                .join('');
+            return text === '' ? undefined : text;
+        }
+        return undefined;
+    }
+}
+// 计量桶映射单源已上移 llm/events.ts usageBucketsOf（04 §5 #41/#44 桥接单点化——旧扫退役）