@librechat/agents 3.4.7 → 3.5.1

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

@@ -1,217 +0,0 @@
-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',
-    ]);
-  });
-});

package/src/specs/durability-checkpoint.integration.test.ts

@@ -1,243 +0,0 @@
-import { MongoClient } from 'mongodb';
-import { HumanMessage } from '@langchain/core/messages';
-import { MongoMemoryServer } from 'mongodb-memory-server-core';
-import { MongoDBSaver } from '@langchain/langgraph-checkpoint-mongodb';
-import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
-import {
-  END,
-  START,
-  Command,
-  Annotation,
-  StateGraph,
-  interrupt,
-} from '@langchain/langgraph';
-import type * as t from '@/types';
-import { Providers } from '@/common';
-import { Run } from '@/run';
-
-/**
- * End-to-end proof against a real Mongo store that the durability default is
- * the storage optimization it claims to be, not just a config flag. A real
- * `Run` with a fake streaming model (no provider API hit) writes through the
- * official MongoDBSaver, and a langgraph interrupt graph exercises the HITL
- * pause/resume boundary. `exit` persists only at the exit/interrupt boundary
- * with no per-superstep writes; `async` checkpoints every superstep.
- */
-describe('durability default — real Mongo checkpointer', () => {
-  let mongod: MongoMemoryServer;
-  let client: MongoClient;
-
-  beforeAll(async () => {
-    // First CI run downloads a mongod binary — allow time beyond the 60s default.
-    mongod = await MongoMemoryServer.create();
-    client = new MongoClient(mongod.getUri());
-    await client.connect();
-  }, 120000);
-
-  afterAll(async () => {
-    await client.close();
-    await mongod.stop();
-  });
-
-  const counts = async (
-    dbName: string
-  ): Promise<{ checkpoints: number; writes: number }> => {
-    const db = client.db(dbName);
-    const [checkpoints, writes] = await Promise.all([
-      db.collection('checkpoints').countDocuments({}),
-      db.collection('checkpoint_writes').countDocuments({}),
-    ]);
-    return { checkpoints, writes };
-  };
-
-  describe('normal run (real Run + fake model)', () => {
-    const runOnce = async (
-      dbName: string,
-      durability?: t.Durability
-    ): Promise<void> => {
-      const run = await Run.create<t.IState>({
-        runId: `durability-${dbName}`,
-        graphConfig: {
-          type: 'standard',
-          agents: [
-            {
-              agentId: 'a',
-              provider: Providers.OPENAI,
-              clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-              instructions: 'noop',
-              maxContextTokens: 8000,
-            },
-          ],
-          compileOptions: {
-            checkpointer: new MongoDBSaver({ client, dbName }),
-          },
-        },
-      });
-      // Fake streaming model: one assistant turn, no tool calls -> agent -> END.
-      run.Graph?.overrideTestModel(['done'], 1);
-      await run.processStream(
-        { messages: [new HumanMessage('hi')] },
-        {
-          version: 'v2',
-          ...(durability != null ? { durability } : {}),
-          configurable: { thread_id: dbName },
-        }
-      );
-    };
-
-    it('exit default writes one checkpoint and no per-superstep writes; async writes more of both', async () => {
-      await runOnce('normal_exit');
-      await runOnce('normal_async', 'async');
-
-      const exitCounts = await counts('normal_exit');
-      const asyncCounts = await counts('normal_async');
-
-      // exit: only the final checkpoint, zero per-superstep pending writes.
-      expect(exitCounts).toEqual({ checkpoints: 1, writes: 0 });
-      // async: a checkpoint plus pending writes for every superstep.
-      expect(asyncCounts.checkpoints).toBeGreaterThan(exitCounts.checkpoints);
-      expect(asyncCounts.writes).toBeGreaterThan(exitCounts.writes);
-    });
-  });
-
-  describe('HITL interrupt (langgraph graph + real saver)', () => {
-    const State = Annotation.Root({
-      steps: Annotation<string[]>({
-        reducer: (a, b) => a.concat(b),
-        default: () => [],
-      }),
-    });
-
-    const drain = async (stream: AsyncIterable<unknown>): Promise<void> => {
-      for await (const _event of stream) {
-        // Consume the event stream exactly like Run.processStream does.
-      }
-    };
-
-    const runInterruptGraph = async (
-      dbName: string,
-      durability: t.Durability
-    ): Promise<{
-      atPause: { checkpoints: number; writes: number };
-      done: { checkpoints: number; writes: number };
-    }> => {
-      const saver = new MongoDBSaver({ client, dbName });
-      const graph = new StateGraph(State)
-        .addNode('a', () => ({ steps: ['a'] }))
-        .addNode('b', () => {
-          interrupt({ ask: 'approve?' });
-          return { steps: ['b'] };
-        })
-        .addNode('c', () => ({ steps: ['c'] }))
-        .addEdge(START, 'a')
-        .addEdge('a', 'b')
-        .addEdge('b', 'c')
-        .addEdge('c', END)
-        .compile({ checkpointer: saver });
-
-      // durability rides in the 2nd-arg config, exactly as run.ts threads it.
-      const cfg = {
-        configurable: { thread_id: dbName },
-        durability,
-        version: 'v2' as const,
-      };
-
-      await drain(graph.streamEvents({ steps: [] }, cfg, { raiseError: true }));
-      const atPause = await counts(dbName);
-
-      await drain(
-        graph.streamEvents(new Command({ resume: 'ok' }), cfg, {
-          raiseError: true,
-        })
-      );
-      const done = await counts(dbName);
-
-      return { atPause, done };
-    };
-
-    it('exit checkpoints only at the interrupt boundary and final exit; async checkpoints every superstep', async () => {
-      const exitRun = await runInterruptGraph('hitl_exit', 'exit');
-      const asyncRun = await runInterruptGraph('hitl_async', 'async');
-
-      // exit: one checkpoint at the pause (the interrupt), two once resumed
-      // (interrupt boundary + final exit).
-      expect(exitRun.atPause.checkpoints).toBe(1);
-      expect(exitRun.done.checkpoints).toBe(2);
-
-      // async: a checkpoint for every superstep, strictly more at each stage.
-      expect(asyncRun.atPause.checkpoints).toBeGreaterThan(
-        exitRun.atPause.checkpoints
-      );
-      expect(asyncRun.done.checkpoints).toBeGreaterThan(
-        exitRun.done.checkpoints
-      );
-      expect(asyncRun.done.writes).toBeGreaterThan(exitRun.done.writes);
-    });
-  });
-
-  describe('multiple interrupts (sequential ask-user-questions)', () => {
-    const State = Annotation.Root({
-      qa: Annotation<string[]>({
-        reducer: (a, b) => a.concat(b),
-        default: () => [],
-      }),
-    });
-
-    const drain = async (stream: AsyncIterable<unknown>): Promise<void> => {
-      for await (const _event of stream) {
-        // Consume the event stream.
-      }
-    };
-
-    it('checkpoints each interrupt boundary, chains them, and discards none across resumes', async () => {
-      const dbName = 'multi_exit';
-      const saver = new MongoDBSaver({ client, dbName });
-      const graph = new StateGraph(State)
-        .addNode('ask1', () => ({ qa: [`Q1=${interrupt({ q: 'Q1' })}`] }))
-        .addNode('ask2', () => ({ qa: [`Q2=${interrupt({ q: 'Q2' })}`] }))
-        .addNode('done', () => ({ qa: ['done'] }))
-        .addEdge(START, 'ask1')
-        .addEdge('ask1', 'ask2')
-        .addEdge('ask2', 'done')
-        .addEdge('done', END)
-        .compile({ checkpointer: saver });
-
-      const cfg = {
-        configurable: { thread_id: dbName },
-        durability: 'exit' as const,
-        version: 'v2' as const,
-      };
-
-      // First question -> pauses at ask1, one checkpoint at that boundary.
-      await drain(graph.streamEvents({ qa: [] }, cfg, { raiseError: true }));
-      let state = await graph.getState(cfg);
-      expect(state.next).toEqual(['ask1']);
-      expect((await counts(dbName)).checkpoints).toBe(1);
-
-      // Answer 1 -> the run continues and the LLM asks a second question.
-      // The chain grows to 2: the first interrupt checkpoint is retained as
-      // the parent, not discarded or overwritten.
-      await drain(
-        graph.streamEvents(new Command({ resume: 'A1' }), cfg, {
-          raiseError: true,
-        })
-      );
-      state = await graph.getState(cfg);
-      expect(state.next).toEqual(['ask2']);
-      expect(state.values.qa).toEqual(['Q1=A1']);
-      expect((await counts(dbName)).checkpoints).toBe(2);
-
-      // Answer 2 -> run completes; both answers applied, three checkpoints
-      // total (two interrupt boundaries + final exit).
-      await drain(
-        graph.streamEvents(new Command({ resume: 'A2' }), cfg, {
-          raiseError: true,
-        })
-      );
-      state = await graph.getState(cfg);
-      expect(state.next).toEqual([]);
-      expect(state.values.qa).toEqual(['Q1=A1', 'Q2=A2', 'done']);
-      expect((await counts(dbName)).checkpoints).toBe(3);
-    });
-  });
-});

package/src/specs/graph-subagent.live.test.ts

@@ -1,242 +0,0 @@
-import { config as dotenvConfig } from 'dotenv';
-
-dotenvConfig(
-  process.env.LIVE_ENV_PATH == null
-    ? undefined
-    : { path: process.env.LIVE_ENV_PATH }
-);
-dotenvConfig();
-
-import { describe, expect, it, jest } from '@jest/globals';
-import type { RunnableConfig } from '@langchain/core/runnables';
-import type * as t from '@/types';
-import { Constants, GraphEvents, Providers } from '@/common';
-import { StandardGraph } from '@/graphs/Graph';
-import { Run } from '@/run';
-
-jest.setTimeout(180_000);
-
-const liveEnabled = process.env.RUN_GRAPH_SUBAGENT_LIVE_TESTS === '1';
-const requestedProvider = process.env.GRAPH_SUBAGENT_LIVE_PROVIDER;
-const describeIfLive = liveEnabled ? describe : describe.skip;
-
-type LiveProviderCase = {
-  label: string;
-  provider: Providers;
-  model: string;
-  apiKey?: string;
-};
-
-const LIVE_PROVIDER_CASES: readonly LiveProviderCase[] = [
-  {
-    label: 'Anthropic Haiku',
-    provider: Providers.ANTHROPIC,
-    model:
-      process.env.ANTHROPIC_GRAPH_SUBAGENT_LIVE_MODEL ?? 'claude-haiku-4-5',
-    apiKey: process.env.ANTHROPIC_API_KEY,
-  },
-  {
-    label: 'OpenAI GPT-4.1 mini',
-    provider: Providers.OPENAI,
-    model: process.env.OPENAI_GRAPH_SUBAGENT_LIVE_MODEL ?? 'gpt-4.1-mini',
-    apiKey: process.env.OPENAI_API_KEY,
-  },
-];
-
-const explicitlyRequestedCase =
-  requestedProvider == null || requestedProvider === ''
-    ? undefined
-    : LIVE_PROVIDER_CASES.find(
-      ({ provider }) =>
-        provider.toLowerCase() === requestedProvider.toLowerCase()
-    );
-
-if (
-  liveEnabled &&
-  requestedProvider != null &&
-  requestedProvider !== '' &&
-  explicitlyRequestedCase == null
-) {
-  throw new Error(
-    `Unknown GRAPH_SUBAGENT_LIVE_PROVIDER "${requestedProvider}".`
-  );
-}
-if (
-  liveEnabled &&
-  explicitlyRequestedCase != null &&
-  (explicitlyRequestedCase.apiKey == null ||
-    explicitlyRequestedCase.apiKey === '')
-) {
-  throw new Error(
-    `Missing credentials for GRAPH_SUBAGENT_LIVE_PROVIDER "${requestedProvider}".`
-  );
-}
-if (
-  liveEnabled &&
-  explicitlyRequestedCase == null &&
-  !LIVE_PROVIDER_CASES.some(({ apiKey }) => apiKey != null && apiKey !== '')
-) {
-  throw new Error(
-    'No graph-subagent live-provider credentials are configured.'
-  );
-}
-
-function createLiveAgent(
-  testCase: LiveProviderCase,
-  agentId: string,
-  marker: string
-): t.AgentInputs {
-  return {
-    agentId,
-    provider: testCase.provider,
-    clientOptions: {
-      modelName: testCase.model,
-      apiKey: testCase.apiKey,
-      temperature: 0,
-      maxTokens: 64,
-      streaming: true,
-      streamUsage: true,
-    },
-    instructions: `You are the ${agentId} validation stage. When asked to proceed, reply with exactly ${marker} and no other text.`,
-    maxContextTokens: 8_000,
-  };
-}
-
-function getGraphSubagentTool(run: Run<t.IState>): t.GenericTool {
-  const tools = (run.Graph as StandardGraph).agentContexts.get('parent')
-    ?.graphTools as t.GenericTool[] | undefined;
-  const subagentTool = tools?.find(
-    (tool) => 'name' in tool && tool.name === Constants.SUBAGENT
-  );
-  if (subagentTool == null) {
-    throw new Error('Expected graph subagent tool');
-  }
-  return subagentTool;
-}
-
-describeIfLive('Graph subagent live providers', () => {
-  for (const testCase of LIVE_PROVIDER_CASES) {
-    const providerSelected =
-      requestedProvider == null ||
-      requestedProvider === '' ||
-      requestedProvider.toLowerCase() === testCase.provider.toLowerCase();
-    const itIfAvailable =
-      providerSelected && testCase.apiKey != null && testCase.apiKey !== ''
-        ? it
-        : it.skip;
-
-    itIfAvailable(
-      `${testCase.label} runs a bounded team and returns only its result member`,
-      async () => {
-        const usageEvents: t.SubagentUsageEvent[] = [];
-        const updateEvents: t.SubagentUpdateEvent[] = [];
-        const entry = createLiveAgent(testCase, 'entry', 'ENTRY_MARKER');
-        const worker = createLiveAgent(testCase, 'worker', 'WORKER_MARKER');
-        const resultAgent = createLiveAgent(testCase, 'result', 'FINAL_MARKER');
-        const parent: t.AgentInputs = {
-          ...createLiveAgent(testCase, 'parent', 'PARENT_MARKER'),
-          maxSubagentDepth: 1,
-          subagentConfigs: [
-            {
-              kind: 'graph',
-              type: 'live-team',
-              name: 'Live Team',
-              description: 'Runs a three-member live-provider chain.',
-              maxTurns: 2,
-              agents: [entry, worker, resultAgent],
-              edges: [
-                {
-                  from: 'entry',
-                  to: 'worker',
-                  edgeType: 'direct',
-                  prompt: 'Proceed with the worker validation stage.',
-                },
-                {
-                  from: 'worker',
-                  to: 'result',
-                  edgeType: 'direct',
-                  prompt: 'Proceed with the result validation stage.',
-                },
-              ],
-              entryAgentId: 'entry',
-              resultAgentId: 'result',
-            },
-          ],
-        };
-        const rootRunId = `graph-subagent-live-${testCase.provider}-${Date.now()}`;
-        const run = await Run.create<t.IState>({
-          runId: rootRunId,
-          graphConfig: { type: 'standard', agents: [parent] },
-          returnContent: true,
-          skipCleanup: true,
-          subagentUsageSink: (event) => {
-            usageEvents.push(event);
-          },
-          customHandlers: {
-            [GraphEvents.ON_SUBAGENT_UPDATE]: {
-              handle: (_event, data): void => {
-                updateEvents.push(data as t.SubagentUpdateEvent);
-              },
-            },
-          },
-        });
-        const invokeConfig: RunnableConfig = {
-          configurable: {
-            thread_id: `graph-subagent-live-${testCase.provider}`,
-          },
-        };
-
-        const output = await getGraphSubagentTool(run).invoke(
-          {
-            description: 'Begin the entry validation stage.',
-            subagent_type: 'live-team',
-          },
-          invokeConfig
-        );
-        const outputText = String(output);
-
-        expect(outputText).toContain('FINAL_MARKER');
-        expect(outputText).not.toContain('ENTRY_MARKER');
-        expect(outputText).not.toContain('WORKER_MARKER');
-        expect(usageEvents.map((event) => event.memberAgentId).sort()).toEqual([
-          'entry',
-          'result',
-          'worker',
-        ]);
-        for (const event of usageEvents) {
-          expect(event.runId).toBe(rootRunId);
-          expect(event.parentRunId).toBe(rootRunId);
-          expect(event.depth).toBe(1);
-          expect(event.ancestry?.map((entry) => entry.subagentType)).toEqual([
-            'live-team',
-          ]);
-          expect(event.subagentKind).toBe('graph');
-          expect(event.provider).toBe(testCase.provider);
-          expect(event.model).toBeTruthy();
-          expect(event.usage.total_tokens).toBeGreaterThan(0);
-        }
-        expect(
-          updateEvents.filter((event) => event.phase === 'start')
-        ).toHaveLength(1);
-        expect(
-          updateEvents.filter((event) => event.phase === 'stop')
-        ).toHaveLength(1);
-        for (const event of updateEvents) {
-          expect(event.runId).toBe(rootRunId);
-          expect(event.parentRunId).toBe(rootRunId);
-          expect(event.depth).toBe(1);
-          expect(event.ancestry?.map((entry) => entry.subagentType)).toEqual([
-            'live-team',
-          ]);
-        }
-        expect(
-          new Set(
-            updateEvents
-              .map((event) => event.memberAgentId)
-              .filter((agentId): agentId is string => agentId != null)
-          )
-        ).toEqual(new Set(['entry', 'worker', 'result']));
-      }
-    );
-  }
-});