@cordfuse/crosstalk 7.0.0-alpha.9 → 7.0.0-beta.1

package/src/web/chat-pty.ts

@@ -0,0 +1,254 @@
+// chat-pty.ts — WebSocket bridge from xterm.js in the browser to a pty
+// running an agent CLI (or $SHELL) on the host.
+//
+// Lifecycle contract (Steve's directive: 'when the user exits, kill
+// the interactive agent'):
+//
+//   client connects WS /ws/chat?agent=<name>
+//     ↓
+//   server spawns a pty running the named agent (or 'bash' for --shell)
+//     ↓
+//   pty stdout → WS text frames (browser xterm.js writes them in)
+//     ↑                                                     ↓
+//   pty stdin ← WS text frames                          operator types
+//     ↓                                                     ↓
+//   when client disconnects (tab close, /exit typed by operator):
+//     pty.kill(SIGTERM) → SIGKILL 1s later if still alive
+//
+// Async-by-design contract: NO persistent session. Each WS attach
+// spawns a fresh agent. There's no detach + reattach. If you want
+// durable state, send messages through the orch bus.
+
+import type { Server as HttpServer } from 'http';
+import type { Duplex } from 'stream';
+import { WebSocketServer, type WebSocket } from 'ws';
+import { spawn as ptySpawn, type IPty } from 'node-pty';
+import { spawnSync } from 'child_process';
+import { hostname } from 'os';
+import { statSync } from 'fs';
+
+// node-pty's native bindings load under bun, but tmux/SIGHUP semantics
+// break at runtime (parallels the llmuxd 'must launch under node' issue).
+// Production is safe — commands/daemon.js spawns the dispatch loop with
+// process.execPath = node. This guard fires loudly if someone tries to
+// load the chat-pty module under bun (e.g. via `bun test` importing
+// src/api.ts, or `bun bin/crosstalk.js daemon dispatch` directly), so
+// the failure mode is a clear message instead of a mysterious tmux hang.
+declare const Bun: unknown;
+if (typeof Bun !== 'undefined') {
+  throw new Error(
+    'src/web/chat-pty.ts cannot load under bun — node-pty pty operations ' +
+    'fail at runtime (tmux/SIGHUP). Run under node instead. ' +
+    '(Production daemon already does — this guard catches test/dev mis-invocations.)',
+  );
+}
+
+/**
+ * Set of agent binary names crosstalk knows how to PTY-wrap. Matches
+ * the static list in chat.js — keep them in sync if a new agent is
+ * added to the catalog.
+ */
+const KNOWN_AGENT_BINARIES = ['claude', 'codex', 'gemini', 'qwen', 'opencode', 'agy'];
+
+interface AttachOptions {
+  agent: string;     // 'bash' (for --shell) or an entry in KNOWN_AGENT_BINARIES
+  cwd?: string;
+  cols?: number;
+  rows?: number;
+}
+
+function isOnPath(bin: string): boolean {
+  const r = spawnSync('which', [bin], { encoding: 'utf-8' });
+  return r.status === 0;
+}
+
+function resolveBinary(agent: string): string | null {
+  if (agent === 'bash') {
+    // Use $SHELL when present, fall back to bash. Matches the CLI
+    // chat --shell behavior we added in v8-native.
+    const shell = process.env['SHELL'];
+    return shell || 'bash';
+  }
+  if (!KNOWN_AGENT_BINARIES.includes(agent)) return null;
+  return isOnPath(agent) ? agent : null;
+}
+
+function safeKill(pty: IPty): void {
+  try { pty.kill('SIGTERM'); } catch { /* already gone */ }
+  setTimeout(() => {
+    try { pty.kill('SIGKILL'); } catch { /* expected if SIGTERM took */ }
+  }, 1000);
+}
+
+/**
+ * Mount the chat WebSocket onto an existing http server. Wires
+ * /ws/chat?agent=<name>&cols=<n>&rows=<n> to a pty spawn.
+ *
+ * Trust model: same as the rest of the API — engine binds 127.0.0.1,
+ * so anyone reaching the WS is on the host (or coming via the
+ * operator's tailscale-serve front). v8 auth: the upgrade handshake
+ * checks the crosstalk_session cookie via the auth middleware so a
+ * browser without a valid session can't open a chat panel even via
+ * the loopback bind.
+ */
+export interface MountChatPtyOptions {
+  /** Validates the upgrade request's auth (cookie). Returns true to
+   *  allow, false to reject (results in 401 close). When undefined,
+   *  the WS is open — caller must ensure the bind address is the
+   *  security boundary. */
+  authorize?: (req: import('http').IncomingMessage) => Promise<boolean>;
+}
+
+export function mountChatPty(server: HttpServer, opts: MountChatPtyOptions = {}): WebSocketServer {
+  // `noServer: true` so we drive the upgrade handshake ourselves and
+  // can write a proper auth rejection. With `server: server`, ws would
+  // accept the upgrade unconditionally.
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on('upgrade', async (req, socket, head) => {
+    try {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      if (url.pathname !== '/ws/chat') {
+        // Not our route — let the default 404 fall through.
+        rejectUpgrade(socket, 404, 'not found');
+        return;
+      }
+      if (opts.authorize) {
+        const ok = await opts.authorize(req);
+        if (!ok) {
+          rejectUpgrade(socket, 401, 'unauthorized');
+          return;
+        }
+      }
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        const agent = url.searchParams.get('agent') ?? 'bash';
+        const cols = clamp(Number(url.searchParams.get('cols') ?? 80), 20, 500);
+        const rows = clamp(Number(url.searchParams.get('rows') ?? 24), 5, 200);
+        const cwd = url.searchParams.get('cwd') ?? undefined;
+        bridgePty(ws, { agent, cols, rows, cwd: cwd ?? undefined });
+      });
+    } catch (err) {
+      rejectUpgrade(socket, 500, 'upgrade failure');
+      void err;
+    }
+  });
+
+  return wss;
+}
+
+function rejectUpgrade(socket: Duplex, status: number, reason: string): void {
+  try {
+    socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\n\r\n`);
+    socket.destroy();
+  } catch { /* socket already gone */ }
+}
+
+function clamp(n: number, lo: number, hi: number): number {
+  if (!Number.isFinite(n)) return lo;
+  return Math.max(lo, Math.min(hi, Math.floor(n)));
+}
+
+function bridgePty(ws: WebSocket, opts: AttachOptions): void {
+  const bin = resolveBinary(opts.agent);
+  if (!bin) {
+    ws.send(`\r\n\x1b[31mcrosstalk: agent '${opts.agent}' not on PATH or not supported.\x1b[0m\r\n`);
+    ws.close(1003, 'agent unavailable');
+    return;
+  }
+
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) if (v !== undefined) env[k] = v;
+  env.TERM = 'xterm-256color';
+
+  // Resolve cwd. Operator can pass any path via the cwd= query param,
+  // but the engine refuses to spawn into a non-existent or non-dir
+  // path — falls back to $HOME with a warning line so the session
+  // still starts. The engine already runs as the operator's user, so
+  // there's no privilege boundary to enforce beyond fs existence.
+  const home = env['HOME'] ?? '/';
+  let cwd = opts.cwd && opts.cwd.length > 0 ? opts.cwd : home;
+  let cwdWarning: string | null = null;
+  if (cwd !== home) {
+    try {
+      const st = statSync(cwd);
+      if (!st.isDirectory()) {
+        cwdWarning = `crosstalk: '${cwd}' is not a directory, falling back to $HOME (${home})`;
+        cwd = home;
+      }
+    } catch {
+      cwdWarning = `crosstalk: '${cwd}' not accessible, falling back to $HOME (${home})`;
+      cwd = home;
+    }
+  }
+
+  let pty: IPty;
+  try {
+    pty = ptySpawn(bin, [], {
+      name: 'xterm-256color',
+      cols: opts.cols ?? 80,
+      rows: opts.rows ?? 24,
+      cwd,
+      env,
+    });
+  } catch (err) {
+    ws.send(`\r\n\x1b[31mcrosstalk: spawn failed: ${(err as Error).message}\x1b[0m\r\n`);
+    ws.close(1011, 'spawn failed');
+    return;
+  }
+
+  if (cwdWarning) {
+    ws.send(`\r\n\x1b[33m${cwdWarning}\x1b[0m\r\n`);
+  }
+
+  // Greeting so the operator sees something even before the agent's
+  // own TUI renders. Sky-blue branded line + cwd + small hint.
+  const host = (() => { try { return hostname(); } catch { return 'host'; } })();
+  ws.send(`\r\n\x1b[36m── crosstalk chat: ${opts.agent} @ ${host} ────────────────\x1b[0m\r\n`);
+  ws.send(`\x1b[90m  cwd: ${cwd}\r\n  Type /exit to disconnect (or close the tab).\r\n  When you exit, this agent process is terminated.\x1b[0m\r\n\r\n`);
+
+  // pty → ws (output stream)
+  pty.onData((data) => {
+    try { ws.send(data); } catch { /* socket closing */ }
+  });
+
+  // pty exit → close ws
+  pty.onExit(({ exitCode, signal }) => {
+    try {
+      ws.send(`\r\n\x1b[36m── agent exited (code=${exitCode}${signal ? `, signal=${signal}` : ''}) ──\x1b[0m\r\n`);
+      ws.close(1000, 'agent exited');
+    } catch { /* already closed */ }
+  });
+
+  // ws → pty (input)
+  // Two message kinds:
+  //   strings — interpreted as terminal input (typed characters)
+  //   JSON { type: 'resize', cols, rows } — pty resize from the browser
+  //   JSON { type: 'exit' } — explicit operator '/exit' command
+  ws.on('message', (raw) => {
+    const text = typeof raw === 'string' ? raw : raw.toString('utf-8');
+    if (text.startsWith('{')) {
+      try {
+        const msg = JSON.parse(text) as { type?: string; cols?: number; rows?: number };
+        if (msg.type === 'resize' && typeof msg.cols === 'number' && typeof msg.rows === 'number') {
+          try { pty.resize(clamp(msg.cols, 20, 500), clamp(msg.rows, 5, 200)); } catch {}
+          return;
+        }
+        // Two terminations:
+        //   exit — graceful: SIGTERM, then SIGKILL after 1s if the
+        //          process didn't honor the TERM (matches /exit typed
+        //          in the terminal).
+        //   kill — immediate SIGKILL. No grace window. For when an
+        //          agent CLI is wedged and you want it gone NOW.
+        if (msg.type === 'exit') { safeKill(pty); return; }
+        if (msg.type === 'kill') {
+          try { pty.kill('SIGKILL'); } catch { /* already gone */ }
+          return;
+        }
+      } catch { /* fall through to treat as raw input */ }
+    }
+    try { pty.write(text); } catch { /* pty closed */ }
+  });
+
+  ws.on('close', () => safeKill(pty));
+  ws.on('error', () => safeKill(pty));
+}

package/src/web/dashboard.ts

@@ -0,0 +1,129 @@
+// dashboard.ts — / page: operator's at-a-glance state of this crosstalk
+// engine instance. Heartbeat freshness, claimed model registry, channel count,
+// recent activity, error count. Auto-refreshes every 5s.
+
+import { page, escapeHtml, relativeTime, TOAST_HELPER } from './layout.js';
+
+export interface DashboardData {
+  host: string;
+  alias: string;
+  version: string;
+  transportRoot: string;
+  heartbeat: { ts: string; pid: number; version: string; alias: string | undefined } | null;
+  cursor: string | null;
+  claimedModels: string[];
+  channels: { uuid: string; name: string | null; parent: string | null }[];
+  errorsLogged: number;
+  /** Pending work — unreplied messages grouped by recipient. Cap to top 10. */
+  pendingWork: { to: string; count: number; channelLabels: string[] }[];
+}
+
+export function dashboardPage(d: DashboardData): string {
+  const hbAge = d.heartbeat ? Date.now() - new Date(d.heartbeat.ts).getTime() : null;
+  const hbClass = hbAge === null
+    ? 'err'
+    : hbAge < 60_000 ? 'ok' : hbAge < 300_000 ? 'warn' : 'err';
+  const hbLabel = d.heartbeat ? relativeTime(d.heartbeat.ts) : 'no heartbeat yet';
+
+  const namedChannels = d.channels.filter(c => c.name).map(c => c.name as string);
+  const cursorShort = d.cursor ? d.cursor.slice(0, 8) + '…' : '—';
+
+  const body = `
+<div class="grid cols-2">
+  <section class="card">
+    <h3>Engine</h3>
+    <div class="kv"><span class="key">alias</span><span class="val brand">${escapeHtml(d.alias)}</span></div>
+    <div class="kv"><span class="key">version</span><span class="val">${escapeHtml(d.version)}</span></div>
+    <div class="kv"><span class="key">transport</span><span class="val dim">${escapeHtml(d.transportRoot)}</span></div>
+    <div class="kv"><span class="key">cursor</span><span class="val">${escapeHtml(cursorShort)}</span></div>
+  </section>
+
+  <section class="card">
+    <h3>Dispatcher</h3>
+    <div class="kv"><span class="key">heartbeat</span><span class="val ${hbClass}">${escapeHtml(hbLabel)}</span></div>
+    <div class="kv"><span class="key">pid</span><span class="val">${d.heartbeat ? d.heartbeat.pid : '—'}</span></div>
+    <div class="kv"><span class="key">claimed</span><span class="val">${d.claimedModels.length} model${d.claimedModels.length === 1 ? '' : 's'}</span></div>
+    <div class="kv"><span class="key">errors logged</span><span class="val ${d.errorsLogged > 0 ? 'warn' : 'dim'}">${d.errorsLogged}</span></div>
+  </section>
+</div>
+
+<section class="card">
+  <h3>Pending work <span style="float:right;font-size:10px;color:#7a7f87;letter-spacing:.06em">${d.pendingWork.reduce((sum, p) => sum + p.count, 0)} TOTAL</span></h3>
+  <p class="sub">Unreplied messages on the bus, grouped by recipient. A claimed model with pending work is what the dispatcher will pick up on its next tick.</p>
+  ${d.pendingWork.length === 0
+    ? '<p class="empty">No pending work — every message on the bus has a reply.</p>'
+    : d.pendingWork.slice(0, 10).map(p => {
+        const isClaimedHere = d.claimedModels.some(m => m === p.to || p.to.startsWith(m + '@'));
+        const badge = isClaimedHere ? '<span class="chip brand" title="claimed by this dispatcher">us</span>' : '';
+        return `<div style="display:flex;justify-content:space-between;align-items:center;gap:10px;padding:8px 0;border-bottom:1px solid #1f2329">
+          <div style="min-width:0;flex:1 1 auto"><span class="chip">${escapeHtml(p.to)}</span> ${badge}<div style="font-size:10px;color:#7a7f87;margin-top:4px">in ${p.channelLabels.map(escapeHtml).join(', ')}</div></div>
+          <div style="font-weight:600;color:${isClaimedHere ? '#7ee787' : '#d29922'};font-size:18px">${p.count}</div>
+        </div>`;
+      }).join('')}
+</section>
+
+<section class="card">
+  <h3>Claimed models</h3>
+  ${d.claimedModels.length === 0
+    ? '<p class="empty">No models claimed on this dispatcher. Check <code>data/crosstalk.yaml</code> + that the CLI binaries are on PATH.</p>'
+    : d.claimedModels.map(m => `<span class="chip brand">${escapeHtml(m)}</span>`).join('')}
+</section>
+
+<section class="card">
+  <h3>Channels (${d.channels.length})</h3>
+  <p class="sub">Click a channel to open the threaded message view + send form.</p>
+  ${d.channels.length === 0
+    ? '<p class="empty">No channels yet. Create one with <code>crosstalk channel &lt;name&gt;</code>.</p>'
+    : d.channels.map(c => {
+        const handle = c.name ?? c.uuid;
+        const display = c.name ? escapeHtml(c.name) : `<span style="color:#7a7f87">${escapeHtml(c.uuid.slice(0,8))}…</span>`;
+        return `<a href="/c/${encodeURIComponent(handle)}" style="display:block;padding:8px 0;border-bottom:1px solid #1f2329"><span class="chip brand">${display}</span> <span style="color:#7a7f87;font-size:11px;margin-left:8px">${escapeHtml(c.uuid)}</span></a>`;
+      }).join('')}
+</section>
+`;
+
+  return page({
+    title: `crosstalk on ${d.host} · Dashboard`,
+    host: d.host,
+    alias: d.alias,
+    activeNav: 'dashboard',
+    body,
+    inlineScript: `${TOAST_HELPER}
+// SSE subscription — engine pushes 'snapshot' (initial) + 'update'
+// (whenever cursor or heartbeat changes). When we see an update, reload
+// the page so the cards re-render with the new values. Falls back to
+// 5s polling if SSE isn't available (e.g., behind a buffering proxy).
+let lastCursor = ${JSON.stringify(d.cursor)};
+let lastHb = ${JSON.stringify(d.heartbeat?.ts ?? null)};
+let sseConnected = false;
+try {
+  const es = new EventSource('/events');
+  es.addEventListener('open', () => { sseConnected = true; });
+  es.addEventListener('update', (e) => {
+    try {
+      const data = JSON.parse(e.data);
+      const curCursor = data.cursor ?? null;
+      const curHb = data.heartbeat?.ts ?? null;
+      if (curCursor !== lastCursor || curHb !== lastHb) {
+        location.reload();
+      }
+    } catch (_) {}
+  });
+  es.addEventListener('error', () => { /* browser will retry; we don't fall back unless sseConnected stayed false for > 10s */ });
+} catch (_) {}
+// Poll fallback — fires only if SSE never connected.
+setTimeout(() => {
+  if (sseConnected) return;
+  setInterval(async () => {
+    try {
+      const r = await fetch('/status');
+      if (!r.ok) return;
+      const s = await r.json();
+      const curCursor = s.cursor ?? null;
+      const curHb = s.heartbeat?.ts ?? null;
+      if (curCursor !== lastCursor || curHb !== lastHb) location.reload();
+    } catch (_) {}
+  }, 5000);
+}, 10000);`,
+  });
+}

package/src/web/layout.ts

@@ -0,0 +1,237 @@
+// layout.ts — shared HTML/CSS chrome for the crosstalk web UI.
+//
+// Design language matches the @cordfuse/llmux picker (dark navy bg,
+// sky-blue accents, monospace) so a single Cordfuse operator sees a
+// consistent visual family across tools. Layout is async-by-design:
+// dashboards, channel browser, threaded message view, dispatcher
+// status. The chat panel (interactive agent attach) is Phase 2 — pty
+// over WebSocket + xterm.js, fresh agent per attach, killed on close.
+
+const BRAND_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><rect width="512" height="512" rx="90" ry="90" fill="#0b0c10"/><rect x="1.5" y="1.5" width="509" height="509" rx="89" ry="89" fill="none" stroke="#7cc4ff" stroke-width="1.5" stroke-opacity="0.22"/><text x="256" y="236" text-anchor="middle" dominant-baseline="central" font-family="'Noto Sans Mono', 'Courier New', monospace" font-size="155" font-weight="700" fill="#7cc4ff" letter-spacing="-3">{Ct}</text></svg>`;
+const FAVICON_DATA_URL = `data:image/svg+xml,${encodeURIComponent(BRAND_SVG)}`;
+
+export function escapeHtml(s: string | null | undefined): string {
+  return String(s ?? '').replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[c]!));
+}
+
+export function relativeTime(iso: string | null | undefined): string {
+  if (!iso) return '—';
+  const ms = Date.now() - new Date(iso).getTime();
+  if (Number.isNaN(ms)) return iso;
+  if (ms < 0) return 'in the future';
+  if (ms < 5_000) return 'just now';
+  if (ms < 60_000) return Math.floor(ms / 1000) + 's ago';
+  if (ms < 3_600_000) return Math.floor(ms / 60_000) + 'm ago';
+  if (ms < 86_400_000) return Math.floor(ms / 3_600_000) + 'h ago';
+  return Math.floor(ms / 86_400_000) + 'd ago';
+}
+
+interface NavItem {
+  id: string;
+  label: string;
+  icon: string;
+  href: string;
+}
+
+const NAV: NavItem[] = [
+  { id: 'dashboard', label: 'Dashboard', icon: '▦', href: '/' },
+  { id: 'chat',      label: 'Chat',      icon: '◉', href: '/chat' },
+  { id: 'channels',  label: 'Channels',  icon: '⇄', href: '/c' },
+  { id: 'workflows', label: 'Workflows', icon: '⎇', href: '/w' },
+  { id: 'tokens',    label: 'Tokens',    icon: '⚿', href: '/tokens' },
+  { id: 'agents',    label: 'Agents',    icon: '⌬', href: '/agents' },
+  { id: 'logs',      label: 'Logs',      icon: '▤', href: '/logs' },
+  { id: 'settings',  label: 'Settings',  icon: '⚙', href: '/settings' },
+  { id: 'account',   label: 'Account',   icon: '◐', href: '/account' },
+  { id: 'users',     label: 'Users',     icon: '☷', href: '/users' },
+  { id: 'about',     label: 'About',     icon: 'ⓘ', href: '/about' },
+];
+
+function navDrawer(opts: { host: string; alias: string; activeId?: string }): string {
+  const links = NAV.map((it) => {
+    const active = it.id === opts.activeId ? ' class="active"' : '';
+    return `    <a href="${escapeHtml(it.href)}"${active}><span class="nav-icon">${it.icon}</span>${escapeHtml(it.label)}</a>`;
+  }).join('\n');
+  return `<div id="nav-backdrop" aria-hidden="true"></div>
+<aside id="nav-drawer" aria-hidden="true">
+  <div class="nav-header">
+    <span class="nav-brand">CROSSTALK</span>
+    <span class="nav-host">${escapeHtml(opts.host)}</span>
+    <span class="nav-alias">alias: ${escapeHtml(opts.alias)}</span>
+  </div>
+  <nav>
+${links}
+  </nav>
+</aside>`;
+}
+
+function commonStyles(): string {
+  return `
+  :root{color-scheme:dark}
+  html,body{margin:0;background:#0b0c10;color:#e6e8eb;font-family:ui-monospace,monospace;font-size:14px;overflow-x:hidden}
+  body{padding:18px 16px 80px;max-width:980px;margin:0 auto;box-sizing:border-box}
+  a{color:#7cc4ff;text-decoration:none}
+  a:hover{text-decoration:underline}
+  header{display:flex;flex-direction:column;align-items:stretch;gap:8px;margin-bottom:18px}
+  header .header-controls{display:flex;justify-content:space-between;align-items:center;gap:10px;flex-wrap:wrap}
+  h1{font-size:18px;margin:0}
+  h1 .brand{color:#7cc4ff;letter-spacing:.08em;font-weight:600}
+  h1 .host{color:#a371f7;font-weight:500;margin-left:8px}
+  h1 .page-title{color:#a371f7;font-weight:500;margin-left:8px}
+  #meta{color:#7a7f87;font-size:11px;display:flex;gap:8px;align-items:center;flex-wrap:wrap}
+  #meta .dot{display:inline-block;width:8px;height:8px;border-radius:50%;background:#7ee787}
+  #meta .dot.stale{background:#d29922}
+  #meta .dot.dead{background:#f85149}
+  #nav-toggle{background:#1c2128;color:#e6e8eb;border:1px solid #262c34;border-radius:6px;width:34px;height:34px;display:inline-flex;align-items:center;justify-content:center;cursor:pointer;padding:0;font-size:18px;line-height:1;margin-right:10px;flex:0 0 auto;transition:background 150ms ease,border-color 150ms ease}
+  #nav-toggle:hover{background:#252b34;border-color:#3a414b}
+  #nav-toggle:active{transform:scale(.94)}
+  #nav-drawer{position:fixed;top:0;left:-300px;width:280px;height:100dvh;background:#0e1116;border-right:1px solid #1f2329;transition:left 220ms ease;z-index:55;padding:18px 0;box-sizing:border-box;display:flex;flex-direction:column}
+  #nav-drawer.open{left:0}
+  #nav-backdrop{position:fixed;inset:0;background:rgba(11,12,16,.55);z-index:54;opacity:0;visibility:hidden;transition:opacity 180ms ease,visibility 0s 180ms}
+  #nav-backdrop.show{opacity:1;visibility:visible;transition:opacity 180ms ease}
+  #nav-drawer .nav-header{padding:0 20px 16px;border-bottom:1px solid #1f2329;display:flex;flex-direction:column;gap:4px}
+  #nav-drawer .nav-brand{color:#7cc4ff;font-weight:600;letter-spacing:.08em;font-size:15px}
+  #nav-drawer .nav-host{color:#a371f7;font-size:12px}
+  #nav-drawer .nav-alias{color:#7a7f87;font-size:11px;margin-top:2px}
+  #nav-drawer nav{flex:1;display:flex;flex-direction:column;padding:8px 0;overflow-y:auto}
+  #nav-drawer a{display:flex;align-items:center;gap:10px;padding:12px 20px;color:#c9d1d9;text-decoration:none;font-size:14px;border-left:3px solid transparent;cursor:pointer}
+  #nav-drawer a:hover{background:#11141a;text-decoration:none}
+  #nav-drawer a.active{border-left-color:#7cc4ff;color:#7cc4ff;background:#11141a}
+  #nav-drawer a .nav-icon{font-size:16px;width:20px;text-align:center;color:inherit}
+  .card{background:#11141a;border:1px solid #1f2329;border-radius:8px;padding:14px 16px;margin-bottom:14px}
+  .card h3{margin:0 0 10px;font-size:13px;color:#7cc4ff;font-weight:600;letter-spacing:.05em;text-transform:uppercase}
+  .card .sub{margin:-6px 0 10px;font-size:11px;color:#9aa0a6;line-height:1.5}
+  .kv{display:flex;justify-content:space-between;gap:14px;padding:6px 0;border-bottom:1px solid #1f2329;font-size:13px}
+  .kv:last-child{border-bottom:none}
+  .kv .key{color:#9aa0a6}
+  .kv .val{color:#e6e8eb;font-family:ui-monospace,monospace;text-align:right;word-break:break-word}
+  .kv .val.dim{color:#7a7f87}
+  .kv .val.ok{color:#7ee787}
+  .kv .val.warn{color:#d29922}
+  .kv .val.err{color:#f85149}
+  .kv .val.brand{color:#7cc4ff}
+  .grid{display:grid;grid-template-columns:1fr;gap:14px;margin-bottom:14px}
+  @media (min-width:601px){.grid.cols-2{grid-template-columns:1fr 1fr}}
+  .chip{display:inline-block;background:#1c2128;color:#c9d1d9;border:1px solid #262c34;border-radius:12px;padding:3px 10px;font-size:11px;margin:2px 4px 2px 0}
+  .chip.brand{color:#7cc4ff;border-color:#2d4a66}
+  .empty{color:#7a7f87;font-style:italic;text-align:center;padding:24px 0}
+  /* Threaded message view (mirrors @cordfuse/llmux's /orch pattern). */
+  .thread{margin-bottom:18px;border:1px solid #262c34;border-left:4px solid #2d4a66;border-radius:8px;padding:12px;background:#0d0f14}
+  .thread .msg{margin-bottom:8px}
+  .thread .msg:last-of-type{margin-bottom:0}
+  .thread-summary{font-size:10px;color:#7cc4ff;text-transform:uppercase;letter-spacing:.08em;padding:0 0 8px 4px;font-weight:600}
+  .msg{background:#11141a;border:1px solid #1f2329;border-radius:8px;padding:12px 14px}
+  .msg.reply{margin-left:36px;background:#161a22;border-left:3px solid #2d4a66;position:relative}
+  .msg.reply::before{content:"";position:absolute;left:-22px;top:18px;width:18px;height:2px;background:#2d4a66}
+  @media (max-width:600px){
+    .msg.reply{margin-left:20px}
+    .msg.reply::before{left:-14px;width:12px}
+  }
+  .msg-head{display:flex;justify-content:space-between;gap:12px;font-size:12px;color:#9aa0a6;margin-bottom:8px;align-items:baseline;flex-wrap:wrap}
+  .msg-route{display:inline-flex;gap:6px;align-items:baseline;flex-wrap:wrap}
+  .msg-from{color:#7cc4ff;font-weight:600}
+  .msg-arrow{color:#7a7f87}
+  .msg-to{color:#7ee787}
+  .msg-re{color:#f0883e;font-size:11px;margin-left:6px}
+  .msg-id{font-family:ui-monospace,monospace;font-size:11px;color:#7a7f87}
+  .msg-body{white-space:pre-wrap;font:12px ui-monospace,monospace;background:#0b0c10;padding:10px 12px;border-radius:6px;color:#e6e8eb;max-height:400px;overflow:auto;border:1px solid #1f2329}
+  .msg-failed{margin-top:6px;color:#f85149;font-size:11px}
+  /* Forms (send-message, channel-create, etc.) */
+  .field{display:flex;flex-direction:column;gap:4px;margin-bottom:12px}
+  .field label{font-size:11px;color:#9aa0a6;text-transform:uppercase;letter-spacing:.05em}
+  .field input,.field textarea,.field select{background:#0b0c10;color:#e6e8eb;border:1px solid #262c34;border-radius:6px;padding:8px 10px;font:13px ui-monospace,monospace;outline:none;width:100%;box-sizing:border-box}
+  .field input:focus,.field textarea:focus,.field select:focus{border-color:#2d4a66}
+  .field textarea{min-height:90px;resize:vertical}
+  .actions{display:flex;gap:8px;justify-content:flex-end;align-items:center}
+  button{background:#1c2128;color:#e6e8eb;border:1px solid #262c34;border-radius:6px;padding:8px 14px;font:13px ui-monospace,monospace;cursor:pointer;transition:background 150ms ease,border-color 150ms ease}
+  button:hover:not(:disabled){background:#252b34;border-color:#3a414b}
+  button.primary{color:#7cc4ff;border-color:#2d4a66}
+  button.primary:hover:not(:disabled){background:#11141a}
+  button:disabled{opacity:.4;cursor:not-allowed}
+  .toast{position:fixed;bottom:24px;left:50%;transform:translateX(-50%) translateY(80px);background:#11141a;border:1px solid #1f2329;border-radius:8px;padding:10px 16px;font-size:13px;z-index:80;opacity:0;transition:opacity 180ms ease,transform 220ms ease;pointer-events:none;max-width:90vw;text-align:center}
+  .toast.show{opacity:1;transform:translateX(-50%) translateY(0)}
+  .toast.ok{color:#7ee787;border-color:#1f4528}
+  .toast.err{color:#f85149;border-color:#4a2329}
+  `;
+}
+
+export const TOAST_HELPER = `
+window.showToast = function(msg, kind){
+  const t = document.getElementById('toast');
+  if (!t) return;
+  t.textContent = msg;
+  t.className = 'toast show ' + (kind || 'ok');
+  clearTimeout(window._toastTimer);
+  window._toastTimer = setTimeout(() => { t.className = 'toast ' + (kind || 'ok'); }, 3000);
+};
+`;
+
+const NAV_TOGGLE_SCRIPT = `<script>
+(() => {
+  const drawer = document.getElementById('nav-drawer');
+  const backdrop = document.getElementById('nav-backdrop');
+  const toggle = document.getElementById('nav-toggle');
+  if (!drawer || !backdrop || !toggle) return;
+  const open = () => { drawer.classList.add('open'); backdrop.classList.add('show'); drawer.setAttribute('aria-hidden','false'); };
+  const close = () => { drawer.classList.remove('open'); backdrop.classList.remove('show'); drawer.setAttribute('aria-hidden','true'); };
+  toggle.addEventListener('click', () => drawer.classList.contains('open') ? close() : open());
+  backdrop.addEventListener('click', close);
+  document.addEventListener('keydown', e => { if (e.key === 'Escape') close(); });
+})();
+</script>`;
+
+export interface PageOpts {
+  title: string;
+  host: string;
+  alias: string;
+  /** Marks the active nav item. Use one of: 'dashboard'|'channels'|'agents'. */
+  activeNav?: string;
+  /** Short page subtitle shown in the header next to host. */
+  pageTitle?: string;
+  /** Extra CSS rules appended after commonStyles(). */
+  extraCss?: string;
+  /** Body HTML. */
+  body: string;
+  /** Inline JS to run after the body. */
+  inlineScript?: string;
+  /** Override the viewport meta. Chat page passes
+   *  `interactive-widget=resizes-content` so the soft keyboard
+   *  resizes the viewport (pushing the bottom bar up) instead of
+   *  overlaying it. */
+  viewport?: string;
+}
+
+export function page(opts: PageOpts): string {
+  const css = commonStyles() + (opts.extraCss ?? '');
+  const titleSuffix = opts.pageTitle ? ` <span class="page-title">· ${escapeHtml(opts.pageTitle)}</span>` : '';
+  const viewport = opts.viewport ?? 'width=device-width,initial-scale=1';
+  return `<!doctype html><html lang="en"><head>
+<meta charset="utf-8"><meta name="viewport" content="${escapeHtml(viewport)}">
+<title>${escapeHtml(opts.title)}</title>
+<link rel="icon" href="${FAVICON_DATA_URL}">
+<link rel="apple-touch-icon" href="${FAVICON_DATA_URL}">
+<meta name="theme-color" content="#0b0c10">
+<style>${css}</style>
+</head><body>
+${navDrawer({ host: opts.host, alias: opts.alias, ...(opts.activeNav ? { activeId: opts.activeNav } : {}) })}
+<header>
+  <div class="header-controls">
+    <h1><button id="nav-toggle" aria-label="open navigation" type="button">≡</button><span class="brand">CROSSTALK</span> <span class="host">${escapeHtml(opts.host)}</span>${titleSuffix}</h1>
+    <div id="meta">
+      <span class="dot" id="liveness-dot"></span>
+      <span id="liveness-label">live · 5s</span>
+      <span>·</span>
+      <span>alias ${escapeHtml(opts.alias)}</span>
+    </div>
+  </div>
+</header>
+<main>
+${opts.body}
+</main>
+<div class="toast" id="toast" role="status" aria-live="polite"></div>
+${NAV_TOGGLE_SCRIPT}
+${opts.inlineScript ? '<script>' + opts.inlineScript + '</script>' : ''}
+</body></html>`;
+}