@librechat/agents 3.1.77 → 3.1.78-dev.0

package/src/messages/__tests__/recency.test.ts

@@ -0,0 +1,267 @@
+import {
+  AIMessage,
+  HumanMessage,
+  ToolMessage,
+  SystemMessage,
+  type BaseMessage,
+} from '@langchain/core/messages';
+import { splitAtRecencyBoundary } from '@/messages/recency';
+
+describe('splitAtRecencyBoundary', () => {
+  describe('default behavior (turns: 2)', () => {
+    it('returns empty head and full tail for an empty array', () => {
+      const result = splitAtRecencyBoundary([], { turns: 2 });
+      expect(result.head).toEqual([]);
+      expect(result.tail).toEqual([]);
+      expect(result.tailTurnCount).toBe(0);
+      expect(result.tailStartIndex).toBe(0);
+    });
+
+    it('always preserves the most recent turn even with one large message', () => {
+      const messages = [new HumanMessage('huge first message'.repeat(1000))];
+      const result = splitAtRecencyBoundary(messages, { turns: 2 });
+      expect(result.head).toEqual([]);
+      expect(result.tail).toEqual(messages);
+      expect(result.tailTurnCount).toBe(1);
+    });
+
+    it('keeps a complete user-assistant exchange in the tail', () => {
+      const messages = [new HumanMessage('hi'), new AIMessage('hello')];
+      const result = splitAtRecencyBoundary(messages, { turns: 2 });
+      expect(result.head).toEqual([]);
+      expect(result.tail).toEqual(messages);
+      expect(result.tailTurnCount).toBe(1);
+    });
+
+    it('places older turns in the head when there are more turns than the cap', () => {
+      const messages = [
+        new HumanMessage('turn 1'),
+        new AIMessage('reply 1'),
+        new HumanMessage('turn 2'),
+        new AIMessage('reply 2'),
+        new HumanMessage('turn 3'),
+        new AIMessage('reply 3'),
+      ];
+      const result = splitAtRecencyBoundary(messages, { turns: 2 });
+      expect(result.head).toEqual(messages.slice(0, 2));
+      expect(result.tail).toEqual(messages.slice(2));
+      expect(result.tailTurnCount).toBe(2);
+      expect(result.tailStartIndex).toBe(2);
+    });
+
+    it('preserves tool_use / tool_result pairs across the boundary', () => {
+      const messages = [
+        new HumanMessage('turn 1'),
+        new AIMessage({
+          content: '',
+          tool_calls: [{ id: 'call_a', name: 'search', args: {} }],
+        }),
+        new ToolMessage({
+          content: 'result A',
+          tool_call_id: 'call_a',
+          name: 'search',
+        }),
+        new AIMessage('done with turn 1'),
+        new HumanMessage('turn 2'),
+        new AIMessage({
+          content: '',
+          tool_calls: [{ id: 'call_b', name: 'search', args: {} }],
+        }),
+        new ToolMessage({
+          content: 'result B',
+          tool_call_id: 'call_b',
+          name: 'search',
+        }),
+        new AIMessage('done with turn 2'),
+        new HumanMessage('turn 3'),
+        new AIMessage('reply 3'),
+      ];
+      const result = splitAtRecencyBoundary(messages, { turns: 2 });
+      // Head must contain turn 1's complete tool_use → tool_result pair.
+      expect(result.head).toHaveLength(4);
+      expect(result.head[0]).toBe(messages[0]);
+      expect(result.head[3]).toBe(messages[3]);
+      // Tail starts cleanly at turn 2's HumanMessage — never mid-pair.
+      expect(result.tail[0]).toBe(messages[4]);
+      expect(result.tail).toHaveLength(6);
+    });
+  });
+
+  describe('disabled (turns: 0)', () => {
+    it('puts everything in head when turns is 0', () => {
+      const messages = [
+        new HumanMessage('one'),
+        new AIMessage('two'),
+        new HumanMessage('three'),
+      ];
+      const result = splitAtRecencyBoundary(messages, { turns: 0 });
+      expect(result.head).toEqual(messages);
+      expect(result.tail).toEqual([]);
+      expect(result.tailTurnCount).toBe(0);
+    });
+
+    it('treats negative turns as 0', () => {
+      const messages = [new HumanMessage('a'), new AIMessage('b')];
+      const result = splitAtRecencyBoundary(messages, { turns: -5 });
+      expect(result.tail).toEqual([]);
+      expect(result.head).toEqual(messages);
+    });
+  });
+
+  describe('token cap', () => {
+    it('honors the token cap when adding older turns', () => {
+      const messages = [
+        new HumanMessage('turn 1'),
+        new AIMessage('reply 1'),
+        new HumanMessage('turn 2'),
+        new AIMessage('reply 2'),
+        new HumanMessage('turn 3'),
+        new AIMessage('reply 3'),
+      ];
+      const tokenCounter = (): number => 100;
+      const result = splitAtRecencyBoundary(messages, {
+        turns: 5,
+        tokens: 250,
+        tokenCounter,
+      });
+      // Last turn is always preserved (200 tokens for 2 messages).
+      // Adding turn 2 would push to 400, exceeding cap of 250 → stop.
+      expect(result.tailTurnCount).toBe(1);
+      expect(result.tail).toEqual(messages.slice(4));
+    });
+
+    it('always preserves the most recent turn even when it exceeds the cap', () => {
+      const messages = [new HumanMessage('huge'), new AIMessage('also huge')];
+      const tokenCounter = (): number => 1_000_000;
+      const result = splitAtRecencyBoundary(messages, {
+        turns: 2,
+        tokens: 10,
+        tokenCounter,
+      });
+      expect(result.head).toEqual([]);
+      expect(result.tail).toEqual(messages);
+      expect(result.tailTurnCount).toBe(1);
+    });
+
+    it('ignores the token cap when no tokenCounter is provided', () => {
+      const messages = [
+        new HumanMessage('a'),
+        new AIMessage('b'),
+        new HumanMessage('c'),
+        new AIMessage('d'),
+      ];
+      const result = splitAtRecencyBoundary(messages, {
+        turns: 3,
+        tokens: 1, // would force tail to most-recent-only if applied
+      });
+      // No tokenCounter → fall back to turn-based selection only.
+      expect(result.tailTurnCount).toBe(2);
+      expect(result.head).toEqual([]);
+      expect(result.tail).toEqual(messages);
+    });
+  });
+
+  describe('linearity', () => {
+    it('calls tokenCounter once per message in visited turns (no quadratic recount)', () => {
+      // Build a long history: 200 turns × 10 messages = 2,000 messages.
+      // If the boundary search were quadratic in the number of turns,
+      // the call count would explode (e.g., 200 × 2,000 = 400,000).
+      // The disjoint-slice invariant guarantees one call per visited
+      // message, bounded by messages.length even with a generous turn
+      // budget that visits every turn.
+      const messages: BaseMessage[] = [];
+      const turnCount = 200;
+      const messagesPerTurn = 10;
+      for (let t = 0; t < turnCount; t++) {
+        messages.push(new HumanMessage(`turn ${t} query`));
+        for (let m = 1; m < messagesPerTurn; m++) {
+          messages.push(new AIMessage(`turn ${t} reply ${m}`));
+        }
+      }
+
+      let calls = 0;
+      const tokenCounter = (): number => {
+        calls += 1;
+        return 1;
+      };
+
+      // Generous tokens cap so the loop visits every turn.
+      // turnsCap also generous so the limit isn't hit early.
+      splitAtRecencyBoundary(messages, {
+        turns: 1_000_000,
+        tokens: 1_000_000,
+        tokenCounter,
+      });
+
+      // Strictly bounded by messages.length.  No message is counted
+      // twice, regardless of how many turns the splitter walks.
+      expect(calls).toBeLessThanOrEqual(messages.length);
+      expect(calls).toBe(messages.length);
+    });
+
+    it('stops counting once the tokens cap is exceeded (no scan past the boundary)', () => {
+      const messages: BaseMessage[] = [];
+      for (let t = 0; t < 50; t++) {
+        messages.push(new HumanMessage(`turn ${t}`));
+        messages.push(new AIMessage(`reply ${t}`));
+      }
+
+      let calls = 0;
+      const tokenCounter = (): number => {
+        calls += 1;
+        return 1; // 1 token per message → 100 tokens total
+      };
+
+      // Cap of 10 tokens lets us include the last 5 turns (10 messages)
+      // before the next turn's 2 tokens would overflow.
+      const result = splitAtRecencyBoundary(messages, {
+        turns: 1_000,
+        tokens: 10,
+        tokenCounter,
+      });
+
+      // Visited at most: 5 included turns × 2 messages + one over-budget
+      // turn × 2 messages (counted then rejected) = 12 messages.  Far
+      // less than the full 100.
+      expect(calls).toBeLessThanOrEqual(12);
+      expect(result.tailTurnCount).toBe(5);
+    });
+  });
+
+  describe('degenerate inputs', () => {
+    it('puts everything in the head when there is no HumanMessage', () => {
+      const messages = [
+        new SystemMessage('preamble'),
+        new AIMessage('starter'),
+      ];
+      const result = splitAtRecencyBoundary(messages, { turns: 2 });
+      expect(result.head).toEqual(messages);
+      expect(result.tail).toEqual([]);
+      expect(result.tailTurnCount).toBe(0);
+    });
+
+    it('handles a HumanMessage at index 0 with prior non-human messages absent', () => {
+      const messages = [new HumanMessage('only')];
+      const result = splitAtRecencyBoundary(messages, { turns: 3 });
+      expect(result.head).toEqual([]);
+      expect(result.tail).toEqual(messages);
+    });
+
+    it('handles tool messages as the very last messages', () => {
+      const messages = [
+        new HumanMessage('q1'),
+        new AIMessage('a1'),
+        new HumanMessage('q2'),
+        new AIMessage({
+          content: '',
+          tool_calls: [{ id: 'c1', name: 't', args: {} }],
+        }),
+        new ToolMessage({ content: 'r', tool_call_id: 'c1', name: 't' }),
+      ];
+      const result = splitAtRecencyBoundary(messages, { turns: 1 });
+      // Most recent turn includes the trailing tool result.
+      expect(result.tail).toEqual(messages.slice(2));
+      expect(result.head).toEqual(messages.slice(0, 2));
+    });
+  });
+});

package/src/messages/anthropicToolCache.ts

@@ -0,0 +1,116 @@
+/**
+ * Anthropic prompt-caching helper for the `tools[]` request field.
+ *
+ * Anthropic accepts `cache_control: { type: 'ephemeral' }` on individual
+ * tool definitions. Whichever tool carries the marker becomes the end of
+ * a cached prefix: `tools[0..N]` (everything up to and including the
+ * marked tool) is cached and rebated on subsequent matching requests.
+ *
+ * For agents that mix static and deferred (lazily-discovered) tools, the
+ * winning configuration is:
+ *
+ *   1. Stable-partition tools so all *static* (non-deferred) tools come
+ *      first and discovered-deferred tools come last.
+ *   2. Stamp `cache_control` on the LAST static tool.
+ *
+ * That way, the cached prefix covers exactly the static tool inventory.
+ * Discovered tools that show up later (or vary turn-to-turn as new ones
+ * get discovered) never invalidate the prefix because they sit *after*
+ * the breakpoint.
+ *
+ * LangChain's Anthropic adapter passes the marker through via
+ * `tool.extras.cache_control` (`AnthropicToolExtrasSchema`), so we set
+ * it as an `extras` field on a fresh wrapper around the tool — never
+ * mutating the original tool instance, since callers may share them
+ * across runs.
+ */
+
+import type { GraphTools } from '@/types';
+
+/**
+ * Returns a callable that reports whether a given tool *name* is deferred
+ * according to the supplied registry of tool definitions. Tools without
+ * a registry entry are treated as non-deferred (i.e. static), matching
+ * the host-supplied `graphTools` semantics elsewhere in the SDK.
+ */
+export function makeIsDeferred(
+  toolDefinitions:
+    | ReadonlyArray<{ name: string; defer_loading?: boolean }>
+    | undefined
+): (toolName: string) => boolean {
+  if (toolDefinitions == null || toolDefinitions.length === 0) {
+    return () => false;
+  }
+  const deferred = new Set<string>();
+  for (const def of toolDefinitions) {
+    if (def.defer_loading === true) deferred.add(def.name);
+  }
+  if (deferred.size === 0) return () => false;
+  return (name) => deferred.has(name);
+}
+
+/**
+ * Stable-partition `tools` into [static..., deferred...] and stamp the
+ * Anthropic `cache_control: ephemeral` marker on the last static tool.
+ *
+ * If `tools` is undefined or empty, or no entry has a usable `.name`,
+ * returns the input unchanged. If there are no static tools at all,
+ * also returns unchanged (nothing to cache).
+ *
+ * The original tool instances are never mutated. The marked entry is a
+ * shallow wrapper that preserves the prototype chain so downstream
+ * `instanceof` checks still pass. `extras` is merged so any existing
+ * `providerToolDefinition` / other extras the host attached are kept.
+ */
+export function partitionAndMarkAnthropicToolCache(
+  tools: GraphTools | undefined,
+  isDeferred: (toolName: string) => boolean
+): GraphTools | undefined {
+  if (tools == null || tools.length === 0) return tools;
+
+  // Use unknown[] internally to avoid GraphTools' union-array variance
+  // (each member is one of three array types). We cast back to
+  // GraphTools when returning.
+  const staticTools: unknown[] = [];
+  const deferredTools: unknown[] = [];
+
+  for (const tool of tools) {
+    const name = (tool as { name?: unknown }).name;
+    if (typeof name === 'string' && isDeferred(name)) {
+      deferredTools.push(tool);
+    } else {
+      staticTools.push(tool);
+    }
+  }
+
+  if (staticTools.length === 0) {
+    return tools;
+  }
+
+  const last = staticTools[staticTools.length - 1] as {
+    extras?: Record<string, unknown>;
+  };
+  // Already marked? Don't double-clone.
+  if (
+    last.extras != null &&
+    'cache_control' in last.extras &&
+    (last.extras as { cache_control?: unknown }).cache_control != null
+  ) {
+    if (deferredTools.length === 0) return tools;
+    return [...staticTools, ...deferredTools] as GraphTools;
+  }
+
+  const wrapped = Object.assign(
+    Object.create(Object.getPrototypeOf(last) ?? Object.prototype),
+    last,
+    {
+      extras: {
+        ...((last.extras as Record<string, unknown> | undefined) ?? {}),
+        cache_control: { type: 'ephemeral' as const },
+      },
+    }
+  );
+
+  staticTools[staticTools.length - 1] = wrapped;
+  return [...staticTools, ...deferredTools] as GraphTools;
+}

package/src/messages/index.ts

@@ -3,8 +3,10 @@ export * from './ids';
 export * from './prune';
 export * from './format';
 export * from './cache';
+export * from './anthropicToolCache';
 export * from './content';
 export * from './tools';
 export * from './contextPruning';
 export * from './contextPruningSettings';
 export * from './reducer';
+export * from './recency';

package/src/messages/prune.ts

@@ -50,7 +50,33 @@ const PRESSURE_BANDS: [number, number][] = [
 const MASKED_RESULT_MAX_CHARS = 300;
 
 /** Hard cap for the originalToolContent store (~2 MB estimated from char length). */
-const ORIGINAL_CONTENT_MAX_CHARS = 2_000_000;
+export const ORIGINAL_CONTENT_MAX_CHARS = 2_000_000;
+
+/**
+ * Evicts oldest entries from `map` (in Map-iteration / insertion order) until
+ * the cumulative char length of remaining values fits within
+ * `ORIGINAL_CONTENT_MAX_CHARS`.  Used by the recency-window carry-over merge
+ * path in Graph.ts to bound long-running session memory: the pruner enforces
+ * the cap inside its own `originalToolContent` map, but a key-wise union with
+ * recency carry-over bypasses that cap unless re-applied here.
+ */
+export function enforceOriginalContentCap(map: Map<number, string>): void {
+  let total = 0;
+  for (const v of map.values()) {
+    total += v.length;
+  }
+  while (total > ORIGINAL_CONTENT_MAX_CHARS && map.size > 0) {
+    const oldest = map.keys().next();
+    if (oldest.done === true) {
+      break;
+    }
+    const removed = map.get(oldest.value);
+    if (removed != null) {
+      total -= removed.length;
+    }
+    map.delete(oldest.value);
+  }
+}
 
 /** Minimum cumulative calibration ratio — provider can't count fewer tokens
  *  than our raw estimate (within reason). Prevents divide-by-zero edge cases. */

package/src/messages/recency.ts

@@ -0,0 +1,155 @@
+import type { BaseMessage } from '@langchain/core/messages';
+
+/**
+ * Configuration for splitting a message list into a head (to be summarized)
+ * and a tail (to be preserved verbatim).
+ */
+export interface RecencyWindowOptions {
+  /**
+   * Maximum number of recent user-led turns to keep in the tail.  A "turn"
+   * begins at a HumanMessage and includes every following AIMessage and
+   * ToolMessage up to (but not including) the next HumanMessage.  Cutting
+   * at turn boundaries guarantees that tool_use / tool_result pairs are
+   * never split across the head/tail divide.
+   *
+   * The most recent turn is always preserved regardless of this value or
+   * the token cap, so that a single oversized first message is never
+   * destroyed by summarization.
+   *
+   * Defaults to `2`.  A value of `0` disables the recency window (head =
+   * everything, tail = empty), restoring the pre-recency-window behavior.
+   */
+  turns?: number;
+  /**
+   * Optional cap on tail size in tokens.  When set, additional turns
+   * beyond the most recent one are added to the tail only while the
+   * cumulative token count stays at or below this cap.  Turns are added
+   * whole — never partially — so a turn that would exceed the cap is
+   * left in the head.
+   *
+   * The most recent turn is always preserved even if it exceeds the cap.
+   */
+  tokens?: number;
+  /** Token-counter used to evaluate the optional `tokens` cap. */
+  tokenCounter?: (m: BaseMessage) => number;
+}
+
+export interface RecencySplit {
+  /** Older messages eligible for summarization.  Empty when nothing to summarize. */
+  head: BaseMessage[];
+  /** Recent messages preserved verbatim.  Always contains the most recent turn when any HumanMessage exists. */
+  tail: BaseMessage[];
+  /** Number of user-led turns retained in the tail (0 if no HumanMessage exists). */
+  tailTurnCount: number;
+  /** Index in the original `messages` array where the tail begins. */
+  tailStartIndex: number;
+}
+
+/**
+ * Splits `messages` into a head (older, to summarize) and a tail (recent,
+ * to preserve verbatim) at user-message boundaries.  The most recent
+ * user-led turn is always included in the tail; additional older turns
+ * are added subject to `turns` and `tokens` caps.
+ *
+ * Cutting strictly at HumanMessage boundaries ensures that:
+ * - tool_use ↔ tool_result pairs are never split (they always live within
+ *   the same turn);
+ * - the first user message is never replaced by a summary, addressing
+ *   the "first turn destruction" failure mode where a single large
+ *   user-pasted payload would otherwise be replaced by a generic summary.
+ *
+ * When `messages` contains no HumanMessage (degenerate state — e.g. system
+ * + assistant messages from a programmatic preamble), everything is
+ * placed in the head and the tail is empty.  The summarize node treats
+ * an empty tail as "nothing recent to preserve" and falls through to its
+ * existing logic.
+ */
+export function splitAtRecencyBoundary(
+  messages: BaseMessage[],
+  options: RecencyWindowOptions = {}
+): RecencySplit {
+  const turnsCap = options.turns ?? 2;
+
+  if (messages.length === 0 || turnsCap <= 0) {
+    return {
+      head: messages,
+      tail: [],
+      tailTurnCount: 0,
+      tailStartIndex: messages.length,
+    };
+  }
+
+  const turnStarts: number[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].getType() === 'human') {
+      turnStarts.push(i);
+    }
+  }
+
+  if (turnStarts.length === 0) {
+    return {
+      head: messages,
+      tail: [],
+      tailTurnCount: 0,
+      tailStartIndex: messages.length,
+    };
+  }
+
+  const lastTurnStart = turnStarts[turnStarts.length - 1] as number;
+  let tailStartIndex = lastTurnStart;
+  let tailTurnCount = 1;
+
+  const tokensCap = options.tokens;
+  const tokenCounter = options.tokenCounter;
+  const trackTokens =
+    tokensCap != null && Number.isFinite(tokensCap) && tokenCounter != null;
+
+  /**
+   * Token-counting strategy: each candidate turn `t` spans the half-open
+   * range `[turnStarts[t], turnStarts[t + 1])` (or `[turnStarts[t], messages.length)`
+   * for the most recent turn).  Successive iterations of the outer loop
+   * walk older turns one at a time and never revisit messages from a
+   * later turn — so each message contributes to `tokenCounter` at most
+   * once across the entire selection, making the boundary search
+   * `O(messages_in_visited_turns)` and bounded by `O(messages.length)`
+   * even before the `turnsCap` short-circuit applies.  The inner upper
+   * bound uses `turnStarts[t + 1]` (a value derived from immutable
+   * `turnStarts`) rather than the mutated `tailStartIndex` to make the
+   * disjoint-range invariant self-evident.
+   */
+  let tailTokens = 0;
+  if (trackTokens) {
+    for (let i = lastTurnStart; i < messages.length; i++) {
+      tailTokens += tokenCounter(messages[i] as BaseMessage);
+    }
+  }
+
+  for (let t = turnStarts.length - 2; t >= 0; t--) {
+    if (tailTurnCount >= turnsCap) {
+      break;
+    }
+    const turnStart = turnStarts[t] as number;
+    const turnEnd = turnStarts[t + 1] as number;
+
+    if (trackTokens) {
+      let turnTokens = 0;
+      for (let i = turnStart; i < turnEnd; i++) {
+        turnTokens += tokenCounter(messages[i] as BaseMessage);
+      }
+      if (tailTokens + turnTokens > (tokensCap as number)) {
+        break;
+      }
+      tailTokens += turnTokens;
+    }
+
+    tailStartIndex = turnStart;
+    tailTurnCount += 1;
+  }
+
+  return {
+    head: messages.slice(0, tailStartIndex),
+    tail: messages.slice(tailStartIndex),
+    tailTurnCount,
+    tailStartIndex,
+  };
+}

package/src/run.ts

@@ -54,6 +54,7 @@ export class Run<_T extends t.BaseGraphState> {
   private hookRegistry?: HookRegistry;
   private humanInTheLoop?: t.HumanInTheLoopConfig;
   private toolOutputReferences?: t.ToolOutputReferencesConfig;
+  private toolExecution?: t.ToolExecutionConfig;
   private indexTokenCountMap?: Record<string, number>;
   calibrationRatio: number = 1;
   graphRunnable?: t.CompiledStateWorkflow;
@@ -98,6 +99,7 @@ export class Run<_T extends t.BaseGraphState> {
     this.hookRegistry = config.hooks;
     this.humanInTheLoop = config.humanInTheLoop;
     this.toolOutputReferences = config.toolOutputReferences;
+    this.toolExecution = config.toolExecution;
 
     if (!config.graphConfig) {
       throw new Error('Graph config not provided');
@@ -178,6 +180,7 @@ export class Run<_T extends t.BaseGraphState> {
     standardGraph.hookRegistry = this.hookRegistry;
     standardGraph.humanInTheLoop = this.humanInTheLoop;
     standardGraph.toolOutputReferences = this.toolOutputReferences;
+    standardGraph.toolExecution = this.toolExecution;
     this.Graph = standardGraph;
     return standardGraph.createWorkflow();
   }
@@ -202,6 +205,7 @@ export class Run<_T extends t.BaseGraphState> {
     multiAgentGraph.hookRegistry = this.hookRegistry;
     multiAgentGraph.humanInTheLoop = this.humanInTheLoop;
     multiAgentGraph.toolOutputReferences = this.toolOutputReferences;
+    multiAgentGraph.toolExecution = this.toolExecution;
     this.Graph = multiAgentGraph;
     return multiAgentGraph.createWorkflow();
   }
@@ -898,6 +902,33 @@ export class Run<_T extends t.BaseGraphState> {
    * graph state from the checkpoint and re-enters the interrupted node
    * from the start.
    */
+  /**
+   * Returns the per-Run file checkpointer when
+   * `toolExecution.local.fileCheckpointing === true` was set on the
+   * RunConfig. Hosts can capture extra paths or call `rewind()`
+   * directly. Returns undefined when checkpointing is disabled.
+   *
+   * Construction-time invariant: the checkpointer is shared across
+   * every ToolNode the graph compiles (single-agent and multi-agent),
+   * so a `rewind()` call here unwinds writes made by ANY agent in the
+   * run.
+   */
+  getFileCheckpointer(): t.LocalFileCheckpointer | undefined {
+    return this.Graph?.getOrCreateFileCheckpointer();
+  }
+
+  /**
+   * Convenience wrapper that calls `rewind()` on the per-Run file
+   * checkpointer. Restores every file the local engine snapshotted
+   * during this Run to its pre-write content (and deletes any path
+   * that didn't exist before being created). Returns the count of
+   * paths processed; returns 0 when checkpointing is disabled.
+   */
+  async rewindFiles(): Promise<number> {
+    const cp = this.getFileCheckpointer();
+    return cp == null ? 0 : cp.rewind();
+  }
+
   async resume<TResume = t.ToolApprovalDecision[] | t.ToolApprovalDecisionMap>(
     resumeValue: TResume,
     callerConfig: Partial<RunnableConfig> & {