@cap-js/agents 0.9.1 → 0.9.3

package/lib/telemetry/mlflow/tracing.js

@@ -0,0 +1,264 @@
+import cds from "@sap/cds"
+import { resolveMlflowCredentials, resolveExperimentId } from "./credentials.js"
+import { resolvePromptName, linkedPromptsAttr } from "./prompts.js"
+
+// Validated wrapper: throws when @Core.SchemaVersion is present but non-numeric,
+// since MLflow experiment IDs must be int64.
+function _resolveExperimentId() {
+  const srvName = cds.context?.["agent.service"]
+  if (srvName) {
+    const def = cds.context?.model?.definitions?.[srvName] || cds.services?.[srvName]?.definition
+    const annotated = def?.["@Core.SchemaVersion"]
+    if (annotated) {
+      const id = String(annotated)
+      if (!/^\d+$/.test(id))
+        throw new Error(
+          `@Core.SchemaVersion on "${srvName}" must be a numeric string (MLflow experiment ID requires int64). Got: "${id}"`,
+        )
+      return id
+    }
+  }
+  return resolveExperimentId()
+}
+
+/**
+ * Build mlflow.* span attributes for a given span type.
+ * @param {"LLM"|"AGENT"|"TOOL"|"CHAIN"|"RETRIEVER"} spanType
+ * @param {{ inputs?: any, outputs?: any, model?: string, provider?: string, functionName?: string, tokenUsage?: object }} [opts]
+ * @returns {Record<string, string>} Attributes to set on span, or {} when disabled
+ */
+export function mlflowAttrs(spanType, opts = {}) {
+  if (!cds.env.agents?.mlflow) return {}
+  const experimentId = _resolveExperimentId()
+  const attrs = {}
+  if (experimentId) attrs["mlflow.experimentId"] = String(experimentId)
+  attrs["mlflow.spanType"] = spanType
+  if (opts.model) attrs["mlflow.llm.model"] = String(opts.model)
+  if (opts.provider) attrs["mlflow.llm.provider"] = String(opts.provider)
+  if (opts.functionName) attrs["mlflow.spanFunctionName"] = String(opts.functionName)
+  if (opts.inputs !== undefined) attrs["mlflow.spanInputs"] = JSON.stringify(opts.inputs)
+  if (opts.outputs !== undefined) attrs["mlflow.spanOutputs"] = JSON.stringify(opts.outputs)
+  if (opts.tokenUsage) attrs["mlflow.chat.tokenUsage"] = JSON.stringify(opts.tokenUsage)
+  return attrs
+}
+
+/**
+ * Build mlflow trace-level tag attributes (set on root/workflow span).
+ * Uses mlflow.traceTag.* prefix so MLflow server extracts them as trace tags.
+ * Also sets OTel semconv user.id and session.id which MLflow reads natively.
+ * When a system prompt is registered, adds mlflow.traceTag.mlflow.linkedPrompts
+ * so MLflow links this trace to the prompt version — no extra REST call needed.
+ * @returns {Record<string, string>} Attributes to set on root span, or {} when disabled
+ */
+export function mlflowTraceAttrs() {
+  if (!cds.env.agents?.mlflow) return {}
+  const session = String(cds.context?.["agent.context.id"] || "")
+  const user = String(cds.context?.user?.id || "")
+  const tenant = String(cds.context?.tenant || "")
+  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,
+  }
+  return attrs
+}
+
+export function linkTraceToPrompt() {
+  if (!cds.env.agents?.mlflow) return {}
+  const srvName = cds.context?.["agent.service"]
+  const srv = cds.services[srvName]
+  const linked = srv ? linkedPromptsAttr(resolvePromptName(srv)) : null
+  if (linked) {
+    return { "mlflow.traceTag.mlflow.linkedPrompts": linked }
+  }
+  return {}
+}
+
+/**
+ * Spread attributes object onto an OTel span (null-safe).
+ * Coerces all values to strings to prevent [object Object] in downstream systems.
+ * @param {import("@opentelemetry/api").Span | null} span
+ * @param {Record<string, string>} attrs
+ */
+export function setSpanAttrs(span, attrs) {
+  if (!cds.env.agents?.mlflow) return
+  if (!span) return
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v !== undefined && v !== null) span.setAttribute(k, v)
+  }
+}
+
+/**
+ * SpanProcessor that routes spans to per-experiment-ID BatchSpanProcessors.
+ * One OTLPTraceExporter per unique mlflow.experimentId
+ */
+export class RoutingSpanProcessor {
+  /**
+   * @param {{ url: string, token?: string, getAuthHeaders?: () => Promise<Record<string,string>>,
+   *           ucTableName?: string, BatchSpanProcessor: any, OTLPTraceExporter: any }} opts
+   *
+   * Auth: `getAuthHeaders` (async, OAuth-capable) takes precedence over static `token`.
+   * UC:   When `ucTableName` is provided it is added as `X-Databricks-UC-Table-Name` header.
+   */
+  constructor({ url, token, getAuthHeaders, ucTableName, BatchSpanProcessor, OTLPTraceExporter }) {
+    this._url = url
+    // OAuth factory (async) takes precedence over static token.
+    // When only a static token is given, keep headers as a plain object so
+    // OTLPTraceExporter can use them synchronously (and tests can inspect them directly).
+    this._getAuthHeaders = getAuthHeaders ?? null
+    this._staticToken = token ?? null
+    this._ucTableName = ucTableName
+    this._BatchSpanProcessor = BatchSpanProcessor
+    this._OTLPTraceExporter = OTLPTraceExporter
+    this._processors = new Map()
+  }
+
+  onStart() {}
+
+  onEnd(span) {
+    const expId = span.attributes?.["mlflow.experimentId"]
+    if (!expId) return
+    // If this span carries a run ID, update the per-experiment map so the
+    // OTLP exporter for this experiment sends x-mlflow-run-id on the next flush.
+    const sourceRun = span.attributes?.["mlflow.sourceRun"]
+    if (sourceRun) _runIdByExperiment.set(expId, sourceRun)
+    else if (!_runIdByExperiment.has(expId)) _runIdByExperiment.delete(expId)
+    this._getOrCreate(expId).onEnd(span)
+  }
+
+  _getOrCreate(experimentId) {
+    if (this._processors.has(experimentId)) return this._processors.get(experimentId)
+    const ucTableName = this._ucTableName
+    const expHeader = { "x-mlflow-experiment-id": experimentId }
+    const ucHeader = ucTableName ? { "X-Databricks-UC-Table-Name": ucTableName } : {}
+
+    let headers
+    if (this._getAuthHeaders) {
+      // OAuth / async path — factory is called at export time, so run ID is resolved
+      // dynamically from _runIdByExperiment without needing to recreate the exporter.
+      const getAuthHeaders = this._getAuthHeaders
+      headers = async () => {
+        const runId = _runIdByExperiment.get(experimentId)
+        return {
+          ...(await getAuthHeaders()),
+          ...expHeader,
+          ...ucHeader,
+          ...(runId ? { "x-mlflow-run-id": runId } : {}),
+        }
+      }
+    } else {
+      // Static token path — plain object so OTLPTraceExporter and tests can read it directly.
+      const authHeader = this._staticToken ? { Authorization: `Bearer ${this._staticToken}` } : {}
+      headers = { ...authHeader, ...expHeader, ...ucHeader }
+    }
+
+    const exporter = new this._OTLPTraceExporter({ url: this._url, headers })
+    const proc = new this._BatchSpanProcessor(exporter)
+    this._processors.set(experimentId, proc)
+    return proc
+  }
+
+  async forceFlush() {
+    await Promise.all([...this._processors.values()].map((p) => p.forceFlush()))
+  }
+
+  async shutdown() {
+    await Promise.all([...this._processors.values()].map((p) => p.shutdown()))
+    this._processors.clear()
+  }
+}
+
+/** Module-level singleton — set by setupMlflowExporter(), used as fast path by flushMlflowTraces(). */
+let _routing = null
+
+/**
+ * Run IDs keyed by experiment ID — populated by RoutingSpanProcessor.onEnd()
+ * when a span carries mlflow.sourceRun. The OTLP header factory reads this
+ * at export time to include x-mlflow-run-id on the batch.
+ */
+const _runIdByExperiment = new Map()
+
+/**
+ * Force-flush all pending MLflow OTLP spans to the remote server.
+ */
+export async function flushMlflowTraces() {
+  try {
+    const { trace } = await import("@opentelemetry/api")
+    const provider = trace.getTracerProvider()
+    const delegate = provider.getDelegate?.() || provider
+    if (typeof delegate.forceFlush === "function") {
+      await delegate.forceFlush()
+      return
+    }
+  } catch {
+    // @opentelemetry/api not available — fall through
+  }
+  // Fallback: flush via the singleton registered in this module instance
+  await _routing?.forceFlush()
+}
+
+/**
+ * Register MLflow OTLP RoutingSpanProcessor.
+ * No-op when credentials are missing.
+ */
+export async function setupMlflowExporter() {
+  if (!cds.env.agents?.mlflow) return
+
+  const LOG = cds.log("agent")
+  try {
+    const mlflowCreds = resolveMlflowCredentials()
+    const creds = cds.env.requires?.mlflow?.credentials || {}
+    const mlflowEndpoint =
+      creds.MLFLOW_OTLP_ENDPOINT || (mlflowCreds?.host && `${mlflowCreds.host}/v1/traces`)
+
+    if (!mlflowEndpoint) {
+      LOG.warn(
+        "MLflow: credentials missing (MLFLOW_HOST or MLFLOW_OTLP_ENDPOINT) — export disabled",
+      )
+      return
+    }
+
+    const ucTableName = mlflowCreds?.uc
+      ? `${mlflowCreds.uc.catalog}.${mlflowCreds.uc.schema}.${mlflowCreds.uc.tablePrefix}_otel_spans`
+      : undefined
+
+    const { trace } = await import("@opentelemetry/api")
+    const provider = trace.getTracerProvider()
+    const delegate = provider.getDelegate?.() || provider
+
+    const { BatchSpanProcessor } = await import("@opentelemetry/sdk-trace-base")
+    const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-proto")
+
+    const routing = new RoutingSpanProcessor({
+      url: mlflowEndpoint,
+      getAuthHeaders: mlflowCreds?.getAuthHeaders ?? (async () => ({})),
+      ucTableName,
+      BatchSpanProcessor,
+      OTLPTraceExporter,
+    })
+
+    if (delegate.addSpanProcessor) {
+      // OTEL SDK v1
+      delegate.addSpanProcessor(routing)
+    } else if (delegate._activeSpanProcessor?._spanProcessors) {
+      // OTEL SDK v2: no addSpanProcessor — push into MultiSpanProcessor
+      delegate._activeSpanProcessor._spanProcessors.push(routing)
+    } else {
+      LOG.warn(
+        "MLflow: no TracerProvider with addSpanProcessor — ensure @cap-js/telemetry is loaded",
+      )
+      return
+    }
+    _routing = routing
+    LOG.info("MLflow: routing span processor added (per-experiment export)", {
+      endpoint: mlflowEndpoint,
+      ...(ucTableName && { ucTableName }),
+    })
+  } catch (err) {
+    LOG.error("MLflow: failed to configure OTLP export", { error: err.message })
+  }
+}

package/lib/telemetry/tool-tracing.js

@@ -1,6 +1,6 @@
 import cds from "@sap/cds"
 import * as metrics from "./metrics.js"
-import { mlflowAttrs, setSpanAttrs } from "./mlflow.js"
+import { mlflowAttrs, setSpanAttrs } from "./mlflow/index.js"
 import { audit } from "../utils/utils.js"
 
 const LOG = cds.log("agents")
@@ -45,6 +45,7 @@ export function _patchToolsProto(proto) {
     const toolName = this.name || this.constructor.name
 
     const invoke = async (span) => {
+      const t0 = Date.now()
       if (span) {
         span.setAttribute("gen_ai.operation.name", "execute_tool")
         span.setAttribute("gen_ai.provider.name", "langchain")
@@ -53,13 +54,16 @@ export function _patchToolsProto(proto) {
         setSpanAttrs(span, mlflowAttrs("TOOL", { inputs, functionName: toolName }))
         if (LOG._debug) span.setAttribute("gen_ai.tool.call.arguments", JSON.stringify(inputs))
       }
-      const t0 = Date.now()
+      const taskId = config?.configurable?._taskId || cds.context?.["agent.task.id"]
+      let outcome
+      let errorMessage
+      let duration
       try {
         const result = await original.call(this, args, config)
-        const duration = Date.now() - t0
+        duration = Date.now() - t0
 
         const semanticError = result?.artifact?.isError === true
-        const outcome = semanticError ? "error" : "success"
+        outcome = semanticError ? "error" : "success"
         const outputs = result?.content ?? result
 
         if (span) {
@@ -81,36 +85,16 @@ export function _patchToolsProto(proto) {
             span.setAttribute("gen_ai.tool.call.result", outputs)
           }
         }
-
-        metrics.toolInvocations.add(1, {
-          "sap.tenantId": cds.context?.tenant || "anonymous",
-          "agent.service": config?.configurable?._service || cds.context?.["agent.service"],
-          tool: toolName,
-          outcome,
-        })
-
-        // Audit: record tool invocation
-        const taskId = config?.configurable?._taskId || cds.context?.["agent.task.id"]
-        if (taskId) {
+        if (semanticError) {
           const resultStr = typeof outputs === "string" ? outputs : JSON.stringify(outputs)
-          audit("ToolInvocation", {
-            data: {
-              taskId,
-              service: config?.configurable?._service || cds.context?.["agent.service"],
-              tool: toolName,
-              args,
-              outcome,
-              ...(semanticError
-                ? { error: resultStr?.slice(0, 2000) }
-                : { result: resultStr?.slice(0, 2000) }),
-              duration,
-            },
-          })
+          errorMessage = resultStr
         }
 
         return result
       } catch (err) {
-        const duration = Date.now() - t0
+        duration = Date.now() - t0
+        outcome = "error"
+        errorMessage = err.message
         if (span) {
           span.setAttribute("gen_ai.tool.call.outcome", "error")
           span.setAttribute("error.type", err.constructor?.name || "Error")
@@ -119,36 +103,25 @@ export function _patchToolsProto(proto) {
           setSpanAttrs(span, mlflowAttrs("TOOL", { outputs: { error: err.message } }))
         }
 
+        throw err
+      } finally {
         metrics.toolInvocations.add(1, {
           "sap.tenantId": cds.context?.tenant || "anonymous",
           "agent.service": config?.configurable?._service || cds.context?.["agent.service"],
           tool: toolName,
-          outcome: "error",
+          outcome,
+        })
+        audit("ToolInvocation", {
+          data: {
+            taskId,
+            service: config?.configurable?._service || cds.context?.["agent.service"],
+            tool: toolName,
+            args,
+            outcome,
+            ...(outcome === "error" ? { error: errorMessage } : {}),
+            duration,
+          },
         })
-
-        // Audit: record failed tool invocation
-        const taskId = config?.configurable?._taskId || cds.context?.["agent.task.id"]
-        if (taskId) {
-          audit("ToolInvocation", {
-            data: {
-              taskId,
-              service: config?.configurable?._service || cds.context?.["agent.service"],
-              tool: toolName,
-              args,
-              outcome: "error",
-              error: err.message,
-              duration,
-            },
-          })
-        }
-
-        // Swallow error: return as string so LLM can see it and retry.
-        // Deep agents use ToolNode with handleToolErrors (default: true) which
-        // already wraps errors as ToolMessages. Custom graphs that invoke tools
-        // directly also benefit from error swallowing — the graph continues and
-        // the LLM can retry with a corrected query.
-        return `Error: ${err.message}`
-      } finally {
         if (span) span.end()
       }
     }

package/lib/telemetry/tracing.js

@@ -1,6 +1,6 @@
 import cds from "@sap/cds"
 import * as metrics from "./metrics.js"
-import { mlflowAttrs, setSpanAttrs } from "./mlflow.js"
+import { mlflowAttrs, setSpanAttrs } from "./mlflow/index.js"
 
 const LOG = cds.log("agents")
 
@@ -121,6 +121,8 @@ function _patchRunnableSequenceProto(proto) {
   proto.invoke = async function (input, config) {
     const tracer = metrics.getTracer()
     if (!tracer) return original.call(this, input, config)
+    // Skip invokes fired during graph compilation, which would create orphan spans.
+    if (!cds.context?.["agent.service"]) return original.call(this, input, config)
 
     const name = this.name || config?.runName || this.first?.name || "RunnableSequence"
     return tracer.startActiveSpan(`workflow RunnableSequence ${name}`, async (span) => {

package/lib/utils/markdown.js

@@ -1,18 +1,8 @@
 import cds from "@sap/cds"
+import { slugified } from "./utils.js"
 const { path, fs } = cds.utils
 const LOG = cds.log("agents")
 
-/**
- * Mirrors CAP's internal slug rules used for service path generation.
- */
-export const slugified = (name) =>
-  /[^.]+$/
-    .exec(name)[0]
-    .replace(/Service$/, "")
-    .replace(/_/g, "-")
-    .replace(/([a-z0-9])([A-Z])/g, (_m, c, C) => c + "-" + C)
-    .toLowerCase()
-
 /**
  * Absolute filesystem directory of the `.cds` source file that defines `srv`.
  */

package/lib/utils/resilience.js

@@ -0,0 +1,133 @@
+import cds from "@sap/cds"
+
+const LOG = cds.log("agents")
+
+const DEFAULT_TIMEOUT_MS = 10_000
+const DEFAULT_RETRIES = 3
+const BACKOFF_BASE_MS = 1_000
+const BACKOFF_MAX_MS = 32_000
+
+/**
+ * Resilience middleware for the SAP AI SDK HTTP layer.
+ * Contract: (options: { fn, context: { uri, tenantId } }) => (arg) => Promise
+ * Compose right-to-left: [timeout(t), circuitBreaker()] wraps timeout around
+ * circuit breaker around the request.
+ */
+
+export function timeout(ms = DEFAULT_TIMEOUT_MS) {
+  if (ms < 0) throw new Error("Timeout must be greater or equal to 0.")
+  if (ms > 0 && ms < 10)
+    LOG.warn(`The timeout of ${ms} ms is too low. Make sure this is not intentional.`)
+
+  return ({ fn, context }) =>
+    (arg) => {
+      if (ms === 0) return fn(arg)
+      const controller = new AbortController()
+      const signal = arg?.signal
+        ? AbortSignal.any([arg.signal, controller.signal])
+        : controller.signal
+      const request = arg && typeof arg === "object" ? { ...arg, signal } : arg
+      let timer
+      const call = fn(request).finally(() => clearTimeout(timer))
+      const race = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort()
+          reject(new Error(`Request to URL: ${context?.uri} ran into a timeout after ${ms}ms.`))
+        }, ms)
+      })
+      return Promise.race([call, race])
+    }
+}
+
+// Retries on 5xx / network errors; bails immediately on 4xx.
+export function retry(retries = DEFAULT_RETRIES) {
+  if (retries < 0) throw new Error("Number of retries must be greater or equal to 0.")
+
+  return ({ fn }) =>
+    async (arg) => {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          return await fn(arg) // eslint-disable-line no-await-in-loop
+        } catch (error) {
+          const status = error?.response?.status
+          if (status == null)
+            LOG.debug("HTTP request failed without a response status. Rethrowing.")
+          else if (`${status}`.startsWith("4"))
+            throw Object.assign(new Error(`Request failed with status code ${status}`), {
+              cause: error,
+            })
+          if (attempt >= retries) throw error
+          const delay =
+            Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** attempt) * (1 + Math.random())
+          await new Promise((r) => setTimeout(r, delay)) // eslint-disable-line no-await-in-loop
+        }
+      }
+    }
+}
+
+// One breaker per uri. Opens after volumeThreshold calls exceed the
+// error rate; fails fast with EOPENBREAKER while open. 4xx never trips it.
+export const circuitBreakers = {}
+
+export function circuitBreaker() {
+  return ({ fn, context }) =>
+    (arg) => {
+      const key = context?.uri ?? "default"
+      circuitBreakers[key] ??= new CircuitBreaker()
+      return circuitBreakers[key].fire(fn, arg)
+    }
+}
+
+class CircuitBreaker {
+  #state = "closed"
+  #openedAt = 0
+  #window = []
+
+  async fire(fn, arg) {
+    const now = Date.now()
+    const opts = cds.env.agents.circuitBreaker
+    if (this.#state === "open") {
+      if (now - this.#openedAt < opts.resetTimeout)
+        throw Object.assign(new Error("Breaker is open"), { code: "EOPENBREAKER" })
+      this.#state = "half-open"
+    }
+    try {
+      const result = await fn(arg)
+      if (this.#state === "half-open") this.#reset("closed")
+      else this.#record(true, now)
+      return result
+    } catch (error) {
+      if (!`${error?.response?.status}`.startsWith("4")) this.#onError(now)
+      throw error
+    }
+  }
+
+  #onError(now) {
+    if (this.#state === "half-open") {
+      this.#reset("open", now)
+      return
+    }
+    this.#record(false, now)
+    if (this.#shouldOpen()) this.#reset("open", now)
+  }
+
+  #record(success, now) {
+    const { rollingCountTimeout } = cds.env.agents.circuitBreaker
+    const cutoff = now - rollingCountTimeout
+    while (this.#window.length && this.#window[0].t < cutoff) this.#window.shift()
+    this.#window.push({ success, t: now })
+  }
+
+  #shouldOpen() {
+    const { volumeThreshold, errorThresholdPercentage } = cds.env.agents.circuitBreaker
+    if (this.#window.length < volumeThreshold) return false
+    const failures = this.#window.filter((o) => !o.success).length
+    return (failures / this.#window.length) * 100 >= errorThresholdPercentage
+  }
+
+  #reset(state, openedAt = 0) {
+    this.#state = state
+    this.#openedAt = openedAt
+    this.#window = []
+  }
+}

package/lib/utils/utils.js

@@ -10,6 +10,23 @@ function resolveI18n(value, locale) {
   return value
 }
 
+export function getAgentLogger(srv) {
+  const slug = slugified(srv.name)
+  const agentSlug = slug.endsWith("-agent") ? slug : `${slug}-agent`
+  return cds.log("agents:" + srv.name, { label: agentSlug })
+}
+
+/**
+ * Mirrors CAP's internal slug rules used for service path generation.
+ */
+export const slugified = (name) =>
+  /[^.]+$/
+    .exec(name)[0]
+    .replace(/Service$/, "")
+    .replace(/_/g, "-")
+    .replace(/([a-z0-9])([A-Z])/g, (_m, c, C) => c + "-" + C)
+    .toLowerCase()
+
 export function getDescription(obj, locale) {
   locale = locale || cds.context?.locale || "en"