@illuma-ai/agents 1.0.90 → 1.0.93

package/src/utils/contextAnalytics.test.js

@@ -0,0 +1,166 @@
+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/contextAnalytics.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextAnalytics.test.js","sourceRoot":"","sources":["contextAnalytics.test.ts"],"names":[],"mappings":"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"}

package/src/utils/contextAnalytics.test.ts

@@ -0,0 +1,222 @@
+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: (): string => 'human',
+        // Deliberately no getType
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const result = buildContextAnalytics([fakeMsg as any], {
+        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',
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const result = buildContextAnalytics([plainObj as any], {
+        tokenCounter: () => 10,
+      });
+
+      expect(result.breakdown!['ai']).toBeDefined();
+    });
+
+    it('should label as unknown when no type information is available', () => {
+      const bareObj = { content: 'orphan' };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const result = buildContextAnalytics([bareObj as any], {
+        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);
+    });
+  });
+});

package/src/utils/contextAnalytics.ts

@@ -8,9 +8,7 @@
 import type { BaseMessage } from '@langchain/core/messages';
 import type { TokenCounter } from '@/types/run';
 
-/**
- * Context analytics data for traces
- */
+/** Context analytics data for traces */
 export interface ContextAnalytics {
   /** Total messages in context */
   messageCount: number;
@@ -27,7 +25,31 @@ export interface ContextAnalytics {
 }
 
 /**
- * Build context analytics for traces (no logging)
+ * 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: BaseMessage): string {
+  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 as unknown as Record<string, unknown>).type as string) ?? '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: BaseMessage[],
@@ -45,13 +67,12 @@ export function buildContextAnalytics(
     indexTokenCountMap,
   } = options;
 
-  // Calculate total tokens
   let totalTokens = 0;
   const breakdown: Record<string, { tokens: number; percent: number }> = {};
 
   for (let i = 0; i < messages.length; i++) {
     const msg = messages[i];
-    const type = msg.getType();
+    const type = resolveMessageType(msg);
 
     let tokens = 0;
     if (indexTokenCountMap && indexTokenCountMap[i] != null) {
@@ -60,7 +81,6 @@ export function buildContextAnalytics(
       try {
         tokens = tokenCounter(msg);
       } catch {
-        // Estimate from content length
         const content =
           typeof msg.content === 'string'
             ? msg.content
@@ -77,7 +97,6 @@ export function buildContextAnalytics(
     breakdown[type].tokens += tokens;
   }
 
-  // Calculate percentages
   for (const type of Object.keys(breakdown)) {
     breakdown[type].percent =
       totalTokens > 0
@@ -85,7 +104,6 @@ export function buildContextAnalytics(
         : 0;
   }
 
-  // Calculate utilization
   let utilizationPercent: number | undefined;
   if (maxContextTokens && maxContextTokens > 0) {
     utilizationPercent =

package/src/utils/events.js

@@ -0,0 +1,26 @@
+/* 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/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["events.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,sBAAsB;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAGzE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAAa,EACb,OAAgB,EAChB,MAAuB;IAEvB,IAAI,CAAC;QACH,MAAM,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,8DAA8D;QAC9D,IACE,CAAC,YAAY,KAAK;YAClB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC;YAC/C,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAC1C,CAAC;YACD,yEAAyE;YACzE,yDAAyD;YACzD,kEAAkE;YAClE,OAAO;QACT,CAAC;QACD,mBAAmB;QACnB,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,CAAC,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}

package/src/utils/graph.js

@@ -0,0 +1,11 @@
+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/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["graph.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,CAAI,KAAQ,EAAE,UAAa,EAAK,EAAE;IAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;IAC/C,CAAC;IACD,IAAI,KAAK,YAAY,GAAG,IAAI,KAAK,YAAY,GAAG,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;AAClD,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAqC,EAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC"}

package/src/utils/handlers.js

@@ -0,0 +1,65 @@
+/**
+ * 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/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAmB3D;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,SAA4B;IAOzD,4BAA4B;IAC5B,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,GAAG,uBAAuB,EAAE,CAAC;IAErE,6BAA6B;IAC7B,MAAM,QAAQ,GAAG;QACf,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,IAAI,cAAc,EAAE;QAC5C,CAAC,WAAW,CAAC,cAAc,CAAC,EAAE,IAAI,eAAe,EAAE;QACnD,CAAC,WAAW,CAAC,iBAAiB,CAAC,EAAE,IAAI,sBAAsB,EAAE;QAE7D,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE;YACzB,MAAM,EAAE,CACN,KAA8B,EAC9B,IAAuB,EACjB,EAAE;gBACR,gBAAgB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAiB,EAAE,CAAC,CAAC;gBACrD,SAAS,EAAE,SAAS,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACtC,CAAC;SACF;QAED,CAAC,WAAW,CAAC,qBAAqB,CAAC,EAAE;YACnC,MAAM,EAAE,CACN,KAAwC,EACxC,IAAuB,EACjB,EAAE;gBACR,gBAAgB,CAAC;oBACf,KAAK;oBACL,IAAI,EAAE,IAA6C;iBACpD,CAAC,CAAC;gBACH,SAAS,EAAE,kBAAkB,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC/C,CAAC;SACF;QAED,CAAC,WAAW,CAAC,iBAAiB,CAAC,EAAE;YAC/B,MAAM,EAAE,CACN,KAAoC,EACpC,IAAuB,EACjB,EAAE;gBACR,gBAAgB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAA2B,EAAE,CAAC,CAAC;gBAC/D,SAAS,EAAE,cAAc,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC3C,CAAC;SACF;QAED,CAAC,WAAW,CAAC,gBAAgB,CAAC,EAAE;YAC9B,MAAM,EAAE,CACN,KAAmC,EACnC,IAAuB,EACjB,EAAE;gBACR,gBAAgB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAA2B,EAAE,CAAC,CAAC;gBAC/D,SAAS,EAAE,cAAc,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC3C,CAAC;SACF;KACF,CAAC;IAEF,OAAO;QACL,YAAY;QACZ,gBAAgB;QAChB,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/src/utils/index.js

@@ -0,0 +1,10 @@
+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/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC"}

package/src/utils/index.ts

@@ -7,3 +7,4 @@ export * from './tokens';
 export * from './toonFormat';
 export * from './contextAnalytics';
 export * from './schema';
+export * from './toolCallContinuation';

package/src/utils/llm.js

@@ -0,0 +1,21 @@
+// 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

package/src/utils/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["llm.ts"],"names":[],"mappings":"AAAA,mBAAmB;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,MAAM,UAAU,YAAY,CAAC,QAA6B;IACxD,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OACE;QACE,SAAS,CAAC,MAAM;QAChB,SAAS,CAAC,KAAK;QACf,SAAS,CAAC,UAAU;QACpB,SAAS,CAAC,GAAG;QACb,SAAS,CAAC,QAAQ;KAErB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAA6B;IACxD,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAc,CAAC,QAAQ,CAClE,QAAQ,CACT,CAAC;AACJ,CAAC"}