@agent-native/core 0.101.7 → 0.101.11

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

@@ -27,8 +27,10 @@ import {
   settleProcessingA2ATask,
   touchQueuedA2ATaskDispatch,
   touchProcessingA2ATask,
+  pauseProcessingA2ATask,
 } from "./task-store.js";
 import type {
+  A2AApprovedAction,
   A2AConfig,
   A2AHandler,
   A2AHandlerContext,
@@ -46,6 +48,30 @@ const PORTABLE_FALLBACK_HANDOFF_TIMEOUT_MS = 1_000;
 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;
+
+function trustedApprovedActions(
+  value: unknown,
+  event: any | undefined,
+): A2AApprovedAction[] | undefined {
+  // Static API keys and unsigned requests do not prove which user authorized
+  // a consequential action. Only a verified identity-bearing JWT may carry
+  // chat authorization across the A2A boundary.
+  if (!event?.context?.__a2aVerifiedEmail || !Array.isArray(value)) {
+    return undefined;
+  }
+  const approved = value
+    .slice(0, MAX_A2A_APPROVED_ACTIONS)
+    .filter(
+      (candidate): candidate is A2AApprovedAction =>
+        !!candidate &&
+        typeof candidate === "object" &&
+        typeof (candidate as Record<string, unknown>).tool === "string" &&
+        !!(candidate as Record<string, unknown>).tool,
+    )
+    .map((candidate) => ({ tool: candidate.tool, input: candidate.input }));
+  return approved.length > 0 ? approved : undefined;
+}
 
 /**
  * Request origin is routing/link context, not an identity signal. Accept only
@@ -250,6 +276,9 @@ export async function processA2ATaskFromQueue(
       | Record<string, unknown>
       | null
       | undefined) ?? undefined;
+  const approvedActions = Array.isArray(processorMeta.approvedActions)
+    ? (processorMeta.approvedActions as A2AApprovedAction[])
+    : undefined;
 
   const resolvedOrgId = await resolveVerifiedA2AOrgId(
     verifiedEmail,
@@ -281,6 +310,7 @@ export async function processA2ATaskFromQueue(
           contextId,
           callerMetadata,
           event,
+          approvedActions,
         ),
     );
   } catch (err: any) {
@@ -386,6 +416,7 @@ function makeHandlerContext(
   contextId?: string,
   metadata?: Record<string, unknown>,
   event?: any,
+  approvedActions?: A2AApprovedAction[],
 ): {
   context: A2AHandlerContext;
   artifacts: Artifact[];
@@ -396,6 +427,7 @@ function makeHandlerContext(
     contextId,
     metadata,
     event,
+    approvedActions,
     writeArtifact(name, content, mimeType) {
       const artifact: Artifact = {
         name,
@@ -491,12 +523,14 @@ async function runHandlerAndPersist(
   contextId: string | undefined,
   metadata: Record<string, unknown> | undefined,
   event?: any,
+  approvedActions?: A2AApprovedAction[],
 ): Promise<void> {
   const { context, artifacts } = makeHandlerContext(
     taskId,
     contextId,
     metadata,
     event,
+    approvedActions,
   );
   try {
     const result = getHandler(config)(message, context);
@@ -510,6 +544,10 @@ async function runHandlerAndPersist(
       for await (const msg of result as AsyncGenerator<Message>) {
         lastMessage = msg;
       }
+      if (lastMessage?.metadata?.agentNativeTaskState === "input-required") {
+        await pauseProcessingA2ATask(taskId, lastMessage);
+        return;
+      }
       await settleProcessingA2ATask(taskId, {
         state: "completed",
         message: lastMessage,
@@ -520,6 +558,10 @@ async function runHandlerAndPersist(
 
     const handlerResult = await (result as Promise<A2AHandlerResult>);
     const allArtifacts = [...artifacts, ...(handlerResult.artifacts ?? [])];
+    if (handlerResult.taskState === "input-required") {
+      await pauseProcessingA2ATask(taskId, handlerResult.message);
+      return;
+    }
     await settleProcessingA2ATask(taskId, {
       state: "completed",
       message: handlerResult.message,
@@ -555,6 +597,7 @@ async function handleSend(
 
   const contextId = params.contextId as string | undefined;
   const metadata = params.metadata as Record<string, unknown> | undefined;
+  const approvedActions = trustedApprovedActions(params.approvedActions, event);
 
   // The JWT-verified caller email (set by mountA2A in server.ts) is the
   // single source of truth for task ownership — bound at creation, checked
@@ -619,6 +662,7 @@ async function handleSend(
         ...(requestOrigin ? { requestOrigin } : {}),
         contextId: contextId ?? null,
         callerMetadata: safeMetadata ?? null,
+        approvedActions: approvedActions ?? null,
       },
     };
     const task = await createTask(
@@ -642,7 +686,10 @@ async function handleSend(
       console.error("[a2a] Failed to dispatch process-task:", err);
     }
 
-    return { ...jsonRpcResult(0, working ?? task), _id: 0 };
+    return {
+      ...jsonRpcResult(0, sanitizeTaskForResponse(working ?? task)),
+      _id: 0,
+    };
   }
 
   return withA2ARequestContext(metadata, event, async () => {
@@ -659,6 +706,7 @@ async function handleSend(
       contextId,
       trustedA2AMetadata(metadata, event),
       event,
+      approvedActions,
     );
 
     try {
@@ -673,6 +721,13 @@ async function handleSend(
         for await (const msg of result as AsyncGenerator<Message>) {
           lastMessage = msg;
         }
+        if (lastMessage?.metadata?.agentNativeTaskState === "input-required") {
+          const updated = await updateTask(task.id, {
+            state: "input-required",
+            message: lastMessage,
+          });
+          return { ...jsonRpcResult(0, updated), _id: 0 };
+        }
         const updated = await updateTask(task.id, {
           state: "completed",
           message: lastMessage,
@@ -686,6 +741,13 @@ async function handleSend(
         ...ctx.artifacts,
         ...(handlerResult.artifacts ?? []),
       ];
+      if (handlerResult.taskState === "input-required") {
+        const updated = await updateTask(task.id, {
+          state: "input-required",
+          message: handlerResult.message,
+        });
+        return { ...jsonRpcResult(0, updated), _id: 0 };
+      }
       const updated = await updateTask(task.id, {
         state: "completed",
         message: handlerResult.message,
@@ -725,6 +787,7 @@ 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;
 
@@ -743,6 +806,7 @@ async function handleStream(
       contextId,
       trustedA2AMetadata(metadata, event),
       event,
+      approvedActions,
     );
 
     try {

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

@@ -1,23 +1,31 @@
 import {
   defineEventHandler,
+  setResponseHeader,
   setResponseStatus,
   getMethod,
   getRequestHeader,
 } from "h3";
 import * as jose from "jose";
 
+import { redactArgsToJson } from "../audit/redact.js";
 import {
   extractBearerToken,
   verifyInternalToken,
 } from "../integrations/internal-token.js";
 import { getH3App } from "../server/framework-request-handler.js";
 import { readBody } from "../server/h3-helpers.js";
+import { isSameOriginRequest } from "../server/request-origin.js";
 import { generateAgentCard } from "./agent-card.js";
 import {
   hasConfiguredA2ASecret,
   isA2AProductionRuntime,
 } from "./auth-policy.js";
 import { handleJsonRpcH3, processA2ATaskFromQueue } from "./handlers.js";
+import {
+  claimA2AApproval,
+  getA2AApprovalForOwner,
+  settleA2AApproval,
+} from "./task-store.js";
 import type { A2AConfig } from "./types.js";
 
 /**
@@ -235,6 +243,122 @@ export function mountA2A(
     }),
   );
 
+  // Human-only continuation for consequential A2A tool calls. The opaque id
+  // is a lookup handle, not authorization: every read and mutation also
+  // requires the task owner's live browser session. Ordinary A2A bearer
+  // tokens never reach this control plane and cannot approve themselves.
+  getH3App(nitroApp).use(
+    `${routePrefix}/a2a/approvals`,
+    defineEventHandler(async (event) => {
+      const approvalId = (event.path || "")
+        .split("?")[0]
+        .replace(/^\//, "")
+        .split("/")[0];
+      if (!approvalId) {
+        setResponseStatus(event, 404);
+        return { error: "Approval not found" };
+      }
+
+      const { getSession } = await import("../server/auth.js");
+      const session = await getSession(event);
+      if (!session?.email) {
+        setResponseStatus(event, 401);
+        return { error: "Sign in to review this approval" };
+      }
+
+      if (getMethod(event) === "GET") {
+        const approval = await getA2AApprovalForOwner(
+          approvalId,
+          session.email,
+          session.orgId ?? null,
+        );
+        if (!approval) {
+          setResponseStatus(event, 404);
+          return { error: "Approval not found" };
+        }
+        const safeInput = redactArgsToJson(approval.input) ?? "{}";
+        const esc = (value: string) =>
+          value.replace(
+            /[&<>"']/g,
+            (char) =>
+              ({
+                "&": "&amp;",
+                "<": "&lt;",
+                ">": "&gt;",
+                '"': "&quot;",
+                "'": "&#39;",
+              })[char] ?? char,
+          );
+        setResponseHeader(event, "content-type", "text/html; charset=utf-8");
+        setResponseHeader(event, "cache-control", "no-store");
+        setResponseHeader(event, "x-frame-options", "DENY");
+        setResponseHeader(
+          event,
+          "content-security-policy",
+          "frame-ancestors 'none'",
+        );
+        setResponseHeader(event, "referrer-policy", "no-referrer");
+        const expired = approval.expiresAt <= Date.now();
+        const active = approval.status === "pending" && !expired;
+        const displayStatus = expired ? "expired" : approval.status;
+        return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Review agent action</title><style>body{font:15px/1.5 ui-sans-serif,system-ui;background:#f7f7f5;color:#171717;margin:0}.card{max-width:680px;margin:8vh auto;background:white;border:1px solid #ddd;border-radius:14px;padding:28px;box-shadow:0 12px 36px #0001}h1{font-size:22px;margin:0 0 8px}p{color:#555}pre{white-space:pre-wrap;word-break:break-word;background:#f4f4f2;padding:16px;border-radius:9px;max-height:45vh;overflow:auto}button{background:#171717;color:white;border:0;border-radius:8px;padding:11px 16px;font-weight:650;cursor:pointer}button[disabled]{opacity:.5;cursor:default}#status{margin-left:10px;color:#555}</style></head><body><main class="card"><h1>Review agent action</h1><p>This action is paused until you approve it. Approval can be used once.</p><h2>${esc(approval.tool)}</h2><pre>${esc(safeInput)}</pre><button id="approve" ${active ? "" : "disabled"}>${active ? "Approve and run" : esc(displayStatus)}</button><span id="status">${active ? "" : esc(approval.result ?? displayStatus)}</span><script>document.getElementById('approve').onclick=async function(){this.disabled=true;document.getElementById('status').textContent='Running…';try{const r=await fetch(location.href,{method:'POST',credentials:'include',headers:{'content-type':'application/json'}});const j=await r.json();document.getElementById('status').textContent=j.output||j.error||'Done';}catch(e){document.getElementById('status').textContent='Could not run the action.'}}</script></main></body></html>`;
+      }
+
+      if (getMethod(event) !== "POST") {
+        setResponseStatus(event, 405);
+        return { error: "Method not allowed" };
+      }
+      if (!isSameOriginRequest(event)) {
+        setResponseStatus(event, 403);
+        return { error: "Cross-origin approval denied" };
+      }
+      if (!config.executeApproval) {
+        setResponseStatus(event, 501);
+        return { error: "Approval execution is not configured" };
+      }
+
+      const approval = await claimA2AApproval(
+        approvalId,
+        session.email,
+        session.orgId ?? null,
+      );
+      if (!approval) {
+        const current = await getA2AApprovalForOwner(
+          approvalId,
+          session.email,
+          session.orgId ?? null,
+        );
+        setResponseStatus(event, current ? 409 : 404);
+        return {
+          error: current
+            ? `Approval is ${current.status} and cannot be run again`
+            : "Approval not found",
+        };
+      }
+
+      const { runWithRequestContext } =
+        await import("../server/request-context.js");
+      let execution: { status: "completed" | "failed"; output: string };
+      try {
+        execution = await runWithRequestContext(
+          { userEmail: session.email, orgId: session.orgId ?? undefined },
+          () => config.executeApproval!(approval),
+        );
+      } catch (error) {
+        execution = {
+          status: "failed",
+          output:
+            error instanceof Error
+              ? error.message
+              : "Approval execution failed",
+        };
+      }
+      await settleA2AApproval(approval.id, execution.status, execution.output);
+      if (execution.status === "failed") setResponseStatus(event, 500);
+      return execution;
+    }),
+  );
+
   // Async-mode processor route. MUST be mounted BEFORE the `/a2a` catch-all
   // below, since h3's `.use()` matches by prefix and `/a2a` would otherwise
   // swallow `/a2a/_process-task` and return a JSON-RPC "Invalid token" error

package/corpus/core/src/a2a/task-store.ts

@@ -24,6 +24,23 @@ async function ensureTable(): Promise<void> {
           updated_at ${intType()} NOT NULL
         )
       `;
+      const createApprovalsSql = `
+        CREATE TABLE IF NOT EXISTS a2a_approvals (
+          id TEXT PRIMARY KEY,
+          task_id TEXT NOT NULL UNIQUE,
+          owner_email TEXT NOT NULL,
+          org_id TEXT,
+          tool_name TEXT NOT NULL,
+          tool_input TEXT NOT NULL,
+          approval_key TEXT NOT NULL,
+          call_id TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'pending',
+          result TEXT,
+          expires_at ${intType()} NOT NULL,
+          created_at ${intType()} NOT NULL,
+          updated_at ${intType()} NOT NULL
+        )
+      `;
 
       if (isPostgres()) {
         // PG-guard: probe information_schema before issuing DDL to avoid ACCESS
@@ -40,6 +57,7 @@ async function ensureTable(): Promise<void> {
           "owner_email",
           `ALTER TABLE a2a_tasks ADD COLUMN IF NOT EXISTS owner_email TEXT`,
         );
+        await ensureTableExists("a2a_approvals", createApprovalsSql);
         return;
       }
 
@@ -58,6 +76,7 @@ async function ensureTable(): Promise<void> {
       } catch {
         // Column already exists — expected on every restart after first run.
       }
+      await client.execute(createApprovalsSql);
     })().catch((err) => {
       // Retry init on the next call after a failed startup.
       _initPromise = undefined;
@@ -67,6 +86,240 @@ async function ensureTable(): Promise<void> {
   return _initPromise;
 }
 
+export interface A2AApprovalRecord {
+  id: string;
+  taskId: string;
+  ownerEmail: string;
+  orgId: string | null;
+  tool: string;
+  input: unknown;
+  approvalKey: string;
+  callId: string;
+  status: "pending" | "processing" | "completed" | "failed";
+  result: string | null;
+  expiresAt: number;
+}
+
+async function withDbTransaction<T>(
+  client: ReturnType<typeof getDbExec>,
+  fn: (tx: ReturnType<typeof getDbExec>) => Promise<T>,
+): Promise<T> {
+  if (client.transaction) return client.transaction(fn);
+  await client.execute(isPostgres() ? "BEGIN" : "BEGIN IMMEDIATE");
+  try {
+    const result = await fn(client);
+    await client.execute("COMMIT");
+    return result;
+  } catch (error) {
+    await client.execute("ROLLBACK").catch(() => {});
+    throw error;
+  }
+}
+
+function approvalFromRow(row: any): A2AApprovalRecord {
+  return {
+    id: String(row.id),
+    taskId: String(row.task_id),
+    ownerEmail: String(row.owner_email),
+    orgId: row.org_id ? String(row.org_id) : null,
+    tool: String(row.tool_name),
+    input: JSON.parse(String(row.tool_input)),
+    approvalKey: String(row.approval_key),
+    callId: String(row.call_id),
+    status: row.status,
+    result: row.result ? String(row.result) : null,
+    expiresAt: Number(row.expires_at),
+  };
+}
+
+export async function createA2AApproval(input: {
+  taskId: string;
+  ownerEmail: string;
+  orgId?: string | null;
+  tool: string;
+  toolInput: unknown;
+  approvalKey: string;
+  callId: string;
+  ttlMs?: number;
+}): Promise<A2AApprovalRecord> {
+  await ensureTable();
+  const client = getDbExec();
+  const id = crypto.randomUUID();
+  const now = Date.now();
+  const expiresAt = now + (input.ttlMs ?? 15 * 60_000);
+  await client.execute({
+    sql: `INSERT INTO a2a_approvals (id, task_id, owner_email, org_id, tool_name, tool_input, approval_key, call_id, status, expires_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?)`,
+    args: [
+      id,
+      input.taskId,
+      input.ownerEmail,
+      input.orgId ?? null,
+      input.tool,
+      JSON.stringify(input.toolInput ?? {}),
+      input.approvalKey,
+      input.callId,
+      expiresAt,
+      now,
+      now,
+    ],
+  });
+  return {
+    id,
+    taskId: input.taskId,
+    ownerEmail: input.ownerEmail,
+    orgId: input.orgId ?? null,
+    tool: input.tool,
+    input: input.toolInput ?? {},
+    approvalKey: input.approvalKey,
+    callId: input.callId,
+    status: "pending",
+    result: null,
+    expiresAt,
+  };
+}
+
+export async function getA2AApprovalForOwner(
+  id: string,
+  ownerEmail: string,
+  orgId?: string | null,
+): Promise<A2AApprovalRecord | null> {
+  await ensureTable();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT * FROM a2a_approvals WHERE id = ? AND owner_email = ? AND (org_id IS NULL OR org_id = ?)`,
+    args: [id, ownerEmail, orgId ?? null],
+  });
+  return rows[0] ? approvalFromRow(rows[0]) : null;
+}
+
+export async function claimA2AApproval(
+  id: string,
+  ownerEmail: string,
+  orgId?: string | null,
+): Promise<A2AApprovalRecord | null> {
+  await ensureTable();
+  const client = getDbExec();
+  const now = Date.now();
+  class ClaimRejected extends Error {}
+  try {
+    return await withDbTransaction(client, async (tx) => {
+      const approvalUpdate = await tx.execute({
+        sql: `UPDATE a2a_approvals SET status = 'processing', updated_at = ? WHERE id = ? AND owner_email = ? AND status = 'pending' AND expires_at > ? AND (org_id IS NULL OR org_id = ?)`,
+        args: [now, id, ownerEmail, now, orgId ?? null],
+      });
+      if (getAffectedRowCount(approvalUpdate) === 0) throw new ClaimRejected();
+      const { rows } = await tx.execute({
+        sql: `SELECT * FROM a2a_approvals WHERE id = ? AND owner_email = ? AND status = 'processing'`,
+        args: [id, ownerEmail],
+      });
+      if (!rows[0]) throw new ClaimRejected();
+      const approval = approvalFromRow(rows[0]);
+      const timestamp = new Date(now).toISOString();
+      const runningMessage: Message = {
+        role: "agent",
+        parts: [{ type: "text", text: "Approved action is running." }],
+      };
+      const taskUpdate = await tx.execute({
+        sql: `UPDATE a2a_tasks SET status_state = 'working', status_message = ?, status_timestamp = ?, updated_at = ? WHERE id = ? AND owner_email = ? AND status_state = 'input-required'`,
+        args: [
+          JSON.stringify(runningMessage),
+          timestamp,
+          now,
+          approval.taskId,
+          ownerEmail,
+        ],
+      });
+      if (getAffectedRowCount(taskUpdate) === 0) throw new ClaimRejected();
+      return approval;
+    });
+  } catch (error) {
+    if (error instanceof ClaimRejected) return null;
+    throw error;
+  }
+}
+
+export async function settleA2AApproval(
+  id: string,
+  status: "completed" | "failed",
+  resultText: string,
+): Promise<void> {
+  await ensureTable();
+  const client = getDbExec();
+  const now = Date.now();
+  const message: Message = {
+    role: "agent",
+    parts: [{ type: "text", text: resultText }],
+  };
+  await withDbTransaction(client, async (tx) => {
+    const { rows } = await tx.execute({
+      sql: `SELECT task_id FROM a2a_approvals WHERE id = ? AND status = 'processing'`,
+      args: [id],
+    });
+    if (!rows[0]) throw new Error("Approval is not processing");
+    const taskId = String((rows[0] as any).task_id);
+    const { rows: taskRows } = await tx.execute({
+      sql: `SELECT history FROM a2a_tasks WHERE id = ? AND status_state = 'working'`,
+      args: [taskId],
+    });
+    if (!taskRows[0]) {
+      throw new Error("Approval task is no longer awaiting settlement");
+    }
+    const history = JSON.parse(String((taskRows[0] as any).history));
+    history.push(message);
+    const timestamp = new Date(now).toISOString();
+    const taskUpdate = await tx.execute({
+      sql: `UPDATE a2a_tasks SET status_state = ?, status_message = ?, status_timestamp = ?, history = ?, updated_at = ? WHERE id = ? AND status_state = 'working'`,
+      args: [
+        status,
+        JSON.stringify(message),
+        timestamp,
+        JSON.stringify(history),
+        now,
+        taskId,
+      ],
+    });
+    if (getAffectedRowCount(taskUpdate) === 0) {
+      throw new Error("Approval task settlement lost its state claim");
+    }
+    const approvalUpdate = await tx.execute({
+      sql: `UPDATE a2a_approvals SET status = ?, result = ?, updated_at = ? WHERE id = ? AND status = 'processing'`,
+      args: [status, resultText, now, id],
+    });
+    if (getAffectedRowCount(approvalUpdate) === 0) {
+      throw new Error("Approval settlement lost its state claim");
+    }
+  });
+}
+
+export async function pauseProcessingA2ATask(
+  id: string,
+  message: Message,
+): Promise<Task | null> {
+  await ensureTable();
+  const client = getDbExec();
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM a2a_tasks WHERE id = ? AND status_state = 'processing'`,
+    args: [id],
+  });
+  if (!rows[0]) return null;
+  const task = taskFromRow(rows[0]);
+  task.history?.push(message);
+  const now = Date.now();
+  const timestamp = new Date(now).toISOString();
+  const result = await client.execute({
+    sql: `UPDATE a2a_tasks SET status_state = 'input-required', status_message = ?, status_timestamp = ?, history = ?, updated_at = ? WHERE id = ? AND status_state = 'processing'`,
+    args: [
+      JSON.stringify(message),
+      timestamp,
+      JSON.stringify(task.history ?? []),
+      now,
+      id,
+    ],
+  });
+  if (getAffectedRowCount(result) === 0) return null;
+  task.status = { state: "input-required", message, timestamp };
+  return task;
+}
+
 function taskFromRow(row: any): Task & { ownerEmail?: string | null } {
   return {
     id: row.id as string,

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

@@ -126,6 +126,12 @@ export interface JsonRpcResponse {
   error?: JsonRpcError;
 }
 
+/** One exact downstream action explicitly authorized in the caller's chat. */
+export interface A2AApprovedAction {
+  tool: string;
+  input: unknown;
+}
+
 // --- Framework config ---
 
 export interface A2AHandlerContext {
@@ -135,12 +141,27 @@ export interface A2AHandlerContext {
   metadata?: Record<string, unknown>;
   /** Current H3 event when the handler is running inside an HTTP request. */
   event?: unknown;
+  /** Exact one-time action grants from a JWT-authenticated caller. */
+  approvedActions?: A2AApprovedAction[];
   writeArtifact: (name: string, content: string, mimeType?: string) => string;
 }
 
 export interface A2AHandlerResult {
   message: Message;
   artifacts?: Artifact[];
+  /** Optional non-terminal state requested by the handler. */
+  taskState?: Extract<TaskState, "input-required">;
+}
+
+export interface A2AApprovalExecution {
+  id: string;
+  taskId: string;
+  ownerEmail: string;
+  orgId?: string | null;
+  tool: string;
+  input: unknown;
+  approvalKey: string;
+  callId: string;
 }
 
 export type A2AHandler = (
@@ -160,4 +181,9 @@ export interface A2AConfig {
   streaming?: boolean;
   /** Route async A2A work through the app's durable background worker when available. */
   durableBackgroundRuns?: boolean;
+  /** Execute a persisted, human-approved A2A tool call. */
+  executeApproval?: (approval: A2AApprovalExecution) => Promise<{
+    status: "completed" | "failed";
+    output: string;
+  }>;
 }

package/corpus/core/src/agent/production-agent.ts

@@ -2747,7 +2747,7 @@ function stableStringify(value: unknown): string {
     .join(",")}}`;
 }
 
-function toolCallCacheKey(toolName: string, input: unknown): string {
+export function toolCallCacheKey(toolName: string, input: unknown): string {
   return `${toolName}:${stableStringify(normalizeToolCallInputForHistory(input))}`;
 }
 
@@ -4180,7 +4180,10 @@ export async function runAgentLoop(opts: {
       // instead of executing. The action's side effect never happens until a
       // human re-issues the turn approving this call's stable key.
       const approvalKey = toolCallCacheKey(toolCall.name, toolCall.input);
-      if (actionEntry.needsApproval && !approvedToolCallKeys.has(approvalKey)) {
+      // Consume a grant on its first exact match. A second identical call in
+      // the same continuation must request its own human approval.
+      const wasApproved = approvedToolCallKeys.delete(approvalKey);
+      if (actionEntry.needsApproval && !wasApproved) {
         let mustApprove = false;
         try {
           mustApprove =