@cap-js/agents 0.0.0 → 0.9.1

package/lib/utils/markdown.js

@@ -0,0 +1,199 @@
+import cds from "@sap/cds"
+const { path, fs } = cds.utils
+const LOG = cds.log("agents")
+
+/**
+ * Mirrors CAP's internal slug rules used for service path generation.
+ */
+export const slugified = (name) =>
+  /[^.]+$/
+    .exec(name)[0]
+    .replace(/Service$/, "")
+    .replace(/_/g, "-")
+    .replace(/([a-z0-9])([A-Z])/g, (_m, c, C) => c + "-" + C)
+    .toLowerCase()
+
+/**
+ * Absolute filesystem directory of the `.cds` source file that defines `srv`.
+ */
+export function serviceSourceDir(srv) {
+  const file = srv?.definition?.$location?.file
+  if (!file) return undefined
+  // $location.file is relative to cds.root
+  return path.dirname(path.join(cds.root, file))
+}
+
+/**
+ * Get the effective service definition (feature-toggled if available, else base).
+ */
+function effectiveDefinition(srv) {
+  return cds.context?.model?.definitions?.[srv.name] || srv?.definition
+}
+
+/**
+ * Resolve a path from a `@agent.directory` / `@agent.card` annotation against the
+ * `.cds` source file's directory. Absolute paths are returned as-is.
+ */
+function resolveAnnotatedPath(srv, annotationValue) {
+  if (!annotationValue || typeof annotationValue !== "string") return undefined
+  if (path.isAbsolute(annotationValue)) return annotationValue
+  const srcDir = serviceSourceDir(srv)
+  if (!srcDir) return undefined
+  return path.resolve(srcDir, annotationValue)
+}
+
+/**
+ * Resolve the agent directory for a service.
+ *
+ * Resolution order (all paths relative to the `.cds` source file dir):
+ *   1. `@agent.directory` annotation (relative to `.cds` source file dir, or absolute)
+ *   2. `<srcDir>` itself — when the service `.cds` file lives inside its own dedicated
+ *      folder and `AGENTS.md` is co-located there (e.g. `srv/travel-agent/service.cds`
+ *      + `srv/travel-agent/AGENTS.md`).
+ *   3. `<srcDir>/<slug-with-agent-suffix>/` — sibling directory.
+ *      The slug gets `-agent` appended if it does not already end in `-agent`,
+ *      e.g. `TravelService` → `./travel-agent/`, `ProductAgentService` → `./product-agent/`.
+ *   4. `<srcDir>/agents/<base>/` — collected under an `agents/` parent.
+ *      The base is the slug with any trailing `-agent` stripped,
+ *      e.g. `TravelService` → `./agents/travel/`, `ProductAgentService` → `./agents/product/`.
+ *   5. `undefined`
+ */
+export function resolveAgentDir(srv) {
+  const def = effectiveDefinition(srv)
+  const annotated = resolveAnnotatedPath(srv, def?.["@agent.directory"])
+  // 1. `@agent.directory`
+  if (annotated) {
+    if (fs.existsSync(annotated)) return annotated
+    LOG.warn("@agent.directory path not found, falling back to convention", {
+      service: srv?.name,
+      annotation: def?.["@agent.directory"],
+      resolved: annotated,
+    })
+    return undefined
+  }
+  const srcDir = serviceSourceDir(srv)
+  if (!srcDir) return undefined
+
+  // 2. <srcDir> itself — AGENTS.md co-located with the .cds file
+  if (fs.existsSync(path.join(srcDir, "AGENTS.md"))) return srcDir
+
+  const slug = slugified(srv.name)
+  const agentSlug = slug.endsWith("-agent") ? slug : `${slug}-agent`
+  const base = slug.endsWith("-agent") ? slug.slice(0, -"-agent".length) : slug
+
+  // 3. <srcDir>/<agentSlug>/
+  const sibling = path.join(srcDir, agentSlug)
+  if (fs.existsSync(sibling)) return sibling
+
+  // 4. <srcDir>/agents/<base>/
+  if (base) {
+    const grouped = path.join(srcDir, "agents", base)
+    if (fs.existsSync(grouped)) return grouped
+  }
+
+  return undefined
+}
+
+/**
+ * Resolve an explicit agent-card markdown file via `@agent.card` annotation.
+ * Returns `undefined` when no annotation is set; falls through to the
+ * agent-dir-based resolution chain (`AGENT_CARD.md` → `skills/`) handled by
+ * the card builder.
+ */
+export function resolveAgentCardPath(srv) {
+  const def = effectiveDefinition(srv)
+  return resolveAnnotatedPath(srv, def?.["@agent.card"])
+}
+
+/**
+ * `<dir>/AGENTS.md` exists ⇒ this is a deep-agent directory.
+ */
+export function isDeepAgentDir(dir) {
+  if (!dir) return false
+  return fs.existsSync(path.join(dir, "AGENTS.md"))
+}
+
+/**
+ * Parse YAML frontmatter from a markdown file.
+ */
+export function parseFrontmatter(filePath) {
+  let content
+  try {
+    content = fs.readFileSync(filePath, "utf8")
+  } catch {
+    return null
+  }
+
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)
+  if (!match) return null
+
+  try {
+    const { yaml } = cds.utils
+    return yaml.parse(match[1])
+  } catch {
+    // Fallback: return null if YAML parsing fails
+    return null
+  }
+}
+
+/**
+ * Scan a skills directory and return skill metadata for the agent card.
+ * Reads SKILL.md frontmatter per agentskills.io spec.
+ * Respects metadata.private: true to exclude internal skills.
+ *
+ * @returns {Array<{id, name, description, tags, examples}>}
+ */
+export function scanSkills(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return []
+
+  let entries
+  try {
+    entries = fs.readdirSync(skillsDir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+
+  const skills = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const skillFile = path.join(skillsDir, entry.name, "SKILL.md")
+    const meta = parseFrontmatter(skillFile)
+    if (!meta || !meta.name) continue
+
+    // metadata.private: true → internal skill, not in agent card
+    const isPrivate = meta.metadata?.private === "true" || meta.metadata?.private === true
+    if (isPrivate) continue
+
+    skills.push({
+      id: meta.name,
+      name: meta.name.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+      description: (meta.description || "").trim(),
+      tags: meta.metadata?.tags || [],
+      examples: meta.metadata?.examples || [],
+    })
+  }
+
+  // Alphabetical sort for deterministic output across filesystems
+  return skills.sort((a, b) => a.id.localeCompare(b.id))
+}
+
+/**
+ * Parse AGENTS.md frontmatter for agent-level metadata.
+ */
+export function parseAgentMetadata(agentDir) {
+  return parseFrontmatter(path.join(agentDir, "AGENTS.md"))
+}
+
+/**
+ * Parse AGENT_CARD.md for explicit agent card definition (convention within agentDir).
+ */
+export function parseAgentCardMd(agentDir) {
+  return parseFrontmatter(path.join(agentDir, "AGENT_CARD.md"))
+}
+
+/**
+ * Parse an agent card markdown file at an explicit absolute path.
+ */
+export function parseAgentCardFile(absolutePath) {
+  return parseFrontmatter(absolutePath)
+}

package/lib/utils/message-handling.js

@@ -0,0 +1,155 @@
+/**
+ * A2A message part utilities — handle both wire formats:
+ *
+ * v0.3.x (kind-based): {kind:"text",text} | {kind:"file",file:{bytes|uri,mimeType}} | {kind:"data",data}
+ * v1.0   (oneOf):      {content:{$case:"text"|"raw"|"url"|"data", value}, mediaType, filename}
+ */
+
+/**
+ * Extract plain text from A2A parts. Data parts → JSON.stringify. File parts skipped.
+ * @param {Array} parts
+ * @returns {string}
+ */
+export function partsToText(parts = []) {
+  return (
+    parts
+      .map((p) => {
+        if (p.content?.$case === "text") return p.content.value || ""
+        if (p.content?.$case === "data") return JSON.stringify(p.content.value)
+        // REVISIT: remove when @a2a-js/sdk pinned to ^1.x (SDK normalizes to content.$case)
+        if (p.kind === "text" || (!p.kind && p.text)) return p.text || ""
+        if (p.kind === "data" && p.data !== undefined) return JSON.stringify(p.data)
+        return null
+      })
+      .filter((v) => v !== null)
+      .join(" ") || ""
+  )
+}
+
+/**
+ * Return the raw `data` object of the FIRST DataPart in `parts`, or undefined if none.
+ * Handles both wire shapes (v0.3 kind-based, v1.0 oneOf); returned as-is (no clone/validation).
+ * @param {Array} parts
+ * @returns {object | undefined}
+ */
+export function firstDataPart(parts = []) {
+  for (const p of parts) {
+    // Nullish payloads fall through to the text parser (spec: `data` is always an object).
+    if (p.content?.$case === "data" && p.content.value != null) return p.content.value
+    // REVISIT: remove when @a2a-js/sdk pinned to ^1.x (SDK normalizes to content.$case)
+    if (p.kind === "data" && p.data != null) return p.data
+  }
+  return undefined
+}
+
+const IMAGE_MIME_RE = /^image\//
+
+/**
+ * Map A2A parts to LangChain-JS / OpenAI content value for MLflow span inputs.
+ *
+ * Single text part → plain string. Otherwise array of content blocks:
+ *   text/data → {type:"text", text}
+ *   image/*   → {type:"image_url", image_url:{url:"data:<mime>;base64,..."|"<uri>"}}
+ *   other files → {type:"text", text:"[file: <name> (<mime>)]"}
+ *
+ * @param {Array} parts
+ * @returns {string | Array}
+ */
+export function partsToMessageContent(parts = []) {
+  const blocks = []
+  for (const p of parts) {
+    // v1.0 oneOf
+    if (p.content?.$case) {
+      switch (p.content.$case) {
+        case "text":
+          blocks.push({ type: "text", text: p.content.value || "" })
+          break
+        case "url": {
+          const mime = p.mediaType || ""
+          if (IMAGE_MIME_RE.test(mime)) {
+            blocks.push({ type: "image_url", image_url: { url: p.content.value } })
+          } else {
+            const label = p.filename
+              ? `[file: ${p.filename} (${mime || "unknown"})]`
+              : p.content.value
+            blocks.push({ type: "text", text: label })
+          }
+          break
+        }
+        case "raw": {
+          const mime = p.mediaType || "application/octet-stream"
+          const b64 = Buffer.isBuffer(p.content.value)
+            ? p.content.value.toString("base64")
+            : p.content.value
+          if (IMAGE_MIME_RE.test(mime)) {
+            blocks.push({ type: "image_url", image_url: { url: `data:${mime};base64,${b64}` } })
+          } else {
+            blocks.push({ type: "text", text: `[file: ${p.filename || "attachment"} (${mime})]` })
+          }
+          break
+        }
+        case "data":
+          blocks.push({ type: "text", text: JSON.stringify(p.content.value, null, 2) })
+          break
+        default:
+          break
+      }
+      continue
+    }
+    // REVISIT: remove when @a2a-js/sdk pinned to ^1.x (SDK normalizes to content.$case)
+    // v0.3.x kind-based
+    if (p.kind === "text" || (!p.kind && p.text)) {
+      blocks.push({ type: "text", text: p.text || "" })
+    } else if (p.kind === "file") {
+      const f = p.file || p
+      const mime = f.mimeType || "application/octet-stream"
+      if (f.bytes) {
+        if (IMAGE_MIME_RE.test(mime)) {
+          blocks.push({ type: "image_url", image_url: { url: `data:${mime};base64,${f.bytes}` } })
+        } else {
+          blocks.push({ type: "text", text: `[file: ${f.name || "attachment"} (${mime})]` })
+        }
+      } else if (f.uri) {
+        if (IMAGE_MIME_RE.test(mime)) {
+          blocks.push({ type: "image_url", image_url: { url: f.uri } })
+        } else {
+          blocks.push({ type: "text", text: `[file: ${f.name || f.uri} (${mime})]` })
+        }
+      }
+    } else if (p.kind === "data" && p.data !== undefined) {
+      blocks.push({ type: "text", text: JSON.stringify(p.data, null, 2) })
+    }
+  }
+  if (blocks.length === 0) return ""
+  if (blocks.length === 1 && blocks[0].type === "text") return blocks[0].text
+  return blocks
+}
+
+/**
+ * Build OpenAI-format chat messages from A2A conversation history + current message.
+ *
+ * A2A roles → OpenAI roles:
+ *   "user" | "ROLE_USER" | 1 → "user"
+ *   "agent" | "ROLE_AGENT" | 2 → "assistant"
+ *
+ * Uses history when available (SDK appends current message to it before execute()),
+ * falls back to current message only for new tasks.
+ *
+ * @param {object} requestContext
+ * @returns {Array<{role:string, content:string|Array}>}
+ */
+export function buildChatMessages(requestContext) {
+  const history = requestContext.task?.history || []
+  const current = requestContext.userMessage
+  const a2aMessages = history.length > 0 ? history : [current]
+
+  function toOaiRole(role) {
+    if (role === "agent" || role === "ROLE_AGENT" || role === 2) return "assistant"
+    return "user"
+  }
+
+  return a2aMessages.filter(Boolean).map((msg) => ({
+    role: toOaiRole(msg.role),
+    content: partsToMessageContent(msg.parts || []),
+  }))
+}

package/lib/utils/utils.js

@@ -0,0 +1,168 @@
+import cds from "@sap/cds"
+import { domainToASCII } from "node:url"
+
+function resolveI18n(value, locale) {
+  if (!value) return undefined
+  const match = /{i18n>([^}]+)}/.exec(value)
+  if (match) {
+    return cds.i18n?.labels?.texts4?.(locale)?.[match[1]] || value
+  }
+  return value
+}
+
+export function getDescription(obj, locale) {
+  locale = locale || cds.context?.locale || "en"
+
+  const title =
+    cds.i18n?.labels?.at(obj, locale) ||
+    resolveI18n(obj["@Common.Label"], locale) ||
+    resolveI18n(obj["@title"], locale)
+
+  const description =
+    resolveI18n(obj["@Core.Description"], locale) || resolveI18n(obj["@description"], locale)
+
+  const longDescription = resolveI18n(obj["@Core.LongDescription"], locale)
+
+  const parts = [title, description].filter(Boolean)
+  if (parts.length === 0 && !longDescription) return obj.doc || undefined
+
+  let result = parts.join("\n")
+
+  if (longDescription) {
+    result = result ? `${result}\n\n${longDescription}` : longDescription
+  }
+
+  return result || undefined
+}
+
+export function getFilteredEntities(srv) {
+  return Object.fromEntries(
+    Object.entries(srv.entities || {})
+      .filter(
+        ([name, entity]) =>
+          !(entity["@cds.autoexposed"] && !entity["@cds.autoexpose"]) &&
+          !name.endsWith("DraftAdministrativeData") &&
+          !name.endsWith(".texts") &&
+          !entity["@cds.api.ignore"],
+      )
+      .sort(([a], [b]) => a.localeCompare(b)),
+  )
+}
+
+export function getFilteredActions(srv) {
+  const actions = {}
+  for (const op of srv.actions || []) {
+    if ((op.kind === "action" || op.kind === "function") && !op["@cds.api.ignore"]) {
+      const localName = op.name.split(".").pop()
+      actions[localName] = op
+    }
+  }
+  return actions
+}
+
+/**
+ * Sanitize an agent name into a valid LangChain/LLM tool name.
+ */
+export function toolName(rawName) {
+  return rawName
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .toLowerCase()
+    .replace(/^[^a-z]/, (c) => `_${c}`) // ensure first char is a letter (some LLM APIs reject otherwise)
+    .slice(0, 60)
+}
+
+/**
+ * Shorten a UUID/ID to first 8 characters for log readability.
+ */
+export function short(id) {
+  return id?.slice(0, 8) || "-"
+}
+
+/**
+ * Emit an audit log event (fire-and-forget).
+ * All events are mapped to SecurityEvent for compatibility with SAP Audit Log Service.
+ * The original event name is preserved in data.data.event for forensic analysis.
+ * Includes cds.context.id as correlationId for cross-referencing with auto-emitted
+ * DPP events (e.g., SensitiveDataRead triggered by tool entity access).
+ * Never blocks execution. Logs warning on failure.
+ */
+export function audit(event, data) {
+  if (!cds.requires["audit-log"]) return
+  cds.connect
+    .to("audit-log")
+    .then((a) =>
+      a.log("SecurityEvent", {
+        data: { event, correlationId: cds.context?.id, ...data.data },
+        ip: data.ip,
+      }),
+    )
+    .catch((err) => {
+      const LOG = cds.log("agents|audit")
+      LOG.warn("audit emit failed", { event, error: err.message })
+    })
+}
+
+const ALLOWED_PROTOCOLS = ["http:", "https:"]
+
+/**
+ * Validates that a URL belongs to one of the allowed domains.
+ * Handles subdomains, punycode normalization, protocol validation.
+ * Returns true if URL's hostname matches or is a subdomain of any allowed domain.
+ * Returns false for invalid URLs, non-HTTP(S) protocols, or domain mismatch.
+ */
+export function isAllowedDomain(untrustedUrl, allowedDomains) {
+  if (!untrustedUrl || !allowedDomains?.length) return false
+
+  let hostname
+  try {
+    const parsed = new URL(untrustedUrl)
+    if (!ALLOWED_PROTOCOLS.includes(parsed.protocol)) return false
+    hostname = parsed.hostname
+    if (!hostname) return false
+  } catch {
+    return false
+  }
+
+  for (const domain of allowedDomains) {
+    const normalized = domainToASCII(domain)
+    if (!normalized) continue
+    if (hostname === normalized) return true
+    if (hostname.endsWith("." + normalized)) return true
+  }
+
+  return false
+}
+
+export const ms4 =
+  cds.utils.ms4 ||
+  ((val) => {
+    if (typeof val === "number") return val
+    const m = /^(\d+)\s*(ms|s|sec|seconds?|m|min|minutes?|h|hrs|hours?|d|days?|w|weeks?)?$/i.exec(
+      String(val),
+    )
+    if (!m) return Number(val) || 0
+    const n = Number(m[1])
+    const unit = (m[2] || "ms").toLowerCase()
+    const factors = {
+      ms: 1,
+      s: 1000,
+      sec: 1000,
+      second: 1000,
+      seconds: 1000,
+      m: 60000,
+      min: 60000,
+      minute: 60000,
+      minutes: 60000,
+      h: 3600000,
+      hrs: 3600000,
+      hour: 3600000,
+      hours: 3600000,
+      d: 86400000,
+      day: 86400000,
+      days: 86400000,
+      w: 604800000,
+      week: 604800000,
+      weeks: 604800000,
+    }
+    return n * (factors[unit] || 1)
+  })