berry-agent 0.1.0-alpha.1

package/dist/tools/pipeline.js

@@ -0,0 +1,176 @@
+/**
+ * L2 tools — 三段 waterfall 管道（04 §7：schema → 守门 → 执行，工具执行唯一合法路径）。
+ *
+ * 结构（前三步是硬编舞、钩子是同词 waterfall 监听者——safety 守门行与插件
+ * 钩子同链，监听者可追加；守门段由 safety 件占首位）：
+ *
+ *   0. schema 段（前置步，非钩子段）——typebox Value.Check 不过即拒
+ *      TOOL_INVALID_ARGS（可纠正错误回执），不进守门/执行段；
+ *   1. tools_pre_execute 守门段——决策词汇 allow / block{reason}（短路）/
+ *      mutate{args}（就地改参）；监听器抛错 = fail-closed 视同 block
+ *      （TOOL_GATE_FAILED——先落 gate/decision 再拒，审计链不断头）；
+ *   2. tools_execute 执行段——around-dispatch（载荷 = 执行闭包，监听者包
+ *      装后经 next 传播）；链尾缺省实现 = timeoutMs 预算竞速 + 调 execute
+ *      （超时 TOOL_TIMEOUT——取消传播靠 signal，不强杀 promise）；
+ *   3. tools_post_execute 后处理段——可就地改写 result（裁剪/isError 改写）；
+ *      链尾固定步 = 输出护栏（64KiB 保尾截断 + 全文外溢临时文件——04 §7
+ *      执行段细则：护栏是管道属性，全部工具受益；只钳文本 content）。
+ *
+ * 失败统一抛 BaseError（message 首缀 `[CODE]`——02 §5.3 #4：错误信息 =
+ * code + 人读 message，durable 结果里码可见可序列化）；loop 工具批的
+ * executeOne try/catch 把异常包装成 isError 结果（错误是数据面）。
+ *
+ * gate/decision durable 事件经注入 sink 落日志（装配根接 session.append；
+ * tools 不依赖 session——DAG 单向，04 §7 段 2）。
+ */
+import { Value } from 'typebox/value';
+import { writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { BaseError } from '../contracts/index.js';
+import { redactToolResultExit } from '../contracts/index.js';
+import { TOOL_EXECUTE_EVENT, TOOL_POST_EXECUTE_EVENT, TOOL_PRE_EXECUTE_EVENT } from '../contracts/index.js';
+/** 组装 `[CODE] message` 形态的错误文本（码随 message 进入工具结果——02 §5.3 #4） */
+function codedMessage(code, message) {
+    return `[${code}] ${message}`;
+}
+/** 缺省输出护栏预算（64KiB——04 §7 执行段细则：输出护栏是管道属性） */
+export const OUTPUT_GUARD_BYTES = 64 * 1024;
+/** spill 文件序号（模块级自增——辅助段；唯一性主载体是随机前缀） */
+let spillSeq = 0;
+/**
+ * 取字节缓冲尾部至多 maxBytes 字节（UTF-8 安全：起点落在多字节字符中间则
+ * 前移过续字节——不产 U+FFFD 乱码尾巴）。
+ */
+function tailBytes(buf, maxBytes) {
+    if (maxBytes <= 0)
+        return '';
+    let start = Math.max(0, buf.length - maxBytes);
+    while (start > 0 && start < buf.length && (buf[start] & 0xc0) === 0x80)
+        start++;
+    return buf.subarray(start).toString('utf8');
+}
+/**
+ * 输出护栏（固定链尾步）：文本 content 合计超帽保尾截断 + 全文外溢写系统
+ * 临时目录（spill 路径进截断注记——模型可循路径自取全文）。
+ * - 只钳文本 content；图片等其余 content 原样保留（自有界）；
+ * - spill 写失败降级为仅截断（不抛——护栏自身故障不该炸掉正常结果）；
+ * - 后处理监听器若已改写 result，护栏对改写后结果同样执法（监听器先于固定步）。
+ */
+async function applyOutputGuard(result, toolCallId, guardBytes) {
+    const textParts = result.content.filter((part) => part.type === 'text');
+    const full = textParts.map((part) => part.text).join('\n');
+    const totalBytes = Buffer.byteLength(full, 'utf8');
+    if (totalBytes <= guardBytes)
+        return;
+    // spill 全文（尽力而为）：文件名只留安全字符，防 callId 形态未知的路径注入；
+    // 铸名 = 随机前缀 + 独占写 wx + 0600（04 §7 2026-09-14 spill 安全硬化三件）——
+    // 随机前缀使种植者不可预测文件名，wx 即便撞名也不跟随既有 symlink（种植位
+    // 结构性不可用），0600 独占读（工具输出可能含敏感面，世界可读即泄漏面）
+    spillSeq += 1;
+    const safeCallId = toolCallId.replace(/[^A-Za-z0-9_-]/g, '_');
+    const nonce = randomBytes(6).toString('hex');
+    const spillPath = `${tmpdir()}/tool-output-${nonce}-${safeCallId}-${spillSeq}.txt`;
+    let spilled = true;
+    try {
+        await writeFile(spillPath, full, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    }
+    catch {
+        spilled = false; // tmp 满/EEXIST 撞名等故障：截断照做，路径不承诺
+    }
+    const tail = tailBytes(Buffer.from(full, 'utf8'), guardBytes);
+    const note = `\n\n[输出 ${totalBytes} 字节超 ${guardBytes} 字节上限，已保尾截断${spilled ? `；全文外溢至 ${spillPath}（可用 read/grep 从外溢文件取段）` : ''}]`;
+    result.content = [...result.content.filter((part) => part.type !== 'text'), { type: 'text', text: `${tail}${note}` }];
+}
+/**
+ * 创建工具执行管道（装配根一次性创建；注册表把每个 ToolDefinition 的执行
+ * 接到本管道——toAgentTool 包装）。守门段 mutate 语义依赖「可变入参就地
+ * 改写」：gateInput 对象对整条链固定，守门者改 gateInput.args 即改执行段
+ * 所见参数（mutated 旗由改参者维护，落账 decision 判据）。
+ */
+export function createToolPipeline(dispatch, opts = {}) {
+    const defaultTimeoutMs = opts.defaultTimeoutMs ?? 60_000;
+    const guardBytes = opts.outputGuardBytes ?? OUTPUT_GUARD_BYTES;
+    const recordGate = opts.onGateDecision ?? (() => { });
+    const sensitiveValues = opts.sensitiveValues ?? (() => []);
+    return async function runToolPipeline(def, toolCallId, args, signal, onUpdate, sessionId) {
+        /* ---- 前置步：参数 schema 校验（typebox Value；不合法不进守门） ---- */
+        if (!Value.Check(def.parameters, args)) {
+            const problems = [...Value.Errors(def.parameters, args)]
+                .slice(0, 5)
+                .map((e) => `${e.instancePath || '(root)'} ${e.message}`)
+                .join('；');
+            throw new BaseError('TOOL_INVALID_ARGS', codedMessage('TOOL_INVALID_ARGS', `工具 ${def.name} 参数校验失败：${problems}`));
+        }
+        /* ---- 第一段：守门（fail-closed；block 短路不进执行段） ---- */
+        // sessionId 透传进守门载荷（04 §7 批 15d 补注——checkpoint 按会话判 per-run）
+        const gateInput = {
+            tool: def,
+            args,
+            toolCallId,
+            mutated: false,
+            ...(signal !== undefined ? { signal } : {}),
+            ...(sessionId !== undefined ? { sessionId } : {}),
+        };
+        let gated;
+        try {
+            gated = await dispatch.waterfall(TOOL_PRE_EXECUTE_EVENT, gateInput);
+        }
+        catch (err) {
+            // fail-closed：守门监听器自身异常 = 视为 block，绝不放行；先落决策再抛
+            const message = err instanceof Error ? err.message : String(err);
+            recordGate({ toolCallId, decision: 'block', reason: codedMessage('TOOL_GATE_FAILED', message) });
+            throw new BaseError('TOOL_GATE_FAILED', codedMessage('TOOL_GATE_FAILED', `守门检查失败（fail-closed 拒绝）：${message}`));
+        }
+        if (gated.outcome?.action === 'block') {
+            // block 短路：结构化拒绝（含 reason）经 throw 交 loop 编码 isError 结果返回模型
+            recordGate({ toolCallId, decision: 'block', reason: gated.outcome.reason });
+            throw new BaseError('TOOL_BLOCKED', codedMessage('TOOL_BLOCKED', gated.outcome.reason));
+        }
+        // 放行/改参：mutated 旗由改参的守门者维护，汇总进 durable 决策；allowReason
+        // = 放行来源标注（策略表 allow 免问命中置 policy-allow:<条目序>——04 §9 命中审计）
+        recordGate({ toolCallId, decision: gated.mutated ? 'mutate' : 'allow', reason: gated.allowReason ?? 'ok' });
+        /* ---- 第二段：执行（around-dispatch；链尾缺省实现 = 超时预算 + execute） ---- */
+        // 载荷 = 执行闭包：监听者包装闭包经 next 传播（超时预算/重试/指标类包装位）
+        const timedExecute = async () => {
+            const timeoutMs = def.timeoutMs ?? defaultTimeoutMs;
+            const toolCtx = {
+                toolCallId,
+                ...(signal !== undefined ? { signal } : {}),
+                ...(onUpdate !== undefined ? { onUpdate } : {}),
+                ...(sessionId !== undefined ? { sessionId } : {}),
+            };
+            const execOwned = () => def.execute(gated.args, toolCtx);
+            // 预算竞速：超时先到即抛 TOOL_TIMEOUT（原 execute 继续跑但结果弃置——
+            // loop 侧 accepting 护栏忽略其迟到 onUpdate；取消传播靠 signal，不强杀）
+            let timer;
+            const timeoutPromise = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new BaseError('TOOL_TIMEOUT', codedMessage('TOOL_TIMEOUT', `工具 ${def.name} 执行超时（>${timeoutMs}ms）`))), timeoutMs);
+            });
+            try {
+                return await Promise.race([execOwned(), timeoutPromise]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        const wrapped = await dispatch.waterfall(TOOL_EXECUTE_EVENT, timedExecute);
+        const result = await wrapped();
+        /* ---- 第三段：后处理（可就地改写 result）+ 出口消毒 + 固定链尾输出护栏 ---- */
+        const postInput = { tool: def, args: gated.args, toolCallId, result };
+        const posted = await dispatch.waterfall(TOOL_POST_EXECUTE_EVENT, postInput);
+        // 出口治理③ 凭据消毒（04 §7 定形①：护栏之前一步——消毒先于截断，截断边界
+        // 不劈秘密对；spill 外溢文件同持消毒产物）。provider 故障只降级值基腿
+        // （模式腿恒在场——消毒是出口护栏非执法门，库坏不该炸掉正常结果）。
+        let secretValues = [];
+        try {
+            secretValues = sensitiveValues();
+        }
+        catch {
+            /* provider 读取故障 → 空值表 = 纯模式执法（降级诚实） */
+        }
+        redactToolResultExit(posted.result, secretValues);
+        await applyOutputGuard(posted.result, toolCallId, guardBytes);
+        return posted.result;
+    };
+}

package/dist/tools/protected-read.js

@@ -0,0 +1,54 @@
+/**
+ * L2 tools — 敏感件读侧 carve-out 判定件（04 §7 读侧条 + 2026-09-08 P0① 落码定形③④）。
+ *
+ * 独立小文件、不 import fs.ts（防 fs → protected-read → fs 环——模块内文件
+ * 级依赖只许单向；search.ts 对 fs.ts 的 canonicalize 引用同理合法）。两判据：
+ * - 路径判（open 前）：目标 canonical 路径命中敏感件集 = FS_READ_PROTECTED
+ *   硬拒——fail-closed、无审批出路、不登记观察（拒读不构成「看过」）；deny
+ *   检查先于存在性检查（缺席同拒同文案——不暴露敏感件存在性差异）；
+ * - inode 判（open 后）：对已打开句柄 fstat 的 (dev, ino) 与敏感件集 stat
+ *   比对，命中 = 同硬拒——一判收口两攻击面（硬链别名：canonical 路径不同而
+ *   inode 相同；TOCTOU 换靶：canonicalize 与 open 之间路径组件被换）。
+ *
+ * 敏感集 = 装配层注入 provider（() => canonical 绝对路径数组；缺省空集 =
+ * 判定 no-op）。tools 不 import safety（DAG 边表），与 fence 的
+ * writableRoots 同注入形——数据在装配层，判定语义在工具件。
+ */
+import { stat } from 'node:fs/promises';
+import { BaseError } from '../contracts/index.js';
+/** 保护面硬拒（两判据共用回执——同码同文案，不区分命中路径判还是 inode 判） */
+function rejectProtected(abs) {
+    throw new BaseError('FS_READ_PROTECTED', `[FS_READ_PROTECTED] 读目标属敏感件保护面：${abs}（04 §7 读侧 carve-out——密钥与免问面恒不可读，fail-closed 无审批出路）`);
+}
+/**
+ * open 前路径判：canonical 目标命中敏感集 = 硬拒（不登记观察）。比对语义 =
+ * canonical 路径相等（敏感件是具体文件不是目录域——无前缀匹配面）。
+ */
+export function rejectProtectedReadPath(canonical, protectedReadFiles) {
+    for (const p of protectedReadFiles()) {
+        if (canonical === p)
+            rejectProtected(canonical);
+    }
+}
+/**
+ * open 后 inode 判：已打开句柄的 fstat 产物与敏感件集逐件 stat 比对，
+ * (dev, ino) 双等 = 同硬拒。敏感件自身缺席（stat ENOENT）= 跳过（无可比对
+ * 象；保护面不虚构）。空敏感集零 stat（缺省装配 no-op 无开销）。
+ *
+ * @param abs 用户可见的请求路径（回执文案用——真实判据是 inode 不是路径）
+ * @param opened 打开句柄的 fstat 产物（`open` 已把路径解析钉死到具体 inode
+ *   ——比对的正是「真正打开的那个」，而非再次路径解析的快照）
+ */
+export async function assertInodeNotProtected(abs, opened, protectedReadFiles) {
+    const paths = protectedReadFiles();
+    if (paths.length === 0)
+        return; // 敏感集缺席（诊断形/未注入）——判定 no-op
+    for (const p of paths) {
+        // 敏感件 stat：读失败（含缺席/权限）一律跳过——保护面只按在场可比对象执法
+        const st = await stat(p).catch(() => undefined);
+        if (st === undefined)
+            continue;
+        if (st.dev === opened.dev && st.ino === opened.ino)
+            rejectProtected(abs);
+    }
+}

package/dist/tools/registry.js

@@ -0,0 +1,250 @@
+/**
+ * L2 tools — 工具注册表两层（04 §7：全局层 + 驱动层；03 §2.2 ctx.tools.register 落形）。
+ *
+ * 两层（2026-09-04 立项改造裁决：承 berry 三层删应用域分片——插件工具进
+ * 全局层，无第三层）：
+ * - 全局层：进程单例 Map（宿主固定件工具 + 插件注册的工具——全部会话可见）；
+ * - 驱动层：sessionId → Map（会话态工具面——存在理由是会话态状态〔fs 观察
+ *   态 per-driver / bash 升权闭包〕，不是域隔离）。
+ * - 工具面按会话解析：listFor(sessionId) = 全局层 ∪ 驱动层[sessionId]。
+ *
+ * 查重碰撞域（「任何单一组合面内不得双名」）：全局层注册查「全局 ∪ 全部
+ * 驱动层」（全局工具进一切面——与任何驱动层条目在任何面都共现）；驱动层[s]
+ * 注册查「全局 ∪ 驱动层[s]」；跨驱动层同名合法（永不同面——fs 四名每会话
+ * 一套即靠此）。03 §2.7「无论哪层哪来源双向对称」按此碰撞域执法。
+ *
+ * 注册面防线四道（任何来源同一执法——官方件同受管，防线在树上不在审查上）：
+ * ①描述注入模式扫描（03 §2.8）→ TOOL_DESCRIPTION_REJECTED；
+ * ②parameters 根 object 断言 → TOOL_SCHEMA_INVALID；
+ * ③timeoutMs <= 0 拒（正数过小钳至下限——微小预算 = 变相自杀钟，钳而非拒）；
+ * ④双帽（03 §3.4）：两层合计 10^3 总量帽 TOOL_REGISTRY_CAPACITY +
+ * register/unregister 令牌桶（容量 240、回填 600/分钟，全局键）
+ * TOOL_CHANGE_RATE_LIMITED——可用性防线非安全边界。
+ *
+ * tools_change 事件（03 §2.4 主表 emit 面）：每次注册/注销发射
+ * {kind: 'register'|'unregister', name, driver?}——loop 工具快照活数组原位
+ * 替换的接线源（04 §4 装配接线义务，消费在装配根）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { TOOLS_CHANGE_EVENT } from '../contracts/index.js';
+/** 注册表两层合计件数帽（03 §3.4 总量帽——良性行为距阈值两个数量级，超限 = 失控或泄漏） */
+const REGISTRY_TOTAL_LIMIT = 1_000;
+/**
+ * register/unregister 变更频率桶参数（03 §3.4）：容量 240 吃下 boot + 两连
+ * 重载的合法重注册序列；回填 600/分钟 = 10 op/s 持续供给，热迭代不触顶、
+ * 武器化持续注册耗尽容量即拦。全局键——registry 无 scope 概念。
+ */
+const REGISTRY_RATE = { capacity: 240, perMinute: 600 };
+/** timeoutMs 下限（正数过小钳至此——500ms 类微小预算 = 变相自杀钟，钳而非拒） */
+export const TOOL_TIMEOUT_FLOOR_MS = 100;
+/**
+ * v1 注入模式最小词表（03 §2.8 描述扫描）。描述是进模型上下文的文本：
+ * `curl … | sh` 形态 = 让模型照描述执行任意下载，是描述面执行漏洞。词表随
+ * 真实生态扩充——规范只钉「注册面扫描」这个位置，不在此堆正则。
+ */
+const DESCRIPTION_INJECTION_PATTERNS = [/\b(curl|wget)\b[^\n|]*\|[^\n]*\b(ba|z|da)?sh\b/i];
+/**
+ * 扫描工具描述是否命中注入模式（注册面统一防线——任何来源的工具同一执法）。
+ * @returns 命中的模式串（错误归因用）；干净描述返回 undefined
+ */
+export function scanToolDescription(description) {
+    for (const pattern of DESCRIPTION_INJECTION_PATTERNS) {
+        if (pattern.test(description))
+            return pattern.source;
+    }
+    return undefined;
+}
+/**
+ * 变更频率令牌桶（03 §3.4 双帽之二）：容量 240、每分钟回填 600——按流逝
+ * 时间连续回填（600/60000 per ms），take 不足即拒。桶状态进程内单份（全
+ * 局键），随注册表实例生命周期。
+ */
+class RateLimiter {
+    capacity;
+    perMinute;
+    /** 当前令牌数（初始满桶——boot 期的合法批量注册不受阻） */
+    tokens;
+    /** 上次回填时间戳（ms——按流逝时间折算回填量） */
+    lastRefill;
+    constructor(capacity, perMinute) {
+        this.capacity = capacity;
+        this.perMinute = perMinute;
+        this.tokens = capacity;
+        this.lastRefill = Date.now();
+    }
+    /** 取一枚令牌：充足即取、不足即拒（false——调用方抛 TOOL_CHANGE_RATE_LIMITED） */
+    take() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        if (elapsed > 0) {
+            this.tokens = Math.min(this.capacity, this.tokens + (elapsed * this.perMinute) / 60_000);
+            this.lastRefill = now;
+        }
+        if (this.tokens < 1)
+            return false;
+        this.tokens -= 1;
+        return true;
+    }
+}
+/**
+ * 把 ToolDefinition 适配成 loop 面的 AgentTool（execute = 三段管道——管道是
+ * 唯一执行路径的结构保证位）。驱动层条目绑 sessionId（管道内 ToolContext
+ * 路由 per-session 状态的语境键）。
+ */
+export function toAgentTool(def, executor, sessionId) {
+    return {
+        name: def.name,
+        description: def.description,
+        parameters: def.parameters,
+        // 调度语义位透传（一位两用——批消费序按 effect 分段：read 段并发、write 屏障）
+        effect: def.effect,
+        execute: (toolCallId, args, signal, onUpdate) => executor(def, toolCallId, args, signal, onUpdate, sessionId),
+    };
+}
+/**
+ * 组装工具注册表（装配根调用一次；tools_change 经注入的 dispatch 发射）。
+ * 注册面归一：effect 缺省 'exec'（**未知缺省最危律**——2026-09-11 审批分档
+ * 批缺省反转，04 §9 定形块②：未声明效果面的工具按最高危档归一走全审批链，
+ * 「缺省放行」的静默豁口不立；03 §2.3 契约缺省同笔更文）、repeatable 缺省
+ * true；timeoutMs 正数过小钳至下限（存归一副本——对调用方原对象零改动）。
+ */
+export function createToolRegistry(dispatch, opts = {}) {
+    const executor = opts.pipeline;
+    const totalLimit = opts.registryTotalLimit ?? REGISTRY_TOTAL_LIMIT;
+    const rate = opts.changeRate ?? REGISTRY_RATE;
+    /** 全局层：name → 定义（Map 保注册序） */
+    const globalLayer = new Map();
+    /** 驱动层：sessionId → (name → 定义)（Map 保注册序） */
+    const driverLayers = new Map();
+    /** 变更频率桶（register 侧 fail-loud 先于变更；unregister 侧在注销器内） */
+    const changeRate = new RateLimiter(rate.capacity, rate.perMinute);
+    /** 撞名查重（碰撞域见文件头注）——命中返回既有来源描述（错误信息归因用） */
+    const findConflict = (name, driver) => {
+        const global = globalLayer.get(name);
+        if (global !== undefined)
+            return `全局层 ${global.name}`;
+        if (driver !== undefined) {
+            const inDriver = driverLayers.get(driver)?.get(name);
+            if (inDriver !== undefined)
+                return `驱动层[${driver}] ${inDriver.name}`;
+            return undefined;
+        }
+        // 全局层注册与全部驱动层查撞（全局进一切面）
+        for (const [sessionId, layer] of driverLayers) {
+            const hit = layer.get(name);
+            if (hit !== undefined)
+                return `驱动层[${sessionId}] ${hit.name}`;
+        }
+        return undefined;
+    };
+    /** 两层合计件数（总量帽读数） */
+    const totalSize = () => {
+        let n = globalLayer.size;
+        for (const layer of driverLayers.values())
+            n += layer.size;
+        return n;
+    };
+    /** tools_change 发射（emit 模式——观察面；发射失败不阻注册〔emit 已隔离〕） */
+    const announce = (kind, name, driver) => {
+        void dispatch.emit(TOOLS_CHANGE_EVENT, { kind, name, ...(driver !== undefined ? { driver } : {}) });
+    };
+    /** 注销器（幂等——disposer 重复调用零次侧效应；频率桶同扣〔unregister 也算变更〕） */
+    const makeDisposer = (name, driver, normalized) => {
+        let disposed = false;
+        return () => {
+            if (disposed)
+                return;
+            disposed = true;
+            const layer = driver === undefined ? globalLayer : driverLayers.get(driver);
+            // 身份护栏：仅当仍是本定义时移除（防误摘后来胜出者——03 §2.7 与 disposer 释放对齐三律②）
+            if (layer === undefined || layer.get(name) !== normalized)
+                return;
+            if (!changeRate.take()) {
+                throw new BaseError('TOOL_CHANGE_RATE_LIMITED', `工具变更频率桶空（容量 ${rate.capacity}、回填 ${rate.perMinute}/分钟）——注销被拦：${name}`);
+            }
+            layer.delete(name);
+            if (driver !== undefined && layer.size === 0)
+                driverLayers.delete(driver);
+            announce('unregister', name, driver);
+        };
+    };
+    const registry = {
+        executor,
+        definitions() {
+            // 全局层只读副本（快照与注册表解耦——后续注册不进旧快照）
+            return [...globalLayer.values()];
+        },
+        register(def, registerOpts) {
+            // ① 描述注入扫描（03 §2.8——任何来源同一防线，官方件同受管）
+            const injectionHit = scanToolDescription(def.description);
+            if (injectionHit !== undefined) {
+                throw new BaseError('TOOL_DESCRIPTION_REJECTED', `工具描述命中注入模式（/${injectionHit}/）：${def.name}——描述是进模型上下文的文本，拒绝注册`);
+            }
+            // ② parameters 根 object 断言：顶层 union（无 type 字段）会被宽容网关剥
+            //    成空声明面（模型以空参数调用、宿主 root 级拒绝）——注册即炸前移到装配期
+            const schemaRoot = def.parameters;
+            if (schemaRoot !== undefined && schemaRoot.type !== 'object') {
+                throw new BaseError('TOOL_SCHEMA_INVALID', `工具 ${def.name} parameters 根节点非 object（${schemaRoot.type ?? '（无 type 字段——顶层 union 形）'}）——` +
+                    `声明契约只认根 object；互斥多形工具请用扁平 object（判别字段可选 + 字段级 enum）`);
+            }
+            // ③ timeoutMs 正数校验（<= 0 拒——拒绝式而非钳 0：钳制会静默改变行为）
+            if (def.timeoutMs !== undefined && def.timeoutMs <= 0) {
+                throw new BaseError('TOOL_INVALID_ARGS', `工具 ${def.name} timeoutMs <= 0（${def.timeoutMs}）——不设预算请省略该字段（走管道缺省 60s）`);
+            }
+            const driver = registerOpts?.driver;
+            // ④ 双帽：变更频率桶先扣（fail-loud 先于变更）→ 撞名 → 总量帽
+            if (!changeRate.take()) {
+                throw new BaseError('TOOL_CHANGE_RATE_LIMITED', `工具变更频率桶空（容量 ${rate.capacity}、回填 ${rate.perMinute}/分钟）——注册被拦：${def.name}`);
+            }
+            const conflict = findConflict(def.name, driver);
+            if (conflict !== undefined) {
+                throw new BaseError('TOOL_NAME_CONFLICT', `工具名 ${def.name} 已被占用（${conflict}）——碰撞域内双向对称拒绝（03 §2.7）`);
+            }
+            if (totalSize() >= totalLimit) {
+                throw new BaseError('TOOL_REGISTRY_CAPACITY', `注册表两层合计达总量帽 ${totalLimit}（当前 ${totalSize()}）——超限拒新注册：${def.name}`);
+            }
+            // 归一副本：effect 缺省 exec（未知缺省最危律——04 §9 定形块②反转：
+            // 未声明 = 最高危档走全审批链，修前形 read 直达的静默豁口封死）、
+            // repeatable 缺省 true（03 §2.3 契约缺省）；timeoutMs 钳下限
+            const normalized = {
+                ...def,
+                effect: def.effect ?? 'exec',
+                repeatable: def.repeatable ?? true,
+                ...(def.timeoutMs !== undefined ? { timeoutMs: Math.max(def.timeoutMs, TOOL_TIMEOUT_FLOOR_MS) } : {}),
+            };
+            if (driver === undefined) {
+                globalLayer.set(normalized.name, normalized);
+            }
+            else {
+                const existing = driverLayers.get(driver);
+                if (existing !== undefined) {
+                    existing.set(normalized.name, normalized);
+                }
+                else {
+                    const layer = new Map();
+                    layer.set(normalized.name, normalized);
+                    driverLayers.set(driver, layer);
+                }
+            }
+            announce('register', normalized.name, driver);
+            return makeDisposer(normalized.name, driver, normalized);
+        },
+        listFor(sessionId) {
+            const driverLayer = driverLayers.get(sessionId);
+            if (driverLayer === undefined)
+                return [...globalLayer.values()];
+            // 驱动层条目在后（同面重名不可能——碰撞域已拒，序 = 全局先驱动后）
+            return [...globalLayer.values(), ...driverLayer.values()];
+        },
+        agentToolsFor(sessionId) {
+            if (executor === undefined) {
+                throw new BaseError('CONTEXT_SERVICE_MISSING', `工具注册表未接三段管道（pipeline 缺席）——agentToolsFor 不可用（装配缺陷）`);
+            }
+            return registry.listFor(sessionId).map((def) => toAgentTool(def, executor, sessionId));
+        },
+        get size() {
+            return totalSize();
+        },
+    };
+    return registry;
+}