@agent-native/dispatch 0.20.4 → 0.22.0

package/src/components/create-app-popover.tsx

@@ -7,7 +7,11 @@ import {
 import { PromptComposer } from "@agent-native/core/client/composer";
 import { isInBuilderFrame } from "@agent-native/core/client/host";
 import { useBuilderConnectFlow } from "@agent-native/core/client/settings/useBuilderStatus";
-import { getWorkspaceAppIdValidationError } from "@agent-native/core/shared";
+import {
+  buildChatFirstAppCreationPrompt,
+  getWorkspaceAppIdValidationError,
+  titleFromChatFirstAppPrompt,
+} from "@agent-native/core/shared";
 import {
   IconAlertTriangle,
   IconArrowLeft,
@@ -57,87 +61,6 @@ interface CreateAppPopoverProps {
   align?: "start" | "center" | "end";
 }
 
-function slugify(value: string): string {
-  return value
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .replace(/^[^a-z]+/, "")
-    .slice(0, 48);
-}
-
-function titleFromPrompt(prompt: string): string {
-  const cleaned = prompt
-    .replace(/\b(build|create|make|an?|the|app|tool|dashboard)\b/gi, " ")
-    .replace(/\s+/g, " ")
-    .trim();
-  return slugify(cleaned || "new-app") || "new-app";
-}
-
-function buildAppCreationPrompt(input: {
-  appId: string;
-  prompt: string;
-  selectedKeys: string[];
-  selectedResources: WorkspaceResourceOption[];
-  vaultAccessMode: VaultAccessMode;
-}): string {
-  const keyList = input.selectedKeys.join(", ");
-  const grantRequest =
-    input.vaultAccessMode === "all-apps"
-      ? `Dispatch vault access: all saved vault keys are available to every workspace app by default. No per-app vault grants are needed.`
-      : keyList
-        ? `Requested Dispatch vault key grants for this app: ${keyList}`
-        : `Requested Dispatch vault key grants for this app: none`;
-  const resourceList = input.selectedResources.length
-    ? input.selectedResources
-        .map(
-          (resource) =>
-            `- ${resource.name} (${resource.kind}, ${resource.path})`,
-        )
-        .join("\n")
-    : "none";
-
-  return [
-    `Create a new agent-native app in this workspace.`,
-    `This is a new workspace app request, not a feature request for the current app.`,
-    ``,
-    `Suggested app name: ${input.appId} (you may adjust the slug if it conflicts)`,
-    `User prompt: ${input.prompt.trim()}`,
-    `Generate a concise one-sentence app description from the user prompt before coding; save it in apps/${input.appId}/package.json "description" so Dispatch and A2A can describe the app.`,
-    `If the user mentions a product or company such as Granola, Loom, Superhuman, Linear, or Notion, treat it as product inspiration unless they explicitly ask to connect to that service. Do not invent or require third-party API keys like GRANOLA_API_KEY just because a product is named.`,
-    grantRequest,
-    `Requested Dispatch workspace resources for this app:\n${resourceList}`,
-    `Dispatch workspace resources with scope=all are inherited workspace context. Do not copy or sync them into the new app; every workspace app reads them at runtime and may override with app shared or personal resources.`,
-    ``,
-    `Pick a UI template that fits the user's prompt — analytics, assets, brain, calendar, chat, content, design, dispatch, forms, mail, slides, or clips when none of the others fit.`,
-    `If you use the chat template, treat it as scaffolding only: the finished app must use the requested app's real name, home screen, navigation, package metadata, and manifest, and it must not leave visible "Chat", "Starter", "Blank app", or "New app" UI behind.`,
-    `Use the workspace app layout: create it under apps/${input.appId}, mount it at /${input.appId}, keep it on the shared workspace database/hosting model, and avoid table-name collisions by namespacing any new domain tables to the app.`,
-    `Important routing rule: from outside the app, link to /${input.appId}; inside apps/${input.appId}, React Router routes are app-local. Use <Link to="/review"> and navigate("/review"), not "/${input.appId}/review"; APP_BASE_PATH supplies the mounted prefix, and hardcoding it causes doubled URLs like /${input.appId}/${input.appId}/review.`,
-    `Prefer useActionQuery/useActionMutation for actions. If you must raw-fetch framework endpoints, wrap them with agentNativePath("/_agent-native/actions/<name>") so mounted apps call the right URL.`,
-    `Use relative workspace links like /${input.appId}. Do not hardcode localhost, 127.0.0.1, 8080, 8100, or any dev port; the active workspace gateway/browser origin owns the port.`,
-    `Use the framework/template UI stack: shadcn/ui components and @tabler/icons-react. Do not add lucide-react or another icon library for standard UI.`,
-    `Existing first-party apps are neighbors, not implementation details for this app. If the user's prompt mentions Mail, Calendar, Analytics, Brain, Assets, Dispatch, or other templates, treat them as existing hosted/connected apps that this app can link to or call through A2A/default connected agents. For example, Mail, Calendar, Analytics, Brain, and Assets already exist at https://mail.agent-native.com, https://calendar.agent-native.com, https://analytics.agent-native.com, https://brain.agent-native.com, and https://assets.agent-native.com.`,
-    `Do not create wrapper apps or scaffold child apps/routes for Mail, Calendar, Analytics, Brain, Assets, etc. inside apps/${input.appId} just so this app can access them. If the request is a cross-app dashboard or overview, build only the new dashboard/overview app and delegate to the existing apps for domain work.`,
-    `Only create another first-party app when the user explicitly asks for a customized app from that template; otherwise keep using the hosted/shared app so improvements to the base app keep flowing to users.`,
-    `Do not satisfy this by adding a route, page, component, or file inside apps/chat or another existing app unless the user explicitly asks to modify that existing app.`,
-    input.vaultAccessMode === "all-apps"
-      ? `Do not create per-app Dispatch vault grants unless the workspace switches vault access to manual or the user explicitly asks for manual grants.`
-      : keyList
-        ? `After the app exists, grant the selected Dispatch vault keys to appId "${input.appId}" and sync them once the app server is available. Treat these as requested grants, not active grants before creation succeeds.`
-        : `Do not grant any Dispatch vault keys unless the user asks later.`,
-    input.selectedResources.length
-      ? `After the app exists, grant the selected Dispatch workspace resources to appId "${input.appId}". Do not sync All-app workspace resources; they are inherited.`
-      : `Do not grant any selected-only Dispatch workspace resources unless the user asks later.`,
-    ``,
-    `App readiness requirements before handing off:`,
-    `- Ensure apps/${input.appId}/package.json exists with displayName/name and a concise description; Dispatch discovers workspace apps from apps/<app-id>/package.json, not a separate app registry.`,
-    `- Update the app manifest/package/deploy metadata needed by the existing workspace deployment model.`,
-    `- Ensure the React Router client entry preserves APP_BASE_PATH/VITE_APP_BASE_PATH via appBasePath() so /${input.appId} hydrates correctly.`,
-    `- Verify the app's agent card/A2A metadata is ready so Dispatch can discover and delegate to the app after deployment. Every sibling workspace app is available over A2A by default through call-agent, with names and descriptions from the workspace app registry.`,
-    `When it is ready, start or update the workspace dev server and navigate the user to the absolute path /${input.appId} on the workspace origin. Do not prefix with /dispatch/, /apps/, /workspace/, or any other Dispatch tab — the new app is mounted at the workspace root, not under Dispatch. If you have a navigate tool available, pass /${input.appId} verbatim; if you only have a window.location-style escape hatch, set it to /${input.appId}.`,
-  ].join("\n");
-}
-
 async function fetchJson(url: string, init?: RequestInit): Promise<any> {
   const res = await fetch(url, init);
   const data = await res.json().catch(() => null);
@@ -168,6 +91,8 @@ const ERROR_FAILURE_REASONS = new Set([
   "credential-store-unavailable",
   "settings-management-required",
 ]);
+const LOCAL_APP_DOCS_URL =
+  "https://agent-native.com/docs/multi-app-workspace#adding-a-new-app";
 
 function isErrorFailureReason(reason: string | null): boolean {
   return !!reason && ERROR_FAILURE_REASONS.has(reason);
@@ -292,14 +217,14 @@ export function CreateAppFlow({
   async function submit(rawPrompt: string) {
     const trimmed = rawPrompt.trim();
     if (!trimmed || isSubmitting) return;
-    const appId = titleFromPrompt(trimmed);
+    const appId = titleFromChatFirstAppPrompt(trimmed);
     const validationError = getWorkspaceAppIdValidationError(appId);
     if (validationError) {
       setStatusMessage(validationError);
       return;
     }
 
-    const message = buildAppCreationPrompt({
+    const message = buildChatFirstAppCreationPrompt({
       appId,
       prompt: trimmed,
       selectedKeys:
@@ -653,16 +578,27 @@ export function CreateAppFlow({
             ) : null}
           </div>
           {failureReason === "builder-not-connected" ? (
-            <Button
-              type="button"
-              size="sm"
-              variant="outline"
-              onClick={() => connectFlow.start()}
-              disabled={connectFlow.connecting}
-              className="w-fit"
-            >
-              {connectFlow.connecting ? "Connecting..." : "Connect Builder"}
-            </Button>
+            <div className="flex flex-wrap items-center gap-2">
+              <Button
+                type="button"
+                size="sm"
+                variant="outline"
+                onClick={() => connectFlow.start()}
+                disabled={connectFlow.connecting}
+                className="w-fit"
+              >
+                {connectFlow.connecting ? "Connecting..." : "Connect Builder"}
+              </Button>
+              <a
+                href={LOCAL_APP_DOCS_URL}
+                target="_blank"
+                rel="noreferrer"
+                data-create-app-local-link
+                className="inline-flex items-center gap-1 text-xs font-medium text-foreground underline underline-offset-2"
+              >
+                Create locally <IconArrowUpRight className="h-3 w-3" />
+              </a>
+            </div>
           ) : null}
           {failureReason === "credential-store-unavailable" ||
           failureReason === "builder-error" ? (

package/src/components/layout/HeaderActions.tsx

@@ -1,84 +1 @@
-import {
-  useEffect,
-  useSyncExternalStore,
-  type ReactNode,
-  type FC,
-} from "react";
-
-/**
- * External store for the page's header title + actions. We use an external
- * store (not React context) so that pages can inject ReactNode without
- * subscribing to the header state themselves — subscribing would trigger a
- * re-render on every update, which in turn creates new JSX, which updates
- * the store again, which re-renders… an infinite loop.
- *
- * Only <Header /> reads the store via useSyncExternalStore; pages only write.
- */
-
-type Listener = () => void;
-
-let currentTitle: ReactNode = null;
-let currentActions: ReactNode = null;
-const listeners = new Set<Listener>();
-
-function notify() {
-  for (const l of listeners) l();
-}
-
-function subscribe(l: Listener): () => void {
-  listeners.add(l);
-  return () => {
-    listeners.delete(l);
-  };
-}
-
-/** Consumed only by <Header /> — returns the current title. */
-export function useHeaderTitle(): ReactNode {
-  return useSyncExternalStore(
-    subscribe,
-    () => currentTitle,
-    () => currentTitle,
-  );
-}
-
-/** Consumed only by <Header /> — returns the current actions slot. */
-export function useHeaderActions(): ReactNode {
-  return useSyncExternalStore(
-    subscribe,
-    () => currentActions,
-    () => currentActions,
-  );
-}
-
-/**
- * Provider is now a no-op wrapper for backwards compatibility — the state
- * lives in the module-level store above. Kept as a component so callers of
- * <HeaderActionsProvider> don't need to change.
- */
-export const HeaderActionsProvider: FC<{ children: ReactNode }> = ({
-  children,
-}) => <>{children}</>;
-
-/** Mount a custom title into the app header. Cleans up on unmount. */
-export function useSetPageTitle(node: ReactNode) {
-  useEffect(() => {
-    currentTitle = node;
-    notify();
-    return () => {
-      currentTitle = null;
-      notify();
-    };
-  });
-}
-
-/** Mount ReactNode into the header's actions slot. Cleans up on unmount. */
-export function useSetHeaderActions(node: ReactNode) {
-  useEffect(() => {
-    currentActions = node;
-    notify();
-    return () => {
-      currentActions = null;
-      notify();
-    };
-  });
-}
+export * from "@agent-native/toolkit/app-shell";

package/src/components/layout/Layout.spec.tsx

@@ -6,7 +6,11 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { AdminShell } from "../admin-navigation";
 import { TooltipProvider } from "../ui/tooltip";
-import { formatThreadAge, NavContent } from "./Layout";
+import {
+  buildChatFirstEmbedSessionInput,
+  formatThreadAge,
+  NavContent,
+} from "./Layout";
 
 const clientState = vi.hoisted(() => ({
   createThread: vi.fn<() => Promise<string | null>>(),
@@ -36,6 +40,7 @@ vi.mock("@agent-native/core/client/agent-chat", () => ({
 }));
 
 vi.mock("@agent-native/core/client/api-path", () => ({
+  agentNativePath: (path: string) => path,
   appBasePath: () => "",
   appPath: (path: string) => path,
 }));
@@ -96,6 +101,16 @@ describe("formatThreadAge", () => {
   });
 });
 
+describe("chat-first embed sessions", () => {
+  it("keeps the granted app id on app-relative embed requests", () => {
+    expect(buildChatFirstEmbedSessionInput("mail", "/mail/inbox")).toEqual({
+      app: "mail",
+      path: "/mail/inbox",
+      chrome: "minimal",
+    });
+  });
+});
+
 describe("Dispatch NavContent", () => {
   let container: HTMLDivElement;
   let root: Root;
@@ -218,7 +233,7 @@ describe("Dispatch NavContent", () => {
     expect(shell?.querySelector('a[href="/admin/apps"]')).toBeNull();
   });
 
-  it("shows ready workspace apps as host links and highlights the active app", async () => {
+  it("keeps workspace app discovery in the Apps destination", async () => {
     clientState.workspaceApps = [
       { id: "calendar", name: "Calendar", path: "/calendar", status: "ready" },
       { id: "pending", name: "Pending", path: "/pending", status: "pending" },
@@ -226,7 +241,7 @@ describe("Dispatch NavContent", () => {
 
     await act(async () => {
       root.render(
-        <MemoryRouter initialEntries={["/apps/calendar"]}>
+        <MemoryRouter initialEntries={["/overview"]}>
           <TooltipProvider>
             <NavContent />
           </TooltipProvider>
@@ -234,14 +249,24 @@ describe("Dispatch NavContent", () => {
       );
     });
 
-    const rail = container.querySelector("[data-dispatch-apps-rail]");
-    expect(rail).not.toBeNull();
-    expect(rail?.textContent).toContain("Calendar");
-    expect(rail?.textContent).not.toContain("Pending");
+    expect(container.querySelector("[data-dispatch-apps-rail]")).toBeNull();
+    expect(container.querySelector('a[href="/apps"]')).not.toBeNull();
+    expect(container.textContent).not.toContain("Calendar");
+    expect(container.textContent).not.toContain("Pending");
 
-    const calendarLink = rail?.querySelector('a[href="/apps/calendar"]');
-    expect(calendarLink).not.toBeNull();
-    expect(calendarLink?.getAttribute("aria-current")).toBe("page");
+    await act(async () => {
+      root.render(
+        <MemoryRouter initialEntries={["/apps/calendar"]}>
+          <TooltipProvider>
+            <NavContent />
+          </TooltipProvider>
+        </MemoryRouter>,
+      );
+    });
+
+    expect(container.querySelector('a[href="/apps"]')?.className).toContain(
+      "bg-sidebar-accent",
+    );
   });
 
   it("keeps Dispatch branding and anchors Settings above the organization picker", async () => {