berry-agent 0.1.0-alpha.1

package/dist/conversation/index.js

@@ -0,0 +1,12 @@
+export { AGENT_PRE_STEP_EVENT, CONTEXT_TRANSFORM_EVENT, DEFAULT_RETRY_POLICY, SESSION_LIFECYCLE_EVENT, } from './types.js';
+export { reseedTimeline } from './reseed.js';
+export { ConversationDriver } from './driver.js';
+// 操控面码注册（02 §5.3 SESSION_ 族操控五码——e-4 落码批；import 发生才注册）
+import './codes.js';
+export { A2A_ROUND_LIMIT_DEFAULT, bindControlForPlugin, CONTROL_CROSS_CAPABILITY, controlSourceOf, createSessionsControl, SESSIONS_CONTROL_SERVICE, } from './control.js';
+export { createControlTools } from './control-tools.js';
+export { TODO_ROLE, createTodoTool, ensureTodoRole, foldTodoTable, renderTodoTable, todoSnapshotMessage, } from './todo.js';
+export { wireSessionApproval } from './approval-wiring.js';
+export { assembleOpenTools } from './open-tools.js';
+export { AGENT_SERVICE_NAME, notifyRunSettled, provideAgentService } from './agent-service.js';
+export { SESSION_HOOK_NAMES, SessionManager } from './sessions.js';

package/dist/conversation/model-visible.js

@@ -0,0 +1,169 @@
+import { isStandardMessage } from '../contracts/index.js';
+import { normalizeUsage } from './reseed.js';
+/** 预算刀降级标记核心串（session/budget.ts 真源标记的稳定子串） */
+const DEGRADATION_MARKERS = ['…[truncated ', 'image-blob-dropped'];
+/** 诊断摘录帽（红消息里的规范形截断长度——诊断可读性，非语义面） */
+const SNIPPET_LIMIT = 240;
+/**
+ * 规范序列化：对象键递归排序的确定性 JSON（键序不敏感对拍的前提——两侧
+ * 构造路径独立，键插入序天然可异）。undefined 值键随 stringify 丢弃——
+ * 「在场 undefined ≡ 缺席」正是白名单外的兜底语义。
+ */
+function canonicalJson(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            const record = val;
+            const sorted = {};
+            for (const key of Object.keys(record).sort())
+                sorted[key] = record[key];
+            return sorted;
+        }
+        return val;
+    });
+}
+/** 诊断摘录（超帽截断加省略号——红消息不吞日志） */
+function snippet(text) {
+    return text.length <= SNIPPET_LIMIT ? text : `${text.slice(0, SNIPPET_LIMIT)}…`;
+}
+/**
+ * assistant 内容块规范形：toolCall 块归尾（与 reseedTimeline「装回尾部」
+ * 同律——durable 分立事件下交错序无账，两侧都归一到尾部序再对拍）。
+ */
+function canonicalAssistantContent(blocks) {
+    const plain = [];
+    const calls = [];
+    for (const block of blocks) {
+        if (block.type === 'toolCall')
+            calls.push({ type: 'toolCall', id: block.id, name: block.name, arguments: block.arguments });
+        else
+            plain.push(block);
+    }
+    return [...plain, ...calls];
+}
+/** 单消息规范形（model-visible 白名单——见件头注） */
+function canonicalMessageForm(message) {
+    if (!isStandardMessage(message)) {
+        // 自定义角色：role + content 原样对拍（对拍红素材——wiring 零 durable
+        // 写点位，活侧出现即暗通道候选，规范形不吞）
+        return { kind: 'custom', role: message.role, content: message.content };
+    }
+    switch (message.role) {
+        case 'user':
+            return { kind: 'user', content: message.content };
+        case 'assistant':
+            return {
+                kind: 'assistant',
+                content: canonicalAssistantContent(message.content),
+                usage: normalizeUsage(message.usage),
+                stopReason: message.stopReason,
+                ...(message.errorMessage !== undefined ? { errorMessage: message.errorMessage } : {}),
+            };
+        case 'toolResult':
+            return {
+                kind: 'toolResult',
+                toolCallId: message.toolCallId,
+                toolName: message.toolName,
+                content: message.content,
+                isError: message.isError,
+            };
+    }
+}
+/**
+ * 单消息结构形（预算刀豁免位的内容降级对拍）：角色 / toolCall id·name
+ * 清单（arguments 豁免——被截后解析兜底 {}，与真值永假）/ stopReason /
+ * isError。内容文本腿豁免（刀后字节级对拍永假）。
+ */
+function structuralMessageForm(message) {
+    if (!isStandardMessage(message))
+        return { kind: 'custom', role: message.role };
+    switch (message.role) {
+        case 'user':
+            return { kind: 'user' };
+        case 'assistant':
+            return {
+                kind: 'assistant',
+                plainBlockTypes: message.content.filter((block) => block.type !== 'toolCall').map((block) => block.type),
+                calls: message.content
+                    .filter((block) => block.type === 'toolCall')
+                    .map((block) => ({ id: block.id, name: block.name })),
+                stopReason: message.stopReason,
+            };
+        case 'toolResult':
+            return {
+                kind: 'toolResult',
+                toolCallId: message.toolCallId,
+                toolName: message.toolName,
+                isError: message.isError,
+            };
+    }
+}
+/** 投影原始形的消息级降级扫描（canonicalJson 全文含任一标记即降级位） */
+function projectedIsDegraded(projected) {
+    const raw = projected.type === 'user'
+        ? projected.content
+        : projected.type === 'assistant'
+            ? {
+                content: projected.content,
+                toolCalls: projected.toolCalls,
+                ...(projected.errorMessage !== undefined ? { errorMessage: projected.errorMessage } : {}),
+            }
+            : { output: projected.output, arguments: projected.arguments };
+    const text = canonicalJson(raw);
+    return DEGRADATION_MARKERS.some((marker) => text.includes(marker));
+}
+/**
+ * 降级掩码（预算刀豁免位清单）：投影逐消息判降级——掩码[i] = true 表示
+ * 第 i 条重建消息源自被截事件，对拍降为结构级。掩码从投影原始形判而非
+ * 重建形：arguments 被截后 reseedTimeline 解析兜底 {}，标记在重建形已蒸发，
+ * 唯投影形（事件 data 原值）保真。
+ */
+export function degradationMask(projection) {
+    return projection.map(projectedIsDegraded);
+}
+/** 角色名（诊断用——缺位形明示） */
+function roleOf(message) {
+    return message === undefined ? '（缺位）' : message.role;
+}
+/** 红消息构造（首分歧位 + 双形摘录 + 病灶指认——fail-loud 诊断面） */
+function driftError(index, live, expected, reason, liveForm, expectedForm) {
+    return new Error(`模型可见即已记录对拍红（05 §1.2 总拍）：timeline 活数组与日志重建漂移——${reason}。` +
+        `首分歧位 ${index}：live ${roleOf(live[index])} vs 重建 ${roleOf(expected[index])}。` +
+        `live 形 ${snippet(canonicalJson(liveForm))}；重建形 ${snippet(canonicalJson(expectedForm))}。` +
+        `驱动 bug——存在绕过 durable 落账的模型可见写入（loop「入列↔emit」对偶被绕过）或落账翻译腿失真（wiring 翻译丢字段/变形）`);
+}
+/**
+ * 请求关口总拍断言（05 §1.2——恒开执法位唯一消费面是 driver.onTransformContext
+ * 入口）。逐条规范形比对；degraded[i] = true 的位置降为结构形比对（预算刀
+ * 豁免）；长度差单列诊断。等价零动作，漂移 throw（驱动 bug 语义——与
+ * occludeFailedTail 锚缺席同律，不占公开错误码面）。
+ *
+ * @param live 驱动 timeline 活数组（请求组装时点的模型可见持久消息序列）
+ * @param expected 日志独立重建（reseedTimeline 产物——与 live 同源不同路）
+ * @param degraded 降级掩码（degradationMask 产物；缺省全 false）
+ */
+export function assertModelVisibleTimeline(live, expected, degraded) {
+    const n = Math.min(live.length, expected.length);
+    for (let i = 0; i < n; i += 1) {
+        if (degraded?.[i] === true) {
+            // 预算刀豁免位：结构形比对（内容腿降级——刀后字节级对拍永假）
+            const liveForm = structuralMessageForm(live[i]);
+            const expectedForm = structuralMessageForm(expected[i]);
+            if (canonicalJson(liveForm) !== canonicalJson(expectedForm)) {
+                throw driftError(i, live, expected, '结构异（预算刀豁免位——内容腿已降级，结构仍不等价）', liveForm, expectedForm);
+            }
+            continue;
+        }
+        const liveForm = canonicalMessageForm(live[i]);
+        const expectedForm = canonicalMessageForm(expected[i]);
+        if (canonicalJson(liveForm) !== canonicalJson(expectedForm)) {
+            throw driftError(i, live, expected, '内容异（规范形不等价）', liveForm, expectedForm);
+        }
+    }
+    if (live.length !== expected.length) {
+        // 长度差诊断（前 n 条已逐条过拍——本红专指尾部多出/缺失）
+        const surplus = live.length > expected.length
+            ? 'live 多出——存在绕过 durable 落账的模型可见写入（暗通道）'
+            : '重建多出——存在落账后未入 timeline 的 surplus（翻译腿多写/入列腿漏推）';
+        throw new Error(`模型可见即已记录对拍红（05 §1.2 总拍）：timeline 活数组与日志重建漂移——长度差：live ${live.length} 条 vs 重建 ${expected.length} 条（前 ${n} 条规范形等价；${surplus}）。驱动 bug fail-loud`);
+    }
+}

package/dist/conversation/open-tools.js

@@ -0,0 +1,126 @@
+/**
+ * fresh 作用域审批三件之③（04 §9 守门安装）+ open 域工具装配——会话级
+ * 工具面的组装面（04 §7 三段管道唯一合法路径执法位 / 03 §2.3 defineTool 形）。
+ *
+ * 装配序（一次成型，host 装配根 / 驱动测试面注入）：
+ *  ① 词汇接线——工具族事件词注册（contracts TOOL_EVENT_NAMES 的装配消费面）；
+ *  ② 审批三件前两件（wireSessionApproval：服务 + answerer + settlePending）；
+ *  ③ 守门安装（installSafetyGate **先装本行**——waterfall 注册序即执行序，
+ *     carve-out 硬拒 / 策略表 allow 免问 / write-effect 审批对最先执法；后续
+ *     守门者（插件拦截族）装在其后）；
+ *  ④ 管道 + 注册表（gate/decision durable 落账接线——守门不可绕不变式的
+ *     断言对象）；
+ *  ⑤ 工具族：fs 四件（read/write/edit/ls——fence 数据源 createRootsProvider
+ *     与守门行同档位单源）+ 检索两件（find/grep）+ bash（exec 服务面
+ *     scope.tryGet 诚实缺席——exec 禁用 = coding 降级对话本体仍通）+
+ *     todo 一件（全量快照 durable 落 todo/write）。
+ *
+ * 工具注册走注册表驱动层（{driver: sessionId}——per-session 工具面）；
+ * agentToolsFor 快照即驱动 tools 面直用形。dispose 按 LIFO 拆解（工具注册 →
+ * 守门 → answerer）。
+ */
+import { canonicalWorkspaceRoot } from '../context/index.js';
+import { TOOL_EVENT_NAMES } from '../contracts/index.js';
+import { createRootsProvider, installSafetyGate, sensitiveReadFiles } from '../safety/index.js';
+import { createFsTools, createSearchTools, createToolPipeline, createToolRegistry } from '../tools/index.js';
+import { wireSessionApproval } from './approval-wiring.js';
+import { createTodoTool } from './todo.js';
+/**
+ * 组装 open 域工具面 + 审批守门。**一次成型**：返回的 tools 快照经真三段
+ * 管道执行（schema → 守门 → 执行——04 §7 唯一合法路径），驱动侧零旁路。
+ */
+export function assembleOpenTools(opts) {
+    const workspace = opts.workspace ?? (() => canonicalWorkspaceRoot());
+    const workspaceRoot = workspace();
+    // ① 工具族事件词接线（contracts TOOL_EVENT_NAMES 装配消费面）。一词两册
+    // 幂等跳过（03 §2.4 装配序律——装载批预注册主表镜像在前，已注册词共享
+    // 登记非撞名覆盖；未注册词自举注册保单测独立装配）。装配哨兵词同走幂等
+    // 跳过（批 19c-1 修正：「同 dispatch 二次装配 = bug」前提随多会话装配废止
+    // ——in-process 子代理真工厂首例〔同栈父子两会话各装配一次〕；「同一会话
+    // 重复装配」检测由 SessionManager records 幂等守卫承担——open 幂等回
+    // 活体驱动不二造）
+    opts.dispatch.registerEventNames(['conversation/open-tools-mounted', ...TOOL_EVENT_NAMES].filter((name) => !opts.dispatch.isRegistered(name)));
+    // ② 审批三件前两件（服务 + answerer + 审批对 durable 落账）
+    const approvalWiring = wireSessionApproval({
+        sessionId: opts.sessionId,
+        dispatch: opts.dispatch,
+        session: opts.session,
+        ...(opts.askApproval !== undefined ? { askApproval: opts.askApproval } : {}),
+        ...(opts.policy !== undefined ? { policy: opts.policy } : {}),
+        ...(opts.persistToolPolicy !== undefined ? { persistToolPolicy: opts.persistToolPolicy } : {}),
+    });
+    // ③ 守门安装（先装本行——waterfall 注册序即执行序，本行最先执法；
+    // sessionId 归属位 = 会话归属过滤——他会话〔in-process 子代理等〕的工具
+    // 调用本行让棒，防止同栈多会话装配时同一 toolCall 被多行各问一次审批）
+    const uninstallGate = installSafetyGate(opts.dispatch, {
+        approval: approvalWiring.approval,
+        sessionId: opts.sessionId,
+        workspace: workspaceRoot,
+        mode: opts.mode,
+        dataDir: opts.dataDir,
+        ...(opts.toolPolicy !== undefined ? { toolPolicy: opts.toolPolicy } : {}),
+        ...(opts.entries !== undefined ? { entries: opts.entries } : {}),
+    });
+    // ④ 管道 + 注册表（gate/decision durable 落账——守门不可绕不变式的载体；
+    // sensitiveValues 透传 = 出口治理③ 值基腿接线，管道链尾消毒步消费）
+    const pipeline = createToolPipeline(opts.dispatch, {
+        onGateDecision: (record) => opts.session.append('gate/decision', record),
+        ...(opts.sensitiveValues !== undefined ? { sensitiveValues: opts.sensitiveValues } : {}),
+    });
+    const registry = createToolRegistry(opts.dispatch, { pipeline });
+    // ⑤ 工具族装配（fs fence 数据源与守门行同档位单源——createRootsProvider；
+    // fs/search 两族读侧 carve-out 同注入位——sensitiveReadFiles 单源派生，与
+    // 沙箱 profile 读 deny 行同数据〔2026-09-08 P0① 两腿同源〕）
+    const fsTools = createFsTools({
+        workspace,
+        writableRoots: createRootsProvider({ workspace: workspaceRoot, mode: opts.mode }),
+        protectedReadFiles: () => sensitiveReadFiles(opts.dataDir),
+    });
+    const searchTools = createSearchTools({
+        workspace,
+        protectedReadFiles: () => sensitiveReadFiles(opts.dataDir),
+    });
+    // exec 服务面诚实缺席（02 §4.1 #16：tryGet——exec 禁用 = bash 静默缺席）；
+    // 在场则经会话装配期工厂求值 bash 工具（批 19a 定形：档位/审批/工作区
+    // 会话 deps 注入——装载期固定构造会丢会话面）
+    const execService = opts.scope.tryGet('exec');
+    const bashTool = execService !== undefined
+        ? execService.createBashTool({
+            workspaceRoot: workspace,
+            currentMode: opts.mode,
+            // 升权审批面绑本会话审批服务（结构窄面 {ask}——ApprovalService 满足）
+            approval: { ask: (req) => approvalWiring.approval.ask(req) },
+        })
+        : undefined;
+    // todo 工具：goal 换装注入位胜出（03 §10.5），缺省本域内置件
+    const todoTool = opts.todoTool ?? createTodoTool((data) => opts.session.append('todo/write', data));
+    const definitions = [
+        ...fsTools.tools,
+        ...searchTools.tools,
+        ...(bashTool !== undefined ? [bashTool] : []),
+        todoTool,
+        // 装载工具重放（批 19a 消费腿：boot 全局层定义经驱动层注册走真三段
+        // 管道——04 §7 插件工具同管线执法；每会话重放一次，快照在装配时点取）
+        ...(opts.extraTools !== undefined ? [...opts.extraTools()] : []),
+    ];
+    // 驱动层注册（{driver: sessionId}——per-session 工具面；批 12 前插件的
+    // beforeToolCall 钩子同 dispatch 挂后续守门位）；owner 缺省盖章
+    // 'core:host'（03 §2.3 尾注族谱——T9 案一批 t-1）：本注册点是宿主装配
+    // 工具的唯一入口，未带 owner 的定义即宿主直构件（fs/search/bash/todo +
+    // obs/control extraTools 族）；extraTools 重放腿携带的插件定义已被受理壳
+    // 铸得插件 id owner——`??` 缺省式不覆盖，插件归因原样存活到会话层
+    const disposers = definitions.map((definition) => registry.register({ ...definition, owner: definition.owner ?? 'core:host' }, { driver: opts.sessionId }));
+    return {
+        tools: registry.agentToolsFor(opts.sessionId),
+        registry,
+        approval: approvalWiring.approval,
+        settlePending: approvalWiring.settlePending,
+        dispose() {
+            // LIFO 拆解：先摘工具注册（含执行面）→ 守门 → answerer
+            for (const dispose of disposers.reverse())
+                dispose();
+            uninstallGate();
+            approvalWiring.dispose();
+        },
+    };
+}

package/dist/conversation/reseed.js

@@ -0,0 +1,132 @@
+/** StopReason 闭集（成员校验用——contracts 联合的运行时镜像） */
+const STOP_REASONS = new Set([
+    'pending',
+    'stop',
+    'length',
+    'toolUse',
+    'error',
+    'aborted',
+    'deferred',
+]);
+/** 零用量兜底形（usage 未知/损坏时——0 值不冒充计量，底账在 llm/usage 事件） */
+const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+};
+/**
+ * usage 归一（unknown → Usage 必填形）：数值字段 finite 才取，任一主字段
+ * 缺损即整笔退零用量（半拼凑的 usage 比零用量更有害——计量面要么完整
+ * 要么明示没有）。导出面：模型可见总拍（model-visible.ts）两侧同归一复用
+ * ——对拍等价判据以本归一为准（undefined ≡ 零用量兜底），单一归一源。
+ */
+export function normalizeUsage(usage) {
+    if (usage === null || typeof usage !== 'object')
+        return ZERO_USAGE;
+    const u = usage;
+    const num = (key) => {
+        const v = u[key];
+        return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    };
+    const input = num('input');
+    const output = num('output');
+    const cacheRead = num('cacheRead');
+    const cacheWrite = num('cacheWrite');
+    if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined) {
+        return ZERO_USAGE;
+    }
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        ...(num('cacheWrite1h') !== undefined ? { cacheWrite1h: num('cacheWrite1h') } : {}),
+        ...(num('reasoning') !== undefined ? { reasoning: num('reasoning') } : {}),
+        totalTokens: num('totalTokens') ?? input + output + cacheRead + cacheWrite,
+    };
+}
+/** stopReason 闭集校验：undefined（历史/残缺）→ 'stop' 最小偏见；非成员 → 'error' 保守 */
+function normalizeStopReason(reason) {
+    if (reason === undefined)
+        return 'stop';
+    return STOP_REASONS.has(reason) ? reason : 'error';
+}
+/** durable 原始参数串 → 已解析对象：解析失败兜底空对象（损坏不炸重播种） */
+function parseArguments(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // 落空兜底——真源串在 durable 事件里永不丢
+    }
+    return {};
+}
+/** 投影 toolCall 块 → contracts ToolCallBlock（id/name 字段名对齐） */
+function toToolCallBlock(call) {
+    return {
+        type: 'toolCall',
+        id: call.toolCallId,
+        name: call.toolName,
+        arguments: parseArguments(call.arguments),
+    };
+}
+/**
+ * 重播种：投影消息序列 → 标准 Message 数组（timeline 活数组种子）。
+ * 纯函数（timeOf 词典注入保确定性）；toolResult 侧 arguments 丢弃
+ * （请求面不需要——assistant 内联块已带）。
+ * @param projection 投影（SessionLog.projection() 或 deriveMessages 产物——两路同源）
+ * @param timeOf 锚事件 seq → 毫秒时间戳解析器（确定性时间源——不用墙钟）
+ */
+export function reseedTimeline(projection, timeOf) {
+    const messages = [];
+    for (const projected of projection) {
+        switch (projected.type) {
+            case 'user': {
+                const user = {
+                    role: 'user',
+                    // content 双形直通（string | 块数组——session ContentBlock 与 contracts
+                    // 块结构对齐，derive 头注同裁；只读→可写经结构断言收口）
+                    content: projected.content,
+                    timestamp: timeOf(projected.seq),
+                    // source 闭集由写者闭环保证（durable 原值即 UserMessage.source 落账回读）
+                    ...(projected.source !== undefined ? { source: projected.source } : {}),
+                };
+                messages.push(user);
+                break;
+            }
+            case 'assistant': {
+                const assistant = {
+                    role: 'assistant',
+                    // toolCalls 装回尾部（投影序 = 尾部序——交错序在 durable 分立事件下无账）
+                    content: [...projected.content, ...projected.toolCalls.map(toToolCallBlock)],
+                    usage: normalizeUsage(projected.usage),
+                    stopReason: normalizeStopReason(projected.stopReason),
+                    timestamp: timeOf(projected.seq),
+                    ...(projected.errorMessage !== undefined ? { errorMessage: projected.errorMessage } : {}),
+                };
+                messages.push(assistant);
+                break;
+            }
+            case 'toolResult': {
+                messages.push({
+                    role: 'toolResult',
+                    toolCallId: projected.toolCallId,
+                    toolName: projected.toolName,
+                    // string 输出包裹文本块（请求面 content 恒块数组）；块数组直通
+                    content: typeof projected.output === 'string'
+                        ? [{ type: 'text', text: projected.output }]
+                        : projected.output,
+                    isError: projected.isError,
+                    timestamp: timeOf(projected.seq),
+                });
+                break;
+            }
+        }
+    }
+    return messages;
+}

package/dist/conversation/sessions.js

@@ -0,0 +1,215 @@
+import { forkPrefix, isSeededPrefix, recoverClosers } from '../session/index.js';
+/** 会话编排钩子词汇（03 主表在册——本面消费的 waterfall 事件名单源） */
+export const SESSION_HOOK_NAMES = ['session_before_fork'];
+/**
+ * 多会话管理器（进程级单例——Persistence 同生命周期；02 §2.3 多会话单焦点：
+ * 并存多枚驱动、焦点唯 caller 视角，本件不持焦点态）。
+ */
+export class SessionManager {
+    persistence;
+    dispatch;
+    createDriver;
+    /** 单会话收口观察位（构造面注入——缺省无观察） */
+    onRetired;
+    /** 已开会话登记（sessionId → 驱动 + 血缘形态——幂等 open 的判据面） */
+    records = new Map();
+    constructor(options) {
+        this.persistence = options.persistence;
+        this.dispatch = options.dispatch;
+        this.createDriver = options.createDriver;
+        this.onRetired = options.onRetired;
+        // 钩子词汇接线（一词两册幂等跳过——03 §2.4 装配序律：装载批预注册主表
+        // 镜像在前，session_before_fork 已注册即共享登记；未注册自举保独立装配）；
+        // 重复建管理器检测改经装配哨兵（永不 emit 的占位词——二次装配撞哨兵红）
+        this.dispatch.registerEventNames([
+            'conversation/session-manager-mounted',
+            ...SESSION_HOOK_NAMES.filter((name) => !this.dispatch.isRegistered(name)),
+        ]);
+    }
+    /** 会话列表（「按 cwd 取最新」选取面透传） */
+    list(options = {}) {
+        return this.persistence.listSessions(options);
+    }
+    /** 新开会话（origin 缺省普通对话；model/systemPrompt/shapeTools/askApproval/extraTools 为本会话装配覆盖——纯内存载体，批 19c-1 子代理通道同 model 律） */
+    create(init = {}) {
+        const origin = init.origin ?? 'conversation';
+        const log = this.persistence.createSession({
+            origin,
+            ...(init.workspaceRoot !== undefined ? { workspaceRoot: init.workspaceRoot } : {}),
+            ...(init.title !== undefined ? { title: init.title } : {}),
+        });
+        return this.adopt(log, origin, false, init);
+    }
+    /**
+     * 打开（resume）既有会话：幂等——已 open 直接回活体驱动（单焦点，不造第二
+     * 附着）。未 open 走 loadSession → closer 合成（崩溃收形——合成物复用最后
+     * 真实 time 可审计辨）→ 驱动构造（resumed 形）。
+     * @throws 会话不存在（fail-loud——读未落库 id 属调用方 bug）
+     */
+    open(sessionId) {
+        const existing = this.records.get(sessionId);
+        if (existing !== undefined) {
+            return { sessionId, driver: existing.driver, origin: existing.origin };
+        }
+        const loaded = this.persistence.loadSession(sessionId);
+        // closer 合成（05 §4——孤儿 tool/未闭合 turn 等补形；全日志扫描不设窗口）
+        for (const draft of recoverClosers(loaded.log.events())) {
+            loaded.log.appendSynthetic(draft);
+        }
+        return this.adopt(loaded.log, loaded.row.origin, true);
+    }
+    /**
+     * 分叉（05 §5.0 边界快照）：前缀种子 + 复制。边界缺省 lastClosedBoundary
+     * （不在进行中 turn 中间切）；内存种子组装——end-seed 只随种子走（time 复用
+     * 前缀尾事件时间，§4 合成确定性同律），源日志零污染。session_before_fork
+     * 钩子可否决（联合回执）。源会话已 open 取活体事件流（最新鲜）。
+     * @throws 源会话不存在 / upToSeq 越界（fail-loud 调用方 bug）
+     */
+    async fork(sourceSessionId, options = {}) {
+        // —— 事实源选择：活体优先（双事实源纪律——未 open 才 loadSession）——
+        const live = this.records.get(sourceSessionId);
+        let sourceLog;
+        let workspaceRoot;
+        if (live !== undefined) {
+            sourceLog = live.driver.session;
+            // 活体驱动不携带行信息——workspaceRoot 经公开列表面反查（不为内部
+            // 取值开新 persistence 读口）
+            workspaceRoot = this.persistence.listSessions().find((row) => row.id === sourceSessionId)?.workspaceRoot;
+        }
+        else {
+            const loaded = this.persistence.loadSession(sourceSessionId);
+            sourceLog = loaded.log;
+            workspaceRoot = loaded.row.workspaceRoot;
+        }
+        const sourceEvents = sourceLog.events();
+        // —— 边界解析 + 合法性（缺省最后闭合边界；显式值须落在日志内）——
+        const boundary = options.upToSeq ?? sourceLog.lastClosedBoundary();
+        if (options.upToSeq !== undefined && (options.upToSeq < -1 || options.upToSeq >= sourceEvents.length)) {
+            throw new Error(`fork 边界越界：upToSeq=${options.upToSeq} 日志长 ${sourceEvents.length}（调用方 bug）`);
+        }
+        // —— 钩子（waterfall 可否决——只认 veto 位；空链直通）——
+        const hookInput = { sourceSessionId, upToSeq: boundary };
+        const hookOutput = await this.dispatch.waterfall('session_before_fork', hookInput);
+        if (hookOutput.veto !== undefined) {
+            return { status: 'vetoed', reason: hookOutput.veto.reason };
+        }
+        // —— 种子组装：前缀拷贝 + end-seed 字面尾事件（data 空对象——§1.1）——
+        const seed = forkPrefix(sourceEvents, boundary);
+        seed.push({
+            type: 'session/end-seed',
+            seq: seed.length,
+            time: seed.length > 0 ? seed[seed.length - 1].time : 0,
+            data: {},
+        });
+        // 合法种子断言（防御位——forkPrefix + 字面尾事件在构造上恒真，触达即实现回归）
+        if (!isSeededPrefix(seed, seed.length, true)) {
+            throw new Error('fork 种子不合法（isSeededPrefix 断言失败——实现回归，不应触达）');
+        }
+        // —— 物理腿：同步落库（返回 id 必可读——不返回幻影 id）+ 驱动构造 ——
+        const forkedLog = this.persistence.createSeededSession(seed, {
+            origin: 'fork',
+            parentId: sourceSessionId,
+            ...(workspaceRoot !== undefined ? { workspaceRoot } : {}),
+            ...(options.title !== undefined ? { title: options.title } : {}),
+        });
+        const opened = this.adopt(forkedLog, 'fork', false);
+        return {
+            status: 'forked',
+            ...opened,
+            lineage: { parentId: sourceSessionId, seedLength: seed.length, origin: 'fork' },
+            firstAppendSeq: seed.length,
+        };
+    }
+    /**
+     * 会话内全文检索（05 §9 首发口径）：flush 屏障先行（write-behind 在飞事件
+     * 不进 FTS 索引——检索前先落定）→ Store.searchSessionFts。
+     * @returns 命中事件 seq 升序列表（limit 缺省 50）
+     */
+    async search(sessionId, pattern, limit) {
+        await this.persistence.flush();
+        return this.persistence.searchSessionFts(sessionId, pattern, limit);
+    }
+    /** 已开判据（幂等 open 的外部可读面） */
+    isOpen(sessionId) {
+        return this.records.has(sessionId);
+    }
+    /**
+     * 目标会话在场判定（进程内在管 ∪ durable 行——e-4 操控轴幽灵守卫判据位，
+     * 03 §2.2 第十一面：三动词共同前置「目标 id 无对应行拒
+     * SESSION_TARGET_NOT_FOUND」）。零副作用：不 attach、不合成 closer、
+     * 不构造驱动。
+     */
+    exists(sessionId) {
+        return this.records.has(sessionId) || this.persistence.hasSession(sessionId);
+    }
+    /** 已开驱动读取（缺席 undefined——焦点编排归调用方） */
+    driverOf(sessionId) {
+        return this.records.get(sessionId)?.driver;
+    }
+    /** 任一已开驱动在飞（宿主 busy 判据读面——scheduler GateFacts agentBusy 源，批 20c） */
+    anyRunning() {
+        for (const { driver } of this.records.values()) {
+            if (driver.running)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * 已开会话清单投影（e-2 观测腿——宿主 SessionView deps.liveSessions 消费位；
+     * 结构兼容 obs ObsLiveSessionsFace）。只含进程内在管（durable 未开不在场——
+     * 会话维清单语义 = 进程内活体会话，历史会话归持久层 list）。
+     */
+    listActive() {
+        return [...this.records.entries()].map(([sessionId, { origin }]) => ({ sessionId, origin }));
+    }
+    /** 全量拆解（进程收尾序）：逐驱动 dismantle（打断在飞 run）+ 清登记 */
+    dispose() {
+        for (const { driver } of this.records.values()) {
+            driver.dismantle();
+        }
+        this.records.clear();
+    }
+    /**
+     * 单会话收口（run 生命周期收口——05 §7 retire 律 / 04 §12 第 5 律）：驱动
+     * dismantle（终态停摆——打断在飞 run，dispose 同律）+ 摘活体登记。幂等——
+     * 不在册回 false 零副作用（dispose 后再 retire / 重复收口均无害）。
+     *
+     * 与 dispose 分立：彼系进程收尾序全量拆解，此系单条无头编排会话的终态
+     * 收口（tick 用户行 / subagent 子会话 / issue headless 会话三消费位——
+     * 19c-1 头注「活体登记回收挂账」的销账动词）。durable 面不受影响：日志
+     * 仍可查、open 可复续（幂等 open 对已摘行重造活体）。会话复用形（goal
+     * 绑定会话——广播唤醒依赖活体登记）不走此收口。
+     */
+    retire(sessionId) {
+        const record = this.records.get(sessionId);
+        if (record === undefined)
+            return false;
+        record.driver.dismantle();
+        this.records.delete(sessionId);
+        // 收口观察 seam：主流程（dismantle + 摘登记）已成——观察者异常吞隔离
+        // 不回卷收口序（观察位当前 = 冻结缓存摘除〔Map.delete 不抛〕，防御位
+        // 留给未来观察者）
+        try {
+            this.onRetired?.(sessionId);
+        }
+        catch {
+            /* 观察者异常不回卷收口序（发射序末位） */
+        }
+        return true;
+    }
+    /** 登记 + 驱动构造 + 入册（create/open/fork 共尾；装配覆盖位仅 create 腿携带——resume 不回放） */
+    adopt(log, origin, resumed, overrides = {}) {
+        const driver = this.createDriver({
+            session: log,
+            origin,
+            resumed,
+            ...(overrides.model !== undefined ? { model: overrides.model } : {}),
+            ...(overrides.systemPrompt !== undefined ? { systemPrompt: overrides.systemPrompt } : {}),
+            ...(overrides.shapeTools !== undefined ? { shapeTools: overrides.shapeTools } : {}),
+            ...(overrides.askApproval !== undefined ? { askApproval: overrides.askApproval } : {}),
+            ...(overrides.extraTools !== undefined ? { extraTools: overrides.extraTools } : {}),
+        });
+        this.records.set(log.sessionId, { driver, origin });
+        return { sessionId: log.sessionId, driver, origin };
+    }
+}