@cap-js/agents 0.9.7 → 0.9.8

package/lib/telemetry/chat-tracing.js

@@ -308,6 +308,8 @@ export function setLLMSpanStartAttrs(
   if (params?.temperature != null)
     span.setAttribute("gen_ai.request.temperature", params.temperature)
   if (params?.max_tokens != null) span.setAttribute("gen_ai.request.max_tokens", params.max_tokens)
+  const modelParams = pickModelParams(params)
+  if (modelParams) span.setAttribute("gen_ai.request.model_params", JSON.stringify(modelParams))
   if (cds.context?.["agent.context.id"])
     span.setAttribute("gen_ai.conversation.id", cds.context["agent.context.id"])
   if (streaming) span.setAttribute("gen_ai.request.stream", true)

package/lib/telemetry/mlflow/evaluation.js

@@ -6,17 +6,36 @@ export async function createEvalRun({ name } = {}) {
   if (!exporter) return null
   const creds = cds.env.requires?.mlflow?.credentials || {}
   const experimentId = creds.MLFLOW_EXPERIMENT_ID || process.env.MLFLOW_EXPERIMENT_ID || "0"
-  return exporter.createRun(experimentId, name)
+  const tags = [
+    ...(await getSourceTags()),
+    { key: "mlflow.user", value: "@cap-js/agents evaluation" },
+  ]
+  return exporter.createRun(experimentId, name, tags)
 }
 
-export async function closeEvalRun(runId) {
+export async function closeEvalRun({ mlflowRunId: runId, metricKeys = [], prompts = [] }) {
   if (!runId) return
-  getMlflowExporter()?.closeRun(runId)
+  const exporter = getMlflowExporter()
+  if (!exporter) return
+  await logFinalMlflowMetrics(runId, metricKeys, exporter)
+  const uniquePrompts = []
+  for (const prompt of prompts) {
+    if (!uniquePrompts.some((p) => p.version === prompt.version && p.name === prompt.name)) {
+      uniquePrompts.push(prompt)
+    }
+  }
+  if (uniquePrompts.length)
+    await exporter.linkPromptVersionsToRun(runId, uniquePrompts).catch(() => {})
+  await exporter.closeRun(runId)
 }
 
 // Log a flat metrics object; null/undefined values are skipped.
-export async function logMlflowMetrics(runId, metrics) {
+export async function logMlflowMetrics({ mlflowRunId: runId, metricKeys }, metrics) {
   if (!runId) return
+  metricKeys ??= new Set()
+  for (const [key, value] of Object.entries(metrics)) {
+    if (value != null) metricKeys.add(key)
+  }
   const exporter = getMlflowExporter()
   if (!exporter) return
   await Promise.allSettled(
@@ -26,6 +45,42 @@ export async function logMlflowMetrics(runId, metrics) {
   )
 }
 
+export async function logMlflowRunMetadata(runId, metadata, exporter = getMlflowExporter()) {
+  if (!runId || !exporter || !metadata) return
+  const params = {
+    ...(metadata.model && { "llm.model": metadata.model }),
+    ...(metadata.provider && { "llm.provider": metadata.provider }),
+  }
+  for (const [key, value] of Object.entries(metadata.params ?? {})) {
+    if (value != null) params[`llm.param.${key}`] = _stringifyMlflowValue(value)
+  }
+
+  await Promise.allSettled(
+    Object.entries(params).map(([key, value]) => exporter.logParam(runId, key, value)),
+  )
+}
+
+const AVG_METRICS = { success_rate: 1, output_correctness: 1, latency_ms: 1 }
+
+export async function logFinalMlflowMetrics(runId, metricKeys, exporter = getMlflowExporter()) {
+  if (!runId || !exporter) return
+  const keys = Array.from(metricKeys ?? []).concat(["success_rate", "output_correctness"])
+  await Promise.allSettled(
+    keys.map(async (key) => {
+      const history = await exporter.getMetricHistory(runId, key)
+      const values = history
+        .filter((metric) => metric?.step !== 1)
+        .map((metric) => Number(metric?.value))
+        .filter(Number.isFinite)
+      if (!values.length) return
+
+      const total = values.reduce((sum, value) => sum + value, 0)
+      const aggregate = AVG_METRICS[key] ? total / values.length : total
+      await exporter.logMetric(runId, key, aggregate, { step: 1 })
+    }),
+  )
+}
+
 export async function postMlflowAssessment(
   traceId,
   score,
@@ -36,3 +91,27 @@ export async function postMlflowAssessment(
 ) {
   getMlflowExporter()?.postAssessment(traceId, score, rationale, assessmentName, sourceId, opts)
 }
+
+function _stringifyMlflowValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value)
+}
+
+function isCI() {
+  return process.env.GITHUB_ACTIONS === "true"
+}
+
+async function getSourceTags() {
+  const serverUrl = process.env.GITHUB_SERVER_URL?.replace(/\/$/, "")
+  const sourceName =
+    serverUrl && process.env.GITHUB_REPOSITORY
+      ? `${serverUrl}/${process.env.GITHUB_REPOSITORY}`
+      : undefined
+  const branch = process.env.GITHUB_HEAD_REF
+  const commit = process.env.GITHUB_SHA
+  return [
+    sourceName && { key: "mlflow.source.name", value: sourceName },
+    { key: "mlflow.source.type", value: isCI() ? "JOB" : "LOCAL" },
+    branch && { key: "mlflow.source.git.branch", value: branch },
+    commit && { key: "mlflow.source.git.commit", value: commit },
+  ].filter(Boolean)
+}

package/lib/telemetry/mlflow/exporter/DatabricksExporter.js

@@ -1,6 +1,28 @@
 import { MlflowExporter } from "./MlflowExporter.js"
 
 export class DatabricksExporter extends MlflowExporter {
+  async getMetricHistory(runId, key) {
+    const metrics = []
+    let pageToken
+    do {
+      const query = new URLSearchParams({
+        run_id: runId,
+        metric_key: key,
+        max_results: 1000,
+        ...(pageToken && { page_token: pageToken }),
+      }).toString()
+      // eslint-disable-next-line no-await-in-loop
+      const data = await this._fetch(
+        `/api/2.0/mlflow/metrics/get-history?${query}`,
+        undefined,
+        "GET",
+      )
+      metrics.push(...(data?.metrics ?? []))
+      pageToken = data?.next_page_token
+    } while (pageToken)
+    return metrics
+  }
+
   async postAssessment(
     traceId,
     score,
@@ -31,15 +53,27 @@ export class DatabricksExporter extends MlflowExporter {
     })
   }
 
+  async linkPromptVersionsToRun(runId, prompts = []) {
+    if (!prompts.length) return
+    await super.linkPromptVersionsToRun(runId, prompts)
+    await this._fetch("/api/2.0/mlflow/unity-catalog/prompt-versions/links-to-runs", {
+      prompt_versions: prompts,
+      run_ids: [runId],
+    })
+  }
+
   // Returns { tags: [{key,value}], latestVersion: {version, tags} | null }.
   async ensurePrompt(name, description) {
     let res = await this._fetch(
-      `/mlflow/unity-catalog/prompts/${encodeURIComponent(name)}`,
+      `/api/2.0/mlflow/unity-catalog/prompts/${encodeURIComponent(name)}`,
       undefined,
       "GET",
     )
     if (!res) {
-      res = await this._fetch("/mlflow/unity-catalog/prompts", { name, prompt: { description } })
+      res = await this._fetch("/api/2.0/mlflow/unity-catalog/prompts", {
+        name,
+        prompt: { description },
+      })
     }
     const latestVersion = await this._getLatestUcVersion(name)
     return { tags: res?.tags ?? [], latestVersion }
@@ -47,7 +81,7 @@ export class DatabricksExporter extends MlflowExporter {
 
   async createPromptVersion(name, description, tags = [], template = "") {
     const res = await this._fetch(
-      `/mlflow/unity-catalog/prompts/${encodeURIComponent(name)}/versions`,
+      `/api/2.0/mlflow/unity-catalog/prompts/${encodeURIComponent(name)}/versions`,
       {
         prompt_version: { template, description, tags },
       },
@@ -56,7 +90,7 @@ export class DatabricksExporter extends MlflowExporter {
   }
 
   async setRegisteredModelTag(name, key, value) {
-    await this._fetch(`/mlflow/unity-catalog/prompts/${encodeURIComponent(name)}/tags`, {
+    await this._fetch(`/api/2.0/mlflow/unity-catalog/prompts/${encodeURIComponent(name)}/tags`, {
       key,
       value,
     })
@@ -65,7 +99,7 @@ export class DatabricksExporter extends MlflowExporter {
   // Returns { version, tags } of the latest UC prompt version, or null.
   async _getLatestUcVersion(name) {
     const res = await this._fetch(
-      `/mlflow/unity-catalog/prompts/${encodeURIComponent(name)}/versions/search`,
+      `/api/2.0/mlflow/unity-catalog/prompts/${encodeURIComponent(name)}/versions/search`,
       { max_results: 1 },
     )
     const pv = res?.prompt_versions?.[0]

package/lib/telemetry/mlflow/exporter/MlflowExporter.js

@@ -29,12 +29,12 @@ export class MlflowExporter {
     }
   }
 
-  async createRun(experimentId, name) {
+  async createRun(experimentId, name, tags) {
     const data = await this._fetch("/api/2.0/mlflow/runs/create", {
       experiment_id: experimentId,
       run_name: name || `eval-${new Date().toISOString()}`,
       start_time: Date.now(),
-      tags: [{ key: "mlflow.source.type", value: "LOCAL" }],
+      tags,
     })
     return data?.run?.info?.run_id ?? null
   }
@@ -47,13 +47,52 @@ export class MlflowExporter {
     })
   }
 
-  async logMetric(runId, key, value) {
+  async linkPromptVersionsToRun(runId, prompts = []) {
+    if (!prompts.length) return
+    await this._fetch("/api/2.0/mlflow/runs/set-tag", {
+      run_id: runId,
+      key: "mlflow.linkedPrompts",
+      value: JSON.stringify(prompts),
+    })
+  }
+
+  async getMetricHistory(runId, key) {
+    const metrics = []
+    let pageToken
+    do {
+      const query = new URLSearchParams({
+        run_id: runId,
+        metric_key: key,
+        max_results: 1000,
+        ...(pageToken && { page_token: pageToken }),
+      }).toString()
+      // eslint-disable-next-line no-await-in-loop
+      const data = await this._fetch(
+        `/api/2.0/mlflow/metrics/get-history?${query}`,
+        undefined,
+        "GET",
+      )
+      metrics.push(...(data?.metrics ?? []))
+      pageToken = data?.next_page_token
+    } while (pageToken)
+    return metrics
+  }
+
+  async logMetric(runId, key, value, { step = 0 } = {}) {
     await this._fetch("/api/2.0/mlflow/runs/log-metric", {
       run_id: runId,
       key,
       value,
       timestamp: Date.now(),
-      step: 0,
+      step,
+    })
+  }
+
+  async logParam(runId, key, value) {
+    await this._fetch("/api/2.0/mlflow/runs/log-parameter", {
+      run_id: runId,
+      key,
+      value: String(value),
     })
   }
 

package/lib/telemetry/mlflow/index.js

@@ -7,10 +7,4 @@ export {
   RoutingSpanProcessor,
 } from "./tracing.js"
 export { postMlflowAssessment, createEvalRun, closeEvalRun } from "./evaluation.js"
-export {
-  syncPromptVersion,
-  syncSystemPrompt,
-  resolvePromptName,
-  linkedPromptsAttr,
-  hashPrompt,
-} from "./prompts.js"
+export { syncPromptVersion, resolvePromptName, linkedPromptsAttr, hashPrompt } from "./prompts.js"

package/lib/telemetry/mlflow/prompts.js

@@ -48,23 +48,27 @@ export function linkedPromptsAttr(promptName) {
 // Extracts the SystemMessage from prepared LLM messages and syncs it to MLflow.
 export function syncSystemPrompt(messages) {
   if (!cds.env.agents?.mlflow) return
-  const srvName = cds.context?.["agent.service"]
-  if (!srvName) return
-  const sysMsg = messages?.find((m) => m.type === "system")
-  if (!sysMsg) return
+  const msg = messages[0]
+  if (!msg) return
   const text =
-    typeof sysMsg.content === "string"
-      ? sysMsg.content
-      : Array.isArray(sysMsg.content)
-        ? sysMsg.content
+    typeof msg.content === "string"
+      ? msg.content
+      : Array.isArray(msg.content)
+        ? msg.content
             .filter((b) => b?.type === "text")
             .map((b) => b.text ?? "")
             .join("")
         : null
   if (!text) return
-  const srv = cds.services[srvName]
-  if (!srv) return
-  syncPromptVersion(resolvePromptName(srv), text).catch(() => {})
+  let name = msg.name
+  if (!name) {
+    const srvName = cds.context?.["agent.service"]
+    if (!srvName) return
+    const srv = cds.services[srvName]
+    if (!srv) return
+    name = resolvePromptName(srv)
+  }
+  syncPromptVersion(name, text).catch(() => {})
 }
 
 // AGENTS.md path relative to cds.root, or srv.name when no AGENTS.md exists.

package/lib/utils/markdown.js

@@ -1,5 +1,5 @@
 import cds from "@sap/cds"
-import { slugified } from "./utils.js"
+import { effectiveDefinition, slugified } from "./utils.js"
 const { path, fs } = cds.utils
 const LOG = cds.log("agents")
 
@@ -13,13 +13,6 @@ export function serviceSourceDir(srv) {
   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.

package/lib/utils/resilience.js

@@ -40,7 +40,7 @@ export function timeout(ms = DEFAULT_TIMEOUT_MS) {
 }
 
 // Retries on 5xx / network errors; bails immediately on 4xx.
-export function retry(retries = DEFAULT_RETRIES) {
+export function retry(retries = DEFAULT_RETRIES, { shouldRetry } = {}) {
   if (retries < 0) throw new Error("Number of retries must be greater or equal to 0.")
 
   return ({ fn }) =>
@@ -50,6 +50,7 @@ export function retry(retries = DEFAULT_RETRIES) {
           return await fn(arg) // eslint-disable-line no-await-in-loop
         } catch (error) {
           const status = error?.response?.status
+          if (shouldRetry && !shouldRetry(error)) throw error
           if (status == null)
             LOG.debug("HTTP request failed without a response status. Rethrowing.")
           else if (`${status}`.startsWith("4"))

package/lib/utils/toml.js

@@ -0,0 +1,67 @@
+/**
+ * Minimal TOML parser supporting:
+ *   - bare keys and quoted keys
+ *   - string values (single- and double-quoted)
+ *   - boolean values
+ *   - standard tables ([section]) and dotted tables ([a.b])
+ *   - comments (#)
+ */
+
+export const toml = {
+  parse(src) {
+    const lines = src.split(/\r?\n/)
+    const root = {}
+    let current = root
+
+    for (let raw of lines) {
+      const line = raw.replace(/#.*$/, "").trim()
+      if (!line) continue
+
+      // table header
+      const tableMatch = line.match(/^\[([^\]]+)\]$/)
+      if (tableMatch) {
+        current = tableMatch[1]
+          .trim()
+          .split(".")
+          .reduce((obj, key) => {
+            key = key.trim()
+            if (!obj[key] || typeof obj[key] !== "object") obj[key] = {}
+            return obj[key]
+          }, root)
+        continue
+      }
+
+      // key = value
+      const kvMatch = line.match(/^([A-Za-z0-9_\-."']+)\s*=\s*(.+)$/)
+      if (!kvMatch) continue
+      const key = kvMatch[1].replace(/^['"]|['"]$/g, "")
+      const raw_val = kvMatch[2].trim()
+
+      let value
+      if (/^'''[\s\S]*'''$/.test(raw_val) || /^"""[\s\S]*"""$/.test(raw_val)) {
+        value = raw_val.slice(3, -3)
+      } else if (/^'[^']*'$/.test(raw_val)) {
+        value = raw_val.slice(1, -1)
+      } else if (/^"[^"]*"$/.test(raw_val)) {
+        value = raw_val
+          .slice(1, -1)
+          .replace(/\\n/g, "\n")
+          .replace(/\\t/g, "\t")
+          .replace(/\\"/g, '"')
+          .replace(/\\\\/g, "\\")
+      } else if (raw_val === "true") {
+        value = true
+      } else if (raw_val === "false") {
+        value = false
+      } else if (!isNaN(Number(raw_val))) {
+        value = Number(raw_val)
+      } else {
+        value = raw_val
+      }
+
+      current[key] = value
+    }
+
+    return root
+  },
+}

package/lib/utils/usage.js

@@ -0,0 +1,34 @@
+import cds from "@sap/cds"
+const NORMALIZED = Symbol.for("@cap-js/agents:additive-cache-usage-normalized")
+
+export function isAdditiveCacheUsageModel(model) {
+  const name = String(model || "")
+  return /anthropic|claude/i.test(name) || /^amazon--/i.test(name)
+}
+
+export function normalizeAdditiveCacheUsage(result) {
+  for (const message of result?.generations?.map((g) => g.message) ?? []) {
+    normalizeAdditiveCacheUsageMetadata(message?.usage_metadata)
+  }
+  return result
+}
+
+export function normalizeAdditiveCacheUsageChunk(chunk) {
+  // Avoid adjusting usage in chunks when streaming is disabled, because normalizeAdditiveCacheUsage runs as well
+  if (!cds.env.agents.streaming) return chunk
+  normalizeAdditiveCacheUsageMetadata(chunk?.message?.usage_metadata)
+  return chunk
+}
+
+function normalizeAdditiveCacheUsageMetadata(usage) {
+  if (!usage || usage[NORMALIZED]) return
+  const cache =
+    (usage.input_token_details?.cache_read ?? 0) + (usage.input_token_details?.cache_creation ?? 0)
+  if (!cache) return
+
+  usage.input_tokens += cache
+  if (usage.total_tokens != null && usage.output_tokens != null) {
+    usage.total_tokens = usage.input_tokens + usage.output_tokens
+  }
+  Object.defineProperty(usage, NORMALIZED, { value: true })
+}

package/lib/utils/utils.js

@@ -15,6 +15,38 @@ export const slugified = (name) =>
     .replace(/([a-z0-9])([A-Z])/g, (_m, c, C) => c + "-" + C)
     .toLowerCase()
 
+export function effectiveDefinition(srv) {
+  return cds.context?.model?.definitions?.[srv.name] || srv?.definition
+}
+
+/**
+ * Resolve an explicitly declared label for a CDS service (i18n label /
+ * @Common.Label / @title) — NOT the description or doc comment. Returns undefined
+ * when no label is declared, so callers can choose their own fallback.
+ */
+export function declaredServiceLabel(serviceName, locale) {
+  if (!serviceName) return undefined
+  locale = locale || cds.context?.locale || "en"
+  const model = cds.context?.model ?? cds.model
+  const def = model?.definitions?.[serviceName]
+  if (!def) return undefined
+  return (
+    cds.i18n?.labels?.at(def, locale) ||
+    resolveI18n(def["@Common.Label"], locale) ||
+    resolveI18n(def["@title"], locale) ||
+    undefined
+  )
+}
+
+/**
+ * Resolve a display label for a CDS service. Uses the declared label when
+ * available, otherwise returns the real (fully-qualified) service name unchanged.
+ */
+export function serviceLabel(serviceName, locale) {
+  if (!serviceName) return undefined
+  return declaredServiceLabel(serviceName, locale) || serviceName
+}
+
 export function getDescription(obj, locale) {
   locale = locale || cds.context?.locale || "en"
 
@@ -40,6 +72,16 @@ export function getDescription(obj, locale) {
   return result || undefined
 }
 
+/**
+ * Classify an (unprefixed) MCP tool name into a status-update kind:
+ * "query" (read), "describe" (model introspection), or "action" (everything else).
+ */
+export function mcpToolKind(rawName) {
+  if (rawName === "query" || rawName.endsWith("_query")) return "query"
+  if (rawName === "describe" || rawName.endsWith("_describe")) return "describe"
+  return "call"
+}
+
 /**
  * Sanitize an agent name into a valid LangChain/LLM tool name.
  */
@@ -67,7 +109,7 @@ export function short(id) {
  * Never blocks execution. Logs warning on failure.
  */
 export function audit(event, data) {
-  if (!cds.requires["audit-log"]) return
+  if (!cds.env.requires["audit-log"]) return
   cds.connect
     .to("audit-log")
     .then((a) =>

package/package.json

@@ -1,14 +1,34 @@
 {
   "name": "@cap-js/agents",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "CDS plugin for building agents",
-  "author": "SAP SE (https://www.sap.com)",
-  "license": "Apache-2.0",
   "homepage": "https://cap.cloud.sap/",
+  "license": "Apache-2.0",
+  "author": "SAP SE (https://www.sap.com)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cap-js/agents.git"
   },
+  "workspaces": [
+    "tests/projects/bookshop/",
+    "tests/projects/deep-agent/",
+    "tests/projects/mtx/mtx/sidecar/",
+    "tests/projects/telemetry-debug/",
+    "tests/projects/telemetry-v1/",
+    "tests/projects/travel/travel-agent/",
+    "tests/projects/travel/xflights/",
+    "tests/projects/travel/leisure-services/",
+    "tests/sidecar-projects/java-bookshop/agent/sidecar",
+    "tests/sidecar-projects/java-bookshop",
+    "tests/sidecar-projects/node-bookshop/agent/sidecar",
+    "tests/sidecar-projects/node-bookshop"
+  ],
+  "files": [
+    "cds-plugin.js",
+    "lib",
+    "srv",
+    "_i18n"
+  ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -30,15 +50,9 @@
     "watch:deep-agent": "cds w tests/projects/deep-agent --profile hybrid",
     "docs:audit": "node .scripts/generate-audit-docs.js",
     "docs:audit:check": "node .scripts/generate-audit-docs.js --check",
-    "prettier": "npx -y prettier@3 --write .",
-    "prettier:check": "npx -y prettier@3 --check ."
+    "format": "npx -y oxfmt@0.70.0",
+    "format:check": "npx -y oxfmt@0.70.0 --check"
   },
-  "files": [
-    "cds-plugin.js",
-    "lib",
-    "srv",
-    "_i18n"
-  ],
   "dependencies": {
     "@a2a-js/sdk": "^0.3.12",
     "@cap-js/attachments": ">=3",
@@ -47,6 +61,7 @@
     "@langchain/core": "^1",
     "@langchain/langgraph": "^1",
     "@langchain/mcp-adapters": "^1.1.3",
+    "@langchain/openai": "^1.5.13",
     "@sap-ai-sdk/langchain": "^2.13.0",
     "@sap-ai-sdk/orchestration": "^2.11.0",
     "@sap-cloud-sdk/connectivity": "^4.7.0",
@@ -61,6 +76,7 @@
     "@cap-js/sqlite": "^3",
     "@sap/cds-mtxs": "^4",
     "@toon-format/toon": ">=2.3",
+    "@vitest/coverage-v8": "^5.0.1",
     "acorn": "^8.18.0",
     "deepagents": "^1.10.2",
     "openevals": "^0.2.0"
@@ -186,6 +202,9 @@
         "anthropic": {
           "impl": "@cap-js/agents/lib/models/anthropic"
         },
+        "openai": {
+          "impl": "@cap-js/agents/lib/models/openai"
+        },
         "llm-mock": {
           "impl": "@cap-js/agents/lib/models/mock"
         }
@@ -222,19 +241,5 @@
     "folders": {
       "srvs": "srv/*"
     }
-  },
-  "workspaces": [
-    "tests/projects/bookshop/",
-    "tests/projects/deep-agent/",
-    "tests/projects/mtx/mtx/sidecar/",
-    "tests/projects/telemetry-debug/",
-    "tests/projects/telemetry-v1/",
-    "tests/projects/travel/travel-agent/",
-    "tests/projects/travel/xflights/",
-    "tests/projects/travel/leisure-services/",
-    "tests/sidecar-projects/java-bookshop/agent/sidecar",
-    "tests/sidecar-projects/java-bookshop",
-    "tests/sidecar-projects/node-bookshop/agent/sidecar",
-    "tests/sidecar-projects/node-bookshop"
-  ]
+  }
 }

package/srv/handlers/graph-executor/crash-handler.js

@@ -0,0 +1,47 @@
+import cds from "@sap/cds"
+
+const LOG = cds.log("agents")
+
+// REVISIT: Check if in the future tasks can be picked up again after restart
+async function markActiveTasksFailed() {
+  const tasksByTenant = new Map()
+
+  for (const executor of registerShutdownHook.executors) {
+    for (const taskId of executor._abortControllers.keys()) {
+      const tenant = executor._taskTenants.get(taskId)
+      const taskIds = tasksByTenant.get(tenant) || []
+      taskIds.push(taskId)
+      tasksByTenant.set(tenant, taskIds)
+    }
+  }
+
+  await Promise.all(
+    [...tasksByTenant].map(async ([tenant, taskIds]) => {
+      const update = () =>
+        UPDATE("cap.agent.Tasks")
+          .where({
+            taskId: { in: [...new Set(taskIds)] },
+            state: { in: ["submitted", "working", "input-required"] },
+          })
+          .set({ state: "failed" })
+
+      if (tenant) return cds.spawn({ tenant, user: cds.User.privileged }, update)
+      return update()
+    }),
+  )
+}
+
+export function registerShutdownHook(executor) {
+  registerShutdownHook.executors.add(executor)
+  if (registerShutdownHook.executors.size > 1) return
+
+  cds.on("shutdown", async () => {
+    try {
+      await markActiveTasksFailed()
+    } catch (err) {
+      LOG.error("Failed to mark active tasks as failed during shutdown", { error: err.message })
+    }
+  })
+}
+
+registerShutdownHook.executors = new Set()