@librechat/agents 3.3.3 → 3.3.5

package/dist/types/types/run.d.ts

@@ -101,6 +101,63 @@ export type StandardGraphConfig = Omit<MultiAgentGraphConfig, 'edges' | 'type'>
     type?: 'standard';
     signal?: AbortSignal;
 };
+/**
+ * Cooperative mid-generation preemption. Lets a host seal the live model
+ * stream at the next provider-safe token boundary — the run is never
+ * aborted, the partial assistant turn is kept, and the graph self-loops
+ * into a fresh model call once the `PreemptBoundary` hook has injected
+ * whatever the host queued.
+ *
+ * Preconditions the host MUST satisfy:
+ *   - `shouldPreempt` is polled once per streamed chunk on the top-level
+ *     graph. It must be synchronous, allocation-free and O(1) — never I/O.
+ *     It must also be LEVEL-TRIGGERED (non-consuming): the SDK never clears
+ *     the host's request, and a true result is only honored once the
+ *     accumulated chunk is provider-safe, so the predicate may be polled
+ *     many times before a seal. A one-shot read that clears its own pending
+ *     flag would silently lose the request on an unsafe chunk (leading
+ *     whitespace/reasoning, an in-flight tool call) — keep returning true
+ *     until the `PreemptBoundary` drain hands over the queued injection,
+ *     then disarm there.
+ *   - Sealing is only honored on the SDK's own dispatch loop. A run whose
+ *     registered `CHAT_MODEL_STREAM` handler IS the SDK dispatcher — or wraps
+ *     it, which `composeEventHandlers` and `createRunHandlers` both do —
+ *     consumes chunks through a decoupled `streamEvents` reader that can lag
+ *     the accumulated chunk, so those runs never seal.
+ *
+ *     Detection is by capability, not identity: the dispatcher carries
+ *     `SDK_STREAM_DISPATCH` and the SDK's wrappers propagate it. A handler
+ *     that merely OBSERVES the raw chunk echo — LibreChat's no-op
+ *     `OpenAIChatModelStreamHandler`, say — is unbranded and does NOT disable
+ *     sealing, because it assigns no content-part indices and so cannot be
+ *     inverted. A host that renders from the raw feed and wants the opt-out
+ *     should brand its handler with `SDK_STREAM_DISPATCH`.
+ *   - `RunConfig.tokenCounter` should be set. A sealed turn ends before most
+ *     providers send their usage chunk, so the synthetic `CHAT_MODEL_END`
+ *     falls back to the counter to report `output_tokens`. Without one that
+ *     fallback silently no-ops and the sealed turn's usage is lost — verified
+ *     live: OpenAI, Azure OpenAI and DeepSeek report no usage for the sealed
+ *     segment without a counter, while Anthropic streams usage incrementally
+ *     and reports it either way.
+ */
+export interface StreamPreemption {
+    /**
+     * Polled once per streamed chunk. Synchronous, allocation-free, O(1), and
+     * level-triggered — keep returning true until the `PreemptBoundary` drain
+     * consumes the request; a self-clearing read loses it on an unsafe chunk.
+     */
+    shouldPreempt: () => boolean;
+    /**
+     * Max cooperative seals per run. Each seal costs one extra superstep, so
+     * this also bounds the recursion-limit headroom the run reserves.
+     */
+    maxSeals?: number;
+}
+/** Seals honored and boundaries that had nothing to inject, per run. */
+export type PreemptStats = {
+    seals: number;
+    emptyBoundaries: number;
+};
 export type RunConfig = {
     runId: string;
     graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
@@ -132,6 +189,14 @@ export type RunConfig = {
      * block to prevent leaks.
      */
     hooks?: HookRegistry;
+    /**
+     * Opt-in cooperative preemption for this run. Requires a `hooks` registry
+     * with a `PreemptBoundary` matcher — the seal only stops the stream, the
+     * hook is what supplies the messages to resume with. Omit to keep the
+     * pre-preemption behavior, where a mid-run injection can only land at a
+     * tool boundary.
+     */
+    preemption?: StreamPreemption;
     returnContent?: boolean;
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;

package/dist/types/types/stream.d.ts

@@ -2,7 +2,6 @@ import type { MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessa
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { LLMResult, Generation } from '@langchain/core/outputs';
 import type { Command } from '@langchain/langgraph';
-import type OpenAITypes from 'openai';
 import type { AnthropicContentBlock } from '@/llm/anthropic/types';
 import type { SummarizeCompleteEvent } from '@/types/summarize';
 import type { ToolEndEvent } from '@/types/tools';
@@ -265,7 +264,7 @@ export type ToolCallPart = {
     /** If provided, an identifier associated with the tool call */
     id?: string;
     /** If provided, the output of the tool call */
-    output?: string;
+    output?: ToolResultContent['content'];
     /** Auth URL */
     auth?: string;
     /** Expiration time */
@@ -297,30 +296,6 @@ export interface TMessage {
     [key: string]: unknown;
 }
 export type TPayload = Array<Partial<TMessage>>;
-export type CustomChunkDelta = null | undefined | (Partial<OpenAITypes.Chat.Completions.ChatCompletionChunk.Choice.Delta> & {
-    reasoning?: string | null;
-    reasoning_content?: string | null;
-});
-export type CustomChunkChoice = Partial<Omit<OpenAITypes.Chat.Completions.ChatCompletionChunk.Choice, 'delta'> & {
-    delta?: CustomChunkDelta;
-}>;
-export type CustomChunk = Partial<OpenAITypes.ChatCompletionChunk> & {
-    choices?: Partial<Array<CustomChunkChoice>>;
-};
-export type SplitStreamHandlers = Partial<{
-    [GraphEvents.ON_RUN_STEP]: ({ event, data, }: {
-        event: GraphEvents;
-        data: RunStep;
-    }) => void;
-    [GraphEvents.ON_MESSAGE_DELTA]: ({ event, data, }: {
-        event: GraphEvents;
-        data: MessageDeltaEvent;
-    }) => void;
-    [GraphEvents.ON_REASONING_DELTA]: ({ event, data, }: {
-        event: GraphEvents;
-        data: ReasoningDeltaEvent;
-    }) => void;
-}>;
 export type SummarizeDeltaData = {
     id: string;
     delta: {

package/dist/types/utils/tokens.d.ts

@@ -44,6 +44,13 @@ export declare function estimateDocumentBlockTokens(block: Record<string, unknow
  */
 export declare function estimateTimedMediaBlockTokens(block: Record<string, unknown>): number;
 export declare function encodingForModel(model: string): EncodingName;
+/**
+ * Detects values whose native JSON representation can differ after local
+ * measurement. Accessor properties and `toJSON` hooks are deliberately not
+ * invoked; values too large to inspect within bounded work are treated as
+ * unsafe so the caller can normalize or reject them conservatively.
+ */
+export declare function hasUnsafeStructuredSerialization(value: unknown): boolean;
 export declare function getTokenCountForMessage(message: BaseMessage, getTokenCount: (text: string) => number, encoding?: EncodingName): number;
 /**
  * Largest-remainder apportionment: scales each count by `multiplier` and

package/dist/types/utils/toolContent.d.ts

@@ -0,0 +1,107 @@
+import { ToolMessage, type BaseMessage } from '@langchain/core/messages';
+type ToolContent = BaseMessage['content'];
+/**
+ * Serializes values that providers render as JSON without throwing on values
+ * such as bigint or circular diagnostic metadata.
+ */
+export declare function serializeStructuredValue(value: unknown): string;
+type StructuredWorkState = {
+    remaining: number;
+    characterRemaining: number;
+    exceeded: boolean;
+    failurePlaceholder?: string;
+    propertyCache: WeakMap<object, Map<string, unknown>>;
+    propertyCacheEntries: number;
+};
+export type BoundedStructuredSerialization = {
+    /** Provider-facing head/tail preview, bounded by `maxChars`. */
+    content: string;
+    /** Exact serialized prefix up to the defensive traversal-work ceiling. */
+    prefix: string;
+    /** Exact length, or `Number.MAX_SAFE_INTEGER` when traversal was capped. */
+    originalChars: number;
+    truncated: boolean;
+};
+/**
+ * Serializes structured output while retaining at most the requested provider
+ * preview and registry prefix. The traversal never calls `toJSON` and never
+ * materializes the complete serialized string when it exceeds those limits.
+ *
+ * `prefixChars` is useful for the tool-output registry: it receives the exact
+ * serialized prefix up to `registry.perOutputLimit`, while `content` retains
+ * the provider-facing head/tail truncation behavior at `maxChars`. Property
+ * accessors are represented by a fixed placeholder instead of being invoked.
+ */
+export declare function serializeStructuredValueBounded(value: unknown, maxChars: number, prefixChars?: number, work?: StructuredWorkState): BoundedStructuredSerialization;
+export declare function isAtomicToolContentBlock(value: unknown): boolean;
+/**
+ * Produces the text representation providers use for structured tool results.
+ * Text-only block arrays stay readable; opaque blocks use canonical JSON.
+ */
+export declare function serializeToolContent(content: unknown): string;
+export declare function getToolContentCharLength(content: unknown): number;
+/**
+ * Produces provider-facing tool-result text without ever exceeding `maxChars`.
+ */
+export declare function serializeToolContentBounded(content: unknown, maxChars: number): string;
+export type CompactToolContentResult = {
+    content: ToolContent;
+    changed: boolean;
+    originalChars: number;
+};
+export type CacheControlledTextToolContent = [
+    {
+        type: 'text';
+        text: string;
+        cache_control: {
+            type: 'ephemeral';
+            ttl?: '1h';
+        };
+    }
+];
+/** Reads one safe text block and returns its bounded text payload. */
+export declare function getBoundedSingleTextToolContent(content: unknown, maxChars: number): string | undefined;
+/**
+ * Canonicalizes the single cache-decorated text block produced by tail prompt
+ * caching without invoking accessors or custom serialization hooks.
+ */
+export declare function getBoundedCacheControlledTextToolContent(content: unknown, maxChars: number): CacheControlledTextToolContent | undefined;
+export type ComputerCallOutputScreenshot = {
+    type: 'input_image';
+    image_url: string;
+    detail?: InputImageDetail;
+} | {
+    type: 'input_image';
+    file_id: string;
+    detail?: InputImageDetail;
+} | {
+    type: 'computer_screenshot';
+    image_url: string;
+} | {
+    type: 'computer_screenshot';
+    file_id: string;
+};
+type InputImageDetail = 'low' | 'high' | 'auto' | 'original';
+/**
+ * Selects the exact screenshot shape accepted by LangChain's Responses
+ * converter without invoking accessors or user-defined serialization hooks.
+ */
+export declare function getComputerCallOutputScreenshot(content: unknown): ComputerCallOutputScreenshot | undefined;
+/** Returns the provider image URL when a screenshot is URL-backed. */
+export declare function getComputerCallOutputImageUrl(content: unknown): string | undefined;
+/** Returns whether content can be sent as a native computer screenshot. */
+export declare function isComputerCallOutputContent(content: unknown): content is ToolContent;
+/** Returns whether a ToolMessage carries the native computer-output marker. */
+export declare function hasComputerCallOutputMarker(message: BaseMessage): boolean;
+/** Native Responses computer screenshots are indivisible provider payloads. */
+export declare function isComputerCallOutputMessage(message: BaseMessage): boolean;
+/**
+ * Bounds structured tool output without slicing binary/media payloads.
+ * Purely textual/structured arrays become a universally valid string tool
+ * result. For mixed-media arrays, compactable blocks become one text preview
+ * while atomic blocks remain intact.
+ */
+export declare function compactToolContent(content: unknown, maxChars: number): CompactToolContentResult;
+/** Clones a ToolMessage while retaining fields omitted by ad-hoc clones. */
+export declare function cloneToolMessageWithContent(message: ToolMessage, content: ToolContent, artifact?: unknown): ToolMessage;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.3.3",
+  "version": "3.3.5",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/__tests__/stream.eagerEventExecution.test.ts

@@ -2498,6 +2498,80 @@ describe('ChatModelStreamHandler eager event tool execution', () => {
     ).toBe(true);
   });
 
+  it('serializes bigint output before eager completion dispatch', async () => {
+    const graph = createGraph();
+    const completedEvents: Array<{ result: t.ToolEndEvent }> = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<void> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          completedEvents.push(data as { result: t.ToolEndEvent });
+          return;
+        }
+        if (event !== GraphEvents.ON_TOOL_EXECUTE) {
+          return;
+        }
+        const batch = data as t.ToolExecuteBatchRequest;
+        batch.resolve([
+          {
+            toolCallId: 'call_weather',
+            status: 'success',
+            content: [{ rowsRead: BigInt(42) }],
+          },
+        ]);
+      });
+
+    const handler = new ChatModelStreamHandler();
+    const metadata = { langgraph_node: 'agent' };
+    await handler.handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_call_chunks: [
+            {
+              id: 'call_weather',
+              name: 'weather',
+              args: '{"city":"NYC"}',
+              index: 0,
+            },
+          ],
+        } as unknown as t.StreamChunk,
+      },
+      metadata,
+      graph
+    );
+    await handler.handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_call_chunks: [
+            {
+              id: 'call_stock',
+              name: 'stock',
+              args: '{"ticker":"C',
+              index: 1,
+            },
+          ],
+        } as unknown as t.StreamChunk,
+      },
+      metadata,
+      graph
+    );
+
+    await graph.eagerEventToolExecutions.get('call_weather')?.promise;
+
+    expect(completedEvents).toHaveLength(1);
+    expect(
+      (
+        completedEvents[0].result as {
+          tool_call?: { output?: string };
+        }
+      ).tool_call?.output
+    ).toBe('[{"rowsRead":"42"}]');
+  });
+
   it('does not emit a stale eager completion after the active execution is invalidated', async () => {
     const graph = createGraph({
       getAgentContext: jest.fn(

package/src/agents/AgentContext.ts

@@ -1638,6 +1638,7 @@ export class AgentContext {
       provider: this.provider,
       tokenCounter,
       maxTokens: this.maxContextTokens,
+      maxToolResultChars: this.maxToolResultChars,
       thinkingEnabled: isThinkingEnabled(this.provider, this.clientOptions),
       indexTokenCountMap,
       contextPruningConfig: this.contextPruningConfig,