@animalabs/agent-framework 0.6.7 → 0.6.10

package/src/modules/workspace/index.ts

@@ -651,6 +651,15 @@ export class WorkspaceModule implements Module {
                 error: err.message,
               } as ProcessEvent);
             },
+            onReattach: () => {
+              mount.watcherError = null;
+              void this.initialScan(name);
+              this.ctx?.pushEvent({
+                type: 'workspace:watcher-reattached',
+                mount: name,
+                path: mount.config.path,
+              } as ProcessEvent);
+            },
           },
         );
         watcher.start();
@@ -1018,6 +1027,30 @@ export class WorkspaceModule implements Module {
     };
   }
 
+  /**
+   * Read a file's raw bytes from a mount (through the Chronicle tree, synced
+   * first like the `read` tool). Public API for the framework's synthesized
+   * `read_image` tool and other peer callers that need binary content.
+   */
+  async readBinary(
+    mountPrefixedPath: string,
+  ): Promise<{ data: Buffer } | { error: string }> {
+    let mount: MountState;
+    let relativePath: string;
+    try {
+      ({ mount, relativePath } = this.parsePath(mountPrefixedPath));
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+    const store = this.getStore();
+    await this.ensureSynced(mount, relativePath);
+    const entry = store.treeGet(mount.treeStateId, relativePath);
+    if (!entry) return { error: `File not found: ${mountPrefixedPath}` };
+    const blob = store.getBlob(entry.blobHash);
+    if (!blob) return { error: `Blob not found for: ${mountPrefixedPath}` };
+    return { data: blob };
+  }
+
   /**
    * Parse a mount-prefixed path into (mountName, relativePath).
    */
@@ -1662,8 +1695,20 @@ export class WorkspaceModule implements Module {
         mount.initialSyncDone = true;
       }
 
-      const prefix = relativePath ? relativePath + '/' : undefined;
-      const entries = store.treeList(mount.treeStateId, prefix);
+      // If `path` points at a single FILE, grep just that file. Otherwise treat
+      // `path` as a directory prefix (the original behaviour). Previously a file
+      // path produced an empty prefix like "notes.md/" and matched nothing, so
+      // grepping a specific file silently returned zero results.
+      let entries: Array<{ path: string; blobHash: string }>;
+      const fileNode = relativePath
+        ? (store.treeGet(mount.treeStateId, relativePath) as { blobHash?: string } | null)
+        : null;
+      if (fileNode && fileNode.blobHash) {
+        entries = [{ path: relativePath, blobHash: fileNode.blobHash }];
+      } else {
+        const prefix = relativePath ? relativePath + '/' : undefined;
+        entries = store.treeList(mount.treeStateId, prefix);
+      }
 
       for (const entry of entries) {
         if (fileGlob && !fileGlob.test(entry.path)) continue;

package/src/modules/workspace/types.ts

@@ -25,6 +25,8 @@ export interface MountConfig {
   watch?: 'always' | 'on-agent-action' | 'never';
   /** Debounce window in ms for watch: 'always' mode (default: 300) */
   watchDebounceMs?: number;
+  /** Poll interval in ms for checking watched root identity changes (default: 2000) */
+  watchRootPollMs?: number;
   /**
    * Simple ignore patterns (NOT full gitignore syntax). Supported forms:
    * - Exact name match: ".git", "node_modules"

package/src/modules/workspace/watcher.ts

@@ -6,7 +6,8 @@
  */
 
 import { watch, type FSWatcher } from 'chokidar';
-import { mkdirSync } from 'node:fs';
+import { mkdirSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
 import { type MountConfig } from './types.js';
 
 export type FsOp = 'created' | 'modified' | 'deleted';
@@ -30,6 +31,14 @@ export interface WatcherLifecycle {
   onReady?: () => void;
   /** Fires on any chokidar-reported error (ENOENT, EACCES, platform faults). */
   onError?: (err: Error) => void;
+  /** Fires after the watcher re-attaches to a replaced root inode. */
+  onReattach?: () => void;
+}
+
+interface RootIdentity {
+  dev: number;
+  ino: number;
+  birthtimeMs: number;
 }
 
 /**
@@ -42,8 +51,13 @@ export class MountWatcher {
   // create -> modify collapses to 'created' (single batch); delete always wins.
   private pendingChanges = new Map<string, FsOp>();
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private rootPollTimer: ReturnType<typeof setInterval> | null = null;
   private suppressedPaths = new Set<string>();
   private suppressionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private rootIdentity: RootIdentity | null = null;
+  private detached = false;
+  private attaching = false;
+  private stopped = true;
   private readonly debounceMs: number;
   private readonly config: MountConfig;
   private readonly onChangeCallback: (changes: FsChange[]) => void;
@@ -64,8 +78,14 @@ export class MountWatcher {
    * Start watching the filesystem.
    */
   start(): void {
-    if (this.watcher) return;
+    if (this.watcher || this.rootPollTimer) return;
+
+    this.stopped = false;
+    this.attach();
+    this.startRootPolling();
+  }
 
+  private attach(): void {
     // Read-write mounts: ensure the path exists before chokidar attaches.
     // chokidar 4's fs.watch-based backend silently fails to fire events when
     // the watched path OR any of its parent directories don't exist at
@@ -110,21 +130,39 @@ export class MountWatcher {
     this.watcher.on('add', handleEvent('created'));
     this.watcher.on('change', handleEvent('modified'));
     this.watcher.on('unlink', handleEvent('deleted'));
+    this.watcher.on('unlinkDir', (dirPath) => {
+      if (this.isRootPath(dirPath)) {
+        this.detached = true;
+      }
+    });
 
     if (this.lifecycle.onReady) {
       this.watcher.once('ready', this.lifecycle.onReady);
     }
-    if (this.lifecycle.onError) {
-      this.watcher.on('error', (err) => {
-        this.lifecycle.onError?.(err instanceof Error ? err : new Error(String(err)));
-      });
-    }
+    this.watcher.on('error', (err) => {
+      this.reportError(err);
+    });
+    this.watcher.on('raw', (event: string, rawPath: string, _details: unknown) => {
+      if (event !== 'rename') return;
+      // A rename on the watched root's path/basename is the one signal that
+      // survives inode reuse on Linux, where unlinkDir/error never fire.
+      if (this.isRootPath(rawPath) || basename(rawPath) === basename(this.config.path)) {
+        void this.checkRootLiveness({ force: true });
+      }
+    });
+
+    this.captureRootIdentity();
   }
 
   /**
    * Stop watching.
    */
   async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.rootPollTimer) {
+      clearInterval(this.rootPollTimer);
+      this.rootPollTimer = null;
+    }
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
       this.debounceTimer = null;
@@ -140,6 +178,9 @@ export class MountWatcher {
       await this.watcher.close();
       this.watcher = null;
     }
+    this.rootIdentity = null;
+    this.detached = false;
+    this.attaching = false;
   }
 
   /**
@@ -219,6 +260,108 @@ export class MountWatcher {
     }, this.debounceMs);
   }
 
+  private startRootPolling(): void {
+    const pollMs = this.config.watchRootPollMs ?? 2000;
+    this.rootPollTimer = setInterval(() => {
+      void this.checkRootLiveness();
+    }, pollMs);
+    this.rootPollTimer.unref();
+  }
+
+  private async checkRootLiveness(opts: { force?: boolean } = {}): Promise<void> {
+    if (this.stopped || this.attaching) return;
+
+    let current: RootIdentity;
+    try {
+      current = this.readRootIdentity();
+    } catch (err) {
+      if (this.isErrno(err, 'ENOENT')) {
+        this.detached = true;
+        if (this.config.mode === 'read-write') {
+          await this.reattach();
+        }
+        return;
+      }
+      this.reportError(err);
+      if (opts.force) {
+        this.detached = true;
+        await this.reattach();
+      }
+      return;
+    }
+
+    if (!this.rootIdentity && !this.detached) {
+      await this.reattach();
+      return;
+    }
+
+    if (!opts.force && !this.detached && this.rootIdentity
+      && this.sameIdentity(current, this.rootIdentity)) {
+      return;
+    }
+
+    await this.reattach();
+  }
+
+  private async reattach(): Promise<void> {
+    if (this.attaching || this.stopped) return;
+
+    this.attaching = true;
+    try {
+      const oldWatcher = this.watcher;
+      this.watcher = null;
+      if (oldWatcher) {
+        await oldWatcher.close();
+      }
+      if (this.stopped) return;
+
+      this.attach();
+      if (!this.detached && this.rootIdentity) {
+        this.lifecycle.onReattach?.();
+      }
+    } catch (err) {
+      this.reportError(err);
+    } finally {
+      this.attaching = false;
+    }
+  }
+
+  private captureRootIdentity(): void {
+    try {
+      this.rootIdentity = this.readRootIdentity();
+      this.detached = false;
+    } catch (err) {
+      if (this.isErrno(err, 'ENOENT')) {
+        this.rootIdentity = null;
+        this.detached = true;
+        return;
+      }
+      this.rootIdentity = null;
+      this.detached = false;
+      this.reportError(err);
+    }
+  }
+
+  private readRootIdentity(): RootIdentity {
+    const stat = statSync(this.config.path);
+    return { dev: stat.dev, ino: stat.ino, birthtimeMs: stat.birthtimeMs };
+  }
+
+  private sameIdentity(a: RootIdentity, b: RootIdentity): boolean {
+    // birthtimeMs is only a secondary tripwire: sub-millisecond replacements
+    // can reuse both the inode and timestamp, so raw rename remains essential.
+    return a.dev === b.dev && a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+  }
+
+  private isErrno(err: unknown, code: string): boolean {
+    return typeof err === 'object' && err !== null && 'code' in err
+      && (err as NodeJS.ErrnoException).code === code;
+  }
+
+  private reportError(err: unknown): void {
+    this.lifecycle.onError?.(err instanceof Error ? err : new Error(String(err)));
+  }
+
   private toRelative(absolutePath: string): string | null {
     const base = this.config.path.endsWith('/')
       ? this.config.path
@@ -228,4 +371,14 @@ export class MountWatcher {
     }
     return null;
   }
+
+  private isRootPath(absolutePath: string): boolean {
+    const root = this.config.path.endsWith('/')
+      ? this.config.path.slice(0, -1)
+      : this.config.path;
+    const candidate = absolutePath.endsWith('/')
+      ? absolutePath.slice(0, -1)
+      : absolutePath;
+    return candidate === root;
+  }
 }

package/src/types/agent.ts

@@ -68,6 +68,23 @@ export interface AgentConfig {
    */
   cacheTtl?: '5m' | '1h';
 
+  /**
+   * Whether to emit prompt-cache markers (cache_control) on requests.
+   * Default true (Anthropic API). Set false for transports that reject
+   * cache_control — e.g. Bedrock legacy Claude models, which fail with
+   * "your request did not allow prompt caching".
+   */
+  promptCaching?: boolean;
+
+  /**
+   * Prefill-formatter support: a synthetic user message appended after the
+   * conversation (e.g. chapterx's `<cmd>cat untitled.txt</cmd>` CLI-sim
+   * scaffold). Forwarded verbatim to membrane's prefill formatters; ignored
+   * by native formatting. Part of reproducing a prefill-era bot's exact
+   * prompting structure when migrating it into a resident.
+   */
+  prefillUserMessage?: string;
+
   /** Provider-specific request parameters (for example Responses reasoning
    * and server-side compaction settings). */
   providerParams?: Record<string, unknown>;
@@ -115,18 +132,6 @@ export interface AgentConfig {
      * than dropping it silently. Default true.
      */
     announceHumanTurns?: boolean;
-    /**
-     * Primary-lane autobiographical summary refusal fallback. Disabled by
-     * default: when enabled, the framework may compare the refused primary
-     * request against the latest compatible healthy request on the same branch
-     * generation, expand newly admitted summary pairs back to exact raw
-     * source, and issue at most one retry.
-     */
-    primarySummaryFallback?: {
-      enabled?: boolean;
-      maxNewSummaries?: number;
-      requestBudgetTokens?: number;
-    };
   };
 }
 

package/dist/src/canonical-json.d.ts

@@ -1,2 +0,0 @@
-export declare function canonicalJsonStringify(value: unknown): string;
-//# sourceMappingURL=canonical-json.d.ts.map

package/dist/src/canonical-json.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../../src/canonical-json.ts"],"names":[],"mappings":"AAmBA,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7D"}

package/dist/src/canonical-json.js

@@ -1,23 +0,0 @@
-function normalizeCanonicalJson(value) {
-    if (Array.isArray(value)) {
-        return value.map((entry) => normalizeCanonicalJson(entry));
-    }
-    if (value && typeof value === 'object') {
-        const withToJson = value;
-        if (typeof withToJson.toJSON === 'function') {
-            return normalizeCanonicalJson(withToJson.toJSON());
-        }
-        const normalized = {};
-        for (const key of Object.keys(value).sort()) {
-            const child = normalizeCanonicalJson(value[key]);
-            if (child !== undefined)
-                normalized[key] = child;
-        }
-        return normalized;
-    }
-    return value;
-}
-export function canonicalJsonStringify(value) {
-    return JSON.stringify(normalizeCanonicalJson(value)) ?? 'null';
-}
-//# sourceMappingURL=canonical-json.js.map

package/dist/src/canonical-json.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../../src/canonical-json.ts"],"names":[],"mappings":"AAAA,SAAS,sBAAsB,CAAC,KAAc;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,KAAmC,CAAC;QACvD,IAAI,OAAO,UAAU,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC5C,OAAO,sBAAsB,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,MAAM,UAAU,GAA4B,EAAE,CAAC;QAC/C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACvE,MAAM,KAAK,GAAG,sBAAsB,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9E,IAAI,KAAK,KAAK,SAAS;gBAAE,UAAU,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnD,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,OAAO,IAAI,CAAC,SAAS,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC;AACjE,CAAC"}

package/dist/test/primary-summary-refusal-fallback-integration.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=primary-summary-refusal-fallback-integration.test.d.ts.map

package/dist/test/primary-summary-refusal-fallback-integration.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"primary-summary-refusal-fallback-integration.test.d.ts","sourceRoot":"","sources":["../../test/primary-summary-refusal-fallback-integration.test.ts"],"names":[],"mappings":""}