@towles/tool 0.0.107 → 0.0.108

package/plugins/tt-agentboard/packages/runtime/src/contracts/agent-watcher.ts

@@ -0,0 +1,38 @@
+import type { AgentEvent } from "./agent";
+
+/**
+ * Callback context provided by the server to each watcher.
+ * Lets watchers resolve project directories to mux session names
+ * and emit events without knowing about server internals.
+ */
+export interface AgentWatcherContext {
+  /** Resolve a project directory path to a mux session name, or null if unmatched */
+  resolveSession(projectDir: string): string | null;
+  /** Emit an agent event (applied to tracker + broadcast automatically) */
+  emit(event: AgentEvent): void;
+}
+
+/**
+ * Interface for agent watchers that detect agent status by watching
+ * external data sources (thread files, databases, etc).
+ *
+ * Implementations:
+ *   - amp: watches ~/.local/share/amp/threads/*.json
+ *   - claude-code: watches ~/.claude/projects/ JSONL files
+ *   - codex: watches ~/.codex/sessions/ JSONL transcripts
+ *   - opencode: polls OpenCode SQLite database
+ *
+ * To add a new watcher:
+ *   1. Create a file implementing AgentWatcher
+ *   2. Register it via PluginAPI.registerWatcher() or in the server entry point
+ */
+export interface AgentWatcher {
+  /** Unique name for this watcher (e.g. "amp", "claude-code") */
+  readonly name: string;
+
+  /** Start watching. Called once by the server with the watcher context. */
+  start(ctx: AgentWatcherContext): void;
+
+  /** Stop watching and clean up resources. */
+  stop(): void;
+}

package/plugins/tt-agentboard/packages/runtime/src/contracts/agent.ts

@@ -0,0 +1,16 @@
+export type AgentStatus = "idle" | "running" | "done" | "error" | "waiting" | "interrupted";
+
+export interface AgentEvent {
+  agent: string;
+  session: string;
+  status: AgentStatus;
+  ts: number;
+  threadId?: string;
+  threadName?: string;
+  /** Set by tracker when serializing for the TUI — true if user hasn't seen this terminal state */
+  unseen?: boolean;
+  /** Set by pane scanner — the tmux pane ID where this agent was detected */
+  paneId?: string;
+}
+
+export const TERMINAL_STATUSES = new Set<AgentStatus>(["done", "error", "interrupted"]);

package/plugins/tt-agentboard/packages/runtime/src/contracts/index.ts

@@ -0,0 +1,3 @@
+export type { AgentStatus, AgentEvent } from "./agent";
+export { TERMINAL_STATUSES } from "./agent";
+export type { MuxProvider, MuxSessionInfo } from "./mux";

package/plugins/tt-agentboard/packages/runtime/src/contracts/mux.ts

@@ -0,0 +1,148 @@
+// ─── Specification version ───────────────────────────────────────────────────
+// Like ai-sdk's specificationVersion — a literal discriminant for version compat.
+
+export type MuxSpecificationVersion = "v1";
+
+// ─── Core data types ─────────────────────────────────────────────────────────
+
+export interface MuxSessionInfo {
+  readonly name: string;
+  readonly createdAt: number;
+  readonly dir: string;
+  readonly windows: number;
+}
+
+export interface ActiveWindow {
+  readonly id: string;
+  readonly sessionName: string;
+  readonly active: boolean;
+}
+
+export interface SidebarPane {
+  readonly paneId: string;
+  readonly sessionName: string;
+  readonly windowId: string;
+  readonly width?: number;
+  readonly windowWidth?: number;
+}
+
+/** Position for sidebar placement */
+export type SidebarPosition = "left" | "right";
+
+/** Provider-specific metadata (escape hatch — like ai-sdk's providerMetadata) */
+export type MuxProviderMetadata = Record<string, Record<string, unknown>>;
+
+// ─── Capability interfaces ───────────────────────────────────────────────────
+// Split from one monolith into composable traits. Providers implement what they
+// support. The server narrows with type guards, not NonNullable hacks.
+
+/**
+ * Core mux operations — every provider MUST implement this.
+ *
+ * Like ai-sdk's ProviderV4 required methods (languageModel, embeddingModel).
+ */
+export interface MuxProviderV1 {
+  readonly specificationVersion: "v1";
+  readonly name: string;
+
+  // Session CRUD
+  listSessions(): MuxSessionInfo[];
+  switchSession(name: string, clientTty?: string): void;
+  getCurrentSession(): string | null;
+  getSessionDir(name: string): string;
+  getPaneCount(name: string): number;
+  getClientTty(): string;
+  createSession(name?: string, dir?: string): void;
+  killSession(name: string): void;
+
+  // Hooks
+  setupHooks(serverHost: string, serverPort: number): void;
+  cleanupHooks(): void;
+}
+
+/**
+ * Window/tab awareness — providers that can enumerate their windows/tabs.
+ */
+export interface WindowCapable {
+  listActiveWindows(): ActiveWindow[];
+  getCurrentWindowId(): string | null;
+}
+
+/**
+ * Sidebar management — providers that can spawn/manage sidebar panes.
+ */
+export interface SidebarCapable {
+  listSidebarPanes(sessionName?: string): SidebarPane[];
+  spawnSidebar(
+    sessionName: string,
+    windowId: string,
+    width: number,
+    position: SidebarPosition,
+  ): string | null;
+  hideSidebar(paneId: string): void;
+  killSidebarPane(paneId: string): void;
+  resizeSidebarPane(paneId: string, width: number): void;
+  cleanupSidebar(): void;
+}
+
+/**
+ * Batch operations — providers that can fetch data in bulk for performance.
+ */
+export interface BatchCapable {
+  getAllPaneCounts(): Map<string, number>;
+}
+
+// ─── Composite types ─────────────────────────────────────────────────────────
+
+/**
+ * A fully-featured provider with all capabilities.
+ * Most providers won't implement everything — use the type guards below to narrow.
+ */
+export type FullMuxProvider = MuxProviderV1 & WindowCapable & SidebarCapable & BatchCapable;
+
+/**
+ * The union type the server accepts — core is required, capabilities are optional.
+ *
+ * Like ai-sdk's LanguageModel = V2 | V3 | V4 — accepts any level of capability.
+ */
+export type MuxProvider = MuxProviderV1 & Partial<WindowCapable & SidebarCapable & BatchCapable>;
+
+// ─── Type guards ─────────────────────────────────────────────────────────────
+// Runtime narrowing — like ai-sdk's isInstance() pattern, but for capabilities.
+
+/** Check if a provider supports window operations */
+export function isWindowCapable(p: MuxProvider): p is MuxProviderV1 & WindowCapable {
+  return typeof p.listActiveWindows === "function" && typeof p.getCurrentWindowId === "function";
+}
+
+/** Check if a provider supports sidebar operations */
+export function isSidebarCapable(p: MuxProvider): p is MuxProviderV1 & SidebarCapable {
+  return (
+    typeof p.listSidebarPanes === "function" &&
+    typeof p.spawnSidebar === "function" &&
+    typeof p.hideSidebar === "function" &&
+    typeof p.killSidebarPane === "function" &&
+    typeof p.resizeSidebarPane === "function" &&
+    typeof p.cleanupSidebar === "function"
+  );
+}
+
+/** Check if a provider supports batch operations */
+export function isBatchCapable(p: MuxProvider): p is MuxProviderV1 & BatchCapable {
+  return typeof p.getAllPaneCounts === "function";
+}
+
+/** Check if a provider supports full sidebar management (window + sidebar) */
+export function isFullSidebarCapable(
+  p: MuxProvider,
+): p is MuxProviderV1 & WindowCapable & SidebarCapable {
+  return isWindowCapable(p) && isSidebarCapable(p);
+}
+
+// ─── Provider settings ───────────────────────────────────────────────────────
+// Like ai-sdk's OpenAIProviderSettings — each provider can extend this.
+
+export interface MuxProviderSettings {
+  /** Override the provider name (for custom/wrapped providers) */
+  name?: string;
+}

package/plugins/tt-agentboard/packages/runtime/src/debug.ts

@@ -0,0 +1,19 @@
+import { appendFileSync } from "node:fs";
+
+export const DEBUG_LOG = "/tmp/agentboard-debug.log";
+export const TUI_RESIZE_LOG = "/tmp/agentboard-tui-resize.log";
+export const TUI_AGENT_CLICK_LOG = "/tmp/agentboard-tui-agent-click.log";
+export const SERVER_ERR_LOG = "/tmp/agentboard-server-err.log";
+export const INSTALL_LOG = "/tmp/agentboard-install.log";
+
+const DEBUG_ENABLED = !!process.env.TT_AGENTBOARD_DEBUG;
+
+export function debugLog(category: string, msg: string, data?: Record<string, unknown>): void {
+  if (!DEBUG_ENABLED) return;
+  const ts = new Date().toISOString().slice(11, 23);
+  const extra = data ? " " + JSON.stringify(data) : "";
+  const line = `[${ts}] [${category}] ${msg}${extra}\n`;
+  try {
+    appendFileSync(DEBUG_LOG, line);
+  } catch {}
+}

package/plugins/tt-agentboard/packages/runtime/src/index.ts

@@ -0,0 +1,69 @@
+export type {
+  MuxProvider,
+  MuxProviderV1,
+  MuxSessionInfo,
+  ActiveWindow,
+  SidebarPane,
+  SidebarPosition,
+  WindowCapable,
+  SidebarCapable,
+  BatchCapable,
+  FullMuxProvider,
+  MuxProviderSettings,
+} from "./contracts/mux";
+export {
+  isWindowCapable,
+  isSidebarCapable,
+  isBatchCapable,
+  isFullSidebarCapable,
+} from "./contracts/mux";
+export type { AgentStatus, AgentEvent } from "./contracts/agent";
+export { TERMINAL_STATUSES } from "./contracts/agent";
+export type { AgentWatcher, AgentWatcherContext } from "./contracts/agent-watcher";
+export { AgentTracker } from "./agents/tracker";
+export { AmpAgentWatcher } from "./agents/watchers/amp";
+export { ClaudeCodeAgentWatcher } from "./agents/watchers/claude-code";
+export { CodexAgentWatcher } from "./agents/watchers/codex";
+export { OpenCodeAgentWatcher } from "./agents/watchers/opencode";
+export { MuxRegistry } from "./mux/registry";
+export { detectMux } from "./mux/detect";
+export { PluginLoader } from "./plugins/loader";
+export type { PluginAPI, PluginFactory } from "./plugins/loader";
+export {
+  debugLog,
+  DEBUG_LOG,
+  TUI_RESIZE_LOG,
+  TUI_AGENT_CLICK_LOG,
+  SERVER_ERR_LOG,
+  INSTALL_LOG,
+} from "./debug";
+export { loadConfig, saveConfig } from "./config";
+export type { AgentboardConfig } from "./config";
+export { resolveTheme, BUILTIN_THEMES, DEFAULT_THEME } from "./themes";
+export type { Theme, ThemePalette, PartialTheme } from "./themes";
+export { startServer } from "./server/index";
+export { ensureServer } from "./server/launcher";
+export {
+  SERVER_PORT,
+  SERVER_HOST,
+  PID_FILE,
+  SERVER_IDLE_TIMEOUT_MS,
+  STUCK_RUNNING_TIMEOUT_MS,
+  C,
+  STATUS_COLORS,
+  STATUS_ICONS,
+} from "./shared";
+export type {
+  SessionData,
+  ServerState,
+  FocusUpdate,
+  ResizeNotify,
+  QuitNotify,
+  ServerMessage,
+  ClientCommand,
+  MetadataTone,
+  MetadataStatus,
+  MetadataProgress,
+  MetadataLogEntry,
+  SessionMetadata,
+} from "./shared";

package/plugins/tt-agentboard/packages/runtime/src/mux/detect.ts

@@ -0,0 +1,20 @@
+import type { MuxProvider } from "../contracts/mux";
+import { MuxRegistry } from "./registry";
+
+/**
+ * Auto-detect the terminal multiplexer from environment variables.
+ * Uses the registry to find matching providers.
+ *
+ * Detection: $TMUX → provider named "tmux"
+ *
+ * Users can override by passing their own MuxProvider.
+ */
+export function detectMux(registry?: MuxRegistry): MuxProvider | null {
+  if (!registry) return null;
+
+  if (process.env.TMUX) {
+    return registry.get("tmux");
+  }
+
+  return null;
+}

package/plugins/tt-agentboard/packages/runtime/src/mux/registry.ts

@@ -0,0 +1,45 @@
+import type { MuxProvider } from "../contracts/mux";
+
+/**
+ * Registry for MuxProvider implementations.
+ *
+ * The server resolves which provider to use via:
+ *   1. Explicit config override (user picks a mux by name)
+ *   2. Auto-detect from env ($TMUX)
+ *   3. First registered provider as fallback
+ */
+export class MuxRegistry {
+  private providers = new Map<string, MuxProvider>();
+
+  register(provider: MuxProvider): void {
+    this.providers.set(provider.name, provider);
+  }
+
+  get(name: string): MuxProvider | null {
+    return this.providers.get(name) ?? null;
+  }
+
+  list(): string[] {
+    return [...this.providers.keys()];
+  }
+
+  /**
+   * Resolve the active MuxProvider.
+   * @param preference — explicit mux name from config. Takes priority.
+   * @returns the resolved provider, or null if none found.
+   */
+  resolve(preference?: string): MuxProvider | null {
+    // 1. Explicit preference
+    if (preference) {
+      return this.providers.get(preference) ?? null;
+    }
+
+    // 2. Auto-detect from environment (tmux only)
+    if (process.env.TMUX && this.providers.has("tmux")) {
+      return this.providers.get("tmux")!;
+    }
+
+    // 3. No match
+    return null;
+  }
+}

package/plugins/tt-agentboard/packages/runtime/src/plugins/loader.ts

@@ -0,0 +1,152 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, extname } from "node:path";
+import type { MuxProvider } from "../contracts/mux";
+import type { AgentWatcher } from "../contracts/agent-watcher";
+import { MuxRegistry } from "../mux/registry";
+import { SERVER_PORT, SERVER_HOST } from "../shared";
+
+/**
+ * The API surface passed to every plugin factory function.
+ * Inspired by pi-mono's ExtensionAPI pattern:
+ *   export default function(api: PluginAPI) { ... }
+ */
+export interface PluginAPI {
+  registerMux(provider: MuxProvider): void;
+  registerWatcher(watcher: AgentWatcher): void;
+  readonly serverPort: number;
+  readonly serverHost: string;
+}
+
+/** Plugin factory — the single export a plugin must provide */
+export type PluginFactory = (api: PluginAPI) => void | Promise<void>;
+
+export class PluginLoader {
+  readonly registry = new MuxRegistry();
+  private watchers: AgentWatcher[] = [];
+
+  registerMux(provider: MuxProvider): void {
+    this.registry.register(provider);
+  }
+
+  registerWatcher(watcher: AgentWatcher): void {
+    this.watchers.push(watcher);
+  }
+
+  getWatchers(): AgentWatcher[] {
+    return [...this.watchers];
+  }
+
+  resolve(preference?: string): MuxProvider | null {
+    return this.registry.resolve(preference);
+  }
+
+  /**
+   * Build the PluginAPI object that gets passed to every factory function.
+   */
+  private createAPI(): PluginAPI {
+    return {
+      registerMux: (provider: MuxProvider) => this.registry.register(provider),
+      registerWatcher: (watcher: AgentWatcher) => this.registerWatcher(watcher),
+      serverPort: SERVER_PORT,
+      serverHost: SERVER_HOST,
+    };
+  }
+
+  /**
+   * Load plugins from a directory (like ~/.config/towles-tool/agentboard/plugins/).
+   * Scans one level deep:
+   *   - *.ts / *.js files → loaded directly
+   *   - subdirs with index.ts / index.js → loaded as entry point
+   *
+   * Each must `export default function(api: PluginAPI) { ... }`
+   *
+   * Returns names of successfully loaded plugins.
+   */
+  loadDir(dir: string): string[] {
+    if (!existsSync(dir)) return [];
+
+    const loaded: string[] = [];
+    const api = this.createAPI();
+    const entries = readdirSync(dir);
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+
+      if (stat.isFile()) {
+        const ext = extname(entry);
+        if (ext !== ".ts" && ext !== ".js") continue;
+        if (this.loadFactory(fullPath, api)) loaded.push(entry);
+      } else if (stat.isDirectory()) {
+        // Check for index.ts or index.js
+        const indexTs = join(fullPath, "index.ts");
+        const indexJs = join(fullPath, "index.js");
+        const indexPath = existsSync(indexTs) ? indexTs : existsSync(indexJs) ? indexJs : null;
+        if (indexPath && this.loadFactory(indexPath, api)) loaded.push(entry);
+      }
+    }
+
+    return loaded;
+  }
+
+  /**
+   * Load community plugins from npm package names.
+   * Each package should `export default function(api: PluginAPI) { ... }`
+   * or have a package.json "agentboard" field pointing to the entry file.
+   *
+   * Returns names of successfully loaded packages.
+   */
+  loadPackages(packageNames: string[]): string[] {
+    const loaded: string[] = [];
+    const api = this.createAPI();
+
+    for (const pkg of packageNames) {
+      try {
+        const mod = require(pkg);
+        const factory: PluginFactory | undefined =
+          typeof mod.default === "function"
+            ? mod.default
+            : typeof mod === "function"
+              ? mod
+              : undefined;
+        if (factory) {
+          factory(api);
+          loaded.push(pkg);
+        }
+      } catch {
+        // Package not installed or broken — skip
+      }
+    }
+
+    return loaded;
+  }
+
+  /**
+   * Load a single factory from a file path.
+   */
+  private loadFactory(filePath: string, api: PluginAPI): boolean {
+    try {
+      const mod = require(filePath);
+      const factory: PluginFactory | undefined =
+        typeof mod.default === "function"
+          ? mod.default
+          : typeof mod === "function"
+            ? mod
+            : undefined;
+      if (!factory) return false;
+      factory(api);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  getSetupInfo(): { registeredMuxProviders: string[]; configPath: string; serverPort: number } {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    return {
+      registeredMuxProviders: this.registry.list(),
+      configPath: join(home, ".config", "towles-tool", "agentboard", "config.json"),
+      serverPort: SERVER_PORT,
+    };
+  }
+}

package/plugins/tt-agentboard/packages/runtime/src/server/context.ts

@@ -0,0 +1,112 @@
+import type { Server } from "bun";
+import type { MuxProvider, FullSidebarCapable, SidebarPane } from "../contracts/mux";
+import type { AgentTracker } from "../agents/tracker";
+import type { SessionOrder } from "./session-order";
+import type { SessionMetadataStore } from "./metadata-store";
+import type { SidebarResizeContext, SidebarResizeSuppression } from "./sidebar-width-sync";
+import type { ServerState } from "../shared";
+import type { AgentStatus } from "../contracts/agent";
+
+export interface PaneAgentPresence {
+  agent: string;
+  session: string;
+  paneId: string;
+  threadId?: string;
+  threadName?: string;
+  status?: AgentStatus;
+  lastSeenTs: number;
+}
+
+/**
+ * Shared mutable state for all server modules.
+ * Created once in startServer(), passed to all sub-modules.
+ */
+export interface ServerContext {
+  // Core dependencies
+  mux: MuxProvider;
+  allProviders: MuxProvider[];
+  tracker: AgentTracker;
+  sessionOrder: SessionOrder;
+  metadataStore: SessionMetadataStore;
+
+  // Config
+  currentTheme: string | undefined;
+  sidebarWidth: number;
+  sidebarPosition: "left" | "right";
+  sidebarVisible: boolean;
+  home: string;
+
+  // Session/focus state
+  focusedSession: string | null;
+  lastState: ServerState | null;
+  clientCount: number;
+  idleTimer: ReturnType<typeof setTimeout> | null;
+  clientTtys: WeakMap<object, string>;
+  clientSessionNames: WeakMap<object, string>;
+  sessionProviders: Map<string, MuxProvider>;
+  clientTtyBySession: Map<string, string>;
+
+  // Current session cache
+  cachedCurrentSession: string | null;
+  cachedCurrentSessionTs: number;
+
+  // Sidebar state
+  pendingSidebarSpawns: Set<string>;
+  suppressedSidebarResizeAcks: Map<string, SidebarResizeSuppression>;
+  sidebarSnapshots: Map<string, { width?: number; windowWidth?: number }>;
+  pendingSidebarResize: ReturnType<typeof setTimeout> | null;
+  sidebarPaneCache: { provider: FullSidebarCapable; panes: SidebarPane[] }[] | null;
+  sidebarPaneCacheTs: number;
+  ensureSidebarTimer: ReturnType<typeof setTimeout> | null;
+  ensureSidebarPendingCtx: { session: string; windowId: string } | undefined;
+
+  // Pane agent scanning
+  paneAgentsBySession: Map<string, Map<string, PaneAgentPresence>>;
+  paneScanTimer: ReturnType<typeof setInterval> | null;
+
+  // Port polling
+  portPollTimer: ReturnType<typeof setInterval> | null;
+
+  // Highlight tracking
+  pendingHighlightResets: Map<string, ReturnType<typeof setTimeout>>;
+
+  // Server ref (set after Bun.serve)
+  server: Server;
+
+  // Wired functions
+  broadcastState: () => void;
+  broadcastFocusOnly: (sender?: any) => void;
+  getCurrentSession: () => string | null;
+  getCachedCurrentSession: () => string | null;
+  invalidateCurrentSessionCache: () => void;
+  getProvidersWithSidebar: () => FullSidebarCapable[];
+  listSidebarPanesByProvider: () => { provider: FullSidebarCapable; panes: SidebarPane[] }[];
+  invalidateSidebarPaneCache: () => void;
+  handleFocus: (name: string) => void;
+  moveFocus: (delta: -1 | 1, sender?: any) => void;
+  setFocus: (name: string, sender?: any) => void;
+  refreshPaneAgents: () => void;
+  cleanup: () => void;
+  toggleSidebar: (ctx?: { session: string; windowId: string }) => void;
+  ensureSidebarInWindow: (
+    provider?: FullSidebarCapable,
+    ctx?: { session: string; windowId: string },
+  ) => void;
+  debouncedEnsureSidebar: (ctx?: { session: string; windowId: string }) => void;
+  scheduleSidebarResize: (ctx?: SidebarResizeContext) => void;
+  resizeSidebars: (ctx?: SidebarResizeContext) => void;
+  quitAll: () => void;
+  switchToVisibleIndex: (index: number, clientTty?: string) => void;
+  focusAgentPane: (
+    sessionName: string,
+    agentName: string,
+    threadId?: string,
+    threadName?: string,
+  ) => void;
+  killAgentPane: (
+    sessionName: string,
+    agentName: string,
+    threadId?: string,
+    threadName?: string,
+  ) => void;
+}