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

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

@@ -0,0 +1,196 @@
+/**
+ * Recommended pi extensions for pi-agent-dashboard.
+ *
+ * The dashboard has custom UI and wiring for a small set of pi extensions
+ * it was built to work with. This manifest enumerates them so the dashboard
+ * can surface installation status, offer one-click installs in the Packages
+ * tab, walk users through setup in the first-launch wizard, and warn when
+ * a `required` entry is missing.
+ *
+ * This list is intentionally curated (not auto-discovered from npm). Each
+ * entry lives and dies by explicit PR review — the dashboard team owns the
+ * decision of which extensions are promoted.
+ *
+ * Descriptions in `fallbackDescription` are shipped inline. At runtime the
+ * dashboard server optionally enriches them with live descriptions fetched
+ * from the npm registry or GitHub (see `/api/packages/recommended`).
+ */
+
+/** Relative importance of a recommended extension. */
+export type RecommendedExtensionStatus =
+	| "required"            // dashboard features or provider paths break without it
+	| "strongly-suggested"  // dashboard has UI that depends on this
+	| "optional";           // nice-to-have
+
+/** Static manifest entry. Enriched at runtime via the recommended route. */
+export interface RecommendedExtension {
+	/** Stable kebab-case identifier. Used for skip/persist state and IPC. */
+	id: string;
+
+	/**
+	 * pi install source. Any form parseable by pi's DefaultPackageManager:
+	 *   - `npm:<name>`
+	 *   - `git:<host>/<path>`
+	 *   - `git@<host>:<path>.git`
+	 *   - `https://<host>/<path>.git`
+	 *   - local path
+	 */
+	source: string;
+
+	/** Human-readable package name for the UI. */
+	displayName: string;
+
+	/**
+	 * Fallback description. Used when npm/GitHub is unreachable. Kept
+	 * short (one or two sentences).
+	 */
+	fallbackDescription: string;
+
+	/** Relative importance. */
+	status: RecommendedExtensionStatus;
+
+	/** Which dashboard features light up when this is installed. */
+	unlocks: string[];
+
+	/** Tool names this extension registers (for diagnostics / UI hinting). */
+	toolsRegistered?: string[];
+
+	/**
+	 * True when the extension self-wires into pi / dashboard without
+	 * additional configuration — installing it is sufficient for it to
+	 * start working.
+	 */
+	autowired?: boolean;
+}
+
+/** Enriched manifest entry returned by GET /api/packages/recommended. */
+export interface EnrichedRecommendedExtension extends RecommendedExtension {
+	/** Live description (falls back to `fallbackDescription` on fetch failure). */
+	description: string;
+	/** Current upstream version, if available. */
+	version?: string;
+	/**
+	 * Install status by scope. `null` means not present on disk in any scope.
+	 */
+	installed: { scope: "global" | "local" | null };
+	/** True iff the source is currently listed in `~/.pi/agent/settings.json` `packages[]`. */
+	activeInPi: boolean;
+	/** True iff a newer version is available upstream. */
+	updateAvailable: boolean;
+}
+
+export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
+	{
+		id: "pi-anthropic-messages",
+		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 " +
+			"anthropic-messages endpoint for Claude models (direct Anthropic " +
+			"OAuth/API key, 9Router cc/claude-*, pi-model-proxy, any Claude " +
+			"Code-flavored proxy). Required whenever a provider has " +
+			'api: "anthropic-messages" with a Claude model — without it, ' +
+			"tool calls fall back to Claude Code's built-in bash_ide sandbox.",
+		status: "required",
+		unlocks: ["Tool calls on Anthropic OAuth / 9Router cc/* / proxy providers"],
+		autowired: true,
+	},
+	{
+		id: "tintinweb-pi-subagents",
+		source: "npm:@tintinweb/pi-subagents",
+		displayName: "@tintinweb/pi-subagents",
+		fallbackDescription:
+			"Claude Code-style autonomous sub-agents for pi. Registers " +
+			"the Agent tool and its companions. The dashboard has custom " +
+			"card UI for it.",
+		status: "strongly-suggested",
+		unlocks: [
+			"Agent tool card UI",
+			"Subagent activity badge",
+			"get_subagent_result / steer_subagent renderers",
+		],
+		toolsRegistered: ["Agent", "get_subagent_result", "steer_subagent"],
+		autowired: true,
+	},
+	{
+		id: "pi-flows",
+		source: "https://github.com/BlackBeltTechnology/pi-flows.git",
+		displayName: "pi-flows",
+		fallbackDescription:
+			"Flow engine, dashboard, and orchestration extensions for pi. " +
+			"Powers the dashboard's Flow view, role aliases, and multi-agent " +
+			"orchestration tools.",
+		status: "strongly-suggested",
+		unlocks: [
+			"Flow dashboard",
+			"Role aliases (@planning, @coding, …)",
+			"subagent / flow_write / flow_results / agent_write / ask_user / skill_read / finish tools",
+		],
+		toolsRegistered: [
+			"subagent",
+			"agent_catalog",
+			"agent_write",
+			"flow_write",
+			"flow_results",
+			"skill_read",
+			"ask_user",
+			"finish",
+		],
+		autowired: true,
+	},
+	{
+		id: "pi-web-access",
+		source: "npm:pi-web-access",
+		displayName: "pi-web-access",
+		fallbackDescription:
+			"Web search, URL fetching, GitHub repo cloning, PDF extraction, " +
+			"and YouTube / local video analysis for pi.",
+		status: "strongly-suggested",
+		unlocks: ["web_search", "code_search", "fetch_content", "get_search_content"],
+		toolsRegistered: [
+			"web_search",
+			"code_search",
+			"fetch_content",
+			"get_search_content",
+		],
+	},
+	{
+		id: "pi-agent-browser",
+		source: "npm:pi-agent-browser",
+		displayName: "pi-agent-browser",
+		fallbackDescription:
+			"Browser automation (open, snapshot, click, fill, screenshot) " +
+			"via the agent-browser CLI.",
+		status: "optional",
+		unlocks: ["browser tool (open, snapshot, click, screenshot)"],
+		toolsRegistered: ["browser"],
+	},
+];
+
+/**
+ * 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);
+}
+
+/** Retrieve all entries with the given status. */
+export function getRecommendedByStatus(
+	status: RecommendedExtensionStatus,
+): readonly RecommendedExtension[] {
+	return RECOMMENDED_EXTENSIONS.filter((e) => e.status === status);
+}

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

@@ -7,6 +7,11 @@ import type {
   ApiResponse,
 } from "./types.js";
 
+export type { ApiResponse } from "./types.js";
+import type { EnrichedRecommendedExtension } from "./recommended-extensions.js";
+
+export type { EnrichedRecommendedExtension } from "./recommended-extensions.js";
+
 // ── Sessions ────────────────────────────────────────────────────────
 
 export interface ListSessionsQuery {
@@ -63,14 +68,44 @@ export interface BrowseEntry {
   isPi: boolean;
 }
 
+/**
+ * Response shape for `GET /api/browse?path=<dir>&q=<query>`.
+ *
+ * The optional `q` query parameter, when present and non-empty, causes the
+ * server to filter entries by case-insensitive substring on `name` and rank
+ * them (exact → prefix → word-boundary → substring) before the 200-entry cap.
+ * When omitted or whitespace-only, entries are sorted alphabetically.
+ */
 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>;
 
+/** Request body for `POST /api/browse/mkdir`. */
+export interface MkdirRequest {
+  parent: string;
+  name: string;
+}
+
+export interface MkdirResult {
+  path: string;
+}
+
+export type MkdirResponse = ApiResponse<MkdirResult>;
+
 // ── Tunnel Status ───────────────────────────────────────────────────
 
 export type TunnelStatus =
@@ -246,6 +281,46 @@ export interface PackageUpdateInfo {
 
 export type CheckUpdatesResponse = ApiResponse<PackageUpdateInfo[]>;
 
+// ── Pi core version check ────────────────────────────────────
+
+/** A core pi ecosystem CLI package (not managed by pi's PackageManager). */
+export interface PiCorePackage {
+  name: string;
+  displayName: string;
+  currentVersion: string;
+  latestVersion: string | null;
+  updateAvailable: boolean;
+  installSource: "global" | "managed";
+}
+
+export interface PiCoreStatus {
+  packages: PiCorePackage[];
+  updatesAvailable: number;
+  lastChecked: string;
+}
+
+export type PiCoreVersionsResponse = ApiResponse<PiCoreStatus>;
+
+/** Request body for POST /api/pi-core/update. Empty packages = update all. */
+export interface PiCoreUpdateRequest {
+  packages?: string[];
+}
+
+/** Result of a single package update. */
+export interface PiCoreUpdateResult {
+  name: string;
+  success: boolean;
+  error?: string;
+}
+
+/** Response from POST /api/pi-core/update (completes synchronously). */
+export interface PiCoreUpdateResponse {
+  results: PiCoreUpdateResult[];
+  sessionsReloaded: number;
+}
+
+export type PiCoreUpdateApiResponse = ApiResponse<PiCoreUpdateResponse>;
+
 // ── Known Servers ─────────────────────────────────────────────
 
 import type { KnownServer } from "./config.js";
@@ -281,3 +356,25 @@ export interface NetworkInterface {
   netmask: string;
   cidr: string;
 }
+
+// ── Recommended extensions ───────────────────────────
+
+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/source-matching.ts

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// source-matching — canonical "two source strings refer to the same package"
+// predicate, shared between the server's /api/packages/recommended route
+// and the Electron wizard's bootstrap enricher.
+//
+// Pure string logic, no fs / no pi SDK dependency. Safe to import from any
+// package (shared, server, client, electron).
+//
+// Input sources take one of these forms:
+//
+//   npm:<name>[@<version>]
+//     e.g.  "npm:pi-web-access", "npm:@tintinweb/pi-subagents@0.5.2"
+//
+//   git@<host>:<owner>/<repo>[.git]
+//     e.g.  "git@github.com:BlackBeltTechnology/pi-flows.git"
+//
+//   https://<host>/<owner>/<repo>[.git][#ref]
+//     e.g.  "https://github.com/BlackBeltTechnology/pi-flows.git"
+//
+//   git:<host>/<owner>/<repo>[#ref]
+//     e.g.  "git:github.com/BlackBeltTechnology/pi-flows#main"
+//
+//   any other string (absolute path, relative path, unrecognized URL)
+//     → parsed as kind:"raw" with the literal preserved
+//
+// Matching rules:
+//   - Same kind: exact comparison of the semantically-meaningful parts.
+//   - Cross-kind (git ↔ raw): the raw source's basename (last path
+//     segment, stripped of trailing slash and trailing .git) must equal
+//     the git repo name, case-insensitive. This handles the common case
+//     where a user registered the package via `pi install -l <path>`
+//     instead of by URL and the basename is the repo name.
+// ---------------------------------------------------------------------------
+
+export type SourceKey =
+	| { kind: "npm"; name: string }
+	| { kind: "git"; host: string; owner: string; repo: string }
+	| { kind: "raw"; source: string };
+
+export function parseSourceKey(source: string): SourceKey {
+	const trimmed = source.trim();
+
+	if (trimmed.startsWith("npm:")) {
+		const spec = trimmed.slice(4).trim();
+		// Strip a trailing @version but preserve the scope @ in @scope/name.
+		// If spec starts with @, the SECOND @ (if any) delimits version.
+		let name = spec;
+		if (spec.startsWith("@")) {
+			const idx = spec.indexOf("@", 1);
+			if (idx > 0) name = spec.slice(0, idx);
+		} else {
+			const idx = spec.indexOf("@");
+			if (idx > 0) name = spec.slice(0, idx);
+		}
+		return { kind: "npm", name };
+	}
+
+	const sshMatch = trimmed.match(/^git@([^:]+):([^/]+)\/([^/.]+)(?:\.git)?$/);
+	if (sshMatch) {
+		return { kind: "git", host: sshMatch[1], owner: sshMatch[2], repo: sshMatch[3] };
+	}
+
+	const httpsMatch = trimmed.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/#.]+)(?:\.git)?(?:#.+)?$/);
+	if (httpsMatch) {
+		return {
+			kind: "git",
+			host: httpsMatch[1],
+			owner: httpsMatch[2],
+			repo: httpsMatch[3],
+		};
+	}
+
+	const gitPrefixMatch = trimmed.match(/^git:([^/]+)\/([^/]+)\/([^/#]+?)(?:\.git)?(?:#.+)?$/);
+	if (gitPrefixMatch) {
+		return {
+			kind: "git",
+			host: gitPrefixMatch[1],
+			owner: gitPrefixMatch[2],
+			repo: gitPrefixMatch[3],
+		};
+	}
+
+	return { kind: "raw", source: trimmed };
+}
+
+/**
+ * Extract the basename (last path segment, .git-stripped) from a raw
+ * source string. Returns lowercase or null.
+ */
+function localPathBasename(src: string): string | null {
+	const stripped = src.replace(/\/+$/, "").replace(/\.git$/, "");
+	const segments = stripped.split(/[\\/]/);
+	const tail = segments[segments.length - 1];
+	return tail ? tail.toLowerCase() : null;
+}
+
+/**
+ * True iff two source strings refer to the same package. See module
+ * header for the full matching rules and rationale.
+ */
+export function sourcesMatch(a: string, b: string): boolean {
+	const ka = parseSourceKey(a);
+	const kb = parseSourceKey(b);
+
+	if (ka.kind === kb.kind) {
+		if (ka.kind === "npm" && kb.kind === "npm") return ka.name === kb.name;
+		if (ka.kind === "git" && kb.kind === "git") {
+			return (
+				ka.host.toLowerCase() === kb.host.toLowerCase() &&
+				ka.owner.toLowerCase() === kb.owner.toLowerCase() &&
+				ka.repo.toLowerCase() === kb.repo.toLowerCase()
+			);
+		}
+		if (ka.kind === "raw" && kb.kind === "raw") return ka.source === kb.source;
+	}
+
+	// Cross-kind: git ↔ raw (local path). Match on repo basename.
+	const gitKey = ka.kind === "git" ? ka : kb.kind === "git" ? kb : null;
+	const rawKey = ka.kind === "raw" ? ka : kb.kind === "raw" ? kb : null;
+	if (gitKey && rawKey) {
+		const basename = localPathBasename(rawKey.source);
+		if (basename && basename === gitKey.repo.toLowerCase()) return true;
+	}
+
+	return false;
+}