@agent-native/core 0.120.1 → 0.120.2

package/docs/content/extensions.mdx

@@ -223,7 +223,7 @@ Pattern across all of these: extensions are about **the moment** the user is in
 
 The simple path:
 
-1. **Click "New Extension"** in the sidebar (or just ask in chat).
+1. Open **Settings → Extensions** (or just ask in chat), then click **New Extension**.
 2. **Describe what you want in one sentence.** "A sticky-note pad for the contact I'm emailing." "A KPI box for trials started this week."
 3. **The agent writes it and it appears in your Extensions list, ready to use.**
 
@@ -617,9 +617,23 @@ Extensions are private to the user who created them by default. To share:
 
 Shared extensions have their own URLs and plug into the same share dialog as documents, decks, and dashboards. Slot installs are always personal — sharing an extension means others _can_ install it; it doesn't auto-pin it to their UI.
 
-## Extensions vs. editing the app code {#vs-app-code}
+## Should I use an extension or edit the app code? {#vs-app-code}
 
-The framework lets the agent edit the app's source code directly — components, routes, styles. So when should you reach for an extension instead?
+The framework lets the agent edit the app's source code directly — components,
+routes, styles, and business logic. Use this question when either path could
+solve the request:
+
+- **Start with an extension** for a self-contained, relatively one-off widget:
+  a custom visualization or interaction, a dashboard tile, a standalone
+  utility, or an add-on in an existing slot. It is fast, requires no source
+  change, build, or deploy, and can be private or shared.
+- **Use app code** for a core feature of the template, a change to native UI,
+  layout, routes, or business logic, or anything that should be reused broadly
+  across dashboards or users. If the host has no suitable slot or the request
+  needs a new slot, use code.
+- **Promote repeated extensions.** If people keep rebuilding the same
+  extension, or maintaining copies in many places would be worse than one
+  shared implementation, move it into app code as a reusable native feature.
 
 |                       | Extension                                         | App code edit                        |
 | --------------------- | ------------------------------------------------- | ------------------------------------ |
@@ -630,7 +644,12 @@ The framework lets the agent edit the app's source code directly — components,
 | **Scope**             | One user (or shared with org)                     | The entire product, every user       |
 | **Best for**          | Personal widgets, custom KPIs, per-team utilities | Core features that ship to all users |
 
-Rule of thumb: **if it's for one user or one team, it's an extension.** If every user of the template should get it, ship it as a real feature.
+Rule of thumb: **if an extension can solve the problem, generally start there.**
+Use code when the extension boundary does not fit or when broad reuse and
+product-wide availability justify a native implementation. For example, a
+one-off custom visualization on a dashboard is a good extension; a new pie,
+multi-bar, or line chart type that should be available across dashboards
+belongs in the template code.
 
 If what you actually need is a cached, refreshable data source for an existing chart or table — not a new interactive widget — see [Data Programs](/docs/data-programs) instead; it shares this page's sandbox and security posture but has no UI of its own.
 

package/package.json

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

package/src/agent/production-agent.ts

@@ -6401,6 +6401,10 @@ export async function chainServerDrivenContinuation(opts: {
         terminalEvent: run.events.at(-1)?.event,
       })
       .catch(() => {});
+    run.continuationTerminalEvent = {
+      type: "auto_continue",
+      reason: continuationReason,
+    };
   } catch (chainErr) {
     // Chain dispatch failed — fail loud so the held row goes terminal
     // instead of spinning. The reaper would also catch it, but this is

package/src/agent/run-manager.ts

@@ -41,6 +41,16 @@ export interface ActiveRun {
   subscribers: Set<(event: RunEvent) => void>;
   abort: AbortController;
   abortReason?: string;
+  /**
+   * Terminal event to emit when a server-driven continuation has been handed
+   * off successfully. The continuation runs outside this process, so the
+   * normal loop-level auto_continue event is not sent through this run's
+   * `send` callback.
+   */
+  continuationTerminalEvent?: Extract<
+    AgentChatEvent,
+    { type: "auto_continue" }
+  >;
   startedAt: number;
 }
 
@@ -954,7 +964,17 @@ export function startRun(
       //    /runs/active check while we wait for SQL writes to land.
       let completionError: unknown = null;
       let terminalPersistenceError: unknown = null;
-      const terminalEvent = pendingTerminalEvent?.event ?? null;
+      const resolveTerminalEventForCompletion = () => {
+        const continuationTerminalEvent = run.continuationTerminalEvent
+          ? {
+              seq: run.events.length,
+              event: run.continuationTerminalEvent,
+            }
+          : null;
+        return continuationTerminalEvent ?? pendingTerminalEvent;
+      };
+      let terminalEventForCompletion = resolveTerminalEventForCompletion();
+      let terminalEvent = terminalEventForCompletion?.event ?? null;
       if (
         onComplete &&
         !(run.status === "aborted" && run.abortReason === "no_progress")
@@ -966,12 +986,12 @@ export function startRun(
               ? "errored"
               : run.status;
           const completionRun: ActiveRun =
-            pendingTerminalEvent || completionStatus !== run.status
+            terminalEventForCompletion || completionStatus !== run.status
               ? {
                   ...run,
                   status: completionStatus,
-                  events: pendingTerminalEvent
-                    ? [...run.events, pendingTerminalEvent]
+                  events: terminalEventForCompletion
+                    ? [...run.events, terminalEventForCompletion]
                     : run.events,
                 }
               : run;
@@ -986,6 +1006,12 @@ export function startRun(
         }
       }
 
+      // Server-driven continuation is installed by onComplete after the
+      // successor has been dispatched. Resolve the terminal event again so
+      // this chunk emits auto_continue instead of a misleading done event.
+      terminalEventForCompletion = resolveTerminalEventForCompletion();
+      terminalEvent = terminalEventForCompletion?.event ?? null;
+
       // 2. Compute final status. If the completion callback threw, we'd
       //    rather mark the run errored than claim success with incomplete
       //    thread_data.
@@ -1022,18 +1048,18 @@ export function startRun(
         // re-stamp the seq at emit time (max-seq+1) just below.
         const terminalEvent: AgentChatEvent =
           finalStatus === "completed"
-            ? (pendingTerminalEvent?.event ?? { type: "done" })
-            : pendingTerminalEvent?.event.type === "error" ||
-                pendingTerminalEvent?.event.type === "missing_api_key"
-              ? pendingTerminalEvent.event
-              : pendingTerminalEvent?.event.type === "auto_continue"
+            ? (terminalEventForCompletion?.event ?? { type: "done" })
+            : terminalEventForCompletion?.event.type === "error" ||
+                terminalEventForCompletion?.event.type === "missing_api_key"
+              ? terminalEventForCompletion.event
+              : terminalEventForCompletion?.event.type === "auto_continue"
                 ? // The run was checkpointed at a soft-timeout/loop boundary and
                   // is recoverable: the partial turn is in agent_run_events and
                   // the continuation run will re-attempt the thread_data save.
                   // Even though the completion save failed (finalStatus stays
                   // "errored" for SQL/diagnostics), re-emit the auto_continue so
                   // the client resumes instead of seeing a dead chat.
-                  pendingTerminalEvent.event
+                  terminalEventForCompletion.event
                 : {
                     type: "error",
                     error: completionError

package/src/agent/types.ts

@@ -167,6 +167,7 @@ export interface AgentChatRequest {
     continuationReason?:
       | "run_timeout"
       | "loop_limit"
+      | "max_tokens"
       | "no_progress"
       | "stream_ended"
       | "gateway_timeout"
@@ -371,6 +372,7 @@ export type AgentChatEvent =
       reason:
         | "run_timeout"
         | "loop_limit"
+        | "max_tokens"
         | "no_progress"
         | "stream_ended"
         | "gateway_timeout"

package/src/client/extensions/ExtensionsListPage.tsx

@@ -99,7 +99,14 @@ function CreateToolInput({ className }: { className?: string }) {
   );
 }
 
-export function ExtensionsListPage() {
+export interface ExtensionsListPageProps {
+  /** Skip the standalone extensions navigation state when embedded in Settings. */
+  embedded?: boolean;
+}
+
+export function ExtensionsListPage({
+  embedded = false,
+}: ExtensionsListPageProps = {}) {
   const t = useT();
   const [showCreate, setShowCreate] = useState(false);
   const [confirmDeleteId, setConfirmDeleteId] = useState<string | null>(null);
@@ -111,12 +118,13 @@ export function ExtensionsListPage() {
   );
 
   useEffect(() => {
+    if (embedded) return;
     fetch(agentNativePath("/_agent-native/application-state/navigation"), {
       method: "PUT",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ view: "extensions" }),
     }).catch(() => {});
-  }, []);
+  }, [embedded]);
 
   useEffect(() => {
     if (typeof window === "undefined") return;
@@ -189,7 +197,12 @@ export function ExtensionsListPage() {
   };
 
   return (
-    <div className="flex h-full w-full flex-col">
+    <div
+      className={cn(
+        "flex w-full flex-col",
+        embedded ? "min-h-[28rem]" : "h-full",
+      )}
+    >
       <header className="flex h-12 items-center justify-between border-b px-4 shrink-0">
         <div className="flex items-center gap-2">
           <h1 className="text-sm font-semibold">{t("extensions.title")}</h1>

package/src/client/settings/ExtensionsSettingsContent.tsx

@@ -0,0 +1,24 @@
+import { IconLoader2 } from "@tabler/icons-react";
+import { lazy, Suspense } from "react";
+
+const ExtensionsListPage = lazy(() =>
+  import("../extensions/ExtensionsListPage.js").then((module) => ({
+    default: module.ExtensionsListPage,
+  })),
+);
+
+export function ExtensionsSettingsContent() {
+  return (
+    <div className="mx-auto w-full max-w-5xl overflow-hidden rounded-lg border border-border bg-background">
+      <Suspense
+        fallback={
+          <div className="flex min-h-[28rem] items-center justify-center text-muted-foreground">
+            <IconLoader2 className="size-5 animate-spin" aria-label="Loading" />
+          </div>
+        }
+      >
+        <ExtensionsListPage embedded />
+      </Suspense>
+    </div>
+  );
+}

package/src/client/settings/SettingsPanel.tsx

@@ -29,6 +29,7 @@ import {
   IconGauge,
   IconApps,
   IconUsersGroup,
+  IconTool,
 } from "@tabler/icons-react";
 import React, {
   Suspense,
@@ -67,6 +68,7 @@ import {
 import { AgentsSection } from "./AgentsSection.js";
 import { AutomationsSection } from "./AutomationsSection.js";
 import { DemoModeSection } from "./DemoModeSection.js";
+import { ExtensionsSettingsContent } from "./ExtensionsSettingsContent.js";
 import { SecretsSection } from "./SecretsSection.js";
 import {
   SettingsSection,
@@ -3037,6 +3039,14 @@ export function useAgentSettingsTabs(): SettingsTabItem[] {
           />
         ),
       },
+      {
+        id: "extensions",
+        label: "Extensions",
+        icon: IconTool,
+        group: "workspace",
+        keywords: "extensions widgets mini apps tools sandboxed apps",
+        content: <ExtensionsSettingsContent />,
+      },
     ];
   }, [baseProps]);
 }

package/src/deploy/build.ts

@@ -3708,6 +3708,9 @@ export default bundle;
       "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(
         process.env.GA_MEASUREMENT_ID?.trim() || "",
       ),
+      "process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID": JSON.stringify(
+        process.env.GTM_CONTAINER_ID?.trim() || "",
+      ),
       "process.env.AGENT_NATIVE_BUILD_DEPLOY_CONTEXT": JSON.stringify(
         process.env.CONTEXT?.trim() || "",
       ),

package/src/server/analytics.ts

@@ -2,16 +2,21 @@
  * Opt-in analytics injection for SSR streams.
  * Supported environment variables:
  * - `GA_MEASUREMENT_ID` — Google Analytics 4 measurement ID
+ * - `GTM_CONTAINER_ID` — Google Tag Manager web container ID
  *
  * Netlify configuration-file env vars are build-time only for serverless
  * functions, so the Vite/Nitro build paths also bake this public value into
  * SSR bundles.
  *
  * Amplitude and Sentry are initialized client-side via their npm packages
- * (see `packages/core/src/client/analytics.ts`). Only GA requires script
- * tag injection because the gtag.js loader must be a `<script src>`.
+ * (see `packages/core/src/client/analytics.ts`). GTM and GA require script
+ * tag injection because their loaders must be `<script>` elements.
  *
- * When set, the corresponding script tags are injected before `</head>`.
+ * When GTM is set, its head bootstrap is injected before `</head>` and its
+ * noscript fallback immediately after `<body>`. GTM takes precedence over GA
+ * so pageviews are not double-counted; configure the GA tag inside GTM.
+ * When only GA is set, the corresponding script tags are injected before
+ * `</head>`.
  * When not set, the stream passes through untouched (zero overhead).
  *
  * Usage in entry.server.tsx:
@@ -22,6 +27,7 @@
  */
 
 declare const __AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID__: string | undefined;
+declare const __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__: string | undefined;
 
 function normalizeMeasurementId(value: string | undefined): string | null {
   const trimmed = value?.trim();
@@ -34,6 +40,25 @@ function getViteBakedGaMeasurementId(): string | undefined {
     : undefined;
 }
 
+function normalizeContainerId(value: string | undefined): string | null {
+  const trimmed = value?.trim().toUpperCase();
+  return trimmed && /^GTM-[A-Z0-9]+$/.test(trimmed) ? trimmed : null;
+}
+
+function getViteBakedGtmContainerId(): string | undefined {
+  return typeof __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__ === "string"
+    ? __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__
+    : undefined;
+}
+
+function getGtmContainerId(): string | null {
+  return (
+    normalizeContainerId(process.env.GTM_CONTAINER_ID) ||
+    normalizeContainerId(process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID) ||
+    normalizeContainerId(getViteBakedGtmContainerId())
+  );
+}
+
 function getGaMeasurementId(): string | null {
   return (
     normalizeMeasurementId(process.env.GA_MEASUREMENT_ID) ||
@@ -74,6 +99,37 @@ function getGaScript(): string | null {
   );
 }
 
+function getGtmHeadScript(containerId: string): string {
+  const jsId = JSON.stringify(containerId);
+  return `<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer',${jsId});</script>`;
+}
+
+function getGtmBodyFallback(containerId: string): string {
+  const src = encodeURIComponent(containerId);
+  return `<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=${src}" height="0" width="0" style="display:none;visibility:hidden" title="Google Tag Manager"></iframe></noscript>`;
+}
+
+type AnalyticsInjection = {
+  head: string;
+  body: string;
+};
+
+function getAnalyticsInjection(): AnalyticsInjection | null {
+  const containerId = getGtmContainerId();
+  if (containerId) {
+    return {
+      head: getGtmHeadScript(containerId),
+      body: getGtmBodyFallback(containerId),
+    };
+  }
+
+  const gaScript = getGaScript();
+  return gaScript ? { head: gaScript, body: "" } : null;
+}
+
+const HEAD_CLOSE_PATTERN = /<\/head>/i;
+const BODY_OPEN_PATTERN = /<body\b[^>]*>/i;
+
 /**
  * Add the configured analytics scripts to a complete HTML document.
  *
@@ -82,38 +138,111 @@ function getGaScript(): string | null {
  * auth guard and need the same injection path.
  */
 export function injectAnalyticsIntoHtml(html: string): string {
-  const script = getGaScript();
-  if (!script) return html;
-  const headCloseIdx = html.indexOf("</head>");
-  if (headCloseIdx === -1) return html;
-  return html.slice(0, headCloseIdx) + script + html.slice(headCloseIdx);
+  const injection = getAnalyticsInjection();
+  if (!injection) return html;
+
+  const headCloseMatch = HEAD_CLOSE_PATTERN.exec(html);
+  if (!headCloseMatch || headCloseMatch.index === undefined) return html;
+
+  let output =
+    html.slice(0, headCloseMatch.index) +
+    injection.head +
+    html.slice(headCloseMatch.index);
+
+  if (injection.body) {
+    const bodyOpenMatch = BODY_OPEN_PATTERN.exec(output);
+    if (bodyOpenMatch && bodyOpenMatch.index !== undefined) {
+      const bodyEnd = bodyOpenMatch.index + bodyOpenMatch[0].length;
+      output =
+        output.slice(0, bodyEnd) + injection.body + output.slice(bodyEnd);
+    }
+  }
+
+  return output;
 }
 
-export function wrapWithAnalytics(body: ReadableStream): ReadableStream {
-  const scripts = [getGaScript()].filter(Boolean).join("");
-  if (!scripts) return body;
+export function wrapWithAnalytics(
+  body: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  const injection = getAnalyticsInjection();
+  if (!injection) return body;
 
   const decoder = new TextDecoder();
   const encoder = new TextEncoder();
-  let injected = false;
+  let pending = "";
+  let headInjected = false;
+  let bodyInjected = !injection.body;
 
   return body.pipeThrough(
-    new TransformStream({
+    new TransformStream<Uint8Array, Uint8Array>({
       transform(chunk, controller) {
-        if (injected) {
-          controller.enqueue(chunk);
-          return;
+        pending += decoder.decode(chunk, { stream: true });
+
+        if (!headInjected) {
+          const headCloseMatch = HEAD_CLOSE_PATTERN.exec(pending);
+          if (!headCloseMatch || headCloseMatch.index === undefined) return;
+
+          const headEnd = headCloseMatch.index + headCloseMatch[0].length;
+          controller.enqueue(
+            encoder.encode(
+              pending.slice(0, headCloseMatch.index) +
+                injection.head +
+                pending.slice(headCloseMatch.index, headEnd),
+            ),
+          );
+          pending = pending.slice(headEnd);
+          headInjected = true;
         }
-        const text = decoder.decode(chunk, { stream: true });
-        const headCloseIdx = text.indexOf("</head>");
-        if (headCloseIdx !== -1) {
-          const modified =
-            text.slice(0, headCloseIdx) + scripts + text.slice(headCloseIdx);
-          controller.enqueue(encoder.encode(modified));
-          injected = true;
-        } else {
-          controller.enqueue(chunk);
+
+        if (!bodyInjected) {
+          const bodyOpenMatch = BODY_OPEN_PATTERN.exec(pending);
+          if (!bodyOpenMatch || bodyOpenMatch.index === undefined) return;
+
+          const bodyEnd = bodyOpenMatch.index + bodyOpenMatch[0].length;
+          controller.enqueue(
+            encoder.encode(pending.slice(0, bodyEnd) + injection.body),
+          );
+          pending = pending.slice(bodyEnd);
+          bodyInjected = true;
         }
+
+        if (pending) {
+          controller.enqueue(encoder.encode(pending));
+          pending = "";
+        }
+      },
+      flush(controller) {
+        pending += decoder.decode();
+
+        if (!headInjected) {
+          const headCloseMatch = HEAD_CLOSE_PATTERN.exec(pending);
+          if (headCloseMatch && headCloseMatch.index !== undefined) {
+            const headEnd = headCloseMatch.index + headCloseMatch[0].length;
+            controller.enqueue(
+              encoder.encode(
+                pending.slice(0, headCloseMatch.index) +
+                  injection.head +
+                  pending.slice(headCloseMatch.index, headEnd),
+              ),
+            );
+            pending = pending.slice(headEnd);
+            headInjected = true;
+          }
+        }
+
+        if (headInjected && !bodyInjected) {
+          const bodyOpenMatch = BODY_OPEN_PATTERN.exec(pending);
+          if (bodyOpenMatch && bodyOpenMatch.index !== undefined) {
+            const bodyEnd = bodyOpenMatch.index + bodyOpenMatch[0].length;
+            controller.enqueue(
+              encoder.encode(pending.slice(0, bodyEnd) + injection.body),
+            );
+            pending = pending.slice(bodyEnd);
+            bodyInjected = true;
+          }
+        }
+
+        if (pending) controller.enqueue(encoder.encode(pending));
       },
     }),
   );

package/src/templates/chat/app/components/layout/Sidebar.tsx

@@ -4,7 +4,6 @@ import {
   type ChatThreadSummary,
 } from "@agent-native/core/client/agent-chat";
 import { appPath } from "@agent-native/core/client/api-path";
-import { ExtensionsSidebarSection } from "@agent-native/core/client/extensions";
 import { useT } from "@agent-native/core/client/i18n";
 import { OrgSwitcher } from "@agent-native/core/client/org";
 import { FeedbackButton } from "@agent-native/core/client/ui";
@@ -38,6 +37,9 @@ const navItems = [
     href: "/",
     view: "chat",
   },
+];
+
+const bottomNavItems = [
   {
     icon: IconHierarchy2,
     labelKey: "settings.agentTitle",
@@ -419,11 +421,38 @@ export function Sidebar({
       </nav>
 
       <div className={cn("mt-auto shrink-0", collapsed && "py-2")}>
-        {!collapsed ? (
-          <div className="px-2 py-1">
-            <ExtensionsSidebarSection />
-          </div>
-        ) : null}
+        <nav
+          className={cn(
+            "grid",
+            collapsed ? "gap-0 px-1 py-1" : "gap-1 px-2 py-1",
+          )}
+        >
+          {bottomNavItems.map((item) => {
+            const Icon = item.icon;
+            const isActive = location.pathname.startsWith(item.href);
+            const link = (
+              <Link
+                to={item.href}
+                className={navClass({ isActive })}
+                aria-current={isActive ? "page" : undefined}
+                aria-label={collapsed ? t(item.labelKey) : undefined}
+              >
+                <Icon className="size-4 shrink-0" />
+                <span className={collapsed ? "sr-only" : "truncate"}>
+                  {t(item.labelKey)}
+                </span>
+              </Link>
+            );
+            return collapsed ? (
+              <Tooltip key={item.href}>
+                <TooltipTrigger asChild>{link}</TooltipTrigger>
+                <TooltipContent side="right">{t(item.labelKey)}</TooltipContent>
+              </Tooltip>
+            ) : (
+              <div key={item.href}>{link}</div>
+            );
+          })}
+        </nav>
 
         <div className={cn(collapsed ? "px-1 py-1" : "px-3 py-2")}>
           <OrgSwitcher

package/src/templates/chat/app/routes/extensions._index.tsx

@@ -1,4 +1,4 @@
-import { ExtensionsListPage } from "@agent-native/core/client/extensions";
+import { Navigate } from "react-router";
 
 import { APP_TITLE } from "@/lib/app-config";
 
@@ -7,5 +7,5 @@ export function meta() {
 }
 
 export default function ExtensionsRoute() {
-  return <ExtensionsListPage />;
+  return <Navigate to="/settings#extensions" replace />;
 }

package/src/templates/chat/netlify.toml

@@ -6,5 +6,6 @@ functions = "templates/chat/.netlify/functions-internal"
 
 [build.environment]
 GA_MEASUREMENT_ID = "G-ESF7FYXGN9"
+GTM_CONTAINER_ID = "GTM-N3WSTXZ"
 NITRO_PRESET = "netlify"
 NPM_CONFIG_PRODUCTION = "false"

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

@@ -76,6 +76,22 @@ Full source-code customization is a core Agent Native capability. Extensions
 are the fast, sandboxed, no-deploy layer—not the limit of what the app can
 become.
 
+Use this decision rule when either path could solve the request:
+
+- Start with an extension for a self-contained, relatively one-off widget,
+  custom visualization or interaction, dashboard tile, standalone utility, or
+  add-on in an existing slot.
+- Use app code for a core template feature, native UI/layout/routes/business
+  logic, a new slot, or behavior that should be reused broadly across dashboards
+  or users.
+- If the same extension keeps getting rebuilt, promote it into app code as one
+  reusable native feature instead of maintaining copies.
+
+As a rule of thumb, if an extension can solve the problem, generally start
+there. An isolated custom dashboard visualization belongs in an extension; a
+new chart type that should be available across dashboards belongs in the
+template code.
+
 **When a user asks to "make an extension", "create an extension", or "build
 a ... extension" (or the older phrasings "make a tool" / "create a tool"):**
 

package/src/vite/client.ts

@@ -3066,6 +3066,12 @@ function createAgentNativeConfig(
       "process.env.AGENT_NATIVE_BUILD_GA_MEASUREMENT_ID": JSON.stringify(
         process.env.GA_MEASUREMENT_ID?.trim() || "",
       ),
+      __AGENT_NATIVE_BUILD_GTM_CONTAINER_ID__: JSON.stringify(
+        process.env.GTM_CONTAINER_ID?.trim() || "",
+      ),
+      "process.env.AGENT_NATIVE_BUILD_GTM_CONTAINER_ID": JSON.stringify(
+        process.env.GTM_CONTAINER_ID?.trim() || "",
+      ),
       // Framework route warmup controls how SSR `.data` routes are fetched:
       // ordinary fetches keep them CDN-cacheable, while native prefetch headers
       // can be refused before the CDN/origin sees the request. Keep this value