@agent-native/core 0.146.5 → 0.146.7

package/dist/server/http-response-telemetry.js

@@ -13,10 +13,21 @@ const TRACKING_INGEST_PATHS = new Set([
     "/api/events/track",
     "/_agent-native/track",
 ]);
+const SLOW_REQUEST_MS = 1_000;
+const SLOW_REQUEST_LOG_EVENT = "agent-native.slow_request";
 const PROCESS_STATE_KEY = Symbol.for("@agent-native/core/http-response-telemetry.process-state");
 const globalRef = globalThis;
+// Process start → this module being evaluated. On a serverless cold start that
+// span is the platform's container boot plus server-bundle evaluation, which
+// happens entirely before any request handler runs and is therefore invisible
+// to every in-handler measurement. Recorded here because module scope is the
+// earliest point our own code can observe. Stored on globalThis so the
+// earliest-evaluated copy wins if the bundle loads this module twice.
 const processState = globalRef[PROCESS_STATE_KEY] ??
-    (globalRef[PROCESS_STATE_KEY] = { requestSequence: 0 });
+    (globalRef[PROCESS_STATE_KEY] = {
+        requestSequence: 0,
+        moduleEvalUptimeMs: Math.max(0, Math.round(process.uptime() * 1_000)),
+    });
 const REQUEST_TELEMETRY_KEY = Symbol.for("@agent-native/core/http-response-telemetry.request");
 const installedApps = new WeakSet();
 function envValue(key) {
@@ -118,7 +129,7 @@ function shouldTrack(pathname, statusCode, state) {
         return true;
     if (state.startupDb)
         return true;
-    if (Date.now() - state.startedAt >= 1_000)
+    if (Date.now() - state.startedAt >= SLOW_REQUEST_MS)
         return true;
     if (state.db.errorCount > 0 || state.db.timeoutCount > 0) {
         return true;
@@ -151,6 +162,10 @@ function runtimeProvider() {
         return "cloudflare-pages";
     return "node";
 }
+/** Module evaluation → this request starting, i.e. idle boot the app paid for. */
+function moduleToRequestMs(state) {
+    return Math.max(0, state.processAgeAtStartMs - processState.moduleEvalUptimeMs);
+}
 function emitTelemetry(event, state, response) {
     const statusCode = responseStatusCode(event, response);
     const pathname = requestPath(event);
@@ -175,6 +190,8 @@ function emitTelemetry(event, state, response) {
             cold_start: state.requestSequence === 1,
             request_sequence: state.requestSequence,
             process_age_ms: state.processAgeAtStartMs,
+            boot_to_module_ms: processState.moduleEvalUptimeMs,
+            module_to_request_ms: moduleToRequestMs(state),
             framework_ready_wait_ms: state.frameworkReadyWaitMs,
             runtime_provider: runtimeProvider(),
             function_name: envValue("AWS_LAMBDA_FUNCTION_NAME"),
@@ -238,20 +255,99 @@ function requestTelemetryState(event) {
 export function getHttpRequestTelemetryId(event) {
     return requestTelemetryState(event)?.requestId;
 }
-function appendServerTiming(response, event, name, durationMs) {
+function appendServerTiming(response, event, name, durationMs, desc) {
     const duration = Math.max(0, Math.round(durationMs));
+    const suffix = desc ? `;desc=${JSON.stringify(desc)}` : "";
     try {
-        response.headers.append("server-timing", `${name};dur=${duration}`);
+        response.headers.append("server-timing", `${name};dur=${duration}${suffix}`);
     }
     catch {
         try {
-            setServerTiming(event, name, { dur: duration });
+            setServerTiming(event, name, desc ? { dur: duration, desc } : { dur: duration });
         }
         catch {
             // Some adapters finalize headers eagerly. Tracking still runs.
         }
     }
 }
+/**
+ * Does this response get stored in a shared (CDN) cache and replayed?
+ *
+ * SSR HTML and React Router `.data` are one impersonal shell hard-cached for
+ * every visitor, so their headers are written ONCE by the origin render and
+ * then handed unchanged to everyone who hits the cache afterwards.
+ */
+function isSharedCacheable(response) {
+    const cacheControl = response.headers.get("cache-control")?.toLowerCase() ?? "";
+    if (!cacheControl)
+        return false;
+    if (/\b(?:no-store|no-cache|private)\b/.test(cacheControl))
+        return false;
+    return (/\bpublic\b/.test(cacheControl) || /\bs-maxage=[1-9]/.test(cacheControl));
+}
+/**
+ * Per-phase `server-timing` entries do NOT belong on a shared-cacheable
+ * response. `app;dur=2159` on a cached shell describes one origin render from
+ * an arbitrary point in the past, yet every later visitor reads it as the cost
+ * of their own request — a stale number wearing a live number's name.
+ *
+ * So a cacheable response gets exactly one entry, `origin`, whose description
+ * leads with the absolute wall-clock time of the render that produced it. Two
+ * visitors comparing notes see the identical timestamp, which is what a replay
+ * is. The live per-invocation breakdown goes to the slow-request log line and
+ * to tracking instead; neither is ever cached.
+ */
+function originSnapshotDesc(state) {
+    const parts = [new Date(state.startedAt).toISOString()];
+    if (state.requestSequence === 1) {
+        parts.push("cold", `boot=${processState.moduleEvalUptimeMs}`, `init=${moduleToRequestMs(state)}`);
+    }
+    if (state.frameworkReadyWaitMs > 0) {
+        parts.push(`startup=${Math.round(state.frameworkReadyWaitMs)}`);
+    }
+    if (state.db.operationCount > 0) {
+        parts.push(`db=${Math.round(state.db.operationWallMs)}`, `dbops=${state.db.operationCount}`);
+    }
+    return parts.join(" ");
+}
+/**
+ * One structured line per cold or slow request, straight to stdout.
+ *
+ * Function logs are the only timing surface readable without a deploy, and
+ * `track()` silently no-ops when no tracking provider is registered — which is
+ * the common case. Deliberately NOT wrapped in a catch: a swallowed emit would
+ * leave a slow request indistinguishable from a fast one.
+ */
+function logSlowRequest(event, state, response, durationMs, pathname) {
+    const coldStart = state.requestSequence === 1;
+    if (!coldStart && durationMs < SLOW_REQUEST_MS)
+        return;
+    console.log(JSON.stringify({
+        event: SLOW_REQUEST_LOG_EVENT,
+        app: getAppName(),
+        method: getMethod(event),
+        path: normalizeHttpTelemetryPath(pathname),
+        status: responseStatusCode(event, response),
+        duration_ms: Math.round(durationMs),
+        cold_start: coldStart,
+        request_sequence: state.requestSequence,
+        boot_to_module_ms: processState.moduleEvalUptimeMs,
+        module_to_request_ms: moduleToRequestMs(state),
+        process_age_ms: state.processAgeAtStartMs,
+        framework_ready_wait_ms: Math.round(state.frameworkReadyWaitMs),
+        db_ms: Math.round(state.db.operationWallMs),
+        db_connect_ms: Math.round(state.db.connectTotalMs),
+        db_operation_count: state.db.operationCount,
+        db_error_count: state.db.errorCount,
+        db_timeout_count: state.db.timeoutCount,
+        startup_db_ms: state.startupDb
+            ? Math.round(state.startupDb.operationWallMs)
+            : undefined,
+        shared_cacheable: response ? isSharedCacheable(response) : undefined,
+        runtime_provider: runtimeProvider(),
+        request_id: state.requestId,
+    }));
+}
 export function recordFrameworkReadyWait(event, durationMs) {
     const state = requestTelemetryState(event);
     if (state) {
@@ -295,7 +391,17 @@ export function installHttpResponseTelemetryHooks(nitroApp) {
                 // Some adapters finalize headers eagerly. Tracking still has the id.
             }
         }
+        if (isSharedCacheable(response)) {
+            appendServerTiming(response, event, "origin", durationMs, originSnapshotDesc(state));
+            logSlowRequest(event, state, response, durationMs, requestPath(event));
+            emitTelemetry(event, state, response);
+            return;
+        }
         appendServerTiming(response, event, "app", durationMs);
+        if (state.requestSequence === 1) {
+            appendServerTiming(response, event, "boot", processState.moduleEvalUptimeMs);
+            appendServerTiming(response, event, "init", moduleToRequestMs(state));
+        }
         if (state.frameworkReadyWaitMs > 0) {
             appendServerTiming(response, event, "startup", state.frameworkReadyWaitMs);
         }
@@ -309,6 +415,7 @@ export function installHttpResponseTelemetryHooks(nitroApp) {
             appendServerTiming(response, event, "startup-db", state.startupDb.operationWallMs);
             appendServerTiming(response, event, "startup-db-connect", state.startupDb.connectTotalMs);
         }
+        logSlowRequest(event, state, response, durationMs, requestPath(event));
         emitTelemetry(event, state, response);
     });
 }

package/dist/server/release-migrations.js

@@ -2,6 +2,7 @@ import { CONTEXT_XRAY_MIGRATIONS } from "../agent/context-xray/migrations.js";
 import { OBSERVATIONAL_MEMORY_MIGRATIONS } from "../agent/observational-memory/migrations.js";
 import { runMigrations } from "../db/migrations.js";
 import { runAutomationRunMigrations } from "../jobs/run-history.js";
+import { runAutomationSchedulerHealthMigrations } from "../jobs/scheduler-health.js";
 import { ORG_MIGRATIONS } from "../org/migrations.js";
 import { runBetterAuthMigrations } from "./better-auth-migrations.js";
 /**
@@ -21,4 +22,5 @@ export async function runFrameworkReleaseMigrations(nitroApp) {
         table: "_observational_memory_migrations",
     })(nitroApp);
     await runAutomationRunMigrations(nitroApp);
+    await runAutomationSchedulerHealthMigrations(nitroApp);
 }

package/dist/server/ssr-handler.js

@@ -193,6 +193,14 @@ function isSsrHtmlOrDataResponse(headers, status, pathname) {
  * │ hatch — because that is what poisons a shared CDN cache key. A value fixed │
  * │ for the whole deployment cannot.                                           │
  * └──────────────────────────────────────────────────────────────────────────┘
+ *
+ * The same sharing rule governs any DIAGNOSTIC header on this response. A
+ * per-request timing written here is stored once by the origin render and
+ * replayed unchanged to every later visitor, so it must not wear a live-looking
+ * phase name. `installHttpResponseTelemetryHooks` detects the shared-cacheable
+ * policy stamped below and collapses `server-timing` to one `origin` entry
+ * carrying the render's wall-clock time; do not add a per-request header here
+ * that contradicts that.
  */
 function applyDefaultSsrCacheHeader(headers, status, pathname) {
     if (!isSsrHtmlOrDataResponse(headers, status, pathname))

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

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

package/dist/templates/workspace-core/.agents/skills/performance/SKILL.md

@@ -3,8 +3,10 @@ name: performance
 description: >-
   Keep apps and templates loading fast. Read when adding a data model, a
   list/read action, a page or sidebar that loads data, or when something loads
-  slowly. Covers column projection, indexing hot-path queries, avoiding N+1 and
-  round-trip waterfalls, cheap polling, and not recomputing on every read.
+  slowly, or when adding a dependency to the deployed server bundle. Covers
+  column projection, indexing hot-path queries, avoiding N+1 and round-trip
+  waterfalls, cheap polling, not recomputing on every read, and cold-start
+  artifact size.
 scope: dev
 metadata:
   internal: true
@@ -146,7 +148,9 @@ just one.
 
 If you're debugging a slow first response, check whether something
 re-personalized the shell before concluding the render itself is slow — the
-fix is client-side data loading after the shell paints, never per-user SSR.
+fix is client-side data loading after the shell paints, never per-user SSR. If
+the shell is clean and a cold miss is still seconds long, the cost is upstream
+of the render: see §9.
 See the `authentication` skill for the full model and `guard:ssr-cache-shell`
 plus `ssr-handler.spec.ts` (`packages/core/src/server/ssr-handler.ts`) for the
 enforced contract.
@@ -231,6 +235,50 @@ await backfillOneRow(); // guard:allow-boot-data-work — single row, bounded
 branch adds. It cannot see everything — a helper that hides the work one call
 deeper reads as innocent — so the rule matters more than the check.
 
+## 9. Cold start is the artifact, not just the work it does
+
+§8 covers what the process does at boot. This covers how much there is to boot.
+Measured in production: a cold cache miss on `www.agent-native.com` returned in
+**4.5–6.0s** while the in-handler `server-timing: app;dur` was only **~2100ms** —
+the other ~2900ms is platform init, spent before any of our code evaluates. A
+different app with a healthy database measured **13.4s** TTFB on its first cold
+request with `app;dur=1338`, so ~12s of init. Platform init scales with the size
+of the deployed artifact. Every app pays it, and no query tuning can reach it.
+
+- **The `/*` page function is the one every visitor's cache miss wakes.** Nothing
+  belongs in it that a page render cannot call. Headless browsers, ffmpeg, image
+  rasterizers, and other heavy runtimes belong in the function that actually
+  invokes them, or behind a job — not in the default handler. PR #2684, titled
+  "Harden auth and cold-start data paths", put 78MB of headless Chromium into
+  every page function; nothing in the diff looked like a performance change.
+- **Each extra emitted function is a full second copy of the bundle.** Netlify
+  copies the whole server directory per function, so splitting out a
+  `-background` or per-route function multiplies existing weight rather than
+  dividing it. Trim the artifact before you split it.
+- **Already-compressed binaries do not shrink again in the deploy zip.** A
+  Brotli-packed browser or a static ffmpeg build costs close to its full size in
+  upload and in cold-start extraction. Budget from bytes on disk, never from an
+  assumption that compression will absorb it.
+- **Never resolve a copied dependency by walking ancestor `node_modules`.** In a
+  monorepo that walk does not fail — it finds a sibling app's copy and ships
+  that. Resolve from the app's own dependency root and throw when it is missing;
+  a silently-found wrong package is precisely the indistinguishable-from-success
+  failure this repo bans.
+
+`packages/core/src/deploy/build.ts` is what decides all of this: the
+platform/arch filter at `:2384-2410` and the per-preset copy list at
+`:4499-4504`. Adding a package there adds it to every page function.
+
+**Measure a built bundle by timing the import and forcing exit.** Never measure
+by waiting for the process to exit — module scope starts timers and opens
+handles, so process lifetime measures those, not boot cost. That exact mistake
+produced a wrong number during the investigation behind this section.
+
+```sh
+node -e 'const t=Date.now();import(process.argv[1]).then(()=>{console.log(`${Date.now()-t}ms`);process.exit(0)})' \
+  ./.netlify/functions-internal/server/main.mjs
+```
+
 ## Checklist — run before shipping a list/read or a new table
 
 - [ ] List selects only displayed columns; heavy blobs excluded or `substr`-truncated.
@@ -246,3 +294,6 @@ deeper reads as innocent — so the rule matters more than the check.
       aggregations and re-syncs run on every cold start there (see §8).
 - [ ] Mutation-fresh reads go through actions + `useActionQuery`, not SSR loader
       data.
+- [ ] No heavy runtime (browser, ffmpeg, rasterizer) added to what the `/*` page
+      function ships, and no new copied dependency resolved by walking ancestor
+      `node_modules` (see §9).

package/dist/vite/client.js

@@ -2547,7 +2547,11 @@ const DEFAULT_VITE_WATCH_IGNORES = [
 function forceServeOnly(pluginOrPreset) {
     if (Array.isArray(pluginOrPreset))
         return pluginOrPreset.map(forceServeOnly);
-    return { ...pluginOrPreset, apply: "serve" };
+    return {
+        ...pluginOrPreset,
+        apply: (_config, configEnv) => configEnv.command === "serve" &&
+            !(configEnv.isPreview && process.env.IS_RR_BUILD_REQUEST === "yes"),
+    };
 }
 function nitroPresetMarkerPlugin(options) {
     const preset = options.nitro?.preset;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.146.5",
+  "version": "0.146.7",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/src/templates/workspace-core/.agents/skills/performance/SKILL.md

@@ -3,8 +3,10 @@ name: performance
 description: >-
   Keep apps and templates loading fast. Read when adding a data model, a
   list/read action, a page or sidebar that loads data, or when something loads
-  slowly. Covers column projection, indexing hot-path queries, avoiding N+1 and
-  round-trip waterfalls, cheap polling, and not recomputing on every read.
+  slowly, or when adding a dependency to the deployed server bundle. Covers
+  column projection, indexing hot-path queries, avoiding N+1 and round-trip
+  waterfalls, cheap polling, not recomputing on every read, and cold-start
+  artifact size.
 scope: dev
 metadata:
   internal: true
@@ -146,7 +148,9 @@ just one.
 
 If you're debugging a slow first response, check whether something
 re-personalized the shell before concluding the render itself is slow — the
-fix is client-side data loading after the shell paints, never per-user SSR.
+fix is client-side data loading after the shell paints, never per-user SSR. If
+the shell is clean and a cold miss is still seconds long, the cost is upstream
+of the render: see §9.
 See the `authentication` skill for the full model and `guard:ssr-cache-shell`
 plus `ssr-handler.spec.ts` (`packages/core/src/server/ssr-handler.ts`) for the
 enforced contract.
@@ -231,6 +235,50 @@ await backfillOneRow(); // guard:allow-boot-data-work — single row, bounded
 branch adds. It cannot see everything — a helper that hides the work one call
 deeper reads as innocent — so the rule matters more than the check.
 
+## 9. Cold start is the artifact, not just the work it does
+
+§8 covers what the process does at boot. This covers how much there is to boot.
+Measured in production: a cold cache miss on `www.agent-native.com` returned in
+**4.5–6.0s** while the in-handler `server-timing: app;dur` was only **~2100ms** —
+the other ~2900ms is platform init, spent before any of our code evaluates. A
+different app with a healthy database measured **13.4s** TTFB on its first cold
+request with `app;dur=1338`, so ~12s of init. Platform init scales with the size
+of the deployed artifact. Every app pays it, and no query tuning can reach it.
+
+- **The `/*` page function is the one every visitor's cache miss wakes.** Nothing
+  belongs in it that a page render cannot call. Headless browsers, ffmpeg, image
+  rasterizers, and other heavy runtimes belong in the function that actually
+  invokes them, or behind a job — not in the default handler. PR #2684, titled
+  "Harden auth and cold-start data paths", put 78MB of headless Chromium into
+  every page function; nothing in the diff looked like a performance change.
+- **Each extra emitted function is a full second copy of the bundle.** Netlify
+  copies the whole server directory per function, so splitting out a
+  `-background` or per-route function multiplies existing weight rather than
+  dividing it. Trim the artifact before you split it.
+- **Already-compressed binaries do not shrink again in the deploy zip.** A
+  Brotli-packed browser or a static ffmpeg build costs close to its full size in
+  upload and in cold-start extraction. Budget from bytes on disk, never from an
+  assumption that compression will absorb it.
+- **Never resolve a copied dependency by walking ancestor `node_modules`.** In a
+  monorepo that walk does not fail — it finds a sibling app's copy and ships
+  that. Resolve from the app's own dependency root and throw when it is missing;
+  a silently-found wrong package is precisely the indistinguishable-from-success
+  failure this repo bans.
+
+`packages/core/src/deploy/build.ts` is what decides all of this: the
+platform/arch filter at `:2384-2410` and the per-preset copy list at
+`:4499-4504`. Adding a package there adds it to every page function.
+
+**Measure a built bundle by timing the import and forcing exit.** Never measure
+by waiting for the process to exit — module scope starts timers and opens
+handles, so process lifetime measures those, not boot cost. That exact mistake
+produced a wrong number during the investigation behind this section.
+
+```sh
+node -e 'const t=Date.now();import(process.argv[1]).then(()=>{console.log(`${Date.now()-t}ms`);process.exit(0)})' \
+  ./.netlify/functions-internal/server/main.mjs
+```
+
 ## Checklist — run before shipping a list/read or a new table
 
 - [ ] List selects only displayed columns; heavy blobs excluded or `substr`-truncated.
@@ -246,3 +294,6 @@ deeper reads as innocent — so the rule matters more than the check.
       aggregations and re-syncs run on every cold start there (see §8).
 - [ ] Mutation-fresh reads go through actions + `useActionQuery`, not SSR loader
       data.
+- [ ] No heavy runtime (browser, ffmpeg, rasterizer) added to what the `/*` page
+      function ships, and no new copied dependency resolved by walking ancestor
+      `node_modules` (see §9).