@cap-js/agents 0.9.3 → 0.9.4

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

@@ -0,0 +1,18 @@
+import { createMiddleware } from "langchain"
+import { HumanMessage } from "@langchain/core/messages"
+import { z } from "zod"
+
+// Injects user HITL decisions before the model continues after a rejection or edit.
+export function hitlDecisionNoteInjectorMiddleware() {
+  return createMiddleware({
+    name: "hitlDecisionNoteInjectorMiddleware",
+    stateSchema: z.object({ _hitlDecisionNote: z.string().optional() }),
+    beforeModel: async (state) => {
+      if (!state._hitlDecisionNote) return
+      return {
+        messages: [new HumanMessage(state._hitlDecisionNote)],
+        _hitlDecisionNote: undefined,
+      }
+    },
+  })
+}

package/lib/agents/middleware/hitl.js

@@ -1,5 +1,5 @@
 import { humanInTheLoopMiddleware as hitl } from "langchain"
-import { hitlEditNoteInjectorMiddleware } from "./hitl-edit-note-injector.js"
+import { hitlDecisionNoteInjectorMiddleware } from "./hitl-decision-note-injector.js"
 
 function buildHitlInterruptMap(srv, tools = []) {
   return tools.reduce((interruptOn, tool) => {
@@ -16,5 +16,5 @@ function buildHitlInterruptMap(srv, tools = []) {
 export async function humanInTheLoopMiddleware(srv, tools) {
   const interruptOn = buildHitlInterruptMap(srv, tools)
   if (!Object.keys(interruptOn).length) return []
-  return [hitl({ interruptOn }), hitlEditNoteInjectorMiddleware()]
+  return [hitl({ interruptOn }), hitlDecisionNoteInjectorMiddleware()]
 }

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

@@ -89,6 +89,15 @@ export async function quotaEnforcerMiddleware() {
           }
         },
       },
+      afterAgent: {
+        hook: () => {
+          return {
+            runModelCallCount: 0,
+            runTokenCount: 0,
+            runToolCallCount: 0,
+          }
+        },
+      },
     }),
   ]
 }

package/lib/models/anthropic.js

@@ -5,6 +5,7 @@ import os from 'node:os'
 import cds from '@sap/cds'
 
 const HOME = os.homedir() || process.env.HOME || process.env.USERPROFILE
+const local = file => file.replace(HOME,'~')
 const LOG = cds.log('agents')
 
 /**
@@ -15,27 +16,36 @@ const LOG = cds.log('agents')
  */
 export default class ChatAnthropicService extends ChatAnthropic {
   constructor (name, options) {
-    // REVISIT: may be better handled via options.credentials?
-    let config = { ...options, ...fromEnv() }
+    let config = { ...options, ...options?.credentials, ...fromEnv() }
     if (!config.anthropicApiUrl) config = {
       ...fromClaude() || fromOpencode(),
       ...config
     }
-    LOG.debug (`Using effective config for ChatAnthropic:`, config)
+    if (LOG._debug) {
+      const { kind, model, anthropicApiUrl, apiKey } = config
+      LOG.info (`Using effective config:`, {
+        kind,
+        model,
+        credentials: {
+          anthropicApiUrl,
+          apiKey: apiKey ? '***' : undefined
+        }
+      })
+    }
     super (config)
     this.name = name
     this.options = config
   }
 }
 
-function fromEnv (env = process.env) {
+function fromEnv (env = process.env, silent) {
   let any, config = {}
   if ((any = env.ANTHROPIC_BASE_URL)) config.anthropicApiUrl = any
   if ((any = env.ANTHROPIC_AUTH_TOKEN)) config.apiKey = any
   if ((any = env.ANTHROPIC_API_KEY)) config.apiKey = any
   if ((any = env.ANTHROPIC_MODEL)) config.model = any
   if (!Object.keys(config).length) return null
-  LOG.debug (`Loaded Anthropic settings from env:`, config)
+  if (!silent) LOG.debug (`Loaded Anthropic settings from env:`, config)
   return config
 }
 
@@ -43,12 +53,17 @@ function fromClaude() {
   if ('cached' in fromClaude) return fromClaude.cached
   const settings_json = path.join (HOME,'.claude/settings.json')
   try {
-    let conf = JSON.parse (fs.readFileSync (settings_json,'utf8'))
+    let settings = JSON.parse (fs.readFileSync (settings_json,'utf8'))
     // https://www.schemastore.org/claude-code-settings.json
-    fromClaude.cached = conf = fromEnv (conf?.env)
-    LOG.debug(`Loaded Claude settings from`, settings_json, ':', conf)
+
+    let conf = fromClaude.cached = fromEnv (settings?.env, 'silent')
+    if (!conf.model && settings.env) {
+      let family = (settings.model||'sonnet').toUpperCase()
+      conf.model = settings.env[`ANTHROPIC_DEFAULT_${family}_MODEL`] || settings?.model
+    }
+    LOG.debug(`Loaded Claude settings from`, local(settings_json), ':', conf)
   } catch {
-    LOG.debug(`Failed loading Claude settings from`, settings_json)
+    LOG.debug(`Failed loading Claude settings from`, local(settings_json))
     fromClaude.cached = null
   }
   return fromClaude.cached
@@ -59,7 +74,7 @@ function fromOpencode() {
   const opencode_json = path.join (HOME,'.config/opencode/opencode.json')
   try {
     let conf = JSON.parse (fs.readFileSync (opencode_json,'utf8'))
-    LOG.debug(`Loaded OpenCode settings from`, opencode_json)
+    LOG.debug(`Loaded OpenCode settings from`, local(opencode_json))
     // https://opencode.ai/config.json
     let o = conf?.provider?.anthropic?.options
     if (!o) return fromOpencode.cached = null
@@ -68,9 +83,9 @@ function fromOpencode() {
     if ((any = o.anthropicApiKey ?? o.apiKey)) config.apiKey = any
     if ((any = conf?.model)) config.model = any.replace('anthropic/','')
     fromOpencode.cached = Object.keys(config).length ? config : null
-    LOG.debug(`Loaded OpenCode settings from`, opencode_json, ':', conf)
+    LOG.debug(`Loaded OpenCode settings from`, local(opencode_json), ':', conf)
   } catch {
-    LOG.debug(`Failed loading OpenCode settings from`, opencode_json)
+    LOG.debug(`Failed loading OpenCode settings from`, local(opencode_json))
     fromOpencode.cached = null
   }
   return fromOpencode.cached

package/lib/preview/chat.html

@@ -115,6 +115,7 @@
         color: #1d3e5a;
         border-bottom-left-radius: 3px;
         border-left: 3px solid #537492;
+        white-space: pre-wrap;
       }
       .msg.approval::before {
         content: "Action Required";
@@ -616,7 +617,7 @@
       function flushPendingThinkingUpdate() {
         const pending = pendingThinkingUpdate
         clearPendingThinkingUpdate()
-        if (pending) renderThinkingStep(pending.artifactId, pending.text, pending.lastChunk)
+        if (pending) renderThinkingStep(pending)
       }
 
       function prefersReducedMotion() {
@@ -642,10 +643,17 @@
         else expandThinkingSummary(el)
       }
 
-      function renderThinkingStep(artifactId, text, lastChunk) {
+      function renderThinkingStep(update) {
+        const { artifactId, text, lastChunk, append } = update
         const panel = ensureThinkingSummary()
-        const isNewStep = artifactId !== currentThinkingArtifactId || currentThinkingClosed
-        if (isNewStep) {
+        const idx = thinkingStepEls.findIndex((step) => step._artifactId === artifactId)
+        if (append && idx >= 0) {
+          thinkingTexts[idx] += text
+          thinkingStepEls[idx].innerHTML = md(thinkingTexts[idx])
+        } else if (artifactId === currentThinkingArtifactId && !currentThinkingClosed) {
+          thinkingTexts[idx] += "\n" + text
+          thinkingStepEls[idx].innerHTML = md(thinkingTexts[idx])
+        } else {
           const step = document.createElement("div")
           step.className = "thinking-step"
           step._artifactId = artifactId
@@ -657,17 +665,12 @@
           updateThinkingSummaryLabel()
           currentThinkingArtifactId = artifactId
           currentThinkingClosed = false
-        } else {
-          // Append to current open step for this artifactId
-          const idx = thinkingStepEls.length - 1
-          thinkingTexts[idx] += text
-          thinkingStepEls[idx].innerHTML = md(thinkingTexts[idx])
         }
         if (lastChunk) currentThinkingClosed = true
         messages.scrollTop = messages.scrollHeight
       }
 
-      function addThinkingStep(artifactId, text, lastChunk) {
+      function addThinkingStep(artifactId, text, lastChunk, append) {
         if (
           pendingThinkingUpdate &&
           pendingThinkingUpdate.artifactId === artifactId &&
@@ -677,7 +680,7 @@
           pendingThinkingUpdate.lastChunk = lastChunk
         } else {
           flushPendingThinkingUpdate()
-          pendingThinkingUpdate = { artifactId, text, lastChunk }
+          pendingThinkingUpdate = { artifactId, text, lastChunk, append }
         }
 
         if (pendingThinkingTimer) clearTimeout(pendingThinkingTimer)
@@ -811,7 +814,7 @@
       function addApprovalPrompt(description) {
         const el = document.createElement("div")
         el.className = "msg approval"
-        el.innerHTML = md(description || "The agent requires your approval to continue.")
+        el.textContent = description || "The agent requires your approval to continue."
         const actions = document.createElement("div")
         actions.className = "approval-actions"
 
@@ -1100,7 +1103,8 @@
 
           if (event.artifact?.artifactId?.startsWith("thinking")) {
             const lastChunk = event.lastChunk ?? false
-            if (text) addThinkingStep(event.artifact.artifactId, text, lastChunk)
+            if (text)
+              addThinkingStep(event.artifact.artifactId, text, lastChunk, event.append ?? false)
             return null
           }
 

package/lib/utils/message-handling.js

@@ -1,3 +1,17 @@
+import { randomUUID } from "node:crypto"
+
+export function agentMessage(text, data, metadata) {
+  const parts = [{ kind: "text", text }]
+  if (data && typeof data === "object") parts.push({ kind: "data", data })
+  return {
+    kind: "message",
+    messageId: randomUUID(),
+    role: "agent",
+    parts,
+    ...(metadata && { metadata }),
+  }
+}
+
 /**
  * A2A message part utilities — handle both wire formats:
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js/agents",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "CDS plugin for building agents",
   "author": "SAP SE (https://www.sap.com)",
   "license": "Apache-2.0",
@@ -217,6 +217,9 @@
           "_javaHcqlCompat": true
         }
       }
+    },
+    "folders": {
+      "srvs": "srv/*"
     }
   },
   "workspaces": [

package/srv/handlers/chat.js

@@ -73,7 +73,7 @@ function toolCallsFromMessages(messages) {
   for (const msg of messages) {
     if (msg.tool_call_id && msg.type === "tool") {
       const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content)
-      resultById.set(msg.tool_call_id, content)
+      resultById.set(msg.tool_call_id, { content, ...msg })
     }
   }
 
@@ -84,14 +84,14 @@ function toolCallsFromMessages(messages) {
       const raw = resultById.get(tc.id)
       let toolResult
       try {
-        toolResult = raw !== undefined ? JSON.parse(raw) : undefined
+        toolResult = raw?.content !== undefined ? JSON.parse(raw.content) : undefined
       } catch {
-        toolResult = raw
+        toolResult = raw?.content
       }
       const entry = {
         tool: tc.name,
         args: tc.args ?? {},
-        outcome: "success",
+        outcome: raw.status,
         ...(toolResult !== undefined && { result: toolResult }),
       }
       attachCqn(entry)

package/srv/handlers/graph-executor/hitl.js

@@ -0,0 +1,263 @@
+import cds from "@sap/cds"
+import { agentMessage, firstDataPart, partsToText } from "../../../lib/utils/message-handling.js"
+import { audit, short } from "../../../lib/utils/utils.js"
+
+const LOG = cds.log("agents")
+
+export const HITL_METADATA_KEY = "sap.cds.agents.hitl"
+export const requiresHitl = (result) =>
+  result?.__interrupt__?.length > 0 || result?.interrupts?.length > 0
+
+export function parseResumeDecision(userText) {
+  const t = userText.trim()
+  if (/^(approve|yes|confirm|ok)$/i.test(t)) return { decisions: [{ type: "approve" }] }
+  if (/^edit$/i.test(t)) return { decisions: [{ type: "edit" }] }
+  return {
+    decisions: [
+      {
+        type: "reject",
+        message: `The user rejected this particular tool invocation with the reason: ${userText}`,
+      },
+    ],
+  }
+}
+
+function decisionsForAudit(resume, actionRequests = []) {
+  if (!Array.isArray(resume?.decisions)) return [{ action: null, decision: resume }]
+  return resume.decisions.map((decision, index) => ({
+    action: actionRequests[index] ?? { index: index + 1 },
+    decision,
+  }))
+}
+
+function extractInterruptDescription(resultOrErr) {
+  const interrupt = resultOrErr.__interrupt__?.[0] || resultOrErr.interrupts?.[0]
+  const payload = interrupt?.value
+  if (!payload) return "This action requires your approval. Reply 'approve' or 'reject'."
+  if (payload.actionRequests?.length > 0) {
+    return (
+      payload.actionRequests[0].description || `Approve action: ${payload.actionRequests[0].name}?`
+    )
+  }
+  return typeof payload === "string" ? payload : JSON.stringify(payload)
+}
+
+export function extractInterruptData(resultOrErr) {
+  const interrupt = resultOrErr.__interrupt__?.[0] || resultOrErr.interrupts?.[0]
+  const payload = interrupt?.value
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined
+  const actionRequests = mergeReviewConfigs(payload.actionRequests, payload.reviewConfigs)
+  return actionRequests === payload.actionRequests ? payload : { ...payload, actionRequests }
+}
+
+function mergeReviewConfigs(actionRequests, reviewConfigs) {
+  if (!Array.isArray(actionRequests) || !Array.isArray(reviewConfigs)) return actionRequests
+  const configsByAction = new Map(reviewConfigs.map((config) => [config.actionName, config]))
+  let changed = false
+  const requests = actionRequests.map((request) => {
+    const config = configsByAction.get(request.name)
+    if (!config) return request
+    changed = true
+    const { allowedDecisions, argsSchema } = config
+    return {
+      ...request,
+      ...(allowedDecisions === undefined ? {} : { allowedDecisions }),
+      ...(argsSchema === undefined ? {} : { argsSchema }),
+    }
+  })
+  return changed ? requests : actionRequests
+}
+
+function interruptActionCount(resultOrErr) {
+  const interrupts = resultOrErr.__interrupt__ || resultOrErr.interrupts || []
+  return interrupts.reduce(
+    (count, interrupt) => count + (interrupt?.value?.actionRequests?.length || 0),
+    0,
+  )
+}
+
+function interruptActionRequests(resultOrErr) {
+  const interrupts = resultOrErr.__interrupt__ || resultOrErr.interrupts || []
+  return interrupts.flatMap((interrupt) => interrupt?.value?.actionRequests || [])
+}
+
+export function composeHitlDecisionNote(actionRequests, resume) {
+  const decisions = resume?.decisions
+  if (!Array.isArray(decisions) || decisions.length === 0) return undefined
+  if (decisions.every((decision) => decision?.type === "approve")) return undefined
+  const consumed = new Set()
+  const takeByName = (name) => {
+    for (let index = 0; index < actionRequests.length; index++) {
+      if (!consumed.has(index) && actionRequests[index]?.name === name) {
+        consumed.add(index)
+        return actionRequests[index]
+      }
+    }
+    return undefined
+  }
+  const action = (request) =>
+    "`" + (request?.name ?? "unknown action") + "(" + JSON.stringify(request?.args ?? {}) + ")`"
+  const lines = []
+  for (const [index, decision] of decisions.entries()) {
+    const original = actionRequests[index]
+    if (decision?.type === "edit") {
+      const matched = takeByName(decision.editedAction?.name) ?? original
+      lines.push("- User edited " + action(matched) + " to " + action(decision.editedAction) + ".")
+      continue
+    }
+  }
+  if (!lines.length) {
+    return undefined
+  }
+  return ["User HITL decisions (not tool failures):", ...lines].join("\n")
+}
+
+async function getPreInterruptToolCalls(graph, config) {
+  try {
+    if (typeof graph.getState !== "function") return []
+    const state = await graph.getState(config)
+    const messages = state?.values?.messages ?? []
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const message = messages[i]
+      if (message?.tool_calls?.length) {
+        return message.tool_calls.map((call) => ({ id: call.id, name: call.name, args: call.args }))
+      }
+    }
+    return []
+  } catch {
+    return []
+  }
+}
+
+async function getPendingHitlActionCount(graph, config) {
+  if (typeof graph.getState !== "function") {
+    throw new Error("Cannot resume HITL: graph state is unavailable.")
+  }
+  const state = await graph.getState(config)
+  const interrupts = state?.tasks?.flatMap((task) => task.interrupts || []) || []
+  const count = interrupts.reduce(
+    (total, interrupt) => total + (interrupt?.value?.actionRequests?.length || 1),
+    0,
+  )
+  if (count < 1) throw new Error("Cannot resume HITL: no pending actions found.")
+  return count
+}
+
+function pendingHitlFromTask(task) {
+  const pending = task?.status?.message?.metadata?.[HITL_METADATA_KEY]
+  if (!Number.isInteger(pending?.actionCount) || pending.actionCount < 1) return undefined
+  if (!Array.isArray(pending.decisions)) return undefined
+  return pending
+}
+
+function pendingActionRequests(task, pending) {
+  return (
+    pending?.actionRequests || firstDataPart(task?.status?.message?.parts)?.actionRequests || []
+  )
+}
+
+function interruptDescriptionFromTask(task, pending) {
+  const action = pendingActionRequests(task, pending)[pending?.decisions?.length || 0]
+  if (action) return action.description || `Approve action: ${action.name}?`
+  return (
+    task?.status?.message?.parts?.find((part) => part.kind === "text")?.text ||
+    "This action requires your approval. Reply 'approve' or 'reject'."
+  )
+}
+
+function publishInputRequired({ requestContext, eventBus, description, interruptData, pending }) {
+  const { taskId, contextId } = requestContext
+  eventBus.publish({
+    kind: "status-update",
+    taskId,
+    contextId,
+    status: {
+      state: "input-required",
+      message: agentMessage(description, interruptData, { [HITL_METADATA_KEY]: pending }),
+      timestamp: new Date().toISOString(),
+    },
+    final: true,
+  })
+  eventBus.finished()
+}
+
+export async function resumeHitl({ requestContext, graph, config, eventBus, stream, signal }) {
+  const { taskId, contextId } = requestContext
+  const dataPart = firstDataPart(requestContext.userMessage?.parts)
+  const userText = partsToText(requestContext.userMessage?.parts)
+  if (dataPart === undefined && !userText.trim()) {
+    throw new Error(cds.i18n.messages.at("RESUME_REQUIRES_TEXT"))
+  }
+  const { Command } = await import("@langchain/langgraph")
+  let resume = dataPart !== undefined ? dataPart : parseResumeDecision(userText)
+  let actionRequests = []
+
+  if (Array.isArray(resume?.decisions)) {
+    const pending = pendingHitlFromTask(requestContext.task)
+    const actionCount = pending?.actionCount ?? (await getPendingHitlActionCount(graph, config))
+    actionRequests = pendingActionRequests(requestContext.task, pending)
+    const decisions = [...(pending?.decisions || []), ...resume.decisions]
+    if (decisions.length < actionCount) {
+      const interruptData = firstDataPart(requestContext.task?.status?.message?.parts)
+      const nextPending = { ...pending, actionCount, decisions }
+      publishInputRequired({
+        requestContext,
+        eventBus,
+        description: interruptDescriptionFromTask(requestContext.task, nextPending),
+        interruptData,
+        pending: {
+          actionCount,
+          decisions,
+          actionRequests: pendingActionRequests(requestContext.task, nextPending),
+        },
+      })
+      return undefined
+    }
+    resume = { ...resume, decisions }
+  }
+
+  const decisions = decisionsForAudit(resume, actionRequests)
+  LOG.debug("resuming", { conversation: short(contextId), decisions })
+  audit("AgentTaskResumed", {
+    data: { taskId, contextId, service: cds.context?.["agent.service"], decisions },
+  })
+
+  const originalActions = actionRequests.length
+    ? actionRequests
+    : await getPreInterruptToolCalls(graph, config)
+  const decisionNote = composeHitlDecisionNote(originalActions, resume)
+  const commandArgs = { resume }
+  if (decisionNote) commandArgs.update = { _hitlDecisionNote: decisionNote }
+  const resumed = await stream(new Command(commandArgs), signal)
+  return resumed.state
+}
+
+export function handleHitlInterrupt({
+  result,
+  requestContext,
+  eventBus,
+  serviceName,
+  duration,
+  onInputRequired,
+}) {
+  const { taskId, contextId } = requestContext
+  const description = extractInterruptDescription(result)
+  const interruptData = extractInterruptData(result)
+  LOG.info("input-required", { conversation: short(contextId), service: serviceName, duration })
+  onInputRequired?.(description)
+  audit("AgentInputRequired", {
+    data: { taskId, contextId, service: serviceName, description, interruptData },
+  })
+  publishInputRequired({
+    requestContext,
+    eventBus,
+    description,
+    interruptData,
+    pending: {
+      actionCount: interruptActionCount(result),
+      decisions: [],
+      actionRequests: interruptData?.actionRequests || interruptActionRequests(result),
+    },
+  })
+  return true
+}

package/srv/handlers/graph-executor.js

@@ -1,6 +1,6 @@
 import cds from "@sap/cds"
 import { short, audit, ms4 } from "../../lib/utils/utils.js"
-import { partsToText, buildChatMessages, firstDataPart } from "../../lib/utils/message-handling.js"
+import { agentMessage, partsToText, buildChatMessages } from "../../lib/utils/message-handling.js"
 import * as metrics from "../../lib/telemetry/metrics.js"
 import { mlflowAttrs, mlflowTraceAttrs, setSpanAttrs } from "../../lib/telemetry/mlflow/index.js"
 import { CdsFileStore } from "../../lib/protocol/persistence/file-store.js"
@@ -9,6 +9,7 @@ import { convertUsageData } from "../../lib/telemetry/chat-tracing.js"
 import { triggerCleanup } from "../../lib/protocol/persistence/cleanup.js"
 import { COLLECT_RESULT } from "./chat.js"
 import { linkTraceToPrompt } from "../../lib/telemetry/mlflow/tracing.js"
+import { handleHitlInterrupt, requiresHitl, resumeHitl } from "./graph-executor/hitl.js"
 
 const LOG = cds.log("agents")
 
@@ -104,18 +105,6 @@ function defaultOutputMapper(result) {
   return JSON.stringify(result)
 }
 
-// Construct a spec-compliant A2A Message; when `data` is a plain object, append it as a DataPart.
-function agentMessage(text, data) {
-  const parts = [{ kind: "text", text }]
-  if (data && typeof data === "object") parts.push({ kind: "data", data })
-  return {
-    kind: "message",
-    messageId: cds.utils.uuid(),
-    role: "agent",
-    parts,
-  }
-}
-
 /**
  * Extract user text from A2A message parts.
  */
@@ -123,147 +112,6 @@ function extractText(requestContext) {
   return partsToText(requestContext.userMessage?.parts)
 }
 
-// Extract the first inbound DataPart's opaque `data` object, or undefined if none.
-function extractData(requestContext) {
-  return firstDataPart(requestContext.userMessage?.parts)
-}
-
-/**
- * Parse user's resume text into a HITL decision.
- * Maps to the format expected by deepagents' humanInTheLoopMiddleware.
- */
-function parseResumeDecision(userText) {
-  const t = userText.trim()
-  if (/^(approve|yes|confirm|ok)$/i.test(t)) {
-    return { decisions: [{ type: "approve" }] }
-  }
-  if (/^edit$/i.test(t)) {
-    // Bare edit — structured edits (with args) arrive via the DataPart path.
-    return { decisions: [{ type: "edit" }] }
-  }
-  return { decisions: [{ type: "reject", message: userText }] }
-}
-
-// Best-effort decision label for logging/audit; opaque DataPart resumes fall back to "data".
-function decisionTypeOf(resume) {
-  return resume?.decisions?.[0]?.type ?? "data"
-}
-
-/**
- * Extract the human-readable description from an interrupt payload.
- * Accepts either a graph result (with __interrupt__) or a GraphInterrupt error (with .interrupts).
- * Handles both deepagents' humanInTheLoopMiddleware format and raw interrupt() calls.
- */
-function extractInterruptDescription(resultOrErr) {
-  const interrupt = resultOrErr.__interrupt__?.[0] || resultOrErr.interrupts?.[0]
-  const payload = interrupt?.value
-  if (!payload) return "This action requires your approval. Reply 'approve' or 'reject'."
-
-  // deepagents' humanInTheLoopMiddleware: { actionRequests: [{ description }], reviewConfigs }
-  if (payload.actionRequests?.length > 0) {
-    return (
-      payload.actionRequests[0].description || `Approve action: ${payload.actionRequests[0].name}?`
-    )
-  }
-
-  // Raw interrupt(value) - value is a string or object
-  if (typeof payload === "string") return payload
-  return JSON.stringify(payload)
-}
-
-/**
- * Extract the raw structured interrupt payload for opaque carry on a DataPart.
- * Returns the payload ONLY when it is a plain object; arrays and strings are
- * carried by the TextPart alone. Payload is app-defined; the plugin never
- * interprets it.
- */
-function extractInterruptData(resultOrErr) {
-  const interrupt = resultOrErr.__interrupt__?.[0] || resultOrErr.interrupts?.[0]
-  const payload = interrupt?.value
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined
-  return payload
-}
-
-// Order-invariant JSON serializer for structural arg comparison.
-function canonicalJSON(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value)
-  if (Array.isArray(value)) return "[" + value.map(canonicalJSON).join(",") + "]"
-  const keys = Object.keys(value).sort()
-  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalJSON(value[k])).join(",") + "}"
-}
-
-// Firm note describing HITL edits so the model doesn't apologize on the next turn.
-function composeEditNote(originals, resume) {
-  const decisions = resume?.decisions
-  if (!Array.isArray(decisions) || decisions.length === 0) return undefined
-
-  const consumed = new Set()
-  const takeByName = (name) => {
-    for (let j = 0; j < originals.length; j++) {
-      if (!consumed.has(j) && originals[j]?.name === name) {
-        consumed.add(j)
-        return originals[j]
-      }
-    }
-    return undefined
-  }
-  const takeNextUnconsumed = () => {
-    for (let j = 0; j < originals.length; j++) {
-      if (!consumed.has(j)) {
-        consumed.add(j)
-        return originals[j]
-      }
-    }
-    return undefined
-  }
-
-  const changes = []
-  for (const d of decisions) {
-    if (d?.type !== "edit" || !d.editedAction) continue
-    const editedName = d.editedAction.name
-    const editedArgs = d.editedAction.args
-    const orig = takeByName(editedName) ?? takeNextUnconsumed()
-    if (!orig) continue
-    if (orig.name === editedName && canonicalJSON(orig.args) === canonicalJSON(editedArgs)) continue
-    changes.push({
-      from: { name: orig.name, args: orig.args },
-      to: { name: editedName, args: editedArgs },
-    })
-  }
-  if (changes.length === 0) return undefined
-
-  const lines = changes.map(
-    (c) =>
-      `- \`${c.from.name}(${JSON.stringify(c.from.args)})\` → \`${c.to.name}(${JSON.stringify(c.to.args)})\``,
-  )
-  return [
-    "The user reviewed your proposed tool call(s) in the human-in-the-loop approval flow and edited them before execution. This is intentional user action, NOT a mistake on your part. Do NOT apologize or say you made an error.",
-    "",
-    "Edits applied:",
-    ...lines,
-    "",
-    "Proceed as if the edited values are what the user actually wants. Describe the outcome of the executed call accurately.",
-  ].join("\n")
-}
-
-// Reads the pre-interrupt AI's tool_calls from the checkpointer (still un-mutated at resume time).
-async function getPreInterruptToolCalls(graph, config) {
-  try {
-    if (typeof graph.getState !== "function") return []
-    const state = await graph.getState(config)
-    const messages = state?.values?.messages ?? []
-    for (let i = messages.length - 1; i >= 0; i--) {
-      const m = messages[i]
-      if (m?.tool_calls?.length) {
-        return m.tool_calls.map((tc) => ({ id: tc.id, name: tc.name, args: tc.args }))
-      }
-    }
-    return []
-  } catch {
-    return []
-  }
-}
-
 /**
  * GraphExecutor wraps a compiled LangGraph graph as an A2A AgentExecutor.
  *
@@ -716,50 +564,16 @@ class GraphExecutor {
         const t0 = Date.now()
 
         if (isResume) {
-          const dataPart = extractData(requestContext)
-          const userText = extractText(requestContext)
-          // Relaxed guard: accept a DataPart-only resume OR non-empty text.
-          if (dataPart === undefined && !userText.trim()) {
-            throw new Error(cds.i18n.messages.at("RESUME_REQUIRES_TEXT"))
-          }
-          const { Command } = await import("@langchain/langgraph")
-          // DataPart wins over text — a structured resume is self-describing and any
-          // accompanying text is treated as incidental (e.g. a human-readable echo).
-          const resume = dataPart !== undefined ? dataPart : parseResumeDecision(userText)
-          const decision = decisionTypeOf(resume)
-
-          LOG.debug("resuming", {
-            conversation: short(contextId),
-            service: serviceName,
-            decision,
-          })
-
-          // Audit: task resumed with HITL decision
-          audit("AgentTaskResumed", {
-            data: {
-              taskId,
-              contextId,
-              service: serviceName,
-              decision,
-            },
-          })
-          // On edit, stash a diff note in state; the injector middleware prepends it next turn.
-          const commandArgs = { resume }
-          if (decision === "edit") {
-            const originals = await getPreInterruptToolCalls(graph, config)
-            const editNote = composeEditNote(originals, resume)
-            if (editNote) commandArgs.update = { _hitlEditNote: editNote }
-          }
-          const resumed = await this._streamWithPublish(
+          result = await resumeHitl({
+            requestContext,
             graph,
-            new Command(commandArgs),
             config,
             eventBus,
-            taskId,
-            contextId,
-            controller.signal,
-          )
-          result = resumed.state
+            signal: controller.signal,
+            stream: (input, signal) =>
+              this._streamWithPublish(graph, input, config, eventBus, taskId, contextId, signal),
+          })
+          if (!result) return
         } else {
           const inputMapper = this._inputMapper || defaultInputMapper
           const rawInput = await inputMapper(requestContext)
@@ -780,56 +594,28 @@ class GraphExecutor {
         // (interrupt-only results may have no `messages` — treat as empty)
         usageData = aggregateUsageData(result.messages || [])
 
-        if (result?.__interrupt__?.length > 0) {
-          const description = extractInterruptDescription(result)
-          const interruptData = extractInterruptData(result)
-
-          const duration = ((Date.now() - t0) / 1000).toFixed(1) + "s"
-          LOG.info("input-required", {
-            conversation: short(contextId),
-            service: serviceName,
+        const duration = ((Date.now() - t0) / 1000).toFixed(1) + "s"
+        if (requiresHitl(result)) {
+          handleHitlInterrupt({
+            result,
+            requestContext,
+            eventBus,
+            serviceName,
             duration,
-          })
-
-          if (wfSpan) {
-            wfSpan.setAttribute("agent.outcome", "input-required")
-            const outputs = {
-              choices: [{ message: { role: "assistant", content: description } }],
-            }
-            setSpanAttrs(wfSpan, mlflowAttrs("AGENT", { outputs }))
-            const rootSpan = cds.context?.["_mlflow.rootSpan"]
-            if (rootSpan) {
-              setSpanAttrs(rootSpan, mlflowAttrs("CHAIN", { outputs }))
-            }
-          }
-
-          // Audit: agent requires human input
-          audit("AgentInputRequired", {
-            data: {
-              taskId,
-              contextId,
-              service: serviceName,
-              description,
-              interruptData,
-            },
-          })
-
-          eventBus.publish({
-            kind: "status-update",
-            taskId,
-            contextId,
-            status: {
-              state: "input-required",
-              message: agentMessage(description, interruptData),
-              timestamp: new Date().toISOString(),
+            onInputRequired: (description) => {
+              if (!wfSpan) return
+              wfSpan.setAttribute("agent.outcome", "input-required")
+              const outputs = {
+                choices: [{ message: { role: "assistant", content: description } }],
+              }
+              setSpanAttrs(wfSpan, mlflowAttrs("AGENT", { outputs }))
+              const rootSpan = cds.context?.["_mlflow.rootSpan"]
+              if (rootSpan) setSpanAttrs(rootSpan, mlflowAttrs("CHAIN", { outputs }))
             },
-            final: true,
           })
-          eventBus.finished()
           return
         }
 
-        const duration = ((Date.now() - t0) / 1000).toFixed(1) + "s"
         const outputMapper = this._outputMapper || defaultOutputMapper
         const output = outputMapper(result) || "I could not generate a response."
 
@@ -892,6 +678,9 @@ class GraphExecutor {
         //   1. emit_file_part tool calls (default graph) — JSON in toolResults/messages
         //   2. write_file '/outputs/*' via OutputsBackend (deep agent) — CDS rows
         const fileArtifacts = []
+        // DataParts embedded in tool-result content.
+        // Published as their own `data-*` artifact-update events below.
+        const dataArtifacts = []
         const maxFileBytes = cds.env.agents.fileIO.maxOutputFileSizeBytes
 
         // Artifacts from emit_file_part are this agent's own outputs — they must be
@@ -915,7 +704,10 @@ class GraphExecutor {
           const content = typeof msg.content === "string" ? msg.content : ""
           let pos = 0
           while (pos < content.length) {
-            const start = content.indexOf('{"kind":"file"', pos)
+            // Find the earliest next FilePart or DataPart marker.
+            const fileAt = content.indexOf('{"kind":"file"', pos)
+            const dataAt = content.indexOf('{"kind":"data"', pos)
+            const start = fileAt === -1 ? dataAt : dataAt === -1 ? fileAt : Math.min(fileAt, dataAt)
             if (start === -1) break
             // Walk forward tracking depth and quoted strings so that '}' inside
             // a string value (e.g. a filename like "result_{final}.csv") does not
@@ -944,6 +736,11 @@ class GraphExecutor {
             const raw = content.slice(start, i + 1)
             try {
               const artifact = JSON.parse(raw)
+              if (artifact.kind === "data") {
+                dataArtifacts.push(artifact)
+                pos = i + 1
+                continue
+              }
               // Apply the same per-file size cap as Source 2. Decode-length is
               // computed by Buffer.byteLength (zero allocation — pure formula
               // over string length + padding) so an oversized blob never pins
@@ -1064,6 +861,26 @@ class GraphExecutor {
           })
         }
 
+        dataArtifacts.forEach((artifact, i) => {
+          if (artifact.data == null || typeof artifact.data !== "object") {
+            LOG.warn("skipping malformed data artifact", {
+              conversation: short(contextId),
+              service: serviceName,
+            })
+            return
+          }
+          LOG.info("data emitted", { conversation: short(contextId), service: serviceName })
+          eventBus.publish({
+            kind: "artifact-update",
+            taskId,
+            contextId,
+            artifact: {
+              artifactId: `data-${i}`,
+              parts: [{ kind: "data", data: artifact.data }],
+            },
+          })
+        })
+
         // Programmatic .chat() path: stash graph result on eventBus so chat.js
         // can read messages without an extra checkpoint roundtrip.
         if (eventBus[COLLECT_RESULT]) {
@@ -1326,16 +1143,7 @@ class GraphExecutor {
   }
 }
 
-export {
-  GraphExecutor,
-  messageText,
-  defaultOutputMapper,
-  agentMessage,
-  parseResumeDecision,
-  decisionTypeOf,
-  extractInterruptData,
-  composeEditNote,
-}
+export { GraphExecutor, messageText, defaultOutputMapper, agentMessage }
 
 /**
  * @param {[import('@langchain/core/messages').Message]} messages

package/srv/handlers/index.js

@@ -92,7 +92,8 @@ export default function registerDefaultAgentHandlers(srv) {
   // Default buildModel: cds.connect.to('llm'), configurable via @agent.llm
   srv.on("buildModel", async (req) => {
     const name = srv?.options?.agent?.llm || srv?.definition?.["@agent.llm"] || "llm"
-    let { kind, impl, ...options } = cds.requires[name] ?? {}
+    const options = cds.requires[name] ?? {}
+    let { kind, impl } = options
     if (!impl) impl = cds.requires.kinds[kind]?.impl
     if (!impl) throw new Error("No service implementation found for " + name)
     const { default: LLMProvider } = await import(impl)

package/srv/handlers/sub-agent-tools.js

@@ -4,8 +4,9 @@ import { z } from "zod"
 import { LangGraphExecutor } from "../langgraph-executor-srv.js"
 import { short, toolName } from "../../lib/utils/utils.js"
 
-const LOG = cds.log("agents:sub-agents")
+const LOG = cds.log("agents:sub-agents|agents|sub-agents")
 
+import { inspect } from "util"
 /**
  * Extract text and file parts from an A2A response (task or message).
  */
@@ -15,7 +16,7 @@ function extractResult(result) {
   const text = []
   const files = []
 
-  const processParts = (parts = []) => {
+  const processParts = (parts) => {
     for (const part of parts) {
       if (part.kind === "text") text.push(part.text)
       else if (part.kind === "file") files.push(part)
@@ -23,8 +24,11 @@ function extractResult(result) {
   }
 
   if (result.kind === "task") {
-    processParts(result.status?.message?.parts)
-    for (const artifact of result.artifacts || []) processParts(artifact.parts)
+    if (result.artifacts)
+      for (let artifact of result.artifacts) {
+        if (!artifact.artifactId.startsWith("thinking")) processParts(artifact.parts)
+      }
+    else if (result.status?.message) processParts(result.status.message.parts)
     if (text.length === 0 && files.length === 0) {
       return { text: `Task ${result.id}: ${result.status?.state || "unknown"}`, files: [] }
     }
@@ -71,21 +75,29 @@ function formatToolResult({ text, files }) {
  * Wrap an A2A client as a LangChain tool the agent can call.
  */
 function createA2ATool(client, agentCard) {
+  const subagent = agentCard.name
   return tool(
     async ({ message }) => {
       try {
+        const messageId = cds.utils.uuid()
+        LOG.info(`Sending message to ${subagent}`, { messageId }, "\n\n" + message + "\n")
         const result = await client.sendMessage({
           message: {
             kind: "message",
             role: "user",
-            messageId: cds.utils.uuid(),
+            messageId,
             parts: [{ kind: "text", text: message }],
           },
         })
-        return formatToolResult(extractResult(result))
+        if (LOG._debug)
+          LOG.trace(`Raw results from ${subagent}`, inspect(result, { depth: null, colors: true }))
+        let response = formatToolResult(extractResult(result))
+        if (response)
+          LOG.info(`Got response from ${subagent}`, { messageId }, "\n\n" + response + "\n")
+        return response
       } catch (err) {
-        LOG.warn("Sub-agent tool error", { agent: agentCard.name, error: err.message })
-        return `Error communicating with ${agentCard.name}: ${err.message}`
+        LOG.warn("Sub agent tool error", { subagent, error: err.message })
+        return `Error communicating with ${subagent}: ${err.message}`
       }
     },
     {
@@ -106,7 +118,7 @@ export async function buildSubAgentToolLocally(serviceName) {
 
   const { generateAgentCard } = await import("../../lib/protocol/agent-card.js")
   const agentCard = generateAgentCard(srv)
-  LOG.info(`Wired local sub-agent "${agentCard.name}" (${serviceName})`)
+  LOG.info(`Connecting to sub agent ${serviceName}`, "(local)")
 
   const { RequestContext, DefaultExecutionEventBus } = await import("@a2a-js/sdk/server")
 
@@ -280,7 +292,7 @@ export async function buildSubAgentToolFromConnection(serviceName) {
 
   const path = typeof credentials === "object" ? credentials?.path : null
   const base = agentBaseUrl.replace(/\/$/, "") + (path ? `/${path.replace(/^\//, "")}` : "")
-  LOG.info(`Connecting to sub-agent at ${base}`)
+  LOG.info(`Connecting to sub agent ${serviceName}`, { at: base })
 
   // revisit: a2a agents may be tenant specific, card per tenant?
   const initialHeaders = await resolveHeaders()
@@ -294,7 +306,6 @@ export async function buildSubAgentToolFromConnection(serviceName) {
     )
   }
   const agentCard = await cardRes.json()
-  LOG.info(`Connected to sub-agent "${agentCard.name}" (${serviceName})`)
 
   const { ClientFactory, ClientFactoryOptions, JsonRpcTransportFactory, RestTransportFactory } =
     await import("@a2a-js/sdk/client")

package/srv/handlers/tools.js

@@ -222,6 +222,10 @@ export function generateTools(srv) {
     tools.push(createEmitFilePartTool())
   }
 
+  if (cds.env.agents?.emitDataParts) {
+    tools.push(createEmitDataPartTool())
+  }
+
   return tools
 }
 
@@ -368,3 +372,29 @@ export function createReadFileTool(fileStore, contextId, userId) {
     },
   )
 }
+
+/**
+ * Create a tool that emits a DataPart in the A2A response.
+ * The executor's toolResults collection detects `kind: "data"`
+ * and emits the tool result as a data part.
+ */
+export function createEmitDataPartTool() {
+  return tool(
+    async ({ data, mediaType }) => {
+      return {
+        kind: "data",
+        data,
+        mediaType: mediaType ?? "application/json",
+      }
+    },
+    {
+      name: "emit_data_part",
+      description: "Emit a structured A2A DataPart. Only use when instructed.",
+      schema: z.object({
+        // A2A DataPart is specified to be an object in A2A 0.3
+        // https://a2a-protocol.org/v0.3.0/specification/#653-datapart-object
+        data: z.looseObject().describe("Structured object"),
+      }),
+    },
+  )
+}

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

@@ -1,18 +0,0 @@
-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,
-      }
-    },
-  })
-}