@creativeintelligence/abbie 0.1.0

package/src/lib/windows/inventory.ts

@@ -0,0 +1,352 @@
+import * as nvim from "../nvim/index.js";
+import * as process from "../process/snapshot.js";
+import * as tmux from "../tmux/bridge.js";
+import type { AgentInfo, BufferInfo, WindowInfo, WindowState } from "./types.js";
+
+export interface InventoryOptions {
+  session?: string; // filter to specific tmux session
+  includeNvim?: boolean; // correlate nvim instances (default: true)
+  includeAgent?: boolean; // detect agent processes (default: true)
+  includeBuffers?: boolean; // fetch buffer list (default: false, expensive)
+}
+
+function normalizeTty(tty: string | null | undefined): string | null {
+  if (!tty) return null;
+  const trimmed = tty.trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith("/dev/")) return trimmed.slice("/dev/".length);
+  return trimmed;
+}
+
+function guessPanePidFromTty(
+  paneTty: string | null,
+  snapshot: Map<number, process.ProcessInfo>,
+): number | null {
+  const normalizedPaneTty = normalizeTty(paneTty);
+  if (!normalizedPaneTty) return null;
+
+  const matching: process.ProcessInfo[] = [];
+  for (const [, info] of snapshot) {
+    if (normalizeTty(info.tty) === normalizedPaneTty) {
+      matching.push(info);
+    }
+  }
+
+  if (matching.length === 0) return null;
+
+  const pidSet = new Set(matching.map((p) => p.pid));
+  const roots = matching.filter((p) => !pidSet.has(p.ppid));
+  const candidates = roots.length > 0 ? roots : matching;
+
+  const shells = new Set(["zsh", "bash", "fish", "sh", "nu", "pwsh", "tcsh", "csh", "ksh", "dash"]);
+  candidates.sort((a, b) => {
+    const aShell = shells.has(a.cmd.toLowerCase()) ? 0 : 1;
+    const bShell = shells.has(b.cmd.toLowerCase()) ? 0 : 1;
+    if (aShell !== bShell) return aShell - bShell;
+    return a.pid - b.pid;
+  });
+
+  return candidates[0]?.pid ?? null;
+}
+
+function extractSessionId(args: string): string | undefined {
+  const match = args.match(/(?:^|\s)--session-id(?:=|\s+)([^\s]+)/);
+  return match?.[1];
+}
+
+function extractIssue(args: string): string | undefined {
+  const match = args.match(/\b[A-Z][A-Z0-9]{1,9}-\d+\b/);
+  return match?.[0];
+}
+
+function depthFromRoot(
+  rootPid: number,
+  pid: number,
+  snapshot: Map<number, process.ProcessInfo>,
+  maxDepth = 50,
+): number {
+  if (pid === rootPid) return 0;
+
+  let depth = 0;
+  let current = pid;
+  const visited = new Set<number>();
+
+  while (depth < maxDepth) {
+    if (current === rootPid) return depth;
+    if (visited.has(current)) break;
+    visited.add(current);
+
+    const info = snapshot.get(current);
+    if (!info) break;
+    current = info.ppid;
+    depth++;
+  }
+
+  return depth;
+}
+
+function toBufferInfo(buf: unknown): BufferInfo {
+  const record: Record<string, unknown> =
+    typeof buf === "object" && buf !== null ? (buf as Record<string, unknown>) : {};
+
+  const name = typeof record.name === "string" ? record.name : "";
+  const filetype = typeof record.filetype === "string" ? record.filetype : "";
+  const lineCount =
+    typeof record.lineCount === "number"
+      ? record.lineCount
+      : typeof record.linecount === "number"
+        ? record.linecount
+        : 0;
+
+  const cursor =
+    typeof record.cursor === "object" &&
+    record.cursor !== null &&
+    typeof (record.cursor as Record<string, unknown>).line === "number" &&
+    typeof (record.cursor as Record<string, unknown>).col === "number"
+      ? ({
+          line: (record.cursor as Record<string, unknown>).line as number,
+          col: (record.cursor as Record<string, unknown>).col as number,
+        } satisfies { line: number; col: number })
+      : undefined;
+
+  return {
+    name,
+    path: name,
+    modified: Boolean(record.modified),
+    filetype,
+    lineCount,
+    cursor,
+  };
+}
+
+function detectAgentForPane(
+  panePid: number,
+  snapshot: Map<number, process.ProcessInfo>,
+  tree: Map<number, number[]>,
+): AgentInfo | null {
+  if (panePid <= 0) return null;
+
+  const candidatePids = process.findDescendants(panePid, tree, snapshot, (p) => {
+    return process.detectAgentType(p) !== null;
+  });
+
+  // Include root pid if pane is running the agent directly.
+  const paneInfo = snapshot.get(panePid);
+  if (paneInfo && process.detectAgentType(paneInfo)) {
+    candidatePids.push(panePid);
+  }
+
+  if (candidatePids.length === 0) return null;
+
+  let best: {
+    pid: number;
+    depth: number;
+    type: AgentInfo["type"];
+    info: process.ProcessInfo;
+  } | null = null;
+
+  for (const pid of candidatePids) {
+    const info = snapshot.get(pid);
+    if (!info) continue;
+
+    const type = process.detectAgentType(info);
+    if (!type) continue;
+
+    const depth = depthFromRoot(panePid, pid, snapshot);
+    if (!best || depth > best.depth || (depth === best.depth && pid < best.pid)) {
+      best = { pid, depth, type, info };
+    }
+  }
+
+  if (!best) return null;
+
+  return {
+    type: best.type,
+    pid: best.pid,
+    sessionId: extractSessionId(best.info.args),
+    issue: extractIssue(best.info.args),
+  };
+}
+
+async function buildWindowState(params: {
+  sessionName: string;
+  windowIndex: number;
+  windowName: string;
+  pane: tmux.TmuxPane;
+  snapshot: Map<number, process.ProcessInfo>;
+  tree: Map<number, number[]>;
+  options: Required<Pick<InventoryOptions, "includeNvim" | "includeAgent" | "includeBuffers">>;
+}): Promise<WindowState> {
+  const { sessionName, windowIndex, windowName, pane, snapshot, tree, options } = params;
+
+  const paneId = (await tmux.getPaneId(windowIndex, pane.index, sessionName)) ?? "";
+  const paneTty = (await tmux.getPaneTty(windowIndex, pane.index, sessionName)) ?? "";
+  const panePid = guessPanePidFromTty(paneTty, snapshot) ?? -1;
+
+  const window: WindowInfo = {
+    session: sessionName,
+    window: windowIndex,
+    windowName,
+    pane: pane.index,
+    paneId,
+    panePid,
+    paneTty,
+    title: pane.currentCommand,
+    cwd: pane.currentPath,
+    active: pane.active,
+    size: { cols: pane.width, rows: pane.height },
+  };
+
+  const agent = options.includeAgent ? detectAgentForPane(panePid, snapshot, tree) : null;
+
+  if (!options.includeNvim) {
+    return { window, nvim: null, agent, buffers: [] };
+  }
+
+  const nvimState: NonNullable<WindowState["nvim"]> = {
+    available: false,
+    pid: null,
+    serverAddr: null,
+    discoveryMethod: null,
+    currentBuffer: null,
+  };
+
+  let buffers: BufferInfo[] = [];
+
+  if (panePid > 0) {
+    let nvimPid = nvim.findNvimPidForWindow(panePid, snapshot, tree);
+
+    // If the pane is running nvim directly (no shell), treat it as the nvim pid.
+    if (!nvimPid) {
+      const rootInfo = snapshot.get(panePid);
+      if (rootInfo && process.isNvimProcess(rootInfo)) {
+        nvimPid = panePid;
+      }
+    }
+
+    if (nvimPid) {
+      nvimState.available = true;
+      nvimState.pid = nvimPid;
+
+      const discovery = await nvim.discoverNvimServerAddress(nvimPid, snapshot);
+      nvimState.serverAddr = discovery?.addr ?? null;
+      nvimState.discoveryMethod = discovery?.method ?? null;
+
+      if (options.includeBuffers && nvimState.serverAddr) {
+        const [listed, current] = await Promise.all([
+          nvim.listBuffers(nvimState.serverAddr),
+          nvim.getCurrentBufferInfo(nvimState.serverAddr),
+        ]);
+
+        buffers = (listed ?? []).map(toBufferInfo);
+        nvimState.currentBuffer = current ? toBufferInfo(current) : null;
+      }
+    }
+  }
+
+  return { window, nvim: nvimState, agent, buffers };
+}
+
+/**
+ * Get complete inventory of all workspace windows.
+ * Correlates tmux panes → nvim instances → agent processes.
+ */
+export async function inventory(options?: InventoryOptions): Promise<WindowState[]> {
+  const {
+    session,
+    includeNvim = true,
+    includeAgent = true,
+    includeBuffers = false,
+  } = options || {};
+
+  const tmuxRunning = await tmux.isRunning();
+  if (!tmuxRunning) return [];
+
+  const sessions = await tmux.listSessions();
+  const targetSessions = session ? sessions.filter((s) => s.name === session) : sessions;
+  if (session && targetSessions.length === 0) return [];
+
+  const snapshot = await process.getProcessSnapshot();
+  const tree = process.buildProcessTree(snapshot);
+
+  const states: WindowState[] = [];
+
+  for (const s of targetSessions) {
+    const windows = await tmux.listWindows(s.name);
+
+    for (const w of windows) {
+      const panes = await tmux.listPanes(w.index, s.name);
+
+      for (const pane of panes) {
+        states.push(
+          await buildWindowState({
+            sessionName: s.name,
+            windowIndex: w.index,
+            windowName: w.name,
+            pane,
+            snapshot,
+            tree,
+            options: { includeNvim, includeAgent, includeBuffers },
+          }),
+        );
+      }
+    }
+  }
+
+  return states;
+}
+
+/**
+ * Get a single window's state by pane ID or session:window.pane reference.
+ */
+export async function getWindowState(
+  ref: string,
+  options?: Omit<InventoryOptions, "session">,
+): Promise<WindowState | null> {
+  const trimmed = ref.trim();
+  if (!trimmed) return null;
+
+  // Pane ID form: "%3"
+  if (trimmed.startsWith("%")) {
+    const states = await inventory({ ...(options || {}) });
+    return states.find((s) => s.window.paneId === trimmed) ?? null;
+  }
+
+  // session:window.pane form, e.g. "work:1.0"
+  const match = trimmed.match(/^([^:]+):(\d+)\.(\d+)$/);
+  if (!match) return null;
+
+  const sessionName = match[1];
+  const windowIndex = parseInt(match[2], 10);
+  const paneIndex = parseInt(match[3], 10);
+
+  const states = await inventory({ ...(options || {}), session: sessionName });
+  return states.find((s) => s.window.window === windowIndex && s.window.pane === paneIndex) ?? null;
+}
+
+/**
+ * Get the currently focused window's state.
+ */
+export async function getFocusedWindow(
+  options?: Omit<InventoryOptions, "session">,
+): Promise<WindowState | null> {
+  const tmuxRunning = await tmux.isRunning();
+  if (!tmuxRunning) return null;
+
+  const sessions = await tmux.listSessions();
+  const attachedSession = sessions.find((s) => s.attached);
+  if (!attachedSession) return null;
+
+  const windows = await tmux.listWindows(attachedSession.name);
+  const activeWindow = windows.find((w) => w.active);
+  if (!activeWindow) return null;
+
+  const panes = await tmux.listPanes(activeWindow.index, attachedSession.name);
+  const activePane = panes.find((p) => p.active);
+  if (!activePane) return null;
+
+  return getWindowState(
+    `${attachedSession.name}:${activeWindow.index}.${activePane.index}`,
+    options,
+  );
+}

package/src/lib/windows/types.ts

@@ -0,0 +1,46 @@
+// Window identification
+export interface WindowInfo {
+  session: string; // tmux session name
+  window: number; // window index
+  windowName: string; // window name
+  pane: number; // pane index
+  paneId: string; // tmux pane ID (e.g., "%3")
+  panePid: number; // pane's shell PID
+  paneTty: string; // pane's TTY (e.g., "/dev/ttys003")
+  title: string; // window title or current command
+  cwd: string; // current working directory
+  active: boolean; // is this the active pane
+  size: { cols: number; rows: number };
+}
+
+// Buffer information from nvim
+export interface BufferInfo {
+  name: string; // buffer name/path
+  path: string; // full file path
+  modified: boolean;
+  filetype: string;
+  lineCount: number;
+  cursor?: { line: number; col: number };
+}
+
+// Agent process information
+export interface AgentInfo {
+  type: "claude" | "codex" | "copilot" | "gemini";
+  pid: number;
+  sessionId?: string; // abbie session ID if known
+  issue?: string; // Linear issue if known
+}
+
+// Full window state with correlations
+export interface WindowState {
+  window: WindowInfo;
+  nvim: {
+    available: boolean;
+    pid: number | null;
+    serverAddr: string | null;
+    discoveryMethod: "argv" | "lsof" | null;
+    currentBuffer: BufferInfo | null;
+  } | null;
+  agent: AgentInfo | null;
+  buffers: BufferInfo[]; // all listed buffers in nvim
+}

package/src/lib.ts

@@ -0,0 +1,260 @@
+/**
+ * Programmatic API for abbie CLI.
+ *
+ * This module provides clean library exports for using agents
+ * functionality without the CLI wrapper.
+ *
+ * @example
+ * ```typescript
+ * import { getAllSessions, createSession, EventStore, reportStart, reportComplete } from 'agents';
+ *
+ * // Planning sessions
+ * const sessions = getAllSessions('/path/to/plans');
+ * const session = createSession('/path/to/plans', 'arbor', 'feature-slug');
+ *
+ * // Event sourcing
+ * const events = new EventStore();
+ * events.append(createEvent.sessionStart('hostagent-20251222-123456-abc1', 'claude', {
+ *   project: 'hostagent',
+ *   issue: 'ZO-123'
+ * }));
+ *
+ * // Heartbeat/liveness
+ * const heartbeat = new HeartbeatManager();
+ * heartbeat.register('hostagent-20251222-123456-abc1', 'claude', {
+ *   project: 'hostagent'
+ * });
+ *
+ * // Resource semaphores
+ * const resources = createResourceManager();
+ * const lease = resources.acquire('codex_api', sessionId, 'claude');
+ *
+ * // Multi-agent session mining
+ * const miner = getSessionMiner();
+ * const recentSessions = miner.getRecentSessions('hostagent');
+ *
+ * // Auto-discovery
+ * const items = await discoverWork({
+ *   cwd: process.cwd(),
+ *   project: 'hostagent',
+ *   dryRun: true,
+ *   limit: 5,
+ *   staleDays: 14,
+ *   linear: { enabled: true, limit: 5 }
+ * });
+ *
+ * // Spawn agent
+ * await spawnAgent(items[0], {
+ *   dryRun: false,
+ *   cwd: process.cwd(),
+ *   project: 'hostagent',
+ *   sessionId: 'hostagent-auto-123',
+ *   resources
+ * });
+ *
+ * // Backlog management
+ * const backlog = getBacklogManager();
+ * backlog.add({
+ *   type: 'issue',
+ *   ref: 'ZO-123',
+ *   title: 'Fix auth bug',
+ *   project: 'hostagent',
+ *   priority: 1,
+ *   source: 'linear'
+ * });
+ *
+ * // Unified lifecycle reporting (Convex reports + Slack + messages)
+ * const result = await reportStart('beginning loop on arbor', { dm: true });
+ * // ... do work ...
+ * await reportComplete('feature implemented', { confidence: 9 });
+ * ```
+ */
+
+// Active session management (spawn + track running agents)
+export {
+  type ActiveAgentType,
+  type ActiveSession,
+  ActiveSessionManager,
+  getActiveSessionManager,
+  type StartSessionOptions,
+  type StartSessionResult,
+} from "./lib/active-sessions.js";
+// Agent adapters (extensible agent CLI abstraction)
+export {
+  AGENT_ADAPTERS,
+  AGENT_METADATA,
+  type AgentAdapter,
+  type AgentCommandContext,
+  type AgentCommandResult,
+  ALL_AGENTS,
+  getAgentAdapter,
+  getAvailableAgents,
+} from "./lib/agent-adapters.js";
+// Multi-agent session mining
+export {
+  type AgentSession,
+  AgentSessionMiner,
+  getSessionMiner,
+} from "./lib/agent-sessions.js";
+// Auto-discovery and execution
+export {
+  type DiscoveryOptions,
+  type DiscoveryResult,
+  discoverWork,
+  type WorkItem,
+  type WorkSource,
+} from "./lib/auto/discover.js";
+export {
+  analyzeCodebase,
+  analyzeGitTrajectory,
+  type IdeatedWork,
+  type IdeationResult,
+  ideatedToWorkItem,
+  ideateWork,
+  synthesizeWork,
+} from "./lib/auto/ideate.js";
+export {
+  decideAgent,
+  type SpawnOptions,
+  type SpawnRequest,
+  type SpawnResult,
+  spawnAgent,
+  spawnWorkItems,
+} from "./lib/auto/spawn.js";
+export {
+  type LoopConfig,
+  readLoopConfig,
+  resolveLinearApiKey,
+  resolveLinearApiKeyAsync,
+  type WorkspaceResolution,
+} from "./lib/auto/workspace.js";
+// Backlog management
+export {
+  addBacklogItem,
+  type BacklogItem,
+  BacklogManager,
+  type BacklogStatus,
+  type ClaimResult,
+  claimBacklogItem,
+  getBacklogManager,
+} from "./lib/backlog.js";
+// Errors
+export {
+  AgentsError,
+  errorToExitCode,
+  InvalidProjectError,
+  InvalidSessionError,
+  type JsonError,
+  SessionExistsError,
+  SessionNotFoundError,
+  toJsonError,
+} from "./lib/errors.js";
+// Event sourcing
+export {
+  type BaseEvent,
+  createEvent,
+  EventStore,
+  type EventType,
+  generateSessionId,
+  type PreviewCreatedEvent,
+  type ResourceAcquiredEvent,
+  type ResourceReleasedEvent,
+  type SessionBlockedEvent,
+  type SessionCheckpointEvent,
+  type SessionCompleteEvent,
+  type SessionEvent,
+  type SessionHeartbeatEvent,
+  type SessionStartEvent,
+  type TaskCompleteEvent,
+  type TaskStartEvent,
+} from "./lib/events.js";
+// Heartbeat/liveness
+export {
+  type HeartbeatConfig,
+  HeartbeatManager,
+  type SessionLiveness,
+} from "./lib/heartbeat.js";
+// Hook discovery and management
+export {
+  type AgentPlatform,
+  ClaudeAdapter,
+  CodexAdapter,
+  CopilotAdapter,
+  discoverAllHooks,
+  generateMockPayload,
+  getAllHooks,
+  getConfigPaths,
+  getConfiguredPlatforms,
+  getHooksForPlatform,
+  type Hook,
+  type HookAdapter,
+  type HookDiscoveryError,
+  type HookEventType,
+  type HookRegistry,
+  type HookTestResult,
+  runHook,
+} from "./lib/hooks/index.js";
+// Managed abbie tmux session
+export {
+  ensureManagedSession,
+  getManagedSessionName,
+  hasProjectWindow,
+  listManagedWindows,
+} from "./lib/managed-session.js";
+// Panes broker protocol + client helper (local fanout for pane streaming)
+export * from "./lib/panes/index.js";
+// Unified lifecycle reporting (Convex reports + Slack + messages)
+export {
+  type AgentIdentity,
+  type BlockerType,
+  detectAgent,
+  generateTraceId,
+  getOrCreateTraceId,
+  type ReportAction,
+  type ReportOptions,
+  type ReportResult,
+  reportBlocked,
+  reportComplete,
+  reportProgress,
+  reportStart,
+} from "./lib/report.js";
+// Resource semaphores
+export {
+  createResourceManager,
+  DEFAULT_RESOURCES,
+  type ResourceConfig,
+  type ResourceLease,
+  ResourceManager,
+} from "./lib/resources.js";
+// Planning session management
+export {
+  createSession,
+  generateSlug,
+  getAllSessions,
+  getSession,
+  type SessionMetadata,
+} from "./lib/session-manager.js";
+// SQLite-backed session state (device-aware)
+export {
+  type CleanupSessionStateOptions,
+  type CleanupSessionStateResult,
+  type EndSessionStateOptions,
+  type InitSessionStateOptions,
+  type ListSessionStateOptions,
+  type SessionAgentType,
+  SessionStateManager,
+  type SessionStateRecord,
+  type SessionStateStatus,
+  type UpdateSessionStateOptions,
+} from "./lib/session-state.js";
+// Core agent types
+export {
+  AGENT_CAPABILITIES,
+  AGENTS,
+  Agent,
+  AgentCapability,
+  type AgentCapabilityType,
+  type AgentType,
+  DEFAULT_AGENT,
+  isValidAgent,
+} from "./lib/types.js";