@illuma-ai/agents 1.0.81

package/dist/esm/utils/toonFormat.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toonFormat.mjs","sources":["../../../src/utils/toonFormat.ts"],"sourcesContent":["/**\n * TOON Format Utility\n *\n * Provides JSON to TOON conversion for token-efficient encoding.\n * TOON format can reduce token count by 30-60% for JSON data.\n *\n * Uses the official @toon-format/toon library when available.\n */\n\n// Dynamic import holder for the TOON library (ESM)\nlet toonEncode: ((data: unknown) => string) | null = null;\nlet toonLoadAttempted = false;\nlet toonLoadPromise: Promise<boolean> | null = null;\n\n/**\n * Lazily loads the TOON library\n * Tries both ESM dynamic import and CommonJS require for compatibility\n */\nasync function loadToonLibrary(): Promise<boolean> {\n  if (toonLoadAttempted) return toonEncode !== null;\n  toonLoadAttempted = true;\n\n  // Try ESM dynamic import first\n  try {\n    const mod = await import('@toon-format/toon');\n    toonEncode = mod.encode;\n    return true;\n  } catch {\n    // ESM import failed, try CommonJS require\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-require-imports\n      const mod = require('@toon-format/toon');\n      toonEncode = mod.encode;\n      return true;\n    } catch {\n      // Library not available - that's OK, we'll return original content\n      return false;\n    }\n  }\n}\n\n/**\n * Ensures the TOON library is loaded. Call this before using jsonToToon in tests.\n */\nexport async function ensureToonLoaded(): Promise<boolean> {\n  if (!toonLoadPromise) {\n    toonLoadPromise = loadToonLibrary();\n  }\n  return toonLoadPromise;\n}\n\n// Start loading immediately\nensureToonLoaded();\n\n/**\n * Check if a string appears to be in TOON format.\n * TOON format characteristics:\n * - Uses key: value syntax (like YAML)\n * - Uses array notation like [3] or {fields}\n * - Does NOT start with { or [\n * - Often has patterns like \"name[N]:\" or \"name{fields}:\"\n *\n * @param str - String to check\n * @returns true if string appears to be TOON format\n */\nexport function isToonFormat(str: string): boolean {\n  if (typeof str !== 'string' || str.length === 0) return false;\n\n  const trimmed = str.trim();\n\n  // TOON doesn't start with JSON brackets\n  if (trimmed.startsWith('{') || trimmed.startsWith('[')) return false;\n\n  // Check for TOON-specific patterns:\n  // 1. Key-value with colon (but not URL-like patterns)\n  // 2. Array notation like \"items[3]:\" or \"data[10]:\"\n  // 3. Object schema notation like \"items{id,name}:\"\n  const toonPatterns = [\n    /^\\w+:$/m, // Simple key: at start of line\n    /^\\w+\\[\\d+\\]:/m, // Array notation: items[3]:\n    /^\\w+\\{[^}]+\\}:/m, // Schema notation: items{id,name}:\n    /^\\w+\\[\\d+\\]\\{[^}]+\\}:/m, // Combined: items[3]{id,name}:\n  ];\n\n  // Must match at least one TOON pattern\n  const hasToonPattern = toonPatterns.some((pattern) => pattern.test(trimmed));\n\n  // Additional check: TOON typically has multiple lines with consistent indentation\n  const lines = trimmed.split('\\n').filter((l) => l.trim());\n  const hasMultipleKeyValueLines =\n    lines.filter((l) => /^\\s*\\w+.*:/.test(l)).length >= 2;\n\n  return hasToonPattern || hasMultipleKeyValueLines;\n}\n\n/**\n * Extract the first valid JSON object or array from a string.\n * Handles pure JSON or JSON embedded in text (e.g., tool responses).\n *\n * @param str - The string to extract JSON from\n * @returns Object with found status, parsed JSON, and indices\n */\nexport function extractFirstJson(str: string): {\n  found: boolean;\n  parsed: unknown;\n  startIndex: number;\n  endIndex: number;\n} {\n  if (typeof str !== 'string' || str.length === 0) {\n    return { found: false, parsed: null, startIndex: -1, endIndex: -1 };\n  }\n\n  // Find the first { or [ character\n  const objStart = str.indexOf('{');\n  const arrStart = str.indexOf('[');\n\n  if (objStart === -1 && arrStart === -1) {\n    return { found: false, parsed: null, startIndex: -1, endIndex: -1 };\n  }\n\n  let startIndex: number;\n  if (objStart === -1) {\n    startIndex = arrStart;\n  } else if (arrStart === -1) {\n    startIndex = objStart;\n  } else {\n    startIndex = Math.min(objStart, arrStart);\n  }\n\n  // Find the matching closing bracket using a stack-based approach\n  // Properly handle strings to avoid counting brackets inside strings\n  let depth = 0;\n  let inString = false;\n  let escapeNext = false;\n\n  for (let i = startIndex; i < str.length; i++) {\n    const char = str[i];\n\n    if (escapeNext) {\n      escapeNext = false;\n      continue;\n    }\n\n    if (char === '\\\\' && inString) {\n      escapeNext = true;\n      continue;\n    }\n\n    if (char === '\"') {\n      inString = !inString;\n      continue;\n    }\n\n    if (inString) continue;\n\n    if (char === '{' || char === '[') depth++;\n    if (char === '}' || char === ']') depth--;\n\n    if (depth === 0) {\n      // Found matching bracket, try to parse\n      const jsonStr = str.substring(startIndex, i + 1);\n      try {\n        const parsed = JSON.parse(jsonStr);\n        return { found: true, parsed, startIndex, endIndex: i };\n      } catch {\n        // Not valid JSON at this bracket level, continue searching\n        // Reset and look for the next JSON start after this position\n        const nextResult = extractFirstJson(str.substring(i + 1));\n        if (nextResult.found) {\n          return {\n            found: true,\n            parsed: nextResult.parsed,\n            startIndex: i + 1 + nextResult.startIndex,\n            endIndex: i + 1 + nextResult.endIndex,\n          };\n        }\n        return { found: false, parsed: null, startIndex: -1, endIndex: -1 };\n      }\n    }\n  }\n\n  return { found: false, parsed: null, startIndex: -1, endIndex: -1 };\n}\n\n/**\n * Convert JSON content to TOON format for token efficiency.\n * Extracts JSON from string if embedded, converts to TOON.\n * Returns original string if:\n * - Already in TOON format\n * - Not JSON\n * - TOON conversion fails or is larger\n *\n * @param str - The string containing JSON to convert\n * @returns Object with conversion status, result, and reduction percentage\n */\nexport function jsonToToon(str: string): {\n  converted: boolean;\n  result: string;\n  reduction: number;\n  alreadyToon?: boolean;\n  error?: string;\n} {\n  if (!toonEncode || typeof str !== 'string') {\n    return {\n      converted: false,\n      result: str,\n      reduction: 0,\n      error: !toonEncode ? 'TOON library not loaded' : undefined,\n    };\n  }\n\n  // Check if already in TOON format - skip conversion\n  if (isToonFormat(str)) {\n    return { converted: false, result: str, reduction: 0, alreadyToon: true };\n  }\n\n  try {\n    const { found, parsed, startIndex, endIndex } = extractFirstJson(str);\n\n    if (!found || !parsed) {\n      return {\n        converted: false,\n        result: str,\n        reduction: 0,\n        error: 'No JSON found in content',\n      };\n    }\n\n    // Check if this JSON structure would benefit from TOON\n    // Text-heavy content (emails, documents) won't compress well\n    if (!isToonBeneficial(parsed)) {\n      return {\n        converted: false,\n        result: str,\n        reduction: 0,\n        error:\n          'Content is text-heavy (>70% string values), TOON not beneficial',\n      };\n    }\n\n    const toonResult = toonEncode(parsed);\n\n    // Preserve text before and after the JSON block\n    const textBefore = str.substring(0, startIndex);\n    const textAfter = str.substring(endIndex + 1);\n\n    // Build the full result: textBefore + TOON + textAfter\n    const fullResult = textBefore + toonResult + textAfter;\n\n    if (fullResult.length < str.length) {\n      const reduction = Math.round(\n        ((str.length - fullResult.length) / str.length) * 100\n      );\n      return { converted: true, result: fullResult, reduction };\n    } else {\n      // TOON output was larger or same size - not beneficial\n      return {\n        converted: false,\n        result: str,\n        reduction: 0,\n        error: `TOON output not smaller (${fullResult.length} >= ${str.length})`,\n      };\n    }\n  } catch (err) {\n    // TOON encoding or extraction failed - log error for debugging\n    const errorMsg = err instanceof Error ? err.message : String(err);\n    return {\n      converted: false,\n      result: str,\n      reduction: 0,\n      error: `TOON conversion error: ${errorMsg}`,\n    };\n  }\n}\n\n/**\n * Check if TOON library is loaded and available\n */\nexport function isToonAvailable(): boolean {\n  return toonEncode !== null;\n}\n\n/**\n * Result of processing tool output\n */\nexport interface ProcessToolOutputResult {\n  /** The processed content string */\n  content: string;\n  /** Whether TOON conversion was applied */\n  toonConverted: boolean;\n  /** Whether content was truncated */\n  truncated: boolean;\n  /** Percentage reduction from TOON (0 if not converted) */\n  reduction: number;\n  /** Whether input was already in TOON format */\n  alreadyToon: boolean;\n  /** Original content length */\n  originalLength: number;\n  /** Estimated original tokens (~4 chars per token) */\n  originalTokens: number;\n  /** Final content length */\n  finalLength: number;\n  /** Estimated final tokens */\n  finalTokens: number;\n  /** Error message if TOON conversion failed (for debugging) */\n  toonError?: string;\n}\n\n/**\n * Options for processing tool output\n */\nexport interface ProcessToolOutputOptions {\n  /** Maximum output length in characters (default: 100000) */\n  maxLength?: number;\n  /** Whether to apply TOON conversion (default: true) */\n  enableToon?: boolean;\n  /** Minimum content size to attempt TOON conversion (default: 1000) */\n  minSizeForToon?: number;\n  /** Minimum reduction % to accept TOON result (default: 10) */\n  minReductionPercent?: number;\n}\n\n/**\n * Analyze JSON structure to determine if TOON conversion would be beneficial.\n * Text-heavy content (emails, documents) doesn't compress well with TOON.\n * Structured data (API responses, metadata) compresses much better.\n *\n * @param parsed - Parsed JSON object\n * @returns true if TOON conversion is likely beneficial\n */\nfunction isToonBeneficial(parsed: unknown): boolean {\n  if (!parsed || typeof parsed !== 'object') return false;\n\n  const jsonStr = JSON.stringify(parsed);\n  const totalLength = jsonStr.length;\n\n  // Count characters in string values (text content)\n  let textContentLength = 0;\n\n  function countTextContent(obj: unknown): void {\n    if (typeof obj === 'string') {\n      // Count string length (this is text content that TOON can't compress)\n      textContentLength += obj.length;\n    } else if (Array.isArray(obj)) {\n      obj.forEach(countTextContent);\n    } else if (obj && typeof obj === 'object') {\n      Object.values(obj).forEach(countTextContent);\n    }\n  }\n\n  countTextContent(parsed);\n\n  // Calculate ratio of text content to total JSON\n  const textRatio = textContentLength / totalLength;\n\n  // If more than 70% is text content, TOON won't help much\n  // TOON compresses structure (field names, brackets), not text\n  return textRatio < 0.7;\n}\n\n/**\n * Process tool output: apply TOON conversion if beneficial, then truncate if needed.\n * This is the main entry point for processing any tool output (regular or MCP).\n *\n * Flow:\n * 1. Check if already TOON format → skip conversion\n * 2. Try TOON conversion if content is JSON and large enough\n * 3. Truncate if still exceeds maxLength (with smart break points)\n *\n * @param content - The tool output content\n * @param options - Processing options\n * @returns Processed content and metadata\n */\nexport function processToolOutput(\n  content: string,\n  options: ProcessToolOutputOptions = {}\n): ProcessToolOutputResult {\n  const {\n    maxLength = 100000,\n    enableToon = true,\n    minSizeForToon = 1000,\n    minReductionPercent = 10, // Increased from 5% - only apply TOON when clearly beneficial\n  } = options;\n\n  const originalLength = content.length;\n  const originalTokens = Math.ceil(originalLength / 4);\n\n  let result = content;\n  let toonConverted = false;\n  let alreadyToon = false;\n  let reduction = 0;\n  let truncated = false;\n  let toonError: string | undefined;\n\n  // Step 1: Check if already TOON format\n  if (isToonFormat(content)) {\n    alreadyToon = true;\n  }\n  // Step 2: Apply TOON conversion if enabled and content is large enough\n  else if (enableToon && content.length > minSizeForToon) {\n    const toonResult = jsonToToon(content);\n    if (toonResult.alreadyToon) {\n      alreadyToon = true;\n    } else if (\n      toonResult.converted &&\n      toonResult.reduction >= minReductionPercent\n    ) {\n      result = toonResult.result;\n      toonConverted = true;\n      reduction = toonResult.reduction;\n    } else if (toonResult.error) {\n      // Track error for debugging\n      toonError = toonResult.error;\n    } else if (\n      toonResult.converted &&\n      toonResult.reduction < minReductionPercent\n    ) {\n      // TOON converted but reduction was too small to be worth it\n      toonError = `TOON reduction ${toonResult.reduction}% below threshold ${minReductionPercent}%`;\n    } else if (!toonResult.converted) {\n      // Conversion failed without explicit error - investigate\n      toonError =\n        toonResult.error || 'TOON conversion returned false with no error';\n    }\n  }\n\n  // Step 3: Truncate if still too long (with smart break points)\n  if (result.length > maxLength) {\n    let truncatedStr = result.substring(0, maxLength);\n\n    // Try to find a clean break point\n    if (toonConverted || alreadyToon) {\n      // For TOON format, break at newline for cleaner output\n      const lastNewline = truncatedStr.lastIndexOf('\\n');\n      if (lastNewline > maxLength * 0.7) {\n        truncatedStr = truncatedStr.substring(0, lastNewline);\n      }\n    } else {\n      // For JSON, try to find a clean JSON break point\n      const lastCompleteItem = truncatedStr.lastIndexOf('},');\n      const lastArrayItem = truncatedStr.lastIndexOf('],');\n      const breakPoint = Math.max(lastCompleteItem, lastArrayItem);\n      if (breakPoint > maxLength * 0.5) {\n        truncatedStr = truncatedStr.substring(0, breakPoint + 1);\n      }\n    }\n\n    // Build truncation message\n    const truncationInfo = toonConverted\n      ? `Original ${originalLength.toLocaleString()} chars → TOON ${result.length.toLocaleString()} chars (${reduction}% saved). ` +\n        `Still exceeds ${maxLength.toLocaleString()} char limit.`\n      : `Original output was ${originalLength.toLocaleString()} characters (~${originalTokens.toLocaleString()} tokens).`;\n\n    result =\n      truncatedStr +\n      `\\n\\n[OUTPUT_TRUNCATED: ${truncationInfo} Please use more specific queries or smaller date ranges.]`;\n    truncated = true;\n  }\n\n  const finalLength = result.length;\n  const finalTokens = Math.ceil(finalLength / 4);\n\n  return {\n    content: result,\n    toonConverted,\n    truncated,\n    reduction,\n    alreadyToon,\n    originalLength,\n    originalTokens,\n    finalLength,\n    finalTokens,\n    toonError,\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/types/agents/AgentContext.d.ts

@@ -0,0 +1,293 @@
+import { SystemMessage } from '@langchain/core/messages';
+import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import type { createPruneMessages } from '@/messages';
+import { ContentTypes, Providers } from '@/common';
+/**
+ * Encapsulates agent-specific state that can vary between agents in a multi-agent system
+ */
+export declare class AgentContext {
+    /**
+     * Create an AgentContext from configuration with token accounting initialization
+     */
+    static fromConfig(agentConfig: t.AgentInputs, tokenCounter?: t.TokenCounter, indexTokenCountMap?: Record<string, number>): AgentContext;
+    /** Agent identifier */
+    agentId: string;
+    /** Human-readable name for this agent (used in handoff context). Falls back to agentId if not provided. */
+    name?: string;
+    /** Provider for this specific agent */
+    provider: Providers;
+    /** Client options for this agent */
+    clientOptions?: t.ClientOptions;
+    /** Token count map indexed by message position */
+    indexTokenCountMap: Record<string, number | undefined>;
+    /** Maximum context tokens for this agent */
+    maxContextTokens?: number;
+    /** Current usage metadata for this agent */
+    currentUsage?: Partial<UsageMetadata>;
+    /** Prune messages function configured for this agent */
+    pruneMessages?: ReturnType<typeof createPruneMessages>;
+    /** Token counter function for this agent */
+    tokenCounter?: t.TokenCounter;
+    /** Instructions/system message token count */
+    instructionTokens: number;
+    /** The amount of time that should pass before another consecutive API call */
+    streamBuffer?: number;
+    /** Last stream call timestamp for rate limiting */
+    lastStreamCall?: number;
+    /** Tools available to this agent */
+    tools?: t.GraphTools;
+    /** Tool map for this agent */
+    toolMap?: t.ToolMap;
+    /**
+     * Tool definitions registry (includes deferred and programmatic tool metadata).
+     * Used for tool search and programmatic tool calling.
+     */
+    toolRegistry?: t.LCToolRegistry;
+    /**
+     * Serializable tool definitions for event-driven execution.
+     * When provided, ToolNode operates in event-driven mode.
+     */
+    toolDefinitions?: t.LCTool[];
+    /** Set of tool names discovered via tool search (to be loaded) */
+    discoveredToolNames: Set<string>;
+    /** Instructions for this agent */
+    instructions?: string;
+    /** Additional instructions for this agent */
+    additionalInstructions?: string;
+    /**
+     * Dynamic context that changes per-request (e.g., current time, user info).
+     * This is NOT included in the system message to preserve cache.
+     * Instead, it's injected as a user message at the start of the conversation.
+     */
+    dynamicContext?: string;
+    /** Reasoning key for this agent */
+    reasoningKey: 'reasoning_content' | 'reasoning';
+    /** Last token for reasoning detection */
+    lastToken?: string;
+    /** Token type switch state */
+    tokenTypeSwitch?: 'reasoning' | 'content';
+    /** Current token type being processed */
+    currentTokenType: ContentTypes.TEXT | ContentTypes.THINK | 'think_and_text';
+    /** Whether tools should end the workflow */
+    toolEnd: boolean;
+    /** Cached system runnable (created lazily) */
+    private cachedSystemRunnable?;
+    /** Whether system runnable needs rebuild (set when discovered tools change) */
+    private systemRunnableStale;
+    /** Cached system message token count (separate from tool tokens) */
+    private systemMessageTokens;
+    /** Promise for token calculation initialization */
+    tokenCalculationPromise?: Promise<void>;
+    /** Format content blocks as strings (for legacy compatibility) */
+    useLegacyContent: boolean;
+    /** Detailed per-tool token breakdown for admin tracking */
+    private toolsDetail;
+    /** Total tool tokens (sum of all toolsDetail) */
+    private toolTokensTotal;
+    /** Per-prompt token breakdown for detailed admin reporting */
+    private promptBreakdown;
+    /**
+     * Handoff context when this agent receives control via handoff.
+     * Contains source and parallel execution info for system message context.
+     */
+    handoffContext?: {
+        /** Source agent that transferred control */
+        sourceAgentName: string;
+        /** Names of sibling agents executing in parallel (empty if sequential) */
+        parallelSiblings: string[];
+    };
+    /**
+     * Structured output configuration.
+     * When set, the agent will return a validated JSON response
+     * instead of streaming text.
+     */
+    structuredOutput?: t.StructuredOutputConfig;
+    /**
+     * Optional callback for summarizing messages that were pruned from context.
+     * When provided, discarded messages are summarized instead of silently dropped.
+     */
+    summarizeCallback?: (messagesToRefine: BaseMessage[]) => Promise<string | undefined>;
+    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, }: {
+        agentId: string;
+        name?: string;
+        provider: Providers;
+        clientOptions?: t.ClientOptions;
+        maxContextTokens?: number;
+        streamBuffer?: number;
+        tokenCounter?: t.TokenCounter;
+        tools?: t.GraphTools;
+        toolMap?: t.ToolMap;
+        toolRegistry?: t.LCToolRegistry;
+        toolDefinitions?: t.LCTool[];
+        instructions?: string;
+        additionalInstructions?: string;
+        dynamicContext?: string;
+        reasoningKey?: 'reasoning_content' | 'reasoning';
+        toolEnd?: boolean;
+        instructionTokens?: number;
+        useLegacyContent?: boolean;
+        structuredOutput?: t.StructuredOutputConfig;
+        discoveredTools?: string[];
+    });
+    /**
+     * Checks if structured output mode is enabled for this agent.
+     * When enabled, the agent will use model.invoke() instead of streaming
+     * and return a validated JSON response.
+     */
+    get isStructuredOutputMode(): boolean;
+    /**
+     * Gets the structured output schema with normalized defaults.
+     * Returns undefined if structured output is not configured.
+     */
+    getStructuredOutputSchema(): Record<string, unknown> | undefined;
+    /**
+     * Resolves the structured output mode to a concrete method based on provider capabilities.
+     *
+     * Resolution logic:
+     * - 'native' or 'auto' + supported provider → native constrained decoding
+     * - 'native' + unsupported provider → fallback to 'functionCalling' with warning
+     * - 'provider' → LangChain's jsonMode (existing behavior)
+     * - 'tool' → function calling trick (existing behavior)
+     * - 'auto' + unsupported provider → 'functionCalling'
+     *
+     * @returns The resolved method for withStructuredOutput, or 'native' for direct API usage
+     */
+    resolveStructuredOutputMode(): {
+        method: t.ResolvedStructuredOutputMethod;
+        warnings: string[];
+    };
+    /**
+     * Builds instructions text for tools that are ONLY callable via programmatic code execution.
+     * These tools cannot be called directly by the LLM but are available through the
+     * run_tools_with_code tool.
+     *
+     * Includes:
+     * - Code_execution-only tools that are NOT deferred
+     * - Code_execution-only tools that ARE deferred but have been discovered via tool search
+     */
+    private buildProgrammaticOnlyToolsInstructions;
+    /**
+     * Gets the system runnable, creating it lazily if needed.
+     * Includes instructions, additional instructions, and programmatic-only tools documentation.
+     * Only rebuilds when marked stale (via markToolsAsDiscovered).
+     */
+    get systemRunnable(): Runnable<BaseMessage[], (BaseMessage | SystemMessage)[], RunnableConfig<Record<string, unknown>>> | undefined;
+    /**
+     * Explicitly initializes the system runnable.
+     * Call this before async token calculation to ensure system message tokens are counted first.
+     */
+    initializeSystemRunnable(): void;
+    /**
+     * Builds the raw instructions string (without creating SystemMessage).
+     * Includes agent identity preamble and handoff context when available.
+     */
+    private buildInstructionsString;
+    /**
+     * Builds the agent identity preamble including handoff context if present.
+     * This helps the agent understand its role in the multi-agent workflow.
+     */
+    private buildIdentityPreamble;
+    /**
+     * Build system runnable from pre-built instructions string.
+     * Only called when content has actually changed.
+     */
+    private buildSystemRunnable;
+    /**
+     * Reset context for a new run
+     */
+    reset(): void;
+    /**
+     * Update the token count map with instruction tokens
+     */
+    updateTokenMapWithInstructions(baseTokenMap: Record<string, number>): void;
+    /**
+     * Calculate tool tokens and add to instruction tokens
+     * Note: System message tokens are calculated during systemRunnable creation
+     * Also tracks per-tool token breakdown for admin reporting
+     */
+    calculateInstructionTokens(tokenCounter: t.TokenCounter): Promise<void>;
+    /**
+     * Set the per-prompt token breakdown for detailed admin tracking.
+     * Called by the client after assembling all prompt components.
+     * @param breakdown - Object with token counts per prompt component
+     */
+    setPromptBreakdown(breakdown: {
+        branding?: number;
+        toolRouting?: number;
+        agentInstructions?: number;
+        mcpInstructions?: number;
+        artifacts?: number;
+        memory?: number;
+    }): void;
+    /**
+     * Get a detailed breakdown of context tokens for admin reporting.
+     * This provides visibility into what's consuming the input token budget.
+     * @returns ContextBreakdown object with per-component token counts
+     */
+    getContextBreakdown(): {
+        instructions: number;
+        artifacts: number;
+        tools: number;
+        toolCount: number;
+        toolContext: number;
+        total: number;
+        toolsDetail: Array<{
+            name: string;
+            tokens: number;
+        }>;
+        toolContextDetail: Array<{
+            name: string;
+            tokens: number;
+        }>;
+        prompts?: {
+            branding: number;
+            toolRouting: number;
+            agentInstructions: number;
+            mcpInstructions: number;
+            artifacts: number;
+            memory: number;
+        };
+    };
+    /**
+     * Gets the tool registry for deferred tools (for tool search).
+     * @param onlyDeferred If true, only returns tools with defer_loading=true
+     * @returns LCToolRegistry with tool definitions
+     */
+    getDeferredToolRegistry(onlyDeferred?: boolean): t.LCToolRegistry;
+    /**
+     * Sets the handoff context for this agent.
+     * Call this when the agent receives control via handoff from another agent.
+     * Marks system runnable as stale to include handoff context in system message.
+     * @param sourceAgentName - Name of the agent that transferred control
+     * @param parallelSiblings - Names of other agents executing in parallel with this one
+     */
+    setHandoffContext(sourceAgentName: string, parallelSiblings: string[]): void;
+    /**
+     * Clears any handoff context.
+     * Call this when resetting the agent or when handoff context is no longer relevant.
+     */
+    clearHandoffContext(): void;
+    /**
+     * Marks tools as discovered via tool search.
+     * Discovered tools will be included in the next model binding.
+     * Only marks system runnable stale if NEW tools were actually added.
+     * @param toolNames - Array of discovered tool names
+     * @returns true if any new tools were discovered
+     */
+    markToolsAsDiscovered(toolNames: string[]): boolean;
+    /**
+     * Gets tools that should be bound to the LLM.
+     * In event-driven mode (toolDefinitions present, tools empty), creates schema-only tools.
+     * Otherwise filters tool instances based on:
+     * 1. Non-deferred tools with allowed_callers: ['direct']
+     * 2. Discovered tools (from tool search)
+     * @returns Array of tools to bind to model
+     */
+    getToolsForBinding(): t.GraphTools | undefined;
+    /** Creates schema-only tools from toolDefinitions for event-driven mode */
+    private getEventDrivenToolsForBinding;
+    /** Filters tool instances for binding based on registry config */
+    private filterToolsForBinding;
+}

package/dist/types/common/enum.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Enum representing the various event types emitted during the execution of runnables.
+ * These events provide real-time information about the progress and state of different components.
+ *
+ * @enum {string}
+ */
+export declare enum GraphEvents {
+    /** [Custom] Agent update event in multi-agent graph/workflow */
+    ON_AGENT_UPDATE = "on_agent_update",
+    /** [Custom] Delta event for run steps (message creation and tool calls) */
+    ON_RUN_STEP = "on_run_step",
+    /** [Custom] Delta event for run steps (tool calls) */
+    ON_RUN_STEP_DELTA = "on_run_step_delta",
+    /** [Custom] Completed event for run steps (tool calls) */
+    ON_RUN_STEP_COMPLETED = "on_run_step_completed",
+    /** [Custom] Delta events for messages */
+    ON_MESSAGE_DELTA = "on_message_delta",
+    /** [Custom] Reasoning Delta events for messages */
+    ON_REASONING_DELTA = "on_reasoning_delta",
+    /** [Custom] Context analytics event for traces */
+    ON_CONTEXT_ANALYTICS = "on_context_analytics",
+    /** [Custom] Structured output event - emitted when agent returns structured JSON */
+    ON_STRUCTURED_OUTPUT = "on_structured_output",
+    /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
+    ON_TOOL_EXECUTE = "on_tool_execute",
+    /** Custom event, emitted by system */
+    ON_CUSTOM_EVENT = "on_custom_event",
+    /** Emitted when a chat model starts processing. */
+    CHAT_MODEL_START = "on_chat_model_start",
+    /** Emitted when a chat model streams a chunk of its response. */
+    CHAT_MODEL_STREAM = "on_chat_model_stream",
+    /** Emitted when a chat model completes its processing. */
+    CHAT_MODEL_END = "on_chat_model_end",
+    /** Emitted when a language model starts processing. */
+    LLM_START = "on_llm_start",
+    /** Emitted when a language model streams a chunk of its response. */
+    LLM_STREAM = "on_llm_stream",
+    /** Emitted when a language model completes its processing. */
+    LLM_END = "on_llm_end",
+    /** Emitted when a chain starts processing. */
+    CHAIN_START = "on_chain_start",
+    /** Emitted when a chain streams a chunk of its output. */
+    CHAIN_STREAM = "on_chain_stream",
+    /** Emitted when a chain completes its processing. */
+    CHAIN_END = "on_chain_end",
+    /** Emitted when a tool starts its operation. */
+    TOOL_START = "on_tool_start",
+    /** Emitted when a tool completes its operation. */
+    TOOL_END = "on_tool_end",
+    /** Emitted when a retriever starts its operation. */
+    RETRIEVER_START = "on_retriever_start",
+    /** Emitted when a retriever completes its operation. */
+    RETRIEVER_END = "on_retriever_end",
+    /** Emitted when a prompt starts processing. */
+    PROMPT_START = "on_prompt_start",
+    /** Emitted when a prompt completes its processing. */
+    PROMPT_END = "on_prompt_end"
+}
+export declare enum Providers {
+    OPENAI = "openAI",
+    VERTEXAI = "vertexai",
+    BEDROCK = "bedrock",
+    ANTHROPIC = "anthropic",
+    MISTRALAI = "mistralai",
+    MISTRAL = "mistral",
+    GOOGLE = "google",
+    AZURE = "azureOpenAI",
+    DEEPSEEK = "deepseek",
+    OPENROUTER = "openrouter",
+    XAI = "xai",
+    MOONSHOT = "moonshot"
+}
+export declare enum GraphNodeKeys {
+    TOOLS = "tools=",
+    AGENT = "agent=",
+    ROUTER = "router",
+    PRE_TOOLS = "pre_tools",
+    POST_TOOLS = "post_tools"
+}
+export declare enum GraphNodeActions {
+    TOOL_NODE = "tool_node",
+    CALL_MODEL = "call_model",
+    ROUTE_MESSAGE = "route_message"
+}
+export declare enum CommonEvents {
+    LANGGRAPH = "LangGraph"
+}
+export declare enum StepTypes {
+    TOOL_CALLS = "tool_calls",
+    MESSAGE_CREATION = "message_creation"
+}
+export declare enum ContentTypes {
+    TEXT = "text",
+    ERROR = "error",
+    THINK = "think",
+    TOOL_CALL = "tool_call",
+    IMAGE_URL = "image_url",
+    IMAGE_FILE = "image_file",
+    /** Anthropic */
+    THINKING = "thinking",
+    /** Vertex AI / Google Common */
+    REASONING = "reasoning",
+    /** Multi-Agent Switch */
+    AGENT_UPDATE = "agent_update",
+    /** Bedrock */
+    REASONING_CONTENT = "reasoning_content"
+}
+export declare enum ToolCallTypes {
+    FUNCTION = "function",
+    RETRIEVAL = "retrieval",
+    FILE_SEARCH = "file_search",
+    CODE_INTERPRETER = "code_interpreter",
+    TOOL_CALL = "tool_call"
+}
+export declare enum Callback {
+    TOOL_ERROR = "handleToolError",
+    TOOL_START = "handleToolStart",
+    TOOL_END = "handleToolEnd",
+    CUSTOM_EVENT = "handleCustomEvent"
+}
+export declare enum Constants {
+    OFFICIAL_CODE_BASEURL = "https://api.illuma.ai/v1",
+    EXECUTE_CODE = "execute_code",
+    TOOL_SEARCH = "tool_search",
+    PROGRAMMATIC_TOOL_CALLING = "run_tools_with_code",
+    WEB_SEARCH = "web_search",
+    CONTENT_AND_ARTIFACT = "content_and_artifact",
+    LC_TRANSFER_TO_ = "lc_transfer_to_",
+    /** Delimiter for MCP tools: toolName_mcp_serverName */
+    MCP_DELIMITER = "_mcp_"
+}
+export declare enum TitleMethod {
+    STRUCTURED = "structured",
+    FUNCTIONS = "functions",
+    COMPLETION = "completion"
+}
+export declare enum EnvVar {
+    CODE_API_KEY = "CODE_EXECUTOR_API_KEY",
+    CODE_BASEURL = "CODE_EXECUTOR_BASEURL"
+}
+/**
+ * Message type identifiers used by LangChain's BaseMessage.getType().
+ * Use these constants instead of instanceof checks to avoid module mismatch issues
+ * when different copies of @langchain/core/messages are loaded.
+ */
+export declare enum MessageTypes {
+    HUMAN = "human",
+    AI = "ai",
+    SYSTEM = "system",
+    TOOL = "tool",
+    FUNCTION = "function",
+    GENERIC = "generic",
+    DEVELOPER = "developer",
+    REMOVE = "remove"
+}

package/dist/types/common/index.d.ts

@@ -0,0 +1 @@
+export * from './enum';

package/dist/types/events.d.ts

@@ -0,0 +1,31 @@
+import type { UsageMetadata, BaseMessageFields } from '@langchain/core/messages';
+import type { MultiAgentGraph, StandardGraph } from '@/graphs';
+import type { Logger } from 'winston';
+import type * as t from '@/types';
+export declare class HandlerRegistry {
+    private handlers;
+    register(eventType: string, handler: t.EventHandler): void;
+    getHandler(eventType: string): t.EventHandler | undefined;
+}
+export declare class ModelEndHandler implements t.EventHandler {
+    collectedUsage?: UsageMetadata[];
+    constructor(collectedUsage?: UsageMetadata[]);
+    handle(event: string, data: t.ModelEndData, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): Promise<void>;
+}
+export declare class ToolEndHandler implements t.EventHandler {
+    private callback?;
+    private logger?;
+    private omitOutput?;
+    constructor(callback?: t.ToolEndCallback, logger?: Logger, omitOutput?: (name?: string) => boolean);
+    handle(event: string, data: t.StreamEventData | undefined, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): Promise<void>;
+}
+export declare class TestLLMStreamHandler implements t.EventHandler {
+    handle(event: string, data: t.StreamEventData | undefined): void;
+}
+export declare class TestChatStreamHandler implements t.EventHandler {
+    handle(event: string, data: t.StreamEventData | undefined): void;
+}
+export declare class LLMStreamHandler implements t.EventHandler {
+    handle(event: string, data: t.StreamEventData | undefined, metadata?: Record<string, unknown>): void;
+}
+export declare const createMetadataAggregator: (_collected?: Record<string, NonNullable<BaseMessageFields["response_metadata"]>>[]) => t.MetadataAggregatorResult;