@librechat/agents 3.9.3 → 3.9.5

package/src/tools/ProgrammaticToolCalling.ts

@@ -22,7 +22,6 @@ import {
   resolveCodeApiAuthHeaders,
   selectRuntimeSessionHint,
 } from './CodeExecutor';
-import { appendExecutionArtifactFileSummary } from './CodeSessionFileSummary';
 import {
   assertUnambiguousIdentifiers,
   projectProgrammaticToolMap,
@@ -39,10 +38,15 @@ import {
   appendArtifactDeliveryWarning,
   normalizeArtifactDeliveryFailure,
 } from '@/tools/ArtifactDelivery';
+import {
+  appendArtifactTruncationWarning,
+  normalizeArtifactTruncation,
+} from '@/tools/ArtifactTruncation';
 import {
   describeCodeApiError,
   logCodeApiDiagnostic,
 } from '@/tools/diagnostics';
+import { appendExecutionArtifactFileSummary } from './CodeSessionFileSummary';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
@@ -946,11 +950,18 @@ export function formatCompletedResponse(
     outputWithReminder,
     artifactDelivery
   );
+  const artifactTruncation = normalizeArtifactTruncation(
+    response.artifact_truncation
+  );
+  const outputWithWarnings = appendArtifactTruncationWarning(
+    outputWithDeliveryWarning,
+    artifactTruncation
+  );
 
   return [
     filePersistence === 'execution'
-      ? appendExecutionArtifactFileSummary(outputWithDeliveryWarning, response.files)
-      : appendCodeSessionFileSummary(outputWithDeliveryWarning, response.files),
+      ? appendExecutionArtifactFileSummary(outputWithWarnings, response.files)
+      : appendCodeSessionFileSummary(outputWithWarnings, response.files),
     {
       session_id: response.session_id,
       files: response.files,
@@ -960,6 +971,9 @@ export function formatCompletedResponse(
       ...(artifactDelivery != null
         ? { artifact_delivery: artifactDelivery }
         : {}),
+      ...(artifactTruncation != null
+        ? { artifact_truncation: artifactTruncation }
+        : {}),
       ...(response.runtime_session_id != null
         ? {
           runtime_session_id: response.runtime_session_id,

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;
@@ -495,6 +497,21 @@ export type ArtifactDeliveryFailure = {
   failed: number;
 };
 
+export type ArtifactTruncationReason =
+  | 'max_files'
+  | 'depth'
+  | 'size'
+  | 'path'
+  | 'unreadable';
+
+export type ArtifactTruncation = {
+  code: 'artifact_truncated';
+  reasons: Partial<Record<ArtifactTruncationReason, number>>;
+  /** Up to 20 relative paths omitted from the response. */
+  skipped: string[];
+  skipped_count: number;
+};
+
 export type ExecuteResult = {
   /**
    * Execution session id — the (transient) sandbox run that produced
@@ -508,6 +525,7 @@ export type ExecuteResult = {
   /** Persisted input paths explicitly removed during this execution. */
   deleted_files?: string[];
   artifact_delivery?: ArtifactDeliveryFailure;
+  artifact_truncation?: ArtifactTruncation;
   /**
    * Durable runtime session id echoed by a stateful Code API backend
    * (hash of tenant+user+hint). Additive; absent on stateless servers.
@@ -1354,6 +1372,7 @@ export type ProgrammaticExecutionResponse = {
   /** Persisted input paths explicitly removed during this execution. */
   deleted_files?: string[];
   artifact_delivery?: ArtifactDeliveryFailure;
+  artifact_truncation?: ArtifactTruncation;
 
   /** Durable runtime session echo from a stateful backend (additive). */
   runtime_session_id?: string;
@@ -1373,6 +1392,7 @@ export type ProgrammaticExecutionArtifact = {
   /** Persisted input paths explicitly removed during this execution. */
   deleted_files?: string[];
   artifact_delivery?: ArtifactDeliveryFailure;
+  artifact_truncation?: ArtifactTruncation;
   /** Durable runtime session echo from a stateful backend (additive). */
   runtime_session_id?: string;
   runtime_status?: 'new' | 'reused';
@@ -1455,6 +1475,7 @@ export type CodeExecutionArtifact = {
   /** Persisted input paths explicitly removed during this execution. */
   deleted_files?: string[];
   artifact_delivery?: ArtifactDeliveryFailure;
+  artifact_truncation?: ArtifactTruncation;
   /** Durable runtime session echo from a stateful backend (additive). */
   runtime_session_id?: string;
   runtime_status?: 'new' | 'reused';

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