@blackbelt-technology/pi-agent-dashboard 0.2.0

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

@@ -0,0 +1,255 @@
+/**
+ * REST API endpoint types.
+ */
+import type {
+  DashboardSession,
+  DashboardEvent,
+  ApiResponse,
+} from "./types.js";
+
+// ── Sessions ────────────────────────────────────────────────────────
+
+export interface ListSessionsQuery {
+  status?: "active" | "ended";
+}
+
+export type ListSessionsResponse = ApiResponse<DashboardSession[]>;
+
+// ── Events ──────────────────────────────────────────────────────────
+
+export type FetchEventContentResponse = ApiResponse<DashboardEvent>;
+
+// ── Session Spawn ───────────────────────────────────────────────────
+
+export interface SpawnSessionRequest {
+  cwd: string;
+}
+
+export type SpawnSessionResponse = ApiResponse<{ message: string }>;
+
+// ── Aggregate Stats ─────────────────────────────────────────────────
+
+export interface AggregateStats {
+  activeSessions: number;
+  totalTokensIn: number;
+  totalTokensOut: number;
+  totalCost: number;
+}
+
+export type AggregateStatsResponse = ApiResponse<AggregateStats>;
+
+// ── File Read ───────────────────────────────────────────────────────
+
+export interface FileContentResult {
+  type: "file";
+  content: string;
+}
+
+export interface DirectoryListResult {
+  type: "directory";
+  entries: string[];
+}
+
+export type FileReadResult = FileContentResult | DirectoryListResult;
+
+export type FileReadResponse = ApiResponse<FileReadResult>;
+
+// ── Browse ──────────────────────────────────────────────────────────
+
+export interface BrowseEntry {
+  name: string;
+  path: string;
+  isGit: boolean;
+  isPi: boolean;
+}
+
+export interface BrowseResult {
+  entries: BrowseEntry[];
+  parent: string | null;
+  current: string;
+}
+
+export type BrowseResponse = ApiResponse<BrowseResult>;
+
+// ── Tunnel Status ───────────────────────────────────────────────────
+
+export type TunnelStatus =
+  | { status: "active"; url: string; serverOs: string }
+  | { status: "inactive"; serverOs: string }
+  | { status: "unavailable"; serverOs: string };
+
+export type TunnelStatusResponse = ApiResponse<TunnelStatus>;
+
+// ── Pi Resources ────────────────────────────────────────────────────
+
+export interface PiResource {
+  name: string;
+  description?: string;
+  filePath: string;
+  type: "extension" | "skill" | "prompt";
+}
+
+export interface PiResourceScope {
+  extensions: PiResource[];
+  skills: PiResource[];
+  prompts: PiResource[];
+}
+
+export interface PiPackageInfo {
+  name: string;
+  description?: string;
+  source: string; // e.g. "npm:pi-web-access", "git:github.com/user/repo", "../relative"
+  resources: PiResourceScope;
+  /** Which scope this package was resolved from */
+  scope?: "local" | "global";
+}
+
+export interface PiResourcesResult {
+  local: PiResourceScope;
+  global: PiResourceScope;
+  packages: PiPackageInfo[];
+}
+
+export type PiResourcesResponse = ApiResponse<PiResourcesResult>;
+
+// ── Git Operations ──────────────────────────────────────────────────
+
+export interface GitBranchEntry {
+  name: string;
+  isRemote: boolean;
+  isCurrent: boolean;
+}
+
+export interface GitBranchesResult {
+  current: string;
+  detached: boolean;
+  branches: GitBranchEntry[];
+}
+
+export type GitBranchesResponse = ApiResponse<GitBranchesResult>;
+
+export interface GitCheckoutRequest {
+  cwd: string;
+  branch: string;
+  stash?: boolean;
+}
+
+export type GitCheckoutResponse =
+  | ApiResponse<{ stashed?: boolean }>
+  | ApiResponse<never> & { success: false; dirty: true; files: string[] };
+
+export interface GitInitRequest {
+  cwd: string;
+}
+
+export type GitInitResponse = ApiResponse<void>;
+
+export interface GitStashPopResult {
+  conflicts: boolean;
+}
+
+export type GitStashPopResponse = ApiResponse<GitStashPopResult>;
+
+// ── Provider Auth ─────────────────────────────────────────────────────────
+
+export interface ProviderAuthInfo {
+  id: string;
+  name: string;
+  flowType: "auth_code" | "device_code";
+}
+
+export interface ProviderAuthStatus {
+  id: string;
+  name: string;
+  flowType: "auth_code" | "device_code" | "api_key";
+  authenticated: boolean;
+  expires?: number;
+  maskedKey?: string;
+}
+
+export interface AuthorizeResponse {
+  flowId: string;
+  authUrl: string;
+}
+
+export interface DeviceCodeResponse {
+  flowId: string;
+  userCode: string;
+  verificationUri: string;
+  expiresIn: number;
+  interval: number;
+}
+
+// ── Package Management ──────────────────────────────────────────────
+
+/** A single result from the npm registry search. */
+export interface NpmPackageResult {
+  name: string;
+  description?: string;
+  version: string;
+  keywords: string[];
+  date: string;
+  publisher?: { username: string; email?: string };
+  links?: { npm?: string; homepage?: string; repository?: string };
+  downloads?: { weekly: number; monthly: number };
+  /** Derived from keywords: extension, skill, theme, prompt */
+  types: string[];
+}
+
+export interface NpmSearchResponse {
+  packages: NpmPackageResult[];
+  total: number;
+}
+
+export type NpmSearchApiResponse = ApiResponse<NpmSearchResponse>;
+
+export interface NpmReadmeResponse {
+  readme: string;
+  name: string;
+  version: string;
+}
+
+export type NpmReadmeApiResponse = ApiResponse<NpmReadmeResponse>;
+
+/** An installed pi package as returned by the list endpoint. */
+export interface InstalledPackage {
+  source: string;
+  scope: "user" | "project";
+  filtered: boolean;
+  installedPath?: string;
+  /** Set after check-updates: true if newer version available */
+  updateAvailable?: boolean;
+}
+
+export type InstalledPackagesResponse = ApiResponse<InstalledPackage[]>;
+
+/** Request body for install / remove / update operations. */
+export interface PackageOperationRequest {
+  source: string;
+  scope: "global" | "local";
+  cwd?: string;
+}
+
+/** Response returned immediately (202) when an operation starts. */
+export interface PackageOperationResponse {
+  operationId: string;
+}
+
+export type PackageOperationApiResponse = ApiResponse<PackageOperationResponse>;
+
+/** Result of check-updates. */
+export interface PackageUpdateInfo {
+  source: string;
+  displayName: string;
+  type: "npm" | "git";
+}
+
+export type CheckUpdatesResponse = ApiResponse<PackageUpdateInfo[]>;
+
+/** Detected network interface for trusted networks UI. */
+export interface NetworkInterface {
+  name: string;
+  address: string;
+  netmask: string;
+  cidr: string;
+}

package/packages/shared/src/server-identity.ts

@@ -0,0 +1,51 @@
+/**
+ * Server identity verification via HTTP health check.
+ * Replaces bare TCP port probes with identity-verified dashboard detection.
+ */
+
+const HEALTH_TIMEOUT = 2000;
+
+export interface DashboardStatus {
+  /** Whether the dashboard server is running on this port */
+  running: boolean;
+  /** PID of the running server (if detected) */
+  pid?: number;
+  /** Port is occupied by a non-dashboard service */
+  portConflict?: boolean;
+}
+
+/**
+ * Check if a dashboard server is running on the given port by hitting GET /api/health.
+ * Returns identity-verified status instead of just "port is open".
+ */
+export async function isDashboardRunning(port: number, host = "localhost"): Promise<DashboardStatus> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), HEALTH_TIMEOUT);
+
+  try {
+    const res = await fetch(`http://${host}:${port}/api/health`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+
+    if (!res.ok) {
+      return { running: false, portConflict: true };
+    }
+
+    const data = await res.json() as Record<string, unknown>;
+    if (data && data.ok === true && typeof data.pid === "number") {
+      return { running: true, pid: data.pid };
+    }
+
+    // HTTP 200 but not our format — another service
+    return { running: false, portConflict: true };
+  } catch (err: unknown) {
+    clearTimeout(timer);
+    // Connection refused or timeout — nothing running
+    if (err instanceof Error && err.name === "AbortError") {
+      return { running: false };
+    }
+    // Could be ECONNREFUSED or other network error
+    return { running: false };
+  }
+}

package/packages/shared/src/session-meta.ts

@@ -0,0 +1,86 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Session metadata stored as a sidecar `.meta.json` file
+ * next to the session's `.jsonl` file.
+ *
+ * Contains dashboard-owned per-session state and cached stats.
+ * All fields are optional — a minimal `{ source: "dashboard" }` is valid.
+ */
+export interface SessionMeta {
+  // Dashboard-owned (user-set via UI)
+  source?: string;
+  name?: string;
+  attachedProposal?: string | null;
+  hidden?: boolean;
+
+  // Cached identity & state (from .jsonl header / bridge)
+  cwd?: string;
+  status?: string;
+  startedAt?: number;
+  endedAt?: number;
+  firstMessage?: string;
+
+  // Cached stats (extracted from .jsonl, avoids re-parsing)
+  model?: string;
+  thinkingLevel?: string;
+  tokensIn?: number;
+  tokensOut?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: number;
+  contextTokens?: number;
+  contextWindow?: number;
+
+  // Cache freshness — compared against .jsonl mtime
+  cachedAt?: number;
+}
+
+/**
+ * Derive the `.meta.json` path from a `.jsonl` session file path.
+ */
+export function metaPath(sessionFile: string): string {
+  const dir = path.dirname(sessionFile);
+  const base = path.basename(sessionFile, ".jsonl");
+  return path.join(dir, `${base}.meta.json`);
+}
+
+/**
+ * Read session metadata from the sidecar file.
+ * Returns undefined if the file doesn't exist or is invalid.
+ */
+export function readSessionMeta(sessionFile: string): SessionMeta | undefined {
+  try {
+    const content = fs.readFileSync(metaPath(sessionFile), "utf-8");
+    return JSON.parse(content) as SessionMeta;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Write session metadata to the sidecar file.
+ * Creates parent directories if needed.
+ * Uses atomic write (write-to-tmp + rename) to prevent corruption.
+ */
+export function writeSessionMeta(sessionFile: string, meta: SessionMeta): void {
+  const p = metaPath(sessionFile);
+  const dir = path.dirname(p);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmpPath = p + ".tmp";
+  fs.writeFileSync(tmpPath, JSON.stringify(meta, null, 2) + "\n");
+  fs.renameSync(tmpPath, p);
+}
+
+/**
+ * Merge new fields into an existing `.meta.json` sidecar.
+ * Reads the existing file, merges with the provided partial,
+ * and writes atomically. Fields in `partial` overwrite existing ones.
+ * Preserves any unknown fields already in the file.
+ */
+export function mergeSessionMeta(sessionFile: string, partial: Partial<SessionMeta>): void {
+  const existing = readSessionMeta(sessionFile) ?? {};
+  const merged = { ...existing, ...partial };
+  writeSessionMeta(sessionFile, merged);
+}

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

@@ -0,0 +1,174 @@
+/**
+ * State replay — synthesizes dashboard events from pi session entries
+ * so the browser can rebuild the chat view after a reconnect or DB reset.
+ */
+import type { EventForwardMessage } from "./protocol.js";
+
+/**
+ * Convert pi session entries (from ctx.sessionManager.getBranch())
+ * into dashboard event_forward messages that the event reducer can process.
+ *
+ * Only generates the minimal events needed to rebuild the chat view:
+ * - message_start for user messages
+ * - message_update + message_end for assistant messages
+ * - tool_execution_start / tool_execution_end for tool calls
+ * - model_select for model changes
+ */
+export function replayEntriesAsEvents(
+  sessionId: string,
+  entries: any[],
+): EventForwardMessage[] {
+  const messages: EventForwardMessage[] = [];
+  const openToolCalls = new Set<string>(); // track tool calls without results
+
+  let currentModel = "";
+
+  for (const entry of entries) {
+    if (!entry || !entry.type) continue;
+    const ts = entry.timestamp ? new Date(entry.timestamp).getTime() : Date.now();
+
+    if (entry.type === "model_change") {
+      currentModel = entry.modelId ?? "";
+    }
+
+    if (entry.type === "message" && entry.message) {
+      const msg = entry.message;
+
+      if (msg.role === "user") {
+        messages.push(makeEvent(sessionId, "message_start", ts, { message: msg, entryId: entry.id }));
+      }
+
+      if (msg.role === "assistant") {
+        const content = Array.isArray(msg.content) ? msg.content : [];
+        // Emit tool_execution_start for each tool call
+        for (const part of content) {
+          if (part.type === "toolCall") {
+            messages.push(makeEvent(sessionId, "tool_execution_start", ts, {
+              toolCallId: part.id,
+              toolName: part.name,
+              args: typeof part.arguments === "string"
+                ? tryParseJson(part.arguments)
+                : part.arguments,
+            }));
+            openToolCalls.add(part.id);
+          }
+        }
+        // Emit message_update (sets streamingText) then message_end (finalizes)
+        messages.push(makeEvent(sessionId, "message_update", ts, { message: msg }));
+        messages.push(makeEvent(sessionId, "message_end", ts, { message: msg, entryId: entry.id }));
+
+        // Emit stats_update if usage data is present
+        const usage = msg.usage as Record<string, unknown> | undefined;
+        if (usage) {
+          const cost = usage.cost as Record<string, number> | undefined;
+          const totalTokens = usage.totalTokens as number | undefined;
+          const statsData: Record<string, unknown> = {
+            tokensIn: (usage.input as number) ?? 0,
+            tokensOut: (usage.output as number) ?? 0,
+            cost: cost?.total ?? 0,
+            turnUsage: {
+              input: (usage.input as number) ?? 0,
+              output: (usage.output as number) ?? 0,
+              cacheRead: (usage.cacheRead as number) ?? 0,
+              cacheWrite: (usage.cacheWrite as number) ?? 0,
+            },
+          };
+          // Include context usage estimate from totalTokens
+          if (totalTokens && totalTokens > 0) {
+            statsData.contextUsage = {
+              tokens: totalTokens,
+              contextWindow: inferContextWindow(currentModel),
+            };
+          }
+          messages.push(makeEvent(sessionId, "stats_update", ts, statsData));
+        }
+      }
+
+      // Tool results: toolCallId and toolName are at the message level
+      // Structure: { role: "toolResult", toolCallId, toolName, content: [{type:"text",text:"..."}], isError }
+      if (msg.role === "toolResult" && msg.toolCallId) {
+        const resultText = Array.isArray(msg.content)
+          ? msg.content
+              .filter((c: any) => c.type === "text")
+              .map((c: any) => c.text)
+              .join("")
+          : typeof msg.content === "string" ? msg.content : "";
+        // Extract image content blocks if present
+        const imageBlocks = Array.isArray(msg.content)
+          ? msg.content.filter((c: any) => c.type === "image" && c.data && c.mimeType)
+          : [];
+        const eventData: Record<string, unknown> = {
+          toolCallId: msg.toolCallId,
+          toolName: msg.toolName ?? "unknown",
+          result: resultText,
+          isError: msg.isError ?? false,
+        };
+        if (imageBlocks.length > 0) {
+          eventData.images = imageBlocks.map((c: any) => ({ data: c.data, mimeType: c.mimeType }));
+        }
+        // Include tool details (e.g. AgentDetails from pi-subagents) if present
+        if (msg.details && typeof msg.details === "object") {
+          eventData.details = msg.details;
+        }
+        messages.push(makeEvent(sessionId, "tool_execution_end", ts, eventData));
+        openToolCalls.delete(msg.toolCallId);
+      }
+    }
+
+    if (entry.type === "model_change") {
+      messages.push(makeEvent(sessionId, "model_select", ts, {
+        type: "model_select",
+        model: { provider: entry.provider, id: entry.modelId },
+      }));
+    }
+  }
+
+  // Close any orphaned tool calls (agent killed mid-execution)
+  for (const toolCallId of openToolCalls) {
+    const startEvent = messages.find(
+      (m) => m.event.eventType === "tool_execution_start" && (m.event.data as any).toolCallId === toolCallId,
+    );
+    const ts = startEvent ? startEvent.event.timestamp : Date.now();
+    messages.push(makeEvent(sessionId, "tool_execution_end", ts, {
+      toolCallId,
+      toolName: (startEvent?.event.data as any)?.toolName ?? "unknown",
+      result: "",
+      isError: false,
+    }));
+  }
+
+  return messages;
+}
+
+function makeEvent(
+  sessionId: string,
+  eventType: string,
+  timestamp: number,
+  data: Record<string, unknown>,
+): EventForwardMessage {
+  return {
+    type: "event_forward",
+    sessionId,
+    event: {
+      eventType,
+      timestamp,
+      data: { type: eventType, ...data },
+    },
+  };
+}
+
+function tryParseJson(s: string): Record<string, unknown> {
+  try { return JSON.parse(s); } catch { return {}; }
+}
+
+/** Infer context window size from model ID */
+function inferContextWindow(modelId: string): number {
+  const id = modelId.toLowerCase();
+  if (id.includes("claude") && (id.includes("opus") || id.includes("sonnet") || id.includes("haiku"))) return 200_000;
+  if (id.includes("gpt-4o")) return 128_000;
+  if (id.includes("gpt-4")) return 128_000;
+  if (id.includes("o1") || id.includes("o3") || id.includes("o4")) return 200_000;
+  if (id.includes("gemini")) return 1_000_000;
+  if (id.includes("deepseek")) return 128_000;
+  return 200_000; // safe default
+}

package/packages/shared/src/stats-extractor.ts

@@ -0,0 +1,54 @@
+/**
+ * Extract token stats from a turn_end event.
+ * Reads usage from event.message.usage (the pi SDK's TurnEndEvent shape).
+ */
+
+export interface StatsData {
+  tokensIn: number;
+  tokensOut: number;
+  cost: number;
+  turnUsage: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  };
+  contextUsage?: {
+    tokens: number | null;
+    contextWindow: number;
+  };
+}
+
+/**
+ * Extract stats from a turn_end event and context usage.
+ * Returns null if the event has no usage data.
+ */
+export function extractTurnStats(
+  event: Record<string, unknown>,
+  contextUsage?: { tokens: number | null; contextWindow: number },
+): StatsData | null {
+  const message = event.message as Record<string, unknown> | undefined;
+  const usage = message?.usage as Record<string, unknown> | undefined;
+
+  if (!usage) return null;
+
+  const cost = usage.cost as Record<string, number> | undefined;
+
+  const stats: StatsData = {
+    tokensIn: (usage.input as number) ?? 0,
+    tokensOut: (usage.output as number) ?? 0,
+    cost: cost?.total ?? 0,
+    turnUsage: {
+      input: (usage.input as number) ?? 0,
+      output: (usage.output as number) ?? 0,
+      cacheRead: (usage.cacheRead as number) ?? 0,
+      cacheWrite: (usage.cacheWrite as number) ?? 0,
+    },
+  };
+
+  if (contextUsage) {
+    stats.contextUsage = contextUsage;
+  }
+
+  return stats;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Shared types for the terminal emulator feature.
+ */
+
+export interface TerminalSession {
+  id: string;
+  cwd: string;
+  shell: string;
+  status: "active" | "ended";
+  title?: string;
+  manuallyRenamed?: boolean;
+  createdAt: number;
+}
+
+/** Control messages sent as text frames on the terminal WebSocket. */
+export type TerminalControlMessage =
+  | { type: "resize"; cols: number; rows: number }
+  | { type: "title"; title: string };