@illuma-ai/agents 1.0.96 → 1.1.0

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.96",
+  "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

@@ -19,3 +19,85 @@ export const MIN_THINKING_BUDGET = 1024;
  * compounding across multi-tool conversations (e.g., 10 tool calls).
  */
 export const TOOL_TURN_THINKING_BUDGET = 1024;
+
+// ============================================================================
+// CONTEXT OVERFLOW MANAGEMENT
+//
+// Context overflow is handled mechanically — no token budget numbers are
+// exposed to the LLM. The system uses: pruning (Graph), summarization
+// (summarizeCallback), and auto-continuation (client.js max_tokens detection).
+//
+// See: docs/context-overflow-architecture.md
+// ============================================================================
+
+/**
+ * Minimum number of attached documents before the multi-document delegation
+ * hint is injected. Below this threshold, the agent processes documents
+ * directly within its own context.
+ */
+export const MULTI_DOCUMENT_THRESHOLD = 3;
+
+/**
+ * Context utilization safety buffer multiplier (0-1).
+ * Applied as: effectiveMax = (maxContextTokens - maxOutputTokens) * CONTEXT_SAFETY_BUFFER
+ *
+ * Reserves headroom so the LLM doesn't hit hard token limits mid-generation.
+ * 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;