@illuma-ai/agents 1.0.96 → 1.1.0

package/src/specs/agent-handoffs.test.ts

@@ -4,7 +4,7 @@ import { HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
-import { Providers, Constants } from '@/common';
+import { Providers, Constants, EdgeType } from '@/common';
 import { StandardGraph } from '@/graphs/Graph';
 import { Run } from '@/run';
 
@@ -94,7 +94,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
       ];
@@ -128,7 +128,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B when needed',
         },
       ];
@@ -192,7 +192,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -223,13 +223,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
         {
           from: 'agent_b',
           to: 'agent_a',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent A',
         },
       ];
@@ -268,12 +268,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
         {
           from: 'agent_b',
           to: 'agent_a',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -334,13 +334,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent C',
         },
       ];
@@ -395,19 +395,19 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'agent_a',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent A for task A',
         },
         {
           from: 'router',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B for task B',
         },
         {
           from: 'router',
           to: 'agent_c',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent C for task C',
         },
       ];
@@ -449,13 +449,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'agent_a',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent A',
         },
         {
           from: 'router',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
       ];
@@ -519,7 +519,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B with instructions',
           prompt: 'Provide specific instructions for agent B',
           promptKey: 'instructions',
@@ -551,7 +551,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           prompt: 'Instructions for handoff',
           // promptKey not specified, should default to 'instructions'
         },
@@ -581,7 +581,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
           prompt: 'Additional context for agent B',
           promptKey: 'context',
@@ -638,7 +638,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_a',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Self-handoff (should be allowed but unusual)',
         },
       ];
@@ -724,7 +724,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
       ];
@@ -759,12 +759,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -806,12 +806,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_c',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -853,7 +853,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'data_analyst',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to data analyst',
           prompt: 'Instructions for the analyst about what to analyze',
           promptKey: 'instructions',
@@ -939,7 +939,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'flight_assistant',
           to: 'hotel_assistant',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to hotel booking',
         },
       ];
@@ -970,7 +970,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_with_underscores',
           to: 'AgentWithCamelCase',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -1007,7 +1007,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'data_analyst',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           // No description provided - should auto-generate from agent name + description
         },
       ];
@@ -1042,7 +1042,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'writer',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -1075,7 +1075,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Custom handoff description that takes priority',
         },
       ];
@@ -1118,9 +1118,9 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'router', to: 'sales', edgeType: 'handoff' },
-        { from: 'router', to: 'support', edgeType: 'handoff' },
-        { from: 'router', to: 'billing', edgeType: 'handoff' },
+        { from: 'router', to: 'sales', edgeType: EdgeType.HANDOFF },
+        { from: 'router', to: 'support', edgeType: EdgeType.HANDOFF },
+        { from: 'router', to: 'billing', edgeType: EdgeType.HANDOFF },
       ];
 
       const run = await Run.create(createTestConfig(agents, edges));
@@ -1176,7 +1176,7 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_b', edgeType: 'handoff' },
+        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.HANDOFF },
       ];
 
       const run = await Run.create(createTestConfig(agents, edges));
@@ -1215,7 +1215,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to B',
         },
       ];
@@ -1255,7 +1255,7 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_b', edgeType: 'handoff' },
+        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.HANDOFF },
       ];
 
       const run = await Run.create(createTestConfig(agents, edges));

package/src/specs/thinking-handoff.test.ts

@@ -3,7 +3,7 @@ import { HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
-import { Providers, Constants } from '@/common';
+import { Providers, Constants, EdgeType } from '@/common';
 import { StandardGraph } from '@/graphs/Graph';
 import { Run } from '@/run';
 
@@ -77,7 +77,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'supervisor',
           to: 'specialist',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to specialist for detailed analysis',
         },
       ];
@@ -166,7 +166,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -223,7 +223,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'coordinator',
           to: 'analyst',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to analyst for deep analysis',
         },
       ];
@@ -297,7 +297,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -360,7 +360,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'supervisor',
           to: 'bedrock_specialist',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to Bedrock specialist',
         },
       ];
@@ -450,12 +450,12 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'router',
           to: 'processor',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
         {
           from: 'processor',
           to: 'reviewer',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -538,7 +538,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -603,7 +603,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: 'handoff',
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 

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(

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);
+    });
+  });
+});