@zqagent/core 0.2.5 → 0.2.7

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

@@ -266,6 +266,11 @@ interface StreamOpts {
      * 仅置引擎内部的取消标志位无法结束已静默挂死的网络流。
      */
     signal?: AbortSignal;
+    /**
+     * 最大输出 token 数（可选）。用于摘要器等轻量请求限制输出长度；
+     * Responses → max_output_tokens，Chat → max_tokens / max_completion_tokens。
+     */
+    maxTokens?: number;
     /**
      * 内部字段：流空闲看门狗（由 `stream()` 注入，各流路径复用）。
      * 引擎侧无需感知，请勿在 `stream()` 之外构造。
@@ -528,8 +533,19 @@ interface TurnEngineOpts {
     contextWindow?: number;
     /** 压缩触发阈值比例（占窗口比例，默认 0.8） */
     thresholdPct?: number;
+    /**
+     * 软阈值比例（占窗口比例）：达到它只淘汰旧工具结果，不调用 LLM。
+     * 缺省为硬阈值的 75%（即默认 60% 窗口）。
+     */
+    softThresholdPct?: number;
     /** 压缩触发阈值绝对上限（token 数；缺省不限制，即按比例用满窗口） */
     capTokens?: number | null;
+    /**
+     * 超预算工具结果的落盘目录（可选）。
+     *
+     * 多租户 Server 应指向租户/会话自己的目录，避免不同租户的内容混在一个目录里。
+     */
+    toolResultDir?: string;
 }
 /** 核心 Agent 循环 (对齐 Python 版 TurnEngine) */
 declare class TurnEngine {
@@ -552,12 +568,22 @@ declare class TurnEngine {
     private _steering;
     compactionState: CompactionState | null;
     private _lastContextTokens;
+    /** 压缩无进展时的消息条数快照；-1 表示无冷却 */
+    private _compactStalledAt;
     /** 显式配置的上下文窗口大小（token 数），未设置时为 undefined（走自动检测） */
     private _contextWindow;
     /** 压缩触发阈值比例（默认 0.8） */
     private _thresholdPct;
+    /** 软阈值比例（undefined = 取硬阈值的 75%） */
+    private _softThresholdPct;
+    /** 是否启用软阈值淘汰（COMPACTION_ELIDE=0 可关闭） */
+    private _elisionEnabled;
+    /** 是否启用重复读取去重（COMPACTION_DEDUP=0 可关闭） */
+    private _dedupEnabled;
     /** 压缩触发阈值绝对上限（null = 不限制） */
     private _capTokens;
+    /** 超预算工具结果的落盘目录（undefined = 使用默认状态目录） */
+    private _toolResultDir;
     private _producedFiles;
     private _turnStartTime;
     private static readonly FILE_WRITE_TOOLS;
@@ -631,8 +657,14 @@ declare class TurnEngine {
      * 过滤 notice 消息；tool 消息只保留必要字段；
      * 其余消息剥离 display-only sidecar 字段（source/_display/ts/
      * reasoning/usage），避免污染模型上下文。
+     *
+     * 达到软阈值时先淘汰旧工具结果（零 LLM 成本），再产出最终视图。
      */
     private _outboundMessages;
+    /** 过滤 notice + 剥离 display-only 字段，得到最终发送视图 */
+    private _finalizeOutbound;
+    /** 软阈值（token 数）：达到它只淘汰旧工具结果 */
+    private _softTriggerTokens;
     /** 通知消息：仅用于日志/展示，不发给模型 */
     private _appendNotice;
     /**
@@ -649,8 +681,18 @@ declare class TurnEngine {
      * 消息即停止；只有末尾全部是 error 通知才返回 true。
      */
     private _tailIsRetriableError;
-    /** 当前上下文 token 用量：优先采信 API 返回的精确数量，否则用 chars/4 估算 */
+    /**
+     * 当前上下文 token 用量。
+     *
+     * API 返回的 `usage.input` 是精确值，但反映的是「上一次请求」——工具结果
+     * 与淘汰/压缩都会让它过时。因此同时估算当前 outbound 视图，取较大者：
+     * 宁可早一点压缩，也不要漏判导致溢出。
+     */
     private _compactionTokens;
+    /** 压缩后重置精确计数：后续按估算值判断 */
+    private _resetContextTokens;
+    /** 当前 outbound 视图的估算 token 数 */
+    private _estimateContextTokens;
     /** 检查是否需要压缩（每轮 LLM 调用前） */
     private _compactionDue;
     /** 组装压缩开始时的用量信息（供 hook 与 COMPACTING 事件携带） */
@@ -702,6 +744,8 @@ declare function buildExplorerEngine(opts: {
      * 会回调给调用方渲染（如 CLI 的 SubagentHook）；不传则与旧版一致（静默）。
      */
     hook?: EngineHook;
+    /** 超预算工具结果的落盘目录（与主引擎共用，保持租户隔离） */
+    toolResultDir?: string;
 }): TurnEngine;
 /**
  * 创建 explore 工具函数
@@ -721,6 +765,8 @@ declare function makeExploreTool(opts: {
      * explore 会同时运行），共享同一个渲染器会互相串状态、输出交错难辨。
      */
     hookFactory?: () => EngineHook;
+    /** 超预算工具结果的落盘目录（透传给子引擎） */
+    toolResultDir?: string;
 }): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /** 注册 explore 工具（低风险，无需审批） */
 declare function registerExploreTool(registry: ToolRegistry, opts: {
@@ -730,6 +776,8 @@ declare function registerExploreTool(registry: ToolRegistry, opts: {
     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 };

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

@@ -266,6 +266,11 @@ interface StreamOpts {
      * 仅置引擎内部的取消标志位无法结束已静默挂死的网络流。
      */
     signal?: AbortSignal;
+    /**
+     * 最大输出 token 数（可选）。用于摘要器等轻量请求限制输出长度；
+     * Responses → max_output_tokens，Chat → max_tokens / max_completion_tokens。
+     */
+    maxTokens?: number;
     /**
      * 内部字段：流空闲看门狗（由 `stream()` 注入，各流路径复用）。
      * 引擎侧无需感知，请勿在 `stream()` 之外构造。
@@ -528,8 +533,19 @@ interface TurnEngineOpts {
     contextWindow?: number;
     /** 压缩触发阈值比例（占窗口比例，默认 0.8） */
     thresholdPct?: number;
+    /**
+     * 软阈值比例（占窗口比例）：达到它只淘汰旧工具结果，不调用 LLM。
+     * 缺省为硬阈值的 75%（即默认 60% 窗口）。
+     */
+    softThresholdPct?: number;
     /** 压缩触发阈值绝对上限（token 数；缺省不限制，即按比例用满窗口） */
     capTokens?: number | null;
+    /**
+     * 超预算工具结果的落盘目录（可选）。
+     *
+     * 多租户 Server 应指向租户/会话自己的目录，避免不同租户的内容混在一个目录里。
+     */
+    toolResultDir?: string;
 }
 /** 核心 Agent 循环 (对齐 Python 版 TurnEngine) */
 declare class TurnEngine {
@@ -552,12 +568,22 @@ declare class TurnEngine {
     private _steering;
     compactionState: CompactionState | null;
     private _lastContextTokens;
+    /** 压缩无进展时的消息条数快照；-1 表示无冷却 */
+    private _compactStalledAt;
     /** 显式配置的上下文窗口大小（token 数），未设置时为 undefined（走自动检测） */
     private _contextWindow;
     /** 压缩触发阈值比例（默认 0.8） */
     private _thresholdPct;
+    /** 软阈值比例（undefined = 取硬阈值的 75%） */
+    private _softThresholdPct;
+    /** 是否启用软阈值淘汰（COMPACTION_ELIDE=0 可关闭） */
+    private _elisionEnabled;
+    /** 是否启用重复读取去重（COMPACTION_DEDUP=0 可关闭） */
+    private _dedupEnabled;
     /** 压缩触发阈值绝对上限（null = 不限制） */
     private _capTokens;
+    /** 超预算工具结果的落盘目录（undefined = 使用默认状态目录） */
+    private _toolResultDir;
     private _producedFiles;
     private _turnStartTime;
     private static readonly FILE_WRITE_TOOLS;
@@ -631,8 +657,14 @@ declare class TurnEngine {
      * 过滤 notice 消息；tool 消息只保留必要字段；
      * 其余消息剥离 display-only sidecar 字段（source/_display/ts/
      * reasoning/usage），避免污染模型上下文。
+     *
+     * 达到软阈值时先淘汰旧工具结果（零 LLM 成本），再产出最终视图。
      */
     private _outboundMessages;
+    /** 过滤 notice + 剥离 display-only 字段，得到最终发送视图 */
+    private _finalizeOutbound;
+    /** 软阈值（token 数）：达到它只淘汰旧工具结果 */
+    private _softTriggerTokens;
     /** 通知消息：仅用于日志/展示，不发给模型 */
     private _appendNotice;
     /**
@@ -649,8 +681,18 @@ declare class TurnEngine {
      * 消息即停止；只有末尾全部是 error 通知才返回 true。
      */
     private _tailIsRetriableError;
-    /** 当前上下文 token 用量：优先采信 API 返回的精确数量，否则用 chars/4 估算 */
+    /**
+     * 当前上下文 token 用量。
+     *
+     * API 返回的 `usage.input` 是精确值，但反映的是「上一次请求」——工具结果
+     * 与淘汰/压缩都会让它过时。因此同时估算当前 outbound 视图，取较大者：
+     * 宁可早一点压缩，也不要漏判导致溢出。
+     */
     private _compactionTokens;
+    /** 压缩后重置精确计数：后续按估算值判断 */
+    private _resetContextTokens;
+    /** 当前 outbound 视图的估算 token 数 */
+    private _estimateContextTokens;
     /** 检查是否需要压缩（每轮 LLM 调用前） */
     private _compactionDue;
     /** 组装压缩开始时的用量信息（供 hook 与 COMPACTING 事件携带） */
@@ -702,6 +744,8 @@ declare function buildExplorerEngine(opts: {
      * 会回调给调用方渲染（如 CLI 的 SubagentHook）；不传则与旧版一致（静默）。
      */
     hook?: EngineHook;
+    /** 超预算工具结果的落盘目录（与主引擎共用，保持租户隔离） */
+    toolResultDir?: string;
 }): TurnEngine;
 /**
  * 创建 explore 工具函数
@@ -721,6 +765,8 @@ declare function makeExploreTool(opts: {
      * explore 会同时运行），共享同一个渲染器会互相串状态、输出交错难辨。
      */
     hookFactory?: () => EngineHook;
+    /** 超预算工具结果的落盘目录（透传给子引擎） */
+    toolResultDir?: string;
 }): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /** 注册 explore 工具（低风险，无需审批） */
 declare function registerExploreTool(registry: ToolRegistry, opts: {
@@ -730,6 +776,8 @@ declare function registerExploreTool(registry: ToolRegistry, opts: {
     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 };