@illuma-ai/agents 1.0.81

package/src/messages/shiftIndexTokenCountMap.test.ts

@@ -0,0 +1,81 @@
+import { shiftIndexTokenCountMap } from './format';
+
+describe('shiftIndexTokenCountMap', () => {
+  it('should add a system message token count at index 0 and shift all other indices', () => {
+    const originalMap: Record<number, number> = {
+      0: 10,
+      1: 20,
+      2: 30
+    };
+
+    const systemMessageTokenCount = 15;
+
+    const result = shiftIndexTokenCountMap(originalMap, systemMessageTokenCount);
+
+    // Check that the system message token count is at index 0
+    expect(result[0]).toBe(15);
+
+    // Check that all other indices are shifted by 1
+    expect(result[1]).toBe(10);
+    expect(result[2]).toBe(20);
+    expect(result[3]).toBe(30);
+
+    // Check that the original map is not modified
+    expect(originalMap[0]).toBe(10);
+    expect(originalMap[1]).toBe(20);
+    expect(originalMap[2]).toBe(30);
+  });
+
+  it('should handle an empty map', () => {
+    const emptyMap: Record<number, number> = {};
+    const systemMessageTokenCount = 15;
+
+    const result = shiftIndexTokenCountMap(emptyMap, systemMessageTokenCount);
+
+    // Check that only the system message token count is in the result
+    expect(Object.keys(result).length).toBe(1);
+    expect(result[0]).toBe(15);
+  });
+
+  it('should handle non-sequential indices', () => {
+    const nonSequentialMap: Record<number, number> = {
+      0: 10,
+      2: 20,
+      5: 30
+    };
+
+    const systemMessageTokenCount = 15;
+
+    const result = shiftIndexTokenCountMap(nonSequentialMap, systemMessageTokenCount);
+
+    // Check that the system message token count is at index 0
+    expect(result[0]).toBe(15);
+
+    // Check that all other indices are shifted by 1
+    expect(result[1]).toBe(10);
+    expect(result[3]).toBe(20);
+    expect(result[6]).toBe(30);
+  });
+
+  it('should handle string keys', () => {
+    // TypeScript will convert string keys to numbers when accessing the object
+    const mapWithStringKeys: Record<string, number> = {
+      '0': 10,
+      '1': 20,
+      '2': 30
+    };
+
+    const systemMessageTokenCount = 15;
+
+    // Cast to Record<number, number> to match the function signature
+    const result = shiftIndexTokenCountMap(mapWithStringKeys as unknown as Record<number, number>, systemMessageTokenCount);
+
+    // Check that the system message token count is at index 0
+    expect(result[0]).toBe(15);
+
+    // Check that all other indices are shifted by 1
+    expect(result[1]).toBe(10);
+    expect(result[2]).toBe(20);
+    expect(result[3]).toBe(30);
+  });
+});

package/src/messages/tools.ts

@@ -0,0 +1,108 @@
+// src/messages/toolDiscovery.ts
+import { AIMessageChunk, ToolMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { Constants, MessageTypes } from '@/common';
+import { findLastIndex } from './core';
+
+type ToolSearchArtifact = {
+  tool_references?: Array<{ tool_name: string }>;
+};
+
+/**
+ * Extracts discovered tool names from tool search results in the current turn.
+ * Only processes tool search messages after the latest AI message with tool calls.
+ *
+ * Similar pattern to formatArtifactPayload - finds relevant messages efficiently
+ * by identifying the latest AI parent and only processing subsequent tool messages.
+ *
+ * @param messages - All messages in the conversation
+ * @returns Array of discovered tool names (empty if no new discoveries)
+ */
+export function extractToolDiscoveries(messages: BaseMessage[]): string[] {
+  if (messages.length === 0) return [];
+  const lastMessage = messages[messages.length - 1];
+  // Use getType() instead of instanceof to avoid module mismatch issues
+  if (lastMessage.getType() !== MessageTypes.TOOL) return [];
+  const lastToolMessage = lastMessage as ToolMessage;
+
+  // Find the latest AIMessage with tool_calls that this tool message belongs to
+  const latestAIParentIndex = findLastIndex(
+    messages,
+    (msg) =>
+      (msg instanceof AIMessageChunk &&
+        (msg.tool_calls?.length ?? 0) > 0 &&
+        msg.tool_calls?.some((tc) => tc.id === lastToolMessage.tool_call_id)) ??
+      false
+  );
+
+  if (latestAIParentIndex === -1) return [];
+
+  // Collect tool_call_ids from the AI message
+  const aiMessage = messages[latestAIParentIndex] as AIMessageChunk;
+  const toolCallIds = new Set(aiMessage.tool_calls?.map((tc) => tc.id) ?? []);
+
+  // Only process tool search results after the AI message that belong to this turn
+  const discoveredNames: string[] = [];
+  for (let i = latestAIParentIndex + 1; i < messages.length; i++) {
+    const msg = messages[i];
+    // Use getType() instead of instanceof to avoid module mismatch issues
+    if (msg.getType() !== MessageTypes.TOOL) continue;
+    const toolMsg = msg as ToolMessage;
+    if (toolMsg.name !== Constants.TOOL_SEARCH) continue;
+    if (!toolCallIds.has(toolMsg.tool_call_id)) continue;
+
+    // This is a tool search result from the current turn
+    if (typeof toolMsg.artifact === 'object' && toolMsg.artifact != null) {
+      const artifact = toolMsg.artifact as ToolSearchArtifact;
+      if (artifact.tool_references && artifact.tool_references.length > 0) {
+        for (const ref of artifact.tool_references) {
+          discoveredNames.push(ref.tool_name);
+        }
+      }
+    }
+  }
+
+  return discoveredNames;
+}
+
+/**
+ * Checks if the current turn has any tool search results.
+ * Quick check to avoid full extraction when not needed.
+ */
+export function hasToolSearchInCurrentTurn(messages: BaseMessage[]): boolean {
+  if (messages.length === 0) return false;
+  const lastMessage = messages[messages.length - 1];
+  // Use getType() instead of instanceof to avoid module mismatch issues
+  if (lastMessage.getType() !== MessageTypes.TOOL) return false;
+  const lastToolMessage = lastMessage as ToolMessage;
+
+  // Find the latest AIMessage with tool_calls
+  const latestAIParentIndex = findLastIndex(
+    messages,
+    (msg) =>
+      (msg instanceof AIMessageChunk &&
+        (msg.tool_calls?.length ?? 0) > 0 &&
+        msg.tool_calls?.some((tc) => tc.id === lastToolMessage.tool_call_id)) ??
+      false
+  );
+
+  if (latestAIParentIndex === -1) return false;
+
+  const aiMessage = messages[latestAIParentIndex] as AIMessageChunk;
+  const toolCallIds = new Set(aiMessage.tool_calls?.map((tc) => tc.id) ?? []);
+
+  // Check if any tool search results exist after the AI message
+  // Use getType() instead of instanceof to avoid module mismatch issues
+  for (let i = latestAIParentIndex + 1; i < messages.length; i++) {
+    const msg = messages[i];
+    if (
+      msg.getType() === MessageTypes.TOOL &&
+      (msg as ToolMessage).name === Constants.TOOL_SEARCH &&
+      toolCallIds.has((msg as ToolMessage).tool_call_id)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/mockStream.ts

@@ -0,0 +1,99 @@
+
+// import { nanoid } from 'nanoid';
+import type OpenAITypes from 'openai';
+import type * as t from '@/types';
+// import { SplitStreamHandler } from '@/splitStream';
+// import { GraphEvents } from '@/common';
+import { sleep } from '@/utils';
+
+const choiceProps: OpenAITypes.Chat.Completions.ChatCompletionChunk.Choice = { finish_reason: null, index: 0, delta: {} };
+const reasoningSplitRegex = /(?<=\s+)|(?=\s+)/;
+const contentSplitRegex = /(?<=<\/?think>)|(?=<\/?think>)|(?<=\s+)|(?=\s+)/;
+export const createMockStream = (options: {
+  text?: string;
+  reasoningText?: string;
+  streamRate?: number;
+  reasoningKey?: 'reasoning' | 'reasoning_content';
+} = {}) => {
+  const {
+    text,
+    reasoningText,
+    streamRate = 25,
+    reasoningKey = 'reasoning_content'
+  } = options;
+
+  return async function* mockOpenAIStream(): AsyncGenerator<t.CustomChunk> {
+    const content = text ?? `Here's a sample message that includes code:
+\`\`\`python
+def hello_world():
+    print("Hello, World!")
+    # This is a long code block
+    # That shouldn't be split
+    return True
+\`\`\`
+Now we're back to regular text. This is a very long sentence that should probably be split at some point because it exceeds our threshold and contains multiple natural breaking points. Let's see how it handles this case properly.
+
+Here's another code block:
+\`\`\`javascript
+console.log("Another test");
+// More code here
+\`\`\`
+And finally some more regular text to test our splitting logic.`;
+
+    if (reasoningText != null && reasoningText) {
+      // Split reasoning text into "token-like" chunks
+      const reasoningTokens = reasoningText.split(reasoningSplitRegex);
+      for (const token of reasoningTokens) {
+        yield {
+          choices: [{
+            ...choiceProps,
+            delta: {
+              [reasoningKey]: token,
+            },
+          }]
+        };
+        await sleep(streamRate);
+      }
+    }
+
+    // Split main content into "token-like" chunks
+    const tokens = content.split(contentSplitRegex);
+    for (const token of tokens) {
+      yield {
+        choices: [{
+          ...choiceProps,
+          delta: {
+            content: token
+          }
+        }]
+      };
+      await sleep(streamRate);
+    }
+  };
+};
+
+/**
+(async function testStream(): Promise<void> {
+  const runId = nanoid();
+
+  const streamHandler = new SplitStreamHandler({
+    runId,
+    handlers: {
+      [GraphEvents.ON_RUN_STEP]: (data): void => {
+        console.dir(data, { depth: null });
+      },
+      [GraphEvents.ON_MESSAGE_DELTA]: (): void => {
+        // console.dir(data, { depth: null });
+      },
+    },
+  });
+  const stream = createMockStream({
+    reasoningText: 'This is a test reasoning text.',
+    streamRate: 5,
+  })();
+
+  for await (const chunk of stream) {
+    streamHandler.handle(chunk);
+  }
+})();
+ */

package/src/prompts/collab.ts

@@ -0,0 +1,6 @@
+// src/prompts/collab.ts
+export const supervisorPrompt = `You are a supervisor tasked with managing a conversation between the
+following workers: {members}. Given the following user request,
+respond with the worker to act next. Each worker will perform a
+task and respond with their results and status. Multiple workers can work at once, and they can use multiple tools at once. Each worker can run their tools multiple times per task. When finished,
+respond with FINISH.`;

package/src/prompts/index.ts

@@ -0,0 +1,2 @@
+export * from './collab';
+export * from './taskmanager';

package/src/prompts/taskmanager.ts

@@ -0,0 +1,61 @@
+export const taskManagerPrompt = `You are a Task Manager responsible for efficiently coordinating a team of specialized workers: {members}. Your PRIMARY and SOLE OBJECTIVE is to fulfill the user's specific request as quickly and effectively as possible.
+
+CRITICAL GUIDELINES:
+1. The user's request is your CHIEF CONCERN. Every action must directly contribute to fulfilling this request.
+2. Aim to complete the entire task in NO MORE THAN 2-3 TURNS, unless explicitly instructed otherwise.
+3. Eliminate all superfluous activity. Each task must be essential to achieving the user's goal.
+4. Assign no more than 5 tasks per turn, and only if absolutely necessary.
+5. Be concise and direct in your task assignments.
+6. End the process IMMEDIATELY once the user's request is fulfilled by setting 'end' to true and assigning no new tasks.
+
+Your responsibilities:
+1. Analyze the user's request and break it down into the minimum necessary subtasks.
+2. Assign these essential tasks to the most appropriate team members based on their skills and tools.
+3. Prioritize tasks to ensure the most efficient path to completion.
+4. Continuously evaluate if the user's request has been fully addressed.
+5. End the process IMMEDIATELY once the user's request is fulfilled.
+
+Task Assignment Guidelines:
+- Assign only the most crucial tasks required to meet the user's needs.
+- Multiple tasks can be assigned to the same team member if it improves efficiency.
+- Always specify the tool to use if applicable.
+- Consider task dependencies to minimize the number of turns.
+
+After each round:
+- Critically assess if the user's request has been fully addressed.
+- If more work is genuinely needed, assign only the most essential remaining tasks.
+- If the user's request has been fulfilled or can be fulfilled with the results at hand, set 'end' to true and assign no new tasks.
+
+REMEMBER: Your success is measured by how quickly and effectively you fulfill the user's request, not by the number of tasks assigned or turns taken. Excessive deliberation or unnecessary tasks are counterproductive. Focus solely on the user's needs and conclude the process as soon as those needs are met.`;
+
+export const assignTasksFunctionDescription = 'Assign the minimum necessary tasks to team members to fulfill the user\'s request as quickly as possible. Assign up to 5 tasks maximum per turn, only if absolutely necessary. Each task must specify the team member, a concise description, and the tool to use if applicable.';
+
+export const assignTasksFunctionParameters = {
+  type: 'object',
+  properties: {
+    tasks: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          member: { type: 'string', description: 'Name of the team member assigned to the task' },
+          description: { type: 'string', description: 'Concise description of the essential task to be performed' },
+          tool: { type: 'string', description: 'Specific tool to be used for the task, if applicable' },
+        },
+        required: ['member', 'description'],
+      },
+      description: 'List of essential tasks to be assigned, maximum 5 tasks per turn.',
+    },
+  },
+  required: ['tasks'],
+};
+
+export const endProcessFunctionDescription = 'End the process when the user\'s request has been fulfilled.';
+
+export const endProcessFunctionParameters = {
+  type: 'object',
+  properties: {
+    reason: { type: 'string', description: 'Brief explanation of why the process is ending' },
+  },
+  required: ['reason'],
+};