@librechat/agents 3.1.77-dev.1 → 3.1.78-dev.0

package/src/graphs/Graph.ts

@@ -20,10 +20,13 @@ import {
   extractToolDiscoveries,
   addBedrockCacheControl,
   formatArtifactPayload,
+  enforceOriginalContentCap,
   formatContentStrings,
   createPruneMessages,
   addCacheControl,
   getMessageId,
+  makeIsDeferred,
+  partitionAndMarkAnthropicToolCache,
 } from '@/messages';
 import {
   GraphNodeKeys,
@@ -53,6 +56,8 @@ import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
 import { createFakeStreamingLLM } from '@/llm/fake';
 import { handleToolCalls } from '@/tools/handlers';
+import { resolveLocalToolsForBinding } from '@/tools/local';
+import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
 import { isThinkingEnabled } from '@/llm/request';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
@@ -142,6 +147,11 @@ export abstract class Graph<
    * graph compiles.
    */
   toolOutputReferences: t.ToolOutputReferencesConfig | undefined;
+  /**
+   * Run-scoped execution backend for built-in code tools. Defaults to the
+   * remote Code API sandbox when unset.
+   */
+  toolExecution: t.ToolExecutionConfig | undefined;
   /**
    * Shared registry instance used by every ToolNode compiled from this
    * graph. Lazily constructed on first access so multi-agent graphs
@@ -176,6 +186,7 @@ export abstract class Graph<
     this.hookRegistry = undefined;
     this.humanInTheLoop = undefined;
     this.toolOutputReferences = undefined;
+    this.toolExecution = undefined;
     /**
      * ToolNodes compiled from this graph captured the registry
      * instance at construction time, so simply dropping the Graph's
@@ -186,9 +197,38 @@ export abstract class Graph<
      */
     this._toolOutputRegistry?.clear();
     this._toolOutputRegistry = undefined;
+    // NB: `_fileCheckpointer` is intentionally NOT cleared here.
+    // `Run.processStream()` calls `clearHeavyState()` in its
+    // finally block on natural-completion / error paths — exactly
+    // when the host is most likely to want `Run.rewindFiles()` (for
+    // rollback after a failed batch). Per-Run isolation is already
+    // automatic because each `Run.create()` constructs a brand-new
+    // Graph instance, so the next Run gets its own checkpointer
+    // without us needing to reset this field. Codex P1 #32: pre-fix
+    // the checkpointer was nulled before the caller could reach it.
+    // Flush each compiled ToolNode's direct-path turn cache so it
+    // doesn't leak across Runs (Codex P2 #33). The cache survives
+    // `run()` re-entry by design (resume-stable), but end-of-Run
+    // is the right point to reset it.
+    for (const node of this._compiledToolNodes) {
+      node.clearDirectPathTurns();
+    }
+    this._compiledToolNodes.clear();
     this.sessions.clear();
   }
 
+  /**
+   * Subclass hook to register a freshly compiled ToolNode so
+   * `clearHeavyState` can flush its per-Run direct-path turn cache
+   * at end-of-Run. Internal — called from `initializeTools` in the
+   * concrete graph subclasses.
+   */
+  protected registerCompiledToolNode(node: {
+    clearDirectPathTurns(): void;
+  }): void {
+    this._compiledToolNodes.add(node);
+  }
+
   /**
    * Returns the shared `ToolOutputReferenceRegistry` for this run,
    * constructing it on first access. Returns `undefined` when the
@@ -216,6 +256,56 @@ export abstract class Graph<
     }
     return this._toolOutputRegistry;
   }
+
+  /**
+   * Single per-Run file checkpointer shared across every ToolNode the
+   * graph compiles. Lazily constructed when
+   * `toolExecution.local.fileCheckpointing === true` so multi-agent
+   * graphs see ONE snapshot store, not one-per-agent. Returns
+   * undefined when checkpointing is disabled or the local engine
+   * isn't selected. Exposed via `Run.getFileCheckpointer()` /
+   * `Run.rewindFiles()`.
+   */
+  private _fileCheckpointer?: t.LocalFileCheckpointer;
+  /**
+   * ToolNodes compiled into this Graph's workflow. Tracked so
+   * `clearHeavyState()` can flush their per-Run direct-path turn
+   * cache (`directPathTurns`) at end-of-Run — that map intentionally
+   * survives `run()` re-entry (resume-stable per Codex P2 #30) but
+   * would otherwise grow linearly with tool calls and could collide
+   * across Runs if a provider reuses call ids (Codex P2 #33).
+   */
+  private _compiledToolNodes: Set<{
+    clearDirectPathTurns(): void;
+  }> = new Set();
+  public getOrCreateFileCheckpointer():
+    | t.LocalFileCheckpointer
+    | undefined {
+    // Return the cached instance unconditionally if one exists. The
+    // toolExecution check below decides whether to *create* a new
+    // one — `clearHeavyState` nulls `this.toolExecution` at end-of-
+    // Run, but we want post-Run `Run.rewindFiles()` to still resolve
+    // to the checkpointer that captured the writes. Codex P1 #32.
+    if (this._fileCheckpointer != null) {
+      return this._fileCheckpointer;
+    }
+    if (
+      this.toolExecution?.engine !== 'local' ||
+      this.toolExecution.local?.fileCheckpointing !== true
+    ) {
+      return undefined;
+    }
+    // Eagerly create via the bundle factory so the construction path
+    // matches the bundle-only callers (and future bundle-internal
+    // cleanup hooks fire). The bundle factory itself accepts a pre-
+    // supplied checkpointer when present, so re-injecting this one
+    // into every ToolNode is idempotent.
+    const bundle = createLocalCodingToolBundle(
+      this.toolExecution.local ?? {}
+    );
+    this._fileCheckpointer = bundle.checkpointer;
+    return this._fileCheckpointer;
+  }
 }
 
 export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
@@ -577,7 +667,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
       }
 
-      return new CustomToolNode<t.BaseGraphState>({
+      const node = new CustomToolNode<t.BaseGraphState>({
         tools: allTools,
         toolMap: allToolMap,
         eventDrivenMode: true,
@@ -588,13 +678,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         toolRegistry: agentContext?.toolRegistry,
         hookRegistry: this.hookRegistry,
         humanInTheLoop: this.humanInTheLoop,
+        toolExecution: this.toolExecution,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,
         toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
-        errorHandler: (data, metadata) =>
+        fileCheckpointer: this.getOrCreateFileCheckpointer(),
+        errorHandler: (data, metadata): Promise<void> =>
           StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       });
+      this.registerCompiledToolNode(node);
+      return node;
     }
 
     const graphTools = agentContext?.graphTools as t.GenericTool[] | undefined;
@@ -613,18 +707,24 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         ])
         : currentToolMap;
 
-    return new CustomToolNode<t.BaseGraphState>({
+    const node = new CustomToolNode<t.BaseGraphState>({
       tools: allTraditionalTools,
       toolMap: traditionalToolMap,
       toolCallStepIds: this.toolCallStepIds,
-      errorHandler: (data, metadata) =>
+      errorHandler: (data, metadata): Promise<void> =>
         StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       toolRegistry: agentContext?.toolRegistry,
       sessions: this.sessions,
+      toolExecution: this.toolExecution,
+      hookRegistry: this.hookRegistry,
+      humanInTheLoop: this.humanInTheLoop,
       maxContextTokens: agentContext?.maxContextTokens,
       maxToolResultChars: agentContext?.maxToolResultChars,
       toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
+      fileCheckpointer: this.getOrCreateFileCheckpointer(),
     });
+    this.registerCompiledToolNode(node);
+    return node;
   }
 
   overrideTestModel(
@@ -688,7 +788,37 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         agentContext.markToolsAsDiscovered(discoveredNames);
       }
 
-      const toolsForBinding = agentContext.getToolsForBinding();
+      const rawToolsForBinding = resolveLocalToolsForBinding({
+        tools: agentContext.getToolsForBinding(),
+        toolExecution: this.toolExecution,
+      });
+
+      /**
+       * Anthropic prompt-cache breakpoint on the tool definitions.
+       *
+       * Without this, the (often static) tool inventory shows up as
+       * fresh input on every turn — measured at ~28k tokens/turn for
+       * the local engine's coding-tool bundle, dominating per-turn
+       * cost even when message-level caching is on.
+       *
+       * Strategy: partition tools into [static, deferred] and stamp
+       * `cache_control: ephemeral` on the last static tool.
+       * Discovered deferred tools that arrive across turns sit *after*
+       * the breakpoint and don't invalidate the prefix.
+       */
+      let toolsForBinding = rawToolsForBinding;
+      if (
+        agentContext.provider === Providers.ANTHROPIC &&
+        (agentContext.clientOptions as t.AnthropicClientOptions | undefined)
+          ?.promptCache === true
+      ) {
+        toolsForBinding =
+          partitionAndMarkAnthropicToolCache(
+            rawToolsForBinding,
+            makeIsDeferred(agentContext.toolDefinitions)
+          ) ?? rawToolsForBinding;
+      }
+
       let model =
         this.overrideModel ??
         initializeModel({
@@ -804,7 +934,35 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
           if (triggerResult) {
             if (originalToolContent != null && originalToolContent.size > 0) {
-              agentContext.pendingOriginalToolContent = originalToolContent;
+              /**
+               * Merge — never overwrite — the pruner's masking record
+               * into pendingOriginalToolContent.  Carry-over entries
+               * from a prior summarize (preserved by the recency
+               * window for masked tool messages still in the tail) and
+               * the current pruner's new entries are both keyed by
+               * indices in the current `state.messages`, so a key-wise
+               * union is correct.  Overwriting would discard the
+               * carry-over and reduce summary fidelity when those
+               * masked tail messages eventually move into the head.
+               */
+              if (agentContext.pendingOriginalToolContent == null) {
+                agentContext.pendingOriginalToolContent = originalToolContent;
+              } else {
+                for (const [idx, content] of originalToolContent) {
+                  agentContext.pendingOriginalToolContent.set(idx, content);
+                }
+                /**
+                 * Re-apply the per-store char cap after the union.  The
+                 * pruner enforces ORIGINAL_CONTENT_MAX_CHARS inside its
+                 * own map via the onContentStored callback, but a
+                 * key-wise merge with recency carry-over bypasses that
+                 * accounting and could let the merged map grow without
+                 * bound across long sessions.
+                 */
+                enforceOriginalContentCap(
+                  agentContext.pendingOriginalToolContent
+                );
+              }
             }
 
             emitAgentLog(

package/src/hooks/__tests__/compactHooks.test.ts

@@ -58,7 +58,14 @@ function buildConversation(): t.IState {
 async function createCompactingRun(
   tokenCounter: t.TokenCounter,
   hooks?: HookRegistry,
-  runId = 'compact-run'
+  runId = 'compact-run',
+  /**
+   * Recency-window setting.  Defaults to `{ turns: 0 }` for these tests so
+   * the post-compaction state is the legacy "remove-all only" shape, which
+   * the original assertions were written against.  Tests that want to
+   * exercise the recency-window path should pass an explicit value.
+   */
+  retainRecent: { turns: number } = { turns: 0 }
 ): Promise<Run<t.IState>> {
   const conversation = buildConversation();
   const indexTokenCountMap: Record<string, number> = {};
@@ -79,6 +86,7 @@ async function createCompactingRun(
       summarizationEnabled: true,
       summarizationConfig: {
         provider: Providers.OPENAI,
+        retainRecent,
       },
     },
     returnContent: true,
@@ -138,7 +146,7 @@ describe('Compaction hook integration', () => {
   });
 
   describe('PostCompact', () => {
-    it('fires with summary text after compaction', async () => {
+    it('fires with summary text after compaction (legacy retainRecent.turns=0 shape)', async () => {
       const registry = new HookRegistry();
       let captured: PostCompactHookInput | undefined;
       const hook: HookCallback<'PostCompact'> = async (
@@ -161,6 +169,34 @@ describe('Compaction hook integration', () => {
       expect(captured!.messagesAfterCount).toBe(0);
       expect(captured!.agentId).toBeDefined();
     });
+
+    it('reports the recency-tail length in messagesAfterCount when retainRecent.turns > 0', async () => {
+      const registry = new HookRegistry();
+      let captured: PostCompactHookInput | undefined;
+      const hook: HookCallback<'PostCompact'> = async (
+        input
+      ): Promise<PostCompactHookOutput> => {
+        captured = input;
+        return {};
+      };
+      registry.register('PostCompact', { hooks: [hook] });
+
+      const run = await createCompactingRun(
+        tokenCounter,
+        registry,
+        'compact-recency-run',
+        { turns: 2 }
+      );
+      run.Graph!.overrideTestModel(['Final answer after compaction.']);
+      const inputs = buildConversation();
+      await run.processStream(inputs, callerConfig);
+
+      expect(captured).toBeDefined();
+      expect(captured!.hook_event_name).toBe('PostCompact');
+      // buildConversation produces 20 user-led turns of [user, ai].  With
+      // retainRecent.turns=2, the tail is the last 2 turns = 4 messages.
+      expect(captured!.messagesAfterCount).toBe(4);
+    });
   });
 
   describe('error resilience', () => {