@librechat/agents 3.9.2 → 3.9.4

package/src/graphs/MultiAgentGraph.ts

@@ -33,6 +33,7 @@ import {
   HARD_MAX_TOOL_RESULT_CHARS,
 } from '@/utils/truncation';
 import { withInstructionlessHandoffCue } from '@/messages/handoffCue';
+import { HandoffRouting, handoffStateAnnotation } from './handoff';
 import { serializeToolContentBounded } from '@/utils/toolContent';
 import { Constants, MULTI_AGENT_GRAPH_RUN_NAME } from '@/common';
 import { StandardGraph } from './Graph';
@@ -337,6 +338,7 @@ export class MultiAgentGraph extends StandardGraph {
   private handoffSourceIds = new Set<string>();
   private readonly resultAgentId?: string;
   private readonly memberRecursionLimit?: number;
+  private reachableAgentIds?: Set<string>;
   private handoffPromptLabels: Map<string, Set<string>> = new Map();
   /**
    * Map of agentId to parallel group info.
@@ -379,9 +381,115 @@ export class MultiAgentGraph extends StandardGraph {
     this.categorizeEdges();
     this.validateCommandRoutedDirectEdges();
     this.analyzeGraph();
+    if (input.entryAgentId != null) {
+      if (!this.agentContexts.has(input.entryAgentId)) {
+        throw new Error(
+          `MultiAgentGraph: unknown entryAgentId "${input.entryAgentId}"`
+        );
+      }
+      this.startingNodes = new Set([input.entryAgentId]);
+      this.defaultAgentId = input.entryAgentId;
+      this.computeParallelCapability();
+      this.reachableAgentIds = this.resolveEntryReachability(
+        input.entryAgentId
+      );
+    }
+    if (
+      input.maxHandoffs != null &&
+      (!Number.isSafeInteger(input.maxHandoffs) || input.maxHandoffs < 0)
+    ) {
+      throw new Error(
+        'MultiAgentGraph: maxHandoffs must be a non-negative safe integer'
+      );
+    }
+    const directDestinations = new Map<string, Set<string>>();
+    for (const edge of this.directEdges) {
+      if (edge.handoffScope != null)
+        throw new Error('handoffScope is only valid on handoff edges');
+      for (const source of Array.isArray(edge.from) ? edge.from : [edge.from]) {
+        const targets = directDestinations.get(source) ?? new Set<string>();
+        for (const target of Array.isArray(edge.to) ? edge.to : [edge.to])
+          targets.add(target);
+        directDestinations.set(source, targets);
+      }
+    }
+    this.handoffRouting = new HandoffRouting(
+      this.startingNodes.values().next().value ?? this.defaultAgentId,
+      input.maxHandoffs,
+      this.startingNodes.size > 1 ||
+        [...directDestinations.values()].some((targets) => targets.size > 1)
+    );
+    this.validateHandoffScopes();
     this.createHandoffTools();
   }
 
+  private validateHandoffScopes(): void {
+    const scopes = new Map<string, string>();
+    for (const edge of this.handoffEdges) {
+      const scope = edge.handoffScope ?? 'turn';
+      if (!['turn', 'conversation'].includes(scope))
+        throw new Error('Invalid handoffScope');
+      for (const source of Array.isArray(edge.from) ? edge.from : [edge.from]) {
+        const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+        const targets =
+          edge.condition != null ? ['conditional_transfer'] : destinations;
+        for (const target of targets) {
+          const key = JSON.stringify([source, target]);
+          const previous = scopes.get(key);
+          if (previous != null && previous !== scope)
+            throw new Error(
+              'Conflicting handoffScope for the same transfer tool'
+            );
+          scopes.set(key, scope);
+        }
+      }
+    }
+  }
+
+  private resolveEntryReachability(entryAgentId: string): Set<string> {
+    const reachable = new Set([entryAgentId]);
+    const direct = new Set(this.directEdges);
+    const outgoing = new Map<string, t.GraphEdge[]>();
+    const remaining = new Map<t.GraphEdge, number>();
+    for (const edge of this.edges) {
+      const sources = new Set(
+        Array.isArray(edge.from) ? edge.from : [edge.from]
+      );
+      remaining.set(edge, direct.has(edge) ? sources.size : 1);
+      for (const source of sources) {
+        const edges = outgoing.get(source) ?? [];
+        edges.push(edge);
+        outgoing.set(source, edges);
+      }
+    }
+    const queue = [entryAgentId];
+    for (let i = 0; i < queue.length; i++) {
+      for (const edge of outgoing.get(queue[i]) ?? []) {
+        const pending = remaining.get(edge) ?? 0;
+        if (pending === 0) continue;
+        remaining.set(edge, pending - 1);
+        if (pending > 1) continue;
+        for (const target of Array.isArray(edge.to) ? edge.to : [edge.to]) {
+          if (reachable.has(target)) continue;
+          reachable.add(target);
+          queue.push(target);
+        }
+      }
+    }
+    for (const edge of this.directEdges) {
+      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+      if (
+        sources.some((source) => reachable.has(source)) &&
+        !sources.every((source) => reachable.has(source))
+      ) {
+        throw new Error(
+          'entryAgentId cannot satisfy a grouped direct edge prerequisite'
+        );
+      }
+    }
+    return reachable;
+  }
+
   /**
    * Fails fast when an edge references an agent that is not in
    * `agentContexts`. Without this check, the underlying LangGraph
@@ -762,6 +870,11 @@ export class MultiAgentGraph extends StandardGraph {
               destination = Array.isArray(result) ? result[0] : destinations[0];
             }
 
+            if (!destinations.includes(destination)) {
+              throw new Error(
+                `Conditional handoff selected undeclared destination "${destination}"`
+              );
+            }
             const handoffInstructions = getHandoffInstructions(
               input,
               promptKey,
@@ -789,7 +902,15 @@ export class MultiAgentGraph extends StandardGraph {
 
             return new Command({
               goto: destination,
-              update: { messages: state.messages.concat(toolMessage) },
+              update: {
+                messages: state.messages.concat(toolMessage),
+                handoffRequest: {
+                  sourceAgentId,
+                  targetAgentId: destination,
+                  toolCallId,
+                  scope: edge.handoffScope ?? 'turn',
+                },
+              },
               graph: Command.PARENT,
             });
           },
@@ -926,7 +1047,15 @@ export class MultiAgentGraph extends StandardGraph {
 
               return new Command({
                 goto: destination,
-                update: { messages: filteredMessages },
+                update: {
+                  messages: filteredMessages,
+                  handoffRequest: {
+                    sourceAgentId,
+                    targetAgentId: destination,
+                    toolCallId,
+                    scope: edge.handoffScope ?? 'turn',
+                  },
+                },
                 graph: Command.PARENT,
               });
             },
@@ -1274,6 +1403,7 @@ export class MultiAgentGraph extends StandardGraph {
         default: () => undefined,
       }),
       runStepState: this.createRunStepStateAnnotation(),
+      handoffState: handoffStateAnnotation(),
     });
 
     const builder = new StateGraph(StateAnnotation);
@@ -1298,9 +1428,16 @@ export class MultiAgentGraph extends StandardGraph {
     const agentIds =
       summarizeOnlyAgentId != null
         ? [summarizeOnlyAgentId]
-        : [...this.agentContexts.keys()];
+        : [...(this.reachableAgentIds ?? this.agentContexts.keys())];
     const handoffEdges = summarizeOnlyAgentId != null ? [] : this.handoffEdges;
-    const directEdges = summarizeOnlyAgentId != null ? [] : this.directEdges;
+    const directEdges =
+      summarizeOnlyAgentId != null
+        ? []
+        : this.directEdges.filter((edge) => {
+          if (this.reachableAgentIds == null) return true;
+          const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+          return sources.every((id) => this.reachableAgentIds!.has(id));
+        });
 
     // Add all agents as complete subgraphs
     for (const agentId of agentIds) {
@@ -1348,6 +1485,7 @@ export class MultiAgentGraph extends StandardGraph {
         state: t.MultiAgentGraphState,
         config?: LangGraphRunnableConfig
       ): Promise<t.MultiAgentGraphState | Command> => {
+        this.handoffRouting?.restore(state.handoffState);
         let result: t.MultiAgentGraphState;
         let inputMessages = state.messages;
         const agentContext = this.agentContexts.get(agentId);

package/src/graphs/acceptedModelResponse.ts

@@ -0,0 +1,307 @@
+import { types } from 'node:util';
+import type { AIMessageChunk } from '@langchain/core/messages';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { ModelResponseEvent } from '@/types';
+import {
+  cloneToolArguments,
+  serializeToolArguments,
+} from '@/utils/acceptedToolArguments';
+import { linkStreamLimitCanonical } from '@/llm/streamLimits';
+
+const MAX_SNAPSHOT_BYTES = 4 * 1024 * 1024;
+const MAX_SNAPSHOT_CALLS = 1024;
+
+export class InvalidModelToolCallError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidModelToolCallError';
+  }
+}
+
+/** Detach executable calls before dispatch. Invalid diagnostics remain available
+ * for ToolNode to synthesize paired error results; accepted projection rejects them.
+ */
+export function detachValidatedModelToolCalls(
+  message: AIMessageChunk,
+  partial = false
+): void {
+  try {
+    // Inspect every collection before replacing any provider-owned data. Raw
+    // fragments are read by accounting and handlers even when tool_calls is empty.
+    const toolCalls = snapshotToolCalls(message, true, partial);
+    const chunks = snapshotToolRecords(message, 'tool_call_chunks');
+    const invalid = snapshotToolRecords(message, 'invalid_tool_calls');
+    Object.defineProperties(message, {
+      tool_calls: {
+        value: toolCalls,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      },
+      tool_call_chunks: {
+        value: chunks,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      },
+      invalid_tool_calls: {
+        value: invalid,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      },
+    });
+  } catch (error) {
+    throw new InvalidModelToolCallError(
+      error instanceof Error
+        ? error.message
+        : 'Accepted model response contains non-serializable tool calls'
+    );
+  }
+}
+
+/** Inspect original descriptors before a getter, proxy, or custom instance can
+ * be normalized away. The bound applies to each model message independently.
+ */
+function snapshotToolCalls(
+  finalResponse: AIMessageChunk,
+  allowInvalidDiagnostics: boolean,
+  allowFragmentArgs = false
+): ToolCall[] {
+  // Read own data descriptors, not accessors supplied by a custom model. Invalid
+  // diagnostics are rejected in O(1); cloning them can run getters and bypass
+  // the valid-call snapshot's byte/count limits.
+  if (types.isProxy(finalResponse)) {
+    throw new Error(
+      'Accepted model response contains non-serializable tool calls'
+    );
+  }
+  const calls = Object.getOwnPropertyDescriptor(finalResponse, 'tool_calls');
+  const diagnostics = Object.getOwnPropertyDescriptor(
+    finalResponse,
+    'invalid_tool_calls'
+  );
+  const readArray = (descriptor: PropertyDescriptor | undefined): unknown[] => {
+    if (descriptor === undefined) return [];
+    if (!('value' in descriptor)) {
+      throw new Error(
+        'Accepted model response contains non-serializable tool calls'
+      );
+    }
+    const value: unknown = descriptor.value;
+    if (value === undefined) return [];
+    if (types.isProxy(value) || !Array.isArray(value)) {
+      throw new Error(
+        'Accepted model response contains non-serializable tool calls'
+      );
+    }
+    return value;
+  };
+  if (readArray(diagnostics).length > 0 && !allowInvalidDiagnostics) {
+    throw new Error('Accepted model response contains invalid tool calls');
+  }
+  const source = readArray(calls);
+  if (!allowInvalidDiagnostics && source.length > MAX_SNAPSHOT_CALLS) {
+    throw new Error('Accepted model response exceeds snapshot limits');
+  }
+  const toolCalls: ToolCall[] = [];
+  let remaining = allowInvalidDiagnostics ? Infinity : MAX_SNAPSHOT_BYTES;
+  for (let index = 0; index < source.length; index++) {
+    const entry = Object.getOwnPropertyDescriptor(source, String(index));
+    if (entry == null || !('value' in entry) || entry.enumerable !== true) {
+      throw new Error(
+        'Accepted model response contains non-serializable tool calls'
+      );
+    }
+    const call: unknown = entry.value;
+    if (call == null || typeof call !== 'object' || types.isProxy(call)) {
+      throw new Error(
+        'Accepted model response contains non-serializable tool calls'
+      );
+    }
+    const name = Object.getOwnPropertyDescriptor(call, 'name');
+    const originalId = Object.getOwnPropertyDescriptor(call, 'id');
+    const originalArgs = Object.getOwnPropertyDescriptor(call, 'args');
+    if (
+      name == null ||
+      !('value' in name) ||
+      typeof name.value !== 'string' ||
+      originalArgs == null ||
+      !('value' in originalArgs) ||
+      (originalId != null && !('value' in originalId))
+    ) {
+      throw new Error(
+        'Accepted model response contains non-serializable tool calls'
+      );
+    }
+    const providerId: unknown = originalId?.value;
+    if (providerId !== undefined && typeof providerId !== 'string') {
+      throw new Error(
+        'Accepted model response contains non-serializable tool calls'
+      );
+    }
+    let args: ToolCall['args'];
+    if (allowInvalidDiagnostics) {
+      // Callback streams may carry a not-yet-plannable argument string. It is
+      // safe scalar data, but must not become an accepted executable call.
+      args =
+        allowFragmentArgs && typeof originalArgs.value === 'string'
+          ? (originalArgs.value as unknown as ToolCall['args'])
+          : cloneToolArguments(originalArgs.value);
+    } else {
+      remaining -=
+        Buffer.byteLength(name.value, 'utf8') +
+        (typeof providerId === 'string'
+          ? Buffer.byteLength(providerId, 'utf8')
+          : 0);
+      const encoded = serializeToolArguments(originalArgs.value, remaining);
+      remaining -= Buffer.byteLength(encoded, 'utf8');
+      args = JSON.parse(encoded);
+    }
+    toolCalls.push({
+      name: name.value,
+      id: providerId,
+      args,
+      type: 'tool_call',
+    });
+  }
+  return toolCalls;
+}
+
+/** Only the accepted final response becomes a host-visible model result. */
+export function snapshotAcceptedModelResponse(
+  finalResponse: AIMessageChunk,
+  id: string,
+  agentId: string,
+  providerExecutedIds?: ReadonlySet<string>,
+  clientDelegatedToolNames?: ReadonlySet<string>
+): ModelResponseEvent {
+  const toolCalls = snapshotToolCalls(finalResponse, false);
+  const hasClientCall = toolCalls.some(
+    (call) => clientDelegatedToolNames?.has(call.name) === true
+  );
+  if (
+    hasClientCall &&
+    (toolCalls.some(
+      (call) =>
+        clientDelegatedToolNames?.has(call.name) !== true ||
+        (call.id != null && providerExecutedIds?.has(call.id) === true)
+    ) ||
+      (finalResponse.invalid_tool_calls?.length ?? 0) > 0)
+  ) {
+    throw new InvalidModelToolCallError(
+      'Mixed client and graph-owned tool calls require separate model turns'
+    );
+  }
+  return {
+    type: 'model_response',
+    id,
+    agentId,
+    ...(finalResponse.id != null ? { messageId: finalResponse.id } : {}),
+    toolCalls,
+    toolCallDispositions: toolCalls.map((call) => {
+      if (hasClientCall) return 'client';
+      return call.id != null && providerExecutedIds?.has(call.id) === true
+        ? 'provider'
+        : 'sdk';
+    }),
+    invalidToolCalls: [],
+  };
+}
+
+/** These records contain only scalar fields, unlike parsed tool arguments. Never
+ * spread or iterate provider records until their original descriptors pass.
+ */
+function snapshotToolRecords(
+  message: AIMessageChunk,
+  field: 'tool_call_chunks' | 'invalid_tool_calls'
+): Record<string, unknown>[] {
+  function invalid(): never {
+    throw new Error(
+      'Accepted model response contains non-serializable tool calls'
+    );
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(message, field);
+  if (descriptor == null) return [];
+  if (!('value' in descriptor)) invalid();
+  const source: unknown = descriptor.value;
+  if (source === undefined) return [];
+  if (source == null || types.isProxy(source) || !Array.isArray(source))
+    invalid();
+  const result: Record<string, unknown>[] = [];
+  for (let index = 0; index < source.length; index++) {
+    const entry = Object.getOwnPropertyDescriptor(source, String(index));
+    if (entry == null || !('value' in entry)) invalid();
+    const record: unknown = entry.value;
+    if (record == null || typeof record !== 'object' || types.isProxy(record))
+      invalid();
+    const copy: Record<string, unknown> = {};
+    for (const key of Reflect.ownKeys(record)) {
+      if (typeof key !== 'string') invalid();
+      const property = Object.getOwnPropertyDescriptor(record, key);
+      if (property == null || !('value' in property)) invalid();
+      const value: unknown = property.value;
+      if (
+        value != null &&
+        (key === 'index'
+          ? typeof value !== 'number' ||
+            !Number.isSafeInteger(value) ||
+            value < 0
+          : typeof value !== 'string')
+      )
+        invalid();
+      Object.defineProperty(copy, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+    }
+    result.push(copy);
+  }
+  return result;
+}
+
+/** Providers can mutate and re-yield records. Inspect a per-emission snapshot,
+ * leaving their originals intact, but keep producer/consumer charge identity.
+ */
+export function snapshotValidatedModelChunk(
+  message: AIMessageChunk,
+  partial = true
+): AIMessageChunk {
+  if (types.isProxy(message)) {
+    throw new InvalidModelToolCallError(
+      'Accepted model response contains non-serializable tool calls'
+    );
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(message);
+  // Object.freeze on the provider result must not freeze the SDK's own
+  // envelope. LangChain updates IDs, lc_kwargs and response metadata later.
+  for (const descriptor of Object.values(descriptors)) {
+    descriptor.configurable = true;
+    if ('value' in descriptor) descriptor.writable = true;
+  }
+  const kwargs = descriptors.lc_kwargs;
+  if (Object.hasOwn(descriptors, 'lc_kwargs') && 'value' in kwargs) {
+    const value: unknown = kwargs.value;
+    if (value === null || typeof value !== 'object' || types.isProxy(value)) {
+      throw new InvalidModelToolCallError('Invalid model response metadata');
+    }
+    const fields = Object.getOwnPropertyDescriptors(value);
+    for (const field of Object.values(fields)) {
+      if (!('value' in field)) {
+        throw new InvalidModelToolCallError('Invalid model response metadata');
+      }
+      field.configurable = true;
+      field.writable = true;
+    }
+    kwargs.value = Object.create(Object.getPrototypeOf(value), fields);
+  }
+  const copy = Object.create(
+    Object.getPrototypeOf(message),
+    descriptors
+  ) as AIMessageChunk;
+  detachValidatedModelToolCalls(copy, partial);
+  if (partial) linkStreamLimitCanonical(copy, message);
+  return copy;
+}