@illuma-ai/agents 1.0.98 → 1.1.0

package/dist/esm/utils/toolDiscoveryCache.mjs

@@ -0,0 +1,125 @@
+import { MessageTypes, Constants } from '../common/enum.mjs';
+import { TOOL_DISCOVERY_CACHE_MAX_SIZE } from '../common/constants.mjs';
+
+/**
+ * ToolDiscoveryCache provides a run-scoped cache of tool search results.
+ *
+ * Problem: Without caching, every LLM iteration re-parses the full message
+ * history via extractToolDiscoveries() to find tool_search results. In long
+ * conversations with many tool iterations, this is redundant work.
+ *
+ * Solution: Cache discovered tool names by message index. On each iteration,
+ * only scan messages AFTER the last scanned index. Already-seen discoveries
+ * are returned from cache instantly.
+ *
+ * This mirrors the pattern used by VS Code Copilot Chat where tool search
+ * results from prior turns are cached to avoid re-discovery.
+ *
+ * @example
+ * ```ts
+ * const cache = new ToolDiscoveryCache();
+ *
+ * // First call: scans all messages
+ * const newTools = cache.getNewDiscoveries(messages);
+ * // Returns: ['web_search', 'file_read']
+ *
+ * // Second call (3 new messages added): only scans new messages
+ * const moreTools = cache.getNewDiscoveries(messages);
+ * // Returns: ['code_exec'] (only newly discovered)
+ * ```
+ */
+class ToolDiscoveryCache {
+    /** Set of all discovered tool names (deduped) */
+    _discoveredTools = new Set();
+    /** Last message index that was scanned */
+    _lastScannedIndex = -1;
+    /**
+     * Scan messages for new tool_search results since the last scan.
+     * Only processes messages after `_lastScannedIndex` to avoid redundant work.
+     *
+     * @param messages - Full conversation message array
+     * @returns Array of newly discovered tool names (not previously cached)
+     */
+    getNewDiscoveries(messages) {
+        if (messages.length === 0) {
+            return [];
+        }
+        const startIndex = this._lastScannedIndex + 1;
+        if (startIndex >= messages.length) {
+            return [];
+        }
+        const newDiscoveries = [];
+        for (let i = startIndex; i < messages.length; i++) {
+            const msg = messages[i];
+            if (msg.getType() !== MessageTypes.TOOL) {
+                continue;
+            }
+            // Check if this is a tool_search result
+            if (msg.name !== Constants.TOOL_SEARCH) {
+                continue;
+            }
+            // Extract tool references from artifact
+            const artifact = msg.artifact;
+            if (typeof artifact === 'object' && artifact != null) {
+                const refs = artifact.tool_references;
+                if (refs && refs.length > 0) {
+                    for (const ref of refs) {
+                        if (!this._discoveredTools.has(ref.tool_name)) {
+                            // Enforce cache size limit
+                            if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {
+                                break;
+                            }
+                            this._discoveredTools.add(ref.tool_name);
+                            newDiscoveries.push(ref.tool_name);
+                        }
+                    }
+                }
+            }
+        }
+        this._lastScannedIndex = messages.length - 1;
+        return newDiscoveries;
+    }
+    /**
+     * Returns all tool names discovered so far (across all scans).
+     */
+    getAllDiscoveredTools() {
+        return [...this._discoveredTools];
+    }
+    /**
+     * Check if a specific tool has been discovered.
+     */
+    has(toolName) {
+        return this._discoveredTools.has(toolName);
+    }
+    /**
+     * Number of unique tools discovered.
+     */
+    get size() {
+        return this._discoveredTools.size;
+    }
+    /**
+     * Reset the cache (e.g., on graph reset).
+     */
+    reset() {
+        this._discoveredTools.clear();
+        this._lastScannedIndex = -1;
+    }
+    /**
+     * Seed the cache with previously known tool names (e.g., from prior conversation turns).
+     * Does not affect _lastScannedIndex — the next getNewDiscoveries call will still
+     * scan all messages from the beginning.
+     *
+     * @param toolNames - Tool names to pre-seed into the cache
+     */
+    seed(toolNames) {
+        for (const name of toolNames) {
+            if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {
+                break;
+            }
+            this._discoveredTools.add(name);
+        }
+    }
+}
+
+export { ToolDiscoveryCache };
+//# sourceMappingURL=toolDiscoveryCache.mjs.map

package/dist/esm/utils/toolDiscoveryCache.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolDiscoveryCache.mjs","sources":["../../../src/utils/toolDiscoveryCache.ts"],"sourcesContent":["// src/utils/toolDiscoveryCache.ts\nimport type { BaseMessage } from '@langchain/core/messages';\nimport { Constants, MessageTypes } from '@/common';\nimport { TOOL_DISCOVERY_CACHE_MAX_SIZE } from '@/common/constants';\n\n/**\n * Cached tool discovery entry.\n * Stores the tool name and the message index where it was discovered,\n * enabling efficient lookups without re-parsing conversation history.\n */\nexport interface ToolDiscoveryEntry {\n  /** The tool name that was discovered */\n  toolName: string;\n  /** Message index in conversation history where discovery occurred */\n  discoveredAtIndex: number;\n}\n\n/**\n * ToolDiscoveryCache provides a run-scoped cache of tool search results.\n *\n * Problem: Without caching, every LLM iteration re-parses the full message\n * history via extractToolDiscoveries() to find tool_search results. In long\n * conversations with many tool iterations, this is redundant work.\n *\n * Solution: Cache discovered tool names by message index. On each iteration,\n * only scan messages AFTER the last scanned index. Already-seen discoveries\n * are returned from cache instantly.\n *\n * This mirrors the pattern used by VS Code Copilot Chat where tool search\n * results from prior turns are cached to avoid re-discovery.\n *\n * @example\n * ```ts\n * const cache = new ToolDiscoveryCache();\n *\n * // First call: scans all messages\n * const newTools = cache.getNewDiscoveries(messages);\n * // Returns: ['web_search', 'file_read']\n *\n * // Second call (3 new messages added): only scans new messages\n * const moreTools = cache.getNewDiscoveries(messages);\n * // Returns: ['code_exec'] (only newly discovered)\n * ```\n */\nexport class ToolDiscoveryCache {\n  /** Set of all discovered tool names (deduped) */\n  private _discoveredTools: Set<string> = new Set();\n  /** Last message index that was scanned */\n  private _lastScannedIndex: number = -1;\n\n  /**\n   * Scan messages for new tool_search results since the last scan.\n   * Only processes messages after `_lastScannedIndex` to avoid redundant work.\n   *\n   * @param messages - Full conversation message array\n   * @returns Array of newly discovered tool names (not previously cached)\n   */\n  getNewDiscoveries(messages: BaseMessage[]): string[] {\n    if (messages.length === 0) {\n      return [];\n    }\n\n    const startIndex = this._lastScannedIndex + 1;\n    if (startIndex >= messages.length) {\n      return [];\n    }\n\n    const newDiscoveries: string[] = [];\n\n    for (let i = startIndex; i < messages.length; i++) {\n      const msg = messages[i];\n      if (msg.getType() !== MessageTypes.TOOL) {\n        continue;\n      }\n\n      // Check if this is a tool_search result\n      if ((msg as { name?: string }).name !== Constants.TOOL_SEARCH) {\n        continue;\n      }\n\n      // Extract tool references from artifact\n      const artifact = (msg as { artifact?: unknown }).artifact;\n      if (typeof artifact === 'object' && artifact != null) {\n        const refs = (\n          artifact as { tool_references?: Array<{ tool_name: string }> }\n        ).tool_references;\n        if (refs && refs.length > 0) {\n          for (const ref of refs) {\n            if (!this._discoveredTools.has(ref.tool_name)) {\n              // Enforce cache size limit\n              if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {\n                break;\n              }\n              this._discoveredTools.add(ref.tool_name);\n              newDiscoveries.push(ref.tool_name);\n            }\n          }\n        }\n      }\n    }\n\n    this._lastScannedIndex = messages.length - 1;\n    return newDiscoveries;\n  }\n\n  /**\n   * Returns all tool names discovered so far (across all scans).\n   */\n  getAllDiscoveredTools(): string[] {\n    return [...this._discoveredTools];\n  }\n\n  /**\n   * Check if a specific tool has been discovered.\n   */\n  has(toolName: string): boolean {\n    return this._discoveredTools.has(toolName);\n  }\n\n  /**\n   * Number of unique tools discovered.\n   */\n  get size(): number {\n    return this._discoveredTools.size;\n  }\n\n  /**\n   * Reset the cache (e.g., on graph reset).\n   */\n  reset(): void {\n    this._discoveredTools.clear();\n    this._lastScannedIndex = -1;\n  }\n\n  /**\n   * Seed the cache with previously known tool names (e.g., from prior conversation turns).\n   * Does not affect _lastScannedIndex — the next getNewDiscoveries call will still\n   * scan all messages from the beginning.\n   *\n   * @param toolNames - Tool names to pre-seed into the cache\n   */\n  seed(toolNames: string[]): void {\n    for (const name of toolNames) {\n      if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {\n        break;\n      }\n      this._discoveredTools.add(name);\n    }\n  }\n}\n"],"names":[],"mappings":";;;AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BG;MACU,kBAAkB,CAAA;;AAErB,IAAA,gBAAgB,GAAgB,IAAI,GAAG,EAAE;;IAEzC,iBAAiB,GAAW,EAAE;AAEtC;;;;;;AAMG;AACH,IAAA,iBAAiB,CAAC,QAAuB,EAAA;AACvC,QAAA,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE;AACzB,YAAA,OAAO,EAAE;QACX;AAEA,QAAA,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,GAAG,CAAC;AAC7C,QAAA,IAAI,UAAU,IAAI,QAAQ,CAAC,MAAM,EAAE;AACjC,YAAA,OAAO,EAAE;QACX;QAEA,MAAM,cAAc,GAAa,EAAE;AAEnC,QAAA,KAAK,IAAI,CAAC,GAAG,UAAU,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;AACjD,YAAA,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC;YACvB,IAAI,GAAG,CAAC,OAAO,EAAE,KAAK,YAAY,CAAC,IAAI,EAAE;gBACvC;YACF;;YAGA,IAAK,GAAyB,CAAC,IAAI,KAAK,SAAS,CAAC,WAAW,EAAE;gBAC7D;YACF;;AAGA,YAAA,MAAM,QAAQ,GAAI,GAA8B,CAAC,QAAQ;YACzD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,IAAI,IAAI,EAAE;AACpD,gBAAA,MAAM,IAAI,GACR,QACD,CAAC,eAAe;gBACjB,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE;AAC3B,oBAAA,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE;AACtB,wBAAA,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;;4BAE7C,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,6BAA6B,EAAE;gCAC/D;4BACF;4BACA,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC;AACxC,4BAAA,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;wBACpC;oBACF;gBACF;YACF;QACF;QAEA,IAAI,CAAC,iBAAiB,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC;AAC5C,QAAA,OAAO,cAAc;IACvB;AAEA;;AAEG;IACH,qBAAqB,GAAA;AACnB,QAAA,OAAO,CAAC,GAAG,IAAI,CAAC,gBAAgB,CAAC;IACnC;AAEA;;AAEG;AACH,IAAA,GAAG,CAAC,QAAgB,EAAA;QAClB,OAAO,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC5C;AAEA;;AAEG;AACH,IAAA,IAAI,IAAI,GAAA;AACN,QAAA,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI;IACnC;AAEA;;AAEG;IACH,KAAK,GAAA;AACH,QAAA,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE;AAC7B,QAAA,IAAI,CAAC,iBAAiB,GAAG,EAAE;IAC7B;AAEA;;;;;;AAMG;AACH,IAAA,IAAI,CAAC,SAAmB,EAAA;AACtB,QAAA,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE;YAC5B,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,6BAA6B,EAAE;gBAC/D;YACF;AACA,YAAA,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;QACjC;IACF;AACD;;;;"}

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

@@ -116,7 +116,9 @@ export declare class AgentContext {
     summarizeCallback?: (messages: BaseMessage[]) => Promise<string | undefined>;
     /** Pre-existing summary loaded from persistent storage, injected into context on new turns */
     persistedSummary?: string;
-    constructor({ agentId, name, description, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, summarizeCallback, persistedSummary, }: {
+    /** Summarization configuration controlling trigger strategy, reserve ratio, and EMA calibration */
+    summarizationConfig?: t.SummarizationConfig;
+    constructor({ agentId, name, description, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, summarizeCallback, persistedSummary, summarizationConfig, }: {
         agentId: string;
         name?: string;
         description?: string;
@@ -140,6 +142,7 @@ export declare class AgentContext {
         discoveredTools?: string[];
         summarizeCallback?: (messages: BaseMessage[]) => Promise<string | undefined>;
         persistedSummary?: string;
+        summarizationConfig?: t.SummarizationConfig;
     });
     /**
      * Checks if structured output mode is enabled for this agent.

package/dist/types/common/constants.d.ts

@@ -30,3 +30,38 @@ export declare const MULTI_DOCUMENT_THRESHOLD = 3;
  * 0.9 = 10% reserved for safety.
  */
 export declare const CONTEXT_SAFETY_BUFFER = 0.9;
+/**
+ * Default context utilization percentage (0-100) at which summarization triggers.
+ * When the context window is ≥80% full, pruning + summarization activates.
+ */
+export declare const SUMMARIZATION_CONTEXT_THRESHOLD = 80;
+/**
+ * Default reserve ratio (0-1) — fraction of context window to preserve as recent messages.
+ * 0.3 means 30% of the context budget is reserved for the most recent messages,
+ * ensuring the model always has immediate conversation history even after aggressive pruning.
+ */
+export declare const SUMMARIZATION_RESERVE_RATIO = 0.3;
+/**
+ * Default EMA (Exponential Moving Average) alpha for pruning calibration.
+ * Controls how quickly the calibration adapts to new token counts.
+ * Higher α = faster adaptation (more responsive to recent changes).
+ * Lower α = smoother adaptation (more stable across iterations).
+ * 0.3 provides a balance between responsiveness and stability.
+ */
+export declare const PRUNING_EMA_ALPHA = 0.3;
+/**
+ * Default initial calibration ratio for EMA pruning.
+ * 1.0 means no adjustment on the first iteration (trust the raw token counts).
+ * Subsequent iterations will adjust based on actual vs. estimated token usage.
+ */
+export declare const PRUNING_INITIAL_CALIBRATION = 1;
+/**
+ * Maximum number of tool discovery entries to cache per conversation.
+ * Prevents unbounded memory growth in very long conversations.
+ */
+export declare const TOOL_DISCOVERY_CACHE_MAX_SIZE = 200;
+/**
+ * Maximum length of system message content to hash for deduplication.
+ * Messages longer than this are always considered unique (hashing would be expensive).
+ */
+export declare const DEDUP_MAX_CONTENT_LENGTH = 10000;

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

@@ -73,6 +73,13 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     runId: string | undefined;
     startIndex: number;
     signal?: AbortSignal;
+    /** Cached summary from the first prune in this run.
+     * Reused for subsequent prunes to avoid blocking LLM calls on every tool iteration. */
+    private _cachedRunSummary;
+    /** EMA-based pruning calibration state — smooths token budget adjustments across iterations */
+    private _pruneCalibration;
+    /** Run-scoped tool discovery cache — avoids re-parsing conversation history on every iteration */
+    private _toolDiscoveryCache;
     /** Map of agent contexts by agent ID */
     agentContexts: Map<string, AgentContext>;
     /** Default agent ID to use */
@@ -105,6 +112,24 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * @returns Shallow-cloned clientOptions with reduced thinking budget, or the original if no reduction needed
      */
     getAdaptiveClientOptions(clientOptions: t.ClientOptions, provider: Providers): t.ClientOptions;
+    /**
+     * Determines whether summarization should trigger based on SummarizationConfig.
+     *
+     * Supports three trigger strategies:
+     * - contextPercentage (default): Trigger when context utilization >= threshold%
+     * - messageCount: Trigger when pruned message count >= threshold
+     * - tokenThreshold: Trigger when total estimated tokens >= threshold
+     *
+     * When no config is provided, always triggers (preserves backward compatibility).
+     *
+     * @param prunedMessageCount - Number of messages that were pruned
+     * @param maxContextTokens - Maximum context token budget
+     * @param indexTokenCountMap - Token count map by message index
+     * @param instructionTokens - Token count for instructions/system message
+     * @param config - Optional SummarizationConfig
+     * @returns Whether summarization should be triggered
+     */
+    private shouldTriggerSummarization;
     /**
      * Returns the normalized finish/stop reason from the last LLM invocation.
      * Used by callers to detect when the response was truncated due to max_tokens.

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

@@ -0,0 +1,25 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Deduplicates consecutive identical system messages in the context window.
+ *
+ * Problem: In long tool-use chains, the same system messages (e.g., post-prune notes,
+ * conversation summaries) can accumulate when the context is rebuilt on each iteration.
+ * These duplicates waste tokens without adding information.
+ *
+ * Strategy: Only deduplicate system messages that appear consecutively or are exact
+ * duplicates of an earlier system message. The FIRST occurrence is always kept.
+ * Non-system messages (human, ai, tool) are never touched.
+ *
+ * Important constraints:
+ * - The first system message (index 0) is ALWAYS preserved (it's the main system prompt)
+ * - Only system messages are candidates for deduplication
+ * - Messages with content longer than DEDUP_MAX_CONTENT_LENGTH are skipped (too expensive to compare)
+ * - Content comparison is by string equality (fast and deterministic)
+ *
+ * @param messages - The message array to deduplicate (not mutated)
+ * @returns A new array with duplicate system messages removed, and the count of removed messages
+ */
+export declare function deduplicateSystemMessages(messages: BaseMessage[]): {
+    messages: BaseMessage[];
+    removedCount: number;
+};

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

@@ -6,3 +6,4 @@ export * from './cache';
 export * from './content';
 export * from './tools';
 export * from './summarize';
+export * from './dedup';

package/dist/types/types/graph.d.ts

@@ -343,6 +343,63 @@ export interface StructuredOutputInput {
     /** Whether to enforce strict schema validation */
     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. */
@@ -412,4 +469,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/dist/types/utils/index.d.ts

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

package/dist/types/utils/pruneCalibration.d.ts

@@ -0,0 +1,43 @@
+import type { PruneCalibrationState } from '@/types/graph';
+/**
+ * Creates an initial pruning calibration state.
+ *
+ * @param initialRatio - Starting calibration ratio (default: 1.0)
+ * @returns Fresh calibration state
+ */
+export declare function createPruneCalibration(initialRatio?: number): PruneCalibrationState;
+/**
+ * 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 declare function updatePruneCalibration(state: PruneCalibrationState, actualTokens: number, estimatedTokens: number, alpha?: number): PruneCalibrationState;
+/**
+ * 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 declare function applyCalibration(maxTokens: number, state: PruneCalibrationState): number;

package/dist/types/utils/toolDiscoveryCache.d.ts

@@ -0,0 +1,77 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Cached tool discovery entry.
+ * Stores the tool name and the message index where it was discovered,
+ * enabling efficient lookups without re-parsing conversation history.
+ */
+export interface ToolDiscoveryEntry {
+    /** The tool name that was discovered */
+    toolName: string;
+    /** Message index in conversation history where discovery occurred */
+    discoveredAtIndex: number;
+}
+/**
+ * ToolDiscoveryCache provides a run-scoped cache of tool search results.
+ *
+ * Problem: Without caching, every LLM iteration re-parses the full message
+ * history via extractToolDiscoveries() to find tool_search results. In long
+ * conversations with many tool iterations, this is redundant work.
+ *
+ * Solution: Cache discovered tool names by message index. On each iteration,
+ * only scan messages AFTER the last scanned index. Already-seen discoveries
+ * are returned from cache instantly.
+ *
+ * This mirrors the pattern used by VS Code Copilot Chat where tool search
+ * results from prior turns are cached to avoid re-discovery.
+ *
+ * @example
+ * ```ts
+ * const cache = new ToolDiscoveryCache();
+ *
+ * // First call: scans all messages
+ * const newTools = cache.getNewDiscoveries(messages);
+ * // Returns: ['web_search', 'file_read']
+ *
+ * // Second call (3 new messages added): only scans new messages
+ * const moreTools = cache.getNewDiscoveries(messages);
+ * // Returns: ['code_exec'] (only newly discovered)
+ * ```
+ */
+export declare class ToolDiscoveryCache {
+    /** Set of all discovered tool names (deduped) */
+    private _discoveredTools;
+    /** Last message index that was scanned */
+    private _lastScannedIndex;
+    /**
+     * Scan messages for new tool_search results since the last scan.
+     * Only processes messages after `_lastScannedIndex` to avoid redundant work.
+     *
+     * @param messages - Full conversation message array
+     * @returns Array of newly discovered tool names (not previously cached)
+     */
+    getNewDiscoveries(messages: BaseMessage[]): string[];
+    /**
+     * Returns all tool names discovered so far (across all scans).
+     */
+    getAllDiscoveredTools(): string[];
+    /**
+     * Check if a specific tool has been discovered.
+     */
+    has(toolName: string): boolean;
+    /**
+     * Number of unique tools discovered.
+     */
+    get size(): number;
+    /**
+     * Reset the cache (e.g., on graph reset).
+     */
+    reset(): void;
+    /**
+     * Seed the cache with previously known tool names (e.g., from prior conversation turns).
+     * Does not affect _lastScannedIndex — the next getNewDiscoveries call will still
+     * scan all messages from the beginning.
+     *
+     * @param toolNames - Tool names to pre-seed into the cache
+     */
+    seed(toolNames: string[]): void;
+}

package/package.json

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

package/src/agents/AgentContext.ts

@@ -50,6 +50,7 @@ export class AgentContext {
       discoveredTools,
       summarizeCallback,
       persistedSummary,
+      summarizationConfig,
     } = agentConfig;
 
     // Normalize structured output: support both camelCase and snake_case inputs
@@ -95,6 +96,7 @@ export class AgentContext {
       discoveredTools,
       summarizeCallback,
       persistedSummary,
+      summarizationConfig,
     });
 
     if (tokenCounter) {
@@ -246,6 +248,8 @@ export class AgentContext {
   summarizeCallback?: (messages: BaseMessage[]) => Promise<string | undefined>;
   /** Pre-existing summary loaded from persistent storage, injected into context on new turns */
   persistedSummary?: string;
+  /** Summarization configuration controlling trigger strategy, reserve ratio, and EMA calibration */
+  summarizationConfig?: t.SummarizationConfig;
 
   constructor({
     agentId,
@@ -271,6 +275,7 @@ export class AgentContext {
     discoveredTools,
     summarizeCallback,
     persistedSummary,
+    summarizationConfig,
   }: {
     agentId: string;
     name?: string;
@@ -297,6 +302,7 @@ export class AgentContext {
       messages: BaseMessage[]
     ) => Promise<string | undefined>;
     persistedSummary?: string;
+    summarizationConfig?: t.SummarizationConfig;
   }) {
     this.agentId = agentId;
     this.name = name;
@@ -316,6 +322,7 @@ export class AgentContext {
     this.structuredOutput = structuredOutput;
     this.summarizeCallback = summarizeCallback;
     this.persistedSummary = persistedSummary;
+    this.summarizationConfig = summarizationConfig;
     if (reasoningKey) {
       this.reasoningKey = reasoningKey;
     }

package/src/common/constants.ts

@@ -45,3 +45,59 @@ export const MULTI_DOCUMENT_THRESHOLD = 3;
  * 0.9 = 10% reserved for safety.
  */
 export const CONTEXT_SAFETY_BUFFER = 0.9;
+
+// ============================================================================
+// SUMMARIZATION CONFIGURATION DEFAULTS
+//
+// These constants provide sensible defaults for the SummarizationConfig.
+// They can be overridden per-agent via AgentInputs.summarizationConfig.
+// ============================================================================
+
+/**
+ * Default context utilization percentage (0-100) at which summarization triggers.
+ * When the context window is ≥80% full, pruning + summarization activates.
+ */
+export const SUMMARIZATION_CONTEXT_THRESHOLD = 80;
+
+/**
+ * Default reserve ratio (0-1) — fraction of context window to preserve as recent messages.
+ * 0.3 means 30% of the context budget is reserved for the most recent messages,
+ * ensuring the model always has immediate conversation history even after aggressive pruning.
+ */
+export const SUMMARIZATION_RESERVE_RATIO = 0.3;
+
+/**
+ * Default EMA (Exponential Moving Average) alpha for pruning calibration.
+ * Controls how quickly the calibration adapts to new token counts.
+ * Higher α = faster adaptation (more responsive to recent changes).
+ * Lower α = smoother adaptation (more stable across iterations).
+ * 0.3 provides a balance between responsiveness and stability.
+ */
+export const PRUNING_EMA_ALPHA = 0.3;
+
+/**
+ * Default initial calibration ratio for EMA pruning.
+ * 1.0 means no adjustment on the first iteration (trust the raw token counts).
+ * Subsequent iterations will adjust based on actual vs. estimated token usage.
+ */
+export const PRUNING_INITIAL_CALIBRATION = 1.0;
+
+// ============================================================================
+// TOOL DISCOVERY CACHING
+// ============================================================================
+
+/**
+ * Maximum number of tool discovery entries to cache per conversation.
+ * Prevents unbounded memory growth in very long conversations.
+ */
+export const TOOL_DISCOVERY_CACHE_MAX_SIZE = 200;
+
+// ============================================================================
+// MESSAGE DEDUPLICATION
+// ============================================================================
+
+/**
+ * Maximum length of system message content to hash for deduplication.
+ * Messages longer than this are always considered unique (hashing would be expensive).
+ */
+export const DEDUP_MAX_CONTENT_LENGTH = 10000;