@agent-native/core 0.119.5 → 0.119.6

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1660
+- core files: 1662
 - toolkit files: 159
-- template files: 6330
+- template files: 6331

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.119.6
+
+### Patch Changes
+
+- f3c3523: Add an opt-in, scoped Netlify background handoff and scheduled recovery sweep for durable messaging-integration tasks.
+
 ## 0.119.5
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.119.5",
+  "version": "0.119.6",
   "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/agent/durable-background.ts

@@ -85,6 +85,7 @@ export const AGENT_BACKGROUND_FUNCTION_URL_PATH = `/.netlify/functions/${AGENT_B
  */
 export const AGENT_BACKGROUND_PROCESSOR_FIELD = "__agentNativeProcessor";
 export const AGENT_BACKGROUND_PROCESSOR_A2A = "a2a";
+export const AGENT_BACKGROUND_PROCESSOR_INTEGRATION = "integration";
 export const AGENT_BACKGROUND_PROCESSOR_ROUTE = "route";
 export const AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD =
   "__agentNativeProcessorRoute";

package/corpus/core/src/deploy/build.ts

@@ -24,10 +24,16 @@ import {
   AGENT_BACKGROUND_FUNCTION_NAME,
   AGENT_BACKGROUND_PROCESSOR_A2A,
   AGENT_BACKGROUND_PROCESSOR_FIELD,
+  AGENT_BACKGROUND_PROCESSOR_INTEGRATION,
   AGENT_BACKGROUND_PROCESSOR_ROUTE,
   AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD,
   AGENT_CHAT_PROCESS_RUN_PATH,
 } from "../agent/durable-background.js";
+import {
+  INTEGRATION_RETRY_SWEEP_PATH,
+  INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT,
+  isIntegrationDurableDispatchConfigured,
+} from "../integrations/integration-durable-dispatch-config.js";
 import { normalizeAppBasePath } from "../server/app-base-path.js";
 import {
   DEFAULT_SSR_CDN_CACHE_CONTROL,
@@ -2369,6 +2375,13 @@ export function isDurableBackgroundDeployEnabled(): boolean {
   return v === "1" || v === "true" || v === "yes" || v === "on";
 }
 
+export const NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME =
+  "server-integration-recovery";
+
+export function isIntegrationDurableDispatchDeployEnabled(): boolean {
+  return isIntegrationDurableDispatchConfigured();
+}
+
 const NETLIFY_KEEP_WARM_FUNCTION_NAME = "agent-native-keep-warm";
 
 /**
@@ -2536,10 +2549,16 @@ export function emitSingleTemplateNetlifyBackgroundFunction(
 
   const processRunPath = JSON.stringify(AGENT_CHAT_PROCESS_RUN_PATH);
   const a2aProcessTaskPath = JSON.stringify("/_agent-native/a2a/_process-task");
+  const integrationProcessTaskPath = JSON.stringify(
+    "/_agent-native/integrations/process-task",
+  );
   const backgroundProcessorField = JSON.stringify(
     AGENT_BACKGROUND_PROCESSOR_FIELD,
   );
   const backgroundProcessorA2A = JSON.stringify(AGENT_BACKGROUND_PROCESSOR_A2A);
+  const backgroundProcessorIntegration = JSON.stringify(
+    AGENT_BACKGROUND_PROCESSOR_INTEGRATION,
+  );
   const backgroundProcessorRoute = JSON.stringify(
     AGENT_BACKGROUND_PROCESSOR_ROUTE,
   );
@@ -2558,8 +2577,10 @@ globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
 // The framework route the Nitro router dispatches to (the _process-run plugin).
 const PROCESS_RUN_PATH = ${processRunPath};
 const A2A_PROCESS_TASK_PATH = ${a2aProcessTaskPath};
+const INTEGRATION_PROCESS_TASK_PATH = ${integrationProcessTaskPath};
 const BACKGROUND_PROCESSOR_FIELD = ${backgroundProcessorField};
 const BACKGROUND_PROCESSOR_A2A = ${backgroundProcessorA2A};
+const BACKGROUND_PROCESSOR_INTEGRATION = ${backgroundProcessorIntegration};
 const BACKGROUND_PROCESSOR_ROUTE = ${backgroundProcessorRoute};
 const BACKGROUND_PROCESSOR_ROUTE_FIELD = ${backgroundProcessorRouteField};
 
@@ -2570,6 +2591,12 @@ function processorPathFromBody(body) {
     if (parsed?.[BACKGROUND_PROCESSOR_FIELD] === BACKGROUND_PROCESSOR_A2A) {
       return A2A_PROCESS_TASK_PATH;
     }
+    if (
+      parsed?.[BACKGROUND_PROCESSOR_FIELD] ===
+      BACKGROUND_PROCESSOR_INTEGRATION
+    ) {
+      return INTEGRATION_PROCESS_TASK_PATH;
+    }
     const route = parsed?.[BACKGROUND_PROCESSOR_ROUTE_FIELD];
     if (
       parsed?.[BACKGROUND_PROCESSOR_FIELD] === BACKGROUND_PROCESSOR_ROUTE &&
@@ -2658,6 +2685,78 @@ export const config = {
   );
 }
 
+export function emitSingleTemplateNetlifyIntegrationRecoveryFunction(
+  projectCwd: string,
+): void {
+  const internalDir = path.join(projectCwd, ".netlify", "functions-internal");
+  const serverDir = path.join(internalDir, "server");
+  if (!fs.existsSync(path.join(serverDir, "main.mjs"))) {
+    console.warn(
+      "[build] Integration recovery emit skipped: expected Nitro Netlify function " +
+        "at .netlify/functions-internal/server/main.mjs was not found.",
+    );
+    return;
+  }
+  const functionName = NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME;
+  const dest = path.join(internalDir, functionName);
+  fs.rmSync(dest, { recursive: true, force: true });
+  copyDir(serverDir, dest);
+  fs.rmSync(path.join(dest, "server.mjs"), { force: true });
+
+  const entry = `import { createHmac } from "node:crypto";
+
+const SWEEP_PATH = ${JSON.stringify(INTEGRATION_RETRY_SWEEP_PATH)};
+const SWEEP_SUBJECT = ${JSON.stringify(INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT)};
+
+function enabled() {
+  const raw = process.env.AGENT_INTEGRATION_DURABLE_DISPATCH;
+  if (!raw) return false;
+  return ["1", "true", "yes", "on"].includes(raw.trim().toLowerCase());
+}
+
+function token(secret) {
+  const timestamp = Date.now();
+  const signature = createHmac("sha256", secret)
+    .update(\`${INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT}:\${timestamp}\`)
+    .digest("hex");
+  return \`\${timestamp}.\${signature}\`;
+}
+
+let cachedHandler;
+
+export default async function handler(request, context) {
+  if (!enabled()) return new Response(null, { status: 204 });
+  const secret = process.env.A2A_SECRET;
+  if (!secret) {
+    console.error("[integration-recovery] A2A_SECRET is required; sweep skipped");
+    return new Response(null, { status: 204 });
+  }
+  cachedHandler ??= (await import("./main.mjs")).default;
+  const url = new URL(request.url);
+  url.pathname = SWEEP_PATH;
+  const rewritten = new Request(url.toString(), {
+    method: "POST",
+    headers: {
+      Authorization: \`Bearer \${token(secret)}\`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ taskId: SWEEP_SUBJECT }),
+  });
+  return cachedHandler(rewritten, context);
+}
+
+export const config = {
+  name: "integration pending-task recovery",
+  generator: "agent-native build",
+  schedule: "* * * * *",
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  preferStatic: false,
+};
+`;
+  fs.writeFileSync(path.join(dest, `${functionName}.mjs`), entry);
+}
+
 /**
  * Nitro's Netlify preset can emit a harmful fallback rewrite to
  * `/.netlify/functions/server`. With `config.path: "/*"`, that default URL is
@@ -2950,7 +3049,10 @@ export function assertSingleTemplateNetlifyBuildOutput(
     );
   }
 
-  if (isDurableBackgroundDeployEnabled()) {
+  if (
+    isDurableBackgroundDeployEnabled() ||
+    isIntegrationDurableDispatchDeployEnabled()
+  ) {
     const backgroundDir = path.join(
       internalDir,
       AGENT_BACKGROUND_FUNCTION_NAME,
@@ -2987,6 +3089,32 @@ export function assertSingleTemplateNetlifyBuildOutput(
     }
   }
 
+  if (isIntegrationDurableDispatchDeployEnabled()) {
+    const recoveryEntryPath = path.join(
+      internalDir,
+      NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME,
+      `${NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME}.mjs`,
+    );
+    if (!fs.existsSync(recoveryEntryPath)) {
+      failures.push(
+        `integration durable dispatch is enabled but ${path.relative(
+          projectCwd,
+          recoveryEntryPath,
+        )} was not emitted`,
+      );
+    } else {
+      const recoveryEntry = fs.readFileSync(recoveryEntryPath, "utf-8");
+      if (!/\bschedule\s*:\s*["']\* \* \* \* \*["']/.test(recoveryEntry)) {
+        failures.push(
+          `integration recovery entry ${path.relative(
+            projectCwd,
+            recoveryEntryPath,
+          )} is missing the one-minute schedule`,
+        );
+      }
+    }
+  }
+
   if (failures.length > 0) {
     throw new Error(
       "[deploy] Netlify deploy guard failed; refusing to publish an output " +
@@ -3638,7 +3766,10 @@ export default bundle;
     // bundle, so the chat `_process-run` POST lands on Netlify's async (15-min)
     // function. When not opted in this is a no-op and the single-function
     // deploy is byte-for-byte unchanged.
-    if (isDurableBackgroundDeployEnabled()) {
+    if (
+      isDurableBackgroundDeployEnabled() ||
+      isIntegrationDurableDispatchDeployEnabled()
+    ) {
       try {
         emitSingleTemplateNetlifyBackgroundFunction(cwd);
       } catch (err) {
@@ -3649,6 +3780,17 @@ export default bundle;
       }
     }
 
+    if (isIntegrationDurableDispatchDeployEnabled()) {
+      try {
+        emitSingleTemplateNetlifyIntegrationRecoveryFunction(cwd);
+      } catch (err) {
+        console.warn(
+          "[build] Failed to emit integration recovery Netlify function (non-fatal):",
+          err instanceof Error ? err.message : err,
+        );
+      }
+    }
+
     writeSingleTemplateNetlifyRedirects(cwd);
     assertSingleTemplateNetlifyBuildOutput(cwd);
   }

package/corpus/core/src/deploy/workspace-deploy.ts

@@ -21,10 +21,16 @@ import path from "path";
 import {
   AGENT_BACKGROUND_PROCESSOR_A2A,
   AGENT_BACKGROUND_PROCESSOR_FIELD,
+  AGENT_BACKGROUND_PROCESSOR_INTEGRATION,
   AGENT_BACKGROUND_PROCESSOR_ROUTE,
   AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD,
   AGENT_CHAT_PROCESS_RUN_PATH,
 } from "../agent/durable-background.js";
+import {
+  INTEGRATION_RETRY_SWEEP_PATH,
+  INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT,
+  isIntegrationDurableDispatchConfigured,
+} from "../integrations/integration-durable-dispatch-config.js";
 import { findWorkspaceRoot } from "../scripts/utils.js";
 import {
   DEFAULT_WORKSPACE_APP_AUDIENCE,
@@ -677,9 +683,19 @@ function copyNetlifyFunctionIntoWorkspace(
   // Durable background agent runs (default-ON; opt out with a falsy
   // AGENT_CHAT_DURABLE_BACKGROUND). Additive ONLY: when explicitly opted out
   // this emits nothing and the single-function deploy is unchanged.
-  if (isDurableBackgroundDeployEnabled()) {
+  const integrationDurableDispatch =
+    app === "dispatch" && isIntegrationDurableDispatchConfigured();
+  if (isDurableBackgroundDeployEnabled() || integrationDurableDispatch) {
     emitNetlifyBackgroundFunction(workspaceRoot, app, src, workspaceApps);
   }
+  if (integrationDurableDispatch) {
+    emitNetlifyIntegrationRecoveryFunction(
+      workspaceRoot,
+      app,
+      src,
+      workspaceApps,
+    );
+  }
 }
 
 /**
@@ -753,6 +769,7 @@ function emitNetlifyBackgroundFunction(
   // incoming pathname to `/<app>/_agent-native/agent-chat/_process-run`.
   const processRunPath = `${basePath}${AGENT_CHAT_PROCESS_RUN_PATH}`;
   const a2aProcessTaskPath = `${basePath}/_agent-native/a2a/_process-task`;
+  const integrationProcessTaskPath = `${basePath}/_agent-native/integrations/process-task`;
   const server = `// Mark this isolate as the durable background runtime BEFORE the handler bundle
 // is imported, so isInBackgroundFunctionRuntime() reliably returns true in this
 // function (the deployed Lambda name is not guaranteed to end in -background). A
@@ -764,8 +781,10 @@ const basePath = ${JSON.stringify(basePath)};
 // The base-path-prefixed framework route the Nitro router dispatches to.
 const PROCESS_RUN_PATH = ${JSON.stringify(processRunPath)};
 const A2A_PROCESS_TASK_PATH = ${JSON.stringify(a2aProcessTaskPath)};
+const INTEGRATION_PROCESS_TASK_PATH = ${JSON.stringify(integrationProcessTaskPath)};
 const BACKGROUND_PROCESSOR_FIELD = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_FIELD)};
 const BACKGROUND_PROCESSOR_A2A = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_A2A)};
+const BACKGROUND_PROCESSOR_INTEGRATION = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_INTEGRATION)};
 const BACKGROUND_PROCESSOR_ROUTE = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_ROUTE)};
 const BACKGROUND_PROCESSOR_ROUTE_FIELD = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD)};
 
@@ -776,6 +795,12 @@ function processorPathFromBody(body) {
     if (parsed?.[BACKGROUND_PROCESSOR_FIELD] === BACKGROUND_PROCESSOR_A2A) {
       return A2A_PROCESS_TASK_PATH;
     }
+    if (
+      parsed?.[BACKGROUND_PROCESSOR_FIELD] ===
+      BACKGROUND_PROCESSOR_INTEGRATION
+    ) {
+      return INTEGRATION_PROCESS_TASK_PATH;
+    }
     const route = parsed?.[BACKGROUND_PROCESSOR_ROUTE_FIELD];
     if (
       parsed?.[BACKGROUND_PROCESSOR_FIELD] === BACKGROUND_PROCESSOR_ROUTE &&
@@ -862,6 +887,103 @@ export const config = {
   );
 }
 
+function emitNetlifyIntegrationRecoveryFunction(
+  workspaceRoot: string,
+  app: string,
+  srcServerDir: string,
+  workspaceApps: WorkspaceAppManifestEntry[],
+): void {
+  const functionName = `${app}-integration-recovery`;
+  const dest = path.join(netlifyFunctionsDir(workspaceRoot), functionName);
+  fs.rmSync(dest, { recursive: true, force: true });
+  copyDir(srcServerDir, dest);
+  fs.rmSync(path.join(dest, "server.mjs"), { force: true });
+
+  const basePath = `/${app}`;
+  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
+  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
+    workspaceApps,
+    app,
+  );
+  const sweepPath = `${basePath}${INTEGRATION_RETRY_SWEEP_PATH}`;
+  const entry = `import { createHmac } from "node:crypto";
+
+const basePath = ${JSON.stringify(basePath)};
+const SWEEP_PATH = ${JSON.stringify(sweepPath)};
+const SWEEP_SUBJECT = ${JSON.stringify(INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT)};
+
+function setBasePathEnv() {
+  const processRef = globalThis.process ??= { env: {} };
+  processRef.env ??= {};
+  Object.assign(processRef.env, {
+    AGENT_NATIVE_WORKSPACE: "1",
+    AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    APP_BASE_PATH: basePath,
+    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE: "1",
+    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    VITE_APP_BASE_PATH: basePath,
+    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: ${JSON.stringify(JSON.stringify(workspaceApps))},
+    ${JSON.stringify(WORKSPACE_APPS_ENV_KEY)}: ${JSON.stringify(JSON.stringify(workspaceApps))},
+  });
+}
+
+function enabled() {
+  const raw = process.env.AGENT_INTEGRATION_DURABLE_DISPATCH;
+  if (!raw) return false;
+  return ["1", "true", "yes", "on"].includes(raw.trim().toLowerCase());
+}
+
+function token(secret) {
+  const timestamp = Date.now();
+  const signature = createHmac("sha256", secret)
+    .update(\`${INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT}:\${timestamp}\`)
+    .digest("hex");
+  return \`\${timestamp}.\${signature}\`;
+}
+
+setBasePathEnv();
+let cachedHandler;
+
+export default async function handler(request, context) {
+  setBasePathEnv();
+  if (!enabled()) return new Response(null, { status: 204 });
+  const secret = process.env.A2A_SECRET;
+  if (!secret) {
+    console.error("[integration-recovery] A2A_SECRET is required; sweep skipped");
+    return new Response(null, { status: 204 });
+  }
+  cachedHandler ??= (await import("./main.mjs")).default;
+  const url = new URL(request.url);
+  url.pathname = SWEEP_PATH;
+  const rewritten = new Request(url.toString(), {
+    method: "POST",
+    headers: {
+      Authorization: \`Bearer \${token(secret)}\`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ taskId: SWEEP_SUBJECT }),
+  });
+  return cachedHandler(rewritten, context);
+}
+
+export const config = {
+  name: ${JSON.stringify(`${app} integration pending-task recovery`)},
+  generator: "agent-native workspace deploy",
+  schedule: "* * * * *",
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  preferStatic: false,
+};
+`;
+  fs.writeFileSync(path.join(dest, `${functionName}.mjs`), entry);
+}
+
 function patchNetlifyFunctionEntry(
   functionDir: string,
   app: string,

package/corpus/core/src/integrations/integration-durable-dispatch-config.ts

@@ -0,0 +1,22 @@
+export const INTEGRATION_DURABLE_DISPATCH_ENV =
+  "AGENT_INTEGRATION_DURABLE_DISPATCH";
+export const INTEGRATION_DURABLE_DISPATCH_SCOPES_ENV =
+  "AGENT_INTEGRATION_DURABLE_DISPATCH_SCOPES";
+export const INTEGRATION_PROCESS_TASK_PATH =
+  "/_agent-native/integrations/process-task";
+export const INTEGRATION_RETRY_SWEEP_PATH =
+  "/_agent-native/integrations/retry-stuck-tasks";
+export const INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT =
+  "integration-pending-tasks-sweep";
+
+export function isIntegrationDurableDispatchConfigured(): boolean {
+  const value = process.env.AGENT_INTEGRATION_DURABLE_DISPATCH;
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return (
+    normalized === "1" ||
+    normalized === "true" ||
+    normalized === "yes" ||
+    normalized === "on"
+  );
+}

package/corpus/core/src/integrations/integration-durable-dispatch.ts

@@ -0,0 +1,190 @@
+import { hasConfiguredA2ASecret } from "../a2a/auth-policy.js";
+import {
+  AGENT_BACKGROUND_PROCESSOR_FIELD,
+  AGENT_BACKGROUND_PROCESSOR_INTEGRATION,
+  dispatchPathTargetsNetlifyBackgroundFunction,
+  resolveDurableBackgroundDispatchPath,
+} from "../agent/durable-background.js";
+import { fireInternalDispatch } from "../server/self-dispatch.js";
+import {
+  INTEGRATION_DURABLE_DISPATCH_ENV,
+  INTEGRATION_DURABLE_DISPATCH_SCOPES_ENV,
+  INTEGRATION_PROCESS_TASK_PATH,
+  INTEGRATION_RETRY_SWEEP_PATH,
+  INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT,
+  isIntegrationDurableDispatchConfigured,
+} from "./integration-durable-dispatch-config.js";
+import { recordPendingTaskDispatchAttempt } from "./pending-tasks-store.js";
+
+export {
+  INTEGRATION_DURABLE_DISPATCH_ENV,
+  INTEGRATION_DURABLE_DISPATCH_SCOPES_ENV,
+  INTEGRATION_PROCESS_TASK_PATH,
+  INTEGRATION_RETRY_SWEEP_PATH,
+  INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT,
+  isIntegrationDurableDispatchConfigured,
+};
+
+export type IntegrationDispatchOutcome =
+  | "background-acknowledged"
+  | "portable-unconfirmed"
+  | "failed";
+
+export interface IntegrationDispatchTaskScope {
+  platform: string;
+  externalThreadId: string;
+  platformContext?: Record<string, unknown>;
+}
+
+export interface IntegrationDurableDispatchScope {
+  platform: string;
+  value: string;
+}
+
+export function integrationDispatchScopeValue(
+  task: IntegrationDispatchTaskScope,
+): string | null {
+  const value = task.platformContext?.channelId;
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+export function configuredIntegrationDurableDispatchScopes():
+  | IntegrationDurableDispatchScope[]
+  | null {
+  const raw = process.env.AGENT_INTEGRATION_DURABLE_DISPATCH_SCOPES;
+  if (!raw?.trim()) return null;
+  return raw
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean)
+    .map((scope) => {
+      const separator = scope.indexOf(":");
+      return {
+        platform: separator > 0 ? scope.slice(0, separator) : "",
+        value: separator > 0 ? scope.slice(separator + 1) : "",
+      };
+    })
+    .filter((scope) => scope.platform && scope.value);
+}
+
+function taskScopeCandidates(task: IntegrationDispatchTaskScope): string[] {
+  const candidates = [
+    `${task.platform}:*`,
+    `${task.platform}:${task.externalThreadId}`,
+  ];
+  const explicitScope = integrationDispatchScopeValue(task);
+  if (explicitScope) {
+    candidates.push(`${task.platform}:${explicitScope}`);
+  } else if (task.platform === "slack") {
+    const channelId = task.externalThreadId.split(":")[2];
+    if (channelId) candidates.push(`slack:${channelId}`);
+  }
+  return candidates;
+}
+
+export function isIntegrationDurableDispatchEnabledForTask(
+  task: IntegrationDispatchTaskScope,
+): boolean {
+  if (!isIntegrationDurableDispatchConfigured()) return false;
+  const scopes = configuredIntegrationDurableDispatchScopes();
+  if (
+    scopes &&
+    !taskScopeCandidates(task).some((candidate) =>
+      scopes.some((scope) => `${scope.platform}:${scope.value}` === candidate),
+    )
+  ) {
+    return false;
+  }
+  const path = resolveDurableBackgroundDispatchPath(
+    INTEGRATION_PROCESS_TASK_PATH,
+  );
+  return (
+    dispatchPathTargetsNetlifyBackgroundFunction(path) &&
+    hasConfiguredA2ASecret()
+  );
+}
+
+async function recordDispatch(
+  taskId: string,
+  outcome: IntegrationDispatchOutcome,
+): Promise<void> {
+  try {
+    await recordPendingTaskDispatchAttempt(taskId, outcome);
+  } catch (error) {
+    console.error(
+      `[integrations] Failed to record dispatch outcome for ${taskId}:`,
+      error,
+    );
+  }
+}
+
+function logDispatch(
+  taskId: string,
+  outcome: IntegrationDispatchOutcome,
+  startedAt: number,
+): void {
+  console.info("[integrations] pending task dispatch", {
+    taskId,
+    outcome,
+    durationMs: Date.now() - startedAt,
+  });
+}
+
+export async function dispatchPendingIntegrationTask(input: {
+  taskId: string;
+  task: IntegrationDispatchTaskScope;
+  event?: unknown;
+  baseUrl?: string;
+  portableSettleMs?: number;
+}): Promise<IntegrationDispatchOutcome> {
+  const startedAt = Date.now();
+  const durable = isIntegrationDurableDispatchEnabledForTask(input.task);
+  if (durable) {
+    const backgroundPath = resolveDurableBackgroundDispatchPath(
+      INTEGRATION_PROCESS_TASK_PATH,
+    );
+    try {
+      await fireInternalDispatch({
+        event: input.event,
+        baseUrl: input.baseUrl,
+        path: backgroundPath,
+        taskId: input.taskId,
+        body: {
+          [AGENT_BACKGROUND_PROCESSOR_FIELD]:
+            AGENT_BACKGROUND_PROCESSOR_INTEGRATION,
+        },
+        awaitResponse: true,
+        responseTimeoutMs: 2_000,
+      });
+      await recordDispatch(input.taskId, "background-acknowledged");
+      logDispatch(input.taskId, "background-acknowledged", startedAt);
+      return "background-acknowledged";
+    } catch (error) {
+      console.error(
+        `[integrations] Background dispatch failed for ${input.taskId}; trying the portable processor:`,
+        error,
+      );
+    }
+  }
+
+  try {
+    await fireInternalDispatch({
+      event: input.event,
+      baseUrl: input.baseUrl,
+      path: INTEGRATION_PROCESS_TASK_PATH,
+      taskId: input.taskId,
+      settleMs: input.portableSettleMs,
+    });
+    await recordDispatch(input.taskId, "portable-unconfirmed");
+    logDispatch(input.taskId, "portable-unconfirmed", startedAt);
+    return "portable-unconfirmed";
+  } catch (error) {
+    console.error(
+      `[integrations] Portable dispatch failed for ${input.taskId}:`,
+      error,
+    );
+    await recordDispatch(input.taskId, "failed");
+    logDispatch(input.taskId, "failed", startedAt);
+    return "failed";
+  }
+}