@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/packages/shared/src/browser-protocol.ts

@@ -22,6 +22,14 @@ import type { EditorInstanceStatus } from "./editor-types.js";
 export interface SessionAddedMessage {
   type: "session_added";
   session: DashboardSession;
+  /**
+   * Echoed `requestId` from the originating browser `spawn_session` /
+   * `resume_session` (when known). Lets the client auto-select / dismiss
+   * placeholder by exact correlation, replacing the cwd-FIFO heuristic.
+   * Absent for server-initiated spawns (auto-resume, headless reload).
+   * See change: spawn-correlation-token.
+   */
+  spawnRequestId?: string;
 }
 
 export interface SessionUpdatedMessage {
@@ -118,6 +126,24 @@ export interface ResumeResultBrowserMessage {
   sessionId: string;
   success: boolean;
   message: string;
+  /** Echoed from input `resume_session.requestId` when provided. */
+  requestId?: string;
+  /**
+   * For `mode: "fork"` only — populated once the new fork's bridge has
+   * registered and been correlated. Absent for `mode: "continue"` (the
+   * sessionId is unchanged across the respawn).
+   * See change: spawn-correlation-token.
+   */
+  newSessionId?: string;
+  /**
+   * Optional structured failure classifier. Known values:
+   *   - `"FORK_EMPTY_SESSION"`: fork attempted on a session whose
+   *     `sessionFile` does not exist on disk yet (e.g., freshly spawned,
+   *     no messages persisted).
+   * Old clients that don't read this field still get the human-readable
+   * `message`. See change: fix-fork-empty-session-silent-timeout.
+   */
+  code?: string;
 }
 
 export interface SpawnResultBrowserMessage {
@@ -125,6 +151,37 @@ export interface SpawnResultBrowserMessage {
   cwd: string;
   success: boolean;
   message: string;
+  /** Echoed from input `spawn_session.requestId` when provided. */
+  requestId?: string;
+  /** Spawned process PID when known (headless strategies); informational. */
+  pid?: number;
+}
+
+/**
+ * Failure classification codes for spawn errors.
+ * Set on every `{ success: false }` path inside process-manager and the
+ * session-action-handler. Additive — clients that do not know a code fall
+ * back to the `message` string.
+ * See change: spawn-failure-diagnostics.
+ */
+export type SpawnFailureCode =
+  | "DIR_MISSING"
+  | "PI_NOT_FOUND"
+  | "WIN_PI_CMD_ONLY"
+  | "WT_MISSING"
+  | "TMUX_MISSING"
+  | "PI_CRASHED"
+  | "SPAWN_ERRNO"
+  | "PREFLIGHT_FAILED"
+  | "REGISTER_TIMEOUT";
+
+/**
+ * A single reason from the synchronous spawn preflight check.
+ * See change: spawn-failure-diagnostics.
+ */
+export interface PreflightReason {
+  code: string;
+  message: string;
 }
 
 /**
@@ -140,6 +197,37 @@ export interface SpawnErrorMessage {
   message: string;
   /** Up to ~2 KB tail of stderr captured from the failed child, if any. */
   stderr?: string;
+  /** Structured failure classifier. Additive — old clients ignore this field. See change: spawn-failure-diagnostics. */
+  code?: SpawnFailureCode;
+  /** Preflight failure reasons. Only set when code === "PREFLIGHT_FAILED". See change: spawn-failure-diagnostics. */
+  reasons?: PreflightReason[];
+}
+
+/**
+ * Emitted when a spawned pi session never sends `session_register` within
+ * the configured `spawnRegisterTimeoutMs` window.
+ * See change: spawn-failure-diagnostics.
+ */
+export interface SpawnRegisterTimeoutMessage {
+  type: "spawn_register_timeout";
+  cwd: string;
+  /** Present for headless spawns; absent for tmux/wt/wsl-tmux. */
+  pid?: number;
+  /** Last 4 KB of the per-session stderr log, if available. */
+  stderrTail?: string;
+  /** The effective watchdog timeout in ms — so the UI can render e.g. "30s". See change: spawn-failure-diagnostics (fix W2). */
+  timeoutMs?: number;
+}
+
+/**
+ * Emitted when pi finally registers AFTER the watchdog already fired.
+ * The UI uses it to auto-clear the timeout banner for the given cwd.
+ * See change: spawn-failure-diagnostics.
+ */
+export interface SpawnRegisterRecoveredMessage {
+  type: "spawn_register_recovered";
+  cwd: string;
+  pid?: number;
 }
 
 export interface SessionsReorderedMessage {
@@ -148,6 +236,28 @@ export interface SessionsReorderedMessage {
   sessionIds: string[];
 }
 
+/**
+ * Atomic on-connect snapshot of the server's full session registry and
+ * per-cwd ordering. Replaces the legacy per-session `session_added` loop
+ * + per-cwd `sessions_reordered` loop that the gateway used to emit on
+ * each browser WS connect. Client SHALL replace its `sessions` Map and
+ * `sessionOrderMap` with this payload (no merging) so stale ids from a
+ * previous server lifetime are dropped atomically.
+ *
+ * Live updates after the snapshot continue using the incremental
+ * `session_added` / `session_updated` / `session_removed` /
+ * `sessions_reordered` messages.
+ *
+ * See change: fix-stale-sessions-on-reconnect.
+ */
+export interface SessionsSnapshotMessage {
+  type: "sessions_snapshot";
+  /** Every session known to the server at construction time, alive AND ended. */
+  sessions: DashboardSession[];
+  /** cwd → ordered session ids. Only non-empty arrays are included. */
+  orders: Record<string, string[]>;
+}
+
 export interface PinnedDirsUpdatedMessage {
   type: "pinned_dirs_updated";
   paths: string[];
@@ -362,6 +472,23 @@ export interface BrowserExtUiDecoratorMessage {
   removed?: boolean;
 }
 
+/**
+ * Server → browser: register a base64-encoded image asset under a content
+ * hash for the given session. Forwarded verbatim from the bridge's
+ * `asset_register` message and replayed to reconnecting browsers (in
+ * chronological position relative to its referencing `message_update` /
+ * `message_end`). The client populates a per-session `Map<hash,{data,mime}>`
+ * consumed by the `MarkdownContent` `pi-asset:` resolver.
+ * See change: chat-markdown-local-images-and-math.
+ */
+export interface BrowserAssetRegisterMessage {
+  type: "asset_register";
+  sessionId: string;
+  hash: string;
+  mimeType: string;
+  data: string;
+}
+
 /** Sent when a plugin's config changes; carries only that plugin's namespace. */
 export interface PluginConfigUpdateMessage {
   type: "plugin_config_update";
@@ -392,7 +519,10 @@ export type ServerToBrowserMessage =
   | ResumeResultBrowserMessage
   | SpawnResultBrowserMessage
   | SpawnErrorMessage
+  | SpawnRegisterTimeoutMessage
+  | SpawnRegisterRecoveredMessage
   | SessionsReorderedMessage
+  | SessionsSnapshotMessage
   | PinnedDirsUpdatedMessage
   | TerminalAddedMessage
   | TerminalRemovedMessage
@@ -416,7 +546,8 @@ export type ServerToBrowserMessage =
   | BootstrapTicketCompleteMessage
   | BrowserUiModulesListMessage
   | BrowserUiDataListMessage
-  | BrowserExtUiDecoratorMessage;
+  | BrowserExtUiDecoratorMessage
+  | BrowserAssetRegisterMessage;
 
 // ── Browser → Server ────────────────────────────────────────────────
 
@@ -476,6 +607,15 @@ export interface RequestModelsBrowserMessage {
   sessionId: string;
 }
 
+/**
+ * Browser asks the server to forward `request_providers` to the bridge.
+ * See change: replace-hardcoded-provider-lists.
+ */
+export interface RequestProvidersBrowserMessage {
+  type: "request_providers";
+  sessionId: string;
+}
+
 export interface SetThinkingLevelBrowserMessage {
   type: "set_thinking_level";
   sessionId: string;
@@ -555,6 +695,12 @@ export interface ResumeSessionBrowserMessage {
   mode: "continue" | "fork";
   /** When forking, optionally fork from a specific session entry instead of the latest */
   entryId?: string;
+  /**
+   * Client-minted UUIDv4 used to correlate `resume_result` and (for fork mode)
+   * the eventual `session_added` for the new session. Optional for back-compat.
+   * See change: spawn-correlation-token.
+   */
+  requestId?: string;
   /**
    * Placement intent for the resumed session in the cwd's sessionOrder:
    *   - "front" (default): move to top of alive tier (Resume button, REST,
@@ -589,6 +735,13 @@ export interface SpawnSessionBrowserMessage {
    * add-folder-task-checker-and-spawn-attach.
    */
   attachProposal?: string;
+  /**
+   * Client-minted UUIDv4 used to correlate `spawn_result` and the eventual
+   * `session_added` (which echoes it as `spawnRequestId`). Optional for
+   * back-compat with older clients.
+   * See change: spawn-correlation-token.
+   */
+  requestId?: string;
 }
 
 export interface AttachProposalBrowserMessage {
@@ -769,6 +922,7 @@ export type BrowserToServerMessage =
   | OpenSpecRefreshBrowserMessage
   | RenameSessionBrowserMessage
   | RequestModelsBrowserMessage
+  | RequestProvidersBrowserMessage
   | SetThinkingLevelBrowserMessage
   | SetModelBrowserMessage
   | ShutdownBrowserMessage

package/packages/shared/src/changelog-types.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared types for the pi changelog display feature.
+ *
+ * Server parses `CHANGELOG.md` files installed alongside core packages
+ * and the client renders the result via `WhatsNewDialog`. These types
+ * are the wire contract between the two halves.
+ *
+ * See change: pi-update-whats-new-panel.
+ */
+
+/**
+ * One bullet point under a release section. Preserves the original
+ * markdown prose verbatim so issue/PR links and inline code formatting
+ * survive intact for the client renderer.
+ */
+export interface ChangelogBullet {
+  /**
+   * Original markdown text of the bullet, with the leading `- `
+   * removed and any continuation lines joined with `\n`. Inline
+   * markdown (links, code spans, emphasis) is preserved exactly as
+   * written so the client can hand it to a markdown renderer.
+   */
+  text: string;
+  /**
+   * Issue / PR references mined from the prose via the canonical
+   * `([#NNN](URL))` pattern pi uses at end-of-bullet. May be empty
+   * when no such pattern is found. Order matches occurrence order.
+   * The `text` field still contains the link in its original form.
+   */
+  issues: { num: number; url: string }[];
+}
+
+/**
+ * One release entry parsed from a Keep-a-Changelog-style markdown
+ * document. Typed sub-section arrays are populated only when the
+ * corresponding H3 heading is present in the source.
+ */
+export interface ChangelogRelease {
+  /**
+   * Version string lifted from the `## [<version>] - <date>` H2
+   * heading. The bracket contents are taken verbatim so versions
+   * like `0.4.3-rc.1` survive.
+   */
+  version: string;
+  /**
+   * Date string lifted from the H2 heading. Set to `null` when the
+   * date token is missing or fails to parse as a YYYY-MM-DD-ish form.
+   * Parser tolerance is intentional — pi has shipped rare entries
+   * with date ranges or missing dates.
+   */
+  date: string | null;
+  /** Bullets under `### Breaking Changes`, in source order. */
+  breaking: ChangelogBullet[];
+  /**
+   * Union of bullets under `### New Features` and `### Added`. Pi
+   * uses both labels at different times for the same concept, so
+   * we merge them. Source order is preserved within each sub-section
+   * and the two sub-sections are concatenated in source order.
+   */
+  features: ChangelogBullet[];
+  /** Bullets under `### Changed`. */
+  changed: ChangelogBullet[];
+  /** Bullets under `### Fixed`. */
+  fixed: ChangelogBullet[];
+  /**
+   * Full markdown text from the release's H2 line up to (but not
+   * including) the next H2 line. Retained as a fallback render path
+   * when the typed arrays don't capture the content (e.g. an
+   * unrecognized H3 heading).
+   */
+  raw: string;
+}
+
+/**
+ * Response shape for `GET /api/pi-core/changelog`. Always wraps the
+ * filtered release list in this envelope so the client gets the
+ * derived `hasBreaking` flag and the GitHub link in one round-trip.
+ */
+export interface ChangelogResponse {
+  /** Package the changelog was parsed for. */
+  pkg: string;
+  /**
+   * Lower bound of the version range, EXCLUSIVE. Echoes the request
+   * query param. Releases at or below this version are filtered out.
+   */
+  from: string;
+  /**
+   * Upper bound of the version range, INCLUSIVE. Echoes the request
+   * query param. Releases above this version are filtered out.
+   */
+  to: string;
+  /**
+   * Filtered release list, ordered with the latest version FIRST.
+   * Empty when no releases exist in `(from, to]` or when the
+   * CHANGELOG could not be located.
+   */
+  releases: ChangelogRelease[];
+  /**
+   * Convenience flag derived from `releases.some(r => r.breaking.length > 0)`.
+   * Lets the client render the warning icon without re-walking the array.
+   */
+  hasBreaking: boolean;
+  /**
+   * Public URL to the full CHANGELOG on GitHub, derived from the
+   * package's `repository` field. `null` when the repository is not
+   * GitHub-hosted or is unparseable.
+   */
+  changelogUrl: string | null;
+  /** ISO timestamp at which the parser produced this response. */
+  parsedAt: string;
+}

package/packages/shared/src/config.ts

@@ -159,6 +159,12 @@ export interface DashboardConfig {
   reattachPlacement: ReattachPlacement;
   /** Persisted list of known remote servers */
   knownServers: KnownServer[];
+  /**
+   * How long (ms) to wait for a spawned pi session to send `session_register`
+   * before emitting a timeout warning. Default 30000 (30s). Clamped [5000, 120000].
+   * See change: spawn-failure-diagnostics.
+   */
+  spawnRegisterTimeoutMs: number;
   /**
    * Per-plugin config namespaces. Reserved top-level key.
    * Each plugin's config lives at plugins.<id>.*
@@ -178,6 +184,13 @@ const VALID_SPAWN_STRATEGIES: SpawnStrategy[] = ["tmux", "headless"];
 /** Default ask_user prompt timeout: 300 seconds (5 minutes). */
 export const DEFAULT_ASK_USER_PROMPT_TIMEOUT_SECONDS = 300;
 
+/** Default + clamp for spawnRegisterTimeoutMs. See change: spawn-failure-diagnostics. */
+export const DEFAULT_SPAWN_REGISTER_TIMEOUT_MS = 30000;
+export function clampSpawnRegisterTimeoutMs(v: unknown): number {
+  if (typeof v !== "number" || isNaN(v)) return DEFAULT_SPAWN_REGISTER_TIMEOUT_MS;
+  return Math.max(5000, Math.min(120000, v));
+}
+
 const DEFAULTS: DashboardConfig = {
   plugins: {},
   port: 8000,
@@ -199,6 +212,7 @@ const DEFAULTS: DashboardConfig = {
   knownServers: [],
   askUserPromptTimeoutSeconds: DEFAULT_ASK_USER_PROMPT_TIMEOUT_SECONDS,
   reattachPlacement: DEFAULT_REATTACH_PLACEMENT,
+  spawnRegisterTimeoutMs: 30000,
 };
 
 /**
@@ -399,6 +413,7 @@ export function loadConfig(): DashboardConfig {
       askUserPromptTimeoutSeconds: typeof parsed.askUserPromptTimeoutSeconds === "number"
         ? parsed.askUserPromptTimeoutSeconds
         : defaults.askUserPromptTimeoutSeconds,
+      spawnRegisterTimeoutMs: clampSpawnRegisterTimeoutMs(parsed.spawnRegisterTimeoutMs),
     };
 
     // Compute resolvedTrustedNetworks: merge trustedNetworks + auth.bypassHosts

package/packages/shared/src/dashboard-starter.ts

@@ -0,0 +1,33 @@
+/**
+ * DashboardStarter — identifies who launched the dashboard server process.
+ *
+ * "Bridge"     — spawned by the pi bridge extension (server-launcher.ts).
+ * "Standalone" — invoked directly via CLI (`pi-dashboard` or `pi-dashboard start`).
+ * "Electron"   — spawned by the Electron main process.
+ *
+ * The value is injected via the DASHBOARD_STARTER env var at spawn time.
+ * When unset or empty the default is "Standalone" (direct CLI invocation).
+ */
+
+export type DashboardStarter = "Bridge" | "Standalone" | "Electron";
+
+const VALID: ReadonlySet<string> = new Set<DashboardStarter>(["Bridge", "Standalone", "Electron"]);
+
+/**
+ * Parse `env.DASHBOARD_STARTER` into a `DashboardStarter`.
+ *
+ * - Unset or empty → `"Standalone"` (direct CLI invocation default).
+ * - Valid value    → that value.
+ * - Invalid value  → logs `console.warn`, returns `"Standalone"`.
+ */
+export function parseDashboardStarter(
+  env: Record<string, string | undefined>,
+): DashboardStarter {
+  const raw = env["DASHBOARD_STARTER"];
+  if (!raw) return "Standalone";
+  if (VALID.has(raw)) return raw as DashboardStarter;
+  console.warn(
+    `[dashboard-starter] Unknown DASHBOARD_STARTER value "${raw}"; defaulting to "Standalone".`,
+  );
+  return "Standalone";
+}