@librechat/agents 3.4.0 → 3.4.2

package/src/graphs/__tests__/composition.smoke.test.ts

@@ -1,3 +1,4 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { HumanMessage, getBufferString } from '@langchain/core/messages';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
@@ -65,6 +66,40 @@ class CapturingChatModel extends FakeChatModel {
   }
 }
 
+class GatedMessageCountChatModel extends FakeChatModel {
+  private responseIndex = 0;
+
+  constructor(
+    private readonly gatedAiMessageCount: number,
+    private readonly onGatedStart: () => void,
+    private readonly releaseGate: Promise<void>
+  ) {
+    super({ responses: ['unused'] });
+  }
+
+  override async *_streamResponseChunks(
+    messages: BaseMessage[],
+    _options: this['ParsedCallOptions'],
+    runManager?: CallbackManagerForLLMRun
+  ): AsyncGenerator<ChatGenerationChunk> {
+    const aiMessageCount = messages.filter(
+      (message) => message.getType() === 'ai'
+    ).length;
+    if (aiMessageCount === this.gatedAiMessageCount) {
+      this.onGatedStart();
+      await this.releaseGate;
+    }
+    const output = `response-${this.responseIndex++}`;
+    yield this._createResponseChunk(output);
+    void runManager?.handleLLMNewToken(output);
+  }
+}
+
+type AgentInvocation = {
+  agentId: string;
+  messages: BaseMessage[];
+};
+
 const expectCompiledWorkflow = (
   workflow: t.CompiledWorkflow | t.CompiledMultiAgentWorkflow
 ): void => {
@@ -342,6 +377,123 @@ describe('LangGraph composition smoke tests', () => {
     expect(graph.getParallelGroupId('final')).toBeUndefined();
   });
 
+  it.each([
+    ['without a prompt wrapper', undefined],
+    ['with a prompt wrapper', 'Summarize these results:\n{results}'],
+  ])('waits for every explicit fan-in source %s', async (_label, prompt) => {
+    const invocations: AgentInvocation[] = [];
+    let releaseLeft2!: () => void;
+    let markLeft2Started!: () => void;
+    const left2Release = new Promise<void>((resolve) => {
+      releaseLeft2 = resolve;
+    });
+    const left2Started = new Promise<void>((resolve) => {
+      markLeft2Started = resolve;
+    });
+    const invocationHandler = BaseCallbackHandler.fromMethods({
+      handleChatModelStart: (
+        _llm,
+        messages,
+        _runId,
+        _parentRunId,
+        _extraParams,
+        _tags,
+        metadata
+      ) => {
+        const agentId = metadata?.agentId;
+        if (typeof agentId === 'string') {
+          invocations.push({ agentId, messages: [...messages[0]] });
+        }
+      },
+    });
+    const graph = new MultiAgentGraph({
+      runId: 'fan-in-waiting-edge-smoke',
+      agents: [
+        makeAgent('root'),
+        makeAgent('left'),
+        makeAgent('left2'),
+        makeAgent('right'),
+        makeAgent('final'),
+      ],
+      edges: [
+        { from: 'root', to: ['left', 'right'], edgeType: 'direct' },
+        { from: 'left', to: 'left2', edgeType: 'direct' },
+        {
+          from: ['left2', 'right'],
+          to: 'final',
+          edgeType: 'direct',
+          prompt,
+        },
+      ],
+    });
+    graph.overrideModel = new GatedMessageCountChatModel(
+      3,
+      markLeft2Started,
+      left2Release
+    );
+
+    const invocation = graph.createWorkflow().invoke(
+      { messages: [new HumanMessage('start')] },
+      {
+        ...makeConfig('fan-in-waiting-edge-smoke'),
+        callbacks: [invocationHandler],
+      }
+    );
+
+    let gateTimeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        left2Started,
+        new Promise<void>((_resolve, reject) => {
+          gateTimeout = setTimeout(
+            () =>
+              reject(
+                new Error(
+                  `Timed out waiting for the gated branch; started: ${invocations
+                    .map(({ agentId }) => agentId)
+                    .join(', ')}`
+                )
+              ),
+            5_000
+          );
+        }),
+      ]);
+    } finally {
+      clearTimeout(gateTimeout);
+    }
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    expect(
+      invocations.filter(({ agentId }) => agentId === 'final')
+    ).toHaveLength(0);
+    releaseLeft2();
+    await invocation;
+
+    const invokedAgentIds = invocations.map(({ agentId }) => agentId);
+    expect(
+      invokedAgentIds.filter((agentId) => agentId === 'final')
+    ).toHaveLength(1);
+    expect(invokedAgentIds.indexOf('final')).toBeGreaterThan(
+      invokedAgentIds.indexOf('left2')
+    );
+    expect(invokedAgentIds.indexOf('final')).toBeGreaterThan(
+      invokedAgentIds.indexOf('right')
+    );
+    const finalInvocation = invocations.find(
+      ({ agentId }) => agentId === 'final'
+    );
+    if (prompt == null) {
+      expect(
+        finalInvocation?.messages.filter(
+          (message) => message.getType() === 'ai'
+        )
+      ).toHaveLength(4);
+    } else {
+      expect(getBufferString(finalInvocation?.messages ?? [])).toContain(
+        'response-3'
+      );
+    }
+  });
+
   it('compiles mixed handoff and direct routing from the same agent', () => {
     const graph = new MultiAgentGraph({
       runId: 'mixed-routing-smoke',

package/src/graphs/__tests__/createGraph.test.ts

@@ -0,0 +1,206 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { GraphFactory, GraphFactoryRequest } from '@/graphs/graphFactory';
+import type * as t from '@/types';
+import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import { createFakeStreamingLLM } from '@/llm/fake';
+import { createGraph } from '@/graphs/createGraph';
+import { Constants, Providers } from '@/common';
+import { StandardGraph } from '@/graphs/Graph';
+
+const invokeConfig: RunnableConfig = {
+  configurable: { thread_id: 'graph-factory-test' },
+};
+
+const makeAgent = (agentId: string): t.AgentInputs => ({
+  agentId,
+  provider: Providers.OPENAI,
+  instructions: `You are ${agentId}.`,
+});
+
+const getSubagentTool = (
+  graph: StandardGraph,
+  agentId: string
+): t.GenericTool => {
+  graph.createWorkflow();
+  const tools = graph.agentContexts.get(agentId)?.graphTools as
+    | t.GenericTool[]
+    | undefined;
+  const tool = tools?.find(
+    (candidate) => 'name' in candidate && candidate.name === Constants.SUBAGENT
+  );
+  if (tool == null) {
+    throw new Error(`Expected subagent tool for ${agentId}`);
+  }
+  return tool;
+};
+
+describe('graph factory', () => {
+  it('constructs standard and multi-agent graph adapters', () => {
+    const standard = createGraph({
+      kind: 'standard',
+      input: { runId: 'standard-factory', agents: [makeAgent('standard')] },
+    });
+    const multiAgent = createGraph({
+      kind: 'multi-agent',
+      input: {
+        runId: 'multi-agent-factory',
+        agents: [makeAgent('multi')],
+        edges: [],
+      },
+    });
+
+    expect(standard).toBeInstanceOf(StandardGraph);
+    expect(standard).not.toBeInstanceOf(MultiAgentGraph);
+    expect(multiAgent).toBeInstanceOf(MultiAgentGraph);
+  });
+
+  it('accepts a union-typed graph factory request', () => {
+    const construct = (request: GraphFactoryRequest): StandardGraph =>
+      createGraph(request);
+    const graph = construct({
+      kind: 'standard',
+      input: { runId: 'union-factory', agents: [makeAgent('union')] },
+    });
+
+    expect(graph).toBeInstanceOf(StandardGraph);
+  });
+
+  it('rejects invalid per-member recursion limits', () => {
+    expect(() =>
+      createGraph({
+        kind: 'multi-agent',
+        input: {
+          runId: 'invalid-member-limit',
+          agents: [makeAgent('member')],
+          edges: [],
+          memberRecursionLimit: 0,
+        },
+      })
+    ).toThrow(/memberRecursionLimit must be a positive safe integer/);
+  });
+
+  it('keeps direct StandardGraph construction compatible with agent children', async () => {
+    const parent = {
+      ...makeAgent('parent'),
+      subagentConfigs: [
+        {
+          type: 'worker',
+          name: 'Worker',
+          description: 'Completes one isolated task.',
+          agentInputs: makeAgent('worker'),
+        },
+      ],
+    } satisfies t.AgentInputs;
+    const graph = new StandardGraph({
+      runId: 'direct-standard-factory',
+      agents: [parent],
+    });
+    graph.setSubagentModelOverride(
+      createFakeStreamingLLM({ responses: ['worker complete'] })
+    );
+
+    const result = await getSubagentTool(graph, 'parent').invoke(
+      { description: 'Complete the task.', subagent_type: 'worker' },
+      invokeConfig
+    );
+
+    expect(result).toBe('worker complete');
+  });
+
+  it('fails early when direct construction cannot instantiate a graph child', () => {
+    const parent = {
+      ...makeAgent('parent'),
+      subagentConfigs: [
+        {
+          kind: 'graph' as const,
+          type: 'team',
+          name: 'Team',
+          description: 'Runs one member.',
+          agents: [makeAgent('member')],
+          edges: [],
+          entryAgentId: 'member',
+          resultAgentId: 'member',
+        },
+      ],
+    } satisfies t.AgentInputs;
+    const graph = new StandardGraph({
+      runId: 'direct-graph-child-factory',
+      agents: [parent],
+    });
+
+    expect(() => graph.createWorkflow()).toThrow(
+      /constructing the parent with createGraph\(\)/
+    );
+  });
+
+  it('propagates an injected factory through child and grandchild graphs', async () => {
+    const requests: GraphFactoryRequest[] = [];
+    const graphFactory: GraphFactory = (request) => {
+      requests.push(request);
+      if (request.kind === 'multi-agent') {
+        return new MultiAgentGraph(request.input, { graphFactory });
+      }
+      return new StandardGraph(request.input, { graphFactory });
+    };
+    const nestedToolCall: ToolCall = {
+      id: 'call_nested_specialist',
+      name: Constants.SUBAGENT,
+      args: {
+        description: 'Complete the specialist step.',
+        subagent_type: 'specialist',
+      },
+      type: 'tool_call',
+    };
+    const router = {
+      ...makeAgent('router'),
+      subagentConfigs: [
+        {
+          type: 'specialist',
+          name: 'Specialist',
+          description: 'Completes the nested specialist step.',
+          agentInputs: makeAgent('specialist'),
+        },
+      ],
+    } satisfies t.AgentInputs;
+    const root = {
+      ...makeAgent('root'),
+      maxSubagentDepth: 2,
+      subagentConfigs: [
+        {
+          type: 'router',
+          name: 'Router',
+          description: 'Delegates one nested specialist step.',
+          allowNested: true,
+          agentInputs: router,
+        },
+      ],
+    } satisfies t.AgentInputs;
+    const graph = new StandardGraph(
+      { runId: 'recursive-graph-factory', agents: [root] },
+      { graphFactory }
+    );
+    graph.setSubagentModelOverride(
+      createFakeStreamingLLM({
+        responses: ['delegating', 'specialist complete', 'router complete'],
+        toolCalls: [nestedToolCall],
+      })
+    );
+
+    const result = await getSubagentTool(graph, 'root').invoke(
+      { description: 'Route the task.', subagent_type: 'router' },
+      invokeConfig
+    );
+
+    expect(result).toBe('router complete');
+    expect(
+      requests.map(({ kind, input }) => ({
+        kind,
+        agentIds: input.agents.map(({ agentId }) => agentId),
+      }))
+    ).toEqual([
+      { kind: 'standard', agentIds: ['router'] },
+      { kind: 'standard', agentIds: ['specialist'] },
+    ]);
+  });
+});

package/src/graphs/applyGraphRuntimeConfig.ts

@@ -0,0 +1,25 @@
+import type { StandardGraph } from './Graph';
+
+export type GraphRuntimeConfig = Pick<
+  StandardGraph,
+  | 'hookRegistry'
+  | 'humanInTheLoop'
+  | 'toolOutputReferences'
+  | 'eagerEventToolExecution'
+  | 'codeSessionToolNames'
+  | 'interruptingToolNames'
+  | 'toolExecution'
+>;
+
+export function applyGraphRuntimeConfig(
+  graph: StandardGraph,
+  config: GraphRuntimeConfig
+): void {
+  graph.hookRegistry = config.hookRegistry;
+  graph.humanInTheLoop = config.humanInTheLoop;
+  graph.toolOutputReferences = config.toolOutputReferences;
+  graph.eagerEventToolExecution = config.eagerEventToolExecution;
+  graph.codeSessionToolNames = config.codeSessionToolNames;
+  graph.interruptingToolNames = config.interruptingToolNames;
+  graph.toolExecution = config.toolExecution;
+}

package/src/graphs/createGraph.ts

@@ -0,0 +1,32 @@
+import type {
+  GraphFactory,
+  GraphFactoryDependencies,
+  GraphFactoryRequest,
+} from '@/graphs/graphFactory';
+import type { MultiAgentGraphInput, StandardGraphInput } from '@/types';
+import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import { StandardGraph } from '@/graphs/Graph';
+
+const createGraphByKind: GraphFactory = (request) => {
+  if (request.kind === 'multi-agent') {
+    return new MultiAgentGraph(request.input, dependencies);
+  }
+  return new StandardGraph(request.input, dependencies);
+};
+
+const dependencies: GraphFactoryDependencies = {
+  graphFactory: createGraphByKind,
+};
+
+export function createGraph(request: {
+  kind: 'standard';
+  input: StandardGraphInput;
+}): StandardGraph;
+export function createGraph(request: {
+  kind: 'multi-agent';
+  input: MultiAgentGraphInput;
+}): MultiAgentGraph;
+export function createGraph(request: GraphFactoryRequest): StandardGraph;
+export function createGraph(request: GraphFactoryRequest): StandardGraph {
+  return createGraphByKind(request);
+}

package/src/graphs/graphFactory.ts

@@ -0,0 +1,12 @@
+import type { StandardGraph } from './Graph';
+import type * as t from '@/types';
+
+export type GraphFactoryRequest =
+  | { kind: 'standard'; input: t.StandardGraphInput }
+  | { kind: 'multi-agent'; input: t.MultiAgentGraphInput };
+
+export type GraphFactory = (request: GraphFactoryRequest) => StandardGraph;
+
+export type GraphFactoryDependencies = {
+  graphFactory: GraphFactory;
+};

package/src/graphs/index.ts

@@ -1,2 +1,4 @@
 export * from './Graph';
 export * from './MultiAgentGraph';
+export * from './createGraph';
+export type * from './graphFactory';

package/src/hooks/HookRegistry.ts

@@ -1,5 +1,31 @@
 // src/hooks/HookRegistry.ts
-import type { HookEvent, HookMatcher } from './types';
+import type {
+  HookEvent,
+  HookMatcher,
+  ToolApprovalReplayKey,
+  ToolApprovalReplaySnapshot,
+  AggregatedHookResult,
+} from './types';
+
+function serializeApprovalKey(key: ToolApprovalReplayKey): string {
+  return JSON.stringify([key.executionScope, key.agentId, key.toolUseId]);
+}
+
+function deserializeApprovalKey(value: string): ToolApprovalReplayKey | null {
+  const parsed: unknown = JSON.parse(value);
+  if (
+    !Array.isArray(parsed) ||
+    parsed.length !== 3 ||
+    parsed.some((part) => typeof part !== 'string')
+  ) {
+    return null;
+  }
+  return {
+    executionScope: parsed[0],
+    agentId: parsed[1],
+    toolUseId: parsed[2],
+  };
+}
 
 /**
  * Internal matcher storage type.
@@ -71,6 +97,11 @@ export class HookRegistry {
    * O(1) insertion in hot paths, no spread-on-write.
    */
   private readonly haltSignals: Map<string, HookHaltSignal> = new Map();
+  /** One-shot hook contributions retained until approval is consumed. */
+  private readonly pendingToolApprovals = new Map<
+    string,
+    Map<string, AggregatedHookResult>
+  >();
 
   /**
    * Register a matcher for the lifetime of this registry (= one Run).
@@ -160,6 +191,125 @@ export class HookRegistry {
    */
   clearSession(sessionId: string): void {
     this.sessions.delete(sessionId);
+    this.pendingToolApprovals.delete(sessionId);
+  }
+
+  /** Copies session-scoped policy into a rebuilt or branched Run. */
+  copySession(sourceSessionId: string, targetSessionId: string): void {
+    if (sourceSessionId === targetSessionId) {
+      return;
+    }
+    const source = this.sessions.get(sourceSessionId);
+    if (source != null) {
+      const target = this.ensureSessionBucket(targetSessionId);
+      for (const event of Object.keys(source) as HookEvent[]) {
+        const targetList = ensureList(target, event);
+        for (const matcher of readList(source, event)) {
+          if (!targetList.includes(matcher)) {
+            targetList.push(matcher);
+          }
+        }
+      }
+    }
+    const pending = this.pendingToolApprovals.get(sourceSessionId);
+    if (pending == null) {
+      return;
+    }
+    let targetPending = this.pendingToolApprovals.get(targetSessionId);
+    if (targetPending == null) {
+      targetPending = new Map();
+      this.pendingToolApprovals.set(targetSessionId, targetPending);
+    }
+    for (const [toolUseId, result] of pending) {
+      if (!targetPending.has(toolUseId)) {
+        targetPending.set(toolUseId, result);
+      }
+    }
+  }
+
+  getPendingToolApproval(
+    sessionId: string,
+    key: ToolApprovalReplayKey
+  ): AggregatedHookResult | undefined {
+    return this.pendingToolApprovals
+      .get(sessionId)
+      ?.get(serializeApprovalKey(key));
+  }
+
+  setPendingToolApproval(
+    sessionId: string,
+    key: ToolApprovalReplayKey,
+    result: AggregatedHookResult
+  ): void {
+    let pending = this.pendingToolApprovals.get(sessionId);
+    if (pending == null) {
+      pending = new Map();
+      this.pendingToolApprovals.set(sessionId, pending);
+    }
+    pending.set(serializeApprovalKey(key), result);
+  }
+
+  clearPendingToolApproval(
+    sessionId: string,
+    key: ToolApprovalReplayKey
+  ): void {
+    const pending = this.pendingToolApprovals.get(sessionId);
+    if (pending == null) {
+      return;
+    }
+    pending.delete(serializeApprovalKey(key));
+    if (pending.size === 0) {
+      this.pendingToolApprovals.delete(sessionId);
+    }
+  }
+
+  snapshotPendingToolApprovals(
+    sessionId: string,
+    executionScope: string
+  ): ToolApprovalReplaySnapshot[] {
+    const pending = this.pendingToolApprovals.get(sessionId);
+    if (pending == null) {
+      return [];
+    }
+    const snapshots: ToolApprovalReplaySnapshot[] = [];
+    for (const [serializedKey, result] of pending) {
+      const key = deserializeApprovalKey(serializedKey);
+      if (key == null || key.executionScope !== executionScope) {
+        continue;
+      }
+      snapshots.push({ key, result });
+    }
+    return snapshots;
+  }
+
+  restorePendingToolApprovals(
+    sessionId: string,
+    targetExecutionScope: string,
+    snapshots: ReadonlyArray<ToolApprovalReplaySnapshot>
+  ): void {
+    const restored = new Map<string, AggregatedHookResult>();
+    for (const [serializedKey, result] of this.pendingToolApprovals.get(
+      sessionId
+    ) ?? []) {
+      const key = deserializeApprovalKey(serializedKey);
+      if (key?.executionScope !== targetExecutionScope) {
+        restored.set(serializedKey, result);
+      }
+    }
+    for (const snapshot of snapshots) {
+      restored.set(
+        serializeApprovalKey({
+          ...snapshot.key,
+          executionScope: targetExecutionScope,
+        }),
+        snapshot.result
+      );
+    }
+    if (restored.size === 0) {
+      this.pendingToolApprovals.delete(sessionId);
+      return;
+    }
+    this.pendingToolApprovals.set(sessionId, restored);
   }
 
   /**