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

package/packages/shared/src/__tests__/state-replay-entry-id.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Round-trip test for state-replay (per change: fix-per-message-fork):
+ * for every persisted entry, the reducer-equivalent message_start /
+ * message_end carries entryId === entry.id. Replay does NOT need
+ * entry_persisted back-fill because it reads from the persisted JSONL.
+ */
+import { describe, it, expect } from "vitest";
+import { replayEntriesAsEvents } from "../state-replay.js";
+
+describe("replayEntriesAsEvents — entryId fidelity", () => {
+  it("stamps entryId on user message_start matching the source entry id", () => {
+    const sessionId = "sess-1";
+    const entries = [
+      {
+        type: "message",
+        id: "u1",
+        parentId: "root",
+        timestamp: "2026-04-27T07:26:25.000Z",
+        message: { role: "user", content: [{ type: "text", text: "Hello" }] },
+      },
+    ];
+
+    const events = replayEntriesAsEvents(sessionId, entries);
+    const start = events.find((e) => e.event.eventType === "message_start");
+    expect(start).toBeDefined();
+    expect((start!.event.data as any).entryId).toBe("u1");
+  });
+
+  it("stamps entryId on assistant message_end matching the source entry id", () => {
+    const sessionId = "sess-1";
+    const entries = [
+      {
+        type: "message",
+        id: "a1",
+        parentId: "u1",
+        timestamp: "2026-04-27T07:26:30.000Z",
+        message: { role: "assistant", content: [{ type: "text", text: "Hi!" }] },
+      },
+    ];
+
+    const events = replayEntriesAsEvents(sessionId, entries);
+    const end = events.find((e) => e.event.eventType === "message_end");
+    expect(end).toBeDefined();
+    expect((end!.event.data as any).entryId).toBe("a1");
+  });
+
+  it("emits no entry_persisted events during replay", () => {
+    const sessionId = "sess-1";
+    const entries = [
+      {
+        type: "message",
+        id: "u1",
+        timestamp: "2026-04-27T07:26:25.000Z",
+        message: { role: "user", content: [{ type: "text", text: "Hi" }] },
+      },
+      {
+        type: "message",
+        id: "a1",
+        parentId: "u1",
+        timestamp: "2026-04-27T07:26:30.000Z",
+        message: { role: "assistant", content: [{ type: "text", text: "Hello!" }] },
+      },
+    ];
+
+    const events = replayEntriesAsEvents(sessionId, entries);
+    const persisted = events.filter((e) => e.event.eventType === "entry_persisted");
+    expect(persisted).toHaveLength(0);
+  });
+});

package/packages/shared/src/platform/index.ts

@@ -9,6 +9,7 @@ export * from "./detached-spawn.js";
 export * from "./spawn-mechanism.js";
 export * from "./process-identify.js";
 export * from "./subprocess-adapter.js";
+export * from "./node-spawn.js";
 export * as git from "./git.js";
 export * as openspec from "./openspec.js";
 export * as npm from "./npm.js";

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

@@ -0,0 +1,154 @@
+/**
+ * Canonical helper for spawning `node --import <loader> <entry>` argv.
+ *
+ * Node ≥ 20's ESM loader parses BOTH the `--import` loader position AND
+ * the entry-script position as URLs. Raw Windows paths like
+ * `B:\Dev\foo.ts` URL-parse to scheme `b:`, which is not in the ESM
+ * loader's allowlist (file, data, node) → the process crashes with
+ * `ERR_UNSUPPORTED_ESM_URL_SCHEME` before any filesystem access.
+ *
+ * Node's internal drive-letter heuristic catches the common cases
+ * (`C:\`, `D:\`) but has known gaps for `A:`, `B:`, and other letters.
+ * Rather than relying on the heuristic, we wrap the loader position
+ * with `file://` unconditionally.
+ *
+ * The entry-script position needs a more nuanced rule. Node's default
+ * resolver AND jiti's ESM hook both accept `file://` URL entries. But
+ * **tsx's ESM hook rejects `file://` URLs as entries** — tsx's resolver
+ * treats the entry as a user-typed specifier and attempts bare-import
+ * / relative-path resolution, producing `<cwd>/file:/...` errors.
+ * Since tsx is used as the jiti fallback on dev machines without pi
+ * installed (the most common Linux dev path), we must NOT URL-wrap
+ * the entry when the loader is tsx. Detection: the loader path
+ * contains `/tsx/` (every tsx install ships its hook under a `tsx/`
+ * directory; jiti's hook is under `jiti/`).
+ *
+ * This module is the canonical chokepoint. The repo-level lint test
+ * `no-raw-node-import.test.ts` refuses any other call site that
+ * passes a raw path to `--import` / `--loader`.
+ *
+ * See change: fix-windows-entry-script-url.
+ */
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { SpawnOptions, ChildProcess } from "node:child_process"; // ban:child_process-ok — types only
+import { spawn as execSpawn } from "./exec.js";
+
+export interface SpawnNodeScriptOptions {
+  /** Path to node.exe / node (raw OS path — binary, not ESM-loaded). */
+  nodeBin?: string;
+
+  /** Path to the script Node will run. Raw path OR file:// URL. */
+  entry: string;
+
+  /** Optional ESM loader for --import. Raw path OR file:// URL. */
+  loader?: string;
+
+  /** Arguments passed to the script (after entry). */
+  args?: string[];
+
+  /** Standard spawn options (cwd, env, stdio, detached, etc.). */
+  spawnOptions?: SpawnOptions;
+}
+
+/**
+ * Detect whether a loader (file:// URL or raw path) is tsx.
+ *
+ * tsx's ESM hook rejects `file://` URLs at the entry-script position,
+ * so the caller must pass a raw OS path for the entry when this
+ * returns true. jiti and Node's default resolver both accept URL
+ * entries.
+ *
+ * Heuristic: every tsx install places its hook under a `tsx/` package
+ * directory (e.g. `.../node_modules/tsx/dist/esm/index.mjs`). The
+ * check is tolerant of `file://` URLs, raw POSIX paths, and raw
+ * Windows paths with either slash direction.
+ */
+export function isTsxLoader(loader: string | null | undefined): boolean {
+  if (!loader) return false;
+  // Normalize backslashes so the `/tsx/` probe works on Windows paths.
+  const normalized = loader.replace(/\\/g, "/");
+  return /\/tsx\//i.test(normalized);
+}
+
+/**
+ * Convert a path-or-url string to a file:// URL.
+ *
+ * Pure and idempotent. Safe to call on strings that are already
+ * file:// URLs — returns them unchanged.
+ *
+ * Handles Windows-style input (drive letter + backslash) regardless of
+ * host OS, so unit tests on Linux/macOS can exercise the Windows path
+ * contract. Mirrors the pattern in
+ * `packages/shared/src/resolve-jiti.ts::buildJitiRegisterUrl`.
+ */
+export function toFileUrl(pathOrUrl: string): string {
+  if (pathOrUrl.startsWith("file:")) return pathOrUrl;
+
+  const isWindowsStyle = /^[A-Za-z]:[\\/]/.test(pathOrUrl);
+  if (isWindowsStyle) {
+    // pathToFileURL on POSIX hosts URL-encodes backslashes rather than
+    // treating them as separators. Build the URL manually so tests on
+    // Linux produce the same result a Windows host would.
+    return `file:///${pathOrUrl.replace(/\\/g, "/")}`;
+  }
+
+  // Use path.resolve to ensure absolute path on the host OS, then
+  // let Node's pathToFileURL handle any host-specific quirks.
+  const absolute = path.isAbsolute(pathOrUrl) ? pathOrUrl : path.resolve(pathOrUrl);
+  return pathToFileURL(absolute).href;
+}
+
+/**
+ * Decide whether the entry-script position needs `file://` URL wrapping.
+ *
+ * Rule:
+ *   - tsx loader: always raw path (tsx rejects file:// entries on every OS)
+ *   - non-tsx (jiti / Node default) on POSIX: raw path
+ *     (POSIX has no drive-letter / URL-scheme collision; jiti's resolver
+ *      actively MISBEHAVES when handed `file://` URL entries — it
+ *      normalises away the triple-slash and then treats `file:/...` as
+ *      a relative specifier, producing `<cwd>/file:/...` ENOENT errors.)
+ *   - non-tsx on Windows: file:// URL
+ *     (Node parses drive letters like `B:` / `A:` as URL schemes in argv
+ *      before loaders run, throwing ERR_UNSUPPORTED_ESM_URL_SCHEME.
+ *      Wrapping with `file://` sidesteps the parse.)
+ *
+ * Keeps a `platform` parameter for testability so unit tests on a POSIX
+ * host can exercise the Windows branch without mutating `process.platform`.
+ */
+export function shouldUrlWrapEntry(
+  loader: string | null | undefined,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (isTsxLoader(loader)) return false;
+  return platform === "win32";
+}
+
+/**
+ * Spawn `node` with an optional `--import` loader and a script entry.
+ *
+ * The loader position is always URL-wrapped (Node's ESM loader
+ * requires `file://` on Windows drive letters outside the heuristic).
+ *
+ * The entry position follows `shouldUrlWrapEntry(loader, platform)` —
+ * URL on Windows + non-tsx, raw everywhere else.
+ *
+ * Delegates actual spawning to `platform/exec.ts::spawn` so the
+ * `windowsHide: true` default and other safe-spawn invariants are
+ * preserved. Does not import `node:child_process` directly (the type
+ * imports above are annotated with the opt-out marker).
+ */
+export function spawnNodeScript(opts: SpawnNodeScriptOptions): ChildProcess {
+  const nodeBin = opts.nodeBin ?? process.execPath;
+  const wrapEntry = shouldUrlWrapEntry(opts.loader);
+
+  const argv: string[] = [];
+  if (opts.loader) {
+    argv.push("--import", toFileUrl(opts.loader));
+  }
+  argv.push(wrapEntry ? toFileUrl(opts.entry) : opts.entry);
+  if (opts.args) argv.push(...opts.args);
+
+  return execSpawn(nodeBin, argv, opts.spawnOptions ?? {});
+}

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/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,

package/packages/shared/src/tool-registry/definitions.ts

@@ -22,6 +22,7 @@ import {
   overrideStrategy,
   whereStrategy,
 } from "./strategies.js";
+import type { Strategy } from "./types.js";
 
 // ── Classifier ──────────────────────────────────────────────────────────────
 
@@ -66,6 +67,68 @@ function moduleDefWithAliases(
   return { name: canonicalName, kind: "module", strategies, classify };
 }
 
+// ── Build-time module definitions (electron, node-pty) ────────────────────
+
+/**
+ * Bare-import strategy that resolves `<pkg>/package.json` and returns the
+ * containing directory. Used for build-time tools whose useful artifact is
+ * a sibling file of `package.json` (e.g. `electron/install.js`,
+ * `node-pty/prebuilds/`). Mirrors the semantics that build-time consumers
+ * (`publish.yml`, `Dockerfile.build`, `scripts/fix-pty-permissions.cjs`)
+ * need — see change: register-build-time-tools.
+ *
+ * `searchPaths` are passed to Node's resolver as the `paths` option,
+ * making the lookup work whether the package is hoisted to the repo root
+ * or nested under a workspace.
+ */
+function bareImportPackageDirStrategy(
+  pkgName: string,
+  searchPaths?: readonly string[],
+  deps?: StrategyDeps,
+): Strategy {
+  const fallbackResolve = (id: string, from: string): string | null => {
+    try {
+      if (searchPaths && searchPaths.length > 0) {
+        const req = createRequire(from) as unknown as {
+          resolve(id: string, opts?: { paths?: readonly string[] }): string;
+        };
+        return req.resolve(id, { paths: searchPaths });
+      }
+      return createRequire(from).resolve(id);
+    } catch {
+      return null;
+    }
+  };
+  const resolveModule = deps?.resolveModule ?? fallbackResolve;
+  return {
+    name: "bare-import",
+    run() {
+      const pkgJson = resolveModule(`${pkgName}/package.json`, import.meta.url);
+      if (!pkgJson) {
+        return { ok: false, reason: `cannot resolve ${pkgName}/package.json` };
+      }
+      return { ok: true, path: path.dirname(pkgJson) };
+    },
+  };
+}
+
+/** Module def that returns the package directory (containing package.json). */
+function packageDirModuleDef(
+  toolName: string,
+  pkgName: string,
+  options: { searchPaths?: readonly string[]; includeManaged?: boolean },
+  deps?: StrategyDeps,
+): ToolDefinition {
+  const strategies: Strategy[] = [
+    overrideStrategy(toolName, deps),
+    bareImportPackageDirStrategy(pkgName, options.searchPaths, deps),
+  ];
+  if (options.includeManaged) {
+    strategies.push(managedModuleStrategy(pkgName, "package.json", deps));
+  }
+  return { name: toolName, kind: "module", strategies, classify };
+}
+
 // ── Registration ─────────────────────────────────────────────────
 
 // Tools intentionally NOT registered:
@@ -76,6 +139,14 @@ function moduleDefWithAliases(
 //   - `pi-dashboard` — that's the package this code is part of.
 //     "Is it installed" is a bootstrap concern handled directly in
 //     `packages/electron/src/lib/dependency-detector.ts`.
+//
+// Build-time tools (see change: register-build-time-tools):
+//   - `electron`   — module, returns the package directory containing
+//                    `install.js`. Resolved with paths anchored at
+//                    `packages/electron` to handle hoisted vs. nested
+//                    layouts uniformly.
+//   - `node-pty`   — module, returns the package directory containing
+//                    `prebuilds/`. Standard module resolution suffices.
 // See change: consolidate-tool-resolution (follow-up).
 
 /**
@@ -333,6 +404,27 @@ export function registerDefaultTools(registry: ToolRegistry, deps?: StrategyDeps
       deps,
     ),
   );
+
+  // Build-time tools (see change: register-build-time-tools).
+  registry.register(
+    packageDirModuleDef(
+      "electron",
+      "electron",
+      {
+        searchPaths: [path.resolve("packages/electron")],
+        includeManaged: true,
+      },
+      deps,
+    ),
+  );
+  registry.register(
+    packageDirModuleDef(
+      "node-pty",
+      "node-pty",
+      { includeManaged: false },
+      deps,
+    ),
+  );
 }
 
 /** Handy re-exports for callers that want raw definitions for testing. */