@animalabs/agent-framework 0.1.0 → 0.3.0

package/src/modules/workspace/index.ts

@@ -5,8 +5,8 @@
  * auto-sync between real filesystem and Chronicle, and manual materialization.
  */
 
-import { readFile, stat, access } from 'node:fs/promises';
-import { join, resolve, relative } from 'node:path';
+import { readFile, stat, access, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join, resolve, relative, dirname } from 'node:path';
 import type { JsStore } from '@animalabs/chronicle';
 import type { Module, ModuleContext, ProcessState, EventResponse } from '../../types/module.js';
 import type { ProcessEvent, ToolDefinition, ToolCall, ToolResult } from '../../types/events.js';
@@ -25,9 +25,13 @@ import type {
   StatusInput,
   MaterializeInput,
   SyncInput,
-  WorkspaceChangedEvent,
+  WorkspaceCreatedEvent,
+  WorkspaceModifiedEvent,
+  WorkspaceDeletedEvent,
+  WorkspaceFsOp,
 } from './types.js';
-import { MountWatcher } from './watcher.js';
+import { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
+import { MountWatcher, type FsChange } from './watcher.js';
 import { syncFromFs, materializeToFs, hashContent, DEFAULT_MAX_FILE_SIZE, type ConflictInfo } from './sync.js';
 
 export type {
@@ -85,6 +89,12 @@ export class WorkspaceModule implements Module {
 
   /**
    * Inject the Chronicle store. Must be called after framework creation.
+   *
+   * Host ordering is: `AgentFramework.create()` calls `module.start(ctx)`
+   * before the framework is fully returned, and the host (e.g. conhost) wires
+   * the store via `initStore(store)` afterwards. Neither half has everything
+   * it needs on its own, so watcher setup runs in whichever callback fires
+   * second. `ensureRunning()` gates on `ctx && mounts-populated`.
    */
   initStore(store: JsStore): void {
     this.store = store;
@@ -111,9 +121,13 @@ export class WorkspaceModule implements Module {
         initialSyncDone: false,
         lastMaterializedBranchId: null,
         materializedHashes: new Map(),
+        watcherReadyAt: null,
+        watcherError: null,
       };
       this.mounts.set(mount.name, mountState);
     }
+
+    this.ensureRunning();
   }
 
   async start(ctx: ModuleContext): Promise<void> {
@@ -128,24 +142,64 @@ export class WorkspaceModule implements Module {
           if (mount) {
             mount.lastMaterializedSeq = meta.lastMaterializedSeq;
             mount.lastMaterializedBranchId = meta.lastMaterializedBranchId ?? null;
+            // watcherReadyAt intentionally not restored — each session must
+            // observe its own watcher attach, otherwise a stale timestamp
+            // would hide a new-session attach failure.
           }
         }
       }
     }
 
-    // Start watchers for 'always' mode mounts
+    this.ensureRunning();
+  }
+
+  /**
+   * Start chokidar watchers and emit workspace:mounted events.
+   * Idempotent: safe to call from both start() and initStore(), fires once
+   * per mount regardless of which runs second.
+   */
+  private ensureRunning(): void {
+    if (!this.ctx || this.mounts.size === 0) return;
+
     for (const [name, mount] of this.mounts) {
+      if (this.watchers.has(name)) continue;
+
       const watchMode = mount.config.watch ?? 'always';
       if (watchMode === 'always') {
-        const watcher = new MountWatcher(mount.config, (paths) => {
-          this.handleFsChanges(name, paths);
-        });
+        const watcher = new MountWatcher(
+          mount.config,
+          (changes) => {
+            this.handleFsChanges(name, changes);
+          },
+          {
+            onReady: () => {
+              mount.watcherReadyAt = Date.now();
+              mount.watcherError = null;
+            },
+            onError: (err) => {
+              mount.watcherError = err.message;
+              this.ctx?.pushEvent({
+                type: 'workspace:watcher-error',
+                mount: name,
+                path: mount.config.path,
+                error: err.message,
+              } as ProcessEvent);
+            },
+          },
+        );
         watcher.start();
         this.watchers.set(name, watcher);
+
+        // Chokidar is started with ignoreInitial:true, so files already on
+        // disk at session start would be invisible. Trigger one syncFromFs
+        // pass — syncFromFs diffs disk against the tree state, so only files
+        // new-to-this-session's-tree fire workspace:created events. Fresh
+        // sessions see the existing catalog; restarts only see what appeared
+        // while the session was down.
+        void this.initialScan(name);
       }
 
-      // Emit mounted event
-      this.ctx?.pushEvent({
+      this.ctx.pushEvent({
         type: 'workspace:mounted',
         mount: name,
         path: mount.config.path,
@@ -153,6 +207,25 @@ export class WorkspaceModule implements Module {
     }
   }
 
+  private async initialScan(mountName: string): Promise<void> {
+    const store = this.store;
+    const mount = this.mounts.get(mountName);
+    if (!store || !mount) return;
+
+    try {
+      const result = await syncFromFs(store, mount);
+      mount.initialSyncDone = true;
+      this.emitFsEvents(mountName, result.synced, result.conflicts);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.ctx?.pushEvent({
+        type: 'workspace:initial-scan-failed',
+        mount: mountName,
+        error: msg,
+      } as ProcessEvent);
+    }
+  }
+
   async stop(): Promise<void> {
     // Persist state
     if (this.ctx) {
@@ -162,6 +235,8 @@ export class WorkspaceModule implements Module {
         state.mounts[name] = {
           lastMaterializedSeq: mount.lastMaterializedSeq,
           lastMaterializedBranchId: mount.lastMaterializedBranchId ?? undefined,
+          watcherReadyAt: mount.watcherReadyAt,
+          watcherError: mount.watcherError,
         };
       }
       this.ctx.setState(state);
@@ -330,14 +405,47 @@ export class WorkspaceModule implements Module {
     }
   }
 
-  async onProcess(_event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
-    return {};
+  async onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
+    // Wake agents on filesystem events when the originating mount opted in.
+    // The EventGate still has final say — gate policies can further filter by
+    // mount name, path glob, or op type without requiring a recipe change.
+    if (!(WORKSPACE_FS_EVENT_TYPES as readonly string[]).includes(event.type)) {
+      return {};
+    }
+    const mountName = (event as { mount?: string }).mount;
+    if (!mountName) return {};
+    const mount = this.mounts.get(mountName);
+    if (!mount) return {};
+
+    const flag = mount.config.wakeOnChange;
+    if (!flag) return {};
+
+    const op = event.type.slice('workspace:'.length) as WorkspaceFsOp;
+    const opAllowed = flag === true || (Array.isArray(flag) && flag.includes(op));
+    if (!opAllowed) return {};
+
+    return { requestInference: true };
   }
 
   // ==========================================================================
   // Path Resolution
   // ==========================================================================
 
+  /**
+   * Resolve a mount-prefixed path (e.g. "tickets/2026-04-22-foo.md") to its
+   * absolute filesystem path. Returns null if the mount is unknown or the
+   * resolved path escapes the mount root (path-traversal guard). Public API
+   * for peer modules that need to read workspace files directly.
+   */
+  resolveAbsolutePath(mountPrefixedPath: string): string | null {
+    try {
+      const { mount, relativePath } = this.parsePath(mountPrefixedPath);
+      return resolve(mount.config.path, relativePath);
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Parse a mount-prefixed path into (mountName, relativePath).
    */
@@ -366,6 +474,58 @@ export class WorkspaceModule implements Module {
     return this.store;
   }
 
+  /**
+   * Persist a single write/edit/delete to disk when the mount opts in via
+   * `autoMaterialize`. Required for cross-agent pipelines — another agent's
+   * chokidar watcher on the same directory only sees real filesystem events.
+   * The local watcher's `suppress()` absorbs the echo so we don't self-wake.
+   *
+   * Returns an error string on failure so callers can surface it in the tool
+   * result. The autoMaterialize contract is specifically "disk is the source
+   * of truth for downstream agents", so a silent disk-write failure with a
+   * Chronicle commit would defeat the whole purpose. No-op cases (flag off,
+   * read-only mount) return null (success).
+   */
+  private async autoMaterialize(
+    mount: MountState,
+    relativePath: string,
+    op: 'write' | 'delete',
+    content?: Buffer,
+  ): Promise<string | null> {
+    if (!mount.config.autoMaterialize) return null;
+    if (mount.config.mode === 'read-only') return null;
+
+    const absolutePath = join(mount.config.path, relativePath);
+    const watcher = this.watchers.get(mount.config.name);
+    watcher?.suppress(relativePath);
+
+    try {
+      if (op === 'write' && content) {
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, content);
+        mount.materializedHashes.set(relativePath, hashContent(content));
+      } else if (op === 'delete') {
+        try {
+          await unlink(absolutePath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+        }
+        mount.materializedHashes.delete(relativePath);
+      }
+      return null;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.ctx?.pushEvent({
+        type: 'workspace:materialize-failed',
+        mount: mount.config.name,
+        path: relativePath,
+        op,
+        error: msg,
+      } as ProcessEvent);
+      return msg;
+    }
+  }
+
   // ==========================================================================
   // Lazy Sync
   // ==========================================================================
@@ -456,12 +616,21 @@ export class WorkspaceModule implements Module {
       return { success: false, error: `Content exceeds max file size (${maxSize} bytes)`, isError: true };
     }
 
-    const blobHash = store.storeBlob(Buffer.from(input.content, 'utf-8'), 'text/plain');
+    const buffer = Buffer.from(input.content, 'utf-8');
+    const blobHash = store.storeBlob(buffer, 'text/plain');
     store.treeSet(mount.treeStateId, relativePath, {
       blobHash,
       size: Buffer.byteLength(input.content),
       mode: 0o644,
     });
+    const materializeError = await this.autoMaterialize(mount, relativePath, 'write', buffer);
+    if (materializeError) {
+      return {
+        success: false,
+        error: `Wrote to Chronicle but failed to materialize "${input.path}" to disk: ${materializeError}. Downstream agents will not see this change until the next materialize call.`,
+        isError: true,
+      };
+    }
 
     return {
       success: true,
@@ -513,12 +682,21 @@ export class WorkspaceModule implements Module {
       ? content.replaceAll(input.oldString, input.newString)
       : content.replace(input.oldString, input.newString);
 
-    const newBlobHash = store.storeBlob(Buffer.from(content, 'utf-8'), 'text/plain');
+    const newBuffer = Buffer.from(content, 'utf-8');
+    const newBlobHash = store.storeBlob(newBuffer, 'text/plain');
     store.treeSet(mount.treeStateId, relativePath, {
       blobHash: newBlobHash,
       size: Buffer.byteLength(content),
       mode: entry.mode,
     });
+    const materializeError = await this.autoMaterialize(mount, relativePath, 'write', newBuffer);
+    if (materializeError) {
+      return {
+        success: false,
+        error: `Edited Chronicle but failed to materialize "${input.path}" to disk: ${materializeError}. Downstream agents will not see this change until the next materialize call.`,
+        isError: true,
+      };
+    }
 
     return {
       success: true,
@@ -542,6 +720,14 @@ export class WorkspaceModule implements Module {
     }
 
     store.treeRemove(mount.treeStateId, relativePath);
+    const materializeError = await this.autoMaterialize(mount, relativePath, 'delete');
+    if (materializeError) {
+      return {
+        success: false,
+        error: `Removed from Chronicle but failed to unlink "${input.path}" from disk: ${materializeError}. Downstream agents will still see the stale file until manual cleanup.`,
+        isError: true,
+      };
+    }
 
     return { success: true, data: { path: input.path, deleted: true } };
   }
@@ -869,20 +1055,12 @@ export class WorkspaceModule implements Module {
       mount.initialSyncDone = true;
 
       if (result.synced.length > 0 || result.conflicts.length > 0) {
-        allResults.push({ mount: name, synced: result.synced, conflicts: result.conflicts });
-
-        // Emit workspace:changed event
-        if (this.ctx) {
-          const event: WorkspaceChangedEvent = {
-            type: 'workspace:changed',
-            paths: result.synced.map(p => `${name}/${p}`),
-            mount: name,
-            conflicts: result.conflicts.length > 0
-              ? result.conflicts.map(c => `${name}/${c.path}`)
-              : undefined,
-          };
-          this.ctx.pushEvent(event as ProcessEvent);
-        }
+        allResults.push({
+          mount: name,
+          synced: result.synced.map(s => s.path),
+          conflicts: result.conflicts,
+        });
+        this.emitFsEvents(name, result.synced, result.conflicts);
       }
     }
 
@@ -902,23 +1080,76 @@ export class WorkspaceModule implements Module {
 
   /**
    * Handle filesystem changes detected by watcher (watch: 'always' mode).
+   *
+   * The watcher carries the op per path. For created/modified we call
+   * syncFromFs to pull content into the tree; for deleted we strip the tree
+   * entry directly (the file is gone, nothing to read). We emit one event per
+   * op type.
    */
-  private async handleFsChanges(mountName: string, paths: string[]): Promise<void> {
+  private async handleFsChanges(mountName: string, changes: FsChange[]): Promise<void> {
     const store = this.store;
     const mount = this.mounts.get(mountName);
     if (!store || !mount) return;
 
-    const result = await syncFromFs(store, mount, paths);
+    const touchedPaths = changes.filter(c => c.op !== 'deleted').map(c => c.path);
+    const deletedPaths = changes.filter(c => c.op === 'deleted').map(c => c.path);
+
+    const syncResult = touchedPaths.length > 0
+      ? await syncFromFs(store, mount, touchedPaths)
+      : { synced: [], conflicts: [], skipped: [] };
+
+    // Strip deleted entries from the tree so downstream consumers see a
+    // coherent state. syncFromFs would also do this if we passed the paths in,
+    // but the op from the watcher is authoritative — skip the access() probe.
+    for (const p of deletedPaths) {
+      const existing = store.treeGet(mount.treeStateId, p);
+      if (existing) {
+        store.treeRemove(mount.treeStateId, p);
+        syncResult.synced.push({ path: p, op: 'deleted' });
+      }
+    }
+
+    this.emitFsEvents(mountName, syncResult.synced, syncResult.conflicts);
+  }
 
-    if ((result.synced.length > 0 || result.conflicts.length > 0) && this.ctx) {
-      const event: WorkspaceChangedEvent = {
-        type: 'workspace:changed',
-        paths: result.synced.map(p => `${mountName}/${p}`),
+  /**
+   * Group synced paths by op and push one ProcessEvent per non-empty op.
+   */
+  private emitFsEvents(
+    mountName: string,
+    synced: Array<{ path: string; op: WorkspaceFsOp }>,
+    conflicts: ConflictInfo[],
+  ): void {
+    if (!this.ctx || synced.length === 0) return;
+
+    const byOp = new Map<WorkspaceFsOp, string[]>();
+    for (const { path, op } of synced) {
+      const list = byOp.get(op) ?? [];
+      list.push(`${mountName}/${path}`);
+      byOp.set(op, list);
+    }
+
+    // Conflicts by definition require a prior tree entry (sync detected that
+    // the agent-side version diverged from the filesystem baseline), which
+    // means the path is being re-synced as a modification. Attach conflicts
+    // only to the workspace:modified event, intersected with its paths — a
+    // created/deleted batch can't carry a meaningful conflict.
+    const conflictsByPath = new Map<string, ConflictInfo>();
+    for (const c of conflicts) conflictsByPath.set(c.path, c);
+
+    for (const [op, paths] of byOp) {
+      const type = opToEventType(op);
+      let eventConflicts: string[] | undefined;
+      if (op === 'modified' && conflictsByPath.size > 0) {
+        const matched = paths.filter(p => conflictsByPath.has(p.slice(mountName.length + 1)));
+        if (matched.length > 0) eventConflicts = matched;
+      }
+      const event = {
+        type,
+        paths,
         mount: mountName,
-        conflicts: result.conflicts.length > 0
-          ? result.conflicts.map(c => `${mountName}/${c.path}`)
-          : undefined,
-      };
+        ...(eventConflicts ? { conflicts: eventConflicts } : {}),
+      } as WorkspaceCreatedEvent | WorkspaceModifiedEvent | WorkspaceDeletedEvent;
       this.ctx.pushEvent(event as ProcessEvent);
     }
   }

package/src/modules/workspace/sync.ts

@@ -56,9 +56,16 @@ export interface ConflictInfo {
   agentBlobHash: string;
 }
 
+export type SyncOp = 'created' | 'modified' | 'deleted';
+
+export interface SyncedPath {
+  path: string;
+  op: SyncOp;
+}
+
 export interface SyncResult {
-  /** Paths that were synced */
-  synced: string[];
+  /** 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 (binary, too large, etc.) */
@@ -97,7 +104,7 @@ export async function syncFromFs(
       const existing = store.treeGet(mount.treeStateId, relativePath);
       if (existing) {
         store.treeRemove(mount.treeStateId, relativePath);
-        result.synced.push(relativePath);
+        result.synced.push({ path: relativePath, op: 'deleted' });
       }
       continue;
     }
@@ -151,7 +158,7 @@ export async function syncFromFs(
       }
 
       store.treeSet(mount.treeStateId, relativePath, entry);
-      result.synced.push(relativePath);
+      result.synced.push({ path: relativePath, op: existing ? 'modified' : 'created' });
     } catch {
       result.skipped.push(relativePath);
     }

package/src/modules/workspace/types.ts

@@ -36,6 +36,26 @@ export interface MountConfig {
   followSymlinks?: boolean;
   /** Maximum file size in bytes (default: 5MB) */
   maxFileSize?: number;
+  /**
+   * If set, filesystem changes on this mount request inference.
+   * - `true` — wake on any op (created | modified | deleted)
+   * - array — wake only for the listed ops
+   *
+   * Self-writes through the module's own tools are already suppressed by the
+   * watcher, so a mount shared between agents only wakes on external writes.
+   * The EventGate still has final say — use gate policies for path-glob
+   * filtering or to disable wake temporarily via hot-reload.
+   */
+  wakeOnChange?: boolean | Array<'created' | 'modified' | 'deleted'>;
+
+  /**
+   * If true, writes/edits/deletes via the module's tools materialize to the
+   * filesystem immediately (not just into Chronicle tree state). Required for
+   * any mount shared across agents as a communication channel — without it,
+   * another agent's watcher on the same directory sees nothing. The watcher
+   * suppresses its own echoes, so this doesn't cause self-wake loops.
+   */
+  autoMaterialize?: boolean;
 }
 
 /**
@@ -74,6 +94,15 @@ export interface MountState {
   lastMaterializedBranchId: string | null;
   /** Per-file hash at time of last materialization — baseline for conflict detection */
   materializedHashes: Map<string, string>;
+  /**
+   * Wall-clock time chokidar emitted `ready` for this mount, or null if the
+   * watcher hasn't finished its initial scan. null after session start =
+   * watcher attach silently failed; a set value with empty tree = attached
+   * to an empty directory.
+   */
+  watcherReadyAt: number | null;
+  /** Most recent chokidar error for this mount, if any. */
+  watcherError: string | null;
 }
 
 /**
@@ -84,6 +113,8 @@ export interface WorkspaceModuleState {
   mounts: Record<string, {
     lastMaterializedSeq: number;
     lastMaterializedBranchId?: string;
+    watcherReadyAt?: number | null;
+    watcherError?: string | null;
   }>;
   /** Branch ID considered "active" for materialization */
   activeBranchId?: string;
@@ -175,14 +206,36 @@ export interface SyncInput {
 // Events
 // ============================================================================
 
-export interface WorkspaceChangedEvent {
-  type: 'workspace:changed';
+export type WorkspaceFsOp = 'created' | 'modified' | 'deleted';
+
+/**
+ * Fired when files in a mount are created. `paths` are mount-prefixed
+ * (e.g. "tickets/2026-04-20-foo.md"). Conflicts are reported when Chronicle
+ * sync detected divergence between the filesystem and the tree state.
+ */
+export interface WorkspaceCreatedEvent {
+  type: 'workspace:created';
   paths: string[];
   mount: string;
   conflicts?: string[];
   [key: string]: unknown;
 }
 
+export interface WorkspaceModifiedEvent {
+  type: 'workspace:modified';
+  paths: string[];
+  mount: string;
+  conflicts?: string[];
+  [key: string]: unknown;
+}
+
+export interface WorkspaceDeletedEvent {
+  type: 'workspace:deleted';
+  paths: string[];
+  mount: string;
+  [key: string]: unknown;
+}
+
 export interface WorkspaceMountedEvent {
   type: 'workspace:mounted';
   mount: string;
@@ -197,6 +250,20 @@ export interface WorkspaceUnmountedEvent {
 }
 
 export type WorkspaceEvent =
-  | WorkspaceChangedEvent
+  | WorkspaceCreatedEvent
+  | WorkspaceModifiedEvent
+  | WorkspaceDeletedEvent
   | WorkspaceMountedEvent
   | WorkspaceUnmountedEvent;
+
+export const WORKSPACE_FS_EVENT_TYPES = [
+  'workspace:created',
+  'workspace:modified',
+  'workspace:deleted',
+] as const;
+
+export type WorkspaceFsEventType = typeof WORKSPACE_FS_EVENT_TYPES[number];
+
+export function opToEventType(op: WorkspaceFsOp): WorkspaceFsEventType {
+  return `workspace:${op}` as WorkspaceFsEventType;
+}