illuma-agents 1.0.36 → 1.0.38

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

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+/** Zod schema type for tool search parameters */
+type ToolSearchSchema = z.ZodObject<{
+    query: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    fields: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodEnum<['name', 'description', 'parameters']>>>>;
+    max_results: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    mcp_server: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>>;
+}>;
+/**
+ * Creates the Zod schema with dynamic query description based on mode.
+ * @param mode - The search mode determining query interpretation
+ * @returns Zod schema for tool search parameters
+ */
+declare function createToolSearchSchema(mode: t.ToolSearchMode): ToolSearchSchema;
+/**
+ * Extracts the MCP server name from a tool name.
+ * MCP tools follow the pattern: toolName_mcp_serverName
+ * @param toolName - The full tool name
+ * @returns The server name if it's an MCP tool, undefined otherwise
+ */
+declare function extractMcpServerName(toolName: string): string | undefined;
+/**
+ * Checks if a tool belongs to a specific MCP server.
+ * @param toolName - The full tool name
+ * @param serverName - The server name to match
+ * @returns True if the tool belongs to the specified server
+ */
+declare function isFromMcpServer(toolName: string, serverName: string): boolean;
+/**
+ * Checks if a tool belongs to any of the specified MCP servers.
+ * @param toolName - The full tool name
+ * @param serverNames - Array of server names to match
+ * @returns True if the tool belongs to any of the specified servers
+ */
+declare function isFromAnyMcpServer(toolName: string, serverNames: string[]): boolean;
+/**
+ * Normalizes server filter input to always be an array.
+ * @param serverFilter - String, array of strings, or undefined
+ * @returns Array of server names (empty if none specified)
+ */
+declare function normalizeServerFilter(serverFilter: string | string[] | undefined): string[];
+/**
+ * Extracts all unique MCP server names from a tool registry.
+ * @param toolRegistry - The tool registry to scan
+ * @param onlyDeferred - If true, only considers deferred tools
+ * @returns Array of unique server names, sorted alphabetically
+ */
+declare function getAvailableMcpServers(toolRegistry: t.LCToolRegistry | undefined, onlyDeferred?: boolean): string[];
+/**
+ * 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;
+};
+/**
+ * Performs BM25-based search for better relevance ranking.
+ * Uses Okapi BM25 algorithm for term frequency and document length normalization.
+ * @param tools - Array of tool metadata to search
+ * @param query - The search query
+ * @param fields - Which fields to search
+ * @param maxResults - Maximum results to return
+ * @returns Search response with matching tools ranked by BM25 score
+ */
+declare function performLocalSearch(tools: t.ToolMetadata[], query: string, fields: string[], maxResults: number): t.ToolSearchResponse;
+/**
+ * Extracts the base tool name (without MCP server suffix) from a full tool name.
+ * @param toolName - The full tool name
+ * @returns The base tool name without server suffix
+ */
+declare function getBaseToolName(toolName: string): string;
+/**
+ * Generates a compact listing of deferred tools grouped by server.
+ * Format: "server: tool1, tool2, tool3"
+ * Non-MCP tools are grouped under "other".
+ * @param toolRegistry - The tool registry
+ * @param onlyDeferred - Whether to only include deferred tools
+ * @returns Formatted string with tools grouped by server
+ */
+declare function getDeferredToolsListing(toolRegistry: t.LCToolRegistry | undefined, onlyDeferred: boolean): string;
+/**
+ * Formats a server listing response as structured JSON.
+ * NOTE: This is a PREVIEW only - tools are NOT discovered/loaded.
+ * @param tools - Array of tool metadata from the server(s)
+ * @param serverNames - The MCP server name(s)
+ * @returns JSON string showing all tools grouped by server
+ */
+declare function formatServerListing(tools: t.ToolMetadata[], serverNames: string | string[]): string;
+/**
+ * Creates a Tool Search 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.
+ *
+ * **Modes:**
+ * - `code_interpreter` (default): Uses external sandbox for regex search. Safer for complex patterns.
+ * - `local`: Uses safe substring matching locally. No network call, faster, completely safe from ReDoS.
+ *
+ * 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: Code interpreter mode (regex via sandbox)
+ * const tool = createToolSearch({ apiKey, toolRegistry });
+ * await tool.invoke({ query: 'expense.*report' });
+ *
+ * @example
+ * // Option 2: Local mode (safe substring search, no API key needed)
+ * const tool = createToolSearch({ mode: 'local', toolRegistry });
+ * await tool.invoke({ query: 'expense' });
+ */
+declare function createToolSearch(initParams?: t.ToolSearchParams): DynamicStructuredTool<ReturnType<typeof createToolSearchSchema>>;
+export { createToolSearch, performLocalSearch, extractMcpServerName, isFromMcpServer, isFromAnyMcpServer, normalizeServerFilter, getAvailableMcpServers, getDeferredToolsListing, getBaseToolName, formatServerListing, sanitizeRegex, escapeRegexSpecialChars, isDangerousPattern, countNestedGroups, hasNestedQuantifiers, };

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

@@ -236,6 +236,8 @@ export type MultiAgentGraphInput = StandardGraphInput & {
 };
 export interface AgentInputs {
     agentId: string;
+    /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
+    name?: string;
     toolEnd?: boolean;
     toolMap?: ToolMap;
     tools?: GraphTools;

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

@@ -37,7 +37,9 @@ export type AnthropicReasoning = {
     thinkingBudget?: number;
 };
 export type OpenAIClientOptions = ChatOpenAIFields;
-export type AnthropicClientOptions = AnthropicInput;
+export type AnthropicClientOptions = AnthropicInput & {
+    promptCache?: boolean;
+};
 export type MistralAIClientOptions = ChatMistralAIInput;
 export type VertexAIClientOptions = ChatVertexAIInput & {
     includeThoughts?: boolean;

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

@@ -29,6 +29,8 @@ export type ToolNodeOptions = {
     errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<void>;
     /** Tool registry for lazy computation of programmatic tools and tool search */
     toolRegistry?: LCToolRegistry;
+    /** Reference to Graph's sessions map for automatic session injection */
+    sessions?: ToolSessionMap;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -55,6 +57,8 @@ export type FileRef = {
     id: string;
     name: string;
     path?: string;
+    /** Session ID this file belongs to (for multi-session file tracking) */
+    session_id?: string;
 };
 export type FileRefs = FileRef[];
 export type ExecuteResult = {
@@ -99,12 +103,18 @@ export type ProgrammaticCache = {
     toolMap: ToolMap;
     toolDefs: LCTool[];
 };
-/** Parameters for creating a Tool Search Regex tool */
-export type ToolSearchRegexParams = {
+/** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
+export type ToolSearchMode = 'code_interpreter' | 'local';
+/** Parameters for creating a Tool Search tool */
+export type ToolSearchParams = {
     apiKey?: string;
     toolRegistry?: LCToolRegistry;
     onlyDeferred?: boolean;
     baseUrl?: string;
+    /** Search mode: 'code_interpreter' (default) uses sandbox for regex, 'local' uses safe substring matching */
+    mode?: ToolSearchMode;
+    /** Filter tools to only those from specific MCP server(s). Can be a single name or array of names. */
+    mcpServer?: string | string[];
     [key: string]: unknown;
 };
 /** Simplified tool metadata for search purposes */
@@ -199,3 +209,33 @@ export type ProgrammaticToolCallingParams = {
     /** Environment variable key for API key */
     [key: string]: unknown;
 };
+/**
+ * Tracks code execution session state for automatic file persistence.
+ * Stored in Graph.sessions and injected into subsequent tool invocations.
+ */
+export type CodeSessionContext = {
+    /** Session ID from the code execution environment */
+    session_id: string;
+    /** Files generated in this session (for context/tracking) */
+    files: FileRefs;
+    /** Timestamp of last update */
+    lastUpdated: number;
+};
+/**
+ * Artifact structure returned by code execution tools (CodeExecutor, PTC).
+ * Used to extract session context after tool completion.
+ */
+export type CodeExecutionArtifact = {
+    session_id?: string;
+    files?: FileRefs;
+};
+/**
+ * Generic session context union type for different tool types.
+ * Extend this as new tool session types are added.
+ */
+export type ToolSessionContext = CodeSessionContext;
+/**
+ * Map of tool names to their session contexts.
+ * Keys are tool constants (e.g., Constants.EXECUTE_CODE, Constants.PROGRAMMATIC_TOOL_CALLING).
+ */
+export type ToolSessionMap = Map<string, ToolSessionContext>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.36",
+  "version": "1.0.38",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -44,14 +44,17 @@
     "code_exec": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "image": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/image.ts --provider 'google' --name 'Jo' --location 'New York, NY'",
     "code_exec_files": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_files.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "code_exec_simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_simple.ts --provider 'google' --name 'Jo' --location 'New York, NY'",
-    "simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/simple.ts --provider 'openrouter' --name 'Jo' --location 'New York, NY'",
+    "code_exec_session": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_session.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "code_exec_multi_session": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_multi_session.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "code_exec_simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_simple.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
+    "simple": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/simple.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
     "caching": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/caching.ts --name 'Jo' --location 'New York, NY'",
     "thinking": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/thinking.ts --name 'Jo' --location 'New York, NY'",
+    "thinking:bedrock": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/thinking-bedrock.ts --name 'Jo' --location 'New York, NY'",
     "memory": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/memory.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
-    "tool": "node --trace-warnings -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'openrouter' --name 'Jo' --location 'New York, NY'",
+    "tool": "node --trace-warnings -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
     "search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/search.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
-    "tool_search_regex": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search_regex.ts",
+    "tool_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search.ts",
     "programmatic_exec": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec.ts",
     "code_exec_ptc": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "programmatic_exec_agent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec_agent.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
@@ -69,6 +72,7 @@
     "multi-agent-sequence": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-sequence.ts",
     "multi-agent-conditional": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-conditional.ts",
     "multi-agent-supervisor": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-supervisor.ts",
+    "test-handoff-preamble": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-handoff-preamble.ts",
     "multi-agent-list-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-multi-agent-list-handoff.ts",
     "test-parallel-agent-labeling": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-parallel-agent-labeling.ts",
     "test-thinking-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-thinking-handoff.ts",
@@ -102,6 +106,7 @@
     }
   },
   "dependencies": {
+    "@aws-sdk/client-bedrock-runtime": "^3.970.0",
     "@langchain/anthropic": "^0.3.26",
     "@langchain/aws": "^0.1.15",
     "@langchain/core": "^0.3.80",
@@ -124,6 +129,7 @@
     "https-proxy-agent": "^7.0.6",
     "mathjs": "^15.1.0",
     "nanoid": "^3.3.7",
+    "okapibm25": "^1.4.1",
     "openai": "5.8.2"
   },
   "imports": {
@@ -151,6 +157,7 @@
     "eslint-plugin-import": "^2.31.0",
     "husky": "^9.1.7",
     "jest": "^30.2.0",
+    "jest-util": "^30.2.0",
     "lint-staged": "^15.2.7",
     "prettier": "^3.6.2",
     "rollup": "^4.34.6",

package/src/agents/AgentContext.ts

@@ -27,6 +27,7 @@ export class AgentContext {
   ): AgentContext {
     const {
       agentId,
+      name,
       provider,
       clientOptions,
       tools,
@@ -44,6 +45,7 @@ export class AgentContext {
 
     const agentContext = new AgentContext({
       agentId,
+      name: name ?? agentId,
       provider,
       clientOptions,
       maxContextTokens,
@@ -87,6 +89,8 @@ export class AgentContext {
 
   /** Agent identifier */
   agentId: string;
+  /** Human-readable name for this agent (used in handoff context). Falls back to agentId if not provided. */
+  name?: string;
   /** Provider for this specific agent */
   provider: Providers;
   /** Client options for this agent */
@@ -173,9 +177,20 @@ export class AgentContext {
       artifacts: 0,
       memory: 0,
     };
+  /**
+   * Handoff context when this agent receives control via handoff.
+   * Contains source and parallel execution info for system message context.
+   */
+  handoffContext?: {
+    /** Source agent that transferred control */
+    sourceAgentName: string;
+    /** Names of sibling agents executing in parallel (empty if sequential) */
+    parallelSiblings: string[];
+  };
 
   constructor({
     agentId,
+    name,
     provider,
     clientOptions,
     maxContextTokens,
@@ -193,6 +208,7 @@ export class AgentContext {
     useLegacyContent,
   }: {
     agentId: string;
+    name?: string;
     provider: Providers;
     clientOptions?: t.ClientOptions;
     maxContextTokens?: number;
@@ -210,6 +226,7 @@ export class AgentContext {
     useLegacyContent?: boolean;
   }) {
     this.agentId = agentId;
+    this.name = name;
     this.provider = provider;
     this.clientOptions = clientOptions;
     this.maxContextTokens = maxContextTokens;
@@ -324,27 +341,65 @@ export class AgentContext {
 
   /**
    * Builds the raw instructions string (without creating SystemMessage).
+   * Includes agent identity preamble and handoff context when available.
    */
   private buildInstructionsString(): string {
-    let result = this.instructions ?? '';
+    const parts: string[] = [];
+
+    /** Build agent identity and handoff context preamble */
+    const identityPreamble = this.buildIdentityPreamble();
+    if (identityPreamble) {
+      parts.push(identityPreamble);
+    }
 
+    /** Add main instructions */
+    if (this.instructions != null && this.instructions !== '') {
+      parts.push(this.instructions);
+    }
+
+    /** Add additional instructions */
     if (
       this.additionalInstructions != null &&
       this.additionalInstructions !== ''
     ) {
-      result = result
-        ? `${result}\n\n${this.additionalInstructions}`
-        : this.additionalInstructions;
+      parts.push(this.additionalInstructions);
     }
 
+    /** Add programmatic tools documentation */
     const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
     if (programmaticToolsDoc) {
-      result = result
-        ? `${result}${programmaticToolsDoc}`
-        : programmaticToolsDoc;
+      parts.push(programmaticToolsDoc);
+    }
+
+    return parts.join('\n\n');
+  }
+
+  /**
+   * Builds the agent identity preamble including handoff context if present.
+   * This helps the agent understand its role in the multi-agent workflow.
+   */
+  private buildIdentityPreamble(): string {
+    if (!this.handoffContext) return '';
+
+    const displayName = this.name ?? this.agentId;
+    const { sourceAgentName, parallelSiblings } = this.handoffContext;
+    const isParallel = parallelSiblings.length > 0;
+
+    const lines: string[] = [];
+    lines.push('## Multi-Agent Workflow');
+    lines.push(
+      `You are "${displayName}", transferred from "${sourceAgentName}".`
+    );
+
+    if (isParallel) {
+      lines.push(`Running in parallel with: ${parallelSiblings.join(', ')}.`);
     }
 
-    return result;
+    lines.push(
+      'Execute only tasks relevant to your role. Routing is already handled if requested, unless you can route further.'
+    );
+
+    return lines.join('\n');
   }
 
   /**
@@ -374,14 +429,7 @@ export class AgentContext {
       const anthropicOptions = this.clientOptions as
         | t.AnthropicClientOptions
         | undefined;
-      const defaultHeaders = anthropicOptions?.clientOptions?.defaultHeaders as
-        | Record<string, string>
-        | undefined;
-      const anthropicBeta = defaultHeaders?.['anthropic-beta'];
-      if (
-        typeof anthropicBeta === 'string' &&
-        anthropicBeta.includes('prompt-caching')
-      ) {
+      if (anthropicOptions?.promptCache === true) {
         finalInstructions = {
           content: [
             {
@@ -455,6 +503,7 @@ export class AgentContext {
     this.tokenTypeSwitch = undefined;
     this.currentTokenType = ContentTypes.TEXT;
     this.discoveredToolNames.clear();
+    this.handoffContext = undefined;
   }
 
   /**
@@ -626,6 +675,29 @@ export class AgentContext {
     return registry;
   }
 
+  /**
+   * Sets the handoff context for this agent.
+   * Call this when the agent receives control via handoff from another agent.
+   * Marks system runnable as stale to include handoff context in system message.
+   * @param sourceAgentName - Name of the agent that transferred control
+   * @param parallelSiblings - Names of other agents executing in parallel with this one
+   */
+  setHandoffContext(sourceAgentName: string, parallelSiblings: string[]): void {
+    this.handoffContext = { sourceAgentName, parallelSiblings };
+    this.systemRunnableStale = true;
+  }
+
+  /**
+   * Clears any handoff context.
+   * Call this when resetting the agent or when handoff context is no longer relevant.
+   */
+  clearHandoffContext(): void {
+    if (this.handoffContext) {
+      this.handoffContext = undefined;
+      this.systemRunnableStale = true;
+    }
+  }
+
   /**
    * Marks tools as discovered via tool search.
    * Discovered tools will be included in the next model binding.

package/src/common/enum.ts

@@ -161,11 +161,13 @@ export enum Callback {
 export enum Constants {
   OFFICIAL_CODE_BASEURL = 'https://api.illuma.ai/v1',
   EXECUTE_CODE = 'execute_code',
-  TOOL_SEARCH_REGEX = 'tool_search_regex',
+  TOOL_SEARCH = 'tool_search',
   PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',
   WEB_SEARCH = 'web_search',
   CONTENT_AND_ARTIFACT = 'content_and_artifact',
   LC_TRANSFER_TO_ = 'lc_transfer_to_',
+  /** Delimiter for MCP tools: toolName_mcp_serverName */
+  MCP_DELIMITER = '_mcp_',
 }
 
 export enum TitleMethod {

package/src/graphs/Graph.ts

@@ -37,6 +37,7 @@ import {
   Providers,
   StepTypes,
   MessageTypes,
+  Constants,
 } from '@/common';
 import {
   formatAnthropicArtifactContent,
@@ -141,6 +142,12 @@ export abstract class Graph<
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
+  /**
+   * Tool session contexts for automatic state persistence across tool invocations.
+   * Keyed by tool name (e.g., Constants.EXECUTE_CODE).
+   * Currently supports code execution session tracking (session_id, files).
+   */
+  sessions: t.ToolSessionMap = new Map();
 }
 
 export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
@@ -487,11 +494,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       finalInstructions != null &&
       finalInstructions &&
       provider === Providers.ANTHROPIC &&
-      ((
-        (clientOptions as t.AnthropicClientOptions).clientOptions
-          ?.defaultHeaders as Record<string, string> | undefined
-      )?.['anthropic-beta']?.includes('prompt-caching') ??
-        false)
+      (clientOptions as t.AnthropicClientOptions).promptCache === true
     ) {
       finalInstructions = {
         content: [
@@ -528,6 +531,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       errorHandler: (data, metadata) =>
         StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       toolRegistry: agentContext?.toolRegistry,
+      sessions: this.sessions,
     });
   }
 
@@ -860,14 +864,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         const anthropicOptions = agentContext.clientOptions as
           | t.AnthropicClientOptions
           | undefined;
-        const defaultHeaders = anthropicOptions?.clientOptions
-          ?.defaultHeaders as Record<string, string> | undefined;
-        const anthropicBeta = defaultHeaders?.['anthropic-beta'];
-
-        if (
-          typeof anthropicBeta === 'string' &&
-          anthropicBeta.includes('prompt-caching')
-        ) {
+        if (anthropicOptions?.promptCache === true) {
           finalMessages = addCacheControl<BaseMessage>(finalMessages);
         }
       } else if (agentContext.provider === Providers.BEDROCK) {
@@ -1366,6 +1363,60 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
       throw new Error(`No run step found for stepId ${stepId}`);
     }
 
+    /**
+     * Extract and store code execution session context from artifacts.
+     * Each file is stamped with its source session_id to support multi-session file tracking.
+     * When the same filename appears in a later execution, the newer version replaces the old.
+     */
+    const toolName = output.name;
+    if (
+      toolName === Constants.EXECUTE_CODE ||
+      toolName === Constants.PROGRAMMATIC_TOOL_CALLING
+    ) {
+      const artifact = output.artifact as t.CodeExecutionArtifact | undefined;
+      const newFiles = artifact?.files ?? [];
+      const hasNewFiles = newFiles.length > 0;
+
+      if (
+        hasNewFiles &&
+        artifact?.session_id != null &&
+        artifact.session_id !== ''
+      ) {
+        /**
+         * Stamp each new file with its source session_id.
+         * This enables files from different executions (parallel or sequential)
+         * to be tracked and passed to subsequent calls.
+         */
+        const filesWithSession: t.FileRefs = newFiles.map((file) => ({
+          ...file,
+          session_id: artifact.session_id,
+        }));
+
+        const existingSession = this.sessions.get(Constants.EXECUTE_CODE) as
+          | t.CodeSessionContext
+          | undefined;
+        const existingFiles = existingSession?.files ?? [];
+
+        /**
+         * Merge files, preferring latest versions by name.
+         * If a file with the same name exists, replace it with the new version.
+         * This handles cases where files are edited/recreated in subsequent executions.
+         */
+        const newFileNames = new Set(filesWithSession.map((f) => f.name));
+        const filteredExisting = existingFiles.filter(
+          (f) => !newFileNames.has(f.name)
+        );
+
+        this.sessions.set(Constants.EXECUTE_CODE, {
+          /** Keep latest session_id for reference/fallback */
+          session_id: artifact.session_id,
+          /** Accumulated files with latest versions preferred */
+          files: [...filteredExisting, ...filesWithSession],
+          lastUpdated: Date.now(),
+        });
+      }
+    }
+
     const dispatchedOutput =
       typeof output.content === 'string'
         ? output.content