@librechat/agents 3.9.3 → 3.9.4

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

package/src/messages/fading.ts

@@ -4,7 +4,12 @@ import {
   calculateMaxToolResultChars,
 } from '@/utils/truncation';
 
-export const FADING_TIER_VERSION = 1;
+/**
+ * Version 2: exchange width counts only the current turn. Version 1 tiers may
+ * have latched on history whose steps storage had merged into one assistant
+ * message, so they are discarded and re-derived once.
+ */
+export const FADING_TIER_VERSION = 2;
 
 /** Context pressure at which observation masking activates. */
 export const PRESSURE_THRESHOLD_MASKING = 0.8;
@@ -34,7 +39,7 @@ export type FadingSignals = {
   /** (pruningBudget − instruction tokens) ÷ calibrationRatio, in raw token space. */
   effectiveRawTokens: number;
   summarizationEnabled: boolean;
-  /** Largest number of parallel calls observed in one assistant exchange. */
+  /** Largest number of parallel calls in one assistant exchange of the current turn. */
   toolExchangeWidth?: number;
   /** Recovery paths force at least this rung on the current window's ladder. */
   minRung?: number;
@@ -59,7 +64,10 @@ export function createFadingTier(window: number): FadingTier {
   return { v: FADING_TIER_VERSION, budgetTokens: window, masked: false };
 }
 
-export function isFadingTier(value: unknown): value is FadingTier {
+/** Tier version before exchange width became turn-scoped. */
+const LEGACY_FADING_TIER_VERSION = 1;
+
+function isFadingTierOfVersion(value: unknown, version: number): boolean {
   if (typeof value !== 'object' || value === null) {
     return false;
   }
@@ -67,7 +75,7 @@ export function isFadingTier(value: unknown): value is FadingTier {
     Record<keyof FadingTier, unknown>
   >;
   return (
-    v === FADING_TIER_VERSION &&
+    v === version &&
     typeof budgetTokens === 'number' &&
     Number.isFinite(budgetTokens) &&
     budgetTokens > 0 &&
@@ -76,6 +84,20 @@ export function isFadingTier(value: unknown): value is FadingTier {
   );
 }
 
+export function isFadingTier(value: unknown): value is FadingTier {
+  return isFadingTierOfVersion(value, FADING_TIER_VERSION);
+}
+
+/**
+ * A well-formed tier persisted before version 2. Stored snapshots that carry
+ * one (resume manifests, session files) stay valid; every consumer then drops
+ * it through `isFadingTier`, so the tier re-derives once instead of the
+ * snapshot being rejected as corrupt.
+ */
+export function isLegacyFadingTier(value: unknown): boolean {
+  return isFadingTierOfVersion(value, LEGACY_FADING_TIER_VERSION);
+}
+
 /** Deepest rung for a window: the point where the budget reaches its floor. */
 export function maxFadingRung(window: number): number {
   const floor = floorBudgetTokens(window);
@@ -199,7 +221,10 @@ export function fadingRungForExchangeChars(
       maxToolResultChars == null
         ? windowResultChars
         : Math.min(windowResultChars, maxToolResultChars);
-    if (resultChars + calculateMaxToolCallInputChars(budgetTokens) <= targetChars) {
+    if (
+      resultChars + calculateMaxToolCallInputChars(budgetTokens) <=
+      targetChars
+    ) {
       return rung;
     }
   }