weflayr 0.27.0 → 0.28.0

package/dist/src/instrumentation/openai/get_service_tier_telemetry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Service tier capture for the OpenAI chat and Responses paths.
+ *
+ * OpenLLMetry's Python instrumentor stamps the lane OpenAI served the call in
+ * (`service_tier`: "default", "flex", "priority", ...) as
+ * `openai.response.service_tier`; `@traceloop/instrumentation-openai` (Node)
+ * records nothing, so a flex or priority call would be priced at the standard
+ * rate. This stamps the same attribute, read off the complete response or off
+ * the streamed chunks (each one carries it), using the same `_endSpan` /
+ * `_streamingWrapPromise` hooks as `OpenAIReasoningContentInstrumentor`.
+ */
+export declare class OpenAIServiceTierInstrumentor {
+    private _patched;
+    instrument(instrumentation: any): void;
+    /** Remember the service tier the streamed chunks carry. */
+    private _patchStreamedServiceTier;
+    /** Stamp the service tier before the span ends. */
+    private _patchEndSpan;
+    uninstrument(): void;
+}

package/dist/src/instrumentation/openai/get_service_tier_telemetry.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Service tier capture for the OpenAI chat and Responses paths.
+ *
+ * OpenLLMetry's Python instrumentor stamps the lane OpenAI served the call in
+ * (`service_tier`: "default", "flex", "priority", ...) as
+ * `openai.response.service_tier`; `@traceloop/instrumentation-openai` (Node)
+ * records nothing, so a flex or priority call would be priced at the standard
+ * rate. This stamps the same attribute, read off the complete response or off
+ * the streamed chunks (each one carries it), using the same `_endSpan` /
+ * `_streamingWrapPromise` hooks as `OpenAIReasoningContentInstrumentor`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIServiceTierInstrumentor = void 0;
+const SERVICE_TIER_ATTR = 'openai.response.service_tier';
+// Service tier seen in the stream, per open span: chunks arrive while the
+// stream is consumed, and the span is ended once it is done.
+const _streamedServiceTierBySpan = new WeakMap();
+function _readServiceTier(responseOrChunk) {
+    const serviceTier = responseOrChunk?.service_tier;
+    return typeof serviceTier === 'string' && serviceTier ? serviceTier : undefined;
+}
+class OpenAIServiceTierInstrumentor {
+    // [owner, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    // No-op (and never throws) if the instrumentor's internals have changed shape:
+    // the worst case is a call priced at the standard rate, never a crash.
+    instrument(instrumentation) {
+        if (!instrumentation)
+            return;
+        this._patchStreamedServiceTier(instrumentation);
+        this._patchEndSpan(instrumentation);
+    }
+    /** Remember the service tier the streamed chunks carry. */
+    _patchStreamedServiceTier(instrumentation) {
+        const original = instrumentation._streamingWrapPromise;
+        if (typeof original !== 'function')
+            return;
+        instrumentation._streamingWrapPromise = function streamingWrapWithServiceTier(streamArgs) {
+            const span = streamArgs && streamArgs.span;
+            const wrappedStream = original.call(this, streamArgs);
+            if (!span)
+                return wrappedStream;
+            return (async function* recordServiceTier() {
+                for await (const chunk of wrappedStream) {
+                    const serviceTier = _readServiceTier(chunk);
+                    if (serviceTier)
+                        _streamedServiceTierBySpan.set(span, serviceTier);
+                    yield chunk;
+                }
+            })();
+        };
+        this._patched.push([instrumentation, '_streamingWrapPromise', original]);
+    }
+    /** Stamp the service tier before the span ends. */
+    _patchEndSpan(instrumentation) {
+        const original = instrumentation._endSpan;
+        if (typeof original !== 'function')
+            return;
+        instrumentation._endSpan = function endSpanWithServiceTier(args) {
+            const span = args && args.span;
+            if (span) {
+                try {
+                    const serviceTier = _readServiceTier(args.result) ?? _streamedServiceTierBySpan.get(span);
+                    if (serviceTier)
+                        span.setAttribute(SERVICE_TIER_ATTR, serviceTier);
+                }
+                catch {
+                    // Telemetry must never break the app's LLM call.
+                }
+                _streamedServiceTierBySpan.delete(span);
+            }
+            return original.call(this, args);
+        };
+        this._patched.push([instrumentation, '_endSpan', original]);
+    }
+    uninstrument() {
+        for (const [owner, methodName, original] of this._patched) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.OpenAIServiceTierInstrumentor = OpenAIServiceTierInstrumentor;

package/dist/src/instrumentation/openai/get_structured_output_schema_telemetry.d.ts

@@ -2,11 +2,13 @@
  * Structured-output schema location for OpenAI requests.
  *
  * OpenAI pins an answer to a JSON schema with
- * `response_format: { type: 'json_schema', json_schema: { schema } }`. The
- * traceloop instrumentor records the request's model and sampling params but
- * never the schema - which OpenAI bills as input.
+ * `response_format: { type: 'json_schema', json_schema: { schema } }` on the
+ * chat endpoint, and with `text: { format: { type: 'json_schema', schema } }` on
+ * the Responses one. The traceloop instrumentor records the request's model and
+ * sampling params but never the schema - which OpenAI bills as input.
  *
- * (The Python OpenLLMetry instrumentor stamps this one natively, so the Python
- * SDK has no OpenAI counterpart to this file - see known_divergences.md.)
+ * (The Python OpenLLMetry instrumentor stamps the chat endpoint's field
+ * natively, so the Python SDK reads only the Responses one, in
+ * `get_responses_telemetry.py` - see known_divergences.md.)
  */
 export declare function readStructuredOutputSchema(params: any): unknown;

package/dist/src/instrumentation/openai/get_structured_output_schema_telemetry.js

@@ -3,18 +3,25 @@
  * Structured-output schema location for OpenAI requests.
  *
  * OpenAI pins an answer to a JSON schema with
- * `response_format: { type: 'json_schema', json_schema: { schema } }`. The
- * traceloop instrumentor records the request's model and sampling params but
- * never the schema - which OpenAI bills as input.
+ * `response_format: { type: 'json_schema', json_schema: { schema } }` on the
+ * chat endpoint, and with `text: { format: { type: 'json_schema', schema } }` on
+ * the Responses one. The traceloop instrumentor records the request's model and
+ * sampling params but never the schema - which OpenAI bills as input.
  *
- * (The Python OpenLLMetry instrumentor stamps this one natively, so the Python
- * SDK has no OpenAI counterpart to this file - see known_divergences.md.)
+ * (The Python OpenLLMetry instrumentor stamps the chat endpoint's field
+ * natively, so the Python SDK reads only the Responses one, in
+ * `get_responses_telemetry.py` - see known_divergences.md.)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readStructuredOutputSchema = readStructuredOutputSchema;
 function readStructuredOutputSchema(params) {
     const responseFormat = params && params.response_format;
-    if (!responseFormat || responseFormat.type !== 'json_schema')
-        return undefined;
-    return responseFormat.json_schema && responseFormat.json_schema.schema;
+    if (responseFormat && responseFormat.type === 'json_schema') {
+        return responseFormat.json_schema && responseFormat.json_schema.schema;
+    }
+    const textFormat = params && params.text && params.text.format;
+    if (textFormat && textFormat.type === 'json_schema') {
+        return textFormat.schema;
+    }
+    return undefined;
 }

package/dist/src/instrumentation/openai/get_vertex_openai_compatible_telemetry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Billing attribution for the openai client pointed at Vertex AI's
+ * OpenAI-compatible endpoint.
+ *
+ * Vertex serves its partner models (Grok, DeepSeek, Llama...) on
+ * `.../endpoints/openapi/chat/completions`, which the stock openai client
+ * reaches with a Google access token as its API key. The traceloop
+ * instrumentor attributes those calls to "gcp.vertex_ai", which the worker
+ * parses as a Gemini payload, while the endpoint answers in OpenAI's shape and
+ * counts usage OpenAI's way. So the chat spans get `weflayr.billing_provider`
+ * set to `vertex`, which the worker prices by (Google bills them at Vertex's
+ * prices), and `gen_ai.provider.name`, which it parses by, set to "openai". The
+ * exception is Grok (models named `xai/...`): Vertex reports its reasoning
+ * tokens outside `completion_tokens`, as xAI does, so its spans are parsed as
+ * "spacexai".
+ *
+ * Only the chat path is patched: the endpoint serves no embedding model.
+ */
+export declare class VertexOpenAICompatibleInstrumentor {
+    private _patched;
+    instrument(instrumentation: any): void;
+    uninstrument(): void;
+}

package/dist/src/instrumentation/openai/get_vertex_openai_compatible_telemetry.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Billing attribution for the openai client pointed at Vertex AI's
+ * OpenAI-compatible endpoint.
+ *
+ * Vertex serves its partner models (Grok, DeepSeek, Llama...) on
+ * `.../endpoints/openapi/chat/completions`, which the stock openai client
+ * reaches with a Google access token as its API key. The traceloop
+ * instrumentor attributes those calls to "gcp.vertex_ai", which the worker
+ * parses as a Gemini payload, while the endpoint answers in OpenAI's shape and
+ * counts usage OpenAI's way. So the chat spans get `weflayr.billing_provider`
+ * set to `vertex`, which the worker prices by (Google bills them at Vertex's
+ * prices), and `gen_ai.provider.name`, which it parses by, set to "openai". The
+ * exception is Grok (models named `xai/...`): Vertex reports its reasoning
+ * tokens outside `completion_tokens`, as xAI does, so its spans are parsed as
+ * "spacexai".
+ *
+ * Only the chat path is patched: the endpoint serves no embedding model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VertexOpenAICompatibleInstrumentor = void 0;
+const is_vertex_base_url_1 = require("../shared/is_vertex_base_url");
+const get_openai_compatible_provider_telemetry_1 = require("./get_openai_compatible_provider_telemetry");
+// traceloop's internal tag for a chat request, the value it passes to `startSpan`.
+const CHAT_TYPE = 'chat';
+const PROVIDER_ATTR = 'gen_ai.provider.name';
+// The prefix Vertex names Grok models with on this endpoint, e.g. "xai/grok-4.6".
+const XAI_MODEL_PREFIX = 'xai/';
+const SPACEXAI_PROVIDER = 'spacexai';
+const OPENAI_PROVIDER = 'openai';
+class VertexOpenAICompatibleInstrumentor {
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    instrument(instrumentation) {
+        if (!instrumentation)
+            return;
+        const original = instrumentation.startSpan;
+        if (typeof original !== 'function') {
+            throw new Error('weflayr: @traceloop/instrumentation-openai no longer defines startSpan, so chat ' +
+                "calls made to Vertex's OpenAI-compatible endpoint cannot be billed to Vertex.");
+        }
+        instrumentation.startSpan = function startSpanBilledToVertex(args) {
+            const span = original.call(this, args);
+            try {
+                if (args?.type === CHAT_TYPE &&
+                    span?.isRecording?.() &&
+                    (0, is_vertex_base_url_1.isVertexBaseURL)((0, get_openai_compatible_provider_telemetry_1.resolveClient)(args.client)?.baseURL)) {
+                    span.setAttribute(is_vertex_base_url_1.BILLING_PROVIDER_ATTR, is_vertex_base_url_1.VERTEX_BILLING_PROVIDER);
+                    const isGrok = String(args.params?.model ?? '').startsWith(XAI_MODEL_PREFIX);
+                    span.setAttribute(PROVIDER_ATTR, isGrok ? SPACEXAI_PROVIDER : OPENAI_PROVIDER);
+                }
+            }
+            catch {
+                // Never break span creation over an enrichment failure.
+            }
+            return span;
+        };
+        this._patched.push([instrumentation, 'startSpan', original]);
+    }
+    uninstrument() {
+        // Restore newest first, so a double instrument() unwinds back to the true
+        // original instead of reinstalling the first wrapper.
+        for (const [owner, methodName, original] of [...this._patched].reverse()) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.VertexOpenAICompatibleInstrumentor = VertexOpenAICompatibleInstrumentor;

package/dist/src/instrumentation/openai/get_web_search_telemetry.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Provider-run web search capture for OpenAI chat spans.
+ *
+ * OpenAI runs the search itself when the request carries `web_search_options`,
+ * and bills the call once whatever number of searches it ran. Unlike every other
+ * provider it is not a `tools` entry but a request parameter of its own, and the
+ * answer reports the pages it read as `url_citation` annotations on the message
+ * rather than as content blocks. The traceloop instrumentor records neither, so
+ * a searching call reaches the span as an ordinary one.
+ *
+ * Both are stamped under `weflayr.web_search.*`, in OpenAI's own vocabulary;
+ * `normalizers/openai.py` maps them to the shape every provider's web search is
+ * stored in.
+ *
+ * OpenAI reports no query and no count: it says which pages were cited, never
+ * what was typed into the search, and its usage carries no search total. So the
+ * stored count is 1 as soon as the answer cites a page, and 0 when a request
+ * that allowed searching did not produce one, which is also how OpenAI bills
+ * it, per call that used the tool rather than per search.
+ *
+ * Over a stream the annotations arrive on the deltas, so they are gathered per
+ * span as the chunks pass and stamped once the stream ends.
+ *
+ * The `/v1/responses` endpoint reports the same search in three other places,
+ * which `get_responses_telemetry.ts` stamps by calling the helpers exported
+ * here: the request enables it with a `{type: "web_search"}` entry in `tools`
+ * like every other provider, the answer carries one `web_search_call` output
+ * item per search, naming the query OpenAI never reports on chat completions,
+ * and `tool_usage.web_search.num_requests` gives the number of searches the
+ * call is billed for instead of leaving it to be assumed.
+ */
+/** The pages an answer cited, from every choice's annotations. The
+ * `{type, url_citation}` wrapper is dropped and the citation itself kept, since
+ * nothing else is annotated this way today. */
+export declare function extractUrlCitations(choices: any): any[];
+/** The `web_search_call` items of a `/v1/responses` answer, one per search the
+ * model ran, kept as OpenAI wrote them: `normalizers/openai.py` reads the id and
+ * the query off each. */
+export declare function extractResponsesSearchItems(outputItems: any): any[];
+/** The pages a `/v1/responses` answer cited, from the `url_citation` annotations
+ * of its message items' content blocks. The endpoint spells one citation flat
+ * (`{type: "url_citation", url, title}`) where chat completions nest it under
+ * its own type, so the annotation itself is kept and both endpoints stamp the
+ * same `{url, title, ...}` shape. */
+export declare function extractResponsesCitations(outputItems: any): any[];
+/** How many searches a `/v1/responses` answer is billed for, from OpenAI's
+ * `tool_usage.web_search.num_requests` or xAI's
+ * `usage.server_side_tool_usage_details.web_search_calls`, or null when the
+ * response reports neither (an answer that ran no search, or an older API
+ * version). Unlike chat completions, which report no count at all, this is the
+ * provider's own number, so it is stored rather than assumed. */
+export declare function readBilledSearchCount(response: any): number | null;
+/** Stamp the knobs the request's `web_search` tool entry was given. On this
+ * endpoint the search is a tool like every other provider's, so the entry's own
+ * type is dropped and only its knobs stamped, which is the shape the chat
+ * endpoint's `web_search_options` already has. */
+export declare function setResponsesWebSearchRequestAttributes(span: any, params: any): void;
+/** Stamp the searches a `/v1/responses` answer ran, the pages it cited and the
+ * number of searches it is billed for. */
+export declare function setResponsesWebSearchAnswerAttributes(span: any, response: any): void;
+export declare class OpenAIWebSearchInstrumentor {
+    private _patched;
+    instrument(instrumentation: any): void;
+    /** Stamp `web_search_options` as sent. An empty object still stamps something:
+     * it says the request allowed searching, which is what the stored tool
+     * definition records. */
+    private _patchRequestOptions;
+    /** Gather `delta.annotations` across the streamed chunks. */
+    private _patchStreamedCitations;
+    /** Stamp the citations as the span is finalized, from the answer itself on a
+     * plain call and from the gathered deltas on a streamed one. */
+    private _patchResponseCitations;
+    uninstrument(): void;
+}

package/dist/src/instrumentation/openai/get_web_search_telemetry.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * Provider-run web search capture for OpenAI chat spans.
+ *
+ * OpenAI runs the search itself when the request carries `web_search_options`,
+ * and bills the call once whatever number of searches it ran. Unlike every other
+ * provider it is not a `tools` entry but a request parameter of its own, and the
+ * answer reports the pages it read as `url_citation` annotations on the message
+ * rather than as content blocks. The traceloop instrumentor records neither, so
+ * a searching call reaches the span as an ordinary one.
+ *
+ * Both are stamped under `weflayr.web_search.*`, in OpenAI's own vocabulary;
+ * `normalizers/openai.py` maps them to the shape every provider's web search is
+ * stored in.
+ *
+ * OpenAI reports no query and no count: it says which pages were cited, never
+ * what was typed into the search, and its usage carries no search total. So the
+ * stored count is 1 as soon as the answer cites a page, and 0 when a request
+ * that allowed searching did not produce one, which is also how OpenAI bills
+ * it, per call that used the tool rather than per search.
+ *
+ * Over a stream the annotations arrive on the deltas, so they are gathered per
+ * span as the chunks pass and stamped once the stream ends.
+ *
+ * The `/v1/responses` endpoint reports the same search in three other places,
+ * which `get_responses_telemetry.ts` stamps by calling the helpers exported
+ * here: the request enables it with a `{type: "web_search"}` entry in `tools`
+ * like every other provider, the answer carries one `web_search_call` output
+ * item per search, naming the query OpenAI never reports on chat completions,
+ * and `tool_usage.web_search.num_requests` gives the number of searches the
+ * call is billed for instead of leaving it to be assumed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIWebSearchInstrumentor = void 0;
+exports.extractUrlCitations = extractUrlCitations;
+exports.extractResponsesSearchItems = extractResponsesSearchItems;
+exports.extractResponsesCitations = extractResponsesCitations;
+exports.readBilledSearchCount = readBilledSearchCount;
+exports.setResponsesWebSearchRequestAttributes = setResponsesWebSearchRequestAttributes;
+exports.setResponsesWebSearchAnswerAttributes = setResponsesWebSearchAnswerAttributes;
+const OPTIONS_ATTR = 'weflayr.web_search.options';
+const CITATIONS_ATTR = 'weflayr.web_search.citations';
+const REQUESTS_ATTR = 'weflayr.web_search.requests';
+// The searches an answer ran, reported by /v1/responses only.
+const OUTPUT_BLOCKS_ATTR = 'weflayr.web_search.output_blocks';
+// The request parameter that lets the model search, and the annotation type the
+// answer cites a page with.
+const WEB_SEARCH_OPTIONS_PARAM = 'web_search_options';
+const URL_CITATION_ANNOTATION_TYPE = 'url_citation';
+// How /v1/responses spells the same three things: the tool the request enables,
+// the output item one search becomes, and the message item carrying the
+// answer's citations.
+const WEB_SEARCH_TOOL_TYPE = 'web_search';
+const WEB_SEARCH_CALL_ITEM_TYPE = 'web_search_call';
+const MESSAGE_ITEM_TYPE = 'message';
+// Citations gathered from a stream's deltas, keyed by the span they belong to,
+// so concurrent streams never mix. Weak so an ended span is collectable.
+const _streamedCitationsBySpan = new WeakMap();
+/** The pages an answer cited, from every choice's annotations. The
+ * `{type, url_citation}` wrapper is dropped and the citation itself kept, since
+ * nothing else is annotated this way today. */
+function extractUrlCitations(choices) {
+    if (!Array.isArray(choices))
+        return [];
+    const citations = [];
+    for (const choice of choices) {
+        for (const annotation of choice?.message?.annotations || []) {
+            if (annotation && annotation.type === URL_CITATION_ANNOTATION_TYPE) {
+                const citation = annotation[URL_CITATION_ANNOTATION_TYPE];
+                if (citation)
+                    citations.push(citation);
+            }
+        }
+    }
+    return citations;
+}
+/** Stamp the pages the answer cited, and that the call is billed for one search.
+ * A request that allowed searching but cited nothing stamps neither: OpenAI
+ * bills the call that used the tool, not the one that could have. */
+function setCitations(span, citations) {
+    if (!span || !span.isRecording || !span.isRecording() || !citations.length)
+        return;
+    span.setAttribute(CITATIONS_ATTR, JSON.stringify(citations));
+    span.setAttribute(REQUESTS_ATTR, 1);
+}
+/** The `web_search_call` items of a `/v1/responses` answer, one per search the
+ * model ran, kept as OpenAI wrote them: `normalizers/openai.py` reads the id and
+ * the query off each. */
+function extractResponsesSearchItems(outputItems) {
+    if (!Array.isArray(outputItems))
+        return [];
+    return outputItems.filter((item) => item && typeof item === 'object' && item.type === WEB_SEARCH_CALL_ITEM_TYPE);
+}
+/** The pages a `/v1/responses` answer cited, from the `url_citation` annotations
+ * of its message items' content blocks. The endpoint spells one citation flat
+ * (`{type: "url_citation", url, title}`) where chat completions nest it under
+ * its own type, so the annotation itself is kept and both endpoints stamp the
+ * same `{url, title, ...}` shape. */
+function extractResponsesCitations(outputItems) {
+    if (!Array.isArray(outputItems))
+        return [];
+    const citations = [];
+    for (const item of outputItems) {
+        if (!item || typeof item !== 'object' || item.type !== MESSAGE_ITEM_TYPE)
+            continue;
+        for (const block of Array.isArray(item.content) ? item.content : []) {
+            for (const annotation of Array.isArray(block?.annotations) ? block.annotations : []) {
+                if (annotation && annotation.type === URL_CITATION_ANNOTATION_TYPE) {
+                    citations.push(annotation);
+                }
+            }
+        }
+    }
+    return citations;
+}
+/** How many searches a `/v1/responses` answer is billed for, from OpenAI's
+ * `tool_usage.web_search.num_requests` or xAI's
+ * `usage.server_side_tool_usage_details.web_search_calls`, or null when the
+ * response reports neither (an answer that ran no search, or an older API
+ * version). Unlike chat completions, which report no count at all, this is the
+ * provider's own number, so it is stored rather than assumed. */
+function readBilledSearchCount(response) {
+    const numRequests = response?.tool_usage?.[WEB_SEARCH_TOOL_TYPE]?.num_requests;
+    if (typeof numRequests === 'number')
+        return numRequests;
+    const webSearchCalls = response?.usage?.server_side_tool_usage_details?.web_search_calls;
+    return typeof webSearchCalls === 'number' ? webSearchCalls : null;
+}
+/** Stamp the knobs the request's `web_search` tool entry was given. On this
+ * endpoint the search is a tool like every other provider's, so the entry's own
+ * type is dropped and only its knobs stamped, which is the shape the chat
+ * endpoint's `web_search_options` already has. */
+function setResponsesWebSearchRequestAttributes(span, params) {
+    if (!span || !span.isRecording || !span.isRecording())
+        return;
+    for (const tool of Array.isArray(params?.tools) ? params.tools : []) {
+        if (tool && typeof tool === 'object' && tool.type === WEB_SEARCH_TOOL_TYPE) {
+            const options = Object.fromEntries(Object.entries(tool).filter(([name]) => name !== 'type'));
+            span.setAttribute(OPTIONS_ATTR, JSON.stringify(options));
+            return;
+        }
+    }
+}
+/** Stamp the searches a `/v1/responses` answer ran, the pages it cited and the
+ * number of searches it is billed for. */
+function setResponsesWebSearchAnswerAttributes(span, response) {
+    if (!span || !span.isRecording || !span.isRecording())
+        return;
+    const searches = extractResponsesSearchItems(response?.output);
+    if (searches.length)
+        span.setAttribute(OUTPUT_BLOCKS_ATTR, JSON.stringify(searches));
+    const citations = extractResponsesCitations(response?.output);
+    if (citations.length)
+        span.setAttribute(CITATIONS_ATTR, JSON.stringify(citations));
+    const billedSearchCount = readBilledSearchCount(response);
+    if (billedSearchCount)
+        span.setAttribute(REQUESTS_ATTR, billedSearchCount);
+}
+class OpenAIWebSearchInstrumentor {
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    // No-op (and never throws) if the instrumentor's internals have changed shape:
+    // the worst case is a missing web search, never a crash.
+    instrument(instrumentation) {
+        if (!instrumentation)
+            return;
+        this._patchRequestOptions(instrumentation);
+        this._patchStreamedCitations(instrumentation);
+        this._patchResponseCitations(instrumentation);
+    }
+    /** Stamp `web_search_options` as sent. An empty object still stamps something:
+     * it says the request allowed searching, which is what the stored tool
+     * definition records. */
+    _patchRequestOptions(instrumentation) {
+        const original = instrumentation.startSpan;
+        if (typeof original !== 'function')
+            return;
+        instrumentation.startSpan = function startSpanWithWebSearchOptions(request) {
+            const span = original.call(this, request);
+            try {
+                const options = request?.params?.[WEB_SEARCH_OPTIONS_PARAM];
+                if (options !== undefined && options !== null) {
+                    span.setAttribute(OPTIONS_ATTR, JSON.stringify(typeof options === 'object' ? options : {}));
+                }
+            }
+            catch {
+                // Never break span creation over an enrichment failure.
+            }
+            return span;
+        };
+        this._patched.push([instrumentation, 'startSpan', original]);
+    }
+    /** Gather `delta.annotations` across the streamed chunks. */
+    _patchStreamedCitations(instrumentation) {
+        const original = instrumentation._streamingWrapPromise;
+        if (typeof original !== 'function')
+            return;
+        instrumentation._streamingWrapPromise = function streamingWrapWithCitations(streamArgs) {
+            const span = streamArgs && streamArgs.span;
+            const wrappedStream = original.call(this, streamArgs);
+            if (!span)
+                return wrappedStream;
+            return (async function* accumulateCitations() {
+                for await (const chunk of wrappedStream) {
+                    try {
+                        for (const choice of chunk?.choices || []) {
+                            for (const annotation of choice?.delta?.annotations || []) {
+                                if (annotation && annotation.type === URL_CITATION_ANNOTATION_TYPE) {
+                                    const citation = annotation[URL_CITATION_ANNOTATION_TYPE];
+                                    if (citation) {
+                                        _streamedCitationsBySpan.set(span, [
+                                            ...(_streamedCitationsBySpan.get(span) ?? []),
+                                            citation,
+                                        ]);
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // Never break the caller's stream over an enrichment failure.
+                    }
+                    yield chunk;
+                }
+            })();
+        };
+        this._patched.push([instrumentation, '_streamingWrapPromise', original]);
+    }
+    /** Stamp the citations as the span is finalized, from the answer itself on a
+     * plain call and from the gathered deltas on a streamed one. */
+    _patchResponseCitations(instrumentation) {
+        const original = instrumentation._endSpan;
+        if (typeof original !== 'function')
+            return;
+        instrumentation._endSpan = function endSpanWithCitations(args) {
+            try {
+                const span = args && args.span;
+                const streamed = span && _streamedCitationsBySpan.get(span);
+                setCitations(span, streamed ?? extractUrlCitations(args?.result?.choices));
+                if (span)
+                    _streamedCitationsBySpan.delete(span);
+            }
+            catch {
+                // Never break span finalization over an enrichment failure.
+            }
+            return original.call(this, args);
+        };
+        this._patched.push([instrumentation, '_endSpan', original]);
+    }
+    uninstrument() {
+        // Restore newest first, so a double instrument() unwinds back to the true
+        // original instead of reinstalling the first wrapper.
+        for (const [owner, methodName, original] of [...this._patched].reverse()) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.OpenAIWebSearchInstrumentor = OpenAIWebSearchInstrumentor;

package/dist/src/instrumentation/openai/set_telemetry_attributes.d.ts

@@ -7,7 +7,19 @@
  *     non-streamed cached-prompt tokens (these enrich the traceloop instrumentor
  *     instance, hence the `instrumentation` argument), and
  *   - the request's structured-output schema, and
- *   - Bedrock Mantle's provider attribution and reasoning output.
+ *   - the Responses endpoint, which it wraps but records far less of than the
+ *     Python instrumentor does (and not at all when streamed), and
+ *   - Bedrock Mantle's provider attribution and reasoning output, and
+ *   - the provider-run web search (`web_search_options` and the answer's
+ *     `url_citation` annotations), and
+ *   - the mime type of an inline file (PDF, ...), which it reads from a
+ *     field OpenAI's API does not have and so always records as
+ *     application/octet-stream, and
+ *   - the provider attribution of the vendors served over an
+ *     OpenAI-compatible API (Alibaba Model Studio, xAI), and
+ *   - the billing of the calls to Vertex AI's OpenAI-compatible endpoint, and
+ *   - a `reasoning_content` output part for any provider that returns one, and
+ *   - the service tier the call was served in (flex, priority, ...).
  */
 export declare class OpenAITelemetryInstrumentor {
     private _subInstrumentors;