illuma-agents 1.0.10 → 1.0.12

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

@@ -38,10 +38,23 @@ 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 */
     additionalInstructions?: string;
+    /**
+     * Dynamic context that changes per-request (e.g., current time, user info).
+     * This is NOT included in the system message to preserve cache.
+     * Instead, it's injected as a user message at the start of the conversation.
+     */
+    dynamicContext?: string;
     /** Reasoning key for this agent */
     reasoningKey: 'reasoning_content' | 'reasoning';
     /** Last token for reasoning detection */
@@ -52,13 +65,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, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
         agentId: string;
         provider: Providers;
         clientOptions?: t.ClientOptions;
@@ -67,17 +84,45 @@ export declare class AgentContext {
         tokenCounter?: t.TokenCounter;
         tools?: t.GraphTools;
         toolMap?: t.ToolMap;
+        toolRegistry?: t.LCToolRegistry;
         instructions?: string;
         additionalInstructions?: string;
+        dynamicContext?: string;
         reasoningKey?: 'reasoning_content' | 'reasoning';
         toolEnd?: boolean;
         instructionTokens?: number;
         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 buildInstructionsString;
+    /**
+     * Build system runnable from pre-built instructions string.
+     * Only called when content has actually changed.
      */
-    private createSystemRunnable;
+    private buildSystemRunnable;
     /**
      * Reset context for a new run
      */
@@ -91,4 +136,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/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/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,17 @@ 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>;
+    /**
+     * Dynamic context that changes per-request (e.g., current time, user info).
+     * This is injected as a user message rather than system prompt to preserve cache.
+     * Keeping this separate from instructions ensures the system message stays static
+     * and can be cached by Bedrock/Anthropic prompt caching.
+     */
+    dynamicContext?: string;
 }