@agent-native/core 0.101.10 → 0.101.12

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2258
-- template files: 5665
+- template files: 5674

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @agent-native/core
 
+## 0.101.12
+
+### Patch Changes
+
+- 2ff004e: Fix workspace-file resolution and run-code paging/routing edge cases. `contentFromWorkspaceFile` now resolves the same file the run-code `workspaceRead`/`workspaceWrite` bridge sees (bridge scope first, then Resources), and fails closed on a bridge read error instead of silently falling back to a possibly-different same-path Resources body. `workspaceRead` returns null instead of a silently truncated prefix when a later page fails, and the run-code bridge now returns a distinct "not registered" (404) error for unknown tools instead of a misleading read-only access error.
+
+## 0.101.11
+
+### Patch Changes
+
+- fd0ddb8: Wait for agent-card and A2A routes to finish initializing on cold starts, preserve human approval gates across A2A tasks, and carry exact one-time chat authorization through authenticated agent delegation.
+
 ## 0.101.10
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.101.10",
+  "version": "0.101.12",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

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

@@ -2,6 +2,7 @@ import * as jose from "jose";
 
 import { ssrfSafeFetch } from "../extensions/url-safety.js";
 import type {
+  A2AApprovedAction,
   AgentCard,
   JsonRpcRequest,
   JsonRpcResponse,
@@ -227,6 +228,7 @@ export class A2AClient {
     opts?: {
       contextId?: string;
       metadata?: Record<string, unknown>;
+      approvedActions?: A2AApprovedAction[];
       /**
        * If true, ask the server to return the task immediately in `working`
        * state and process the handler in the background. The caller should
@@ -242,6 +244,9 @@ export class A2AClient {
       message,
       contextId: opts?.contextId,
       metadata: opts?.metadata,
+      ...(opts?.approvedActions?.length
+        ? { approvedActions: opts.approvedActions }
+        : {}),
       ...(opts?.async ? { async: true } : {}),
     });
 
@@ -281,6 +286,7 @@ export class A2AClient {
     opts?: {
       contextId?: string;
       metadata?: Record<string, unknown>;
+      approvedActions?: A2AApprovedAction[];
       /** Total time to wait for completion. Default 5 min. */
       timeoutMs?: number;
       /** Poll interval. Default 2s. */
@@ -292,10 +298,18 @@ export class A2AClient {
     const submitted = await this.send(message, {
       contextId: opts?.contextId,
       metadata: opts?.metadata,
+      ...(opts?.approvedActions?.length
+        ? { approvedActions: opts.approvedActions }
+        : {}),
       async: true,
     });
 
-    const terminalStates = new Set(["completed", "failed", "canceled"]);
+    const terminalStates = new Set([
+      "completed",
+      "failed",
+      "canceled",
+      "input-required",
+    ]);
     if (terminalStates.has(submitted.status.state)) return submitted;
 
     const timeoutMs = opts?.timeoutMs ?? 5 * 60_000;
@@ -542,6 +556,8 @@ export async function callAgent(
     orgSecret?: string;
     /** Origin used to build links back to the receiving app. */
     requestOrigin?: string;
+    /** Exact downstream actions explicitly authorized in the caller's chat. */
+    approvedActions?: A2AApprovedAction[];
     /**
      * Use async/poll instead of a single blocking POST. Recommended for
      * cross-app calls that may exceed a synchronous serverless request budget.
@@ -602,6 +618,9 @@ export async function callAgent(
         task = await client.sendAndWait(message, {
           contextId: opts?.contextId,
           metadata,
+          ...(opts?.approvedActions?.length
+            ? { approvedActions: opts.approvedActions }
+            : {}),
           timeoutMs: opts?.timeoutMs,
           pollIntervalMs: opts?.pollIntervalMs,
           onUpdate: opts?.onUpdate,
@@ -610,6 +629,9 @@ export async function callAgent(
         task = await client.send(message, {
           contextId: opts?.contextId,
           metadata,
+          ...(opts?.approvedActions?.length
+            ? { approvedActions: opts.approvedActions }
+            : {}),
         });
       }
 

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