@cap-js/agents 0.9.2 → 0.9.4

package/srv/handlers/graph-executor.js

@@ -1,12 +1,15 @@
 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 { agentMessage, partsToText, buildChatMessages } 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"
+import { handleHitlInterrupt, requiresHitl, resumeHitl } from "./graph-executor/hitl.js"
 
 const LOG = cds.log("agents")
 
@@ -102,18 +105,6 @@ function defaultOutputMapper(result) {
   return JSON.stringify(result)
 }
 
-// Construct a spec-compliant A2A Message; when `data` is a plain object, append it as a DataPart.
-function agentMessage(text, data) {
-  const parts = [{ kind: "text", text }]
-  if (data && typeof data === "object") parts.push({ kind: "data", data })
-  return {
-    kind: "message",
-    messageId: cds.utils.uuid(),
-    role: "agent",
-    parts,
-  }
-}
-
 /**
  * Extract user text from A2A message parts.
  */
@@ -121,147 +112,6 @@ function extractText(requestContext) {
   return partsToText(requestContext.userMessage?.parts)
 }
 
-// Extract the first inbound DataPart's opaque `data` object, or undefined if none.
-function extractData(requestContext) {
-  return firstDataPart(requestContext.userMessage?.parts)
-}
-
-/**
- * Parse user's resume text into a HITL decision.
- * Maps to the format expected by deepagents' humanInTheLoopMiddleware.
- */
-function parseResumeDecision(userText) {
-  const t = userText.trim()
-  if (/^(approve|yes|confirm|ok)$/i.test(t)) {
-    return { decisions: [{ type: "approve" }] }
-  }
-  if (/^edit$/i.test(t)) {
-    // Bare edit — structured edits (with args) arrive via the DataPart path.
-    return { decisions: [{ type: "edit" }] }
-  }
-  return { decisions: [{ type: "reject", message: userText }] }
-}
-
-// Best-effort decision label for logging/audit; opaque DataPart resumes fall back to "data".
-function decisionTypeOf(resume) {
-  return resume?.decisions?.[0]?.type ?? "data"
-}
-
-/**
- * Extract the human-readable description from an interrupt payload.
- * Accepts either a graph result (with __interrupt__) or a GraphInterrupt error (with .interrupts).
- * Handles both deepagents' humanInTheLoopMiddleware format and raw interrupt() calls.
- */
-function extractInterruptDescription(resultOrErr) {
-  const interrupt = resultOrErr.__interrupt__?.[0] || resultOrErr.interrupts?.[0]
-  const payload = interrupt?.value
-  if (!payload) return "This action requires your approval. Reply 'approve' or 'reject'."
-
-  // deepagents' humanInTheLoopMiddleware: { actionRequests: [{ description }], reviewConfigs }
-  if (payload.actionRequests?.length > 0) {
-    return (
-      payload.actionRequests[0].description || `Approve action: ${payload.actionRequests[0].name}?`
-    )
-  }
-
-  // Raw interrupt(value) - value is a string or object
-  if (typeof payload === "string") return payload
-  return JSON.stringify(payload)
-}
-
-/**
- * Extract the raw structured interrupt payload for opaque carry on a DataPart.
- * Returns the payload ONLY when it is a plain object; arrays and strings are
- * carried by the TextPart alone. Payload is app-defined; the plugin never
- * interprets it.
- */
-function extractInterruptData(resultOrErr) {
-  const interrupt = resultOrErr.__interrupt__?.[0] || resultOrErr.interrupts?.[0]
-  const payload = interrupt?.value
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined
-  return payload
-}
-
-// Order-invariant JSON serializer for structural arg comparison.
-function canonicalJSON(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value)
-  if (Array.isArray(value)) return "[" + value.map(canonicalJSON).join(",") + "]"
-  const keys = Object.keys(value).sort()
-  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJSON(value[k])).join(",") + "}"
-}
-
-// Firm note describing HITL edits so the model doesn't apologize on the next turn.
-function composeEditNote(originals, resume) {
-  const decisions = resume?.decisions
-  if (!Array.isArray(decisions) || decisions.length === 0) return undefined
-
-  const consumed = new Set()
-  const takeByName = (name) => {
-    for (let j = 0; j < originals.length; j++) {
-      if (!consumed.has(j) && originals[j]?.name === name) {
-        consumed.add(j)
-        return originals[j]
-      }
-    }
-    return undefined
-  }
-  const takeNextUnconsumed = () => {
-    for (let j = 0; j < originals.length; j++) {
-      if (!consumed.has(j)) {
-        consumed.add(j)
-        return originals[j]
-      }
-    }
-    return undefined
-  }
-
-  const changes = []
-  for (const d of decisions) {
-    if (d?.type !== "edit" || !d.editedAction) continue
-    const editedName = d.editedAction.name
-    const editedArgs = d.editedAction.args
-    const orig = takeByName(editedName) ?? takeNextUnconsumed()
-    if (!orig) continue
-    if (orig.name === editedName && canonicalJSON(orig.args) === canonicalJSON(editedArgs)) continue
-    changes.push({
-      from: { name: orig.name, args: orig.args },
-      to: { name: editedName, args: editedArgs },
-    })
-  }
-  if (changes.length === 0) return undefined
-
-  const lines = changes.map(
-    (c) =>
-      `- \`${c.from.name}(${JSON.stringify(c.from.args)})\` → \`${c.to.name}(${JSON.stringify(c.to.args)})\``,
-  )
-  return [
-    "The user reviewed your proposed tool call(s) in the human-in-the-loop approval flow and edited them before execution. This is intentional user action, NOT a mistake on your part. Do NOT apologize or say you made an error.",
-    "",
-    "Edits applied:",
-    ...lines,
-    "",
-    "Proceed as if the edited values are what the user actually wants. Describe the outcome of the executed call accurately.",
-  ].join("\n")
-}
-
-// Reads the pre-interrupt AI's tool_calls from the checkpointer (still un-mutated at resume time).
-async function getPreInterruptToolCalls(graph, config) {
-  try {
-    if (typeof graph.getState !== "function") return []
-    const state = await graph.getState(config)
-    const messages = state?.values?.messages ?? []
-    for (let i = messages.length - 1; i >= 0; i--) {
-      const m = messages[i]
-      if (m?.tool_calls?.length) {
-        return m.tool_calls.map((tc) => ({ id: tc.id, name: tc.name, args: tc.args }))
-      }
-    }
-    return []
-  } catch {
-    return []
-  }
-}
-
 /**
  * GraphExecutor wraps a compiled LangGraph graph as an A2A AgentExecutor.
  *
@@ -334,16 +184,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 +227,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 +244,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 +529,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
@@ -728,51 +564,16 @@ class GraphExecutor {
         const t0 = Date.now()
 
         if (isResume) {
-          const dataPart = extractData(requestContext)
-          const userText = extractText(requestContext)
-          // Relaxed guard: accept a DataPart-only resume OR non-empty text.
-          if (dataPart === undefined && !userText.trim()) {
-            throw new Error(cds.i18n.messages.at("RESUME_REQUIRES_TEXT"))
-          }
-          const { Command } = await import("@langchain/langgraph")
-          // DataPart wins over text — a structured resume is self-describing and any
-          // accompanying text is treated as incidental (e.g. a human-readable echo).
-          const resume = dataPart !== undefined ? dataPart : parseResumeDecision(userText)
-          const decision = decisionTypeOf(resume)
-
-          LOG.debug("resuming", {
-            conversation: short(contextId),
-            service: serviceName,
-            decision,
-          })
-
-          // Audit: task resumed with HITL decision
-          audit("AgentTaskResumed", {
-            data: {
-              taskId,
-              contextId,
-              service: serviceName,
-              decision,
-              userMessage: requestContext.userMessage,
-            },
-          })
-          // On edit, stash a diff note in state; the injector middleware prepends it next turn.
-          const commandArgs = { resume }
-          if (decision === "edit") {
-            const originals = await getPreInterruptToolCalls(graph, config)
-            const editNote = composeEditNote(originals, resume)
-            if (editNote) commandArgs.update = { _hitlEditNote: editNote }
-          }
-          const resumed = await this._streamWithPublish(
+          result = await resumeHitl({
+            requestContext,
             graph,
-            new Command(commandArgs),
             config,
             eventBus,
-            taskId,
-            contextId,
-            controller.signal,
-          )
-          result = resumed.state
+            signal: controller.signal,
+            stream: (input, signal) =>
+              this._streamWithPublish(graph, input, config, eventBus, taskId, contextId, signal),
+          })
+          if (!result) return
         } else {
           const inputMapper = this._inputMapper || defaultInputMapper
           const rawInput = await inputMapper(requestContext)
@@ -793,56 +594,28 @@ class GraphExecutor {
         // (interrupt-only results may have no `messages` — treat as empty)
         usageData = aggregateUsageData(result.messages || [])
 
-        if (result?.__interrupt__?.length > 0) {
-          const description = extractInterruptDescription(result)
-          const interruptData = extractInterruptData(result)
-
-          const duration = ((Date.now() - t0) / 1000).toFixed(1) + "s"
-          LOG.info("input-required", {
-            conversation: short(contextId),
-            service: serviceName,
+        const duration = ((Date.now() - t0) / 1000).toFixed(1) + "s"
+        if (requiresHitl(result)) {
+          handleHitlInterrupt({
+            result,
+            requestContext,
+            eventBus,
+            serviceName,
             duration,
-          })
-
-          if (wfSpan) {
-            wfSpan.setAttribute("agent.outcome", "input-required")
-            const outputs = {
-              choices: [{ message: { role: "assistant", content: description } }],
-            }
-            setSpanAttrs(wfSpan, mlflowAttrs("AGENT", { outputs }))
-            const rootSpan = cds.context?.["_mlflow.rootSpan"]
-            if (rootSpan) {
-              setSpanAttrs(rootSpan, mlflowAttrs("CHAIN", { outputs }))
-            }
-          }
-
-          // Audit: agent requires human input
-          audit("AgentInputRequired", {
-            data: {
-              taskId,
-              contextId,
-              service: serviceName,
-              description,
-              userMessage: requestContext.userMessage,
-            },
-          })
-
-          eventBus.publish({
-            kind: "status-update",
-            taskId,
-            contextId,
-            status: {
-              state: "input-required",
-              message: agentMessage(description, interruptData),
-              timestamp: new Date().toISOString(),
+            onInputRequired: (description) => {
+              if (!wfSpan) return
+              wfSpan.setAttribute("agent.outcome", "input-required")
+              const outputs = {
+                choices: [{ message: { role: "assistant", content: description } }],
+              }
+              setSpanAttrs(wfSpan, mlflowAttrs("AGENT", { outputs }))
+              const rootSpan = cds.context?.["_mlflow.rootSpan"]
+              if (rootSpan) setSpanAttrs(rootSpan, mlflowAttrs("CHAIN", { outputs }))
             },
-            final: true,
           })
-          eventBus.finished()
           return
         }
 
-        const duration = ((Date.now() - t0) / 1000).toFixed(1) + "s"
         const outputMapper = this._outputMapper || defaultOutputMapper
         const output = outputMapper(result) || "I could not generate a response."
 
@@ -878,8 +651,7 @@ class GraphExecutor {
             service: serviceName,
             duration,
             tokenUsage: usageData,
-            toolCalls: totalToolCalls(result.messages),
-            output: output?.slice(0, 2000),
+            toolCalls: toolCallsShortened(result.messages),
             task: requestContext.task,
           },
         })
@@ -906,6 +678,9 @@ class GraphExecutor {
         //   1. emit_file_part tool calls (default graph) — JSON in toolResults/messages
         //   2. write_file '/outputs/*' via OutputsBackend (deep agent) — CDS rows
         const fileArtifacts = []
+        // DataParts embedded in tool-result content.
+        // Published as their own `data-*` artifact-update events below.
+        const dataArtifacts = []
         const maxFileBytes = cds.env.agents.fileIO.maxOutputFileSizeBytes
 
         // Artifacts from emit_file_part are this agent's own outputs — they must be
@@ -929,7 +704,10 @@ class GraphExecutor {
           const content = typeof msg.content === "string" ? msg.content : ""
           let pos = 0
           while (pos < content.length) {
-            const start = content.indexOf('{"kind":"file"', pos)
+            // Find the earliest next FilePart or DataPart marker.
+            const fileAt = content.indexOf('{"kind":"file"', pos)
+            const dataAt = content.indexOf('{"kind":"data"', pos)
+            const start = fileAt === -1 ? dataAt : dataAt === -1 ? fileAt : Math.min(fileAt, dataAt)
             if (start === -1) break
             // Walk forward tracking depth and quoted strings so that '}' inside
             // a string value (e.g. a filename like "result_{final}.csv") does not
@@ -958,6 +736,11 @@ class GraphExecutor {
             const raw = content.slice(start, i + 1)
             try {
               const artifact = JSON.parse(raw)
+              if (artifact.kind === "data") {
+                dataArtifacts.push(artifact)
+                pos = i + 1
+                continue
+              }
               // Apply the same per-file size cap as Source 2. Decode-length is
               // computed by Buffer.byteLength (zero allocation — pure formula
               // over string length + padding) so an oversized blob never pins
@@ -1078,6 +861,32 @@ class GraphExecutor {
           })
         }
 
+        dataArtifacts.forEach((artifact, i) => {
+          if (artifact.data == null || typeof artifact.data !== "object") {
+            LOG.warn("skipping malformed data artifact", {
+              conversation: short(contextId),
+              service: serviceName,
+            })
+            return
+          }
+          LOG.info("data emitted", { conversation: short(contextId), service: serviceName })
+          eventBus.publish({
+            kind: "artifact-update",
+            taskId,
+            contextId,
+            artifact: {
+              artifactId: `data-${i}`,
+              parts: [{ kind: "data", data: artifact.data }],
+            },
+          })
+        })
+
+        // 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 +1054,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)
 
@@ -1330,16 +1143,7 @@ class GraphExecutor {
   }
 }
 
-export {
-  GraphExecutor,
-  messageText,
-  defaultOutputMapper,
-  agentMessage,
-  parseResumeDecision,
-  decisionTypeOf,
-  extractInterruptData,
-  composeEditNote,
-}
+export { GraphExecutor, messageText, defaultOutputMapper, agentMessage }
 
 /**
  * @param {[import('@langchain/core/messages').Message]} messages
@@ -1372,3 +1176,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")
 
@@ -91,7 +92,8 @@ export default function registerDefaultAgentHandlers(srv) {
   // Default buildModel: cds.connect.to('llm'), configurable via @agent.llm
   srv.on("buildModel", async (req) => {
     const name = srv?.options?.agent?.llm || srv?.definition?.["@agent.llm"] || "llm"
-    let { kind, impl, ...options } = cds.requires[name] ?? {}
+    const options = cds.requires[name] ?? {}
+    let { kind, impl } = options
     if (!impl) impl = cds.requires.kinds[kind]?.impl
     if (!impl) throw new Error("No service implementation found for " + name)
     const { default: LLMProvider } = await import(impl)
@@ -175,4 +177,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) {