@librechat/agents 3.1.75 → 3.1.77-dev.1

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

@@ -1,20 +1,26 @@
 import { AzureOpenAI as AzureOpenAIClient } from 'openai';
 import { ChatXAI as OriginalChatXAI } from '@langchain/xai';
 import { ChatGenerationChunk } from '@langchain/core/outputs';
-import { AIMessage } from '@langchain/core/messages';
 import { ChatDeepSeek as OriginalChatDeepSeek } from '@langchain/deepseek';
 import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import { OpenAIClient, ChatOpenAI as OriginalChatOpenAI, AzureChatOpenAI as OriginalAzureChatOpenAI } from '@langchain/openai';
 import type { HeaderValue, HeadersLike } from './types';
-import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
 import type { BaseMessage } from '@langchain/core/messages';
-import type { ChatResult } from '@langchain/core/outputs';
+import type { BindToolsInput } from '@langchain/core/language_models/chat_models';
 import type { ChatXAIInput } from '@langchain/xai';
 import type * as t from '@langchain/openai';
 export declare function isHeaders(headers: unknown): headers is Headers;
 export declare function normalizeHeaders(headers: HeadersLike): Record<string, HeaderValue | readonly HeaderValue[]>;
-type OpenAICompletionParam = OpenAIClient.Chat.Completions.ChatCompletionMessageParam;
 type OpenAICoreRequestOptions = OpenAIClient.RequestOptions;
+type LibreChatOpenAIFields = t.ChatOpenAIFields & {
+    _lc_stream_delay?: number;
+    includeReasoningContent?: boolean;
+    includeReasoningDetails?: boolean;
+    convertReasoningDetailsToContent?: boolean;
+};
+type LibreChatAzureOpenAIFields = t.AzureOpenAIInput & {
+    _lc_stream_delay?: number;
+};
 /**
  * Formats a tool in either OpenAI format, or LangChain structured tool format
  * into an OpenAI tool format. If the tool is already in OpenAI format, return without
@@ -41,15 +47,12 @@ export declare class CustomAzureOpenAIClient extends AzureOpenAIClient {
     abortHandler?: () => void;
     fetchWithTimeout(url: RequestInfo, init: RequestInit | undefined, ms: number, controller: AbortController): Promise<Response>;
 }
-/** @ts-expect-error We are intentionally overriding `getReasoningParams` */
 export declare class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
     _lc_stream_delay?: number;
-    constructor(fields?: t.ChatOpenAICallOptions & {
-        _lc_stream_delay?: number;
-    } & t.OpenAIChatInput['modelKwargs']);
+    constructor(fields?: LibreChatOpenAIFields & t.OpenAIChatInput['modelKwargs']);
     get exposedClient(): CustomOpenAIClient;
     static lc_name(): string;
-    protected _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
+    _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
     /**
      * Returns backwards compatible reasoning parameters from constructor params and call options
      * @internal
@@ -57,14 +60,10 @@ export declare class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptio
     getReasoningParams(options?: this['ParsedCallOptions']): OpenAIClient.Reasoning | undefined;
     protected _getReasoningParams(options?: this['ParsedCallOptions']): OpenAIClient.Reasoning | undefined;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
-    _streamResponseChunks2(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
-/** @ts-expect-error We are intentionally overriding `getReasoningParams` */
 export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
     _lc_stream_delay?: number;
-    constructor(fields?: t.AzureOpenAIInput & {
-        _lc_stream_delay?: number;
-    });
+    constructor(fields?: LibreChatAzureOpenAIFields);
     get exposedClient(): CustomOpenAIClient;
     static lc_name(): 'LibreChatAzureOpenAI';
     /**
@@ -73,16 +72,17 @@ export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
      */
     getReasoningParams(options?: this['ParsedCallOptions']): OpenAIClient.Reasoning | undefined;
     protected _getReasoningParams(options?: this['ParsedCallOptions']): OpenAIClient.Reasoning | undefined;
-    protected _getClientOptions(options: OpenAICoreRequestOptions | undefined): OpenAICoreRequestOptions;
+    _getClientOptions(options: OpenAICoreRequestOptions | undefined): OpenAICoreRequestOptions;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
 export declare class ChatDeepSeek extends OriginalChatDeepSeek {
+    _lc_stream_delay?: number;
+    constructor(fields?: ConstructorParameters<typeof OriginalChatDeepSeek>[0] & {
+        _lc_stream_delay?: number;
+    });
     get exposedClient(): CustomOpenAIClient;
     static lc_name(): 'LibreChatDeepSeek';
-    protected _convertMessages(messages: BaseMessage[]): OpenAICompletionParam[];
-    _generate(messages: BaseMessage[], options: this['ParsedCallOptions'] | undefined, runManager?: CallbackManagerForLLMRun): Promise<ChatResult>;
-    protected _convertResponseToMessage(choice: OpenAIClient.Chat.Completions.ChatCompletion.Choice, data: OpenAIClient.Chat.Completions.ChatCompletion): AIMessage;
-    protected _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
+    _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
 /** xAI-specific usage metadata type */
@@ -102,11 +102,8 @@ export interface XAIUsageMetadata extends OpenAIClient.Completions.CompletionUsa
     num_sources_used?: number;
 }
 export declare class ChatMoonshot extends ChatOpenAI {
+    constructor(fields?: LibreChatOpenAIFields & t.OpenAIChatInput['modelKwargs']);
     static lc_name(): 'LibreChatMoonshot';
-    protected _convertMessages(messages: BaseMessage[]): OpenAICompletionParam[];
-    _generate(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): Promise<ChatResult>;
-    protected _convertResponseToMessage(choice: OpenAIClient.Chat.Completions.ChatCompletion.Choice, data: OpenAIClient.Chat.Completions.ChatCompletion): AIMessage;
-    _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
 export declare class ChatXAI extends OriginalChatXAI {
     _lc_stream_delay?: number;
@@ -121,7 +118,7 @@ export declare class ChatXAI extends OriginalChatXAI {
     });
     static lc_name(): 'LibreChatXAI';
     get exposedClient(): CustomOpenAIClient;
-    protected _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
+    _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
 export {};

package/dist/types/llm/openrouter/index.d.ts

@@ -1,7 +1,7 @@
 import { ChatOpenAI } from '@/llm/openai';
-import { ChatGenerationChunk } from '@langchain/core/outputs';
-import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
-import type { FunctionMessageChunk, SystemMessageChunk, HumanMessageChunk, ToolMessageChunk, ChatMessageChunk, AIMessageChunk, BaseMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { ChatOpenAICallOptions, OpenAIChatInput, OpenAIClient } from '@langchain/openai';
 export type OpenRouterReasoningEffort = 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none';
 export interface OpenRouterReasoning {
@@ -16,20 +16,22 @@ export interface ChatOpenRouterCallOptions extends Omit<ChatOpenAICallOptions, '
     reasoning?: OpenRouterReasoning;
     modelKwargs?: OpenAIChatInput['modelKwargs'];
 }
+export type ChatOpenRouterInput = Partial<ChatOpenRouterCallOptions & OpenAIChatInput>;
 /** invocationParams return type extended with OpenRouter reasoning */
 export type OpenRouterInvocationParams = Omit<OpenAIClient.Chat.ChatCompletionCreateParams, 'messages'> & {
     reasoning?: OpenRouterReasoning;
 };
+type InvocationParamsExtra = {
+    streaming?: boolean;
+};
 export declare class ChatOpenRouter extends ChatOpenAI {
     private openRouterReasoning?;
     /** @deprecated Use `reasoning` object instead */
     private includeReasoning?;
-    constructor(_fields: Partial<ChatOpenRouterCallOptions>);
+    constructor(_fields: ChatOpenRouterInput);
     static lc_name(): 'LibreChatOpenRouter';
-    invocationParams(options?: this['ParsedCallOptions'], extra?: {
-        streaming?: boolean;
-    }): OpenRouterInvocationParams;
+    invocationParams(options?: this['ParsedCallOptions'], extra?: InvocationParamsExtra): OpenRouterInvocationParams;
     private buildOpenRouterReasoning;
-    protected _convertOpenAIDeltaToBaseMessageChunk(delta: Record<string, any>, rawResponse: OpenAIClient.ChatCompletionChunk, defaultRole?: 'function' | 'user' | 'system' | 'developer' | 'assistant' | 'tool'): AIMessageChunk | HumanMessageChunk | SystemMessageChunk | FunctionMessageChunk | ToolMessageChunk | ChatMessageChunk;
-    _streamResponseChunks2(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
+    _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
+export {};

package/dist/types/llm/vertexai/index.d.ts

@@ -288,6 +288,7 @@ export declare class ChatVertexAI extends ChatGoogle {
     dynamicThinkingBudget: boolean;
     thinkingConfig?: GoogleThinkingConfig;
     static lc_name(): 'LibreChatVertexAI';
+    constructor(model: string, fields?: Omit<VertexAIClientOptions, 'model'>);
     constructor(fields?: VertexAIClientOptions);
     invocationParams(options?: this['ParsedCallOptions'] | undefined): GoogleAIModelRequestParams;
     buildConnection(fields: VertexAIClientOptions | undefined, client: GoogleAbstractedClient): void;

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

@@ -36,5 +36,8 @@ export declare function stripBedrockCacheControl<T extends MessageWithContent>(m
  * @param messages - The array of message objects.
  * @returns - A new array of message objects with cache points added.
  */
-export declare function addBedrockCacheControl<T extends Partial<BaseMessage> & MessageWithContent>(messages: T[]): T[];
+export declare function addBedrockCacheControl<T extends MessageWithContent & {
+    getType?: () => string;
+    role?: string;
+}>(messages: T[]): T[];
 export {};

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

@@ -84,6 +84,9 @@ interface LangChainMessage {
  * @returns - The formatted LangChain message.
  */
 export declare const formatFromLangChain: (message: LangChainMessage) => Record<string, any>;
+interface FormatAgentMessagesOptions {
+    provider?: Providers;
+}
 /**
  * Groups content parts by agent and formats them with agent labels
  * This preprocesses multi-agent content to prevent identity confusion
@@ -107,7 +110,7 @@ export declare const labelContentByAgent: (contentParts: MessageContentComplex[]
  * @param skills - Optional map of skill name to body for reconstructing skill HumanMessages.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
-export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>, skills?: Map<string, string>) => {
+export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>, skills?: Map<string, string>, options?: FormatAgentMessagesOptions) => {
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
     /** Cross-run summary extracted from the payload. Should be forwarded to the

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

@@ -0,0 +1,27 @@
+import type { MessageContent } from '@langchain/core/messages';
+import type * as t from '@/types';
+type LibreChatMessageContent = MessageContent | string | t.MessageContentComplex[] | t.ExtendedMessageContent[];
+type WithLangChainContent<T extends {
+    content: LibreChatMessageContent;
+}> = Omit<T, 'content'> & {
+    content: MessageContent;
+};
+/**
+ * Bridges LibreChat's extended content blocks to LangChain 1.x MessageContent.
+ *
+ * LangChain 1.x narrowed message constructor types around ContentBlock, while
+ * LibreChat still carries provider-specific blocks through the same content
+ * field. This helper keeps the runtime shape unchanged during the dependency
+ * upgrade; tracking issue: https://github.com/danny-avila/agents/issues/130.
+ */
+export declare function toLangChainContent(content: LibreChatMessageContent): MessageContent;
+/**
+ * Applies the same LangChain 1.x content bridge to message constructor fields.
+ *
+ * Keep this cast-only helper local to constructor boundaries so follow-up work
+ * can replace it with aligned content types or explicit conversion logic.
+ */
+export declare function toLangChainMessageFields<T extends {
+    content: LibreChatMessageContent;
+}>(message: T): WithLangChainContent<T>;
+export {};

package/dist/types/run.d.ts

@@ -1,4 +1,5 @@
 import './instrumentation';
+import { Command } from '@langchain/langgraph';
 import type { MessageContentComplex, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
@@ -10,6 +11,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private tokenCounter?;
     private handlerRegistry?;
     private hookRegistry?;
+    private humanInTheLoop?;
     private toolOutputReferences?;
     private indexTokenCountMap?;
     calibrationRatio: number;
@@ -18,9 +20,70 @@ export declare class Run<_T extends t.BaseGraphState> {
     returnContent: boolean;
     private skipCleanup;
     private _streamResult;
+    /**
+     * Captured interrupt payload typed as `unknown` because the SDK
+     * does not validate the runtime shape — custom graph nodes can
+     * raise interrupts with arbitrary payloads (not just the SDK's
+     * `HumanInterruptPayload` union). The public `getInterrupt<T>()`
+     * lets callers assert the type they expect.
+     */
+    private _interrupt;
+    private _haltedReason;
     private constructor();
     private createLegacyGraph;
     private createMultiAgentGraph;
+    /**
+     * When the host opted into HITL via `humanInTheLoop: { enabled: true }`
+     * and did not supply a checkpointer, install an in-memory `MemorySaver`
+     * so `interrupt()` can persist checkpoints and `Command({ resume })`
+     * can rebuild state. The fallback is intentionally process-local:
+     * production hosts that need durable resumption across processes /
+     * restarts must provide their own checkpointer (Redis, Postgres, etc.)
+     * on `compileOptions.checkpointer`.
+     *
+     * No-op when HITL is off (the default — omitted, or
+     * `{ enabled: false }`) or the host already supplied a checkpointer
+     * of their own. See `HumanInTheLoopConfig` JSDoc for the rationale
+     * behind the default-off stance.
+     */
+    private applyHITLCheckpointerFallback;
+    /**
+     * Run RunStart + UserPromptSubmit hooks before the graph stream
+     * begins, accumulate any `additionalContext` strings into the input
+     * messages, and short-circuit when a hook signals the run should not
+     * proceed (deny / ask decision on the prompt, or `preventContinuation`
+     * on either hook).
+     *
+     * Returns `true` when the caller should bail with `undefined` (run
+     * was halted before any model call); returns `false` to proceed
+     * into the stream loop.
+     *
+     * ## Side effects
+     *
+     * On the success path:
+     *   - Mutates `stateInputs.messages` in place to append a
+     *     consolidated `HumanMessage` carrying any hook
+     *     `additionalContext` strings. Safe because the host owns the
+     *     array and `processStream` is the only consumer until LangGraph
+     *     reads it.
+     *
+     * On the halt path (returning `true`):
+     *   - Sets `this._haltedReason` so callers (and the eventual host)
+     *     can distinguish a hook-driven halt from a natural completion.
+     *   - Calls `registry.clearSession(this.id)` and
+     *     `registry.clearHaltSignal(this.id)` because no resume is
+     *     expected from a pre-stream halt — the run never entered the
+     *     graph, so the session/halt state for this run would otherwise
+     *     leak to the next `processStream` invocation on the same
+     *     registry. Other concurrent runs on the same registry are
+     *     untouched (halt signals are scoped per session id).
+     *   - Sets `config.callbacks = undefined` to drop the callback
+     *     references the caller built (langfuse handler, custom event
+     *     handler, etc.) since they won't be exercised. Mirrors the
+     *     equivalent cleanup the `processStream` `finally` block does
+     *     on the natural-completion path.
+     */
+    private runPreStreamHooks;
     static create<T extends t.BaseGraphState>(config: t.RunConfig): Promise<Run<T>>;
     getRunMessages(): BaseMessage[] | undefined;
     /**
@@ -37,7 +100,60 @@ export declare class Run<_T extends t.BaseGraphState> {
      * and processes them through our handler registry instead of EventStreamCallbackHandler
      */
     private createCustomEventCallback;
-    processStream(inputs: t.IState, callerConfig: Partial<RunnableConfig> & {
+    processStream(inputs: t.IState | Command, callerConfig: Partial<RunnableConfig> & {
+        version: 'v1' | 'v2';
+        run_id?: string;
+    }, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;
+    /**
+     * Returns the pending interrupt captured during the most recent
+     * `processStream` (or `resume`) invocation. `undefined` when the run
+     * either has not been streamed yet or completed without pausing.
+     *
+     * Hosts call this immediately after `processStream` returns to decide
+     * whether the run is awaiting human input. Persist the returned
+     * descriptor (alongside `thread_id` and the agent run config) so a
+     * later `resume(decisions)` can rebuild the run.
+     *
+     * The default `TPayload` is the SDK's `HumanInterruptPayload` union
+     * (`tool_approval` / `ask_user_question`), suitable for the common
+     * case where interrupts come from the built-in ToolNode or
+     * `askUserQuestion()` helper. Hosts that raise custom interrupts
+     * from custom graph nodes pass their own type — the SDK does not
+     * validate the runtime shape, it just transports whatever the
+     * `interrupt()` call carried. When in doubt, narrow with the
+     * `isToolApprovalInterrupt` / `isAskUserQuestionInterrupt` type
+     * guards (which accept `unknown`) before reading variant-specific
+     * fields.
+     */
+    getInterrupt<TPayload = t.HumanInterruptPayload>(): t.RunInterruptResult<TPayload> | undefined;
+    /**
+     * Returns the reason a hook halted the run via
+     * `preventContinuation: true`, or `undefined` if no hook halted.
+     *
+     * Hosts inspect this after `processStream` returns to distinguish a
+     * natural completion (`undefined`) from a hook-driven halt (a
+     * truthy string). Independent from `getInterrupt()` — a halted run
+     * has no interrupt; an interrupted run has no halt reason.
+     */
+    getHaltReason(): string | undefined;
+    /**
+     * Resume a paused HITL run with the value the user (or whatever
+     * decided the interrupt) supplied. The default `TResume` covers the
+     * `tool_approval` interrupt (the common case): an array of decisions
+     * in `action_requests` order, or a record keyed by `tool_call_id`.
+     *
+     * For other interrupt types (e.g., `ask_user_question` →
+     * `AskUserQuestionResolution`, or any custom interrupt a host raises
+     * from a custom node), pass the type parameter and the SDK forwards
+     * the value through unchanged. LangGraph delivers it as the return
+     * value of the original `interrupt()` call inside the paused node.
+     *
+     * The host MUST construct this Run with the same `thread_id` and the
+     * same checkpointer as the original paused run; LangGraph rebuilds
+     * graph state from the checkpoint and re-enters the interrupted node
+     * from the start.
+     */
+    resume<TResume = t.ToolApprovalDecision[] | t.ToolApprovalDecisionMap>(resumeValue: TResume, callerConfig: Partial<RunnableConfig> & {
         version: 'v1' | 'v2';
         run_id?: string;
     }, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;

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

@@ -47,6 +47,12 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private maxToolResultChars;
     /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
     private hookRegistry?;
+    /**
+     * Run-scoped HITL config. When `enabled`, `ask` decisions from
+     * PreToolUse hooks raise a LangGraph `interrupt()` instead of being
+     * treated as fail-closed denies.
+     */
+    private humanInTheLoop?;
     /**
      * Registry of tool outputs keyed by `tool<idx>turn<turn>`.
      *
@@ -67,7 +73,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, toolOutputReferences, toolOutputRegistry, }: t.ToolNodeConstructorParams);
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, }: t.ToolNodeConstructorParams);
     /**
      * Returns the run-scoped tool output registry, or `undefined` when
      * the feature is disabled.
@@ -155,6 +161,25 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      *    ToolMessages (appended AFTER to respect provider ordering).
      */
     private dispatchToolEvents;
+    /**
+     * Fires the `PostToolBatch` hook (if registered) and appends the
+     * accumulated batch-level `additionalContext` strings to `injected`
+     * as a single `HumanMessage`. Entries are materialized in the
+     * original `toolCalls` order so hooks correlating outcomes by
+     * position (as the type docs promise) see exactly the sequence
+     * the model emitted, regardless of when each individual outcome
+     * was recorded into the map (deny synchronous, approved
+     * post-execution, respond on resume).
+     *
+     * The PostToolBatch hook's `additionalContexts` flow into the same
+     * batch accumulator per-tool hooks already use, so a single
+     * batch-level convention message can be injected through one path.
+     *
+     * Mutates `batchAdditionalContexts` (push from batch hook) and
+     * `injected` (push the consolidated HumanMessage). The caller owns
+     * those arrays and consumes them right after this returns.
+     */
+    private dispatchPostToolBatchAndInjectContext;
     private dispatchStepCompleted;
     /**
      * Converts InjectedMessage instances to LangChain HumanMessage objects.

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

@@ -0,0 +1,19 @@
+import type * as t from './types';
+export declare class TavilyScraper implements t.BaseScraper {
+    private apiKey;
+    private apiUrl;
+    private timeout;
+    private payloadTimeout;
+    private logger;
+    private extractDepth;
+    private includeImages;
+    private includeFavicon;
+    private format;
+    constructor(config?: t.TavilyScraperConfig);
+    scrapeUrl(url: string, options?: t.TavilyScrapeOptions): Promise<[string, t.TavilyScrapeResponse]>;
+    scrapeUrls(urls: string[], options?: t.TavilyScrapeOptions): Promise<Array<[string, t.TavilyScrapeResponse]>>;
+    private extractBatch;
+    extractContent(response: t.TavilyScrapeResponse): [string, undefined | t.References];
+    extractMetadata(response: t.TavilyScrapeResponse): t.GenericScrapeMetadata;
+}
+export declare const createTavilyScraper: (config?: t.TavilyScraperConfig) => TavilyScraper;

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

@@ -0,0 +1,4 @@
+import type * as t from './types';
+export declare const createTavilyAPI: (apiKey?: string, apiUrl?: string, options?: t.TavilySearchOptions) => {
+    getSources: (params: t.GetSourcesParams) => Promise<t.SearchResult>;
+};

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

@@ -2,8 +2,8 @@ import type { Logger as WinstonLogger } from 'winston';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
-export type SearchProvider = 'serper' | 'searxng';
-export type ScraperProvider = 'firecrawl' | 'serper';
+export type SearchProvider = 'serper' | 'searxng' | 'tavily';
+export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 export interface Highlight {
     score: number;
@@ -56,11 +56,50 @@ export interface Source {
     snippet?: string;
     date?: string;
 }
+export type TavilyTimeRange = 'day' | 'week' | 'month' | 'year';
+export type TavilyTimeRangeInput = TavilyTimeRange | 'h' | 'd' | 'w' | 'm' | 'y';
+export interface TavilySearchOptions {
+    searchDepth?: 'basic' | 'advanced' | 'fast' | 'ultra-fast';
+    maxResults?: number;
+    includeImages?: boolean;
+    includeAnswer?: boolean | 'basic' | 'advanced';
+    includeRawContent?: boolean | 'markdown' | 'text';
+    includeDomains?: string[];
+    excludeDomains?: string[];
+    topic?: 'general' | 'news' | 'finance';
+    timeRange?: TavilyTimeRangeInput;
+    includeImageDescriptions?: boolean;
+    includeFavicon?: boolean;
+    chunksPerSource?: number;
+    safeSearch?: boolean;
+    timeout?: number;
+}
+export interface TavilySearchPayload {
+    query: string;
+    search_depth: NonNullable<TavilySearchOptions['searchDepth']>;
+    topic: NonNullable<TavilySearchOptions['topic']>;
+    max_results: number;
+    safe_search?: boolean;
+    time_range?: TavilyTimeRange;
+    country?: string;
+    include_images?: boolean;
+    include_answer?: NonNullable<TavilySearchOptions['includeAnswer']>;
+    include_raw_content?: NonNullable<TavilySearchOptions['includeRawContent']>;
+    include_domains?: string[];
+    exclude_domains?: string[];
+    include_image_descriptions?: boolean;
+    include_favicon?: boolean;
+    chunks_per_source?: number;
+}
 export interface SearchConfig {
     searchProvider?: SearchProvider;
     serperApiKey?: string;
     searxngInstanceUrl?: string;
     searxngApiKey?: string;
+    tavilyApiKey?: string;
+    tavilySearchUrl?: string;
+    tavilyExtractUrl?: string;
+    tavilySearchOptions?: TavilySearchOptions;
 }
 export type References = {
     links: MediaReference[];
@@ -95,6 +134,16 @@ export interface SerperScraperConfig {
     logger?: Logger;
     includeMarkdown?: boolean;
 }
+export interface TavilyScraperConfig {
+    apiKey?: string;
+    apiUrl?: string;
+    timeout?: number;
+    logger?: Logger;
+    extractDepth?: 'basic' | 'advanced';
+    includeImages?: boolean;
+    includeFavicon?: boolean;
+    format?: 'markdown' | 'text';
+}
 export interface ScraperContentResult {
     content: string;
 }
@@ -135,6 +184,7 @@ export interface CohereRerankerResponse {
 export type SafeSearchLevel = 0 | 1 | 2;
 export type Logger = WinstonLogger;
 export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
+    tavilyScraperOptions?: TavilyScraperConfig;
     logger?: Logger;
     safeSearch?: SafeSearchLevel;
     jinaApiKey?: string;
@@ -157,15 +207,27 @@ export type UsedReferences = {
     originalIndex: number;
     reference: MediaReference;
 }[];
+export type AnyScraperResponse = FirecrawlScrapeResponse | SerperScrapeResponse | TavilyScrapeResponse;
 /** Base Scraper Interface */
 export interface BaseScraper {
-    scrapeUrl(url: string, options?: unknown): Promise<[string, FirecrawlScrapeResponse | SerperScrapeResponse]>;
-    extractContent(response: FirecrawlScrapeResponse | SerperScrapeResponse): [string, undefined | References];
-    extractMetadata(response: FirecrawlScrapeResponse | SerperScrapeResponse): ScrapeMetadata | Record<string, string | number | boolean | null | undefined>;
+    scrapeUrl(url: string, options?: unknown): Promise<[string, AnyScraperResponse]>;
+    scrapeUrls?(urls: string[], options?: unknown): Promise<Array<[string, AnyScraperResponse]>>;
+    extractContent(response: AnyScraperResponse): [string, undefined | References];
+    extractMetadata(response: AnyScraperResponse): ScrapeMetadata | GenericScrapeMetadata;
 }
 /** Firecrawl */
 export type FirecrawlScrapeOptions = Omit<FirecrawlScraperConfig, 'apiKey' | 'apiUrl' | 'version' | 'logger'>;
 export type SerperScrapeOptions = Omit<SerperScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
+export type TavilyScrapeOptions = Omit<TavilyScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
+export interface TavilyExtractPayload {
+    urls: string[];
+    extract_depth: NonNullable<TavilyScraperConfig['extractDepth']>;
+    include_images: boolean;
+    include_favicon?: boolean;
+    format?: NonNullable<TavilyScraperConfig['format']>;
+    timeout?: number;
+}
+export type GenericScrapeMetadata = Record<string, string | number | boolean | null | undefined>;
 export interface ScrapeMetadata {
     sourceURL?: string;
     url?: string;
@@ -241,6 +303,38 @@ export interface SerperScrapeResponse {
     };
     error?: string;
 }
+export interface TavilyScrapeResponse {
+    success: boolean;
+    data?: {
+        rawContent?: string;
+        images?: string[];
+        favicon?: string;
+    };
+    error?: string;
+}
+export interface TavilySearchResult {
+    title?: string;
+    url?: string;
+    content?: string;
+    score?: number;
+    published_date?: string;
+}
+export type TavilyImageResult = string | {
+    url?: string;
+    description?: string;
+};
+export interface TavilySearchResponse {
+    answer?: string;
+    images?: TavilyImageResult[];
+    results?: TavilySearchResult[];
+}
+export interface TavilyExtractResult {
+    url: string;
+    raw_content?: string;
+    images?: string[];
+    favicon?: string;
+    error?: string;
+}
 export interface FirecrawlScraperConfig {
     apiKey?: string;
     apiUrl?: string;

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

@@ -6,5 +6,5 @@ import type * as t from './types';
  */
 export declare const createDefaultLogger: () => t.Logger;
 export declare const fileExtRegex: RegExp;
-export declare const getDomainName: (link: string, metadata?: t.ScrapeMetadata, logger?: t.Logger) => string | undefined;
-export declare function getAttribution(link: string, metadata?: t.ScrapeMetadata, logger?: t.Logger): string | undefined;
+export declare const getDomainName: (link: string, metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata, logger?: t.Logger) => string | undefined;
+export declare function getAttribution(link: string, metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata, logger?: t.Logger): string | undefined;