illuma-agents 1.0.10 → 1.0.12

package/dist/cjs/run.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"run.cjs","sources":["../../src/run.ts"],"sourcesContent":["// src/run.ts\nimport './instrumentation';\nimport { CallbackHandler } from '@langfuse/langchain';\nimport { PromptTemplate } from '@langchain/core/prompts';\nimport { RunnableLambda } from '@langchain/core/runnables';\nimport { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';\nimport type {\n  MessageContentComplex,\n  BaseMessage,\n} from '@langchain/core/messages';\nimport type { StringPromptValue } from '@langchain/core/prompt_values';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type * as t from '@/types';\nimport {\n  createCompletionTitleRunnable,\n  createTitleRunnable,\n} from '@/utils/title';\nimport { GraphEvents, Callback, TitleMethod } from '@/common';\nimport { MultiAgentGraph } from '@/graphs/MultiAgentGraph';\nimport { createTokenCounter } from '@/utils/tokens';\nimport { StandardGraph } from '@/graphs/Graph';\nimport { HandlerRegistry } from '@/events';\nimport { isOpenAILike } from '@/utils/llm';\nimport { isPresent } from '@/utils/misc';\n\nexport const defaultOmitOptions = new Set([\n  'stream',\n  'thinking',\n  'streaming',\n  'maxTokens',\n  'clientOptions',\n  'thinkingConfig',\n  'thinkingBudget',\n  'includeThoughts',\n  'maxOutputTokens',\n  'additionalModelRequestFields',\n]);\n\nexport class Run<_T extends t.BaseGraphState> {\n  id: string;\n  private tokenCounter?: t.TokenCounter;\n  private handlerRegistry?: HandlerRegistry;\n  private indexTokenCountMap?: Record<string, number>;\n  graphRunnable?: t.CompiledStateWorkflow;\n  Graph: StandardGraph | MultiAgentGraph | undefined;\n  returnContent: boolean = false;\n\n  private constructor(config: Partial<t.RunConfig>) {\n    const runId = config.runId ?? '';\n    if (!runId) {\n      throw new Error('Run ID not provided');\n    }\n\n    this.id = runId;\n    this.tokenCounter = config.tokenCounter;\n    this.indexTokenCountMap = config.indexTokenCountMap;\n\n    const handlerRegistry = new HandlerRegistry();\n\n    if (config.customHandlers) {\n      for (const [eventType, handler] of Object.entries(\n        config.customHandlers\n      )) {\n        handlerRegistry.register(eventType, handler);\n      }\n    }\n\n    this.handlerRegistry = handlerRegistry;\n\n    if (!config.graphConfig) {\n      throw new Error('Graph config not provided');\n    }\n\n    /** Handle different graph types */\n    if (config.graphConfig.type === 'multi-agent') {\n      this.graphRunnable = this.createMultiAgentGraph(config.graphConfig);\n      if (this.Graph) {\n        this.Graph.handlerRegistry = handlerRegistry;\n      }\n    } else {\n      /** Default to legacy graph for 'standard' or undefined type */\n      this.graphRunnable = this.createLegacyGraph(config.graphConfig);\n      if (this.Graph) {\n        this.Graph.compileOptions =\n          config.graphConfig.compileOptions ?? this.Graph.compileOptions;\n        this.Graph.handlerRegistry = handlerRegistry;\n      }\n    }\n\n    this.returnContent = config.returnContent ?? false;\n  }\n\n  private createLegacyGraph(\n    config: t.LegacyGraphConfig | t.StandardGraphConfig\n  ): t.CompiledStateWorkflow {\n    let agentConfig: t.AgentInputs;\n    let signal: AbortSignal | undefined;\n\n    /** Check if this is a multi-agent style config (has agents array) */\n    if ('agents' in config && Array.isArray(config.agents)) {\n      if (config.agents.length === 0) {\n        throw new Error('At least one agent must be provided');\n      }\n      agentConfig = config.agents[0];\n      signal = config.signal;\n    } else {\n      /** Legacy path: build agent config from llmConfig */\n      const {\n        type: _type,\n        llmConfig,\n        signal: legacySignal,\n        tools = [],\n        ...agentInputs\n      } = config as t.LegacyGraphConfig;\n      const { provider, ...clientOptions } = llmConfig;\n\n      agentConfig = {\n        ...agentInputs,\n        tools,\n        provider,\n        clientOptions,\n        agentId: 'default',\n      };\n      signal = legacySignal;\n    }\n\n    const standardGraph = new StandardGraph({\n      signal,\n      runId: this.id,\n      agents: [agentConfig],\n      tokenCounter: this.tokenCounter,\n      indexTokenCountMap: this.indexTokenCountMap,\n    });\n    /** Propagate compile options from graph config */\n    standardGraph.compileOptions = config.compileOptions;\n    this.Graph = standardGraph;\n    return standardGraph.createWorkflow();\n  }\n\n  private createMultiAgentGraph(\n    config: t.MultiAgentGraphConfig\n  ): t.CompiledStateWorkflow {\n    const { agents, edges, compileOptions } = config;\n\n    const multiAgentGraph = new MultiAgentGraph({\n      runId: this.id,\n      agents,\n      edges,\n      tokenCounter: this.tokenCounter,\n      indexTokenCountMap: this.indexTokenCountMap,\n    });\n\n    if (compileOptions != null) {\n      multiAgentGraph.compileOptions = compileOptions;\n    }\n\n    this.Graph = multiAgentGraph;\n    return multiAgentGraph.createWorkflow();\n  }\n\n  static async create<T extends t.BaseGraphState>(\n    config: t.RunConfig\n  ): Promise<Run<T>> {\n    /** Create tokenCounter if indexTokenCountMap is provided but tokenCounter is not */\n    if (config.indexTokenCountMap && !config.tokenCounter) {\n      config.tokenCounter = await createTokenCounter();\n    }\n    return new Run<T>(config);\n  }\n\n  getRunMessages(): BaseMessage[] | undefined {\n    if (!this.Graph) {\n      throw new Error(\n        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n    return this.Graph.getRunMessages();\n  }\n\n  /**\n   * Creates a custom event callback handler that intercepts custom events\n   * and processes them through our handler registry instead of EventStreamCallbackHandler\n   */\n  private createCustomEventCallback() {\n    return async (\n      eventName: string,\n      data: unknown,\n      runId: string,\n      tags?: string[],\n      metadata?: Record<string, unknown>\n    ): Promise<void> => {\n      if (\n        (data as t.StreamEventData)['emitted'] === true &&\n        eventName === GraphEvents.CHAT_MODEL_STREAM\n      ) {\n        return;\n      }\n      const handler = this.handlerRegistry?.getHandler(eventName);\n      if (handler && this.Graph) {\n        return await handler.handle(\n          eventName,\n          data as\n            | t.StreamEventData\n            | t.ModelEndData\n            | t.RunStep\n            | t.RunStepDeltaEvent\n            | t.MessageDeltaEvent\n            | t.ReasoningDeltaEvent\n            | { result: t.ToolEndEvent },\n          metadata,\n          this.Graph\n        );\n      }\n    };\n  }\n\n  async processStream(\n    inputs: t.IState,\n    config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; run_id?: string },\n    streamOptions?: t.EventStreamOptions\n  ): Promise<MessageContentComplex[] | undefined> {\n    if (this.graphRunnable == null) {\n      throw new Error(\n        'Run not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n    if (!this.Graph) {\n      throw new Error(\n        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n\n    this.Graph.resetValues(streamOptions?.keepContent);\n\n    /** Custom event callback to intercept and handle custom events */\n    const customEventCallback = this.createCustomEventCallback();\n\n    const baseCallbacks = (config.callbacks as t.ProvidedCallbacks) ?? [];\n    const streamCallbacks = streamOptions?.callbacks\n      ? this.getCallbacks(streamOptions.callbacks)\n      : [];\n\n    config.callbacks = baseCallbacks.concat(streamCallbacks).concat({\n      [Callback.CUSTOM_EVENT]: customEventCallback,\n    });\n\n    if (\n      isPresent(process.env.LANGFUSE_SECRET_KEY) &&\n      isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&\n      isPresent(process.env.LANGFUSE_BASE_URL)\n    ) {\n      const userId = config.configurable?.user_id;\n      const sessionId = config.configurable?.thread_id;\n      const traceMetadata = {\n        messageId: this.id,\n        parentMessageId: config.configurable?.requestBody?.parentMessageId,\n      };\n      const handler = new CallbackHandler({\n        userId,\n        sessionId,\n        traceMetadata,\n      });\n      config.callbacks = (\n        (config.callbacks as t.ProvidedCallbacks) ?? []\n      ).concat([handler]);\n    }\n\n    if (!this.id) {\n      throw new Error('Run ID not provided');\n    }\n\n    config.run_id = this.id;\n    config.configurable = Object.assign(config.configurable ?? {}, {\n      run_id: this.id,\n    });\n\n    const stream = this.graphRunnable.streamEvents(inputs, config, {\n      raiseError: true,\n      /**\n       * Prevent EventStreamCallbackHandler from processing custom events.\n       * Custom events are already handled via our createCustomEventCallback()\n       * which routes them through the handlerRegistry.\n       * Without this flag, EventStreamCallbackHandler throws errors when\n       * custom events are dispatched for run IDs not in its internal map\n       * (due to timing issues in parallel execution or after run cleanup).\n       */\n      ignoreCustomEvent: true,\n    });\n\n    for await (const event of stream) {\n      const { data, metadata, ...info } = event;\n\n      const eventName: t.EventName = info.event;\n\n      // Debug: log tool-related events\n      if (eventName.includes('tool')) {\n        console.log('[AgentRun] Tool event received:', eventName, { \n          hasData: !!data, \n          dataKeys: data ? Object.keys(data) : [],\n          outputType: data?.output ? typeof data.output : 'none',\n        });\n      }\n\n      /** Skip custom events as they're handled by our callback */\n      if (eventName === GraphEvents.ON_CUSTOM_EVENT) {\n        continue;\n      }\n\n      const handler = this.handlerRegistry?.getHandler(eventName);\n      if (handler) {\n        await handler.handle(eventName, data, metadata, this.Graph);\n      }\n    }\n\n    if (this.returnContent) {\n      return this.Graph.getContentParts();\n    }\n  }\n\n  private createSystemCallback<K extends keyof t.ClientCallbacks>(\n    clientCallbacks: t.ClientCallbacks,\n    key: K\n  ): t.SystemCallbacks[K] {\n    return ((...args: unknown[]) => {\n      const clientCallback = clientCallbacks[key];\n      if (clientCallback && this.Graph) {\n        (clientCallback as (...args: unknown[]) => void)(this.Graph, ...args);\n      }\n    }) as t.SystemCallbacks[K];\n  }\n\n  getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks {\n    return {\n      [Callback.TOOL_ERROR]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_ERROR\n      ),\n      [Callback.TOOL_START]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_START\n      ),\n      [Callback.TOOL_END]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_END\n      ),\n    };\n  }\n\n  async generateTitle({\n    provider,\n    inputText,\n    contentParts,\n    titlePrompt,\n    clientOptions,\n    chainOptions,\n    skipLanguage,\n    titleMethod = TitleMethod.COMPLETION,\n    titlePromptTemplate,\n  }: t.RunTitleOptions): Promise<{ language?: string; title?: string }> {\n    if (\n      chainOptions != null &&\n      isPresent(process.env.LANGFUSE_SECRET_KEY) &&\n      isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&\n      isPresent(process.env.LANGFUSE_BASE_URL)\n    ) {\n      const userId = chainOptions.configurable?.user_id;\n      const sessionId = chainOptions.configurable?.thread_id;\n      const traceMetadata = {\n        messageId: 'title-' + this.id,\n      };\n      const handler = new CallbackHandler({\n        userId,\n        sessionId,\n        traceMetadata,\n      });\n      chainOptions.callbacks = (\n        (chainOptions.callbacks as t.ProvidedCallbacks) ?? []\n      ).concat([handler]);\n    }\n\n    const convoTemplate = PromptTemplate.fromTemplate(\n      titlePromptTemplate ?? 'User: {input}\\nAI: {output}'\n    );\n\n    const response = contentParts\n      .map((part) => {\n        if (part?.type === 'text') return part.text;\n        return '';\n      })\n      .join('\\n');\n\n    const model = this.Graph?.getNewModel({\n      provider,\n      clientOptions,\n    });\n    if (!model) {\n      return { language: '', title: '' };\n    }\n    if (\n      isOpenAILike(provider) &&\n      (model instanceof ChatOpenAI || model instanceof AzureChatOpenAI)\n    ) {\n      model.temperature = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.temperature as number;\n      model.topP = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.topP as number;\n      model.frequencyPenalty = (\n        clientOptions as t.OpenAIClientOptions | undefined\n      )?.frequencyPenalty as number;\n      model.presencePenalty = (\n        clientOptions as t.OpenAIClientOptions | undefined\n      )?.presencePenalty as number;\n      model.n = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.n as number;\n    }\n\n    const convoToTitleInput = new RunnableLambda({\n      func: (\n        promptValue: StringPromptValue\n      ): { convo: string; inputText: string; skipLanguage?: boolean } => ({\n        convo: promptValue.value,\n        inputText,\n        skipLanguage,\n      }),\n    }).withConfig({ runName: 'ConvoTransform' });\n\n    const titleChain =\n      titleMethod === TitleMethod.COMPLETION\n        ? await createCompletionTitleRunnable(model, titlePrompt)\n        : await createTitleRunnable(model, titlePrompt);\n\n    /** Pipes `convoTemplate` -> `transformer` -> `titleChain` */\n    const fullChain = convoTemplate\n      .withConfig({ runName: 'ConvoTemplate' })\n      .pipe(convoToTitleInput)\n      .pipe(titleChain)\n      .withConfig({ runName: 'TitleChain' });\n\n    const invokeConfig = Object.assign({}, chainOptions, {\n      run_id: this.id,\n      runId: this.id,\n    });\n\n    try {\n      return await fullChain.invoke(\n        { input: inputText, output: response },\n        invokeConfig\n      );\n    } catch (_e) {\n      // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments\n      // But preserve langfuse handler if it exists\n      const langfuseHandler = (\n        invokeConfig.callbacks as t.ProvidedCallbacks\n      )?.find((cb) => cb instanceof CallbackHandler);\n      const { callbacks: _cb, ...rest } = invokeConfig;\n      const safeConfig = Object.assign({}, rest, {\n        callbacks: langfuseHandler ? [langfuseHandler] : [],\n      });\n      return await fullChain.invoke(\n        { input: inputText, output: response },\n        safeConfig as Partial<RunnableConfig>\n      );\n    }\n  }\n}\n"],"names":["HandlerRegistry","StandardGraph","MultiAgentGraph","createTokenCounter","GraphEvents","Callback","isPresent","CallbackHandler","TitleMethod","PromptTemplate","isOpenAILike","ChatOpenAI","AzureChatOpenAI","RunnableLambda","createCompletionTitleRunnable","createTitleRunnable"],"mappings":"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"}
+{"version":3,"file":"run.cjs","sources":["../../src/run.ts"],"sourcesContent":["// src/run.ts\nimport './instrumentation';\nimport { CallbackHandler } from '@langfuse/langchain';\nimport { PromptTemplate } from '@langchain/core/prompts';\nimport { RunnableLambda } from '@langchain/core/runnables';\nimport { AzureChatOpenAI, ChatOpenAI } from '@langchain/openai';\nimport type {\n  MessageContentComplex,\n  BaseMessage,\n} from '@langchain/core/messages';\nimport type { StringPromptValue } from '@langchain/core/prompt_values';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type * as t from '@/types';\nimport {\n  createCompletionTitleRunnable,\n  createTitleRunnable,\n} from '@/utils/title';\nimport { GraphEvents, Callback, TitleMethod } from '@/common';\nimport { MultiAgentGraph } from '@/graphs/MultiAgentGraph';\nimport { createTokenCounter } from '@/utils/tokens';\nimport { StandardGraph } from '@/graphs/Graph';\nimport { HandlerRegistry } from '@/events';\nimport { isOpenAILike } from '@/utils/llm';\nimport { isPresent } from '@/utils/misc';\n\nexport const defaultOmitOptions = new Set([\n  'stream',\n  'thinking',\n  'streaming',\n  'maxTokens',\n  'clientOptions',\n  'thinkingConfig',\n  'thinkingBudget',\n  'includeThoughts',\n  'maxOutputTokens',\n  'additionalModelRequestFields',\n]);\n\nexport class Run<_T extends t.BaseGraphState> {\n  id: string;\n  private tokenCounter?: t.TokenCounter;\n  private handlerRegistry?: HandlerRegistry;\n  private indexTokenCountMap?: Record<string, number>;\n  graphRunnable?: t.CompiledStateWorkflow;\n  Graph: StandardGraph | MultiAgentGraph | undefined;\n  returnContent: boolean = false;\n\n  private constructor(config: Partial<t.RunConfig>) {\n    const runId = config.runId ?? '';\n    if (!runId) {\n      throw new Error('Run ID not provided');\n    }\n\n    this.id = runId;\n    this.tokenCounter = config.tokenCounter;\n    this.indexTokenCountMap = config.indexTokenCountMap;\n\n    const handlerRegistry = new HandlerRegistry();\n\n    if (config.customHandlers) {\n      for (const [eventType, handler] of Object.entries(\n        config.customHandlers\n      )) {\n        handlerRegistry.register(eventType, handler);\n      }\n    }\n\n    this.handlerRegistry = handlerRegistry;\n\n    if (!config.graphConfig) {\n      throw new Error('Graph config not provided');\n    }\n\n    /** Handle different graph types */\n    if (config.graphConfig.type === 'multi-agent') {\n      this.graphRunnable = this.createMultiAgentGraph(config.graphConfig);\n      if (this.Graph) {\n        this.Graph.handlerRegistry = handlerRegistry;\n      }\n    } else {\n      /** Default to legacy graph for 'standard' or undefined type */\n      this.graphRunnable = this.createLegacyGraph(config.graphConfig);\n      if (this.Graph) {\n        this.Graph.compileOptions =\n          config.graphConfig.compileOptions ?? this.Graph.compileOptions;\n        this.Graph.handlerRegistry = handlerRegistry;\n      }\n    }\n\n    this.returnContent = config.returnContent ?? false;\n  }\n\n  private createLegacyGraph(\n    config: t.LegacyGraphConfig | t.StandardGraphConfig\n  ): t.CompiledStateWorkflow {\n    let agentConfig: t.AgentInputs;\n    let signal: AbortSignal | undefined;\n\n    /** Check if this is a multi-agent style config (has agents array) */\n    if ('agents' in config && Array.isArray(config.agents)) {\n      if (config.agents.length === 0) {\n        throw new Error('At least one agent must be provided');\n      }\n      agentConfig = config.agents[0];\n      signal = config.signal;\n    } else {\n      /** Legacy path: build agent config from llmConfig */\n      const {\n        type: _type,\n        llmConfig,\n        signal: legacySignal,\n        tools = [],\n        ...agentInputs\n      } = config as t.LegacyGraphConfig;\n      const { provider, ...clientOptions } = llmConfig;\n\n      agentConfig = {\n        ...agentInputs,\n        tools,\n        provider,\n        clientOptions,\n        agentId: 'default',\n      };\n      signal = legacySignal;\n    }\n\n    const standardGraph = new StandardGraph({\n      signal,\n      runId: this.id,\n      agents: [agentConfig],\n      tokenCounter: this.tokenCounter,\n      indexTokenCountMap: this.indexTokenCountMap,\n    });\n    /** Propagate compile options from graph config */\n    standardGraph.compileOptions = config.compileOptions;\n    this.Graph = standardGraph;\n    return standardGraph.createWorkflow();\n  }\n\n  private createMultiAgentGraph(\n    config: t.MultiAgentGraphConfig\n  ): t.CompiledStateWorkflow {\n    const { agents, edges, compileOptions } = config;\n\n    const multiAgentGraph = new MultiAgentGraph({\n      runId: this.id,\n      agents,\n      edges,\n      tokenCounter: this.tokenCounter,\n      indexTokenCountMap: this.indexTokenCountMap,\n    });\n\n    if (compileOptions != null) {\n      multiAgentGraph.compileOptions = compileOptions;\n    }\n\n    this.Graph = multiAgentGraph;\n    return multiAgentGraph.createWorkflow();\n  }\n\n  static async create<T extends t.BaseGraphState>(\n    config: t.RunConfig\n  ): Promise<Run<T>> {\n    /** Create tokenCounter if indexTokenCountMap is provided but tokenCounter is not */\n    if (config.indexTokenCountMap && !config.tokenCounter) {\n      config.tokenCounter = await createTokenCounter();\n    }\n    return new Run<T>(config);\n  }\n\n  getRunMessages(): BaseMessage[] | undefined {\n    if (!this.Graph) {\n      throw new Error(\n        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n    return this.Graph.getRunMessages();\n  }\n\n  /**\n   * Creates a custom event callback handler that intercepts custom events\n   * and processes them through our handler registry instead of EventStreamCallbackHandler\n   */\n  private createCustomEventCallback() {\n    return async (\n      eventName: string,\n      data: unknown,\n      runId: string,\n      tags?: string[],\n      metadata?: Record<string, unknown>\n    ): Promise<void> => {\n      if (\n        (data as t.StreamEventData)['emitted'] === true &&\n        eventName === GraphEvents.CHAT_MODEL_STREAM\n      ) {\n        return;\n      }\n      const handler = this.handlerRegistry?.getHandler(eventName);\n      if (handler && this.Graph) {\n        return await handler.handle(\n          eventName,\n          data as\n            | t.StreamEventData\n            | t.ModelEndData\n            | t.RunStep\n            | t.RunStepDeltaEvent\n            | t.MessageDeltaEvent\n            | t.ReasoningDeltaEvent\n            | { result: t.ToolEndEvent },\n          metadata,\n          this.Graph\n        );\n      }\n    };\n  }\n\n  async processStream(\n    inputs: t.IState,\n    config: Partial<RunnableConfig> & { version: 'v1' | 'v2'; run_id?: string },\n    streamOptions?: t.EventStreamOptions\n  ): Promise<MessageContentComplex[] | undefined> {\n    if (this.graphRunnable == null) {\n      throw new Error(\n        'Run not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n    if (!this.Graph) {\n      throw new Error(\n        'Graph not initialized. Make sure to use Run.create() to instantiate the Run.'\n      );\n    }\n\n    this.Graph.resetValues(streamOptions?.keepContent);\n\n    /** Custom event callback to intercept and handle custom events */\n    const customEventCallback = this.createCustomEventCallback();\n\n    const baseCallbacks = (config.callbacks as t.ProvidedCallbacks) ?? [];\n    const streamCallbacks = streamOptions?.callbacks\n      ? this.getCallbacks(streamOptions.callbacks)\n      : [];\n\n    config.callbacks = baseCallbacks.concat(streamCallbacks).concat({\n      [Callback.CUSTOM_EVENT]: customEventCallback,\n    });\n\n    if (\n      isPresent(process.env.LANGFUSE_SECRET_KEY) &&\n      isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&\n      isPresent(process.env.LANGFUSE_BASE_URL)\n    ) {\n      const userId = config.configurable?.user_id;\n      const sessionId = config.configurable?.thread_id;\n      const traceMetadata = {\n        messageId: this.id,\n        parentMessageId: config.configurable?.requestBody?.parentMessageId,\n      };\n      const handler = new CallbackHandler({\n        userId,\n        sessionId,\n        traceMetadata,\n      });\n      config.callbacks = (\n        (config.callbacks as t.ProvidedCallbacks) ?? []\n      ).concat([handler]);\n    }\n\n    if (!this.id) {\n      throw new Error('Run ID not provided');\n    }\n\n    config.run_id = this.id;\n    config.configurable = Object.assign(config.configurable ?? {}, {\n      run_id: this.id,\n    });\n\n    const stream = this.graphRunnable.streamEvents(inputs, config, {\n      raiseError: true,\n      /**\n       * Prevent EventStreamCallbackHandler from processing custom events.\n       * Custom events are already handled via our createCustomEventCallback()\n       * which routes them through the handlerRegistry.\n       * Without this flag, EventStreamCallbackHandler throws errors when\n       * custom events are dispatched for run IDs not in its internal map\n       * (due to timing issues in parallel execution or after run cleanup).\n       */\n      ignoreCustomEvent: true,\n    });\n\n    for await (const event of stream) {\n      const { data, metadata, ...info } = event;\n\n      const eventName: t.EventName = info.event;\n\n      /** Skip custom events as they're handled by our callback */\n      if (eventName === GraphEvents.ON_CUSTOM_EVENT) {\n        continue;\n      }\n\n      const handler = this.handlerRegistry?.getHandler(eventName);\n      if (handler) {\n        await handler.handle(eventName, data, metadata, this.Graph);\n      }\n    }\n\n    if (this.returnContent) {\n      return this.Graph.getContentParts();\n    }\n  }\n\n  private createSystemCallback<K extends keyof t.ClientCallbacks>(\n    clientCallbacks: t.ClientCallbacks,\n    key: K\n  ): t.SystemCallbacks[K] {\n    return ((...args: unknown[]) => {\n      const clientCallback = clientCallbacks[key];\n      if (clientCallback && this.Graph) {\n        (clientCallback as (...args: unknown[]) => void)(this.Graph, ...args);\n      }\n    }) as t.SystemCallbacks[K];\n  }\n\n  getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks {\n    return {\n      [Callback.TOOL_ERROR]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_ERROR\n      ),\n      [Callback.TOOL_START]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_START\n      ),\n      [Callback.TOOL_END]: this.createSystemCallback(\n        clientCallbacks,\n        Callback.TOOL_END\n      ),\n    };\n  }\n\n  async generateTitle({\n    provider,\n    inputText,\n    contentParts,\n    titlePrompt,\n    clientOptions,\n    chainOptions,\n    skipLanguage,\n    titleMethod = TitleMethod.COMPLETION,\n    titlePromptTemplate,\n  }: t.RunTitleOptions): Promise<{ language?: string; title?: string }> {\n    if (\n      chainOptions != null &&\n      isPresent(process.env.LANGFUSE_SECRET_KEY) &&\n      isPresent(process.env.LANGFUSE_PUBLIC_KEY) &&\n      isPresent(process.env.LANGFUSE_BASE_URL)\n    ) {\n      const userId = chainOptions.configurable?.user_id;\n      const sessionId = chainOptions.configurable?.thread_id;\n      const traceMetadata = {\n        messageId: 'title-' + this.id,\n      };\n      const handler = new CallbackHandler({\n        userId,\n        sessionId,\n        traceMetadata,\n      });\n      chainOptions.callbacks = (\n        (chainOptions.callbacks as t.ProvidedCallbacks) ?? []\n      ).concat([handler]);\n    }\n\n    const convoTemplate = PromptTemplate.fromTemplate(\n      titlePromptTemplate ?? 'User: {input}\\nAI: {output}'\n    );\n\n    const response = contentParts\n      .map((part) => {\n        if (part?.type === 'text') return part.text;\n        return '';\n      })\n      .join('\\n');\n\n    const model = this.Graph?.getNewModel({\n      provider,\n      clientOptions,\n    });\n    if (!model) {\n      return { language: '', title: '' };\n    }\n    if (\n      isOpenAILike(provider) &&\n      (model instanceof ChatOpenAI || model instanceof AzureChatOpenAI)\n    ) {\n      model.temperature = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.temperature as number;\n      model.topP = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.topP as number;\n      model.frequencyPenalty = (\n        clientOptions as t.OpenAIClientOptions | undefined\n      )?.frequencyPenalty as number;\n      model.presencePenalty = (\n        clientOptions as t.OpenAIClientOptions | undefined\n      )?.presencePenalty as number;\n      model.n = (clientOptions as t.OpenAIClientOptions | undefined)\n        ?.n as number;\n    }\n\n    const convoToTitleInput = new RunnableLambda({\n      func: (\n        promptValue: StringPromptValue\n      ): { convo: string; inputText: string; skipLanguage?: boolean } => ({\n        convo: promptValue.value,\n        inputText,\n        skipLanguage,\n      }),\n    }).withConfig({ runName: 'ConvoTransform' });\n\n    const titleChain =\n      titleMethod === TitleMethod.COMPLETION\n        ? await createCompletionTitleRunnable(model, titlePrompt)\n        : await createTitleRunnable(model, titlePrompt);\n\n    /** Pipes `convoTemplate` -> `transformer` -> `titleChain` */\n    const fullChain = convoTemplate\n      .withConfig({ runName: 'ConvoTemplate' })\n      .pipe(convoToTitleInput)\n      .pipe(titleChain)\n      .withConfig({ runName: 'TitleChain' });\n\n    const invokeConfig = Object.assign({}, chainOptions, {\n      run_id: this.id,\n      runId: this.id,\n    });\n\n    try {\n      return await fullChain.invoke(\n        { input: inputText, output: response },\n        invokeConfig\n      );\n    } catch (_e) {\n      // Fallback: strip callbacks to avoid EventStream tracer errors in certain environments\n      // But preserve langfuse handler if it exists\n      const langfuseHandler = (\n        invokeConfig.callbacks as t.ProvidedCallbacks\n      )?.find((cb) => cb instanceof CallbackHandler);\n      const { callbacks: _cb, ...rest } = invokeConfig;\n      const safeConfig = Object.assign({}, rest, {\n        callbacks: langfuseHandler ? [langfuseHandler] : [],\n      });\n      return await fullChain.invoke(\n        { input: inputText, output: response },\n        safeConfig as Partial<RunnableConfig>\n      );\n    }\n  }\n}\n"],"names":["HandlerRegistry","StandardGraph","MultiAgentGraph","createTokenCounter","GraphEvents","Callback","isPresent","CallbackHandler","TitleMethod","PromptTemplate","isOpenAILike","ChatOpenAI","AzureChatOpenAI","RunnableLambda","createCompletionTitleRunnable","createTitleRunnable"],"mappings":"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"}

package/dist/cjs/tools/CodeExecutor.cjs

@@ -72,6 +72,10 @@ function createCodeExecutionTool(params = {}) {
     const description = `
 Runs code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
 
+⚠️ DO NOT USE FOR: Creating dashboards, UI components, React components, HTML pages, charts, or visualizations. These should be created as artifacts directly in your response using :::artifact syntax.
+
+✅ USE FOR: Data processing, calculations, file generation (CSV, Excel, PowerPoint, PDF), matplotlib plots, running algorithms, or computational tasks.
+
 Usage:
 - No network access available.
 - Generated files are automatically delivered; **DO NOT** provide download links.

package/dist/cjs/tools/CodeExecutor.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"CodeExecutor.cjs","sources":["../../../src/tools/CodeExecutor.ts"],"sourcesContent":["import { z } from 'zod';\nimport { config } from 'dotenv';\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport type * as t from '@/types';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\nexport const imageExtRegex = /\\.(jpg|jpeg|png|gif|webp)$/i;\nexport const getCodeBaseURL = (): string =>\n  getEnvironmentVariable(EnvVar.CODE_BASEURL) ??\n  Constants.OFFICIAL_CODE_BASEURL;\n\nconst imageMessage = 'Image is already displayed to the user';\nconst otherMessage = 'File is already downloaded by the user';\nconst accessMessage =\n  'Note: Files are READ-ONLY. Save changes to NEW filenames. To access these files in future executions, provide the `session_id` as a parameter (not in your code).';\nconst emptyOutputMessage =\n  'stdout: Empty. Ensure you\\'re writing output explicitly.\\n';\n\nconst CodeExecutionToolSchema = z.object({\n  lang: z\n    .enum([\n      'py',\n      'js',\n      'ts',\n      'c',\n      'cpp',\n      'java',\n      'php',\n      'rs',\n      'go',\n      'd',\n      'f90',\n      'r',\n    ])\n    .describe('The programming language or runtime to execute the code in.'),\n  code: z.string()\n    .describe(`The complete, self-contained code to execute, without any truncation or minimization.\n- The environment is stateless; variables and imports don't persist between executions.\n- When using \\`session_id\\`: Don't hardcode it in \\`code\\`, and write file modifications to NEW filenames (files are READ-ONLY).\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- py: This is not a Jupyter notebook environment. Use \\`print()\\` for all outputs.\n- py: Matplotlib: Use \\`plt.savefig()\\` to save plots as files.\n- js: use the \\`console\\` or \\`process\\` methods for all outputs.\n- r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).\n- Other languages: use appropriate output functions.`),\n  session_id: z\n    .string()\n    .optional()\n    .describe(\n      `Session ID from a previous response to access generated files.\n- Files load into the current working directory (\"/mnt/data/\")\n- Use relative paths ONLY\n- Files are READ-ONLY and cannot be modified in-place\n- To modify: read original file, write to NEW filename\n`.trim()\n    ),\n  args: z\n    .array(z.string())\n    .optional()\n    .describe(\n      'Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.'\n    ),\n});\n\nconst baseEndpoint = getCodeBaseURL();\nconst EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\nfunction createCodeExecutionTool(\n  params: t.CodeExecutionToolParams = {}\n): DynamicStructuredTool<typeof CodeExecutionToolSchema> {\n  const apiKey =\n    params[EnvVar.CODE_API_KEY] ??\n    params.apiKey ??\n    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??\n    '';\n  if (!apiKey) {\n    throw new Error('No API key provided for code execution tool.');\n  }\n\n  const description = `\nRuns code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.\n\nUsage:\n- No network access available.\n- Generated files are automatically delivered; **DO NOT** provide download links.\n- NEVER use this tool to execute malicious code.\n`.trim();\n\n  return tool<typeof CodeExecutionToolSchema>(\n    async ({ lang, code, session_id, ...rest }) => {\n      const postData = {\n        lang,\n        code,\n        ...rest,\n        ...params,\n      };\n\n      if (session_id != null && session_id.length > 0) {\n        try {\n          const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;\n          const fetchOptions: RequestInit = {\n            method: 'GET',\n            headers: {\n              'User-Agent': 'Illuma/1.0',\n              'X-API-Key': apiKey,\n            },\n          };\n\n          if (process.env.PROXY != null && process.env.PROXY !== '') {\n            fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n          }\n\n          const response = await fetch(filesEndpoint, fetchOptions);\n          if (!response.ok) {\n            throw new Error(\n              `Failed to fetch files for session: ${response.status}`\n            );\n          }\n\n          const files = await response.json();\n          if (Array.isArray(files) && files.length > 0) {\n            const fileReferences: t.CodeEnvFile[] = files.map((file) => {\n              // Extract the ID from the file name (part after session ID prefix and before extension)\n              const nameParts = file.name.split('/');\n              const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';\n\n              return {\n                session_id,\n                id,\n                name: file.metadata['original-filename'],\n              };\n            });\n\n            if (!postData.files) {\n              postData.files = fileReferences;\n            } else if (Array.isArray(postData.files)) {\n              postData.files = [...postData.files, ...fileReferences];\n            }\n          }\n        } catch {\n          // eslint-disable-next-line no-console\n          console.warn(`Failed to fetch files for session: ${session_id}`);\n        }\n      }\n\n      try {\n        const fetchOptions: RequestInit = {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'User-Agent': 'Illuma/1.0',\n            'X-API-Key': apiKey,\n          },\n          body: JSON.stringify(postData),\n        };\n\n        if (process.env.PROXY != null && process.env.PROXY !== '') {\n          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n        }\n        const response = await fetch(EXEC_ENDPOINT, fetchOptions);\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const result: t.ExecuteResult = await response.json();\n        let formattedOutput = '';\n        if (result.stdout) {\n          formattedOutput += `stdout:\\n${result.stdout}\\n`;\n        } else {\n          formattedOutput += emptyOutputMessage;\n        }\n        if (result.stderr) formattedOutput += `stderr:\\n${result.stderr}\\n`;\n        if (result.files && result.files.length > 0) {\n          formattedOutput += 'Generated files:\\n';\n\n          const fileCount = result.files.length;\n          for (let i = 0; i < fileCount; i++) {\n            const file = result.files[i];\n            const isImage = imageExtRegex.test(file.name);\n            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;\n\n            if (i < fileCount - 1) {\n              formattedOutput += fileCount <= 3 ? ', ' : ',\\n';\n            }\n          }\n\n          formattedOutput += `\\nsession_id: ${result.session_id}\\n\\n${accessMessage}`;\n          return [\n            formattedOutput.trim(),\n            {\n              session_id: result.session_id,\n              files: result.files,\n            },\n          ];\n        }\n\n        return [formattedOutput.trim(), { session_id: result.session_id }];\n      } catch (error) {\n        throw new Error(\n          `Execution error:\\n\\n${(error as Error | undefined)?.message}`\n        );\n      }\n    },\n    {\n      name: Constants.EXECUTE_CODE,\n      description,\n      schema: CodeExecutionToolSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport { createCodeExecutionTool };\n"],"names":["config","getEnvironmentVariable","EnvVar","Constants","z","tool","HttpsProxyAgent"],"mappings":";;;;;;;;;;AASAA,aAAM,EAAE;AAED,MAAM,aAAa,GAAG;AACtB,MAAM,cAAc,GAAG,MAC5BC,0BAAsB,CAACC,YAAM,CAAC,YAAY,CAAC;IAC3CC,eAAS,CAAC;AAEZ,MAAM,YAAY,GAAG,wCAAwC;AAC7D,MAAM,YAAY,GAAG,wCAAwC;AAC7D,MAAM,aAAa,GACjB,mKAAmK;AACrK,MAAM,kBAAkB,GACtB,4DAA4D;AAE9D,MAAM,uBAAuB,GAAGC,KAAC,CAAC,MAAM,CAAC;AACvC,IAAA,IAAI,EAAEA;AACH,SAAA,IAAI,CAAC;QACJ,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,GAAG;QACH,KAAK;QACL,MAAM;QACN,KAAK;QACL,IAAI;QACJ,IAAI;QACJ,GAAG;QACH,KAAK;QACL,GAAG;KACJ;SACA,QAAQ,CAAC,6DAA6D,CAAC;AAC1E,IAAA,IAAI,EAAEA,KAAC,CAAC,MAAM;AACX,SAAA,QAAQ,CAAC,CAAA;;;;;;;;;;qDAUuC,CAAC;AACpD,IAAA,UAAU,EAAEA;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;AACR,SAAA,QAAQ,CACP,CAAA;;;;;CAKL,CAAC,IAAI,EAAE,CACH;AACH,IAAA,IAAI,EAAEA;AACH,SAAA,KAAK,CAACA,KAAC,CAAC,MAAM,EAAE;AAChB,SAAA,QAAQ;SACR,QAAQ,CACP,iIAAiI,CAClI;AACJ,CAAA,CAAC;AAEF,MAAM,YAAY,GAAG,cAAc,EAAE;AACrC,MAAM,aAAa,GAAG,CAAG,EAAA,YAAY,OAAO;AAE5C,SAAS,uBAAuB,CAC9B,MAAA,GAAoC,EAAE,EAAA;AAEtC,IAAA,MAAM,MAAM,GACV,MAAM,CAACF,YAAM,CAAC,YAAY,CAAC;AAC3B,QAAA,MAAM,CAAC,MAAM;AACb,QAAAD,0BAAsB,CAACC,YAAM,CAAC,YAAY,CAAC;AAC3C,QAAA,EAAE;IACJ,IAAI,CAAC,MAAM,EAAE;AACX,QAAA,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC;;AAGjE,IAAA,MAAM,WAAW,GAAG;;;;;;;CAOrB,CAAC,IAAI,EAAE;AAEN,IAAA,OAAOG,UAAI,CACT,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,KAAI;AAC5C,QAAA,MAAM,QAAQ,GAAG;YACf,IAAI;YACJ,IAAI;AACJ,YAAA,GAAG,IAAI;AACP,YAAA,GAAG,MAAM;SACV;QAED,IAAI,UAAU,IAAI,IAAI,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE;AAC/C,YAAA,IAAI;AACF,gBAAA,MAAM,aAAa,GAAG,CAAA,EAAG,YAAY,CAAU,OAAA,EAAA,UAAU,cAAc;AACvE,gBAAA,MAAM,YAAY,GAAgB;AAChC,oBAAA,MAAM,EAAE,KAAK;AACb,oBAAA,OAAO,EAAE;AACP,wBAAA,YAAY,EAAE,YAAY;AAC1B,wBAAA,WAAW,EAAE,MAAM;AACpB,qBAAA;iBACF;AAED,gBAAA,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,EAAE;AACzD,oBAAA,YAAY,CAAC,KAAK,GAAG,IAAIC,+BAAe,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;;gBAG7D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,aAAa,EAAE,YAAY,CAAC;AACzD,gBAAA,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE;oBAChB,MAAM,IAAI,KAAK,CACb,CAAA,mCAAA,EAAsC,QAAQ,CAAC,MAAM,CAAE,CAAA,CACxD;;AAGH,gBAAA,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE;AACnC,gBAAA,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE;oBAC5C,MAAM,cAAc,GAAoB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,KAAI;;wBAEzD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;wBACtC,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE;wBAEjE,OAAO;4BACL,UAAU;4BACV,EAAE;AACF,4BAAA,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC;yBACzC;AACH,qBAAC,CAAC;AAEF,oBAAA,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;AACnB,wBAAA,QAAQ,CAAC,KAAK,GAAG,cAAc;;yBAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE;AACxC,wBAAA,QAAQ,CAAC,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,EAAE,GAAG,cAAc,CAAC;;;;AAG3D,YAAA,MAAM;;AAEN,gBAAA,OAAO,CAAC,IAAI,CAAC,sCAAsC,UAAU,CAAA,CAAE,CAAC;;;AAIpE,QAAA,IAAI;AACF,YAAA,MAAM,YAAY,GAAgB;AAChC,gBAAA,MAAM,EAAE,MAAM;AACd,gBAAA,OAAO,EAAE;AACP,oBAAA,cAAc,EAAE,kBAAkB;AAClC,oBAAA,YAAY,EAAE,YAAY;AAC1B,oBAAA,WAAW,EAAE,MAAM;AACpB,iBAAA;AACD,gBAAA,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;aAC/B;AAED,YAAA,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,EAAE,EAAE;AACzD,gBAAA,YAAY,CAAC,KAAK,GAAG,IAAIA,+BAAe,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC;;YAE7D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,aAAa,EAAE,YAAY,CAAC;AACzD,YAAA,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE;gBAChB,MAAM,IAAI,KAAK,CAAC,CAAA,oBAAA,EAAuB,QAAQ,CAAC,MAAM,CAAE,CAAA,CAAC;;AAG3D,YAAA,MAAM,MAAM,GAAoB,MAAM,QAAQ,CAAC,IAAI,EAAE;YACrD,IAAI,eAAe,GAAG,EAAE;AACxB,YAAA,IAAI,MAAM,CAAC,MAAM,EAAE;AACjB,gBAAA,eAAe,IAAI,CAAY,SAAA,EAAA,MAAM,CAAC,MAAM,IAAI;;iBAC3C;gBACL,eAAe,IAAI,kBAAkB;;YAEvC,IAAI,MAAM,CAAC,MAAM;AAAE,gBAAA,eAAe,IAAI,CAAY,SAAA,EAAA,MAAM,CAAC,MAAM,IAAI;AACnE,YAAA,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE;gBAC3C,eAAe,IAAI,oBAAoB;AAEvC,gBAAA,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM;AACrC,gBAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE;oBAClC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;oBAC5B,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AAC7C,oBAAA,eAAe,IAAI,CAAe,YAAA,EAAA,IAAI,CAAC,IAAI,MAAM,OAAO,GAAG,YAAY,GAAG,YAAY,EAAE;AAExF,oBAAA,IAAI,CAAC,GAAG,SAAS,GAAG,CAAC,EAAE;AACrB,wBAAA,eAAe,IAAI,SAAS,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK;;;gBAIpD,eAAe,IAAI,iBAAiB,MAAM,CAAC,UAAU,CAAO,IAAA,EAAA,aAAa,EAAE;gBAC3E,OAAO;oBACL,eAAe,CAAC,IAAI,EAAE;AACtB,oBAAA;wBACE,UAAU,EAAE,MAAM,CAAC,UAAU;wBAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;AACpB,qBAAA;iBACF;;AAGH,YAAA,OAAO,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;;QAClE,OAAO,KAAK,EAAE;YACd,MAAM,IAAI,KAAK,CACb,CAAA,oBAAA,EAAwB,KAA2B,EAAE,OAAO,CAAE,CAAA,CAC/D;;AAEL,KAAC,EACD;QACE,IAAI,EAAEH,eAAS,CAAC,YAAY;QAC5B,WAAW;AACX,QAAA,MAAM,EAAE,uBAAuB;QAC/B,cAAc,EAAEA,eAAS,CAAC,oBAAoB;AAC/C,KAAA,CACF;AACH;;;;;;"}
+{"version":3,"file":"CodeExecutor.cjs","sources":["../../../src/tools/CodeExecutor.ts"],"sourcesContent":["import { z } from 'zod';\nimport { config } from 'dotenv';\nimport fetch, { RequestInit } from 'node-fetch';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport type * as t from '@/types';\nimport { EnvVar, Constants } from '@/common';\n\nconfig();\n\nexport const imageExtRegex = /\\.(jpg|jpeg|png|gif|webp)$/i;\nexport const getCodeBaseURL = (): string =>\n  getEnvironmentVariable(EnvVar.CODE_BASEURL) ??\n  Constants.OFFICIAL_CODE_BASEURL;\n\nconst imageMessage = 'Image is already displayed to the user';\nconst otherMessage = 'File is already downloaded by the user';\nconst accessMessage =\n  'Note: Files are READ-ONLY. Save changes to NEW filenames. To access these files in future executions, provide the `session_id` as a parameter (not in your code).';\nconst emptyOutputMessage =\n  'stdout: Empty. Ensure you\\'re writing output explicitly.\\n';\n\nconst CodeExecutionToolSchema = z.object({\n  lang: z\n    .enum([\n      'py',\n      'js',\n      'ts',\n      'c',\n      'cpp',\n      'java',\n      'php',\n      'rs',\n      'go',\n      'd',\n      'f90',\n      'r',\n    ])\n    .describe('The programming language or runtime to execute the code in.'),\n  code: z.string()\n    .describe(`The complete, self-contained code to execute, without any truncation or minimization.\n- The environment is stateless; variables and imports don't persist between executions.\n- When using \\`session_id\\`: Don't hardcode it in \\`code\\`, and write file modifications to NEW filenames (files are READ-ONLY).\n- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.\n- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.\n- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.\n- py: This is not a Jupyter notebook environment. Use \\`print()\\` for all outputs.\n- py: Matplotlib: Use \\`plt.savefig()\\` to save plots as files.\n- js: use the \\`console\\` or \\`process\\` methods for all outputs.\n- r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).\n- Other languages: use appropriate output functions.`),\n  session_id: z\n    .string()\n    .optional()\n    .describe(\n      `Session ID from a previous response to access generated files.\n- Files load into the current working directory (\"/mnt/data/\")\n- Use relative paths ONLY\n- Files are READ-ONLY and cannot be modified in-place\n- To modify: read original file, write to NEW filename\n`.trim()\n    ),\n  args: z\n    .array(z.string())\n    .optional()\n    .describe(\n      'Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.'\n    ),\n});\n\nconst baseEndpoint = getCodeBaseURL();\nconst EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\nfunction createCodeExecutionTool(\n  params: t.CodeExecutionToolParams = {}\n): DynamicStructuredTool<typeof CodeExecutionToolSchema> {\n  const apiKey =\n    params[EnvVar.CODE_API_KEY] ??\n    params.apiKey ??\n    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??\n    '';\n  if (!apiKey) {\n    throw new Error('No API key provided for code execution tool.');\n  }\n\n  const description = `\nRuns code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.\n\n⚠️ DO NOT USE FOR: Creating dashboards, UI components, React components, HTML pages, charts, or visualizations. These should be created as artifacts directly in your response using :::artifact syntax.\n\n✅ USE FOR: Data processing, calculations, file generation (CSV, Excel, PowerPoint, PDF), matplotlib plots, running algorithms, or computational tasks.\n\nUsage:\n- No network access available.\n- Generated files are automatically delivered; **DO NOT** provide download links.\n- NEVER use this tool to execute malicious code.\n`.trim();\n\n  return tool<typeof CodeExecutionToolSchema>(\n    async ({ lang, code, session_id, ...rest }) => {\n      const postData = {\n        lang,\n        code,\n        ...rest,\n        ...params,\n      };\n\n      if (session_id != null && session_id.length > 0) {\n        try {\n          const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;\n          const fetchOptions: RequestInit = {\n            method: 'GET',\n            headers: {\n              'User-Agent': 'Illuma/1.0',\n              'X-API-Key': apiKey,\n            },\n          };\n\n          if (process.env.PROXY != null && process.env.PROXY !== '') {\n            fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n          }\n\n          const response = await fetch(filesEndpoint, fetchOptions);\n          if (!response.ok) {\n            throw new Error(\n              `Failed to fetch files for session: ${response.status}`\n            );\n          }\n\n          const files = await response.json();\n          if (Array.isArray(files) && files.length > 0) {\n            const fileReferences: t.CodeEnvFile[] = files.map((file) => {\n              // Extract the ID from the file name (part after session ID prefix and before extension)\n              const nameParts = file.name.split('/');\n              const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';\n\n              return {\n                session_id,\n                id,\n                name: file.metadata['original-filename'],\n              };\n            });\n\n            if (!postData.files) {\n              postData.files = fileReferences;\n            } else if (Array.isArray(postData.files)) {\n              postData.files = [...postData.files, ...fileReferences];\n            }\n          }\n        } catch {\n          // eslint-disable-next-line no-console\n          console.warn(`Failed to fetch files for session: ${session_id}`);\n        }\n      }\n\n      try {\n        const fetchOptions: RequestInit = {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'User-Agent': 'Illuma/1.0',\n            'X-API-Key': apiKey,\n          },\n          body: JSON.stringify(postData),\n        };\n\n        if (process.env.PROXY != null && process.env.PROXY !== '') {\n          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);\n        }\n        const response = await fetch(EXEC_ENDPOINT, fetchOptions);\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const result: t.ExecuteResult = await response.json();\n        let formattedOutput = '';\n        if (result.stdout) {\n          formattedOutput += `stdout:\\n${result.stdout}\\n`;\n        } else {\n          formattedOutput += emptyOutputMessage;\n        }\n        if (result.stderr) formattedOutput += `stderr:\\n${result.stderr}\\n`;\n        if (result.files && result.files.length > 0) {\n          formattedOutput += 'Generated files:\\n';\n\n          const fileCount = result.files.length;\n          for (let i = 0; i < fileCount; i++) {\n            const file = result.files[i];\n            const isImage = imageExtRegex.test(file.name);\n            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;\n\n            if (i < fileCount - 1) {\n              formattedOutput += fileCount <= 3 ? ', ' : ',\\n';\n            }\n          }\n\n          formattedOutput += `\\nsession_id: ${result.session_id}\\n\\n${accessMessage}`;\n          return [\n            formattedOutput.trim(),\n            {\n              session_id: result.session_id,\n              files: result.files,\n            },\n          ];\n        }\n\n        return [formattedOutput.trim(), { session_id: result.session_id }];\n      } catch (error) {\n        throw new Error(\n          `Execution error:\\n\\n${(error as Error | undefined)?.message}`\n        );\n      }\n    },\n    {\n      name: Constants.EXECUTE_CODE,\n      description,\n      schema: CodeExecutionToolSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport { createCodeExecutionTool };\n"],"names":["config","getEnvironmentVariable","EnvVar","Constants","z","tool","HttpsProxyAgent"],"mappings":"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"}

package/dist/cjs/tools/ProgrammaticToolCalling.cjs

@@ -0,0 +1,438 @@
+'use strict';
+
+var zod = require('zod');
+var dotenv = require('dotenv');
+var fetch = require('node-fetch');
+var httpsProxyAgent = require('https-proxy-agent');
+var env = require('@langchain/core/utils/env');
+var tools = require('@langchain/core/tools');
+var CodeExecutor = require('./CodeExecutor.cjs');
+var _enum = require('../common/enum.cjs');
+
+// src/tools/ProgrammaticToolCalling.ts
+dotenv.config();
+// ============================================================================
+// Constants
+// ============================================================================
+const imageMessage = 'Image is already displayed to the user';
+const otherMessage = 'File is already downloaded by the user';
+const accessMessage = 'Note: Files are READ-ONLY. Save changes to NEW filenames. To access these files in future executions, provide the `session_id` as a parameter (not in your code).';
+const emptyOutputMessage = 'stdout: Empty. Ensure you\'re writing output explicitly.\n';
+/** Default max round-trips to prevent infinite loops */
+const DEFAULT_MAX_ROUND_TRIPS = 20;
+/** Default execution timeout in milliseconds */
+const DEFAULT_TIMEOUT = 60000;
+// ============================================================================
+// Schema
+// ============================================================================
+const ProgrammaticToolCallingSchema = zod.z.object({
+    code: zod.z
+        .string()
+        .min(1)
+        .describe(`Python code that calls tools programmatically. Tools are automatically available as async Python functions - DO NOT define them yourself.
+
+The Code API generates async function stubs from the tool definitions. Just call them directly:
+
+Example (Simple call):
+  result = await get_weather(city="San Francisco")
+  print(result)
+
+Example (Parallel - Fastest):
+  results = await asyncio.gather(
+      get_weather(city="SF"),
+      get_weather(city="NYC"),
+      get_weather(city="London")
+  )
+  for city, weather in zip(["SF", "NYC", "London"], results):
+      print(f"{city}: {weather['temperature']}°F")
+
+Example (Loop with processing):
+  team = await get_team_members()
+  for member in team:
+      expenses = await get_expenses(user_id=member['id'])
+      total = sum(e['amount'] for e in expenses)
+      print(f"{member['name']}: \${total:.2f}")
+
+Example (Conditional logic):
+  data = await fetch_data(source="primary")
+  if not data:
+      data = await fetch_data(source="backup")
+  print(f"Got {len(data)} records")
+
+Requirements:
+- Tools are pre-defined as async functions - DO NOT write function definitions
+- Use await for all tool calls
+- Use asyncio.gather() for parallel execution of independent calls
+- Only print() output flows back to the context window
+- Tool results from programmatic calls do NOT consume context tokens`),
+    session_id: zod.z
+        .string()
+        .optional()
+        .describe('Session ID for file access (same as regular code execution). Files load into /mnt/data/ and are READ-ONLY.'),
+    timeout: zod.z
+        .number()
+        .int()
+        .min(1000)
+        .max(300000)
+        .optional()
+        .default(DEFAULT_TIMEOUT)
+        .describe('Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.'),
+});
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/** Python reserved keywords that get `_tool` suffix in Code API */
+const PYTHON_KEYWORDS = new Set([
+    'False',
+    'None',
+    'True',
+    'and',
+    'as',
+    'assert',
+    'async',
+    'await',
+    'break',
+    'class',
+    'continue',
+    'def',
+    'del',
+    'elif',
+    'else',
+    'except',
+    'finally',
+    'for',
+    'from',
+    'global',
+    'if',
+    'import',
+    'in',
+    'is',
+    'lambda',
+    'nonlocal',
+    'not',
+    'or',
+    'pass',
+    'raise',
+    'return',
+    'try',
+    'while',
+    'with',
+    'yield',
+]);
+/**
+ * Normalizes a tool name to Python identifier format.
+ * Must match the Code API's `normalizePythonFunctionName` exactly:
+ * 1. Replace hyphens and spaces with underscores
+ * 2. Remove any other invalid characters
+ * 3. Prefix with underscore if starts with number
+ * 4. Append `_tool` if it's a Python keyword
+ * @param name - The tool name to normalize
+ * @returns Normalized Python-safe identifier
+ */
+function normalizeToPythonIdentifier(name) {
+    let normalized = name.replace(/[-\s]/g, '_');
+    normalized = normalized.replace(/[^a-zA-Z0-9_]/g, '');
+    if (/^[0-9]/.test(normalized)) {
+        normalized = '_' + normalized;
+    }
+    if (PYTHON_KEYWORDS.has(normalized)) {
+        normalized = normalized + '_tool';
+    }
+    return normalized;
+}
+/**
+ * Extracts tool names that are actually called in the Python code.
+ * Handles hyphen/underscore conversion since Python identifiers use underscores.
+ * @param code - The Python code to analyze
+ * @param toolNameMap - Map from normalized Python name to original tool name
+ * @returns Set of original tool names found in the code
+ */
+function extractUsedToolNames(code, toolNameMap) {
+    const usedTools = new Set();
+    for (const [pythonName, originalName] of toolNameMap) {
+        const escapedName = pythonName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const pattern = new RegExp(`\\b${escapedName}\\s*\\(`, 'g');
+        if (pattern.test(code)) {
+            usedTools.add(originalName);
+        }
+    }
+    return usedTools;
+}
+/**
+ * Filters tool definitions to only include tools actually used in the code.
+ * Handles the hyphen-to-underscore conversion for Python compatibility.
+ * @param toolDefs - All available tool definitions
+ * @param code - The Python code to analyze
+ * @param debug - Enable debug logging
+ * @returns Filtered array of tool definitions
+ */
+function filterToolsByUsage(toolDefs, code, debug = false) {
+    const toolNameMap = new Map();
+    for (const tool of toolDefs) {
+        const pythonName = normalizeToPythonIdentifier(tool.name);
+        toolNameMap.set(pythonName, tool.name);
+    }
+    const usedToolNames = extractUsedToolNames(code, toolNameMap);
+    if (debug) {
+        // eslint-disable-next-line no-console
+        console.log(`[PTC Debug] Tool filtering: found ${usedToolNames.size}/${toolDefs.length} tools in code`);
+        if (usedToolNames.size > 0) {
+            // eslint-disable-next-line no-console
+            console.log(`[PTC Debug] Matched tools: ${Array.from(usedToolNames).join(', ')}`);
+        }
+    }
+    if (usedToolNames.size === 0) {
+        if (debug) {
+            // eslint-disable-next-line no-console
+            console.log('[PTC Debug] No tools detected in code - sending all tools as fallback');
+        }
+        return toolDefs;
+    }
+    return toolDefs.filter((tool) => usedToolNames.has(tool.name));
+}
+/**
+ * Makes an HTTP request to the Code API.
+ * @param endpoint - The API endpoint URL
+ * @param apiKey - The API key for authentication
+ * @param body - The request body
+ * @param proxy - Optional HTTP proxy URL
+ * @returns The parsed API response
+ */
+async function makeRequest(endpoint, apiKey, body, proxy) {
+    const fetchOptions = {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': 'Illuma/1.0',
+            'X-API-Key': apiKey,
+        },
+        body: JSON.stringify(body),
+    };
+    if (proxy != null && proxy !== '') {
+        fetchOptions.agent = new httpsProxyAgent.HttpsProxyAgent(proxy);
+    }
+    const response = await fetch(endpoint, fetchOptions);
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`HTTP error! status: ${response.status}, body: ${errorText}`);
+    }
+    return (await response.json());
+}
+/**
+ * Executes tools in parallel when requested by the API.
+ * Uses Promise.all for parallel execution, catching individual errors.
+ * @param toolCalls - Array of tool calls from the API
+ * @param toolMap - Map of tool names to executable tools
+ * @returns Array of tool results
+ */
+async function executeTools(toolCalls, toolMap) {
+    const executions = toolCalls.map(async (call) => {
+        const tool = toolMap.get(call.name);
+        if (!tool) {
+            return {
+                call_id: call.id,
+                result: null,
+                is_error: true,
+                error_message: `Tool '${call.name}' not found. Available tools: ${Array.from(toolMap.keys()).join(', ')}`,
+            };
+        }
+        try {
+            const result = await tool.invoke(call.input, {
+                metadata: { [_enum.Constants.PROGRAMMATIC_TOOL_CALLING]: true },
+            });
+            return {
+                call_id: call.id,
+                result,
+                is_error: false,
+            };
+        }
+        catch (error) {
+            return {
+                call_id: call.id,
+                result: null,
+                is_error: true,
+                error_message: error.message || 'Tool execution failed',
+            };
+        }
+    });
+    return await Promise.all(executions);
+}
+/**
+ * Formats the completed response for the agent.
+ * @param response - The completed API response
+ * @returns Tuple of [formatted string, artifact]
+ */
+function formatCompletedResponse(response) {
+    let formatted = '';
+    if (response.stdout != null && response.stdout !== '') {
+        formatted += `stdout:\n${response.stdout}\n`;
+    }
+    else {
+        formatted += emptyOutputMessage;
+    }
+    if (response.stderr != null && response.stderr !== '') {
+        formatted += `stderr:\n${response.stderr}\n`;
+    }
+    if (response.files && response.files.length > 0) {
+        formatted += 'Generated files:\n';
+        const fileCount = response.files.length;
+        for (let i = 0; i < fileCount; i++) {
+            const file = response.files[i];
+            const isImage = CodeExecutor.imageExtRegex.test(file.name);
+            formatted += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+            if (i < fileCount - 1) {
+                formatted += fileCount <= 3 ? ', ' : ',\n';
+            }
+        }
+        formatted += `\nsession_id: ${response.session_id}\n\n${accessMessage}`;
+    }
+    return [
+        formatted.trim(),
+        {
+            session_id: response.session_id,
+            files: response.files,
+        },
+    ];
+}
+// ============================================================================
+// Tool Factory
+// ============================================================================
+/**
+ * Creates a Programmatic Tool Calling tool for complex multi-tool workflows.
+ *
+ * This tool enables AI agents to write Python code that orchestrates multiple
+ * tool calls programmatically, reducing LLM round-trips and token usage.
+ *
+ * The tool map must be provided at runtime via config.configurable.toolMap.
+ *
+ * @param params - Configuration parameters (apiKey, baseUrl, maxRoundTrips, proxy)
+ * @returns A LangChain DynamicStructuredTool for programmatic tool calling
+ *
+ * @example
+ * const ptcTool = createProgrammaticToolCallingTool({
+ *   apiKey: process.env.CODE_API_KEY,
+ *   maxRoundTrips: 20
+ * });
+ *
+ * const [output, artifact] = await ptcTool.invoke(
+ *   { code, tools },
+ *   { configurable: { toolMap } }
+ * );
+ */
+function createProgrammaticToolCallingTool(initParams = {}) {
+    const apiKey = initParams[_enum.EnvVar.CODE_API_KEY] ??
+        initParams.apiKey ??
+        env.getEnvironmentVariable(_enum.EnvVar.CODE_API_KEY) ??
+        '';
+    if (!apiKey) {
+        throw new Error('No API key provided for programmatic tool calling. ' +
+            'Set CODE_API_KEY environment variable or pass apiKey in initParams.');
+    }
+    const baseUrl = initParams.baseUrl ?? CodeExecutor.getCodeBaseURL();
+    const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;
+    const proxy = initParams.proxy ?? process.env.PROXY;
+    const debug = initParams.debug ?? process.env.PTC_DEBUG === 'true';
+    const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
+    const description = `
+Run tools by writing Python code. Tools are available as async functions - just call them with await.
+
+This is different from execute_code: here you can call your tools (like get_weather, get_expenses, etc.) directly in Python code.
+
+Usage:
+- Tools are pre-defined as async functions - call them with await
+- Use asyncio.gather() to run multiple tools in parallel
+- Only print() output is returned - tool results stay in Python
+
+Examples:
+- Simple: result = await get_weather(city="NYC")
+- Loop: for user in users: data = await get_expenses(user_id=user['id'])
+- Parallel: sf, ny = await asyncio.gather(get_weather(city="SF"), get_weather(city="NY"))
+
+When to use this instead of calling tools directly:
+- You need to call tools in a loop (process many items)
+- You want parallel execution (asyncio.gather)
+- You need conditionals based on tool results
+- You want to aggregate/filter data before returning
+`.trim();
+    return tools.tool(async (params, config) => {
+        const { code, session_id, timeout = DEFAULT_TIMEOUT } = params;
+        // Extra params injected by ToolNode (follows web_search pattern)
+        const { toolMap, toolDefs } = (config.toolCall ?? {});
+        if (toolMap == null || toolMap.size === 0) {
+            throw new Error('No toolMap provided. ' +
+                'ToolNode should inject this from AgentContext when invoked through the graph.');
+        }
+        if (toolDefs == null || toolDefs.length === 0) {
+            throw new Error('No tool definitions provided. ' +
+                'Either pass tools in the input or ensure ToolNode injects toolDefs.');
+        }
+        let roundTrip = 0;
+        try {
+            // ====================================================================
+            // Phase 1: Filter tools and make initial request
+            // ====================================================================
+            const effectiveTools = filterToolsByUsage(toolDefs, code, debug);
+            if (debug) {
+                // eslint-disable-next-line no-console
+                console.log(`[PTC Debug] Sending ${effectiveTools.length} tools to API ` +
+                    `(filtered from ${toolDefs.length})`);
+            }
+            let response = await makeRequest(EXEC_ENDPOINT, apiKey, {
+                code,
+                tools: effectiveTools,
+                session_id,
+                timeout,
+            }, proxy);
+            // ====================================================================
+            // Phase 2: Handle response loop
+            // ====================================================================
+            while (response.status === 'tool_call_required') {
+                roundTrip++;
+                if (roundTrip > maxRoundTrips) {
+                    throw new Error(`Exceeded maximum round trips (${maxRoundTrips}). ` +
+                        'This may indicate an infinite loop, excessive tool calls, ' +
+                        'or a logic error in your code.');
+                }
+                if (debug) {
+                    // eslint-disable-next-line no-console
+                    console.log(`[PTC Debug] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`);
+                }
+                const toolResults = await executeTools(response.tool_calls ?? [], toolMap);
+                response = await makeRequest(EXEC_ENDPOINT, apiKey, {
+                    continuation_token: response.continuation_token,
+                    tool_results: toolResults,
+                }, proxy);
+            }
+            // ====================================================================
+            // Phase 3: Handle final state
+            // ====================================================================
+            if (response.status === 'completed') {
+                return formatCompletedResponse(response);
+            }
+            if (response.status === 'error') {
+                throw new Error(`Execution error: ${response.error}` +
+                    (response.stderr != null && response.stderr !== ''
+                        ? `\n\nStderr:\n${response.stderr}`
+                        : ''));
+            }
+            throw new Error(`Unexpected response status: ${response.status}`);
+        }
+        catch (error) {
+            throw new Error(`Programmatic execution failed: ${error.message}`);
+        }
+    }, {
+        name: _enum.Constants.PROGRAMMATIC_TOOL_CALLING,
+        description,
+        schema: ProgrammaticToolCallingSchema,
+        responseFormat: _enum.Constants.CONTENT_AND_ARTIFACT,
+    });
+}
+
+exports.createProgrammaticToolCallingTool = createProgrammaticToolCallingTool;
+exports.executeTools = executeTools;
+exports.extractUsedToolNames = extractUsedToolNames;
+exports.filterToolsByUsage = filterToolsByUsage;
+exports.formatCompletedResponse = formatCompletedResponse;
+exports.makeRequest = makeRequest;
+exports.normalizeToPythonIdentifier = normalizeToPythonIdentifier;
+//# sourceMappingURL=ProgrammaticToolCalling.cjs.map