illuma-agents 1.0.12 → 1.0.13

package/dist/types/agents/AgentContext.d.ts

@@ -75,6 +75,10 @@ export declare class AgentContext {
     tokenCalculationPromise?: Promise<void>;
     /** Format content blocks as strings (for legacy compatibility) */
     useLegacyContent: boolean;
+    /** Detailed per-tool token breakdown for admin tracking */
+    private toolsDetail;
+    /** Total tool tokens (sum of all toolsDetail) */
+    private toolTokensTotal;
     constructor({ agentId, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
         agentId: string;
         provider: Providers;
@@ -134,8 +138,30 @@ export declare class AgentContext {
     /**
      * Calculate tool tokens and add to instruction tokens
      * Note: System message tokens are calculated during systemRunnable creation
+     * Also tracks per-tool token breakdown for admin reporting
      */
     calculateInstructionTokens(tokenCounter: t.TokenCounter): Promise<void>;
+    /**
+     * Get a detailed breakdown of context tokens for admin reporting.
+     * This provides visibility into what's consuming the input token budget.
+     * @returns ContextBreakdown object with per-component token counts
+     */
+    getContextBreakdown(): {
+        instructions: number;
+        artifacts: number;
+        tools: number;
+        toolCount: number;
+        toolContext: number;
+        total: number;
+        toolsDetail: Array<{
+            name: string;
+            tokens: number;
+        }>;
+        toolContextDetail: Array<{
+            name: string;
+            tokens: number;
+        }>;
+    };
     /**
      * Gets the tool registry for deferred tools (for tool search).
      * @param onlyDeferred If true, only returns tools with defer_loading=true

package/dist/types/graphs/Graph.d.ts

@@ -85,6 +85,26 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * Returns a map where key is the contentPart index and value is the agentId
      */
     getContentPartAgentMap(): Map<number, string>;
+    /**
+     * Get the context breakdown from the primary agent for admin token tracking.
+     * Returns detailed token counts for instructions, tools, etc.
+     */
+    getContextBreakdown(): {
+        instructions: number;
+        artifacts: number;
+        tools: number;
+        toolCount: number;
+        toolContext: number;
+        total: number;
+        toolsDetail: Array<{
+            name: string;
+            tokens: number;
+        }>;
+        toolContextDetail: Array<{
+            name: string;
+            tokens: number;
+        }>;
+    } | null;
     createSystemRunnable({ provider, clientOptions, instructions, additional_instructions, }: {
         provider?: Providers;
         clientOptions?: t.ClientOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/agents/AgentContext.ts

@@ -153,6 +153,10 @@ export class AgentContext {
   tokenCalculationPromise?: Promise<void>;
   /** Format content blocks as strings (for legacy compatibility) */
   useLegacyContent: boolean = false;
+  /** Detailed per-tool token breakdown for admin tracking */
+  private toolsDetail: Array<{ name: string; tokens: number }> = [];
+  /** Total tool tokens (sum of all toolsDetail) */
+  private toolTokensTotal: number = 0;
 
   constructor({
     agentId,
@@ -386,8 +390,6 @@ export class AgentContext {
       const supportsCaching = modelId.includes('claude') || modelId.includes('anthropic') || modelId.includes('nova');
 
       if (bedrockOptions?.promptCache === true && supportsCaching) {
-        // Always log system cache structure
-        console.log(`[Cache] 📝 System | chars=${instructionsString.length} | tokens=${this.systemMessageTokens} | model=${modelId}`);
         
         finalInstructions = {
           content: [
@@ -423,6 +425,8 @@ export class AgentContext {
   reset(): void {
     this.instructionTokens = 0;
     this.systemMessageTokens = 0;
+    this.toolsDetail = [];
+    this.toolTokensTotal = 0;
     this.cachedSystemRunnable = undefined;
     this.systemRunnableStale = true;
     this.lastToken = undefined;
@@ -458,11 +462,14 @@ export class AgentContext {
   /**
    * Calculate tool tokens and add to instruction tokens
    * Note: System message tokens are calculated during systemRunnable creation
+   * Also tracks per-tool token breakdown for admin reporting
    */
   async calculateInstructionTokens(
     tokenCounter: t.TokenCounter
   ): Promise<void> {
     let toolTokens = 0;
+    this.toolsDetail = []; // Reset per-tool breakdown
+    
     if (this.tools && this.tools.length > 0) {
       for (const tool of this.tools) {
         const genericTool = tool as Record<string, unknown>;
@@ -480,17 +487,60 @@ export class AgentContext {
             describedSchema as Parameters<typeof zodToJsonSchema>[0],
             (genericTool.name as string) || ''
           );
-          toolTokens += tokenCounter(
+          const toolName = (genericTool.name as string) || 'unknown';
+          const tokens = tokenCounter(
             new SystemMessage(JSON.stringify(jsonSchema))
           );
+          
+          // Track per-tool breakdown
+          this.toolsDetail.push({ name: toolName, tokens });
+          toolTokens += tokens;
         }
       }
     }
 
+    // Store total tool tokens for breakdown reporting
+    this.toolTokensTotal = toolTokens;
+    
     // Add tool tokens to existing instruction tokens (which may already include system message tokens)
     this.instructionTokens += toolTokens;
   }
 
+  /**
+   * Get a detailed breakdown of context tokens for admin reporting.
+   * This provides visibility into what's consuming the input token budget.
+   * @returns ContextBreakdown object with per-component token counts
+   */
+  getContextBreakdown(): {
+    instructions: number;
+    artifacts: number;
+    tools: number;
+    toolCount: number;
+    toolContext: number;
+    total: number;
+    toolsDetail: Array<{ name: string; tokens: number }>;
+    toolContextDetail: Array<{ name: string; tokens: number }>;
+  } {
+    return {
+      // System message tokens (instructions + additional_instructions)
+      instructions: this.systemMessageTokens,
+      // Artifacts are not currently tracked separately, set to 0
+      artifacts: 0,
+      // Total tool definition tokens
+      tools: this.toolTokensTotal,
+      // Number of tools
+      toolCount: this.toolsDetail.length,
+      // Tool context/usage instructions (currently embedded in system message)
+      toolContext: 0,
+      // Total tracked context tokens
+      total: this.instructionTokens,
+      // Per-tool token breakdown
+      toolsDetail: [...this.toolsDetail],
+      // Tool context detail (currently not tracked separately)
+      toolContextDetail: [],
+    };
+  }
+
   /**
    * Gets the tool registry for deferred tools (for tool search).
    * @param onlyDeferred If true, only returns tools with defer_loading=true

package/src/graphs/Graph.ts

@@ -391,6 +391,27 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     return contentPartAgentMap;
   }
 
+  /**
+   * Get the context breakdown from the primary agent for admin token tracking.
+   * Returns detailed token counts for instructions, tools, etc.
+   */
+  getContextBreakdown(): {
+    instructions: number;
+    artifacts: number;
+    tools: number;
+    toolCount: number;
+    toolContext: number;
+    total: number;
+    toolsDetail: Array<{ name: string; tokens: number }>;
+    toolContextDetail: Array<{ name: string; tokens: number }>;
+  } | null {
+    const primaryContext = this.agentContexts.get(this.defaultAgentId);
+    if (!primaryContext) {
+      return null;
+    }
+    return primaryContext.getContextBreakdown();
+  }
+
   /* Graph */
 
   createSystemRunnable({

package/src/llm/bedrock/index.ts

@@ -92,8 +92,7 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
         }
       }
 
-      // Always log cache structure (INFO level for tracking)
-      console.log(`[Cache] 🔧 Tools | Core: [${coreToolNames.join(', ')}] (${coreTools.length}) | MCP: [${mcpToolNames.join(', ')}] (${mcpTools.length})`);
+
 
       // Build tools array with strategic cachePoints:
       // [CoreTool1, CoreTool2, cachePoint] + [MCPTool1, MCPTool2, cachePoint]
@@ -120,7 +119,7 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
         cachePointCount++;
       }
       
-      console.log(`[Cache] 📍 Tool cachePoints: ${cachePointCount} | Order: [${coreToolNames.length > 0 ? 'CoreTools→CP' : ''}${mcpToolNames.length > 0 ? '→MCPTools→CP' : ''}]`);
+
       
       params.toolConfig.tools = toolsWithCache;
     }
@@ -176,11 +175,6 @@ export class CustomChatBedrockConverse extends ChatBedrockConverse {
           const outputTokens = (usage.outputTokens as number) ?? 0;
           
           if (cacheRead > 0 || cacheWrite > 0) {
-            // Always log cache results for tracking
-            const cacheStatus = cacheRead > 0 && cacheWrite === 0 ? '✅ HIT' : 
-                               cacheWrite > 0 && cacheRead === 0 ? '📝 WRITE' :
-                               cacheRead > 0 && cacheWrite > 0 ? '🔄 PARTIAL' : '❌ MISS';
-            console.log(`[Cache] ${cacheStatus} | read=${cacheRead} | write=${cacheWrite} | input=${inputTokens} | output=${outputTokens}`);
             
             needsModification = true;
             enhancedUsageMetadata = {

package/src/messages/cache.ts

@@ -7,14 +7,10 @@ type MessageWithContent = {
   content?: string | MessageContentComplex[];
 };
 
-/** Always-on logger for cache operations */
-const logCache = (message: string) => {
-  console.log(`[Cache] ${message}`);
-};
-
 /** Debug logger for cache operations - set ILLUMA_DEBUG_CACHE=true to enable */
 const debugCache = (message: string, data?: unknown) => {
   if (process.env.ILLUMA_DEBUG_CACHE === 'true') {
+    // eslint-disable-next-line no-console
     console.log(`[Cache] ${message}`, data !== undefined ? JSON.stringify(data, null, 2) : '');
   }
 };
@@ -266,12 +262,12 @@ export function addBedrockCacheControl<
   }
 
   // Log message summary
-  logCache(`📨 Messages | total=${updatedMessages.length} | ${Object.entries(messageTypes).map(([k,v]) => `${k}:${v}`).join(' ')} | skippedReasoning=${skippedWithReasoning}`);
+  debugCache(`📨 Messages | total=${updatedMessages.length} | ${Object.entries(messageTypes).map(([k,v]) => `${k}:${v}`).join(' ')} | skippedReasoning=${skippedWithReasoning}`);
 
   // If no suitable assistant message found, skip conversation caching
   // (System and Tools caching are still handled separately)
   if (lastAssistantIndex === -1) {
-    logCache('📨 Messages | No suitable assistant message for cachePoint (first turn or all have reasoning)');
+    debugCache('📨 Messages | No suitable assistant message for cachePoint (first turn or all have reasoning)');
     return updatedMessages;
   }
 
@@ -284,7 +280,7 @@ export function addBedrockCacheControl<
       { type: ContentTypes.TEXT, text: content },
       { cachePoint: { type: 'default' } },
     ] as MessageContentComplex[];
-    logCache(`📍 Message cachePoint at index ${lastAssistantIndex} (string, ${content.length} chars)`);
+    debugCache(`📍 Message cachePoint at index ${lastAssistantIndex} (string, ${content.length} chars)`);
     debugCache('addBedrockCacheControl: Added cachePoint to assistant message (string content)', {
       index: lastAssistantIndex,
       contentLength: content.length,
@@ -293,7 +289,7 @@ export function addBedrockCacheControl<
     // Double-check: If this message has reasoning blocks, skip adding cache point entirely
     // This handles edge cases where the initial skip check might have missed it
     if (hasReasoningBlock(assistantMessage)) {
-      logCache(`⚠️ Message cachePoint SKIPPED at index ${lastAssistantIndex} (has reasoning blocks)`);
+      debugCache(`⚠️ Message cachePoint SKIPPED at index ${lastAssistantIndex} (has reasoning blocks)`);
       debugCache('addBedrockCacheControl: Skipping - assistant message has reasoning blocks (safety check)', {
         index: lastAssistantIndex,
       });
@@ -312,7 +308,7 @@ export function addBedrockCacheControl<
             cachePoint: { type: 'default' },
           } as MessageContentComplex);
           inserted = true;
-          logCache(`📍 Message cachePoint at index ${lastAssistantIndex} (array, block ${j}, ${text.length} chars)`);
+          debugCache(`📍 Message cachePoint at index ${lastAssistantIndex} (array, block ${j}, ${text.length} chars)`);
           debugCache('addBedrockCacheControl: Added cachePoint after text block in assistant message', {
             index: lastAssistantIndex,
             textBlockIndex: j,
@@ -326,7 +322,7 @@ export function addBedrockCacheControl<
     // If no text block found, don't append cache point as the message structure is unexpected
     if (!inserted) {
       const contentTypes = assistantMessage.content.map((b) => (b as { type?: string }).type);
-      logCache(`⚠️ Message cachePoint SKIPPED at index ${lastAssistantIndex} (no text block, types: ${contentTypes.join(',')})`);
+      debugCache(`⚠️ Message cachePoint SKIPPED at index ${lastAssistantIndex} (no text block, types: ${contentTypes.join(',')})`);
       debugCache('addBedrockCacheControl: No suitable text block found, skipping cache point', {
         index: lastAssistantIndex,
         contentTypes,