@cap-js/agents 0.9.1 → 0.9.3

package/srv/handlers/mcp-tools.js

@@ -1,5 +1,4 @@
 import cds from "@sap/cds"
-import { MultiServerMCPClient } from "@langchain/mcp-adapters"
 import { generateTools } from "./tools.js"
 import { toolName } from "../../lib/utils/utils.js"
 
@@ -42,48 +41,26 @@ async function resolveDestination(destinationName, dest, localUrl) {
   }
 }
 
-/**
- * Wrap MCP tool invocations to convert errors into plain string results.
- * deepagents' wrapToolCall middleware marks errors thrown inside it as
- * "middleware errors", which LangChain's ToolNode re-throws rather than
- * converting to a ToolMessage (see ToolNode.js: isMiddlewareError check).
- * MCP tool schema validation errors therefore crash the graph instead of
- * being fed back to the LLM as recoverable feedback.
- */
-function wrapToolsWithErrorHandling(tools, serviceName) {
-  return tools.map((tool) => {
-    const original = tool.invoke.bind(tool)
-    tool.invoke = async (args, config) => {
-      try {
-        return await original(args, config)
-      } catch (err) {
-        LOG.warn(`MCP tool "${tool.name}" error: ${err.message}`, { service: serviceName })
-        return `Error: ${err.message}`
-      }
-    }
-    return tool
-  })
-}
-
 export async function buildMcpToolsLocally(serviceName) {
   const srv = cds.services[serviceName]
   const tools = generateTools(srv)
   const prefix = toolName(`${serviceName}_`)
   for (const tool of tools) tool.name = `${prefix}${tool.name}`
 
-  LOG.info(
+  LOG.debug(
     `Got ${tools.length} MCP tools from ${serviceName}: ${tools.map((t) => t.name).join(", ")}`,
   )
   return tools
 }
 
 /**
- * Build LangChain tools from a CAP MCP connection.
- * Resolves the destination URL and auth headers, connects to the MCP server,
- * and returns the tools wrapped with error handling for use in agent graphs.
+ * Build a dynamic MCP placeholder from a CAP MCP connection.
+ * Resolves the destination URL and auth-header factory; the actual tools/list
+ * call is deferred to remoteMcpMiddleware which runs per-request with the
+ * current user's credentials.
  *
  * @param {string} serviceName - cds.requires service key
- * @returns {Promise<import("@langchain/core/tools").StructuredTool[]>}
+ * @returns {Promise<{ _mcpDynamic: true, mcpUrl: string, resolveHeaders: () => Promise<object> }>}
  */
 export async function buildMcpToolsFromConnection(serviceName) {
   let endpoints = cds.service.endpoints4({
@@ -94,7 +71,8 @@ export async function buildMcpToolsFromConnection(serviceName) {
   const { credentials, kind } = cds.requires[serviceName]
 
   // dest is either a string (BTP destination name) or an object { name, url, ... }
-  const destinationName = typeof credentials === "string" ? credentials : credentials?.name
+  const destinationName =
+    typeof credentials === "string" ? credentials : (credentials?.destination ?? credentials?.name)
   const localUrl =
     typeof credentials === "string"
       ? null
@@ -121,7 +99,8 @@ export async function buildMcpToolsFromConnection(serviceName) {
     )
   }
 
-  const mcpUrl = url.replace(/\/$/, "")
+  const path = typeof credentials === "object" ? credentials?.path : null
+  const mcpUrl = url.replace(/\/$/, "") + (path ? `/${path.replace(/^\//, "")}` : "")
   LOG.info(`Connecting to MCP server at ${mcpUrl}`)
 
   const resolveHeaders = async () => {
@@ -134,22 +113,7 @@ export async function buildMcpToolsFromConnection(serviceName) {
     return token ? { Authorization: `Bearer ${token}` } : {}
   }
 
-  const client = new MultiServerMCPClient({
-    mcpServers: {
-      [serviceName]: { url: mcpUrl },
-    },
-    beforeToolCall: async () => ({ headers: await resolveHeaders() }),
-  })
-
-  const tools = await client.getTools()
-  const prefix = toolName(`${serviceName}_`)
-  for (const tool of tools) tool.name = `${prefix}${tool.name}`
-
-  LOG.info(
-    `Got ${tools.length} MCP tools from ${serviceName}: ${tools.map((t) => t.name).join(", ")}`,
-  )
-
-  return wrapToolsWithErrorHandling(tools, serviceName)
+  return { _mcpDynamic: true, mcpUrl, serviceName, resolveHeaders }
 }
 
 export async function buildMcpTools(serviceName) {

package/srv/handlers/sub-agent-tools.js

@@ -2,7 +2,7 @@ import cds from "@sap/cds"
 import { tool } from "@langchain/core/tools"
 import { z } from "zod"
 import { LangGraphExecutor } from "../langgraph-executor-srv.js"
-import { toolName } from "../../lib/utils/utils.js"
+import { short, toolName } from "../../lib/utils/utils.js"
 
 const LOG = cds.log("agents:sub-agents")
 
@@ -164,6 +164,7 @@ export async function buildSubAgentToolLocally(serviceName) {
         taskId,
         contextId,
       )
+      const truncated = message?.length > 80 ? message.slice(0, 80) + "..." : message
 
       try {
         // Run the sub-agent detached from the calling agent, in its own root
@@ -172,6 +173,12 @@ export async function buildSubAgentToolLocally(serviceName) {
         await new Promise((resolve, reject) => {
           cds
             .spawn({ user: cds.context?.user, tenant: cds.context?.tenant }, async () => {
+              LOG.info("request", {
+                conversation: short(contextId),
+                service: srv.name,
+                text: truncated,
+              })
+
               await executor.execute(requestContext, eventBus)
               await done
             })
@@ -206,7 +213,8 @@ export async function buildSubAgentToolFromConnection(serviceName) {
   endpoints = Object.fromEntries(endpoints.map((o) => [o.kind, o.path]))
   const { credentials, kind } = cds.requires[serviceName]
 
-  const destinationName = typeof credentials === "string" ? credentials : credentials?.name
+  const destinationName =
+    typeof credentials === "string" ? credentials : (credentials?.destination ?? credentials?.name)
   const localUrl =
     typeof credentials === "string"
       ? null
@@ -270,7 +278,8 @@ export async function buildSubAgentToolFromConnection(serviceName) {
     )
   }
 
-  const base = agentBaseUrl.replace(/\/$/, "")
+  const path = typeof credentials === "object" ? credentials?.path : null
+  const base = agentBaseUrl.replace(/\/$/, "") + (path ? `/${path.replace(/^\//, "")}` : "")
   LOG.info(`Connecting to sub-agent at ${base}`)
 
   // revisit: a2a agents may be tenant specific, card per tenant?

package/srv/handlers/tools.js

@@ -11,7 +11,7 @@ import {
   executeCallActionTool,
   executePerActionTool,
 } from "@cap-js/mcp/lib/tools.js"
-import { getFilteredEntities, getFilteredActions } from "../../lib/utils/utils.js"
+import { getFilteredEntities, getFilteredActions, getAgentLogger } from "../../lib/utils/utils.js"
 import { isTextMime } from "../../lib/agents/markdown/backends/mime-utils.js"
 import { checkAuthorization } from "@cap-js/mcp/lib/auth.js"
 
@@ -31,6 +31,7 @@ function cachedAuth(srv) {
 
 class GenericReadTool extends DynamicStructuredTool {
   constructor(srv, entities) {
+    const log = getAgentLogger(srv)
     const def = createGenericReadToolDefinition(Object.keys(entities), srv.name, "")
     super({
       name: def.name,
@@ -38,7 +39,7 @@ class GenericReadTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeGenericReadTool(srv, entities, args, { log: LOG }))
+        return unwrap(await executeGenericReadTool(srv, entities, args, { log }))
       },
     })
     this.srv = srv
@@ -67,6 +68,7 @@ class GenericReadTool extends DynamicStructuredTool {
 
 class DescribeTool extends DynamicStructuredTool {
   constructor(srv, entities, actions) {
+    const log = getAgentLogger(srv)
     const def = createDescribeToolDefinition(
       Object.keys(entities),
       Object.keys(actions),
@@ -79,7 +81,7 @@ class DescribeTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeDescribe(srv, entities, actions, args, { log: LOG }))
+        return unwrap(await executeDescribe(srv, entities, actions, args, { log }))
       },
     })
     this.srv = srv
@@ -119,6 +121,7 @@ class DescribeTool extends DynamicStructuredTool {
 
 class PerActionTool extends DynamicStructuredTool {
   constructor(srv, actionName, action) {
+    const log = getAgentLogger(srv)
     const def = createPerActionToolDefinition(actionName, action, srv.name, srv.model, "")
     super({
       name: def.name,
@@ -126,7 +129,7 @@ class PerActionTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executePerActionTool(srv, actionName, action, args, { log: LOG }))
+        return unwrap(await executePerActionTool(srv, actionName, action, args, { log }))
       },
     })
     this.srv = srv
@@ -142,6 +145,7 @@ class PerActionTool extends DynamicStructuredTool {
 
 class CallActionTool extends DynamicStructuredTool {
   constructor(srv, actions) {
+    const log = getAgentLogger(srv)
     const def = createCallActionToolDefinition(Object.keys(actions), srv.name, "")
     super({
       name: def.name,
@@ -149,7 +153,7 @@ class CallActionTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeCallActionTool(srv, actions, args, { log: LOG }))
+        return unwrap(await executeCallActionTool(srv, actions, args, { log }))
       },
     })
     this.srv = srv

package/lib/telemetry/mlflow.js

@@ -1,290 +0,0 @@
-/**
- * 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 })
-  }
-}