@cap-js/agents 0.9.2 → 0.9.4

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

@@ -2,10 +2,11 @@ import cds from "@sap/cds"
 import { tool } from "@langchain/core/tools"
 import { z } from "zod"
 import { LangGraphExecutor } from "../langgraph-executor-srv.js"
-import { toolName } from "../../lib/utils/utils.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")
 
@@ -164,6 +176,7 @@ export async function buildSubAgentToolLocally(serviceName) {
         taskId,
         contextId,
       )
+      const truncated = message?.length > 80 ? message.slice(0, 80) + "..." : message
 
       try {
         // Run the sub-agent detached from the calling agent, in its own root
@@ -172,6 +185,12 @@ export async function buildSubAgentToolLocally(serviceName) {
         await new Promise((resolve, reject) => {
           cds
             .spawn({ user: cds.context?.user, tenant: cds.context?.tenant }, async () => {
+              LOG.info("request", {
+                conversation: short(contextId),
+                service: srv.name,
+                text: truncated,
+              })
+
               await executor.execute(requestContext, eventBus)
               await done
             })
@@ -273,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()
@@ -287,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

@@ -11,7 +11,7 @@ import {
   executeCallActionTool,
   executePerActionTool,
 } from "@cap-js/mcp/lib/tools.js"
-import { getFilteredEntities, getFilteredActions } from "../../lib/utils/utils.js"
+import { getFilteredEntities, getFilteredActions, getAgentLogger } from "../../lib/utils/utils.js"
 import { isTextMime } from "../../lib/agents/markdown/backends/mime-utils.js"
 import { checkAuthorization } from "@cap-js/mcp/lib/auth.js"
 
@@ -31,6 +31,7 @@ function cachedAuth(srv) {
 
 class GenericReadTool extends DynamicStructuredTool {
   constructor(srv, entities) {
+    const log = getAgentLogger(srv)
     const def = createGenericReadToolDefinition(Object.keys(entities), srv.name, "")
     super({
       name: def.name,
@@ -38,7 +39,7 @@ class GenericReadTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeGenericReadTool(srv, entities, args, { log: LOG }))
+        return unwrap(await executeGenericReadTool(srv, entities, args, { log }))
       },
     })
     this.srv = srv
@@ -67,6 +68,7 @@ class GenericReadTool extends DynamicStructuredTool {
 
 class DescribeTool extends DynamicStructuredTool {
   constructor(srv, entities, actions) {
+    const log = getAgentLogger(srv)
     const def = createDescribeToolDefinition(
       Object.keys(entities),
       Object.keys(actions),
@@ -79,7 +81,7 @@ class DescribeTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeDescribe(srv, entities, actions, args, { log: LOG }))
+        return unwrap(await executeDescribe(srv, entities, actions, args, { log }))
       },
     })
     this.srv = srv
@@ -119,6 +121,7 @@ class DescribeTool extends DynamicStructuredTool {
 
 class PerActionTool extends DynamicStructuredTool {
   constructor(srv, actionName, action) {
+    const log = getAgentLogger(srv)
     const def = createPerActionToolDefinition(actionName, action, srv.name, srv.model, "")
     super({
       name: def.name,
@@ -126,7 +129,7 @@ class PerActionTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executePerActionTool(srv, actionName, action, args, { log: LOG }))
+        return unwrap(await executePerActionTool(srv, actionName, action, args, { log }))
       },
     })
     this.srv = srv
@@ -142,6 +145,7 @@ class PerActionTool extends DynamicStructuredTool {
 
 class CallActionTool extends DynamicStructuredTool {
   constructor(srv, actions) {
+    const log = getAgentLogger(srv)
     const def = createCallActionToolDefinition(Object.keys(actions), srv.name, "")
     super({
       name: def.name,
@@ -149,7 +153,7 @@ class CallActionTool extends DynamicStructuredTool {
       schema: def.inputSchema,
       responseFormat: "content_and_artifact",
       func: async (args) => {
-        return unwrap(await executeCallActionTool(srv, actions, args, { log: LOG }))
+        return unwrap(await executeCallActionTool(srv, actions, args, { log }))
       },
     })
     this.srv = srv
@@ -218,6 +222,10 @@ export function generateTools(srv) {
     tools.push(createEmitFilePartTool())
   }
 
+  if (cds.env.agents?.emitDataParts) {
+    tools.push(createEmitDataPartTool())
+  }
+
   return tools
 }
 
@@ -364,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,
-      }
-    },
-  })
-}

package/lib/telemetry/mlflow.js

@@ -1,290 +0,0 @@
-/**
- * MLflow span attribute helpers for @cap-js/agents.
- *
- * Adds mlflow.* attributes to existing OTel spans so the MLflow OTLP
- * ingestion endpoint can assemble them into proper MLflow traces.
- *
- * All functions return {} when cds.env.agents.mlflow is falsy (zero overhead).
- *
- * The exporter itself is configured via setupMlflowExporter() as a
- * RoutingSpanProcessor that lazily creates per-experiment-ID exporters —
- * existing exporters (Dynatrace, Cloud Logging, Grafana, etc.) continue
- * to work unchanged.
- */
-import cds from "@sap/cds"
-
-/**
- * Resolve the MLflow experiment ID for the current request context.
- *
- * Resolution order:
- *   1. @Core.SchemaVersion annotation on the service (feature-toggleable via cds.context.model)
- *   2. cds.env.requires["mlflow"].credentials.MLFLOW_EXPERIMENT_ID
- *   3. process.env.MLFLOW_EXPERIMENT_ID
- *
- * MLflow requires experiment IDs to be numeric (int64). Throws if annotation
- * value is not a valid integer string.
- */
-function resolveExperimentId() {
-  // Read from @Core.SchemaVersion on the active service (feature-toggle-aware)
-  const serviceName = cds.context?.["agent.service"]
-  if (serviceName) {
-    const definition =
-      cds.context?.model?.definitions?.[serviceName] || cds.services?.[serviceName]?.definition
-    const annotated = definition?.["@Core.SchemaVersion"]
-    if (annotated) {
-      const id = String(annotated)
-      if (!/^\d+$/.test(id)) {
-        throw new Error(
-          `@Core.SchemaVersion on "${serviceName}" must be a numeric string (MLflow experiment ID requires int64). Got: "${id}"`,
-        )
-      }
-      return id
-    }
-  }
-
-  // Fallback: credentials / env
-  const creds = cds.env.requires?.mlflow?.credentials || cds.env.requires?.mlflow?.credentials
-  return creds?.MLFLOW_EXPERIMENT_ID || process.env.MLFLOW_EXPERIMENT_ID
-}
-
-/**
- * Build mlflow.* span attributes for a given span type.
- * @param {"LLM"|"AGENT"|"TOOL"|"CHAIN"|"RETRIEVER"} spanType
- * @param {{ inputs?: any, outputs?: any, model?: string, provider?: string, functionName?: string, tokenUsage?: object }} [opts]
- * @returns {Record<string, string>} Attributes to set on span, or {} when disabled
- */
-export function mlflowAttrs(spanType, opts = {}) {
-  if (!cds.env.agents?.mlflow) return {}
-  const experimentId = resolveExperimentId()
-  const attrs = {}
-  if (experimentId) attrs["mlflow.experimentId"] = String(experimentId)
-  attrs["mlflow.spanType"] = spanType
-  if (opts.model) attrs["mlflow.llm.model"] = String(opts.model)
-  if (opts.provider) attrs["mlflow.llm.provider"] = String(opts.provider)
-  if (opts.functionName) attrs["mlflow.spanFunctionName"] = String(opts.functionName)
-  if (opts.inputs !== undefined) attrs["mlflow.spanInputs"] = JSON.stringify(opts.inputs)
-  if (opts.outputs !== undefined) attrs["mlflow.spanOutputs"] = JSON.stringify(opts.outputs)
-  if (opts.tokenUsage) {
-    attrs["mlflow.chat.tokenUsage"] = JSON.stringify({
-      input_tokens: opts.tokenUsage.input_tokens,
-      output_tokens: opts.tokenUsage.output_tokens,
-      total_tokens: opts.tokenUsage.total_tokens,
-      cache_creation_input_tokens: opts.tokenUsage.cache_creation_input_tokens,
-      cache_read_input_tokens: opts.tokenUsage.cache_read_input_tokens,
-    })
-  }
-  return attrs
-}
-
-/**
- * Build mlflow trace-level tag attributes (set on root/workflow span).
- * Uses mlflow.traceTag.* prefix so MLflow server extracts them as trace tags.
- * Also sets OTel semconv user.id and session.id which MLflow reads natively.
- * @returns {Record<string, string>} Attributes to set on root span, or {} when disabled
- */
-export function mlflowTraceAttrs() {
-  if (!cds.env.agents?.mlflow) return {}
-  const session = String(cds.context?.["agent.context.id"] || "")
-  const user = String(cds.context?.user?.id || "")
-  const tenant = String(cds.context?.tenant || "")
-  return {
-    // OTel semconv keys MLflow reads natively for user/session display
-    "session.id": session,
-    "user.id": user,
-    // mlflow.traceTag.* prefix for custom trace tags
-    "mlflow.traceTag.tenant": tenant,
-  }
-}
-
-/**
- * Spread attributes object onto an OTel span (null-safe).
- * Coerces all values to strings to prevent [object Object] in downstream systems.
- * @param {import("@opentelemetry/api").Span | null} span
- * @param {Record<string, string>} attrs
- */
-export function setSpanAttrs(span, attrs) {
-  if (!cds.env.agents?.mlflow) return
-  if (!span) return
-  for (const [k, v] of Object.entries(attrs)) {
-    if (v !== undefined && v !== null) span.setAttribute(k, v)
-  }
-}
-
-/**
- * SpanProcessor that routes spans to per-experiment-ID BatchSpanProcessors.
- * Lazily creates an OTLPTraceExporter for each unique mlflow.experimentId
- * seen on spans, so different services (or feature-toggled @Core.SchemaVersion
- * values) export to the correct MLflow experiment.
- *
- * Supports both static headers (PAT token) and async header factories (OAuth).
- */
-export class RoutingSpanProcessor {
-  constructor({ url, headersConfig, ucTableName, BatchSpanProcessor, OTLPTraceExporter }) {
-    this._url = url
-    this._headersConfig = headersConfig
-    this._ucTableName = ucTableName
-    this._BatchSpanProcessor = BatchSpanProcessor
-    this._OTLPTraceExporter = OTLPTraceExporter
-    this._processors = new Map()
-  }
-
-  onStart() {}
-
-  onEnd(span) {
-    const expId = span.attributes?.["mlflow.experimentId"]
-    if (!expId) return
-    this._getOrCreate(expId).onEnd(span)
-  }
-
-  _getOrCreate(experimentId) {
-    if (this._processors.has(experimentId)) return this._processors.get(experimentId)
-    const ucHeader = this._ucTableName
-      ? { "X-Databricks-UC-Table-Name": this._ucTableName }
-      : undefined
-    // Build headers — async factory or static object
-    const headers =
-      typeof this._headersConfig === "function"
-        ? async () => ({
-            ...(await this._headersConfig()),
-            "x-mlflow-experiment-id": experimentId,
-            ...ucHeader,
-          })
-        : {
-            ...this._headersConfig,
-            "x-mlflow-experiment-id": experimentId,
-            ...ucHeader,
-          }
-    const exporter = new this._OTLPTraceExporter({ url: this._url, headers })
-    const proc = new this._BatchSpanProcessor(exporter)
-    this._processors.set(experimentId, proc)
-    return proc
-  }
-
-  async forceFlush() {
-    await Promise.all([...this._processors.values()].map((p) => p.forceFlush()))
-  }
-
-  async shutdown() {
-    await Promise.all([...this._processors.values()].map((p) => p.shutdown()))
-    this._processors.clear()
-  }
-}
-
-/**
- * Register MLflow OTLP RoutingSpanProcessor. No-op when credentials missing.
- * Reads from cds.env.requires["mlflow"].credentials
- *
- * Auth: OAuth (clientid+clientsecret+url) takes precedence over static MLFLOW_TOKEN.
- * UC: set UC_CATALOG + UC_SCHEMA + UC_TABLE_PREFIX for Unity Catalog trace storage.
- */
-export async function setupMlflowExporter() {
-  if (!cds.env.agents?.mlflow) return
-
-  const LOG = cds.log("agents")
-  try {
-    const creds = cds.env.requires?.mlflow?.credentials || {}
-    const host = creds.MLFLOW_HOST
-    const token = creds.MLFLOW_TOKEN
-    const mlflowEndpoint =
-      creds.MLFLOW_OTLP_ENDPOINT || (host && `${host.replace(/\/$/, "")}/v1/traces`)
-
-    // Resolve authentication mode
-    let headersConfig
-    if (creds.clientid && creds.clientsecret) {
-      const tokenUrl = `${creds.url ?? host.replace(/\/$/, "")}/oidc/v1/token`
-      let cached = null
-      let expiresAt = 0
-      headersConfig = async function fetchToken() {
-        // Return cached token if still valid (60s buffer before expiry)
-        if (cached && Date.now() < expiresAt) return cached
-        const res = await fetch(tokenUrl, {
-          method: "POST",
-          headers: {
-            Authorization:
-              "Basic " + Buffer.from(`${creds.clientid}:${creds.clientsecret}`).toString("base64"),
-            "Content-Type": "application/x-www-form-urlencoded",
-          },
-          body: `grant_type=client_credentials&scope=all-apis`,
-          signal: AbortSignal.timeout(10_000),
-        })
-        if (!res.ok) {
-          const body = await res.text().catch(() => "")
-          const msg = `MLFlow oauth export failed: HTTP ${res.status} ${res.statusText}`
-          throw cds.error({ message: msg, response: body })
-        }
-        const { access_token, expires_in } = await res.json()
-        cached = { Authorization: `Bearer ${access_token}` }
-        expiresAt = Date.now() + (expires_in - 60) * 1000
-        return cached
-      }
-      LOG.debug("MLflow: using OAuth client credentials authentication")
-    } else if (token) {
-      headersConfig = { Authorization: `Bearer ${token}` }
-    } else {
-      headersConfig = {}
-      LOG.debug("MLflow: no auth credentials — assuming unauthenticated MLflow server")
-    }
-
-    if (!mlflowEndpoint) {
-      LOG.warn(
-        "MLflow: no endpoint configured (MLFLOW_HOST or MLFLOW_OTLP_ENDPOINT) — export disabled",
-      )
-      return
-    }
-
-    const ucCatalog = creds.UC_CATALOG
-    const ucSchema = creds.UC_SCHEMA
-    const ucTablePrefix = creds.UC_TABLE_PREFIX
-    const ucTableName =
-      ucCatalog && ucSchema && ucTablePrefix
-        ? `${ucCatalog}.${ucSchema}.${ucTablePrefix}_otel_spans`
-        : undefined
-
-    const { trace } = await import("@opentelemetry/api")
-    const provider = trace.getTracerProvider()
-    const delegate = provider.getDelegate?.() || provider
-
-    let BatchSpanProcessor, OTLPTraceExporter
-    try {
-      const { createRequire } = await import("node:module")
-      const req = createRequire(process.cwd() + "/")
-      ;({ BatchSpanProcessor } = req("@opentelemetry/sdk-trace-base"))
-      ;({ OTLPTraceExporter } = req("@opentelemetry/exporter-trace-otlp-proto"))
-    } catch (err) {
-      LOG.warn(
-        "MLflow: @opentelemetry/exporter-trace-otlp-proto not resolvable from the application. " +
-          "Install a version matching your @cap-js/telemetry major " +
-          "(v1 → ^0.57, v2 → ^0.221). Export disabled.",
-        { error: err.message },
-      )
-      return
-    }
-
-    const routing = new RoutingSpanProcessor({
-      url: mlflowEndpoint,
-      headersConfig,
-      ucTableName,
-      BatchSpanProcessor,
-      OTLPTraceExporter,
-    })
-
-    if (delegate.addSpanProcessor) {
-      // OTEL SDK v1
-      delegate.addSpanProcessor(routing)
-    } else if (delegate._activeSpanProcessor?._spanProcessors) {
-      // OTEL SDK v2: no addSpanProcessor — push into MultiSpanProcessor
-      delegate._activeSpanProcessor._spanProcessors.push(routing)
-    } else {
-      LOG.warn(
-        "MLflow: no TracerProvider with addSpanProcessor — ensure @cap-js/telemetry is loaded",
-      )
-      return
-    }
-    LOG.info("MLflow: routing span processor added (per-experiment export)", {
-      endpoint: mlflowEndpoint,
-      ...(ucTableName && { ucTableName }),
-    })
-  } catch (err) {
-    LOG.error("MLflow: failed to configure OTLP export", { error: err.message })
-  }
-}