illuma-agents 1.0.10 → 1.0.11

package/dist/esm/utils/run.mjs

@@ -28,8 +28,12 @@ class RunnableCallable extends Runnable {
     }
     async _tracedInvoke(input, config, runManager) {
         return new Promise((resolve, reject) => {
+            // Defensive check: ensure runManager has getChild method before calling
+            const childCallbacks = typeof runManager?.getChild === 'function'
+                ? runManager.getChild()
+                : undefined;
             const childConfig = patchConfig(config, {
-                callbacks: runManager?.getChild(),
+                callbacks: childCallbacks,
             });
             void AsyncLocalStorageProviderSingleton.runWithConfig(childConfig, async () => {
                 try {

package/dist/esm/utils/run.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run.mjs","sources":["../../../src/utils/run.ts"],"sourcesContent":["import { CallbackManagerForChainRun } from '@langchain/core/callbacks/manager';\nimport {\n  mergeConfigs,\n  patchConfig,\n  Runnable,\n  RunnableConfig,\n} from '@langchain/core/runnables';\nimport { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';\n\n/**\n * Delays the execution for a specified number of milliseconds.\n *\n * @param {number} ms - The number of milliseconds to delay.\n * @return {Promise<void>} A promise that resolves after the specified delay.\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface RunnableCallableArgs extends Partial<any> {\n  name?: string;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  func: (...args: any[]) => any;\n  tags?: string[];\n  trace?: boolean;\n  recurse?: boolean;\n}\n\nexport class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {\n  lc_namespace: string[] = ['langgraph'];\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  func: (...args: any[]) => any;\n\n  tags?: string[];\n\n  config?: RunnableConfig;\n\n  trace: boolean = true;\n\n  recurse: boolean = true;\n\n  constructor(fields: RunnableCallableArgs) {\n    super();\n    this.name = fields.name ?? fields.func.name;\n    this.func = fields.func;\n    this.config = fields.tags ? { tags: fields.tags } : undefined;\n    this.trace = fields.trace ?? this.trace;\n    this.recurse = fields.recurse ?? this.recurse;\n  }\n\n  protected async _tracedInvoke(\n    input: I,\n    config?: Partial<RunnableConfig>,\n    runManager?: CallbackManagerForChainRun\n  ): Promise<O> {\n    return new Promise<O>((resolve, reject) => {\n      const childConfig = patchConfig(config, {\n        callbacks: runManager?.getChild(),\n      });\n      void AsyncLocalStorageProviderSingleton.runWithConfig(\n        childConfig,\n        async () => {\n          try {\n            const output = await this.func(input, childConfig);\n            resolve(output);\n          } catch (e) {\n            reject(e);\n          }\n        }\n      );\n    });\n  }\n\n  async invoke(\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    input: any,\n    options?: Partial<RunnableConfig> | undefined\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ): Promise<any> {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let returnValue: any;\n\n    if (this.trace) {\n      returnValue = await this._callWithConfig(\n        this._tracedInvoke,\n        input,\n        mergeConfigs(this.config, options)\n      );\n    } else {\n      returnValue = await this.func(input, mergeConfigs(this.config, options));\n    }\n\n    if (Runnable.isRunnable(returnValue) && this.recurse) {\n      return await returnValue.invoke(input, options);\n    }\n\n    return returnValue;\n  }\n}"],"names":[],"mappings":";;;AASA;;;;;AAKG;AACG,SAAU,KAAK,CAAC,EAAU,EAAA;AAC9B,IAAA,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC1D;AAYM,MAAO,gBAA2C,SAAQ,QAAc,CAAA;AAC5E,IAAA,YAAY,GAAa,CAAC,WAAW,CAAC;;AAGtC,IAAA,IAAI;AAEJ,IAAA,IAAI;AAEJ,IAAA,MAAM;IAEN,KAAK,GAAY,IAAI;IAErB,OAAO,GAAY,IAAI;AAEvB,IAAA,WAAA,CAAY,MAA4B,EAAA;AACtC,QAAA,KAAK,EAAE;AACP,QAAA,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI;AAC3C,QAAA,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,SAAS;QAC7D,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK;QACvC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;;AAGrC,IAAA,MAAM,aAAa,CAC3B,KAAQ,EACR,MAAgC,EAChC,UAAuC,EAAA;QAEvC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,KAAI;AACxC,YAAA,MAAM,WAAW,GAAG,WAAW,CAAC,MAAM,EAAE;AACtC,gBAAA,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;AAClC,aAAA,CAAC;YACF,KAAK,kCAAkC,CAAC,aAAa,CACnD,WAAW,EACX,YAAW;AACT,gBAAA,IAAI;oBACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC;oBAClD,OAAO,CAAC,MAAM,CAAC;;gBACf,OAAO,CAAC,EAAE;oBACV,MAAM,CAAC,CAAC,CAAC;;AAEb,aAAC,CACF;AACH,SAAC,CAAC;;AAGJ,IAAA,MAAM,MAAM;;AAEV,IAAA,KAAU,EACV;;;;AAIA,QAAA,IAAI,WAAgB;AAEpB,QAAA,IAAI,IAAI,CAAC,KAAK,EAAE;YACd,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,CACtC,IAAI,CAAC,aAAa,EAClB,KAAK,EACL,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CACnC;;aACI;AACL,YAAA,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;QAG1E,IAAI,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE;YACpD,OAAO,MAAM,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;;AAGjD,QAAA,OAAO,WAAW;;AAErB;;;;"}
+{"version":3,"file":"run.mjs","sources":["../../../src/utils/run.ts"],"sourcesContent":["import { CallbackManagerForChainRun } from '@langchain/core/callbacks/manager';\nimport {\n  mergeConfigs,\n  patchConfig,\n  Runnable,\n  RunnableConfig,\n} from '@langchain/core/runnables';\nimport { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';\n\n/**\n * Delays the execution for a specified number of milliseconds.\n *\n * @param {number} ms - The number of milliseconds to delay.\n * @return {Promise<void>} A promise that resolves after the specified delay.\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface RunnableCallableArgs extends Partial<any> {\n  name?: string;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  func: (...args: any[]) => any;\n  tags?: string[];\n  trace?: boolean;\n  recurse?: boolean;\n}\n\nexport class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {\n  lc_namespace: string[] = ['langgraph'];\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  func: (...args: any[]) => any;\n\n  tags?: string[];\n\n  config?: RunnableConfig;\n\n  trace: boolean = true;\n\n  recurse: boolean = true;\n\n  constructor(fields: RunnableCallableArgs) {\n    super();\n    this.name = fields.name ?? fields.func.name;\n    this.func = fields.func;\n    this.config = fields.tags ? { tags: fields.tags } : undefined;\n    this.trace = fields.trace ?? this.trace;\n    this.recurse = fields.recurse ?? this.recurse;\n  }\n\n  protected async _tracedInvoke(\n    input: I,\n    config?: Partial<RunnableConfig>,\n    runManager?: CallbackManagerForChainRun\n  ): Promise<O> {\n    return new Promise<O>((resolve, reject) => {\n      // Defensive check: ensure runManager has getChild method before calling\n      const childCallbacks = typeof runManager?.getChild === 'function' \n        ? runManager.getChild() \n        : undefined;\n      const childConfig = patchConfig(config, {\n        callbacks: childCallbacks,\n      });\n      void AsyncLocalStorageProviderSingleton.runWithConfig(\n        childConfig,\n        async () => {\n          try {\n            const output = await this.func(input, childConfig);\n            resolve(output);\n          } catch (e) {\n            reject(e);\n          }\n        }\n      );\n    });\n  }\n\n  async invoke(\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    input: any,\n    options?: Partial<RunnableConfig> | undefined\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ): Promise<any> {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let returnValue: any;\n\n    if (this.trace) {\n      returnValue = await this._callWithConfig(\n        this._tracedInvoke,\n        input,\n        mergeConfigs(this.config, options)\n      );\n    } else {\n      returnValue = await this.func(input, mergeConfigs(this.config, options));\n    }\n\n    if (Runnable.isRunnable(returnValue) && this.recurse) {\n      return await returnValue.invoke(input, options);\n    }\n\n    return returnValue;\n  }\n}"],"names":[],"mappings":";;;AASA;;;;;AAKG;AACG,SAAU,KAAK,CAAC,EAAU,EAAA;AAC9B,IAAA,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC1D;AAYM,MAAO,gBAA2C,SAAQ,QAAc,CAAA;AAC5E,IAAA,YAAY,GAAa,CAAC,WAAW,CAAC;;AAGtC,IAAA,IAAI;AAEJ,IAAA,IAAI;AAEJ,IAAA,MAAM;IAEN,KAAK,GAAY,IAAI;IAErB,OAAO,GAAY,IAAI;AAEvB,IAAA,WAAA,CAAY,MAA4B,EAAA;AACtC,QAAA,KAAK,EAAE;AACP,QAAA,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI;AAC3C,QAAA,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,SAAS;QAC7D,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK;QACvC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO;;AAGrC,IAAA,MAAM,aAAa,CAC3B,KAAQ,EACR,MAAgC,EAChC,UAAuC,EAAA;QAEvC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,KAAI;;AAExC,YAAA,MAAM,cAAc,GAAG,OAAO,UAAU,EAAE,QAAQ,KAAK;AACrD,kBAAE,UAAU,CAAC,QAAQ;kBACnB,SAAS;AACb,YAAA,MAAM,WAAW,GAAG,WAAW,CAAC,MAAM,EAAE;AACtC,gBAAA,SAAS,EAAE,cAAc;AAC1B,aAAA,CAAC;YACF,KAAK,kCAAkC,CAAC,aAAa,CACnD,WAAW,EACX,YAAW;AACT,gBAAA,IAAI;oBACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC;oBAClD,OAAO,CAAC,MAAM,CAAC;;gBACf,OAAO,CAAC,EAAE;oBACV,MAAM,CAAC,CAAC,CAAC;;AAEb,aAAC,CACF;AACH,SAAC,CAAC;;AAGJ,IAAA,MAAM,MAAM;;AAEV,IAAA,KAAU,EACV;;;;AAIA,QAAA,IAAI,WAAgB;AAEpB,QAAA,IAAI,IAAI,CAAC,KAAK,EAAE;YACd,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,CACtC,IAAI,CAAC,aAAa,EAClB,KAAK,EACL,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CACnC;;aACI;AACL,YAAA,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;QAG1E,IAAI,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE;YACpD,OAAO,MAAM,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;;AAGjD,QAAA,OAAO,WAAW;;AAErB;;;;"}

package/dist/types/agents/AgentContext.d.ts

@@ -38,6 +38,13 @@ export declare class AgentContext {
     tools?: t.GraphTools;
     /** Tool map for this agent */
     toolMap?: t.ToolMap;
+    /**
+     * Tool definitions registry (includes deferred and programmatic tool metadata).
+     * Used for tool search and programmatic tool calling.
+     */
+    toolRegistry?: t.LCToolRegistry;
+    /** Set of tool names discovered via tool search (to be loaded) */
+    discoveredToolNames: Set<string>;
     /** Instructions for this agent */
     instructions?: string;
     /** Additional instructions for this agent */
@@ -52,13 +59,17 @@ export declare class AgentContext {
     currentTokenType: ContentTypes.TEXT | ContentTypes.THINK | 'think_and_text';
     /** Whether tools should end the workflow */
     toolEnd: boolean;
-    /** System runnable for this agent */
-    systemRunnable?: Runnable<BaseMessage[], (BaseMessage | SystemMessage)[], RunnableConfig<Record<string, unknown>>>;
+    /** Cached system runnable (created lazily) */
+    private cachedSystemRunnable?;
+    /** Whether system runnable needs rebuild (set when discovered tools change) */
+    private systemRunnableStale;
+    /** Cached system message token count (separate from tool tokens) */
+    private systemMessageTokens;
     /** Promise for token calculation initialization */
     tokenCalculationPromise?: Promise<void>;
     /** Format content blocks as strings (for legacy compatibility) */
     useLegacyContent: boolean;
-    constructor({ agentId, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
+    constructor({ agentId, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
         agentId: string;
         provider: Providers;
         clientOptions?: t.ClientOptions;
@@ -67,6 +78,7 @@ export declare class AgentContext {
         tokenCounter?: t.TokenCounter;
         tools?: t.GraphTools;
         toolMap?: t.ToolMap;
+        toolRegistry?: t.LCToolRegistry;
         instructions?: string;
         additionalInstructions?: string;
         reasoningKey?: 'reasoning_content' | 'reasoning';
@@ -75,9 +87,35 @@ export declare class AgentContext {
         useLegacyContent?: boolean;
     });
     /**
-     * Create system runnable from instructions and calculate tokens if tokenCounter is available
+     * Builds instructions text for tools that are ONLY callable via programmatic code execution.
+     * These tools cannot be called directly by the LLM but are available through the
+     * run_tools_with_code tool.
+     *
+     * Includes:
+     * - Code_execution-only tools that are NOT deferred
+     * - Code_execution-only tools that ARE deferred but have been discovered via tool search
+     */
+    private buildProgrammaticOnlyToolsInstructions;
+    /**
+     * Gets the system runnable, creating it lazily if needed.
+     * Includes instructions, additional instructions, and programmatic-only tools documentation.
+     * Only rebuilds when marked stale (via markToolsAsDiscovered).
+     */
+    get systemRunnable(): Runnable<BaseMessage[], (BaseMessage | SystemMessage)[], RunnableConfig<Record<string, unknown>>> | undefined;
+    /**
+     * Explicitly initializes the system runnable.
+     * Call this before async token calculation to ensure system message tokens are counted first.
+     */
+    initializeSystemRunnable(): void;
+    /**
+     * Builds the raw instructions string (without creating SystemMessage).
      */
-    private createSystemRunnable;
+    private buildInstructionsString;
+    /**
+     * Build system runnable from pre-built instructions string.
+     * Only called when content has actually changed.
+     */
+    private buildSystemRunnable;
     /**
      * Reset context for a new run
      */
@@ -91,4 +129,26 @@ export declare class AgentContext {
      * Note: System message tokens are calculated during systemRunnable creation
      */
     calculateInstructionTokens(tokenCounter: t.TokenCounter): Promise<void>;
+    /**
+     * Gets the tool registry for deferred tools (for tool search).
+     * @param onlyDeferred If true, only returns tools with defer_loading=true
+     * @returns LCToolRegistry with tool definitions
+     */
+    getDeferredToolRegistry(onlyDeferred?: boolean): t.LCToolRegistry;
+    /**
+     * Marks tools as discovered via tool search.
+     * Discovered tools will be included in the next model binding.
+     * Only marks system runnable stale if NEW tools were actually added.
+     * @param toolNames - Array of discovered tool names
+     * @returns true if any new tools were discovered
+     */
+    markToolsAsDiscovered(toolNames: string[]): boolean;
+    /**
+     * Gets tools that should be bound to the LLM.
+     * Includes:
+     * 1. Non-deferred tools with allowed_callers: ['direct']
+     * 2. Discovered tools (from tool search)
+     * @returns Array of tools to bind to model
+     */
+    getToolsForBinding(): t.GraphTools | undefined;
 }

package/dist/types/common/enum.d.ts

@@ -114,6 +114,8 @@ export declare enum Callback {
 export declare enum Constants {
     OFFICIAL_CODE_BASEURL = "https://api.illuma.ai/v1",
     EXECUTE_CODE = "execute_code",
+    TOOL_SEARCH_REGEX = "tool_search_regex",
+    PROGRAMMATIC_TOOL_CALLING = "run_tools_with_code",
     WEB_SEARCH = "web_search",
     CONTENT_AND_ARTIFACT = "content_and_artifact",
     LC_TRANSFER_TO_ = "lc_transfer_to_"

package/dist/types/graphs/Graph.d.ts

@@ -91,9 +91,10 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
         instructions?: string;
         additional_instructions?: string;
     }): t.SystemRunnable | undefined;
-    initializeTools({ currentTools, currentToolMap, }: {
+    initializeTools({ currentTools, currentToolMap, agentContext, }: {
         currentTools?: t.GraphTools;
         currentToolMap?: t.ToolMap;
+        agentContext?: AgentContext;
     }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState>;
     initializeModel({ provider, tools, clientOptions, }: {
         provider: Providers;
@@ -109,7 +110,7 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     /** Execute model invocation with streaming support */
     private attemptInvoke;
     cleanupSignalListener(currentModel?: t.ChatModel): void;
-    createCallModel(agentId?: string, currentModel?: t.ChatModel): (state: t.BaseGraphState, config?: RunnableConfig) => Promise<Partial<t.BaseGraphState>>;
+    createCallModel(agentId?: string): (state: t.BaseGraphState, config?: RunnableConfig) => Promise<Partial<t.BaseGraphState>>;
     createAgentNode(agentId: string): t.CompiledAgentWorfklow;
     createWorkflow(): t.CompiledStateWorkflow;
     /**

package/dist/types/index.d.ts

@@ -6,6 +6,8 @@ export * from './messages';
 export * from './graphs';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/ProgrammaticToolCalling';
+export * from './tools/ToolSearchRegex';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './common';

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

@@ -21,7 +21,7 @@ export declare class CustomAnthropic extends ChatAnthropicMessages {
     private emitted_usage?;
     top_k: number | undefined;
     constructor(fields?: CustomAnthropicInput);
-    static lc_name(): 'IllumaAnthropic';
+    static lc_name(): 'LibreChatAnthropic';
     /**
      * Get the parameters used to invoke the model
      */

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

@@ -1,5 +1,6 @@
 /**
  * Optimized ChatBedrockConverse wrapper that fixes contentBlockIndex conflicts
+ * and adds prompt caching support for Bedrock Converse API.
  *
  * Bedrock sends the same contentBlockIndex for both text and tool_use content blocks,
  * causing LangChain's merge logic to fail with "field[contentBlockIndex] already exists"
@@ -9,19 +10,45 @@
  * The contentBlockIndex field is only used internally by Bedrock's streaming protocol
  * and isn't needed by application logic - the index field on tool_call_chunks serves
  * the purpose of tracking tool call ordering.
+ *
+ * PROMPT CACHING:
+ * When promptCache: true is set, this wrapper adds cachePoint markers to the tools array
+ * to enable Bedrock prompt caching for tool definitions. This allows tool schemas to be
+ * cached and reused across requests, reducing latency and costs.
+ *
+ * CACHE TOKEN EXTRACTION:
+ * LangChain AWS doesn't extract cacheReadInputTokens/cacheWriteInputTokens from Bedrock's
+ * response. This wrapper adds input_token_details to usage_metadata with cache information.
  */
 import { ChatBedrockConverse } from '@langchain/aws';
 import type { ChatBedrockConverseInput } from '@langchain/aws';
 import type { BaseMessage } from '@langchain/core/messages';
 import { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+/** Extended input type with promptCache option */
+export interface CustomChatBedrockConverseInput extends ChatBedrockConverseInput {
+    promptCache?: boolean;
+}
 export declare class CustomChatBedrockConverse extends ChatBedrockConverse {
-    constructor(fields?: ChatBedrockConverseInput);
+    promptCache: boolean;
+    constructor(fields?: CustomChatBedrockConverseInput);
     static lc_name(): string;
     /**
-     * Override _streamResponseChunks to strip contentBlockIndex from response_metadata
-     * This prevents LangChain's merge conflicts when the same index is used for
-     * different content types (text vs tool calls)
+     * Override invocationParams to add cachePoint to tools when promptCache is enabled.
+     * This enables Bedrock prompt caching for tool definitions.
+     *
+     * STRATEGY: Separate cachePoints for core tools and MCP tools
+     * - Core tools (web_search, execute_code, etc.) are stable → cache first
+     * - MCP tools (have '_mcp_' in name) are dynamic → cache separately after
+     * - This allows core tools to stay cached when MCP selection changes
+     *
+     * NOTE: Only Claude models support cachePoint - Nova and other models will reject it.
+     */
+    invocationParams(options?: this['ParsedCallOptions']): ReturnType<ChatBedrockConverse['invocationParams']>;
+    /**
+     * Override _streamResponseChunks to:
+     * 1. Strip contentBlockIndex from response_metadata to prevent merge conflicts
+     * 2. Extract cacheReadInputTokens/cacheWriteInputTokens and add to usage_metadata
      */
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
     /**

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

@@ -12,7 +12,7 @@ export declare class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI
      */
     get _isMultimodalModel(): boolean;
     constructor(fields: GoogleClientOptions);
-    static lc_name(): 'IllumaGoogleGenerativeAI';
+    static lc_name(): 'LibreChatGoogleGenerativeAI';
     /**
      * Helper function to convert Gemini API usage metadata to LangChain format
      * Includes support for cached tokens and tier-based tracking for gemini-3-pro-preview

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

@@ -63,7 +63,7 @@ export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
         _lc_stream_delay?: number;
     });
     get exposedClient(): CustomOpenAIClient;
-    static lc_name(): 'IllumaAzureOpenAI';
+    static lc_name(): 'LibreChatAzureOpenAI';
     /**
      * Returns backwards compatible reasoning parameters from constructor params and call options
      * @internal
@@ -75,7 +75,7 @@ export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
 }
 export declare class ChatDeepSeek extends OriginalChatDeepSeek {
     get exposedClient(): CustomOpenAIClient;
-    static lc_name(): 'IllumaDeepSeek';
+    static lc_name(): 'LibreChatDeepSeek';
     protected _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
 }
@@ -106,7 +106,7 @@ export declare class ChatXAI extends OriginalChatXAI {
         };
         _lc_stream_delay?: number;
     });
-    static lc_name(): 'IllumaXAI';
+    static lc_name(): 'LibreChatXAI';
     get exposedClient(): CustomOpenAIClient;
     protected _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
     _streamResponseChunks(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;

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

@@ -9,7 +9,7 @@ export interface ChatOpenRouterCallOptions extends ChatOpenAICallOptions {
 }
 export declare class ChatOpenRouter extends ChatOpenAI {
     constructor(_fields: Partial<ChatOpenRouterCallOptions>);
-    static lc_name(): 'IllumaOpenRouter';
+    static lc_name(): 'LibreChatOpenRouter';
     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>;
 }

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

@@ -23,14 +23,29 @@ export declare function stripAnthropicCacheControl<T extends MessageWithContent>
  */
 export declare function stripBedrockCacheControl<T extends MessageWithContent>(messages: T[]): T[];
 /**
- * Adds Bedrock Converse API cache points to the last two messages.
- * Inserts `{ cachePoint: { type: 'default' } }` as a separate content block
- * immediately after the last text block in each targeted message.
- * Strips ALL existing cache control (both Bedrock and Anthropic formats) from all messages,
- * then adds fresh cache points to the last 2 messages in a single backward pass.
- * This ensures we don't accumulate stale cache points across multiple turns.
- * @param messages - The array of message objects.
- * @returns - The updated array of message objects with cache points added.
+ * Adds Bedrock Converse API cache points using "Stable Prefix Caching" strategy.
+ *
+ * STRATEGY: Place cache point after the LAST ASSISTANT message only.
+ * This ensures the prefix (everything before the cache point) remains STABLE
+ * as the conversation grows, maximizing cache hits.
+ *
+ * Why this works:
+ * - System message has its own cachePoint (added in AgentContext)
+ * - Tools have their own cachePoint (added in CustomChatBedrockConverse)
+ * - Conversation history grows, but the PREFIX stays the same
+ * - Only the NEW user message is uncached (it's always different)
+ *
+ * Example conversation flow:
+ * Request 1: [System+cachePoint][Tools+cachePoint][User1] → No conversation cache yet
+ * Request 2: [System][Tools][User1][Assistant1+cachePoint][User2] → Cache User1+Assistant1
+ * Request 3: [System][Tools][User1][Assistant1][User2][Assistant2+cachePoint][User3]
+ *            → Cache reads User1+A1+User2+A2, cache writes new portion
+ *
+ * Claude's "Simplified Cache Management" automatically looks back up to 20 content
+ * blocks from the cache checkpoint to find the longest matching prefix.
+ *
+ * @param messages - The array of message objects (excluding system message).
+ * @returns - The updated array with a single cache point after the last assistant message.
  */
 export declare function addBedrockCacheControl<T extends Partial<BaseMessage> & MessageWithContent>(messages: T[]): T[];
 export {};

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

@@ -4,3 +4,4 @@ export * from './prune';
 export * from './format';
 export * from './cache';
 export * from './content';
+export * from './tools';

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

@@ -0,0 +1,17 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Extracts discovered tool names from tool search results in the current turn.
+ * Only processes tool search messages after the latest AI message with tool calls.
+ *
+ * Similar pattern to formatArtifactPayload - finds relevant messages efficiently
+ * by identifying the latest AI parent and only processing subsequent tool messages.
+ *
+ * @param messages - All messages in the conversation
+ * @returns Array of discovered tool names (empty if no new discoveries)
+ */
+export declare function extractToolDiscoveries(messages: BaseMessage[]): string[];
+/**
+ * Checks if the current turn has any tool search results.
+ * Quick check to avoid full extraction when not needed.
+ */
+export declare function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean;

package/dist/types/test/mockTools.d.ts

@@ -0,0 +1,28 @@
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import type { LCToolRegistry } from '@/types';
+/**
+ * Mock get_team_members tool - returns list of team members
+ */
+export declare function createGetTeamMembersTool(): StructuredToolInterface;
+/**
+ * Mock get_expenses tool - returns expense records for a user
+ */
+export declare function createGetExpensesTool(): StructuredToolInterface;
+/**
+ * Mock get_weather tool - returns weather data for a city
+ */
+export declare function createGetWeatherTool(): StructuredToolInterface;
+/**
+ * Mock calculator tool - evaluates mathematical expressions
+ */
+export declare function createCalculatorTool(): StructuredToolInterface;
+/**
+ * Creates a tool registry for programmatic tool calling tests.
+ * Tools are configured with allowed_callers to demonstrate classification.
+ */
+export declare function createProgrammaticToolRegistry(): LCToolRegistry;
+/**
+ * Creates a sample tool registry for tool search tests.
+ * Includes mix of deferred and non-deferred tools.
+ */
+export declare function createToolSearchToolRegistry(): LCToolRegistry;

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

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+declare const ProgrammaticToolCallingSchema: z.ZodObject<{
+    code: z.ZodString;
+    session_id: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    timeout: number;
+    session_id?: string | undefined;
+}, {
+    code: string;
+    timeout?: number | undefined;
+    session_id?: string | undefined;
+}>;
+/**
+ * Normalizes a tool name to Python identifier format.
+ * Must match the Code API's `normalizePythonFunctionName` exactly:
+ * 1. Replace hyphens and spaces with underscores
+ * 2. Remove any other invalid characters
+ * 3. Prefix with underscore if starts with number
+ * 4. Append `_tool` if it's a Python keyword
+ * @param name - The tool name to normalize
+ * @returns Normalized Python-safe identifier
+ */
+export declare function normalizeToPythonIdentifier(name: string): string;
+/**
+ * Extracts tool names that are actually called in the Python code.
+ * Handles hyphen/underscore conversion since Python identifiers use underscores.
+ * @param code - The Python code to analyze
+ * @param toolNameMap - Map from normalized Python name to original tool name
+ * @returns Set of original tool names found in the code
+ */
+export declare function extractUsedToolNames(code: string, toolNameMap: Map<string, string>): Set<string>;
+/**
+ * Filters tool definitions to only include tools actually used in the code.
+ * Handles the hyphen-to-underscore conversion for Python compatibility.
+ * @param toolDefs - All available tool definitions
+ * @param code - The Python code to analyze
+ * @param debug - Enable debug logging
+ * @returns Filtered array of tool definitions
+ */
+export declare function filterToolsByUsage(toolDefs: t.LCTool[], code: string, debug?: boolean): t.LCTool[];
+/**
+ * Makes an HTTP request to the Code API.
+ * @param endpoint - The API endpoint URL
+ * @param apiKey - The API key for authentication
+ * @param body - The request body
+ * @param proxy - Optional HTTP proxy URL
+ * @returns The parsed API response
+ */
+export declare function makeRequest(endpoint: string, apiKey: string, body: Record<string, unknown>, proxy?: string): Promise<t.ProgrammaticExecutionResponse>;
+/**
+ * Executes tools in parallel when requested by the API.
+ * Uses Promise.all for parallel execution, catching individual errors.
+ * @param toolCalls - Array of tool calls from the API
+ * @param toolMap - Map of tool names to executable tools
+ * @returns Array of tool results
+ */
+export declare function executeTools(toolCalls: t.PTCToolCall[], toolMap: t.ToolMap): Promise<t.PTCToolResult[]>;
+/**
+ * Formats the completed response for the agent.
+ * @param response - The completed API response
+ * @returns Tuple of [formatted string, artifact]
+ */
+export declare function formatCompletedResponse(response: t.ProgrammaticExecutionResponse): [string, t.ProgrammaticExecutionArtifact];
+/**
+ * Creates a Programmatic Tool Calling tool for complex multi-tool workflows.
+ *
+ * This tool enables AI agents to write Python code that orchestrates multiple
+ * tool calls programmatically, reducing LLM round-trips and token usage.
+ *
+ * The tool map must be provided at runtime via config.configurable.toolMap.
+ *
+ * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)
+ * @returns A LangChain DynamicStructuredTool for programmatic tool calling
+ *
+ * @example
+ * const ptcTool = createProgrammaticToolCallingTool({
+ *   apiKey: process.env.CODE_API_KEY,
+ *   maxRoundTrips: 20
+ * });
+ *
+ * const [output, artifact] = await ptcTool.invoke(
+ *   { code, tools },
+ *   { configurable: { toolMap } }
+ * );
+ */
+export declare function createProgrammaticToolCallingTool(initParams?: t.ProgrammaticToolCallingParams): DynamicStructuredTool<typeof ProgrammaticToolCallingSchema>;
+export {};

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

@@ -5,7 +5,6 @@ import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
 export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
-    tools: t.GenericTool[];
     private toolMap;
     private loadRuntimeTools?;
     handleToolErrors: boolean;
@@ -13,7 +12,16 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
     private toolUsageCount;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, }: t.ToolNodeConstructorParams);
+    /** Tool registry for filtering (lazy computation of programmatic maps) */
+    private toolRegistry?;
+    /** Cached programmatic tools (computed once on first PTC call) */
+    private programmaticCache?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, }: t.ToolNodeConstructorParams);
+    /**
+     * Returns cached programmatic tools, computing once on first access.
+     * Single iteration builds both toolMap and toolDefs simultaneously.
+     */
+    private getProgrammaticTools;
     /**
      * Returns a snapshot of the current tool usage counts.
      * @returns A ReadonlyMap where keys are tool names and values are their usage counts.

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

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+declare const ToolSearchRegexSchema: z.ZodObject<{
+    query: z.ZodString;
+    fields: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<["name", "description", "parameters"]>, "many">>>;
+    max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    fields: ("name" | "description" | "parameters")[];
+    max_results: number;
+}, {
+    query: string;
+    fields?: ("name" | "description" | "parameters")[] | undefined;
+    max_results?: number | undefined;
+}>;
+/**
+ * Escapes special regex characters in a string to use as a literal pattern.
+ * @param pattern - The string to escape
+ * @returns The escaped string safe for use in a RegExp
+ */
+declare function escapeRegexSpecialChars(pattern: string): string;
+/**
+ * Counts the maximum nesting depth of groups in a regex pattern.
+ * @param pattern - The regex pattern to analyze
+ * @returns The maximum nesting depth
+ */
+declare function countNestedGroups(pattern: string): number;
+/**
+ * Detects nested quantifiers that can cause catastrophic backtracking.
+ * Patterns like (a+)+, (a*)*, (a+)*, etc.
+ * @param pattern - The regex pattern to check
+ * @returns True if nested quantifiers are detected
+ */
+declare function hasNestedQuantifiers(pattern: string): boolean;
+/**
+ * Checks if a regex pattern contains potentially dangerous constructs.
+ * @param pattern - The regex pattern to validate
+ * @returns True if the pattern is dangerous
+ */
+declare function isDangerousPattern(pattern: string): boolean;
+/**
+ * Sanitizes a regex pattern for safe execution.
+ * If the pattern is dangerous, it will be escaped to a literal string search.
+ * @param pattern - The regex pattern to sanitize
+ * @returns Object containing the safe pattern and whether it was escaped
+ */
+declare function sanitizeRegex(pattern: string): {
+    safe: string;
+    wasEscaped: boolean;
+};
+/**
+ * Creates a Tool Search Regex tool for discovering tools from a large registry.
+ *
+ * This tool enables AI agents to dynamically discover tools from a large library
+ * without loading all tool definitions into the LLM context window. The agent
+ * can search for relevant tools on-demand using regex patterns.
+ *
+ * The tool registry can be provided either:
+ * 1. At initialization time via params.toolRegistry
+ * 2. At runtime via config.configurable.toolRegistry when invoking
+ *
+ * @param params - Configuration parameters for the tool (toolRegistry is optional)
+ * @returns A LangChain DynamicStructuredTool for tool searching
+ *
+ * @example
+ * // Option 1: Registry at initialization
+ * const tool = createToolSearchRegexTool({ apiKey, toolRegistry });
+ * await tool.invoke({ query: 'expense' });
+ *
+ * @example
+ * // Option 2: Registry at runtime
+ * const tool = createToolSearchRegexTool({ apiKey });
+ * await tool.invoke(
+ *   { query: 'expense' },
+ *   { configurable: { toolRegistry, onlyDeferred: true } }
+ * );
+ */
+declare function createToolSearchRegexTool(initParams?: t.ToolSearchRegexParams): DynamicStructuredTool<typeof ToolSearchRegexSchema>;
+export { createToolSearchRegexTool, sanitizeRegex, escapeRegexSpecialChars, isDangerousPattern, countNestedGroups, hasNestedQuantifiers, };

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

@@ -4,7 +4,7 @@ import type { BaseMessage, AIMessageChunk, SystemMessage } from '@langchain/core
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { ToolMap, ToolEndEvent, GenericTool } from '@/types/tools';
+import type { ToolMap, ToolEndEvent, GenericTool, LCTool } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -248,4 +248,10 @@ export interface AgentInputs {
     reasoningKey?: 'reasoning_content' | 'reasoning';
     /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
     useLegacyContent?: boolean;
+    /**
+     * Tool definitions for all tools, including deferred and programmatic.
+     * Used for tool search and programmatic tool calling.
+     * Maps tool name to LCTool definition.
+     */
+    toolRegistry?: Map<string, LCTool>;
 }