weflayr 0.16.0 → 0.20.2

package/tests/index.test.js

@@ -1,1102 +1,691 @@
 'use strict';
 
-// ---------------------------------------------------------------------------
-// Module doubles — registered before any test code so snippet require() calls
-// work without openai installed and without weflayr in node_modules.
-// ---------------------------------------------------------------------------
-{
-  const Module = require('module');
-  const path = require('path');
-  const _origLoad = Module._load;
-  Module._load = function(request, parent, isMain) {
-    if (request === 'openai') {
-      // The real openai package is required as `const OpenAI = require('openai')`,
-      // so the module export IS the constructor (not a namespace object).
-      function OpenAI(_opts) {
-        return {
-          chat: {
-            completions: {
-              create: async (args) => ({ id: 'mock-res', model: args.model || 'gpt-4o-mini', choices: [] }),
-            },
-          },
-          images: {
-            generate: async () => ({ data: [{ b64_json: 'abc123', url: 'https://example.com/img.png' }] }),
-          },
-        };
-      }
-      return OpenAI;
-    }
-    if (request === '@mastra/core') {
-      function Agent(opts) {
-        this._name = opts.name;
-      }
-      Agent.prototype.generate = async function(_messages, _options) {
-        return {
-          text:         'Hello from the Mastra fake agent.',
-          modelId:      'gpt-4o-mini',
-          finishReason: 'stop',
-          usage:    { promptTokens: 10, completionTokens: 15, totalTokens: 25 },
-          request:  { body: '{"messages":[{"role":"user","content":"Hello"}]}' },
-          response: {
-            id:       'fake-res',
-            modelId:  'gpt-4o-mini',
-            messages: [{ role: 'assistant', content: [{ type: 'text', text: 'Hello.' }] }],
-            body:     { choices: [{ message: { role: 'assistant', content: 'Hello.' } }] },
-          },
-          steps: [{ text: 'Hello.', request: { body: '...' }, finishReason: 'stop' }],
-        };
-      };
-      // stream() returns a StreamTextResult-like object (NOT directly iterable).
-      // usage and response are DelayedPromise wrappers matching real Mastra behaviour.
-      Agent.prototype.stream = function(_messages, _options) {
-        return {
-          textStream: (async function* () {
-            yield 'Hello'; yield ' Mastra'; yield ' stream.';
-          })(),
-          usage: { status: { type: 'resolved', value: { promptTokens: 10, completionTokens: 15, totalTokens: 25 } } },
-          response: { status: { type: 'resolved', value: { modelId: 'gpt-4o-mini', id: 'fake-stream-res' } } },
-        };
-      };
-      return { Agent };
-    }
-    if (request === '@ai-sdk/openai') {
-      return { openai: (modelId) => ({ _provider: 'openai', modelId }) };
-    }
-    if (request === '@ai-sdk/openai-compatible') {
-      function createOpenAICompatible({ name }) {
-        return function(modelId) {
-          return {
-            specificationVersion: 'v1',
-            provider: name,
-            modelId,
-            defaultObjectGenerationMode: undefined,
-            doGenerate: async () => ({
-              text: 'Hello!',
-              usage: { promptTokens: 10, completionTokens: 5 },
-              finishReason: 'stop',
-              rawCall: { rawPrompt: [], rawSettings: {} },
-              rawResponse: { headers: {} },
-              warnings: [],
-            }),
-            doStream: async () => ({
-              stream: new ReadableStream({
-                start(ctrl) {
-                  ctrl.enqueue({ type: 'text-delta', textDelta: 'Hello!' });
-                  ctrl.enqueue({ type: 'finish', finishReason: 'stop', usage: { promptTokens: 10, completionTokens: 5 } });
-                  ctrl.close();
-                },
-              }),
-              rawCall: { rawPrompt: [], rawSettings: {} },
-              rawResponse: { headers: {} },
-              warnings: [],
-            }),
-          };
-        };
-      }
-      return { createOpenAICompatible };
-    }
-    if (request === 'ai') {
-      function wrapLanguageModel({ model, middleware }) {
-        return {
-          modelId: model.modelId,
-          doGenerate: async (params) =>
-            middleware.wrapGenerate({ doGenerate: () => model.doGenerate(params), params, model }),
-          doStream: async (params) =>
-            middleware.wrapStream({ doStream: () => model.doStream(params), params, model }),
-        };
-      }
-      async function generateText({ model, prompt }) {
-        const params = { prompt: [{ role: 'user', content: [{ type: 'text', text: prompt }] }] };
-        return model.doGenerate(params);
-      }
-      function streamText({ model, prompt }) {
-        const params = { prompt: [{ role: 'user', content: [{ type: 'text', text: prompt }] }] };
-        const streamPromise = model.doStream(params);
-        return {
-          get textStream() {
-            return (async function* () {
-              const { stream } = await streamPromise;
-              const reader = stream.getReader();
-              while (true) {
-                const { done, value } = await reader.read();
-                if (done) break;
-                if (value && value.type === 'text-delta') yield value.textDelta;
-              }
-            })();
-          },
-        };
-      }
-      return { wrapLanguageModel, generateText, streamText };
-    }
-    if (request === 'weflayr') {
-      return _origLoad.call(this, path.resolve(__dirname, '../src/index.js'), parent, isMain);
-    }
-    return _origLoad.call(this, request, parent, isMain);
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const Module = require('node:module');
+
+const { trace, context: otelContext } = require('@opentelemetry/api');
+const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base');
+const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+const { AsyncHooksContextManager } = require('@opentelemetry/context-async-hooks');
+
+const weflayr = require('../src');
+const { _state } = require('../src/setup');
+const { isDefaultExportSpan } = require('../src/otel/span-filter');
+const { WeflayrSpanProcessor } = require('../src/otel/span-processor');
+const { buildExporter, _exportWithRetry } = require('../src/otel/exporter');
+const { patchOpenAIStreamingUsage } = require('../src/otel/openai-streaming-usage');
+
+const contextManager = new AsyncHooksContextManager();
+contextManager.enable();
+otelContext.setGlobalContextManager(contextManager);
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeExporterStub() {
+  const exported = [];
+  return {
+    exported,
+    export(spans, cb) {
+      exported.push(...spans);
+      cb({ code: 0 });
+    },
+    shutdown() {
+      return Promise.resolve();
+    },
+    forceFlush() {
+      return Promise.resolve();
+    },
   };
 }
 
-const { test } = require('node:test');
-const assert = require('assert/strict');
-
-const TEST_CREDS = {
-  intake_url: 'http://localhost:19999', // nothing listening — fire-and-forget is fine
-  client_id: 'test-client-id',
-  client_secret: 'test-secret',
-};
-
-// Reset module cache between tests so _config doesn't leak
-function freshSDK() {
-  delete require.cache[require.resolve('../src/instrument')];
-  delete require.cache[require.resolve('../src/vercel-ai-middleware')];
-  delete require.cache[require.resolve('../src/index')];
-  return require('../src/index');
-}
-
-// Minimal fake client: one async method at a nested path
-function fakeClient() {
+function makeFakeSpan({
+  attributes = {},
+  instrumentationScope = { name: 'opentelemetry.instrumentation.openai' },
+  name = 'openai.chat',
+} = {}) {
+  const attrs = { ...attributes };
+  const ctx = {
+    traceId: '11111111111111111111111111111111',
+    spanId: '2222222222222222',
+    traceFlags: 1,
+  };
   return {
-    chat: {
-      completions: {
-        create: async (args) => ({ id: 'res-1', model: args.model, choices: [] }),
-      },
+    name,
+    attributes: attrs,
+    instrumentationScope,
+    instrumentationLibrary: instrumentationScope,
+    resource: { attributes: {} },
+    kind: 0,
+    status: { code: 0 },
+    startTime: [0, 0],
+    endTime: [0, 0],
+    duration: [0, 0],
+    events: [],
+    links: [],
+    droppedAttributesCount: 0,
+    droppedEventsCount: 0,
+    droppedLinksCount: 0,
+    ended: true,
+    spanContext: () => ctx,
+    setAttribute(k, v) {
+      attrs[k] = v;
+    },
+    setAttributes(obj) {
+      Object.assign(attrs, obj);
     },
+    isRecording: () => true,
   };
 }
 
-// ---------------------------------------------------------------------------
-// Content policy — function-based middleware
-// ---------------------------------------------------------------------------
+// ── setup ─────────────────────────────────────────────────────────────────────
 
-test('ignore_fields function filters event data', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  weflayr_setup({
-    ...TEST_CREDS,
-    event_mode: 'default',
-    ignore_fields: (data) => { delete data.messages; return data; },
-    methods: [{ call: 'chat.completions.create' }],
-  });
-
-  const client = weflayr_instrument(fakeClient());
-  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
-
-  assert.equal(result.id, 'res-1');
+test('setup throws without apiKey', () => {
+  const saved = process.env.WEFLAYR_API_KEY;
+  delete process.env.WEFLAYR_API_KEY;
+  try {
+    assert.throws(() => weflayr.setup({}), /apiKey/);
+  } finally {
+    if (saved !== undefined) process.env.WEFLAYR_API_KEY = saved;
+  }
 });
 
-test('allow_fields function filters event data', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  weflayr_setup({
-    ...TEST_CREDS,
-    event_mode: 'default',
-    allow_fields: (data) => ({ model: data.model }),
-    methods: [{ call: 'chat.completions.create' }],
-  });
-
-  const client = weflayr_instrument(fakeClient());
-  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
-
-  assert.equal(result.id, 'res-1');
+test('setup picks up apiKey from WEFLAYR_API_KEY env var', () => {
+  trace.disable();
+  _state.processor = null;
+  process.env.WEFLAYR_API_KEY = 'env-key';
+  try {
+    weflayr.setup({});
+    assert.ok(_state.processor, 'processor must be installed using the env-var key');
+  } finally {
+    delete process.env.WEFLAYR_API_KEY;
+  }
 });
 
-test('both ignore_fields and allow_fields set — no events sent, function still works', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  weflayr_setup({
-    ...TEST_CREDS,
-    event_mode: 'default',
-    ignore_fields: (data) => data,
-    allow_fields: (data) => data,
-    methods: [{ call: 'chat.completions.create' }],
-  });
-
-  const client = weflayr_instrument(fakeClient());
-  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
-
-  assert.equal(result.id, 'res-1');
+test('setup sets the content-capture env var when captureMessageContent=false', () => {
+  delete process.env.OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT;
+  weflayr.setup({ apiKey: 'test-key', captureMessageContent: false });
+  assert.equal(process.env.OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, 'false');
 });
 
-test('no content policy — pass-through, function still works', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  weflayr_setup({
-    ...TEST_CREDS,
-    event_mode: 'default',
-    methods: [{ call: 'chat.completions.create' }],
-  });
-
-  const client = weflayr_instrument(fakeClient());
-  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
-
-  assert.equal(result.id, 'res-1');
+test('setup with captureMessageContent=true sets env var to true', () => {
+  delete process.env.OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT;
+  weflayr.setup({ apiKey: 'test-key', captureMessageContent: true });
+  assert.equal(process.env.OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, 'true');
 });
 
-test('ignore_fields does not mutate actual call args', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  let capturedArgs;
-  const client = {
-    chat: {
-      completions: {
-        create: async (args) => { capturedArgs = args; return { id: 'res-1' }; },
-      },
-    },
-  };
-
-  weflayr_setup({
-    ...TEST_CREDS,
-    event_mode: 'default',
-    ignore_fields: (data) => { delete data.messages; return data; },
-    methods: [{ call: 'chat.completions.create' }],
-  });
-
-  const instrumented = weflayr_instrument(client);
-  await instrumented.chat.completions.create({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'hello' }] });
-
-  assert.ok(Array.isArray(capturedArgs.messages));
-  assert.equal(capturedArgs.messages[0].content, 'hello');
+test('setup without captureMessageContent leaves env var untouched', () => {
+  delete process.env.OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT;
+  weflayr.setup({ apiKey: 'test-key' });
+  assert.equal(process.env.OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, undefined);
 });
 
-test('missing methods does not crash on object instrumentation', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  weflayr_setup({
-    ...TEST_CREDS,
-    event_mode: 'default',
-    // methods intentionally omitted
-  });
-
-  const client = weflayr_instrument(fakeClient());
-  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
-
-  assert.equal(result.id, 'res-1');
+test('setup adopts a pre-existing TracerProvider', () => {
+  // Reset the global proxy and our _state so the test owns the registry.
+  trace.disable();
+  _state.processor = null;
+
+  // The user (or another OTel instrumentation) registers a provider first.
+  const foreign = new NodeTracerProvider({ spanProcessors: [] });
+  foreign.register();
+
+  weflayr.setup({ apiKey: 'test-key' });
+
+  // weflayr must have attached its processor to `foreign`, not created a new
+  // provider — otherwise provider.register() would have silently no-op'd and
+  // the LLM spans wouldn't reach our exporter.
+  const attached = foreign._activeSpanProcessor?._spanProcessors ?? [];
+  assert.ok(
+    attached.some((sp) => sp instanceof WeflayrSpanProcessor),
+    'WeflayrSpanProcessor must be attached to the existing TracerProvider'
+  );
+  assert.strictEqual(_state.tracerProvider, foreign);
 });
 
-test('missing methods does not crash on function instrumentation', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
+test('setup called twice replaces the prior processor', () => {
+  // Stacking would double-export every span and leak HTTP pools in
+  // long-running processes that reconfigure (e.g. API-key rotation).
+  trace.disable();
+  _state.processor = null;
+
+  weflayr.setup({ apiKey: 'k1' });
+  const firstProcessor = _state.processor;
+  let shutdownCalled = false;
+  const originalShutdown = firstProcessor.shutdown.bind(firstProcessor);
+  firstProcessor.shutdown = () => {
+    shutdownCalled = true;
+    return originalShutdown();
+  };
 
-  weflayr_setup({
-    ...TEST_CREDS,
-    event_mode: 'default',
-    // methods intentionally omitted
-  });
+  weflayr.setup({ apiKey: 'k2' });
 
-  async function myFn(x) { return x * 2; }
-  const instrumented = weflayr_instrument(myFn);
+  assert.ok(_state.processor);
+  assert.notStrictEqual(_state.processor, firstProcessor);
+  assert.equal(shutdownCalled, true);
 
-  assert.equal(await instrumented(5), 10);
+  const tp = _state.tracerProvider;
+  const attached = tp._activeSpanProcessor?._spanProcessors ?? [];
+  assert.ok(!attached.includes(firstProcessor));
+  assert.ok(attached.includes(_state.processor));
 });
 
-// ---------------------------------------------------------------------------
-// enabled: false — target passes through unchanged, calls still work
-// ---------------------------------------------------------------------------
+// ── buildExporter ─────────────────────────────────────────────────────────────
 
-test('enabled:false returns the original object untouched', () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  weflayr_setup({ methods: [{ call: 'chat.completions.create' }] , enabled: false });
-
-  const client = fakeClient();
-  const result = weflayr_instrument(client);
+function _exporterParams(exporter) {
+  return exporter._delegate._transport._transport._parameters;
+}
 
-  assert.strictEqual(result, client);
+test('buildExporter sets the bearer header and base URL', () => {
+  const exporter = buildExporter({ baseUrl: 'https://api.weflayr.com', apiKey: 'sk-x' });
+  assert.equal(_exporterParams(exporter).url, 'https://api.weflayr.com/');
 });
 
-test('enabled:false returns the original function untouched', () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  async function myFn(x) { return x * 2; }
-  weflayr_setup({ methods: [{ call: 'myFn' }] , enabled: false });
-
-  assert.strictEqual(weflayr_instrument(myFn), myFn);
+test('buildExporter strips trailing slash on baseUrl', () => {
+  const exporter = buildExporter({ baseUrl: 'https://api.weflayr.com/', apiKey: 'k' });
+  assert.equal(_exporterParams(exporter).url, 'https://api.weflayr.com/');
 });
 
-test('enabled:false — original function still executes correctly', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  weflayr_setup({ methods: [{ call: 'chat.completions.create' }] , enabled: false });
-
-  const client = weflayr_instrument(fakeClient());
-  const result = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+// ── span-filter ───────────────────────────────────────────────────────────────
 
-  assert.equal(result.id, 'res-1');
+test('isDefaultExportSpan accepts spans with gen_ai.* attributes', () => {
+  const span = makeFakeSpan({
+    attributes: { 'gen_ai.system': 'openai' },
+    instrumentationScope: { name: 'unknown' },
+  });
+  assert.equal(isDefaultExportSpan(span), true);
 });
 
-// ---------------------------------------------------------------------------
-// Documentation snippets
-// All snippet code runs verbatim — Module._load at top of file provides
-// require('openai') and require('weflayr') doubles.
-// update_doc_snippets.py extracts between:  // SNIPPET_START: <name> ... // SNIPPET_END: <name>
-// ---------------------------------------------------------------------------
-
-// Intercept http.request; returns array of parsed event JSON bodies.
-async function captureHttp(fn) {
-  const http = require('http');
-  const sent = [];
-  const origRequest = http.request;
-  http.request = function(_opts, responseCb) {
-    const chunks = [];
-    const req = {
-      write: (d) => chunks.push(typeof d === 'string' ? d : d.toString()),
-      end: () => {
-        try { sent.push(JSON.parse(chunks.join(''))); } catch { /* skip malformed */ }
-        if (responseCb) responseCb({ resume: () => {}, on: () => {}, statusCode: 200 });
-      },
-      on: () => req,
-    };
-    return req;
-  };
-  try { await fn(); } finally { http.request = origRequest; }
-  return sent;
-}
-
-const SNIPPET_ENV = {
-  WEFLAYR_INTAKE_URL: TEST_CREDS.intake_url,
-  WEFLAYR_CLIENT_ID:  TEST_CREDS.client_id,
-  WEFLAYR_CLIENT_SECRET: TEST_CREDS.client_secret,
-  OPENAI_API_KEY: 'sk-test',
-};
-function setSnippetEnv() { Object.assign(process.env, SNIPPET_ENV); }
-
-test('snippet quickstart_setup: wraps client, sends before+after events', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: quickstart_setup
-    const OpenAI = require('openai');
-    const { weflayr_setup, weflayr_instrument } = require('weflayr');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-      default_tags: {
-        app: 'my-app',
-        version: '1.0.0',
-      },
-      methods: [
-        { call: 'chat.completions.create' },
-      ],
-    });
-
-    const client = weflayr_instrument(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
-    // SNIPPET_END: quickstart_setup
-
-    assert.equal(typeof client.chat.completions.create, 'function');
-    await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+test('isDefaultExportSpan accepts spans from known instrumentation scopes', () => {
+  const span = makeFakeSpan({
+    attributes: {},
+    instrumentationScope: { name: 'opentelemetry.instrumentation.openai' },
   });
-
-  assert.ok(sent.some(e => e.event_type === 'before'), 'before event sent');
-  assert.ok(sent.some(e => e.event_type === 'after'),  'after event sent');
-  assert.equal(sent[0].method, 'chat.completions.create');
-  assert.equal(sent[0].tags.app, 'my-app');
-  assert.equal(sent[0].tags.version, '1.0.0');
+  assert.equal(isDefaultExportSpan(span), true);
 });
 
-test('snippet quickstart_call: tags stripped from call, tags in telemetry', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-  setSnippetEnv();
-
-  let capturedArgs;
-  const raw = {
-    chat: { completions: { create: async (args) => { capturedArgs = args; return { id: 'res-1', choices: [] }; } } },
-  };
-  weflayr_setup({ ...TEST_CREDS, methods: [{ call: 'chat.completions.create' }] });
-  const client = weflayr_instrument(raw);
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: quickstart_call
-    const response = await client.chat.completions.create({
-      model: 'gpt-4o-mini',
-      messages: [{ role: 'user', content: 'Hello!' }],
-      __weflayr_tags: {
-          provider: 'openai',
-          feature: 'onboarding',
-          customer_id: '#3756'
-        },
-    });
-    // response is the standard OpenAI response object — unchanged
-    // SNIPPET_END: quickstart_call
-
-    assert.equal(response.id, 'res-1');
+test('isDefaultExportSpan rejects unrelated spans', () => {
+  const span = makeFakeSpan({
+    attributes: { 'http.method': 'GET' },
+    instrumentationScope: { name: 'http' },
   });
-
-  assert.ok(!('__weflayr_tags' in capturedArgs), 'tags stripped from underlying call');
-  const before = sent.find(e => e.event_type === 'before');
-  assert.ok(before, 'before event sent');
-  assert.deepEqual(before.tags, { provider: 'openai', feature: 'onboarding', customer_id: '#3756' });
+  assert.equal(isDefaultExportSpan(span), false);
 });
 
-test('snippet openai_full_coverage: 7 methods configured, events sent', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: openai_full_coverage
-    const { weflayr_setup, weflayr_instrument } = require('weflayr');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-      methods: [
-        { call: 'chat.completions.create' },
-        { call: 'completions.create' },
-        { call: 'embeddings.create' },
-        { call: 'responses.create' },
-        {
-          call: 'audio.speech.create',
-          middleware: (args) => ({ char_count: args?.input?.length ?? 0 }),
-        },
-        { call: 'audio.transcriptions.create' },
-        { call: 'audio.translations.create' },
-      ],
-    });
-
-    const OpenAI = require('openai');
-    const client = weflayr_instrument(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
-    // SNIPPET_END: openai_full_coverage
+// ── WeflayrSpanProcessor ──────────────────────────────────────────────────────
 
-    assert.equal(typeof client.chat.completions.create, 'function');
-    await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+test('WeflayrSpanProcessor stamps defaultTags on span start', () => {
+  const exporter = makeExporterStub();
+  const proc = new WeflayrSpanProcessor({
+    exporter,
+    defaultTags: { app: 'svc-A', env: 'prod' },
   });
-
-  assert.ok(sent.some(e => e.event_type === 'before'), 'before event sent');
-  assert.ok(sent.some(e => e.event_type === 'after'),  'after event sent');
-  assert.equal(sent[0].method, 'chat.completions.create');
+  const span = makeFakeSpan();
+  proc.onStart(span, otelContext.active());
+  assert.equal(span.attributes['weflayr.tag.app'], 'svc-A');
+  assert.equal(span.attributes['weflayr.tag.env'], 'prod');
 });
 
-test('snippet openai_tagging: tags stripped from call, all 4 tags in telemetry', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-  setSnippetEnv();
-
-  let capturedArgs;
-  const raw = {
-    chat: { completions: { create: async (args) => { capturedArgs = args; return { id: 'res-1' }; } } },
-  };
-  weflayr_setup({ ...TEST_CREDS, methods: [{ call: 'chat.completions.create' }] });
-  const client = weflayr_instrument(raw);
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: openai_tagging
-    await client.chat.completions.create({
-      model: 'gpt-4o-mini',
-      messages: [{ role: 'user', content: 'Hello' }],
-      __weflayr_tags: {
-        provider: 'openai',
-        feature: 'support-chat',
-        customer_id: 'acme-corp',
-        env: 'production',
-      },
-    });
-    // SNIPPET_END: openai_tagging
-  });
+test('WeflayrSpanProcessor forwards GenAI spans to the exporter', async () => {
+  const exporter = makeExporterStub();
+  const proc = new WeflayrSpanProcessor({ exporter, exportMode: 'immediate' });
+  const span = makeFakeSpan({ attributes: { 'gen_ai.system': 'openai' } });
+  proc.onEnd(span);
+  await proc.forceFlush();
+  assert.equal(exporter.exported.length, 1);
+});
 
-  assert.ok(!('__weflayr_tags' in capturedArgs), 'tags stripped from underlying call');
-  assert.equal(capturedArgs.model, 'gpt-4o-mini');
-  const before = sent.find(e => e.event_type === 'before');
-  assert.ok(before, 'before event sent');
-  assert.deepEqual(before.tags, { provider: 'openai', feature: 'support-chat', customer_id: 'acme-corp', env: 'production' });
+test('WeflayrSpanProcessor drops non-GenAI spans', async () => {
+  const exporter = makeExporterStub();
+  const proc = new WeflayrSpanProcessor({ exporter, exportMode: 'immediate' });
+  proc.onEnd(
+    makeFakeSpan({
+      attributes: { 'http.method': 'GET' },
+      instrumentationScope: { name: 'http' },
+    })
+  );
+  await proc.forceFlush();
+  assert.equal(exporter.exported.length, 0);
 });
 
-test('snippet openai_image_generation: b64_json stripped from telemetry, url preserved', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: openai_image_generation
-    const { weflayr_setup, weflayr_instrument } = require('weflayr');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-      ignore_fields: (data) => {
-        (data.data ?? []).forEach(img => delete img.b64_json);
-        return data;
-      },
-      methods: [
-        { call: 'images.generate' },
-      ],
-    });
+test('WeflayrSpanProcessor ends orphaned LLM spans on forceFlush', async () => {
+  // LLM spans that started but never ended should be force-ended with ERROR on
+  // flush — covers openllmetry-style leaks (e.g. anthropic streaming auth error).
+  const exporter = makeExporterStub();
+  const proc = new WeflayrSpanProcessor({ exporter, exportMode: 'immediate' });
+  const provider = new BasicTracerProvider({ spanProcessors: [proc] });
+  const tracer = provider.getTracer('opentelemetry.instrumentation.anthropic');
 
-    const OpenAI = require('openai');
-    const client = weflayr_instrument(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
-    // SNIPPET_END: openai_image_generation
+  const leaked = tracer.startSpan('anthropic.chat');
+  leaked.setAttribute('gen_ai.system', 'anthropic');
+  assert.equal(exporter.exported.length, 0, 'span should not have been exported yet');
 
-    await client.images.generate({ model: 'gpt-image-1', prompt: 'a cat' });
-  });
+  await proc.forceFlush();
 
-  const after = sent.find(e => e.event_type === 'after');
-  assert.ok(after, 'after event sent');
-  for (const img of (after.response?.data ?? [])) {
-    assert.ok(!('b64_json' in img), 'b64_json stripped from telemetry');
-  }
-  assert.ok(after.response.data[0].url, 'url preserved in telemetry');
+  assert.equal(exporter.exported.length, 1);
+  // SpanStatusCode.ERROR === 2 in @opentelemetry/api
+  assert.equal(exporter.exported[0].status.code, 2);
+  await provider.shutdown();
 });
 
-// ---------------------------------------------------------------------------
-// default_tags and weflayr_propagate — behavioural tests
-// ---------------------------------------------------------------------------
-
-test('default_tags appear in before and after events', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-
-  weflayr_setup({
-    ...TEST_CREDS,
-    default_tags: { app: 'my-app', version: '1.2.0' },
-    methods: [{ call: 'chat.completions.create' }],
+test('WeflayrSpanProcessor applies mask before export', async () => {
+  const exporter = makeExporterStub();
+  let received = null;
+  const proc = new WeflayrSpanProcessor({
+    exporter,
+    exportMode: 'immediate',
+    mask: (attrs) => {
+      received = attrs;
+      attrs['gen_ai.prompt'] = '[REDACTED]';
+      return attrs;
+    },
   });
-
-  const client = weflayr_instrument(fakeClient());
-  const sent = await captureHttp(async () => {
-    await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+  const span = makeFakeSpan({
+    attributes: { 'gen_ai.system': 'openai', 'gen_ai.prompt': 'Hi Noe' },
   });
-
-  const before = sent.find(e => e.event_type === 'before');
-  assert.equal(before.tags.app, 'my-app');
-  assert.equal(before.tags.version, '1.2.0');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.equal(after.tags.app, 'my-app');
-  assert.equal(after.tags.version, '1.2.0');
+  proc.onEnd(span);
+  await proc.forceFlush();
+  assert.ok(received);
+  assert.equal(span.attributes['gen_ai.prompt'], '[REDACTED]');
 });
 
-test('weflayr_propagate adds a tag to before and after events', async () => {
-  const { weflayr_setup, weflayr_instrument, weflayr_propagate } = freshSDK();
-
-  weflayr_setup({
-    ...TEST_CREDS,
-    methods: [{ call: 'chat.completions.create' }],
-  });
+// ── propagateMetadata ────────────────────────────────────────────────────────
 
-  weflayr_propagate('customer_id', 'acme-corp');
+function _makeMetadataHarness() {
+  const exporter = makeExporterStub();
+  const proc = new WeflayrSpanProcessor({ exporter, exportMode: 'immediate' });
+  const provider = new BasicTracerProvider({ spanProcessors: [proc] });
+  const tracer = provider.getTracer('test');
+  return { exporter, proc, provider, tracer };
+}
 
-  const client = weflayr_instrument(fakeClient());
-  const sent = await captureHttp(async () => {
-    await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
-  });
+test('propagateMetadata writes structured fields and extra tags', async () => {
+  const { exporter, proc, provider, tracer } = _makeMetadataHarness();
 
-  const before = sent.find(e => e.event_type === 'before');
-  assert.equal(before.tags.customer_id, 'acme-corp');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.equal(after.tags.customer_id, 'acme-corp');
+  await weflayr.propagateMetadata(
+    {
+      featureName: 'onboarding',
+      customerId: '#3756',
+      extraTags: { variant: 'control' },
+    },
+    async () => {
+      const span = tracer.startSpan('child');
+      span.setAttribute('gen_ai.system', 'openai');
+      span.end();
+    }
+  );
+
+  await proc.forceFlush();
+  assert.equal(exporter.exported.length, 1);
+  const attrs = exporter.exported[0].attributes;
+  assert.equal(attrs['weflayr.feature_name'], 'onboarding');
+  assert.equal(attrs['weflayr.customer_id'], '#3756');
+  assert.equal(attrs['weflayr.tag.variant'], 'control');
+  assert.ok(attrs['weflayr.uuid']);
+  assert.equal(attrs['weflayr.provider_name'], undefined);
+  await provider.shutdown();
 });
 
-test('tag priority: __weflayr_tags > weflayr_propagate > default_tags', async () => {
-  const { weflayr_setup, weflayr_instrument, weflayr_propagate } = freshSDK();
+test('propagateMetadata uuid is stable within scope and changes across calls', async () => {
+  const { exporter, proc, provider, tracer } = _makeMetadataHarness();
 
-  weflayr_setup({
-    ...TEST_CREDS,
-    default_tags: { env: 'production', app: 'my-app' },
-    methods: [{ call: 'chat.completions.create' }],
+  await weflayr.propagateMetadata({ featureName: 'f', customerId: 'c' }, async () => {
+    const spanA = tracer.startSpan('a');
+    spanA.setAttribute('gen_ai.system', 'openai');
+    spanA.end();
+    const spanB = tracer.startSpan('b');
+    spanB.setAttribute('gen_ai.system', 'openai');
+    spanB.end();
   });
 
-  weflayr_propagate('env', 'staging');  // overrides default_tags.env
-
-  const client = weflayr_instrument(fakeClient());
-  const sent = await captureHttp(async () => {
-    await client.chat.completions.create({
-      model: 'gpt-4o-mini',
-      messages: [],
-      __weflayr_tags: { env: 'test' },  // overrides both
-    });
+  await weflayr.propagateMetadata({ featureName: 'f', customerId: 'c' }, async () => {
+    const spanC = tracer.startSpan('c_span');
+    spanC.setAttribute('gen_ai.system', 'openai');
+    spanC.end();
   });
 
-  const before = sent.find(e => e.event_type === 'before');
-  assert.equal(before.tags.env, 'test');      // per-call wins
-  assert.equal(before.tags.app, 'my-app');    // from default_tags, untouched
+  await proc.forceFlush();
+  const uuidA = exporter.exported[0].attributes['weflayr.uuid'];
+  const uuidB = exporter.exported[1].attributes['weflayr.uuid'];
+  const uuidC = exporter.exported[2].attributes['weflayr.uuid'];
+  assert.equal(uuidA, uuidB);
+  assert.notEqual(uuidA, uuidC);
+  await provider.shutdown();
 });
 
-// ---------------------------------------------------------------------------
-// Propagate — documentation snippets
-// ---------------------------------------------------------------------------
-
-test('snippet propagate_default_tags: default_tags in every event', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: propagate_default_tags
-    const { weflayr_setup, weflayr_instrument } = require('weflayr');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-      default_tags: {
-        app: 'my-app',
-        version: '1.2.0',
-        env: 'production',
-      },
-      methods: [{ call: 'chat.completions.create' }],
-    });
-
-    const OpenAI = require('openai');
-    const client = weflayr_instrument(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
-    // SNIPPET_END: propagate_default_tags
+test('propagateMetadata nested scopes inner overrides and extra tags merge', async () => {
+  const { exporter, proc, provider, tracer } = _makeMetadataHarness();
 
-    await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
-  });
-
-  const before = sent.find(e => e.event_type === 'before');
-  assert.ok(before, 'before event sent');
-  assert.equal(before.tags.app, 'my-app');
-  assert.equal(before.tags.version, '1.2.0');
-  assert.equal(before.tags.env, 'production');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.ok(after, 'after event sent');
-  assert.equal(after.tags.app, 'my-app');
+  await weflayr.propagateMetadata(
+    {
+      featureName: 'outer',
+      customerId: 'outer_c',
+      extraTags: { variant: 'A', shared: 'outer' },
+    },
+    async () => {
+      await weflayr.propagateMetadata(
+        {
+          featureName: 'inner',
+          customerId: 'inner_c',
+          extraTags: { shared: 'inner', experiment: 'B' },
+        },
+        async () => {
+          const span = tracer.startSpan('child');
+          span.setAttribute('gen_ai.system', 'openai');
+          span.end();
+        }
+      );
+    }
+  );
+
+  await proc.forceFlush();
+  const attrs = exporter.exported[0].attributes;
+  assert.equal(attrs['weflayr.feature_name'], 'inner');
+  assert.equal(attrs['weflayr.customer_id'], 'inner_c');
+  // Outer extra tag not shadowed survives
+  assert.equal(attrs['weflayr.tag.variant'], 'A');
+  // Inner extra tag wins on conflict
+  assert.equal(attrs['weflayr.tag.shared'], 'inner');
+  assert.equal(attrs['weflayr.tag.experiment'], 'B');
+  await provider.shutdown();
 });
 
-test('snippet propagate_runtime: propagated tag in before and after', async () => {
-  const { weflayr_setup, weflayr_instrument, weflayr_propagate } = freshSDK();
-  setSnippetEnv();
+test('propagateMetadata decorator mints fresh uuid per invocation', async () => {
+  const { exporter, proc, provider, tracer } = _makeMetadataHarness();
 
-  let capturedArgs;
-  const raw = {
-    chat: { completions: { create: async (args) => { capturedArgs = args; return { id: 'res-1' }; } } },
-  };
-  weflayr_setup({ ...TEST_CREDS, methods: [{ call: 'chat.completions.create' }] });
-  const client = weflayr_instrument(raw);
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: propagate_runtime
-    const { weflayr_propagate } = require('weflayr');
-
-    // In a request handler — tags every LLM call made during this execution
-    weflayr_propagate('customer_id', 'acme-corp');
-
-    await client.chat.completions.create({
-      model: 'gpt-4o-mini',
-      messages: [{ role: 'user', content: 'Hello!' }],
-    });
-    // SNIPPET_END: propagate_runtime
+  const wrap = weflayr.propagateMetadata({ featureName: 'f', customerId: 'c' });
+  const leaf = wrap(async function leaf() {
+    const span = tracer.startSpan('child');
+    span.setAttribute('gen_ai.system', 'openai');
+    span.end();
   });
 
-  assert.ok(!('__weflayr_tags' in capturedArgs), 'no tags leaked to provider');
-  const before = sent.find(e => e.event_type === 'before');
-  assert.ok(before, 'before event sent');
-  assert.equal(before.tags.customer_id, 'acme-corp');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.ok(after, 'after event sent');
-  assert.equal(after.tags.customer_id, 'acme-corp');
-});
+  await leaf();
+  await leaf();
 
-// ---------------------------------------------------------------------------
-// Mastra integration — documentation snippets
-// @mastra/core and @ai-sdk/openai are faked by Module._load at top of file.
-// ---------------------------------------------------------------------------
-
-test('snippet mastra_setup: wraps Mastra Agent, sends before+after events on generate()', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: mastra_setup
-    const { weflayr_setup, weflayr_instrument } = require('weflayr');
-    const { Agent } = require('@mastra/core');
-    const { openai } = require('@ai-sdk/openai');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-      methods: [{ call: 'generate' }],
-    });
-
-    const agent = weflayr_instrument(
-      new Agent({
-        name:         'my-agent',
-        model:        openai('gpt-4o-mini'),
-        instructions: 'You are a helpful assistant.',
-      })
-    );
-    // SNIPPET_END: mastra_setup
-
-    await agent.generate([{ role: 'user', content: 'Hello' }]);
-  });
-
-  assert.ok(sent.some(e => e.event_type === 'before'), 'before event sent');
-  assert.ok(sent.some(e => e.event_type === 'after'),  'after event sent');
-  assert.equal(sent[0].method, 'generate');
+  await proc.forceFlush();
+  const uuidFirst = exporter.exported[0].attributes['weflayr.uuid'];
+  const uuidSecond = exporter.exported[1].attributes['weflayr.uuid'];
+  assert.notEqual(uuidFirst, uuidSecond);
+  await provider.shutdown();
 });
 
-test('snippet mastra_tags: per-call tags stripped from generate args, appear in events', async () => {
-  const { weflayr_setup, weflayr_instrument } = freshSDK();
-  setSnippetEnv();
-
-  const { Agent } = require('@mastra/core');
-  const { openai } = require('@ai-sdk/openai');
-  weflayr_setup({ ...TEST_CREDS, methods: [{ call: 'generate' }] });
-  const agent = weflayr_instrument(new Agent({ name: 'test-agent', model: openai('gpt-4o-mini'), instructions: '...' }));
+test('propagateMetadata decorator form wraps a function', async () => {
+  const { exporter, proc, provider, tracer } = _makeMetadataHarness();
 
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: mastra_tags
-    await agent.generate(
-      [{ role: 'user', content: 'Hello' }],
-      { __weflayr_tags: { feature: 'chat', customer_id: '42', env: 'prod' } },
-    );
-    // SNIPPET_END: mastra_tags
+  const wrap = weflayr.propagateMetadata({
+    featureName: 'chat',
+    customerId: 'c_42',
+    extraTags: { experiment: 'B' },
   });
-
-  const before = sent.find(e => e.event_type === 'before');
-  assert.ok(before, 'before event sent');
-  assert.deepEqual(before.tags, { feature: 'chat', customer_id: '42', env: 'prod' });
-});
-
-test('snippet mastra_content_privacy: text/request/steps/response content stripped from events', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: mastra_content_privacy
-    const { weflayr_setup, weflayr_instrument } = require('weflayr');
-    const { Agent } = require('@mastra/core');
-    const { openai } = require('@ai-sdk/openai');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-      methods: [{ call: 'generate' }],
-      ignore_fields: (data) => {
-        delete data.text;
-        delete data.request;
-        delete data.steps;
-        if (data.response) {
-          delete data.response.body;
-          delete data.response.messages;
-        }
-        return data;
-      },
-    });
-
-    const agent = weflayr_instrument(
-      new Agent({
-        name:         'my-agent',
-        model:        openai('gpt-4o-mini'),
-        instructions: 'You are a helpful assistant.',
-      })
-    );
-    // SNIPPET_END: mastra_content_privacy
-
-    await agent.generate([{ role: 'user', content: 'Hello' }]);
+  const leaf = wrap(async function leaf() {
+    const span = tracer.startSpan('child');
+    span.setAttribute('gen_ai.system', 'openai');
+    span.end();
   });
 
-  const after = sent.find(e => e.event_type === 'after');
-  assert.ok(after, 'after event sent');
-  assert.ok(!after.response || !('text'    in after.response), 'text stripped');
-  assert.ok(!after.response || !('request' in after.response), 'request stripped');
-  assert.ok(!after.response || !('steps'   in after.response), 'steps stripped');
-  assert.ok(!after.response?.response?.body,     'response.body stripped');
-  assert.ok(!after.response?.response?.messages, 'response.messages stripped');
+  await leaf();
+  await proc.forceFlush();
+  const attrs = exporter.exported[0].attributes;
+  assert.equal(attrs['weflayr.feature_name'], 'chat');
+  assert.equal(attrs['weflayr.customer_id'], 'c_42');
+  assert.equal(attrs['weflayr.tag.experiment'], 'B');
+  await provider.shutdown();
 });
 
-test('snippet mastra_stream: stream_start + after emitted, model/usage in after via streamMiddleware', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: mastra_stream
-    const { weflayr_setup, weflayr_instrument } = require('weflayr');
-    const { Agent } = require('@mastra/core');
-    const { openai } = require('@ai-sdk/openai');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-      methods: [
-        { call: 'generate' },
-        {
-          call: 'stream',
-          streamPath: 'textStream',
-          streamMiddleware: (fullResult) => ({
-            onChunk: () => false,
-            async finalize() {
-              const rawUsage    = await fullResult.usage;
-              const rawResponse = await fullResult.response;
-              const response    = rawResponse?.status?.value ?? rawResponse;
-              return {
-                usage: rawUsage,
-                model: response?.modelId ?? null,
-              };
-            },
-          }),
-        },
-      ],
-      ignore_fields: (data) => {
-        delete data.text;
-        delete data.request;
-        delete data.steps;
-        if (data.response) {
-          delete data.response.body;
-          delete data.response.messages;
-        }
-        return data;
-      },
-    });
+test('propagateMetadata callable form runs function', async () => {
+  const { exporter, proc, provider, tracer } = _makeMetadataHarness();
 
-    const agent = weflayr_instrument(
-      new Agent({
-        name:         'my-agent',
-        model:        openai('gpt-4o-mini'),
-        instructions: 'You are a helpful assistant.',
-      })
-    );
-
-    const streamResult = await agent.stream(
-      [{ role: 'user', content: 'Hello' }],
-      { __weflayr_tags: { feature: 'chat', customer_id: '42' } },
-    );
-
-    let text = '';
-    for await (const chunk of streamResult.textStream) {
-      text += chunk;
+  const result = await weflayr.propagateMetadata(
+    {
+      featureName: 'callable',
+      customerId: 'c_42',
+      extraTags: { variant: 'A' },
+    },
+    async () => {
+      const span = tracer.startSpan('child');
+      span.setAttribute('gen_ai.system', 'openai');
+      span.end();
+      return 'done';
     }
-    // SNIPPET_END: mastra_stream
-  });
-
-  const types = sent.map(e => e.event_type);
-  assert.ok(types.includes('before'),       'before event sent');
-  assert.ok(types.includes('stream_start'), 'stream_start event sent');
-  assert.ok(types.includes('after'),        'after event sent');
-
-  const after = sent.find(e => e.event_type === 'after');
-  assert.equal(after.method, 'stream');
-  assert.equal(after.model, 'gpt-4o-mini');
-  assert.ok(after.usage, 'usage present in after event');
-  assert.equal(after.tags.feature, 'chat');
-  assert.equal(after.tags.customer_id, '42');
+  );
+
+  await proc.forceFlush();
+  assert.equal(result, 'done');
+  const attrs = exporter.exported[0].attributes;
+  assert.equal(attrs['weflayr.feature_name'], 'callable');
+  assert.equal(attrs['weflayr.tag.variant'], 'A');
+  await provider.shutdown();
 });
 
-// ---------------------------------------------------------------------------
-// Vercel AI middleware — behavioural
-// ---------------------------------------------------------------------------
-
-test('weflayr_vercel_ai_middleware: wrapGenerate sends before + after with model and tags', async () => {
-  const { weflayr_setup, weflayr_vercel_ai_middleware } = freshSDK();
-
-  weflayr_setup({ ...TEST_CREDS });
+test('propagateMetadata providerName writes attribute', async () => {
+  const { exporter, proc, provider, tracer } = _makeMetadataHarness();
 
-  const middleware = weflayr_vercel_ai_middleware({
-    model: 'openai/gpt-4o-mini',
-    tags:  { feature: 'chat' },
-  });
-
-  const sent = await captureHttp(async () => {
-    await middleware.wrapGenerate({
-      doGenerate: async () => ({
-        text: 'Hello!',
-        usage: { promptTokens: 10, completionTokens: 5 },
-        finishReason: 'stop',
-        rawCall: {}, rawResponse: {}, warnings: [],
-      }),
-      params: {},
-      model:  {},
-    });
-  });
+  await weflayr.propagateMetadata(
+    {
+      featureName: 'f',
+      customerId: 'c',
+      providerName: weflayr.AIProviderName.VERCEL_AI_GATEWAY,
+    },
+    async () => {
+      const span = tracer.startSpan('child');
+      span.setAttribute('gen_ai.system', 'openai');
+      span.end();
+    }
+  );
 
-  assert.ok(sent.some(e => e.event_type === 'before'), 'before event sent');
-  assert.ok(sent.some(e => e.event_type === 'after'),  'after event sent');
-  const before = sent.find(e => e.event_type === 'before');
-  assert.equal(before.method,        'vercel.generate');
-  assert.equal(before.args.model,    'openai/gpt-4o-mini');
-  assert.equal(before.tags.feature,  'chat');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.deepEqual(after.response.usage, { promptTokens: 10, completionTokens: 5 });
-  assert.equal(after.response.finish_reason, 'stop');
-  assert.ok(after.elapsed_ms >= 0);
+  await proc.forceFlush();
+  assert.equal(exporter.exported[0].attributes['weflayr.provider_name'], 'vercel_ai_gateway');
+  await provider.shutdown();
 });
 
-test('weflayr_vercel_ai_middleware: wrapStream sends before + stream_start + after with usage', async () => {
-  const { weflayr_setup, weflayr_vercel_ai_middleware } = freshSDK();
+// ── autoInstrument ────────────────────────────────────────────────────────────
 
-  weflayr_setup({ ...TEST_CREDS });
+function _ensureSetupDone() {
+  if (!_state.processor) weflayr.setup({ apiKey: 'test-key' });
+}
 
-  const middleware = weflayr_vercel_ai_middleware({
-    model: 'openai/gpt-4o-mini',
-    tags:  { feature: 'chat' },
-  });
+test('autoInstrument throws "install package X" when the dep is missing', async () => {
+  _ensureSetupDone();
+  await assert.rejects(
+    () => weflayr.autoInstrument({ aiSdks: weflayr.AiSdk.OPENAI }),
+    /Install it with: npm install @traceloop\/instrumentation-openai/
+  );
+});
 
-  const sent = await captureHttp(async () => {
-    const { stream } = await middleware.wrapStream({
-      doStream: async () => ({
-        stream: new ReadableStream({
-          start(ctrl) {
-            ctrl.enqueue({ type: 'text-delta', textDelta: 'Hello!' });
-            ctrl.enqueue({ type: 'finish', finishReason: 'stop', usage: { promptTokens: 10, completionTokens: 5 } });
-            ctrl.close();
-          },
-        }),
-        rawCall: {}, rawResponse: {}, warnings: [],
-      }),
-      params: {},
-      model:  {},
-    });
+test('autoInstrument rejects unknown providers', async () => {
+  // JS keeps this runtime check because `AiSdk` is a frozen object — it
+  // doesn't enforce membership at the value level the way Python's `Enum` does.
+  _ensureSetupDone();
+  await assert.rejects(() => weflayr.autoInstrument({ aiSdks: 'unicorn-llm' }), /unknown provider/);
+});
 
-    const reader = stream.getReader();
-    while (true) {
-      const { done } = await reader.read();
-      if (done) break;
+test('autoInstrument loads a stubbed Traceloop package', async () => {
+  _ensureSetupDone();
+  let constructed = false;
+  class FakeOpenAIInstrumentation {
+    constructor() {
+      constructed = true;
     }
-  });
-
-  const types = sent.map(e => e.event_type);
-  assert.ok(types.includes('before'),       'before event sent');
-  assert.ok(types.includes('stream_start'), 'stream_start event sent');
-  assert.ok(types.includes('after'),        'after event sent');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.equal(after.method, 'vercel.stream');
-  assert.deepEqual(after.response.usage, { promptTokens: 10, completionTokens: 5 });
-  assert.equal(after.response.finish_reason, 'stop');
+    enable() {}
+    disable() {}
+    setTracerProvider() {}
+    setMeterProvider() {}
+    setConfig() {}
+    getConfig() {
+      return {};
+    }
+  }
+  const origResolve = Module._resolveFilename;
+  Module._resolveFilename = function patched(req, ...rest) {
+    if (req === '@traceloop/instrumentation-openai') return req;
+    return origResolve.call(this, req, ...rest);
+  };
+  require.cache['@traceloop/instrumentation-openai'] = {
+    id: '@traceloop/instrumentation-openai',
+    filename: '@traceloop/instrumentation-openai',
+    loaded: true,
+    exports: { OpenAIInstrumentation: FakeOpenAIInstrumentation },
+  };
+  try {
+    await weflayr.autoInstrument({ aiSdks: weflayr.AiSdk.OPENAI });
+    assert.equal(constructed, true);
+  } finally {
+    Module._resolveFilename = origResolve;
+    delete require.cache['@traceloop/instrumentation-openai'];
+  }
 });
 
-test('weflayr_vercel_ai_middleware: weflayr_propagate tags appear in events', async () => {
-  const { weflayr_setup, weflayr_vercel_ai_middleware, weflayr_propagate } = freshSDK();
-
-  weflayr_setup({ ...TEST_CREDS });
-  weflayr_propagate('customer_id', 'acme-corp');
-
-  const middleware = weflayr_vercel_ai_middleware({ model: 'openai/gpt-4o-mini' });
+test('autoInstrument throws when no apiKey is reachable (env nor argument)', async () => {
+  _state.processor = null;
+  const saved = process.env.WEFLAYR_API_KEY;
+  delete process.env.WEFLAYR_API_KEY;
+  try {
+    await assert.rejects(
+      () => weflayr.autoInstrument({ aiSdks: weflayr.AiSdk.OPENAI }),
+      /apiKey.*required/
+    );
+  } finally {
+    if (saved !== undefined) process.env.WEFLAYR_API_KEY = saved;
+  }
+});
 
-  const sent = await captureHttp(async () => {
-    await middleware.wrapGenerate({
-      doGenerate: async () => ({ text: 'ok', usage: { promptTokens: 1, completionTokens: 1 }, finishReason: 'stop', rawCall: {}, rawResponse: {}, warnings: [] }),
-      params: {},
-      model:  {},
+test('autoInstrument runs setup when apiKey passed', async () => {
+  _state.processor = null;
+  class FakeOpenAIInstrumentation {
+    constructor() {}
+    enable() {}
+    disable() {}
+    setTracerProvider() {}
+    setMeterProvider() {}
+    setConfig() {}
+    getConfig() {
+      return {};
+    }
+  }
+  const origResolve = Module._resolveFilename;
+  Module._resolveFilename = function patched(req, ...rest) {
+    if (req === '@traceloop/instrumentation-openai') return req;
+    return origResolve.call(this, req, ...rest);
+  };
+  require.cache['@traceloop/instrumentation-openai'] = {
+    id: '@traceloop/instrumentation-openai',
+    filename: '@traceloop/instrumentation-openai',
+    loaded: true,
+    exports: { OpenAIInstrumentation: FakeOpenAIInstrumentation },
+  };
+  try {
+    await weflayr.autoInstrument({
+      aiSdks: weflayr.AiSdk.OPENAI,
+      apiKey: 'convenience-key',
     });
-  });
-
-  const before = sent.find(e => e.event_type === 'before');
-  assert.equal(before.tags.customer_id, 'acme-corp');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.equal(after.tags.customer_id, 'acme-corp');
+    assert.ok(_state.processor, 'processor should be installed by the embedded setup() call');
+  } finally {
+    Module._resolveFilename = origResolve;
+    delete require.cache['@traceloop/instrumentation-openai'];
+  }
 });
 
-// ---------------------------------------------------------------------------
-// Vercel AI middleware — documentation snippets
-// @ai-sdk/openai-compatible and ai are faked by Module._load at top of file.
-// ---------------------------------------------------------------------------
-
-test('snippet vercel_ai_setup: before+after via generateText, method and args correct', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: vercel_ai_setup
-    const { weflayr_setup, weflayr_vercel_ai_middleware } = require('weflayr');
-    const { wrapLanguageModel, generateText } = require('ai');
-    const { createOpenAICompatible } = require('@ai-sdk/openai-compatible');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-    });
+test('autoInstrument requires aiSdks', async () => {
+  _state.processor = null;
+  await assert.rejects(() => weflayr.autoInstrument({ apiKey: 'k' }), /`aiSdks` is required/);
+});
 
-    const provider = createOpenAICompatible({
-      name:    'openai',
-      baseURL: 'https://api.openai.com/v1',
-      headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
-    });
+// ── exporter retry ────────────────────────────────────────────────────────────
 
-    const model = wrapLanguageModel({
-      model: provider('gpt-4o-mini'),
-      middleware: weflayr_vercel_ai_middleware({
-        model: 'openai/gpt-4o-mini',
-        tags:  { env: 'production' },
-      }),
-    });
+function _failResult(status) {
+  return { code: 1, error: { code: status, message: `HTTP ${status}` } };
+}
 
-    await generateText({ model, prompt: 'Hello!' });
-    // SNIPPET_END: vercel_ai_setup
-  });
+test('exporter retries on 503 then succeeds', async () => {
+  const responses = [_failResult(503), _failResult(503), { code: 0 }];
+  let i = 0;
+  const fakeExport = (spans, cb) => cb(responses[i++]);
+  const wrapped = _exportWithRetry(fakeExport, { maxRetries: 3, maxRetryMs: 5000 });
+  const result = await new Promise((resolve) => wrapped([], resolve));
+  assert.equal(result.code, 0);
+  assert.equal(i, 3);
+});
 
-  assert.ok(sent.some(e => e.event_type === 'before'), 'before event sent');
-  assert.ok(sent.some(e => e.event_type === 'after'),  'after event sent');
-  const before = sent.find(e => e.event_type === 'before');
-  assert.equal(before.method,       'vercel.generate');
-  assert.equal(before.args.model,   'openai/gpt-4o-mini');
-  assert.equal(before.tags.env,     'production');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.ok(after.response.usage, 'usage in after event');
-  assert.ok(after.elapsed_ms >= 0);
+test('exporter does not retry on 401', async () => {
+  let calls = 0;
+  const fakeExport = (spans, cb) => {
+    calls++;
+    cb(_failResult(401));
+  };
+  const wrapped = _exportWithRetry(fakeExport, { maxRetries: 3, maxRetryMs: 5000 });
+  const result = await new Promise((resolve) => wrapped([], resolve));
+  assert.equal(result.code, 1);
+  assert.equal(result.error.code, 401);
+  assert.equal(calls, 1);
 });
 
-test('snippet vercel_ai_propagate: propagated customer_id in before+after events', async () => {
-  const { weflayr_setup, weflayr_vercel_ai_middleware } = freshSDK();
-  setSnippetEnv();
+test('exporter swallows unexpected exceptions', async () => {
+  const fakeExport = () => {
+    throw new Error('boom');
+  };
+  const wrapped = _exportWithRetry(fakeExport, { maxRetries: 1, maxRetryMs: 5000 });
+  const result = await new Promise((resolve) => wrapped([], resolve));
+  assert.equal(result.code, 1);
+});
 
-  const { wrapLanguageModel, generateText } = require('ai');
-  const { createOpenAICompatible } = require('@ai-sdk/openai-compatible');
+test('exporter gives up after maxRetries on persistent 503', async () => {
+  let calls = 0;
+  const fakeExport = (spans, cb) => {
+    calls++;
+    cb(_failResult(503));
+  };
+  const wrapped = _exportWithRetry(fakeExport, { maxRetries: 3, maxRetryMs: 5000 });
+  const result = await new Promise((resolve) => wrapped([], resolve));
+  assert.equal(result.code, 1);
+  assert.equal(result.error.code, 503);
+  assert.equal(calls, 3);
+});
 
-  weflayr_setup({ ...TEST_CREDS });
+// ── OpenAI streaming usage backfill ─────────────────────────────────────────────
 
-  const provider = createOpenAICompatible({ name: 'openai', baseURL: 'https://api.openai.com/v1', headers: {} });
-  const model = wrapLanguageModel({
-    model: provider('gpt-4o-mini'),
-    middleware: weflayr_vercel_ai_middleware({ model: 'openai/gpt-4o-mini' }),
-  });
+// Build a fake OpenAI instrumentor whose streaming handler mimics traceloop's:
+// it yields content chunks, then a final usage chunk (as OpenAI sends when
+// `stream_options.include_usage` is set) without recording usage itself. The
+// patch should read the usage chunk and set the token attributes on the span.
+function makeFakeOpenAIInstrumentation() {
+  return {
+    _streamingWrapPromise() {
+      return (async function* originalStream() {
+        yield { id: 'chatcmpl-1', model: 'gpt-4o-mini', choices: [{ delta: { content: 'Hi' } }] };
+        yield {
+          id: 'chatcmpl-1',
+          model: 'gpt-4o-mini',
+          choices: [],
+          usage: { prompt_tokens: 13, completion_tokens: 2, total_tokens: 15 },
+        };
+      })();
+    },
+  };
+}
 
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: vercel_ai_propagate
-    const { weflayr_propagate } = require('weflayr');
+test('patchOpenAIStreamingUsage sets token attributes from the streamed usage chunk', async () => {
+  const span = makeFakeSpan();
+  const instrumentation = makeFakeOpenAIInstrumentation();
+  patchOpenAIStreamingUsage(instrumentation);
 
-    weflayr_propagate('customer_id', 'acme-corp');
-    await generateText({ model, prompt: 'Hello!' });
-    // SNIPPET_END: vercel_ai_propagate
-  });
+  const stream = instrumentation._streamingWrapPromise({ span });
+  for await (const chunk of stream) void chunk;
 
-  const before = sent.find(e => e.event_type === 'before');
-  assert.ok(before, 'before event sent');
-  assert.equal(before.tags.customer_id, 'acme-corp');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.equal(after.tags.customer_id, 'acme-corp');
+  assert.equal(span.attributes['gen_ai.usage.input_tokens'], 13);
+  assert.equal(span.attributes['gen_ai.usage.output_tokens'], 2);
+  assert.equal(span.attributes['gen_ai.usage.total_tokens'], 15);
 });
 
-test('snippet vercel_ai_stream: before + stream_start + after via streamText', async () => {
-  freshSDK();
-  setSnippetEnv();
-
-  const sent = await captureHttp(async () => {
-    // SNIPPET_START: vercel_ai_stream
-    const { weflayr_setup, weflayr_vercel_ai_middleware } = require('weflayr');
-    const { wrapLanguageModel, streamText } = require('ai');
-    const { createOpenAICompatible } = require('@ai-sdk/openai-compatible');
-
-    weflayr_setup({
-      intake_url:    process.env.WEFLAYR_INTAKE_URL,
-      client_id:     process.env.WEFLAYR_CLIENT_ID,
-      client_secret: process.env.WEFLAYR_CLIENT_SECRET,
-    });
-
-    const provider = createOpenAICompatible({
-      name:    'openai',
-      baseURL: 'https://api.openai.com/v1',
-      headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
-    });
-
-    const model = wrapLanguageModel({
-      model: provider('gpt-4o-mini'),
-      middleware: weflayr_vercel_ai_middleware({
-        model: 'openai/gpt-4o-mini',
-        tags:  { feature: 'chat' },
-      }),
-    });
+test('patchOpenAIStreamingUsage is a no-op when the streaming handler is absent', () => {
+  const instrumentation = {};
+  patchOpenAIStreamingUsage(instrumentation);
+  assert.equal(instrumentation._streamingWrapPromise, undefined);
+});
 
-    const { textStream } = streamText({ model, prompt: 'Hello!' });
-    for await (const _chunk of textStream) {}
-    // SNIPPET_END: vercel_ai_stream
-  });
+// ── flush ─────────────────────────────────────────────────────────────────────
 
-  const types = sent.map(e => e.event_type);
-  assert.ok(types.includes('before'),       'before event sent');
-  assert.ok(types.includes('stream_start'), 'stream_start event sent');
-  assert.ok(types.includes('after'),        'after event sent');
-  const after = sent.find(e => e.event_type === 'after');
-  assert.equal(after.method,       'vercel.stream');
-  assert.equal(after.tags.feature, 'chat');
-  assert.ok(after.response.usage,  'usage in after event');
+test('flush does not throw', async () => {
+  await weflayr.flush();
 });
+
+void trace;