@agent-native/core 0.12.14 → 0.12.16

package/dist/templates/default/AGENTS.md

@@ -50,6 +50,12 @@ Ephemeral UI state is stored in the SQL `application_state` table, accessed via
 
 The `navigation` key is written by the UI whenever the route changes. The `navigate` key is a one-shot command: the agent writes it, the UI reads and executes the navigation, then deletes it.
 
+## Mounted Workspace Routing
+
+This app may be mounted under `/<app-id>` in a workspace. Inside app source, React Router paths are app-local: use `<Link to="/review">` and `navigate("/review")`, not `/<app-id>/review`. The workspace gateway and `APP_BASE_PATH` add the mounted prefix in the browser; hardcoding it inside React Router links causes doubled URLs such as `/<app-id>/<app-id>/review`.
+
+For raw paths outside React Router, use the core helpers: `appPath()` for static assets or normal hrefs, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+
 ## Agent Operations
 
 **Always know what the user is currently viewing before you edit anything.** The user's view can change mid-conversation. Stale IDs lead to editing the wrong record.
@@ -101,7 +107,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 As you build out this app, follow this checklist for each new feature:
 
-1. **Add navigation state entries** -- create or extend `app/hooks/use-navigation-state.ts` to track new routes
+1. **Add navigation state entries** -- extend `app/hooks/use-navigation-state.ts` to track new routes
 2. **Enhance view-screen** -- make the view-screen script return relevant context for the new view
 3. **Create domain actions** -- add scripts for CRUD operations on new data models
 4. **Create domain skills** -- add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations

package/dist/templates/default/DEVELOPING.md

@@ -20,6 +20,18 @@ app/routes/inbox.$threadId.tsx     → /inbox/:threadId
 app/routes/$id.tsx                 → /:id (dynamic param)
 ```
 
+## Mounted Workspace Routing
+
+In a workspace, this app can be mounted under `/<app-id>`. React Router already receives `APP_BASE_PATH`/`VITE_APP_BASE_PATH` through `appBasePath()`, so route code stays app-local:
+
+| Route file              | App-internal route | Mounted browser URL |
+| ----------------------- | ------------------ | ------------------- |
+| `app/routes/_index.tsx` | `/`                | `/<app-id>`         |
+| `app/routes/review.tsx` | `/review`          | `/<app-id>/review`  |
+| `app/routes/$id.tsx`    | `/:id`             | `/<app-id>/:id`     |
+
+Use `<Link to="/review">` and `navigate("/review")` inside this app. Do not prefix React Router paths with `/<app-id>` or the URL can double-prefix, e.g. `/<app-id>/<app-id>/review`. Use `appPath()` for raw `href`s/static assets, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+
 Each route file exports a default component and optional `meta()`:
 
 ```tsx

package/dist/templates/default/app/hooks/use-navigation-state.ts

@@ -0,0 +1,81 @@
+import { useEffect } from "react";
+import { useLocation, useNavigate } from "react-router";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  agentNativePath,
+  appBasePath,
+  appPath,
+} from "@agent-native/core/client";
+
+export interface NavigationState {
+  view: string;
+  path?: string;
+}
+
+export function useNavigationState() {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const qc = useQueryClient();
+
+  useEffect(() => {
+    const state: NavigationState = {
+      view: viewFromPath(location.pathname),
+      path: appPath(location.pathname),
+    };
+
+    fetch(agentNativePath("/_agent-native/application-state/navigation"), {
+      method: "PUT",
+      keepalive: true,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(state),
+    }).catch(() => {});
+  }, [location.pathname]);
+
+  const { data: navCommand } = useQuery({
+    queryKey: ["navigate-command"],
+    queryFn: async () => {
+      const res = await fetch(
+        agentNativePath("/_agent-native/application-state/navigate"),
+      );
+      if (!res.ok) return null;
+      const data = await res.json();
+      return data ? { ...data, _ts: Date.now() } : null;
+    },
+    refetchInterval: 2_000,
+    refetchIntervalInBackground: true,
+    structuralSharing: false,
+  });
+
+  useEffect(() => {
+    if (!navCommand) return;
+    fetch(agentNativePath("/_agent-native/application-state/navigate"), {
+      method: "DELETE",
+      headers: { "X-Agent-Native-CSRF": "1" },
+    }).catch(() => {});
+    const cmd = navCommand as NavigationState;
+
+    const path = routerPath(cmd.path || pathFromView(cmd.view));
+    navigate(path);
+    qc.setQueryData(["navigate-command"], null);
+  }, [navCommand, navigate, qc]);
+}
+
+function viewFromPath(pathname: string): string {
+  if (!pathname || pathname === "/") return "home";
+  return pathname.replace(/^\/+/, "") || "home";
+}
+
+function pathFromView(view: string | undefined): string {
+  if (!view || view === "home") return "/";
+  return `/${view.replace(/^\/+/, "")}`;
+}
+
+function routerPath(path: string): string {
+  const basePath = appBasePath();
+  if (!basePath) return path;
+  if (path === basePath) return "/";
+  if (path.startsWith(`${basePath}/`)) {
+    return path.slice(basePath.length) || "/";
+  }
+  return path;
+}

package/dist/templates/default/app/root.tsx

@@ -16,10 +16,15 @@ import {
 } from "@tanstack/react-query";
 import { ThemeProvider } from "next-themes";
 import { useDbSync } from "@agent-native/core";
-import { ClientOnly, DefaultSpinner } from "@agent-native/core/client";
-import { getThemeInitScript } from "@agent-native/core/client";
+import {
+  ClientOnly,
+  DefaultSpinner,
+  appPath,
+  getThemeInitScript,
+} from "@agent-native/core/client";
 import { Toaster } from "sonner";
 import { configureTracking } from "@agent-native/core/client";
+import { useNavigationState } from "./hooks/use-navigation-state";
 configureTracking({
   getDefaultProps: (_name, properties) => ({
     ...properties,
@@ -56,8 +61,8 @@ export function Layout({ children }: { children: React.ReactNode }) {
           suppressHydrationWarning
           dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }}
         />
-        <link rel="manifest" href="/manifest.json" />
-        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+        <link rel="manifest" href={appPath("/manifest.json")} />
+        <link rel="icon" type="image/svg+xml" href={appPath("/favicon.svg")} />
         <meta name="theme-color" content="#111111" />
         <meta name="mobile-web-app-capable" content="yes" />
         <meta
@@ -65,7 +70,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
           content="black-translucent"
         />
         <meta name="apple-mobile-web-app-title" content="App" />
-        <link rel="apple-touch-icon" href="/icon-180.svg" />
+        <link rel="apple-touch-icon" href={appPath("/icon-180.svg")} />
         <Meta />
         <Links />
       </head>
@@ -80,6 +85,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 
 function DbSyncSetup() {
   const qc = useQueryClient();
+  useNavigationState();
   useDbSync({ queryClient: qc, queryKeys: ["files", "data"] });
   return null;
 }

package/dist/templates/workspace-root/AGENTS.md

@@ -29,6 +29,19 @@ in `apps/<app>/AGENTS.md`; shared cross-app behavior belongs in
 - Do not satisfy a new-app request by adding a route, page, component, or file
   to `apps/starter` or another existing app unless the user explicitly asks to
   modify that existing app.
+- Treat first-party apps such as Mail, Calendar, Analytics, and Dispatch as
+  existing hosted/connected neighbors available through links and A2A/default
+  connected agents. For example, Mail, Calendar, and Analytics already exist at
+  `https://mail.agent-native.com`, `https://calendar.agent-native.com`, and
+  `https://analytics.agent-native.com`.
+- If a new app needs to use Mail, Calendar, Analytics, or similar first-party
+  data/agents, build only the genuinely new workflow and delegate/link to those
+  existing apps. Do not create wrapper apps, child apps, nested template copies,
+  or cloned Mail/Calendar/Analytics implementations inside the new app just to
+  provide access.
+- Only create a first-party app copy when the user explicitly asks for a
+  customized fork/copy of that app. Otherwise prefer the hosted/shared app so
+  base template improvements continue to flow automatically.
 - Workspace apps are discovered from `apps/<app-id>/package.json`. There is no
   separate workspace app registry to edit for Dispatch to list the app.
 - Use relative workspace links like `/<app-id>`. Never hardcode

package/dist/templates/workspace-root/README.md

@@ -84,6 +84,12 @@ separate workspace app registry to edit. React Router apps must preserve
 For requests phrased as creating an "agent", classify the scope first: simple
 recurring Dispatch behavior can stay in Dispatch, while a robust app-like
 teammate should become a real workspace app listed with the rest of the apps.
+First-party apps such as Mail, Calendar, Analytics, and Dispatch should be
+treated as existing hosted or connected neighbors. If a new app needs access to
+their data or agents, link/delegate to those apps through the workspace/A2A
+path rather than creating wrapper apps, child apps, or cloned template copies
+inside the new app. Only fork one of those apps when the user explicitly asks
+for a customized copy.
 
 ## Editing shared behavior
 

package/docs/content/multi-app-workspace.md

@@ -31,6 +31,8 @@ Anything every app in your org should agree on can live in `packages/shared`:
 
 Each individual app becomes _just a set of screens_ — routes, dashboards, views, domain-specific actions. Framework defaults cover the rest until you add a real workspace customization.
 
+That same boundary applies when your app wants to use another first-party app. A new workspace dashboard that needs email, calendar, and analytics context should use the existing Mail, Calendar, and Analytics apps as connected neighbors over links or A2A. It should not clone those templates, create a wrapper app that nests them, or scaffold child apps inside itself just to get access to their data or agents. For example, the hosted first-party apps already live at [mail.agent-native.com](https://mail.agent-native.com), [calendar.agent-native.com](https://calendar.agent-native.com), and [analytics.agent-native.com](https://analytics.agent-native.com). Fork or scaffold a copy only when you explicitly want to customize that app; otherwise, using the hosted/shared app keeps base template improvements flowing automatically.
+
 ## Getting started {#getting-started}
 
 Workspace is the default shape of an agent-native project. Scaffold one with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.12.14",
+  "version": "0.12.16",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",

package/src/templates/default/AGENTS.md

@@ -50,6 +50,12 @@ Ephemeral UI state is stored in the SQL `application_state` table, accessed via
 
 The `navigation` key is written by the UI whenever the route changes. The `navigate` key is a one-shot command: the agent writes it, the UI reads and executes the navigation, then deletes it.
 
+## Mounted Workspace Routing
+
+This app may be mounted under `/<app-id>` in a workspace. Inside app source, React Router paths are app-local: use `<Link to="/review">` and `navigate("/review")`, not `/<app-id>/review`. The workspace gateway and `APP_BASE_PATH` add the mounted prefix in the browser; hardcoding it inside React Router links causes doubled URLs such as `/<app-id>/<app-id>/review`.
+
+For raw paths outside React Router, use the core helpers: `appPath()` for static assets or normal hrefs, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+
 ## Agent Operations
 
 **Always know what the user is currently viewing before you edit anything.** The user's view can change mid-conversation. Stale IDs lead to editing the wrong record.
@@ -101,7 +107,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 As you build out this app, follow this checklist for each new feature:
 
-1. **Add navigation state entries** -- create or extend `app/hooks/use-navigation-state.ts` to track new routes
+1. **Add navigation state entries** -- extend `app/hooks/use-navigation-state.ts` to track new routes
 2. **Enhance view-screen** -- make the view-screen script return relevant context for the new view
 3. **Create domain actions** -- add scripts for CRUD operations on new data models
 4. **Create domain skills** -- add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations

package/src/templates/default/DEVELOPING.md

@@ -20,6 +20,18 @@ app/routes/inbox.$threadId.tsx     → /inbox/:threadId
 app/routes/$id.tsx                 → /:id (dynamic param)
 ```
 
+## Mounted Workspace Routing
+
+In a workspace, this app can be mounted under `/<app-id>`. React Router already receives `APP_BASE_PATH`/`VITE_APP_BASE_PATH` through `appBasePath()`, so route code stays app-local:
+
+| Route file              | App-internal route | Mounted browser URL |
+| ----------------------- | ------------------ | ------------------- |
+| `app/routes/_index.tsx` | `/`                | `/<app-id>`         |
+| `app/routes/review.tsx` | `/review`          | `/<app-id>/review`  |
+| `app/routes/$id.tsx`    | `/:id`             | `/<app-id>/:id`     |
+
+Use `<Link to="/review">` and `navigate("/review")` inside this app. Do not prefix React Router paths with `/<app-id>` or the URL can double-prefix, e.g. `/<app-id>/<app-id>/review`. Use `appPath()` for raw `href`s/static assets, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+
 Each route file exports a default component and optional `meta()`:
 
 ```tsx

package/src/templates/default/app/hooks/use-navigation-state.ts

@@ -0,0 +1,81 @@
+import { useEffect } from "react";
+import { useLocation, useNavigate } from "react-router";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  agentNativePath,
+  appBasePath,
+  appPath,
+} from "@agent-native/core/client";
+
+export interface NavigationState {
+  view: string;
+  path?: string;
+}
+
+export function useNavigationState() {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const qc = useQueryClient();
+
+  useEffect(() => {
+    const state: NavigationState = {
+      view: viewFromPath(location.pathname),
+      path: appPath(location.pathname),
+    };
+
+    fetch(agentNativePath("/_agent-native/application-state/navigation"), {
+      method: "PUT",
+      keepalive: true,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(state),
+    }).catch(() => {});
+  }, [location.pathname]);
+
+  const { data: navCommand } = useQuery({
+    queryKey: ["navigate-command"],
+    queryFn: async () => {
+      const res = await fetch(
+        agentNativePath("/_agent-native/application-state/navigate"),
+      );
+      if (!res.ok) return null;
+      const data = await res.json();
+      return data ? { ...data, _ts: Date.now() } : null;
+    },
+    refetchInterval: 2_000,
+    refetchIntervalInBackground: true,
+    structuralSharing: false,
+  });
+
+  useEffect(() => {
+    if (!navCommand) return;
+    fetch(agentNativePath("/_agent-native/application-state/navigate"), {
+      method: "DELETE",
+      headers: { "X-Agent-Native-CSRF": "1" },
+    }).catch(() => {});
+    const cmd = navCommand as NavigationState;
+
+    const path = routerPath(cmd.path || pathFromView(cmd.view));
+    navigate(path);
+    qc.setQueryData(["navigate-command"], null);
+  }, [navCommand, navigate, qc]);
+}
+
+function viewFromPath(pathname: string): string {
+  if (!pathname || pathname === "/") return "home";
+  return pathname.replace(/^\/+/, "") || "home";
+}
+
+function pathFromView(view: string | undefined): string {
+  if (!view || view === "home") return "/";
+  return `/${view.replace(/^\/+/, "")}`;
+}
+
+function routerPath(path: string): string {
+  const basePath = appBasePath();
+  if (!basePath) return path;
+  if (path === basePath) return "/";
+  if (path.startsWith(`${basePath}/`)) {
+    return path.slice(basePath.length) || "/";
+  }
+  return path;
+}

package/src/templates/default/app/root.tsx

@@ -16,10 +16,15 @@ import {
 } from "@tanstack/react-query";
 import { ThemeProvider } from "next-themes";
 import { useDbSync } from "@agent-native/core";
-import { ClientOnly, DefaultSpinner } from "@agent-native/core/client";
-import { getThemeInitScript } from "@agent-native/core/client";
+import {
+  ClientOnly,
+  DefaultSpinner,
+  appPath,
+  getThemeInitScript,
+} from "@agent-native/core/client";
 import { Toaster } from "sonner";
 import { configureTracking } from "@agent-native/core/client";
+import { useNavigationState } from "./hooks/use-navigation-state";
 configureTracking({
   getDefaultProps: (_name, properties) => ({
     ...properties,
@@ -56,8 +61,8 @@ export function Layout({ children }: { children: React.ReactNode }) {
           suppressHydrationWarning
           dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }}
         />
-        <link rel="manifest" href="/manifest.json" />
-        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+        <link rel="manifest" href={appPath("/manifest.json")} />
+        <link rel="icon" type="image/svg+xml" href={appPath("/favicon.svg")} />
         <meta name="theme-color" content="#111111" />
         <meta name="mobile-web-app-capable" content="yes" />
         <meta
@@ -65,7 +70,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
           content="black-translucent"
         />
         <meta name="apple-mobile-web-app-title" content="App" />
-        <link rel="apple-touch-icon" href="/icon-180.svg" />
+        <link rel="apple-touch-icon" href={appPath("/icon-180.svg")} />
         <Meta />
         <Links />
       </head>
@@ -80,6 +85,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 
 function DbSyncSetup() {
   const qc = useQueryClient();
+  useNavigationState();
   useDbSync({ queryClient: qc, queryKeys: ["files", "data"] });
   return null;
 }

package/src/templates/workspace-root/AGENTS.md

@@ -29,6 +29,19 @@ in `apps/<app>/AGENTS.md`; shared cross-app behavior belongs in
 - Do not satisfy a new-app request by adding a route, page, component, or file
   to `apps/starter` or another existing app unless the user explicitly asks to
   modify that existing app.
+- Treat first-party apps such as Mail, Calendar, Analytics, and Dispatch as
+  existing hosted/connected neighbors available through links and A2A/default
+  connected agents. For example, Mail, Calendar, and Analytics already exist at
+  `https://mail.agent-native.com`, `https://calendar.agent-native.com`, and
+  `https://analytics.agent-native.com`.
+- If a new app needs to use Mail, Calendar, Analytics, or similar first-party
+  data/agents, build only the genuinely new workflow and delegate/link to those
+  existing apps. Do not create wrapper apps, child apps, nested template copies,
+  or cloned Mail/Calendar/Analytics implementations inside the new app just to
+  provide access.
+- Only create a first-party app copy when the user explicitly asks for a
+  customized fork/copy of that app. Otherwise prefer the hosted/shared app so
+  base template improvements continue to flow automatically.
 - Workspace apps are discovered from `apps/<app-id>/package.json`. There is no
   separate workspace app registry to edit for Dispatch to list the app.
 - Use relative workspace links like `/<app-id>`. Never hardcode

package/src/templates/workspace-root/README.md

@@ -84,6 +84,12 @@ separate workspace app registry to edit. React Router apps must preserve
 For requests phrased as creating an "agent", classify the scope first: simple
 recurring Dispatch behavior can stay in Dispatch, while a robust app-like
 teammate should become a real workspace app listed with the rest of the apps.
+First-party apps such as Mail, Calendar, Analytics, and Dispatch should be
+treated as existing hosted or connected neighbors. If a new app needs access to
+their data or agents, link/delegate to those apps through the workspace/A2A
+path rather than creating wrapper apps, child apps, or cloned template copies
+inside the new app. Only fork one of those apps when the user explicitly asks
+for a customized copy.
 
 ## Editing shared behavior