illuma-agents 1.0.26 → 1.0.28

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

@@ -19,6 +19,17 @@ export declare class MultiAgentGraph extends StandardGraph {
     private startingNodes;
     private directEdges;
     private handoffEdges;
+    /**
+     * Map of agentId to parallel group info.
+     * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
+     * Sequential agents (not in any parallel group) have undefined entry.
+     *
+     * Example for: researcher -> [analyst1, analyst2, analyst3] -> summarizer
+     * - researcher: undefined (sequential, order 0)
+     * - analyst1, analyst2, analyst3: { groupId: 1 } (parallel group, order 1)
+     * - summarizer: undefined (sequential, order 2)
+     */
+    private agentParallelGroups;
     constructor(input: t.MultiAgentGraphInput);
     /**
      * Categorize edges into handoff and direct types
@@ -28,6 +39,36 @@ export declare class MultiAgentGraph extends StandardGraph {
      * Analyze graph structure to determine starting nodes and connections
      */
     private analyzeGraph;
+    /**
+     * Compute parallel groups by traversing the graph in execution order.
+     * Assigns incrementing group IDs that reflect the sequential order of execution.
+     *
+     * For: researcher -> [analyst1, analyst2, analyst3] -> summarizer
+     * - researcher: no group (first sequential node)
+     * - analyst1, analyst2, analyst3: groupId 1 (first parallel group)
+     * - summarizer: no group (next sequential node)
+     *
+     * This allows frontend to render in order:
+     * Row 0: researcher
+     * Row 1: [analyst1, analyst2, analyst3] (grouped)
+     * Row 2: summarizer
+     */
+    private computeParallelCapability;
+    /**
+     * Get the parallel group ID for an agent, if any.
+     * Returns undefined if the agent is not part of a parallel group.
+     * Group IDs are incrementing numbers reflecting execution order.
+     */
+    getParallelGroupId(agentId: string): number | undefined;
+    /**
+     * Override to indicate this is a multi-agent graph.
+     * Enables agentId to be included in RunStep for frontend agent labeling.
+     */
+    protected isMultiAgentGraph(): boolean;
+    /**
+     * Override base class method to provide parallel group IDs for run steps.
+     */
+    protected getParallelGroupIdForAgent(agentId: string): number | undefined;
     /**
      * Create handoff tools for agents based on handoff edges only
      */

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

@@ -105,7 +105,7 @@ export declare const labelContentByAgent: (contentParts: MessageContentComplex[]
  * @param tools - Optional set of tool names that are allowed in the request.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
-export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number>, tools?: Set<string>) => {
+export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>) => {
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
 };

package/dist/types/tools/BrowserTools.d.ts

@@ -15,7 +15,29 @@ export declare const EBrowserTools: {
     readonly SCREENSHOT: "browser_screenshot";
     readonly GET_PAGE_STATE: "browser_get_page_state";
 };
-export type BrowserToolName = typeof EBrowserTools[keyof typeof EBrowserTools];
+export type BrowserToolName = (typeof EBrowserTools)[keyof typeof EBrowserTools];
+/**
+ * Callback function type for waiting on browser action results
+ * This allows the server (Ranger) to provide a callback that waits for the extension
+ * to POST results back to the server before returning to the LLM.
+ *
+ * @param action - The browser action (click, type, navigate, etc.)
+ * @param args - Arguments for the action
+ * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)
+ * @returns Promise that resolves with the actual browser result (page state, etc.)
+ */
+export type BrowserToolCallback = (action: string, args: Record<string, unknown>, toolCallId: string) => Promise<BrowserActionResult>;
+/**
+ * Result returned from browser action execution
+ */
+export interface BrowserActionResult {
+    success: boolean;
+    url?: string;
+    title?: string;
+    elementList?: string;
+    error?: string;
+    screenshot?: string;
+}
 /**
  * Check if browser capability is available based on request headers or context
  * The browser extension sets these headers when connected:
@@ -33,13 +55,31 @@ export interface BrowserToolResponse {
     requiresBrowserExecution: true;
     action: string;
     args: Record<string, unknown>;
+    toolCallId?: string;
 }
 /**
- * Create placeholder browser tools that signal to the extension to execute locally
- * The server creates these tools to give the LLM the schema, but actual execution
- * happens in the browser extension which intercepts tool calls
+ * Options for creating browser tools
+ */
+export interface CreateBrowserToolsOptions {
+    /**
+     * Optional callback that waits for browser action results.
+     * When provided, tools will await this callback to get actual results from the extension.
+     * When not provided, tools return markers immediately (for non-server contexts).
+     */
+    waitForResult?: BrowserToolCallback;
+}
+/**
+ * Create browser tools with optional callback for waiting on results
+ *
+ * When waitForResult callback is provided:
+ * 1. Tool returns marker that triggers extension
+ * 2. Tool then awaits callback to get actual results
+ * 3. Returns real page state to LLM
+ *
+ * When no callback:
+ * 1. Tool returns marker only (for non-server contexts)
  *
  * NOTE: These tools use TEXT-BASED element lists, NOT screenshots
  * Screenshots would be 100K+ tokens each - element lists are ~100 tokens
  */
-export declare function createBrowserTools(): DynamicStructuredTool[];
+export declare function createBrowserTools(options?: CreateBrowserToolsOptions): DynamicStructuredTool[];

package/dist/types/types/stream.d.ts

@@ -38,6 +38,17 @@ export type RunStep = {
     id: string;
     runId?: string;
     agentId?: string;
+    /**
+     * Group ID - incrementing number (1, 2, 3...) reflecting execution order.
+     * Agents with the same groupId run in parallel and should be rendered together.
+     * undefined means the agent runs sequentially (not part of any parallel group).
+     *
+     * Example for: researcher -> [analyst1, analyst2, analyst3] -> summarizer
+     * - researcher: undefined (sequential)
+     * - analyst1, analyst2, analyst3: 1 (first parallel group)
+     * - summarizer: undefined (sequential)
+     */
+    groupId?: number;
     index: number;
     stepIndex?: number;
     stepDetails: StepDetails;
@@ -251,6 +262,8 @@ export type MessageContentComplex = (ToolResultContent | ThinkingContentText | A
     type?: never;
 })) & {
     tool_call_ids?: string[];
+    agentId?: string;
+    groupId?: number;
 };
 export interface TMessage {
     role?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -63,6 +63,8 @@
     "multi-agent-test": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-test.ts",
     "test-tools-before-handoff": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/test-tools-before-handoff.ts",
     "multi-agent-parallel": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-parallel.ts",
+    "multi-agent-parallel-start": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-parallel-start.ts",
+    "single-agent-metadata-test": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/single-agent-metadata-test.ts",
     "multi-agent-chain": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-chain.ts",
     "multi-agent-sequence": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-sequence.ts",
     "multi-agent-conditional": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-conditional.ts",
@@ -102,7 +104,7 @@
   "dependencies": {
     "@langchain/anthropic": "^0.3.26",
     "@langchain/aws": "^0.1.15",
-    "@langchain/core": "^0.3.79",
+    "@langchain/core": "^0.3.80",
     "@langchain/deepseek": "^0.0.2",
     "@langchain/google-genai": "^0.2.18",
     "@langchain/google-vertexai": "^0.2.18",

package/src/graphs/Graph.ts

@@ -1246,6 +1246,26 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
     return workflow;
   }
 
+  /**
+   * Indicates if this is a multi-agent graph.
+   * Override in MultiAgentGraph to return true.
+   * Used to conditionally include agentId in RunStep for frontend rendering.
+   */
+  protected isMultiAgentGraph(): boolean {
+    return false;
+  }
+
+  /**
+   * Get the parallel group ID for an agent, if any.
+   * Override in MultiAgentGraph to provide actual group IDs.
+   * Group IDs are incrementing numbers (1, 2, 3...) reflecting execution order.
+   * @param _agentId - The agent ID to look up
+   * @returns undefined for StandardGraph (no parallel groups), or group number for MultiAgentGraph
+   */
+  protected getParallelGroupIdForAgent(_agentId: string): number | undefined {
+    return undefined;
+  }
+
   /* Dispatchers */
 
   /**
@@ -1286,13 +1306,21 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
     }
 
     /**
-     * Extract and store agentId from metadata
+     * Extract agentId and parallelGroupId from metadata
+     * Only set agentId for MultiAgentGraph (so frontend knows when to show agent labels)
      */
     if (metadata) {
       try {
         const agentContext = this.getAgentContext(metadata);
-        if (agentContext.agentId) {
+        if (this.isMultiAgentGraph() && agentContext.agentId) {
+          // Only include agentId for MultiAgentGraph - enables frontend to show agent labels
           runStep.agentId = agentContext.agentId;
+          // Set group ID if this agent is part of a parallel group
+          // Group IDs are incrementing numbers (1, 2, 3...) reflecting execution order
+          const groupId = this.getParallelGroupIdForAgent(agentContext.agentId);
+          if (groupId != null) {
+            runStep.groupId = groupId;
+          }
         }
       } catch (_e) {
         /** If we can't get agent context, that's okay - agentId remains undefined */

package/src/graphs/MultiAgentGraph.ts

@@ -40,6 +40,17 @@ export class MultiAgentGraph extends StandardGraph {
   private startingNodes: Set<string> = new Set();
   private directEdges: t.GraphEdge[] = [];
   private handoffEdges: t.GraphEdge[] = [];
+  /**
+   * Map of agentId to parallel group info.
+   * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
+   * Sequential agents (not in any parallel group) have undefined entry.
+   *
+   * Example for: researcher -> [analyst1, analyst2, analyst3] -> summarizer
+   * - researcher: undefined (sequential, order 0)
+   * - analyst1, analyst2, analyst3: { groupId: 1 } (parallel group, order 1)
+   * - summarizer: undefined (sequential, order 2)
+   */
+  private agentParallelGroups: Map<string, number> = new Map();
 
   constructor(input: t.MultiAgentGraphInput) {
     super(input);
@@ -99,6 +110,114 @@ export class MultiAgentGraph extends StandardGraph {
     if (this.startingNodes.size === 0 && this.agentContexts.size > 0) {
       this.startingNodes.add(this.agentContexts.keys().next().value!);
     }
+
+    // Determine if graph has parallel execution capability
+    this.computeParallelCapability();
+  }
+
+  /**
+   * Compute parallel groups by traversing the graph in execution order.
+   * Assigns incrementing group IDs that reflect the sequential order of execution.
+   *
+   * For: researcher -> [analyst1, analyst2, analyst3] -> summarizer
+   * - researcher: no group (first sequential node)
+   * - analyst1, analyst2, analyst3: groupId 1 (first parallel group)
+   * - summarizer: no group (next sequential node)
+   *
+   * This allows frontend to render in order:
+   * Row 0: researcher
+   * Row 1: [analyst1, analyst2, analyst3] (grouped)
+   * Row 2: summarizer
+   */
+  private computeParallelCapability(): void {
+    let groupCounter = 1; // Start at 1, 0 reserved for "no group"
+
+    // Check 1: Multiple starting nodes means parallel from the start (group 1)
+    if (this.startingNodes.size > 1) {
+      for (const agentId of this.startingNodes) {
+        this.agentParallelGroups.set(agentId, groupCounter);
+      }
+      groupCounter++;
+    }
+
+    // Check 2: Traverse direct edges in order to find fan-out patterns
+    // Build a simple execution order by following edges from starting nodes
+    const visited = new Set<string>();
+    const queue: string[] = [...this.startingNodes];
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (visited.has(current)) continue;
+      visited.add(current);
+
+      // Find direct edges from this node
+      for (const edge of this.directEdges) {
+        const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+        if (!sources.includes(current)) continue;
+
+        const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+
+        // Fan-out: multiple destinations = parallel group
+        if (destinations.length > 1) {
+          for (const dest of destinations) {
+            // Only set if not already in a group (first group wins)
+            if (!this.agentParallelGroups.has(dest)) {
+              this.agentParallelGroups.set(dest, groupCounter);
+            }
+            if (!visited.has(dest)) {
+              queue.push(dest);
+            }
+          }
+          groupCounter++;
+        } else {
+          // Single destination - add to queue for traversal
+          for (const dest of destinations) {
+            if (!visited.has(dest)) {
+              queue.push(dest);
+            }
+          }
+        }
+      }
+
+      // Also follow handoff edges for traversal (but they don't create parallel groups)
+      for (const edge of this.handoffEdges) {
+        const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+        if (!sources.includes(current)) continue;
+
+        const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+        for (const dest of destinations) {
+          if (!visited.has(dest)) {
+            queue.push(dest);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Get the parallel group ID for an agent, if any.
+   * Returns undefined if the agent is not part of a parallel group.
+   * Group IDs are incrementing numbers reflecting execution order.
+   */
+  getParallelGroupId(agentId: string): number | undefined {
+    return this.agentParallelGroups.get(agentId);
+  }
+
+  /**
+   * Override to indicate this is a multi-agent graph.
+   * Enables agentId to be included in RunStep for frontend agent labeling.
+   */
+  protected override isMultiAgentGraph(): boolean {
+    return true;
+  }
+
+  /**
+   * Override base class method to provide parallel group IDs for run steps.
+   */
+  protected override getParallelGroupIdForAgent(
+    agentId: string
+  ): number | undefined {
+    return this.agentParallelGroups.get(agentId);
   }
 
   /**

package/src/messages/format.ts

@@ -636,7 +636,7 @@ export const labelContentByAgent = (
  */
 export const formatAgentMessages = (
   payload: TPayload,
-  indexTokenCountMap?: Record<number, number>,
+  indexTokenCountMap?: Record<number, number | undefined>,
   tools?: Set<string>
 ): {
   messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
@@ -648,7 +648,7 @@ export const formatAgentMessages = (
   // If indexTokenCountMap is provided, create a new map to track the updated indices
   const updatedIndexTokenCountMap: Record<number, number> = {};
   // Keep track of the mapping from original payload indices to result indices
-  const indexMapping: Record<number, number[]> = {};
+  const indexMapping: Record<number, number[] | undefined> = {};
 
   // Process messages with tool conversion if tools set is provided
   for (let i = 0; i < payload.length; i++) {

package/src/scripts/multi-agent-chain.ts

@@ -143,18 +143,49 @@ async function testSequentialAgentChain() {
 
   // Track agent progression
   let currentAgent = '';
+  const startTime = Date.now();
+  let messageCount = 0;
 
-  // Create custom handlers
+  // Create custom handlers with extensive metadata logging
   const customHandlers = {
     [GraphEvents.TOOL_END]: new ToolEndHandler(),
-    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_END METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        console.log(`⏱️  COMPLETED at ${elapsed}ms`);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_START METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        console.log(`⏱️  STARTED at ${elapsed}ms`);
+      },
+    },
     [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
     [GraphEvents.ON_RUN_STEP]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
         const runStepData = data as any;
+        console.log('\n====== ON_RUN_STEP ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         if (runStepData?.name) {
           currentAgent = runStepData.name;
           console.log(`\n→ ${currentAgent} is processing...`);
@@ -165,9 +196,15 @@ async function testSequentialAgentChain() {
     [GraphEvents.ON_RUN_STEP_COMPLETED]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_COMPLETED,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
         const runStepData = data as any;
+        console.log('\n====== ON_RUN_STEP_COMPLETED ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         if (runStepData?.name) {
           console.log(`✓ ${runStepData.name} completed`);
         }
@@ -180,16 +217,32 @@ async function testSequentialAgentChain() {
     [GraphEvents.ON_RUN_STEP_DELTA]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_DELTA,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        console.log('\n====== ON_RUN_STEP_DELTA ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({ event, data: data as t.RunStepDeltaEvent });
       },
     },
     [GraphEvents.ON_MESSAGE_DELTA]: {
       handle: (
         event: GraphEvents.ON_MESSAGE_DELTA,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
+        messageCount++;
+        // Only log first few message deltas to avoid spam
+        if (messageCount <= 3) {
+          console.log('\n====== ON_MESSAGE_DELTA ======');
+          console.log('DATA:');
+          console.dir(data, { depth: null });
+          console.log('METADATA:');
+          console.dir(metadata, { depth: null });
+        }
         aggregateContent({ event, data: data as t.MessageDeltaEvent });
       },
     },