@cap-js/agents 0.9.5 → 0.9.7

package/lib/masking/unstructured/dpi.js

@@ -0,0 +1,84 @@
+import cds from "@sap/cds"
+
+const PSEUDONYMIZE_PATH = "/anonymization/api/v1.0/unstructureddata/pseudonymize/text"
+const TIMEOUT = 30_000
+const DEFAULT_ENTITIES = [
+  "profile-person",
+  "profile-email",
+  "profile-phone",
+  "profile-address",
+  "profile-username-password",
+  "profile-nationalid",
+  "profile-iban",
+  "profile-ssn",
+  "profile-credit-card-number",
+  "profile-passport",
+  "profile-driverlicense",
+]
+
+export async function anonymize(text) {
+  const destinationName = resolveDestination()
+  if (!destinationName || !text) return { text }
+  const result = await anonymizeText(text, destinationName)
+  return { text: result.text, mappings: result.mappings }
+}
+
+function resolveDestination() {
+  const required = cds.env.requires?.["data-anonymization"]
+  const destinationName = required?.credentials?.destination
+  if (!destinationName) return undefined
+  return destinationName
+}
+
+async function anonymizeText(text, destinationName) {
+  const payload = buildPayload(text)
+  const data = await postToDpi(payload, destinationName)
+  const mappings = extractPseudonymMappings(data.metadata)
+  // Rewrite DPI tags in the anonymized text from <<profile-person>:hash> to person-hash.
+  const result = data.result.replace(/<<(?:profile-)?([^>]+)>:([^>]+)>/g, "$1-$2")
+  return { text: result, mappings }
+}
+
+function buildPayload(text) {
+  const payload = new URLSearchParams()
+  payload.set("text", text)
+  payload.set("entities", DEFAULT_ENTITIES.join(";"))
+  payload.set("anonymization-method-per-profile", "")
+  payload.set("whitelist", "")
+  payload.set("enable-default-whitelist", "false")
+  return payload.toString()
+}
+
+function extractPseudonymMappings(data) {
+  const mappings = []
+  // DPI returns pseudonyms in the form "<<profile-person>:abc12345>".
+  // Convert to the standard tag format "person-abc12345" and also register
+  // the bare hash "abc12345" so the LLM can use it in queries.
+  for (const dpiTag of Object.keys(data)) {
+    const match = dpiTag.match(/^<<(?:profile-)?([^>]+)>:([^>]+)>$/)
+    if (!match) continue
+    const [, entityType, hash] = match
+    const tag = `${entityType}-${hash}`
+    const original = data[dpiTag].real_entity
+    mappings.push([tag, original])
+    mappings.push([hash, original])
+  }
+  return mappings
+}
+// API Docs: https://api.sap.com/api/sap-dpi-pseudonymization-v1/resource/Pseudonymization
+// SAP Help: https://help.sap.com/docs/data-privacy-integration/development/api-endpoints-9956053a4e6447cfbaccb9d2dee35c11
+async function postToDpi(payload, destinationName) {
+  const { executeHttpRequest } = await import("@sap-cloud-sdk/http-client")
+  const response = await executeHttpRequest(
+    { destinationName },
+    {
+      method: "post",
+      url: `${PSEUDONYMIZE_PATH}?priority=high`,
+      data: payload,
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      timeout: TIMEOUT,
+    },
+    { fetchCsrfToken: false },
+  )
+  return response.data
+}

package/lib/masking/unstructured/hana.js

@@ -0,0 +1,64 @@
+import cds from "@sap/cds"
+import { generatePseudonymTag } from "../store.js"
+
+const LOG = cds.log("agents")
+
+// Full list of categories HANA detects: https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-predictive-analysis-library/descriptions-of-entity-types
+const DPP_CATEGORIES = new Map([
+  ["PERSON", "person"],
+  ["URI:EMAIL", "email"],
+  ["PHONE", "phone"],
+  ["ADDRESS", "address"],
+  ["URI:URL", "url"],
+  ["URI:IP", "ip"],
+])
+
+let scriptServerActive = true
+
+export async function anonymize(text, seed) {
+  if (!scriptServerActive || !text || !seed) return { text }
+  try {
+    return await pseudonymizeText(text, seed)
+  } catch (err) {
+    LOG.error(`SAP HANA Cloud NLS based pseudonymization disabled due to error: `, err)
+    scriptServerActive = false
+    return { text }
+  }
+}
+
+async function pseudonymizeText(text, seed) {
+  const res = await cds.run(buildPalCallSql(), [text])
+  const entities = res.changes[1]
+  const piiEntities = entities
+    .filter((e) => e.TYPE === "ner" && DPP_CATEGORIES.has(e.ENTITY))
+    // Sort back to front so offsets stay valid after replacement
+    .sort((a, b) => b.GLOBAL_OFFSET - a.GLOBAL_OFFSET)
+
+  const mappings = []
+  const seen = new Set()
+  let result = text
+  for (const row of piiEntities) {
+    if (result.slice(row.GLOBAL_OFFSET, row.GLOBAL_OFFSET + row.TOKEN.length) !== row.TOKEN)
+      continue
+    const category = DPP_CATEGORIES.get(row.ENTITY)
+    const tag = generatePseudonymTag(seed, row.TOKEN, category)
+    result = `${result.slice(0, row.GLOBAL_OFFSET)}${tag}${result.slice(row.GLOBAL_OFFSET + row.TOKEN.length)}`
+    if (!seen.has(row.TOKEN)) {
+      seen.add(row.TOKEN)
+      const hash = tag.slice(category.length + 1)
+      mappings.push([tag, row.TOKEN])
+      mappings.push([hash, row.TOKEN])
+    }
+  }
+  return { text: result, mappings, textAnalysisResults: entities }
+}
+
+function buildPalCallSql() {
+  return `DO (IN text NVARCHAR(5000) => ?, OUT textAnalysisResults TABLE (ID NVARCHAR(36), "TYPE" NVARCHAR(3), SENTENCE_ID INTEGER, "TOKEN" NVARCHAR(5000), "ENTITY" NVARCHAR(1000), OFFSET INTEGER, GLOBAL_OFFSET INTEGER) => ?) BEGIN
+    lt_data = SELECT CAST(SYSUUID as NVARCHAR(36)) AS "ID", :text AS "CONTENT", CAST('' AS NVARCHAR(1000)) AS "LANGUAGE", CAST('ner' AS NVARCHAR(20)) AS "TASK" FROM DUMMY UNION SELECT CAST(SYSUUID as NVARCHAR(36)) AS "ID", :text AS "CONTENT", CAST('' AS NVARCHAR(1000)) AS "LANGUAGE", CAST('pos' AS NVARCHAR(20)) AS "TASK" FROM DUMMY;
+    lt_param = SELECT CAST('' AS NVARCHAR(256)) AS "PARAM_NAME", CAST(0 AS INTEGER) AS "INT_VALUE", CAST(0.0 AS DOUBLE) AS "DOUBLE_VALUE", CAST('' AS NVARCHAR(1000)) AS "STRING_VALUE" FROM DUMMY;
+    CALL _SYS_AFL.PAL_TEXT_ANALYSIS(:lt_data, :lt_param, lt_sentences, lt_pos, lt_ner, lt_doc_sentiment, lt_sentence_sentiment, lt_phrase_sentiment, lt_extra);
+    textAnalysisResults = 
+      SELECT SYSUUID AS "ID", 'ner' AS "TYPE", "SENTENCE_ID", "TOKEN", "ENTITY", "OFFSET", "GLOBAL_OFFSET" FROM :lt_ner UNION  SELECT SYSUUID AS "ID", 'pos' AS "TYPE", "SENTENCE_ID", "TOKEN", "ENTITY", "OFFSET", "GLOBAL_OFFSET" FROM :lt_pos;
+END;`
+}

package/lib/masking/unstructured/index.js

@@ -0,0 +1,52 @@
+import cds from "@sap/cds"
+import { anonymize as hana } from "./hana.js"
+import { anonymize as dpi } from "./dpi.js"
+import { ensureSession, pseudonymize } from "../index.js"
+
+export default async function anonymizeUnstructured(text, seed) {
+  const hanaResult = await hana(text, seed)
+  const dpiResult = await dpi(hanaResult.text)
+  return {
+    text: dpiResult.text,
+    mappings: [...(hanaResult.mappings ?? []), ...(dpiResult.mappings ?? [])],
+    textAnalysisResults: hanaResult.textAnalysisResults,
+  }
+}
+
+/**
+ * Pseudonymize user message text parts before graph execution.
+ */
+export async function pseudonymizeUserMessage(srv, requestContext, checkpointer, threadId) {
+  await ensureSession(checkpointer, threadId)
+  const session = cds.context?.["agent.pseudonyms"]
+  const parts = requestContext.userMessage?.parts
+  if (!session || !Array.isArray(parts)) return
+
+  const textParts = parts.filter((p) => (p.kind === "text" || (!p.kind && p.text)) && p.text)
+  if (!textParts.length) return
+
+  const results = await Promise.all(
+    textParts.map((p) =>
+      pseudonymize(
+        {
+          data: p.text,
+          type: "unstructured",
+          seed: session._seed,
+        },
+        srv,
+      ),
+    ),
+  )
+  for (let i = 0; i < textParts.length; i++) {
+    const r = results[i]
+    textParts[i].text = r.data
+    session.addMappings(r.mappings)
+    if (r.metadata?.textAnalysisResults?.length) {
+      session._textAnalysisResults = (session._textAnalysisResults ?? []).concat(
+        r.metadata.textAnalysisResults,
+      )
+    }
+    // Scrub any PII detected in prior turns that is not detected by HANA/DPI
+    textParts[i].text = session.scrubText(textParts[i].text)
+  }
+}

package/lib/preview/chat.html

@@ -96,6 +96,16 @@
         border-bottom-right-radius: 3px;
         white-space: pre-wrap;
       }
+      .msg.user.queued {
+        opacity: 0.65;
+      }
+      .msg.user.queued::after {
+        content: "Queued";
+        display: block;
+        margin-top: 4px;
+        font-size: 0.7em;
+        text-align: right;
+      }
       .msg.agent {
         align-self: flex-start;
         background: #d0e9ff;
@@ -246,6 +256,7 @@
 
       #prompt {
         flex: 1;
+        box-sizing: border-box;
         padding: 10px 14px;
         border: 1px solid #91adc5;
         border-radius: 8px;
@@ -288,7 +299,6 @@
       #send.cancel:hover {
         background: #c62828;
       }
-
       .approval-actions {
         display: flex;
         gap: 8px;
@@ -508,6 +518,8 @@
       const THINKING_SUMMARY_ANIMATION_MS = 160
 
       let busy = false
+      let processingQueue = false
+      const messageQueue = []
       let contextId = null
       let pendingTaskId = null
       let activeTaskId = null
@@ -547,13 +559,14 @@
 
       prompt.addEventListener("input", () => {
         prompt.style.height = "auto"
-        prompt.style.height = Math.min(prompt.scrollHeight, 140) + "px"
+        const borderHeight = prompt.offsetHeight - prompt.clientHeight
+        prompt.style.height = Math.min(prompt.scrollHeight + borderHeight, 140) + "px"
+        renderComposerAction()
       })
       prompt.addEventListener("keydown", (e) => {
         if (e.key === "Enter" && !e.shiftKey) {
           e.preventDefault()
-          if (busy) cancel()
-          else send()
+          enqueueMessage()
         } else if (e.key === "ArrowUp" && prompt.selectionStart === 0) {
           e.preventDefault()
           if (historyIndex === -1) currentDraft = prompt.value
@@ -561,6 +574,7 @@
             historyIndex++
             prompt.value = inputHistory[inputHistory.length - 1 - historyIndex]
             prompt.selectionStart = prompt.selectionEnd = prompt.value.length
+            renderComposerAction()
           }
         } else if (e.key === "ArrowDown" && prompt.selectionEnd === prompt.value.length) {
           e.preventDefault()
@@ -568,26 +582,32 @@
             historyIndex--
             prompt.value = inputHistory[inputHistory.length - 1 - historyIndex]
             prompt.selectionStart = prompt.selectionEnd = prompt.value.length
+            renderComposerAction()
           } else if (historyIndex === 0) {
             historyIndex = -1
             prompt.value = currentDraft
             prompt.selectionStart = prompt.selectionEnd = prompt.value.length
+            renderComposerAction()
           }
         }
       })
       sendBtn.addEventListener("click", () => {
-        if (busy) cancel()
-        else send()
+        if (busy && !prompt.value.trim()) cancel()
+        else enqueueMessage()
       })
+      renderComposerAction()
 
-      function addMessage(role, text) {
+      function addMessage(role, text, beforeEl) {
         const el = document.createElement("div")
         el.className = "msg " + role
         if (role === "agent" || role === "agent_thinking")
           el.innerHTML = md(text, { sanitize: true })
         else el.textContent = text
         if (role === "agent_thinking") el.className = "msg agent_thinking"
-        messages.insertBefore(el, typing.parentElement === messages ? typing : statusText)
+        messages.insertBefore(
+          el,
+          beforeEl ?? (typing.parentElement === messages ? typing : statusText),
+        )
         messages.scrollTop = messages.scrollHeight
         return el
       }
@@ -869,25 +889,27 @@
 
       function setBusy(val) {
         busy = val
-        prompt.disabled = val
         if (typing.parentElement !== messages) messages.insertBefore(typing, statusText)
         typing.style.display = val ? "block" : "none"
         dot.className = "status-dot" + (val ? " busy" : "")
-        if (val) {
-          sendBtn.textContent = "Cancel"
-          sendBtn.classList.add("cancel")
-          sendBtn.disabled = false
-        } else {
-          sendBtn.textContent = "Send"
-          sendBtn.classList.remove("cancel")
-          sendBtn.disabled = false
+        if (!val) {
           activeTaskId = null
           activeAbort = null
           statusText.textContent = ""
         }
+        renderComposerAction()
         messages.scrollTop = messages.scrollHeight
       }
 
+      function renderComposerAction() {
+        const stopsGeneration = busy && !prompt.value.trim()
+        sendBtn.textContent = stopsGeneration ? "Cancel" : "Send"
+        sendBtn.classList.toggle("cancel", stopsGeneration)
+        sendBtn.setAttribute("aria-label", stopsGeneration ? "Stop generating" : "Send message")
+        sendBtn.title = stopsGeneration ? "Stop generating" : "Send message"
+        sendBtn.disabled = !busy && !prompt.value.trim()
+      }
+
       async function resume(decision) {
         const taskId = pendingTaskId
         pendingTaskId = null
@@ -934,6 +956,7 @@
         } finally {
           setBusy(false)
           prompt.focus()
+          processQueue()
         }
       }
 
@@ -982,11 +1005,10 @@
         finalizeThinking(replyEl, reply)
       }
 
-      async function send() {
+      function enqueueMessage() {
         const text = prompt.value.trim()
-        if (!text || busy) return
+        if (!text) return
 
-        // Save to input history (skip if same as last entry)
         if (inputHistory[inputHistory.length - 1] !== text) {
           inputHistory.push(text)
           if (inputHistory.length > 100) inputHistory.shift()
@@ -994,10 +1016,31 @@
         }
         historyIndex = -1
         currentDraft = ""
-
-        addMessage("user", text)
         prompt.value = ""
         prompt.style.height = "auto"
+        renderComposerAction()
+        const el = addMessage("user", text, statusText)
+        el.classList.add("queued")
+        messageQueue.push({ text, el })
+        processQueue()
+      }
+
+      async function processQueue() {
+        if (processingQueue || pendingTaskId) return
+        processingQueue = true
+        try {
+          while (messageQueue.length && !pendingTaskId) {
+            const message = messageQueue.shift()
+            await sendMessage(message)
+          }
+        } finally {
+          processingQueue = false
+        }
+      }
+
+      async function sendMessage({ text, el }) {
+        el.classList.remove("queued")
+        messages.insertBefore(el, typing.parentElement === messages ? typing : statusText)
         setBusy(true)
 
         const abort = new AbortController()
@@ -1202,11 +1245,8 @@
 
       async function cancel() {
         const taskId = activeTaskId
+        activeAbort?.abort()
 
-        // Abort ongoing fetch
-        if (activeAbort) activeAbort.abort()
-
-        // Send tasks/cancel if we have a taskId
         if (taskId) {
           fetch(AGENT_URL, {
             method: "POST",
@@ -1219,10 +1259,6 @@
             }),
           }).catch(() => {})
         }
-
-        addMessage("agent", "⊘ Task canceled.")
-        setBusy(false)
-        prompt.focus()
       }
     </script>
   </body>

package/lib/protocol/agent-card.js

@@ -1,12 +1,8 @@
 import cds from "@sap/cds"
 import { createRequire } from "node:module"
 const { path } = cds.utils
-import {
-  getDescription,
-  getFilteredEntities,
-  getFilteredActions,
-  slugified,
-} from "../utils/utils.js"
+import { getFilteredEntities, getFilteredActions } from "@cap-js/mcp/lib/utils/tools-shared.js"
+import { getDescription, slugified } from "../utils/utils.js"
 import {
   scanSkills,
   parseAgentMetadata,

package/lib/protocol/persistence/cleanup.js

@@ -49,10 +49,19 @@ export async function triggerCleanup(serviceName) {
     LOG.debug(`triggerCleanup: srv.schedule not available (CDS < 9). Skipping cleanup scheduling.`)
     return
   }
-  serviceMap.set(serviceName, Date.now())
-  const MAX_TIMEOUT = 2_147_483_647
-  const delay = Math.min(ttlMs + MS_OF_A_DAY, MAX_TIMEOUT)
-  await srv.schedule("cleanupTasks", {}).after(delay)
+  const now = Date.now()
+  serviceMap.set(serviceName, now)
+  const delay = ttlMs + MS_OF_A_DAY
+  const scheduled = srv.schedule("cleanupTasks", {})
+  const taskName = `cleanupTasks-${srv.name}-${new Date().toDateString().substring(0, 10)}`
+  // .as in cds10
+  if (typeof scheduled.as === "function") await scheduled.as(taskName).after(delay)
+  // .asTask in cds9.9
+  else if (typeof scheduled.asTask === "function") await scheduled.asTask(taskName).after(delay)
+  // cds9 < 9.9 has no task naming API
+  else {
+    LOG.error("Cannot schedule cleanup of old tasks. Please update your @sap/cds version.")
+  }
 }
 
 /**

package/lib/telemetry/chat-tracing.js

@@ -316,7 +316,10 @@ export function setLLMSpanStartAttrs(
 
   // MLflow inputs: chat messages for Chat tab
   if ((cds.env.agents?.mlflow || LOG._debug) && messages) {
-    const mlMessages = messages.map((m) => ({ role: toRole(m), content: extractText(m.content) }))
+    const mlMessages = messages.map((m) => ({
+      role: toRole(m),
+      content: extractText(m.content),
+    }))
     setSpanAttrs(span, mlflowAttrs("LLM", { model, provider, inputs: { messages: mlMessages } }))
     if (LOG._debug) {
       span.setAttribute("gen_ai.input.messages", JSON.stringify(messages.map((m) => m.content)))
@@ -367,7 +370,9 @@ export function setLLMSpanEndAttrs(span, { model, provider, tokenUsage, outputCo
       mlflowAttrs("LLM", {
         model,
         provider,
-        outputs: { choices: [{ message: { role: "assistant", content: outputContent } }] },
+        outputs: {
+          choices: [{ message: { role: "assistant", content: outputContent } }],
+        },
       }),
     )
   }

package/lib/telemetry/mlflow/tracing.js

@@ -58,12 +58,12 @@ export function mlflowTraceAttrs() {
   const attrs = {
     // OTel semconv keys MLflow reads natively for user/session display
     "session.id": session,
-    "user.id": user,
     // mlflow.traceTag.* prefix for custom trace tags
-    "mlflow.traceTag.session": session,
-    "mlflow.traceTag.user": user,
     "mlflow.traceTag.tenant": tenant,
   }
+  if (cds.env.agents?.masking?.resolveInTraces) {
+    attrs["user.id"] = user
+  }
   return attrs
 }
 

package/lib/telemetry/span-masking.js

@@ -0,0 +1,165 @@
+import cds from "@sap/cds"
+import { decode, encode } from "@toon-format/toon"
+import { pseudonymizeToolResult } from "../masking/structured/index.js"
+import { resolveRemoteMcpTool } from "../masking/index.js"
+
+const LOG = cds.log("agents")
+const REGISTERED = Symbol.for("@cap-js/agents:trace-scrubber-registered")
+
+/**
+ * Returns true when PII should be replaced with pseudonym tokens in spans.
+ * Returns false when tokens should be resolved back to originals (resolveInTraces mode).
+ */
+function mustMaskValues() {
+  if (cds.env.agents?.masking?.resolveInTraces) {
+    LOG._debug &&
+      LOG.debug(
+        `Resolving pseudonymized values in OTEL spans because "cds.env.agents.masking.resolveInTraces" = true`,
+      )
+    return false
+  }
+  return true
+}
+
+function scrubValue(value, session) {
+  if (typeof value === "string") return session.scrubText(value)
+  if (Array.isArray(value)) return value.map((item) => scrubValue(item, session))
+  if (value !== null && typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) value[k] = scrubValue(v, session)
+    return value
+  }
+  return value
+}
+
+function resolveValue(value, session) {
+  if (typeof value === "string") return session.resolveText(value)
+  if (Array.isArray(value)) return value.map((item) => resolveValue(item, session))
+  if (value !== null && typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) value[k] = resolveValue(v, session)
+    return value
+  }
+  return value
+}
+
+function transformAttributes(attrs, session, mask) {
+  if (!attrs) return
+  const transform = mask ? scrubValue : resolveValue
+  for (const [key, value] of Object.entries(attrs)) attrs[key] = transform(value, session)
+}
+
+function parseJson(value) {
+  if (typeof value !== "string") return undefined
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+function scrubToolOutputs(span, session) {
+  const attrs = span.attributes
+  if (attrs?.["mlflow.spanType"] !== "TOOL") return
+  const rawOutputs = parseJson(attrs["mlflow.spanOutputs"])
+  // rawOutputs is the parsed value of the JSON-stringified tool outputs.
+  // Only TOON-encoded strings (the success path) can be scrubbed; skip objects (error case).
+  if (typeof rawOutputs !== "string") return
+  const inputs = parseJson(attrs["mlflow.spanInputs"]) ?? {}
+
+  const remote = resolveRemoteMcpTool(attrs["gen_ai.tool.call.id"])
+  const effectiveToolName = remote?.bareName ?? attrs["gen_ai.tool.call.id"]
+  const effectiveSrv = remote?.remoteSrv
+
+  const srvName = cds.context?.["agent.service"]
+  const defaultSrv = cds.services?.[srvName]
+  const args = {
+    toolName: effectiveToolName,
+    cql: inputs.cql,
+    strictMasking: true,
+    session,
+    srv: effectiveSrv ?? defaultSrv,
+    model: cds.context?.model ?? effectiveSrv?.model ?? defaultSrv?.model,
+  }
+
+  // Decode TOON or JSON, pseudonymize decoded object, re-encode
+  let scrubbed = rawOutputs
+  try {
+    const decoded = decode(rawOutputs)
+    pseudonymizeToolResult({ decoded, ...args })
+    scrubbed = encode(decoded)
+  } catch {
+    try {
+      const decoded = JSON.parse(rawOutputs)
+      pseudonymizeToolResult({ decoded, ...args })
+      scrubbed = JSON.stringify(decoded)
+    } catch {
+      // unparseable — leave unchanged
+    }
+  }
+  attrs["mlflow.spanOutputs"] = JSON.stringify(scrubbed)
+  if (attrs["gen_ai.tool.call.result"] === rawOutputs) attrs["gen_ai.tool.call.result"] = scrubbed
+}
+
+export class MaskingSpanProcessor {
+  onStart() {}
+
+  onEnd(span) {
+    if (!cds.env.agents?.masking) return
+    const session = cds.context?.["agent.pseudonyms"]
+    if (!session) return
+
+    const mask = mustMaskValues()
+    if (mask) scrubToolOutputs(span, session)
+
+    transformAttributes(span.attributes, session, mask)
+    for (const event of span.events ?? []) transformAttributes(event.attributes, session, mask)
+    if (span.status?.message) {
+      span.status.message = mask
+        ? session.scrubText(span.status.message)
+        : session.resolveText(span.status.message)
+    }
+  }
+
+  forceFlush() {
+    return Promise.resolve()
+  }
+
+  shutdown() {
+    return Promise.resolve()
+  }
+}
+
+function registerFirst(delegate, processor) {
+  // @opentelemetry/sdk-trace-base >= 2.0: internal MultiSpanProcessor holds processors in _spanProcessors
+  if (Array.isArray(delegate._activeSpanProcessor?._spanProcessors)) {
+    delegate._activeSpanProcessor._spanProcessors.unshift(processor)
+    return true
+  }
+  // @opentelemetry/sdk-trace-base ^1.x: BasicTracerProvider exposes _registeredSpanProcessors directly
+  if (Array.isArray(delegate._registeredSpanProcessors)) {
+    delegate._registeredSpanProcessors.unshift(processor)
+    return true
+  }
+  // @opentelemetry/sdk-trace-base ^1.x fallback: public addSpanProcessor API (appends, not prepends)
+  if (typeof delegate.addSpanProcessor === "function") {
+    delegate.addSpanProcessor(processor)
+    return true
+  }
+  return false
+}
+
+export async function setupTraceScrubbing() {
+  if (!cds.env.agents?.masking) return
+  try {
+    const { trace } = await import("@opentelemetry/api")
+    const provider = trace.getTracerProvider()
+    const delegate = provider.getDelegate?.() || provider
+    if (delegate[REGISTERED]) return
+    if (!registerFirst(delegate, new MaskingSpanProcessor())) {
+      LOG.warn("Trace scrubbing: no TracerProvider with span processor support")
+      return
+    }
+    delegate[REGISTERED] = true
+  } catch (err) {
+    LOG.warn("Trace scrubbing setup failed", { error: err.message })
+  }
+}