@librechat/agents 3.9.3 → 3.9.4

package/dist/types/openai/toolProjection.d.ts

@@ -0,0 +1,30 @@
+import type { OpenAIChatCompletionChunkChoice, OpenAIToolCall, OpenAIStreamTracker } from './index';
+import type { EventHandler } from '@/types';
+interface OpenAIToolCallStreamOptions {
+    /** Synchronous framing only. Async transport/backpressure is a separate boundary. */
+    emit?: (delta: OpenAIChatCompletionChunkChoice['delta']) => void;
+    signal?: AbortSignal;
+    /** Bound retained complete-before-publish output, not model execution. Default: 1024. */
+    maxToolCalls?: number;
+    /** UTF-8 bytes of serialized arguments, names and IDs retained across accepted responses. Default: 4 MiB. */
+    maxBufferedBytes?: number;
+}
+/** Streaming hosts share the finalizer's tracker; map-only hosts collect JSON output. */
+export type OpenAIToolCallStreamConfig = OpenAIToolCallStreamOptions & ({
+    tracker: OpenAIStreamTracker;
+    toolCalls?: never;
+    emit: NonNullable<OpenAIToolCallStreamOptions['emit']>;
+} | {
+    toolCalls: Map<number, OpenAIToolCall>;
+    tracker?: never;
+});
+export interface OpenAIToolCallStream {
+    /** Pass directly to Run.create({ customHandlers: stream.handlers }). */
+    handlers: Record<string, EventHandler>;
+    /** Publish only after the host verifies that the entire run completed successfully. */
+    finish: () => void;
+    abort: () => void;
+}
+/** Serializes finalized, accepted tool calls. No provider fragments or attempt inference. */
+export declare function createOpenAIToolCallStream(config: OpenAIToolCallStreamConfig): OpenAIToolCallStream;
+export {};

package/dist/types/run.d.ts

@@ -14,6 +14,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private langfuse?;
     private toolOutputReferences?;
     private eagerEventToolExecution?;
+    private clientDelegatedToolNames?;
     private codeSessionToolNames?;
     private interruptingToolNames?;
     private toolExecution?;

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

@@ -229,7 +229,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     private anonBatchCounter;
     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);
+    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, onToolCallsClaimed, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     private withToolScope;
     /**

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

@@ -4,8 +4,8 @@ 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 { RunStep, ModelResponseEvent, ModelToolsClaimedEvent, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, CompactionSemanticIndex, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
-import type { RunStep, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecutionConfig, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { SubagentTaskConfig } from '@/types/subagentTasks';
@@ -127,7 +127,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;
@@ -139,7 +139,7 @@ export interface FadingTier {
 /** Latched fading tiers keyed by agent ID. */
 export type FadingTiers = Record<string, FadingTier>;
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
+    handle(event: string, data: StreamEventData | ModelEndData | ModelResponseEvent | ModelToolsClaimedEvent | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -291,6 +291,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>;

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

@@ -260,6 +260,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/dist/types/types/stream.d.ts

@@ -1,4 +1,4 @@
-import type { MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessage } from '@langchain/core/messages';
+import type { AIMessageChunk, MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessage } from '@langchain/core/messages';
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { LLMResult, Generation } from '@langchain/core/outputs';
 import type { Command } from '@langchain/langgraph';
@@ -8,6 +8,21 @@ import type { AssistantTextPhase } from '@/types/assistantPhase';
 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, parentRunId?: string, tags?: string[]) => void;
 export type MetadataAggregatorResult = {
     handleLLMEnd: HandleLLMEnd;
@@ -442,3 +457,9 @@ 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/dist/types/types/tools.d.ts

@@ -293,6 +293,8 @@ export type ToolNodeOptions = {
     restoreRunStepResumeState?: (state?: RunStepResumeState, config?: RunnableConfig) => 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;
 export type ToolEndEvent = {

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

@@ -0,0 +1,10 @@
+/** Encode JSON data, not arbitrary JS values. No getters, proxies or toJSON hooks run.
+ * Repeated references expand like JSON (and count against the budget); cycles fail.
+ * Limits bound output and traversal, including deeply nested/alias-heavy input.
+ */
+export declare function serializeToolArguments(value: unknown, maxBytes: number): string;
+/** Detach JSON data without encoding it. Unlike projection, invocation has no
+ * formatting budget: preserve shared references and traverse iteratively so a
+ * deep or alias-heavy object cannot expand exponentially during validation.
+ */
+export declare function cloneToolArguments(value: unknown): Record<string, unknown>;

package/package.json

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

package/src/common/enum.ts

@@ -7,6 +7,11 @@
 export enum GraphEvents {
   /* Custom Events */
 
+  /** Accepted graph model result, after fallback selection. Registry-only, not a provider callback. */
+  ON_MODEL_RESPONSE = 'on_model_response',
+  /** Registry-only: ToolNode has taken ownership of an accepted message's calls. */
+  ON_MODEL_TOOLS_CLAIMED = 'on_model_tools_claimed',
+
   /** [Custom] Agent update event in multi-agent graph/workflow */
   ON_AGENT_UPDATE = 'on_agent_update',
   /** [Custom] Delta event for run steps (message creation and tool calls) */

package/src/events.ts

@@ -8,7 +8,7 @@ import type { Logger } from 'winston';
 import type { MultiAgentGraph, StandardGraph } from '@/graphs';
 import type * as t from '@/types';
 import { dispatchesChatModelStream, SDK_STREAM_DISPATCH } from '@/stream';
-import { Constants } from '@/common';
+import { Constants, GraphEvents } from '@/common';
 
 export class HandlerRegistry {
   private handlers: Map<string, t.EventHandler> = new Map();
@@ -26,12 +26,23 @@ export function composeEventHandlers(
   ...handlerSets: Array<Record<string, t.EventHandler> | undefined>
 ): Record<string, t.EventHandler> {
   const composed: Partial<Record<string, t.EventHandler>> = {};
+  const acceptedObservers = new Map<string, t.EventHandler[]>();
 
   for (const handlerSet of handlerSets) {
     if (!handlerSet) {
       continue;
     }
     for (const [eventType, handler] of Object.entries(handlerSet)) {
+      if (
+        eventType === GraphEvents.ON_MODEL_RESPONSE ||
+        eventType === GraphEvents.ON_MODEL_TOOLS_CLAIMED
+      ) {
+        const observers = acceptedObservers.get(eventType) ?? [];
+        observers.push(handler);
+        acceptedObservers.set(eventType, observers);
+        composed[eventType] = handler;
+        continue;
+      }
       const previous = composed[eventType];
       if (previous === undefined) {
         composed[eventType] = handler;
@@ -61,6 +72,18 @@ export function composeEventHandlers(
     }
   }
 
+  for (const [eventType, observers] of acceptedObservers) {
+    composed[eventType] = {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        // Clone from the graph-owned snapshot, not from any preceding observer's
+        // possibly mutated argument tree. One bounded copy per observer.
+        for (const observer of observers) {
+          await observer.handle(event, structuredClone(data), metadata, graph);
+        }
+      },
+    };
+  }
+
   return composed as Record<string, t.EventHandler>;
 }
 

package/src/graphs/Graph.ts

@@ -135,6 +135,10 @@ import {
   annotateMessagesForLLM,
   ToolOutputReferenceRegistry,
 } from '@/tools/toolOutputReferences';
+import {
+  InvalidModelToolCallError,
+  snapshotAcceptedModelResponse,
+} from './acceptedModelResponse';
 import {
   prepareProviderRequest,
   usesNativeOpenAIResponses,
@@ -831,6 +835,8 @@ export abstract class Graph<
   callerSignal?: AbortSignal;
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
+  /** Explicit host policy. Never inferred from missing ToolNode claims. */
+  clientDelegatedToolNames?: ReadonlySet<string>;
   handlerRegistry: HandlerRegistry | undefined;
   /** Host registry retained only for forwarding tools from nested child graphs. */
   protected parentToolHandlerRegistry: HandlerRegistry | undefined;
@@ -1543,6 +1549,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       preemption,
       streamLimits,
       toolExecution,
+      clientDelegatedToolNames,
     }: t.StandardGraphInput,
     dependencies?: GraphFactoryDependencies
   ) {
@@ -1570,6 +1577,15 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.preemption = preemption;
     this.streamLimits = resolveStreamLimits(streamLimits);
     this.toolExecution = toolExecution;
+    if (clientDelegatedToolNames != null && clientDelegatedToolNames.length > 0) {
+      if (agents.length !== 1) {
+        throw new Error('Client tool delegation requires a single-agent graph');
+      }
+      if (clientDelegatedToolNames.some((name) => !name.trim())) {
+        throw new Error('Client delegated tool names must be nonempty');
+      }
+      this.clientDelegatedToolNames = new Set(clientDelegatedToolNames);
+    }
 
     if (agents.length === 0) {
       throw new Error('At least one agent configuration is required');
@@ -2833,6 +2849,25 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     currentToolMap?: t.ToolMap;
     agentContext?: AgentContext;
   }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState> {
+    const onToolCallsClaimed = async (
+      messageId: string,
+      config: RunnableConfig
+    ): Promise<void> => {
+      const handler = this.handlerRegistry?.getHandler(
+        GraphEvents.ON_MODEL_TOOLS_CLAIMED
+      );
+      if (handler == null) return;
+      await handler.handle(
+        GraphEvents.ON_MODEL_TOOLS_CLAIMED,
+        {
+          type: 'model_tools_claimed',
+          agentId: agentContext?.agentId ?? this.defaultAgentId,
+          messageId,
+        },
+        config.metadata,
+        this
+      );
+    };
     const toolDefinitions = agentContext?.toolDefinitions;
     const eventDrivenMode =
       toolDefinitions != null && toolDefinitions.length > 0;
@@ -2920,6 +2955,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           this.config = config;
           this.restoreRunStepResumeState(state);
         },
+        onToolCallsClaimed,
         createRunStepResumeState: (): t.RunStepResumeState =>
           this.createRunStepResumeState(),
         errorHandler: (data, metadata): Promise<boolean> =>
@@ -3002,6 +3038,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         this.config = config;
         this.restoreRunStepResumeState(state);
       },
+      onToolCallsClaimed,
       createRunStepResumeState: (): t.RunStepResumeState =>
         this.createRunStepResumeState(),
     });
@@ -4363,6 +4400,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * succeeding fallback would resolve a run the public contract says
          * must reject. Rethrow before any recovery path.
          */
+        if (primaryError instanceof InvalidModelToolCallError) {
+          throw primaryError;
+        }
         if (
           primaryError instanceof StreamLimitExceededError ||
           primaryError instanceof PreparedSubagentError
@@ -4703,6 +4743,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               })
           );
         } catch (fallbackError) {
+          if (fallbackError instanceof InvalidModelToolCallError) {
+            throw fallbackError;
+          }
           if (
             fallbackError instanceof StreamLimitExceededError ||
             fallbackError instanceof PreparedSubagentError
@@ -5007,6 +5050,36 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         this.preemptIncomplete = true;
       }
 
+      const responseHandler = this.handlerRegistry?.getHandler(
+        GraphEvents.ON_MODEL_RESPONSE
+      );
+      if (responseHandler != null && responseMessage?.getType() === 'ai') {
+        try {
+          // One graph-owned accepted result after all primary/fallback/overflow paths.
+          // No inference from provider chunks, run-step IDs, or attempt callback metadata.
+          invokeConfig.signal?.throwIfAborted();
+          const accepted = snapshotAcceptedModelResponse(
+            responseMessage as AIMessageChunk,
+            v4(),
+            agentId,
+            this.invokedToolIds,
+            this.clientDelegatedToolNames
+          );
+          // Awaited, registry-only: no trace replay, usage recording or side effects.
+          // Detached calls prevent a consumer from changing tools about to execute.
+          await responseHandler.handle(
+            GraphEvents.ON_MODEL_RESPONSE,
+            accepted,
+            metadata,
+            this
+          );
+          invokeConfig.signal?.throwIfAborted();
+        } catch (error) {
+          this.cleanupSignalListener();
+          throw error;
+        }
+      }
+
       this.cleanupSignalListener();
       return result;
     };
@@ -5475,6 +5548,28 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (this.summarizeOnlyAgentId != null) {
         return END;
       }
+      const delegatedNames = this.clientDelegatedToolNames;
+      if (delegatedNames != null && delegatedNames.size > 0) {
+        const { messages } = state as t.BaseGraphState;
+        const last = messages[messages.length - 1] as AIMessageChunk | undefined;
+        const calls = last?.getType() === 'ai' ? last.tool_calls ?? [] : [];
+        if (calls.some((call) => delegatedNames.has(call.name))) {
+          if (
+            calls.some(
+              (call) =>
+                !delegatedNames.has(call.name) ||
+                (call.id != null && this.invokedToolIds?.has(call.id) === true)
+            ) ||
+            (last?.invalid_tool_calls?.length ?? 0) > 0 ||
+            getTruncationStopReason(last) != null
+          ) {
+            throw new InvalidModelToolCallError(
+              'Mixed client and graph-owned tool calls require separate model turns'
+            );
+          }
+          return END;
+        }
+      }
       const decision = toolsCondition(
         state as t.BaseGraphState,
         toolNode,