@usagetap/sdk 1.3.2 → 1.7.0

package/dist/express/index.mjs

@@ -174,6 +174,75 @@ async function pipeToResponse(stream, res, options = {}) {
   }
 }
 var USAGETAP_CORRELATION_HEADER = "x-usage-correlation-id";
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function serializeSamplingError(error) {
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message };
+  }
+  return { message: String(error) };
+}
+function normalizeMeteredOpenAISampling(options) {
+  if (!options) return void 0;
+  if (options === true) return { provider: "openai" };
+  const { provider = "openai", ...policyFields } = options;
+  return {
+    provider,
+    policy: typeof policyFields.rate === "number" ? policyFields : void 0
+  };
+}
+function startMeteredOpenAISampleDecision({
+  usageTap,
+  sampling,
+  beginRequest,
+  input
+}) {
+  if (!sampling) return Promise.resolve(false);
+  return usageTap.shouldSampleAsync(
+    {
+      customerId: beginRequest.customerId,
+      feature: beginRequest.feature,
+      input
+    },
+    sampling.policy
+  );
+}
+async function captureMeteredOpenAISample({
+  usageTap,
+  sampling,
+  decision,
+  ctx,
+  beginRequest,
+  input,
+  response,
+  error,
+  startedAt
+}) {
+  if (!sampling) return;
+  let selected = false;
+  try {
+    selected = await decision;
+  } catch {
+    return;
+  }
+  if (!selected) return;
+  const record = isObjectRecord(response) ? response : {};
+  await usageTap.captureSample({
+    sampleId: ctx.begin.data.callId,
+    callId: ctx.begin.data.callId,
+    customerId: beginRequest.customerId,
+    feature: beginRequest.feature,
+    tags: beginRequest.tags,
+    provider: sampling.provider,
+    model: readString(record.model) ?? readString(input.model),
+    input,
+    ...response === void 0 ? {} : { output: response },
+    usage: record.usage,
+    latencyMs: Date.now() - startedAt,
+    ...error === void 0 ? {} : { error: serializeSamplingError(error) }
+  }).catch(() => void 0);
+}
 function wrapOpenAI(client, usageTap, options = {}) {
   if (!client) {
     throw new UsageTapError("USAGETAP_BAD_REQUEST", "wrapOpenAI requires an OpenAI client instance");
@@ -181,6 +250,8 @@ function wrapOpenAI(client, usageTap, options = {}) {
   const defaultContext = options.defaultContext;
   const applyVendorHints = options.applyVendorHints !== false;
   const defaultPromptCompression = normalizePromptCompressionOptions(options.promptCompression);
+  const defaultSampling = normalizeMeteredOpenAISampling(options.sampling);
+  const provider = options.provider ?? "openai";
   const promptCompressionStats = new OpenAIPromptCompressionStats();
   const proxiedChat = client.chat ? createChatProxy(
     client.chat,
@@ -188,7 +259,9 @@ function wrapOpenAI(client, usageTap, options = {}) {
     defaultContext,
     applyVendorHints,
     defaultPromptCompression,
-    promptCompressionStats
+    promptCompressionStats,
+    defaultSampling,
+    provider
   ) : void 0;
   const proxiedResponses = typeof client.responses !== "undefined" ? createResponsesProxy(
     client.responses,
@@ -196,7 +269,9 @@ function wrapOpenAI(client, usageTap, options = {}) {
     defaultContext,
     applyVendorHints,
     defaultPromptCompression,
-    promptCompressionStats
+    promptCompressionStats,
+    defaultSampling,
+    provider
   ) : void 0;
   const handler = {
     get(target, prop, receiver) {
@@ -223,14 +298,16 @@ function wrapOpenAI(client, usageTap, options = {}) {
   };
   return new Proxy(client, handler);
 }
-function createChatProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
+function createChatProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats, defaultSampling, provider) {
   const completions = createChatCompletionsProxy(
     resource.completions,
     usageTap,
     defaultContext,
     applyVendorHints,
     defaultPromptCompression,
-    promptCompressionStats
+    promptCompressionStats,
+    defaultSampling,
+    provider
   );
   const handler = {
     get(target, prop, receiver) {
@@ -242,7 +319,7 @@ function createChatProxy(resource, usageTap, defaultContext, applyVendorHints, d
   };
   return new Proxy(resource, handler);
 }
-function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
+function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats, defaultSampling, provider) {
   if (!resource || typeof resource !== "object") {
     return void 0;
   }
@@ -257,9 +334,20 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
       withUsage: withUsage2,
       promptCompression
     } = splitUsageOptions(options);
-    const beginRequest = resolveBeginRequest(defaultContext, usageContext);
+    const beginRequest = responsesBeginRequest(
+      resolveBeginRequest(defaultContext, usageContext),
+      params
+    );
     const wantsStream = isStreamingRequest(params);
     return usageTap.withUsage(beginRequest, async (ctx) => {
+      const settle = wantsStream ? deferUsageFinalization(ctx) : void 0;
+      const sampleStartedAt = Date.now();
+      const sampleDecision = wantsStream ? Promise.resolve(false) : startMeteredOpenAISampleDecision({
+        usageTap,
+        sampling: defaultSampling,
+        beginRequest,
+        input: params
+      });
       const hintedParams = applyVendorHints ? applyResponsesVendorHints(params, ctx.begin.data.vendorHints) : params;
       const finalParams = await compressResponsesParamsForCall({
         params: hintedParams,
@@ -271,25 +359,67 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
         withUsage: withUsage2,
         operation: "responses.create"
       });
+      ctx.setUsage(openAIRequestExecutionMetadata(finalParams, provider));
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       if (wantsStream) {
         const apiPromise2 = originalCreate(finalParams, request);
         const wrappedPromise2 = transformApiPromise(apiPromise2, (rawStream) => {
           ensureAsyncIterable(rawStream, "responses.create");
-          const wrappedStream = wrapStreamForUsageTap(rawStream, async () => {
-            const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints);
-            if (usage) {
-              ctx.setUsage(usage);
+          const wrappedStream = wrapStreamForUsageTap(rawStream, async (termination) => {
+            try {
+              if (termination === "complete") {
+                const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints, provider);
+                if (usage) {
+                  ctx.setUsage(usage);
+                }
+              }
+            } catch (error) {
+              ctx.setError({
+                code: "USAGE_FINALIZE_ERROR",
+                message: error instanceof Error ? error.message : String(error)
+              });
+              throw error;
+            } finally {
+              await settle?.();
             }
-          }, ctx);
+          }, ctx, (chunk) => {
+            tryInferUsageFromStreamChunk(
+              chunk,
+              ctx.begin.data.vendorHints,
+              ctx,
+              provider
+            );
+          });
           return wrappedStream;
         });
         return wrappedPromise2;
       }
       const apiPromise = originalCreate(finalParams, request);
-      const wrappedPromise = transformApiPromise(apiPromise, (response) => {
-        tryInferUsage(response, ctx.begin.data.vendorHints, void 0, ctx);
+      const wrappedPromise = transformApiPromise(apiPromise, async (response) => {
+        tryInferUsage(response, ctx.begin.data.vendorHints, void 0, ctx, provider);
+        await captureMeteredOpenAISample({
+          usageTap,
+          sampling: defaultSampling,
+          decision: sampleDecision,
+          ctx,
+          beginRequest,
+          input: params,
+          response,
+          startedAt: sampleStartedAt
+        });
         return response;
+      }, async (error) => {
+        await captureMeteredOpenAISample({
+          usageTap,
+          sampling: defaultSampling,
+          decision: sampleDecision,
+          ctx,
+          beginRequest,
+          input: params,
+          error,
+          startedAt: sampleStartedAt
+        });
+        throw error;
       });
       return wrappedPromise;
     }, withUsage2);
@@ -304,7 +434,7 @@ function createResponsesProxy(resource, usageTap, defaultContext, applyVendorHin
   };
   return new Proxy(resource, handler);
 }
-function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats) {
+function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVendorHints, defaultPromptCompression, promptCompressionStats, defaultSampling, provider) {
   const originalCreate = resource.create.bind(resource);
   const streamCandidate = resource.stream;
   const originalStream = typeof streamCandidate === "function" ? streamCandidate.bind(resource) : void 0;
@@ -318,8 +448,16 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
     const beginRequest = resolveBeginRequest(defaultContext, usageContext);
     const wantsStream = isStreamingRequest(params);
     return usageTap.withUsage(beginRequest, async (ctx) => {
+      const settle = wantsStream ? deferUsageFinalization(ctx) : void 0;
+      const sampleStartedAt = Date.now();
+      const sampleDecision = wantsStream ? Promise.resolve(false) : startMeteredOpenAISampleDecision({
+        usageTap,
+        sampling: defaultSampling,
+        beginRequest,
+        input: params
+      });
       const hintedParams = applyVendorHints ? applyChatVendorHints(params, ctx.begin.data.vendorHints) : params;
-      const finalParams = await compressChatParamsForCall({
+      const compressedParams = await compressChatParamsForCall({
         params: hintedParams,
         usageTap,
         ctx,
@@ -329,25 +467,68 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
         withUsage: withUsage2,
         operation: "chat.completions.create"
       });
+      const finalParams = wantsStream ? ensureOpenAIStreamUsage(compressedParams) : compressedParams;
+      ctx.setUsage(openAIRequestExecutionMetadata(finalParams, provider));
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       if (wantsStream) {
         const apiPromise2 = originalCreate(finalParams, request);
         const wrappedPromise2 = transformApiPromise(apiPromise2, (rawStream) => {
           ensureAsyncIterable(rawStream, "chat.completions.create");
-          const wrappedStream2 = wrapStreamForUsageTap(rawStream, async () => {
-            const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints);
-            if (usage) {
-              ctx.setUsage(usage);
+          const wrappedStream2 = wrapStreamForUsageTap(rawStream, async (termination) => {
+            try {
+              if (termination === "complete") {
+                const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints, provider);
+                if (usage) {
+                  ctx.setUsage(usage);
+                }
+              }
+            } catch (error) {
+              ctx.setError({
+                code: "USAGE_FINALIZE_ERROR",
+                message: error instanceof Error ? error.message : String(error)
+              });
+              throw error;
+            } finally {
+              await settle?.();
             }
-          }, ctx);
+          }, ctx, (chunk) => {
+            tryInferUsageFromStreamChunk(
+              chunk,
+              ctx.begin.data.vendorHints,
+              ctx,
+              provider
+            );
+          });
           return wrappedStream2;
         });
         return wrappedPromise2;
       }
       const apiPromise = originalCreate(finalParams, request);
-      const wrappedPromise = transformApiPromise(apiPromise, (response) => {
-        tryInferUsage(response, ctx.begin.data.vendorHints, void 0, ctx);
+      const wrappedPromise = transformApiPromise(apiPromise, async (response) => {
+        tryInferUsage(response, ctx.begin.data.vendorHints, void 0, ctx, provider);
+        await captureMeteredOpenAISample({
+          usageTap,
+          sampling: defaultSampling,
+          decision: sampleDecision,
+          ctx,
+          beginRequest,
+          input: params,
+          response,
+          startedAt: sampleStartedAt
+        });
         return response;
+      }, async (error) => {
+        await captureMeteredOpenAISample({
+          usageTap,
+          sampling: defaultSampling,
+          decision: sampleDecision,
+          ctx,
+          beginRequest,
+          input: params,
+          error,
+          startedAt: sampleStartedAt
+        });
+        throw error;
       });
       return wrappedPromise;
     }, withUsage2);
@@ -361,8 +542,9 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
     } = splitUsageOptions(options);
     const beginRequest = resolveBeginRequest(defaultContext, usageContext);
     return usageTap.withUsage(beginRequest, async (ctx) => {
+      const settle = deferUsageFinalization(ctx);
       const hintedParams = applyVendorHints ? applyChatVendorHints(params, ctx.begin.data.vendorHints) : params;
-      const finalParams = await compressChatParamsForCall({
+      const compressedParams = await compressChatParamsForCall({
         params: hintedParams,
         usageTap,
         ctx,
@@ -372,16 +554,41 @@ function createChatCompletionsProxy(resource, usageTap, defaultContext, applyVen
         withUsage: withUsage2,
         operation: "chat.completions.stream"
       });
+      const finalParams = ensureOpenAIStreamUsage(compressedParams);
+      ctx.setUsage(openAIRequestExecutionMetadata(finalParams, provider));
       const request = attachCorrelationHeader(requestOptions, ctx.begin.correlationId);
       const apiPromise = originalStream(finalParams, request);
       const wrappedPromise = transformApiPromise(apiPromise, (rawStream) => {
         ensureAsyncIterable(rawStream, "chat.completions.stream");
-        const wrappedStreamInner = wrapStreamForUsageTap(rawStream, async () => {
-          const usage = await extractUsageFromStream(rawStream, ctx.begin.data.vendorHints);
-          if (usage) {
-            ctx.setUsage(usage);
+        const wrappedStreamInner = wrapStreamForUsageTap(rawStream, async (termination) => {
+          try {
+            if (termination === "complete") {
+              const usage = await extractUsageFromStream(
+                rawStream,
+                ctx.begin.data.vendorHints,
+                provider
+              );
+              if (usage) {
+                ctx.setUsage(usage);
+              }
+            }
+          } catch (error) {
+            ctx.setError({
+              code: "USAGE_FINALIZE_ERROR",
+              message: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+          } finally {
+            await settle();
           }
-        }, ctx);
+        }, ctx, (chunk) => {
+          tryInferUsageFromStreamChunk(
+            chunk,
+            ctx.begin.data.vendorHints,
+            ctx,
+            provider
+          );
+        });
         return wrappedStreamInner;
       });
       return wrappedPromise;
@@ -503,6 +710,10 @@ async function compressChatParams(params, usageTap, compression, signal) {
     const result = await usageTap.compressPromptMessages(source, {
       provider: "usagetap",
       failOpen: compression.failOpen,
+      mode: compression.mode,
+      latencyBudgetMs: compression.latencyBudgetMs,
+      compactEmptyUserMessages: compression.compactEmptyUserMessages,
+      compactDuplicateUserTextParts: compression.compactDuplicateUserTextParts,
       aggressiveness: resolveMessageEndpointAggressiveness(compression),
       signal
     });
@@ -972,19 +1183,52 @@ function resolveBeginRequest(defaults, override) {
   if (requested) begin.requested = requested;
   const feature = current.feature ?? base.feature;
   if (feature) begin.feature = feature;
+  const runId = current.runId ?? base.runId;
+  if (runId) begin.runId = runId;
   const idempotency = current.idempotency ?? base.idempotency;
   if (idempotency) begin.idempotency = idempotency;
   const customerName = current.customerName ?? base.customerName;
   if (customerName) begin.customerName = customerName;
   const customerEmail = current.customerEmail ?? base.customerEmail;
   if (customerEmail) begin.customerEmail = customerEmail;
+  const customerUserId = current.customerUserId ?? base.customerUserId;
+  if (customerUserId) begin.customerUserId = customerUserId;
+  const customerUserName = current.customerUserName ?? base.customerUserName;
+  if (customerUserName) begin.customerUserName = customerUserName;
+  const customerUserEmail = current.customerUserEmail ?? base.customerUserEmail;
+  if (customerUserEmail) begin.customerUserEmail = customerUserEmail;
+  const stripeCustomerId = current.stripeCustomerId ?? base.stripeCustomerId;
+  if (stripeCustomerId) begin.stripeCustomerId = stripeCustomerId;
+  const batch = current.batch ?? base.batch;
+  if (typeof batch === "boolean") begin.batch = batch;
+  const pricingMode = current.pricingMode ?? base.pricingMode;
+  if (pricingMode) begin.pricingMode = pricingMode;
   if (tags?.length) {
     begin.tags = tags;
   }
   return begin;
 }
-function transformApiPromise(apiPromise, onResolve) {
-  const resolvedPromise = Promise.resolve(apiPromise).then(onResolve);
+function responsesBeginRequest(begin, params) {
+  if (!responsesRequestUsesWebSearch(params)) return begin;
+  return {
+    ...begin,
+    requested: {
+      ...begin.requested ?? {},
+      search: true
+    }
+  };
+}
+function responsesRequestUsesWebSearch(params) {
+  if (!params || typeof params !== "object") return false;
+  const tools = params.tools;
+  return Array.isArray(tools) && tools.some((tool) => {
+    if (!tool || typeof tool !== "object") return false;
+    const type = tool.type;
+    return type === "web_search" || type === "web_search_preview";
+  });
+}
+function transformApiPromise(apiPromise, onResolve, onReject) {
+  const resolvedPromise = Promise.resolve(apiPromise).then(onResolve, onReject);
   if (isObjectRecord(apiPromise)) {
     const proto = Object.getPrototypeOf(apiPromise);
     if (proto) {
@@ -1119,12 +1363,12 @@ function applyResponsesVendorHints(params, hints) {
   }
   return next;
 }
-async function extractUsageFromStream(stream, hints) {
+async function extractUsageFromStream(stream, hints, provider = "openai") {
   const finalPayload = await resolveStreamFinalPayload(stream);
   if (!finalPayload) {
     return void 0;
   }
-  return inferUsageFromResponse(finalPayload, hints);
+  return inferUsageFromResponse(finalPayload, hints, provider);
 }
 async function resolveStreamFinalPayload(stream) {
   if (!stream || typeof stream !== "object") {
@@ -1197,13 +1441,13 @@ function setHeaderIfPossible(res, key, value) {
     res.setHeader(key, value);
   }
 }
-function tryInferUsage(response, hints, extractor, ctx) {
-  const inferred = inferUsageFromResponse(response, hints);
+function tryInferUsage(response, hints, extractor, ctx, provider = "openai") {
+  const inferred = inferUsageFromResponse(response, hints, provider);
   if (inferred) {
     ctx.setUsage(inferred);
   }
 }
-function inferUsageFromResponse(response, hints) {
+function inferUsageFromResponse(response, hints, provider = "openai") {
   if (!response || typeof response !== "object") {
     return void 0;
   }
@@ -1211,32 +1455,110 @@ function inferUsageFromResponse(response, hints) {
   if (!candidate.usage) {
     return void 0;
   }
-  const cachedInputTokens = candidate.usage.prompt_tokens_details?.cached_tokens ?? candidate.usage.cached_tokens;
+  const cachedInputTokens = candidate.usage.prompt_tokens_details?.cached_tokens ?? candidate.usage.input_tokens_details?.cached_tokens ?? candidate.usage.cached_tokens;
+  const cacheWriteInputTokens = candidate.usage.prompt_tokens_details?.cache_write_tokens ?? candidate.usage.prompt_tokens_details?.cache_creation_tokens ?? candidate.usage.input_tokens_details?.cache_write_tokens ?? candidate.usage.input_tokens_details?.cache_creation_tokens ?? candidate.usage.cache_creation_input_tokens ?? candidate.usage.cache_write_input_tokens ?? candidate.usage.cache_write_tokens;
+  const cacheWrite5mInputTokens = candidate.usage.cache_write_5m_input_tokens ?? candidate.usage.cache_creation?.ephemeral_5m_input_tokens;
+  const cacheWrite1hInputTokens = candidate.usage.cache_write_1h_input_tokens ?? candidate.usage.cache_creation?.ephemeral_1h_input_tokens;
+  const outputSearches = Array.isArray(candidate.output) ? candidate.output.filter((item) => item?.type === "web_search_call").length : 0;
+  const searches = candidate.usage.searches ?? candidate.usage.web_search_queries ?? candidate.usage.server_tool_use?.web_search_requests ?? outputSearches;
+  const responseEffort = normalizeExecutionReasoningEffort(
+    candidate.reasoning?.effort
+  );
   return {
+    providerUsed: provider,
     modelUsed: candidate.model ?? hints?.preferredModel,
-    inputTokens: candidate.usage.prompt_tokens,
-    responseTokens: candidate.usage.completion_tokens,
-    cachedInputTokens
+    inputTokens: candidate.usage.prompt_tokens ?? candidate.usage.input_tokens,
+    responseTokens: candidate.usage.completion_tokens ?? candidate.usage.output_tokens,
+    cachedInputTokens,
+    cacheWriteInputTokens,
+    cacheWrite5mInputTokens,
+    cacheWrite1hInputTokens,
+    audioInputTokens: candidate.usage.prompt_tokens_details?.audio_tokens ?? candidate.usage.input_tokens_details?.audio_tokens,
+    cachedAudioInputTokens: candidate.usage.prompt_tokens_details?.cached_audio_tokens ?? candidate.usage.input_tokens_details?.cached_audio_tokens ?? candidate.usage.prompt_tokens_details?.cached_tokens_details?.audio_tokens ?? candidate.usage.input_tokens_details?.cached_tokens_details?.audio_tokens,
+    imageInputTokens: candidate.usage.prompt_tokens_details?.image_tokens ?? candidate.usage.input_tokens_details?.image_tokens,
+    imageOutputTokens: candidate.usage.completion_tokens_details?.image_tokens ?? candidate.usage.output_tokens_details?.image_tokens,
+    audioOutputTokens: candidate.usage.completion_tokens_details?.audio_tokens ?? candidate.usage.output_tokens_details?.audio_tokens,
+    reasoningTokens: candidate.usage.completion_tokens_details?.reasoning_tokens ?? candidate.usage.output_tokens_details?.reasoning_tokens,
+    ...responseEffort ? {
+      reasoningEffort: responseEffort,
+      reasoningEffortSource: "provider_response"
+    } : {},
+    ...typeof candidate.reasoning?.type === "string" ? { reasoningMode: candidate.reasoning.type } : typeof candidate.reasoning?.mode === "string" ? { reasoningMode: candidate.reasoning.mode } : {},
+    ...typeof searches === "number" && searches > 0 ? { searches } : {}
+  };
+}
+function normalizeExecutionReasoningEffort(value) {
+  return value === "none" || value === "minimal" || value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max" ? value : void 0;
+}
+function openAIRequestExecutionMetadata(params, provider) {
+  const record = params && typeof params === "object" ? params : {};
+  const reasoning = record.reasoning && typeof record.reasoning === "object" ? record.reasoning : void 0;
+  const effort = normalizeExecutionReasoningEffort(
+    record.reasoning_effort ?? reasoning?.effort ?? record.thinking_level
+  );
+  const mode = typeof reasoning?.type === "string" ? reasoning.type : typeof reasoning?.mode === "string" ? reasoning.mode : void 0;
+  const rawBudget = reasoning?.budget_tokens ?? record.thinking_budget ?? record.thinking_budget_tokens;
+  const budget = typeof rawBudget === "number" && Number.isInteger(rawBudget) && rawBudget >= 0 ? rawBudget : void 0;
+  return {
+    providerUsed: provider,
+    ...typeof record.model === "string" ? { modelUsed: record.model } : {},
+    ...effort ? { reasoningEffort: effort, reasoningEffortSource: "provider_request" } : {},
+    ...mode ? { reasoningMode: mode } : {},
+    ...budget !== void 0 ? { reasoningBudgetTokens: budget } : {}
+  };
+}
+function tryInferUsageFromStreamChunk(chunk, hints, ctx, provider) {
+  const payload = isObjectRecord(chunk) && isObjectRecord(chunk.response) ? chunk.response : chunk;
+  const inferred = inferUsageFromResponse(payload, hints, provider);
+  if (inferred) {
+    ctx.setUsage(inferred);
+  }
+}
+function ensureOpenAIStreamUsage(params) {
+  if (!isObjectRecord(params)) {
+    return params;
+  }
+  const streamOptions = isObjectRecord(params.stream_options) ? params.stream_options : {};
+  return {
+    ...params,
+    stream_options: {
+      ...streamOptions,
+      include_usage: true
+    }
   };
 }
-function wrapStreamForUsageTap(source, finalize, ctx) {
+function deferUsageFinalization(ctx) {
+  return ctx.deferFinalization?.() ?? (() => Promise.resolve());
+}
+function wrapStreamForUsageTap(source, finalize, ctx, onChunk) {
   const getIterator = source[Symbol.asyncIterator];
   if (typeof getIterator !== "function") {
     throw new TypeError("Stream is not async iterable");
   }
   const iterator = getIterator.call(source);
   let completed = false;
-  const invokeFinalize = async () => {
+  const invokeFinalize = async (termination, error) => {
     if (completed) return;
     completed = true;
+    if (termination === "cancel" || termination === "manual") {
+      ctx.setError({
+        code: "STREAM_ABORTED",
+        message: termination === "cancel" ? "Provider stream consumption was cancelled before completion" : "Provider stream was finalized before completion"
+      });
+    } else if (termination === "error") {
+      ctx.setError({
+        code: "VENDOR_ERROR",
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
     try {
-      await finalize();
-    } catch (error) {
+      await finalize(termination);
+    } catch (error2) {
       ctx.setError({
         code: "USAGE_FINALIZE_ERROR",
-        message: error instanceof Error ? error.message : String(error)
+        message: error2 instanceof Error ? error2.message : String(error2)
       });
-      throw error;
+      throw error2;
     }
   };
   const prototype = Object.getPrototypeOf(source) ?? Object.prototype;
@@ -1260,12 +1582,15 @@ function wrapStreamForUsageTap(source, finalize, ctx) {
     value: async (...args) => {
       try {
         const result = await iterator.next(...args);
+        if (!result.done) {
+          onChunk?.(result.value);
+        }
         if (result.done) {
-          await invokeFinalize();
+          await invokeFinalize("complete");
         }
         return result;
       } catch (error) {
-        await invokeFinalize().catch(() => void 0);
+        await invokeFinalize("error", error).catch(() => void 0);
         throw error;
       }
     },
@@ -1274,39 +1599,49 @@ function wrapStreamForUsageTap(source, finalize, ctx) {
   });
   Object.defineProperty(wrapped, "return", {
     value: async (value) => {
-      if (typeof iterator.return === "function") {
-        const rawResult = await iterator.return(value);
-        if (!isIteratorResult(rawResult)) {
-          throw new TypeError("Iterator.return() returned an invalid result");
+      try {
+        if (typeof iterator.return === "function") {
+          const rawResult = await iterator.return(value);
+          if (!isIteratorResult(rawResult)) {
+            throw new TypeError("Iterator.return() returned an invalid result");
+          }
+          await invokeFinalize("cancel");
+          return rawResult;
         }
-        await invokeFinalize();
-        return rawResult;
+        await invokeFinalize("cancel");
+        return { done: true, value };
+      } catch (error) {
+        await invokeFinalize("error", error).catch(() => void 0);
+        throw error;
       }
-      await invokeFinalize();
-      return { done: true, value };
     },
     configurable: true,
     writable: true
   });
   Object.defineProperty(wrapped, "throw", {
     value: async (error) => {
-      if (typeof iterator.throw === "function") {
-        const rawResult = await iterator.throw(error);
-        if (!isIteratorResult(rawResult)) {
-          throw new TypeError("Iterator.throw() returned an invalid result");
+      try {
+        if (typeof iterator.throw === "function") {
+          const rawResult = await iterator.throw(error);
+          if (!isIteratorResult(rawResult)) {
+            throw new TypeError("Iterator.throw() returned an invalid result");
+          }
+          await invokeFinalize("error", error);
+          return rawResult;
         }
-        await invokeFinalize();
-        return rawResult;
+        await invokeFinalize("error", error);
+        throw error;
+      } catch (thrownError) {
+        await invokeFinalize("error", thrownError).catch(() => void 0);
+        throw thrownError;
       }
-      await invokeFinalize();
-      throw error;
     },
     configurable: true,
     writable: true
   });
   Object.defineProperty(wrapped, "__usageTapFinalize", {
     value: async () => {
-      await invokeFinalize();
+      await invokeFinalize("manual");
     },
     configurable: true
   });