@creativeintelligence/abbie 0.1.0

package/src/lib/tmux/context.ts

@@ -0,0 +1,380 @@
+/**
+ * tmux context builder.
+ * Builds a structured snapshot of the tmux workspace for agent injection.
+ */
+
+import * as bridge from "./bridge.js";
+import {
+  type FilterConfig,
+  type RedactMode,
+  redactContent,
+  shouldFilterCommand,
+  shouldFilterPath,
+  shouldFilterSession,
+  shouldFilterWindow,
+} from "./redaction.js";
+
+/**
+ * Allowed commands for pane capture.
+ * Only capture panes running these commands.
+ */
+const ALLOWED_COMMANDS = new Set(["nvim", "vim", "vi", "zsh", "bash", "fish", "sh"]);
+
+/**
+ * Context options.
+ */
+export interface ContextOptions {
+  /** Maximum bytes in output (default: 200000) */
+  maxBytes?: number;
+  /** Maximum total lines across all panes (default: 4000) */
+  maxTotalLines?: number;
+  /** Maximum sessions to include (default: unlimited) */
+  maxSessions?: number;
+  /** Maximum windows per session (default: unlimited) */
+  maxWindowsPerSession?: number;
+  /** Maximum panes per window (default: unlimited) */
+  maxPanesPerWindow?: number;
+  /** Enable redaction (default: true) */
+  redact?: boolean;
+  /** Redaction mode (default: balanced) */
+  redactMode?: RedactMode;
+  /** Filter configuration */
+  filter?: FilterConfig;
+  /** Include all commands, not just shell+editor (default: false) */
+  includeAllCommands?: boolean;
+}
+
+/**
+ * Pane context.
+ */
+export interface PaneContext {
+  index: number;
+  active: boolean;
+  cwd: string;
+  cmd: string;
+  size: string;
+  screen: string;
+  redacted: boolean;
+}
+
+/**
+ * Window context.
+ */
+export interface WindowContext {
+  id: string;
+  index: number;
+  name: string;
+  active: boolean;
+  paneCount: number;
+  panes: PaneContext[];
+}
+
+/**
+ * Session context.
+ */
+export interface SessionContext {
+  name: string;
+  attached: boolean;
+  windows: WindowContext[];
+}
+
+/**
+ * Full tmux context.
+ */
+export interface TmuxContext {
+  generatedAt: string;
+  tmuxRunning: boolean;
+  truncated: boolean;
+  truncationReason?: string;
+  sessions: SessionContext[];
+}
+
+/**
+ * Build a structured tmux context.
+ */
+export async function buildContext(options: ContextOptions = {}): Promise<TmuxContext> {
+  const {
+    maxBytes = 200000,
+    maxTotalLines = 4000,
+    maxSessions,
+    maxWindowsPerSession,
+    maxPanesPerWindow,
+    redact = true,
+    redactMode = "balanced",
+    filter = {},
+    includeAllCommands = false,
+  } = options;
+
+  // Check if tmux is running
+  const tmuxRunning = await bridge.isRunning();
+  if (!tmuxRunning) {
+    return {
+      generatedAt: new Date().toISOString(),
+      tmuxRunning: false,
+      truncated: false,
+      sessions: [],
+    };
+  }
+
+  // Get all sessions
+  let sessions = await bridge.listSessions();
+
+  // Apply session filters
+  sessions = sessions.filter((s) => !shouldFilterSession(s.name, filter));
+
+  // Apply maxSessions limit
+  if (maxSessions !== undefined && sessions.length > maxSessions) {
+    sessions = sessions.slice(0, maxSessions);
+  }
+
+  const result: TmuxContext = {
+    generatedAt: new Date().toISOString(),
+    tmuxRunning: true,
+    truncated: false,
+    sessions: [],
+  };
+
+  let totalBytes = 0;
+  let totalLines = 0;
+  let truncated = false;
+  let truncationReason: string | undefined;
+
+  for (const session of sessions) {
+    // Check byte limit
+    if (totalBytes >= maxBytes) {
+      truncated = true;
+      truncationReason = "max-bytes";
+      break;
+    }
+
+    // Check line limit
+    if (totalLines >= maxTotalLines) {
+      truncated = true;
+      truncationReason = "max-lines";
+      break;
+    }
+
+    let windows = await bridge.listWindows(session.name);
+
+    // Apply window filters
+    windows = windows.filter((w) => !shouldFilterWindow(w.name, filter));
+
+    // Apply maxWindowsPerSession limit
+    if (maxWindowsPerSession !== undefined && windows.length > maxWindowsPerSession) {
+      windows = windows.slice(0, maxWindowsPerSession);
+    }
+
+    const sessionContext: SessionContext = {
+      name: session.name,
+      attached: session.attached,
+      windows: [],
+    };
+
+    for (const window of windows) {
+      // Check limits again
+      if (totalBytes >= maxBytes || totalLines >= maxTotalLines) {
+        truncated = true;
+        truncationReason = totalBytes >= maxBytes ? "max-bytes" : "max-lines";
+        break;
+      }
+
+      let panes = await bridge.listPanes(window.index, session.name);
+
+      // Filter by allowed commands unless includeAllCommands is true
+      if (!includeAllCommands) {
+        panes = panes.filter((p) => ALLOWED_COMMANDS.has(p.currentCommand));
+      }
+
+      // Apply path and command filters
+      panes = panes.filter((p) => {
+        if (shouldFilterPath(p.currentPath, filter)) return false;
+        if (shouldFilterCommand(p.currentCommand, filter)) return false;
+        return true;
+      });
+
+      // Apply maxPanesPerWindow limit
+      if (maxPanesPerWindow !== undefined && panes.length > maxPanesPerWindow) {
+        panes = panes.slice(0, maxPanesPerWindow);
+      }
+
+      // Skip windows with no eligible panes
+      if (panes.length === 0) {
+        continue;
+      }
+
+      const windowContext: WindowContext = {
+        id: window.id,
+        index: window.index,
+        name: window.name,
+        active: window.active,
+        paneCount: window.panes,
+        panes: [],
+      };
+
+      for (const pane of panes) {
+        // Check limits
+        if (totalBytes >= maxBytes || totalLines >= maxTotalLines) {
+          truncated = true;
+          truncationReason = totalBytes >= maxBytes ? "max-bytes" : "max-lines";
+          break;
+        }
+
+        // Capture the visible screen (based on pane height)
+        const capturedContent = await bridge.capturePane(window.index, pane.index, {
+          session: session.name,
+          lines: pane.height,
+        });
+
+        let screenContent = capturedContent;
+        let wasRedacted = false;
+
+        // Apply redaction
+        if (redact) {
+          const redactionResult = redactContent(capturedContent, redactMode);
+          screenContent = redactionResult.content;
+          wasRedacted = redactionResult.wasRedacted;
+        }
+
+        // Calculate bytes and lines
+        const contentBytes = Buffer.byteLength(screenContent, "utf-8");
+        const contentLines = screenContent.split("\n").length;
+
+        // Check if adding this would exceed limits
+        if (totalBytes + contentBytes > maxBytes) {
+          // Truncate content to fit
+          const remainingBytes = maxBytes - totalBytes;
+          screenContent = truncateToBytes(screenContent, remainingBytes);
+          truncated = true;
+          truncationReason = "max-bytes";
+        }
+
+        if (totalLines + contentLines > maxTotalLines) {
+          // Truncate lines to fit
+          const remainingLines = maxTotalLines - totalLines;
+          const lines = screenContent.split("\n");
+          screenContent = lines.slice(0, remainingLines).join("\n");
+          truncated = true;
+          truncationReason = "max-lines";
+        }
+
+        totalBytes += Buffer.byteLength(screenContent, "utf-8");
+        totalLines += screenContent.split("\n").length;
+
+        const paneContext: PaneContext = {
+          index: pane.index,
+          active: pane.active,
+          cwd: pane.currentPath,
+          cmd: pane.currentCommand,
+          size: `${pane.width}x${pane.height}`,
+          screen: screenContent,
+          redacted: wasRedacted,
+        };
+
+        windowContext.panes.push(paneContext);
+      }
+
+      if (windowContext.panes.length > 0) {
+        sessionContext.windows.push(windowContext);
+      }
+    }
+
+    if (sessionContext.windows.length > 0) {
+      result.sessions.push(sessionContext);
+    }
+  }
+
+  result.truncated = truncated;
+  if (truncationReason) {
+    result.truncationReason = truncationReason;
+  }
+
+  return result;
+}
+
+/**
+ * Truncate a string to a maximum number of bytes.
+ */
+function truncateToBytes(str: string, maxBytes: number): string {
+  const buf = Buffer.from(str, "utf-8");
+  if (buf.length <= maxBytes) {
+    return str;
+  }
+
+  // Binary search for the right length
+  let low = 0;
+  let high = str.length;
+
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const slice = str.slice(0, mid);
+    if (Buffer.byteLength(slice, "utf-8") <= maxBytes) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  return str.slice(0, low);
+}
+
+/**
+ * Escape XML special characters.
+ */
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Serialize context to XML.
+ */
+export function toXml(context: TmuxContext): string {
+  const lines: string[] = [];
+
+  lines.push(
+    `<tmux_context generated_at="${escapeXml(context.generatedAt)}" tmux_running="${context.tmuxRunning}" truncated="${context.truncated}"${context.truncationReason ? ` truncation_reason="${escapeXml(context.truncationReason)}"` : ""}>`,
+  );
+
+  for (const session of context.sessions) {
+    lines.push(`  <session name="${escapeXml(session.name)}" attached="${session.attached}">`);
+
+    for (const window of session.windows) {
+      lines.push(
+        `    <window id="${escapeXml(window.id)}" index="${window.index}" name="${escapeXml(window.name)}" active="${window.active}" panes="${window.paneCount}">`,
+      );
+
+      for (const pane of window.panes) {
+        lines.push(
+          `      <pane index="${pane.index}" active="${pane.active}" cwd="${escapeXml(pane.cwd)}" cmd="${escapeXml(pane.cmd)}" size="${pane.size}">`,
+        );
+        lines.push(`        <screen redacted="${pane.redacted}">`);
+        // Indent screen content and escape
+        const screenLines = pane.screen.split("\n");
+        for (const screenLine of screenLines) {
+          lines.push(`          ${escapeXml(screenLine)}`);
+        }
+        lines.push("        </screen>");
+        lines.push("      </pane>");
+      }
+
+      lines.push("    </window>");
+    }
+
+    lines.push("  </session>");
+  }
+
+  lines.push("</tmux_context>");
+
+  return lines.join("\n");
+}
+
+/**
+ * Serialize context to JSON.
+ */
+export function toJson(context: TmuxContext): string {
+  return JSON.stringify(context, null, 2);
+}

package/src/lib/tmux/index.ts

@@ -0,0 +1,46 @@
+/**
+ * tmux module - bridge and context building for agent prompts.
+ */
+
+// Core bridge primitives
+export * from "./bridge.js";
+
+// Context building
+export {
+  buildContext,
+  type ContextOptions,
+  type PaneContext,
+  type SessionContext,
+  type TmuxContext,
+  toJson,
+  toXml,
+  type WindowContext,
+} from "./context.js";
+// Agent ↔ pane mapping
+export {
+  type AgentPaneMapping,
+  correlateAgentsToPanes,
+  detectAgentType,
+  extractProjectFromPath,
+  getAllPanes,
+  getFocusedPane,
+  isAgentProcess,
+  type MapResult,
+  type PaneLocation,
+  pathsMatch,
+  type UnmappedPane,
+} from "./map.js";
+// Redaction utilities
+export {
+  type FilterConfig,
+  isSensitiveCommand,
+  type RedactMode,
+  redactContent,
+  redactLine,
+  redactTokens,
+  shouldFilterCommand,
+  shouldFilterPath,
+  shouldFilterSession,
+  shouldFilterWindow,
+  shouldRedactLine,
+} from "./redaction.js";

package/src/lib/tmux/map.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import { detectAgentType, extractProjectFromPath, isAgentProcess, pathsMatch } from "./map.js";
+
+describe("isAgentProcess", () => {
+  test("detects claude", () => {
+    expect(isAgentProcess("claude")).toBe(true);
+    expect(isAgentProcess("Claude")).toBe(true);
+  });
+
+  test("detects codex", () => {
+    expect(isAgentProcess("codex")).toBe(true);
+    expect(isAgentProcess("Codex")).toBe(true);
+  });
+
+  test("detects copilot", () => {
+    expect(isAgentProcess("copilot")).toBe(true);
+  });
+
+  test("detects gemini", () => {
+    expect(isAgentProcess("gemini")).toBe(true);
+  });
+
+  test("rejects non-agent processes", () => {
+    expect(isAgentProcess("nvim")).toBe(false);
+    expect(isAgentProcess("zsh")).toBe(false);
+    expect(isAgentProcess("bash")).toBe(false);
+    expect(isAgentProcess("node")).toBe(false);
+  });
+});
+
+describe("detectAgentType", () => {
+  test("returns agent type for agent processes", () => {
+    expect(detectAgentType("claude")).toBe("claude");
+    expect(detectAgentType("codex")).toBe("codex");
+    expect(detectAgentType("copilot")).toBe("copilot");
+    expect(detectAgentType("gemini")).toBe("gemini");
+  });
+
+  test("returns null for non-agent processes", () => {
+    expect(detectAgentType("nvim")).toBe(null);
+    expect(detectAgentType("zsh")).toBe(null);
+  });
+});
+
+describe("pathsMatch", () => {
+  test("matches identical paths", () => {
+    expect(pathsMatch("/Users/luke/project", "/Users/luke/project")).toBe(true);
+  });
+
+  test("handles trailing slashes", () => {
+    expect(pathsMatch("/Users/luke/project/", "/Users/luke/project")).toBe(true);
+    expect(pathsMatch("/Users/luke/project", "/Users/luke/project/")).toBe(true);
+    expect(pathsMatch("/Users/luke/project/", "/Users/luke/project/")).toBe(true);
+  });
+
+  test("expands ~ to home", () => {
+    const home = process.env.HOME || "/Users/luke";
+    expect(pathsMatch("~/project", `${home}/project`)).toBe(true);
+    expect(pathsMatch(`${home}/project`, "~/project")).toBe(true);
+  });
+
+  test("rejects different paths", () => {
+    expect(pathsMatch("/Users/luke/project1", "/Users/luke/project2")).toBe(false);
+    expect(pathsMatch("/Users/luke", "/Users/luke/project")).toBe(false);
+  });
+});
+
+describe("extractProjectFromPath", () => {
+  const home = process.env.HOME || "/Users/luke";
+
+  test("extracts from ~/Developer/apps/{project}", () => {
+    expect(extractProjectFromPath(`${home}/Developer/apps/arbor`)).toBe("arbor");
+    expect(extractProjectFromPath(`${home}/Developer/apps/arbor/src`)).toBe("arbor");
+    expect(extractProjectFromPath(`${home}/Developer/apps/koto-xyz/packages/design`)).toBe(
+      "koto-xyz",
+    );
+  });
+
+  test("extracts from ~/Developer/utils/{project}", () => {
+    expect(extractProjectFromPath(`${home}/Developer/utils/agents`)).toBe("agents");
+    expect(extractProjectFromPath(`${home}/Developer/utils/outline/src`)).toBe("outline");
+  });
+
+  test("extracts from ~/Developer/{project}", () => {
+    expect(extractProjectFromPath(`${home}/Developer/config`)).toBe("config");
+    expect(extractProjectFromPath(`${home}/Developer/forks/pi-mono`)).toBe("forks");
+  });
+
+  test("returns null for non-matching paths", () => {
+    expect(extractProjectFromPath("/tmp/project")).toBe(null);
+    expect(extractProjectFromPath("/var/log")).toBe(null);
+    expect(extractProjectFromPath(`${home}/Documents/project`)).toBe(null);
+  });
+
+  test("handles ~ prefix", () => {
+    expect(extractProjectFromPath("~/Developer/apps/arbor")).toBe("arbor");
+    expect(extractProjectFromPath("~/Developer/utils/agents")).toBe("agents");
+  });
+});