@librechat/agents 3.3.9 → 3.3.10

package/src/graphs/Graph.ts

@@ -643,6 +643,10 @@ export abstract class Graph<
     currentToolMap?: t.ToolMap;
   }): CustomToolNode<T> | ToolNode<T>;
   abstract getRunMessages(): BaseMessage[] | undefined;
+  /** Returns a snapshot of deferred tools discovered by this graph. */
+  getDiscoveredTools(_agentId?: string): string[] {
+    return [];
+  }
   abstract getContentParts(): t.MessageContentComplex[] | undefined;
   abstract generateStepId(stepKey: string): [string, number];
   abstract getKeyList(
@@ -1006,6 +1010,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   messages: BaseMessage[] = [];
   /** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
   private cachedRunMessages?: BaseMessage[];
+  /** Per-agent discovery snapshots preserved before contexts are reset on cleanup. */
+  private cachedDiscoveredTools?: Map<string, string[]>;
   /** Ids of AI turns the agent node returned THIS run; see isRunProducedMessage. */
   protected runProducedAiMessageIds = new Set<string>();
   /** Checkpoint scope whose messages match index-keyed tool snapshots. */
@@ -1137,6 +1143,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   resetValues(keepContent?: boolean, checkpointScope?: string): void {
     this.messages = [];
     this.cachedRunMessages = undefined;
+    this.cachedDiscoveredTools = undefined;
     this.config = resetIfNotEmpty(this.config, undefined);
     if (keepContent !== true) {
       this.contentData = resetIfNotEmpty(this.contentData, []);
@@ -1203,6 +1210,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
   override clearHeavyState(): void {
     this.cachedRunMessages = this.messages.slice(this.startIndex);
+    this.cachedDiscoveredTools = new Map(
+      Array.from(this.agentContexts, ([agentId, context]) => [
+        agentId,
+        context.getDiscoveredTools(),
+      ])
+    );
     super.clearHeavyState();
     this.messages = [];
     this.overrideModel = undefined;
@@ -1497,6 +1510,32 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     return this.messages.slice(this.startIndex);
   }
 
+  override getDiscoveredTools(agentId?: string): string[] {
+    if (agentId != null) {
+      const current =
+        this.agentContexts.get(agentId)?.getDiscoveredTools() ?? [];
+      if (current.length > 0 || this.cachedDiscoveredTools == null) {
+        return current;
+      }
+      return [...(this.cachedDiscoveredTools.get(agentId) ?? [])];
+    }
+
+    const discoveredTools = new Set<string>();
+    for (const context of this.agentContexts.values()) {
+      for (const toolName of context.getDiscoveredTools()) {
+        discoveredTools.add(toolName);
+      }
+    }
+    if (discoveredTools.size === 0 && this.cachedDiscoveredTools != null) {
+      for (const snapshot of this.cachedDiscoveredTools.values()) {
+        for (const toolName of snapshot) {
+          discoveredTools.add(toolName);
+        }
+      }
+    }
+    return Array.from(discoveredTools);
+  }
+
   /**
    * True when THIS RUN produced `message` — the provenance the handoff cue
    * gate needs. Tracked as an id set rather than inferred from `startIndex`

package/src/run.ts

@@ -538,6 +538,21 @@ export class Run<_T extends t.BaseGraphState> {
     return this.Graph.getRunMessages();
   }
 
+  /**
+   * Returns a defensive snapshot of tools discovered by the current run.
+   * Pass an agent id for that context, or omit it for the ordered union across
+   * contexts. Interrupted state is available immediately for host persistence;
+   * completed runs retain their final snapshot through graph cleanup.
+   */
+  getDiscoveredTools(agentId?: string): string[] {
+    if (!this.Graph) {
+      throw new Error(
+        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'
+      );
+    }
+    return this.Graph.getDiscoveredTools(agentId);
+  }
+
   /**
    * Returns the current calibration ratio (EMA of provider-vs-estimate token ratios).
    * Hosts should persist this value and pass it back as `RunConfig.calibrationRatio`

package/src/specs/discovered-tools.test.ts

@@ -0,0 +1,217 @@
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+import { MemorySaver } from '@langchain/langgraph';
+import { HumanMessage } from '@langchain/core/messages';
+import { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { FakeChatModel } from '@/llm/fake';
+import { StandardGraph } from '@/graphs';
+import { askUserQuestion } from '@/hitl';
+import { Providers } from '@/common';
+import { Run } from '@/run';
+
+const DISCOVERED_TOOL = 'save_issue_mcp_linear';
+
+const searchTool = tool(
+  async ({ query }) => [
+    JSON.stringify({
+      found: 1,
+      tools: [{ name: DISCOVERED_TOOL }],
+      query,
+    }),
+    { tool_references: [{ tool_name: DISCOVERED_TOOL }] },
+  ],
+  {
+    name: 'tool_search',
+    description: 'Find a deferred tool.',
+    schema: z.object({ query: z.string() }),
+    responseFormat: 'content_and_artifact',
+  }
+);
+
+const askTool = tool(
+  async (input) => {
+    const { answer } = askUserQuestion(input);
+    return answer;
+  },
+  {
+    name: 'ask_user_question',
+    description: 'Pause until the user answers a question.',
+    schema: z.object({ question: z.string() }),
+  }
+);
+
+class DiscoveryThenAskModel extends FakeChatModel {
+  private turn = 0;
+
+  constructor() {
+    super({ responses: ['', ''] });
+  }
+
+  async *_streamResponseChunks(
+    _messages: BaseMessage[],
+    _options: this['ParsedCallOptions'],
+    _runManager?: CallbackManagerForLLMRun
+  ): AsyncGenerator<ChatGenerationChunk> {
+    const calls: ToolCall[][] = [
+      [
+        {
+          name: 'tool_search',
+          args: { query: 'save_issue' },
+          id: 'search-call',
+          type: 'tool_call',
+        },
+      ],
+      [
+        {
+          name: 'ask_user_question',
+          args: { question: 'Proceed?' },
+          id: 'ask-call',
+          type: 'tool_call',
+        },
+      ],
+    ];
+    const toolCallChunks = calls[this.turn++].map(
+      (call, index): ToolCallChunk => ({
+        name: call.name,
+        args: JSON.stringify(call.args),
+        id: call.id,
+        index,
+        type: 'tool_call_chunk',
+      })
+    );
+    yield this._createResponseChunk('', toolCallChunks);
+  }
+}
+
+describe('Run discovered tools', () => {
+  it('exposes discoveries made before an ask-user pause', async () => {
+    const run = await Run.create<t.IState>({
+      runId: 'discovery-pause-run',
+      graphConfig: {
+        type: 'standard',
+        llmConfig: {
+          provider: Providers.OPENAI,
+          model: 'gpt-4o-mini',
+          streaming: true,
+          streamUsage: false,
+        },
+        instructions: 'Search first, then ask the user.',
+        tools: [searchTool, askTool],
+        compileOptions: { checkpointer: new MemorySaver() },
+      },
+      returnContent: true,
+      customHandlers: {},
+    });
+    run.Graph!.overrideModel = new DiscoveryThenAskModel();
+
+    await run.processStream(
+      { messages: [new HumanMessage('Create a Linear issue')] },
+      {
+        configurable: { thread_id: 'discovery-pause-thread' },
+        version: 'v2',
+      }
+    );
+
+    expect(run.getInterrupt()?.payload.type).toBe('ask_user_question');
+    // The interrupted inner subgraph has not returned its messages to the outer
+    // reducer, which is why reconstructing discoveries from run history fails.
+    expect(run.getRunMessages()).toEqual([]);
+    expect(run.getDiscoveredTools()).toEqual([DISCOVERED_TOOL]);
+
+    const snapshot = run.getDiscoveredTools();
+    snapshot.push('caller-mutation');
+    expect(run.getDiscoveredTools()).toEqual([DISCOVERED_TOOL]);
+  });
+
+  it('retains the last snapshot when normal cleanup resets agent contexts', async () => {
+    const run = await Run.create<t.IState>({
+      runId: 'discovery-cleanup-run',
+      graphConfig: {
+        type: 'standard',
+        llmConfig: {
+          provider: Providers.OPENAI,
+          model: 'gpt-4o-mini',
+        },
+        instructions: 'Test discovery cleanup.',
+      },
+    });
+    const graph = run.Graph as StandardGraph;
+    graph.agentContexts
+      .get(graph.defaultAgentId)
+      ?.markToolsAsDiscovered([DISCOVERED_TOOL]);
+
+    graph.clearHeavyState();
+
+    expect(run.getDiscoveredTools()).toEqual([DISCOVERED_TOOL]);
+  });
+
+  it('supports per-agent snapshots while returning a deduplicated union by default', async () => {
+    const run = await Run.create<t.IState>({
+      runId: 'multi-agent-discovery-run',
+      graphConfig: {
+        type: 'multi-agent',
+        agents: [
+          {
+            agentId: 'researcher',
+            provider: Providers.ANTHROPIC,
+            clientOptions: {
+              modelName: 'claude-haiku-4-5',
+              apiKey: 'test-key',
+            },
+            instructions: 'Research.',
+          },
+          {
+            agentId: 'writer',
+            provider: Providers.ANTHROPIC,
+            clientOptions: {
+              modelName: 'claude-haiku-4-5',
+              apiKey: 'test-key',
+            },
+            instructions: 'Write.',
+          },
+        ],
+        edges: [{ from: 'researcher', to: 'writer', edgeType: 'direct' }],
+      },
+    });
+    const graph = run.Graph as StandardGraph;
+    graph.agentContexts
+      .get('researcher')
+      ?.markToolsAsDiscovered(['shared_tool', 'research_tool']);
+    graph.agentContexts
+      .get('writer')
+      ?.markToolsAsDiscovered(['shared_tool', 'writing_tool']);
+
+    expect(run.getDiscoveredTools('researcher')).toEqual([
+      'shared_tool',
+      'research_tool',
+    ]);
+    expect(run.getDiscoveredTools('writer')).toEqual([
+      'shared_tool',
+      'writing_tool',
+    ]);
+    expect(run.getDiscoveredTools()).toEqual([
+      'shared_tool',
+      'research_tool',
+      'writing_tool',
+    ]);
+
+    graph.clearHeavyState();
+    expect(run.getDiscoveredTools('researcher')).toEqual([
+      'shared_tool',
+      'research_tool',
+    ]);
+    expect(run.getDiscoveredTools('writer')).toEqual([
+      'shared_tool',
+      'writing_tool',
+    ]);
+    expect(run.getDiscoveredTools()).toEqual([
+      'shared_tool',
+      'research_tool',
+      'writing_tool',
+    ]);
+  });
+});