@cap-js/agents 0.9.7 → 0.9.8

package/srv/handlers/graph-executor/hitl.js

@@ -156,6 +156,10 @@ export function composeHitlDecisionNote(actionRequests, resume) {
       lines.push("- User edited " + action(matched) + " to " + action(decision.editedAction) + ".")
       continue
     }
+    if (decision?.type === "reject") {
+      lines.push("- User explicitly rejected " + action(original) + ".")
+      continue
+    }
   }
   if (!lines.length) {
     return undefined
@@ -163,6 +167,28 @@ export function composeHitlDecisionNote(actionRequests, resume) {
   return ["User HITL decisions (not tool failures):", ...lines].join("\n")
 }
 
+// The generic combined "call" tool carries its target action in args.action. HITL
+// gates it per-call via a `when` predicate, so the interrupt only fires for a gated
+// action. An edit must therefore not repoint args.action at a *different* action —
+// that would run an un-gated action under the approval granted for the gated one.
+// Editing the parameters is fine; the action itself is fixed.
+const GENERIC_CALL_TOOL = "call"
+
+export function guardHitlEdits(resume, actions = []) {
+  if (!Array.isArray(resume?.decisions)) return resume
+  resume.decisions.forEach((decision, index) => {
+    if (decision?.type !== "edit") return
+    const original = actions[index]
+    if (original?.name !== GENERIC_CALL_TOOL) return
+    const from = original.args?.action
+    const to = decision.editedAction?.args?.action
+    if (to !== undefined && from !== undefined && to !== from) {
+      throw new Error(`HITL edit must not change the gated action (expected "${from}", got "${to}").`)
+    }
+  })
+  return resume
+}
+
 async function getPreInterruptToolCalls(graph, config) {
   try {
     if (typeof graph.getState !== "function") return []
@@ -339,6 +365,7 @@ export async function resumeHitl({ requestContext, graph, config, eventBus, stre
   const originalActions = actionRequests.length
     ? actionRequests
     : await getPreInterruptToolCalls(graph, config)
+  guardHitlEdits(resume, originalActions)
   const decisionNote = composeHitlDecisionNote(originalActions, resume)
   const commandArgs = { resume }
   if (decisionNote) commandArgs.update = { _hitlDecisionNote: decisionNote }

package/srv/handlers/graph-executor.js

@@ -19,6 +19,7 @@ import {
   resumeHitl,
   resumeTimeoutHitl,
 } from "./graph-executor/hitl.js"
+import { registerShutdownHook } from "./graph-executor/crash-handler.js"
 
 const LOG = cds.log("agents")
 
@@ -145,6 +146,9 @@ class GraphExecutor {
     this._recursionLimit = options.recursionLimit ?? null
     /** @type {Map<string, AbortController>} per-task abort controllers */
     this._abortControllers = new Map()
+    /** @type {Map<string, string | undefined>} task tenant by task ID */
+    this._taskTenants = new Map()
+    registerShutdownHook(this)
   }
 
   /**
@@ -199,6 +203,7 @@ class GraphExecutor {
     // final visual (collapse to the last turn's bubble at task completion).
     let currentMsgId = null
     let thinkingCount = 0
+    let thinkingMsgId = null
     // Holds a trailing fragment of the previous chunk that is a prefix of a known
     // pseudonym hash. Prepended to the next chunk so split hashes are resolved correctly.
     let pendingPrefix = ""
@@ -247,6 +252,9 @@ class GraphExecutor {
           pendingPrefix = ""
           if (!raw) continue
 
+          if (thinkingMsgId !== null && currentMsgId !== thinkingMsgId) thinkingCount++
+          thinkingMsgId = currentMsgId
+
           // Hashes look like name-8hexchars and never contain spaces.
           // On non-last chunks, slice last token and append to next chunk
           // to avoid unresolved boundaries
@@ -275,7 +283,6 @@ class GraphExecutor {
               parts: [{ kind: "text", text }],
             },
           })
-          if (lastChunk) thinkingCount++
           tokenCount++
         } else if (mode === "updates") {
           // The updates stream yields per-node deltas — { <node>: { messages: [oneNewMessage] } },
@@ -382,8 +389,6 @@ class GraphExecutor {
         reason,
         checkpointer: this._graph?.checkpointer,
         getModel: () => this._srv.send("buildModel"),
-        // Summary runs after graph abort, so no execution-time grace is needed.
-        timeout: 10_000,
       }),
     )
   }
@@ -397,6 +402,7 @@ class GraphExecutor {
     // Cooperative cancellation: per-task AbortController
     const controller = new AbortController()
     this._abortControllers.set(taskId, controller)
+    this._taskTenants.set(taskId, cds.context?.tenant)
 
     // A2A context for tracing
     if (!cds.context) {
@@ -406,6 +412,7 @@ class GraphExecutor {
     cds.context["agent.context.id"] = contextId
     cds.context["agent.service"] = serviceName
     cds.context["agent.eventBus"] = eventBus
+    cds.context["agent.request.metadata"] = requestContext.userMessage?.metadata ?? {}
 
     // REVISIT: Resolve graph early for pseudonymizeUserMessage. Mid-term move into beforeAgent together with Audit & Telemetry which rely on it
     const graph = await this._resolveGraph()
@@ -910,16 +917,19 @@ class GraphExecutor {
           eventBus._graphResult = { messages: result.messages || [] }
         }
 
+        const usageMeta =
+          usageData?.total_tokens > 0 ? { "sap.cds.agents.token-usage": usageData } : undefined
         eventBus.publish({
           kind: "status-update",
           taskId,
           contextId,
           status: {
             state: "completed",
-            message: agentMessage(output),
+            message: agentMessage(output, undefined, usageMeta),
             timestamp: new Date().toISOString(),
           },
           final: true,
+          metadata: usageMeta,
         })
       } catch (err) {
         // Aborted (client disconnect or tasks/cancel) — publish canceled, not failed
@@ -1049,6 +1059,7 @@ class GraphExecutor {
         setSpanAttrs(rootSpan, linkTraceToPrompt())
 
         this._abortControllers.delete(taskId)
+        this._taskTenants.delete(taskId)
         metrics.concurrentExecutions.add(-1, mAttrs)
 
         // Update task record with usage data (non-blocking, best effort)
@@ -1146,13 +1157,16 @@ function aggregateUsageData(messages) {
     cache_creation_input_tokens: 0,
     cache_read_input_tokens: 0,
     reasoning_tokens: 0,
+    context_tokens: 0,
   }
   for (let i = 0; i < messages.length; i++) {
     if (!messages[i].usage_metadata) continue
     const innerRes = convertUsageData(messages[i].usage_metadata)
     Object.keys(innerRes).forEach((k) => {
-      if (innerRes[k] != null) result[k] += innerRes[k]
+      if (k in result && innerRes[k] != null) result[k] += innerRes[k]
     })
+    if (innerRes.input_tokens != null)
+      result.context_tokens = innerRes.input_tokens + (innerRes.output_tokens || 0)
   }
   return result
 }

package/srv/handlers/index.js

@@ -5,6 +5,7 @@ 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"
+import { effectiveDefinition } from "../../lib/utils/utils.js"
 
 const LOG = cds.log("agents")
 
@@ -91,12 +92,16 @@ 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"
+    const def = effectiveDefinition(srv)
+    const name = def?.["@agent.llm"] || srv?.options?.agent?.llm || "llm"
     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)
+    const { credentials, ...o } = options
+    if (credentials) o.credentials = '{ *** }'
+    LOG.debug (`Creating LLMProvider instance for cds.requires.${name} with options:`, o)
     return new LLMProvider(name, { ...options, ...req.data })
   })
 

package/srv/handlers/mcp-tools.js

@@ -1,6 +1,6 @@
 import cds from "@sap/cds"
 import { generateTools } from "./tools.js"
-import { toolName } from "../../lib/utils/utils.js"
+import { toolName, mcpToolKind } from "../../lib/utils/utils.js"
 
 const LOG = cds.log("agents:mcp")
 
@@ -45,7 +45,16 @@ 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}`
+  for (const tool of tools) {
+    // Keep PerActionTool's actionName so status-update can resolve the action's label.
+    tool.metadata = {
+      ...tool.metadata,
+      serviceName,
+      kind: mcpToolKind(tool.name),
+      ...(tool.actionName && { actionName: tool.actionName }),
+    }
+    tool.name = `${prefix}${tool.name}`
+  }
 
   LOG.debug(
     `Got ${tools.length} MCP tools from ${serviceName}: ${tools.map((t) => t.name).join(", ")}`,

package/srv/handlers/subagent-tools.js

@@ -78,9 +78,9 @@ function formatToolResult({ text, files }) {
 /**
  * Wrap an A2A client as a LangChain tool the agent can call.
  */
-function createA2ATool(client, agentCard) {
+function createA2ATool(client, agentCard, serviceName) {
   const subagent = agentCard.name
-  return tool(
+  const t = tool(
     async ({ message }) => {
       try {
         const messageId = cds.utils.uuid()
@@ -116,6 +116,8 @@ function createA2ATool(client, agentCard) {
       }),
     },
   )
+  t.metadata = { ...t.metadata, kind: "agent", agentName: agentCard.name, serviceName }
+  return t
 }
 
 export async function buildSubAgentToolLocally(serviceName) {
@@ -130,7 +132,7 @@ export async function buildSubAgentToolLocally(serviceName) {
 
   const { RequestContext, DefaultExecutionEventBus } = await import("@a2a-js/sdk/server")
 
-  return tool(
+  const localTool = tool(
     async ({ message }) => {
       const taskId = cds.utils.uuid()
       const contextId = cds.utils.uuid()
@@ -221,6 +223,13 @@ export async function buildSubAgentToolLocally(serviceName) {
       }),
     },
   )
+  localTool.metadata = {
+    ...localTool.metadata,
+    kind: "agent",
+    agentName: agentCard.name,
+    serviceName,
+  }
+  return localTool
 }
 
 export async function buildSubAgentToolFromConnection(serviceName) {
@@ -334,7 +343,7 @@ export async function buildSubAgentToolFromConnection(serviceName) {
   )
   const client = await factory.createFromAgentCard(agentCard)
 
-  return createA2ATool(client, agentCard)
+  return createA2ATool(client, agentCard, serviceName)
 }
 
 export function buildSubAgentTool(serviceName) {

package/srv/handlers/system-prompt.js

@@ -1,32 +1,35 @@
 import cds from "@sap/cds"
 import { getDescription } from "../../lib/utils/utils.js"
+const LOG = cds.log("agents")
 
 export function buildSystemPrompt(srv) {
-  const serviceDesc = getDescription(srv.definition) || `Service ${srv.name}`
-
-  return [
-    `You are an AI assistant for the "${srv.name}" service.`,
-    serviceDesc,
-    "",
-    "Always use the provided tools to answer questions - do not make up data.",
-    "Use the `describe` tool to get information about the service's entities and actions if needed.",
-    "Use the `query` tool to read data from entities.",
-    cds.env.agents?.per_action_tool !== false
-      ? "Call action and function tools directly by name."
-      : "Use the `call` tool to invoke actions and functions.",
-    ...(cds.env.agents?.fileIO?.enabled
-      ? [
-          "When the user's message contains '[Uploaded files: ...]', use the `read_file` tool to read each listed file before answering.",
-          "Use `emit_file_part` to return files in your response.",
-        ]
-      : []),
-    "Be concise and helpful.",
-    ...(cds.env.agents?.masking
-      ? [
-          `## How to handle pseudonymized values`,
-          `Never comment on pseudonymization and that you had to work with pseudonymized values but use the pseudonymized values in responses like it would be regular values!`,
-          `The user sees the actual values and thus should not be made aware of any pseudonymization that has taken place internally.`,
-        ]
-      : []),
-  ].join("\n")
+
+  let text = `
+
+    You are an AI assistant for the local CAP service \`${srv.name}\`.
+    ${ getDescription(srv.definition) || '' }
+    Use the provided tools to answer questions:
+
+    - the \`describe\` tool to learn about the service's entities and actions.
+    - the \`query\` tool to read data from entities.
+    - the \`call\` tool to invoke actions, or individual action tools.
+
+    IMPORTANT: Don't guess element names when \`query\`ing entities.
+    Use the \`describe\` tool instead to find correct element names.
+
+    ${ cds.env.agents?.fileIO?.enabled ? `## File I/O
+    When the incomming request message contains '[Uploaded files: ...]',
+    use the \`read_file\` tool to read each listed file before answering.
+    Use the \`emit_file_part\` tool to return files in your response.` : ''}
+
+    ${ cds.env.agents?.masking ? `## How to handle pseudonymized values
+    Never comment on pseudonymization and that you had to work with pseudonymized values
+    but use the pseudonymized values in responses like it would be regular values!
+    The user sees the actual values and thus should not be made aware of any
+    pseudonymization that has taken place internally.` : ''}
+
+  `.replace(/ {4,}/g,'').trim()
+
+  if (LOG._debug) LOG.debug (srv.name, '-', "using system prompt:", '\n\n'+ text +'\n')
+  return text
 }

package/srv/handlers/tools.js

@@ -183,31 +183,32 @@ class CallActionTool extends DynamicStructuredTool {
  * @param {object} srv - CDS ApplicationService
  */
 export function generateTools(srv) {
-  const entities = getFilteredEntities(srv)
-  const actions = getFilteredActions(srv)
+  const entities = getFilteredEntities(srv), has_entities = Object.keys(entities).length > 0
+  const actions = getFilteredActions(srv), has_actions = Object.keys(actions).length > 0
 
   const tools = []
 
-  // Query tool — one tool for reading all entities
-  const entityNames = Object.keys(entities)
-  if (entityNames.length > 0) {
-    tools.push(new GenericReadTool(srv, entities))
-  }
-
   // Describe tool — introspect service model
-  const actionNames = Object.keys(actions)
-  if (entityNames.length > 0 || actionNames.length > 0) {
+  if (has_entities || has_actions) {
+    LOG.debug(srv.name, '–', `adding generic 'describe' tool`)
     tools.push(new DescribeTool(srv, entities, actions))
   }
 
+  // Query tool — one tool for reading all entities
+  if (has_entities) {
+    LOG.debug(srv.name, '–', `adding generic 'query' entity tool`)
+    tools.push(new GenericReadTool(srv, entities))
+  }
+
   // Action/function tools — per-action (default) or combined call action
-  const usePerActionTools = cds.env.agents?.per_action_tool !== false
-  if (actionNames.length > 0) {
-    if (usePerActionTools) {
+  if (has_actions) {
+    if (cds.env.mcp?.per_action_tool) {
       for (const [name, action] of Object.entries(actions)) {
+        LOG.debug(srv.name, '–', `adding specific tool to call action '${name}'`)
         tools.push(new PerActionTool(srv, name, action))
       }
     } else {
+      LOG.debug(srv.name, '–', `adding generic 'call' action tool`)
       tools.push(new CallActionTool(srv, actions))
     }
   }