@librechat/agents 3.9.2 → 3.9.4

package/src/graphs/handoff.ts

@@ -0,0 +1,263 @@
+import { nanoid } from 'nanoid';
+import { Annotation, Command, Send } from '@langchain/langgraph';
+import type { BaseChannel, OverwriteValue } from '@langchain/langgraph';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type {
+  BaseGraphState,
+  HandoffOutcome,
+  HandoffState,
+  HandoffTransition,
+} from '@/types/graph';
+
+function isSupportedVersion(version: number): boolean {
+  return version === 1;
+}
+
+function isSend(value: string | Send): value is Send {
+  return typeof value !== 'string' && value.lg_name === 'Send';
+}
+
+export type HandoffRequest = Pick<
+  HandoffTransition,
+  'sourceAgentId' | 'targetAgentId' | 'toolCallId' | 'scope'
+>;
+
+type HandoffUpdate = Partial<BaseGraphState> & {
+  handoffRequest?: HandoffRequest;
+};
+
+function sameTransition(a: HandoffTransition, b: HandoffTransition): boolean {
+  return (
+    a.id === b.id &&
+    a.sourceAgentId === b.sourceAgentId &&
+    a.targetAgentId === b.targetAgentId &&
+    a.toolCallId === b.toolCallId &&
+    a.scope === b.scope &&
+    a.depth === b.depth
+  );
+}
+
+/** Union by identity makes checkpoint replay idempotent and parallel merges commutative. */
+export function mergeHandoffState(
+  current: HandoffState | undefined,
+  update: HandoffState | undefined
+): HandoffState | undefined {
+  if (update == null) return current;
+  if (current == null) return update;
+  if (current.executionId !== update.executionId) {
+    throw new Error('Cannot merge handoffs from different logical turns');
+  }
+  if (
+    current.entryAgentId !== update.entryAgentId ||
+    current.maxHandoffs !== update.maxHandoffs
+  ) {
+    throw new Error('Conflicting handoff checkpoint configuration');
+  }
+  const transitions = new Map(
+    current.transitions.map((item) => [item.id, item])
+  );
+  for (const transition of update.transitions) {
+    const existing = transitions.get(transition.id);
+    if (existing != null && !sameTransition(existing, transition)) {
+      throw new Error('Conflicting replayed handoff transition');
+    }
+    transitions.set(transition.id, transition);
+  }
+  return {
+    ...current,
+    parallel: current.parallel || update.parallel,
+    historyComplete:
+      current.historyComplete !== false && update.historyComplete !== false,
+    transitions: [...transitions.values()].sort(
+      (a, b) => a.depth - b.depth || a.id.localeCompare(b.id)
+    ),
+  };
+}
+
+export function handoffStateAnnotation(): BaseChannel<
+  HandoffState | undefined,
+  HandoffState | OverwriteValue<HandoffState | undefined> | undefined
+  > {
+  return Annotation<HandoffState | undefined>({
+    reducer: mergeHandoffState,
+    default: () => undefined,
+  });
+}
+
+export class HandoffLimitError extends Error {
+  constructor(readonly limit: number) {
+    super(`Agent handoff limit (${limit}) reached`);
+    this.name = 'HandoffLimitError';
+  }
+}
+
+/** One owner per graph, never shared with isolated child executions. */
+export class HandoffRouting {
+  private state: HandoffState;
+
+  constructor(
+    private readonly entryAgentId: string,
+    private readonly maxHandoffs: number | undefined,
+    private readonly parallel: boolean
+  ) {
+    this.state = this.freshState();
+  }
+
+  private freshState(): HandoffState {
+    return {
+      version: 1,
+      executionId: nanoid(),
+      entryAgentId: this.entryAgentId,
+      ...(this.maxHandoffs == null ? {} : { maxHandoffs: this.maxHandoffs }),
+      transitions: [],
+      parallel: this.parallel,
+    };
+  }
+
+  start(): HandoffState {
+    this.state = this.freshState();
+    return this.snapshot();
+  }
+
+  resume(state: HandoffState | undefined): void {
+    if (state != null) {
+      this.restore(state);
+      return;
+    }
+    if (this.maxHandoffs != null) {
+      throw new Error(
+        'Cannot enforce a handoff budget on a legacy checkpoint without routing state'
+      );
+    }
+    this.state = { ...this.state, historyComplete: false };
+  }
+
+  restore(state: HandoffState | undefined): void {
+    if (state == null) return;
+    if (!isSupportedVersion(state.version))
+      throw new Error('Unsupported handoff checkpoint version');
+    if (
+      state.entryAgentId !== this.entryAgentId ||
+      state.maxHandoffs !== this.maxHandoffs
+    ) {
+      throw new Error('Cannot resume with a different handoff entry or budget');
+    }
+    if (this.state.executionId !== state.executionId) {
+      if (this.state.transitions.length > 0) {
+        throw new Error('Cannot resume a different handoff execution');
+      }
+      this.state = {
+        ...state,
+        transitions: state.transitions.map((item) => ({ ...item })),
+      };
+      return;
+    }
+    this.state = mergeHandoffState(this.state, state)!;
+  }
+
+  snapshot(): HandoffState {
+    return {
+      ...this.state,
+      transitions: this.state.transitions.map((item) => ({ ...item })),
+    };
+  }
+
+  /** Called after tools settle but before Commands can schedule recipients. */
+  finalize(
+    commands: Command[],
+    input: BaseGraphState,
+    config: RunnableConfig
+  ): void {
+    this.restore(input.handoffState);
+    const updates: HandoffUpdate[] = [];
+    let parallel = this.state.parallel;
+    for (const command of commands) {
+      if (command.graph !== Command.PARENT) continue;
+      const sends = Array.isArray(command.goto)
+        ? command.goto.filter(isSend)
+        : [];
+      parallel ||= sends.length > 1;
+      if (sends.length > 0) {
+        for (const send of sends) updates.push(send.args as HandoffUpdate);
+      } else if (command.update != null) {
+        updates.push(command.update as HandoffUpdate);
+      }
+    }
+    const accepted = new Map(
+      this.state.transitions.map((item) => [item.id, item])
+    );
+    const requests = updates.filter((update) => update.handoffRequest != null);
+    if (requests.length === 0) return;
+    const depth =
+      input.handoffState?.transitions.length ?? this.state.transitions.length;
+    const lastMessage = input.messages.at(-1);
+    for (const update of requests) {
+      const request = update.handoffRequest!;
+      const id = JSON.stringify([
+        this.state.executionId,
+        config.configurable?.checkpoint_ns ?? '',
+        request.sourceAgentId,
+        lastMessage?.id ?? input.messages.length,
+        request.toolCallId,
+      ]);
+      const transition = { ...request, id, depth };
+      const existing = accepted.get(id);
+      if (
+        existing != null &&
+        (existing.targetAgentId !== transition.targetAgentId ||
+          existing.scope !== transition.scope)
+      )
+        throw new Error('Handoff replay changed its destination or scope');
+      accepted.set(id, existing ?? transition);
+    }
+    if (this.maxHandoffs != null && accepted.size > this.maxHandoffs) {
+      throw new HandoffLimitError(this.maxHandoffs);
+    }
+    this.state = {
+      ...this.state,
+      transitions: [...accepted.values()],
+      parallel,
+    };
+    for (const update of requests) delete update.handoffRequest;
+    for (const command of commands) {
+      if (command.graph !== Command.PARENT) continue;
+      command.update = {
+        ...(command.update as HandoffUpdate),
+        handoffState: this.snapshot(),
+      };
+      if (!Array.isArray(command.goto)) continue;
+      command.goto = command.goto.map((destination) =>
+        isSend(destination)
+          ? new Send(destination.node, {
+            ...destination.args,
+            handoffState: this.snapshot(),
+          })
+          : destination
+      );
+    }
+  }
+
+  outcome(reason?: string): HandoffOutcome {
+    const state = this.snapshot();
+    const base = {
+      executionId: state.executionId,
+      entryAgentId: state.entryAgentId,
+      transitions: state.transitions,
+    };
+    if (reason != null) return { ...base, status: 'incomplete', reason };
+    if (state.historyComplete === false)
+      return { ...base, status: 'incomplete', reason: 'legacy_checkpoint' };
+    const persistent = state.transitions.filter(
+      (item) => item.scope === 'conversation'
+    );
+    if (persistent.length === 0) return { ...base, status: 'unchanged' };
+    if (state.parallel) return { ...base, status: 'ambiguous' };
+    const last = persistent.reduce((a, b) => (a.depth > b.depth ? a : b));
+    return {
+      ...base,
+      status: 'candidate',
+      agentId: last.targetAgentId,
+      transitionId: last.id,
+    };
+  }
+}

package/src/graphs/index.ts

@@ -2,3 +2,5 @@ export * from './Graph';
 export * from './MultiAgentGraph';
 export * from './createGraph';
 export type * from './graphFactory';
+
+export { HandoffLimitError } from './handoff';

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