@cap-js/agents 0.0.0 → 0.9.1

package/lib/preview/preview.js

@@ -0,0 +1,46 @@
+import express from "express"
+import { readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { join, dirname } from "node:path"
+import { createRequire } from "node:module"
+
+const _dir = dirname(fileURLToPath(import.meta.url))
+const _chatTemplate = readFileSync(join(_dir, "chat.html"), "utf-8")
+const _require = createRequire(import.meta.url)
+const _markedPath = join(dirname(_require.resolve("marked/package.json")), "lib", "marked.umd.js")
+const _markedJs = readFileSync(_markedPath, "utf-8")
+
+export default function preview(agentName) {
+  const router = express.Router()
+
+  const safeName = agentName
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;")
+
+  // Serve chat preview UI
+  router.get("/", (req, res) => {
+    if (!req.originalUrl.split("?")[0].endsWith("/")) {
+      const [pathPart, query = ""] = req.originalUrl.split("?")
+      return res.redirect(301, pathPart + "/" + (query ? "?" + query : ""))
+    }
+    // Echo the browser's Authorization header into the page
+    const authHeader = (req.headers.authorization || "").replace(/"/g, "&quot;")
+    const html = _chatTemplate
+      .replace(/\{\{agentName\}\}/g, safeName)
+      .replace(/\{\{authHeader\}\}/g, authHeader)
+    res.setHeader("Content-Type", "text/html; charset=utf-8")
+    res.send(html)
+  })
+
+  // Serve bundled marked.js (avoids non-SAP CDN dependency)
+  router.get("/marked.min.js", (_req, res) => {
+    res.setHeader("Content-Type", "application/javascript; charset=utf-8")
+    res.setHeader("Cache-Control", "public, max-age=86400")
+    res.send(_markedJs)
+  })
+
+  return router
+}

package/lib/protocol/agent-card.js

@@ -0,0 +1,297 @@
+import cds from "@sap/cds"
+import { createRequire } from "node:module"
+const { path } = cds.utils
+import { getDescription, getFilteredEntities, getFilteredActions } from "../utils/utils.js"
+import {
+  scanSkills,
+  parseAgentMetadata,
+  parseAgentCardMd,
+  parseAgentCardFile,
+  slugified,
+} from "../utils/markdown.js"
+
+const require = createRequire(import.meta.url)
+
+const LOG = cds.log("agents")
+
+/**
+ * Check if push notifications are enabled via cds.agents.pushNotifications config.
+ * Defaults to true. Set to `false` to disable.
+ */
+function isPushNotificationsEnabled() {
+  const cfg = cds.env.agents?.pushNotifications
+  if (cfg === false) return false
+  return true
+}
+
+const FILE_IO_MIME_TYPES = [
+  "text/csv",
+  "application/json",
+  "text/plain",
+  "application/pdf",
+  "image/png",
+  "image/jpeg",
+]
+
+/**
+ * Merge fileIO MIME types into an agent card when cds.env.agents.fileIO.enabled is true.
+ * defaultInputModes/defaultOutputModes are sufficient to advertise file transfer
+ * capabilities to A2A clients — no capability extension is added.
+ */
+function applyFileIOCapability(card) {
+  const cfg = cds.env.agents?.fileIO
+  if (!cfg?.enabled) return card
+  const inputMimes = cfg.defaultInputModes ?? FILE_IO_MIME_TYPES
+  const outputMimes = cfg.defaultOutputModes ?? FILE_IO_MIME_TYPES
+  const inputModes = [...new Set([...(card.defaultInputModes ?? []), ...inputMimes])]
+  const outputModes = [...new Set([...(card.defaultOutputModes ?? []), ...outputMimes])]
+  return { ...card, defaultInputModes: inputModes, defaultOutputModes: outputModes }
+}
+
+/**
+ * Lines starting with "Example:" (case-insensitive) are parsed as skill examples.
+ */
+function getDocExamples(def) {
+  if (!def.doc) return []
+  return def.doc
+    .split("\n")
+    .filter((line) => /^\s*example\s*:/i.test(line))
+    .map((line) => line.replace(/^\s*example\s*:\s*/i, "").trim())
+    .filter(Boolean)
+}
+
+/**
+ * Generate skills from entities and actions (agentify mode).
+ */
+function generateSkills(entities, actions) {
+  const skills = []
+  const entityNames = Object.keys(entities)
+
+  if (entityNames.length > 0) {
+    const entityDescriptions = entityNames
+      .map((name) => {
+        const desc = getDescription(entities[name])
+        return desc ? `${name}: ${desc}` : name
+      })
+      .join(" \n ")
+
+    skills.push({
+      id: "query",
+      name: "Data Query",
+      description: `Query data from the service. Available entities: \n ${entityDescriptions}`,
+      examples: [`Show me all ${entityNames[0]}`],
+      tags: ["query", "data", "read", ...entityNames.slice(0, 3).map((n) => n.toLowerCase())],
+    })
+  }
+
+  for (const [name, action] of Object.entries(actions)) {
+    const description =
+      getDescription(action) || `${action.kind === "function" ? "Get" : "Execute"} ${name}`
+
+    const docExamples = getDocExamples(action)
+    const examples = docExamples.length > 0 ? docExamples : [description]
+
+    const tags = [name.toLowerCase(), action.kind]
+    if (action.kind === "action") tags.push("hitl")
+
+    skills.push({ id: name, name, description, examples, tags })
+  }
+
+  return skills
+}
+
+/**
+ * Build agent card from explicit params (used by compile.js for compile-time generation).
+ */
+function buildAgentCard({ name, description, entities, actions, url, streaming = false }) {
+  const skills = generateSkills(entities, actions)
+
+  let version = "0.0.1"
+  try {
+    version = require(path.join(cds.root, "package.json")).version || version
+  } catch {
+    /* fallback */
+  }
+
+  return applyFileIOCapability({
+    name,
+    description,
+    url,
+    version,
+    protocolVersion: "0.3.0",
+    supportedInterfaces: [{ url, protocolBinding: "JSONRPC", protocolVersion: "0.3.0" }],
+    capabilities: { streaming, pushNotifications: isPushNotificationsEnabled() },
+    defaultInputModes: ["text/plain"],
+    defaultOutputModes: ["text/plain"],
+    skills,
+  })
+}
+
+/**
+ * Build agent card from CDS model (agentify mode, runtime).
+ */
+function buildAgentCardFromModel(srv, servicePath, streaming = false) {
+  return buildAgentCard({
+    name: srv.name,
+    description: getDescription(srv.definition) || `Agent for ${srv.name}`,
+    entities: getFilteredEntities(srv),
+    actions: getFilteredActions(srv),
+    url: servicePath,
+    streaming,
+  })
+}
+
+/**
+ * Build agent card from AGENT_CARD.md (explicit card file).
+ */
+function buildAgentCardFromCardFile(cardMeta, agentMeta, srv, servicePath, streaming = false) {
+  let version = cardMeta.version || agentMeta?.version
+  try {
+    version = version || require(path.join(cds.root, "package.json")).version
+  } catch {
+    /* fallback */
+  }
+  version = version || "1.0.0"
+
+  const skills = (cardMeta.skills || []).map((s) => ({
+    id: s.id || s.name,
+    name: s.name || s.id,
+    description: s.description || "",
+    tags: Array.isArray(s.tags) ? s.tags : [],
+    examples: Array.isArray(s.examples) ? s.examples : [],
+  }))
+
+  return {
+    name: cardMeta.name || agentMeta?.name || srv.name,
+    description: (
+      cardMeta.description ||
+      agentMeta?.description ||
+      getDescription(srv.definition) ||
+      `Agent for ${srv.name}`
+    ).trim(),
+    url: servicePath,
+    version,
+    protocolVersion: cardMeta.metadata?.protocolVersion || "0.3.0",
+    supportedInterfaces: [
+      { url: servicePath, protocolBinding: "JSONRPC", protocolVersion: "0.3.0" },
+    ],
+    capabilities: cardMeta.metadata?.capabilities || {
+      streaming,
+      pushNotifications: isPushNotificationsEnabled(),
+    },
+    defaultInputModes: cardMeta.defaultInputModes || ["text/plain"],
+    defaultOutputModes: cardMeta.defaultOutputModes || ["text/plain"],
+    skills,
+  }
+}
+
+/**
+ * Build agent card from skills/ directory scan.
+ */
+function buildAgentCardFromSkills(agentDir, agentMeta, srv, servicePath, streaming = false) {
+  const skills = scanSkills(path.join(agentDir, "skills"))
+
+  let version = agentMeta?.version
+  try {
+    version = version || require(path.join(cds.root, "package.json")).version
+  } catch {
+    /* fallback */
+  }
+  version = version || "1.0.0"
+
+  return {
+    name: agentMeta?.name || srv.name,
+    description: (
+      agentMeta?.description ||
+      getDescription(srv.definition) ||
+      `Agent for ${srv.name}`
+    ).trim(),
+    url: servicePath,
+    version,
+    protocolVersion: "0.3.0",
+    supportedInterfaces: [
+      { url: servicePath, protocolBinding: "JSONRPC", protocolVersion: "0.3.0" },
+    ],
+    capabilities: { streaming, pushNotifications: isPushNotificationsEnabled() },
+    defaultInputModes: ["text/plain"],
+    defaultOutputModes: ["text/plain"],
+    skills,
+  }
+}
+
+/**
+ * Generate the A2A agent card for a service.
+ *
+ * Resolution chain (inputs supplied via the `resolved` parameter):
+ *   1. `resolved.agentCardPath` — explicit path to agent card markdown
+ *      (sourced from `@agent.card` annotation by the caller)
+ *   2. `<resolved.agentDir>/AGENT_CARD.md` — convention within agent directory
+ *   3. `<resolved.agentDir>/skills/` — auto-generated from SKILL.md frontmatter
+ *   4. CDS model — entities + actions (agentify fallback)
+ *
+ * @param {object} srv      CDS ApplicationService
+ * @param {object} [options] adapter options (e.g. `path`)
+ * @param {object} [resolved] convention-resolved paths
+ * @param {string} [resolved.agentDir]      absolute path to agent directory or undefined
+ * @param {string} [resolved.agentCardPath] absolute path to explicit card file or undefined
+ */
+function generateAgentCard(srv, options = {}, resolved = {}) {
+  const servicePath = options.path || `/a2a/${slugified(srv.name)}`
+  const { agentDir, agentCardPath } = resolved
+  const streaming = true
+
+  // Priority 1: Explicit agentCardPath (from @agent.card annotation)
+  if (agentCardPath) {
+    const cardMeta = parseAgentCardFile(agentCardPath)
+    if (cardMeta) {
+      const card = buildAgentCardFromCardFile(cardMeta, null, srv, servicePath, streaming)
+      LOG._trace &&
+        LOG.debug("Generated agent card from @agent.card annotation", {
+          service: srv.name,
+          path: agentCardPath,
+          skills: card.skills.length,
+        })
+      return applyFileIOCapability(card)
+    }
+    LOG.warn("Agent card file not found or invalid YAML, falling back", {
+      service: srv.name,
+      path: agentCardPath,
+    })
+  }
+
+  if (agentDir) {
+    const agentMeta = parseAgentMetadata(agentDir)
+
+    // Priority 2: AGENT_CARD.md in agentDir (convention)
+    const cardMeta = parseAgentCardMd(agentDir)
+    if (cardMeta) {
+      const card = buildAgentCardFromCardFile(cardMeta, agentMeta, srv, servicePath, streaming)
+      LOG._trace &&
+        LOG.debug("Generated agent card from AGENT_CARD.md", {
+          service: srv.name,
+          skills: card.skills.length,
+        })
+      return applyFileIOCapability(card)
+    }
+
+    // Priority 3: Scan skills/ directory
+    const card = buildAgentCardFromSkills(agentDir, agentMeta, srv, servicePath, streaming)
+    LOG._trace &&
+      LOG.debug("Generated agent card from skills/", {
+        service: srv.name,
+        skills: card.skills.length,
+      })
+    return applyFileIOCapability(card)
+  }
+
+  // Priority 4: CDS model (agentify mode)
+  const card = buildAgentCardFromModel(srv, servicePath, streaming)
+  LOG._trace &&
+    LOG.debug("Generated agent card from CDS model", {
+      service: srv.name,
+      skills: card.skills.length,
+    })
+  return applyFileIOCapability(card)
+}
+
+export { generateAgentCard, buildAgentCard }

package/lib/protocol/persistence/checkpoint-saver.js

@@ -0,0 +1,317 @@
+/* eslint-disable no-await-in-loop */
+import cds from "@sap/cds"
+import {
+  BaseCheckpointSaver,
+  WRITES_IDX_MAP,
+  copyCheckpoint,
+  getCheckpointId,
+} from "@langchain/langgraph-checkpoint"
+
+const LOG = cds.log("agents")
+
+const toUtf8String = (bytes) => Buffer.from(bytes).toString("utf-8")
+
+const CHECKPOINTS = "cap.agent.Checkpoints"
+const WRITES = "cap.agent.CheckpointWrites"
+
+const ASSOC_TYPES = new Set(["cds.Association", "cds.Composition"])
+
+function scalarColumnsOf(entityName) {
+  return Object.entries(cds.model.definitions[entityName].elements)
+    .filter(([, e]) => !ASSOC_TYPES.has(e.type))
+    .map(([name]) => name)
+}
+
+const resolveUserId = () => {
+  const id = cds.context?.user?.id
+  if (!id)
+    LOG.warn("cds.context missing or has no user — checkpoint query falls back to 'anonymous'")
+  return id ?? "anonymous"
+}
+
+/**
+ * CDS entity-backed LangGraph checkpoint saver.
+ *
+ * Persists graph state to cap.agent.Checkpoints and cap.agent.CheckpointWrites,
+ * enabling multi-turn conversations.
+ *
+ * Implements BaseCheckpointSaver from @langchain/langgraph-checkpoint.
+ * Uses inherited JsonPlusSerializer (this.serde) to handle LangChain-specific
+ * types (messages, tool calls, etc.).
+ */
+export class CdsCheckpointSaver extends BaseCheckpointSaver {
+  constructor(serde) {
+    super(serde)
+  }
+
+  /**
+   * Find the checkpoint namespace holding the most recent checkpoint for a
+   * thread. LangGraph writes the root graph state under checkpoint_ns=""; but a
+   * graph whose final node runs in a nested namespace (e.g. a custom StateGraph
+   * with a "tools" node) may only leave state under that nested ns. Callers that
+   * recover final state from the checkpoint can use this to locate the right ns
+   * when the default "" lookup misses. Returns undefined if the thread has none.
+   */
+  async latestNamespace(thread_id) {
+    if (!thread_id) return undefined
+    const row = await SELECT.one
+      .from(CHECKPOINTS)
+      .columns("checkpoint_ns")
+      .where({ thread_id, createdBy: resolveUserId() })
+      .orderBy("checkpoint_id desc")
+    return row?.checkpoint_ns
+  }
+
+  /**
+   * Load a checkpoint for a thread.
+   * If checkpoint_id in config -> load that exact checkpoint.
+   * Otherwise -> load latest (checkpoint_id is UUID6, time-ordered, so desc = latest).
+   * Also loads associated CheckpointWrites (LangGraph expects them in the tuple).
+   */
+  async getTuple(config) {
+    const thread_id = config.configurable?.thread_id
+    if (!thread_id) return undefined
+    const checkpoint_ns = config.configurable?.checkpoint_ns ?? ""
+    const checkpoint_id = getCheckpointId(config)
+
+    let row
+    if (checkpoint_id) {
+      row = await SELECT.one
+        .from(CHECKPOINTS)
+        .columns(...scalarColumnsOf(CHECKPOINTS))
+        .where({ thread_id, checkpoint_ns, checkpoint_id, createdBy: resolveUserId() })
+    } else {
+      row = await SELECT.one
+        .from(CHECKPOINTS)
+        .columns(...scalarColumnsOf(CHECKPOINTS))
+        .where({ thread_id, checkpoint_ns, createdBy: resolveUserId() })
+        .orderBy("checkpoint_id desc")
+    }
+
+    if (!row) return undefined
+
+    if (!row.checkpoint) {
+      LOG.warn("Checkpoint row exists but LOB column is missing — treating as miss", {
+        thread_id,
+        checkpoint_id: row.checkpoint_id,
+      })
+      return undefined
+    }
+
+    const actualCheckpointId = row.checkpoint_id
+
+    const persistAll = cds.env.agents?.persistAllCheckpointWrites === true
+    const writesFilter = { thread_id, checkpoint_ns, checkpoint_id: actualCheckpointId }
+    if (!persistAll) writesFilter.idx = { "<": 0 }
+    const writeRows = await SELECT.from(WRITES)
+      .columns(...scalarColumnsOf(WRITES))
+      .where(writesFilter)
+
+    // Deserialize via inherited JsonPlusSerializer (handles LangChain message types etc.)
+    const checkpoint = await this.serde.loadsTyped("json", row.checkpoint)
+    const metadata = await this.serde.loadsTyped("json", row.metadata)
+    const pendingWrites = await Promise.all(
+      writeRows.map(async (w) => [
+        w.task_id,
+        w.channel,
+        await this.serde.loadsTyped("json", w.value),
+      ]),
+    )
+
+    const tuple = {
+      config: {
+        configurable: { thread_id, checkpoint_ns, checkpoint_id: actualCheckpointId },
+      },
+      checkpoint,
+      metadata,
+      pendingWrites,
+    }
+
+    // Link to parent checkpoint for time-travel / history chain
+    if (row.parent_checkpoint_id) {
+      tuple.parentConfig = {
+        configurable: {
+          thread_id,
+          checkpoint_ns,
+          checkpoint_id: row.parent_checkpoint_id,
+        },
+      }
+    }
+
+    LOG._trace && LOG.debug("Checkpoint loaded", { thread_id, checkpoint_id: actualCheckpointId })
+    return tuple
+  }
+
+  /**
+   * Save a new checkpoint after a graph step completes.
+   * config.configurable.checkpoint_id = the PARENT checkpoint (what was loaded before this step).
+   * checkpoint.id = the NEW checkpoint being stored.
+   */
+  async put(config, checkpoint, metadata) {
+    const thread_id = config.configurable?.thread_id
+    const checkpoint_ns = config.configurable?.checkpoint_ns ?? ""
+    const parent_checkpoint_id = config.configurable?.checkpoint_id
+
+    if (!thread_id) {
+      throw new Error('Missing required "thread_id" in config.configurable')
+    }
+
+    const prepared = copyCheckpoint(checkpoint)
+    const [, serializedCheckpoint] = await this.serde.dumpsTyped(prepared)
+    const [, serializedMetadata] = await this.serde.dumpsTyped(metadata)
+
+    await UPSERT.into(CHECKPOINTS).entries({
+      thread_id,
+      checkpoint_ns,
+      checkpoint_id: checkpoint.id,
+      parent_checkpoint_id,
+      checkpoint: toUtf8String(serializedCheckpoint),
+      metadata: toUtf8String(serializedMetadata),
+      createdBy: resolveUserId(),
+    })
+
+    LOG._trace && LOG.debug("Checkpoint saved", { thread_id, checkpoint_id: checkpoint.id })
+
+    return {
+      configurable: {
+        thread_id,
+        checkpoint_ns,
+        checkpoint_id: checkpoint.id,
+      },
+    }
+  }
+
+  /**
+   * Save intermediate node outputs during a graph step.
+   * Called by LangGraph after each node finishes, before the next checkpoint is created.
+   * Special channels (__interrupt__, __error__) get negative indices via WRITES_IDX_MAP.
+   *
+   * By default only special (negative-index) writes are persisted to reduce DB load.
+   * Regular node outputs are already captured in the checkpoint blob via put().
+   * Enable cds.env.agents.persistAllCheckpointWrites for custom graphs with parallel branches.
+   */
+  async putWrites(config, writes, taskId) {
+    const thread_id = config.configurable?.thread_id
+    const checkpoint_ns = config.configurable?.checkpoint_ns ?? ""
+    const checkpoint_id = config.configurable?.checkpoint_id
+
+    if (!thread_id || !checkpoint_id) {
+      throw new Error('Missing required "thread_id" or "checkpoint_id" in config.configurable')
+    }
+
+    const persistAll = cds.env.agents?.persistAllCheckpointWrites === true
+    const entries = []
+
+    for (let i = 0; i < writes.length; i++) {
+      const [channel, value] = writes[i]
+      const idx = WRITES_IDX_MAP[channel] ?? i
+
+      // Skip positive-index (regular node output) writes unless full persistence enabled
+      if (!persistAll && idx >= 0) continue
+
+      // Dedup: skip positive-index writes that already exist
+      if (idx >= 0) {
+        const existing = await SELECT.one
+          .from(WRITES)
+          .columns("task_id")
+          .where({ thread_id, checkpoint_ns, checkpoint_id, task_id: taskId, idx })
+        if (existing) continue
+      }
+
+      const [, serializedValue] = await this.serde.dumpsTyped(value)
+
+      entries.push({
+        thread_id,
+        checkpoint_ns,
+        checkpoint_id,
+        task_id: taskId,
+        idx,
+        channel,
+        value: toUtf8String(serializedValue),
+        createdBy: resolveUserId(),
+      })
+    }
+
+    if (entries.length > 0) {
+      await UPSERT.into(WRITES).entries(entries)
+    }
+  }
+
+  /**
+   * Stream checkpoints for a thread, newest first.
+   */
+  async *list(config, options) {
+    const { thread_id, checkpoint_ns = "" } = config?.configurable ?? {}
+    if (!thread_id) return
+
+    const userLimit = options?.limit
+    const BATCH_SIZE = 100
+    let cursorBefore = options?.before?.configurable?.checkpoint_id
+    let yielded = 0
+
+    while (true) {
+      const remaining = userLimit ? userLimit - yielded : Infinity
+      if (remaining <= 0) return
+      const batchSize = Math.min(BATCH_SIZE, remaining)
+
+      const rows = await SELECT.from(CHECKPOINTS)
+        .columns(...scalarColumnsOf(CHECKPOINTS))
+        .where({
+          thread_id,
+          checkpoint_ns,
+          createdBy: resolveUserId(),
+          ...(cursorBefore ? { checkpoint_id: { "<": cursorBefore } } : {}),
+        })
+        .orderBy("checkpoint_id desc")
+        .limit(batchSize)
+
+      if (rows.length === 0) return
+
+      for (const row of rows) {
+        if (!row.checkpoint) {
+          LOG.warn("Checkpoint row has missing LOB — skipping", {
+            thread_id,
+            checkpoint_id: row.checkpoint_id,
+          })
+          continue
+        }
+        const [checkpoint, metadata] = await Promise.all([
+          this.serde.loadsTyped("json", row.checkpoint),
+          this.serde.loadsTyped("json", row.metadata),
+        ])
+        yield {
+          config: {
+            configurable: { thread_id, checkpoint_ns, checkpoint_id: row.checkpoint_id },
+          },
+          checkpoint,
+          metadata,
+          parentConfig: row.parent_checkpoint_id
+            ? {
+                configurable: { thread_id, checkpoint_ns, checkpoint_id: row.parent_checkpoint_id },
+              }
+            : undefined,
+        }
+        yielded++
+      }
+
+      // Short batch -> no more rows beyond it.
+      if (rows.length < batchSize) return
+
+      // Advance cursor: oldest row of this batch (rows are checkpoint_id desc).
+      cursorBefore = rows[rows.length - 1].checkpoint_id
+    }
+  }
+
+  async deleteThread(threadId) {
+    const checkpointIds = await SELECT.from(CHECKPOINTS)
+      .columns("checkpoint_id", "checkpoint_ns")
+      .where({ thread_id: threadId, createdBy: cds.context.user.id })
+
+    if (checkpointIds.length > 0) {
+      const ids = checkpointIds.map(({ checkpoint_id }) => checkpoint_id)
+      await DELETE.from(WRITES).where({ thread_id: threadId, checkpoint_id: { in: ids } })
+    }
+
+    await DELETE.from(CHECKPOINTS).where({ thread_id: threadId, createdBy: cds.context.user.id })
+  }
+}