@agent-native/core 0.108.0 → 0.109.1

package/corpus/core/src/scripts/call-agent.ts

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 import {
   A2ATaskTimeoutError,
@@ -6,7 +6,12 @@ import {
   shouldPreferGlobalA2ASecret,
   signA2AToken,
 } from "../a2a/client.js";
-import type { A2AApprovedAction, Task } from "../a2a/types.js";
+import { invokeAgentAction } from "../a2a/invoke.js";
+import type {
+  A2AApprovedAction,
+  A2ACorrelationMetadata,
+  Task,
+} from "../a2a/types.js";
 import {
   formatLlmCredentialErrorMessage,
   isLlmCredentialError,
@@ -27,6 +32,38 @@ const DEFAULT_SERVERLESS_INTEGRATION_A2A_TIMEOUT_MS = 18_000;
 const NETLIFY_INTEGRATION_A2A_TIMEOUT_MS = 2_000;
 const INTEGRATION_A2A_TOKEN_TTL = "30m";
 
+function buildDelegationCorrelation(
+  context: ActionRunContext | undefined,
+  selfAppId: string | undefined,
+  invocationId?: string,
+): A2ACorrelationMetadata {
+  return {
+    ...(selfAppId?.trim() ? { callerApp: selfAppId.trim() } : {}),
+    ...(context?.threadId ? { callerThreadId: context.threadId } : {}),
+    ...(context?.runId ? { parentRunId: context.runId } : {}),
+    ...(context?.turnId ? { parentTurnId: context.turnId } : {}),
+    ...(invocationId ? { invocationId } : {}),
+  };
+}
+
+function buildMessageIdempotencyKey(
+  originatingTurnId: string | undefined,
+  target: string,
+  exactMessage: string,
+): string | undefined {
+  if (!originatingTurnId) return undefined;
+  const digest = createHash("sha256")
+    .update(
+      JSON.stringify({
+        originatingTurnId,
+        target,
+        message: exactMessage,
+      }),
+    )
+    .digest("hex");
+  return `v1:${digest}`;
+}
+
 function parseTimeoutMs(value: string | undefined): number | undefined {
   if (!value) return undefined;
   const parsed = Number(value);
@@ -94,12 +131,13 @@ function formatDownstreamLlmCredentialFailure(
 
 export const tool: ActionTool = {
   description:
-    "Call a DIFFERENT, separately-deployed agent app to ask a question or delegate a task. This is strictly for cross-app A2A communication — for example, asking the mail agent to send an email while you are the calendar 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. " +
+    "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. " +
     '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. " +
     '(b) If it does NOT contain a URL/ID and the user asked for one, say so explicitly (e.g. "the agent created the deck/image but didn\'t return a link — open the app directly to view it"). NEVER invent a URL, slug, or path — guessing produces broken links that look real. ' +
-    "(c) If the downstream response reports missing credentials, never repeat raw env var names, Vault key names, token names, secret names, or other credential identifiers. Tell the user the target app needs its LLM/provider connection configured.",
+    "(c) If the downstream response reports missing credentials, never repeat raw env var names, Vault key names, token names, secret names, or other credential identifiers. Tell the user the target app needs its LLM/provider connection configured. " +
+    "(d) A bounded wait can expire while the remote task is still healthy. The result will include its taskId and exact retry instructions. Continue polling that SAME task with taskId; NEVER send a new check-in/follow-up message, because that starts duplicate downstream work.",
   parameters: {
     type: "object",
     properties: {
@@ -110,7 +148,24 @@ export const tool: ActionTool = {
       },
       message: {
         type: "string",
-        description: "The message/question to send to the other agent",
+        description:
+          "The message/question to send when starting a new task. Omit when taskId is provided.",
+      },
+      taskId: {
+        type: "string",
+        description:
+          "Existing A2A task ID returned by a timed-out call. Polls that exact task without sending a new message. Never create a fresh check-in message for work that already has a taskId.",
+      },
+      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.",
+      },
+      input: {
+        type: "object",
+        description:
+          "Complete input object for action. The target app validates it and refuses actions that are not explicitly exposed read-only operations.",
+        additionalProperties: true,
       },
       approvedActions: {
         type: "array",
@@ -126,7 +181,7 @@ export const tool: ActionTool = {
         },
       },
     },
-    required: ["agent", "message"],
+    required: ["agent"],
   },
 };
 
@@ -137,12 +192,23 @@ export async function run(
 ): Promise<string> {
   const agentIdOrName = String(args.agent ?? "");
   const message = String(args.message ?? "");
+  const taskId = String(args.taskId ?? "").trim();
+  const action = String(args.action ?? "").trim();
+  const input = args.input ?? {};
   const approvedActions = Array.isArray(args.approvedActions)
     ? (args.approvedActions as A2AApprovedAction[])
     : undefined;
 
   if (!agentIdOrName) return "Error: --agent is required";
-  if (!message) return "Error: --message is required";
+  if (!message && !taskId && !action) {
+    return "Error: --message, --taskId, or --action is required";
+  }
+  if (action && (message || taskId)) {
+    return "Error: --action direct-invoke mode cannot be combined with --message or --taskId";
+  }
+  if (action && (!input || typeof input !== "object" || Array.isArray(input))) {
+    return "Error: --input must be an object when --action is provided";
+  }
 
   // Prevent self-calls — the agent must use its own registered tools instead
   if (selfAppId && agentIdOrName.toLowerCase() === selfAppId.toLowerCase()) {
@@ -157,16 +223,43 @@ export async function run(
     return `Error: Agent "${agentIdOrName}" not found. Available agents: ${available || "(none)"}`;
   }
 
+  const correlation = buildDelegationCorrelation(context, selfAppId);
+  const idempotencyKey =
+    message && !taskId
+      ? buildMessageIdempotencyKey(context?.turnId, agent.url, message)
+      : undefined;
+
+  if (action) {
+    if (context?.send) {
+      context.send({ type: "agent_call", agent: agent.name, status: "start" });
+    }
+    try {
+      const output = await invokeReadOnlyAppAction(
+        agent,
+        action,
+        input as Record<string, unknown>,
+        buildDelegationCorrelation(context, selfAppId, randomUUID()),
+      );
+      return output;
+    } finally {
+      if (context?.send) {
+        context.send({ type: "agent_call", agent: agent.name, status: "done" });
+      }
+    }
+  }
+
   // Append a small cross-app hint to the outgoing message so the receiving
   // agent (which may be on an older deploy without the receiver-side hint
   // in handlers.ts) still emits fully-qualified URLs. This is belt-and-
   // suspenders with the receiver hint — but it works against any current
   // deployment, no redeploy required.
-  const messageWithHint =
-    `${message}${integrationSourceContextHint()}\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. ` +
-    `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.]`;
+  const messageWithHint = taskId
+    ? ""
+    : `${message}${integrationSourceContextHint()}\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. ` +
+      `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.]`;
 
   try {
     // If we have a send context, use streaming so the UI shows progressive text
@@ -228,8 +321,9 @@ export async function run(
 
       let responseText = "";
       let lastSentLength = 0;
-      const existingContinuationText =
-        await formatExistingIntegrationContinuationIfRetry(agent, message);
+      const existingContinuationText = taskId
+        ? null
+        : await formatExistingIntegrationContinuationIfRetry(agent, message);
       if (existingContinuationText) return existingContinuationText;
 
       context.send({
@@ -338,13 +432,15 @@ export async function run(
           orgDomain: callerOrgDomain,
           orgSecret: callerOrgSecret,
           approvedActions,
+          contextId: context.threadId,
+          correlation,
+          idempotencyKey,
+          ...(taskId ? { taskId } : {}),
           onUpdate: onRemotePollUpdate,
+          returnRecoverableArtifactsOnTimeout: false,
           ...(callTimeoutMs
             ? {
                 timeoutMs: callTimeoutMs,
-                // Integration callers must keep the timeout task id so the
-                // catch below can enqueue durable continuation polling.
-                returnRecoverableArtifactsOnTimeout: false,
               }
             : {}),
         });
@@ -387,8 +483,11 @@ export async function run(
                 agent.url,
               );
             } else {
-              const reason = pollErr?.message ?? "unknown error";
-              responseText = `The ${agent.name} agent is taking longer than expected and didn't reply in time. (${reason})`;
+              responseText = formatExistingTaskWaitInstruction(
+                agent.name,
+                timeoutTaskId,
+                agentIdOrName,
+              );
             }
           }
         } else {
@@ -427,6 +526,11 @@ export async function run(
       orgDomain: domain,
       orgSecret,
       approvedActions,
+      contextId: context?.threadId,
+      correlation,
+      idempotencyKey,
+      ...(taskId ? { taskId } : {}),
+      returnRecoverableArtifactsOnTimeout: false,
     });
     const sanitized =
       formatDownstreamLlmCredentialFailure(agent.name, response) ?? response;
@@ -438,6 +542,14 @@ export async function run(
       err,
     );
     if (credentialMessage) return credentialMessage;
+    const timeoutTaskId = getA2ATaskTimeoutTaskId(err);
+    if (timeoutTaskId) {
+      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)) {
@@ -447,6 +559,65 @@ export async function run(
   }
 }
 
+async function invokeReadOnlyAppAction(
+  agent: { name: string; url: string },
+  action: string,
+  input: Record<string, unknown>,
+  correlation: A2ACorrelationMetadata,
+): Promise<string> {
+  const callerEmail = getRequestUserEmail();
+  if (!callerEmail) {
+    return `Error calling ${agent.name} action ${action}: a signed-in user identity is required`;
+  }
+
+  let callerOrgDomain: string | undefined;
+  let callerOrgSecret: string | undefined;
+  const orgId = getRequestOrgId();
+  if (orgId) {
+    try {
+      callerOrgDomain = (await getOrgDomain(orgId)) ?? undefined;
+    } catch {}
+    try {
+      callerOrgSecret = (await getOrgA2ASecret(orgId)) ?? undefined;
+    } catch {}
+  }
+
+  if (!callerOrgSecret && !process.env.A2A_SECRET) {
+    return `Error calling ${agent.name} action ${action}: direct cross-app reads require A2A identity verification`;
+  }
+
+  try {
+    const invocation = await invokeAgentAction({
+      target: agent.url,
+      action,
+      input,
+      userEmail: callerEmail,
+      orgDomain: callerOrgDomain,
+      orgSecret: callerOrgSecret,
+      correlation,
+    });
+    return invocation.result.status === "completed"
+      ? invocation.result.output
+      : `Error calling ${agent.name} action ${action}: ${invocation.result.output}`;
+  } catch (error) {
+    return `Error calling ${agent.name} action ${action}: ${
+      error instanceof Error ? error.message : String(error)
+    }`;
+  }
+}
+
+function formatExistingTaskWaitInstruction(
+  agentName: string,
+  taskId: string,
+  agentIdOrName: string,
+): string {
+  return (
+    `The ${agentName} task is still running under taskId "${taskId}". ` +
+    `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.`
+  );
+}
+
 async function enqueueIntegrationContinuationIfPossible(
   taskId: string,
   agent: { name: string; url: string },

package/corpus/core/src/server/agent-chat/action-filters-a2a.ts

@@ -15,6 +15,10 @@ import {
 } from "../../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
 import type { AgentChatEvent } from "../../agent/types.js";
+import {
+  isAuthenticatedReadAction,
+  isAutoReadExcludedActionName,
+} from "../../mcp/build-server.js";
 import { withConfiguredAppBasePath } from "../app-base-path.js";
 import type { AgentChatPluginOptions } from "./plugin-options.js";
 
@@ -61,6 +65,42 @@ export function filterPublicAgentActions(
   );
 }
 
+/**
+ * Direct A2A action calls share the authenticated external-agent policy with
+ * MCP, but remain stricter: only explicitly exposed, authenticated read-only
+ * actions can skip the receiver's model loop.
+ */
+export function filterDirectA2AActions(
+  actions: Record<string, ActionEntry>,
+  options: Pick<AgentChatPluginOptions, "connectorCatalog" | "externalAgents">,
+): Record<string, ActionEntry> {
+  const catalog = new Set(options.connectorCatalog ?? []);
+  const denied = new Set(options.externalAgents?.denyActions ?? []);
+  const autoReads = options.externalAgents?.authenticatedReads === "auto";
+
+  return Object.fromEntries(
+    Object.entries(actions).filter(([name, entry]) => {
+      const exposure = entry.publicAgent;
+      const selected =
+        catalog.has(name) ||
+        (autoReads &&
+          isAuthenticatedReadAction(entry) &&
+          !isAutoReadExcludedActionName(name));
+      return (
+        selected &&
+        !denied.has(name) &&
+        entry.agentTool !== false &&
+        entry.readOnly === true &&
+        exposure?.expose === true &&
+        exposure.readOnly === true &&
+        exposure.requiresAuth === true &&
+        (entry.needsApproval === undefined || entry.needsApproval === false) &&
+        exposure.isConsequential !== true
+      );
+    }),
+  );
+}
+
 export function buildPublicAgentA2ASkills(
   actions: Record<string, ActionEntry>,
 ): Array<{
@@ -151,34 +191,81 @@ function formatA2ATerminalError(
 
 type A2AAgentLoopRunner = typeof runAgentLoopDirectWithSoftTimeout;
 
-function runDelegatedAgentLoop(
+export interface DelegatedAgentLoopTelemetry {
+  runId: string;
+  threadId: string | null;
+  userId: string | null;
+  delegation: {
+    protocol: "a2a" | "mcp";
+    callerApp?: string;
+    taskId?: string;
+    parentRunId?: string;
+    parentTurnId?: string;
+  };
+}
+
+interface DelegatedAgentLoopOptions {
+  runner?: A2AAgentLoopRunner;
+  telemetry?: DelegatedAgentLoopTelemetry;
+}
+
+async function runDelegatedAgentLoop(
   runOptions: Parameters<A2AAgentLoopRunner>[0],
   pluginOptions: Pick<
     AgentChatPluginOptions,
     "finalResponseGuard" | "runSoftTimeoutMs"
   >,
   timeoutOptions: Parameters<A2AAgentLoopRunner>[2],
-  runner: A2AAgentLoopRunner,
+  options: DelegatedAgentLoopOptions,
 ) {
-  return runner(
-    {
-      ...runOptions,
-      // Delegated runs resolve their own model and do not pass through the
-      // interactive request handler's output-token setup. Use the same
-      // model-aware headroom here so reasoning models (notably GPT-5.x) do
-      // not spend the small internal default entirely on reasoning before
-      // emitting a tool call or answer. Preserve explicit test/caller values.
-      maxOutputTokens:
-        runOptions.maxOutputTokens ??
-        resolveMainChatMaxOutputTokens(runOptions.model),
-      reasoningEffort:
-        runOptions.reasoningEffort ??
-        resolveAgentRequestReasoningEffort({ model: runOptions.model }),
-      finalResponseGuard: pluginOptions.finalResponseGuard,
-    },
-    pluginOptions.runSoftTimeoutMs,
-    timeoutOptions,
-  );
+  const runner = options.runner ?? runAgentLoopDirectWithSoftTimeout;
+  const resolvedRunOptions = {
+    ...runOptions,
+    // Delegated runs resolve their own model and do not pass through the
+    // interactive request handler's output-token setup. Use the same
+    // model-aware headroom here so reasoning models (notably GPT-5.x) do
+    // not spend the small internal default entirely on reasoning before
+    // emitting a tool call or answer. Preserve explicit test/caller values.
+    maxOutputTokens:
+      runOptions.maxOutputTokens ??
+      resolveMainChatMaxOutputTokens(runOptions.model),
+    reasoningEffort:
+      runOptions.reasoningEffort ??
+      resolveAgentRequestReasoningEffort({ model: runOptions.model }),
+    finalResponseGuard: pluginOptions.finalResponseGuard,
+  };
+  const execute = (loopOptions = resolvedRunOptions) =>
+    runner(loopOptions, pluginOptions.runSoftTimeoutMs, timeoutOptions);
+
+  if (!options.telemetry) return execute();
+
+  let instrumented = false;
+  try {
+    const { getObservabilityConfig, instrumentAgentLoop } =
+      await import("../../observability/traces.js");
+    const config = await getObservabilityConfig();
+    if (config.enabled) {
+      instrumented = true;
+      return await instrumentAgentLoop({
+        runAgentLoop: (loopOptions) =>
+          execute(
+            loopOptions as Parameters<A2AAgentLoopRunner>[0] &
+              typeof resolvedRunOptions,
+          ),
+        loopOpts: resolvedRunOptions,
+        runId: options.telemetry.runId,
+        threadId: options.telemetry.threadId,
+        userId: options.telemetry.userId,
+        config,
+        delegation: options.telemetry.delegation,
+      });
+    }
+  } catch (error) {
+    // Match interactive chat: setup failures fall through, but a failure from
+    // inside an instrumented agent loop is the real run failure and rethrows.
+    if (instrumented) throw error;
+  }
+  return execute();
 }
 
 /**
@@ -196,13 +283,13 @@ export function runA2AAgentLoop(
     "finalResponseGuard" | "runSoftTimeoutMs"
   >,
   timeoutOptions: Parameters<A2AAgentLoopRunner>[2],
-  runner: A2AAgentLoopRunner = runAgentLoopDirectWithSoftTimeout,
+  options: DelegatedAgentLoopOptions = {},
 ) {
   return runDelegatedAgentLoop(
     runOptions,
     pluginOptions,
     timeoutOptions,
-    runner,
+    options,
   );
 }
 
@@ -218,13 +305,13 @@ export function runMCPAgentLoop(
     "finalResponseGuard" | "runSoftTimeoutMs"
   >,
   timeoutOptions: Parameters<A2AAgentLoopRunner>[2],
-  runner: A2AAgentLoopRunner = runAgentLoopDirectWithSoftTimeout,
+  options: DelegatedAgentLoopOptions = {},
 ) {
   return runDelegatedAgentLoop(
     runOptions,
     pluginOptions,
     timeoutOptions,
-    runner,
+    options,
   );
 }