illuma-agents 1.0.9 → 1.0.11

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>;
 }

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

@@ -25,6 +25,8 @@ export type ToolNodeOptions = {
     loadRuntimeTools?: ToolRefGenerator;
     toolCallStepIds?: Map<string, string>;
     errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<void>;
+    /** Tool registry for lazy computation of programmatic tools and tool search */
+    toolRegistry?: LCToolRegistry;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -59,3 +61,139 @@ export type ExecuteResult = {
     stderr: string;
     files?: FileRefs;
 };
+/** JSON Schema type definition for tool parameters */
+export type JsonSchemaType = {
+    type: 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'array' | 'object';
+    enum?: string[];
+    items?: JsonSchemaType;
+    properties?: Record<string, JsonSchemaType>;
+    required?: string[];
+    description?: string;
+    additionalProperties?: boolean | JsonSchemaType;
+};
+/**
+ * Specifies which contexts can invoke a tool (inspired by Anthropic's allowed_callers)
+ * - 'direct': Only callable directly by the LLM (default if omitted)
+ * - 'code_execution': Only callable from within programmatic code execution
+ */
+export type AllowedCaller = 'direct' | 'code_execution';
+/** Tool definition with optional deferred loading and caller restrictions */
+export type LCTool = {
+    name: string;
+    description?: string;
+    parameters?: JsonSchemaType;
+    /** When true, tool is not loaded into context initially (for tool search) */
+    defer_loading?: boolean;
+    /**
+     * Which contexts can invoke this tool.
+     * Default: ['direct'] (only callable directly by LLM)
+     * Options: 'direct', 'code_execution'
+     */
+    allowed_callers?: AllowedCaller[];
+};
+/** Map of tool names to tool definitions */
+export type LCToolRegistry = Map<string, LCTool>;
+export type ProgrammaticCache = {
+    toolMap: ToolMap;
+    toolDefs: LCTool[];
+};
+/** Parameters for creating a Tool Search Regex tool */
+export type ToolSearchRegexParams = {
+    apiKey?: string;
+    toolRegistry?: LCToolRegistry;
+    onlyDeferred?: boolean;
+    baseUrl?: string;
+    [key: string]: unknown;
+};
+/** Simplified tool metadata for search purposes */
+export type ToolMetadata = {
+    name: string;
+    description: string;
+    parameters?: JsonSchemaType;
+};
+/** Individual search result for a matching tool */
+export type ToolSearchResult = {
+    tool_name: string;
+    match_score: number;
+    matched_field: string;
+    snippet: string;
+};
+/** Response from the tool search operation */
+export type ToolSearchResponse = {
+    tool_references: ToolSearchResult[];
+    total_tools_searched: number;
+    pattern_used: string;
+};
+/** Artifact returned alongside the formatted search results */
+export type ToolSearchArtifact = {
+    tool_references: ToolSearchResult[];
+    metadata: {
+        total_searched: number;
+        pattern: string;
+        error?: string;
+    };
+};
+/**
+ * Tool call requested by the Code API during programmatic execution
+ */
+export type PTCToolCall = {
+    /** Unique ID like "call_001" */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Input parameters */
+    input: Record<string, any>;
+};
+/**
+ * Tool result sent back to the Code API
+ */
+export type PTCToolResult = {
+    /** Matches PTCToolCall.id */
+    call_id: string;
+    /** Tool execution result (any JSON-serializable value) */
+    result: any;
+    /** Whether tool execution failed */
+    is_error: boolean;
+    /** Error details if is_error=true */
+    error_message?: string;
+};
+/**
+ * Response from the Code API for programmatic execution
+ */
+export type ProgrammaticExecutionResponse = {
+    status: 'tool_call_required' | 'completed' | 'error' | unknown;
+    session_id?: string;
+    /** Present when status='tool_call_required' */
+    continuation_token?: string;
+    tool_calls?: PTCToolCall[];
+    /** Present when status='completed' */
+    stdout?: string;
+    stderr?: string;
+    files?: FileRefs;
+    /** Present when status='error' */
+    error?: string;
+};
+/**
+ * Artifact returned by the PTC tool
+ */
+export type ProgrammaticExecutionArtifact = {
+    session_id?: string;
+    files?: FileRefs;
+};
+/**
+ * Initialization parameters for the PTC tool
+ */
+export type ProgrammaticToolCallingParams = {
+    /** Code API key (or use CODE_API_KEY env var) */
+    apiKey?: string;
+    /** Code API base URL (or use CODE_BASEURL env var) */
+    baseUrl?: string;
+    /** Safety limit for round-trips (default: 20) */
+    maxRoundTrips?: number;
+    /** HTTP proxy URL */
+    proxy?: string;
+    /** Enable debug logging (or set PTC_DEBUG=true env var) */
+    debug?: boolean;
+    /** Environment variable key for API key */
+    [key: string]: unknown;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -34,7 +34,7 @@
   "scripts": {
     "prepare": "node husky-setup.js",
     "prepublishOnly": "npm run build",
-    "build": "set NODE_ENV=production && rollup -c && tsc -p tsconfig.build.json",
+    "build": "cross-env NODE_ENV=production rollup -c && tsc -p tsconfig.build.json",
     "build:dev": "rollup -c",
     "start": "node dist/esm/main.js",
     "clean": "node ./config/clean.js",
@@ -51,8 +51,12 @@
     "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'",
     "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 -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'bedrock' --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'",
     "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",
+    "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'",
     "ant_web_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search.ts --name 'Jo' --location 'New York, NY'",
     "ant_web_search_edge_case": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search_edge_case.ts --name 'Jo' --location 'New York, NY'",
     "ant_web_search_error_edge_case": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/ant_web_search_error_edge_case.ts --name 'Jo' --location 'New York, NY'",
@@ -140,6 +144,7 @@
     "@types/yargs-parser": "^21.0.3",
     "@typescript-eslint/eslint-plugin": "^8.24.0",
     "@typescript-eslint/parser": "^8.24.0",
+    "cross-env": "^10.1.0",
     "eslint": "^9.39.1",
     "eslint-import-resolver-typescript": "^3.7.0",
     "eslint-plugin-import": "^2.31.0",