@dinhtungdu/watcher 1.0.0

package/src/integrationsInstaller.ts

@@ -0,0 +1,218 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { AgentType } from './model.js';
+import { AGENT_INTEGRATIONS, getAgentIntegration, isAgentType } from './agents/registry.js';
+import type { AgentIntegration } from './agents/types.js';
+
+export const WATCHER_MARKER = 'WATCHER_AGENT_EVENT_SOURCE_MANAGED';
+const LEGACY_WATCHER_MARKER = 'WATCHER_STATUS_HOOK_MANAGED';
+export const PI_EXTENSION_RELATIVE = path.join('.pi', 'agent', 'extensions', 'watcher-status.ts');
+
+export type IntegrationState = 'installed' | 'outdated' | 'missing' | 'conflict' | 'not-implemented';
+
+export interface IntegrationInstallOptions {
+  home?: string;
+}
+
+export interface IntegrationStatus {
+  agent: AgentType;
+  state: IntegrationState;
+  path?: string;
+}
+
+export function piExtensionPath(home = process.env.HOME || ''): string {
+  return path.join(home, PI_EXTENSION_RELATIVE);
+}
+
+export function generatePiExtension(): string {
+  return `// ${WATCHER_MARKER}
+// Generated by watcher integrations install pi. Safe to overwrite by Watcher.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawn, spawnSync } from "node:child_process";
+
+function textFromContent(content: unknown): string | undefined {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const text = content
+      .map((part) => part && typeof part === "object" && "text" in part ? String((part as { text?: unknown }).text ?? "") : "")
+      .filter(Boolean)
+      .join("\\n");
+    return text || undefined;
+  }
+  return undefined;
+}
+
+function assistantMessageText(message: unknown): string | undefined {
+  const candidate = message as { role?: unknown; content?: unknown } | undefined;
+  if (candidate?.role !== "assistant") return undefined;
+  return textFromContent(candidate.content);
+}
+
+function lastAssistantMessage(messages: unknown): string | undefined {
+  if (!Array.isArray(messages)) return undefined;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const text = assistantMessageText(messages[index]);
+    if (text) return text;
+  }
+  return undefined;
+}
+
+function compactUnknown(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  let text: string;
+  try {
+    text = typeof value === "string" ? value : JSON.stringify(value);
+  } catch {
+    text = String(value);
+  }
+  return text.replace(/\\s+/g, " ").trim().slice(0, 16000) || undefined;
+}
+
+function payloadWithSurface(payload: Record<string, unknown>): Record<string, unknown> {
+  const tmuxPane = process.env.TMUX_PANE;
+  const surface = tmuxPane ? { backend: "tmux" as const, id: tmuxPane } : undefined;
+  return surface ? { surface, ...payload } : payload;
+}
+
+function report(event: string, payload: Record<string, unknown> = {}) {
+  try {
+    const child = spawn("watcher", ["event", "--quiet", "pi", event], {
+      stdio: ["pipe", "ignore", "ignore"],
+      detached: true,
+      env: process.env,
+    });
+    child.stdin.end(JSON.stringify(payloadWithSurface(payload)));
+    child.unref();
+  } catch {
+    // Watcher integrations must never break Pi. If this fails, shrug in lowercase.
+  }
+}
+
+function reportSync(event: string, payload: Record<string, unknown> = {}) {
+  try {
+    spawnSync("watcher", ["event", "--quiet", "pi", event], {
+      input: JSON.stringify(payloadWithSurface(payload)),
+      stdio: ["pipe", "ignore", "ignore"],
+      env: process.env,
+      timeout: 1500,
+    });
+  } catch {
+    // Shutdown hooks get one best-effort synchronous poke. No drama, no broken Pi exit.
+  }
+}
+
+export default function watcherAgentEventSource(pi: ExtensionAPI) {
+  pi.on("session_start", async (event, ctx) => {
+    report("session-started", { reason: event.reason, cwd: ctx.cwd });
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    report("user-message", { text: event.prompt, cwd: ctx.cwd });
+  });
+
+  pi.on("agent_start", async (_event, ctx) => {
+    report("agent-started", { cwd: ctx.cwd });
+  });
+
+  pi.on("message_end", async (event, ctx) => {
+    const text = assistantMessageText(event.message);
+    if (text) report("assistant-message", { text, cwd: ctx.cwd });
+  });
+
+  pi.on("tool_execution_start", async (event, ctx) => {
+    report("tool-started", { id: event.toolCallId, name: event.toolName, input: compactUnknown(event.args), cwd: ctx.cwd });
+  });
+
+  pi.on("tool_execution_update", async (event, ctx) => {
+    report("tool-updated", { id: event.toolCallId, name: event.toolName, text: compactUnknown(event.partialResult), cwd: ctx.cwd });
+  });
+
+  pi.on("tool_execution_end", async (event, ctx) => {
+    report("tool-finished", { id: event.toolCallId, name: event.toolName, output: compactUnknown(event.result), error: Boolean(event.isError), cwd: ctx.cwd });
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    report("agent-finished", { finalMessage: lastAssistantMessage(event.messages), cwd: ctx.cwd });
+  });
+
+  pi.on("session_shutdown", async (event, ctx) => {
+    if (event.reason === "quit") {
+      reportSync("agent-finished", { finalMessage: "Session quit", cwd: ctx.cwd });
+    }
+  });
+}
+`;
+}
+
+function piIntegrationState(content: string): IntegrationState {
+  if (content.includes(WATCHER_MARKER)) return 'installed';
+  if (content.includes(LEGACY_WATCHER_MARKER)) return 'outdated';
+  return 'conflict';
+}
+
+export async function getPiIntegrationStatus(options: IntegrationInstallOptions = {}): Promise<IntegrationStatus> {
+  const target = piExtensionPath(options.home);
+  try {
+    const current = await fs.readFile(target, 'utf8');
+    return { agent: 'pi', state: piIntegrationState(current), path: target };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { agent: 'pi', state: 'missing', path: target };
+    throw error;
+  }
+}
+
+export async function installPiIntegration(options: IntegrationInstallOptions = {}): Promise<IntegrationStatus> {
+  const status = await getPiIntegrationStatus(options);
+  if (status.state === 'conflict') {
+    throw new Error(`Refusing to overwrite non-Watcher Pi extension at ${status.path}`);
+  }
+  if (!status.path) throw new Error('Pi extension path unavailable');
+  await fs.mkdir(path.dirname(status.path), { recursive: true });
+  await fs.writeFile(status.path, generatePiExtension(), 'utf8');
+  return { ...status, state: 'installed' };
+}
+
+function capabilitySummary(integration: AgentIntegration): string {
+  const caps = integration.capabilities;
+  return `event ingestion ${caps.eventIngestion}, install ${caps.eventSourceInstall}, activity ${caps.activityEvents}, deltas ${caps.assistantDeltas}`;
+}
+
+function dedupeAgents(agents: string[]): string[] {
+  return [...new Set(agents)];
+}
+
+export async function runIntegrationsInstall(agents: string[], options: IntegrationInstallOptions = {}): Promise<{ code: number; output: string }> {
+  const requested = dedupeAgents(agents);
+  if (requested.length === 0) return { code: 2, output: 'Usage: watcher integrations install <agents...>\n' };
+  const unknown = requested.filter((agent) => !isAgentType(agent));
+  if (unknown.length > 0) return { code: 2, output: `Unknown agent integration(s): ${unknown.join(', ')}\n` };
+
+  const notInstallable = requested
+    .map((agent) => getAgentIntegration(agent as AgentType))
+    .filter((integration) => integration.capabilities.eventSourceInstall !== 'supported')
+    .map((integration) => integration.type);
+  if (notInstallable.length > 0) return { code: 2, output: `Installer not implemented for: ${notInstallable.join(', ')}\n` };
+
+  const lines: string[] = [];
+  for (const agent of requested as AgentType[]) {
+    if (agent === 'pi') {
+      const status = await installPiIntegration(options);
+      lines.push(`Installed Pi Agent Event Source at ${status.path}`);
+      lines.push('Run /reload in existing Pi panes or restart Pi for the integration to load.');
+    }
+  }
+  return { code: 0, output: `${lines.join('\n')}\n` };
+}
+
+export async function runIntegrationsStatus(options: IntegrationInstallOptions = {}): Promise<string> {
+  const lines: string[] = [];
+  for (const integration of AGENT_INTEGRATIONS) {
+    if (integration.type === 'pi') {
+      const status = await getPiIntegrationStatus(options);
+      lines.push(`pi: ${status.state}${status.path ? ` at ${status.path}` : ''} — ${capabilitySummary(integration)}`);
+      continue;
+    }
+    lines.push(`${integration.type}: installer not implemented — ${capabilitySummary(integration)}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/ipc.ts

@@ -0,0 +1,56 @@
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { DaemonRequest, DaemonResponse } from './daemon.js';
+
+export function defaultSocketPath(): string {
+  return process.env.WATCHER_SOCKET || path.join(os.tmpdir(), `watcher-${process.getuid?.() ?? 'user'}.sock`);
+}
+
+export interface SendOptions {
+  socketPath?: string;
+  timeoutMs?: number;
+}
+
+export async function sendDaemonRequest(request: DaemonRequest, options: SendOptions = {}): Promise<DaemonResponse> {
+  const socketPath = options.socketPath ?? defaultSocketPath();
+  const timeoutMs = options.timeoutMs ?? 500;
+  if (!fs.existsSync(socketPath)) {
+    throw new Error(`daemon socket not found: ${socketPath}`);
+  }
+  return new Promise<DaemonResponse>((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let settled = false;
+    let body = '';
+    const timer = setTimeout(() => {
+      finish(() => reject(new Error('daemon request timed out')));
+    }, timeoutMs);
+    function finish(callback: () => void): void {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      callback();
+    }
+    socket.setEncoding('utf8');
+    socket.on('connect', () => {
+      socket.write(`${JSON.stringify(request)}\n`);
+    });
+    socket.on('data', (chunk) => {
+      body += chunk;
+    });
+    socket.on('end', () => {
+      finish(() => {
+        try {
+          resolve(JSON.parse(body) as DaemonResponse);
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+    socket.on('error', (error) => {
+      finish(() => reject(error));
+    });
+  });
+}

package/src/model.ts

@@ -0,0 +1,94 @@
+export type AgentStatus = 'working' | 'needs_input' | 'stalled' | 'unknown' | 'idle';
+
+export type AgentType = 'pi' | 'claude' | 'codex' | 'opencode';
+
+export type TerminalBackend = 'tmux';
+
+export interface BaseTerminalTarget {
+  backend: TerminalBackend;
+  id: string;
+  cwd?: string;
+  title?: string;
+  pid?: number;
+  currentCommand?: string;
+}
+
+export interface TmuxTarget extends BaseTerminalTarget {
+  backend: 'tmux';
+  paneId: string;
+  sessionName?: string;
+  windowIndex?: string;
+  paneIndex?: string;
+  paneCurrentPath?: string;
+  panePid?: number;
+  paneCurrentCommand?: string;
+  windowName?: string;
+  paneTitle?: string;
+}
+
+export type TerminalTarget = TmuxTarget;
+
+export interface GitMetadata {
+  repo: string;
+  branch: string;
+  worktreePath: string;
+}
+
+export interface AgentActivityItem {
+  id: string;
+  kind: 'assistant' | 'tool';
+  label: string;
+  text?: string;
+  state?: 'running' | 'done' | 'error' | 'waiting';
+  updatedAt: number;
+}
+
+export interface ObservationCapability {
+  source: 'event-source' | 'terminal' | 'mixed';
+  semanticEvents: boolean;
+  assistantDeltas: boolean;
+  terminalPreview: boolean;
+}
+
+export interface AgentPane {
+  id: string;
+  agentType: AgentType;
+  status: AgentStatus;
+  summary: string;
+  userMessage?: string;
+  currentAction?: string;
+  lastMessage?: string;
+  pendingAssistantMessage?: string;
+  activityItems?: AgentActivityItem[];
+  observation?: ObservationCapability;
+  target: TerminalTarget;
+  cwd?: string;
+  git?: GitMetadata;
+  updatedAt: number;
+  reportedStatus?: Exclude<AgentStatus, 'stalled'>;
+  terminalPreview?: string;
+  outputHash?: string;
+  outputChangedAt?: number;
+}
+
+export interface SwitcherSnapshot {
+  panes: AgentPane[];
+  daemonAvailable: boolean;
+  tmuxAvailable: boolean;
+  message?: string;
+  now?: number;
+}
+
+export const RUNNING_AGENT_STATUSES: AgentStatus[] = ['needs_input', 'stalled', 'working', 'unknown', 'idle'];
+
+export const STATUS_RANK: Record<AgentStatus, number> = {
+  needs_input: 0,
+  stalled: 1,
+  working: 2,
+  unknown: 3,
+  idle: 4,
+};
+
+export function isRunningAgentStatus(status: AgentStatus): boolean {
+  return RUNNING_AGENT_STATUSES.includes(status);
+}

package/src/runningAgentPanes.ts

@@ -0,0 +1,96 @@
+import { AgentPane, SwitcherSnapshot } from './model.js';
+import { CommandRunner, hasTmuxServer, nodeCommandRunner } from './tmux.js';
+import { sendDaemonRequest } from './ipc.js';
+import { observeTerminalAgentPanes, TerminalAgentObservation } from './discovery.js';
+import { captureTmuxPanePreview } from './tmuxContext.js';
+import { deriveStalledStatuses, StallTracker } from './stalled.js';
+import { normalizeAgentPaneTarget } from './terminalTarget.js';
+
+export interface RunningAgentPaneSnapshotOptions {
+  runner?: CommandRunner;
+  now?: number;
+  stallTracker?: StallTracker;
+  stalledMs?: number;
+  socketPath?: string;
+}
+
+async function readDaemonSnapshot(socketPath: string | undefined): Promise<SwitcherSnapshot | undefined> {
+  try {
+    const response = await sendDaemonRequest({ type: 'snapshot' }, { timeoutMs: 300, socketPath });
+    if (!response.ok || !response.snapshot) return undefined;
+    return {
+      ...response.snapshot,
+      panes: response.snapshot.panes
+        .map((pane) => normalizeAgentPaneTarget(pane))
+        .filter((pane): pane is AgentPane => pane !== undefined),
+    };
+  } catch {
+    // No daemon yet; render an honest empty state instead of faceplanting like a fragile dashboard goblin.
+    return undefined;
+  }
+}
+
+function daemonPaneIsRunning(pane: AgentPane, observation: TerminalAgentObservation): boolean {
+  if (!observation.tmuxAvailable) return true;
+  if (!observation.livePaneIds.has(pane.id)) return false;
+  return observation.liveAgentProcessPaneIds.has(pane.id);
+}
+
+function reconcileRunningAgentPanes(daemonPanes: AgentPane[], observation: TerminalAgentObservation): AgentPane[] {
+  const result = new Map<string, AgentPane>();
+  for (const pane of daemonPanes) {
+    const normalized = normalizeAgentPaneTarget(pane);
+    if (!normalized) continue;
+    if (!daemonPaneIsRunning(normalized, observation)) continue;
+    result.set(normalized.id, normalized);
+  }
+  for (const pane of observation.discoveredPanes) {
+    const normalized = normalizeAgentPaneTarget(pane);
+    if (normalized && !result.has(normalized.id)) result.set(normalized.id, normalized);
+  }
+  return [...result.values()];
+}
+
+async function attachTerminalPreviews(panes: AgentPane[], runner: CommandRunner): Promise<AgentPane[]> {
+  return Promise.all(panes.map(async (pane) => {
+    if (pane.terminalPreview || pane.target.backend !== 'tmux') return pane;
+    const terminalPreview = await captureTmuxPanePreview(pane.target.paneId, runner);
+    if (!terminalPreview) return pane;
+    return {
+      ...pane,
+      terminalPreview,
+      observation: {
+        source: pane.observation?.source ?? 'mixed',
+        semanticEvents: pane.observation?.semanticEvents ?? true,
+        assistantDeltas: pane.observation?.assistantDeltas ?? false,
+        terminalPreview: true,
+      },
+    };
+  }));
+}
+
+export async function loadRunningAgentPaneSnapshot(options: RunningAgentPaneSnapshotOptions = {}): Promise<SwitcherSnapshot> {
+  const runner = options.runner ?? nodeCommandRunner;
+  const now = options.now ?? Date.now();
+  const daemonSnapshot = await readDaemonSnapshot(options.socketPath);
+  const observation = await observeTerminalAgentPanes(runner, now);
+
+  if (observation.tmuxAvailable) {
+    const runningPanes = reconcileRunningAgentPanes(daemonSnapshot?.panes ?? [], observation);
+    const panesWithPreviews = await attachTerminalPreviews(runningPanes, runner);
+    return {
+      panes: await deriveStalledStatuses(panesWithPreviews, { now, runner, tracker: options.stallTracker, stalledMs: options.stalledMs }),
+      daemonAvailable: daemonSnapshot?.daemonAvailable ?? false,
+      tmuxAvailable: true,
+      now,
+    };
+  }
+
+  const tmuxAvailable = daemonSnapshot?.tmuxAvailable ?? await hasTmuxServer(runner);
+  return {
+    panes: daemonSnapshot?.panes ?? [],
+    daemonAvailable: daemonSnapshot?.daemonAvailable ?? false,
+    tmuxAvailable,
+    now,
+  };
+}

package/src/snapshot.ts

@@ -0,0 +1,8 @@
+import { SwitcherSnapshot } from './model.js';
+import { loadRunningAgentPaneSnapshot, RunningAgentPaneSnapshotOptions } from './runningAgentPanes.js';
+
+export type SnapshotOptions = RunningAgentPaneSnapshotOptions;
+
+export async function loadSwitcherSnapshot(options: SnapshotOptions = {}): Promise<SwitcherSnapshot> {
+  return loadRunningAgentPaneSnapshot(options);
+}

package/src/stalled.ts

@@ -0,0 +1,93 @@
+import crypto from 'node:crypto';
+import { AgentPane } from './model.js';
+import { terminalTargetTitle } from './terminalTarget.js';
+import { CommandRunner, nodeCommandRunner } from './tmux.js';
+
+export const DEFAULT_STALLED_MS = 5 * 60 * 1000;
+
+export interface StallEntry {
+  lastActivityAt: number;
+  eventUpdatedAt: number;
+  outputHash?: string;
+  title?: string;
+}
+
+export interface StallTracker {
+  entries: Map<string, StallEntry>;
+}
+
+export function createStallTracker(): StallTracker {
+  return { entries: new Map() };
+}
+
+export async function capturePaneTailHash(paneId: string, runner: CommandRunner = nodeCommandRunner): Promise<string | undefined> {
+  try {
+    const result = await runner.execFile('tmux', ['capture-pane', '-p', '-t', paneId, '-S', '-200'], { timeout: 1000 });
+    return crypto.createHash('sha1').update(result.stdout).digest('hex');
+  } catch {
+    return undefined;
+  }
+}
+
+export interface StalledOptions {
+  now?: number;
+  stalledMs?: number;
+  runner?: CommandRunner;
+  tracker?: StallTracker;
+}
+
+function observedTitle(pane: AgentPane): string | undefined {
+  return terminalTargetTitle(pane.target);
+}
+
+export async function deriveStalledStatuses(panes: AgentPane[], options: StalledOptions = {}): Promise<AgentPane[]> {
+  const now = options.now ?? Date.now();
+  const stalledMs = options.stalledMs ?? DEFAULT_STALLED_MS;
+  const runner = options.runner ?? nodeCommandRunner;
+  const tracker = options.tracker ?? createStallTracker();
+  const liveIds = new Set(panes.map((pane) => pane.id));
+  for (const id of tracker.entries.keys()) {
+    if (!liveIds.has(id)) tracker.entries.delete(id);
+  }
+
+  const result: AgentPane[] = [];
+  for (const pane of panes) {
+    if (pane.status !== 'working') {
+      if (pane.status === 'idle') tracker.entries.delete(pane.id);
+      else tracker.entries.set(pane.id, {
+        lastActivityAt: pane.updatedAt,
+        eventUpdatedAt: pane.updatedAt,
+        outputHash: pane.outputHash,
+        title: observedTitle(pane),
+      });
+      result.push(pane);
+      continue;
+    }
+
+    const outputHash = await capturePaneTailHash(pane.target.paneId, runner);
+    const title = observedTitle(pane);
+    const previous = tracker.entries.get(pane.id);
+    let entry: StallEntry = previous ?? {
+      lastActivityAt: pane.updatedAt,
+      eventUpdatedAt: pane.updatedAt,
+      outputHash,
+      title,
+    };
+
+    const eventChanged = pane.updatedAt > entry.eventUpdatedAt;
+    const outputChanged = outputHash !== undefined && entry.outputHash !== undefined && outputHash !== entry.outputHash;
+    const titleChanged = title !== undefined && entry.title !== undefined && title !== entry.title;
+    if (eventChanged) {
+      entry = { lastActivityAt: pane.updatedAt, eventUpdatedAt: pane.updatedAt, outputHash, title };
+    } else if (outputChanged || titleChanged) {
+      entry = { ...entry, lastActivityAt: now, outputHash, title };
+    } else {
+      entry = { ...entry, outputHash: outputHash ?? entry.outputHash, title: title ?? entry.title };
+    }
+    tracker.entries.set(pane.id, entry);
+
+    const stalled = now - entry.lastActivityAt >= stalledMs;
+    result.push(stalled ? { ...pane, status: 'stalled', reportedStatus: 'working', outputHash: outputHash ?? pane.outputHash } : { ...pane, outputHash: outputHash ?? pane.outputHash });
+  }
+  return result;
+}

package/src/surfaceIdentity.ts

@@ -0,0 +1,18 @@
+import type { TerminalBackend, TerminalTarget } from './model.js';
+
+export interface EventSurfaceIdentity {
+  backend: TerminalBackend;
+  id: string;
+}
+
+export function canonicalSurfaceKey(surface: EventSurfaceIdentity): string {
+  return `${surface.backend}:${surface.id}`;
+}
+
+export function surfaceFromTarget(target: TerminalTarget): EventSurfaceIdentity {
+  return { backend: target.backend, id: target.id };
+}
+
+export function tmuxSurface(paneId: string): EventSurfaceIdentity {
+  return { backend: 'tmux', id: paneId };
+}