weflayr 0.23.0 → 0.26.0

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

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Request-side prompt-caching config capture for OpenAI chat spans.
+ *
+ * OpenAI callers influence the (automatic, server-side) prompt cache with
+ * request parameters the traceloop instrumentor never records:
+ * `prompt_cache_key` (a client-chosen routing key — requests sharing a key are
+ * routed to the same cache shard), the retention tuning —
+ * `prompt_cache_retention` ("in_memory" / "24h") on older models, replaced by
+ * `prompt_cache_options: { ttl }` ("30m") on GPT-5.6+ — and, also on GPT-5.6+,
+ * explicit breakpoint placement: a `prompt_cache_breakpoint` marker on a
+ * message content block (`prompt_cache_options: { mode: "explicit" }`
+ * disables the automatic breakpoint, requiring these to cache anything).
+ *
+ * Wrap `startSpan({ type, params })` (covering the streamed and non-streamed
+ * paths) to stamp the values as `weflayr.cache.key` / `weflayr.cache.retention`
+ * (raw retention/ttl string) and, when any content block carries the marker,
+ * `weflayr.cache.breakpoints` (a JSON list of `{"location": "messages[i]"}`
+ * entries — the marker itself carries no TTL, unlike Anthropic's
+ * `cache_control`; the normalizer owns the vocabulary).
+ * `prompt_cache_options: { mode: "explicit" }` is stamped as
+ * `weflayr.cache.mode` so the normalizer knows not to also synthesize the
+ * automatic "auto"-location breakpoint OpenAI does not create in this mode.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAICacheConfigInstrumentor = void 0;
+const CACHE_KEY_ATTR = 'weflayr.cache.key';
+const CACHE_RETENTION_ATTR = 'weflayr.cache.retention';
+const CACHE_MODE_ATTR = 'weflayr.cache.mode';
+const BREAKPOINTS_ATTR = 'weflayr.cache.breakpoints';
+function explicitBreakpoints(params) {
+    const breakpoints = [];
+    const messages = (params && params.messages) || [];
+    messages.forEach((message, index) => {
+        const content = message && message.content;
+        if (!Array.isArray(content))
+            return;
+        for (const block of content) {
+            if (block && typeof block === 'object' && 'prompt_cache_breakpoint' in block) {
+                breakpoints.push({ location: `messages[${index}]` });
+            }
+        }
+    });
+    return breakpoints;
+}
+class OpenAICacheConfigInstrumentor {
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    // No-op (and never throws) if the instrumentor's internals have changed shape —
+    // the worst case is missing cache-config capture, never a crash.
+    instrument(instrumentation) {
+        if (!instrumentation)
+            return;
+        const startSpanOriginal = instrumentation.startSpan;
+        if (typeof startSpanOriginal !== 'function')
+            return;
+        instrumentation.startSpan = function startSpanWithCacheConfig(request) {
+            const span = startSpanOriginal.call(this, request);
+            try {
+                const params = (request && request.params) || {};
+                if (params.prompt_cache_key) {
+                    span.setAttribute(CACHE_KEY_ATTR, String(params.prompt_cache_key));
+                }
+                const retention = params.prompt_cache_retention ||
+                    (params.prompt_cache_options && params.prompt_cache_options.ttl);
+                if (retention) {
+                    span.setAttribute(CACHE_RETENTION_ATTR, String(retention));
+                }
+                if (params.prompt_cache_options && params.prompt_cache_options.mode === 'explicit') {
+                    span.setAttribute(CACHE_MODE_ATTR, 'explicit');
+                }
+                const breakpoints = explicitBreakpoints(params);
+                if (breakpoints.length) {
+                    span.setAttribute(BREAKPOINTS_ATTR, JSON.stringify(breakpoints));
+                }
+            }
+            catch {
+                // Never break span creation over an enrichment failure.
+            }
+            return span;
+        };
+        this._patched.push([instrumentation, 'startSpan', startSpanOriginal]);
+    }
+    uninstrument() {
+        for (const [owner, methodName, original] of this._patched) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.OpenAICacheConfigInstrumentor = OpenAICacheConfigInstrumentor;

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

@@ -0,0 +1,18 @@
+/**
+ * Hand-written OTel instrumentor for the OpenAI embeddings endpoint.
+ *
+ * `@traceloop/instrumentation-openai` (the package weflayr uses for OpenAI on
+ * Node) does not wrap the embeddings endpoint, so this ships inside weflayr to
+ * cover it. The Python SDK gets embeddings for free from OpenLLMetry's
+ * instrumentor, so there is no Python counterpart to this file — but the span it
+ * emits is shaped to normalize identically. It is registered alongside the
+ * traceloop instrumentor whenever `autoInstrument({ aiSdks: 'openai' })` runs.
+ *
+ * Embeddings are billed per input token, so the span records the prompt tokens
+ * read off the response under `gen_ai.usage.input_tokens`; there is no completion.
+ */
+export declare class OpenAIEmbeddingsInstrumentor {
+    private _patched;
+    instrument(): void;
+    uninstrument(): void;
+}

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

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Hand-written OTel instrumentor for the OpenAI embeddings endpoint.
+ *
+ * `@traceloop/instrumentation-openai` (the package weflayr uses for OpenAI on
+ * Node) does not wrap the embeddings endpoint, so this ships inside weflayr to
+ * cover it. The Python SDK gets embeddings for free from OpenLLMetry's
+ * instrumentor, so there is no Python counterpart to this file — but the span it
+ * emits is shaped to normalize identically. It is registered alongside the
+ * traceloop instrumentor whenever `autoInstrument({ aiSdks: 'openai' })` runs.
+ *
+ * Embeddings are billed per input token, so the span records the prompt tokens
+ * read off the response under `gen_ai.usage.input_tokens`; there is no completion.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIEmbeddingsInstrumentor = void 0;
+const api_1 = require("@opentelemetry/api");
+const TRACER_NAME = 'weflayr.instrumentation.openai_embeddings';
+const EMBEDDINGS_OPERATION = 'embeddings';
+// Return the gen_ai.system for this call, matching how the OpenAI chat
+// instrumentor attributes the vendor: Azure clients (reached via the same openai
+// SDK) report `azure.ai.openai`, everything else `openai`.
+function _detectSystem(instance) {
+    const baseURL = (instance && instance._client && instance._client.baseURL) || '';
+    return baseURL.toLowerCase().includes('openai.azure.com') ? 'azure.ai.openai' : 'openai';
+}
+function _recordError(span, error) {
+    span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error?.message ?? String(error) });
+    span.recordException(error);
+}
+class OpenAIEmbeddingsInstrumentor {
+    // [ownerPrototype, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    instrument() {
+        let Embeddings;
+        try {
+            ({ Embeddings } = require('openai/resources/embeddings'));
+        }
+        catch (err) {
+            throw new Error('weflayr.autoInstrument(OPENAI): the openai client is not installed. ' +
+                'Install it with: npm install openai\n' +
+                `Underlying error: ${err.message}`);
+        }
+        const owner = Embeddings.prototype;
+        const original = owner.create;
+        function wrapper(body, ...rest) {
+            const span = api_1.trace.getTracer(TRACER_NAME).startSpan(EMBEDDINGS_OPERATION);
+            span.setAttribute('gen_ai.system', _detectSystem(this));
+            span.setAttribute('gen_ai.operation.name', EMBEDDINGS_OPERATION);
+            if (body && body.model) {
+                span.setAttribute('gen_ai.request.model', body.model);
+            }
+            // One user message per input element, matching the shape the chat
+            // instrumentors emit. The span processor strips it when message-content
+            // capture is disabled.
+            if (body && body.input != null) {
+                const inputs = Array.isArray(body.input) ? body.input : [body.input];
+                span.setAttribute('gen_ai.input.messages', JSON.stringify(inputs.map((content) => ({ role: 'user', parts: [{ type: 'text', content }] }))));
+            }
+            return Promise.resolve(original.call(this, body, ...rest)).then((response) => {
+                if (response && response.model) {
+                    span.setAttribute('gen_ai.response.model', response.model);
+                }
+                const promptTokens = response && response.usage && response.usage.prompt_tokens;
+                if (promptTokens != null) {
+                    span.setAttribute('gen_ai.usage.input_tokens', promptTokens);
+                }
+                span.end();
+                return response;
+            }, (error) => {
+                _recordError(span, error);
+                span.end();
+                throw error;
+            });
+        }
+        owner.create = wrapper;
+        this._patched.push([owner, 'create', original]);
+    }
+    uninstrument() {
+        for (const [owner, methodName, original] of this._patched) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.OpenAIEmbeddingsInstrumentor = OpenAIEmbeddingsInstrumentor;

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

@@ -0,0 +1,21 @@
+/**
+ * Streamed token-usage enrichment complement for the OpenAI chat path.
+ *
+ * `@traceloop/instrumentation-openai` does not record token usage for streamed
+ * calls: its stream handler accumulates `choices[].delta` but never reads the
+ * final usage chunk OpenAI sends when the request sets
+ * `stream_options: { include_usage: true }`. Non-streaming calls work because
+ * OpenAI returns `usage` in the response body, which the instrumentor reads
+ * directly. The Python OpenLLMetry instrumentor reads the streamed usage, so
+ * this gap is Node-only.
+ *
+ * It wraps the instrumentor instance's `_streamingWrapPromise`: that handler
+ * hands us the span and ends it only after its chunk loop, so when the usage
+ * chunk arrives the span is still open and we set the same `gen_ai.usage.*`
+ * attributes the instrumentor sets for non-streaming calls.
+ */
+export declare class OpenAIStreamingUsageInstrumentor {
+    private _patched;
+    instrument(instrumentation: any): void;
+    uninstrument(): void;
+}

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

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Streamed token-usage enrichment complement for the OpenAI chat path.
+ *
+ * `@traceloop/instrumentation-openai` does not record token usage for streamed
+ * calls: its stream handler accumulates `choices[].delta` but never reads the
+ * final usage chunk OpenAI sends when the request sets
+ * `stream_options: { include_usage: true }`. Non-streaming calls work because
+ * OpenAI returns `usage` in the response body, which the instrumentor reads
+ * directly. The Python OpenLLMetry instrumentor reads the streamed usage, so
+ * this gap is Node-only.
+ *
+ * It wraps the instrumentor instance's `_streamingWrapPromise`: that handler
+ * hands us the span and ends it only after its chunk loop, so when the usage
+ * chunk arrives the span is still open and we set the same `gen_ai.usage.*`
+ * attributes the instrumentor sets for non-streaming calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIStreamingUsageInstrumentor = void 0;
+const USAGE_INPUT_TOKENS_ATTR = 'gen_ai.usage.input_tokens';
+const USAGE_OUTPUT_TOKENS_ATTR = 'gen_ai.usage.output_tokens';
+const USAGE_TOTAL_TOKENS_ATTR = 'gen_ai.usage.total_tokens';
+const CACHE_READ_INPUT_TOKENS_ATTR = 'gen_ai.usage.cache_read_input_tokens';
+function _setUsageAttributes(span, usage) {
+    if (typeof usage.prompt_tokens === 'number') {
+        span.setAttribute(USAGE_INPUT_TOKENS_ATTR, usage.prompt_tokens);
+    }
+    if (typeof usage.completion_tokens === 'number') {
+        span.setAttribute(USAGE_OUTPUT_TOKENS_ATTR, usage.completion_tokens);
+    }
+    if (typeof usage.total_tokens === 'number') {
+        span.setAttribute(USAGE_TOTAL_TOKENS_ATTR, usage.total_tokens);
+    }
+    // Cached-prompt tokens ride in the same streamed usage chunk; mirror the
+    // non-streamed cache backfill in get_cache_and_reasoning_telemetry.js.
+    const cachedTokens = usage.prompt_tokens_details && usage.prompt_tokens_details.cached_tokens;
+    if (cachedTokens) {
+        span.setAttribute(CACHE_READ_INPUT_TOKENS_ATTR, cachedTokens);
+    }
+}
+class OpenAIStreamingUsageInstrumentor {
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    // No-op if the instrumentor's internals have changed shape — the worst case is
+    // streamed spans without token counts, never a crash.
+    instrument(instrumentation) {
+        const original = instrumentation && instrumentation._streamingWrapPromise;
+        if (typeof original !== 'function')
+            return;
+        instrumentation._streamingWrapPromise = function streamingWrapWithUsage(streamArgs) {
+            const span = streamArgs && streamArgs.span;
+            const wrappedStream = original.call(this, streamArgs);
+            if (!span)
+                return wrappedStream;
+            return (async function* backfillUsage() {
+                for await (const chunk of wrappedStream) {
+                    const usage = chunk && chunk.usage;
+                    if (usage && span.isRecording()) {
+                        _setUsageAttributes(span, usage);
+                    }
+                    yield chunk;
+                }
+            })();
+        };
+        this._patched.push([instrumentation, '_streamingWrapPromise', original]);
+    }
+    uninstrument() {
+        for (const [owner, methodName, original] of this._patched) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.OpenAIStreamingUsageInstrumentor = OpenAIStreamingUsageInstrumentor;

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ *
+ * (The Python OpenLLMetry instrumentor stamps this one natively, so the Python
+ * SDK has no OpenAI counterpart to this file - see known_divergences.md.)
+ */
+export declare function readStructuredOutputSchema(params: any): unknown;

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

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * 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.
+ *
+ * (The Python OpenLLMetry instrumentor stamps this one natively, so the Python
+ * SDK has no OpenAI counterpart to this file - 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;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * OpenAI telemetry complement — the registered orchestrator.
+ *
+ * Wires every weflayr-supplied patch the traceloop OpenAI instrumentor misses:
+ *   - the audio (TTS/STT) and embeddings endpoints it doesn't cover, and
+ *   - usage it drops on the chat endpoint it does cover: streamed token usage and
+ *     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.
+ */
+export declare class OpenAITelemetryInstrumentor {
+    private _subInstrumentors;
+    constructor();
+    instrument(instrumentation: any): void;
+    uninstrument(): void;
+}

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

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * OpenAI telemetry complement — the registered orchestrator.
+ *
+ * Wires every weflayr-supplied patch the traceloop OpenAI instrumentor misses:
+ *   - the audio (TTS/STT) and embeddings endpoints it doesn't cover, and
+ *   - usage it drops on the chat endpoint it does cover: streamed token usage and
+ *     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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAITelemetryInstrumentor = void 0;
+const get_structured_output_schema_telemetry_1 = require("../shared/get_structured_output_schema_telemetry");
+const get_audio_telemetry_1 = require("./get_audio_telemetry");
+const get_bedrock_mantle_telemetry_1 = require("./get_bedrock_mantle_telemetry");
+const get_cache_config_telemetry_1 = require("./get_cache_config_telemetry");
+const get_embeddings_telemetry_1 = require("./get_embeddings_telemetry");
+const get_streaming_usage_1 = require("./get_streaming_usage");
+const get_cache_and_reasoning_telemetry_1 = require("./get_cache_and_reasoning_telemetry");
+const get_structured_output_schema_telemetry_2 = require("./get_structured_output_schema_telemetry");
+class OpenAITelemetryInstrumentor {
+    _subInstrumentors;
+    constructor() {
+        this._subInstrumentors = [
+            new get_audio_telemetry_1.OpenAIAudioInstrumentor(),
+            new get_embeddings_telemetry_1.OpenAIEmbeddingsInstrumentor(),
+            new get_streaming_usage_1.OpenAIStreamingUsageInstrumentor(),
+            new get_cache_and_reasoning_telemetry_1.OpenAIPromptCachingInstrumentor(),
+            new get_cache_config_telemetry_1.OpenAICacheConfigInstrumentor(),
+            new get_bedrock_mantle_telemetry_1.OpenAIBedrockMantleInstrumentor(),
+            new get_structured_output_schema_telemetry_1.TraceloopStructuredOutputSchemaInstrumentor(get_structured_output_schema_telemetry_2.readStructuredOutputSchema),
+        ];
+    }
+    // The endpoint complements ignore `instrumentation`; the streaming/cache ones
+    // patch its internal handlers.
+    instrument(instrumentation) {
+        for (const sub of this._subInstrumentors)
+            sub.instrument(instrumentation);
+    }
+    uninstrument() {
+        for (const sub of this._subInstrumentors)
+            sub.uninstrument();
+    }
+}
+exports.OpenAITelemetryInstrumentor = OpenAITelemetryInstrumentor;

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

@@ -0,0 +1,35 @@
+/**
+ * Structured-output schema capture, shared by every provider complement.
+ *
+ * Each provider asks for structured output under its own request field (OpenAI
+ * `response_format`, Anthropic `output_config.format`, Cohere `response_format`,
+ * Gemini `responseJsonSchema`), but they all serialize the schema into the
+ * request the same way - and OpenAI, Anthropic and Vercel bill it as input - so
+ * the complements stamp one provider-agnostic attribute and the worker stores it
+ * in `input_structured_output_schema`.
+ *
+ * Every traceloop instrumentor builds its span in `startSpan({ params })`, so
+ * the three that go through one (OpenAI, Anthropic, Cohere) share the wrapper
+ * below and supply only a reader for their own request vocabulary. Google is
+ * wrapped at its own call site, and stamps through `setStructuredOutputSchemaTelemetry`
+ * directly.
+ */
+import type { Span } from '@opentelemetry/api';
+export declare const STRUCTURED_OUTPUT_SCHEMA_ATTRIBUTE = "gen_ai.request.structured_output_schema";
+/**
+ * Stamp the requested JSON schema. JS callers always reach the request with a
+ * plain JSON-schema object (Zod and friends are converted by the client before
+ * it), so unlike the Python SDK there is no output-model shape to convert here.
+ */
+export declare function setStructuredOutputSchemaTelemetry(span: Span, schema: unknown): void;
+/**
+ * Stamp the schema of every span a traceloop instrumentor opens, reading it out
+ * of the request with the provider's own `readSchema`.
+ */
+export declare class TraceloopStructuredOutputSchemaInstrumentor {
+    private readonly _readSchema;
+    private _patched;
+    constructor(_readSchema: (params: any) => unknown);
+    instrument(instrumentation: any): void;
+    uninstrument(): void;
+}

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

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Structured-output schema capture, shared by every provider complement.
+ *
+ * Each provider asks for structured output under its own request field (OpenAI
+ * `response_format`, Anthropic `output_config.format`, Cohere `response_format`,
+ * Gemini `responseJsonSchema`), but they all serialize the schema into the
+ * request the same way - and OpenAI, Anthropic and Vercel bill it as input - so
+ * the complements stamp one provider-agnostic attribute and the worker stores it
+ * in `input_structured_output_schema`.
+ *
+ * Every traceloop instrumentor builds its span in `startSpan({ params })`, so
+ * the three that go through one (OpenAI, Anthropic, Cohere) share the wrapper
+ * below and supply only a reader for their own request vocabulary. Google is
+ * wrapped at its own call site, and stamps through `setStructuredOutputSchemaTelemetry`
+ * directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceloopStructuredOutputSchemaInstrumentor = exports.STRUCTURED_OUTPUT_SCHEMA_ATTRIBUTE = void 0;
+exports.setStructuredOutputSchemaTelemetry = setStructuredOutputSchemaTelemetry;
+exports.STRUCTURED_OUTPUT_SCHEMA_ATTRIBUTE = 'gen_ai.request.structured_output_schema';
+/**
+ * Stamp the requested JSON schema. JS callers always reach the request with a
+ * plain JSON-schema object (Zod and friends are converted by the client before
+ * it), so unlike the Python SDK there is no output-model shape to convert here.
+ */
+function setStructuredOutputSchemaTelemetry(span, schema) {
+    if (!span || !span.isRecording || !span.isRecording())
+        return;
+    if (!schema || typeof schema !== 'object')
+        return;
+    span.setAttribute(exports.STRUCTURED_OUTPUT_SCHEMA_ATTRIBUTE, JSON.stringify(schema));
+}
+/**
+ * Stamp the schema of every span a traceloop instrumentor opens, reading it out
+ * of the request with the provider's own `readSchema`.
+ */
+class TraceloopStructuredOutputSchemaInstrumentor {
+    _readSchema;
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    constructor(_readSchema) {
+        this._readSchema = _readSchema;
+    }
+    // No-op (and never throws) if the instrumentor's internals have changed shape —
+    // the worst case is a missing schema, never a crash.
+    instrument(instrumentation) {
+        if (!instrumentation)
+            return;
+        // OpenAI and Anthropic build their span in `startSpan`, Cohere in
+        // `_startSpan`; all receive the same `{ params }` request.
+        const methodName = typeof instrumentation.startSpan === 'function' ? 'startSpan' : '_startSpan';
+        const startSpanOriginal = instrumentation[methodName];
+        if (typeof startSpanOriginal !== 'function')
+            return;
+        const readSchema = this._readSchema;
+        instrumentation[methodName] = function startSpanWithStructuredOutputSchema(request) {
+            const span = startSpanOriginal.call(this, request);
+            try {
+                setStructuredOutputSchemaTelemetry(span, readSchema(request && request.params));
+            }
+            catch {
+                // Never break span creation over an enrichment failure.
+            }
+            return span;
+        };
+        this._patched.push([instrumentation, methodName, startSpanOriginal]);
+    }
+    uninstrument() {
+        for (const [owner, methodName, original] of this._patched) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.TraceloopStructuredOutputSchemaInstrumentor = TraceloopStructuredOutputSchemaInstrumentor;

package/dist/src/instrumentation/vercel/full_instrumentation.d.ts

@@ -0,0 +1,3 @@
+export declare class VercelAiSdkInstrumentor {
+    instrument(): void;
+}

package/dist/src/instrumentation/vercel/full_instrumentation.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VercelAiSdkInstrumentor = void 0;
+/**
+ * Instrumentor for the Vercel AI SDK (`ai` package, v7+).
+ *
+ * The AI SDK ships its own OTel integration in `@ai-sdk/otel`; instrumenting
+ * is registering it globally so every generateText/streamText/embed call emits
+ * GenAI semconv spans through the tracer provider weflayr's setup() installed.
+ * `usage: true` adds the `ai.usage.*` token details (reasoning tokens, uncached
+ * input) that the semconv attributes do not carry; `providerMetadata: true`
+ * opts into `ai.response.providerMetadata` on the spans that carry it.
+ *
+ * The aggregate spans the integration emits around each model call
+ * (invoke_agent, agent_step, duplicated embeddings spans) are filtered out
+ * before export by otel/vercel-ai-sdk-span-filter.js.
+ */
+const get_cache_creation_telemetry_1 = require("./get_cache_creation_telemetry");
+const get_structured_output_schema_telemetry_1 = require("./get_structured_output_schema_telemetry");
+class VercelAiSdkInstrumentor {
+    instrument() {
+        let registerTelemetry;
+        let OpenTelemetry;
+        try {
+            ({ registerTelemetry } = require('ai'));
+            ({ OpenTelemetry } = require('@ai-sdk/otel'));
+        }
+        catch (err) {
+            throw new Error('weflayr.autoInstrument("vercel_ai_gateway"): failed to load "ai" / "@ai-sdk/otel". ' +
+                `Install them with: npm install ai @ai-sdk/otel\nUnderlying error: ${err.message}`);
+        }
+        // registerTelemetry only exists since v7.
+        if (typeof registerTelemetry !== 'function') {
+            throw new Error('weflayr.autoInstrument("vercel_ai_gateway") requires version 7+ of the Vercel AI SDK ' +
+                '(the "ai" package), which added global telemetry registration. ' +
+                'Upgrade with: npm install ai@latest @ai-sdk/otel.\n' +
+                'On ai <= 6 telemetry can only be enabled per call: remove "vercel_ai_gateway" from ' +
+                'aiSdks (pass an empty list if no other sdks need to be instrumented). Instead, make sure ' +
+                'experimental_telemetry: { isEnabled: true } is passed on each generateText/streamText call.');
+        }
+        const dispatcher = new OpenTelemetry({ usage: true, providerMetadata: true });
+        // The integration never emits the raw provider usage, the only place the
+        // written cache tokens per TTL (Anthropic's `cache_creation`) are
+        // reported; this complement stamps it on the model-call span (see
+        // get_cache_creation_telemetry).
+        new get_cache_creation_telemetry_1.VercelCacheCreationInstrumentor().instrument(dispatcher);
+        // generateObject's schema is only stamped on the root span the weflayr
+        // filter drops; this complement re-stamps it on the model-call span (see
+        // get_structured_output_schema_telemetry).
+        new get_structured_output_schema_telemetry_1.VercelStructuredOutputSchemaInstrumentor().instrument(dispatcher);
+        registerTelemetry(dispatcher);
+    }
+}
+exports.VercelAiSdkInstrumentor = VercelAiSdkInstrumentor;

package/dist/src/instrumentation/vercel/get_cache_creation_telemetry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cache-write capture for Vercel AI SDK (ai >= 7) model-call spans.
+ *
+ * Anthropic reports the written cache tokens per TTL in its raw usage
+ * (`usage.cache_creation`, ephemeral_5m/1h buckets — billed at different
+ * rates). ai >= 7 carries that verbatim on the model-call telemetry event as
+ * `event.usage.raw` (a documented field of LanguageModelUsage), but the
+ * `@ai-sdk/otel` integration never emits it, so the span loses it.
+ *
+ * Wrap the telemetry dispatcher's `onLanguageModelCallEnd(event)` (a public
+ * callback of the telemetry interface) to read `usage.cache_creation` off the
+ * raw usage and stamp it verbatim as `weflayr.cache.creation` on the
+ * still-open model-call span (reached through the integration's call state)
+ * before the original handler ends it; the normalizer owns the mapping to TTL
+ * tiers.
+ */
+export declare function cacheCreationFromRawUsage(rawUsage: any): Record<string, unknown> | undefined;
+export declare class VercelCacheCreationInstrumentor {
+    private _patched;
+    instrument(dispatcher: any): void;
+    uninstrument(): void;
+}

package/dist/src/instrumentation/vercel/get_cache_creation_telemetry.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Cache-write capture for Vercel AI SDK (ai >= 7) model-call spans.
+ *
+ * Anthropic reports the written cache tokens per TTL in its raw usage
+ * (`usage.cache_creation`, ephemeral_5m/1h buckets — billed at different
+ * rates). ai >= 7 carries that verbatim on the model-call telemetry event as
+ * `event.usage.raw` (a documented field of LanguageModelUsage), but the
+ * `@ai-sdk/otel` integration never emits it, so the span loses it.
+ *
+ * Wrap the telemetry dispatcher's `onLanguageModelCallEnd(event)` (a public
+ * callback of the telemetry interface) to read `usage.cache_creation` off the
+ * raw usage and stamp it verbatim as `weflayr.cache.creation` on the
+ * still-open model-call span (reached through the integration's call state)
+ * before the original handler ends it; the normalizer owns the mapping to TTL
+ * tiers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VercelCacheCreationInstrumentor = void 0;
+exports.cacheCreationFromRawUsage = cacheCreationFromRawUsage;
+const CACHE_CREATION_ATTR = 'weflayr.cache.creation';
+// The raw `usage.cache_creation` of a provider usage, or undefined when the
+// provider reports none (or reports only zeros — non-caching calls carry no
+// attribute).
+function cacheCreationFromRawUsage(rawUsage) {
+    const cacheCreation = rawUsage && rawUsage.cache_creation;
+    if (!cacheCreation)
+        return undefined;
+    return Object.values(cacheCreation).some(Boolean) ? cacheCreation : undefined;
+}
+class VercelCacheCreationInstrumentor {
+    // [owner, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    // No-op (and never throws) if the interface is missing — the worst case is
+    // the cache-write capture staying empty, exactly the pre-complement
+    // behaviour.
+    instrument(dispatcher) {
+        if (!dispatcher || typeof dispatcher.onLanguageModelCallEnd !== 'function')
+            return;
+        const original = dispatcher.onLanguageModelCallEnd;
+        dispatcher.onLanguageModelCallEnd = function onLanguageModelCallEndWithCacheCreation(event) {
+            try {
+                const cacheCreation = cacheCreationFromRawUsage(event && event.usage && event.usage.raw);
+                if (cacheCreation) {
+                    const callState = this.getCallState && this.getCallState(event.callId);
+                    const span = callState && callState.inferenceSpan;
+                    if (span && typeof span.setAttribute === 'function') {
+                        span.setAttribute(CACHE_CREATION_ATTR, JSON.stringify(cacheCreation));
+                    }
+                }
+            }
+            catch {
+                // Never break span finalization over an enrichment failure.
+            }
+            return original.call(this, event);
+        };
+        this._patched.push([dispatcher, 'onLanguageModelCallEnd', original]);
+    }
+    uninstrument() {
+        for (const [owner, methodName, original] of this._patched) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.VercelCacheCreationInstrumentor = VercelCacheCreationInstrumentor;