illuma-agents 1.0.6 → 1.0.8

package/dist/types/llm/google/utils/common.d.ts

@@ -1,7 +1,16 @@
 import { POSSIBLE_ROLES, type Part, type Content, type EnhancedGenerateContentResponse, type FunctionDeclarationsTool as GoogleGenerativeAIFunctionDeclarationsTool } from '@google/generative-ai';
 import { BaseMessage, UsageMetadata } from '@langchain/core/messages';
 import { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { ChatResult } from '@langchain/core/outputs';
 import { GoogleGenerativeAIToolType } from '../types';
+export declare const _FUNCTION_CALL_THOUGHT_SIGNATURES_MAP_KEY = "__gemini_function_call_thought_signatures__";
+/**
+ * Executes a function immediately and returns its result.
+ * Functional utility similar to an Immediately Invoked Function Expression (IIFE).
+ * @param fn The function to execute.
+ * @returns The result of invoking fn.
+ */
+export declare const iife: <T>(fn: () => T) => T;
 export declare function getMessageAuthor(message: BaseMessage): string;
 /**
  * Maps a message type to a Google Generative AI chat author.
@@ -10,10 +19,16 @@ export declare function getMessageAuthor(message: BaseMessage): string;
  * @returns The message type mapped to a Google Generative AI chat author.
  */
 export declare function convertAuthorToRole(author: string): (typeof POSSIBLE_ROLES)[number];
-export declare function convertMessageContentToParts(message: BaseMessage, isMultimodalModel: boolean, previousMessages: BaseMessage[]): Part[];
-export declare function convertBaseMessagesToContent(messages: BaseMessage[], isMultimodalModel: boolean, convertSystemMessageToHumanContent?: boolean): Content[] | undefined;
+export declare function convertMessageContentToParts(message: BaseMessage, isMultimodalModel: boolean, previousMessages: BaseMessage[], model?: string): Part[];
+export declare function convertBaseMessagesToContent(messages: BaseMessage[], isMultimodalModel: boolean, convertSystemMessageToHumanContent?: boolean, model?: string): Content[] | undefined;
 export declare function convertResponseContentToChatGenerationChunk(response: EnhancedGenerateContentResponse, extra: {
     usageMetadata?: UsageMetadata | undefined;
     index: number;
 }): ChatGenerationChunk | null;
+/**
+ * Maps a Google GenerateContentResult to a LangChain ChatResult
+ */
+export declare function mapGenerateContentResultToChatResult(response: EnhancedGenerateContentResponse, extra?: {
+    usageMetadata: UsageMetadata | undefined;
+}): ChatResult;
 export declare function convertToGenerativeAITools(tools: GoogleGenerativeAIToolType[]): GoogleGenerativeAIFunctionDeclarationsTool[];

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

@@ -120,9 +120,15 @@ export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap
 export declare function shiftIndexTokenCountMap(indexTokenCountMap: Record<number, number>, instructionsTokenCount: number): Record<number, number>;
 /**
  * Ensures compatibility when switching from a non-thinking agent to a thinking-enabled agent.
- * Converts AI messages with tool calls (that lack thinking blocks) into buffer strings,
+ * Converts AI messages with tool calls (that lack thinking/reasoning blocks) into buffer strings,
  * avoiding the thinking block signature requirement.
  *
+ * Recognizes the following as valid thinking/reasoning blocks:
+ * - ContentTypes.THINKING (Anthropic)
+ * - ContentTypes.REASONING_CONTENT (Bedrock)
+ * - ContentTypes.REASONING (VertexAI / Google)
+ * - 'redacted_thinking'
+ *
  * @param messages - Array of messages to process
  * @param provider - The provider being used (unused but kept for future compatibility)
  * @returns The messages array with tool sequences converted to buffer strings if necessary

package/dist/types/tools/ToolNode.d.ts

@@ -1,4 +1,5 @@
-import { END, MessagesAnnotation } from '@langchain/langgraph';
+import { ToolCall } from '@langchain/core/messages/tool';
+import { END, Command, MessagesAnnotation } from '@langchain/langgraph';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
@@ -8,6 +9,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolMap;
     private loadRuntimeTools?;
     handleToolErrors: boolean;
+    trace: boolean;
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
     private toolUsageCount;
@@ -17,6 +19,12 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * @returns A ReadonlyMap where keys are tool names and values are their usage counts.
      */
     getToolUsageCounts(): ReadonlyMap<string, number>;
+    /**
+     * Runs a single tool call with error handling
+     */
+    protected runTool(call: ToolCall, config: RunnableConfig): Promise<BaseMessage | Command>;
     protected run(input: any, config: RunnableConfig): Promise<T>;
+    private isSendInput;
+    private isMessagesState;
 }
 export declare function toolsCondition<T extends string>(state: BaseMessage[] | typeof MessagesAnnotation.State, toolNode: T, invokedToolIds?: Set<string>): T | typeof END;

package/dist/types/types/stream.d.ts

@@ -74,7 +74,7 @@ export type ToolErrorData = {
     name: string;
     error?: Error;
 } & Pick<ToolEndData, 'input'>;
-export type ToolEndCallback = (data: ToolEndData, metadata?: Record<string, unknown>) => void;
+export type ToolEndCallback = (data: ToolEndData, metadata?: Record<string, unknown>) => Promise<void>;
 export type ProcessedToolCall = {
     name: string;
     args: string | Record<string, unknown>;

package/dist/types/types/tools.d.ts

@@ -24,7 +24,7 @@ export type ToolNodeOptions = {
     handleToolErrors?: boolean;
     loadRuntimeTools?: ToolRefGenerator;
     toolCallStepIds?: Map<string, string>;
-    errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => void;
+    errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<void>;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -94,8 +94,8 @@
     "@langchain/aws": "^0.1.15",
     "@langchain/core": "^0.3.79",
     "@langchain/deepseek": "^0.0.2",
-    "@langchain/google-genai": "^0.2.13",
-    "@langchain/google-vertexai": "^0.2.13",
+    "@langchain/google-genai": "^0.2.18",
+    "@langchain/google-vertexai": "^0.2.18",
     "@langchain/langgraph": "^0.4.9",
     "@langchain/mistralai": "^0.2.1",
     "@langchain/ollama": "^0.2.3",

package/src/events.ts

@@ -6,6 +6,7 @@ import type {
   BaseMessageFields,
 } from '@langchain/core/messages';
 import type { MultiAgentGraph, StandardGraph } from '@/graphs';
+import type { Logger } from 'winston';
 import type * as t from '@/types';
 import { handleToolCalls } from '@/tools/handlers';
 import { Providers } from '@/common';
@@ -74,12 +75,15 @@ export class ModelEndHandler implements t.EventHandler {
 
 export class ToolEndHandler implements t.EventHandler {
   private callback?: t.ToolEndCallback;
+  private logger?: Logger;
   private omitOutput?: (name?: string) => boolean;
   constructor(
     callback?: t.ToolEndCallback,
+    logger?: Logger,
     omitOutput?: (name?: string) => boolean
   ) {
     this.callback = callback;
+    this.logger = logger;
     this.omitOutput = omitOutput;
   }
   async handle(
@@ -88,23 +92,41 @@ export class ToolEndHandler implements t.EventHandler {
     metadata?: Record<string, unknown>,
     graph?: StandardGraph | MultiAgentGraph
   ): Promise<void> {
-    if (!graph || !metadata) {
-      console.warn(`Graph or metadata not found in ${event} event`);
-      return;
-    }
+    try {
+      if (!graph || !metadata) {
+        if (this.logger) {
+          this.logger.warn(`Graph or metadata not found in ${event} event`);
+        } else {
+          console.warn(`Graph or metadata not found in ${event} event`);
+        }
+        return;
+      }
 
-    const toolEndData = data as t.ToolEndData | undefined;
-    if (!toolEndData?.output) {
-      console.warn('No output found in tool_end event');
-      return;
-    }
+      const toolEndData = data as t.ToolEndData | undefined;
+      if (!toolEndData?.output) {
+        if (this.logger) {
+          this.logger.warn('No output found in tool_end event');
+        } else {
+          console.warn('No output found in tool_end event');
+        }
+        return;
+      }
 
-    this.callback?.(toolEndData, metadata);
-    await graph.handleToolCallCompleted(
-      { input: toolEndData.input, output: toolEndData.output },
-      metadata,
-      this.omitOutput?.((toolEndData.output as ToolMessage | undefined)?.name)
-    );
+      if (this.callback) {
+        await this.callback(toolEndData, metadata);
+      }
+      await graph.handleToolCallCompleted(
+        { input: toolEndData.input, output: toolEndData.output },
+        metadata,
+        this.omitOutput?.((toolEndData.output as ToolMessage | undefined)?.name)
+      );
+    } catch (error) {
+      if (this.logger) {
+        this.logger.error('Error handling tool_end event:', error);
+      } else {
+        console.error('Error handling tool_end event:', error);
+      }
+    }
   }
 }
 

package/src/llm/google/index.ts

@@ -11,15 +11,30 @@ import type {
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import type { BaseMessage, UsageMetadata } from '@langchain/core/messages';
 import type { GeminiGenerationConfig } from '@langchain/google-common';
-import type { GeminiApiUsageMetadata } from './types';
+import type { GeminiApiUsageMetadata, InputTokenDetails } from './types';
 import type { GoogleClientOptions } from '@/types';
 import {
   convertResponseContentToChatGenerationChunk,
   convertBaseMessagesToContent,
+  mapGenerateContentResultToChatResult,
 } from './utils/common';
 
 export class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
   thinkingConfig?: GeminiGenerationConfig['thinkingConfig'];
+
+  /**
+   * Override to add gemini-3 model support for multimodal and function calling thought signatures
+   */
+  get _isMultimodalModel(): boolean {
+    return (
+      this.model.startsWith('gemini-1.5') ||
+      this.model.startsWith('gemini-2') ||
+      (this.model.startsWith('gemma-3-') &&
+        !this.model.startsWith('gemma-3-1b')) ||
+      this.model.startsWith('gemini-3')
+    );
+  }
+
   constructor(fields: GoogleClientOptions) {
     super(fields);
 
@@ -111,6 +126,59 @@ export class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
     return 'IllumaGoogleGenerativeAI';
   }
 
+  /**
+   * Helper function to convert Gemini API usage metadata to LangChain format
+   * Includes support for cached tokens and tier-based tracking for gemini-3-pro-preview
+   */
+  private _convertToUsageMetadata(
+    usageMetadata: GeminiApiUsageMetadata | undefined,
+    model: string
+  ): UsageMetadata | undefined {
+    if (!usageMetadata) {
+      return undefined;
+    }
+
+    const output: UsageMetadata = {
+      input_tokens: usageMetadata.promptTokenCount ?? 0,
+      output_tokens:
+        (usageMetadata.candidatesTokenCount ?? 0) +
+        (usageMetadata.thoughtsTokenCount ?? 0),
+      total_tokens: usageMetadata.totalTokenCount ?? 0,
+    };
+
+    if (usageMetadata.cachedContentTokenCount) {
+      output.input_token_details ??= {};
+      output.input_token_details.cache_read =
+        usageMetadata.cachedContentTokenCount;
+    }
+
+    // gemini-3-pro-preview has bracket based tracking of tokens per request
+    if (model === 'gemini-3-pro-preview') {
+      const over200k = Math.max(
+        0,
+        (usageMetadata.promptTokenCount ?? 0) - 200000
+      );
+      const cachedOver200k = Math.max(
+        0,
+        (usageMetadata.cachedContentTokenCount ?? 0) - 200000
+      );
+      if (over200k) {
+        output.input_token_details = {
+          ...output.input_token_details,
+          over_200k: over200k,
+        } as InputTokenDetails;
+      }
+      if (cachedOver200k) {
+        output.input_token_details = {
+          ...output.input_token_details,
+          cache_read_over_200k: cachedOver200k,
+        } as InputTokenDetails;
+      }
+    }
+
+    return output;
+  }
+
   invocationParams(
     options?: this['ParsedCallOptions']
   ): Omit<GenerateContentRequest, 'contents'> {
@@ -127,6 +195,60 @@ export class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
     return params;
   }
 
+  async _generate(
+    messages: BaseMessage[],
+    options: this['ParsedCallOptions'],
+    runManager?: CallbackManagerForLLMRun
+  ): Promise<import('@langchain/core/outputs').ChatResult> {
+    const prompt = convertBaseMessagesToContent(
+      messages,
+      this._isMultimodalModel,
+      this.useSystemInstruction,
+      this.model
+    );
+    let actualPrompt = prompt;
+    if (prompt?.[0].role === 'system') {
+      const [systemInstruction] = prompt;
+      /** @ts-ignore */
+      this.client.systemInstruction = systemInstruction;
+      actualPrompt = prompt.slice(1);
+    }
+    const parameters = this.invocationParams(options);
+    const request = {
+      ...parameters,
+      contents: actualPrompt,
+    };
+
+    const res = await this.caller.callWithOptions(
+      { signal: options.signal },
+      async () =>
+        /** @ts-ignore */
+        this.client.generateContent(request)
+    );
+
+    const response = res.response;
+    const usageMetadata = this._convertToUsageMetadata(
+      /** @ts-ignore */
+      response.usageMetadata,
+      this.model
+    );
+
+    /** @ts-ignore */
+    const generationResult = mapGenerateContentResultToChatResult(response, {
+      usageMetadata,
+    });
+
+    await runManager?.handleLLMNewToken(
+      generationResult.generations[0].text || '',
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined
+    );
+    return generationResult;
+  }
+
   async *_streamResponseChunks(
     messages: BaseMessage[],
     options: this['ParsedCallOptions'],
@@ -135,7 +257,8 @@ export class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
     const prompt = convertBaseMessagesToContent(
       messages,
       this._isMultimodalModel,
-      this.useSystemInstruction
+      this.useSystemInstruction,
+      this.model
     );
     let actualPrompt = prompt;
     if (prompt?.[0].role === 'system') {
@@ -166,18 +289,10 @@ export class CustomChatGoogleGenerativeAI extends ChatGoogleGenerativeAI {
         this.streamUsage !== false &&
         options.streamUsage !== false
       ) {
-        const genAIUsageMetadata = response.usageMetadata as
-          | GeminiApiUsageMetadata
-          | undefined;
-
-        const output_tokens =
-          (genAIUsageMetadata?.candidatesTokenCount ?? 0) +
-          (genAIUsageMetadata?.thoughtsTokenCount ?? 0);
-        lastUsageMetadata = {
-          input_tokens: genAIUsageMetadata?.promptTokenCount ?? 0,
-          output_tokens,
-          total_tokens: genAIUsageMetadata?.totalTokenCount ?? 0,
-        };
+        lastUsageMetadata = this._convertToUsageMetadata(
+          response.usageMetadata as GeminiApiUsageMetadata | undefined,
+          this.model
+        );
       }
 
       const chunk = convertResponseContentToChatGenerationChunk(response, {