@agent-native/core 0.101.10 → 0.101.11

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 =

package/corpus/core/src/mcp/builtin-tools.ts

@@ -31,7 +31,7 @@
  * `mountMCP` — the Node bits are dynamically imported inside `run()`.
  */
 
-import type { Task } from "../a2a/types.js";
+import type { A2AApprovedAction, Task } from "../a2a/types.js";
 import type { ActionEntry } from "../agent/production-agent.js";
 import type { ActionTool } from "../agent/types.js";
 import { getConfiguredAppBasePath } from "../server/app-base-path.js";
@@ -404,6 +404,7 @@ async function submitAskAppA2ATask(
   route: AskAppRoute,
   message: string,
   maxWaitMs: number,
+  approvedActions?: A2AApprovedAction[],
 ): Promise<AskAppTaskResult> {
   const deadline = maxWaitMs > 0 ? Date.now() + maxWaitMs : undefined;
   const { client, metadata } = await createA2AClientForAskApp(
@@ -419,6 +420,7 @@ async function submitAskAppA2ATask(
     {
       async: true,
       metadata,
+      ...(approvedActions?.length ? { approvedActions } : {}),
     },
   );
   const finalOrRunning = await waitForA2ATask(client, task, deadline);
@@ -890,6 +892,7 @@ async function routeAskOverA2A(
     durable?: boolean;
     maxWaitMs?: number;
     requestOrigin?: string;
+    approvedActions?: A2AApprovedAction[];
   },
 ): Promise<
   { app: string; routedVia: "a2a"; response: string } | AskAppTaskResult
@@ -904,6 +907,7 @@ async function routeAskOverA2A(
       },
       message,
       options.maxWaitMs ?? ASK_APP_DEFAULT_INLINE_WAIT_MS,
+      options.approvedActions,
     );
   }
   const { callAgent } = await import("../a2a/client.js");
@@ -919,6 +923,7 @@ async function routeAskOverA2A(
     orgDomain: auth.orgDomain,
     orgSecret: auth.orgSecret,
     requestOrigin: options?.requestOrigin,
+    approvedActions: options?.approvedActions,
     // Bound the wait — cross-app A2A polls async by default.
     timeoutMs: 5 * 60_000,
   });
@@ -1012,6 +1017,19 @@ function askAppTool(
           description:
             "Maximum time to wait inline before returning a taskId. Hosted MCP clamps this to 25000ms.",
         },
+        approvedActions: {
+          type: "array",
+          description:
+            "Exact downstream tool calls the user explicitly authorized in this chat. Never infer authorization or include a different action.",
+          items: {
+            type: "object",
+            properties: {
+              tool: { type: "string" },
+              input: { type: "object", additionalProperties: true },
+            },
+            required: ["tool", "input"],
+          },
+        } as any,
       },
       ["message"],
     ),
@@ -1024,6 +1042,9 @@ function askAppTool(
       const maxWaitMs = isExplicitAsyncAsk(args.async)
         ? 0
         : boundedAskAppWaitMs(args.maxWaitMs);
+      const approvedActions = Array.isArray(args.approvedActions)
+        ? (args.approvedActions as A2AApprovedAction[])
+        : undefined;
 
       // Cross-app: the caller named a *different* workspace app. Route the
       // message to THAT app's agent over A2A (its `/_agent-native/a2a`
@@ -1040,6 +1061,7 @@ function askAppTool(
               durable: useDurableA2A,
               maxWaitMs,
               requestOrigin: targetApp.origin,
+              approvedActions,
             },
           );
         } catch (err: any) {
@@ -1074,6 +1096,7 @@ function askAppTool(
                 durable: useDurableA2A,
                 maxWaitMs,
                 requestOrigin: dirMatch.url,
+                approvedActions,
               },
             );
           } catch (err: any) {
@@ -1120,6 +1143,7 @@ function askAppTool(
           },
           message,
           maxWaitMs,
+          approvedActions,
         );
       }
 

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

@@ -6,7 +6,7 @@ import {
   shouldPreferGlobalA2ASecret,
   signA2AToken,
 } from "../a2a/client.js";
-import type { Task } from "../a2a/types.js";
+import type { A2AApprovedAction, Task } from "../a2a/types.js";
 import {
   formatLlmCredentialErrorMessage,
   isLlmCredentialError,
@@ -112,17 +112,34 @@ export const tool: ActionTool = {
         type: "string",
         description: "The message/question to send to the other agent",
       },
+      approvedActions: {
+        type: "array",
+        description:
+          "Exact downstream tool calls the current user explicitly authorized in this chat. Never infer authorization or include a broader/different action.",
+        items: {
+          type: "object",
+          properties: {
+            tool: { type: "string" },
+            input: { type: "object", additionalProperties: true },
+          },
+          required: ["tool", "input"],
+        },
+      },
     },
     required: ["agent", "message"],
   },
 };
 
 export async function run(
-  args: Record<string, string>,
+  args: Record<string, unknown>,
   context?: ActionRunContext,
   selfAppId?: string,
 ): Promise<string> {
-  const { agent: agentIdOrName, message } = args;
+  const agentIdOrName = String(args.agent ?? "");
+  const message = String(args.message ?? "");
+  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";
@@ -320,6 +337,7 @@ export async function run(
           userEmail: callerEmail,
           orgDomain: callerOrgDomain,
           orgSecret: callerOrgSecret,
+          approvedActions,
           onUpdate: onRemotePollUpdate,
           ...(callTimeoutMs
             ? {
@@ -408,6 +426,7 @@ export async function run(
       userEmail: email,
       orgDomain: domain,
       orgSecret,
+      approvedActions,
     });
     const sanitized =
       formatDownstreamLlmCredentialFailure(agent.name, response) ?? response;

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import nodePath from "node:path";
 
 import {
@@ -19,7 +20,10 @@ import {
   isTrustedLocalRuntime,
 } from "../a2a/auth-policy.js";
 import { applyAgentTextEventToBuffer } from "../a2a/response-text.js";
-import { updateTaskStatusMessage } from "../a2a/task-store.js";
+import {
+  createA2AApproval,
+  updateTaskStatusMessage,
+} from "../a2a/task-store.js";
 import type { ActionHttpConfig } from "../action.js";
 import {
   canUpdateAgentAppModelDefaultSettings,
@@ -52,6 +56,7 @@ import {
   createProductionAgentHandler,
   actionsToEngineTools,
   executeAgentToolCall,
+  toolCallCacheKey,
   getActiveRunForThreadAsync,
   abortRunDurably,
   subscribeToRun,
@@ -1171,6 +1176,25 @@ export function createAgentChatPlugin(
         publicSkillsOnly: true,
         streaming: true,
         durableBackgroundRuns: options?.durableBackgroundRuns,
+        executeApproval: async (approval) => {
+          const result = await executeAgentToolCall({
+            actions: mcpFullActions ?? allScripts,
+            name: approval.tool,
+            input: approval.input,
+            callId: approval.callId,
+            ownerEmail: approval.ownerEmail,
+            orgId: approval.orgId ?? null,
+            approvedToolCalls: [approval.approvalKey],
+          });
+          if (result.status === "approval_required") {
+            return {
+              status: "failed" as const,
+              output:
+                "The approved action was unexpectedly gated again and did not run.",
+            };
+          }
+          return { status: result.status, output: result.output };
+        },
         handler: async function* (message, context) {
           // Resolve the caller's identity for user-scoped data access.
           // Priority: A2A-JWT verified email (set by the A2A handler in
@@ -1495,6 +1519,9 @@ export function createAgentChatPlugin(
               // scope when a processor hop or alternate runner is involved.
               ownerEmail: userEmail,
               orgId: getRequestOrgId() ?? null,
+              approvedToolCalls: context.approvedActions?.map((approved) =>
+                toolCallCacheKey(approved.tool, approved.input),
+              ),
               executionMode: "act",
               send: (event) => {
                 a2aEvents.push(event);
@@ -1549,6 +1576,62 @@ export function createAgentChatPlugin(
             },
           );
 
+          const approval = [...a2aEvents]
+            .reverse()
+            .find(
+              (
+                event,
+              ): event is Extract<
+                AgentChatEvent,
+                { type: "approval_required" }
+              > => event.type === "approval_required",
+            );
+          if (approval) {
+            const pending = await createA2AApproval({
+              taskId: context.taskId,
+              ownerEmail: userEmail,
+              orgId: getRequestOrgId() ?? null,
+              tool: approval.tool,
+              toolInput: approval.input,
+              approvalKey: approval.approvalKey,
+              callId: approval.toolCallId ?? crypto.randomUUID(),
+            });
+            const baseUrl = resolveArtifactBaseUrl(context.event);
+            const approvalPath = `/_agent-native/a2a/approvals/${encodeURIComponent(pending.id)}`;
+            const approvalUrl = baseUrl
+              ? `${baseUrl}${approvalPath}`
+              : approvalPath;
+            yield {
+              role: "agent" as const,
+              metadata: {
+                agentNativeTaskState: "input-required",
+                agentNativeApproval: {
+                  id: pending.id,
+                  tool: approval.tool,
+                  url: approvalUrl,
+                },
+              },
+              parts: [
+                {
+                  type: "text" as const,
+                  text:
+                    `Human approval is required to run ${approval.tool}. ` +
+                    `Open ${approvalUrl} to review and approve this one-time action.`,
+                },
+                {
+                  type: "data" as const,
+                  data: {
+                    kind: "agent-native/approval-required",
+                    approvalId: pending.id,
+                    tool: approval.tool,
+                    approvalUrl,
+                  },
+                },
+              ],
+            };
+            return;
+          }
+
           const { responseText, finalText } = assembleA2AFinalResponse(
             a2aEvents,
             a2aToolResults,
@@ -5621,6 +5704,8 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
         "/_agent-native/agent-model-defaults",
         "/_agent-native/mcp",
         "/mcp",
+        "/.well-known/agent-card.json",
+        "/_agent-native/a2a",
       ],
     });
   };

package/corpus/core/src/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -147,6 +147,31 @@ for await (const update of client.stream({
 }
 ```
 
+### Carrying explicit chat authorization
+
+When the authenticated caller has an exact consequential action that the user
+explicitly authorized in the originating chat, pass the tool name and complete
+input as `approvedActions`. The receiver accepts these grants only from a
+JWT-verified user identity, converts each one to the same content-addressed key
+as its local approval gate, and consumes it once:
+
+```ts
+await client.send(message, {
+  async: true,
+  approvedActions: [
+    {
+      tool: "send-email",
+      input: { to, subject, body, attachments },
+    },
+  ],
+});
+```
+
+Never infer authorization from request prose or broaden the input. A changed
+recipient, body, attachment, or tool produces a different key and follows the
+receiver's normal approval-required path. Static API keys and unsigned callers
+cannot carry these grants.
+
 ## JSON-RPC Methods
 
 | Method           | Purpose                          | Auth required |