@cap-js/agents 0.9.6 → 0.9.8

package/_i18n/messages_zh_TW.properties

@@ -0,0 +1,48 @@
+# Agent status messages (shown during task execution)
+#XMSG Status info message send to the user client when a tool is called. {0} = tool name
+agent_status_calling_tools=正在呼叫 {0}
+#XMSG Status info message send to the user client when an entity is being queried. {0} = entity name
+agent_status_querying=正在查詢 {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=正在處理工具回應
+#XMSG Status info message send to the user client after multiple tool results returned and the agent is processing it
+agent_status_processing_responses=正在處理工具回應
+agent_status_summarizing_progress=已中斷代理程式；正在彙總進度。
+AGENT_SUMMARY_QUOTA_FALLBACK=由於工作細項已到達資源耗用限制，因此已停止。可能已完成部份工作 - 請查看結果或使用較簡單的請求重試。
+AGENT_SUMMARY_TIMEOUT_FALLBACK=由於工作細項已到達時間限制，因此已停止。進度可能不完整，要繼續執行或停止？
+
+# Authentication
+#XMSG Error message for HTTP 401 status
+UNAUTHORIZED=未授權
+#XMSG Error message for HTTP 403 status
+FORBIDDEN=已禁止
+
+# Input validation
+#XMSG Error message send to the users client when their message exceeds the limit. {0} = number of allowed characters
+MESSAGE_TOO_LONG=訊息不可超過 {0} 個字元。
+
+# Quota enforcement
+QUOTA_CONCURRENT_TASKS=已達到 {0} 個同時工作細項上限，請稍後再試一次。
+QUOTA_CONCURRENT_TASKS_PER_USER=已達到每位使用者 {0} 個同時工作細項上限，請稍後再試一次。
+QUOTA_TASKS_PER_HOUR=此租用戶已達到每小時 {0} 個工作細項上限，請稍後再試一次。
+QUOTA_TASKS_PER_HOUR_PER_USER=已達到每位使用者每小時 {0} 個工作細項上限，請稍後再試一次。
+QUOTA_TOOL_CALLS_PER_HOUR=已使用每小時的工具呼叫數量上限 ({0})，請稍後再試一次。
+QUOTA_LLM_TOKENS_PER_DAY=已使用今天的 LLM 權杖數量上限 ({0})，請明天再試一次。
+
+# Content filter
+CONTENT_FILTER_BLOCKED=內容安全篩選已凍結您的輸入，請重新撰寫。
+CONTENT_FILTER_UNAVAILABLE=內容安全檢查暫時無法使用，請再試一次。
+CONTENT_FILTER_TOOL_BLOCKED=上次呼叫的工具產生惡意結果，請嘗試不同方向以避免相同惡意資料。
+
+# Push notifications
+PUSH_URL_NOT_ALLOWED=推送通知回呼 URL ''{0}'' 不在允許的網域中：{1}
+
+# HITL
+HITL_APPROVE=核准
+HITL_REJECT=拒絕
+HITL_CONTINUE=繼續
+HITL_STOP=停止
+RESUME_REQUIRES_TEXT=繼續訊息必須包含文字 (例如：''核准'' 或 ''拒絕'') 或資料部份。
+
+# LLM
+LLM_UNAVAILABLE=代理程式暫時無法使用，請稍後再試一次。

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 })
   })
@@ -103,7 +106,9 @@ if (cds.env.requires?.telemetry)
     // Schedule active_users metric computation + MLflow exporter
     cds.on("served", async () => {
       const { setupActiveUsersMetric } = await import("./lib/telemetry/active-users.js")
+      const { setupTraceScrubbing } = await import("./lib/telemetry/span-masking.js")
       setupActiveUsersMetric()
+      await setupTraceScrubbing()
       // Defer LangChain patching so the CDS model is fully loaded before patches land.
       // opt-out via cds.env.agents.trace_langchain = false
       if (cds.env.agents?.trace_langchain !== false) {

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

@@ -1,5 +1,6 @@
 export default async function buildMiddleware(srv, options = {}) {
   const { tools, model } = options
+  const { masking } = await import("./masking.js")
   const { quotaEnforcerMiddleware } = await import("./quota-enforcer.js")
   const { contentFilterMiddleware } = await import("./content-filter.js")
   const { agentActionsMiddleware } = await import("./agent-actions.js")
@@ -18,11 +19,12 @@ export default async function buildMiddleware(srv, options = {}) {
 
   return [
     ...dynamicMcpMiddlewares,
+    masking(srv), // first — all downstream middleware see pseudonymized data
     ...(await quotaEnforcerMiddleware()),
     await contentFilterMiddleware(model),
     await agentActionsMiddleware(),
     patchToolCallsMiddleware(),
-    await statusUpdateMiddleware(),
+    await statusUpdateMiddleware(tools),
     ...(await humanInTheLoopMiddleware(srv, tools)),
     toolSelectionMiddleware(),
     toolWrapMiddleware(srv),

package/lib/agents/middleware/masking.js

@@ -0,0 +1,127 @@
+import cds from "@sap/cds"
+import { createMiddleware, ToolMessage } from "langchain"
+import { randomBytes } from "node:crypto"
+import { decode, encode } from "@toon-format/toon"
+import { ensureSession, pseudonymize, resolveRemoteMcpTool } from "../../masking/index.js"
+import { resolveArgs, needsMasking } from "../../masking/structured/index.js"
+import z from "zod"
+import { Command, StateSchema, ReducedValue, isCommand } from "@langchain/langgraph"
+
+// REVISIT: Whether it is possible to make it easier without the ReducedValue class
+const stateSchema = new StateSchema({
+  seed: new ReducedValue(z.string().default(randomBytes(16).toString("hex")), {
+    reducer: (_current, next) => next,
+  }),
+  hashToOriginal: new ReducedValue(z.map(z.string(), z.string()).default(new Map()), {
+    reducer: (_current, next) => next,
+  }),
+})
+
+export function masking(srv) {
+  if (!cds.env.agents?.masking) return null
+
+  return createMiddleware({
+    name: "masking",
+    stateSchema,
+
+    beforeAgent: async () => {
+      if (!needsMasking(srv.name)) return
+      await ensureSession()
+      cds.context["agent.masking.tools"] = true
+    },
+
+    wrapToolCall: async (request, handler) => {
+      const session = cds.context?.["agent.pseudonyms"]
+      if (!session || !cds.context["agent.masking.tools"]) return handler(request)
+
+      const toolName = request.toolCall?.name
+      const toolArgs = request.toolCall?.args ?? {}
+      const resolvedArgs = resolveArgs(toolArgs, session)
+      const resolvedRequest =
+        resolvedArgs !== toolArgs
+          ? { ...request, toolCall: { ...request.toolCall, args: resolvedArgs } }
+          : request
+
+      const result = await handler(resolvedRequest)
+      const isCmd = isCommand(result)
+      const toolMessage = isCmd ? result.update?.messages?.[0] : result
+
+      let outMessage = toolMessage
+      if (toolMessage?.content) {
+        // Resolve remote MCP tool prefix before srv.send (cds.context differs inside event)
+        const remote = resolveRemoteMcpTool(toolName)
+        const effectiveToolName = remote?.bareName ?? toolName
+
+        // Decode TOON or JSON — pseudonymize operates on decoded objects
+        const { decoded, format } = decodeContent(toolMessage.content)
+        if (decoded && typeof decoded !== "string") {
+          const result = await pseudonymize(
+            {
+              data: decoded,
+              type: toolArgs.cql ? "cql" : "action",
+              seed: session._seed,
+              metadata: {
+                cql: toolArgs.cql,
+                toolName: effectiveToolName,
+                ...(remote?.remoteSrv && { serviceName: remote.remoteSrv.name }),
+              },
+            },
+            srv,
+          )
+
+          session.addMappings(result?.mappings)
+
+          const encoded =
+            format === "toon"
+              ? encode(result.data)
+              : format === "json"
+                ? JSON.stringify(result.data)
+                : result.data
+          if (encoded !== toolMessage.content) {
+            outMessage = new ToolMessage({ ...toolMessage, content: encoded })
+          }
+        } else {
+          // 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 })
+          }
+        }
+      }
+
+      const cmd = new Command({
+        update: {
+          messages: [outMessage],
+          seed: session._seed,
+          hashToOriginal: session._hashToOriginal,
+        },
+      })
+      if (isCmd) return merge(result, cmd)
+      return cmd
+    },
+  })
+}
+
+function merge(c1, c2) {
+  return new Command({
+    ...c1,
+    ...c2,
+    update: {
+      ...c1.update,
+      ...c2.update,
+    },
+  })
+}
+
+function decodeContent(content) {
+  if (typeof content !== "string" || !content) return {}
+  try {
+    return { decoded: decode(content), format: "toon" }
+  } catch {
+    try {
+      return { decoded: JSON.parse(content), format: "json" }
+    } catch {
+      return {}
+    }
+  }
+}

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,20 +27,25 @@ 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}`)
-          cache[mcpUrl] = raw
+          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(", ")}`,
           )
         }),
       )
-      const resolved = placeholders.flatMap(({ mcpUrl }) => cache[mcpUrl] ?? [])
+      const resolved = placeholders.flatMap(({ mcpUrl }) => cache[mcpUrl]?.tools ?? [])
       const staticTools = (request.tools ?? []).filter((t) => !t._mcpDynamic)
       return handler({ ...request, tools: [...staticTools, ...resolved] })
     },
 
     wrapToolCall: async (request, handler) => {
-      const allCached = Object.values(cds.context.__mcpDynamicTools ?? {}).flat()
+      const allCached = Object.values(cds.context.__mcpDynamicTools ?? {}).flatMap(
+        (e) => e.tools ?? [],
+      )
       const tool = allCached.find((t) => t.name === request.toolCall.name)
       if (!tool) return handler(request)
       try {