@agent-native/core 0.141.2 → 0.141.4

package/dist/db/migrations.js

@@ -154,6 +154,15 @@ function splitSqlStatements(sql) {
         out.push(tail);
     return out;
 }
+/**
+ * A run-only migration can defer its work without recording itself as applied.
+ * This is for serialized backfills where another instance owns the advisory
+ * lock; throwing would turn an expected loser into a startup retry storm.
+ */
+export const MIGRATION_DEFERRED = Symbol("migration-deferred");
+export function deferMigration() {
+    return MIGRATION_DEFERRED;
+}
 function resolveMigrationSql(sql, pg) {
     if (typeof sql === "string")
         return sql;
@@ -272,8 +281,11 @@ export function runMigrations(migrations, options) {
                     try {
                         // D1 is SQLite-compatible
                         const raw = resolveMigrationSql(m.sql, false);
-                        if (m.run)
-                            await m.run();
+                        const runResult = m.run ? await m.run() : undefined;
+                        if (runResult === MIGRATION_DEFERRED) {
+                            console.info(`[db] Deferred migration ${m.name ? `"${m.name}" ` : ""}v${m.version}; it remains pending for a later boot`);
+                            continue;
+                        }
                         const recordStatements = [
                             m.name
                                 ? d1
@@ -482,8 +494,11 @@ export function runMigrations(migrations, options) {
                     // A throw here escapes to the outer handler with nothing recorded,
                     // so the entry is retried on the next boot rather than being marked
                     // applied against work that never happened.
-                    if (m.run)
-                        await m.run();
+                    const runResult = m.run ? await m.run() : undefined;
+                    if (runResult === MIGRATION_DEFERRED) {
+                        console.info(`[db] Deferred migration ${label}; it remains pending for a later boot`);
+                        continue;
+                    }
                     if (raw == null) {
                         // Dialect-gated migration with no SQL for this dialect; still mark
                         // as applied so we don't retry forever.

package/dist/deploy/build.d.ts

@@ -90,6 +90,8 @@ export declare function findInstalledResvgPackages(nodeModulesRoots: string[]):
 export declare function isDurableBackgroundDeployEnabled(): boolean;
 export declare const NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME = "server-integration-recovery";
 export declare function isIntegrationDurableDispatchDeployEnabled(): boolean;
+export declare const NETLIFY_RECURRING_JOBS_FUNCTION_NAME = "agent-native-recurring-jobs";
+export declare function isRecurringJobsDeployEnabled(): boolean;
 /**
  * Emit a site-local Netlify Scheduled Function that wakes the public server
  * function and its database every minute. GitHub Actions schedules can be
@@ -97,6 +99,12 @@ export declare function isIntegrationDurableDispatchDeployEnabled(): boolean;
  * autosuspend window and leaves the next visitor to pay the cold-start cost.
  */
 export declare function emitSingleTemplateNetlifyKeepWarmFunction(projectCwd: string): void;
+/**
+ * Emit the durable recurring-job trigger. Netlify's scheduled function only
+ * hands off work; the existing `-background` function owns the long sweep so
+ * a model run is not constrained by the synchronous scheduled-function wall.
+ */
+export declare function emitSingleTemplateNetlifyRecurringJobsFunction(projectCwd: string): void;
 /**
  * Single-template Netlify build: emit an async (background) function INSIDE the
  * scanned functions dir so the chat `_process-run` worker runs on Netlify's

package/dist/deploy/build.js

@@ -20,6 +20,7 @@ import path from "path";
 import { fileURLToPath } from "url";
 import { AGENT_BACKGROUND_FUNCTION_NAME, AGENT_BACKGROUND_FUNCTION_URL_PATH, 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, isDurableBackgroundFlagExplicitlyDisabled, } from "../agent/durable-background.js";
 import { INTEGRATION_RECOVERY_RUNTIME_MARKER, INTEGRATION_RETRY_SWEEP_PATH, INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT, isIntegrationDurableDispatchConfigured, } from "../integrations/integration-durable-dispatch-config.js";
+import { RECURRING_JOBS_SWEEP_PATH, RECURRING_JOBS_SWEEP_TOKEN_SUBJECT, } from "../jobs/scheduler-dispatch.js";
 import { normalizeAppBasePath } from "../server/app-base-path.js";
 import { DEFAULT_SPECULATION_RULES_PATH, resolveSsrCacheHeaders, } from "../shared/cache-control.js";
 import { mcpEmbedStaticAssetRouteRules } from "../shared/mcp-embed-headers.js";
@@ -2090,13 +2091,19 @@ export function isDurableBackgroundDeployEnabled() {
  */
 function isDurableBackgroundEmitRequired() {
     return (isDurableBackgroundDeployEnabled() ||
-        isIntegrationDurableDispatchDeployEnabled());
+        isIntegrationDurableDispatchDeployEnabled() ||
+        isRecurringJobsDeployEnabled());
 }
 export const NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME = "server-integration-recovery";
 export function isIntegrationDurableDispatchDeployEnabled() {
     return isIntegrationDurableDispatchConfigured();
 }
 const NETLIFY_KEEP_WARM_FUNCTION_NAME = "agent-native-keep-warm";
+export const NETLIFY_RECURRING_JOBS_FUNCTION_NAME = "agent-native-recurring-jobs";
+export function isRecurringJobsDeployEnabled() {
+    const value = process.env.AGENT_NATIVE_DISABLE_RECURRING_JOBS?.trim();
+    return !value || !["1", "true", "yes", "on"].includes(value.toLowerCase());
+}
 /**
  * Emit a site-local Netlify Scheduled Function that wakes the public server
  * function and its database every minute. GitHub Actions schedules can be
@@ -2170,7 +2177,7 @@ export default async function handler(request) {
   }
 
   if (!response.ok) {
-    const body = await response.text().catch(() => "");
+    const body = await response.text();
     throw new Error(
       "[agent-native-keep-warm] Health request failed with " +
         response.status +
@@ -2194,6 +2201,84 @@ export const config = {
     fs.writeFileSync(path.join(dest, `${NETLIFY_KEEP_WARM_FUNCTION_NAME}.mjs`), entry);
     console.log(`[build] Emitted Netlify scheduled keep-warm function "${NETLIFY_KEEP_WARM_FUNCTION_NAME}".`);
 }
+/**
+ * Emit the durable recurring-job trigger. Netlify's scheduled function only
+ * hands off work; the existing `-background` function owns the long sweep so
+ * a model run is not constrained by the synchronous scheduled-function wall.
+ */
+export function emitSingleTemplateNetlifyRecurringJobsFunction(projectCwd) {
+    if (!isRecurringJobsDeployEnabled())
+        return;
+    const internalDir = path.join(projectCwd, ".netlify", "functions-internal");
+    const backgroundEntry = path.join(internalDir, AGENT_BACKGROUND_FUNCTION_NAME, `${AGENT_BACKGROUND_FUNCTION_NAME}.mjs`);
+    if (!fs.existsSync(backgroundEntry)) {
+        throw new Error("[build] Recurring-job trigger cannot be emitted without the durable background function.");
+    }
+    const functionName = NETLIFY_RECURRING_JOBS_FUNCTION_NAME;
+    const dest = path.join(internalDir, functionName);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.mkdirSync(dest, { recursive: true });
+    const entry = `import { createHmac } from "node:crypto";
+
+const BACKGROUND_PATH = ${JSON.stringify(AGENT_BACKGROUND_FUNCTION_URL_PATH)};
+const SWEEP_PATH = ${JSON.stringify(RECURRING_JOBS_SWEEP_PATH)};
+const TOKEN_SUBJECT = ${JSON.stringify(RECURRING_JOBS_SWEEP_TOKEN_SUBJECT)};
+const PROCESSOR_FIELD = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_FIELD)};
+const PROCESSOR_ROUTE = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_ROUTE)};
+const PROCESSOR_ROUTE_FIELD = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD)};
+
+function siteOrigin(request) {
+  const configured = process.env.URL || process.env.DEPLOY_URL;
+  if (configured) return configured;
+  return new URL(request.url).origin;
+}
+
+function token(secret) {
+  const timestamp = Date.now();
+  const signature = createHmac("sha256", secret)
+    .update(\`\${TOKEN_SUBJECT}:\${timestamp}\`)
+    .digest("hex");
+  return \`\${timestamp}.\${signature}\`;
+}
+
+export default async function handler(request) {
+  const secret = process.env.A2A_SECRET;
+  if (!secret) {
+    throw new Error("[recurring-jobs] A2A_SECRET is required for the scheduled sweep");
+  }
+  const url = new URL(BACKGROUND_PATH, siteOrigin(request));
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: \`Bearer \${token(secret)}\`,
+      "Content-Type": "application/json",
+      "user-agent": "agent-native-recurring-jobs",
+    },
+    body: JSON.stringify({
+      [PROCESSOR_FIELD]: PROCESSOR_ROUTE,
+      [PROCESSOR_ROUTE_FIELD]: SWEEP_PATH,
+    }),
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      \`[recurring-jobs] Durable sweep handoff failed (\${response.status}): \${body.slice(0, 500)}\`,
+    );
+  }
+  console.log("[recurring-jobs] Durable sweep handed off", url.toString());
+  return new Response(null, { status: 204 });
+}
+
+export const config = {
+  name: "agent-native recurring jobs",
+  generator: "agent-native build",
+  schedule: "* * * * *",
+  nodeBundler: "none",
+};
+`;
+    fs.writeFileSync(path.join(dest, `${functionName}.mjs`), entry);
+    console.log(`[build] Emitted Netlify scheduled recurring-job function "${functionName}".`);
+}
 /**
  * Single-template Netlify build: emit an async (background) function INSIDE the
  * scanned functions dir so the chat `_process-run` worker runs on Netlify's
@@ -2289,6 +2374,7 @@ export function emitSingleTemplateNetlifyBackgroundFunction(projectCwd) {
     const backgroundProcessorIntegration = JSON.stringify(AGENT_BACKGROUND_PROCESSOR_INTEGRATION);
     const backgroundProcessorRoute = JSON.stringify(AGENT_BACKGROUND_PROCESSOR_ROUTE);
     const backgroundProcessorRouteField = JSON.stringify(AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD);
+    const recurringJobsSweepPath = JSON.stringify(RECURRING_JOBS_SWEEP_PATH);
     const entry = `// 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
@@ -2307,6 +2393,7 @@ const BACKGROUND_PROCESSOR_A2A = ${backgroundProcessorA2A};
 const BACKGROUND_PROCESSOR_INTEGRATION = ${backgroundProcessorIntegration};
 const BACKGROUND_PROCESSOR_ROUTE = ${backgroundProcessorRoute};
 const BACKGROUND_PROCESSOR_ROUTE_FIELD = ${backgroundProcessorRouteField};
+const RECURRING_JOBS_SWEEP_PATH = ${recurringJobsSweepPath};
 
 function processorPathFromBody(body) {
   if (!body) return null;
@@ -2326,7 +2413,8 @@ function processorPathFromBody(body) {
       parsed?.[BACKGROUND_PROCESSOR_FIELD] === BACKGROUND_PROCESSOR_ROUTE &&
       typeof route === "string" &&
       route.startsWith("/") &&
-      route.includes("/api/_agent-native-background/") &&
+      (route === RECURRING_JOBS_SWEEP_PATH ||
+        route.includes("/api/_agent-native-background/")) &&
       !route.includes("?") &&
       !route.includes("#")
     ) {
@@ -3367,6 +3455,7 @@ export default bundle;
         if (isDurableBackgroundEmitRequired()) {
             emitSingleTemplateNetlifyBackgroundFunction(cwd);
         }
+        emitSingleTemplateNetlifyRecurringJobsFunction(cwd);
         // Emit keep-warm after the background artifact so it only pings a function
         // that this build actually produced.
         emitSingleTemplateNetlifyKeepWarmFunction(cwd);

package/dist/deploy/workspace-deploy.js

@@ -19,10 +19,11 @@ import fs from "fs";
 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, isDurableBackgroundFlagExplicitlyDisabled, } from "../agent/durable-background.js";
 import { INTEGRATION_RECOVERY_RUNTIME_MARKER, INTEGRATION_RETRY_SWEEP_PATH, INTEGRATION_RETRY_SWEEP_TOKEN_SUBJECT, isIntegrationDurableDispatchConfigured, } from "../integrations/integration-durable-dispatch-config.js";
+import { RECURRING_JOBS_SWEEP_PATH, RECURRING_JOBS_SWEEP_TOKEN_SUBJECT, } from "../jobs/scheduler-dispatch.js";
 import { findWorkspaceRoot } from "../scripts/utils.js";
 import { DEFAULT_WORKSPACE_APP_AUDIENCE, normalizeWorkspaceAppAudience, normalizeWorkspaceAppPathList, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromPackageJson, } from "../shared/workspace-app-audience.js";
 import { DISPATCH_WORKSPACE_ROOT_REDIRECTS } from "../shared/workspace-app-id.js";
-import { assertEmittedBackgroundFunctionOnDisk } from "./build.js";
+import { assertEmittedBackgroundFunctionOnDisk, isRecurringJobsDeployEnabled, } from "./build.js";
 import { cloneServerBundleForFunction } from "./function-bundle.js";
 import { collectImmutableAssetPaths, IMMUTABLE_ASSET_CACHE_HEADERS, } from "./immutable-assets.js";
 const NETLIFY_WORKSPACE_STATIC_DIR = "_workspace_static";
@@ -464,14 +465,93 @@ function copyNetlifyFunctionIntoWorkspace(workspaceRoot, app, workspaceApps, sta
     // Durable background agent runs. Additive ONLY: when explicitly opted out
     // this emits nothing and the single-function deploy is unchanged.
     const integrationDurableDispatch = app === "dispatch" && isIntegrationDurableDispatchConfigured();
+    const recurringJobs = isRecurringJobsDeployEnabled();
     if (isDurableBackgroundWorkspaceDeployEnabled() ||
-        integrationDurableDispatch) {
+        integrationDurableDispatch ||
+        recurringJobs) {
         emitNetlifyBackgroundFunction(workspaceRoot, app, src, workspaceApps);
     }
+    if (recurringJobs) {
+        emitNetlifyRecurringJobsFunction(workspaceRoot, app);
+    }
     if (integrationDurableDispatch) {
         emitNetlifyIntegrationRecoveryFunction(workspaceRoot, app, src, workspaceApps);
     }
 }
+/**
+ * Emit the per-app Netlify Scheduled Function that hands one recurring-job
+ * sweep to that app's durable background worker. The worker owns the actual
+ * scan so scheduled-function timeouts cannot strand the automation runner.
+ */
+function emitNetlifyRecurringJobsFunction(workspaceRoot, app) {
+    const functionName = `${app}-agent-recurring-jobs`;
+    const dest = path.join(netlifyFunctionsDir(workspaceRoot), functionName);
+    const backgroundName = `${app}-agent-background`;
+    const backgroundPath = `/.netlify/functions/${backgroundName}`;
+    const sweepPath = `/${app}${RECURRING_JOBS_SWEEP_PATH}`;
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.mkdirSync(dest, { recursive: true });
+    const entry = `import { createHmac } from "node:crypto";
+
+const BACKGROUND_PATH = ${JSON.stringify(backgroundPath)};
+const SWEEP_PATH = ${JSON.stringify(sweepPath)};
+const TOKEN_SUBJECT = ${JSON.stringify(RECURRING_JOBS_SWEEP_TOKEN_SUBJECT)};
+const PROCESSOR_FIELD = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_FIELD)};
+const PROCESSOR_ROUTE = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_ROUTE)};
+const PROCESSOR_ROUTE_FIELD = ${JSON.stringify(AGENT_BACKGROUND_PROCESSOR_ROUTE_FIELD)};
+
+function siteOrigin(request) {
+  const configured = process.env.URL || process.env.DEPLOY_URL;
+  if (configured) return configured;
+  return new URL(request.url).origin;
+}
+
+function token(secret) {
+  const timestamp = Date.now();
+  const signature = createHmac("sha256", secret)
+    .update(\`${RECURRING_JOBS_SWEEP_TOKEN_SUBJECT}:\${timestamp}\`)
+    .digest("hex");
+  return \`\${timestamp}.\${signature}\`;
+}
+
+export default async function handler(request) {
+  const secret = process.env.A2A_SECRET;
+  if (!secret) {
+    throw new Error("[recurring-jobs] A2A_SECRET is required for the scheduled sweep");
+  }
+  const url = new URL(BACKGROUND_PATH, siteOrigin(request));
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: \`Bearer \${token(secret)}\`,
+      "Content-Type": "application/json",
+      "user-agent": "agent-native-recurring-jobs",
+    },
+    body: JSON.stringify({
+      [PROCESSOR_FIELD]: PROCESSOR_ROUTE,
+      [PROCESSOR_ROUTE_FIELD]: SWEEP_PATH,
+    }),
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      \`[recurring-jobs] Durable sweep handoff failed (\${response.status}): \${body.slice(0, 500)}\`,
+    );
+  }
+  console.log("[recurring-jobs] Durable sweep handed off", url.toString());
+  return new Response(null, { status: 204 });
+}
+
+export const config = {
+  name: ${JSON.stringify(`${app} agent-native recurring jobs`)},
+  generator: "agent-native workspace deploy",
+  schedule: "* * * * *",
+  nodeBundler: "none",
+};
+`;
+    fs.writeFileSync(path.join(dest, `${functionName}.mjs`), entry);
+    console.log(`[workspace-deploy] Emitted Netlify scheduled recurring-job function "${functionName}" for app "${app}".`);
+}
 /**
  * Deploy-time gate for emitting the per-app `-background` Netlify function.
  *
@@ -534,6 +614,7 @@ function emitNetlifyBackgroundFunction(workspaceRoot, app, srcServerDir, workspa
     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 recurringJobsSweepPath = `${basePath}${RECURRING_JOBS_SWEEP_PATH}`;
     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
@@ -546,6 +627,7 @@ const basePath = ${JSON.stringify(basePath)};
 const PROCESS_RUN_PATH = ${JSON.stringify(processRunPath)};
 const A2A_PROCESS_TASK_PATH = ${JSON.stringify(a2aProcessTaskPath)};
 const INTEGRATION_PROCESS_TASK_PATH = ${JSON.stringify(integrationProcessTaskPath)};
+const RECURRING_JOBS_SWEEP_PATH = ${JSON.stringify(recurringJobsSweepPath)};
 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)};
@@ -569,7 +651,8 @@ function processorPathFromBody(body) {
     if (
       parsed?.[BACKGROUND_PROCESSOR_FIELD] === BACKGROUND_PROCESSOR_ROUTE &&
       typeof route === "string" &&
-      route.startsWith(basePath + "/api/_agent-native-background/") &&
+      (route === RECURRING_JOBS_SWEEP_PATH ||
+        route.startsWith(basePath + "/api/_agent-native-background/")) &&
       !route.includes("?") &&
       !route.includes("#")
     ) {

package/dist/email-catalog/actions/list-email-activity.d.ts

@@ -0,0 +1,5 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    templateId: string;
+    limit?: unknown;
+}, import("../provider-metrics.js").ProviderMetricsResult<import("../provider-metrics.js").EmailActivityEntry[]>>;
+export default _default;

package/dist/email-catalog/actions/list-email-activity.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getRequestOrgId } from "../../server/request-context.js";
+import { authorizeTransactionalEmailRead } from "../authorize.js";
+import { fetchEmailActivity } from "../provider-metrics.js";
+export default defineAction({
+    description: "List recent provider activity for one registered transactional email in this app. Organization admin only.",
+    schema: z.object({
+        templateId: z.string().min(1),
+        limit: z.coerce.number().int().min(1).max(1000).default(50),
+    }),
+    http: { method: "GET" },
+    authorize: ({ templateId }) => authorizeTransactionalEmailRead([templateId]),
+    run: async ({ templateId, limit }) => fetchEmailActivity({
+        templateId,
+        limit,
+        orgId: getRequestOrgId(),
+    }),
+});

package/dist/email-catalog/actions/list-email-engagement.d.ts

@@ -0,0 +1,5 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    templateIds: string[];
+    windowDays?: unknown;
+}, import("../provider-metrics.js").ProviderMetricsResult<import("../provider-metrics.js").EmailEngagement[]>>;
+export default _default;

package/dist/email-catalog/actions/list-email-engagement.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getRequestOrgId } from "../../server/request-context.js";
+import { authorizeTransactionalEmailRead } from "../authorize.js";
+import { fetchEmailEngagement } from "../provider-metrics.js";
+export default defineAction({
+    description: "Read provider engagement metrics for registered transactional emails in this app. Organization admin only.",
+    schema: z.object({
+        templateIds: z.array(z.string().min(1)).max(100),
+        windowDays: z.coerce.number().int().min(1).max(365).default(30),
+    }),
+    http: { method: "POST" },
+    authorize: ({ templateIds }) => authorizeTransactionalEmailRead(templateIds),
+    run: async ({ templateIds, windowDays }) => fetchEmailEngagement(templateIds, windowDays, getRequestOrgId()),
+});

package/dist/email-catalog/actions/list-email-log.d.ts

@@ -0,0 +1,7 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    templateId?: string;
+    limit?: unknown;
+}, {
+    entries: import("../log.js").EmailLogEntry[];
+}>;
+export default _default;

package/dist/email-catalog/actions/list-email-log.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getAppSlug } from "../../server/app-name.js";
+import { getRequestOrgId } from "../../server/request-context.js";
+import { authorizeTransactionalEmailRead } from "../authorize.js";
+import { listEmailLog } from "../log.js";
+export default defineAction({
+    description: "List recent transactional email sends from this app, newest first, optionally filtered to one registered email id.",
+    schema: z.object({
+        templateId: z.string().optional(),
+        limit: z.coerce.number().int().min(1).max(500).default(100),
+    }),
+    http: { method: "GET" },
+    authorize: ({ templateId }) => authorizeTransactionalEmailRead(templateId ? [templateId] : []),
+    run: async ({ templateId, limit }) => ({
+        entries: await listEmailLog({
+            orgId: getRequestOrgId() ?? "",
+            app: getAppSlug() ?? "unknown",
+            templateId,
+            limit,
+        }),
+    }),
+});

package/dist/email-catalog/actions/list-transactional-emails.d.ts

@@ -0,0 +1,22 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    windowDays?: unknown;
+}, {
+    app: string;
+    windowDays: number;
+    statsAvailable: boolean;
+    statsError: string;
+    emails: {
+        id: string;
+        app: string;
+        name: string;
+        trigger: string;
+        recipient: string;
+        recipientLabel: string;
+        sender: string;
+        senderLabel: string;
+        sent: number;
+        failed: number;
+        lastSentAt: number;
+    }[];
+}>;
+export default _default;

package/dist/email-catalog/actions/list-transactional-emails.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getAppSlug } from "../../server/app-name.js";
+import { getRequestOrgId } from "../../server/request-context.js";
+import { authorizeTransactionalEmailRead } from "../authorize.js";
+import { getEmailSendStats } from "../log.js";
+import { listTransactionalEmails } from "../registry.js";
+import { registerCoreSystemEmails } from "../system-emails.js";
+const DEFAULT_WINDOW_DAYS = 30;
+export default defineAction({
+    description: "List the transactional emails this app can send, with the trigger, recipient and sender logic for each, plus local send counts and last-sent. Engagement metrics such as open rate are not included here — they live at the email provider.",
+    schema: z.object({
+        windowDays: z.coerce
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .default(DEFAULT_WINDOW_DAYS)
+            .describe("How many days of send history to summarize."),
+    }),
+    http: { method: "GET" },
+    authorize: () => authorizeTransactionalEmailRead([]),
+    run: async ({ windowDays }) => {
+        registerCoreSystemEmails();
+        const since = Date.now() - windowDays * 24 * 60 * 60 * 1000;
+        const app = getAppSlug() ?? "unknown";
+        const orgId = getRequestOrgId();
+        const definitions = listTransactionalEmails();
+        // A failed stats read must not masquerade as "no email ever sent" — the
+        // catalog is still worth returning, but the caller has to be able to tell
+        // that the numbers are missing rather than zero.
+        let statsById = null;
+        let statsError = null;
+        try {
+            if (!orgId) {
+                throw new Error("Organization context is required for transactional email stats.");
+            }
+            const stats = await getEmailSendStats(since, app, orgId);
+            statsById = new Map(stats.map((row) => [row.templateId, row]));
+        }
+        catch (error) {
+            statsError = error instanceof Error ? error.message : String(error);
+        }
+        return {
+            app,
+            windowDays,
+            statsAvailable: statsError === null,
+            statsError,
+            emails: definitions.map((definition) => {
+                const stats = statsById?.get(definition.id);
+                return {
+                    id: definition.id,
+                    app: definition.app,
+                    name: definition.name,
+                    trigger: definition.trigger,
+                    recipient: definition.recipient,
+                    recipientLabel: definition.recipientLabel,
+                    sender: definition.sender,
+                    senderLabel: definition.senderLabel,
+                    sent: stats?.sent ?? (statsById ? 0 : null),
+                    failed: stats?.failed ?? (statsById ? 0 : null),
+                    lastSentAt: stats?.lastSentAt ?? null,
+                };
+            }),
+        };
+    },
+});

package/dist/email-catalog/actions/render-transactional-email-preview.d.ts

@@ -0,0 +1,9 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    id: string;
+}, {
+    id: string;
+    subject: string;
+    html: string;
+    text: string;
+}>;
+export default _default;

package/dist/email-catalog/actions/render-transactional-email-preview.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { authorizeTransactionalEmailRead } from "../authorize.js";
+import { renderTransactionalEmailPreview } from "../registry.js";
+import { registerCoreSystemEmails } from "../system-emails.js";
+export default defineAction({
+    description: "Render one of this app's transactional emails with representative dummy data, returning the subject, HTML and plain-text bodies for preview.",
+    schema: z.object({
+        id: z
+            .string()
+            .describe("Registered email id, e.g. calendar.booking-confirmed."),
+    }),
+    http: { method: "GET" },
+    authorize: ({ id }) => authorizeTransactionalEmailRead([id]),
+    run: async ({ id }) => {
+        registerCoreSystemEmails();
+        const rendered = renderTransactionalEmailPreview(id);
+        return {
+            id,
+            subject: rendered.subject,
+            html: rendered.html,
+            text: rendered.text,
+        };
+    },
+});

package/dist/email-catalog/authorize.d.ts

@@ -0,0 +1 @@
+export declare function authorizeTransactionalEmailRead(templateIds?: string[]): Promise<boolean>;

package/dist/email-catalog/authorize.js

@@ -0,0 +1,9 @@
+import { currentRequestUserIsOrgAdmin } from "../server/org-admin.js";
+import { getTransactionalEmail } from "./registry.js";
+import { registerCoreSystemEmails } from "./system-emails.js";
+export async function authorizeTransactionalEmailRead(templateIds = []) {
+    if (!(await currentRequestUserIsOrgAdmin()))
+        return false;
+    registerCoreSystemEmails();
+    return templateIds.every((id) => Boolean(getTransactionalEmail(id)));
+}

package/dist/email-catalog/log.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Durable send log for transactional emails.
+ *
+ * Written by `sendEmail` on every attempt, successful or not. Read by Dispatch
+ * to report per-email send counts and last-sent without depending on the
+ * provider's activity retention window.
+ */
+export interface RecordEmailSendArgs {
+    orgId?: string | null;
+    templateId?: string;
+    app?: string;
+    recipient: string;
+    sender: string;
+    subject: string;
+    status: "sent" | "failed";
+    error?: string;
+    provider: string;
+}
+/**
+ * Append one send record.
+ *
+ * Callers treat logging as best-effort: a logging failure must not turn a
+ * delivered email into a thrown send. The failure is surfaced on the console
+ * rather than swallowed, so a persistently broken log is visible instead of
+ * quietly producing an empty activity view.
+ */
+export declare function recordEmailSend(args: RecordEmailSendArgs): Promise<void>;
+export interface EmailSendStats {
+    templateId: string;
+    sent: number;
+    failed: number;
+    lastSentAt: number | null;
+}
+/**
+ * Per-template send counts and last-sent, for sends at or after `since`.
+ * Templates with no rows are absent from the result — callers distinguish
+ * "never sent" from "sent zero times in window" by that absence.
+ */
+export declare function getEmailSendStats(since: number, app: string, orgId: string): Promise<EmailSendStats[]>;
+export interface EmailLogEntry {
+    id: string;
+    templateId: string | null;
+    app: string | null;
+    recipient: string;
+    sender: string;
+    subject: string;
+    status: string;
+    error: string | null;
+    provider: string;
+    createdAt: number;
+}
+/** Most recent sends for one app, newest first, optionally filtered to one template. */
+export declare function listEmailLog(options: {
+    orgId: string;
+    app: string;
+    templateId?: string;
+    limit?: number;
+}): Promise<EmailLogEntry[]>;
+/** Provider category that is safe to query for one organization only. */
+export declare function getScopedEmailProviderCategory(templateId: string, orgId: string): string;