@zqagent/core 0.1.30 → 0.2.4

package/dist/{explore-OI6htHN1.d.cts → explore-D4lCKXbA.d.ts}

@@ -1,4 +1,4 @@
-import { a as TokenUsage, b as ToolMetadata, M as Message, c as ToolSchema, R as ReasoningEffort, S as StreamChunk, T as ToolRegistry } from './ToolRegistry-BmvPxgMr.cjs';
+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 { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 import { RequestOptions } from 'openai/core.mjs';
 
@@ -48,7 +48,11 @@ declare enum EventType {
     /** LLM 请求发出 — 携带 reqId 用于关联审计日志与后续 delta/error 事件 */
     LLM_REQUEST = "llm_request",
     /** 模型通过 ask_user 工具向用户提问 */
-    ASK_USER_QUESTION = "ask_user_question"
+    ASK_USER_QUESTION = "ask_user_question",
+    /** 会话名已（自动/手动）更新 — data: { name, source } */
+    SESSION_NAMED = "session_named",
+    /** 瞬时网络错误自动重试 — data: { attempt, max, reason } */
+    LLM_RETRY = "llm_retry"
 }
 /** WebSocket 事件 (CLI 模式下通过 async generator 模拟) */
 interface WsEvent {
@@ -93,6 +97,45 @@ interface EngineErrorInfo {
     /** 错误堆栈（异常对象存在时提供，可能缺失） */
     stack?: string;
 }
+/**
+ * 上下文压缩触发原因
+ *
+ * - `threshold`：达到触发阈值的预防性压缩
+ * - `overflow`：API 报上下文溢出后的强制压缩
+ */
+type CompactionTrigger = "threshold" | "overflow";
+/** 压缩开始时的上下文用量（供 hook / 事件携带，便于展示更多信息） */
+interface CompactionStartInfo {
+    /** 触发原因 */
+    trigger: CompactionTrigger;
+    /** 触发时的上下文 token 用量（优先 API 精确值，否则为估算） */
+    tokens: number;
+    /** tokens 是否为 chars/4 估算值 */
+    estimated: boolean;
+    /** 当前模型的上下文窗口（token 数） */
+    contextWindow: number;
+    /** 触发阈值占窗口的比例（0-1） */
+    thresholdPct: number;
+    /** 触发阈值（token 数，已计入 capTokens 截断） */
+    thresholdTokens: number;
+    /** 压缩前发送给模型的消息条数 */
+    outboundMessages: number;
+}
+/** 压缩结果信息 */
+interface CompactionDoneInfo {
+    /** summarized=LLM 摘要，trimmed=裁剪降级 */
+    method: "summarized" | "trimmed";
+    /** 压缩前发送给模型的消息条数 */
+    messagesBefore: number;
+    /** 压缩后发送给模型的消息条数 */
+    messagesAfter: number;
+    /** 摘要所用模型（method=summarized 时提供） */
+    model?: string;
+    /** 摘要保留的早期用户消息数 */
+    keptUserMessages?: number;
+    /** 摘要丢弃的早期用户消息数 */
+    droppedUserMessages?: number;
+}
 /**
  * 引擎生命周期钩子
  *
@@ -119,11 +162,13 @@ interface EngineHook {
     onPermissionRequired?(name: string, reason: string): void;
     /** 迭代结束 */
     onIterationEnd?(iteration: number): void;
-    /** 上下文压缩 */
-    onCompacting?(): void;
-    onCompacted?(text: string): void;
+    /** 上下文压缩：开始（info 含触发原因与用量）/ 完成（info 含压缩方式与前后条数） */
+    onCompacting?(info?: CompactionStartInfo): void;
+    onCompacted?(text: string, info?: CompactionDoneInfo): void;
     /** 异常 */
     onError?(error: string, errorType: string, info?: EngineErrorInfo): void;
+    /** 瞬时网络错误自动重试（attempt 从 1 开始） */
+    onRetry?(attempt: number, max: number, reason: string): void;
     onInterrupted?(iterations: number): void;
     /** 通用兜底：所有未匹配到具体回调的事件都会走这里 */
     onEvent?(type: EventType, data: Record<string, unknown>): void;
@@ -187,7 +232,7 @@ declare class PermissionEngine {
     evaluate(toolName: string, args: Record<string, unknown>, metadata?: ToolMetadata): Decision;
     /** 将工具加入会话白名单 */
     allowToolForSession(toolName: string): void;
-    /** 将命令加入会话白名单 */
+    /** 将命令加入会话白名单（按可执行程序名记录，同类命令后续直接放行） */
     allowCommandForSession(command: string): void;
     /**
      * 检查路径是否在可写根目录下
@@ -216,6 +261,19 @@ interface StreamOpts {
      * DeepSeek 不支持级别控制，自动跳过。
      */
     reasoningEffort?: ReasoningEffort;
+    /**
+     * 中止信号（可选）。引擎按下「停止」时 abort，用于掐断在飞的流式请求 ——
+     * 仅置引擎内部的取消标志位无法结束已静默挂死的网络流。
+     */
+    signal?: AbortSignal;
+    /**
+     * 内部字段：流空闲看门狗（由 `stream()` 注入，各流路径复用）。
+     * 引擎侧无需感知，请勿在 `stream()` 之外构造。
+     */
+    idle?: {
+        ms: number;
+        onIdle: () => void;
+    };
 }
 /** LLM Provider 抽象接口 */
 interface ProviderClient {
@@ -229,7 +287,12 @@ interface ProviderClient {
      * @returns 流式 chunk 的异步可迭代对象
      */
     stream(model: string, messages: Message[], tools: ToolSchema[], opts: StreamOpts): Promise<AsyncIterable<StreamChunk>>;
-    chat(model: string, messages: any[], options: RequestOptions, opts: StreamOpts): Promise<string | null>;
+    chat(model: string, messages: any[], options: RequestOptions, opts: StreamOpts, params?: ChatParams): Promise<string | null>;
+}
+/** chat 请求的附加参数（用于会话命名等轻量请求，限制输出长度） */
+interface ChatParams {
+    /** 最大输出 token 数（Responses → max_output_tokens；Chat → max_tokens / max_completion_tokens） */
+    maxTokens?: number;
 }
 /** OpenAI-compatible Provider（Responses API 优先，失败降级 Chat Completions） */
 declare class OpenAIProvider implements ProviderClient {
@@ -256,15 +319,19 @@ declare class OpenAIProvider implements ProviderClient {
      */
     private _resolveMode;
     /**
-     * 判断 Responses 调用失败是否属于"端点不支持"类错误（可安全降级）。
+     * Responses 失败的分类（决定「能不能改走 Chat Completions」以及要不要缓存降级）。
      *
-     * 仅对发生在连接阶段（首字节之前）的错误调用本方法：
-     *   - 404 / 405：端点不存在或方法不允许 → 一律视为不支持
-     *   - 400 / 403：错误信息含 not supported / unsupported /
-     *     unknown endpoint / not implemented 等特征才视为不支持
-     *   - 其它错误（鉴权 401、网络超时等）不降级，原样抛出
+     * @param connectionStage 失败是否发生在连接阶段（首字节之前）。
+     *   流内失败（已建立 SSE 后才收到 response.failed）只在**尚未 yield 任何
+     *   chunk** 时才允许重试，否则会向用户重复输出前半段内容。
+     *
+     * 返回值：
+     *   - "endpoint"：该端点/模型不支持 Responses → 降级 Chat 并写入缓存
+     *   - "param"：参数或模型不被接受（如阿里兼容模式的 InvalidParameter）
+     *     → 本次改走 Chat（Chat 的参数集不同，可能可用），但不写缓存
+     *   - null：鉴权(401)/限流(429)/服务端(5xx)/网络类 → 不降级，原样抛出
      */
-    private _isResponsesUnsupported;
+    private _responsesFailureKind;
     /** 识别 DeepSeek 供应商（模型名或 baseURL 含 "deepseek"） */
     private _isDeepSeek;
     /**
@@ -279,9 +346,24 @@ declare class OpenAIProvider implements ProviderClient {
      * @param opts     reqId 等审计信息
      * @returns 模型回复文本；失败返回 null
      */
-    chat(model: string, messages: ChatCompletionMessageParam[], options: RequestOptions, opts: StreamOpts): Promise<string | null>;
+    chat(model: string, messages: ChatCompletionMessageParam[], options: RequestOptions, opts: StreamOpts, params?: ChatParams): Promise<string | null>;
     /** 发起流式对话请求，返回包装后的 chunk 迭代器 */
     stream(model: string, messages: Message[], tools: ToolSchema[] | undefined, opts: StreamOpts): Promise<AsyncIterable<StreamChunk>>;
+    /**
+     * Responses 流 + 流内失败降级。
+     *
+     * 阿里云百炼（DashScope 兼容模式）等网关在模型/参数不被接受时，
+     * **先回 HTTP 200 建流，再下发 `response.failed` 事件**，SDK 不抛错，
+     * 因此 `stream()` 里的连接阶段降级判定完全不会触发 —— 用户只看到一句
+     * "Responses API 调用失败"，且永远不会走 Chat。这里在**尚未 yield 任何
+     * chunk 之前**捕获该失败并按 `_responsesFailureKind` 降级重发。
+     *
+     * 安全边界：一旦已向引擎吐出过任何 chunk（正文/思考/工具调用），绝不重放，
+     * 否则用户会看到重复输出 —— 此时原样抛出。
+     */
+    private _responsesStream;
+    /** Chat Completions 流式路径（默认或 Responses 降级后） */
+    private _chatStream;
     /** 将内部 Message 转换为 OpenAI Chat Completions 格式 */
     private _toOpenAIMessages;
     /**
@@ -325,6 +407,14 @@ declare class OpenAIProvider implements ProviderClient {
      * 由调用方按请求传入，避免并发请求互相覆盖归档日期。
      */
     private _appendResponse;
+    /**
+     * 流空闲看门狗：相邻两个 chunk 之间超过 idleMs 无数据即视为网关静默断供，
+     * 先 onIdle() 中止底层请求，再抛错结束迭代。
+     *
+     * 用 Promise.race 而不只依赖 abort：底层 HTTP 实现未必响应 signal，
+     * 此时引擎侧仍能退出等待，不会永久卡在 running 状态。
+     */
+    private _withIdleTimeout;
     /**
      * 包装 _wrapStream / _wrapResponsesStream：在流结束时补充响应日志；
      * 异常时补充错误日志。
@@ -360,6 +450,15 @@ declare class OpenAIProvider implements ProviderClient {
      *   - response.failed → 抛出错误（含响应错误信息）
      */
     private _wrapResponsesStream;
+    /**
+     * 从 `response.failed` 事件的 response 对象构造错误。
+     *
+     * 保留 `error.code` / `error.type` / `request_id`：阿里兼容模式下
+     * 典型返回是 `{code:"InvalidParameter", message:"Required parameter(s)
+     * missing or invalid", request_id:"..."}`，只有 message 时既无法判断
+     * 能否降级，也无从排查。
+     */
+    private _responsesFailure;
     /**
      * Responses API 的 usage → 标准化 TokenUsage。
      *
@@ -414,7 +513,7 @@ interface TurnEngineOpts {
     instructions: string;
     /** 生成会话名称的提示词 */
     genSessionNamePrompt?: string;
-    /** 单轮最大迭代次数（默认 150） */
+    /** 单轮最大迭代次数（默认 300） */
     maxIterations?: number;
     /**
      * 推理强度（可选）。透传给 Provider 的 LLM 请求参数
@@ -427,6 +526,10 @@ interface TurnEngineOpts {
     hook?: EngineHook;
     /** 模型上下文窗口大小（token 数）。设置后将覆盖自动检测与默认值 (128K)。 */
     contextWindow?: number;
+    /** 压缩触发阈值比例（占窗口比例，默认 0.8） */
+    thresholdPct?: number;
+    /** 压缩触发阈值绝对上限（token 数；缺省不限制，即按比例用满窗口） */
+    capTokens?: number | null;
 }
 /** 核心 Agent 循环 (对齐 Python 版 TurnEngine) */
 declare class TurnEngine {
@@ -444,11 +547,17 @@ declare class TurnEngine {
     /** 引擎生命周期钩子（由外部注入，可选） */
     private _hook;
     private _cancel;
+    private _llmAbort;
+    private _toolAbort;
     private _steering;
     compactionState: CompactionState | null;
     private _lastContextTokens;
     /** 显式配置的上下文窗口大小（token 数），未设置时为 undefined（走自动检测） */
     private _contextWindow;
+    /** 压缩触发阈值比例（默认 0.8） */
+    private _thresholdPct;
+    /** 压缩触发阈值绝对上限（null = 不限制） */
+    private _capTokens;
     private _producedFiles;
     private _turnStartTime;
     private static readonly FILE_WRITE_TOOLS;
@@ -458,7 +567,10 @@ declare class TurnEngine {
     /** 推理强度（透传给 Provider；undefined = 使用模型默认） */
     private _reasoningEffort;
     constructor(opts: TurnEngineOpts);
-    /** 外部中断：置位取消标记，引擎会在安全点停止 */
+    /**
+     * 外部中断：置位取消标记 + 掐断在飞的 LLM 请求 + 中止正在执行的工具，
+     * 引擎随后按中断收尾
+     */
     requestInterrupt(): void;
     /** 设置审批回调 */
     setApprover(approver: Approver): void;
@@ -485,6 +597,13 @@ declare class TurnEngine {
     genSessionName(): Promise<string | null>;
     /** 从持久化消息历史中重建未完成的 tool_calls */
     private _unansweredTrailingToolCalls;
+    /**
+     * 中断收尾：保留已流式输出的内容、记一条 interrupted 提示，
+     * 产出 INTERRUPTED + TURN_END 事件并结束本轮。
+     *
+     * 两处调用：流式结束后发现取消标记、以及流被 abort 中断抛错时。
+     */
+    private _finishInterrupted;
     /**
      * 核心迭代循环
      *
@@ -501,6 +620,8 @@ declare class TurnEngine {
      *      PERMISSION_REQUIRED 事件并调用 approver；被拒/未知工具
      *      直接产出错误结果，不进入执行。
      *   B. 分类执行：低风险工具并发执行（Promise.all），其余串行；
+     *      交互类工具（ask_user / propose_plan / request_directory）虽然
+     *      风险级别为 low，但需要用户逐条作答，一律串行；
      *      每个结果都转成 tool 消息追加到历史并产出 TOOL_FINISHED。
      */
     private _handleToolCalls;
@@ -528,8 +649,14 @@ declare class TurnEngine {
      * 消息即停止；只有末尾全部是 error 通知才返回 true。
      */
     private _tailIsRetriableError;
+    /** 当前上下文 token 用量：优先采信 API 返回的精确数量，否则用 chars/4 估算 */
+    private _compactionTokens;
     /** 检查是否需要压缩（每轮 LLM 调用前） */
     private _compactionDue;
+    /** 组装压缩开始时的用量信息（供 hook 与 COMPACTING 事件携带） */
+    private _compactionStartInfo;
+    /** 组装压缩结果信息（供 hook 与 COMPACTED 事件携带） */
+    private _compactionDoneInfo;
     /** 获取当前模型的上下文窗口大小（token 数）。优先级：显式配置 > 自动检测 > 默认值 128K。 */
     private _getContextWindow;
     /** 执行压缩策略（对齐 Python 版 _compact_now） */
@@ -559,7 +686,7 @@ declare class TurnEngine {
  * 构建 Explorer 子引擎 (对齐 Python 版 build_explorer_engine)
  *
  * 只注册只读工具，使用 Plan 模式权限引擎（硬阻断所有写入），
- * 迭代上限为 10 次（研究任务通常不需要很多轮）。
+ * 迭代上限默认 30 次（环境变量 EXPLORE_MAX_ITERATIONS 可覆盖）。
  *
  * 可选 readonlyRegistrars：外部可注入"只读工具注册器"（例如沙箱远程工具），
  * 用于把 explore 子代理的执行目标从宿主机工作区切换到远程沙箱。
@@ -570,6 +697,11 @@ declare function buildExplorerEngine(opts: {
     provider: ProviderClient;
     model: string;
     readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /**
+     * 子引擎生命周期钩子（可选）：注入后子代理的执行过程（工具活动、终态）
+     * 会回调给调用方渲染（如 CLI 的 SubagentHook）；不传则与旧版一致（静默）。
+     */
+    hook?: EngineHook;
 }): TurnEngine;
 /**
  * 创建 explore 工具函数
@@ -582,6 +714,13 @@ declare function makeExploreTool(opts: {
     provider: ProviderClient;
     model: string;
     readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /**
+     * 子引擎钩子工厂（可选）：每次 explore 调用生成一个新实例。
+     *
+     * 用工厂而非共享实例，是因为低风险工具会被并发执行（同一条回复里的多个
+     * explore 会同时运行），共享同一个渲染器会互相串状态、输出交错难辨。
+     */
+    hookFactory?: () => EngineHook;
 }): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /** 注册 explore 工具（低风险，无需审批） */
 declare function registerExploreTool(registry: ToolRegistry, opts: {
@@ -589,6 +728,8 @@ declare function registerExploreTool(registry: ToolRegistry, opts: {
     provider: ProviderClient;
     model: string;
     readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /** 子引擎钩子工厂（可选）：见 makeExploreTool */
+    hookFactory?: () => EngineHook;
 }): void;
 
-export { ApprovalOutcome as A, 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, EventType as a, type EngineErrorInfo as b, type Approver as c, PermissionEngine as d, type PermissionRequest as e, type TurnEngineOpts as f, buildExplorerEngine as g, 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, 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 };

package/dist/{explore-Pmhyk4gv.d.ts → explore-Dj1j_GyN.d.cts}

@@ -1,4 +1,4 @@
-import { a as TokenUsage, b as ToolMetadata, M as Message, c as ToolSchema, R as ReasoningEffort, S as StreamChunk, T as ToolRegistry } from './ToolRegistry-BmvPxgMr.js';
+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 { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 import { RequestOptions } from 'openai/core.mjs';
 
@@ -48,7 +48,11 @@ declare enum EventType {
     /** LLM 请求发出 — 携带 reqId 用于关联审计日志与后续 delta/error 事件 */
     LLM_REQUEST = "llm_request",
     /** 模型通过 ask_user 工具向用户提问 */
-    ASK_USER_QUESTION = "ask_user_question"
+    ASK_USER_QUESTION = "ask_user_question",
+    /** 会话名已（自动/手动）更新 — data: { name, source } */
+    SESSION_NAMED = "session_named",
+    /** 瞬时网络错误自动重试 — data: { attempt, max, reason } */
+    LLM_RETRY = "llm_retry"
 }
 /** WebSocket 事件 (CLI 模式下通过 async generator 模拟) */
 interface WsEvent {
@@ -93,6 +97,45 @@ interface EngineErrorInfo {
     /** 错误堆栈（异常对象存在时提供，可能缺失） */
     stack?: string;
 }
+/**
+ * 上下文压缩触发原因
+ *
+ * - `threshold`：达到触发阈值的预防性压缩
+ * - `overflow`：API 报上下文溢出后的强制压缩
+ */
+type CompactionTrigger = "threshold" | "overflow";
+/** 压缩开始时的上下文用量（供 hook / 事件携带，便于展示更多信息） */
+interface CompactionStartInfo {
+    /** 触发原因 */
+    trigger: CompactionTrigger;
+    /** 触发时的上下文 token 用量（优先 API 精确值，否则为估算） */
+    tokens: number;
+    /** tokens 是否为 chars/4 估算值 */
+    estimated: boolean;
+    /** 当前模型的上下文窗口（token 数） */
+    contextWindow: number;
+    /** 触发阈值占窗口的比例（0-1） */
+    thresholdPct: number;
+    /** 触发阈值（token 数，已计入 capTokens 截断） */
+    thresholdTokens: number;
+    /** 压缩前发送给模型的消息条数 */
+    outboundMessages: number;
+}
+/** 压缩结果信息 */
+interface CompactionDoneInfo {
+    /** summarized=LLM 摘要，trimmed=裁剪降级 */
+    method: "summarized" | "trimmed";
+    /** 压缩前发送给模型的消息条数 */
+    messagesBefore: number;
+    /** 压缩后发送给模型的消息条数 */
+    messagesAfter: number;
+    /** 摘要所用模型（method=summarized 时提供） */
+    model?: string;
+    /** 摘要保留的早期用户消息数 */
+    keptUserMessages?: number;
+    /** 摘要丢弃的早期用户消息数 */
+    droppedUserMessages?: number;
+}
 /**
  * 引擎生命周期钩子
  *
@@ -119,11 +162,13 @@ interface EngineHook {
     onPermissionRequired?(name: string, reason: string): void;
     /** 迭代结束 */
     onIterationEnd?(iteration: number): void;
-    /** 上下文压缩 */
-    onCompacting?(): void;
-    onCompacted?(text: string): void;
+    /** 上下文压缩：开始（info 含触发原因与用量）/ 完成（info 含压缩方式与前后条数） */
+    onCompacting?(info?: CompactionStartInfo): void;
+    onCompacted?(text: string, info?: CompactionDoneInfo): void;
     /** 异常 */
     onError?(error: string, errorType: string, info?: EngineErrorInfo): void;
+    /** 瞬时网络错误自动重试（attempt 从 1 开始） */
+    onRetry?(attempt: number, max: number, reason: string): void;
     onInterrupted?(iterations: number): void;
     /** 通用兜底：所有未匹配到具体回调的事件都会走这里 */
     onEvent?(type: EventType, data: Record<string, unknown>): void;
@@ -187,7 +232,7 @@ declare class PermissionEngine {
     evaluate(toolName: string, args: Record<string, unknown>, metadata?: ToolMetadata): Decision;
     /** 将工具加入会话白名单 */
     allowToolForSession(toolName: string): void;
-    /** 将命令加入会话白名单 */
+    /** 将命令加入会话白名单（按可执行程序名记录，同类命令后续直接放行） */
     allowCommandForSession(command: string): void;
     /**
      * 检查路径是否在可写根目录下
@@ -216,6 +261,19 @@ interface StreamOpts {
      * DeepSeek 不支持级别控制，自动跳过。
      */
     reasoningEffort?: ReasoningEffort;
+    /**
+     * 中止信号（可选）。引擎按下「停止」时 abort，用于掐断在飞的流式请求 ——
+     * 仅置引擎内部的取消标志位无法结束已静默挂死的网络流。
+     */
+    signal?: AbortSignal;
+    /**
+     * 内部字段：流空闲看门狗（由 `stream()` 注入，各流路径复用）。
+     * 引擎侧无需感知，请勿在 `stream()` 之外构造。
+     */
+    idle?: {
+        ms: number;
+        onIdle: () => void;
+    };
 }
 /** LLM Provider 抽象接口 */
 interface ProviderClient {
@@ -229,7 +287,12 @@ interface ProviderClient {
      * @returns 流式 chunk 的异步可迭代对象
      */
     stream(model: string, messages: Message[], tools: ToolSchema[], opts: StreamOpts): Promise<AsyncIterable<StreamChunk>>;
-    chat(model: string, messages: any[], options: RequestOptions, opts: StreamOpts): Promise<string | null>;
+    chat(model: string, messages: any[], options: RequestOptions, opts: StreamOpts, params?: ChatParams): Promise<string | null>;
+}
+/** chat 请求的附加参数（用于会话命名等轻量请求，限制输出长度） */
+interface ChatParams {
+    /** 最大输出 token 数（Responses → max_output_tokens；Chat → max_tokens / max_completion_tokens） */
+    maxTokens?: number;
 }
 /** OpenAI-compatible Provider（Responses API 优先，失败降级 Chat Completions） */
 declare class OpenAIProvider implements ProviderClient {
@@ -256,15 +319,19 @@ declare class OpenAIProvider implements ProviderClient {
      */
     private _resolveMode;
     /**
-     * 判断 Responses 调用失败是否属于"端点不支持"类错误（可安全降级）。
+     * Responses 失败的分类（决定「能不能改走 Chat Completions」以及要不要缓存降级）。
      *
-     * 仅对发生在连接阶段（首字节之前）的错误调用本方法：
-     *   - 404 / 405：端点不存在或方法不允许 → 一律视为不支持
-     *   - 400 / 403：错误信息含 not supported / unsupported /
-     *     unknown endpoint / not implemented 等特征才视为不支持
-     *   - 其它错误（鉴权 401、网络超时等）不降级，原样抛出
+     * @param connectionStage 失败是否发生在连接阶段（首字节之前）。
+     *   流内失败（已建立 SSE 后才收到 response.failed）只在**尚未 yield 任何
+     *   chunk** 时才允许重试，否则会向用户重复输出前半段内容。
+     *
+     * 返回值：
+     *   - "endpoint"：该端点/模型不支持 Responses → 降级 Chat 并写入缓存
+     *   - "param"：参数或模型不被接受（如阿里兼容模式的 InvalidParameter）
+     *     → 本次改走 Chat（Chat 的参数集不同，可能可用），但不写缓存
+     *   - null：鉴权(401)/限流(429)/服务端(5xx)/网络类 → 不降级，原样抛出
      */
-    private _isResponsesUnsupported;
+    private _responsesFailureKind;
     /** 识别 DeepSeek 供应商（模型名或 baseURL 含 "deepseek"） */
     private _isDeepSeek;
     /**
@@ -279,9 +346,24 @@ declare class OpenAIProvider implements ProviderClient {
      * @param opts     reqId 等审计信息
      * @returns 模型回复文本；失败返回 null
      */
-    chat(model: string, messages: ChatCompletionMessageParam[], options: RequestOptions, opts: StreamOpts): Promise<string | null>;
+    chat(model: string, messages: ChatCompletionMessageParam[], options: RequestOptions, opts: StreamOpts, params?: ChatParams): Promise<string | null>;
     /** 发起流式对话请求，返回包装后的 chunk 迭代器 */
     stream(model: string, messages: Message[], tools: ToolSchema[] | undefined, opts: StreamOpts): Promise<AsyncIterable<StreamChunk>>;
+    /**
+     * Responses 流 + 流内失败降级。
+     *
+     * 阿里云百炼（DashScope 兼容模式）等网关在模型/参数不被接受时，
+     * **先回 HTTP 200 建流，再下发 `response.failed` 事件**，SDK 不抛错，
+     * 因此 `stream()` 里的连接阶段降级判定完全不会触发 —— 用户只看到一句
+     * "Responses API 调用失败"，且永远不会走 Chat。这里在**尚未 yield 任何
+     * chunk 之前**捕获该失败并按 `_responsesFailureKind` 降级重发。
+     *
+     * 安全边界：一旦已向引擎吐出过任何 chunk（正文/思考/工具调用），绝不重放，
+     * 否则用户会看到重复输出 —— 此时原样抛出。
+     */
+    private _responsesStream;
+    /** Chat Completions 流式路径（默认或 Responses 降级后） */
+    private _chatStream;
     /** 将内部 Message 转换为 OpenAI Chat Completions 格式 */
     private _toOpenAIMessages;
     /**
@@ -325,6 +407,14 @@ declare class OpenAIProvider implements ProviderClient {
      * 由调用方按请求传入，避免并发请求互相覆盖归档日期。
      */
     private _appendResponse;
+    /**
+     * 流空闲看门狗：相邻两个 chunk 之间超过 idleMs 无数据即视为网关静默断供，
+     * 先 onIdle() 中止底层请求，再抛错结束迭代。
+     *
+     * 用 Promise.race 而不只依赖 abort：底层 HTTP 实现未必响应 signal，
+     * 此时引擎侧仍能退出等待，不会永久卡在 running 状态。
+     */
+    private _withIdleTimeout;
     /**
      * 包装 _wrapStream / _wrapResponsesStream：在流结束时补充响应日志；
      * 异常时补充错误日志。
@@ -360,6 +450,15 @@ declare class OpenAIProvider implements ProviderClient {
      *   - response.failed → 抛出错误（含响应错误信息）
      */
     private _wrapResponsesStream;
+    /**
+     * 从 `response.failed` 事件的 response 对象构造错误。
+     *
+     * 保留 `error.code` / `error.type` / `request_id`：阿里兼容模式下
+     * 典型返回是 `{code:"InvalidParameter", message:"Required parameter(s)
+     * missing or invalid", request_id:"..."}`，只有 message 时既无法判断
+     * 能否降级，也无从排查。
+     */
+    private _responsesFailure;
     /**
      * Responses API 的 usage → 标准化 TokenUsage。
      *
@@ -414,7 +513,7 @@ interface TurnEngineOpts {
     instructions: string;
     /** 生成会话名称的提示词 */
     genSessionNamePrompt?: string;
-    /** 单轮最大迭代次数（默认 150） */
+    /** 单轮最大迭代次数（默认 300） */
     maxIterations?: number;
     /**
      * 推理强度（可选）。透传给 Provider 的 LLM 请求参数
@@ -427,6 +526,10 @@ interface TurnEngineOpts {
     hook?: EngineHook;
     /** 模型上下文窗口大小（token 数）。设置后将覆盖自动检测与默认值 (128K)。 */
     contextWindow?: number;
+    /** 压缩触发阈值比例（占窗口比例，默认 0.8） */
+    thresholdPct?: number;
+    /** 压缩触发阈值绝对上限（token 数；缺省不限制，即按比例用满窗口） */
+    capTokens?: number | null;
 }
 /** 核心 Agent 循环 (对齐 Python 版 TurnEngine) */
 declare class TurnEngine {
@@ -444,11 +547,17 @@ declare class TurnEngine {
     /** 引擎生命周期钩子（由外部注入，可选） */
     private _hook;
     private _cancel;
+    private _llmAbort;
+    private _toolAbort;
     private _steering;
     compactionState: CompactionState | null;
     private _lastContextTokens;
     /** 显式配置的上下文窗口大小（token 数），未设置时为 undefined（走自动检测） */
     private _contextWindow;
+    /** 压缩触发阈值比例（默认 0.8） */
+    private _thresholdPct;
+    /** 压缩触发阈值绝对上限（null = 不限制） */
+    private _capTokens;
     private _producedFiles;
     private _turnStartTime;
     private static readonly FILE_WRITE_TOOLS;
@@ -458,7 +567,10 @@ declare class TurnEngine {
     /** 推理强度（透传给 Provider；undefined = 使用模型默认） */
     private _reasoningEffort;
     constructor(opts: TurnEngineOpts);
-    /** 外部中断：置位取消标记，引擎会在安全点停止 */
+    /**
+     * 外部中断：置位取消标记 + 掐断在飞的 LLM 请求 + 中止正在执行的工具，
+     * 引擎随后按中断收尾
+     */
     requestInterrupt(): void;
     /** 设置审批回调 */
     setApprover(approver: Approver): void;
@@ -485,6 +597,13 @@ declare class TurnEngine {
     genSessionName(): Promise<string | null>;
     /** 从持久化消息历史中重建未完成的 tool_calls */
     private _unansweredTrailingToolCalls;
+    /**
+     * 中断收尾：保留已流式输出的内容、记一条 interrupted 提示，
+     * 产出 INTERRUPTED + TURN_END 事件并结束本轮。
+     *
+     * 两处调用：流式结束后发现取消标记、以及流被 abort 中断抛错时。
+     */
+    private _finishInterrupted;
     /**
      * 核心迭代循环
      *
@@ -501,6 +620,8 @@ declare class TurnEngine {
      *      PERMISSION_REQUIRED 事件并调用 approver；被拒/未知工具
      *      直接产出错误结果，不进入执行。
      *   B. 分类执行：低风险工具并发执行（Promise.all），其余串行；
+     *      交互类工具（ask_user / propose_plan / request_directory）虽然
+     *      风险级别为 low，但需要用户逐条作答，一律串行；
      *      每个结果都转成 tool 消息追加到历史并产出 TOOL_FINISHED。
      */
     private _handleToolCalls;
@@ -528,8 +649,14 @@ declare class TurnEngine {
      * 消息即停止；只有末尾全部是 error 通知才返回 true。
      */
     private _tailIsRetriableError;
+    /** 当前上下文 token 用量：优先采信 API 返回的精确数量，否则用 chars/4 估算 */
+    private _compactionTokens;
     /** 检查是否需要压缩（每轮 LLM 调用前） */
     private _compactionDue;
+    /** 组装压缩开始时的用量信息（供 hook 与 COMPACTING 事件携带） */
+    private _compactionStartInfo;
+    /** 组装压缩结果信息（供 hook 与 COMPACTED 事件携带） */
+    private _compactionDoneInfo;
     /** 获取当前模型的上下文窗口大小（token 数）。优先级：显式配置 > 自动检测 > 默认值 128K。 */
     private _getContextWindow;
     /** 执行压缩策略（对齐 Python 版 _compact_now） */
@@ -559,7 +686,7 @@ declare class TurnEngine {
  * 构建 Explorer 子引擎 (对齐 Python 版 build_explorer_engine)
  *
  * 只注册只读工具，使用 Plan 模式权限引擎（硬阻断所有写入），
- * 迭代上限为 10 次（研究任务通常不需要很多轮）。
+ * 迭代上限默认 30 次（环境变量 EXPLORE_MAX_ITERATIONS 可覆盖）。
  *
  * 可选 readonlyRegistrars：外部可注入"只读工具注册器"（例如沙箱远程工具），
  * 用于把 explore 子代理的执行目标从宿主机工作区切换到远程沙箱。
@@ -570,6 +697,11 @@ declare function buildExplorerEngine(opts: {
     provider: ProviderClient;
     model: string;
     readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /**
+     * 子引擎生命周期钩子（可选）：注入后子代理的执行过程（工具活动、终态）
+     * 会回调给调用方渲染（如 CLI 的 SubagentHook）；不传则与旧版一致（静默）。
+     */
+    hook?: EngineHook;
 }): TurnEngine;
 /**
  * 创建 explore 工具函数
@@ -582,6 +714,13 @@ declare function makeExploreTool(opts: {
     provider: ProviderClient;
     model: string;
     readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /**
+     * 子引擎钩子工厂（可选）：每次 explore 调用生成一个新实例。
+     *
+     * 用工厂而非共享实例，是因为低风险工具会被并发执行（同一条回复里的多个
+     * explore 会同时运行），共享同一个渲染器会互相串状态、输出交错难辨。
+     */
+    hookFactory?: () => EngineHook;
 }): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /** 注册 explore 工具（低风险，无需审批） */
 declare function registerExploreTool(registry: ToolRegistry, opts: {
@@ -589,6 +728,8 @@ declare function registerExploreTool(registry: ToolRegistry, opts: {
     provider: ProviderClient;
     model: string;
     readonlyRegistrars?: (registry: ToolRegistry) => void;
+    /** 子引擎钩子工厂（可选）：见 makeExploreTool */
+    hookFactory?: () => EngineHook;
 }): void;
 
-export { ApprovalOutcome as A, 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, EventType as a, type EngineErrorInfo as b, type Approver as c, PermissionEngine as d, type PermissionRequest as e, type TurnEngineOpts as f, buildExplorerEngine as g, 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, 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 };