@agent-native/core 0.108.0 → 0.109.1

package/corpus/core/src/a2a/handlers.ts

@@ -1,3 +1,5 @@
+import crypto from "node:crypto";
+
 import { setResponseHeader, setResponseStatus } from "h3";
 
 import {
@@ -7,18 +9,22 @@ import {
   isAgentChatDurableBackgroundEnabled,
   resolveAgentChatProcessRunDispatchPath,
 } from "../agent/durable-background.js";
+import { trackingIdentityProperties } from "../observability/tracking-identity.js";
 import { withConfiguredAppBasePath } from "../server/app-base-path.js";
 import { getOrigin, isConfiguredAppOrigin } from "../server/google-oauth.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { agentChat } from "../shared/agent-chat.js";
+import { track } from "../tracking/registry.js";
 import {
   hasConfiguredA2ASecret,
   isA2AProductionRuntime,
 } from "./auth-policy.js";
+import { sanitizeA2ACorrelationMetadata } from "./correlation.js";
 import {
   createTask,
+  createOrReuseTask,
   getTask,
-  getTaskOwner,
+  getTaskOwnership,
   updateTask,
   claimA2ATaskForProcessing,
   getA2ATaskDispatchState,
@@ -28,6 +34,8 @@ import {
   touchQueuedA2ATaskDispatch,
   touchProcessingA2ATask,
   pauseProcessingA2ATask,
+  MAX_A2A_IDEMPOTENCY_KEY_CHARS,
+  A2A_PERSONAL_OWNER_SCOPE,
 } from "./task-store.js";
 import type {
   A2AApprovedAction,
@@ -49,6 +57,9 @@ const A2A_QUEUED_DISPATCH_STUCK_AFTER_MS = 10_000;
 const A2A_PROCESSING_STUCK_AFTER_MS = 5 * 60 * 1000;
 const A2A_PROCESSING_HEARTBEAT_MS = 30_000;
 const MAX_A2A_APPROVED_ACTIONS = 10;
+const MAX_A2A_DIRECT_ACTION_NAME_CHARS = 200;
+const MAX_A2A_DIRECT_ACTION_INPUT_BYTES = 64 * 1024;
+const A2A_READ_INVOKE_EVENT = "$a2a_read_invoke";
 
 function trustedApprovedActions(
   value: unknown,
@@ -578,6 +589,22 @@ async function runHandlerAndPersist(
   }
 }
 
+function verifiedTaskOwner(event?: any): {
+  ownerEmail: string | null;
+  ownerScope: string | null;
+} {
+  const ownerEmail =
+    (event?.context?.__a2aVerifiedEmail as string | undefined) ?? null;
+  return {
+    ownerEmail,
+    ownerScope: ownerEmail
+      ? ((event?.context?.__a2aOrgDomain as string | undefined)
+          ?.trim()
+          .toLowerCase() ?? A2A_PERSONAL_OWNER_SCOPE)
+      : null,
+  };
+}
+
 async function handleSend(
   params: Record<string, unknown>,
   config: A2AConfig,
@@ -604,8 +631,31 @@ async function handleSend(
   // on every subsequent tasks/get and tasks/cancel call. Caller-supplied
   // metadata.userEmail is NEVER used for ownership; that would re-introduce
   // the IDOR class fixed here.
-  const ownerEmailForTask =
-    (event?.context?.__a2aVerifiedEmail as string | undefined) ?? null;
+  const { ownerEmail: ownerEmailForTask, ownerScope: ownerScopeForTask } =
+    verifiedTaskOwner(event);
+  let idempotencyKey: string | undefined;
+  if (ownerEmailForTask && params.idempotencyKey !== undefined) {
+    if (typeof params.idempotencyKey !== "string") {
+      return {
+        ...jsonRpcError(
+          0,
+          -32602,
+          "Invalid params: idempotencyKey must be a string",
+        ),
+        _id: 0,
+      };
+    }
+    idempotencyKey = params.idempotencyKey.trim();
+    if (
+      !idempotencyKey ||
+      idempotencyKey.length > MAX_A2A_IDEMPOTENCY_KEY_CHARS
+    ) {
+      return {
+        ...jsonRpcError(0, -32602, "Invalid params: idempotencyKey is invalid"),
+        _id: 0,
+      };
+    }
+  }
 
   // Async mode: return the task immediately in `working` state, run the
   // handler in the background, and let the caller poll `tasks/get`. This is
@@ -618,6 +668,7 @@ async function handleSend(
   // production — see the additional gate below.
   const asyncMode =
     params.async === true || (event && event.context?.__a2aForceAsync === true);
+  if (!asyncMode) idempotencyKey = undefined;
 
   if (asyncMode) {
     // Refuse async mode entirely when no auth is configured in production.
@@ -665,12 +716,20 @@ async function handleSend(
         approvedActions: approvedActions ?? null,
       },
     };
-    const task = await createTask(
+    const { task, reused } = await createOrReuseTask(
       message,
       contextId,
       taskMetadata,
       ownerEmailForTask,
+      ownerScopeForTask,
+      idempotencyKey,
     );
+    if (reused) {
+      return {
+        ...jsonRpcResult(0, sanitizeTaskForResponse(task)),
+        _id: 0,
+      };
+    }
     const working = await updateTask(task.id, { state: "working" });
 
     // Awaited, not fire-and-forget: this handler is about to return, and a
@@ -693,12 +752,20 @@ async function handleSend(
   }
 
   return withA2ARequestContext(metadata, event, async () => {
-    const task = await createTask(
+    const { task, reused } = await createOrReuseTask(
       message,
       contextId,
       undefined,
       ownerEmailForTask,
+      ownerScopeForTask,
+      idempotencyKey,
     );
+    if (reused) {
+      return {
+        ...jsonRpcResult(0, sanitizeTaskForResponse(task)),
+        _id: 0,
+      };
+    }
     await updateTask(task.id, { state: "working" });
 
     const ctx = makeHandlerContext(
@@ -788,8 +855,8 @@ async function handleStream(
   const contextId = params.contextId as string | undefined;
   const metadata = params.metadata as Record<string, unknown> | undefined;
   const approvedActions = trustedApprovedActions(params.approvedActions, event);
-  const ownerEmailForTask =
-    (event?.context?.__a2aVerifiedEmail as string | undefined) ?? null;
+  const { ownerEmail: ownerEmailForTask, ownerScope: ownerScopeForTask } =
+    verifiedTaskOwner(event);
 
   await withA2ARequestContext(metadata, event, async () => {
     const task = await createTask(
@@ -797,6 +864,7 @@ async function handleStream(
       contextId,
       undefined,
       ownerEmailForTask,
+      ownerScopeForTask,
     );
 
     await updateTask(task.id, { state: "working" });
@@ -877,16 +945,23 @@ const SENSITIVE_METADATA_KEYS = new Set([
 
 function sanitizeTaskForResponse(task: any): any {
   if (!task || typeof task !== "object") return task;
-  if (!task.metadata || typeof task.metadata !== "object") return task;
+  const {
+    ownerEmail: _ownerEmail,
+    ownerScope: _ownerScope,
+    ...publicTask
+  } = task;
+  if (!publicTask.metadata || typeof publicTask.metadata !== "object") {
+    return publicTask;
+  }
 
-  const meta = task.metadata as Record<string, unknown>;
+  const meta = publicTask.metadata as Record<string, unknown>;
   const publicMeta: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(meta)) {
     if (k === "__a2a_processor") continue;
     if (SENSITIVE_METADATA_KEYS.has(k)) continue;
     publicMeta[k] = v;
   }
-  return { ...task, metadata: publicMeta };
+  return { ...publicTask, metadata: publicMeta };
 }
 
 /**
@@ -905,6 +980,7 @@ function sanitizeTaskForResponse(task: any): any {
  */
 function authorizeTaskAccess(
   taskOwnerEmail: string | null,
+  taskOwnerScope: string | null,
   event: any,
   config: A2AConfig,
 ): JsonRpcResponse | null {
@@ -926,6 +1002,15 @@ function authorizeTaskAccess(
     if (verifiedEmail.toLowerCase() !== taskOwnerEmail.toLowerCase()) {
       return jsonRpcError(0, -32001, "Task not found");
     }
+    if (taskOwnerScope) {
+      const verifiedScope =
+        (event?.context?.__a2aOrgDomain as string | undefined)
+          ?.trim()
+          .toLowerCase() ?? A2A_PERSONAL_OWNER_SCOPE;
+      if (verifiedScope !== taskOwnerScope.toLowerCase()) {
+        return jsonRpcError(0, -32001, "Task not found");
+      }
+    }
   }
   // Legacy row (no owner_email recorded). The route-level auth gate is the
   // only thing protecting it — fall through and serve.
@@ -941,8 +1026,13 @@ async function handleGet(
   if (!id) {
     return jsonRpcError(0, -32602, "Invalid params: id required");
   }
-  const ownerEmail = await getTaskOwner(id);
-  const denied = authorizeTaskAccess(ownerEmail, event, config);
+  const ownership = await getTaskOwnership(id);
+  const denied = authorizeTaskAccess(
+    ownership.ownerEmail,
+    ownership.ownerScope,
+    event,
+    config,
+  );
   if (denied) return denied;
 
   const task = await getTask(id);
@@ -1036,8 +1126,13 @@ async function handleCancel(
   if (!id) {
     return jsonRpcError(0, -32602, "Invalid params: id required");
   }
-  const ownerEmail = await getTaskOwner(id);
-  const denied = authorizeTaskAccess(ownerEmail, event, config);
+  const ownership = await getTaskOwnership(id);
+  const denied = authorizeTaskAccess(
+    ownership.ownerEmail,
+    ownership.ownerScope,
+    event,
+    config,
+  );
   if (denied) return denied;
 
   const task = await updateTask(id, { state: "canceled" });
@@ -1047,6 +1142,93 @@ async function handleCancel(
   return jsonRpcResult(0, sanitizeTaskForResponse(task));
 }
 
+async function handleInvokeReadOnlyAction(
+  params: Record<string, unknown>,
+  event: any,
+  config: A2AConfig,
+): Promise<JsonRpcResponse> {
+  const action = typeof params.action === "string" ? params.action.trim() : "";
+  const input = params.input ?? {};
+
+  if (!action) {
+    return jsonRpcError(0, -32602, "Invalid params: action required");
+  }
+  if (action.length > MAX_A2A_DIRECT_ACTION_NAME_CHARS) {
+    return jsonRpcError(0, -32602, "Invalid params: action is too long");
+  }
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return jsonRpcError(0, -32602, "Invalid params: input must be an object");
+  }
+  let inputBytes: number;
+  try {
+    inputBytes = Buffer.byteLength(JSON.stringify(input), "utf8");
+  } catch {
+    return jsonRpcError(0, -32602, "Invalid params: input must be JSON-safe");
+  }
+  if (inputBytes > MAX_A2A_DIRECT_ACTION_INPUT_BYTES) {
+    return jsonRpcError(0, -32602, "Invalid params: input is too large");
+  }
+  if (
+    !event?.context?.__a2aVerifiedEmail ||
+    event?.context?.__a2aAudienceVerified !== true
+  ) {
+    return jsonRpcError(
+      0,
+      -32001,
+      "A verified, audience-bound user identity is required for direct action invocation",
+    );
+  }
+  if (!config.executeReadOnlyAction) {
+    return jsonRpcError(0, -32601, "Direct action invocation not supported");
+  }
+
+  const startedAt = Date.now();
+  const correlation = sanitizeA2ACorrelationMetadata(params.metadata);
+  const invocationId = crypto.randomUUID();
+  const verifiedEmail = event.context.__a2aVerifiedEmail as string;
+  const emitTracking = (status: "completed" | "failed") => {
+    const identity = trackingIdentityProperties();
+    track(
+      A2A_READ_INVOKE_EVENT,
+      {
+        ...identity,
+        action,
+        receiver_app: config.appId ?? identity.app ?? config.name,
+        caller_app: correlation.callerApp ?? "unknown",
+        duration_ms: Math.max(0, Date.now() - startedAt),
+        status,
+        invocation_id: invocationId,
+        ...(correlation.parentRunId
+          ? { parent_run_id: correlation.parentRunId }
+          : {}),
+        ...(correlation.parentTurnId
+          ? { parent_turn_id: correlation.parentTurnId }
+          : {}),
+        ...(correlation.invocationId
+          ? { caller_invocation_id: correlation.invocationId }
+          : {}),
+      },
+      { userId: verifiedEmail },
+    );
+  };
+
+  try {
+    const result = await withA2ARequestContext(undefined, event, () =>
+      config.executeReadOnlyAction!({
+        action,
+        input: input as Record<string, unknown>,
+        invocationId,
+      }),
+    );
+    emitTracking(result.status);
+    return jsonRpcResult(0, { action, ...result });
+  } catch (error) {
+    emitTracking("failed");
+    console.error(`[a2a] Direct action ${action} failed:`, error);
+    return jsonRpcError(0, -32000, "Direct action invocation failed");
+  }
+}
+
 /**
  * H3-compatible JSON-RPC handler. Returns JSON directly (H3 serializes it).
  * Streaming is handled via H3's node response when needed.
@@ -1093,6 +1275,10 @@ export async function handleJsonRpcH3(
       const result = await handleCancel(params, event, config);
       return { ...result, id } as JsonRpcResponse;
     }
+    case "actions/invoke": {
+      const result = await handleInvokeReadOnlyAction(params, event, config);
+      return { ...result, id } as JsonRpcResponse;
+    }
     default:
       return jsonRpcError(id, -32601, `Method not found: ${body.method}`);
   }

package/corpus/core/src/a2a/index.ts

@@ -4,11 +4,12 @@ export type { A2ATokenPayload } from "./server.js";
 export { generateAgentCard } from "./agent-card.js";
 
 // Client
-export { A2AClient, callAgent, signA2AToken } from "./client.js";
+export { A2AClient, callAction, callAgent, signA2AToken } from "./client.js";
 export {
   AgentInvocationError,
   buildAgentInvocationPrompt,
   invokeAgent,
+  invokeAgentAction,
   looksLikeAgentUrl,
   resolveAgentInvocationTarget,
 } from "./invoke.js";
@@ -33,11 +34,16 @@ export type {
   Artifact,
   JsonRpcRequest,
   JsonRpcResponse,
+  A2ACorrelationMetadata,
+  A2AReadOnlyActionInvocation,
+  A2AReadOnlyActionResult,
 } from "./types.js";
 export type {
   AgentInvocationErrorCode,
+  AgentActionInvocationResult,
   AgentInvocationResult,
   AgentInvocationRuntime,
+  InvokeAgentActionOptions,
   InvokeAgentOptions,
   ResolveAgentInvocationTargetOptions,
   ResolvedAgentInvocationTarget,

package/corpus/core/src/a2a/invoke.ts

@@ -3,11 +3,20 @@ import {
   findAgent as defaultFindAgent,
   type DiscoveredAgent,
 } from "../server/agent-discovery.js";
-import { callAgent as defaultCallAgent } from "./client.js";
+import {
+  callAction as defaultCallAction,
+  callAgent as defaultCallAgent,
+} from "./client.js";
+import type {
+  A2ACorrelationMetadata,
+  A2AReadOnlyActionResult,
+} from "./types.js";
 
 export type AgentInvocationErrorCode =
   | "missing-target"
   | "missing-prompt"
+  | "missing-action"
+  | "invalid-input"
   | "invalid-url"
   | "self-call"
   | "not-found";
@@ -45,10 +54,17 @@ export interface AgentInvocationResult {
   responseText: string;
 }
 
+export interface AgentActionInvocationResult {
+  target: ResolvedAgentInvocationTarget;
+  action: string;
+  result: A2AReadOnlyActionResult;
+}
+
 export interface AgentInvocationRuntime {
   findAgent: typeof defaultFindAgent;
   discoverAgents: typeof defaultDiscoverAgents;
   callAgent: typeof defaultCallAgent;
+  callAction: typeof defaultCallAction;
 }
 
 export interface ResolveAgentInvocationTargetOptions {
@@ -69,6 +85,21 @@ export interface InvokeAgentOptions extends ResolveAgentInvocationTargetOptions
   timeoutMs?: number;
   pollIntervalMs?: number;
   includeInvocationHint?: boolean;
+  correlation?: A2ACorrelationMetadata;
+  idempotencyKey?: string;
+  runtime?: Partial<AgentInvocationRuntime>;
+}
+
+export interface InvokeAgentActionOptions extends ResolveAgentInvocationTargetOptions {
+  target: string;
+  action: string;
+  input?: Record<string, unknown>;
+  apiKey?: string;
+  userEmail?: string;
+  orgDomain?: string;
+  orgSecret?: string;
+  requestTimeoutMs?: number;
+  correlation?: A2ACorrelationMetadata;
   runtime?: Partial<AgentInvocationRuntime>;
 }
 
@@ -172,6 +203,8 @@ export async function invokeAgent(
     async: options.async,
     timeoutMs: options.timeoutMs,
     pollIntervalMs: options.pollIntervalMs,
+    correlation: options.correlation,
+    idempotencyKey: options.idempotencyKey,
   });
 
   return {
@@ -181,6 +214,49 @@ export async function invokeAgent(
   };
 }
 
+/**
+ * Resolve another app and execute one explicitly exposed read-only action on
+ * it. This is the fast A2A path for bounded data operations that do not need a
+ * second model to plan or synthesize.
+ */
+export async function invokeAgentAction(
+  options: InvokeAgentActionOptions,
+): Promise<AgentActionInvocationResult> {
+  const action = options.action.trim();
+  if (!action) {
+    throw new AgentInvocationError(
+      "missing-action",
+      "Error: action is required",
+      { target: options.target },
+    );
+  }
+  const input = options.input ?? {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new AgentInvocationError(
+      "invalid-input",
+      "Error: action input must be an object",
+      { target: options.target },
+    );
+  }
+
+  const target = await resolveAgentInvocationTarget(options.target, {
+    selfAppId: options.selfAppId,
+    selfUrl: options.selfUrl,
+    runtime: options.runtime,
+  });
+  const callAction = options.runtime?.callAction ?? defaultCallAction;
+  const result = await callAction(target.url, action, input, {
+    apiKey: options.apiKey,
+    userEmail: options.userEmail,
+    orgDomain: options.orgDomain,
+    orgSecret: options.orgSecret,
+    requestTimeoutMs: options.requestTimeoutMs,
+    correlation: options.correlation,
+  });
+
+  return { target, action, result };
+}
+
 export function buildAgentInvocationPrompt(
   prompt: string,
   agentUrl: string,

package/corpus/core/src/a2a/server.ts

@@ -79,7 +79,7 @@ function expectedJwtAudience(event: any | undefined): string | undefined {
     process.env.URL ||
     process.env.DEPLOY_URL ||
     process.env.BETTER_AUTH_URL;
-  if (fromEnv) return String(fromEnv);
+  if (fromEnv) return String(fromEnv).replace(/\/$/, "");
   // Best-effort: derive from the inbound request host. This is forgeable
   // (Host-header attack), but only useful as a hint when env-derived URL
   // is unset; the rest of the JWT verification still uses the secret.
@@ -440,6 +440,7 @@ export function mountA2A(
       const bearerToken = extractBearerToken(authHeader);
       let verifiedCallerEmail: string | null = null;
       let verifiedOrgDomain: string | null = null;
+      let verifiedAudienceBound = false;
       let legacyApiKeyAuthenticated = false;
       let bearerTokenRejectedByJwt = false;
 
@@ -456,6 +457,14 @@ export function mountA2A(
         const tokenPayload = await verifyA2AToken(bearerToken, event);
         verifiedCallerEmail = tokenPayload.email;
         verifiedOrgDomain = tokenPayload.orgDomain;
+        if (verifiedCallerEmail) {
+          try {
+            verifiedAudienceBound =
+              typeof jose.decodeJwt(bearerToken).aud !== "undefined";
+          } catch {
+            verifiedAudienceBound = false;
+          }
+        }
         bearerTokenRejectedByJwt = !verifiedCallerEmail;
       }
 
@@ -532,6 +541,9 @@ export function mountA2A(
       if (verifiedCallerEmail) {
         event.context.__a2aVerifiedEmail = verifiedCallerEmail;
       }
+      if (verifiedAudienceBound) {
+        event.context.__a2aAudienceVerified = true;
+      }
       if (verifiedOrgDomain) {
         event.context.__a2aOrgDomain = verifiedOrgDomain;
       }