@agent-native/core 0.145.0 → 0.145.2

package/dist/server/core-routes-plugin.js

@@ -57,6 +57,7 @@ import { createPollHandler } from "./poll.js";
 import { createRealtimeTokenHandler } from "./realtime-token.js";
 import { getRequestContext, hasRequestContext, runWithRequestContext, } from "./request-context.js";
 import { findUnsupportedScopedKeyNames, saveKeyValuesToScopedSecrets, ScopedKeyStorageError, } from "./scoped-key-storage.js";
+import { shouldDisableInProcessSweeps } from "./sweep-runtime.js";
 import { createTranscribeVoiceHandler } from "./transcribe-voice.js";
 import { createVoiceProvidersStatusHandler } from "./voice-providers-status.js";
 import { createWorkspaceProviderOAuthHandler } from "./workspace-provider-oauth.js";
@@ -1260,6 +1261,8 @@ export function createCoreRoutesPlugin(options = {}) {
             // poll-time drain in run-code covers deployments where warm-instance
             // timers rarely fire.
             (() => {
+                if (shouldDisableInProcessSweeps())
+                    return;
                 let lastSweep = 0;
                 const SWEEP_INTERVAL_MS = 2 * 60 * 1000;
                 setTimeout(() => {

package/dist/server/index.d.ts

@@ -14,7 +14,7 @@ export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } fro
 export { verifyCaptcha, type CaptchaVerifyResult } from "./captcha.js";
 export { getLocaleInitScript, parseAcceptLanguage, resolveLocaleFromRequest, type LocaleInitScriptOptions, type ResolveLocaleFromRequestOptions, type ResolvedRequestLocale, } from "../localization/server.js";
 export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "../agent/index.js";
-export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, runAgentLoop, type AgentToolCallExecutionResult, type ExecuteAgentToolCallOptions, } from "../agent/production-agent.js";
+export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, getOwnerApiKeyForEngine, resolveOwnerEngineApiKey, runAgentLoop, type AgentToolCallExecutionResult, type ExecuteAgentToolCallOptions, type ResolvedOwnerApiKey, } from "../agent/production-agent.js";
 export { mountRealtimeVoiceRoutes, realtimeVoiceSafetyIdentifier, REALTIME_VOICE_MAX_SDP_BYTES, REALTIME_VOICE_MAX_TOOL_BODY_BYTES, REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS, REALTIME_VOICE_SESSION_PATH, REALTIME_VOICE_TOOL_PATH, type MountRealtimeVoiceRoutesOptions, type RealtimeVoiceRequestContext, type RealtimeVoiceToolExecutionRequest, type RealtimeVoiceToolExecutionResult, } from "./realtime-voice.js";
 export { getStoredModelForEngine, resolveEngine, } from "../agent/engine/index.js";
 export { completeText, type CompleteTextMessage, type CompleteTextOptions, type CompleteTextResult, type CompleteTextUsage, } from "./complete-text.js";

package/dist/server/index.js

@@ -14,7 +14,7 @@ export { assertCurrentRequestUserIsOrgAdmin, currentRequestUserIsOrgAdmin, } fro
 export { verifyCaptcha } from "./captcha.js";
 export { getLocaleInitScript, parseAcceptLanguage, resolveLocaleFromRequest, } from "../localization/server.js";
 export { createProductionAgentHandler, } from "../agent/index.js";
-export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, runAgentLoop, } from "../agent/production-agent.js";
+export { actionsToEngineTools, executeAgentToolCall, getOwnerActiveApiKey, getOwnerApiKeyForEngine, resolveOwnerEngineApiKey, runAgentLoop, } from "../agent/production-agent.js";
 export { mountRealtimeVoiceRoutes, realtimeVoiceSafetyIdentifier, REALTIME_VOICE_MAX_SDP_BYTES, REALTIME_VOICE_MAX_TOOL_BODY_BYTES, REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS, REALTIME_VOICE_SESSION_PATH, REALTIME_VOICE_TOOL_PATH, } from "./realtime-voice.js";
 export { getStoredModelForEngine, resolveEngine, } from "../agent/engine/index.js";
 export { completeText, } from "./complete-text.js";

package/dist/server/request-context.d.ts

@@ -41,8 +41,14 @@ export interface RequestRunContext {
     } | null;
     /** Resolved owner email (set by prepareRun). */
     owner?: string;
-    /** Owner's active Anthropic API key (set by prepareRun). */
+    /** Owner's API key for this run's engine (set by prepareRun). */
     userApiKey?: string;
+    /**
+     * Env var `userApiKey` was issued for. Anything that hands the key to a
+     * fixed provider must check this first — the owner's active engine is not
+     * always Anthropic, and an unchecked key reaches the wrong endpoint.
+     */
+    userApiKeyEnvVar?: string;
     /** Thread ID for the current run (set by onRunStart). */
     threadId?: string;
     /** Run ID for the current run (set by onRunStart). */

package/dist/server/session-email-cache.d.ts

@@ -0,0 +1,14 @@
+export declare function getCachedSessionEmail(token: string): string | undefined;
+export declare function setCachedSessionEmail(token: string, email: string): void;
+export declare function forgetCachedSessionEmail(token: string): void;
+/**
+ * Drop cached session resolutions. Call after ANY write to `sessions`.
+ *
+ * Clears every token rather than one: the bulk sign-out paths delete by email
+ * (`DELETE FROM sessions WHERE email = ?`) and do not know which tokens they
+ * removed, so a per-token eviction there would leave a signed-out session
+ * resolving for the rest of the TTL.
+ */
+export declare function invalidateSessionEmailCache(): void;
+/** Test seam — the cache is module state, so suites must be able to clear it. */
+export declare function __resetSessionEmailCacheForTests(): void;

package/dist/server/session-email-cache.js

@@ -0,0 +1,48 @@
+import { createTtlCache } from "../shared/ttl-cache.js";
+/**
+ * Cross-request cache for resolved legacy session tokens.
+ *
+ * A session token is immutable for its (30-day) lifetime, yet every
+ * authenticated request re-read it: production showed 494,848 of these for 3
+ * users, 1:1 with the request count. The TTL is far shorter than the session
+ * lifetime, so expiry is enforced at most `SESSION_EMAIL_TTL_MS` late — a 30-day
+ * boundary observed up to 15s late changes nothing.
+ *
+ * ONLY successful resolutions belong in here. A `null` — no such token, expired,
+ * revoked — must stay uncached so a sign-out or a token that has just been
+ * written is never answered from a stale negative, and so an auth failure can
+ * never be made sticky by a cache.
+ *
+ * Lives in its own module rather than in `auth.ts` because `auth.ts` imports
+ * `org/auth-policy.ts`, which also revokes sessions and so needs to invalidate
+ * this. Importing back into `auth.ts` from there would be a cycle.
+ */
+const SESSION_EMAIL_TTL_MS = 15_000;
+const sessionEmailCache = createTtlCache({
+    ttlMs: SESSION_EMAIL_TTL_MS,
+    maxEntries: 4_096,
+});
+export function getCachedSessionEmail(token) {
+    return sessionEmailCache.get(token);
+}
+export function setCachedSessionEmail(token, email) {
+    sessionEmailCache.set(token, email);
+}
+export function forgetCachedSessionEmail(token) {
+    sessionEmailCache.delete(token);
+}
+/**
+ * Drop cached session resolutions. Call after ANY write to `sessions`.
+ *
+ * Clears every token rather than one: the bulk sign-out paths delete by email
+ * (`DELETE FROM sessions WHERE email = ?`) and do not know which tokens they
+ * removed, so a per-token eviction there would leave a signed-out session
+ * resolving for the rest of the TTL.
+ */
+export function invalidateSessionEmailCache() {
+    sessionEmailCache.clear();
+}
+/** Test seam — the cache is module state, so suites must be able to clear it. */
+export function __resetSessionEmailCacheForTests() {
+    sessionEmailCache.clear();
+}

package/dist/server/sweep-runtime.d.ts

@@ -0,0 +1,22 @@
+type SweepRuntimeEnvKey = "AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS";
+type SweepRuntimeEnv = Partial<Record<SweepRuntimeEnvKey, string | undefined>>;
+/**
+ * Kill switch for the `setInterval` backstop sweeps.
+ *
+ * These timers are correct on a long-lived Node server: one process, one timer
+ * set, one query per tick. On a serverless host they are billed per WARM
+ * CONTAINER, not per deployment — every warm instance independently runs the
+ * whole timer set, so the sweep query rate scales with instance count, which no
+ * in-process backoff or `lastSweep` guard can observe. A production sample
+ * showed one 2-minute sweep issuing 237k queries, implying ~11 containers each
+ * ticking forever against a database that then never gets to autosuspend.
+ *
+ * Default OFF (sweeps run), because on every host where the timers are the only
+ * thing driving recovery, disabling them silently strands queued work. Turn this
+ * on ONLY where a durable platform scheduler already drives the same recovery —
+ * the shape `isNetlifyRecurringJobsRuntime` + the emitted scheduled sweep
+ * already implement for recurring jobs, and which these three sweeps should
+ * eventually adopt instead of needing this switch at all.
+ */
+export declare function shouldDisableInProcessSweeps(env?: SweepRuntimeEnv): boolean;
+export {};

package/dist/server/sweep-runtime.js

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// Gating for the in-process backstop sweep timers (automation redispatch,
+// agent-teams orphan reconciliation, durable sandbox executions).
+// ---------------------------------------------------------------------------
+function isTruthyEnv(value) {
+    return /^(1|true|yes|on)$/i.test(value?.trim() ?? "");
+}
+/**
+ * Kill switch for the `setInterval` backstop sweeps.
+ *
+ * These timers are correct on a long-lived Node server: one process, one timer
+ * set, one query per tick. On a serverless host they are billed per WARM
+ * CONTAINER, not per deployment — every warm instance independently runs the
+ * whole timer set, so the sweep query rate scales with instance count, which no
+ * in-process backoff or `lastSweep` guard can observe. A production sample
+ * showed one 2-minute sweep issuing 237k queries, implying ~11 containers each
+ * ticking forever against a database that then never gets to autosuspend.
+ *
+ * Default OFF (sweeps run), because on every host where the timers are the only
+ * thing driving recovery, disabling them silently strands queued work. Turn this
+ * on ONLY where a durable platform scheduler already drives the same recovery —
+ * the shape `isNetlifyRecurringJobsRuntime` + the emitted scheduled sweep
+ * already implement for recurring jobs, and which these three sweeps should
+ * eventually adopt instead of needing this switch at all.
+ */
+export function shouldDisableInProcessSweeps(env = process.env) {
+    return isTruthyEnv(env.AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS);
+}

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    error?: undefined;
     text: string;
+    error?: undefined;
 }>>;

package/dist/settings/store.js

@@ -25,6 +25,24 @@ function requestSettingsCache() {
     }
     return cache;
 }
+/**
+ * Per-request memo of the WHOLE settings table for `getAllSettings`.
+ *
+ * The single-key path above was already request-cached; the full-table read was
+ * not, and production showed 98,479 of them — an entire `SELECT key, value FROM
+ * settings` per call, several times per request via the MCP client routes and
+ * org settings.
+ *
+ * Holds raw JSON strings, like the single-key cache, so callers can't mutate a
+ * shared parsed object. Dropped by every write path, because a request that
+ * writes a setting and then re-reads all of them must see its own write.
+ */
+const _requestAllSettingsCache = new WeakMap();
+function invalidateRequestAllSettings() {
+    const ctx = getRequestContext();
+    if (ctx && typeof ctx === "object")
+        _requestAllSettingsCache.delete(ctx);
+}
 // Created lazily so this module can be evaluated in the browser dev graph
 // without a top-level `new EventEmitter()` tripping Vite's externalized
 // `node:events` stub. The emitter drives server-side SSE fan-out only.
@@ -152,6 +170,7 @@ export async function mutateSetting(key, updater, options) {
         if (result.rowsAffected === 0)
             continue;
         requestSettingsCache()?.set(key, nextRaw);
+        invalidateRequestAllSettings();
         settingsEmitter().emit("settings", {
             source: "settings",
             type: "change",
@@ -173,6 +192,7 @@ export async function putSetting(key, value, options) {
         args: [key, JSON.stringify(value), Date.now()],
     });
     requestSettingsCache()?.set(key, JSON.stringify(value));
+    invalidateRequestAllSettings();
     settingsEmitter().emit("settings", {
         source: "settings",
         type: "change",
@@ -189,6 +209,7 @@ export async function deleteSetting(key, options) {
         args: [key],
     });
     requestSettingsCache()?.set(key, null);
+    invalidateRequestAllSettings();
     if (result.rowsAffected > 0) {
         settingsEmitter().emit("settings", {
             source: "settings",
@@ -215,6 +236,7 @@ export async function deleteSettingsByPrefix(prefix, options) {
         args: [`${escaped}%`],
     });
     requestSettingsCache()?.clear();
+    invalidateRequestAllSettings();
     if (result.rowsAffected > 0) {
         settingsEmitter().emit("settings", {
             source: "settings",
@@ -226,13 +248,47 @@ export async function deleteSettingsByPrefix(prefix, options) {
     return result.rowsAffected;
 }
 export async function getAllSettings() {
-    await ensureTable();
-    const client = getDbExec();
-    const table = settingsTable();
-    const { rows } = await client.execute(`SELECT key, value FROM ${table}`);
+    const raw = await loadAllSettingsRaw();
     const result = {};
-    for (const row of rows) {
-        result[row.key] = JSON.parse(row.value);
-    }
+    for (const [key, value] of raw)
+        result[key] = JSON.parse(value);
     return result;
 }
+async function loadAllSettingsRaw() {
+    const ctx = getRequestContext();
+    const cached = ctx && typeof ctx === "object"
+        ? _requestAllSettingsCache.get(ctx)
+        : undefined;
+    if (cached)
+        return cached;
+    const load = (async () => {
+        await ensureTable();
+        const client = getDbExec();
+        const table = settingsTable();
+        const { rows } = await client.execute(`SELECT key, value FROM ${table}`);
+        const raw = new Map();
+        for (const row of rows)
+            raw.set(row.key, row.value);
+        // Seed the single-key cache so a `getSetting` after `getAllSettings` in the
+        // same request is free rather than another round trip. Only fills keys it
+        // does not already hold: a value written earlier in this request is already
+        // written through there and must win over this snapshot.
+        const perKey = requestSettingsCache();
+        if (perKey) {
+            for (const [key, value] of raw) {
+                if (!perKey.has(key))
+                    perKey.set(key, value);
+            }
+        }
+        return raw;
+    })();
+    if (ctx && typeof ctx === "object") {
+        // Evicted on failure so one transient error is not memoized as the answer
+        // for the rest of the request.
+        _requestAllSettingsCache.set(ctx, load.catch((err) => {
+            _requestAllSettingsCache.delete(ctx);
+            throw err;
+        }));
+    }
+    return load;
+}

package/dist/shared/ttl-cache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Bounded process-level TTL cache for answers that are expensive to re-fetch
+ * and safe to serve slightly stale.
+ *
+ * ## Which cache do I want?
+ *
+ * This repo has exactly two general caching patterns. Reach for an existing one
+ * rather than hand-rolling a third `Map` with timestamps in it:
+ *
+ * 1. **Request-scoped** — `WeakMap<RequestContext, Map<...>>`, freed with the
+ *    request. Use when repeated reads within ONE request must collapse but no
+ *    answer may outlive it. See `settings/store.ts` (`requestSettingsCache`),
+ *    `org/request-org-cache.ts`, `secrets/storage.ts`.
+ * 2. **Process-scoped with a TTL** — this module. Use when every request
+ *    re-reads the same value and staleness bounded by the TTL is acceptable.
+ *    Every consumer must also wire an invalidation path for the writes that
+ *    change the answer; the TTL is a backstop, not the correctness story.
+ *
+ * Two caches deliberately do NOT use this and should stay as they are, because
+ * flattening them into this shape would lose behavior they depend on:
+ *
+ * - `server/poll.ts`'s collab access cache — different TTL per outcome
+ *   (allow vs deny), a per-resource invalidation epoch, and in-flight request
+ *   dedup.
+ * - `demo/redact.ts` — a bidirectional memo (forward map plus a produced-value
+ *   reverse index) with refresh-on-read recency, needed for round-trip
+ *   stability.
+ *
+ * The per-request memos elsewhere in this codebase (`event.context` caches,
+ * `requestSettingsCache`) collapse repeated reads WITHIN one request. They do
+ * nothing for a value every request re-reads identically — a session token's
+ * email, an account's org memberships — which on a remote Postgres is a round
+ * trip per request per value, forever.
+ *
+ * ## Only cache successful reads
+ *
+ * Never `set` a value that stands for "I could not read this". A cached
+ * "unreadable" is indistinguishable from a cached "absent" to every later
+ * caller, which is exactly how a transient blip turns into a
+ * permanent-looking wrong answer. Leave failures on the uncached path so they
+ * stay loud and retryable.
+ *
+ * ## Bounded on purpose
+ *
+ * Keys here are user-supplied (session tokens, emails), so an unbounded map is
+ * a memory leak that grows with traffic. `maxEntries` evicts oldest-written
+ * first once the cap is reached.
+ */
+export interface TtlCache<V> {
+    get(key: string): V | undefined;
+    set(key: string, value: V): void;
+    delete(key: string): void;
+    clear(): void;
+    readonly size: number;
+}
+export declare function createTtlCache<V>(options: {
+    ttlMs: number;
+    maxEntries: number;
+}): TtlCache<V>;

package/dist/shared/ttl-cache.js

@@ -0,0 +1,43 @@
+export function createTtlCache(options) {
+    const { ttlMs, maxEntries } = options;
+    if (!(ttlMs > 0)) {
+        throw new Error(`createTtlCache: ttlMs must be positive, got ${ttlMs}`);
+    }
+    if (!(maxEntries > 0)) {
+        throw new Error(`createTtlCache: maxEntries must be positive, got ${maxEntries}`);
+    }
+    const entries = new Map();
+    return {
+        get(key) {
+            const hit = entries.get(key);
+            if (!hit)
+                return undefined;
+            if (hit.expiresAt <= Date.now()) {
+                entries.delete(key);
+                return undefined;
+            }
+            return hit.value;
+        },
+        set(key, value) {
+            // Delete before insert so Map insertion order tracks the newest write,
+            // which is what the eviction loop below reads as "oldest".
+            entries.delete(key);
+            entries.set(key, { value, expiresAt: Date.now() + ttlMs });
+            while (entries.size > maxEntries) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                entries.delete(oldest.value);
+            }
+        },
+        delete(key) {
+            entries.delete(key);
+        },
+        clear() {
+            entries.clear();
+        },
+        get size() {
+            return entries.size;
+        },
+    };
+}

package/dist/sharing/actions/list-resource-shares.d.ts

@@ -12,9 +12,9 @@ declare const _default: import("../../action.js").ActionDefinition<{
     orgId?: undefined;
     role?: undefined;
 } | {
-    ownerEmail: any;
-    orgId: any;
-    visibility: any;
+    ownerEmail: string;
+    orgId: string;
+    visibility: import("../schema.js").Visibility;
     role: "owner" | import("../schema.js").ShareRole;
     shares: any;
     policy: {

package/dist/sharing/actions/list-resource-shares.js

@@ -43,7 +43,10 @@ export default defineAction({
             allowPublic: reg.allowPublic !== false,
             requireOrgMemberForUserShares: reg.requireOrgMemberForUserShares === true,
         };
-        const access = await resolveAccess(args.resourceType, args.resourceId);
+        // Only `ownerEmail`/`orgId`/`visibility` are read below, all of which the
+        // projected load carries — so the share dialog never pulls a resource's
+        // body blob just to render who it is shared with.
+        const access = await resolveAccess(args.resourceType, args.resourceId, undefined, { skipResourceBody: true });
         if (!access)
             return { ownerEmail: null, visibility: null, shares: [], policy };
         const db = reg.getDb();

package/dist/triggers/condition-evaluator.js

@@ -14,16 +14,22 @@
  * invalidated wholesale by bumping CONDITION_EVAL_VERSION.
  */
 import { createHash } from "node:crypto";
+import { createTtlCache } from "../shared/ttl-cache.js";
 /**
  * Bumped whenever the prompt template, model, or hardening logic changes.
  * Included in the cache key so cached "yes" answers from a previous
  * (potentially weaker) prompt don't satisfy conditions in the new prompt.
  */
 const CONDITION_EVAL_VERSION = "v2";
-// LRU cache: hash → { result: boolean, expiresAt: number }
-const _cache = new Map();
+// Bounded TTL cache: hash → classifier result. Uses the shared primitive so
+// there is one implementation of "expire and cap an in-memory map" rather than
+// one per call site; see `shared/ttl-cache.ts` for which pattern to use where.
 const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const MAX_CACHE_SIZE = 500;
+const _cache = createTtlCache({
+    ttlMs: CACHE_TTL_MS,
+    maxEntries: MAX_CACHE_SIZE,
+});
 function cacheKey(condition, payload) {
     // Salt the cache key with the prompt version + a separate hash of the
     // payload so two callers can't cross-pollute each other's cache via
@@ -41,26 +47,6 @@ function cacheKey(condition, payload) {
     const raw = `${CONDITION_EVAL_VERSION}|${condition}|${payloadHash}`;
     return createHash("sha256").update(raw).digest("hex").slice(0, 32);
 }
-function pruneCache() {
-    if (_cache.size <= MAX_CACHE_SIZE)
-        return;
-    const now = Date.now();
-    for (const [key, entry] of _cache) {
-        if (entry.expiresAt < now)
-            _cache.delete(key);
-    }
-    // If still too large, drop oldest entries
-    if (_cache.size > MAX_CACHE_SIZE) {
-        const excess = _cache.size - MAX_CACHE_SIZE;
-        let deleted = 0;
-        for (const key of _cache.keys()) {
-            if (deleted >= excess)
-                break;
-            _cache.delete(key);
-            deleted++;
-        }
-    }
-}
 /**
  * Evaluate whether a natural-language condition matches an event payload.
  * Returns true if the condition is empty/undefined (unconditional trigger).
@@ -70,12 +56,10 @@ export async function evaluateCondition(condition, payload, apiKey) {
         return true;
     const key = cacheKey(condition, payload);
     const cached = _cache.get(key);
-    if (cached && cached.expiresAt > Date.now()) {
-        return cached.result;
-    }
+    if (cached !== undefined)
+        return cached;
     const result = await callHaikuClassifier(condition, payload, apiKey);
-    pruneCache();
-    _cache.set(key, { result, expiresAt: Date.now() + CACHE_TTL_MS });
+    _cache.set(key, result);
     return result;
 }
 async function callHaikuClassifier(condition, payload, apiKey) {

package/docs/content/deployment.mdx

@@ -433,6 +433,49 @@ npx @agent-native/core@latest deploy --preset netlify
 
 The workspace build writes static assets under `dist/_workspace_static/` and routes each app to its own Netlify function without forced asset redirects, so files like `/mail/assets/...` are served statically before the server function handles app routes.
 
+### Keep-warm and scale-to-zero databases {#netlify-keep-warm}
+
+The Netlify build emits a scheduled function that requests `/_agent-native/health` **every minute**. That keeps the server function and its database warm so the next visitor after an idle period doesn't pay a cold start (1–5s on Neon). On provisioned compute this is the right default.
+
+**On a metered scale-to-zero database it is the wrong default.** A once-a-minute wake means autosuspend never fires, so the database bills and quota-limits as though it were awake continuously with nobody using the app. On a free-tier Neon this exhausts the compute quota, and the database then rejects **all** reads mid-session — the symptom is a dead app, not a slow one.
+
+Three knobs, all opt-in, defaults unchanged:
+
+| Variable                                    | Effect                                                                                                                                                                       |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Skips the scheduled function entirely. The database is free to autosuspend; the next visitor after an idle period pays its cold start.                                       |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Overrides the cadence with a 5-field cron expression, e.g. `*/5 * * * *`. An unparseable value **fails the build** rather than silently reverting to once a minute.          |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drops only the background-function warm, keeping the server warm. Warming `server` is one request; warming `-background` starts a fresh container that re-probes the schema. |
+
+If you are on a free or otherwise quota-limited database tier, set `AGENT_NATIVE_DISABLE_KEEP_WARM=1` or pick a slower cadence.
+
+### On-demand schema DDL {#skip-ensure-tables}
+
+Each store calls `ensureTable()` on its first database touch, which probes
+`information_schema` / `pg_indexes` and issues `CREATE TABLE` / `ADD COLUMN` /
+`CREATE INDEX` only for what is genuinely missing. On a long-lived Node server
+that cost is paid once per boot and is invisible. On serverless, "first touch" is
+**every cold start**, across ~57 stores — so a cold request can pay a few hundred
+serial round trips before it does any real work.
+
+Two things reduce it:
+
+- The probes are answered from **one batched introspection pass per database**
+  (two queries), instead of one query per table, column, and index. This is
+  automatic and needs no configuration.
+- `AGENT_NATIVE_SKIP_ENSURE_TABLES=1` skips the probe-and-DDL machinery
+  altogether, which is the largest cold-start latency win available.
+
+Set `AGENT_NATIVE_SKIP_ENSURE_TABLES=1` when your database schema is already
+migrated and you do not want application boot creating or altering tables — the
+normal case for a production deployment with a real migration step.
+
+<Callout tone="risk">
+
+**This flag does not and cannot fail closed.** If the schema is in fact missing, the first real query fails loudly rather than being repaired on the fly — which is the point, but it means you own the migration story. Do not set it on a deployment that relies on application boot to provision its tables.
+
+</Callout>
+
 ## Cloudflare Pages {#cloudflare-pages}
 
 ```ts filename="vite.config.ts"
@@ -532,6 +575,11 @@ hosting behavior.
 | `APP_URL`                                   | Optional canonical public origin. Checked ahead of `BETTER_AUTH_URL` when resolving the A2A JWT audience, the OAuth public origin, self-dispatch webhook targets, and generated resource links. Set it explicitly on preview/staging deploys where the request host is unreliable.                                                                                      |
 | `AGENT_PROD_CODE_EXECUTION`                 | Optional production code-execution mode: `off` (default), `sandboxed`, or `trusted`. See [Production Code Execution](#production-code-execution).                                                                                                                                                                                                                       |
 | `AGENT_NATIVE_SSR_CACHE`                    | Deployment-wide SSR shell cache policy: unset/`on` keeps the default hard-cache, `off` sends `no-store`, or a duration such as `30s` / `5m` sets a shorter freshness. See [SSR Caching](#ssr-caching).                                                                                                                                                                  |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Skip the Netlify keep-warm scheduled function so a scale-to-zero database can autosuspend. See [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                                                                         |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Override the keep-warm cadence with a 5-field cron expression (default `* * * * *`). An unparseable value fails the build. See [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                                         |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drop only the background-function warm and keep the server warm. See [Keep-warm](#netlify-keep-warm).                                                                                                                                                                                                                                                                   |
+| `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`     | Turn off the in-process backstop sweep timers (automation redispatch, agent-teams reconciliation, sandbox-execution recovery). On serverless these run per warm container, so their query rate scales with instance count. Set it **only** where a durable scheduler already drives the same recovery, or queued work will not be retried.                              |
+| `AGENT_NATIVE_SKIP_ENSURE_TABLES`           | Skip on-demand schema DDL entirely. Removes the schema-probe round trips every cold start pays before doing any work. Requires that your schema is already migrated — see [On-demand schema DDL](#skip-ensure-tables).                                                                                                                                                  |
 | `AGENT_NATIVE_BUILDER_RELAY_SECRET`         | Dedicated 32+ char shared HMAC secret for preview-safe Builder authorization relay. Set the same value on the approved corporate callback deployment and preview deployments only when authorization must land in an isolated preview database.                                                                                                                         |
 | `AGENT_NATIVE_BUILDER_RELAY_TARGET_ORIGINS` | Corporate callback-only, comma-separated allowlist of exact trusted preview origins (for example, `https://0123456789abcdef01234567--content.netlify.app`). Set it only on the corporate callback deployment. Netlify origins must use an immutable, deploy-specific 24-hex permalink; mutable `deploy-preview-*` aliases, wildcards, and domain suffixes are rejected. |
 

package/docs/content/environment-variables.mdx

@@ -40,6 +40,8 @@ deployment-specific values in the environment or scoped secret store.
 | `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Stable encryption key for a workspace-shared secrets vault.                                     | The same stable key in every app that reads the vault.                                                         |
 | `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Previous workspace key during rotation.                                                         | The old key only; remove it after migration.                                                                   |
 | `ANTHROPIC_API_KEY`                         | Optional deploy-level fallback for the embedded production agent.                               | An API key; prefer scoped credentials for multi-tenant apps.                                                   |
+| `AGENT_ENGINE`                              | Explicitly selects the agent engine instead of auto-detecting from provider keys.               | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                      |
+| `AGENT_ENGINE_PREFER_BYO_KEY`               | Prefers a provider key you set over the managed Builder gateway during auto-detection.          | `true` or `1`; Builder still applies as the fallback when no provider key is set.                              |
 | `AUTH_MODE`                                 | Selects the local authentication behavior used by CLI and agent flows.                          | Unset or `local`; this is not a browser login bypass.                                                          |
 | `AUTH_DISABLED`                             | Disables auth for local or preview-only work.                                                   | `true` or `1`; never use on a public production app.                                                           |
 | `AUTH_MAGIC_LINK`                           | Controls the password-first versus magic-link sign-in path.                                     | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links.               |
@@ -47,6 +49,11 @@ deployment-specific values in the environment or scoped secret store.
 | `ACCESS_TOKEN` / `ACCESS_TOKENS`            | Static bearer fallback for MCP and Connect clients.                                             | One token or a delimited token list; these are not browser auth.                                               |
 | `AGENT_PROD_CODE_EXECUTION`                 | Production code-execution policy.                                                               | `off`, `sandboxed`, or `trusted`. See [Production Code Execution](/docs/deployment#production-code-execution). |
 | `AGENT_NATIVE_SSR_CACHE`                    | Deployment-wide public SSR shell cache policy.                                                  | Unset/`on`, `off`, or a duration such as `30s` or `5m`. See [SSR Caching](/docs/deployment#ssr-caching).       |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Lets a scale-to-zero database autosuspend instead of being woken every minute.                  | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Keep-warm cadence override.                                                                     | A 5-field cron expression such as `*/5 * * * *`; an unparseable value fails the build.                         |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drops only the background-function warm and keeps the server warm.                              | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
+| `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`     | Turns off the in-process backstop sweep timers where a durable scheduler drives the same work.  | `1`; queued work is not retried without another driver.                                                        |
+| `AGENT_NATIVE_SKIP_ENSURE_TABLES`           | Skips on-demand schema DDL for an already-migrated database.                                    | `1`; see [On-demand schema DDL](/docs/deployment#skip-ensure-tables). You own migrations when this is set.     |
 | `COOKIE_DOMAIN`                             | Shares auth cookies across same-database subdomains when explicitly configured.                 | A cookie domain.                                                                                               |
 | `CORS_ALLOWED_ORIGINS`                      | Cross-origin request allowlist.                                                                 | A comma-separated list of exact origins.                                                                       |
 | `WEBHOOK_BASE_URL`                          | Optional public base URL for self-callback and webhook targets.                                 | An absolute public `http(s)` origin.                                                                           |
@@ -90,8 +97,12 @@ specific Google API integrations; they are not required for browser sign-in.
 These are deploy-level fallbacks for single-tenant or local use. Hosted,
 multi-user apps should prefer the scoped credential and connection store.
 
+Every provider key below selects its engine on its own: dropping one in is
+enough, and `AGENT_ENGINE` is only needed to pick between several.
+
 | Variable                       | What it controls                                         | Supported values or format                              |
 | ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------- |
+| `ANTHROPIC_API_KEY`            | Claude model fallback for the built-in AI engine.        | An Anthropic API key.                                   |
 | `OPENAI_API_KEY`               | OpenAI model, realtime voice, or transcription fallback. | An OpenAI API key.                                      |
 | `OPENAI_BASE_URL`              | OpenAI-compatible endpoint used with `OPENAI_API_KEY`.   | An absolute `http(s)` URL without embedded credentials. |
 | `GOOGLE_GENERATIVE_AI_API_KEY` | Gemini model fallback for the built-in AI engine.        | A Google AI API key.                                    |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.145.0",
+  "version": "0.145.2",
   "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": {