@bivelio/savings-layer 0.4.25 → 0.4.26

package/dist/index.d.ts

@@ -142,6 +142,14 @@ declare class SavingsLedger {
      * not yet billed as verifiable against the invoice).
      */
     elididoLocal: number;
+    /**
+     * Tokens (LOCAL ruler) that tool-output compaction removed from the sent
+     * prompt. Subtracted from `removedInputLocal` for the same reason as
+     * {@link elididoLocal}: the saving is a COUNT in ledger 3 (`compressedInput`)
+     * and never enters the reconstructed baseline or the commission, so `basis`
+     * stays "measured" and the provider's invoice shows the effect on its own.
+     */
+    compactedLocal: number;
     /**
      * ¿El estimador que produjo las dos cifras anteriores cuenta con la regla del
      * proveedor? Lo fija el pipeline al resolver el tokenizador del modelo.
@@ -303,7 +311,7 @@ declare function precioDeLista(model: string, at?: Date | number): CostModel | u
  * on the customer's machine. `test/version-declarada.test.ts` ties this
  * constant to package.json so the two can never drift.
  */
-declare const BV_SALA_VERSION = "0.4.25";
+declare const BV_SALA_VERSION = "0.4.26";
 
 /**
  * Environment-agnostic UUID generation.
@@ -517,6 +525,35 @@ interface RetrievalOptions {
     maxRounds?: number;
     maxDocuments?: number;
 }
+/**
+ * How a request chooses between the provider's native tool search and the layer's
+ * tool selector. See {@link SavingsToggles.toolSearch}.
+ *
+ * - `"off"` (default): the layer's tool selector runs, as without this option.
+ * - `"auto"`: native tool search when the adapter talks to the provider's own API host,
+ *   the catalogue reaches the provider's documented size threshold, and deferring it
+ *   pays for one search on every request even with a warm prompt cache. Otherwise the
+ *   selector runs.
+ * - `"always"`: native tool search whenever the adapter and model support it, with no
+ *   size or cost check. Use it when a proxy in front of the provider forwards the
+ *   search blocks, or when you have measured it on your own traffic.
+ */
+type ToolSearchMode = "off" | "auto" | "always";
+/** The long form of {@link SavingsToggles.toolSearch}. */
+interface ToolSearchOptions {
+    mode: ToolSearchMode;
+    /**
+     * Tool ids sent without deferred loading, so the model can call them without
+     * searching first. They are part of the cached prefix: keep the list short and the
+     * same on every request. Ids that are not in the request's tools are ignored.
+     */
+    alwaysLoaded?: string[];
+    /**
+     * The provider's search: `"bm25"` (the model writes natural-language queries; the
+     * default) or `"regex"` (the model writes regular expressions).
+     */
+    variant?: "bm25" | "regex";
+}
 interface SavingsToggles {
     exactCache?: boolean;
     /**
@@ -563,6 +600,30 @@ interface SavingsToggles {
      * and never enters your commission — your invoice stays the source of truth.
      */
     elision?: boolean;
+    /**
+     * OPT-IN. Compact the text of `role: "tool"` messages before the request is
+     * sent: terminal escape sequences and superseded progress-bar states are
+     * removed, whitespace between JSON tokens is removed when the whole output is
+     * JSON, and runs of identical consecutive lines are folded into one line plus
+     * a count. Nothing is summarised and no word is dropped.
+     *
+     * IT NEVER REWRITES WHAT THE PROVIDER HAS ALREADY CACHED. The decision for each
+     * tool output depends only on its own text and on the call that produced it,
+     * so an output compacted on the turn it arrives is re-sent with the same bytes
+     * on every later turn and the prefix cache keeps matching. Turn it on for a
+     * whole conversation (or layer-wide with `toolOutputCompaction` in
+     * `createSavingsLayer`), not halfway through one: the first compacted request
+     * of a conversation that started without it rewrites the history once.
+     *
+     * Outputs of calls whose arguments name a file are left verbatim by default,
+     * because an agent that edits files by exact string match copies what it read.
+     * `false` switches it off for this request even when the layer enables it.
+     *
+     * What it removes is a COUNT in `report.tokens.compressedInput`; it is never
+     * priced into `cost.netSavings` or your commission — your provider's invoice
+     * shows the effect.
+     */
+    toolOutputCompaction?: boolean;
     serialization?: boolean | "auto";
     singleflight?: boolean;
     deterministicResolvers?: boolean;
@@ -656,6 +717,37 @@ interface SavingsToggles {
      * action can be lost to a discovery step.
      */
     toolDiscovery?: boolean;
+    /**
+     * OPT-IN. Let the PROVIDER search your tool catalogue instead of the layer's tool
+     * selector. Defaults to `"off"`. Read {@link ToolSearchMode} for the three modes.
+     *
+     * With it applied, every tool you pass travels on every request, marked for deferred
+     * loading, next to the provider's search tool. The provider keeps deferred definitions
+     * out of the prompt prefix; the model searches the catalogue when it needs a tool, and
+     * the definitions it finds are added after the prefix. No tool you declared becomes
+     * unreachable, and the cached prefix stays the same when the question changes or the
+     * catalogue grows.
+     *
+     * WHERE IT APPLIES. The Anthropic adapter of this package, on a model listed in the
+     * provider's tool search compatibility table, with at least one tool to defer.
+     * Requests with an output contract, or with the model cascade on, keep the selector.
+     * OpenAI documents its tool search for the Responses and Agents APIs, not for Chat
+     * Completions, which the OpenAI-compatible adapter speaks, so it keeps the selector too.
+     * `report.traces` says which path ran and why (entry `tool-search`).
+     *
+     * WHAT IT IS WORTH BELONGS TO THE PROVIDER. Your provider's usage counter reflects it
+     * directly. The layer credits nothing for it, adds nothing to any ledger for it and
+     * charges no commission on it, and a request served this way is never used as the
+     * reference to value a later repeat.
+     *
+     * WHAT CHANGES FOR YOU. Relevance pruning of read tools is off: the model chooses.
+     * When your catalogue declares `risk`, write and destructive tools are still withheld
+     * from requests the router does not classify as actions, as with the selector. Each
+     * search is a short extra step inside the same call, and the definitions it loads are
+     * billed as normal input. This adapter sends earlier turns as text, so a later turn
+     * that needs a tool searches again.
+     */
+    toolSearch?: ToolSearchMode | ToolSearchOptions;
     /**
      * Send the request to a CHEAPER model of the same family, check the answer
      * with a deterministic gate, and fall back to the model you asked for only
@@ -1236,7 +1328,31 @@ type QualityCacheMatch = {
      * negation parity and content-word overlap. A hit is never served without it.
      */
     factGuard: "passed";
+    /**
+     * Present when the cache runs with `calibration`: the bound this reuse was
+     * served under, and the labels behind it.
+     */
+    calibration?: SemanticCalibrationBound;
 };
+/**
+ * The bound a calibrated semantic reuse was served under: with probability at
+ * least `confidence`, at most `maxErrorRate` of the reuses served at or above
+ * `floor` are wrong, where "wrong" is what the calibration's judge rejects.
+ * It rests on the labels counted here, which your own traffic produced.
+ */
+interface SemanticCalibrationBound {
+    maxErrorRate: number;
+    confidence: number;
+    /** The certified floor this reuse's score cleared. */
+    floor: number;
+    /** Held-out labels at or above the floor that certified it, and how many were wrong reuses. */
+    heldOutAtFloor: number;
+    wrongHeldOutAtFloor: number;
+    /** Labels collected in this traffic segment. */
+    labeled: number;
+    /** Calibrations are kept apart for single-shot and agentic traffic. */
+    segment: "single_shot" | "agentic";
+}
 /** What the model cascade decided on this request. See {@link ModelCascadeReport}. */
 interface QualityCascadeCheck {
     mode: "shadow" | "on";
@@ -1402,7 +1518,8 @@ interface SavingsReport {
     deferred?: DeferredExecutionReport;
     /**
      * Where the provider was allowed to write its prompt cache. Present whenever
-     * `savings.standalone` is `true`, including when it changed nothing.
+     * `savings.standalone` is `true`, including when it changed nothing, and when
+     * `cacheBreakpoints: "auto"` switched this request to explicit mode.
      */
     cacheWrites?: CacheWriteReport;
     /** How a streamed request was delivered. Present only on results of `generateStream`. */
@@ -1761,6 +1878,103 @@ declare function stableStringify(value: unknown): string;
 declare function modelFamilyOf(model: string): string;
 declare function canonicalize(request: SavingsRequest): CanonicalRequest;
 
+/**
+ * Decides whether a stored answer would have been right for a new request,
+ * given the answer your provider just produced for it. `true` = the stored
+ * answer was reusable.
+ *
+ * It is the definition of "correct" behind every calibrated floor: the bound
+ * holds for what your judge accepts, nothing more. A judge that calls a model
+ * costs money this layer does not see and never subtracts from a saving.
+ */
+type AnswerJudge = (stored: CachedAnswer, fresh: CachedAnswer) => boolean | Promise<boolean>;
+/**
+ * Opt-in calibration of the semantic cache: instead of a fixed acceptance floor,
+ * the cache serves a reworded request only at or above a floor that labeled
+ * traffic has certified, so that at most `maxErrorRate` of the reuses served
+ * from that floor up are wrong, at the stated `confidence`.
+ *
+ * Until a floor is certified the cache serves nothing: every candidate goes to
+ * your provider, exactly as it would without the cache, and the fresh answer is
+ * compared with the stored one to produce a label. Calibration costs reuses,
+ * never an extra provider call.
+ *
+ * Only candidates at or above `similarityThreshold` are labeled, so no floor
+ * below it can be certified: lower it to let the calibration look further down.
+ * Your verifier, if any, still scores every candidate, and the score that is
+ * calibrated is the lower of similarity and its score.
+ */
+interface SemanticCalibrationOptions {
+    /** Highest share of wrong reuses you accept, in (0, 0.5]. E.g. 0.02. */
+    maxErrorRate: number;
+    /** Confidence of the bound, in (0.5, 1). Default 0.95. */
+    confidence?: number;
+    /**
+     * How a label is produced. Default {@link sameAnswer}: identical structured
+     * data, or identical text after trimming and collapsing whitespace. For free
+     * text, pass your own: with the default, two differently worded correct
+     * answers count as a wrong reuse, and the floor stays uncertified.
+     */
+    judge?: AnswerJudge;
+    /**
+     * Share of reuses that clear the floor but are sent to your provider anyway,
+     * to keep labeling above it. In [0, 1). Default 0.05. Without these labels
+     * the floor cannot be re-tested where it serves.
+     */
+    auditRate?: number;
+    /**
+     * Stop serving a stored answer at or below a score where it was already
+     * judged wrong for another request. It only ever removes reuses. Default true.
+     */
+    perRecordFloors?: boolean;
+    /** Source of randomness for audits, in [0, 1). Default `Math.random`. */
+    random?: () => number;
+}
+/** One labeled reuse decision: the score the cache would have served on, and whether the stored answer was right. */
+interface CalibrationObservation {
+    score: number;
+    correct: boolean;
+}
+/** Where a calibration stands. */
+interface SemanticCalibrationStatus {
+    maxErrorRate: number;
+    confidence: number;
+    /** Lowest certified score; null while the labels certify none. */
+    floor: number | null;
+    /** Labels collected. */
+    labeled: number;
+    /** Labels kept apart to test the floor (about half). */
+    heldOut: number;
+    /** Held-out labels at or above the floor, and how many of them were wrong reuses. 0 without a floor. */
+    heldOutAtFloor: number;
+    wrongHeldOutAtFloor: number;
+    /**
+     * Held-out labels at or above a floor, all correct, that the next test needs
+     * to certify it: the shortest possible wait, not a promise.
+     */
+    minHeldOutToCertify: number;
+    /** Online only: the label count at which the floor is re-tested next. Each test comes when the labels have grown by half. */
+    nextTestAt?: number;
+}
+/** Default {@link AnswerJudge}: the stored answer counts as right only if it is the same answer. */
+declare function sameAnswer(stored: CachedAnswer, fresh: CachedAnswer): boolean;
+/**
+ * Certifies an acceptance floor from labels you already have (your own traffic,
+ * or a labeled set scored with your embedder), with the same test the cache
+ * runs online. Pass the result's `floor` as `acceptThreshold`, or `null` means
+ * these labels do not support any floor at this bound.
+ *
+ * The labels are split at random (fixed seed, independent of their content):
+ * one half proposes candidate floors, the other half tests them, most
+ * conservative first, with an exact binomial test. With probability at least `confidence`, the share of wrong
+ * reuses at or above the returned floor is at most `maxErrorRate`, provided new
+ * requests come from the same distribution as these labels.
+ */
+declare function calibrateSemanticFloor(observations: readonly CalibrationObservation[], options: {
+    maxErrorRate: number;
+    confidence?: number;
+}): SemanticCalibrationStatus;
+
 /**
  * Semantic cache (safe-by-construction).
  *
@@ -1823,6 +2037,11 @@ interface SemanticRecord {
     /** Sampling seed of the request, or null when it set none. */
     seed: number | null;
     storedAtMs: number;
+    /**
+     * With calibration on: the highest score at which this stored answer was
+     * judged wrong for another request. It is never served at or below it.
+     */
+    failedAtScore?: number;
 }
 interface SemanticHit {
     record: SemanticRecord;
@@ -1840,6 +2059,30 @@ interface SemanticHit {
     embedder: "built_in" | "custom";
     /** Whether a verifier scored this hit. When false, `verifierScore` equals `similarity`. */
     verifierRan: boolean;
+    /** With calibration on: the bound this hit is served under. `acceptFloor` is then the certified floor. */
+    calibration?: SemanticCalibrationBound;
+}
+/**
+ * With calibration on, a candidate the cache did not serve: the request goes to
+ * your provider, and {@link InMemorySemanticCache.observe} turns the answer into
+ * a label.
+ *
+ * - `calibrating`: no floor is certified yet in this traffic segment.
+ * - `below_floor`: the candidate's score is under the certified floor.
+ * - `record_floor`: this stored answer was already judged wrong at this score or higher.
+ * - `audit`: the candidate cleared the floor and was sampled to keep testing it.
+ */
+interface SemanticProbe {
+    reason: "calibrating" | "below_floor" | "record_floor" | "audit";
+    /** The score the decision was made on: the lower of similarity and your verifier's score. */
+    score: number;
+    segment: "single_shot" | "agentic";
+    record: SemanticRecord;
+}
+/** What {@link InMemorySemanticCache.lookup} found: a hit to serve, a candidate to label, or neither. */
+interface SemanticLookup {
+    hit: SemanticHit | null;
+    probe: SemanticProbe | null;
 }
 interface SemanticCacheOptions {
     /**
@@ -1865,6 +2108,12 @@ interface SemanticCacheOptions {
     ttlMs?: number;
     maxRecords?: number;
     now?: () => number;
+    /**
+     * Opt-in: replace the fixed acceptance floor with one your own labeled
+     * traffic certifies for a wrong-reuse rate you choose. Off by default. See
+     * {@link SemanticCalibrationOptions}.
+     */
+    calibration?: SemanticCalibrationOptions;
 }
 declare function cosine(a: number[], b: number[]): number;
 declare function numericTokens(s: string): string[];
@@ -1889,13 +2138,53 @@ declare class InMemorySemanticCache {
     private readonly maxRecords;
     private readonly now;
     private readonly embebedorPropio;
+    private readonly calibracion;
+    private readonly estados;
+    private readonly pendientes;
+    private readonly aceptacionExplicita;
     constructor(opts?: SemanticCacheOptions);
+    /** Whether this cache runs with `calibration`. */
+    get calibrated(): boolean;
     /**
      * Find a safe hit for a canonical request, or null. Metadata filters run
      * FIRST and hard — a candidate from another tenant, scope, or knowledge epoch
      * is never even scored.
+     *
+     * With calibration on, it returns only a hit served under a certified floor
+     * and labels nothing: without {@link lookup} and {@link observe} (the layer
+     * calls both) the calibration never gets a label and never certifies.
      */
     find(c: CanonicalRequest): Promise<SemanticHit | null>;
+    /**
+     * The best candidate that passes every hard filter, the similarity floor and
+     * the fact guard. With `conAceptacion`, also the confidence floor (the path
+     * without calibration, unchanged); without it, calibration decides.
+     */
+    private mejorCandidata;
+    /**
+     * Like {@link find}, and with calibration on it also returns the candidate it
+     * did not serve, so the caller can label it with {@link observe} once the
+     * provider has answered. Without calibration, `probe` is always null.
+     *
+     * `agentic` picks the traffic segment: calibrations are kept apart for
+     * single-shot and agentic requests.
+     */
+    lookup(c: CanonicalRequest, opts?: {
+        agentic?: boolean;
+    }): Promise<SemanticLookup>;
+    /**
+     * Label a candidate {@link lookup} did not serve, with the answer your provider
+     * produced for that request. Resolves to the judge's verdict, or null when
+     * there is no calibration or the judge failed (no label is recorded then).
+     * It never rejects.
+     */
+    observe(probe: SemanticProbe, fresh: CachedAnswer): Promise<boolean | null>;
+    private etiquetar;
+    /** Resolves once every pending {@link observe} has recorded its label. */
+    settled(): Promise<void>;
+    /** Where the calibration of a traffic segment stands, or null without calibration. */
+    calibrationStatus(segment?: SemanticProbe["segment"]): SemanticCalibrationStatus | null;
+    private estadoDe;
     store(c: CanonicalRequest, answer: CachedAnswer): Promise<void>;
     /** Drop every record for a knowledge epoch (invalidation on re-index). */
     invalidateEpoch(knowledgeEpoch: string): number;
@@ -2310,6 +2599,69 @@ declare const noopCompressor: Compressor;
  */
 declare function compresionFiel(original: string, comprimido: string): boolean;
 
+/** A deterministic, content-only transformation applied to a tool output. */
+type CompactionTransform = "ansi" | "carriage-return" | "json" | "repeated-lines";
+/** Every transformation, in the order they are applied. */
+declare const COMPACTION_TRANSFORMS: readonly CompactionTransform[];
+/**
+ * How tool outputs are compacted. Every field is optional.
+ *
+ * The decision for each tool output depends only on its own text and the tool
+ * call that produced it — never on its position, the size of the prompt or the
+ * model — so an output compacted when it first arrives is re-sent with the same
+ * bytes on every later turn and the provider's prefix cache keeps matching.
+ * Change these settings between conversations, not in the middle of one: a
+ * change rewrites outputs the provider has already cached.
+ */
+interface ToolOutputCompactionSettings {
+    /** Which transformations may run. Default: all of {@link COMPACTION_TRANSFORMS}. */
+    transforms?: readonly CompactionTransform[];
+    /**
+     * Leave an output verbatim unless compaction removes at least this many
+     * characters (default 256). Small gains are not worth changing the text the
+     * model sees.
+     */
+    minSavedChars?: number;
+    /** Tool names whose outputs are never compacted. */
+    exceptTools?: readonly string[];
+    /**
+     * Also compact outputs of tool calls whose arguments name a file (`path`,
+     * `file_path`, `filename`…). Default `false`: an agent that edits files by
+     * exact string match copies what it read, and a compacted view of a file
+     * would not match the file on disk.
+     */
+    compactFileViews?: boolean;
+}
+/** The outcome of compacting one tool output. */
+interface ToolOutputCompaction {
+    /** The text to send: compacted when `changed`, otherwise the input as-is. */
+    text: string;
+    changed: boolean;
+    /** Transformations that changed the text, in the order they ran. */
+    applied: CompactionTransform[];
+    originalChars: number;
+    compactChars: number;
+    /** Why the output was, or was not, compacted. */
+    reason: string;
+}
+/** Default minimum saving, in characters, for an output to be compacted. */
+declare const DEFAULT_MIN_SAVED_CHARS = 256;
+/**
+ * Compact one tool output with deterministic, content-only transformations.
+ *
+ * Nothing is summarised and no word is dropped: terminal escape sequences and
+ * superseded progress-bar states are removed, whitespace between JSON tokens is
+ * removed (strings and numbers are kept byte for byte, and the result must parse
+ * to the same value), and runs of identical consecutive lines are folded into
+ * the first line plus a count that expands back to the exact original.
+ *
+ * The same input always produces the same output. Call it where a tool result
+ * is produced, before you append it to your conversation history, and the
+ * history itself holds the compacted text — the provider's prefix cache is
+ * never disturbed.
+ */
+declare function compactToolOutput(text: string, settings?: ToolOutputCompactionSettings): ToolOutputCompaction;
+
 /** What the layer needs to know about a provider's prefix cache to price a decision. */
 interface CacheTier {
     /**
@@ -2468,6 +2820,53 @@ interface ProviderRequest {
      * letting the provider choose. Others ignore it.
      */
     explicitCacheWrites?: boolean;
+    /**
+     * Provider-native tool search, decided by the layer for this request. An adapter that
+     * supports it sends every tool with deferred loading except `alwaysLoaded`, plus the
+     * provider's search tool. The layer sets it only for adapters of this package that
+     * declared the capability; other providers never receive it.
+     */
+    toolSearch?: ProviderToolSearch;
+    /**
+     * Where the layer's breakpoint placer (`cacheBreakpoints: "auto"`) wants the
+     * provider's prompt cache written, on top of `stablePrefixMessages`. Only
+     * adapters with explicit breakpoints (Anthropic) act on it; others ignore it.
+     * Absent: the adapter's fixed placement.
+     */
+    cachePlacement?: CachePlacement;
+}
+/** See {@link ProviderRequest.toolSearch}. */
+interface ProviderToolSearch {
+    /** The provider's search: natural-language queries (`"bm25"`) or regular expressions. */
+    variant: "bm25" | "regex";
+    /** Tool ids sent without deferred loading. */
+    alwaysLoaded: string[];
+}
+/** What the provider's native tool search did in one call, as its response shows it. */
+interface ProviderToolSearchUsage {
+    /** Searches the model ran. */
+    searches: number;
+    /** Tool names the searches loaded, in order, without repeats. */
+    loaded: string[];
+    /** Searches that came back as an error result instead of references. */
+    errors: number;
+}
+/**
+ * Breakpoint placement decided by the layer from the reuse it measured on your
+ * traffic. See `cacheBreakpoints` in the layer configuration.
+ */
+interface CachePlacement {
+    /**
+     * Also mark the last block of the request, so that a continuation of this
+     * exact prompt (the next turn of a conversation or an agent loop) reads all
+     * of it from cache instead of writing it again.
+     */
+    tail: boolean;
+    /**
+     * Cache lifetime for every breakpoint of this request. On Anthropic a
+     * one-hour write is billed at 2x the input rate, a five-minute one at 1.25x.
+     */
+    ttl: "5m" | "1h";
 }
 interface ProviderUsage {
     inputTokens: number;
@@ -2486,6 +2885,13 @@ interface ProviderUsage {
      * bill INCREASE as a saving.
      */
     cacheWriteInputTokens?: number;
+    /**
+     * The part of `cacheWriteInputTokens` written with a ONE-HOUR lifetime
+     * (Anthropic `cache_creation.ephemeral_1h_input_tokens`), billed at 2x the
+     * input rate instead of 1.25x. Absent when the provider did not break the
+     * writes down by lifetime.
+     */
+    cacheWrite1hInputTokens?: number;
     /**
      * Output tokens the provider billed for hidden reasoning, already included in
      * `outputTokens` (OpenAI `completion_tokens_details.reasoning_tokens`).
@@ -2575,6 +2981,11 @@ interface ProviderResponse {
      * replayable.
      */
     replayable?: boolean;
+    /**
+     * Present when the request carried {@link ProviderRequest.toolSearch} and the adapter can
+     * read what the search did. The layer only reports it; it credits nothing for it.
+     */
+    toolSearch?: ProviderToolSearchUsage;
     raw?: unknown;
 }
 /** One event of a provider-level stream. */
@@ -2819,6 +3230,13 @@ interface SavingsLayerConfig {
      * with your own measurements to unlock the full decision in both directions.
      */
     compressionEconomics?: CompressionEconomics;
+    /**
+     * Compact tool outputs on every request (`true`, or settings), unless a
+     * request sets `savings.toolOutputCompaction: false`. Off by default; a request
+     * can also switch it on alone with `savings.toolOutputCompaction: true`.
+     * See {@link ToolOutputCompactionSettings}.
+     */
+    toolOutputCompaction?: boolean | ToolOutputCompactionSettings;
     retriever?: Retriever;
     reranker?: Reranker;
     /**
@@ -2832,6 +3250,33 @@ interface SavingsLayerConfig {
      * All off by default; a request's own `savings` value always wins.
      */
     priceLevers?: PriceLeverSettings;
+    /**
+     * Where the layer writes the provider's prompt cache. Defaults to `"fixed"`.
+     *
+     * `"fixed"`: one breakpoint at the end of the system header and one at the
+     * end of the history before the last user message, subject to the measured
+     * hit-rate gate. Nothing else.
+     *
+     * `"auto"`: the layer watches, per model, tool set and system header, how
+     * often your traffic re-sends each part of the prompt and how long after.
+     * Watching costs nothing — it compares prefixes locally, it does not mark
+     * anything to find out. Once it has enough samples it places breakpoints only
+     * where the reuse beats the write premium: the tail of the prompt when turns
+     * continue each other (agent loops, conversations), the history only when it
+     * is re-sent, and a one-hour lifetime on Anthropic only when your gaps and the
+     * size of this request make it pay. On OpenAI models that bill cache writes
+     * (GPT-5.6 and later, on OpenAI's own API) it switches to explicit mode, with
+     * no write on your question, when continuations are rare; `savings.standalone`
+     * still wins when you set it. Until it has samples it behaves exactly like
+     * `"fixed"`.
+     *
+     * What it did and why is in `report.traces` (`prefix-cache-placement`), and
+     * the effect is read from the provider's own counters (`cachedInputTokens`,
+     * `cacheWriteInputTokens`): if they do not confirm the reads the layer
+     * predicted, it falls back to `"fixed"` for that traffic. The write premium it
+     * causes, one-hour writes at 2x included, is charged to `cost.actual`.
+     */
+    cacheBreakpoints?: "fixed" | "auto";
     /**
      * Signed BiVelio license token (from your paid subscription). This is the
      * primary way to license the SDK: `createSavingsLayer` verifies it offline
@@ -3160,6 +3605,195 @@ interface SavingsCallOptions {
     savings?: SavingsAdapterLevers;
 }
 
+/** One request of a batch: your id for it, and the same request you would pass to `generate()`. */
+interface BatchRequest {
+    /**
+     * Your id for this request, unique within one `submit()`: 1 to 64 letters, digits,
+     * `_` or `-`. Results come back in any order and are matched by this id.
+     */
+    customId: string;
+    /**
+     * The request, as for `generate()`. It is sent as written, translated by the same
+     * provider adapter: the layer's per-request savings (caching, compression, model
+     * cascade, retrieval) do not run on batches, so `retrieval` and `structuredData`
+     * are rejected and `savings` is ignored.
+     */
+    request: SavingsRequest;
+}
+/** Options for `layer.batches.submit()`. */
+interface BatchSubmitOptions {
+    /**
+     * Anthropic only. Mark the leading system messages of each request as a prompt-cache
+     * prefix, so requests that share them can read it at the cache rate. A cache write
+     * costs more than plain input and, in a batch, hits are best-effort, so this pays
+     * only when many requests share a long system prompt. Defaults to false. OpenAI
+     * caches on its own and ignores it.
+     */
+    cacheSharedPrefix?: boolean;
+    /**
+     * Upper bound on requests per provider batch, below the provider's own limit, to get
+     * partial results sooner. The layer always splits at the provider limits (and, on
+     * OpenAI, by model).
+     */
+    maxRequestsPerBatch?: number;
+    /** Cancels the HTTP calls of this submission. Batches already created stay created. */
+    signal?: AbortSignal;
+}
+/**
+ * A submitted batch job. Plain JSON: store it and pass it back to `status()`,
+ * `results()` or `cancel()`, from this process or another one. It holds batch ids,
+ * your request ids, model ids and output schemas; never prompts or answers.
+ */
+interface BatchJob {
+    kind: "bvsala.batch";
+    version: 1;
+    /** Which batch API holds the job. */
+    provider: "anthropic" | "openai";
+    /** The provider base URL the job was submitted to, without credentials. */
+    endpoint: string;
+    /** One provider batch id per chunk, in submission order. */
+    batchIds: string[];
+    /** ISO 8601. */
+    submittedAt: string;
+    /**
+     * Every submitted request: your id, its model, the index in `batchIds` of the provider
+     * batch that carries it, and its output schema as an index into `schemas`.
+     */
+    requests: {
+        customId: string;
+        model: string;
+        batch: number;
+        schema?: number;
+    }[];
+    /** The distinct output schemas of the job, stored once each. */
+    schemas: JsonSchema[];
+}
+/** Request counts of a job, summed over its provider batches. */
+interface BatchCounts {
+    processing: number;
+    succeeded: number;
+    errored: number;
+    canceled: number;
+    expired: number;
+}
+/** Where a job stands, as its provider reports it. */
+interface BatchJobStatus {
+    /** `"ended"` once every provider batch of the job has finished, expired, failed or been canceled. */
+    state: "in_progress" | "canceling" | "ended";
+    requestCount: number;
+    /**
+     * As the provider reports them. OpenAI reports only completed and failed while a
+     * batch runs; its canceled and expired requests are counted once it has ended.
+     */
+    counts: BatchCounts;
+    /** Each provider batch with the status its provider gave, verbatim. */
+    batches: {
+        id: string;
+        status: string;
+    }[];
+}
+/** One request's outcome. */
+interface BatchItemResult<T = unknown> {
+    customId: string;
+    /** The model you asked for. */
+    model: string;
+    /**
+     * `"succeeded"` ran and is billed by the provider. `"errored"`, `"canceled"` and
+     * `"expired"` returned no answer and no usage (Anthropic documents that it does not
+     * bill them). `"missing"` means the provider returned no line for a request of an
+     * ended batch, which should not happen: nothing is assumed about it.
+     */
+    outcome: "succeeded" | "errored" | "canceled" | "expired" | "missing";
+    text?: string;
+    /** Present when the request had an output contract and the answer met it. */
+    data?: T;
+    /** Whether the answer met the output contract, when the request had one and no tool was called. */
+    contract?: "met" | "missed";
+    toolCalls?: ToolCallRequest[];
+    finishReason?: string;
+    /** The provider's own counter for this request. */
+    usage?: ProviderUsage;
+    /** The processing tier this result was billed at, as read from the provider. */
+    servedTier?: string;
+    /**
+     * What the batch tier was worth on this request: its usage at the standard rate card
+     * minus the same usage at the published batch rate card, component by component.
+     * Present only when credited. It is reported, never metered or billed.
+     */
+    tierSaving?: PriceLeverSaving;
+    /** Why it was or was not credited, or what failed. One sentence, never empty. */
+    reason: string;
+    /** The provider's error, for `"errored"` results. */
+    error?: {
+        type: string;
+        message: string;
+    };
+}
+/** The whole job, added up. */
+interface BatchSummary {
+    requestCount: number;
+    succeeded: number;
+    errored: number;
+    canceled: number;
+    expired: number;
+    missing: number;
+    /** Requests whose provider batch has not ended yet: not in `items`. */
+    pending: number;
+    /** Succeeded requests with a `tierSaving`. */
+    credited: number;
+    /** Sum of every `tierSaving.amount`. Never more than the sum of each request's published difference. */
+    tierSaving: number;
+    /** The credited requests' usage at the standard rate card. */
+    standardCost: number;
+    /** The same usage at the batch rate card. */
+    appliedCost: number;
+    /** `"measured"` only when every credited request is; `"none"` when nothing was credited. */
+    basis: "measured" | "estimated" | "none";
+    /** YYYY-MM-DD: the oldest check date of the rate cards used. */
+    pricesCheckedOn?: string;
+    /** Always `"none"`: a batch saving is reported next to the ledgers, never folded into them. */
+    creditedLedger: "none";
+    /** One sentence. Never empty. */
+    reason: string;
+}
+/** What `layer.batches.results()` returns. */
+interface BatchResults<T = unknown> {
+    /** False while any provider batch of the job is still running; results then cover only the ones that ended. */
+    ended: boolean;
+    items: BatchItemResult<T>[];
+    summary: BatchSummary;
+}
+/**
+ * The provider's asynchronous batch API: requests that can wait hours, billed at the
+ * provider's batch rate card. Anthropic's Message Batches and OpenAI's Batch API
+ * (Chat Completions) through the built-in providers; other providers throw.
+ */
+interface SavingsBatches {
+    /**
+     * Send requests to the provider's batch API. Returns as soon as the provider has
+     * accepted them, with nothing priced: a batch is valued only when its results are
+     * read. Throws before sending anything when a request cannot be batched. If a later
+     * chunk fails after earlier ones were created, the thrown error carries the partial
+     * job as `error.job`, so no created batch is lost.
+     */
+    submit(requests: BatchRequest[], options?: BatchSubmitOptions): Promise<BatchJob>;
+    /** Where the job stands. */
+    status(job: BatchJob, options?: {
+        signal?: AbortSignal;
+    }): Promise<BatchJobStatus>;
+    /**
+     * The results of every provider batch of the job that has ended, one per request,
+     * each valued at the two published rate cards, and the total.
+     */
+    results<T = unknown>(job: BatchJob, options?: {
+        signal?: AbortSignal;
+    }): Promise<BatchResults<T>>;
+    /** Ask the provider to stop the job. Requests it already processed are still billed. */
+    cancel(job: BatchJob, options?: {
+        signal?: AbortSignal;
+    }): Promise<BatchJobStatus>;
+}
+
 /**
  * Tokenizador EXACTO — la regla del proveedor, no una aproximación.
  *
@@ -3660,8 +4294,10 @@ declare class OpenAICompatibleProvider implements Provider {
      */
     generateStream(req: ProviderRequest, options?: ProviderStreamOptions): AsyncGenerator<ProviderStreamEvent, void, undefined>;
     private enviar;
+    private construirCuerpo;
     /** Translate a 2xx endpoint response into the provider-neutral shape. */
     private leer;
+    private leerJson;
 }
 
 /**
@@ -3713,10 +4349,13 @@ interface AnthropicOptions {
     /**
      * How many `cache_control` breakpoints the adapter may spend.
      *
-     * The API caps them at 4 per request. The adapter never needs more than 2
-     * (end of system, end of the stable message prefix) and the cap is exposed so
-     * a gateway with a stricter limit can lower it. Raising it above 4 is
-     * pointless: the extra breakpoints are rejected by the API, not ignored.
+     * The API caps them at 4 per request. The fixed placement never needs more
+     * than 2 (end of system, end of the stable message prefix); the layer's
+     * placer (`cacheBreakpoints: "auto"`) may add a third on the last block. The
+     * cap is exposed so a gateway with a stricter limit can lower it; when it is
+     * short, the system block goes first and the last block second. Raising it
+     * above 4 is pointless: the extra breakpoints are rejected by the API, not
+     * ignored.
      */
     maxCacheBreakpoints?: number;
     /**
@@ -3733,6 +4372,10 @@ interface AnthropicOptions {
      * the whole history at 0.1x — and loses money on one-shot traffic where
      * nothing ever reads it back. It is also rejected by legacy Bedrock
      * deployments. Turn it on when your traffic is multi-turn.
+     *
+     * Ignored on requests whose breakpoints were placed by the layer's placer
+     * (`cacheBreakpoints: "auto"`): the placer already decides whether the tail is
+     * marked, from the reuse it measured on your traffic.
      */
     automaticCache?: boolean;
     /**
@@ -3770,6 +4413,7 @@ declare class AnthropicProvider implements Provider {
     private construirCuerpo;
     private marcarCache;
     private leer;
+    private leerMensaje;
 }
 
 /**
@@ -4210,6 +4854,15 @@ interface SavingsLayer {
      * Await `result` before calling close(), or its usage record may be lost.
      */
     generateStream<T = unknown>(request: SavingsRequest, options?: SavingsStreamOptions): SavingsStream<T>;
+    /**
+     * The provider's asynchronous batch API, for requests that can wait hours: submit
+     * them, check on them, and read their results valued at the provider's batch rate
+     * card. Requests are sent as written (the layer's per-request savings do not run on
+     * batches), nothing is metered, and the batch saving is reported, never billed.
+     * Works with the built-in Anthropic and OpenAI providers; needs the same license as
+     * generate().
+     */
+    readonly batches: SavingsBatches;
     /**
      * Stop the background revocation poller (when the online call-home was enabled
      * via `licenseServerUrl`) and abort any in-flight request, and settle every
@@ -4253,6 +4906,20 @@ declare class StreamAbortedError extends Error {
     readonly requestSent: boolean;
     constructor(requestSent: boolean);
 }
+/**
+ * Thrown by `layer.batches.submit()` when a chunk fails after earlier chunks were
+ * already created at the provider. Those batches run and are billed: keep `job` and
+ * read it with `results()`, or pass it to `cancel()`.
+ */
+declare class BatchSubmitError extends Error {
+    /** The batches that were created, as a job you can read or cancel. `batchIds` may be empty. */
+    readonly job: BatchJob;
+    /** Your ids of the requests that were not sent. */
+    readonly notSubmitted: string[];
+    constructor(message: string, job: BatchJob, notSubmitted: string[], options?: {
+        cause?: unknown;
+    });
+}
 
 /**
  * The parts of a SavingsReport the exporters read. A full SavingsReport
@@ -4623,4 +5290,4 @@ declare function toCsv(rows: readonly Readonly<Record<string, CsvValue>>[], opti
     columns?: readonly string[];
 }): string;
 
-export { type AnswerSource, type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BivelioHandoff, CATALOGO, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CacheTier, type CacheWriteReport, type CachedAnswer, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, type CsvValue, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FocusExportOptions, type FocusRow, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, type LangfuseGenerationUpdate, LicenseError, type LicenseGate, type LicenseKeyShape, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type PriceLeverSaving, type PriceLeverSettings, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderStreamEvent, type ProviderStreamOptions, type ProviderUsage, QUALITY_STATUSES, type QualityCacheMatch, type QualityCascadeCheck, type QualityLedger, type QualityRepairCheck, type QualitySchemaCheck, type QualityStatus, type QualityTruncationCheck, REFERENCE_MAX_AGE_MS, REFERENCE_MESSAGE_ALLOWANCE, REFERENCE_OUTPUT_SHARE, type ReferenceCredit, type ReferenceRejection, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsAdapterLevers, type SavingsAdapterOptions, type SavingsAttributeOptions, type SavingsCallOptions, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsRecord, type SavingsReport, type SavingsReportForExport, type SavingsRequest, type SavingsResult, type SavingsSeriesOptions, type SavingsSeriesRow, type SavingsSpanAttributes, type SavingsSpanOptions, type SavingsStream, type SavingsStreamEvent, type SavingsStreamOptions, type SavingsToggles, type SavingsTracingOptions, SchemaRegistry, type SemanticCacheOptions, type SemanticHit, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type SpanAttributeValue, type SpanLike, type SpanStartOptionsLike, StreamAbortedError, type StreamingReport, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolRisk, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, type TracerLike, type TracerProviderLike, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, type VerificationCheck, type VerificationExclusion, type VerificationOutcome, type VerificationReport, type VerificationSettings, type VerificationSide, type VerificationStratum, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, canonicalize, compactRowsSerializer, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, instrumentSavingsLayer, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, licenseKeyShape, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeLicenseKey, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, quitarPrefijoDeProveedor, randomId, recordSavingsOnSpan, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, savingsSpanAttributes, sha256, shouldCompress, stableStringify, toCsv, toFocusRows, toLangfuseGeneration, toSavingsSeries, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };
+export { type AnswerJudge, type AnswerSource, type AnthropicOptions, AnthropicProvider, BV_SALA_VERSION, type BatchCounts, type BatchItemResult, type BatchJob, type BatchJobStatus, type BatchRequest, type BatchResults, BatchSubmitError, type BatchSubmitOptions, type BatchSummary, type BivelioHandoff, CATALOGO, COMPACTION_TRANSFORMS, COMPACT_ROWS_INSTRUCTION, type CacheOutcome, type CachePlacement, type CacheTier, type CacheWriteReport, type CachedAnswer, type CalibrationObservation, type CanonicalRequest, type ChatMessage, type CompactRowsDecodeOptions, type CompactRowsOptions, type CompactVerification, type CompactionTransform, type CompressionEconomics, type CompressionPolicyInput, type CompressionRequest, type CompressionResult, type Compressor, type ConstraintBackend, type ConstraintBackendId, type ConstraintPlan, type ConversationState, type CostBasis, type CostModel, type CsvValue, DEFAULT_COST_MODEL, DEFAULT_MAX_STALENESS_SECONDS, DEFAULT_MIN_SAVED_CHARS, type DeferredExecutionReport, type DeterministicResolver, EMBEDDED_PUBLIC_KEY, type EmbeddingFn, type EvidenceDoc, type ExactCache, ExactTokenizer, type ExecutionClass, ExecutionRouter, type FocusExportOptions, type FocusRow, type FormatChoice, FormatSelector, type FormatSelectorOptions, type HandoffFact, HeuristicEstimator, InMemoryExactCache, InMemorySemanticCache, InMemoryToolSetFreezer, type JsonSchema, type LangfuseGenerationUpdate, LicenseError, type LicenseGate, type LicenseKeyShape, type LicenseKeyset, type LicenseStatus, type LicenseTokenPayload, type LocalClassifier, MODELOS_POR_CODIFICACION, MODELS_BY_ENCODING, type MemoryDelta, type MessageRole, MockProvider, type MockProviderOptions, type ModelCascadeMode, type ModelCascadeReport, type ModelCascadeSettings, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OutputContract, PRECIOS_AL_DIA, type Policy, type PriceLeverSaving, type PriceLeverSettings, type ProtectedSpan, type Provider, type ProviderRequest, type ProviderResponse, type ProviderStreamEvent, type ProviderStreamOptions, type ProviderToolSearch, type ProviderToolSearchUsage, type ProviderUsage, QUALITY_STATUSES, type QualityCacheMatch, type QualityCascadeCheck, type QualityLedger, type QualityRepairCheck, type QualitySchemaCheck, type QualityStatus, type QualityTruncationCheck, REFERENCE_MAX_AGE_MS, REFERENCE_MESSAGE_ALLOWANCE, REFERENCE_OUTPUT_SHARE, type ReferenceCredit, type ReferenceRejection, type RequestContext, type Reranker, type ResolvedDeps, type ResolvedGate, type ResolvedLicense, ResolverRegistry, type ResolverResult, type RetrievalOptions, type RetrievalOutcome, type RetrievalPlan, type Retriever, type RevocationListBody, type RevocationListVerification, type RevocationPollEvent, RevocationPoller, type RevocationPollerOptions, RevocationSnapshot, type RouteDecision, type SavingsAdapterLevers, type SavingsAdapterOptions, type SavingsAttributeOptions, type SavingsBatches, type SavingsCallOptions, type SavingsLayer, type SavingsLayerConfig, SavingsLedger, type SavingsRecord, type SavingsReport, type SavingsReportForExport, type SavingsRequest, type SavingsResult, type SavingsSeriesOptions, type SavingsSeriesRow, type SavingsSpanAttributes, type SavingsSpanOptions, type SavingsStream, type SavingsStreamEvent, type SavingsStreamOptions, type SavingsToggles, type SavingsTracingOptions, SchemaRegistry, type SemanticCacheOptions, type SemanticCalibrationBound, type SemanticCalibrationOptions, type SemanticCalibrationStatus, type SemanticHit, type SemanticLookup, type SemanticProbe, type SemanticRecord, type SemanticVerifier, type SerializationFormat, type Serializer, Singleflight, type SpanAttributeValue, type SpanLike, type SpanStartOptionsLike, StreamAbortedError, type StreamingReport, type TokenEstimator, TokenizerRegistry, type ToolCallRequest, type ToolDescriptor, type ToolOutputCompaction, type ToolOutputCompactionSettings, type ToolRisk, type ToolSearchMode, type ToolSearchOptions, type ToolSelection, ToolSelector, type ToolSelectorOptions, type ToolSetFreezer, TraceCollector, type TraceEvent, type TracerLike, type TracerProviderLike, UMBRAL_LOCAL, UsageEmitter, type UsageEmitterOptions, type ValidationError, type ValidationResult, type VerificationCheck, type VerificationExclusion, type VerificationOutcome, type VerificationReport, type VerificationSettings, type VerificationSide, type VerificationStratum, adaptiveK, arithmeticResolver, buildExactKey, buildInflightKey, calibrateSemanticFloor, canonicalize, compactRowsSerializer, compactToolOutput, compresionFiel, computeNextDelay, cosine, createCompactRowsSerializer, createDefaultResolvers, createHandoff, createMockProvider, createSavingsLayer, csvSerializer, decodeCompactRows, dedupe, defaultTokenizerRegistry, deriveSeatId, deriveStatus, detectCi, embebedorLocal, emptyState, encodeCompactRows, evalArithmetic, evaluatePolicy, executeRetrievalPlan, gateFromKey, heuristicEstimator, instrumentSavingsLayer, isKeyset, isStrictCompatible, jsonCompactSerializer, keyTokensMatch, licenseKeyShape, liveGateFromKey, mergeDelta, modelFamilyOf, multisetEqual, negationCount, noopCompressor, normalizeLicenseKey, normalizeText, numericTokens, precioDeLista, projectContext, providerNativeBackend, quitarPrefijoDeProveedor, randomId, recordSavingsOnSpan, registerExactTokenizer, registrarTokenizadorExacto, renderState, resolveConstraintBackend, resolveDependencies, resolveLicense, sameAnswer, savingsSpanAttributes, sha256, shouldCompress, stableStringify, toCsv, toFocusRows, toLangfuseGeneration, toSavingsSeries, uniformColumns, validateAgainstSchema, vectorLocal, verifyCompactSignature, verifyLicenseToken, verifyRevocationList, withProtectedSpans, words };