@illuma-ai/agents 1.0.89 → 1.0.93

package/dist/cjs/tools/AskUser.cjs

@@ -0,0 +1,131 @@
+'use strict';
+
+var tools = require('@langchain/core/tools');
+var zod = require('zod');
+var _enum = require('../common/enum.cjs');
+
+const AskUserToolName = _enum.Constants.ASK_USER;
+const AskUserDescription = 'Ask the user clarification questions with structured options before taking action. ' +
+    'For a single key question, use question+options. For multiple related questions, use steps[] (max 3 steps). ' +
+    'Each step can be single-select or multi-select. After receiving answers, proceed immediately.';
+const AskUserOptionSchema = zod.z.object({
+    label: zod.z.string().describe('Short display label'),
+    value: zod.z.string().describe('Machine-readable value returned when selected'),
+    description: zod.z.string().optional().describe('Optional longer description'),
+});
+const AskUserStepSchema = zod.z.object({
+    question: zod.z.string().describe('The question to ask the user for this step'),
+    options: zod.z
+        .array(AskUserOptionSchema)
+        .min(2)
+        .max(6)
+        .describe('Structured options for this step (2-6 choices)'),
+    type: zod.z
+        .enum(['single', 'multi'])
+        .default('single')
+        .describe('Selection type: single-select or multi-select'),
+});
+const AskUserSchema = zod.z
+    .object({
+    question: zod.z
+        .string()
+        .optional()
+        .describe('The question to ask the user. Be specific and clear.'),
+    options: zod.z
+        .array(AskUserOptionSchema)
+        .min(2)
+        .max(6)
+        .optional()
+        .describe('Structured options for the user (2-6 choices)'),
+    context: zod.z.string().optional().describe('Why you are asking this question'),
+    steps: zod.z
+        .array(AskUserStepSchema)
+        .min(1)
+        .max(5)
+        .optional()
+        .describe('Multi-step wizard: array of question steps (1-5 steps)'),
+})
+    // passthrough() preserves extra fields like _selectedOption injected by the
+    // approval flow's modifiedArgs — without this, Zod strips unknown keys.
+    .passthrough()
+    .refine((data) => {
+    // Must have either steps[] OR question+options (legacy format)
+    const hasSteps = Array.isArray(data.steps) && data.steps.length > 0;
+    const hasLegacy = typeof data.question === 'string' && Array.isArray(data.options);
+    return hasSteps || hasLegacy;
+}, {
+    message: 'Either steps[] or question+options must be provided',
+});
+/** Field names injected into modifiedArgs by the approval flow */
+const HITL_FIELDS = {
+    SELECTIONS: '_selections',
+    SELECTED_OPTION: '_selectedOption',
+    CUSTOM_INPUT: '_customInput',
+};
+/**
+ * Creates an ask_user tool that lets the LLM ask clarification questions mid-conversation.
+ *
+ * How it works:
+ * 1. LLM calls ask_user(question, options) OR ask_user(steps)
+ * 2. ToolNode.requiresApproval() → always true (per-tool rule in askUserRules.js)
+ * 3. ToolNode.requestApproval() promotes options/question/steps to top-level fields on the event
+ * 4. Frontend HumanInputPopover renders option cards + freeform text input
+ * 5. User selects option(s) OR types custom input →
+ *    backend resolves with modifiedArgs containing _selections, _selectedOption, or _customInput
+ * 6. Tool executes, reads the user's choice, returns result to LLM
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+function createAskUserTool() {
+    return tools.tool(async (args) => {
+        const extArgs = args;
+        const selections = extArgs[HITL_FIELDS.SELECTIONS];
+        const customInput = extArgs[HITL_FIELDS.CUSTOM_INPUT];
+        const selectedOption = extArgs[HITL_FIELDS.SELECTED_OPTION];
+        // Multi-step wizard flow: _selections is an array of { values, customInput? } per step
+        if (selections &&
+            Array.isArray(selections) &&
+            Array.isArray(args.steps)) {
+            const lines = [];
+            for (let i = 0; i < args.steps.length; i++) {
+                const step = args.steps[i];
+                const sel = selections[i];
+                if (!sel || (sel.values.length === 0 && !sel.customInput)) {
+                    lines.push(`${i + 1}. ${step.question} → (skipped)`);
+                    continue;
+                }
+                if (sel.customInput) {
+                    lines.push(`${i + 1}. ${step.question} → "${sel.customInput}"`);
+                    continue;
+                }
+                // Resolve value(s) to labels
+                const labels = sel.values.map((v) => {
+                    const opt = step.options.find((o) => o.value === v);
+                    return opt?.label || v;
+                });
+                lines.push(`${i + 1}. ${step.question} → ${labels.join(', ')}`);
+            }
+            return `User responses:\n${lines.join('\n')}`;
+        }
+        // Legacy: custom freeform input takes priority — user explicitly chose "none of these"
+        if (customInput) {
+            return `User provided custom response: "${customInput}"`;
+        }
+        if (selectedOption) {
+            const option = args.options?.find((o) => o.value === selectedOption);
+            return `User selected: "${option?.label || selectedOption}" (value: ${selectedOption})`;
+        }
+        // Fallback — should not happen in interactive mode since approval always fires first
+        return 'No user response received.';
+    }, {
+        name: AskUserToolName,
+        description: AskUserDescription,
+        schema: AskUserSchema,
+    });
+}
+
+exports.AskUserDescription = AskUserDescription;
+exports.AskUserStepSchema = AskUserStepSchema;
+exports.AskUserToolName = AskUserToolName;
+exports.HITL_FIELDS = HITL_FIELDS;
+exports.createAskUserTool = createAskUserTool;
+//# sourceMappingURL=AskUser.cjs.map

package/dist/cjs/tools/AskUser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"AskUser.cjs","sources":["../../../src/tools/AskUser.ts"],"sourcesContent":["import { tool } from '@langchain/core/tools';\nimport { z } from 'zod';\nimport { Constants } from '@/common';\n\nexport const AskUserToolName = Constants.ASK_USER;\n\nexport const AskUserDescription =\n  'Ask the user clarification questions with structured options before taking action. ' +\n  'For a single key question, use question+options. For multiple related questions, use steps[] (max 3 steps). ' +\n  'Each step can be single-select or multi-select. After receiving answers, proceed immediately.';\n\nconst AskUserOptionSchema = z.object({\n  label: z.string().describe('Short display label'),\n  value: z.string().describe('Machine-readable value returned when selected'),\n  description: z.string().optional().describe('Optional longer description'),\n});\n\nexport const AskUserStepSchema = z.object({\n  question: z.string().describe('The question to ask the user for this step'),\n  options: z\n    .array(AskUserOptionSchema)\n    .min(2)\n    .max(6)\n    .describe('Structured options for this step (2-6 choices)'),\n  type: z\n    .enum(['single', 'multi'])\n    .default('single')\n    .describe('Selection type: single-select or multi-select'),\n});\n\nexport type AskUserStep = z.infer<typeof AskUserStepSchema>;\n\nconst AskUserSchema = z\n  .object({\n    question: z\n      .string()\n      .optional()\n      .describe('The question to ask the user. Be specific and clear.'),\n    options: z\n      .array(AskUserOptionSchema)\n      .min(2)\n      .max(6)\n      .optional()\n      .describe('Structured options for the user (2-6 choices)'),\n    context: z.string().optional().describe('Why you are asking this question'),\n    steps: z\n      .array(AskUserStepSchema)\n      .min(1)\n      .max(5)\n      .optional()\n      .describe('Multi-step wizard: array of question steps (1-5 steps)'),\n  })\n  // passthrough() preserves extra fields like _selectedOption injected by the\n  // approval flow's modifiedArgs — without this, Zod strips unknown keys.\n  .passthrough()\n  .refine(\n    (data) => {\n      // Must have either steps[] OR question+options (legacy format)\n      const hasSteps = Array.isArray(data.steps) && data.steps.length > 0;\n      const hasLegacy =\n        typeof data.question === 'string' && Array.isArray(data.options);\n      return hasSteps || hasLegacy;\n    },\n    {\n      message: 'Either steps[] or question+options must be provided',\n    }\n  );\n\n/**\n * Represents a single step selection from the multi-step wizard UI.\n * Exported for use by both ranger web client and browser extension.\n */\nexport type StepSelection = {\n  values: string[];\n  customInput?: string;\n};\n\n/** Field names injected into modifiedArgs by the approval flow */\nexport const HITL_FIELDS = {\n  SELECTIONS: '_selections',\n  SELECTED_OPTION: '_selectedOption',\n  CUSTOM_INPUT: '_customInput',\n} as const;\n\n/**\n * Creates an ask_user tool that lets the LLM ask clarification questions mid-conversation.\n *\n * How it works:\n * 1. LLM calls ask_user(question, options) OR ask_user(steps)\n * 2. ToolNode.requiresApproval() → always true (per-tool rule in askUserRules.js)\n * 3. ToolNode.requestApproval() promotes options/question/steps to top-level fields on the event\n * 4. Frontend HumanInputPopover renders option cards + freeform text input\n * 5. User selects option(s) OR types custom input →\n *    backend resolves with modifiedArgs containing _selections, _selectedOption, or _customInput\n * 6. Tool executes, reads the user's choice, returns result to LLM\n */\n// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\nexport function createAskUserTool() {\n  return tool(\n    async (args) => {\n      const extArgs = args as Record<string, unknown>;\n      const selections = extArgs[HITL_FIELDS.SELECTIONS] as\n        | StepSelection[]\n        | undefined;\n      const customInput = extArgs[HITL_FIELDS.CUSTOM_INPUT] as\n        | string\n        | undefined;\n      const selectedOption = extArgs[HITL_FIELDS.SELECTED_OPTION] as\n        | string\n        | undefined;\n\n      // Multi-step wizard flow: _selections is an array of { values, customInput? } per step\n      if (\n        selections &&\n        Array.isArray(selections) &&\n        Array.isArray(args.steps)\n      ) {\n        const lines: string[] = [];\n        for (let i = 0; i < args.steps.length; i++) {\n          const step = args.steps[i];\n          const sel = selections[i];\n          if (!sel || (sel.values.length === 0 && !sel.customInput)) {\n            lines.push(`${i + 1}. ${step.question} → (skipped)`);\n            continue;\n          }\n          if (sel.customInput) {\n            lines.push(`${i + 1}. ${step.question} → \"${sel.customInput}\"`);\n            continue;\n          }\n          // Resolve value(s) to labels\n          const labels = sel.values.map((v) => {\n            const opt = step.options.find((o) => o.value === v);\n            return opt?.label || v;\n          });\n          lines.push(`${i + 1}. ${step.question} → ${labels.join(', ')}`);\n        }\n        return `User responses:\\n${lines.join('\\n')}`;\n      }\n\n      // Legacy: custom freeform input takes priority — user explicitly chose \"none of these\"\n      if (customInput) {\n        return `User provided custom response: \"${customInput}\"`;\n      }\n\n      if (selectedOption) {\n        const option = args.options?.find((o) => o.value === selectedOption);\n        return `User selected: \"${option?.label || selectedOption}\" (value: ${selectedOption})`;\n      }\n\n      // Fallback — should not happen in interactive mode since approval always fires first\n      return 'No user response received.';\n    },\n    {\n      name: AskUserToolName,\n      description: AskUserDescription,\n      schema: AskUserSchema,\n    }\n  );\n}\n"],"names":["Constants","z","tool"],"mappings":"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"}

package/dist/cjs/tools/BrowserTools.cjs

@@ -24,15 +24,15 @@ const EBrowserTools = {
 /**
  * Check if browser capability is available based on request headers or context
  * The browser extension sets these headers when connected:
- * - X-Ranger-Browser-Extension: true
- * - X-Ranger-Browser-Capable: true
+ * - X-Illuma-Browser-Extension: true
+ * - X-Illuma-Browser-Capable: true
  */
 function hasBrowserCapability(req) {
     if (!req?.headers) {
         return false;
     }
-    const browserExtension = req.headers['x-ranger-browser-extension'];
-    const browserCapable = req.headers['x-ranger-browser-capable'];
+    const browserExtension = req.headers['x-illuma-browser-extension'];
+    const browserCapable = req.headers['x-illuma-browser-capable'];
     return browserExtension === 'true' || browserCapable === 'true';
 }
 // Tool schemas
@@ -97,10 +97,12 @@ const BrowserSwitchTabSchema = zod.z.object({
  * Format browser action result for LLM consumption
  */
 function formatResultForLLM(result, action) {
+    const parts = [];
+    // Include error info but DON'T discard page state — the extension often sends
+    // success=false with valid page state (URL, elementList) that the LLM needs
     if (!result.success && result.error) {
-        return `Browser action "${action}" failed: ${result.error}`;
+        parts.push(`**Note:** Action "${action}" reported: ${result.error}`);
     }
-    const parts = [];
     if (result.url != null && result.url !== '') {
         parts.push(`**Current URL:** ${result.url}`);
     }
@@ -108,13 +110,15 @@ function formatResultForLLM(result, action) {
         parts.push(`**Page Title:** ${result.title}`);
     }
     if (result.elementList != null && result.elementList !== '') {
-        // Add hint about fieldLabel and targeting inputs for form interactions
         parts.push(`\n**Interactive Elements** (for typing: target <input> elements with fieldLabel, NOT parent <div> containers):\n${result.elementList}`);
     }
     if (result.screenshot != null && result.screenshot !== '') {
         parts.push('\n[Screenshot captured and displayed to user]');
     }
     if (parts.length === 0) {
+        if (!result.success) {
+            return `Browser action "${action}" failed: ${result.error || 'Unknown error'}`;
+        }
         return `Browser action "${action}" completed successfully.`;
     }
     return parts.join('\n');

package/dist/cjs/tools/BrowserTools.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"BrowserTools.cjs","sources":["../../../src/tools/BrowserTools.ts"],"sourcesContent":["import { z } from 'zod';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type * as _t from '@/types';\n\n/**\n * Browser tool names - keep in sync with ranger-browser extension\n * These tools execute locally in the browser extension, NOT on the server\n */\nexport const EBrowserTools = {\n  CLICK: 'browser_click',\n  TYPE: 'browser_type',\n  NAVIGATE: 'browser_navigate',\n  SCROLL: 'browser_scroll',\n  EXTRACT: 'browser_extract',\n  HOVER: 'browser_hover',\n  WAIT: 'browser_wait',\n  BACK: 'browser_back',\n  SCREENSHOT: 'browser_screenshot',\n  GET_PAGE_STATE: 'browser_get_page_state',\n  KEYPRESS: 'browser_keypress',\n  SWITCH_TAB: 'browser_switch_tab',\n} as const;\n\nexport type BrowserToolName =\n  (typeof EBrowserTools)[keyof typeof EBrowserTools];\n\n/**\n * Callback function type for waiting on browser action results\n * This allows the server (Ranger) to provide a callback that waits for the extension\n * to POST results back to the server before returning to the LLM.\n *\n * @param action - The browser action (click, type, navigate, etc.)\n * @param args - Arguments for the action\n * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)\n * @returns Promise that resolves with the actual browser result (page state, etc.)\n */\nexport type BrowserToolCallback = (\n  action: string,\n  args: Record<string, unknown>,\n  toolCallId: string\n) => Promise<BrowserActionResult>;\n\n/**\n * Result returned from browser action execution\n */\nexport interface BrowserActionResult {\n  success: boolean;\n  url?: string;\n  title?: string;\n  elementList?: string; // Text-based element list\n  error?: string;\n  screenshot?: string; // Base64 screenshot (if requested)\n}\n\n/**\n * Check if browser capability is available based on request headers or context\n * The browser extension sets these headers when connected:\n * - X-Ranger-Browser-Extension: true\n * - X-Ranger-Browser-Capable: true\n */\nexport function hasBrowserCapability(req?: {\n  headers?: Record<string, string | string[] | undefined>;\n}): boolean {\n  if (!req?.headers) {\n    return false;\n  }\n\n  const browserExtension = req.headers['x-ranger-browser-extension'];\n  const browserCapable = req.headers['x-ranger-browser-capable'];\n\n  return browserExtension === 'true' || browserCapable === 'true';\n}\n\n// Tool schemas\nconst BrowserClickSchema = z.object({\n  index: z\n    .number()\n    .describe(\n      'The [index] of the element to click. Use fieldLabel to identify the correct element. For form fields, target <input> or <textarea> elements, NOT parent <div> containers.'\n    ),\n});\n\nconst BrowserTypeSchema = z.object({\n  index: z\n    .number()\n    .describe(\n      'The [index] of the INPUT element to type into. Target <input> or <textarea> elements. Check fieldLabel to identify the correct field.'\n    ),\n  text: z.string().describe('The text to type into the element'),\n  pressEnter: z\n    .boolean()\n    .optional()\n    .describe(\n      'Whether to press Enter after typing (useful for search forms and submitting)'\n    ),\n});\n\nconst BrowserNavigateSchema = z.object({\n  url: z\n    .string()\n    .describe('The full URL to navigate to (must include https://)'),\n});\n\nconst BrowserScrollSchema = z.object({\n  direction: z\n    .enum(['up', 'down', 'left', 'right'])\n    .describe('Direction to scroll'),\n  amount: z\n    .number()\n    .optional()\n    .describe('Pixels to scroll (default: one viewport height)'),\n});\n\nconst BrowserExtractSchema = z.object({\n  query: z\n    .string()\n    .optional()\n    .describe('Optional: specific content to extract from the page'),\n});\n\nconst BrowserHoverSchema = z.object({\n  index: z.number().describe('The index number of the element to hover over'),\n});\n\nconst BrowserWaitSchema = z.object({\n  duration: z\n    .number()\n    .optional()\n    .describe('Milliseconds to wait (default: 1000)'),\n});\n\nconst BrowserBackSchema = z.object({});\n\nconst BrowserScreenshotSchema = z.object({});\n\nconst BrowserGetPageStateSchema = z.object({});\n\nconst BrowserKeypressSchema = z.object({\n  keys: z\n    .string()\n    .describe(\n      'Keyboard keys to press. Use \"+\" to combine modifiers (e.g., \"Control+Enter\", \"Control+a\", \"Escape\", \"Tab\", \"Enter\"). Common shortcuts: Control+Enter (submit forms/send), Escape (close dialogs), Tab (next field).'\n    ),\n});\n\nconst BrowserSwitchTabSchema = z.object({\n  tabId: z\n    .number()\n    .describe(\n      'The tab ID to switch to. Use the tab IDs shown in the tabs list from page state.'\n    ),\n});\n\n/**\n * Browser tool response interface\n * This is what the extension returns after executing the action\n */\nexport interface BrowserToolResponse {\n  requiresBrowserExecution: true;\n  action: string;\n  args: Record<string, unknown>;\n  toolCallId?: string; // Added to help extension correlate with callback\n}\n\n/**\n * Options for creating browser tools\n */\nexport interface CreateBrowserToolsOptions {\n  /**\n   * Optional callback that waits for browser action results.\n   * When provided, tools will await this callback to get actual results from the extension.\n   * When not provided, tools return markers immediately (for non-server contexts).\n   */\n  waitForResult?: BrowserToolCallback;\n}\n\n/**\n * Format browser action result for LLM consumption\n */\nfunction formatResultForLLM(\n  result: BrowserActionResult,\n  action: string\n): string {\n  if (!result.success && result.error) {\n    return `Browser action \"${action}\" failed: ${result.error}`;\n  }\n\n  const parts: string[] = [];\n\n  if (result.url != null && result.url !== '') {\n    parts.push(`**Current URL:** ${result.url}`);\n  }\n  if (result.title != null && result.title !== '') {\n    parts.push(`**Page Title:** ${result.title}`);\n  }\n  if (result.elementList != null && result.elementList !== '') {\n    // Add hint about fieldLabel and targeting inputs for form interactions\n    parts.push(\n      `\\n**Interactive Elements** (for typing: target <input> elements with fieldLabel, NOT parent <div> containers):\\n${result.elementList}`\n    );\n  }\n  if (result.screenshot != null && result.screenshot !== '') {\n    parts.push('\\n[Screenshot captured and displayed to user]');\n  }\n\n  if (parts.length === 0) {\n    return `Browser action \"${action}\" completed successfully.`;\n  }\n\n  return parts.join('\\n');\n}\n\n/**\n * Create browser tools with optional callback for waiting on results\n *\n * When waitForResult callback is provided:\n * 1. Tool returns marker that triggers extension\n * 2. Tool then awaits callback to get actual results\n * 3. Returns real page state to LLM\n *\n * When no callback:\n * 1. Tool returns marker only (for non-server contexts)\n *\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\n */\nexport function createBrowserTools(\n  options?: CreateBrowserToolsOptions\n): DynamicStructuredTool[] {\n  const { waitForResult } = options || {};\n  const tools: DynamicStructuredTool[] = [];\n\n  /**\n   * Helper to create tool function that optionally waits for results\n   * The toolCallId is extracted from the RunnableConfig passed by LangChain\n   */\n  const createToolFunction = (action: string) => {\n    return async (\n      args: Record<string, unknown>,\n      config?: { toolCall?: { id?: string } }\n    ): Promise<string> => {\n      const toolCallId =\n        config?.toolCall?.id ??\n        `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;\n\n      // Create marker for extension\n      const marker: BrowserToolResponse = {\n        requiresBrowserExecution: true,\n        action,\n        args,\n        toolCallId,\n      };\n\n      // If no callback, return marker immediately (extension handles via SSE interception)\n      if (!waitForResult) {\n        return JSON.stringify(marker);\n      }\n\n      // With callback: wait for actual results from extension\n      // The marker is still returned initially via SSE, but we wait for the callback\n      try {\n        const result = await waitForResult(action, args, toolCallId);\n        return formatResultForLLM(result, action);\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return `Browser action \"${action}\" failed: ${errorMessage}`;\n      }\n    };\n  };\n\n  // browser_click\n  tools.push(\n    tool(createToolFunction('click'), {\n      name: EBrowserTools.CLICK,\n      description:\n        'Click element by [index]. Use fieldLabel attribute to identify correct element. For form fields, target <input> elements NOT parent <div> containers.',\n      schema: BrowserClickSchema,\n    })\n  );\n\n  // browser_type\n  tools.push(\n    tool(createToolFunction('type'), {\n      name: EBrowserTools.TYPE,\n      description:\n        'Type text into <input> element by [index]. CRITICAL: Always target <input> or <textarea> tags (NOT parent <div> containers). Use fieldLabel to identify correct field (e.g., fieldLabel=\"To recipients\" for To field).',\n      schema: BrowserTypeSchema,\n    })\n  );\n\n  // browser_navigate\n  tools.push(\n    tool(createToolFunction('navigate'), {\n      name: EBrowserTools.NAVIGATE,\n      description:\n        'Navigate to URL (include https://). Returns new page element list.',\n      schema: BrowserNavigateSchema,\n    })\n  );\n\n  // browser_scroll\n  tools.push(\n    tool(createToolFunction('scroll'), {\n      name: EBrowserTools.SCROLL,\n      description:\n        'Scroll page (up/down/left/right). Returns updated element list.',\n      schema: BrowserScrollSchema,\n    })\n  );\n\n  // browser_extract\n  tools.push(\n    tool(createToolFunction('extract'), {\n      name: EBrowserTools.EXTRACT,\n      description:\n        'Extract page content. Returns URL, title, and element list.',\n      schema: BrowserExtractSchema,\n    })\n  );\n\n  // browser_hover\n  tools.push(\n    tool(createToolFunction('hover'), {\n      name: EBrowserTools.HOVER,\n      description:\n        'Hover element by [index] to reveal menus/tooltips. Returns updated element list.',\n      schema: BrowserHoverSchema,\n    })\n  );\n\n  // browser_wait\n  tools.push(\n    tool(createToolFunction('wait'), {\n      name: EBrowserTools.WAIT,\n      description:\n        'Wait for async content to load. Returns updated element list.',\n      schema: BrowserWaitSchema,\n    })\n  );\n\n  // browser_back\n  tools.push(\n    tool(createToolFunction('back'), {\n      name: EBrowserTools.BACK,\n      description:\n        'Go back in browser history. Returns previous page element list.',\n      schema: BrowserBackSchema,\n    })\n  );\n\n  // browser_screenshot\n  tools.push(\n    tool(createToolFunction('screenshot'), {\n      name: EBrowserTools.SCREENSHOT,\n      description:\n        'Capture screenshot. Displayed to user. Use get_page_state for automation.',\n      schema: BrowserScreenshotSchema,\n    })\n  );\n\n  // browser_get_page_state\n  tools.push(\n    tool(createToolFunction('get_page_state'), {\n      name: EBrowserTools.GET_PAGE_STATE,\n      description:\n        'Get page URL, title, and interactive elements with [index] for actions. Start here.',\n      schema: BrowserGetPageStateSchema,\n    })\n  );\n\n  // browser_keypress - for keyboard shortcuts\n  tools.push(\n    tool(createToolFunction('keypress'), {\n      name: EBrowserTools.KEYPRESS,\n      description:\n        'Send keyboard shortcut or key press. Use for: Control+Enter (send email/submit), Escape (close dialog/cancel), Tab (next field), Enter (confirm). The keys are sent to the currently focused element.',\n      schema: BrowserKeypressSchema,\n    })\n  );\n\n  // browser_switch_tab - for switching between tabs\n  tools.push(\n    tool(createToolFunction('switch_tab'), {\n      name: EBrowserTools.SWITCH_TAB,\n      description:\n        'Switch to a different browser tab by its ID. Tab IDs are shown in the page state. Use this to work with existing open tabs (e.g., use existing Gmail tab instead of opening a new one).',\n      schema: BrowserSwitchTabSchema,\n    })\n  );\n\n  return tools;\n}\n"],"names":["z","tools","tool"],"mappings":"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"}
+{"version":3,"file":"BrowserTools.cjs","sources":["../../../src/tools/BrowserTools.ts"],"sourcesContent":["import { z } from 'zod';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type * as _t from '@/types';\n\n/**\n * Browser tool names - keep in sync with ranger-browser extension\n * These tools execute locally in the browser extension, NOT on the server\n */\nexport const EBrowserTools = {\n  CLICK: 'browser_click',\n  TYPE: 'browser_type',\n  NAVIGATE: 'browser_navigate',\n  SCROLL: 'browser_scroll',\n  EXTRACT: 'browser_extract',\n  HOVER: 'browser_hover',\n  WAIT: 'browser_wait',\n  BACK: 'browser_back',\n  SCREENSHOT: 'browser_screenshot',\n  GET_PAGE_STATE: 'browser_get_page_state',\n  KEYPRESS: 'browser_keypress',\n  SWITCH_TAB: 'browser_switch_tab',\n} as const;\n\nexport type BrowserToolName =\n  (typeof EBrowserTools)[keyof typeof EBrowserTools];\n\n/**\n * Callback function type for waiting on browser action results\n * This allows the server (Ranger) to provide a callback that waits for the extension\n * to POST results back to the server before returning to the LLM.\n *\n * @param action - The browser action (click, type, navigate, etc.)\n * @param args - Arguments for the action\n * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)\n * @returns Promise that resolves with the actual browser result (page state, etc.)\n */\nexport type BrowserToolCallback = (\n  action: string,\n  args: Record<string, unknown>,\n  toolCallId: string\n) => Promise<BrowserActionResult>;\n\n/**\n * Result returned from browser action execution\n */\nexport interface BrowserActionResult {\n  success: boolean;\n  url?: string;\n  title?: string;\n  elementList?: string; // Text-based element list\n  error?: string;\n  screenshot?: string; // Base64 screenshot (if requested)\n}\n\n/**\n * Check if browser capability is available based on request headers or context\n * The browser extension sets these headers when connected:\n * - X-Illuma-Browser-Extension: true\n * - X-Illuma-Browser-Capable: true\n */\nexport function hasBrowserCapability(req?: {\n  headers?: Record<string, string | string[] | undefined>;\n}): boolean {\n  if (!req?.headers) {\n    return false;\n  }\n\n  const browserExtension = req.headers['x-illuma-browser-extension'];\n  const browserCapable = req.headers['x-illuma-browser-capable'];\n\n  return browserExtension === 'true' || browserCapable === 'true';\n}\n\n// Tool schemas\nconst BrowserClickSchema = z.object({\n  index: z\n    .number()\n    .describe(\n      'The [index] of the element to click. Use fieldLabel to identify the correct element. For form fields, target <input> or <textarea> elements, NOT parent <div> containers.'\n    ),\n});\n\nconst BrowserTypeSchema = z.object({\n  index: z\n    .number()\n    .describe(\n      'The [index] of the INPUT element to type into. Target <input> or <textarea> elements. Check fieldLabel to identify the correct field.'\n    ),\n  text: z.string().describe('The text to type into the element'),\n  pressEnter: z\n    .boolean()\n    .optional()\n    .describe(\n      'Whether to press Enter after typing (useful for search forms and submitting)'\n    ),\n});\n\nconst BrowserNavigateSchema = z.object({\n  url: z\n    .string()\n    .describe('The full URL to navigate to (must include https://)'),\n});\n\nconst BrowserScrollSchema = z.object({\n  direction: z\n    .enum(['up', 'down', 'left', 'right'])\n    .describe('Direction to scroll'),\n  amount: z\n    .number()\n    .optional()\n    .describe('Pixels to scroll (default: one viewport height)'),\n});\n\nconst BrowserExtractSchema = z.object({\n  query: z\n    .string()\n    .optional()\n    .describe('Optional: specific content to extract from the page'),\n});\n\nconst BrowserHoverSchema = z.object({\n  index: z.number().describe('The index number of the element to hover over'),\n});\n\nconst BrowserWaitSchema = z.object({\n  duration: z\n    .number()\n    .optional()\n    .describe('Milliseconds to wait (default: 1000)'),\n});\n\nconst BrowserBackSchema = z.object({});\n\nconst BrowserScreenshotSchema = z.object({});\n\nconst BrowserGetPageStateSchema = z.object({});\n\nconst BrowserKeypressSchema = z.object({\n  keys: z\n    .string()\n    .describe(\n      'Keyboard keys to press. Use \"+\" to combine modifiers (e.g., \"Control+Enter\", \"Control+a\", \"Escape\", \"Tab\", \"Enter\"). Common shortcuts: Control+Enter (submit forms/send), Escape (close dialogs), Tab (next field).'\n    ),\n});\n\nconst BrowserSwitchTabSchema = z.object({\n  tabId: z\n    .number()\n    .describe(\n      'The tab ID to switch to. Use the tab IDs shown in the tabs list from page state.'\n    ),\n});\n\n/**\n * Browser tool response interface\n * This is what the extension returns after executing the action\n */\nexport interface BrowserToolResponse {\n  requiresBrowserExecution: true;\n  action: string;\n  args: Record<string, unknown>;\n  toolCallId?: string; // Added to help extension correlate with callback\n}\n\n/**\n * Options for creating browser tools\n */\nexport interface CreateBrowserToolsOptions {\n  /**\n   * Optional callback that waits for browser action results.\n   * When provided, tools will await this callback to get actual results from the extension.\n   * When not provided, tools return markers immediately (for non-server contexts).\n   */\n  waitForResult?: BrowserToolCallback;\n}\n\n/**\n * Format browser action result for LLM consumption\n */\nfunction formatResultForLLM(\n  result: BrowserActionResult,\n  action: string\n): string {\n  const parts: string[] = [];\n\n  // Include error info but DON'T discard page state — the extension often sends\n  // success=false with valid page state (URL, elementList) that the LLM needs\n  if (!result.success && result.error) {\n    parts.push(`**Note:** Action \"${action}\" reported: ${result.error}`);\n  }\n\n  if (result.url != null && result.url !== '') {\n    parts.push(`**Current URL:** ${result.url}`);\n  }\n  if (result.title != null && result.title !== '') {\n    parts.push(`**Page Title:** ${result.title}`);\n  }\n  if (result.elementList != null && result.elementList !== '') {\n    parts.push(\n      `\\n**Interactive Elements** (for typing: target <input> elements with fieldLabel, NOT parent <div> containers):\\n${result.elementList}`\n    );\n  }\n  if (result.screenshot != null && result.screenshot !== '') {\n    parts.push('\\n[Screenshot captured and displayed to user]');\n  }\n\n  if (parts.length === 0) {\n    if (!result.success) {\n      return `Browser action \"${action}\" failed: ${result.error || 'Unknown error'}`;\n    }\n    return `Browser action \"${action}\" completed successfully.`;\n  }\n\n  return parts.join('\\n');\n}\n\n/**\n * Create browser tools with optional callback for waiting on results\n *\n * When waitForResult callback is provided:\n * 1. Tool returns marker that triggers extension\n * 2. Tool then awaits callback to get actual results\n * 3. Returns real page state to LLM\n *\n * When no callback:\n * 1. Tool returns marker only (for non-server contexts)\n *\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\n */\nexport function createBrowserTools(\n  options?: CreateBrowserToolsOptions\n): DynamicStructuredTool[] {\n  const { waitForResult } = options || {};\n  const tools: DynamicStructuredTool[] = [];\n\n  /**\n   * Helper to create tool function that optionally waits for results\n   * The toolCallId is extracted from the RunnableConfig passed by LangChain\n   */\n  const createToolFunction = (action: string) => {\n    return async (\n      args: Record<string, unknown>,\n      config?: { toolCall?: { id?: string } }\n    ): Promise<string> => {\n      const toolCallId =\n        config?.toolCall?.id ??\n        `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;\n\n      // Create marker for extension\n      const marker: BrowserToolResponse = {\n        requiresBrowserExecution: true,\n        action,\n        args,\n        toolCallId,\n      };\n\n      // If no callback, return marker immediately (extension handles via SSE interception)\n      if (!waitForResult) {\n        return JSON.stringify(marker);\n      }\n\n      // With callback: wait for actual results from extension\n      // The marker is still returned initially via SSE, but we wait for the callback\n      try {\n        const result = await waitForResult(action, args, toolCallId);\n        return formatResultForLLM(result, action);\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return `Browser action \"${action}\" failed: ${errorMessage}`;\n      }\n    };\n  };\n\n  // browser_click\n  tools.push(\n    tool(createToolFunction('click'), {\n      name: EBrowserTools.CLICK,\n      description:\n        'Click element by [index]. Use fieldLabel attribute to identify correct element. For form fields, target <input> elements NOT parent <div> containers.',\n      schema: BrowserClickSchema,\n    })\n  );\n\n  // browser_type\n  tools.push(\n    tool(createToolFunction('type'), {\n      name: EBrowserTools.TYPE,\n      description:\n        'Type text into <input> element by [index]. CRITICAL: Always target <input> or <textarea> tags (NOT parent <div> containers). Use fieldLabel to identify correct field (e.g., fieldLabel=\"To recipients\" for To field).',\n      schema: BrowserTypeSchema,\n    })\n  );\n\n  // browser_navigate\n  tools.push(\n    tool(createToolFunction('navigate'), {\n      name: EBrowserTools.NAVIGATE,\n      description:\n        'Navigate to URL (include https://). Returns new page element list.',\n      schema: BrowserNavigateSchema,\n    })\n  );\n\n  // browser_scroll\n  tools.push(\n    tool(createToolFunction('scroll'), {\n      name: EBrowserTools.SCROLL,\n      description:\n        'Scroll page (up/down/left/right). Returns updated element list.',\n      schema: BrowserScrollSchema,\n    })\n  );\n\n  // browser_extract\n  tools.push(\n    tool(createToolFunction('extract'), {\n      name: EBrowserTools.EXTRACT,\n      description:\n        'Extract page content. Returns URL, title, and element list.',\n      schema: BrowserExtractSchema,\n    })\n  );\n\n  // browser_hover\n  tools.push(\n    tool(createToolFunction('hover'), {\n      name: EBrowserTools.HOVER,\n      description:\n        'Hover element by [index] to reveal menus/tooltips. Returns updated element list.',\n      schema: BrowserHoverSchema,\n    })\n  );\n\n  // browser_wait\n  tools.push(\n    tool(createToolFunction('wait'), {\n      name: EBrowserTools.WAIT,\n      description:\n        'Wait for async content to load. Returns updated element list.',\n      schema: BrowserWaitSchema,\n    })\n  );\n\n  // browser_back\n  tools.push(\n    tool(createToolFunction('back'), {\n      name: EBrowserTools.BACK,\n      description:\n        'Go back in browser history. Returns previous page element list.',\n      schema: BrowserBackSchema,\n    })\n  );\n\n  // browser_screenshot\n  tools.push(\n    tool(createToolFunction('screenshot'), {\n      name: EBrowserTools.SCREENSHOT,\n      description:\n        'Capture screenshot. Displayed to user. Use get_page_state for automation.',\n      schema: BrowserScreenshotSchema,\n    })\n  );\n\n  // browser_get_page_state\n  tools.push(\n    tool(createToolFunction('get_page_state'), {\n      name: EBrowserTools.GET_PAGE_STATE,\n      description:\n        'Get page URL, title, and interactive elements with [index] for actions. Start here.',\n      schema: BrowserGetPageStateSchema,\n    })\n  );\n\n  // browser_keypress - for keyboard shortcuts\n  tools.push(\n    tool(createToolFunction('keypress'), {\n      name: EBrowserTools.KEYPRESS,\n      description:\n        'Send keyboard shortcut or key press. Use for: Control+Enter (send email/submit), Escape (close dialog/cancel), Tab (next field), Enter (confirm). The keys are sent to the currently focused element.',\n      schema: BrowserKeypressSchema,\n    })\n  );\n\n  // browser_switch_tab - for switching between tabs\n  tools.push(\n    tool(createToolFunction('switch_tab'), {\n      name: EBrowserTools.SWITCH_TAB,\n      description:\n        'Switch to a different browser tab by its ID. Tab IDs are shown in the page state. Use this to work with existing open tabs (e.g., use existing Gmail tab instead of opening a new one).',\n      schema: BrowserSwitchTabSchema,\n    })\n  );\n\n  return tools;\n}\n"],"names":["z","tools","tool"],"mappings":"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"}

package/dist/cjs/tools/Calculator.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"Calculator.cjs","sources":["../../../src/tools/Calculator.ts"],"sourcesContent":["import { Tool } from '@langchain/core/tools';\nimport * as math from 'mathjs';\n\nexport const CalculatorToolName = 'calculator';\n\nexport const CalculatorToolDescription =\n  'Useful for getting the result of a math expression. The input to this tool should be a valid mathematical expression that could be executed by a simple calculator.';\n\nexport const CalculatorSchema = {\n  type: 'object',\n  properties: {\n    input: {\n      type: 'string',\n      description: 'A valid mathematical expression to evaluate',\n    },\n  },\n  required: ['input'],\n} as const;\n\nexport const CalculatorToolDefinition = {\n  name: CalculatorToolName,\n  description: CalculatorToolDescription,\n  schema: CalculatorSchema,\n} as const;\n\nexport class Calculator extends Tool {\n  static lc_name(): string {\n    return 'Calculator';\n  }\n\n  get lc_namespace(): string[] {\n    return [...super.lc_namespace, 'calculator'];\n  }\n\n  name = CalculatorToolName;\n\n  async _call(input: string): Promise<string> {\n    try {\n      return math.evaluate(input).toString();\n    } catch {\n      return 'I don\\'t know how to do that.';\n    }\n  }\n\n  description = CalculatorToolDescription;\n}\n"],"names":["Tool","math"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAGO,MAAM,kBAAkB,GAAG;AAE3B,MAAM,yBAAyB,GACpC;AAEW,MAAA,gBAAgB,GAAG;AAC9B,IAAA,IAAI,EAAE,QAAQ;AACd,IAAA,UAAU,EAAE;AACV,QAAA,KAAK,EAAE;AACL,YAAA,IAAI,EAAE,QAAQ;AACd,YAAA,WAAW,EAAE,6CAA6C;AAC3D,SAAA;AACF,KAAA;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;;AAGR,MAAA,wBAAwB,GAAG;AACtC,IAAA,IAAI,EAAE,kBAAkB;AACxB,IAAA,WAAW,EAAE,yBAAyB;AACtC,IAAA,MAAM,EAAE,gBAAgB;;AAGpB,MAAO,UAAW,SAAQA,UAAI,CAAA;AAClC,IAAA,OAAO,OAAO,GAAA;AACZ,QAAA,OAAO,YAAY;;AAGrB,IAAA,IAAI,YAAY,GAAA;QACd,OAAO,CAAC,GAAG,KAAK,CAAC,YAAY,EAAE,YAAY,CAAC;;IAG9C,IAAI,GAAG,kBAAkB;IAEzB,MAAM,KAAK,CAAC,KAAa,EAAA;AACvB,QAAA,IAAI;YACF,OAAOC,eAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE;;AACtC,QAAA,MAAM;AACN,YAAA,OAAO,+BAA+B;;;IAI1C,WAAW,GAAG,yBAAyB;AACxC;;;;;;;;"}
+{"version":3,"file":"Calculator.cjs","sources":["../../../src/tools/Calculator.ts"],"sourcesContent":["import { Tool } from '@langchain/core/tools';\nimport * as math from 'mathjs';\n\nexport const CalculatorToolName = 'calculator';\n\nexport const CalculatorToolDescription =\n  'Useful for getting the result of a math expression. The input to this tool should be a valid mathematical expression that could be executed by a simple calculator.';\n\nexport const CalculatorSchema = {\n  type: 'object',\n  properties: {\n    input: {\n      type: 'string',\n      description: 'A valid mathematical expression to evaluate',\n    },\n  },\n  required: ['input'],\n} as const;\n\nexport const CalculatorToolDefinition = {\n  name: CalculatorToolName,\n  description: CalculatorToolDescription,\n  schema: CalculatorSchema,\n} as const;\n\nexport class Calculator extends Tool {\n  static lc_name(): string {\n    return 'Calculator';\n  }\n\n  get lc_namespace(): string[] {\n    return [...super.lc_namespace, 'calculator'];\n  }\n\n  name = CalculatorToolName;\n\n  async _call(input: string): Promise<string> {\n    try {\n      return math.evaluate(input).toString();\n    } catch {\n      return 'I don\\'t know how to do that.';\n    }\n  }\n\n  description = CalculatorToolDescription;\n}\n"],"names":["Tool","math"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAGO,MAAM,kBAAkB,GAAG;AAE3B,MAAM,yBAAyB,GACpC;AAEK,MAAM,gBAAgB,GAAG;AAC9B,IAAA,IAAI,EAAE,QAAQ;AACd,IAAA,UAAU,EAAE;AACV,QAAA,KAAK,EAAE;AACL,YAAA,IAAI,EAAE,QAAQ;AACd,YAAA,WAAW,EAAE,6CAA6C;AAC3D,SAAA;AACF,KAAA;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;;AAGd,MAAM,wBAAwB,GAAG;AACtC,IAAA,IAAI,EAAE,kBAAkB;AACxB,IAAA,WAAW,EAAE,yBAAyB;AACtC,IAAA,MAAM,EAAE,gBAAgB;;AAGpB,MAAO,UAAW,SAAQA,UAAI,CAAA;AAClC,IAAA,OAAO,OAAO,GAAA;AACZ,QAAA,OAAO,YAAY;IACrB;AAEA,IAAA,IAAI,YAAY,GAAA;QACd,OAAO,CAAC,GAAG,KAAK,CAAC,YAAY,EAAE,YAAY,CAAC;IAC9C;IAEA,IAAI,GAAG,kBAAkB;IAEzB,MAAM,KAAK,CAAC,KAAa,EAAA;AACvB,QAAA,IAAI;YACF,OAAOC,eAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE;QACxC;AAAE,QAAA,MAAM;AACN,YAAA,OAAO,+BAA+B;QACxC;IACF;IAEA,WAAW,GAAG,yBAAyB;AACxC;;;;;;;;"}

package/dist/cjs/tools/CodeExecutor.cjs

@@ -14,7 +14,7 @@ const getCodeBaseURL = () => env.getEnvironmentVariable(_enum.EnvVar.CODE_BASEUR
 const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
 const accessMessage = 'Note: Files from previous executions are automatically available and can be modified.';
-const emptyOutputMessage = 'stdout: Empty. Ensure you\'re writing output explicitly.\n';
+const emptyOutputMessage = "stdout: Empty. Ensure you're writing output explicitly.\n";
 const SUPPORTED_LANGUAGES = [
     'py',
     'js',
@@ -28,6 +28,7 @@ const SUPPORTED_LANGUAGES = [
     'd',
     'f90',
     'r',
+    'bash',
 ];
 const CodeExecutionToolSchema = {
     type: 'object',
@@ -60,8 +61,6 @@ const CodeExecutionToolSchema = {
     },
     required: ['lang', 'code'],
 };
-const baseEndpoint = getCodeBaseURL();
-const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
 const CodeExecutionToolDescription = `
 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.
 
@@ -106,6 +105,9 @@ Rules:
 - Generated files auto-delivered (no download links needed)
 `.trim();
     return tools.tool(async (rawInput, config) => {
+        // Resolve URL at call time (not module load time) to pick up env var changes
+        const baseEndpoint = getCodeBaseURL();
+        const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
         const { lang, code, ...rest } = rawInput;
         /**
          * Extract session context from config.toolCall (injected by ToolNode).
@@ -190,6 +192,22 @@ Rules:
             }
             const result = await response.json();
             let formattedOutput = '';
+            let stdoutCapped = false;
+            // Self-healing: Cap large stdout to prevent context bloat.
+            // Preserves head (8KB) + tail (4KB) so the agent sees beginning and end.
+            const STDOUT_MAX_CHARS = 16384;
+            const STDOUT_HEAD_CHARS = 8192;
+            const STDOUT_TAIL_CHARS = 4096;
+            if (result.stdout && result.stdout.length > STDOUT_MAX_CHARS) {
+                const originalLen = result.stdout.length;
+                const head = result.stdout.substring(0, STDOUT_HEAD_CHARS);
+                const tail = result.stdout.substring(result.stdout.length - STDOUT_TAIL_CHARS);
+                const omitted = originalLen - STDOUT_HEAD_CHARS - STDOUT_TAIL_CHARS;
+                result.stdout = `${head}\n\n[...${omitted} chars omitted...]\n\n${tail}`;
+                stdoutCapped = true;
+                // eslint-disable-next-line no-console
+                console.debug(`[CodeExecutor] stdout capped: ${originalLen} → ${result.stdout.length} chars`);
+            }
             if (result.stdout) {
                 formattedOutput += `stdout:\n${result.stdout}\n`;
             }
@@ -198,6 +216,30 @@ Rules:
             }
             if (result.stderr)
                 formattedOutput += `stderr:\n${result.stderr}\n`;
+            // Self-healing: Detect code truncation (syntax error on long code).
+            // When the agent's generated code is >1500 chars and produces a SyntaxError,
+            // it's likely truncated mid-generation rather than a real bug.
+            const CODE_TRUNCATION_MIN_CHARS = 1500;
+            if (result.stderr && code.length > CODE_TRUNCATION_MIN_CHARS) {
+                const stderrLower = result.stderr.toLowerCase();
+                if (stderrLower.includes('syntaxerror') ||
+                    stderrLower.includes('unexpected end') ||
+                    stderrLower.includes('unexpected eof') ||
+                    stderrLower.includes('unterminated')) {
+                    // eslint-disable-next-line no-console
+                    console.debug(`[CodeExecutor] Code truncation detected: code=${code.length} chars, stderr contains syntax error`);
+                    formattedOutput +=
+                        '\n[CODE_TRUNCATION_LIKELY] Your code appears truncated mid-generation.' +
+                            ' Split into multiple smaller execute_code calls (max 60 lines each).' +
+                            ' For documents: create+save first, then open+append+save in follow-up calls.' +
+                            ' Do NOT retry the same long code block.';
+                }
+            }
+            // Self-healing: Advisory when stdout was capped
+            if (stdoutCapped) {
+                formattedOutput +=
+                    '\n[OUTPUT_TOO_LARGE] stdout was capped. Use targeted print() for specific values.';
+            }
             if (result.files && result.files.length > 0) {
                 formattedOutput += 'Generated files:\n';
                 const fileCount = result.files.length;
@@ -221,7 +263,7 @@ Rules:
             return [formattedOutput.trim(), { session_id: result.session_id }];
         }
         catch (error) {
-            throw new Error(`Execution error:\n\n${error?.message}`);
+            throw new Error(`Execution error (${EXEC_ENDPOINT}):\n\n${error?.message}`);
         }
     }, {
         name: CodeExecutionToolName,

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

@@ -1 +1 @@
-{"version":3,"file":"CodeExecutor.cjs","sources":["../../../src/tools/CodeExecutor.ts"],"sourcesContent":["import { 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 from previous executions are automatically available and can be modified.';\nconst emptyOutputMessage =\n  'stdout: Empty. Ensure you\\'re writing output explicitly.\\n';\n\nconst SUPPORTED_LANGUAGES = [\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] as const;\n\nexport const CodeExecutionToolSchema = {\n  type: 'object',\n  properties: {\n    lang: {\n      type: 'string',\n      enum: SUPPORTED_LANGUAGES,\n      description:\n        'The programming language or runtime to execute the code in.',\n    },\n    code: {\n      type: 'string',\n      description: `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- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\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    },\n    args: {\n      type: 'array',\n      items: { type: 'string' },\n      description:\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  required: ['lang', 'code'],\n} as const;\n\nconst baseEndpoint = getCodeBaseURL();\nconst EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\ntype SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];\n\nexport const CodeExecutionToolDescription = `\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\nexport const CodeExecutionToolName = Constants.EXECUTE_CODE;\n\nexport const CodeExecutionToolDefinition = {\n  name: CodeExecutionToolName,\n  description: CodeExecutionToolDescription,\n  schema: CodeExecutionToolSchema,\n} as const;\n\nfunction createCodeExecutionTool(\n  params: t.CodeExecutionToolParams = {}\n): DynamicStructuredTool {\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 = `\n⛔ STOP! Before using this tool, ask: \"Does user need a DOWNLOADABLE FILE?\"\n- If NO (dashboard, chart, visualization, UI) → DO NOT USE THIS TOOL. Use content_tool write instead.\n- If YES (.pptx, .docx, .pdf, .xlsx) → Use this tool.\n\nRuns code in a stateless execution environment. Each execution is isolated.\n\n🚫 NEVER USE FOR:\n- Dashboards, charts, visualizations → Use content_tool write with React/Chart.js\n- \"Mock data\" or \"sample data\" for display → Hardcode data in content_tool write\n- UI components, HTML pages, React apps → Use content_tool write\n\n✅ ONLY USE FOR:\n- File generation: PowerPoint (.pptx), Word (.docx), PDF (.pdf), Excel (.xlsx)\n- Processing uploaded files (CSV, Excel analysis)\n- Heavy computation requiring Python\n\nRules:\n- No network access available\n- Generated files auto-delivered (no download links needed)\n`.trim();\n\n  return tool(\n    async (rawInput, config) => {\n      const { lang, code, ...rest } = rawInput as {\n        lang: SupportedLanguage;\n        code: string;\n        args?: string[];\n      };\n      /**\n       * Extract session context from config.toolCall (injected by ToolNode).\n       * - session_id: For API to associate with previous session\n       * - _injected_files: File refs to pass directly (avoids /files endpoint race condition)\n       */\n      const { session_id, _injected_files } = (config.toolCall ?? {}) as {\n        session_id?: string;\n        _injected_files?: t.CodeEnvFile[];\n      };\n\n      const postData: Record<string, unknown> = {\n        lang,\n        code,\n        ...rest,\n        ...params,\n      };\n\n      /**\n       * Pass session_id to /exec so code-executor reuses the existing session workspace.\n       * This allows retries and follow-up executions to access previously generated files.\n       */\n      if (session_id != null && session_id.length > 0) {\n        postData.session_id = session_id;\n      }\n\n      /**\n       * File injection priority:\n       * 1. Use _injected_files from ToolNode (avoids /files endpoint race condition)\n       * 2. Fall back to fetching from /files endpoint if session_id provided but no injected files\n       */\n      if (_injected_files && _injected_files.length > 0) {\n        postData.files = _injected_files;\n      } else if (session_id != null && session_id.length > 0) {\n        /** Fallback: fetch from /files endpoint (may have race condition issues) */\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              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            postData.files = fileReferences;\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 += `\\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: CodeExecutionToolName,\n      description,\n      schema: CodeExecutionToolSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport { createCodeExecutionTool };\n"],"names":["config","getEnvironmentVariable","EnvVar","Constants","tool","HttpsProxyAgent"],"mappings":"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"}
+{"version":3,"file":"CodeExecutor.cjs","sources":["../../../src/tools/CodeExecutor.ts"],"sourcesContent":["import { 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 from previous executions are automatically available and can be modified.';\nconst emptyOutputMessage =\n  \"stdout: Empty. Ensure you're writing output explicitly.\\n\";\n\nconst SUPPORTED_LANGUAGES = [\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  'bash',\n] as const;\n\nexport const CodeExecutionToolSchema = {\n  type: 'object',\n  properties: {\n    lang: {\n      type: 'string',\n      enum: SUPPORTED_LANGUAGES,\n      description:\n        'The programming language or runtime to execute the code in.',\n    },\n    code: {\n      type: 'string',\n      description: `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- Generated files from previous executions are automatically available in \"/mnt/data/\".\n- Files from previous executions are automatically available and can be modified in place.\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    },\n    args: {\n      type: 'array',\n      items: { type: 'string' },\n      description:\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  required: ['lang', 'code'],\n} as const;\n\n// NOTE: Resolved at call time inside the tool function, not at module load time.\n// Module-level caching caused stale URLs when env vars changed between restarts.\n\ntype SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];\n\nexport const CodeExecutionToolDescription = `\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\nexport const CodeExecutionToolName = Constants.EXECUTE_CODE;\n\nexport const CodeExecutionToolDefinition = {\n  name: CodeExecutionToolName,\n  description: CodeExecutionToolDescription,\n  schema: CodeExecutionToolSchema,\n} as const;\n\nfunction createCodeExecutionTool(\n  params: t.CodeExecutionToolParams = {}\n): DynamicStructuredTool {\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 = `\n⛔ STOP! Before using this tool, ask: \"Does user need a DOWNLOADABLE FILE?\"\n- If NO (dashboard, chart, visualization, UI) → DO NOT USE THIS TOOL. Use content_tool write instead.\n- If YES (.pptx, .docx, .pdf, .xlsx) → Use this tool.\n\nRuns code in a stateless execution environment. Each execution is isolated.\n\n🚫 NEVER USE FOR:\n- Dashboards, charts, visualizations → Use content_tool write with React/Chart.js\n- \"Mock data\" or \"sample data\" for display → Hardcode data in content_tool write\n- UI components, HTML pages, React apps → Use content_tool write\n\n✅ ONLY USE FOR:\n- File generation: PowerPoint (.pptx), Word (.docx), PDF (.pdf), Excel (.xlsx)\n- Processing uploaded files (CSV, Excel analysis)\n- Heavy computation requiring Python\n\nRules:\n- No network access available\n- Generated files auto-delivered (no download links needed)\n`.trim();\n\n  return tool(\n    async (rawInput, config) => {\n      // Resolve URL at call time (not module load time) to pick up env var changes\n      const baseEndpoint = getCodeBaseURL();\n      const EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\n      const { lang, code, ...rest } = rawInput as {\n        lang: SupportedLanguage;\n        code: string;\n        args?: string[];\n      };\n      /**\n       * Extract session context from config.toolCall (injected by ToolNode).\n       * - session_id: For API to associate with previous session\n       * - _injected_files: File refs to pass directly (avoids /files endpoint race condition)\n       */\n      const { session_id, _injected_files } = (config.toolCall ?? {}) as {\n        session_id?: string;\n        _injected_files?: t.CodeEnvFile[];\n      };\n\n      const postData: Record<string, unknown> = {\n        lang,\n        code,\n        ...rest,\n        ...params,\n      };\n\n      /**\n       * Pass session_id to /exec so code-executor reuses the existing session workspace.\n       * This allows retries and follow-up executions to access previously generated files.\n       */\n      if (session_id != null && session_id.length > 0) {\n        postData.session_id = session_id;\n      }\n\n      /**\n       * File injection priority:\n       * 1. Use _injected_files from ToolNode (avoids /files endpoint race condition)\n       * 2. Fall back to fetching from /files endpoint if session_id provided but no injected files\n       */\n      if (_injected_files && _injected_files.length > 0) {\n        postData.files = _injected_files;\n      } else if (session_id != null && session_id.length > 0) {\n        /** Fallback: fetch from /files endpoint (may have race condition issues) */\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              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            postData.files = fileReferences;\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        let stdoutCapped = false;\n\n        // Self-healing: Cap large stdout to prevent context bloat.\n        // Preserves head (8KB) + tail (4KB) so the agent sees beginning and end.\n        const STDOUT_MAX_CHARS = 16384;\n        const STDOUT_HEAD_CHARS = 8192;\n        const STDOUT_TAIL_CHARS = 4096;\n        if (result.stdout && result.stdout.length > STDOUT_MAX_CHARS) {\n          const originalLen = result.stdout.length;\n          const head = result.stdout.substring(0, STDOUT_HEAD_CHARS);\n          const tail = result.stdout.substring(\n            result.stdout.length - STDOUT_TAIL_CHARS\n          );\n          const omitted = originalLen - STDOUT_HEAD_CHARS - STDOUT_TAIL_CHARS;\n          result.stdout = `${head}\\n\\n[...${omitted} chars omitted...]\\n\\n${tail}`;\n          stdoutCapped = true;\n          // eslint-disable-next-line no-console\n          console.debug(\n            `[CodeExecutor] stdout capped: ${originalLen} → ${result.stdout.length} chars`\n          );\n        }\n\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\n        // Self-healing: Detect code truncation (syntax error on long code).\n        // When the agent's generated code is >1500 chars and produces a SyntaxError,\n        // it's likely truncated mid-generation rather than a real bug.\n        const CODE_TRUNCATION_MIN_CHARS = 1500;\n        if (result.stderr && code.length > CODE_TRUNCATION_MIN_CHARS) {\n          const stderrLower = result.stderr.toLowerCase();\n          if (\n            stderrLower.includes('syntaxerror') ||\n            stderrLower.includes('unexpected end') ||\n            stderrLower.includes('unexpected eof') ||\n            stderrLower.includes('unterminated')\n          ) {\n            // eslint-disable-next-line no-console\n            console.debug(\n              `[CodeExecutor] Code truncation detected: code=${code.length} chars, stderr contains syntax error`\n            );\n            formattedOutput +=\n              '\\n[CODE_TRUNCATION_LIKELY] Your code appears truncated mid-generation.' +\n              ' Split into multiple smaller execute_code calls (max 60 lines each).' +\n              ' For documents: create+save first, then open+append+save in follow-up calls.' +\n              ' Do NOT retry the same long code block.';\n          }\n        }\n\n        // Self-healing: Advisory when stdout was capped\n        if (stdoutCapped) {\n          formattedOutput +=\n            '\\n[OUTPUT_TOO_LARGE] stdout was capped. Use targeted print() for specific values.';\n        }\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 += `\\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 (${EXEC_ENDPOINT}):\\n\\n${(error as Error | undefined)?.message}`\n        );\n      }\n    },\n    {\n      name: CodeExecutionToolName,\n      description,\n      schema: CodeExecutionToolSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport { createCodeExecutionTool };\n"],"names":["config","getEnvironmentVariable","EnvVar","Constants","tool","HttpsProxyAgent"],"mappings":";;;;;;;;;AAQAA,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,uFAAuF;AACzF,MAAM,kBAAkB,GACtB,2DAA2D;AAE7D,MAAM,mBAAmB,GAAG;IAC1B,IAAI;IACJ,IAAI;IACJ,IAAI;IACJ,GAAG;IACH,KAAK;IACL,MAAM;IACN,KAAK;IACL,IAAI;IACJ,IAAI;IACJ,GAAG;IACH,KAAK;IACL,GAAG;IACH,MAAM;CACE;AAEH,MAAM,uBAAuB,GAAG;AACrC,IAAA,IAAI,EAAE,QAAQ;AACd,IAAA,UAAU,EAAE;AACV,QAAA,IAAI,EAAE;AACJ,YAAA,IAAI,EAAE,QAAQ;AACd,YAAA,IAAI,EAAE,mBAAmB;AACzB,YAAA,WAAW,EACT,6DAA6D;AAChE,SAAA;AACD,QAAA,IAAI,EAAE;AACJ,YAAA,IAAI,EAAE,QAAQ;AACd,YAAA,WAAW,EAAE,CAAA;;;;;;;;;;;AAWkC,oDAAA,CAAA;AAChD,SAAA;AACD,QAAA,IAAI,EAAE;AACJ,YAAA,IAAI,EAAE,OAAO;AACb,YAAA,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;AACzB,YAAA,WAAW,EACT,iIAAiI;AACpI,SAAA;AACF,KAAA;AACD,IAAA,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;;AAQrB,MAAM,4BAA4B,GAAG;;;;;;;CAO3C,CAAC,IAAI;AAEC,MAAM,qBAAqB,GAAGA,eAAS,CAAC;AAExC,MAAM,2BAA2B,GAAG;AACzC,IAAA,IAAI,EAAE,qBAAqB;AAC3B,IAAA,WAAW,EAAE,4BAA4B;AACzC,IAAA,MAAM,EAAE,uBAAuB;;AAGjC,SAAS,uBAAuB,CAC9B,MAAA,GAAoC,EAAE,EAAA;AAEtC,IAAA,MAAM,MAAM,GACV,MAAM,CAACD,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;IACjE;AAEA,IAAA,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;CAoBrB,CAAC,IAAI,EAAE;IAEN,OAAOE,UAAI,CACT,OAAO,QAAQ,EAAE,MAAM,KAAI;;AAEzB,QAAA,MAAM,YAAY,GAAG,cAAc,EAAE;AACrC,QAAA,MAAM,aAAa,GAAG,CAAA,EAAG,YAAY,OAAO;QAE5C,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,QAI/B;AACD;;;;AAIG;AACH,QAAA,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,IAAI,MAAM,CAAC,QAAQ,IAAI,EAAE,CAG7D;AAED,QAAA,MAAM,QAAQ,GAA4B;YACxC,IAAI;YACJ,IAAI;AACJ,YAAA,GAAG,IAAI;AACP,YAAA,GAAG,MAAM;SACV;AAED;;;AAGG;QACH,IAAI,UAAU,IAAI,IAAI,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE;AAC/C,YAAA,QAAQ,CAAC,UAAU,GAAG,UAAU;QAClC;AAEA;;;;AAIG;QACH,IAAI,eAAe,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE;AACjD,YAAA,QAAQ,CAAC,KAAK,GAAG,eAAe;QAClC;aAAO,IAAI,UAAU,IAAI,IAAI,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE;;AAEtD,YAAA,IAAI;AACF,gBAAA,MAAM,aAAa,GAAG,CAAA,EAAG,YAAY,CAAA,OAAA,EAAU,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;gBAC7D;gBAEA,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,CAAA,CAAE,CACxD;gBACH;AAEA,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;wBACzD,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,oBAAA,CAAC,CAAC;AAEF,oBAAA,QAAQ,CAAC,KAAK,GAAG,cAAc;gBACjC;YACF;AAAE,YAAA,MAAM;;AAEN,gBAAA,OAAO,CAAC,IAAI,CAAC,sCAAsC,UAAU,CAAA,CAAE,CAAC;YAClE;QACF;AAEA,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;YAC7D;YACA,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,CAAA,CAAE,CAAC;YAC3D;AAEA,YAAA,MAAM,MAAM,GAAoB,MAAM,QAAQ,CAAC,IAAI,EAAE;YACrD,IAAI,eAAe,GAAG,EAAE;YACxB,IAAI,YAAY,GAAG,KAAK;;;YAIxB,MAAM,gBAAgB,GAAG,KAAK;YAC9B,MAAM,iBAAiB,GAAG,IAAI;YAC9B,MAAM,iBAAiB,GAAG,IAAI;AAC9B,YAAA,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,gBAAgB,EAAE;AAC5D,gBAAA,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM;AACxC,gBAAA,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,iBAAiB,CAAC;AAC1D,gBAAA,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAClC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,iBAAiB,CACzC;AACD,gBAAA,MAAM,OAAO,GAAG,WAAW,GAAG,iBAAiB,GAAG,iBAAiB;gBACnE,MAAM,CAAC,MAAM,GAAG,CAAA,EAAG,IAAI,WAAW,OAAO,CAAA,sBAAA,EAAyB,IAAI,CAAA,CAAE;gBACxE,YAAY,GAAG,IAAI;;AAEnB,gBAAA,OAAO,CAAC,KAAK,CACX,CAAA,8BAAA,EAAiC,WAAW,CAAA,GAAA,EAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAA,MAAA,CAAQ,CAC/E;YACH;AAEA,YAAA,IAAI,MAAM,CAAC,MAAM,EAAE;AACjB,gBAAA,eAAe,IAAI,CAAA,SAAA,EAAY,MAAM,CAAC,MAAM,IAAI;YAClD;iBAAO;gBACL,eAAe,IAAI,kBAAkB;YACvC;YACA,IAAI,MAAM,CAAC,MAAM;AAAE,gBAAA,eAAe,IAAI,CAAA,SAAA,EAAY,MAAM,CAAC,MAAM,IAAI;;;;YAKnE,MAAM,yBAAyB,GAAG,IAAI;YACtC,IAAI,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,yBAAyB,EAAE;gBAC5D,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE;AAC/C,gBAAA,IACE,WAAW,CAAC,QAAQ,CAAC,aAAa,CAAC;AACnC,oBAAA,WAAW,CAAC,QAAQ,CAAC,gBAAgB,CAAC;AACtC,oBAAA,WAAW,CAAC,QAAQ,CAAC,gBAAgB,CAAC;AACtC,oBAAA,WAAW,CAAC,QAAQ,CAAC,cAAc,CAAC,EACpC;;oBAEA,OAAO,CAAC,KAAK,CACX,CAAA,8CAAA,EAAiD,IAAI,CAAC,MAAM,CAAA,oCAAA,CAAsC,CACnG;oBACD,eAAe;wBACb,wEAAwE;4BACxE,sEAAsE;4BACtE,8EAA8E;AAC9E,4BAAA,yCAAyC;gBAC7C;YACF;;YAGA,IAAI,YAAY,EAAE;gBAChB,eAAe;AACb,oBAAA,mFAAmF;YACvF;AAEA,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,CAAA,YAAA,EAAe,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;oBAClD;gBACF;AAEA,gBAAA,eAAe,IAAI,CAAA,IAAA,EAAO,aAAa,CAAA,CAAE;gBACzC,OAAO;oBACL,eAAe,CAAC,IAAI,EAAE;AACtB,oBAAA;wBACE,UAAU,EAAE,MAAM,CAAC,UAAU;wBAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;AACpB,qBAAA;iBACF;YACH;AAEA,YAAA,OAAO,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;QACpE;QAAE,OAAO,KAAK,EAAE;YACd,MAAM,IAAI,KAAK,CACb,CAAA,iBAAA,EAAoB,aAAa,CAAA,MAAA,EAAU,KAA2B,EAAE,OAAO,CAAA,CAAE,CAClF;QACH;AACF,IAAA,CAAC,EACD;AACE,QAAA,IAAI,EAAE,qBAAqB;QAC3B,WAAW;AACX,QAAA,MAAM,EAAE,uBAAuB;QAC/B,cAAc,EAAEF,eAAS,CAAC,oBAAoB;AAC/C,KAAA,CACF;AACH;;;;;;;;;;"}

package/dist/cjs/tools/ProgrammaticToolCalling.cjs

@@ -22,24 +22,21 @@ const DEFAULT_MAX_ROUND_TRIPS = 20;
 /** Default execution timeout in milliseconds */
 const DEFAULT_TIMEOUT = 60000;
 // ============================================================================
-// Schema
+// Description Components (Single Source of Truth)
 // ============================================================================
-const ProgrammaticToolCallingSchema = {
-    type: 'object',
-    properties: {
-        code: {
-            type: 'string',
-            minLength: 1,
-            description: `Python code that calls tools programmatically. Tools are available as async functions.
-
-CRITICAL - STATELESS EXECUTION:
+const STATELESS_WARNING = `CRITICAL - STATELESS EXECUTION:
 Each call is a fresh Python interpreter. Variables, imports, and data do NOT persist between calls.
 You MUST complete your entire workflow in ONE code block: query → process → output.
-DO NOT split work across multiple calls expecting to reuse variables.
-
-Your code is auto-wrapped in async context. Just write logic with await—no boilerplate needed.
-
-Example (Complete workflow in one call):
+DO NOT split work across multiple calls expecting to reuse variables.`;
+const CORE_RULES = `Rules:
+- EVERYTHING in one call—no state persists between executions
+- Just write code with await—auto-wrapped in async context
+- DO NOT define async def main() or call asyncio.run()
+- Tools are pre-defined—DO NOT write function definitions
+- Only print() output returns to the model`;
+const ADDITIONAL_RULES = `- Generated files are automatically available in /mnt/data/ for subsequent executions
+- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix`;
+const EXAMPLES = `Example (Complete workflow in one call):
   # Query data
   data = await query_database(sql="SELECT * FROM users")
   # Process it
@@ -51,14 +48,26 @@ Example (Complete workflow in one call):
 
 Example (Parallel calls):
   sf, ny = await asyncio.gather(get_weather(city="SF"), get_weather(city="NY"))
-  print(f"SF: {sf}, NY: {ny}")
+  print(f"SF: {sf}, NY: {ny}")`;
+// ============================================================================
+// Schema
+// ============================================================================
+const CODE_PARAM_DESCRIPTION = `Python code that calls tools programmatically. Tools are available as async functions.
 
-Rules:
-- EVERYTHING in one call—no state persists between executions
-- Just write code with await—auto-wrapped in async context
-- DO NOT define async def main() or call asyncio.run()
-- Tools are pre-defined—DO NOT write function definitions
-- Only print() output returns to the model`,
+${STATELESS_WARNING}
+
+Your code is auto-wrapped in async context. Just write logic with await—no boilerplate needed.
+
+${EXAMPLES}
+
+${CORE_RULES}`;
+const ProgrammaticToolCallingSchema = {
+    type: 'object',
+    properties: {
+        code: {
+            type: 'string',
+            minLength: 1,
+            description: CODE_PARAM_DESCRIPTION,
         },
         timeout: {
             type: 'integer',
@@ -74,21 +83,14 @@ const ProgrammaticToolCallingName = _enum.Constants.PROGRAMMATIC_TOOL_CALLING;
 const ProgrammaticToolCallingDescription = `
 Run tools via Python code. Auto-wrapped in async context—just use \`await\` directly.
 
-CRITICAL - STATELESS: Each call is a fresh interpreter. Variables/imports do NOT persist.
-Complete your ENTIRE workflow in ONE call: fetch → process → save. No splitting across calls.
+${STATELESS_WARNING}
 
-Rules:
-- Everything in ONE code block—no state carries over between executions
-- Do NOT define \`async def main()\` or call \`asyncio.run()\`—just write code with await
-- Tools are pre-defined—DO NOT write function definitions
-- Only \`print()\` output returns; tool results are raw dicts/lists/strings
-- Generated files are automatically available in /mnt/data/ for subsequent executions
-- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix
+${CORE_RULES}
+${ADDITIONAL_RULES}
 
 When to use: loops, conditionals, parallel (\`asyncio.gather\`), multi-step pipelines.
 
-Example (complete pipeline):
-  data = await query_db(sql="..."); df = process(data); await save_to_sheet(data=df); print("Done")
+${EXAMPLES}
 `.trim();
 const ProgrammaticToolCallingDefinition = {
     name: ProgrammaticToolCallingName,
@@ -513,25 +515,6 @@ function createProgrammaticToolCallingTool(initParams = {}) {
     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 via Python code. Auto-wrapped in async context—just use \`await\` directly.
-
-CRITICAL - STATELESS: Each call is a fresh interpreter. Variables/imports do NOT persist.
-Complete your ENTIRE workflow in ONE call: fetch → process → save. No splitting across calls.
-
-Rules:
-- Everything in ONE code block—no state carries over between executions
-- Do NOT define \`async def main()\` or call \`asyncio.run()\`—just write code with await
-- Tools are pre-defined—DO NOT write function definitions
-- Only \`print()\` output returns; tool results are raw dicts/lists/strings
-- Generated files are automatically available in /mnt/data/ for subsequent executions
-- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix
-
-When to use: loops, conditionals, parallel (\`asyncio.gather\`), multi-step pipelines.
-
-Example (complete pipeline):
-  data = await query_db(sql="..."); df = process(data); await save_to_sheet(data=df); print("Done")
-`.trim();
     return tools.tool(async (rawParams, config) => {
         const params = rawParams;
         const { code, timeout = DEFAULT_TIMEOUT } = params;
@@ -614,7 +597,7 @@ Example (complete pipeline):
         }
     }, {
         name: _enum.Constants.PROGRAMMATIC_TOOL_CALLING,
-        description,
+        description: ProgrammaticToolCallingDescription,
         schema: ProgrammaticToolCallingSchema,
         responseFormat: _enum.Constants.CONTENT_AND_ARTIFACT,
     });