@cap-js/agents 0.0.0 → 0.9.1

package/lib/protocol/persistence/file-store.js

@@ -0,0 +1,209 @@
+import { Readable } from "node:stream"
+import cds from "@sap/cds"
+
+const LOG = cds.log("agents")
+
+/**
+ * Resolve the user id used to scope input-file reads.
+ */
+function resolveUserId(explicit) {
+  if (explicit) return explicit
+  return cds.context.user.id
+}
+
+/**
+ * Consume a Readable stream into a Buffer.
+ */
+async function toBuffer(value) {
+  if (Buffer.isBuffer(value)) return value
+  if (value && typeof value.pipe === "function") {
+    return new Promise((resolve, reject) => {
+      const chunks = []
+      value.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)))
+      value.on("end", () => resolve(Buffer.concat(chunks)))
+      value.on("error", reject)
+    })
+  }
+  if (value == null) return Buffer.alloc(0)
+  return Buffer.from(value)
+}
+
+function inputFilesEntity() {
+  return cds.model.definitions["cap.agent.Tasks.inputFiles"]
+}
+
+function outputFilesEntity() {
+  return cds.model.definitions["cap.agent.Tasks.outputFiles"]
+}
+
+/**
+ * CDS-backed store for A2A file I/O using @cap-js/attachments composition children.
+ */
+export class CdsFileStore {
+  async saveInputFile(taskId, name, mimeType, bytesBuffer) {
+    const InputFiles = inputFilesEntity()
+    LOG.debug("Files: save input", { taskId, name, bytes: bytesBuffer.length })
+    await INSERT.into(InputFiles).entries({
+      ID: cds.utils.uuid(),
+      up__taskId: taskId,
+      filename: name,
+      mimeType,
+      content: Readable.from([bytesBuffer]),
+    })
+  }
+
+  async getInputFile(contextId, name, userId) {
+    const InputFiles = inputFilesEntity()
+    const row = await SELECT.one
+      .from(InputFiles)
+      .columns("ID", "filename", "mimeType", "content")
+      .where({ "up_.contextId": contextId, "up_.createdBy": resolveUserId(userId), filename: name })
+      .orderBy([
+        { ref: ["up_", "createdAt"], sort: "desc" },
+        { ref: ["createdAt"], sort: "desc" },
+      ])
+
+    if (!row) {
+      LOG.debug("Files: get input miss", { contextId, name })
+      return null
+    }
+
+    const bytes = await toBuffer(row.content)
+    LOG.debug("Files: get input hit", { contextId, name, size: bytes.length })
+    return {
+      name: row.filename,
+      mimeType: row.mimeType,
+      bytes,
+      size: bytes.length,
+    }
+  }
+
+  async listInputFiles(contextId, userId) {
+    const InputFiles = inputFilesEntity()
+    const rows = await SELECT.from(InputFiles)
+      .columns(
+        "ID",
+        "filename",
+        "mimeType",
+        "createdAt",
+        { ref: ["up_", "createdAt"], as: "taskCreatedAt" },
+        { func: "length", args: [{ ref: ["content"] }], as: "size" },
+      )
+      .where({ "up_.contextId": contextId, "up_.createdBy": resolveUserId(userId) })
+      .orderBy([
+        { ref: ["up_", "createdAt"], sort: "desc" },
+        { ref: ["createdAt"], sort: "desc" },
+      ])
+
+    // JS dedupe by filename keeping latest (first in desc order)
+    const seen = new Map()
+    for (const row of rows) {
+      if (!seen.has(row.filename)) seen.set(row.filename, row)
+    }
+    return [...seen.values()].map((r) => ({
+      name: r.filename,
+      mimeType: r.mimeType,
+      size: r.size ?? 0,
+    }))
+  }
+
+  /**
+   * Delete all input files for a context.
+   */
+  async deleteInputFiles(contextId, opts = {}) {
+    const InputFiles = inputFilesEntity()
+    const where = { "up_.contextId": contextId }
+    if (!opts.allUsers) where["up_.createdBy"] = resolveUserId(opts.userId)
+    await DELETE.from(InputFiles).where(where)
+    LOG.debug("Files: deleted input files", { contextId, allUsers: !!opts.allUsers })
+  }
+
+  async saveOutputFile(taskId, name, mimeType, bytesBuffer) {
+    const OutputFiles = outputFilesEntity()
+    LOG.debug("Files: save output", { taskId, name, bytes: bytesBuffer.length })
+    const existing = await SELECT.one
+      .from(OutputFiles)
+      .columns("ID")
+      .where({ up__taskId: taskId, filename: name })
+    if (existing) {
+      await UPDATE(OutputFiles)
+        .set({ mimeType, content: Readable.from([bytesBuffer]) })
+        .where({ ID: existing.ID })
+    } else {
+      await INSERT.into(OutputFiles).entries({
+        ID: cds.utils.uuid(),
+        up__taskId: taskId,
+        filename: name,
+        mimeType,
+        content: Readable.from([bytesBuffer]),
+      })
+    }
+  }
+
+  async getOutputFile(taskId, name) {
+    const OutputFiles = outputFilesEntity()
+    const row = await SELECT.one
+      .from(OutputFiles)
+      .columns("ID", "filename", "mimeType", "content")
+      .where({ up__taskId: taskId, filename: name })
+      .orderBy([{ ref: ["createdAt"], sort: "desc" }])
+
+    if (!row) {
+      LOG.debug("Files: get output miss", { taskId, name })
+      return null
+    }
+
+    const bytes = await toBuffer(row.content)
+    return {
+      name: row.filename,
+      mimeType: row.mimeType,
+      bytes,
+      size: bytes.length,
+    }
+  }
+
+  async listOutputFiles(taskId) {
+    const OutputFiles = outputFilesEntity()
+    const rows = await SELECT.from(OutputFiles)
+      .columns("ID", "filename", "mimeType", "content")
+      .where({ up__taskId: taskId })
+
+    return Promise.all(
+      rows.map(async (row) => {
+        const bytes = await toBuffer(row.content)
+        return {
+          name: row.filename,
+          mimeType: row.mimeType,
+          bytes,
+          size: bytes.length,
+        }
+      }),
+    )
+  }
+
+  /**
+   * List output file metadata for a task without fetching content bytes.
+   */
+  async listOutputFilesMeta(taskId) {
+    const OutputFiles = outputFilesEntity()
+    const rows = await SELECT.from(OutputFiles)
+      .columns("ID", "filename", "mimeType", {
+        func: "length",
+        args: [{ ref: ["content"] }],
+        as: "size",
+      })
+      .where({ up__taskId: taskId })
+
+    return rows.map((r) => ({
+      name: r.filename,
+      mimeType: r.mimeType,
+      size: r.size ?? 0,
+    }))
+  }
+
+  async deleteOutputFiles(taskId) {
+    const OutputFiles = outputFilesEntity()
+    await DELETE.from(OutputFiles).where({ up__taskId: taskId })
+    LOG.debug("Files: deleted output files", { taskId })
+  }
+}

package/lib/protocol/persistence/push-notification-store.js

@@ -0,0 +1,59 @@
+import cds from "@sap/cds"
+import { isAllowedDomain } from "../../utils/utils.js"
+
+const LOG = cds.log("agents")
+
+const CONFIGS = "cap.agent.PushNotificationConfigs"
+
+/**
+ * CDS entity-backed store for A2A push notification configs.
+ *
+ * Implements the PushNotificationStore interface from @a2a-js/sdk/server:
+ *   save(taskId: string, config: PushNotificationConfig): Promise<void>
+ *   load(taskId: string): Promise<PushNotificationConfig[]>
+ *   delete(taskId: string, configId?: string): Promise<void>
+ *
+ * REVISIT: Currently only stores URL (no auth). When authenticated push callbacks needed:
+ * - Persist authentication.schemes in DB (non-secret metadata)
+ * - Store token/credentials in SAP Credential Store via @sap-cloud-sdk
+ * - Reconstruct full PushNotificationConfig on load()
+ * - See index.cds REVISIT comment for full plan
+ */
+export class CdsPushNotificationStore {
+  async save(taskId, config) {
+    const configId = config.id || taskId
+
+    // Validate callback URL against configured domain allowlist
+    const allowedDomains = cds.env.agents?.pushNotifications?.allowedDomains
+    if (!isAllowedDomain(config.url, allowedDomains)) {
+      const domains = Array.isArray(allowedDomains)
+        ? allowedDomains.join(", ")
+        : "(none configured)"
+      throw new Error(cds.i18n.messages.at("PUSH_URL_NOT_ALLOWED", [config.url, domains]))
+    }
+
+    const existing = await SELECT.one
+      .from(CONFIGS)
+      .where({ taskId, configId, createdBy: cds.context.user.id })
+    if (!existing) {
+      await INSERT.into(CONFIGS).entries({ taskId, configId, url: config.url })
+    } else {
+      await UPDATE.entity(CONFIGS)
+        .set({ url: config.url })
+        .where({ taskId, configId, createdBy: cds.context.user.id })
+    }
+    LOG.debug("Push notification config saved", { taskId, configId })
+  }
+
+  async load(taskId) {
+    const rows = await SELECT.from(CONFIGS).where({ taskId, createdBy: cds.context.user.id })
+    return rows.map((r) => ({ id: r.configId, url: r.url }))
+  }
+
+  async delete(taskId, configId) {
+    const where = { taskId, createdBy: cds.context.user.id }
+    if (configId) where.configId = configId
+    await DELETE.from(CONFIGS).where(where)
+    LOG.debug("Push notification config deleted", { taskId, configId: configId || "all" })
+  }
+}

package/lib/protocol/persistence/task-store.js

@@ -0,0 +1,47 @@
+import cds from "@sap/cds"
+
+const LOG = cds.log("agents")
+
+const TASKS = "cap.agent.Tasks"
+
+/**
+ * CDS entity-backed store for A2A tasks.
+ *
+ * Implements the TaskStore interface from @a2a-js/sdk/server:
+ *   save(task: Task): Promise<void>
+ *   load(taskId: string): Promise<Task | undefined>
+ */
+export class CdsTaskStore {
+  async save(task) {
+    if (cds.context["agent.new.task"]) {
+      await INSERT.into(TASKS).entries({
+        taskId: task.id,
+        contextId: task.contextId,
+        state: task.status?.state,
+        data: JSON.stringify(task),
+      })
+      delete cds.context["agent.new.task"]
+    } else {
+      await UPDATE.entity(TASKS)
+        .where({ taskId: task.id, createdBy: cds.context.user.id })
+        .set({
+          contextId: task.contextId,
+          state: task.status?.state,
+          data: JSON.stringify(task),
+        })
+    }
+
+    LOG._trace && LOG.debug("Task saved", { taskId: task.id, state: task.status?.state })
+  }
+
+  async load(taskId) {
+    const row = await SELECT.one.from(TASKS).where({ taskId, createdBy: cds.context.user.id })
+    if (!row) {
+      LOG._trace && LOG.debug("Task not found", { taskId })
+      return undefined
+    }
+
+    LOG._trace && LOG.debug("Task loaded", { taskId, state: row.state })
+    return JSON.parse(row.data)
+  }
+}

package/lib/protocol/push-notification-sender.js

@@ -0,0 +1,57 @@
+import cds from "@sap/cds"
+
+const LOG = cds.log("agents")
+
+/**
+ * CDS-based push notification sender with:
+ * - IAS App-to-App client_credentials token exchange (when identity binding present)
+ * - CAP outbox for reliable at-least-once delivery with retry
+ * - Fallback to plain HTTP POST (dev mode, no identity binding)
+ *
+ * Implements PushNotificationSender interface from @a2a-js/sdk/server:
+ *   send(task: Task): Promise<void>
+ *
+ * Token exchange uses @sap-cloud-sdk/connectivity getIasToken() which handles:
+ * - mTLS or client_secret auth (based on identity binding credentials)
+ * - Per-tenant tokens (appTid)
+ * - Built-in LRU token cache
+ */
+export class CdsPushNotificationSender {
+  constructor(pushNotificationStore) {
+    this._store = pushNotificationStore
+    this._outboxed = null
+  }
+
+  async send(task) {
+    if (!task?.id) return
+
+    const configs = await this._store.load(task.id)
+    if (!configs?.length) return
+
+    const outboxed = await this._getOutboxed()
+
+    // Emit one event per push config — independent retry per target
+    for (const config of configs) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await outboxed.emit("pushNotification", {
+          task,
+          url: config.url,
+        })
+      } catch (err) {
+        LOG.error("Failed to enqueue push notification", {
+          taskId: task.id,
+          url: config.url,
+          error: err.message,
+        })
+      }
+    }
+  }
+
+  async _getOutboxed() {
+    if (this._outboxed) return this._outboxed
+    const srv = await cds.connect.to("agent-push-notifications")
+    this._outboxed = cds.outboxed(srv)
+    return this._outboxed
+  }
+}

package/lib/sidecar.js

@@ -0,0 +1,162 @@
+import cds from "@sap/cds"
+import A2AProtocolAdapter, { authContext } from "./index.js"
+import { slugified } from "./utils/markdown.js"
+import registerDefaultAgentHandlers from "../srv/handlers/index.js"
+
+const LOG = cds.log("a2a")
+
+/**
+ * Create an A2A agent router for a CDS service (local or remote).
+ *
+ * This is the programmatic API for sidecar mode. While the protocol adapter
+ * factory is called automatically for local @agent services during cds.serve(),
+ * remote services obtained via cds.connect.to() need this explicit API.
+ *
+ * The returned Express router can be mounted on any Express app.
+ *
+ * @param {cds.Service} srv - A CDS service instance (local or remote)
+ * @param {object} [options] - Options passed to A2AProtocolAdapter
+ * @param {string} [options.path] - Override the default mount path
+ * @returns {express.Router|null} Express router or null if service is incompatible
+ *
+ * @example
+ *   const { createA2AAgent } = require('@cap-js/a2a/lib/sidecar')
+ *   const remoteSrv = await cds.connect.to('CatalogService')
+ *   const router = createA2AAgent(remoteSrv)
+ *   app.use('/a2a/catalog', router)
+ */
+function createA2AAgent(srv, options = {}) {
+  return A2AProtocolAdapter(srv, { ...options, isSidecar: true })
+}
+
+/**
+ * Bootstrap A2A sidecar mode.
+ *
+ * Auto-detects all @agent-annotated services from the loaded model,
+ * connects to them, and mounts A2A agent routers on the Express app.
+ *
+ * Activated via the "a2a-sidecar" CDS profile, which loads A2ASidecarBootstrap
+ * whose init() calls this function.
+ */
+async function bootstrapSidecar() {
+  const app = cds.app
+
+  if (!app) {
+    LOG.error("Cannot bootstrap agent sidecar: no Express app available")
+    return
+  }
+
+  const requires = cds.env.requires || {}
+  const isNode = cds.env.profiles?.includes("node")
+
+  const agentServices = Object.entries(cds.model?.definitions || {})
+    .filter(([, def]) => def.kind === "service" && def["@agent"])
+    .map(([cdsName]) => {
+      // Use slugified name for Node apps (/hcql/catalog), CDS name for Java apps (/hcql/CatalogService)
+      const name = isNode ? slugified(cdsName) : cdsName
+      return { name, cdsName, config: requires[name] || { kind: "hcql" } }
+    })
+
+  if (agentServices.length === 0) {
+    LOG.info("No remote @agent services found for A2A sidecar")
+    return
+  }
+
+  LOG.info(`Bootstrapping agent sidecar for ${isNode ? "node" : "java"} app`, {
+    services: agentServices.map((s) => s.cdsName),
+  })
+
+  // Connect to each remote service and mount A2A routers
+  await Promise.all(
+    agentServices.map(async ({ name, cdsName, config }) => {
+      try {
+        // Connect to the service
+        const srv = await cds.connect.to(name)
+
+        // When connected via slugified name (Node apps), restore the CDS name and model
+        // so tools and agent card generation work against the correct definition.
+        if (isNode) {
+          srv.name = cdsName
+          srv.model = cds.model
+          delete srv.definition
+          delete srv.entities
+          delete srv.actions
+          delete srv.operations
+        }
+
+        // Register default agent handlers (buildGraph, buildTools, buildModel, etc.)
+        // normally done by the cds "serving" hook, which only fires for ApplicationServices.
+        registerDefaultAgentHandlers(srv)
+
+        // Attach "before":
+        // Forward the incoming Authorization header to all outbound calls on this service.
+        // We use our own AsyncLocalStorage (authContext) because the A2A SDK fires the
+        // executor asynchronously, which severs the CDS http context (cds.context.http).
+        srv.before("*", (req) => {
+          const authHeader = authContext.getStore()?.authHeader
+          if (authHeader) req.headers = { ...req.headers, authorization: authHeader }
+        })
+
+        // Apply the HCQL actions patch only for Java main apps.
+        // Java's HCQL adapter requires the envelope format {"event":"<action>","args":[...]},
+        // but Node.js HCQL accepts the standard CDS remote format directly.
+        // Enable via cds.env.agent._javaHcqlCompat (set automatically by --profile java).
+        if ((!config.kind || config.kind === "hcql") && !isNode && cds.env.agent?._javaHcqlCompat) {
+          _patchHcqlActions(srv)
+        }
+
+        // Add service with its sluggified name
+        const path = config.a2aPath || `/a2a/${slugified(cdsName)}`
+        const router = createA2AAgent(srv, { path })
+
+        if (router) {
+          app.use(path, cds.middlewares.before, router)
+          LOG.info("Mounted agent", { service: cdsName, path })
+        } else {
+          LOG.warn("Could not create agent for service", { service: cdsName })
+        }
+      } catch (err) {
+        LOG.error("Failed to create agent for remote service", {
+          service: cdsName,
+          error: err.message,
+        })
+      }
+    }),
+  )
+}
+
+export { createA2AAgent, bootstrapSidecar }
+
+// _patchHcqlActions patches actions and functions to use the HCQL envelope format
+// {"event":"<action>","args":[{...}]} posted to the service root.
+// Necessary because @sap/cds/libx/_runtime/remote/Service.js (v9.9.1) sends:
+//   - actions as REST-style POST /<action> with data as body
+//   - functions as OData-style GET /<function>(param=@param)?@param=value
+// The Java HCQL adapter rejects both formats.
+// This patch may be removed once the Java HCQL accepts the format sent by Service.js.
+//
+// No recursion risk: srv.on(opName, ...) only fires for the action event (e.g. "submitOrder"),
+// while srv.send({ method: "POST", path: "/" }) dispatches as "POST /" — a different event key.
+function _patchHcqlActions(srv) {
+  const model = srv.model || cds.model
+  const actions = Object.entries(model.definitions)
+    .filter(
+      ([n, def]) =>
+        n.startsWith(srv.name + ".") && (def.kind === "action" || def.kind === "function"),
+    )
+    .map(([n]) => n.slice(srv.name.length + 1))
+
+  srv.prepend(() => {
+    for (const opName of actions) {
+      srv.on(opName, async (req) => {
+        const result = await srv.send({
+          method: "POST",
+          path: "/",
+          headers: req.headers,
+          data: { event: opName, args: [req.data] },
+        })
+        req.reply(result)
+      })
+    }
+  })
+}

package/lib/telemetry/active-users.js

@@ -0,0 +1,106 @@
+import cds from "@sap/cds"
+import * as metrics from "./metrics.js"
+import { ms4 } from "../utils/utils.js"
+
+const LOG = cds.log("agents")
+const TASKS = "cap.agent.Tasks"
+
+/** Cached active users data — updated by computeActiveUsers(), reported by gauge callback */
+let _activeUsersData = []
+
+/**
+ * Compute active users from Tasks table (last 24h rolling window).
+ * Groups by agentService, counts distinct createdBy.
+ *
+ * In multi-tenant deployments, iterates all subscribed tenants via
+ * cds.xt.DeploymentService and queries each tenant's HDI container separately.
+ * In single-tenant mode, queries the current DB directly.
+ */
+export async function computeActiveUsers() {
+  _activeUsersData = []
+
+  let tenants
+  try {
+    const ds = await cds.connect.to("cds.xt.DeploymentService")
+    tenants = await ds.getTenants()
+  } catch {
+    // Not multi-tenant (dev/SQLite) — run in current context
+    tenants = null
+  }
+
+  if (!tenants) {
+    await _computeForTenant(cds.context?.tenant || "anonymous")
+  } else {
+    for (const tenant of tenants) {
+      // eslint-disable-next-line no-await-in-loop
+      await cds.spawn({ tenant, user: cds.User.privileged }, () => _computeForTenant(tenant))
+    }
+  }
+
+  LOG.debug("active_users computed", {
+    tenants: tenants?.length || 1,
+    services: _activeUsersData.length,
+  })
+}
+
+async function _computeForTenant(tenant) {
+  const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString()
+  const results = await SELECT.from(TASKS)
+    .columns("agentService", "count(distinct createdBy) as userCount")
+    .where({ createdAt: { ">=": since } })
+    .groupBy("agentService")
+
+  for (const r of results) {
+    _activeUsersData.push({
+      agentService: r.agentService,
+      userCount: r.userCount,
+      tenant,
+    })
+  }
+}
+
+/** ObservableGauge callback — reports cached values on each OTel collection */
+export function observeActiveUsers(result) {
+  for (const { agentService, userCount, tenant } of _activeUsersData) {
+    result.observe(userCount, {
+      "sap.tenantId": tenant,
+      "agent.service": agentService,
+    })
+  }
+}
+
+/**
+ * Setup the active_users ObservableGauge + schedule periodic computation.
+ * When cds.env.agents.activeUsersInterval is 0, only the gauge is registered (no automatic scheduling).
+ * Apps can still trigger computation manually via executor.emit("computeActiveUsers").
+ */
+export function setupActiveUsersMetric() {
+  const interval = cds.env.agents?.activeUsersInterval
+
+  // Always register the gauge
+  metrics.createActiveUsersGauge(observeActiveUsers)
+
+  // Disabled scheduling when interval is 0 or "0"
+  if (interval === 0 || interval === "0") {
+    LOG.debug("active_users automatic scheduling disabled (activeUsersInterval = 0)")
+    return
+  }
+
+  // Schedule periodic computation
+  const every = interval || "24h"
+  const ms = ms4(every)
+  const spawned = cds.spawn({ every: ms }, async () => {
+    try {
+      await computeActiveUsers()
+    } catch (err) {
+      LOG.error("active_users computation failed", { error: err.message })
+    }
+  })
+
+  // Clean up timer on shutdown to prevent post-teardown errors in test environments
+  if (spawned?.timer) {
+    cds.on("shutdown", () => clearInterval(spawned.timer))
+  }
+
+  LOG.debug("active_users metric scheduled", { every })
+}