@cap-js/agents 0.9.7 → 0.9.8

package/_i18n/messages.properties

@@ -3,6 +3,8 @@
 agent_status_calling_tools = Calling {0}
 #XMSG Status info message send to the user client when an entity is being queried. {0} = entity name
 agent_status_querying = Querying {0}
+#XMSG Status info message send to the user client when a service model is being inspected. {0} = service/entity name
+agent_status_describing = Inspecting {0}
 #XMSG Status info message send to the user client after a tool result returned and the agent is processing it
 agent_status_processing_response = Processing tool response
 #XMSG Status info message send to the user client after multiple tool results returned and the agent is processing it

package/cds-plugin.js

@@ -69,24 +69,27 @@ cds.on("bootstrap", (app) => {
 
 !(function cds_requires_llm() {
   cds.on("served", async () => {
-    if (
-      cds.requires.llm === "anthropic" ||
-      cds.requires.llm?.kind === "anthropic" ||
-      cds.requires.llm === "auto" ||
-      cds.requires.llm?.kind === "auto"
-    ) {
+    const kind = cds.requires.llm?.kind ?? cds.requires.llm
+    if (kind === "auto") {
       const { resolve_config } = await import("./lib/config/local.js")
-      let options = cds.requires.llm
-      if (options === "auto") options = { kind: "auto" }
-      cds.env.requires.llm = resolve_config(options)
+      cds.env.requires.llm = resolve_config({ kind: "auto" })
+    }
+    if (kind === "anthropic") {
+      const { resolve_anthropic_config } = await import("./lib/config/local.js")
+      cds.env.requires.llm = resolve_anthropic_config(cds.requires.llm)
+    }
+    if (kind === "openai") {
+      const { resolve_openai_config } = await import("./lib/config/local.js")
+      cds.env.requires.llm = resolve_openai_config(cds.requires.llm)
     }
 
     const config = cds.requires.llm,
       credentials = {}
-    const { url, destination, anthropicApiUrl, apiKey } = config?.credentials || {}
+    const { url, destination, anthropicApiUrl, baseURL, apiKey } = config?.credentials || {}
     if (url) credentials.url = url
     if (destination) credentials.destination = destination
     if (anthropicApiUrl) credentials.anthropicApiUrl = anthropicApiUrl
+    if (baseURL) credentials.baseURL = baseURL
     if (apiKey) credentials.apiKey = "***"
     LOG.info(`cds.connect.to 'llm' with:`, { ...config, credentials })
   })

package/lib/agents/middleware/content-filter.js

@@ -47,6 +47,7 @@ export async function contentFilterMiddleware(model) {
     },
     {
       disableStreaming: true,
+      maxRetries: 0,
       customRequestConfig: {
         middleware: [timeout(10_000), retry(2)],
       },
@@ -112,6 +113,9 @@ export async function contentFilterMiddleware(model) {
         try {
           await inputFilterModel.invoke(filterMessages)
         } catch (err) {
+          if (err.rootCause?.message.match(/Could not find service credentials for AI Core/)) {
+            throw err.rootCause
+          }
           const { status, data } = extractErrorDetails(err)
           const isFilterBlock =
             /Filtering Module/i.test(data?.error?.location || "") && status === 400

package/lib/agents/middleware/hitl-decision-note-injector.js

@@ -2,17 +2,29 @@ import { createMiddleware } from "langchain"
 import { HumanMessage } from "@langchain/core/messages"
 import { z } from "zod"
 
-// Injects user HITL decisions before the model continues after a rejection or edit.
+// Injects user HITL decisions (edit/reject) as a HumanMessage before the model
+// continues, so the model treats them as deliberate user decisions rather than
+// tool failures.
+//
+// LangChain's humanInTheLoop middleware routes these decisions differently:
+//   - edit   → jumpTo undefined → normal flow → `beforeModel` runs. Inject + clear here.
+//   - reject → jumpTo "model"  → re-enters the model node directly, SKIPPING all
+//              `beforeModel` hooks. `wrapModelCall` still runs, so it injects as a
+//              fallback when `beforeModel` did not consume the note.
+//
+// So we use `wrapModel` to inject the message and clear the note after the model call.
 export function hitlDecisionNoteInjectorMiddleware() {
   return createMiddleware({
     name: "hitlDecisionNoteInjectorMiddleware",
     stateSchema: z.object({ _hitlDecisionNote: z.string().optional() }),
-    beforeModel: async (state) => {
+    wrapModelCall: async (request, handler) => {
+      const note = request.state?._hitlDecisionNote
+      if (!note) return handler(request)
+      return handler({ ...request, messages: [...(request.messages || []), new HumanMessage(note)] })
+    },
+    afterModel: async (state) => {
       if (!state._hitlDecisionNote) return
-      return {
-        messages: [new HumanMessage(state._hitlDecisionNote)],
-        _hitlDecisionNote: undefined,
-      }
+      return { _hitlDecisionNote: undefined }
     },
   })
 }

package/lib/agents/middleware/hitl.js

@@ -1,13 +1,24 @@
 import { humanInTheLoopMiddleware as hitl } from "langchain"
 import { hitlDecisionNoteInjectorMiddleware } from "./hitl-decision-note-injector.js"
 
-function buildHitlInterruptMap(srv, tools = []) {
+const ALLOWED_DECISIONS = ["approve", "reject", "edit"]
+
+const isHitlAction = (action) => action?.["@agent.hitl"] ?? action?.["@Common.IsActionCritical"]
+
+export function buildHitlInterruptMap(srv, tools = []) {
   return tools.reduce((interruptOn, tool) => {
-    if (
-      srv.actions[tool.name]?.["@agent.hitl"] ??
-      srv.actions[tool.name]?.["@Common.IsActionCritical"]
-    ) {
-      interruptOn[tool.name] = { allowedDecisions: ["approve", "reject", "edit"] }
+    // Per-action tool: its name IS the action name, so a static entry gates it.
+    if (isHitlAction(srv.actions[tool.name])) {
+      interruptOn[tool.name] = { allowedDecisions: ALLOWED_DECISIONS }
+    }
+    // Generic @cap-js/mcp "call" tool: one tool fronts every action, with the
+    // target action in args.action. The tool name matches no action, so gate
+    // per-call via `when`, which inspects the requested action at invoke time.
+    else if (tool.name === "call" && Object.values(srv.actions).some(isHitlAction)) {
+      interruptOn[tool.name] = {
+        allowedDecisions: ALLOWED_DECISIONS,
+        when: (request) => Boolean(isHitlAction(srv.actions[request.toolCall?.args?.action])),
+      }
     }
     return interruptOn
   }, {})

package/lib/agents/middleware/index.js

@@ -24,7 +24,7 @@ export default async function buildMiddleware(srv, options = {}) {
     await contentFilterMiddleware(model),
     await agentActionsMiddleware(),
     patchToolCallsMiddleware(),
-    await statusUpdateMiddleware(),
+    await statusUpdateMiddleware(tools),
     ...(await humanInTheLoopMiddleware(srv, tools)),
     toolSelectionMiddleware(),
     toolWrapMiddleware(srv),

package/lib/agents/middleware/masking.js

@@ -54,7 +54,7 @@ export function masking(srv) {
 
         // Decode TOON or JSON — pseudonymize operates on decoded objects
         const { decoded, format } = decodeContent(toolMessage.content)
-        if (decoded) {
+        if (decoded && typeof decoded !== "string") {
           const result = await pseudonymize(
             {
               data: decoded,
@@ -81,8 +81,11 @@ export function masking(srv) {
             outMessage = new ToolMessage({ ...toolMessage, content: encoded })
           }
         } else {
-          const session = cds.context["agent.pseudonyms"]
-          outMessage = session.scrubText(toolMessage.content)
+          // Plain string (e.g. read_file output) or unparseable — scrub using session mappings.
+          const scrubbed = session.scrubText(toolMessage.content)
+          if (scrubbed !== toolMessage.content) {
+            outMessage = new ToolMessage({ ...toolMessage, content: scrubbed })
+          }
         }
       }
 

package/lib/agents/middleware/remote-mcp.js

@@ -2,7 +2,7 @@ import cds from "@sap/cds"
 import { createMiddleware } from "langchain"
 import { ToolMessage } from "@langchain/core/messages"
 import { MultiServerMCPClient } from "@langchain/mcp-adapters"
-import { toolName } from "../../utils/utils.js"
+import { toolName, mcpToolKind } from "../../utils/utils.js"
 
 const LOG = cds.log("agents:mcp")
 
@@ -27,7 +27,10 @@ export function remoteMcpMiddleware() {
           })
           let raw = await client.getTools()
           if (toolFilter?.length) raw = raw.filter((t) => toolFilter.includes(t.name))
-          for (const t of raw) t.name = toolName(`${serviceName}_${t.name}`)
+          for (const t of raw) {
+            t.metadata = { ...t.metadata, serviceName, kind: mcpToolKind(t.name) }
+            t.name = toolName(`${serviceName}_${t.name}`)
+          }
           cache[mcpUrl] = { serviceName, tools: raw }
           LOG.debug(
             `Got ${raw.length} MCP tools from ${mcpUrl}: ${raw.map((t) => t.name).join(", ")}`,

package/lib/agents/middleware/status-update.js

@@ -1,63 +1,103 @@
 import cds from "@sap/cds"
 import { createMiddleware } from "langchain"
-import { ToolMessage } from "@langchain/core/messages"
+import { AIMessage, ToolMessage } from "@langchain/core/messages"
+import { resolvePseudonyms } from "../../masking/index.js"
+import { serviceLabel, declaredServiceLabel, mcpToolKind } from "../../utils/utils.js"
 
 /**
- * Resolves a human-readable label for a tool call.
- *
- * - query tool → resolves entity label from CDS model: @Common.Label, @title, or i18n
- * - actions → resolves label from action definition
- * - fallback → tool name as-is
+ * Resolve the metadata for a tool call, or undefined when the tool is unknown.
+ * Static tools come from the precomputed `toolMeta` map; remote MCP tools are
+ * resolved per-request from cds.context.__mcpDynamicTools.
  */
-function resolveToolLabel(tc) {
-  const serviceName = cds.context?.["agent.service"]
-  const srv = serviceName && cds.services?.[serviceName]
-  const model = cds.context?.model ?? cds.model
+function resolveMeta(tc, toolMeta) {
+  const meta = toolMeta.get(tc.name)
+  if (meta) return meta
 
-  // Query tool: extract entity target and resolve its label
-  if (tc.name === "query" || tc.name?.endsWith("_query")) {
-    let entityName = tc.args?.entity ? `${serviceName}.${tc.args.entity}` : undefined
-
-    // SQL format: no entity arg — parse SQL to extract FROM target
-    if (!entityName && tc.args?.cql) {
-      try {
-        const cqn = cds.parse.cql(tc.args.cql)
-        const ref0 = cqn.SELECT?.from?.ref?.[0]
-        const targetName = ref0?.id ?? ref0
-        if (targetName && serviceName && !targetName.startsWith(serviceName + ".")) {
-          entityName = `${serviceName}.${targetName}`
-        } else {
-          entityName = targetName
-        }
-      } catch {
-        /* fallback to tc.name below */
-      }
-    }
-    if (entityName) {
-      const entityDef = model.definitions?.[entityName]
-      if (entityDef) {
-        const label = cds.i18n?.labels?.at(entityDef)
-        if (label) return label
-      }
-    }
-    // Fallback: strip service prefix if present
-    if (entityName && srv?.name && entityName.startsWith(srv.name + ".")) {
-      return entityName.slice(srv.name.length + 1)
+  const cache = cds.context?.__mcpDynamicTools
+  if (cache) {
+    for (const entry of Object.values(cache)) {
+      const t = entry.tools?.find((t) => t.name === tc.name)
+      if (t) return t.metadata
     }
-    return entityName || tc.name
   }
+  return undefined
+}
+
+/**
+ * Resolve the kind ("query" | "describe" | "action" | "agent") for a tool call.
+ * Prefer the build-time `meta.kind` (classified from the unprefixed name, so it
+ * survives prefixing/truncation); else sniff `tc.name` for own-service tools.
+ */
+function resolveToolKind(tc, meta) {
+  if (meta?.kind) return meta.kind
+  return mcpToolKind(tc.name)
+}
+
+/** Resolve an entity's display label (declared i18n label, else its simple name). */
+function entityLabel(name, serviceName, model) {
+  const fq = serviceName && !name.startsWith(serviceName + ".") ? `${serviceName}.${name}` : name
+  const def = model?.definitions?.[fq]
+  return (
+    (def && cds.i18n?.labels?.at(def)) ||
+    (fq.includes(".") ? fq.slice(fq.lastIndexOf(".") + 1) : fq)
+  )
+}
 
-  // Action/function tools: resolve from service definition
-  if (srv) {
-    // Try as action on service
-    const actionDef = model.definitions[`${srv.name}.${tc.name}`]
-    if (actionDef) {
-      const label = cds.i18n?.labels?.at(actionDef)
-      if (label) return label
+/** Resolve the query target: the `entity` arg, or the FROM target parsed from `cql`. */
+function queryTarget(tc) {
+  if (tc.args?.entity) return tc.args.entity
+  if (tc.args?.cql) {
+    try {
+      const ref0 = cds.parse.cql(tc.args.cql).SELECT?.from?.ref?.[0]
+      return ref0?.id ?? ref0 ?? undefined
+    } catch {
+      /* no target derivable */
     }
   }
+  return undefined
+}
+
+/**
+ * Resolve a human-readable label for a tool call:
+ * - agent    → declared service label, else the subagent's agent-card name
+ * - describe → service label (declared, else the FQ service name)
+ * - query    → entity label, prefixed with the service only when it has a declared label
+ * - action   → action label, prefixed with the service only when it has a declared label
+ */
+function resolveToolLabel(tc, meta, kind = resolveToolKind(tc, meta)) {
+  const model = cds.context?.model ?? cds.model
+  const serviceName = meta?.serviceName ?? cds.context?.["agent.service"] // REVISIT: why are we using cds.context here?
+
+  if (kind === "agent") {
+    return declaredServiceLabel(meta?.serviceName) || meta?.agentName || tc.name
+  }
+
+  if (kind === "describe") {
+    let parts = []
+    if (tc.args?.entities) parts.push(...tc.args.entities.map(e => entityLabel(e, serviceName, model)))
+    if (tc.args?.actions) parts.push(...tc.args.actions.map(a => entityLabel(a, serviceName, model)))
+    if (!parts.length) parts.push(serviceLabel(serviceName) || tc.name)
+    return parts.join(", ")
+  }
+
+  const svcLabel = declaredServiceLabel(serviceName)
+  const withService = (detail) => (svcLabel ? `${svcLabel} · ${detail}` : detail)
+
+  if (kind === "query") {
+    const target = queryTarget(tc)
+    if (target) return withService(entityLabel(target, serviceName, model))
+    return svcLabel || tc.name
+  }
 
-  return tc.name
+  // meta.actionName is the un-prefixed name for MCP action tools (tc.name is
+  // "{service}_{action}"); own-service tools already carry the bare name.
+  const actionName = meta?.actionName ?? tc.args?.action ?? tc.name
+  if (serviceName) {
+    const actionDef = model?.definitions?.[`${serviceName}.${actionName}`]
+    const declared = actionDef && cds.i18n?.labels?.at(actionDef) || actionName
+    if (declared) return withService(declared)
+  }
+  return withService(actionName)
 }
 
 /**
@@ -86,29 +126,106 @@ export function publishStatus(text) {
 }
 
 /**
- * beforeModel hook: emit "Processing tool response" when tools just finished.
+ * Reads tool-call visibility config from the current request's metadata.
+ * Controlled entirely by the client: presence of userMessage.metadata["tool-status-update"] enables it.
+ */
+function toolCallConfig() {
+  const requestMeta = cds.context?.["agent.request.metadata"]?.["tool-status-update"]
+  return {
+    enabled: requestMeta !== undefined,
+    args: requestMeta?.args ?? true,
+    result: requestMeta?.result ?? true,
+  }
+}
+
+function serialize(v) {
+  return resolvePseudonyms(typeof v === "string" ? v : JSON.stringify(v))
+}
+
+/**
+ * Publishes an artifact-update for a tool call (start or end).
+ */
+function publishToolCallArtifact(tc, { meta, status, lastChunk, result }) {
+  const eventBus = cds.context?.["agent.eventBus"]
+  const config = toolCallConfig()
+  if (!eventBus || !config.enabled) return
+
+  let kind = resolveToolKind(tc, meta)
+  let label = resolveToolLabel(tc, meta)
+  eventBus.publish({
+    kind: "artifact-update",
+    taskId: cds.context["agent.task.id"],
+    contextId: cds.context["agent.context.id"],
+    append: false,
+    lastChunk,
+    artifact: {
+      artifactId: `tool-call-${tc.id}`,
+      parts: [
+        {
+          kind: "data",
+          data: {
+            type: "tool-call",
+            name: tc.name,
+            kind,
+            label,
+            status,
+            ...(config.args && { args: serialize(tc.args) }),
+            ...(result !== undefined && config.result && { result: serialize(result) }),
+          },
+        },
+      ],
+    },
+  })
+}
+
+/**
+ * beforeModel hook: emit "Processing tool response" + tool-call completion events.
  */
-export function beforeModelHook(state) {
+export function beforeModelHook(state, toolMeta) {
   if (!cds.context?.["agent.eventBus"]) return {}
 
   const msgs = state.messages
   if (!msgs?.length) return {}
-  const lastMsg = msgs[msgs.length - 1]
-  if (!ToolMessage.isInstance(lastMsg)) return {}
+  if (!ToolMessage.isInstance(msgs[msgs.length - 1])) return {}
 
-  // Plural if second-to-last is also a ToolMessage
-  const plural = msgs.length >= 2 && ToolMessage.isInstance(msgs[msgs.length - 2])
+  const firstToolIdx = msgs.findLastIndex((m) => !ToolMessage.isInstance(m)) + 1
+  const toolMsgs = msgs.slice(firstToolIdx)
+
+  const tcMap = {}
+  const msg = msgs.findLast((m) => AIMessage.isInstance(m) && m.tool_calls?.length)
+  if (msg) for (const tc of msg.tool_calls) tcMap[tc.id] = tc
+
+  for (const tm of toolMsgs) {
+    const tc = tcMap[tm.tool_call_id]
+    if (!tc) continue
+    const meta = resolveMeta(tc, toolMeta)
+    if (meta) {
+      publishToolCallArtifact(tc, {
+        meta,
+        status: tm.status === "error" ? "error" : "done",
+        lastChunk: true,
+        result: tm.content,
+      })
+    }
+  }
+
+  const plural = toolMsgs.length >= 2
   const key = plural ? "agent_status_processing_responses" : "agent_status_processing_response"
-  const text = cds.i18n.messages.at(key)
-  publishStatus(text)
+  publishStatus(cds.i18n.messages.at(key))
 
   return {}
 }
 
+/** De-duplicate labels while preserving order. */
+function uniqueLabels(calls) {
+  return [...new Set(calls.map(({ label }) => label))].join(", ")
+}
+
 /**
- * afterModel hook: emit tool-call status updates (querying/calling).
+ * afterModel hook: emit tool-call status updates (querying/inspecting/calling)
+ * + tool-call start events.
  */
-export function afterModelHook(state) {
+export function afterModelHook(state, toolMeta) {
   if (!cds.context?.["agent.eventBus"]) return {}
 
   const msgs = state.messages
@@ -118,36 +235,52 @@ export function afterModelHook(state) {
   const toolCalls = lastAI?.tool_calls
   if (!toolCalls?.length) return {}
 
-  // Separate query calls from action calls
-  const queryCalls = toolCalls.filter((tc) => tc.name === "query" || tc.name?.endsWith("_query"))
-  const otherCalls = toolCalls.filter((tc) => tc.name !== "query" && !tc.name?.endsWith("_query"))
+  const resolved = toolCalls
+    .map((tc) => ({ tc, meta: resolveMeta(tc, toolMeta) }))
+    .filter(({ meta }) => meta)
+    .map(({ tc, meta }) => {
+      let kind = resolveToolKind(tc, meta)
+      let label = resolveToolLabel(tc, meta, kind)
+      return { tc, meta, kind, label }
+    })
+
+  const queryCalls = resolved.filter(({ kind }) => kind === "query")
+  const describeCalls = resolved.filter(({ kind }) => kind === "describe")
+  const otherCalls = resolved.filter(({ kind }) => kind !== "query" && kind !== "describe")
 
-  // Emit "Querying {entities}" for query tools
   if (queryCalls.length) {
-    const labels = queryCalls.map((tc) => resolveToolLabel(tc))
-    const text = cds.i18n.messages.at("agent_status_querying", [labels.join(", ")])
-    publishStatus(text)
+    publishStatus(cds.i18n.messages.at("agent_status_querying", [uniqueLabels(queryCalls)]))
+  }
+  if (describeCalls.length) {
+    publishStatus(cds.i18n.messages.at("agent_status_describing", [uniqueLabels(describeCalls)]))
   }
-
-  // Emit "Calling {action labels}" for other tools
   if (otherCalls.length) {
-    const labels = otherCalls.map((tc) => resolveToolLabel(tc))
-    const text = cds.i18n.messages.at("agent_status_calling_tools", [labels.join(", ")])
-    publishStatus(text)
+    publishStatus(cds.i18n.messages.at("agent_status_calling_tools", [uniqueLabels(otherCalls)]))
+  }
+
+  for (const { tc, meta } of resolved) {
+    publishToolCallArtifact(tc, { meta, status: "running", lastChunk: false })
   }
 
   return {}
 }
 
 /**
- * Middleware factory that emits non-final status-update events during agent execution:
- * - beforeModel: "Processing tool response" after tools finish
- * - afterModel:  "Querying <entity>" / "Calling <action>" before tools are invoked
+ * Middleware emitting non-final status-update events during agent execution:
+ * - beforeModel: "Processing tool response" + tool-call completion events
+ * - afterModel:  "Querying"/"Inspecting"/"Calling" + tool-call start events
+ *
+ * Static tools are captured here; remote MCP tools are resolved per-request from
+ * cds.context.__mcpDynamicTools by resolveMeta().
  */
-export async function statusUpdateMiddleware() {
+export async function statusUpdateMiddleware(tools = []) {
+  // Presence in the map marks a tool as "known"; own-service tools carry no
+  // metadata (→ {}), so resolveToolKind sniffs their kind from the name.
+  const toolMeta = new Map(tools.map((t) => [t.name, t.metadata ?? {}]))
+
   return createMiddleware({
     name: "statusUpdateMiddleware",
-    beforeModel: { hook: beforeModelHook },
-    afterModel: { hook: afterModelHook },
+    beforeModel: { hook: (state) => beforeModelHook(state, toolMeta) },
+    afterModel: { hook: (state) => afterModelHook(state, toolMeta) },
   })
 }

package/lib/agents/middleware/tool-wrap.js

@@ -14,9 +14,8 @@ export function toolWrapMiddleware(srv) {
   return createMiddleware({
     name: "ToolWrapMiddleware",
     wrapToolCall: async function (request, handler) {
-      const { name, id, args } = request.toolCall
+      const { name, id } = request.toolCall
       try {
-        LOG.debug(srv.name, "calling tool", name, args)
         const result = await handler(request)
         if (ToolMessage.isInstance(result) && result.artifact?.isError === true) {
           result.status = "error"

package/lib/agents/summarize-on-timeout.js

@@ -60,14 +60,17 @@ export async function summarizePartialWork({
       reason === "timeOut"
         ? `Agent task was not completed within its time limit. Write short, precise progress summary so user can decide whether to continue. State completed work and immediate next work. Do not claim work not shown. Start with: Agent did not finish within time! End with: Continue running or stop? No other questions to the user allowed!`
         : `Agent task was interrupted. Reason: ${reason}. Based on conversation history, provide brief summary of completed work and remaining work. Be concise.`
-    summaryPrompt += `\n\n Conversation Snippet: \n\n ${conversationSnippet.trim()}`
+    summaryPrompt += `\n\n Conversation Snippet: \n\n`
 
     let summaryTimer
     try {
       const response = await Promise.race([
         (async () => {
+          const instruction = new HumanMessage(summaryPrompt)
+          instruction.name = "cap-js-agents-summarize"
           const model = await getModel()
-          return model.invoke([new HumanMessage(summaryPrompt)])
+          // Two messages, so the first one can be logged as the prompt for summarization in MLflow
+          return model.invoke([instruction, new HumanMessage(conversationSnippet.trim())])
         })(),
         new Promise((_, reject) => {
           summaryTimer = setTimeout(() => reject(new Error("Summary LLM call timed out")), timeout)