@bivelio/savings-layer 0.4.28 → 0.4.29

package/dist/index.d.ts

@@ -311,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.28";
+declare const BV_SALA_VERSION = "0.4.29";
 
 /**
  * Environment-agnostic UUID generation.
@@ -483,7 +483,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 +1126,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 +1309,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 +1863,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 +2155,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 +3178,17 @@ 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;
     /**
      * Llamadas a herramienta que pidió el modelo, tal cual las devolvió el
      * proveedor.
@@ -3724,7 +3775,8 @@ 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.
      */
     silenceWarnings?: boolean;
     /**
@@ -4104,7 +4156,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 +4955,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. */