@illuma-ai/agents 1.0.81

package/src/tools/handlers.ts

@@ -0,0 +1,363 @@
+/* eslint-disable no-console */
+// src/tools/handlers.ts
+import { nanoid } from 'nanoid';
+import { ToolMessage } from '@langchain/core/messages';
+import type { AnthropicWebSearchResultBlockParam } from '@/llm/anthropic/types';
+import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
+import type { MultiAgentGraph, StandardGraph } from '@/graphs';
+import type { AgentContext } from '@/agents/AgentContext';
+import type * as t from '@/types';
+import {
+  ToolCallTypes,
+  GraphEvents,
+  StepTypes,
+  Providers,
+  Constants,
+} from '@/common';
+import {
+  coerceAnthropicSearchResults,
+  isAnthropicWebSearchResult,
+} from '@/tools/search/anthropic';
+import { formatResultsForLLM } from '@/tools/search/format';
+import { getMessageId } from '@/messages';
+
+export async function handleToolCallChunks({
+  graph,
+  stepKey,
+  toolCallChunks,
+  metadata,
+}: {
+  graph: StandardGraph | MultiAgentGraph;
+  stepKey: string;
+  toolCallChunks: ToolCallChunk[];
+  metadata?: Record<string, unknown>;
+}): Promise<void> {
+  let prevStepId: string;
+  let prevRunStep: t.RunStep | undefined;
+  try {
+    prevStepId = graph.getStepIdByKey(stepKey);
+    prevRunStep = graph.getRunStep(prevStepId);
+  } catch {
+    /** Edge Case: If no previous step exists, create a new message creation step */
+    const message_id = getMessageId(stepKey, graph, true) ?? '';
+    prevStepId = await graph.dispatchRunStep(
+      stepKey,
+      {
+        type: StepTypes.MESSAGE_CREATION,
+        message_creation: {
+          message_id,
+        },
+      },
+      metadata
+    );
+    prevRunStep = graph.getRunStep(prevStepId);
+  }
+
+  const _stepId = graph.getStepIdByKey(stepKey);
+
+  /** Edge Case: Tool Call Run Step or `tool_call_ids` never dispatched */
+  const tool_calls: ToolCall[] | undefined =
+    prevStepId && prevRunStep && prevRunStep.type === StepTypes.MESSAGE_CREATION
+      ? []
+      : undefined;
+
+  /** Edge Case: `id` and `name` fields cannot be empty strings */
+  for (const toolCallChunk of toolCallChunks) {
+    if (toolCallChunk.name === '') {
+      toolCallChunk.name = undefined;
+    }
+    if (toolCallChunk.id === '') {
+      toolCallChunk.id = undefined;
+    } else if (
+      tool_calls != null &&
+      toolCallChunk.id != null &&
+      toolCallChunk.name != null
+    ) {
+      tool_calls.push({
+        args: {},
+        id: toolCallChunk.id,
+        name: toolCallChunk.name,
+        type: ToolCallTypes.TOOL_CALL,
+      });
+    }
+  }
+
+  let stepId: string = _stepId;
+  const alreadyDispatched =
+    prevRunStep?.type === StepTypes.MESSAGE_CREATION &&
+    graph.messageStepHasToolCalls.has(prevStepId);
+
+  if (prevRunStep?.type === StepTypes.TOOL_CALLS) {
+    /**
+     * If previous step is already a tool_calls step, use that step ID
+     * This ensures tool call deltas are dispatched to the correct step
+     */
+    stepId = prevStepId;
+  } else if (
+    !alreadyDispatched &&
+    prevRunStep?.type === StepTypes.MESSAGE_CREATION
+  ) {
+    /**
+     * Create tool_calls step as soon as we receive the first tool call chunk
+     * This ensures deltas are always associated with the correct step
+     *
+     * NOTE: We do NOT dispatch an empty text block here because:
+     * - Empty text blocks cause providers (Anthropic, Bedrock) to reject messages
+     * - The tool_calls themselves are sufficient for the step
+     * - Empty content with tool_call_ids gets stored in conversation history
+     *   and causes "messages must have non-empty content" errors on replay
+     */
+    graph.messageStepHasToolCalls.set(prevStepId, true);
+    stepId = await graph.dispatchRunStep(
+      stepKey,
+      {
+        type: StepTypes.TOOL_CALLS,
+        tool_calls: tool_calls ?? [],
+      },
+      metadata
+    );
+  }
+  await graph.dispatchRunStepDelta(stepId, {
+    type: StepTypes.TOOL_CALLS,
+    tool_calls: toolCallChunks,
+  });
+}
+
+export const handleToolCalls = async (
+  toolCalls?: ToolCall[],
+  metadata?: Record<string, unknown>,
+  graph?: StandardGraph | MultiAgentGraph
+): Promise<void> => {
+  if (!graph || !metadata) {
+    console.warn(`Graph or metadata not found in ${event} event`);
+    return;
+  }
+
+  if (!toolCalls) {
+    return;
+  }
+
+  if (toolCalls.length === 0) {
+    return;
+  }
+
+  const stepKey = graph.getStepKey(metadata);
+
+  for (const tool_call of toolCalls) {
+    const toolCallId = tool_call.id ?? `toolu_${nanoid()}`;
+    tool_call.id = toolCallId;
+    if (!toolCallId || graph.toolCallStepIds.has(toolCallId)) {
+      continue;
+    }
+
+    let prevStepId = '';
+    let prevRunStep: t.RunStep | undefined;
+    try {
+      prevStepId = graph.getStepIdByKey(stepKey);
+      prevRunStep = graph.getRunStep(prevStepId);
+    } catch {
+      // no previous step
+    }
+
+    /**
+     * NOTE: We do NOT dispatch empty text blocks with tool_call_ids because:
+     * - Empty text blocks cause providers (Anthropic, Bedrock) to reject messages
+     * - They get stored in conversation history and cause errors on replay:
+     *   "messages must have non-empty content" (Anthropic)
+     *   "The content field in the Message object is empty" (Bedrock)
+     * - The tool_calls themselves are sufficient
+     */
+
+    /* If the previous step exists and is a message creation */
+    if (
+      prevStepId &&
+      prevRunStep &&
+      prevRunStep.type === StepTypes.MESSAGE_CREATION
+    ) {
+      graph.messageStepHasToolCalls.set(prevStepId, true);
+      /* If the previous step doesn't exist or is not a message creation */
+    } else if (
+      !prevRunStep ||
+      prevRunStep.type !== StepTypes.MESSAGE_CREATION
+    ) {
+      const messageId = getMessageId(stepKey, graph, true) ?? '';
+      const stepId = await graph.dispatchRunStep(
+        stepKey,
+        {
+          type: StepTypes.MESSAGE_CREATION,
+          message_creation: {
+            message_id: messageId,
+          },
+        },
+        metadata
+      );
+      graph.messageStepHasToolCalls.set(stepId, true);
+    }
+
+    await graph.dispatchRunStep(
+      stepKey,
+      {
+        type: StepTypes.TOOL_CALLS,
+        tool_calls: [tool_call],
+      },
+      metadata
+    );
+  }
+};
+
+export const toolResultTypes = new Set([
+  // 'tool_use',
+  // 'server_tool_use',
+  // 'input_json_delta',
+  'tool_result',
+  'web_search_result',
+  'web_search_tool_result',
+]);
+
+/**
+ * Handles the result of a server tool call; in other words, a provider's built-in tool.
+ * As of 2025-07-06, only Anthropic handles server tool calls with this pattern.
+ */
+export async function handleServerToolResult({
+  graph,
+  content,
+  metadata,
+  agentContext,
+}: {
+  graph: StandardGraph | MultiAgentGraph;
+  content?: string | t.MessageContentComplex[];
+  metadata?: Record<string, unknown>;
+  agentContext?: AgentContext;
+}): Promise<boolean> {
+  let skipHandling = false;
+  if (agentContext?.provider !== Providers.ANTHROPIC) {
+    return skipHandling;
+  }
+  if (
+    typeof content === 'string' ||
+    content == null ||
+    content.length === 0 ||
+    (content.length === 1 &&
+      (content[0] as t.ToolResultContent).tool_use_id == null)
+  ) {
+    return skipHandling;
+  }
+
+  for (const contentPart of content) {
+    const toolUseId = (contentPart as t.ToolResultContent).tool_use_id;
+    if (toolUseId == null || toolUseId === '') {
+      continue;
+    }
+    const stepId = graph.toolCallStepIds.get(toolUseId);
+    if (stepId == null || stepId === '') {
+      console.warn(
+        `Tool use ID ${toolUseId} not found in graph, cannot dispatch tool result.`
+      );
+      continue;
+    }
+    const runStep = graph.getRunStep(stepId);
+    if (!runStep) {
+      console.warn(
+        `Run step for ${stepId} does not exist, cannot dispatch tool result.`
+      );
+      continue;
+    } else if (runStep.type !== StepTypes.TOOL_CALLS) {
+      console.warn(
+        `Run step for ${stepId} is not a tool call step, cannot dispatch tool result.`
+      );
+      continue;
+    }
+
+    const toolCall =
+      runStep.stepDetails.type === StepTypes.TOOL_CALLS
+        ? (runStep.stepDetails.tool_calls?.find(
+          (toolCall) => toolCall.id === toolUseId
+        ) as ToolCall)
+        : undefined;
+
+    if (!toolCall) {
+      continue;
+    }
+
+    if (
+      contentPart.type === 'web_search_result' ||
+      contentPart.type === 'web_search_tool_result'
+    ) {
+      await handleAnthropicSearchResults({
+        contentPart: contentPart as t.ToolResultContent,
+        toolCall,
+        metadata,
+        graph,
+      });
+    }
+
+    if (!skipHandling) {
+      skipHandling = true;
+    }
+  }
+
+  return skipHandling;
+}
+
+async function handleAnthropicSearchResults({
+  contentPart,
+  toolCall,
+  metadata,
+  graph,
+}: {
+  contentPart: t.ToolResultContent;
+  toolCall: Partial<ToolCall>;
+  metadata?: Record<string, unknown>;
+  graph: StandardGraph | MultiAgentGraph;
+}): Promise<void> {
+  if (!Array.isArray(contentPart.content)) {
+    console.warn(
+      `Expected content to be an array, got ${typeof contentPart.content}`
+    );
+    return;
+  }
+
+  if (!isAnthropicWebSearchResult(contentPart.content[0])) {
+    console.warn(
+      `Expected content to be an Anthropic web search result, got ${JSON.stringify(
+        contentPart.content
+      )}`
+    );
+    return;
+  }
+
+  const turn = graph.invokedToolIds?.size ?? 0;
+  const searchResultData = coerceAnthropicSearchResults({
+    turn,
+    results: contentPart.content as AnthropicWebSearchResultBlockParam[],
+  });
+
+  const name = toolCall.name;
+  const input = toolCall.args ?? {};
+  const artifact = {
+    [Constants.WEB_SEARCH]: searchResultData,
+  };
+  const { output: formattedOutput } = formatResultsForLLM(
+    turn,
+    searchResultData
+  );
+  const output = new ToolMessage({
+    name,
+    artifact,
+    content: formattedOutput,
+    tool_call_id: toolCall.id!,
+  });
+  const toolEndData: t.ToolEndData = {
+    input,
+    output,
+  };
+  await graph.handlerRegistry
+    ?.getHandler(GraphEvents.TOOL_END)
+    ?.handle(GraphEvents.TOOL_END, toolEndData, metadata, graph);
+
+  if (graph.invokedToolIds == null) {
+    graph.invokedToolIds = new Set<string>();
+  }
+
+  graph.invokedToolIds.add(toolCall.id!);
+}

package/src/tools/schema.ts

@@ -0,0 +1,37 @@
+import { tool, type StructuredToolInterface } from '@langchain/core/tools';
+import type { LCTool } from '@/types';
+
+/**
+ * Creates a schema-only tool for LLM binding in event-driven mode.
+ * These tools have valid schemas for the LLM to understand but should
+ * never be invoked directly - ToolNode handles execution via events.
+ */
+export function createSchemaOnlyTool(
+  definition: LCTool
+): StructuredToolInterface {
+  const { name, description, parameters, responseFormat } = definition;
+
+  return tool(
+    async () => {
+      throw new Error(
+        `Tool "${name}" should not be invoked directly in event-driven mode. ` +
+          'ToolNode should dispatch ON_TOOL_EXECUTE events instead.'
+      );
+    },
+    {
+      name,
+      description: description ?? '',
+      schema: parameters ?? { type: 'object', properties: {} },
+      responseFormat: responseFormat ?? 'content_and_artifact',
+    }
+  );
+}
+
+/**
+ * Creates schema-only tools for all definitions in an array.
+ */
+export function createSchemaOnlyTools(
+  definitions: LCTool[]
+): StructuredToolInterface[] {
+  return definitions.map((def) => createSchemaOnlyTool(def));
+}

package/src/tools/search/anthropic.ts

@@ -0,0 +1,51 @@
+import type {
+  AnthropicTextBlockParam,
+  AnthropicWebSearchResultBlockParam,
+} from '@/llm/anthropic/types';
+import type { SearchResultData, ProcessedOrganic } from './types';
+import { getAttribution } from './utils';
+
+/**
+ * Coerces Anthropic web search results to the SearchResultData format
+ * @param results - Array of Anthropic web search results
+ * @param turn - The turn number to associate with these results
+ * @returns SearchResultData with minimal ProcessedOrganic items
+ */
+export function coerceAnthropicSearchResults({
+  results,
+  turn = 0,
+}: {
+  results: (AnthropicTextBlockParam | AnthropicWebSearchResultBlockParam)[];
+  turn?: number;
+}): SearchResultData {
+  const organic: ProcessedOrganic[] = results
+    .filter((result) => result.type === 'web_search_result')
+    .map((result, index) => ({
+      link: result.url,
+      position: index + 1,
+      title: result.title,
+      date: result.page_age ?? undefined,
+      attribution: getAttribution(result.url),
+    }));
+
+  return {
+    turn,
+    organic,
+  };
+}
+
+/**
+ * Helper function to check if an object is an Anthropic web search result
+ */
+export function isAnthropicWebSearchResult(
+  obj: unknown
+): obj is AnthropicWebSearchResultBlockParam {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    'type' in obj &&
+    obj.type === 'web_search_result' &&
+    'url' in obj &&
+    typeof (obj as Record<string, unknown>).url === 'string'
+  );
+}

package/src/tools/search/content.test.ts

@@ -0,0 +1,173 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable no-console */
+// content.test.ts
+import * as fs from 'fs';
+import { processContent } from './content';
+
+describe('Link Processor', () => {
+  afterAll(() => {
+    if (fs.existsSync('./temp.html')) {
+      fs.unlinkSync('./temp.html');
+    }
+    if (fs.existsSync('./temp.md')) {
+      fs.unlinkSync('./temp.md');
+    }
+  });
+  // Basic functionality tests
+  test('should replace basic links with references', () => {
+    const html = `
+      <p>Test with <a href="https://example.com/link" title="Example">a link</a></p>
+      <p>And an <img src="https://example.com/img.jpg" alt="image"></p>
+      <p>Plus a <video src="https://example.com/video.mp4"></video></p>
+    `;
+
+    const markdown = `
+      Test with [a link](https://example.com/link "Example")
+      And an ![image](https://example.com/img.jpg)
+      Plus a [video](https://example.com/video.mp4)
+    `;
+
+    const result = processContent(html, markdown);
+
+    expect(result.links.length).toBe(1);
+    expect(result.images.length).toBe(1);
+    expect(result.videos.length).toBe(1);
+    expect(result.markdown).toContain('link#1');
+    expect(result.markdown).toContain('image#1');
+    expect(result.markdown).toContain('video#1');
+  });
+
+  // Edge case tests
+  test('should handle links with parentheses and special characters', () => {
+    const html = `
+      <a href="https://example.com/page(1).html" title="Parens">Link with parens</a>
+      <a href="https://example.com/path?query=test&param=value">Link with query</a>
+    `;
+
+    const markdown = `
+      [Link with parens](https://example.com/page(1).html "Parens")
+      [Link with query](https://example.com/path?query=test&param=value)
+    `;
+
+    const result = processContent(html, markdown);
+
+    expect(result.links.length).toBe(2);
+    expect(result.markdown).toContain('link#1');
+    expect(result.markdown).toContain('link#2');
+  });
+
+  // Performance test with large files
+  test('should process large files efficiently', () => {
+    const html = fs.readFileSync('src/tools/search/test.html', 'utf-8');
+    const markdown = fs.readFileSync('src/tools/search/test.md', 'utf-8');
+
+    // const largeHtml = generateLargeHtml(1000); // 1000 links
+    // fs.writeFileSync('./temp.html', largeHtml);
+
+    // const largeMd = generateLargeMarkdown(1000); // 1000 links
+    // fs.writeFileSync('./temp.md', largeMd);
+
+    // const html = fs.readFileSync('./temp.html', 'utf-8');
+    // const markdown = fs.readFileSync('./temp.md', 'utf-8');
+
+    // Measure time taken to process
+    const startTime = process.hrtime();
+    const result = processContent(html, markdown);
+    const elapsed = process.hrtime(startTime);
+    const timeInMs = elapsed[0] * 1000 + elapsed[1] / 1000000;
+
+    console.log(
+      `Processed ${result.links.length} links, ${result.images.length} images, and ${result.videos.length} videos in ${timeInMs.toFixed(2)}ms`
+    );
+
+    // Basic validations for large file processing
+    expect(result.links.length).toBeGreaterThan(0);
+    expect(result.markdown).toContain('link#');
+
+    // Check if all links were replaced (sample check)
+    expect(result.markdown).not.toContain('https://example.com/link');
+  });
+
+  // Memory usage test
+  test('should have reasonable memory usage', () => {
+    const html = fs.readFileSync('src/tools/search/test.html', 'utf-8');
+    const markdown = fs.readFileSync('src/tools/search/test.md', 'utf-8');
+
+    const beforeMem = process.memoryUsage();
+    processContent(html, markdown);
+    const afterMem = process.memoryUsage();
+
+    const heapUsed = (afterMem.heapUsed - beforeMem.heapUsed) / 1024 / 1024; // MB
+
+    console.log(`Memory used: ${heapUsed.toFixed(2)} MB`);
+
+    // This is a loose check - actual thresholds depend on your environment
+    expect(heapUsed).toBeLessThan(100); // Should use less than 100MB additional heap
+  });
+
+  // Real-world file test (if available)
+  test('should process real-world Wikipedia content', () => {
+    // Try to find real-world test files if they exist
+    const wikiHtml = 'src/tools/search/test.html';
+    const wikiMd = 'src/tools/search/test.md';
+
+    if (fs.existsSync(wikiHtml) && fs.existsSync(wikiMd)) {
+      const html = fs.readFileSync(wikiHtml, 'utf-8');
+      const markdown = fs.readFileSync(wikiMd, 'utf-8');
+
+      const result = processContent(html, markdown);
+
+      console.log(
+        `Processed ${result.links.length} Wikipedia links, ${result.images.length} images, and ${result.videos.length} videos`
+      );
+
+      expect(result.links.length).toBeGreaterThan(10); // Wikipedia articles typically have many links
+      expect(result.markdown).not.toMatch(/\]\(https?:\/\/[^\s")]+\)/); // No regular URLs should remain
+    } else {
+      console.log('Wikipedia test files not found, skipping this test');
+    }
+  });
+});
+
+// Helper function to generate large HTML test data
+function generateLargeHtml(linkCount: number): string {
+  let html = '<html><body>';
+
+  for (let i = 1; i <= linkCount; i++) {
+    html += `<p>Paragraph ${i} with <a href="https://example.com/link${i}" title="Link ${i}">link ${i}</a>`;
+
+    if (i % 10 === 0) {
+      html += ` and <img src="https://example.com/image${i / 10}.jpg" alt="Image ${i / 10}">`;
+    }
+
+    if (i % 50 === 0) {
+      html += ` and <video src="https://example.com/video${i / 50}.mp4" title="Video ${i / 50}"></video>`;
+    }
+
+    html += '</p>';
+  }
+
+  html += '</body></html>';
+  return html;
+}
+
+/** Helper function to generate large Markdown test data  */
+function generateLargeMarkdown(linkCount: number): string {
+  let markdown = '# Test Document\n\n';
+
+  for (let i = 1; i <= linkCount; i++) {
+    markdown += `Paragraph ${i} with [link ${i}](https://example.com/link${i} "Link ${i}")`;
+
+    if (i % 10 === 0) {
+      markdown += ` and ![Image ${i / 10}](https://example.com/image${i / 10}.jpg)`;
+    }
+
+    if (i % 50 === 0) {
+      markdown += ` and [Video ${i / 50}](https://example.com/video${i / 50}.mp4 "Video ${i / 50}")`;
+    }
+
+    markdown += '\n\n';
+  }
+
+  return markdown;
+}