@blackbelt-technology/pi-agent-dashboard 0.2.0 → 0.2.2

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

@@ -5,12 +5,22 @@
 declare module "@mariozechner/pi-coding-agent" {
   export type ExtensionAPI = import("@oh-my-pi/pi-coding-agent").ExtensionAPI;
 }
+declare module "@mariozechner/pi-ai" {
+  export function StringEnum<T extends readonly string[]>(values: T, schema?: Record<string, unknown>): any;
+}
+
 declare module "@oh-my-pi/pi-coding-agent" {
   export interface ModelRegistry {
     getAvailable(): Array<{ provider: string; id: string }>;
     refresh(): void;
   }
 
+  export interface EventBus {
+    on(event: string, handler: (...args: any[]) => any): void;
+    off(event: string, handler: (...args: any[]) => any): void;
+    emit(event: string, ...args: any[]): void;
+  }
+
   export interface ExtensionAPI {
     on(event: string, handler: (...args: any[]) => any): void;
     getCommands(): any[];
@@ -18,6 +28,9 @@ declare module "@oh-my-pi/pi-coding-agent" {
     setSessionName(name: string): void;
     getSessionName(): string | undefined;
     registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: any) => Promise<void> }): void;
+    registerTool(tool: any): void;
+    registerProvider(name: string, config: any): void;
     exec(command: string, args: string[], options?: { timeout?: number }): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+    events: EventBus;
   }
 }

package/packages/extension/src/prompt-bus.ts

@@ -0,0 +1,240 @@
+/**
+ * PromptBus — Unified prompt routing infrastructure.
+ *
+ * Routes prompt requests to registered adapters (TUI, dashboard, custom).
+ * Enforces first-response-wins semantics and cross-adapter dismissal.
+ * Replaces the ui-proxy race pattern and emitPromptAndAwait event system.
+ */
+
+// ── Interfaces ──────────────────────────────────────────────────────
+
+export interface PromptComponent {
+  /** Component type identifier — maps to a React component on the client */
+  type: string;
+  /** Serializable props for the component */
+  props: Record<string, unknown>;
+}
+
+export interface PromptClaim {
+  /** Optional custom dashboard UI component. If omitted, adapter handles externally (e.g. TUI). */
+  component?: PromptComponent;
+  /** Where to render the component on the dashboard client */
+  placement?: "widget-bar" | "inline" | "overlay";
+}
+
+export interface PromptRequest {
+  id: string;
+  pipeline: string;
+  type: "select" | "input" | "confirm" | "editor" | "multiselect";
+  question: string;
+  options?: string[];
+  defaultValue?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PromptResponse {
+  id: string;
+  answer?: string;
+  cancelled?: boolean;
+  source: string;
+}
+
+export interface PromptAdapter {
+  name: string;
+  /**
+   * Called when a new prompt arrives.
+   * Return a PromptClaim to participate, or null/undefined to skip.
+   */
+  onRequest(prompt: PromptRequest): PromptClaim | null | undefined | void;
+  /** Called when any adapter answered — dismiss your UI if active. */
+  onResponse(response: PromptResponse): void;
+  /** Called on cancel/timeout — clean up your UI. */
+  onCancel(id: string): void;
+}
+
+// ── Internal types ──────────────────────────────────────────────────
+
+interface PendingPrompt {
+  request: PromptRequest;
+  resolve: (response: PromptResponse) => void;
+  timer: ReturnType<typeof setTimeout>;
+  claims: Array<{ adapter: PromptAdapter; claim: PromptClaim }>;
+  /** Resolved component sent to dashboard at request time (for reconnect replay) */
+  resolvedComponent: PromptComponent | undefined;
+  /** Resolved placement sent to dashboard at request time (for reconnect replay) */
+  resolvedPlacement: string | undefined;
+}
+
+export interface PromptBusOptions {
+  /** Default timeout in milliseconds (default: 5 minutes) */
+  timeoutMs?: number;
+  /** Called when a prompt_request should be sent to the dashboard */
+  onDashboardRequest?: (prompt: PromptRequest, component: PromptComponent, placement: string) => void;
+  /** Called when a prompt_dismiss should be sent to the dashboard */
+  onDashboardDismiss?: (id: string) => void;
+  /** Called when a prompt_cancel should be sent to the dashboard */
+  onDashboardCancel?: (id: string) => void;
+}
+
+// ── PromptBus ───────────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+export class PromptBus {
+  private adapters: PromptAdapter[] = [];
+  private pending = new Map<string, PendingPrompt>();
+  private options: PromptBusOptions;
+
+  constructor(options: PromptBusOptions = {}) {
+    this.options = options;
+  }
+
+  /**
+   * Register an adapter. Returns an unsubscribe function.
+   * Re-registering with the same name replaces the previous adapter.
+   */
+  registerAdapter(adapter: PromptAdapter): () => void {
+    // Replace existing adapter with same name
+    this.adapters = this.adapters.filter(a => a.name !== adapter.name);
+    this.adapters.push(adapter);
+
+    return () => {
+      this.adapters = this.adapters.filter(a => a !== adapter);
+    };
+  }
+
+  /**
+   * Submit a prompt. Returns a promise that resolves when any adapter answers.
+   */
+  request(options: Omit<PromptRequest, "id">): Promise<PromptResponse> {
+    const id = crypto.randomUUID();
+    const request: PromptRequest = { id, ...options };
+
+    return new Promise<PromptResponse>((resolve) => {
+      const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const timer = setTimeout(() => {
+        this.cancel(id);
+      }, timeoutMs);
+
+      // Distribute to all adapters and collect claims
+      const claims: PendingPrompt["claims"] = [];
+      for (const adapter of this.adapters) {
+        try {
+          const claim = adapter.onRequest(request);
+          if (claim) {
+            claims.push({ adapter, claim });
+          }
+        } catch {
+          // Adapter error — skip it
+        }
+      }
+
+      // Resolve dashboard rendering: first adapter with a component wins
+      const componentClaim = claims.find(c => c.claim.component);
+      let resolvedComponent: PromptComponent | undefined;
+      let resolvedPlacement: string | undefined;
+      if (componentClaim) {
+        resolvedComponent = componentClaim.claim.component!;
+        resolvedPlacement = componentClaim.claim.placement ?? "inline";
+      } else if (this.options.onDashboardRequest) {
+        resolvedComponent = {
+          type: "generic-dialog",
+          props: {
+            question: request.question,
+            type: request.type,
+            options: request.options,
+            defaultValue: request.defaultValue,
+          },
+        };
+        resolvedPlacement = "inline";
+      }
+
+      // Store pending state (with resolved component for reconnect replay)
+      this.pending.set(id, { request, resolve, timer, claims, resolvedComponent, resolvedPlacement });
+
+      // Send to dashboard
+      if (resolvedComponent && this.options.onDashboardRequest) {
+        this.options.onDashboardRequest(request, resolvedComponent, resolvedPlacement!);
+      }
+    });
+  }
+
+  /**
+   * An adapter calls this to answer a prompt. First response wins.
+   */
+  respond(response: PromptResponse): void {
+    const entry = this.pending.get(response.id);
+    if (!entry) return; // Already resolved or unknown
+
+    this.pending.delete(response.id);
+    clearTimeout(entry.timer);
+
+    // Notify ALL adapters so they can dismiss their UI
+    for (const adapter of this.adapters) {
+      try {
+        adapter.onResponse(response);
+      } catch {
+        // Adapter error — continue
+      }
+    }
+
+    // Send dismiss to dashboard if a non-dashboard source answered
+    if (this.options.onDashboardDismiss) {
+      this.options.onDashboardDismiss(response.id);
+    }
+
+    entry.resolve(response);
+  }
+
+  /**
+   * Cancel a pending prompt (e.g. on timeout or abort).
+   */
+  cancel(id: string): void {
+    const entry = this.pending.get(id);
+    if (!entry) return;
+
+    this.pending.delete(id);
+    clearTimeout(entry.timer);
+
+    // Notify adapters
+    for (const adapter of this.adapters) {
+      try {
+        adapter.onCancel(id);
+      } catch {
+        // Adapter error — continue
+      }
+    }
+
+    // Notify dashboard
+    if (this.options.onDashboardCancel) {
+      this.options.onDashboardCancel(id);
+    }
+
+    entry.resolve({ id, cancelled: true, source: "__bus__" });
+  }
+
+  /** Get pending requests with their resolved dashboard components (for reconnect replay). */
+  getPendingRequests(): Array<{ request: PromptRequest; component: PromptComponent; placement: string }> {
+    const result: Array<{ request: PromptRequest; component: PromptComponent; placement: string }> = [];
+    for (const entry of this.pending.values()) {
+      if (entry.resolvedComponent && entry.resolvedPlacement) {
+        result.push({
+          request: entry.request,
+          component: entry.resolvedComponent,
+          placement: entry.resolvedPlacement,
+        });
+      }
+    }
+    return result;
+  }
+
+  /** Get the number of pending prompts (for testing/diagnostics). */
+  get pendingCount(): number {
+    return this.pending.size;
+  }
+
+  /** Get registered adapter names (for testing/diagnostics). */
+  get adapterNames(): string[] {
+    return this.adapters.map(a => a.name);
+  }
+}

package/packages/extension/src/server-launcher.ts

@@ -18,10 +18,10 @@ export interface LaunchResult {
 
 /**
  * Resolve the dashboard server CLI script path relative to this extension file.
- * From src/extension/server-launcher.ts → src/server/cli.ts
+ * From packages/extension/src/server-launcher.ts → packages/server/src/cli.ts
  */
 export function resolveServerCliPath(): string {
-  return path.resolve(__dirname, "..", "server", "cli.ts");
+  return path.resolve(__dirname, "..", "..", "server", "src", "cli.ts");
 }
 
 /**

package/packages/extension/src/session-sync.ts

@@ -81,7 +81,8 @@ export function replaySessionEntries(bc: BridgeContext): void {
 }
 
 /**
- * Handle session_switch or session_fork: unregister old, register new, replay, sync.
+ * Handle session change (new/fork/resume): unregister old, register new, replay, sync.
+ * Called from session_start when event.reason indicates a session switch.
  */
 export function handleSessionChange(
   bc: BridgeContext,

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-server",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Dashboard server for monitoring and interacting with pi agent sessions",
   "type": "module",
   "main": "src/cli.ts",

package/packages/server/src/__tests__/bridge-register-nondestructive.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Tests for non-destructive bridge registration cleanup.
+ * Verifies that existing valid extension paths are preserved,
+ * while stale (non-existent) paths are removed.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import { registerBridgeExtension } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
+
+describe("non-destructive bridge registration", () => {
+  let tmpDir: string;
+  let settingsPath: string;
+  let origHome: string | undefined;
+  let fakeExtensionDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "bridge-reg-test-"));
+    settingsPath = path.join(tmpDir, ".pi", "agent", "settings.json");
+    origHome = process.env.HOME;
+    process.env.HOME = tmpDir;
+
+    // Create a fake "existing valid" extension dir that looks like a dev install
+    fakeExtensionDir = path.join(tmpDir, "dev-project", "pi-agent-dashboard", "packages", "extension");
+    fs.mkdirSync(fakeExtensionDir, { recursive: true });
+    fs.writeFileSync(path.join(fakeExtensionDir, "package.json"), '{"name":"test"}');
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function writeSettings(data: Record<string, unknown>) {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2));
+  }
+
+  function readSettings(): Record<string, unknown> {
+    return JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  }
+
+  it("preserves existing valid dashboard extension path", () => {
+    writeSettings({ packages: [fakeExtensionDir] });
+
+    const newPath = path.join(tmpDir, "new-extension");
+    registerBridgeExtension(newPath);
+
+    const settings = readSettings();
+    const packages = settings.packages as string[];
+    expect(packages).toContain(fakeExtensionDir);
+    expect(packages).toContain(newPath);
+  });
+
+  it("removes stale (non-existent) dashboard extension path", () => {
+    const stalePath = "/old/nonexistent/pi-dashboard/extension";
+    writeSettings({ packages: [stalePath, fakeExtensionDir] });
+
+    const newPath = path.join(tmpDir, "new-extension");
+    registerBridgeExtension(newPath);
+
+    const settings = readSettings();
+    const packages = settings.packages as string[];
+    expect(packages).not.toContain(stalePath);
+    expect(packages).toContain(fakeExtensionDir);
+    expect(packages).toContain(newPath);
+  });
+
+  it("does not add duplicate entries", () => {
+    writeSettings({ packages: [fakeExtensionDir] });
+
+    registerBridgeExtension(fakeExtensionDir);
+
+    const settings = readSettings();
+    const packages = settings.packages as string[];
+    const count = packages.filter(p => p === fakeExtensionDir).length;
+    expect(count).toBe(1);
+  });
+
+  it("preserves non-dashboard extension paths", () => {
+    const otherExt = "/some/other/extension";
+    writeSettings({ packages: [otherExt, fakeExtensionDir] });
+
+    const newPath = path.join(tmpDir, "new-extension");
+    registerBridgeExtension(newPath);
+
+    const settings = readSettings();
+    const packages = settings.packages as string[];
+    expect(packages).toContain(otherExt);
+  });
+
+  it("removes path without package.json even if directory exists", () => {
+    const noPkgDir = path.join(tmpDir, "broken-pi-dashboard");
+    fs.mkdirSync(noPkgDir, { recursive: true });
+
+    writeSettings({ packages: [noPkgDir, fakeExtensionDir] });
+
+    const newPath = path.join(tmpDir, "new-extension");
+    registerBridgeExtension(newPath);
+
+    const settings = readSettings();
+    const packages = settings.packages as string[];
+    expect(packages).not.toContain(noPkgDir);
+    expect(packages).toContain(fakeExtensionDir);
+  });
+});

package/packages/server/src/__tests__/extension-register-appimage.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Tests for AppImage guard in findBundledExtension().
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import { findBundledExtension } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
+
+describe("findBundledExtension - AppImage guard", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "appimage-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns extension path for stable install location", () => {
+    const extDir = path.join(tmpDir, "packages", "extension");
+    fs.mkdirSync(extDir, { recursive: true });
+    fs.writeFileSync(path.join(extDir, "package.json"), "{}");
+
+    const result = findBundledExtension(tmpDir);
+    expect(result).toBe(extDir);
+    expect(result).not.toContain("/tmp/.mount_");
+  });
+
+  it("returns null when extension does not exist", () => {
+    expect(findBundledExtension(tmpDir)).toBeNull();
+  });
+
+  // Note: We can't easily test the /tmp/.mount_ guard with real paths
+  // since we'd need to create dirs under /tmp/.mount_PIxxxx.
+  // The guard is verified by code inspection and the shared module tests.
+});

package/packages/server/src/__tests__/extension-register.test.ts

@@ -1,12 +1,14 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+/**
+ * Tests for the shared bridge extension registration (server context).
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 
-// We test the module's exported function
-import { ensureBridgeExtensionRegistered } from "../extension-register.js";
+import { registerBridgeExtension, findBundledExtension } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
 
-describe("ensureBridgeExtensionRegistered", () => {
+describe("bridge extension registration (server context)", () => {
   let tmpDir: string;
   let settingsPath: string;
   let origHome: string | undefined;
@@ -23,39 +25,41 @@ describe("ensureBridgeExtensionRegistered", () => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
-  it("should be a no-op when no bundled extension exists", () => {
-    // In dev mode, the extension directory relative to server/src is the real
-    // packages/extension, but in test context __dirname doesn't point to a bundle.
-    // The function should not crash and should not create settings.json
-    ensureBridgeExtensionRegistered();
-    // No assertion needed — just verify no crash
+  it("findBundledExtension returns null when extension dir does not exist", () => {
+    const result = findBundledExtension(tmpDir);
+    expect(result).toBeNull();
   });
 
-  it("should add extension path to empty settings file", () => {
-    // Create a fake bundled extension at the expected relative path
-    // extension-register.ts resolves __dirname/../../../extension relative to server/src
-    // We can't easily test the real path detection, so we test the settings write logic
-    // by directly calling with a mocked path
+  it("findBundledExtension finds extension under base dir", () => {
+    const extDir = path.join(tmpDir, "packages", "extension");
+    fs.mkdirSync(extDir, { recursive: true });
+    fs.writeFileSync(path.join(extDir, "package.json"), "{}");
+    expect(findBundledExtension(tmpDir)).toBe(extDir);
+  });
 
-    // Create settings dir
+  it("registerBridgeExtension adds extension to empty settings file", () => {
     fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
     fs.writeFileSync(settingsPath, "{}");
 
-    // Since we can't mock __dirname easily, we test the settings logic directly
+    registerBridgeExtension("/test/extension");
     const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
-    expect(settings.packages).toBeUndefined();
+    expect(settings.packages).toContain("/test/extension");
   });
 
   it("should not crash on malformed settings.json", () => {
     fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
     fs.writeFileSync(settingsPath, "not valid json{{{");
-    ensureBridgeExtensionRegistered();
-    // Should not throw
+    // Should not throw — starts fresh
+    registerBridgeExtension("/test/extension");
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    expect(settings.packages).toContain("/test/extension");
   });
 
   it("should not crash when settings directory does not exist", () => {
     // HOME points to tmpDir but .pi/agent/ doesn't exist
-    ensureBridgeExtensionRegistered();
-    // Should not throw
+    registerBridgeExtension("/test/extension");
+    // Should create the directory and write
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    expect(settings.packages).toContain("/test/extension");
   });
 });

package/packages/server/src/__tests__/process-manager.test.ts

@@ -168,7 +168,10 @@ describe("Process Manager", () => {
     it("should not duplicate managed bin if already present", () => {
       const managedBin = require("path").join(require("os").homedir(), ".pi-dashboard", "node_modules", ".bin");
       const env = buildSpawnEnv({ PATH: `${managedBin}:/usr/bin` });
-      expect(env.PATH).toBe(`${managedBin}:/usr/bin`);
+      // Managed bin should appear exactly once
+      const parts = env.PATH!.split(":");
+      const managedCount = parts.filter(p => p === managedBin).length;
+      expect(managedCount).toBe(1);
     });
   });
 

package/packages/server/src/__tests__/session-lifecycle-logging.test.ts

@@ -43,7 +43,7 @@ describe("Session lifecycle logging", () => {
     }));
     await delay(100);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] session registered: log-reg cwd=/tmp/test"));
     ws.close();
   }, 10000);
@@ -64,7 +64,7 @@ describe("Session lifecycle logging", () => {
     ws.send(JSON.stringify({ type: "session_unregister", sessionId: "log-unreg" }));
     await delay(100);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] session unregistered: log-unreg (explicit)"));
     ws.close();
   }, 10000);
@@ -87,7 +87,7 @@ describe("Session lifecycle logging", () => {
     ws.close();
     await delay(SHORT_HB + 300);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] session timed out: log-timeout (no heartbeat for"));
   }, 10000);
 
@@ -107,7 +107,7 @@ describe("Session lifecycle logging", () => {
     ws.close();
     await delay(200);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] connection closed: log-close"));
   }, 10000);
 
@@ -132,7 +132,7 @@ describe("Session lifecycle logging", () => {
     (ws as any)._socket?.pause();
     await delay(200 * 4);
 
-    const logs = errorSpy.mock.calls.map((c) => c[0]);
+    const logs = errorSpy.mock.calls.map((c: any) => c[0]);
     expect(logs).toContainEqual(expect.stringContaining("[gateway] connection dead (ping timeout, 2 misses): log-ping"));
   }, 10000);
 });

package/packages/server/src/__tests__/tunnel.test.ts

@@ -7,7 +7,7 @@ vi.mock("node:fs", async (importOriginal) => {
   return {
     ...actual,
     default: {
-      ...actual.default,
+      ...(actual as any).default,
       existsSync: vi.fn(),
       readFileSync: vi.fn(),
       writeFileSync: vi.fn(),
@@ -25,7 +25,7 @@ vi.mock("node:os", async (importOriginal) => {
   const actual = await importOriginal<typeof import("node:os")>();
   return {
     ...actual,
-    default: { ...actual.default, homedir: vi.fn(() => "/home/testuser") },
+    default: { ...(actual as any).default, homedir: vi.fn(() => "/home/testuser") },
     homedir: vi.fn(() => "/home/testuser"),
   };
 });