@illuma-ai/agents 1.0.81

package/dist/types/prompts/taskmanager.d.ts

@@ -0,0 +1,41 @@
+export declare const taskManagerPrompt = "You are a Task Manager responsible for efficiently coordinating a team of specialized workers: {members}. Your PRIMARY and SOLE OBJECTIVE is to fulfill the user's specific request as quickly and effectively as possible.\n\nCRITICAL GUIDELINES:\n1. The user's request is your CHIEF CONCERN. Every action must directly contribute to fulfilling this request.\n2. Aim to complete the entire task in NO MORE THAN 2-3 TURNS, unless explicitly instructed otherwise.\n3. Eliminate all superfluous activity. Each task must be essential to achieving the user's goal.\n4. Assign no more than 5 tasks per turn, and only if absolutely necessary.\n5. Be concise and direct in your task assignments.\n6. End the process IMMEDIATELY once the user's request is fulfilled by setting 'end' to true and assigning no new tasks.\n\nYour responsibilities:\n1. Analyze the user's request and break it down into the minimum necessary subtasks.\n2. Assign these essential tasks to the most appropriate team members based on their skills and tools.\n3. Prioritize tasks to ensure the most efficient path to completion.\n4. Continuously evaluate if the user's request has been fully addressed.\n5. End the process IMMEDIATELY once the user's request is fulfilled.\n\nTask Assignment Guidelines:\n- Assign only the most crucial tasks required to meet the user's needs.\n- Multiple tasks can be assigned to the same team member if it improves efficiency.\n- Always specify the tool to use if applicable.\n- Consider task dependencies to minimize the number of turns.\n\nAfter each round:\n- Critically assess if the user's request has been fully addressed.\n- If more work is genuinely needed, assign only the most essential remaining tasks.\n- If the user's request has been fulfilled or can be fulfilled with the results at hand, set 'end' to true and assign no new tasks.\n\nREMEMBER: Your success is measured by how quickly and effectively you fulfill the user's request, not by the number of tasks assigned or turns taken. Excessive deliberation or unnecessary tasks are counterproductive. Focus solely on the user's needs and conclude the process as soon as those needs are met.";
+export declare const assignTasksFunctionDescription = "Assign the minimum necessary tasks to team members to fulfill the user's request as quickly as possible. Assign up to 5 tasks maximum per turn, only if absolutely necessary. Each task must specify the team member, a concise description, and the tool to use if applicable.";
+export declare const assignTasksFunctionParameters: {
+    type: string;
+    properties: {
+        tasks: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    member: {
+                        type: string;
+                        description: string;
+                    };
+                    description: {
+                        type: string;
+                        description: string;
+                    };
+                    tool: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
+            description: string;
+        };
+    };
+    required: string[];
+};
+export declare const endProcessFunctionDescription = "End the process when the user's request has been fulfilled.";
+export declare const endProcessFunctionParameters: {
+    type: string;
+    properties: {
+        reason: {
+            type: string;
+            description: string;
+        };
+    };
+    required: string[];
+};

package/dist/types/run.d.ts

@@ -0,0 +1,41 @@
+import './instrumentation';
+import type { MessageContentComplex, BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
+import { StandardGraph } from '@/graphs/Graph';
+export declare const defaultOmitOptions: Set<string>;
+export declare class Run<_T extends t.BaseGraphState> {
+    id: string;
+    private tokenCounter?;
+    private handlerRegistry?;
+    private indexTokenCountMap?;
+    graphRunnable?: t.CompiledStateWorkflow;
+    Graph: StandardGraph | MultiAgentGraph | undefined;
+    returnContent: boolean;
+    private constructor();
+    private createLegacyGraph;
+    private createMultiAgentGraph;
+    static create<T extends t.BaseGraphState>(config: t.RunConfig): Promise<Run<T>>;
+    getRunMessages(): BaseMessage[] | undefined;
+    /**
+     * Returns the normalized finish/stop reason from the last LLM invocation.
+     * Delegates to the underlying Graph instance.
+     */
+    getLastFinishReason(): string | undefined;
+    /**
+     * Creates a custom event callback handler that intercepts custom events
+     * and processes them through our handler registry instead of EventStreamCallbackHandler
+     */
+    private createCustomEventCallback;
+    processStream(inputs: t.IState, config: Partial<RunnableConfig> & {
+        version: 'v1' | 'v2';
+        run_id?: string;
+    }, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;
+    private createSystemCallback;
+    getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks;
+    generateTitle({ provider, inputText, contentParts, titlePrompt, clientOptions, chainOptions, skipLanguage, titleMethod, titlePromptTemplate, }: t.RunTitleOptions): Promise<{
+        language?: string;
+        title?: string;
+    }>;
+}

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

@@ -0,0 +1 @@
+export * from './validate';

package/dist/types/schemas/validate.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+/**
+ * Validation result from structured output
+ */
+export interface ValidationResult<T = Record<string, unknown>> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    raw?: unknown;
+}
+/**
+ * Validates structured output against a JSON Schema.
+ *
+ * @param output - The output to validate
+ * @param schema - JSON Schema to validate against
+ * @returns Validation result with success flag and data or error
+ */
+export declare function validateStructuredOutput(output: unknown, schema: Record<string, unknown>): ValidationResult;
+/**
+ * Converts a Zod schema to JSON Schema format.
+ * This is a simplified converter for common types.
+ */
+export declare function zodToJsonSchema(zodSchema: z.ZodType): Record<string, unknown>;
+/**
+ * Creates a structured output error message for retry.
+ */
+export declare function createValidationErrorMessage(result: ValidationResult, customMessage?: string): string;
+/**
+ * Checks if a value is a valid JSON Schema object.
+ */
+export declare function isValidJsonSchema(value: unknown): value is Record<string, unknown>;
+/**
+ * Normalizes a JSON Schema by adding defaults and cleaning up.
+ */
+export declare function normalizeJsonSchema(schema: Record<string, unknown>, config?: t.StructuredOutputConfig): Record<string, unknown>;
+/**
+ * Result from schema preparation, includes the prepared schema and any warnings.
+ */
+export interface SchemaPreparationResult {
+    schema: Record<string, unknown>;
+    warnings: string[];
+}
+/**
+ * Prepares a JSON Schema for a specific provider's native structured output API.
+ *
+ * This function normalizes the schema to comply with provider-specific requirements:
+ * - Adds `additionalProperties: false` recursively to all objects (required by all providers in strict mode)
+ * - Ensures all properties are listed in `required` (required by OpenAI and Anthropic)
+ * - Strips unsupported constraint keywords (minimum, maxLength, etc.) and moves them to description
+ * - Returns warnings for any modifications made
+ *
+ * @param schema - The original JSON Schema
+ * @param provider - The LLM provider
+ * @param strict - Whether strict mode is enabled (default: true)
+ * @returns The prepared schema and any warnings
+ */
+export declare function prepareSchemaForProvider(schema: Record<string, unknown>, provider: Providers | string, strict?: boolean): SchemaPreparationResult;

package/dist/types/splitStream.d.ts

@@ -0,0 +1,37 @@
+import type * as t from '@/types';
+import { ContentTypes } from '@/common';
+export declare const SEPARATORS: string[];
+export declare class SplitStreamHandler {
+    private inCodeBlock;
+    private inThinkBlock;
+    private accumulate;
+    tokens: string[];
+    lastToken: string;
+    reasoningTokens: string[];
+    currentStepId?: string;
+    currentMessageId?: string;
+    currentType?: ContentTypes.TEXT | ContentTypes.THINK;
+    currentLength: number;
+    reasoningKey: 'reasoning_content' | 'reasoning';
+    currentIndex: number;
+    blockThreshold: number;
+    /** The run ID AKA the Message ID associated with the complete generation */
+    runId: string;
+    handlers?: t.SplitStreamHandlers;
+    constructor({ runId, handlers, accumulate, reasoningKey, blockThreshold, }: {
+        runId: string;
+        accumulate?: boolean;
+        handlers: t.SplitStreamHandlers;
+        blockThreshold?: number;
+        reasoningKey?: 'reasoning_content' | 'reasoning';
+    });
+    getMessageId: () => string | undefined;
+    createMessageStep: (type?: ContentTypes.TEXT | ContentTypes.THINK) => [string, string];
+    dispatchRunStep: (stepId: string, stepDetails: t.StepDetails) => void;
+    dispatchMessageDelta: (stepId: string, delta: t.MessageDelta) => void;
+    dispatchReasoningDelta: (stepId: string, delta: t.ReasoningDelta) => void;
+    handleContent: (content: string, _type: ContentTypes.TEXT | ContentTypes.THINK) => void;
+    getDeltaContent(chunk?: t.CustomChunk): string;
+    getReasoningDelta(chunk?: t.CustomChunk): string;
+    handle(chunk?: t.CustomChunk): void;
+}

package/dist/types/stream.d.ts

@@ -0,0 +1,15 @@
+import type { AIMessageChunk } from '@langchain/core/messages';
+import type { AgentContext } from '@/agents/AgentContext';
+import type { StandardGraph } from '@/graphs';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+export declare function getChunkContent({ chunk, provider, reasoningKey, }: {
+    chunk?: Partial<AIMessageChunk>;
+    provider?: Providers;
+    reasoningKey: 'reasoning_content' | 'reasoning';
+}): string | t.MessageContentComplex[] | undefined;
+export declare class ChatModelStreamHandler implements t.EventHandler {
+    handle(event: string, data: t.StreamEventData, metadata?: Record<string, unknown>, graph?: StandardGraph): Promise<void>;
+    handleReasoning(chunk: Partial<AIMessageChunk>, agentContext: AgentContext): void;
+}
+export declare function createContentAggregator(): t.ContentAggregatorResult;

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/BrowserTools.d.ts

@@ -0,0 +1,87 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+/**
+ * Browser tool names - keep in sync with ranger-browser extension
+ * These tools execute locally in the browser extension, NOT on the server
+ */
+export declare const EBrowserTools: {
+    readonly CLICK: "browser_click";
+    readonly TYPE: "browser_type";
+    readonly NAVIGATE: "browser_navigate";
+    readonly SCROLL: "browser_scroll";
+    readonly EXTRACT: "browser_extract";
+    readonly HOVER: "browser_hover";
+    readonly WAIT: "browser_wait";
+    readonly BACK: "browser_back";
+    readonly SCREENSHOT: "browser_screenshot";
+    readonly GET_PAGE_STATE: "browser_get_page_state";
+    readonly KEYPRESS: "browser_keypress";
+    readonly SWITCH_TAB: "browser_switch_tab";
+};
+export type BrowserToolName = (typeof EBrowserTools)[keyof typeof EBrowserTools];
+/**
+ * Callback function type for waiting on browser action results
+ * This allows the server (Ranger) to provide a callback that waits for the extension
+ * to POST results back to the server before returning to the LLM.
+ *
+ * @param action - The browser action (click, type, navigate, etc.)
+ * @param args - Arguments for the action
+ * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)
+ * @returns Promise that resolves with the actual browser result (page state, etc.)
+ */
+export type BrowserToolCallback = (action: string, args: Record<string, unknown>, toolCallId: string) => Promise<BrowserActionResult>;
+/**
+ * Result returned from browser action execution
+ */
+export interface BrowserActionResult {
+    success: boolean;
+    url?: string;
+    title?: string;
+    elementList?: string;
+    error?: string;
+    screenshot?: string;
+}
+/**
+ * Check if browser capability is available based on request headers or context
+ * The browser extension sets these headers when connected:
+ * - X-Ranger-Browser-Extension: true
+ * - X-Ranger-Browser-Capable: true
+ */
+export declare function hasBrowserCapability(req?: {
+    headers?: Record<string, string | string[] | undefined>;
+}): boolean;
+/**
+ * Browser tool response interface
+ * This is what the extension returns after executing the action
+ */
+export interface BrowserToolResponse {
+    requiresBrowserExecution: true;
+    action: string;
+    args: Record<string, unknown>;
+    toolCallId?: string;
+}
+/**
+ * Options for creating browser tools
+ */
+export interface CreateBrowserToolsOptions {
+    /**
+     * Optional callback that waits for browser action results.
+     * When provided, tools will await this callback to get actual results from the extension.
+     * When not provided, tools return markers immediately (for non-server contexts).
+     */
+    waitForResult?: BrowserToolCallback;
+}
+/**
+ * Create browser tools with optional callback for waiting on results
+ *
+ * When waitForResult callback is provided:
+ * 1. Tool returns marker that triggers extension
+ * 2. Tool then awaits callback to get actual results
+ * 3. Returns real page state to LLM
+ *
+ * When no callback:
+ * 1. Tool returns marker only (for non-server contexts)
+ *
+ * NOTE: These tools use TEXT-BASED element lists, NOT screenshots
+ * Screenshots would be 100K+ tokens each - element lists are ~100 tokens
+ */
+export declare function createBrowserTools(options?: CreateBrowserToolsOptions): DynamicStructuredTool[];

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

@@ -0,0 +1,34 @@
+import { Tool } from '@langchain/core/tools';
+export declare const CalculatorToolName = "calculator";
+export declare const CalculatorToolDescription = "Useful for getting the result of a math expression. The input to this tool should be a valid mathematical expression that could be executed by a simple calculator.";
+export declare const CalculatorSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly input: {
+            readonly type: "string";
+            readonly description: "A valid mathematical expression to evaluate";
+        };
+    };
+    readonly required: readonly ["input"];
+};
+export declare const CalculatorToolDefinition: {
+    readonly name: "calculator";
+    readonly description: "Useful for getting the result of a math expression. The input to this tool should be a valid mathematical expression that could be executed by a simple calculator.";
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly input: {
+                readonly type: "string";
+                readonly description: "A valid mathematical expression to evaluate";
+            };
+        };
+        readonly required: readonly ["input"];
+    };
+};
+export declare class Calculator extends Tool {
+    static lc_name(): string;
+    get lc_namespace(): string[];
+    name: string;
+    _call(input: string): Promise<string>;
+    description: string;
+}

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

@@ -0,0 +1,57 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+export declare const imageExtRegex: RegExp;
+export declare const getCodeBaseURL: () => string;
+export declare const CodeExecutionToolSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly lang: {
+            readonly type: "string";
+            readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r"];
+            readonly description: "The programming language or runtime to execute the code in.";
+        };
+        readonly code: {
+            readonly type: "string";
+            readonly description: "The complete, self-contained code to execute, without any truncation or minimization.\n- The environment is stateless; variables and imports don't persist between executions.\n- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- py: This is not a Jupyter notebook environment. Use `print()` for all outputs.\n- py: Matplotlib: Use `plt.savefig()` to save plots as files.\n- js: use the `console` or `process` methods for all outputs.\n- r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).\n- Other languages: use appropriate output functions.";
+        };
+        readonly args: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.";
+        };
+    };
+    readonly required: readonly ["lang", "code"];
+};
+export declare const CodeExecutionToolDescription: string;
+export declare const CodeExecutionToolName = Constants.EXECUTE_CODE;
+export declare const CodeExecutionToolDefinition: {
+    readonly name: Constants.EXECUTE_CODE;
+    readonly description: string;
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly lang: {
+                readonly type: "string";
+                readonly enum: readonly ["py", "js", "ts", "c", "cpp", "java", "php", "rs", "go", "d", "f90", "r"];
+                readonly description: "The programming language or runtime to execute the code in.";
+            };
+            readonly code: {
+                readonly type: "string";
+                readonly description: "The complete, self-contained code to execute, without any truncation or minimization.\n- The environment is stateless; variables and imports don't persist between executions.\n- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- py: This is not a Jupyter notebook environment. Use `print()` for all outputs.\n- py: Matplotlib: Use `plt.savefig()` to save plots as files.\n- js: use the `console` or `process` methods for all outputs.\n- r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).\n- Other languages: use appropriate output functions.";
+            };
+            readonly args: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.";
+            };
+        };
+        readonly required: readonly ["lang", "code"];
+    };
+};
+declare function createCodeExecutionTool(params?: t.CodeExecutionToolParams): DynamicStructuredTool;
+export { createCodeExecutionTool };

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

@@ -0,0 +1,138 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+export declare const ProgrammaticToolCallingSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly code: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Python code that calls tools programmatically. Tools are available as async functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh Python interpreter. Variables, imports, and data do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block: query → process → output.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nYour code is auto-wrapped in async context. Just write logic with await—no boilerplate needed.\n\nExample (Complete workflow in one call):\n  # Query data\n  data = await query_database(sql=\"SELECT * FROM users\")\n  # Process it\n  df = pd.DataFrame(data)\n  summary = df.groupby('region').sum()\n  # Output results\n  await write_to_sheet(spreadsheet_id=sid, data=summary.to_dict())\n  print(f\"Wrote {len(summary)} rows\")\n\nExample (Parallel calls):\n  sf, ny = await asyncio.gather(get_weather(city=\"SF\"), get_weather(city=\"NY\"))\n  print(f\"SF: {sf}, NY: {ny}\")\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Just write code with await—auto-wrapped in async context\n- DO NOT define async def main() or call asyncio.run()\n- Tools are pre-defined—DO NOT write function definitions\n- Only print() output returns to the model";
+        };
+        readonly timeout: {
+            readonly type: "integer";
+            readonly minimum: 1000;
+            readonly maximum: 300000;
+            readonly default: 60000;
+            readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.";
+        };
+    };
+    readonly required: readonly ["code"];
+};
+export declare const ProgrammaticToolCallingName = Constants.PROGRAMMATIC_TOOL_CALLING;
+export declare const ProgrammaticToolCallingDescription: string;
+export declare const ProgrammaticToolCallingDefinition: {
+    readonly name: Constants.PROGRAMMATIC_TOOL_CALLING;
+    readonly description: string;
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly code: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Python code that calls tools programmatically. Tools are available as async functions.\n\nCRITICAL - STATELESS EXECUTION:\nEach call is a fresh Python interpreter. Variables, imports, and data do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block: query → process → output.\nDO NOT split work across multiple calls expecting to reuse variables.\n\nYour code is auto-wrapped in async context. Just write logic with await—no boilerplate needed.\n\nExample (Complete workflow in one call):\n  # Query data\n  data = await query_database(sql=\"SELECT * FROM users\")\n  # Process it\n  df = pd.DataFrame(data)\n  summary = df.groupby('region').sum()\n  # Output results\n  await write_to_sheet(spreadsheet_id=sid, data=summary.to_dict())\n  print(f\"Wrote {len(summary)} rows\")\n\nExample (Parallel calls):\n  sf, ny = await asyncio.gather(get_weather(city=\"SF\"), get_weather(city=\"NY\"))\n  print(f\"SF: {sf}, NY: {ny}\")\n\nRules:\n- EVERYTHING in one call—no state persists between executions\n- Just write code with await—auto-wrapped in async context\n- DO NOT define async def main() or call asyncio.run()\n- Tools are pre-defined—DO NOT write function definitions\n- Only print() output returns to the model";
+            };
+            readonly timeout: {
+                readonly type: "integer";
+                readonly minimum: 1000;
+                readonly maximum: 300000;
+                readonly default: 60000;
+                readonly description: "Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.";
+            };
+        };
+        readonly required: readonly ["code"];
+    };
+};
+/**
+ * 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[];
+/**
+ * Fetches files from a previous session to make them available for the current execution.
+ * Files are returned as CodeEnvFile references to be included in the request.
+ * @param baseUrl - The base URL for the Code API
+ * @param apiKey - The API key for authentication
+ * @param sessionId - The session ID to fetch files from
+ * @param proxy - Optional HTTP proxy URL
+ * @returns Array of CodeEnvFile references, or empty array if fetch fails
+ */
+export declare function fetchSessionFiles(baseUrl: string, apiKey: string, sessionId: string, proxy?: string): Promise<t.CodeEnvFile[]>;
+/**
+ * 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>;
+/**
+ * Unwraps tool responses that may be formatted as tuples or content blocks.
+ * MCP tools return [content, artifacts], we need to extract the raw data.
+ * @param result - The raw result from tool.invoke()
+ * @param isMCPTool - Whether this is an MCP tool (has mcp property)
+ * @returns Unwrapped raw data (string, object, or parsed JSON)
+ */
+export declare function unwrapToolResponse(result: unknown, isMCPTool: boolean): unknown;
+/**
+ * Executes tools in parallel when requested by the API.
+ * Uses Promise.all for parallel execution, catching individual errors.
+ * Unwraps formatted responses (e.g., MCP tool tuples) to raw data.
+ * @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;

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

@@ -0,0 +1,51 @@
+import { ToolCall } from '@langchain/core/messages/tool';
+import { END, Command, MessagesAnnotation } from '@langchain/langgraph';
+import type { RunnableConfig } from '@langchain/core/runnables';
+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> {
+    private toolMap;
+    private loadRuntimeTools?;
+    handleToolErrors: boolean;
+    trace: boolean;
+    toolCallStepIds?: Map<string, string>;
+    errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
+    private toolUsageCount;
+    /** Tool registry for filtering (lazy computation of programmatic maps) */
+    private toolRegistry?;
+    /** Cached programmatic tools (computed once on first PTC call) */
+    private programmaticCache?;
+    /** Reference to Graph's sessions map for automatic session injection */
+    private sessions?;
+    /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+    private eventDrivenMode;
+    /** Tool definitions for event-driven mode */
+    private toolDefinitions?;
+    /** Agent ID for event-driven mode */
+    private agentId?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, toolDefinitions, agentId, }: 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.
+     */
+    getToolUsageCounts(): ReadonlyMap<string, number>;
+    /**
+     * Runs a single tool call with error handling
+     */
+    protected runTool(call: ToolCall, config: RunnableConfig): Promise<BaseMessage | Command>;
+    /**
+     * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
+     * Used in event-driven mode where the host handles actual tool execution.
+     */
+    private executeViaEvent;
+    protected run(input: any, config: RunnableConfig): Promise<T>;
+    private isSendInput;
+    private isMessagesState;
+}
+export declare function toolsCondition<T extends string>(state: BaseMessage[] | typeof MessagesAnnotation.State, toolNode: T, invokedToolIds?: Set<string>): T | typeof END;