@agent-native/core 0.207.0-nightly-20261011124220 → 0.207.0

package/dist/resources/store.js

@@ -982,36 +982,31 @@ async function _doEnsureTable() {
             now,
         ],
     });
-    try {
-        const { getBuiltinAgentsForSeeding } = await import("../server/agent-discovery.js");
-        const builtins = getBuiltinAgentsForSeeding();
-        for (const agent of builtins) {
-            const agentJson = JSON.stringify({
-                id: agent.id,
-                name: agent.name,
-                description: agent.description,
-                url: agent.url, // always prod
-                color: agent.color,
-            }, null, 2);
-            assertResourcePayloadIsSqlSafe(agentJson, "application/json");
-            const agentSize = Buffer.byteLength(agentJson, "utf8");
-            await client.execute({
-                sql: seedSql,
-                args: [
-                    crypto.randomUUID(),
-                    `remote-agents/${agent.id}.json`,
-                    SHARED_OWNER,
-                    agentJson,
-                    "application/json",
-                    agentSize,
-                    now,
-                    now,
-                ],
-            });
-        }
-    }
-    catch {
-        // Agent discovery not available — skip seeding
+    const { getBuiltinAgentsForSeeding } = await import("../server/agent-discovery.js");
+    const builtins = getBuiltinAgentsForSeeding();
+    for (const agent of builtins) {
+        const agentJson = JSON.stringify({
+            id: agent.id,
+            name: agent.name,
+            description: agent.description,
+            url: agent.url, // always prod
+            color: agent.color,
+        }, null, 2);
+        assertResourcePayloadIsSqlSafe(agentJson, "application/json");
+        const agentSize = Buffer.byteLength(agentJson, "utf8");
+        await client.execute({
+            sql: seedSql,
+            args: [
+                crypto.randomUUID(),
+                `remote-agents/${agent.id}.json`,
+                SHARED_OWNER,
+                agentJson,
+                "application/json",
+                agentSize,
+                now,
+                now,
+            ],
+        });
     }
     try {
         const legacy = await client.execute({

package/dist/server/agent-discovery.js

@@ -6,7 +6,7 @@ import { HIDDEN_FIRST_PARTY_AGENT_IDS, isBuiltinAgentCatalogId, normalizeAgentId
 import { DEFAULT_WORKSPACE_APP_AUDIENCE, normalizeWorkspaceAppAudience, normalizeWorkspaceAppHomePath, normalizeWorkspaceAppPathList, workspaceAppAudienceFromPackageJson, workspaceAppRouteAccessFromPackageJson, } from "../shared/workspace-app-audience.js";
 import { inferWorkspaceAppRootHomePath, readConfiguredWorkspaceAppHomePath, } from "../workspace-app-config.js";
 import { resolveAppRuntimeUrl } from "./app-url.js";
-import { readBuiltinAgentsConfig } from "./builtin-agents.js";
+import { readBuiltinAgentsConfig, } from "./builtin-agents.js";
 import { getRequestContext, getRequestOrgId, getRequestUserEmail, } from "./request-context.js";
 import { findWorkspaceRoot, readJson } from "./workspace-root.js";
 export { isBuiltinAgentCatalogId, normalizeAgentId };
@@ -199,23 +199,57 @@ export function shouldIncludeRemoteAgentManifest(manifest, selfAppId) {
     }
     return !HIDDEN_FIRST_PARTY_AGENT_IDS.has(normalizedId);
 }
-function builtinAgentsFor(ids, selfAppId, options) {
+function builtinAgentsFor(config, selfAppId, options) {
     const normalizedSelfAppId = selfAppId ? normalizeAgentId(selfAppId) : "";
-    return BUILTIN_AGENT_CATALOG.filter((app) => ids.includes(app.id) && app.id !== normalizedSelfAppId && app.url).map((app) => ({
+    const useLocalUrls = options?.preferLocalUrls === true || shouldUseLocalAgentUrls();
+    return BUILTIN_AGENT_CATALOG.filter((app) => config.include.includes(app.id) &&
+        app.id !== normalizedSelfAppId &&
+        app.url).map((app) => ({
         id: app.id,
         name: app.name,
         description: app.description,
-        url: resolveAgentUrl(app, options?.preferLocalUrls),
+        url: !useLocalUrls && config.urls?.[app.id]
+            ? config.urls[app.id]
+            : resolveAgentUrl(app, options?.preferLocalUrls),
         color: app.color,
     }));
 }
 /** Built-ins the workspace builder offers (`agent-native.builtinAgents`). */
 export function getBuiltinAgents(selfAppId, options) {
-    return builtinAgentsFor(readBuiltinAgentsConfig().include, selfAppId, options);
+    return builtinAgentsFor(readBuiltinAgentsConfig(), selfAppId, options);
 }
 function isUnofferedBuiltinManifest(manifestId, offeredBuiltinIds) {
     return (isBuiltinAgentCatalogId(manifestId) && !offeredBuiltinIds.has(manifestId));
 }
+function resolveRemoteAgentManifestUrl(manifestId, rawManifestId, manifestUrl, builtin, options) {
+    const catalogBuiltin = BUILTIN_AGENT_CATALOG.find((candidate) => candidate.id === manifestId);
+    const hosted = isHostedRuntime();
+    let url = manifestUrl;
+    if (hosted && isLoopbackUrl(url)) {
+        if (builtin?.url)
+            url = builtin.url;
+        else
+            return undefined;
+    }
+    if (catalogBuiltin && builtin && manifestUrl === catalogBuiltin.url) {
+        url = builtin.url;
+    }
+    if (options?.preferLocalUrls && builtin && catalogBuiltin) {
+        url = builtin.url;
+    }
+    const isLegacyAssetsManifest = rawManifestId.trim().toLowerCase() !== manifestId;
+    if (isLegacyAssetsManifest && builtin?.url) {
+        try {
+            if (new URL(url).hostname === "images.agent-native.com") {
+                url = builtin.url;
+            }
+        }
+        catch {
+            url = builtin.url;
+        }
+    }
+    return { url, isLegacyAssetsManifest };
+}
 export async function discoverAgents(selfAppId, options) {
     const builtins = getBuiltinAgents(selfAppId, options);
     const offeredBuiltinIds = new Set(builtins.map((agent) => agent.id));
@@ -281,32 +315,11 @@ export async function discoverAgents(selfAppId, options) {
                 const manifestId = normalizeAgentId(manifest.id);
                 if (isUnofferedBuiltinManifest(manifestId, offeredBuiltinIds))
                     continue;
-                let url = manifest.url;
-                const isHosted = isHostedRuntime();
-                if (isHosted && typeof url === "string" && isLoopbackUrl(url)) {
-                    const builtin = agentsById.get(manifestId);
-                    if (builtin?.url)
-                        url = builtin.url;
-                    else
-                        continue;
-                }
                 const builtin = agentsById.get(manifestId);
-                if (options?.preferLocalUrls && builtin) {
-                    const isBuiltinAgent = BUILTIN_AGENT_CATALOG.some((candidate) => candidate.id === manifestId);
-                    if (isBuiltinAgent)
-                        url = builtin.url;
-                }
-                const isLegacyAssetsManifest = manifest.id.trim().toLowerCase() !== manifestId;
-                if (isLegacyAssetsManifest && builtin?.url) {
-                    try {
-                        if (new URL(url).hostname === "images.agent-native.com") {
-                            url = builtin.url;
-                        }
-                    }
-                    catch {
-                        url = builtin.url;
-                    }
-                }
+                const resolved = resolveRemoteAgentManifestUrl(manifestId, manifest.id, manifest.url, builtin, options);
+                if (!resolved)
+                    continue;
+                const { url, isLegacyAssetsManifest } = resolved;
                 agentsById.set(manifestId, {
                     id: manifestId,
                     name: isLegacyAssetsManifest && builtin?.name
@@ -414,30 +427,11 @@ async function overlayRemoteAgentResources(agentsById, offeredBuiltinIds, resour
         const manifestId = normalizeAgentId(manifest.id);
         if (isUnofferedBuiltinManifest(manifestId, offeredBuiltinIds))
             continue;
-        let url = manifest.url;
         const builtin = agentsById.get(manifestId);
-        if (isHostedRuntime() && isLoopbackUrl(url)) {
-            if (builtin?.url)
-                url = builtin.url;
-            else
-                continue;
-        }
-        if (options?.preferLocalUrls &&
-            builtin &&
-            BUILTIN_AGENT_CATALOG.some((candidate) => candidate.id === manifestId)) {
-            url = builtin.url;
-        }
-        const isLegacyAssetsManifest = manifest.id.trim().toLowerCase() !== manifestId;
-        if (isLegacyAssetsManifest && builtin?.url) {
-            try {
-                if (new URL(url).hostname === "images.agent-native.com") {
-                    url = builtin.url;
-                }
-            }
-            catch {
-                url = builtin.url;
-            }
-        }
+        const resolved = resolveRemoteAgentManifestUrl(manifestId, manifest.id, manifest.url, builtin, options);
+        if (!resolved)
+            continue;
+        const { url, isLegacyAssetsManifest } = resolved;
         agentsById.set(manifestId, {
             id: manifestId,
             name: isLegacyAssetsManifest && builtin?.name ? builtin.name : manifest.name,

package/dist/server/agent-engine-api-key-route.d.ts

@@ -66,6 +66,7 @@ export declare function createAgentEngineApiKeyHandler(): import("h3").EventHand
     error: any;
     code: any;
 } | {
+    error?: undefined;
     errorCode?: undefined;
     code?: undefined;
     ok: boolean;
@@ -73,6 +74,5 @@ export declare function createAgentEngineApiKeyHandler(): import("h3").EventHand
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
     defaultModel?: import("./agent-engine-default-model-route.js").SavedKeyDefaultModelOutcome;
-    error?: undefined;
 }>>;
 export {};

package/dist/server/agent-engine-ollama-models-route.d.ts

@@ -1,9 +1,9 @@
 export declare function createAgentEngineOllamaModelsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    models?: undefined;
     ok?: undefined;
+    models?: undefined;
 } | {
+    error?: undefined;
     ok: boolean;
     models: string[];
-    error?: undefined;
 }>>;

package/dist/server/builtin-agents.d.ts

@@ -3,6 +3,8 @@ export interface BuiltinAgentsConfig {
     mode: BuiltinAgentsMode;
     /** Built-ins this workspace offers. Anything else is unknown to it. */
     include: string[];
+    /** Hosted URL overrides, applied only when a built-in is offered. */
+    urls?: Record<string, string>;
 }
 export declare const BUILTIN_AGENTS_ENV_KEY = "AGENT_NATIVE_BUILTIN_AGENTS_JSON";
 export declare function frameworkDefaultBuiltinAgentsConfig(): BuiltinAgentsConfig;

package/dist/server/builtin-agents.js

@@ -32,6 +32,48 @@ function parseIdList(value, field, warnings) {
     }
     return ids;
 }
+function parseBuiltinAgentUrls(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("builtinAgents.urls must be an object mapping built-in ids to URLs");
+    }
+    const urls = {};
+    const seenIds = new Set();
+    for (const [rawId, rawUrl] of Object.entries(value)) {
+        const id = normalizeAgentId(rawId);
+        if (!BUILTIN_AGENT_CATALOG_IDS.includes(id)) {
+            throw new Error("builtinAgents.urls contains an unknown built-in agent id");
+        }
+        if (seenIds.has(id)) {
+            throw new Error("builtinAgents.urls contains duplicate built-in agent ids");
+        }
+        seenIds.add(id);
+        if (typeof rawUrl !== "string" || rawUrl.trim() !== rawUrl) {
+            throw new Error("builtinAgents.urls values must be absolute HTTPS URLs without credentials, query, or fragment");
+        }
+        let url;
+        try {
+            url = new URL(rawUrl);
+        }
+        catch {
+            throw new Error("builtinAgents.urls values must be absolute HTTPS URLs without credentials, query, or fragment");
+        }
+        if (/[\s\p{Cc}]/u.test(rawUrl) ||
+            !/^https:\/\//i.test(rawUrl) ||
+            url.protocol !== "https:" ||
+            !url.hostname ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            /[?#]/.test(rawUrl)) {
+            throw new Error("builtinAgents.urls values must be absolute HTTPS URLs without credentials, query, or fragment");
+        }
+        urls[id] = rawUrl;
+    }
+    return urls;
+}
 export function parseBuiltinAgentsConfig(raw) {
     const warnings = [];
     if (raw === undefined || raw === null) {
@@ -42,13 +84,18 @@ export function parseBuiltinAgentsConfig(raw) {
         return { config: frameworkDefaultBuiltinAgentsConfig(), warnings };
     }
     const record = raw;
+    const urls = parseBuiltinAgentUrls(record.urls);
+    const urlsConfig = urls === undefined ? {} : { urls };
     const mode = record.mode ?? "all";
     if (mode !== "all" && mode !== "none" && mode !== "selected") {
         warnings.push(`builtinAgents.mode must be "all", "none", or "selected"; using the default`);
-        return { config: frameworkDefaultBuiltinAgentsConfig(), warnings };
+        return {
+            config: { ...frameworkDefaultBuiltinAgentsConfig(), ...urlsConfig },
+            warnings,
+        };
     }
     if (mode === "none") {
-        return { config: { mode, include: [] }, warnings };
+        return { config: { mode, include: [], ...urlsConfig }, warnings };
     }
     let include;
     if (mode === "all") {
@@ -64,7 +111,7 @@ export function parseBuiltinAgentsConfig(raw) {
         include =
             parseIdList(record.include, "builtinAgents.include", warnings) ?? [];
     }
-    return { config: { mode, include }, warnings };
+    return { config: { mode, include, ...urlsConfig }, warnings };
 }
 function readRawBuiltinAgentsConfig() {
     const envJson = getAppConfig().workspace.builtinAgentsJson;

package/dist/server/credential-provider.d.ts

@@ -38,18 +38,15 @@ export declare function assertCredentialStoreReadable(result: {
     cause?: unknown;
 }): void;
 /**
- * Deployment-level credential fallback for single-tenant/local operation.
- * Multi-tenant call sites must gate this explicitly before calling.
+ * Read deployment-owned configuration. LLM provider keys have an app-wide
+ * fallback policy; user and workspace credentials must use scoped resolvers.
  */
 export declare function readDeployCredentialEnv(key: string): string | undefined;
 /**
- * Deployment-level credentials are safe as a runtime fallback only in local /
- * single-tenant contexts. In hosted production with a shared database, every
- * signed-in user needs their own user/org/workspace credential for provider
- * keys. Model-provider env keys are never shared with hosted users because
- * they bill the app owner. Other app-provided service credentials configure
- * the deployed app itself, such as email transport and OAuth client
- * credentials whose per-user identity remains in scoped OAuth tokens.
+ * Legacy deployment-level credential policy for non-provider call sites.
+ * Model-provider env keys use `canUseDeployCredentialFallbackForRequest()` so
+ * self-hosted apps and local PGlite development can share an app-owned
+ * inference key.
  *
  * @deprecated Use `canUseDeployCredentialFallbackForRequest()` for generic
  * provider secrets. This stricter helper remains for legacy call sites with

package/dist/server/credential-provider.js

@@ -96,23 +96,27 @@ export function assertCredentialStoreReadable(result) {
     }
 }
 /**
- * Deployment-level credential fallback for single-tenant/local operation.
- * Multi-tenant call sites must gate this explicitly before calling.
+ * Read deployment-owned configuration. LLM provider keys have an app-wide
+ * fallback policy; user and workspace credentials must use scoped resolvers.
  */
 export function readDeployCredentialEnv(key) {
-    if (HOSTED_MODEL_PROVIDER_ENV_KEYS.has(key) &&
+    if (key === "GOOGLE_APPLICATION_CREDENTIALS" &&
+        (getRequestContext()?.isSyntheticTraffic === true ||
+            isHostedWorkspaceRuntime() ||
+            !isDeployCredentialFallbackAllowed())) {
+        return undefined;
+    }
+    if ((DEPLOY_LLM_PROVIDER_ENV_KEYS.has(key) ||
+        BUILDER_CREDITS_DEPLOY_ENV_KEYS.has(key)) &&
         !canUseDeployCredentialFallbackForRequest(key)) {
         return undefined;
     }
     return process.env[key] || undefined;
 }
-const HOSTED_MODEL_PROVIDER_ENV_KEYS = new Set([
+const DEPLOY_LLM_PROVIDER_ENV_KEYS = new Set([
     "ANTHROPIC_API_KEY",
-    "BUILDER_GATEWAY_SPACE_ID",
-    "BUILDER_GATEWAY_TOKEN",
     "COHERE_API_KEY",
     "GEMINI_API_KEY",
-    "GOOGLE_APPLICATION_CREDENTIALS",
     "GOOGLE_GENERATIVE_AI_API_KEY",
     "GROQ_API_KEY",
     "JEV_API_KEY",
@@ -122,6 +126,10 @@ const HOSTED_MODEL_PROVIDER_ENV_KEYS = new Set([
     "TYPESAFE_API_KEY",
     "VOYAGE_API_KEY",
 ]);
+const BUILDER_CREDITS_DEPLOY_ENV_KEYS = new Set([
+    "BUILDER_GATEWAY_SPACE_ID",
+    "BUILDER_GATEWAY_TOKEN",
+]);
 const APP_PROVIDED_DEPLOY_CREDENTIAL_KEYS = new Set([
     "EMAIL_FROM",
     "EMAIL_INBOUND_WEBHOOK_SECRET",
@@ -142,13 +150,10 @@ function isAppProvidedDeployCredentialKey(key) {
     return !!key && APP_PROVIDED_DEPLOY_CREDENTIAL_KEYS.has(key);
 }
 /**
- * Deployment-level credentials are safe as a runtime fallback only in local /
- * single-tenant contexts. In hosted production with a shared database, every
- * signed-in user needs their own user/org/workspace credential for provider
- * keys. Model-provider env keys are never shared with hosted users because
- * they bill the app owner. Other app-provided service credentials configure
- * the deployed app itself, such as email transport and OAuth client
- * credentials whose per-user identity remains in scoped OAuth tokens.
+ * Legacy deployment-level credential policy for non-provider call sites.
+ * Model-provider env keys use `canUseDeployCredentialFallbackForRequest()` so
+ * self-hosted apps and local PGlite development can share an app-owned
+ * inference key.
  *
  * @deprecated Use `canUseDeployCredentialFallbackForRequest()` for generic
  * provider secrets. This stricter helper remains for legacy call sites with
@@ -160,16 +165,23 @@ export function isDeployCredentialFallbackAllowed() {
     return isLocalDatabase();
 }
 export function canUseDeployCredentialFallbackForRequest(key) {
+    const requestContext = getRequestContext();
     // Synthetic checks must never fall through to a deploy-wide provider key.
-    // If the dedicated test credential is rejected, using the site's shared key
-    // would make a green retry both misleading and billable to real traffic.
-    if (getRequestContext()?.isSyntheticTraffic === true)
+    // Anonymous public runs must not consume the deployment owner's key either.
+    if (requestContext?.isSyntheticTraffic === true ||
+        requestContext?.agentRunAnonymous === true) {
         return false;
-    if (key && HOSTED_MODEL_PROVIDER_ENV_KEYS.has(key)) {
-        if (isHostedWorkspaceRuntime())
-            return false;
-        if (isProductionLikeRuntime() && !isLocalDatabase())
+    }
+    if (key && BUILDER_CREDITS_DEPLOY_ENV_KEYS.has(key)) {
+        return isTrustedSelfHostedRuntime();
+    }
+    if (key && DEPLOY_LLM_PROVIDER_ENV_KEYS.has(key)) {
+        const hostedWorkspace = isHostedWorkspaceRuntime();
+        if (hostedWorkspace && isProductionLikeRuntime())
             return false;
+        if (isLocalDatabase())
+            return true;
+        return !hostedWorkspace;
     }
     const email = getRequestUserEmail();
     if (!email)

package/dist/templates/builder-code-starter/.agents/skills/adding-a-feature/SKILL.md.patch

@@ -1,7 +1,7 @@
 ===================================================================
 --- a/.agents/skills/adding-a-feature/SKILL.md
 +++ b/.agents/skills/adding-a-feature/SKILL.md
-@@ -129,11 +129,12 @@
+@@ -131,11 +131,12 @@
  Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
  placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
  real keys, internal data, or customer data into instructions as examples.

package/dist/templates/builder-code-starter/AGENTS.md.patch

@@ -5,7 +5,7 @@
 -# Chat — Agent Guide
 +# App — Agent Guide
  
--Chat is the minimal chat-first agent-native app. `/` redirects to shared sign-in; authenticated chat starts at `/home`. Actions carry capabilities; screens exist only for durable workflows.
+-Chat is the minimal chat-first agent-native app. `/` redirects to shared sign-in, then `/home`, the editable Get started page. Chat lives at `/chat`; new chats start there. Actions carry capabilities; screens exist only for durable workflows.
 +This starter ships as a blank Agent-Native app canvas — that describes its
 +initial state, not necessarily its current one. See `DEVELOPING.md` before
 +making any source code change.
@@ -30,7 +30,7 @@
  
  ## Application state
  
--- `navigation` describes the view and selected ids. Chat is `chat` at `/home`; `/` opens shared sign-in/signup.
+-- `navigation` describes the view and selected ids. Chat is `chat` at `/chat` and `/chat/<threadId>`; the Get started page is `home` at `/home`; `/` opens shared sign-in/signup.
 +- `navigation` describes the view and selected ids. The default home view is
 +  `home` at `/` (blank app canvas). No agent rail or chat is mounted by
 +  default; add one only when the user asks.
@@ -38,7 +38,7 @@
  
  ## Building a domain app
  
--Choose the primary workflow and route before editing. Add a domain route under `app/routes/` and set `app.homePath` in `server/plugins/agent-native-email-branding.ts` with `defineAppConfig`. Keep `/home` as Chat. Add a static link in `app/components/layout/Sidebar.tsx` before `ChatThreadsSection`; `Header.tsx` maps `/home` to Chat and uses `APP_TITLE` elsewhere. Shared sidebar and AgentInspector remain.
+-Choose the primary workflow and route before editing. Add a domain route under `app/routes/` and set `app.homePath` in `server/plugins/agent-native-email-branding.ts` with `defineAppConfig`. The default Get started page lives at `/home`, and Chat stays at `/chat`; edit `app/routes/home.tsx` when replacing that page with a domain-specific home. Add a static link in `app/components/layout/Sidebar.tsx` before `ChatThreadsSection`; `Header.tsx` uses `APP_TITLE` elsewhere. Shared sidebar and AgentInspector remain.
 +Choose the primary workflow and route before editing. Build on the blank canvas in `app/routes/_index.tsx` or add domain routes under `app/routes/`. This starter has no Chat route, sidebar, header, or agent rail; add only the navigation the product needs. Set `app.homePath` in the existing `defineAppConfig` in `server/plugins/config.ts` as `DEVELOPING.md` describes.
  
 -Use `adding-a-feature` for functional parity and `frontend-design` for a user-facing screen. Keep feature guidance here; do not rewrite `README.md` or `DESIGN.md`. After all edits, run one typecheck, one doctor check, and one browser smoke of the primary workflow, including overlap rejection, cancellation freeing the slot, and authenticated landing. Skip production build and extra test suites.

package/dist/templates/builder-code-starter/app/components/layout/Layout.tsx.patch

@@ -1,7 +1,7 @@
 ===================================================================
 --- a/app/components/layout/Layout.tsx
 +++ b/app/components/layout/Layout.tsx
-@@ -1,189 +1,28 @@
+@@ -1,188 +1,28 @@
 -import { useT } from "@agent-native/core/client/i18n";
 -import { HeaderActionsProvider } from "@agent-native/toolkit/app-shell/header-actions";
 -import {
@@ -23,6 +23,7 @@
 -  SheetTitle,
 -} from "@/components/ui/sheet";
 -import { APP_TITLE } from "@/lib/app-config";
+-import { HOME_PATH, isChatPathname } from "@/lib/chat-paths";
 -
 -import { Sidebar } from "./Sidebar";
 -
@@ -43,8 +44,8 @@
 -
 -function routeOwnsToolbar(pathname: string): boolean {
 -  return (
--    pathname === "/home" ||
--    pathname.startsWith("/chat/") ||
+-    pathname === HOME_PATH ||
+-    isChatPathname(pathname) ||
 -    pathname === "/database" ||
 -    pathname.startsWith("/extensions")
 -  );
@@ -66,8 +67,7 @@
 -  const t = useT();
 -  const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
 -  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
--  const isChatRoute =
--    location.pathname === "/home" || location.pathname.startsWith("/chat/");
+-  const isChatRoute = isChatPathname(location.pathname);
 -  // Settings brings its own navigation, header, and agent toggle, so it
 -  // renders full width.
 -  const settingsOwnsChrome = isSettingsPathname(location.pathname);
@@ -79,8 +79,7 @@
 -  const chatHomeHandoffPending = isAgentChatHomeHandoffActive("chat");
 -  useAgentChatHomeHandoffLinks({
 -    storageKey: "chat",
--    isChatPath: (pathname) =>
--      pathname === "/home" || pathname.startsWith("/chat/"),
+-    isChatPath: isChatPathname,
 -    requireActiveHandoff: true,
 -  });
 -

package/dist/templates/builder-code-starter/app/hooks/use-navigation-state.ts.patch

@@ -1,7 +1,18 @@
 ===================================================================
 --- a/app/hooks/use-navigation-state.ts
 +++ b/app/hooks/use-navigation-state.ts
-@@ -5,83 +5,37 @@
+@@ -1,85 +1,41 @@
+ import { appBasePath, appPath } from "@agent-native/core/client/api-path";
+ import { useAgentRouteState } from "@agent-native/core/client/navigation";
+ 
+-import {
+-  chatThreadPath,
+-  HOME_PATH,
+-  isChatPathname,
+-  NEW_CHAT_PATH,
+-  threadIdFromPath,
+-} from "@/lib/chat-paths";
+ import { TAB_ID } from "@/lib/tab-id";
  
  export interface NavigationState {
    view: string;
@@ -31,19 +42,9 @@
    });
  }
  
--function threadIdFromPath(pathname: string): string | null {
--  const match = pathname.match(/^\/chat\/([^/]+)/);
--  if (!match) return null;
--  try {
--    const value = decodeURIComponent(match[1]).trim();
--    return value || null;
--  } catch {
--    return null;
--  }
--}
--
  function viewForPath(pathname: string): string {
--  if (isChatPath(pathname)) return "chat";
+-  if (isChatPathname(pathname)) return "chat";
+-  if (pathname === HOME_PATH) return "home";
 -  if (pathname.startsWith("/database")) return "database";
 -  if (pathname.startsWith("/extensions")) return "extensions";
 -  if (pathname.startsWith("/observability")) return "observability";
@@ -60,9 +61,10 @@
  function pathForView(view?: string): string {
    switch (view) {
 -    case "chat":
-     case "home":
 -    case "ask":
--      return "/home";
+-      return NEW_CHAT_PATH;
+     case "home":
+-      return HOME_PATH;
 -    case "database":
 -      return "/database";
 -    case "extensions":
@@ -77,29 +79,20 @@
 -      return "/settings/organization";
 +      return "/";
      default:
--      return "/home";
+-      return HOME_PATH;
 +      return "/";
    }
  }
  
--function pathForCommand(command: any): string {
+-export function pathForCommand(command: any): string {
 -  const path = pathForView(command?.view);
--  if (path !== "/home") return path;
+-  if (command?.view !== "chat" && command?.view !== "ask") return path;
 -  const threadId =
 -    typeof command?.threadId === "string" ? command.threadId.trim() : "";
--  return threadId ? `/chat/${encodeURIComponent(threadId)}` : path;
+-  return threadId ? chatThreadPath(threadId) : path;
 -}
 -
  function routerPath(path: string): string {
    const basePath = appBasePath();
    if (!basePath) return path;
    if (path === basePath) return "/";
-@@ -89,8 +43,4 @@
-     return path.slice(basePath.length) || "/";
-   }
-   return path;
- }
--
--function isChatPath(pathname: string): boolean {
--  return pathname === "/home" || pathname.startsWith("/chat/");
--}