@animalabs/agent-framework 0.22.1 → 0.22.2

package/src/mcpl/transport.ts

@@ -19,6 +19,7 @@
 import { spawn, type ChildProcess } from 'node:child_process';
 import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
+import { StringDecoder } from 'node:string_decoder';
 import WebSocket from 'ws';
 
 import type { McplServerConfig } from './types.js';
@@ -29,6 +30,9 @@ export interface TransportCloseInfo {
   code?: number | null;
   signal?: NodeJS.Signals | null;
   reason?: string;
+  /** True when `reason` is the peer's own text, a WebSocket server's close
+   *  reason, rather than the transport's words. */
+  reasonFromPeer?: boolean;
 }
 
 /**
@@ -71,6 +75,16 @@ export abstract class McplTransport extends EventEmitter {
     return this._closed;
   }
 
+  /**
+   * The last of what the server wrote to its diagnostic stream: at most its
+   * last {@link STDERR_TAIL_CHARS} UTF-16 code units, never opening inside a
+   * surrogate pair, after a '…' when earlier ones were dropped. A stdio
+   * child's stderr, and '' for a transport that has none.
+   */
+  get stderrTail(): string {
+    return '';
+  }
+
   /** Deliver an inbound line, buffering it if nobody is listening yet. */
   protected pushLine(line: string): void {
     if (this.listenerCount('line') > 0) this.emit('line', line);
@@ -167,8 +181,19 @@ export function buildChildEnv(
   return merged;
 }
 
+/** The most of a stdio child's stderr a transport keeps for {@link McplTransport.stderrTail}. */
+export const STDERR_TAIL_CHARS = 2_048;
+
 export class StdioTransport extends McplTransport {
   readonly kind = 'stdio' as const;
+  /** The first error on the child's stdin or stdout, named in the close reason. */
+  private pipeError: Error | undefined;
+  private stderrEnd = '';
+  private stderrCut = false;
+
+  override get stderrTail(): string {
+    return (this.stderrCut ? '…' : '') + this.stderrEnd;
+  }
 
   private constructor(
     private readonly child: ChildProcess,
@@ -178,26 +203,70 @@ export class StdioTransport extends McplTransport {
 
     this.rl.on('line', (line: string) => this.pushLine(line));
 
-    // Stitch stderr chunks into whole lines (a chunk can split a line).
+    // Stitch stderr chunks into whole lines (a chunk can split a line, and a
+    // character's bytes), and keep the stream's last characters for
+    // stderrTail.
     let carry = '';
-    this.child.stderr?.on('data', (chunk: Buffer) => {
-      const text = carry + chunk.toString('utf8');
-      const lines = text.split('\n');
+    const decoder = new StringDecoder('utf8');
+    const received = (text: string) => {
+      const end = this.stderrEnd + text;
+      this.stderrCut ||= end.length > STDERR_TAIL_CHARS;
+      let kept = end.slice(-STDERR_TAIL_CHARS);
+      // A cut between a surrogate pair's halves drops the low half too.
+      if (/^[\uDC00-\uDFFF]/.test(kept) && end.length > STDERR_TAIL_CHARS) kept = kept.slice(1);
+      this.stderrEnd = kept;
+      const lines = (carry + text).split('\n');
       carry = lines.pop() ?? '';
       for (const l of lines) if (l.length > 0) this.pushStderr(l);
+    };
+    this.child.stderr?.on('data', (chunk: Buffer) => received(decoder.write(chunk)));
+    // A last line with no newline is complete once the stream ends.
+    this.child.stderr?.on('end', () => {
+      received(decoder.end());
+      if (carry.length > 0) this.pushStderr(carry);
     });
 
     this.child.on('error', (err) => this.emit('error', err));
-    this.child.on('exit', (code, signal) =>
-      this.markClosed({ code, signal, reason: 'child process exited' }),
-    );
+    // The child's stdin and stdout carry the protocol, so after an error on
+    // either, a write's EPIPE or a read error, this transport can't reach the
+    // child even if it's still running. The handler sends a running child
+    // SIGTERM, and the exit's close names the error, so the connection handles
+    // it as any other exit. The close is the report: no 'error' is emitted,
+    // nothing is thrown. Nothing here escalates to SIGKILL, so a child that
+    // ignores SIGTERM keeps running, unreported. A child that stops reading
+    // without closing its stdin raises no error: the writes are buffered, and
+    // only request timeouts bound it (McplServerConfig.requestTimeoutMs).
+    const endOnPipeError = (err: Error) => {
+      this.pipeError ??= err;
+      if (this.child.exitCode === null && this.child.signalCode === null) this.child.kill();
+    };
+    this.child.stdin?.on('error', endOnPipeError);
+    // On the stream itself, since close() closes readline, which takes its own
+    // listener off the stream. While readline is open, its listener, which
+    // came first, re-emits the error on the interface, where an empty
+    // listener absorbs that copy.
+    this.child.stdout?.on('error', endOnPipeError);
+    this.rl.on('error', () => { /* readline's copy of a stdout error, handled above */ });
+    // stderr carries diagnostics only: a read error on it is reported if
+    // anyone listens and never thrown. It ends nothing once the connection
+    // is wired; during a handshake the listener is the handshake's, which
+    // fails it.
+    this.child.stderr?.on('error', (err) => {
+      if (this.listenerCount('error') > 0) this.emit('error', err);
+    });
+    this.child.on('exit', (code, signal) => this.markClosed({
+      code,
+      signal,
+      reason: this.pipeError ? `child process exited, and its pipe failed with ${this.pipeError.message}` : 'child process exited',
+    }));
   }
 
   /**
-   * Spawn `config.command` and return a ready stdio transport. Rejects if the
-   * command is missing (a config bug) or the process fails to spawn.
+   * Spawn `config.command` and resolve with a ready stdio transport once the
+   * child has spawned. Rejects if the command is missing (a config bug) or the
+   * process fails to spawn.
    */
-  static spawn(config: McplServerConfig): StdioTransport {
+  static async spawn(config: McplServerConfig): Promise<StdioTransport> {
     if (!config.command) {
       throw new Error(
         `MCPL server "${config.id}": stdio transport requires "command" (none provided)`,
@@ -207,6 +276,22 @@ export class StdioTransport extends McplTransport {
       stdio: ['pipe', 'pipe', 'pipe'],
       env: buildChildEnv(config),
     });
+    // Node reports a failed spawn (a command that doesn't exist, say) as an
+    // 'error' on a tick after spawn() returns, and no 'exit' follows. It is
+    // settled here, where it is listened for. A caller that listens only once
+    // this resolves, as the handshake does, would be too late when reached
+    // from a timer callback, as a reconnect is: Node runs that tick before the
+    // caller's promise continuation, and throws an 'error' nothing listens for.
+    await new Promise<void>((resolve, reject) => {
+      const failed = (err: Error) => {
+        reject(new Error(`MCPL server "${config.id}" could not be started: ${err.message}`, { cause: err }));
+      };
+      child.once('error', failed);
+      child.once('spawn', () => {
+        child.off('error', failed);
+        resolve();
+      });
+    });
     const rl = createInterface({ input: child.stdout! });
     return new StdioTransport(child, rl);
   }
@@ -223,7 +308,12 @@ export class StdioTransport extends McplTransport {
       this.child.kill();
     }
     await new Promise<void>((resolve) => {
-      if (!this.child || this.child.exitCode !== null || this.child.killed) {
+      // Once Node has seen a child exit, it has its exitCode set, or its
+      // signalCode when a signal ended it, and its 'exit' event has fired. A
+      // signal that didn't come through kill() (an OOM kill, a crash) leaves
+      // `killed` false. A child that has exited but isn't reaped yet still
+      // takes the kill() above, which sets `killed`.
+      if (!this.child || this.child.exitCode !== null || this.child.signalCode !== null || this.child.killed) {
         resolve();
       } else {
         this.child.once('exit', () => resolve());
@@ -256,9 +346,10 @@ export class WebSocketTransport extends McplTransport {
     });
 
     this.ws.on('error', (err: Error) => this.emit('error', err));
-    this.ws.on('close', (code: number, reason: Buffer) =>
-      this.markClosed({ code, reason: reason?.toString('utf8') || 'websocket closed' }),
-    );
+    this.ws.on('close', (code: number, reason: Buffer) => {
+      const text = reason?.toString('utf8');
+      this.markClosed(text ? { code, reason: text, reasonFromPeer: true } : { code, reason: 'websocket closed' });
+    });
   }
 
   /**

package/src/mcpl/types.ts

@@ -374,7 +374,11 @@ export interface McplServerConfig {
    * accepts a request and never responds would otherwise freeze the awaiting
    * agent turn forever; with the timeout the pending request rejects with a
    * descriptive error, which the framework surfaces as a normal isError
-   * tool_result. Set 0 to disable. Default: 60000 (60 seconds).
+   * tool_result. Request timeouts are the only bound for a stdio server that
+   * stops reading its stdin without closing it: the host's writes are
+   * buffered, no error is raised, and the connection stays up. This is the
+   * timeout of every request that names none; the handshake's initialize has
+   * its own. Set 0 to disable. Default: 60000 (60 seconds).
    */
   requestTimeoutMs?: number;
 

package/src/modules/discord/index.ts

@@ -67,9 +67,11 @@ const TYPING_REFRESH_MS = 8_000;
 // stuck on forever.
 const TYPING_MAX_MS = 5 * 60_000;
 
-// Trace event types that terminate an agent's turn — any of these stops the
-// typing keepalive. They fire once per turn, after all tool-call cycles.
+// Trace event types that end an agent's turn (onTrace's contract) — any of
+// these stops the typing keepalive. A turn's tool-call cycles stay inside its
+// stream, so they come after them. inference:completed is the normal end.
 const TURN_TERMINAL_TRACES = new Set([
+  'inference:completed',
   'inference:turn_ended',
   'inference:aborted',
   'inference:failed',

package/src/modules/workspace/disk-agreement.ts

@@ -15,7 +15,9 @@
  * that isn't that directory any more (an unmounted drive whose mountpoint is
  * now empty, a replaced directory) is an unavailable mount, never a disk on
  * which every file was deleted; only an explicit acceptance takes it, and
- * that starts its evidence afresh.
+ * that starts its evidence afresh. A place, where a walk stopped (`walks`),
+ * binds no root: it only says where the next walk starts, in whatever
+ * directory the root is by then.
  *
  * Every transition is write-ahead (see reconcile.ts): an `intent` entry
  * (`pending`, with the prior value and the expected one) is durable before the
@@ -92,16 +94,30 @@ type JournalEntry =
   /** The root's identity; with `reset`, an accepted new root, whose evidence starts empty. */
   | { t: 'root'; mount: string; identity: RootIdentity; reset?: true }
   | { t: 'set'; mount: string; path: string; value: Physical }
-  | { t: 'forget'; mount: string; path: string };
+  | { t: 'forget'; mount: string; path: string }
+  /**
+   * Where a capped walk of `scope` stopped (the last entry it took), or null
+   * once a walk covered the scope. It carries no `path` field: agent-framework
+   * 0.22 replays an entry it doesn't know as a `forget` of `entry.path`, and
+   * so leaves the evidence alone when there is none.
+   */
+  | { t: 'walk'; mount: string; scope: string; after: string | null };
 
 interface MountEvidence {
   root: string;
   identity?: RootIdentity;
   paths: Map<string, Physical>;
+  /** By scope ('' for the mount root): where the next walk of it resumes. */
+  walks: Map<string, string>;
 }
 
 interface Snapshot {
-  mounts: Record<string, { root: string; identity?: RootIdentity; paths: Record<string, Physical> }>;
+  mounts: Record<string, {
+    root: string;
+    identity?: RootIdentity;
+    paths: Record<string, Physical>;
+    walks?: Record<string, string>;
+  }>;
 }
 
 export const DISK_AGREEMENT_RECORD_TYPE = 'workspace/disk-agreement';
@@ -123,9 +139,10 @@ export class DiskAgreement {
   private readonly mounts = new Map<string, MountEvidence>();
   private configured: Array<{ name: string; root: string }> = [];
   /**
-   * An append (or a rebuild) not yet made durable. Cleared only by a
-   * barrier that succeeds, so a failed barrier stays owed: a later pass with
-   * nothing new to record still settles it before deciding anything.
+   * An append of evidence (or a rebuild) not yet made durable. Cleared only
+   * by a barrier that succeeds, so a failed barrier stays owed: a later pass
+   * with nothing new to record still settles it before deciding anything. A
+   * place owes none (recordWalk).
    */
   private unsynced = false;
 
@@ -183,19 +200,19 @@ export class DiskAgreement {
         root: mount.root,
         ...(mount.identity ? { identity: mount.identity } : {}),
         paths: new Map(Object.entries(mount.paths)),
+        walks: new Map(Object.entries(mount.walks ?? {})),
       });
     }
     for (const { entry } of entries) {
       if (entry.t === 'mount') {
         const existing = replayed.get(entry.mount);
-        if (!existing || !sameRootPath(existing.root, entry.root)) replayed.set(entry.mount, { root: entry.root, paths: new Map() });
+        if (!existing || !sameRootPath(existing.root, entry.root)) {
+          replayed.set(entry.mount, { root: entry.root, paths: new Map(), walks: new Map() });
+        }
         continue;
       }
       const mount = replayed.get(entry.mount);
-      if (!mount) continue;
-      if (entry.t === 'root') applyRoot(mount, entry);
-      else if (entry.t === 'set') mount.paths.set(entry.path, entry.value);
-      else mount.paths.delete(entry.path);
+      if (mount) apply(mount, entry);
     }
     this.mounts.clear();
     for (const { name, root } of this.configured) {
@@ -203,7 +220,7 @@ export class DiskAgreement {
       if (found && sameRootPath(found.root, root)) {
         this.mounts.set(name, found);
       } else {
-        this.mounts.set(name, { root, paths: new Map() });
+        this.mounts.set(name, { root, paths: new Map(), walks: new Map() });
         this.journal.append({ t: 'mount', mount: name, root });
       }
     }
@@ -250,6 +267,29 @@ export class DiskAgreement {
     return out;
   }
 
+  /**
+   * Where the next walk of `scope` ('' for the mount root) resumes: the last
+   * entry a walk of it took before its cap stopped it, if one did.
+   */
+  walkResumesAfter(mount: string, scope: string): string | undefined {
+    this.ensureReconciled();
+    return this.mounts.get(mount)?.walks.get(scope);
+  }
+
+  /**
+   * Record where a walk of `scope` stopped (`after`), or that one covered it
+   * (null). Kept with the evidence so a restart resumes there too. A place
+   * that's lost costs coverage, never a decision: an append that didn't land
+   * loses one, and a checkpoint written by a version that doesn't keep them
+   * (0.22) loses them all, and each scope's walks start at its top again.
+   * So recording one owes no barrier: a pass that moves only its place makes
+   * no store sync, and the place becomes durable with the next one.
+   */
+  recordWalk(mount: string, scope: string, after: string | null): void {
+    if ((this.walkResumesAfter(mount, scope) ?? null) === after) return;
+    this.write({ t: 'walk', mount, scope, after }, {});
+  }
+
   /**
    * Record an intent. `durable` makes it (and every append before it) stable
    * before the caller performs the effect; batches pass it on their last one.
@@ -284,14 +324,13 @@ export class DiskAgreement {
 
   private write(entry: JournalEntry, opts: { durable?: boolean; afterCommittedState?: boolean }): void {
     this.ensureReconciled();
-    this.unsynced = true; // until proven durable: a failed append may still have landed
+    // Evidence is owed a barrier until proven durable: a failed append may
+    // still have landed. A place isn't (recordWalk).
+    if (entry.t !== 'walk') this.unsynced = true;
     this.journal.append(entry, opts);
     if (opts.durable) this.unsynced = false; // synced after this append, and so everything before it
     const mount = this.mounts.get((entry as { mount: string }).mount);
-    if (!mount) return;
-    if (entry.t === 'root') applyRoot(mount, entry);
-    else if (entry.t === 'set') mount.paths.set(entry.path, entry.value);
-    else if (entry.t === 'forget') mount.paths.delete(entry.path);
+    if (mount) apply(mount, entry);
   }
 
   /** Checkpoint when the tail has outgrown the live evidence. */
@@ -307,6 +346,7 @@ export class DiskAgreement {
         root: mount.root,
         ...(mount.identity ? { identity: mount.identity } : {}),
         paths: Object.fromEntries(mount.paths),
+        ...(mount.walks.size > 0 ? { walks: Object.fromEntries(mount.walks) } : {}),
       };
     }
     this.journal.checkpoint(snapshot);
@@ -319,7 +359,23 @@ export class DiskAgreement {
   }
 }
 
+/** Apply one entry to a mount's evidence; one of a kind this version doesn't know changes nothing. */
+function apply(mount: MountEvidence, entry: JournalEntry): void {
+  if (entry.t === 'root') applyRoot(mount, entry);
+  else if (entry.t === 'set') mount.paths.set(entry.path, entry.value);
+  else if (entry.t === 'forget') mount.paths.delete(entry.path);
+  else if (entry.t === 'walk') {
+    if (entry.after === null) mount.walks.delete(entry.scope);
+    else mount.walks.set(entry.scope, entry.after);
+  }
+}
+
 function applyRoot(mount: MountEvidence, entry: Extract<JournalEntry, { t: 'root' }>): void {
   mount.identity = entry.identity;
-  if (entry.reset) mount.paths.clear();
+  if (entry.reset) {
+    // Evidence about another directory says nothing about this one, and the
+    // accepted root's walks start at its top.
+    mount.paths.clear();
+    mount.walks.clear();
+  }
 }

package/src/modules/workspace/index.ts

@@ -50,6 +50,7 @@ import {
   type PushResult,
   type Scope,
   type TreeOp,
+  WALK_CAP,
   pushPaths,
   reconcilePass,
   settleAdoptionBeforeMutation,
@@ -651,6 +652,16 @@ export class WorkspaceModule implements Module {
   private savedState: WorkspaceModuleState | null = null;
 
   constructor(config: WorkspaceConfig) {
+    for (const mount of config.mounts) {
+      const cap: unknown = mount.walkCap;
+      if (cap !== undefined && !(Number.isSafeInteger(cap) && (cap as number) > 0)) {
+        // Numbers as JavaScript writes them (JSON would say null for NaN), anything else as JSON.
+        const shown = typeof cap === 'number' ? String(cap) : typeof cap === 'bigint' ? `${cap}n` : JSON.stringify(cap) ?? String(cap);
+        throw new Error(
+          `[workspace] Mount "${mount.name}": walkCap must be a positive integer no larger than ${Number.MAX_SAFE_INTEGER}, not ${shown}`,
+        );
+      }
+    }
     // Detect overlapping mount paths: if mount A contains mount B,
     // auto-add an ignore rule on A for B's path to prevent syncing
     // the sub-mount's directory through the super-mount.
@@ -779,6 +790,8 @@ export class WorkspaceModule implements Module {
       treeStateId: mount.treeStateId,
       intents: this.intents.get(mount.config.name)!,
       readOnly: mount.config.mode === 'read-only',
+      walkCap: mount.config.walkCap ?? WALK_CAP,
+      catchUpScan: (mount.config.watch ?? 'always') === 'always',
     };
   }
 
@@ -982,9 +995,12 @@ export class WorkspaceModule implements Module {
         this.watchers.set(name, watcher);
 
         // Chokidar is started with ignoreInitial:true, so changes made while
-        // the session was down would be invisible. One full pass catches up
-        // under the three-way rule: only real differences produce tree
-        // changes and events.
+        // the session was down would be invisible. A catch-up pass takes them
+        // in under the three-way rule: only real differences produce tree
+        // changes and events. It takes its turn with the mount's bare syncs,
+        // so on a mount over its walkCap it covers the walkCap entries after
+        // where the last turn stopped, and a change elsewhere waits for the
+        // rotation to reach it, or for a sync of its path.
         void this.initialScan(name);
       }
 
@@ -1004,7 +1020,7 @@ export class WorkspaceModule implements Module {
     try {
       // A full pass under the three-way rule: deletions on disk are confirmed
       // where nothing newer is pending, and nothing unvisited is touched.
-      await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true }));
+      await this.withMount(mount, () => this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true }, { resume: true }));
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       this.ctx?.pushEvent({
@@ -1211,7 +1227,12 @@ export class WorkspaceModule implements Module {
       {
         name: 'sync',
         description: 'Bring disk changes into the workspace. Without a path, every mount (or the given one) is '
-          + 'rechecked in full and nothing pending in the workspace is discarded. With a path (file or directory), '
+          + 'rechecked and nothing pending in the workspace is discarded. A sync takes up to the mount\'s walk '
+          + 'cap of entries, files, links and the like (5000 unless configured). Past it, what this one didn\'t reach is listed under '
+          + '`incomplete`, and the walk takes turns: the next sync of the same mount or directory picks up where '
+          + 'the last turn stopped, so repeated syncs cover it all. On a mount watched continuously, its own catch-up '
+          + 'scan, at start and when its watcher reattaches, takes turns with its whole-mount syncs. With a '
+          + 'path (file or directory), '
           + 'the workspace takes disk\'s state there explicitly: it restores a workspace-deleted file, resolves '
           + 'conflicts toward disk, replaces a workspace draft, and removes a workspace file disk does not have. '
           + 'Each workspace change it gives up is listed under `discarded`, with the state it had and, as `op`, '
@@ -2851,7 +2872,8 @@ export class WorkspaceModule implements Module {
         if (input.acceptRoot && await this.acceptRootUnlocked(mount)) rootsAccepted.push(name);
         if (!relativePath) {
           // A full recheck: every file rehashed, nothing pending discarded.
-          return this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true }, { rehash: true });
+          // Past the mount's walkCap, it resumes where the last one stopped.
+          return this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true }, { rehash: true, resume: true });
         }
         // An explicit path: the workspace takes disk's state there.
         const prefix = relativePath + '/';
@@ -2864,7 +2886,7 @@ export class WorkspaceModule implements Module {
         // beneath it (a directory scope's walk; a path scope doesn't walk).
         const opts: PassOptions = { rehash: true, adopt: () => true, branchId: askedOn, named: true };
         if (!isDir) return this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, opts);
-        const beneath = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive: true }, opts);
+        const beneath = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive: true }, { ...opts, resume: true });
         // Something at the path itself is no part of a directory scope: a file
         // disk has where the workspace holds a directory, or a workspace file
         // where disk has a directory. Its own pass takes disk's state there
@@ -2988,10 +3010,14 @@ export class WorkspaceModule implements Module {
    * After an agent's completed tool batch, before anything continues its turn:
    * scan every `watch: 'on-agent-action'` mount, so what the batch's tools did
    * on disk (a shell command's files, a deletion) is in the workspace when the
-   * agent next looks. A scan that outlasts the deadline stops holding the
-   * round: the miss is recorded on the mount's status and pushed as a
-   * `workspace:agent-action-scan-incomplete` event, and the scan continues,
-   * deciding on the branch selected when it applies.
+   * agent next looks. On a mount over its walkCap, that holds for the first
+   * walkCap entries in the walk's order, which every batch's scan takes; files
+   * past them come in through syncs and the listings that reach them, while a
+   * read takes in only a file the workspace doesn't hold yet. A scan that
+   * outlasts the deadline stops holding the round: the miss is recorded on
+   * the mount's status and pushed as a `workspace:agent-action-scan-incomplete`
+   * event, and the scan continues, deciding on the branch selected when it
+   * applies.
    */
   async onToolBatchComplete(_agentName?: string): Promise<void> {
     // Every agent's workspace is the store's current branch, so the agent
@@ -3057,6 +3083,10 @@ export class WorkspaceModule implements Module {
     const scan: AgentActionScan = { late: false, settled: Promise.resolve() };
     const pass = this.withMount(mount, () => {
       if (mount.agentActionScanWaiting === scan) mount.agentActionScanWaiting = undefined;
+      // From the mount's start, as a listing walks, keeping no place: on a
+      // mount over its walkCap, every batch's scan takes the first walkCap
+      // entries in the walk's order, and the place that syncs and catch-up
+      // scans resume from stays theirs.
       return this.passUnlocked(mount, { kind: 'dir', dir: '', recursive: true });
     });
     scan.settled = pass.then(