@cap-js/agents 0.9.4 → 0.9.6

package/lib/telemetry/mlflow/exporter/DatabricksExporter.js

@@ -11,7 +11,7 @@ export class DatabricksExporter extends MlflowExporter {
   ) {
     const { uc, warehouseId } = this._creds
     const ucPrefix = `${uc.catalog}.${uc.schema}.${uc.tablePrefix}`
-    let url = `/api/4.0/mlflow/traces/${encodeURIComponent(ucPrefix)}/tr-${traceId}/assessments`
+    let url = `/api/4.0/mlflow/traces/${encodeURIComponent(ucPrefix)}/${traceId}/assessments`
     if (warehouseId) url += `?sql_warehouse_id=${encodeURIComponent(warehouseId)}`
     await this._fetch(url, {
       trace_id: traceId,

package/lib/telemetry/mlflow/prompts.js

@@ -71,9 +71,9 @@ export function syncSystemPrompt(messages) {
 export function resolvePromptName(srv) {
   if (!srv?.name) return ""
   const agentDir = resolveAgentDir(srv)
-  if (!agentDir) return srv.name
+  if (!agentDir) return _mlflowName(srv.name)
   const root = cds.root ?? process.cwd()
-  return relative(root, join(agentDir, "AGENTS.md")).replace(/\\/g, "/")
+  return _mlflowName(relative(root, join(agentDir, "AGENTS.md")).replace(/\\/g, "/"))
 }
 
 export function hashPrompt(text) {
@@ -88,6 +88,10 @@ function _description(name) {
   return `System prompt for CAP agent service "${name.split("/")[0]}"`
 }
 
+function _mlflowName(name) {
+  return String(name).replace(/[\\/.:]/g, "_")
+}
+
 function _registrationTags() {
   return [{ key: "mlflow.prompt.is_prompt", value: "true" }]
 }

package/lib/utils/caching.js

@@ -0,0 +1,132 @@
+import cds from "@sap/cds"
+
+export const PROMPT_CACHE_MODEL_PARAMS = Symbol("promptCacheModelParams")
+
+const CACHE_CONTROL_EPHEMERAL = { type: "ephemeral" }
+
+export function isPromptCachingModel(model) {
+  return promptCachingMode(model) !== undefined
+}
+
+export function withPromptCachingParams(model, params) {
+  if (params !== undefined && (typeof params !== "object" || Array.isArray(params))) return params
+  const mode = promptCachingMode(model)
+  const base = params || {}
+  if (mode === "gpt-implicit") {
+    return {
+      ...base,
+      ...(base.prompt_cache_options === undefined
+        ? { prompt_cache_options: { mode: "implicit", ttl: "30m" } }
+        : {}),
+    }
+  }
+  if (mode === "gpt-retention") {
+    return {
+      ...base,
+      ...(base.prompt_cache_retention === undefined ? { prompt_cache_retention: "24h" } : {}),
+    }
+  }
+  return params
+}
+
+export function withPromptCachingMessages(model, messages, opts) {
+  if (promptCachingMode(model) !== "claude") return { messages, opts }
+
+  const cachedMessages = [...messages]
+  addCacheControlToLast(cachedMessages, "system")
+  addCacheControlToLast(cachedMessages, "ai")
+  addCacheControlToLast(cachedMessages, "human")
+
+  if (!opts?.tools?.length) return { messages: cachedMessages, opts }
+  const tools = [...opts.tools]
+  tools[tools.length - 1] = { ...tools[tools.length - 1], cache_control: CACHE_CONTROL_EPHEMERAL }
+  return { messages: cachedMessages, opts: { ...opts, tools } }
+}
+
+export function withPromptCachingOptions(model, opts) {
+  const mode = promptCachingMode(model)
+  if (mode === "nova" && !opts?.cache_control) {
+    return { ...opts, cache_control: CACHE_CONTROL_EPHEMERAL }
+  }
+  if (!isGptCachingMode(mode)) return opts
+
+  const params = opts?.[PROMPT_CACHE_MODEL_PARAMS] || {}
+  if (params.prompt_cache_key !== undefined) return opts
+  return {
+    ...opts,
+    [PROMPT_CACHE_MODEL_PARAMS]: {
+      ...params,
+      prompt_cache_key: opts?.prompt_cache_key ?? buildPromptCacheKey(),
+    },
+  }
+}
+
+function buildPromptCacheKey() {
+  return cds.context?.tenant || ""
+}
+
+function promptCachingMode(model) {
+  const name = String(model || "")
+  if (/anthropic|claude/i.test(name)) return "claude"
+  if (/(?:^|[-_])nova(?:[-_]|$)/i.test(name) || /amazon.*nova/i.test(name)) return "nova"
+
+  const version = gptVersion(name)
+  if (!version) return undefined
+  if (version.major > 5 || (version.major === 5 && version.minor >= 6)) return "gpt-implicit"
+  if ((version.major === 5 && version.minor < 6) || (version.major === 4 && version.minor === 1)) {
+    return "gpt-retention"
+  }
+}
+
+function isGptCachingMode(mode) {
+  return mode === "gpt-implicit" || mode === "gpt-retention"
+}
+
+function gptVersion(model) {
+  const match = model.match(/(?:^|[^a-z0-9])gpt[-_]?([0-9]+)(?:[._-]([0-9]+))?/i)
+  return match && { major: Number(match[1]), minor: Number(match[2] || 0) }
+}
+
+function addCacheControlToLast(messages, type) {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    if (messageType(messages[index]) === type && hasTextContent(messages[index])) {
+      messages[index] = withCacheControl(messages[index])
+      return
+    }
+  }
+}
+
+function messageType(message) {
+  return message._getType?.() || message.type
+}
+
+function hasTextContent(message) {
+  return (
+    (typeof message.content === "string" && message.content.length > 0) ||
+    (Array.isArray(message.content) &&
+      message.content.some((block) => block?.type === "text" && block.text?.length > 0))
+  )
+}
+
+function withCacheControl(message) {
+  const content = message.content
+  if (typeof content === "string") {
+    return cloneMessage(message, [
+      { type: "text", text: content, cache_control: CACHE_CONTROL_EPHEMERAL },
+    ])
+  }
+  if (!Array.isArray(content)) return message
+
+  for (let index = content.length - 1; index >= 0; index--) {
+    if (content[index]?.type === "text") {
+      const nextContent = [...content]
+      nextContent[index] = { ...nextContent[index], cache_control: CACHE_CONTROL_EPHEMERAL }
+      return cloneMessage(message, nextContent)
+    }
+  }
+  return message
+}
+
+function cloneMessage(message, content) {
+  return Object.assign(Object.create(Object.getPrototypeOf(message)), message, { content })
+}

package/lib/utils/utils.js

@@ -1,20 +1,8 @@
 import cds from "@sap/cds"
 import { domainToASCII } from "node:url"
 
-function resolveI18n(value, locale) {
-  if (!value) return undefined
-  const match = /{i18n>([^}]+)}/.exec(value)
-  if (match) {
-    return cds.i18n?.labels?.texts4?.(locale)?.[match[1]] || value
-  }
-  return value
-}
-
-export function getAgentLogger(srv) {
-  const slug = slugified(srv.name)
-  const agentSlug = slug.endsWith("-agent") ? slug : `${slug}-agent`
-  return cds.log("agents:" + srv.name, { label: agentSlug })
-}
+import { resolveI18n, getFilteredEntities } from "@cap-js/mcp/lib/utils/tools-shared.js"
+export { resolveI18n, getFilteredEntities }
 
 /**
  * Mirrors CAP's internal slug rules used for service path generation.
@@ -52,31 +40,6 @@ export function getDescription(obj, locale) {
   return result || undefined
 }
 
-export function getFilteredEntities(srv) {
-  return Object.fromEntries(
-    Object.entries(srv.entities || {})
-      .filter(
-        ([name, entity]) =>
-          !(entity["@cds.autoexposed"] && !entity["@cds.autoexpose"]) &&
-          !name.endsWith("DraftAdministrativeData") &&
-          !name.endsWith(".texts") &&
-          !entity["@cds.api.ignore"],
-      )
-      .sort(([a], [b]) => a.localeCompare(b)),
-  )
-}
-
-export function getFilteredActions(srv) {
-  const actions = {}
-  for (const op of srv.actions || []) {
-    if ((op.kind === "action" || op.kind === "function") && !op["@cds.api.ignore"]) {
-      const localName = op.name.split(".").pop()
-      actions[localName] = op
-    }
-  }
-  return actions
-}
-
 /**
  * Sanitize an agent name into a valid LangChain/LLM tool name.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/agents",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "CDS plugin for building agents",
   "author": "SAP SE (https://www.sap.com)",
   "license": "Apache-2.0",
@@ -41,8 +41,8 @@
   ],
   "dependencies": {
     "@a2a-js/sdk": "^0.3.12",
-    "@cap-js/attachments": "^4",
-    "@cap-js/mcp": "^1.4",
+    "@cap-js/attachments": ">=3",
+    "@cap-js/mcp": "^1.5",
     "@langchain/anthropic": "^1.5.1",
     "@langchain/core": "^1",
     "@langchain/langgraph": "^1",
@@ -147,7 +147,7 @@
           "image/jpeg"
         ]
       },
-      "pool": {
+      "quotas": {
         "maxConcurrentTasks": 10,
         "maxConcurrentTasksPerUser": 4,
         "maxTasksPerHour": 100,
@@ -159,7 +159,6 @@
         "maxLLMTokensPerTask": 200000,
         "maxLLMCallTimeout": "120s",
         "maxExecutionTimePerTask": "5min",
-        "timeoutGrace": "15s",
         "maxIncomingMessageLength": 5000
       }
     },
@@ -190,7 +189,7 @@
         }
       },
       "[development]": {
-        "llm": "mock"
+        "llm": "auto"
       },
       "[with-claude]": {
         "llm": "anthropic"

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

@@ -1,10 +1,27 @@
 import cds from "@sap/cds"
 import { agentMessage, firstDataPart, partsToText } from "../../../lib/utils/message-handling.js"
 import { audit, short } from "../../../lib/utils/utils.js"
+import * as metrics from "../../../lib/telemetry/metrics.js"
 
 const LOG = cds.log("agents")
 
 export const HITL_METADATA_KEY = "sap.cds.agents.hitl"
+export const TIMEOUT_HITL_METADATA_KEY = "sap.cds.agents.timeout-hitl"
+export const INPUT_REQUIRED_METADATA_KEY = "sap.cds.agents.input-required"
+
+function approvalOptions() {
+  return [
+    { value: "approve", label: cds.i18n.messages.at("HITL_APPROVE") },
+    { value: "reject", label: cds.i18n.messages.at("HITL_REJECT") },
+  ]
+}
+
+function timeoutOptions() {
+  return [
+    { value: "continue", label: cds.i18n.messages.at("HITL_CONTINUE") },
+    { value: "reject", label: cds.i18n.messages.at("HITL_STOP") },
+  ]
+}
 export const requiresHitl = (result) =>
   result?.__interrupt__?.length > 0 || result?.interrupts?.length > 0
 
@@ -22,6 +39,21 @@ export function parseResumeDecision(userText) {
   }
 }
 
+export function patchRejectMessage(dataPart) {
+  if (!Array.isArray(dataPart?.decisions)) return dataPart
+  return {
+    ...dataPart,
+    decisions: dataPart.decisions.map((decision) =>
+      decision?.type === "reject"
+        ? {
+            ...decision,
+            message: `The user rejected this particular tool invocation with the reason: ${decision.message ?? ""}`,
+          }
+        : decision,
+    ),
+  }
+}
+
 function decisionsForAudit(resume, actionRequests = []) {
   if (!Array.isArray(resume?.decisions)) return [{ action: null, decision: resume }]
   return resume.decisions.map((decision, index) => ({
@@ -30,6 +62,25 @@ function decisionsForAudit(resume, actionRequests = []) {
   }))
 }
 
+function hitlMetricAttrs(serviceName, action, decision) {
+  return {
+    ...metrics.attrs(serviceName),
+    "agent.hitl.action": action?.name,
+    ...(decision && { "agent.hitl.decision": decision }),
+  }
+}
+
+function recordHitlDecisions(serviceName, actionRequests, resume, actionOffset = 0) {
+  if (!Array.isArray(resume?.decisions)) return
+  for (const [index, decision] of resume.decisions.entries()) {
+    if (!decision?.type) continue
+    metrics.hitlDecisions.add(
+      1,
+      hitlMetricAttrs(serviceName, actionRequests[index + actionOffset], decision.type),
+    )
+  }
+}
+
 function extractInterruptDescription(resultOrErr) {
   const interrupt = resultOrErr.__interrupt__?.[0] || resultOrErr.interrupts?.[0]
   const payload = interrupt?.value
@@ -173,7 +224,10 @@ function publishInputRequired({ requestContext, eventBus, description, interrupt
     contextId,
     status: {
       state: "input-required",
-      message: agentMessage(description, interruptData, { [HITL_METADATA_KEY]: pending }),
+      message: agentMessage(description, interruptData, {
+        [HITL_METADATA_KEY]: pending,
+        [INPUT_REQUIRED_METADATA_KEY]: { options: approvalOptions() },
+      }),
       timestamp: new Date().toISOString(),
     },
     final: true,
@@ -181,6 +235,64 @@ function publishInputRequired({ requestContext, eventBus, description, interrupt
   eventBus.finished()
 }
 
+export function isTimeoutHitl(task) {
+  return task?.status?.message?.metadata?.[TIMEOUT_HITL_METADATA_KEY] === true
+}
+
+export function publishTimeoutHitl({ requestContext, eventBus, description, serviceName }) {
+  const { taskId, contextId } = requestContext
+  LOG.info(serviceName, "-", "timeout awaiting decision", { conversation: short(contextId) })
+  audit("AgentInputRequired", {
+    data: { taskId, contextId, service: serviceName, reason: "timeout", description },
+  })
+  eventBus.publish({
+    kind: "status-update",
+    taskId,
+    contextId,
+    status: {
+      state: "input-required",
+      message: agentMessage(description, undefined, {
+        [TIMEOUT_HITL_METADATA_KEY]: true,
+        [INPUT_REQUIRED_METADATA_KEY]: { options: timeoutOptions() },
+      }),
+      timestamp: new Date().toISOString(),
+    },
+    final: true,
+  })
+}
+
+export async function resumeTimeoutHitl({ requestContext, eventBus, stream, signal }) {
+  const { taskId, contextId } = requestContext
+  const decision = partsToText(requestContext.userMessage?.parts).trim()
+  if (!decision) throw new Error(cds.i18n.messages.at("RESUME_REQUIRES_TEXT"))
+
+  if (/^(continue|approve|yes|confirm|ok)$/i.test(decision)) {
+    LOG.info("timeout continuation approved", { conversation: short(contextId) })
+    audit("AgentTaskResumed", {
+      data: { taskId, contextId, service: cds.context?.["agent.service"], reason: "timeout" },
+    })
+    const resumed = await stream(null, signal)
+    return resumed.state
+  }
+
+  LOG.info("timeout continuation declined", { conversation: short(contextId) })
+  audit("AgentTaskCanceled", {
+    data: { taskId, contextId, service: cds.context?.["agent.service"], reason: "timeout" },
+  })
+  eventBus.publish({
+    kind: "status-update",
+    taskId,
+    contextId,
+    status: {
+      state: "canceled",
+      message: agentMessage("Task stopped by user after timeout."),
+      timestamp: new Date().toISOString(),
+    },
+    final: true,
+  })
+  return undefined
+}
+
 export async function resumeHitl({ requestContext, graph, config, eventBus, stream, signal }) {
   const { taskId, contextId } = requestContext
   const dataPart = firstDataPart(requestContext.userMessage?.parts)
@@ -189,14 +301,16 @@ export async function resumeHitl({ requestContext, graph, config, eventBus, stre
     throw new Error(cds.i18n.messages.at("RESUME_REQUIRES_TEXT"))
   }
   const { Command } = await import("@langchain/langgraph")
-  let resume = dataPart !== undefined ? dataPart : parseResumeDecision(userText)
+  let resume = dataPart !== undefined ? patchRejectMessage(dataPart) : parseResumeDecision(userText)
   let actionRequests = []
 
   if (Array.isArray(resume?.decisions)) {
     const pending = pendingHitlFromTask(requestContext.task)
     const actionCount = pending?.actionCount ?? (await getPendingHitlActionCount(graph, config))
     actionRequests = pendingActionRequests(requestContext.task, pending)
+    const priorDecisionCount = pending?.decisions?.length || 0
     const decisions = [...(pending?.decisions || []), ...resume.decisions]
+    recordHitlDecisions(cds.context?.["agent.service"], actionRequests, resume, priorDecisionCount)
     if (decisions.length < actionCount) {
       const interruptData = firstDataPart(requestContext.task?.status?.message?.parts)
       const nextPending = { ...pending, actionCount, decisions }
@@ -243,7 +357,11 @@ export function handleHitlInterrupt({
   const { taskId, contextId } = requestContext
   const description = extractInterruptDescription(result)
   const interruptData = extractInterruptData(result)
-  LOG.info("input-required", { conversation: short(contextId), service: serviceName, duration })
+  const actionRequests = interruptData?.actionRequests || interruptActionRequests(result)
+  for (const action of actionRequests) {
+    metrics.hitlGates.add(1, hitlMetricAttrs(serviceName, action))
+  }
+  LOG.info(serviceName, "-", "input-required", { conversation: short(contextId), duration })
   onInputRequired?.(description)
   audit("AgentInputRequired", {
     data: { taskId, contextId, service: serviceName, description, interruptData },