@animalabs/agent-framework 0.21.0 → 0.22.0

package/src/modules/workspace/sync.ts

@@ -1,350 +1,20 @@
 /**
- * Sync logic between filesystem and Chronicle tree state.
- *
- * Two directions:
- * - syncFromFs: filesystem → Chronicle (user changes)
- * - materializeToFs: Chronicle → filesystem (agent changes)
+ * Shared helpers for moving content between the filesystem and the Chronicle
+ * tree. The rules for when content moves — the three-way rule over disk, the
+ * store and disk-agreement evidence — live in reconcile.ts, and how disk is
+ * observed (containment, symlinks, walks) in observe.ts.
  */
 
 import { createHash } from 'node:crypto';
-import { readFile, writeFile, mkdir, readdir, stat, access } from 'node:fs/promises';
-import { join, dirname, relative, resolve, sep } 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 {
-  // Compare with the PLATFORM separator: resolve() emits backslashes on
-  // Windows, so a '/'-suffixed root never prefix-matches there and every
-  // in-mount path was reported as outside the mount.
-  const resolved = resolve(mountPath, relativePath);
-  const root = mountPath.endsWith(sep) ? mountPath : mountPath + sep;
-  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).
+ * Hash content to a full SHA-256 hex string.
+ * Matches 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.
- */
-export interface SkippedFile {
-  /** Relative path of the file that was not synced */
-  path: string;
-  /** Why, in words the resident can act on */
-  reason: string;
-}
-
-export 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 type SyncOp = 'created' | 'modified' | 'deleted';
-
-export interface SyncedPath {
-  path: string;
-  op: SyncOp;
-}
-
-export interface SyncResult {
-  /** Paths that were synced, tagged with the op detected against tree state */
-  synced: SyncedPath[];
-  /** Paths that conflicted (both agent and user modified) — filesystem wins */
-  conflicts: ConflictInfo[];
-  /** Paths that were skipped, each with the reason — a silently skipped file
-   *  is indistinguishable from one that synced cleanly, which is how a
-   *  resident ends up believing a file is in their workspace when it never
-   *  arrived. */
-  skipped: SkippedFile[];
-}
-
-/**
- * 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({ path: relativePath, reason: 'path resolves outside the mount' });
-      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({ path: relativePath, op: 'deleted' });
-      }
-      continue;
-    }
-
-    try {
-      const fileStat = await stat(absolutePath);
-      if (!fileStat.isFile()) continue;
-      if (fileStat.size > maxSize) {
-        result.skipped.push({
-          path: relativePath,
-          reason: `too large: ${fileStat.size} bytes > maxFileSize ${maxSize}`,
-        });
-        continue;
-      }
-
-      const buffer = await readFile(absolutePath);
-      if (isBinary(buffer)) {
-        // Disk -> store sync is text-only, at ANY size: the tree stores text
-        // blobs. Binary that must live in the store has to be written through
-        // writeBinary; binary that is only passing through should be read with
-        // readBinaryFromDisk instead of synced at all.
-        result.skipped.push({
-          path: relativePath,
-          reason: 'binary file — disk sync stores text only (read it from disk, or write it via a binary-aware tool)',
-        });
-        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({ path: relativePath, op: existing ? 'modified' : 'created' });
-    } catch (error) {
-      result.skipped.push({
-        path: relativePath,
-        reason: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-
-  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);
-      // Logical workspace paths are '/'-separated everywhere (mount-prefixed
-      // paths, chronicle tree paths); node's relative() emits backslashes on
-      // Windows, so normalize. No-op on POSIX (sep === '/').
-      const relativePath = relative(basePath, fullPath).split(sep).join('/');
-
-      // 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

@@ -18,9 +18,13 @@ export interface MountConfig {
   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
+   * - 'always': chokidar watches continuously; each event re-observes its paths
+   * - 'on-agent-action': after each completed agent tool batch, the mount is
+   *   scanned, and the agent's next inference waits for that scan up to
+   *   `agentActionScanDeadlineMs`; a scan that takes longer finishes while
+   *   the round goes on
+   * - 'never': no background reads; listings and lazy reads still observe
+   *   the paths they show
    */
   watch?: 'always' | 'on-agent-action' | 'never';
   /** Debounce window in ms for watch: 'always' mode (default: 300) */
@@ -72,6 +76,19 @@ export interface WorkspaceConfig {
   deltaSnapshotEvery?: number;
   /** Full snapshot frequency for tree states (default: 10) */
   fullSnapshotEvery?: number;
+  /**
+   * How long the scan of `watch: 'on-agent-action'` mounts after a tool batch
+   * may hold the agent's next inference, in ms (default: 20000). A scan that
+   * takes longer finishes in the background; the miss is recorded on the
+   * mount's status and pushed as a `workspace:agent-action-scan-incomplete`
+   * event. So is a scan that finished without observing everything, with the
+   * regions it couldn't (`incomplete`). While a scan that outlasted its
+   * deadline still runs, later batches aren't held: their scan is queued
+   * after it, and the miss is recorded at once. The framework bounds every
+   * module's batch hook at 30 s, so a deadline above 29 s is lowered to 29 s,
+   * with a warning, for the workspace's own miss to come first.
+   */
+  agentActionScanDeadlineMs?: number;
 }
 
 // ============================================================================
@@ -79,23 +96,52 @@ export interface WorkspaceConfig {
 // ============================================================================
 
 /**
- * Per-mount runtime state (not persisted — rebuilt on start).
+ * Per-mount runtime state (not persisted — rebuilt on start). What disk last
+ * agreed with lives in the module's disk-agreement journal (global chronicle
+ * records), and branch-local intent in `intentTreeStateId`.
  */
 export interface MountState {
   /** The mount config */
   config: MountConfig;
   /** Tree state ID in Chronicle */
   treeStateId: string;
+  /** Branch-local intent (tombstones, store origin, conflicts) for this mount's paths */
+  intentTreeStateId: 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 */
+  /** Whether a full scan of the mount has completed this session */
   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>;
+  /**
+   * The last on-agent-action scan, as of `at`: `complete` when it has
+   * finished at all, `withinDeadline` when it finished before the deadline
+   * released the round, `reason` for a miss or a failure, and `incomplete`
+   * for the regions a finished scan couldn't observe (each also pushed as a
+   * `workspace:agent-action-scan-incomplete` event).
+   */
+  lastAgentActionScan?: {
+    at: number;
+    complete: boolean;
+    withinDeadline: boolean;
+    reason?: string;
+    incomplete?: Array<{ path: string; reason: string }>;
+  };
+  /**
+   * The after-batch scan queued behind the mount's running work, not yet
+   * started: later batches share it, since it starts after their tools ran.
+   */
+  agentActionScanWaiting?: AgentActionScan;
+  /**
+   * The mount's newest after-batch scan. Only its outcome is put on
+   * `lastAgentActionScan`: one queued behind an older scan describes a later
+   * batch, which the older scan's outcome mustn't speak for.
+   */
+  agentActionScanLatest?: AgentActionScan;
+  /** A scan that outlasted a batch's deadline, while it still runs. */
+  agentActionScanLate?: Promise<unknown>;
   /**
    * Wall-clock time chokidar emitted `ready` for this mount, or null if the
    * watcher hasn't finished its initial scan. null after session start =
@@ -195,6 +241,14 @@ export interface GrepInput {
   contextAfter?: number;
 }
 
+/** One after-batch scan of a mount, shared by the batches that wait for it. */
+export interface AgentActionScan {
+  /** Whether some batch stopped waiting for it (its deadline passed, or an earlier scan still ran late). */
+  late: boolean;
+  /** Settles, never rejects, once its outcome is recorded: on status if it is the newest, as events either way. */
+  settled: Promise<void>;
+}
+
 export interface StatusInput {
   /** Specific mount to check (optional — defaults to all) */
   mount?: string;
@@ -207,11 +261,18 @@ export interface MaterializeInput {
   mount?: string;
   /**
    * Materialize even when the current branch has genuinely diverged from the
-   * branch last materialized to disk (default: false). Not needed for linear
-   * continuations (child branches forked at or after the last materialized
-   * point) — those pass the guard automatically.
+   * branch last materialized to disk, and overwrite a disk copy in conflict
+   * (default: false). Not needed for linear continuations (child branches
+   * forked at or after the last materialized point) — those pass the guard
+   * automatically.
    */
   force?: boolean;
+  /**
+   * Also delete from disk the files deleted in the workspace whose disk copy
+   * is still one the workspace holds (default: false). With `force`, also
+   * those whose disk copy changed since.
+   */
+  applyDeletions?: boolean;
 }
 
 export interface SyncInput {
@@ -219,6 +280,8 @@ export interface SyncInput {
   path?: string;
   /** Specific mount (optional — defaults to all) */
   mount?: string;
+  /** Take each mount's root as it is now, when it isn't the directory disk last agreed with. */
+  acceptRoot?: boolean;
 }
 
 // ============================================================================
@@ -252,6 +315,8 @@ export interface WorkspaceDeletedEvent {
   type: 'workspace:deleted';
   paths: string[];
   mount: string;
+  /** Paths deleted on disk whose newer workspace version was kept as a conflict. */
+  conflicts?: string[];
   [key: string]: unknown;
 }