@illuma-ai/agents 1.0.98 → 1.1.0

package/src/graphs/nonBlockingSummarization.test.ts

@@ -0,0 +1,307 @@
+/**
+ * nonBlockingSummarization.test.ts
+ *
+ * Tests that the Graph's summarization pipeline is fully non-blocking.
+ * The core invariant: summarizeCallback is NEVER awaited in the hot path.
+ * Instead, the graph uses cached/persisted summaries and fires background updates.
+ */
+
+import {
+  HumanMessage,
+  AIMessage,
+  SystemMessage,
+  BaseMessage,
+} from '@langchain/core/messages';
+import type { TokenCounter } from '@/types/run';
+import { createPruneMessages } from '@/messages/prune';
+
+/**
+ * Simple token counter: ~1 token per 4 characters
+ */
+const simpleTokenCounter: TokenCounter = (msg: BaseMessage): number => {
+  const content =
+    typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
+  return Math.ceil(content.length / 4);
+};
+
+/**
+ * Build a conversation that exceeds the token budget to trigger pruning.
+ * Each message is ~100 tokens (400 chars).
+ */
+function buildLargeConversation(messageCount: number): BaseMessage[] {
+  const messages: BaseMessage[] = [
+    new SystemMessage('You are a helpful assistant.'),
+  ];
+  for (let i = 0; i < messageCount; i++) {
+    const longText = `Message ${i}: ${'x'.repeat(380)}`;
+    if (i % 2 === 0) {
+      messages.push(new HumanMessage(longText));
+    } else {
+      messages.push(new AIMessage(longText));
+    }
+  }
+  return messages;
+}
+
+// ============================================================================
+// Non-blocking summarization behavior
+// ============================================================================
+
+describe('Non-blocking summarization in Graph pruning', () => {
+  /**
+   * Simulates the Graph.ts summarization decision logic (lines 1439-1492).
+   * This is extracted to test the branching behavior without needing a full Graph.
+   */
+  function simulateGraphSummarization(opts: {
+    messagesToRefine: BaseMessage[];
+    cachedRunSummary: string | null;
+    persistedSummary: string | null;
+    summarizeCallback: (msgs: BaseMessage[]) => Promise<string | undefined>;
+  }): {
+    summary: string | undefined;
+    callbackCalled: boolean;
+    wasBlocking: boolean;
+  } {
+    const {
+      messagesToRefine,
+      cachedRunSummary,
+      persistedSummary,
+      summarizeCallback,
+    } = opts;
+
+    let summary: string | undefined;
+    let callbackCalled = false;
+    let wasBlocking = false;
+
+    if (messagesToRefine.length > 0 && summarizeCallback) {
+      if (cachedRunSummary != null) {
+        // Case 1: Reuse cached summary
+        summary = cachedRunSummary;
+        callbackCalled = true;
+        wasBlocking = false;
+        // Fire background update (non-blocking)
+        summarizeCallback(messagesToRefine).catch(() => {});
+      } else if (persistedSummary != null && persistedSummary !== '') {
+        // Case 2: Use persisted summary as fallback
+        summary = persistedSummary;
+        callbackCalled = true;
+        wasBlocking = false;
+        summarizeCallback(messagesToRefine).catch(() => {});
+      } else {
+        // Case 3: No summary exists — skip injection, fire background generation
+        summary = undefined;
+        callbackCalled = true;
+        wasBlocking = false;
+        summarizeCallback(messagesToRefine).catch(() => {});
+      }
+    }
+
+    return { summary, callbackCalled, wasBlocking };
+  }
+
+  it('Case 1: uses cached run summary without blocking', () => {
+    const callback = jest.fn().mockResolvedValue('updated summary');
+    const result = simulateGraphSummarization({
+      messagesToRefine: [new HumanMessage('old msg')],
+      cachedRunSummary: 'existing cached summary',
+      persistedSummary: null,
+      summarizeCallback: callback,
+    });
+
+    expect(result.summary).toBe('existing cached summary');
+    expect(result.wasBlocking).toBe(false);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('Case 2: uses persisted summary as fallback without blocking', () => {
+    const callback = jest.fn().mockResolvedValue('updated summary');
+    const result = simulateGraphSummarization({
+      messagesToRefine: [new HumanMessage('old msg')],
+      cachedRunSummary: null,
+      persistedSummary: 'persisted from last turn',
+      summarizeCallback: callback,
+    });
+
+    expect(result.summary).toBe('persisted from last turn');
+    expect(result.wasBlocking).toBe(false);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('Case 3: no summary available — skips injection, fires background', () => {
+    const callback = jest.fn().mockResolvedValue('new summary');
+    const result = simulateGraphSummarization({
+      messagesToRefine: [new HumanMessage('old msg')],
+      cachedRunSummary: null,
+      persistedSummary: null,
+      summarizeCallback: callback,
+    });
+
+    expect(result.summary).toBeUndefined();
+    expect(result.wasBlocking).toBe(false);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not call callback when no messages were refined', () => {
+    const callback = jest.fn().mockResolvedValue('summary');
+    const result = simulateGraphSummarization({
+      messagesToRefine: [],
+      cachedRunSummary: null,
+      persistedSummary: null,
+      summarizeCallback: callback,
+    });
+
+    expect(result.summary).toBeUndefined();
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it('handles callback failure gracefully', async () => {
+    const callback = jest.fn().mockRejectedValue(new Error('LLM timeout'));
+    const result = simulateGraphSummarization({
+      messagesToRefine: [new HumanMessage('msg')],
+      cachedRunSummary: 'cached',
+      persistedSummary: null,
+      summarizeCallback: callback,
+    });
+
+    // Should still use cached summary
+    expect(result.summary).toBe('cached');
+    // Wait for background promise to settle
+    await new Promise((r) => setTimeout(r, 10));
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('background callback updates cache for subsequent iterations', async () => {
+    let cachedSummary: string | null = null;
+    const callback = jest.fn().mockImplementation(async () => {
+      // Simulate LLM call delay
+      await new Promise((r) => setTimeout(r, 50));
+      const updated = 'background-updated summary';
+      cachedSummary = updated;
+      return updated;
+    });
+
+    // First call: no cache
+    simulateGraphSummarization({
+      messagesToRefine: [new HumanMessage('msg')],
+      cachedRunSummary: null,
+      persistedSummary: 'stale persisted',
+      summarizeCallback: callback,
+    });
+
+    // Initially still using persisted
+    expect(cachedSummary).toBeNull();
+
+    // Wait for background to complete
+    await new Promise((r) => setTimeout(r, 100));
+    expect(cachedSummary).toBe('background-updated summary');
+
+    // Second call: now has cached summary
+    const result2 = simulateGraphSummarization({
+      messagesToRefine: [new HumanMessage('msg2')],
+      cachedRunSummary: cachedSummary,
+      persistedSummary: null,
+      summarizeCallback: callback,
+    });
+    expect(result2.summary).toBe('background-updated summary');
+  });
+});
+
+// ============================================================================
+// Pruning integration with summary injection
+// ============================================================================
+
+describe('Pruning + summary injection flow', () => {
+  it('pruneMessages produces messagesToRefine when context exceeds budget', () => {
+    // Each message ~100 tokens (400 chars). 40 messages = ~4000 tokens.
+    // maxTokens = 200 forces heavy pruning.
+    const messages = buildLargeConversation(40);
+    const maxTokens = 200;
+
+    const prune = createPruneMessages({
+      startIndex: 0,
+      provider: 'anthropic' as any,
+      tokenCounter: simpleTokenCounter,
+      maxTokens,
+      indexTokenCountMap: {},
+    });
+
+    const { context, messagesToRefine } = prune({ messages });
+
+    expect(messagesToRefine.length).toBeGreaterThan(0);
+    expect(context.length).toBeLessThan(messages.length);
+  });
+
+  it('summary is injected after system message when available', () => {
+    const messages: BaseMessage[] = [
+      new SystemMessage('System prompt'),
+      new HumanMessage('Recent question'),
+    ];
+    const summaryText = 'User discussed project deadlines and budget';
+    const summaryMsg = new SystemMessage(
+      `[Conversation Summary]\n${summaryText}`
+    );
+
+    // Insert after system message
+    const systemIdx = messages[0]?.getType() === 'system' ? 1 : 0;
+    const result = [
+      ...messages.slice(0, systemIdx),
+      summaryMsg,
+      ...messages.slice(systemIdx),
+    ];
+
+    expect(result.length).toBe(3);
+    expect(result[0].getType()).toBe('system'); // Original system
+    expect(result[1].content as string).toContain('[Conversation Summary]');
+    expect(result[2].getType()).toBe('human'); // Recent question preserved
+  });
+});
+
+// ============================================================================
+// Multi-turn simulation
+// ============================================================================
+
+describe('Multi-turn conversation with rolling summaries', () => {
+  it('simulates 5 turns with persisted summary handoff', async () => {
+    let persistedSummary: string | null = null;
+    const summaryUpdates: string[] = [];
+
+    const callback = jest
+      .fn()
+      .mockImplementation(async (msgs: BaseMessage[]) => {
+        const msgCount = msgs.length;
+        const summary = `Summary of ${msgCount} messages (turn ${summaryUpdates.length + 1})`;
+        summaryUpdates.push(summary);
+        persistedSummary = summary;
+        return summary;
+      });
+
+    // Simulate 5 conversation turns
+    for (let turn = 0; turn < 5; turn++) {
+      const messages = buildLargeConversation(10);
+      const prune = createPruneMessages({
+        startIndex: 0,
+        provider: 'anthropic' as any,
+        tokenCounter: simpleTokenCounter,
+        maxTokens: 300,
+        indexTokenCountMap: {},
+      });
+      const { messagesToRefine } = prune({ messages });
+
+      if (messagesToRefine.length > 0) {
+        // Simulate Graph behavior: use persisted, fire background
+        const cachedSummary = persistedSummary;
+        if (cachedSummary) {
+          // Non-blocking: use existing summary
+          expect(cachedSummary).toBeDefined();
+        }
+        // Fire background update
+        callback(messagesToRefine).catch(() => {});
+        await new Promise((r) => setTimeout(r, 10));
+      }
+    }
+
+    // All turns should have fired background updates
+    expect(summaryUpdates.length).toBeGreaterThanOrEqual(4);
+    expect(persistedSummary).toContain('Summary of');
+  });
+});

package/src/messages/__tests__/dedup.test.ts

@@ -0,0 +1,166 @@
+// src/messages/__tests__/dedup.test.ts
+import {
+  SystemMessage,
+  HumanMessage,
+  AIMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { deduplicateSystemMessages } from '../dedup';
+
+describe('deduplicateSystemMessages', () => {
+  it('returns empty array unchanged', () => {
+    const result = deduplicateSystemMessages([]);
+    expect(result.messages).toEqual([]);
+    expect(result.removedCount).toBe(0);
+  });
+
+  it('returns single message unchanged', () => {
+    const msgs = [new SystemMessage('Hello')];
+    const result = deduplicateSystemMessages(msgs);
+    expect(result.messages).toHaveLength(1);
+    expect(result.removedCount).toBe(0);
+  });
+
+  it('preserves conversation with no duplicates', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('You are helpful'),
+      new HumanMessage('Hello'),
+      new AIMessage('Hi there'),
+      new SystemMessage('Summary of prior context'),
+      new HumanMessage('What about X?'),
+    ];
+
+    const result = deduplicateSystemMessages(msgs);
+    expect(result.messages).toHaveLength(5);
+    expect(result.removedCount).toBe(0);
+  });
+
+  it('removes duplicate system messages', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('You are helpful'),
+      new SystemMessage('[Conversation Summary]\nUser discussed X'),
+      new HumanMessage('Hello'),
+      new AIMessage('Hi'),
+      new SystemMessage('[Conversation Summary]\nUser discussed X'), // duplicate
+      new HumanMessage('What?'),
+    ];
+
+    const result = deduplicateSystemMessages(msgs);
+    expect(result.messages).toHaveLength(5);
+    expect(result.removedCount).toBe(1);
+    // Verify the duplicate at index 4 was removed
+    expect(result.messages.map((m) => m.getType())).toEqual([
+      'system',
+      'system',
+      'human',
+      'ai',
+      'human',
+    ]);
+  });
+
+  it('keeps the first occurrence of duplicate system messages', () => {
+    const duplicateContent = 'Context was compressed. Summary follows.';
+    const msgs: BaseMessage[] = [
+      new SystemMessage('Main prompt'),
+      new SystemMessage(duplicateContent), // first occurrence
+      new HumanMessage('Q1'),
+      new AIMessage('A1'),
+      new SystemMessage(duplicateContent), // duplicate
+      new HumanMessage('Q2'),
+      new AIMessage('A2'),
+      new SystemMessage(duplicateContent), // another duplicate
+    ];
+
+    const result = deduplicateSystemMessages(msgs);
+    expect(result.messages).toHaveLength(6);
+    expect(result.removedCount).toBe(2);
+  });
+
+  it('never removes non-system messages', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('Prompt'),
+      new HumanMessage('Same content'),
+      new AIMessage('Same content'),
+      new HumanMessage('Same content'), // duplicate content but not system
+      new AIMessage('Same content'), // duplicate content but not system
+    ];
+
+    const result = deduplicateSystemMessages(msgs);
+    expect(result.messages).toHaveLength(5);
+    expect(result.removedCount).toBe(0);
+  });
+
+  it('always preserves the first system message (main prompt)', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('Main system prompt'),
+      new HumanMessage('Hello'),
+      new SystemMessage('Main system prompt'), // duplicate of first
+    ];
+
+    const result = deduplicateSystemMessages(msgs);
+    expect(result.messages).toHaveLength(2);
+    expect(result.removedCount).toBe(1);
+    // First system message is preserved
+    expect(result.messages[0].content as string).toBe('Main system prompt');
+  });
+
+  it('handles tool messages correctly (never deduped)', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('Prompt'),
+      new HumanMessage('Q'),
+      new AIMessage({
+        content: 'Using tool',
+        tool_calls: [{ id: 'tc1', name: 'test', args: {} }],
+      }),
+      new ToolMessage({ content: 'result', tool_call_id: 'tc1' }),
+      new SystemMessage('Post-prune note'),
+      new AIMessage({
+        content: 'Using tool',
+        tool_calls: [{ id: 'tc2', name: 'test', args: {} }],
+      }),
+      new ToolMessage({ content: 'result', tool_call_id: 'tc2' }),
+      new SystemMessage('Post-prune note'), // duplicate system msg
+    ];
+
+    const result = deduplicateSystemMessages(msgs);
+    expect(result.removedCount).toBe(1);
+    // Tool messages are all preserved
+    const toolMsgs = result.messages.filter((m) => m.getType() === 'tool');
+    expect(toolMsgs).toHaveLength(2);
+  });
+
+  it('does not mutate input array', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('Prompt'),
+      new SystemMessage('Dup'),
+      new SystemMessage('Dup'),
+    ];
+    const originalLength = msgs.length;
+
+    deduplicateSystemMessages(msgs);
+    expect(msgs.length).toBe(originalLength);
+  });
+
+  it('handles mixed duplicate patterns', () => {
+    const msgs: BaseMessage[] = [
+      new SystemMessage('A'),
+      new SystemMessage('B'),
+      new SystemMessage('A'), // dup of first
+      new HumanMessage('Q'),
+      new SystemMessage('B'), // dup
+      new SystemMessage('C'),
+      new SystemMessage('C'), // dup
+    ];
+
+    const result = deduplicateSystemMessages(msgs);
+    expect(result.removedCount).toBe(3);
+    expect(result.messages).toHaveLength(4);
+    expect(
+      result.messages.map((m) => {
+        if (typeof m.content === 'string') return m.content;
+        return '';
+      })
+    ).toEqual(['A', 'B', 'Q', 'C']);
+  });
+});

package/src/messages/dedup.ts

@@ -0,0 +1,104 @@
+// src/messages/dedup.ts
+import type { BaseMessage } from '@langchain/core/messages';
+import { MessageTypes } from '@/common';
+import { DEDUP_MAX_CONTENT_LENGTH } from '@/common/constants';
+
+/**
+ * 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 function deduplicateSystemMessages(messages: BaseMessage[]): {
+  messages: BaseMessage[];
+  removedCount: number;
+} {
+  if (messages.length <= 1) {
+    return { messages, removedCount: 0 };
+  }
+
+  const seenSystemContents = new Set<string>();
+  const result: BaseMessage[] = [];
+  let removedCount = 0;
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    const type = msg.getType();
+
+    // Non-system messages are always kept
+    if (type !== MessageTypes.SYSTEM) {
+      result.push(msg);
+      continue;
+    }
+
+    // First system message (main prompt) is always kept
+    if (i === 0) {
+      result.push(msg);
+      // Track its content for dedup of later duplicates
+      const content = getContentString(msg);
+      if (content != null) {
+        seenSystemContents.add(content);
+      }
+      continue;
+    }
+
+    // Get string content for comparison
+    const content = getContentString(msg);
+
+    // Skip dedup for very long or non-string content
+    if (content == null) {
+      result.push(msg);
+      continue;
+    }
+
+    // Check if this exact system message was already seen
+    if (seenSystemContents.has(content)) {
+      removedCount++;
+      continue; // Skip this duplicate
+    }
+
+    // New unique system message — keep it and track
+    seenSystemContents.add(content);
+    result.push(msg);
+  }
+
+  return { messages: result, removedCount };
+}
+
+/**
+ * Extracts a comparable string from a message's content.
+ * Returns null if the content is too large or non-string (skip dedup for those).
+ */
+function getContentString(msg: BaseMessage): string | null {
+  if (typeof msg.content === 'string') {
+    if (msg.content.length > DEDUP_MAX_CONTENT_LENGTH) {
+      return null;
+    }
+    return msg.content;
+  }
+  // Array content (e.g., Anthropic cache_control blocks) — serialize for comparison
+  // but only if reasonably sized
+  try {
+    const serialized = JSON.stringify(msg.content);
+    if (serialized.length > DEDUP_MAX_CONTENT_LENGTH) {
+      return null;
+    }
+    return serialized;
+  } catch {
+    return null;
+  }
+}

package/src/messages/index.ts

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

package/src/tools/CodeExecutor.ts

@@ -94,10 +94,27 @@ export const CodeExecutionToolDescription = `
 Runs code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
 
 Usage:
-- No network access available.
+- No network access available. Do NOT use pip install, npm install, or any package manager.
 - Generated files are automatically delivered; **DO NOT** provide download links.
 - NEVER use this tool to execute malicious code.
 - When a code_id is returned in output, you can edit that code using code_id + old_str + new_str instead of rewriting the entire code block.
+
+Pre-installed Python packages (use directly, no installation needed):
+- Data Science: numpy, pandas
+- Visualization: matplotlib, seaborn, plotly
+- Documents: python-docx, python-pptx, reportlab, fpdf2, PyMuPDF, pdfplumber
+- Spreadsheets: openpyxl, xlsxwriter
+- Image: pillow
+- Data: orjson, lxml, beautifulsoup4, faker
+
+Pre-installed JavaScript packages:
+- pptxgenjs, react, react-dom, react-icons, sharp
+
+Pre-installed Go packages:
+- excelize (Excel), gofpdf (PDF)
+
+Pre-installed R packages:
+- ggplot2, dplyr, tidyr, readxl, writexl, jsonlite, Cairo
 `.trim();
 
 export const CodeExecutionToolName = Constants.EXECUTE_CODE;
@@ -135,11 +152,13 @@ Runs code in a stateless execution environment. Each execution is isolated.
 ✅ ONLY USE FOR:
 - File generation: PowerPoint (.pptx), Word (.docx), PDF (.pdf), Excel (.xlsx)
 - Processing uploaded files (CSV, Excel analysis)
-- Heavy computation requiring Python
+- Heavy computation requiring Python (numpy, pandas for data analytics)
 
 Rules:
-- No network access available
+- No network access — do NOT use pip install, npm install, or any package manager
+- All packages are pre-installed: numpy, pandas, matplotlib, seaborn, plotly, python-docx, python-pptx, reportlab, openpyxl, xlsxwriter, pillow, faker, orjson, lxml, beautifulsoup4
 - Generated files auto-delivered (no download links needed)
+- **Error recovery**: When execution fails, use \`code_id\` + \`old_str\` + \`new_str\` to fix only the broken part — do NOT rewrite the entire code block. This is faster and saves tokens.
 `.trim();
 
   return tool(