@blackbelt-technology/pi-agent-dashboard 0.4.5 → 0.5.0

package/packages/shared/src/bootstrap-install.ts

@@ -12,8 +12,15 @@
  *
  * See change: unified-bootstrap-install.
  */
-import { spawn as cpSpawn } from "./platform/exec.js";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { spawn as cpSpawn, spawnSync as cpSpawnSync } from "./platform/exec.js";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import path from "node:path";
 import { getManagedDir } from "./managed-paths.js";
 import { getDefaultRegistry, type ToolRegistry } from "./tool-registry/index.js";
@@ -210,3 +217,190 @@ export async function bootstrapInstallDefaults(
     progress,
   });
 }
+
+// ── Managed Node runtime install ───────────────────────────────────────
+//
+// See change: embed-managed-node-runtime (spec: managed-node-runtime).
+//
+// `installManagedNode` copies a bundled Node distribution into
+// `<managedDir>/node/` and writes a `<managedDir>/node/.version` marker.
+// Idempotent: skip when marker matches the bundled version, replace on
+// mismatch, no-op when the bundled source isn't available (standalone
+// CLI install with no Electron resources).
+
+export interface InstallManagedNodeOptions {
+  /**
+   * Source directory containing the bundled Node distribution.
+   * Layout matches the upstream Node zip/tar:
+   *   Windows: `<dir>/node.exe`, `<dir>/npm.cmd`, `<dir>/npx.cmd`
+   *   Unix:    `<dir>/bin/node`, `<dir>/bin/npm`, `<dir>/bin/npx`
+   *
+   * Caller resolves this (Electron uses `path.dirname(getBundledNodePath())`
+   * after stripping the platform-specific suffix). Pass `null` /
+   * `undefined` for the standalone CLI install case — the function
+   * no-ops without error.
+   */
+  bundledNodeDir?: string | null;
+  /** Root of the managed install. Defaults to `getManagedDir()`. */
+  managedDir?: string;
+  /** Called on every progress tick. Mirrors `bootstrapInstall` shape. */
+  progress?: ProgressCallback;
+  /**
+   * Test seam: override how the bundled Node version is read. Default
+   * spawns `<bundledNodeDir>/bin/node --version` (or `node.exe` on
+   * Windows) and trims stdout. Tests inject a fake to avoid real spawns.
+   */
+  _readVersion?: (sourceBinary: string) => string | null;
+}
+
+export interface InstallManagedNodeResult {
+  /** True iff the operation succeeded (including the no-op cases). */
+  ok: boolean;
+  /** Did we actually copy files? false when no-op or skipped. */
+  copied: boolean;
+  /** Resolved managed Node directory (`<managedDir>/node`). */
+  managedNodeDir: string;
+  /** Bundled Node version (e.g. `v22.12.0`) when known. */
+  version?: string;
+  /** Reason for skip / failure. Always set when `copied === false`. */
+  reason?: string;
+  /** Error message when `ok === false`. */
+  error?: string;
+}
+
+/** Path to the source `node` / `node.exe` binary inside `bundledNodeDir`. */
+function sourceNodeBinary(bundledNodeDir: string): string {
+  return process.platform === "win32" // platform-branch-ok: Node distribution layout differs Windows vs Unix
+    ? path.join(bundledNodeDir, "node.exe")
+    : path.join(bundledNodeDir, "bin", "node");
+}
+
+/**
+ * Spawn `<nodeBinary> --version` and return the trimmed stdout (e.g.
+ * `v22.12.0`). Returns null on failure or when the binary is missing.
+ * Synchronous because bootstrap is naturally serial.
+ */
+function readNodeVersion(nodeBinary: string): string | null {
+  if (!existsSync(nodeBinary)) return null;
+  try {
+    const r = cpSpawnSync(nodeBinary, ["--version"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 5_000,
+      encoding: "utf-8",
+    });
+    if (r.status !== 0) return null;
+    const out = (r.stdout ?? "").toString().trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read the `<managedNodeDir>/.version` marker if present, else null. */
+function readManagedMarker(managedNodeDir: string): string | null {
+  const markerPath = path.join(managedNodeDir, ".version");
+  if (!existsSync(markerPath)) return null;
+  try {
+    return readFileSync(markerPath, "utf-8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Idempotently copy the bundled Node distribution into `<managedDir>/node/`.
+ *
+ * - First-run: full recursive copy + write `.version` marker.
+ * - Re-run with matching marker: no-op.
+ * - Mismatched marker (or missing marker with dir present): replace +
+ *   rewrite marker.
+ * - Bundled source absent or `bundledNodeDir == null`: no-op.
+ * - Failed copy mid-flight: marker NOT written, so next call retries.
+ */
+export async function installManagedNode(
+  opts: InstallManagedNodeOptions = {},
+): Promise<InstallManagedNodeResult> {
+  const managedDir = opts.managedDir ?? getManagedDir();
+  const managedNodeDir = path.join(managedDir, "node");
+  const step = "node-runtime";
+
+  const bundledDir = opts.bundledNodeDir ?? null;
+  if (!bundledDir) {
+    return {
+      ok: true,
+      copied: false,
+      managedNodeDir,
+      reason: "no bundled source",
+    };
+  }
+
+  const sourceBinary = sourceNodeBinary(bundledDir);
+  const sourceVersion = (opts._readVersion ?? readNodeVersion)(sourceBinary);
+  if (!sourceVersion) {
+    return {
+      ok: true,
+      copied: false,
+      managedNodeDir,
+      reason: `bundled node binary missing or unreadable: ${sourceBinary}`,
+    };
+  }
+
+  const existingMarker = readManagedMarker(managedNodeDir);
+  if (existingMarker === sourceVersion) {
+    return {
+      ok: true,
+      copied: false,
+      managedNodeDir,
+      version: sourceVersion,
+      reason: "version matches bundled — no copy needed",
+    };
+  }
+
+  opts.progress?.({
+    step,
+    status: "running",
+    output: `Installing Node ${sourceVersion} runtime`,
+  });
+
+  try {
+    // Replace any existing dir (handles the mismatch + missing-marker
+    // cases) so the copy is from a clean slate.
+    if (existsSync(managedNodeDir)) {
+      rmSync(managedNodeDir, { recursive: true, force: true });
+    }
+    mkdirSync(path.dirname(managedNodeDir), { recursive: true });
+
+    cpSync(bundledDir, managedNodeDir, {
+      recursive: true,
+      force: true,
+      // dereference: false keeps symlinks-as-symlinks (Unix npm shim).
+      // verbatimSymlinks would also work in newer Node; default is fine.
+    });
+
+    // Marker last — partial copy on failure leaves no marker, so the
+    // next invocation treats the dir as missing and retries.
+    writeFileSync(
+      path.join(managedNodeDir, ".version"),
+      sourceVersion + "\n",
+      "utf-8",
+    );
+
+    opts.progress?.({ step, status: "done", output: `Node ${sourceVersion}` });
+    return {
+      ok: true,
+      copied: true,
+      managedNodeDir,
+      version: sourceVersion,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    opts.progress?.({ step, status: "error", error: message });
+    return {
+      ok: false,
+      copied: false,
+      managedNodeDir,
+      version: sourceVersion,
+      error: message,
+    };
+  }
+}

package/packages/shared/src/browser-protocol.ts

@@ -127,6 +127,33 @@ export interface SpawnResultBrowserMessage {
   message: string;
 }
 
+/**
+ * Failure classification codes for spawn errors.
+ * Set on every `{ success: false }` path inside process-manager and the
+ * session-action-handler. Additive — clients that do not know a code fall
+ * back to the `message` string.
+ * See change: spawn-failure-diagnostics.
+ */
+export type SpawnFailureCode =
+  | "DIR_MISSING"
+  | "PI_NOT_FOUND"
+  | "WIN_PI_CMD_ONLY"
+  | "WT_MISSING"
+  | "TMUX_MISSING"
+  | "PI_CRASHED"
+  | "SPAWN_ERRNO"
+  | "PREFLIGHT_FAILED"
+  | "REGISTER_TIMEOUT";
+
+/**
+ * A single reason from the synchronous spawn preflight check.
+ * See change: spawn-failure-diagnostics.
+ */
+export interface PreflightReason {
+  code: string;
+  message: string;
+}
+
 /**
  * Emitted when a session spawn fails — either because `spawnPiSession` threw,
  * returned `{ success: false }`, or the spawned child crashed immediately.
@@ -140,6 +167,37 @@ export interface SpawnErrorMessage {
   message: string;
   /** Up to ~2 KB tail of stderr captured from the failed child, if any. */
   stderr?: string;
+  /** Structured failure classifier. Additive — old clients ignore this field. See change: spawn-failure-diagnostics. */
+  code?: SpawnFailureCode;
+  /** Preflight failure reasons. Only set when code === "PREFLIGHT_FAILED". See change: spawn-failure-diagnostics. */
+  reasons?: PreflightReason[];
+}
+
+/**
+ * Emitted when a spawned pi session never sends `session_register` within
+ * the configured `spawnRegisterTimeoutMs` window.
+ * See change: spawn-failure-diagnostics.
+ */
+export interface SpawnRegisterTimeoutMessage {
+  type: "spawn_register_timeout";
+  cwd: string;
+  /** Present for headless spawns; absent for tmux/wt/wsl-tmux. */
+  pid?: number;
+  /** Last 4 KB of the per-session stderr log, if available. */
+  stderrTail?: string;
+  /** The effective watchdog timeout in ms — so the UI can render e.g. "30s". See change: spawn-failure-diagnostics (fix W2). */
+  timeoutMs?: number;
+}
+
+/**
+ * Emitted when pi finally registers AFTER the watchdog already fired.
+ * The UI uses it to auto-clear the timeout banner for the given cwd.
+ * See change: spawn-failure-diagnostics.
+ */
+export interface SpawnRegisterRecoveredMessage {
+  type: "spawn_register_recovered";
+  cwd: string;
+  pid?: number;
 }
 
 export interface SessionsReorderedMessage {
@@ -148,6 +206,28 @@ export interface SessionsReorderedMessage {
   sessionIds: string[];
 }
 
+/**
+ * Atomic on-connect snapshot of the server's full session registry and
+ * per-cwd ordering. Replaces the legacy per-session `session_added` loop
+ * + per-cwd `sessions_reordered` loop that the gateway used to emit on
+ * each browser WS connect. Client SHALL replace its `sessions` Map and
+ * `sessionOrderMap` with this payload (no merging) so stale ids from a
+ * previous server lifetime are dropped atomically.
+ *
+ * Live updates after the snapshot continue using the incremental
+ * `session_added` / `session_updated` / `session_removed` /
+ * `sessions_reordered` messages.
+ *
+ * See change: fix-stale-sessions-on-reconnect.
+ */
+export interface SessionsSnapshotMessage {
+  type: "sessions_snapshot";
+  /** Every session known to the server at construction time, alive AND ended. */
+  sessions: DashboardSession[];
+  /** cwd → ordered session ids. Only non-empty arrays are included. */
+  orders: Record<string, string[]>;
+}
+
 export interface PinnedDirsUpdatedMessage {
   type: "pinned_dirs_updated";
   paths: string[];
@@ -362,6 +442,23 @@ export interface BrowserExtUiDecoratorMessage {
   removed?: boolean;
 }
 
+/**
+ * Server → browser: register a base64-encoded image asset under a content
+ * hash for the given session. Forwarded verbatim from the bridge's
+ * `asset_register` message and replayed to reconnecting browsers (in
+ * chronological position relative to its referencing `message_update` /
+ * `message_end`). The client populates a per-session `Map<hash,{data,mime}>`
+ * consumed by the `MarkdownContent` `pi-asset:` resolver.
+ * See change: chat-markdown-local-images-and-math.
+ */
+export interface BrowserAssetRegisterMessage {
+  type: "asset_register";
+  sessionId: string;
+  hash: string;
+  mimeType: string;
+  data: string;
+}
+
 /** Sent when a plugin's config changes; carries only that plugin's namespace. */
 export interface PluginConfigUpdateMessage {
   type: "plugin_config_update";
@@ -392,7 +489,10 @@ export type ServerToBrowserMessage =
   | ResumeResultBrowserMessage
   | SpawnResultBrowserMessage
   | SpawnErrorMessage
+  | SpawnRegisterTimeoutMessage
+  | SpawnRegisterRecoveredMessage
   | SessionsReorderedMessage
+  | SessionsSnapshotMessage
   | PinnedDirsUpdatedMessage
   | TerminalAddedMessage
   | TerminalRemovedMessage
@@ -416,7 +516,8 @@ export type ServerToBrowserMessage =
   | BootstrapTicketCompleteMessage
   | BrowserUiModulesListMessage
   | BrowserUiDataListMessage
-  | BrowserExtUiDecoratorMessage;
+  | BrowserExtUiDecoratorMessage
+  | BrowserAssetRegisterMessage;
 
 // ── Browser → Server ────────────────────────────────────────────────
 
@@ -476,6 +577,15 @@ export interface RequestModelsBrowserMessage {
   sessionId: string;
 }
 
+/**
+ * Browser asks the server to forward `request_providers` to the bridge.
+ * See change: replace-hardcoded-provider-lists.
+ */
+export interface RequestProvidersBrowserMessage {
+  type: "request_providers";
+  sessionId: string;
+}
+
 export interface SetThinkingLevelBrowserMessage {
   type: "set_thinking_level";
   sessionId: string;
@@ -769,6 +879,7 @@ export type BrowserToServerMessage =
   | OpenSpecRefreshBrowserMessage
   | RenameSessionBrowserMessage
   | RequestModelsBrowserMessage
+  | RequestProvidersBrowserMessage
   | SetThinkingLevelBrowserMessage
   | SetModelBrowserMessage
   | ShutdownBrowserMessage

package/packages/shared/src/config.ts

@@ -134,6 +134,13 @@ export interface DashboardConfig {
   editor: EditorConfig;
   /** OpenSpec background polling behavior (interval, concurrency, change detection, jitter) */
   openspec: OpenSpecPollConfig;
+  /**
+   * Timeout for ask_user prompts in seconds.
+   * Default: 300 (5 minutes).
+   * Set to -1 (or any value <= 0) for no timeout (waits indefinitely).
+   * If the key is absent from config.json the default of 300 s applies.
+   */
+  askUserPromptTimeoutSeconds: number;
   /** Networks trusted for full access without authentication (CIDR, wildcard, exact IP) */
   trustedNetworks: string[];
   /** Merged trustedNetworks + auth.bypassHosts (deduplicated). Computed at load time. */
@@ -152,6 +159,12 @@ export interface DashboardConfig {
   reattachPlacement: ReattachPlacement;
   /** Persisted list of known remote servers */
   knownServers: KnownServer[];
+  /**
+   * How long (ms) to wait for a spawned pi session to send `session_register`
+   * before emitting a timeout warning. Default 30000 (30s). Clamped [5000, 120000].
+   * See change: spawn-failure-diagnostics.
+   */
+  spawnRegisterTimeoutMs: number;
   /**
    * Per-plugin config namespaces. Reserved top-level key.
    * Each plugin's config lives at plugins.<id>.*
@@ -168,6 +181,16 @@ export interface CorsConfig {
 
 const VALID_SPAWN_STRATEGIES: SpawnStrategy[] = ["tmux", "headless"];
 
+/** Default ask_user prompt timeout: 300 seconds (5 minutes). */
+export const DEFAULT_ASK_USER_PROMPT_TIMEOUT_SECONDS = 300;
+
+/** Default + clamp for spawnRegisterTimeoutMs. See change: spawn-failure-diagnostics. */
+export const DEFAULT_SPAWN_REGISTER_TIMEOUT_MS = 30000;
+export function clampSpawnRegisterTimeoutMs(v: unknown): number {
+  if (typeof v !== "number" || isNaN(v)) return DEFAULT_SPAWN_REGISTER_TIMEOUT_MS;
+  return Math.max(5000, Math.min(120000, v));
+}
+
 const DEFAULTS: DashboardConfig = {
   plugins: {},
   port: 8000,
@@ -187,7 +210,9 @@ const DEFAULTS: DashboardConfig = {
   cors: { allowedOrigins: [] },
   electronMode: false,
   knownServers: [],
+  askUserPromptTimeoutSeconds: DEFAULT_ASK_USER_PROMPT_TIMEOUT_SECONDS,
   reattachPlacement: DEFAULT_REATTACH_PLACEMENT,
+  spawnRegisterTimeoutMs: 30000,
 };
 
 /**
@@ -385,6 +410,10 @@ export function loadConfig(): DashboardConfig {
       knownServers: parseKnownServers(parsed.knownServers),
       reattachPlacement: parseReattachPlacement(parsed.reattachPlacement),
       plugins: parsePluginsConfig(parsed.plugins),
+      askUserPromptTimeoutSeconds: typeof parsed.askUserPromptTimeoutSeconds === "number"
+        ? parsed.askUserPromptTimeoutSeconds
+        : defaults.askUserPromptTimeoutSeconds,
+      spawnRegisterTimeoutMs: clampSpawnRegisterTimeoutMs(parsed.spawnRegisterTimeoutMs),
     };
 
     // Compute resolvedTrustedNetworks: merge trustedNetworks + auth.bypassHosts

package/packages/shared/src/dashboard-starter.ts

@@ -0,0 +1,33 @@
+/**
+ * DashboardStarter — identifies who launched the dashboard server process.
+ *
+ * "Bridge"     — spawned by the pi bridge extension (server-launcher.ts).
+ * "Standalone" — invoked directly via CLI (`pi-dashboard` or `pi-dashboard start`).
+ * "Electron"   — spawned by the Electron main process.
+ *
+ * The value is injected via the DASHBOARD_STARTER env var at spawn time.
+ * When unset or empty the default is "Standalone" (direct CLI invocation).
+ */
+
+export type DashboardStarter = "Bridge" | "Standalone" | "Electron";
+
+const VALID: ReadonlySet<string> = new Set<DashboardStarter>(["Bridge", "Standalone", "Electron"]);
+
+/**
+ * Parse `env.DASHBOARD_STARTER` into a `DashboardStarter`.
+ *
+ * - Unset or empty → `"Standalone"` (direct CLI invocation default).
+ * - Valid value    → that value.
+ * - Invalid value  → logs `console.warn`, returns `"Standalone"`.
+ */
+export function parseDashboardStarter(
+  env: Record<string, string | undefined>,
+): DashboardStarter {
+  const raw = env["DASHBOARD_STARTER"];
+  if (!raw) return "Standalone";
+  if (VALID.has(raw)) return raw as DashboardStarter;
+  console.warn(
+    `[dashboard-starter] Unknown DASHBOARD_STARTER value "${raw}"; defaulting to "Standalone".`,
+  );
+  return "Standalone";
+}

package/packages/shared/src/diff-types.ts

@@ -38,4 +38,21 @@ export interface SessionDiffResponse {
   files: FileDiffEntry[];
   /** Whether the session cwd is a git repository */
   isGitRepo: boolean;
+  /**
+   * VCS regime used to compute the per-file diffs. Optional for
+   * backwards compatibility — absent on responses produced before
+   * change `add-jj-workspace-plugin`.
+   */
+  vcsKind?: "git" | "jj";
+  /**
+   * The literal revset / ref used as the diff base (e.g. "HEAD",
+   * "@-", "fork_point(@, trunk())"). Optional.
+   */
+  diffBase?: string;
+  /**
+   * Human-readable label for `diffBase` (e.g. "develop", "trunk()",
+   * "HEAD"). Optional. Renders as "Diffing against \<baseLabel\>"
+   * in the client when `vcsKind === "jj"`.
+   */
+  baseLabel?: string;
 }