illuma-agents 1.0.37 → 1.0.39

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

@@ -3,16 +3,13 @@ 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.

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

@@ -16,7 +16,9 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     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);
+    /** Reference to Graph's sessions map for automatic session injection */
+    private sessions?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, }: t.ToolNodeConstructorParams);
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.

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

@@ -27,6 +27,11 @@ export type SystemCallbacks = {
 };
 export type BaseGraphState = {
     messages: BaseMessage[];
+    /**
+     * Structured response when using structured output mode.
+     * Contains the validated JSON response conforming to the configured schema.
+     */
+    structuredResponse?: Record<string, unknown>;
 };
 export type MultiAgentGraphState = BaseGraphState & {
     agentMessages?: BaseMessage[];
@@ -234,8 +239,68 @@ export type GraphEdge = {
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];
 };
+/**
+ * Structured output mode determines how the agent returns structured data.
+ * - 'tool': Uses tool calling to return structured output (works with all tool-calling models)
+ * - 'provider': Uses provider-native structured output (OpenAI, Anthropic, etc.)
+ * - 'auto': Automatically selects the best strategy based on model capabilities
+ */
+export type StructuredOutputMode = 'tool' | 'provider' | 'auto';
+/**
+ * Configuration for structured JSON output from agents.
+ * When configured, the agent will return a validated JSON response
+ * instead of streaming text.
+ */
+export interface StructuredOutputConfig {
+    /**
+     * JSON Schema defining the output structure.
+     * The model will be forced to return data conforming to this schema.
+     */
+    schema: Record<string, unknown>;
+    /**
+     * Name for the structured output format (used in tool mode).
+     * @default 'StructuredResponse'
+     */
+    name?: string;
+    /**
+     * Description of what the structured output represents.
+     * Helps the model understand the expected format.
+     */
+    description?: string;
+    /**
+     * Output mode strategy.
+     * @default 'auto'
+     */
+    mode?: StructuredOutputMode;
+    /**
+     * Enable strict schema validation.
+     * When true, the response must exactly match the schema.
+     * @default true
+     */
+    strict?: boolean;
+    /**
+     * Error handling configuration.
+     * - true: Auto-retry on validation errors (default)
+     * - false: Throw error on validation failure
+     * - string: Custom error message for retry
+     */
+    handleErrors?: boolean | string;
+    /**
+     * Maximum number of retry attempts on validation failure.
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Include the raw AI message along with structured response.
+     * Useful for debugging.
+     * @default false
+     */
+    includeRaw?: boolean;
+}
 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;
@@ -261,4 +326,10 @@ export interface AgentInputs {
      * and can be cached by Bedrock/Anthropic prompt caching.
      */
     dynamicContext?: string;
+    /**
+     * Structured output configuration.
+     * When set, disables streaming and returns a validated JSON response
+     * conforming to the specified schema.
+     */
+    structuredOutput?: StructuredOutputConfig;
 }

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.37",
+  "version": "1.0.39",
   "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",
@@ -87,7 +91,7 @@
     "start:collab5": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/collab_design_v5.ts",
     "start:dev": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/main.ts",
     "supervised": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/supervised.ts --provider anthropic --name Jo --location \"New York, NY\"",
-    "test": "jest",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "test:memory": "NODE_OPTIONS='--expose-gc' npx jest src/specs/title.memory-leak.test.ts",
     "test:all": "npm test -- --testPathIgnorePatterns=title.memory-leak.test.ts && npm run test:memory",
     "reinstall": "npm run clean && npm ci && rm -rf ./dist && npm run build",
@@ -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",