@relay-harness/coding-agent 0.0.0-stage → 1.0.3

package/dist/core/cache-stats.d.ts

@@ -0,0 +1,49 @@
+import type { AssistantMessage } from "@relay-harness/ai";
+import type { SessionEntry } from "./session-manager.ts";
+/**
+ * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the
+ * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.
+ */
+export declare const CACHE_TTL_MS: number;
+/** A counted cache miss on a single assistant message. */
+export interface CacheMiss {
+    /** Prompt tokens that were in the previous turn's prompt but not read from cache. */
+    missedTokens: number;
+    /** Extra dollars paid vs. a full cache hit; 0 when pricing is unknown. */
+    missedCost: number;
+    /** Milliseconds since the previous request (which last refreshed the cache). */
+    idleMs: number;
+    /** True when the model changed relative to the previous request. */
+    modelChanged: boolean;
+}
+export interface CacheWasteTotals {
+    missedTokens: number;
+    missedCost: number;
+    /** Number of counted misses (turns above the noise floor). */
+    missCount: number;
+}
+/** Minimal pricing lookup, satisfied by ModelRuntime. Cost is $/million tokens. */
+export interface ModelPriceSource {
+    getModel(provider: string, modelId: string): {
+        cost: {
+            cacheRead: number;
+        };
+    } | undefined;
+}
+/**
+ * Cumulative cache waste across a session: prompt tokens that should have been
+ * cache reads (they were in the previous turn's prompt) but were re-billed.
+ */
+export declare function computeCacheWaste(entries: SessionEntry[], models: ModelPriceSource): CacheWasteTotals;
+/**
+ * All counted cache misses across a session, keyed by the assistant message
+ * (by reference) that paid for them. Used to re-derive transcript notices when
+ * rebuilding the chat from entries (resume, post-compaction rebuild).
+ */
+export declare function collectCacheMisses(entries: SessionEntry[], models: ModelPriceSource): Map<AssistantMessage, CacheMiss>;
+/**
+ * Detect a cache miss on a just-completed assistant message.
+ * `entries` must not yet contain `message` (message_end fires before persistence).
+ */
+export declare function detectCacheMiss(entries: SessionEntry[], message: AssistantMessage, models: ModelPriceSource): CacheMiss | undefined;
+//# sourceMappingURL=cache-stats.d.ts.map

package/dist/core/cache-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-stats.d.ts","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAgB,CAAC;AAK1C,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACzB,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACzF;AA6GD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAErG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,MAAM,EAAE,gBAAgB,GACtB,GAAG,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAElC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,gBAAgB,GACtB,SAAS,GAAG,SAAS,CAEvB"}

package/dist/core/cache-stats.js

@@ -0,0 +1,112 @@
+/**
+ * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the
+ * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.
+ */
+export const CACHE_TTL_MS = 5 * 60 * 1000;
+/** Per-turn misses at or below this are cache breakpoint granularity noise. */
+const NOISE_FLOOR_TOKENS = 1024;
+/**
+ * Compute the cache miss for one assistant message relative to the previous
+ * request. Returns undefined when nothing is counted: first turn, after a
+ * reset, no cache activity ever reported (provider without cache support), or
+ * miss below the noise floor.
+ */
+function detectMiss(prev, message, models) {
+    const usage = message.usage;
+    const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+    // A zero-cache turn only counts when cache activity was reported before:
+    // on cache-read-only providers that is a total miss, while on providers
+    // that never report caching it means nothing.
+    if (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) {
+        return undefined;
+    }
+    const missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead;
+    if (missedTokens <= NOISE_FLOOR_TOKENS)
+        return undefined;
+    // Extra cost = missed tokens billed at the actual paid rate (input/cacheWrite,
+    // incl. write premium) instead of the cache-read rate. Missed tokens can only
+    // land in the input or cacheWrite buckets, so the paid rate comes straight
+    // from this message's own cost breakdown.
+    const paidTokens = usage.input + usage.cacheWrite;
+    const paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0;
+    const readPerToken = usage.cacheRead > 0
+        ? usage.cost.cacheRead / usage.cacheRead
+        : (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000;
+    return {
+        missedTokens,
+        missedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),
+        idleMs: Math.max(0, message.timestamp - prev.timestamp),
+        modelChanged: `${message.provider}/${message.model}` !== prev.modelKey,
+    };
+}
+function asPreviousRequest(message, reportedCache) {
+    const usage = message.usage;
+    const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+    if (promptTokens <= 0)
+        return undefined;
+    return {
+        promptTokens,
+        modelKey: `${message.provider}/${message.model}`,
+        timestamp: message.timestamp,
+        reportedCache: reportedCache || usage.cacheRead + usage.cacheWrite > 0,
+    };
+}
+function scan(entries, models) {
+    let prev;
+    const totals = { missedTokens: 0, missedCost: 0, missCount: 0 };
+    const misses = new Map();
+    for (const entry of entries) {
+        if (entry.type === "compaction" || entry.type === "branch_summary") {
+            // The context legitimately changed; the next turn's prompt is new content,
+            // not re-billed content. Model switches are NOT exempt: they re-bill the
+            // full prompt and should be counted.
+            prev = undefined;
+            continue;
+        }
+        if (entry.type === "usage" && entry.kind === "cache_warm") {
+            const promptTokens = entry.usage.input + entry.usage.cacheRead + entry.usage.cacheWrite;
+            if (promptTokens > 0) {
+                prev = {
+                    promptTokens,
+                    modelKey: `${entry.provider}/${entry.model}`,
+                    timestamp: Date.parse(entry.timestamp),
+                    reportedCache: true,
+                };
+            }
+        }
+        else if (entry.type === "message" && entry.message.role === "assistant") {
+            const miss = detectMiss(prev, entry.message, models);
+            if (miss) {
+                totals.missedTokens += miss.missedTokens;
+                totals.missedCost += miss.missedCost;
+                totals.missCount += 1;
+                misses.set(entry.message, miss);
+            }
+            prev = asPreviousRequest(entry.message, prev?.reportedCache ?? false) ?? prev;
+        }
+    }
+    return { prev, totals, misses };
+}
+/**
+ * Cumulative cache waste across a session: prompt tokens that should have been
+ * cache reads (they were in the previous turn's prompt) but were re-billed.
+ */
+export function computeCacheWaste(entries, models) {
+    return scan(entries, models).totals;
+}
+/**
+ * All counted cache misses across a session, keyed by the assistant message
+ * (by reference) that paid for them. Used to re-derive transcript notices when
+ * rebuilding the chat from entries (resume, post-compaction rebuild).
+ */
+export function collectCacheMisses(entries, models) {
+    return scan(entries, models).misses;
+}
+/**
+ * Detect a cache miss on a just-completed assistant message.
+ * `entries` must not yet contain `message` (message_end fires before persistence).
+ */
+export function detectCacheMiss(entries, message, models) {
+    return detectMiss(scan(entries, models).prev, message, models);
+}
+//# sourceMappingURL=cache-stats.js.map

package/dist/core/cache-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-stats.js","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AssistantMessage } from \"@relay-harness/ai\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\n/**\n * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the\n * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.\n */\nexport const CACHE_TTL_MS = 5 * 60 * 1000;\n\n/** Per-turn misses at or below this are cache breakpoint granularity noise. */\nconst NOISE_FLOOR_TOKENS = 1024;\n\n/** A counted cache miss on a single assistant message. */\nexport interface CacheMiss {\n\t/** Prompt tokens that were in the previous turn's prompt but not read from cache. */\n\tmissedTokens: number;\n\t/** Extra dollars paid vs. a full cache hit; 0 when pricing is unknown. */\n\tmissedCost: number;\n\t/** Milliseconds since the previous request (which last refreshed the cache). */\n\tidleMs: number;\n\t/** True when the model changed relative to the previous request. */\n\tmodelChanged: boolean;\n}\n\nexport interface CacheWasteTotals {\n\tmissedTokens: number;\n\tmissedCost: number;\n\t/** Number of counted misses (turns above the noise floor). */\n\tmissCount: number;\n}\n\n/** Minimal pricing lookup, satisfied by ModelRuntime. Cost is $/million tokens. */\nexport interface ModelPriceSource {\n\tgetModel(provider: string, modelId: string): { cost: { cacheRead: number } } | undefined;\n}\n\n/** The last request seen by the scan; everything in its prompt should be cached. */\ninterface PreviousRequest {\n\tpromptTokens: number;\n\tmodelKey: string;\n\ttimestamp: number;\n\t/**\n\t * Sticky: some earlier request in this scan segment reported cache activity.\n\t * Distinguishes a total miss on a cache-read-only provider (OpenAI-style,\n\t * writes unreported) from a provider that never reports caching at all.\n\t */\n\treportedCache: boolean;\n}\n\n/**\n * Compute the cache miss for one assistant message relative to the previous\n * request. Returns undefined when nothing is counted: first turn, after a\n * reset, no cache activity ever reported (provider without cache support), or\n * miss below the noise floor.\n */\nfunction detectMiss(\n\tprev: PreviousRequest | undefined,\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\t// A zero-cache turn only counts when cache activity was reported before:\n\t// on cache-read-only providers that is a total miss, while on providers\n\t// that never report caching it means nothing.\n\tif (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) {\n\t\treturn undefined;\n\t}\n\n\tconst missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead;\n\tif (missedTokens <= NOISE_FLOOR_TOKENS) return undefined;\n\n\t// Extra cost = missed tokens billed at the actual paid rate (input/cacheWrite,\n\t// incl. write premium) instead of the cache-read rate. Missed tokens can only\n\t// land in the input or cacheWrite buckets, so the paid rate comes straight\n\t// from this message's own cost breakdown.\n\tconst paidTokens = usage.input + usage.cacheWrite;\n\tconst paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0;\n\tconst readPerToken =\n\t\tusage.cacheRead > 0\n\t\t\t? usage.cost.cacheRead / usage.cacheRead\n\t\t\t: (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000;\n\n\treturn {\n\t\tmissedTokens,\n\t\tmissedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),\n\t\tidleMs: Math.max(0, message.timestamp - prev.timestamp),\n\t\tmodelChanged: `${message.provider}/${message.model}` !== prev.modelKey,\n\t};\n}\n\nfunction asPreviousRequest(message: AssistantMessage, reportedCache: boolean): PreviousRequest | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\tif (promptTokens <= 0) return undefined;\n\treturn {\n\t\tpromptTokens,\n\t\tmodelKey: `${message.provider}/${message.model}`,\n\t\ttimestamp: message.timestamp,\n\t\treportedCache: reportedCache || usage.cacheRead + usage.cacheWrite > 0,\n\t};\n}\n\nfunction scan(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): { prev: PreviousRequest | undefined; totals: CacheWasteTotals; misses: Map<AssistantMessage, CacheMiss> } {\n\tlet prev: PreviousRequest | undefined;\n\tconst totals: CacheWasteTotals = { missedTokens: 0, missedCost: 0, missCount: 0 };\n\tconst misses = new Map<AssistantMessage, CacheMiss>();\n\n\tfor (const entry of entries) {\n\t\tif (entry.type === \"compaction\" || entry.type === \"branch_summary\") {\n\t\t\t// The context legitimately changed; the next turn's prompt is new content,\n\t\t\t// not re-billed content. Model switches are NOT exempt: they re-bill the\n\t\t\t// full prompt and should be counted.\n\t\t\tprev = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.type === \"usage\" && entry.kind === \"cache_warm\") {\n\t\t\tconst promptTokens = entry.usage.input + entry.usage.cacheRead + entry.usage.cacheWrite;\n\t\t\tif (promptTokens > 0) {\n\t\t\t\tprev = {\n\t\t\t\t\tpromptTokens,\n\t\t\t\t\tmodelKey: `${entry.provider}/${entry.model}`,\n\t\t\t\t\ttimestamp: Date.parse(entry.timestamp),\n\t\t\t\t\treportedCache: true,\n\t\t\t\t};\n\t\t\t}\n\t\t} else if (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tconst miss = detectMiss(prev, entry.message, models);\n\t\t\tif (miss) {\n\t\t\t\ttotals.missedTokens += miss.missedTokens;\n\t\t\t\ttotals.missedCost += miss.missedCost;\n\t\t\t\ttotals.missCount += 1;\n\t\t\t\tmisses.set(entry.message, miss);\n\t\t\t}\n\t\t\tprev = asPreviousRequest(entry.message, prev?.reportedCache ?? false) ?? prev;\n\t\t}\n\t}\n\treturn { prev, totals, misses };\n}\n\n/**\n * Cumulative cache waste across a session: prompt tokens that should have been\n * cache reads (they were in the previous turn's prompt) but were re-billed.\n */\nexport function computeCacheWaste(entries: SessionEntry[], models: ModelPriceSource): CacheWasteTotals {\n\treturn scan(entries, models).totals;\n}\n\n/**\n * All counted cache misses across a session, keyed by the assistant message\n * (by reference) that paid for them. Used to re-derive transcript notices when\n * rebuilding the chat from entries (resume, post-compaction rebuild).\n */\nexport function collectCacheMisses(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): Map<AssistantMessage, CacheMiss> {\n\treturn scan(entries, models).misses;\n}\n\n/**\n * Detect a cache miss on a just-completed assistant message.\n * `entries` must not yet contain `message` (message_end fires before persistence).\n */\nexport function detectCacheMiss(\n\tentries: SessionEntry[],\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\treturn detectMiss(scan(entries, models).prev, message, models);\n}\n"]}

package/dist/core/cache-warmer.d.ts

@@ -0,0 +1,103 @@
+import { type Api, type Context, type Model, type ModelsSimpleStreamOptions, type SimpleStreamOptions } from "@relay-harness/ai";
+import type { ModelRuntime } from "./model-runtime.ts";
+import type { SessionManager, UsageEntry } from "./session-manager.ts";
+import type { CacheWarmingMode } from "./settings-manager.ts";
+/** Refresh at 90% of the TTL while preserving at least ten seconds of margin. */
+export declare function getCacheWarmingDelayMs(ttlMs: number): number | undefined;
+/**
+ * Lifetime of the prompt cache entry a request writes, from the model's
+ * `promptCache` tier for the retention the request used. Undefined when the
+ * model has no lifetime for that tier or caching is off.
+ */
+export declare function getPromptCacheTtlMs(model: Model<Api>, options: SimpleStreamOptions | undefined): number | undefined;
+/**
+ * Whether replaying the request with a one-token output cap leaves its cache
+ * entry untouched. Anthropic's budget-based thinking (Claude models without
+ * adaptive thinking) derives `budget_tokens` from `max_tokens`; the replay
+ * would get a different budget, which Anthropic keys the message cache on,
+ * and the model could still think for thousands of tokens.
+ */
+export declare function isReplayable(model: Model<Api>, options: SimpleStreamOptions | undefined): boolean;
+export type CacheWarmingAction = "warm" | "stop";
+/** Inputs and outcome of one warm-or-stop decision, as shown by `/session`. */
+export interface CacheWarmingDecision {
+    /** "streaming" while the agent run that sent the request is still active. */
+    phase: "streaming" | "idle";
+    /** Price of this refresh: a cache read of the prompt plus one output token. */
+    warmCost: number;
+    /** Extra price of the next real request if the cache entry is lost. */
+    missCost: number;
+    /** Estimated chance that a real request arrives before the entry expires. */
+    continuationProbability: number;
+    /** `continuationProbability * missCost - warmCost`. */
+    expectedSavings: number;
+    /** False when the prompt size or the model's prices are unknown. */
+    economicsAvailable: boolean;
+    /** Relay's decision: "warm" when `expectedSavings` is at least $0.05. */
+    action: CacheWarmingAction;
+}
+/**
+ * Fired before each refresh with relay's decision filled in. Everything else an
+ * extension might want (model, idle state, context size) is on the context.
+ */
+export interface CacheWarmingDecisionEvent extends Pick<CacheWarmingDecision, "warmCost" | "missCost" | "continuationProbability" | "action"> {
+    type: "cache_warming_decision";
+}
+export interface CacheWarmingDecisionEventResult {
+    /** Override whether this refresh is sent. "stop" ends warming until the next real request. */
+    action?: CacheWarmingAction;
+}
+export interface CacheWarmingStatus {
+    /** "scheduled": a refresh timer is armed; "refreshing": a warm request is in flight. */
+    state: "inactive" | "scheduled" | "refreshing";
+    /** Why nothing is scheduled. */
+    reason?: string;
+    nextWarmAt?: number;
+    /** The pending decision, or the decision that stopped warming. */
+    decision?: CacheWarmingDecision;
+    /** True when an extension changed `decision.action`. */
+    extensionOverride?: boolean;
+}
+/** The request whose prompt cache entry should be kept warm, exactly as it was sent. */
+export interface CacheWarmRequest {
+    model: Model<Api>;
+    context: Context;
+    options: ModelsSimpleStreamOptions;
+}
+/**
+ * Keeps one prompt cache entry alive by re-sending its request with a
+ * one-token output cap before the entry expires. `start` replaces any
+ * previous run; warm requests never extend the fixed safety windows.
+ */
+export declare class CacheWarmer {
+    private run?;
+    private inactive;
+    private readonly models;
+    private readonly sessionManager;
+    private readonly getMode;
+    /** Lets extensions override `event.action`; failures fall back to relay's decision. */
+    private readonly decide;
+    /** Called with the persisted usage entry after each successful refresh. */
+    onWarmed?: (entry: UsageEntry) => void;
+    constructor(models: Pick<ModelRuntime, "streamSimple">, sessionManager: Pick<SessionManager, "appendUsage" | "getBranch">, getMode: () => CacheWarmingMode, decide?: (event: CacheWarmingDecisionEvent) => Promise<CacheWarmingAction>);
+    get status(): CacheWarmingStatus;
+    /** Keep the prompt cache entry written by `request` warm while `isCurrent` holds. */
+    start(request: CacheWarmRequest, isCurrent: () => boolean): void;
+    onAgentSettled(): void;
+    /** Reconcile an active run after the persisted warming mode changes. */
+    onModeChanged(): void;
+    cancel(): void;
+    private clearRun;
+    private stop;
+    private schedule;
+    private refresh;
+    private refreshDeadlineMissed;
+    private validateRun;
+    private getModeStopReason;
+    private evaluate;
+}
+/** One-line status for `/session`. */
+export declare function formatCacheWarmingStatus(status: CacheWarmingStatus, now?: number): string;
+/** One-line transcript text for persisted cache-warming usage. */
+export declare function formatCacheWarmingUsage(entry: UsageEntry): string;
+//# sourceMappingURL=cache-warmer.d.ts.map

package/dist/core/cache-warmer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-warmer.d.ts","sourceRoot":"","sources":["../../src/core/cache-warmer.ts"],"names":[],"mappings":"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"}

package/dist/core/cache-warmer.js

@@ -0,0 +1,356 @@
+import { calculateCost, } from "@relay-harness/ai";
+import { getProviderEnvValue } from "@relay-harness/ai/utils/provider-env";
+/** Streaming warming never continues past this long after the real request that started it. */
+const MAX_WARMING_AGE_MS = 60 * 60_000;
+/** Idle warming uses a shorter horizon because continuation estimates become less reliable with age. */
+const MAX_IDLE_WARMING_AGE_MS = 30 * 60_000;
+/** A refresh is sent only when it is expected to save at least this many dollars. */
+const CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS = 0.05;
+/**
+ * Chance that a real request arrives before the cache entry expires while the
+ * agent sits idle. Measured from our own usage; per-session estimates were not
+ * better than this constant.
+ */
+const IDLE_CONTINUATION_PROBABILITY = 0.15;
+/** Refresh at 90% of the TTL while preserving at least ten seconds of margin. */
+export function getCacheWarmingDelayMs(ttlMs) {
+    if (ttlMs <= 10_000)
+        return undefined;
+    return Math.max(1, Math.floor(Math.min(ttlMs * 0.9, ttlMs - 10_000)));
+}
+/**
+ * Lifetime of the prompt cache entry a request writes, from the model's
+ * `promptCache` tier for the retention the request used. Undefined when the
+ * model has no lifetime for that tier or caching is off.
+ */
+export function getPromptCacheTtlMs(model, options) {
+    const retention = options?.cacheRetention ??
+        (getProviderEnvValue("RELAY_CACHE_RETENTION", options?.env) === "long" ? "long" : "short");
+    if (retention === "none")
+        return undefined;
+    const seconds = model.promptCache?.[retention];
+    return seconds === undefined ? undefined : seconds * 1000;
+}
+/**
+ * Whether replaying the request with a one-token output cap leaves its cache
+ * entry untouched. Anthropic's budget-based thinking (Claude models without
+ * adaptive thinking) derives `budget_tokens` from `max_tokens`; the replay
+ * would get a different budget, which Anthropic keys the message cache on,
+ * and the model could still think for thousands of tokens.
+ */
+export function isReplayable(model, options) {
+    if (!options?.reasoning || model.api !== "anthropic-messages")
+        return true;
+    return model.compat?.forceAdaptiveThinking === true;
+}
+/** Prompt size of the most recent real request on the branch, as reported by the provider. */
+function lastPromptTokens(entries) {
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type === "message" && entry.message.role === "assistant") {
+            const usage = entry.message.usage;
+            return usage.input + usage.cacheRead + usage.cacheWrite;
+        }
+    }
+    return 0;
+}
+function price(model, tokens) {
+    const usage = {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        ...tokens,
+    };
+    return calculateCost(model, usage).total;
+}
+/**
+ * Keeps one prompt cache entry alive by re-sending its request with a
+ * one-token output cap before the entry expires. `start` replaces any
+ * previous run; warm requests never extend the fixed safety windows.
+ */
+export class CacheWarmer {
+    run;
+    inactive;
+    models;
+    sessionManager;
+    getMode;
+    /** Lets extensions override `event.action`; failures fall back to relay's decision. */
+    decide;
+    /** Called with the persisted usage entry after each successful refresh. */
+    onWarmed;
+    constructor(models, sessionManager, getMode, decide = async (event) => event.action) {
+        this.models = models;
+        this.sessionManager = sessionManager;
+        this.getMode = getMode;
+        this.decide = decide;
+        this.inactive = { state: "inactive", reason: "waiting for first request" };
+    }
+    get status() {
+        if (this.getMode() === "off")
+            return { state: "inactive", reason: "cache warming disabled" };
+        const run = this.run;
+        if (!run)
+            return this.inactive;
+        if (!run.isCurrent())
+            return { state: "inactive", reason: "conversation context changed" };
+        const decision = this.evaluate(run);
+        const refreshing = run.timer === undefined;
+        if (!decision.economicsAvailable && !refreshing) {
+            return { state: "inactive", reason: "cache economics unavailable" };
+        }
+        return {
+            state: refreshing ? "refreshing" : "scheduled",
+            nextWarmAt: run.nextWarmAt,
+            decision,
+            extensionOverride: run.extensionOverride,
+        };
+    }
+    /** Keep the prompt cache entry written by `request` warm while `isCurrent` holds. */
+    start(request, isCurrent) {
+        this.clearRun();
+        const mode = this.getMode();
+        if (mode === "off") {
+            this.stop("cache warming disabled");
+            return;
+        }
+        if (!isReplayable(request.model, request.options)) {
+            this.stop("request cannot be replayed safely");
+            return;
+        }
+        const ttlMs = getPromptCacheTtlMs(request.model, request.options);
+        if (ttlMs === undefined) {
+            this.stop(request.options.cacheRetention === "none"
+                ? "request disabled prompt caching"
+                : "cache lifetime unavailable");
+            return;
+        }
+        const delayMs = getCacheWarmingDelayMs(ttlMs);
+        if (delayMs === undefined) {
+            this.stop("cache lifetime unavailable");
+            return;
+        }
+        this.run = {
+            ...request,
+            isCurrent,
+            ttlMs,
+            delayMs,
+            refreshDeadlineAt: 0,
+            startedAt: Date.now(),
+            controller: new AbortController(),
+            phase: "streaming",
+            nextWarmAt: 0,
+            extensionOverride: false,
+        };
+        this.schedule(this.run);
+    }
+    onAgentSettled() {
+        const run = this.run;
+        if (!run)
+            return;
+        if (this.getMode() === "streaming") {
+            this.stop("agent run settled");
+            return;
+        }
+        run.phase = "idle";
+        const deadline = run.startedAt + MAX_IDLE_WARMING_AGE_MS;
+        if (run.nextWarmAt > deadline || Date.now() >= deadline) {
+            this.stop("30-minute idle safety limit reached");
+        }
+    }
+    /** Reconcile an active run after the persisted warming mode changes. */
+    onModeChanged() {
+        const run = this.run;
+        if (!run)
+            return;
+        const reason = this.getModeStopReason(run);
+        if (reason)
+            this.stop(reason);
+    }
+    cancel() {
+        this.stop("inactive");
+    }
+    clearRun() {
+        const run = this.run;
+        if (!run)
+            return;
+        this.run = undefined;
+        if (run.timer)
+            clearTimeout(run.timer);
+        run.controller.abort();
+    }
+    stop(reason, stopped) {
+        this.clearRun();
+        this.inactive = { state: "inactive", reason, ...stopped };
+    }
+    schedule(run) {
+        run.extensionOverride = false;
+        run.nextWarmAt = Date.now() + run.delayMs;
+        // A timer can run late after sleep or event-loop blockage. Keep half of
+        // the planned pre-expiry margin for that delay and request dispatch; a
+        // late refresh is likely a full-price cache write, not a cache warm.
+        run.refreshDeadlineAt = run.nextWarmAt + Math.floor((run.ttlMs - run.delayMs) / 2);
+        const deadline = run.startedAt + (run.phase === "idle" ? MAX_IDLE_WARMING_AGE_MS : MAX_WARMING_AGE_MS);
+        if (run.nextWarmAt > deadline || Date.now() >= deadline) {
+            this.stop(run.phase === "idle" ? "30-minute idle safety limit reached" : "one-hour safety limit reached");
+            return;
+        }
+        run.timer = setTimeout(() => void this.refresh(run), Math.max(0, run.nextWarmAt - Date.now()));
+        run.timer.unref?.();
+    }
+    async refresh(run) {
+        run.timer = undefined;
+        if (!this.validateRun(run))
+            return;
+        if (this.refreshDeadlineMissed(run))
+            return;
+        const decision = this.evaluate(run);
+        const { warmCost, missCost, continuationProbability } = decision;
+        let action = decision.action;
+        try {
+            action = await this.decide({
+                type: "cache_warming_decision",
+                warmCost,
+                missCost,
+                continuationProbability,
+                action,
+            });
+        }
+        catch {
+            // Extension failures fall back to relay's own decision.
+        }
+        if (!this.validateRun(run) || this.refreshDeadlineMissed(run))
+            return;
+        const extensionOverride = action !== decision.action;
+        if (action === "stop") {
+            const reason = extensionOverride
+                ? "stopped by extension"
+                : decision.economicsAvailable
+                    ? "expected savings below threshold"
+                    : "cache economics unavailable";
+            this.stop(reason, { decision, extensionOverride });
+            return;
+        }
+        run.extensionOverride = extensionOverride;
+        try {
+            const message = await this.models
+                .streamSimple(run.model, run.context, {
+                ...run.options,
+                maxTokens: 1,
+                maxRetries: 0,
+                signal: run.controller.signal,
+            })
+                .result();
+            if (!this.validateRun(run))
+                return;
+            if (message.stopReason !== "error" && message.stopReason !== "aborted") {
+                const entry = this.sessionManager.appendUsage("cache_warm", message.provider, message.responseModel ?? message.model, message.usage, extensionOverride ? "extension override" : undefined);
+                this.onWarmed?.(entry);
+            }
+        }
+        catch {
+            // Cache warming is best-effort and must not affect the active agent run.
+        }
+        if (this.run === run)
+            this.schedule(run);
+    }
+    refreshDeadlineMissed(run) {
+        if (Date.now() <= run.refreshDeadlineAt)
+            return false;
+        this.stop("cache refresh deadline missed");
+        return true;
+    }
+    validateRun(run) {
+        if (this.run !== run)
+            return false;
+        const reason = this.getModeStopReason(run) ?? (!run.isCurrent() ? "conversation context changed" : undefined);
+        if (!reason)
+            return true;
+        this.stop(reason);
+        return false;
+    }
+    getModeStopReason(run) {
+        const mode = this.getMode();
+        if (mode === "off")
+            return "cache warming disabled";
+        if (mode === "streaming" && run.phase === "idle")
+            return "agent run settled";
+        return undefined;
+    }
+    evaluate(run) {
+        const model = run.model;
+        const promptTokens = lastPromptTokens(this.sessionManager.getBranch());
+        const cacheHitCost = price(model, { cacheRead: promptTokens });
+        const cacheMissCost = price(model, model.cost.cacheWrite > 0 ? { cacheWrite: promptTokens } : { input: promptTokens });
+        const warmCost = price(model, { cacheRead: promptTokens, output: 1 });
+        const missCost = Math.max(0, cacheMissCost - cacheHitCost);
+        const continuationProbability = run.phase === "idle" ? IDLE_CONTINUATION_PROBABILITY : 1;
+        const economicsAvailable = promptTokens > 0 && (cacheHitCost > 0 || cacheMissCost > 0);
+        const expectedSavings = continuationProbability * missCost - warmCost;
+        return {
+            phase: run.phase,
+            warmCost,
+            missCost,
+            continuationProbability,
+            expectedSavings,
+            economicsAvailable,
+            action: expectedSavings >= CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS ? "warm" : "stop",
+        };
+    }
+}
+function formatDollars(value) {
+    return value < 0 ? `-$${Math.abs(value).toFixed(3)}` : `$${value.toFixed(3)}`;
+}
+function formatCacheWarmingEconomics(decision) {
+    if (!decision.economicsAvailable)
+        return "cache economics unavailable";
+    const probability = Math.round(decision.continuationProbability * 100);
+    const probabilityText = decision.phase === "streaming"
+        ? `${probability}% continuation probability while agent is running`
+        : `${probability}% continuation probability`;
+    const comparison = decision.action === "warm" ? ">=" : "<";
+    return `${probabilityText}, expected savings ${formatDollars(decision.expectedSavings)} ${comparison} $${CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS.toFixed(3)}`;
+}
+function formatCacheWarmingDecisionTime(nextWarmAt, now) {
+    if (nextWarmAt === undefined || nextWarmAt <= now)
+        return "Decision now";
+    let remainingSeconds = Math.ceil((nextWarmAt - now) / 1000);
+    const hours = Math.floor(remainingSeconds / 3600);
+    remainingSeconds %= 3600;
+    const minutes = Math.floor(remainingSeconds / 60);
+    const seconds = remainingSeconds % 60;
+    const parts = [];
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    if (seconds > 0 || parts.length === 0)
+        parts.push(`${seconds}s`);
+    return `Decision in ${parts.join(" ")}`;
+}
+/** One-line status for `/session`. */
+export function formatCacheWarmingStatus(status, now = Date.now()) {
+    const decision = status.decision;
+    // A decision is attached once relay (or an extension) acted on it; "inactive"
+    // without one never got that far.
+    if (!decision || (status.state === "inactive" && !decision.economicsAvailable && !status.extensionOverride)) {
+        return `Inactive (${status.reason ?? "unknown reason"})`;
+    }
+    const details = status.extensionOverride
+        ? `extension override, ${formatCacheWarmingEconomics(decision)}`
+        : `${formatCacheWarmingEconomics(decision)} -> ${decision.action}`;
+    if (status.state === "inactive")
+        return `Stopped (${details})`;
+    if (status.state === "refreshing")
+        return `Warming cache (${details})`;
+    return `${formatCacheWarmingDecisionTime(status.nextWarmAt, now)} (${details})`;
+}
+/** One-line transcript text for persisted cache-warming usage. */
+export function formatCacheWarmingUsage(entry) {
+    const note = entry.note ? ` (${entry.note})` : "";
+    const cost = entry.usage.cost.total.toFixed(6).replace(/(\.\d{3}\d*?)0+$/, "$1");
+    return `Cache warmed${note}: $${cost}`;
+}
+//# sourceMappingURL=cache-warmer.js.map