@towles/tool 0.0.106 → 0.0.108

package/plugins/tt-agentboard/packages/mux-tmux/src/provider.ts

@@ -0,0 +1,259 @@
+import type {
+  MuxProviderV1,
+  MuxSessionInfo,
+  ActiveWindow,
+  SidebarPane,
+  SidebarPosition,
+  WindowCapable,
+  SidebarCapable,
+  BatchCapable,
+} from "@tt-agentboard/runtime";
+import { TmuxClient } from "./client";
+import { debugLog } from "@tt-agentboard/runtime";
+
+/** Settings for creating a tmux provider (ai-sdk style) */
+export interface TmuxProviderSettings {
+  /** Override the provider name */
+  name?: string;
+  /** Override the TmuxClient instance (for testing) */
+  client?: TmuxClient;
+}
+
+function plog(msg: string, data?: Record<string, unknown>) {
+  debugLog("provider", msg, data);
+}
+
+const STASH_SESSION = "_ab_stash";
+const SIDEBAR_PANE_TITLE = "agentboard-sidebar";
+
+export class TmuxProvider implements MuxProviderV1, WindowCapable, SidebarCapable, BatchCapable {
+  readonly specificationVersion = "v1" as const;
+  readonly name: string;
+  private readonly tmux: TmuxClient;
+
+  constructor(settings?: TmuxProviderSettings) {
+    this.name = settings?.name ?? "tmux";
+    this.tmux = settings?.client ?? new TmuxClient();
+  }
+
+  listSessions(): MuxSessionInfo[] {
+    const sessions = this.tmux.listSessions().filter((s) => s.name !== STASH_SESSION);
+    const activeDirs = this.tmux.getActiveSessionDirs();
+    return sessions.map((s) => ({
+      name: s.name,
+      createdAt: s.createdAt,
+      dir: activeDirs.get(s.name) ?? s.dir,
+      windows: s.windowCount,
+    }));
+  }
+
+  switchSession(name: string, clientTty?: string): void {
+    this.tmux.switchClient(name, clientTty ? { clientTty } : undefined);
+  }
+
+  getCurrentSession(): string | null {
+    return this.tmux.getCurrentSession();
+  }
+
+  getSessionDir(name: string): string {
+    return this.tmux.getSessionDir(name);
+  }
+
+  getPaneCount(name: string): number {
+    return this.tmux.getPaneCount(name);
+  }
+
+  getClientTty(): string {
+    return this.tmux.getClientTty();
+  }
+
+  createSession(name?: string, dir?: string): void {
+    this.tmux.newSession({ name, cwd: dir });
+  }
+
+  killSession(name: string): void {
+    this.tmux.killSession(name);
+  }
+
+  setupHooks(serverHost: string, serverPort: number): void {
+    const base = `http://${serverHost}:${serverPort}`;
+    const hookPost = (path: string, data?: string) => {
+      // #{q:...} escapes shell metacharacters in each tmux variable.
+      // Use escaped double quotes (\") inside the outer run-shell "..." to wrap the body.
+      const body = data ? ` -d \\"${data}\\"` : "";
+      return `run-shell -b "curl -s -o /dev/null -X POST ${base}${path}${body} >/dev/null 2>&1 || true"`;
+    };
+    // tmux expands #{} formats at hook-fire time — no need for $(tmux display-message)
+    // #{q:...} shell-escapes each value to prevent injection from session names etc.
+    const focusCmd = hookPost("/focus", "#{q:client_tty}|#{q:session_name}|#{q:window_id}");
+    const refreshCmd = hookPost("/refresh");
+    const resizeCmd = hookPost("/resize-sidebars");
+    const resizePaneCmd = hookPost(
+      "/resize-sidebars",
+      "#{q:pane_id}|#{q:session_name}|#{q:window_id}|#{q:pane_width}|#{q:window_width}",
+    );
+    const ensureCmd = hookPost(
+      "/ensure-sidebar",
+      "#{q:client_tty}|#{q:session_name}|#{q:window_id}",
+    );
+
+    // client-session-changed: update focus AND ensure sidebar in the new session's window
+    this.tmux.setGlobalHook("client-session-changed", `${focusCmd} ; ${ensureCmd}`);
+    this.tmux.setGlobalHook("session-created", refreshCmd);
+    this.tmux.setGlobalHook("session-closed", refreshCmd);
+    this.tmux.setGlobalHook("client-resized", resizeCmd);
+    this.tmux.setGlobalHook("after-select-window", ensureCmd);
+    this.tmux.setGlobalHook("after-new-window", ensureCmd);
+    this.tmux.setGlobalHook("after-resize-pane", resizePaneCmd);
+  }
+
+  cleanupHooks(): void {
+    this.tmux.unsetGlobalHook("client-session-changed");
+    this.tmux.unsetGlobalHook("session-created");
+    this.tmux.unsetGlobalHook("session-closed");
+    this.tmux.unsetGlobalHook("client-resized");
+    this.tmux.unsetGlobalHook("after-select-window");
+    this.tmux.unsetGlobalHook("after-new-window");
+    this.tmux.unsetGlobalHook("after-resize-pane");
+  }
+
+  getAllPaneCounts(): Map<string, number> {
+    return this.tmux.getAllPaneCounts();
+  }
+
+  listActiveWindows(): ActiveWindow[] {
+    return this.tmux
+      .listWindows()
+      .filter((w) => w.active && w.sessionName !== STASH_SESSION)
+      .map((w) => ({ id: w.id, sessionName: w.sessionName, active: w.active }));
+  }
+
+  getCurrentWindowId(): string | null {
+    return this.tmux.getCurrentWindowId() || null;
+  }
+
+  cleanupSidebar(): void {
+    // Kill the stash session used for hiding sidebar panes
+    this.tmux.killSession(STASH_SESSION);
+  }
+
+  listSidebarPanes(sessionName?: string): SidebarPane[] {
+    const panes = sessionName
+      ? this.tmux.listPanes({ scope: "session", target: sessionName })
+      : this.tmux.listPanes();
+    const windowWidths = new Map<string, number>();
+    for (const pane of panes) {
+      windowWidths.set(
+        pane.windowId,
+        Math.max(windowWidths.get(pane.windowId) ?? 0, pane.right + 1),
+      );
+    }
+
+    return panes
+      .filter((p) => p.title === SIDEBAR_PANE_TITLE && p.sessionName !== STASH_SESSION)
+      .map((p) => ({
+        paneId: p.id,
+        sessionName: p.sessionName,
+        windowId: p.windowId,
+        width: p.width,
+        windowWidth: windowWidths.get(p.windowId),
+      }));
+  }
+
+  /** Ensure the invisible stash session exists for hiding sidebar panes */
+  private ensureStash(): void {
+    const r = this.tmux.run(["has-session", "-t", STASH_SESSION]);
+    if (!r.ok) {
+      this.tmux.rawRun(["new-session", "-d", "-s", STASH_SESSION, "-x", "80", "-y", "24"]);
+    }
+  }
+
+  spawnSidebar(
+    sessionName: string,
+    windowId: string,
+    width: number,
+    position: SidebarPosition,
+  ): string | null {
+    // Find the edge pane to split against
+    const panes = this.tmux.listPanes({ scope: "window", target: windowId });
+    plog("spawnSidebar", { windowId, paneCount: panes.length });
+    if (panes.length === 0) return null;
+
+    const targetPane =
+      position === "left"
+        ? panes.reduce((a, b) => (a.left <= b.left ? a : b))
+        : panes.reduce((a, b) => (a.right >= b.right ? a : b));
+
+    // --- Try to restore a stashed sidebar pane ---
+    try {
+      const stashPanes = this.tmux.listPanes({ scope: "session", target: STASH_SESSION });
+      const stashedPane = stashPanes.find((p) => p.title === SIDEBAR_PANE_TITLE);
+      if (stashedPane) {
+        plog("spawnSidebar: restoring from stash", {
+          paneId: stashedPane.id,
+          target: targetPane.id,
+        });
+        const joinFlag = position === "left" ? "-hb" : "-h";
+        this.tmux.rawRun([
+          "join-pane",
+          joinFlag,
+          "-f",
+          "-l",
+          String(width),
+          "-s",
+          stashedPane.id,
+          "-t",
+          targetPane.id,
+        ]);
+        this.tmux.setPaneTitle(stashedPane.id, SIDEBAR_PANE_TITLE);
+        // Do NOT selectPane here — same as fresh spawns. The TUI's
+        // restoreTerminalModes fires on focus-in after join-pane, generating
+        // capability query responses. Refocusing the main pane immediately
+        // causes those responses to leak as garbage escape sequences.
+        return stashedPane.id;
+      }
+    } catch {
+      /* stash session doesn't exist yet — spawn fresh */
+    }
+
+    // --- No stashed pane, spawn fresh ---
+    plog("spawnSidebar: spawning new", { target: targetPane.id, width, position });
+    const newPane = this.tmux.splitWindow({
+      target: targetPane.id,
+      direction: "horizontal",
+      before: position === "left",
+      fullWindow: true,
+      size: width,
+      command: `REFOCUS_WINDOW=${windowId} exec tt agentboard tui`,
+    });
+
+    if (!newPane) {
+      plog("spawnSidebar: splitWindow FAILED");
+      return null;
+    }
+
+    this.tmux.setPaneTitle(newPane.id, SIDEBAR_PANE_TITLE);
+    // Do NOT selectPane here for fresh spawns — the TUI's refocusMainPane()
+    // handles it after terminal capability detection finishes. Refocusing
+    // immediately causes capability query responses (DECRPM, DA1, Kitty
+    // graphics) to be routed to the main pane as garbage escape sequences.
+    return newPane.id;
+  }
+
+  hideSidebar(paneId: string): void {
+    this.ensureStash();
+    // Ensure the stash window is large enough to accept another pane.
+    // join-pane fails with "pane too small" when stash panes fill up.
+    this.tmux.rawRun(["resize-window", "-t", `${STASH_SESSION}:`, "-x", "200", "-y", "200"]);
+    plog("hideSidebar: stashing pane", { paneId });
+    this.tmux.rawRun(["join-pane", "-d", "-s", paneId, "-t", `${STASH_SESSION}:`]);
+  }
+
+  killSidebarPane(paneId: string): void {
+    this.tmux.killPane(paneId);
+  }
+
+  resizeSidebarPane(paneId: string, width: number): void {
+    this.tmux.resizePane(paneId, { width });
+  }
+}

package/plugins/tt-agentboard/packages/mux-tmux/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"]
+}

package/plugins/tt-agentboard/packages/runtime/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@tt-agentboard/runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/plugins/tt-agentboard/packages/runtime/src/agents/tracker.ts

@@ -0,0 +1,233 @@
+import type { AgentEvent } from "../contracts/agent";
+import { TERMINAL_STATUSES } from "../contracts/agent";
+
+const MAX_EVENT_TIMESTAMPS = 30;
+const TERMINAL_PRUNE_MS = 5 * 60 * 1000;
+
+const STATUS_PRIORITY: Record<string, number> = {
+  running: 5,
+  error: 4,
+  interrupted: 3,
+  waiting: 2,
+  done: 1,
+  idle: 0,
+};
+
+export function instanceKey(agent: string, threadId?: string): string {
+  return threadId ? `${agent}:${threadId}` : agent;
+}
+
+export class AgentTracker {
+  // Outer key: session name, inner key: instance key (agent or agent:threadId)
+  private instances = new Map<string, Map<string, AgentEvent>>();
+  private eventTimestamps = new Map<string, number[]>();
+  // Per-instance unseen tracking: "session\0instanceKey"
+  private unseenInstances = new Set<string>();
+  private active = new Set<string>();
+  // Pinned instances: agents backed by a live pane process — exempt from pruning
+  private pinnedKeys = new Map<string, Set<string>>(); // session → Set<instanceKey>
+
+  private unseenKey(session: string, key: string): string {
+    return `${session}\0${key}`;
+  }
+
+  applyEvent(event: AgentEvent, options?: { seed?: boolean }): void {
+    const key = instanceKey(event.agent, event.threadId);
+
+    // Store instance
+    let sessionInstances = this.instances.get(event.session);
+    if (!sessionInstances) {
+      sessionInstances = new Map();
+      this.instances.set(event.session, sessionInstances);
+    }
+    sessionInstances.set(key, event);
+
+    // Track event timestamps
+    let timestamps = this.eventTimestamps.get(event.session);
+    if (!timestamps) {
+      timestamps = [];
+      this.eventTimestamps.set(event.session, timestamps);
+    }
+    timestamps.push(event.ts);
+    if (timestamps.length > MAX_EVENT_TIMESTAMPS) {
+      timestamps.splice(0, timestamps.length - MAX_EVENT_TIMESTAMPS);
+    }
+
+    // Per-instance unseen tracking
+    // Seeded events always mark as unseen (they represent state from before the user connected)
+    const ukey = this.unseenKey(event.session, key);
+    if (TERMINAL_STATUSES.has(event.status)) {
+      if (options?.seed || !this.active.has(event.session)) {
+        this.unseenInstances.add(ukey);
+      }
+    } else {
+      // Non-terminal status for this instance = user is interacting, mark seen
+      this.unseenInstances.delete(ukey);
+    }
+  }
+
+  /** Returns the most important agent state for backward compat */
+  getState(session: string): AgentEvent | null {
+    const sessionInstances = this.instances.get(session);
+    if (!sessionInstances || sessionInstances.size === 0) return null;
+
+    let best: AgentEvent | null = null;
+    let bestPriority = -1;
+    for (const event of sessionInstances.values()) {
+      const p = STATUS_PRIORITY[event.status] ?? 0;
+      if (p > bestPriority) {
+        bestPriority = p;
+        best = event;
+      }
+    }
+    return best;
+  }
+
+  /** Returns all agent instances for a session, with unseen flag stamped */
+  getAgents(session: string): AgentEvent[] {
+    const sessionInstances = this.instances.get(session);
+    if (!sessionInstances) return [];
+    return [...sessionInstances.values()]
+      .map((event) => {
+        const key = instanceKey(event.agent, event.threadId);
+        const isUnseen = this.unseenInstances.has(this.unseenKey(session, key));
+        return isUnseen ? { ...event, unseen: true } : event;
+      })
+      .sort((a, b) => b.ts - a.ts);
+  }
+
+  /** Returns recent event timestamps for sparkline rendering */
+  getEventTimestamps(session: string): number[] {
+    return this.eventTimestamps.get(session) ?? [];
+  }
+
+  markSeen(session: string): boolean {
+    const hadUnseen = this.isUnseen(session);
+    if (!hadUnseen) return false;
+
+    // Clear unseen flags for all instances — keep the instances themselves
+    // (pruneTerminal will remove seen terminal instances after timeout)
+    const sessionInstances = this.instances.get(session);
+    if (sessionInstances) {
+      for (const key of sessionInstances.keys()) {
+        this.unseenInstances.delete(this.unseenKey(session, key));
+      }
+    }
+    return true;
+  }
+
+  dismiss(session: string, agent: string, threadId?: string): boolean {
+    const sessionInstances = this.instances.get(session);
+    if (!sessionInstances) return false;
+
+    const key = instanceKey(agent, threadId);
+    const removed = sessionInstances.delete(key);
+    if (!removed) return false;
+
+    this.unseenInstances.delete(this.unseenKey(session, key));
+    if (sessionInstances.size === 0) {
+      this.instances.delete(session);
+    }
+    return true;
+  }
+
+  pruneStuck(timeoutMs: number): void {
+    const now = Date.now();
+    for (const [session, sessionInstances] of this.instances) {
+      for (const [key, event] of sessionInstances) {
+        if (event.status === "running" && now - event.ts > timeoutMs) {
+          if (this.isPinned(session, key)) continue;
+          sessionInstances.delete(key);
+          this.unseenInstances.delete(this.unseenKey(session, key));
+        }
+      }
+      if (sessionInstances.size === 0) {
+        this.instances.delete(session);
+      }
+    }
+  }
+
+  /** Auto-prune terminal instances older than timeout, but only if instance is not unseen or pinned */
+  pruneTerminal(): void {
+    const now = Date.now();
+    for (const [session, sessionInstances] of this.instances) {
+      for (const [key, event] of sessionInstances) {
+        if (!TERMINAL_STATUSES.has(event.status)) continue;
+        const ukey = this.unseenKey(session, key);
+        if (this.unseenInstances.has(ukey)) continue; // Don't prune unseen — user hasn't looked yet
+        if (this.isPinned(session, key)) continue; // Don't prune agents backed by live panes
+        if (now - event.ts > TERMINAL_PRUNE_MS) {
+          sessionInstances.delete(key);
+        }
+      }
+      if (sessionInstances.size === 0) {
+        this.instances.delete(session);
+      }
+    }
+  }
+
+  isUnseen(session: string): boolean {
+    // Session is unseen if any instance within it is unseen
+    const sessionInstances = this.instances.get(session);
+    if (!sessionInstances) return false;
+    for (const key of sessionInstances.keys()) {
+      if (this.unseenInstances.has(this.unseenKey(session, key))) return true;
+    }
+    return false;
+  }
+
+  getUnseen(): string[] {
+    // Derive session-level unseen from per-instance tracking
+    const sessions = new Set<string>();
+    for (const ukey of this.unseenInstances) {
+      sessions.add(ukey.split("\0")[0]!);
+    }
+    return [...sessions];
+  }
+
+  handleFocus(session: string): boolean {
+    this.active.clear();
+    this.active.add(session);
+
+    const hadUnseen = this.isUnseen(session);
+    if (hadUnseen) {
+      // Clear unseen flags — keep terminal instances visible (as "seen")
+      // pruneTerminal will clean them up after timeout
+      const sessionInstances = this.instances.get(session);
+      if (sessionInstances) {
+        for (const key of sessionInstances.keys()) {
+          this.unseenInstances.delete(this.unseenKey(session, key));
+        }
+      }
+    }
+    return hadUnseen;
+  }
+
+  setActiveSessions(sessions: string[]): void {
+    this.active.clear();
+    for (const s of sessions) this.active.add(s);
+  }
+
+  /** Update the set of pinned instance keys for a session (live pane-backed agents). */
+  setPinnedInstances(session: string | null, keys: string[]): void {
+    this.pinnedKeys.clear();
+    if (session && keys.length > 0) {
+      this.pinnedKeys.set(session, new Set(keys));
+    }
+  }
+
+  /** Update pinned instance keys for multiple sessions at once. */
+  setPinnedInstancesMulti(keysBySession: Map<string, string[]>): void {
+    this.pinnedKeys.clear();
+    for (const [session, keys] of keysBySession) {
+      if (keys.length > 0) {
+        this.pinnedKeys.set(session, new Set(keys));
+      }
+    }
+  }
+
+  /** Check if an instance is pinned (backed by a live pane process). */
+  isPinned(session: string, key: string): boolean {
+    return this.pinnedKeys.get(session)?.has(key) ?? false;
+  }
+}