@librechat/agents 3.3.4 → 3.3.5

package/dist/types/llm/preempt.d.ts

@@ -0,0 +1,40 @@
+import type { AIMessageChunk } from '@langchain/core/messages';
+/**
+ * Normalizes a host-supplied seal budget.
+ *
+ * Read in two places that interpret it differently — a numeric comparison in
+ * the seal gate and an addition into the recursion limit — so a value like
+ * `1.5` would permit two seals while reserving fractional headroom, `NaN`
+ * would poison the recursion limit outright, and `Infinity` would remove both
+ * bounds at once. Normalizing once keeps the two readings in agreement.
+ *
+ * `0` is honored as a deliberate "never seal"; anything not finite falls back
+ * to the default rather than silently disabling the feature.
+ */
+export declare function resolveMaxSeals(maxSeals: number | undefined): number;
+/**
+ * Cooperative mid-generation seal gate. Returns true ONLY when sealing here
+ * yields a message sequence valid on EVERY supported provider:
+ *  - non-whitespace TEXT content, so the FIRST injected user turn is preceded
+ *    by a non-empty assistant turn — no empty-content 400s. Note this says
+ *    nothing about adjacency AMONG several injected turns: a boundary that
+ *    drains two steers emits two consecutive user messages, which strict
+ *    providers reject. That is normalized at the provider-facing hop by
+ *    `coalesceAdjacentUserTurns`, not here;
+ *  - no tool call in flight, so no `tool_use` can be orphaned AND no eagerly
+ *    prestarted execution can be stripped out from under the model.
+ *
+ * Anthropic's server-side tools need no check of their own. Every
+ * `server_tool_use` content block also emits a `tool_call_chunk`
+ * (`_makeMessageChunkFromAnthropicEvent`), and `concat` keeps that chunk on
+ * the accumulated message for the remainder of the turn, so the tool-call
+ * gates below already cover it. The practical consequence is worth stating
+ * plainly: once a turn starts a web search it is no longer preemptible, and
+ * a queued message waits for the ordinary tool boundary instead.
+ *
+ * Nothing is stripped and nothing is repaired: when the accumulated shape is
+ * not already safe the stream simply runs on, and whatever the host queued
+ * lands at the next tool boundary instead. Chunks accumulate monotonically
+ * through `concat`, so an unsafe shape can never be observed at a seal point.
+ */
+export declare function canSealPreempt(chunk: AIMessageChunk | undefined): boolean;

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

@@ -0,0 +1,23 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import { Providers } from '@/common';
+/**
+ * Providers whose APIs specify strict user/assistant alternation. Mistral
+ * rejects consecutive user turns outright. Bedrock's Converse API documents
+ * the alternation requirement across many model families; enforcement varies
+ * by family — Claude on Converse currently tolerates adjacent user turns
+ * (verified live, 2026-07-28) — so the payload is normalized for all of them
+ * rather than betting on per-family leniency. Anthropic's own Messages API,
+ * OpenAI and Gemini all accept consecutive user turns, so they are
+ * deliberately absent.
+ */
+export declare const strictAlternationProviders: ReadonlySet<Providers>;
+/**
+ * Merges runs of consecutive human turns into one, for providers that reject
+ * them. Purely a wire-shaping pass: it returns a new array of new messages,
+ * so graph state and the host's persisted messages keep the per-message
+ * identity that steer rendering and the trailing-steer anchor rely on.
+ *
+ * Tool-result turns are excluded — the converters merge those themselves, and
+ * combining one with a text turn would orphan the pairing.
+ */
+export declare function coalesceAdjacentUserTurns(messages: BaseMessage[]): BaseMessage[];

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

@@ -0,0 +1,40 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Bracketed-meta convention, like the handoff path's
+ * `[Processed tool result and transferring to …]` bridge. The wording makes
+ * two things unambiguous to the model: the assistant turn above is FINISHED,
+ * and it belongs to a previous stage — so the successor answers as itself
+ * instead of continuing someone else's sentence.
+ */
+export declare const PREDECESSOR_HANDOFF_CUE: string;
+/**
+ * Appends a user-turn handoff cue when a payload ends with an assistant turn
+ * that THIS RUN produced — which only happens when a different agent in a
+ * multi-agent workflow produced it (an agent's own self-loops always re-enter
+ * on a tool result or an injected user turn).
+ *
+ * Why: providers with prefill semantics (Anthropic, Bedrock-Claude) treat a
+ * trailing assistant message as a prefill and CONTINUE it. A bare direct-edge
+ * successor therefore speaks in its predecessor's voice — or, when the
+ * trailing turn reads complete (a preemption steer's short resume, say),
+ * returns empty content (danny-avila/agents#345, reproduced live 3/3).
+ * Handoff edges with instructions and prompt-instruction edges already break
+ * the prefill with a user turn; this closes the same gap for bare edges.
+ *
+ * Fail-safe OFF by provenance: the trailing payload message must be one the
+ * run itself produced (`isRunProduced`, backed by the graph's run-produced id
+ * set — immune to summarization compaction, which rewrites the live array
+ * and stales index-based boundaries). Host-supplied trailing assistant
+ * turns (deliberate prefill flows) never match — the run has not produced
+ * them — so single-agent prefill behavior is untouched. Wire-only: the cue is
+ * appended to the provider projection, never to graph state or host history.
+ */
+export declare function appendPredecessorHandoffCue(messages: BaseMessage[], isRunProduced: ((message: BaseMessage) => boolean) | undefined): BaseMessage[];
+/**
+ * Strips a trailing handoff cue. The counterpart for the serving-provider
+ * funnel: an Anthropic-like PRIMARY bakes the cue into its measured payload,
+ * and a tolerant fallback (OpenAI, Mistral, Bedrock-Nova) re-sending that
+ * payload must not ship the Claude-only synthetic turn. Identity on the
+ * no-op path.
+ */
+export declare function removePredecessorHandoffCue(messages: BaseMessage[]): BaseMessage[];

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

@@ -7,6 +7,9 @@ export * from './cache';
 export * from './anthropicToolCache';
 export * from './content';
 export * from './tools';
+export * from './injected';
+export * from './alternation';
+export * from './handoffCue';
 export * from './contextPruning';
 export * from './contextPruningSettings';
 export * from './reducer';

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

@@ -0,0 +1,3 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { InjectedMessage } from '@/types/tools';
+export declare function convertInjectedMessages(messages: InjectedMessage[]): BaseMessage[];

package/dist/types/run.d.ts

@@ -17,6 +17,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private interruptingToolNames?;
     private toolExecution?;
     private subagentUsageSink?;
+    private preemption?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     graphRunnable?: t.CompiledStateWorkflow;
@@ -109,6 +110,12 @@ export declare class Run<_T extends t.BaseGraphState> {
      */
     getCalibrationRatio(): number;
     getResolvedInstructionOverhead(): number | undefined;
+    /**
+     * Cooperative-seal counters for this run. `emptyBoundaries` is the one to
+     * watch: it counts seals whose `PreemptBoundary` produced nothing to
+     * inject, which ends the turn early and leaves the answer unfinished.
+     */
+    getPreemptStats(): t.PreemptStats;
     getToolCount(): number;
     /**
      * Creates a custom event callback handler that intercepts custom events

package/dist/types/stream.d.ts

@@ -8,7 +8,21 @@ export declare function getChunkContent({ chunk, provider, reasoningKey, }: {
     provider?: Providers;
     reasoningKey: 'reasoning_content' | 'reasoning';
 }): string | t.MessageContentComplex[] | undefined;
+/**
+ * Brands a handler as one that dispatches content parts for the SDK — either
+ * `ChatModelStreamHandler` itself or a wrapper forwarding to one.
+ *
+ * Identity alone is not a usable contract here. Hosts compose and wrap
+ * handlers (`composeEventHandlers`, `createRunHandlers`), and every wrapper
+ * fails `instanceof` while still driving the same dispatch. A brand survives
+ * wrapping, so "does this handler own content-part dispatch" can be answered
+ * about a value the SDK did not construct.
+ */
+export declare const SDK_STREAM_DISPATCH: unique symbol;
+/** True when `handler` is, or forwards to, the SDK's stream dispatcher. */
+export declare function dispatchesChatModelStream(handler?: t.EventHandler): boolean;
 export declare class ChatModelStreamHandler implements t.EventHandler {
+    readonly [SDK_STREAM_DISPATCH] = true;
     handle(event: string, data: t.StreamEventData, metadata?: Record<string, unknown>, graph?: StandardGraph): Promise<void>;
     handleReasoning(chunk: Partial<AIMessageChunk>, agentContext: AgentContext): void;
 }

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

@@ -401,13 +401,6 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * actually dispatched so the caller can fall back to batch-time emission.
      */
     private dispatchEarlyToolCompletion;
-    /**
-     * Converts InjectedMessage instances to LangChain HumanMessage objects.
-     * Both 'user' and 'system' roles become HumanMessage to avoid provider
-     * rejections (Anthropic/Google reject non-leading SystemMessages).
-     * The original role is preserved in additional_kwargs for downstream consumers.
-     */
-    private convertInjectedMessages;
     /**
      * Execute a group of direct (in-process) tool calls with interrupt-safe
      * ordering, returning outputs aligned 1:1 with `directCalls`.

package/dist/types/tools/search/keenable-scraper.d.ts

@@ -0,0 +1,15 @@
+import type * as t from './types';
+export declare class KeenableScraper implements t.BaseScraper {
+    private apiKey;
+    private apiUrl;
+    private timeout;
+    private attributionTitle;
+    private logger;
+    constructor(config?: t.KeenableScraperConfig);
+    private buildHeaders;
+    scrapeUrl(url: string, options?: t.KeenableScrapeOptions): Promise<[string, t.KeenableScrapeResponse]>;
+    scrapeUrls(urls: string[], options?: t.KeenableScrapeOptions): Promise<Array<[string, t.KeenableScrapeResponse]>>;
+    extractContent(response: t.KeenableScrapeResponse): [string, undefined | t.References];
+    extractMetadata(response: t.KeenableScrapeResponse): t.GenericScrapeMetadata;
+}
+export declare const createKeenableScraper: (config?: t.KeenableScraperConfig) => KeenableScraper;

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

@@ -3,7 +3,7 @@ import type { Logger as WinstonLogger } from 'winston';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
 export type SearchProvider = 'serper' | 'searxng' | 'tavily' | 'keenable' | 'crw';
-export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily' | 'crw';
+export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily' | 'crw' | 'keenable';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 export interface Highlight {
     score: number;
@@ -172,6 +172,34 @@ export interface KeenableSearchResult {
 export interface KeenableSearchResponse {
     results?: KeenableSearchResult[];
 }
+export interface KeenableScraperConfig {
+    apiKey?: string;
+    /** Override the fetch endpoint base (default: public keyless, keyed when a
+     * key is set). Env fallback: KEENABLE_FETCH_URL. */
+    apiUrl?: string;
+    timeout?: number;
+    logger?: Logger;
+    /** Sent as the X-Keenable-Title attribution header. Defaults to "LibreChat". */
+    attributionTitle?: string;
+}
+export type KeenableScrapeOptions = Omit<KeenableScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
+/** Raw JSON shape returned by GET /v1/fetch{,/public}?url=... */
+export interface KeenableFetchResult {
+    url?: string;
+    title?: string;
+    content?: string;
+    description?: string;
+}
+export interface KeenableScrapeResponse {
+    success: boolean;
+    data?: {
+        content: string;
+        title?: string;
+        description?: string;
+        url?: string;
+    };
+    error?: string;
+}
 export type References = {
     links: MediaReference[];
     images: MediaReference[];
@@ -272,6 +300,7 @@ export type Logger = WinstonLogger;
 export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
     tavilyScraperOptions?: TavilyScraperConfig;
     crwScraperOptions?: CrwScraperConfig;
+    keenableScraperOptions?: KeenableScraperConfig;
     /** Max chars of highlight content this tool feeds the MODEL per search (the
      * dominant, otherwise-unbounded part of the output). Distinct from
      * `maxContentLength`, which caps scraped/reranked content per source — full
@@ -303,7 +332,7 @@ export type UsedReferences = {
     originalIndex: number;
     reference: MediaReference;
 }[];
-export type AnyScraperResponse = FirecrawlScrapeResponse | SerperScrapeResponse | TavilyScrapeResponse | CrwScrapeResponse;
+export type AnyScraperResponse = FirecrawlScrapeResponse | SerperScrapeResponse | TavilyScrapeResponse | CrwScrapeResponse | KeenableScrapeResponse;
 /** Base Scraper Interface */
 export interface BaseScraper {
     scrapeUrl(url: string, options?: unknown): Promise<[string, AnyScraperResponse]>;

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

@@ -7,7 +7,7 @@ import type { GoogleAIToolType } from '@langchain/google-common';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
 import type { ToolMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
 import type { RunStep, RunStepDeltaEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
-import type { TokenCounter, TokenBudgetBreakdown } from '@/types/run';
+import type { TokenCounter, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -243,6 +243,13 @@ export type StandardGraphInput = {
      * hook inputs carry only `executingAgentId`.
      */
     subagentScope?: boolean;
+    /**
+     * Cooperative preemption, forwarded from `RunConfig.preemption`. Only ever
+     * set on the top-level graph: a steer targets the conversation, so subagent
+     * children must run to completion and `buildChildInputs` does not propagate
+     * this field.
+     */
+    preemption?: StreamPreemption;
 };
 export type GraphEdge = {
     /** Agent ID, use a list for multiple sources */

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';
@@ -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/package.json

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