claude-code-swarm 0.0.1 → 0.3.3

package/references/opentasks/src/daemon/entire-watcher.ts

@@ -0,0 +1,415 @@
+/**
+ * Entire Session Watcher
+ *
+ * Watches .git/sessionlog-sessions/ for session state changes and emits
+ * structured events. Used by the auto-linker to correlate sessions
+ * with OpenTasks tasks.
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import chokidar, { type FSWatcher } from 'chokidar';
+import type { TrackedTask, PlanEntry, TrackedSkill } from 'sessionlog';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Entire session state from a session file
+ */
+export interface EntireSessionState {
+  id: string;
+  agent: string;
+  phase: 'ACTIVE' | 'IDLE' | 'ENDED';
+  baseCommit?: string;
+  branch?: string;
+  startedAt?: string;
+  endedAt?: string;
+  checkpoints: string[];
+  lastPromptAt?: string;
+  /** Tracked tasks during the session (from sessionlog real-time hooks) */
+  tasks?: Record<string, TrackedTask>;
+  /** Whether the session is currently in plan mode */
+  inPlanMode?: boolean;
+  /** Number of times plan mode was entered */
+  planModeEntries?: number;
+  /** All plan mode enter/exit cycles */
+  planEntries?: PlanEntry[];
+  /** Skills used during the session */
+  skillsUsed?: TrackedSkill[];
+}
+
+/**
+ * Event emitted when a session changes
+ */
+export interface EntireSessionEvent {
+  type: 'started' | 'updated' | 'checkpoint' | 'ended' | 'deleted';
+  sessionId: string;
+  session: EntireSessionState;
+  previousPhase?: string;
+  checkpointId?: string;
+  timestamp: string;
+}
+
+export type SessionEventHandler = (event: EntireSessionEvent) => void;
+
+/**
+ * Configuration for the Entire watcher
+ */
+export interface EntireWatcherConfig {
+  /** Path to .opentasks/ directory (used to resolve .git) */
+  locationPath: string;
+
+  /** Override the git directory path (for testing) */
+  gitDir?: string;
+
+  /** Debounce delay in milliseconds (default: 200) */
+  debounceMs?: number;
+
+  /** Use polling instead of native fs events (useful for containers/tests) */
+  usePolling?: boolean;
+}
+
+/**
+ * Entire session watcher interface
+ */
+export interface EntireWatcher {
+  /** Start watching for session changes */
+  start(): Promise<void>;
+
+  /** Stop watching */
+  stop(): Promise<void>;
+
+  /** Register event handler */
+  onSessionEvent(handler: SessionEventHandler): void;
+
+  /** Check if watching */
+  readonly isWatching: boolean;
+
+  /** Get the resolved sessions directory path */
+  readonly sessionsDir: string;
+}
+
+// ============================================================================
+// Git Directory Resolution
+// ============================================================================
+
+/**
+ * Resolve the git directory from a location path.
+ * Handles worktrees by checking for .git file that references the real git dir.
+ */
+function resolveGitDir(locationPath: string): string | null {
+  // Walk up from the opentasks location to find .git
+  let dir = path.dirname(locationPath); // Go from .opentasks/ to project root
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    const gitPath = path.join(dir, '.git');
+
+    try {
+      const stat = fs.statSync(gitPath);
+      if (stat.isDirectory()) {
+        return gitPath;
+      }
+      // Worktree: .git is a file containing "gitdir: <path>"
+      if (stat.isFile()) {
+        const content = fs.readFileSync(gitPath, 'utf-8').trim();
+        const match = content.match(/^gitdir:\s*(.+)$/);
+        if (match) {
+          const resolved = path.resolve(dir, match[1]);
+          return resolved;
+        }
+      }
+    } catch {
+      // .git doesn't exist at this level, keep looking
+    }
+
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+// ============================================================================
+// Session File Parsing
+// ============================================================================
+
+/**
+ * Parse a session state file
+ */
+function parseSessionFile(filePath: string): EntireSessionState | null {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(content) as Record<string, unknown>;
+
+    const id = path.basename(filePath, '.json');
+
+    return {
+      id,
+      agent: String(data.agent ?? data.agentType ?? 'unknown'),
+      phase: normalizePhase(String(data.phase ?? data.state ?? 'ACTIVE')),
+      baseCommit: data.baseCommit as string | undefined,
+      branch: data.branch as string | undefined,
+      startedAt: data.startedAt as string | undefined,
+      endedAt: data.endedAt as string | undefined,
+      checkpoints: Array.isArray(data.checkpoints) ? data.checkpoints.map(String) : [],
+      lastPromptAt: data.lastPromptAt as string | undefined,
+      tasks: data.tasks as Record<string, TrackedTask> | undefined,
+      inPlanMode: data.inPlanMode as boolean | undefined,
+      planModeEntries: data.planModeEntries as number | undefined,
+      planEntries: data.planEntries as PlanEntry[] | undefined,
+      skillsUsed: data.skillsUsed as TrackedSkill[] | undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function normalizePhase(phase: string): EntireSessionState['phase'] {
+  const upper = phase.toUpperCase();
+  if (upper === 'ACTIVE' || upper === 'IDLE' || upper === 'ENDED') {
+    return upper as EntireSessionState['phase'];
+  }
+  return 'ACTIVE';
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Create an Entire session watcher
+ */
+export function createEntireWatcher(config: EntireWatcherConfig): EntireWatcher {
+  const { locationPath, debounceMs = 200, usePolling = false } = config;
+
+  // Resolve git dir
+  const gitDir = config.gitDir ?? resolveGitDir(locationPath);
+  const sessionsDir = gitDir ? path.join(gitDir, 'sessionlog-sessions') : '';
+
+  let watcher: FSWatcher | null = null;
+  let watching = false;
+  const handlers: SessionEventHandler[] = [];
+
+  // Cache of known session states for diff detection
+  const sessionCache = new Map<string, EntireSessionState>();
+
+  // Debounce map
+  const pendingChanges = new Map<string, ReturnType<typeof setTimeout>>();
+
+  function emitEvent(event: EntireSessionEvent): void {
+    for (const handler of handlers) {
+      try {
+        handler(event);
+      } catch {
+        // Ignore handler errors
+      }
+    }
+  }
+
+  function hasTaskOrPlanChanges(prev: EntireSessionState, curr: EntireSessionState): boolean {
+    const prevTaskCount = prev.tasks ? Object.keys(prev.tasks).length : 0;
+    const currTaskCount = curr.tasks ? Object.keys(curr.tasks).length : 0;
+    if (prevTaskCount !== currTaskCount) return true;
+
+    if (prev.inPlanMode !== curr.inPlanMode) return true;
+
+    const prevPlanCount = prev.planEntries?.length ?? 0;
+    const currPlanCount = curr.planEntries?.length ?? 0;
+    if (prevPlanCount !== currPlanCount) return true;
+
+    return false;
+  }
+
+  function determineEventType(
+    previous: EntireSessionState | undefined,
+    current: EntireSessionState,
+  ): EntireSessionEvent | null {
+    const timestamp = new Date().toISOString();
+
+    if (!previous) {
+      // New session
+      return {
+        type: current.phase === 'ENDED' ? 'ended' : 'started',
+        sessionId: current.id,
+        session: current,
+        timestamp,
+      };
+    }
+
+    // Phase change to ENDED
+    if (previous.phase !== 'ENDED' && current.phase === 'ENDED') {
+      return {
+        type: 'ended',
+        sessionId: current.id,
+        session: current,
+        previousPhase: previous.phase,
+        timestamp,
+      };
+    }
+
+    // New checkpoints
+    if (current.checkpoints.length > previous.checkpoints.length) {
+      const newCheckpointId = current.checkpoints[current.checkpoints.length - 1];
+      return {
+        type: 'checkpoint',
+        sessionId: current.id,
+        session: current,
+        checkpointId: newCheckpointId,
+        previousPhase: previous.phase,
+        timestamp,
+      };
+    }
+
+    // Phase change (ACTIVE → IDLE, etc.)
+    if (previous.phase !== current.phase) {
+      return {
+        type: 'updated',
+        sessionId: current.id,
+        session: current,
+        previousPhase: previous.phase,
+        timestamp,
+      };
+    }
+
+    // Task or plan state changes
+    if (hasTaskOrPlanChanges(previous, current)) {
+      return {
+        type: 'updated',
+        sessionId: current.id,
+        session: current,
+        previousPhase: previous.phase,
+        timestamp,
+      };
+    }
+
+    // No meaningful change
+    return null;
+  }
+
+  function handleFileChange(filePath: string): void {
+    if (!filePath.endsWith('.json')) return;
+
+    // Cancel existing debounce
+    const existing = pendingChanges.get(filePath);
+    if (existing) clearTimeout(existing);
+
+    pendingChanges.set(
+      filePath,
+      setTimeout(() => {
+        pendingChanges.delete(filePath);
+
+        const current = parseSessionFile(filePath);
+        if (!current) return;
+
+        const previous = sessionCache.get(current.id);
+        const event = determineEventType(previous, current);
+
+        // Update cache
+        sessionCache.set(current.id, current);
+
+        if (event) {
+          emitEvent(event);
+        }
+      }, debounceMs),
+    );
+  }
+
+  function handleFileDelete(filePath: string): void {
+    if (!filePath.endsWith('.json')) return;
+
+    const sessionId = path.basename(filePath, '.json');
+    const previous = sessionCache.get(sessionId);
+
+    if (previous) {
+      sessionCache.delete(sessionId);
+
+      emitEvent({
+        type: 'deleted',
+        sessionId,
+        session: previous,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  return {
+    get isWatching(): boolean {
+      return watching;
+    },
+
+    get sessionsDir(): string {
+      return sessionsDir;
+    },
+
+    async start(): Promise<void> {
+      if (watching || !sessionsDir) return;
+
+      // Process existing session files on startup
+      try {
+        if (fs.existsSync(sessionsDir)) {
+          const files = fs.readdirSync(sessionsDir).filter((f) => f.endsWith('.json'));
+          for (const file of files) {
+            const filePath = path.join(sessionsDir, file);
+            const session = parseSessionFile(filePath);
+            if (session) {
+              sessionCache.set(session.id, session);
+            }
+          }
+        }
+      } catch {
+        // Ignore errors reading existing files
+      }
+
+      return new Promise<void>((resolve) => {
+        // Watch the directory (not a glob) — chokidar v5 doesn't support
+        // glob patterns with usePolling. The .json filter is already applied
+        // in handleFileChange/handleFileDelete.
+        watcher = chokidar.watch(sessionsDir, {
+          ignoreInitial: true,
+          persistent: true,
+          ignorePermissionErrors: true,
+          usePolling,
+          interval: usePolling ? 100 : undefined,
+          awaitWriteFinish: {
+            stabilityThreshold: usePolling ? 100 : 200,
+            pollInterval: 50,
+          },
+        });
+
+        watcher.on('add', handleFileChange);
+        watcher.on('change', handleFileChange);
+        watcher.on('unlink', handleFileDelete);
+
+        watcher.on('ready', () => {
+          watching = true;
+          resolve();
+        });
+
+        watcher.on('error', () => {
+          // Log but don't crash — directory may not exist yet
+          resolve();
+        });
+      });
+    },
+
+    async stop(): Promise<void> {
+      // Clear pending changes
+      for (const timeout of pendingChanges.values()) {
+        clearTimeout(timeout);
+      }
+      pendingChanges.clear();
+
+      if (watcher) {
+        await watcher.close();
+        watcher = null;
+      }
+      watching = false;
+    },
+
+    onSessionEvent(handler: SessionEventHandler): void {
+      handlers.push(handler);
+    },
+  };
+}

package/references/opentasks/src/daemon/factory.ts

@@ -0,0 +1,133 @@
+/**
+ * Daemon Factory
+ *
+ * Convenience factories that create fully initialized daemons
+ * with SQLite + JSONL storage and GraphStores.
+ *
+ * - createDaemonWithStore: Single-location mode (backward compatible)
+ * - createMultiLocationDaemonFromGit: Multi-location mode for git repos
+ */
+
+import * as path from 'node:path';
+import { existsSync } from 'node:fs';
+import { createDaemon, type Daemon } from './lifecycle.js';
+import { createGraphStore, type GraphStore } from '../graph/store.js';
+import { createSQLitePersister } from '../storage/sqlite.js';
+import { JSONLPersister } from '../storage/jsonl.js';
+import type { Storage } from '../storage/interface.js';
+import type { PartialOpenTasksConfig } from '../config/schema.js';
+
+/**
+ * Configuration for createDaemonWithStore
+ */
+export interface DaemonWithStoreConfig {
+  /** Path to .opentasks/ directory */
+  locationPath: string;
+
+  /** OpenTasks version */
+  version: string;
+
+  /** Custom registry path (for testing) */
+  registryPath?: string;
+
+  /** Shutdown timeout in milliseconds */
+  shutdownTimeoutMs?: number;
+
+  /** OpenTasks config (controls tracking, providers, etc.) */
+  openTasksConfig?: PartialOpenTasksConfig;
+}
+
+/**
+ * Create a daemon with a fully initialized GraphStore
+ *
+ * Handles the boilerplate of creating SQLite + JSONL persisters,
+ * building a GraphStore, initializing it, and passing it to createDaemon.
+ *
+ * @param config - Daemon configuration
+ * @returns A ready-to-start daemon with an initialized store
+ */
+export async function createDaemonWithStore(config: DaemonWithStoreConfig): Promise<Daemon> {
+  const { locationPath, version, registryPath, shutdownTimeoutMs, openTasksConfig } = config;
+
+  const jsonlPath = path.join(locationPath, 'graph.jsonl');
+
+  // Create SQLite persister
+  const sqlite = createSQLitePersister(locationPath);
+
+  // Create JSONL persister
+  const jsonl = new JSONLPersister({ path: jsonlPath });
+
+  // JSONL load/save functions
+  const jsonlLoad = async () => {
+    if (!existsSync(jsonlPath)) {
+      return { nodes: [], edges: [] };
+    }
+    return await jsonl.load();
+  };
+
+  const jsonlSave = async (
+    nodes: Parameters<typeof jsonl.save>[0],
+    edges: Parameters<typeof jsonl.save>[1],
+  ) => {
+    await jsonl.save(nodes, edges);
+  };
+
+  // Create and initialize graph store
+  const store: GraphStore = createGraphStore(
+    { basePath: locationPath, flush: { debounceMs: 5000, maxDelayMs: 30000 } },
+    sqlite as unknown as Storage,
+    jsonlLoad,
+    jsonlSave,
+  );
+  await store.initialize();
+
+  return createDaemon({
+    locationPath,
+    version,
+    store,
+    registryPath,
+    shutdownTimeoutMs,
+    openTasksConfig,
+  });
+}
+
+/**
+ * Configuration for createMultiLocationDaemonFromGit
+ */
+export interface MultiLocationDaemonFromGitConfig {
+  /** Path to git common dir (e.g., /repo/.git) */
+  gitCommonDir: string;
+
+  /** OpenTasks version */
+  version: string;
+
+  /** Custom registry path (for testing) */
+  registryPath?: string;
+
+  /** Shutdown timeout in milliseconds */
+  shutdownTimeoutMs?: number;
+
+  /** Override for primary location path */
+  primaryLocationPath?: string;
+}
+
+/**
+ * Create a multi-location daemon from a git repo
+ *
+ * The daemon manages all worktrees registered in the git repo.
+ * Each worktree gets its own store, flush manager, and watcher.
+ *
+ * @param config - Multi-location daemon configuration
+ * @returns A ready-to-start daemon (call start() to initialize locations)
+ */
+export function createMultiLocationDaemonFromGit(config: MultiLocationDaemonFromGitConfig): Daemon {
+  const { gitCommonDir, version, registryPath, shutdownTimeoutMs, primaryLocationPath } = config;
+
+  return createDaemon({
+    gitCommonDir,
+    version,
+    registryPath,
+    shutdownTimeoutMs,
+    primaryLocationPath,
+  });
+}

package/references/opentasks/src/daemon/flush.ts

@@ -0,0 +1,168 @@
+/**
+ * Daemon Flush Manager
+ *
+ * Coordinates debounced flushing from SQLite to JSONL with
+ * file watcher integration for handling external changes.
+ */
+
+import {
+  createDebouncedFlusher,
+  type DebouncedFlusher,
+  type DebounceConfig,
+} from '../graph/debounce.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Callback to perform the actual flush operation
+ */
+export type FlushOperation = (nodeIds: string[]) => Promise<void>;
+
+/**
+ * Daemon flush manager configuration
+ */
+export interface FlushManagerConfig {
+  /** Debounce delay in milliseconds (default: 5000) */
+  debounceMs?: number;
+
+  /** Maximum delay before forced flush (default: 30000) */
+  maxDelayMs?: number;
+}
+
+/**
+ * Daemon flush manager interface
+ */
+export interface DaemonFlushManager {
+  /** Mark a node as dirty (needs flush) */
+  markDirty(nodeId: string): void;
+
+  /** Schedule a debounced flush */
+  schedule(): void;
+
+  /** Force immediate flush */
+  flush(): Promise<void>;
+
+  /** Pause flushing (for file watcher coordination) */
+  pause(): void;
+
+  /** Resume flushing */
+  resume(): void;
+
+  /** Final flush on shutdown (ignores pause state) */
+  finalFlush(): Promise<void>;
+
+  /** Check if there are pending changes */
+  hasPendingChanges(): boolean;
+
+  /** Get list of dirty node IDs */
+  getDirtyNodes(): string[];
+
+  /** Check if currently paused */
+  readonly paused: boolean;
+}
+
+// ============================================================================
+// Default Configuration
+// ============================================================================
+
+export const DEFAULT_FLUSH_CONFIG: Required<FlushManagerConfig> = {
+  debounceMs: 5000, // 5 seconds
+  maxDelayMs: 30000, // 30 seconds
+};
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Create a daemon flush manager
+ *
+ * @param config - Flush configuration
+ * @param onFlush - Callback to perform the actual flush with dirty node IDs
+ */
+export function createDaemonFlushManager(
+  config: FlushManagerConfig,
+  onFlush: FlushOperation,
+): DaemonFlushManager {
+  const {
+    debounceMs = DEFAULT_FLUSH_CONFIG.debounceMs,
+    maxDelayMs = DEFAULT_FLUSH_CONFIG.maxDelayMs,
+  } = config;
+
+  const dirtyNodes = new Set<string>();
+  let isPaused = false;
+
+  /**
+   * Perform flush operation
+   */
+  async function doFlush(): Promise<void> {
+    if (dirtyNodes.size === 0) {
+      return;
+    }
+
+    // Copy and clear dirty nodes before flush
+    const nodeIds = Array.from(dirtyNodes);
+    dirtyNodes.clear();
+
+    await onFlush(nodeIds);
+  }
+
+  // Create debounced flusher for timing
+  const flusher: DebouncedFlusher = createDebouncedFlusher({ debounceMs, maxDelayMs }, doFlush);
+
+  return {
+    get paused(): boolean {
+      return isPaused;
+    },
+
+    markDirty(nodeId: string): void {
+      dirtyNodes.add(nodeId);
+      flusher.markDirty();
+    },
+
+    schedule(): void {
+      if (isPaused) return;
+      flusher.schedule();
+    },
+
+    async flush(): Promise<void> {
+      if (isPaused) return;
+      await flusher.flush();
+    },
+
+    pause(): void {
+      isPaused = true;
+      // Cancel any pending scheduled flush
+      flusher.cancel();
+      // Note: we keep dirtyNodes intact - they'll be flushed on resume
+    },
+
+    resume(): void {
+      isPaused = false;
+      // If there are pending dirty nodes, re-mark and schedule
+      if (dirtyNodes.size > 0) {
+        flusher.markDirty();
+        flusher.schedule();
+      }
+    },
+
+    async finalFlush(): Promise<void> {
+      // Final flush ignores pause state
+      // Cancel any pending scheduled flush
+      flusher.cancel();
+
+      // Flush all remaining dirty nodes
+      await doFlush();
+    },
+
+    hasPendingChanges(): boolean {
+      return dirtyNodes.size > 0 || flusher.hasPending();
+    },
+
+    getDirtyNodes(): string[] {
+      return Array.from(dirtyNodes);
+    },
+  };
+}