illuma-agents 1.0.16 → 1.0.18

package/src/tools/__tests__/ProgrammaticToolCalling.test.ts

@@ -12,6 +12,7 @@ import {
   filterToolsByUsage,
   executeTools,
   normalizeToPythonIdentifier,
+  unwrapToolResponse,
 } from '../ProgrammaticToolCalling';
 import {
   createProgrammaticToolRegistry,
@@ -228,6 +229,160 @@ describe('ProgrammaticToolCalling', () => {
     });
   });
 
+  describe('unwrapToolResponse', () => {
+    describe('non-MCP tools', () => {
+      it('returns result as-is for non-MCP tools', () => {
+        const result = { temperature: 65, condition: 'Foggy' };
+        expect(unwrapToolResponse(result, false)).toEqual(result);
+      });
+
+      it('returns string as-is for non-MCP tools', () => {
+        expect(unwrapToolResponse('plain string', false)).toBe('plain string');
+      });
+
+      it('returns array as-is for non-MCP tools', () => {
+        const result = [1, 2, 3];
+        expect(unwrapToolResponse(result, false)).toEqual(result);
+      });
+    });
+
+    describe('MCP tools - tuple format [content, artifacts]', () => {
+      it('extracts string content from tuple', () => {
+        const result = ['Hello world', { artifacts: [] }];
+        expect(unwrapToolResponse(result, true)).toBe('Hello world');
+      });
+
+      it('parses JSON string content from tuple', () => {
+        const result = ['{"temperature": 65}', { artifacts: [] }];
+        expect(unwrapToolResponse(result, true)).toEqual({ temperature: 65 });
+      });
+
+      it('parses JSON array string content from tuple', () => {
+        const result = ['[1, 2, 3]', { artifacts: [] }];
+        expect(unwrapToolResponse(result, true)).toEqual([1, 2, 3]);
+      });
+
+      it('extracts text from single content block in tuple', () => {
+        const result = [{ type: 'text', text: 'Spreadsheet info here' }, {}];
+        expect(unwrapToolResponse(result, true)).toBe('Spreadsheet info here');
+      });
+
+      it('extracts and parses JSON from single content block in tuple', () => {
+        const result = [
+          { type: 'text', text: '{"id": "123", "name": "Test"}' },
+          {},
+        ];
+        expect(unwrapToolResponse(result, true)).toEqual({
+          id: '123',
+          name: 'Test',
+        });
+      });
+
+      it('extracts text from array of content blocks in tuple', () => {
+        const result = [
+          [
+            { type: 'text', text: 'Line 1' },
+            { type: 'text', text: 'Line 2' },
+          ],
+          {},
+        ];
+        expect(unwrapToolResponse(result, true)).toBe('Line 1\nLine 2');
+      });
+
+      it('returns object content as-is when not a text block', () => {
+        const result = [{ temperature: 65, condition: 'Foggy' }, {}];
+        expect(unwrapToolResponse(result, true)).toEqual({
+          temperature: 65,
+          condition: 'Foggy',
+        });
+      });
+    });
+
+    describe('MCP tools - single content block (not in tuple)', () => {
+      it('extracts text from single content block object', () => {
+        const result = { type: 'text', text: 'No data found in range' };
+        expect(unwrapToolResponse(result, true)).toBe('No data found in range');
+      });
+
+      it('extracts and parses JSON from single content block object', () => {
+        const result = {
+          type: 'text',
+          text: '{"sheets": [{"name": "raw_data"}]}',
+        };
+        expect(unwrapToolResponse(result, true)).toEqual({
+          sheets: [{ name: 'raw_data' }],
+        });
+      });
+
+      it('handles real-world MCP spreadsheet response', () => {
+        const result = {
+          type: 'text',
+          text: 'Spreadsheet: "NYC Taxi - Top Pickup Neighborhoods" (ID: abc123)\nSheets (2):\n  - "raw_data" (ID: 123) | Size: 1000x26',
+        };
+        expect(unwrapToolResponse(result, true)).toBe(
+          'Spreadsheet: "NYC Taxi - Top Pickup Neighborhoods" (ID: abc123)\nSheets (2):\n  - "raw_data" (ID: 123) | Size: 1000x26'
+        );
+      });
+
+      it('handles real-world MCP no data response', () => {
+        const result = {
+          type: 'text',
+          text: 'No data found in range \'raw_data!A1:D25\' for user@example.com.',
+        };
+        expect(unwrapToolResponse(result, true)).toBe(
+          'No data found in range \'raw_data!A1:D25\' for user@example.com.'
+        );
+      });
+    });
+
+    describe('MCP tools - array of content blocks (not in tuple)', () => {
+      it('extracts text from array of content blocks', () => {
+        const result = [
+          { type: 'text', text: 'First block' },
+          { type: 'text', text: 'Second block' },
+        ];
+        expect(unwrapToolResponse(result, true)).toBe(
+          'First block\nSecond block'
+        );
+      });
+
+      it('filters out non-text blocks', () => {
+        const result = [
+          { type: 'text', text: 'Text content' },
+          { type: 'image', data: 'base64...' },
+          { type: 'text', text: 'More text' },
+        ];
+        expect(unwrapToolResponse(result, true)).toBe(
+          'Text content\nMore text'
+        );
+      });
+    });
+
+    describe('edge cases', () => {
+      it('returns non-text block object as-is', () => {
+        const result = { type: 'image', data: 'base64...' };
+        expect(unwrapToolResponse(result, true)).toEqual(result);
+      });
+
+      it('handles empty array', () => {
+        expect(unwrapToolResponse([], true)).toEqual([]);
+      });
+
+      it('handles malformed JSON in text block gracefully', () => {
+        const result = { type: 'text', text: '{ invalid json }' };
+        expect(unwrapToolResponse(result, true)).toBe('{ invalid json }');
+      });
+
+      it('handles null', () => {
+        expect(unwrapToolResponse(null, true)).toBe(null);
+      });
+
+      it('handles undefined', () => {
+        expect(unwrapToolResponse(undefined, true)).toBe(undefined);
+      });
+    });
+  });
+
   describe('extractUsedToolNames', () => {
     const createToolMap = (names: string[]): Map<string, string> => {
       const map = new Map<string, string>();

package/src/tools/search/jina-reranker.test.ts

@@ -1,18 +1,22 @@
-import { JinaReranker } from './rerankers';
+import { JinaReranker, createReranker } from './rerankers';
 import { createDefaultLogger } from './utils';
 
+// Helper to access private apiUrl property for testing
+const getApiUrl = (reranker: JinaReranker): string =>
+  (reranker as unknown as { apiUrl: string }).apiUrl;
+
 describe('JinaReranker', () => {
   const mockLogger = createDefaultLogger();
-  
+
   describe('constructor', () => {
     it('should use default API URL when no apiUrl is provided', () => {
       const reranker = new JinaReranker({
         apiKey: 'test-key',
         logger: mockLogger,
       });
-      
+
       // Access private property for testing
-      const apiUrl = (reranker as any).apiUrl;
+      const apiUrl = getApiUrl(reranker);
       expect(apiUrl).toBe('https://api.jina.ai/v1/rerank');
     });
 
@@ -23,25 +27,25 @@ describe('JinaReranker', () => {
         apiUrl: customUrl,
         logger: mockLogger,
       });
-      
-      const apiUrl = (reranker as any).apiUrl;
+
+      const apiUrl = getApiUrl(reranker);
       expect(apiUrl).toBe(customUrl);
     });
 
     it('should use environment variable JINA_API_URL when available', () => {
       const originalEnv = process.env.JINA_API_URL;
       process.env.JINA_API_URL = 'https://env-jina-endpoint.com/v1/rerank';
-      
+
       const reranker = new JinaReranker({
         apiKey: 'test-key',
         logger: mockLogger,
       });
-      
-      const apiUrl = (reranker as any).apiUrl;
+
+      const apiUrl = getApiUrl(reranker);
       expect(apiUrl).toBe('https://env-jina-endpoint.com/v1/rerank');
-      
+
       // Restore original environment
-      if (originalEnv) {
+      if (originalEnv != null && originalEnv !== '') {
         process.env.JINA_API_URL = originalEnv;
       } else {
         delete process.env.JINA_API_URL;
@@ -51,19 +55,19 @@ describe('JinaReranker', () => {
     it('should prioritize explicit apiUrl over environment variable', () => {
       const originalEnv = process.env.JINA_API_URL;
       process.env.JINA_API_URL = 'https://env-jina-endpoint.com/v1/rerank';
-      
+
       const customUrl = 'https://explicit-jina-endpoint.com/v1/rerank';
       const reranker = new JinaReranker({
         apiKey: 'test-key',
         apiUrl: customUrl,
         logger: mockLogger,
       });
-      
-      const apiUrl = (reranker as any).apiUrl;
+
+      const apiUrl = getApiUrl(reranker);
       expect(apiUrl).toBe(customUrl);
-      
+
       // Restore original environment
-      if (originalEnv) {
+      if (originalEnv != null && originalEnv !== '') {
         process.env.JINA_API_URL = originalEnv;
       } else {
         delete process.env.JINA_API_URL;
@@ -79,27 +83,27 @@ describe('JinaReranker', () => {
         apiUrl: customUrl,
         logger: mockLogger,
       });
-      
+
       const logSpy = jest.spyOn(mockLogger, 'debug');
-      
+
       try {
         await reranker.rerank('test query', ['document1', 'document2'], 2);
-      } catch (error) {
+      } catch (_error) {
         // Expected to fail due to missing API key, but we can check the log
       }
-      
+
       expect(logSpy).toHaveBeenCalledWith(
-        expect.stringContaining(`Reranking 2 chunks with Jina using API URL: ${customUrl}`)
+        expect.stringContaining(
+          `Reranking 2 chunks with Jina using API URL: ${customUrl}`
+        )
       );
-      
+
       logSpy.mockRestore();
     });
   });
 });
 
 describe('createReranker', () => {
-  const { createReranker } = require('./rerankers');
-  
   it('should create JinaReranker with jinaApiUrl when provided', () => {
     const customUrl = 'https://custom-jina-endpoint.com/v1/rerank';
     const reranker = createReranker({
@@ -107,9 +111,9 @@ describe('createReranker', () => {
       jinaApiKey: 'test-key',
       jinaApiUrl: customUrl,
     });
-    
+
     expect(reranker).toBeInstanceOf(JinaReranker);
-    const apiUrl = (reranker as any).apiUrl;
+    const apiUrl = getApiUrl(reranker as JinaReranker);
     expect(apiUrl).toBe(customUrl);
   });
 
@@ -118,9 +122,9 @@ describe('createReranker', () => {
       rerankerType: 'jina',
       jinaApiKey: 'test-key',
     });
-    
+
     expect(reranker).toBeInstanceOf(JinaReranker);
-    const apiUrl = (reranker as any).apiUrl;
+    const apiUrl = getApiUrl(reranker as JinaReranker);
     expect(apiUrl).toBe('https://api.jina.ai/v1/rerank');
   });
 });

package/src/tools/search/search.ts

@@ -603,7 +603,9 @@ export const createSourceProcessor = (
 
       // If content was already extracted directly (e.g., direct URL extraction), skip scraping
       if (skipScraping) {
-        logger_.debug('Skipping additional scraping - content already extracted');
+        logger_.debug(
+          'Skipping additional scraping - content already extracted'
+        );
         return result.data;
       }
 

package/src/tools/search/tool.ts

@@ -98,15 +98,21 @@ async function extractDirectUrlContent({
 
           results.push({
             position: results.length + 1,
-            title: getString(metadata.title) ?? getString(metadata.ogTitle) ?? url,
+            title:
+              getString(metadata.title) ?? getString(metadata.ogTitle) ?? url,
             link: url,
-            snippet: getString(metadata.description) ?? getString(metadata.ogDescription) ?? '',
+            snippet:
+              getString(metadata.description) ??
+              getString(metadata.ogDescription) ??
+              '',
             content: content,
             references: references,
             processed: true,
           });
         } else {
-          logger.warn(`Failed to extract content from ${url}: ${response.error}`);
+          logger.warn(
+            `Failed to extract content from ${url}: ${response.error}`
+          );
           // Still add the URL as a result, but without content
           results.push({
             position: results.length + 1,
@@ -424,15 +430,17 @@ function createTool({
     async (params, runnableConfig) => {
       const { query, date, country: _c, images, videos, news } = params;
       const country = typeof _c === 'string' && _c ? _c : undefined;
-      
+
       // Log the incoming query for debugging URL detection
       const toolLogger = createDefaultLogger();
       toolLogger.debug(`[web_search] Received query: "${query}"`);
       const detectedUrls = extractUrlsFromQuery(query);
       if (detectedUrls.length > 0) {
-        toolLogger.debug(`[web_search] Detected URLs in query: ${detectedUrls.join(', ')}`);
+        toolLogger.debug(
+          `[web_search] Detected URLs in query: ${detectedUrls.join(', ')}`
+        );
       }
-      
+
       const searchResult = await search({
         query,
         date,
@@ -452,7 +460,8 @@ function createTool({
     },
     {
       name: Constants.WEB_SEARCH,
-      description: `Real-time web search and direct URL content extraction. Results have required citation anchors.
+      description:
+        `Real-time web search and direct URL content extraction. Results have required citation anchors.
 
 **CAPABILITIES:**
 - Search: Query the web for information on any topic

package/src/types/tools.ts

@@ -15,7 +15,9 @@ export type CustomToolCall = {
   output?: string;
 };
 
-export type GenericTool = StructuredToolInterface | RunnableToolLike;
+export type GenericTool = (StructuredToolInterface | RunnableToolLike) & {
+  mcp?: boolean;
+};
 
 export type ToolMap = Map<string, GenericTool>;
 export type ToolRefs = {

package/src/utils/contextAnalytics.ts

@@ -0,0 +1,103 @@
+/**
+ * Context Analytics Utility
+ *
+ * Provides context analytics data for observability/traces.
+ * No console logging - just data structures for event emission.
+ */
+
+import type { BaseMessage } from '@langchain/core/messages';
+import type { TokenCounter } from '@/types/run';
+
+/**
+ * Context analytics data for traces
+ */
+export interface ContextAnalytics {
+  /** Total messages in context */
+  messageCount: number;
+  /** Total tokens in context */
+  totalTokens: number;
+  /** Maximum allowed context tokens */
+  maxContextTokens?: number;
+  /** Instruction/system tokens */
+  instructionTokens?: number;
+  /** Context utilization percentage (0-100) */
+  utilizationPercent?: number;
+  /** Breakdown by message type */
+  breakdown?: Record<string, { tokens: number; percent: number }>;
+}
+
+/**
+ * Build context analytics for traces (no logging)
+ */
+export function buildContextAnalytics(
+  messages: BaseMessage[],
+  options: {
+    tokenCounter?: TokenCounter;
+    maxContextTokens?: number;
+    instructionTokens?: number;
+    indexTokenCountMap?: Record<string, number | undefined>;
+  }
+): ContextAnalytics {
+  const {
+    tokenCounter,
+    maxContextTokens,
+    instructionTokens,
+    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();
+
+    let tokens = 0;
+    if (indexTokenCountMap && indexTokenCountMap[i] != null) {
+      tokens = indexTokenCountMap[i]!;
+    } else if (tokenCounter) {
+      try {
+        tokens = tokenCounter(msg);
+      } catch {
+        // Estimate from content length
+        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;
+  }
+
+  // Calculate percentages
+  for (const type of Object.keys(breakdown)) {
+    breakdown[type].percent =
+      totalTokens > 0
+        ? Math.round((breakdown[type].tokens / totalTokens) * 1000) / 10
+        : 0;
+  }
+
+  // Calculate utilization
+  let utilizationPercent: number | undefined;
+  if (maxContextTokens && maxContextTokens > 0) {
+    utilizationPercent =
+      Math.round((totalTokens / maxContextTokens) * 1000) / 10;
+  }
+
+  return {
+    messageCount: messages.length,
+    totalTokens,
+    maxContextTokens,
+    instructionTokens,
+    utilizationPercent,
+    breakdown,
+  };
+}

package/src/utils/index.ts

@@ -4,3 +4,5 @@ export * from './misc';
 export * from './handlers';
 export * from './run';
 export * from './tokens';
+export * from './toonFormat';
+export * from './contextAnalytics';

package/src/utils/llmConfig.ts

@@ -56,7 +56,9 @@ export const llmConfigs: Record<string, t.LLMConfig | undefined> = {
     provider: Providers.OPENROUTER,
     streaming: true,
     streamUsage: true,
-    model: 'anthropic/claude-sonnet-4',
+    // model: 'anthropic/claude-sonnet-4',
+    // model: 'moonshotai/kimi-k2-thinking',
+    model: 'google/gemini-3-pro-preview',
     apiKey: process.env.OPENROUTER_API_KEY,
     configuration: {
       baseURL: process.env.OPENROUTER_BASE_URL,
@@ -145,9 +147,14 @@ export const llmConfigs: Record<string, t.LLMConfig | undefined> = {
   [Providers.VERTEXAI]: {
     provider: Providers.VERTEXAI,
     model: 'gemini-2.5-flash',
+    // model: 'gemini-2.5-pro',
     streaming: true,
     streamUsage: true,
     keyFile: process.env.VERTEXAI_KEY_FILE,
+    // maxRetries: 2,
+    // location: 'global',
+    // thinkingBudget: -1,
+    // includeThoughts: true,
   } as t.VertexAIClientOptions & t.LLMConfig,
   [Providers.GOOGLE]: {
     provider: Providers.GOOGLE,

package/src/utils/run.ts

@@ -57,9 +57,10 @@ export class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {
   ): 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 childCallbacks =
+        typeof runManager?.getChild === 'function'
+          ? runManager.getChild()
+          : undefined;
       const childConfig = patchConfig(config, {
         callbacks: childCallbacks,
       });
@@ -102,4 +103,4 @@ export class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {
 
     return returnValue;
   }
-}
+}