@agent-native/core 0.146.4 → 0.146.6

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.4",
+  "version": "0.146.6",
   "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/chat/app/hooks/use-navigation-state.ts

@@ -42,7 +42,10 @@ function viewForPath(pathname: string): string {
   if (pathname.startsWith("/database")) return "database";
   if (pathname.startsWith("/extensions")) return "extensions";
   if (pathname.startsWith("/observability")) return "observability";
-  if (pathname.startsWith("/agent")) return "agent";
+  if (pathname.startsWith("/settings/agent") || pathname.startsWith("/agent")) {
+    return "agent";
+  }
+  if (pathname.startsWith("/settings")) return "settings";
   if (pathname.startsWith("/team")) return "settings";
   return "chat";
 }
@@ -60,7 +63,7 @@ function pathForView(view?: string): string {
     case "observability":
       return "/observability";
     case "agent":
-      return "/agent";
+      return "/settings/agent";
     case "settings":
       return "/settings";
     case "team":

package/src/templates/chat/app/routes/agent.tsx

@@ -1,5 +1,4 @@
-import { useT } from "@agent-native/core/client/i18n";
-import { useSetPageTitle } from "@agent-native/toolkit/app-shell";
+import { buildLegacyAgentSettingsRoute } from "@agent-native/core/client/navigation";
 import { Navigate, useLocation } from "react-router";
 
 export function meta() {
@@ -7,34 +6,11 @@ export function meta() {
 }
 
 export default function AgentRoute() {
-  const t = useT();
   const location = useLocation();
-  useSetPageTitle(t("settings.agentTitle"));
-
-  const legacyTab = location.hash.replace(/^#/, "").toLowerCase();
-  const resourceTabs = new Set([
-    "files",
-    "instructions",
-    "agents",
-    "memory",
-    "skills",
-    "learnings",
-  ]);
-  const destination = resourceTabs.has(legacyTab)
-    ? `/settings/agent/resources/${legacyTab}`
-    : legacyTab === "remote-agents"
-      ? "/settings/agent/agents"
-      : legacyTab === "connections"
-        ? "/settings/integrations"
-        : legacyTab === "jobs"
-          ? "/settings/agent/automations"
-          : legacyTab === "access"
-            ? "/settings/agent"
-            : ["llm", "app-models", "limits", "voice", "background"].includes(
-                  legacyTab,
-                )
-              ? `/settings/agent/${legacyTab}`
-              : "/settings/agent";
-
-  return <Navigate to={destination} replace />;
+  return (
+    <Navigate
+      to={buildLegacyAgentSettingsRoute(location.hash, location.search)}
+      replace
+    />
+  );
 }

package/src/templates/default/app/routes/_index.tsx

@@ -76,7 +76,7 @@ export default function IndexPage() {
             </p>
           </Link>
           <Link
-            to="/agent"
+            to="/settings/agent"
             className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
           >
             <p className="text-[13px] font-medium text-foreground">

package/src/templates/default/app/routes/agent.tsx

@@ -1,34 +1,16 @@
-import { AgentTabsPage } from "@agent-native/core/client/agent-chat";
-import { useT } from "@agent-native/core/client/i18n";
-import { Link } from "react-router";
+import { buildLegacyAgentSettingsRoute } from "@agent-native/core/client/navigation";
+import { Navigate, useLocation } from "react-router";
 
 export function meta() {
   return [{ title: "Agent - {{APP_TITLE}}" }];
 }
 
 export default function AgentPage() {
-  const t = useT();
-
+  const location = useLocation();
   return (
-    <main className="min-h-screen bg-background px-6 py-10">
-      <div className="mx-auto w-full max-w-5xl space-y-6">
-        <div className="space-y-2">
-          <Link
-            to="/settings"
-            className="text-[13px] text-muted-foreground hover:text-foreground"
-          >
-            {t("settings.title")}
-          </Link>
-          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
-            {t("settings.agentTitle")}
-          </h1>
-          <p className="text-[14px] leading-relaxed text-muted-foreground">
-            {t("settings.agentDescription")}
-          </p>
-        </div>
-
-        <AgentTabsPage className="min-h-[640px] rounded-lg border border-border/50" />
-      </div>
-    </main>
+    <Navigate
+      to={buildLegacyAgentSettingsRoute(location.hash, location.search)}
+      replace
+    />
   );
 }

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).