berry-agent 0.1.0-alpha.1

package/dist/host/conversation-stack.js

@@ -0,0 +1,654 @@
+/**
+ * host/conversation-stack — 对话栈组合根（批 12e 装配序核心件；07 §1.1
+ * 表 #10 host 席「装配序」条的本体，channels/service.ts 头注装配序真源）。
+ *
+ * 一次成型装配五层：
+ *  ① context 基座——Scope 根 + EventDispatch + ctx.agent 服务面（先于一切
+ *     驱动起跑——onRunSettled 订阅面的供给前提）；
+ *  ② llm 运行时——Models 宿主 + StreamFn（永不抛）+ complete 单发服务，
+ *     两出口共享同一 InFlightTracker（04 §3.6 同源计数）；
+ *  ③ compaction 服务——SummaryChannel 适配 LlmService（maxChars 预算入
+ *     prompt 指令、输出防御性截断）+ 阈值触发器经 onRunSettled 接线
+ *     （05 §2 装配挂账 + 判阈双源真值笔全兑现——run 终态从日志末条
+ *     assistant 计量供笔〔lastUsageFactOf，末条不回溯〕，真 token 主判、
+ *     缺真值回落投影字符估算）；
+ *  ④ channels 通道核——fetchProjection/history 同源投影注入（07 §4.1 边表
+ *     执法：核零 session 依赖，数据源在此闭包注入）；
+ *  ⑤ SessionManager——DriverFactory 注入：open 域工具一次成型（assembleOpenTools
+ *     + 审批桥）+ ConversationDriver 装配注入族全接线 + 活体事件信封汇入
+ *     channels.emit（per-run sink 的归汇处）。
+ *
+ * 装配循环依赖解法：channels 的投影源要驱动登记、驱动的审批 ask 要 channels
+ * 队列——channels 创建收进本件内部（组合根自持），TUI 入口只 addBackend。
+ *
+ * memory 形降级（05 §6.6/07 §5）：runtime.dataDir === null 时 open 域工具整面
+ * 缺席（守门恒排除位必填真 dataDir）——纯对话 run，工具面类型可选的诚实降级。
+ */
+import { join } from 'node:path';
+import { canonicalWorkspaceRoot, EventDispatch, Scope } from '../context/index.js';
+import { createChannels } from '../channels/index.js';
+import { getMessageRoleDefinition, isStandardMessage } from '../contracts/index.js';
+import { createCompactionService, createCompactionSlots, createCcrRetrieveTool, BEFORE_COMPACT_ATTRIB, } from '../compaction/index.js';
+import { assembleOpenTools, ConversationDriver, createSessionsControl, createControlTools, CONTROL_CROSS_CAPABILITY, DEFAULT_RETRY_POLICY, ensureTodoRole, provideAgentService, reseedTimeline, SessionManager, } from '../conversation/index.js';
+import { classifyError, createLlmRuntime, createLlmService, createStreamFn, InFlightTracker, resolveDefaultModelSpec, usageBucketsOf, } from '../llm/index.js';
+import { matchToolPolicy } from '../safety/index.js';
+import { deriveMessages } from '../session/index.js';
+import { TOOL_POLICY_BASENAME } from './tool-policy-store.js';
+import { createSessionTools, createSessionView, OBSERVE_CROSS_CAPABILITY } from '../obs/index.js';
+import { adjudicateCapabilityDoor } from '../contracts/api.js';
+/**
+ * 组装对话栈。副作用注册：两 closer（manager 拆解 → compaction 排空）按注册
+ * 序进运行时退出序（abort 之后、write-behind flush 之前）。
+ */
+export function createConversationStack(options) {
+    const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    const scope = options.scope ?? Scope.createRoot();
+    const dispatch = options.dispatch ?? new EventDispatch();
+    const model = options.model ?? resolveDefaultModelSpec(options.env ?? process.env);
+    // lane 帽（04 §4 宿主级 run 并发帽——channels 消息语义批 m-2）：全宿主
+    // 单例信号量，driver 装配位 seam 注入（acquireRunSlot——kick 同步试位/
+    // 排队段两面消费；steer/inject 腿不经闸）。容量解析序：显式覆盖位 > env > 缺省 16。
+    const runLane = createRunLaneGate(resolveRunLaneCapacity(options.maxConcurrentRuns, options.env ?? process.env));
+    // 当日后台预算限额（04 §5 env 旋钮——2026-09-13 复盘修复 #44 F3）：
+    // undefined = 缺省 4M（缺省值单源在 llm 件——本层只透传覆盖位）
+    const backgroundBudgetTokens = resolveBackgroundBudgetTokens(options.env ?? process.env);
+    const sandboxMode = options.sandboxMode ?? (() => 'workspace-write');
+    const workspaceAnchor = options.workspace ?? (() => canonicalWorkspaceRoot());
+    // ① ctx.agent 服务面先于一切驱动起跑（onRunSettled 订阅供给前提）
+    const agentService = provideAgentService(scope);
+    // todo 回看角色幂等注册（进程级单表——convertToLlm 消费前置）
+    ensureTodoRole();
+    // ② llm 运行时：两出口共享同一 InFlightTracker（04 §3.6 同源计数名实相符）；
+    // 钩子派发段只读面同注双入口（03 §3.4——LLM_CALL_IN_HOOK 前置查，ca-3）。
+    // 预算读面同位接线（04 §5——2026-09-13 复盘修复 #44：修前 backgroundSpentToday
+    // 缺省 () => 0 空转，canAfford/预警三档/reserve 线三消费面生产恒判未超）。
+    const llmRuntime = createLlmRuntime(options.providers !== undefined ? { providers: options.providers } : {});
+    const tracker = new InFlightTracker();
+    const streamFn = createStreamFn(llmRuntime, {}, tracker, options.hookDispatchGuard);
+    // 当日后台已耗读面：日键缓存 + 桥接增量（05 §1.1 口径——SUM(input+output)、
+    // background 道过滤）。单写者进程（单活跃机收口）内首读聚合后只随本进程
+    // 桥接落账增量推进；日翻转重聚合（昨账不跨日）。write-behind 未落盘窗内
+    // 最近一笔偏松——软闸门既有语义（04 §5 定形注②）。
+    let spentDayStart = -1;
+    let spentCached = 0;
+    const backgroundSpentToday = () => {
+        const dayStart = startOfTodayMs();
+        if (dayStart !== spentDayStart) {
+            spentDayStart = dayStart;
+            try {
+                spentCached = aggregateBackgroundSpentToday(options.runtime.persistence.store, dayStart);
+            }
+            catch (err) {
+                // 读面失败 fail-open + warn：预算是软闸门，db 抖动不应反噬请求路（欠账
+                // 随下次日键重试/进程重启收口——丢弃的只是当次聚合精度）
+                warn(`当日后台已耗聚合失败（fail-open 归既知值 ${spentCached}）：${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return spentCached;
+    };
+    const llm = createLlmService({
+        runtime: llmRuntime,
+        tracker,
+        defaultModel: () => model,
+        ...(options.hookDispatchGuard !== undefined ? { hookDispatch: options.hookDispatchGuard } : {}),
+        backgroundSpentToday,
+        ...(backgroundBudgetTokens !== undefined ? { backgroundBudgetTokens } : {}),
+    });
+    /**
+     * usage 桥接落账（04 §5 记账桥接单点——2026-09-13 复盘修复 #41/#44 定形注①）：
+     * settled 回执窗扫 (seqFromLaunch, settle] 的 assistant/message 逐条转抄
+     * llm/usage（真源仍是 assistant 落账位——桥接投影零改写；05 §1.1 表注）。
+     * callId `run:<sid>:<seq>`（与 run CLI 旧桥接同形平移零迁移）；priority 随
+     * run 级 backgroundLane（「前台花销照入账」就此收口——TUI/webui/issue/SDK
+     * /run CLI 五入口统一）。run-entry --background 块与 scheduler-tick
+     * recordBackgroundUsage 两处旧扫已退役（同窗同键防双计）。
+     */
+    const bridgeUsageLedger = (log, modelSpec, receipt) => {
+        for (const event of log.events()) {
+            if (event.seq <= receipt.seqFromLaunch || event.type !== 'assistant/message')
+                continue;
+            const usage = event.data.usage;
+            if (usage === undefined)
+                continue; // 无计量不造零账
+            log.append('llm/usage', {
+                callId: `run:${receipt.sessionId}:${event.seq}`,
+                model: modelSpec,
+                usage: usageBucketsOf(usage),
+                priority: receipt.backgroundLane ? 'background' : 'foreground',
+            });
+            // 当日缓存增量（仅后台道进闸门口径；先经读面确保日键已初始化——
+            // 未初始化时磁盘聚合随后自会收编本笔，双计不生）
+            if (receipt.backgroundLane) {
+                void backgroundSpentToday();
+                if (spentDayStart === startOfTodayMs())
+                    spentCached += usage.input + usage.output;
+            }
+        }
+    };
+    // ③ compaction：SummaryChannel 适配（maxChars 由 prompt 指令承载——complete
+    // 单发面无 maxTokens 参数；输出防御性截断兜底）。阈值触发器接线：run 终态
+    // 订阅 → handleRunSettled（真 token 笔从日志末条 assistant 计量供笔——见
+    // lastUsageFactOf；注入位在则为测试替身/装配覆盖）。
+    // U4-3 三 seam 容器位：席位容器（getConfig/getProvider 晚绑定——plugin-boot
+    // fork 绑定装载面）+ 接管缝派发包装（waterfall + 归因箱种子/读末位）。
+    // 注：options.compaction 注入覆盖时席位容器仍外露（绑定面照常可达）——注入
+    // 替身不走 seam，容器位对其无效果（测试覆盖语义）。
+    const compactionSlots = createCompactionSlots();
+    const dispatchBeforeCompact = async (input) => {
+        // 零监听器直通（boot 未跑/词未注册形——waterfall 面词缺席即拒，守卫免炸）
+        if (!dispatch.isRegistered('session_before_compact'))
+            return { value: input };
+        // 归因箱种子：symbol 键随值链 spread 传播（改写必新建对象律）——plugin-context
+        // 钩子包装层逐跳记名（mark）/铸造（forge），出口读末位改写者
+        const box = {};
+        const seeded = Object.assign({}, input, { [BEFORE_COMPACT_ATTRIB]: box });
+        const value = await dispatch.waterfall('session_before_compact', seeded);
+        return box.lastAdjustedBy === undefined ? { value } : { value, lastAdjustedBy: box.lastAdjustedBy };
+    };
+    const compaction = options.compaction ??
+        createCompactionService({
+            channel: {
+                complete: async ({ prompt, maxChars }) => {
+                    const result = await llm.complete({
+                        messages: [{ role: 'user', content: prompt, timestamp: Date.now() }],
+                        priority: 'foreground',
+                    });
+                    // 文本块拼接 + 预算截断（防御位——prompt 指令是主预算通道）
+                    const text = result.message.content
+                        .filter((block) => block.type === 'text')
+                        .map((block) => block.text)
+                        .join('');
+                    return { text: text.length > maxChars ? text.slice(0, maxChars) : text };
+                },
+            },
+            getConfig: compactionSlots.getConfig,
+            getProvider: compactionSlots.getProvider,
+            onBeforeCompact: dispatchBeforeCompact,
+            warn,
+        });
+    // ④ channels 通道核（投影源在⑤驱动登记之后才被调用——闭包前向引用安全）
+    const channels = createChannels({
+        fetchProjection: (sessionId) => Promise.resolve(projectionOf(sessionId)),
+        history: (sessionId) => Promise.resolve(projectionOf(sessionId)),
+        // /memory 注册位（06 §7——mm 批）：库座在位即注册（persistence 在场 ⇒
+        // memory 件将装载；件缺席形由命令 handler 的 notify 降级提示诚实兜底）
+        memory: true,
+    });
+    // ④½ 会话维视图（e-2 观测腿——SessionView 纯派生读面）：数据三窄面全结构
+    // 兼容直传（store.queryEvents/getSessionRow + manager.listActive 投影——前向
+    // 闭包同 channels 律，首会话起跑时 manager 必已建）；消费位两会话工具族
+    // （durable 形 per-session 闭包）+ 装配根 sessionLineage（订阅 tree 档过滤）
+    const sessionStore = options.runtime.persistence.store;
+    const sessionView = createSessionView({
+        events: sessionStore,
+        sessions: sessionStore,
+        liveSessions: { listActive: () => manager.listActive() },
+        workspaceRoot: workspaceAnchor,
+    });
+    // ④' 出口治理③ 值基腿活值 provider（04 §7 执行段 2026-09-08 落码定形⑤）：
+    // credentials 库 live 读——管道链尾消毒步每次调用现取（工具执行期间新入库
+    // 凭证同受覆盖）。单行解密失败跳过不连坐（其余行照常参与——行级隔离）；
+    // 库整体故障抛给管道侧 catch 降级纯模式腿（降级诚实）。长度 ≥8 过滤在
+    // redactKnownSecretValues 内执法（短值误伤普通文本的灾难面控制）。
+    const sensitiveValues = () => {
+        const values = [];
+        for (const row of options.runtime.persistence.store.listCredentialProviders()) {
+            try {
+                const entry = options.runtime.persistence.store.getCredential(row.namespace, row.provider);
+                if (entry !== undefined && entry.apiKey.length > 0)
+                    values.push(entry.apiKey);
+            }
+            catch {
+                /* 单行坏（解密不匹配等）跳过——消毒面按行降级，不炸 provider */
+            }
+        }
+        return values;
+    };
+    // ⑤ SessionManager：DriverFactory 装配注入族全接线（model = per-fresh-session
+    // 覆盖 ?? 栈缺省——create init.model 透传位，触发器 starter 载体，C 批 C-3；
+    // systemPrompt/shapeTools/askApproval = 批 19c-1 per-session 装配覆盖通道——
+    // in-process 子代理工厂消费位：系统提示覆盖、派生面白名单整形、审批升父面；
+    // extraTools = 会话维追加工具面（成熟度缺口 #5——issue 起会腿消费位：件注册
+    // 的只读工具面经 open 域管道注册位并入，真三段管道零旁路）
+    const createDriver = ({ session, model: sessionModel, systemPrompt, shapeTools, askApproval, extraTools, }) => {
+        const sessionId = session.sessionId;
+        // 审批桥：driver 与 open 域工具共用同一 per-session ask 面（07 §4.3 提问队列）；
+        // 工厂注入覆盖在场时胜出（委派边界①——子会话审批落父会话呈现面，04 §10）
+        const askFace = askApproval ??
+            ((request, opts) => channels.askApproval(sessionId, request, opts));
+        let tools;
+        let settleApprovals;
+        // 工具归因取值器（T9 案一批 t-1——tool/call 载荷 owner 位）：assembly
+        // 在场时从会话注册表构造（listFor 两层并集 live 查询——覆盖装配后动态
+        // 注册）；memory 形（无工具面）保持 undefined——纯对话 run 无 tool/call
+        let resolveToolOwner;
+        if (options.runtime.dataDir !== null) {
+            // goal 段换装（批 19c-3——03 §10.5）：goal 件在场 + 锚注入在位 →
+            // per-session 扩展 todo 工具替换内置件（openTools todoTool 注入位——
+            // 词面独立律 conversation 域零 goal 知识；未装载/锚缺席 = 内置件）
+            const goalFace = scope.tryGet('goal');
+            const goalTodo = goalFace !== undefined && options.goalScopeFor !== undefined
+                ? goalFace.todoFactory({
+                    append: (data) => session.append('todo/write', data),
+                    getScope: () => options.goalScopeFor?.(sessionId) ?? null,
+                })
+                : undefined;
+            // 会话维工具族（e-2 观测腿——03 §10.8 恒挂载四件；per-session 闭包
+            // callerSessionId 注入〔todoTool 换装 seam 同构〕；跨树门检输入经
+            // observeCross seam——装配已接 doors 段活体真源 + capability/used
+            // 审计〔assembly；缺席形 ?? 空集 = 测试/未装配兜底〕）
+            const sessionTools = createSessionTools({
+                view: sessionView,
+                callerSessionId: sessionId,
+                getOpens: () => options.observeCross?.getOpens() ?? new Set(),
+                ...(options.observeCross?.onCapabilityUsed !== undefined
+                    ? { onCapabilityUsed: options.observeCross.onCapabilityUsed }
+                    : {}),
+                // e-3 环境自感窄面（03 §10.8 session_status 并入注）：工具清单 =
+                // 本会话整形后面（shapeTools 白名单后的可见面——子代理派生面自省
+                // 即其子实面，04 §10「孙代委派以子实面为基准」同律；lazy 读，execute
+                // 时点装配已完成）；门态 = 与门检同吃 caller 感知合成源（开门制扩展批
+                // ——本会话即模型道 caller：观测门 doors 段单独、操控门 getOpensFor
+                // session caller 形；reason 与执行时拒绝 message 同源——先查后用）
+                env: {
+                    listTools: () => (tools ?? []).map((entry) => ({ name: entry.name })),
+                    doorStates: () => {
+                        const opens = options.observeCross?.getOpens() ?? new Set();
+                        const verdict = adjudicateCapabilityDoor(opens, OBSERVE_CROSS_CAPABILITY);
+                        const controlVerdict = adjudicateCapabilityDoor(options.controlCross?.getOpensFor({ kind: 'session', sessionId }) ?? new Set(), CONTROL_CROSS_CAPABILITY);
+                        return [
+                            {
+                                capability: OBSERVE_CROSS_CAPABILITY,
+                                open: verdict.ok,
+                                ...(verdict.ok ? {} : { reason: verdict.message }),
+                                scope: '跨树会话枚举与读取（session_list/session_read/session_trace 跨树目标）',
+                            },
+                            {
+                                capability: CONTROL_CROSS_CAPABILITY,
+                                open: controlVerdict.ok,
+                                ...(controlVerdict.ok ? {} : { reason: controlVerdict.message }),
+                                scope: '跨会话操控三动词（session_send/session_interrupt/session_withdraw——全域同门无树内豁免）',
+                            },
+                        ];
+                    },
+                    // ap-3 第四段数据源（03 §10.8 ap-3 定形注）：装配期快照 + 整名族
+                    // dryRun 闭包（matchToolPolicy 同源——obs 零 safety 依赖的桥位）；
+                    // 策略表功能缺席（options.toolPolicy undefined）= getter 返 undefined
+                    // ——obs 段不呈现。dryRun 只喂整名族条目（write/edit/bash 条目命中
+                    // 依赖调用实参，整名干跑恒 miss——闭包内过滤防假报）
+                    ...(options.toolPolicy !== undefined
+                        ? {
+                            toolPolicy: () => {
+                                // memory 形降级防御：dataDir 缺席（正常装配下不共现——
+                                // assembly 只在 dataDir 非空时穿 toolPolicy）= 段不呈现
+                                if (options.runtime.dataDir === null)
+                                    return undefined;
+                                const wholeName = options.toolPolicy.filter((e) => e.tool !== 'write' && e.tool !== 'edit' && e.tool !== 'bash');
+                                return {
+                                    entries: options.toolPolicy.map((entry, index) => ({
+                                        index,
+                                        tool: entry.tool,
+                                        ...(entry.pattern !== undefined ? { pattern: entry.pattern } : {}),
+                                        ...(entry.effect !== undefined ? { effect: entry.effect } : {}),
+                                        decision: entry.decision,
+                                        ...(entry.reason !== undefined ? { reason: entry.reason } : {}),
+                                        ...(entry.expiresAt !== undefined ? { expiresAt: entry.expiresAt } : {}),
+                                    })),
+                                    path: join(options.runtime.dataDir, TOOL_POLICY_BASENAME),
+                                    dryRun: (tool, effect) => {
+                                        const hit = matchToolPolicy(wholeName, { tool, effect }, Date.now());
+                                        return hit === undefined ? undefined : { decision: hit.entry.decision, index: hit.index };
+                                    },
+                                };
+                            },
+                        }
+                        : {}),
+                },
+            });
+            const assembly = assembleOpenTools({
+                sessionId,
+                dispatch,
+                session,
+                scope,
+                mode: sandboxMode,
+                dataDir: options.runtime.dataDir,
+                workspace: workspaceAnchor,
+                askApproval: askFace,
+                ...(options.toolPolicy !== undefined ? { toolPolicy: options.toolPolicy } : {}),
+                ...(options.persistToolPolicy !== undefined ? { persistToolPolicy: options.persistToolPolicy } : {}),
+                // 审批策略档穿线（04 §9 两旋钮——装配根四层解析胜者；缺省不注入 =
+                // approval 服务内缺省 'ask'）
+                ...(options.approvalPolicy !== undefined ? { policy: options.approvalPolicy } : {}),
+                // 会话维工具族并入扩展位（bootTools 同位——模型可见清单恒在律）；
+                // 操控三件同位并入（e-4——恒挂载，门检在受理器内执法）；
+                // ccr_retrieve 同位并入（05 §2.1 压缩可逆性——恒挂载：压缩归档原文
+                // 回取面，turn 1 起在场永不摘除；memory 形随工具整面缺席）；
+                // extraTools 会话维追加位（缺口 #5——issue 工具面经管道注册并入，
+                // boot 全局层之后、会话族之前：宿主全局面 → 本会话编排面 → 观测族）
+                extraTools: () => [
+                    ...(options.bootTools?.() ?? []),
+                    ...(extraTools?.() ?? []),
+                    ...sessionTools,
+                    ...createControlTools({ callerSessionId: sessionId, control: sessionsControl }),
+                    ...createCcrRetrieveTool({ events: () => session.events() }),
+                ],
+                ...(goalTodo !== undefined ? { todoTool: goalTodo } : {}),
+                sensitiveValues, // 出口消毒值基腿（栈级单闭包——多会话装配共享，live 读）
+            });
+            options.runtime.registerDisposer(assembly.dispose); // LIFO 拆解进运行时退出序
+            // 整形钩子（批 19c-1）：装配产物进驱动前整形（语义归调用方——子代理
+            // 派生面执法；fullTools 快照即整形后面——孙代委派以子实面为基准）
+            tools = shapeTools !== undefined ? [...shapeTools(assembly.tools)] : assembly.tools;
+            // owner 取数闭包：装配产物 registry 即会话注册表——宿主直构件已盖
+            // 'core:host'、extraTools 重放的插件定义携插件 id owner，listFor 全量
+            // 可查（live 形——named provider 程序化注册等后续注册天然覆盖）
+            resolveToolOwner = (name) => assembly.registry.listFor(sessionId).find((def) => def.name === name)?.owner;
+            settleApprovals = assembly.settlePending;
+        } // memory 形：工具整面缺席——纯对话 run（件头注降级语义）
+        const driver = new ConversationDriver({
+            session,
+            scope,
+            dispatch,
+            streamFn,
+            convertToLlm: (message) => isStandardMessage(message) ? message : (getMessageRoleDefinition(message.role)?.toLlm?.(message) ?? null),
+            model: sessionModel ?? model,
+            ...(tools !== undefined ? { tools } : {}),
+            // tool/call 载荷 owner 位取数（T9 案一批 t-1——memory 形 undefined 不带）
+            ...(resolveToolOwner !== undefined ? { resolveToolOwner } : {}),
+            // lane 帽取位器（04 §4——channels 消息语义批 m-2）：followUp 起跑前
+            // 取位、run 终态释放；排队不计在飞（冷读闸 M1 裁决）。栈级单 gate
+            // 全会话共享——「宿主级」并发数的真源。
+            acquireRunSlot: runLane,
+            ...(options.thinkingLevel !== undefined ? { thinkingLevel: options.thinkingLevel } : {}),
+            // per-session 覆盖 ?? 栈基线（open/resume 不携带——回落基线同 model 律）
+            ...((systemPrompt ?? options.systemPrompt) !== undefined
+                ? { systemPrompt: systemPrompt ?? options.systemPrompt }
+                : {}),
+            ...(options.pluginSections !== undefined ? { pluginSections: options.pluginSections } : {}),
+            // goal 段升格锚穿线（批 19c-3——驱动 fold 升格消费位 driver.ts）
+            ...(options.goalScopeFor !== undefined ? { goalScopeFor: options.goalScopeFor } : {}),
+            // goal 轮间沉淀 + 记账回执穿线（批 #99——sessionId 位在此落格绑定）
+            ...(options.goalDeposit !== undefined ? { goalDeposit: () => options.goalDeposit(sessionId) } : {}),
+            // 预算预警穿线（批 H——04 §5 软着陆层 + 修复批 run 车道透传）：sessionId
+            // 落格绑定同 goalDeposit 形；backgroundLane = 驱动侧当前 run 声明位
+            ...(options.budgetAdvisory !== undefined
+                ? { budgetAdvisory: (backgroundLane) => options.budgetAdvisory(sessionId, backgroundLane) }
+                : {}),
+            // run 结算回执链（无条件装——2026-09-13 复盘修复 #41/#44 记账桥接单点）：
+            // 桥接落账先于消费侧钩（usage 底账近源先行；goal recordTurn 等
+            // options.onRunSettled 消费者随后——批 #99 既有链不破）。session 直接
+            // 取闭包本尊（settle 时点即本驱动日志——不经 manager 回查）
+            onRunSettled: (receipt) => {
+                bridgeUsageLedger(session, sessionModel ?? model, receipt);
+                options.onRunSettled?.(sessionId, receipt);
+            },
+            classifyError,
+            compactForOverflow: (log) => compaction.compactForOverflow(log),
+            environmentDisclosure: options.runtime.disclosure,
+            askApproval: askFace,
+            ...(settleApprovals !== undefined ? { settleApprovals } : {}),
+            warn,
+            onEvent: (event) => channels.emit({ sessionId, event }),
+            retry: DEFAULT_RETRY_POLICY,
+        });
+        return driver;
+    };
+    const manager = new SessionManager({
+        persistence: options.runtime.persistence,
+        dispatch,
+        createDriver,
+        // 单会话收口观察穿线（发现 ⑯——缺席形不设位保持测试替身零观察）
+        ...(options.onSessionRetired !== undefined ? { onRetired: options.onSessionRetired } : {}),
+    });
+    // 操控受理器（e-4——03 §2.2 第十一面双面同源单源实现位）：栈级单例——
+    // 工具族（模型道 per-session 闭包）与 plugin-boot fork 绑定（插件道）消费
+    // 同一实例。门检 caller 感知合成 + 审计经 controlCross seam（开门制扩展批
+    // ——装配根接 doors 段 ∪ 行 opens 双源，模型道 doors 段单独）
+    const sessionsControl = createSessionsControl({
+        manager,
+        getOpensFor: (caller) => options.controlCross?.getOpensFor(caller) ?? new Set(),
+        ...(options.controlCross?.onCapabilityUsed !== undefined
+            ? { onCapabilityUsed: options.controlCross.onCapabilityUsed }
+            : {}),
+    });
+    // 阈值触发器：run 终态 → 该会话日志入阈值判定（fire-and-forget）。判阈双源
+    // 的真 token 主判在此供笔（lastUsageFactOf——日志末条 assistant 计量）；零计量
+    // 不携带 → 服务侧回落投影字符估算（estimate 兜底档）
+    agentService.onRunSettled((event) => {
+        const driver = manager.driverOf(event.sessionId);
+        if (driver !== undefined)
+            compaction.handleRunSettled({ log: driver.session, ...lastUsageFactOf(driver.session) });
+    });
+    /** 投影拉取：驱动活体优先（内存最新鲜），未开回库装载（双事实源纪律同律） */
+    async function projectionOf(sessionId) {
+        const log = manager.driverOf(sessionId)?.session ?? options.runtime.persistence.loadSession(sessionId).log;
+        const events = log.events();
+        return reseedTimeline(deriveMessages(events), (seq) => events[seq]?.time ?? 0);
+    }
+    // 退出序接线：closer 注册序即 drain 序——先拆驱动（打断在飞 run）再排空压缩链
+    options.runtime.registerCloser({ label: 'conversation-manager', fn: () => manager.dispose() });
+    options.runtime.registerCloser({
+        label: 'compaction-drain',
+        fn: () => compaction.drain(),
+    });
+    return {
+        manager,
+        channels,
+        llm,
+        llmRuntime,
+        scope,
+        dispatch,
+        model,
+        sessionView,
+        sessionsControl,
+        compactionSlots,
+        projectionOf,
+        driverOf: (sessionId) => manager.driverOf(sessionId),
+        submitText(sessionId, text, submitOptions) {
+            const driver = manager.driverOf(sessionId);
+            if (driver === undefined)
+                return undefined; // 未开会话——上层提交序不达（理论不达防御位）
+            const run = driver.submit(text, submitOptions);
+            // 回执面错误经 notify 回流呈现面（fire-and-forget 无未处理拒绝；await 方仍得真回执）
+            void run.catch((err) => {
+                channels.notify(sessionId, `提交失败：${err instanceof Error ? err.message : String(err)}`, {
+                    level: 'error',
+                });
+            });
+            return run;
+        },
+        interrupt(sessionId) {
+            manager.driverOf(sessionId)?.abort();
+        },
+        openStartupSession(cwd) {
+            const workspaceRoot = canonicalWorkspaceRoot(cwd);
+            // 按 cwd 归一根取最新会话（会话表 workspace_root 选取键——07 §5 策略真源）
+            const [latest] = manager.list({ workspaceRoot, limit: 1 });
+            if (latest !== undefined) {
+                const opened = manager.open(latest.id);
+                return { ...opened, resumed: true, workspaceRoot };
+            }
+            const created = manager.create({ workspaceRoot });
+            return { ...created, resumed: false, workspaceRoot };
+        },
+    };
+}
+/**
+ * 末次真计量笔（05 §2.1 判阈双源「真 token 主判」的供笔侧）：取日志**末条**
+ * assistant/message 事件的计量快照（provider 报数随落账原样在场——05 §1.1）。
+ *
+ * 取值律：
+ * - 只看末条不回溯——上一轮的 input 是上一形态的真值、不是本轮的，回溯即拿
+ *   旧值冒充新真值（真值可用时不猜，真值缺席就明说缺席）；
+ * - 零值/坏形（中止早退、脚本零报形）= 无真值：返回不携带，调用方回落投影
+ *   字符估算（chars/4——estimate 兜底档语义在此保底而非在服务侧猜测）；
+ * - contextWindow 不供（栈面只有模型 id 无目录查询）——分母归服务侧
+ *   fallbackWindowTokens 缺省，与估算档同分母。
+ */
+export function lastUsageFactOf(log) {
+    const events = log.events();
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.type !== 'assistant/message')
+            continue;
+        const data = event.data;
+        const usage = typeof data === 'object' && data !== null ? data.usage : undefined;
+        if (typeof usage === 'object' &&
+            usage !== null &&
+            typeof usage.input === 'number' &&
+            usage.input > 0) {
+            // cache 两桶同笔带出（cache 经济批 RP4——basis 五件的数据源）：与 input
+            // 同一事件同一读笔，缺桶/非数不猜（透传面收敛 number 判）
+            const record = usage;
+            return {
+                usage: {
+                    input: record.input,
+                    ...(typeof record.cacheRead === 'number' ? { cacheRead: record.cacheRead } : {}),
+                    ...(typeof record.cacheWrite === 'number' ? { cacheWrite: record.cacheWrite } : {}),
+                },
+            };
+        }
+        return {}; // 末条已见而无可信计量——无真值不猜（不回溯）
+    }
+    return {}; // 无 assistant 事件（空 run/纯消费防御路径）
+}
+/**
+ * lane 帽缺省容量（04 §4——码面缺省参数非契约常数，观测证据可再裁；
+ * 对齐常见 LLM 供应商并发档量级）。
+ */
+export const DEFAULT_RUN_LANE_CAPACITY = 16;
+/**
+ * lane 帽容量解析（04 §4 宿主级 run 并发帽——channels 消息语义批 m-2）：
+ * 解析序 = 显式覆盖位 > env `BERRY_AGENT_MAX_CONCURRENT_RUNS` > 缺省 16。
+ * 非正整数 fail-loud 拒（RangeError）——空帽/坏帽是死配置（queue capacity
+ * 同律）。
+ */
+export function resolveRunLaneCapacity(override, env) {
+    const raw = override ?? env['BERRY_AGENT_MAX_CONCURRENT_RUNS'];
+    if (raw === undefined)
+        return DEFAULT_RUN_LANE_CAPACITY;
+    // 字串形全串 /^\d+$/ 判——parseInt 截停会把 '16x'/'16.5'/'0x10'/'+16'/' 16' 类
+    // 尾随垃圾静默放行成 16，与「空帽/坏帽是死配置」的 fail-loud 自述相悖
+    let value;
+    if (typeof raw === 'number') {
+        value = raw;
+    }
+    else if (/^\d+$/.test(raw)) {
+        value = Number.parseInt(raw, 10);
+    }
+    else {
+        value = Number.NaN;
+    }
+    if (!Number.isInteger(value) || value < 1) {
+        throw new RangeError(`lane 帽容量须为正整数，收到 ${String(raw)}——空帽/坏帽是死配置（BERRY_AGENT_MAX_CONCURRENT_RUNS / maxConcurrentRuns）`);
+    }
+    return value;
+}
+/** env 名（04 §5——2026-09-13 复盘修复 #44 F3；07 环境变量 BERRY_AGENT_* 前缀族） */
+export const BACKGROUND_BUDGET_TOKENS_ENV = 'BERRY_AGENT_BACKGROUND_BUDGET_TOKENS';
+/**
+ * 当日后台预算限额解析（04 §5 env 旋钮）：env 缺席 = undefined（缺省 4M 由
+ * llm 件单源持有——本函数只产覆盖位）。坏形 fail-loud 启动当场红（与 lane
+ * 帽/静置窗两旋钮同律：坏预算值是死配置，静默回落缺省会吞掉用户显式
+ * 降额/提额意图）。零值合法（显式关池——canAfford 恒 false，停靠腿承接）。
+ */
+export function resolveBackgroundBudgetTokens(env) {
+    const raw = env[BACKGROUND_BUDGET_TOKENS_ENV];
+    if (raw === undefined || raw === '')
+        return undefined;
+    // 字串形全串 /^\d+$/ 判（同 resolveRunLaneCapacity——parseInt 截停防）
+    if (!/^\d+$/.test(raw)) {
+        throw new RangeError(`当日后台预算限额须为非负整数字串，收到 "${raw}"——坏形是死配置（${BACKGROUND_BUDGET_TOKENS_ENV}）`);
+    }
+    return Number.parseInt(raw, 10);
+}
+/** 当日零点毫秒（本地时区——「当日」语义随用户挂钟；04 §5 日池窗） */
+export function startOfTodayMs(now = Date.now()) {
+    const d = new Date(now);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+/**
+ * 当日后台已耗聚合（04 §5 #44 聚合读面——05 §1.1 口径单源）：queryEvents
+ * 当日窗 llm/usage · `priority === 'background'` 过滤 · SUM(input+output)
+ * 主计费桶（cache 桶进观察面板不进闸门）。分页游标走满（页帽顶格 10000——
+ * 当日调用密度远不及帽，走满是完整性防御非热路径）。读失败上抛由调用方
+ * 定姿态（装配位 fail-open + warn——预算软闸门不反噬请求路）。
+ */
+export function aggregateBackgroundSpentToday(store, sinceMs) {
+    let sum = 0;
+    let cursor = undefined;
+    do {
+        const page = store.queryEvents({
+            types: ['llm/usage'],
+            sinceMs,
+            limit: 10_000,
+            ...(cursor !== undefined ? { cursor } : {}),
+        });
+        for (const event of page.events) {
+            const data = event.data;
+            if (data.priority !== 'background')
+                continue; // 前台照入账不进闸门
+            sum += (data.usage?.input ?? 0) + (data.usage?.output ?? 0);
+        }
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor !== undefined);
+    return sum;
+}
+/**
+ * 造宿主级 run 并发闸（04 §4——排队非拒收：帽满排队 FIFO、释放依序续跑；
+ * openclaw CommandLane 先例的宿主级对位）。lane 队列是内存态：退出 drain
+ * 不等待排队件（与 PendingMessageQueue 崩溃即丢同语义——04 §1）。释放器
+ * 幂等（双调安全——driver kick 的 finally 腿防御）。
+ */
+export function createRunLaneGate(capacity) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+        throw new RangeError(`lane 帽容量须为正整数，收到 ${capacity}——空帽是死配置`);
+    }
+    let inFlight = 0;
+    /** FIFO 等位队列（帽满时的挂起取位——resolve 载释放器） */
+    const waiting = [];
+    /** 释放在飞位；有等位者则依 FIFO 直接移交（等位者即刻在飞——无缝续跑） */
+    const releaseSlot = () => {
+        inFlight -= 1;
+        const next = waiting.shift();
+        if (next === undefined)
+            return;
+        inFlight += 1;
+        next(makeRelease());
+    };
+    /** 造幂等释放器（每次取位独立一枚——双调只是无操作，不双扣在飞位） */
+    const makeRelease = () => {
+        let used = false;
+        return () => {
+            if (used)
+                return;
+            used = true;
+            releaseSlot();
+        };
+    };
+    return {
+        tryAcquire() {
+            if (inFlight >= capacity)
+                return undefined;
+            inFlight += 1;
+            return makeRelease();
+        },
+        acquire() {
+            return new Promise((resolve) => {
+                if (inFlight < capacity) {
+                    inFlight += 1;
+                    resolve(makeRelease());
+                    return;
+                }
+                waiting.push(resolve);
+            });
+        },
+        get inFlight() {
+            return inFlight;
+        },
+        get queued() {
+            return waiting.length;
+        },
+    };
+}