@cap-js/agents 0.9.2 → 0.9.3

package/srv/handlers/chat.js

@@ -0,0 +1,278 @@
+import cds from "@sap/cds"
+import { startCollection } from "../../lib/eval/span-collector.js"
+import { metricsFromSpans } from "../../lib/eval/metrics.js"
+import { getActiveRunState, logMlflowMetricsForResult } from "../../lib/eval/eval-run.js"
+
+export const COLLECT_RESULT = Symbol.for("@cap-js/agents:chat:collect-result")
+
+class NoopEventBus {
+  constructor() {
+    this.events = []
+    this[COLLECT_RESULT] = true
+    this._graphResult = null
+    this._done = false
+    this.finished$ = new Promise((resolve, reject) => {
+      this._resolve = resolve
+      this._reject = reject
+    })
+  }
+
+  publish(event) {
+    this.events.push(event)
+  }
+
+  finished() {
+    this._done = true
+    this._resolve?.()
+  }
+
+  error(err) {
+    this._reject?.(err)
+  }
+
+  getFinalText() {
+    for (let i = this.events.length - 1; i >= 0; i--) {
+      const e = this.events[i]
+      if (e.kind === "artifact-update" && e.lastChunk === true) {
+        const text = e.artifact?.parts
+          ?.filter((p) => p.kind === "text")
+          .map((p) => p.text)
+          .join("")
+        if (text) return text
+      }
+    }
+    for (let i = this.events.length - 1; i >= 0; i--) {
+      const e = this.events[i]
+      if (e.kind === "status-update" && e.status?.message?.parts) {
+        const text = e.status.message.parts
+          .filter((p) => p.kind === "text")
+          .map((p) => p.text)
+          .join("")
+        if (text) return text
+      }
+    }
+    return ""
+  }
+
+  getStatus() {
+    const e = this.events.at(-1)
+    if (e && e.kind === "status-update" && e.status?.state) {
+      const state = e.status.state
+      const msg = e.status?.message?.parts?.find((p) => p.kind === "text")?.text ?? ""
+      return { status: state, description: msg }
+    }
+    return { status: "completed", description: "" }
+  }
+}
+
+// Derive toolCalls from graph messages by pairing AIMessage.tool_calls with ToolMessage results.
+function toolCallsFromMessages(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return []
+
+  const resultById = new Map()
+  for (const msg of messages) {
+    if (msg.tool_call_id && msg.type === "tool") {
+      const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content)
+      resultById.set(msg.tool_call_id, content)
+    }
+  }
+
+  const entries = []
+  for (const msg of messages) {
+    if (!Array.isArray(msg.tool_calls) || msg.tool_calls.length === 0) continue
+    for (const tc of msg.tool_calls) {
+      const raw = resultById.get(tc.id)
+      let toolResult
+      try {
+        toolResult = raw !== undefined ? JSON.parse(raw) : undefined
+      } catch {
+        toolResult = raw
+      }
+      const entry = {
+        tool: tc.name,
+        args: tc.args ?? {},
+        outcome: "success",
+        ...(toolResult !== undefined && { result: toolResult }),
+      }
+      attachCqn(entry)
+      entries.push(entry)
+    }
+  }
+  return entries
+}
+
+/**
+ * If entry.args.cql attaches cqn as hidden property.
+ * No-op when cql is absent or faulty.
+ */
+function attachCqn(entry) {
+  const cql = entry.args?.cql
+  if (typeof cql !== "string") return
+  try {
+    const cqn = cds.parse.cql(cql)
+    Object.defineProperty(entry, "cqn", {
+      value: cqn,
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    })
+  } catch {
+    /* unparseable CQL — skip */
+  }
+}
+
+function buildRequestContext(query, opts = {}) {
+  const taskId = opts.taskId || cds.utils.uuid()
+  const contextId = opts.contextId || cds.utils.uuid()
+  const parts =
+    opts.parts ??
+    (typeof query === "string"
+      ? [{ kind: "text", text: query }]
+      : (query?.parts ?? [{ kind: "text", text: String(query) }]))
+  return {
+    taskId,
+    contextId,
+    task: opts.task ?? null,
+    userMessage: {
+      kind: "message",
+      messageId: cds.utils.uuid(),
+      role: "user",
+      taskId,
+      contextId,
+      parts,
+    },
+  }
+}
+
+/** Install srv.chat(query, previous?) on an @agent service for eval tests. */
+export function registerChat(srv) {
+  srv.chat = async function chat(query, previous) {
+    // Resolve the small eval helper API:
+    //   chat(query)
+    //   chat(query, prevResult) — extract contextId + taskId for HITL resume
+    //   chat(query, { _details: true }) — internal/test escape hatch outside test profile
+    let opts = {}
+    if (typeof previous === "string") {
+      throw new TypeError(
+        "agent.chat: second argument must be a previous chat result object or options object",
+      )
+    } else if (previous && typeof previous === "object") {
+      if ("text" in previous || "contextId" in previous) {
+        // prior chat() result — extract conversation ids and HITL state
+        opts = {
+          contextId: previous.contextId,
+          // mark as resume when prior result was input-required
+          ...(previous.status === "input-required" && {
+            taskId: previous.taskId,
+            task: { id: previous.taskId, status: { state: "input-required" } },
+          }),
+        }
+      } else {
+        opts = { _details: previous._details === true }
+      }
+    }
+
+    const includeDetails = shouldIncludeChatDetails(opts)
+    const runState = includeDetails ? getActiveRunState() : null
+
+    // Open span collection session before execution so the processor
+    // captures all spans from this trace.
+    const collection = includeDetails ? await startCollection() : null
+
+    const { LangGraphExecutor } = await import("../langgraph-executor-srv.js")
+    const executor = LangGraphExecutor.for(srv)
+    const requestContext = buildRequestContext(query, opts)
+    const eventBus = new NoopEventBus()
+    const mlflowRunId = runState?.mlflowRunId
+    let traceId
+
+    const runInContext = async () => {
+      // Link the trace to the MLflow eval run — graph-executor reads this to set mlflow.sourceRun.
+      if (mlflowRunId && cds.context) cds.context["_mlflow.evalRunId"] = mlflowRunId
+
+      let execError = null
+      const execPromise = executor.execute(requestContext, eventBus).catch((err) => {
+        execError = err
+        if (!eventBus._done) eventBus.finished()
+      })
+      await Promise.race([eventBus.finished$, execPromise])
+      if (!eventBus._done) eventBus.finished()
+      if (execError) throw execError
+
+      if (includeDetails) {
+        const rootSpan = cds.context?.["_mlflow.rootSpan"]
+        if (rootSpan) traceId = rootSpan.spanContext?.()?.traceId
+      }
+    }
+
+    if (cds.context) {
+      await runInContext()
+    } else {
+      await cds._with(
+        new cds.EventContext({ tenant: "t0", user: new cds.User.Privileged() }),
+        runInContext,
+      )
+    }
+
+    const { status, description } = eventBus.getStatus()
+    if (status === "failed")
+      throw new Error(`agent.chat: task failed — ${description || "no message"}`)
+
+    const text = eventBus.getFinalText()
+    const result = {
+      text,
+      contextId: requestContext.contextId,
+      taskId: requestContext.taskId,
+      status,
+    }
+
+    if (includeDetails) {
+      const allMessages = eventBus._graphResult?.messages ?? []
+
+      // Find last HumanMessage whose text matches current query; return from there.
+      const queryText = String(query)
+      let turnStart = 0
+      for (let i = allMessages.length - 1; i >= 0; i--) {
+        const m = allMessages[i]
+        if (m.getType?.() === "human" || m._getType?.() === "human" || m.type === "human") {
+          const content = typeof m.content === "string" ? m.content : (m.content?.[0]?.text ?? "")
+          if (content.startsWith(queryText) || queryText.startsWith(content.trim())) {
+            turnStart = i
+            break
+          }
+        }
+      }
+      const messages = allMessages.slice(turnStart)
+      const toolCalls = toolCallsFromMessages(messages)
+
+      const allSpans = collection.collect()
+      const spans = traceId
+        ? allSpans.filter((s) => s.spanContext?.()?.traceId === traceId)
+        : allSpans
+
+      result.query = String(query)
+      result.traceId = traceId
+      result.toolCalls = toolCalls
+      result.messages = messages.map((m) => {
+        // Eval prompts expect text content, not content-block objects.
+        if (m.type === "ai") {
+          if (Array.isArray(m.content) && m.content[0]?.text) {
+            m.content = m.content[0].text
+          }
+        }
+        return m
+      })
+      result.spans = spans
+      result.metrics = metricsFromSpans(spans)
+      if (runState) result._evalState = runState
+      // Post metrics to MLflow ootb — fire-and-forget.
+      logMlflowMetricsForResult(result, runState).catch(() => {})
+    }
+
+    return result
+  }
+}
+
+export function shouldIncludeChatDetails(opts = {}) {
+  return cds.env.profiles?.includes("test") || opts._details === true
+}

package/srv/handlers/graph-executor.js

@@ -2,11 +2,13 @@ import cds from "@sap/cds"
 import { short, audit, ms4 } from "../../lib/utils/utils.js"
 import { partsToText, buildChatMessages, firstDataPart } from "../../lib/utils/message-handling.js"
 import * as metrics from "../../lib/telemetry/metrics.js"
-import { mlflowAttrs, mlflowTraceAttrs, setSpanAttrs } from "../../lib/telemetry/mlflow.js"
+import { mlflowAttrs, mlflowTraceAttrs, setSpanAttrs } from "../../lib/telemetry/mlflow/index.js"
 import { CdsFileStore } from "../../lib/protocol/persistence/file-store.js"
 import { formatFileSize, sanitizeFilename } from "./tools.js"
 import { convertUsageData } from "../../lib/telemetry/chat-tracing.js"
 import { triggerCleanup } from "../../lib/protocol/persistence/cleanup.js"
+import { COLLECT_RESULT } from "./chat.js"
+import { linkTraceToPrompt } from "../../lib/telemetry/mlflow/tracing.js"
 
 const LOG = cds.log("agents")
 
@@ -334,16 +336,14 @@ class GraphExecutor {
 
     let tokenCount = 0
     let finalState = null
-    // Track the current turn (langchain message id) and whether it has emitted a
-    // tool call. Anthropic-style turns can stream a text preamble BEFORE their
-    // tool_use block ("Let me first look up …"); we can't tell in advance that
-    // such a turn is planning rather than the final answer, so we stream those
-    // tokens optimistically. Once we see tool_call_chunks for the same turn, we
-    // know retrospectively that the preamble was planning — emit an authoritative
-    // event-level replace with empty text to wipe the leaked preamble, then skip
-    // all further text from this turn.
+    // Track the current turn (langchain message id). Each new turn opens a fresh
+    // bubble on the client via `append:false`; subsequent tokens of the same turn
+    // are `append:true` (accumulate). Anthropic-style turns can stream a text
+    // preamble BEFORE their tool_use block ("Let me first look up …") — we let
+    // that reasoning text stream normally; the client is responsible for the
+    // final visual (collapse to the last turn's bubble at task completion).
     let currentMsgId = null
-    let turnHasToolCall = false
+    let thinkingCount = 0
 
     try {
       if (typeof graph.stream !== "function" || cds.env.agents?.streaming === false) {
@@ -379,30 +379,11 @@ class GraphExecutor {
 
           if (msgChunk.id && msgChunk.id !== currentMsgId) {
             currentMsgId = msgChunk.id
-            turnHasToolCall = false
             tokenCount = 0
           }
 
-          // Retroactively invalidate a leaked planning preamble. In a ReAct loop
-          // the model can emit "Let me look this up …" before its tool_use block
-          if (msgChunk.tool_call_chunks?.length && !turnHasToolCall) {
-            turnHasToolCall = true
-            if (tokenCount > 0) {
-              eventBus.publish({
-                kind: "artifact-update",
-                taskId,
-                contextId,
-                append: false,
-                lastChunk: false,
-                artifact: {
-                  artifactId: "response",
-                  parts: [{ kind: "text", text: "" }],
-                },
-              })
-              tokenCount = 0
-            }
-          }
-          if (turnHasToolCall) continue
+          const lastChunk =
+            !!msgChunk.additional_kwargs?.intermediate_results?.llm?.choices[0].finish_reason
 
           const text = messageText(msgChunk?.content)
           if (!text) continue
@@ -415,12 +396,13 @@ class GraphExecutor {
             taskId,
             contextId,
             append: tokenCount > 0,
-            lastChunk: false,
+            lastChunk: lastChunk,
             artifact: {
-              artifactId: "response",
+              artifactId: `thinking-${thinkingCount}`,
               parts: [{ kind: "text", text }],
             },
           })
+          if (lastChunk) thinkingCount++
           tokenCount++
         } else if (mode === "updates") {
           // The updates stream yields per-node deltas — { <node>: { messages: [oneNewMessage] } },
@@ -699,6 +681,12 @@ class GraphExecutor {
           }),
         )
         setSpanAttrs(rootSpan, mlflowTraceAttrs())
+        // Required for MLFLow run linking
+        const evalRunId = cds.context?.["_mlflow.evalRunId"]
+        if (evalRunId) {
+          rootSpan.setAttribute("mlflow.sourceRun", evalRunId)
+          wfSpan.setAttribute("mlflow.sourceRun", evalRunId)
+        }
       }
 
       let usageData
@@ -753,7 +741,6 @@ class GraphExecutor {
               contextId,
               service: serviceName,
               decision,
-              userMessage: requestContext.userMessage,
             },
           })
           // On edit, stash a diff note in state; the injector middleware prepends it next turn.
@@ -823,7 +810,7 @@ class GraphExecutor {
               contextId,
               service: serviceName,
               description,
-              userMessage: requestContext.userMessage,
+              interruptData,
             },
           })
 
@@ -878,8 +865,7 @@ class GraphExecutor {
             service: serviceName,
             duration,
             tokenUsage: usageData,
-            toolCalls: totalToolCalls(result.messages),
-            output: output?.slice(0, 2000),
+            toolCalls: toolCallsShortened(result.messages),
             task: requestContext.task,
           },
         })
@@ -1078,6 +1064,12 @@ class GraphExecutor {
           })
         }
 
+        // Programmatic .chat() path: stash graph result on eventBus so chat.js
+        // can read messages without an extra checkpoint roundtrip.
+        if (eventBus[COLLECT_RESULT]) {
+          eventBus._graphResult = { messages: result.messages || [] }
+        }
+
         eventBus.publish({
           kind: "status-update",
           taskId,
@@ -1245,6 +1237,10 @@ class GraphExecutor {
           final: true,
         })
       } finally {
+        // setSpanAttrs must happen at the end for the linking as else prompt might not yet have been created
+        const rootSpan = cds.context["_mlflow.rootSpan"]
+        setSpanAttrs(rootSpan, linkTraceToPrompt())
+
         this._abortControllers.delete(taskId)
         metrics.concurrentExecutions.add(-1, mAttrs)
 
@@ -1372,3 +1368,13 @@ function totalToolCalls(messages) {
     return acc
   }, 0)
 }
+
+/**
+ * @param {[import('@langchain/core/messages').Message]} messages
+ */
+function toolCallsShortened(messages) {
+  return messages.reduce((acc, val) => {
+    if (val.type === "tool") acc.push(val.name)
+    return acc
+  }, [])
+}

package/srv/handlers/index.js

@@ -4,6 +4,7 @@ import { buildSystemPrompt } from "./system-prompt.js"
 import buildMiddleware from "../../lib/agents/middleware/index.js"
 import { partsToText } from "../../lib/utils/message-handling.js"
 import { cleanupExpiredTasks } from "../../lib/protocol/persistence/cleanup.js"
+import { registerChat } from "./chat.js"
 
 const LOG = cds.log("agents")
 
@@ -175,4 +176,6 @@ export default function registerDefaultAgentHandlers(srv) {
   srv.on("cleanupTasks", async () => {
     await cleanupExpiredTasks(srv.name)
   })
+
+  registerChat(srv)
 }

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({
@@ -136,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
             })

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