@cap-js/agents 0.9.6 → 0.9.8

package/lib/masking/structured/index.js

@@ -0,0 +1,170 @@
+import cds from "@sap/cds"
+import {
+  shouldHash,
+  personalDataElements,
+  discoverElementsToBeMasked,
+  hasPersonalDataAnnotations,
+  hasPersonalDataAnnotation,
+  actionReturnType,
+} from "./findElements.js"
+
+export { shouldHash, personalDataElements, discoverElementsToBeMasked, hasPersonalDataAnnotations }
+
+/**
+ * Check whether masking is needed for a service — local model + remote MCP models.
+ */
+export function needsMasking(serviceName) {
+  const srv = cds.services?.[serviceName]
+  const model = cds.context?.model ?? srv?.model
+  if (model && hasPersonalDataAnnotations(model, serviceName)) return true
+  for (const { serviceName: remoteName } of Object.values(cds.context?.__mcpDynamicTools ?? {})) {
+    const remoteSrv = cds.services?.[remoteName]
+    const remoteModel = remoteSrv?.model
+    if (remoteModel && hasPersonalDataAnnotations(remoteModel, remoteName)) return true
+  }
+  return false
+}
+
+export function pseudonymizeData(data, annotatedFields, session) {
+  if (!annotatedFields.size) return
+  const rows = Array.isArray(data) ? data : data ? [data] : []
+  for (const row of rows) {
+    if (!row || typeof row !== "object") continue
+    for (const field of annotatedFields) {
+      if (Array.isArray(field) && field.length > 1) {
+        // Multi-segment path: nested ({address:{street}}) or CAP-flattened ({address_street}).
+        const [first, ...rest] = field
+        if (first in row && row[first] != null && typeof row[first] === "object") {
+          pseudonymizeData(row[first], new Set([rest.length === 1 ? rest[0] : rest]), session)
+        } else {
+          const flat = field.join("_")
+          if (flat in row && row[flat] != null) {
+            const v = row[flat]
+            row[flat] = Array.isArray(v)
+              ? v.map((x) => (x == null ? x : session.pseudonymize(x, flat)))
+              : session.pseudonymize(v, flat)
+          }
+        }
+      } else {
+        // Plain name or single-element path array ["nicknames"].
+        const name = Array.isArray(field) ? field[0] : field
+        if (!(name in row) || row[name] == null) continue
+        const value = row[name]
+        // Scalar array — hash each element.
+        row[name] = Array.isArray(value)
+          ? value.map((v) => (v == null ? v : session.pseudonymize(v, name)))
+          : session.pseudonymize(value, name)
+      }
+    }
+  }
+}
+
+export function resolveArgs(value, session) {
+  if (!session?._hashToOriginal?.size) return value
+  if (typeof value === "string") return session.resolveText(value)
+  if (Array.isArray(value)) {
+    const mapped = value.map((v) => resolveArgs(v, session))
+    return mapped.every((v, i) => v === value[i]) ? value : mapped
+  }
+  if (value && typeof value === "object") {
+    let changed = false
+    const out = {}
+    for (const [k, v] of Object.entries(value)) {
+      const resolved = resolveArgs(v, session)
+      out[k] = resolved
+      if (resolved !== v) changed = true
+    }
+    return changed ? out : value
+  }
+  return value
+}
+
+// Walk a CDS type definition recursively alongside `data`, hashing PII leaves.
+// Covers action/function return shapes: named type refs, structs, arrays, scalar arrays.
+// Depth guard (20) prevents runaway on self-referential types.
+function pseudonymizeByType(data, typeDef, propName, session, model, strictMasking, depth = 0) {
+  if (data == null || typeDef == null || depth > 20) return data
+
+  // Named type ref → resolve then recurse; unresolved scalar → hash if PII.
+  if (typeDef.type && !typeDef.elements && !typeDef.items) {
+    const resolved = model.definitions?.[typeDef.type]
+    if (resolved)
+      return pseudonymizeByType(data, resolved, propName, session, model, strictMasking, depth + 1)
+    if (shouldHash(typeDef) && hasPersonalDataAnnotation(typeDef)) {
+      if (!strictMasking && typeDef["@Common.Masked"] === false) return data
+      return session.pseudonymize(data, propName)
+    }
+    return data
+  }
+
+  // Array: `many String @PersonalData` carries the annotation on the arrayed node, not
+  // on items — detect and hash each scalar directly; otherwise recurse per item.
+  if (typeDef.items) {
+    if (!Array.isArray(data)) return data
+    const scalarPii =
+      hasPersonalDataAnnotation(typeDef) &&
+      !typeDef.items.elements &&
+      !typeDef.items.items &&
+      shouldHash(typeDef.items)
+    if (scalarPii && (strictMasking || typeDef["@Common.Masked"] !== false))
+      return data.map((item) => (item == null ? item : session.pseudonymize(item, propName)))
+    return data.map((item) =>
+      pseudonymizeByType(item, typeDef.items, propName, session, model, strictMasking, depth + 1),
+    )
+  }
+
+  // Struct → recurse into each element.
+  if (typeDef.elements) {
+    if (typeof data !== "object" || Array.isArray(data)) return data
+    for (const [name, elDef] of Object.entries(typeDef.elements)) {
+      if (!(name in data) || data[name] == null) continue
+      data[name] = pseudonymizeByType(
+        data[name],
+        elDef,
+        name,
+        session,
+        model,
+        strictMasking,
+        depth + 1,
+      )
+    }
+    return data
+  }
+
+  // Inline scalar leaf.
+  if (shouldHash(typeDef) && hasPersonalDataAnnotation(typeDef)) {
+    if (!strictMasking && typeDef["@Common.Masked"] === false) return data
+    return session.pseudonymize(data, propName)
+  }
+  return data
+}
+
+// Pseudonymize PII in a decoded tool result object (mutates in place).
+// Queries: CQL-derived field discovery. Actions/functions: recursive type walk.
+export function pseudonymizeToolResult({
+  decoded,
+  toolName,
+  cql,
+  strictMasking = false,
+  session,
+  srv,
+  model,
+}) {
+  if (!decoded || !session || !srv || !model) return
+  const payload = decoded?.data ?? decoded?.result
+  if (payload == null) return
+
+  if (toolName === "query" || toolName.endsWith("_query")) {
+    const annotatedFields = discoverElementsToBeMasked(model, srv, cql, strictMasking)
+    if (!annotatedFields.size) return
+    pseudonymizeData(payload, annotatedFields, session)
+    return
+  }
+
+  // Action/function: walk return-type definition. Top-level scalar has no element
+  // name → use tool name as hash prefix.
+  const returnType = actionReturnType(model, srv, toolName)
+  if (!returnType) return
+  const key = decoded.data != null ? "data" : "result"
+  decoded[key] = pseudonymizeByType(payload, returnType, toolName, session, model, strictMasking)
+}

package/lib/masking/unstructured/dpi.js

@@ -0,0 +1,84 @@
+import cds from "@sap/cds"
+
+const PSEUDONYMIZE_PATH = "/anonymization/api/v1.0/unstructureddata/pseudonymize/text"
+const TIMEOUT = 30_000
+const DEFAULT_ENTITIES = [
+  "profile-person",
+  "profile-email",
+  "profile-phone",
+  "profile-address",
+  "profile-username-password",
+  "profile-nationalid",
+  "profile-iban",
+  "profile-ssn",
+  "profile-credit-card-number",
+  "profile-passport",
+  "profile-driverlicense",
+]
+
+export async function anonymize(text) {
+  const destinationName = resolveDestination()
+  if (!destinationName || !text) return { text }
+  const result = await anonymizeText(text, destinationName)
+  return { text: result.text, mappings: result.mappings }
+}
+
+function resolveDestination() {
+  const required = cds.env.requires?.["data-anonymization"]
+  const destinationName = required?.credentials?.destination
+  if (!destinationName) return undefined
+  return destinationName
+}
+
+async function anonymizeText(text, destinationName) {
+  const payload = buildPayload(text)
+  const data = await postToDpi(payload, destinationName)
+  const mappings = extractPseudonymMappings(data.metadata)
+  // Rewrite DPI tags in the anonymized text from <<profile-person>:hash> to person-hash.
+  const result = data.result.replace(/<<(?:profile-)?([^>]+)>:([^>]+)>/g, "$1-$2")
+  return { text: result, mappings }
+}
+
+function buildPayload(text) {
+  const payload = new URLSearchParams()
+  payload.set("text", text)
+  payload.set("entities", DEFAULT_ENTITIES.join(";"))
+  payload.set("anonymization-method-per-profile", "")
+  payload.set("whitelist", "")
+  payload.set("enable-default-whitelist", "false")
+  return payload.toString()
+}
+
+function extractPseudonymMappings(data) {
+  const mappings = []
+  // DPI returns pseudonyms in the form "<<profile-person>:abc12345>".
+  // Convert to the standard tag format "person-abc12345" and also register
+  // the bare hash "abc12345" so the LLM can use it in queries.
+  for (const dpiTag of Object.keys(data)) {
+    const match = dpiTag.match(/^<<(?:profile-)?([^>]+)>:([^>]+)>$/)
+    if (!match) continue
+    const [, entityType, hash] = match
+    const tag = `${entityType}-${hash}`
+    const original = data[dpiTag].real_entity
+    mappings.push([tag, original])
+    mappings.push([hash, original])
+  }
+  return mappings
+}
+// API Docs: https://api.sap.com/api/sap-dpi-pseudonymization-v1/resource/Pseudonymization
+// SAP Help: https://help.sap.com/docs/data-privacy-integration/development/api-endpoints-9956053a4e6447cfbaccb9d2dee35c11
+async function postToDpi(payload, destinationName) {
+  const { executeHttpRequest } = await import("@sap-cloud-sdk/http-client")
+  const response = await executeHttpRequest(
+    { destinationName },
+    {
+      method: "post",
+      url: `${PSEUDONYMIZE_PATH}?priority=high`,
+      data: payload,
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      timeout: TIMEOUT,
+    },
+    { fetchCsrfToken: false },
+  )
+  return response.data
+}

package/lib/masking/unstructured/hana.js

@@ -0,0 +1,72 @@
+import cds from "@sap/cds"
+import { generatePseudonymTag } from "../store.js"
+import { circuitBreaker, retry } from "../../utils/resilience.js"
+
+const LOG = cds.log("agents")
+
+// Full list of categories HANA detects: https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-predictive-analysis-library/descriptions-of-entity-types
+const DPP_CATEGORIES = new Map([
+  ["PERSON", "person"],
+  ["URI:EMAIL", "email"],
+  ["PHONE", "phone"],
+  ["ADDRESS", "address"],
+  ["URI:URL", "url"],
+  ["URI:IP", "ip"],
+])
+
+const PAL_CONNECTIVITY_ERROR = "73003604"
+const retryMw = retry(5, {
+  shouldRetry: (err) => String(err?.message ?? "").includes(PAL_CONNECTIVITY_ERROR),
+})
+const circuitBreakerMw = circuitBreaker()
+
+export async function anonymize(text, seed) {
+  if (!text || !seed) return { text }
+  try {
+    const resilientPseudonymize = circuitBreakerMw({
+      fn: retryMw({ fn: pseudonymizeText }),
+      context: { uri: "hana-script-server" },
+    })
+    return await resilientPseudonymize({ text, seed })
+  } catch (err) {
+    LOG.error(`SAP HANA Cloud NLS based pseudonymization disabled due to error: `, err)
+    return { text }
+  }
+}
+
+async function pseudonymizeText({ text, seed }) {
+  const res = await cds.run(buildPalCallSql(), [text])
+  const entities = res.changes[1]
+  const piiEntities = entities
+    .filter((e) => e.TYPE === "ner" && DPP_CATEGORIES.has(e.ENTITY))
+    // Sort back to front so offsets stay valid after replacement
+    .sort((a, b) => b.GLOBAL_OFFSET - a.GLOBAL_OFFSET)
+
+  const mappings = []
+  const seen = new Set()
+  let result = text
+  for (const row of piiEntities) {
+    if (result.slice(row.GLOBAL_OFFSET, row.GLOBAL_OFFSET + row.TOKEN.length) !== row.TOKEN)
+      continue
+    const category = DPP_CATEGORIES.get(row.ENTITY)
+    const tag = generatePseudonymTag(seed, row.TOKEN, category)
+    result = `${result.slice(0, row.GLOBAL_OFFSET)}${tag}${result.slice(row.GLOBAL_OFFSET + row.TOKEN.length)}`
+    if (!seen.has(row.TOKEN)) {
+      seen.add(row.TOKEN)
+      const hash = tag.slice(category.length + 1)
+      mappings.push([tag, row.TOKEN])
+      mappings.push([hash, row.TOKEN])
+    }
+  }
+  return { text: result, mappings, textAnalysisResults: entities }
+}
+
+function buildPalCallSql() {
+  return `DO (IN text NVARCHAR(5000) => ?, OUT textAnalysisResults TABLE (ID NVARCHAR(36), "TYPE" NVARCHAR(3), SENTENCE_ID INTEGER, "TOKEN" NVARCHAR(5000), "ENTITY" NVARCHAR(1000), OFFSET INTEGER, GLOBAL_OFFSET INTEGER) => ?) BEGIN
+    lt_data = SELECT CAST(SYSUUID as NVARCHAR(36)) AS "ID", :text AS "CONTENT", CAST('' AS NVARCHAR(1000)) AS "LANGUAGE", CAST('ner' AS NVARCHAR(20)) AS "TASK" FROM DUMMY UNION SELECT CAST(SYSUUID as NVARCHAR(36)) AS "ID", :text AS "CONTENT", CAST('' AS NVARCHAR(1000)) AS "LANGUAGE", CAST('pos' AS NVARCHAR(20)) AS "TASK" FROM DUMMY;
+    lt_param = SELECT CAST('' AS NVARCHAR(256)) AS "PARAM_NAME", CAST(0 AS INTEGER) AS "INT_VALUE", CAST(0.0 AS DOUBLE) AS "DOUBLE_VALUE", CAST('' AS NVARCHAR(1000)) AS "STRING_VALUE" FROM DUMMY;
+    CALL _SYS_AFL.PAL_TEXT_ANALYSIS(:lt_data, :lt_param, lt_sentences, lt_pos, lt_ner, lt_doc_sentiment, lt_sentence_sentiment, lt_phrase_sentiment, lt_extra);
+    textAnalysisResults = 
+      SELECT SYSUUID AS "ID", 'ner' AS "TYPE", "SENTENCE_ID", "TOKEN", "ENTITY", "OFFSET", "GLOBAL_OFFSET" FROM :lt_ner UNION  SELECT SYSUUID AS "ID", 'pos' AS "TYPE", "SENTENCE_ID", "TOKEN", "ENTITY", "OFFSET", "GLOBAL_OFFSET" FROM :lt_pos;
+END;`
+}

package/lib/masking/unstructured/index.js

@@ -0,0 +1,52 @@
+import cds from "@sap/cds"
+import { anonymize as hana } from "./hana.js"
+import { anonymize as dpi } from "./dpi.js"
+import { ensureSession, pseudonymize } from "../index.js"
+
+export default async function anonymizeUnstructured(text, seed) {
+  const hanaResult = await hana(text, seed)
+  const dpiResult = await dpi(hanaResult.text)
+  return {
+    text: dpiResult.text,
+    mappings: [...(hanaResult.mappings ?? []), ...(dpiResult.mappings ?? [])],
+    textAnalysisResults: hanaResult.textAnalysisResults,
+  }
+}
+
+/**
+ * Pseudonymize user message text parts before graph execution.
+ */
+export async function pseudonymizeUserMessage(srv, requestContext, checkpointer, threadId) {
+  await ensureSession(checkpointer, threadId)
+  const session = cds.context?.["agent.pseudonyms"]
+  const parts = requestContext.userMessage?.parts
+  if (!session || !Array.isArray(parts)) return
+
+  const textParts = parts.filter((p) => (p.kind === "text" || (!p.kind && p.text)) && p.text)
+  if (!textParts.length) return
+
+  const results = await Promise.all(
+    textParts.map((p) =>
+      pseudonymize(
+        {
+          data: p.text,
+          type: "unstructured",
+          seed: session._seed,
+        },
+        srv,
+      ),
+    ),
+  )
+  for (let i = 0; i < textParts.length; i++) {
+    const r = results[i]
+    textParts[i].text = r.data
+    session.addMappings(r.mappings)
+    if (r.metadata?.textAnalysisResults?.length) {
+      session._textAnalysisResults = (session._textAnalysisResults ?? []).concat(
+        r.metadata.textAnalysisResults,
+      )
+    }
+    // Scrub any PII detected in prior turns that is not detected by HANA/DPI
+    textParts[i].text = session.scrubText(textParts[i].text)
+  }
+}

package/lib/models/aicore.js

@@ -11,6 +11,11 @@ import {
   withPromptCachingOptions,
   withPromptCachingParams,
 } from "../utils/caching.js"
+import {
+  isAdditiveCacheUsageModel,
+  normalizeAdditiveCacheUsage,
+  normalizeAdditiveCacheUsageChunk,
+} from "../utils/usage.js"
 import { syncSystemPrompt } from "../telemetry/mlflow/prompts.js"
 
 const LOG = cds.log("agents")
@@ -29,8 +34,12 @@ function noTemp0Support(model) {
 }
 
 const llmError = (err) => {
-  LOG.error(`AI Core request failed!`, err.rootCause || err)
-  cds.error(cds.i18n.messages.at("LLM_UNAVAILABLE"))
+  if (err.rootCause?.message.match(/Could not find service credentials for AI Core/)) {
+    throw err.rootCause
+  } else {
+    LOG.error(`AI Core request failed!`, err.rootCause || err)
+    cds.error(cds.i18n.messages.at("LLM_UNAVAILABLE"))
+  }
 }
 
 class _InstrumentedOrchestrationClient extends OrchestrationClient {
@@ -83,6 +92,8 @@ class _InstrumentedOrchestrationClient extends OrchestrationClient {
         // works for every agent regardless of this flag (deep or managed alike).
         // Default on; `streaming: false` opts out.
         streaming: streaming !== false,
+        // p-retry from langchain = 0, retry for AI Core completion is still set to 2
+        maxRetries: 0,
         onFailedAttempt: (err) => {
           // Abort retries when circuit breaker is open (otherwise pRetry delays ~30-60s)
           if (err.code === "EOPENBREAKER" || err.message === "Breaker is open") {
@@ -108,7 +119,8 @@ class _InstrumentedOrchestrationClient extends OrchestrationClient {
     opts = _withMiddleware(this, opts)
     const prepared = _prepareMessages(messages, { flatten, model, opts })
     try {
-      return super._generate(prepared.inputMessages, prepared.opts, runManager)
+      const result = await super._generate(prepared.inputMessages, prepared.opts, runManager)
+      return isAdditiveCacheUsageModel(model) ? normalizeAdditiveCacheUsage(result) : result
     } catch (err) {
       llmError(err)
     }
@@ -135,6 +147,7 @@ class _InstrumentedOrchestrationClient extends OrchestrationClient {
     let turnHasToolCall = false
     try {
       for await (const chunk of super._streamResponseChunks(inputMessages, opts, runManager)) {
+        if (isAdditiveCacheUsageModel(model)) normalizeAdditiveCacheUsageChunk(chunk)
         if (chunk.message?.tool_call_chunks?.length > 0) turnHasToolCall = true
         const text = chunk.text || extractTextFromContentBlocks(chunk)
         const reasoning = extractReasoningFromChunk(chunk)

package/lib/models/openai.js

@@ -0,0 +1,9 @@
+import { ChatOpenAI } from "@langchain/openai"
+
+export default class ChatOpenAIService extends ChatOpenAI {
+  constructor(name, options = {}) {
+    const { credentials = {} } = options
+    super({ ...options, configuration: credentials })
+    this.name = name
+  }
+}