@zqagent/core 0.2.16 → 0.3.6

package/dist/{explore-RtZtb-V6.d.ts → TurnEngine-BPKhWuSI.d.cts}

@@ -1,6 +1,8 @@
-import { a as TokenUsage, b as ToolMetadata, M as Message, c as ToolSchema, R as ReasoningEffort, S as StreamChunk, T as ToolRegistry } from './ToolRegistry-C3pTFiaJ.js';
+import { T as TokenUsage, M as Message, a as ToolSchema, R as ReasoningEffort, S as StreamChunk, b as MessageAttachment, c as StoredAttachment } from './types-BYyXWWPW.cjs';
+import { a as ToolMetadata, T as ToolRegistry } from './ToolRegistry-DouDvn9E.cjs';
 import { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 import { RequestOptions } from 'openai/core.mjs';
+import { ModelCapability } from '@zqagent/shared/model-capabilities';
 
 /**
  * 事件模型
@@ -182,6 +184,7 @@ interface EngineHook {
  *   - 运行模式（只读模式硬阻断写入与 shell）
  *   - 工具风险分类（读 / 写 / 执行 / 外部）
  *   - 写入路径是否在可写根目录内
+ *   - shell 是否可免审（OS 沙箱生效 / 命令路径都在工作区内）
  *   - 命令是否命中白名单（且不含 shell 运算符）
  *   - 会话级白名单（用户选择「总是允许」后生效）
  */
@@ -206,6 +209,24 @@ interface Decision {
     /** 是否需要用户审批 */
     needsUser: boolean;
 }
+/**
+ * shell 免审策略
+ *
+ * - `approve`：除白名单外一律审批（默认，保持既有语义）
+ * - `sandbox`：仅当 OS 级沙箱生效时免审，否则审批
+ * - `workspace`：沙箱生效 → 免审；未生效 → 用工作区路径判定兜底
+ * - `all`：shell 全部免审（等同只对 shell 生效的 auto 模式）
+ */
+type ShellPolicy = "approve" | "sandbox" | "workspace" | "all";
+/** 权限引擎可见的沙箱状态（由 tools/sandbox.ts 的 SandboxPlan 投影而来） */
+interface ShellSandboxStatus {
+    /** OS 级文件系统约束是否真正生效 */
+    enforced: boolean;
+    /** 后端标识（sandbox-exec / bwrap / none） */
+    backend: string;
+    /** 状态说明（用于审批理由 / 日志） */
+    reason?: string;
+}
 /** 权限引擎 (对齐 Python 版 PermissionEngine) */
 declare class PermissionEngine {
     /** 工作区根目录（写入路径必须位于其下） */
@@ -218,10 +239,19 @@ declare class PermissionEngine {
     sessionAllowTools: Set<string>;
     /** 会话级「总是允许此命令」集合 */
     sessionAllowCommands: Set<string>;
+    /** shell 免审策略 */
+    shellPolicy: ShellPolicy;
+    /** 沙箱状态（未传时视为无沙箱） */
+    sandbox: ShellSandboxStatus | null;
+    /** 取当前 shell cwd（用于工作区判定的相对路径解析） */
+    shellCwd?: () => string | null;
     constructor(opts: {
         workspaceRoot: string;
         mode: Mode;
         allowedCommands?: string[];
+        shellPolicy?: ShellPolicy;
+        sandbox?: ShellSandboxStatus | null;
+        shellCwd?: () => string | null;
     });
     /**
      * 评估工具调用是否允许
@@ -230,6 +260,13 @@ declare class PermissionEngine {
      * 命令白名单 → 会话白名单 → 最后兜底为「需要审批」。
      */
     evaluate(toolName: string, args: Record<string, unknown>, metadata?: ToolMetadata): Decision;
+    /**
+     * 按 shellPolicy 判断是否可免审。
+     *
+     * 返回 decision 时直接采用；否则 hint 说明「为什么仍需审批」，供审批卡片
+     * 展示（例如 `路径越界: /etc/hosts`），让用户一眼看出风险点。
+     */
+    private _autoAllowShell;
     /** 将工具加入会话白名单 */
     allowToolForSession(toolName: string): void;
     /** 将命令加入会话白名单（按可执行程序名记录，同类命令后续直接放行） */
@@ -369,8 +406,18 @@ declare class OpenAIProvider implements ProviderClient {
     private _responsesStream;
     /** Chat Completions 流式路径（默认或 Responses 降级后） */
     private _chatStream;
-    /** 将内部 Message 转换为 OpenAI Chat Completions 格式 */
+    /**
+     * 内部 Message → Chat Completions 消息。
+     *
+     * 带附件时 `content` 变为数组（DeepSeek 与 OpenAI 的通用格式）：
+     *   - 文本 → `{type:"text"}`
+     *   - 图片 → `{type:"image_url", image_url:{url:"data:..."}}`（≤32MiB）
+     *   - 音频 → `{type:"input_audio"}`（仅 wav/mp3，DeepSeek 目前不支持）
+     *   - 视频 → `{type:"video_url"}`（供应商私有扩展，DeepSeek 目前不支持）
+     */
     private _toOpenAIMessages;
+    /** 文本 + 附件 → Chat Completions 的 content part 数组 */
+    private _toOpenAIContent;
     /**
      * 将内部 Message 转换为 OpenAI Responses API 的 input items。
      *
@@ -518,8 +565,30 @@ interface TurnEngineOpts {
     instructions: string;
     /** 生成会话名称的提示词 */
     genSessionNamePrompt?: string;
-    /** 单轮最大迭代次数（默认 300） */
+    /**
+     * 界面语言（zh / en / zh-TW / ja / ko / es）。
+     *
+     * 影响会话自动命名的语言，以及上下文压缩摘要与续接指令的语言。
+     * 系统提示词本身由调用方按语言构建后通过 `instructions` 传入。
+     */
+    lang?: string;
+    /** 单轮最大迭代次数（缺省用 DEFAULT_MAX_ITERATIONS） */
     maxIterations?: number;
+    /**
+     * 达到迭代上限后，是否再用一轮「不带工具」的调用让模型收尾总结。
+     *
+     * 只给子代理（explore）用：它的产出就是一份报告，半途而废等于白跑。
+     * 主代理撞上限通常意味着任务确实没做完，强行总结会给出似是而非的结论，
+     * 因此缺省关闭。
+     */
+    finalizeOnMaxIterations?: boolean;
+    /**
+     * 当前模型的输入能力（来自 `modelMeta.capabilities`）。
+     *
+     * 决定附件走「内联给模型」还是「落进工作目录交给助手读」。**不传表示调用方
+     * 没有能力信息**（直接集成 core / CLI），此时沿用旧行为：模态可识别就内联。
+     */
+    modelCapabilities?: ModelCapability[];
     /**
      * 推理强度（可选）。透传给 Provider 的 LLM 请求参数
      * （OpenAI reasoning_effort；DeepSeek 自动跳过）。
@@ -555,6 +624,7 @@ declare class TurnEngine {
     model: string;
     instructions: string;
     genSessionNamePrompt: string;
+    lang: string;
     maxIterations: number;
     /** 对话历史（含 notice 消息，发送前过滤） */
     messages: Message[];
@@ -566,6 +636,11 @@ declare class TurnEngine {
     private _llmAbort;
     private _toolAbort;
     private _steering;
+    /**
+     * 当前模型的输入能力。`undefined` = 调用方没提供（直接集成 core / CLI），
+     * 此时沿用旧行为：模态可识别的附件都内联给模型。
+     */
+    private readonly _modelCaps;
     compactionState: CompactionState | null;
     private _lastContextTokens;
     /** 压缩无进展时的消息条数快照；-1 表示无冷却 */
@@ -592,6 +667,10 @@ declare class TurnEngine {
     private taskId?;
     /** 推理强度（透传给 Provider；undefined = 使用模型默认） */
     private _reasoningEffort;
+    /** 撞上限后是否再跑一轮收尾（见 TurnEngineOpts.finalizeOnMaxIterations） */
+    private _finalizeOnMaxIterations;
+    /** 收尾轮只跑一次（防止 yield* 被重入时反复总结） */
+    private _finalized;
     constructor(opts: TurnEngineOpts);
     /**
      * 外部中断：置位取消标记 + 掐断在飞的 LLM 请求 + 中止正在执行的工具，
@@ -607,8 +686,18 @@ declare class TurnEngine {
      * 若历史首条不是 system（如恢复的会话），则在最前插入新的 system 消息。
      */
     setSystemPrompt(prompt: string): void;
+    /**
+     * 把「模型读不了的附件」落到工作目录，并把路径拼进用户输入。
+     *
+     * 模型不知道自己漏收了什么，所以必须显式写进消息：否则用户说「见附件」，
+     * 模型回「我看不到附件」，任务直接卡死。落盘失败的文件不提及（避免给出
+     * 一个不存在的路径）。
+     *
+     * @returns 内联给模型的附件（已剔除落盘的那些）+ 可能加了说明的文本
+     */
+    private _routeAttachments;
     /** 排队 steering 消息（下一迭代间隙注入为 user 消息） */
-    queueSteering(text: string): void;
+    queueSteering(text: string, attachments?: MessageAttachment[], attachmentRefs?: StoredAttachment[]): void;
     /**
      * 撤销一条尚未注入的 steering。
      *
@@ -625,7 +714,9 @@ declare class TurnEngine {
      * 追加用户输入到历史，产出 TURN_START 事件，然后转发 _loop()
      * 的全部事件。收到中断后仍会消费完剩余事件（保证 TURN_END 产出）。
      */
-    run(userInput: string, taskId?: string): AsyncGenerator<WsEvent>;
+    run(userInput: string, taskId?: string, attachments?: MessageAttachment[], 
+    /** 附件落盘引用（由会话层先存盘再传入）：消息与事件只带它，不带 base64 */
+    attachmentRefs?: StoredAttachment[]): AsyncGenerator<WsEvent>;
     /** 重试 (仅在 Provider 错误后可用) */
     retry(): AsyncGenerator<WsEvent>;
     /** 从持久化的挂起点恢复 Turn (对齐 Python 版 resume) */
@@ -648,6 +739,17 @@ declare class TurnEngine {
      * 则执行（_handleToolCalls）→ ITERATION_END → 检查中断与 steering。
      */
     private _loop;
+    /**
+     * 撞上限后的收尾轮（仅 finalizeOnMaxIterations）。
+     *
+     * 与正常迭代的区别只有两点：追加一条「停止探索、输出报告」的指令，
+     * 以及**不提供任何工具**（schemas 传空）。这样模型没有可调用的工具，
+     * 只能把已经读到的内容写成正文；正文会像正常轮次一样产出
+     * ASSISTANT_MESSAGE，explore 据此取到报告。
+     *
+     * 收尾轮失败不改变结束状态：已流出的正文照样交给调用方，比直接丢弃好。
+     */
+    private _finalizeAtLimit;
     /**
      * 处理一轮迭代中的全部工具调用
      *
@@ -723,71 +825,4 @@ declare class TurnEngine {
     private _scanRecentFiles;
 }
 
-/**
- * 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;
-    readonlyRegistrars?: (registry: ToolRegistry) => void;
-    /**
-     * 子引擎生命周期钩子（可选）：注入后子代理的执行过程（工具活动、终态）
-     * 会回调给调用方渲染（如 CLI 的 SubagentHook）；不传则与旧版一致（静默）。
-     */
-    hook?: EngineHook;
-    /** 超预算工具结果的落盘目录（与主引擎共用，保持租户隔离） */
-    toolResultDir?: string;
-}): TurnEngine;
-/**
- * 创建 explore 工具函数
- *
- * 每次调用都会新建一个独立的子引擎，运行研究任务并收集
- * 子代理的最终回复作为报告返回。
- */
-declare function makeExploreTool(opts: {
-    workspace: string;
-    provider: ProviderClient;
-    model: 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;
-    readonlyRegistrars?: (registry: ToolRegistry) => void;
-    /** 子引擎钩子工厂（可选）：见 makeExploreTool */
-    hookFactory?: () => EngineHook;
-    /** 超预算工具结果的落盘目录（透传给子引擎） */
-    toolResultDir?: string;
-}): void;
-
-export { ApprovalOutcome as A, type CompactionStartInfo as C, type Decision as D, type EngineHook as E, Mode as M, OpenAIProvider as O, type ProviderClient as P, TurnEngine as T, type WsEvent as W, type CompactionDoneInfo as a, EventType as b, type EngineErrorInfo as c, type Approver as d, type CompactionTrigger as e, PermissionEngine as f, type PermissionRequest as g, type TurnEngineOpts as h, buildExplorerEngine as i, makeExploreTool as m, registerExploreTool as r };
+export { ApprovalOutcome as A, type CompactionStartInfo as C, type Decision as D, type EngineHook as E, Mode as M, OpenAIProvider as O, type ProviderClient as P, type ShellPolicy as S, TurnEngine as T, type WsEvent as W, type CompactionDoneInfo as a, EventType as b, type EngineErrorInfo as c, type Approver as d, type CompactionTrigger as e, PermissionEngine as f, type PermissionRequest as g, type ShellSandboxStatus as h, type TurnEngineOpts as i };

package/dist/{explore-BgRhj6SP.d.cts → TurnEngine-DtGEuVLT.d.ts}

@@ -1,6 +1,8 @@
-import { a as TokenUsage, b as ToolMetadata, M as Message, c as ToolSchema, R as ReasoningEffort, S as StreamChunk, T as ToolRegistry } from './ToolRegistry-C3pTFiaJ.cjs';
+import { T as TokenUsage, M as Message, a as ToolSchema, R as ReasoningEffort, S as StreamChunk, b as MessageAttachment, c as StoredAttachment } from './types-BYyXWWPW.js';
+import { a as ToolMetadata, T as ToolRegistry } from './ToolRegistry-Cy0fQxrb.js';
 import { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 import { RequestOptions } from 'openai/core.mjs';
+import { ModelCapability } from '@zqagent/shared/model-capabilities';
 
 /**
  * 事件模型
@@ -182,6 +184,7 @@ interface EngineHook {
  *   - 运行模式（只读模式硬阻断写入与 shell）
  *   - 工具风险分类（读 / 写 / 执行 / 外部）
  *   - 写入路径是否在可写根目录内
+ *   - shell 是否可免审（OS 沙箱生效 / 命令路径都在工作区内）
  *   - 命令是否命中白名单（且不含 shell 运算符）
  *   - 会话级白名单（用户选择「总是允许」后生效）
  */
@@ -206,6 +209,24 @@ interface Decision {
     /** 是否需要用户审批 */
     needsUser: boolean;
 }
+/**
+ * shell 免审策略
+ *
+ * - `approve`：除白名单外一律审批（默认，保持既有语义）
+ * - `sandbox`：仅当 OS 级沙箱生效时免审，否则审批
+ * - `workspace`：沙箱生效 → 免审；未生效 → 用工作区路径判定兜底
+ * - `all`：shell 全部免审（等同只对 shell 生效的 auto 模式）
+ */
+type ShellPolicy = "approve" | "sandbox" | "workspace" | "all";
+/** 权限引擎可见的沙箱状态（由 tools/sandbox.ts 的 SandboxPlan 投影而来） */
+interface ShellSandboxStatus {
+    /** OS 级文件系统约束是否真正生效 */
+    enforced: boolean;
+    /** 后端标识（sandbox-exec / bwrap / none） */
+    backend: string;
+    /** 状态说明（用于审批理由 / 日志） */
+    reason?: string;
+}
 /** 权限引擎 (对齐 Python 版 PermissionEngine) */
 declare class PermissionEngine {
     /** 工作区根目录（写入路径必须位于其下） */
@@ -218,10 +239,19 @@ declare class PermissionEngine {
     sessionAllowTools: Set<string>;
     /** 会话级「总是允许此命令」集合 */
     sessionAllowCommands: Set<string>;
+    /** shell 免审策略 */
+    shellPolicy: ShellPolicy;
+    /** 沙箱状态（未传时视为无沙箱） */
+    sandbox: ShellSandboxStatus | null;
+    /** 取当前 shell cwd（用于工作区判定的相对路径解析） */
+    shellCwd?: () => string | null;
     constructor(opts: {
         workspaceRoot: string;
         mode: Mode;
         allowedCommands?: string[];
+        shellPolicy?: ShellPolicy;
+        sandbox?: ShellSandboxStatus | null;
+        shellCwd?: () => string | null;
     });
     /**
      * 评估工具调用是否允许
@@ -230,6 +260,13 @@ declare class PermissionEngine {
      * 命令白名单 → 会话白名单 → 最后兜底为「需要审批」。
      */
     evaluate(toolName: string, args: Record<string, unknown>, metadata?: ToolMetadata): Decision;
+    /**
+     * 按 shellPolicy 判断是否可免审。
+     *
+     * 返回 decision 时直接采用；否则 hint 说明「为什么仍需审批」，供审批卡片
+     * 展示（例如 `路径越界: /etc/hosts`），让用户一眼看出风险点。
+     */
+    private _autoAllowShell;
     /** 将工具加入会话白名单 */
     allowToolForSession(toolName: string): void;
     /** 将命令加入会话白名单（按可执行程序名记录，同类命令后续直接放行） */
@@ -369,8 +406,18 @@ declare class OpenAIProvider implements ProviderClient {
     private _responsesStream;
     /** Chat Completions 流式路径（默认或 Responses 降级后） */
     private _chatStream;
-    /** 将内部 Message 转换为 OpenAI Chat Completions 格式 */
+    /**
+     * 内部 Message → Chat Completions 消息。
+     *
+     * 带附件时 `content` 变为数组（DeepSeek 与 OpenAI 的通用格式）：
+     *   - 文本 → `{type:"text"}`
+     *   - 图片 → `{type:"image_url", image_url:{url:"data:..."}}`（≤32MiB）
+     *   - 音频 → `{type:"input_audio"}`（仅 wav/mp3，DeepSeek 目前不支持）
+     *   - 视频 → `{type:"video_url"}`（供应商私有扩展，DeepSeek 目前不支持）
+     */
     private _toOpenAIMessages;
+    /** 文本 + 附件 → Chat Completions 的 content part 数组 */
+    private _toOpenAIContent;
     /**
      * 将内部 Message 转换为 OpenAI Responses API 的 input items。
      *
@@ -518,8 +565,30 @@ interface TurnEngineOpts {
     instructions: string;
     /** 生成会话名称的提示词 */
     genSessionNamePrompt?: string;
-    /** 单轮最大迭代次数（默认 300） */
+    /**
+     * 界面语言（zh / en / zh-TW / ja / ko / es）。
+     *
+     * 影响会话自动命名的语言，以及上下文压缩摘要与续接指令的语言。
+     * 系统提示词本身由调用方按语言构建后通过 `instructions` 传入。
+     */
+    lang?: string;
+    /** 单轮最大迭代次数（缺省用 DEFAULT_MAX_ITERATIONS） */
     maxIterations?: number;
+    /**
+     * 达到迭代上限后，是否再用一轮「不带工具」的调用让模型收尾总结。
+     *
+     * 只给子代理（explore）用：它的产出就是一份报告，半途而废等于白跑。
+     * 主代理撞上限通常意味着任务确实没做完，强行总结会给出似是而非的结论，
+     * 因此缺省关闭。
+     */
+    finalizeOnMaxIterations?: boolean;
+    /**
+     * 当前模型的输入能力（来自 `modelMeta.capabilities`）。
+     *
+     * 决定附件走「内联给模型」还是「落进工作目录交给助手读」。**不传表示调用方
+     * 没有能力信息**（直接集成 core / CLI），此时沿用旧行为：模态可识别就内联。
+     */
+    modelCapabilities?: ModelCapability[];
     /**
      * 推理强度（可选）。透传给 Provider 的 LLM 请求参数
      * （OpenAI reasoning_effort；DeepSeek 自动跳过）。
@@ -555,6 +624,7 @@ declare class TurnEngine {
     model: string;
     instructions: string;
     genSessionNamePrompt: string;
+    lang: string;
     maxIterations: number;
     /** 对话历史（含 notice 消息，发送前过滤） */
     messages: Message[];
@@ -566,6 +636,11 @@ declare class TurnEngine {
     private _llmAbort;
     private _toolAbort;
     private _steering;
+    /**
+     * 当前模型的输入能力。`undefined` = 调用方没提供（直接集成 core / CLI），
+     * 此时沿用旧行为：模态可识别的附件都内联给模型。
+     */
+    private readonly _modelCaps;
     compactionState: CompactionState | null;
     private _lastContextTokens;
     /** 压缩无进展时的消息条数快照；-1 表示无冷却 */
@@ -592,6 +667,10 @@ declare class TurnEngine {
     private taskId?;
     /** 推理强度（透传给 Provider；undefined = 使用模型默认） */
     private _reasoningEffort;
+    /** 撞上限后是否再跑一轮收尾（见 TurnEngineOpts.finalizeOnMaxIterations） */
+    private _finalizeOnMaxIterations;
+    /** 收尾轮只跑一次（防止 yield* 被重入时反复总结） */
+    private _finalized;
     constructor(opts: TurnEngineOpts);
     /**
      * 外部中断：置位取消标记 + 掐断在飞的 LLM 请求 + 中止正在执行的工具，
@@ -607,8 +686,18 @@ declare class TurnEngine {
      * 若历史首条不是 system（如恢复的会话），则在最前插入新的 system 消息。
      */
     setSystemPrompt(prompt: string): void;
+    /**
+     * 把「模型读不了的附件」落到工作目录，并把路径拼进用户输入。
+     *
+     * 模型不知道自己漏收了什么，所以必须显式写进消息：否则用户说「见附件」，
+     * 模型回「我看不到附件」，任务直接卡死。落盘失败的文件不提及（避免给出
+     * 一个不存在的路径）。
+     *
+     * @returns 内联给模型的附件（已剔除落盘的那些）+ 可能加了说明的文本
+     */
+    private _routeAttachments;
     /** 排队 steering 消息（下一迭代间隙注入为 user 消息） */
-    queueSteering(text: string): void;
+    queueSteering(text: string, attachments?: MessageAttachment[], attachmentRefs?: StoredAttachment[]): void;
     /**
      * 撤销一条尚未注入的 steering。
      *
@@ -625,7 +714,9 @@ declare class TurnEngine {
      * 追加用户输入到历史，产出 TURN_START 事件，然后转发 _loop()
      * 的全部事件。收到中断后仍会消费完剩余事件（保证 TURN_END 产出）。
      */
-    run(userInput: string, taskId?: string): AsyncGenerator<WsEvent>;
+    run(userInput: string, taskId?: string, attachments?: MessageAttachment[], 
+    /** 附件落盘引用（由会话层先存盘再传入）：消息与事件只带它，不带 base64 */
+    attachmentRefs?: StoredAttachment[]): AsyncGenerator<WsEvent>;
     /** 重试 (仅在 Provider 错误后可用) */
     retry(): AsyncGenerator<WsEvent>;
     /** 从持久化的挂起点恢复 Turn (对齐 Python 版 resume) */
@@ -648,6 +739,17 @@ declare class TurnEngine {
      * 则执行（_handleToolCalls）→ ITERATION_END → 检查中断与 steering。
      */
     private _loop;
+    /**
+     * 撞上限后的收尾轮（仅 finalizeOnMaxIterations）。
+     *
+     * 与正常迭代的区别只有两点：追加一条「停止探索、输出报告」的指令，
+     * 以及**不提供任何工具**（schemas 传空）。这样模型没有可调用的工具，
+     * 只能把已经读到的内容写成正文；正文会像正常轮次一样产出
+     * ASSISTANT_MESSAGE，explore 据此取到报告。
+     *
+     * 收尾轮失败不改变结束状态：已流出的正文照样交给调用方，比直接丢弃好。
+     */
+    private _finalizeAtLimit;
     /**
      * 处理一轮迭代中的全部工具调用
      *
@@ -723,71 +825,4 @@ declare class TurnEngine {
     private _scanRecentFiles;
 }
 
-/**
- * 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;
-    readonlyRegistrars?: (registry: ToolRegistry) => void;
-    /**
-     * 子引擎生命周期钩子（可选）：注入后子代理的执行过程（工具活动、终态）
-     * 会回调给调用方渲染（如 CLI 的 SubagentHook）；不传则与旧版一致（静默）。
-     */
-    hook?: EngineHook;
-    /** 超预算工具结果的落盘目录（与主引擎共用，保持租户隔离） */
-    toolResultDir?: string;
-}): TurnEngine;
-/**
- * 创建 explore 工具函数
- *
- * 每次调用都会新建一个独立的子引擎，运行研究任务并收集
- * 子代理的最终回复作为报告返回。
- */
-declare function makeExploreTool(opts: {
-    workspace: string;
-    provider: ProviderClient;
-    model: 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;
-    readonlyRegistrars?: (registry: ToolRegistry) => void;
-    /** 子引擎钩子工厂（可选）：见 makeExploreTool */
-    hookFactory?: () => EngineHook;
-    /** 超预算工具结果的落盘目录（透传给子引擎） */
-    toolResultDir?: string;
-}): void;
-
-export { ApprovalOutcome as A, type CompactionStartInfo as C, type Decision as D, type EngineHook as E, Mode as M, OpenAIProvider as O, type ProviderClient as P, TurnEngine as T, type WsEvent as W, type CompactionDoneInfo as a, EventType as b, type EngineErrorInfo as c, type Approver as d, type CompactionTrigger as e, PermissionEngine as f, type PermissionRequest as g, type TurnEngineOpts as h, buildExplorerEngine as i, makeExploreTool as m, registerExploreTool as r };
+export { ApprovalOutcome as A, type CompactionStartInfo as C, type Decision as D, type EngineHook as E, Mode as M, OpenAIProvider as O, type ProviderClient as P, type ShellPolicy as S, TurnEngine as T, type WsEvent as W, type CompactionDoneInfo as a, EventType as b, type EngineErrorInfo as c, type Approver as d, type CompactionTrigger as e, PermissionEngine as f, type PermissionRequest as g, type ShellSandboxStatus as h, type TurnEngineOpts as i };

package/dist/conflictGuard-BBOOIxxK.d.cts

@@ -0,0 +1,42 @@
+/** 内容指纹（sha256 前 16 位，足够防碰撞且便于展示） */
+declare function contentDigest(content: string | null | undefined): string;
+interface WriteConflict {
+    /** 绝对路径 */
+    path: string;
+    /** 本会话读到的版本指纹 */
+    expected: string;
+    /** 磁盘上的当前指纹；文件已被删除时为 null */
+    actual: string | null;
+    /** 给模型看的错误消息（可直接作为工具返回值） */
+    message: string;
+}
+/**
+ * 会话级写冲突检测器。
+ *
+ * 一个会话一个实例；跨会话不共享状态，这正是「检测」而非「阻止」的前提：
+ * 每个会话只知道**自己**读到过什么，因此在别人改动后写入会被发现。
+ */
+declare class ConflictGuard {
+    /** 绝对路径 → 本会话最近一次读到（或自己写入）的内容指纹 */
+    private readonly digests;
+    /** 记录一次读取：后续写入将以这个版本为基准 */
+    noteRead(absPath: string, content: string): void;
+    /** 记录一次自己的写入：更新基准，避免同会话连续写触发误报 */
+    noteWrite(absPath: string, content: string): void;
+    /** 是否读过该文件（用于判断「有没有保护」） */
+    hasRead(absPath: string): boolean;
+    /**
+     * 写入前检查。
+     *
+     * 返回 null 表示可以写：
+     * - 本会话没读过该文件（不保护，保持既有行为）；
+     * - 或者磁盘内容与读到的版本一致。
+     *
+     * 返回冲突时调用方应放弃写入并把 message 交给模型，由它重新读取后重试。
+     */
+    checkWrite(absPath: string, displayPath: string): WriteConflict | null;
+    /** 清空记录（会话结束 / 测试用） */
+    reset(): void;
+}
+
+export { ConflictGuard as C, type WriteConflict as W, contentDigest as c };

package/dist/conflictGuard-BBOOIxxK.d.ts

@@ -0,0 +1,42 @@
+/** 内容指纹（sha256 前 16 位，足够防碰撞且便于展示） */
+declare function contentDigest(content: string | null | undefined): string;
+interface WriteConflict {
+    /** 绝对路径 */
+    path: string;
+    /** 本会话读到的版本指纹 */
+    expected: string;
+    /** 磁盘上的当前指纹；文件已被删除时为 null */
+    actual: string | null;
+    /** 给模型看的错误消息（可直接作为工具返回值） */
+    message: string;
+}
+/**
+ * 会话级写冲突检测器。
+ *
+ * 一个会话一个实例；跨会话不共享状态，这正是「检测」而非「阻止」的前提：
+ * 每个会话只知道**自己**读到过什么，因此在别人改动后写入会被发现。
+ */
+declare class ConflictGuard {
+    /** 绝对路径 → 本会话最近一次读到（或自己写入）的内容指纹 */
+    private readonly digests;
+    /** 记录一次读取：后续写入将以这个版本为基准 */
+    noteRead(absPath: string, content: string): void;
+    /** 记录一次自己的写入：更新基准，避免同会话连续写触发误报 */
+    noteWrite(absPath: string, content: string): void;
+    /** 是否读过该文件（用于判断「有没有保护」） */
+    hasRead(absPath: string): boolean;
+    /**
+     * 写入前检查。
+     *
+     * 返回 null 表示可以写：
+     * - 本会话没读过该文件（不保护，保持既有行为）；
+     * - 或者磁盘内容与读到的版本一致。
+     *
+     * 返回冲突时调用方应放弃写入并把 message 交给模型，由它重新读取后重试。
+     */
+    checkWrite(absPath: string, displayPath: string): WriteConflict | null;
+    /** 清空记录（会话结束 / 测试用） */
+    reset(): void;
+}
+
+export { ConflictGuard as C, type WriteConflict as W, contentDigest as c };