@librechat/agents 3.3.4 → 3.3.6

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

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Tool intent labels.
+ *
+ * Lets a tool declare, as the FIRST property of its input schema, an `intent`
+ * string: one model-authored sentence stating what that specific call is about
+ * to do ("Searching for OAuth handling in the callback router"). Because the
+ * property is first, it is the first key providers stream in the tool-call
+ * args, so a host UI can render it as the call's live status label before the
+ * rest of the args exist. When the call settles, {@link applyOutcome} edits
+ * the sentence in place into its outcome form — a tool-supplied replacement
+ * (`outcome`), a tool-supplied span edit (`outcome_patch`), or a mechanical
+ * present-progressive→past-tense transform of the leading verb.
+ *
+ * The arg is always optional (never listed in `required`): the same schemas
+ * are callable from programmatic tool calling, where no UI renders a label
+ * and forcing generated code to fabricate one would be pure cost. Tool bodies
+ * must call {@link stripIntent} before using their args so no tool receives a
+ * parameter it did not declare.
+ */
+import type { JsonSchemaType, OutcomePatch } from '@/types';
+/** Argument carrying the model-authored label for a tool call. */
+export declare const INTENT_ARG = "intent";
+/** Model-facing instruction for the injected `intent` property. */
+export declare const INTENT_DESCRIPTION: string;
+/**
+ * Canonical (frozen) shape of the injected property. Always embed a COPY
+ * (`{ ...INTENT_PROPERTY }`): LangChain's JSON-schema validator stamps a
+ * `__absolute_uri__` marker onto every subschema it dereferences, which
+ * throws on a frozen object — and a single shared instance would be stamped
+ * with one schema's URI while embedded in many.
+ */
+export declare const INTENT_PROPERTY: JsonSchemaType;
+/**
+ * Discriminates the intent LABEL property from a tool's own business
+ * parameter that merely shares the name: the label contract always opens
+ * with the same instruction. Removal/sanitize passes must never strip a
+ * parameter the tool actually needs.
+ */
+export declare function isIntentLabelProperty(property: unknown): boolean;
+/**
+ * Returns a copy of the parameters schema with `intent` prepended as the
+ * FIRST property (object key order is insertion order and every provider
+ * serializer preserves it — first key in the schema means first key in the
+ * streamed input). Never mutates the input; no-op when the schema already
+ * declares `intent`. The property is not added to `required`.
+ */
+export declare function withIntent(parameters?: JsonSchemaType): JsonSchemaType;
+/**
+ * Reads the model-authored intent from tool-call args (handles stringified
+ * args). Returns undefined when absent, empty, or not a string.
+ */
+export declare function readIntent(args: unknown): string | undefined;
+/**
+ * Returns the args without the `intent` key so downstream consumers that did
+ * not declare it never receive it. Parses stringified JSON object args;
+ * returns the value unchanged when the key is absent.
+ */
+export declare function stripIntent(args: unknown): unknown;
+/**
+ * Resolves the settled label for a call from its model-authored `intent` and
+ * the tool's result fields, in precedence order:
+ *
+ *  1. `outcome` — full replacement authored by the tool.
+ *  2. `outcome_patch` — first occurrence of `from` in the intent replaced
+ *     with `to` (case-sensitive); no-op when `from` is absent or empty.
+ *  3. Mechanical transform — the leading word mapped present-progressive →
+ *     past tense; an unknown leading word leaves the intent unchanged.
+ *
+ * Returns undefined when there is neither an intent nor an outcome, so
+ * callers fall back to their default label. Pure and dependency-free — host
+ * UIs needing identical logic can import or mirror it.
+ */
+export declare function applyOutcome(intent: string | undefined, result?: {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+}): string | undefined;
+/**
+ * Resolves the settled label to emit on a completion event: only when the
+ * tool actually authored `outcome`/`outcome_patch` fields. Returns undefined
+ * otherwise — the mechanical transform of a bare intent is left to the host
+ * so the wire never carries a label the host can derive itself. The result
+ * is collapsed to a bounded single line before emission.
+ *
+ * For failed calls (`isError`), only tool-AUTHORED text may label the call:
+ * an explicit `outcome`, or a patch whose `from` actually matches the
+ * intent. An unmatched patch must not fall through to the mechanical
+ * past-tense transform — wording drift in a failure patch would otherwise
+ * render a success-looking label for an error.
+ */
+export declare function resolveToolOutcome(args: unknown, fields?: {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+} | null, options?: {
+    isError?: boolean;
+}): string | undefined;
+/**
+ * Reads the outcome fields off a tool-execution result: the typed
+ * `outcome`/`outcome_patch` fields when present, else the artifact channel
+ * (see {@link readOutcomeFields}) — so a `content_and_artifact` tool authors
+ * its label the same way on the direct and event-driven paths.
+ */
+export declare function outcomeFieldsFromResult(result: {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+    artifact?: unknown;
+}): {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+} | undefined;
+/**
+ * Extracts validated `outcome`/`outcome_patch` fields from an arbitrary
+ * value — the artifact channel through which an in-process
+ * `content_and_artifact` tool authors its settled label. Returns undefined
+ * when neither field is usable.
+ */
+export declare function readOutcomeFields(source: unknown): {
+    outcome?: string;
+    outcome_patch?: OutcomePatch;
+} | undefined;

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

@@ -1,3 +1,4 @@
+import type { JsonSchemaType } from '@/types';
 export declare const DEFAULT_CODE_API_RUN_TIMEOUT_MS = 15000;
 export declare const MIN_CODE_API_RUN_TIMEOUT_MS = 1000;
 export declare const MAX_CODE_API_RUN_TIMEOUT_SCHEMA_MS = 300000;
@@ -11,6 +12,7 @@ type TimeoutSchema = {
 export type ProgrammaticToolCallingJsonSchema = {
     type: 'object';
     properties: {
+        intent: JsonSchemaType;
         code: {
             type: 'string';
             minLength: number;

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/schema.d.ts

@@ -36,6 +36,15 @@ export declare const newsSchema: {
 export declare const WebSearchToolSchema: {
     readonly type: "object";
     readonly properties: {
+        readonly intent: {
+            readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+            readonly enum?: string[];
+            readonly items?: import("../..").JsonSchemaType;
+            readonly properties?: Record<string, import("../..").JsonSchemaType>;
+            readonly required?: string[];
+            readonly description?: string;
+            readonly additionalProperties?: boolean | import("../..").JsonSchemaType;
+        };
         readonly query: {
             readonly type: "string";
             readonly description: string;
@@ -72,6 +81,15 @@ export declare const WebSearchToolDefinition: {
     readonly schema: {
         readonly type: "object";
         readonly properties: {
+            readonly intent: {
+                readonly type: "string" | "number" | "integer" | "float" | "boolean" | "array" | "object";
+                readonly enum?: string[];
+                readonly items?: import("../..").JsonSchemaType;
+                readonly properties?: Record<string, import("../..").JsonSchemaType>;
+                readonly required?: string[];
+                readonly description?: string;
+                readonly additionalProperties?: boolean | import("../..").JsonSchemaType;
+            };
             readonly query: {
                 readonly type: "string";
                 readonly description: string;

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

@@ -2,6 +2,24 @@ import { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from './types';
 import { DATE_RANGE } from './schema';
 import { createSearchAPI } from './search';
+/**
+ * Settled label for a `web_search` call's intent (see `intentArg.ts`).
+ *
+ * Counts the result kinds `formatResultsForLLM` actually renders —
+ * `references` only tracks links embedded in extracted highlights, so it
+ * undercounts ordinary results and can overcount when one highlight embeds
+ * several links.
+ *
+ * A caught provider or processing failure is reported through `data.error`
+ * while the tool still returns NORMALLY, so that case must author its own
+ * label: the `ToolMessage` carries success status, and a bare intent would
+ * otherwise settle mechanically from "Searching…" to "Searched…" and present
+ * a failed search as a successful one.
+ *
+ * Returns undefined for a genuine zero-result search, leaving the host's
+ * mechanical past-tense transform to label it.
+ */
+export declare function resolveSearchOutcome(data: t.SearchResultData, query: string): string | undefined;
 /**
  * Executes parallel searches and merges the results,
  * deduplicating top stories by link

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/tools/toolOutputReferences.d.ts

@@ -69,8 +69,18 @@ export type ResolveResult<T> = {
  * point in time, ignoring any subsequent registrations.
  */
 export interface ToolOutputResolveView {
-    resolve<T>(args: T): ResolveResult<T>;
+    resolve<T>(args: T, options?: ResolveOptions): ResolveResult<T>;
 }
+/**
+ * Per-call resolution options. `substituteIntentKey` opts the top-level
+ * `intent` key back INTO placeholder substitution: the exemption protects
+ * the injected display label, but a tool whose own schema declares a
+ * business parameter named `intent` (the injectors skip such tools) still
+ * needs references piped into it like any other argument.
+ */
+export type ResolveOptions = {
+    substituteIntentKey?: boolean;
+};
 /**
  * Pre-resolved arg map keyed by `toolCallId`. Used by the mixed
  * direct+event dispatch path to feed event calls' resolved args
@@ -166,7 +176,7 @@ export declare class ToolOutputReferenceRegistry {
      * the serialized args, the original input is returned without
      * walking the tree.
      */
-    resolve<T>(runId: string | undefined, args: T): ResolveResult<T>;
+    resolve<T>(runId: string | undefined, args: T, options?: ResolveOptions): ResolveResult<T>;
     /**
      * Captures a frozen snapshot of `runId`'s current entries and
      * returns a view that resolves placeholders against *only* that

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';
@@ -99,6 +98,13 @@ export type ProcessedToolCall = {
     id: string;
     output: string;
     progress: number;
+    /**
+     * Settled label for the call, resolved from the tool-supplied
+     * `outcome`/`outcome_patch` result fields against the model-authored
+     * `intent` arg. Only present when the tool authored one — hosts apply
+     * the mechanical intent transform themselves when absent.
+     */
+    outcome?: string;
 };
 export type ProcessedContent = {
     type: ContentType;
@@ -266,6 +272,11 @@ export type ToolCallPart = {
     id?: string;
     /** If provided, the output of the tool call */
     output?: ToolResultContent['content'];
+    /**
+     * Tool-authored settled label for the call (see `ProcessedToolCall.outcome`),
+     * preserved through aggregation so it survives persistence/reload.
+     */
+    outcome?: string;
     /** Auth URL */
     auth?: string;
     /** Expiration time */
@@ -297,30 +308,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/types/tools.d.ts

@@ -224,8 +224,16 @@ export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
     /** The Step Id of the Tool Call */
     id: string;
-    /** The Completed Tool Call */
-    tool_call: ToolCall;
+    /**
+     * The Completed Tool Call. Carries the tool-authored `outcome` label when
+     * present (see `ProcessedToolCall.outcome`) so `ON_RUN_STEP_COMPLETED`
+     * consumers can read it without an unsafe cast.
+     */
+    tool_call: ToolCall & {
+        output?: string;
+        progress?: number;
+        outcome?: string;
+    };
     /** The content index of the tool call */
     index: number;
     type?: 'tool_call';
@@ -486,6 +494,16 @@ export type InjectedMessage = {
     /** Only set when source is 'skill', for compaction preservation */
     skillName?: string;
 };
+/**
+ * In-place edit of a call's model-authored `intent` label: the first
+ * occurrence of `from` in the intent is replaced with `to` (case-sensitive).
+ * Lets a tool settle the label while preserving the model's own phrasing,
+ * e.g. `{ from: 'Searching', to: 'Searched' }`.
+ */
+export type OutcomePatch = {
+    from: string;
+    to: string;
+};
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
     /** Matches ToolCallRequest.id */
@@ -498,6 +516,13 @@ export type ToolExecuteResult = {
     status: 'success' | 'error';
     /** Error message if status is 'error' */
     errorMessage?: string;
+    /**
+     * Settled human-readable label for this call, replacing the model-authored
+     * `intent` arg in the UI. Full replacement; wins over `outcome_patch`.
+     */
+    outcome?: string;
+    /** In-place edit of the model-authored `intent` label (see {@link OutcomePatch}). */
+    outcome_patch?: OutcomePatch;
     /**
      * Messages to inject into graph state after the ToolMessage for this call.
      * Placed after tool results to respect provider message ordering (tool_call -> tool_result adjacency).

package/package.json

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