@agent-native/core 0.144.3 → 0.145.1

package/dist/agent/run-manager.js

@@ -197,16 +197,69 @@ export const SQL_SUBSCRIPTION_IDLE_POLL_MS = 500;
 export const SQL_SUBSCRIPTION_ACTIVE_GRACE_MS = 2_000;
 /** Keep terminal/status probes at the historical cadence to bound DB work. */
 export const SQL_SUBSCRIPTION_STATUS_POLL_MS = 500;
+/**
+ * Consecutive empty polls before the IDLE cadence starts decaying toward
+ * `SQL_SUBSCRIPTION_IDLE_MAX_POLL_MS`.
+ *
+ * The active grace already covers a streaming producer, so decay only ever
+ * applies to a subscriber watching a run that is producing nothing: a long tool
+ * call, a slow first token, or a wedged producer. Those cost one poll per
+ * 500ms each, forever, per subscriber — the single largest source of idle
+ * `agent_run_events` reads.
+ */
+export const SQL_SUBSCRIPTION_IDLE_DECAY_AFTER_POLLS = 4;
+/**
+ * Ceiling for the decayed idle cadence. Bounds the WORST-CASE added latency to
+ * the next token a quiet run eventually produces; a row already waiting when the
+ * timer fires is delivered immediately, so this is not added to a streaming run.
+ */
+export const SQL_SUBSCRIPTION_IDLE_MAX_POLL_MS = 2_000;
+/**
+ * Cadence for the opportunistic `reapIfStale` probe inside the SSE poll loop,
+ * kept SEPARATE from (and much slower than) the status probe next to it.
+ *
+ * A reap can only ever act on a run whose liveness basis is older than the
+ * tightest staleness window any sweep enforces — `RUN_STALE_MS`, 15s — so
+ * running it on the 500ms status cadence issued ~30 rounds of
+ * `reconcileTerminalRunFromEvents` + reap-eligibility queries (2-4 round trips
+ * each) before the first one could possibly match a row. This cadence still
+ * detects a stale producer well inside the client's own idle timeout while
+ * cutting that probe traffic ~10x. `getRunById` deliberately stays on the fast
+ * status cadence: it is one indexed read and it is what closes the stream on a
+ * NORMAL finish, which must stay prompt.
+ */
+export const SQL_SUBSCRIPTION_REAP_POLL_MS = 5_000;
 /** Initial retry delay after a transient cross-isolate SQL polling failure. */
 export const SQL_SUBSCRIPTION_RETRY_BASE_MS = 250;
 /** Bound consecutive SQL polling failures so a dead subscription fails loud. */
 export const SQL_SUBSCRIPTION_MAX_CONSECUTIVE_FAILURES = 4;
 /** Cap retry delay even if the failure bound changes independently. */
 export const SQL_SUBSCRIPTION_RETRY_MAX_MS = 2_000;
-export function resolveSqlSubscriptionPollMs(now, activePollUntil) {
-    return now < activePollUntil
-        ? SQL_SUBSCRIPTION_ACTIVE_POLL_MS
-        : SQL_SUBSCRIPTION_IDLE_POLL_MS;
+export function resolveSqlSubscriptionPollMs(now, activePollUntil, consecutiveEmptyPolls = 0) {
+    if (now < activePollUntil)
+        return SQL_SUBSCRIPTION_ACTIVE_POLL_MS;
+    // Clamped before exponentiation: an unbounded `2 ** steps` reaches Infinity
+    // and would make the cap the only thing keeping this finite.
+    const steps = Math.min(16, Math.max(0, Math.floor(consecutiveEmptyPolls) -
+        SQL_SUBSCRIPTION_IDLE_DECAY_AFTER_POLLS));
+    return Math.min(SQL_SUBSCRIPTION_IDLE_MAX_POLL_MS, SQL_SUBSCRIPTION_IDLE_POLL_MS * 2 ** steps);
+}
+/**
+ * Advance the empty-poll counter that drives `resolveSqlSubscriptionPollMs`'s
+ * decay.
+ *
+ * Only IDLE polls count. Counting the ~16 fast polls inside the active grace
+ * window would push the ladder to its cap the instant the grace expired, so a
+ * producer that pauses a few seconds between tokens would resume at the 2s cap
+ * instead of 500ms — a visible mid-stream stutter rather than the intended
+ * "this run has gone quiet" backoff.
+ */
+export function nextSqlSubscriptionEmptyPolls(current, hadEvents, now, activePollUntil) {
+    if (hadEvents)
+        return 0;
+    if (now < activePollUntil)
+        return current;
+    return current + 1;
 }
 export function resolveSqlSubscriptionRetryMs(consecutiveFailures) {
     const retryIndex = Math.max(0, Math.floor(consecutiveFailures) - 1);
@@ -1323,7 +1376,9 @@ function subscribeFromSQL(runId, fromSeq) {
             let lastSeq = fromSeq;
             let activePollUntil = 0;
             let lastStatusCheckAt = 0;
+            let lastReapCheckAt = 0;
             let consecutivePollFailures = 0;
+            let consecutiveEmptyPolls = 0;
             const ping = () => {
                 try {
                     controller.enqueue(encoder.encode(`: ping ${Date.now()}\n\n`));
@@ -1382,6 +1437,7 @@ function subscribeFromSQL(runId, fromSeq) {
                 try {
                     // Read new events from SQL
                     const events = await getRunEventsSince(runId, lastSeq);
+                    consecutiveEmptyPolls = nextSqlSubscriptionEmptyPolls(consecutiveEmptyPolls, events.length > 0, Date.now(), activePollUntil);
                     if (events.length > 0) {
                         activePollUntil = Date.now() + SQL_SUBSCRIPTION_ACTIVE_GRACE_MS;
                     }
@@ -1419,7 +1475,7 @@ function subscribeFromSQL(runId, fromSeq) {
                         if (now - lastStatusCheckAt < SQL_SUBSCRIPTION_STATUS_POLL_MS) {
                             if (!cancelled) {
                                 consecutivePollFailures = 0;
-                                const pollMs = resolveSqlSubscriptionPollMs(now, activePollUntil);
+                                const pollMs = resolveSqlSubscriptionPollMs(now, activePollUntil, consecutiveEmptyPolls);
                                 pollTimer = setTimeout(poll, pollMs);
                             }
                             return;
@@ -1427,8 +1483,14 @@ function subscribeFromSQL(runId, fromSeq) {
                         lastStatusCheckAt = now;
                         // Opportunistically reap a stale producer before trusting SQL's
                         // "running" status — otherwise a crashed server leaves us polling
-                        // forever.
-                        await reapIfStale(runId).catch(() => { });
+                        // forever. Throttled independently of the status probe below: a reap
+                        // cannot match a row younger than RUN_STALE_MS, so running it at the
+                        // status cadence was ~30 rounds of wasted round trips per run before
+                        // the first one could do anything. See SQL_SUBSCRIPTION_REAP_POLL_MS.
+                        if (now - lastReapCheckAt >= SQL_SUBSCRIPTION_REAP_POLL_MS) {
+                            lastReapCheckAt = now;
+                            await reapIfStale(runId).catch(() => { });
+                        }
                         const run = await getRunById(runId);
                         if (!run || run.status !== "running") {
                             // Run ended — do one final event read, then close
@@ -1543,7 +1605,7 @@ function subscribeFromSQL(runId, fromSeq) {
                     // Schedule next poll
                     if (!cancelled) {
                         consecutivePollFailures = 0;
-                        const pollMs = resolveSqlSubscriptionPollMs(Date.now(), activePollUntil);
+                        const pollMs = resolveSqlSubscriptionPollMs(Date.now(), activePollUntil, consecutiveEmptyPolls);
                         pollTimer = setTimeout(poll, pollMs);
                     }
                 }

package/dist/chat-threads/store.js

@@ -429,10 +429,12 @@ export async function ensureChatThreadTables() {
 export async function resolveThreadAccess(userEmail, threadId, minRole = "viewer", ctx = {}) {
     if (!userEmail || !threadId)
         return null;
-    const access = await resolveAccess("chat_thread", threadId, {
-        userEmail,
-        orgId: ctx.orgId,
-    });
+    // `skipResourceBody` matters more here than anywhere else: without it the
+    // access load is an unprojected `select()` that pulls `thread_data` — the
+    // whole conversation JSON — and then this function discards the row and reads
+    // it again through `getThread`. Two full-blob reads of the same row per call,
+    // on the agent-chat hot path.
+    const access = await resolveAccess("chat_thread", threadId, { userEmail, orgId: ctx.orgId }, { skipResourceBody: true });
     if (!access || !roleSatisfies(access.role, minRole))
         return null;
     return await getThread(threadId);

package/dist/client/use-db-sync.js

@@ -1216,7 +1216,15 @@ export function useDbSync(options = {}) {
                         // the independent framework prefixes, while pure action batches
                         // retain their narrow storm-resistant invalidation.
                         if (!hasActionEvent) {
-                            invalidateWithoutCancel({ queryKey: ["action"] });
+                            // Honour the app's predicate here too. Without it the contract was
+                            // silently conditional: a batch carrying an `action` event
+                            // respected the predicate (above), while a batch carrying only
+                            // `db`/`collab`/`settings`/`screen-refresh` blew away every
+                            // ["action"] query regardless of what the app opted out of — and
+                            // an app cannot work around it, because both the prefix and this
+                            // call are framework-owned.
+                            const predicate = actionInvalidatePredicateRef.current;
+                            invalidateWithoutCancel(predicate ? { predicate } : { queryKey: ["action"] });
                         }
                         if (!hasActionEvent || hasFrameworkPrefixEvent) {
                             invalidateWithoutCancel({ queryKey: ["extension"] });

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/db/ddl-guard.d.ts

@@ -29,6 +29,14 @@
  * behaviour there.
  */
 import { type DbExec } from "./client.js";
+/**
+ * Drop the cached picture after any successful DDL, so a freshly created object
+ * is visible to the next probe rather than reported absent for the life of the
+ * process.
+ */
+export declare function invalidateSchemaSnapshot(injectedClient?: DbExec): void;
+/** Test seam — the snapshots are module state, so suites must clear them. */
+export declare function __resetSchemaSnapshotForTests(): void;
 /**
  * True when running against Postgres AND the given table already exists in the
  * `public` schema. Returns `false` on SQLite (callers gate their own behaviour

package/dist/db/ddl-guard.js

@@ -30,6 +30,135 @@
  */
 import { isPostgres, getDbExec } from "./client.js";
 const PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Skip on-demand schema DDL entirely. For deployments that run real migrations,
+ * where the probe → DDL machinery below is pure cold-start latency.
+ *
+ * Implemented at the PROBE layer, not per store: every `ensureTable()` in the
+ * codebase reaches the database through these three helpers, and there are ~390
+ * call sites across ~57 stores. Reporting "present" here makes
+ * `ensureSchemaObject` a no-op without touching any of them.
+ *
+ * This does not fail closed, and cannot: the only honest signal that schema is
+ * missing is the real query failing, which it will, loudly, at the first read.
+ * Silently reporting "absent" instead would be worse — it would send every store
+ * down the DDL path this flag exists to avoid.
+ */
+function schemaEnsureDisabled() {
+    const raw = process.env.AGENT_NATIVE_SKIP_ENSURE_TABLES?.trim();
+    return !!raw && ["1", "true", "yes", "on"].includes(raw.toLowerCase());
+}
+const injectedSnapshots = new WeakMap();
+let globalSnapshot;
+/**
+ * Drop the cached picture after any successful DDL, so a freshly created object
+ * is visible to the next probe rather than reported absent for the life of the
+ * process.
+ */
+export function invalidateSchemaSnapshot(injectedClient) {
+    // The global snapshot always goes: a store may create an object through an
+    // injected client and later probe through the global one (or the reverse), so
+    // after DDL neither picture is trustworthy and both are cheap to rebuild.
+    globalSnapshot = undefined;
+    if (injectedClient)
+        injectedSnapshots.delete(injectedClient);
+}
+/** Test seam — the snapshots are module state, so suites must clear them. */
+export function __resetSchemaSnapshotForTests() {
+    globalSnapshot = undefined;
+}
+async function loadSchemaSnapshot(client) {
+    try {
+        const [columnRows, indexRows] = await Promise.all([
+            client.execute(`SELECT table_name, column_name FROM information_schema.columns WHERE table_schema = 'public'`),
+            client.execute(`SELECT indexname FROM pg_indexes WHERE schemaname = 'public'`),
+        ]);
+        // An EMPTY result is a valid snapshot (a fresh database really has nothing
+        // in `public`). A result whose rows lack the columns we asked for is not —
+        // it means something other than Postgres answered, and treating it as "these
+        // are the objects that exist" would report every table absent and send every
+        // store down the DDL path. Fall back to per-object probes instead.
+        const columnData = columnRows.rows;
+        const indexData = indexRows.rows;
+        if (columnData.length > 0 && !("table_name" in columnData[0]))
+            return null;
+        if (indexData.length > 0 && !("indexname" in indexData[0]))
+            return null;
+        const tables = new Set();
+        const columns = new Set();
+        for (const row of columnData) {
+            const table = String(row.table_name ?? "").toLowerCase();
+            const column = String(row.column_name ?? "").toLowerCase();
+            if (!table)
+                continue;
+            tables.add(table);
+            if (column)
+                columns.add(`${table}.${column}`);
+        }
+        const indexes = new Set();
+        for (const row of indexData) {
+            const name = String(row.indexname ?? "").toLowerCase();
+            if (name)
+                indexes.add(name);
+        }
+        return { tables, columns, indexes };
+    }
+    catch (err) {
+        // `information_schema` unreadable (permissions / non-standard backend).
+        // `null` is a typed "no snapshot" the caller tells apart from an empty one:
+        // each probe falls back to its original per-object query. It does NOT mean
+        // "the schema is empty", which would make every store issue DDL it does not
+        // need. Say so once — the fallback is correct but costs a few hundred round
+        // trips per cold start, which is invisible otherwise.
+        warnIntrospectionUnavailableOnce(err);
+        return null;
+    }
+}
+let _warnedIntrospectionUnavailable = false;
+function warnIntrospectionUnavailableOnce(err) {
+    if (_warnedIntrospectionUnavailable)
+        return;
+    _warnedIntrospectionUnavailable = true;
+    console.warn("[db] batched schema introspection unavailable; falling back to one probe " +
+        "per table/column/index (slower cold starts, same behaviour): " +
+        (err?.message ?? err));
+}
+// `loadSchemaSnapshot` resolves to `null` on failure rather than rejecting, so
+// these need no `.catch()` — adding one would be dead code hiding that contract.
+function schemaSnapshot(client, injected) {
+    if (injected) {
+        let pending = injectedSnapshots.get(client);
+        if (!pending) {
+            pending = loadSchemaSnapshot(client);
+            injectedSnapshots.set(client, pending);
+        }
+        return pending;
+    }
+    if (!globalSnapshot) {
+        globalSnapshot = loadSchemaSnapshot(client);
+    }
+    return globalSnapshot;
+}
+/**
+ * `true`/`false` from the cached picture, or `undefined` when there is no usable
+ * snapshot and the caller must fall back to its own single-object probe.
+ *
+ * A snapshot MISS is authoritative: the snapshot lists every object in `public`,
+ * so "not in the set" means the object really is absent and the caller should
+ * proceed to DDL. That is what makes this a replacement for the per-object
+ * probe rather than a layer in front of it.
+ */
+async function snapshotHas(kind, key, client, injected) {
+    const snapshot = await schemaSnapshot(client, injected);
+    if (!snapshot)
+        return undefined;
+    const set = kind === "table"
+        ? snapshot.tables
+        : kind === "column"
+            ? snapshot.columns
+            : snapshot.indexes;
+    return set.has(key.toLowerCase());
+}
 /**
  * True when running against Postgres AND the given table already exists in the
  * `public` schema. Returns `false` on SQLite (callers gate their own behaviour
@@ -47,7 +176,12 @@ export async function pgTableExists(table, injectedClient, dialectIsPostgres) {
     if (!(dialectIsPostgres ?? isPostgres()) || !PLAIN_IDENTIFIER.test(table)) {
         return false;
     }
+    if (schemaEnsureDisabled())
+        return true;
     const client = injectedClient ?? getDbExec();
+    const cached = await snapshotHas("table", table, client, !!injectedClient);
+    if (cached !== undefined)
+        return cached;
     try {
         const { rows } = await client.execute({
             sql: `SELECT 1 FROM information_schema.tables
@@ -77,7 +211,12 @@ export async function pgColumnExists(table, column, injectedClient) {
     if (!PLAIN_IDENTIFIER.test(table) || !PLAIN_IDENTIFIER.test(column)) {
         return false;
     }
+    if (schemaEnsureDisabled())
+        return true;
     const client = injectedClient ?? getDbExec();
+    const cached = await snapshotHas("column", `${table}.${column}`, client, !!injectedClient);
+    if (cached !== undefined)
+        return cached;
     try {
         const { rows } = await client.execute({
             sql: `SELECT 1 FROM information_schema.columns
@@ -108,7 +247,12 @@ export async function pgIndexExists(indexName, injectedClient, dialectIsPostgres
         !PLAIN_IDENTIFIER.test(indexName)) {
         return false;
     }
+    if (schemaEnsureDisabled())
+        return true;
     const client = injectedClient ?? getDbExec();
+    const cached = await snapshotHas("index", indexName, client, !!injectedClient);
+    if (cached !== undefined)
+        return cached;
     try {
         const { rows } = await client.execute({
             sql: `SELECT 1 FROM pg_indexes
@@ -162,6 +306,10 @@ export async function ensureSchemaObject(options) {
         injectedClient,
         dialectIsPostgres,
     });
+    // The cached picture predates this object. Drop it before anyone probes again,
+    // or a sibling `ensureTable` in the same boot is told the object it just
+    // created does not exist.
+    invalidateSchemaSnapshot(injectedClient);
     if (ran)
         return true;
     // The DDL was swallowed by a lock-timeout. The object is virtually always

package/dist/deploy/build.d.ts

@@ -94,11 +94,47 @@ export declare const NETLIFY_INTEGRATION_RECOVERY_FUNCTION_NAME = "server-integr
 export declare function isIntegrationDurableDispatchDeployEnabled(): boolean;
 export declare const NETLIFY_RECURRING_JOBS_FUNCTION_NAME = "agent-native-recurring-jobs";
 export declare function isRecurringJobsDeployEnabled(): boolean;
+/**
+ * Keep-warm is ON by default, and on a provisioned database that is the right
+ * default. It is the wrong default on a metered scale-to-zero tier: a
+ * once-a-minute wake means autosuspend NEVER fires, so the endpoint bills (and
+ * quota-limits) as if it were awake 100% of the time with zero users online. On
+ * a free-tier Neon that exhausts the compute quota and the database then
+ * hard-blocks every read mid-session — the symptom is a dead app, not a slow one.
+ */
+export declare function isKeepWarmDeployEnabled(): boolean;
+/**
+ * The background warm is a separate, much more expensive knob than the server
+ * warm and gets its own switch. Warming `server` is one health request; warming
+ * the `-background` Lambda is a *fresh container*, so every ping pays the full
+ * on-demand `ensureTable()` schema-probe fan-out (hundreds of
+ * `information_schema` round trips) before it does anything. At the default
+ * cadence that is ~1,440 manufactured cold starts a day that no user asked for.
+ * Turn this off to keep dispatch-latency protection for the server function
+ * while dropping the probe storm.
+ */
+export declare function isKeepWarmBackgroundDeployEnabled(): boolean;
+/**
+ * Cadence for the keep-warm schedule, overridable with
+ * `AGENT_NATIVE_KEEP_WARM_SCHEDULE` (standard 5-field cron).
+ *
+ * An unparseable value THROWS rather than falling back to the default. Falling
+ * back would leave an operator who set this specifically to stop burning
+ * database quota still burning it at the original once-a-minute cadence, with a
+ * successful build and nothing in the log to say the value was ignored.
+ */
+export declare function resolveKeepWarmSchedule(): string;
 /**
  * Emit a site-local Netlify Scheduled Function that wakes the public server
  * function and its database every minute. GitHub Actions schedules can be
  * delayed by tens of minutes, which is longer than a scale-to-zero database's
  * autosuspend window and leaves the next visitor to pay the cold-start cost.
+ *
+ * Both halves are opt-out and the cadence is configurable — see
+ * `isKeepWarmDeployEnabled`, `isKeepWarmBackgroundDeployEnabled`, and
+ * `resolveKeepWarmSchedule`. The tradeoff this function encodes is next-visitor
+ * latency against database awake-time, and only the deployment knows which of
+ * those it is paying for.
  */
 export declare function emitSingleTemplateNetlifyKeepWarmFunction(projectCwd: string): void;
 /**

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 { isValidCron } from "../jobs/cron.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";
@@ -2196,17 +2197,85 @@ export function isIntegrationDurableDispatchDeployEnabled() {
 }
 const NETLIFY_KEEP_WARM_FUNCTION_NAME = "agent-native-keep-warm";
 export const NETLIFY_RECURRING_JOBS_FUNCTION_NAME = "agent-native-recurring-jobs";
+/** Shared shape for the `AGENT_NATIVE_DISABLE_*` build kill switches. */
+function isDisabledByEnv(name) {
+    const value = process.env[name]?.trim();
+    return !!value && ["1", "true", "yes", "on"].includes(value.toLowerCase());
+}
 export function isRecurringJobsDeployEnabled() {
-    const value = process.env.AGENT_NATIVE_DISABLE_RECURRING_JOBS?.trim();
-    return !value || !["1", "true", "yes", "on"].includes(value.toLowerCase());
+    return !isDisabledByEnv("AGENT_NATIVE_DISABLE_RECURRING_JOBS");
+}
+/**
+ * Keep-warm is ON by default, and on a provisioned database that is the right
+ * default. It is the wrong default on a metered scale-to-zero tier: a
+ * once-a-minute wake means autosuspend NEVER fires, so the endpoint bills (and
+ * quota-limits) as if it were awake 100% of the time with zero users online. On
+ * a free-tier Neon that exhausts the compute quota and the database then
+ * hard-blocks every read mid-session — the symptom is a dead app, not a slow one.
+ */
+export function isKeepWarmDeployEnabled() {
+    return !isDisabledByEnv("AGENT_NATIVE_DISABLE_KEEP_WARM");
+}
+/**
+ * The background warm is a separate, much more expensive knob than the server
+ * warm and gets its own switch. Warming `server` is one health request; warming
+ * the `-background` Lambda is a *fresh container*, so every ping pays the full
+ * on-demand `ensureTable()` schema-probe fan-out (hundreds of
+ * `information_schema` round trips) before it does anything. At the default
+ * cadence that is ~1,440 manufactured cold starts a day that no user asked for.
+ * Turn this off to keep dispatch-latency protection for the server function
+ * while dropping the probe storm.
+ */
+export function isKeepWarmBackgroundDeployEnabled() {
+    return !isDisabledByEnv("AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND");
+}
+const DEFAULT_KEEP_WARM_SCHEDULE = "* * * * *";
+/**
+ * Cadence for the keep-warm schedule, overridable with
+ * `AGENT_NATIVE_KEEP_WARM_SCHEDULE` (standard 5-field cron).
+ *
+ * An unparseable value THROWS rather than falling back to the default. Falling
+ * back would leave an operator who set this specifically to stop burning
+ * database quota still burning it at the original once-a-minute cadence, with a
+ * successful build and nothing in the log to say the value was ignored.
+ */
+export function resolveKeepWarmSchedule() {
+    const raw = process.env.AGENT_NATIVE_KEEP_WARM_SCHEDULE?.trim();
+    if (!raw)
+        return DEFAULT_KEEP_WARM_SCHEDULE;
+    const fields = raw.split(/\s+/);
+    // The field count is checked separately from the field values because
+    // `isValidCron` also accepts 6-field (seconds) and `@daily` forms that
+    // Netlify's scheduler does not; "5 fields" is the narrower contract.
+    if (fields.length !== 5 || !isValidCron(raw)) {
+        throw new Error(`AGENT_NATIVE_KEEP_WARM_SCHEDULE must be a 5-field cron expression ` +
+            `(minute hour day month weekday); got "${raw}" (${fields.length} field(s)). ` +
+            `Example: "*/5 * * * *" for every five minutes.`);
+    }
+    return raw;
 }
 /**
  * Emit a site-local Netlify Scheduled Function that wakes the public server
  * function and its database every minute. GitHub Actions schedules can be
  * delayed by tens of minutes, which is longer than a scale-to-zero database's
  * autosuspend window and leaves the next visitor to pay the cold-start cost.
+ *
+ * Both halves are opt-out and the cadence is configurable — see
+ * `isKeepWarmDeployEnabled`, `isKeepWarmBackgroundDeployEnabled`, and
+ * `resolveKeepWarmSchedule`. The tradeoff this function encodes is next-visitor
+ * latency against database awake-time, and only the deployment knows which of
+ * those it is paying for.
  */
 export function emitSingleTemplateNetlifyKeepWarmFunction(projectCwd) {
+    if (!isKeepWarmDeployEnabled()) {
+        console.log("[build] Keep-warm emit skipped: AGENT_NATIVE_DISABLE_KEEP_WARM is set. " +
+            "The database is free to autosuspend; the next visitor after an idle " +
+            "period pays its cold start.");
+        return;
+    }
+    // Resolved before anything is removed or written, so a bad cron fails the
+    // build rather than leaving a wiped/half-emitted function directory behind.
+    const keepWarmSchedule = resolveKeepWarmSchedule();
     const internalDir = path.join(projectCwd, ".netlify", "functions-internal");
     const serverBundle = path.join(internalDir, "server", "main.mjs");
     if (!fs.existsSync(serverBundle)) {
@@ -2223,7 +2292,9 @@ export function emitSingleTemplateNetlifyKeepWarmFunction(projectCwd) {
     // rejected by the `_process-run` route before any DB work, so this only keeps
     // the container alive.
     const backgroundEntryPath = path.join(internalDir, AGENT_BACKGROUND_FUNCTION_NAME, `${AGENT_BACKGROUND_FUNCTION_NAME}.mjs`);
-    const backgroundWarmPath = isDurableBackgroundEmitRequired() && fs.existsSync(backgroundEntryPath)
+    const backgroundWarmPath = isKeepWarmBackgroundDeployEnabled() &&
+        isDurableBackgroundEmitRequired() &&
+        fs.existsSync(backgroundEntryPath)
         ? JSON.stringify(AGENT_BACKGROUND_FUNCTION_URL_PATH)
         : "null";
     const entry = `const HEALTH_PATH = "/_agent-native/health";
@@ -2288,12 +2359,14 @@ export default async function handler(request) {
 export const config = {
   name: "agent-native server keep warm",
   generator: "agent-native build",
-  schedule: "* * * * *",
+  schedule: ${JSON.stringify(keepWarmSchedule)},
   nodeBundler: "none",
 };
 `;
     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}".`);
+    console.log(`[build] Emitted Netlify scheduled keep-warm function ` +
+        `"${NETLIFY_KEEP_WARM_FUNCTION_NAME}" (schedule "${keepWarmSchedule}", ` +
+        `background warm ${backgroundWarmPath === "null" ? "off" : "on"}).`);
 }
 /**
  * Emit the durable recurring-job trigger. Netlify's scheduled function only