@agent-native/core 0.145.0 → 0.145.1

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

@@ -47,6 +47,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.                                                                           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.145.0",
+  "version": "0.145.1",
   "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": {
@@ -412,8 +412,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.3",
-    "@agent-native/toolkit": "^0.13.3"
+    "@agent-native/toolkit": "^0.13.3",
+    "@agent-native/recap-cli": "0.5.3"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",