@agent-native/core 0.12.15 → 0.12.17

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

@@ -69,7 +69,7 @@ Then boot it:
 cd my-company-platform
 cp .env.example .env             # fill in ANTHROPIC_API_KEY, BETTER_AUTH_SECRET, ...
 pnpm install
-pnpm dev                         # runs every app
+pnpm dev                         # opens Dispatch; other apps start on first visit
 ```
 
 Every app already knows how to log in, share the same database, and load the workspace `AGENTS.md`. You didn't wire any of that up — the framework auto-discovered the shared package via the `agent-native.workspaceCore` field in the root `package.json`:

package/package.json

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

@@ -56,7 +56,9 @@ in `apps/<app>/AGENTS.md`; shared cross-app behavior belongs in
 - In local development, scaffold the app from the workspace root with
   `pnpm exec agent-native create <app-id> --template=<template>`. In production
   Dispatch posts the request to Builder branch creation; the Builder branch
-  should still create the separate workspace app, not patch starter.
+  should still create the separate workspace app, not patch starter. The local
+  workspace gateway detects new app directories automatically and starts each
+  app server lazily on first visit.
 
 ## Workspace Identity
 

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

@@ -44,10 +44,10 @@ pnpm dev               # starts the workspace gateway; opens Dispatch when prese
 
 The dev gateway serves Dispatch at `/dispatch` when you keep the recommended
 Dispatch app selected, and every app at its own path such as `/starter`. It
-watches `apps/`, so newly-created apps are detected and started without
-restarting `pnpm dev`. App links should stay relative, such as `/starter` or
-`/<app-id>`; do not hardcode localhost or dev ports because the active gateway
-origin owns the port.
+watches `apps/`, so newly-created apps are detected without restarting
+`pnpm dev`. App servers start lazily the first time you visit their path. App
+links should stay relative, such as `/starter` or `/<app-id>`; do not hardcode
+localhost or dev ports because the active gateway origin owns the port.
 
 ## Workspace org identity
 

package/dist/templates/workspace-root/netlify.toml

@@ -1,11 +0,0 @@
-[build]
-  command = "export DATABASE_URL=\"${NETLIFY_DATABASE_URL:-$DATABASE_URL}\" && pnpm install && pnpm exec agent-native deploy --preset netlify --build-only"
-  publish = "dist"
-  functions = ".netlify/functions-internal"
-
-[build.environment]
-  NITRO_PRESET = "netlify"
-  NPM_CONFIG_PRODUCTION = "false"
-
-[functions."*"]
-  timeout = 60

package/src/templates/workspace-root/netlify.toml

@@ -1,11 +0,0 @@
-[build]
-  command = "export DATABASE_URL=\"${NETLIFY_DATABASE_URL:-$DATABASE_URL}\" && pnpm install && pnpm exec agent-native deploy --preset netlify --build-only"
-  publish = "dist"
-  functions = ".netlify/functions-internal"
-
-[build.environment]
-  NITRO_PRESET = "netlify"
-  NPM_CONFIG_PRODUCTION = "false"
-
-[functions."*"]
-  timeout = 60