@librechat/agents 3.9.2 → 3.9.4

package/src/run.ts

@@ -111,6 +111,7 @@ import { initializeLangfuseTracing } from './instrumentation';
 import { seedRunInitialSessions } from '@/utils/toolSessions';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
 import { resolveClientOptionsModel } from '@/llm/request';
+import { HandoffLimitError } from '@/graphs/handoff';
 import { createGraph } from '@/graphs/createGraph';
 import { isFadingTier } from '@/messages/fading';
 import { resolveMaxSeals } from '@/llm/preempt';
@@ -291,6 +292,7 @@ function getInterruptHookSessionId(payload: unknown): string | undefined {
 type InterruptStateSnapshot = {
   config?: RunnableConfig;
   values?: {
+    handoffState?: t.HandoffState;
     messages?: BaseMessage[];
     runStepState?: t.RunStepResumeState;
   };
@@ -466,6 +468,7 @@ export class Run<_T extends t.BaseGraphState> {
   private langfuse?: t.LangfuseConfig;
   private toolOutputReferences?: t.ToolOutputReferencesConfig;
   private eagerEventToolExecution?: t.EagerEventToolExecutionConfig;
+  private clientDelegatedToolNames?: readonly string[];
   private codeSessionToolNames?: string[];
   private interruptingToolNames?: string[];
   private toolExecution?: t.ToolExecutionConfig;
@@ -512,6 +515,7 @@ export class Run<_T extends t.BaseGraphState> {
   /** Distinguishes sibling forks started from the same explicit checkpoint. */
   private checkpointForkSeq = 0;
   private _haltedReason: string | undefined;
+  private _handoffOutcome?: t.HandoffOutcome;
 
   private constructor(config: Partial<t.RunConfig>) {
     const runId = config.runId ?? '';
@@ -546,12 +550,19 @@ export class Run<_T extends t.BaseGraphState> {
       }
     }
 
+    if (
+      (config.clientDelegatedToolNames?.length ?? 0) > 0 &&
+      handlerRegistry.getHandler(GraphEvents.ON_MODEL_RESPONSE) == null
+    ) {
+      throw new Error('Client tool delegation requires an accepted-result handler');
+    }
     this.handlerRegistry = handlerRegistry;
     this.hookRegistry = config.hooks;
     this.humanInTheLoop = config.humanInTheLoop;
     this.langfuse = config.langfuse;
     this.toolOutputReferences = config.toolOutputReferences;
     this.eagerEventToolExecution = config.eagerEventToolExecution;
+    this.clientDelegatedToolNames = config.clientDelegatedToolNames;
     this.codeSessionToolNames = config.codeSessionToolNames;
     this.interruptingToolNames = config.interruptingToolNames;
     this.toolExecution = config.toolExecution;
@@ -570,6 +581,9 @@ export class Run<_T extends t.BaseGraphState> {
 
     /** Handle different graph types */
     if (config.graphConfig.type === 'multi-agent') {
+      if (this.clientDelegatedToolNames != null && this.clientDelegatedToolNames.length > 0) {
+        throw new Error('Client tool delegation requires a single-agent graph');
+      }
       this.graphRunnable = this.createMultiAgentGraph(config.graphConfig);
       if (this.Graph) {
         this.Graph.handlerRegistry = handlerRegistry;
@@ -660,6 +674,7 @@ export class Run<_T extends t.BaseGraphState> {
         preemption: this.preemption,
         streamLimits: this.streamLimits,
         toolExecution: this.toolExecution,
+        clientDelegatedToolNames: this.clientDelegatedToolNames,
       },
     });
     /** Propagate compile options from graph config */
@@ -683,7 +698,7 @@ export class Run<_T extends t.BaseGraphState> {
   private createMultiAgentGraph(
     config: t.MultiAgentGraphConfig
   ): t.CompiledStateWorkflow {
-    const { agents, edges, compileOptions } = config;
+    const { agents, edges, compileOptions, entryAgentId, maxHandoffs } = config;
 
     const multiAgentGraph = createGraph({
       kind: 'multi-agent',
@@ -691,6 +706,8 @@ export class Run<_T extends t.BaseGraphState> {
         runId: this.id,
         agents,
         edges,
+        entryAgentId,
+        maxHandoffs,
         langfuse: this.langfuse,
         tokenCounter: this.tokenCounter,
         indexTokenCountMap: this.indexTokenCountMap,
@@ -1053,6 +1070,11 @@ export class Run<_T extends t.BaseGraphState> {
       ) {
         return;
       }
+      // Accepted results are graph-owned, never inferred from provider/tool callbacks.
+      if (
+        eventName === GraphEvents.ON_MODEL_RESPONSE ||
+        eventName === GraphEvents.ON_MODEL_TOOLS_CLAIMED
+      ) return;
       const handler = this.handlerRegistry?.getHandler(eventName);
       /**
        * Tool completions arriving over the custom-event channel are the only
@@ -1237,6 +1259,7 @@ export class Run<_T extends t.BaseGraphState> {
     }
     const graphRunnable = this.graphRunnable;
     const graph = this.Graph;
+    this._handoffOutcome = undefined;
 
     /**
      * `Command` inputs (`Command({ resume, update?, goto? })`) are
@@ -1347,6 +1370,7 @@ export class Run<_T extends t.BaseGraphState> {
             checkpointId === '' ? 0 : ++this.checkpointForkSeq,
           ]);
       graph.resetValues(streamOptions?.keepContent, checkpointScope);
+      graph.handoffRouting?.start();
       graph.startStopContinuationExecution(nanoid());
     }
     this._interrupt = undefined;
@@ -1482,9 +1506,18 @@ export class Run<_T extends t.BaseGraphState> {
 
     const consumeStream = async (): Promise<void> => {
       let streamInputs: t.IState | Command = inputs;
-      if (!isResume && this.hasCheckpointer) {
+      if (!isResume && graph.handoffRouting != null) {
         streamInputs = {
           ...(inputs as t.IState),
+          handoffState: graph.handoffRouting.snapshot(),
+        };
+      }
+      if (!isResume && this.hasCheckpointer) {
+        streamInputs = {
+          ...(streamInputs as t.IState),
+          ...(graph.handoffRouting == null
+            ? {}
+            : { handoffState: new Overwrite(graph.handoffRouting.snapshot()) }),
           runStepState: new Overwrite(graph.createRunStepResumeState()),
         } as unknown as t.IState;
       } else if (overwriteLegacyResumeState) {
@@ -1538,6 +1571,10 @@ export class Run<_T extends t.BaseGraphState> {
 
           const modelEndAt =
             eventName === GraphEvents.CHAT_MODEL_END ? Date.now() : undefined;
+          if (
+            eventName === GraphEvents.ON_MODEL_RESPONSE ||
+            eventName === GraphEvents.ON_MODEL_TOOLS_CLAIMED
+          ) continue;
           const handler = this.handlerRegistry?.getHandler(eventName);
           if (handler) {
             await handler.handle(eventName, data, metadata, this.Graph);
@@ -1679,6 +1716,7 @@ export class Run<_T extends t.BaseGraphState> {
                 ? injected
                 : [...graph.messages, ...injected],
               runStepState: graph.createRunStepResumeState(),
+              handoffState: graph.handoffRouting?.snapshot(),
             };
             streamConfig = completedSegmentConfig;
             continue;
@@ -1716,6 +1754,8 @@ export class Run<_T extends t.BaseGraphState> {
     } catch (err) {
       terminalAt = Date.now();
       streamThrew = true;
+      if (err instanceof HandoffLimitError)
+        this._haltedReason = 'handoff_limit';
       await langfuseHandler?.handleChainError(
         err instanceof Error ? err : new Error(String(err)),
         this.id
@@ -1860,6 +1900,13 @@ export class Run<_T extends t.BaseGraphState> {
        * `HumanInTheLoopConfig` JSDoc.
        */
       const awaitingResume = this.isAwaitingResume(streamThrew);
+      this._handoffOutcome = graph.handoffRouting?.outcome(
+        this.getHandoffIncompleteReason(
+          streamThrew,
+          awaitingResume,
+          config.signal
+        )
+      );
       if (!this.skipCleanup && !awaitingResume) {
         this.Graph.clearHeavyState();
       }
@@ -1921,6 +1968,31 @@ export class Run<_T extends t.BaseGraphState> {
     return this._haltedReason;
   }
 
+  private getHandoffIncompleteReason(
+    streamThrew: boolean,
+    awaitingResume: boolean,
+    signal?: AbortSignal
+  ): string | undefined {
+    if (this._haltedReason != null) return this._haltedReason;
+    if (signal?.aborted === true || this.Graph?.signal?.aborted === true) {
+      return 'aborted';
+    }
+    if (streamThrew) return 'error';
+    if (awaitingResume) return 'interrupted';
+    if (this.Graph?.subagentScope === true) return 'subagent';
+    return undefined;
+  }
+
+  /** Execution evidence only. The host must authorize and durably commit a candidate. */
+  getHandoffOutcome(): t.HandoffOutcome | undefined {
+    const outcome = this._handoffOutcome;
+    if (outcome == null) return undefined;
+    return {
+      ...outcome,
+      transitions: outcome.transitions.map((item) => ({ ...item })),
+    };
+  }
+
   /**
    * Resume a paused HITL run with the value the user (or whatever
    * decided the interrupt) supplied. The default `TResume` covers the
@@ -2134,6 +2206,7 @@ export class Run<_T extends t.BaseGraphState> {
     const snapshot = await workflow.getState(callerConfig as RunnableConfig, {
       subgraphs: true,
     });
+    this.Graph?.handoffRouting?.resume(snapshot.values?.handoffState);
     const persistedInterrupt = getFirstPersistedInterrupt(snapshot);
     if (persistedInterrupt == null) {
       return;

package/src/session/AgentSession.ts

@@ -27,6 +27,7 @@ import {
   deriveSessionMessages,
   releaseSessionProjection,
 } from './sessionProjection';
+import { FADING_TIER_VERSION, isFadingTier } from '@/messages/fading';
 import { createSummarizeNode } from '@/summarization/node';
 import { resolveStreamLimits } from '@/llm/streamLimits';
 import { JsonlSessionStore } from './JsonlSessionStore';
@@ -34,7 +35,6 @@ import { AgentContext } from '@/agents/AgentContext';
 import { ContentTypes, GraphEvents } from '@/common';
 import { createRunId, createSessionId } from './ids';
 import { deriveMessages } from './deriveMessages';
-import { isFadingTier } from '@/messages/fading';
 import { createRunHandlers } from './handlers';
 import { Run } from '@/run';
 
@@ -420,7 +420,7 @@ function mergeFadingTier(
     masked !== current.masked ||
     masked !== incoming.masked;
   return {
-    v: 1,
+    v: FADING_TIER_VERSION,
     budgetTokens,
     masked,
     ...(latched ? { latched: true } : {}),

package/src/stream.ts

@@ -56,6 +56,7 @@ import {
   truncateToolResultContent,
 } from '@/utils/truncation';
 import { resolveToolOutcome, outcomeFieldsFromResult } from '@/tools/intentArg';
+import { snapshotValidatedModelChunk } from '@/graphs/acceptedModelResponse';
 import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { isReasoningContentBlock } from '@/messages/core';
@@ -746,6 +747,10 @@ function createEagerToolExecutionPlan(args: {
         toolCall.id == null ||
         toolCall.id === '' ||
         toolCall.name === '' ||
+        // A serialized parsed call is not a prepared executable object;
+        // parsing is permitted only on sealed raw tool_call_chunks.
+        typeof toolCall.args === 'string' ||
+        graph.clientDelegatedToolNames?.has(toolCall.name) === true ||
         (!skipExisting && graph.eagerEventToolExecutions.has(toolCall.id))
     )
   ) {
@@ -794,6 +799,9 @@ function startEagerToolExecutions(args: {
   skipExisting?: boolean;
 }): void {
   const { graph, metadata, agentContext, toolCalls, skipExisting } = args;
+  // A later call in the same model turn may be client-delegated. Do not
+  // pre-execute an earlier SDK call in a run that rejects mixed batches.
+  if ((graph.clientDelegatedToolNames?.size ?? 0) > 0) return;
   const entries = createEagerToolExecutionPlan({
     graph,
     metadata,
@@ -1345,6 +1353,10 @@ function startPreparedSubagents(
   metadata?: Record<string, unknown>
 ): void {
   const attempt = resolveGenerationKey(metadata);
+  if ((graph.clientDelegatedToolNames?.size ?? 0) > 0) return;
+  // A parsed string call is not executable even if the same event carries
+  // sealed raw fragments. Wait for a separately validated complete call.
+  if (chunk.tool_calls?.some((call) => typeof call.args === 'string') === true) return;
   if (
     (graph as Partial<StandardGraph>).canPrestartSubagents?.(agentContext) !==
       true ||
@@ -1389,6 +1401,9 @@ function startPreparedSubagents(
   for (const call of calls) {
     if (
       call.name === Constants.SUBAGENT &&
+      graph.clientDelegatedToolNames?.has(call.name) !== true &&
+      typeof call.args === 'object' &&
+      !Array.isArray(call.args) &&
       !hasToolOutputReference(call.args)
     ) {
       graph.prestartSubagent(call, attempt, agentContext);
@@ -1643,7 +1658,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
       return;
     }
 
-    const chunk = data.chunk as Partial<AIMessageChunk>;
+    let chunk = data.chunk as Partial<AIMessageChunk>;
 
     /** Attempts stamp their breaker epoch into event metadata; a mismatch
      * marks a straggling chunk from a failed run that outlived
@@ -1681,6 +1696,10 @@ export class ChatModelStreamHandler implements t.EventHandler {
       }
     };
 
+    // Callback delivery can beat the producer's iterator. Validate before
+    // accounting, run steps, or eager dispatch reads raw tool descriptors.
+    chunk = snapshotValidatedModelChunk(chunk as AIMessageChunk);
+
     /**
      * Enforced before every content-specific early return below
      * (server-tool results, deferred mixed reasoning, late OpenRouter
@@ -1885,6 +1904,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
           chunk.response_metadata as Record<string, unknown> | undefined
         );
       const canStreamEager =
+        chunk.tool_calls?.some((call) => typeof call.args === 'string') !== true &&
         (allowSequentialSeal || hasExplicitStreamedToolCallSeals(chunk)) &&
         !hasPotentialDirectToolInStreamContext({ graph, agentContext }) &&
         isEagerToolExecutionEnabledForBatch({ graph, metadata, agentContext });

package/src/tools/ToolNode.ts

@@ -974,8 +974,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    * other's in-flight state.
    */
   private anonBatchCounter: number = 0;
+  private handoffRouting?: t.ToolNodeOptions['handoffRouting'];
 
   constructor({
+    handoffRouting,
     tools,
     toolMap,
     name,
@@ -1019,6 +1021,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     preparedSubagents,
     restoreRunStepResumeState,
     createRunStepResumeState,
+    onToolCallsClaimed,
   }: t.ToolNodeConstructorParams) {
     super({
       name: name ?? TOOL_NODE_RUN_NAME,
@@ -1153,6 +1156,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         }
         const state = input as T & Pick<t.BaseGraphState, 'runStepState'>;
         restoreRunStepResumeState?.(state.runStepState, config);
+        // Freeze replay authority before observers can yield to sibling tasks.
+        if (onToolCallsClaimed != null && assistantBatch?.message.id != null) {
+          await onToolCallsClaimed(assistantBatch.message.id, config);
+        }
         let result: T;
         try {
           result = await this.run(input, config, referenceReplay);
@@ -1219,6 +1226,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.runLangfuse = runLangfuse;
     this.agentLangfuse = agentLangfuse;
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
+    this.handoffRouting = handoffRouting;
     this.toolCallStepIds = toolCallStepIds;
     this.handleToolErrors = handleToolErrors ?? this.handleToolErrors;
     this.loadRuntimeTools = loadRuntimeTools;
@@ -3221,10 +3229,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
 
   private retainCodeSessionInputsFromRequests(
     requests: Iterable<t.ToolCallRequest>,
-    baselineByRequestId: ReadonlyMap<
-      string,
-      ReadonlyMap<string, string>
-    >
+    baselineByRequestId: ReadonlyMap<string, ReadonlyMap<string, string>>
   ): void {
     if (!this.sessions) {
       return;
@@ -5140,8 +5145,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         call.id == null
           ? undefined
           : baseContext.resolvedArgsByCallId?.get(call.id);
-      const codeSessionBaseline =
-        baseContext.codeSessionBaselineByCallId?.get(call.id ?? '');
+      const codeSessionBaseline = baseContext.codeSessionBaselineByCallId?.get(
+        call.id ?? ''
+      );
       const result: SettledDirectToolResult = {
         proposal: structuredClone({
           name: call.name,
@@ -6073,6 +6079,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     if (replayBatchKey != null) {
       this.settledDirectResultsByBatch.delete(replayBatchKey);
     }
+    if (!Array.isArray(input) && !this.isSendInput(input)) {
+      this.handoffRouting?.finalize(
+        combinedOutputs.filter(isCommand),
+        input as t.BaseGraphState,
+        config
+      );
+    }
     return combinedOutputs as T;
   }
 

package/src/tools/subagent/SubagentReplay.ts

@@ -8,7 +8,7 @@ import type {
   RunStepResumeState,
   ToolSessionContext,
 } from '@/types';
-import { isFadingTier } from '@/messages/fading';
+import { isFadingTier, isLegacyFadingTier } from '@/messages/fading';
 import {
   attachRunStepResumeState,
   getRunStepResumeState,
@@ -290,6 +290,11 @@ export function isToolOutputReferenceState(
   );
 }
 
+/** A current tier, or a legacy one the run then drops so it re-derives. */
+function isStoredFadingTier(value: unknown): boolean {
+  return isFadingTier(value) || isLegacyFadingTier(value);
+}
+
 function isGraphResumeState(value: unknown): value is SubagentGraphResumeState {
   if (value == null || typeof value !== 'object') {
     return false;
@@ -306,15 +311,14 @@ function isGraphResumeState(value: unknown): value is SubagentGraphResumeState {
     !state.eagerToolUsage.every(isEagerToolUsageState) ||
     !Array.isArray(state.eagerToolSuppressions) ||
     !state.eagerToolSuppressions.every(isString) ||
-    (state.runStepState != null &&
-      !isRunStepResumeState(state.runStepState)) ||
+    (state.runStepState != null && !isRunStepResumeState(state.runStepState)) ||
     (state.toolOutputReferences != null &&
       !isToolOutputReferenceState(state.toolOutputReferences)) ||
-    (state.fadingTier != null && !isFadingTier(state.fadingTier)) ||
+    (state.fadingTier != null && !isStoredFadingTier(state.fadingTier)) ||
     (state.fadingTiers != null &&
       (typeof state.fadingTiers !== 'object' ||
         Array.isArray(state.fadingTiers) ||
-        !Object.values(state.fadingTiers).every(isFadingTier)))
+        !Object.values(state.fadingTiers).every(isStoredFadingTier)))
   ) {
     return false;
   }
@@ -515,10 +519,7 @@ export function attachSubagentResumeManifest(
   const runStepState = getRunStepResumeState(payload);
   if (runStepState != null) {
     return attachRunStepResumeState(
-      attachSubagentResumeManifest(
-        stripRunStepResumeState(payload),
-        manifest
-      ),
+      attachSubagentResumeManifest(stripRunStepResumeState(payload), manifest),
       runStepState
     );
   }

package/src/types/graph.ts

@@ -10,22 +10,24 @@ import type { START, StateGraph, StateGraphArgs } from '@langchain/langgraph';
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type {
-  SummarizationNodeInput,
-  SummarizeCompleteEvent,
-  CompactionSemanticIndex,
-  SummarizationConfig,
-  SummarizeStartEvent,
-  SummarizeDeltaEvent,
-} from '@/types/summarize';
 import type {
   RunStep,
+  ModelResponseEvent,
+  ModelToolsClaimedEvent,
   RunStepDeltaEvent,
   RunStepResumeState,
   RunStepClosedEvent,
   MessageDeltaEvent,
   ReasoningDeltaEvent,
 } from '@/types/stream';
+import type {
+  SummarizationNodeInput,
+  SummarizeCompleteEvent,
+  CompactionSemanticIndex,
+  SummarizationConfig,
+  SummarizeStartEvent,
+  SummarizeDeltaEvent,
+} from '@/types/summarize';
 import type {
   ToolMap,
   ToolSessionMap,
@@ -78,9 +80,45 @@ export type SystemCallbacks = {
     : 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
@@ -147,7 +185,7 @@ export interface ContextUsageEvent {
  * `RunConfig.fadingTiers[agentId]`.
  */
 export interface FadingTier {
-  v: 1;
+  v: 2;
   /** Token budget the caps derive from, in raw token space. Never grows;
    *  clamped to the current context window when seeded. */
   budgetTokens: number;
@@ -166,6 +204,8 @@ export interface EventHandler {
     data:
       | StreamEventData
       | ModelEndData
+      | ModelResponseEvent
+      | ModelToolsClaimedEvent
       | RunStep
       | RunStepDeltaEvent
       | RunStepClosedEvent
@@ -370,6 +410,8 @@ export type StandardGraphInput = {
   agents: AgentInputs[];
   /** Execution backend used to resolve the effective tool registry. */
   toolExecution?: ToolExecutionConfig;
+  /** Trusted single-agent client delegation policy; mixed batches fail closed. */
+  clientDelegatedToolNames?: readonly string[];
   langfuse?: LangfuseConfig;
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;
@@ -434,6 +476,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
@@ -463,15 +507,20 @@ export type GraphEdge = {
 
 export type GraphSubagentEdge = Omit<
   GraphEdge,
-  'edgeType' | 'condition' | 'promptKey'
+  '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/src/types/run.ts

@@ -115,11 +115,13 @@ export type MultiAgentGraphConfig = {
   compileOptions?: g.CompileOptions;
   agents: g.AgentInputs[];
   edges: g.GraphEdge[];
+  entryAgentId?: string;
+  maxHandoffs?: number;
 };
 
 export type StandardGraphConfig = Omit<
   MultiAgentGraphConfig,
-  'edges' | 'type'
+  'edges' | 'type' | 'entryAgentId' | 'maxHandoffs'
 > & { type?: 'standard'; signal?: AbortSignal };
 
 /**
@@ -277,6 +279,11 @@ export type RunConfig = {
    */
   langfuse?: g.LangfuseConfig;
   customHandlers?: Record<string, g.EventHandler>;
+  /** Explicit client-owned tools for a single-agent graph. A batch mixing
+   * client and SDK/provider calls fails closed; omitted means SDK ownership.
+   * Hosts must register the corresponding model-facing tool schemas.
+   */
+  clientDelegatedToolNames?: readonly string[];
   /**
    * Receives token usage for every model call made inside subagent child
    * runs (including nested subagents). Child graphs execute via `invoke()`

package/src/types/stream.ts

@@ -1,5 +1,6 @@
 // src/types/stream.ts
 import type {
+  AIMessageChunk,
   MessageContentImageUrl,
   MessageContentText,
   ToolMessage,
@@ -15,6 +16,24 @@ import type { SummarizeCompleteEvent } from '@/types/summarize';
 import type { ToolEndEvent } from '@/types/tools';
 import { StepTypes, ContentTypes, GraphEvents } from '@/common/enum';
 
+/** One accepted model result, detached from execution state before host dispatch.
+ * Provider chunks, failed attempts and UI run-step events are not this contract. */
+export interface ModelResponseEvent {
+  type: 'model_response';
+  /** Graph-generated acceptance ID, not a provider ID or run-step index. */
+  id: string;
+  agentId: string;
+  /** Graph-state message identity used to correlate ToolNode ownership. */
+  messageId?: string;
+  toolCalls: ReadonlyArray<ToolCall>;
+  /** Same index as toolCalls. Only a trusted graph decision of 'client'
+   * permits this call on the OpenAI client wire; absence fails closed. */
+  toolCallDispositions: ReadonlyArray<'sdk' | 'provider' | 'client'>;
+  invalidToolCalls: ReadonlyArray<
+    NonNullable<AIMessageChunk['invalid_tool_calls']>[number]
+  >;
+}
+
 export type HandleLLMEnd = (
   output: LLMResult,
   runId: string,
@@ -542,3 +561,10 @@ export type ContentAggregatorResult = {
   contentParts: Array<MessageContentComplex | undefined>;
   aggregateContent: ContentAggregator;
 };
+
+/** Ownership, not successful completion. Interrupted/failed batches remain graph-owned. */
+export interface ModelToolsClaimedEvent {
+  type: 'model_tools_claimed';
+  agentId: string;
+  messageId: string;
+}

package/src/types/tools.ts

@@ -14,6 +14,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';
 
@@ -117,6 +118,8 @@ export type EagerEventToolCallChunkState = {
 };
 
 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. */
@@ -310,6 +313,8 @@ export type ToolNodeOptions = {
   ) => void;
   /** SDK-owned checkpoint snapshot for open run-step lifecycle state. */
   createRunStepResumeState?: () => RunStepResumeState;
+  /** Internal ownership bridge, awaited before ToolNode can execute a batch. */
+  onToolCallsClaimed?: (messageId: string, config: RunnableConfig) => Promise<void>;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;