@cap-js/agents 0.0.0 → 0.9.1

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

@@ -0,0 +1,152 @@
+/**
+ * OutputsBackend — deepagents BackendProtocolV2 implementation for /outputs/ route.
+ *
+ * Creative reuse of deepagents' existing write_file tool: instead of adding
+ * an emit_file_part tool to the deep agent's tool set, the executor routes
+ * /outputs/ writes (which the agent makes via the standard write_file tool)
+ * to cap.agent.Tasks.outputFiles in CDS. After invocation, the executor reads all output
+ * files for the task from cap.agent.Tasks.outputFiles and emits them as A2A FileParts.
+ *
+ */
+
+import { isTextMime, globToRegex } from "./mime-utils.js"
+
+function inferMimeType(name) {
+  const ext = name?.split(".").pop()?.toLowerCase()
+  const map = {
+    csv: "text/csv",
+    txt: "text/plain",
+    md: "text/markdown",
+    html: "text/html",
+    htm: "text/html",
+    json: "application/json",
+    xml: "application/xml",
+    yaml: "application/yaml",
+    yml: "application/yaml",
+    pdf: "application/pdf",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    svg: "image/svg+xml",
+    js: "application/javascript",
+    ts: "text/typescript",
+    py: "text/x-python",
+    sql: "application/sql",
+  }
+  return map[ext] || "application/octet-stream"
+}
+
+export class OutputsBackend {
+  constructor(taskId, fileStore) {
+    this.taskId = taskId
+    this.fileStore = fileStore
+  }
+
+  // CompositeBackend strips the route prefix (/outputs/) before delegating,
+  // so paths arrive here as either "/name" (stripped) or "/outputs/name" (direct).
+  // _name() handles both forms.
+  _name(filePath) {
+    return filePath.replace(/^\/outputs\//, "").replace(/^\//, "")
+  }
+
+  async write(filePath, content, options = {}) {
+    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)
+    return { success: true }
+  }
+
+  async exists(filePath) {
+    const name = this._name(filePath)
+    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 file = files.find((f) => f.name === name)
+    if (!file) return null
+    return { name: file.name, mimeType: file.mimeType, size: file.size }
+  }
+
+  // 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)
+    return files.map((f) => `/${f.name}`)
+  }
+
+  async ls(_path) {
+    const files = await this.fileStore.listOutputFilesMeta(this.taskId)
+    return {
+      files: files.map((f) => ({
+        path: `/${f.name}`,
+        is_dir: false,
+        size: f.size,
+        modified_at: "",
+      })),
+    }
+  }
+
+  async glob(pattern, _path) {
+    const re = globToRegex(pattern)
+    const files = await this.fileStore.listOutputFilesMeta(this.taskId)
+    return {
+      files: files
+        .filter((f) => re.test(f.name))
+        .map((f) => ({ path: `/${f.name}`, is_dir: false, size: f.size, modified_at: "" })),
+    }
+  }
+
+  async grep(pattern, _path, glob) {
+    const reGlob = glob ? globToRegex(glob) : null
+    const files = await this.fileStore.listOutputFiles(this.taskId)
+    const matches = []
+    for (const f of files) {
+      if (reGlob && !reGlob.test(f.name)) continue
+      if (!isTextMime(f.mimeType)) continue
+      const lines = (f.bytes ? Buffer.from(f.bytes).toString("utf-8") : "").split("\n")
+      for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(pattern)) {
+          matches.push({ path: `/${f.name}`, line: i + 1, text: lines[i] })
+        }
+      }
+    }
+    return { matches }
+  }
+
+  async read(filePath, offset = 0, limit = 100) {
+    const name = this._name(filePath)
+    const file = await this.fileStore.getOutputFile(this.taskId, name)
+    if (!file) {
+      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}` }
+    }
+    if (!isTextMime(file.mimeType)) {
+      return { error: `"${name}" is a binary file (${file.mimeType}) — cannot be read as text.` }
+    }
+    const text = file.bytes ? Buffer.from(file.bytes).toString("utf-8") : ""
+    const lines = text.split("\n")
+    return {
+      content: lines.slice(offset, offset + limit).join("\n"),
+      mimeType: file.mimeType,
+    }
+  }
+
+  // Defensive stub for deepagents' BackendProtocolV2 — see UploadsBackend.readRaw
+  // 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)
+    if (!file) return { error: `File not found: ${filePath}` }
+    return { bytes: file.bytes, mimeType: file.mimeType, size: file.size }
+  }
+
+  edit() {
+    return { error: "use write_file to overwrite an output file" }
+  }
+}

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

@@ -0,0 +1,143 @@
+/**
+ * UploadsBackend — deepagents BackendProtocolV2 implementation for /uploads/ route.
+ *
+ * Bridges deepagents' built-in read_file tool (which routes /uploads/* paths
+ * through whatever backend is registered at '/uploads/' in CompositeBackend)
+ * to cap.agent.Tasks.inputFiles via cds.ql. Without this backend, deepagents has no way
+ * to honour /uploads/ paths at all — FilesystemMiddleware wires read_file
+ * unconditionally to the backend.
+ *
+ */
+
+import { isTextMime, globToRegex } from "./mime-utils.js"
+
+export class UploadsBackend {
+  constructor(contextId, fileStore, userId) {
+    this.contextId = contextId
+    this.fileStore = fileStore
+    this.userId = userId
+  }
+
+  // CompositeBackend strips the route prefix (/uploads/) before delegating,
+  // so paths arrive here as either "/name" (stripped) or "/uploads/name" (direct).
+  // normalise() handles both forms.
+  _name(filePath) {
+    return filePath.replace(/^\/uploads\//, "").replace(/^\//, "")
+  }
+
+  async read(filePath, offset = 0, limit = 100) {
+    const name = this._name(filePath)
+    const file = await this.fileStore.getInputFile(this.contextId, name, this.userId)
+
+    if (!file) {
+      const available =
+        (await this.fileStore.listInputFiles(this.contextId, this.userId))
+          .map((f) => `/uploads/${f.name}`)
+          .join(", ") || "none"
+      return { error: `File not found: ${filePath}. Available: ${available}` }
+    }
+
+    if (file.mimeType?.startsWith("image/")) {
+      return { error: `"${name}" is an image. Use an image analysis tool.` }
+    }
+
+    if (!isTextMime(file.mimeType)) {
+      return { error: `"${name}" is a binary file (${file.mimeType}) — cannot be read as text.` }
+    }
+
+    const lines = (file.bytes ? file.bytes.toString("utf-8") : "").split("\n")
+    return {
+      content: lines.slice(offset, offset + limit).join("\n"),
+      mimeType: file.mimeType,
+    }
+  }
+
+  // Defensive stub for deepagents' BackendProtocolV2: callers that bypass the
+  // text-only `read()` path (binary handling, future deepagents versions) hit
+  // this method. Without it, `compositeBackend.readRaw('/uploads/<name>')`
+  // throws `TypeError: backend.readRaw is not a function`. Currently unused
+  // by our shipped code paths — do not delete as "dead".
+  async readRaw(filePath) {
+    const name = this._name(filePath)
+    const file = await this.fileStore.getInputFile(this.contextId, name, this.userId)
+    if (!file) return { error: `File not found: ${filePath}` }
+    return { bytes: file.bytes, mimeType: file.mimeType, size: file.size }
+  }
+
+  // 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)
+    return files.map((f) => `/${f.name}`)
+  }
+
+  async ls(_path) {
+    const files = await this.fileStore.listInputFiles(this.contextId, this.userId)
+    return {
+      files: files.map((f) => ({
+        path: `/${f.name}`,
+        is_dir: false,
+        size: f.size,
+        modified_at: "",
+      })),
+    }
+  }
+
+  async glob(pattern, _path) {
+    const re = globToRegex(pattern)
+    const files = await this.fileStore.listInputFiles(this.contextId, this.userId)
+    return {
+      files: files
+        .filter((f) => re.test(f.name))
+        .map((f) => ({ path: `/${f.name}`, is_dir: false, size: f.size, modified_at: "" })),
+    }
+  }
+
+  async grep(pattern, _path, glob) {
+    const reGlob = glob ? globToRegex(glob) : null
+    const files = await this.fileStore.listInputFiles(this.contextId, this.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)),
+    )
+    const matches = []
+    for (let i = 0; i < candidates.length; i++) {
+      const file = fetched[i]
+      if (!file) continue
+      const lines = (file.bytes ? file.bytes.toString("utf-8") : "").split("\n")
+      for (let j = 0; j < lines.length; j++) {
+        if (lines[j].includes(pattern)) {
+          matches.push({
+            path: `/${candidates[i].name}`,
+            line: j + 1,
+            text: lines[j],
+          })
+        }
+      }
+    }
+    return { matches }
+  }
+
+  async exists(filePath) {
+    const name = this._name(filePath)
+    const file = await this.fileStore.getInputFile(this.contextId, name, this.userId)
+    return !!file
+  }
+
+  async stat(filePath) {
+    const name = this._name(filePath)
+    const file = await this.fileStore.getInputFile(this.contextId, name, this.userId)
+    if (!file) return null
+    return { name: file.name, mimeType: file.mimeType, size: file.size }
+  }
+
+  write() {
+    return { error: "read-only" }
+  }
+
+  edit() {
+    return { error: "read-only — uploads cannot be edited" }
+  }
+}

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

@@ -0,0 +1,93 @@
+import cds from "@sap/cds"
+const { fs, path } = cds.utils
+
+const LOG = cds.log("agents")
+
+/**
+ * Auto-build a `deepagents` graph from the convention-resolved agent directory.
+ */
+export async function createAutoDeepAgent(srv, agentDir) {
+  if (!agentDir) {
+    throw new Error(
+      `createAutoDeepAgent: agentDir is required (service: ${srv?.name ?? "<unknown>"})`,
+    )
+  }
+
+  const tools = await srv.send("buildTools")
+  const model = await srv.send("buildModel", { deepAgent: true, tools })
+  const middleware = await srv.send("buildMiddleware", { model, tools })
+  const systemPrompt = await srv.send("buildSystemPrompt")
+
+  const {
+    createDeepAgent,
+    StateBackend,
+    CompositeBackend,
+    FilesystemBackend,
+    createMemoryMiddleware,
+    createSkillsMiddleware,
+  } = await import("deepagents")
+
+  LOG.debug("Auto-building deep agent", {
+    service: srv?.name,
+    agentDir,
+    tools: tools.length,
+  })
+
+  let backend
+  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()
+  }
+
+  const agentFsBackend = new FilesystemBackend({ rootDir: agentDir })
+  const agentDirMiddleware = []
+  if (fs.existsSync(path.join(agentDir, "AGENTS.md"))) {
+    agentDirMiddleware.push(
+      createMemoryMiddleware({
+        backend: agentFsBackend,
+        sources: ["./AGENTS.md"],
+      }),
+    )
+  }
+  if (fs.existsSync(path.join(agentDir, "skills"))) {
+    agentDirMiddleware.push(
+      createSkillsMiddleware({
+        backend: agentFsBackend,
+        sources: ["./skills/"],
+      }),
+    )
+  }
+
+  return createDeepAgent({
+    model,
+    tools,
+    systemPrompt,
+    backend,
+    middleware: [...agentDirMiddleware, ...middleware],
+    // checkpointer auto-injected by GraphExecutor (CdsCheckpointSaver)
+  })
+}

package/lib/agents/middleware/agent-actions.js

@@ -0,0 +1,18 @@
+import cds from "@sap/cds"
+import { createMiddleware } from "langchain"
+import * as metrics from "../../telemetry/metrics.js"
+
+/**
+ * Middleware that increments the `agent_actions` metric on every LLM invocation.
+ */
+export async function agentActionsMiddleware() {
+  return createMiddleware({
+    name: "agentActionsMiddleware",
+    afterModel: {
+      hook: () => {
+        metrics.agentActions.add(1, { "sap.tenantId": cds.context?.tenant || "anonymous" })
+        return {}
+      },
+    },
+  })
+}

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

@@ -0,0 +1,191 @@
+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 { toSdkFilterFormat } from "../../../lib/models/aicore.js"
+import { audit } from "../../utils/utils.js"
+import { INSTRUMENTED } from "../../telemetry/tracing.js"
+
+const LOG = cds.log("agents")
+
+/**
+ * Extract HTTP status and response data from a wrapped AI SDK error wrapped
+ * within langchain middleware wraps.
+ */
+function extractErrorDetails(err) {
+  let current = err
+  while (current) {
+    // Direct properties (e.g. MiddlewareError that has them)
+    if (current.rootCause?.status != null) {
+      return { status: current.rootCause.status, data: current.rootCause.response?.data }
+    }
+    // Check if current error itself is an axios-like response
+    if (current.status != null && current.response?.data) {
+      return { status: current.status, data: current.response.data }
+    }
+    current = current.cause
+  }
+  return { status: undefined, data: undefined }
+}
+
+/**
+ * Content filter middleware - workaround for aicore limitations on input filtering.
+ * Checks latest user input / tool result against input filters via a
+ * cheap model call (max_tokens:1) before the real model processes full context.
+ */
+export async function contentFilterMiddleware(model) {
+  const { contentFilter } = model?.options ?? {}
+  if (!contentFilter?.input) return
+
+  const inputFiltering = toSdkFilterFormat({ input: contentFilter.input })
+
+  const inputFilterModel = new OrchestrationClient(
+    {
+      promptTemplating: { model: { name: "gpt-4o-mini", params: { max_tokens: 1 } } },
+      filtering: inputFiltering,
+    },
+    {
+      disableStreaming: true,
+      customRequestConfig: {
+        middleware: [timeout(10_000), retry(2)],
+      },
+    },
+    model?.deploymentConfig,
+    model?.destination,
+  )
+  // Opt this internal probe out of generic LangChain tracing: it runs before the
+  // real model (BeforeModelNode) and would otherwise emit a "chat OrchestrationClient"
+  // span that shadows the real model's chat span in same-trace span lookups.
+  inputFilterModel[INSTRUMENTED] = true
+
+  return createMiddleware({
+    name: "ContentFilterMiddleware",
+    beforeModel: {
+      canJumpTo: ["end"],
+      hook: async (state) => {
+        const messages = state.messages || []
+
+        // Sanitize poisoned tool messages that triggered a prior content filter block.
+        // Detected by: tool message immediately followed by AI "malicious result" recovery.
+        for (let i = 0; i < messages.length - 1; i++) {
+          const type = messages[i]._getType?.() || messages[i].type
+          const nextType = messages[i + 1]?._getType?.() || messages[i + 1]?.type
+          if (type === "tool" && nextType === "ai") {
+            const nextContent = messages[i + 1]?.content || ""
+            if (/malicious result/i.test(nextContent) && messages[i].content) {
+              messages[i].content = ""
+            }
+          }
+        }
+
+        // Extract messages after the last AI message (new input for this model call)
+        const toFilter = []
+        let hasHumanMessage = false
+        for (let i = messages.length - 1; i >= 0; i--) {
+          const type = messages[i]._getType?.() || messages[i].type
+          if (type === "human") {
+            toFilter.unshift(messages[i])
+            hasHumanMessage = true
+          } else if (type === "tool") {
+            toFilter.unshift(messages[i])
+          } else {
+            // Stop at first AI/system message — anything before is already processed
+            break
+          }
+        }
+
+        if (toFilter.length === 0) return
+
+        // Convert tool messages to human messages for the filter model
+        // (OrchestrationClient requires human messages to trigger input filter)
+        const { HumanMessage } = await import("@langchain/core/messages")
+        const filterMessages = toFilter.map((m) => {
+          const type = m._getType?.() || m.type
+          if (type === "tool") {
+            const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content)
+            return new HumanMessage(content)
+          }
+          return m
+        })
+
+        try {
+          await inputFilterModel.invoke(filterMessages)
+        } catch (err) {
+          const { status, data } = extractErrorDetails(err)
+          const isFilterBlock =
+            /Filtering Module/i.test(data?.error?.location || "") && status === 400
+
+          if (isFilterBlock) {
+            LOG.warn("Content filter blocked input", { reason: data?.error?.message })
+            audit("ContentFilterBlocked", {
+              data: {
+                service: cds.context?.["agent.service"],
+                user: cds.context?.user?.id,
+                taskId: cds.context?.["agent.task.id"],
+                reason: data?.error?.message,
+                source: hasHumanMessage ? "user" : "tool",
+              },
+            })
+            // Only terminate for human messages; tool results continue (let model handle)
+            if (hasHumanMessage) {
+              return {
+                jumpTo: "end",
+                messages: [new AIMessage(cds.i18n.messages.at("CONTENT_FILTER_BLOCKED"))],
+              }
+            }
+          } else {
+            // Fail closed: unrecognized errors (timeout, 5xx, network) block the message
+            LOG.warn("Content filter unavailable — blocking input", {
+              error: err.message,
+              status,
+            })
+            if (hasHumanMessage) {
+              return {
+                jumpTo: "end",
+                messages: [new AIMessage(cds.i18n.messages.at("CONTENT_FILTER_UNAVAILABLE"))],
+              }
+            }
+          }
+        }
+      },
+    },
+    wrapModelCall: async (request, handler) => {
+      try {
+        return await handler(request)
+      } catch (err) {
+        const { status, data } = extractErrorDetails(err)
+        const isFilterBlock =
+          /Filtering Module/i.test(data?.error?.location || "") && status === 400
+
+        if (isFilterBlock) {
+          const lastMsg = request.state?.messages?.at(-1)
+          const isTool = lastMsg?._getType?.() === "tool" || lastMsg?.type === "tool"
+          const reason = data?.error?.message || "Content filter blocked"
+
+          LOG.warn("Content filter blocked model response", {
+            reason,
+            source: isTool ? "tool" : "model",
+          })
+          audit("ContentFilterBlocked", {
+            data: {
+              service: cds.context?.["agent.service"],
+              user: cds.context?.user?.id,
+              taskId: cds.context?.["agent.task.id"],
+              reason,
+              source: isTool ? "tool" : "model",
+            },
+          })
+
+          // Return graceful AI message so the agent can recover
+          const message = isTool
+            ? cds.i18n.messages.at("CONTENT_FILTER_TOOL_BLOCKED")
+            : reason.split("-").at(-1)?.trim() || cds.i18n.messages.at("CONTENT_FILTER_BLOCKED")
+
+          return new AIMessage(message)
+        }
+        throw err
+      }
+    },
+  })
+}

package/lib/agents/middleware/hitl-edit-note-injector.js

@@ -0,0 +1,18 @@
+import { createMiddleware } from "langchain"
+import { HumanMessage } from "@langchain/core/messages"
+import { z } from "zod"
+
+// Injects a HumanMessage for a pending _hitlEditNote before the next model turn.
+export function hitlEditNoteInjectorMiddleware() {
+  return createMiddleware({
+    name: "hitlEditNoteInjectorMiddleware",
+    stateSchema: z.object({ _hitlEditNote: z.string().optional() }),
+    beforeModel: async (state) => {
+      if (!state._hitlEditNote) return
+      return {
+        messages: [new HumanMessage(state._hitlEditNote)],
+        _hitlEditNote: undefined,
+      }
+    },
+  })
+}

package/lib/agents/middleware/hitl.js

@@ -0,0 +1,20 @@
+import { humanInTheLoopMiddleware as hitl } from "langchain"
+import { hitlEditNoteInjectorMiddleware } from "./hitl-edit-note-injector.js"
+
+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"] }
+    }
+    return interruptOn
+  }, {})
+}
+
+export async function humanInTheLoopMiddleware(srv, tools) {
+  const interruptOn = buildHitlInterruptMap(srv, tools)
+  if (!Object.keys(interruptOn).length) return []
+  return [hitl({ interruptOn }), hitlEditNoteInjectorMiddleware()]
+}

package/lib/agents/middleware/index.js

@@ -0,0 +1,19 @@
+export default async function buildMiddleware(srv, options = {}) {
+  const { tools, model } = options
+  const { quotaEnforcerMiddleware } = await import("./quota-enforcer.js")
+  const { contentFilterMiddleware } = await import("./content-filter.js")
+  const { agentActionsMiddleware } = await import("./agent-actions.js")
+  const { patchToolCallsMiddleware } = await import("./patch-tool-calls.js")
+  const { statusUpdateMiddleware } = await import("./status-update.js")
+  const { humanInTheLoopMiddleware } = await import("./hitl.js")
+  const { toolSelectionMiddleware } = await import("./tool-selection.js")
+  return [
+    ...(await quotaEnforcerMiddleware()),
+    await contentFilterMiddleware(model),
+    await agentActionsMiddleware(),
+    patchToolCallsMiddleware(),
+    await statusUpdateMiddleware(),
+    ...(await humanInTheLoopMiddleware(srv, tools)),
+    toolSelectionMiddleware(),
+  ].filter(Boolean)
+}