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

package/packages/shared/src/protocol.ts

@@ -1,7 +1,7 @@
 /**
  * Extension ↔ Server WebSocket protocol messages.
  */
-import type { DashboardEvent, CommandInfo, FlowInfo, SessionSource, ImageContent, FileEntry, TurnUsage, ContextUsage, ModelInfo, PiSessionInfo, OpenSpecPhase, RoleInfo } from "./types.js";
+import type { DashboardEvent, CommandInfo, FlowInfo, SessionSource, ImageContent, FileEntry, TurnUsage, ContextUsage, ModelInfo, PiSessionInfo, OpenSpecPhase, RoleInfo, ExtensionUiModule, DecoratorDescriptor } from "./types.js";
 
 // ── Extension → Server ──────────────────────────────────────────────
 
@@ -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;
@@ -205,6 +228,39 @@ export interface ProcessListMessage {
 
 // LoadSessionEventsResultMessage and LoadSessionEventsErrorMessage removed — server loads directly
 
+// ── Extension UI System (Phase 1) ──
+// Pull-discovered, schema-driven UI modules. See change: add-extension-ui-modal.
+
+export interface UiModulesListMessage {
+  type: "ui_modules_list";
+  sessionId: string;
+  modules: ExtensionUiModule[];
+}
+
+export interface UiDataListMessage {
+  type: "ui_data_list";
+  sessionId: string;
+  /** Matches some `module.view.dataEvent`. */
+  event: string;
+  items: unknown[];
+}
+
+// ── Extension UI System (Phase 2: live in-page decorations) ──
+// See change: add-extension-ui-decorations.
+
+/**
+ * Extension → server: a single live decorator descriptor. Cache key
+ * `${kind}:${namespace}:${id}` MUST be unique within a session; `removed: true`
+ * deletes the cache entry instead of upserting.
+ */
+export interface ExtUiDecoratorMessage {
+  type: "ext_ui_decorator";
+  sessionId: string;
+  descriptor: DecoratorDescriptor;
+  /** When true, server deletes the cached descriptor under the matching key. */
+  removed?: boolean;
+}
+
 export type ExtensionToServerMessage =
   | SessionRegisterMessage
   | SessionUnregisterMessage
@@ -227,7 +283,10 @@ export type ExtensionToServerMessage =
   | FirstMessageUpdateMessage
   | RolesListMessage
   | SpawnNewSessionMessage
-  | ProcessListMessage;
+  | ProcessListMessage
+  | UiModulesListMessage
+  | UiDataListMessage
+  | ExtUiDecoratorMessage;
 
 // ── Server → Extension ──────────────────────────────────────────────
 
@@ -378,6 +437,23 @@ export interface ExtensionUiResponseMessage {
   cancelled?: boolean;
 }
 
+/**
+ * Server → extension: a browser invoked an action / requested data on a
+ * Phase-1 management-modal module. The bridge re-emits this on `pi.events`
+ * as `pi.events.emit(msg.event, { ...msg.params, action: msg.action, _reply })`.
+ * Extensions either populate `data.items` synchronously (for `action: "list"`
+ * data fetches) or perform side-effects and emit `ui:invalidate` to refresh.
+ */
+export interface UiManagementMessage {
+  type: "ui_management";
+  sessionId: string;
+  /** Action id (matches some `UiAction.id`) or `"list"` for data fetch. */
+  action: string;
+  /** Event name to emit (matches `view.dataEvent` or `UiAction.event`). */
+  event: string;
+  params?: Record<string, unknown>;
+}
+
 export interface PromptResponseServerMessage {
   type: "prompt_response";
   sessionId: string;
@@ -412,4 +488,5 @@ export type ServerToExtensionMessage =
   | RolePresetSaveExtensionMessage
   | RolePresetDeleteExtensionMessage
   | RequestRolesMessage
+  | UiManagementMessage
   | KillProcessMessage;

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

@@ -180,7 +180,13 @@ export const RECOMMENDED_EXTENSIONS: readonly RecommendedExtension[] = [
  */
 export const BUNDLED_EXTENSION_IDS: readonly string[] = [
 	"pi-anthropic-messages",
-	"pi-flows",
+	// "pi-flows" is intentionally NOT bundled until the upstream repo declares
+	// an SPDX-conformant license (`LICENSE` file or `package.json#license`).
+	// The bundle-recommended-extensions.sh license allowlist enforcement
+	// (MIT/Apache-2.0/BSD-2-Clause/BSD-3-Clause/ISC) correctly rejects it.
+	// Re-add this entry once https://github.com/BlackBeltTechnology/pi-flows
+	// has a license declared. See: openspec/changes/archive/
+	// 2026-04-21-bundle-first-party-extensions/design.md §"License blockers".
 ];
 
 /** Retrieve a recommended entry by id, or `undefined`. */

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

@@ -64,17 +64,35 @@ export type FileReadResponse = ApiResponse<FileReadResult>;
 export interface BrowseEntry {
   name: string;
   path: string;
-  isGit: boolean;
-  isPi: boolean;
+  /**
+   * Set only when the request used `detect=1`. When the response was
+   * produced without `detect=1`, this field is absent (undefined) —
+   * meaning "not classified", NOT "classified as not-git". Consumers
+   * that need badges SHOULD call `GET /api/browse/flags` to fill in
+   * the flags lazily.
+   *
+   * See change: split-browse-flags.
+   */
+  isGit?: boolean;
+  /** See `isGit` — same opt-in / detect-gated semantics. */
+  isPi?: boolean;
 }
 
 /**
- * Response shape for `GET /api/browse?path=<dir>&q=<query>`.
+ * Response shape for `GET /api/browse?path=<dir>&q=<query>&detect=<0|1>`.
  *
  * 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.
+ *
+ * The optional `detect` query parameter (only the literal string `"1"` is
+ * truthy) opts into eager `.git` / `.pi` classification on every entry. When
+ * absent (the default), per-entry `isGit` / `isPi` are omitted and no
+ * filesystem probes run — use the bulk `GET /api/browse/flags` endpoint to
+ * classify entries lazily.
+ *
+ * See change: split-browse-flags.
  */
 export interface BrowseResult {
   entries: BrowseEntry[];
@@ -94,6 +112,43 @@ export interface BrowseResult {
 
 export type BrowseResponse = ApiResponse<BrowseResult>;
 
+// ── Browse flags (bulk classifier) ──────────────────────────────────
+
+/**
+ * Per-path classification record returned by `GET /api/browse/flags`.
+ * Booleans only — any probe failure (ENOENT, EACCES, ELOOP, race-on-
+ * deletion, …) maps to `false` for that flag, never an error.
+ *
+ * See change: split-browse-flags.
+ */
+export interface BrowseFlagEntry {
+  isGit: boolean;
+  isPi: boolean;
+}
+
+/**
+ * Wire shape passed via the `paths` query parameter on
+ * `GET /api/browse/flags?paths=<json-array>`. The value MUST be a
+ * URL-encoded JSON array of absolute path strings (length ≤ 100).
+ * Provided here for type-only documentation — the request itself is a
+ * GET, so this interface is not serialized as a body.
+ */
+export interface BrowseFlagsRequest {
+  paths: string[];
+}
+
+/** Successful response payload for `GET /api/browse/flags`. */
+export interface BrowseFlagsResult {
+  /**
+   * Map keyed by the absolute paths that were requested. The key set
+   * SHALL equal the input `paths` set — one classification per input
+   * path, no extras, no omissions.
+   */
+  flags: Record<string, BrowseFlagEntry>;
+}
+
+export type BrowseFlagsResponse = ApiResponse<BrowseFlagsResult>;
+
 /** Request body for `POST /api/browse/mkdir`. */
 export interface MkdirRequest {
   parent: string;
@@ -254,6 +309,16 @@ export interface InstalledPackage {
   installedPath?: string;
   /** Set after check-updates: true if newer version available */
   updateAvailable?: boolean;
+  /** Version read from `<installedPath>/package.json#version`. Undefined if missing/unreadable. */
+  version?: string;
+  /** Description read from `<installedPath>/package.json#description`. */
+  description?: string;
+  /** Friendly name. From RECOMMENDED_EXTENSIONS displayName when matched, else basename of source. */
+  displayName?: string;
+  /** True when this row matches a RECOMMENDED_EXTENSIONS entry (via sourcesMatch). */
+  isRecommended?: boolean;
+  /** True when isRecommended AND id is in BUNDLED_EXTENSION_IDS AND bundle subtree exists. */
+  isBundled?: boolean;
 }
 
 export type InstalledPackagesResponse = ApiResponse<InstalledPackage[]>;

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

@@ -13,10 +13,29 @@ 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.
+ */
+/**
+ * @param knownContextWindow Optional override for the context window size,
+ *   typically `session.contextWindow` from `.meta.json` (which was persisted
+ *   from a live `turn_end` event). When provided, it is used in place of the
+ *   `inferContextWindow(modelId)` heuristic for every synthesized
+ *   `stats_update` event. The heuristic ignores Sonnet's 1M variant and
+ *   pins Claude to 200k, so passing the persisted value avoids a brief
+ *   200k flicker on reload before the next live `turn_end` arrives.
  */
 export function replayEntriesAsEvents(
   sessionId: string,
   entries: any[],
+  knownContextWindow?: number,
 ): EventForwardMessage[] {
   const messages: EventForwardMessage[] = [];
   const openToolCalls = new Set<string>(); // track tool calls without results
@@ -77,7 +96,7 @@ export function replayEntriesAsEvents(
           if (totalTokens && totalTokens > 0) {
             statsData.contextUsage = {
               tokens: totalTokens,
-              contextWindow: inferContextWindow(currentModel),
+              contextWindow: knownContextWindow ?? inferContextWindow(currentModel),
             };
           }
           messages.push(makeEvent(sessionId, "stats_update", ts, statsData));

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. */

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

@@ -11,7 +11,7 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
-import { ToolResolver } from "../platform/binary-lookup.js";
+import { ToolResolver, isAppImageSelfHit } from "../platform/binary-lookup.js";
 import { getManagedBin, getManagedDir } from "../managed-paths.js";
 import * as npm from "../platform/npm.js";
 import type { Strategy, StrategyCtx, StrategyResult } from "./types.js";
@@ -152,6 +152,17 @@ export function npmGlobalStrategy(
 /**
  * PATH search via `ToolResolver.which()`. This is the plain-old "is it
  * on PATH" strategy and should appear last in most chains.
+ *
+ * Filters AppImage self-hits via `isAppImageSelfHit` — when the host
+ * runs as a Linux AppImage with `executableName: "pi-dashboard"`, the
+ * AppImage runtime prepends its squashfs mount to PATH, so the first
+ * `which pi-dashboard` hit can be the Electron launcher itself.
+ * Trusting that result spawns the Electron app recursively as if it
+ * were the dashboard CLI, which never opens the dashboard port and
+ * causes the loading screen to hang. Every tool registered via
+ * `whereStrategy` inherits this guard transparently.
+ *
+ * See change: fix-electron-appimage-cli-self-detection (D2).
  */
 export function whereStrategy(binaryName: string, deps?: StrategyDeps): Strategy {
   const { which } = d(deps);
@@ -159,8 +170,11 @@ export function whereStrategy(binaryName: string, deps?: StrategyDeps): Strategy
     name: "where",
     run(): StrategyResult {
       const p = which(binaryName);
-      if (p) return { ok: true, path: p };
-      return { ok: false, reason: `not found on PATH` };
+      if (!p) return { ok: false, reason: `not found on PATH` };
+      if (isAppImageSelfHit(p)) {
+        return { ok: false, reason: `appimage-self-hit: ${p}` };
+      }
+      return { ok: true, path: p };
     },
   };
 }

package/packages/shared/src/types.ts

@@ -61,8 +61,168 @@ export interface DashboardSession {
     /** Timestamp when metrics were last received */
     updatedAt: number;
   };
+  /** Extension-declared UI modules (Phase 1: management-modal slot). */
+  uiModules?: ExtensionUiModule[];
+  /** Cached row data per `view.dataEvent` for table/grid views. Per-event item cap is enforced server-side. */
+  uiDataMap?: Record<string, unknown[]>;
+  /**
+   * Phase-2 live in-page decorations (footer-segment, agent-metric, breadcrumb,
+   * gate, toast). Keyed by `${kind}:${namespace}:${id}`. Last-write-wins on
+   * upsert; explicit removal via `ext_ui_decorator { removed: true }` deletes
+   * the entry. See change: add-extension-ui-decorations.
+   */
+  uiDecorators?: Record<string, DecoratorDescriptor>;
+}
+
+// ── Extension UI System (Phase 1: management-modal slot) ───────────
+// Per `extension-ui-system` design + `add-extension-ui-modal` change.
+// Field/type names match PR #15 verbatim so any later archival diff stays small.
+
+export type UiViewKind = "table" | "grid" | "form";
+
+export type UiFieldKind =
+  | "text"
+  | "number"
+  | "boolean"
+  | "select"
+  | "code"
+  | "datetime"
+  | "textarea";
+
+export interface UiField {
+  /** Dot-path into row / form-state. */
+  key: string;
+  label: string;
+  kind: UiFieldKind;
+  /** For kind: "select". */
+  options?: string[];
+  placeholder?: string;
+  required?: boolean;
+  readOnly?: boolean;
+  /** Legacy alias for kind: "textarea". Prefer `kind: "textarea"`. */
+  multiline?: boolean;
+  /** Display-only: table column width. */
+  width?: string | number;
+  /** For kind: "code". Hint to syntax highlighter. */
+  language?: string;
 }
 
+export interface UiAction {
+  /** Action id, echoed back as the `action` field on the `ui_management` message. */
+  id: string;
+  label: string;
+  /** MDI icon key from `@mdi/js` (e.g. `"mdiCheckCircle"`). Unknown keys render no icon. */
+  icon?: string;
+  variant?: "primary" | "secondary" | "danger";
+  /** Event name re-emitted on the extension's `pi.events` bus when the action fires. */
+  event: string;
+  params?: Record<string, unknown>;
+  /** If present, dashboard mounts ConfirmDialog with this message before dispatching. */
+  confirm?: string;
+}
+
+export interface UiSection {
+  id: string;
+  title?: string;
+  description?: string;
+  fields: UiField[];
+}
+
+export interface UiView {
+  kind: UiViewKind;
+  /** Table/grid columns; form fields when no `sections` provided. */
+  fields?: UiField[];
+  /** For form view: grouped fields. Mutually exclusive with top-level `fields`. */
+  sections?: UiSection[];
+  /** Event name to request rows; required for `table`/`grid`. */
+  dataEvent?: string;
+  /** Unique-row field for `table`/`grid` (default: `"id"`). */
+  rowKey?: string;
+  /** Per-row actions for `table`/`grid`. */
+  rowActions?: UiAction[];
+  /** Shown when `items.length === 0`. */
+  emptyState?: string;
+  /** Top-of-modal toolbar actions. */
+  actions?: UiAction[];
+}
+
+export interface ExtensionUiModule {
+  /** Phase 1: only `"management-modal"`. */
+  kind: "management-modal";
+  /** Unique within the session. Last-write-wins on collision. */
+  id: string;
+  /** Exact slash command (case-sensitive). */
+  command: string;
+  title: string;
+  description?: string;
+  /** MDI icon key from `@mdi/js`. */
+  icon?: string;
+  /** Free-form group label (sidebar grouping in future). */
+  category?: string;
+  view: UiView;
+}
+
+// ── Extension UI System (Phase 2: live in-page decorations) ──────
+// Per `extension-ui-system` design + `add-extension-ui-decorations` change.
+// Single discriminated union forwarded as one `ext_ui_decorator` message per
+// descriptor. Cache key: `${kind}:${namespace}:${id}`. `namespace` MUST match
+// `/^[a-z0-9-]+$/`; the bridge drops malformed namespaces with a warning.
+
+export type DecoratorKind =
+  | "footer-segment"
+  | "agent-metric"
+  | "breadcrumb"
+  | "gate"
+  | "toast";
+
+export interface FooterSegmentPayload {
+  text: string;
+  tooltip?: string;
+  /** MDI icon key from `@mdi/js`. Unknown keys render no icon. */
+  icon?: string;
+}
+
+export interface AgentMetricPayload {
+  /** Matches the agent id rendered by `FlowAgentCard`. */
+  agentId: string;
+  text: string;
+  tooltip?: string;
+}
+
+export interface BreadcrumbStep {
+  id: string;
+  label: string;
+  status: "pending" | "active" | "done" | "error";
+}
+
+export interface BreadcrumbPayload {
+  steps: BreadcrumbStep[];
+  /** Step id of the currently-active step (overrides `status: "active"` selection). */
+  current?: string;
+}
+
+export interface GatePayload {
+  /** Matches the flow id rendered in `FlowLaunchDialog`. */
+  flowId: string;
+  available: boolean;
+  /** Reason rendered as a tooltip when `available: false`. */
+  reason?: string;
+}
+
+export interface ToastPayload {
+  level: "info" | "success" | "warn" | "error";
+  message: string;
+  /** Auto-dismiss after this many ms. Default 5000; `0` = sticky. */
+  durationMs?: number;
+}
+
+export type DecoratorDescriptor =
+  | { kind: "footer-segment"; namespace: string; id: string; payload: FooterSegmentPayload }
+  | { kind: "agent-metric";   namespace: string; id: string; payload: AgentMetricPayload }
+  | { kind: "breadcrumb";     namespace: string; id: string; payload: BreadcrumbPayload }
+  | { kind: "gate";           namespace: string; id: string; payload: GatePayload }
+  | { kind: "toast";          namespace: string; id: string; payload: ToastPayload };
+
 /** An event forwarded from a pi session */
 export interface DashboardEvent {
   eventType: string;