@basein/runner 0.3.25 → 0.3.26

package/dist/replay/controller.js

@@ -22,7 +22,7 @@ import { BuiltinNotRunnable, BuiltinTimeout, FILE_BUILTINS, parseBashAllow, pars
 import { BASH_CHANNEL_MAX, MAX_REPLAY_REASON, testWords, truncate } from "./bundle.js";
 import { coverageOf, modeFor, reachOf } from "./coverage.js";
 import { deriveParameters, localDay, } from "./derive.js";
-import { buildHandoverNote, MAX_HANDOVER_NOTE, } from "./handover.js";
+import { buildHandoverNote, buildUnseenResultNote, MAX_HANDOVER_NOTE, } from "./handover.js";
 import { NO_PROXY, NoSessionProxyError, ProxyWorkQueue, QUEUE_CLOSED } from "./executor.js";
 import { logicTimeoutMs, MAX_LOGIC_TIMEOUT_MS } from "./logic.js";
 import { PREVIEW_BUDGET_MS, RecordedValueError, ScenarioReplayPlan, StepRunError, } from "./plan.js";
@@ -171,6 +171,56 @@ export const DEFAULT_INTENT_MATCH = {
     maxPerTurn: 3,
     maxRequestsPerTurn: 40,
 };
+/**
+ * Where the stopped step stood when a plan handed over, in the words the
+ * service reads (its recordings/repo.ts `handoverFamily`): did the step
+ * happen. Its tool ran and only its output could not be read: `ran`. It was
+ * sent and nothing came back: `uncertain`. Stopped in front of it — the plan's
+ * time ran out (`budget`), its caller left (`cancelled`), its test could not
+ * say whether this request needs it (`test_failed`) — it was never sent:
+ * `not_run`. Otherwise the stop's own reason (`not_run`, `failed`,
+ * `concurrent`, `host_rejected`, `host_edited`), and a plain failure, which
+ * carries none, reads `failed`.
+ *
+ * The service continues a hand-over only with work that was recorded where the
+ * step had not happened (`not_run`, `failed`): the agent's work there starts
+ * with that very step. Continued after a step that ran, or may have, the plan
+ * made of it ran the step a second time. The three stops in front of a step
+ * went out under their own names, which the service reads as "may have run":
+ * a plan stopped by its time budget was never continued.
+ */
+export function stopOf(h) {
+    if (h.ranThisStep)
+        return "ran";
+    if (h.inFlight)
+        return "uncertain";
+    if (h.stopReason === "budget" || h.stopReason === "cancelled" || h.stopReason === "test_failed")
+        return "not_run";
+    return h.stopReason ?? "failed";
+}
+/**
+ * Whether a run of the plan sent at least one of its calls: a step did its
+ * work, its tool answered with an error, its output could not be read after
+ * the tool ran, or it was sent and has not been seen through (a pin still out,
+ * a stop that may have happened). A step its test left out, one whose logic
+ * broke before its call, one that could not be sent and a recorded stand-in
+ * sent nothing — a plan that only did those has nothing a second run could
+ * repeat.
+ */
+export function sentACall(state) {
+    if (state.stepsPinned > 0 || state.pinned.size > 0 || (state.lingering?.size ?? 0) > 0)
+        return true;
+    const stop = state.handover?.stop;
+    if (stop === "ran" || stop === "uncertain" || stop === "host_edited")
+        return true;
+    for (const r of state.stepResults.values()) {
+        if (r.status === "ok")
+            return true;
+        if (r.status === "failed" && (r.stage === "tool_call" || r.stage === "tool_output_logic"))
+            return true;
+    }
+    return false;
+}
 /**
  * How long a call waits for the previous pin to thread before it is judged to
  * be running beside it: the control server's hook-view fallback
@@ -527,12 +577,23 @@ export class ReplayController {
         // reading that did not answer carries every target at its recorded
         // sample (derive.ts), and one of these must be the mark there too — never
         // last week's task name under a step that would create the task.
-        const oneHalf = hasTargets(scenario.paramsObject)
-            ? testedOnlyTargets(targetKeys(scenario.paramsObject), scenario.paramsObject, planned, scenario.paramsLogic)
+        const allTargets = hasTargets(scenario.paramsObject) ? targetKeys(scenario.paramsObject) : [];
+        const oneHalf = allTargets.length > 0
+            ? testedOnlyTargets(allTargets, scenario.paramsObject, planned, scenario.paramsLogic)
             : [];
-        const params = derivation.then((r) => r.derived || oneHalf.length === 0
+        // A reading that did not answer (no key, the service down, out of budget,
+        // too slow) names no target at all. Settings may stand on their recorded
+        // samples; a target never does, whichever way the plan reads it. Only the
+        // ones a step would act on outright make the gate below decline, and the
+        // rest are what targets.ts counts on: a chain that finds its own value
+        // (`(respParams.ranked || [])[0] ?? parameters.id`) keeps the caller's
+        // copy as a bare fallback, and that fallback is `null` there — as it is
+        // when the reading answered and found nothing. Left at its sample, the
+        // fallback was last week's device, and the step acted on it whenever the
+        // chain found nothing.
+        const params = derivation.then((r) => r.derived || allTargets.length === 0
             ? r.params
-            : { ...r.params, ...Object.fromEntries(oneHalf.map((key) => [key, null])) });
+            : { ...r.params, ...Object.fromEntries(allTargets.map((key) => [key, null])) });
         // `params` is awaited by the plan, and by gate 7 below when there is a
         // target. Without this, the losing race in gate 7 leaves `derivation`
         // rejected and unhandled, which takes the process down on an unhandled
@@ -665,7 +726,10 @@ export class ReplayController {
         if (this.recordedFallback && this.opts.authUrl && this.opts.authToken) {
             state.sourceRun = new SourceRunOutputs({
                 baseUrl: this.opts.authUrl,
-                runId: scenario.runId,
+                // The run the current chain was calculated from: for a plan repaired
+                // from a fresh recording that is not the run it is stored under, and a
+                // stand-in taken from the old one is the output of another chain.
+                runId: scenario.sourceRunId ?? scenario.runId,
                 token: this.opts.authToken,
                 fetchImpl: this.opts.fetchImpl,
             });
@@ -759,24 +823,63 @@ export class ReplayController {
      * against the plan; the outcome is `fell_back` when a step ran and `failed`
      * when none did, as for every hand-over. The note is the caller's to
      * deliver ({@link takeNote}). Returns false when there was no live plan.
+     *
+     * A step the adapter was given and has not reported back on may be running:
+     * the plan stops after it, as for a call beside a pin ({@link concurrentCall}),
+     * and the hand-over says the step may have happened — never "did not run",
+     * which the service would continue with work that starts by running it
+     * again. Its result is still read when it lands.
      */
     hostHandOver(state, why) {
         const plan = state.plan;
         if (!plan || state.retired)
             return false;
-        const position = plan.currentStepIndex;
-        this.handOver(state, {
-            kind: "step_failed",
-            step: plan.currentStep(),
-            position,
-            error: why === "own_call"
-                ? "the model made a call of its own, so the scenario stopped"
-                : why === "late"
-                    ? "its arguments were not ready in time"
-                    : "the run ended before this step",
-            delivery: "above",
-            stopReason: "not_run",
-        });
+        const reason = why === "own_call"
+            ? "the model made a call of its own, so the scenario stopped"
+            : why === "late"
+                ? "its arguments were not ready in time"
+                : "the run ended before this step";
+        const outstanding = [...state.pinned.values()][0];
+        if (!outstanding) {
+            this.handOver(state, {
+                kind: "step_failed",
+                step: plan.currentStep(),
+                position: plan.currentStepIndex,
+                error: reason,
+                delivery: "above",
+                stopReason: "not_run",
+            });
+            return true;
+        }
+        const inFlight = new Map(state.pinned);
+        const next = outstanding.stepIndex + 1;
+        if (next < plan.stepCount) {
+            this.handOver(state, {
+                kind: "step_failed",
+                step: plan.allSteps()[next],
+                position: next,
+                error: reason,
+                delivery: "above",
+                stopReason: "not_run",
+                ran: outstanding.stepIndex,
+                inFlight: { stepIndex: outstanding.stepIndex, toolName: outstanding.toolName },
+            });
+        }
+        else {
+            // The step out is the plan's last: the stop is that step, sent and not answered.
+            this.handOver(state, {
+                kind: "step_failed",
+                step: plan.allSteps()[outstanding.stepIndex],
+                position: outstanding.stepIndex,
+                error: why === "own_call"
+                    ? "it had not reported back when the model made a call of its own"
+                    : "it had not reported back when the run ended",
+                delivery: "above",
+                stopReason: "uncertain",
+                ran: outstanding.stepIndex,
+            });
+        }
+        state.lingering = inFlight;
         return true;
     }
     /**
@@ -858,14 +961,27 @@ export class ReplayController {
      */
     takeNote(state) {
         const h = state?.handover;
-        if (!h || h.delivered)
-            return undefined;
-        h.delivered = true;
-        logDetail("replay.handover_delivered", {
-            scenario: state.scenarioId ?? undefined,
-            bytes: h.note.length,
-        });
-        return h.note;
+        if (h && !h.delivered) {
+            h.delivered = true;
+            logDetail("replay.handover_delivered", {
+                scenario: state.scenarioId ?? undefined,
+                bytes: h.note.length,
+            });
+            return h.note;
+        }
+        // A plan that ran to its end with nobody there to read it has no
+        // hand-over, and this one note instead.
+        const u = state?.unseen;
+        if (u && !u.delivered) {
+            u.delivered = true;
+            logDetail("replay.unseen_delivered", { scenario: state.scenarioId ?? undefined, bytes: u.note.length });
+            return u.note;
+        }
+        return undefined;
+    }
+    /** Whether a note about this plan is still to be told to the model: a hand-over's, or the unseen results'. */
+    hasUndeliveredNote(state) {
+        return Boolean((state?.handover && !state.handover.delivered) || (state?.unseen && !state.unseen.delivered));
     }
     /**
      * Deliver text to the model in place of the tool call it was about to make:
@@ -1709,6 +1825,12 @@ export class ReplayController {
         const plan = state.plan;
         if (!plan || state.retired)
             return { ok: false, why: RUN_NO_PLAN };
+        // Only a direct plan is run here, and only one with no step pinned for the
+        // model's own call. A steer plan is stepped through by the model's calls,
+        // and a step it pinned and that is still in flight would run a second time
+        // under this run: the model told to call `run_scenario` by hand, beside it.
+        if (state.mode !== "direct" || state.pinned.size > 0)
+            return { ok: false, why: RUN_NO_PLAN };
         if (state.running)
             return state.running;
         const running = this.runArmedOnce(state, plan, signal).catch((err) => {
@@ -1799,7 +1921,14 @@ export class ReplayController {
             // out — is no saving at all: the turn it ended cost next to nothing and
             // says nothing about what the task costs. `handOver` books `fell_back`
             // (steps did run) or `failed`, and the report is not a measurement.
-            if (stop.reason === "cancelled")
+            //
+            // Whether the caller is gone is read here, after the run, and not only
+            // from the stop's own reason: a caller who leaves during a step sees the
+            // run go on to that step's end, and a step that then fails stops the run
+            // for its own reason. The note about it went to a closed request, and the
+            // model was never told which steps had run.
+            const callerGone = stop.reason === "cancelled" || signal?.aborted === true;
+            if (callerGone)
                 state.callerCancelled = true;
             // Nothing ran *here*: there is no bundle, only the task — a recorded
             // output is not a result that happened (plan.ts, DriveOptions).
@@ -1815,7 +1944,7 @@ export class ReplayController {
                 // A cancelled run's note is kept for the model's next call, alone —
                 // the bundle went to a caller who is gone — so it points at side
                 // effects in place, never at results "below" that nobody receives.
-                delivery: live && stop.reason !== "cancelled" ? "below" : "none",
+                delivery: live && !callerGone ? "below" : "none",
                 stopReason: stop.reason,
                 ran: live ? undefined : 0,
                 // An output-logic failure stops *after* its step's tool ran: the step
@@ -1824,7 +1953,7 @@ export class ReplayController {
                 // The other half (AC5): what the steps from here are for.
                 whenText: stop.whenText,
             });
-            if (stop.reason === "cancelled") {
+            if (callerGone) {
                 // The caller is gone and reads nothing. The note stays undelivered: a
                 // client that timed out hands the task back to the model in this same
                 // turn, and the model's next call is where it learns which steps
@@ -1922,6 +2051,29 @@ export class ReplayController {
             partial: result.partial || undefined,
             ms: Date.now() - state.armedAt,
         });
+        // The caller left during the last step, which the run does not interrupt:
+        // every step ran, and the answer goes to a closed request. Nothing stopped,
+        // so there is no hand-over note, and the model was never told that the
+        // steps ran — the next request of the same task ran them again, a second
+        // row, a second mail. So the turn is no measurement of the task, and the
+        // model is told once, at its next call or prompt (the server keeps the note
+        // for it: `stashCancelledNote`).
+        if (signal?.aborted) {
+            state.callerCancelled = true;
+            state.unseen = {
+                note: buildUnseenResultNote({
+                    intent: plan.intent ?? "",
+                    executed: result.executed,
+                    totalSteps: plan.totalSteps ?? state.stepsPlanned,
+                }),
+                delivered: false,
+            };
+            logLine("replay.cancelled", {
+                scenario: state.scenarioId ?? undefined,
+                ran: `${result.executed}/${plan.stepCount}`,
+                why: "the caller went away during the last step — every step ran and nobody read the results",
+            });
+        }
         return {
             ok: true,
             text: result.text,
@@ -2025,8 +2177,15 @@ export class ReplayController {
             // After a person's "no" the task ended early; after a changed call that
             // was the plan's first step, the turn made one model call fewer than
             // the task needs — the one the plan's call replaced.
+            //
+            // Nor one its caller cancelled, or one this plan was not armed for
+            // because it had been cancelled a moment before: the steps it did
+            // already ran in the turn before, so the agent's work is the rest of the
+            // task, and its cost is no measure of the whole.
             baselineEligible: d.siblings?.some((s) => s !== state && s.plan !== undefined) ||
                 state.hostStop !== undefined ||
+                state.callerCancelled === true ||
+                state.declined === "after_cancel" ||
                 d.cutShort === true
                 ? false
                 : undefined,
@@ -2106,17 +2265,30 @@ export class ReplayController {
             }
             return out;
         });
+        // The plan stops in front of a step the service parked, or whose owner
+        // froze it by hand (plan-services.md D8). An operator who asks for the run
+        // by id turns the gates off, not that: a frozen step is the one that must
+        // not run unattended — an install, a deploy — and the run ended up running
+        // it, and every step after it. It stops there, and says so (`stopped`).
+        const stopAt = stopIndex(scenario.steps, undefined);
+        if (stopAt === 0) {
+            return {
+                ok: false,
+                why: "the plan's first step is parked or frozen by hand, so it stops in front of it: nothing was run",
+            };
+        }
         const plan = new ScenarioReplayPlan({
             scenario,
             params,
             mode,
             fallbackTargets: "samples",
+            stopAt,
         });
         state.plan = plan;
         if (this.opts.authUrl && this.opts.authToken) {
             state.sourceRun = new SourceRunOutputs({
                 baseUrl: this.opts.authUrl,
-                runId: scenario.runId,
+                runId: scenario.sourceRunId ?? scenario.runId,
                 token: this.opts.authToken,
                 fetchImpl: this.opts.fetchImpl,
             });
@@ -2366,7 +2538,10 @@ export class ReplayController {
         // it as that half's evidence. Booked `diverged`, it never did.
         const otherHalf = stop?.kind === "other_branch";
         this.upgrade(state, broke || !didWork ? "failed" : otherHalf ? "fell_back" : "diverged");
-        state.stepsPinned += composed.executed;
+        // A step whose tool answered with an error did not do its work: it is not
+        // among the steps the plan "ran", whose saving is booked and whose note
+        // tells the model not to run them again (as `runArmedOnce` counts them).
+        state.stepsPinned += Math.max(0, composed.executed - composed.errored);
         // The headline number of this whole design: recovering from a divergence
         // costs nothing, because the proxies were already connected.
         logLine("replay.compose", {
@@ -2484,6 +2659,9 @@ export class ReplayController {
             stepIndex: step?.stepIndex ?? position,
             toolName: step?.toolName ?? undefined,
             error: stop.error,
+            ...(stop.kind === "step_failed"
+                ? { stop: stopOf({ ranThisStep: stop.stage === "tool_output_logic", stopReason: stop.reason }) }
+                : {}),
             note,
             delivered: true,
         };
@@ -2507,6 +2685,7 @@ export class ReplayController {
             stepIndex: h.step?.stepIndex ?? h.position,
             toolName: h.step?.toolName ?? undefined,
             error: h.error,
+            ...(h.kind === "step_failed" ? { stop: stopOf(h) } : {}),
             note: this.noteFor(state, h),
             delivered: false,
         };
@@ -3152,6 +3331,13 @@ function classifyWorkError(err, serverName) {
     if (message === QUEUE_CLOSED || /\bupstream is not available\b/i.test(message)) {
         return new StepRunError(message, "not_run");
     }
+    // A timeout, an interrupt, a dropped connection: sent, and not seen through,
+    // so its work may have happened — before the "MCP error" rule below, which
+    // would call `MCP error -32001: Request timed out` a failure the tool
+    // answered. The pinned path words it the same way ({@link pinFailure}). A
+    // plan told "failed" there let the agent run the step again.
+    if (UNCERTAIN_TEXT.test(message))
+        return new StepRunError(message, "uncertain");
     if (/^MCP error -?\d+/i.test(message))
         return new StepRunError(message, "failed");
     return new StepRunError(message, "uncertain");

package/dist/replay/derive.js

@@ -33,7 +33,7 @@
 import { redactText } from "../record/redact.js";
 import { isUnhealthyStatus, serviceHealth, timeoutSignal } from "../util/service-health.js";
 import { serviceHeaders } from "../util/service-headers.js";
-import { calculateCostUsd } from "./pricing.js";
+import { calculateCostUsd, requestRates } from "./pricing.js";
 export const DEFAULT_DERIVE_MODEL = "claude-haiku-4-5-20251001";
 const ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
 const ANTHROPIC_VERSION = "2023-06-01";
@@ -133,6 +133,44 @@ export function extractJsonObject(text) {
     }
     return undefined;
 }
+/**
+ * `text` with each bare `undefined` in its JSON made `null`, when that JSON
+ * does not parse as it came. `undefined` is not JSON, but models emit it
+ * (`{"a": undefined}`), and one stray token should not cost the extraction.
+ * A value that says it in words — `TypeError: undefined is not a function` —
+ * is a value, and was rewritten along with the rest: the plan was handed
+ * `TypeError: null is not a function`, silently. So the JSON is read as it
+ * came first, and only a token outside every string literal is changed: the
+ * walk takes each string from its opening quote to its closing one, so a
+ * quote inside a string never ends it early.
+ */
+function nullUndefined(text) {
+    const json = extractJsonObject(text);
+    if (json === undefined)
+        return text;
+    try {
+        JSON.parse(json);
+        return text;
+    }
+    catch {
+        // not JSON as it came: repaired below
+    }
+    let fixed = "";
+    let at = 0;
+    while (at < json.length) {
+        const open = json.indexOf('"', at);
+        fixed += json.slice(at, open < 0 ? json.length : open).replace(/\bundefined\b/g, "null");
+        if (open < 0)
+            break;
+        let end = open + 1;
+        while (end < json.length && json[end] !== '"')
+            end += json[end] === "\\" ? 2 : 1;
+        fixed += json.slice(open, end + 1);
+        at = end + 1;
+    }
+    const start = text.indexOf(json);
+    return text.slice(0, start) + fixed + text.slice(start + json.length);
+}
 export function buildExtractionPrompt(prompt, intent, schema, ctx = {}) {
     // Each parameter wears its kind, because the last rule below treats the two
     // differently and the model cannot tell them apart from the name alone
@@ -232,15 +270,19 @@ export async function deriveParameters(opts) {
         .join("");
     const inputTokens = body.usage?.input_tokens ?? 0;
     const outputTokens = body.usage?.output_tokens ?? 0;
+    const cacheReadTokens = body.usage?.cache_read_input_tokens ?? 0;
+    const cacheCreationTokens = body.usage?.cache_creation_input_tokens ?? 0;
     const costUsd = calculateCostUsd(model, {
         inputTokens,
         outputTokens,
-        cacheReadTokens: body.usage?.cache_read_input_tokens ?? 0,
-        cacheCreationTokens: body.usage?.cache_creation_input_tokens ?? 0,
+        cacheReadTokens,
+        cacheCreationTokens,
+        // One request: priced by its own prompt length where the model is (pricing.ts).
+        ...requestRates(model, { promptTokens: inputTokens + cacheReadTokens + cacheCreationTokens }),
     });
     // `undefined` is not JSON, but models emit it; normalise before parsing so one
     // stray token does not cost the whole extraction.
-    const normalized = text.replace(/:\s*undefined\b/g, ": null");
+    const normalized = nullUndefined(text);
     const cleaned = extractJsonObject(normalized) ??
         normalized
             .replace(/^```(?:json)?\s*/m, "")

package/dist/replay/handover.d.ts

@@ -130,6 +130,19 @@ export interface HandoverNoteInput {
     whenText?: string | null;
 }
 export declare function buildHandoverNote(n: HandoverNoteInput): string;
+/**
+ * The note for a plan that ran every one of its steps while its caller was
+ * gone (Esc on `run_scenario`, or the client's timeout), so that the results
+ * reached nobody. Nothing stopped, so no hand-over note exists; without this
+ * one the model was never told the steps ran, and the next request of the same
+ * task ran them again — a row added twice, a mail sent twice.
+ */
+export declare function buildUnseenResultNote(n: {
+    intent: string;
+    /** How many steps ran, of how many the plan has. */
+    executed: number;
+    totalSteps: number;
+}): string;
 /** "Step 2", "Steps 1–3", "Steps 1, 3 and 5–6": 1-based numbers in order, runs joined. */
 export declare function stepsPhrase(numbers: readonly number[]): string;
 //# sourceMappingURL=handover.d.ts.map

package/dist/replay/handover.js

@@ -129,6 +129,24 @@ export function buildHandoverNote(n) {
     }
     return truncate(lines.join("\n"), MAX_HANDOVER_NOTE);
 }
+/**
+ * The note for a plan that ran every one of its steps while its caller was
+ * gone (Esc on `run_scenario`, or the client's timeout), so that the results
+ * reached nobody. Nothing stopped, so no hand-over note exists; without this
+ * one the model was never told the steps ran, and the next request of the same
+ * task ran them again — a row added twice, a mail sent twice.
+ */
+export function buildUnseenResultNote(n) {
+    const intent = n.intent.length > 240 ? `${n.intent.slice(0, 240)}…` : n.intent;
+    const lines = [
+        "[BaseInstRunner calculated replay] The calculated scenario for the earlier request ran while its result",
+        "was not being waited for, so nobody has seen what it did.",
+    ];
+    if (intent)
+        lines.push(`Intent: ${intent}`);
+    lines.push(`${n.executed === n.totalSteps ? `All ${n.totalSteps}` : `${n.executed} of ${n.totalSteps}`} steps of the scenario ran, and their side effects are in place. Do not run them again.`, "If you need what they returned, look at the state they changed, or tell the user what ran and ask.");
+    return truncate(lines.join("\n"), MAX_HANDOVER_NOTE);
+}
 /** "Step 2", "Steps 1–3", "Steps 1, 3 and 5–6": 1-based numbers in order, runs joined. */
 export function stepsPhrase(numbers) {
     if (numbers.length === 0)

package/dist/replay/pricing.d.ts

@@ -15,27 +15,77 @@
  * numbers are comparable. For that row, right now, they are not.
  *
  * Bump the version — on **every** side — whenever a row changes.
+ *
+ * WHAT A PRICE DEPENDS ON BESIDE THE MODEL (Anthropic's pricing page, read
+ * 2026-11-11). Until this version a turn was priced from four token counts per
+ * model, and three things the bill reads were not looked at:
+ *
+ * - WHICH CACHE WAS WRITTEN. A 5-minute cache write bills at 1.25x input, a
+ *   1-hour one at 2x. Claude Code writes the 1-hour cache: in the transcripts
+ *   this was checked against, every cache write was a 1-hour one, and each was
+ *   priced 37.5% too low.
+ * - THE REQUEST'S OWN PROMPT LENGTH, on Claude Haiku 5.5: a request whose prompt
+ *   (input, cache reads and cache writes together) is over 100,000 tokens pays
+ *   five times the price. Each request is priced on its own.
+ * - HOW THE REQUEST RAN: fast mode bills at twice the standard prices, and
+ *   US-only inference at 1.1x.
+ *
+ * So a usage now says these of itself ({@link TokenUsage}), and whoever folds
+ * requests into totals keeps the requests that are priced differently apart
+ * ({@link requestRates}).
  */
 /** Identifies {@link MODEL_PRICING}. Must equal the service's constant. */
-export declare const PRICING_VERSION = "2026-09-24";
-/**
- * Tolerate provider prefixes (`anthropic/`, `us.anthropic.`), date snapshots and
- * unseen version bumps by falling back to the longest matching family, so a new
- * snapshot never silently prices at $0.
- */
-export declare function resolveModelPricing(model: string): {
+export declare const PRICING_VERSION = "2026-11-11";
+/** One rate card, in $/million tokens. */
+export interface ModelRates {
     input: number;
     output: number;
     cacheRead: number;
+    /** A write to the 5-minute cache. */
     cacheWrite: number;
-} | undefined;
-export declare function hasModelPricing(model: string): boolean;
-export interface TokenUsage {
+    /** A write to the 1-hour cache. */
+    cacheWrite1h: number;
+}
+/**
+ * A model's rate card, or undefined when the table has no row for it. With
+ * `longPrompt`, the card of a request over the model's prompt-length
+ * threshold, for a model that has one.
+ */
+export declare function resolveModelPricing(name: string, opts?: {
+    longPrompt?: boolean;
+}): ModelRates | undefined;
+export declare function hasModelPricing(name: string): boolean;
+/** What of a request, beside its model and its token counts, sets its prices. */
+export interface RateFlags {
+    /** Its prompt was over the model's long-prompt threshold (Haiku 5.5: 100,000 tokens). */
+    longPrompt?: boolean;
+    /** It ran in fast mode. */
+    fast?: boolean;
+    /** It ran on US-only inference. */
+    usOnly?: boolean;
+}
+export interface TokenUsage extends RateFlags {
     inputTokens: number;
     outputTokens: number;
     cacheReadTokens?: number;
+    /** Every cache write, the 1-hour ones among them. */
     cacheCreationTokens?: number;
+    /** Of {@link cacheCreationTokens}, the tokens written to the 1-hour cache. */
+    cacheCreation1hTokens?: number;
 }
+/**
+ * The flags of ONE request, from its own `usage` as the API reports it: its
+ * prompt length (input, cache reads and cache writes together), its `speed`
+ * and its `inference_geo`. Only what is so is set, so two requests priced
+ * alike give equal flags — and {@link rateKey} the same key.
+ */
+export declare function requestRates(name: string, request: {
+    promptTokens: number;
+    speed?: unknown;
+    inferenceGeo?: unknown;
+}): RateFlags;
+/** A short text that is equal for two sets of flags exactly when they price alike. "" for none. */
+export declare function rateKey(flags: RateFlags): string;
 /** Cost in USD. An unpriced model yields 0 — the caller reports `measured: false`. */
-export declare function calculateCostUsd(model: string, usage: TokenUsage): number;
+export declare function calculateCostUsd(name: string, usage: TokenUsage): number;
 //# sourceMappingURL=pricing.d.ts.map