@eddyskywalker/dsh-chatgpt-subscription 0.44.0 → 0.46.0

package/lib/types/host/cache-warmup/install.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 「缓存预热」宿主集成的挂载点。
+ *
+ * 这个文件把核心（结果投影、预算、引用存储、指标）接到宿主上，挂四样东西：
+ *
+ * 1. `tools/post-execute` 上的**新结果投影**：Kimi 线路的 `run_code` 结果交给
+ *    `projectToolResult`，能可靠结构化提取的大结果被换成带 `ref://` 引用的预览；
+ * 2. `cache_warmup_result` 工具（`result-tool.ts`），预览的唯一精确补读入口；
+ * 3. 一段**静态**系统提示词引导（见 `CACHE_WARMUP_GUIDANCE`）；
+ * 4. 结构化指标日志（`logging.ts`）。
+ *
+ * ## 只处理新结果
+ *
+ * post-execute 是每条工具结果各触发一次的**当下**事件：这里改的只是这次调用即将
+ * 写进历史的 content。历史里已经落下的结果不会被回改，`promptCacheKey`、replay、
+ * mapper、动态工具 in-history 机制一概不碰——它们读的是同一个 content，改历史
+ * 等于让同一个会话两次重放得到两段不同的字节。
+ *
+ * 因此开关的语义是**只影响之后的新结果**：关掉之后，已有的 preview/refId 继续
+ * 存在、继续可读（引用过期与否归存储管），只是不再产生新的。
+ *
+ * ## 可选服务一律走 `ctx.get()`
+ *
+ * `tools` 与 `systemPrompt` 都不在本插件的 `inject` 里（前者由宿主另装，后者
+ * 出现与否随 harness 代次）。Cordis 对没写进 `inject` 的服务直接读属性会抛
+ * `cannot get property "..." without inject`，一次就够把整个插件打成 degraded。
+ * 所以这里全部是**调用时**的 `get()`，缺席就安静降级：没有 tools 就不注册工具，
+ * 没有 systemPrompt 就不挂引导，插件照样挂得上。
+ *
+ * @module dsh-chatgpt-subscription/host/cache-warmup/install
+ */
+import { type CacheWarmupDurableHint, type ResultReferenceStore } from './index.ts';
+import { type CacheWarmupLogger } from './logging.ts';
+import type { CacheWarmupSettings } from './settings.ts';
+/**
+ * 本模块服务的线路。
+ *
+ * 结果投影的正确性依赖这条线路的缓存语义（内容前缀命中），别的线路上把结果换成
+ * 预览只有坏处没有好处，所以这里写死一个 provider 名而不是做成开关。
+ */
+export declare const CACHE_WARMUP_PROVIDER = "kimi-code";
+/**
+ * 默认被投影的主工具名（保留导出供向后兼容）。
+ */
+export declare const CACHE_WARMUP_SOURCE_TOOL = "run_code";
+/**
+ * 允许进入结果投影的工具集合。
+ *
+ * 除了 PTC 的 `run_code`，宿主的独立 Shell 与后台任务输出工具（`win_bash`、
+ * `bash`、`pwsh`、`job_output`）同样经常吐出整屏测试/构建日志。源码读取/编辑类
+ * 工具（`read`、`edit`、`grep`、`glob`、CodeGraph 等）不在此列，保持 100% 原样。
+ */
+export declare const CACHE_WARMUP_SOURCE_TOOLS: ReadonlySet<string>;
+/** 提示词分节名，全局唯一（重复注册会抛错）。 */
+export declare const CACHE_WARMUP_SECTION_NAME = "plugin:cache-warmup";
+/**
+ * 引导词在提示词里的排序位。
+ *
+ * 插件族占用的区间在部署人设之后、SDK 的 `PLAN_POLICY`(500) 之前；进展更新占了
+ * 220，这里取 225，紧挨着它但不并列。
+ */
+export declare const CACHE_WARMUP_SECTION_ORDER = 225;
+/**
+ * 一段**恒定**的引导词：告诉模型预览是什么、怎么补读。
+ *
+ * 文本与开关无关，这是刻意的——系统提示是缓存前缀的第一段，会话中途改一个字就
+ * 让整段前缀失效、整段重新计费。开关的语义只交给 post-execute 与工具。
+ */
+export declare const CACHE_WARMUP_GUIDANCE: string;
+/**
+ * 静态引导词的文本提供者。
+ * @returns 一个永远返回同一段文本的函数（系统提示的稳定前缀）。
+ */
+export declare function cacheWarmupSectionText(): () => string;
+/** 一次工具调用所属的线路。 */
+export interface CacheWarmupRoute {
+    /** 当前会话被路由到的 provider id。 */
+    readonly provider?: string;
+    /** 当前会话标识；引用归属、预算与命中率都按它记账。 */
+    readonly sessionId?: string;
+}
+/**
+ * 读一次工具调用所属的线路。
+ *
+ * provider 先问会话的 request header（那是本轮请求真正走的那条线），再退回
+ * agent 自己的 options。两处都没有就返回空对象——调用方据此放手，而不是猜一个。
+ * @param agent - 事件里的调用方 agent。
+ * @returns 线路信息；读不到的字段省略。
+ */
+export declare function cacheWarmupRouteOf(agent: unknown): CacheWarmupRoute;
+/** 挂载选项。 */
+export interface CacheWarmupOptions {
+    /**
+     * 读取当前设置。
+     *
+     * 必须是**函数**：loader 把 volatile 字段换成活引用，设置保存时就地写新值而不
+     * 重挂插件行；apply 时求值一次存下来的写法会让开关在会话中途失效。
+     */
+    settings: () => CacheWarmupSettings;
+    /**
+     * 结果引用存储。
+     *
+     * 缺省时按需构造一个 `FileResultReferenceStore()`（核心的 `CACHE_WARMUP_DEFAULTS`
+     * 提供其余默认值）；注入一个工厂是为了让测试与别的部署换掉存储，而不必改这里。
+     */
+    store?: () => ResultReferenceStore | undefined;
+    /**
+     * 进程重启后尚无内存报告时的持久化预热状态回退读取器（可选）。
+     */
+    durableHint?: (sessionId: string) => CacheWarmupDurableHint | undefined;
+}
+/** 本模块读得到的宿主上下文（Cordis Context 结构上满足；测试可用假对象）。 */
+export interface CacheWarmupContext {
+    /** Cordis 的副作用登记：回调返回的 disposer 会随插件卸载执行。 */
+    effect?<T>(execute: () => T, label?: string): unknown;
+    /** Cordis 的事件总线。 */
+    on?(event: string, listener: (...args: never[]) => unknown): () => void;
+    /** 服务查找：**调用时**读可选服务，不触发 inject 断言。 */
+    get?(name: string): unknown;
+    /** 宿主 logger（可选）。 */
+    logger?: CacheWarmupLogger;
+}
+/**
+ * 挂载「缓存预热」的宿主半边。
+ * @param ctx - 宿主插件上下文。
+ * @param options - 挂载选项（设置读取器、可选的存储工厂）。
+ * @returns 卸载函数；重复挂载时返回一个空操作。
+ */
+export declare function installCacheWarmup(ctx: CacheWarmupContext, options: CacheWarmupOptions): () => void;
+/**
+ * 本文件刻意**不保留**任何"把异常压成一句话"的辅助函数。
+ *
+ * 这里曾经有一个 `describe(error)`，把 `error.message` 截断后拼进宿主日志。它看上去
+ * 无害（只取第一行、还截了长度），实际上是一条原文出口：异常消息里常常带着绝对
+ * 路径、命令行片段、凭据，或者被读取结果的一段正文。三处降级日志现在统一走
+ * {@link cacheWarmupErrorLabel}——只输出稳定的 name/code。
+ */
+//# sourceMappingURL=install.d.ts.map

package/lib/types/host/cache-warmup/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../../src/host/cache-warmup/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,EAML,KAAK,sBAAsB,EAG3B,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAA;AACnB,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAExD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,cAAc,CAAA;AAEhD;;GAEG;AACH,eAAO,MAAM,wBAAwB,aAAa,CAAA;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAMxD,CAAA;AAEF,4BAA4B;AAC5B,eAAO,MAAM,yBAAyB,wBAAwB,CAAA;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAStB,CAAA;AAEZ;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,MAAM,CAErD;AAED,mBAAmB;AACnB,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAaD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAiBnE;AAED,YAAY;AACZ,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,mBAAmB,CAAA;IACnC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,oBAAoB,GAAG,SAAS,CAAA;IAC9C;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,sBAAsB,GAAG,SAAS,CAAA;CACxE;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACrD,oBAAoB;IACpB,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAAG,MAAM,IAAI,CAAA;IACvE,uCAAuC;IACvC,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC3B,qBAAqB;IACrB,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAC3B;AA+GD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAoOnG;AAiBD;;;;;;;GAOG"}

package/lib/types/host/cache-warmup/logging.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 「缓存预热」的结构化指标日志。
+ *
+ * 这个文件只做一件事：把一个**指标**形状的事件序列化成一行 JSON。它不碰原文、
+ * 不碰凭据、不碰路径——日志会被收进部署方的日志管道，一条原文进去就把整个工具
+ * 结果的体积原样复制了一份，一条凭据进去就是一次泄露。
+ *
+ * 形状按 `event` 判别，每个分支只允许出现它自己那几个字段：
+ *
+ * - `projection`：一次 post-execute 投影的输入/输出字符数与所选策略；
+ * - `ref-page`：一次 ref 分页读取（读了多少、是否读完、下一页从哪开始）；
+ * - `ref-release`：一次引用释放；
+ * - `warmup-exit`：本会话的预热窗口结束（连同结束时的命中率指标）。
+ *
+ * @module dsh-chatgpt-subscription/host/cache-warmup/logging
+ */
+/** 预热窗口退出时的判定原因（取值有限，便于按值统计）。 */
+export type CacheWarmupExitReason = 
+/** 命中率已经稳定在阈值之上：预热算成功。 */
+'settled'
+/** 命中率没跟上来：预热失败，回到保守行为。 */
+ | 'dropped';
+/** 一次投影的日志记录。 */
+export interface CacheWarmupProjectionLog {
+    readonly event: 'projection';
+    /** 会话标识（只用于把指标归到会话，不含任何正文）。 */
+    readonly session: string;
+    /** 核心选中的策略名（`raw` / `preview` 之类）。 */
+    readonly strategy: string;
+    /** 本次是否真的替换了内容。 */
+    readonly changed: boolean;
+    /** 投影前内容的字符数。 */
+    readonly inputChars: number;
+    /** 投影后内容的字符数。 */
+    readonly outputChars: number;
+    /** 被省略（只剩 preview 指向）的字符数。 */
+    readonly omittedChars: number;
+    /** 会话是否处在预热窗口内。 */
+    readonly warmup?: boolean;
+}
+/** 一次 ref 分页读取的日志记录。 */
+export interface CacheWarmupPageLog {
+    readonly event: 'ref-page';
+    readonly session: string;
+    /** `ref://<session>/<sha256>` 形式的引用（本身不含原文）。 */
+    readonly refId: string;
+    /** 本次读取的起始偏移。 */
+    readonly offset: number;
+    /** 本次真正读到的字符数。 */
+    readonly returnedChars: number;
+    /** 这一次读取是否已经读到结尾。 */
+    readonly complete: boolean;
+    /** 下一次应从哪个偏移继续；`complete` 为真时没有这一项。 */
+    readonly nextOffset?: number;
+}
+/** 一次引用释放的日志记录。 */
+export interface CacheWarmupReleaseLog {
+    readonly event: 'ref-release';
+    readonly session: string;
+    readonly refId: string;
+    /** 是否真的释放掉了（引用不存在时为 false，不算错误）。 */
+    readonly released: boolean;
+}
+/** 一次预热窗口退出的日志记录。 */
+export interface CacheWarmupWarmupExitLog {
+    readonly event: 'warmup-exit';
+    readonly session: string;
+    readonly reason: CacheWarmupExitReason;
+    /** 退出时的连续命中次数（读不到就省略）。 */
+    readonly consecutiveHits?: number;
+    /** 退出时的命中率（读不到就省略）。 */
+    readonly hitRatio?: number;
+}
+/** 本模块产出的全部日志事件。 */
+export type CacheWarmupLogEvent = CacheWarmupProjectionLog | CacheWarmupPageLog | CacheWarmupReleaseLog | CacheWarmupWarmupExitLog;
+/** 日志行前缀，便于在混合日志里一眼认出来源。 */
+export declare const CACHE_WARMUP_LOG_PREFIX = "[cache-warmup]";
+/** 日志面（可选：本插件的 logger 老宿主上可能只有一部分成员）。 */
+export interface CacheWarmupLogger {
+    /** 常规信息行。 */
+    info?(message: string): void;
+    /** 警告行。 */
+    warn?(message: string): void;
+}
+/**
+ * 把一条事件序列化成日志行。
+ *
+ * 形状写死在这里，而不是让调用方自己拼字符串：任何一次「顺手把 content 也带进
+ * 去」的改动都只会发生在这个函数里，而它有测试盯着（断言日志里不含原文）。
+ * 值为 `undefined` 的字段直接不出现在行里，保持每一行只描述它确实测到的指标。
+ * @param event - 指标事件。
+ * @returns 一行日志文本（带上本模块前缀）。
+ */
+export declare function formatCacheWarmupLog(event: CacheWarmupLogEvent): string;
+/**
+ * 把一个异常压成**稳定的身份标签**，只用于宿主日志。
+ *
+ * 只取两样东西：`name`（构造器名；缺失或不是非空字符串时退成 `'Error'`）和
+ * `code`（有就带上——`CacheWarmupStoreError` 与 Node 的系统错误都靠它区分）。
+ *
+ * **`message` 一律不进日志**，这是本函数存在的全部理由：异常消息里常常带着绝对
+ * 路径、命令行片段、凭据，或者被读取结果的一段原文。一条日志就够把原文复制一份，
+ * 或者把主机的目录结构写进部署方的日志管道。想知道"哪一类错误、来自哪一层"，
+ * name/code 就够了；想知道"具体哪一条",该去会话本身看，不该从日志里捞。
+ * @param error - 捕获到的任意值。
+ * @returns 形如 `Error`、`RangeError`、`CacheWarmupStoreError/SESSION_MISMATCH`
+ *   的标签（`code` 是非空字符串时以 `/` 连接）。
+ */
+export declare function cacheWarmupErrorLabel(error: unknown): string;
+/**
+ * 发一条指标日志。
+ *
+ * logger 缺席时**安静跳过**：日志不是功能，装不上日志服务的宿主不该因此装不上
+ * 这个模块。写入失败同样吞掉——一条日志把工具调用搞挂是最不划算的失败。
+ * @param logger - 宿主 logger（可选）。
+ * @param event - 指标事件。
+ * @returns 写出的那一行（调用方/测试可以拿去断言）；没写出去时 undefined。
+ */
+export declare function logCacheWarmup(logger: CacheWarmupLogger | undefined, event: CacheWarmupLogEvent): string | undefined;
+//# sourceMappingURL=logging.d.ts.map

package/lib/types/host/cache-warmup/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../../src/host/cache-warmup/logging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,iCAAiC;AACjC,MAAM,MAAM,qBAAqB;AAC/B,0BAA0B;AACxB,SAAS;AACX,2BAA2B;GACzB,SAAS,CAAA;AAEb,iBAAiB;AACjB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,mBAAmB;IACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,iBAAiB;IACjB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,iBAAiB;IACjB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,mBAAmB;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED,wBAAwB;AACxB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iBAAiB;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,kBAAkB;IAClB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,qBAAqB;IACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,mBAAmB;AACnB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED,qBAAqB;AACrB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;IACtC,0BAA0B;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,uBAAuB;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,oBAAoB;AACpB,MAAM,MAAM,mBAAmB,GAC3B,wBAAwB,GACxB,kBAAkB,GAClB,qBAAqB,GACrB,wBAAwB,CAAA;AAE5B,4BAA4B;AAC5B,eAAO,MAAM,uBAAuB,mBAAmB,CAAA;AAEvD,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,aAAa;IACb,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,WAAW;IACX,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAUvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQ5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,EAAE,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAUpH"}

package/lib/types/host/cache-warmup/projection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 保守结构化投影：只有**可证明**的结构才换成预览，其余一律原样。
+ *
+ * 默认保守的四条线：
+ *
+ * - 小结果原样（不超过预算就不动），因为换来换去只会扰乱缓存前缀。
+ * - 无法可靠解析的大文本原样；未知大文本原样；关键源码、接口/类型定义、子代理报告原样。
+ * - 失败结果只允许换成「完整失败集」型预览（测试失败清单、shell 错误行），
+ *   永远不会被压成一句计数 —— 计数看起来像结论，实际会把下一步的调试带偏。
+ * - 预览必须自述完整度：带 ref、带省略字符数，读全文的路径写在预览里。
+ *
+ * 另一个不变量：本模块**不修改历史**。它返回一份新内容，调用方决定要不要写进新结果；
+ * 已经进入历史的 preview 与其 refId 是常量，存储过期也不会回头改它。
+ *
+ * @module dsh-chatgpt-subscription/host/cache-warmup/projection
+ */
+import { type PreviewBudget, type ProjectionResult, type ProjectToolResultInput } from './contracts.ts';
+/**
+ * 投影一条工具结果。
+ *
+ * 纯函数式语义：不改入参、不写日志、不碰历史；返回新内容 + 度量。
+ * 只有 `changed: true` 时才有 `refId`/`preview`。
+ * @param input - 工具结果与预算。
+ * @returns 投影结果。
+ */
+export declare function projectToolResult(input: ProjectToolResultInput): Promise<ProjectionResult>;
+/** 便于测试/统计：当前生效的默认预览预算（不传会话）。 */
+export declare function defaultPreviewBudget(): PreviewBudget;
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/host/cache-warmup/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../../src/host/cache-warmup/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAErB,KAAK,sBAAsB,EAG5B,MAAM,gBAAgB,CAAA;AA+sBvB;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgFhG;AAED,iCAAiC;AACjC,wBAAgB,oBAAoB,IAAI,aAAa,CAEpD"}

package/lib/types/host/cache-warmup/result-tool.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 模型可见的 `cache_warmup_result` 工具：对一条被投影过的结果做**精确补读**。
+ *
+ * 投影把超大结果换成预览，预览里带一个 `ref://<session>/<sha256>` 引用。这个
+ * 工具就是那条引用的唯一读法，两个动作：
+ *
+ * - `page`：读一段。参数与共享的 `ResultReferenceStore.page` 逐字对齐
+ *   （`sessionId` / `refId` / `offset` / `limit` / `maxBytes` / `fields` /
+ *   `equals`），回来的永远是一页带 `complete` / `nextOffset` / `omitted` 的结构
+ *   —— 模型必须能从返回值本身看出「读完了没有」，而不是猜。
+ * - `release`：丢掉服务端的那份存储。释放之后历史里的 preview 与 refId **不变**
+ *   （它们是历史的一部分），变的只是"补读不到了"。
+ *
+ * 三条不变量写在这个文件里：
+ *
+ * 1. **越权拒绝**：执行时再校验一次当前 provider 与 session。会话变了（换了线路、
+ *    子会话拿到了父会话的引用）就返回结构化错误，**不去问存储**——一条被拒绝的
+ *    调用不该在别人的引用上留下任何痕迹。
+ * 2. **错误是值，不是异常**：开关关闭、存储缺席、引用不存在，全都返回 `ok:false`
+ *    的规范值。一次「补读不到」不该变成一次失败的工具调用。存储自己抛的错误码
+ *    （`SESSION_MISMATCH` / `REFERENCE_INVALID` / …）原样透传，别压成一个笼统的
+ *    "读失败"，模型按码能自己纠正参数。
+ * 3. **不手写模型消息**：输出走 `defineTool` 的 `output.schema` + `render`，
+ *    由宿主决定怎么落到对话里。
+ *
+ * @module dsh-chatgpt-subscription/host/cache-warmup/result-tool
+ */
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { ResultReferenceStore } from './index.ts';
+import type { CacheWarmupRoute } from './install.ts';
+import type { CacheWarmupLogEvent } from './logging.ts';
+/** 注册的工具名。冻结契约的一部分，不要改动。 */
+export declare const CACHE_WARMUP_RESULT_TOOL = "cache_warmup_result";
+/** 工具认识的两个动作。 */
+export type CacheWarmupResultAction = 'page' | 'release';
+/** 工具返回的规范值。 */
+export interface CacheWarmupResultValue {
+    /** 这次调用是否成功。失败的细节在 `error` 里。 */
+    ok: boolean;
+    /** 回显动作，便于模型确认自己调的是哪一个。 */
+    action: CacheWarmupResultAction;
+    /** 被读/被释放的引用。 */
+    refId: string;
+    /** 引用所属会话（执行时校验过）。 */
+    sessionId: string;
+    /** page：这一次是否已经读到结尾。 */
+    complete?: boolean;
+    /** page：本页实际的起始位置（与请求同一单位）。 */
+    offset?: number;
+    /** page：下一次应继续的位置；`complete` 为真时不出现。 */
+    nextOffset?: number;
+    /** page：本页之外还剩多少字符没给出。 */
+    omitted?: number;
+    /** page：本页正文的字符数。 */
+    chars?: number;
+    /** page：原文总字符数（模型据此知道还剩多少要看）。 */
+    totalChars?: number;
+    /** release：是否真的释放掉了。 */
+    released?: boolean;
+    /** page：本页正文。 */
+    text?: string;
+    /** 失败时的结构化错误。 */
+    error?: {
+        /** 稳定的错误码，调用方按它分支。 */
+        code: string;
+        /** 给模型看的一句话说明（不含原文）。 */
+        message: string;
+    };
+}
+/** 工具依赖。 */
+export interface CacheWarmupResultToolDeps {
+    /** 本工具只为这一条线路服务（由安装方注入，工具自己不认识 provider 名字）。 */
+    readonly provider: string;
+    /** 读一次执行所属的线路；每次执行重读，不缓存。 */
+    readonly routeOf: (exec: unknown) => CacheWarmupRoute;
+    /** 结果引用存储；缺席时工具照常存在，只是每次都返回结构化错误。 */
+    readonly store: () => ResultReferenceStore | undefined;
+    /** 指标日志出口（由安装方接上 logger；测试里可以换成断言用的收集器）。 */
+    readonly log?: (event: CacheWarmupLogEvent) => unknown;
+}
+/**
+ * 造 `cache_warmup_result` 工具。
+ * @param deps - 依赖：线路校验、存储读取、指标日志。
+ * @returns 可注册的工具定义。
+ */
+export declare function createCacheWarmupResultTool(deps: CacheWarmupResultToolDeps): ToolDefinition;
+//# sourceMappingURL=result-tool.d.ts.map

package/lib/types/host/cache-warmup/result-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-tool.d.ts","sourceRoot":"","sources":["../../../../src/host/cache-warmup/result-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAEvD,4BAA4B;AAC5B,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAE7D,iBAAiB;AACjB,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAAA;AAaxD,gBAAgB;AAChB,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,EAAE,EAAE,OAAO,CAAA;IACX,2BAA2B;IAC3B,MAAM,EAAE,uBAAuB,CAAA;IAC/B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,iBAAiB;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iBAAiB;IACjB,KAAK,CAAC,EAAE;QACN,sBAAsB;QACtB,IAAI,EAAE,MAAM,CAAA;QACZ,wBAAwB;QACxB,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAED,YAAY;AACZ,MAAM,WAAW,yBAAyB;IACxC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,gBAAgB,CAAA;IACrD,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,oBAAoB,GAAG,SAAS,CAAA;IACtD,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAA;CACvD;AAsHD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,yBAAyB,GAAG,cAAc,CAkL3F"}

package/lib/types/host/cache-warmup/settings.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 「缓存预热」宿主集成的设置面。
+ *
+ * 这个文件**刻意不 import 核心**：设置解析必须在这个宿主上的任何状态都能跑——
+ * 包括结果投影因为任何原因不可用的时候，设置卡那一行仍然要读得回来。
+ *
+ * 字段是 volatile 的（见 `src/index.ts` 的 `Config`）：loader 把它解析成活引用交进
+ * `apply`，设置卡保存时就地写新值、**不**重挂插件行。所以
+ * {@link resolveCacheWarmupSettings} 必须每次用到都重新调，而不是在 apply 时求值
+ * 一次存下来——存下来的那一份会让开关在同一个会话里彻底失效。
+ *
+ * 语义上只有一条保守规则：开关**只影响之后产生的新结果**。已经进入历史的结果，
+ * 它的 preview 与 refId 是历史的一部分，不随开关、也不随存储过期而改变
+ * （见 `install.ts` 的 post-execute 说明）。
+ *
+ * @module dsh-chatgpt-subscription/host/cache-warmup/settings
+ */
+/**
+ * profile 里的设置字段名。
+ *
+ * 设置卡按这个键读写，改名等于让老配置整体失效；测试也用它拼配置对象，避免
+ * 「设置里叫 A、解析时读 B」这种只在线上才发现的错位。
+ */
+export declare const CACHE_WARMUP_SETTING = "cacheWarmup";
+/**
+ * 设置卡上这一行的说明文字。
+ *
+ * schema（`src/index.ts` 的 `Config`）与设置卡共用同一份文案：两处各写一份，
+ * 迟早变成「卡片说只影响新结果、schema 说立刻生效」这种自相矛盾。
+ */
+export declare const CACHE_WARMUP_SETTING_DESCRIPTION: string;
+/** 一次挂载读到的有效设置。 */
+export interface CacheWarmupSettings {
+    /** 总开关。关闭后新的工具结果原样返回，已有结果与引用不动。 */
+    enabled: boolean;
+}
+/** 缺省设置：开启。 */
+export declare const DEFAULT_CACHE_WARMUP_SETTINGS: CacheWarmupSettings;
+/**
+ * 设置字段在运行时可能是活引用（volatile）或普通值（手工构造的上下文、测试）。
+ *
+ * loader 把声明为 `volatile()` 的字段解析成一个 `{ get() }` 活引用，设置保存时
+ * 就地写新值并广播 `loader/volatile-update`，**不**重挂插件行；所以这里必须能
+ * 跟着引用读到当前值，而不是拿到一份快照。
+ */
+interface ConfigRef<T> {
+    /** 读取当前已提交的值。 */
+    get(): T | undefined;
+}
+/** 一个配置字段：活引用或普通值。 */
+export type CacheWarmupConfigField<T> = ConfigRef<T> | T | undefined;
+/** 主入口交给本模块的配置形状（只取本模块认识的那一个字段）。 */
+export interface CacheWarmupConfigFields {
+    /** 总开关字段。 */
+    cacheWarmup?: CacheWarmupConfigField<boolean>;
+}
+/**
+ * 读取一个配置字段，沿着 volatile 活引用取当前值。
+ * @param field - 字段本身。
+ * @returns 当前值，或字段缺失时的 undefined。
+ */
+export declare function readCacheWarmupConfigField<T>(field: CacheWarmupConfigField<T>): T | undefined;
+/**
+ * 解析一次读取的有效设置。
+ *
+ * 每次调用都重读活引用，因此设置保存后立刻生效（对**之后**的新结果生效；历史
+ * 结果不重新投影，见模块说明）。
+ * @param config - 主入口收到的插件配置（活引用或普通值）。
+ * @returns 生效的开关。
+ */
+export declare function resolveCacheWarmupSettings(config?: CacheWarmupConfigFields): CacheWarmupSettings;
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/lib/types/host/cache-warmup/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../../src/host/cache-warmup/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,gBAAgB,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,QAEkB,CAAA;AAE/D,mBAAmB;AACnB,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,eAAe;AACf,eAAO,MAAM,6BAA6B,EAAE,mBAAuC,CAAA;AAEnF;;;;;;GAMG;AACH,UAAU,SAAS,CAAC,CAAC;IACnB,iBAAiB;IACjB,GAAG,IAAI,CAAC,GAAG,SAAS,CAAA;CACrB;AAED,sBAAsB;AACtB,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAA;AAEpE,oCAAoC;AACpC,MAAM,WAAW,uBAAuB;IACtC,aAAa;IACb,WAAW,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,CAAA;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAM7F;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,CAAC,EAAE,uBAAuB,GAAG,mBAAmB,CAKhG"}

package/lib/types/host/cache-warmup/store.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 结果引用存储：内容寻址、原子写入、按字节安全分页。
+ *
+ * 三条不变量：
+ *
+ * 1. **原文逐字保存**。文件名是原文 UTF-8 字节的 sha256，所以同一份内容重复入库是幂等的，
+ *    也不可能有一条引用悄悄指向别的字节。
+ * 2. **历史 preview 与存储生命周期无关**。过期/淘汰/释放只影响「还能不能读到原文」，
+ *    已经写进历史的那段预览文本是常量 —— 本模块从不接触历史。
+ * 3. **只删具体文件**。淘汰按 mtime 逐个 `rm` 文件，绝不递归删除任何目录。
+ *
+ * @module dsh-chatgpt-subscription/host/cache-warmup/store
+ */
+import { type ResultPage, type ResultPageQuery, type ResultPutInput, type ResultReferenceStore, type StoredResultReference } from './contracts.ts';
+/** 引用前缀。 */
+export declare const RESULT_REFERENCE_PREFIX = "ref://";
+/**
+ * 拼一条引用。digest 必须是 64 位小写十六进制，否则分页时会拒绝解析。
+ * @param sessionId - 会话 id。
+ * @param digest - 原文 sha256。
+ * @returns `ref://<session>/<digest>`。
+ */
+export declare function formatResultRefId(sessionId: string, digest: string): string;
+/**
+ * 解析一条引用。
+ * @param refId - 待解析的引用。
+ * @returns 会话与 digest；形状不合法时 undefined。
+ */
+export declare function parseResultRefId(refId: string): {
+    sessionId: string;
+    digest: string;
+} | undefined;
+/** `FileResultReferenceStore` 的构造选项；全部可选，零参构造走 {@link defaultResultStoreRootDir}。 */
+export interface FileResultReferenceStoreOptions {
+    /** 根目录；不传则用 `<DSH_HOME>/storages/cache-warmup`。 */
+    rootDir?: string;
+    /** 单结果字节上限。 */
+    maxResultBytes?: number;
+    /** 每 session 字节总量上限。 */
+    maxSessionBytes?: number;
+    /** 引用有效期（毫秒）；不传表示不过期。 */
+    ttlMs?: number;
+    /** 时钟（毫秒），只用于有效期判定与记录时刻；测试可注入。 */
+    now?: () => number;
+}
+/**
+ * 默认根目录。
+ *
+ * 每次调用都重新解析 `DSH_HOME`，所以构造之后再改环境变量（测试、多 profile）
+ * 仍然生效；这也是零参构造能安全地只拿一个惰性默认值的原因。
+ * @returns 默认根目录的绝对路径。
+ */
+export declare function defaultResultStoreRootDir(): string;
+/**
+ * 文件系统结果存储。
+ *
+ * 目录布局：`<rootDir>/<sessionId>/<sha256>.txt`。会话 id 已经是单个安全路径段，
+ * 所以「另一个 session 的引用」在路径上就构造不出来；即便如此 page 仍然先做归属校验，
+ * 免得将来换布局时丢掉这道闸。
+ */
+export declare class FileResultReferenceStore implements ResultReferenceStore {
+    private readonly options;
+    private resolvedRootDir;
+    /** @param options - 根目录与上限；全部可选。 */
+    constructor(options?: FileResultReferenceStoreOptions);
+    /** 当前生效的根目录。 */
+    rootDir(): string;
+    /** 单结果字节上限。 */
+    private maxResultBytes;
+    /** 每 session 字节总量上限。 */
+    private maxSessionBytes;
+    /** 当前时钟。 */
+    private now;
+    /** 一个会话的目录。 */
+    private sessionDir;
+    /** 一个会话里一个 digest 的文件路径。 */
+    private fileFor;
+    /**
+     * 保存原文。
+     *
+     * 幂等：文件已存在就直接返回同一个 refId，不重写、不改 mtime。
+     * 原子：先写同目录的临时文件再 rename，读到一半的引用不可能存在。
+     * 权限：写 0600（Windows 上是尽力而为，测试按平台跳过权限断言）。
+     */
+    put(input: ResultPutInput): Promise<StoredResultReference>;
+    /**
+     * 按 session 预算淘汰最旧的原文。
+     *
+     * 只按 mtime 从旧到新单个删除；删的是具体文件，路径来自 readdir，不含目录递归。
+     * 淘汰永远不改任何历史 preview —— 那是调用方已经拿走的文本。
+     */
+    private enforceSessionBudget;
+    /**
+     * 读一页。
+     *
+     * 归属校验在碰文件系统之前完成：别人的引用不会告诉你它存在不存在。
+     */
+    page(input: ResultPageQuery): Promise<ResultPage>;
+    /**
+     * 释放一条引用：只删这一个具体文件，缺了就当已经释放（返回 false）。
+     * 清理路径上不抛文件系统错误，免得在 finally 里把原始异常顶掉。
+     */
+    release(input: {
+        sessionId: string;
+        refId: string;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/types/host/cache-warmup/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/host/cache-warmup/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAA;AAQvB,YAAY;AACZ,eAAO,MAAM,uBAAuB,WAAW,CAAA;AAQ/C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAKjG;AAED,qFAAqF;AACrF,MAAM,WAAW,+BAA+B;IAC9C,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,eAAe;IACf,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AA8PD;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,oBAAoB;IACnE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,eAAe,CAAoB;IAE3C,oCAAoC;gBACxB,OAAO,GAAE,+BAAoC;IAIzD,gBAAgB;IAChB,OAAO,IAAI,MAAM;IAOjB,eAAe;IACf,OAAO,CAAC,cAAc;IAKtB,wBAAwB;IACxB,OAAO,CAAC,eAAe;IAKvB,YAAY;IACZ,OAAO,CAAC,GAAG;IAIX,eAAe;IACf,OAAO,CAAC,UAAU;IAIlB,4BAA4B;IAC5B,OAAO,CAAC,OAAO;IAIf;;;;;;OAMG;IACG,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAoChE;;;;;OAKG;YACW,oBAAoB;IAiClC;;;;OAIG;IACG,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAuCvD;;;OAGG;IACG,OAAO,CAAC,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAmB7E"}