@eddyskywalker/dsh-chatgpt-subscription 0.44.0 → 0.45.0

package/lib/index.js

@@ -141,7 +141,7 @@ const ROUTE_PREFIX$4 = "/api/dsh-chatgpt-subscription";
 * `test/responses-client.test.ts` asserts the two agree, so a release that
 * forgets this constant fails the suite instead of shipping quietly.
 */
-const PLUGIN_VERSION = "0.44.0";
+const PLUGIN_VERSION = "0.45.0";
 const CODEX_CHATGPT_PROVIDER_ID = "codex-chatgpt";
 const CODEX_API_BASE = "https://chatgpt.com/backend-api/codex";
 const CODEX_RESPONSES_URL = `${CODEX_API_BASE}/responses`;
@@ -221,6 +221,18 @@ const CODEX_MODEL_CATALOG = [
 		supportsOutputVerbosity: true,
 		defaultOutputVerbosity: "low"
 	},
+	{
+		id: "gpt-6.1-terra",
+		name: "6.1 Terra",
+		contextWindow: GPT_6_DEFAULT_CONTEXT_WINDOW,
+		inputModalities: ["text", "image"],
+		defaultReasoningEffort: "medium",
+		reasoningProfile: "gpt-6",
+		supportsReasoningSummary: true,
+		maxTokens: GPT_6_MAX_TOKENS,
+		supportsOutputVerbosity: true,
+		defaultOutputVerbosity: "low"
+	},
 	{
 		id: "gpt-6-sol",
 		name: "6 Sol",
@@ -312,6 +324,7 @@ const CODEX_MODEL_CATALOG = [
 const DEFAULT_VISIBLE_CODEX_MODEL_IDS = [
 	"gpt-6-astra",
 	"gpt-6.1-sol",
+	"gpt-6.1-terra",
 	"gpt-6-sol",
 	"gpt-6-luna",
 	"gpt-5.6-sol",
@@ -24670,6 +24683,1327 @@ var OllamaAccountPool = class extends AccountPoolCore {
 	}
 };
 //#endregion
+//#region src/host/cache-warmup/contracts.ts
+/**
+* 缓存预热子包（cache-warmup）的共享契约：类型、默认值与错误码。
+*
+* 这一层刻意不 import 任何 `node:` 内置模块：投影与预算的一半逻辑是纯字符串/数字运算，
+* 保持零依赖才能让消费者（宿主适配层、设置路由、测试）只为了一个类型就拖进文件系统实现。
+* 唯一的例外是 `parseStructuredResultRows` —— 它是对**已存储原文**的解析器，
+* 存储分页与投影预览必须共用同一份判定，否则「能分页但预览判断不同」会立刻变成幻觉。
+*
+* @module dsh-chatgpt-subscription/host/cache-warmup/contracts
+*/
+/**
+* 子包默认值。
+*
+* 预热期的字符上限是**按 token 反推的保守字符预算**：中文/代码混排大约每 token 1.6-2.0
+* 字符，1200 字符落在 512-1024 token 区间的中段，宁可少给也不要在预热期用一个
+* 还没被验证过的更大预算去撞缓存键。命中率与连续次数见约束 4。
+*/
+const CACHE_WARMUP_DEFAULTS = {
+	/** 预热期单次预览的字符预算。约 600-750 tokens。 */
+	warmupMaxChars: 1200,
+	/** 稳态（连续两次高命中率且无 drift 之后）的字符预算。 */
+	steadyStateMaxChars: 8e3,
+	/** 视为命中的最低命中率。 */
+	hitRatioThreshold: .97,
+	/** 退出预热期需要连续命中的报告条数。 */
+	consecutiveHitsRequired: 2,
+	/** 单结果原文上限（字节）。 */
+	maxResultBytes: 8 * 1024 * 1024,
+	/** 每 session 原文总量上限（字节）。 */
+	maxSessionBytes: 64 * 1024 * 1024,
+	/** 分页 limit 默认值（行）。 */
+	pageLimitDefault: 64,
+	/** 分页 limit 上限（行）。 */
+	pageLimitMax: 512,
+	/** 分页 maxBytes 默认值（字节）。 */
+	pageMaxBytesDefault: 16 * 1024,
+	/** 分页 maxBytes 上限（字节）。 */
+	pageMaxBytesMax: 64 * 1024,
+	/** usage registry 的 session 数上限。 */
+	maxUsageSessions: 256,
+	/** 每 session 保留的用量报告条数上限。 */
+	maxUsageReportsPerSession: 32
+};
+/**
+* 存储层错误。信息里只描述**请求本身**的问题，绝不回显其他 session 的内容或存在性。
+*/
+var CacheWarmupStoreError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "CacheWarmupStoreError";
+	}
+};
+/** 一段文本被拆开的一列。 */
+function splitDelimitedLine(line, delimiter) {
+	const cells = [];
+	let current = "";
+	let quoted = false;
+	for (let index = 0; index < line.length; index += 1) {
+		const char = line[index];
+		if (char === "\"") {
+			if (quoted && line[index + 1] === "\"") {
+				current += "\"";
+				index += 1;
+			} else quoted = !quoted;
+			continue;
+		}
+		if (!quoted && char === delimiter) {
+			cells.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	cells.push(current);
+	return cells;
+}
+/** 把任意 JSON 值压成单元格文本；对象/数组保持可读的 JSON。 */
+function cellOf(value) {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	try {
+		return JSON.stringify(value) ?? "";
+	} catch {
+		return "";
+	}
+}
+/** JSON Lines：每一行都是一个对象，且至少两行。 */
+function parseJsonLines(lines) {
+	if (lines.length < 2) return void 0;
+	const fields = [];
+	const seen = /* @__PURE__ */ new Set();
+	const rows = [];
+	for (const line of lines) {
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			return;
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return void 0;
+		const record = parsed;
+		const row = {};
+		for (const [key, value] of Object.entries(record)) {
+			if (!seen.has(key)) {
+				seen.add(key);
+				fields.push(key);
+			}
+			row[key] = cellOf(value);
+		}
+		rows.push(row);
+	}
+	if (fields.length === 0) return void 0;
+	return {
+		fields,
+		rows
+	};
+}
+/** 分隔符表格：首行表头 + 至少两行同列数的数据。 */
+function parseDelimitedRows(lines) {
+	if (lines.length < 3) return void 0;
+	const header = lines[0];
+	const delimiter = header.includes("	") ? "	" : header.includes(",") ? "," : void 0;
+	if (delimiter === void 0) return void 0;
+	const fields = splitDelimitedLine(header, delimiter).map((cell) => cell.trim());
+	if (fields.length < 2 || fields.some((field) => field === "")) return void 0;
+	if (new Set(fields).size !== fields.length) return void 0;
+	const rows = [];
+	for (const line of lines.slice(1)) {
+		const cells = splitDelimitedLine(line, delimiter);
+		if (cells.length !== fields.length) return void 0;
+		const row = {};
+		fields.forEach((field, index) => {
+			row[field] = cells[index];
+		});
+		rows.push(row);
+	}
+	return rows.length === 0 ? void 0 : {
+		fields,
+		rows
+	};
+}
+/**
+* 把一段文本可靠地解析成结构化行；解析不可靠就返回 undefined。
+*
+* 判定刻意保守：宁可返回 undefined 让调用方保持原文，也不要猜出一张表，
+* 因为下游会把「猜出来的表」当成完整事实。
+*/
+function parseStructuredResultRows(text) {
+	const lines = text.split("\n").map((line) => line.trimEnd()).filter((line) => line.trim() !== "");
+	if (lines.length < 2) return void 0;
+	return parseJsonLines(lines) ?? parseDelimitedRows(lines);
+}
+//#endregion
+//#region src/host/cache-warmup/store.ts
+/**
+* 结果引用存储：内容寻址、原子写入、按字节安全分页。
+*
+* 三条不变量：
+*
+* 1. **原文逐字保存**。文件名是原文 UTF-8 字节的 sha256，所以同一份内容重复入库是幂等的，
+*    也不可能有一条引用悄悄指向别的字节。
+* 2. **历史 preview 与存储生命周期无关**。过期/淘汰/释放只影响「还能不能读到原文」，
+*    已经写进历史的那段预览文本是常量 —— 本模块从不接触历史。
+* 3. **只删具体文件**。淘汰按 mtime 逐个 `rm` 文件，绝不递归删除任何目录。
+*
+* @module dsh-chatgpt-subscription/host/cache-warmup/store
+*/
+/** 会话 id 的合法形状：单个路径段，不允许分隔符与 `..`。 */
+const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** `ref://<session>/<sha256>`。 */
+const REFERENCE_PATTERN = /^ref:\/\/([A-Za-z0-9][A-Za-z0-9._-]{0,127})\/([0-9a-f]{64})$/;
+/** 引用前缀。 */
+const RESULT_REFERENCE_PREFIX = "ref://";
+/** 原文文件后缀。 */
+const RESULT_SUFFIX = ".txt";
+/** 临时文件标记（原子写入的中转，永不被分页读到）。 */
+const TMP_MARKER = ".tmp.";
+/**
+* 拼一条引用。digest 必须是 64 位小写十六进制，否则分页时会拒绝解析。
+* @param sessionId - 会话 id。
+* @param digest - 原文 sha256。
+* @returns `ref://<session>/<digest>`。
+*/
+function formatResultRefId(sessionId, digest) {
+	return `${RESULT_REFERENCE_PREFIX}${sessionId}/${digest}`;
+}
+/**
+* 解析一条引用。
+* @param refId - 待解析的引用。
+* @returns 会话与 digest；形状不合法时 undefined。
+*/
+function parseResultRefId(refId) {
+	if (typeof refId !== "string") return void 0;
+	const match = REFERENCE_PATTERN.exec(refId);
+	if (match === null) return void 0;
+	return {
+		sessionId: match[1],
+		digest: match[2]
+	};
+}
+/**
+* 默认根目录。
+*
+* 每次调用都重新解析 `DSH_HOME`，所以构造之后再改环境变量（测试、多 profile）
+* 仍然生效；这也是零参构造能安全地只拿一个惰性默认值的原因。
+* @returns 默认根目录的绝对路径。
+*/
+function defaultResultStoreRootDir() {
+	return path.join(dshHomeDir(), "storages", "cache-warmup");
+}
+/** 校验会话 id 形状，非法直接拒绝（路径穿越在这里被挡住）。 */
+function assertSessionId(sessionId) {
+	if (typeof sessionId !== "string" || !SESSION_PATTERN.test(sessionId)) throw new CacheWarmupStoreError("session id is not a single safe path segment", "SESSION_INVALID");
+	return sessionId;
+}
+/** 把 limit 收进 [1, 512]。 */
+function clampLimit(limit) {
+	if (limit === void 0 || !Number.isFinite(limit)) return CACHE_WARMUP_DEFAULTS.pageLimitDefault;
+	const rounded = Math.floor(limit);
+	if (rounded < 1) return 1;
+	return Math.min(rounded, CACHE_WARMUP_DEFAULTS.pageLimitMax);
+}
+/** 把 maxBytes 收进 [1, 65536]。 */
+function clampMaxBytes(maxBytes) {
+	if (maxBytes === void 0 || !Number.isFinite(maxBytes)) return CACHE_WARMUP_DEFAULTS.pageMaxBytesDefault;
+	const rounded = Math.floor(maxBytes);
+	if (rounded < 1) return 1;
+	return Math.min(rounded, CACHE_WARMUP_DEFAULTS.pageMaxBytesMax);
+}
+/** 一段文本的行数（末尾没有换行也算一行）。 */
+function countLines(text) {
+	if (text === "") return 0;
+	let lines = 0;
+	for (const char of text) if (char === "\n") lines += 1;
+	return text.endsWith("\n") ? lines : lines + 1;
+}
+/**
+* 按 UTF-8 字节安全分页。
+*
+* `offset` 是字节偏移，必须落在字符边界上（上一页的 `nextOffset` 天然满足）；
+* 每页最多 `limit` 行且不超过 `maxBytes` 字节，任何一页都不会把一个字符切成两半。
+* 两个上限谁先到就在谁那里收手，`nextOffset` 精确指回同一位置，所以
+* 「两次翻页拼起来等于原文」是构造出来的性质，不是巧合。
+*/
+function pageText(args) {
+	const { sessionId, refId, text, buffer, offset, limit, maxBytes } = args;
+	const totalBytes = buffer.length;
+	if (!Number.isInteger(offset) || offset < 0) throw new CacheWarmupStoreError("offset must be a non-negative integer byte offset", "OFFSET_OUT_OF_RANGE");
+	if (offset > totalBytes) throw new CacheWarmupStoreError(`offset ${offset} is past the ${totalBytes}-byte result`, "OFFSET_OUT_OF_RANGE");
+	if (offset < totalBytes && (buffer[offset] & 192) === 128) throw new CacheWarmupStoreError("offset is not on a UTF-8 character boundary", "OFFSET_INVALID");
+	const rest = offset === 0 ? text : new TextDecoder("utf-8").decode(buffer.subarray(offset));
+	let content = "";
+	let contentBytes = 0;
+	let lines = 0;
+	let stoppedByBytes = false;
+	let stoppedByLines = false;
+	for (const char of rest) {
+		const charBytes = Buffer.byteLength(char, "utf8");
+		if (lines >= limit) {
+			stoppedByLines = true;
+			break;
+		}
+		if (contentBytes + charBytes > maxBytes) {
+			if (content === "") {
+				content = char;
+				contentBytes = charBytes;
+			}
+			stoppedByBytes = true;
+			break;
+		}
+		content += char;
+		contentBytes += charBytes;
+		if (char === "\n") lines += 1;
+	}
+	const nextOffset = offset + Buffer.byteLength(content, "utf8");
+	const complete = nextOffset >= totalBytes;
+	const remaining = rest.slice(content.length);
+	return {
+		sessionId,
+		refId,
+		mode: "text",
+		content,
+		offset,
+		nextOffset: complete ? null : nextOffset,
+		complete,
+		omitted: {
+			reason: complete ? "none" : stoppedByBytes ? "bytes" : stoppedByLines ? "lines" : "bytes",
+			chars: remaining.length,
+			lines: countLines(remaining),
+			rows: 0,
+			bytes: Buffer.byteLength(remaining, "utf8")
+		},
+		totalChars: text.length,
+		totalBytes,
+		limit,
+		maxBytes
+	};
+}
+/**
+* 结构化行分页：先可靠解析，再按 `fields`/`equals` 过滤，最后按行取一页。
+*
+* 解析不可信就抛 `NOT_STRUCTURED`，而不是退回文本模式 —— 调用方要的是「按字段取」，
+* 悄悄给回一段原文等于让它以为字段过滤生效了。
+*/
+function pageStructured(args) {
+	const { sessionId, refId, text, buffer, offset, limit, maxBytes } = args;
+	const parsed = parseStructuredResultRows(text);
+	if (parsed === void 0) throw new CacheWarmupStoreError("stored result is not reliably structured rows", "NOT_STRUCTURED");
+	const requested = args.fields === void 0 ? [...parsed.fields] : [...args.fields];
+	for (const field of requested) if (!parsed.fields.includes(field)) throw new CacheWarmupStoreError(`unknown field "${field}"`, "FIELD_UNKNOWN");
+	const equals = args.equals ?? {};
+	for (const key of Object.keys(equals)) if (!parsed.fields.includes(key)) throw new CacheWarmupStoreError(`unknown field "${key}"`, "FIELD_UNKNOWN");
+	const matched = parsed.rows.filter((row) => Object.entries(equals).every(([key, value]) => (row[key] ?? "") === value));
+	if (!Number.isInteger(offset) || offset < 0) throw new CacheWarmupStoreError("offset must be a non-negative integer row index", "OFFSET_OUT_OF_RANGE");
+	if (offset > matched.length) throw new CacheWarmupStoreError(`offset ${offset} is past the ${matched.length}-row result`, "OFFSET_OUT_OF_RANGE");
+	const project = (row) => {
+		const out = {};
+		for (const field of requested) out[field] = row[field] ?? "";
+		return out;
+	};
+	const serialized = (row) => JSON.stringify(project(row));
+	const selected = [];
+	let bytes = 0;
+	let index = offset;
+	let hitByteCap = false;
+	while (index < matched.length && selected.length < limit) {
+		const line = serialized(matched[index]);
+		const lineBytes = Buffer.byteLength(line, "utf8") + (selected.length === 0 ? 0 : 1);
+		if (bytes + lineBytes > maxBytes && selected.length > 0) {
+			hitByteCap = true;
+			break;
+		}
+		if (lineBytes > maxBytes) hitByteCap = true;
+		selected.push(line);
+		bytes += lineBytes;
+		index += 1;
+	}
+	const remainingRows = matched.slice(index);
+	const remainingText = remainingRows.map(serialized).join("\n");
+	const complete = index >= matched.length;
+	return {
+		sessionId,
+		refId,
+		mode: "structured",
+		content: selected.join("\n"),
+		offset,
+		nextOffset: complete ? null : index,
+		complete,
+		omitted: {
+			reason: complete ? "none" : hitByteCap ? "bytes" : "rows",
+			chars: remainingText.length,
+			lines: remainingRows.length,
+			rows: remainingRows.length,
+			bytes: Buffer.byteLength(remainingText, "utf8")
+		},
+		totalChars: text.length,
+		totalBytes: buffer.length,
+		limit,
+		maxBytes,
+		fields: requested,
+		totalRows: parsed.rows.length,
+		matchedRows: matched.length
+	};
+}
+/**
+* 文件系统结果存储。
+*
+* 目录布局：`<rootDir>/<sessionId>/<sha256>.txt`。会话 id 已经是单个安全路径段，
+* 所以「另一个 session 的引用」在路径上就构造不出来；即便如此 page 仍然先做归属校验，
+* 免得将来换布局时丢掉这道闸。
+*/
+var FileResultReferenceStore = class {
+	options;
+	resolvedRootDir;
+	/** @param options - 根目录与上限；全部可选。 */
+	constructor(options = {}) {
+		this.options = { ...options };
+	}
+	/** 当前生效的根目录。 */
+	rootDir() {
+		const configured = this.options.rootDir;
+		if (configured !== void 0 && configured.trim() !== "") return path.resolve(configured);
+		if (this.resolvedRootDir === void 0) this.resolvedRootDir = path.resolve(defaultResultStoreRootDir());
+		return this.resolvedRootDir;
+	}
+	/** 单结果字节上限。 */
+	maxResultBytes() {
+		const value = this.options.maxResultBytes;
+		return value !== void 0 && Number.isFinite(value) && value > 0 ? Math.floor(value) : CACHE_WARMUP_DEFAULTS.maxResultBytes;
+	}
+	/** 每 session 字节总量上限。 */
+	maxSessionBytes() {
+		const value = this.options.maxSessionBytes;
+		return value !== void 0 && Number.isFinite(value) && value > 0 ? Math.floor(value) : CACHE_WARMUP_DEFAULTS.maxSessionBytes;
+	}
+	/** 当前时钟。 */
+	now() {
+		return this.options.now === void 0 ? Date.now() : this.options.now();
+	}
+	/** 一个会话的目录。 */
+	sessionDir(sessionId) {
+		return path.join(this.rootDir(), sessionId);
+	}
+	/** 一个会话里一个 digest 的文件路径。 */
+	fileFor(sessionId, digest) {
+		return path.join(this.sessionDir(sessionId), digest + RESULT_SUFFIX);
+	}
+	/**
+	* 保存原文。
+	*
+	* 幂等：文件已存在就直接返回同一个 refId，不重写、不改 mtime。
+	* 原子：先写同目录的临时文件再 rename，读到一半的引用不可能存在。
+	* 权限：写 0600（Windows 上是尽力而为，测试按平台跳过权限断言）。
+	*/
+	async put(input) {
+		const sessionId = assertSessionId(input.sessionId);
+		if (typeof input.content !== "string") throw new CacheWarmupStoreError("content must be a string", "CONTENT_INVALID");
+		const bytes = Buffer.from(input.content, "utf8");
+		const maxResultBytes = this.maxResultBytes();
+		if (bytes.length > maxResultBytes) throw new CacheWarmupStoreError(`result is ${bytes.length} bytes, above the ${maxResultBytes}-byte single-result limit`, "RESULT_TOO_LARGE");
+		const digest = createHash("sha256").update(bytes).digest("hex");
+		const refId = formatResultRefId(sessionId, digest);
+		const at = input.at ?? this.now();
+		const target = this.fileFor(sessionId, digest);
+		const existing = await fs.stat(target).catch(() => void 0);
+		if (existing !== void 0 && existing.isFile()) return {
+			refId,
+			sessionId,
+			digest,
+			bytes: existing.size,
+			chars: input.content.length,
+			at,
+			created: false
+		};
+		await fs.mkdir(this.sessionDir(sessionId), {
+			recursive: true,
+			mode: 448
+		});
+		await this.enforceSessionBudget(this.sessionDir(sessionId), bytes.length, target);
+		const tmp = path.join(this.sessionDir(sessionId), `${digest}.${process.pid}.${Date.now()}${TMP_MARKER}`);
+		await fs.writeFile(tmp, bytes, { mode: 384 });
+		await fs.chmod(tmp, 384).catch(() => void 0);
+		await fs.rename(tmp, target);
+		await fs.chmod(target, 384).catch(() => void 0);
+		return {
+			refId,
+			sessionId,
+			digest,
+			bytes: bytes.length,
+			chars: input.content.length,
+			at,
+			created: true
+		};
+	}
+	/**
+	* 按 session 预算淘汰最旧的原文。
+	*
+	* 只按 mtime 从旧到新单个删除；删的是具体文件，路径来自 readdir，不含目录递归。
+	* 淘汰永远不改任何历史 preview —— 那是调用方已经拿走的文本。
+	*/
+	async enforceSessionBudget(dir, incoming, keep) {
+		const budget = this.maxSessionBytes();
+		if (incoming > budget) throw new CacheWarmupStoreError(`result is ${incoming} bytes, above the ${budget}-byte per-session limit`, "STORE_FULL");
+		let entries;
+		try {
+			entries = await fs.readdir(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		const files = [];
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith(RESULT_SUFFIX)) continue;
+			const file = path.join(dir, entry.name);
+			if (file === keep) continue;
+			const stats = await fs.stat(file).catch(() => void 0);
+			if (stats === void 0) continue;
+			files.push({
+				file,
+				size: stats.size,
+				mtime: stats.mtimeMs
+			});
+		}
+		let total = files.reduce((sum, file) => sum + file.size, 0);
+		if (total + incoming <= budget) return;
+		files.sort((left, right) => left.mtime - right.mtime);
+		for (const file of files) {
+			if (total + incoming <= budget) break;
+			await fs.rm(file.file, { force: true }).catch(() => void 0);
+			total -= file.size;
+		}
+	}
+	/**
+	* 读一页。
+	*
+	* 归属校验在碰文件系统之前完成：别人的引用不会告诉你它存在不存在。
+	*/
+	async page(input) {
+		const sessionId = assertSessionId(input.sessionId);
+		const parsed = parseResultRefId(input.refId);
+		if (parsed === void 0) throw new CacheWarmupStoreError("reference is not one this store issues", "REFERENCE_INVALID");
+		if (parsed.sessionId !== sessionId) throw new CacheWarmupStoreError("reference does not belong to this session", "SESSION_MISMATCH");
+		const file = this.fileFor(sessionId, parsed.digest);
+		const stats = await fs.stat(file).catch(() => void 0);
+		if (stats === void 0 || !stats.isFile()) throw new CacheWarmupStoreError("stored result is missing; it was released or evicted", "RESULT_NOT_FOUND");
+		const ttlMs = this.options.ttlMs;
+		if (ttlMs !== void 0 && ttlMs > 0 && this.now() - stats.mtimeMs > ttlMs) throw new CacheWarmupStoreError("stored result expired", "RESULT_EXPIRED");
+		const buffer = await fs.readFile(file);
+		const text = new TextDecoder("utf-8").decode(buffer);
+		const limit = clampLimit(input.limit);
+		const maxBytes = clampMaxBytes(input.maxBytes);
+		const offset = input.offset ?? 0;
+		if (input.fields !== void 0 || input.equals !== void 0) return pageStructured({
+			sessionId,
+			refId: input.refId,
+			text,
+			buffer,
+			offset,
+			limit,
+			maxBytes,
+			fields: input.fields,
+			equals: input.equals
+		});
+		return pageText({
+			sessionId,
+			refId: input.refId,
+			text,
+			buffer,
+			offset,
+			limit,
+			maxBytes
+		});
+	}
+	/**
+	* 释放一条引用：只删这一个具体文件，缺了就当已经释放（返回 false）。
+	* 清理路径上不抛文件系统错误，免得在 finally 里把原始异常顶掉。
+	*/
+	async release(input) {
+		const sessionId = assertSessionId(input.sessionId);
+		const parsed = parseResultRefId(input.refId);
+		if (parsed === void 0) throw new CacheWarmupStoreError("reference is not one this store issues", "REFERENCE_INVALID");
+		if (parsed.sessionId !== sessionId) throw new CacheWarmupStoreError("reference does not belong to this session", "SESSION_MISMATCH");
+		const file = this.fileFor(sessionId, parsed.digest);
+		const exists = await fs.stat(file).catch(() => void 0);
+		if (exists === void 0 || !exists.isFile()) return false;
+		try {
+			await fs.rm(file, { force: true });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+//#region src/host/cache-warmup/usage.ts
+/**
+* 缓存用量登记表 —— 有界、只写不读消息、永不抛出。
+*
+* 为什么「永不抛出」是硬性契约：Kimi adapter 在 finally 路径里调用
+* `recordCacheWarmupUsage`。那个位置抛出的任何东西都会顶掉原始异常、把一次失败
+* 伪装成另一次失败，或者让重试/账号轮换逻辑读到半个状态。所以整个函数体被
+* 一层 catch 包住，坏输入、被污染的属性访问、内部容器异常一律降级成中性返回值。
+*
+* 有界：最多 {@link CACHE_WARMUP_DEFAULTS.maxUsageSessions} 个会话，
+* 每个会话最多 {@link CACHE_WARMUP_DEFAULTS.maxUsageReportsPerSession} 条报告。
+* 超出时淘汰最久未活动的会话 / 最旧的报告 —— 内存里只留「最近发生了什么」。
+*
+* @module dsh-chatgpt-subscription/host/cache-warmup/usage
+*/
+/** 有界登记表：Map 的插入顺序同时是 LRU 顺序（命中即重新插入到队尾）。 */
+const registry = /* @__PURE__ */ new Map();
+/** 一个中性返回值，异常路径复用（不含任何容器操作）。 */
+function neutralState(sessionId) {
+	return {
+		sessionId,
+		reports: 0,
+		consecutiveHits: 0,
+		hitRatio: 0
+	};
+}
+/** 非负有限数；其他一律 0。 */
+function finiteCount(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+* 一次请求的缓存命中率 = 命中缓存 token / (未命中 token + 命中 token)。
+*
+* 这里的两个字段是**互斥的两半**，不是整体与部分：Kimi/DSH 上报的
+* `inputTokens` 是这次真正送去计算的未命中部分，`cacheReadTokens` 是命中缓存、
+* 没有重算的部分。所以分母必须是两者之和。
+*
+* 用 `cached / inputTokens` 是错的，而且错得很隐蔽：只要命中数接近或超过未命中数，
+* 比值就会 ≥ 1 并被钳成 1，于是「连续两次 ≥ 0.97」的判据在真实流量的**第一次**请求上
+* 就成立，预热期形同不存在 —— 这正好是这套预算想防的那件事。
+*
+* 也不允许拿 `totalTokens` 当分母：那个字段的构成由上层决定（可能含输出 token、
+* 也可能已经包含缓存部分），用它会让命中率随无关字段漂移。
+*
+* @param usage - 至少含 inputTokens（未命中）与 cacheReadTokens（命中）的用量。
+* @returns 0-1；`input=0` 且 `cached>0` 时为 1；两者都为 0 或非法时为 0。
+*/
+function cacheWarmupHitRatio(usage) {
+	try {
+		const input = finiteCount(usage.inputTokens);
+		const cached = finiteCount(usage.cacheReadTokens);
+		if (cached <= 0) return 0;
+		const total = input + cached;
+		if (total <= 0) return 0;
+		return Math.min(1, cached / total);
+	} catch {
+		return 0;
+	}
+}
+/**
+* 从最新一条往回数「连续高命中率」条数。
+*
+* 停止条件（任一）：命中率低于阈值、该条带 driftCause、报告到头。
+* 「连续」是从最近往回数的，所以中间任何一次低命中或漂移都会把计数截断到 0。
+* @param reports - 按时间从旧到新排列的报告。
+* @returns 连续命中条数。
+*/
+/** Kimi 对每个请求都会报告的生命周期状态；只有其余值才表示真实前缀漂移。 */
+const BENIGN_LIFECYCLE_CAUSES = /* @__PURE__ */ new Set(["stable", "first-request"]);
+function consecutiveWarmupHits(reports) {
+	try {
+		if (!Array.isArray(reports)) return 0;
+		let hits = 0;
+		for (let index = reports.length - 1; index >= 0; index -= 1) {
+			const report = reports[index];
+			if (report === void 0 || report === null) break;
+			const drift = report.driftCause;
+			if (typeof drift === "string" && drift.trim() !== "" && !BENIGN_LIFECYCLE_CAUSES.has(drift)) break;
+			if (cacheWarmupHitRatio(report) < CACHE_WARMUP_DEFAULTS.hitRatioThreshold) break;
+			hits += 1;
+		}
+		return hits;
+	} catch {
+		return 0;
+	}
+}
+/** 把任意输入归一成一条用量报告；形状不对返回 undefined（绝不抛）。 */
+function normalizeUsage(input) {
+	if (input === null || input === void 0 || typeof input !== "object") return void 0;
+	const sessionId = input.sessionId;
+	if (typeof sessionId !== "string" || sessionId.trim() === "") return void 0;
+	const driftCause = typeof input.driftCause === "string" && input.driftCause.trim() !== "" ? input.driftCause : void 0;
+	const at = typeof input.at === "number" && Number.isFinite(input.at) ? input.at : Date.now();
+	const normalized = {
+		sessionId,
+		inputTokens: finiteCount(input.inputTokens),
+		cacheReadTokens: finiteCount(input.cacheReadTokens),
+		outputTokens: finiteCount(input.outputTokens),
+		totalTokens: finiteCount(input.totalTokens),
+		at
+	};
+	if (driftCause !== void 0) normalized.driftCause = driftCause;
+	return normalized;
+}
+/** 由一份报告列表算出状态摘要。 */
+function stateOf(sessionId, reports) {
+	const last = reports[reports.length - 1];
+	return {
+		sessionId,
+		reports: reports.length,
+		consecutiveHits: consecutiveWarmupHits(reports),
+		hitRatio: last === void 0 ? 0 : cacheWarmupHitRatio(last),
+		lastAt: last?.at
+	};
+}
+/**
+* 登记一次用量报告。
+*
+* **total function**：任何输入、任何内部异常都不抛出，最差返回一份中性状态。
+* 有副作用（更新有界登记表），但不触碰消息、不发起请求、不改变请求参数。
+* @param input - 用量报告。
+* @returns 该会话登记之后的状态摘要。
+*/
+function recordCacheWarmupUsage(input) {
+	let sessionId = "";
+	try {
+		const usage = normalizeUsage(input);
+		if (usage === void 0) return neutralState("");
+		sessionId = usage.sessionId;
+		const previous = registry.get(usage.sessionId);
+		const kept = previous === void 0 ? [] : [...previous];
+		kept.push(Object.freeze({ ...usage }));
+		while (kept.length > CACHE_WARMUP_DEFAULTS.maxUsageReportsPerSession) kept.shift();
+		if (previous !== void 0) registry.delete(usage.sessionId);
+		registry.set(usage.sessionId, Object.freeze(kept));
+		while (registry.size > CACHE_WARMUP_DEFAULTS.maxUsageSessions) {
+			const oldest = registry.keys().next();
+			if (oldest.done === true) break;
+			registry.delete(oldest.value);
+		}
+		return stateOf(usage.sessionId, kept);
+	} catch {
+		try {
+			if (sessionId !== "") registry.delete(sessionId);
+		} catch {}
+		return neutralState(sessionId);
+	}
+}
+/**
+* 读一个会话的报告（从旧到新），不抛出。
+* @param sessionId - 会话 id。
+* @returns 报告副本；没有或读不到时为空数组。
+*/
+function cacheWarmupUsageReports(sessionId) {
+	try {
+		if (typeof sessionId !== "string" || sessionId === "") return [];
+		const reports = registry.get(sessionId);
+		return reports === void 0 ? [] : [...reports];
+	} catch {
+		return [];
+	}
+}
+/**
+* 列出所有有报告的会话，按最近活动倒序；不抛出。
+* @returns 会话摘要数组。
+*/
+function cacheWarmupUsageSessions() {
+	try {
+		const summaries = [];
+		for (const [sessionId, reports] of registry.entries()) {
+			if (reports.length === 0) continue;
+			const last = reports[reports.length - 1];
+			summaries.push({
+				sessionId,
+				reports: reports.length,
+				lastAt: last.at,
+				hitRatio: cacheWarmupHitRatio(last)
+			});
+		}
+		summaries.sort((left, right) => right.lastAt - left.lastAt);
+		return summaries;
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/host/cache-warmup/budget.ts
+/**
+* 预热预算：预热期保守、连续命中后放大、漂移立刻收回。
+*
+* 控制器是**纯函数**：不发起请求、不改消息、不改登记表。它只回答一个问题 ——
+* 「这一次预览最多能占多少字符」。把决策与执行分开，才能保证预算收紧或放开
+* 都不会悄悄改写已经进入历史的文本（历史里的 preview 是常量）。
+*
+* @module dsh-chatgpt-subscription/host/cache-warmup/budget
+*/
+/** 预热期的保守预算（构造一次，避免每次读模块常量）。 */
+const WARMUP_BUDGET = Object.freeze({
+	maxChars: CACHE_WARMUP_DEFAULTS.warmupMaxChars,
+	warmup: true,
+	consecutiveHits: 0,
+	hitRatio: 0
+});
+/**
+* 当前会话的预览预算。
+*
+* 规则（约束 4）：预热期 `maxChars = 1200`（约 600-750 tokens）；连续
+* `consecutiveHitsRequired`(2) 次命中率 ≥ 0.97 且期间没有 drift，才进入稳态
+* `maxChars = 8000`。任何一次 drift 都清零连续计数，于是下一条请求立刻回落到预热预算。
+*
+* **不抛出**：没有会话、没有报告、登记表异常，一律返回预热期的保守预算。
+* @param sessionId - 会话 id；不传则按最保守的预热预算处理。
+* @returns 本次投影可用的预算。
+*/
+function cacheWarmupBudget(sessionId) {
+	try {
+		if (typeof sessionId !== "string" || sessionId.trim() === "") return { ...WARMUP_BUDGET };
+		const reports = cacheWarmupUsageReports(sessionId);
+		if (reports.length === 0) return { ...WARMUP_BUDGET };
+		const consecutiveHits = consecutiveWarmupHits(reports);
+		const last = reports[reports.length - 1];
+		const hitRatio = last === void 0 ? 0 : cacheWarmupHitRatio(last);
+		const warmup = consecutiveHits < CACHE_WARMUP_DEFAULTS.consecutiveHitsRequired;
+		return {
+			maxChars: warmup ? CACHE_WARMUP_DEFAULTS.warmupMaxChars : CACHE_WARMUP_DEFAULTS.steadyStateMaxChars,
+			warmup,
+			consecutiveHits,
+			hitRatio
+		};
+	} catch {
+		return { ...WARMUP_BUDGET };
+	}
+}
+/**
+* 一份可读快照。**不抛出**，且完全无副作用（只读登记表）。
+* @param sessionId - 会话 id；不传则给全局汇总。
+* @returns 快照。
+*/
+function cacheWarmupSnapshot(sessionId) {
+	const fallback = {
+		budget: { ...WARMUP_BUDGET },
+		defaults: CACHE_WARMUP_DEFAULTS,
+		usage: {
+			reports: 0,
+			hitRatio: 0,
+			totals: {
+				inputTokens: 0,
+				cacheReadTokens: 0,
+				outputTokens: 0,
+				totalTokens: 0
+			},
+			driftCauses: []
+		},
+		sessions: 0
+	};
+	try {
+		const budget = cacheWarmupBudget(sessionId);
+		const reports = typeof sessionId === "string" && sessionId.trim() !== "" ? cacheWarmupUsageReports(sessionId) : [];
+		const totals = {
+			inputTokens: 0,
+			cacheReadTokens: 0,
+			outputTokens: 0,
+			totalTokens: 0
+		};
+		const driftCauses = [];
+		for (const report of reports) {
+			totals.inputTokens += report.inputTokens;
+			totals.cacheReadTokens += report.cacheReadTokens;
+			totals.outputTokens += report.outputTokens;
+			totals.totalTokens += report.totalTokens;
+			const drift = report.driftCause;
+			if (typeof drift === "string" && drift !== "" && !driftCauses.includes(drift)) driftCauses.push(drift);
+		}
+		const last = reports[reports.length - 1];
+		const snapshot = {
+			budget,
+			defaults: CACHE_WARMUP_DEFAULTS,
+			usage: {
+				reports: reports.length,
+				hitRatio: last === void 0 ? 0 : cacheWarmupHitRatio(last),
+				totals,
+				driftCauses
+			},
+			sessions: cacheWarmupUsageSessions().length
+		};
+		if (last !== void 0) snapshot.usage.lastAt = last.at;
+		if (typeof sessionId === "string" && sessionId.trim() !== "") snapshot.sessionId = sessionId;
+		return snapshot;
+	} catch {
+		return fallback;
+	}
+}
+//#endregion
+//#region src/host/cache-warmup/projection.ts
+/**
+* 保守结构化投影：只有**可证明**的结构才换成预览，其余一律原样。
+*
+* 默认保守的四条线：
+*
+* - 小结果原样（不超过预算就不动），因为换来换去只会扰乱缓存前缀。
+* - 无法可靠解析的大文本原样；未知大文本原样；关键源码、接口/类型定义、子代理报告原样。
+* - 失败结果只允许换成「完整失败集」型预览（测试失败清单、shell 错误行），
+*   永远不会被压成一句计数 —— 计数看起来像结论，实际会把下一步的调试带偏。
+* - 预览必须自述完整度：带 ref、带省略字符数，读全文的路径写在预览里。
+*
+* 另一个不变量：本模块**不修改历史**。它返回一份新内容，调用方决定要不要写进新结果；
+* 已经进入历史的 preview 与其 refId 是常量，存储过期也不会回头改它。
+*
+* @module dsh-chatgpt-subscription/host/cache-warmup/projection
+*/
+/** 子代理报告：一律原样，摘要会丢掉调用方真正要的判断依据。 */
+const TOOL_SUBAGENT = /(?:^|[-_/])(?:subagent|agent|task|delegate|ralph|teammate)(?:[-_/]|$)/i;
+/** 源码读取/写入类工具：一律原样。 */
+const TOOL_SOURCE = /(?:^|[-_/])(?:read|view|cat|open|edit|write|patch|apply_patch|notebook|document|diff)(?:[-_/]|$)/i;
+/** 一行文本的裁剪（超长行才裁剪，并留下省略号）。 */
+function clip(text, max) {
+	return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+/**
+* 按预算装配预览正文。
+*
+* 必需段落要么整段进来，要么整体装不下就返回 undefined（调用方据此保持原文）；
+* 可选段落逐段尝试，装不下就整段跳过。这样任何输出都不会出现「半截失败清单」。
+*/
+function fitSections(sections, maxChars) {
+	const lines = [];
+	let used = 0;
+	for (const section of sections) {
+		if (section.optional === true) continue;
+		for (const line of section.lines) {
+			used += line.length + 1;
+			lines.push(line);
+		}
+	}
+	if (used > maxChars + 1) return void 0;
+	for (const section of sections) {
+		if (section.optional !== true) continue;
+		const size = section.lines.reduce((sum, line) => sum + line.length + 1, 0);
+		if (used + size > maxChars + 1) continue;
+		for (const line of section.lines) lines.push(line);
+		used += size;
+	}
+	return lines.join("\n");
+}
+/** 从测试输出里抽取「完整失败集」与汇总行；抽不全就整体放弃。 */
+function extractTestEvidence(text) {
+	const summary = [];
+	const failures = [];
+	for (const raw of text.split("\n")) {
+		const trimmed = raw.trim();
+		if (trimmed === "") continue;
+		if (/^(?:FAIL|FAILED|✗|✕|×)\s+\S/.test(trimmed) || /^not ok \d+ - /.test(trimmed) || /^●\s+\S/.test(trimmed) || /^--- FAIL:\s/.test(trimmed)) {
+			failures.push(clip(trimmed, 240));
+			continue;
+		}
+		if (/^Test Files\s+\d/.test(trimmed) || /^Tests\s+\d/.test(trimmed) || /^Test Suites:\s/.test(trimmed) || /^Snapshots:\s/.test(trimmed) || /^Time:\s/.test(trimmed) || /^={2,}.*\b\d+ (?:failed|passed|error)/.test(trimmed) || /^\d+ (?:failed|passed), \d+ (?:passed|failed)/.test(trimmed)) summary.push(clip(trimmed, 200));
+	}
+	if (summary.length === 0 && failures.length === 0) return void 0;
+	if (summary.length === 0 && !/\b(?:test|tests|spec|suite|assert)\b/i.test(text.slice(0, 4e3))) return void 0;
+	return {
+		summary,
+		failures
+	};
+}
+/** 测试预览：失败集必须完整，汇总行紧随其后。 */
+function buildTestSections(evidence) {
+	const sections = [{ lines: [`failures: ${evidence.failures.length} (complete set)`] }];
+	if (evidence.failures.length > 0) sections.push({ lines: evidence.failures.map((line) => `  ${line}`) });
+	if (evidence.summary.length > 0) sections.push({ lines: ["summary:", ...evidence.summary.map((line) => `  ${line}`)] });
+	return sections;
+}
+/** 一行 shell 错误。用于「完整错误集」，所以匹配宁可宽一点。 */
+const SHELL_ERROR_LINE = /(?:error|fatal|panic|traceback|exception|EACCES|EPERM|ENOENT|EEXIST|ELIFECYCLE|ERR!|FAILED|permission denied|cannot |could not |not found)/i;
+/** 一行 glob 结果的判定：无空白、像路径。 */
+function looksLikeGlobResult(text) {
+	const lines = text.split("\n").filter((line) => line.trim() !== "");
+	if (lines.length < 10) return false;
+	let paths = 0;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed.length === 0 || trimmed.length > 400) continue;
+		if (/\s/.test(trimmed)) continue;
+		if (/^[-*+]$/.test(trimmed)) continue;
+		paths += 1;
+	}
+	return paths / lines.length >= .9;
+}
+/** shell 输出判定：有退出码标记，或至少一行错误。 */
+function looksLikeShellOutput(text) {
+	if (/(?:exit code|exited with code|process exited with code)[:=\s]+-?\d+/i.test(text)) return true;
+	if (/\[exit code: -?\d+\]/i.test(text)) return true;
+	if (/^Traceback \(most recent call last\):/m.test(text)) return true;
+	const lines = text.split("\n");
+	let errors = 0;
+	for (const line of lines) {
+		if (line.trim() === "") continue;
+		if (/^\s*(?:0|no)\s+(?:errors?|failures?|failed)\b/i.test(line.trim())) continue;
+		if (SHELL_ERROR_LINE.test(line)) errors += 1;
+		if (errors >= 1) return true;
+	}
+	return false;
+}
+/** shell 预览：退出码 + 完整错误集（必需），首尾片段（可选）。 */
+function buildShellSections(text) {
+	const lines = text.split("\n");
+	const errors = [];
+	for (const raw of lines) {
+		const trimmed = raw.trim();
+		if (trimmed === "") continue;
+		if (/^\[exit code: -?\d+\]/i.test(trimmed)) continue;
+		if (/^\s*(?:0|no)\s+(?:errors?|failures?|failed)\b/i.test(trimmed)) continue;
+		if (SHELL_ERROR_LINE.test(trimmed)) errors.push(`  ${clip(trimmed, 240)}`);
+	}
+	if (errors.length > 300) return void 0;
+	const exitMatch = /(?:exit code|exited with code|process exited with code)[:=\s]+(-?\d+)/i.exec(text) ?? /\[exit code: (-?\d+)\]/i.exec(text);
+	const sections = [];
+	if (exitMatch !== null) sections.push({ lines: [`exit code: ${exitMatch[1]}`] });
+	sections.push({ lines: [`errors: ${errors.length} (complete set)`] });
+	if (errors.length > 0) sections.push({ lines: errors });
+	const nonEmpty = lines.map((line) => line.trimEnd()).filter((line) => line.trim() !== "");
+	const head = nonEmpty.slice(0, 5).map((line) => `  ${clip(line.trim(), 160)}`);
+	const tail = nonEmpty.slice(-5).map((line) => `  ${clip(line.trim(), 160)}`);
+	if (head.length > 0) sections.push({
+		lines: ["head:", ...head],
+		optional: true
+	});
+	if (tail.length > 0) sections.push({
+		lines: ["tail:", ...tail],
+		optional: true
+	});
+	return sections;
+}
+/** 一行 grep 结果：`<path>:<line>[:<column>]:<text>`。 */
+const GREP_LINE = /^(.+?):(\d+):(?:\d+:)?(.*)$/;
+/** 抽取 grep 证据；命中线占比不到 80% 就当它不是 grep 输出。 */
+function extractGrepEvidence(text) {
+	const lines = text.split("\n").filter((line) => line.trim() !== "");
+	if (lines.length < 10) return void 0;
+	const files = /* @__PURE__ */ new Map();
+	let matched = 0;
+	for (const line of lines) {
+		const match = GREP_LINE.exec(line);
+		if (match === null) continue;
+		const file = match[1];
+		if (!/[\\/.]/.test(file) || file.length > 400) continue;
+		matched += 1;
+		const entry = files.get(file);
+		if (entry === void 0) files.set(file, {
+			count: 1,
+			first: match[3]
+		});
+		else entry.count += 1;
+	}
+	if (matched < 10 || matched / lines.length < .8) return void 0;
+	return {
+		files,
+		total: matched
+	};
+}
+/** grep 预览：命中总数与每文件计数（最多列 30 个文件，其余显式说明）。 */
+function buildGrepSections(evidence) {
+	const ranked = [...evidence.files.entries()].sort((left, right) => right[1].count - left[1].count);
+	const shown = ranked.slice(0, 30);
+	const sections = [{ lines: [`matches: ${evidence.total} across ${ranked.length} files`] }, { lines: ["by file:", ...shown.map(([file, entry]) => `  ${clip(file, 120)}: ${entry.count}`)] }];
+	if (ranked.length > shown.length) sections.push({ lines: [`  … ${ranked.length - shown.length} more files (full list via ref)`] });
+	sections.push({
+		lines: ["first matches:", ...shown.slice(0, 8).map(([file, entry]) => `  ${clip(file, 80)}: ${clip(entry.first, 120)}`)],
+		optional: true
+	});
+	return sections;
+}
+/** glob 预览：总数 + 扩展名分布（必需），样本路径（可选）。 */
+function buildGlobSections(text) {
+	const paths = text.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+	const byExtension = /* @__PURE__ */ new Map();
+	for (const entry of paths) {
+		const dot = entry.lastIndexOf(".");
+		const extension = dot > Math.max(entry.lastIndexOf("/"), entry.lastIndexOf("\\")) ? entry.slice(dot).toLowerCase() : "(none)";
+		byExtension.set(extension, (byExtension.get(extension) ?? 0) + 1);
+	}
+	const top = [...byExtension.entries()].sort((left, right) => right[1] - left[1]).slice(0, 6);
+	const sample = paths.slice(0, 10).map((entry) => `  ${clip(entry, 140)}`);
+	if (paths.length > 10) sample.push(`  … ${paths.length - 10} more`);
+	return [
+		{ lines: [`paths: ${paths.length}`] },
+		{ lines: ["by extension:", ...top.map(([extension, count]) => `  ${extension}: ${count}`)] },
+		{
+			lines: ["sample:", ...sample],
+			optional: true
+		}
+	];
+}
+/** 结构化预览：行数与字段（必需），样本行（可选）。 */
+function buildStructuredSections(text) {
+	const parsed = parseStructuredResultRows(text);
+	if (parsed === void 0) return void 0;
+	const sample = parsed.rows.slice(0, 3).map((row) => `  ${clip(JSON.stringify(row), 240)}`);
+	return [{ lines: [`rows: ${parsed.rows.length}`, `fields: ${parsed.fields.join(", ")}`] }, {
+		lines: ["sample:", ...sample],
+		optional: true
+	}];
+}
+/** 契约/类型定义：命中两行以上声明就当它是契约，保持原样。 */
+function looksLikeContract(text) {
+	let declarations = 0;
+	for (const line of text.split("\n").slice(0, 800)) {
+		if (/^\s*(?:export\s+)?(?:declare\s+)?(?:interface|type)\s+[A-Za-z_$][\w$]*/.test(line)) declarations += 1;
+		if (declarations >= 2) return true;
+	}
+	return false;
+}
+/** 源码判定：代码行占比过半（或含多处 markdown 代码围栏）。 */
+function looksLikeSourceCode(text) {
+	let fences = 0;
+	for (const line of text.split("\n").slice(0, 600)) if (line.trim().startsWith("```")) fences += 1;
+	if (fences >= 4) return true;
+	let code = 0;
+	let nonEmpty = 0;
+	for (const raw of text.split("\n").slice(0, 600)) {
+		const trimmed = raw.trim();
+		if (trimmed === "") continue;
+		nonEmpty += 1;
+		if (/^(?:import|export|from|const|let|var|function|class|interface|type|enum|async|await|return|if|for|while|switch|case|break|continue|try|catch|finally|throw|new|public|private|protected|static|readonly|def|using|namespace|package|#include|#pragma)\b/.test(trimmed) || /^[})\];]/.test(trimmed) || /^(?:\/\/|\/\*|\*)/.test(trimmed)) code += 1;
+	}
+	return nonEmpty >= 10 && code / nonEmpty >= .45;
+}
+/** 完整 JSON 文档或被截断的 JSON 对象：可能是批量源码/混合证据，不按裸日志猜测。 */
+function isJsonDocument(text) {
+	const trimmed = text.trim();
+	if (trimmed.length < 2) return false;
+	const first = trimmed[0];
+	const last = trimmed[trimmed.length - 1];
+	if (first !== "{" && first !== "[") return false;
+	if (first === "{" && last === "}" || first === "[" && last === "]") try {
+		const value = JSON.parse(trimmed);
+		return typeof value === "object" && value !== null;
+	} catch {}
+	if (first === "{") {
+		let fields = 0;
+		for (const line of trimmed.split("\n").slice(0, 24)) if (/^\s*"[^"]+"\s*:/.test(line)) fields += 1;
+		return fields >= 2;
+	}
+	return false;
+}
+/**
+* 决定这一段文本该怎么处理。
+*
+* 顺序就是「可证明性」的顺序：子代理报告/源码工具/契约先被判成原样，
+* 然后是测试失败集、grep、结构化、glob、shell 这些有明确形状的，
+* 最后落到「无法解析 → 原样」。
+*/
+function planProjection(text, toolName) {
+	if (TOOL_SUBAGENT.test(toolName)) return {
+		kind: "verbatim",
+		strategy: "verbatim-subagent-report"
+	};
+	if (TOOL_SOURCE.test(toolName)) return {
+		kind: "verbatim",
+		strategy: "verbatim-source-code"
+	};
+	if (looksLikeContract(text)) return {
+		kind: "verbatim",
+		strategy: "verbatim-contract"
+	};
+	if (isJsonDocument(text)) return {
+		kind: "verbatim",
+		strategy: "verbatim-unparsed"
+	};
+	if (looksLikeSourceCode(text)) return {
+		kind: "verbatim",
+		strategy: "verbatim-source-code"
+	};
+	const test = extractTestEvidence(text);
+	if (test !== void 0) return {
+		kind: "preview",
+		strategy: "test-failure",
+		sections: buildTestSections(test)
+	};
+	const grep = extractGrepEvidence(text);
+	if (grep !== void 0) return {
+		kind: "preview",
+		strategy: "grep-results",
+		sections: buildGrepSections(grep)
+	};
+	const structured = buildStructuredSections(text);
+	if (structured !== void 0) return {
+		kind: "preview",
+		strategy: "structured-rows",
+		sections: structured
+	};
+	if (looksLikeGlobResult(text)) return {
+		kind: "preview",
+		strategy: "glob-results",
+		sections: buildGlobSections(text)
+	};
+	if (looksLikeShellOutput(text)) {
+		const sections = buildShellSections(text);
+		if (sections === void 0) return {
+			kind: "verbatim",
+			strategy: "verbatim-unparsed"
+		};
+		return {
+			kind: "preview",
+			strategy: "shell-output",
+			sections
+		};
+	}
+	return {
+		kind: "verbatim",
+		strategy: "verbatim-unparsed"
+	};
+}
+/** 预览尾部：把「怎么读全文」写死在预览里，模型不用猜。 */
+function footerFor(refId) {
+	return `[full result: ${refId} · page with offset/limit(default 64 lines)/maxBytes(default 16384 bytes)]`;
+}
+/**
+* 核心决策：预算 → 计划 → 装配 → 入库。
+*
+* 入库放在最后：预览装不进预算就不写文件，也不会留下一条没人引用的引用。
+* 入库失败一律降级为「保持原样」—— 没有 ref 的预览等于把原文丢了。
+*/
+async function decide(args) {
+	const { text, input, budget } = args;
+	if (text.length <= budget.maxChars) return { reason: "verbatim-small" };
+	const plan = planProjection(text, input.toolName);
+	if (plan.kind === "verbatim") return { reason: plan.strategy };
+	if (input.isError === true && plan.strategy !== "test-failure" && plan.strategy !== "shell-output") return { reason: "verbatim-unparsed" };
+	const header = `[cache-warmup preview] strategy=${plan.strategy} input=${text.length}ch`;
+	const footerBudget = footerFor(`ref://${input.sessionId}/${"0".repeat(64)}`).length;
+	const bodyBudget = budget.maxChars - header.length - footerBudget - 2;
+	if (bodyBudget <= 0) return { reason: "verbatim-budget" };
+	const body = fitSections(plan.sections, bodyBudget);
+	if (body === void 0) return { reason: "verbatim-budget" };
+	const store = input.store;
+	if (store === void 0) return { reason: "store-unavailable" };
+	let reference;
+	try {
+		reference = await store.put({
+			sessionId: input.sessionId,
+			content: text,
+			toolName: input.toolName,
+			at: args.at
+		});
+	} catch {
+		return { reason: "store-unavailable" };
+	}
+	const preview = `${header}\n${body}\n${footerFor(reference.refId)}`;
+	if (preview.length > budget.maxChars) return { reason: "verbatim-budget" };
+	return {
+		preview,
+		refId: reference.refId,
+		strategy: plan.strategy
+	};
+}
+/** 块数组里文本字符数的合计。 */
+function textCharsOf(blocks) {
+	let total = 0;
+	for (const block of blocks) if (typeof block.text === "string") total += block.text.length;
+	return total;
+}
+/**
+* 投影一条工具结果。
+*
+* 纯函数式语义：不改入参、不写日志、不碰历史；返回新内容 + 度量。
+* 只有 `changed: true` 时才有 `refId`/`preview`。
+* @param input - 工具结果与预算。
+* @returns 投影结果。
+*/
+async function projectToolResult(input) {
+	const at = input.at ?? Date.now();
+	const budget = input.budget ?? cacheWarmupBudget(input.sessionId);
+	const base = {
+		toolName: input.toolName,
+		sessionId: input.sessionId,
+		provider: input.provider,
+		at
+	};
+	if (typeof input.content === "string") {
+		const text = input.content;
+		const decision = await decide({
+			text,
+			input,
+			budget,
+			at
+		});
+		if ("reason" in decision) return {
+			...base,
+			content: input.content,
+			changed: false,
+			metrics: {
+				inputChars: text.length,
+				outputChars: text.length,
+				omittedChars: 0,
+				strategy: decision.reason
+			}
+		};
+		return {
+			...base,
+			content: decision.preview,
+			changed: true,
+			refId: decision.refId,
+			preview: decision.preview,
+			metrics: {
+				inputChars: text.length,
+				outputChars: decision.preview.length,
+				omittedChars: Math.max(0, text.length - decision.preview.length),
+				strategy: decision.strategy
+			}
+		};
+	}
+	const blocks = input.content;
+	if (!(blocks.length === 1 && blocks[0]?.type === "text" && typeof blocks[0]?.text === "string")) {
+		const chars = textCharsOf(blocks);
+		const hasNonText = blocks.some((block) => block.type !== "text");
+		return {
+			...base,
+			content: input.content,
+			changed: false,
+			metrics: {
+				inputChars: chars,
+				outputChars: chars,
+				omittedChars: 0,
+				strategy: hasNonText ? "verbatim-non-text" : "verbatim-unparsed"
+			}
+		};
+	}
+	const text = blocks[0].text;
+	const decision = await decide({
+		text,
+		input,
+		budget,
+		at
+	});
+	if ("reason" in decision) return {
+		...base,
+		content: input.content,
+		changed: false,
+		metrics: {
+			inputChars: text.length,
+			outputChars: text.length,
+			omittedChars: 0,
+			strategy: decision.reason
+		}
+	};
+	const rebuilt = {
+		...blocks[0],
+		text: decision.preview
+	};
+	return {
+		...base,
+		content: [rebuilt],
+		changed: true,
+		refId: decision.refId,
+		preview: decision.preview,
+		metrics: {
+			inputChars: text.length,
+			outputChars: decision.preview.length,
+			omittedChars: Math.max(0, text.length - decision.preview.length),
+			strategy: decision.strategy
+		}
+	};
+}
+//#endregion
 //#region src/host/common/request-images.ts
 function isRecord$41(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -31526,6 +32860,15 @@ function noteSessionCacheState(sessionId, state) {
 		...lastDrift === void 0 ? {} : { lastDrift },
 		updatedAt: now
 	});
+	recordCacheWarmupUsage({
+		sessionId,
+		inputTokens: state.inputTokens,
+		cacheReadTokens: state.cacheReadTokens,
+		outputTokens: state.outputTokens,
+		totalTokens: state.cacheReadTokens + state.inputTokens,
+		at: now,
+		...lastDrift === void 0 ? {} : { driftCause: lastDrift }
+	});
 }
 var KimiCodeAdapter = class extends LlmAdapter {
 	store;
@@ -53701,7 +55044,7 @@ function withTimeout$3(signal, ms) {
 	return signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
 }
 /** 一句可以直接展示给用户的失败原因；正文只截前 200 字，且不含任何请求头。 */
-function failure(detail) {
+function failure$1(detail) {
 	return "GLM（ZCode 账号） " + detail;
 }
 /** 响应正文的一句话摘要（去换行、截断），用于把上游原因带给调用方。 */
@@ -53728,7 +55071,7 @@ function glmOpenAiProbeHeaders(codingPlanKey) {
 */
 function quotaRequestHeaders$1(codingPlanKey) {
 	const key = codingPlanKey.trim();
-	if (key === "") throw new Error(failure("的配额接口需要一把 Coding Plan Key（裸值，不加 Bearer）；空凭据不会变成一个能通过鉴权的请求。"));
+	if (key === "") throw new Error(failure$1("的配额接口需要一把 Coding Plan Key（裸值，不加 Bearer）；空凭据不会变成一个能通过鉴权的请求。"));
 	return {
 		"content-type": "application/json",
 		accept: "application/json",
@@ -53810,13 +55153,13 @@ async function fetchCatalog(region, codingPlanKey, options = {}) {
 	const text = await response.text().catch(() => "");
 	if (!response.ok) {
 		const detail = summarize(text);
-		throw new Error(failure("读取模型目录失败（HTTP " + response.status + "）: " + url) + (detail === "" ? "" : "：" + detail));
+		throw new Error(failure$1("读取模型目录失败（HTTP " + response.status + "）: " + url) + (detail === "" ? "" : "：" + detail));
 	}
 	let payload;
 	try {
 		payload = JSON.parse(text);
 	} catch {
-		throw new Error(failure("返回的模型目录不是可读的 JSON：" + url));
+		throw new Error(failure$1("返回的模型目录不是可读的 JSON：" + url));
 	}
 	return parseCatalogListing(payload, region);
 }
@@ -54071,7 +55414,7 @@ async function fetchSubscriptionPlan(region, codingPlanKey, options = {}) {
 *   所以它同步抛出，与「上游读失败返回 `error`」那条路径分开。
 */
 async function fetchGlmQuota(region, codingPlanKey, options = {}) {
-	if (codingPlanKey.trim() === "") throw new Error(failure("的配额读取需要一把 Coding Plan Key（裸值，不加 Bearer）。"));
+	if (codingPlanKey.trim() === "") throw new Error(failure$1("的配额读取需要一把 Coding Plan Key（裸值，不加 Bearer）。"));
 	const accountId = options.accountId;
 	const cached = quotaEntryFor(accountId);
 	if (options.force !== true && cached !== null && Date.now() - cached.at < 12e4) return {
@@ -54097,7 +55440,7 @@ async function fetchGlmQuota(region, codingPlanKey, options = {}) {
 		} catch (error) {
 			return {
 				snapshot: null,
-				error: failure("配额接口不可达：" + (error instanceof Error ? error.message : String(error))),
+				error: failure$1("配额接口不可达：" + (error instanceof Error ? error.message : String(error))),
 				fromCache: false
 			};
 		}
@@ -54106,7 +55449,7 @@ async function fetchGlmQuota(region, codingPlanKey, options = {}) {
 			const detail = summarize(text);
 			return {
 				snapshot: null,
-				error: failure("配额查询失败（HTTP " + response.status + "）") + (detail === "" ? "" : "：" + detail),
+				error: failure$1("配额查询失败（HTTP " + response.status + "）") + (detail === "" ? "" : "：" + detail),
 				fromCache: false
 			};
 		}
@@ -54116,7 +55459,7 @@ async function fetchGlmQuota(region, codingPlanKey, options = {}) {
 		} catch {
 			return {
 				snapshot: null,
-				error: failure("配额查询返回的不是 JSON。"),
+				error: failure$1("配额查询返回的不是 JSON。"),
 				fromCache: false
 			};
 		}
@@ -54129,7 +55472,7 @@ async function fetchGlmQuota(region, codingPlanKey, options = {}) {
 		});
 		if (snapshot === null) return {
 			snapshot: null,
-			error: failure("上游没有返回可显示的额度窗口。"),
+			error: failure$1("上游没有返回可显示的额度窗口。"),
 			fromCache: false
 		};
 		return {
@@ -80962,6 +82305,751 @@ function releaseListener(handle) {
 	handle?.dispose?.();
 }
 //#endregion
+//#region src/host/cache-warmup/logging.ts
+/**
+* 把一条事件序列化成日志行。
+*
+* 形状写死在这里，而不是让调用方自己拼字符串：任何一次「顺手把 content 也带进
+* 去」的改动都只会发生在这个函数里，而它有测试盯着（断言日志里不含原文）。
+* 值为 `undefined` 的字段直接不出现在行里，保持每一行只描述它确实测到的指标。
+* @param event - 指标事件。
+* @returns 一行日志文本（带上本模块前缀）。
+*/
+function formatCacheWarmupLog(event) {
+	const record = {};
+	for (const [key, value] of Object.entries(event)) if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") record[key] = value;
+	return "[cache-warmup] " + JSON.stringify(record);
+}
+/**
+* 把一个异常压成**稳定的身份标签**，只用于宿主日志。
+*
+* 只取两样东西：`name`（构造器名；缺失或不是非空字符串时退成 `'Error'`）和
+* `code`（有就带上——`CacheWarmupStoreError` 与 Node 的系统错误都靠它区分）。
+*
+* **`message` 一律不进日志**，这是本函数存在的全部理由：异常消息里常常带着绝对
+* 路径、命令行片段、凭据，或者被读取结果的一段原文。一条日志就够把原文复制一份，
+* 或者把主机的目录结构写进部署方的日志管道。想知道"哪一类错误、来自哪一层"，
+* name/code 就够了；想知道"具体哪一条",该去会话本身看，不该从日志里捞。
+* @param error - 捕获到的任意值。
+* @returns 形如 `Error`、`RangeError`、`CacheWarmupStoreError/SESSION_MISMATCH`
+*   的标签（`code` 是非空字符串时以 `/` 连接）。
+*/
+function cacheWarmupErrorLabel(error) {
+	if (typeof error !== "object" || error === null) return "Error";
+	const record = error;
+	const name = typeof record.name === "string" && record.name !== "" ? record.name : "Error";
+	const code = typeof record.code === "string" && record.code !== "" ? record.code : void 0;
+	return code === void 0 ? name : name + "/" + code;
+}
+/**
+* 发一条指标日志。
+*
+* logger 缺席时**安静跳过**：日志不是功能，装不上日志服务的宿主不该因此装不上
+* 这个模块。写入失败同样吞掉——一条日志把工具调用搞挂是最不划算的失败。
+* @param logger - 宿主 logger（可选）。
+* @param event - 指标事件。
+* @returns 写出的那一行（调用方/测试可以拿去断言）；没写出去时 undefined。
+*/
+function logCacheWarmup(logger, event) {
+	const line = formatCacheWarmupLog(event);
+	const info = logger?.info;
+	if (typeof info !== "function") return void 0;
+	try {
+		info.call(logger, line);
+	} catch {
+		return;
+	}
+	return line;
+}
+//#endregion
+//#region src/host/cache-warmup/result-tool.ts
+/** 注册的工具名。冻结契约的一部分，不要改动。 */
+const CACHE_WARMUP_RESULT_TOOL = "cache_warmup_result";
+/** 是不是一个可用的非负整数。 */
+function isCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+/** 读一个未知值为有限数字（`null` 不算：契约用 `null` 表示"没有下一页"）。 */
+function numberOf$1(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+/** 读一个未知值为布尔。 */
+function booleanOf$1(value) {
+	return typeof value === "boolean" ? value : void 0;
+}
+/** 读一个未知值为非空字符串。 */
+function stringOf$1(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/**
+* 从存储交回来的 `omitted` 里读出省略字符数。
+*
+* 契约给的是一个结构化对象（`{ reason, chars, lines, rows, bytes }`，`reason: 'none'`
+* 表示这一页就是全部）；这里同时容忍一个裸数字，因为"省略了多少字符"是唯一
+* 模型真正需要的那个数，而形状变化不该让整页读取失败。
+* @param value - 存储返回的 `omitted`。
+* @returns 省略的字符数；读不到时 undefined。
+*/
+function omittedCharsOf(value) {
+	const direct = numberOf$1(value);
+	if (direct !== void 0) return direct;
+	if (typeof value !== "object" || value === null) return void 0;
+	return numberOf$1(value.chars);
+}
+/**
+* 造一个失败值。
+* @param action - 回显的动作。
+* @param refId - 被拒绝的引用。
+* @param sessionId - 当前会话（拿不到时为空串）。
+* @param code - 稳定错误码。
+* @param message - 一句话说明。
+* @returns 规范值。
+*/
+function failure(action, refId, sessionId, code, message) {
+	return {
+		ok: false,
+		action,
+		refId,
+		sessionId,
+		error: {
+			code,
+			message
+		}
+	};
+}
+/**
+* 把未知异常压成一句不含原文的话。
+*
+* 异常消息里可能带着被读取内容的片段（解析错误最常见），所以只取消息的第一行，
+* 长度也截断——工具输出不该成为原文的第二条出口。
+* @param error - 捕获到的值。
+* @returns 一句话描述。
+*/
+function describe(error) {
+	const firstLine = (error instanceof Error ? error.message : String(error)).split("\n", 1)[0] ?? "";
+	return firstLine.length > 160 ? firstLine.slice(0, 157) + "..." : firstLine;
+}
+/**
+* 取结构化错误码：存储自己的码优先，否则用本工具给的兜底码。
+* @param error - 捕获到的值。
+* @param fallback - 兜底码。
+* @returns 错误码。
+*/
+function errorCodeOf(error, fallback) {
+	const code = error?.code;
+	return typeof code === "string" && code !== "" ? code : fallback;
+}
+/**
+* 把共享存储交回来的页读成规范值。
+*
+* 字段一律按「读得到就用、读不到就不出现」处理：核心侧多给字段不会让这里报错，
+* 少给字段也不会伪造一个 `complete:true`——「不确定是否读完」必须表现成
+* `complete:false`，把 partial 伪装成完整是这条路线上最贵的一种错。
+* @param raw - 存储的返回值（`ResultPage`，按共享约定结构化读取）。
+* @param refId - 引用。
+* @param sessionId - 会话。
+* @returns 规范值。
+*/
+function pageValue(raw, refId, sessionId) {
+	const page = typeof raw === "object" && raw !== null ? raw : {};
+	const text = stringOf$1(page.content) ?? stringOf$1(page.text);
+	const complete = booleanOf$1(page.complete) === true;
+	const offset = numberOf$1(page.offset);
+	const nextOffset = complete ? void 0 : numberOf$1(page.nextOffset);
+	const omitted = omittedCharsOf(page.omitted);
+	const totalChars = numberOf$1(page.totalChars);
+	return {
+		ok: true,
+		action: "page",
+		refId,
+		sessionId,
+		complete,
+		...offset === void 0 ? {} : { offset },
+		...nextOffset === void 0 ? {} : { nextOffset },
+		...omitted === void 0 ? {} : { omitted },
+		...totalChars === void 0 ? {} : { totalChars },
+		...text === void 0 ? {} : {
+			text,
+			chars: text.length
+		}
+	};
+}
+/**
+* 造 `cache_warmup_result` 工具。
+* @param deps - 依赖：线路校验、存储读取、指标日志。
+* @returns 可注册的工具定义。
+*/
+function createCacheWarmupResultTool(deps) {
+	/** 发一条日志；安装方没接线时什么也不做。 */
+	const log = (event) => {
+		try {
+			deps.log?.(event);
+		} catch {}
+	};
+	return defineTool({
+		name: CACHE_WARMUP_RESULT_TOOL,
+		description: [
+			"Read back a result that was replaced by a preview, using the `ref://<session>/<sha256>` handle written in that preview.",
+			"Use `action: \"page\"` to read a slice: pass `offset`, and optionally `limit`, `maxBytes`, `fields` and `equals`.",
+			"Every page reports `complete`, `nextOffset`, `omitted` and `totalChars`, so you can see whether more remains instead of assuming a slice is the whole thing.",
+			"Use `action: \"release\"` when the stored copy is no longer needed."
+		].join(" "),
+		parameters: {
+			action: {
+				type: "string",
+				required: true,
+				description: "page reads a slice of the stored result; release drops the stored copy.",
+				enum: ["page", "release"]
+			},
+			refId: {
+				type: "string",
+				required: true,
+				description: "The `ref://<session>/<sha256>` handle exactly as written in the preview."
+			},
+			offset: {
+				type: "integer",
+				description: "Where to start: a UTF-8 byte offset for text results, a row index for structured ones."
+			},
+			limit: {
+				type: "integer",
+				description: "Maximum number of rows for a structured result."
+			},
+			maxBytes: {
+				type: "integer",
+				description: "Byte budget for this page; the store returns less when the budget is smaller."
+			},
+			fields: {
+				type: "array",
+				items: { type: "string" },
+				description: "Restrict a structured result to these fields."
+			},
+			equals: {
+				type: "object",
+				additionalProperties: true,
+				description: "Keep only structured rows whose named field equals the given string."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: {
+						type: "boolean",
+						description: "Whether the call succeeded."
+					},
+					action: {
+						type: "string",
+						enum: ["page", "release"],
+						description: "The action that ran."
+					},
+					refId: {
+						type: "string",
+						description: "The handle this call addressed."
+					},
+					sessionId: {
+						type: "string",
+						description: "The session that owns the handle."
+					},
+					complete: {
+						type: "boolean",
+						description: "Whether this page reached the end of the stored result."
+					},
+					offset: {
+						type: "number",
+						description: "Where this page actually started."
+					},
+					nextOffset: {
+						type: "number",
+						description: "Where the next page should start."
+					},
+					omitted: {
+						type: "number",
+						description: "Characters still not returned after this page."
+					},
+					chars: {
+						type: "number",
+						description: "Characters in this page."
+					},
+					totalChars: {
+						type: "number",
+						description: "Characters in the whole stored result."
+					},
+					released: {
+						type: "boolean",
+						description: "Whether a stored copy was actually released."
+					},
+					text: {
+						type: "string",
+						description: "This page of the stored result."
+					},
+					error: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							code: {
+								type: "string",
+								description: "Stable error code."
+							},
+							message: {
+								type: "string",
+								description: "One-line explanation."
+							}
+						}
+					}
+				}
+			},
+			render(_args, value) {
+				if (value.ok !== true) {
+					const code = value.error?.code ?? "FAILED";
+					const message = value.error?.message ?? "the request was refused";
+					return [{
+						type: "text",
+						text: "cache_warmup_result " + value.action + " refused (" + code + "): " + message
+					}];
+				}
+				if (value.action === "release") return [{
+					type: "text",
+					text: value.released === true ? "Released " + value.refId + ". The preview in your history is unchanged; it can no longer be read back." : "Nothing stored for " + value.refId + "; nothing to release."
+				}];
+				const at = value.offset ?? 0;
+				const span = typeof value.chars === "number" ? value.chars + " chars" : "no content";
+				const total = typeof value.totalChars === "number" ? " of " + value.totalChars : "";
+				const tail = value.complete === true ? "complete" : "more remains" + (typeof value.nextOffset === "number" ? ", continue at offset " + value.nextOffset : "") + (typeof value.omitted === "number" ? ", " + value.omitted + " chars omitted" : "");
+				const body = typeof value.text === "string" && value.text !== "" ? value.text : "(empty page)";
+				return [{
+					type: "text",
+					text: value.refId + " from offset " + at + " — " + span + total + ", " + tail + "\n\n" + body
+				}];
+			}
+		},
+		async execute(args, exec) {
+			const route = deps.routeOf(exec);
+			const refId = args.refId;
+			const action = args.action;
+			if (route.provider !== deps.provider) return failure(action, refId, route.sessionId ?? "", "WRONG_PROVIDER", "ref handles belong to the " + deps.provider + " line; this session is routed to \"" + (route.provider ?? "unknown") + "\"");
+			const sessionId = route.sessionId;
+			if (sessionId === void 0) return failure(action, refId, "", "NO_SESSION", "the current session could not be resolved, so the handle cannot be checked");
+			const store = deps.store();
+			if (store === void 0) return failure(action, refId, sessionId, "NO_STORE", "the result store is unavailable on this host");
+			if (action === "release") {
+				let released = false;
+				try {
+					const raw = await store.release({
+						sessionId,
+						refId
+					});
+					released = booleanOf$1(raw) ?? booleanOf$1(raw?.released) ?? false;
+				} catch (error) {
+					return failure(action, refId, sessionId, errorCodeOf(error, "STORE_FAILED"), "releasing the stored copy failed: " + describe(error));
+				}
+				log({
+					event: "ref-release",
+					session: sessionId,
+					refId,
+					released
+				});
+				return {
+					ok: true,
+					action,
+					refId,
+					sessionId,
+					released
+				};
+			}
+			for (const [name, value] of [
+				["offset", args.offset],
+				["limit", args.limit],
+				["maxBytes", args.maxBytes]
+			]) if (value !== void 0 && !isCount(value)) return failure(action, refId, sessionId, "BAD_ARGUMENT", name + " must be a non-negative integer");
+			const request = {
+				sessionId,
+				refId
+			};
+			if (args.offset !== void 0) request.offset = args.offset;
+			if (args.limit !== void 0) request.limit = args.limit;
+			if (args.maxBytes !== void 0) request.maxBytes = args.maxBytes;
+			if (args.fields !== void 0) request.fields = args.fields;
+			if (args.equals !== void 0) request.equals = args.equals;
+			let raw;
+			try {
+				raw = await store.page(request);
+			} catch (error) {
+				return failure(action, refId, sessionId, errorCodeOf(error, "STORE_FAILED"), "reading the stored copy failed: " + describe(error));
+			}
+			const value = pageValue(raw, refId, sessionId);
+			log({
+				event: "ref-page",
+				session: sessionId,
+				refId,
+				offset: value.offset ?? args.offset ?? 0,
+				returnedChars: value.chars ?? 0,
+				complete: value.complete === true,
+				...value.nextOffset === void 0 ? {} : { nextOffset: value.nextOffset }
+			});
+			return value;
+		}
+	});
+}
+//#endregion
+//#region src/host/cache-warmup/install.ts
+/**
+* 本模块服务的线路。
+*
+* 结果投影的正确性依赖这条线路的缓存语义（内容前缀命中），别的线路上把结果换成
+* 预览只有坏处没有好处，所以这里写死一个 provider 名而不是做成开关。
+*/
+const CACHE_WARMUP_PROVIDER = "kimi-code";
+/** 提示词分节名，全局唯一（重复注册会抛错）。 */
+const CACHE_WARMUP_SECTION_NAME = "plugin:cache-warmup";
+/**
+* 一段**恒定**的引导词：告诉模型预览是什么、怎么补读。
+*
+* 文本与开关无关，这是刻意的——系统提示是缓存前缀的第一段，会话中途改一个字就
+* 让整段前缀失效、整段重新计费。开关的语义只交给 post-execute 与工具。
+*/
+const CACHE_WARMUP_GUIDANCE = [
+	"## Result previews",
+	"",
+	"On large `run_code` results this line may replace the output with a preview: a short description plus one or more `ref://<session>/<sha256>` handles.",
+	"",
+	"- A preview is **not** the full result. It states `complete`, `omitted` and `nextOffset` explicitly; treat an incomplete preview as incomplete data, not as the whole output.",
+	"- To read the original, call `cache_warmup_result` with `action: \"page\"` and that `refId`, then follow `nextOffset` until `complete` is true.",
+	"- `action: \"release\"` drops the stored copy. The preview already in the conversation stays identical; it simply can no longer be read back.",
+	"- Source code, type and contract definitions, mixed evidence and anything that could not be parsed reliably are never replaced: they arrive in full."
+].join("\n");
+/**
+* 静态引导词的文本提供者。
+* @returns 一个永远返回同一段文本的函数（系统提示的稳定前缀）。
+*/
+function cacheWarmupSectionText() {
+	return () => CACHE_WARMUP_GUIDANCE;
+}
+/**
+* 读一次工具调用所属的线路。
+*
+* provider 先问会话的 request header（那是本轮请求真正走的那条线），再退回
+* agent 自己的 options。两处都没有就返回空对象——调用方据此放手，而不是猜一个。
+* @param agent - 事件里的调用方 agent。
+* @returns 线路信息；读不到的字段省略。
+*/
+function cacheWarmupRouteOf(agent) {
+	const record = typeof agent === "object" && agent !== null ? agent : void 0;
+	const session = record?.session;
+	let provider;
+	try {
+		provider = stringOf(session?.requestHeader?.()?.config?.provider);
+	} catch {
+		provider = void 0;
+	}
+	if (provider === void 0) provider = stringOf(record?.options?.provider);
+	const sessionId = stringOf(session?.header?.id) ?? stringOf(record?.id);
+	return {
+		...provider === void 0 ? {} : { provider },
+		...sessionId === void 0 ? {} : { sessionId }
+	};
+}
+/**
+* 预热窗口结束时，本次算「稳住了」还是「掉了」。
+*
+* 阈值取核心契约里的 `consecutiveHitsRequired`（连续高命中率报告条数），而不是在
+* 这里另编一个命中率——判定标准只有核心一份，日志只如实记录它当时的结论。
+* @param consecutiveHits - 退出时的连续命中条数；读不到时 undefined。
+* @returns 稳定的退出原因。
+*/
+function exitReasonOf(consecutiveHits) {
+	return consecutiveHits !== void 0 && consecutiveHits >= CACHE_WARMUP_DEFAULTS.consecutiveHitsRequired ? "settled" : "dropped";
+}
+/** 单实例登记表，走一个 global symbol（与进展更新模块共用一个表）。 */
+const MOUNTED = Symbol.for("dsh-chatgpt-subscription.mounted-modules");
+/** 本模块在登记表里的名字。 */
+const MODULE_ID = "cache-warmup";
+/**
+* 读一个未知值为非空字符串。
+* @param value - 候选值。
+* @returns 非空字符串，其它类型的 undefined。
+*/
+function stringOf(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/**
+* 读一个未知值为有限数字。
+* @param value - 候选值。
+* @returns 有限数字，其它类型的 undefined。
+*/
+function numberOf(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+/**
+* 读一个未知值为布尔。
+* @param value - 候选值。
+* @returns 布尔，其它类型的 undefined。
+*/
+function booleanOf(value) {
+	return typeof value === "boolean" ? value : void 0;
+}
+/**
+* 单实例守卫：本模块已挂载时放弃本次安装。
+* @param ctx - 宿主上下文。
+* @returns 释放函数（交出挂载权）；已经挂载过时返回 undefined。
+*/
+function claimMount(ctx) {
+	const registry = globalThis;
+	const existing = registry[MOUNTED];
+	const mounted = existing instanceof Set ? existing : /* @__PURE__ */ new Set();
+	if (existing !== mounted) registry[MOUNTED] = mounted;
+	if (mounted.has(MODULE_ID)) return void 0;
+	mounted.add(MODULE_ID);
+	const release = () => {
+		mounted.delete(MODULE_ID);
+	};
+	if (typeof ctx.effect === "function") ctx.effect(() => release, "dsh-chatgpt-subscription: cache warmup mount");
+	return release;
+}
+/**
+* 读一次会话级指标快照。
+*
+* 形状按共享约定**结构化**推断，任何字段缺失都不影响日志；读不出来就返回
+* undefined，让调用方退回预算对象上的那一份。
+* @param sessionId - 会话标识。
+* @returns 快照，或读不到时的 undefined。
+*/
+function readCacheWarmupSnapshot(sessionId) {
+	try {
+		const raw = cacheWarmupSnapshot(sessionId);
+		return typeof raw === "object" && raw !== null ? raw : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* 挂载「缓存预热」的宿主半边。
+* @param ctx - 宿主插件上下文。
+* @param options - 挂载选项（设置读取器、可选的存储工厂）。
+* @returns 卸载函数；重复挂载时返回一个空操作。
+*/
+function installCacheWarmup(ctx, options) {
+	const release = claimMount(ctx);
+	if (release === void 0) return () => void 0;
+	/** 每次调用重新读服务：宿主树可能在本模块挂载之后才 settle，读一次存下来会漏。 */
+	const serviceOf = (name) => {
+		const read = ctx.get;
+		if (typeof read !== "function") return void 0;
+		try {
+			return read.call(ctx, name);
+		} catch {
+			return;
+		}
+	};
+	/** 登记一个副作用；上下文没有 effect 时立即执行（测试用假上下文）。 */
+	const track = (execute, label) => {
+		if (typeof ctx.effect === "function") ctx.effect(execute, label);
+		else execute();
+	};
+	/** 日志出口（每次现读，logger 可能晚于本模块挂载）。 */
+	const loggerOf = () => ctx.logger ?? serviceOf("logger");
+	/** 发一条指标日志。 */
+	const log = (event) => {
+		logCacheWarmup(loggerOf(), event);
+	};
+	/** 惰性构造出来的存储（注入优先）。 */
+	let ownedStore;
+	/**
+	* 取结果引用存储。
+	*
+	* 构造失败只意味着「这台主机上没有引用存储」：此时投影不生效（原样返回），
+	* `cache_warmup_result` 返回结构化错误。都不是一次安装失败。
+	* @returns 存储，或拿不到时的 undefined。
+	*/
+	const storeOf = () => {
+		if (options.store !== void 0) try {
+			return options.store();
+		} catch (error) {
+			loggerOf()?.warn?.("[dsh-chatgpt-subscription] cache warmup store injection failed: " + cacheWarmupErrorLabel(error));
+			return;
+		}
+		if (ownedStore !== void 0) return ownedStore;
+		try {
+			ownedStore = new FileResultReferenceStore();
+		} catch (error) {
+			loggerOf()?.warn?.("[dsh-chatgpt-subscription] cache warmup store unavailable: " + cacheWarmupErrorLabel(error));
+			return;
+		}
+		return ownedStore;
+	};
+	track(() => {
+		const tools = serviceOf("tools");
+		if (tools === void 0) return () => void 0;
+		return tools.register(createCacheWarmupResultTool({
+			provider: CACHE_WARMUP_PROVIDER,
+			routeOf: (exec) => cacheWarmupRouteOf(exec?.agent),
+			store: storeOf,
+			log
+		}));
+	}, "dsh-chatgpt-subscription: cache warmup result tool");
+	track(() => {
+		const systemPrompt = serviceOf("systemPrompt");
+		if (systemPrompt === void 0) return () => void 0;
+		return systemPrompt.section({
+			name: CACHE_WARMUP_SECTION_NAME,
+			order: 225,
+			text: cacheWarmupSectionText()
+		});
+	}, "dsh-chatgpt-subscription: cache warmup prompt section");
+	/** 上一轮看到的预热状态，用来在窗口结束时发一条 `warmup-exit`。 */
+	const warmupState = /* @__PURE__ */ new Map();
+	/**
+	* 记账并（必要时）发一条 `warmup-exit`。
+	* @param sessionId - 会话标识。
+	* @param budget - 本轮读到的预算对象。
+	*/
+	const trackWarmup = (sessionId, budget) => {
+		const snapshot = readCacheWarmupSnapshot(sessionId);
+		const warmup = booleanOf(snapshot?.warmup) ?? booleanOf(budget.warmup);
+		const consecutiveHits = numberOf(snapshot?.consecutiveHits) ?? numberOf(budget.consecutiveHits);
+		const hitRatio = numberOf(snapshot?.hitRatio) ?? numberOf(budget.hitRatio);
+		if (warmupState.get(sessionId) === true && warmup === false) {
+			const reason = exitReasonOf(consecutiveHits);
+			log({
+				event: "warmup-exit",
+				session: sessionId,
+				reason,
+				...consecutiveHits === void 0 ? {} : { consecutiveHits },
+				...hitRatio === void 0 ? {} : { hitRatio }
+			});
+		}
+		if (warmup !== void 0) warmupState.set(sessionId, warmup);
+		return {
+			...warmup === void 0 ? {} : { warmup },
+			...consecutiveHits === void 0 ? {} : { consecutiveHits },
+			...hitRatio === void 0 ? {} : { hitRatio }
+		};
+	};
+	/**
+	* 一次工具结果的投影。
+	*
+	* 决策取舍写在代码里，因为它全是「什么时候**不动**」：
+	* - 不是 `accept`（`block` 的 feedback 是别人的东西）；
+	* - 已经带 `value`（执行本地的 canonical 值，replay 与结构化消费方读它，
+	*   替换掉等于把一份 JSON 换成字符串）；
+	* - 工具名不是 `run_code`、线路不是本线、会话拿不到；
+	* - 没有存储、内容为空。
+	* 上面任何一条成立就原样返回同一个决策对象。
+	* @param exec - 工具执行上下文。
+	* @param result - 归一化后的执行结果。
+	* @param decision - `next()` 交回来的决策。
+	* @returns 投影后的决策（形状不变），或原决策。
+	*/
+	const projectDecision = async (exec, result, decision) => {
+		if (decision.kind !== "accept") return decision;
+		if (decision.value !== void 0) return decision;
+		if (exec.name !== "run_code") return decision;
+		if (!options.settings().enabled) return decision;
+		const route = cacheWarmupRouteOf(exec.agent);
+		if (route.provider !== "kimi-code") return decision;
+		const sessionId = route.sessionId;
+		if (sessionId === void 0) return decision;
+		const store = storeOf();
+		if (store === void 0) return decision;
+		const blocks = decision.content ?? result.content;
+		if (blocks.length === 0) return decision;
+		const content = blocks;
+		const budget = cacheWarmupBudget(sessionId);
+		const projected = await projectToolResult({
+			toolName: exec.name,
+			provider: route.provider,
+			sessionId,
+			content,
+			isError: result.isError === true,
+			budget,
+			store
+		}).catch((error) => {
+			loggerOf()?.warn?.("[dsh-chatgpt-subscription] cache warmup projection skipped: " + cacheWarmupErrorLabel(error));
+		});
+		if (projected === void 0) return decision;
+		const metrics = trackWarmup(sessionId, budget);
+		log({
+			event: "projection",
+			session: sessionId,
+			strategy: String(projected.metrics.strategy),
+			changed: projected.changed === true,
+			inputChars: projected.metrics.inputChars,
+			outputChars: projected.metrics.outputChars,
+			omittedChars: projected.metrics.omittedChars,
+			...metrics.warmup === void 0 ? {} : { warmup: metrics.warmup }
+		});
+		if (projected.changed !== true) return decision;
+		return {
+			kind: "accept",
+			content: blocksOf(projected.content),
+			...decision.additionalContexts === void 0 ? {} : { additionalContexts: decision.additionalContexts }
+		};
+	};
+	const disposeListener = ctx.on?.("tools/post-execute", (async (exec, result, next) => {
+		const decision = await next();
+		return projectDecision(exec, result, decision);
+	}));
+	return () => {
+		disposeListener?.();
+		warmupState.clear();
+		release();
+	};
+}
+/**
+* 把投影结果的内容转回宿主的内容块数组。
+*
+* 核心的 `ProjectionResult.content` 允许纯文本（预览就是一段文本），也允许块数组
+* （只替换了其中一个文本块，非文本块原样保留）。宿主的 `PostToolDecision.content`
+* 只认块数组，所以纯文本在这里包成一个 text 块——包一层，不改字。
+* @param content - 核心交回来的内容。
+* @returns 宿主的块数组。
+*/
+function blocksOf(content) {
+	if (typeof content === "string") return [{
+		type: "text",
+		text: content
+	}];
+	return content;
+}
+/**
+* 本文件刻意**不保留**任何"把异常压成一句话"的辅助函数。
+*
+* 这里曾经有一个 `describe(error)`，把 `error.message` 截断后拼进宿主日志。它看上去
+* 无害（只取第一行、还截了长度），实际上是一条原文出口：异常消息里常常带着绝对
+* 路径、命令行片段、凭据，或者被读取结果的一段正文。三处降级日志现在统一走
+* {@link cacheWarmupErrorLabel}——只输出稳定的 name/code。
+*/
+//#endregion
+//#region src/host/cache-warmup/settings.ts
+/**
+* 设置卡上这一行的说明文字。
+*
+* schema（`src/index.ts` 的 `Config`）与设置卡共用同一份文案：两处各写一份，
+* 迟早变成「卡片说只影响新结果、schema 说立刻生效」这种自相矛盾。
+*/
+const CACHE_WARMUP_SETTING_DESCRIPTION = "启用缓存预热的结果投影：Kimi 线路上可以可靠结构化提取的超大工具结果会被替换成带 ref:// 引用的预览，需要原文时由 cache_warmup_result 精确补读。关闭只影响之后产生的新结果，已进入历史的内容不变。";
+/**
+* 读取一个配置字段，沿着 volatile 活引用取当前值。
+* @param field - 字段本身。
+* @returns 当前值，或字段缺失时的 undefined。
+*/
+function readCacheWarmupConfigField(field) {
+	if (field === void 0 || field === null) return void 0;
+	if (typeof field === "object" && typeof field.get === "function") return field.get();
+	return field;
+}
+/**
+* 解析一次读取的有效设置。
+*
+* 每次调用都重读活引用，因此设置保存后立刻生效（对**之后**的新结果生效；历史
+* 结果不重新投影，见模块说明）。
+* @param config - 主入口收到的插件配置（活引用或普通值）。
+* @returns 生效的开关。
+*/
+function resolveCacheWarmupSettings(config) {
+	return { enabled: readCacheWarmupConfigField(config?.cacheWarmup) !== false };
+}
+//#endregion
 //#region src/index.ts
 const Config = z.object({
 	fetchProvider: z.union([
@@ -80985,6 +83073,7 @@ const Config = z.object({
 		z.const("zh"),
 		z.const("en")
 	]).default("auto").volatile().description("进展更新的输出语言：auto 跟随对话语言，zh 中文，en 英文。"),
+	cacheWarmup: z.boolean().default(true).volatile().description(CACHE_WARMUP_SETTING_DESCRIPTION),
 	codexStreamIdleTimeoutMs: z.number().min(1).max(MAX_TIMER_DELAY_MS).step(1).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS$2),
 	poolStorage: z.union([z.const("keyring"), z.const("credentials")]).default("keyring").description("号池存储后端：keyring（默认，桌面平台的系统密钥环）或 credentials（DSH 凭据库，服务器推荐）。")
 });
@@ -81102,6 +83191,7 @@ function apply(ctx, pluginConfig = {}) {
 			return dispose;
 		}, "dsh-chatgpt-subscription: no-answer resume");
 	}
+	ctx.effect(() => installCacheWarmup(ctx, { settings: () => resolveCacheWarmupSettings(pluginConfig) }), "dsh-chatgpt-subscription: cache warmup");
 	const probeEnvFile = relayProbeEnvFile();
 	if (relayProbeEnabled(process.env, { envFile: probeEnvFile })) {
 		const probePath = relayProbeLogPath(process.env, { envFile: probeEnvFile });