@animalabs/agent-framework 0.6.8 → 0.7.0

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();
@@ -724,13 +733,13 @@ export class WorkspaceModule implements Module {
     return [
       {
         name: 'read',
-        description: 'Read a file from the workspace. Returns content with line numbers.',
+        description: 'Read a file from the workspace. Returns content with line numbers. Reads at most 2000 lines per call by default — use offset/limit to page through larger files.',
         inputSchema: {
           type: 'object' as const,
           properties: {
             path: { type: 'string', description: 'File path (mount-prefixed, e.g., "project/src/main.ts")' },
             offset: { type: 'number', description: 'Starting line number (1-indexed)' },
-            limit: { type: 'number', description: 'Maximum number of lines to return' },
+            limit: { type: 'number', description: 'Maximum number of lines to return (default 2000)' },
           },
           required: ['path'],
         },
@@ -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).
    */
@@ -1311,10 +1344,16 @@ export class WorkspaceModule implements Module {
     const content = blob.toString('utf-8');
     const lines = content.split('\n');
 
-    // Apply offset/limit
+    // Apply offset/limit. An unlimited read of a large file would inject the
+    // whole thing into the turn (a 2MB file ≈ 600k tokens → the request blows
+    // past the model context and 400s), so an omitted limit falls back to a
+    // default cap; the result reports total/from/to so the agent can page.
+    const DEFAULT_READ_LINE_LIMIT = 2000;
     const startLine = (input.offset ?? 1) - 1; // Convert to 0-indexed
-    const endLine = input.limit ? startLine + input.limit : lines.length;
+    const effectiveLimit = input.limit ?? DEFAULT_READ_LINE_LIMIT;
+    const endLine = startLine + effectiveLimit;
     const slice = lines.slice(startLine, endLine);
+    const truncated = endLine < lines.length;
 
     // Format with line numbers (cat -n style)
     const formatted = slice
@@ -1328,6 +1367,9 @@ export class WorkspaceModule implements Module {
         totalLines: lines.length,
         fromLine: startLine + 1,
         toLine: Math.min(endLine, lines.length),
+        ...(truncated
+          ? { note: `Truncated at ${effectiveLimit} lines (file has ${lines.length}). Use offset/limit to read more.` }
+          : {}),
         content: formatted,
       },
     };
@@ -1662,8 +1704,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>;
@@ -116,6 +133,16 @@ export interface AgentConfig {
      */
     announceHumanTurns?: boolean;
   };
+
+  /**
+   * How the agent's PLAIN PROSE (non-tool output) reaches channels.
+   * - 'locus' (default): host-inferred — the turn-frozen locus machinery.
+   * - 'explicit': the model prefixes prose with a destination
+   *   (`>>#channel` / `>>@person` / `>>skip_reply`); unprefixed prose is never
+   *   delivered — it bounces to a clipboard for a cheap prefixed resend.
+   *   See docs/explicit-prose-routing.md.
+   */
+  proseRouting?: 'locus' | 'explicit';
 }
 
 /** The intentionally small set of agent settings that may change in-process. */
@@ -222,4 +249,12 @@ export interface InferenceRequest {
    * which correctly fall back to the global default channel.
    */
   channelId?: string;
+  /**
+   * True when the triggering message explicitly addressed the agent (mention,
+   * reply-to-bot, DM — `chat:addressed` in MCPL RFC-001 terms). When a wake
+   * batch spans several channels, an addressed channel outranks ambient
+   * chatter for the turn's frozen speech locus: overheard conversation must
+   * not capture the agent's voice just by being newest.
+   */
+  addressed?: boolean;
 }

package/src/types/trace.ts

@@ -37,7 +37,18 @@ export type TraceEvent =
     })
 
   // Inference lifecycle
-  | (TraceEventBase & { type: 'inference:started'; agentName: string })
+  | (TraceEventBase & {
+      type: 'inference:started';
+      agentName: string;
+      /**
+       * The turn-frozen outbound locus (see turnLocusPins) — the channel this
+       * turn's plain prose will be routed to. Omitted for turns with no locus
+       * (heartbeats with no default channel). Observability only, like every
+       * trace field; lets external taps (e.g. a TTS relay) tag the whole
+       * activation with its channel without re-deriving routing.
+       */
+      channelId?: string;
+    })
   | (TraceEventBase & {
       type: 'inference:completed';
       agentName: string;
@@ -82,6 +93,8 @@ export type TraceEvent =
       blockType: 'text' | 'thinking' | 'tool_call' | 'tool_result';
       /** 0-indexed block position in the current assistant turn. */
       blockIndex: number;
+      /** Turn-frozen outbound locus for this turn (see inference:started). */
+      channelId?: string;
     })
   | (TraceEventBase & {
       /**
@@ -95,6 +108,8 @@ export type TraceEvent =
       phase: 'block_start' | 'block_complete';
       blockType: 'text' | 'thinking' | 'tool_call' | 'tool_result';
       blockIndex: number;
+      /** Turn-frozen outbound locus for this turn (see inference:started). */
+      channelId?: string;
     })
   | (TraceEventBase & {
       type: 'inference:tool_calls_yielded';
@@ -281,6 +296,37 @@ export type TraceEvent =
       channelId?: string;
     })
 
+  // Host-owned speech routing (ChannelRegistry.routeSpeech). One trace per
+  // delivered prose segment. `text` is the segment verbatim — the same content
+  // already on the bus chunk-by-chunk via inference:tokens, and mcpl:* traces
+  // are 'ops'-scoped on the webui wire — and `messageId` is the surface's id
+  // for the posted message (when the MCPL server reports one). Together they
+  // give external taps the (channelId, messageId, text) tuple needed to edit
+  // a just-posted message, e.g. a TTS interruption truncating a reply to the
+  // words actually voiced.
+  | (TraceEventBase & {
+      type: 'mcpl:speech-routed';
+      /** Agent / conversation whose speech was routed. */
+      conversationId: string;
+      serverId: string;
+      channelId: string;
+      delivered: boolean;
+      textLen: number;
+      /** The routed prose segment, verbatim. */
+      text: string;
+      /** Surface message id (e.g. Discord message id), when reported. */
+      messageId?: string;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:speech-route-failed';
+      /** Agent / conversation whose speech failed to route. */
+      conversationId: string;
+      /** Empty string when the failure was "no locus at all". */
+      channelId: string;
+      reason: string;
+      textLen: number;
+    })
+
   // MCPL server connection lifecycle (spawn / handshake / reconnect health).
   // Previously these outcomes were visible only on the host process's own
   // stderr, so a server that lost the boot handshake race just went missing.