illuma-agents 1.0.10 → 1.0.11

package/src/types/tools.ts

@@ -35,6 +35,8 @@ export type ToolNodeOptions = {
     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;
@@ -78,3 +80,167 @@ 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;
+  };
+};
+
+// ============================================================================
+// Programmatic Tool Calling Types
+// ============================================================================
+
+/**
+ * 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 */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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/src/utils/run.ts

@@ -56,8 +56,12 @@ export class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {
     runManager?: CallbackManagerForChainRun
   ): Promise<O> {
     return new Promise<O>((resolve, reject) => {
+      // Defensive check: ensure runManager has getChild method before calling
+      const childCallbacks = typeof runManager?.getChild === 'function' 
+        ? runManager.getChild() 
+        : undefined;
       const childConfig = patchConfig(config, {
-        callbacks: runManager?.getChild(),
+        callbacks: childCallbacks,
       });
       void AsyncLocalStorageProviderSingleton.runWithConfig(
         childConfig,