@blackbelt-technology/pi-agent-dashboard 0.3.0 → 0.4.1

package/packages/shared/src/platform/spawn-mechanism.ts

@@ -0,0 +1,124 @@
+/**
+ * Session-spawn mechanism selection.
+ *
+ * The user expresses preference via a two-valued config type
+ * (`SpawnStrategy` = "tmux" | "headless"). The dashboard internally
+ * decides WHICH actual mechanism to use given the OS and what's
+ * available on this host. This module is the single source of truth
+ * for that decision.
+ *
+ * Mechanisms:
+ *   • "tmux"      — Unix terminal multiplexer (Linux, macOS)
+ *   • "wt"        — Windows Terminal new-tab (Win10/11)
+ *   • "wsl-tmux"  — WSL-hosted tmux (Windows, niche)
+ *   • "headless"  — RPC-mode pi, no TTY, bridge over WebSocket
+ *
+ * `selectMechanism` is pure: no I/O, no subprocess calls. Availability
+ * is determined by the caller (typically via `ToolRegistry.resolve`)
+ * and passed in. This keeps the decision trivially testable.
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+
+export type SpawnMechanism = "tmux" | "wt" | "wsl-tmux" | "headless";
+
+/** User-visible config value (from `SpawnStrategy` in shared/config.ts). */
+export type UserSpawnStrategy = "tmux" | "headless";
+
+export interface SpawnMechanismContext {
+  platform: NodeJS.Platform;
+  userStrategy: UserSpawnStrategy;
+  electronMode: boolean;
+  available: {
+    tmux: boolean;
+    wt: boolean;
+    wslTmux: boolean;
+  };
+}
+
+/**
+ * Select one spawn mechanism for this platform given the user's
+ * preference, the electron-mode flag, and tool availability.
+ *
+ * Rules (in order):
+ *   1. electronMode forces "headless".
+ *   2. userStrategy "headless" forces "headless".
+ *   3. Unix (linux/darwin): tmux if available, else headless.
+ *   4. Windows: wt > wsl-tmux > headless.
+ *   5. Any other platform falls back to headless.
+ */
+export function selectMechanism(ctx: SpawnMechanismContext): SpawnMechanism {
+  if (ctx.electronMode) return "headless";
+  if (ctx.userStrategy === "headless") return "headless";
+
+  if (ctx.platform === "linux" || ctx.platform === "darwin") {
+    return ctx.available.tmux ? "tmux" : "headless";
+  }
+  if (ctx.platform === "win32") {
+    if (ctx.available.wt) return "wt";
+    if (ctx.available.wslTmux) return "wsl-tmux";
+    return "headless";
+  }
+  return "headless";
+}
+
+// ── Windows Terminal argv builder ───────────────────────────────────────────
+
+export interface WtArgsOptions {
+  /** Absolute cwd for the new tab. Spaces / parens / quotes are safe in argv form. */
+  cwd: string;
+  /** Tab title, typically the basename of cwd. */
+  title: string;
+  /**
+   * Pre-resolved pi argv: typically [node.exe, cli.js, --mode?, rpc?, --fork?, file?].
+   * Interactive wt sessions OMIT --mode rpc so pi runs its TUI.
+   */
+  piArgv: string[];
+}
+
+/**
+ * Build argv (NOT a shell string) to invoke Windows Terminal so it opens
+ * a new tab in the existing WT window and runs `piArgv` there.
+ *
+ * Design notes:
+ *   • argv form — passed to spawn with shell:false, so wt re-parses it
+ *     internally. No need to escape spaces, semicolons, or quotes in cwd.
+ *   • `-w 0` reuses the most-recently-used WT window; new tab, not new
+ *     window. Matches tmux `new-window` semantics.
+ *   • No `-p <profile>` — respect the user's default WT profile
+ *     (cmd / pwsh / WSL).
+ *   • `--` sentinel before piArgv so any `-` or `/` prefix in piArgv
+ *     can't be misparsed as a wt option.
+ */
+export function buildWtArgs(opts: WtArgsOptions): string[] {
+  return [
+    "-w", "0",
+    "new-tab",
+    "-d", opts.cwd,
+    "--title", opts.title,
+    "--",
+    ...opts.piArgv,
+  ];
+}
+
+// ── Shared helper: append session/fork flags uniformly ─────────────────────
+
+export interface SessionFlags {
+  sessionFile?: string;
+  mode?: "continue" | "fork";
+}
+
+/**
+ * Return `["--session", file]` or `["--fork", file]` or `[]`.
+ * Every mechanism MUST use this to append flags; dropping them silently
+ * is the exact bug that motivated this change (B1, B2).
+ */
+export function sessionFlagsToArgv(flags: SessionFlags): string[] {
+  if (flags.sessionFile && flags.mode === "continue") {
+    return ["--session", flags.sessionFile];
+  }
+  if (flags.sessionFile && flags.mode === "fork") {
+    return ["--fork", flags.sessionFile];
+  }
+  return [];
+}

package/packages/shared/src/platform/subprocess-adapter.ts

@@ -0,0 +1,124 @@
+/**
+ * Subprocess adapter — strategy pattern for OS-aware subprocess invocation.
+ *
+ * The adapter is the single point of entry for spawning any subprocess
+ * from dashboard code or from libraries we wrap. It dispatches to a
+ * platform-specific implementation:
+ *
+ *   - Windows: `.cmd`/`.bat` shims go through explicit `cmd.exe /d /s /c`
+ *     invocation with `windowsHide: true` and `shell: false` (the only
+ *     reliable way to avoid Node issue #21825's flashing console).
+ *     Native `.exe`s spawn directly.
+ *   - Unix: direct spawn, no shell, no special cases.
+ *
+ * Why an adapter instead of a global monkey-patch?
+ *
+ *   - Explicit dependency injection. Callers (and tests) know exactly
+ *     which spawn implementation they get.
+ *   - Isolated — third-party code that needs this behaviour gets it via
+ *     a thin subclass that consumes the adapter (see
+ *     `createSafePackageManagerClass` in
+ *     `packages/server/src/package-manager-wrapper.ts`). No cross-
+ *     cutting global state.
+ *   - Testable: fake adapter => assert argv without spawning real
+ *     subprocesses.
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+import type {
+  ChildProcess,
+  SpawnOptions,
+  SpawnSyncOptions,
+  SpawnSyncReturns,
+} from "node:child_process";
+import {
+  spawn as safeSpawn,
+  spawnSync as safeSpawnSync,
+  buildSafeArgv,
+} from "./exec.js";
+
+// ── Interface ──────────────────────────────────────────────────────────────
+
+/**
+ * Cross-platform subprocess adapter. Implementations guarantee:
+ *   - `windowsHide: true` on Windows, always.
+ *   - No `shell: true` ever — `.cmd` shims are invoked via explicit
+ *     `cmd.exe /d /s /c` argv.
+ *   - Arg arrays are passed verbatim, no shell-escaping surprises.
+ */
+export interface SubprocessAdapter {
+  /** Async spawn. Returns the live ChildProcess. */
+  spawn(command: string, args?: readonly string[], options?: SpawnOptions): ChildProcess;
+
+  /** Synchronous spawn. Blocks until completion. */
+  spawnSync<T extends string | Buffer = Buffer>(
+    command: string,
+    args?: readonly string[],
+    options?: SpawnSyncOptions,
+  ): SpawnSyncReturns<T>;
+}
+
+// ── Windows implementation ─────────────────────────────────────────────────
+
+class WindowsSubprocessAdapter implements SubprocessAdapter {
+  spawn(command: string, args: readonly string[] = [], options?: SpawnOptions): ChildProcess {
+    const { argv, spawnOptions } = buildSafeArgv(command, args, "win32");
+    return safeSpawn(argv[0], argv.slice(1), { ...(options ?? {}), ...spawnOptions });
+  }
+
+  spawnSync<T extends string | Buffer = Buffer>(
+    command: string,
+    args: readonly string[] = [],
+    options?: SpawnSyncOptions,
+  ): SpawnSyncReturns<T> {
+    const { argv, spawnOptions } = buildSafeArgv(command, args, "win32");
+    return safeSpawnSync<T>(argv[0], argv.slice(1), { ...(options ?? {}), ...spawnOptions });
+  }
+}
+
+// ── Unix implementation ────────────────────────────────────────────────────
+
+class UnixSubprocessAdapter implements SubprocessAdapter {
+  spawn(command: string, args: readonly string[] = [], options?: SpawnOptions): ChildProcess {
+    return safeSpawn(command, args, { ...(options ?? {}), shell: false });
+  }
+
+  spawnSync<T extends string | Buffer = Buffer>(
+    command: string,
+    args: readonly string[] = [],
+    options?: SpawnSyncOptions,
+  ): SpawnSyncReturns<T> {
+    return safeSpawnSync<T>(command, args, { ...(options ?? {}), shell: false });
+  }
+}
+
+// ── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Return the appropriate adapter for the given platform. Default:
+ * `process.platform`. Tests pass explicit values without mutating the
+ * global.
+ */
+export function createSubprocessAdapter(
+  platform: NodeJS.Platform = process.platform,
+): SubprocessAdapter {
+  if (platform === "win32") return new WindowsSubprocessAdapter();
+  return new UnixSubprocessAdapter();
+}
+
+/**
+ * Process-wide default adapter. Constructed lazily on first access.
+ * Callers that want a different strategy (e.g. tests injecting a fake)
+ * pass the adapter explicitly to their constructor instead of using
+ * this singleton.
+ */
+let defaultAdapter: SubprocessAdapter | null = null;
+export function getDefaultSubprocessAdapter(): SubprocessAdapter {
+  if (!defaultAdapter) defaultAdapter = createSubprocessAdapter();
+  return defaultAdapter;
+}
+
+/** Test-only: drop the cached default adapter. */
+export function _resetDefaultSubprocessAdapter(): void {
+  defaultAdapter = null;
+}

package/packages/shared/src/protocol.ts

@@ -57,6 +57,29 @@ export interface EventForwardMessage {
   event: DashboardEvent;
 }
 
+/**
+ * Conventions on `event_forward` payloads relevant to per-message fork:
+ *
+ * - `message_start` and `message_end` events MAY carry an optional
+ *   `data.nonce: string` stamped by the bridge. The reducer carries it
+ *   onto the resulting ChatMessage so a later `entry_persisted` event
+ *   can back-fill the entry id.
+ * - `entry_persisted` events have shape:
+ *     {
+ *       eventType: "entry_persisted",
+ *       timestamp,
+ *       data: { type: "entry_persisted", entryId: string, nonce: string }
+ *     }
+ *   They are emitted by the bridge after pi calls
+ *   `sessionManager.appendMessage` and the entry id has been generated.
+ *   See change: fix-per-message-fork.
+ */
+export interface EntryPersistedEventData {
+  type: "entry_persisted";
+  entryId: string;
+  nonce: string;
+}
+
 export interface CommandsListMessage {
   type: "commands_list";
   sessionId: string;

package/packages/shared/src/recommended-extensions.ts

@@ -82,7 +82,7 @@ export interface EnrichedRecommendedExtension extends RecommendedExtension {
 export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 	{
 		id: "pi-anthropic-messages",
-		source: "git@github.com:BlackBeltTechnology/pi-anthropic-messages.git",
+		source: "https://github.com/BlackBeltTechnology/pi-anthropic-messages.git",
 		displayName: "pi-anthropic-messages",
 		fallbackDescription:
 			"Protocol bridge that makes pi's custom tools work with any " +
@@ -114,7 +114,7 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 	},
 	{
 		id: "pi-flows",
-		source: "git@github.com:BlackBeltTechnology/pi-flows.git",
+		source: "https://github.com/BlackBeltTechnology/pi-flows.git",
 		displayName: "pi-flows",
 		fallbackDescription:
 			"Flow engine, dashboard, and orchestration extensions for pi. " +
@@ -167,6 +167,22 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
 	},
 ];
 
+/**
+ * Ids of recommended extensions that ship inside the Electron installer
+ * as a pre-bundled source tree. See
+ * `packages/electron/scripts/bundle-recommended-extensions.sh` and
+ * `installBundledExtensions()` in `dependency-installer.ts`. Every id
+ * MUST also appear in `RECOMMENDED_EXTENSIONS` and MUST have a git-based
+ * `source` (enforced by a test).
+ *
+ * Kept deliberately short — only first-party, source-only, native-dep-free
+ * extensions belong here.
+ */
+export const BUNDLED_EXTENSION_IDS: readonly string[] = [
+	"pi-anthropic-messages",
+	"pi-flows",
+];
+
 /** Retrieve a recommended entry by id, or `undefined`. */
 export function getRecommendedExtension(id: string): RecommendedExtension | undefined {
 	return RECOMMENDED_EXTENSIONS.find((e) => e.id === id);

package/packages/shared/src/resolve-jiti.ts

@@ -8,8 +8,9 @@
  */
 
 import { createRequire } from "node:module";
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const JITI_PACKAGES = [
   "@mariozechner/jiti",
@@ -17,8 +18,38 @@ const JITI_PACKAGES = [
 ];
 
 /**
- * Returns the absolute path to jiti's register hook (lib/jiti-register.mjs).
+ * Pure helper: given a jiti package.json path, return the file:// URL of
+ * its register hook. Exported for testing — no I/O.
+ *
+ * Returns a file:// URL (not a raw path) because Node >= 20 on Windows
+ * rejects raw absolute paths with a drive letter for --import (parses
+ * "C:" / "B:" as a URL scheme → ERR_UNSUPPORTED_ESM_URL_SCHEME). file://
+ * URLs are accepted on every OS.
+ * See change: fix-windows-server-parity.
+ */
+export function buildJitiRegisterUrl(pkgJsonPath: string): string {
+  // Detect Windows-style input (drive letter + backslash) regardless of
+  // host OS, so unit tests can exercise the Windows path contract on macOS/Linux.
+  // Production behaviour is unchanged because the host-OS `path`/`pathToFileURL`
+  // match the input style automatically.
+  const isWindowsStyle = /^[A-Za-z]:[\\/]/.test(pkgJsonPath);
+  if (isWindowsStyle) {
+    // Manually build file:///C:/path/lib/jiti-register.mjs — pathToFileURL on
+    // POSIX hosts URL-encodes backslashes rather than treating them as
+    // separators. Do the join with path.win32 and format the URL ourselves.
+    const registerPath = path.win32.join(path.win32.dirname(pkgJsonPath), "lib", "jiti-register.mjs");
+    return `file:///${registerPath.replace(/\\/g, "/")}`;
+  }
+  const registerPath = path.join(path.dirname(pkgJsonPath), "lib", "jiti-register.mjs");
+  return pathToFileURL(registerPath).href;
+}
+
+/**
+ * Returns jiti's register hook as a file:// URL suitable for `node --import`.
  * Uses process.argv[1] (pi's entry point) to anchor module resolution.
+ *
+ * The return value is ALWAYS a file:// URL (never a raw path). See
+ * buildJitiRegisterUrl for the URL contract rationale.
  */
 export function resolveJitiImport(): string {
   const anchor = process.argv[1];
@@ -30,7 +61,7 @@ export function resolveJitiImport(): string {
       for (const jiti of JITI_PACKAGES) {
         try {
           const pkgJson = req.resolve(`${jiti}/package.json`);
-          return path.join(path.dirname(pkgJson), "lib", "jiti-register.mjs");
+          return buildJitiRegisterUrl(pkgJson);
         } catch { /* next */ }
       }
     } catch { /* fall through */ }
@@ -41,3 +72,31 @@ export function resolveJitiImport(): string {
     "Is @mariozechner/pi-coding-agent or @oh-my-pi/pi-coding-agent installed?"
   );
 }
+
+/**
+ * Resolve jiti's register hook from an arbitrary anchor path (e.g. a
+ * pi-coding-agent package.json in a managed install, or a pi binary on
+ * the system PATH). Returns a file:// URL or null if jiti cannot be
+ * resolved from the anchor.
+ *
+ * This is the Electron/managed-install variant of `resolveJitiImport`
+ * — the difference is the caller supplies the anchor explicitly
+ * instead of using `process.argv[1]`. Consolidates what used to be a
+ * duplicate `resolveJitiFromAnchor` in
+ * `packages/electron/src/lib/server-lifecycle.ts`.
+ * See change: consolidate-platform-handlers.
+ */
+export function resolveJitiFromAnchor(anchorPath: string): string | null {
+  if (!existsSync(anchorPath)) return null;
+  try {
+    const req = createRequire(anchorPath);
+    for (const jiti of JITI_PACKAGES) {
+      try {
+        const pkgJson = req.resolve(`${jiti}/package.json`);
+        const registerPath = path.join(path.dirname(pkgJson), "lib", "jiti-register.mjs");
+        if (existsSync(registerPath)) return pathToFileURL(registerPath).href;
+      } catch { /* next */ }
+    }
+  } catch { /* ignore */ }
+  return null;
+}

package/packages/shared/src/rest-api.ts

@@ -80,6 +80,16 @@ export interface BrowseResult {
   entries: BrowseEntry[];
   parent: string | null;
   current: string;
+  /**
+   * The server's `process.platform` — lets the client use OS-correct path
+   * handling (separator, case-sensitivity, drive-letter rules) without
+   * having to sniff `navigator.userAgent`. Optional for backward
+   * compatibility; consumers fall back to inferring from the `current`
+   * path shape when absent.
+   *
+   * See change: platform-path-normalization.
+   */
+  platform?: NodeJS.Platform;
 }
 
 export type BrowseResponse = ApiResponse<BrowseResult>;
@@ -352,3 +362,19 @@ export interface NetworkInterface {
 export type ListRecommendedExtensionsResponse = ApiResponse<{
   recommended: EnrichedRecommendedExtension[];
 }>;
+
+// ── Tool registry ────────────────────
+
+import type { Resolution } from "./tool-registry/types.js";
+export type { Resolution, Source, TriedEntry } from "./tool-registry/types.js";
+
+export type ListToolsResponse = ApiResponse<{ tools: Resolution[] }>;
+export type GetToolResponse = ApiResponse<Resolution>;
+
+export interface RescanToolsRequest {
+  name?: string;
+}
+
+export interface SetToolOverrideRequest {
+  path: string;
+}

package/packages/shared/src/semaphore.ts

@@ -0,0 +1,83 @@
+/**
+ * Tiny FIFO semaphore for throttling concurrent async operations.
+ *
+ * Used by the server's openspec polling scheduler to cap how many
+ * `openspec` CLI spawns may be running at once. Rolled in-repo instead
+ * of pulling `p-limit` because we need `setMax()` for live reconfig
+ * (when the user edits `openspec.maxConcurrentSpawns` in settings).
+ *
+ * Contract:
+ *   - `run(fn)` runs `fn` through the gate. At most `max` tasks are
+ *     in-flight; excess tasks queue FIFO.
+ *   - `setMax(n)` resizes. Growing drains the queue up to the new cap
+ *     on the next microtask. Shrinking does not interrupt in-flight
+ *     tasks; it only affects newly queued ones.
+ *   - `size()` = active + queued.
+ *   - If the task throws/rejects, the slot is released and queued
+ *     tasks proceed.
+ */
+export interface Semaphore {
+  run<T>(fn: () => Promise<T>): Promise<T>;
+  setMax(n: number): void;
+  size(): number;
+}
+
+export function createSemaphore(max: number): Semaphore {
+  if (!Number.isFinite(max) || max < 1) {
+    throw new Error(`Semaphore max must be a positive integer, got ${max}`);
+  }
+  let limit = Math.floor(max);
+  let active = 0;
+  const queue: Array<() => void> = [];
+
+  function drain() {
+    while (active < limit && queue.length > 0) {
+      const next = queue.shift()!;
+      active++;
+      next();
+    }
+  }
+
+  function release() {
+    active--;
+    // Schedule drain on microtask so `run()` callers see a stable state first.
+    queueMicrotask(drain);
+  }
+
+  return {
+    run<T>(fn: () => Promise<T>): Promise<T> {
+      return new Promise<T>((resolve, reject) => {
+        const start = () => {
+          let settled = false;
+          try {
+            Promise.resolve()
+              .then(fn)
+              .then(
+                (value) => { if (!settled) { settled = true; release(); resolve(value); } },
+                (err) => { if (!settled) { settled = true; release(); reject(err); } },
+              );
+          } catch (err) {
+            if (!settled) { settled = true; release(); reject(err); }
+          }
+        };
+        if (active < limit) {
+          active++;
+          start();
+        } else {
+          queue.push(start);
+        }
+      });
+    },
+    setMax(n: number): void {
+      if (!Number.isFinite(n) || n < 1) {
+        throw new Error(`Semaphore max must be a positive integer, got ${n}`);
+      }
+      limit = Math.floor(n);
+      // Drain synchronously so callers that do `setMax(n); await tick` see queued tasks started.
+      drain();
+    },
+    size(): number {
+      return active + queue.length;
+    },
+  };
+}

package/packages/shared/src/state-replay.ts

@@ -13,6 +13,15 @@ import type { EventForwardMessage } from "./protocol.js";
  * - message_update + message_end for assistant messages
  * - tool_execution_start / tool_execution_end for tool calls
  * - model_select for model changes
+ *
+ * NOTE on entryId (per change: fix-per-message-fork):
+ * Replay reads from the persisted JSONL, so each entry already has a
+ * stable `id`. We attach it directly as `entryId` on both `message_start`
+ * (user) and `message_end` (assistant) events. Replay therefore does NOT
+ * need to emit an `entry_persisted` follow-up — the back-fill protocol
+ * exists to bridge a timing gap that only happens for LIVE pi events on
+ * pi 0.69+, where the bridge sees `message_start` before pi has assigned
+ * the entry id. Replay has no such gap.
  */
 export function replayEntriesAsEvents(
   sessionId: string,