dd-trace 6.9.0 → 6.11.0

package/packages/dd-trace/src/llmobs/experiments/noop.js

@@ -1,13 +1,20 @@
 'use strict'
 
 const log = require('../../log')
+const { ExternalExperiment } = require('./experiment')
+
+const NOOP_EXPERIMENT_ID = '00000000-0000-0000-0000-000000000000'
+const NOOP_SPAN_ID = '0000000000000000'
+const NOOP_TRACE_ID = '00000000000000000000000000000000'
 
 class NoopDataset {
   #name
+  #description
   #records
 
   constructor (name = '', options = {}) {
     this.#name = name
+    this.#description = typeof options === 'string' ? options : (options.description ?? '')
     this.#records = (typeof options === 'string' ? [] : (options.records ?? [])).map(record => ({
       id: record.id ?? null,
       input: record.inputData,
@@ -21,6 +28,20 @@ class NoopDataset {
     return this
   }
 
+  update (index, fields) {
+    const record = this.#records[index]
+    if (record == null) return this
+    if (Object.hasOwn(fields, 'input')) record.input = fields.input
+    if (Object.hasOwn(fields, 'expectedOutput')) record.expectedOutput = fields.expectedOutput ?? null
+    if (Object.hasOwn(fields, 'metadata')) record.metadata = fields.metadata ?? {}
+    return this
+  }
+
+  delete (index) {
+    this.#records.splice(index, 1)
+    return this
+  }
+
   push () {
     return Promise.resolve({ pushedCount: 0, totalCount: 0 })
   }
@@ -29,6 +50,10 @@ class NoopDataset {
     return this.#name
   }
 
+  description () {
+    return this.#description
+  }
+
   id () {
     return null
   }
@@ -60,9 +85,11 @@ class NoopDataset {
 
 class NoopExperiment {
   #name
+  #external
 
-  constructor (name = '') {
+  constructor (name = '', external = false) {
     this.#name = name
+    this.#external = external
   }
 
   name () {
@@ -70,7 +97,7 @@ class NoopExperiment {
   }
 
   experimentId () {
-    return null
+    return this.#external ? NOOP_EXPERIMENT_ID : null
   }
 
   url () {
@@ -80,6 +107,32 @@ class NoopExperiment {
   run () {
     return Promise.resolve({ experimentId: null, rows: [], url: null })
   }
+
+  /**
+   * @returns {Promise<{experimentId: string, spanId: string, traceId: string, url: null}>}
+   */
+  submitSpan () {
+    return Promise.resolve({
+      experimentId: NOOP_EXPERIMENT_ID,
+      spanId: NOOP_SPAN_ID,
+      traceId: NOOP_TRACE_ID,
+      url: null,
+    })
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  submitEvaluationMetrics () {
+    return Promise.resolve()
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  close () {
+    return Promise.resolve()
+  }
 }
 
 // No-op Experiments used when LLM Observability is disabled or the API/APP keys
@@ -87,9 +140,11 @@ class NoopExperiment {
 // throwing, so intentionally disabled experiments remain graceful.
 class NoopExperiments {
   #reason
+  #startExperiment
 
-  constructor (reason) {
+  constructor (reason, options = {}) {
     this.#reason = reason || 'LLMObs experiments are not available'
+    this.#startExperiment = options.startExperiment
   }
 
   #warn () {
@@ -110,6 +165,19 @@ class NoopExperiments {
     this.#warn()
     return new NoopExperiment(options.name)
   }
+
+  /**
+   * @param {object} options
+   * @returns {Promise<ExternalExperiment>}
+   */
+  startExperiment (options = {}) {
+    if (this.#startExperiment !== undefined && options.projectName) {
+      return this.#startExperiment(options)
+    }
+
+    this.#warn()
+    return Promise.resolve(new ExternalExperiment(new NoopExperiment(options.name, true)))
+  }
 }
 
 module.exports = NoopExperiments

package/packages/dd-trace/src/llmobs/experiments/result.js

@@ -13,6 +13,7 @@ class Row {
     this.expectedOutput = fields.expectedOutput
     this.errorType = fields.errorType
     this.errorMessage = fields.errorMessage
+    this.errorStack = fields.errorStack
     this.evaluations = fields.evaluations
     this.evaluationErrors = fields.evaluationErrors
   }

package/packages/dd-trace/src/llmobs/experiments/util.js

@@ -178,12 +178,12 @@ function buildTags (userTags, autoTags) {
 }
 
 /**
- * @param {Record<string, unknown> | undefined} userTags
- * @param {Record<string, unknown>} autoTags
+ * @param {Record<string, unknown> | undefined} baseTags
+ * @param {Record<string, unknown> | undefined} overrideTags
  * @returns {Record<string, unknown>}
  */
-function buildExperimentTagObject (userTags, autoTags) {
-  return userTags ? { ...userTags, ...autoTags } : { ...autoTags }
+function mergeTags (baseTags, overrideTags) {
+  return { ...baseTags, ...overrideTags }
 }
 
 /**
@@ -195,6 +195,40 @@ function sleep (ms) {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function timestampMs (value, fallback = Date.now()) {
+  if (value === null || value === undefined) return fallback
+  if (value instanceof Date) {
+    const timestamp = value.getTime()
+    return Number.isFinite(timestamp) ? timestamp : fallback
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  const parsed = Date.parse(String(value))
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+/**
+ * @param {{ durationMs?: unknown, completedAt?: unknown }} row
+ * @param {number} startMs
+ * @returns {number}
+ */
+function durationNs (row, startMs) {
+  if (typeof row.durationMs === 'number' && Number.isFinite(row.durationMs)) {
+    return Math.max(0, Math.round(row.durationMs * 1e6))
+  }
+
+  if (row.completedAt !== undefined) {
+    const completedMs = timestampMs(row.completedAt, startMs)
+    return Math.max(0, Math.round((completedMs - startMs) * 1e6))
+  }
+
+  return 0
+}
+
 /**
  * @param {Record<string, unknown> | undefined} recordMetadata
  * @param {Record<string, unknown>} config
@@ -207,14 +241,16 @@ function buildSpanMetadata (recordMetadata, config) {
 }
 
 module.exports = {
-  buildExperimentTagObject,
   buildSpanMetadata,
   buildTags,
+  durationNs,
   hasEntries,
   inferMetricType,
+  mergeTags,
   normalizeEvaluators,
   normalizeJsonMetricValue,
   sleep,
   stringify,
+  timestampMs,
   validateEvaluatorName,
 }

package/packages/dd-trace/src/llmobs/index.js

@@ -2,6 +2,7 @@
 
 const { channel } = require('dc-polyfill')
 
+const { readDatadogTags, writeDatadogTags } = require('../carrier')
 const log = require('../log')
 const { DD_MAJOR } = require('../../../../version')
 const startupLogs = require('../startup-log')
@@ -12,6 +13,8 @@ const {
   PROPAGATED_ML_APP_KEY,
   PROPAGATED_PARENT_ID_KEY,
   PROPAGATED_SESSION_ID_KEY,
+  PROPAGATED_PARENT_AGENT_ID_KEY,
+  PROPAGATED_PARENT_AGENT_NAME_KEY,
   SAMPLE_RATE,
   SAMPLING_DECISION,
   PROPAGATED_SAMPLE_RATE_KEY,
@@ -20,6 +23,7 @@ const {
   PROPAGATED_TRACE_ID_KEY,
 } = require('./constants/tags')
 const { storage } = require('./storage')
+const { agentNameWireSafe, appendOptionalPropagatedTag, resolveAgentAttribution, stripTagsetEntry } = require('./util')
 const telemetry = require('./telemetry')
 const LLMObsSpanProcessor = require('./span_processor')
 const LLMObsEvalMetricsWriter = require('./writers/evaluations')
@@ -147,9 +151,17 @@ function handleLLMObsInjection ({ carrier }) {
 
   if (!parentId && !mlApp && samplingDecision == null && !sessionId && !propagatedTraceId) return
 
+  // Propagate the nearest agent so spans in the downstream process attribute correctly. When the
+  // active span sits under a distributed agent, `resolveAgentAttribution` inherits the propagated
+  // id/name already on the parent's registry entry, so the chain survives multiple hops. Resolved
+  // after the bail-out above so we don't allocate when there is nothing to inject.
+  const { name: parentAgentName, spanId: parentAgentSpanId } = resolveAgentAttribution(
+    mlObsSpanTags, parent
+  )
+
   // `_injectTags` only writes `x-datadog-tags` when the trace has `_dd.p.*`
   // tags, so it may be undefined here — coalesce before appending.
-  const existing = carrier['x-datadog-tags']
+  const existing = readDatadogTags(carrier)
   let tags = existing || ''
   if (parentId) tags += `${tags ? ',' : ''}${PROPAGATED_PARENT_ID_KEY}=${parentId}`
   if (mlApp) tags += `${tags ? ',' : ''}${PROPAGATED_ML_APP_KEY}=${mlApp}`
@@ -157,7 +169,27 @@ function handleLLMObsInjection ({ carrier }) {
   if (sampleRate != null) tags += `${tags ? ',' : ''}${PROPAGATED_SAMPLE_RATE_KEY}=${sampleRate}`
   if (samplingDecision != null) tags += `${tags ? ',' : ''}${PROPAGATED_SAMPLING_DECISION_KEY}=${samplingDecision}`
   if (propagatedTraceId != null) tags += `${tags ? ',' : ''}${PROPAGATED_TRACE_ID_KEY}=${propagatedTraceId}`
-  if (tags !== existing) carrier['x-datadog-tags'] = tags
+  // When a local agent attribution is resolved, strip any stale upstream pagent entries that
+  // `_injectTags` may have already written into the carrier (it propagates all `_dd.p.*` from
+  // `_trace.tags`). This ensures the downstream sees a consistent id-only or id+name pair
+  // rather than a mix from different hops. The id is always digit-safe; an unsafe name is wiped.
+  if (parentAgentSpanId) {
+    tags = stripTagsetEntry(tags, PROPAGATED_PARENT_AGENT_ID_KEY)
+    tags = stripTagsetEntry(tags, PROPAGATED_PARENT_AGENT_NAME_KEY)
+  }
+  const maxLength = globalTracerConfig.DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH
+  const tagsWithId = appendOptionalPropagatedTag(
+    tags, PROPAGATED_PARENT_AGENT_ID_KEY, parentAgentSpanId, null, maxLength
+  )
+  // Only append the name when the id fit: a name without an id is unresolvable by the backend.
+  if (tagsWithId === tags) {
+    tags = tagsWithId
+  } else {
+    tags = appendOptionalPropagatedTag(
+      tagsWithId, PROPAGATED_PARENT_AGENT_NAME_KEY, parentAgentName, agentNameWireSafe, maxLength
+    )
+  }
+  if (tags !== existing) writeDatadogTags(carrier, tags)
 }
 
 function handleFlush () {

package/packages/dd-trace/src/llmobs/plugins/ai/util.js

@@ -228,6 +228,7 @@ function getJsonStringValue (str, defaultValue) {
 function getModelMetadata (tags) {
   /** @type {Record<string, unknown>} */
   const modelMetadata = {}
+  let hasModelMetadata = false
   for (const tag of Object.keys(tags)) {
     const isModelMetadata = tag.startsWith(VERCEL_AI_MODEL_METADATA_PREFIX)
     if (isModelMetadata) {
@@ -235,6 +236,7 @@ function getModelMetadata (tags) {
       const metadataKey = lastCommaPosition === -1 ? tag : tag.slice(lastCommaPosition + 1)
       if (metadataKey && MODEL_METADATA_KEYS.has(metadataKey)) {
         modelMetadata[metadataKey] = tags[tag]
+        hasModelMetadata = true
       }
     } else {
       const isTelemetryMetadata = tag.startsWith(VERCEL_AI_TELEMETRY_METADATA_PREFIX)
@@ -242,12 +244,13 @@ function getModelMetadata (tags) {
         const metadataKey = tag.slice(VERCEL_AI_TELEMETRY_METADATA_PREFIX.length)
         if (metadataKey) {
           modelMetadata[metadataKey] = tags[tag]
+          hasModelMetadata = true
         }
       }
     }
   }
 
-  return Object.keys(modelMetadata).length ? modelMetadata : null
+  return hasModelMetadata ? modelMetadata : null
 }
 
 /**
@@ -259,6 +262,7 @@ function getModelMetadata (tags) {
 function getGenerationMetadata (tags) {
   /** @type {Record<string, unknown>} */
   const metadata = {}
+  let hasMetadata = false
 
   for (const tag of Object.keys(tags)) {
     const isGenerationMetadata = tag.startsWith(VERCEL_AI_GENERATION_METADATA_PREFIX)
@@ -270,18 +274,20 @@ function getGenerationMetadata (tags) {
 
       const settingValue = tags[tag]
       metadata[settingKey] = settingValue
+      hasMetadata = true
     } else {
       const isTelemetryMetadata = tag.startsWith(VERCEL_AI_TELEMETRY_METADATA_PREFIX)
       if (isTelemetryMetadata) {
         const metadataKey = tag.slice(VERCEL_AI_TELEMETRY_METADATA_PREFIX.length)
         if (metadataKey) {
           metadata[metadataKey] = tags[tag]
+          hasMetadata = true
         }
       }
     }
   }
 
-  return Object.keys(metadata).length ? metadata : null
+  return hasMetadata ? metadata : null
 }
 
 /**
@@ -307,6 +313,7 @@ function getGenerationMetadataFromEvent (event) {
     metadata[transformedKey] = value
   }
 
+  // eslint-disable-next-line no-restricted-syntax -- manual tracking would duplicate Object.assign semantics
   return Object.keys(metadata).length ? metadata : null
 }
 
@@ -432,6 +439,7 @@ function getLlmObsSpanName (operation, functionId) {
  */
 function getTelemetryMetadata (tags) {
   const metadata = {}
+  let hasMetadata = false
 
   for (const tag of Object.keys(tags)) {
     if (!tag.startsWith(VERCEL_AI_TELEMETRY_METADATA_PREFIX)) continue
@@ -439,10 +447,11 @@ function getTelemetryMetadata (tags) {
     const metadataKey = tag.slice(VERCEL_AI_TELEMETRY_METADATA_PREFIX.length)
     if (metadataKey) {
       metadata[metadataKey] = tags[tag]
+      hasMetadata = true
     }
   }
 
-  return Object.keys(metadata).length ? metadata : null
+  return hasMetadata ? metadata : null
 }
 
 module.exports = {

package/packages/dd-trace/src/llmobs/plugins/base.js

@@ -84,9 +84,11 @@ class LLMObsPlugin extends TracingPlugin {
   }
 
   configure (config) {
-    // we do not want to enable any LLMObs plugins if it is disabled on the tracer
+    // we do not want to enable any LLMObs plugins if it is disabled on the tracer, or if the
+    // integration opted out via `tracer.use(<name>, { llmobs: false })`. Opting out only disables
+    // the LLMObs layer: the integration keeps emitting APM spans and propagating trace context.
     const llmobsEnabled = this._tracerConfig.llmobs.DD_LLMOBS_ENABLED
-    if (llmobsEnabled === false) {
+    if (llmobsEnabled === false || config?.llmobs === false) {
       config = typeof config === 'boolean' ? false : { ...config, enabled: false } // override to false
     }
     super.configure(config)

package/packages/dd-trace/src/llmobs/span_processor.js

@@ -27,6 +27,8 @@ const {
   ML_APP,
   TAGS,
   PARENT_ID_KEY,
+  PARENT_AGENT_NAME,
+  PARENT_AGENT_SPAN_ID,
   SESSION_ID,
   NAME,
   INPUT_PROMPT,
@@ -157,6 +159,20 @@ class LLMObsSpanProcessor {
       this.#addObject(mlObsTags[TOOL_DEFINITIONS], meta.tool_definitions)
     }
 
+    // Surface the agent attribution resolved at registration, but only on spans that actually
+    // have an agent ancestor. The id is always present in that case; the name may be missing when
+    // it arrived id-only over distributed propagation (older/unsafe upstream). Emit the name as
+    // explicit `null` then, matching the cross-language wire shape (dd-trace-py sends null, not an
+    // absent key) so the shared backend and system-tests see the same payload.
+    const parentAgentName = mlObsTags[PARENT_AGENT_NAME]
+    const parentAgentSpanId = mlObsTags[PARENT_AGENT_SPAN_ID]
+    if (parentAgentName != null || parentAgentSpanId != null) {
+      meta.agent_attribution = {
+        pagent_name: parentAgentName ?? null,
+        pagent_span_id: parentAgentSpanId,
+      }
+    }
+
     const llmObsSpan = new LLMObservabilitySpan(spanKind)
 
     if (spanKind === 'llm' && mlObsTags[INPUT_MESSAGES]) {

package/packages/dd-trace/src/llmobs/tagger.js

@@ -23,7 +23,11 @@ const {
   OUTPUT_MESSAGES,
   TAGS,
   NAME,
+  PARENT_AGENT_NAME,
+  PARENT_AGENT_SPAN_ID,
   PROPAGATED_PARENT_ID_KEY,
+  PROPAGATED_PARENT_AGENT_ID_KEY,
+  PROPAGATED_PARENT_AGENT_NAME_KEY,
   ROOT_PARENT_ID,
   CACHE_READ_INPUT_TOKENS_METRIC_KEY,
   CACHE_WRITE_INPUT_TOKENS_METRIC_KEY,
@@ -57,6 +61,7 @@ const {
 const { storage } = require('./storage')
 const {
   findGenAIAncestorSpanId,
+  resolveAgentAttribution,
   validateCostTags,
   writeBridgeTags,
   validateToolDefinitions,
@@ -173,6 +178,7 @@ class LLMObsTagger {
     this._setTag(span, PARENT_ID_KEY, parentId)
 
     this.#tagSamplingDecision(span, parent)
+    this.#tagAgentAttribution(span, parent)
 
     // apply annotation context
     const annotationContext = storage.getStore()?.annotationContext
@@ -229,6 +235,34 @@ class LLMObsTagger {
     if (samplingDecision != null) this._setTag(span, SAMPLING_DECISION, samplingDecision)
   }
 
+  /**
+   * Store the nearest agent ancestor on the span so it can be surfaced as
+   * `meta.agent_attribution` at finish. Resolved once here, at registration, so downstream
+   * children inherit it with a single lookup rather than walking the ancestor chain.
+   *
+   * @param {import('../opentracing/span')} span
+   * @param {import('../opentracing/span')} [parent] the LLMObs parent span, if any
+   */
+  // TODO: spans whose kind changes after registration (e.g. claude-agent-sdk tools promoted to
+  // sub-agents) will not retroactively update already-finished children's attribution. Follow up.
+  #tagAgentAttribution (span, parent) {
+    let name, spanId
+    if (registry.has(parent)) {
+      // Local LLMObs parent: attribute to it if it is an agent, else inherit its resolution.
+      ({ name, spanId } = resolveAgentAttribution(registry.get(parent), parent))
+    } else if (span.context()._trace.tags[PROPAGATED_PARENT_ID_KEY]) {
+      // Distributed LLMObs parent: inherit the nearest agent propagated from upstream. The
+      // name may be absent when the upstream hop ran an older SDK or its name was not
+      // wire-safe; the id-only case is expected and the backend resolves the name by span id.
+      const traceTags = span.context()._trace.tags
+      name = traceTags[PROPAGATED_PARENT_AGENT_NAME_KEY]
+      spanId = traceTags[PROPAGATED_PARENT_AGENT_ID_KEY]
+    }
+
+    if (name != null) this._setTag(span, PARENT_AGENT_NAME, name)
+    if (spanId != null) this._setTag(span, PARENT_AGENT_SPAN_ID, spanId)
+  }
+
   // TODO: similarly for the following `tag` methods,
   // how can we transition from a span weakmap to core API functionality
   tagLLMIO (span, inputData, outputData) {
@@ -696,6 +730,59 @@ class LLMObsTagger {
     return filteredAudioParts
   }
 
+  // Image counterpart of #filterAudioParts, with the same wire shape and validation.
+  #filterImageParts (imageParts) {
+    if (!Array.isArray(imageParts)) {
+      imageParts = [imageParts]
+    }
+
+    const filteredImageParts = []
+    for (const imagePart of imageParts) {
+      if (imagePart == null || typeof imagePart !== 'object') {
+        this.#handleFailure('Image part must be an object.', 'invalid_io_messages')
+        continue
+      }
+
+      const { mimeType, content, attachmentKey } = imagePart
+
+      if (typeof mimeType !== 'string' || !mimeType) {
+        this.#handleFailure('Image part mimeType must be a non-empty string.', 'invalid_io_messages')
+        continue
+      }
+
+      if (content == null && attachmentKey == null) {
+        this.#handleFailure("Image part must have either 'content' or 'attachmentKey'.", 'invalid_io_messages')
+        continue
+      }
+
+      if (content != null && attachmentKey != null) {
+        this.#handleFailure(
+          "Image part must have only one of 'content' or 'attachmentKey', not both.", 'invalid_io_messages'
+        )
+        continue
+      }
+
+      const imagePartObj = { mime_type: mimeType }
+
+      if (content == null) {
+        if (typeof attachmentKey !== 'string') {
+          this.#handleFailure('Image part attachmentKey must be a string.', 'invalid_io_messages')
+          continue
+        }
+        imagePartObj.attachment_key = attachmentKey
+      } else {
+        if (typeof content !== 'string') {
+          this.#handleFailure('Image part content must be a base64-encoded string.', 'invalid_io_messages')
+          continue
+        }
+        imagePartObj.content = content
+      }
+
+      filteredImageParts.push(imagePartObj)
+    }
+    return filteredImageParts
+  }
+
   #tagMessages (span, data, key) {
     if (!data) {
       return
@@ -723,6 +810,7 @@ class LLMObsTagger {
         toolResults,
         toolId,
         audioParts,
+        imageParts,
       } = message
       const messageObj = {}
 
@@ -764,6 +852,14 @@ class LLMObsTagger {
         }
       }
 
+      if (imageParts != null) {
+        const filteredImageParts = this.#filterImageParts(imageParts)
+
+        if (filteredImageParts.length) {
+          messageObj.image_parts = filteredImageParts
+        }
+      }
+
       if (toolId) {
         if (role === 'tool') {
           condition = this.#tagConditionalString(toolId, 'Tool ID', messageObj, 'tool_id') && condition

package/packages/dd-trace/src/llmobs/util.js

@@ -6,6 +6,10 @@ const {
   LLMOBS_PARENT_ID_BRIDGE_KEY,
   LLMOBS_TRACE_ID_BRIDGE_KEY,
   SPAN_KINDS,
+  SPAN_KIND,
+  NAME,
+  PARENT_AGENT_NAME,
+  PARENT_AGENT_SPAN_ID,
 } = require('./constants/tags')
 
 const DECIMAL_TRACE_ID_REGEX = /^\d+$/
@@ -294,6 +298,76 @@ function getFunctionArguments (fn, args = []) {
   }
 }
 
+// The `x-datadog-tags` tagset encoder rejects commas (the entry delimiter) and any byte
+// outside 0x20-0x7E, and a raise there drops the ENTIRE header (taking ml_app,
+// llmobs_trace_id, parent_id, sampling with it). An agent name is arbitrary user text, so it
+// must be skipped rather than sanitized when unsafe: only the digit-safe id then propagates and
+// the backend resolves the real name by span id. `=` is legal in tagset values (illegal only in
+// keys), so a name containing `=` is safe and must not be dropped.
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+function agentNameWireSafe (name) {
+  // Conservative slice of the 512B shared tagset budget, mirroring dd-trace-py.
+  if (Buffer.byteLength(name, 'utf8') > 256) return false
+  for (let index = 0; index < name.length; index++) {
+    const code = name.charCodeAt(index)
+    if (code < 0x20 || code > 0x7E || code === 0x2C /* comma */) return false
+  }
+  return true
+}
+
+/**
+ * Resolve the nearest agent that a *child* of `span` should be attributed to.
+ *
+ * If `span` is itself an agent, the child attributes directly to `span`. Otherwise `span`
+ * already resolved its own nearest agent at registration, so the child inherits that with a
+ * single lookup rather than walking the ancestor chain. An agent never attributes itself.
+ *
+ * @param {Record<string, unknown> | undefined} tags - Registry entry for the parent span.
+ * @param {import('../opentracing/span')} [span] - The parent span itself (needed for span id / name).
+ * @returns {{ name: string | undefined, spanId: string | undefined }}
+ */
+function resolveAgentAttribution (tags, span) {
+  if (!tags) return { name: undefined, spanId: undefined }
+  if (tags[SPAN_KIND] === 'agent') {
+    return { name: tags[NAME] || span._name, spanId: span.context().toSpanId() }
+  }
+  return { name: tags[PARENT_AGENT_NAME], spanId: tags[PARENT_AGENT_SPAN_ID] }
+}
+
+/**
+ * Removes all `key=value` entries for the given key from a comma-separated tagset string.
+ *
+ * @param {string} tags - Existing tagset string (may be empty).
+ * @param {string} key
+ * @returns {string}
+ */
+function stripTagsetEntry (tags, key) {
+  if (!tags.includes(key)) return tags
+  return tags.split(',').filter(entry => !entry.startsWith(`${key}=`)).join(',')
+}
+
+/**
+ * Appends `key=value` to the tagset string with a comma separator, but only when `value` is
+ * truthy, passes the optional `safeguard` predicate, and fits within `maxTagSetLength`. Returns
+ * the original `tags` unchanged when the value is absent, unsafe, or would overflow the budget.
+ *
+ * @param {string} tags - Existing tagset string (may be empty).
+ * @param {string} key
+ * @param {string | undefined} value
+ * @param {((v: string) => boolean) | null} [safeguard]
+ * @param {number} [maxTagSetLength]
+ * @returns {string}
+ */
+function appendOptionalPropagatedTag (tags, key, value, safeguard, maxTagSetLength) {
+  if (!value || (safeguard && !safeguard(value))) return tags
+  const entry = `${tags ? ',' : ''}${key}=${value}`
+  if (maxTagSetLength != null && tags.length + entry.length > maxTagSetLength) return tags
+  return `${tags}${entry}`
+}
+
 function spanHasError (span) {
   const spanContext = span.context()
   return !!(spanContext.getTag('error') || spanContext.getTag('error.type'))
@@ -443,6 +517,8 @@ function formatAudioPart (data, mimeType) {
 }
 
 module.exports = {
+  agentNameWireSafe,
+  appendOptionalPropagatedTag,
   audioMimeTypeFromFormat,
   encodeUnicode,
   findGenAIAncestorSpanId,
@@ -450,6 +526,8 @@ module.exports = {
   llmObsTraceIdToWire,
   normalizeLlmObsTraceId,
   formatAudioPart,
+  resolveAgentAttribution,
+  stripTagsetEntry,
   validateCostTags,
   validateKind,
   getFunctionArguments,