@illuma-ai/agents 1.0.81

package/src/types/tools.ts

@@ -0,0 +1,355 @@
+// src/types/tools.ts
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import type { RunnableToolLike } from '@langchain/core/runnables';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { ToolErrorData } from './stream';
+import { EnvVar } from '@/common';
+
+/** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
+export type CustomToolCall = {
+  name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  args: string | Record<string, any>;
+  id?: string;
+  type?: 'tool_call';
+  output?: string;
+};
+
+export type GenericTool = (StructuredToolInterface | RunnableToolLike) & {
+  mcp?: boolean;
+};
+
+export type ToolMap = Map<string, GenericTool>;
+export type ToolRefs = {
+  tools: GenericTool[];
+  toolMap?: ToolMap;
+};
+
+export type ToolRefGenerator = (tool_calls: ToolCall[]) => ToolRefs;
+
+export type ToolNodeOptions = {
+  name?: string;
+  tags?: string[];
+  handleToolErrors?: boolean;
+  loadRuntimeTools?: ToolRefGenerator;
+  toolCallStepIds?: Map<string, string>;
+  errorHandler?: (
+    data: ToolErrorData,
+    metadata?: Record<string, unknown>
+  ) => Promise<void>;
+  /** Tool registry for lazy computation of programmatic tools and tool search */
+  toolRegistry?: LCToolRegistry;
+  /** Reference to Graph's sessions map for automatic session injection */
+  sessions?: ToolSessionMap;
+  /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+  eventDrivenMode?: boolean;
+  /** Tool definitions for event-driven mode (used for context, not invocation) */
+  toolDefinitions?: Map<string, LCTool>;
+  /** Agent ID for event-driven mode (used to identify which agent's context to use) */
+  agentId?: string;
+};
+
+export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
+
+export type ToolEndEvent = {
+  /** The Step Id of the Tool Call */
+  id: string;
+  /** The Completed Tool Call */
+  tool_call: ToolCall;
+  /** The content index of the tool call */
+  index: number;
+};
+
+export type CodeEnvFile = {
+  id: string;
+  name: string;
+  session_id: string;
+};
+
+export type CodeExecutionToolParams =
+  | undefined
+  | {
+      session_id?: string;
+      user_id?: string;
+      apiKey?: string;
+      files?: CodeEnvFile[];
+      [EnvVar.CODE_API_KEY]?: string;
+    };
+
+export type FileRef = {
+  id: string;
+  name: string;
+  path?: string;
+  /** Session ID this file belongs to (for multi-session file tracking) */
+  session_id?: string;
+};
+
+export type FileRefs = FileRef[];
+
+export type ExecuteResult = {
+  session_id: string;
+  stdout: string;
+  stderr: string;
+  files?: FileRefs;
+};
+
+/** JSON Schema type definition for tool parameters */
+export type JsonSchemaType = {
+  type:
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'float'
+    | 'boolean'
+    | 'array'
+    | 'object';
+  enum?: string[];
+  items?: JsonSchemaType;
+  properties?: Record<string, JsonSchemaType>;
+  required?: string[];
+  description?: string;
+  additionalProperties?: boolean | JsonSchemaType;
+};
+
+/**
+ * Specifies which contexts can invoke a tool (inspired by Anthropic's allowed_callers)
+ * - 'direct': Only callable directly by the LLM (default if omitted)
+ * - 'code_execution': Only callable from within programmatic code execution
+ */
+export type AllowedCaller = 'direct' | 'code_execution';
+
+/** Tool definition with optional deferred loading and caller restrictions */
+export type LCTool = {
+  name: string;
+  description?: string;
+  parameters?: JsonSchemaType;
+  /** When true, tool is not loaded into context initially (for tool search) */
+  defer_loading?: boolean;
+  /**
+   * Which contexts can invoke this tool.
+   * Default: ['direct'] (only callable directly by LLM)
+   * Options: 'direct', 'code_execution'
+   */
+  allowed_callers?: AllowedCaller[];
+  /** Response format for the tool output */
+  responseFormat?: 'content' | 'content_and_artifact';
+  /** Server name for MCP tools */
+  serverName?: string;
+  /** Tool type classification */
+  toolType?: 'builtin' | 'mcp' | 'action';
+};
+
+/** Single tool call within a batch request for event-driven execution */
+export type ToolCallRequest = {
+  /** Tool call ID from the LLM */
+  id: string;
+  /** Tool name */
+  name: string;
+  /** Tool arguments */
+  args: Record<string, unknown>;
+  /** Step ID for tracking */
+  stepId?: string;
+  /** Usage turn count for this tool */
+  turn?: number;
+};
+
+/** Batch request containing ALL tool calls for a graph step */
+export type ToolExecuteBatchRequest = {
+  /** All tool calls from the AIMessage */
+  toolCalls: ToolCallRequest[];
+  /** User ID for context */
+  userId?: string;
+  /** Agent ID for context */
+  agentId?: string;
+  /** Runtime configurable from RunnableConfig (includes user, userMCPAuthMap, etc.) */
+  configurable?: Record<string, unknown>;
+  /** Runtime metadata from RunnableConfig (includes thread_id, run_id, provider, etc.) */
+  metadata?: Record<string, unknown>;
+  /** Promise resolver - handler calls this with ALL results */
+  resolve: (results: ToolExecuteResult[]) => void;
+  /** Promise rejector - handler calls this on fatal error */
+  reject: (error: Error) => void;
+};
+
+/** Result for a single tool call in event-driven execution */
+export type ToolExecuteResult = {
+  /** Matches ToolCallRequest.id */
+  toolCallId: string;
+  /** Tool output content */
+  content: string | unknown[];
+  /** Optional artifact (for content_and_artifact format) */
+  artifact?: unknown;
+  /** Execution status */
+  status: 'success' | 'error';
+  /** Error message if status is 'error' */
+  errorMessage?: string;
+};
+
+/** Map of tool names to tool definitions */
+export type LCToolRegistry = Map<string, LCTool>;
+
+export type ProgrammaticCache = { toolMap: ToolMap; toolDefs: LCTool[] };
+
+/** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
+export type ToolSearchMode = 'code_interpreter' | 'local';
+
+/** Parameters for creating a Tool Search tool */
+export type ToolSearchParams = {
+  apiKey?: string;
+  toolRegistry?: LCToolRegistry;
+  onlyDeferred?: boolean;
+  baseUrl?: string;
+  /** Search mode: 'code_interpreter' (default) uses sandbox for regex, 'local' uses safe substring matching */
+  mode?: ToolSearchMode;
+  /** Filter tools to only those from specific MCP server(s). Can be a single name or array of names. */
+  mcpServer?: string | string[];
+  [key: string]: unknown;
+};
+
+/** Simplified tool metadata for search purposes */
+export type ToolMetadata = {
+  name: string;
+  description: string;
+  parameters?: JsonSchemaType;
+};
+
+/** Individual search result for a matching tool */
+export type ToolSearchResult = {
+  tool_name: string;
+  match_score: number;
+  matched_field: string;
+  snippet: string;
+};
+
+/** Response from the tool search operation */
+export type ToolSearchResponse = {
+  tool_references: ToolSearchResult[];
+  total_tools_searched: number;
+  pattern_used: string;
+};
+
+/** Artifact returned alongside the formatted search results */
+export type ToolSearchArtifact = {
+  tool_references: ToolSearchResult[];
+  metadata: {
+    total_searched: number;
+    pattern: string;
+    error?: string;
+  };
+};
+
+// ============================================================================
+// Programmatic Tool Calling Types
+// ============================================================================
+
+/**
+ * Tool call requested by the Code API during programmatic execution
+ */
+export type PTCToolCall = {
+  /** Unique ID like "call_001" */
+  id: string;
+  /** Tool name */
+  name: string;
+  /** Input parameters */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  input: Record<string, any>;
+};
+
+/**
+ * Tool result sent back to the Code API
+ */
+export type PTCToolResult = {
+  /** Matches PTCToolCall.id */
+  call_id: string;
+  /** Tool execution result (any JSON-serializable value) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  result: any;
+  /** Whether tool execution failed */
+  is_error: boolean;
+  /** Error details if is_error=true */
+  error_message?: string;
+};
+
+/**
+ * Response from the Code API for programmatic execution
+ */
+export type ProgrammaticExecutionResponse = {
+  status: 'tool_call_required' | 'completed' | 'error' | unknown;
+  session_id?: string;
+
+  /** Present when status='tool_call_required' */
+  continuation_token?: string;
+  tool_calls?: PTCToolCall[];
+
+  /** Present when status='completed' */
+  stdout?: string;
+  stderr?: string;
+  files?: FileRefs;
+
+  /** Present when status='error' */
+  error?: string;
+};
+
+/**
+ * Artifact returned by the PTC tool
+ */
+export type ProgrammaticExecutionArtifact = {
+  session_id?: string;
+  files?: FileRefs;
+};
+
+/**
+ * Initialization parameters for the PTC tool
+ */
+export type ProgrammaticToolCallingParams = {
+  /** Code API key (or use CODE_API_KEY env var) */
+  apiKey?: string;
+  /** Code API base URL (or use CODE_BASEURL env var) */
+  baseUrl?: string;
+  /** Safety limit for round-trips (default: 20) */
+  maxRoundTrips?: number;
+  /** HTTP proxy URL */
+  proxy?: string;
+  /** Enable debug logging (or set PTC_DEBUG=true env var) */
+  debug?: boolean;
+  /** Environment variable key for API key */
+  [key: string]: unknown;
+};
+
+// ============================================================================
+// Tool Session Context Types
+// ============================================================================
+
+/**
+ * Tracks code execution session state for automatic file persistence.
+ * Stored in Graph.sessions and injected into subsequent tool invocations.
+ */
+export type CodeSessionContext = {
+  /** Session ID from the code execution environment */
+  session_id: string;
+  /** Files generated in this session (for context/tracking) */
+  files: FileRefs;
+  /** Timestamp of last update */
+  lastUpdated: number;
+};
+
+/**
+ * Artifact structure returned by code execution tools (CodeExecutor, PTC).
+ * Used to extract session context after tool completion.
+ */
+export type CodeExecutionArtifact = {
+  session_id?: string;
+  files?: FileRefs;
+};
+
+/**
+ * Generic session context union type for different tool types.
+ * Extend this as new tool session types are added.
+ */
+export type ToolSessionContext = CodeSessionContext;
+
+/**
+ * Map of tool names to their session contexts.
+ * Keys are tool constants (e.g., Constants.EXECUTE_CODE, Constants.PROGRAMMATIC_TOOL_CALLING).
+ */
+export type ToolSessionMap = Map<string, ToolSessionContext>;

package/src/utils/contextAnalytics.ts

@@ -0,0 +1,103 @@
+/**
+ * Context Analytics Utility
+ *
+ * Provides context analytics data for observability/traces.
+ * No console logging - just data structures for event emission.
+ */
+
+import type { BaseMessage } from '@langchain/core/messages';
+import type { TokenCounter } from '@/types/run';
+
+/**
+ * Context analytics data for traces
+ */
+export interface ContextAnalytics {
+  /** Total messages in context */
+  messageCount: number;
+  /** Total tokens in context */
+  totalTokens: number;
+  /** Maximum allowed context tokens */
+  maxContextTokens?: number;
+  /** Instruction/system tokens */
+  instructionTokens?: number;
+  /** Context utilization percentage (0-100) */
+  utilizationPercent?: number;
+  /** Breakdown by message type */
+  breakdown?: Record<string, { tokens: number; percent: number }>;
+}
+
+/**
+ * Build context analytics for traces (no logging)
+ */
+export function buildContextAnalytics(
+  messages: BaseMessage[],
+  options: {
+    tokenCounter?: TokenCounter;
+    maxContextTokens?: number;
+    instructionTokens?: number;
+    indexTokenCountMap?: Record<string, number | undefined>;
+  }
+): ContextAnalytics {
+  const {
+    tokenCounter,
+    maxContextTokens,
+    instructionTokens,
+    indexTokenCountMap,
+  } = options;
+
+  // Calculate total tokens
+  let totalTokens = 0;
+  const breakdown: Record<string, { tokens: number; percent: number }> = {};
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    const type = msg.getType();
+
+    let tokens = 0;
+    if (indexTokenCountMap && indexTokenCountMap[i] != null) {
+      tokens = indexTokenCountMap[i]!;
+    } else if (tokenCounter) {
+      try {
+        tokens = tokenCounter(msg);
+      } catch {
+        // Estimate from content length
+        const content =
+          typeof msg.content === 'string'
+            ? msg.content
+            : JSON.stringify(msg.content);
+        tokens = Math.ceil(content.length / 4);
+      }
+    }
+
+    totalTokens += tokens;
+
+    if (!breakdown[type]) {
+      breakdown[type] = { tokens: 0, percent: 0 };
+    }
+    breakdown[type].tokens += tokens;
+  }
+
+  // Calculate percentages
+  for (const type of Object.keys(breakdown)) {
+    breakdown[type].percent =
+      totalTokens > 0
+        ? Math.round((breakdown[type].tokens / totalTokens) * 1000) / 10
+        : 0;
+  }
+
+  // Calculate utilization
+  let utilizationPercent: number | undefined;
+  if (maxContextTokens && maxContextTokens > 0) {
+    utilizationPercent =
+      Math.round((totalTokens / maxContextTokens) * 1000) / 10;
+  }
+
+  return {
+    messageCount: messages.length,
+    totalTokens,
+    maxContextTokens,
+    instructionTokens,
+    utilizationPercent,
+    breakdown,
+  };
+}

package/src/utils/events.ts

@@ -0,0 +1,32 @@
+/* eslint-disable no-console */
+// src/utils/events.ts
+import { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';
+import type { RunnableConfig } from '@langchain/core/runnables';
+
+/**
+ * Safely dispatches a custom event and properly awaits it to avoid
+ * race conditions where events are dispatched after run cleanup.
+ */
+export async function safeDispatchCustomEvent(
+  event: string,
+  payload: unknown,
+  config?: RunnableConfig
+): Promise<void> {
+  try {
+    await dispatchCustomEvent(event, payload, config);
+  } catch (e) {
+    // Check if this is the known EventStreamCallbackHandler error
+    if (
+      e instanceof Error &&
+      e.message.includes('handleCustomEvent: Run ID') &&
+      e.message.includes('not found in run map')
+    ) {
+      // Suppress this specific error - it's expected during parallel execution
+      // when EventStreamCallbackHandler loses track of run IDs
+      // console.debug('Suppressed error dispatching custom event:', e);
+      return;
+    }
+    // Log other errors
+    console.error('Error dispatching custom event:', e);
+  }
+}

package/src/utils/graph.ts

@@ -0,0 +1,11 @@
+export const resetIfNotEmpty = <T>(value: T, resetValue: T): T => {
+  if (Array.isArray(value)) {
+    return value.length > 0 ? resetValue : value;
+  }
+  if (value instanceof Set || value instanceof Map) {
+    return value.size > 0 ? resetValue : value;
+  }
+  return value !== undefined ? resetValue : value;
+};
+
+export const joinKeys = (args: (string | number | undefined)[]): string => args.join('_');

package/src/utils/handlers.ts

@@ -0,0 +1,107 @@
+/**
+ * Multi-Agent Handler Utilities
+ *
+ * Provides a simple helper to create handlers with content aggregation for multi-agent scripts.
+ *
+ * Usage:
+ * ```typescript
+ * const { contentParts, aggregateContent, handlers } = createHandlers();
+ *
+ * // With callbacks
+ * const { contentParts, aggregateContent, handlers } = createHandlers({
+ *   onRunStep: (event, data) => console.log('Step:', data),
+ *   onRunStepCompleted: (event, data) => console.log('Completed:', data)
+ * });
+ * ```
+ */
+
+import { GraphEvents } from '@/common';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import type * as t from '@/types';
+
+interface HandlerCallbacks {
+  onRunStep?: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData) => void;
+  onRunStepCompleted?: (
+    event: GraphEvents.ON_RUN_STEP_COMPLETED,
+    data: t.StreamEventData
+  ) => void;
+  onRunStepDelta?: (
+    event: GraphEvents.ON_RUN_STEP_DELTA,
+    data: t.StreamEventData
+  ) => void;
+  onMessageDelta?: (
+    event: GraphEvents.ON_MESSAGE_DELTA,
+    data: t.StreamEventData
+  ) => void;
+}
+
+/**
+ * Creates handlers with content aggregation for multi-agent scripts
+ */
+export function createHandlers(callbacks?: HandlerCallbacks): {
+  contentParts: Array<t.MessageContentComplex | undefined>;
+  aggregateContent: ReturnType<
+    typeof createContentAggregator
+  >['aggregateContent'];
+  handlers: Record<string, t.EventHandler>;
+} {
+  // Set up content aggregator
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  // Create the handlers object
+  const handlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.RunStep });
+        callbacks?.onRunStep?.(event, data);
+      },
+    },
+
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+        callbacks?.onRunStepCompleted?.(event, data);
+      },
+    },
+
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+        callbacks?.onRunStepDelta?.(event, data);
+      },
+    },
+
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+        callbacks?.onMessageDelta?.(event, data);
+      },
+    },
+  };
+
+  return {
+    contentParts,
+    aggregateContent,
+    handlers,
+  };
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+export * from './graph';
+export * from './llm';
+export * from './misc';
+export * from './handlers';
+export * from './run';
+export * from './tokens';
+export * from './toonFormat';
+export * from './contextAnalytics';
+export * from './schema';

package/src/utils/llm.ts

@@ -0,0 +1,26 @@
+// src/utils/llm.ts
+import { Providers } from '@/common';
+
+export function isOpenAILike(provider?: string | Providers): boolean {
+  if (provider == null) {
+    return false;
+  }
+  return (
+    [
+      Providers.OPENAI,
+      Providers.AZURE,
+      Providers.OPENROUTER,
+      Providers.XAI,
+      Providers.DEEPSEEK,
+    ] as string[]
+  ).includes(provider);
+}
+
+export function isGoogleLike(provider?: string | Providers): boolean {
+  if (provider == null) {
+    return false;
+  }
+  return ([Providers.GOOGLE, Providers.VERTEXAI] as string[]).includes(
+    provider
+  );
+}