@agent-native/dispatch 0.1.1 → 0.2.3

package/src/actions/navigate.ts

@@ -5,6 +5,7 @@
  *
  * Usage:
  *   pnpm action navigate --view=overview
+ *   pnpm action navigate --view=<custom-dispatch-extension-id>
  *   pnpm action navigate --path=/some/route
  *
  * Options:
@@ -21,24 +22,11 @@ export default defineAction({
     "Navigate the UI to a specific view or path. Writes a navigate command to application state which the UI reads and auto-deletes.",
   schema: z.object({
     view: z
-      .enum([
-        "overview",
-        "apps",
-        "new-app",
-        "vault",
-        "integrations",
-        "messaging",
-        "workspace",
-        "agents",
-        "destinations",
-        "routes",
-        "identities",
-        "approvals",
-        "audit",
-        "team",
-      ])
+      .string()
       .optional()
-      .describe("Named dispatch view to navigate to"),
+      .describe(
+        "Named dispatch view to navigate to. Built-in views include overview, apps, metrics, new-app, vault, integrations, messaging, workspace, agents, destinations, identities, approvals, audit, and team. Generated Dispatch extension tabs can also use their nav item id.",
+      ),
     path: z.string().optional().describe("URL path to navigate to"),
   }),
   http: false,

package/src/actions/view-screen.ts

@@ -18,6 +18,7 @@ import {
   listRequests,
 } from "../server/lib/vault-store.js";
 import { listWorkspaceApps } from "../server/lib/app-creation-store.js";
+import { listDispatchUsageMetrics } from "../server/lib/usage-metrics-store.js";
 
 export default defineAction({
   description:
@@ -45,6 +46,7 @@ export default defineAction({
     }
     if (
       navigation?.view === "overview" ||
+      navigation?.view === "metrics" ||
       navigation?.view === "apps" ||
       navigation?.view === "new-app"
     ) {
@@ -52,6 +54,22 @@ export default defineAction({
         includeAgentCards: true,
       });
     }
+    if (navigation?.view === "metrics") {
+      try {
+        const metrics = await listDispatchUsageMetrics({ sinceDays: 30 });
+        screen.usageMetrics = {
+          totals: metrics.totals,
+          byApp: metrics.byApp.slice(0, 8),
+          byUser: metrics.byUser.slice(0, 8),
+          appAccess: metrics.appAccess
+            .filter((app) => !app.isDispatch)
+            .slice(0, 8),
+        };
+      } catch (error) {
+        screen.usageMetricsError =
+          error instanceof Error ? error.message : String(error);
+      }
+    }
     if (navigation?.view === "vault" || navigation?.view === "new-app") {
       const [secrets, grants, requests] = await Promise.all([
         listSecrets(),

package/src/components/index.ts

@@ -7,5 +7,11 @@
  */
 export { DispatchShell } from "./dispatch-shell.js";
 export { Layout, NavContent } from "./layout/Layout.js";
+export type {
+  DispatchExtensionConfig,
+  DispatchNavIcon,
+  DispatchNavItem,
+  DispatchNavSection,
+} from "./layout/Layout.js";
 export { CreateAppPopover, CreateAppFlow } from "./create-app-popover.js";
 export { AppKeysPopover } from "./app-keys-popover.js";

package/src/components/layout/Header.tsx

@@ -22,7 +22,7 @@ const pageTitles: Record<string, string> = {
 function resolveTitle(pathname: string): string {
   if (pageTitles[pathname]) return pageTitles[pathname];
 
-  if (pathname.startsWith("/tools")) return "Tools";
+  if (pathname.startsWith("/extensions")) return "Extensions";
 
   return "Dispatch";
 }
@@ -44,7 +44,7 @@ export function Header({
         <Button
           variant="ghost"
           size="icon"
-          className="h-8 w-8 2xl:hidden cursor-pointer"
+          className="h-8 w-8 lg:hidden cursor-pointer"
           onClick={onOpenMobile}
           aria-label="Open navigation"
         >

package/src/components/layout/Layout.tsx

@@ -1,4 +1,4 @@
-import { useState, type ReactNode } from "react";
+import { useState, type ComponentType, type ReactNode } from "react";
 import { NavLink, useLocation } from "react-router";
 import {
   AgentSidebar,
@@ -11,6 +11,7 @@ import { ToolsSidebarSection } from "@agent-native/core/client/tools";
 import {
   IconArrowUpRight,
   IconApps,
+  IconChartBar,
   IconBrandTelegram,
   IconKey,
   IconChevronDown,
@@ -33,27 +34,131 @@ import {
 import { Header } from "./Header";
 import { HeaderActionsProvider } from "./HeaderActions";
 
+export type DispatchNavSection = "primary" | "operations";
+
+export type DispatchNavIcon = ComponentType<{
+  size?: number | string;
+  className?: string;
+}>;
+
+export interface DispatchNavItem {
+  /** Stable id used for keys and navigation.view. Avoid built-in ids. */
+  id: string;
+  /** React Router path for the tab, usually backed by an app/routes/*.tsx file. */
+  to: string;
+  label: string;
+  icon?: DispatchNavIcon;
+  /** Defaults to "operations", which is where local management tools usually fit. */
+  section?: DispatchNavSection;
+  /** Override active matching for nested or multi-route tools. */
+  match?: (pathname: string) => boolean;
+}
+
+export interface DispatchExtensionConfig {
+  /** Extra sidebar tabs supplied by the generated workspace. */
+  navItems?: readonly DispatchNavItem[];
+  /** Extra React Query keys to invalidate when Dispatch receives DB sync events. */
+  queryKeys?: readonly string[];
+}
+
 const PRIMARY_NAV_ITEMS = [
-  { to: "/overview", label: "Overview", icon: IconBroadcast },
-  { to: "/apps", label: "Apps", icon: IconApps },
-  { to: "/vault", label: "Vault", icon: IconKey },
-  { to: "/integrations", label: "Integrations", icon: IconPuzzle },
-  { to: "/agents", label: "Agents", icon: IconPlugConnected },
-] as const;
+  {
+    id: "overview",
+    to: "/overview",
+    label: "Overview",
+    icon: IconBroadcast,
+    section: "primary",
+  },
+  {
+    id: "apps",
+    to: "/apps",
+    label: "Apps",
+    icon: IconApps,
+    section: "primary",
+  },
+  {
+    id: "metrics",
+    to: "/metrics",
+    label: "Metrics",
+    icon: IconChartBar,
+    section: "primary",
+  },
+  {
+    id: "vault",
+    to: "/vault",
+    label: "Vault",
+    icon: IconKey,
+    section: "primary",
+  },
+  {
+    id: "integrations",
+    to: "/integrations",
+    label: "Integrations",
+    icon: IconPuzzle,
+    section: "primary",
+  },
+  {
+    id: "agents",
+    to: "/agents",
+    label: "Agents",
+    icon: IconPlugConnected,
+    section: "primary",
+  },
+] as const satisfies readonly DispatchNavItem[];
 
 const OPERATIONS_NAV_ITEMS = [
-  { to: "/workspace", label: "Resources", icon: IconLayersSubtract },
-  { to: "/messaging", label: "Messaging", icon: IconBrandTelegram },
-  { to: "/destinations", label: "Destinations", icon: IconArrowUpRight },
-  { to: "/identities", label: "Identities", icon: IconFingerprint },
-  { to: "/approvals", label: "Approvals", icon: IconShieldCheck },
-  { to: "/audit", label: "Audit", icon: IconHistory },
-  { to: "/team", label: "Team", icon: IconUsersGroup },
-] as const;
-
-type NavItem =
-  | (typeof PRIMARY_NAV_ITEMS)[number]
-  | (typeof OPERATIONS_NAV_ITEMS)[number];
+  {
+    id: "workspace",
+    to: "/workspace",
+    label: "Resources",
+    icon: IconLayersSubtract,
+    section: "operations",
+  },
+  {
+    id: "messaging",
+    to: "/messaging",
+    label: "Messaging",
+    icon: IconBrandTelegram,
+    section: "operations",
+  },
+  {
+    id: "destinations",
+    to: "/destinations",
+    label: "Destinations",
+    icon: IconArrowUpRight,
+    section: "operations",
+  },
+  {
+    id: "identities",
+    to: "/identities",
+    label: "Identities",
+    icon: IconFingerprint,
+    section: "operations",
+  },
+  {
+    id: "approvals",
+    to: "/approvals",
+    label: "Approvals",
+    icon: IconShieldCheck,
+    section: "operations",
+  },
+  {
+    id: "audit",
+    to: "/audit",
+    label: "Audit",
+    icon: IconHistory,
+    section: "operations",
+  },
+  {
+    id: "team",
+    to: "/team",
+    label: "Team",
+    icon: IconUsersGroup,
+    section: "operations",
+  },
+] as const satisfies readonly DispatchNavItem[];
+
+const EMPTY_NAV_ITEMS: readonly DispatchNavItem[] = [];
 
 const SIDEBAR_SUGGESTIONS = [
   "Create a new app",
@@ -68,6 +173,8 @@ const CHROMELESS_PATHS = ["/approval"];
 // there's no double-header.
 function pageOwnsToolbar(pathname: string): boolean {
   if (pathname === "/tools" || pathname.startsWith("/tools/")) return true;
+  if (pathname === "/extensions" || pathname.startsWith("/extensions/"))
+    return true;
   return false;
 }
 
@@ -77,7 +184,35 @@ interface WorkspaceInfo {
   appCount: number;
 }
 
-export function NavContent({ onNavigate }: { onNavigate?: () => void }) {
+function sectionFor(item: DispatchNavItem): DispatchNavSection {
+  return item.section ?? "operations";
+}
+
+function navItemMatchesPath(item: DispatchNavItem, pathname: string): boolean {
+  if (item.match) {
+    try {
+      if (item.match(pathname)) return true;
+    } catch {
+      return false;
+    }
+  }
+  return pathname === item.to || pathname.startsWith(`${item.to}/`);
+}
+
+function navItemsForSection(
+  items: readonly DispatchNavItem[],
+  section: DispatchNavSection,
+): DispatchNavItem[] {
+  return items.filter((item) => sectionFor(item) === section);
+}
+
+export function NavContent({
+  onNavigate,
+  extensions,
+}: {
+  onNavigate?: () => void;
+  extensions?: DispatchExtensionConfig;
+}) {
   const location = useLocation();
   const { data: workspace } = useActionQuery(
     "get-workspace-info",
@@ -86,29 +221,42 @@ export function NavContent({ onNavigate }: { onNavigate?: () => void }) {
   );
   const ws = workspace as WorkspaceInfo | undefined;
   const workspaceLabel = ws?.displayName ?? ws?.name ?? null;
-  const operationsOpen = OPERATIONS_NAV_ITEMS.some(
-    (item) =>
-      location.pathname === item.to ||
-      location.pathname.startsWith(`${item.to}/`),
+  const extensionNavItems = extensions?.navItems ?? EMPTY_NAV_ITEMS;
+  const primaryNavItems = [
+    ...PRIMARY_NAV_ITEMS,
+    ...navItemsForSection(extensionNavItems, "primary"),
+  ];
+  const operationsNavItems = [
+    ...OPERATIONS_NAV_ITEMS,
+    ...navItemsForSection(extensionNavItems, "operations"),
+  ];
+  const operationsOpen = operationsNavItems.some((item) =>
+    navItemMatchesPath(item, location.pathname),
   );
 
-  const renderNavItem = (item: NavItem) => {
+  const renderNavItem = (item: DispatchNavItem) => {
     const Icon = item.icon;
     return (
-      <li key={item.to}>
+      <li key={item.id}>
         <NavLink
           to={item.to}
           onClick={onNavigate}
-          className={({ isActive }) =>
-            cn(
+          className={({ isActive }) => {
+            const active =
+              isActive || navItemMatchesPath(item, location.pathname);
+            return cn(
               "flex h-8 w-full items-center gap-2 rounded-md px-2 text-sm",
-              isActive
+              active
                 ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground"
                 : "text-sidebar-foreground/70 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
-            )
-          }
+            );
+          }}
         >
-          <Icon size={16} className="shrink-0" />
+          {Icon ? (
+            <Icon size={16} className="shrink-0" />
+          ) : (
+            <span className="h-4 w-4 shrink-0" aria-hidden="true" />
+          )}
           <span className="truncate">{item.label}</span>
         </NavLink>
       </li>
@@ -147,7 +295,7 @@ export function NavContent({ onNavigate }: { onNavigate?: () => void }) {
       </div>
 
       <nav className="flex-1 overflow-y-auto px-2 py-3">
-        <ul className="space-y-0.5">{PRIMARY_NAV_ITEMS.map(renderNavItem)}</ul>
+        <ul className="space-y-0.5">{primaryNavItems.map(renderNavItem)}</ul>
         <details className="group mt-4" open={operationsOpen}>
           <summary className="flex h-8 cursor-pointer list-none items-center justify-between rounded-md px-2 text-xs font-medium uppercase text-sidebar-foreground/50 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground [&::-webkit-details-marker]:hidden">
             <span>Operations</span>
@@ -157,7 +305,7 @@ export function NavContent({ onNavigate }: { onNavigate?: () => void }) {
             />
           </summary>
           <ul className="mt-1 space-y-0.5">
-            {OPERATIONS_NAV_ITEMS.map(renderNavItem)}
+            {operationsNavItems.map(renderNavItem)}
           </ul>
         </details>
       </nav>
@@ -170,11 +318,15 @@ export function NavContent({ onNavigate }: { onNavigate?: () => void }) {
   );
 }
 
-export function Layout({ children }: { children: ReactNode }) {
+export function Layout({
+  children,
+  extensions,
+}: {
+  children: ReactNode;
+  extensions?: DispatchExtensionConfig;
+}) {
   const location = useLocation();
   const [mobileOpen, setMobileOpen] = useState(false);
-  const hasEmbeddedAgentChat =
-    location.pathname === "/" || location.pathname === "/overview";
 
   if (CHROMELESS_PATHS.some((path) => location.pathname === path)) {
     return <>{children}</>;
@@ -183,12 +335,7 @@ export function Layout({ children }: { children: ReactNode }) {
   const showHeader = !pageOwnsToolbar(location.pathname);
   const appContent = (
     <div className="flex h-full flex-1 flex-col overflow-hidden">
-      {showHeader ? (
-        <Header
-          onOpenMobile={() => setMobileOpen(true)}
-          showAgentToggle={!hasEmbeddedAgentChat}
-        />
-      ) : null}
+      {showHeader ? <Header onOpenMobile={() => setMobileOpen(true)} /> : null}
       <InvitationBanner />
       <main className="flex-1 overflow-y-auto">
         {showHeader ? (
@@ -205,8 +352,8 @@ export function Layout({ children }: { children: ReactNode }) {
   return (
     <HeaderActionsProvider>
       <div className="flex h-screen w-full overflow-hidden bg-background">
-        <aside className="hidden 2xl:flex w-64 shrink-0 flex-col border-r bg-sidebar text-sidebar-foreground">
-          <NavContent />
+        <aside className="hidden lg:flex w-64 shrink-0 flex-col border-r bg-sidebar text-sidebar-foreground">
+          <NavContent extensions={extensions} />
         </aside>
 
         <Sheet open={mobileOpen} onOpenChange={setMobileOpen}>
@@ -219,15 +366,17 @@ export function Layout({ children }: { children: ReactNode }) {
               Workspace navigation links
             </SheetDescription>
             <div className="flex h-full w-full flex-col">
-              <NavContent onNavigate={() => setMobileOpen(false)} />
+              <NavContent
+                extensions={extensions}
+                onNavigate={() => setMobileOpen(false)}
+              />
             </div>
           </SheetContent>
         </Sheet>
 
         {/*
          * Always mount AgentSidebar so home composer's sendToAgentChat
-         * fallback can pop it via agent-panel:open. The toggle button stays
-         * hidden on overview because the home composer is the primary input.
+         * fallback can pop it via agent-panel:open.
          */}
         <AgentSidebar
           position="right"

package/src/components/ui/sidebar.tsx

@@ -307,24 +307,28 @@ const SidebarRail = React.forwardRef<
   const { toggleSidebar } = useSidebar();
 
   return (
-    <button
-      ref={ref}
-      data-sidebar="rail"
-      aria-label="Toggle Sidebar"
-      tabIndex={-1}
-      onClick={toggleSidebar}
-      title="Toggle Sidebar"
-      className={cn(
-        "absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] hover:after:bg-sidebar-border group-data-[side=left]:-right-4 group-data-[side=right]:left-0 sm:flex",
-        "[[data-side=left]_&]:cursor-w-resize [[data-side=right]_&]:cursor-e-resize",
-        "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
-        "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full group-data-[collapsible=offcanvas]:hover:bg-sidebar",
-        "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
-        "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
-        className,
-      )}
-      {...props}
-    />
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          ref={ref}
+          data-sidebar="rail"
+          aria-label="Toggle Sidebar"
+          tabIndex={-1}
+          onClick={toggleSidebar}
+          className={cn(
+            "absolute inset-y-0 z-20 hidden w-4 -translate-x-1/2 transition-all ease-linear after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] hover:after:bg-sidebar-border group-data-[side=left]:-right-4 group-data-[side=right]:left-0 sm:flex",
+            "[[data-side=left]_&]:cursor-w-resize [[data-side=right]_&]:cursor-e-resize",
+            "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
+            "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full group-data-[collapsible=offcanvas]:hover:bg-sidebar",
+            "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
+            "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
+            className,
+          )}
+          {...props}
+        />
+      </TooltipTrigger>
+      <TooltipContent>Toggle Sidebar</TooltipContent>
+    </Tooltip>
   );
 });
 SidebarRail.displayName = "SidebarRail";

package/src/hooks/use-navigation-state.ts

@@ -6,13 +6,17 @@ import {
   appBasePath,
   appPath,
 } from "@agent-native/core/client";
+import type {
+  DispatchExtensionConfig,
+  DispatchNavItem,
+} from "../components/index.js";
 
 export interface NavigationState {
   view: string;
   path?: string;
 }
 
-export function useNavigationState() {
+export function useNavigationState(extensions?: DispatchExtensionConfig) {
   const location = useLocation();
   const navigate = useNavigate();
   const qc = useQueryClient();
@@ -20,7 +24,7 @@ export function useNavigationState() {
   // Sync current route to application state
   useEffect(() => {
     const state: NavigationState = {
-      view: resolveView(location.pathname),
+      view: resolveView(location.pathname, extensions),
       path: appPath(location.pathname),
     };
 
@@ -30,7 +34,7 @@ export function useNavigationState() {
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(state),
     }).catch(() => {});
-  }, [location.pathname]);
+  }, [extensions, location.pathname]);
 
   // Listen for navigate commands from agent
   const { data: navCommand } = useQuery({
@@ -62,10 +66,12 @@ export function useNavigationState() {
     const cmd = navCommand as NavigationState;
 
     // Navigate to a specific path or resolve view name to path
-    const path = routerPath(cmd.path || resolvePath(cmd.view) || "/overview");
+    const path = routerPath(
+      cmd.path || resolvePath(cmd.view, extensions) || "/overview",
+    );
     navigate(path);
     qc.setQueryData(["navigate-command"], null);
-  }, [navCommand, navigate, qc]);
+  }, [extensions, navCommand, navigate, qc]);
 }
 
 function routerPath(path: string): string {
@@ -78,8 +84,45 @@ function routerPath(path: string): string {
   return path;
 }
 
-function resolveView(pathname: string): string {
+function extensionItemMatchesPath(
+  item: DispatchNavItem,
+  pathname: string,
+): boolean {
+  if (item.match) {
+    try {
+      if (item.match(pathname)) return true;
+    } catch {
+      return false;
+    }
+  }
+  return pathname === item.to || pathname.startsWith(`${item.to}/`);
+}
+
+function resolveExtensionView(
+  pathname: string,
+  extensions?: DispatchExtensionConfig,
+): string | undefined {
+  return extensions?.navItems?.find((item) =>
+    extensionItemMatchesPath(item, pathname),
+  )?.id;
+}
+
+function resolveExtensionPath(
+  view: string | undefined,
+  extensions?: DispatchExtensionConfig,
+): string | undefined {
+  if (!view) return undefined;
+  return extensions?.navItems?.find((item) => item.id === view)?.to;
+}
+
+function resolveView(
+  pathname: string,
+  extensions?: DispatchExtensionConfig,
+): string {
+  const extensionView = resolveExtensionView(pathname, extensions);
+  if (extensionView) return extensionView;
   if (pathname.startsWith("/apps")) return "apps";
+  if (pathname.startsWith("/metrics")) return "metrics";
   if (pathname.startsWith("/new-app")) return "new-app";
   if (pathname.startsWith("/vault")) return "vault";
   if (pathname.startsWith("/integrations")) return "integrations";
@@ -94,12 +137,18 @@ function resolveView(pathname: string): string {
   return "overview";
 }
 
-function resolvePath(view?: string): string | undefined {
+function resolvePath(
+  view?: string,
+  extensions?: DispatchExtensionConfig,
+): string | undefined {
   switch (view) {
     case "overview":
       return "/overview";
     case "apps":
       return "/apps";
+    case "metrics":
+    case "usage":
+      return "/metrics";
     case "new-app":
     case "create-app":
       return "/new-app";
@@ -127,6 +176,6 @@ function resolvePath(view?: string): string | undefined {
     case "team":
       return "/team";
     default:
-      return undefined;
+      return resolveExtensionPath(view, extensions);
   }
 }

package/src/routes/index.ts

@@ -32,6 +32,7 @@ import { type RouteConfig, route, index } from "@react-router/dev/routes";
 export const dispatchRoutes: RouteConfig = [
   index("./pages/_index.js"),
   route("overview", "./pages/overview.js"),
+  route("metrics", "./pages/metrics.js"),
   route("apps", "./pages/apps.js"),
   route("apps/:appId", "./pages/apps.$appId.js"),
   route("new-app", "./pages/new-app.js"),
@@ -46,6 +47,6 @@ export const dispatchRoutes: RouteConfig = [
   route("approvals", "./pages/approvals.js"),
   route("audit", "./pages/audit.js"),
   route("team", "./pages/team.js"),
-  route("tools", "./pages/tools._index.js"),
-  route("tools/:id", "./pages/tools.$id.js"),
+  route("extensions", "./pages/extensions._index.js"),
+  route("extensions/:id", "./pages/extensions.$id.js"),
 ];

package/src/routes/pages/extensions.$id.tsx

@@ -0,0 +1,5 @@
+import { ToolViewerPage } from "@agent-native/core/client/tools";
+
+export default function ExtensionViewerRoute() {
+  return <ToolViewerPage />;
+}

package/src/routes/pages/extensions._index.tsx

@@ -0,0 +1,5 @@
+import { ToolsListPage } from "@agent-native/core/client/tools";
+
+export default function ExtensionsRoute() {
+  return <ToolsListPage />;
+}