@zqagent/core 0.2.20 → 0.3.6

package/dist/tools/explore.d.cts

@@ -1,4 +1,84 @@
-import '../ToolRegistry-C3pTFiaJ.cjs';
-export { i as buildExplorerEngine, m as makeExploreTool, r as registerExploreTool } from '../explore-BgRhj6SP.cjs';
+import { T as ToolRegistry } from '../ToolRegistry-DouDvn9E.cjs';
+import { P as ProviderClient, E as EngineHook, T as TurnEngine } from '../TurnEngine-BPKhWuSI.cjs';
+import '../types-BYyXWWPW.cjs';
+import '@zqagent/shared/model-capabilities';
 import 'openai/resources/chat/completions.js';
 import 'openai/core.mjs';
+
+/**
+ * Explore 子代理工具
+ *
+ * 提供 explore 工具：把广泛的只读研究任务委托给一个独立的
+ * TurnEngine 子代理。子代理在自己的上下文中搜索和阅读代码，
+ * 只把最终报告返回给调用方——中间的搜索过程不消耗调用方的上下文。
+ * 子代理只注册只读工具（read_file / list_files / grep /
+ * git_log / git_status / git_diff），并以 Plan 模式运行，
+ * 从机制上保证不会写文件或执行命令。
+ */
+
+/**
+ * 构建 Explorer 子引擎 (对齐 Python 版 build_explorer_engine)
+ *
+ * 只注册只读工具，使用 Plan 模式权限引擎（硬阻断所有写入），
+ * 迭代上限默认 30 次（环境变量 EXPLORE_MAX_ITERATIONS 可覆盖）。
+ *
+ * 上限同时写进提示词，并开启「撞上限后收尾」：子代理不会因为不知道预算而
+ * 把轮次耗在漫游上，真到上限也能把已有发现写成报告，而不是整轮作废。
+ *
+ * 可选 readonlyRegistrars：外部可注入"只读工具注册器"（例如沙箱远程工具），
+ * 用于把 explore 子代理的执行目标从宿主机工作区切换到远程沙箱。
+ * 缺省时使用本地文件系统的只读工具（行为与旧版一致）。
+ */
+declare function buildExplorerEngine(opts: {
+    workspace: string;
+    provider: ProviderClient;
+    model: string;
+    /** 界面语言（提示词与报告跟随它；缺省简中） */
+    lang?: string;
+    readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /**
+     * 子引擎生命周期钩子（可选）：注入后子代理的执行过程（工具活动、终态）
+     * 会回调给调用方渲染（如 CLI 的 SubagentHook）；不传则与旧版一致（静默）。
+     */
+    hook?: EngineHook;
+    /** 超预算工具结果的落盘目录（与主引擎共用，保持租户隔离） */
+    toolResultDir?: string;
+}): TurnEngine;
+/**
+ * 创建 explore 工具函数
+ *
+ * 每次调用都会新建一个独立的子引擎，运行研究任务并收集
+ * 子代理的最终回复作为报告返回。
+ */
+declare function makeExploreTool(opts: {
+    workspace: string;
+    provider: ProviderClient;
+    model: string;
+    /** 界面语言（透传给子引擎） */
+    lang?: string;
+    readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /**
+     * 子引擎钩子工厂（可选）：每次 explore 调用生成一个新实例。
+     *
+     * 用工厂而非共享实例，是因为低风险工具会被并发执行（同一条回复里的多个
+     * explore 会同时运行），共享同一个渲染器会互相串状态、输出交错难辨。
+     */
+    hookFactory?: () => EngineHook;
+    /** 超预算工具结果的落盘目录（透传给子引擎） */
+    toolResultDir?: string;
+}): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/** 注册 explore 工具（低风险，无需审批） */
+declare function registerExploreTool(registry: ToolRegistry, opts: {
+    workspace: string;
+    provider: ProviderClient;
+    model: string;
+    /** 界面语言（透传给子引擎） */
+    lang?: string;
+    readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /** 子引擎钩子工厂（可选）：见 makeExploreTool */
+    hookFactory?: () => EngineHook;
+    /** 超预算工具结果的落盘目录（透传给子引擎） */
+    toolResultDir?: string;
+}): void;
+
+export { buildExplorerEngine, makeExploreTool, registerExploreTool };

package/dist/tools/explore.d.ts

@@ -1,4 +1,84 @@
-import '../ToolRegistry-C3pTFiaJ.js';
-export { i as buildExplorerEngine, m as makeExploreTool, r as registerExploreTool } from '../explore-RtZtb-V6.js';
+import { T as ToolRegistry } from '../ToolRegistry-Cy0fQxrb.js';
+import { P as ProviderClient, E as EngineHook, T as TurnEngine } from '../TurnEngine-DtGEuVLT.js';
+import '../types-BYyXWWPW.js';
+import '@zqagent/shared/model-capabilities';
 import 'openai/resources/chat/completions.js';
 import 'openai/core.mjs';
+
+/**
+ * Explore 子代理工具
+ *
+ * 提供 explore 工具：把广泛的只读研究任务委托给一个独立的
+ * TurnEngine 子代理。子代理在自己的上下文中搜索和阅读代码，
+ * 只把最终报告返回给调用方——中间的搜索过程不消耗调用方的上下文。
+ * 子代理只注册只读工具（read_file / list_files / grep /
+ * git_log / git_status / git_diff），并以 Plan 模式运行，
+ * 从机制上保证不会写文件或执行命令。
+ */
+
+/**
+ * 构建 Explorer 子引擎 (对齐 Python 版 build_explorer_engine)
+ *
+ * 只注册只读工具，使用 Plan 模式权限引擎（硬阻断所有写入），
+ * 迭代上限默认 30 次（环境变量 EXPLORE_MAX_ITERATIONS 可覆盖）。
+ *
+ * 上限同时写进提示词，并开启「撞上限后收尾」：子代理不会因为不知道预算而
+ * 把轮次耗在漫游上，真到上限也能把已有发现写成报告，而不是整轮作废。
+ *
+ * 可选 readonlyRegistrars：外部可注入"只读工具注册器"（例如沙箱远程工具），
+ * 用于把 explore 子代理的执行目标从宿主机工作区切换到远程沙箱。
+ * 缺省时使用本地文件系统的只读工具（行为与旧版一致）。
+ */
+declare function buildExplorerEngine(opts: {
+    workspace: string;
+    provider: ProviderClient;
+    model: string;
+    /** 界面语言（提示词与报告跟随它；缺省简中） */
+    lang?: string;
+    readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /**
+     * 子引擎生命周期钩子（可选）：注入后子代理的执行过程（工具活动、终态）
+     * 会回调给调用方渲染（如 CLI 的 SubagentHook）；不传则与旧版一致（静默）。
+     */
+    hook?: EngineHook;
+    /** 超预算工具结果的落盘目录（与主引擎共用，保持租户隔离） */
+    toolResultDir?: string;
+}): TurnEngine;
+/**
+ * 创建 explore 工具函数
+ *
+ * 每次调用都会新建一个独立的子引擎，运行研究任务并收集
+ * 子代理的最终回复作为报告返回。
+ */
+declare function makeExploreTool(opts: {
+    workspace: string;
+    provider: ProviderClient;
+    model: string;
+    /** 界面语言（透传给子引擎） */
+    lang?: string;
+    readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /**
+     * 子引擎钩子工厂（可选）：每次 explore 调用生成一个新实例。
+     *
+     * 用工厂而非共享实例，是因为低风险工具会被并发执行（同一条回复里的多个
+     * explore 会同时运行），共享同一个渲染器会互相串状态、输出交错难辨。
+     */
+    hookFactory?: () => EngineHook;
+    /** 超预算工具结果的落盘目录（透传给子引擎） */
+    toolResultDir?: string;
+}): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/** 注册 explore 工具（低风险，无需审批） */
+declare function registerExploreTool(registry: ToolRegistry, opts: {
+    workspace: string;
+    provider: ProviderClient;
+    model: string;
+    /** 界面语言（透传给子引擎） */
+    lang?: string;
+    readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /** 子引擎钩子工厂（可选）：见 makeExploreTool */
+    hookFactory?: () => EngineHook;
+    /** 超预算工具结果的落盘目录（透传给子引擎） */
+    toolResultDir?: string;
+}): void;
+
+export { buildExplorerEngine, makeExploreTool, registerExploreTool };