@armadra/agent 0.0.0-stage → 0.3.0

package/dist/ai/cache/fingerprint.js

@@ -0,0 +1,39 @@
+/**
+ * 前缀指纹（第三波 §1.2）：一次请求的「可缓存前缀」= 折叠后的系统提示 + 工具表 + 模型。[W3-C1b]
+ *
+ * - `system` = sha256(normalizeContext().systemPrompt) 前 64 bit；
+ * - `tools` = sha256(JSON.stringify(工具表按名排序)) 前 64 bit；
+ * - `model` = `${provider}/${id}` 原文。
+ * 纯函数、零请求；每次真实请求算一次（system + tools 通常 < 20 KB）。未命中归因时与上一条
+ * 记录比对，说出「变了什么」。
+ */
+import { createHash } from "node:crypto";
+import { normalizeContext } from "../context.js";
+/** sha256 的前 16 位 hex（64 bit）。 */
+export function hash16(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+export function modelKey(model) {
+    return `${model.provider}/${model.id}${model.channel !== undefined ? `@${model.channel}` : ""}`;
+}
+function sortedTools(tools) {
+    return [...tools].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+export function fingerprintContext(context, model) {
+    const normalized = normalizeContext(context);
+    return {
+        system: hash16(normalized.systemPrompt),
+        tools: hash16(JSON.stringify(sortedTools(normalized.tools))),
+        model: modelKey(model),
+    };
+}
+/** 两个指纹的差异（按归因顺序：system → tools → model）；相同返回 undefined。 */
+export function fingerprintChange(prev, cur) {
+    if (prev.system !== cur.system)
+        return "system";
+    if (prev.tools !== cur.tools)
+        return "tools";
+    if (prev.model !== cur.model)
+        return "model";
+    return undefined;
+}

package/dist/ai/cache/miss.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 未命中检测（第三波 §1.5）：同一请求链上前后两条 `RequestRecord` 比对，纯函数。[W3-C1b]
+ *
+ * 1. 不计：没有 prev；本条 promptTokens 为 0；本条读写都为 0 且端点不是 `reported`（§1.6）；
+ *    prev 低于最小可缓存长度（判 unknown，不判 miss）。
+ * 2. `missed = min(prev, cur) − cur.cacheRead`；`missed ≤ noiseFloor` 不计，
+ *    `noiseFloor = max(1024, minTokens, 端点推断的缓存粒度)`（分块报读的端点，不足一块的尾部
+ *    不算未命中，见 `reporting.ts`）。
+ * 3. 规模自适应：`missed / prev > clamp(0.10 × √(100k / prev), 0.02, 0.30)` 或 `missed ≥ 20k`。
+ * 4. 成本：用本条实付反推——`(cost.input + cost.cacheWrite) / (input + cacheWrite)` 减去读价
+ *    （本条有读用实付，否则用目录价）；无价格 → `missedCost` 缺省。
+ * 5. 重置点（压缩 / 分支摘要 / 档一裁剪之后的首个请求）由调用方清空 prev；模型切换不豁免。
+ * 6. 归因：指纹 system / tools 变 → `prefix_changed`；模型变 → `model_changed`；
+ *    `idleMs > ttl`（无承诺 TTL 的隐式缓存按 600 s）→ `idle`；task 运行占间隔 ≥ 80% →
+ *    `subtask`；其余 → `evicted`。
+ */
+import type { ModelCost } from "../types.js";
+import type { CacheMiss, CacheReporting, RequestRecord } from "./types.js";
+/** 无承诺 TTL 的端点（隐式缓存）按 10 分钟估。 */
+export declare const IMPLICIT_CACHE_TTL_MS = 600000;
+/** 没有目录 `minTokens` 时的最小可缓存长度与噪声下限。 */
+export declare const DEFAULT_MIN_CACHE_TOKENS = 1024;
+/** 绝对门槛：一次少读这么多 token 无论比例都算未命中。 */
+export declare const MISS_ABSOLUTE_TOKENS = 20000;
+/** 转录 / 消息区只提示超过这两个门槛之一的未命中（统计计入全部）。 */
+export declare const MISS_NOTICE_TOKENS = 20000;
+export declare const MISS_NOTICE_USD = 0.1;
+/** task 运行时间占间隔的比例达到它 → 归因 subtask。 */
+export declare const SUBTASK_SHARE = 0.8;
+export interface MissOptions {
+    /** 本条请求所在端点的三态；读写都为 0 时只有 `reported` 才判。 */
+    reporting?: CacheReporting;
+    /** 目录 `promptCache.minTokens`。 */
+    minTokens?: number;
+    /** 端点推断的缓存读粒度（`CacheReportingTracker.granularity`）。 */
+    granularity?: number;
+    /** prev 与 cur 之间 task 工具运行的墙钟时间。 */
+    subtaskMs?: number;
+    /** 本条没有缓存读时的读价来源（目录价）。 */
+    cost?: Pick<ModelCost, "cacheRead">;
+}
+export declare function noiseFloor(minTokens: number | undefined, granularity?: number): number;
+/** 未命中比例门槛：前缀越长越敏感（2%–30%）。 */
+export declare function missRatioThreshold(prevTokens: number): number;
+/** 重计费金额（美元）；本条无成本 → undefined。 */
+export declare function missedCostOf(cur: RequestRecord, missed: number, cost?: Pick<ModelCost, "cacheRead">): number | undefined;
+export declare function detectMiss(prev: RequestRecord | undefined, cur: RequestRecord, ttlMs: number | undefined, options?: MissOptions): CacheMiss | undefined;
+/** 转录 / 消息区是否提示这次未命中（`/session` 与 RPC 统计计入全部）。 */
+export declare function isNotableMiss(miss: CacheMiss): boolean;

package/dist/ai/cache/miss.js

@@ -0,0 +1,96 @@
+/**
+ * 未命中检测（第三波 §1.5）：同一请求链上前后两条 `RequestRecord` 比对，纯函数。[W3-C1b]
+ *
+ * 1. 不计：没有 prev；本条 promptTokens 为 0；本条读写都为 0 且端点不是 `reported`（§1.6）；
+ *    prev 低于最小可缓存长度（判 unknown，不判 miss）。
+ * 2. `missed = min(prev, cur) − cur.cacheRead`；`missed ≤ noiseFloor` 不计，
+ *    `noiseFloor = max(1024, minTokens, 端点推断的缓存粒度)`（分块报读的端点，不足一块的尾部
+ *    不算未命中，见 `reporting.ts`）。
+ * 3. 规模自适应：`missed / prev > clamp(0.10 × √(100k / prev), 0.02, 0.30)` 或 `missed ≥ 20k`。
+ * 4. 成本：用本条实付反推——`(cost.input + cost.cacheWrite) / (input + cacheWrite)` 减去读价
+ *    （本条有读用实付，否则用目录价）；无价格 → `missedCost` 缺省。
+ * 5. 重置点（压缩 / 分支摘要 / 档一裁剪之后的首个请求）由调用方清空 prev；模型切换不豁免。
+ * 6. 归因：指纹 system / tools 变 → `prefix_changed`；模型变 → `model_changed`；
+ *    `idleMs > ttl`（无承诺 TTL 的隐式缓存按 600 s）→ `idle`；task 运行占间隔 ≥ 80% →
+ *    `subtask`；其余 → `evicted`。
+ */
+import { fingerprintChange } from "./fingerprint.js";
+/** 无承诺 TTL 的端点（隐式缓存）按 10 分钟估。 */
+export const IMPLICIT_CACHE_TTL_MS = 600_000;
+/** 没有目录 `minTokens` 时的最小可缓存长度与噪声下限。 */
+export const DEFAULT_MIN_CACHE_TOKENS = 1024;
+/** 绝对门槛：一次少读这么多 token 无论比例都算未命中。 */
+export const MISS_ABSOLUTE_TOKENS = 20_000;
+/** 转录 / 消息区只提示超过这两个门槛之一的未命中（统计计入全部）。 */
+export const MISS_NOTICE_TOKENS = 20_000;
+export const MISS_NOTICE_USD = 0.1;
+/** task 运行时间占间隔的比例达到它 → 归因 subtask。 */
+export const SUBTASK_SHARE = 0.8;
+export function noiseFloor(minTokens, granularity) {
+    return Math.max(DEFAULT_MIN_CACHE_TOKENS, minTokens ?? DEFAULT_MIN_CACHE_TOKENS, granularity ?? 0);
+}
+/** 未命中比例门槛：前缀越长越敏感（2%–30%）。 */
+export function missRatioThreshold(prevTokens) {
+    if (prevTokens <= 0)
+        return 0.3;
+    const raw = 0.1 * Math.sqrt(100_000 / prevTokens);
+    return Math.min(0.3, Math.max(0.02, raw));
+}
+/** 重计费金额（美元）；本条无成本 → undefined。 */
+export function missedCostOf(cur, missed, cost) {
+    const { usage } = cur;
+    if (usage.cost === undefined)
+        return undefined;
+    const paidTokens = usage.input + usage.cacheWrite;
+    if (paidTokens <= 0)
+        return 0;
+    const paidPerToken = (usage.cost.input + usage.cost.cacheWrite) / paidTokens;
+    let readPerToken;
+    if (usage.cacheRead > 0)
+        readPerToken = usage.cost.cacheRead / usage.cacheRead;
+    else if (cost !== undefined)
+        readPerToken = cost.cacheRead / 1e6;
+    else
+        return undefined;
+    return missed * Math.max(0, paidPerToken - readPerToken);
+}
+export function detectMiss(prev, cur, ttlMs, options = {}) {
+    if (prev === undefined || cur.promptTokens <= 0)
+        return undefined;
+    const { cacheRead, cacheWrite } = cur.usage;
+    if (cacheRead + cacheWrite === 0 && options.reporting !== "reported")
+        return undefined;
+    const minTokens = options.minTokens ?? DEFAULT_MIN_CACHE_TOKENS;
+    if (prev.promptTokens < minTokens)
+        return undefined;
+    const missed = Math.min(prev.promptTokens, cur.promptTokens) - cacheRead;
+    if (missed <= noiseFloor(options.minTokens, options.granularity))
+        return undefined;
+    const ratio = missed / prev.promptTokens;
+    if (ratio <= missRatioThreshold(prev.promptTokens) && missed < MISS_ABSOLUTE_TOKENS) {
+        return undefined;
+    }
+    const idleMs = Math.max(0, cur.at - prev.at);
+    const miss = { missedTokens: missed, reason: "evicted", idleMs };
+    const cost = missedCostOf(cur, missed, options.cost);
+    if (cost !== undefined)
+        miss.missedCost = cost;
+    const change = fingerprintChange(prev.fingerprint, cur.fingerprint);
+    if (change === "system" || change === "tools") {
+        miss.reason = "prefix_changed";
+        miss.detail = change;
+    }
+    else if (change === "model")
+        miss.reason = "model_changed";
+    else if (idleMs > (ttlMs ?? IMPLICIT_CACHE_TTL_MS))
+        miss.reason = "idle";
+    else if (idleMs > 0 && (options.subtaskMs ?? 0) >= SUBTASK_SHARE * idleMs) {
+        miss.reason = "subtask";
+    }
+    return miss;
+}
+/** 转录 / 消息区是否提示这次未命中（`/session` 与 RPC 统计计入全部）。 */
+export function isNotableMiss(miss) {
+    return (miss.missedTokens >= MISS_NOTICE_TOKENS ||
+        (miss.missedCost !== undefined && miss.missedCost >= MISS_NOTICE_USD));
+}

package/dist/ai/cache/reporting.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 「供应商不报缓存」三态（第三波 §1.6）。[W3-C1b]
+ *
+ * 按 `(provider, baseUrl 主机名, model)` 维护 `unknown | reported | silent`：
+ * - 出现过 `cacheRead > 0` 或 `cacheWrite > 0` → `reported`（之后一直是）；
+ * - 连续 K = 3 票 → `silent`；一票 = 前缀 ≥ minTokens 且读写都为 0，并且满足其一：
+ *   原始响应里**没有**缓存字段（`cacheReported === false`）；或与上一条可比（指纹未变、
+ *   间隔 < ttl）——有些中转总塞 `cached_tokens: 0`，单看字段存在不够；
+ * - 其余情形（小请求、不可比）既不投票也不清零。`silent` 之后出现命中即转 `reported`。
+ * `compat.cacheReporting` 为 `silent` / `reported` 时强制。状态只在内存：进程内跨会话复用
+ * （`sharedCacheReporting`），同一端点换会话不必再探 3 次。
+ *
+ * 同一张表还记缓存读的**分块粒度**：有的端点（如 DeepSeek 经中转）按 2048 token 一块报
+ * cacheRead，不足一块的尾部总被算成未读。粒度 = 观察到的非零 cacheRead 的最大公约数，
+ * 至少 2 个样本且落在 [128, 8192] 才采信；未命中的噪声下限据此抬高（`miss.ts`）。
+ */
+import type { CacheReportingSetting } from "../types.js";
+import type { CacheReporting, RequestRecord } from "./types.js";
+/** 连续这么多票判 silent。 */
+export declare const SILENT_STREAK = 3;
+/** 缓存粒度：样本数下限与采信范围。 */
+export declare const GRANULARITY_MIN_SAMPLES = 2;
+export declare const GRANULARITY_MIN = 128;
+export declare const GRANULARITY_MAX = 8192;
+/** 由非零 cacheRead 的最大公约数与样本数推断粒度；不可信 → undefined。 */
+export declare function inferGranularity(divisor: number, samples: number): number | undefined;
+export declare function endpointKey(record: Pick<RequestRecord, "model" | "baseUrl">): string;
+export declare class CacheReportingTracker {
+    private readonly endpoints;
+    /** 记一条真实请求，返回该端点（含强制设置后）的状态。 */
+    observe(record: RequestRecord, minTokens: number, ttlMs?: number, setting?: CacheReportingSetting): CacheReporting;
+    get(key: string, setting?: CacheReportingSetting): CacheReporting;
+    /** 端点的缓存读粒度（token）；样本不足或不可信 → undefined。 */
+    granularity(key: string): number | undefined;
+    /** 测试用：清空全部端点。 */
+    clear(): void;
+}
+/** 进程内共享（同一端点换会话、子会话都复用）。 */
+export declare const sharedCacheReporting: CacheReportingTracker;

package/dist/ai/cache/reporting.js

@@ -0,0 +1,103 @@
+/**
+ * 「供应商不报缓存」三态（第三波 §1.6）。[W3-C1b]
+ *
+ * 按 `(provider, baseUrl 主机名, model)` 维护 `unknown | reported | silent`：
+ * - 出现过 `cacheRead > 0` 或 `cacheWrite > 0` → `reported`（之后一直是）；
+ * - 连续 K = 3 票 → `silent`；一票 = 前缀 ≥ minTokens 且读写都为 0，并且满足其一：
+ *   原始响应里**没有**缓存字段（`cacheReported === false`）；或与上一条可比（指纹未变、
+ *   间隔 < ttl）——有些中转总塞 `cached_tokens: 0`，单看字段存在不够；
+ * - 其余情形（小请求、不可比）既不投票也不清零。`silent` 之后出现命中即转 `reported`。
+ * `compat.cacheReporting` 为 `silent` / `reported` 时强制。状态只在内存：进程内跨会话复用
+ * （`sharedCacheReporting`），同一端点换会话不必再探 3 次。
+ *
+ * 同一张表还记缓存读的**分块粒度**：有的端点（如 DeepSeek 经中转）按 2048 token 一块报
+ * cacheRead，不足一块的尾部总被算成未读。粒度 = 观察到的非零 cacheRead 的最大公约数，
+ * 至少 2 个样本且落在 [128, 8192] 才采信；未命中的噪声下限据此抬高（`miss.ts`）。
+ */
+import { IMPLICIT_CACHE_TTL_MS } from "./miss.js";
+/** 连续这么多票判 silent。 */
+export const SILENT_STREAK = 3;
+/** 缓存粒度：样本数下限与采信范围。 */
+export const GRANULARITY_MIN_SAMPLES = 2;
+export const GRANULARITY_MIN = 128;
+export const GRANULARITY_MAX = 8192;
+function gcd(a, b) {
+    while (b > 0)
+        [a, b] = [b, a % b];
+    return a;
+}
+/** 由非零 cacheRead 的最大公约数与样本数推断粒度；不可信 → undefined。 */
+export function inferGranularity(divisor, samples) {
+    if (samples < GRANULARITY_MIN_SAMPLES)
+        return undefined;
+    return divisor >= GRANULARITY_MIN && divisor <= GRANULARITY_MAX ? divisor : undefined;
+}
+function hostOf(baseUrl) {
+    try {
+        return new URL(baseUrl).host;
+    }
+    catch {
+        return baseUrl;
+    }
+}
+export function endpointKey(record) {
+    const channel = record.model.channel !== undefined ? `@${record.model.channel}` : "";
+    return `${record.model.provider}|${hostOf(record.baseUrl)}|${record.model.id}${channel}`;
+}
+function sameFingerprint(a, b) {
+    return a.system === b.system && a.tools === b.tools && a.model === b.model;
+}
+function forced(setting) {
+    return setting === "silent" || setting === "reported" ? setting : undefined;
+}
+export class CacheReportingTracker {
+    endpoints = new Map();
+    /** 记一条真实请求，返回该端点（含强制设置后）的状态。 */
+    observe(record, minTokens, ttlMs, setting) {
+        const key = endpointKey(record);
+        const entry = this.endpoints.get(key) ?? {
+            state: "unknown",
+            streak: 0,
+            last: undefined,
+            divisor: 0,
+            samples: 0,
+        };
+        this.endpoints.set(key, entry);
+        const last = entry.last;
+        entry.last = record;
+        const { cacheRead, cacheWrite, cacheReported } = record.usage;
+        if (cacheRead > 0 && Number.isInteger(cacheRead)) {
+            entry.divisor = gcd(entry.divisor, cacheRead);
+            entry.samples++;
+        }
+        if (cacheRead + cacheWrite > 0) {
+            entry.state = "reported";
+            entry.streak = 0;
+        }
+        else if (entry.state !== "reported" && record.promptTokens >= minTokens) {
+            const comparable = last !== undefined &&
+                last.promptTokens >= minTokens &&
+                sameFingerprint(last.fingerprint, record.fingerprint) &&
+                record.at - last.at < (ttlMs ?? IMPLICIT_CACHE_TTL_MS);
+            if (cacheReported === false || comparable)
+                entry.streak++;
+            if (entry.streak >= SILENT_STREAK)
+                entry.state = "silent";
+        }
+        return forced(setting) ?? entry.state;
+    }
+    get(key, setting) {
+        return forced(setting) ?? this.endpoints.get(key)?.state ?? "unknown";
+    }
+    /** 端点的缓存读粒度（token）；样本不足或不可信 → undefined。 */
+    granularity(key) {
+        const entry = this.endpoints.get(key);
+        return entry === undefined ? undefined : inferGranularity(entry.divisor, entry.samples);
+    }
+    /** 测试用：清空全部端点。 */
+    clear() {
+        this.endpoints.clear();
+    }
+}
+/** 进程内共享（同一端点换会话、子会话都复用）。 */
+export const sharedCacheReporting = new CacheReportingTracker();

package/dist/ai/cache/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 会话层缓存的共享类型（第三波 §1.2、§1.5–§1.7）。[W3-C0] 契约文件，实现归 W3-C1b。
+ *
+ * 补全与偏差（相对第三波设计正文）：
+ * - 设计把本文件列在 C1b；为让 C2（展示）、宿主（`cache.onWarmingDecision`）与配置
+ *   （`cache.warming`）在 C1b 合入前就能引用同一组名字，类型在契约 PR 里先定死，C1b 只追加。
+ * - `CacheMiss.missedCost` 写成可选：§1.5 第 4 步「模型无价格 → undefined」，正文接口写的是
+ *   `number`，以算法为准。
+ * - 补全 `CacheMissReason`、`WarmingPhase`、`WarmerState`、`WarmerStatus` 与 `WarmDecision`
+ *   的字段（正文只给了 `decide({ warmCost, missCost, probability, action })`）。
+ */
+import type { Api, ModelRef, RequestPurpose, StreamOptions, TranscriptContext, Usage } from "../types.js";
+/** 前缀指纹：各 16 位 hex（sha256 前 64 bit）。 */
+export interface PrefixFingerprint {
+    /** `normalizeContext().systemPrompt` 的哈希。 */
+    system: string;
+    /** 工具表按名排序后 `JSON.stringify` 的哈希。 */
+    tools: string;
+    /** `${provider}/${id}`（原文，不哈希）。 */
+    model: string;
+}
+/** 每次真实请求在会话层记一条（内存，不落盘）。 */
+export interface RequestRecord {
+    /** 请求发出时刻（保温计时从这里算，不是响应结束）。 */
+    at: number;
+    purpose: RequestPurpose;
+    model: ModelRef;
+    api: Api;
+    baseUrl: string;
+    fingerprint: PrefixFingerprint;
+    /** input + cacheRead + cacheWrite。 */
+    promptTokens: number;
+    /** 含 cost 与 cacheReported。 */
+    usage: Usage;
+    /** 保温重放用（同一引用）。 */
+    contextRef: TranscriptContext;
+    options: Omit<StreamOptions, "signal">;
+}
+/** 「供应商不报缓存」三态（§1.6）；按 `(provider, baseUrl 主机名, model)` 维护。 */
+export type CacheReporting = "unknown" | "reported" | "silent";
+/** 未命中原因（§1.5 第 6 步的归因顺序）。 */
+export type CacheMissReason = "prefix_changed" | "model_changed" | "idle" | "subtask" | "evicted";
+export declare const CACHE_MISS_REASONS: readonly CacheMissReason[];
+export interface CacheMiss {
+    /** 重计费 token。 */
+    missedTokens: number;
+    /** 重计费金额（美元）；模型无价格时缺省（显示 `$?`）。 */
+    missedCost?: number;
+    reason: CacheMissReason;
+    /** `prefix_changed` 时哪一段变了。 */
+    detail?: "system" | "tools";
+    /** 与上一条可比请求的间隔。 */
+    idleMs: number;
+}
+/** 保温模式（§1.7）：off 不保温；streaming 只在工具运行期间；idle 另含空闲相（需 opt-in）。 */
+export type WarmingMode = "off" | "streaming" | "idle";
+export declare const WARMING_MODES: readonly WarmingMode[];
+/** 保温所处的相：agent 运行中（streaming）或已 settle（idle）。 */
+export type WarmingPhase = "streaming" | "idle";
+/** 一次保温前的决策（`economics.evaluateWarm` 产出，宿主否决钩子的入参）。 */
+export interface WarmDecision {
+    /** 内置决策。 */
+    action: "warm" | "stop";
+    phase: WarmingPhase;
+    /** 上一次真实请求的 input + cacheRead + cacheWrite。 */
+    promptTokens: number;
+    /** 一次保温请求的花费（美元）；价格缺失时 undefined（经济性不可算 → stop）。 */
+    warmCost: number | undefined;
+    /** 不保温而失效时多付的金额（美元）。 */
+    missCost: number | undefined;
+    /** 失效后仍会再发请求的概率：streaming 1、idle 0.15。 */
+    probability: number;
+    /** stop 的原因（如 `no_price`、`below_min_savings`），warm 时缺省。 */
+    reason?: string;
+}
+/** 宿主 / 扩展的否决钩子（HostApi `cache.onWarmingDecision`）；出错回落内置决策。 */
+export type WarmingDecisionHandler = (decision: WarmDecision) => "warm" | "stop" | Promise<"warm" | "stop">;
+/** inactive：还没有可重放的真实请求或已 cancel；scheduled：计时器在等；stopped：因故停止。 */
+export type WarmerState = "inactive" | "scheduled" | "stopped";
+export interface WarmerStatus {
+    mode: WarmingMode;
+    state: WarmerState;
+    phase?: WarmingPhase;
+    /** 下一次保温的时刻（epoch ms），state 为 scheduled 时给。 */
+    nextWarmAt?: number;
+    /** stopped 的原因。 */
+    reason?: string;
+    /** 本会话已发出的保温请求数。 */
+    sent?: number;
+    /** 保温累计花费（美元）。 */
+    costUsd?: number;
+    /** 最近一次决策的期望节省（美元）。 */
+    expectedSavingsUsd?: number;
+}

package/dist/ai/cache/types.js

@@ -0,0 +1,19 @@
+/**
+ * 会话层缓存的共享类型（第三波 §1.2、§1.5–§1.7）。[W3-C0] 契约文件，实现归 W3-C1b。
+ *
+ * 补全与偏差（相对第三波设计正文）：
+ * - 设计把本文件列在 C1b；为让 C2（展示）、宿主（`cache.onWarmingDecision`）与配置
+ *   （`cache.warming`）在 C1b 合入前就能引用同一组名字，类型在契约 PR 里先定死，C1b 只追加。
+ * - `CacheMiss.missedCost` 写成可选：§1.5 第 4 步「模型无价格 → undefined」，正文接口写的是
+ *   `number`，以算法为准。
+ * - 补全 `CacheMissReason`、`WarmingPhase`、`WarmerState`、`WarmerStatus` 与 `WarmDecision`
+ *   的字段（正文只给了 `decide({ warmCost, missCost, probability, action })`）。
+ */
+export const CACHE_MISS_REASONS = [
+    "prefix_changed",
+    "model_changed",
+    "idle",
+    "subtask",
+    "evicted",
+];
+export const WARMING_MODES = ["off", "streaming", "idle"];

package/dist/ai/cache/warmer.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 缓存保温状态机（第三波 §1.7）。[W3-C1b]
+ *
+ * 注入 now / 计时器 / 发送函数，fake 时钟可测：
+ * - `start(record, ttlMs)`：每个 turn 请求完成后调用（替换上一轮）；计时**从请求发出算**：
+ *   `delay = max(1s, floor(min(0.9·TTL, TTL − 10s)))`，TTL ≤ 10 s 不保温。
+ * - 截止 `deadline = nextWarmAt + (TTL − delay) / 2`：计时器迟到超过截止（睡眠、事件循环阻塞）
+ *   直接停——迟到的刷新大概率是一次全价写入。
+ * - 上限：streaming 相 60 min、idle 相 30 min（从起始真实请求算）；连续 2 次保温响应读写都为
+ *   0 即停。
+ * - 每次刷新前：`isCurrent(record)` 不成立 → 停；内置经济性决策交给否决钩子 `decide`（出错
+ *   回落内置决策）。
+ * - `onAgentSettled()`：streaming 模式静默结束本轮；idle 模式转空闲相。
+ * - `pause()`：真实请求发出时静默挂起（新请求本身就刷新了缓存）；`cancel()` 同时丢弃记录。
+ * 只有已排期之后的异常停止（截止、上限、零命中、过期、否决、失败）回调 `onStopped`。
+ */
+import type { AssistantMessage, Model, StreamOptions } from "../types.js";
+import type { CacheReporting, RequestRecord, WarmDecision, WarmerStatus, WarmingMode, WarmingPhase } from "./types.js";
+export declare const WARM_MIN_TTL_MS = 10000;
+export declare const WARM_STREAMING_CAP_MS: number;
+export declare const WARM_IDLE_CAP_MS: number;
+export declare const WARM_ZERO_HIT_LIMIT = 2;
+export interface WarmerTimers {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** 真实计时器：`unref()`，保温不拖住进程退出。 */
+export declare const REAL_TIMERS: WarmerTimers;
+export interface WarmerDeps {
+    mode(): WarmingMode;
+    now(): number;
+    timers?: WarmerTimers;
+    /** 重放：同 model / context / options，maxTokens 1，purpose warm，不经重试。 */
+    send(record: RequestRecord, signal: AbortSignal): Promise<AssistantMessage>;
+    /** 模型未变 && 记录的上下文仍是当前转录的同一引用前缀 && system 状态未变。 */
+    isCurrent(record: RequestRecord): boolean;
+    /** 内置经济性决策。 */
+    evaluate(record: RequestRecord, phase: WarmingPhase): WarmDecision;
+    /** 宿主 / 扩展否决钩子（每次现取）。 */
+    decide?(decision: WarmDecision): Promise<"warm" | "stop"> | "warm" | "stop";
+    onWarmed(record: RequestRecord, message: AssistantMessage, sentAt: number): void;
+    onScheduled?(nextWarmAt: number): void;
+    onStopped(reason: string): void;
+}
+export declare function warmDelay(ttlMs: number): number;
+export interface ReplayCheck {
+    model: Pick<Model, "api" | "reasoning" | "compat">;
+    options: Pick<StreamOptions, "cacheRetention" | "thinkingLevel">;
+    /** `onPayload` 替换过请求体。 */
+    payloadReplaced: boolean;
+    reporting: CacheReporting;
+}
+/**
+ * 不保温的原因（undefined = 可以保温）：
+ * - `cacheRetention: "none"` 的请求；被 `onPayload` 替换过请求体的请求；
+ * - anthropic-messages 开思考且不是自适应思考：预算从 `max_tokens` 推导，`max_tokens: 1` 会
+ *   去掉 thinking 块、改变缓存键；
+ * - 端点不是 `reported`（未知或不报缓存时看不出保温有没有用，第三波 §4 R2）。
+ */
+export declare function replayBlocker(check: ReplayCheck): string | undefined;
+export declare class CacheWarmer {
+    private readonly deps;
+    private readonly timers;
+    private record;
+    private origin;
+    private ttl;
+    private phase;
+    private timer;
+    private inflight;
+    private generation;
+    private zeroHits;
+    private state;
+    private reason;
+    private nextWarmAt;
+    private deadline;
+    private sent;
+    private costUsd;
+    private savings;
+    constructor(deps: WarmerDeps);
+    start(record: RequestRecord, ttlMs: number): void;
+    /** 不排期并记下原因（无事件：不可重放、端点未报告、经济性不划算等）。 */
+    block(reason: string): void;
+    onAgentSettled(): void;
+    /** 真实请求发出：静默挂起，保留统计。 */
+    pause(): void;
+    cancel(): void;
+    get status(): WarmerStatus;
+    private reset;
+    private stop;
+    private cap;
+    private schedule;
+    private decide;
+    private fire;
+}