@illuma-ai/agents 1.0.96 → 1.1.0

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

@@ -0,0 +1,262 @@
+import {
+  HumanMessage,
+  AIMessage,
+  SystemMessage,
+} from '@langchain/core/messages';
+import { MULTI_DOCUMENT_THRESHOLD } from '@/common/constants';
+import {
+  detectDocuments,
+  shouldInjectMultiDocHint,
+  buildMultiDocHintContent,
+  buildPostPruneNote,
+  hasTaskTool,
+} from './contextPressure';
+
+// ============================================================================
+// detectDocuments
+// ============================================================================
+
+describe('detectDocuments', () => {
+  it('returns zero when no documents are present', () => {
+    const messages = [
+      new HumanMessage('Hello, what can you do?'),
+      new AIMessage('I can help with many things.'),
+    ];
+    const result = detectDocuments(messages);
+    expect(result.count).toBe(0);
+    expect(result.names).toEqual([]);
+  });
+
+  it('detects documents from # "filename" pattern', () => {
+    const messages = [
+      new HumanMessage(
+        'Attached document(s):\n# "report.pdf"\nContent here\n# "analysis.docx"\nMore content'
+      ),
+    ];
+    const result = detectDocuments(messages);
+    expect(result.count).toBe(2);
+    expect(result.names).toEqual(['report.pdf', 'analysis.docx']);
+  });
+
+  it('detects documents from "user has attached" pattern', () => {
+    const messages = [
+      new HumanMessage(
+        'The user has attached: **budget.xlsx, summary.pdf, notes.txt**'
+      ),
+    ];
+    const result = detectDocuments(messages);
+    expect(result.count).toBe(3);
+    expect(result.names).toEqual(['budget.xlsx', 'summary.pdf', 'notes.txt']);
+  });
+
+  it('deduplicates documents across messages', () => {
+    const messages = [
+      new HumanMessage('# "report.pdf"\nContent'),
+      new HumanMessage('# "report.pdf"\nSame doc again'),
+      new HumanMessage('# "other.pdf"\nDifferent doc'),
+    ];
+    const result = detectDocuments(messages);
+    expect(result.count).toBe(2);
+    expect(result.names).toEqual(['report.pdf', 'other.pdf']);
+  });
+
+  it('deduplicates across both patterns', () => {
+    const messages = [
+      new HumanMessage('# "report.pdf"\nContent'),
+      new HumanMessage('The user has attached: **report.pdf, budget.xlsx**'),
+    ];
+    const result = detectDocuments(messages);
+    expect(result.count).toBe(2);
+    expect(result.names).toEqual(['report.pdf', 'budget.xlsx']);
+  });
+
+  it('handles array content (multi-part messages)', () => {
+    const messages = [
+      new HumanMessage({
+        content: [
+          { type: 'text', text: '# "doc1.pdf"\nPart 1' },
+          { type: 'text', text: '# "doc2.pdf"\nPart 2' },
+        ],
+      }),
+    ];
+    const result = detectDocuments(messages);
+    expect(result.count).toBe(2);
+    expect(result.names).toEqual(['doc1.pdf', 'doc2.pdf']);
+  });
+
+  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 result = detectDocuments(messages);
+    expect(result.count).toBe(1);
+  });
+
+  it('handles empty messages array', () => {
+    const result = detectDocuments([]);
+    expect(result.count).toBe(0);
+    expect(result.names).toEqual([]);
+  });
+
+  it('handles case-insensitive "user has attached" pattern', () => {
+    const messages = [
+      new HumanMessage('The User Has Attached: **file1.pdf, file2.pdf**'),
+    ];
+    const result = detectDocuments(messages);
+    expect(result.count).toBe(2);
+  });
+});
+
+// ============================================================================
+// shouldInjectMultiDocHint
+// ============================================================================
+
+describe('shouldInjectMultiDocHint', () => {
+  it('returns true when document count meets threshold and no AI response', () => {
+    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
+    );
+  });
+
+  it('returns false when document count is below threshold', () => {
+    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
+    );
+  });
+
+  it('returns false with zero documents', () => {
+    expect(shouldInjectMultiDocHint(0, false)).toBe(false);
+  });
+
+  it('uses MULTI_DOCUMENT_THRESHOLD constant (currently 3)', () => {
+    expect(MULTI_DOCUMENT_THRESHOLD).toBe(3);
+    expect(shouldInjectMultiDocHint(2, false)).toBe(false);
+    expect(shouldInjectMultiDocHint(3, false)).toBe(true);
+  });
+});
+
+// ============================================================================
+// buildMultiDocHintContent
+// ============================================================================
+
+describe('buildMultiDocHintContent', () => {
+  it('includes document count in header', () => {
+    const content = buildMultiDocHintContent(4, [
+      'a.pdf',
+      'b.pdf',
+      'c.pdf',
+      'd.pdf',
+    ]);
+    expect(content).toContain('4 documents detected');
+  });
+
+  it('lists all document names', () => {
+    const names = ['report.pdf', 'budget.xlsx', 'summary.docx'];
+    const content = buildMultiDocHintContent(3, names);
+    expect(content).toContain('report.pdf');
+    expect(content).toContain('budget.xlsx');
+    expect(content).toContain('summary.docx');
+  });
+
+  it('mentions the task tool for delegation', () => {
+    const content = buildMultiDocHintContent(3, ['a', 'b', 'c']);
+    expect(content).toContain('"task" tool');
+    expect(content).toContain('sub-agent');
+  });
+
+  it('does NOT contain any token numbers or budget percentages', () => {
+    const content = buildMultiDocHintContent(5, ['a', 'b', 'c', 'd', 'e']);
+    expect(content).not.toMatch(/\d+%/);
+    expect(content).not.toMatch(/\d+ of \d+ tokens/);
+    expect(content).not.toMatch(/tokens remaining/);
+    expect(content).not.toMatch(/BUDGET/i);
+  });
+});
+
+// ============================================================================
+// buildPostPruneNote
+// ============================================================================
+
+describe('buildPostPruneNote', () => {
+  it('returns null when no messages were discarded', () => {
+    expect(buildPostPruneNote(0, true)).toBeNull();
+    expect(buildPostPruneNote(0, false)).toBeNull();
+  });
+
+  it('returns null for negative discard count', () => {
+    expect(buildPostPruneNote(-5, true)).toBeNull();
+  });
+
+  it('returns note with summary reference when summary exists', () => {
+    const note = buildPostPruneNote(10, true);
+    expect(note).not.toBeNull();
+    expect(note).toContain('summarized above');
+    expect(note).toContain('"task" tool');
+  });
+
+  it('returns note without summary reference when no summary', () => {
+    const note = buildPostPruneNote(10, false);
+    expect(note).not.toBeNull();
+    expect(note).toContain('removed to maintain context');
+    expect(note).toContain('"task" tool');
+  });
+
+  it('does NOT contain any token numbers or budget percentages', () => {
+    const noteWithSummary = buildPostPruneNote(20, true)!;
+    const noteWithout = buildPostPruneNote(20, false)!;
+    for (const note of [noteWithSummary, noteWithout]) {
+      expect(note).not.toMatch(/\d+%/);
+      expect(note).not.toMatch(/\d+ of \d+ tokens/);
+      expect(note).not.toMatch(/tokens remaining/);
+      expect(note).not.toMatch(/BUDGET/i);
+      expect(note).not.toMatch(/CRITICAL/i);
+      expect(note).not.toMatch(/WARNING/i);
+    }
+  });
+});
+
+// ============================================================================
+// hasTaskTool
+// ============================================================================
+
+describe('hasTaskTool', () => {
+  it('returns true when task tool exists', () => {
+    const tools = [{ name: 'search' }, { name: 'task' }, { name: 'code' }];
+    expect(hasTaskTool(tools)).toBe(true);
+  });
+
+  it('returns false when task tool does not exist', () => {
+    const tools = [{ name: 'search' }, { name: 'code' }];
+    expect(hasTaskTool(tools)).toBe(false);
+  });
+
+  it('returns false for undefined tools', () => {
+    expect(hasTaskTool(undefined)).toBe(false);
+  });
+
+  it('returns false for empty tools array', () => {
+    expect(hasTaskTool([])).toBe(false);
+  });
+
+  it('handles tools without name property', () => {
+    const tools = [{}, { name: 'task' }, 'not-an-object'] as unknown[];
+    expect(hasTaskTool(tools)).toBe(true);
+  });
+
+  it('returns false when tools have no name property', () => {
+    const tools = [{}, {}, 42] as unknown[];
+    expect(hasTaskTool(tools)).toBe(false);
+  });
+});

package/src/utils/contextPressure.ts

@@ -0,0 +1,188 @@
+/**
+ * Context Pressure Utilities
+ *
+ * Pure functions for context overflow management. These handle:
+ * 1. Multi-document detection — counting attached documents in messages
+ * 2. Multi-document delegation hint — injected when 3+ documents detected
+ * 3. Post-prune context note — injected after pruning/summarization
+ *
+ * DESIGN PRINCIPLE: The LLM never sees raw token numbers. Context overflow
+ * is handled mechanically by pruning (Graph) + auto-continuation (client.js).
+ * Only task-driven hints (multi-document) are injected — never budget-based.
+ *
+ * @see docs/context-overflow-architecture.md
+ */
+
+import type { BaseMessage } from '@langchain/core/messages';
+import { MULTI_DOCUMENT_THRESHOLD } from '@/common/constants';
+
+/** Result of scanning messages for attached documents */
+export interface DocumentDetectionResult {
+  /** Total unique documents detected */
+  count: number;
+  /** Names of detected documents */
+  names: string[];
+}
+
+/**
+ * Scan messages for attached documents using known content patterns.
+ *
+ * Detects documents from:
+ * 1. `# "filename"` headers in "Attached document(s):" blocks (text content)
+ * 2. `**filename1, filename2**` in "The user has attached:" blocks (embedded files)
+ *
+ * @param messages - Conversation messages to scan
+ * @returns Document count and names (deduplicated)
+ */
+export function detectDocuments(
+  messages: BaseMessage[]
+): DocumentDetectionResult {
+  const documentNames: string[] = [];
+
+  for (const msg of messages) {
+    const content = extractTextContent(msg);
+
+    // Pattern 1: # "filename" headers in attached document blocks
+    const docMatches = content.match(/# "([^"]+)"/g);
+    if (docMatches) {
+      for (const match of docMatches) {
+        const name = match.replace(/# "/, '').replace(/"$/, '');
+        if (!documentNames.includes(name)) {
+          documentNames.push(name);
+        }
+      }
+    }
+
+    // Pattern 2: "The user has attached: **file1, file2**" (embedded files)
+    const attachedMatch = content.match(
+      /user has attached:\s*\*\*([^*]+)\*\*/i
+    );
+    if (attachedMatch) {
+      const names = attachedMatch[1]
+        .split(',')
+        .map((n: string) => n.trim())
+        .filter(Boolean);
+      for (const name of names) {
+        if (!documentNames.includes(name)) {
+          documentNames.push(name);
+        }
+      }
+    }
+  }
+
+  return { count: documentNames.length, names: documentNames };
+}
+
+/**
+ * Determine whether the multi-document delegation hint should be injected.
+ *
+ * Only fires on the first iteration (before any AI response) when the
+ * document count meets the threshold. This ensures the agent delegates
+ * upfront rather than trying to process all documents itself.
+ *
+ * @param documentCount - Number of detected documents
+ * @param hasAiResponse - Whether the agent has already responded in this chain
+ * @returns Whether to inject the delegation hint
+ */
+export function shouldInjectMultiDocHint(
+  documentCount: number,
+  hasAiResponse: boolean
+): boolean {
+  return documentCount >= MULTI_DOCUMENT_THRESHOLD && !hasAiResponse;
+}
+
+/**
+ * Build the multi-document delegation hint message content.
+ *
+ * @param documentCount - Number of detected documents
+ * @param documentNames - Names of detected documents
+ * @returns Message content string for injection as HumanMessage
+ */
+export function buildMultiDocHintContent(
+  documentCount: number,
+  documentNames: string[]
+): string {
+  return (
+    `[MULTI-DOCUMENT PROCESSING — ${documentCount} documents detected]\n` +
+    `Documents: ${documentNames.join(', ')}\n\n` +
+    `You have ${documentCount} documents attached. For thorough analysis, use the "task" tool ` +
+    'to delegate each document (or group of related documents) to a sub-agent.\n' +
+    'Each sub-agent has its own fresh context window and can use file_search to retrieve the full document content.\n' +
+    'After all sub-agents complete, synthesize their results into a comprehensive response.\n\n' +
+    'This approach ensures each document gets full attention without context limitations.'
+  );
+}
+
+/**
+ * Build the post-prune context note injected after messages are pruned
+ * and summarized. No token numbers — just a contextual signal that
+ * earlier conversation was compressed.
+ *
+ * @param discardedCount - Number of messages that were pruned
+ * @param hasSummary - Whether a summary was successfully generated
+ * @returns Message content string for injection as SystemMessage, or null if no note needed
+ */
+export function buildPostPruneNote(
+  discardedCount: number,
+  hasSummary: boolean
+): string | null {
+  if (discardedCount <= 0) {
+    return null;
+  }
+
+  if (hasSummary) {
+    return (
+      '[Context Compressed] Earlier conversation messages have been summarized above. ' +
+      'For complex remaining work that requires deep analysis, consider delegating to ' +
+      'sub-agents using the "task" tool — each gets a fresh context window.'
+    );
+  }
+
+  return (
+    '[Context Compressed] Some earlier conversation messages were removed to maintain context capacity. ' +
+    'For complex remaining work, consider delegating to sub-agents using the "task" tool.'
+  );
+}
+
+/**
+ * Check whether a tool named "task" exists in the agent's tool set.
+ *
+ * @param tools - Array of tool objects or structured tools
+ * @returns Whether the task tool is available
+ */
+export function hasTaskTool(
+  tools: Array<{ name?: string } | unknown> | undefined
+): boolean {
+  if (!tools) {
+    return false;
+  }
+  return tools.some((tool) => {
+    const toolName =
+      typeof tool === 'object' && tool !== null && 'name' in tool
+        ? (tool as { name: string }).name
+        : '';
+    return toolName === 'task';
+  });
+}
+
+/**
+ * Extract text content from a BaseMessage, handling both string and
+ * array content formats.
+ *
+ * @param msg - A LangChain BaseMessage
+ * @returns Flattened text content
+ */
+function extractTextContent(msg: BaseMessage): string {
+  if (typeof msg.content === 'string') {
+    return msg.content;
+  }
+  if (Array.isArray(msg.content)) {
+    return msg.content
+      .map((p: unknown) => {
+        const part = p as Record<string, unknown>;
+        return String(part.text ?? part.content ?? '');
+      })
+      .join(' ');
+  }
+  return '';
+}

package/src/utils/index.ts

@@ -8,3 +8,6 @@ export * from './toonFormat';
 export * from './contextAnalytics';
 export * from './schema';
 export * from './toolCallContinuation';
+export * from './contextPressure';
+export * from './toolDiscoveryCache';
+export * from './pruneCalibration';