@illuma-ai/agents 1.1.21 → 1.1.23

package/src/types/graph.test.js

@@ -1,192 +0,0 @@
-/**
- * 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 = {
-                schema: { type: 'object' },
-            };
-            expect(config.schema).toBeDefined();
-        });
-        it('should accept full configuration', () => {
-            const config = {
-                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 = ['auto', 'tool', 'provider'];
-            for (const mode of modes) {
-                const config = {
-                    schema: { type: 'string' },
-                    mode,
-                };
-                expect(config.mode).toBe(mode);
-            }
-        });
-        it('should make all fields except schema optional', () => {
-            const minimalConfig = {
-                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 = {
-                schema: {
-                    type: 'object',
-                    properties: {
-                        nested: {
-                            type: 'object',
-                            properties: {
-                                value: { type: 'string' },
-                            },
-                        },
-                    },
-                },
-            };
-            expect(config.schema.type).toBe('object');
-        });
-        it('should accept array schema', () => {
-            const config = {
-                schema: {
-                    type: 'array',
-                    items: {
-                        type: 'object',
-                        properties: {
-                            id: { type: 'number' },
-                        },
-                    },
-                },
-            };
-            expect(config.schema.type).toBe('array');
-        });
-        it('should accept schema with enum', () => {
-            const config = {
-                schema: {
-                    type: 'string',
-                    enum: ['option1', 'option2', 'option3'],
-                },
-            };
-            expect(config.schema.enum).toEqual(['option1', 'option2', 'option3']);
-        });
-        it('should accept schema with $ref', () => {
-            const config = {
-                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 = {
-            agentId: 'agent-1',
-            provider: 'openai',
-        };
-        expect(inputsWithout.structuredOutput).toBeUndefined();
-        const inputsWith = {
-            agentId: 'agent-2',
-            provider: 'anthropic',
-            structuredOutput: {
-                schema: { type: 'object' },
-            },
-        };
-        expect(inputsWith.structuredOutput).toBeDefined();
-    });
-});
-describe('BaseGraphState with structuredResponse', () => {
-    it('should support structuredResponse field', () => {
-        const state = {
-            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 = {
-            messages: [],
-        };
-        expect(state.structuredResponse).toBeUndefined();
-    });
-});
-describe('AgentInputs with summarizeCallback', () => {
-    it('should accept summarizeCallback as optional field', () => {
-        const inputsWithout = {
-            agentId: 'agent-1',
-            provider: 'openai',
-        };
-        expect(inputsWithout.summarizeCallback).toBeUndefined();
-        const inputsWith = {
-            agentId: 'agent-2',
-            provider: 'anthropic',
-            summarizeCallback: async (_messages) => 'summary',
-        };
-        expect(inputsWith.summarizeCallback).toBeDefined();
-    });
-    it('should accept a valid callback function type', () => {
-        const mockCallback = async (messages) => {
-            if (messages.length === 0) {
-                return undefined;
-            }
-            return `Summary of ${messages.length} messages`;
-        };
-        const inputs = {
-            agentId: 'agent-summarize',
-            provider: 'openai',
-            summarizeCallback: mockCallback,
-        };
-        expect(inputs.summarizeCallback).toBe(mockCallback);
-    });
-});
-export {};
-//# sourceMappingURL=graph.test.js.map

package/src/types/index.js

@@ -1,7 +0,0 @@
-// src/types/index.ts
-export * from './graph';
-export * from './llm';
-export * from './run';
-export * from './stream';
-export * from './tools';
-//# sourceMappingURL=index.js.map

package/src/types/llm.js

@@ -1,2 +0,0 @@
-import { Providers } from '@/common';
-//# sourceMappingURL=llm.js.map

package/src/types/messages.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=messages.js.map

package/src/types/run.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=run.js.map

package/src/types/stream.js

@@ -1,2 +0,0 @@
-import { GraphEvents } from '@/common/enum';
-//# sourceMappingURL=stream.js.map

package/src/types/tools.js

@@ -1,2 +0,0 @@
-import { EnvVar } from '@/common';
-//# sourceMappingURL=tools.js.map

package/src/utils/contextAnalytics.js

@@ -1,79 +0,0 @@
-/**
- * Context Analytics Utility
- *
- * Provides context analytics data for observability/traces.
- * No console logging - just data structures for event emission.
- */
-/**
- * Resolve the message type string from a BaseMessage or message-like object.
- *
- * Uses the same duck-typing contract as LangChain's `isBaseMessage`:
- * prefer `_getType()` (internal), fallback to `getType()` (public).
- * This handles cross-package BaseMessage instances where `instanceof`
- * checks may fail but prototype methods are still present.
- */
-function resolveMessageType(msg) {
-    if (typeof msg._getType === 'function') {
-        return msg._getType();
-    }
-    if (typeof msg.getType === 'function') {
-        return msg.getType();
-    }
-    // Last resort: infer from known LangChain serialization fields
-    return msg.type ?? 'unknown';
-}
-/**
- * Build context analytics for traces (no logging).
- *
- * @param messages - Array of BaseMessage (may originate from different @langchain/core installations)
- * @param options  - Token counting and context budget info
- */
-export function buildContextAnalytics(messages, options) {
-    const { tokenCounter, maxContextTokens, instructionTokens, indexTokenCountMap, } = options;
-    let totalTokens = 0;
-    const breakdown = {};
-    for (let i = 0; i < messages.length; i++) {
-        const msg = messages[i];
-        const type = resolveMessageType(msg);
-        let tokens = 0;
-        if (indexTokenCountMap && indexTokenCountMap[i] != null) {
-            tokens = indexTokenCountMap[i];
-        }
-        else if (tokenCounter) {
-            try {
-                tokens = tokenCounter(msg);
-            }
-            catch {
-                const content = typeof msg.content === 'string'
-                    ? msg.content
-                    : JSON.stringify(msg.content);
-                tokens = Math.ceil(content.length / 4);
-            }
-        }
-        totalTokens += tokens;
-        if (!breakdown[type]) {
-            breakdown[type] = { tokens: 0, percent: 0 };
-        }
-        breakdown[type].tokens += tokens;
-    }
-    for (const type of Object.keys(breakdown)) {
-        breakdown[type].percent =
-            totalTokens > 0
-                ? Math.round((breakdown[type].tokens / totalTokens) * 1000) / 10
-                : 0;
-    }
-    let utilizationPercent;
-    if (maxContextTokens && maxContextTokens > 0) {
-        utilizationPercent =
-            Math.round((totalTokens / maxContextTokens) * 1000) / 10;
-    }
-    return {
-        messageCount: messages.length,
-        totalTokens,
-        maxContextTokens,
-        instructionTokens,
-        utilizationPercent,
-        breakdown,
-    };
-}
-//# sourceMappingURL=contextAnalytics.js.map

package/src/utils/contextAnalytics.test.js

@@ -1,166 +0,0 @@
-import { HumanMessage, AIMessage, SystemMessage, ToolMessage, } from '@langchain/core/messages';
-import { buildContextAnalytics } from './contextAnalytics';
-describe('buildContextAnalytics', () => {
-    describe('with proper BaseMessage instances', () => {
-        it('should count messages and compute breakdown by type', () => {
-            const messages = [
-                new SystemMessage('You are helpful'),
-                new HumanMessage('Hello'),
-                new AIMessage('Hi there'),
-            ];
-            const result = buildContextAnalytics(messages, {});
-            expect(result.messageCount).toBe(3);
-            expect(result.breakdown).toBeDefined();
-            expect(result.breakdown['system']).toBeDefined();
-            expect(result.breakdown['human']).toBeDefined();
-            expect(result.breakdown['ai']).toBeDefined();
-        });
-        it('should use tokenCounter when provided', () => {
-            const messages = [
-                new HumanMessage('Hello world'),
-                new AIMessage('Response'),
-            ];
-            const tokenCounter = jest.fn().mockReturnValue(10);
-            const result = buildContextAnalytics(messages, { tokenCounter });
-            expect(tokenCounter).toHaveBeenCalledTimes(2);
-            expect(result.totalTokens).toBe(20);
-        });
-        it('should prefer indexTokenCountMap over tokenCounter', () => {
-            const messages = [new HumanMessage('Hello')];
-            const tokenCounter = jest.fn().mockReturnValue(999);
-            const result = buildContextAnalytics(messages, {
-                tokenCounter,
-                indexTokenCountMap: { '0': 42 },
-            });
-            expect(tokenCounter).not.toHaveBeenCalled();
-            expect(result.totalTokens).toBe(42);
-        });
-        it('should calculate utilization percentage', () => {
-            const messages = [new HumanMessage('Hello')];
-            const result = buildContextAnalytics(messages, {
-                tokenCounter: () => 500,
-                maxContextTokens: 1000,
-            });
-            expect(result.utilizationPercent).toBe(50);
-        });
-        it('should handle ToolMessage instances', () => {
-            const messages = [
-                new HumanMessage('Do something'),
-                new AIMessage({
-                    content: '',
-                    tool_calls: [{ id: 'tc1', name: 'test', args: {} }],
-                }),
-                new ToolMessage({ content: 'result', tool_call_id: 'tc1' }),
-            ];
-            const result = buildContextAnalytics(messages, {});
-            expect(result.messageCount).toBe(3);
-            expect(result.breakdown['tool']).toBeDefined();
-        });
-        it('should calculate correct percentage breakdown', () => {
-            const messages = [
-                new HumanMessage('Hello'),
-                new AIMessage('World'),
-            ];
-            const result = buildContextAnalytics(messages, {
-                tokenCounter: () => 50,
-                maxContextTokens: 1000,
-            });
-            expect(result.breakdown['human'].percent).toBe(50);
-            expect(result.breakdown['ai'].percent).toBe(50);
-            expect(result.utilizationPercent).toBe(10);
-        });
-        it('should pass through maxContextTokens and instructionTokens', () => {
-            const result = buildContextAnalytics([], {
-                maxContextTokens: 4096,
-                instructionTokens: 200,
-            });
-            expect(result.maxContextTokens).toBe(4096);
-            expect(result.instructionTokens).toBe(200);
-            expect(result.messageCount).toBe(0);
-            expect(result.totalTokens).toBe(0);
-        });
-    });
-    describe('with cross-package or plain objects (defensive handling)', () => {
-        it('should resolve type via _getType when getType is missing', () => {
-            // Simulates a message from a different @langchain/core installation
-            // where instanceof fails but _getType still works
-            const fakeMsg = {
-                content: 'hello',
-                _getType: () => 'human',
-                // Deliberately no getType
-            };
-            const result = buildContextAnalytics([fakeMsg], { tokenCounter: () => 5 });
-            expect(result.messageCount).toBe(1);
-            expect(result.breakdown['human']).toBeDefined();
-            expect(result.breakdown['human'].tokens).toBe(5);
-        });
-        it('should fall back to type field when both getType and _getType are missing', () => {
-            // Simulates a fully serialized message (e.g., from JSON deserialization)
-            const plainObj = {
-                content: 'test message',
-                type: 'ai',
-            };
-            const result = buildContextAnalytics([plainObj], { tokenCounter: () => 10 });
-            expect(result.breakdown['ai']).toBeDefined();
-        });
-        it('should label as unknown when no type information is available', () => {
-            const bareObj = { content: 'orphan' };
-            const result = buildContextAnalytics([bareObj], { tokenCounter: () => 3 });
-            expect(result.breakdown['unknown']).toBeDefined();
-            expect(result.totalTokens).toBe(3);
-        });
-        it('should estimate tokens from content when tokenCounter throws', () => {
-            const messages = [new HumanMessage('twelve chars')]; // 12 chars -> ceil(12/4) = 3
-            const tokenCounter = jest.fn(() => {
-                throw new Error('counter failed');
-            });
-            const result = buildContextAnalytics(messages, { tokenCounter });
-            expect(result.totalTokens).toBe(Math.ceil('twelve chars'.length / 4));
-        });
-        it('should estimate tokens from JSON-stringified content for structured content', () => {
-            const msg = new HumanMessage({
-                content: [{ type: 'text', text: 'hi' }],
-            });
-            const tokenCounter = jest.fn(() => {
-                throw new Error('counter failed');
-            });
-            const result = buildContextAnalytics([msg], { tokenCounter });
-            const expectedContent = JSON.stringify([{ type: 'text', text: 'hi' }]);
-            expect(result.totalTokens).toBe(Math.ceil(expectedContent.length / 4));
-        });
-    });
-    describe('edge cases', () => {
-        it('should handle empty messages array', () => {
-            const result = buildContextAnalytics([], {});
-            expect(result.messageCount).toBe(0);
-            expect(result.totalTokens).toBe(0);
-            expect(result.breakdown).toEqual({});
-        });
-        it('should handle zero maxContextTokens without dividing by zero', () => {
-            const result = buildContextAnalytics([new HumanMessage('x')], {
-                tokenCounter: () => 100,
-                maxContextTokens: 0,
-            });
-            expect(result.utilizationPercent).toBeUndefined();
-        });
-        it('should handle undefined maxContextTokens', () => {
-            const result = buildContextAnalytics([new HumanMessage('x')], {
-                tokenCounter: () => 100,
-            });
-            expect(result.utilizationPercent).toBeUndefined();
-        });
-        it('should handle large message arrays efficiently', () => {
-            const messages = Array.from({ length: 1000 }, (_, i) => i % 2 === 0 ? new HumanMessage(`msg ${i}`) : new AIMessage(`reply ${i}`));
-            const start = Date.now();
-            const result = buildContextAnalytics(messages, {
-                tokenCounter: () => 10,
-            });
-            const elapsed = Date.now() - start;
-            expect(result.messageCount).toBe(1000);
-            expect(result.totalTokens).toBe(10000);
-            // Should complete in well under 1 second
-            expect(elapsed).toBeLessThan(1000);
-        });
-    });
-});
-//# sourceMappingURL=contextAnalytics.test.js.map

package/src/utils/events.js

@@ -1,26 +0,0 @@
-/* eslint-disable no-console */
-// src/utils/events.ts
-import { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';
-/**
- * Safely dispatches a custom event and properly awaits it to avoid
- * race conditions where events are dispatched after run cleanup.
- */
-export async function safeDispatchCustomEvent(event, payload, config) {
-    try {
-        await dispatchCustomEvent(event, payload, config);
-    }
-    catch (e) {
-        // Check if this is the known EventStreamCallbackHandler error
-        if (e instanceof Error &&
-            e.message.includes('handleCustomEvent: Run ID') &&
-            e.message.includes('not found in run map')) {
-            // Suppress this specific error - it's expected during parallel execution
-            // when EventStreamCallbackHandler loses track of run IDs
-            // console.debug('Suppressed error dispatching custom event:', e);
-            return;
-        }
-        // Log other errors
-        console.error('Error dispatching custom event:', e);
-    }
-}
-//# sourceMappingURL=events.js.map

package/src/utils/graph.js

@@ -1,11 +0,0 @@
-export const resetIfNotEmpty = (value, resetValue) => {
-    if (Array.isArray(value)) {
-        return value.length > 0 ? resetValue : value;
-    }
-    if (value instanceof Set || value instanceof Map) {
-        return value.size > 0 ? resetValue : value;
-    }
-    return value !== undefined ? resetValue : value;
-};
-export const joinKeys = (args) => args.join('_');
-//# sourceMappingURL=graph.js.map

package/src/utils/handlers.js

@@ -1,65 +0,0 @@
-/**
- * Multi-Agent Handler Utilities
- *
- * Provides a simple helper to create handlers with content aggregation for multi-agent scripts.
- *
- * Usage:
- * ```typescript
- * const { contentParts, aggregateContent, handlers } = createHandlers();
- *
- * // With callbacks
- * const { contentParts, aggregateContent, handlers } = createHandlers({
- *   onRunStep: (event, data) => console.log('Step:', data),
- *   onRunStepCompleted: (event, data) => console.log('Completed:', data)
- * });
- * ```
- */
-import { GraphEvents } from '@/common';
-import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
-import { ToolEndHandler, ModelEndHandler } from '@/events';
-/**
- * Creates handlers with content aggregation for multi-agent scripts
- */
-export function createHandlers(callbacks) {
-    // Set up content aggregator
-    const { contentParts, aggregateContent } = createContentAggregator();
-    // Create the handlers object
-    const handlers = {
-        [GraphEvents.TOOL_END]: new ToolEndHandler(),
-        [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
-        [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
-        [GraphEvents.ON_RUN_STEP]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-                callbacks?.onRunStep?.(event, data);
-            },
-        },
-        [GraphEvents.ON_RUN_STEP_COMPLETED]: {
-            handle: (event, data) => {
-                aggregateContent({
-                    event,
-                    data: data,
-                });
-                callbacks?.onRunStepCompleted?.(event, data);
-            },
-        },
-        [GraphEvents.ON_RUN_STEP_DELTA]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-                callbacks?.onRunStepDelta?.(event, data);
-            },
-        },
-        [GraphEvents.ON_MESSAGE_DELTA]: {
-            handle: (event, data) => {
-                aggregateContent({ event, data: data });
-                callbacks?.onMessageDelta?.(event, data);
-            },
-        },
-    };
-    return {
-        contentParts,
-        aggregateContent,
-        handlers,
-    };
-}
-//# sourceMappingURL=handlers.js.map

package/src/utils/index.js

@@ -1,10 +0,0 @@
-export * from './graph';
-export * from './llm';
-export * from './misc';
-export * from './handlers';
-export * from './run';
-export * from './tokens';
-export * from './toonFormat';
-export * from './contextAnalytics';
-export * from './schema';
-//# sourceMappingURL=index.js.map

package/src/utils/llm.js

@@ -1,21 +0,0 @@
-// src/utils/llm.ts
-import { Providers } from '@/common';
-export function isOpenAILike(provider) {
-    if (provider == null) {
-        return false;
-    }
-    return [
-        Providers.OPENAI,
-        Providers.AZURE,
-        Providers.OPENROUTER,
-        Providers.XAI,
-        Providers.DEEPSEEK,
-    ].includes(provider);
-}
-export function isGoogleLike(provider) {
-    if (provider == null) {
-        return false;
-    }
-    return [Providers.GOOGLE, Providers.VERTEXAI].includes(provider);
-}
-//# sourceMappingURL=llm.js.map