@bivelio/savings-layer 0.4.28 → 0.4.30

package/dist/index.d.ts

@@ -232,6 +232,20 @@ declare class SavingsLedger {
     providerCached(tokens: number): void;
     /** Record the premium for `tokens` of cache write the provider bills at `multiplier`x on its own. */
     providerCacheWritePremium(tokens: number, multiplier: number, price: CostModel): void;
+    /** Input tokens of calls the provider documents as not billed; already included in `actualInput`. */
+    unbilledInput: number;
+    /** Output tokens of those calls; already included in `actualOutput`. */
+    unbilledOutput: number;
+    /** Provider-cached input tokens of those calls; already included in `providerCachedInput`. */
+    unbilledCachedInput: number;
+    /** True when the answer served is a refusal the provider does not bill: no saving is credited. */
+    servedUnbilledRefusal: boolean;
+    /** Record a call the provider documents as not billed: its tokens stay counted and are priced at 0. */
+    unbilledCall(usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cachedInputTokens?: number;
+    }): void;
     /** Set when an avoided call is valued against the provider counter of an identical call that ran. */
     reference: ReferenceCredit | null;
     /** Set when an avoided cache or coalesced hit could not be valued by reference: why it stays estimated. */
@@ -311,7 +325,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.28";
+declare const BV_SALA_VERSION = "0.4.30";
 
 /**
  * Environment-agnostic UUID generation.
@@ -483,7 +497,12 @@ interface ChatMessage {
      * ids included.
      */
     toolCalls?: ToolCallRequest[];
-    /** Opaque provider metadata; never used for the exact-cache key. */
+    /**
+     * Opaque provider metadata; never used for the exact-cache key. The one
+     * exception is `tool_call_id` on a `role: "tool"` message: the OpenAI
+     * adapter still sends it as the call id when `toolCallId` is absent,
+     * so the key reads it as that same field.
+     */
     metadata?: Record<string, unknown>;
 }
 /** How a request is classified by the execution router. */
@@ -1121,6 +1140,14 @@ interface SavingsResult<T = unknown> {
      * (caché/resolver), que solo sirven respuestas finales completas.
      */
     finishReason?: string;
+    /**
+     * The refusal message the model returned instead of an answer (OpenAI
+     * Structured Outputs: `message.refusal`, with `finish_reason: "stop"` and no
+     * content). When present, the request was refused: `text` is empty and no
+     * output contract was met. It is measured like any call, and it is never
+     * repaired, cached or replayed.
+     */
+    refusal?: string;
     report: SavingsReport;
 }
 /** One event of a streamed answer. */
@@ -1296,8 +1323,9 @@ interface QualityRepairCheck {
      * - `decode_time_constraint`: generation was already constrained, so a retry
      *   would not change the outcome.
      * - `provider_refusal`: the provider refused the request (`finishReason:
-     *   "content_filter"`, Anthropic's `stop_reason: "refusal"`); a repair on the
-     *   same model would be refused, and may be billed, again.
+     *   "content_filter"`, Anthropic's `stop_reason: "refusal"`, or OpenAI's
+     *   `message.refusal`); a repair on the same model would be refused, and may
+     *   be billed, again.
      */
     skipReason?: "output_truncated" | "schema_defect" | "would_cost_more_than_no_layer" | "decode_time_constraint" | "provider_refusal";
 }
@@ -1849,6 +1877,25 @@ interface CanonicalRequest {
     normalizedText: string;
     systemPromptHash: string;
     toolsetHash: string;
+    /**
+     * Hash of the tool-loop fields of the conversation, the part of each turn
+     * that `normalizedText` does not carry: the calls on an assistant turn (name,
+     * arguments and id) and, on a `role: "tool"` message, the call it answers,
+     * its error flag and its name. Part of the exact key, the in-flight key and
+     * the semantic filter, so two conversations that differ only there never
+     * share an answer.
+     *
+     * Call ids count by what they pair, not by their value: results matched to
+     * other calls give another hash, while the same conversation with its ids
+     * consistently renamed (a new run of the same agent loop gets fresh ids from
+     * the provider) keeps it.
+     *
+     * Absent when the request carries none of them: the keys are then built from
+     * exactly the same material as before this field existed. A field that is
+     * present but empty or false (`toolCalls: []`, `isError: false`, `name: ""`)
+     * reaches the provider exactly as an absent one, and counts as absent.
+     */
+    toolTurnsHash?: string;
     /** Hash of the structured payload; part of the cache key so different data never collides. */
     structuredDataHash: string;
     schemaVersion: string;
@@ -2122,6 +2169,13 @@ interface SemanticRecord {
     safetyPolicyVersion: string;
     /** Hash of the declared tool catalog (ids, risk and parameters). */
     toolsetHash: string;
+    /**
+     * Hash of the tool-loop fields of the conversation (tool calls, the call each
+     * tool result answers, its error flag and name); absent when it had none.
+     * Compared for equality like the other identity fields: similarity is scored
+     * on text only, and never decides between two tool loops.
+     */
+    toolTurnsHash?: string;
     /** Sampling temperature of the request, or null when it set none. */
     temperature: number | null;
     /** Sampling seed of the request, or null when it set none. */
@@ -3138,6 +3192,30 @@ interface ProviderResponse {
      * podía distinguirlo y hacía exactamente eso.
      */
     finishReason?: "stop" | "length" | "content_filter" | "tool_calls" | (string & {});
+    /**
+     * The refusal message the model returned INSTEAD of an answer, exactly as the
+     * provider wrote it: OpenAI's `message.refusal` (Chat Completions with
+     * Structured Outputs), which arrives with `finish_reason: "stop"` and no
+     * `content`. Present only when non-empty.
+     *
+     * The layer treats it like `finishReason: "content_filter"`: the call is
+     * measured, and the answer is never repaired against its contract, cached, or
+     * replayed by reference. `text` and `finishReason` stay what the provider said.
+     */
+    refusal?: string;
+    /**
+     * True when this answer is a refusal the provider documents as NOT billed:
+     * Anthropic's Messages API refusal that arrives before any output, in a
+     * category its published table marks as not billed (`cyber`,
+     * `general_harms`, or a `null` category). See
+     * https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback
+     * («How refusals are billed»).
+     *
+     * The layer then measures this call at cost 0 and credits no saving on the
+     * request at all (measured, estimated or by reference). Absent means billed
+     * like any other call. Set it only from the provider's own response.
+     */
+    unbilledRefusal?: boolean;
     /**
      * Llamadas a herramienta que pidió el modelo, tal cual las devolvió el
      * proveedor.
@@ -3724,7 +3802,19 @@ interface SavingsLayerConfig {
      * revocation list going stale. Nothing here throws and nothing here changes
      * what the layer does — turning it on only removes the console noise, so set
      * it when you have your own observability. Applies to the pipeline, the usage
-     * emitter and the revocation poller alike.
+     * emitter, the revocation poller and the provider adapters shipped in this
+     * package alike.
+     *
+     * **One warning is NOT silenced: a rejected renewal credential.** When the
+     * automatic pickup of the renewed license gets HTTP 401, 403 or 404 (the
+     * `serviceAccountKey` was rotated, belongs to another organization, or
+     * `licenseServerUrl` is wrong), the SDK warns even with this flag on. That is
+     * not a degraded saving: the token will not renew and the layer will stop
+     * operating when the grace period ends, and the failure happens inside the SDK
+     * where your own observability cannot see it. It is printed once per status
+     * code per layer, never on every renewal attempt, and it never contains the
+     * key or any part of it. Fix the credential, or turn the pickup off with
+     * {@link licenseRefresh}`.enabled = false`, to make it go away.
      */
     silenceWarnings?: boolean;
     /**
@@ -4104,7 +4194,8 @@ declare const registrarTokenizadorExacto: typeof registerExactTokenizer;
  *
  * A hash of the user text alone is NOT a safe cache key. Two requests may share
  * text but differ in tenant, permission scope, model version, system prompt,
- * schema, toolset, locale, sampling, knowledge epoch or safety policy — any of
+ * schema, toolset, tool-loop fields (tool calls, the call a tool result answers,
+ * its error flag), locale, sampling, knowledge epoch or safety policy — any of
  * which can change the correct answer. The exact key includes all of them.
  *
  * `servedModel` CARRIES THE MODEL THAT WILL ACTUALLY ANSWER, not the one the
@@ -4902,7 +4993,6 @@ declare class RevocationPoller {
     private consecutiveFailures;
     private stopped;
     private started;
-    private warnedNoFetch;
     /** ETag of the last 200; sent as If-None-Match so an unchanged list 304s (cheap no-op). */
     private lastEtag;
     /** 304 seguidos; al llegar al tope se fuerza una descarga firmada. */