@agent-native/core 0.130.0 → 0.130.1

package/dist/integrations/a2a-continuations-store.js

@@ -4,6 +4,9 @@ import { isDuplicateColumnError } from "../db/migrations.js";
 let _initPromise;
 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
 // db/client mock doesn't stub intType (e.g. db-admin specs).
@@ -25,6 +28,10 @@ function buildCreateSql() {
     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,
@@ -50,6 +57,11 @@ async function ensureTable() {
                 await ensureColumnExists("integration_a2a_continuations", "dedupe_key", `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS dedupe_key TEXT`);
                 await ensureColumnExists("integration_a2a_continuations", "progress_ref", `ALTER TABLE integration_a2a_continuations ADD COLUMN IF NOT EXISTS progress_ref TEXT`);
                 await ensureColumnExists("integration_a2a_continuations", "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", `CREATE INDEX IF NOT EXISTS idx_a2a_continuations_dedupe_key ON integration_a2a_continuations(integration_task_id, agent_url, dedupe_key)`);
                 await ensureIndexExists("idx_a2a_continuations_one_progress_owner", `CREATE UNIQUE INDEX IF NOT EXISTS idx_a2a_continuations_one_progress_owner ON integration_a2a_continuations(integration_task_id) WHERE progress_ref_claimed = 1`);
@@ -64,6 +76,11 @@ async function ensureTable() {
             await addColumnIfMissing("dedupe_key", "TEXT");
             await addColumnIfMissing("progress_ref", "TEXT");
             await addColumnIfMissing("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(`CREATE INDEX IF NOT EXISTS idx_a2a_continuations_dedupe_key ON integration_a2a_continuations(integration_task_id, agent_url, dedupe_key)`));
             await retryOnDdlRace(() => client.execute(`CREATE UNIQUE INDEX IF NOT EXISTS idx_a2a_continuations_one_progress_owner ON integration_a2a_continuations(integration_task_id) WHERE progress_ref_claimed = 1`));
@@ -75,6 +92,9 @@ async function ensureTable() {
     }
     return _initPromise;
 }
+export async function ensureA2AContinuationsTable() {
+    await ensureTable();
+}
 async function addColumnIfMissing(name, definition) {
     try {
         await retryOnDdlRace(() => getDbExec().execute(`ALTER TABLE integration_a2a_continuations ADD COLUMN ${name} ${definition}`));
@@ -109,6 +129,15 @@ async function backfillProgressRefOwners(client) {
       )
   `);
 }
+async function backfillLegacyCompletedDeliveries(client) {
+    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
+  `);
+}
 const MAX_PROGRESS_REF_KIND_CHARS = 128;
 const MAX_PROGRESS_REF_STREAM_TS_CHARS = 256;
 /**
@@ -159,6 +188,15 @@ function rowToContinuation(row) {
         dedupeKey: row.dedupe_key ?? null,
         a2aTaskId: row.a2a_task_id,
         a2aAuthToken: row.a2a_auth_token ?? null,
+        verifiedArtifactCheckpoint: row.verified_artifact_checkpoint ?? 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,
         attempts: Number(row.attempts ?? 0),
         nextCheckAt: Number(row.next_check_at ?? 0),
@@ -168,6 +206,36 @@ function rowToContinuation(row) {
         completedAt: row.completed_at == null ? null : Number(row.completed_at),
     };
 }
+function parseTerminalHistoryPayload(value) {
+    if (typeof value !== "string" || !value)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        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 &&
+                typeof artifact === "object" &&
+                !Array.isArray(artifact) &&
+                typeof artifact.id === "string" &&
+                typeof artifact.resourceType ===
+                    "string" &&
+                typeof artifact.sourceAction ===
+                    "string"),
+        };
+    }
+    catch {
+        return null;
+    }
+}
 export async function insertA2AContinuation(input) {
     await ensureTable();
     const client = getDbExec();
@@ -291,14 +359,60 @@ export async function hasActiveA2AContinuationsForIntegrationTask(integrationTas
     });
     return rows.length > 0;
 }
+export async function getA2AContinuationTaskOutcome(integrationTaskId) {
+    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) {
+    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) {
+    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, errorMessage) {
     await ensureTable();
     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],
     });
 }
@@ -413,7 +527,7 @@ export async function claimDueA2AContinuations(limit = 5) {
  * to wake the normal processor, whose atomic claim remains the sole progress
  * and delivery owner under overlapping scheduler/self-dispatch executions.
  */
-export async function recoverDueA2AContinuationIds(limit = 5, integrationTaskIds) {
+export async function recoverDueA2AContinuationIds(limit = 5, integrationTaskIds, confirmedDeliveryOnly = false) {
     await ensureTable();
     const client = getDbExec();
     const now = Date.now();
@@ -425,20 +539,25 @@ export async function recoverDueA2AContinuationIds(limit = 5, integrationTaskIds
         ? ` 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,
@@ -450,7 +569,7 @@ export async function recoverDueA2AContinuationIds(limit = 5, integrationTaskIds
     });
     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],
@@ -470,7 +589,13 @@ export async function listRecoverableA2AIntegrationTasks(limit = 50) {
     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
@@ -478,13 +603,16 @@ export async function listRecoverableA2AIntegrationTasks(limit = 50) {
             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)),
         ],
@@ -495,6 +623,8 @@ export async function listRecoverableA2AIntegrationTasks(limit = 50) {
         externalThreadId: String(row.external_thread_id),
         dispatchScope: row.dispatch_scope ?? null,
         status: String(row.status),
+        hasPendingConfirmedDelivery: row.has_pending_confirmed_delivery === true ||
+            Number(row.has_pending_confirmed_delivery ?? 0) === 1,
     }));
 }
 export async function claimA2AContinuationDelivery(id) {
@@ -537,6 +667,105 @@ export async function rescheduleA2AContinuation(id, delayMs) {
         args: ["pending", now + delayMs, now, id],
     });
 }
+export async function retainA2AUnconfirmedDeliveryClaim(id) {
+    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, checkpoint) {
+    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, kind, historyPayload, errorMessage) {
+    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) {
+    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) {
     await ensureTable();
     const client = getDbExec();
@@ -544,9 +773,13 @@ export async function completeA2AContinuation(id) {
     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],
     });
 }
 export async function failA2AContinuation(id, errorMessage) {
@@ -556,7 +789,8 @@ export async function failA2AContinuation(id, errorMessage) {
     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],
     });