@librechat/agents 3.9.1 → 3.9.3

package/dist/types/graphs/MultiAgentGraph.d.ts

@@ -24,6 +24,7 @@ export declare class MultiAgentGraph extends StandardGraph {
     private handoffSourceIds;
     private readonly resultAgentId?;
     private readonly memberRecursionLimit?;
+    private reachableAgentIds?;
     private handoffPromptLabels;
     /**
      * Map of agentId to parallel group info.
@@ -37,6 +38,8 @@ export declare class MultiAgentGraph extends StandardGraph {
      */
     private agentParallelGroups;
     constructor(input: t.MultiAgentGraphInput, dependencies?: GraphFactoryDependencies);
+    private validateHandoffScopes;
+    private resolveEntryReachability;
     /**
      * Fails fast when an edge references an agent that is not in
      * `agentContexts`. Without this check, the underlying LangGraph

package/dist/types/graphs/handoff.d.ts

@@ -0,0 +1,28 @@
+import { Command } from '@langchain/langgraph';
+import type { BaseChannel, OverwriteValue } from '@langchain/langgraph';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { BaseGraphState, HandoffOutcome, HandoffState, HandoffTransition } from '@/types/graph';
+export type HandoffRequest = Pick<HandoffTransition, 'sourceAgentId' | 'targetAgentId' | 'toolCallId' | 'scope'>;
+/** Union by identity makes checkpoint replay idempotent and parallel merges commutative. */
+export declare function mergeHandoffState(current: HandoffState | undefined, update: HandoffState | undefined): HandoffState | undefined;
+export declare function handoffStateAnnotation(): BaseChannel<HandoffState | undefined, HandoffState | OverwriteValue<HandoffState | undefined> | undefined>;
+export declare class HandoffLimitError extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+/** One owner per graph, never shared with isolated child executions. */
+export declare class HandoffRouting {
+    private readonly entryAgentId;
+    private readonly maxHandoffs;
+    private readonly parallel;
+    private state;
+    constructor(entryAgentId: string, maxHandoffs: number | undefined, parallel: boolean);
+    private freshState;
+    start(): HandoffState;
+    resume(state: HandoffState | undefined): void;
+    restore(state: HandoffState | undefined): void;
+    snapshot(): HandoffState;
+    /** Called after tools settle but before Commands can schedule recipients. */
+    finalize(commands: Command[], input: BaseGraphState, config: RunnableConfig): void;
+    outcome(reason?: string): HandoffOutcome;
+}

package/dist/types/graphs/index.d.ts

@@ -2,3 +2,4 @@ export * from './Graph';
 export * from './MultiAgentGraph';
 export * from './createGraph';
 export type * from './graphFactory';
+export { HandoffLimitError } from './handoff';

package/dist/types/run.d.ts

@@ -60,6 +60,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     /** Distinguishes sibling forks started from the same explicit checkpoint. */
     private checkpointForkSeq;
     private _haltedReason;
+    private _handoffOutcome?;
     private constructor();
     private createLegacyGraph;
     private createMultiAgentGraph;
@@ -216,6 +217,9 @@ export declare class Run<_T extends t.BaseGraphState> {
      * no halt reason.
      */
     getHaltReason(): string | undefined;
+    private getHandoffIncompleteReason;
+    /** Execution evidence only. The host must authorize and durably commit a candidate. */
+    getHandoffOutcome(): t.HandoffOutcome | undefined;
     /**
      * Resume a paused HITL run with the value the user (or whatever
      * decided the interrupt) supplied. The default `TResume` covers the

package/dist/types/tools/ToolNode.d.ts

@@ -228,7 +228,8 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, toolDefinitions, getDiscoveredToolNames, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, executionContext, executingAgentName, rootAgentId, rootAgentName, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, preparedSubagents, restoreRunStepResumeState, createRunStepResumeState, }: t.ToolNodeConstructorParams);
+    private handoffRouting?;
+    constructor({ handoffRouting, tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, toolDefinitions, getDiscoveredToolNames, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, executionContext, executingAgentName, rootAgentId, rootAgentName, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, preparedSubagents, restoreRunStepResumeState, createRunStepResumeState, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     private withToolScope;
     /**

package/dist/types/types/graph.d.ts

@@ -27,9 +27,47 @@ export type ClientCallbacks = {
 export type SystemCallbacks = {
     [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<infer Args> ? (...args: Args) => void : never;
 };
+/** An executed, SDK-generated handoff, identified independently of stream events. */
+export interface HandoffTransition {
+    id: string;
+    sourceAgentId: string;
+    targetAgentId: string;
+    toolCallId: string;
+    scope: 'turn' | 'conversation';
+    /** Causal order: number of handoffs visible at this batch's input. */
+    depth: number;
+}
+/** Versioned graph checkpoint payload, scoped to one logical user turn. */
+export interface HandoffState {
+    version: 1;
+    executionId: string;
+    entryAgentId: string;
+    maxHandoffs?: number;
+    transitions: HandoffTransition[];
+    parallel: boolean;
+    /** False when resuming an older checkpoint without complete routing provenance. */
+    historyComplete?: boolean;
+}
+/** Only a candidate from a completed top-level run may be promoted by a host. */
+export type HandoffOutcome = {
+    executionId: string;
+    entryAgentId: string;
+    transitions: readonly HandoffTransition[];
+} & ({
+    status: 'candidate';
+    agentId: string;
+    transitionId: string;
+} | {
+    status: 'unchanged' | 'ambiguous';
+} | {
+    status: 'incomplete';
+    reason: string;
+});
 export type BaseGraphState = {
     messages: BaseMessage[];
     runStepState?: RunStepResumeState;
+    /** SDK-owned routing state; hosts must not synthesize it from messages. */
+    handoffState?: HandoffState;
     /**
      * The summary a summarize-only run produced. Kept in state because such a
      * run has no assistant reply: trace roots report it as the run's output
@@ -316,6 +354,8 @@ export type GraphEdge = {
     condition?: (state: BaseGraphState) => boolean | string | string[];
     /** 'handoff' creates tools for dynamic routing, 'direct' creates direct edges, which also allow parallel execution */
     edgeType?: 'handoff' | 'direct';
+    /** Host may promote the destination after successful top-level completion. */
+    handoffScope?: 'turn' | 'conversation';
     /**
      * For direct edges: Optional prompt to add when transitioning through this edge.
      * String prompts can include variables like {results} which will be replaced with
@@ -337,13 +377,18 @@ export type GraphEdge = {
      */
     promptKey?: string;
 };
-export type GraphSubagentEdge = Omit<GraphEdge, 'edgeType' | 'condition' | 'promptKey'> & {
+export type GraphSubagentEdge = Omit<GraphEdge, 'edgeType' | 'condition' | 'promptKey' | 'handoffScope'> & {
     edgeType: 'direct';
     condition?: never;
     promptKey?: never;
+    handoffScope?: never;
 };
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];
+    /** Explicit fresh-turn entry; absent preserves topology-inferred entry points. */
+    entryAgentId?: string;
+    /** Shared logical-turn handoff cap. Zero forbids handoffs; absent uses only recursion limits. */
+    maxHandoffs?: number;
     /** Captures the designated member's final AI turn in graph state. */
     resultAgentId?: string;
     /** Optional per-member Pregel budget when the outer graph has its own topology budget. */

package/dist/types/types/run.d.ts

@@ -101,8 +101,10 @@ export type MultiAgentGraphConfig = {
     compileOptions?: g.CompileOptions;
     agents: g.AgentInputs[];
     edges: g.GraphEdge[];
+    entryAgentId?: string;
+    maxHandoffs?: number;
 };
-export type StandardGraphConfig = Omit<MultiAgentGraphConfig, 'edges' | 'type'> & {
+export type StandardGraphConfig = Omit<MultiAgentGraphConfig, 'edges' | 'type' | 'entryAgentId' | 'maxHandoffs'> & {
     type?: 'standard';
     signal?: AbortSignal;
 };

package/dist/types/types/tools.d.ts

@@ -6,6 +6,7 @@ import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { LangfuseConfig, SubagentExecutionContext } from './graph';
 import type { PreparedSubagents } from '@/tools/preparedSubagents';
 import type { RunBreakerScope } from '@/llm/streamLimits';
+import type { HandoffRouting } from '@/graphs/handoff';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { HookRegistry } from '@/hooks';
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
@@ -103,6 +104,8 @@ export type EagerEventToolCallChunkState = {
     sealedArgsFragment?: string;
 };
 export type ToolNodeOptions = {
+    /** @internal Admission shared by tool nodes belonging to one multi-agent graph. */
+    handoffRouting?: Pick<HandoffRouting, 'finalize'>;
     name?: string;
     tags?: string[];
     /** Enables LangChain/LangGraph tracing for this ToolNode. Defaults to false. */

package/dist/types/utils/toolContent.d.ts

@@ -16,7 +16,7 @@ type StructuredWorkState = {
 export type BoundedStructuredSerialization = {
     /** Provider-facing head/tail preview, bounded by `maxChars`. */
     content: string;
-    /** Exact serialized prefix up to the defensive traversal-work ceiling. */
+    /** Code-point-aligned serialized prefix up to the traversal-work ceiling. */
     prefix: string;
     /** Exact length, or `Number.MAX_SAFE_INTEGER` when traversal was capped. */
     originalChars: number;

package/dist/types/utils/truncation.d.ts

@@ -4,6 +4,8 @@
  * Prevents oversized tool outputs from entering the message array and
  * consuming the entire context window.
  */
+/** Slices by UTF-16 code units, dropping orphaned surrogate halves at either edge. */
+export declare function sliceWithoutSplittingSurrogates(value: string, start: number, end?: number): string;
 /**
  * Absolute hard cap on tool result length (characters).
  * Even if the model has a 1M-token context, a single tool result

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.9.1",
+  "version": "3.9.3",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/graphs/Graph.ts

@@ -38,6 +38,7 @@ import type {
 } from '@/graphs/graphFactory';
 import type { OverflowRecoveryPlan } from '@/llm/contextOverflowRecovery';
 import type { FallbackErrorContext } from '@/llm/invoke';
+import type { HandoffRouting } from './handoff';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 import {
@@ -185,6 +186,7 @@ import { getTruncationStopReason } from '@/llm/truncation';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
 import { createFakeStreamingLLM } from '@/llm/fake';
+import { handoffStateAnnotation } from './handoff';
 import { handleToolCalls } from '@/tools/handlers';
 import { isThinkingEnabled } from '@/llm/request';
 import { resolveMaxSeals } from '@/llm/preempt';
@@ -1354,6 +1356,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   subagentUsageSink?: t.SubagentUsageSink;
   /** See {@link t.StandardGraphInput.subagentScope}. */
   subagentScope: boolean;
+  handoffRouting?: HandoffRouting;
   /** See {@link t.StandardGraphInput.subagentTasks}. */
   subagentTasks: t.SubagentTaskConfig | undefined;
   /** See {@link t.StandardGraphInput.subagentExecutionContext}. */
@@ -2871,6 +2874,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       }
 
       const node = new CustomToolNode<t.BaseGraphState>({
+        handoffRouting: this.handoffRouting,
         tools: allTools,
         toolMap: allToolMap,
         trace: traceToolNode,
@@ -2960,6 +2964,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         : currentToolMap;
 
     const node = new CustomToolNode<t.BaseGraphState>({
+      handoffRouting: this.handoffRouting,
       tools: allTraditionalTools,
       toolMap: traditionalToolMap,
       trace: traceToolNode,
@@ -5434,6 +5439,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     ): Promise<Partial<t.AgentSubgraphState>> => {
       this.config = config;
       this.restoreRunStepResumeState(state.runStepState);
+      this.handoffRouting?.restore(state.handoffState);
       const result = await invoke();
       /** An ordinary run on a checkpointed thread inherits the last
        *  compaction's summary in state; it is not this run's output. */
@@ -5512,6 +5518,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         default: () => undefined,
       }),
       runStepState: this.createRunStepStateAnnotation(),
+      handoffState: handoffStateAnnotation(),
     });
 
     const readChargeCredits = ():
@@ -5727,6 +5734,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         default: () => undefined,
       }),
       runStepState: this.createRunStepStateAnnotation(),
+      handoffState: handoffStateAnnotation(),
     });
     const compactingAgentNode = async (
       state: t.AgentSubgraphState,

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);