@cap-js/agents 0.9.1 → 0.9.3

package/README.md

@@ -54,7 +54,7 @@ Both approaches start from a CDS service annotated with `@agent` (as shown in [R
 
 ### Agentify Existing CAP Services
 
-With `@agent` alone, the plugin auto-generates tools from the service's entities and actions, creates a ReAct agent loop, and serves it as a remote agent — no code required.
+With `@agent` alone, the plugin auto-generates tools from the service's entities and actions, creates a [ReAct agent](https://arxiv.org/abs/2210.03629) loop, and serves it as a remote agent — no code required.
 
 ```cds
 @agent
@@ -135,6 +135,7 @@ The following capabilities are experimental and documented separately. Their pub
 - [Configuration](.docs/configuration.md) — using multiple models, global and per-service settings, file I/O, and push notifications
 - [Quota Enforcement](.docs/quota.md) — configurable rate limits and resource quotas
 - [Audit Logging](.docs/audit-logging.md) — immutable audit trail of agent decisions and tool usage
+- [Data Privacy](.docs/data-privacy.md) — deletion of message history
 - [Telemetry](.docs/telemetry.md) — OpenTelemetry metrics, tracing, and MLflow export
 - [Content Filter](.docs/content-filter.md) — SAP AI Core content filtering and prompt injection shielding
 

package/cds-plugin.js

@@ -4,7 +4,7 @@ const LOG = cds.log("agents")
 import { patchLangChain } from "./lib/telemetry/tracing.js"
 import cds_compile_to_a2a from "./lib/compile.js"
 import registerDefaultAgentHandlers from "./srv/handlers/index.js"
-import { slugified } from "./lib/utils/markdown.js"
+import { slugified } from "./lib/utils/utils.js"
 
 cds.compile.to.a2a = cds_compile_to_a2a
 
@@ -96,7 +96,7 @@ cds.on("served", async () => {
   }
 
   if (cds.env.agents?.mlflow) {
-    const { setupMlflowExporter } = await import("./lib/telemetry/mlflow.js")
+    const { setupMlflowExporter } = await import("./lib/telemetry/mlflow/index.js")
     setupMlflowExporter()
   }
 })

package/lib/agents/markdown/backends/outputs-backend.js

@@ -9,6 +9,7 @@
  *
  */
 
+import { getConfig } from "@langchain/langgraph"
 import { isTextMime, globToRegex } from "./mime-utils.js"
 
 function inferMimeType(name) {
@@ -38,11 +39,14 @@ function inferMimeType(name) {
 }
 
 export class OutputsBackend {
-  constructor(taskId, fileStore) {
-    this.taskId = taskId
+  constructor(fileStore) {
     this.fileStore = fileStore
   }
 
+  _taskId() {
+    return getConfig()?.configurable?._taskId || ""
+  }
+
   // CompositeBackend strips the route prefix (/outputs/) before delegating,
   // so paths arrive here as either "/name" (stripped) or "/outputs/name" (direct).
   // _name() handles both forms.
@@ -54,19 +58,19 @@ export class OutputsBackend {
     const name = this._name(filePath)
     const mimeType = options.mimeType || inferMimeType(name)
     const buf = typeof content === "string" ? Buffer.from(content, "utf-8") : Buffer.from(content)
-    await this.fileStore.saveOutputFile(this.taskId, name, mimeType, buf)
+    await this.fileStore.saveOutputFile(this._taskId(), name, mimeType, buf)
     return { success: true }
   }
 
   async exists(filePath) {
     const name = this._name(filePath)
-    const files = await this.fileStore.listOutputFilesMeta(this.taskId)
+    const files = await this.fileStore.listOutputFilesMeta(this._taskId())
     return files.some((f) => f.name === name)
   }
 
   async stat(filePath) {
     const name = this._name(filePath)
-    const files = await this.fileStore.listOutputFilesMeta(this.taskId)
+    const files = await this.fileStore.listOutputFilesMeta(this._taskId())
     const file = files.find((f) => f.name === name)
     if (!file) return null
     return { name: file.name, mimeType: file.mimeType, size: file.size }
@@ -75,12 +79,12 @@ export class OutputsBackend {
   // CompositeBackend re-prepends the route prefix to paths returned here,
   // so return bare "/<name>" paths (without /outputs/) to avoid double-prefix.
   async list(_dirPath) {
-    const files = await this.fileStore.listOutputFilesMeta(this.taskId)
+    const files = await this.fileStore.listOutputFilesMeta(this._taskId())
     return files.map((f) => `/${f.name}`)
   }
 
   async ls(_path) {
-    const files = await this.fileStore.listOutputFilesMeta(this.taskId)
+    const files = await this.fileStore.listOutputFilesMeta(this._taskId())
     return {
       files: files.map((f) => ({
         path: `/${f.name}`,
@@ -93,7 +97,7 @@ export class OutputsBackend {
 
   async glob(pattern, _path) {
     const re = globToRegex(pattern)
-    const files = await this.fileStore.listOutputFilesMeta(this.taskId)
+    const files = await this.fileStore.listOutputFilesMeta(this._taskId())
     return {
       files: files
         .filter((f) => re.test(f.name))
@@ -103,7 +107,7 @@ export class OutputsBackend {
 
   async grep(pattern, _path, glob) {
     const reGlob = glob ? globToRegex(glob) : null
-    const files = await this.fileStore.listOutputFiles(this.taskId)
+    const files = await this.fileStore.listOutputFiles(this._taskId())
     const matches = []
     for (const f of files) {
       if (reGlob && !reGlob.test(f.name)) continue
@@ -120,9 +124,9 @@ export class OutputsBackend {
 
   async read(filePath, offset = 0, limit = 100) {
     const name = this._name(filePath)
-    const file = await this.fileStore.getOutputFile(this.taskId, name)
+    const file = await this.fileStore.getOutputFile(this._taskId(), name)
     if (!file) {
-      const files = await this.fileStore.listOutputFilesMeta(this.taskId)
+      const files = await this.fileStore.listOutputFilesMeta(this._taskId())
       const available = files.map((f) => `/outputs/${f.name}`).join(", ") || "none"
       return { error: `File not found: ${filePath}. Available: ${available}` }
     }
@@ -141,7 +145,7 @@ export class OutputsBackend {
   // for the rationale. Currently unused by our shipped code paths; do not delete.
   async readRaw(filePath) {
     const name = this._name(filePath)
-    const file = await this.fileStore.getOutputFile(this.taskId, name)
+    const file = await this.fileStore.getOutputFile(this._taskId(), name)
     if (!file) return { error: `File not found: ${filePath}` }
     return { bytes: file.bytes, mimeType: file.mimeType, size: file.size }
   }

package/lib/agents/markdown/backends/readonly-backend.js

@@ -0,0 +1,48 @@
+import { FilesystemBackend } from "deepagents"
+
+export class ReadonlyBackend {
+  constructor(options) {
+    // explicitly keep this internal (no class inheritance) so we do not expose write operations
+    this._fsBackend = new FilesystemBackend(options)
+  }
+
+  ls(path) {
+    return this._fsBackend.ls(path)
+  }
+
+  read(filePath, offset, limit) {
+    return this._fsBackend.read(filePath, offset, limit)
+  }
+
+  readRaw(filePath) {
+    return this._fsBackend.readRaw(filePath)
+  }
+
+  grep(pattern, path, glob, maxCount) {
+    return this._fsBackend.grep(pattern, path, glob, maxCount)
+  }
+
+  glob(pattern, path) {
+    return this._fsBackend.glob(pattern, path)
+  }
+
+  downloadFiles(paths) {
+    return this._fsBackend.downloadFiles(paths)
+  }
+
+  write() {
+    return { error: "read-only" }
+  }
+
+  edit() {
+    return { error: "read-only" }
+  }
+
+  delete() {
+    return { error: "read-only" }
+  }
+
+  uploadFiles() {
+    return { error: "read-only" }
+  }
+}

package/lib/agents/markdown/backends/uploads-backend.js

@@ -9,13 +9,22 @@
  *
  */
 
+import { getConfig } from "@langchain/langgraph"
 import { isTextMime, globToRegex } from "./mime-utils.js"
 
 export class UploadsBackend {
-  constructor(contextId, fileStore, userId) {
-    this.contextId = contextId
+  constructor(fileStore) {
     this.fileStore = fileStore
-    this.userId = userId
+  }
+
+  _resolveContext() {
+    const config = getConfig()
+    const rawThreadId = config?.configurable?.thread_id || ""
+    const contextId = rawThreadId.includes(":")
+      ? rawThreadId.split(":").slice(1).join(":")
+      : rawThreadId
+    const userId = config?.configurable?._userId
+    return { contextId, userId }
   }
 
   // CompositeBackend strips the route prefix (/uploads/) before delegating,
@@ -26,12 +35,13 @@ export class UploadsBackend {
   }
 
   async read(filePath, offset = 0, limit = 100) {
+    const { contextId, userId } = this._resolveContext()
     const name = this._name(filePath)
-    const file = await this.fileStore.getInputFile(this.contextId, name, this.userId)
+    const file = await this.fileStore.getInputFile(contextId, name, userId)
 
     if (!file) {
       const available =
-        (await this.fileStore.listInputFiles(this.contextId, this.userId))
+        (await this.fileStore.listInputFiles(contextId, userId))
           .map((f) => `/uploads/${f.name}`)
           .join(", ") || "none"
       return { error: `File not found: ${filePath}. Available: ${available}` }
@@ -58,8 +68,9 @@ export class UploadsBackend {
   // throws `TypeError: backend.readRaw is not a function`. Currently unused
   // by our shipped code paths — do not delete as "dead".
   async readRaw(filePath) {
+    const { contextId, userId } = this._resolveContext()
     const name = this._name(filePath)
-    const file = await this.fileStore.getInputFile(this.contextId, name, this.userId)
+    const file = await this.fileStore.getInputFile(contextId, name, userId)
     if (!file) return { error: `File not found: ${filePath}` }
     return { bytes: file.bytes, mimeType: file.mimeType, size: file.size }
   }
@@ -67,12 +78,14 @@ export class UploadsBackend {
   // CompositeBackend re-prepends the route prefix to paths returned here,
   // so return bare "/<name>" paths (without /uploads/) to avoid double-prefix.
   async list(_dirPath) {
-    const files = await this.fileStore.listInputFiles(this.contextId, this.userId)
+    const { contextId, userId } = this._resolveContext()
+    const files = await this.fileStore.listInputFiles(contextId, userId)
     return files.map((f) => `/${f.name}`)
   }
 
   async ls(_path) {
-    const files = await this.fileStore.listInputFiles(this.contextId, this.userId)
+    const { contextId, userId } = this._resolveContext()
+    const files = await this.fileStore.listInputFiles(contextId, userId)
     return {
       files: files.map((f) => ({
         path: `/${f.name}`,
@@ -84,8 +97,9 @@ export class UploadsBackend {
   }
 
   async glob(pattern, _path) {
+    const { contextId, userId } = this._resolveContext()
     const re = globToRegex(pattern)
-    const files = await this.fileStore.listInputFiles(this.contextId, this.userId)
+    const files = await this.fileStore.listInputFiles(contextId, userId)
     return {
       files: files
         .filter((f) => re.test(f.name))
@@ -94,13 +108,14 @@ export class UploadsBackend {
   }
 
   async grep(pattern, _path, glob) {
+    const { contextId, userId } = this._resolveContext()
     const reGlob = glob ? globToRegex(glob) : null
-    const files = await this.fileStore.listInputFiles(this.contextId, this.userId)
+    const files = await this.fileStore.listInputFiles(contextId, userId)
     const candidates = files.filter(
       (f) => (!reGlob || reGlob.test(f.name)) && isTextMime(f.mimeType),
     )
     const fetched = await Promise.all(
-      candidates.map((f) => this.fileStore.getInputFile(this.contextId, f.name, this.userId)),
+      candidates.map((f) => this.fileStore.getInputFile(contextId, f.name, userId)),
     )
     const matches = []
     for (let i = 0; i < candidates.length; i++) {
@@ -121,14 +136,16 @@ export class UploadsBackend {
   }
 
   async exists(filePath) {
+    const { contextId, userId } = this._resolveContext()
     const name = this._name(filePath)
-    const file = await this.fileStore.getInputFile(this.contextId, name, this.userId)
+    const file = await this.fileStore.getInputFile(contextId, name, userId)
     return !!file
   }
 
   async stat(filePath) {
+    const { contextId, userId } = this._resolveContext()
     const name = this._name(filePath)
-    const file = await this.fileStore.getInputFile(this.contextId, name, this.userId)
+    const file = await this.fileStore.getInputFile(contextId, name, userId)
     if (!file) return null
     return { name: file.name, mimeType: file.mimeType, size: file.size }
   }

package/lib/agents/markdown/deep-agent.js

@@ -1,4 +1,5 @@
 import cds from "@sap/cds"
+import { ReadonlyBackend } from "./backends/readonly-backend.js"
 const { fs, path } = cds.utils
 
 const LOG = cds.log("agents")
@@ -22,7 +23,6 @@ export async function createAutoDeepAgent(srv, agentDir) {
     createDeepAgent,
     StateBackend,
     CompositeBackend,
-    FilesystemBackend,
     createMemoryMiddleware,
     createSkillsMiddleware,
   } = await import("deepagents")
@@ -33,37 +33,20 @@ export async function createAutoDeepAgent(srv, agentDir) {
     tools: tools.length,
   })
 
-  let backend
+  const additionalBackends = {}
+
   if (cds.env.agents?.fileIO?.enabled) {
     const { CdsFileStore } = await import("../../protocol/persistence/file-store.js")
     const { UploadsBackend } = await import("./backends/uploads-backend.js")
     const { OutputsBackend } = await import("./backends/outputs-backend.js")
     const fileStore = new CdsFileStore()
-    backend = (runtime) => {
-      const rawThreadId = runtime?.configurable?.thread_id || ""
-      const contextId = rawThreadId.includes(":")
-        ? rawThreadId.split(":").slice(1).join(":")
-        : rawThreadId
-      const taskId = runtime?.configurable?._taskId || ""
-      // GraphExecutor threads the request-entry user id as `_userId` so the
-      // backend keeps user isolation even if cds.context drifts inside the
-      // agent's tool callbacks. Falls back to cds.context for compatibility.
-      const userId = runtime?.configurable?._userId
-      return new CompositeBackend(
-        new StateBackend(),
-        {
-          "/uploads/": new UploadsBackend(contextId, fileStore, userId),
-          "/outputs/": new OutputsBackend(taskId, fileStore),
-        },
-        // Fallback to StateBackend for any other paths so deepagents'
-        // built-in tools that read state still work.
-      )
-    }
-  } else {
-    backend = new StateBackend()
+    Object.assign(additionalBackends, {
+      "/uploads/": new UploadsBackend(fileStore),
+      "/outputs/": new OutputsBackend(fileStore),
+    })
   }
 
-  const agentFsBackend = new FilesystemBackend({ rootDir: agentDir })
+  const agentFsBackend = new ReadonlyBackend({ rootDir: agentDir, virtualMode: true })
   const agentDirMiddleware = []
   if (fs.existsSync(path.join(agentDir, "AGENTS.md"))) {
     agentDirMiddleware.push(
@@ -74,14 +57,20 @@ export async function createAutoDeepAgent(srv, agentDir) {
     )
   }
   if (fs.existsSync(path.join(agentDir, "skills"))) {
+    additionalBackends["./skills/"] = additionalBackends["/skills/"] = new ReadonlyBackend({
+      rootDir: path.join(agentDir, "skills"),
+      virtualMode: true,
+    })
     agentDirMiddleware.push(
       createSkillsMiddleware({
         backend: agentFsBackend,
-        sources: ["./skills/"],
+        sources: ["./skills"],
       }),
     )
   }
 
+  const backend = new CompositeBackend(new StateBackend(), additionalBackends)
+
   return createDeepAgent({
     model,
     tools,

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

@@ -2,7 +2,7 @@ import cds from "@sap/cds"
 import { createMiddleware } from "langchain"
 import { AIMessage } from "@langchain/core/messages"
 import { OrchestrationClient } from "@sap-ai-sdk/langchain"
-import { timeout, retry } from "@sap-cloud-sdk/resilience"
+import { timeout, retry } from "../../utils/resilience.js"
 import { toSdkFilterFormat } from "../../../lib/models/aicore.js"
 import { audit } from "../../utils/utils.js"
 import { INSTRUMENTED } from "../../telemetry/tracing.js"
@@ -136,9 +136,10 @@ export async function contentFilterMiddleware(model) {
             }
           } else {
             // Fail closed: unrecognized errors (timeout, 5xx, network) block the message
-            LOG.warn("Content filter unavailable — blocking input", {
+            LOG.error("Content filter unavailable — blocking input", {
               error: err.message,
               status,
+              data,
             })
             if (hasHumanMessage) {
               return {

package/lib/agents/middleware/index.js

@@ -7,7 +7,17 @@ export default async function buildMiddleware(srv, options = {}) {
   const { statusUpdateMiddleware } = await import("./status-update.js")
   const { humanInTheLoopMiddleware } = await import("./hitl.js")
   const { toolSelectionMiddleware } = await import("./tool-selection.js")
+  const { toolWrapMiddleware } = await import("./tool-wrap.js")
+
+  const hasDynamicMcp = tools?.some((t) => t._mcpDynamic) ?? false
+  let dynamicMcpMiddlewares = []
+  if (hasDynamicMcp) {
+    const { remoteMcpMiddleware } = await import("./remote-mcp.js")
+    dynamicMcpMiddlewares = [remoteMcpMiddleware()]
+  }
+
   return [
+    ...dynamicMcpMiddlewares,
     ...(await quotaEnforcerMiddleware()),
     await contentFilterMiddleware(model),
     await agentActionsMiddleware(),
@@ -15,5 +25,6 @@ export default async function buildMiddleware(srv, options = {}) {
     await statusUpdateMiddleware(),
     ...(await humanInTheLoopMiddleware(srv, tools)),
     toolSelectionMiddleware(),
+    toolWrapMiddleware(),
   ].filter(Boolean)
 }

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

@@ -0,0 +1,62 @@
+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"
+
+const LOG = cds.log("agents:mcp")
+
+/**
+ * Middleware that resolves remote MCP tools per-request using the current user's auth headers.
+ * Tools are cached on cds.context.__mcpDynamicTools keyed by mcpUrl for the lifetime of the
+ * request so multi-turn ReAct loops don't issue a new tools/list call on every model invocation.
+ */
+export function remoteMcpMiddleware() {
+  return createMiddleware({
+    name: "RemoteMcpMiddleware",
+
+    wrapModelCall: async (request, handler) => {
+      const cache = (cds.context.__mcpDynamicTools ??= {})
+      const placeholders = (request.tools ?? []).filter((t) => t._mcpDynamic)
+      await Promise.all(
+        placeholders.map(async ({ mcpUrl, serviceName, resolveHeaders }) => {
+          if (cache[mcpUrl]) return
+          const headers = await resolveHeaders()
+          const client = new MultiServerMCPClient({
+            mcpServers: { default: { transport: "http", url: mcpUrl, headers } },
+          })
+          const raw = await client.getTools()
+          for (const t of raw) t.name = toolName(`${serviceName}_${t.name}`)
+          cache[mcpUrl] = raw
+          LOG.debug(
+            `Got ${raw.length} MCP tools from ${mcpUrl}: ${raw.map((t) => t.name).join(", ")}`,
+          )
+        }),
+      )
+      const resolved = placeholders.flatMap(({ mcpUrl }) => cache[mcpUrl] ?? [])
+      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 tool = allCached.find((t) => t.name === request.toolCall.name)
+      if (!tool) return handler(request)
+      try {
+        const output = await tool.invoke(request.toolCall.args)
+        return new ToolMessage({
+          name: request.toolCall.name,
+          content: typeof output === "string" ? output : JSON.stringify(output),
+          tool_call_id: request.toolCall.id,
+        })
+      } catch (err) {
+        LOG.warn(`MCP tool "${request.toolCall.name}" error: ${err.message}`)
+        return new ToolMessage({
+          name: request.toolCall.name,
+          content: `Error: ${err.message}`,
+          tool_call_id: request.toolCall.id,
+        })
+      }
+    },
+  })
+}

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

@@ -0,0 +1,52 @@
+import { createMiddleware } from "langchain"
+import { ToolMessage } from "@langchain/core/messages"
+import { isGraphInterrupt } from "@langchain/langgraph"
+import cds from "@sap/cds"
+
+const LOG = cds.log("agents")
+
+/**
+ * Converts tool errors into error ToolMessages so the LLM can retry.
+ * Handles two paths: thrown errors (err.details appended when present)
+ * and tools returning artifact.isError=true (@cap-js/mcp action pattern).
+ */
+export function toolWrapMiddleware() {
+  return createMiddleware({
+    name: "ToolWrapMiddleware",
+    wrapToolCall: async (request, handler) => {
+      const { name, id, args } = request.toolCall
+      try {
+        LOG.debug("[tool]", name, args)
+        const result = await handler(request)
+        if (ToolMessage.isInstance(result) && result.artifact?.isError === true) {
+          result.status = "error"
+        }
+        if (
+          ToolMessage.isInstance(result) &&
+          result.status !== "error" &&
+          typeof result.content === "string" &&
+          result.content.startsWith("Error:")
+        ) {
+          result.status = "error"
+        }
+        if (result?.status === "error") LOG.debug("[tool] error", name, result.content)
+        else LOG.debug("[tool] completed", name)
+        return result
+      } catch (err) {
+        if (isGraphInterrupt(err)) throw err
+        LOG.debug("[tool] error", name, err)
+        let content = `Error: ${err.message}`
+        if (Array.isArray(err.details) && err.details.length > 0) {
+          const lines = err.details.map((d) => `- ${d.message}`).join("\n")
+          content += `\n${lines}`
+        }
+        return new ToolMessage({
+          content,
+          tool_call_id: id ?? "",
+          name,
+          status: "error",
+        })
+      }
+    },
+  })
+}

package/lib/compile.js

@@ -1,7 +1,11 @@
 import cds from "@sap/cds"
-import { getDescription, getFilteredEntities, getFilteredActions } from "./utils/utils.js"
+import {
+  getDescription,
+  getFilteredEntities,
+  getFilteredActions,
+  slugified,
+} from "./utils/utils.js"
 import { buildAgentCard } from "./protocol/agent-card.js"
-import { slugified } from "./utils/markdown.js"
 
 const A2A_BASE_PATH = "/a2a"