@librechat/agents 3.9.3 → 3.9.5

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,

package/src/graphs/acceptedModelResponse.ts

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

package/src/llm/invoke.ts

@@ -41,6 +41,11 @@ import {
   resolvePreemptAction,
   resolveRestartGraceMs,
 } from '@/llm/preempt';
+import {
+  detachValidatedModelToolCalls,
+  snapshotValidatedModelChunk,
+  InvalidModelToolCallError,
+} from '@/graphs/acceptedModelResponse';
 import {
   assertPreparedProviderRequestFor,
   prepareProviderRequest,
@@ -1079,7 +1084,8 @@ async function attemptInvokeBody(
       const signal = config.signal;
       if (
         signal?.aborted === true &&
-        (signal.reason instanceof StreamLimitExceededError || signal.reason instanceof PreparedSubagentError)
+        (signal.reason instanceof StreamLimitExceededError ||
+          signal.reason instanceof PreparedSubagentError)
       ) {
         throw signal.reason;
       }
@@ -1105,8 +1111,9 @@ async function attemptInvokeBody(
           const attemptMetadata = config.metadata as
             | Record<string, unknown>
             | undefined;
-          for await (const chunk of stream) {
+          for await (const rawChunk of stream) {
             throwIfBreakerTripped();
+            const chunk = snapshotValidatedModelChunk(rawChunk);
             /** An onChunk consumer replaces the stream handler entirely, so
              * stream limits are enforced here for every such caller — public
              * package consumers get no other accounting. The internal
@@ -1127,10 +1134,13 @@ async function attemptInvokeBody(
             });
           }
         } else if (registeredStreamHandler == null) {
-          const metadata = config.metadata as Record<string, unknown> | undefined;
+          const metadata = config.metadata as
+            | Record<string, unknown>
+            | undefined;
           const streamHandler = new ChatModelStreamHandler();
-          for await (const chunk of stream) {
+          for await (const rawChunk of stream) {
             throwIfBreakerTripped();
+            const chunk = snapshotValidatedModelChunk(rawChunk);
             /**
              * The decision is final, so stop consuming here rather than
              * trusting the adapter to honor the abort. An adapter that ignores
@@ -1239,7 +1249,9 @@ async function attemptInvokeBody(
             }
           }
         } else {
-          const metadata = config.metadata as Record<string, unknown> | undefined;
+          const metadata = config.metadata as
+            | Record<string, unknown>
+            | undefined;
           /**
            * The original wire chunk still reaches the registered handler through
            * `streamEvents` (where the late-reasoning skip discards it AFTER the
@@ -1248,8 +1260,9 @@ async function attemptInvokeBody(
            * once per attempt, only when a transformation occurs.
            */
           let redispatchMetadata: Record<string, unknown> | undefined;
-          for await (const chunk of stream) {
+          for await (const rawChunk of stream) {
             throwIfBreakerTripped();
+            const chunk = snapshotValidatedModelChunk(rawChunk);
             /**
              * Charged synchronously, ahead of the decoupled `streamEvents`
              * reader that will echo this same chunk to the registered handler:
@@ -1258,7 +1271,11 @@ async function attemptInvokeBody(
              * throws. The chunk is marked so the echo skips accounting.
              */
             if (context != null) {
-              enforceStreamLimitsForWireChunk({ graph: context, metadata, chunk });
+              enforceStreamLimitsForWireChunk({
+                graph: context,
+                metadata,
+                chunk,
+              });
             }
             const handlingChunk = getStreamHandlingChunk({
               current: finalChunk,
@@ -1366,7 +1383,8 @@ async function attemptInvokeBody(
         );
       }
       if (finalChunk != null || sealedRunId != null) {
-        const discardedChunk = finalChunk ?? new AIMessageChunk({ content: '' });
+        const discardedChunk =
+          finalChunk ?? new AIMessageChunk({ content: '' });
         const responseMetadata = {
           ...discardedChunk.response_metadata,
           preempted: true,
@@ -1448,6 +1466,7 @@ async function attemptInvokeBody(
       );
     }
 
+    if (finalChunk != null) detachValidatedModelToolCalls(finalChunk);
     if ((finalChunk?.tool_calls?.length ?? 0) > 0) {
       finalChunk!.tool_calls = finalChunk!.tool_calls?.filter(
         (tool_call: ToolCall) => !!tool_call.name
@@ -1458,9 +1477,9 @@ async function attemptInvokeBody(
     return { messages: [finalChunk as AIMessageChunk] };
   }
 
-  const finalMessage = await model.invoke(
-    messagesForProvider,
-    invocationConfig
+  const finalMessage = snapshotValidatedModelChunk(
+    await model.invoke(messagesForProvider, invocationConfig),
+    false
   );
   if ((finalMessage.tool_calls?.length ?? 0) > 0) {
     finalMessage.tool_calls = finalMessage.tool_calls?.filter(
@@ -1666,7 +1685,8 @@ export async function tryFallbackProviders({
        * a run that must reject. Check before every fallback invocation. */
       if (
         config?.signal?.aborted === true &&
-        (config.signal.reason instanceof StreamLimitExceededError || config.signal.reason instanceof PreparedSubagentError)
+        (config.signal.reason instanceof StreamLimitExceededError ||
+          config.signal.reason instanceof PreparedSubagentError)
       ) {
         throw config.signal.reason;
       }
@@ -1700,7 +1720,11 @@ export async function tryFallbackProviders({
        * provider failure. Continuing would try the remaining fallbacks and a
        * succeeding one would resolve a run that must reject.
        */
-      if (e instanceof StreamLimitExceededError || e instanceof PreparedSubagentError) {
+      if (
+        e instanceof StreamLimitExceededError ||
+        e instanceof PreparedSubagentError ||
+        e instanceof InvalidModelToolCallError
+      ) {
         throw e;
       }
       /** A parallel sibling's trip aborts this branch's composed signal, and
@@ -1709,7 +1733,8 @@ export async function tryFallbackProviders({
        * abort. Rethrow the breaker's own reason instead. */
       if (
         config?.signal?.aborted === true &&
-        (config.signal.reason instanceof StreamLimitExceededError || config.signal.reason instanceof PreparedSubagentError)
+        (config.signal.reason instanceof StreamLimitExceededError ||
+          config.signal.reason instanceof PreparedSubagentError)
       ) {
         throw config.signal.reason;
       }

package/src/llm/streamLimits.ts

@@ -981,7 +981,7 @@ export function linkStreamLimitCanonical(
   canonical: object
 ): void {
   Object.defineProperty(copy, STREAM_LIMIT_CANONICAL, {
-    value: canonical,
+    value: canonicalChunk(canonical),
     enumerable: false,
     configurable: true,
   });