@librechat/agents 3.9.3 → 3.9.4

package/src/run.ts

@@ -468,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;
@@ -549,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;
@@ -573,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;
@@ -663,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 */
@@ -1058,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
@@ -1554,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);

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

@@ -1021,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,
@@ -1155,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);

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,
@@ -183,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;
@@ -202,6 +204,8 @@ export interface EventHandler {
     data:
       | StreamEventData
       | ModelEndData
+      | ModelResponseEvent
+      | ModelToolsClaimedEvent
       | RunStep
       | RunStepDeltaEvent
       | RunStepClosedEvent
@@ -406,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>;

package/src/types/run.ts

@@ -279,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

@@ -313,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;

package/src/utils/acceptedToolArguments.ts

@@ -0,0 +1,204 @@
+import { types } from 'node:util';
+
+const MAX_ARGUMENT_DEPTH = 64;
+const INVALID = 'Accepted tool call arguments are not JSON serializable';
+const LIMIT = 'Tool projection buffer limit exceeded';
+
+function invalid(): never {
+  throw new Error(INVALID);
+}
+
+/** structuredClone and VM providers may return objects from another realm. */
+function hasJSONPrototype(value: object, array: boolean): boolean {
+  const proto: unknown = Object.getPrototypeOf(value);
+  if (proto === null) return true;
+  if (typeof proto !== 'object' || types.isProxy(proto)) return false;
+  const ctor: unknown = Object.getOwnPropertyDescriptor(
+    proto,
+    'constructor'
+  )?.value;
+  if (typeof ctor !== 'function' || types.isProxy(ctor)) return false;
+  return (
+    Object.getOwnPropertyDescriptor(ctor, 'prototype')?.value === proto &&
+    Function.prototype.toString.call(ctor) ===
+      Function.prototype.toString.call(array ? Array : Object)
+  );
+}
+
+/** 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 function serializeToolArguments(
+  value: unknown,
+  maxBytes: number
+): string {
+  if (maxBytes < 2) throw new Error(LIMIT);
+  const parts: string[] = [];
+  const ancestors = new Set<object>();
+  let remaining = maxBytes;
+  const append = (text: string): void => {
+    remaining -= Buffer.byteLength(text, 'utf8');
+    if (remaining < 0) throw new Error(LIMIT);
+    parts.push(text);
+  };
+  const string = (text: string): void => {
+    // Every UTF-16 unit needs at least one encoded byte. Check before allocating escapes.
+    if (text.length + 2 > remaining) throw new Error(LIMIT);
+    append(JSON.stringify(text));
+  };
+  const encode = (input: unknown, depth: number): void => {
+    if (depth > MAX_ARGUMENT_DEPTH) invalid();
+    if (input === null) {
+      append('null');
+      return;
+    }
+    if (typeof input === 'string') {
+      string(input);
+      return;
+    }
+    if (typeof input === 'boolean') {
+      append(input ? 'true' : 'false');
+      return;
+    }
+    if (typeof input === 'number') {
+      if (!Number.isFinite(input)) invalid();
+      append(Object.is(input, -0) ? '-0' : String(input));
+      return;
+    }
+    if (typeof input !== 'object') invalid();
+    if (types.isProxy(input) || ancestors.has(input)) invalid();
+    const array = Array.isArray(input);
+    if (!hasJSONPrototype(input, array)) invalid();
+    const keys = Reflect.ownKeys(input);
+    // At least one byte per entry, plus punctuation. Bound descriptor work up front.
+    if (keys.length > remaining + (array ? 1 : 0)) throw new Error(LIMIT);
+    ancestors.add(input);
+    if (array) {
+      // Dense arrays only, with no symbols, hidden entries or extra named properties.
+      if (keys.length !== input.length + 1) invalid();
+      append('[');
+      for (let i = 0; i < input.length; i++) {
+        const descriptor = Object.getOwnPropertyDescriptor(input, String(i));
+        if (
+          descriptor == null ||
+          descriptor.enumerable !== true ||
+          !('value' in descriptor)
+        )
+          invalid();
+        if (i !== 0) append(',');
+        encode(descriptor.value, depth + 1);
+      }
+      append(']');
+    } else {
+      append('{');
+      for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        if (typeof key !== 'string') invalid();
+        const descriptor = Object.getOwnPropertyDescriptor(input, key);
+        if (
+          descriptor == null ||
+          descriptor.enumerable !== true ||
+          !('value' in descriptor)
+        )
+          invalid();
+        if (i !== 0) append(',');
+        string(key);
+        append(':');
+        encode(descriptor.value, depth + 1);
+      }
+      append('}');
+    }
+    ancestors.delete(input);
+  };
+  if (value != null && typeof value === 'object' && types.isProxy(value))
+    invalid();
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Accepted tool call arguments must be an object');
+  }
+  encode(value, 0);
+  return parts.join('');
+}
+
+/** 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 function cloneToolArguments(value: unknown): Record<string, unknown> {
+  const copies = new Map<object, object>();
+  const ancestors = new Set<object>();
+  const stack: Array<{
+    input: object;
+    output: object;
+    keys: (string | symbol)[];
+    index: number;
+  }> = [];
+  const copy = (input: unknown): unknown => {
+    if (
+      input === null ||
+      typeof input === 'string' ||
+      typeof input === 'boolean'
+    )
+      return input;
+    if (typeof input === 'number') {
+      if (!Number.isFinite(input)) invalid();
+      return input;
+    }
+    if (
+      typeof input !== 'object' ||
+      types.isProxy(input) ||
+      ancestors.has(input)
+    )
+      invalid();
+    const existing = copies.get(input);
+    if (existing != null) return existing;
+    const array = Array.isArray(input);
+    if (!hasJSONPrototype(input, array)) invalid();
+    const keys = Reflect.ownKeys(input);
+    if (array && keys.length !== input.length + 1) invalid();
+    const output: object = array ? [] : {};
+    copies.set(input, output);
+    ancestors.add(input);
+    stack.push({
+      input,
+      output,
+      keys: array ? keys.filter((key) => key !== 'length') : keys,
+      index: 0,
+    });
+    return output;
+  };
+  if (
+    value == null ||
+    typeof value !== 'object' ||
+    types.isProxy(value) ||
+    Array.isArray(value)
+  )
+    invalid();
+  const result = copy(value) as Record<string, unknown>;
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame.index === frame.keys.length) {
+      ancestors.delete(frame.input);
+      stack.pop();
+      continue;
+    }
+    const key = frame.keys[frame.index++];
+    if (typeof key !== 'string') invalid();
+    if (Array.isArray(frame.input) && key !== String(frame.index - 1))
+      invalid();
+    const descriptor = Object.getOwnPropertyDescriptor(frame.input, key);
+    if (
+      descriptor == null ||
+      !('value' in descriptor) ||
+      descriptor.enumerable !== true
+    )
+      invalid();
+    Object.defineProperty(frame.output, key, {
+      value: copy(descriptor.value),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return result;
+}