@blackbelt-technology/pi-agent-dashboard 0.2.0

package/packages/extension/src/connection.ts

@@ -0,0 +1,204 @@
+/**
+ * WebSocket connection manager with exponential backoff reconnection
+ * and message buffering during disconnection.
+ */
+
+export interface ConnectionManagerOptions {
+  url: string;
+  WebSocketImpl?: any;
+  maxBufferSize?: number;
+  /** Server liveness watchdog: force reconnect after this many ms without any received message. Default 60000. Set 0 to disable. */
+  watchdogTimeout?: number;
+  onMessage?: (data: unknown) => void;
+  onReconnect?: () => void;
+}
+
+export class ConnectionManager {
+  private url: string;
+  private WS: any;
+  private ws: any | null = null;
+  private buffer: string[] = [];
+  private maxBufferSize: number;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private backoff = 0;
+  private intentionalClose = false;
+  private hasConnectedBefore = false;
+  private onMessage?: (data: unknown) => void;
+  private onReconnect?: () => void;
+
+  private static readonly INITIAL_BACKOFF = 1000;
+  private static readonly MAX_BACKOFF = 30000;
+  private static readonly WATCHDOG_CHECK_INTERVAL = 15_000;
+  private static readonly DEFAULT_WATCHDOG_TIMEOUT = 60_000;
+
+  private lastMessageAt = 0;
+  private watchdogTimer: ReturnType<typeof setInterval> | null = null;
+  private watchdogTimeout: number;
+
+  constructor(options: ConnectionManagerOptions) {
+    this.url = options.url;
+    this.WS = options.WebSocketImpl ?? (globalThis as any).WebSocket;
+    this.maxBufferSize = options.maxBufferSize ?? 10000;
+    this.watchdogTimeout = options.watchdogTimeout ?? ConnectionManager.DEFAULT_WATCHDOG_TIMEOUT;
+    this.onMessage = options.onMessage;
+    this.onReconnect = options.onReconnect;
+  }
+
+  connect(): void {
+    this.intentionalClose = false;
+    this.createConnection();
+    this.startWatchdog();
+  }
+
+  disconnect(): void {
+    this.intentionalClose = true;
+    this.stopWatchdog();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.onclose = null;
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  send(message: unknown): void {
+    const data = JSON.stringify(message);
+
+    if (this.ws?.readyState === 1) {
+      try {
+        this.ws.send(data);
+      } catch {
+        // Connection died between readyState check and send — buffer instead
+        this.bufferMessage(data);
+      }
+    } else {
+      this.bufferMessage(data);
+    }
+  }
+
+  private bufferMessage(data: string): void {
+    this.buffer.push(data);
+    if (this.buffer.length > this.maxBufferSize) {
+      this.buffer.shift();
+    }
+  }
+
+  get isConnected(): boolean {
+    return this.ws?.readyState === 1;
+  }
+
+  /**
+   * Update the WebSocket URL and reconnect.
+   * Used when mDNS discovers the server on a different address/port.
+   */
+  updateUrl(newUrl: string): void {
+    if (newUrl === this.url) return;
+    this.url = newUrl;
+    // Force reconnect to new URL
+    if (this.ws) {
+      this.handleDisconnect();
+    }
+  }
+
+  private createConnection(): void {
+    try {
+      this.ws = new this.WS(this.url);
+    } catch {
+      // Constructor failed — schedule reconnect
+      this.ws = null;
+      if (!this.intentionalClose) {
+        this.scheduleReconnect();
+      }
+      return;
+    }
+
+    this.ws.onopen = () => {
+      // Reset backoff on successful connection
+      this.backoff = 0;
+      this.lastMessageAt = Date.now();
+
+      // Notify reconnect if this isn't the first connection
+      if (this.hasConnectedBefore) {
+        this.onReconnect?.();
+      }
+      this.hasConnectedBefore = true;
+
+      // Flush buffer
+      const buffered = [...this.buffer];
+      this.buffer = [];
+      for (const data of buffered) {
+        this.ws?.send(data);
+      }
+    };
+
+    this.ws.onmessage = (ev: { data: string }) => {
+      this.lastMessageAt = Date.now();
+      try {
+        const parsed = JSON.parse(ev.data);
+        this.onMessage?.(parsed);
+      } catch {
+        // Ignore malformed messages
+      }
+    };
+
+    this.ws.onclose = () => {
+      this.handleDisconnect();
+    };
+
+    this.ws.onerror = () => {
+      // Node 22's built-in WebSocket may fire onerror WITHOUT onclose
+      // on connection failure. Handle once and prevent re-entrant calls
+      // (ws.close() can re-trigger onerror synchronously).
+      this.handleDisconnect();
+    };
+  }
+
+  private handleDisconnect(): void {
+    if (!this.ws) return; // Already handled — idempotent guard
+    const ws = this.ws;
+    this.ws = null;
+    // Detach handlers to prevent re-entrant calls from ws.close()
+    ws.onclose = null;
+    ws.onerror = null;
+    ws.onopen = null;
+    ws.onmessage = null;
+    try { ws.close(); } catch { /* ignore — may already be closed */ }
+    if (!this.intentionalClose) {
+      this.scheduleReconnect();
+    }
+  }
+
+  private startWatchdog(): void {
+    this.stopWatchdog();
+    if (this.watchdogTimeout <= 0) return;
+    this.watchdogTimer = setInterval(() => {
+      if (this.ws && this.lastMessageAt > 0 && Date.now() - this.lastMessageAt >= this.watchdogTimeout) {
+        // Server has gone silent — force close to trigger reconnect
+        this.handleDisconnect();
+      }
+    }, ConnectionManager.WATCHDOG_CHECK_INTERVAL);
+  }
+
+  private stopWatchdog(): void {
+    if (this.watchdogTimer) {
+      clearInterval(this.watchdogTimer);
+      this.watchdogTimer = null;
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.backoff === 0) {
+      this.backoff = ConnectionManager.INITIAL_BACKOFF;
+    } else {
+      this.backoff = Math.min(this.backoff * 2, ConnectionManager.MAX_BACKOFF);
+    }
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.createConnection();
+    }, this.backoff);
+  }
+}

package/packages/extension/src/dev-build.ts

@@ -0,0 +1,39 @@
+/**
+ * Dev build-on-reload helper.
+ * Builds the Vite client and requests server shutdown.
+ */
+import { execSync as defaultExecSync } from "node:child_process";
+
+export interface DevBuildOptions {
+  packageRoot: string;
+  serverPort: number;
+  /** @internal for testing */
+  _execSync?: typeof defaultExecSync;
+  /** @internal for testing */
+  _fetch?: typeof fetch;
+}
+
+/**
+ * Run the dev build and shutdown sequence.
+ * Errors are caught and logged — never throws.
+ */
+export function runDevBuild(opts: DevBuildOptions): void {
+  const execSyncFn = opts._execSync ?? defaultExecSync;
+  const fetchFn = opts._fetch ?? fetch;
+
+  try {
+    console.log("🔨 Dashboard: building client...");
+    execSyncFn("npm run build", { cwd: opts.packageRoot, stdio: "inherit" });
+    console.log("✅ Dashboard: client built");
+  } catch (err: any) {
+    console.log(`❌ Dashboard: build failed — ${err.message}`);
+  }
+
+  try {
+    console.log("🛑 Dashboard: stopping server...");
+    fetchFn(`http://localhost:${opts.serverPort}/api/shutdown`, { method: "POST" }).catch(() => {});
+    console.log("✅ Dashboard: server stopped");
+  } catch {
+    // Server may not be running — that's fine
+  }
+}

package/packages/extension/src/event-forwarder.ts

@@ -0,0 +1,40 @@
+import type { EventForwardMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
+
+/**
+ * Extract only JSON-serializable fields from an event object.
+ * Strips functions, AbortSignals, and other non-serializable values.
+ */
+function extractSerializable(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === undefined || value === null) {
+      result[key] = value;
+      continue;
+    }
+    if (typeof value === "function") continue;
+    if (value instanceof AbortSignal) continue;
+    if (typeof value === "object" && "aborted" in (value as object)) continue;
+    result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Map a pi event object to an event_forward protocol message.
+ */
+export function mapEventToProtocol(
+  sessionId: string,
+  piEvent: Record<string, unknown>,
+): EventForwardMessage {
+  const serializable = extractSerializable(piEvent);
+
+  return {
+    type: "event_forward",
+    sessionId,
+    event: {
+      eventType: (piEvent.type as string) ?? "unknown",
+      timestamp: Date.now(),
+      data: serializable,
+    },
+  };
+}

package/packages/extension/src/flow-event-wiring.ts

@@ -0,0 +1,102 @@
+/**
+ * Flow event wiring: registers listeners for pi-flows events
+ * and forwards them as protocol messages to the dashboard server.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { BridgeContext } from "./bridge-context.js";
+import { filterHiddenCommands } from "./bridge-context.js";
+import type { FlowInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+/** Map of pi-flows event names to dashboard protocol event types */
+export const FLOW_EVENT_MAP: Record<string, string> = {
+  "flow:flow-started": "flow_started",
+  "flow:agent-started": "flow_agent_started",
+  "flow:agent-complete": "flow_agent_complete",
+  "flow:subagent-tool-call": "flow_tool_call",
+  "flow:subagent-tool-result": "flow_tool_result",
+  "flow:assistant-text": "flow_assistant_text",
+  "flow:thinking-text": "flow_thinking_text",
+  "flow:loop-iteration": "flow_loop_iteration",
+  "flow:auto-decision": "flow_auto_decision",
+  "flow:complete": "flow_complete",
+  "flow:summary-started": "flow_summary_started",
+  "flow:summary-ready": "flow_summary_ready",
+  "flow:summary-dismissed": "flow_summary_dismissed",
+  // Architect lifecycle events
+  "flow:architect-started": "architect_started",
+  "flow:architect-tool-call": "architect_tool_call",
+  "flow:architect-tool-result": "architect_tool_result",
+  "flow:architect-text": "architect_text",
+  "flow:architect-preview": "architect_preview",
+  "flow:architect-complete": "architect_complete",
+  "flow:architect-replan": "architect_replan",
+  "flow:architect-cancelled": "architect_cancelled",
+  "flow:architect-saved": "architect_saved",
+  "flow:architect-error": "architect_error",
+  "flow:architect-context-generating": "architect_context_generating",
+  "flow:architect-context-ready": "architect_context_ready",
+  "flow:architect-run-handoff": "architect_run_handoff",
+};
+
+/** Map of pi-subagents event names to dashboard protocol event types */
+export const SUBAGENT_EVENT_MAP: Record<string, string> = {
+  "subagents:created": "subagent_created",
+  "subagents:started": "subagent_started",
+  "subagents:completed": "subagent_completed",
+  "subagents:failed": "subagent_failed",
+};
+
+/**
+ * Register flow event listeners on pi.events.
+ * Must be called after session_start when pi.events is available.
+ *
+ * @param bc - Bridge context (mutable state)
+ * @param isSessionReady - Function that returns whether session is ready
+ * @param getFlowsList - Function to get current flows list
+ */
+export function registerFlowEventListeners(
+  bc: BridgeContext,
+  isSessionReady: () => boolean,
+  getFlowsList: () => FlowInfo[],
+): void {
+  const { pi, connection } = bc;
+  if (!pi.events) return;
+
+  // Re-send commands and flows list when pi-flows discovers new flows or completes
+  const resendCommandsAndFlows = () => {
+    if (!isSessionReady()) return;
+    const commands = filterHiddenCommands(pi.getCommands());
+    connection.send({ type: "commands_list", sessionId: bc.sessionId, commands });
+    const flows = getFlowsList();
+    connection.send({ type: "flows_list", sessionId: bc.sessionId, flows });
+  };
+  pi.events.on("flow:rediscover", resendCommandsAndFlows);
+  pi.events.on("flow:complete", resendCommandsAndFlows);
+
+  // Note: event_forward sending for flow and subagent events is handled by
+  // the EventBus emit intercept in bridge.ts (catch-all forwarding).
+
+  // Forward architect prompt requests directly to the dashboard widget bar.
+  // Non-architect prompts still go through ui-proxy (flow-tui -> ctx.ui.select -> extension_ui_request).
+  // Both paths race -- first response wins via emitPromptAndAwait's resolved guard.
+  pi.events.on("flow:prompt-request", (data: unknown) => {
+    if (!isSessionReady()) return;
+    const req = data as { id?: string; pipeline?: string; type?: string; question?: string; options?: string[]; defaultValue?: string };
+    if (!req.id || !req.pipeline?.startsWith("architect-")) return;
+    connection.send({
+      type: "event_forward",
+      sessionId: bc.sessionId,
+      event: {
+        eventType: "architect_prompt_request",
+        timestamp: Date.now(),
+        data: {
+          id: req.id,
+          promptType: req.type,
+          question: req.question,
+          options: req.options,
+          defaultValue: req.defaultValue,
+        },
+      },
+    });
+  });
+}

package/packages/extension/src/git-info.ts

@@ -0,0 +1,65 @@
+/**
+ * Git info gathering — detects branch, remote URL, and PR number.
+ */
+import { execSync } from "node:child_process";
+import { buildGitLinks, type GitLinks } from "./git-link-builder.js";
+
+export interface GitInfo {
+  gitBranch: string;
+  gitBranchUrl?: string;
+  gitPrNumber?: number;
+  gitPrUrl?: string;
+}
+
+/** Run a shell command and return trimmed stdout, or undefined on failure. */
+function runGit(command: string, cwd: string): string | undefined {
+  try {
+    return execSync(command, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 5000 }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Detect the current git branch. Returns short SHA for detached HEAD. */
+export function detectBranch(cwd: string): string | undefined {
+  const ref = runGit("git rev-parse --abbrev-ref HEAD", cwd);
+  if (!ref) return undefined;
+  if (ref === "HEAD") {
+    // Detached HEAD — return short commit SHA
+    return runGit("git rev-parse --short HEAD", cwd) ?? "HEAD";
+  }
+  return ref;
+}
+
+/** Detect the remote origin URL. */
+export function detectRemoteUrl(cwd: string): string | undefined {
+  return runGit("git remote get-url origin", cwd);
+}
+
+/** Detect the PR number via gh CLI (best effort). */
+export function detectPrNumber(cwd: string): number | undefined {
+  const result = runGit("gh pr view --json number -q .number", cwd);
+  if (result) {
+    const num = parseInt(result, 10);
+    if (!isNaN(num)) return num;
+  }
+  return undefined;
+}
+
+/** Gather all git info for a directory. Returns undefined if not a git repo. */
+export function gatherGitInfo(cwd: string): GitInfo | undefined {
+  const branch = detectBranch(cwd);
+  if (!branch) return undefined;
+
+  const remoteUrl = detectRemoteUrl(cwd);
+  const prNumber = detectPrNumber(cwd);
+
+  const links: GitLinks = remoteUrl ? buildGitLinks(remoteUrl, branch, prNumber) : {};
+
+  return {
+    gitBranch: branch,
+    gitBranchUrl: links.branchUrl,
+    gitPrNumber: prNumber,
+    gitPrUrl: links.prUrl,
+  };
+}

package/packages/extension/src/git-link-builder.ts

@@ -0,0 +1,112 @@
+/**
+ * Git link builder — parses remote URLs and builds platform-specific links.
+ */
+
+export interface GitLinks {
+  branchUrl?: string;
+  prUrl?: string;
+}
+
+export interface ParsedRemote {
+  host: string;
+  user: string;
+  repo: string;
+}
+
+type Platform = "github" | "gitlab" | "bitbucket" | "gitea" | "codeberg" | "sourcehut";
+
+const HOST_TO_PLATFORM: Record<string, Platform> = {
+  "github.com": "github",
+  "gitlab.com": "gitlab",
+  "bitbucket.org": "bitbucket",
+  "gitea.com": "gitea",
+  "codeberg.org": "codeberg",
+  "sr.ht": "sourcehut",
+};
+
+/** Parse an SSH or HTTPS remote URL into host/user/repo. */
+export function parseRemoteUrl(url: string): ParsedRemote | undefined {
+  // SSH: git@host:user/repo.git
+  const sshMatch = url.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
+  if (sshMatch) {
+    const [, host, path] = sshMatch;
+    const parts = path!.split("/");
+    if (parts.length >= 2) {
+      return { host: host!, user: parts.slice(0, -1).join("/"), repo: parts[parts.length - 1]! };
+    }
+  }
+
+  // HTTPS: https://host/user/repo.git
+  const httpsMatch = url.match(/^https?:\/\/([^/]+)\/(.+?)(?:\.git)?$/);
+  if (httpsMatch) {
+    const [, host, path] = httpsMatch;
+    const parts = path!.split("/");
+    if (parts.length >= 2) {
+      return { host: host!, user: parts.slice(0, -1).join("/"), repo: parts[parts.length - 1]! };
+    }
+  }
+
+  return undefined;
+}
+
+/** Detect the hosting platform from a hostname. */
+export function detectPlatform(host: string): Platform | undefined {
+  return HOST_TO_PLATFORM[host];
+}
+
+/** Build branch and PR URLs for a given platform. */
+export function buildGitLinks(remoteUrl: string, branch: string, prNumber?: number): GitLinks {
+  const parsed = parseRemoteUrl(remoteUrl);
+  if (!parsed) return {};
+
+  const platform = detectPlatform(parsed.host);
+  if (!platform) return {};
+
+  const baseUrl = `https://${parsed.host}/${parsed.user}/${parsed.repo}`;
+  const encodedBranch = encodeURIComponent(branch);
+
+  const links: GitLinks = {};
+
+  // Don't generate branch URL for detached HEAD
+  if (branch !== "HEAD") {
+    switch (platform) {
+      case "github":
+      case "sourcehut":
+        links.branchUrl = `${baseUrl}/tree/${encodedBranch}`;
+        break;
+      case "gitlab":
+        links.branchUrl = `${baseUrl}/-/tree/${encodedBranch}`;
+        break;
+      case "bitbucket":
+        links.branchUrl = `${baseUrl}/src/${encodedBranch}`;
+        break;
+      case "gitea":
+      case "codeberg":
+        links.branchUrl = `${baseUrl}/src/branch/${encodedBranch}`;
+        break;
+    }
+  }
+
+  if (prNumber !== undefined) {
+    switch (platform) {
+      case "github":
+        links.prUrl = `${baseUrl}/pull/${prNumber}`;
+        break;
+      case "gitlab":
+        links.prUrl = `${baseUrl}/-/merge_requests/${prNumber}`;
+        break;
+      case "bitbucket":
+        links.prUrl = `${baseUrl}/pull-requests/${prNumber}`;
+        break;
+      case "gitea":
+      case "codeberg":
+        links.prUrl = `${baseUrl}/pulls/${prNumber}`;
+        break;
+      case "sourcehut":
+        links.prUrl = `${baseUrl}/patches/${prNumber}`;
+        break;
+    }
+  }
+
+  return links;
+}

package/packages/extension/src/model-tracker.ts

@@ -0,0 +1,56 @@
+/**
+ * Model and thinking-level change detection.
+ * Sends model_update only when values actually change.
+ */
+import type { BridgeContext } from "./bridge-context.js";
+import { getCurrentModelString } from "./bridge-context.js";
+import { gatherGitInfo } from "./git-info.js";
+
+/**
+ * Send model_update if model or thinking level has changed since last send.
+ */
+export function sendModelUpdateIfChanged(bc: BridgeContext): void {
+  const model = getCurrentModelString(bc);
+  const thinkingLevel = (bc.pi as any).getThinkingLevel?.() ?? undefined;
+  if (model === bc.lastModel && thinkingLevel === bc.lastThinkingLevel) return;
+  bc.lastModel = model;
+  bc.lastThinkingLevel = thinkingLevel;
+  if (model) {
+    bc.connection.send({
+      type: "model_update",
+      sessionId: bc.sessionId,
+      model,
+      thinkingLevel,
+    });
+  }
+}
+
+/**
+ * Send session_name_update if name has changed since last send.
+ */
+export function sendSessionNameIfChanged(bc: BridgeContext): void {
+  const name = bc.pi.getSessionName() ?? "";
+  if (name === bc.lastSessionName) return;
+  bc.lastSessionName = name;
+  bc.connection.send({
+    type: "session_name_update",
+    sessionId: bc.sessionId,
+    name,
+  });
+}
+
+/**
+ * Send git_info_update if branch or PR has changed since last send.
+ */
+export function sendGitInfoIfChanged(bc: BridgeContext, cwd: string): void {
+  const info = gatherGitInfo(cwd);
+  if (!info) return;
+  if (info.gitBranch === bc.lastGitBranch && info.gitPrNumber === bc.lastGitPrNumber) return;
+  bc.lastGitBranch = info.gitBranch;
+  bc.lastGitPrNumber = info.gitPrNumber;
+  bc.connection.send({
+    type: "git_info_update",
+    sessionId: bc.sessionId,
+    ...info,
+  });
+}

package/packages/extension/src/pi-env.d.ts

@@ -0,0 +1,23 @@
+// Ambient declarations for pi runtime packages.
+// The actual types are provided by whichever host (pi or OMP) loads this extension.
+// tsconfig paths handles resolution when one of the packages is installed;
+// these declarations serve as fallback when neither is available (e.g. CI, dev without pi).
+declare module "@mariozechner/pi-coding-agent" {
+  export type ExtensionAPI = import("@oh-my-pi/pi-coding-agent").ExtensionAPI;
+}
+declare module "@oh-my-pi/pi-coding-agent" {
+  export interface ModelRegistry {
+    getAvailable(): Array<{ provider: string; id: string }>;
+    refresh(): void;
+  }
+
+  export interface ExtensionAPI {
+    on(event: string, handler: (...args: any[]) => any): void;
+    getCommands(): any[];
+    sendUserMessage(message: string | any[]): void;
+    setSessionName(name: string): void;
+    getSessionName(): string | undefined;
+    registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: any) => Promise<void> }): void;
+    exec(command: string, args: string[], options?: { timeout?: number }): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+  }
+}