@zooique/memora 2.0.3 → 3.0.1

package/dist/agent/toolResultCache.js

@@ -0,0 +1,243 @@
+/**
+ * 工具结果防重缓存（闭环内有效）
+ *
+ * 设计意图：LLM 在问答闭环中反复调用 read_file/list_dir/web_search 等信息获取型工具，
+ * 同一参数重复调用既浪费 token 又无增量价值（文件未变 / 同 query 网络结果近似）。
+ * 本缓存以「闭环内去重」为粒度——闭环结束即清空，跨闭环不复用。
+ *
+ * 拦截语义与 loop 已有的 web_search MAX_WEB_SEARCH_CALLS / ask_user askLimit 同级：
+ * 检测到重复 → blocked=true（不算工具失败）→ 返回 [ALREADY_READ] 拒绝文案。
+ *
+ * **去重主体是结构化的**（`DedupSubject`），不是预先拼好的字符串 key：
+ * 写入（set）/ 命中（check）/ 失效（invalidateFile）三处必须对**同一份主体**判定。
+ * 任何一处自行拼 key 都会让三者静默失配——历史缺陷即此形态：key 里加上读取区间后，
+ * `invalidateFile` 的 `read_file:${path}` 前缀永远匹配不上 → 文件被改后旧缓存不失效 → 误拦重读。
+ *
+ * 防重维度：闭环内 + 同 toolName + 同主体语义（路径 + 读取区间 / query）。
+ * 不防重：write_file / run_code / run_skill_script 等副作用型工具。
+ *
+ * 补充导出 `WRITE_PATH_EXTRACTORS`（非防重）：写工具**不防重**，但同一 step 内打在同一路径上的
+ * 两次写**必须串行**（并行会因读旧快照而互相覆盖）。二者是同一批「副作用型工具」的两面。
+ */
+import path from 'node:path';
+// PATH_WRITE_TOOL_NAMES：写工具名集真源（builtinTools 各定义行 `diskWrite:'path'` 声明派生）——
+// 本模块只借其键集组装提取器表，不自存工具名清单。
+import { PATH_WRITE_TOOL_NAMES } from '../agent/builtinTools.js';
+// 正整数解析单一真源（read_file 去重主体 offset/limit 与 builtinToolHandlers 分段预算同规）
+import { positiveInt } from '../utils/math.js';
+/**
+ * 路径去重规范化（纯字符串，不触磁盘）：统一分隔符 → 消除 `./`、`a//b`、`a/../b` → 去尾部 `/`。
+ *
+ * 只做「同一写法的等价归并」，**不解析绝对路径**（loop 不认文件系统，项目根属宿主）。
+ * 因此 `a.md` 与 `/abs/a.md` 仍是不同主体 —— 这是**保守语义**：
+ * 无法确定二者是同一文件时就不该判为重复，判错方向的代价是死锁（见 loop 的拦截前提）。
+ */
+export function normalizePathKey(raw) {
+    const unified = raw.trim().replace(/\\/g, '/');
+    const normalized = path.posix.normalize(unified);
+    return normalized.length > 1 ? normalized.replace(/\/+$/, '') : normalized;
+}
+/** 安全解析 args JSON（非法 / 非对象 → undefined） */
+function parseArgs(argsJson) {
+    try {
+        const parsed = JSON.parse(argsJson);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 取非空字符串字段（非字符串 / 空串 → undefined） */
+function nonEmptyString(v) {
+    return typeof v === 'string' && v.trim() !== '' ? v : undefined;
+}
+/** 内置去重主体生成器集合（SSOT：loop 注册防重拦截时引用） */
+export const DEDUP_SUBJECT_EXTRACTORS = {
+    /** read_file 主体 = 规范化路径 + 读取区间（区间语义与 handler 一致） */
+    read_file: (argsJson) => {
+        const a = parseArgs(argsJson);
+        const rawPath = a ? nonEmptyString(a.path) : undefined;
+        if (!rawPath)
+            return undefined;
+        return {
+            path: normalizePathKey(rawPath),
+            offset: positiveInt(a?.offset) ?? 1,
+            limit: positiveInt(a?.limit),
+        };
+    },
+    /** list_dir 主体 = 规范化路径 */
+    list_dir: (argsJson) => {
+        const a = parseArgs(argsJson);
+        const rawPath = a ? nonEmptyString(a.path) : undefined;
+        return rawPath ? { path: normalizePathKey(rawPath) } : undefined;
+    },
+    /** web_search 主体 = query（短时间内同 query 结果近似） */
+    web_search: (argsJson) => {
+        const a = parseArgs(argsJson);
+        const query = a ? nonEmptyString(a.query) : undefined;
+        return query ? { query } : undefined;
+    },
+    /** web_fetch 主体 = 规范化 URL（搜索→抓取闭环第二段；同 URL 抓取两次正文无增量） */
+    web_fetch: (argsJson) => {
+        const a = parseArgs(argsJson);
+        const url = a ? nonEmptyString(a.url) : undefined;
+        // URL 只做 trim 归一并滤空 —— 不做路径 normalize（避免 `..`/尾部斜杠误并不同 target）
+        return url ? { query: url.trim() } : undefined;
+    },
+    /** trace_summary 主体 = sessionId（主定位，query 槽）+ roundId（可选子定位，item 槽）—— 同会话不同轮仍是合法增量读取 */
+    trace_summary: (argsJson) => {
+        const a = parseArgs(argsJson);
+        const sessionId = a ? nonEmptyString(a.sessionId) : undefined;
+        if (!sessionId)
+            return undefined;
+        const roundId = a ? nonEmptyString(a.roundId) : undefined;
+        return { query: sessionId.trim(), item: roundId?.trim() };
+    },
+    /** search_memories 主体 = query（与 web_search 同构：只按检索词判重；追更多候选应换 query 或改用 trace_summary 精取） */
+    search_memories: (argsJson) => {
+        const a = parseArgs(argsJson);
+        const query = a ? nonEmptyString(a.query) : undefined;
+        return query ? { query } : undefined;
+    },
+};
+/** 取「写路径」原始值（写工具的定位参数固定叫 `path`，与 read_file / list_dir 同名字段） */
+function rawPathOf(argsJson) {
+    const a = parseArgs(argsJson);
+    return a ? nonEmptyString(a.path) : undefined;
+}
+/**
+ * 写路径提取器：**仅**覆盖「按 `args.path` 定位、会改盘」的工具。
+ *
+ * 用途单一：loop 判定「同一 step 内两次写是否打在同一文件上」，从而只对**同路径**串行。
+ * 为何必须串行——`write_file` 是「读盘 → 改 → 写盘」，同 step 内并行发起时两次都基于同一份
+ * 旧快照，后落地者覆盖先落地者 ⇒ **静默丢内容**（真机实证：`insert` + `append` 同 step 并行，
+ * 插入的行被 append 覆盖）。
+ *
+ * 为何**单独**一份、不并入 `DEDUP_SUBJECT_EXTRACTORS`：那份是**防重**判据（命中即拦截），
+ * 而写工具正是被防重**刻意排除**的对象（见文件头「不防重：write_file …」）——并入会让
+ * 「同一文件分次追加」被误判为重复调用而拦掉，属语义反转。
+ *
+ * 键集 = **派生自** `builtinTools` 各定义行的 `diskWrite: 'path'` 声明（构造级单源，禁再
+ * 独立枚举工具名）；值 = 共用的 `args.path` 提取语义（'path' 模式的定义即「目标 = args.path」）。
+ * 路径规范化与去重同源（`normalizePathKey`）：路径等价语义只有这一套，不另造。
+ */
+export const WRITE_PATH_EXTRACTORS = Object.fromEntries(PATH_WRITE_TOOL_NAMES.map((name) => [name, extractArgsPathTarget]));
+/** `'path'` 模式写工具的目标提取：`args.path` → 规范化路径（提取失败返回 undefined，调用方降级屏障） */
+function extractArgsPathTarget(argsJson) {
+    const raw = rawPathOf(argsJson);
+    return raw ? normalizePathKey(raw) : undefined;
+}
+/** 主体 → 缓存 key（本模块唯一的 key 构造点；用不可打印分隔符，避免与路径 / query / item 内容冲突） */
+function keyOf(toolName, subject) {
+    return [
+        toolName,
+        subject.path ?? '',
+        subject.query ?? '',
+        subject.item ?? '',
+        subject.offset ?? '',
+        subject.limit ?? '',
+    ].join('\u0001');
+}
+/**
+ * 主体 → 人类可读描述（拦截文案出口）。
+ *
+ * 文案面向 LLM，**不暴露内部 key 格式**：它需要知道的是「哪个文件的哪一段已经在你手上」。
+ */
+export function formatDedupSubject(toolName, subject) {
+    // 查询/会话类主体（web_search / web_fetch / trace_summary）：主定位 + 可选子定位（session·round）
+    if (subject.query !== undefined) {
+        return subject.item !== undefined ? `${subject.query} · ${subject.item}` : subject.query;
+    }
+    // 文件类主体（read_file 渲染区间；list_dir 仅路径）
+    if (subject.path !== undefined) {
+        if (toolName !== 'read_file')
+            return subject.path;
+        const range = subject.limit !== undefined
+            ? `第 ${subject.offset} 行起的 ${subject.limit} 行`
+            : `第 ${subject.offset} 行起`;
+        return `${subject.path} · ${range}`;
+    }
+    return '';
+}
+/**
+ * 同主体聚合键（工具名 + 规范化 path/query/item），粒度 = 同参。
+ *
+ * **两个消费语境共用本函数**（SSOT）：① `read_failed` 的连续失败计数；
+ * ② `read_dedup` 的撞墙升级计数。二者要的都是「工具 + 请求主体」这一个标识，
+ * 故共用同一口径——各自另拼 key 会让两套计数对「同一主体」的理解悄悄分叉。
+ *
+ * 原子分隔符 `\u0002`：不可打印，避免与 path/query/item 的合法内容（文件路径、URL、会话 id）冲突。
+ *
+ * @param toolName 工具名
+ * @param subject  请求主体（由 `DEDUP_SUBJECT_EXTRACTORS` 产出）
+ */
+export function failureSubjectKey(toolName, subject) {
+    // item 纳入：trace_summary 同 sessionId 不同 roundId 计为不同主体，不把「任一 round 失败」误并到整个会话
+    return `${toolName}\u0002${subject.path ?? ''}\u0002${subject.query ?? ''}\u0002${subject.item ?? ''}`;
+}
+/**
+ * 闭环内工具结果防重缓存
+ *
+ * 只负责「同 tool + 同主体」的重复检测。mtime 放行不需要——
+ * 文件被 write_file 修改后，loop 结果处理循环会主动 invalidate 同 path 的 read_file 缓存。
+ * 比 statSync 更准确（同一 cwd/path 解析链路）、不依赖 projectPath 传递。
+ */
+export class ToolResultCache {
+    /** Map<key, CacheEntry> */
+    cache = new Map();
+    /**
+     * 检查指定工具调用是否重复
+     *
+     * @param toolName 工具名（如 'read_file'）
+     * @param subject  请求主体（由 `DEDUP_SUBJECT_EXTRACTORS` 产出）
+     * @returns 已重复则返回首次缓存的条目；否则 undefined
+     */
+    check(toolName, subject) {
+        return this.cache.get(keyOf(toolName, subject));
+    }
+    /**
+     * 失效指定 path 关联的 read_file 缓存（副作用型工具成功后调用，放行后续合法重读）
+     *
+     * 按 `subject.path` 匹配 —— **该文件所有读取区间一起失效**（文件内容变了，任何区间的旧结果都作废）。
+     * `list_dir` 不失效：文件修改不改目录结构。
+     *
+     * @param rawPath 被修改 / 删除的文件路径
+     */
+    invalidateFile(rawPath) {
+        const target = normalizePathKey(rawPath);
+        for (const [k, entry] of this.cache) {
+            if (entry.toolName === 'read_file' && entry.subject.path === target) {
+                this.cache.delete(k);
+            }
+        }
+    }
+    /**
+     * 记录一次已执行的工具调用
+     *
+     * @param toolName  工具名
+     * @param subject   请求主体
+     * @param iteration 当前迭代序号（用于日志 / 提示文案）
+     * @param meta      可选元信息（mtime / toolCallId / 内容指纹）
+     */
+    set(toolName, subject, iteration, meta) {
+        this.cache.set(keyOf(toolName, subject), {
+            toolName,
+            subject,
+            cachedAtIteration: iteration,
+            ...(meta?.fileMtime !== undefined ? { fileMtime: meta.fileMtime } : {}),
+            ...(meta?.toolCallId !== undefined ? { toolCallId: meta.toolCallId } : {}),
+            ...(meta?.fingerprint !== undefined ? { fingerprint: meta.fingerprint } : {}),
+        });
+    }
+    /** 闭环结束清空（跨闭环不复用） */
+    clear() {
+        this.cache.clear();
+    }
+    /** 当前缓存条目数（调试 / 监控用） */
+    get size() {
+        return this.cache.size;
+    }
+}
+//# sourceMappingURL=toolResultCache.js.map

package/dist/agent/toolResultCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResultCache.js","sourceRoot":"","sources":["../../src/agent/toolResultCache.ts"],"names":[],"mappings":"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"}

package/dist/agent/toolResultOffload.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 工具结果卸载原语（大文本统一通道 · 入口关）
+ *
+ * 「带问题取件 → 一次一份 → 提炼 → 原文落盘 → 只积攒情报 + 留引用」
+ * （大文本统一通道 §6.2）的**门前换鞋**动作：单条 tool 消息超阈时把原文写入磁盘，
+ * 上下文只留「路径 + 预览 + 续读提示」。
+ *
+ * **单一原语 + 单一收口**：本函数是唯一的落盘实现；唯一调用点是 `AgentLoop.appendToolMessage`
+ * （loop 唯一 tool 写点，一处覆盖五个调用点：工具结果 / `[ASK_ANSWER]` / `[ASK_ABORTED]` /
+ * `[ASK_SUSPENDED]` / `[TOOL_ABORTED]`）。
+ * 上下文中 tool 消息只可能由该写点产生，入口关覆盖后无需事后压缩扫描
+ *（「读者先亡、写者后死」；实证见 §6.2 结论二）。
+ *
+ * **同步实现（有意为之，勿改异步）**：`AgentLoop.answerQuestion()` 是**同步公开 API**（宿主调用后
+ * 立即 `continueAfterPause()`），异步落盘会沿 `appendToolMessage → answerQuestion` 传染成内核公开
+ * API 破坏性变更。落盘是罕见路径（仅超阈时）、单次 ≤ 数百 KB，同步写阻塞可忽略；内核已有同步 fs
+ * 生产先例（`security/pathGuard.ts: realpathSync`、`logging/logger.ts: mkdirSync`）。同步还使
+ * **写失败可当场降级**（返回原文入上下文 + warn），不引入「悬空引用」这一新失败模式。
+ *
+ * **落盘内容 = 传入内容原样**（即 wrapped 后的那条消息全文）：不做 unwrap —— 剥离包裹需要一份与
+ * `wrapToolResult` 模板对称的解析实现（模板一改即失配），而「路径指向的内容与原本将入上下文的内容
+ * 完全一致」是更简单也更自洽的语义。
+ */
+/** 卸载结果：进入上下文的内容 + 是否真的落盘 + 产物路径 */
+export interface ToolResultOffloadOutcome {
+    /** 进入上下文的内容：落盘成功 = 「路径 + 预览 + 续读提示」；未超阈 / 写失败 = 原文 */
+    content: string;
+    /** 是否真的落盘（false = 未超阈，或写失败已降级） */
+    offloaded: boolean;
+    /** 产物绝对路径（仅 offloaded=true 时存在） */
+    filePath?: string;
+}
+/** 卸载参数 */
+export interface ToolResultOffloadOptions {
+    /**
+     * 落盘目录（**必传**）：由装配注入项目 `memoraDir` 下的 outputs 子目录。
+     * 内核不派生落点 —— 信任根外的路径 `read_file` 读不回，等于假引用（OFFLOAD-1 教训）。
+     */
+    offloadDir: string;
+    /**
+     * 落盘阈值（token，**含包裹判据口径**）。
+     * 默认 `LOOP_CONSTANTS.SINGLE_TOOL_RESULT_MAX_TOKENS` —— 与 `read_file` 分段上限同键同源。
+     */
+    thresholdTokens?: number;
+    /** 预览字符数（默认 1,000） */
+    previewChars?: number;
+}
+/**
+ * 单条工具结果超阈 → 落盘 + 生成替换文本；否则原样返回。
+ *
+ * 判据 `estimateTokensText(content) > 阈值`（严格大于）：`read_file` 产出（含包裹）恒 ≤ 阈值，
+ * 故**结构性不落盘**，回取产物不会再次落盘 → 无限嵌套不可能。
+ *
+ * @param content 即将进入上下文的 tool 消息内容（已 wrapped）
+ * @param opts 落盘目录（必传）与可覆盖的阈值 / 预览长度
+ * @returns 替换后内容 + 落盘事实（写失败时 `offloaded=false` 且内容原样）
+ */
+export declare function offloadLargeToolResult(content: string, opts: ToolResultOffloadOptions): ToolResultOffloadOutcome;
+//# sourceMappingURL=toolResultOffload.d.ts.map

package/dist/agent/toolResultOffload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResultOffload.d.ts","sourceRoot":"","sources":["../../src/agent/toolResultOffload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAYH,oCAAoC;AACpC,MAAM,WAAW,wBAAwB;IACvC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,WAAW;AACX,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,wBAAwB,GAC7B,wBAAwB,CA+B1B"}

package/dist/agent/toolResultOffload.js

@@ -0,0 +1,70 @@
+/**
+ * 工具结果卸载原语（大文本统一通道 · 入口关）
+ *
+ * 「带问题取件 → 一次一份 → 提炼 → 原文落盘 → 只积攒情报 + 留引用」
+ * （大文本统一通道 §6.2）的**门前换鞋**动作：单条 tool 消息超阈时把原文写入磁盘，
+ * 上下文只留「路径 + 预览 + 续读提示」。
+ *
+ * **单一原语 + 单一收口**：本函数是唯一的落盘实现；唯一调用点是 `AgentLoop.appendToolMessage`
+ * （loop 唯一 tool 写点，一处覆盖五个调用点：工具结果 / `[ASK_ANSWER]` / `[ASK_ABORTED]` /
+ * `[ASK_SUSPENDED]` / `[TOOL_ABORTED]`）。
+ * 上下文中 tool 消息只可能由该写点产生，入口关覆盖后无需事后压缩扫描
+ *（「读者先亡、写者后死」；实证见 §6.2 结论二）。
+ *
+ * **同步实现（有意为之，勿改异步）**：`AgentLoop.answerQuestion()` 是**同步公开 API**（宿主调用后
+ * 立即 `continueAfterPause()`），异步落盘会沿 `appendToolMessage → answerQuestion` 传染成内核公开
+ * API 破坏性变更。落盘是罕见路径（仅超阈时）、单次 ≤ 数百 KB，同步写阻塞可忽略；内核已有同步 fs
+ * 生产先例（`security/pathGuard.ts: realpathSync`、`logging/logger.ts: mkdirSync`）。同步还使
+ * **写失败可当场降级**（返回原文入上下文 + warn），不引入「悬空引用」这一新失败模式。
+ *
+ * **落盘内容 = 传入内容原样**（即 wrapped 后的那条消息全文）：不做 unwrap —— 剥离包裹需要一份与
+ * `wrapToolResult` 模板对称的解析实现（模板一改即失配），而「路径指向的内容与原本将入上下文的内容
+ * 完全一致」是更简单也更自洽的语义。
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { logger } from '../logging/logger.js';
+import { LOOP_CONSTANTS } from '../agent/constants.js';
+import { estimateTokensText } from '../agent/contextManager.js';
+/** 预览字符数默认值（替换文本自身远小于单条上限，故不会二次触发落盘） */
+const DEFAULT_PREVIEW_CHARS = 1_000;
+/**
+ * 单条工具结果超阈 → 落盘 + 生成替换文本；否则原样返回。
+ *
+ * 判据 `estimateTokensText(content) > 阈值`（严格大于）：`read_file` 产出（含包裹）恒 ≤ 阈值，
+ * 故**结构性不落盘**，回取产物不会再次落盘 → 无限嵌套不可能。
+ *
+ * @param content 即将进入上下文的 tool 消息内容（已 wrapped）
+ * @param opts 落盘目录（必传）与可覆盖的阈值 / 预览长度
+ * @returns 替换后内容 + 落盘事实（写失败时 `offloaded=false` 且内容原样）
+ */
+export function offloadLargeToolResult(content, opts) {
+    const threshold = opts.thresholdTokens ?? LOOP_CONSTANTS.SINGLE_TOOL_RESULT_MAX_TOKENS;
+    const tokens = estimateTokensText(content);
+    if (tokens <= threshold) {
+        return { content, offloaded: false };
+    }
+    const previewChars = opts.previewChars ?? DEFAULT_PREVIEW_CHARS;
+    const fileName = `${Date.now()}_${randomBytes(4).toString('hex')}.txt`;
+    const filePath = path.join(opts.offloadDir, fileName);
+    try {
+        mkdirSync(opts.offloadDir, { recursive: true });
+        writeFileSync(filePath, content, 'utf-8');
+    }
+    catch (err) {
+        // 写失败 → 原样入上下文（不截断、不造假引用）；空间回收交由截断线兜底
+        logger.warn({ err, filePath, tokens }, '工具结果卸载失败，已降级为原文入上下文（未产生引用）');
+        return { content, offloaded: false };
+    }
+    const preview = content.slice(0, previewChars);
+    const omitted = Math.max(0, content.length - previewChars);
+    return {
+        content: `[工具结果已卸载至磁盘] 原文 ${content.length} 字符（≈${tokens} tokens）写入：${filePath}\n` +
+            `[预览（前 ${previewChars} 字符）]\n${preview}…\n` +
+            `[省略 ${omitted} 字符。需要完整内容请用 read_file 读取上述路径，大文件可配合 offset/limit 分段读取]`,
+        offloaded: true,
+        filePath,
+    };
+}
+//# sourceMappingURL=toolResultOffload.js.map

package/dist/agent/toolResultOffload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolResultOffload.js","sourceRoot":"","sources":["../../src/agent/toolResultOffload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,wCAAwC;AACxC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AA4BpC;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAe,EACf,IAA8B;IAE9B,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,IAAI,cAAc,CAAC,6BAA6B,CAAC;IACvF,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAChE,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAEtD,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sCAAsC;QACtC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,4BAA4B,CAAC,CAAC;QACrE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC;IAE3D,OAAO;QACL,OAAO,EACL,mBAAmB,OAAO,CAAC,MAAM,QAAQ,MAAM,cAAc,QAAQ,IAAI;YACzE,SAAS,YAAY,UAAU,OAAO,KAAK;YAC3C,OAAO,OAAO,yDAAyD;QACzE,SAAS,EAAE,IAAI;QACf,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/agent/toolRunner.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 工具执行器（ToolRunner）— 从 AgentLoop 抽出的「单工具执行」独立单元
+ *
+ * 承载一个工具的完整生命周期：执行前检查（三重闸门）→ 并发/中断竞争执行 → 异常转结构化错误串。
+ * 状态独立（不触碰 loop 工作记忆 / 指标 / 自主步标志），输入工具调用元素、输出结果串并触发
+ * onToolExecuted，故可独立单测。loop 的 executeToolCalls 只做批量编排，逐工具委托本执行器。
+ *
+ * 依赖经 deps 注入（execute / preExecutionCheck / onToolExecuted / getStrategy / tracer），
+ * 其中 getStrategy 每次执行读最新策略——setStrategy 的动态更新在此依然生效。
+ */
+import type { PreExecutionResult } from '../agent/types.js';
+import type { ToolDefinition } from '../agent/toolExecutor.js';
+import type { L2RuntimeStrategy } from '../role-pack/types.js';
+import type { ITracer } from '../agent/tracer.js';
+/** 工具调用元素契约（OpenAI 协议结构）——单一真源 llm/types.ToolCall（Message.toolCalls 同源） */
+import type { ToolCall } from '../llm/types.js';
+/** 一次工具调用（LLM 输出的工具调用元素）——SSOT：形状真源在 llm/types.ToolCall（协议契约单一实现；re-export 保留本文件测试判据点） */
+export type { ToolCall };
+/** ToolRunner 依赖注入（loop 稳定的窄面；策略动态经 getStrategy 读取） */
+export interface ToolRunnerDeps {
+    /** 执行单个工具（loop 的 opts.toolExecutor） */
+    execute: (name: string, args: string) => Promise<string>;
+    /** 内置工具定义（只读闸查 readonly 标记） */
+    builtinTools?: ToolDefinition[];
+    /** 宿主执行前检查（拒绝 / 跳过 / 改写参数） */
+    preExecutionCheck?: (name: string, args: string) => PreExecutionResult;
+    /** 工具执行完成回调（outbox 幂等记录是否已执行） */
+    onToolExecuted?: (name: string, args: string, result: string, ok: boolean) => void;
+    /** 读最新 L2 策略（toolReadonly 随 setStrategy 动态生效） */
+    getStrategy: () => L2RuntimeStrategy;
+    /** 可观测性 Tracer */
+    tracer: ITracer;
+}
+/**
+ * 工具执行器：单工具执行单元（异常捕获转结构化错误串回传 LLM，不中断对话）。
+ */
+export declare class ToolRunner {
+    private readonly deps;
+    constructor(deps: ToolRunnerDeps);
+    /**
+     * 执行单个工具（并行独立执行单元，无共享状态，可安全并发）。
+     * @param tc 工具调用元素
+     * @param signal 中止信号（与工具执行 race，signal 先 abort 返回 ABORTED 错误串）
+     * @returns 执行结果串（成功文本或 [ERR:TOOL:code] 错误串）
+     */
+    runOne(tc: ToolCall, signal?: AbortSignal): Promise<string>;
+    /**
+     * 执行前检查：按顺序叠加两层闸门——只读 → 宿主 preExecutionCheck，任一命中提前返回。
+     * （内核不提供"审批"闸门：无"需审批"标签与回调，审批决策统一归宿主 preExecutionCheck。）
+     */
+    private applyPrechecks;
+    /**
+     * 工具执行与 signal abort 竞争包裹。toolExecutor 签名不接受 signal，无法真正中断；
+     * 用 Promise.race 竞争，signal 先 abort 则返回 [ERR:TOOL:ABORTED]（而非抛 AbortError，
+     * 避免破坏"工具失败回传 LLM"契约；ABORTED 不入错误码体系，不触发 Reflection）
+     */
+    private raceToolWithSignal;
+}
+//# sourceMappingURL=toolRunner.d.ts.map

package/dist/agent/toolRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRunner.d.ts","sourceRoot":"","sources":["../../src/agent/toolRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAMjD,2EAA2E;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,0FAA0F;AAC1F,YAAY,EAAE,QAAQ,EAAE,CAAC;AAQzB,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,+BAA+B;IAC/B,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,kBAAkB,CAAC;IACvE,iCAAiC;IACjC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC;IACnF,iDAAiD;IACjD,WAAW,EAAE,MAAM,iBAAiB,CAAC;IACrC,kBAAkB;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,cAAc;IAEjD;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA6DjE;;;OAGG;IACH,OAAO,CAAC,cAAc;IAuCtB;;;;OAIG;YACW,kBAAkB;CA4BjC"}

package/dist/agent/toolRunner.js

@@ -0,0 +1,147 @@
+/**
+ * 工具执行器（ToolRunner）— 从 AgentLoop 抽出的「单工具执行」独立单元
+ *
+ * 承载一个工具的完整生命周期：执行前检查（三重闸门）→ 并发/中断竞争执行 → 异常转结构化错误串。
+ * 状态独立（不触碰 loop 工作记忆 / 指标 / 自主步标志），输入工具调用元素、输出结果串并触发
+ * onToolExecuted，故可独立单测。loop 的 executeToolCalls 只做批量编排，逐工具委托本执行器。
+ *
+ * 依赖经 deps 注入（execute / preExecutionCheck / onToolExecuted / getStrategy / tracer），
+ * 其中 getStrategy 每次执行读最新策略——setStrategy 的动态更新在此依然生效。
+ */
+import { TRACE_SPANS } from '../agent/tracer.js';
+import { MemoraError } from '../utils/errors.js';
+import { toError } from '../utils/toError.js';
+import { logger } from '../logging/logger.js';
+/**
+ * 工具执行器：单工具执行单元（异常捕获转结构化错误串回传 LLM，不中断对话）。
+ */
+export class ToolRunner {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 执行单个工具（并行独立执行单元，无共享状态，可安全并发）。
+     * @param tc 工具调用元素
+     * @param signal 中止信号（与工具执行 race，signal 先 abort 返回 ABORTED 错误串）
+     * @returns 执行结果串（成功文本或 [ERR:TOOL:code] 错误串）
+     */
+    async runOne(tc, signal) {
+        // 工具执行 Span（并发时多个 span 时间重叠，tracer 可观测并发度）
+        const span = this.deps.tracer.startSpan(TRACE_SPANS.TOOL_EXEC, {
+            toolName: tc.function.name,
+        });
+        try {
+            // 记录工具调用参数到 Span（可观测性增强：宿主可通过 span 详情看到每次工具调用的完整参数）
+            span.setAttribute('args', tc.function.arguments);
+            // 执行前检查：三重闸门输出三态决策（allow / skip / deny）
+            const decision = this.applyPrechecks(tc);
+            if (decision.kind === 'denied') {
+                span.setAttribute('denied', true);
+                return decision.result;
+            }
+            if (decision.kind === 'skip') {
+                span.setAttribute('skipped', true);
+                return decision.result;
+            }
+            // raceToolWithSignal 兼容 signal 中断（每个调用独立 race，监听器无并发副作用）
+            const result = await this.raceToolWithSignal(tc.function.name, decision.args, signal);
+            // 通知上层工具执行完成（供 outbox 幂等模式记录是否已执行）
+            const ok = !result.startsWith('[ERR');
+            this.deps.onToolExecuted?.(tc.function.name, decision.args, result, ok);
+            // 记录工具执行结果摘要到 Span（可观测性增强：宿主可追踪每次工具调用的结果）
+            span.setAttribute('result', result.slice(0, 200));
+            span.setAttribute('ok', ok);
+            return result;
+        }
+        catch (err) {
+            // 捕获异常转为结构化错误串回传 LLM 自行调整策略，避免传播中断对话
+            const e = toError(err);
+            span.recordException(e);
+            if (err instanceof MemoraError) {
+                const code = err.errorCode ?? 'UNKNOWN';
+                // 失败串末尾附带 suggestions（人读的「下一步」也要进 LLM 上下文）：
+                // 若建议只在 `error.format()` 给宿主 UI、LLM 只收 title+detail——首击失败后
+                // LLM 收不到「使用 list_dir 查看目录结构」这类确切指令，只能凭证据自己悟（多绕一次）。
+                // 证据（siblingDirHint 清单）在 detail 内，本拼接补上命令式建议，双管齐下。
+                const result = `[ERR:TOOL:${code}] 错误：${err.title}${err.detail ? ` — ${err.detail}` : ''}` +
+                    (err.suggestions.length > 0 ? ` 建议：${err.suggestions.join('；')}` : '');
+                logger.warn({ tool: tc.function.name, errorCode: code, title: err.title }, '工具执行失败，错误已回传给 LLM');
+                this.deps.onToolExecuted?.(tc.function.name, tc.function.arguments, result, false);
+                return result;
+            }
+            else {
+                const result = `[ERR:TOOL:UNKNOWN] 错误：工具执行异常 — ${e.message}`;
+                logger.error({ tool: tc.function.name, err }, '工具执行异常');
+                this.deps.onToolExecuted?.(tc.function.name, tc.function.arguments, result, false);
+                return result;
+            }
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * 执行前检查：按顺序叠加两层闸门——只读 → 宿主 preExecutionCheck，任一命中提前返回。
+     * （内核不提供"审批"闸门：无"需审批"标签与回调，审批决策统一归宿主 preExecutionCheck。）
+     */
+    applyPrechecks(tc) {
+        const name = tc.function.name;
+        const args = tc.function.arguments;
+        const strategy = this.deps.getStrategy();
+        // ① 只读闸：toolReadonly='readonly' 阻止非只读工具
+        if (strategy.toolReadonly === 'readonly') {
+            const toolDef = this.deps.builtinTools?.find((t) => t.name === name);
+            if (toolDef && !toolDef.readonly) {
+                logger.warn({ tool: name }, '工具只读模式：阻止写入工具执行');
+                return {
+                    kind: 'denied',
+                    result: `[ERR:TOOL:READONLY_DENIED] 工具 "${name}" 是写入操作，在只读模式下不可用`,
+                };
+            }
+        }
+        // ② 宿主 preExecutionCheck：拒绝 / 跳过 / 放行（可改写参数）
+        const preCheck = this.deps.preExecutionCheck?.(name, args);
+        if (preCheck?.denied) {
+            const reason = preCheck.reason ?? '工具调用被拒绝';
+            logger.warn({ tool: name, reason }, '工具调用被拒绝（执行前检查）');
+            // PERMISSION_DENIED 不可重试，LLM 见后会调整策略而非重试
+            return { kind: 'denied', result: `[ERR:TOOL:PERMISSION_DENIED] ${reason}` };
+        }
+        if (preCheck?.skip) {
+            const result = preCheck.previousResult ?? '[SKIP:TOOL:IDEMPOTENT] 工具已执行（outbox 模式跳过）';
+            logger.debug({ tool: name, argsSignature: args.slice(0, 80) }, '工具已执行，跳过（仅一次语义）');
+            return { kind: 'skip', result };
+        }
+        // 放行：有改写参数则用改写后的执行（审计/参数改写）
+        return { kind: 'execute', args: preCheck?.overrideArgs ?? args };
+    }
+    /**
+     * 工具执行与 signal abort 竞争包裹。toolExecutor 签名不接受 signal，无法真正中断；
+     * 用 Promise.race 竞争，signal 先 abort 则返回 [ERR:TOOL:ABORTED]（而非抛 AbortError，
+     * 避免破坏"工具失败回传 LLM"契约；ABORTED 不入错误码体系，不触发 Reflection）
+     */
+    async raceToolWithSignal(name, args, signal) {
+        const { execute } = this.deps;
+        // 无 signal 时直接执行工具（保持原行为，测试场景常用）
+        if (!signal) {
+            return execute(name, args);
+        }
+        // signal 已 abort：直接返回中断错误，不发起工具调用
+        if (signal.aborted) {
+            return '[ERR:TOOL:ABORTED] 错误：工具执行被中断';
+        }
+        // abort 监听 Promise（signal abort 时 resolve 错误串）；onAbort 提外层便于 race 后清理
+        let onAbort = null;
+        const abortPromise = new Promise((resolve) => {
+            onAbort = () => resolve('[ERR:TOOL:ABORTED] 错误：工具执行被中断');
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+        // race 结束清理监听器，避免并发工具调用累积残留监听器（{ once: true } 不保证未触发时被移除）
+        return Promise.race([execute(name, args), abortPromise]).finally(() => {
+            if (onAbort)
+                signal.removeEventListener('abort', onAbort);
+        });
+    }
+}
+//# sourceMappingURL=toolRunner.js.map

package/dist/agent/toolRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRunner.js","sourceRoot":"","sources":["../../src/agent/toolRunner.ts"],"names":[],"mappings":"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"}