@animalabs/agent-framework 0.1.0

package/src/modules/workspace/sync.ts

@@ -0,0 +1,314 @@
+/**
+ * Sync logic between filesystem and Chronicle tree state.
+ *
+ * Two directions:
+ * - syncFromFs: filesystem → Chronicle (user changes)
+ * - materializeToFs: Chronicle → filesystem (agent changes)
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile, writeFile, mkdir, readdir, stat, access } from 'node:fs/promises';
+import { join, dirname, relative, resolve } from 'node:path';
+import type { JsStore, JsTreeEntry } from '@animalabs/chronicle';
+import type { MountState } from './types.js';
+
+export const DEFAULT_MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
+
+/**
+ * Resolve a relative path within a mount and verify it doesn't escape.
+ * Returns the absolute path, or null if the path is outside the mount.
+ */
+function safePath(mountPath: string, relativePath: string): string | null {
+  const resolved = resolve(mountPath, relativePath);
+  const root = mountPath.endsWith('/') ? mountPath : mountPath + '/';
+  if (resolved !== mountPath && !resolved.startsWith(root)) {
+    return null;
+  }
+  return resolved;
+}
+
+/**
+ * Hash file content to a full SHA-256 hex string.
+ * Must match Chronicle's storeBlob() hash format (64-char hex).
+ */
+export function hashContent(content: string | Buffer): string {
+  const hash = createHash('sha256');
+  hash.update(content);
+  return hash.digest('hex');
+}
+
+/**
+ * Check if content appears to be binary.
+ */
+function isBinary(buffer: Buffer): boolean {
+  // Check for null bytes in first 8KB
+  const check = buffer.subarray(0, 8192);
+  for (let i = 0; i < check.length; i++) {
+    if (check[i] === 0) return true;
+  }
+  return false;
+}
+
+export interface ConflictInfo {
+  /** Relative path of the conflicted file */
+  path: string;
+  /** Blob hash of the agent's version (retrievable via store.getBlob()) */
+  agentBlobHash: string;
+}
+
+export interface SyncResult {
+  /** Paths that were synced */
+  synced: string[];
+  /** Paths that conflicted (both agent and user modified) — filesystem wins */
+  conflicts: ConflictInfo[];
+  /** Paths that were skipped (binary, too large, etc.) */
+  skipped: string[];
+}
+
+/**
+ * Sync filesystem changes into Chronicle tree state.
+ *
+ * @param store Chronicle store
+ * @param mount Mount state
+ * @param paths Specific paths to sync (relative to mount). If empty, walks the directory.
+ * @returns Sync result with synced/conflicted/skipped paths
+ */
+export async function syncFromFs(
+  store: JsStore,
+  mount: MountState,
+  paths?: string[],
+): Promise<SyncResult> {
+  const result: SyncResult = { synced: [], conflicts: [], skipped: [] };
+  const maxSize = mount.config.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+
+  const filesToSync = paths ?? await walkDirectory(mount.config.path, mount.config.ignore ?? []);
+
+  for (const relativePath of filesToSync) {
+    const absolutePath = safePath(mount.config.path, relativePath);
+    if (!absolutePath) {
+      result.skipped.push(relativePath);
+      continue;
+    }
+
+    try {
+      await access(absolutePath);
+    } catch {
+      // File was deleted on disk — remove from tree
+      const existing = store.treeGet(mount.treeStateId, relativePath);
+      if (existing) {
+        store.treeRemove(mount.treeStateId, relativePath);
+        result.synced.push(relativePath);
+      }
+      continue;
+    }
+
+    try {
+      const fileStat = await stat(absolutePath);
+      if (!fileStat.isFile()) continue;
+      if (fileStat.size > maxSize) {
+        result.skipped.push(relativePath);
+        continue;
+      }
+
+      const buffer = await readFile(absolutePath);
+      if (isBinary(buffer)) {
+        result.skipped.push(relativePath);
+        continue;
+      }
+
+      const content = buffer.toString('utf-8');
+      const hash = hashContent(content);
+
+      // Check current tree state
+      const existing = store.treeGet(mount.treeStateId, relativePath);
+
+      if (existing && existing.blobHash === hash) {
+        // No change
+        continue;
+      }
+
+      // Store blob and update tree
+      const blobHash = store.storeBlob(Buffer.from(content, 'utf-8'), 'text/plain');
+      const entry: JsTreeEntry = {
+        blobHash,
+        size: buffer.length,
+        mode: 0o644,
+      };
+
+      // Conflict detection: if the file existed in the tree AND the agent has
+      // modified it since last materialization, this is a genuine conflict
+      // (both agent and user changed the same file).
+      if (existing) {
+        const baselineHash = mount.materializedHashes.get(relativePath);
+        if (baselineHash && existing.blobHash !== baselineHash) {
+          // Agent changed the tree entry since we last materialized — conflict.
+          // Filesystem still wins, but agent's version is recoverable via agentBlobHash.
+          result.conflicts.push({
+            path: relativePath,
+            agentBlobHash: existing.blobHash,
+          });
+        }
+      }
+
+      store.treeSet(mount.treeStateId, relativePath, entry);
+      result.synced.push(relativePath);
+    } catch {
+      result.skipped.push(relativePath);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Materialize Chronicle tree state to filesystem.
+ *
+ * @param store Chronicle store
+ * @param mount Mount state
+ * @param paths Specific paths to materialize. If undefined, materializes all changed since last.
+ * @returns List of paths that were written
+ */
+export async function materializeToFs(
+  store: JsStore,
+  mount: MountState,
+  paths?: string[],
+): Promise<string[]> {
+  if (mount.config.mode === 'read-only') {
+    return [];
+  }
+
+  const written: string[] = [];
+
+  // Get changed files since last materialization
+  const currentSeq = store.currentSequence();
+  let filesToMaterialize: Array<{ path: string; blobHash: string }>;
+
+  if (paths) {
+    // Materialize specific paths
+    filesToMaterialize = [];
+    for (const p of paths) {
+      const entry = store.treeGet(mount.treeStateId, p);
+      if (entry) {
+        filesToMaterialize.push({ path: p, blobHash: entry.blobHash });
+      }
+    }
+  } else if (mount.lastMaterializedSeq > 0) {
+    // Diff since last materialization
+    const changes = store.treeDiff(
+      mount.treeStateId,
+      mount.lastMaterializedSeq,
+      currentSeq,
+    );
+    filesToMaterialize = changes
+      .filter(c => c.changeType === 'added' || c.changeType === 'modified')
+      .map(c => ({
+        path: c.path,
+        blobHash: c.newEntry!.blobHash,
+      }));
+
+    // Handle removals
+    for (const change of changes) {
+      if (change.changeType === 'removed') {
+        // Don't delete from filesystem — just skip.
+        // Agent removing from tree doesn't mean delete user's file.
+      }
+    }
+  } else {
+    // First materialization — materialize everything
+    const entries = store.treeList(mount.treeStateId);
+    filesToMaterialize = entries.map(e => ({
+      path: e.path,
+      blobHash: e.blobHash,
+    }));
+  }
+
+  for (const { path: relativePath, blobHash } of filesToMaterialize) {
+    const absolutePath = safePath(mount.config.path, relativePath);
+    if (!absolutePath) continue; // Path traversal — skip silently
+
+    const blob = store.getBlob(blobHash);
+    if (!blob) continue;
+
+    // Create parent directories
+    await mkdir(dirname(absolutePath), { recursive: true });
+
+    // Write file
+    await writeFile(absolutePath, blob);
+    written.push(relativePath);
+
+    // Record blob hash at materialization time for conflict detection
+    mount.materializedHashes.set(relativePath, blobHash);
+  }
+
+  mount.lastMaterializedSeq = currentSeq;
+
+  return written;
+}
+
+/**
+ * Walk a directory recursively, respecting ignore patterns.
+ */
+async function walkDirectory(
+  basePath: string,
+  ignorePatterns: string[],
+): Promise<string[]> {
+  const results: string[] = [];
+  const maxFiles = 5000; // Safety limit
+
+  async function walk(dir: string) {
+    if (results.length >= maxFiles) return;
+
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (results.length >= maxFiles) break;
+
+      const fullPath = join(dir, entry.name);
+      const relativePath = relative(basePath, fullPath);
+
+      // Check ignore patterns (simple glob matching)
+      if (shouldIgnore(relativePath, entry.name, ignorePatterns)) continue;
+
+      if (entry.isFile()) {
+        results.push(relativePath);
+      } else if (entry.isDirectory()) {
+        await walk(fullPath);
+      }
+    }
+  }
+
+  await walk(basePath);
+  return results;
+}
+
+/**
+ * Simple ignore pattern matching.
+ */
+function shouldIgnore(
+  relativePath: string,
+  name: string,
+  patterns: string[],
+): boolean {
+  for (const pattern of patterns) {
+    // Exact name match (e.g., ".git", "node_modules")
+    if (pattern === name) return true;
+
+    // Simple ** glob: "node_modules/**" matches anything under node_modules
+    if (pattern.endsWith('/**')) {
+      const prefix = pattern.slice(0, -3);
+      if (relativePath.startsWith(prefix + '/') || relativePath === prefix) return true;
+    }
+
+    // Extension glob: "*.pyc" matches any .pyc file
+    if (pattern.startsWith('*.')) {
+      const ext = pattern.slice(1);
+      if (name.endsWith(ext)) return true;
+    }
+  }
+  return false;
+}

package/src/modules/workspace/types.ts

@@ -0,0 +1,202 @@
+/**
+ * Types for the Workspace module
+ */
+
+// ============================================================================
+// Mount Configuration
+// ============================================================================
+
+/**
+ * Configuration for a single filesystem mount.
+ */
+export interface MountConfig {
+  /** Mount name — becomes the path prefix (e.g., "project", "config") */
+  name: string;
+  /** Absolute filesystem path to mount */
+  path: string;
+  /** Access mode */
+  mode: 'read-write' | 'read-only';
+  /**
+   * Watch mode for filesystem changes:
+   * - 'always': chokidar watches continuously, syncs on debounce
+   * - 'on-agent-action': sync from filesystem after each agent tool call
+   * - 'never': fully virtual, no automatic filesystem reads
+   */
+  watch?: 'always' | 'on-agent-action' | 'never';
+  /** Debounce window in ms for watch: 'always' mode (default: 300) */
+  watchDebounceMs?: number;
+  /**
+   * Simple ignore patterns (NOT full gitignore syntax). Supported forms:
+   * - Exact name match: ".git", "node_modules"
+   * - Directory glob: "node_modules/**" (anything under node_modules)
+   * - Extension glob: "*.pyc" (any file ending in .pyc)
+   */
+  ignore?: string[];
+  /** Whether to follow symlinks (default: false) */
+  followSymlinks?: boolean;
+  /** Maximum file size in bytes (default: 5MB) */
+  maxFileSize?: number;
+}
+
+/**
+ * Configuration for the WorkspaceModule.
+ */
+export interface WorkspaceConfig {
+  /** Mount configurations */
+  mounts: MountConfig[];
+  /** Only materialize the active branch to filesystem (default: true) */
+  materializeOnlyActiveBranch?: boolean;
+  /** Delta snapshot frequency for tree states (default: 50) */
+  deltaSnapshotEvery?: number;
+  /** Full snapshot frequency for tree states (default: 10) */
+  fullSnapshotEvery?: number;
+}
+
+// ============================================================================
+// Internal State
+// ============================================================================
+
+/**
+ * Per-mount runtime state (not persisted — rebuilt on start).
+ */
+export interface MountState {
+  /** The mount config */
+  config: MountConfig;
+  /** Tree state ID in Chronicle */
+  treeStateId: string;
+  /** Sequence number of last materialization */
+  lastMaterializedSeq: number;
+  /** Paths currently suppressed from watcher (recently materialized) */
+  suppressedPaths: Set<string>;
+  /** Whether initial lazy sync has been completed */
+  initialSyncDone: boolean;
+  /** Branch ID that was active when this mount last materialized */
+  lastMaterializedBranchId: string | null;
+  /** Per-file hash at time of last materialization — baseline for conflict detection */
+  materializedHashes: Map<string, string>;
+}
+
+/**
+ * Persisted module state (via Chronicle snapshot).
+ */
+export interface WorkspaceModuleState {
+  /** Per-mount metadata */
+  mounts: Record<string, {
+    lastMaterializedSeq: number;
+    lastMaterializedBranchId?: string;
+  }>;
+  /** Branch ID considered "active" for materialization */
+  activeBranchId?: string;
+}
+
+// ============================================================================
+// Tool Inputs
+// ============================================================================
+
+export interface ReadInput {
+  /** File path (mount-prefixed, e.g., "project/src/main.ts") */
+  path: string;
+  /** Starting line (1-indexed, optional) */
+  offset?: number;
+  /** Number of lines to read (optional) */
+  limit?: number;
+}
+
+export interface WriteInput {
+  /** File path (mount-prefixed) */
+  path: string;
+  /** Content to write */
+  content: string;
+}
+
+export interface EditInput {
+  /** File path (mount-prefixed) */
+  path: string;
+  /** String to find */
+  oldString: string;
+  /** String to replace with */
+  newString: string;
+  /** Replace all occurrences (default: false) */
+  replaceAll?: boolean;
+}
+
+export interface DeleteInput {
+  /** File path (mount-prefixed) */
+  path: string;
+}
+
+export interface LsInput {
+  /** Directory path (mount-prefixed, optional — defaults to workspace root) */
+  path?: string;
+  /** List recursively (default: false) */
+  recursive?: boolean;
+}
+
+export interface GlobInput {
+  /** Glob pattern */
+  pattern: string;
+  /** Directory to search in (mount-prefixed, optional) */
+  path?: string;
+}
+
+export interface GrepInput {
+  /** Regex pattern */
+  pattern: string;
+  /** File or directory to search in (mount-prefixed, optional) */
+  path?: string;
+  /** Glob pattern to filter files */
+  glob?: string;
+  /** Context lines before match */
+  contextBefore?: number;
+  /** Context lines after match */
+  contextAfter?: number;
+}
+
+export interface StatusInput {
+  /** Specific mount to check (optional — defaults to all) */
+  mount?: string;
+}
+
+export interface MaterializeInput {
+  /** Specific file or directory path to materialize (optional — defaults to all) */
+  path?: string;
+  /** Specific mount (optional — defaults to all read-write mounts) */
+  mount?: string;
+}
+
+export interface SyncInput {
+  /** Specific file or directory path to sync (optional — defaults to all) */
+  path?: string;
+  /** Specific mount (optional — defaults to all) */
+  mount?: string;
+}
+
+// ============================================================================
+// Events
+// ============================================================================
+
+export interface WorkspaceChangedEvent {
+  type: 'workspace:changed';
+  paths: string[];
+  mount: string;
+  conflicts?: string[];
+  [key: string]: unknown;
+}
+
+export interface WorkspaceMountedEvent {
+  type: 'workspace:mounted';
+  mount: string;
+  path: string;
+  [key: string]: unknown;
+}
+
+export interface WorkspaceUnmountedEvent {
+  type: 'workspace:unmounted';
+  mount: string;
+  [key: string]: unknown;
+}
+
+export type WorkspaceEvent =
+  | WorkspaceChangedEvent
+  | WorkspaceMountedEvent
+  | WorkspaceUnmountedEvent;

package/src/modules/workspace/watcher.ts

@@ -0,0 +1,142 @@
+/**
+ * Filesystem watcher with debounce, ignore patterns, and suppression.
+ */
+
+import { watch, type FSWatcher } from 'chokidar';
+import { type MountConfig } from './types.js';
+
+export interface WatcherEvents {
+  onChange(paths: string[]): void;
+}
+
+/**
+ * Manages filesystem watching for a single mount.
+ * Handles debouncing, ignore patterns, and write suppression.
+ */
+export class MountWatcher {
+  private watcher: FSWatcher | null = null;
+  private pendingChanges = new Set<string>();
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private suppressedPaths = new Set<string>();
+  private suppressionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly debounceMs: number;
+  private readonly config: MountConfig;
+  private readonly onChangeCallback: (paths: string[]) => void;
+
+  constructor(
+    config: MountConfig,
+    onChange: (paths: string[]) => void,
+  ) {
+    this.config = config;
+    this.debounceMs = config.watchDebounceMs ?? 300;
+    this.onChangeCallback = onChange;
+  }
+
+  /**
+   * Start watching the filesystem.
+   */
+  start(): void {
+    if (this.watcher) return;
+
+    const ignored = this.config.ignore ?? [];
+
+    this.watcher = watch(this.config.path, {
+      ignored: ignored.length > 0 ? ignored : undefined,
+      persistent: true,
+      ignoreInitial: true,
+      followSymlinks: this.config.followSymlinks ?? false,
+      awaitWriteFinish: {
+        stabilityThreshold: 100,
+        pollInterval: 50,
+      },
+    });
+
+    const handleEvent = (filePath: string) => {
+      // Convert absolute path to mount-relative
+      const relative = this.toRelative(filePath);
+      if (!relative) return;
+
+      // Skip if this path is suppressed (we just wrote it)
+      if (this.suppressedPaths.has(relative)) return;
+
+      this.pendingChanges.add(relative);
+      this.scheduleFire();
+    };
+
+    this.watcher.on('add', handleEvent);
+    this.watcher.on('change', handleEvent);
+    this.watcher.on('unlink', handleEvent);
+  }
+
+  /**
+   * Stop watching.
+   */
+  async stop(): Promise<void> {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    for (const timer of this.suppressionTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.suppressionTimers.clear();
+    this.suppressedPaths.clear();
+    this.pendingChanges.clear();
+
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+  }
+
+  /**
+   * Suppress watcher events for a path temporarily.
+   * Used after materializing to avoid echo events.
+   * After the cooldown, the path is re-checked via the recheckCallback.
+   */
+  suppress(relativePath: string, cooldownMs = 500): void {
+    this.suppressedPaths.add(relativePath);
+
+    // Clear existing timer for this path
+    const existing = this.suppressionTimers.get(relativePath);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(() => {
+      this.suppressedPaths.delete(relativePath);
+      this.suppressionTimers.delete(relativePath);
+    }, cooldownMs);
+
+    this.suppressionTimers.set(relativePath, timer);
+  }
+
+  /**
+   * Check if a path is currently suppressed.
+   */
+  isSuppressed(relativePath: string): boolean {
+    return this.suppressedPaths.has(relativePath);
+  }
+
+  private scheduleFire(): void {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      if (this.pendingChanges.size > 0) {
+        const paths = [...this.pendingChanges];
+        this.pendingChanges.clear();
+        this.onChangeCallback(paths);
+      }
+    }, this.debounceMs);
+  }
+
+  private toRelative(absolutePath: string): string | null {
+    const base = this.config.path.endsWith('/')
+      ? this.config.path
+      : this.config.path + '/';
+    if (absolutePath.startsWith(base)) {
+      return absolutePath.slice(base.length);
+    }
+    return null;
+  }
+}