@cap-js/agents 0.0.0 → 0.9.2

package/lib/agents/middleware/hitl-edit-note-injector.js

@@ -0,0 +1,18 @@
+import { createMiddleware } from "langchain"
+import { HumanMessage } from "@langchain/core/messages"
+import { z } from "zod"
+
+// Injects a HumanMessage for a pending _hitlEditNote before the next model turn.
+export function hitlEditNoteInjectorMiddleware() {
+  return createMiddleware({
+    name: "hitlEditNoteInjectorMiddleware",
+    stateSchema: z.object({ _hitlEditNote: z.string().optional() }),
+    beforeModel: async (state) => {
+      if (!state._hitlEditNote) return
+      return {
+        messages: [new HumanMessage(state._hitlEditNote)],
+        _hitlEditNote: undefined,
+      }
+    },
+  })
+}

package/lib/agents/middleware/hitl.js

@@ -0,0 +1,20 @@
+import { humanInTheLoopMiddleware as hitl } from "langchain"
+import { hitlEditNoteInjectorMiddleware } from "./hitl-edit-note-injector.js"
+
+function buildHitlInterruptMap(srv, tools = []) {
+  return tools.reduce((interruptOn, tool) => {
+    if (
+      srv.actions[tool.name]?.["@agent.hitl"] ??
+      srv.actions[tool.name]?.["@Common.IsActionCritical"]
+    ) {
+      interruptOn[tool.name] = { allowedDecisions: ["approve", "reject", "edit"] }
+    }
+    return interruptOn
+  }, {})
+}
+
+export async function humanInTheLoopMiddleware(srv, tools) {
+  const interruptOn = buildHitlInterruptMap(srv, tools)
+  if (!Object.keys(interruptOn).length) return []
+  return [hitl({ interruptOn }), hitlEditNoteInjectorMiddleware()]
+}

package/lib/agents/middleware/index.js

@@ -0,0 +1,19 @@
+export default async function buildMiddleware(srv, options = {}) {
+  const { tools, model } = options
+  const { quotaEnforcerMiddleware } = await import("./quota-enforcer.js")
+  const { contentFilterMiddleware } = await import("./content-filter.js")
+  const { agentActionsMiddleware } = await import("./agent-actions.js")
+  const { patchToolCallsMiddleware } = await import("./patch-tool-calls.js")
+  const { statusUpdateMiddleware } = await import("./status-update.js")
+  const { humanInTheLoopMiddleware } = await import("./hitl.js")
+  const { toolSelectionMiddleware } = await import("./tool-selection.js")
+  return [
+    ...(await quotaEnforcerMiddleware()),
+    await contentFilterMiddleware(model),
+    await agentActionsMiddleware(),
+    patchToolCallsMiddleware(),
+    await statusUpdateMiddleware(),
+    ...(await humanInTheLoopMiddleware(srv, tools)),
+    toolSelectionMiddleware(),
+  ].filter(Boolean)
+}

package/lib/agents/middleware/patch-tool-calls.js

@@ -0,0 +1,51 @@
+import { createMiddleware } from "langchain"
+import { AIMessage, ToolMessage } from "@langchain/core/messages"
+
+/**
+ * Middleware that patches dangling tool calls before each model call.
+ *
+ * When a task is interrupted mid-flight (quota exceeded, timeout, or cancellation),
+ * the checkpoint history may end with an AIMessage containing tool_calls that were
+ * never executed — no matching ToolMessage was written because the tools node never
+ * ran. On the next turn, sending this history to the LLM causes a 400 error (e.g.
+ * AI Core, Anthropic) because providers enforce strict tool_call / tool_result parity.
+ *
+ */
+export function patchToolCallsMiddleware() {
+  return createMiddleware({
+    name: "customPatchToolCallsMiddleware", // deepagents have their own middleware with the same name
+    wrapModelCall: async (request, handler) => {
+      const messages = request.messages
+      if (!messages?.length) return handler(request)
+
+      const patched = []
+      let needsPatch = false
+
+      for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i]
+        patched.push(msg)
+
+        if (AIMessage.isInstance(msg) && msg.tool_calls?.length) {
+          for (const tc of msg.tool_calls) {
+            const hasResponse = messages
+              .slice(i + 1)
+              .some((m) => ToolMessage.isInstance(m) && m.tool_call_id === tc.id)
+
+            if (!hasResponse) {
+              needsPatch = true
+              patched.push(
+                new ToolMessage({
+                  content: `Tool call ${tc.name} was cancelled before it could complete.`,
+                  name: tc.name,
+                  tool_call_id: tc.id,
+                }),
+              )
+            }
+          }
+        }
+      }
+
+      return handler(needsPatch ? { ...request, messages: patched } : request)
+    },
+  })
+}

package/lib/agents/middleware/quota-enforcer.js

@@ -0,0 +1,94 @@
+import cds from "@sap/cds"
+import { audit } from "../../utils/utils.js"
+import { createMiddleware } from "langchain"
+import { AIMessage } from "@langchain/core/messages"
+import { z } from "zod"
+
+/**
+ * Quota enforcement middleware for deep agents.
+ * Reads limits from cds.env.agents.pool at check time (not creation time).
+ * Returns array to spread into middleware config.
+ */
+export async function quotaEnforcerMiddleware() {
+  return [
+    createMiddleware({
+      name: "agentQuotaEnforcerMiddleware",
+      stateSchema: z.object({
+        runModelCallCount: z.number().default(0),
+        runTokenCount: z.number().default(0),
+        runToolCallCount: z.number().default(0),
+      }),
+      afterModel: {
+        canJumpTo: ["end"],
+        hook: (state) => {
+          const pool = cds.env.agents?.pool || {}
+          const newCallCount = state.runModelCallCount + 1
+
+          // Check LLM invocation limit
+          if (pool.maxLLMInvocationsPerTask && newCallCount > pool.maxLLMInvocationsPerTask) {
+            const reason = `LLM call limit exceeded: ${newCallCount} calls (max ${pool.maxLLMInvocationsPerTask} per task)`
+            audit("QuotaExceeded", {
+              data: {
+                service: cds.context?.["agent.service"],
+                user: cds.context?.user?.id,
+                reason,
+                taskId: cds.context?.["agent.task.id"],
+              },
+            })
+            const err = new Error(reason)
+            err.quotaExceeded = true
+            throw err
+          }
+
+          // Accumulate token usage
+          const lastAI = [...state.messages].reverse().find(AIMessage.isInstance)
+          const usage = lastAI?.usage_metadata
+          const consumed = (usage?.input_tokens || 0) + (usage?.output_tokens || 0)
+          const newTokenCount = state.runTokenCount + consumed
+
+          // Check token limit
+          if (pool.maxLLMTokensPerTask && newTokenCount > pool.maxLLMTokensPerTask) {
+            const reason = `Token limit exceeded: ${newTokenCount} tokens (max ${pool.maxLLMTokensPerTask} per task)`
+            audit("QuotaExceeded", {
+              data: {
+                service: cds.context?.["agent.service"],
+                user: cds.context?.user?.id,
+                reason,
+                taskId: cds.context?.["agent.task.id"],
+              },
+            })
+            const err = new Error(reason)
+            err.quotaExceeded = true
+            throw err
+          }
+
+          // Count tool calls from latest AI message
+          const toolCalls = lastAI?.tool_calls?.length || 0
+          const newToolCallCount = state.runToolCallCount + toolCalls
+
+          // Check tool call limit
+          if (pool.maxToolCallsPerTask && newToolCallCount > pool.maxToolCallsPerTask) {
+            const reason = `Tool call limit exceeded: ${newToolCallCount} calls (max ${pool.maxToolCallsPerTask} per task)`
+            audit("QuotaExceeded", {
+              data: {
+                service: cds.context?.["agent.service"],
+                user: cds.context?.user?.id,
+                reason,
+                taskId: cds.context?.["agent.task.id"],
+              },
+            })
+            const err = new Error(reason)
+            err.quotaExceeded = true
+            throw err
+          }
+
+          return {
+            runModelCallCount: newCallCount,
+            runTokenCount: newTokenCount,
+            runToolCallCount: newToolCallCount,
+          }
+        },
+      },
+    }),
+  ]
+}

package/lib/agents/middleware/status-update.js

@@ -0,0 +1,153 @@
+import cds from "@sap/cds"
+import { createMiddleware } from "langchain"
+import { ToolMessage } from "@langchain/core/messages"
+
+/**
+ * Resolves a human-readable label for a tool call.
+ *
+ * - query tool → resolves entity label from CDS model: @Common.Label, @title, or i18n
+ * - actions → resolves label from action definition
+ * - fallback → tool name as-is
+ */
+function resolveToolLabel(tc) {
+  const serviceName = cds.context?.["agent.service"]
+  const srv = serviceName && cds.services?.[serviceName]
+  const model = cds.context?.model ?? cds.model
+
+  // Query tool: extract entity target and resolve its label
+  if (tc.name === "query" || tc.name?.endsWith("_query")) {
+    let entityName = tc.args?.entity ? `${serviceName}.${tc.args.entity}` : undefined
+
+    // SQL format: no entity arg — parse SQL to extract FROM target
+    if (!entityName && tc.args?.cql) {
+      try {
+        const cqn = cds.parse.cql(tc.args.cql)
+        const ref0 = cqn.SELECT?.from?.ref?.[0]
+        const targetName = ref0?.id ?? ref0
+        if (targetName && serviceName && !targetName.startsWith(serviceName + ".")) {
+          entityName = `${serviceName}.${targetName}`
+        } else {
+          entityName = targetName
+        }
+      } catch {
+        /* fallback to tc.name below */
+      }
+    }
+    if (entityName) {
+      const entityDef = model.definitions?.[entityName]
+      if (entityDef) {
+        const label = cds.i18n?.labels?.at(entityDef)
+        if (label) return label
+      }
+    }
+    // Fallback: strip service prefix if present
+    if (entityName && srv?.name && entityName.startsWith(srv.name + ".")) {
+      return entityName.slice(srv.name.length + 1)
+    }
+    return entityName || tc.name
+  }
+
+  // Action/function tools: resolve from service definition
+  if (srv) {
+    // Try as action on service
+    const actionDef = model.definitions[`${srv.name}.${tc.name}`]
+    if (actionDef) {
+      const label = cds.i18n?.labels?.at(actionDef)
+      if (label) return label
+    }
+  }
+
+  return tc.name
+}
+
+/**
+ * Publishes a non-final "working" status-update to the eventBus.
+ */
+function publishStatus(text) {
+  const eventBus = cds.context?.["agent.eventBus"]
+  if (!eventBus || !text) return
+
+  eventBus.publish({
+    kind: "status-update",
+    taskId: cds.context["agent.task.id"],
+    contextId: cds.context["agent.context.id"],
+    status: {
+      state: "working",
+      message: {
+        kind: "message",
+        messageId: cds.utils.uuid(),
+        role: "agent",
+        parts: [{ kind: "text", text }],
+      },
+      timestamp: new Date().toISOString(),
+    },
+    final: false,
+  })
+}
+
+/**
+ * beforeModel hook: emit "Processing tool response" when tools just finished.
+ */
+export function beforeModelHook(state) {
+  if (!cds.context?.["agent.eventBus"]) return {}
+
+  const msgs = state.messages
+  if (!msgs?.length) return {}
+  const lastMsg = msgs[msgs.length - 1]
+  if (!ToolMessage.isInstance(lastMsg)) return {}
+
+  // Plural if second-to-last is also a ToolMessage
+  const plural = msgs.length >= 2 && ToolMessage.isInstance(msgs[msgs.length - 2])
+  const key = plural ? "agent_status_processing_responses" : "agent_status_processing_response"
+  const text = cds.i18n.messages.at(key)
+  publishStatus(text)
+
+  return {}
+}
+
+/**
+ * afterModel hook: emit tool-call status updates (querying/calling).
+ */
+export function afterModelHook(state) {
+  if (!cds.context?.["agent.eventBus"]) return {}
+
+  const msgs = state.messages
+  if (!msgs?.length) return {}
+
+  const lastAI = msgs[msgs.length - 1]
+  const toolCalls = lastAI?.tool_calls
+  if (!toolCalls?.length) return {}
+
+  // Separate query calls from action calls
+  const queryCalls = toolCalls.filter((tc) => tc.name === "query" || tc.name?.endsWith("_query"))
+  const otherCalls = toolCalls.filter((tc) => tc.name !== "query" && !tc.name?.endsWith("_query"))
+
+  // Emit "Querying {entities}" for query tools
+  if (queryCalls.length) {
+    const labels = queryCalls.map((tc) => resolveToolLabel(tc))
+    const text = cds.i18n.messages.at("agent_status_querying", [labels.join(", ")])
+    publishStatus(text)
+  }
+
+  // Emit "Calling {action labels}" for other tools
+  if (otherCalls.length) {
+    const labels = otherCalls.map((tc) => resolveToolLabel(tc))
+    const text = cds.i18n.messages.at("agent_status_calling_tools", [labels.join(", ")])
+    publishStatus(text)
+  }
+
+  return {}
+}
+
+/**
+ * Middleware factory that emits non-final status-update events during agent execution:
+ * - beforeModel: "Processing tool response" after tools finish
+ * - afterModel:  "Querying <entity>" / "Calling <action>" before tools are invoked
+ */
+export async function statusUpdateMiddleware() {
+  return createMiddleware({
+    name: "statusUpdateMiddleware",
+    beforeModel: { hook: beforeModelHook },
+    afterModel: { hook: afterModelHook },
+  })
+}

package/lib/agents/middleware/tool-selection.js

@@ -0,0 +1,22 @@
+import { createMiddleware } from "langchain"
+
+/**
+ * Middleware that filters the tool list passed to the model on every call.
+ * The graph is cached once with all tools; this middleware trims it to the
+ * subset the current user is authorized to see (checkAuthorization runs per-request).
+ *
+ * Tools with an isAllowed() method (GenericReadTool, DescribeTool, etc.) are dropped
+ * when the method returns false. Their description and schema getters return
+ * auth-filtered content dynamically, so the model always sees only what the user
+ * can access — no new instances, no renamed tools.
+ */
+export function toolSelectionMiddleware() {
+  return createMiddleware({
+    name: "ToolSelectionMiddleware",
+    wrapModelCall: (request, handler) => {
+      if (!request.tools?.length) return handler(request)
+      const tools = request.tools.filter((t) => (t.isAllowed ? t.isAllowed() : true))
+      return handler({ ...request, tools })
+    },
+  })
+}

package/lib/agents/quota-enforcer-at-start.js

@@ -0,0 +1,198 @@
+import cds from "@sap/cds"
+
+const LOG = cds.log("agents")
+
+const tasks = () => cds.model.definitions["cap.agent.Tasks"]
+
+function secondsUntilNextHour() {
+  const now = new Date()
+  const next = new Date(now)
+  next.setUTCMinutes(0, 0, 0)
+  next.setUTCHours(next.getUTCHours() + 1)
+  return Math.ceil((next - now) / 1000)
+}
+
+function secondsUntilMidnightUTC() {
+  const now = new Date()
+  const midnight = new Date(now)
+  midnight.setUTCHours(24, 0, 0, 0)
+  return Math.ceil((midnight - now) / 1000)
+}
+
+/**
+ * Quota enforcement before graph execution.
+ * Returns null if within limits, or { message, retryAfter } if a limit is breached.
+ */
+export default async function quotaEnforcerAtStart() {
+  const pool = cds.env.agents?.pool
+  if (!pool) {
+    LOG.debug(
+      "No quota pool configuration found at cds.env.agents.pool — quota enforcement disabled",
+    )
+    return null
+  }
+
+  // REVISIT: If applications ask for it, add agent quota annotations which allow to enforce agent service specific quotas.
+  // Keep extensibility in mind that customers then would not be able to override own limits.
+  const lastHour = new Date(Date.now() - 60 * 60 * 1000)
+  const today = new Date()
+  today.setUTCHours(0, 0, 0, 0)
+
+  const userId = cds.context?.user?.id
+
+  const [
+    {
+      concurrentTasks,
+      lastHourTasks,
+      concurrentTasksThisUser,
+      lastHourTasksThisUser,
+      lastHourToolCalls,
+    },
+    { llmTokensThisDay },
+  ] = await Promise.all([
+    SELECT.one
+      .from(tasks())
+      .columns(
+        concurrentTasksCol,
+        "count(*) as lastHourTasks",
+        concurrentTasksThisUserColFactory(userId),
+        lastHourTasksThisUserColFactory(userId),
+        "coalesce(sum(usageToolCalls), 0) as lastHourToolCalls",
+      )
+      .where({ createdAt: { ">=": lastHour.toISOString() } }),
+    SELECT.one
+      .from(tasks())
+      .columns("coalesce(sum(usageLlmTokens),0) as llmTokensThisDay")
+      .where({ createdAt: { ">=": today.toISOString() } }),
+  ])
+  if (pool.maxConcurrentTasks != null && concurrentTasks >= pool.maxConcurrentTasks) {
+    return {
+      message: cds.i18n.messages.at("QUOTA_CONCURRENT_TASKS", [pool.maxConcurrentTasks]),
+      retryAfter: 30,
+    }
+  }
+  if (
+    pool.maxConcurrentTasksPerUser != null &&
+    concurrentTasksThisUser >= pool.maxConcurrentTasksPerUser
+  ) {
+    return {
+      message: cds.i18n.messages.at("QUOTA_CONCURRENT_TASKS_PER_USER", [
+        pool.maxConcurrentTasksPerUser,
+      ]),
+      retryAfter: 30,
+    }
+  }
+  if (pool.maxTasksPerHour != null && lastHourTasks >= pool.maxTasksPerHour) {
+    return {
+      message: cds.i18n.messages.at("QUOTA_TASKS_PER_HOUR", [pool.maxTasksPerHour]),
+      retryAfter: secondsUntilNextHour(),
+    }
+  }
+  if (pool.maxTasksPerHourPerUser != null && lastHourTasksThisUser >= pool.maxTasksPerHourPerUser) {
+    return {
+      message: cds.i18n.messages.at("QUOTA_TASKS_PER_HOUR_PER_USER", [pool.maxTasksPerHourPerUser]),
+      retryAfter: secondsUntilNextHour(),
+    }
+  }
+  if (pool.maxToolCallsPerHour != null && lastHourToolCalls >= pool.maxToolCallsPerHour) {
+    return {
+      message: cds.i18n.messages.at("QUOTA_TOOL_CALLS_PER_HOUR", [pool.maxToolCallsPerHour]),
+      retryAfter: secondsUntilNextHour(),
+    }
+  }
+  if (pool.maxLLMTokensPerDay != null && llmTokensThisDay >= pool.maxLLMTokensPerDay) {
+    return {
+      message: cds.i18n.messages.at("QUOTA_LLM_TOKENS_PER_DAY", [pool.maxLLMTokensPerDay]),
+      retryAfter: secondsUntilMidnightUTC(),
+    }
+  }
+  return null
+}
+
+const concurrentTasksCol = {
+  func: "coalesce",
+  args: [
+    {
+      func: "sum",
+      args: [
+        {
+          xpr: [
+            "case",
+            "when",
+            { ref: ["state"] },
+            "in",
+            { list: [{ val: "submitted" }, { val: "working" }, { val: "input-required" }] },
+            "then",
+            { val: 1, param: false },
+            "else",
+            { val: 0, param: false },
+            "end",
+          ],
+          cast: { type: "cds.Integer" },
+        },
+      ],
+    },
+    { val: 0 },
+  ],
+  as: "concurrentTasks",
+}
+
+const concurrentTasksThisUserColFactory = (userId) => ({
+  func: "coalesce",
+  args: [
+    {
+      func: "sum",
+      args: [
+        {
+          xpr: [
+            "case",
+            "when",
+            { ref: ["createdBy"] },
+            "=",
+            { val: userId },
+            "and",
+            { ref: ["state"] },
+            "in",
+            { list: [{ val: "submitted" }, { val: "working" }, { val: "input-required" }] },
+            "then",
+            { val: 1, param: false },
+            "else",
+            { val: 0, param: false },
+            "end",
+          ],
+          cast: { type: "cds.Integer" },
+        },
+      ],
+    },
+    { val: 0 },
+  ],
+  as: "concurrentTasksThisUser",
+})
+
+const lastHourTasksThisUserColFactory = (userId) => ({
+  func: "coalesce",
+  args: [
+    {
+      func: "sum",
+      args: [
+        {
+          xpr: [
+            "case",
+            "when",
+            { ref: ["createdBy"] },
+            "=",
+            { val: userId },
+            "then",
+            { val: 1, param: false },
+            "else",
+            { val: 0, param: false },
+            "end",
+          ],
+          cast: { type: "cds.Integer" },
+        },
+      ],
+    },
+    { val: 0 },
+  ],
+  as: "lastHourTasksThisUser",
+})

package/lib/agents/summarize-on-timeout.js

@@ -0,0 +1,91 @@
+import cds from "@sap/cds"
+import { HumanMessage } from "@langchain/core/messages"
+import { short } from "../utils/utils.js"
+
+const LOG = cds.log("agents")
+
+const DEFAULT_TIMEOUT = 10_000
+
+/**
+ * Summarize partial work from a graph execution that was interrupted
+ * (timeout, quota exceeded, or other forced stop).
+ *
+ * Reads partial conversation from the checkpoint and asks the LLM to
+ * produce a concise progress summary. Falls back to a generic message
+ * on any failure (no checkpointer, empty state, LLM unreachable).
+ *
+ * @param {object} options
+ * @param {string} options.contextId
+ * @param {string} options.serviceName
+ * @param {string} options.reason - Why execution was interrupted (e.g. "timed out", "quota exceeded")
+ * @param {object} [options.checkpointer] - LangGraph checkpointer instance
+ * @param {Function} options.getModel - Async function returning a LangChain chat model
+ * @param {number} [options.timeout] - Max ms to spend on summarization (default 10s)
+ * @returns {Promise<string>} Summary message or fallback
+ */
+export async function summarizePartialWork({
+  contextId,
+  serviceName,
+  reason,
+  checkpointer,
+  getModel,
+  timeout = DEFAULT_TIMEOUT,
+}) {
+  const fallback = `The task was stopped (${reason}). Some work may have been done — please check the results or retry with a simpler request.`
+
+  try {
+    if (!getModel) return fallback
+    if (!checkpointer?.getTuple) return fallback
+
+    const cp = await checkpointer.getTuple({
+      configurable: { thread_id: `${serviceName}:${contextId}` },
+    })
+    const messages = cp?.checkpoint?.channel_values?.messages
+    if (!messages?.length) return fallback
+
+    // Extract last few messages as context for summarization (cap at 10)
+    const recentMessages = messages.slice(-10)
+    const conversationSnippet = recentMessages
+      .map((m) => {
+        const role = m._getType?.() || m.type || "unknown"
+        const content = typeof m.content === "string" ? m.content : JSON.stringify(m.content)
+        return `[${role}]: ${content?.slice(0, 500)}`
+      })
+      .join("\n")
+    const summaryPrompt = `The following agent task was interrupted (${reason}). Based on the conversation so far, provide a brief summary of what was accomplished and what remains. Be concise.
+
+Conversation:
+${conversationSnippet}`
+
+    let summaryTimer
+    try {
+      const response = await Promise.race([
+        (async () => {
+          const model = await getModel()
+          return model.invoke([new HumanMessage(summaryPrompt)])
+        })(),
+        new Promise((_, reject) => {
+          summaryTimer = setTimeout(() => reject(new Error("Summary LLM call timed out")), timeout)
+        }),
+      ])
+
+      const summary =
+        typeof response.content === "string" ? response.content : JSON.stringify(response.content)
+
+      LOG.info("partial work summary generated", {
+        conversation: short(contextId),
+        service: serviceName,
+        reason,
+      })
+      return `Task stopped (${reason}). Progress summary: ${summary}`
+    } finally {
+      clearTimeout(summaryTimer)
+    }
+  } catch (err) {
+    LOG.debug("partial work summary failed, using fallback", {
+      conversation: short(contextId),
+      error: err.message,
+    })
+    return fallback
+  }
+}