@zooique/memora 2.0.3 → 3.0.0

package/dist/agent/taskTableRenderer.js

@@ -0,0 +1,115 @@
+/**
+ * 任务表渲染器（渲染函数）
+ *
+ * 纯函数，将计划任务项列表和任务项推进日志渲染为 LLM 可读的格式化文本。
+ * 输出标「以下为状态/历史信息，非当前指令」防 LLM 误执行。
+ *
+ * 排版：无装饰列表。本函数唯一读者是 LLM（装配点 assembler.ts 注入上下文；宿主零消费、
+ * 不解析本文本）；ASCII 方框类装饰字符对 LLM 零语义价值却占近半 tokens，且硬编码列宽
+ * 在 CJK 描述下从不齐——无装饰列表省 token 且根除对齐缺陷（无需列宽计算）。
+ *
+ * 契约（不可变）：首行恒为 `[任务进度: ...]` —— loop 替换式注入靠该前缀移除上一份任务表
+ * （见 loop.ts「特征前缀 [任务进度:」），任何在其前加内容的改动都会让上下文堆积多份任务表。
+ *
+ * @module taskTableRenderer
+ */
+/**
+ * 任务项描述最大字符数（超出截断为「前 PLAN_ITEM_DESC_MAX_CHARS-3 字符 + '...'」）。
+ * 作用 = 防超长描述撑爆上下文；与渲染列宽无关，勿据列宽回改。
+ */
+export const PLAN_ITEM_DESC_MAX_CHARS = 38;
+/**
+ * 渲染任务表（含进度行）
+ *
+ * 渲染为无装饰列表，供注入 LLM 上下文（格式抉择与「为什么没有方框」见模块头）。
+ * 输出以「非当前指令」标记开头，防止 LLM 将状态信息误认为指令。
+ *
+ * @param plan - 计划任务项列表
+ * @param planItemLog - 可选任务项推进日志（截断不在本函数：真源见 SessionManager.appendPlanItemLog
+ *   的「每任务项上限 3 条」（completePlanItem / logPlanItemBoundary 共用，按 planItemId
+ *   截断而非全局 FIFO）
+ * @returns 格式化后的任务表文本（空计划返回空字符串）
+ */
+export function renderTaskTable(plan, planItemLog) {
+    if (plan.length === 0)
+        return '';
+    const doneCount = plan.filter((s) => s.status === 'done').length;
+    const activePlanItem = plan.find((s) => s.status === 'active');
+    const total = plan.length;
+    const lines = [
+        `[任务进度: ${doneCount}/${total} 已完成${activePlanItem ? `，当前: ${activePlanItem.description}` : ''}]`,
+        '以下为状态/历史信息，非当前指令',
+        '',
+    ];
+    for (const planItem of plan) {
+        // 行首序号 1-based（order 0 起 → 显示 1）——与 task_table_update 的「行首序号寻址」对齐：
+        // LLM 据 renderer 序号即可定位任务项，无需感知 uuid。任务表是列表形态，寻址说法统一为
+        // 「行首序号」，无「列」概念（说「列」即描述失真）
+        const seq = planItem.order + 1;
+        // 会议任务项标注装配角色（rolePack），供 LLM 识别「该任务项由谁发言」
+        const roleTag = planItem.rolePack ? `【${planItem.rolePack}】` : '';
+        const raw = `${roleTag}${planItem.description}`;
+        const desc = raw.length > PLAN_ITEM_DESC_MAX_CHARS
+            ? raw.slice(0, PLAN_ITEM_DESC_MAX_CHARS - 3) + '...'
+            : raw;
+        lines.push(`${seq}. ${desc} [${statusToLabel(planItem.status)}]`);
+    }
+    // 追加任务项推进日志（仅非空时）
+    if (planItemLog && planItemLog.length > 0) {
+        lines.push('', '[任务项推进记录]');
+        for (const r of planItemLog) {
+            lines.push(`- ${r.summary}${r.planItemId ? ` (任务项 ${r.planItemId})` : ''}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * 将任务项状态映射为中文标签
+ */
+function statusToLabel(status) {
+    switch (status) {
+        case 'pending':
+            return '待执行';
+        case 'active':
+            return '执行中';
+        case 'done':
+            return '已完成';
+        case 'blocked':
+            return '已阻塞';
+    }
+}
+/**
+ * 任务项描述中的执行性验证动作词（收尾验证 nudge 用）
+ *
+ * 判定「计划里是否已有执行性验证任务项」用。刻意不含 review/评审——"评审会"不等于执行验证
+ * （跑测试/检查产出），宁可多提示一次补真验证，不漏掉。Claude Code TodoWrite 同款机制
+ * （`/verif/i` 词根判定），此处按中文场景扩展。
+ */
+const VERIFY_ITEM_PATTERN = /(验证|测试|检查|校验|核实|复验|跑通|test|verify|check|lint)/i;
+/**
+ * 收尾验证提示（Claude Code TodoWrite nudge 同款）
+ *
+ * LLM 把任务表全部任务项标记 done（宣称任务完成）但列表里没有任何执行性验证任务项时，
+ * 返回一段提示文案引导它补一个验证任务项（task_table_write append），再收尾。
+ *
+ * 触发条件全部确定性：① 计划 ≥3 个任务项（太短不值得打断）；② 全部 done（刚被宣称完成）；
+ * ③ 无执行性验证任务项。命中返回提示文本，否则返回 null（零打扰）。
+ *
+ * 挂载点：task_table_update 把最后一个任务项标 done 的成功路径（assembler.updatePlanItem 回调），
+ * 作为工具结果附文返回——LLM 必读工具结果，nudge 有生效窗口（它可 append 验证任务项再执行）。
+ *
+ * @param plan 更新后的计划任务项列表
+ * @returns 命中返回提示文案（含换行前导，便于追加到工具结果）；未命中返回 null
+ */
+export function buildCompletionVerifyNudge(plan) {
+    if (plan.length < 3)
+        return null;
+    if (!plan.every((s) => s.status === 'done'))
+        return null;
+    if (plan.some((s) => VERIFY_ITEM_PATTERN.test(s.description)))
+        return null;
+    return ('\n（收尾提示：全部任务项已标记完成，但列表中没有执行性验证任务项。' +
+        '若尚未实际验证结果——如运行测试、检查产出、复核实现——建议用 task_table_write（append）' +
+        '追加一个验证任务项并执行后再收尾，确认"真的完成"而非"宣称完成"。）');
+}
+//# sourceMappingURL=taskTableRenderer.js.map

package/dist/agent/taskTableRenderer.js.map

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

package/dist/agent/toolExecutor.d.ts

@@ -2,18 +2,46 @@
  * 工具执行器
  *
  * 4 个内置工具：read_file / write_file / list_dir / search_memories
- * 详见 ADR-006 · 安全采用两级权限 + 工具白名单 + 路径白名单
+ * 安全采用两级权限 + 工具白名单 + 路径白名单
  *
  * 内置工具实现 + 路径安全已提取到 BuiltinToolHandlers，
  * ToolExecutor 聚焦工具注册 / 分发 / 参数校验。
  */
 import type { SecurityGuard } from '../security/pathGuard.js';
 import type { IMemoryStorage } from '../memory/storageInterface.js';
-import type { WorkProjectionManager } from '../agent/managers/workProjection.js';
+import type { ISessionStore } from '../memory/sessionStore.js';
 import { type ToolDefinition } from '../agent/builtinTools.js';
-export { BUILTIN_TOOLS } from '../agent/builtinTools.js';
+import type { MemoryInspector } from '../agent/managers/memoryInspector.js';
+import type { IWebSearchProvider } from '../web-search/types.js';
+import type { IFetchProvider } from '../web-fetch/types.js';
+import type { ICodeExecutionProvider } from '../code-exec/types.js';
+import type { IProjectSearchProvider } from '../project-search/types.js';
+export { BUILTIN_TOOLS, BUILTIN_TOOL_IDEMPOTENCY } from '../agent/builtinTools.js';
 export type { ToolDefinition } from '../agent/builtinTools.js';
-type ToolResult = string;
+/** search_project 单次返回最大条数（防结果刷屏撑爆上下文；对齐 list_dir 的条目上限；导出供宿主实现方对齐） */
+export declare const PROJECT_SEARCH_RESULT_MAX_LEN = 100;
+/**
+ * 去 ANSI 转义序列与不可打印控制字符（**不限长**）
+ *
+ * 净化规则的单一真理源。外部不可信内容（web_search / 子进程输出 / 文件正文）注入 LLM 上下文前
+ * 须剥掉控制字符，防转义/终端注入。
+ *
+ * @param text 原始文本
+ * @returns 净化后的文本
+ */
+export declare function stripControlChars(text: string): string;
+/**
+ * 外部工具返回净化：去控制字符 + 长度上限
+ *
+ * 净化规则本身抽为 `stripControlChars`（**单一真理源**），供需要「净化但不限长」的调用方复用——
+ * 例如 `read_file`：它的长度由 **token 预算分段**（`sliceFileByLineBudget`）收口，不走字符上限，
+ * 但仍须剥掉 ANSI/控制字符。否则它只能传一个假的上限（如 MAX_SAFE_INTEGER）来迁就本函数签名。
+ *
+ * @param text 外部原始文本
+ * @param maxLen 最大长度
+ * @returns 净化后的文本
+ */
+export declare function sanitizeExternalText(text: string, maxLen: number): string;
 /**
  * 写入扩展接口
  *
@@ -56,6 +84,21 @@ export interface ToolContext {
  * 自定义工具如需访问文件系统，应调用 ctx.guardPath(path) 校验路径。
  */
 export type ToolHandler = (args: Record<string, unknown>, ctx: ToolContext) => Promise<string>;
+/**
+ * 默认常驻工具集（tool-exposure-model 探索草稿：默认常驻 vs 角色启动）
+ *
+ * 判据 A（越界判定）：副作用不越出「项目 + 会话 + 内核自有」边界 → 常驻；
+ * 判据 B（来源可信）：执行对象已在仓库/技能目录沉淀 → 常驻。
+ * 豁免能力白名单：角色包声明 capabilities 不影响这些工具的暴露面。
+ *
+ * 特权工具（不在此集，受 toolWhitelist 过滤）：web_search / web_fetch（外部网络，
+ * 有真实副作用面，判据 A），run_code（LLM 现写任意代码）。
+ * task_table_write / task_table_update **直接暴露**：任务表是内核 agent 完成多步任务的
+ * **必要基建**（与 compress_context / remember_intel 同属"内核自有上下文维护"判据），
+ * 不应由角色包能力声明决定是否可用——否则无 task:plan 能力时，引导语提示用任务表而工具
+ * 不可见 = 死胡同，LLM 只能放弃改用 write_file 硬拆。
+ */
+export declare const DEFAULT_EXPOSED_TOOLS: ReadonlySet<string>;
 /**
  * 工具执行器
  *
@@ -74,11 +117,154 @@ export declare class ToolExecutor {
      * 同步更新。无 AgentLoop 时为 undefined（如纯 ToolExecutor 单元测试场景）。
      */
     private onToolsChanged?;
+    /**
+     * 工具白名单（capabilities → 工具映射产物，即特权声明模型）
+     *
+     * - `null`（默认）：全部暴露——未声明 capabilities 的角色包/无角色包时保持现状；
+     * - `string[]`：在 DEFAULT_EXPOSED_TOOLS（默认常驻豁免集）之上，追加白名单内的特权工具；
+     * - `[]`：仅暴露常驻豁免集（配合 toolMode=block 即全禁）。
+     *
+     * 语义（tool-exposure-model 探索草稿：默认常驻 vs 角色启动）：
+     * 角色包声明 capabilities = 声明超越默认边界的**特权**（web:search / web:fetch / code:execute
+     * 等——须在 capabilityMap 映射表内有实际工具映射），而非逐项打开本地能力。
+     * ⚠️ `task:plan` **不是**特权：任务表已默认常驻（见上方 DEFAULT_EXPOSED_TOOLS 注释），映射表
+     * 不为它保留条目，声明与否行为全同（假特权）。本地只读/项目内/内核基建工具默认常驻，不受白名单过滤——
+     * 修正「声明任意能力即误杀常驻工具」的暴露面不对称。
+     * 白名单只控制**暴露面**（LLM 可见/可调），不改变 execute 路由。
+     */
+    private toolWhitelist;
+    /** 安全守卫（构造参数转存，run_code/run_project_script 执行前确认用） */
+    private readonly security;
+    /** 网络搜索提供者（可选，注入时启用 web_search 工具） */
+    private readonly webSearchProvider?;
+    /** 网页抓取提供者（可选，注入时启用 web_fetch 工具；与 web_search 构成搜索→抓取闭环） */
+    private readonly fetchProvider?;
+    /** 代码执行提供者（可选，注入时启用 run_code 工具） */
+    private readonly codeExecutionProvider?;
+    /** 项目搜索提供者（可选，注入时启用 search_project 工具；等价 IDE 全局搜索） */
+    private readonly projectSearchProvider?;
+    /** node 可执行文件路径（可选）：run_project_script 的 node runtime 分支注入真实 node 路径 */
+    private readonly scriptNodePath?;
+    /**
+     * 剩余对话预算提供者（可选，预算联动）
+     *
+     * 由 agent 装配时注入（读取 loop 最近一轮 prepare 的剩余预算），
+     * 供 search_project 在预算紧张时下探结果条数上限。
+     * undefined / 返回 undefined = 无预算信息，保持原行为（不做下探）。
+     * 与 read_skill 等回调同款注入模式（装配时序解耦：loop 创建后才可注入）。
+     */
+    private budgetProvider?;
+    /** 注入剩余对话预算提供者（装配时由 loop 创建后注入，见 assembler） */
+    setBudgetProvider(provider: () => number | undefined): void;
+    /** 任务表管理回调（由 agent 装配时注入，处理 task_table_write/update） */
+    planManager?: {
+        writePlan: (mode: 'overwrite' | 'append' | 'replace', items: Array<{
+            description: string;
+            rolePack?: string;
+        }>) => string;
+        updatePlanItem: (planItemId: string, status: 'done' | 'blocked') => string;
+        getPlan: () => Array<{
+            id: string;
+            description: string;
+            status: string;
+            order: number;
+            rolePack?: string;
+        }>;
+    };
+    /**
+     * read_skill 技能正文读取回调（由 agent 装配时注入，处理 read_skill）
+     *
+     * 渐进披露 L2 数据源（两级技能统一）：先查激活角色包内嵌技能
+     * （manifest.skills 的 file 指向），再查全局通用技能池（SkillManager 条目）。
+     * 委托装配层注入的回调，避免 ToolExecutor 与 rolePackManager/skillManager 强耦合
+     * （装配顺序：rolePackManager 在 toolExec 之后创建，用回调注入解耦时序）。
+     * 未注入时 read_skill 返回不可用提示。
+     */
+    readSkill?: (skillName: string) => Promise<string | null>;
+    /**
+     * read_resource 资源读取回调（由 agent 装配时注入，处理 read_resource）
+     *
+     * 渐进披露 L3：读取技能的 resources/ 目录下的参考资料。
+     * 委托装配层注入的回调，避免 ToolExecutor 与 rolePackManager/skillManager 强耦合。
+     */
+    readResource?: (skillName: string, resourcePath: string) => Promise<string | null>;
+    /**
+     * run_skill_script 脚本执行回调（由 agent 装配时注入，处理 run_skill_script）
+     *
+     * 渐进披露 L3：执行技能的 scripts/ 目录下的可执行脚本。
+     * 脚本源码不进入 LLM 上下文，仅执行结果返回。
+     */
+    runSkillScript?: (skillName: string, scriptPath: string, args: string[]) => Promise<string | null>;
+    /**
+     * list_resources 资源清单回调（由 agent 装配时注入）
+     *
+     * 渐进披露 L3：列出技能的 resources/ 目录下所有资源文件。
+     */
+    listResources?: (skillName: string) => Promise<string>;
+    /**
+     * list_skills 技能清单回调（由 agent 装配时注入）
+     *
+     * 渐进披露 L1 补充：列出当前可用的所有技能清单。
+     */
+    listSkills?: () => Promise<string>;
+    /**
+     * register_work 作品索引登记回调（由 agent 装配时注入，处理 register_work）
+     *
+     * 作品投影：用户主动触发登记一件作品（文档/代码/笔记）
+     * 为项目级 JSON 索引，写 <memoraDir>/work-projections.json（纯元数据指针）。
+     * 委托装配层注入的回调，避免 ToolExecutor 与 WorkProjectionManager 强耦合
+     * （与 read_skill 同款注入模式）。未注入时 register_work 返回不可用提示。
+     */
+    registerWork?: (sourcePath: string, description: string) => Promise<string>;
+    /**
+     * run_team_meeting 评估/评审型会议回调（由 agent 装配时注入，处理 run_team_meeting）
+     *
+     * 工具内嵌 LLM 调用的新形态：回调持有 rolePackManager（组解析 + persona 全文）与
+     * 前台 provider（单次 chat），在装配层闭包中实现一次调用注入多角色 persona 的会议。
+     * 委托装配层注入的回调，避免 ToolExecutor 与 rolePackManager/llm 强耦合（同 readSkill 模式）。
+     * 未注入时 run_team_meeting 返回不可用提示。
+     */
+    runTeamMeeting?: (group: string, topic: string) => Promise<string>;
     constructor(projectPath: string, security: SecurityGuard, memoryIndex: IMemoryStorage, 
-    /** 作品投影管理器（可选，读取文件时自动生成投影） */
-    workProjection?: WorkProjectionManager, 
-    /** 配置目录路径（可选，拦截提示中告知 LLM 正确的写入位置） */
-    configDir?: string);
+    /** 网络搜索提供者（可选，不传则不启用网络搜索能力） */
+    webSearchProvider?: IWebSearchProvider, 
+    /** 会话存储（可选，trace_summary 溯源原始对话用） */
+    sessionStore?: ISessionStore, 
+    /** 网页抓取提供者（可选，不传则不启用 web_fetch 工具） */
+    fetchProvider?: IFetchProvider, 
+    /** 代码执行提供者（可选，不传则不启用 run_code 工具） */
+    codeExecutionProvider?: ICodeExecutionProvider, 
+    /** 项目搜索提供者（可选，不传则不启用 search_project 工具） */
+    projectSearchProvider?: IProjectSearchProvider, 
+    /** node 可执行文件路径（可选）：run_project_script 的 node runtime 分支注入真实 node 路径 */
+    scriptNodePath?: string);
+    /**
+     * 注入 MemoryInspector，启用 search_memories 的纯关键词检索后端（无向量后端）。
+     * assembler 中它依赖 loop/history、后于 toolExec 构造，故用「构造后注入」——装配期经
+     * toolExec.setMemoryInspector(...) 接线，未注入时 search_memories 保持基础内存查询行为。
+     *
+     * @param inspector 记忆搜索器（纯关键词，含 superseded 过滤 + 溯源揭示）
+     */
+    setMemoryInspector(inspector: MemoryInspector): void;
+    /**
+     * 注入 memoryRecalled 事件发射回调（宿主感知「LLM 查询记忆命中 N 条」，§2.4 保留改语义定案）。
+     * 转发给 builtinHandlers：search_memories 命中记忆时触发，为全库**唯一** memoryRecalled
+     * 发射位（无 warmRecall 等其他发射路径）。
+     *
+     * @param callback 命中回调（count 命中条数 / query 检索词），缺省注入则工具静默（无宿主 no-op）
+     */
+    setOnMemoryRecalled(callback: (info: {
+        count: number;
+        query: string;
+    }) => void): void;
+    /**
+     * 注入召回互斥排除集提供者（memory-tool-recall-design §5.1 工具互斥），
+     * 转发给 builtinHandlers：search_memories 用它排除「正文或摘要已在眼前」的轮次 round-summary。
+     * assembler 中装配期 wiring（与 setMemoryInspector 同一时机），缺省不注入则工具不过滤。
+     *
+     * @param provider 返回当前会话「内容已在上下文」的 roundId 精确集合（无参，从 loop 视图派生）
+     */
+    setExclusionRoundIdsProvider(provider: () => ReadonlySet<string>): void;
     /**
      * 注册自定义工具
      *
@@ -92,6 +278,15 @@ export declare class ToolExecutor {
      * @throws 工具名与内置工具冲突或已注册时抛错
      */
     registerTool(definition: ToolDefinition, handler: ToolHandler): void;
+    /**
+     * 移除自定义工具
+     *
+     * 供测试场景使用，可在测试后清理已注册的自定义工具。
+     * 仅能移除通过 registerTool 注册的自定义工具，无法移除内置工具。
+     *
+     * @param name 工具名称
+     */
+    removeTool(name: string): void;
     /**
      * 设置工具列表变更回调
      *
@@ -104,9 +299,40 @@ export declare class ToolExecutor {
      */
     setOnToolsChanged(callback: (() => void) | undefined): void;
     /**
-     * 获取所有工具定义（IX-02：统一为 getter 风格，与 persona/skill 一致）
+     * 设置工具白名单（换角色 → 工具集切换）
+     *
+     * 角色包激活/切换时由 Agent 调用（getActiveCapabilities → resolveCapabilityTools），
+     * 把中立能力声明映射为 memora 工具白名单。变更后触发 onToolsChanged，
+     * AgentLoop 的 toolDefinitions 快照与 system prompt 自动刷新。
+     *
+     * @param whitelist 白名单工具名数组；null=全部暴露（默认，无能力声明时）
+     */
+    setToolWhitelist(whitelist: string[] | null): void;
+    /** 获取当前工具白名单（null=全部暴露） */
+    get currentToolWhitelist(): string[] | null;
+    /**
+     * 获取所有工具定义（getter 风格，与 persona/skill 一致）
+     *
+     * 白名单语义（tool-exposure-model 特权声明模型）：
+     * - toolWhitelist === null：全部暴露（内置 + web_search 条件 + 自定义工具）；
+     * - toolWhitelist === string[]：全部暴露命中「默认常驻豁免集 DEFAULT_EXPOSED_TOOLS」的
+     *   内置工具，特权工具（web_search / web_fetch / run_code / task_table_*）按名单过滤；
+     * - toolWhitelist === []：仅常驻豁免集（角色无任何特权能力时，本地能力仍完整可用）。
+     * - 自定义工具始终暴露（宿主注册，属宿主能力面，角色包能力声明不越权过滤宿主工具）；
+     * - search_project：宿主注入即暴露（方案乙）——本地只读工具，等价 read_file 的只读语义，
+     *   不受角色包能力声明与豁免集语义约束（具备与否不决定其可见性）。
      */
     get list(): ToolDefinition[];
+    /**
+     * 完整内置工具定义（只读闸查询用，单一真理源）
+     *
+     * 含全部始终内置工具 + 条件工具（web_search / web_fetch / run_code，仅定义层面，
+     * 不论 provider 是否注入）。不过白名单过滤、不含自定义工具——只读闸（ToolRunner）需要
+     * 「全部内置定义」以查 readonly 标记，而非「当前暴露面」（被白名单过滤的工具 LLM 调不到，
+     * 但 readonly 语义应覆盖全部内置写操作）。定义合集真源 = `builtinTools.ALL_BUILTIN_TOOL_DEFS`
+     * （写盘派生索引同源消费），此处只转手、不另存清单。
+     */
+    get builtinDefinitions(): ToolDefinition[];
     /**
      * 执行工具调用
      *
@@ -120,7 +346,7 @@ export declare class ToolExecutor {
      * @param extensions 写入扩展（可选，用于 diff 确认等）
      * @returns 工具结果的字符串描述
      */
-    execute(name: string, argsJson: string, extensions?: WriteExtensions): Promise<ToolResult>;
+    execute(name: string, argsJson: string, extensions?: WriteExtensions): Promise<string>;
     /**
      * 参数类型校验 + 自动修正
      *

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

@@ -1 +1 @@
-{"version":3,"file":"toolExecutor.d.ts","sourceRoot":"","sources":["../../src/agent/toolExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,KAAK,UAAU,GAAG,MAAM,CAAC;AAEzB;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CACd,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,YAAY,EAAE,MAAM,KACjB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;OAKG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAgB/F;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,6BAA6B;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsB;IACtD;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAAC,CAAa;gBAGlC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,aAAa,EACvB,WAAW,EAAE,cAAc;IAC3B,8BAA8B;IAC9B,cAAc,CAAC,EAAE,qBAAqB;IACtC,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM;IAapB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IA2BpE;;;;;;;;;OASG;IACH,iBAAiB,CAAC,QAAQ,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI;IAI3D;;OAEG;IACH,IAAI,IAAI,IAAI,cAAc,EAAE,CAE3B;IAED;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAwGhG;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,qBAAqB;CAyE9B"}
+{"version":3,"file":"toolExecutor.d.ts","sourceRoot":"","sources":["../../src/agent/toolExecutor.ts"],"names":[],"mappings":"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"}