illuma-agents 1.0.38 → 1.0.40

package/dist/types/messages/cache.d.ts

@@ -8,18 +8,21 @@ type MessageWithContent = {
  * Strips ALL existing cache control (both Anthropic and Bedrock formats) from all messages,
  * then adds fresh cache control to the last 2 user messages in a single backward pass.
  * This ensures we don't accumulate stale cache points across multiple turns.
+ * Returns a new array - only clones messages that require modification.
  * @param messages - The array of message objects.
- * @returns - The updated array of message objects with cache control added.
+ * @returns - A new array of message objects with cache control added.
  */
 export declare function addCacheControl<T extends AnthropicMessage | BaseMessage>(messages: T[]): T[];
 /**
  * Removes all Anthropic cache_control fields from messages
  * Used when switching from Anthropic to Bedrock provider
+ * Returns a new array - only clones messages that require modification.
  */
 export declare function stripAnthropicCacheControl<T extends MessageWithContent>(messages: T[]): T[];
 /**
  * Removes all Bedrock cachePoint blocks from messages
  * Used when switching from Bedrock to Anthropic provider
+ * Returns a new array - only clones messages that require modification.
  */
 export declare function stripBedrockCacheControl<T extends MessageWithContent>(messages: T[]): T[];
 /**

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

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

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

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type * as t from '@/types';
+/**
+ * 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>;

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,6 +239,64 @@ 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. */
@@ -263,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -91,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",

package/src/agents/AgentContext.test.ts

@@ -0,0 +1,312 @@
+// src/agents/AgentContext.test.ts
+import { AgentContext } from './AgentContext';
+import { Providers } from '@/common';
+import type * as t from '@/types';
+
+describe('AgentContext', () => {
+  describe('structured output', () => {
+    const baseConfig: t.AgentInputs = {
+      agentId: 'test-agent',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        model: 'gpt-4',
+        streaming: true,
+      },
+    };
+
+    describe('isStructuredOutputMode', () => {
+      it('should return false when structuredOutput is not configured', () => {
+        const context = AgentContext.fromConfig(baseConfig);
+        expect(context.isStructuredOutputMode).toBe(false);
+      });
+
+      it('should return false when structuredOutput has no schema', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: undefined as unknown as Record<string, unknown>,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(false);
+      });
+
+      it('should return false when structuredOutput schema is null', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: null as unknown as Record<string, unknown>,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(false);
+      });
+
+      it('should return true when structuredOutput has a valid schema', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: {
+              type: 'object',
+              properties: {
+                answer: { type: 'string' },
+              },
+            },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(true);
+      });
+
+      it('should return true with minimal schema', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'string' },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(true);
+      });
+    });
+
+    describe('getStructuredOutputSchema', () => {
+      it('should return undefined when structuredOutput is not configured', () => {
+        const context = AgentContext.fromConfig(baseConfig);
+        expect(context.getStructuredOutputSchema()).toBeUndefined();
+      });
+
+      it('should return undefined when schema is not set', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {} as t.StructuredOutputConfig,
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.getStructuredOutputSchema()).toBeUndefined();
+      });
+
+      it('should return the schema as-is when properly configured', () => {
+        const schema = {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            age: { type: 'number' },
+          },
+        };
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: { schema },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result).toMatchObject(schema);
+      });
+
+      it('should add type: object when properties exist but type is missing', () => {
+        const schema = {
+          properties: {
+            name: { type: 'string' },
+          },
+        };
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: { schema },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.type).toBe('object');
+      });
+
+      it('should add title from config name', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object' },
+            name: 'ResponseSchema',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.title).toBe('ResponseSchema');
+      });
+
+      it('should not override existing title', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', title: 'ExistingTitle' },
+            name: 'NewName',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.title).toBe('ExistingTitle');
+      });
+
+      it('should add description from config', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object' },
+            description: 'A structured response',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.description).toBe('A structured response');
+      });
+
+      it('should not override existing description', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', description: 'Original description' },
+            description: 'New description',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.description).toBe('Original description');
+      });
+
+      it('should set additionalProperties: false in strict mode by default', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', properties: {} },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBe(false);
+      });
+
+      it('should set additionalProperties: false when strict is explicitly true', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', properties: {} },
+            strict: true,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBe(false);
+      });
+
+      it('should not set additionalProperties when strict is false', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', properties: {} },
+            strict: false,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBeUndefined();
+      });
+
+      it('should preserve existing additionalProperties value', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: {
+              type: 'object',
+              properties: {},
+              additionalProperties: true,
+            },
+            strict: true,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBe(true);
+      });
+
+      it('should not affect non-object types', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'array', items: { type: 'string' } },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBeUndefined();
+        expect(result?.type).toBe('array');
+      });
+
+      it('should not mutate the original schema', () => {
+        const originalSchema = {
+          type: 'object',
+          properties: { name: { type: 'string' } },
+        };
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: originalSchema,
+            name: 'TestSchema',
+            description: 'Test description',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        context.getStructuredOutputSchema();
+
+        // Original should not have been modified
+        expect(originalSchema).not.toHaveProperty('title');
+        expect(originalSchema).not.toHaveProperty('description');
+        expect(originalSchema).not.toHaveProperty('additionalProperties');
+      });
+    });
+
+    describe('fromConfig with structuredOutput', () => {
+      it('should properly initialize structuredOutput from config', () => {
+        const structuredOutput: t.StructuredOutputConfig = {
+          schema: {
+            type: 'object',
+            properties: {
+              response: { type: 'string' },
+              confidence: { type: 'number' },
+            },
+            required: ['response'],
+          },
+          name: 'AnalysisResult',
+          description: 'The analysis result',
+          mode: 'auto',
+          strict: true,
+        };
+
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput,
+        };
+
+        const context = AgentContext.fromConfig(config);
+
+        expect(context.isStructuredOutputMode).toBe(true);
+        expect(context.structuredOutput).toEqual(structuredOutput);
+      });
+
+      it('should handle all mode options', () => {
+        const modes: Array<t.StructuredOutputMode> = [
+          'auto',
+          'tool',
+          'provider',
+        ];
+
+        for (const mode of modes) {
+          const config: t.AgentInputs = {
+            ...baseConfig,
+            structuredOutput: {
+              schema: { type: 'object' },
+              mode,
+            },
+          };
+          const context = AgentContext.fromConfig(config);
+          expect(context.structuredOutput?.mode).toBe(mode);
+        }
+      });
+    });
+  });
+});

package/src/agents/AgentContext.ts

@@ -41,6 +41,7 @@ export class AgentContext {
       reasoningKey,
       useLegacyContent,
       dynamicContext,
+      structuredOutput,
     } = agentConfig;
 
     const agentContext = new AgentContext({
@@ -61,6 +62,7 @@ export class AgentContext {
       tokenCounter,
       useLegacyContent,
       dynamicContext,
+      structuredOutput,
     });
 
     if (tokenCounter) {
@@ -187,6 +189,12 @@ export class AgentContext {
     /** Names of sibling agents executing in parallel (empty if sequential) */
     parallelSiblings: string[];
   };
+  /**
+   * Structured output configuration.
+   * When set, the agent will return a validated JSON response
+   * instead of streaming text.
+   */
+  structuredOutput?: t.StructuredOutputConfig;
 
   constructor({
     agentId,
@@ -206,6 +214,7 @@ export class AgentContext {
     toolEnd,
     instructionTokens,
     useLegacyContent,
+    structuredOutput,
   }: {
     agentId: string;
     name?: string;
@@ -224,6 +233,7 @@ export class AgentContext {
     toolEnd?: boolean;
     instructionTokens?: number;
     useLegacyContent?: boolean;
+    structuredOutput?: t.StructuredOutputConfig;
   }) {
     this.agentId = agentId;
     this.name = name;
@@ -238,6 +248,7 @@ export class AgentContext {
     this.instructions = instructions;
     this.additionalInstructions = additionalInstructions;
     this.dynamicContext = dynamicContext;
+    this.structuredOutput = structuredOutput;
     if (reasoningKey) {
       this.reasoningKey = reasoningKey;
     }
@@ -251,6 +262,51 @@ export class AgentContext {
     this.useLegacyContent = useLegacyContent ?? false;
   }
 
+  /**
+   * Checks if structured output mode is enabled for this agent.
+   * When enabled, the agent will use model.invoke() instead of streaming
+   * and return a validated JSON response.
+   */
+  get isStructuredOutputMode(): boolean {
+    return (
+      this.structuredOutput != null && this.structuredOutput.schema != null
+    );
+  }
+
+  /**
+   * Gets the structured output schema with normalized defaults.
+   * Returns undefined if structured output is not configured.
+   */
+  getStructuredOutputSchema(): Record<string, unknown> | undefined {
+    if (!this.structuredOutput?.schema) {
+      return undefined;
+    }
+
+    const schema = { ...this.structuredOutput.schema };
+
+    // Ensure type is set
+    if (!schema.type && schema.properties) {
+      schema.type = 'object';
+    }
+
+    // Add title from config name
+    if (this.structuredOutput.name && !schema.title) {
+      schema.title = this.structuredOutput.name;
+    }
+
+    // Add description from config
+    if (this.structuredOutput.description && !schema.description) {
+      schema.description = this.structuredOutput.description;
+    }
+
+    // Enable strict mode by default
+    if (this.structuredOutput.strict !== false && schema.type === 'object') {
+      schema.additionalProperties = schema.additionalProperties ?? false;
+    }
+
+    return schema;
+  }
+
   /**
    * Builds instructions text for tools that are ONLY callable via programmatic code execution.
    * These tools cannot be called directly by the LLM but are available through the

package/src/common/enum.ts

@@ -21,6 +21,8 @@ export enum GraphEvents {
   ON_REASONING_DELTA = 'on_reasoning_delta',
   /** [Custom] Context analytics event for traces */
   ON_CONTEXT_ANALYTICS = 'on_context_analytics',
+  /** [Custom] Structured output event - emitted when agent returns structured JSON */
+  ON_STRUCTURED_OUTPUT = 'on_structured_output',
 
   /* Official Events */