@agent-native/core 0.92.11 → 0.93.0

package/corpus/core/src/a2a/artifact-response.ts

@@ -49,6 +49,19 @@ interface CreatedImageArtifact {
   url?: string;
 }
 
+interface CreatedMonitorArtifact {
+  id: string;
+  name?: string;
+  url: string;
+}
+
+interface CreatedFormArtifact {
+  id: string;
+  title?: string;
+  url: string;
+  anonymous: boolean;
+}
+
 type ReferencedArtifactKind =
   | "deck"
   | "design"
@@ -181,6 +194,40 @@ function imageIdValue(parsed: Record<string, unknown>): string | undefined {
   );
 }
 
+function contentDatabaseSubmissionArtifact(
+  parsed: Record<string, unknown>,
+): CreatedDocumentArtifact | null {
+  const id = stringValue(parsed.createdDocumentId);
+  if (!id) return null;
+
+  const verification = asRecord(parsed.verification);
+  const candidates = [
+    stringValue(parsed.url),
+    stringValue(parsed.urlPath),
+    stringValue(parsed.createdDocumentUrl),
+    stringValue(verification?.url),
+    stringValue(verification?.urlPath),
+  ].filter((value): value is string => !!value);
+  const url = candidates.find((candidate) =>
+    artifactUrlReferencesId(candidate, "document", id),
+  );
+
+  const items = Array.isArray(parsed.items) ? parsed.items : [];
+  const createdItem = items.map(asRecord).find((item) => {
+    const document = asRecord(item?.document);
+    return stringValue(document?.id) === id;
+  });
+  const createdDocument = asRecord(createdItem?.document);
+
+  return {
+    id,
+    title:
+      stringValue(parsed.createdDocumentTitle) ??
+      stringValue(createdDocument?.title),
+    url,
+  };
+}
+
 function addImageArtifact(
   images: Map<string, CreatedImageArtifact>,
   parsed: Record<string, unknown>,
@@ -241,6 +288,8 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
   images: CreatedImageArtifact[];
   designShells: CreatedDesignShell[];
   generatedDesigns: GeneratedDesignArtifact[];
+  monitors: CreatedMonitorArtifact[];
+  forms: CreatedFormArtifact[];
 } {
   const documents = new Map<string, CreatedDocumentArtifact>();
   const decks = new Map<string, CreatedDeckArtifact>();
@@ -249,6 +298,8 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
   const images = new Map<string, CreatedImageArtifact>();
   const designShells = new Map<string, CreatedDesignShell>();
   const generatedDesigns = new Map<string, GeneratedDesignArtifact>();
+  const monitors = new Map<string, CreatedMonitorArtifact>();
+  const forms = new Map<string, CreatedFormArtifact>();
 
   for (const toolResult of results) {
     if (toolResult.tool === "call-agent") {
@@ -297,6 +348,43 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
     const parsed = parseToolResultJson(toolResult.result);
     if (!parsed) continue;
 
+    if (toolResult.tool === "save-monitor") {
+      const id = stringValue(parsed.id);
+      const url = stringValue(parsed.monitorAppUrl);
+      if (id && url) {
+        monitors.set(id, {
+          id,
+          name: stringValue(parsed.name),
+          url,
+        });
+      }
+      continue;
+    }
+
+    if (toolResult.tool === "create-form") {
+      const id = stringValue(parsed.id);
+      const url = stringValue(parsed.publicUrl);
+      if (id && url && stringValue(parsed.status) === "published") {
+        const settings = asRecord(parsed.settings);
+        forms.set(id, {
+          id,
+          title: stringValue(parsed.title),
+          url,
+          anonymous: settings?.anonymous === true,
+        });
+      }
+      continue;
+    }
+
+    if (
+      toolResult.tool === "submit-content-database-form" ||
+      toolResult.tool === "add-database-item"
+    ) {
+      const artifact = contentDatabaseSubmissionArtifact(parsed);
+      if (artifact) documents.set(artifact.id, artifact);
+      continue;
+    }
+
     if (
       toolResult.tool === "create-document" ||
       toolResult.tool === "get-document" ||
@@ -484,6 +572,8 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
     images: [...images.values()],
     designShells: [...designShells.values()],
     generatedDesigns: [...generatedDesigns.values()],
+    monitors: [...monitors.values()],
+    forms: [...forms.values()],
   };
 }
 
@@ -713,6 +803,17 @@ function formatDesignLine(
   return `- Design: ${artifactUrlFromResult({ url: design.url }, `/design/${design.id}`, baseUrl)} (ID: ${design.id}, ${fileLabel})`;
 }
 
+function formatMonitorLine(monitor: CreatedMonitorArtifact): string {
+  const label = monitor.name ? `Monitor "${monitor.name}"` : "Monitor";
+  return `- ${label}: ${monitor.url} (ID: ${monitor.id})`;
+}
+
+function formatFormLine(form: CreatedFormArtifact): string {
+  const kind = form.anonymous ? "Anonymous form" : "Public form";
+  const label = form.title ? `${kind} "${form.title}"` : kind;
+  return `- ${label}: ${form.url} (ID: ${form.id})`;
+}
+
 function formatIncompleteDesignMessage(shells: CreatedDesignShell[]): string {
   const ids = shells.map((shell) => shell.id).join(", ");
   const noun = shells.length === 1 ? "project shell" : "project shells";
@@ -885,6 +986,8 @@ export function appendA2AArtifactLinks(
     images,
     designShells,
     generatedDesigns,
+    monitors,
+    forms,
   } = collectArtifacts(toolResults);
   const generatedDesignIds = new Set(
     generatedDesigns.map((design) => design.id),
@@ -985,6 +1088,22 @@ export function appendA2AArtifactLinks(
       missingLines.push(formatDesignLine(design, baseUrl));
     }
   }
+  for (const monitor of monitors) {
+    if (
+      includeReferencedArtifacts ||
+      !responseAlreadyMentionsPath(text, monitor.url)
+    ) {
+      missingLines.push(formatMonitorLine(monitor));
+    }
+  }
+  for (const form of forms) {
+    if (
+      includeReferencedArtifacts ||
+      !responseAlreadyMentionsPath(text, form.url)
+    ) {
+      missingLines.push(formatFormLine(form));
+    }
+  }
 
   if (missingLines.length === 0) return text;
   const artifactBlock = `Artifacts:\n${missingLines.join("\n")}`;
@@ -996,8 +1115,16 @@ export function buildA2ARecoverableArtifactMessage(
   options: A2AArtifactResponseOptions = {},
 ): string | null {
   const baseUrl = normalizeBaseUrl(options.baseUrl);
-  const { documents, decks, dashboards, analyses, images, generatedDesigns } =
-    collectArtifacts(toolResults);
+  const {
+    documents,
+    decks,
+    dashboards,
+    analyses,
+    images,
+    generatedDesigns,
+    monitors,
+    forms,
+  } = collectArtifacts(toolResults);
   const lines = [
     ...documents.map((document) => formatDocumentLine(document, baseUrl)),
     ...decks.map((deck) => formatDeckLine(deck, baseUrl)),
@@ -1005,6 +1132,8 @@ export function buildA2ARecoverableArtifactMessage(
     ...analyses.map((analysis) => formatAnalysisLine(analysis, baseUrl)),
     ...images.map((image) => formatImageLine(image, baseUrl)),
     ...generatedDesigns.map((design) => formatDesignLine(design, baseUrl)),
+    ...monitors.map(formatMonitorLine),
+    ...forms.map(formatFormLine),
   ];
 
   if (lines.length === 0) return null;

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

@@ -550,6 +550,15 @@ export async function callAgent(
     timeoutMs?: number;
     /** Poll interval for async calls. Primarily useful for tests/retries. */
     pollIntervalMs?: number;
+    /**
+     * Called with each successfully polled task while an async call is still
+     * in flight (see `A2AClient.sendAndWait`). Fires once per real poll
+     * round-trip that returns a task — including the terminal poll — so
+     * callers can surface genuine remote liveness/progress. Not called when a
+     * poll fetch throws (remote unresponsive) or when the task completes
+     * synchronously on submit. Only threaded through for async calls.
+     */
+    onUpdate?: (task: Task) => void;
   },
 ): Promise<string> {
   const metadata: Record<string, unknown> = {};
@@ -585,6 +594,7 @@ export async function callAgent(
           metadata,
           timeoutMs: opts?.timeoutMs,
           pollIntervalMs: opts?.pollIntervalMs,
+          onUpdate: opts?.onUpdate,
         });
       } else {
         task = await client.send(message, {

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

@@ -1,7 +1,14 @@
 import { setResponseHeader, setResponseStatus } from "h3";
 
-import { signInternalToken } from "../integrations/internal-token.js";
+import {
+  AGENT_BACKGROUND_PROCESSOR_A2A,
+  AGENT_BACKGROUND_PROCESSOR_FIELD,
+  dispatchPathTargetsNetlifyBackgroundFunction,
+  isAgentChatDurableBackgroundEnabled,
+  resolveAgentChatProcessRunDispatchPath,
+} from "../agent/durable-background.js";
 import { withConfiguredAppBasePath } from "../server/app-base-path.js";
+import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { agentChat } from "../shared/agent-chat.js";
 import {
   hasConfiguredA2ASecret,
@@ -37,79 +44,33 @@ const A2A_PROCESSING_STUCK_AFTER_MS = 5 * 60 * 1000;
 const A2A_PROCESSING_HEARTBEAT_MS = 30_000;
 
 /**
- * Resolve the base URL we should fire the A2A processor request to. Mirrors
- * the integration-webhook resolveBaseUrl pattern — prefer explicit env vars
- * (most reliable on serverless), fall back to inbound request headers.
- */
-function resolveSelfBaseUrl(event: any | undefined): string {
-  const fromEnv =
-    process.env.APP_URL ||
-    process.env.URL ||
-    process.env.DEPLOY_URL ||
-    process.env.BETTER_AUTH_URL;
-  if (fromEnv) return withConfiguredAppBasePath(String(fromEnv));
-  if (isA2AProductionRuntime()) {
-    throw new Error(
-      "A2A self-dispatch requires APP_URL, URL, DEPLOY_URL, or BETTER_AUTH_URL in production.",
-    );
-  }
-
-  try {
-    const headers = event?.node?.req?.headers ?? event?.headers;
-    const get = (name: string): string | undefined => {
-      if (!headers) return undefined;
-      if (typeof headers.get === "function") {
-        return headers.get(name) ?? undefined;
-      }
-      const map = headers as Record<string, string | undefined>;
-      return map[name] ?? map[String(name).toLowerCase()];
-    };
-    const proto = get("x-forwarded-proto") || "http";
-    const host = get("host") || `localhost:${process.env.PORT || 3000}`;
-    return withConfiguredAppBasePath(`${proto}://${host}`);
-  } catch {
-    return withConfiguredAppBasePath(
-      `http://localhost:${process.env.PORT || 3000}`,
-    );
-  }
-}
-
-/**
- * Fire-and-forget POST to the A2A processor route on the same deployment.
- * Used when an A2A send is requested in async mode — the processor runs the
- * handler in a fresh function execution so it gets its own full timeout.
+ * Dispatch an async A2A task to a fresh function execution. Apps that opted
+ * into durable background runs reuse the emitted Netlify 15-minute worker;
+ * other hosts and apps retain the normal portable self-webhook route.
  */
 async function fireProcessTaskDispatch(
   event: any,
   taskId: string,
+  config: A2AConfig,
 ): Promise<void> {
-  const baseUrl = resolveSelfBaseUrl(event);
-  const url = `${baseUrl}${A2A_PROCESS_TASK_PATH}`;
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-  };
-  try {
-    headers["Authorization"] = `Bearer ${signInternalToken(taskId)}`;
-  } catch {
-    // No A2A_SECRET configured — self-fire unsigned. The processor accepts
-    // unsigned dispatches when no secret is set (mirrors the integration
-    // webhook flow).
-  }
-  // Race the fetch against a short timer. On Netlify Lambda, returning
-  // immediately can freeze the function before the outbound TCP handshake
-  // starts, leaving the request stuck. This gives it ~250ms to leave the
-  // box at the cost of slightly higher response latency on async A2A sends.
-  const dispatchPromise = fetch(url, {
-    method: "POST",
-    headers,
-    body: JSON.stringify({ taskId }),
-  }).catch((err) => {
-    console.error("[a2a] Process-task dispatch fetch failed:", err);
+  const backgroundPath = resolveAgentChatProcessRunDispatchPath();
+  const useBackgroundWorker =
+    isAgentChatDurableBackgroundEnabled({
+      appOptIn: config.durableBackgroundRuns === true,
+    }) && dispatchPathTargetsNetlifyBackgroundFunction(backgroundPath);
+
+  await fireInternalDispatch({
+    event,
+    path: useBackgroundWorker ? backgroundPath : A2A_PROCESS_TASK_PATH,
+    taskId,
+    ...(useBackgroundWorker
+      ? {
+          body: {
+            [AGENT_BACKGROUND_PROCESSOR_FIELD]: AGENT_BACKGROUND_PROCESSOR_A2A,
+          },
+        }
+      : {}),
   });
-  await Promise.race([
-    dispatchPromise,
-    new Promise<void>((resolve) => setTimeout(resolve, 250)),
-  ]);
 }
 
 /**
@@ -522,7 +483,7 @@ async function handleSend(
     );
     const working = await updateTask(task.id, { state: "working" });
 
-    fireProcessTaskDispatch(event, task.id).catch((err) => {
+    fireProcessTaskDispatch(event, task.id, config).catch((err) => {
       console.error("[a2a] Failed to dispatch process-task:", err);
     });
 
@@ -764,12 +725,14 @@ async function handleGet(
   if (!task) {
     return jsonRpcError(0, -32001, "Task not found");
   }
-  const taskChanged = await refireStuckAsyncTaskIfNeeded(id, event).catch(
-    (err) => {
-      console.error("[a2a] Failed to refire stuck async task:", err);
-      return false;
-    },
-  );
+  const taskChanged = await refireStuckAsyncTaskIfNeeded(
+    id,
+    event,
+    config,
+  ).catch((err) => {
+    console.error("[a2a] Failed to refire stuck async task:", err);
+    return false;
+  });
   if (taskChanged) {
     const updated = await getTask(id);
     if (updated) return jsonRpcResult(0, sanitizeTaskForResponse(updated));
@@ -780,6 +743,7 @@ async function handleGet(
 async function refireStuckAsyncTaskIfNeeded(
   taskId: string,
   event: any,
+  config: A2AConfig,
 ): Promise<boolean> {
   const state = await getA2ATaskDispatchState(taskId);
   if (!state) return false;
@@ -791,7 +755,7 @@ async function refireStuckAsyncTaskIfNeeded(
     state.updatedAt <= now - A2A_QUEUED_DISPATCH_STUCK_AFTER_MS
   ) {
     if (await touchQueuedA2ATaskDispatch(taskId)) {
-      await fireProcessTaskDispatch(event, taskId);
+      await fireProcessTaskDispatch(event, taskId, config);
       return true;
     }
     return false;

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

@@ -158,4 +158,6 @@ export interface A2AConfig {
   handler?: A2AHandler;
   apiKeyEnv?: string;
   streaming?: boolean;
+  /** Route async A2A work through the app's durable background worker when available. */
+  durableBackgroundRuns?: boolean;
 }

package/corpus/core/src/agent/durable-background.ts

@@ -77,6 +77,18 @@ export const AGENT_BACKGROUND_FUNCTION_NAME = "server-agent-background";
  */
 export const AGENT_BACKGROUND_FUNCTION_URL_PATH = `/.netlify/functions/${AGENT_BACKGROUND_FUNCTION_NAME}`;
 
+/**
+ * Marker carried in a Netlify background-function body when the shared
+ * long-running worker should route to a processor other than agent chat.
+ * The emitted wrapper defaults to the normal agent-chat `_process-run` route;
+ * A2A uses this marker to reuse the same 15-minute function for async tasks.
+ */
+export const AGENT_BACKGROUND_PROCESSOR_FIELD = "__agentNativeProcessor";
+export const AGENT_BACKGROUND_PROCESSOR_A2A = "a2a";
+export const AGENT_BACKGROUND_PROCESSOR_ROUTE = "route";
+export const AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD =
+  "__agentNativeProcessorRoute";
+
 /**
  * The per-app workspace background function URL path. Workspace deploy emits one
  * background function per app named `<app>-agent-background`, reachable at its
@@ -149,6 +161,18 @@ export function resolveAgentChatProcessRunDispatchPath(): string {
   return AGENT_CHAT_PROCESS_RUN_PATH;
 }
 
+export function resolveDurableBackgroundDispatchPath(
+  fallbackPath: string,
+): string {
+  if (isNetlifyHostedRuntimeForDispatch()) {
+    return (
+      resolveWorkspaceBackgroundFunctionUrlPath() ??
+      AGENT_BACKGROUND_FUNCTION_URL_PATH
+    );
+  }
+  return fallbackPath;
+}
+
 export function dispatchPathTargetsNetlifyBackgroundFunction(
   dispatchPath: string,
 ): boolean {

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

@@ -125,6 +125,7 @@ import {
   getActiveRunForThreadAsync,
   getRun,
   abortRun,
+  abortRunDurably,
   tryClaimRunSlot,
 } from "./run-manager.js";
 import type { ActiveRun } from "./run-manager.js";
@@ -136,6 +137,7 @@ import {
   insertRun,
   updateRunHeartbeat,
   updateRunStatusIfRunning,
+  setRunError,
   setRunTerminalReason,
   claimBackgroundRun,
   readBackgroundRunClaim,
@@ -4881,18 +4883,47 @@ export function shouldChainBackgroundContinuation(opts: {
 export async function markBackgroundContinuationChunkTerminal(opts: {
   runId: string;
   continuationReason: AgentLoopContinuationReason;
+  terminalEvent?: AgentChatEvent;
   deps?: {
     updateRunStatusIfRunning?: typeof updateRunStatusIfRunning;
+    setRunError?: typeof setRunError;
     setRunTerminalReason?: typeof setRunTerminalReason;
   };
 }): Promise<boolean> {
   const updateStatus =
     opts.deps?.updateRunStatusIfRunning ?? updateRunStatusIfRunning;
+  const persistError = opts.deps?.setRunError ?? setRunError;
   const setTerminalReason =
     opts.deps?.setRunTerminalReason ?? setRunTerminalReason;
-  const updated = await updateStatus(opts.runId, "completed");
+  const terminalEvent = opts.terminalEvent;
+  const isTerminalFailure =
+    terminalEvent?.type === "error" ||
+    terminalEvent?.type === "missing_api_key";
+  const terminalReason =
+    terminalEvent?.type === "error"
+      ? `error:${terminalEvent.errorCode || "unknown"}`
+      : terminalEvent?.type === "missing_api_key"
+        ? "missing_api_key"
+        : opts.continuationReason;
+  const updated = await updateStatus(
+    opts.runId,
+    isTerminalFailure ? "errored" : "completed",
+  );
   if (updated) {
-    await setTerminalReason(opts.runId, opts.continuationReason);
+    await setTerminalReason(opts.runId, terminalReason);
+    if (terminalEvent?.type === "error") {
+      await persistError(
+        opts.runId,
+        terminalEvent.errorCode,
+        terminalEvent.details || terminalEvent.error,
+      );
+    } else if (terminalEvent?.type === "missing_api_key") {
+      await persistError(
+        opts.runId,
+        LLM_MISSING_CREDENTIALS_ERROR_CODE,
+        LLM_MISSING_CREDENTIALS_MESSAGE,
+      );
+    }
   }
   return updated;
 }
@@ -5451,9 +5482,19 @@ export async function chainServerDrivenContinuation(opts: {
         // successor is within `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS`
         // (via `shouldRedispatchUnclaimedBackgroundRun`). Without that guard a
         // connected client would reap this row at the 25s grace, before the
-        // ~2-min sweep, defeating the deferral. The sweep in agent-chat-plugin
-        // is the recovery actor; run-manager is the guard; this is the
-        // producer.
+        // sweep(s) get a chance, defeating the deferral. That same client
+        // poll also surfaces `awaitingRedispatch: true` on `/runs/active`
+        // for exactly this state so the client's background follow loop
+        // (`agent-chat-adapter.ts`) does not count the quiet gap against its
+        // own `BACKGROUND_FOLLOW_IDLE_TIMEOUT_MS` and report a fatal error
+        // for a turn the server is silently recovering. agent-chat-plugin.ts
+        // runs the actual recovery actors: a FAST redispatch-only sweep
+        // (`UNCLAIMED_BACKGROUND_RUN_FAST_SWEEP_MS`, ~20s ticks) that puts the
+        // first redispatch attempt well inside the client's idle timeout, and
+        // the original SLOW sweep (2 min) that also falls back to the loud
+        // reap once `UNCLAIMED_BACKGROUND_RUN_REDISPATCH_BOUND_MS` is
+        // exceeded. run-manager.ts is the guard + wire-signal source; this is
+        // the producer.
         await d
           .recordRunDiagnostic(
             nextRunId,
@@ -5513,6 +5554,7 @@ export async function chainServerDrivenContinuation(opts: {
       .markBackgroundContinuationChunkTerminal({
         runId,
         continuationReason,
+        terminalEvent: run.events.at(-1)?.event,
       })
       .catch(() => {});
   } catch (chainErr) {
@@ -7464,5 +7506,6 @@ export {
   getActiveRunForThreadAsync,
   getRun,
   abortRun,
+  abortRunDurably,
   subscribeToRun,
 };