dd-trace 5.117.0 → 5.118.0

package/ci/test-optimization-validation/scenarios/early-flake-detection.js

@@ -7,6 +7,7 @@ const {
   failWithDebugRerun,
   pass,
   prepareGeneratedScenario,
+  reportMissingGeneratedTest,
   requireGeneratedScenario,
   runInstrumentedCommand,
   skip,
@@ -28,14 +29,14 @@ async function runEarlyFlakeDetection ({ framework, out, options }) {
 
     const discovery = await discoverScenarioTests({ framework, out, scenarioName, scenario, options })
     if (discovery.tests.length === 0) {
-      return failWithDebugRerun({
+      return reportMissingGeneratedTest({
         command: scenario.runCommand,
         diagnosis: 'The generated new-test candidate was not reported during baseline identity discovery.',
-        evidence: discoveryEvidence(discovery),
+        discovery,
         framework,
         options,
         out,
-        outDir: discovery.outDir,
+        scenario,
         scenarioName,
       })
     }

package/ci/test-optimization-validation/scenarios/helpers.js

@@ -4,7 +4,7 @@ const fs = require('node:fs')
 const path = require('path')
 
 const { getArtifactId } = require('../artifact-id')
-const { buildCiWiringEnv, buildDatadogEnv, runCommand } = require('../command-runner')
+const { buildDatadogEnv, buildOfflineCaptureEnv, runCommand } = require('../command-runner')
 const {
   cleanupGeneratedRuntimeFiles,
   findGeneratedScenario,
@@ -14,10 +14,10 @@ const {
   eventsOfType,
   findTestsByIdentity,
 } = require('../payload-normalizer')
-const { getLocalValidationCommand } = require('../local-command')
 const { cleanupOfflineFixture, createOfflineFixture } = require('../offline-fixtures')
 const { readOfflineOutput } = require('../offline-output')
 const { sanitizeForReport, sanitizeString } = require('../redaction')
+const { getGeneratedCommand } = require('../runner-command')
 const { ensureSafeDirectory, writeFileSafely } = require('../safe-files')
 
 const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}${String.raw`\[[0-?]*[ -/]*[@-~]`}`, 'g')
@@ -34,7 +34,7 @@ async function runInstrumentedCommand ({
   options,
   extraEnv,
   fixtureConfig,
-  ciWiring = false,
+  injectInitialization = true,
   allowMissingInitialization = false,
 }) {
   const outDir = frameworkOutDir(out, framework, scenarioName)
@@ -52,9 +52,9 @@ async function runInstrumentedCommand ({
       scenarioName,
       ...fixtureConfig,
     })
-    const validationEnv = ciWiring
-      ? buildCiWiringEnv({ fixture, outputRoot: rawOutputRoot })
-      : buildDatadogEnv({ fixture, outputRoot: rawOutputRoot, scenario: scenarioName, framework })
+    const validationEnv = injectInitialization
+      ? buildDatadogEnv({ fixture, outputRoot: rawOutputRoot, scenario: scenarioName, framework })
+      : buildOfflineCaptureEnv({ fixture, outputRoot: rawOutputRoot })
     result = await runCommand(command, {
       env: {
         ...validationEnv,
@@ -82,7 +82,7 @@ async function runInstrumentedCommand ({
       `${JSON.stringify(sanitizeForReport(result), null, 2)}\n`,
       'scenario result artifact'
     )
-    if (!offline.initialized && !ciWiring && !allowMissingInitialization) {
+    if (!offline.initialized && injectInitialization && !allowMissingInitialization) {
       const stderr = sanitizeString(result.stderr).trim().slice(-2000)
       throw new Error(
         'Offline Test Optimization exporter did not initialize or write completion evidence. ' +
@@ -180,11 +180,11 @@ async function prepareGeneratedScenario (framework, scenarioId) {
   const scenario = findGeneratedScenario(framework, scenarioId)
   if (!scenario) return { scenario: null, written: [] }
   cleanupGeneratedRuntimeFiles(framework)
-  const written = await writeGeneratedFiles(framework)
+  const written = await writeGeneratedFiles(framework, scenario)
   return {
     scenario: {
       ...scenario,
-      runCommand: getLocalValidationCommand(framework, scenario.runCommand),
+      runCommand: getGeneratedCommand(framework, scenario),
     },
     written,
   }
@@ -314,6 +314,63 @@ async function discoverScenarioTests ({ framework, out, scenarioName, scenario,
   }
 }
 
+/**
+ * Reports a missing generated test without blaming dd-trace when clean execution was unproven.
+ *
+ * @param {object} input missing-test evidence
+ * @param {object} input.command generated scenario command
+ * @param {string} input.diagnosis diagnosis used when clean execution was proven
+ * @param {object} input.discovery instrumented baseline result
+ * @param {object} input.framework framework manifest entry
+ * @param {object} input.options execution options
+ * @param {string} input.out validation output root
+ * @param {object} input.scenario generated scenario
+ * @param {string} input.scenarioName advanced scenario name
+ * @returns {object|Promise<object>} incomplete or confirmed failure result
+ */
+function reportMissingGeneratedTest ({
+  command,
+  diagnosis,
+  discovery,
+  framework,
+  options,
+  out,
+  scenario,
+  scenarioName,
+}) {
+  const verification = framework.generatedTestStrategy?.verification?.observedScenarios
+    ?.find(observed => observed.id === scenario.id)
+  const evidence = {
+    ...discoveryEvidence(discovery),
+    generatedVerificationObservedTestCount: verification?.observedTestCount,
+  }
+  if (verification?.observedTestCount === null) {
+    return inconclusive(
+      framework,
+      scenarioName,
+      'The clean temporary validation command exited as expected without a parseable test count, and the ' +
+        'instrumented baseline emitted no matching test event. The validator cannot prove that the generated test ' +
+        'executed, so no advanced-feature conclusion was reached.',
+      {
+        ...evidence,
+        reasonCode: 'generated-test-execution-unproven',
+      },
+      discovery.outDir
+    )
+  }
+
+  return failWithDebugRerun({
+    command,
+    diagnosis,
+    evidence,
+    framework,
+    options,
+    out,
+    outDir: discovery.outDir,
+    scenarioName,
+  })
+}
+
 function testsForDiscoveredScenario (events, scenario, discovery) {
   if (discovery?.testIdentities?.length > 0) {
     return findTestsByIdentity(events, discovery.testIdentities)
@@ -528,6 +585,7 @@ module.exports = {
   inconclusive,
   pass,
   prepareGeneratedScenario,
+  reportMissingGeneratedTest,
   requireGeneratedScenario,
   runDebugInstrumentedCommand,
   runInstrumentedCommand,

package/ci/test-optimization-validation/scenarios/test-management.js

@@ -9,6 +9,7 @@ const {
   failWithDebugRerun,
   pass,
   prepareGeneratedScenario,
+  reportMissingGeneratedTest,
   requireGeneratedScenario,
   runInstrumentedCommand,
   testEventSamples,
@@ -25,14 +26,14 @@ async function runTestManagement ({ framework, out, options }) {
     const { scenario } = await prepareGeneratedScenario(framework, 'test-management-target')
     const discovery = await discoverScenarioTests({ framework, out, scenarioName, scenario, options })
     if (discovery.tests.length === 0) {
-      return failWithDebugRerun({
+      return reportMissingGeneratedTest({
         command: scenario.runCommand,
         diagnosis: 'The test-management target was not reported during baseline identity discovery.',
-        evidence: discoveryEvidence(discovery),
+        discovery,
         framework,
         options,
         out,
-        outDir: discovery.outDir,
+        scenario,
         scenarioName,
       })
     }

package/ci/test-optimization-validation/source-text.js

@@ -0,0 +1,87 @@
+'use strict'
+
+/**
+ * Replaces JavaScript comments with spaces while preserving line structure and string literals.
+ *
+ * @param {string} source JavaScript or TypeScript source
+ * @returns {string} source with comments masked
+ */
+function maskJavaScriptComments (source) {
+  return maskJavaScriptSource(source, false)
+}
+
+/**
+ * Replaces JavaScript comments and string literals with spaces while preserving line structure.
+ *
+ * @param {string} source JavaScript or TypeScript source
+ * @returns {string} source with non-code text masked
+ */
+function maskJavaScriptNonCode (source) {
+  return maskJavaScriptSource(source, true)
+}
+
+/**
+ * Masks comments and optionally string literals in JavaScript-like source.
+ *
+ * @param {string} source JavaScript or TypeScript source
+ * @param {boolean} maskStrings whether string and template literal contents should be masked
+ * @returns {string} masked source
+ */
+function maskJavaScriptSource (source, maskStrings) {
+  const characters = [...source]
+  let blockComment = false
+  let lineComment = false
+  let quote = ''
+
+  for (let index = 0; index < characters.length; index++) {
+    const character = characters[index]
+    const next = characters[index + 1]
+    if (lineComment) {
+      if (character === '\n') {
+        lineComment = false
+      } else {
+        characters[index] = ' '
+      }
+      continue
+    }
+    if (blockComment) {
+      if (character === '*' && next === '/') {
+        characters[index] = ' '
+        characters[++index] = ' '
+        blockComment = false
+      } else if (character !== '\r' && character !== '\n') {
+        characters[index] = ' '
+      }
+      continue
+    }
+    if (quote) {
+      if (maskStrings && character !== '\r' && character !== '\n') characters[index] = ' '
+      if (character.charCodeAt(0) === 92) {
+        if (maskStrings && index + 1 < characters.length &&
+          characters[index + 1] !== '\r' && characters[index + 1] !== '\n') {
+          characters[index + 1] = ' '
+        }
+        index++
+      } else if (character === quote) {
+        quote = ''
+      }
+      continue
+    }
+    if (character === '"' || character === '\'' || character === '`') {
+      quote = character
+      if (maskStrings) characters[index] = ' '
+    } else if (character === '/' && next === '/') {
+      characters[index] = ' '
+      characters[++index] = ' '
+      lineComment = true
+    } else if (character === '/' && next === '*') {
+      characters[index] = ' '
+      characters[++index] = ' '
+      blockComment = true
+    }
+  }
+
+  return characters.join('')
+}
+
+module.exports = { maskJavaScriptComments, maskJavaScriptNonCode }

package/ci/test-optimization-validation/test-output.js

@@ -1,5 +1,9 @@
 'use strict'
 
+const cypressAdapter = require('./framework-adapters/cypress')
+const cucumberAdapter = require('./framework-adapters/cucumber')
+const playwrightAdapter = require('./framework-adapters/playwright')
+
 const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}${String.raw`\[[0-?]*[ -/]*[@-~]`}`, 'g')
 
 /**
@@ -11,16 +15,14 @@ const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}${String.raw`\[[0-?]*
  * @returns {number|null} observed count when a supported summary was found
  */
 function getObservedTestCount (framework, stdout = '', stderr = '') {
-  const output = `${stdout}\n${stderr}`.replaceAll(ANSI_PATTERN, '')
+  const output = stripAnsi(`${stdout}\n${stderr}`)
+  if (framework === 'cucumber') return cucumberAdapter.getObservedTestCount(output)
+  if (framework === 'cypress') return cypressAdapter.getObservedTestCount(output)
+  if (framework === 'playwright') return playwrightAdapter.getObservedTestCount(output)
   if (framework === 'jest') return getJestObservedTestCount(output)
   if (framework === 'vitest') return getVitestObservedTestCount(output)
-  if (framework === 'playwright') return getPlaywrightObservedTestCount(output)
 
-  const totalPatterns = framework === 'node:test'
-    ? [/^# tests\s+(\d+)\s*$/gim]
-    : framework === 'cucumber'
-      ? [/\b(\d+)\s+scenarios?\b/gi]
-      : []
+  const totalPatterns = framework === 'node:test' ? [/^# tests\s+(\d+)\s*$/gim] : []
 
   for (const pattern of totalPatterns) {
     const count = getLastMatchCount(output, pattern)
@@ -38,20 +40,8 @@ function getObservedTestCount (framework, stdout = '', stderr = '') {
   return getLastMatchCount(output, /\b(\d+)\s+tests?\s+(?:passed|failed)\b/gi)
 }
 
-/**
- * Counts Playwright tests that completed instead of treating skipped tests as executions.
- *
- * @param {string} output test output without ANSI codes
- * @returns {number|null} executed test count
- */
-function getPlaywrightObservedTestCount (output) {
-  const observed = sumLastMatchCounts(output, [
-    /^\s*(\d+)\s+passed\b/gim,
-    /^\s*(\d+)\s+failed\b/gim,
-    /^\s*(\d+)\s+flaky\b/gim,
-  ])
-  if (observed !== null) return observed
-  return /^\s*\d+\s+skipped\b/im.test(output) ? 0 : null
+function stripAnsi (value) {
+  return String(value || '').replaceAll(ANSI_PATTERN, '')
 }
 
 /**
@@ -126,4 +116,4 @@ function sumLastMatchCounts (output, patterns) {
   return found ? count : null
 }
 
-module.exports = { getObservedTestCount }
+module.exports = { getObservedTestCount, stripAnsi }

package/ext/tags.d.ts

@@ -20,6 +20,7 @@ declare const tags: {
   HTTP_RESPONSE_HEADERS: 'http.response.headers'
   HTTP_USERAGENT: 'http.useragent',
   HTTP_CLIENT_IP: 'http.client_ip',
+  GRPC_STATUS_CODE: 'grpc.status.code'
   PATHWAY_HASH: 'pathway.hash'
 }
 

package/index.d.ts

@@ -293,6 +293,7 @@ interface Plugins {
   "next": tracer.plugins.next;
   "nyc": tracer.plugins.nyc;
   "openai": tracer.plugins.openai;
+  "openai-agents": tracer.plugins.openai_agents;
   "opensearch": tracer.plugins.opensearch;
   "oracledb": tracer.plugins.oracledb;
   "playwright": tracer.plugins.playwright;
@@ -3138,6 +3139,12 @@ declare namespace tracer {
      */
     interface openai extends Instrumentation {}
 
+    /**
+     * This plugin automatically instruments the
+     * [@openai/agents](https://www.npmjs.com/package/@openai/agents) library.
+     */
+    interface openai_agents extends Instrumentation {}
+
     /**
      * This plugin automatically instruments the
      * [opensearch](https://github.com/opensearch-project/opensearch-js) module.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dd-trace",
-  "version": "5.117.0",
+  "version": "5.118.0",
   "description": "Datadog APM tracing client for JavaScript",
   "main": "index.js",
   "typings": "index.d.ts",
@@ -198,7 +198,7 @@
     "@types/mocha": "^10.0.10",
     "@types/node": "^18.19.106",
     "@types/sinon": "^22.0.0",
-    "@vercel/nft": "^0.29.4",
+    "@vercel/nft": "^1.10.2",
     "axios": "^1.18.1",
     "benchmark": "^2.1.4",
     "body-parser": "^2.3.0",

package/packages/datadog-instrumentations/src/helpers/hooks.js

@@ -21,6 +21,8 @@ module.exports = {
   '@apollo/gateway': () => require('../apollo'),
   '@langchain/langgraph': { esmFirst: true, fn: () => require('../langgraph') },
   '@modelcontextprotocol/sdk': { esmFirst: true, fn: () => require('../modelcontextprotocol-sdk') },
+  '@openai/agents': () => require('../openai-agents'),
+  '@openai/agents-openai': () => require('../openai-agents'),
   'apollo-server-core': () => require('../apollo-server-core'),
   '@aws-sdk/smithy-client': () => require('../aws-sdk'),
   '@aws/durable-execution-sdk-js': () => require('../aws-durable-execution-sdk-js'),

package/packages/datadog-instrumentations/src/helpers/rewriter/instrumentations/index.js

@@ -10,6 +10,7 @@ module.exports = [
   ...require('./langgraph'),
   ...require('./mercurius'),
   ...require('./modelcontextprotocol-sdk'),
+  ...require('./openai-agents'),
   ...require('./playwright'),
   ...require('./aws-durable-execution-sdk-js'),
 ]

package/packages/datadog-instrumentations/src/helpers/rewriter/instrumentations/openai-agents.js

@@ -0,0 +1,31 @@
+'use strict'
+
+const moduleName = '@openai/agents-openai'
+const versionRange = '>=0.7.0'
+const functionQuery = {
+  methodName: 'constructor',
+  className: 'OpenAIChatCompletionsModel',
+  kind: 'Sync',
+}
+const channelName = 'OpenAIChatCompletionsModel_constructor'
+
+module.exports = [
+  {
+    module: {
+      name: moduleName,
+      versionRange,
+      filePath: 'dist/openaiChatCompletionsModel.js',
+    },
+    functionQuery,
+    channelName,
+  },
+  {
+    module: {
+      name: moduleName,
+      versionRange,
+      filePath: 'dist/openaiChatCompletionsModel.mjs',
+    },
+    functionQuery,
+    channelName,
+  },
+]

package/packages/datadog-instrumentations/src/openai-agents.js

@@ -0,0 +1,159 @@
+'use strict'
+
+const { channel, tracingChannel } = require('dc-polyfill')
+const shimmer = require('../../datadog-shimmer')
+const { addHook, getHooks } = require('./helpers/instrument')
+
+// `WeakSet` keyed by module exports — replaces the underscored
+// `mod._datadogPatched` flag while keeping dedupe semantics. Mods are kept
+// alive by `require.cache` anyway, so this doesn't add lifetime to anything.
+const patchedMods = new WeakSet()
+const modelBaseURLs = new WeakMap()
+const chatCompletionsModelConstructorCh =
+  tracingChannel('orchestrion:@openai/agents-openai:OpenAIChatCompletionsModel_constructor')
+
+/**
+ * Capture the client base URL before the SDK stores the client in a #private field.
+ *
+ * @param {{ arguments?: [{ baseURL?: string }], self?: object }} ctx
+ */
+function captureChatCompletionsModelBaseURL (ctx) {
+  const baseURL = ctx.arguments?.[0]?.baseURL
+  if (ctx.self && typeof baseURL === 'string') modelBaseURLs.set(ctx.self, baseURL)
+}
+
+chatCompletionsModelConstructorCh.end.subscribe(captureChatCompletionsModelBaseURL)
+
+for (const hook of getHooks('@openai/agents-openai')) {
+  addHook(hook, moduleExports => moduleExports)
+}
+
+// Plugin subscribes to this and registers its TracingProcessor when
+// `@openai/agents` loads. Publishing from here keeps this file free of
+// any cross-package import from the plugin.
+const agentsCoreLoadedCh = channel('apm:openai-agents:agents-core:loaded')
+
+// Plugin uses addBind on this channel so that legacyStorage.run(store, fn) wraps
+// the model call — including async iterator advancement for streaming responses.
+// This ensures the active dd-trace span is visible to the openai plugin when it
+// creates its openai.request span, correctly parenting it under the agent span.
+const modelStartCh = channel('apm:openai-agents:model:start')
+
+// Tool.invoke runs inside agents-core's public function-span context. Bind the
+// corresponding dd-trace tool span around that public invocation boundary so
+// spans created by user tool code inherit it.
+const toolStartCh = channel('apm:openai-agents:tool:start')
+
+// Reference to the loaded @openai/agents module, captured in the first hook
+// so that wrapResponseMethod can call getCurrentSpan() without an additional
+// require (and without triggering n/no-missing-require on agents-core internals).
+let agentsMod
+
+// @openai/agents >=0.8.0 moved addTraceProcessor / getCurrentSpan out of the
+// top-level re-exports.  The new public surface uses getGlobalTraceProvider():
+//   provider.registerProcessor(processor)  (replaces addTraceProcessor)
+//   provider.getCurrentSpan()              (replaces getCurrentSpan)
+// Both APIs are tried so this file works across the full supported version range.
+// The plugin subscriber (index.js) handles processor registration via the channel.
+function getCurrentSpan () {
+  if (typeof agentsMod?.getCurrentSpan === 'function') {
+    return agentsMod.getCurrentSpan()
+  }
+  if (typeof agentsMod?.getGlobalTraceProvider === 'function') {
+    return agentsMod.getGlobalTraceProvider().getCurrentSpan()
+  }
+}
+
+function getCurrentSpanId () {
+  return getCurrentSpan()?.spanId
+}
+
+addHook({ name: '@openai/agents', versions: ['>=0.7.0'] }, (mod) => {
+  if (patchedMods.has(mod)) return mod
+  if (typeof mod?.addTraceProcessor !== 'function' && typeof mod?.getGlobalTraceProvider !== 'function') return mod
+  patchedMods.add(mod)
+  agentsMod = mod
+  if (typeof mod.tool === 'function') {
+    shimmer.wrap(mod, 'tool', wrapToolFactory, { replaceGetter: true })
+  }
+  agentsCoreLoadedCh.publish({ mod })
+  return mod
+})
+
+function wrapToolFactory (original) {
+  return function (...args) {
+    const tool = original.apply(this, args)
+    if (typeof tool?.invoke === 'function') {
+      shimmer.wrap(tool, 'invoke', wrapToolInvoke)
+    }
+    return tool
+  }
+}
+
+function wrapToolInvoke (original) {
+  return function (...args) {
+    const agentsCoreSpan = getCurrentSpan()
+    return toolStartCh.runStores({ agentsCoreSpan }, () => original.apply(this, args))
+  }
+}
+
+function wrapResponseMethod (original) {
+  return function (...args) {
+    const agentsCoreSpanId = getCurrentSpanId()
+    const baseURL = getClientBaseURL(this)
+    return modelStartCh.runStores({ agentsCoreSpanId, baseURL }, () => original.apply(this, args))
+  }
+}
+
+function wrapStreamedResponseMethod (original) {
+  return function (...args) {
+    const agentsCoreSpanId = getCurrentSpanId()
+    const baseURL = getClientBaseURL(this)
+    const context = { agentsCoreSpanId, baseURL }
+    const iterator = modelStartCh.runStores(context, () => original.apply(this, args))
+    return wrapAsyncIterator(iterator, context)
+  }
+}
+
+function getClientBaseURL (model) {
+  return model?.client?.baseURL ?? model?._client?.baseURL ?? modelBaseURLs.get(model)
+}
+
+function wrapAsyncIterator (iterator, context) {
+  if (!iterator || typeof iterator !== 'object') return iterator
+
+  return {
+    next () {
+      return modelStartCh.runStores(context, () => iterator.next.apply(iterator, arguments))
+    },
+    throw () {
+      if (typeof iterator.throw !== 'function') return Promise.reject(arguments[0])
+      return modelStartCh.runStores(context, () => iterator.throw.apply(iterator, arguments))
+    },
+    return () {
+      if (typeof iterator.return !== 'function') return Promise.resolve({ done: true, value: arguments[0] })
+      return modelStartCh.runStores(context, () => iterator.return.apply(iterator, arguments))
+    },
+    [Symbol.asyncIterator] () {
+      return this
+    },
+  }
+}
+
+addHook({ name: '@openai/agents-openai', versions: ['>=0.7.0'] }, (mod) => {
+  if (patchedMods.has(mod)) return mod
+  const responseProto = mod?.OpenAIResponsesModel?.prototype
+  const chatCompletionsProto = mod?.OpenAIChatCompletionsModel?.prototype
+  if (!responseProto && !chatCompletionsProto) return mod
+
+  patchedMods.add(mod)
+  for (const proto of [responseProto, chatCompletionsProto]) {
+    if (typeof proto?.getResponse === 'function') {
+      shimmer.wrap(proto, 'getResponse', wrapResponseMethod)
+    }
+    if (typeof proto?.getStreamedResponse === 'function') {
+      shimmer.wrap(proto, 'getStreamedResponse', wrapStreamedResponseMethod)
+    }
+  }
+  return mod
+})

package/packages/datadog-plugin-openai-agents/src/index.js

@@ -0,0 +1,74 @@
+'use strict'
+
+const { storage } = require('../../datadog-core')
+const Plugin = require('../../dd-trace/src/plugins/plugin')
+const { MODEL_BASE_URL_STORE_KEY, OpenAIAgentsIntegration } = require('./integration')
+const { DDOpenAIAgentsProcessor } = require('./processor')
+
+const legacyStorage = storage('legacy')
+
+/**
+ * Drives the openai-agents integration through agents-core's
+ * `TracingProcessor` interface. The instrumentation hook publishes the
+ * loaded `@openai/agents` module on a channel; this plugin subscribes
+ * during its constructor (which runs synchronously between `loadChannel`'s
+ * publish and the addHook callback) and registers the processor.
+ *
+ * The integration's `enabled` flag follows this plugin's configure()
+ * lifecycle. Each loaded version of the agents package replaces all processors
+ * via setTraceProcessors() on module load, so the plugin re-registers a
+ * fresh DDOpenAIAgentsProcessor for each module version that fires the channel.
+ */
+class OpenaiAgentsPlugin extends Plugin {
+  static id = 'openai-agents'
+
+  #integration
+
+  constructor (tracer, tracerConfig) {
+    super(tracer, tracerConfig)
+    this.#integration = new OpenAIAgentsIntegration({
+      tracer: this.tracer,
+      config: tracerConfig,
+    })
+
+    // Register a new processor each time @openai/agents fires the channel.
+    // Each module version calls setTraceProcessors() on load (which replaces
+    // all processors), so we must re-register after every new version loads.
+    // The instrumentation's patchedMods WeakSet ensures each module instance
+    // fires the channel exactly once, so no duplicates accumulate.
+    this.addSub('apm:openai-agents:agents-core:loaded', ({ mod }) => {
+      const processor = new DDOpenAIAgentsProcessor(() => this.#integration)
+      if (typeof mod?.addTraceProcessor === 'function') {
+        mod.addTraceProcessor(processor)
+      } else {
+        mod.getGlobalTraceProvider().registerProcessor(processor)
+      }
+    })
+
+    // Activate the current agent's dd-trace span in legacyStorage for the
+    // duration of model response calls and stream iterator advancement. This
+    // makes the openai plugin's shimmer see the correct parent when it creates its
+    // openai.request span, so all spans land in the same trace.
+    this.addBind('apm:openai-agents:model:start', ({ agentsCoreSpanId, baseURL }) => {
+      const store = legacyStorage.getStore()
+      if (!this.#integration.enabled || !agentsCoreSpanId) return store
+      const ddSpan = this.#integration.getDDSpan(agentsCoreSpanId)
+      if (!ddSpan) return store
+      return { ...store, [MODEL_BASE_URL_STORE_KEY]: baseURL, span: ddSpan }
+    })
+
+    this.addBind('apm:openai-agents:tool:start', ({ agentsCoreSpan }) => {
+      const store = legacyStorage.getStore()
+      if (!this.#integration.enabled || !agentsCoreSpan) return store
+      const ddSpan = this.#integration.getOrStartToolSpan(agentsCoreSpan)
+      return ddSpan ? { ...store, span: ddSpan } : store
+    })
+  }
+
+  configure (config) {
+    super.configure(config)
+    this.#integration.configure(config)
+  }
+}
+
+module.exports = OpenaiAgentsPlugin