@agent-native/core 0.130.0 → 0.130.1

package/corpus/core/src/integrations/a2a-continuations-store.ts

@@ -1,3 +1,4 @@
+import type { A2AArtifactIdentity } from "../a2a/artifact-response.js";
 import {
   getDbExec,
   isPostgres,
@@ -15,6 +16,9 @@ import type { IncomingMessage, PlatformRunProgressRef } from "./types.js";
 let _initPromise: Promise<void> | undefined;
 const PROCESSING_STUCK_AFTER_MS = 5 * 60 * 1000;
 const PROCESSING_NEXT_CHECK_STALE_AFTER_MS = 60 * 1000;
+const TERMINAL_HISTORY_FINALIZATION_LEASE_MS = 60 * 1000;
+const MAX_VERIFIED_ARTIFACT_CHECKPOINT_CHARS = 16_000;
+const MAX_TERMINAL_HISTORY_PAYLOAD_CHARS = 64_000;
 
 // Build the CREATE SQL lazily (not at module scope) so intType() runs at
 // RUNTIME, not import time — a module-scope call breaks any consumer whose
@@ -37,6 +41,10 @@ function buildCreateSql(): string {
     dedupe_key TEXT,
     a2a_task_id TEXT NOT NULL,
     a2a_auth_token TEXT,
+    verified_artifact_checkpoint TEXT,
+    terminal_delivery_kind TEXT,
+    terminal_delivery_confirmed_at ${intType()},
+    terminal_history_payload TEXT,
     status TEXT NOT NULL,
     attempts ${intType()} NOT NULL DEFAULT 0,
     next_check_at ${intType()} NOT NULL,
@@ -88,6 +96,27 @@ async function ensureTable(): Promise<void> {
           "progress_ref_claimed",
           `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS progress_ref_claimed ${intType()} NOT NULL DEFAULT 0`,
         );
+        await ensureColumnExists(
+          "integration_a2a_continuations",
+          "verified_artifact_checkpoint",
+          `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS verified_artifact_checkpoint TEXT`,
+        );
+        await ensureColumnExists(
+          "integration_a2a_continuations",
+          "terminal_delivery_kind",
+          `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS terminal_delivery_kind TEXT`,
+        );
+        await ensureColumnExists(
+          "integration_a2a_continuations",
+          "terminal_delivery_confirmed_at",
+          `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS terminal_delivery_confirmed_at ${intType()}`,
+        );
+        await ensureColumnExists(
+          "integration_a2a_continuations",
+          "terminal_history_payload",
+          `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS terminal_history_payload TEXT`,
+        );
+        await backfillLegacyCompletedDeliveries(client);
         await backfillProgressRefOwners(client);
         await ensureIndexExists(
           "idx_a2a_continuations_dedupe_key",
@@ -123,6 +152,11 @@ async function ensureTable(): Promise<void> {
         "progress_ref_claimed",
         `${intType()} NOT NULL DEFAULT 0`,
       );
+      await addColumnIfMissing("verified_artifact_checkpoint", "TEXT");
+      await addColumnIfMissing("terminal_delivery_kind", "TEXT");
+      await addColumnIfMissing("terminal_delivery_confirmed_at", intType());
+      await addColumnIfMissing("terminal_history_payload", "TEXT");
+      await backfillLegacyCompletedDeliveries(client);
       await backfillProgressRefOwners(client);
       await retryOnDdlRace(() =>
         client.execute(
@@ -143,6 +177,10 @@ async function ensureTable(): Promise<void> {
   return _initPromise;
 }
 
+export async function ensureA2AContinuationsTable(): Promise<void> {
+  await ensureTable();
+}
+
 async function addColumnIfMissing(name: string, definition: string) {
   try {
     await retryOnDdlRace(() =>
@@ -183,6 +221,18 @@ async function backfillProgressRefOwners(
   `);
 }
 
+async function backfillLegacyCompletedDeliveries(
+  client: ReturnType<typeof getDbExec>,
+): Promise<void> {
+  await client.execute(`
+    UPDATE integration_a2a_continuations
+    SET terminal_delivery_kind = 'success',
+        terminal_delivery_confirmed_at = COALESCE(completed_at, updated_at)
+    WHERE status = 'completed'
+      AND terminal_delivery_confirmed_at IS NULL
+  `);
+}
+
 export type A2AContinuationStatus =
   | "pending"
   | "processing"
@@ -190,6 +240,21 @@ export type A2AContinuationStatus =
   | "completed"
   | "failed";
 
+export type A2ATerminalDeliveryKind = "success" | "failure";
+
+export interface A2ATerminalHistoryPayload {
+  text: string;
+  deliveredAt: string;
+  messageRefs: string[];
+  artifacts: A2AArtifactIdentity[];
+}
+
+export type A2AContinuationTaskOutcome =
+  | "active"
+  | "terminal-delivered"
+  | "terminal-without-delivery"
+  | "missing";
+
 export interface A2AContinuation {
   id: string;
   integrationTaskId: string;
@@ -206,6 +271,10 @@ export interface A2AContinuation {
   dedupeKey: string | null;
   a2aTaskId: string;
   a2aAuthToken: string | null;
+  verifiedArtifactCheckpoint: string | null;
+  terminalDeliveryKind: A2ATerminalDeliveryKind | null;
+  terminalDeliveryConfirmedAt: number | null;
+  terminalHistoryPayload: A2ATerminalHistoryPayload | null;
   status: A2AContinuationStatus;
   attempts: number;
   nextCheckAt: number;
@@ -270,6 +339,20 @@ function rowToContinuation(row: Record<string, unknown>): A2AContinuation {
     dedupeKey: (row.dedupe_key as string | null) ?? null,
     a2aTaskId: row.a2a_task_id as string,
     a2aAuthToken: (row.a2a_auth_token as string | null) ?? null,
+    verifiedArtifactCheckpoint:
+      (row.verified_artifact_checkpoint as string | null) ?? null,
+    terminalDeliveryKind:
+      row.terminal_delivery_kind === "success" ||
+      row.terminal_delivery_kind === "failure"
+        ? row.terminal_delivery_kind
+        : null,
+    terminalDeliveryConfirmedAt:
+      row.terminal_delivery_confirmed_at == null
+        ? null
+        : Number(row.terminal_delivery_confirmed_at),
+    terminalHistoryPayload: parseTerminalHistoryPayload(
+      row.terminal_history_payload,
+    ),
     status: row.status as A2AContinuationStatus,
     attempts: Number(row.attempts ?? 0),
     nextCheckAt: Number(row.next_check_at ?? 0),
@@ -281,6 +364,42 @@ function rowToContinuation(row: Record<string, unknown>): A2AContinuation {
   };
 }
 
+function parseTerminalHistoryPayload(
+  value: unknown,
+): A2ATerminalHistoryPayload | null {
+  if (typeof value !== "string" || !value) return null;
+  try {
+    const parsed = JSON.parse(value) as Partial<A2ATerminalHistoryPayload>;
+    if (
+      typeof parsed.text !== "string" ||
+      typeof parsed.deliveredAt !== "string" ||
+      !Array.isArray(parsed.messageRefs) ||
+      !parsed.messageRefs.every((ref) => typeof ref === "string") ||
+      !Array.isArray(parsed.artifacts)
+    ) {
+      return null;
+    }
+    return {
+      text: parsed.text,
+      deliveredAt: parsed.deliveredAt,
+      messageRefs: parsed.messageRefs,
+      artifacts: parsed.artifacts.filter(
+        (artifact): artifact is A2AArtifactIdentity =>
+          !!artifact &&
+          typeof artifact === "object" &&
+          !Array.isArray(artifact) &&
+          typeof (artifact as { id?: unknown }).id === "string" &&
+          typeof (artifact as { resourceType?: unknown }).resourceType ===
+            "string" &&
+          typeof (artifact as { sourceAction?: unknown }).sourceAction ===
+            "string",
+      ),
+    };
+  } catch {
+    return null;
+  }
+}
+
 export async function insertA2AContinuation(input: {
   integrationTaskId: string;
   platform: string;
@@ -432,6 +551,67 @@ export async function hasActiveA2AContinuationsForIntegrationTask(
   return rows.length > 0;
 }
 
+export async function getA2AContinuationTaskOutcome(
+  integrationTaskId: string,
+): Promise<A2AContinuationTaskOutcome> {
+  await ensureTable();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT status, terminal_delivery_confirmed_at
+          FROM integration_a2a_continuations
+          WHERE integration_task_id = ?`,
+    args: [integrationTaskId],
+  });
+  if (rows.length === 0) return "missing";
+  if (
+    rows.some((row) =>
+      ["pending", "processing", "delivering"].includes(String(row.status)),
+    )
+  ) {
+    return "active";
+  }
+  return rows.every((row) => row.terminal_delivery_confirmed_at != null)
+    ? "terminal-delivered"
+    : "terminal-without-delivery";
+}
+
+export async function hasPendingConfirmedA2ADeliveryForIntegrationTask(
+  integrationTaskId: string,
+): Promise<boolean> {
+  await ensureTable();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT 1 AS confirmed FROM integration_a2a_continuations
+          WHERE integration_task_id = ?
+            AND status IN ('pending', 'processing', 'delivering')
+            AND terminal_delivery_confirmed_at IS NOT NULL
+          LIMIT 1`,
+    args: [integrationTaskId],
+  });
+  return rows.length > 0;
+}
+
+export async function hasOnlyLegacyFailedA2AContinuationsForIntegrationTask(
+  integrationTaskId: string,
+): Promise<boolean> {
+  await ensureTable();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT status, terminal_delivery_kind,
+                 terminal_delivery_confirmed_at, terminal_history_payload
+          FROM integration_a2a_continuations
+          WHERE integration_task_id = ?`,
+    args: [integrationTaskId],
+  });
+  return (
+    rows.length > 0 &&
+    rows.every(
+      (row) =>
+        String(row.status) === "failed" &&
+        row.terminal_delivery_kind == null &&
+        row.terminal_delivery_confirmed_at == null &&
+        row.terminal_history_payload == null,
+    )
+  );
+}
+
 export async function failA2AContinuationsForIntegrationTask(
   integrationTaskId: string,
   errorMessage: string,
@@ -440,9 +620,11 @@ export async function failA2AContinuationsForIntegrationTask(
   const now = Date.now();
   await getDbExec().execute({
     sql: `UPDATE integration_a2a_continuations
-          SET status = 'failed', error_message = ?, updated_at = ?, completed_at = ?
+          SET status = 'failed', error_message = ?, updated_at = ?, completed_at = ?,
+              verified_artifact_checkpoint = NULL
           WHERE integration_task_id = ?
-            AND status IN ('pending', 'processing', 'delivering')`,
+            AND status IN ('pending', 'processing', 'delivering')
+            AND terminal_delivery_confirmed_at IS NULL`,
     args: [errorMessage.slice(0, 2000), now, now, integrationTaskId],
   });
 }
@@ -580,6 +762,7 @@ export async function claimDueA2AContinuations(
 export async function recoverDueA2AContinuationIds(
   limit = 5,
   integrationTaskIds?: string[],
+  confirmedDeliveryOnly = false,
 ): Promise<string[]> {
   await ensureTable();
   const client = getDbExec();
@@ -591,20 +774,25 @@ export async function recoverDueA2AContinuationIds(
     ? ` AND integration_task_id IN (${integrationTaskIds.map(() => "?").join(", ")})`
     : "";
   const taskArgs = integrationTaskIds ?? [];
-  // If a processor dies while holding a delivery claim, retry the final send.
-  // The stale cutoff preserves the in-flight delivery guard while keeping
-  // final integration replies at-least-once.
+  const receiptFilter = confirmedDeliveryOnly
+    ? " AND terminal_delivery_confirmed_at IS NOT NULL"
+    : "";
+  // If a processor dies after a provider receipt, retry history-only custody
+  // as soon as its short follow-up deadline passes. A pre-receipt delivery
+  // claim retains the longer stale cutoff before an at-least-once resend.
   await client.execute({
     sql: `UPDATE integration_a2a_continuations
           SET status = ?, next_check_at = ?, updated_at = ?
-          WHERE status = 'delivering' AND updated_at <= ?${taskFilter}`,
-    args: ["pending", now, now, now - 5 * 60 * 1000, ...taskArgs],
+          WHERE status = 'delivering'
+            AND ((terminal_delivery_confirmed_at IS NOT NULL AND next_check_at <= ?)
+              OR updated_at <= ?)${taskFilter}${receiptFilter}`,
+    args: ["pending", now, now, now, now - 5 * 60 * 1000, ...taskArgs],
   });
   await client.execute({
     sql: `UPDATE integration_a2a_continuations
           SET status = ?, next_check_at = ?, updated_at = ?
           WHERE status = 'processing'
-            AND (updated_at <= ? OR next_check_at <= ?)${taskFilter}`,
+            AND (updated_at <= ? OR next_check_at <= ?)${taskFilter}${receiptFilter}`,
     args: [
       "pending",
       now,
@@ -616,7 +804,7 @@ export async function recoverDueA2AContinuationIds(
   });
   const { rows } = await client.execute({
     sql: `SELECT id FROM integration_a2a_continuations
-          WHERE status = 'pending' AND next_check_at <= ?${taskFilter}
+          WHERE status = 'pending' AND next_check_at <= ?${taskFilter}${receiptFilter}
           ORDER BY next_check_at ASC
           LIMIT ?`,
     args: [now, ...taskArgs, limit],
@@ -637,6 +825,7 @@ export interface RecoverableA2AIntegrationTask {
   externalThreadId: string;
   dispatchScope: string | null;
   status: string;
+  hasPendingConfirmedDelivery: boolean;
 }
 
 /**
@@ -650,7 +839,13 @@ export async function listRecoverableA2AIntegrationTasks(
   const now = Date.now();
   const { rows } = await getDbExec().execute({
     sql: `SELECT DISTINCT c.integration_task_id, t.platform,
-                 t.external_thread_id, t.dispatch_scope, t.status
+                 t.external_thread_id, t.dispatch_scope, t.status,
+                 EXISTS (
+                   SELECT 1 FROM integration_a2a_continuations receipt
+                   WHERE receipt.integration_task_id = c.integration_task_id
+                     AND receipt.terminal_delivery_confirmed_at IS NOT NULL
+                     AND receipt.status IN ('pending', 'processing', 'delivering')
+                 ) AS has_pending_confirmed_delivery
           FROM integration_a2a_continuations c
           INNER JOIN integration_pending_tasks t
              ON t.id = c.integration_task_id
@@ -658,13 +853,16 @@ export async function listRecoverableA2AIntegrationTasks(
             AND ((c.status = 'pending' AND c.next_check_at <= ?)
              OR (c.status = 'processing' AND
                  (c.updated_at <= ? OR c.next_check_at <= ?))
-             OR (c.status = 'delivering' AND c.updated_at <= ?))
+             OR (c.status = 'delivering' AND
+                 ((c.terminal_delivery_confirmed_at IS NOT NULL AND c.next_check_at <= ?)
+                   OR c.updated_at <= ?)))
           ORDER BY c.integration_task_id ASC
           LIMIT ?`,
     args: [
       now,
       now - PROCESSING_STUCK_AFTER_MS,
       now - PROCESSING_NEXT_CHECK_STALE_AFTER_MS,
+      now,
       now - 5 * 60 * 1000,
       Math.max(1, Math.min(Math.floor(limit), 200)),
     ],
@@ -675,6 +873,9 @@ export async function listRecoverableA2AIntegrationTasks(
     externalThreadId: String(row.external_thread_id),
     dispatchScope: (row.dispatch_scope as string | null) ?? null,
     status: String(row.status),
+    hasPendingConfirmedDelivery:
+      row.has_pending_confirmed_delivery === true ||
+      Number(row.has_pending_confirmed_delivery ?? 0) === 1,
   }));
 }
 
@@ -723,6 +924,131 @@ export async function rescheduleA2AContinuation(
   });
 }
 
+export async function retainA2AUnconfirmedDeliveryClaim(
+  id: string,
+): Promise<void> {
+  await ensureTable();
+  const now = Date.now();
+  await getDbExec().execute({
+    sql: `UPDATE integration_a2a_continuations
+          SET next_check_at = ?, updated_at = ?
+          WHERE id = ? AND status = 'delivering'
+            AND terminal_delivery_confirmed_at IS NULL`,
+    args: [now + PROCESSING_STUCK_AFTER_MS, now, id],
+  });
+}
+
+export async function saveA2AVerifiedArtifactCheckpoint(
+  id: string,
+  checkpoint: string,
+): Promise<string | null> {
+  await ensureTable();
+  const normalized = checkpoint.trim();
+  if (!normalized) return null;
+  if (normalized.length > MAX_VERIFIED_ARTIFACT_CHECKPOINT_CHARS) {
+    throw new Error(
+      `Verified artifact checkpoint exceeds ${MAX_VERIFIED_ARTIFACT_CHECKPOINT_CHARS} characters`,
+    );
+  }
+  const now = Date.now();
+  await getDbExec().execute({
+    sql: `UPDATE integration_a2a_continuations
+          SET verified_artifact_checkpoint = ?, updated_at = ?
+          WHERE id = ? AND status IN ('pending', 'processing', 'delivering')`,
+    args: [normalized, now, id],
+  });
+  const persisted = await getA2AContinuation(id);
+  return persisted?.verifiedArtifactCheckpoint === normalized
+    ? normalized
+    : null;
+}
+
+export async function recordA2ATerminalDeliveryReceipt(
+  id: string,
+  kind: A2ATerminalDeliveryKind,
+  historyPayload: A2ATerminalHistoryPayload,
+  errorMessage?: string,
+): Promise<A2AContinuation> {
+  await ensureTable();
+  const serializedPayload = JSON.stringify(historyPayload);
+  if (serializedPayload.length > MAX_TERMINAL_HISTORY_PAYLOAD_CHARS) {
+    throw new Error(
+      `Terminal A2A history payload exceeds ${MAX_TERMINAL_HISTORY_PAYLOAD_CHARS} characters`,
+    );
+  }
+  const now = Date.now();
+  await getDbExec().execute({
+    sql: `UPDATE integration_a2a_continuations
+          SET status = 'delivering', terminal_delivery_kind = ?,
+              terminal_delivery_confirmed_at = COALESCE(terminal_delivery_confirmed_at, ?),
+              terminal_history_payload = ?, next_check_at = ?, updated_at = ?,
+              error_message = ?
+          WHERE id = ?
+            AND status IN ('processing', 'delivering')
+            AND (terminal_delivery_confirmed_at IS NULL
+              OR terminal_delivery_kind = ?)`,
+    args: [
+      kind,
+      now,
+      serializedPayload,
+      now + TERMINAL_HISTORY_FINALIZATION_LEASE_MS,
+      now,
+      errorMessage?.slice(0, 2000) ?? null,
+      id,
+      kind,
+    ],
+  });
+  const persisted = await getA2AContinuation(id);
+  if (
+    persisted?.status !== "delivering" ||
+    persisted.terminalDeliveryKind !== kind ||
+    persisted.terminalDeliveryConfirmedAt == null ||
+    JSON.stringify(persisted.terminalHistoryPayload) !== serializedPayload
+  ) {
+    throw new Error("Terminal A2A delivery confirmation did not persist");
+  }
+  return persisted;
+}
+
+export async function finalizeA2ATerminalHistory(id: string): Promise<void> {
+  await ensureTable();
+  const continuation = await getA2AContinuation(id);
+  if (
+    continuation &&
+    (continuation.status === "completed" || continuation.status === "failed") &&
+    continuation.terminalDeliveryConfirmedAt != null &&
+    continuation.terminalHistoryPayload == null
+  ) {
+    return;
+  }
+  if (
+    !continuation?.terminalDeliveryKind ||
+    continuation.terminalDeliveryConfirmedAt == null ||
+    !continuation.terminalHistoryPayload
+  ) {
+    throw new Error("Terminal A2A history cannot finalize without a receipt");
+  }
+  const now = Date.now();
+  const status =
+    continuation.terminalDeliveryKind === "success" ? "completed" : "failed";
+  await getDbExec().execute({
+    sql: `UPDATE integration_a2a_continuations
+          SET status = ?, updated_at = ?, completed_at = ?, incoming_payload = ?,
+              a2a_auth_token = NULL, progress_ref = NULL,
+              verified_artifact_checkpoint = NULL, terminal_history_payload = NULL
+          WHERE id = ? AND status IN ('pending', 'processing', 'delivering')
+            AND terminal_delivery_confirmed_at IS NOT NULL`,
+    args: [status, now, now, "{}", id],
+  });
+  const persisted = await getA2AContinuation(id);
+  if (
+    persisted?.status !== status ||
+    persisted.terminalHistoryPayload != null
+  ) {
+    throw new Error("Terminal A2A history finalization did not persist");
+  }
+}
+
 export async function completeA2AContinuation(id: string): Promise<void> {
   await ensureTable();
   const client = getDbExec();
@@ -730,9 +1056,13 @@ export async function completeA2AContinuation(id: string): Promise<void> {
   await client.execute({
     sql: `UPDATE integration_a2a_continuations
           SET status = ?, updated_at = ?, completed_at = ?,
-              incoming_payload = ?, a2a_auth_token = NULL, progress_ref = NULL
+              incoming_payload = ?, a2a_auth_token = NULL, progress_ref = NULL,
+              verified_artifact_checkpoint = NULL,
+              terminal_delivery_kind = COALESCE(terminal_delivery_kind, 'success'),
+              terminal_delivery_confirmed_at = COALESCE(terminal_delivery_confirmed_at, ?),
+              terminal_history_payload = NULL
           WHERE id = ? AND status IN ('processing', 'delivering', 'completed')`,
-    args: ["completed", now, now, "{}", id],
+    args: ["completed", now, now, "{}", now, id],
   });
 }
 
@@ -746,7 +1076,8 @@ export async function failA2AContinuation(
   await client.execute({
     sql: `UPDATE integration_a2a_continuations
           SET status = ?, updated_at = ?, error_message = ?,
-              incoming_payload = ?, a2a_auth_token = NULL, progress_ref = NULL
+              incoming_payload = ?, a2a_auth_token = NULL, progress_ref = NULL,
+              verified_artifact_checkpoint = NULL
           WHERE id = ? AND status <> 'completed'`,
     args: ["failed", now, errorMessage.slice(0, 2000), "{}", id],
   });