@cap-js/agents 0.9.5 → 0.9.7

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

@@ -103,7 +103,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/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,6 +19,7 @@ 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(),

package/lib/agents/middleware/masking.js

@@ -0,0 +1,124 @@
+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) {
+          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 {
+          const session = cds.context["agent.pseudonyms"]
+          outMessage = session.scrubText(toolMessage.content)
+        }
+      }
+
+      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

@@ -28,19 +28,21 @@ 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
+          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 {

package/lib/compile.js

@@ -1,10 +1,6 @@
 import cds from "@sap/cds"
-import {
-  getDescription,
-  getFilteredEntities,
-  getFilteredActions,
-  slugified,
-} from "./utils/utils.js"
+import { getFilteredEntities, getFilteredActions } from "@cap-js/mcp/lib/utils/tools-shared.js"
+import { getDescription, slugified } from "./utils/utils.js"
 import { buildAgentCard } from "./protocol/agent-card.js"
 
 const A2A_BASE_PATH = "/a2a"

package/lib/masking/index.js

@@ -0,0 +1,90 @@
+import cds from "@sap/cds"
+import { randomBytes } from "node:crypto"
+import { toolName as normaliseName } from "../utils/utils.js"
+import { PseudonymStore } from "./store.js"
+import { pseudonymizeToolResult } from "./structured/index.js"
+import anonymizeUnstructured from "./unstructured/index.js"
+
+export function resolvePseudonyms(text) {
+  if (typeof text !== "string") return text
+  return cds.context?.["agent.pseudonyms"]?.resolveText(text) ?? text
+}
+
+/**
+ * Input:  { data, type, seed?, metadata? }
+ * Output: { data, mappings?, metadata: { textAnalysisResults?, seed, type } }
+ */
+export async function pseudonymize({ data, type, seed, metadata }, srv) {
+  const effectiveSeed = seed ?? randomBytes(16).toString("hex")
+  const result = { metadata: { seed: effectiveSeed, type } }
+
+  if (type === "unstructured") {
+    const r = await anonymizeUnstructured(data, effectiveSeed)
+    result.data = r.text
+    if (r.mappings?.length) result.mappings = r.mappings
+    if (r.textAnalysisResults) result.metadata.textAnalysisResults = r.textAnalysisResults
+  } else {
+    // data is a decoded object (caller handles TOON/JSON decode+encode)
+    const toolName = metadata?.toolName
+    const srvName = metadata?.serviceName ?? srv?.name
+    const targetSrv = cds.services?.[srvName] ?? srv
+    const model = targetSrv?.model
+
+    const store = new PseudonymStore(effectiveSeed)
+
+    pseudonymizeToolResult({
+      decoded: data,
+      toolName,
+      cql: metadata?.cql,
+      strictMasking: metadata?.strictMasking ?? false,
+      session: store,
+      srv: targetSrv,
+      model,
+    })
+    result.data = data
+
+    if (store._hashToOriginal.size) result.mappings = [...store._hashToOriginal]
+  }
+
+  return result
+}
+
+export async function ensureSession(checkpointer, threadId) {
+  if (cds.context?.["agent.pseudonyms"]) return
+  const { seed, hashToOriginal } = await readMaskingState(checkpointer, threadId)
+  const session = new PseudonymStore(seed, hashToOriginal)
+  cds.context["agent.pseudonyms"] = session
+}
+
+// REVISIT: Should not read checkpointer, should move into a beforeAgent hook
+async function readMaskingState(checkpointer, thread_id) {
+  if (!checkpointer || !thread_id) return {}
+  try {
+    const tuple = await checkpointer.getTuple({ configurable: { thread_id } })
+    const values = tuple?.checkpoint?.channel_values
+    if (!values) return {}
+    return {
+      seed: values.seed,
+      hashToOriginal: values.hashToOriginal,
+    }
+  } catch {
+    return {}
+  }
+}
+
+// For a remote MCP tool name like "catalogservice_query", strip the service prefix
+// and return { bareName, remoteSrv }.  Returns null for local tools.
+export function resolveRemoteMcpTool(prefixedName) {
+  const cache = cds.context?.__mcpDynamicTools
+  if (!cache) return null
+  for (const { serviceName, tools } of Object.values(cache)) {
+    const prefix = normaliseName(`${serviceName}_`)
+    if (!tools?.some((t) => t.name === prefixedName)) continue
+    // If multiple CAP MCPs are included its possible that one of the CAP MCPs owns query if the agent itself does not expose any entities
+    return {
+      bareName: prefixedName.startsWith(prefix) ? prefixedName.slice(prefix.length) : prefixedName,
+      remoteSrv: cds.services?.[serviceName],
+    }
+  }
+  return null
+}

package/lib/masking/store.js

@@ -0,0 +1,80 @@
+import { createHash, randomBytes } from "node:crypto"
+
+export function generatePseudonymTag(seed, value, category) {
+  const hash = createHash("sha256")
+    .update(seed + String(value))
+    .digest("hex")
+    .slice(0, 16)
+  return `${category}-${hash}`
+}
+
+export class PseudonymStore {
+  constructor(seed, existing = new Map()) {
+    this._seed = seed ?? randomBytes(16).toString("hex")
+    this._hashToOriginal = new Map(existing)
+    this._originalToHash = new Map()
+    // Sort by descending key length so tags ("name-abc12345") are processed
+    // before bare hashes ("abc12345") and win in _originalToHash.
+    for (const [hash, original] of [...existing].sort((a, b) => b[0].length - a[0].length)) {
+      const str = String(original)
+      if (!this._originalToHash.has(str)) this._originalToHash.set(str, hash)
+    }
+    this._sortedOriginalPairs = null
+    this._sortedHashPairs = null
+  }
+
+  pseudonymize(value, propertyName) {
+    const str = String(value)
+    if (this._originalToHash.has(str)) return this._originalToHash.get(str)
+    const tag = generatePseudonymTag(this._seed, str, propertyName)
+    const hash = tag.slice(propertyName.length + 1)
+    this._hashToOriginal.set(tag, str)
+    this._hashToOriginal.set(hash, str)
+    this._originalToHash.set(str, tag)
+    // Invalidate sorted cache; rebuilt lazily on next scrub.
+    this._sortedOriginalPairs = null
+    this._sortedHashPairs = null
+    return tag
+  }
+
+  addMappings(mappings) {
+    if (!mappings?.length) return
+    // Sort by descending key length so tags ("name-abc12345") win over bare hashes ("abc12345").
+    const sorted = [...mappings].sort((a, b) => b[0].length - a[0].length)
+    for (const [hash, original] of sorted) {
+      const str = String(original)
+      const key = String(hash)
+      if (!str || !key || str === key) continue
+      if (!this._hashToOriginal.has(key)) this._hashToOriginal.set(key, str)
+      if (!this._originalToHash.has(str)) this._originalToHash.set(str, key)
+    }
+    this._sortedOriginalPairs = null
+    this._sortedHashPairs = null
+  }
+
+  resolve(hash) {
+    return this._hashToOriginal.get(hash) ?? hash
+  }
+
+  resolveText(text) {
+    if (!text || !this._hashToOriginal.size) return text
+    // tag and ID are registered. First go for tags then ID, else artefacts are left in text
+    this._sortedHashPairs ??= [...this._hashToOriginal].sort((a, b) => b[0].length - a[0].length)
+    let result = String(text)
+    for (const [hash, original] of this._sortedHashPairs) result = result.replaceAll(hash, original)
+    return result
+  }
+
+  scrubText(text) {
+    if (!text || !this._originalToHash.size) return text
+    // Replace longest originals first so a shorter original that is a substring
+    // of a longer one (e.g. "Emily" vs "Emily Brontë") does not corrupt it.
+    this._sortedOriginalPairs ??= [...this._originalToHash].sort(
+      (a, b) => b[0].length - a[0].length,
+    )
+    let result = String(text)
+    for (const [original, hash] of this._sortedOriginalPairs)
+      result = result.replaceAll(original, hash)
+    return result
+  }
+}