@illuma-ai/agents 1.0.98 → 1.1.0

package/src/types/graph.ts

@@ -488,6 +488,73 @@ export interface StructuredOutputInput {
   strict?: boolean;
 }
 
+/**
+ * Trigger strategy for when summarization should activate.
+ * - 'contextPercentage': Trigger when context utilization exceeds a threshold percentage
+ * - 'messageCount': Trigger when pruned message count exceeds a threshold
+ * - 'tokenThreshold': Trigger when total token count exceeds a raw threshold
+ */
+export type SummarizationTriggerType =
+  | 'contextPercentage'
+  | 'messageCount'
+  | 'tokenThreshold';
+
+/**
+ * Configuration for summarization behavior within the agent pipeline.
+ * All fields are optional — sensible defaults are provided via constants.
+ *
+ * @see SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, PRUNING_EMA_ALPHA
+ */
+export interface SummarizationConfig {
+  /**
+   * Strategy for when summarization triggers.
+   * @default 'contextPercentage'
+   */
+  triggerType?: SummarizationTriggerType;
+
+  /**
+   * Threshold value interpreted based on triggerType:
+   * - contextPercentage: 0-100 (percentage of context window)
+   * - messageCount: absolute count of messages pruned
+   * - tokenThreshold: absolute token count
+   * @default 80 (for contextPercentage)
+   */
+  triggerThreshold?: number;
+
+  /**
+   * Fraction of context window (0-1) reserved for recent messages.
+   * Prevents over-pruning by ensuring at least this fraction of the
+   * context budget is preserved as recent conversation history.
+   * @default 0.3
+   */
+  reserveRatio?: number;
+
+  /**
+   * Whether context pruning is enabled (can be disabled for debugging).
+   * @default true
+   */
+  contextPruning?: boolean;
+
+  /**
+   * Initial summary text to seed across runs.
+   * Different from persistedSummary: this is provided by the caller as a
+   * cross-conversation seed (e.g., agent personality or recurring context),
+   * while persistedSummary is loaded from the conversation's own history.
+   */
+  initialSummary?: string;
+}
+
+/**
+ * Runtime state for EMA-based pruning calibration.
+ * Maintained across iterations within a single run to smooth pruning decisions.
+ */
+export interface PruneCalibrationState {
+  /** Current EMA calibration ratio */
+  ratio: number;
+  /** Number of calibration updates applied */
+  iterations: number;
+}
+
 export interface AgentInputs {
   agentId: string;
   /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -559,4 +626,10 @@ export interface AgentInputs {
    * Set by Ranger's SummaryStore when resuming a conversation.
    */
   persistedSummary?: string;
+  /**
+   * Summarization configuration controlling trigger strategy, reserve ratio,
+   * and EMA calibration for pruning. When omitted, sensible defaults apply.
+   * @see SummarizationConfig
+   */
+  summarizationConfig?: SummarizationConfig;
 }

package/src/utils/__tests__/pruneCalibration.test.ts

@@ -0,0 +1,148 @@
+// src/utils/__tests__/pruneCalibration.test.ts
+import {
+  createPruneCalibration,
+  updatePruneCalibration,
+  applyCalibration,
+} from '../pruneCalibration';
+import {
+  PRUNING_INITIAL_CALIBRATION,
+  PRUNING_EMA_ALPHA,
+} from '@/common/constants';
+
+describe('pruneCalibration', () => {
+  describe('createPruneCalibration', () => {
+    it('creates initial state with default ratio', () => {
+      const state = createPruneCalibration();
+      expect(state.ratio).toBe(PRUNING_INITIAL_CALIBRATION);
+      expect(state.iterations).toBe(0);
+    });
+
+    it('accepts custom initial ratio', () => {
+      const state = createPruneCalibration(0.85);
+      expect(state.ratio).toBe(0.85);
+      expect(state.iterations).toBe(0);
+    });
+  });
+
+  describe('updatePruneCalibration', () => {
+    it('adjusts ratio when actual > estimated (over-counting)', () => {
+      const state = createPruneCalibration();
+      // Actual: 1000 tokens, estimated: 1500 tokens (our counter over-estimates)
+      // observedRatio = 1500/1000 = 1.5
+      // newRatio = 0.3 * 1.5 + 0.7 * 1.0 = 0.45 + 0.7 = 1.15
+      const updated = updatePruneCalibration(state, 1000, 1500);
+      expect(updated.ratio).toBeCloseTo(1.15, 2);
+      expect(updated.iterations).toBe(1);
+    });
+
+    it('adjusts ratio when actual < estimated (under-counting)', () => {
+      const state = createPruneCalibration();
+      // Actual: 2000 tokens, estimated: 1000 tokens (our counter under-estimates)
+      // observedRatio = 1000/2000 = 0.5
+      // newRatio = 0.3 * 0.5 + 0.7 * 1.0 = 0.15 + 0.7 = 0.85
+      const updated = updatePruneCalibration(state, 2000, 1000);
+      expect(updated.ratio).toBeCloseTo(0.85, 2);
+      expect(updated.iterations).toBe(1);
+    });
+
+    it('converges with consistent readings', () => {
+      let state = createPruneCalibration();
+
+      // Simulate 10 iterations where actual is consistently 1.5x estimated
+      for (let i = 0; i < 10; i++) {
+        state = updatePruneCalibration(state, 1500, 1000);
+      }
+
+      // Should converge toward ~0.667 (estimated/actual = 1000/1500)
+      expect(state.ratio).toBeCloseTo(0.667, 1);
+      expect(state.iterations).toBe(10);
+    });
+
+    it('clamps extreme ratios to prevent wild adjustments', () => {
+      const state = createPruneCalibration();
+
+      // Extreme case: estimated 10x actual (should be clamped to 2.0)
+      const updated = updatePruneCalibration(state, 100, 10000);
+      // Clamped observedRatio = 2.0
+      // newRatio = 0.3 * 2.0 + 0.7 * 1.0 = 0.6 + 0.7 = 1.3
+      expect(updated.ratio).toBeCloseTo(1.3, 2);
+    });
+
+    it('does not update with invalid inputs', () => {
+      const state = createPruneCalibration();
+
+      expect(updatePruneCalibration(state, 0, 1000)).toBe(state);
+      expect(updatePruneCalibration(state, 1000, 0)).toBe(state);
+      expect(updatePruneCalibration(state, -1, 1000)).toBe(state);
+    });
+
+    it('does not mutate input state', () => {
+      const state = createPruneCalibration();
+      const original = { ...state };
+
+      updatePruneCalibration(state, 1000, 1500);
+      expect(state).toEqual(original);
+    });
+
+    it('accepts custom alpha', () => {
+      const state = createPruneCalibration();
+      // With alpha=1.0, fully adapts to new reading
+      const updated = updatePruneCalibration(state, 1000, 1500, 1.0);
+      // observedRatio = 1.5, clamped to 1.5
+      // newRatio = 1.0 * 1.5 + 0.0 * 1.0 = 1.5
+      expect(updated.ratio).toBeCloseTo(1.5, 2);
+    });
+  });
+
+  describe('applyCalibration', () => {
+    it('returns raw budget when no iterations have occurred', () => {
+      const state = createPruneCalibration();
+      expect(applyCalibration(10000, state)).toBe(10000);
+    });
+
+    it('adjusts budget after calibration', () => {
+      let state = createPruneCalibration();
+      state = updatePruneCalibration(state, 1000, 1500);
+      // ratio ≈ 1.15, so budget is increased (our counter over-estimates)
+      const adjusted = applyCalibration(10000, state);
+      expect(adjusted).toBeCloseTo(11500, -2);
+    });
+
+    it('decreases budget when under-counting', () => {
+      let state = createPruneCalibration();
+      state = updatePruneCalibration(state, 2000, 1000);
+      // ratio ≈ 0.85, so budget is decreased (our counter under-estimates)
+      const adjusted = applyCalibration(10000, state);
+      expect(adjusted).toBeLessThan(10000);
+    });
+
+    it('returns floor of the adjusted value', () => {
+      let state = createPruneCalibration();
+      state = updatePruneCalibration(state, 1000, 1500);
+      const adjusted = applyCalibration(10001, state);
+      expect(Number.isInteger(adjusted)).toBe(true);
+    });
+  });
+
+  describe('multi-iteration convergence', () => {
+    it('smoothly transitions when accuracy changes', () => {
+      let state = createPruneCalibration();
+
+      // First 5 iterations: estimated is 1.5x actual
+      for (let i = 0; i < 5; i++) {
+        state = updatePruneCalibration(state, 1000, 1500);
+      }
+      const ratio5 = state.ratio;
+
+      // Next 5 iterations: estimated matches actual
+      for (let i = 0; i < 5; i++) {
+        state = updatePruneCalibration(state, 1000, 1000);
+      }
+      const ratio10 = state.ratio;
+
+      // Ratio should move toward 1.0 but still carry some history
+      expect(ratio10).toBeLessThan(ratio5);
+      expect(ratio10).toBeGreaterThan(0.9);
+    });
+  });
+});

package/src/utils/__tests__/toolDiscoveryCache.test.ts

@@ -0,0 +1,214 @@
+// src/utils/__tests__/toolDiscoveryCache.test.ts
+import {
+  ToolMessage,
+  AIMessageChunk,
+  HumanMessage,
+  SystemMessage,
+} from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { ToolDiscoveryCache } from '../toolDiscoveryCache';
+import { Constants } from '@/common';
+
+/**
+ * Creates a mock tool_search result message.
+ */
+function createToolSearchResult(
+  toolNames: string[],
+  toolCallId: string = 'tc_1'
+): ToolMessage {
+  return new ToolMessage({
+    content: `Found ${toolNames.length} tools`,
+    tool_call_id: toolCallId,
+    name: Constants.TOOL_SEARCH,
+    artifact: {
+      tool_references: toolNames.map((name) => ({ tool_name: name })),
+    },
+  });
+}
+
+/**
+ * Creates a mock AI message with tool calls.
+ */
+function createAIWithToolCalls(toolCallIds: string[]): AIMessageChunk {
+  return new AIMessageChunk({
+    content: 'I will search for tools',
+    tool_calls: toolCallIds.map((id) => ({
+      id,
+      name: Constants.TOOL_SEARCH,
+      args: { query: 'test' },
+    })),
+  });
+}
+
+describe('ToolDiscoveryCache', () => {
+  let cache: ToolDiscoveryCache;
+
+  beforeEach(() => {
+    cache = new ToolDiscoveryCache();
+  });
+
+  describe('getNewDiscoveries', () => {
+    it('returns empty array for empty messages', () => {
+      expect(cache.getNewDiscoveries([])).toEqual([]);
+    });
+
+    it('discovers tools from tool_search results', () => {
+      const messages: BaseMessage[] = [
+        new SystemMessage('You are helpful'),
+        new HumanMessage('Find tools'),
+        createAIWithToolCalls(['tc_1']),
+        createToolSearchResult(['web_search', 'file_read'], 'tc_1'),
+      ];
+
+      const result = cache.getNewDiscoveries(messages);
+      expect(result).toEqual(['web_search', 'file_read']);
+      expect(cache.size).toBe(2);
+    });
+
+    it('only scans new messages on subsequent calls', () => {
+      const messages: BaseMessage[] = [
+        new HumanMessage('msg1'),
+        createAIWithToolCalls(['tc_1']),
+        createToolSearchResult(['tool_a'], 'tc_1'),
+      ];
+
+      // First scan
+      const first = cache.getNewDiscoveries(messages);
+      expect(first).toEqual(['tool_a']);
+
+      // Add more messages
+      messages.push(
+        new HumanMessage('msg2'),
+        createAIWithToolCalls(['tc_2']),
+        createToolSearchResult(['tool_b'], 'tc_2')
+      );
+
+      // Second scan: only finds tool_b (tool_a already cached)
+      const second = cache.getNewDiscoveries(messages);
+      expect(second).toEqual(['tool_b']);
+      expect(cache.size).toBe(2);
+    });
+
+    it('deduplicates tool names across scans', () => {
+      const messages: BaseMessage[] = [
+        createAIWithToolCalls(['tc_1']),
+        createToolSearchResult(['tool_a', 'tool_b'], 'tc_1'),
+      ];
+
+      cache.getNewDiscoveries(messages);
+
+      // Add another search that returns tool_a again
+      messages.push(
+        createAIWithToolCalls(['tc_2']),
+        createToolSearchResult(['tool_a', 'tool_c'], 'tc_2')
+      );
+
+      const second = cache.getNewDiscoveries(messages);
+      // tool_a is already cached, only tool_c is new
+      expect(second).toEqual(['tool_c']);
+      expect(cache.size).toBe(3);
+    });
+
+    it('ignores non-tool-search tool messages', () => {
+      const messages: BaseMessage[] = [
+        createAIWithToolCalls(['tc_1']),
+        new ToolMessage({
+          content: 'result',
+          tool_call_id: 'tc_1',
+          name: 'some_other_tool',
+        }),
+      ];
+
+      const result = cache.getNewDiscoveries(messages);
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty when no new messages since last scan', () => {
+      const messages: BaseMessage[] = [
+        createAIWithToolCalls(['tc_1']),
+        createToolSearchResult(['tool_a'], 'tc_1'),
+      ];
+
+      cache.getNewDiscoveries(messages);
+      // No new messages added
+      const second = cache.getNewDiscoveries(messages);
+      expect(second).toEqual([]);
+    });
+  });
+
+  describe('has', () => {
+    it('returns true for discovered tools', () => {
+      const messages: BaseMessage[] = [
+        createAIWithToolCalls(['tc_1']),
+        createToolSearchResult(['tool_a'], 'tc_1'),
+      ];
+
+      cache.getNewDiscoveries(messages);
+      expect(cache.has('tool_a')).toBe(true);
+      expect(cache.has('tool_b')).toBe(false);
+    });
+  });
+
+  describe('getAllDiscoveredTools', () => {
+    it('returns all discovered tool names', () => {
+      const messages: BaseMessage[] = [
+        createAIWithToolCalls(['tc_1']),
+        createToolSearchResult(['tool_a', 'tool_b'], 'tc_1'),
+      ];
+
+      cache.getNewDiscoveries(messages);
+      expect(cache.getAllDiscoveredTools()).toEqual(
+        expect.arrayContaining(['tool_a', 'tool_b'])
+      );
+    });
+  });
+
+  describe('seed', () => {
+    it('pre-populates the cache with known tool names', () => {
+      cache.seed(['tool_x', 'tool_y']);
+      expect(cache.size).toBe(2);
+      expect(cache.has('tool_x')).toBe(true);
+      expect(cache.has('tool_y')).toBe(true);
+    });
+
+    it('seeded tools are treated as already discovered', () => {
+      cache.seed(['tool_a']);
+
+      const messages: BaseMessage[] = [
+        createAIWithToolCalls(['tc_1']),
+        createToolSearchResult(['tool_a', 'tool_b'], 'tc_1'),
+      ];
+
+      // tool_a is already seeded, only tool_b should be new
+      const result = cache.getNewDiscoveries(messages);
+      expect(result).toEqual(['tool_b']);
+    });
+  });
+
+  describe('reset', () => {
+    it('clears all state', () => {
+      cache.seed(['tool_a']);
+      expect(cache.size).toBe(1);
+
+      cache.reset();
+      expect(cache.size).toBe(0);
+      expect(cache.has('tool_a')).toBe(false);
+    });
+
+    it('allows re-discovery after reset', () => {
+      const messages: BaseMessage[] = [
+        createAIWithToolCalls(['tc_1']),
+        createToolSearchResult(['tool_a'], 'tc_1'),
+      ];
+
+      cache.getNewDiscoveries(messages);
+      expect(cache.size).toBe(1);
+
+      cache.reset();
+
+      // Same messages should produce discoveries again
+      const result = cache.getNewDiscoveries(messages);
+      expect(result).toEqual(['tool_a']);
+    });
+  });
+});

package/src/utils/contextPressure.test.ts

@@ -1,4 +1,8 @@
-import { HumanMessage, AIMessage, SystemMessage } from '@langchain/core/messages';
+import {
+  HumanMessage,
+  AIMessage,
+  SystemMessage,
+} from '@langchain/core/messages';
 import { MULTI_DOCUMENT_THRESHOLD } from '@/common/constants';
 import {
   detectDocuments,
@@ -83,9 +87,7 @@ describe('detectDocuments', () => {
   it('ignores non-human messages with document patterns', () => {
     // detectDocuments scans ALL messages — AI messages with doc patterns
     // should still be detected (they may contain tool results with docs)
-    const messages = [
-      new AIMessage('Found: # "results.csv"\nData here'),
-    ];
+    const messages = [new AIMessage('Found: # "results.csv"\nData here')];
     const result = detectDocuments(messages);
     expect(result.count).toBe(1);
   });
@@ -111,19 +113,27 @@ describe('detectDocuments', () => {
 
 describe('shouldInjectMultiDocHint', () => {
   it('returns true when document count meets threshold and no AI response', () => {
-    expect(shouldInjectMultiDocHint(MULTI_DOCUMENT_THRESHOLD, false)).toBe(true);
+    expect(shouldInjectMultiDocHint(MULTI_DOCUMENT_THRESHOLD, false)).toBe(
+      true
+    );
   });
 
   it('returns true when document count exceeds threshold', () => {
-    expect(shouldInjectMultiDocHint(MULTI_DOCUMENT_THRESHOLD + 5, false)).toBe(true);
+    expect(shouldInjectMultiDocHint(MULTI_DOCUMENT_THRESHOLD + 5, false)).toBe(
+      true
+    );
   });
 
   it('returns false when document count is below threshold', () => {
-    expect(shouldInjectMultiDocHint(MULTI_DOCUMENT_THRESHOLD - 1, false)).toBe(false);
+    expect(shouldInjectMultiDocHint(MULTI_DOCUMENT_THRESHOLD - 1, false)).toBe(
+      false
+    );
   });
 
   it('returns false when AI has already responded', () => {
-    expect(shouldInjectMultiDocHint(MULTI_DOCUMENT_THRESHOLD, true)).toBe(false);
+    expect(shouldInjectMultiDocHint(MULTI_DOCUMENT_THRESHOLD, true)).toBe(
+      false
+    );
   });
 
   it('returns false with zero documents', () => {
@@ -143,7 +153,12 @@ describe('shouldInjectMultiDocHint', () => {
 
 describe('buildMultiDocHintContent', () => {
   it('includes document count in header', () => {
-    const content = buildMultiDocHintContent(4, ['a.pdf', 'b.pdf', 'c.pdf', 'd.pdf']);
+    const content = buildMultiDocHintContent(4, [
+      'a.pdf',
+      'b.pdf',
+      'c.pdf',
+      'd.pdf',
+    ]);
     expect(content).toContain('4 documents detected');
   });
 

package/src/utils/index.ts

@@ -9,3 +9,5 @@ export * from './contextAnalytics';
 export * from './schema';
 export * from './toolCallContinuation';
 export * from './contextPressure';
+export * from './toolDiscoveryCache';
+export * from './pruneCalibration';

package/src/utils/pruneCalibration.ts

@@ -0,0 +1,92 @@
+// src/utils/pruneCalibration.ts
+import type { PruneCalibrationState } from '@/types/graph';
+import {
+  PRUNING_EMA_ALPHA,
+  PRUNING_INITIAL_CALIBRATION,
+} from '@/common/constants';
+
+/**
+ * Creates an initial pruning calibration state.
+ *
+ * @param initialRatio - Starting calibration ratio (default: 1.0)
+ * @returns Fresh calibration state
+ */
+export function createPruneCalibration(
+  initialRatio?: number
+): PruneCalibrationState {
+  return {
+    ratio: initialRatio ?? PRUNING_INITIAL_CALIBRATION,
+    iterations: 0,
+  };
+}
+
+/**
+ * Updates the pruning calibration using Exponential Moving Average (EMA).
+ *
+ * Problem: Without calibration, the pruner's token estimates can diverge from
+ * reality across iterations, causing either:
+ * - Over-pruning (context cliff): Too many messages removed at once, losing critical tool results
+ * - Under-pruning: Not enough messages removed, hitting hard token limits
+ *
+ * Solution: Track the ratio between actual token usage (from API response) and
+ * estimated token usage (from our token counter). Apply EMA smoothing so the
+ * calibration adjusts gradually, preventing oscillation.
+ *
+ * The calibration ratio is applied to maxTokens in the pruner:
+ *   effectiveMaxTokens = maxTokens * calibrationRatio
+ *
+ * If actual > estimated → ratio decreases → prune more aggressively
+ * If actual < estimated → ratio increases → prune less aggressively
+ *
+ * @param state - Current calibration state
+ * @param actualTokens - Actual token count from API response (UsageMetadata)
+ * @param estimatedTokens - Estimated token count from token counter
+ * @param alpha - EMA smoothing factor (default: PRUNING_EMA_ALPHA)
+ * @returns Updated calibration state (new object, does not mutate input)
+ */
+export function updatePruneCalibration(
+  state: PruneCalibrationState,
+  actualTokens: number,
+  estimatedTokens: number,
+  alpha: number = PRUNING_EMA_ALPHA
+): PruneCalibrationState {
+  // Guard against division by zero or invalid inputs
+  if (estimatedTokens <= 0 || actualTokens <= 0) {
+    return state;
+  }
+
+  // Raw ratio: how much our estimate differs from reality
+  const observedRatio = estimatedTokens / actualTokens;
+
+  // Clamp to prevent extreme adjustments from outlier readings
+  // Range [0.5, 2.0] means we never more than double or halve the budget
+  const clampedRatio = Math.max(0.5, Math.min(2.0, observedRatio));
+
+  // Apply EMA: new_ratio = α * observed + (1 - α) * previous
+  const newRatio = alpha * clampedRatio + (1 - alpha) * state.ratio;
+
+  return {
+    ratio: newRatio,
+    iterations: state.iterations + 1,
+  };
+}
+
+/**
+ * Applies the calibration ratio to a max token budget.
+ * The ratio adjusts the effective budget so pruning is more or less aggressive
+ * based on observed vs. estimated token divergence.
+ *
+ * @param maxTokens - Raw max token budget
+ * @param state - Current calibration state
+ * @returns Adjusted max token budget
+ */
+export function applyCalibration(
+  maxTokens: number,
+  state: PruneCalibrationState
+): number {
+  if (state.iterations === 0) {
+    // No calibration data yet — use raw budget
+    return maxTokens;
+  }
+  return Math.floor(maxTokens * state.ratio);
+}