@illuma-ai/agents 1.0.98 → 1.1.1

package/src/utils/run.ts

@@ -1,108 +1,108 @@
-import { CallbackManagerForChainRun } from '@langchain/core/callbacks/manager';
-import {
-  mergeConfigs,
-  patchConfig,
-  Runnable,
-  RunnableConfig,
-} from '@langchain/core/runnables';
-import { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';
-
-/**
- * Delays the execution for a specified number of milliseconds.
- *
- * @param {number} ms - The number of milliseconds to delay.
- * @return {Promise<void>} A promise that resolves after the specified delay.
- */
-export function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export interface RunnableCallableArgs extends Partial<any> {
-  name?: string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  func: (...args: any[]) => any;
-  tags?: string[];
-  trace?: boolean;
-  recurse?: boolean;
-}
-
-export class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {
-  lc_namespace: string[] = ['langgraph'];
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  func: (...args: any[]) => any;
-
-  tags?: string[];
-
-  config?: RunnableConfig;
-
-  trace: boolean = true;
-
-  recurse: boolean = true;
-
-  constructor(fields: RunnableCallableArgs) {
-    super();
-    this.name = fields.name ?? fields.func.name;
-    this.func = fields.func;
-    this.config = fields.tags ? { tags: fields.tags } : undefined;
-    this.trace = fields.trace ?? this.trace;
-    this.recurse = fields.recurse ?? this.recurse;
-  }
-
-  protected async _tracedInvoke(
-    input: I,
-    config?: Partial<RunnableConfig>,
-    runManager?: CallbackManagerForChainRun
-  ): Promise<O> {
-    return new Promise<O>((resolve, reject) => {
-      // Defensive check: ensure runManager has getChild method before calling
-      const childCallbacks =
-        typeof runManager?.getChild === 'function'
-          ? runManager.getChild()
-          : undefined;
-      let childConfig: Partial<RunnableConfig> | null = patchConfig(config, {
-        callbacks: childCallbacks,
-      });
-      void AsyncLocalStorageProviderSingleton.runWithConfig(
-        childConfig,
-        async () => {
-          try {
-            const output = await this.func(input, childConfig);
-            childConfig = null;
-            resolve(output);
-          } catch (e) {
-            childConfig = null;
-            reject(e);
-          }
-        }
-      );
-    });
-  }
-
-  async invoke(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    input: any,
-    options?: Partial<RunnableConfig> | undefined
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ): Promise<any> {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let returnValue: any;
-
-    if (this.trace) {
-      returnValue = await this._callWithConfig(
-        this._tracedInvoke,
-        input,
-        mergeConfigs(this.config, options)
-      );
-    } else {
-      returnValue = await this.func(input, mergeConfigs(this.config, options));
-    }
-
-    if (Runnable.isRunnable(returnValue) && this.recurse) {
-      return await returnValue.invoke(input, options);
-    }
-
-    return returnValue;
-  }
-}
+import { CallbackManagerForChainRun } from '@langchain/core/callbacks/manager';
+import {
+  mergeConfigs,
+  patchConfig,
+  Runnable,
+  RunnableConfig,
+} from '@langchain/core/runnables';
+import { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';
+
+/**
+ * Delays the execution for a specified number of milliseconds.
+ *
+ * @param {number} ms - The number of milliseconds to delay.
+ * @return {Promise<void>} A promise that resolves after the specified delay.
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface RunnableCallableArgs extends Partial<any> {
+  name?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  func: (...args: any[]) => any;
+  tags?: string[];
+  trace?: boolean;
+  recurse?: boolean;
+}
+
+export class RunnableCallable<I = unknown, O = unknown> extends Runnable<I, O> {
+  lc_namespace: string[] = ['langgraph'];
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  func: (...args: any[]) => any;
+
+  tags?: string[];
+
+  config?: RunnableConfig;
+
+  trace: boolean = true;
+
+  recurse: boolean = true;
+
+  constructor(fields: RunnableCallableArgs) {
+    super();
+    this.name = fields.name ?? fields.func.name;
+    this.func = fields.func;
+    this.config = fields.tags ? { tags: fields.tags } : undefined;
+    this.trace = fields.trace ?? this.trace;
+    this.recurse = fields.recurse ?? this.recurse;
+  }
+
+  protected async _tracedInvoke(
+    input: I,
+    config?: Partial<RunnableConfig>,
+    runManager?: CallbackManagerForChainRun
+  ): Promise<O> {
+    return new Promise<O>((resolve, reject) => {
+      // Defensive check: ensure runManager has getChild method before calling
+      const childCallbacks =
+        typeof runManager?.getChild === 'function'
+          ? runManager.getChild()
+          : undefined;
+      let childConfig: Partial<RunnableConfig> | null = patchConfig(config, {
+        callbacks: childCallbacks,
+      });
+      void AsyncLocalStorageProviderSingleton.runWithConfig(
+        childConfig,
+        async () => {
+          try {
+            const output = await this.func(input, childConfig);
+            childConfig = null;
+            resolve(output);
+          } catch (e) {
+            childConfig = null;
+            reject(e);
+          }
+        }
+      );
+    });
+  }
+
+  async invoke(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input: any,
+    options?: Partial<RunnableConfig> | undefined
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<any> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let returnValue: any;
+
+    if (this.trace) {
+      returnValue = await this._callWithConfig(
+        this._tracedInvoke,
+        input,
+        mergeConfigs(this.config, options)
+      );
+    } else {
+      returnValue = await this.func(input, mergeConfigs(this.config, options));
+    }
+
+    if (Runnable.isRunnable(returnValue) && this.recurse) {
+      return await returnValue.invoke(input, options);
+    }
+
+    return returnValue;
+  }
+}

package/src/utils/tokens.ts

@@ -1,118 +1,118 @@
-import { Tokenizer } from 'ai-tokenizer';
-import type { BaseMessage } from '@langchain/core/messages';
-import { ContentTypes } from '@/common/enum';
-
-export type EncodingName = 'o200k_base' | 'claude';
-
-const tokenizers: Partial<Record<EncodingName, Tokenizer>> = {};
-
-async function getTokenizer(
-  encoding: EncodingName = 'o200k_base'
-): Promise<Tokenizer> {
-  const cached = tokenizers[encoding];
-  if (cached) {
-    return cached;
-  }
-  const data =
-    encoding === 'claude'
-      ? await import('ai-tokenizer/encoding/claude')
-      : await import('ai-tokenizer/encoding/o200k_base');
-  const instance = new Tokenizer(data);
-  tokenizers[encoding] = instance;
-  return instance;
-}
-
-export function encodingForModel(model: string): EncodingName {
-  if (model.toLowerCase().includes('claude')) {
-    return 'claude';
-  }
-  return 'o200k_base';
-}
-
-export function getTokenCountForMessage(
-  message: BaseMessage,
-  getTokenCount: (text: string) => number
-): number {
-  const tokensPerMessage = 3;
-
-  const processValue = (value: unknown): void => {
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        if (
-          !item ||
-          !item.type ||
-          item.type === ContentTypes.ERROR ||
-          item.type === ContentTypes.IMAGE_URL
-        ) {
-          continue;
-        }
-
-        if (item.type === ContentTypes.TOOL_CALL && item.tool_call != null) {
-          const toolName = item.tool_call?.name || '';
-          if (toolName != null && toolName && typeof toolName === 'string') {
-            numTokens += getTokenCount(toolName);
-          }
-
-          const args = item.tool_call?.args || '';
-          if (args != null && args && typeof args === 'string') {
-            numTokens += getTokenCount(args);
-          }
-
-          const output = item.tool_call?.output || '';
-          if (output != null && output && typeof output === 'string') {
-            numTokens += getTokenCount(output);
-          }
-          continue;
-        }
-
-        const nestedValue = item[item.type];
-
-        if (!nestedValue) {
-          continue;
-        }
-
-        processValue(nestedValue);
-      }
-    } else if (typeof value === 'string') {
-      numTokens += getTokenCount(value);
-    } else if (typeof value === 'number') {
-      numTokens += getTokenCount(value.toString());
-    } else if (typeof value === 'boolean') {
-      numTokens += getTokenCount(value.toString());
-    }
-  };
-
-  let numTokens = tokensPerMessage;
-  processValue(message.content);
-  return numTokens;
-}
-
-/**
- * Creates a token counter function using the specified encoding.
- * Lazily loads the encoding data on first use via dynamic import.
- */
-export const createTokenCounter = async (
-  encoding: EncodingName = 'o200k_base'
-): Promise<(message: BaseMessage) => number> => {
-  const tok = await getTokenizer(encoding);
-  const countTokens = (text: string): number => tok.count(text);
-  return (message: BaseMessage): number =>
-    getTokenCountForMessage(message, countTokens);
-};
-
-/** Utility to manage the token encoder lifecycle explicitly. */
-export const TokenEncoderManager = {
-  async initialize(): Promise<void> {
-    // No-op: ai-tokenizer is synchronously initialized from bundled data.
-  },
-
-  reset(): void {
-    for (const key of Object.keys(tokenizers)) {
-      delete tokenizers[key as EncodingName];
-    }
-  },
-
-  isInitialized(): boolean {
-    return Object.keys(tokenizers).length > 0;
-  },
-};
+import { Tokenizer } from 'ai-tokenizer';
+import type { BaseMessage } from '@langchain/core/messages';
+import { ContentTypes } from '@/common/enum';
+
+export type EncodingName = 'o200k_base' | 'claude';
+
+const tokenizers: Partial<Record<EncodingName, Tokenizer>> = {};
+
+async function getTokenizer(
+  encoding: EncodingName = 'o200k_base'
+): Promise<Tokenizer> {
+  const cached = tokenizers[encoding];
+  if (cached) {
+    return cached;
+  }
+  const data =
+    encoding === 'claude'
+      ? await import('ai-tokenizer/encoding/claude')
+      : await import('ai-tokenizer/encoding/o200k_base');
+  const instance = new Tokenizer(data);
+  tokenizers[encoding] = instance;
+  return instance;
+}
+
+export function encodingForModel(model: string): EncodingName {
+  if (model.toLowerCase().includes('claude')) {
+    return 'claude';
+  }
+  return 'o200k_base';
+}
+
+export function getTokenCountForMessage(
+  message: BaseMessage,
+  getTokenCount: (text: string) => number
+): number {
+  const tokensPerMessage = 3;
+
+  const processValue = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (
+          !item ||
+          !item.type ||
+          item.type === ContentTypes.ERROR ||
+          item.type === ContentTypes.IMAGE_URL
+        ) {
+          continue;
+        }
+
+        if (item.type === ContentTypes.TOOL_CALL && item.tool_call != null) {
+          const toolName = item.tool_call?.name || '';
+          if (toolName != null && toolName && typeof toolName === 'string') {
+            numTokens += getTokenCount(toolName);
+          }
+
+          const args = item.tool_call?.args || '';
+          if (args != null && args && typeof args === 'string') {
+            numTokens += getTokenCount(args);
+          }
+
+          const output = item.tool_call?.output || '';
+          if (output != null && output && typeof output === 'string') {
+            numTokens += getTokenCount(output);
+          }
+          continue;
+        }
+
+        const nestedValue = item[item.type];
+
+        if (!nestedValue) {
+          continue;
+        }
+
+        processValue(nestedValue);
+      }
+    } else if (typeof value === 'string') {
+      numTokens += getTokenCount(value);
+    } else if (typeof value === 'number') {
+      numTokens += getTokenCount(value.toString());
+    } else if (typeof value === 'boolean') {
+      numTokens += getTokenCount(value.toString());
+    }
+  };
+
+  let numTokens = tokensPerMessage;
+  processValue(message.content);
+  return numTokens;
+}
+
+/**
+ * Creates a token counter function using the specified encoding.
+ * Lazily loads the encoding data on first use via dynamic import.
+ */
+export const createTokenCounter = async (
+  encoding: EncodingName = 'o200k_base'
+): Promise<(message: BaseMessage) => number> => {
+  const tok = await getTokenizer(encoding);
+  const countTokens = (text: string): number => tok.count(text);
+  return (message: BaseMessage): number =>
+    getTokenCountForMessage(message, countTokens);
+};
+
+/** Utility to manage the token encoder lifecycle explicitly. */
+export const TokenEncoderManager = {
+  async initialize(): Promise<void> {
+    // No-op: ai-tokenizer is synchronously initialized from bundled data.
+  },
+
+  reset(): void {
+    for (const key of Object.keys(tokenizers)) {
+      delete tokenizers[key as EncodingName];
+    }
+  },
+
+  isInitialized(): boolean {
+    return Object.keys(tokenizers).length > 0;
+  },
+};

package/src/utils/toolDiscoveryCache.ts

@@ -0,0 +1,150 @@
+// src/utils/toolDiscoveryCache.ts
+import type { BaseMessage } from '@langchain/core/messages';
+import { Constants, MessageTypes } from '@/common';
+import { TOOL_DISCOVERY_CACHE_MAX_SIZE } from '@/common/constants';
+
+/**
+ * Cached tool discovery entry.
+ * Stores the tool name and the message index where it was discovered,
+ * enabling efficient lookups without re-parsing conversation history.
+ */
+export interface ToolDiscoveryEntry {
+  /** The tool name that was discovered */
+  toolName: string;
+  /** Message index in conversation history where discovery occurred */
+  discoveredAtIndex: number;
+}
+
+/**
+ * ToolDiscoveryCache provides a run-scoped cache of tool search results.
+ *
+ * Problem: Without caching, every LLM iteration re-parses the full message
+ * history via extractToolDiscoveries() to find tool_search results. In long
+ * conversations with many tool iterations, this is redundant work.
+ *
+ * Solution: Cache discovered tool names by message index. On each iteration,
+ * only scan messages AFTER the last scanned index. Already-seen discoveries
+ * are returned from cache instantly.
+ *
+ * This mirrors the pattern used by VS Code Copilot Chat where tool search
+ * results from prior turns are cached to avoid re-discovery.
+ *
+ * @example
+ * ```ts
+ * const cache = new ToolDiscoveryCache();
+ *
+ * // First call: scans all messages
+ * const newTools = cache.getNewDiscoveries(messages);
+ * // Returns: ['web_search', 'file_read']
+ *
+ * // Second call (3 new messages added): only scans new messages
+ * const moreTools = cache.getNewDiscoveries(messages);
+ * // Returns: ['code_exec'] (only newly discovered)
+ * ```
+ */
+export class ToolDiscoveryCache {
+  /** Set of all discovered tool names (deduped) */
+  private _discoveredTools: Set<string> = new Set();
+  /** Last message index that was scanned */
+  private _lastScannedIndex: number = -1;
+
+  /**
+   * Scan messages for new tool_search results since the last scan.
+   * Only processes messages after `_lastScannedIndex` to avoid redundant work.
+   *
+   * @param messages - Full conversation message array
+   * @returns Array of newly discovered tool names (not previously cached)
+   */
+  getNewDiscoveries(messages: BaseMessage[]): string[] {
+    if (messages.length === 0) {
+      return [];
+    }
+
+    const startIndex = this._lastScannedIndex + 1;
+    if (startIndex >= messages.length) {
+      return [];
+    }
+
+    const newDiscoveries: string[] = [];
+
+    for (let i = startIndex; i < messages.length; i++) {
+      const msg = messages[i];
+      if (msg.getType() !== MessageTypes.TOOL) {
+        continue;
+      }
+
+      // Check if this is a tool_search result
+      if ((msg as { name?: string }).name !== Constants.TOOL_SEARCH) {
+        continue;
+      }
+
+      // Extract tool references from artifact
+      const artifact = (msg as { artifact?: unknown }).artifact;
+      if (typeof artifact === 'object' && artifact != null) {
+        const refs = (
+          artifact as { tool_references?: Array<{ tool_name: string }> }
+        ).tool_references;
+        if (refs && refs.length > 0) {
+          for (const ref of refs) {
+            if (!this._discoveredTools.has(ref.tool_name)) {
+              // Enforce cache size limit
+              if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {
+                break;
+              }
+              this._discoveredTools.add(ref.tool_name);
+              newDiscoveries.push(ref.tool_name);
+            }
+          }
+        }
+      }
+    }
+
+    this._lastScannedIndex = messages.length - 1;
+    return newDiscoveries;
+  }
+
+  /**
+   * Returns all tool names discovered so far (across all scans).
+   */
+  getAllDiscoveredTools(): string[] {
+    return [...this._discoveredTools];
+  }
+
+  /**
+   * Check if a specific tool has been discovered.
+   */
+  has(toolName: string): boolean {
+    return this._discoveredTools.has(toolName);
+  }
+
+  /**
+   * Number of unique tools discovered.
+   */
+  get size(): number {
+    return this._discoveredTools.size;
+  }
+
+  /**
+   * Reset the cache (e.g., on graph reset).
+   */
+  reset(): void {
+    this._discoveredTools.clear();
+    this._lastScannedIndex = -1;
+  }
+
+  /**
+   * Seed the cache with previously known tool names (e.g., from prior conversation turns).
+   * Does not affect _lastScannedIndex — the next getNewDiscoveries call will still
+   * scan all messages from the beginning.
+   *
+   * @param toolNames - Tool names to pre-seed into the cache
+   */
+  seed(toolNames: string[]): void {
+    for (const name of toolNames) {
+      if (this._discoveredTools.size >= TOOL_DISCOVERY_CACHE_MAX_SIZE) {
+        break;
+      }
+      this._discoveredTools.add(name);
+    }
+  }
+}