feat: move dashboard to apps/ so we can share ws proto

apps/dashboard/src/plugins/PluginPage.tsx

@@ -0,0 +1,64 @@
+import { useSyncExternalStore } from "react";
+import { Spinner } from "@nous-research/ui/ui/components/spinner";
+import {
+  getPluginComponent,
+  getPluginLoadError,
+  onPluginRegistered,
+} from "./registry";
+import { useI18n } from "@/i18n";
+import { cn } from "@/lib/utils";
+import type { Translations } from "@/i18n/types";
+
+/** Renders a plugin tab once its bundle has called `register()`. */
+export function PluginPage({ name }: { name: string }) {
+  const { t } = useI18n();
+  // Subscribe in render (via useSyncExternalStore) so we never miss
+  // `register()` if the script loads before a useEffect would run.
+  const Component = useSyncExternalStore(
+    (onChange) => onPluginRegistered(onChange),
+    () => getPluginComponent(name) ?? null,
+    () => null,
+  );
+  const loadError = useSyncExternalStore(
+    (onChange) => onPluginRegistered(onChange),
+    () => getPluginLoadError(name) ?? null,
+    () => null,
+  );
+
+  if (Component) {
+    return <Component />;
+  }
+
+  if (loadError) {
+    const message = formatPluginError(loadError, t);
+    return (
+      <div
+        className={cn(
+          "max-w-lg p-4",
+          "font-mondwest text-sm tracking-[0.08em] text-midground/80",
+        )}
+        role="alert"
+      >
+        {message}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-2 p-4",
+        "font-mondwest text-sm tracking-[0.1em] text-midground/60",
+      )}
+    >
+      <Spinner className="shrink-0" />
+      <span>{t.common.loading}</span>
+    </div>
+  );
+}
+
+function formatPluginError(code: string, t: Translations): string {
+  if (code === "LOAD_FAILED") return t.common.pluginLoadFailed;
+  if (code === "NO_REGISTER") return t.common.pluginNotRegistered;
+  return code;
+}

apps/dashboard/src/plugins/index.ts

@@ -0,0 +1,6 @@
+export { exposePluginSDK, getPluginComponent, onPluginRegistered, getRegisteredCount } from "./registry";
+export { PluginPage } from "./PluginPage";
+export { usePlugins } from "./usePlugins";
+export { PluginSlot, KNOWN_SLOT_NAMES, registerSlot, getSlotEntries, onSlotRegistered, unregisterPluginSlots } from "./slots";
+export type { KnownSlotName } from "./slots";
+export type { PluginManifest, RegisteredPlugin } from "./types";

apps/dashboard/src/plugins/registry.ts

@@ -0,0 +1,149 @@
+/**
+ * Dashboard Plugin SDK + Registry
+ *
+ * Exposes React, UI components, hooks, and utilities on the window so
+ * that plugin bundles can use them without bundling their own copies.
+ *
+ * Plugins call window.__HERMES_PLUGINS__.register(name, Component)
+ * to register their tab component.
+ */
+
+import React, {
+  useState,
+  useEffect,
+  useCallback,
+  useMemo,
+  useRef,
+  useContext,
+  createContext,
+} from "react";
+import { api, fetchJSON } from "@/lib/api";
+import { cn, timeAgo, isoTimeAgo } from "@/lib/utils";
+import { Badge } from "@nous-research/ui/ui/components/badge";
+import { Button } from "@nous-research/ui/ui/components/button";
+import { Select, SelectOption } from "@nous-research/ui/ui/components/select";
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Separator } from "@/components/ui/separator";
+import { Tabs, TabsList, TabsTrigger } from "@nous-research/ui/ui/components/tabs";
+import { useI18n } from "@/i18n";
+import { registerSlot, PluginSlot } from "./slots";
+
+// ---------------------------------------------------------------------------
+// Plugin registry — plugins call register() to add their component.
+// ---------------------------------------------------------------------------
+
+type RegistryListener = () => void;
+
+const _registered: Map<string, React.ComponentType> = new Map();
+const _loadErrors: Map<string, string> = new Map();
+const _listeners: Set<RegistryListener> = new Set();
+
+function _notify() {
+  for (const fn of _listeners) {
+    try { fn(); } catch { /* ignore */ }
+  }
+}
+
+/** Re-run registry subscribers (e.g. after a plugin script onload, or dev HMR re-inject). */
+export function notifyPluginRegistry() {
+  _notify();
+}
+
+/** Register a plugin component. Called by plugin JS bundles. */
+function registerPlugin(name: string, component: React.ComponentType) {
+  _loadErrors.delete(name);
+  _registered.set(name, component);
+  _notify();
+}
+
+/** Get a registered component by plugin name. */
+export function getPluginComponent(name: string): React.ComponentType | undefined {
+  return _registered.get(name);
+}
+
+export function getPluginLoadError(name: string): string | undefined {
+  return _loadErrors.get(name);
+}
+
+export function setPluginLoadError(name: string, message: string) {
+  _loadErrors.set(name, message);
+  _notify();
+}
+
+/** Subscribe to registry changes (returns unsubscribe fn). */
+export function onPluginRegistered(fn: RegistryListener): () => void {
+  _listeners.add(fn);
+  return () => _listeners.delete(fn);
+}
+
+/** Get current count of registered plugins. */
+export function getRegisteredCount(): number {
+  return _registered.size;
+}
+
+// ---------------------------------------------------------------------------
+// Expose SDK + registry on window
+// ---------------------------------------------------------------------------
+
+declare global {
+  interface Window {
+    __HERMES_PLUGIN_SDK__: unknown;
+    __HERMES_PLUGINS__: {
+      register: typeof registerPlugin;
+      registerSlot: typeof registerSlot;
+    };
+  }
+}
+
+export function exposePluginSDK() {
+  window.__HERMES_PLUGINS__ = {
+    register: registerPlugin,
+    registerSlot,
+  };
+
+  window.__HERMES_PLUGIN_SDK__ = {
+    // React core — plugins use these instead of importing react
+    React,
+    hooks: {
+      useState,
+      useEffect,
+      useCallback,
+      useMemo,
+      useRef,
+      useContext,
+      createContext,
+    },
+
+    // Hermes API client
+    api,
+    // Raw fetchJSON for plugin-specific endpoints
+    fetchJSON,
+
+    // UI components (shadcn/ui primitives)
+    components: {
+      Card,
+      CardHeader,
+      CardTitle,
+      CardContent,
+      Badge,
+      Button,
+      Input,
+      Label,
+      Select,
+      SelectOption,
+      Separator,
+      Tabs,
+      TabsList,
+      TabsTrigger,
+      PluginSlot,
+    },
+
+    // Utilities
+    utils: { cn, timeAgo, isoTimeAgo },
+
+    // Hooks
+    useI18n,
+  };
+}

apps/dashboard/src/plugins/slots.ts

@@ -0,0 +1,199 @@
+/**
+ * Plugin slot registry.
+ *
+ * Plugins can inject components into named locations in the app shell
+ * (header-left, sidebar, backdrop, etc.) by calling
+ * `window.__HERMES_PLUGINS__.registerSlot(pluginName, slotName, Component)`
+ * from their JS bundle. Multiple plugins can populate the same slot — they
+ * render stacked in registration order.
+ *
+ * The canonical slot names are documented in `KNOWN_SLOT_NAMES` below. The
+ * registry accepts any string so plugin ecosystems can define their own
+ * slots; the shell only renders `<PluginSlot name="..." />` for the slots
+ * it knows about.
+ */
+
+import React, { Fragment, useEffect, useState } from "react";
+
+/** Slot locations the built-in shell renders. Plugins declaring any of
+ *  these in their manifest's `slots` field get wired in automatically.
+ *
+ *  Shell-wide slots:
+ *  - `backdrop`         — rendered inside `<Backdrop />`, above the noise layer
+ *  - `header-left`      — injected before the Hermes brand in the top bar
+ *  - `header-right`     — injected before the theme/language switchers
+ *  - `header-banner`    — injected below the top nav bar, full-width
+ *  - `sidebar`          — the cockpit sidebar rail (only rendered when
+ *                         `layoutVariant === "cockpit"`)
+ *  - `pre-main`         — rendered above the route outlet (inside `<main>`)
+ *  - `post-main`        — rendered below the route outlet (inside `<main>`)
+ *  - `footer-left`      — replaces the left footer cell content
+ *  - `footer-right`     — replaces the right footer cell content
+ *  - `overlay`          — fixed-position layer above everything else;
+ *                         useful for chrome (scanlines, vignettes) the
+ *                         theme's customCSS can't achieve alone
+ *
+ *  Page-scoped slots (rendered inside a specific built-in page — use these
+ *  to inject widgets, cards, or toolbars into existing pages without
+ *  overriding the whole route):
+ *  - `sessions:top`     — top of /sessions page (above session list)
+ *  - `sessions:bottom`  — bottom of /sessions page
+ *  - `analytics:top`    — top of /analytics page
+ *  - `analytics:bottom` — bottom of /analytics page
+ *  - `logs:top`         — top of /logs page (above filter toolbar)
+ *  - `logs:bottom`      — bottom of /logs page (below log viewer)
+ *  - `cron:top`         — top of /cron page
+ *  - `cron:bottom`      — bottom of /cron page
+ *  - `skills:top`       — top of /skills page
+ *  - `skills:bottom`    — bottom of /skills page
+ *  - `plugins:top`       — top of /plugins page
+ *  - `plugins:bottom`    — bottom of /plugins page
+ *  - `config:top`       — top of /config page
+ *  - `config:bottom`    — bottom of /config page
+ *  - `env:top`          — top of /env (Keys) page
+ *  - `env:bottom`       — bottom of /env (Keys) page
+ *  - `docs:top`         — top of /docs page (above the docs iframe)
+ *  - `docs:bottom`      — bottom of /docs page
+ *  - `chat:top`         — top of /chat page (above the composer, when embedded chat is on)
+ *  - `chat:bottom`      — bottom of /chat page
+ */
+export const KNOWN_SLOT_NAMES = [
+  // Shell-wide
+  "backdrop",
+  "header-left",
+  "header-right",
+  "header-banner",
+  "sidebar",
+  "pre-main",
+  "post-main",
+  "footer-left",
+  "footer-right",
+  "overlay",
+  // Page-scoped
+  "sessions:top",
+  "sessions:bottom",
+  "analytics:top",
+  "analytics:bottom",
+  "logs:top",
+  "logs:bottom",
+  "cron:top",
+  "cron:bottom",
+  "skills:top",
+  "skills:bottom",
+  "plugins:top",
+  "plugins:bottom",
+  "config:top",
+  "config:bottom",
+  "env:top",
+  "env:bottom",
+  "docs:top",
+  "docs:bottom",
+  "chat:top",
+  "chat:bottom",
+] as const;
+
+export type KnownSlotName = (typeof KNOWN_SLOT_NAMES)[number];
+
+type SlotListener = () => void;
+
+interface SlotEntry {
+  plugin: string;
+  component: React.ComponentType;
+}
+
+/** Map<slotName, SlotEntry[]>. Entries are appended in registration order. */
+const _slotRegistry: Map<string, SlotEntry[]> = new Map();
+const _slotListeners: Set<SlotListener> = new Set();
+
+function _notifySlots() {
+  for (const fn of _slotListeners) {
+    try {
+      fn();
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+/** Register a component for a slot. Called by plugin bundles via
+ *  `window.__HERMES_PLUGINS__.registerSlot(...)`.
+ *
+ *  If the same (plugin, slot) pair is registered twice, the later call
+ *  replaces the earlier one — this matches how React HMR expects plugin
+ *  re-mounts to behave. */
+export function registerSlot(
+  plugin: string,
+  slot: string,
+  component: React.ComponentType,
+): void {
+  const existing = _slotRegistry.get(slot) ?? [];
+  const filtered = existing.filter((e) => e.plugin !== plugin);
+  filtered.push({ plugin, component });
+  _slotRegistry.set(slot, filtered);
+  _notifySlots();
+}
+
+/** Read current entries for a slot. Returns a copy so callers can't mutate
+ *  registry state. */
+export function getSlotEntries(slot: string): SlotEntry[] {
+  return (_slotRegistry.get(slot) ?? []).slice();
+}
+
+/** Subscribe to registry changes. Returns an unsubscribe function. */
+export function onSlotRegistered(fn: SlotListener): () => void {
+  _slotListeners.add(fn);
+  return () => {
+    _slotListeners.delete(fn);
+  };
+}
+
+/** Clear a specific plugin's slot registrations. Useful for HMR /
+ *  plugin reload flows — not wired in by default. */
+export function unregisterPluginSlots(plugin: string): void {
+  let changed = false;
+  for (const [slot, entries] of _slotRegistry.entries()) {
+    const kept = entries.filter((e) => e.plugin !== plugin);
+    if (kept.length !== entries.length) {
+      changed = true;
+      if (kept.length === 0) _slotRegistry.delete(slot);
+      else _slotRegistry.set(slot, kept);
+    }
+  }
+  if (changed) _notifySlots();
+}
+
+interface PluginSlotProps {
+  /** Slot identifier (e.g. `"sidebar"`, `"header-left"`). */
+  name: string;
+  /** Optional content rendered when no plugins have claimed the slot.
+   *  Useful for built-in defaults the plugin would replace. */
+  fallback?: React.ReactNode;
+}
+
+/** Render all components registered for a given slot, stacked in order.
+ *
+ *  Component re-renders when the slot registry changes so plugins that
+ *  arrive after initial mount show up without a manual refresh. */
+export function PluginSlot({ name, fallback }: PluginSlotProps) {
+  const [entries, setEntries] = useState<SlotEntry[]>(() => getSlotEntries(name));
+
+  useEffect(() => {
+    // Pick up anything registered between the initial `useState` call
+    // and the first effect tick, then subscribe for future changes.
+    setEntries(getSlotEntries(name));
+    const unsub = onSlotRegistered(() => setEntries(getSlotEntries(name)));
+    return unsub;
+  }, [name]);
+
+  if (entries.length === 0) {
+    return fallback ? React.createElement(Fragment, null, fallback) : null;
+  }
+
+  return React.createElement(
+    Fragment,
+    null,
+    ...entries.map((entry) =>
+      React.createElement(entry.component, { key: entry.plugin }),
+    ),
+  );
+}

apps/dashboard/src/plugins/types.ts

@@ -0,0 +1,31 @@
+/** Types for the dashboard plugin system. */
+
+import type { ComponentType } from "react";
+
+export interface PluginManifest {
+  name: string;
+  label: string;
+  description: string;
+  icon: string;
+  version: string;
+  tab: {
+    path: string;
+    /** "end", "after:<pathSegment>", "before:<pathSegment>" (e.g. "after:skills" → after `/skills`) */
+    position?: string;
+    /** When set to a built-in route path, this plugin replaces that page instead of adding a new tab. */
+    override?: string;
+    /** When true, the plugin may register without a sidebar tab (slot-only, etc.). */
+    hidden?: boolean;
+  };
+  /** Declared for discovery; actual slots use registerSlot in the plugin bundle. */
+  slots?: string[];
+  entry: string;
+  css?: string | null;
+  has_api: boolean;
+  source: string;
+}
+
+export interface RegisteredPlugin {
+  manifest: PluginManifest;
+  component: ComponentType;
+}

apps/dashboard/src/plugins/usePlugins.ts

@@ -0,0 +1,123 @@
+/**
+ * usePlugins hook — discovers and loads dashboard plugins.
+ *
+ * 1. Fetches plugin manifests from GET /api/dashboard/plugins
+ * 2. Injects CSS <link> tags for plugins that declare css
+ * 3. Loads plugin JS bundles via <script> tags
+ * 4. Waits for plugins to call register() and resolves them
+ */
+
+import { useState, useEffect, useRef } from "react";
+import { api } from "@/lib/api";
+import type { PluginManifest, RegisteredPlugin } from "./types";
+import {
+  getPluginComponent,
+  onPluginRegistered,
+  notifyPluginRegistry,
+  setPluginLoadError,
+} from "./registry";
+
+export function usePlugins() {
+  const [manifests, setManifests] = useState<PluginManifest[]>([]);
+  const [plugins, setPlugins] = useState<RegisteredPlugin[]>([]);
+  const [loading, setLoading] = useState(true);
+  const loadedScripts = useRef<Set<string>>(new Set());
+
+  // Fetch manifests on mount.
+  useEffect(() => {
+    api
+      .getPlugins()
+      .then((list) => {
+        setManifests(list);
+        if (list.length === 0) setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, []);
+
+  // Load plugin assets when manifests arrive.
+  useEffect(() => {
+    if (manifests.length === 0) return;
+
+    const injectedScripts: HTMLScriptElement[] = [];
+
+    for (const manifest of manifests) {
+      // Inject CSS if specified.
+      if (manifest.css) {
+        const cssUrl = `/dashboard-plugins/${manifest.name}/${manifest.css}`;
+        if (!document.querySelector(`link[href="${cssUrl}"]`)) {
+          const link = document.createElement("link");
+          link.rel = "stylesheet";
+          link.href = cssUrl;
+          document.head.appendChild(link);
+        }
+      }
+
+      // Load JS bundle. In dev, cache-bust so Vite HMR can clear the
+      // in-memory registry while the browser would otherwise never
+      // re-execute a previously cached <script> URL.
+      const baseUrl = `/dashboard-plugins/${manifest.name}/${manifest.entry}`;
+      const scriptSrc = import.meta.env.DEV
+        ? `${baseUrl}?hermes_dv=${Date.now()}`
+        : baseUrl;
+      if (!import.meta.env.DEV) {
+        if (loadedScripts.current.has(baseUrl)) continue;
+        loadedScripts.current.add(baseUrl);
+      }
+
+      const script = document.createElement("script");
+      script.setAttribute("data-hermes-plugin", manifest.name);
+      script.src = scriptSrc;
+      script.async = true;
+      script.onerror = () => {
+        setPluginLoadError(manifest.name, "LOAD_FAILED");
+        console.warn(
+          `[plugins] Failed to load ${manifest.name} from ${scriptSrc} (open Network tab)`,
+        );
+      };
+      script.onload = () => {
+        notifyPluginRegistry();
+        queueMicrotask(() => {
+          if (getPluginComponent(manifest.name)) return;
+          setPluginLoadError(manifest.name, "NO_REGISTER");
+        });
+      };
+      document.body.appendChild(script);
+      injectedScripts.push(script);
+    }
+
+    // Give plugins a moment to load and register, then stop loading state.
+    const timeout = setTimeout(() => setLoading(false), 2000);
+    return () => {
+      clearTimeout(timeout);
+      if (import.meta.env.DEV) {
+        for (const el of injectedScripts) {
+          el.remove();
+        }
+      }
+    };
+  }, [manifests]);
+
+  // Listen for plugin registrations and resolve them against manifests.
+  useEffect(() => {
+    function resolvePlugins() {
+      const resolved: RegisteredPlugin[] = [];
+      for (const manifest of manifests) {
+        const component = getPluginComponent(manifest.name);
+        if (component) {
+          resolved.push({ manifest, component });
+        }
+      }
+      setPlugins(resolved);
+      // If all plugins registered, stop loading early.
+      if (resolved.length === manifests.length && manifests.length > 0) {
+        setLoading(false);
+      }
+    }
+
+    resolvePlugins();
+    const unsub = onPluginRegistered(resolvePlugins);
+    return unsub;
+  }, [manifests]);
+
+  return { plugins, manifests, loading };
+}