@dinhtungdu/watcher 1.0.0

package/src/ansiShell.ts

@@ -0,0 +1,104 @@
+import { loadSwitcherSnapshot } from './snapshot.js';
+import { groupPanes, moveSelection, renderSwitcherFrame, selectablePanes, SwitcherRenderState } from './switcherLayout.js';
+import { createStallTracker } from './stalled.js';
+import { activateAgentPane } from './activation.js';
+import { AgentPane } from './model.js';
+
+function terminalSize(): { width: number; height: number } {
+  return {
+    width: process.stdout.columns || Number(process.env.COLUMNS) || 100,
+    height: process.stdout.rows || Number(process.env.ROWS) || 30,
+  };
+}
+
+export async function runAnsiSwitcher(): Promise<void> {
+  // Render the accepted prototype-style ANSI frame directly under Bun.
+  let state: SwitcherRenderState = {
+    useColor: Boolean(process.stdout.isTTY && !process.env.NO_COLOR),
+    home: process.env.HOME,
+  };
+  const stallTracker = createStallTracker();
+  let currentPanes = [] as ReturnType<typeof selectablePanes>;
+  let pendingActivation: AgentPane | undefined;
+  let closed = false;
+  let resolveClosed: (() => void) | undefined;
+  const closedPromise = new Promise<void>((resolve) => {
+    resolveClosed = resolve;
+  });
+  let redrawInFlight = false;
+
+  async function redraw(): Promise<void> {
+    if (closed || redrawInFlight) return;
+    redrawInFlight = true;
+    try {
+      state.frameIndex = (state.frameIndex ?? 0) + 1;
+      const snapshot = await loadSwitcherSnapshot({ stallTracker });
+      currentPanes = selectablePanes(groupPanes(snapshot.panes, snapshot.now, state.home));
+      const { width, height } = terminalSize();
+      const frame = renderSwitcherFrame(snapshot, width, height, state).join('\n');
+      process.stdout.write(`\x1b[2J\x1b[H${frame}`);
+    } finally {
+      redrawInFlight = false;
+    }
+  }
+
+  function restoreTerminal(): void {
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    process.stdout.write('\x1b[?25h\x1b[?1049l');
+  }
+
+  function shutdown(): void {
+    if (closed) return;
+    closed = true;
+    clearInterval(interval);
+    process.stdout.off('resize', resizeHandler);
+    process.stdin.off('data', inputHandler);
+    process.stdin.pause();
+    process.off('SIGINT', sigintHandler);
+    restoreTerminal();
+    resolveClosed?.();
+  }
+
+  function sigintHandler(): void {
+    shutdown();
+  }
+
+  function resizeHandler(): void {
+    void redraw();
+  }
+
+  function inputHandler(buffer: Buffer): void {
+    const input = buffer.toString('utf8');
+    if (input === '\u0003' || input === 'q' || input === '\x1b') {
+      shutdown();
+      return;
+    }
+    if (input === '\x1b[A' || input === 'k') {
+      state.selectedPaneId = moveSelection(currentPanes, state.selectedPaneId, -1);
+      void redraw();
+      return;
+    }
+    if (input === '\x1b[B' || input === 'j') {
+      state.selectedPaneId = moveSelection(currentPanes, state.selectedPaneId, 1);
+      void redraw();
+      return;
+    }
+    if (input === '\r' || input === '\n') {
+      pendingActivation = currentPanes.find((pane) => pane.id === state.selectedPaneId) ?? currentPanes[0];
+      shutdown();
+    }
+  }
+
+  process.stdout.write('\x1b[?1049h\x1b[?25l');
+  if (process.stdin.isTTY) process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.on('data', inputHandler);
+  process.stdout.on('resize', resizeHandler);
+  process.once('SIGINT', sigintHandler);
+  const interval = setInterval(() => void redraw(), 250);
+  await redraw();
+
+  await closedPromise;
+
+  if (pendingActivation) await activateAgentPane(pendingActivation);
+}

package/src/cli.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env bun
+import { runAnsiSwitcher } from './ansiShell.js';
+import { loadSwitcherSnapshot } from './snapshot.js';
+import { renderSwitcherFrame } from './switcherLayout.js';
+import { stripAnsi } from './text.js';
+import { startDaemon } from './daemon.js';
+import { defaultSocketPath } from './ipc.js';
+import { runEventCommand } from './eventCommand.js';
+import { runIntegrationsInstall, runIntegrationsStatus } from './integrationsInstaller.js';
+
+export async function main(argv = process.argv.slice(2)): Promise<number> {
+  const [command, ...rest] = argv;
+  if (command === 'help' || command === '--help' || command === '-h') {
+    process.stdout.write('watcher - open the Watcher Agent Switcher\n\nCommands:\n  watcher\n  watcher daemon\n  watcher event [--quiet] <agent> <event>\n  watcher integrations install <agents...>\n  watcher integrations status\n');
+    return 0;
+  }
+  if (command === 'daemon') {
+    const detached = rest.includes('--detach');
+    const server = await startDaemon({ socketPath: defaultSocketPath() });
+    if (!detached) process.stdout.write(`watcher daemon listening on ${defaultSocketPath()}\n`);
+    await new Promise<void>((resolve) => {
+      const close = () => server.close(() => resolve());
+      process.once('SIGINT', close);
+      process.once('SIGTERM', close);
+    });
+    return 0;
+  }
+  if (command === 'event') {
+    return runEventCommand(rest);
+  }
+  if (command === 'integrations') {
+    const [subcommand, ...agents] = rest;
+    if (subcommand === 'install') {
+      try {
+        const result = await runIntegrationsInstall(agents);
+        process.stdout.write(result.output);
+        return result.code;
+      } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+      }
+    }
+    if (subcommand === 'status') {
+      process.stdout.write(await runIntegrationsStatus());
+      return 0;
+    }
+    process.stderr.write('Usage: watcher integrations install <agents...> | watcher integrations status\n');
+    return 2;
+  }
+  if (command) {
+    process.stderr.write(`Unknown command: ${command}\n`);
+    return 2;
+  }
+
+  if (process.env.WATCHER_TUI_SNAPSHOT || !process.stdin.isTTY || !process.stdout.isTTY) {
+    const snapshot = await loadSwitcherSnapshot();
+    const width = Number(process.env.COLUMNS) || process.stdout.columns || 100;
+    const height = Number(process.env.ROWS) || process.stdout.rows || 28;
+    const frame = renderSwitcherFrame(snapshot, width, height, { useColor: false, home: process.env.HOME });
+    process.stdout.write(`${frame.map(stripAnsi).join('\n')}\n`);
+    return 0;
+  }
+
+  await runAnsiSwitcher();
+  return 0;
+}
+
+main().then((code) => {
+  process.exitCode = code;
+}, (error: unknown) => {
+  process.stderr.write(`${error instanceof Error ? error.stack || error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/src/daemon.ts

@@ -0,0 +1,101 @@
+import net from 'node:net';
+import fs from 'node:fs/promises';
+import { AgentPane, SwitcherSnapshot } from './model.js';
+import { WatcherAgentEventInput } from './agentEvents.js';
+import { applyAgentEvent } from './agentEventReducer.js';
+import { CommandRunner, hasTmuxServer, nodeCommandRunner } from './tmux.js';
+import { getTmuxPane } from './tmuxContext.js';
+import { terminalTargetCwd } from './terminalTarget.js';
+import { discoverGitMetadata } from './git.js';
+import { canonicalSurfaceKey } from './surfaceIdentity.js';
+
+export type DaemonRequest =
+  | { type: 'event'; event: WatcherAgentEventInput }
+  | { type: 'snapshot' };
+
+export type DaemonResponse =
+  | { ok: true; snapshot?: SwitcherSnapshot }
+  | { ok: false; error: string };
+
+export class SnapshotStore {
+  private panes = new Map<string, AgentPane>();
+
+  async recordAgentEvent(event: WatcherAgentEventInput, runner: CommandRunner = nodeCommandRunner): Promise<AgentPane> {
+    const target = await getTmuxPane(event.surface.id, runner);
+    const cwd = event.payload.cwd ?? terminalTargetCwd(target);
+    const git = await discoverGitMetadata(cwd, runner);
+    const key = canonicalSurfaceKey(event.surface);
+    const previous = this.panes.get(key);
+    const pane = applyAgentEvent(previous, event, { target, cwd, git, now: event.now ?? Date.now() });
+    this.panes.set(pane.id, pane);
+    return pane;
+  }
+
+  snapshot(tmuxAvailable = true, now = Date.now()): SwitcherSnapshot {
+    return {
+      panes: [...this.panes.values()],
+      daemonAvailable: true,
+      tmuxAvailable,
+      now,
+    };
+  }
+}
+
+export interface DaemonOptions {
+  socketPath: string;
+  runner?: CommandRunner;
+  store?: SnapshotStore;
+}
+
+export async function startDaemon(options: DaemonOptions): Promise<net.Server> {
+  const runner = options.runner ?? nodeCommandRunner;
+  const store = options.store ?? new SnapshotStore();
+  await fs.rm(options.socketPath, { force: true }).catch(() => undefined);
+  const server = net.createServer((socket) => {
+    let body = '';
+    let handled = false;
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk) => {
+      body += chunk;
+      if (!handled && body.includes('\n')) {
+        handled = true;
+        const [line] = body.split('\n');
+        void handleRequest(line ?? body, store, runner).then((response) => {
+          socket.end(`${JSON.stringify(response)}\n`);
+        });
+      }
+    });
+    socket.on('end', () => {
+      if (handled) return;
+      handled = true;
+      void handleRequest(body, store, runner).then((response) => {
+        socket.end(`${JSON.stringify(response)}\n`);
+      });
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(options.socketPath, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+  return server;
+}
+
+async function handleRequest(body: string, store: SnapshotStore, runner: CommandRunner): Promise<DaemonResponse> {
+  try {
+    const request = JSON.parse(body) as DaemonRequest;
+    if (request.type === 'event') {
+      await store.recordAgentEvent(request.event, runner);
+      return { ok: true };
+    }
+    if (request.type === 'snapshot') {
+      const tmuxAvailable = await hasTmuxServer(runner);
+      return { ok: true, snapshot: store.snapshot(tmuxAvailable) };
+    }
+    return { ok: false, error: 'unknown request type' };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,85 @@
+import { AgentPane, TmuxTarget } from './model.js';
+import { detectAgentFromProcess, getAgentIntegration } from './agents/registry.js';
+import { canonicalSurfaceKey, surfaceFromTarget } from './surfaceIdentity.js';
+import { terminalTargetCommand, terminalTargetCwd, terminalTargetPid } from './terminalTarget.js';
+import { CommandRunner, nodeCommandRunner } from './tmux.js';
+import { captureTmuxPanePreview, listTmuxPanes } from './tmuxContext.js';
+import { discoverGitMetadata } from './git.js';
+
+export interface TerminalAgentObservation {
+  tmuxAvailable: boolean;
+  livePaneIds: Set<string>;
+  liveAgentProcessPaneIds: Set<string>;
+  discoveredPanes: AgentPane[];
+}
+
+async function childProcessCommands(parentPid: number | undefined, runner: CommandRunner): Promise<string[]> {
+  if (!parentPid || Number.isNaN(parentPid)) return [];
+  try {
+    const pids = (await runner.execFile('pgrep', ['-P', String(parentPid)], { timeout: 1000 })).stdout.split(/\s+/).filter(Boolean);
+    const commands: string[] = [];
+    for (const pid of pids) {
+      try {
+        const command = (await runner.execFile('ps', ['-p', pid, '-o', 'comm='], { timeout: 1000 })).stdout.trim();
+        if (command) commands.push(command);
+      } catch {
+        // One rude child process should not tank discovery. Tiny process gremlins happen.
+      }
+    }
+    return commands;
+  } catch {
+    return [];
+  }
+}
+
+export async function detectKnownAgent(pane: TmuxTarget, runner: CommandRunner = nodeCommandRunner): Promise<AgentPane['agentType'] | undefined> {
+  const direct = detectAgentFromProcess({ command: terminalTargetCommand(pane) });
+  if (direct) return direct;
+  for (const command of await childProcessCommands(terminalTargetPid(pane), runner)) {
+    const child = detectAgentFromProcess({ command });
+    if (child) return child;
+  }
+  return undefined;
+}
+
+export async function observeTerminalAgentPanes(runner: CommandRunner = nodeCommandRunner, now = Date.now()): Promise<TerminalAgentObservation> {
+  let panes: TmuxTarget[];
+  try {
+    panes = await listTmuxPanes(runner);
+  } catch {
+    return { tmuxAvailable: false, livePaneIds: new Set(), liveAgentProcessPaneIds: new Set(), discoveredPanes: [] };
+  }
+  const discovered: AgentPane[] = [];
+  for (const tmux of panes) {
+    const agentType = await detectKnownAgent(tmux, runner);
+    if (!agentType) continue;
+    const cwd = terminalTargetCwd(tmux);
+    const integration = getAgentIntegration(agentType);
+    const waitsForEvents = integration.capabilities.eventSourceInstall === 'supported';
+    const terminalPreview = await captureTmuxPanePreview(tmux.paneId, runner);
+    discovered.push({
+      id: canonicalSurfaceKey(surfaceFromTarget(tmux)),
+      agentType,
+      status: 'unknown',
+      summary: waitsForEvents ? 'Waiting for first Watcher event' : `Detected ${agentType} process`,
+      currentAction: 'tmux/process discovery fallback',
+      observation: {
+        source: 'terminal',
+        semanticEvents: false,
+        assistantDeltas: false,
+        terminalPreview: Boolean(terminalPreview),
+      },
+      terminalPreview,
+      target: tmux,
+      cwd,
+      git: await discoverGitMetadata(cwd, runner),
+      updatedAt: now,
+    });
+  }
+  return {
+    tmuxAvailable: true,
+    livePaneIds: new Set(panes.map((pane) => canonicalSurfaceKey(surfaceFromTarget(pane)))),
+    liveAgentProcessPaneIds: new Set(discovered.map((pane) => pane.id)),
+    discoveredPanes: discovered,
+  };
+}

package/src/eventCommand.ts

@@ -0,0 +1,114 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import type { DaemonRequest, DaemonResponse } from './daemon.js';
+import { sendDaemonRequest } from './ipc.js';
+import { AgentEventValidationError, buildWatcherAgentEventInput, readJsonObject, WatcherAgentEventInput } from './agentEvents.js';
+
+export async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export interface EventDeliveryDeps {
+  send?: (request: DaemonRequest) => Promise<DaemonResponse>;
+  startDaemon?: () => void;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface EventCommandDeps extends EventDeliveryDeps {
+  readInput?: () => Promise<string>;
+  env?: NodeJS.ProcessEnv;
+  stderr?: (message: string) => void;
+}
+
+export function startDetachedDaemon(): void {
+  const cliPath = process.argv[1];
+  if (!cliPath) return;
+  const child = spawn(process.execPath, [cliPath, 'daemon', '--detach'], {
+    detached: true,
+    stdio: 'ignore',
+    env: process.env,
+  });
+  child.unref();
+}
+
+export async function deliverAgentEvent(event: WatcherAgentEventInput, deps: EventDeliveryDeps = {}): Promise<boolean> {
+  const request: DaemonRequest = { type: 'event', event };
+  const send = deps.send ?? ((daemonRequest) => sendDaemonRequest(daemonRequest, { timeoutMs: 300 }));
+  const nap = deps.sleep ?? sleep;
+  try {
+    const response = await send(request);
+    if (response.ok) return true;
+  } catch {
+    // absent daemon; try to bring it up below
+  }
+  try {
+    (deps.startDaemon ?? startDetachedDaemon)();
+  } catch {
+    return false;
+  }
+  const retryDelays = [50, 100, 200, 300];
+  for (const delay of retryDelays) {
+    await nap(delay);
+    try {
+      const response = await send(request);
+      if (response.ok) return true;
+    } catch {
+      // keep the retry loop bounded; event shims are not a place to cosplay systemd.
+    }
+  }
+  return false;
+}
+
+interface ParsedEventArgs {
+  quiet: boolean;
+  agent?: string;
+  event?: string;
+  validShape: boolean;
+}
+
+function parseEventArgs(args: string[]): ParsedEventArgs {
+  if (args[0] === '--quiet') {
+    return { quiet: true, agent: args[1], event: args[2], validShape: args.length === 3 };
+  }
+  return { quiet: false, agent: args[0], event: args[1], validShape: args.length === 2 };
+}
+
+function reportError(quiet: boolean, stderr: (message: string) => void, message: string): number {
+  if (!quiet) stderr(`${message}\n`);
+  return quiet ? 0 : 2;
+}
+
+export async function runEventCommand(args: string[], deps: EventCommandDeps = {}): Promise<number> {
+  const parsed = parseEventArgs(args);
+  const stderr = deps.stderr ?? ((message) => process.stderr.write(message));
+  if (!parsed.validShape) {
+    return reportError(parsed.quiet, stderr, 'Usage: watcher event [--quiet] <agent> <event>');
+  }
+
+  let payload: Record<string, unknown>;
+  try {
+    payload = readJsonObject(await (deps.readInput ?? readStdin)());
+  } catch (error) {
+    return reportError(parsed.quiet, stderr, error instanceof Error ? error.message : String(error));
+  }
+
+  let event: WatcherAgentEventInput;
+  try {
+    const env = deps.env ?? process.env;
+    event = buildWatcherAgentEventInput(parsed.agent, parsed.event, payload, { fallbackTmuxPaneId: env.TMUX_PANE });
+  } catch (error) {
+    if (error instanceof AgentEventValidationError) return reportError(parsed.quiet, stderr, error.message);
+    return reportError(parsed.quiet, stderr, error instanceof Error ? error.message : String(error));
+  }
+
+  try {
+    await deliverAgentEvent(event, deps);
+  } catch {
+    // Agent Event Sources must never break the agent. Fail open like a polite little gremlin.
+  }
+  return 0;
+}

package/src/git.ts

@@ -0,0 +1,28 @@
+import { basename } from './text.js';
+import { CommandRunner, nodeCommandRunner } from './tmux.js';
+import { GitMetadata } from './model.js';
+
+async function git(args: string[], runner: CommandRunner, cwd: string): Promise<string | undefined> {
+  try {
+    const result = await runner.execFile('git', ['-C', cwd, ...args], { timeout: 1000 });
+    return result.stdout.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function discoverGitMetadata(cwd: string | undefined, runner: CommandRunner = nodeCommandRunner): Promise<GitMetadata | undefined> {
+  if (!cwd) return undefined;
+  const worktreePath = await git(['rev-parse', '--show-toplevel'], runner, cwd);
+  if (!worktreePath) return undefined;
+  const branch = await git(['branch', '--show-current'], runner, cwd)
+    ?? await git(['rev-parse', '--short', 'HEAD'], runner, cwd)
+    ?? 'unknown';
+  const commonDir = await git(['rev-parse', '--path-format=absolute', '--git-common-dir'], runner, cwd);
+  const repoFromCommonDir = commonDir?.endsWith('/.git') ? basename(commonDir.slice(0, -5)) : undefined;
+  return {
+    repo: repoFromCommonDir || basename(worktreePath),
+    branch,
+    worktreePath,
+  };
+}