@posthog/ai 8.6.4 → 8.6.6

package/dist/openai/index.mjs

@@ -41,14 +41,16 @@ const FILE_FAMILY_TYPES = new Set(['file', 'input_file', 'document', 'media', 'f
 const KNOWN_AUDIO_FORMATS = new Set(['wav', 'mp3', 'ogg', 'flac', 'm4a', 'aac', 'webm']);
 class MediaTypeContext {
   static EMPTY = new MediaTypeContext(undefined, undefined);
-  constructor(parent, key) {
+  constructor(parent, key, explicitMediaType) {
     this.parent = parent;
     this.key = key;
+    this.explicitMediaType = explicitMediaType;
   }
   inferMediaType() {
     return this.inferFromSiblingMime() ?? this.inferFromSiblingFormat() ?? this.inferFromParentType() ?? this.inferFromKey();
   }
   inferFromSiblingMime() {
+    if (this.explicitMediaType) return this.explicitMediaType;
     if (!this.parent) return undefined;
     for (const hint of MIME_HINT_KEYS) {
       const v = this.parent[hint];
@@ -83,7 +85,13 @@ class MediaTypeContext {
     if (key.includes('file') || key.includes('document')) return 'application/octet-stream';
     return undefined;
   }
+  hasExplicitBinaryMediaType() {
+    if (!this.explicitMediaType && (!this.parent || !this.key || !STRONG_CONTEXT_KEYS.has(this.key))) return false;
+    const mediaType = this.inferFromSiblingMime();
+    return mediaType !== undefined && !mediaType.toLowerCase().startsWith('text/');
+  }
   signalsBinary() {
+    if (this.explicitMediaType) return true;
     if (this.parent) {
       for (const hint of MIME_HINT_KEYS) {
         if (typeof this.parent[hint] === 'string') return true;
@@ -105,10 +113,10 @@ class BinaryContentRedactor {
   constructor(recognizer = new Base64Recognizer()) {
     this.recognizer = recognizer;
   }
-  redact(value) {
+  redact(value, mediaType) {
     if (this.isMultimodalEnabled()) return value;
     this.visited = new WeakSet();
-    return this.walk(value, MediaTypeContext.EMPTY);
+    return this.walk(value, mediaType ? new MediaTypeContext(undefined, undefined, mediaType) : MediaTypeContext.EMPTY);
   }
   walk(value, ctx) {
     if (value === null || value === undefined) return value;
@@ -132,8 +140,10 @@ class BinaryContentRedactor {
     return out;
   }
   redactString(value, ctx) {
-    const minLength = ctx.signalsBinary() ? STRONG_CONTEXT_MIN_LENGTH : WEAK_CONTEXT_MIN_LENGTH;
-    const recognition = this.recognizer.recognize(value, minLength);
+    const hasExplicitBinaryMediaType = ctx.hasExplicitBinaryMediaType();
+    const recognitionValue = hasExplicitBinaryMediaType ? value.replace(/[\r\n]/g, '') : value;
+    const minLength = hasExplicitBinaryMediaType ? Math.min(recognitionValue.length, STRONG_CONTEXT_MIN_LENGTH) : ctx.signalsBinary() ? STRONG_CONTEXT_MIN_LENGTH : WEAK_CONTEXT_MIN_LENGTH;
+    const recognition = this.recognizer.recognize(recognitionValue, minLength);
     switch (recognition.kind) {
       case 'data-url':
         return this.placeholderFor(recognition.mediaType);
@@ -534,7 +544,7 @@ function formatOpenAIResponsesInput(input, instructions) {
   return messages;
 }
 
-var version = "8.6.4";
+var version = "8.6.6";
 
 const DEFAULT_MAX_DEPTH = 3;
 const MAX_STACK_LINES = 20;
@@ -732,7 +742,9 @@ const captureAiGeneration$1 = async (client, options) => {
         $ai_output_tokens: usage.outputTokens
       } : {}),
       ...additionalTokenValues,
-      $ai_latency: options.latency ?? 0,
+      ...(options.latency !== undefined ? {
+        $ai_latency: options.latency
+      } : {}),
       ...(options.timeToFirstToken !== undefined ? {
         $ai_time_to_first_token: options.timeToFirstToken
       } : {}),
@@ -834,7 +846,7 @@ function extractRequestId(result) {
  * Assembles the `$ai_provider_metadata` blob for OpenAI / Azure OpenAI events.
  * Provider-specific fields (system fingerprint, request id) live here rather
  * than in the shared, provider-agnostic `$ai_*` namespace. Only keys with a
- * truthy value are included, and `undefined` is returned when there is nothing
+ * meaningful value are included, and `undefined` is returned when there is nothing
  * to report so the property can be omitted from the event entirely.
  */
 function buildProviderMetadata(fields) {
@@ -845,8 +857,104 @@ function buildProviderMetadata(fields) {
   if (fields.requestId) {
     metadata.request_id = fields.requestId;
   }
+  if (fields.incompleteDetails != null) {
+    metadata.incomplete_details = fields.incompleteDetails;
+  }
   return Object.keys(metadata).length > 0 ? metadata : undefined;
 }
+const TERMINAL_RESPONSE_STATUSES = new Set(['completed', 'failed', 'cancelled', 'incomplete']);
+
+/**
+ * Checks whether a Responses API response has reached a status that should
+ * produce a final `$ai_generation` event.
+ */
+function isTerminalResponse(response) {
+  return !!response?.status && TERMINAL_RESPONSE_STATUSES.has(response.status);
+}
+
+/**
+ * Returns an isolated copy of a failed Responses API error for `$ai_error`, or
+ * creates a fallback error when the provider omitted failure details.
+ */
+function getResponseFailure(response) {
+  if (response?.status !== 'failed') {
+    return undefined;
+  }
+  return response.error ? {
+    ...response.error
+  } : new Error(`OpenAI response ${response.id} failed without error details`);
+}
+
+function isPendingBackgroundResponse(params, response) {
+  return params.background === true && !!response.status && !isTerminalResponse(response);
+}
+
+/**
+ * Uses provider timestamps so background polling cadence does not inflate
+ * generation latency. Non-completed responses do not expose a terminal time.
+ */
+function getBackgroundResponseLatency(response) {
+  if (typeof response.created_at !== 'number' || typeof response.completed_at !== 'number') {
+    return undefined;
+  }
+  return Math.max(0, response.completed_at - response.created_at);
+}
+
+/**
+ * Keeps the original create context available while a background response is
+ * polled. Entries are insertion ordered, so the oldest context is discarded
+ * when the bound is reached.
+ */
+class BackgroundResponseTracker {
+  contexts = new Map();
+  constructor(maxEntries = 1000) {
+    this.maxEntries = maxEntries;
+  }
+  set(responseID, context) {
+    // Refresh an existing response's insertion order.
+    this.contexts.delete(responseID);
+    this.contexts.set(responseID, context);
+    while (this.contexts.size > this.maxEntries) {
+      const oldestResponseID = this.contexts.keys().next().value;
+      if (oldestResponseID === undefined) {
+        break;
+      }
+      this.contexts.delete(oldestResponseID);
+    }
+  }
+  get(responseID) {
+    return this.contexts.get(responseID);
+  }
+  take(responseID) {
+    const context = this.contexts.get(responseID);
+    if (context !== undefined) {
+      this.contexts.delete(responseID);
+    }
+    return context;
+  }
+}
+
+/**
+ * Inspects a streamed background retrieval without consuming it on the
+ * caller's behalf. The stored create context is consumed only by a terminal
+ * response; an interrupted or nonterminal stream may be followed by another
+ * retrieval while the background job continues.
+ */
+function wrapBackgroundResponseStream(stream, responseID, tracker, captureTerminalResponse) {
+  async function* inspectStream() {
+    for await (const event of stream) {
+      if ('response' in event && isTerminalResponse(event.response)) {
+        const context = tracker.take(responseID);
+        if (context) {
+          // Monitoring must not delay or disrupt delivery of the provider stream.
+          void captureTerminalResponse(event.response, context).catch(() => undefined);
+        }
+      }
+      yield event;
+    }
+  }
+  return new Stream(() => inspectStream(), stream.controller);
+}
 
 function addRequestId(result, response, requestIdHeader) {
   if (!result || typeof result !== 'object' || Array.isArray(result)) {
@@ -1326,7 +1434,7 @@ let WrappedCompletions$1 = class WrappedCompletions extends AzureOpenAI.Chat.Com
                 model: openAIParams.model ?? modelFromResponse,
                 provider: 'azure',
                 input: sanitizeOpenAI(openAIParams.messages),
-                output: formattedOutput,
+                output: sanitizeOpenAIResponse(formattedOutput),
                 latency,
                 timeToFirstToken,
                 baseURL: this.baseURL,
@@ -1382,8 +1490,8 @@ let WrappedCompletions$1 = class WrappedCompletions extends AzureOpenAI.Chat.Com
             ...posthogParams,
             model: openAIParams.model ?? result.model,
             provider: 'azure',
-            input: openAIParams.messages,
-            output: formatResponseOpenAI(result),
+            input: sanitizeOpenAI(openAIParams.messages),
+            output: sanitizeOpenAIResponse(formatResponseOpenAI(result)),
             latency,
             baseURL: this.baseURL,
             modelParameters: getModelParams(body, result.service_tier),
@@ -1408,7 +1516,7 @@ let WrappedCompletions$1 = class WrappedCompletions extends AzureOpenAI.Chat.Com
           ...posthogParams,
           model: openAIParams.model,
           provider: 'azure',
-          input: openAIParams.messages,
+          input: sanitizeOpenAI(openAIParams.messages),
           output: [],
           latency: 0,
           baseURL: this.baseURL,
@@ -1427,11 +1535,43 @@ let WrappedCompletions$1 = class WrappedCompletions extends AzureOpenAI.Chat.Com
   }
 };
 let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
+  backgroundResponses = new BackgroundResponseTracker();
   constructor(client, phClient) {
     super(client);
     this.phClient = phClient;
     this.baseURL = client.baseURL;
   }
+  async captureBackgroundResponse(result, context) {
+    const {
+      openAIParams,
+      posthogParams
+    } = context;
+    await captureAiGeneration(this.phClient, {
+      ...posthogParams,
+      model: openAIParams.model ?? result.model,
+      provider: 'azure',
+      input: formatOpenAIResponsesInput(openAIParams.input, openAIParams.instructions),
+      output: result.output,
+      latency: getBackgroundResponseLatency(result),
+      baseURL: this.baseURL,
+      modelParameters: getModelParams(openAIParams, result.service_tier),
+      httpStatus: 200,
+      usage: {
+        inputTokens: result.usage?.input_tokens ?? 0,
+        outputTokens: result.usage?.output_tokens ?? 0,
+        reasoningTokens: result.usage?.output_tokens_details?.reasoning_tokens ?? 0,
+        cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0,
+        rawUsage: result.usage
+      },
+      stopReason: result.status ?? undefined,
+      completionId: result.id,
+      providerMetadata: buildProviderMetadata({
+        requestId: extractRequestId(result),
+        incompleteDetails: result.incomplete_details
+      }),
+      error: getResponseFailure(result)
+    });
+  }
 
   // --- Overload #1: Non-streaming
 
@@ -1464,6 +1604,7 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
                 inputTokens: 0,
                 outputTokens: 0
               };
+              let terminalResponse;
               for await (const chunk of stream1) {
                 // Track first token time on content delta events
                 if (firstTokenTime === undefined && isResponseTokenChunk(chunk)) {
@@ -1477,12 +1618,19 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
                   if (!completionIdFromResponse && chunk.response.id) {
                     completionIdFromResponse = chunk.response.id;
                   }
+                  if (openAIParams.background === true && !this.backgroundResponses.get(chunk.response.id)) {
+                    this.backgroundResponses.set(chunk.response.id, {
+                      openAIParams,
+                      posthogParams
+                    });
+                  }
                   if (chunk.response.service_tier != null) {
                     serviceTierFromResponse = chunk.response.service_tier;
                   }
-                }
-                if (chunk.type === 'response.completed' && 'response' in chunk && chunk.response?.output && chunk.response.output.length > 0) {
-                  finalContent = chunk.response.output;
+                  if (isTerminalResponse(chunk.response)) {
+                    terminalResponse = chunk.response;
+                    finalContent = chunk.response.output ?? [];
+                  }
                 }
                 if ('response' in chunk && chunk.response?.usage) {
                   usage = {
@@ -1493,28 +1641,45 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
                   };
                 }
               }
+              if (openAIParams.background === true) {
+                if (terminalResponse) {
+                  const context = this.backgroundResponses.take(terminalResponse.id);
+                  if (context) {
+                    await this.captureBackgroundResponse(terminalResponse, context).catch(() => undefined);
+                  }
+                }
+                return;
+              }
               const latency = (Date.now() - startTime) / 1000;
               const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               await captureAiGeneration(this.phClient, {
                 ...posthogParams,
                 model: openAIParams.model ?? modelFromResponse,
                 provider: 'azure',
-                input: formatOpenAIResponsesInput(openAIParams.input, openAIParams.instructions),
-                output: finalContent,
+                input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
+                output: sanitizeOpenAIResponse(finalContent),
                 latency,
                 timeToFirstToken,
                 baseURL: this.baseURL,
                 modelParameters: getModelParams(body, serviceTierFromResponse),
                 httpStatus: 200,
                 usage,
-                completionId: completionIdFromResponse
+                stopReason: terminalResponse?.status ?? undefined,
+                completionId: completionIdFromResponse,
+                providerMetadata: buildProviderMetadata({
+                  incompleteDetails: terminalResponse?.incomplete_details
+                }),
+                error: getResponseFailure(terminalResponse)
               });
             } catch (error) {
+              if (openAIParams.background === true && completionIdFromResponse && this.backgroundResponses.get(completionIdFromResponse)) {
+                throw error;
+              }
               await captureAiGeneration(this.phClient, {
                 ...posthogParams,
                 model: openAIParams.model,
                 provider: 'azure',
-                input: formatOpenAIResponsesInput(openAIParams.input, openAIParams.instructions),
+                input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
                 output: [],
                 latency: 0,
                 baseURL: this.baseURL,
@@ -1542,13 +1707,20 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
     } else {
       const wrappedPromise = parentPromise.then(async result => {
         if ('output' in result) {
+          if (isPendingBackgroundResponse(openAIParams, result)) {
+            this.backgroundResponses.set(result.id, {
+              openAIParams,
+              posthogParams
+            });
+            return result;
+          }
           const latency = (Date.now() - startTime) / 1000;
           await captureAiGeneration(this.phClient, {
             ...posthogParams,
             model: openAIParams.model ?? result.model,
             provider: 'azure',
-            input: formatOpenAIResponsesInput(openAIParams.input, openAIParams.instructions),
-            output: result.output,
+            input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
+            output: sanitizeOpenAIResponse(result.output),
             latency,
             baseURL: this.baseURL,
             modelParameters: getModelParams(body, result.service_tier),
@@ -1557,12 +1729,16 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
               inputTokens: result.usage?.input_tokens ?? 0,
               outputTokens: result.usage?.output_tokens ?? 0,
               reasoningTokens: result.usage?.output_tokens_details?.reasoning_tokens ?? 0,
-              cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0
+              cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0,
+              rawUsage: result.usage
             },
+            stopReason: result.status ?? undefined,
             completionId: result.id,
             providerMetadata: buildProviderMetadata({
-              requestId: extractRequestId(result)
-            })
+              requestId: extractRequestId(result),
+              incompleteDetails: result.incomplete_details
+            }),
+            error: getResponseFailure(result)
           });
         }
         return result;
@@ -1572,7 +1748,7 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
           ...posthogParams,
           model: openAIParams.model,
           provider: 'azure',
-          input: formatOpenAIResponsesInput(openAIParams.input, openAIParams.instructions),
+          input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
           output: [],
           latency: 0,
           baseURL: this.baseURL,
@@ -1589,6 +1765,55 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
       return preserveProviderPromise(parentPromise, wrappedPromise);
     }
   }
+  retrieve(responseID, query = {}, options) {
+    const parentPromise = super.retrieve(responseID, query, options);
+
+    // Preserve the upstream promise and stream unchanged for responses that
+    // were not created through this client.
+    if (!this.backgroundResponses.get(responseID)) {
+      return parentPromise;
+    }
+    if (query.stream) {
+      return parentPromise._thenUnwrap(result => {
+        if ('controller' in result) {
+          return wrapBackgroundResponseStream(result, responseID, this.backgroundResponses, (response, context) => this.captureBackgroundResponse(response, context));
+        }
+        return result;
+      });
+    }
+    return parentPromise._thenUnwrap(async result => {
+      if (!('output' in result) || !isTerminalResponse(result)) {
+        return result;
+      }
+
+      // Removing the context before capture makes concurrent or repeated
+      // terminal polls idempotent.
+      const context = this.backgroundResponses.take(responseID);
+      if (context) {
+        await this.captureBackgroundResponse(result, context).catch(() => undefined);
+      }
+      return result;
+    });
+  }
+  cancel(responseID, options) {
+    const parentPromise = super.cancel(responseID, options);
+
+    // Avoid wrapping calls that do not belong to a background response created
+    // through this client, preserving the upstream APIPromise unchanged.
+    if (!this.backgroundResponses.get(responseID)) {
+      return parentPromise;
+    }
+    return parentPromise._thenUnwrap(async result => {
+      if (!isTerminalResponse(result)) {
+        return result;
+      }
+      const context = this.backgroundResponses.take(responseID);
+      if (context) {
+        await this.captureBackgroundResponse(result, context).catch(() => undefined);
+      }
+      return result;
+    });
+  }
   parse(body, options) {
     const {
       providerParams: openAIParams,
@@ -1597,13 +1822,20 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
     const startTime = Date.now();
     const parentPromise = callWithOriginalCreate(this, super.create.bind(this), () => super.parse(openAIParams, options));
     const wrappedPromise = parentPromise.then(async result => {
+      if (isPendingBackgroundResponse(openAIParams, result)) {
+        this.backgroundResponses.set(result.id, {
+          openAIParams,
+          posthogParams
+        });
+        return result;
+      }
       const latency = (Date.now() - startTime) / 1000;
       await captureAiGeneration(this.phClient, {
         ...posthogParams,
         model: openAIParams.model ?? result.model,
         provider: 'azure',
-        input: formatOpenAIResponsesInput(openAIParams.input, openAIParams.instructions),
-        output: result.output,
+        input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
+        output: sanitizeOpenAIResponse(result.output),
         latency,
         baseURL: this.baseURL,
         modelParameters: getModelParams(body, result.service_tier),
@@ -1612,12 +1844,16 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
           inputTokens: result.usage?.input_tokens ?? 0,
           outputTokens: result.usage?.output_tokens ?? 0,
           reasoningTokens: result.usage?.output_tokens_details?.reasoning_tokens ?? 0,
-          cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0
+          cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0,
+          rawUsage: result.usage
         },
+        stopReason: result.status ?? undefined,
         completionId: result.id,
         providerMetadata: buildProviderMetadata({
-          requestId: extractRequestId(result)
-        })
+          requestId: extractRequestId(result),
+          incompleteDetails: result.incomplete_details
+        }),
+        error: getResponseFailure(result)
       });
       return result;
     }, async error => {
@@ -1625,7 +1861,7 @@ let WrappedResponses$1 = class WrappedResponses extends AzureOpenAI.Responses {
         ...posthogParams,
         model: openAIParams.model,
         provider: 'azure',
-        input: formatOpenAIResponsesInput(openAIParams.input, openAIParams.instructions),
+        input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
         output: [],
         latency: 0,
         baseURL: this.baseURL,
@@ -1715,10 +1951,6 @@ async function captureAiGenerationAfterSuccess(...args) {
     captureAiGenerationInBackground(...args);
   }
 }
-const TERMINAL_RESPONSE_STATUSES = new Set(['completed', 'failed', 'cancelled', 'incomplete']);
-function isPendingBackgroundResponse(params, response) {
-  return params.background === true && !response.usage && !!response.status && !TERMINAL_RESPONSE_STATUSES.has(response.status);
-}
 class PostHogOpenAI extends OpenAI {
   constructor(config) {
     const {
@@ -1905,7 +2137,7 @@ class WrappedCompletions extends Completions {
                 model: openAIParams.model ?? modelFromResponse,
                 provider: 'openai',
                 input: sanitizeOpenAI(openAIParams.messages),
-                output: formattedOutput,
+                output: sanitizeOpenAIResponse(formattedOutput),
                 latency,
                 timeToFirstToken,
                 baseURL: this.baseURL,
@@ -1973,7 +2205,7 @@ class WrappedCompletions extends Completions {
             model: openAIParams.model ?? result.model,
             provider: 'openai',
             input: sanitizeOpenAI(openAIParams.messages),
-            output: formattedOutput,
+            output: sanitizeOpenAIResponse(formattedOutput),
             latency,
             baseURL: this.baseURL,
             modelParameters: getModelParams(body, result.service_tier),
@@ -2021,11 +2253,47 @@ class WrappedCompletions extends Completions {
   }
 }
 class WrappedResponses extends Responses {
+  backgroundResponses = new BackgroundResponseTracker();
   constructor(client, phClient) {
     super(client);
     this.phClient = phClient;
     this.baseURL = client.baseURL;
   }
+  async captureBackgroundResponse(result, context) {
+    const {
+      openAIParams,
+      posthogParams
+    } = context;
+    await captureAiGenerationAfterSuccess(this.phClient, {
+      ...posthogParams,
+      model: openAIParams.model ?? result.model,
+      provider: 'openai',
+      input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
+      output: formatResponseOpenAI({
+        output: result.output
+      }),
+      latency: getBackgroundResponseLatency(result),
+      baseURL: this.baseURL,
+      modelParameters: getModelParams(openAIParams, result.service_tier),
+      httpStatus: 200,
+      usage: {
+        inputTokens: result.usage?.input_tokens ?? 0,
+        outputTokens: result.usage?.output_tokens ?? 0,
+        reasoningTokens: result.usage?.output_tokens_details?.reasoning_tokens ?? 0,
+        cacheReadInputTokens: result.usage?.input_tokens_details?.cached_tokens ?? 0,
+        webSearchCount: calculateWebSearchCount(result),
+        rawUsage: result.usage
+      },
+      stopReason: result.status ?? undefined,
+      tools: extractAvailableToolCalls('openai', openAIParams),
+      completionId: result.id,
+      providerMetadata: buildProviderMetadata({
+        requestId: extractRequestId(result),
+        incompleteDetails: result.incomplete_details
+      }),
+      error: getResponseFailure(result)
+    });
+  }
 
   // --- Overload #1: Non-streaming
 
@@ -2061,6 +2329,7 @@ class WrappedResponses extends Responses {
                 webSearchCount: 0
               };
               let rawUsageData;
+              let terminalResponse;
               for await (const chunk of stream1) {
                 // Track first token time on content delta events
                 if (firstTokenTime === undefined && isResponseTokenChunk(chunk)) {
@@ -2074,6 +2343,12 @@ class WrappedResponses extends Responses {
                   if (!completionIdFromResponse && chunk.response.id) {
                     completionIdFromResponse = chunk.response.id;
                   }
+                  if (openAIParams.background === true && !this.backgroundResponses.get(chunk.response.id)) {
+                    this.backgroundResponses.set(chunk.response.id, {
+                      openAIParams,
+                      posthogParams
+                    });
+                  }
                   if (chunk.response.service_tier != null) {
                     serviceTierFromResponse = chunk.response.service_tier;
                   }
@@ -2081,10 +2356,9 @@ class WrappedResponses extends Responses {
                   if (chunkWebSearchCount > 0 && chunkWebSearchCount > (usage.webSearchCount ?? 0)) {
                     usage.webSearchCount = chunkWebSearchCount;
                   }
-                }
-                if (chunk.type === 'response.completed' && 'response' in chunk && chunk.response?.output && chunk.response.output.length > 0) {
-                  finalContent = chunk.response.output;
-                  if (chunk.response.status) {
+                  if (isTerminalResponse(chunk.response)) {
+                    terminalResponse = chunk.response;
+                    finalContent = chunk.response.output ?? [];
                     stopReason = chunk.response.status;
                   }
                 }
@@ -2099,6 +2373,15 @@ class WrappedResponses extends Responses {
                   };
                 }
               }
+              if (openAIParams.background === true) {
+                if (terminalResponse) {
+                  const context = this.backgroundResponses.take(terminalResponse.id);
+                  if (context) {
+                    await this.captureBackgroundResponse(terminalResponse, context).catch(() => undefined);
+                  }
+                }
+                return;
+              }
               const latency = (Date.now() - startTime) / 1000;
               const timeToFirstToken = firstTokenTime !== undefined ? (firstTokenTime - startTime) / 1000 : undefined;
               const availableTools = extractAvailableToolCalls('openai', openAIParams);
@@ -2107,7 +2390,7 @@ class WrappedResponses extends Responses {
                 model: openAIParams.model ?? modelFromResponse,
                 provider: 'openai',
                 input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
-                output: finalContent,
+                output: sanitizeOpenAIResponse(finalContent),
                 latency,
                 timeToFirstToken,
                 baseURL: this.baseURL,
@@ -2123,9 +2406,16 @@ class WrappedResponses extends Responses {
                 },
                 stopReason,
                 tools: availableTools,
-                completionId: completionIdFromResponse
+                completionId: completionIdFromResponse,
+                providerMetadata: buildProviderMetadata({
+                  incompleteDetails: terminalResponse?.incomplete_details
+                }),
+                error: getResponseFailure(terminalResponse)
               });
             } catch (error) {
+              if (openAIParams.background === true && completionIdFromResponse && this.backgroundResponses.get(completionIdFromResponse)) {
+                throw error;
+              }
               await captureAiGeneration(this.phClient, {
                 ...posthogParams,
                 model: openAIParams.model,
@@ -2159,6 +2449,10 @@ class WrappedResponses extends Responses {
       const wrappedPromise = parentPromise.then(async result => {
         if ('output' in result) {
           if (isPendingBackgroundResponse(openAIParams, result)) {
+            this.backgroundResponses.set(result.id, {
+              openAIParams,
+              posthogParams
+            });
             return result;
           }
           const latency = (Date.now() - startTime) / 1000;
@@ -2171,7 +2465,7 @@ class WrappedResponses extends Responses {
             model: openAIParams.model ?? result.model,
             provider: 'openai',
             input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
-            output: formattedOutput,
+            output: sanitizeOpenAIResponse(formattedOutput),
             latency,
             baseURL: this.baseURL,
             modelParameters: getModelParams(body, result.service_tier),
@@ -2188,8 +2482,10 @@ class WrappedResponses extends Responses {
             tools: availableTools,
             completionId: result.id,
             providerMetadata: buildProviderMetadata({
-              requestId: extractRequestId(result)
-            })
+              requestId: extractRequestId(result),
+              incompleteDetails: result.incomplete_details
+            }),
+            error: getResponseFailure(result)
           });
         }
         return result;
@@ -2216,6 +2512,55 @@ class WrappedResponses extends Responses {
       return preserveProviderPromise(parentPromise, wrappedPromise);
     }
   }
+  retrieve(responseID, query = {}, options) {
+    const parentPromise = super.retrieve(responseID, query, options);
+
+    // Preserve the upstream promise and stream unchanged for responses that
+    // were not created through this client.
+    if (!this.backgroundResponses.get(responseID)) {
+      return parentPromise;
+    }
+    if (query.stream) {
+      return parentPromise._thenUnwrap(result => {
+        if ('controller' in result) {
+          return wrapBackgroundResponseStream(result, responseID, this.backgroundResponses, (response, context) => this.captureBackgroundResponse(response, context));
+        }
+        return result;
+      });
+    }
+    return parentPromise._thenUnwrap(async result => {
+      if (!('output' in result) || !isTerminalResponse(result)) {
+        return result;
+      }
+
+      // Removing the context before capture makes concurrent or repeated
+      // terminal polls idempotent.
+      const context = this.backgroundResponses.take(responseID);
+      if (context) {
+        await this.captureBackgroundResponse(result, context).catch(() => undefined);
+      }
+      return result;
+    });
+  }
+  cancel(responseID, options) {
+    const parentPromise = super.cancel(responseID, options);
+
+    // Avoid wrapping calls that do not belong to a background response created
+    // through this client, preserving the upstream APIPromise unchanged.
+    if (!this.backgroundResponses.get(responseID)) {
+      return parentPromise;
+    }
+    return parentPromise._thenUnwrap(async result => {
+      if (!isTerminalResponse(result)) {
+        return result;
+      }
+      const context = this.backgroundResponses.take(responseID);
+      if (context) {
+        await this.captureBackgroundResponse(result, context).catch(() => undefined);
+      }
+      return result;
+    });
+  }
   parse(body, options) {
     const {
       providerParams: openAIParams,
@@ -2225,6 +2570,10 @@ class WrappedResponses extends Responses {
     const parentPromise = callWithOriginalCreate(this, super.create.bind(this), () => super.parse(openAIParams, options));
     const wrappedPromise = parentPromise.then(async result => {
       if (isPendingBackgroundResponse(openAIParams, result)) {
+        this.backgroundResponses.set(result.id, {
+          openAIParams,
+          posthogParams
+        });
         return result;
       }
       const latency = (Date.now() - startTime) / 1000;
@@ -2233,7 +2582,7 @@ class WrappedResponses extends Responses {
         model: openAIParams.model ?? result.model,
         provider: 'openai',
         input: formatOpenAIResponsesInput(sanitizeOpenAIResponse(openAIParams.input), openAIParams.instructions),
-        output: result.output,
+        output: sanitizeOpenAIResponse(result.output),
         latency,
         baseURL: this.baseURL,
         modelParameters: getModelParams(body, result.service_tier),
@@ -2248,8 +2597,10 @@ class WrappedResponses extends Responses {
         stopReason: result.status ?? undefined,
         completionId: result.id,
         providerMetadata: buildProviderMetadata({
-          requestId: extractRequestId(result)
-        })
+          requestId: extractRequestId(result),
+          incompleteDetails: result.incomplete_details
+        }),
+        error: getResponseFailure(result)
       });
       return result;
     }, async error => {
@@ -2402,7 +2753,7 @@ class WrappedTranscriptions extends Transcriptions {
                 model: openAIParams.model,
                 provider: 'openai',
                 input: openAIParams.prompt,
-                output: finalContent,
+                output: sanitizeOpenAIResponse(finalContent),
                 latency,
                 timeToFirstToken,
                 baseURL: this.baseURL,
@@ -2447,7 +2798,7 @@ class WrappedTranscriptions extends Transcriptions {
             model: openAIParams.model,
             provider: 'openai',
             input: openAIParams.prompt,
-            output: result.text,
+            output: sanitizeOpenAIResponse(result.text),
             latency,
             baseURL: this.baseURL,
             modelParameters: getModelParams(body),