@librechat/agents 3.6.9 → 3.6.11

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

@@ -45,6 +45,26 @@ export declare function shouldIncludeEncryptedReasoning(model: string, params: {
 export declare function getCacheWriteTokens(message: BaseMessage): number | undefined;
 export declare function attachCacheWriteUsage(message: BaseMessage): void;
 export declare function attachCacheWriteMetadata(response: OpenAIClient.Responses.Response): OpenAIClient.Responses.Response;
+type ResponsesAnnotationsBoundaryEvent = {
+    type: OpenAIClient.Responses.ResponseStreamEvent['type'];
+    response?: {
+        output?: Array<{
+            type: string;
+            content?: Array<{
+                type: string;
+                annotations?: object[] | null;
+            }>;
+        }>;
+    };
+};
+/**
+ * The Responses API spec declares `annotations` required on `output_text`
+ * content parts, but some OpenAI-compatible gateways omit the field on the
+ * terminal `response.completed`/`response.incomplete` events. LangChain's
+ * converter calls `part.annotations.map(...)` unconditionally, so a missing
+ * field crashes the whole stream. Default it to `[]` before conversion.
+ */
+export declare function ensureResponsesOutputAnnotations(event: ResponsesAnnotationsBoundaryEvent): void;
 /**
  * Classifies a generation chunk for the smoothing engine:
  * - splittable: plain visible text (string content equal to `chunk.text`, no

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

@@ -158,6 +158,11 @@ export declare function shiftIndexTokenCountMap(indexTokenCountMap: Record<numbe
  * the provider wire.
  */
 export declare function isSyntheticProviderContextMessage(message: BaseMessage): boolean;
+/** Compacts a folded provider-context message without retaining source claims
+ * for bytes whose mapping cannot survive the lossy compaction. The unsourced
+ * user/tool parts intentionally make security consumers inspect the exact
+ * compacted wire under both external trust domains. */
+export declare function compactSyntheticProviderContextMessage(message: HumanMessage, maxChars: number): HumanMessage;
 /**
  * Ensures compatibility when switching from a non-thinking agent to a thinking-enabled agent.
  * Converts AI messages with tool calls (that lack thinking/reasoning blocks) into buffer strings,

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

@@ -15,3 +15,4 @@ export * from './contextPruningSettings';
 export * from './reducer';
 export * from './recency';
 export * from './assistantPhase';
+export * from './provenance';

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

@@ -0,0 +1,85 @@
+import type { BaseMessage } from '@langchain/core/messages';
+export declare const PROVIDER_MESSAGE_PROVENANCE_VERSION: 1;
+/** Recommended consumer trust bounds. Producers preserve complete lineage
+ * above these limits; security-sensitive consumers must reject oversized
+ * envelopes and take their fail-closed path rather than truncate attribution. */
+export declare const PROVIDER_MESSAGE_PROVENANCE_LIMITS: Readonly<{
+    readonly maxParts: 256;
+    readonly maxIndicesPerPart: 256;
+    readonly maxTotalIndexRefs: 4096;
+    readonly maxSourceMessageIds: 256;
+    readonly maxSourceMessageIdLength: 512;
+    readonly maxSourceContentPartIndex: 4095;
+}>;
+/** Authorship of one logical contribution to a provider-bound message. */
+export type ProviderMessageAttribution = 'user' | 'model' | 'tool' | 'synthetic';
+/**
+ * Lineage for one logical contribution to a provider-bound message.
+ * `sourceContentPartIndices` index the persisted source message's `content`
+ * array before formatting, filtering, or summary-boundary slicing.
+ */
+export interface ProviderMessageProvenancePart {
+    readonly attribution: ProviderMessageAttribution;
+    readonly sourceMessageId?: string;
+    readonly sourceContentPartIndices?: readonly number[];
+}
+/** Stable, versioned provenance carried in `BaseMessage.additional_kwargs`. */
+export interface ProviderMessageProvenance {
+    readonly version: typeof PROVIDER_MESSAGE_PROVENANCE_VERSION;
+    readonly parts: readonly ProviderMessageProvenancePart[];
+}
+/** Inert marker used only when a derived message must retain invalidity. */
+export interface InvalidProviderMessageProvenance {
+    readonly version: typeof PROVIDER_MESSAGE_PROVENANCE_VERSION;
+    readonly parts: null;
+}
+/** Distinguishes absent metadata from an explicitly malformed envelope. */
+export type ProviderMessageProvenanceState = {
+    readonly status: 'absent';
+} | {
+    readonly status: 'invalid';
+} | {
+    readonly status: 'valid';
+    readonly provenance: ProviderMessageProvenance;
+};
+/** Distinguishes absent lineage from validated ids and malformed metadata. */
+export type ProviderSourceMessageIdsState = {
+    readonly status: 'absent';
+} | {
+    readonly status: 'invalid';
+} | {
+    readonly status: 'valid';
+    readonly sourceMessageIds: readonly string[];
+};
+/** Typed subset of `additional_kwargs` exposed at provider callbacks. */
+export interface ProviderMessageProvenanceAdditionalKwargs {
+    readonly provenance?: ProviderMessageProvenance | InvalidProviderMessageProvenance;
+    readonly sourceMessageId?: string;
+    readonly sourceMessageIds?: readonly string[];
+}
+/** Returns explicitly stamped provenance without inferring from message role. */
+export declare function getProviderMessageProvenance(message: BaseMessage): ProviderMessageProvenance | undefined;
+/** Safely preserves the semantic difference between absent and invalid input. */
+export declare function inspectProviderMessageProvenance(message: BaseMessage): ProviderMessageProvenanceState;
+/** Safely distinguishes missing source lineage from malformed metadata. */
+export declare function inspectProviderSourceMessageIds(message: BaseMessage): ProviderSourceMessageIdsState;
+/** True when indexed contributions uniquely cover every current content part. */
+export declare function hasBijectiveProviderContentPartMapping(parts: readonly ProviderMessageProvenancePart[], contentPartCount: number): boolean;
+/**
+ * Returns every explicit persisted source id in stable content order.
+ * Typed parts, plural lineage, and the legacy singular id are unioned in that
+ * precedence order; duplicates are removed without reordering.
+ */
+export declare function getProviderSourceMessageIds(message: BaseMessage): string[];
+/** Replaces typed provenance and synchronizes its stable plural source ids. */
+export declare function setProviderMessageProvenance(message: BaseMessage, parts: readonly ProviderMessageProvenancePart[]): void;
+/** Publishes the canonical fail-closed marker for malformed provenance. */
+export declare function setInvalidProviderMessageProvenance(message: BaseMessage): void;
+/** Marks a provider-visible runtime message as host-generated context. */
+export declare function stampSyntheticProviderMessage<T extends BaseMessage>(message: T): T;
+/**
+ * Adds one logical lineage contribution, migrating legacy ids on first use.
+ * This compatibility helper rebuilds validated public metadata; hot formatters
+ * should accumulate locally and call `setProviderMessageProvenance` once.
+ */
+export declare function appendProviderMessageProvenance(message: BaseMessage, part: ProviderMessageProvenancePart): void;

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

@@ -0,0 +1,33 @@
+export type ProviderToolCallKind = 'tool' | 'server' | 'anthropic-server' | 'mcp' | 'google' | 'bedrock';
+export interface ProviderToolCallPartDescriptor {
+    readonly callId: string;
+    readonly kind: ProviderToolCallKind;
+    readonly name?: string;
+    readonly sourceType: string;
+}
+export interface ProviderToolResultPartDescriptor {
+    readonly type: string;
+    readonly compatibleCallKinds: readonly ProviderToolCallKind[];
+    readonly toolCallId?: string;
+    readonly expectedToolNames?: readonly string[];
+    readonly requiresPreviousExecutableCode?: boolean;
+    readonly allowHumanMessagePairing?: boolean;
+}
+export interface ProviderToolCallIndexEntry {
+    readonly descriptor: ProviderToolCallPartDescriptor;
+    secondarySourceType?: string;
+}
+export type ProviderToolCallIndex = Map<string, ProviderToolCallIndexEntry | null>;
+export declare const PROVIDER_TOOL_RESULT_MAX_ARRAY_ENTRIES = 256;
+export declare const PROVIDER_TOOL_RESULT_MAX_VALIDATION_ENTRIES = 4096;
+export declare const PROVIDER_TOOL_PAIRING_MAX_IDENTIFIER_CHARS = 512;
+export declare const PROVIDER_TOOL_PAIRING_MAX_OUTER_PARTS = 4096;
+export declare function getBoundedProviderPairingArray(value: unknown): readonly unknown[] | undefined;
+export declare function getBoundedProviderPairingArrayProperty(value: unknown, key: string): readonly unknown[] | undefined;
+export declare function isBoundedProviderPairingString(value: unknown, allowEmpty?: boolean): value is string;
+export declare function hasStructurallyValidAnthropicWebSearchResultContent(part: unknown): boolean;
+export declare function getProviderToolResultPartDescriptor(part: unknown): ProviderToolResultPartDescriptor | undefined;
+export declare function getProviderAIMessageToolCallDescriptor(toolCall: unknown): ProviderToolCallPartDescriptor | undefined;
+export declare function getProviderToolCallPartDescriptor(part: unknown): ProviderToolCallPartDescriptor | undefined;
+export declare function appendProviderToolCallDescriptor(index: ProviderToolCallIndex, descriptor: ProviderToolCallPartDescriptor): void;
+export declare function consumeProviderToolResultPair(descriptor: ProviderToolResultPartDescriptor, calls: ProviderToolCallIndex, previousPart?: unknown): boolean;

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

@@ -0,0 +1,25 @@
+import type * as t from '@/types';
+export type CallerCapabilityProjection = {
+    directTools: t.LCTool[];
+    codeExecutionTools: t.LCTool[];
+    directOnlyTools: t.LCTool[];
+    codeExecutionOnlyTools: t.LCTool[];
+};
+/**
+ * Combines event schemas with runtime capability metadata. Matching runtime
+ * entries override caller/defer policy without replacing the event schema;
+ * runtime-only definitions are appended intact.
+ */
+export declare function mergeCallerCapabilityDefinitions(toolDefs: Iterable<t.LCTool> | null | undefined, overrides: Iterable<t.LCTool> | null | undefined): t.LCTool[];
+/**
+ * Applies runtime caller metadata to schema-only event definitions without
+ * adding registry-only tools or replacing their model-facing schemas.
+ */
+export declare function applyCallerCapabilityDefinitionOverrides(toolDefs: Iterable<t.LCTool>, overrides: Iterable<t.LCTool> | null | undefined): t.LCTool[];
+/** Converts the live projection into the versioned event transport shape. */
+export declare function createCallerCapabilityProjectionSnapshot(projection: CallerCapabilityProjection): t.CallerCapabilityProjectionSnapshot;
+export declare function getAllowedCallers(toolDef: t.LCTool): readonly t.AllowedCaller[];
+export declare function allowsToolCaller(toolDef: t.LCTool, caller: t.AllowedCaller): boolean;
+export declare function isProgrammaticControlTool(name: string): boolean;
+export declare function isToolDefinitionActive(toolDef: t.LCTool, discoveredToolNames: ReadonlySet<string>): boolean;
+export declare function resolveCallerCapabilityProjection(toolDefs: Iterable<t.LCTool>, isActive?: (toolDef: t.LCTool) => boolean): CallerCapabilityProjection;

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

@@ -0,0 +1,20 @@
+import type * as t from '@/types';
+export type ProgrammaticInvocationParams = {
+    code: string;
+    tool_manifest?: string[];
+    timeout?: number;
+    lang?: string;
+    runtime?: string;
+    language?: string;
+};
+export declare function resolveProgrammaticToolDefinitions(context: Partial<t.ProgrammaticCache> & {
+    tools?: t.LCTool[];
+}): t.LCTool[] | undefined;
+export declare function projectProgrammaticToolMap(toolMap: t.ToolMap, selectedToolDefs: readonly t.LCTool[]): t.ToolMap;
+export declare function assertDisallowedToolUsage(disallowedNames: ReadonlySet<string>, programmaticToolName: string): void;
+export declare function selectProgrammaticTools(args: {
+    requestedToolNames?: string[];
+    allowedToolDefs?: t.LCTool[];
+    disallowedToolDefs?: t.LCTool[];
+    programmaticToolName: string;
+}): t.LCTool[];

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

@@ -122,8 +122,12 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private settledInterruptingResults;
     /** Tool registry for filtering (lazy computation of programmatic maps) */
     private toolRegistry?;
-    /** Cached programmatic tools (computed once on first PTC call) */
-    private programmaticCache?;
+    /** Schema-only definitions used when event mode has no runtime registry. */
+    private toolDefinitions?;
+    /** Tool-map entries created or replaced by the local execution resolver. */
+    private localImplementationNames;
+    /** Reads deferred-tool discovery state from the owning agent context. */
+    private getDiscoveredToolNames?;
     /** Reference to Graph's sessions map for automatic session injection */
     private sessions?;
     /** Partition within `sessions` owned by this agent's execution profile. */
@@ -213,7 +217,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, restoreRunStepResumeState, createRunStepResumeState, }: t.ToolNodeConstructorParams);
+    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, toolDefinitions, getDiscoveredToolNames, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, restoreRunStepResumeState, createRunStepResumeState, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     /**
      * Returns the run-scoped tool output registry, or `undefined` when
@@ -257,10 +261,11 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * they reuse a ToolNode across batches outside of a Graph.
      */
     clearDirectPathTurns(): void;
-    /**
-     * Returns cached programmatic tools, computing once on first access.
-     * Single iteration builds both toolMap and toolDefs simultaneously.
-     */
+    /** Returns the live caller projection used by direct and event execution. */
+    private getCallerCapabilityProjection;
+    /** Serializes the live caller projection for event-driven hosts. */
+    private getCallerCapabilityProjectionSnapshot;
+    /** Returns active tools projected by their effective caller capabilities. */
     private getProgrammaticTools;
     /**
      * Returns a snapshot of the current tool usage counts.

package/dist/types/tools/local/resolveLocalExecutionTools.d.ts

@@ -2,6 +2,8 @@ import type * as t from '@/types';
 type ResolveLocalToolsResult = {
     toolMap: t.ToolMap;
     directToolNames: Set<string>;
+    /** Names whose toolMap entries were created or replaced by this resolver. */
+    localImplementationNames: Set<string>;
     /**
      * Set when `local.fileCheckpointing === true` AND the auto-bind
      * coding suite is in use. ToolNode stashes this on the node and
@@ -14,17 +16,25 @@ type ResolveLocalToolsResult = {
      */
     fileCheckpointer?: t.LocalFileCheckpointer;
 };
+export declare function isProgrammaticRunnerAutoBound(name: string, config?: t.ToolExecutionConfig): boolean;
+/** Mirrors whether resolver policy creates or replaces this runner locally. */
+export declare function isProgrammaticRunnerResolvedDirectly(name: string, config?: t.ToolExecutionConfig, hasExplicitBinding?: boolean): boolean;
 export declare function resolveLocalToolsForBinding(args: {
     tools?: t.GraphTools;
     toolExecution?: t.ToolExecutionConfig;
+    toolRegistry?: t.LCToolRegistry;
+    discoveredToolNames?: ReadonlySet<string>;
 }): t.GraphTools | undefined;
 export declare function resolveLocalToolRegistry(args: {
     toolRegistry?: t.LCToolRegistry;
     toolExecution?: t.ToolExecutionConfig;
 }): t.LCToolRegistry | undefined;
+/** Names that this execution config creates or replaces in the local tool map. */
+export declare function resolveLocalImplementationNames(toolNames: Iterable<string>, toolExecution?: t.ToolExecutionConfig): Set<string>;
 export declare function resolveLocalExecutionTools(args: {
     toolMap: t.ToolMap;
     toolExecution?: t.ToolExecutionConfig;
+    toolRegistry?: t.LCToolRegistry;
     /**
      * Caller-provided checkpointer that overrides the bundle's
      * auto-created one. The Graph layer threads a single per-Run

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

@@ -18,6 +18,14 @@ export type ProgrammaticToolCallingJsonSchema = {
             minLength: number;
             description: string;
         };
+        tool_manifest: {
+            type: 'array';
+            items: {
+                type: 'string';
+            };
+            uniqueItems: true;
+            description: string;
+        };
         timeout: TimeoutSchema;
     };
     required: readonly ['code'];

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

@@ -6,7 +6,7 @@ import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
 import type { RunStep, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
-import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
+import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecutionConfig, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { SubagentTaskConfig } from '@/types/subagentTasks';
@@ -225,6 +225,8 @@ export type StandardGraphInput = {
     runId?: string;
     signal?: AbortSignal;
     agents: AgentInputs[];
+    /** Execution backend used to resolve the effective tool registry. */
+    toolExecution?: ToolExecutionConfig;
     langfuse?: LangfuseConfig;
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;

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

@@ -1,9 +1,9 @@
-import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableConfig, RunnableToolLike } from '@langchain/core/runnables';
+import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type { MessageContentComplex, RunStepResumeState, ToolErrorData } from './stream';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { RunBreakerScope } from '@/llm/streamLimits';
-import type { MessageContentComplex, RunStepResumeState, ToolErrorData } from './stream';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { LangfuseConfig } from './graph';
 import type { HookRegistry } from '@/hooks';
@@ -116,6 +116,8 @@ export type ToolNodeOptions = {
     errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<boolean | void>;
     /** Tool registry for lazy computation of programmatic tools and tool search */
     toolRegistry?: LCToolRegistry;
+    /** Returns the owning agent's currently discovered deferred tool names. */
+    getDiscoveredToolNames?: () => readonly string[];
     /** Reference to Graph's sessions map for automatic session injection */
     sessions?: ToolSessionMap;
     /** Partition within `sessions` used by this agent's code tools. */
@@ -511,6 +513,18 @@ export type ToolCallRequest = {
      */
     runtimeSessionHint?: string;
 };
+/**
+ * Serializable view of the active tools grouped by their effective caller
+ * capabilities. Event-driven hosts use this snapshot to preserve the SDK's
+ * live deferred-tool discovery state without reimplementing its policy.
+ */
+export type CallerCapabilityProjectionSnapshot = {
+    version: 1;
+    directToolNames: string[];
+    codeExecutionToolNames: string[];
+    directOnlyToolNames: string[];
+    codeExecutionOnlyToolNames: string[];
+};
 /** Batch request containing ALL tool calls for a graph step */
 export type ToolExecuteBatchRequest = {
     /** All tool calls from the AIMessage */
@@ -519,6 +533,11 @@ export type ToolExecuteBatchRequest = {
     userId?: string;
     /** Agent ID for context */
     agentId?: string;
+    /**
+     * SDK-owned snapshot of the active caller capability projection. Optional
+     * so older event handlers remain compatible with newer SDKs.
+     */
+    callerCapabilityProjection?: CallerCapabilityProjectionSnapshot;
     /** Runtime configurable from RunnableConfig (includes user, userMCPAuthMap, etc.) */
     configurable?: Record<string, unknown>;
     /** Runtime metadata from RunnableConfig (includes thread_id, run_id, provider, etc.) */
@@ -1084,6 +1103,15 @@ export type ToolExecutionConfig = {
 export type ProgrammaticCache = {
     toolMap: ToolMap;
     toolDefs: LCTool[];
+    /** Actual outer runner name used for caller-policy diagnostics. */
+    programmaticToolName?: string;
+    /**
+     * Known tools that cannot be invoked from programmatic execution. Kept
+     * separate from `toolDefs` so the Programmatic Tool Manifest can be
+     * validated before the execution runtime starts without exposing their
+     * schemas to that runtime.
+     */
+    disallowedToolDefs?: LCTool[];
     /**
      * Hook context plumbed through by ToolNode for the local
      * programmatic-tool path so the in-process bridge can run

package/package.json

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