illuma-agents 1.0.16 → 1.0.17

package/src/graphs/Graph.ts

@@ -36,6 +36,7 @@ import {
   GraphEvents,
   Providers,
   StepTypes,
+  MessageTypes,
 } from '@/common';
 import {
   formatAnthropicArtifactContent,
@@ -56,6 +57,7 @@ import {
   joinKeys,
   sleep,
 } from '@/utils';
+import { buildContextAnalytics, type ContextAnalytics } from '@/utils/contextAnalytics';
 import { getChatModelClass, manualToolStreamProviders } from '@/llm/providers';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
 import { ChatOpenAI, AzureChatOpenAI } from '@/llm/openai';
@@ -445,6 +447,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     return primaryContext.getContextBreakdown();
   }
 
+  /**
+   * Get the latest context analytics from the graph.
+   * Returns metrics like utilization %, TOON stats, message breakdown.
+   */
+  getContextAnalytics(): ContextAnalytics | null {
+    return this.lastContextAnalytics ?? null;
+  }
+
+  /** Store the latest context analytics for retrieval after run */
+  private lastContextAnalytics: ContextAnalytics | null = null;
+
   /* Graph */
 
   createSystemRunnable({
@@ -733,16 +746,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
       let messagesToUse = messages;
       
-      // Debug logging for pruneMessages creation conditions
-      const hasPruneMessages = !!agentContext.pruneMessages;
-      const hasTokenCounter = !!agentContext.tokenCounter;
-      const hasMaxContextTokens = agentContext.maxContextTokens != null;
-      const hasIndex0TokenCount = agentContext.indexTokenCountMap[0] != null;
-      
-      if (!hasPruneMessages && hasTokenCounter && hasMaxContextTokens && !hasIndex0TokenCount) {
-        console.warn('[Graph] Cannot create pruneMessages - missing indexTokenCountMap[0]. Token map keys:', Object.keys(agentContext.indexTokenCountMap));
-      }
-      
       if (
         !agentContext.pruneMessages &&
         agentContext.tokenCounter &&
@@ -771,6 +774,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           indexTokenCountMap: agentContext.indexTokenCountMap,
         });
       }
+
       if (agentContext.pruneMessages) {
         const { context, indexTokenCountMap } = agentContext.pruneMessages({
           messages,
@@ -798,13 +802,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (
         agentContext.provider === Providers.BEDROCK &&
         lastMessageX instanceof AIMessageChunk &&
-        lastMessageY instanceof ToolMessage &&
+        lastMessageY?.getType() === MessageTypes.TOOL &&
         typeof lastMessageX.content === 'string'
       ) {
         finalMessages[finalMessages.length - 2].content = '';
       }
 
-      const isLatestToolMessage = lastMessageY instanceof ToolMessage;
+      // Use getType() instead of instanceof to avoid module mismatch issues
+      const isLatestToolMessage = lastMessageY?.getType() === MessageTypes.TOOL;
 
       if (
         isLatestToolMessage &&
@@ -820,6 +825,33 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         formatArtifactPayload(finalMessages);
       }
 
+      /**
+       * Handle edge case: when switching from a non-thinking agent to a thinking-enabled agent,
+       * convert AI messages with tool calls to HumanMessages to avoid thinking block requirements.
+       * This is required by Anthropic/Bedrock when thinking is enabled.
+       * 
+       * IMPORTANT: This MUST happen BEFORE cache control is applied.
+       * If we add cachePoint to an AI message first, then convert that AI message to a HumanMessage,
+       * the cachePoint is lost. By converting first, we ensure cache control is applied to the
+       * final message structure that will be sent to the API.
+       */
+      const isAnthropicWithThinking =
+        (agentContext.provider === Providers.ANTHROPIC &&
+          (agentContext.clientOptions as t.AnthropicClientOptions).thinking !=
+            null) ||
+        (agentContext.provider === Providers.BEDROCK &&
+          (agentContext.clientOptions as t.BedrockAnthropicInput)
+            .additionalModelRequestFields?.['thinking'] != null);
+
+      if (isAnthropicWithThinking) {
+        finalMessages = ensureThinkingBlockInMessages(
+          finalMessages,
+          agentContext.provider
+        );
+      }
+
+      // Apply cache control AFTER thinking block handling to ensure cachePoints aren't lost
+      // when AI messages are converted to HumanMessages
       if (agentContext.provider === Providers.ANTHROPIC) {
         const anthropicOptions = agentContext.clientOptions as
           | t.AnthropicClientOptions
@@ -847,26 +879,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
       }
 
-      /**
-       * Handle edge case: when switching from a non-thinking agent to a thinking-enabled agent,
-       * convert AI messages with tool calls to HumanMessages to avoid thinking block requirements.
-       * This is required by Anthropic/Bedrock when thinking is enabled.
-       */
-      const isAnthropicWithThinking =
-        (agentContext.provider === Providers.ANTHROPIC &&
-          (agentContext.clientOptions as t.AnthropicClientOptions).thinking !=
-            null) ||
-        (agentContext.provider === Providers.BEDROCK &&
-          (agentContext.clientOptions as t.BedrockAnthropicInput)
-            .additionalModelRequestFields?.['thinking'] != null);
-
-      if (isAnthropicWithThinking) {
-        finalMessages = ensureThinkingBlockInMessages(
-          finalMessages,
-          agentContext.provider
-        );
-      }
-
       if (
         agentContext.lastStreamCall != null &&
         agentContext.streamBuffer != null
@@ -896,6 +908,35 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         );
       }
 
+      // Get model info for analytics
+      const bedrockOpts = agentContext.clientOptions as t.BedrockAnthropicClientOptions | undefined;
+      const modelId = bedrockOpts?.model || (agentContext.clientOptions as t.AnthropicClientOptions | undefined)?.modelName;
+      const thinkingConfig = bedrockOpts?.additionalModelRequestFields?.['thinking'] || 
+                             (agentContext.clientOptions as t.AnthropicClientOptions | undefined)?.thinking;
+
+      // Build and emit context analytics for traces
+      const contextAnalytics = buildContextAnalytics(finalMessages, {
+        tokenCounter: agentContext.tokenCounter,
+        maxContextTokens: agentContext.maxContextTokens,
+        instructionTokens: agentContext.instructionTokens,
+        indexTokenCountMap: agentContext.indexTokenCountMap,
+      });
+      
+      // Store for retrieval via getContextAnalytics() after run completes
+      this.lastContextAnalytics = contextAnalytics;
+      
+      await safeDispatchCustomEvent(
+        GraphEvents.ON_CONTEXT_ANALYTICS,
+        {
+          provider: agentContext.provider,
+          model: modelId,
+          thinkingEnabled: thinkingConfig != null,
+          cacheEnabled: bedrockOpts?.promptCache === true,
+          analytics: contextAnalytics,
+        },
+        config
+      );
+
       try {
         result = await this.attemptInvoke(
           {
@@ -1002,7 +1043,17 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
               ? formatContentStrings(messagesWithNotice)
               : messagesWithNotice;
 
-            // Apply Bedrock cache control if needed
+            // Apply thinking block handling first (before cache control)
+            // This ensures AI+Tool sequences are converted to HumanMessages
+            // before we add cache points that could be lost in the conversion
+            if (isAnthropicWithThinking) {
+              retryMessages = ensureThinkingBlockInMessages(
+                retryMessages,
+                agentContext.provider
+              );
+            }
+
+            // Apply Bedrock cache control if needed (after thinking block handling)
             if (agentContext.provider === Providers.BEDROCK) {
               const bedrockOptions = agentContext.clientOptions as
                 | t.BedrockAnthropicClientOptions

package/src/messages/core.ts

@@ -8,7 +8,7 @@ import {
 } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
-import { Providers } from '@/common';
+import { Providers, MessageTypes } from '@/common';
 
 export function getConverseOverrideMessage({
   userMessage,
@@ -346,7 +346,9 @@ export function convertMessagesToContent(
 
 export function formatAnthropicArtifactContent(messages: BaseMessage[]): void {
   const lastMessage = messages[messages.length - 1];
-  if (!(lastMessage instanceof ToolMessage)) return;
+  // Use getType() instead of instanceof to avoid module mismatch issues
+  if (lastMessage?.getType() !== 'tool') return;
+  const lastToolMessage = lastMessage as ToolMessage;
 
   // Find the latest AIMessage with tool_calls that this tool message belongs to
   const latestAIParentIndex = findLastIndex(
@@ -354,20 +356,21 @@ export function formatAnthropicArtifactContent(messages: BaseMessage[]): void {
     (msg) =>
       (msg instanceof AIMessageChunk &&
         (msg.tool_calls?.length ?? 0) > 0 &&
-        msg.tool_calls?.some((tc) => tc.id === lastMessage.tool_call_id)) ??
+        msg.tool_calls?.some((tc) => tc.id === lastToolMessage.tool_call_id)) ??
       false
   );
 
   if (latestAIParentIndex === -1) return;
 
   // Check if any tool message after the AI message has array artifact content
+  // Use getType() instead of instanceof to avoid module mismatch issues
   const hasArtifactContent = messages.some(
     (msg, i) =>
       i > latestAIParentIndex &&
-      msg instanceof ToolMessage &&
-      msg.artifact != null &&
-      msg.artifact?.content != null &&
-      Array.isArray(msg.artifact.content)
+      msg.getType() === MessageTypes.TOOL &&
+      (msg as ToolMessage).artifact != null &&
+      (msg as ToolMessage).artifact?.content != null &&
+      Array.isArray((msg as ToolMessage).artifact.content)
   );
 
   if (!hasArtifactContent) return;
@@ -377,21 +380,24 @@ export function formatAnthropicArtifactContent(messages: BaseMessage[]): void {
 
   for (let j = latestAIParentIndex + 1; j < messages.length; j++) {
     const msg = messages[j];
+    // Use getType() instead of instanceof to avoid module mismatch issues
     if (
-      msg instanceof ToolMessage &&
-      toolCallIds.includes(msg.tool_call_id) &&
-      msg.artifact != null &&
-      Array.isArray(msg.artifact?.content) &&
+      msg.getType() === MessageTypes.TOOL &&
+      toolCallIds.includes((msg as ToolMessage).tool_call_id) &&
+      (msg as ToolMessage).artifact != null &&
+      Array.isArray((msg as ToolMessage).artifact?.content) &&
       Array.isArray(msg.content)
     ) {
-      msg.content = msg.content.concat(msg.artifact.content);
+      msg.content = (msg.content as t.MessageContentComplex[]).concat((msg as ToolMessage).artifact.content);
     }
   }
 }
 
 export function formatArtifactPayload(messages: BaseMessage[]): void {
   const lastMessageY = messages[messages.length - 1];
-  if (!(lastMessageY instanceof ToolMessage)) return;
+  // Use getType() instead of instanceof to avoid module mismatch issues
+  if (lastMessageY?.getType() !== 'tool') return;
+  const lastToolMessage = lastMessageY as ToolMessage;
 
   // Find the latest AIMessage with tool_calls that this tool message belongs to
   const latestAIParentIndex = findLastIndex(
@@ -399,28 +405,30 @@ export function formatArtifactPayload(messages: BaseMessage[]): void {
     (msg) =>
       (msg instanceof AIMessageChunk &&
         (msg.tool_calls?.length ?? 0) > 0 &&
-        msg.tool_calls?.some((tc) => tc.id === lastMessageY.tool_call_id)) ??
+        msg.tool_calls?.some((tc) => tc.id === lastToolMessage.tool_call_id)) ??
       false
   );
 
   if (latestAIParentIndex === -1) return;
 
   // Check if any tool message after the AI message has array artifact content
+  // Use getType() instead of instanceof to avoid module mismatch issues
   const hasArtifactContent = messages.some(
     (msg, i) =>
       i > latestAIParentIndex &&
-      msg instanceof ToolMessage &&
-      msg.artifact != null &&
-      msg.artifact?.content != null &&
-      Array.isArray(msg.artifact.content)
+      msg.getType() === MessageTypes.TOOL &&
+      (msg as ToolMessage).artifact != null &&
+      (msg as ToolMessage).artifact?.content != null &&
+      Array.isArray((msg as ToolMessage).artifact.content)
   );
 
   if (!hasArtifactContent) return;
 
   // Collect all relevant tool messages and their artifacts
+  // Use getType() instead of instanceof to avoid module mismatch issues
   const relevantMessages = messages
     .slice(latestAIParentIndex + 1)
-    .filter((msg) => msg instanceof ToolMessage) as ToolMessage[];
+    .filter((msg) => msg.getType() === MessageTypes.TOOL) as ToolMessage[];
 
   // Aggregate all content and artifacts
   const aggregatedContent: t.MessageContentComplex[] = [];

package/src/messages/format.ts

@@ -19,7 +19,8 @@ import type {
   TPayload,
   TMessage,
 } from '@/types';
-import { Providers, ContentTypes } from '@/common';
+import { Providers, ContentTypes, MessageTypes } from '@/common';
+import { processToolOutput } from '@/utils/toonFormat';
 
 interface MediaMessageParams {
   message: {
@@ -359,11 +360,15 @@ function formatAssistantMessage(
         }
         lastAIMessage.tool_calls.push(tool_call as ToolCall);
 
+        // Apply TOON compression to historical tool outputs for context efficiency
+        // processToolOutput handles: JSON→TOON conversion, already-TOON detection (skip), truncation
+        const processedOutput = output != null ? processToolOutput(output).content : '';
+
         formattedMessages.push(
           new ToolMessage({
             tool_call_id: tool_call.id ?? '',
             name: tool_call.name,
-            content: output != null ? output : '',
+            content: processedOutput,
           })
         );
       } else if (part.type === ContentTypes.THINK) {
@@ -898,7 +903,9 @@ export function ensureThinkingBlockInMessages(
       let j = i + 1;
 
       // Look ahead for tool messages that belong to this AI message
-      while (j < messages.length && messages[j] instanceof ToolMessage) {
+      // Use getType() instead of instanceof to avoid module mismatch issues
+      // where different copies of ToolMessage class might be loaded
+      while (j < messages.length && messages[j].getType() === MessageTypes.TOOL) {
         toolSequence.push(messages[j]);
         j++;
       }

package/src/messages/tools.ts

@@ -1,7 +1,7 @@
 // src/messages/toolDiscovery.ts
 import { AIMessageChunk, ToolMessage } from '@langchain/core/messages';
 import type { BaseMessage } from '@langchain/core/messages';
-import { Constants } from '@/common';
+import { Constants, MessageTypes } from '@/common';
 import { findLastIndex } from './core';
 
 type ToolSearchArtifact = {
@@ -20,7 +20,9 @@ type ToolSearchArtifact = {
  */
 export function extractToolDiscoveries(messages: BaseMessage[]): string[] {
   const lastMessage = messages[messages.length - 1];
-  if (!(lastMessage instanceof ToolMessage)) return [];
+  // Use getType() instead of instanceof to avoid module mismatch issues
+  if (lastMessage?.getType() !== MessageTypes.TOOL) return [];
+  const lastToolMessage = lastMessage as ToolMessage;
 
   // Find the latest AIMessage with tool_calls that this tool message belongs to
   const latestAIParentIndex = findLastIndex(
@@ -28,7 +30,7 @@ export function extractToolDiscoveries(messages: BaseMessage[]): string[] {
     (msg) =>
       (msg instanceof AIMessageChunk &&
         (msg.tool_calls?.length ?? 0) > 0 &&
-        msg.tool_calls?.some((tc) => tc.id === lastMessage.tool_call_id)) ??
+        msg.tool_calls?.some((tc) => tc.id === lastToolMessage.tool_call_id)) ??
       false
   );
 
@@ -42,13 +44,15 @@ export function extractToolDiscoveries(messages: BaseMessage[]): string[] {
   const discoveredNames: string[] = [];
   for (let i = latestAIParentIndex + 1; i < messages.length; i++) {
     const msg = messages[i];
-    if (!(msg instanceof ToolMessage)) continue;
-    if (msg.name !== Constants.TOOL_SEARCH_REGEX) continue;
-    if (!toolCallIds.has(msg.tool_call_id)) continue;
+    // Use getType() instead of instanceof to avoid module mismatch issues
+    if (msg.getType() !== MessageTypes.TOOL) continue;
+    const toolMsg = msg as ToolMessage;
+    if (toolMsg.name !== Constants.TOOL_SEARCH_REGEX) continue;
+    if (!toolCallIds.has(toolMsg.tool_call_id)) continue;
 
     // This is a tool search result from the current turn
-    if (typeof msg.artifact === 'object' && msg.artifact != null) {
-      const artifact = msg.artifact as ToolSearchArtifact;
+    if (typeof toolMsg.artifact === 'object' && toolMsg.artifact != null) {
+      const artifact = toolMsg.artifact as ToolSearchArtifact;
       if (artifact.tool_references && artifact.tool_references.length > 0) {
         for (const ref of artifact.tool_references) {
           discoveredNames.push(ref.tool_name);
@@ -66,7 +70,9 @@ export function extractToolDiscoveries(messages: BaseMessage[]): string[] {
  */
 export function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean {
   const lastMessage = messages[messages.length - 1];
-  if (!(lastMessage instanceof ToolMessage)) return false;
+  // Use getType() instead of instanceof to avoid module mismatch issues
+  if (lastMessage?.getType() !== MessageTypes.TOOL) return false;
+  const lastToolMessage = lastMessage as ToolMessage;
 
   // Find the latest AIMessage with tool_calls
   const latestAIParentIndex = findLastIndex(
@@ -74,7 +80,7 @@ export function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean {
     (msg) =>
       (msg instanceof AIMessageChunk &&
         (msg.tool_calls?.length ?? 0) > 0 &&
-        msg.tool_calls?.some((tc) => tc.id === lastMessage.tool_call_id)) ??
+        msg.tool_calls?.some((tc) => tc.id === lastToolMessage.tool_call_id)) ??
       false
   );
 
@@ -84,12 +90,13 @@ export function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean {
   const toolCallIds = new Set(aiMessage.tool_calls?.map((tc) => tc.id) ?? []);
 
   // Check if any tool search results exist after the AI message
+  // Use getType() instead of instanceof to avoid module mismatch issues
   for (let i = latestAIParentIndex + 1; i < messages.length; i++) {
     const msg = messages[i];
     if (
-      msg instanceof ToolMessage &&
-      msg.name === Constants.TOOL_SEARCH_REGEX &&
-      toolCallIds.has(msg.tool_call_id)
+      msg.getType() === MessageTypes.TOOL &&
+      (msg as ToolMessage).name === Constants.TOOL_SEARCH_REGEX &&
+      toolCallIds.has((msg as ToolMessage).tool_call_id)
     ) {
       return true;
     }

package/src/tools/ToolNode.ts

@@ -20,6 +20,7 @@ import type { BaseMessage, AIMessage } from '@langchain/core/messages';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
+import { processToolOutput } from '@/utils/toonFormat';
 import { Constants } from '@/common';
 
 /**
@@ -29,6 +30,43 @@ function isSend(value: unknown): value is Send {
   return value instanceof Send;
 }
 
+/**
+ * Extract text content from a ToolMessage content field.
+ * Handles both string and MessageContentComplex[] formats.
+ * For array content (e.g., from content_and_artifact tools), extracts text from text blocks.
+ */
+function extractStringContent(content: unknown): string {
+  // Already a string - return as is
+  if (typeof content === 'string') {
+    return content;
+  }
+  
+  // Array of content blocks - extract text from each
+  if (Array.isArray(content)) {
+    const textParts: string[] = [];
+    for (const block of content) {
+      if (typeof block === 'string') {
+        textParts.push(block);
+      } else if (block && typeof block === 'object') {
+        // Handle {type: 'text', text: '...'} format
+        const obj = block as Record<string, unknown>;
+        if (obj.type === 'text' && typeof obj.text === 'string') {
+          textParts.push(obj.text);
+        } else if (typeof obj.text === 'string') {
+          // Just has 'text' property
+          textParts.push(obj.text);
+        }
+      }
+    }
+    if (textParts.length > 0) {
+      return textParts.join('\n');
+    }
+  }
+  
+  // Fallback: stringify whatever it is
+  return JSON.stringify(content);
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private toolMap: Map<string, StructuredToolInterface | RunnableToolLike>;
@@ -140,16 +178,51 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       }
 
       const output = await tool.invoke(invokeParams, config);
-      if (
-        (isBaseMessage(output) && output._getType() === 'tool') ||
-        isCommand(output)
-      ) {
+
+      // Handle Command outputs directly
+      if (isCommand(output)) {
         return output;
+      }
+
+      // ========================================================================
+      // TOOL OUTPUT PROCESSING - Single point for all tools (MCP and non-MCP)
+      // 1. Extract string content from any output format  
+      // 2. Apply TOON conversion if content contains JSON
+      // 3. Apply truncation if still too large
+      // 4. Return ToolMessage with processed string content
+      // ========================================================================
+      
+      // Step 1: Extract string content from the output
+      let rawContent: string;
+      if (isBaseMessage(output) && output._getType() === 'tool') {
+        const toolMsg = output as ToolMessage;
+        rawContent = extractStringContent(toolMsg.content);
+      } else {
+        rawContent = extractStringContent(output);
+      }
+
+      // Step 2 & 3: Apply TOON conversion and truncation
+      const processed = processToolOutput(rawContent, {
+        maxLength: 100000, // 100K char limit
+        enableToon: true,
+        minSizeForToon: 1000,
+        minReductionPercent: 10, // Only apply TOON when clearly beneficial
+      });
+
+      // Step 4: Return ToolMessage with processed string content
+      if (isBaseMessage(output) && output._getType() === 'tool') {
+        const toolMsg = output as ToolMessage;
+        return new ToolMessage({
+          status: toolMsg.status,
+          name: toolMsg.name,
+          content: processed.content,
+          tool_call_id: toolMsg.tool_call_id,
+        });
       } else {
         return new ToolMessage({
           status: 'success',
           name: tool.name,
-          content: typeof output === 'string' ? output : JSON.stringify(output),
+          content: processed.content,
           tool_call_id: call.id!,
         });
       }

package/src/utils/contextAnalytics.ts

@@ -0,0 +1,95 @@
+/**
+ * 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';