@agent-native/core 0.107.1 → 0.107.2

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.107.2
+
+### Patch Changes
+
+- 2a4d2db: Retry messaging replies without repeating successful agent mutations, and deliver verified A2A artifact checkpoints as soon as they are durable.
+
 ## 0.107.1
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.107.1",
+  "version": "0.107.2",
   "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/artifact-response.ts

@@ -11,6 +11,11 @@ export interface A2AArtifactResponseOptions {
   baseUrl?: string;
   includeReferencedArtifacts?: boolean;
   includePersistedArtifactMarker?: boolean;
+  persistedArtifactSecret?: string;
+}
+
+export interface A2AArtifactIdentityOptions {
+  persistedArtifactSecrets?: readonly string[];
 }
 
 export interface A2AArtifactIdentity {
@@ -74,21 +79,26 @@ const ARTIFACT_RESOURCE_TYPES = new Set<A2AArtifactIdentity["resourceType"]>([
 
 function persistedArtifactIdentitiesFromMarker(
   result: string,
+  secrets: readonly string[] = process.env.A2A_SECRET
+    ? [process.env.A2A_SECRET]
+    : [],
 ): A2AArtifactIdentity[] {
-  const secret = process.env.A2A_SECRET;
-  if (!secret) return [];
+  if (secrets.length === 0) return [];
   const match = result.match(
     /<!--\s*agent-native:persisted-artifacts=([A-Za-z0-9_-]+)\.([a-f0-9]{64})\s*-->/,
   );
   if (!match) return [];
   try {
     const payload = match[1];
-    const expected = createHmac("sha256", secret).update(payload).digest();
     const supplied = Buffer.from(match[2], "hex");
-    if (
-      supplied.length !== expected.length ||
-      !timingSafeEqual(supplied, expected)
-    ) {
+    const verified = secrets.some((secret) => {
+      const expected = createHmac("sha256", secret).update(payload).digest();
+      return (
+        supplied.length === expected.length &&
+        timingSafeEqual(supplied, expected)
+      );
+    });
+    if (!verified) {
       return [];
     }
     const parsed = JSON.parse(Buffer.from(payload, "base64url").toString());
@@ -114,9 +124,15 @@ function persistedArtifactIdentitiesFromMarker(
 function withPersistedArtifactMarker(
   text: string,
   toolResults: A2AToolResultSummary[],
+  secret = process.env.A2A_SECRET,
 ): string {
-  const identities = extractA2AArtifactIdentities(toolResults).slice(0, 12);
-  const secret = process.env.A2A_SECRET;
+  const verificationSecrets = [secret, process.env.A2A_SECRET].filter(
+    (value, index, values): value is string =>
+      !!value && values.indexOf(value) === index,
+  );
+  const identities = extractA2AArtifactIdentities(toolResults, {
+    persistedArtifactSecrets: verificationSecrets,
+  }).slice(0, 12);
   if (identities.length === 0 || !secret) return text;
   const payload = Buffer.from(JSON.stringify(identities)).toString("base64url");
   const signature = createHmac("sha256", secret).update(payload).digest("hex");
@@ -881,6 +897,7 @@ function collectArtifacts(results: A2AToolResultSummary[]): {
  */
 export function extractA2AArtifactIdentities(
   results: A2AToolResultSummary[],
+  options: A2AArtifactIdentityOptions = {},
 ): A2AArtifactIdentity[] {
   const identities = new Map<string, A2AArtifactIdentity>();
 
@@ -894,6 +911,7 @@ export function extractA2AArtifactIdentities(
     if (result.tool === "call-agent") {
       for (const identity of persistedArtifactIdentitiesFromMarker(
         result.result,
+        options.persistedArtifactSecrets,
       )) {
         remember({ ...identity, sourceAction: "call-agent" });
       }
@@ -1387,7 +1405,11 @@ export function appendA2AArtifactLinks(
     options.includeReferencedArtifacts ?? false;
   const finalize = (value: string) =>
     options.includePersistedArtifactMarker
-      ? withPersistedArtifactMarker(value, toolResults)
+      ? withPersistedArtifactMarker(
+          value,
+          toolResults,
+          options.persistedArtifactSecret ?? process.env.A2A_SECRET,
+        )
       : value;
   const {
     documents,

package/corpus/core/src/integrations/a2a-continuation-processor.ts

@@ -171,11 +171,22 @@ async function processClaimedContinuation(
     ...(auth.apiKeyFallbacks ? { fallbackApiKeys: auth.apiKeyFallbacks } : {}),
   });
   const deadline = Date.now() + PROCESSOR_WAIT_MS;
+  const recoverableArtifactSecrets =
+    await resolveContinuationArtifactSecrets(continuation);
   let task: Task | null = null;
+  let latestRecoverableArtifactText: string | null = null;
 
   try {
     while (Date.now() < deadline) {
       task = await client.getTask(continuation.a2aTaskId);
+      const recoverableArtifactText = extractVerifiedRecoverableArtifactText(
+        task,
+        continuation.agentUrl,
+        recoverableArtifactSecrets,
+      );
+      if (recoverableArtifactText) {
+        latestRecoverableArtifactText = recoverableArtifactText;
+      }
       if (TERMINAL_STATES.has(task.status.state)) break;
       await reportA2AContinuationProgress(continuation, progress, task);
       await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
@@ -183,6 +194,17 @@ async function processClaimedContinuation(
   } catch (err) {
     if (isTransientA2APollError(err)) {
       if (shouldStopPollingRemoteTask(continuation)) {
+        if (latestRecoverableArtifactText) {
+          await deliverAndCompleteA2AContinuation(
+            continuation,
+            adapter,
+            formatRecoverableArtifactFallbackText(
+              latestRecoverableArtifactText,
+            ),
+            progress,
+          );
+          return;
+        }
         await notifyAndFailA2AContinuation(
           continuation,
           adapter,
@@ -209,6 +231,15 @@ async function processClaimedContinuation(
 
   if (!task || !TERMINAL_STATES.has(task.status.state)) {
     if (shouldStopPollingRemoteTask(continuation)) {
+      if (latestRecoverableArtifactText) {
+        await deliverAndCompleteA2AContinuation(
+          continuation,
+          adapter,
+          formatRecoverableArtifactFallbackText(latestRecoverableArtifactText),
+          progress,
+        );
+        return;
+      }
       await notifyAndFailA2AContinuation(
         continuation,
         adapter,
@@ -222,6 +253,15 @@ async function processClaimedContinuation(
   }
 
   if (task.status.state !== "completed") {
+    if (latestRecoverableArtifactText) {
+      await deliverAndCompleteA2AContinuation(
+        continuation,
+        adapter,
+        formatRecoverableArtifactFallbackText(latestRecoverableArtifactText),
+        progress,
+      );
+      return;
+    }
     const reason =
       extractTaskText(task) ||
       `Remote A2A task ${continuation.a2aTaskId} ended with state ${task.status.state}`;
@@ -234,6 +274,15 @@ async function processClaimedContinuation(
     continuation.agentUrl,
   );
   if (!text.trim()) {
+    if (latestRecoverableArtifactText) {
+      await deliverAndCompleteA2AContinuation(
+        continuation,
+        adapter,
+        formatRecoverableArtifactFallbackText(latestRecoverableArtifactText),
+        progress,
+      );
+      return;
+    }
     await notifyAndFailA2AContinuation(
       continuation,
       adapter,
@@ -382,6 +431,8 @@ async function deliverAndCompleteA2AContinuation(
       `${deliveryContinuation.platform} response delivery timed out`,
     );
     let persistenceError: unknown;
+    const artifactSecrets =
+      await resolveContinuationArtifactSecrets(deliveryContinuation);
     for (let attempt = 0; attempt < 3; attempt += 1) {
       try {
         await persistA2AContinuationDelivery(
@@ -389,6 +440,7 @@ async function deliverAndCompleteA2AContinuation(
           outgoing,
           deliveryReceipt,
           text,
+          artifactSecrets,
         );
         persistenceError = undefined;
         break;
@@ -463,6 +515,7 @@ async function persistA2AContinuationDelivery(
   outgoing: OutgoingMessage,
   receipt: PlatformDeliveryReceipt,
   artifactText: string,
+  artifactSecrets: readonly string[],
 ): Promise<void> {
   const mapping = await getThreadMapping(
     continuation.platform,
@@ -480,9 +533,12 @@ async function persistA2AContinuationDelivery(
   }
   if (!Array.isArray(repo.messages)) repo.messages = [];
 
-  const artifacts = extractA2AArtifactIdentities([
-    { tool: "call-agent", result: artifactText },
-  ]);
+  const artifacts = extractA2AArtifactIdentities(
+    [{ tool: "call-agent", result: artifactText }],
+    {
+      persistedArtifactSecrets: artifactSecrets,
+    },
+  );
   const metadata: Record<string, unknown> = {
     integrationDeliveryAttempted: true,
     integrationDelivery: {
@@ -726,6 +782,24 @@ async function signFreshContinuationTokens(
   return tokens;
 }
 
+async function resolveContinuationArtifactSecrets(
+  continuation: A2AContinuation,
+): Promise<string[]> {
+  const secrets: string[] = [];
+  const add = (secret: string | null | undefined) => {
+    const value = secret?.trim();
+    if (value && !secrets.includes(value)) secrets.push(value);
+  };
+  add(process.env.A2A_SECRET);
+  if (continuation.orgId) {
+    try {
+      const { getOrgA2ASecret } = await import("../org/context.js");
+      add(await getOrgA2ASecret(continuation.orgId));
+    } catch {}
+  }
+  return secrets;
+}
+
 function isLikelyJwt(token: string): boolean {
   return token.split(".").length === 3;
 }
@@ -740,6 +814,36 @@ function extractTaskText(task: Task): string {
     .join("\n");
 }
 
+function extractVerifiedRecoverableArtifactText(
+  task: Task,
+  agentUrl: string,
+  artifactSecrets: readonly string[],
+): string | null {
+  if (task.status.message?.metadata?.agentNativeRecoverableArtifacts !== true) {
+    return null;
+  }
+
+  const text = formatContinuationArtifactText(extractTaskText(task), agentUrl);
+  if (!text.trim()) return null;
+
+  // Require the signed identity ledger so arbitrary peer progress prose cannot
+  // prematurely complete the continuation.
+  const artifacts = extractA2AArtifactIdentities(
+    [{ tool: "call-agent", result: text }],
+    {
+      persistedArtifactSecrets: artifactSecrets,
+    },
+  );
+  return artifacts.length > 0 ? text : null;
+}
+
+function formatRecoverableArtifactFallbackText(text: string): string {
+  return text.replace(
+    "The agent is still working on the full response, but these verified artifacts already exist:",
+    "The downstream agent did not finish its full response, but these verified artifacts already exist:",
+  );
+}
+
 function formatContinuationArtifactText(
   text: string,
   agentUrl: string,

package/corpus/core/src/integrations/pending-tasks-store.ts

@@ -272,6 +272,19 @@ export async function claimPendingTask(
                AND active.status = 'processing'
                AND active.id <> integration_pending_tasks.id
            )
+           AND NOT EXISTS (
+             SELECT 1 FROM integration_pending_tasks earlier
+             WHERE earlier.platform = integration_pending_tasks.platform
+               AND earlier.external_thread_id = integration_pending_tasks.external_thread_id
+               AND earlier.status = 'pending'
+               AND (
+                 earlier.created_at < integration_pending_tasks.created_at
+                 OR (
+                   earlier.created_at = integration_pending_tasks.created_at
+                   AND earlier.id < integration_pending_tasks.id
+                 )
+               )
+           )
          RETURNING id, platform, external_thread_id, payload, owner_email, org_id, status, attempts, error_message, created_at, updated_at, completed_at`
       : `UPDATE integration_pending_tasks
          SET status = ?, attempts = attempts + 1, updated_at = ?
@@ -282,6 +295,19 @@ export async function claimPendingTask(
                AND active.external_thread_id = integration_pending_tasks.external_thread_id
                AND active.status = 'processing'
                AND active.id <> integration_pending_tasks.id
+           )
+           AND NOT EXISTS (
+             SELECT 1 FROM integration_pending_tasks earlier
+             WHERE earlier.platform = integration_pending_tasks.platform
+               AND earlier.external_thread_id = integration_pending_tasks.external_thread_id
+               AND earlier.status = 'pending'
+               AND (
+                 earlier.created_at < integration_pending_tasks.created_at
+                 OR (
+                   earlier.created_at = integration_pending_tasks.created_at
+                   AND earlier.id < integration_pending_tasks.id
+                 )
+               )
            )`,
     args: ["processing", now, id],
   });
@@ -312,7 +338,7 @@ export async function getNextPendingTaskIdForThread(
   const { rows } = await getDbExec().execute({
     sql: `SELECT id FROM integration_pending_tasks
       WHERE platform = ? AND external_thread_id = ? AND status = 'pending'
-      ORDER BY created_at ASC LIMIT 1`,
+      ORDER BY created_at ASC, id ASC LIMIT 1`,
     args: [platform, externalThreadId],
   });
   return rows[0]?.id ? String(rows[0].id) : null;
@@ -354,6 +380,77 @@ export async function markTaskRetryable(
   });
 }
 
+export async function stageTaskDeliveryPayload(
+  id: string,
+  payload: string,
+): Promise<void> {
+  await ensureTable();
+  const client = getDbExec();
+  const now = Date.now();
+  const result = await client.execute({
+    sql: `UPDATE integration_pending_tasks
+          SET payload = ?, updated_at = ?
+          WHERE id = ? AND status = 'processing'`,
+    args: [payload, now, id],
+  });
+  const affected = Number(
+    (result as { rowsAffected?: number }).rowsAffected ??
+      (result as { rowCount?: number }).rowCount ??
+      0,
+  );
+  if (affected === 0) {
+    throw new Error("Integration task is no longer claimable for delivery");
+  }
+}
+
+export async function markTaskDeliveryRetryable(
+  id: string,
+  payload: string,
+  errorMessage: string,
+): Promise<void> {
+  await ensureTable();
+  const client = getDbExec();
+  const result = await client.execute({
+    sql: `UPDATE integration_pending_tasks
+          SET status = ?, payload = ?, updated_at = ?, error_message = ?
+          WHERE id = ? AND status = 'processing'`,
+    args: ["pending", payload, Date.now(), errorMessage.slice(0, 2000), id],
+  });
+  const affected = Number(
+    (result as { rowsAffected?: number }).rowsAffected ??
+      (result as { rowCount?: number }).rowCount ??
+      0,
+  );
+  if (affected === 0) {
+    throw new Error(
+      "Integration task is no longer claimable for delivery retry",
+    );
+  }
+}
+
+export async function failTaskDeliveryTransition(
+  id: string,
+  errorMessage: string,
+): Promise<void> {
+  await ensureTable();
+  const result = await getDbExec().execute({
+    sql: `UPDATE integration_pending_tasks
+          SET status = ?, updated_at = ?, error_message = ?, payload = ?
+          WHERE id = ? AND status = 'processing'`,
+    args: ["failed", Date.now(), errorMessage.slice(0, 2000), "{}", id],
+  });
+  const affected = Number(
+    (result as { rowsAffected?: number }).rowsAffected ??
+      (result as { rowCount?: number }).rowCount ??
+      0,
+  );
+  if (affected === 0) {
+    throw new Error(
+      "Integration task delivery failure transition lost its race",
+    );
+  }
+}
+
 /** Mark a task as failed and stash an error message. */
 export async function markTaskFailed(
   id: string,

package/corpus/core/src/integrations/plugin.ts

@@ -78,13 +78,16 @@ import {
 import { startPendingTasksRetryJob } from "./pending-tasks-retry-job.js";
 import {
   claimPendingTask,
+  failTaskDeliveryTransition,
   getNextPendingTaskIdForThread,
   insertPendingTask,
   isDuplicateEventError,
   MAX_PENDING_TASK_ATTEMPTS,
   markTaskCompleted,
+  markTaskDeliveryRetryable,
   markTaskFailed,
   markTaskRetryable,
+  stageTaskDeliveryPayload,
 } from "./pending-tasks-store.js";
 import {
   claimNextComputerCommand,
@@ -142,12 +145,18 @@ import type {
   IntegrationStatus,
   IntegrationExecutionContext,
   IncomingMessage,
+  PlatformDeliveryReceipt,
 } from "./types.js";
 import {
   listIntegrationUsageBudgets,
   saveIntegrationUsageBudget,
 } from "./usage-budget-store.js";
-import { handleWebhook, processIntegrationTask } from "./webhook-handler.js";
+import {
+  handleWebhook,
+  processIntegrationTask,
+  recordIntegrationResponseDelivery,
+  type IntegrationResponseDeliveryTaskPayload,
+} from "./webhook-handler.js";
 
 type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
 
@@ -1615,6 +1624,11 @@ export function createIntegrationsPlugin(
           return { ok: true, skipped: "already-claimed-or-missing" };
         }
 
+        let deliveryRetryTransitionStarted = false;
+        let deliveryRetryRecovery:
+          | { payload: string; errorMessage: string }
+          | undefined;
+        let confirmedDeliveryRetryPayload: string | undefined;
         try {
           const adapter = adapterMap.get(task.platform);
           if (!adapter) {
@@ -1622,7 +1636,7 @@ export function createIntegrationsPlugin(
             setResponseStatus(event, 404);
             return { error: "Unknown platform" };
           }
-          await runWithRequestContext(
+          const processingResult = await runWithRequestContext(
             {
               userEmail: task.ownerEmail,
               ...(task.orgId ? { orgId: task.orgId } : {}),
@@ -1631,6 +1645,7 @@ export function createIntegrationsPlugin(
             async () => {
               const taskPayload = JSON.parse(task.payload) as
                 | IntegrationSystemNoticeTaskPayload
+                | IntegrationResponseDeliveryTaskPayload
                 | { kind?: undefined };
               if (taskPayload.kind === "system-notice") {
                 if (!adapter.sendSystemNotice) {
@@ -1657,13 +1672,59 @@ export function createIntegrationsPlugin(
                 );
                 return;
               }
+              if (taskPayload.kind === "response-delivery") {
+                let receipt: void | PlatformDeliveryReceipt =
+                  taskPayload.deliveryReceipt;
+                if (!receipt) {
+                  receipt = await adapter.sendResponse(
+                    taskPayload.message,
+                    taskPayload.incoming,
+                    {
+                      ...(taskPayload.placeholderRef
+                        ? { placeholderRef: taskPayload.placeholderRef }
+                        : {}),
+                    },
+                  );
+                }
+                if (receipt?.status !== "delivered") {
+                  throw new Error(
+                    `${task.platform} response completed without delivery proof`,
+                  );
+                }
+                const deliveredPayload = taskPayload.deliveryReceipt
+                  ? taskPayload
+                  : {
+                      ...taskPayload,
+                      deliveryReceipt: receipt,
+                      deliveredAt: new Date().toISOString(),
+                    };
+                confirmedDeliveryRetryPayload =
+                  JSON.stringify(deliveredPayload);
+                if (!taskPayload.deliveryReceipt) {
+                  deliveryRetryRecovery = {
+                    payload: confirmedDeliveryRetryPayload,
+                    errorMessage:
+                      "Provider delivery was confirmed but its receipt checkpoint failed",
+                  };
+                  await stageTaskDeliveryPayload(
+                    task.id,
+                    deliveryRetryRecovery.payload,
+                  );
+                  deliveryRetryRecovery = undefined;
+                }
+                await recordIntegrationResponseDelivery(
+                  deliveredPayload,
+                  receipt,
+                );
+                return;
+              }
               const resources = await loadResourcesForPrompt(
                 task.ownerEmail,
                 true,
                 options?.appId,
                 task.orgId,
               );
-              await processIntegrationTask(task, {
+              const result = await processIntegrationTask(task, {
                 adapter,
                 systemPrompt: baseSystemPrompt + resources,
                 actions,
@@ -1674,8 +1735,22 @@ export function createIntegrationsPlugin(
                 ownerEmail: task.ownerEmail,
                 appId: options?.appId,
               });
+              if (result?.status === "delivery-pending") {
+                deliveryRetryTransitionStarted = true;
+                await markTaskDeliveryRetryable(
+                  task.id,
+                  JSON.stringify(result.payload),
+                  result.errorMessage,
+                );
+                return "delivery-retry" as const;
+              }
+              return "completed" as const;
             },
           );
+          if (processingResult === "delivery-retry") {
+            setResponseStatus(event, 202);
+            return { ok: true, taskId, retrying: "response-delivery" };
+          }
           await markTaskCompleted(taskId);
           const nextTaskId = await getNextPendingTaskIdForThread(
             task.platform,
@@ -1711,7 +1786,57 @@ export function createIntegrationsPlugin(
           const errorMessage = err?.message
             ? String(err.message).slice(0, 1000)
             : "processor failed";
-          if (task.attempts >= MAX_PENDING_TASK_ATTEMPTS) {
+          if (deliveryRetryRecovery) {
+            try {
+              await markTaskDeliveryRetryable(
+                taskId,
+                deliveryRetryRecovery.payload,
+                `${deliveryRetryRecovery.errorMessage}: ${errorMessage}`,
+              );
+              setResponseStatus(event, 202);
+              return { ok: true, taskId, retrying: "response-delivery" };
+            } catch (transitionError) {
+              const transitionMessage =
+                transitionError instanceof Error
+                  ? transitionError.message
+                  : String(transitionError);
+              await failTaskDeliveryTransition(
+                taskId,
+                `Could not safely checkpoint the delivery receipt: ${transitionMessage}`,
+              ).catch((failureTransitionError) => {
+                console.error(
+                  "[integrations] Failed to contain delivery receipt transition failure:",
+                  failureTransitionError,
+                );
+              });
+            }
+          } else if (confirmedDeliveryRetryPayload) {
+            try {
+              await markTaskDeliveryRetryable(
+                taskId,
+                confirmedDeliveryRetryPayload,
+                `Provider delivery was confirmed but history persistence failed: ${errorMessage}`,
+              );
+              console.error("[integrations] process-task failure:", err);
+              setResponseStatus(event, 202);
+              return { ok: true, taskId, retrying: "response-delivery" };
+            } catch (transitionError) {
+              console.error(
+                "[integrations] Failed to requeue confirmed delivery history:",
+                transitionError,
+              );
+            }
+          } else if (deliveryRetryTransitionStarted) {
+            await failTaskDeliveryTransition(
+              taskId,
+              `Could not safely checkpoint the delivery retry: ${errorMessage}`,
+            ).catch((transitionError) => {
+              console.error(
+                "[integrations] Failed to contain delivery retry transition failure:",
+                transitionError,
+              );
+            });
+          } else if (task.attempts >= MAX_PENDING_TASK_ATTEMPTS) {
             await markTaskFailed(taskId, errorMessage);
           } else {
             await markTaskRetryable(taskId, errorMessage);