@cap-js/agents 0.0.0 → 0.9.1

package/srv/handlers/tools.js

@@ -0,0 +1,366 @@
+import cds from "@sap/cds"
+import { DynamicStructuredTool, tool } from "@langchain/core/tools"
+import z from "zod"
+import {
+  createGenericReadToolDefinition,
+  createDescribeToolDefinition,
+  createCallActionToolDefinition,
+  createPerActionToolDefinition,
+  executeGenericReadTool,
+  executeDescribe,
+  executeCallActionTool,
+  executePerActionTool,
+} from "@cap-js/mcp/lib/tools.js"
+import { getFilteredEntities, getFilteredActions } from "../../lib/utils/utils.js"
+import { isTextMime } from "../../lib/agents/markdown/backends/mime-utils.js"
+import { checkAuthorization } from "@cap-js/mcp/lib/auth.js"
+
+const LOG = cds.log("agents")
+
+const unwrap = (result) => {
+  const text = result.content?.[0]?.text ?? ""
+  return [text, { isError: result.isError === true }]
+}
+
+// we need the checkAuthorization result many times in the same cds context
+function cachedAuth(srv) {
+  if (!cds.context) return checkAuthorization(srv)
+  const cache = (cds.context.__agentAuth ??= {})
+  return (cache[srv.name] ??= checkAuthorization(srv))
+}
+
+class GenericReadTool extends DynamicStructuredTool {
+  constructor(srv, entities) {
+    const def = createGenericReadToolDefinition(Object.keys(entities), srv.name, "")
+    super({
+      name: def.name,
+      description: def.description,
+      schema: def.inputSchema,
+      responseFormat: "content_and_artifact",
+      func: async (args) => {
+        return unwrap(await executeGenericReadTool(srv, entities, args, { log: LOG }))
+      },
+    })
+    this.srv = srv
+    this._allEntities = entities
+    delete this.description
+    delete this.schema
+  }
+
+  get description() {
+    const { entities, error } = cachedAuth(this.srv)
+    if (error) return "Not available due to " + error?.reason
+    return createGenericReadToolDefinition(Object.keys(entities), this.srv.name, "").description
+  }
+
+  get schema() {
+    const { entities, error } = cachedAuth(this.srv)
+    if (error) return z.undefined
+    return createGenericReadToolDefinition(Object.keys(entities), this.srv.name, "").inputSchema
+  }
+
+  isAllowed() {
+    const { entities, error } = cachedAuth(this.srv)
+    return !error && Object.keys(entities).length > 0
+  }
+}
+
+class DescribeTool extends DynamicStructuredTool {
+  constructor(srv, entities, actions) {
+    const def = createDescribeToolDefinition(
+      Object.keys(entities),
+      Object.keys(actions),
+      srv.name,
+      "",
+    )
+    super({
+      name: def.name,
+      description: def.description,
+      schema: def.inputSchema,
+      responseFormat: "content_and_artifact",
+      func: async (args) => {
+        return unwrap(await executeDescribe(srv, entities, actions, args, { log: LOG }))
+      },
+    })
+    this.srv = srv
+    this._allEntities = entities
+    this._allActions = actions
+    delete this.description
+    delete this.schema
+  }
+
+  get description() {
+    const { entities, actions, error } = cachedAuth(this.srv)
+    if (error) return "Not available due to " + error?.reason
+    return createDescribeToolDefinition(
+      Object.keys(entities),
+      Object.keys(actions),
+      this.srv.name,
+      "",
+    ).description
+  }
+
+  get schema() {
+    const { entities, actions, error } = cachedAuth(this.srv)
+    if (error) return z.undefined
+    return createDescribeToolDefinition(
+      Object.keys(entities),
+      Object.keys(actions),
+      this.srv.name,
+      "",
+    ).inputSchema
+  }
+
+  isAllowed() {
+    const { entities, actions, error } = cachedAuth(this.srv)
+    return !error && (Object.keys(entities).length > 0 || Object.keys(actions).length > 0)
+  }
+}
+
+class PerActionTool extends DynamicStructuredTool {
+  constructor(srv, actionName, action) {
+    const def = createPerActionToolDefinition(actionName, action, srv.name, srv.model, "")
+    super({
+      name: def.name,
+      description: def.description,
+      schema: def.inputSchema,
+      responseFormat: "content_and_artifact",
+      func: async (args) => {
+        return unwrap(await executePerActionTool(srv, actionName, action, args, { log: LOG }))
+      },
+    })
+    this.srv = srv
+    this.actionName = actionName
+    this.action = action
+  }
+
+  isAllowed() {
+    const { actions, error } = cachedAuth(this.srv)
+    return !error && Object.prototype.hasOwnProperty.call(actions, this.actionName)
+  }
+}
+
+class CallActionTool extends DynamicStructuredTool {
+  constructor(srv, actions) {
+    const def = createCallActionToolDefinition(Object.keys(actions), srv.name, "")
+    super({
+      name: def.name,
+      description: def.description,
+      schema: def.inputSchema,
+      responseFormat: "content_and_artifact",
+      func: async (args) => {
+        return unwrap(await executeCallActionTool(srv, actions, args, { log: LOG }))
+      },
+    })
+    this.srv = srv
+    this._allActions = actions
+    delete this.description
+    delete this.schema
+  }
+
+  get description() {
+    const { actions, error } = cachedAuth(this.srv)
+    if (error) return "Not available due to " + error?.reason
+    return createCallActionToolDefinition(Object.keys(actions), this.srv.name, "").description
+  }
+
+  get schema() {
+    const { actions, error } = cachedAuth(this.srv)
+    if (error) return z.undefined
+    return createCallActionToolDefinition(Object.keys(actions), this.srv.name, "").inputSchema
+  }
+
+  isAllowed() {
+    const { actions, error } = cachedAuth(this.srv)
+    return !error && Object.keys(actions).length > 0
+  }
+}
+
+/**
+ * Reuses tool definitions and execution logic from @cap-js/mcp.
+ *
+ * @param {object} srv - CDS ApplicationService
+ */
+export function generateTools(srv) {
+  const entities = getFilteredEntities(srv)
+  const actions = getFilteredActions(srv)
+
+  const tools = []
+
+  // Query tool — one tool for reading all entities
+  const entityNames = Object.keys(entities)
+  if (entityNames.length > 0) {
+    tools.push(new GenericReadTool(srv, entities))
+  }
+
+  // Describe tool — introspect service model
+  const actionNames = Object.keys(actions)
+  if (entityNames.length > 0 || actionNames.length > 0) {
+    tools.push(new DescribeTool(srv, entities, actions))
+  }
+
+  // Action/function tools — per-action (default) or combined call action
+  const usePerActionTools = cds.env.agents?.per_action_tool !== false
+  if (actionNames.length > 0) {
+    if (usePerActionTools) {
+      for (const [name, action] of Object.entries(actions)) {
+        tools.push(new PerActionTool(srv, name, action))
+      }
+    } else {
+      tools.push(new CallActionTool(srv, actions))
+    }
+  }
+
+  // File tools — only when fileIO is enabled
+  // emit_file_part: stateless protocol emitter; safe to tools.push once at startup.
+  // read_file: per-request (needs contextId) — created on-demand via createReadFileTool().
+  if (cds.env.agents?.fileIO?.enabled) {
+    tools.push(createEmitFilePartTool())
+  }
+
+  return tools
+}
+
+// ── File tools ────────────────────────────────────────────────────────
+
+/**
+ * Render a byte count as a human-readable string ("123 B" / "12.3 KB" / "1.2 MB").
+ * Exported so callers (e.g. GraphExecutor's file manifest) format sizes identically.
+ */
+export function formatFileSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/**
+ * Sanitize a user-supplied filename so it is safe to use as a stable key,
+ * a /uploads/<name> path component, and an artifactId fragment.
+ *
+ * - Strips any directory components (path.basename) — defeats `../../etc/passwd`
+ *   tricks that would otherwise produce confusing artifactIds and DB keys.
+ * - Replaces characters that are not letters, digits, dot, dash, underscore, or
+ *   space with `_`. Leaves Unicode letters (CJK/etc.) intact.
+ * - Collapses leading dots so the name cannot start with `.` (avoids hidden-file
+ *   surprises and `..` artifacts).
+ * - Falls back to "unnamed" for empty input.
+ */
+export function sanitizeFilename(raw) {
+  const name = String(raw ?? "").trim()
+  if (!name) return "unnamed"
+  // path.basename equivalent without pulling in node:path: drop everything up to
+  // the last forward- or back-slash. Also drop any pure ".."/"." segments.
+  const base = name.replace(/^.*[\\/]/, "")
+  const cleaned = base.replace(/[^\p{L}\p{N}._\-\s]/gu, "_").replace(/^\.+/, "")
+  return cleaned || "unnamed"
+}
+
+/**
+ * Create a tool that emits a file as part of the A2A response.
+ * Pure protocol emitter — caller provides the bytes, no generation, no placeholders.
+ * The executor's toolResults collection loop parses `kind:'file'` JSON from this tool.
+ */
+export function createEmitFilePartTool() {
+  return tool(
+    async ({ filename, mimeType, content, encoding = "utf-8" }) => {
+      const bytes =
+        encoding === "base64" ? content : Buffer.from(content, "utf-8").toString("base64")
+      const decodedSize =
+        encoding === "base64"
+          ? Buffer.byteLength(content, "base64")
+          : Buffer.byteLength(content, "utf-8")
+      LOG.info("emit_file_part", { filename, mimeType, encoding, bytes: decodedSize })
+      return JSON.stringify({ kind: "file", file: { name: filename, mimeType, bytes } })
+    },
+    {
+      name: "emit_file_part",
+      description:
+        'Emit a file as part of the A2A response. For text formats (CSV, JSON, plain text) provide raw text content. For binary formats provide base64-encoded content and set encoding to "base64". You are responsible for obtaining or generating the file content before calling this tool.',
+      schema: z.object({
+        filename: z.string().describe("Filename with extension, e.g. report.csv"),
+        mimeType: z.string().describe("MIME type, e.g. text/csv, application/json, image/png"),
+        content: z
+          .string()
+          .describe("File content: raw text for text formats, base64 string for binary formats"),
+        encoding: z.enum(["utf-8", "base64"]).optional().default("utf-8"),
+      }),
+    },
+  )
+}
+
+/**
+ * Create a read_file tool scoped to the current conversation.
+ * For the default LangGraph path only — deepagents tools.pushs its own read_file
+ * tool via FilesystemMiddleware, which routes through UploadsBackend.
+ *
+ * When contextId is omitted, the tool resolves it from cds.context at invocation
+ * time (set by GraphExecutor before graph.invoke). This allows a single tool
+ * instance to be reused across requests in createAgent-based graphs.
+ *
+ * @param {import('../../lib/protocol/persistence/file-store.js').CdsFileStore} fileStore
+ * @param {string} [contextId] - If omitted, read from cds.context["agent.context.id"]
+ * @param {string} [userId] - If omitted, read from cds.context.user.id
+ */
+export function createReadFileTool(fileStore, contextId, userId) {
+  return tool(
+    async ({ path: filePath }) => {
+      try {
+        const resolvedContextId = contextId || cds.context?.["agent.context.id"]
+        const resolvedUserId = userId || cds.context?.user?.id
+        const name = filePath.replace(/^\/uploads\//, "")
+        if (!fileStore) {
+          return `read_file is not available in this context (no file store configured).`
+        }
+        const file = await fileStore.getInputFile(resolvedContextId, name, resolvedUserId)
+        if (!file) {
+          const available =
+            (await fileStore.listInputFiles(resolvedContextId, resolvedUserId))
+              .map((f) => `/uploads/${f.name}`)
+              .join(", ") || "none"
+          LOG.info("read_file (not found)", {
+            contextId: resolvedContextId,
+            path: filePath,
+            available,
+          })
+          return `File not found: ${filePath}. Available files: ${available}`
+        }
+        if (file.mimeType?.startsWith("image/")) {
+          LOG.info("read_file (image, not returned as text)", {
+            contextId: resolvedContextId,
+            path: filePath,
+            mimeType: file.mimeType,
+            size: file.size,
+          })
+          return `"${name}" is an image (${formatFileSize(file.size)}). Use an image analysis tool to process it.`
+        }
+        if (!isTextMime(file.mimeType)) {
+          LOG.info("read_file (binary, not returned as text)", {
+            contextId: resolvedContextId,
+            path: filePath,
+            mimeType: file.mimeType,
+            size: file.size,
+          })
+          return `"${name}" is a binary file (${file.mimeType}, ${formatFileSize(file.size)}). Cannot be read as text.`
+        }
+        LOG.info("read_file", {
+          contextId: resolvedContextId,
+          path: filePath,
+          mimeType: file.mimeType,
+          size: file.size,
+        })
+        return file.bytes.toString("utf-8")
+      } catch (err) {
+        LOG.error("read_file failed", { filePath, error: err.message })
+        return `Error reading file: ${err.message}`
+      }
+    },
+    {
+      name: "read_file",
+      description:
+        "Read the contents of an uploaded file. Use the /uploads/<filename> path from the file manifest. Returns file content for text-based formats.",
+      schema: z.object({
+        path: z.string().describe("File path, e.g. /uploads/report.csv"),
+      }),
+    },
+  )
+}

package/srv/langgraph-executor-srv.js

@@ -0,0 +1,70 @@
+import cds from "@sap/cds"
+import { GraphExecutor } from "./handlers/graph-executor.js"
+import { GraphCache, hashFeatures } from "./graph-cache.js"
+
+/**
+ * LangGraph-based executor service for @agent annotated services.
+ *
+ * Dispatches `buildGraph` event on the target ApplicationService.
+ * Graphs cached per feature vector (cds.context.features) in a FIFO cache.
+ * Lazy init: graph built on first request (features not available at startup).
+ */
+export class LangGraphExecutor {
+  static _instance
+  _caches = new Map()
+
+  static for(srv) {
+    this._instance ??= new LangGraphExecutor()
+    return this._instance.for(srv)
+  }
+
+  for(srv) {
+    return {
+      execute: (requestContext, eventBus) => this._execute(srv, requestContext, eventBus),
+      cancelTask: async (taskId, eventBus) => {
+        const executor = await this._ensureExecutor(srv)
+        return executor.cancelTask(taskId, eventBus)
+      },
+      abort: async (taskId) => {
+        const executor = await this._ensureExecutor(srv)
+        return executor.abort(taskId)
+      },
+    }
+  }
+
+  _getCache(srv) {
+    if (!this._caches.has(srv.name)) {
+      this._caches.set(srv.name, new GraphCache())
+    }
+    return this._caches.get(srv.name)
+  }
+
+  async _ensureExecutor(srv) {
+    const features = cds.context?.features || {}
+    const key = hashFeatures(features)
+    const cache = this._getCache(srv)
+
+    return cache.getOrBuild(key, () => this._buildExecutor(srv))
+  }
+
+  async _buildExecutor(srv) {
+    const result = await srv.send("buildGraph", {})
+
+    if (result && typeof result.invoke === "function") {
+      return new GraphExecutor(result, srv)
+    }
+    if (result && typeof result.execute === "function") {
+      return result
+    }
+
+    throw new Error(
+      `buildGraph handler for service "${srv.name}" must return a compiled LangGraph (with invoke()) ` +
+        `or a GraphExecutor (with execute()). Got: ${typeof result}`,
+    )
+  }
+
+  async _execute(srv, requestContext, eventBus) {
+    const executor = await this._ensureExecutor(srv)
+    return executor.execute(requestContext, eventBus)
+  }
+}

package/srv/push-notification-srv.js

@@ -0,0 +1,149 @@
+import cds from "@sap/cds"
+import { isAllowedDomain } from "../lib/utils/utils.js"
+
+const LOG = cds.log("agents")
+
+// Hop limit for callback redirects. Real webhooks rarely need more than a
+// single hop (protocol upgrade or CDN edge routing); 3 leaves headroom
+// without opening a redirect loop as an amplifier.
+const MAX_REDIRECTS = 3
+
+/**
+ * CDS service that handles push notification delivery.
+ * Registered as `agent-push-notifications` and wrapped in CAP outbox
+ * by CdsPushNotificationSender for at-least-once delivery with retry.
+ */
+export default class AgentPushNotificationService extends cds.Service {
+  async init() {
+    this.on("pushNotification", async (msg) => {
+      const { task, url } = msg.data
+      await pushNotification(url, task)
+    })
+    return super.init()
+  }
+}
+
+async function pushNotification(url, task) {
+  const headers = { "Content-Type": "application/json" }
+
+  const iasResource = cds.env.agents?.pushNotifications?.ias?.resource
+  if (iasResource) {
+    const bearerToken = await fetchIasToken(iasResource)
+    if (bearerToken) {
+      headers["Authorization"] = `Bearer ${bearerToken}`
+    }
+  }
+
+  const allowedDomains = cds.env.agents?.pushNotifications?.allowedDomains
+  const res = await fetchWithRedirects(
+    url,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify(task),
+      signal: AbortSignal.timeout(10_000),
+    },
+    allowedDomains,
+  )
+
+  if (!res.ok) {
+    // Throw so outbox retries on transient failures (5xx, network)
+    const body = await res.text().catch(() => "")
+    const msg = `Push notification failed: HTTP ${res.status} ${res.statusText}`
+    if (res.status >= 500 || res.status === 429) {
+      throw cds.error({ message: msg, response: body }) // retryable
+    }
+    // 4xx = permanent failure, log and don't retry
+    LOG.error(msg, { taskId: task.id, url, response: body })
+  } else {
+    LOG.debug("Push notification delivered", { taskId: task.id, url, status: res.status })
+  }
+}
+
+/**
+ * POST to `url` with manual redirect handling. Every hop (including the
+ * initial URL) is re-validated against `allowedDomains` so a compromised or
+ * open-redirect endpoint on an allow-listed domain cannot exfiltrate the
+ * request body + Authorization header to an off-allowlist host.
+ *
+ * Policy:
+ *  - Non-3xx responses are returned as-is.
+ *  - 307 / 308 preserve method + body and follow if the new URL is allowlisted.
+ *  - 301 / 302 / 303 would change POST semantics (spec allows GET downgrade)
+ *    so they are refused - legitimate push webhooks never rely on that.
+ *  - The redirect chain is capped at MAX_REDIRECTS. Absolute and relative
+ *    Location values are both resolved against the previous URL.
+ */
+async function fetchWithRedirects(url, options, allowedDomains, maxRedirects = MAX_REDIRECTS) {
+  let currentUrl = url
+  for (let hop = 0; hop <= maxRedirects; hop++) {
+    if (!isAllowedDomain(currentUrl, allowedDomains)) {
+      throw new Error(
+        `Push callback URL not on allowlist: ${currentUrl}` +
+          (hop > 0 ? ` (reached via ${hop} redirect${hop === 1 ? "" : "s"})` : ""),
+      )
+    }
+
+    // Never let fetch follow silently - we validate each hop explicitly.
+    // Sequential await is required
+    // eslint-disable-next-line no-await-in-loop
+    const res = await fetch(currentUrl, { ...options, redirect: "manual" })
+
+    if (res.status < 300 || res.status >= 400) {
+      return res
+    }
+
+    // 3xx: only 307 / 308 preserve method + body. 301 / 302 / 303 semantically
+    // downgrade POST to GET - a push callback that relies on that is misconfigured.
+    if (res.status !== 307 && res.status !== 308) {
+      throw new Error(
+        `Push callback redirect ${res.status} would change method or drop body; refusing`,
+      )
+    }
+
+    if (hop === maxRedirects) {
+      throw new Error(`Push callback exceeded ${maxRedirects} redirects`)
+    }
+
+    const location = res.headers.get("location")
+    if (!location) {
+      // 3xx without Location - nothing to follow, return as-is
+      return res
+    }
+
+    // Resolve relative Locations against the previous URL.
+    currentUrl = new URL(location, currentUrl).toString()
+  }
+}
+
+async function fetchIasToken(resource) {
+  let getIasToken
+  try {
+    ;({ getIasToken } = await import("@sap-cloud-sdk/connectivity"))
+  } catch {
+    LOG.debug("@sap-cloud-sdk/connectivity not available, skipping IAS token")
+    return null
+  }
+
+  const tenant = cds.context?.tenant
+  const options = {
+    resource: { name: resource },
+    ...(tenant && { appTid: tenant }),
+  }
+
+  try {
+    const result = await getIasToken(options)
+    return result?.access_token || result?.token || result
+  } catch (err) {
+    // No identity binding → expected in dev/test
+    if (
+      err.message?.includes("identity") ||
+      err.message?.includes("service binding") ||
+      err.message?.includes("not found")
+    ) {
+      LOG.debug("No identity service binding, push without auth", { resource })
+      return null
+    }
+    throw err
+  }
+}