@agent-native/core 0.131.5 → 0.131.7

package/dist/scripts/call-agent.js

@@ -1,22 +1,87 @@
 import { createHash, randomUUID } from "node:crypto";
 import { parseA2AAgentActivityPart } from "../a2a/activity.js";
-import { A2ATaskTimeoutError, callAgent, shouldPreferGlobalA2ASecret, signA2AToken, } from "../a2a/client.js";
+import { A2ATaskTimeoutError, MAX_A2A_CALLER_RESPONSE_CHARS, callAgent, shouldPreferGlobalA2ASecret, signA2AToken, } from "../a2a/client.js";
+import { MAX_A2A_DELEGATION_HOPS } from "../a2a/correlation.js";
 import { invokeAgentAction } from "../a2a/invoke.js";
 import { formatLlmCredentialErrorMessage, isLlmCredentialError, } from "../agent/engine/credential-errors.js";
 import { A2A_CONTINUATION_QUEUED_MARKER } from "../integrations/a2a-continuation-marker.js";
+import { trackingIdentityProperties } from "../observability/tracking-identity.js";
 import { getOrgDomain, getOrgA2ASecret } from "../org/context.js";
 import { findAgent, discoverAgents } from "../server/agent-discovery.js";
 import { getRequestUserEmail, getRequestOrgId, isIntegrationCallerRequest, getIntegrationRequestContext, } from "../server/request-context.js";
+import { track } from "../tracking/registry.js";
 const DEFAULT_SERVERLESS_INTEGRATION_A2A_TIMEOUT_MS = 18_000;
 const NETLIFY_INTEGRATION_A2A_TIMEOUT_MS = 2_000;
 const INTEGRATION_A2A_TOKEN_TTL = "30m";
+const A2A_INVOCATION_EVENT = "$a2a_invocation";
+function trackA2AInvocation(args) {
+    try {
+        track(A2A_INVOCATION_EVENT, {
+            ...trackingIdentityProperties(),
+            source: "a2a_delegation",
+            invocation_id: args.invocationId,
+            caller_app: args.callerApp ?? "unknown",
+            target_app: args.targetApp,
+            mode: args.mode,
+            status: args.status,
+            duration_ms: Math.max(0, Date.now() - args.startedAt),
+            task_id: args.taskId,
+            terminal_code: args.terminalCode,
+            delegation_depth: args.correlation.delegationDepth,
+            parent_run_id: args.correlation.parentRunId,
+            parent_turn_id: args.correlation.parentTurnId,
+        }, { userId: getRequestUserEmail() });
+    }
+    catch {
+        // Tracking must never affect delegation.
+    }
+}
 function buildDelegationCorrelation(context, selfAppId, invocationId) {
+    const self = normalizeAppHandle(selfAppId);
+    const inheritedVisited = Array.isArray(context?.visitedApps)
+        ? context.visitedApps.map(normalizeAppHandle).filter(Boolean)
+        : [];
+    const visitedApps = self
+        ? [...new Set([...inheritedVisited, self])]
+        : [...new Set(inheritedVisited)];
+    const inheritedDepth = Number.isInteger(context?.delegationDepth)
+        ? Math.max(0, Number(context?.delegationDepth))
+        : 0;
     return {
         ...(selfAppId?.trim() ? { callerApp: selfAppId.trim() } : {}),
         ...(context?.threadId ? { callerThreadId: context.threadId } : {}),
         ...(context?.runId ? { parentRunId: context.runId } : {}),
         ...(context?.turnId ? { parentTurnId: context.turnId } : {}),
         ...(invocationId ? { invocationId } : {}),
+        delegationDepth: Math.min(MAX_A2A_DELEGATION_HOPS, inheritedDepth + 1),
+        ...(visitedApps.length > 0 ? { visitedApps } : {}),
+    };
+}
+function normalizeAppHandle(value) {
+    return typeof value === "string"
+        ? value
+            .trim()
+            .toLowerCase()
+            .replace(/^agent-native-/, "")
+        : "";
+}
+function terminalTaskError(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const candidate = value;
+    if (candidate.name !== "A2ATaskTerminalError")
+        return null;
+    return {
+        state: String(candidate.state ?? "failed"),
+        ...(typeof candidate.taskId === "string"
+            ? { taskId: candidate.taskId }
+            : {}),
+        ...(typeof candidate.responseText === "string"
+            ? { responseText: candidate.responseText }
+            : {}),
+        ...(typeof candidate.errorCode === "string"
+            ? { errorCode: candidate.errorCode }
+            : {}),
     };
 }
 function buildMessageIdempotencyKey(originatingTurnId, target, exactMessage) {
@@ -114,7 +179,7 @@ function formatDownstreamLlmCredentialFailure(agentName, value) {
         : null;
 }
 export const tool = {
-    description: "Call a DIFFERENT, separately-deployed app over A2A. When you know the exact exposed read-only action, pass action + input and omit message; this invokes it directly without starting the other app's model and is the fastest path for bounded data reads. Use message only for natural-language investigation, synthesis, mutations, or multi-step work that needs the other agent. NEVER use this to call your own app or perform actions you can do with your own tools. Using call-agent on yourself will fail and waste time. " +
+    description: "Ask a DIFFERENT, separately-deployed app's agent over A2A. Use message by default so the receiving specialist interprets the objective with its own instructions, skills, connected sources, data dictionary, and tools. The receiver owns provider, schema, query, join, and SQL decisions. Use action + input only for an exact, explicitly known, bounded read whose complete input schema is already known; never expose or call a direct action to work around slow or unreliable delegation, and never guess receiver-owned query logic. NEVER use this to call your own app or perform actions you can do with your own tools. Using call-agent on yourself will fail and waste time. " +
         'For brand-consistent generated media, the first-party Assets agent is available as agent="assets"; use it when another app needs generated heroes, diagrams, product shots, thumbnails, videos, or design imagery, unless the current app has its own generation action that already delegates there. ' +
         "IMPORTANT — handling the response: " +
         "(a) If it contains a URL or ID, copy it VERBATIM into your reply. Do not 'correct' or pluralize the path (e.g. /deck/ → /decks/), normalize casing, or change the slug — any edit breaks the link. " +
@@ -138,7 +203,7 @@ export const tool = {
             },
             action: {
                 type: "string",
-                description: "Exact read-only action exposed by the target app. Use with input and omit message/taskId to skip the downstream agent loop.",
+                description: "Optional exact read-only action for an explicitly known bounded operation. Prefer message when the target agent must interpret data, choose sources or tools, synthesize, mutate, or do multi-step work. Never guess the action schema or send receiver-owned SQL.",
             },
             input: {
                 type: "object",
@@ -185,6 +250,13 @@ export async function run(args, context, selfAppId) {
     if (selfAppId && agentIdOrName.toLowerCase() === selfAppId.toLowerCase()) {
         return `Error: You cannot use call-agent to call yourself (${selfAppId}). Use your own registered actions/tools instead. call-agent is only for communicating with OTHER separately-deployed apps.`;
     }
+    const inheritedDepth = Number.isInteger(context?.delegationDepth)
+        ? Math.max(0, Number(context?.delegationDepth))
+        : 0;
+    if (!taskId && inheritedDepth >= MAX_A2A_DELEGATION_HOPS) {
+        return (`Error: Cross-app delegation stopped at the ${MAX_A2A_DELEGATION_HOPS}-hop limit. ` +
+            "Finish with the results already collected instead of starting another agent.");
+    }
     const agent = await findAgent(agentIdOrName, selfAppId);
     if (!agent) {
         const available = (await discoverAgents(selfAppId))
@@ -192,13 +264,35 @@ export async function run(args, context, selfAppId) {
             .join(", ");
         return `Error: Agent "${agentIdOrName}" not found. Available agents: ${available || "(none)"}`;
     }
+    if (!taskId) {
+        const visited = new Set((context?.visitedApps ?? []).map(normalizeAppHandle).filter(Boolean));
+        const self = normalizeAppHandle(selfAppId);
+        if (self)
+            visited.add(self);
+        const targetHandles = [
+            normalizeAppHandle(agent.id),
+            normalizeAppHandle(agent.name),
+            normalizeAppHandle(agentIdOrName),
+        ].filter(Boolean);
+        const repeated = targetHandles.find((handle) => visited.has(handle));
+        if (repeated) {
+            return (`Error: Cross-app delegation cycle blocked before calling ${agent.name}. ` +
+                `The request already visited ${[...visited].join(" -> ")}.`);
+        }
+    }
     const correlation = buildDelegationCorrelation(context, selfAppId);
     const idempotencyKey = message && !taskId
         ? buildMessageIdempotencyKey(context?.turnId, agent.url, message)
         : undefined;
+    const targetApp = normalizeAppHandle(agent.id) ||
+        normalizeAppHandle(agent.name) ||
+        normalizeAppHandle(agentIdOrName) ||
+        "unknown";
     if (action) {
         const agentCallId = randomUUID();
         const startedAt = Date.now();
+        let terminalStatus = "done";
+        let terminalCode;
         if (context?.send) {
             context.send({
                 type: "agent_call",
@@ -209,6 +303,10 @@ export async function run(args, context, selfAppId) {
         }
         try {
             const output = await invokeReadOnlyAppAction(agent, action, input, buildDelegationCorrelation(context, selfAppId, randomUUID()));
+            if (/^Error\b/i.test(output)) {
+                terminalStatus = "error";
+                terminalCode = "direct_action_failed";
+            }
             if (context?.send && output) {
                 context.send({
                     type: "agent_call_text",
@@ -219,12 +317,27 @@ export async function run(args, context, selfAppId) {
             }
             return output;
         }
+        catch (error) {
+            terminalStatus = "error";
+            terminalCode = "direct_action_failed";
+            throw error;
+        }
         finally {
+            trackA2AInvocation({
+                invocationId: agentCallId,
+                callerApp: selfAppId,
+                targetApp,
+                mode: "direct_action",
+                status: terminalStatus === "done" ? "success" : "error",
+                startedAt,
+                terminalCode,
+                correlation,
+            });
             if (context?.send) {
                 context.send({
                     type: "agent_call",
                     agent: agent.name,
-                    status: "done",
+                    status: terminalStatus,
                     agentCallId,
                     durationMs: Date.now() - startedAt,
                 });
@@ -240,10 +353,17 @@ export async function run(args, context, selfAppId) {
     const messageWithHint = taskId
         ? ""
         : `${message}${integrationSourceContextHint(sourceContext)}\n\n` +
-            `[Note: this request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
+            `<a2a-caller-hint>\n` +
+            `This request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
             `If you create or reference a deck/document/design/dashboard, include its FULLY-QUALIFIED URL (e.g. ${agent.url}/deck/<id>) in your reply, not a relative path. ` +
             `Use only artifact IDs and URL paths returned by successful actions — never invent slugs, IDs, or hosts. ` +
-            `Return a concise caller-ready synthesis rather than raw tool output or full transcripts; preserve source counts, IDs, short supporting quotes, and URLs needed to substantiate the answer.]`;
+            `Return a concise caller-ready synthesis rather than raw tool output or full transcripts; preserve source counts, IDs, short supporting quotes, and URLs needed to substantiate the answer.\n` +
+            `</a2a-caller-hint>`;
+    const invocationId = randomUUID();
+    const invocationStartedAt = Date.now();
+    let invocationStatus = "error";
+    let invocationTaskId = taskId || undefined;
+    let invocationTerminalCode;
     try {
         // If we have a send context, use streaming so the UI shows progressive text
         if (context?.send) {
@@ -297,11 +417,15 @@ export async function run(args, context, selfAppId) {
             let responseText = "";
             let lastSentLength = 0;
             const agentCallId = randomUUID();
+            let terminalStatus = "done";
             const existingContinuationText = taskId
                 ? null
                 : await formatExistingIntegrationContinuationIfRetry(agent, message);
-            if (existingContinuationText)
+            if (existingContinuationText) {
+                invocationStatus = "pending";
+                invocationTerminalCode = "existing_continuation";
                 return existingContinuationText;
+            }
             context.send({
                 type: "agent_call",
                 agent: agent.name,
@@ -457,6 +581,9 @@ export async function run(args, context, selfAppId) {
             catch (pollErr) {
                 const timeoutTaskId = getA2ATaskTimeoutTaskId(pollErr);
                 if (timeoutTaskId) {
+                    terminalStatus = "pending";
+                    invocationTaskId = timeoutTaskId;
+                    invocationTerminalCode = "timeout_pending";
                     const queued = await enqueueIntegrationContinuationIfPossible(timeoutTaskId, agent, message, callerEmail);
                     if (queued) {
                         responseText =
@@ -480,21 +607,60 @@ export async function run(args, context, selfAppId) {
                         }
                     }
                 }
+                else if (terminalTaskError(pollErr)?.state === "input-required") {
+                    terminalStatus = "pending";
+                    const terminal = terminalTaskError(pollErr);
+                    invocationTaskId = terminal.taskId;
+                    invocationTerminalCode = terminal.errorCode ?? "input_required";
+                    responseText = formatInputRequiredWaitInstruction(agent.name, terminal, agentIdOrName);
+                }
+                else if (terminalTaskError(pollErr)) {
+                    terminalStatus = "error";
+                    const terminal = terminalTaskError(pollErr);
+                    invocationTaskId = terminal.taskId;
+                    invocationTerminalCode = terminal.errorCode ?? terminal.state;
+                    const detail = expandRelativeUrls(terminal.responseText ?? pollErr?.message ?? "unknown failure", agent.url);
+                    responseText =
+                        `Error: The ${agent.name} agent ended ${terminal.state}` +
+                            (terminal.errorCode ? ` (${terminal.errorCode})` : "") +
+                            (terminal.taskId ? ` [taskId: ${terminal.taskId}]` : "") +
+                            (detail ? `: ${detail}` : "");
+                }
                 else {
+                    terminalStatus = "error";
+                    invocationTerminalCode = "call_failed";
                     const reason = pollErr?.message ?? "unknown error";
                     responseText =
                         formatDownstreamLlmCredentialFailure(agent.name, pollErr) ??
-                            `The ${agent.name} agent is taking longer than expected and didn't reply in time. (${reason})`;
+                            `Error: The ${agent.name} agent call failed. (${reason})`;
                 }
             }
+            if (!responseText && terminalStatus === "done") {
+                terminalStatus = "error";
+                invocationTerminalCode = "empty_agent_response";
+            }
+            if (responseText.length > MAX_A2A_CALLER_RESPONSE_CHARS) {
+                terminalStatus = "error";
+                invocationTerminalCode = "a2a_response_too_large";
+                responseText =
+                    `Error: The ${agent.name} agent returned more data than the caller can safely consume. ` +
+                        "Ask it for a concise synthesis or a retrievable artifact instead.";
+            }
+            invocationStatus =
+                terminalStatus === "done"
+                    ? "success"
+                    : terminalStatus === "pending"
+                        ? "pending"
+                        : "error";
             context.send({
                 type: "agent_call",
                 agent: agent.name,
-                status: "done",
+                status: terminalStatus,
                 agentCallId,
+                ...(invocationTaskId ? { taskId: invocationTaskId } : {}),
                 durationMs: Date.now() - callStartedAt,
             });
-            return responseText || "(empty response)";
+            return (responseText || `Error: The ${agent.name} agent returned no result.`);
         }
         // No context — use the async + poll call so we don't get cut off at the
         // serverless gateway's ~30s timeout. callAgent defaults to async:true.
@@ -525,24 +691,73 @@ export async function run(args, context, selfAppId) {
             returnRecoverableArtifactsOnTimeout: false,
         });
         const sanitized = formatDownstreamLlmCredentialFailure(agent.name, response) ?? response;
-        return expandRelativeUrls(sanitized, agent.url) || "(empty response)";
+        const expanded = expandRelativeUrls(sanitized, agent.url);
+        if (!expanded) {
+            invocationStatus = "error";
+            invocationTerminalCode = "empty_agent_response";
+            return "Error: The remote agent returned no result.";
+        }
+        if (expanded.length > MAX_A2A_CALLER_RESPONSE_CHARS) {
+            invocationStatus = "error";
+            invocationTerminalCode = "a2a_response_too_large";
+            return (`Error: The ${agent.name} agent returned more data than the caller can safely consume. ` +
+                "Ask it for a concise synthesis or a retrievable artifact instead.");
+        }
+        invocationStatus = "success";
+        return expanded;
     }
     catch (err) {
         const msg = err?.message ?? String(err);
         const credentialMessage = formatDownstreamLlmCredentialFailure(agent.name, err);
         if (credentialMessage)
             return credentialMessage;
+        const terminal = terminalTaskError(err);
+        if (terminal?.state === "input-required") {
+            invocationStatus = "pending";
+            invocationTaskId = terminal.taskId;
+            invocationTerminalCode = terminal.errorCode ?? "input_required";
+            return formatInputRequiredWaitInstruction(agent.name, terminal, agentIdOrName);
+        }
+        if (terminal) {
+            invocationStatus = "error";
+            invocationTaskId = terminal.taskId;
+            invocationTerminalCode = terminal.errorCode ?? terminal.state;
+            return (`Error calling ${agent.name}: remote task ${terminal.state}` +
+                (terminal.errorCode ? ` (${terminal.errorCode})` : "") +
+                (terminal.taskId ? ` [taskId: ${terminal.taskId}]` : "") +
+                (terminal.responseText ? `: ${terminal.responseText}` : ""));
+        }
         const timeoutTaskId = getA2ATaskTimeoutTaskId(err);
         if (timeoutTaskId) {
+            invocationStatus = "pending";
+            invocationTaskId = timeoutTaskId;
+            invocationTerminalCode = "timeout_pending";
             return formatExistingTaskWaitInstruction(agent.name, timeoutTaskId, agentIdOrName);
         }
         // Friendlier message for the common timeout case so the calling agent can
         // decide whether to give up or retry.
         if (/timeout|did not complete|Inactivity|504/i.test(msg)) {
-            return `The ${agent.name} agent is taking longer than expected. Please try again, ask a simpler question, or open the ${agent.name} app directly.`;
+            invocationStatus = "error";
+            invocationTerminalCode = "timeout_without_task";
+            return `Error calling ${agent.name}: the remote request timed out before a task id could be recovered.`;
         }
+        invocationStatus = "error";
+        invocationTerminalCode = "call_failed";
         return `Error calling ${agent.name}: ${msg}`;
     }
+    finally {
+        trackA2AInvocation({
+            invocationId,
+            callerApp: selfAppId,
+            targetApp,
+            mode: taskId ? "task_poll" : "message",
+            status: invocationStatus,
+            startedAt: invocationStartedAt,
+            taskId: invocationTaskId,
+            terminalCode: invocationTerminalCode,
+            correlation,
+        });
+    }
 }
 async function invokeReadOnlyAppAction(agent, action, input, correlation) {
     const callerEmail = getRequestUserEmail();
@@ -588,6 +803,16 @@ function formatExistingTaskWaitInstruction(agentName, taskId, agentIdOrName) {
         `Do not send ${agentName} a new check-in or follow-up message; that would start duplicate work. ` +
         `Call call-agent again with agent="${agentIdOrName}" and taskId="${taskId}" (omit message) to continue waiting for this same task.`);
 }
+function formatInputRequiredWaitInstruction(agentName, terminal, agentIdOrName) {
+    const detail = terminal.responseText?.trim();
+    if (!terminal.taskId) {
+        return ((detail ? `${detail}\n\n` : "") +
+            `Pending: The ${agentName} agent needs input before it can continue.`);
+    }
+    return ((detail ? `${detail}\n\n` : "") +
+        `The ${agentName} agent is waiting for input under taskId "${terminal.taskId}". ` +
+        `After providing or approving the requested input, call call-agent with agent="${agentIdOrName}" and taskId="${terminal.taskId}" (omit message) to continue this same task. Do not start a new message for this work.`);
+}
 async function enqueueIntegrationContinuationIfPossible(taskId, agent, message, ownerEmail) {
     const integration = getIntegrationRequestContext();
     if (!integration || !ownerEmail)