dd-trace 6.16.0 → 6.17.0

package/packages/dd-trace/src/dogstatsd.js

@@ -207,7 +207,6 @@ class DogStatsDClient {
   /**
    * @param {boolean|(() => void)} [forceTelemetry] - Whether to ignore the telemetry interval, or completion callback
    * @param {() => void} [done] - Called after serverless deliveries complete
-   * @returns {void}
    */
   flush (forceTelemetry = false, done) {
     if (typeof forceTelemetry === 'function') {
@@ -238,7 +237,6 @@ class DogStatsDClient {
   /**
    * @param {boolean} force - Whether to ignore the telemetry interval
    * @param {((send: (done?: () => void) => void) => void)} [track] - Tracks a non-serverless delivery
-   * @returns {void}
    */
   #flushTelemetry (force, track) {
     const telemetry = this.telemetry
@@ -291,7 +289,6 @@ class DogStatsDClient {
    * @param {DogStatsDBufferState} state - Payload state to flush
    * @param {boolean} recordTelemetry - Whether to record the transport outcome
    * @param {((send: (done?: () => void) => void) => void)} [track] - Tracks a non-serverless delivery
-   * @returns {void}
    */
   #flush (state, recordTelemetry, track) {
     const queue = this._enqueue(state)
@@ -314,7 +311,6 @@ class DogStatsDClient {
 
   /**
    * @param {number} bytes - Number of bytes sent
-   * @returns {void}
    */
   #recordSent (bytes) {
     const telemetry = this.telemetry
@@ -326,7 +322,6 @@ class DogStatsDClient {
   /**
    * @param {number} bytes - Number of bytes dropped
    * @param {number} [packets] - Number of packets dropped
-   * @returns {void}
    */
   #recordDropped (bytes, packets = 1) {
     const telemetry = this.telemetry
@@ -341,7 +336,6 @@ class DogStatsDClient {
    * @param {Buffer[]} queue - The metrics to send
    * @param {boolean} recordTelemetry - Whether to record the transport outcome
    * @param {() => void} [done] - Called after delivery completes
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _sendHttp (queue, recordTelemetry, done) {
@@ -375,7 +369,6 @@ class DogStatsDClient {
    * @param {Buffer[]} queue - The metrics to send
    * @param {boolean} recordTelemetry - Whether to record the transport outcome
    * @param {() => void} [done] - Called after delivery completes
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _sendUdp (queue, recordTelemetry, done) {
@@ -411,7 +404,6 @@ class DogStatsDClient {
    * @param {number} family - The family of the address
    * @param {boolean} recordTelemetry - Whether to record the transport outcome
    * @param {() => void} [done] - Called after every packet completes
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _sendUdpFromQueue (queue, address, family, recordTelemetry, done) {
@@ -457,7 +449,6 @@ class DogStatsDClient {
    * @param {string[]} tags - The metric tags
    * @param {string} [tagsPrefix] - Serialized global tags
    * @param {DogStatsDBufferState} [state] - Payload state receiving the metric
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _add (stat, value, type, tags, tagsPrefix = this.#tagsPrefix, state = this.#metrics) {
@@ -482,7 +473,6 @@ class DogStatsDClient {
    * @param {string} stat - Telemetry metric name
    * @param {number} value - Telemetry metric value
    * @param {string} [typeLabel] - Submitted or aggregated metric type
-   * @returns {void}
    */
   #addTelemetry (stat, value, typeLabel) {
     const tags = typeLabel === undefined ? undefined : [`metrics_type:${typeLabel}`]
@@ -496,7 +486,6 @@ class DogStatsDClient {
    *
    * @param {string} message - The message to write
    * @param {DogStatsDBufferState} [state] - Payload state receiving the message
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _write (message, state = this.#metrics) {
@@ -605,7 +594,6 @@ class MetricsAggregationClient {
   /**
    * @param {boolean|(() => void)} [forceTelemetry] - Whether to ignore the telemetry interval, or completion callback
    * @param {() => void} [done] - Called after serverless deliveries complete
-   * @returns {void}
    */
   flush (forceTelemetry = false, done) {
     if (typeof forceTelemetry === 'function') {
@@ -680,9 +668,6 @@ class MetricsAggregationClient {
     this.count(name, -count, tags)
   }
 
-  /**
-   * @returns {number} Number of gauge contexts flushed
-   */
   _captureGauges () {
     let metrics = 0
     const contexts = this._captureTree(this._gauges, (node, name, tags) => {
@@ -696,9 +681,6 @@ class MetricsAggregationClient {
     return contexts
   }
 
-  /**
-   * @returns {number} Number of counter contexts flushed
-   */
   _captureCounters () {
     let metrics = 0
     const contexts = this._captureTree(this._counters, (node, name, tags) => {
@@ -712,9 +694,6 @@ class MetricsAggregationClient {
     return contexts
   }
 
-  /**
-   * @returns {number} Number of histogram contexts flushed
-   */
   _captureHistograms () {
     let metrics = 0
     const contexts = this._captureTree(this._histograms, (node, name, tags) => {
@@ -740,7 +719,6 @@ class MetricsAggregationClient {
   /**
    * @param {Map<string, MetricNode>} tree - Metric context tree
    * @param {CaptureMetric} fn - Called for every context with submissions
-   * @returns {number} Number of contexts with submissions
    */
   _captureTree (tree, fn) {
     let contexts = 0
@@ -757,7 +735,6 @@ class MetricsAggregationClient {
    * @param {string} name - Metric name
    * @param {string[]} tags - Current metric tags
    * @param {CaptureMetric} fn - Called for every context with submissions
-   * @returns {number} Number of contexts with submissions
    */
   _captureNode (node, name, tags, fn) {
     let contexts = 0

package/packages/dd-trace/src/encode/0.4-cross-payload.js

@@ -74,13 +74,11 @@ class CrossPayloadAgentEncoder extends AgentEncoder {
     return super.makePayload()
   }
 
-  /** @returns {void} */
   reset () {
     this.#prepareReset()
     super.reset()
   }
 
-  /** @returns {void} */
   #prepareReset () {
     const crossPayloadState = this.#crossPayloadState
     if (crossPayloadState !== undefined && !prepareCrossPayloadReset(crossPayloadState)) {
@@ -129,7 +127,6 @@ function markPayloadString (crossPayloadState, value) {
 
 /**
  * @param {ReturnType<typeof createCrossPayloadState>} crossPayloadState
- * @returns {boolean}
  */
 function prepareCrossPayloadReset (crossPayloadState) {
   const learning = crossPayloadState.learningPayloadCount < CROSS_PAYLOAD_LEARNING_PAYLOAD_LIMIT

package/packages/dd-trace/src/encode/0.4.js

@@ -136,7 +136,6 @@ function formatSpanWithLegacyEvents (span) {
  * replacer hooks).
  *
  * @param {Array<{ name: unknown, startTime: number, attributes?: object }>} spanEvents
- * @returns {string}
  */
 function stringifySpanEvents (spanEvents) {
   let result = '['
@@ -200,7 +199,6 @@ function stringifyAttributeValue (value) {
  * conversion (which is what `JSON.stringify` calls internally).
  *
  * @param {number} value
- * @returns {string}
  */
 function jsonNumber (value) {
   if (Number.isFinite(value)) return String(value)
@@ -215,7 +213,6 @@ function jsonNumber (value) {
  * lone surrogates, etc.).
  *
  * @param {string} value
- * @returns {string}
  */
 function escapeJsonString (value) {
   for (let index = 0; index < value.length; index++) {
@@ -649,7 +646,6 @@ class AgentEncoder {
    * @param {number} offset
    * @param {Buffer} keyPrefix Precomputed `[key, 0xCF]`.
    * @param {{ toBuffer: () => Uint8Array | number[] }} identifier
-   * @returns {number}
    */
   #writeIdAt (target, offset, keyPrefix, identifier) {
     target.set(keyPrefix, offset)
@@ -871,7 +867,6 @@ class AgentEncoder {
    * @param {MsgpackChunk} bytes
    * @param {string} key
    * @param {unknown} value
-   * @returns {boolean}
    */
   #emitAttribute (bytes, key, value) {
     if (typeof value === 'string') {
@@ -911,7 +906,6 @@ class AgentEncoder {
    * @param {MsgpackChunk} bytes
    * @param {string} key
    * @param {Array<unknown>} array
-   * @returns {boolean}
    */
   #emitArrayAttribute (bytes, key, array) {
     const sectionStart = bytes.length
@@ -946,7 +940,6 @@ class AgentEncoder {
    * @param {MsgpackChunk} bytes
    * @param {string} key
    * @param {unknown} value
-   * @returns {boolean}
    */
   #emitArrayItem (bytes, key, value) {
     if (typeof value === 'string') {

package/packages/dd-trace/src/encode/0.5.js

@@ -173,7 +173,6 @@ class AgentEncoder extends BaseEncoder {
    * @param {Uint8Array} target
    * @param {number} offset
    * @param {number} index
-   * @returns {number}
    */
   #writeIndexAt (target, offset, index) {
     target[offset] = 0xCE
@@ -192,7 +191,6 @@ class AgentEncoder extends BaseEncoder {
    * @param {Uint8Array} target
    * @param {number} offset
    * @param {{ toBuffer: () => Uint8Array | number[] }} identifier
-   * @returns {number}
    */
   #writeIdAt (target, offset, identifier) {
     target[offset] = 0xCF

package/packages/dd-trace/src/encode/tags-processors.js

@@ -53,7 +53,6 @@ function truncateSpanTestOpt (span) {
  * the formatter no longer reshapes events, it hands the raw array through.
  *
  * @param {{ startTime: number }} event
- * @returns {number}
  */
 function eventTimeNano (event) {
   return Math.round(event.startTime * 1e6)

package/packages/dd-trace/src/evp_proxy/discovery.js

@@ -106,7 +106,6 @@ function selectEVPProxyPath (agentInfo, { supportedPaths, requiredHeaders = [] }
  * @param {string[]} [options.requiredHeaders] - Headers that the proxy must forward unchanged to intake. Each
  * header must appear in `evp_proxy_allowed_headers`. Do not include routing headers that the Agent consumes.
  * @param {(error: Error|null, route?: {url: URL, basePath: string}) => void} callback - Result callback
- * @returns {void}
  */
 function discoverEVPProxy (url, options, callback) {
   fetchAgentInfo(url, (error, agentInfo) => {

package/packages/dd-trace/src/evp_proxy/path.js

@@ -4,7 +4,6 @@ const LEADING_SLASHES = /^\/+/
 
 /**
  * @param {string} value
- * @returns {string}
  */
 function stripTrailingSlashes (value) {
   let end = value.length
@@ -19,7 +18,6 @@ function stripTrailingSlashes (value) {
  *
  * @param {string} basePath - EVP proxy base path
  * @param {string} endpoint - Product intake endpoint
- * @returns {string} Joined request path
  */
 function joinEVPProxyPath (basePath, endpoint) {
   const normalizedBasePath = stripTrailingSlashes(basePath)

package/packages/dd-trace/src/exporters/agent/writer.js

@@ -44,7 +44,6 @@ class AgentWriter extends BaseWriter {
    * Test Optimization owns its own request lifecycle tracking.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flushDirect (done, options) {
     if (this.#requestTracker) {

package/packages/dd-trace/src/exporters/agentless/index.js

@@ -63,7 +63,6 @@ class AgentlessExporter {
   /**
    * Sets the intake URL.
    * @param {string} urlString - The new intake URL
-   * @returns {boolean} True if URL was set successfully
    */
   setUrl (urlString) {
     try {

package/packages/dd-trace/src/exporters/agentless/intake.js

@@ -25,7 +25,6 @@ const INTAKE_PATH = '/api/v2/spans'
  * reattach the TLD, e.g. 'us2.ddog-gov.com' -> 'https://browser-intake-us2-ddog-gov.com'.
  *
  * @param {string} [site] - The Datadog site, e.g. 'us3.datadoghq.com'. Defaults to 'datadoghq.com'.
- * @returns {string} The intake origin, without a path.
  */
 function computeIntakeUrl (site = 'datadoghq.com') {
   const normalized = site.toLowerCase()

package/packages/dd-trace/src/exporters/agentless/writer.js

@@ -117,9 +117,6 @@ class AgentlessWriter extends BaseWriter {
     }
   }
 
-  /**
-   * @returns {string} The full agentless intake endpoint.
-   */
   #endpoint () {
     const endpoint = new URL(this._url)
     endpoint.pathname = INTAKE_PATH

package/packages/dd-trace/src/exporters/common/final-flush-request-tracker.js

@@ -45,7 +45,6 @@ class FinalFlushRequestTracker {
    *
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flush (done, options) {
     if (options?.deadline === undefined) {
@@ -112,7 +111,6 @@ class FinalFlushRequestTracker {
    * @param {RequestOptions} options
    * @param {(error: Error|null, result?: string|null, statusCode?: number,
    *   headers?: import('node:http').IncomingHttpHeaders) => void} callback
-   * @returns {void}
    */
   send (request, data, options, callback) {
     const controller = new AbortController()
@@ -141,7 +139,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #dropRequest (pendingRequest) {
     this.#pendingRequests.delete(pendingRequest)
@@ -155,7 +152,6 @@ class FinalFlushRequestTracker {
   /**
    * @param {FinalFlush} finalFlush
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #attachRequest (finalFlush, pendingRequest) {
     finalFlush.requests.add(pendingRequest)
@@ -165,7 +161,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #updateRequestDeadline (pendingRequest) {
     let deadline = 0
@@ -177,7 +172,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {FinalFlush} finalFlush
-   * @returns {void}
    */
   #finishFinalFlush (finalFlush) {
     if (!this.#finalFlushes.has(finalFlush) || !finalFlush.writerDone || finalFlush.requests.size !== 0) return

package/packages/dd-trace/src/exporters/common/request.js

@@ -170,6 +170,7 @@ function request (data, options, callback) {
         }
         const error = new log.NoTransmitError(errorMessage)
         error.status = res.statusCode
+        if (options.includeErrorResponseBody) error.responseBody = responseData
 
         complete(error, null, res.statusCode, res.headers)
       }

package/packages/dd-trace/src/exporters/common/url.js

@@ -7,7 +7,6 @@ const { urlToHttpOptions } = require('./url-to-http-options-polyfill')
 
 /**
  * @param {string} hostname
- * @returns {boolean}
  */
 function isLoopbackHost (hostname) {
   // Gate the 127/8 prefix on an IPv4 literal so names such as 127.example.com cannot pass.
@@ -20,7 +19,6 @@ function isLoopbackHost (hostname) {
 /**
  * @param {string|undefined} protocol
  * @param {string|undefined} hostname
- * @returns {boolean}
  */
 function canSendApiKey (protocol, hostname) {
   return protocol === 'https:' || protocol === 'unix:' ||

package/packages/dd-trace/src/exporters/common/writer.js

@@ -27,7 +27,6 @@ class Writer {
    * Flushes queued telemetry, retaining delivery on supported serverless platforms.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flush (done, options) {
     if (this.#deliveryTracker) {
@@ -40,7 +39,6 @@ class Writer {
    * Flushes queued telemetry without registering serverless delivery retention.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flushDirect (done = noop, options) {
     const count = this._encoder.count()

package/packages/dd-trace/src/id.js

@@ -36,7 +36,6 @@ class Identifier {
 
   /**
    * @param {number} [radix]
-   * @returns {string}
    */
   toString (radix = 16) {
     if (radix === 16) {
@@ -50,9 +49,6 @@ class Identifier {
     return toNumberString(this.#buffer, radix)
   }
 
-  /**
-   * @returns {bigint}
-   */
   toBigInt () {
     this.#bigInt ??= Buffer.from(this.#buffer).readBigUInt64BE(0)
     return this.#bigInt
@@ -75,9 +71,6 @@ class Identifier {
     return this.#buffer.slice(-8)
   }
 
-  /**
-   * @returns {string}
-   */
   toJSON () {
     return this.toString()
   }
@@ -88,7 +81,6 @@ class Identifier {
    * only this identifier's hex representation.
    *
    * @param {string | undefined} traceIdHigh - 16-char hex of the upper 64 bits, or undefined
-   * @returns {string}
    */
   toTraceIdHex (traceIdHigh) {
     if (traceIdHigh && this.#buffer.length <= 8) {
@@ -99,7 +91,6 @@ class Identifier {
 
   /**
    * @param {Identifier} other
-   * @returns {boolean}
    */
   equals (other) {
     // Big-endian suffix compare: when buffers differ in length, only the
@@ -182,7 +173,6 @@ function fromString (str, raddix) {
 /**
  * @param {number[] | Uint8Array} buffer
  * @param {number} [radix]
- * @returns {string}
  */
 function toNumberString (buffer, radix) {
   let high = readInt32(buffer, buffer.length - 8)
@@ -233,7 +223,6 @@ function pseudoRandom () {
 /**
  * @param {number[] | Uint8Array} buffer
  * @param {number} offset
- * @returns {number}
  */
 function readInt32 (buffer, offset) {
   return (buffer[offset + 0] * 16_777_216) +

package/packages/dd-trace/src/llmobs/audio-codec.js

@@ -0,0 +1,192 @@
+'use strict'
+
+// Raw-audio primitives shared by the LLM Observability integrations: mapping provider audio formats
+// to MIME types, decoding telephony audio to PCM16, wrapping PCM16 in a WAV container, and deriving
+// a segment's playback duration from its byte count. Deliberately free of LLM Observability concepts
+// so the realtime instrumentation can use the timing half without pulling in span plumbing.
+
+const { G711_SAMPLE_RATE, PCM16_BYTES_PER_SAMPLE, WAV_HEADER_BYTES } = require('./constants/audio')
+
+// OpenAI Realtime audio `format` values (legacy string form) that don't map to `audio/<format>`.
+// A Map rather than an object literal so a hostile format string ("constructor", "__proto__") can't
+// resolve to something off Object.prototype.
+const REALTIME_FORMAT_MIME_TYPES = new Map([
+  ['pcm16', 'audio/pcm'],
+  ['pcm', 'audio/pcm'],
+  ['g711_ulaw', 'audio/pcmu'],
+  ['g711_alaw', 'audio/pcma'],
+])
+
+// Raw little-endian PCM16. Not renderable on its own, but losslessly wrappable in a WAV container.
+const PCM16_MIME_TYPES = new Set(['audio/pcm', 'audio/pcm16', 'audio/l16'])
+
+// G.711 telephony audio (8 kHz, 8-bit companded), used by Realtime for phone-call integrations.
+const G711_MIME_TO_VARIANT = new Map([
+  ['audio/pcmu', 'ulaw'],
+  ['audio/g711_ulaw', 'ulaw'],
+  ['audio/pcma', 'alaw'],
+  ['audio/g711_alaw', 'alaw'],
+])
+
+/**
+ * Decode one G.711 mu-law byte to a signed 16-bit linear PCM sample (CCITT G.711).
+ *
+ * @param {number} byte
+ */
+function decodeUlawSample (byte) {
+  byte = ~byte & 0xFF
+  let sample = ((byte & 0x0F) << 3) + 0x84
+  sample <<= (byte & 0x70) >> 4
+  return (byte & 0x80) ? (0x84 - sample) : (sample - 0x84)
+}
+
+/**
+ * Decode one G.711 A-law byte to a signed 16-bit linear PCM sample (CCITT G.711).
+ *
+ * @param {number} byte
+ */
+function decodeAlawSample (byte) {
+  byte ^= 0x55
+  let sample = (byte & 0x0F) << 4
+  const segment = (byte & 0x70) >> 4
+  if (segment === 0) {
+    sample += 8
+  } else if (segment === 1) {
+    sample += 0x1_08
+  } else {
+    sample = (sample + 0x1_08) << (segment - 1)
+  }
+  return (byte & 0x80) ? sample : -sample
+}
+
+// The input domain is a single byte, so both decodes collapse to a 256-entry lookup built once.
+const ULAW_TABLE = new Int16Array(256)
+const ALAW_TABLE = new Int16Array(256)
+for (let byte = 0; byte < 256; byte++) {
+  ULAW_TABLE[byte] = decodeUlawSample(byte)
+  ALAW_TABLE[byte] = decodeAlawSample(byte)
+}
+
+/**
+ * Map an OpenAI Realtime audio format to a MIME type.
+ *
+ * Handles both the legacy string form (e.g. "pcm16", "g711_ulaw") and the newer discriminated-union
+ * object whose `type` is already a MIME type (e.g. "audio/pcm"). Yields an empty string when the
+ * format is absent or unusable, which callers treat as "unknown" rather than guessing a rate.
+ *
+ * @param {string | { type?: string } | undefined} format
+ */
+function realtimeAudioFormatToMime (format) {
+  const type = typeof format === 'object' && format !== null ? format.type : format
+  if (typeof type !== 'string') return ''
+
+  const normalized = type.trim().toLowerCase()
+  if (!normalized) return ''
+  if (normalized.startsWith('audio/')) return normalized
+
+  return REALTIME_FORMAT_MIME_TYPES.get(normalized) ?? `audio/${normalized}`
+}
+
+/**
+ * @param {string} mimeType
+ */
+function isPcm16AudioMime (mimeType) {
+  return typeof mimeType === 'string' && PCM16_MIME_TYPES.has(mimeType.trim().toLowerCase())
+}
+
+/**
+ * @param {string} mimeType
+ * @returns {'ulaw' | 'alaw' | undefined} The G.711 variant, or `undefined` for any other format.
+ */
+function g711Variant (mimeType) {
+  if (typeof mimeType !== 'string') return
+  return G711_MIME_TO_VARIANT.get(mimeType.trim().toLowerCase())
+}
+
+/**
+ * Decode G.711 audio to raw little-endian PCM16.
+ *
+ * @param {Buffer} data
+ * @param {'ulaw' | 'alaw'} variant
+ * @returns {Buffer}
+ */
+function g711ToPcm16 (data, variant) {
+  const table = variant === 'alaw' ? ALAW_TABLE : ULAW_TABLE
+  const pcm = Buffer.allocUnsafe(data.length * PCM16_BYTES_PER_SAMPLE)
+  for (let i = 0; i < data.length; i++) {
+    pcm.writeInt16LE(table[data[i]], i * PCM16_BYTES_PER_SAMPLE)
+  }
+  return pcm
+}
+
+/**
+ * Wrap raw little-endian PCM16 audio in a WAV container.
+ *
+ * Lossless and cheap — it only prepends a 44-byte header — and turns raw PCM, which the UI can't
+ * render, into a playable `audio/wav` payload.
+ *
+ * @param {Buffer} pcm
+ * @param {number} [sampleRate]
+ * @param {number} [channels]
+ * @returns {Buffer}
+ */
+function pcm16ToWav (pcm, sampleRate = 24_000, channels = 1) {
+  const blockAlign = channels * PCM16_BYTES_PER_SAMPLE
+  const header = Buffer.allocUnsafe(WAV_HEADER_BYTES)
+
+  header.write('RIFF', 0, 'latin1')
+  header.writeUInt32LE(WAV_HEADER_BYTES - 8 + pcm.length, 4) // RIFF chunk size: everything after this field
+  header.write('WAVE', 8, 'latin1')
+  header.write('fmt ', 12, 'latin1')
+  header.writeUInt32LE(16, 16) // fmt chunk size, 16 for PCM
+  header.writeUInt16LE(1, 20) // audio format, 1 for uncompressed PCM
+  header.writeUInt16LE(channels, 22)
+  header.writeUInt32LE(sampleRate, 24)
+  header.writeUInt32LE(sampleRate * blockAlign, 28) // byte rate
+  header.writeUInt16LE(blockAlign, 32)
+  header.writeUInt16LE(PCM16_BYTES_PER_SAMPLE * 8, 34) // bits per sample
+  header.write('data', 36, 'latin1')
+  header.writeUInt32LE(pcm.length, 40)
+
+  return Buffer.concat([header, pcm], WAV_HEADER_BYTES + pcm.length)
+}
+
+/**
+ * Byte rate of a raw audio format: PCM16 is 2 bytes per sample at the session's rate, G.711 is 1
+ * byte per sample at the fixed 8 kHz rate. Any other or unknown format returns `undefined` — we do
+ * not guess a rate, so durations and offsets derived from it are simply unavailable.
+ *
+ * @param {string} mimeType
+ * @param {number} sampleRate
+ * @returns {number | undefined}
+ */
+function bytesPerSecond (mimeType, sampleRate) {
+  if (sampleRate > 0 && isPcm16AudioMime(mimeType)) return sampleRate * PCM16_BYTES_PER_SAMPLE
+  if (g711Variant(mimeType) !== undefined) return G711_SAMPLE_RATE
+}
+
+/**
+ * Playback duration (in milliseconds) of an audio segment, from its decoded byte count. Sizes the
+ * user-speech and agent-speech spans and the turn root's end, so it may be fractional.
+ *
+ * @param {number} decodedBytes
+ * @param {string} mimeType
+ * @param {number} sampleRate
+ * @returns {number | undefined}
+ */
+function segmentDurationMs (decodedBytes, mimeType, sampleRate) {
+  if (!(decodedBytes > 0)) return
+  const rate = bytesPerSecond(mimeType, sampleRate)
+  if (!rate) return
+  return decodedBytes / rate * 1000
+}
+
+module.exports = {
+  bytesPerSecond,
+  g711ToPcm16,
+  g711Variant,
+  isPcm16AudioMime,
+  pcm16ToWav,
+  realtimeAudioFormatToMime,
+  segmentDurationMs,
+}