@cap-js/agents 0.0.0 → 0.9.1

package/lib/telemetry/mlflow.js

@@ -0,0 +1,290 @@
+/**
+ * MLflow span attribute helpers for @cap-js/agents.
+ *
+ * Adds mlflow.* attributes to existing OTel spans so the MLflow OTLP
+ * ingestion endpoint can assemble them into proper MLflow traces.
+ *
+ * All functions return {} when cds.env.agents.mlflow is falsy (zero overhead).
+ *
+ * The exporter itself is configured via setupMlflowExporter() as a
+ * RoutingSpanProcessor that lazily creates per-experiment-ID exporters —
+ * existing exporters (Dynatrace, Cloud Logging, Grafana, etc.) continue
+ * to work unchanged.
+ */
+import cds from "@sap/cds"
+
+/**
+ * Resolve the MLflow experiment ID for the current request context.
+ *
+ * Resolution order:
+ *   1. @Core.SchemaVersion annotation on the service (feature-toggleable via cds.context.model)
+ *   2. cds.env.requires["mlflow"].credentials.MLFLOW_EXPERIMENT_ID
+ *   3. process.env.MLFLOW_EXPERIMENT_ID
+ *
+ * MLflow requires experiment IDs to be numeric (int64). Throws if annotation
+ * value is not a valid integer string.
+ */
+function resolveExperimentId() {
+  // Read from @Core.SchemaVersion on the active service (feature-toggle-aware)
+  const serviceName = cds.context?.["agent.service"]
+  if (serviceName) {
+    const definition =
+      cds.context?.model?.definitions?.[serviceName] || cds.services?.[serviceName]?.definition
+    const annotated = definition?.["@Core.SchemaVersion"]
+    if (annotated) {
+      const id = String(annotated)
+      if (!/^\d+$/.test(id)) {
+        throw new Error(
+          `@Core.SchemaVersion on "${serviceName}" must be a numeric string (MLflow experiment ID requires int64). Got: "${id}"`,
+        )
+      }
+      return id
+    }
+  }
+
+  // Fallback: credentials / env
+  const creds = cds.env.requires?.mlflow?.credentials || cds.env.requires?.mlflow?.credentials
+  return creds?.MLFLOW_EXPERIMENT_ID || process.env.MLFLOW_EXPERIMENT_ID
+}
+
+/**
+ * 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({
+      input_tokens: opts.tokenUsage.input_tokens,
+      output_tokens: opts.tokenUsage.output_tokens,
+      total_tokens: opts.tokenUsage.total_tokens,
+      cache_creation_input_tokens: opts.tokenUsage.cache_creation_input_tokens,
+      cache_read_input_tokens: opts.tokenUsage.cache_read_input_tokens,
+    })
+  }
+  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.
+ * @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 || "")
+  return {
+    // 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.tenant": tenant,
+  }
+}
+
+/**
+ * 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.
+ * Lazily creates an OTLPTraceExporter for each unique mlflow.experimentId
+ * seen on spans, so different services (or feature-toggled @Core.SchemaVersion
+ * values) export to the correct MLflow experiment.
+ *
+ * Supports both static headers (PAT token) and async header factories (OAuth).
+ */
+export class RoutingSpanProcessor {
+  constructor({ url, headersConfig, ucTableName, BatchSpanProcessor, OTLPTraceExporter }) {
+    this._url = url
+    this._headersConfig = headersConfig
+    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
+    this._getOrCreate(expId).onEnd(span)
+  }
+
+  _getOrCreate(experimentId) {
+    if (this._processors.has(experimentId)) return this._processors.get(experimentId)
+    const ucHeader = this._ucTableName
+      ? { "X-Databricks-UC-Table-Name": this._ucTableName }
+      : undefined
+    // Build headers — async factory or static object
+    const headers =
+      typeof this._headersConfig === "function"
+        ? async () => ({
+            ...(await this._headersConfig()),
+            "x-mlflow-experiment-id": experimentId,
+            ...ucHeader,
+          })
+        : {
+            ...this._headersConfig,
+            "x-mlflow-experiment-id": experimentId,
+            ...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()
+  }
+}
+
+/**
+ * Register MLflow OTLP RoutingSpanProcessor. No-op when credentials missing.
+ * Reads from cds.env.requires["mlflow"].credentials
+ *
+ * Auth: OAuth (clientid+clientsecret+url) takes precedence over static MLFLOW_TOKEN.
+ * UC: set UC_CATALOG + UC_SCHEMA + UC_TABLE_PREFIX for Unity Catalog trace storage.
+ */
+export async function setupMlflowExporter() {
+  if (!cds.env.agents?.mlflow) return
+
+  const LOG = cds.log("agents")
+  try {
+    const creds = cds.env.requires?.mlflow?.credentials || {}
+    const host = creds.MLFLOW_HOST
+    const token = creds.MLFLOW_TOKEN
+    const mlflowEndpoint =
+      creds.MLFLOW_OTLP_ENDPOINT || (host && `${host.replace(/\/$/, "")}/v1/traces`)
+
+    // Resolve authentication mode
+    let headersConfig
+    if (creds.clientid && creds.clientsecret) {
+      const tokenUrl = `${creds.url ?? host.replace(/\/$/, "")}/oidc/v1/token`
+      let cached = null
+      let expiresAt = 0
+      headersConfig = async function fetchToken() {
+        // Return cached token if still valid (60s buffer before expiry)
+        if (cached && Date.now() < expiresAt) return cached
+        const res = await fetch(tokenUrl, {
+          method: "POST",
+          headers: {
+            Authorization:
+              "Basic " + Buffer.from(`${creds.clientid}:${creds.clientsecret}`).toString("base64"),
+            "Content-Type": "application/x-www-form-urlencoded",
+          },
+          body: `grant_type=client_credentials&scope=all-apis`,
+          signal: AbortSignal.timeout(10_000),
+        })
+        if (!res.ok) {
+          const body = await res.text().catch(() => "")
+          const msg = `MLFlow oauth export failed: HTTP ${res.status} ${res.statusText}`
+          throw cds.error({ message: msg, response: body })
+        }
+        const { access_token, expires_in } = await res.json()
+        cached = { Authorization: `Bearer ${access_token}` }
+        expiresAt = Date.now() + (expires_in - 60) * 1000
+        return cached
+      }
+      LOG.debug("MLflow: using OAuth client credentials authentication")
+    } else if (token) {
+      headersConfig = { Authorization: `Bearer ${token}` }
+    } else {
+      headersConfig = {}
+      LOG.debug("MLflow: no auth credentials — assuming unauthenticated MLflow server")
+    }
+
+    if (!mlflowEndpoint) {
+      LOG.warn(
+        "MLflow: no endpoint configured (MLFLOW_HOST or MLFLOW_OTLP_ENDPOINT) — export disabled",
+      )
+      return
+    }
+
+    const ucCatalog = creds.UC_CATALOG
+    const ucSchema = creds.UC_SCHEMA
+    const ucTablePrefix = creds.UC_TABLE_PREFIX
+    const ucTableName =
+      ucCatalog && ucSchema && ucTablePrefix
+        ? `${ucCatalog}.${ucSchema}.${ucTablePrefix}_otel_spans`
+        : undefined
+
+    const { trace } = await import("@opentelemetry/api")
+    const provider = trace.getTracerProvider()
+    const delegate = provider.getDelegate?.() || provider
+
+    let BatchSpanProcessor, OTLPTraceExporter
+    try {
+      const { createRequire } = await import("node:module")
+      const req = createRequire(process.cwd() + "/")
+      ;({ BatchSpanProcessor } = req("@opentelemetry/sdk-trace-base"))
+      ;({ OTLPTraceExporter } = req("@opentelemetry/exporter-trace-otlp-proto"))
+    } catch (err) {
+      LOG.warn(
+        "MLflow: @opentelemetry/exporter-trace-otlp-proto not resolvable from the application. " +
+          "Install a version matching your @cap-js/telemetry major " +
+          "(v1 → ^0.57, v2 → ^0.221). Export disabled.",
+        { error: err.message },
+      )
+      return
+    }
+
+    const routing = new RoutingSpanProcessor({
+      url: mlflowEndpoint,
+      headersConfig,
+      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
+    }
+    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

@@ -0,0 +1,164 @@
+import cds from "@sap/cds"
+import * as metrics from "./metrics.js"
+import { mlflowAttrs, setSpanAttrs } from "./mlflow.js"
+import { audit } from "../utils/utils.js"
+
+const LOG = cds.log("agents")
+
+/** Symbol marking our own instrumented classes — patch skips these */
+const INSTRUMENTED = Symbol.for("@cap-js/agents:instrumented")
+
+/** Symbol marking a prototype as already patched */
+const PATCHED = Symbol.for("@cap-js/agents:patched")
+
+export async function patchTools() {
+  try {
+    const mod = await import("@langchain/core/tools")
+    if (mod.StructuredTool?.prototype) _patchToolsProto(mod.StructuredTool.prototype)
+
+    // Also patch CJS prototype (different from ESM in dual-package modules)
+    try {
+      const { createRequire } = await import("node:module")
+      const req = createRequire(import.meta.url)
+      const cjs = req("@langchain/core/tools")
+      if (cjs.StructuredTool?.prototype) _patchToolsProto(cjs.StructuredTool.prototype)
+    } catch {
+      /* CJS not available */
+    }
+  } catch (err) {
+    LOG.error("Failed to patch StructuredTool for tracing", { error: err.message })
+  }
+}
+
+export function _patchToolsProto(proto) {
+  if (proto[PATCHED]) return
+  const original = proto.invoke
+  if (typeof original !== "function") {
+    LOG.warn("StructuredTool.invoke not found — tracing patch skipped")
+    return
+  }
+
+  proto.invoke = async function (args, config) {
+    if (this[INSTRUMENTED]) return original.call(this, args, config)
+
+    const tracer = metrics.getTracer()
+    const toolName = this.name || this.constructor.name
+
+    const invoke = async (span) => {
+      if (span) {
+        span.setAttribute("gen_ai.operation.name", "execute_tool")
+        span.setAttribute("gen_ai.provider.name", "langchain")
+        span.setAttribute("gen_ai.tool.call.id", toolName)
+        const inputs = args?.args ?? args
+        setSpanAttrs(span, mlflowAttrs("TOOL", { inputs, functionName: toolName }))
+        if (LOG._debug) span.setAttribute("gen_ai.tool.call.arguments", JSON.stringify(inputs))
+      }
+      const t0 = Date.now()
+      try {
+        const result = await original.call(this, args, config)
+        const duration = Date.now() - t0
+
+        const semanticError = result?.artifact?.isError === true
+        const outcome = semanticError ? "error" : "success"
+        const outputs = result?.content ?? result
+
+        if (span) {
+          span.setAttribute("gen_ai.tool.call.outcome", outcome)
+          if (semanticError) {
+            const msg = typeof outputs === "string" ? outputs : "tool returned isError"
+            span.setAttribute("error.type", "Error")
+            span.setStatus({ code: 2, message: msg })
+            span.addEvent("exception", {
+              "exception.type": "Error",
+              "exception.message": msg,
+            })
+            setSpanAttrs(span, mlflowAttrs("TOOL", { outputs: { error: msg } }))
+          } else {
+            span.setStatus({ code: 1 })
+            setSpanAttrs(span, mlflowAttrs("TOOL", { outputs }))
+          }
+          if (LOG._debug) {
+            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) {
+          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,
+            },
+          })
+        }
+
+        return result
+      } catch (err) {
+        const duration = Date.now() - t0
+        if (span) {
+          span.setAttribute("gen_ai.tool.call.outcome", "error")
+          span.setAttribute("error.type", err.constructor?.name || "Error")
+          span.setStatus({ code: 2, message: err.message })
+          span.recordException(err)
+          setSpanAttrs(span, mlflowAttrs("TOOL", { outputs: { error: err.message } }))
+        }
+
+        metrics.toolInvocations.add(1, {
+          "sap.tenantId": cds.context?.tenant || "anonymous",
+          "agent.service": config?.configurable?._service || cds.context?.["agent.service"],
+          tool: toolName,
+          outcome: "error",
+        })
+
+        // 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()
+      }
+    }
+
+    if (tracer) {
+      return tracer.startActiveSpan(`execute_tool DynamicStructuredTool ${toolName}`, (span) =>
+        invoke(span),
+      )
+    }
+    return invoke(null)
+  }
+  proto[PATCHED] = true
+}

package/lib/telemetry/tracing.js

@@ -0,0 +1,150 @@
+import cds from "@sap/cds"
+import * as metrics from "./metrics.js"
+import { mlflowAttrs, setSpanAttrs } from "./mlflow.js"
+
+const LOG = cds.log("agents")
+
+// ─── Patching ────────────────────────────────────────────────────────────────
+
+/** Symbol marking our own instrumented classes — patch skips these */
+export const INSTRUMENTED = Symbol.for("@cap-js/agents:instrumented")
+
+/** Symbol marking a prototype as already patched */
+const PATCHED = Symbol.for("@cap-js/agents:patched")
+
+export async function patchLangChain() {
+  await patchChatModel()
+  await patchTools()
+  await patchRunnableLambda()
+  await patchRunnableSequence()
+  LOG.debug("LangChain tracing patches applied")
+}
+
+// ─── BaseChatModel (extracted to chat-tracing.js) ────────────────────────────
+
+import { patchChatModel } from "./chat-tracing.js"
+
+// ─── StructuredTool (extracted to tool-tracing.js) ───────────────────────────
+
+import { patchTools } from "./tool-tracing.js"
+
+// ─── RunnableLambda ───────────────────────────────────────────────────────────
+
+async function patchRunnableLambda() {
+  try {
+    const mod = await import("@langchain/core/runnables")
+    if (mod.RunnableLambda?.prototype) _patchRunnableLambdaProto(mod.RunnableLambda.prototype)
+
+    // Also patch CJS prototype
+    try {
+      const { createRequire } = await import("node:module")
+      const req = createRequire(import.meta.url)
+      const cjs = req("@langchain/core/runnables")
+      if (cjs.RunnableLambda?.prototype) _patchRunnableLambdaProto(cjs.RunnableLambda.prototype)
+    } catch {
+      /* CJS not available */
+    }
+  } catch (err) {
+    LOG.error("Failed to patch RunnableLambda for tracing", { error: err.message })
+  }
+}
+
+function _patchRunnableLambdaProto(proto) {
+  if (proto[PATCHED]) return
+  const original = proto.invoke
+  if (typeof original !== "function") {
+    LOG.warn("RunnableLambda.invoke not found — tracing patch skipped")
+    return
+  }
+
+  proto.invoke = async function (input, config) {
+    const tracer = metrics.getTracer()
+    if (!tracer) return original.call(this, input, config)
+
+    const name = this.name || config?.runName || this.func?.name || "anonymous"
+    return tracer.startActiveSpan(`task RunnableLambda ${name}`, async (span) => {
+      span.setAttribute("gen_ai.operation.name", "invoke_workflow")
+      span.setAttribute("gen_ai.provider.name", "langchain")
+      setSpanAttrs(span, mlflowAttrs("CHAIN", { functionName: name }))
+      if (LOG._debug) span.setAttribute("gen_ai.input.messages", JSON.stringify(input))
+      try {
+        const result = await original.call(this, input, config)
+        if (LOG._debug) {
+          span.setAttribute(
+            "gen_ai.output.messages",
+            typeof result === "string" ? result : JSON.stringify(result),
+          )
+        }
+        return result
+      } catch (err) {
+        span.setAttribute("error.type", err.constructor?.name || "Error")
+        span.setStatus({ code: 2, message: err.message })
+        throw err
+      } finally {
+        span.end()
+      }
+    })
+  }
+  proto[PATCHED] = true
+}
+
+// ─── RunnableSequence ─────────────────────────────────────────────────────────
+
+async function patchRunnableSequence() {
+  try {
+    const mod = await import("@langchain/core/runnables")
+    if (mod.RunnableSequence?.prototype) _patchRunnableSequenceProto(mod.RunnableSequence.prototype)
+
+    // Also patch CJS prototype
+    try {
+      const { createRequire } = await import("node:module")
+      const req = createRequire(import.meta.url)
+      const cjs = req("@langchain/core/runnables")
+      if (cjs.RunnableSequence?.prototype)
+        _patchRunnableSequenceProto(cjs.RunnableSequence.prototype)
+    } catch {
+      /* CJS not available */
+    }
+  } catch (err) {
+    LOG.error("Failed to patch RunnableSequence for tracing", { error: err.message })
+  }
+}
+
+function _patchRunnableSequenceProto(proto) {
+  if (proto[PATCHED]) return
+  const original = proto.invoke
+  if (typeof original !== "function") {
+    LOG.warn("RunnableSequence.invoke not found — tracing patch skipped")
+    return
+  }
+
+  proto.invoke = async function (input, config) {
+    const tracer = metrics.getTracer()
+    if (!tracer) return original.call(this, input, config)
+
+    const name = this.name || config?.runName || this.first?.name || "RunnableSequence"
+    return tracer.startActiveSpan(`workflow RunnableSequence ${name}`, async (span) => {
+      span.setAttribute("gen_ai.operation.name", "invoke_workflow")
+      span.setAttribute("gen_ai.provider.name", "langchain")
+      setSpanAttrs(span, mlflowAttrs("CHAIN", { functionName: name }))
+      if (LOG._debug) span.setAttribute("gen_ai.input.messages", JSON.stringify(input))
+      try {
+        const result = await original.call(this, input, config)
+        if (LOG._debug) {
+          span.setAttribute(
+            "gen_ai.output.messages",
+            typeof result === "string" ? result : JSON.stringify(result),
+          )
+        }
+        return result
+      } catch (err) {
+        span.setAttribute("error.type", err.constructor?.name || "Error")
+        span.setStatus({ code: 2, message: err.message })
+        throw err
+      } finally {
+        span.end()
+      }
+    })
+  }
+  proto[PATCHED] = true
+}

package/lib/utils/inner-auth.js

@@ -0,0 +1,33 @@
+import cds from "@sap/cds"
+
+/**
+ * Dev-only preview auth challenge.
+ *
+ * When a CDS service has NO service-level `@requires`/`@restrict` but SOME
+ * entity or action inside is gated, an anonymous user has no access
+ */
+export const previewAuthChallenge = (srv) => (req, res, next) => {
+  // Auth kind — only mocked participates. `dummy` is intentionally excluded
+  // (grants every role to every user — nothing to challenge). Production auth
+  // strategies (`xsuaa`, `jwt`, `ias`, ...) are untouched.
+  const auth = cds.env.requires?.auth
+  const kind = typeof auth === "string" ? auth : auth?.kind
+  if (kind !== "mocked") return next()
+
+  // Service shape — service itself must be open (else the outer 401 gate in
+  // `lib/index.js` already challenges), but something inside must be gated.
+  const def = srv?.definition
+  if (!def || def["@requires"] || def["@restrict"]) return next()
+  const hasInnerAuth =
+    Object.values(srv.entities || {}).some((e) => e["@requires"] || e["@restrict"]) ||
+    Array.from(srv.actions || []).some((a) => a["@requires"] || a["@restrict"])
+  if (!hasInnerAuth) return next()
+
+  // Caller identity — anonymous callers get the challenge.
+  const user = cds.context?.user || req?.user
+  const anonymous = !user || user._is_anonymous || user.id === "anonymous"
+  if (!anonymous) return next()
+
+  res.setHeader("WWW-Authenticate", `Basic realm="cap-agents:${srv.name}"`)
+  res.status(401).end()
+}