@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

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

@@ -92,6 +92,10 @@ export interface BrowserModelsListMessage {
   models: ModelInfo[];
 }
 
+export interface ModelsRefreshedMessage {
+  type: "models_refreshed";
+}
+
 export interface BrowserRolesListMessage {
   type: "roles_list";
   sessionId: string;
@@ -121,6 +125,21 @@ export interface SpawnResultBrowserMessage {
   message: string;
 }
 
+/**
+ * Emitted when a session spawn fails — either because `spawnPiSession` threw,
+ * returned `{ success: false }`, or the spawned child crashed immediately.
+ * Carries enough context for the UI to render a retryable error banner
+ * instead of leaving the user staring at a silent empty state.
+ */
+export interface SpawnErrorMessage {
+  type: "spawn_error";
+  cwd: string;
+  strategy: string;
+  message: string;
+  /** Up to ~2 KB tail of stderr captured from the failed child, if any. */
+  stderr?: string;
+}
+
 export interface SessionsReorderedMessage {
   type: "sessions_reordered";
   cwd: string;
@@ -207,6 +226,73 @@ export interface PackageProgressMessage {
   };
 }
 
+/** Progress event streamed during a pi core package update. */
+export interface PiCoreUpdateProgressMessage {
+  type: "pi_core_update_progress";
+  name: string;
+  phase: "start" | "output" | "complete" | "error";
+  message?: string;
+}
+
+/** Sent when a full pi core update batch finishes. */
+export interface PiCoreUpdateCompleteMessage {
+  type: "pi_core_update_complete";
+  results: Array<{ name: string; success: boolean; error?: string }>;
+  sessionsReloaded: number;
+}
+
+/**
+ * Bootstrap state snapshot. Mirrors `BootstrapState` in
+ * `packages/server/src/bootstrap-state.ts` but kept as a structural
+ * subset here so the shared package doesn't take a runtime dependency
+ * on the server package.
+ *
+ * See change: unified-bootstrap-install.
+ */
+export interface BootstrapStateSnapshot {
+  status: "ready" | "installing" | "failed";
+  progress?: { step: string; pct?: number; output?: string };
+  error?: { message: string; stack?: string };
+  version?: { pi?: string; openspec?: string; tsx?: string };
+  compatibility?: {
+    minimum: string;
+    recommended: string;
+    maximum: string | null;
+    current?: string;
+    upgradeRecommended?: boolean;
+    upgradeDashboard?: boolean;
+  };
+  bridgeRegistrationError?: string;
+}
+
+/**
+ * Broadcast on every bootstrap-state transition. Browsers use this to
+ * render the first-run install banner, the upgrade-pi progress display,
+ * and version-skew hints.
+ */
+export interface BootstrapStatusUpdateMessage {
+  type: "bootstrap_status_update";
+  state: BootstrapStateSnapshot;
+}
+
+/**
+ * Broadcast when a queued pi-dependent operation (e.g. a session-spawn
+ * request accepted with 202 during "installing") finishes running after
+ * the bootstrap transitioned to "ready". Clients that stored a ticketId
+ * from the 202 response can correlate the outcome via this message.
+ *
+ * `success` is true when the queued handler resolved without throwing;
+ * `error` carries the thrown message string when `success` is false.
+ *
+ * See change: unified-bootstrap-install.
+ */
+export interface BootstrapTicketCompleteMessage {
+  type: "bootstrap_ticket_complete";
+  ticketId: string;
+  success: boolean;
+  error?: string;
+}
+
 /** Sent when a package operation finishes (success or failure). */
 export interface PackageOperationCompleteMessage {
   type: "package_operation_complete";
@@ -236,6 +322,7 @@ export type ServerToBrowserMessage =
   | SessionsListBrowserMessage
   | ResumeResultBrowserMessage
   | SpawnResultBrowserMessage
+  | SpawnErrorMessage
   | SessionsReorderedMessage
   | PinnedDirsUpdatedMessage
   | TerminalAddedMessage
@@ -244,6 +331,8 @@ export type ServerToBrowserMessage =
   | SessionStateResetMessage
   | PackageProgressMessage
   | PackageOperationCompleteMessage
+  | PiCoreUpdateProgressMessage
+  | PiCoreUpdateCompleteMessage
   | EditorStatusMessage
   | ForceKillResultMessage
   | BrowserRolesListMessage
@@ -252,7 +341,10 @@ export type ServerToBrowserMessage =
   | ServersUpdatedMessage
   | BrowserPromptRequestMessage
   | BrowserPromptDismissMessage
-  | BrowserPromptCancelMessage;
+  | BrowserPromptCancelMessage
+  | ModelsRefreshedMessage
+  | BootstrapStatusUpdateMessage
+  | BootstrapTicketCompleteMessage;
 
 // ── Browser → Server ────────────────────────────────────────────────
 

package/packages/shared/src/config.ts

@@ -41,6 +41,24 @@ export const DEFAULT_MEMORY_LIMITS: MemoryLimitsConfig = {
   maxWsBufferBytes: 4 * 1024 * 1024,
 };
 
+export interface OpenSpecPollConfig {
+  /** Poll interval in seconds. Default 30. Clamped to [5, 3600]. */
+  pollIntervalSeconds: number;
+  /** Max concurrent `openspec` CLI invocations across all dirs. Default 3. Clamped to [1, 16]. */
+  maxConcurrentSpawns: number;
+  /** `"mtime"` skips re-polling unchanged changes; `"always"` polls unconditionally. Default `"mtime"`. */
+  changeDetection: "mtime" | "always";
+  /** Max per-directory phase jitter in seconds. 0 disables jitter. Default 5. Clamped to [0, 60]. */
+  jitterSeconds: number;
+}
+
+export const DEFAULT_OPENSPEC_POLL: OpenSpecPollConfig = {
+  pollIntervalSeconds: 30,
+  maxConcurrentSpawns: 3,
+  changeDetection: "mtime",
+  jitterSeconds: 5,
+};
+
 export interface EditorConfig {
   /** Override path to code-server binary */
   binary?: string;
@@ -75,6 +93,8 @@ export interface DashboardConfig {
   defaultModel: string;
   memoryLimits: MemoryLimitsConfig;
   editor: EditorConfig;
+  /** OpenSpec background polling behavior (interval, concurrency, change detection, jitter) */
+  openspec: OpenSpecPollConfig;
   /** Networks trusted for full access without authentication (CIDR, wildcard, exact IP) */
   trustedNetworks: string[];
   /** Merged trustedNetworks + auth.bypassHosts (deduplicated). Computed at load time. */
@@ -108,6 +128,7 @@ const DEFAULTS: DashboardConfig = {
   defaultModel: "",
   memoryLimits: { ...DEFAULT_MEMORY_LIMITS },
   editor: { ...DEFAULT_EDITOR_CONFIG },
+  openspec: { ...DEFAULT_OPENSPEC_POLL },
   trustedNetworks: [],
   resolvedTrustedNetworks: [],
   cors: { allowedOrigins: [] },
@@ -117,28 +138,57 @@ const DEFAULTS: DashboardConfig = {
 
 /**
  * Parse and validate the auth config section.
- * Returns undefined if auth is not configured or has no providers.
+ *
+ * Returns undefined ONLY when nothing auth-relevant is configured — that is,
+ * when none of `providers`, `bypassHosts`, or `bypassUrls` has any content.
+ *
+ * When providers is empty but bypassHosts or bypassUrls is populated, this
+ * function returns a valid AuthConfig with an empty providers map. The auth
+ * plugin already no-ops in that case (providerRegistry.size === 0 → skip
+ * OAuth route + cookie plugin registration), so no OAuth flow activates
+ * accidentally. But returning an object here lets the caller populate
+ * resolvedTrustedNetworks from auth.bypassHosts — which is the entire
+ * point of allowing this shape. Before this change, parseAuthConfig
+ * returned undefined on empty-providers, which nuked auth.bypassHosts
+ * before the resolvedTrustedNetworks merge could read it, and users
+ * without OAuth lost remote network access after the UI started writing
+ * to auth.bypassHosts. See openspec/changes/fix-trusted-networks-no-oauth.
  */
 function parseAuthConfig(raw: any): AuthConfig | undefined {
   if (!raw || typeof raw !== "object") return undefined;
   const providers = raw.providers;
-  if (!providers || typeof providers !== "object" || Object.keys(providers).length === 0) {
-    return undefined;
-  }
-  // Validate each provider has at least clientId and clientSecret
+  const hasProviders =
+    providers && typeof providers === "object" && Object.keys(providers).length > 0;
+  const hasHosts = Array.isArray(raw.bypassHosts) && raw.bypassHosts.length > 0;
+  const hasUrls = Array.isArray(raw.bypassUrls) && raw.bypassUrls.length > 0;
+  if (!hasProviders && !hasHosts && !hasUrls) return undefined;
+
+  // Validate each provider has at least clientId and clientSecret.
+  // validProviders may end up empty when providers is {} or all entries
+  // are malformed — that's fine, the caller tolerates it as long as
+  // bypassHosts or bypassUrls carries the auth-relevant content.
   const validProviders: Record<string, AuthProviderConfig> = {};
-  for (const [key, value] of Object.entries(providers)) {
-    const p = value as any;
-    if (p && typeof p === "object" && p.clientId && p.clientSecret) {
-      validProviders[key] = {
-        clientId: p.clientId,
-        clientSecret: p.clientSecret,
-        ...(p.issuerUrl ? { issuerUrl: p.issuerUrl } : {}),
-        ...(p.name ? { name: p.name } : {}),
-      };
+  if (hasProviders) {
+    for (const [key, value] of Object.entries(providers as Record<string, unknown>)) {
+      const p = value as any;
+      if (p && typeof p === "object" && p.clientId && p.clientSecret) {
+        validProviders[key] = {
+          clientId: p.clientId,
+          clientSecret: p.clientSecret,
+          ...(p.issuerUrl ? { issuerUrl: p.issuerUrl } : {}),
+          ...(p.name ? { name: p.name } : {}),
+        };
+      }
     }
   }
-  if (Object.keys(validProviders).length === 0) return undefined;
+
+  // If providers was declared but all entries are malformed AND there is no
+  // bypass content, fall back to undefined — same "nothing auth-relevant"
+  // rule as the top-level gate.
+  if (Object.keys(validProviders).length === 0 && !hasHosts && !hasUrls) {
+    return undefined;
+  }
+
   return {
     secret: raw.secret ?? "",
     providers: validProviders,
@@ -157,6 +207,27 @@ function parseEditorConfig(raw: any): EditorConfig {
   };
 }
 
+function clampNumber(raw: any, fallback: number, min: number, max: number): number {
+  const n = typeof raw === "number" && Number.isFinite(raw) ? raw : fallback;
+  if (n < min) return min;
+  if (n > max) return max;
+  return n;
+}
+
+function parseOpenSpecPollConfig(raw: any): OpenSpecPollConfig {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_OPENSPEC_POLL };
+  const changeDetection =
+    raw.changeDetection === "always" || raw.changeDetection === "mtime"
+      ? raw.changeDetection
+      : DEFAULT_OPENSPEC_POLL.changeDetection;
+  return {
+    pollIntervalSeconds: clampNumber(raw.pollIntervalSeconds, DEFAULT_OPENSPEC_POLL.pollIntervalSeconds, 5, 3600),
+    maxConcurrentSpawns: clampNumber(raw.maxConcurrentSpawns, DEFAULT_OPENSPEC_POLL.maxConcurrentSpawns, 1, 16),
+    changeDetection,
+    jitterSeconds: clampNumber(raw.jitterSeconds, DEFAULT_OPENSPEC_POLL.jitterSeconds, 0, 60),
+  };
+}
+
 function parseMemoryLimits(raw: any): MemoryLimitsConfig {
   if (!raw || typeof raw !== "object") return { ...DEFAULT_MEMORY_LIMITS };
   return {
@@ -217,6 +288,7 @@ export function loadConfig(): DashboardConfig {
       auth: parseAuthConfig(parsed.auth),
       memoryLimits: parseMemoryLimits(parsed.memoryLimits),
       editor: parseEditorConfig(parsed.editor),
+      openspec: parseOpenSpecPollConfig(parsed.openspec),
       trustedNetworks: parseTrustedNetworks(parsed.trustedNetworks),
       resolvedTrustedNetworks: [],
       cors: {

package/packages/shared/src/managed-paths.ts

@@ -1,15 +1,42 @@
 /**
- * Shared constants for the managed install directory (~/.pi-dashboard/).
+ * Shared constants + getters for the managed install directory (~/.pi-dashboard/).
  * Single source of truth — all packages import from here.
+ *
+ * Constants (MANAGED_DIR, MANAGED_BIN, PI_SETTINGS_PATH) reflect the live
+ * environment at module-load time. Production code continues to use them.
+ *
+ * Getters (getManagedDir, getManagedBin, getPiSettingsPath) accept an
+ * optional `{ homedir }` override so tests (and the bootstrap harness)
+ * can reason about alternate HOME directories without mutating globals.
  */
 import path from "node:path";
 import os from "node:os";
 
+/** Env override surface used by the getters (subset of PlatformEnv). */
+export interface ManagedPathsEnv {
+  homedir?: string;
+}
+
+/** Root directory for managed installs (pi, openspec, tsx). */
+export function getManagedDir(env?: ManagedPathsEnv): string {
+  return path.join(env?.homedir ?? os.homedir(), ".pi-dashboard");
+}
+
+/** Bin directory for managed install executables. */
+export function getManagedBin(env?: ManagedPathsEnv): string {
+  return path.join(getManagedDir(env), "node_modules", ".bin");
+}
+
+/** Path to pi's global settings file. */
+export function getPiSettingsPath(env?: ManagedPathsEnv): string {
+  return path.join(env?.homedir ?? os.homedir(), ".pi", "agent", "settings.json");
+}
+
 /** Root directory for managed installs (pi, openspec, tsx). */
-export const MANAGED_DIR = path.join(os.homedir(), ".pi-dashboard");
+export const MANAGED_DIR = getManagedDir();
 
 /** Bin directory for managed install executables. */
-export const MANAGED_BIN = path.join(MANAGED_DIR, "node_modules", ".bin");
+export const MANAGED_BIN = getManagedBin();
 
 /** Path to pi's global settings file. */
-export const PI_SETTINGS_PATH = path.join(os.homedir(), ".pi", "agent", "settings.json");
+export const PI_SETTINGS_PATH = getPiSettingsPath();

package/packages/shared/src/openspec-poller.ts

@@ -1,48 +1,34 @@
 /**
  * Polls the openspec CLI to gather change data for the session's project.
- * Uses async child processes to avoid blocking the event loop.
+ *
+ * This module is a thin aggregator over `platform/openspec.ts`: it
+ * calls the Recipe-based primitives and combines `list` + per-change
+ * `status` into the dashboard's `OpenSpecData` shape.
+ *
+ * Two public flavors:
+ *
+ *   - `pollOpenSpec` (sync) — for the bridge extension where async
+ *     isn't practical. Uses `run()` under the hood; each call blocks
+ *     the event loop for ~200-2000ms per openspec invocation.
+ *
+ *   - `pollOpenSpecAsync` (async) — for the server's directory service.
+ *     Routes through the runner's `runAsync()` so every spawn goes
+ *     through the same binary resolution, `.cmd` shell handling, and
+ *     `windowsHide: true` default as everything else. Status queries
+ *     run in parallel via `Promise.all`, keeping the event loop free
+ *     on Windows where openspec.cmd startup is slow (~2s per call).
+ *
+ * See change: consolidate-tool-resolution.
  */
-import { spawnSync, execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { listOr, statusOr, OPENSPEC_LIST, OPENSPEC_STATUS } from "./platform/openspec.js";
+import { runAsync, unwrap } from "./platform/runner.js";
 import type { OpenSpecData, OpenSpecChange, OpenSpecArtifact } from "./types.js";
 
-const execFileAsync = promisify(execFile);
 const EMPTY_DATA: OpenSpecData = { initialized: false, changes: [] };
 
-/** Synchronous version — only used by bridge extension where async isn't practical */
-function runOpenSpecSync(args: string[], cwd: string): unknown | null {
-  try {
-    const result = spawnSync("openspec", args, {
-      cwd,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 10_000,
-    });
-    if (result.status !== 0 || !result.stdout) return null;
-    return JSON.parse(result.stdout);
-  } catch {
-    return null;
-  }
-}
-
-/** Async version — non-blocking, used by server */
-async function runOpenSpecAsync(args: string[], cwd: string): Promise<unknown | null> {
-  try {
-    const { stdout } = await execFileAsync("openspec", args, {
-      cwd,
-      encoding: "utf-8",
-      timeout: 10_000,
-    });
-    if (!stdout) return null;
-    return JSON.parse(stdout);
-  } catch {
-    return null;
-  }
-}
-
-function buildOpenSpecData(
+export function buildOpenSpecData(
   listResult: { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> } | null,
-  statusResults: Map<string, { artifacts?: Array<{ id: string; status: string }> } | null>,
+  statusResults: Map<string, { artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null>,
 ): OpenSpecData {
   if (!listResult || !Array.isArray(listResult.changes)) {
     return EMPTY_DATA;
@@ -55,42 +41,78 @@ function buildOpenSpecData(
       status: (a.status === "done" ? "done" : a.status === "ready" ? "ready" : "blocked") as OpenSpecArtifact["status"],
     }));
 
-    return {
+    const isComplete =
+      typeof statusResult?.isComplete === "boolean" ? statusResult.isComplete : undefined;
+
+    const change: OpenSpecChange = {
       name: c.name,
       status: (c.status === "complete" ? "complete" : c.status === "in-progress" ? "in-progress" : "no-tasks") as OpenSpecChange["status"],
       completedTasks: c.completedTasks ?? 0,
       totalTasks: c.totalTasks ?? 0,
       artifacts,
     };
+    if (isComplete !== undefined) change.isComplete = isComplete;
+    return change;
   });
 
   return { initialized: true, changes };
 }
 
-/** Synchronous poll — blocks event loop. Used by bridge extension. */
+/**
+ * Synchronous poll — blocks the event loop. Used by the bridge extension
+ * where async isn't practical (some pi extension hooks are sync).
+ */
 export function pollOpenSpec(cwd: string): OpenSpecData {
-  const listResult = runOpenSpecSync(["list", "--json"], cwd) as any;
+  const listResult = listOr({ cwd }) as any;
   if (!listResult || !Array.isArray(listResult.changes)) return EMPTY_DATA;
 
   const statusResults = new Map<string, any>();
   for (const c of listResult.changes) {
-    statusResults.set(c.name, runOpenSpecSync(["status", "--change", c.name, "--json"], cwd));
+    statusResults.set(c.name, statusOr({ cwd, change: c.name }));
   }
   return buildOpenSpecData(listResult, statusResults);
 }
 
-/** Async poll — non-blocking. Used by server directory service. */
+/**
+ * Run `openspec list --json` for a single cwd. Exposed so callers that
+ * want their own concurrency control or mtime-gate logic can compose
+ * the list + per-change status calls themselves.
+ */
+export async function runOpenSpecList(cwd: string): Promise<
+  | { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> }
+  | null
+> {
+  return unwrap(await runAsync(OPENSPEC_LIST, { cwd }, { cwd }), null) as any;
+}
+
+/**
+ * Run `openspec status --change <name> --json` for a single change.
+ * Exposed for the same reason as `runOpenSpecList`.
+ */
+export async function runOpenSpecStatus(
+  cwd: string,
+  changeName: string,
+): Promise<{ artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null> {
+  return unwrap(await runAsync(OPENSPEC_STATUS, { cwd, change: changeName }, { cwd }), null) as any;
+}
+
+/**
+ * Async poll — genuinely async. Runs per-change status queries in
+ * parallel via the shared `runAsync()`, so each spawn goes through the
+ * central binary resolution + `windowsHide: true` default.
+ */
 export async function pollOpenSpecAsync(cwd: string): Promise<OpenSpecData> {
-  const listResult = await runOpenSpecAsync(["list", "--json"], cwd) as any;
+  const listResult = unwrap(await runAsync(OPENSPEC_LIST, { cwd }, { cwd }), null) as
+    | { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> }
+    | null;
   if (!listResult || !Array.isArray(listResult.changes)) return EMPTY_DATA;
 
-  // Run all status queries in parallel
-  const entries = await Promise.all(
-    listResult.changes.map(async (c: any): Promise<[string, any]> => {
-      const status = await runOpenSpecAsync(["status", "--change", c.name, "--json"], cwd);
-      return [c.name, status];
+  const statusEntries = await Promise.all(
+    listResult.changes.map(async (c) => {
+      const result = await runAsync(OPENSPEC_STATUS, { cwd, change: c.name }, { cwd });
+      return [c.name, unwrap(result, null)] as const;
     }),
   );
-  const statusResults = new Map<string, any>(entries);
+  const statusResults = new Map<string, any>(statusEntries);
   return buildOpenSpecData(listResult, statusResults);
 }