@librechat/agents 3.9.3 → 3.9.5

package/dist/esm/utils/acceptedToolArguments.mjs

@@ -0,0 +1,142 @@
+import { types } from "node:util";
+//#region src/utils/acceptedToolArguments.ts
+const MAX_ARGUMENT_DEPTH = 64;
+const INVALID = "Accepted tool call arguments are not JSON serializable";
+const LIMIT = "Tool projection buffer limit exceeded";
+function invalid() {
+	throw new Error(INVALID);
+}
+function hasJSONPrototype(value, array) {
+	const proto = Object.getPrototypeOf(value);
+	if (proto === null) return true;
+	if (typeof proto !== "object" || types.isProxy(proto)) return false;
+	const ctor = 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);
+}
+function serializeToolArguments(value, maxBytes) {
+	if (maxBytes < 2) throw new Error(LIMIT);
+	const parts = [];
+	const ancestors = /* @__PURE__ */ new Set();
+	let remaining = maxBytes;
+	const append = (text) => {
+		remaining -= Buffer.byteLength(text, "utf8");
+		if (remaining < 0) throw new Error(LIMIT);
+		parts.push(text);
+	};
+	const string = (text) => {
+		if (text.length + 2 > remaining) throw new Error(LIMIT);
+		append(JSON.stringify(text));
+	};
+	const encode = (input, depth) => {
+		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);
+		if (keys.length > remaining + (array ? 1 : 0)) throw new Error(LIMIT);
+		ancestors.add(input);
+		if (array) {
+			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("");
+}
+function cloneToolArguments(value) {
+	const copies = /* @__PURE__ */ new Map();
+	const ancestors = /* @__PURE__ */ new Set();
+	const stack = [];
+	const copy = (input) => {
+		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 = 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);
+	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;
+}
+//#endregion
+export { cloneToolArguments, serializeToolArguments };
+
+//# sourceMappingURL=acceptedToolArguments.mjs.map

package/dist/esm/utils/acceptedToolArguments.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptedToolArguments.mjs","names":[],"sources":["../../../src/utils/acceptedToolArguments.ts"],"mappings":";;AAEA,MAAM,qBAAqB;AAC3B,MAAM,UAAU;AAChB,MAAM,QAAQ;AAEd,SAAS,UAAiB;CACxB,MAAM,IAAI,MAAM,OAAO;AACzB;AAGA,SAAS,iBAAiB,OAAe,OAAyB;CAChE,MAAM,QAAiB,OAAO,eAAe,KAAK;CAClD,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GAAG,OAAO;CAC9D,MAAM,OAAgB,OAAO,yBAC3B,OACA,aACF,CAAC,EAAE;CACH,IAAI,OAAO,SAAS,cAAc,MAAM,QAAQ,IAAI,GAAG,OAAO;CAC9D,OACE,OAAO,yBAAyB,MAAM,WAAW,CAAC,EAAE,UAAU,SAC9D,SAAS,UAAU,SAAS,KAAK,IAAI,MACnC,SAAS,UAAU,SAAS,KAAK,QAAQ,QAAQ,MAAM;AAE7D;AAMA,SAAgB,uBACd,OACA,UACQ;CACR,IAAI,WAAW,GAAG,MAAM,IAAI,MAAM,KAAK;CACvC,MAAM,QAAkB,CAAC;CACzB,MAAM,4BAAY,IAAI,IAAY;CAClC,IAAI,YAAY;CAChB,MAAM,UAAU,SAAuB;EACrC,aAAa,OAAO,WAAW,MAAM,MAAM;EAC3C,IAAI,YAAY,GAAG,MAAM,IAAI,MAAM,KAAK;EACxC,MAAM,KAAK,IAAI;CACjB;CACA,MAAM,UAAU,SAAuB;EAErC,IAAI,KAAK,SAAS,IAAI,WAAW,MAAM,IAAI,MAAM,KAAK;EACtD,OAAO,KAAK,UAAU,IAAI,CAAC;CAC7B;CACA,MAAM,UAAU,OAAgB,UAAwB;EACtD,IAAI,QAAQ,oBAAoB,QAAQ;EACxC,IAAI,UAAU,MAAM;GAClB,OAAO,MAAM;GACb;EACF;EACA,IAAI,OAAO,UAAU,UAAU;GAC7B,OAAO,KAAK;GACZ;EACF;EACA,IAAI,OAAO,UAAU,WAAW;GAC9B,OAAO,QAAQ,SAAS,OAAO;GAC/B;EACF;EACA,IAAI,OAAO,UAAU,UAAU;GAC7B,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,QAAQ;GACrC,OAAO,OAAO,GAAG,OAAO,EAAE,IAAI,OAAO,OAAO,KAAK,CAAC;GAClD;EACF;EACA,IAAI,OAAO,UAAU,UAAU,QAAQ;EACvC,IAAI,MAAM,QAAQ,KAAK,KAAK,UAAU,IAAI,KAAK,GAAG,QAAQ;EAC1D,MAAM,QAAQ,MAAM,QAAQ,KAAK;EACjC,IAAI,CAAC,iBAAiB,OAAO,KAAK,GAAG,QAAQ;EAC7C,MAAM,OAAO,QAAQ,QAAQ,KAAK;EAElC,IAAI,KAAK,SAAS,aAAa,QAAQ,IAAI,IAAI,MAAM,IAAI,MAAM,KAAK;EACpE,UAAU,IAAI,KAAK;EACnB,IAAI,OAAO;GAET,IAAI,KAAK,WAAW,MAAM,SAAS,GAAG,QAAQ;GAC9C,OAAO,GAAG;GACV,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;IACrC,MAAM,aAAa,OAAO,yBAAyB,OAAO,OAAO,CAAC,CAAC;IACnE,IACE,cAAc,QACd,WAAW,eAAe,QAC1B,EAAE,WAAW,aAEb,QAAQ;IACV,IAAI,MAAM,GAAG,OAAO,GAAG;IACvB,OAAO,WAAW,OAAO,QAAQ,CAAC;GACpC;GACA,OAAO,GAAG;EACZ,OAAO;GACL,OAAO,GAAG;GACV,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;IACpC,MAAM,MAAM,KAAK;IACjB,IAAI,OAAO,QAAQ,UAAU,QAAQ;IACrC,MAAM,aAAa,OAAO,yBAAyB,OAAO,GAAG;IAC7D,IACE,cAAc,QACd,WAAW,eAAe,QAC1B,EAAE,WAAW,aAEb,QAAQ;IACV,IAAI,MAAM,GAAG,OAAO,GAAG;IACvB,OAAO,GAAG;IACV,OAAO,GAAG;IACV,OAAO,WAAW,OAAO,QAAQ,CAAC;GACpC;GACA,OAAO,GAAG;EACZ;EACA,UAAU,OAAO,KAAK;CACxB;CACA,IAAI,SAAS,QAAQ,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GACnE,QAAQ;CACV,IAAI,SAAS,QAAQ,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GACnE,MAAM,IAAI,MAAM,gDAAgD;CAElE,OAAO,OAAO,CAAC;CACf,OAAO,MAAM,KAAK,EAAE;AACtB;AAMA,SAAgB,mBAAmB,OAAyC;CAC1E,MAAM,yBAAS,IAAI,IAAoB;CACvC,MAAM,4BAAY,IAAI,IAAY;CAClC,MAAM,QAKD,CAAC;CACN,MAAM,QAAQ,UAA4B;EACxC,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAO,UAAU,WAEjB,OAAO;EACT,IAAI,OAAO,UAAU,UAAU;GAC7B,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,QAAQ;GACrC,OAAO;EACT;EACA,IACE,OAAO,UAAU,YACjB,MAAM,QAAQ,KAAK,KACnB,UAAU,IAAI,KAAK,GAEnB,QAAQ;EACV,MAAM,WAAW,OAAO,IAAI,KAAK;EACjC,IAAI,YAAY,MAAM,OAAO;EAC7B,MAAM,QAAQ,MAAM,QAAQ,KAAK;EACjC,IAAI,CAAC,iBAAiB,OAAO,KAAK,GAAG,QAAQ;EAC7C,MAAM,OAAO,QAAQ,QAAQ,KAAK;EAClC,IAAI,SAAS,KAAK,WAAW,MAAM,SAAS,GAAG,QAAQ;EACvD,MAAM,SAAiB,QAAQ,CAAC,IAAI,CAAC;EACrC,OAAO,IAAI,OAAO,MAAM;EACxB,UAAU,IAAI,KAAK;EACnB,MAAM,KAAK;GACT;GACA;GACA,MAAM,QAAQ,KAAK,QAAQ,QAAQ,QAAQ,QAAQ,IAAI;GACvD,OAAO;EACT,CAAC;EACD,OAAO;CACT;CACA,IACE,SAAS,QACT,OAAO,UAAU,YACjB,MAAM,QAAQ,KAAK,KACnB,MAAM,QAAQ,KAAK,GAEnB,QAAQ;CACV,MAAM,SAAS,KAAK,KAAK;CACzB,OAAO,MAAM,SAAS,GAAG;EACvB,MAAM,QAAQ,MAAM,MAAM,SAAS;EACnC,IAAI,MAAM,UAAU,MAAM,KAAK,QAAQ;GACrC,UAAU,OAAO,MAAM,KAAK;GAC5B,MAAM,IAAI;GACV;EACF;EACA,MAAM,MAAM,MAAM,KAAK,MAAM;EAC7B,IAAI,OAAO,QAAQ,UAAU,QAAQ;EACrC,IAAI,MAAM,QAAQ,MAAM,KAAK,KAAK,QAAQ,OAAO,MAAM,QAAQ,CAAC,GAC9D,QAAQ;EACV,MAAM,aAAa,OAAO,yBAAyB,MAAM,OAAO,GAAG;EACnE,IACE,cAAc,QACd,EAAE,WAAW,eACb,WAAW,eAAe,MAE1B,QAAQ;EACV,OAAO,eAAe,MAAM,QAAQ,KAAK;GACvC,OAAO,KAAK,WAAW,KAAK;GAC5B,YAAY;GACZ,UAAU;GACV,cAAc;EAChB,CAAC;CACH;CACA,OAAO;AACT"}

package/dist/types/common/enum.d.ts

@@ -5,6 +5,10 @@
  * @enum {string}
  */
 export declare enum GraphEvents {
+    /** Accepted graph model result, after fallback selection. Registry-only, not a provider callback. */
+    ON_MODEL_RESPONSE = "on_model_response",
+    /** Registry-only: ToolNode has taken ownership of an accepted message's calls. */
+    ON_MODEL_TOOLS_CLAIMED = "on_model_tools_claimed",
     /** [Custom] Agent update event in multi-agent graph/workflow */
     ON_AGENT_UPDATE = "on_agent_update",
     /** [Custom] Delta event for run steps (message creation and tool calls) */

package/dist/types/graphs/Graph.d.ts

@@ -92,6 +92,8 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     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;
@@ -439,7 +441,7 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * from a discard.
      */
     private preemptRestartPending;
-    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, fadingTier, fadingTiers, subagentUsageSink, subagentTasks, subagentScope, subagentExecutionContext, subagentContext, preemption, streamLimits, toolExecution, }: t.StandardGraphInput, dependencies?: GraphFactoryDependencies);
+    constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, fadingTier, fadingTiers, subagentUsageSink, subagentTasks, subagentScope, subagentExecutionContext, subagentContext, preemption, streamLimits, toolExecution, clientDelegatedToolNames, }: t.StandardGraphInput, dependencies?: GraphFactoryDependencies);
     /**
      * A compaction applies its remove-all inside the agent subgraph, so the
      * subgraph's result carries only the retained tail, and an outer reducer

package/dist/types/graphs/acceptedModelResponse.d.ts

@@ -0,0 +1,15 @@
+import type { AIMessageChunk } from '@langchain/core/messages';
+import type { ModelResponseEvent } from '@/types';
+export declare class InvalidModelToolCallError extends Error {
+    constructor(message: string);
+}
+/** Detach executable calls before dispatch. Invalid diagnostics remain available
+ * for ToolNode to synthesize paired error results; accepted projection rejects them.
+ */
+export declare function detachValidatedModelToolCalls(message: AIMessageChunk, partial?: boolean): void;
+/** Only the accepted final response becomes a host-visible model result. */
+export declare function snapshotAcceptedModelResponse(finalResponse: AIMessageChunk, id: string, agentId: string, providerExecutedIds?: ReadonlySet<string>, clientDelegatedToolNames?: ReadonlySet<string>): ModelResponseEvent;
+/** Providers can mutate and re-yield records. Inspect a per-emission snapshot,
+ * leaving their originals intact, but keep producer/consumer charge identity.
+ */
+export declare function snapshotValidatedModelChunk(message: AIMessageChunk, partial?: boolean): AIMessageChunk;

package/dist/types/messages/fading.d.ts

@@ -1,5 +1,10 @@
 import type { FadingTier } from '@/types/graph';
-export declare 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 declare const FADING_TIER_VERSION = 2;
 /** Context pressure at which observation masking activates. */
 export declare const PRESSURE_THRESHOLD_MASKING = 0.8;
 /** Smallest token budget the ladder can shrink to; keeps the emergency floor near 200 chars. */
@@ -12,7 +17,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;
@@ -29,6 +34,13 @@ export type FadingCaps = {
 /** Tier for a conversation that has never faded: the whole window, nothing masked. */
 export declare function createFadingTier(window: number): FadingTier;
 export declare function isFadingTier(value: unknown): value is FadingTier;
+/**
+ * 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 declare function isLegacyFadingTier(value: unknown): boolean;
 /** Deepest rung for a window: the point where the budget reaches its floor. */
 export declare function maxFadingRung(window: number): number;
 /** Token budget at a rung: the window halved per rung, never below the floor. */

package/dist/types/messages/prune.d.ts

@@ -250,6 +250,13 @@ export declare function preFlightTruncateToolResults(params: {
     indexTokenCountMap: Record<string, number | undefined>;
     tokenCounter: TokenCounter;
 }): number;
+/**
+ * Leads every shortened tool-call input. Fading only shortens calls already in
+ * history, which ran with their full input; a model that reads a shortened copy
+ * as a call that was cut off re-issues it, and a side-effecting tool (sending an
+ * email) then runs again. The note says what actually happened.
+ */
+export declare const TOOL_INPUT_ELISION_NOTE = "Completed call; input shortened to save context.";
 /**
  * Serializes one structured tool-call input as valid, bounded JSON without
  * invoking user-defined accessors or `toJSON`.

package/dist/types/openai/arguments.d.ts

@@ -0,0 +1,2 @@
+/** OpenAI-only compatibility import; validation belongs to the graph-safe utility. */
+export { serializeToolArguments } from '@/utils/acceptedToolArguments';

package/dist/types/openai/index.d.ts

@@ -73,3 +73,5 @@ export declare function createChatCompletionUsageChunk(context: OpenAIResponseCo
 export declare function writeOpenAISSE(writer: OpenAICompatibleWriter, data: OpenAIChatCompletionChunk | '[DONE]'): Promise<void>;
 export declare function createOpenAIHandlers(config: OpenAIHandlerConfig): Record<string, t.EventHandler>;
 export declare function sendOpenAIFinalChunk(config: OpenAIHandlerConfig, finishReason?: OpenAIChatCompletionChunkChoice['finish_reason']): Promise<void>;
+export { createOpenAIToolCallStream } from './toolProjection';
+export type { OpenAIToolCallStream, OpenAIToolCallStreamConfig, } from './toolProjection';

package/dist/types/openai/toolProjection.d.ts

@@ -0,0 +1,30 @@
+import type { OpenAIChatCompletionChunkChoice, OpenAIToolCall, OpenAIStreamTracker } from './index';
+import type { EventHandler } from '@/types';
+interface OpenAIToolCallStreamOptions {
+    /** Synchronous framing only. Async transport/backpressure is a separate boundary. */
+    emit?: (delta: OpenAIChatCompletionChunkChoice['delta']) => void;
+    signal?: AbortSignal;
+    /** Bound retained complete-before-publish output, not model execution. Default: 1024. */
+    maxToolCalls?: number;
+    /** UTF-8 bytes of serialized arguments, names and IDs retained across accepted responses. Default: 4 MiB. */
+    maxBufferedBytes?: number;
+}
+/** Streaming hosts share the finalizer's tracker; map-only hosts collect JSON output. */
+export type OpenAIToolCallStreamConfig = OpenAIToolCallStreamOptions & ({
+    tracker: OpenAIStreamTracker;
+    toolCalls?: never;
+    emit: NonNullable<OpenAIToolCallStreamOptions['emit']>;
+} | {
+    toolCalls: Map<number, OpenAIToolCall>;
+    tracker?: never;
+});
+export interface OpenAIToolCallStream {
+    /** Pass directly to Run.create({ customHandlers: stream.handlers }). */
+    handlers: Record<string, EventHandler>;
+    /** Publish only after the host verifies that the entire run completed successfully. */
+    finish: () => void;
+    abort: () => void;
+}
+/** Serializes finalized, accepted tool calls. No provider fragments or attempt inference. */
+export declare function createOpenAIToolCallStream(config: OpenAIToolCallStreamConfig): OpenAIToolCallStream;
+export {};

package/dist/types/run.d.ts

@@ -14,6 +14,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private langfuse?;
     private toolOutputReferences?;
     private eagerEventToolExecution?;
+    private clientDelegatedToolNames?;
     private codeSessionToolNames?;
     private interruptingToolNames?;
     private toolExecution?;

package/dist/types/tools/ArtifactTruncation.d.ts

@@ -0,0 +1,3 @@
+import type { ArtifactTruncation } from '@/types';
+export declare function normalizeArtifactTruncation(value: unknown): ArtifactTruncation | undefined;
+export declare function appendArtifactTruncationWarning(output: string, truncation: ArtifactTruncation | undefined): string;

package/dist/types/tools/ToolNode.d.ts

@@ -229,7 +229,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      */
     private anonBatchCounter;
     private handoffRouting?;
-    constructor({ handoffRouting, tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, toolDefinitions, getDiscoveredToolNames, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, executionContext, executingAgentName, rootAgentId, rootAgentName, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, preparedSubagents, restoreRunStepResumeState, createRunStepResumeState, }: t.ToolNodeConstructorParams);
+    constructor({ handoffRouting, tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, toolDefinitions, getDiscoveredToolNames, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, executionContext, executingAgentName, rootAgentId, rootAgentName, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, preparedSubagents, restoreRunStepResumeState, createRunStepResumeState, onToolCallsClaimed, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     private withToolScope;
     /**

package/dist/types/types/graph.d.ts

@@ -4,8 +4,8 @@ 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 { RunStep, ModelResponseEvent, ModelToolsClaimedEvent, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, CompactionSemanticIndex, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
-import type { RunStep, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecutionConfig, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { SubagentTaskConfig } from '@/types/subagentTasks';
@@ -127,7 +127,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;
@@ -139,7 +139,7 @@ export interface FadingTier {
 /** Latched fading tiers keyed by agent ID. */
 export type FadingTiers = Record<string, FadingTier>;
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
+    handle(event: string, data: StreamEventData | ModelEndData | ModelResponseEvent | ModelToolsClaimedEvent | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -291,6 +291,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/dist/types/types/run.d.ts

@@ -260,6 +260,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/dist/types/types/stream.d.ts

@@ -1,4 +1,4 @@
-import type { MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessage } from '@langchain/core/messages';
+import type { AIMessageChunk, MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessage } from '@langchain/core/messages';
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { LLMResult, Generation } from '@langchain/core/outputs';
 import type { Command } from '@langchain/langgraph';
@@ -8,6 +8,21 @@ import type { AssistantTextPhase } from '@/types/assistantPhase';
 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, parentRunId?: string, tags?: string[]) => void;
 export type MetadataAggregatorResult = {
     handleLLMEnd: HandleLLMEnd;
@@ -442,3 +457,9 @@ 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/dist/types/types/tools.d.ts

@@ -293,6 +293,8 @@ export type ToolNodeOptions = {
     restoreRunStepResumeState?: (state?: RunStepResumeState, config?: RunnableConfig) => 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;
 export type ToolEndEvent = {
@@ -462,6 +464,14 @@ export type ArtifactDeliveryFailure = {
     delivered: number;
     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
@@ -475,6 +485,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.
@@ -1243,6 +1254,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;
     runtime_status?: 'new' | 'reused';
@@ -1259,6 +1271,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';
@@ -1326,6 +1339,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/dist/types/utils/acceptedToolArguments.d.ts

@@ -0,0 +1,10 @@
+/** 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 declare function serializeToolArguments(value: unknown, maxBytes: number): string;
+/** 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 declare function cloneToolArguments(value: unknown): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.9.3",
+  "version": "3.9.5",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/common/enum.ts

@@ -7,6 +7,11 @@
 export enum GraphEvents {
   /* Custom Events */
 
+  /** Accepted graph model result, after fallback selection. Registry-only, not a provider callback. */
+  ON_MODEL_RESPONSE = 'on_model_response',
+  /** Registry-only: ToolNode has taken ownership of an accepted message's calls. */
+  ON_MODEL_TOOLS_CLAIMED = 'on_model_tools_claimed',
+
   /** [Custom] Agent update event in multi-agent graph/workflow */
   ON_AGENT_UPDATE = 'on_agent_update',
   /** [Custom] Delta event for run steps (message creation and tool calls) */

package/src/events.ts

@@ -8,7 +8,7 @@ import type { Logger } from 'winston';
 import type { MultiAgentGraph, StandardGraph } from '@/graphs';
 import type * as t from '@/types';
 import { dispatchesChatModelStream, SDK_STREAM_DISPATCH } from '@/stream';
-import { Constants } from '@/common';
+import { Constants, GraphEvents } from '@/common';
 
 export class HandlerRegistry {
   private handlers: Map<string, t.EventHandler> = new Map();
@@ -26,12 +26,23 @@ export function composeEventHandlers(
   ...handlerSets: Array<Record<string, t.EventHandler> | undefined>
 ): Record<string, t.EventHandler> {
   const composed: Partial<Record<string, t.EventHandler>> = {};
+  const acceptedObservers = new Map<string, t.EventHandler[]>();
 
   for (const handlerSet of handlerSets) {
     if (!handlerSet) {
       continue;
     }
     for (const [eventType, handler] of Object.entries(handlerSet)) {
+      if (
+        eventType === GraphEvents.ON_MODEL_RESPONSE ||
+        eventType === GraphEvents.ON_MODEL_TOOLS_CLAIMED
+      ) {
+        const observers = acceptedObservers.get(eventType) ?? [];
+        observers.push(handler);
+        acceptedObservers.set(eventType, observers);
+        composed[eventType] = handler;
+        continue;
+      }
       const previous = composed[eventType];
       if (previous === undefined) {
         composed[eventType] = handler;
@@ -61,6 +72,18 @@ export function composeEventHandlers(
     }
   }
 
+  for (const [eventType, observers] of acceptedObservers) {
+    composed[eventType] = {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        // Clone from the graph-owned snapshot, not from any preceding observer's
+        // possibly mutated argument tree. One bounded copy per observer.
+        for (const observer of observers) {
+          await observer.handle(event, structuredClone(data), metadata, graph);
+        }
+      },
+    };
+  }
+
   return composed as Record<string, t.EventHandler>;
 }