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

package/packages/shared/src/platform/binary-lookup.ts

@@ -4,11 +4,106 @@
  * with a single configurable resolver.
  */
 import { execSync, spawnSync, buildSafeArgv } from "./exec.js";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { MANAGED_BIN, MANAGED_DIR } from "../managed-paths.js";
 
+// ── AppImage self-hit guard (Linux power-user mode safety) ────────────────
+
+/**
+ * Optional environment overrides for {@link isAppImageSelfHit}. Tests
+ * inject explicit values so the helper can exercise both branches
+ * without mutating `process.env` or `process.execPath`. Production
+ * callers omit `opts` and the helper reads from the live process.
+ *
+ * See change: fix-electron-appimage-cli-self-detection (D1).
+ */
+export interface AppImageSelfHitOpts {
+  /** Override `process.execPath`. Default: `process.execPath`. */
+  execPath?: string;
+  /** Override `process.env.APPDIR`. Default: `process.env.APPDIR`. */
+  appDir?: string | undefined;
+  /** Override `process.env.APPIMAGE`. Default: `process.env.APPIMAGE`. */
+  appImage?: string | undefined;
+}
+
+/** Defensive realpath — returns the input on any error (broken symlink / ENOENT). */
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Returns `true` when `candidatePath` is the running process's own
+ * Electron launcher binary — the bug class that motivates this helper:
+ * AppImage's runtime prepends its squashfs mount (`/tmp/.mount_*`) to
+ * `PATH` of the Electron child, and `packagerConfig.executableName =
+ * "pi-dashboard"` makes the launcher a name-collision with the dashboard
+ * CLI. Trusting the first `which pi-dashboard` hit therefore spawns the
+ * Electron app recursively as if it were the CLI.
+ *
+ * A path is considered a self-hit when ANY of the following is true:
+ *   - `realpath(candidatePath) === realpath(execPath)`, OR
+ *   - `candidatePath` lives under the directory named by `appDir`, OR
+ *   - `realpath(candidatePath) === realpath(appImage)`.
+ *
+ * `realpath` calls are wrapped in try/catch so broken symlinks / ENOENT
+ * fall back to literal string comparisons. The helper never throws.
+ *
+ * Production callers (`whereStrategy`, `detectPiDashboardCli`,
+ * `detectPi`, `detectSystemNode`) omit `opts`. Tests pass explicit
+ * overrides via `opts`.
+ *
+ * See change: fix-electron-appimage-cli-self-detection (D1).
+ */
+export function isAppImageSelfHit(
+  candidatePath: string,
+  opts?: AppImageSelfHitOpts,
+): boolean {
+  if (!candidatePath) return false;
+
+  const execPath = opts && "execPath" in opts ? opts.execPath : process.execPath;
+  const appDir = opts && "appDir" in opts ? opts.appDir : process.env.APPDIR;
+  const appImage = opts && "appImage" in opts ? opts.appImage : process.env.APPIMAGE;
+
+  const realCandidate = safeRealpath(candidatePath);
+
+  // Rule 1: realpath equals process.execPath
+  if (execPath) {
+    const realExec = safeRealpath(execPath);
+    if (realCandidate === realExec) return true;
+    if (candidatePath === execPath) return true;
+  }
+
+  // Rule 2: candidate lives under APPDIR (the AppImage squashfs mount).
+  // We compare the candidate's realpath against APPDIR's realpath so a
+  // symlink under the mount is still recognized as a self-hit.
+  if (appDir) {
+    const realAppDir = safeRealpath(appDir);
+    const sep = path.sep;
+    // Append separator so /tmp/.mount_PI doesn't accidentally match
+    // /tmp/.mount_PIxx-elsewhere via prefix.
+    const prefix = realAppDir.endsWith(sep) ? realAppDir : realAppDir + sep;
+    if (realCandidate === realAppDir || realCandidate.startsWith(prefix)) return true;
+    // Literal fallback (broken symlinks / ENOENT keep a useful answer).
+    const litPrefix = appDir.endsWith(sep) ? appDir : appDir + sep;
+    if (candidatePath === appDir || candidatePath.startsWith(litPrefix)) return true;
+  }
+
+  // Rule 3: realpath equals APPIMAGE (the .AppImage file the user clicked).
+  if (appImage) {
+    const realAppImage = safeRealpath(appImage);
+    if (realCandidate === realAppImage) return true;
+    if (candidatePath === appImage) return true;
+  }
+
+  return false;
+}
+
 /**
  * Well-known globalThis symbol for the default `ToolRegistry`.
  *

package/packages/shared/src/plugin-bridge-register.ts

@@ -0,0 +1,139 @@
+/**
+ * Plugin bridge entry management in pi's settings.json.
+ *
+ * Manages `dashboard-<plugin-id>` keys in a dedicated
+ * `dashboardPluginBridges` object inside settings.json.
+ *
+ * Rules:
+ * - Only touches entries under the `dashboardPluginBridges` key.
+ * - NEVER modifies user-owned `packages[]` entries.
+ * - Uses atomic write (tmp + rename) for all updates.
+ * - Detects path conflicts (existing entry with mismatched path).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export interface PluginBridgeRegisterOptions {
+  homedir?: string;
+}
+
+export type PluginBridgeConflict =
+  | { type: "ok" }
+  | { type: "conflict"; existingPath: string; newPath: string };
+
+function getSettingsPath(homedir?: string): string {
+  const home = homedir ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
+  return path.join(home, ".pi", "agent", "settings.json");
+}
+
+function readSettings(settingsPath: string): Record<string, unknown> {
+  try {
+    if (!fs.existsSync(settingsPath)) return {};
+    const raw = fs.readFileSync(settingsPath, "utf-8").trim();
+    if (!raw) return {};
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(settingsPath: string, settings: Record<string, unknown>): void {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  const tmp = settingsPath + ".tmp." + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+  fs.renameSync(tmp, settingsPath);
+}
+
+function getManagedBridges(
+  settings: Record<string, unknown>,
+): Record<string, string> {
+  const val = settings.dashboardPluginBridges;
+  if (val && typeof val === "object" && !Array.isArray(val)) {
+    return val as Record<string, string>;
+  }
+  return {};
+}
+
+const MANAGED_PREFIX = "dashboard-";
+
+/**
+ * Register a plugin's bridge entry in pi's settings.json.
+ *
+ * Returns { type: "conflict", existingPath, newPath } if a
+ * `dashboard-<pluginId>` key already exists but points to a different path.
+ * In that case the settings.json is NOT modified.
+ *
+ * Returns { type: "ok" } on success (including when the entry already matches).
+ */
+export function registerPluginBridge(
+  pluginId: string,
+  bridgePath: string,
+  opts: PluginBridgeRegisterOptions = {},
+): PluginBridgeConflict {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  const managed = getManagedBridges(settings);
+  const key = MANAGED_PREFIX + pluginId;
+
+  const existing = managed[key];
+  if (existing) {
+    if (existing === bridgePath) return { type: "ok" }; // already registered
+    return { type: "conflict", existingPath: existing, newPath: bridgePath };
+  }
+
+  managed[key] = bridgePath;
+  settings.dashboardPluginBridges = managed;
+  writeSettings(settingsPath, settings);
+  console.info(`[plugin-bridge] Registered bridge for plugin "${pluginId}": ${bridgePath}`);
+  return { type: "ok" };
+}
+
+/**
+ * Remove a plugin's bridge entry from pi's settings.json.
+ * No-op if the entry does not exist.
+ * NEVER touches entries without the `dashboard-` prefix.
+ */
+export function deregisterPluginBridge(
+  pluginId: string,
+  opts: PluginBridgeRegisterOptions = {},
+): void {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  const managed = getManagedBridges(settings);
+  const key = MANAGED_PREFIX + pluginId;
+
+  if (!(key in managed)) return; // nothing to remove
+
+  delete managed[key];
+  settings.dashboardPluginBridges = managed;
+  writeSettings(settingsPath, settings);
+  console.info(`[plugin-bridge] Deregistered bridge for plugin "${pluginId}"`);
+}
+
+/**
+ * Register all plugins with bridge entries from the discovery list.
+ * Returns a map of pluginId → conflict/ok result.
+ * Plugins with conflicts are NOT registered; caller should surface via /api/health.
+ */
+export function registerAllPluginBridges(
+  plugins: Array<{ pluginId: string; bridgePath: string }>,
+  opts: PluginBridgeRegisterOptions = {},
+): Record<string, PluginBridgeConflict> {
+  const results: Record<string, PluginBridgeConflict> = {};
+  for (const { pluginId, bridgePath } of plugins) {
+    results[pluginId] = registerPluginBridge(pluginId, bridgePath, opts);
+  }
+  return results;
+}
+
+/**
+ * List all currently managed plugin bridge entries.
+ */
+export function listManagedBridges(
+  opts: PluginBridgeRegisterOptions = {},
+): Record<string, string> {
+  const settingsPath = getSettingsPath(opts.homedir);
+  const settings = readSettings(settingsPath);
+  return getManagedBridges(settings);
+}

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 ──────────────────────────────────────────────
 
@@ -228,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
@@ -250,7 +283,10 @@ export type ExtensionToServerMessage =
   | FirstMessageUpdateMessage
   | RolesListMessage
   | SpawnNewSessionMessage
-  | ProcessListMessage;
+  | ProcessListMessage
+  | UiModulesListMessage
+  | UiDataListMessage
+  | ExtUiDecoratorMessage;
 
 // ── Server → Extension ──────────────────────────────────────────────
 
@@ -401,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;
@@ -435,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

@@ -23,9 +23,19 @@ import type { EventForwardMessage } from "./protocol.js";
  * 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
@@ -86,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/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;