@arnilo/prism 0.7.0 → 0.9.0

package/dist/attention-compiler.js

@@ -7,7 +7,7 @@
 import { createHash } from "node:crypto";
 import { estimateMessageBytes, estimateMessageTokens, estimateTextBytes, measureInputCost, } from "./context-budget.js";
 import { assertCompactionTrigger } from "./contracts-core/compaction.js";
-import { capToolResultSummary, foldedToolResultHeader, inferToolResultTurns, toolResultFoldText, } from "./tool-result-fold.js";
+import { capToolResultSummary, foldedToolResultHeader, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, inferToolResultTurns, toolResultFoldText, } from "./tool-result-fold.js";
 export const ATTENTION_BUDGET_ERROR_CODE = "attention_budget_exceeded";
 /** C9: still over `triggerRatio` after every eligible stage — host should compact, not delete. */
 export class AttentionBudgetError extends Error {
@@ -44,6 +44,19 @@ function resolveCount(value, fallback, name) {
     }
     return value;
 }
+/** `resolveRatio` for a value with no default: an axis ratio is required. */
+function requiredRatio(value, name) {
+    if (value === undefined)
+        throw new TypeError(`${name} must be a number in (0, 1)`);
+    return resolveRatio(value, DEFAULT_ATTENTION_TRIGGER_RATIO, name);
+}
+function resolveBoolean(value, name) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== "boolean")
+        throw new TypeError(`${name} must be a boolean`);
+    return value;
+}
 export function resolveAttentionReserveTokens(value) {
     return resolveCount(value, DEFAULT_ATTENTION_RESERVE_TOKENS, "attentionCompiler.reserveTokens");
 }
@@ -92,29 +105,170 @@ function resolveExcludeTools(value) {
     }
     return Object.freeze(out);
 }
+/** Normalize one configured axis, freezing it. Unnamed predicates are wrapped so the evaluator
+ *  sees one shape; every failure is a config-time `TypeError` naming the option. */
+function normalizeAttentionTrigger(value, name) {
+    if (typeof value === "function")
+        return Object.freeze({ kind: "predicate", shouldFold: value });
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError(`${name} must be a trigger object, a predicate function, or an array of them`);
+    }
+    const kind = value.kind;
+    switch (kind) {
+        case "input_ratio":
+        case "run_input_ratio":
+            return Object.freeze({ kind, ratio: requiredRatio(value.ratio, `${name}.ratio`) });
+        case "token_floor": {
+            const tokens = value.tokens;
+            if (!Number.isSafeInteger(tokens) || tokens < 1) {
+                throw new TypeError(`${name}.tokens must be a positive safe integer`);
+            }
+            return Object.freeze({ kind, tokens: tokens });
+        }
+        case "predicate": {
+            const shouldFold = value.shouldFold;
+            if (typeof shouldFold !== "function")
+                throw new TypeError(`${name}.shouldFold must be a function`);
+            return Object.freeze({ kind, shouldFold: shouldFold });
+        }
+        default:
+            throw new TypeError(`unknown ${name} kind: ${String(kind)} (expected input_ratio, run_input_ratio, token_floor, or predicate)`);
+    }
+}
+/** Fold axes for a compiler: exactly the configured `trigger`, or the `triggerRatio` axis alone
+ *  (plan 074 behavior) when none is. Frozen, in evaluation order. */
+function resolveAttentionTriggerAxes(triggerRatio, value) {
+    if (value === undefined)
+        return Object.freeze([Object.freeze({ kind: "input_ratio", ratio: triggerRatio })]);
+    const entries = Array.isArray(value) ? value : [value];
+    if (entries.length === 0) {
+        throw new TypeError("attentionCompiler.trigger must be a trigger object, a predicate function, or a non-empty array of them");
+    }
+    const single = entries.length === 1;
+    return Object.freeze(entries.map((entry, index) => normalizeAttentionTrigger(entry, single ? "attentionCompiler.trigger" : `attentionCompiler.trigger[${index}]`)));
+}
+/** Resolved `RunLimits.maxInputTokens`; `null` disables the cap, so it is no budget either. */
+function resolveAttentionRunInputBudget(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError("attentionCompiler.runInputBudget must be a positive safe integer");
+    }
+    return value;
+}
+/**
+ * Build the frozen per-turn state the axes read: the compiler supplies the cap and the run budget
+ * (so a caller cannot silently drop the budget and fall back to the input cap), the caller
+ * supplies what only the turn knows.
+ */
+export function attentionTriggerState(compiler, turn) {
+    return Object.freeze({
+        estimatedInputTokens: turn.estimatedInputTokens,
+        inputCapTokens: compiler.inputCap,
+        ...(compiler.runInputBudget === undefined ? {} : { runInputBudgetTokens: compiler.runInputBudget }),
+        runInputTokens: turn.runInputTokens ?? 0,
+        turn: turn.turn ?? 1,
+    });
+}
+/**
+ * Evaluate the fold axes in order against one turn's state; the first axis that fires wins, and
+ * its `targetTokens` (when it has one) is what the stages fold to. Called at most twice per turn —
+ * once at turn start, once after the stages — so a host predicate never runs per row.
+ */
+export function evaluateAttentionTrigger(axes, state) {
+    for (const axis of axes) {
+        switch (axis.kind) {
+            case "input_ratio": {
+                const targetTokens = axis.ratio * state.inputCapTokens;
+                if (state.estimatedInputTokens >= targetTokens) {
+                    return { shouldFold: true, firedAxis: "input_ratio", targetTokens, failsClosed: true };
+                }
+                continue;
+            }
+            case "token_floor":
+                if (state.estimatedInputTokens >= axis.tokens) {
+                    return { shouldFold: true, firedAxis: "token_floor", targetTokens: axis.tokens, failsClosed: true };
+                }
+                continue;
+            case "run_input_ratio": {
+                const budget = state.runInputBudgetTokens;
+                if (budget === undefined) {
+                    // No run budget declared: the axis is the per-request ratio comparison.
+                    const targetTokens = axis.ratio * state.inputCapTokens;
+                    if (state.estimatedInputTokens >= targetTokens) {
+                        return { shouldFold: true, firedAxis: "run_input_ratio", targetTokens, failsClosed: true };
+                    }
+                    continue;
+                }
+                if (state.runInputTokens + state.estimatedInputTokens < axis.ratio * budget)
+                    continue;
+                // Cumulative: the spend is already booked, so folding cannot settle the axis. No
+                // per-request target (fold every eligible row) and no fail-closed throw — the run limit
+                // owns the cap, and folding is what keeps the run under it.
+                return { shouldFold: true, firedAxis: "run_input_ratio", failsClosed: false };
+            }
+            case "predicate": {
+                const fired = axis.shouldFold(state);
+                if (typeof fired !== "boolean") {
+                    throw new TypeError("attentionCompiler.trigger predicate must return a boolean (use a synchronous function)");
+                }
+                if (fired)
+                    return { shouldFold: true, firedAxis: "predicate", failsClosed: true };
+                continue;
+            }
+        }
+    }
+    return { shouldFold: false, failsClosed: false };
+}
 /** Validate compiler options + resolve the input cap. No provider I/O; unknown or
  *  unresolvable input throws here rather than on the first turn. */
 export function createAttentionCompiler(options = {}, context = {}) {
     if (typeof options !== "object" || options === null)
         throw new TypeError("attentionCompiler options must be an object");
     const triggerRatio = resolveRatio(options.triggerRatio, DEFAULT_ATTENTION_TRIGGER_RATIO, "attentionCompiler.triggerRatio");
+    const triggerAxes = resolveAttentionTriggerAxes(triggerRatio, options.trigger);
+    // Reference ratio the handle reports and `compactRatio` / the compaction trigger are checked
+    // against: the explicit `triggerRatio`, else the first `input_ratio` axis, so a `trigger` that
+    // replaces the gate still reports the ratio that gate actually folds at.
+    let referenceRatio = triggerRatio;
+    if (options.triggerRatio === undefined) {
+        for (const axis of triggerAxes) {
+            if (axis.kind === "input_ratio") {
+                referenceRatio = axis.ratio;
+                break;
+            }
+        }
+    }
     const compactRatio = resolveRatio(options.compactRatio, DEFAULT_ATTENTION_COMPACT_RATIO, "attentionCompiler.compactRatio");
-    if (compactRatio <= triggerRatio) {
-        throw new TypeError(`attentionCompiler.compactRatio (${compactRatio}) must exceed triggerRatio (${triggerRatio})`);
+    if (compactRatio <= referenceRatio) {
+        throw new TypeError(`attentionCompiler.compactRatio (${compactRatio}) must exceed triggerRatio (${referenceRatio})`);
     }
     const thinkingKeepTurns = resolveCount(options.thinkingKeepTurns, DEFAULT_ATTENTION_THINKING_KEEP_TURNS, "attentionCompiler.thinkingKeepTurns");
     const keepLast = resolveCount(options.keepLast, DEFAULT_ATTENTION_KEEP_LAST, "attentionCompiler.keepLast");
     const inputCap = resolveInputCap(options, context.model);
     const reserveTokens = resolveAttentionReserveTokens(options.reserveTokens);
     const excludeTools = resolveExcludeTools(options.excludeTools);
+    const runInputBudget = resolveAttentionRunInputBudget(context.runInputBudget);
+    const durable = resolveBoolean(options.durable, "attentionCompiler.durable");
     const trigger = context.compactionTrigger;
     if (trigger !== undefined) {
         assertCompactionTrigger(trigger);
-        if (trigger.type === "input_ratio" && trigger.ratio <= triggerRatio) {
-            throw new TypeError(`compaction input_ratio (${trigger.ratio}) must exceed attentionCompiler.triggerRatio (${triggerRatio})`);
+        if (trigger.type === "input_ratio" && trigger.ratio <= referenceRatio) {
+            throw new TypeError(`compaction input_ratio (${trigger.ratio}) must exceed attentionCompiler.triggerRatio (${referenceRatio})`);
         }
     }
-    return Object.freeze({ inputCap, reserveTokens, triggerRatio, compactRatio, thinkingKeepTurns, keepLast, excludeTools });
+    return Object.freeze({
+        inputCap,
+        reserveTokens,
+        triggerRatio: referenceRatio,
+        compactRatio,
+        thinkingKeepTurns,
+        keepLast,
+        excludeTools,
+        trigger: triggerAxes,
+        durable,
+        ...(runInputBudget === undefined ? {} : { runInputBudget }),
+    });
 }
 /* ------------------------------------------------------------------------------------------------
  * Opt-in wiring (Task 5)
@@ -154,8 +308,11 @@ function mergeAttentionRunOverlay(base, overlay) {
         }
         return value;
     };
-    if (overlay.maxInputTokens !== undefined || overlay.reserveTokens !== undefined) {
-        throw new TypeError("RunOptions.attentionCompiler must not set maxInputTokens or reserveTokens: the input cap is agent-config only");
+    if (overlay.maxInputTokens !== undefined ||
+        overlay.reserveTokens !== undefined ||
+        overlay.trigger !== undefined ||
+        overlay.durable !== undefined) {
+        throw new TypeError("RunOptions.attentionCompiler must not set maxInputTokens, reserveTokens, trigger, or durable: the input cap, the gate, and fold durability are agent-config only");
     }
     const triggerRatio = gate("triggerRatio", DEFAULT_ATTENTION_TRIGGER_RATIO);
     const compactRatio = gate("compactRatio", DEFAULT_ATTENTION_COMPACT_RATIO);
@@ -174,7 +331,11 @@ function mergeAttentionRunOverlay(base, overlay) {
 /** Resolve the run's compiler from the agent setting plus an optional run overlay, validating
  *  both eagerly (no provider I/O) so a typo fails at run start, not on some later turn (C12).
  *  Returns `undefined` when the compiler is off — the assembly path then allocates nothing. */
-export function resolveRunAttentionCompiler(agent, run, model) {
+export function resolveRunAttentionCompiler(agent, run, model, runInputBudget) {
+    const context = {
+        model,
+        ...(runInputBudget === undefined || runInputBudget === null ? {} : { runInputBudget }),
+    };
     const enabled = enabledAttentionSetting(agent);
     if (enabled === undefined) {
         if (run !== undefined && run !== false) {
@@ -185,11 +346,11 @@ export function resolveRunAttentionCompiler(agent, run, model) {
     if (run === false)
         return undefined;
     if (run === undefined || run === true)
-        return createAttentionCompiler(enabled, { model });
+        return createAttentionCompiler(enabled, context);
     if (typeof run !== "object" || run === null || Array.isArray(run)) {
         throw new TypeError("RunOptions.attentionCompiler must be false or an options object");
     }
-    return createAttentionCompiler(mergeAttentionRunOverlay(enabled, run), { model });
+    return createAttentionCompiler(mergeAttentionRunOverlay(enabled, run), context);
 }
 export function createAttentionStickyFrontier() {
     return { thinking: new Set(), toolCallIds: new Set() };
@@ -215,15 +376,30 @@ export async function compileAttention(options) {
     const { compiler, groups } = options;
     const turn = options.turn ?? 1;
     const frontier = options.frontier;
-    const triggerTokens = compiler.triggerRatio * compiler.inputCap;
+    const runInputTokens = options.runInputTokens ?? 0;
+    // One frozen state per evaluation: predicates never see a live object they could mutate, and
+    // the axes are evaluated at most twice a turn (turn start, then after the stages).
+    const triggerState = (estimatedInputTokens) => attentionTriggerState(compiler, { estimatedInputTokens, runInputTokens, turn });
     const usedAtStart = measureInputCost({ groups, context: options.context, skills: options.skills, tools: options.tools }).tokens;
+    const decision = evaluateAttentionTrigger(compiler.trigger, triggerState(usedAtStart));
+    const targetTokens = decision.targetTokens;
+    const gateOpen = decision.shouldFold;
     let used = usedAtStart;
-    const over = () => used >= triggerTokens;
+    // The gate is decided once per turn against the assembled estimate; the per-row loop then only
+    // compares numbers, so a predicate axis costs one call, not one per eligible row. A target-less
+    // axis (cumulative run budget, predicate) folds every eligible row.
+    const needsMore = () => gateOpen && (targetTokens === undefined || used >= targetTokens);
+    /** Post-stage verdict: a per-request axis still over its target, or a target-less axis whose
+     *  predicate still fires, fails closed. A cumulative run-budget axis never does. */
+    const stillFired = () => targetTokens !== undefined
+        ? used >= targetTokens
+        : decision.failsClosed && evaluateAttentionTrigger(compiler.trigger, triggerState(Math.max(0, used))).shouldFold;
     const history = [...groups.history];
     const toolResults = [...groups.toolResults];
     let droppedThinkingTurns = 0;
     let stubbedToolResults = 0;
     let stubbedBytes = 0;
+    let newFoldedBodies = 0;
     let leftEligible = 0;
     // Stage 1 — strip thinking from every assistant turn except the newest `thinkingKeepTurns`.
     const rowTurns = inferToolResultTurns(history);
@@ -233,7 +409,7 @@ export async function compileAttention(options) {
             continue;
         const key = thinkingKey(message, options.redactor);
         const sticky = frontier?.thinking.has(key) === true;
-        if (!sticky && !over()) {
+        if (!sticky && !needsMore()) {
             leftEligible += 1;
             continue;
         }
@@ -247,11 +423,12 @@ export async function compileAttention(options) {
     // and the in-flight group (which is always newer than history).
     for (const target of toolResultTargets({ history, toolResults, rowTurns, turn, compiler, fold: options.fold })) {
         const sticky = frontier?.toolCallIds.has(target.toolCallId) === true;
-        if (!sticky && !over()) {
+        if (!sticky && !needsMore()) {
             leftEligible += 1;
             continue;
         }
-        const stubbed = await stubToolResultMessage(target, options);
+        const folded = await foldedBody(target, options);
+        const stubbed = stubToolResultMessage(target, folded.body);
         const before = estimateMessageTokens(target.message);
         const after = estimateMessageTokens(stubbed);
         if (after >= before && !sticky) {
@@ -259,6 +436,8 @@ export async function compileAttention(options) {
             leftEligible += 1;
             continue;
         }
+        if (!folded.cached && rememberFold(options.attentionFold, target.toolCallId, folded.body))
+            newFoldedBodies += 1;
         const beforeBytes = estimateMessageBytes(target.message);
         target.update(stubbed);
         used -= before - after;
@@ -266,8 +445,9 @@ export async function compileAttention(options) {
         stubbedBytes += Math.max(0, beforeBytes - estimateMessageBytes(stubbed));
         rememberToolCall(frontier, target.toolCallId);
     }
-    if (over()) {
-        throw new AttentionBudgetError(`attention budget exceeded: estimated ${used} tokens >= ${Math.ceil(triggerTokens)} (triggerRatio ${compiler.triggerRatio} of inputCap ${compiler.inputCap}) after dropping ${droppedThinkingTurns} thinking turns and stubbing ${stubbedToolResults} tool results`);
+    if (gateOpen && stillFired()) {
+        const threshold = targetTokens === undefined ? String(decision.firedAxis) : Math.ceil(targetTokens);
+        throw new AttentionBudgetError(`attention budget exceeded: estimated ${used} tokens >= ${threshold} (${gateDetail(compiler, decision)}) after dropping ${droppedThinkingTurns} thinking turns and stubbing ${stubbedToolResults} tool results`);
     }
     const mutated = droppedThinkingTurns > 0 || stubbedToolResults > 0;
     return {
@@ -278,15 +458,26 @@ export async function compileAttention(options) {
             usedAfter: Math.max(0, used),
             inputCap: compiler.inputCap,
             triggerRatio: compiler.triggerRatio,
+            ...(decision.firedAxis === undefined ? {} : { firedAxis: decision.firedAxis }),
             droppedThinkingTurns,
             stubbedToolResults,
             stubbedBytes,
+            newFoldedBodies,
             truncated: leftEligible > 0,
             ...(options.runId === undefined ? {} : { runId: options.runId }),
             ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
         },
     };
 }
+/** Error detail for the fail-closed throw: the legacy wording for the plain `triggerRatio` axis,
+ *  the axis name (and run budget, when one is in play) for every other axis. */
+function gateDetail(compiler, decision) {
+    if (decision.firedAxis === "input_ratio" && decision.targetTokens === compiler.triggerRatio * compiler.inputCap) {
+        return `triggerRatio ${compiler.triggerRatio} of inputCap ${compiler.inputCap}`;
+    }
+    const budget = compiler.runInputBudget === undefined ? "" : ` with run input budget ${compiler.runInputBudget}`;
+    return `${String(decision.firedAxis)} gate of inputCap ${compiler.inputCap}${budget}`;
+}
 /** Thinking-bearing assistant-message indexes, oldest first, excluding the newest `keepTurns`.
  *  Counts thinking turns, not assistant messages, so a thinking-free reply does not push an
  *  older reasoning block out of the keep window. */
@@ -338,11 +529,17 @@ function toolResultTargets(options) {
         return estimateTextBytes(toolResultFoldText(block.result, block.error, message.content)) >= fold.minBytes;
     });
 }
-async function stubToolResultMessage(target, options) {
+/** The stub body for one row: the ledger's copy when it has one, the host `summarize`
+ *  otherwise. `cached` is the turn's summarize saving — a miss is the only case that costs a
+ *  host call, and the only case a durable run has new fold state to checkpoint. */
+async function foldedBody(target, options) {
+    const cached = options.attentionFold?.bodies.get(target.toolCallId);
+    if (cached !== undefined)
+        return { body: cached, cached: true };
     const { block, message } = target;
     const text = toolResultFoldText(block.result, block.error, message.content);
     const fold = options.fold;
-    const summary = fold
+    const body = fold
         ? capToolResultSummary(String(await fold.summarize({
             sessionId: options.sessionId ?? "",
             runId: options.runId ?? "",
@@ -352,9 +549,13 @@ async function stubToolResultMessage(target, options) {
             text,
         })), fold.maxSummaryBytes)
         : attentionStubText(options.redactor?.redact(text) ?? text);
+    return { body, cached: false };
+}
+function stubToolResultMessage(target, body) {
+    const { message } = target;
     return {
         ...message,
-        content: message.content.map((part) => part.type === "tool_result" ? { ...part, result: foldedToolResultHeader(target.toolName, target.toolCallId, summary) } : part),
+        content: message.content.map((part) => part.type === "tool_result" ? { ...part, result: foldedToolResultHeader(target.toolName, target.toolCallId, body) } : part),
         metadata: { ...message.metadata, prismFolded: true },
     };
 }
@@ -448,6 +649,66 @@ export function restoreAttentionStickyFrontier(persisted) {
         frontier.toolCallIds.add(id);
     return frontier;
 }
+export function createAttentionFoldLedger() {
+    return { bodies: new Map() };
+}
+/** Live and persisted ledger caps. One body is bounded by the fold's own `maxSummaryBytes`
+ *  (hard cap 4 KiB), so the entry count is what bounds a durable checkpoint. */
+const MAX_ATTENTION_FOLD_BODIES = 64;
+const ATTENTION_FOLD_SCHEMA_VERSION = 1;
+/** Keep the newest `max` entries: a session that folds more rows than the cap keeps the recent
+ *  bodies and re-summarizes the oldest if their rows are ever folded again. */
+function trimOldest(bodies, max) {
+    while (bodies.size > max) {
+        const oldest = bodies.keys().next().value;
+        if (oldest === undefined)
+            break;
+        bodies.delete(oldest);
+    }
+}
+/** Record one folded body, keeping the live ledger inside its caps. Returns `false` for a body
+ *  too large to be worth a checkpoint byte (the fold's own cap makes this host-only in practice). */
+function rememberFold(ledger, toolCallId, body) {
+    if (!ledger || estimateTextBytes(body) > HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES)
+        return false;
+    ledger.bodies.delete(toolCallId);
+    ledger.bodies.set(toolCallId, body);
+    trimOldest(ledger.bodies, MAX_ATTENTION_FOLD_BODIES);
+    return true;
+}
+/** Bounded snapshot of a live ledger; caller-owned (the runtime persists it, the compiler never
+ *  writes anywhere). */
+export function serializeAttentionFoldLedger(ledger) {
+    return {
+        v: ATTENTION_FOLD_SCHEMA_VERSION,
+        bodies: [...ledger.bodies].slice(-MAX_ATTENTION_FOLD_BODIES).map(([id, body]) => ({ id, body })),
+    };
+}
+/** Validate a persisted ledger from an untrusted store (plan 086 T3). Malformed *entries* are
+ *  dropped one by one — a body the compiler cannot trust simply re-summarizes on the next turn —
+ *  while a malformed *shape* yields `undefined` so the caller starts from an empty ledger.
+ *  Never throws: a resume must not fail because a checkpoint was hand-edited. */
+export function restoreAttentionFoldLedger(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const bodies = value.bodies;
+    if (!Array.isArray(bodies))
+        return undefined;
+    const ledger = createAttentionFoldLedger();
+    for (const entry of bodies) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const { id, body } = entry;
+        if (typeof id !== "string" || id.length === 0 || id.length > MAX_ATTENTION_TOOL_CALL_ID_CHARS || id.includes("\u0000"))
+            continue;
+        if (typeof body !== "string" || body.length === 0 || estimateTextBytes(body) > HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES)
+            continue;
+        ledger.bodies.delete(id);
+        ledger.bodies.set(id, body);
+    }
+    trimOldest(ledger.bodies, MAX_ATTENTION_FOLD_BODIES);
+    return ledger;
+}
 /** Consecutive `truncated` turns that arm compaction by default. */
 export const DEFAULT_ATTENTION_TRUNCATION_THRESHOLD = 2;
 export function createAttentionTruncationTrigger(options = {}) {

package/dist/cache-helpers.d.ts

@@ -14,8 +14,10 @@ export type CacheControlledMessage = Omit<Message, "content"> & {
     readonly content: readonly CacheControlledContentBlock[];
 };
 export interface CacheUsageReport {
-    readonly cacheReadTokens: number;
-    readonly cacheWriteTokens: number;
+    /** Present only when the provider reported cache-read usage; never fabricated as zero. */
+    readonly cacheReadTokens?: number;
+    /** Present only when the provider reported cache-write usage; never fabricated as zero. */
+    readonly cacheWriteTokens?: number;
     readonly hitRate?: number;
     readonly estimatedSavings?: number;
     readonly currency?: string;

package/dist/cache-helpers.js

@@ -67,15 +67,17 @@ export function cacheSavings(usage, model) {
     return (read * Math.max(0, input - cacheRead)) / costUnitDivisor(model.cost?.unit);
 }
 export function cacheUsageReport(usage, model) {
-    if (!usage)
+    if (!usage || (usage.cacheReadTokens === undefined && usage.cacheWriteTokens === undefined))
         return undefined;
     const estimatedSavings = model ? cacheSavings(usage, model) : undefined;
+    const currency = estimatedSavings === undefined ? usage.currency : (model?.cost?.currency ?? usage.currency);
+    const hitRate = cacheHitRate(usage);
     return {
-        cacheReadTokens: usage.cacheReadTokens ?? 0,
-        cacheWriteTokens: usage.cacheWriteTokens ?? 0,
-        hitRate: cacheHitRate(usage),
-        estimatedSavings,
-        currency: estimatedSavings === undefined ? usage.currency : (model?.cost?.currency ?? usage.currency),
+        ...(usage.cacheReadTokens === undefined ? {} : { cacheReadTokens: usage.cacheReadTokens }),
+        ...(usage.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: usage.cacheWriteTokens }),
+        ...(hitRate === undefined ? {} : { hitRate }),
+        ...(estimatedSavings === undefined ? {} : { estimatedSavings }),
+        ...(currency === undefined ? {} : { currency }),
     };
 }
 export function resolveBreakpoint(messages, breakpoint) {

package/dist/checkpoint-restore.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Checkpoint restore hooks (plan 094 Task 3). A hook restores one external layer (git commit,
+ * document version, workspace fingerprint) recorded in a checkpoint's sidecar metadata.
+ *
+ * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails
+ * or times out aborts the resume with `CheckpointRestoreError` naming that hook, so the
+ * conversation restore never applies on top of a half-restored external world. Hosts that need
+ * every layer back where they were re-run the whole restore after fixing the failing layer.
+ */
+/** Per-hook ceiling for a restore (plan 094 Task 3 default). */
+export declare const DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS = 10000;
+/** One hook that completed during a restore. */
+export interface CheckpointRestoreAuditEntry {
+    readonly hook: string;
+    readonly durationMs: number;
+}
+/** Audit of a completed restore: every hook that ran, in order. */
+export interface CheckpointRestoreAudit {
+    readonly hooks: readonly CheckpointRestoreAuditEntry[];
+    readonly durationMs: number;
+}
+/**
+ * Host code restoring one external layer. `signal` aborts on the per-hook timeout and on the
+ * caller's abort, so a hook that talks to a remote system can cancel instead of dangling.
+ */
+export type CheckpointRestoreHook<Context> = (checkpoint: Context, signal: AbortSignal) => void | Promise<void>;
+/** Thrown when a restore hook fails or times out; the checkpoint and conversation are untouched. */
+export declare class CheckpointRestoreError extends Error {
+    readonly code = "ERR_PRISM_CHECKPOINT_RESTORE";
+    /** Name of the failing hook (`fn.name` or `hook[i]`). */
+    readonly hook: string;
+    constructor(hook: string, cause: unknown);
+}
+export interface RunCheckpointRestoreHooksOptions {
+    /** Per-hook timeout; defaults to `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+    /** Caller abort: checked between hooks and combined into each hook's signal. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Run restore hooks sequentially and report the audit. A hook failure throws
+ * `CheckpointRestoreError` immediately (later hooks do not run); an already-aborted caller signal
+ * throws its own abort reason so the resume reads as cancelled rather than as a restore failure.
+ */
+export declare function runCheckpointRestoreHooks<Context>(hooks: readonly CheckpointRestoreHook<Context>[], context: Context, options?: RunCheckpointRestoreHooksOptions): Promise<CheckpointRestoreAudit>;

package/dist/checkpoint-restore.js

@@ -0,0 +1,54 @@
+/**
+ * Checkpoint restore hooks (plan 094 Task 3). A hook restores one external layer (git commit,
+ * document version, workspace fingerprint) recorded in a checkpoint's sidecar metadata.
+ *
+ * All-or-nothing: hooks run before the resume claims the checkpoint. The first hook that fails
+ * or times out aborts the resume with `CheckpointRestoreError` naming that hook, so the
+ * conversation restore never applies on top of a half-restored external world. Hosts that need
+ * every layer back where they were re-run the whole restore after fixing the failing layer.
+ */
+/** Per-hook ceiling for a restore (plan 094 Task 3 default). */
+export const DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS = 10_000;
+/** Thrown when a restore hook fails or times out; the checkpoint and conversation are untouched. */
+export class CheckpointRestoreError extends Error {
+    code = "ERR_PRISM_CHECKPOINT_RESTORE";
+    /** Name of the failing hook (`fn.name` or `hook[i]`). */
+    hook;
+    constructor(hook, cause) {
+        super(`Checkpoint restore hook ${hook} failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = "CheckpointRestoreError";
+        this.hook = hook;
+    }
+}
+/**
+ * Run restore hooks sequentially and report the audit. A hook failure throws
+ * `CheckpointRestoreError` immediately (later hooks do not run); an already-aborted caller signal
+ * throws its own abort reason so the resume reads as cancelled rather than as a restore failure.
+ */
+export async function runCheckpointRestoreHooks(hooks, context, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS;
+    const started = Date.now();
+    const entries = [];
+    for (const [index, hook] of hooks.entries()) {
+        options.signal?.throwIfAborted();
+        const name = hook.name || `hook[${index}]`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+        const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+        const hookStarted = Date.now();
+        try {
+            await hook(context, signal);
+        }
+        catch (error) {
+            // Our own abort means the hook either ignored the signal or lost the race; name the timeout.
+            const timedOut = controller.signal.aborted && !options.signal?.aborted;
+            throw new CheckpointRestoreError(name, timedOut ? controller.signal.reason : error);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        entries.push({ hook: name, durationMs: Date.now() - hookStarted });
+    }
+    return { hooks: entries, durationMs: Date.now() - started };
+}
+//# sourceMappingURL=checkpoint-restore.js.map

package/dist/checkpoints.js

@@ -23,8 +23,11 @@ export function createMemoryCheckpointStore(options = {}) {
             }
             const id = recordKey(input);
             const existing = records.get(id);
-            if (existing)
-                assertOwnership(input, existing);
+            // A foreign-owned record is indistinguishable from a CAS miss: never an
+            // ownership-shaped error (plan 080 Task 3).
+            if (existing && !ownershipMatches(input, existing)) {
+                throw new CheckpointConflictError(`Checkpoint compare-and-swap failed (expected ${input.expectedVersion ?? 0}, current ${existing.version})`);
+            }
             if (input.expectedVersion !== undefined && input.expectedVersion !== (existing?.version ?? 0)) {
                 throw new CheckpointConflictError(`Checkpoint compare-and-swap failed (expected ${input.expectedVersion}, current ${existing?.version ?? 0})`);
             }
@@ -66,8 +69,7 @@ export function createMemoryCheckpointStore(options = {}) {
             const record = records.get(recordKey(input));
             if (!record)
                 return null;
-            assertOwnership(input, record);
-            return record;
+            return ownershipMatches(input, record) ? record : null;
         },
         async listCheckpoints(query = {}) {
             throwIfAborted(query.signal);
@@ -94,8 +96,7 @@ export function createMemoryCheckpointStore(options = {}) {
             const record = records.get(id);
             if (!record)
                 return false;
-            assertOwnership(input, record);
-            return records.delete(id);
+            return ownershipMatches(input, record) ? records.delete(id) : false;
         },
     };
 }
@@ -121,11 +122,6 @@ function ownershipFilterMatches(expected, actual) {
         (expected.accountId === undefined || expected.accountId === actual.accountId) &&
         (expected.userId === undefined || expected.userId === actual.userId));
 }
-function assertOwnership(expected, actual) {
-    if (!ownershipMatches(expected, actual)) {
-        throw new CheckpointConflictError("Checkpoint ownership mismatch");
-    }
-}
 function cloneJson(value, label) {
     try {
         const encoded = JSON.stringify(value);

package/dist/context-budget.d.ts

@@ -1,4 +1,4 @@
-import type { ContextBlock, InputAssemblyLayout, Message, ProviderRequest, Skill, ToolDefinition } from "./contracts.js";
+import type { ContextBlock, InputAssemblyLayout, Message, ProviderRequest, Skill, TokenEstimate, ToolDefinition } from "./contracts.js";
 import { type LoadedSkillSet, type SkillRenderContext, type SkillsDisclosure } from "./skill-disclosure.js";
 /**
  * Host-supplied token estimator. Budget-only: it never reaches billing, provider
@@ -55,6 +55,7 @@ export declare function isContextBudgetError(error: unknown): error is ContextBu
 export declare function estimateTextTokens(text: string): number;
 export declare function estimateTextBytes(text: string): number;
 export declare function estimateMessageTokens(message: Message, estimateTokens?: TokenEstimator): number;
+export declare function estimateMessageTokens(messages: readonly Message[], modelFamily?: string): TokenEstimate;
 export declare function estimateMessageBytes(message: Message): number;
 export declare function estimateAssemblyTokens(messages: readonly Message[]): number;
 export declare function resolveContextBudget(budget: ContextBudget): Required<Pick<ContextBudget, "reportOmissions">> & ContextBudget;