illuma-agents 1.0.37 → 1.0.39

package/src/types/graph.test.ts

@@ -0,0 +1,183 @@
+// src/types/graph.test.ts
+import type {
+  StructuredOutputConfig,
+  StructuredOutputMode,
+  AgentInputs,
+  BaseGraphState,
+} from './graph';
+
+/**
+ * Type-level tests to ensure StructuredOutputConfig interface is correctly defined.
+ * These tests don't run at runtime but will fail at compile time if types are wrong.
+ */
+describe('StructuredOutputConfig type', () => {
+  describe('type compatibility', () => {
+    it('should accept minimal configuration', () => {
+      const config: StructuredOutputConfig = {
+        schema: { type: 'object' },
+      };
+      expect(config.schema).toBeDefined();
+    });
+
+    it('should accept full configuration', () => {
+      const config: StructuredOutputConfig = {
+        schema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            value: { type: 'number' },
+          },
+          required: ['name'],
+        },
+        name: 'TestSchema',
+        description: 'A test schema for structured output',
+        mode: 'auto',
+        strict: true,
+        handleErrors: true,
+        maxRetries: 3,
+        includeRaw: false,
+      };
+
+      expect(config.schema).toBeDefined();
+      expect(config.name).toBe('TestSchema');
+      expect(config.description).toBe('A test schema for structured output');
+      expect(config.mode).toBe('auto');
+      expect(config.strict).toBe(true);
+      expect(config.handleErrors).toBe(true);
+      expect(config.maxRetries).toBe(3);
+      expect(config.includeRaw).toBe(false);
+    });
+
+    it('should accept all valid mode values', () => {
+      const modes: StructuredOutputMode[] = ['auto', 'tool', 'provider'];
+
+      for (const mode of modes) {
+        const config: StructuredOutputConfig = {
+          schema: { type: 'string' },
+          mode,
+        };
+        expect(config.mode).toBe(mode);
+      }
+    });
+
+    it('should make all fields except schema optional', () => {
+      const minimalConfig: StructuredOutputConfig = {
+        schema: { type: 'boolean' },
+      };
+
+      // These should all be undefined for minimal config
+      expect(minimalConfig.name).toBeUndefined();
+      expect(minimalConfig.description).toBeUndefined();
+      expect(minimalConfig.mode).toBeUndefined();
+      expect(minimalConfig.strict).toBeUndefined();
+      expect(minimalConfig.handleErrors).toBeUndefined();
+      expect(minimalConfig.maxRetries).toBeUndefined();
+      expect(minimalConfig.includeRaw).toBeUndefined();
+    });
+  });
+
+  describe('schema property types', () => {
+    it('should accept object schema', () => {
+      const config: StructuredOutputConfig = {
+        schema: {
+          type: 'object',
+          properties: {
+            nested: {
+              type: 'object',
+              properties: {
+                value: { type: 'string' },
+              },
+            },
+          },
+        },
+      };
+      expect(config.schema.type).toBe('object');
+    });
+
+    it('should accept array schema', () => {
+      const config: StructuredOutputConfig = {
+        schema: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'number' },
+            },
+          },
+        },
+      };
+      expect(config.schema.type).toBe('array');
+    });
+
+    it('should accept schema with enum', () => {
+      const config: StructuredOutputConfig = {
+        schema: {
+          type: 'string',
+          enum: ['option1', 'option2', 'option3'],
+        },
+      };
+      expect(config.schema.enum).toEqual(['option1', 'option2', 'option3']);
+    });
+
+    it('should accept schema with $ref', () => {
+      const config: StructuredOutputConfig = {
+        schema: {
+          $schema: 'http://json-schema.org/draft-07/schema#',
+          definitions: {
+            Address: {
+              type: 'object',
+              properties: {
+                street: { type: 'string' },
+                city: { type: 'string' },
+              },
+            },
+          },
+          type: 'object',
+          properties: {
+            address: { $ref: '#/definitions/Address' },
+          },
+        },
+      };
+      expect(config.schema.$schema).toBeDefined();
+    });
+  });
+});
+
+describe('AgentInputs with structuredOutput', () => {
+  it('should accept structuredOutput as optional field', () => {
+    const inputsWithout: Partial<AgentInputs> = {
+      agentId: 'agent-1',
+      provider: 'openai' as AgentInputs['provider'],
+    };
+    expect(inputsWithout.structuredOutput).toBeUndefined();
+
+    const inputsWith: Partial<AgentInputs> = {
+      agentId: 'agent-2',
+      provider: 'anthropic' as AgentInputs['provider'],
+      structuredOutput: {
+        schema: { type: 'object' },
+      },
+    };
+    expect(inputsWith.structuredOutput).toBeDefined();
+  });
+});
+
+describe('BaseGraphState with structuredResponse', () => {
+  it('should support structuredResponse field', () => {
+    const state: Partial<BaseGraphState> = {
+      messages: [],
+      structuredResponse: { result: 'success', data: [1, 2, 3] },
+    };
+    expect(state.structuredResponse).toEqual({
+      result: 'success',
+      data: [1, 2, 3],
+    });
+  });
+
+  it('should allow structuredResponse to be undefined', () => {
+    const state: Partial<BaseGraphState> = {
+      messages: [],
+    };
+    expect(state.structuredResponse).toBeUndefined();
+  });
+});

package/src/types/graph.ts

@@ -64,6 +64,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 & {
@@ -355,8 +360,70 @@ 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;
@@ -382,4 +449,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/src/types/llm.ts

@@ -55,7 +55,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/src/types/tools.ts

@@ -39,6 +39,8 @@ export type ToolNodeOptions = {
   ) => 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;
@@ -72,6 +74,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[];
@@ -128,12 +132,19 @@ export type LCToolRegistry = Map<string, LCTool>;
 
 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;
 };
 
@@ -246,3 +257,41 @@ export type ProgrammaticToolCallingParams = {
   /** Environment variable key for API key */
   [key: string]: unknown;
 };
+
+// ============================================================================
+// Tool Session Context Types
+// ============================================================================
+
+/**
+ * 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>;