@librechat/agents 3.1.88 → 3.1.90

package/dist/cjs/tools/BashProgrammaticToolCalling.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"BashProgrammaticToolCalling.cjs","sources":["../../../src/tools/BashProgrammaticToolCalling.ts"],"sourcesContent":["import { config } from 'dotenv';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type { ToolCall } from '@langchain/core/messages/tool';\nimport type { ProgrammaticToolCallingJsonSchema } from './ptcTimeout';\nimport type * as t from '@/types';\nimport {\n  makeRequest,\n  executeTools,\n  formatCompletedResponse,\n} from './ProgrammaticToolCalling';\nimport { getCodeBaseURL } from './CodeExecutor';\nimport {\n  clampCodeApiRunTimeoutMs,\n  createCodeApiRunTimeoutSchema,\n  resolveCodeApiRunTimeoutMs,\n} from './ptcTimeout';\nimport { Constants } from '@/common';\n\nconfig();\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst DEFAULT_MAX_ROUND_TRIPS = 20;\nconst DEFAULT_RUN_TIMEOUT_MS = resolveCodeApiRunTimeoutMs();\n\n/** Bash reserved words that get `_tool` suffix when used as function names */\nconst BASH_RESERVED = new Set([\n  'if',\n  'then',\n  'else',\n  'elif',\n  'fi',\n  'case',\n  'esac',\n  'for',\n  'while',\n  'until',\n  'do',\n  'done',\n  'in',\n  'function',\n  'select',\n  'time',\n  'coproc',\n  'declare',\n  'typeset',\n  'local',\n  'readonly',\n  'export',\n  'unset',\n]);\n\n// ============================================================================\n// Description Components\n// ============================================================================\n\nconst STATELESS_WARNING = `CRITICAL - STATELESS EXECUTION:\nEach call is a fresh bash shell. Variables and state do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block.\nDO NOT split work across multiple calls expecting to reuse variables.`;\n\nconst CORE_RULES = `Rules:\n- EVERYTHING in one call—no state persists between executions\n- Tools are pre-defined as bash functions—DO NOT redefine them\n- Each tool function accepts a JSON string argument\n- Only echo/printf output returns to the model\n- Generated files are automatically available in /mnt/data/ for subsequent executions\n- timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;\n\nconst ADDITIONAL_RULES =\n  '- Tool names normalized: hyphens→underscores, reserved words get `_tool` suffix';\n\nconst EXAMPLES = `Example (Complete workflow in one call):\n  # Query data and process\n  data=$(query_database '{\"sql\": \"SELECT * FROM users\"}')\n  echo \"$data\" | jq '.[] | .name'\n\nExample (Parallel calls):\n  web_search '{\"query\": \"SF weather\"}' > /tmp/sf.txt &\n  web_search '{\"query\": \"NY weather\"}' > /tmp/ny.txt &\n  wait\n  echo \"SF: $(cat /tmp/sf.txt)\"\n  echo \"NY: $(cat /tmp/ny.txt)\"`;\n\nconst CODE_PARAM_DESCRIPTION = `Bash code that calls tools programmatically. Tools are available as bash functions.\n\n${STATELESS_WARNING}\n\nEach tool function accepts a JSON string as its argument.\nExample: tool_name '{\"key\": \"value\"}'\n\n${EXAMPLES}\n\n${CORE_RULES}`;\n\n// ============================================================================\n// Schema\n// ============================================================================\n\nexport function createBashProgrammaticToolCallingSchema(\n  maxRunTimeoutMs = DEFAULT_RUN_TIMEOUT_MS\n): ProgrammaticToolCallingJsonSchema {\n  return {\n    type: 'object',\n    properties: {\n      code: {\n        type: 'string',\n        minLength: 1,\n        description: CODE_PARAM_DESCRIPTION,\n      },\n      timeout: createCodeApiRunTimeoutSchema(maxRunTimeoutMs),\n    },\n    required: ['code'],\n  } as const;\n}\n\nexport const BashProgrammaticToolCallingSchema =\n  createBashProgrammaticToolCallingSchema();\n\nexport const BashProgrammaticToolCallingName =\n  Constants.BASH_PROGRAMMATIC_TOOL_CALLING;\n\nexport const BashProgrammaticToolCallingDescription = `\nRun tools via bash code. Tools are available as bash functions that accept JSON string arguments.\n\n${STATELESS_WARNING}\n\n${CORE_RULES}\n${ADDITIONAL_RULES}\n\nWhen to use: shell pipelines, parallel execution (& and wait), file processing, text manipulation.\n\n${EXAMPLES}\n`.trim();\n\nexport const BashProgrammaticToolCallingDefinition = {\n  name: BashProgrammaticToolCallingName,\n  description: BashProgrammaticToolCallingDescription,\n  schema: BashProgrammaticToolCallingSchema,\n} as const;\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/**\n * Normalizes a tool name to a valid bash function identifier.\n * 1. Replace hyphens, spaces, dots with underscores\n * 2. Remove any other invalid characters\n * 3. Prefix with underscore if starts with number\n * 4. Append `_tool` if it's a bash reserved word\n */\nexport function normalizeToBashIdentifier(name: string): string {\n  let normalized = name.replace(/[-\\s.]/g, '_');\n  normalized = normalized.replace(/[^a-zA-Z0-9_]/g, '');\n\n  if (/^[0-9]/.test(normalized)) {\n    normalized = '_' + normalized;\n  }\n\n  if (BASH_RESERVED.has(normalized)) {\n    normalized = normalized + '_tool';\n  }\n\n  return normalized;\n}\n\n/**\n * Extracts tool names that are actually called in the bash code.\n * Bash functions are invoked as commands (no parentheses), so we match\n * the normalized name as a word boundary.\n */\nexport function extractUsedBashToolNames(\n  code: string,\n  toolNameMap: Map<string, string>\n): Set<string> {\n  const usedTools = new Set<string>();\n\n  for (const [bashName, originalName] of toolNameMap) {\n    const escapedName = bashName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n    const pattern = new RegExp(`\\\\b${escapedName}\\\\b`, 'g');\n\n    if (pattern.test(code)) {\n      usedTools.add(originalName);\n    }\n  }\n\n  return usedTools;\n}\n\n/**\n * Filters tool definitions to only include tools actually used in the bash code.\n */\nexport function filterBashToolsByUsage(\n  toolDefs: t.LCTool[],\n  code: string,\n  debug = false\n): t.LCTool[] {\n  const toolNameMap = new Map<string, string>();\n  for (const def of toolDefs) {\n    const bashName = normalizeToBashIdentifier(def.name);\n    toolNameMap.set(bashName, def.name);\n  }\n\n  const usedToolNames = extractUsedBashToolNames(code, toolNameMap);\n\n  if (debug) {\n    // eslint-disable-next-line no-console\n    console.log(\n      `[BashPTC Debug] Tool filtering: found ${usedToolNames.size}/${toolDefs.length} tools in code`\n    );\n    if (usedToolNames.size > 0) {\n      // eslint-disable-next-line no-console\n      console.log(\n        `[BashPTC Debug] Matched tools: ${Array.from(usedToolNames).join(', ')}`\n      );\n    }\n  }\n\n  if (usedToolNames.size === 0) {\n    if (debug) {\n      // eslint-disable-next-line no-console\n      console.log(\n        '[BashPTC Debug] No tools detected in code - sending all tools as fallback'\n      );\n    }\n    return toolDefs;\n  }\n\n  return toolDefs.filter((def) => usedToolNames.has(def.name));\n}\n\n// ============================================================================\n// Tool Factory\n// ============================================================================\n\n/**\n * Creates a Bash Programmatic Tool Calling tool for multi-tool orchestration.\n *\n * This tool enables AI agents to write bash scripts that orchestrate multiple\n * tool calls programmatically via the remote Code API, reducing LLM round-trips.\n *\n * The tool map must be provided at runtime via config.toolCall (injected by ToolNode).\n */\nexport function createBashProgrammaticToolCallingTool(\n  initParams: t.BashProgrammaticToolCallingParams = {}\n): DynamicStructuredTool {\n  const baseUrl = initParams.baseUrl ?? getCodeBaseURL();\n  const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;\n  const maxRunTimeoutMs = resolveCodeApiRunTimeoutMs(initParams.runTimeoutMs);\n  const proxy = initParams.proxy ?? process.env.PROXY;\n  const debug = initParams.debug ?? process.env.BASH_PTC_DEBUG === 'true';\n  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;\n\n  return tool(\n    async (rawParams, config) => {\n      const params = rawParams as { code: string; timeout?: number };\n      const { code } = params;\n      const timeout = clampCodeApiRunTimeoutMs(params.timeout, maxRunTimeoutMs);\n\n      const toolCall = (config.toolCall ?? {}) as ToolCall &\n        Partial<t.ProgrammaticCache> & {\n          session_id?: string;\n          _injected_files?: t.CodeEnvFile[];\n        };\n      const { toolMap, toolDefs, session_id, _injected_files } = toolCall;\n\n      if (toolMap == null || toolMap.size === 0) {\n        throw new Error(\n          'No toolMap provided. ' +\n            'ToolNode should inject this from AgentContext when invoked through the graph.'\n        );\n      }\n\n      if (toolDefs == null || toolDefs.length === 0) {\n        throw new Error(\n          'No tool definitions provided. ' +\n            'Either pass tools in the input or ensure ToolNode injects toolDefs.'\n        );\n      }\n\n      let roundTrip = 0;\n\n      try {\n        // ====================================================================\n        // Phase 1: Filter tools and make initial request\n        // ====================================================================\n\n        const effectiveTools = filterBashToolsByUsage(toolDefs, code, debug);\n\n        if (debug) {\n          // eslint-disable-next-line no-console\n          console.log(\n            `[BashPTC Debug] Sending ${effectiveTools.length} tools to API ` +\n              `(filtered from ${toolDefs.length})`\n          );\n        }\n\n        /* `/files/<session_id>` HTTP fallback removed — codeapi's\n         * sessionAuth requires kind/id query params unavailable at\n         * this point. See `CodeExecutor.ts` for full rationale. */\n        let files: t.CodeEnvFile[] | undefined;\n        if (_injected_files && _injected_files.length > 0) {\n          files = _injected_files;\n        } else if (session_id != null && session_id.length > 0) {\n          // eslint-disable-next-line no-console\n          console.debug(\n            `[BashProgrammaticToolCalling] No injected files for session_id=${session_id} — exec will run without input files`\n          );\n        }\n\n        let response = await makeRequest(\n          EXEC_ENDPOINT,\n          {\n            lang: 'bash',\n            code,\n            tools: effectiveTools,\n            session_id,\n            timeout,\n            ...(files && files.length > 0 ? { files } : {}),\n          },\n          proxy,\n          initParams.authHeaders\n        );\n\n        // ====================================================================\n        // Phase 2: Handle response loop\n        // ====================================================================\n\n        while (response.status === 'tool_call_required') {\n          roundTrip++;\n\n          if (roundTrip > maxRoundTrips) {\n            throw new Error(\n              `Exceeded maximum round trips (${maxRoundTrips}). ` +\n                'This may indicate an infinite loop, excessive tool calls, ' +\n                'or a logic error in your code.'\n            );\n          }\n\n          if (debug) {\n            // eslint-disable-next-line no-console\n            console.log(\n              `[BashPTC Debug] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`\n            );\n          }\n\n          const toolResults = await executeTools(\n            response.tool_calls ?? [],\n            toolMap,\n            Constants.BASH_PROGRAMMATIC_TOOL_CALLING\n          );\n\n          response = await makeRequest(\n            EXEC_ENDPOINT,\n            {\n              continuation_token: response.continuation_token,\n              tool_results: toolResults,\n            },\n            proxy,\n            initParams.authHeaders\n          );\n        }\n\n        // ====================================================================\n        // Phase 3: Handle final state\n        // ====================================================================\n\n        if (response.status === 'completed') {\n          return formatCompletedResponse(response);\n        }\n\n        if (response.status === 'error') {\n          throw new Error(\n            `Execution error: ${response.error}` +\n              (response.stderr != null && response.stderr !== ''\n                ? `\\n\\nStderr:\\n${response.stderr}`\n                : '')\n          );\n        }\n\n        throw new Error(`Unexpected response status: ${response.status}`);\n      } catch (error) {\n        throw new Error(\n          `Bash programmatic execution failed: ${(error as Error).message}`\n        );\n      }\n    },\n    {\n      name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,\n      description: BashProgrammaticToolCallingDescription,\n      schema: createBashProgrammaticToolCallingSchema(maxRunTimeoutMs),\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n"],"names":["config","resolveCodeApiRunTimeoutMs","createCodeApiRunTimeoutSchema","Constants","getCodeBaseURL","tool","clampCodeApiRunTimeoutMs","makeRequest","executeTools","formatCompletedResponse"],"mappings":";;;;;;;;;AAkBAA,aAAM,EAAE;AAER;AACA;AACA;AAEA,MAAM,uBAAuB,GAAG,EAAE;AAClC,MAAM,sBAAsB,GAAGC,qCAA0B,EAAE;AAE3D;AACA,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,IAAI;IACJ,MAAM;IACN,MAAM;IACN,MAAM;IACN,IAAI;IACJ,MAAM;IACN,MAAM;IACN,KAAK;IACL,OAAO;IACP,OAAO;IACP,IAAI;IACJ,MAAM;IACN,IAAI;IACJ,UAAU;IACV,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,SAAS;IACT,SAAS;IACT,OAAO;IACP,UAAU;IACV,QAAQ;IACR,OAAO;AACR,CAAA,CAAC;AAEF;AACA;AACA;AAEA,MAAM,iBAAiB,GAAG,CAAA;;;sEAG4C;AAEtE,MAAM,UAAU,GAAG,CAAA;;;;;;yFAMsE;AAEzF,MAAM,gBAAgB,GACpB,iFAAiF;AAEnF,MAAM,QAAQ,GAAG,CAAA;;;;;;;;;;gCAUe;AAEhC,MAAM,sBAAsB,GAAG,CAAA;;EAE7B,iBAAiB;;;;;EAKjB,QAAQ;;AAER,EAAA,UAAU,EAAE;AAEd;AACA;AACA;AAEM,SAAU,uCAAuC,CACrD,eAAe,GAAG,sBAAsB,EAAA;IAExC,OAAO;AACL,QAAA,IAAI,EAAE,QAAQ;AACd,QAAA,UAAU,EAAE;AACV,YAAA,IAAI,EAAE;AACJ,gBAAA,IAAI,EAAE,QAAQ;AACd,gBAAA,SAAS,EAAE,CAAC;AACZ,gBAAA,WAAW,EAAE,sBAAsB;AACpC,aAAA;AACD,YAAA,OAAO,EAAEC,wCAA6B,CAAC,eAAe,CAAC;AACxD,SAAA;QACD,QAAQ,EAAE,CAAC,MAAM,CAAC;KACV;AACZ;AAEO,MAAM,iCAAiC,GAC5C,uCAAuC;AAElC,MAAM,+BAA+B,GAC1CC,eAAS,CAAC;AAEL,MAAM,sCAAsC,GAAG;;;EAGpD,iBAAiB;;EAEjB,UAAU;EACV,gBAAgB;;;;EAIhB,QAAQ;CACT,CAAC,IAAI;AAEC,MAAM,qCAAqC,GAAG;AACnD,IAAA,IAAI,EAAE,+BAA+B;AACrC,IAAA,WAAW,EAAE,sCAAsC;AACnD,IAAA,MAAM,EAAE,iCAAiC;;AAG3C;AACA;AACA;AAEA;;;;;;AAMG;AACG,SAAU,yBAAyB,CAAC,IAAY,EAAA;IACpD,IAAI,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;IAC7C,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;AAErD,IAAA,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE;AAC7B,QAAA,UAAU,GAAG,GAAG,GAAG,UAAU;IAC/B;AAEA,IAAA,IAAI,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE;AACjC,QAAA,UAAU,GAAG,UAAU,GAAG,OAAO;IACnC;AAEA,IAAA,OAAO,UAAU;AACnB;AAEA;;;;AAIG;AACG,SAAU,wBAAwB,CACtC,IAAY,EACZ,WAAgC,EAAA;AAEhC,IAAA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU;IAEnC,KAAK,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,IAAI,WAAW,EAAE;QAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC;QACnE,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,CAAA,GAAA,EAAM,WAAW,CAAA,GAAA,CAAK,EAAE,GAAG,CAAC;AAEvD,QAAA,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;AACtB,YAAA,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC;QAC7B;IACF;AAEA,IAAA,OAAO,SAAS;AAClB;AAEA;;AAEG;AACG,SAAU,sBAAsB,CACpC,QAAoB,EACpB,IAAY,EACZ,KAAK,GAAG,KAAK,EAAA;AAEb,IAAA,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB;AAC7C,IAAA,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE;QAC1B,MAAM,QAAQ,GAAG,yBAAyB,CAAC,GAAG,CAAC,IAAI,CAAC;QACpD,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC;IACrC;IAEA,MAAM,aAAa,GAAG,wBAAwB,CAAC,IAAI,EAAE,WAAW,CAAC;IAEjE,IAAI,KAAK,EAAE;;AAET,QAAA,OAAO,CAAC,GAAG,CACT,CAAA,sCAAA,EAAyC,aAAa,CAAC,IAAI,CAAA,CAAA,EAAI,QAAQ,CAAC,MAAM,CAAA,cAAA,CAAgB,CAC/F;AACD,QAAA,IAAI,aAAa,CAAC,IAAI,GAAG,CAAC,EAAE;;AAE1B,YAAA,OAAO,CAAC,GAAG,CACT,CAAA,+BAAA,EAAkC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA,CAAE,CACzE;QACH;IACF;AAEA,IAAA,IAAI,aAAa,CAAC,IAAI,KAAK,CAAC,EAAE;QAC5B,IAAI,KAAK,EAAE;;AAET,YAAA,OAAO,CAAC,GAAG,CACT,2EAA2E,CAC5E;QACH;AACA,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC9D;AAEA;AACA;AACA;AAEA;;;;;;;AAOG;AACG,SAAU,qCAAqC,CACnD,UAAA,GAAkD,EAAE,EAAA;IAEpD,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,IAAIC,2BAAc,EAAE;AACtD,IAAA,MAAM,aAAa,GAAG,UAAU,CAAC,aAAa,IAAI,uBAAuB;IACzE,MAAM,eAAe,GAAGH,qCAA0B,CAAC,UAAU,CAAC,YAAY,CAAC;IAC3E,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK;AACnD,IAAA,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,MAAM;AACvE,IAAA,MAAM,aAAa,GAAG,CAAA,EAAG,OAAO,oBAAoB;IAEpD,OAAOI,UAAI,CACT,OAAO,SAAS,EAAE,MAAM,KAAI;QAC1B,MAAM,MAAM,GAAG,SAA+C;AAC9D,QAAA,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM;QACvB,MAAM,OAAO,GAAGC,mCAAwB,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC;QAEzE,MAAM,QAAQ,IAAI,MAAM,CAAC,QAAQ,IAAI,EAAE,CAIpC;QACH,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,QAAQ;QAEnE,IAAI,OAAO,IAAI,IAAI,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE;YACzC,MAAM,IAAI,KAAK,CACb,uBAAuB;AACrB,gBAAA,+EAA+E,CAClF;QACH;QAEA,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE;YAC7C,MAAM,IAAI,KAAK,CACb,gCAAgC;AAC9B,gBAAA,qEAAqE,CACxE;QACH;QAEA,IAAI,SAAS,GAAG,CAAC;AAEjB,QAAA,IAAI;;;;YAKF,MAAM,cAAc,GAAG,sBAAsB,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC;YAEpE,IAAI,KAAK,EAAE;;AAET,gBAAA,OAAO,CAAC,GAAG,CACT,2BAA2B,cAAc,CAAC,MAAM,CAAA,cAAA,CAAgB;AAC9D,oBAAA,CAAA,eAAA,EAAkB,QAAQ,CAAC,MAAM,CAAA,CAAA,CAAG,CACvC;YACH;AAEA;;AAE2D;AAC3D,YAAA,IAAI,KAAkC;YACtC,IAAI,eAAe,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE;gBACjD,KAAK,GAAG,eAAe;YACzB;iBAAO,IAAI,UAAU,IAAI,IAAI,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE;;AAEtD,gBAAA,OAAO,CAAC,KAAK,CACX,kEAAkE,UAAU,CAAA,oCAAA,CAAsC,CACnH;YACH;AAEA,YAAA,IAAI,QAAQ,GAAG,MAAMC,mCAAW,CAC9B,aAAa,EACb;AACE,gBAAA,IAAI,EAAE,MAAM;gBACZ,IAAI;AACJ,gBAAA,KAAK,EAAE,cAAc;gBACrB,UAAU;gBACV,OAAO;AACP,gBAAA,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAChD,aAAA,EACD,KAAK,EACL,UAAU,CAAC,WAAW,CACvB;;;;AAMD,YAAA,OAAO,QAAQ,CAAC,MAAM,KAAK,oBAAoB,EAAE;AAC/C,gBAAA,SAAS,EAAE;AAEX,gBAAA,IAAI,SAAS,GAAG,aAAa,EAAE;AAC7B,oBAAA,MAAM,IAAI,KAAK,CACb,CAAA,8BAAA,EAAiC,aAAa,CAAA,GAAA,CAAK;wBACjD,4DAA4D;AAC5D,wBAAA,gCAAgC,CACnC;gBACH;gBAEA,IAAI,KAAK,EAAE;;AAET,oBAAA,OAAO,CAAC,GAAG,CACT,CAAA,2BAAA,EAA8B,SAAS,CAAA,EAAA,EAAK,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC,CAAA,mBAAA,CAAqB,CAClG;gBACH;AAEA,gBAAA,MAAM,WAAW,GAAG,MAAMC,oCAAY,CACpC,QAAQ,CAAC,UAAU,IAAI,EAAE,EACzB,OAAO,EACPL,eAAS,CAAC,8BAA8B,CACzC;AAED,gBAAA,QAAQ,GAAG,MAAMI,mCAAW,CAC1B,aAAa,EACb;oBACE,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB;AAC/C,oBAAA,YAAY,EAAE,WAAW;AAC1B,iBAAA,EACD,KAAK,EACL,UAAU,CAAC,WAAW,CACvB;YACH;;;;AAMA,YAAA,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE;AACnC,gBAAA,OAAOE,+CAAuB,CAAC,QAAQ,CAAC;YAC1C;AAEA,YAAA,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE;AAC/B,gBAAA,MAAM,IAAI,KAAK,CACb,oBAAoB,QAAQ,CAAC,KAAK,CAAA,CAAE;qBACjC,QAAQ,CAAC,MAAM,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK;AAC9C,0BAAE,CAAA,aAAA,EAAgB,QAAQ,CAAC,MAAM,CAAA;AACjC,0BAAE,EAAE,CAAC,CACV;YACH;YAEA,MAAM,IAAI,KAAK,CAAC,CAAA,4BAAA,EAA+B,QAAQ,CAAC,MAAM,CAAA,CAAE,CAAC;QACnE;QAAE,OAAO,KAAK,EAAE;YACd,MAAM,IAAI,KAAK,CACb,CAAA,oCAAA,EAAwC,KAAe,CAAC,OAAO,CAAA,CAAE,CAClE;QACH;AACF,IAAA,CAAC,EACD;QACE,IAAI,EAAEN,eAAS,CAAC,8BAA8B;AAC9C,QAAA,WAAW,EAAE,sCAAsC;AACnD,QAAA,MAAM,EAAE,uCAAuC,CAAC,eAAe,CAAC;QAChE,cAAc,EAAEA,eAAS,CAAC,oBAAoB;AAC/C,KAAA,CACF;AACH;;;;;;;;;;;;"}
+{"version":3,"file":"BashProgrammaticToolCalling.cjs","sources":["../../../src/tools/BashProgrammaticToolCalling.ts"],"sourcesContent":["import { config } from 'dotenv';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type { ToolCall } from '@langchain/core/messages/tool';\nimport type { ProgrammaticToolCallingJsonSchema } from './ptcTimeout';\nimport type * as t from '@/types';\nimport {\n  makeRequest,\n  executeTools,\n  formatCompletedResponse,\n} from './ProgrammaticToolCalling';\nimport {\n  BASH_SHELL_GUIDANCE,\n  CODE_ARTIFACT_PATH_GUIDANCE,\n  appendFailedExecutionFileReminder,\n  getCodeBaseURL,\n} from './CodeExecutor';\nimport {\n  clampCodeApiRunTimeoutMs,\n  createCodeApiRunTimeoutSchema,\n  resolveCodeApiRunTimeoutMs,\n} from './ptcTimeout';\nimport { Constants } from '@/common';\n\nconfig();\n\n// ============================================================================\n// Constants\n// ============================================================================\n\nconst DEFAULT_MAX_ROUND_TRIPS = 20;\nconst DEFAULT_RUN_TIMEOUT_MS = resolveCodeApiRunTimeoutMs();\n\n/** Bash reserved words that get `_tool` suffix when used as function names */\nconst BASH_RESERVED = new Set([\n  'if',\n  'then',\n  'else',\n  'elif',\n  'fi',\n  'case',\n  'esac',\n  'for',\n  'while',\n  'until',\n  'do',\n  'done',\n  'in',\n  'function',\n  'select',\n  'time',\n  'coproc',\n  'declare',\n  'typeset',\n  'local',\n  'readonly',\n  'export',\n  'unset',\n]);\n\n// ============================================================================\n// Description Components\n// ============================================================================\n\nconst STATELESS_WARNING = `CRITICAL - STATELESS EXECUTION:\nEach call is a fresh bash shell. Variables and state do NOT persist between calls.\nYou MUST complete your entire workflow in ONE code block.\nDO NOT split work across multiple calls expecting to reuse variables.`;\n\nconst CORE_RULES = `Rules:\n- One call: state does not persist\n- Tools are pre-defined as bash functions—DO NOT redefine them\n- Each tool function accepts a JSON string argument\n- Save tool output with raw=$(tool '{}'); printf '%s\\n' \"$raw\" > /mnt/data/file.json; direct tool > file may be empty\n- jq: use fromjson? // . on saved tool stdout and again on JSON-string fields; check types since arrays may contain strings\n- Only echo/printf output returns to the model\n- ${CODE_ARTIFACT_PATH_GUIDANCE}\n- ${BASH_SHELL_GUIDANCE}\n- timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;\n\nconst ADDITIONAL_RULES =\n  '- Tool names normalized: hyphens→underscores, reserved words get `_tool` suffix';\n\nconst EXAMPLES = `Example (Complete workflow in one call):\n  # Query data and process\n  data=$(query_database '{\"sql\": \"SELECT * FROM users\"}')\n  echo \"$data\" | jq '.[] | .name'\n\nExample (Parallel calls):\n  { sf=$(web_search '{\"query\": \"SF weather\"}'); printf '%s\\n' \"$sf\" > /mnt/data/sf.json; } &\n  { ny=$(web_search '{\"query\": \"NY weather\"}'); printf '%s\\n' \"$ny\" > /mnt/data/ny.json; } &\n  wait\n  echo \"SF: $(jq -r . /mnt/data/sf.json)\"\n  echo \"NY: $(jq -r . /mnt/data/ny.json)\"`;\n\nconst CODE_PARAM_DESCRIPTION = `Bash code that calls tools programmatically. Tools are available as bash functions.\n\n${STATELESS_WARNING}\n\nEach tool function accepts a JSON string as its argument.\nExample: tool_name '{\"key\": \"value\"}'\n\n${EXAMPLES}\n\n${CORE_RULES}`;\n\n// ============================================================================\n// Schema\n// ============================================================================\n\nexport function createBashProgrammaticToolCallingSchema(\n  maxRunTimeoutMs = DEFAULT_RUN_TIMEOUT_MS\n): ProgrammaticToolCallingJsonSchema {\n  return {\n    type: 'object',\n    properties: {\n      code: {\n        type: 'string',\n        minLength: 1,\n        description: CODE_PARAM_DESCRIPTION,\n      },\n      timeout: createCodeApiRunTimeoutSchema(maxRunTimeoutMs),\n    },\n    required: ['code'],\n  } as const;\n}\n\nexport const BashProgrammaticToolCallingSchema =\n  createBashProgrammaticToolCallingSchema();\n\nexport const BashProgrammaticToolCallingName =\n  Constants.BASH_PROGRAMMATIC_TOOL_CALLING;\n\nexport const BashProgrammaticToolCallingDescription = `\nRun tools via bash code. Tools are available as bash functions that accept JSON string arguments.\n\n${STATELESS_WARNING}\n\n${CORE_RULES}\n${ADDITIONAL_RULES}\n\nWhen to use: shell pipelines, parallel execution (& and wait), file processing, text manipulation.\n\n${EXAMPLES}\n`.trim();\n\nexport const BashProgrammaticToolCallingDefinition = {\n  name: BashProgrammaticToolCallingName,\n  description: BashProgrammaticToolCallingDescription,\n  schema: BashProgrammaticToolCallingSchema,\n} as const;\n\n// ============================================================================\n// Helper Functions\n// ============================================================================\n\n/**\n * Normalizes a tool name to a valid bash function identifier.\n * 1. Replace hyphens, spaces, dots with underscores\n * 2. Remove any other invalid characters\n * 3. Prefix with underscore if starts with number\n * 4. Append `_tool` if it's a bash reserved word\n */\nexport function normalizeToBashIdentifier(name: string): string {\n  let normalized = name.replace(/[-\\s.]/g, '_');\n  normalized = normalized.replace(/[^a-zA-Z0-9_]/g, '');\n\n  if (/^[0-9]/.test(normalized)) {\n    normalized = '_' + normalized;\n  }\n\n  if (BASH_RESERVED.has(normalized)) {\n    normalized = normalized + '_tool';\n  }\n\n  return normalized;\n}\n\n/**\n * Extracts tool names that are actually called in the bash code.\n * Bash functions are invoked as commands (no parentheses), so we match\n * the normalized name as a word boundary.\n */\nexport function extractUsedBashToolNames(\n  code: string,\n  toolNameMap: Map<string, string>\n): Set<string> {\n  const usedTools = new Set<string>();\n\n  for (const [bashName, originalName] of toolNameMap) {\n    const escapedName = bashName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n    const pattern = new RegExp(`\\\\b${escapedName}\\\\b`, 'g');\n\n    if (pattern.test(code)) {\n      usedTools.add(originalName);\n    }\n  }\n\n  return usedTools;\n}\n\n/**\n * Filters tool definitions to only include tools actually used in the bash code.\n */\nexport function filterBashToolsByUsage(\n  toolDefs: t.LCTool[],\n  code: string,\n  debug = false\n): t.LCTool[] {\n  const toolNameMap = new Map<string, string>();\n  for (const def of toolDefs) {\n    const bashName = normalizeToBashIdentifier(def.name);\n    toolNameMap.set(bashName, def.name);\n  }\n\n  const usedToolNames = extractUsedBashToolNames(code, toolNameMap);\n\n  if (debug) {\n    // eslint-disable-next-line no-console\n    console.log(\n      `[BashPTC Debug] Tool filtering: found ${usedToolNames.size}/${toolDefs.length} tools in code`\n    );\n    if (usedToolNames.size > 0) {\n      // eslint-disable-next-line no-console\n      console.log(\n        `[BashPTC Debug] Matched tools: ${Array.from(usedToolNames).join(', ')}`\n      );\n    }\n  }\n\n  if (usedToolNames.size === 0) {\n    if (debug) {\n      // eslint-disable-next-line no-console\n      console.log(\n        '[BashPTC Debug] No tools detected in code - sending all tools as fallback'\n      );\n    }\n    return toolDefs;\n  }\n\n  return toolDefs.filter((def) => usedToolNames.has(def.name));\n}\n\n// ============================================================================\n// Tool Factory\n// ============================================================================\n\n/**\n * Creates a Bash Programmatic Tool Calling tool for multi-tool orchestration.\n *\n * This tool enables AI agents to write bash scripts that orchestrate multiple\n * tool calls programmatically via the remote Code API, reducing LLM round-trips.\n *\n * The tool map must be provided at runtime via config.toolCall (injected by ToolNode).\n */\nexport function createBashProgrammaticToolCallingTool(\n  initParams: t.BashProgrammaticToolCallingParams = {}\n): DynamicStructuredTool {\n  const baseUrl = initParams.baseUrl ?? getCodeBaseURL();\n  const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;\n  const maxRunTimeoutMs = resolveCodeApiRunTimeoutMs(initParams.runTimeoutMs);\n  const proxy = initParams.proxy ?? process.env.PROXY;\n  const debug = initParams.debug ?? process.env.BASH_PTC_DEBUG === 'true';\n  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;\n\n  return tool(\n    async (rawParams, config) => {\n      const params = rawParams as { code: string; timeout?: number };\n      const { code } = params;\n      const timeout = clampCodeApiRunTimeoutMs(params.timeout, maxRunTimeoutMs);\n\n      const toolCall = (config.toolCall ?? {}) as ToolCall &\n        Partial<t.ProgrammaticCache> & {\n          session_id?: string;\n          _injected_files?: t.CodeEnvFile[];\n        };\n      const { toolMap, toolDefs, session_id, _injected_files } = toolCall;\n\n      if (toolMap == null || toolMap.size === 0) {\n        throw new Error(\n          'No toolMap provided. ' +\n            'ToolNode should inject this from AgentContext when invoked through the graph.'\n        );\n      }\n\n      if (toolDefs == null || toolDefs.length === 0) {\n        throw new Error(\n          'No tool definitions provided. ' +\n            'Either pass tools in the input or ensure ToolNode injects toolDefs.'\n        );\n      }\n\n      let roundTrip = 0;\n\n      try {\n        // ====================================================================\n        // Phase 1: Filter tools and make initial request\n        // ====================================================================\n\n        const effectiveTools = filterBashToolsByUsage(toolDefs, code, debug);\n\n        if (debug) {\n          // eslint-disable-next-line no-console\n          console.log(\n            `[BashPTC Debug] Sending ${effectiveTools.length} tools to API ` +\n              `(filtered from ${toolDefs.length})`\n          );\n        }\n\n        /* `/files/<session_id>` HTTP fallback removed — codeapi's\n         * sessionAuth requires kind/id query params unavailable at\n         * this point. See `CodeExecutor.ts` for full rationale. */\n        let files: t.CodeEnvFile[] | undefined;\n        if (_injected_files && _injected_files.length > 0) {\n          files = _injected_files;\n        } else if (session_id != null && session_id.length > 0) {\n          // eslint-disable-next-line no-console\n          console.debug(\n            `[BashProgrammaticToolCalling] No injected files for session_id=${session_id} — exec will run without input files`\n          );\n        }\n\n        let response = await makeRequest(\n          EXEC_ENDPOINT,\n          {\n            lang: 'bash',\n            code,\n            tools: effectiveTools,\n            session_id,\n            timeout,\n            ...(files && files.length > 0 ? { files } : {}),\n          },\n          proxy,\n          initParams.authHeaders\n        );\n\n        // ====================================================================\n        // Phase 2: Handle response loop\n        // ====================================================================\n\n        while (response.status === 'tool_call_required') {\n          roundTrip++;\n\n          if (roundTrip > maxRoundTrips) {\n            throw new Error(\n              `Exceeded maximum round trips (${maxRoundTrips}). ` +\n                'This may indicate an infinite loop, excessive tool calls, ' +\n                'or a logic error in your code.'\n            );\n          }\n\n          if (debug) {\n            // eslint-disable-next-line no-console\n            console.log(\n              `[BashPTC Debug] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`\n            );\n          }\n\n          const toolResults = await executeTools(\n            response.tool_calls ?? [],\n            toolMap,\n            Constants.BASH_PROGRAMMATIC_TOOL_CALLING\n          );\n\n          response = await makeRequest(\n            EXEC_ENDPOINT,\n            {\n              continuation_token: response.continuation_token,\n              tool_results: toolResults,\n            },\n            proxy,\n            initParams.authHeaders\n          );\n        }\n\n        // ====================================================================\n        // Phase 3: Handle final state\n        // ====================================================================\n\n        if (response.status === 'completed') {\n          return formatCompletedResponse(response, code);\n        }\n\n        if (response.status === 'error') {\n          throw new Error(\n            `Execution error: ${response.error}` +\n              (response.stderr != null && response.stderr !== ''\n                ? `\\n\\nStderr:\\n${response.stderr}`\n                : '')\n          );\n        }\n\n        throw new Error(`Unexpected response status: ${response.status}`);\n      } catch (error) {\n        const messageWithReminder = appendFailedExecutionFileReminder(\n          (error as Error).message,\n          code\n        );\n        throw new Error(\n          `Bash programmatic execution failed: ${messageWithReminder}`\n        );\n      }\n    },\n    {\n      name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,\n      description: BashProgrammaticToolCallingDescription,\n      schema: createBashProgrammaticToolCallingSchema(maxRunTimeoutMs),\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n"],"names":["config","resolveCodeApiRunTimeoutMs","CODE_ARTIFACT_PATH_GUIDANCE","BASH_SHELL_GUIDANCE","createCodeApiRunTimeoutSchema","Constants","getCodeBaseURL","tool","clampCodeApiRunTimeoutMs","makeRequest","executeTools","formatCompletedResponse","appendFailedExecutionFileReminder"],"mappings":"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"}

package/dist/cjs/tools/CodeExecutor.cjs

@@ -5,12 +5,32 @@ var fetch = require('node-fetch');
 var httpsProxyAgent = require('https-proxy-agent');
 var tools = require('@langchain/core/tools');
 var env = require('@langchain/core/utils/env');
+var CodeSessionFileSummary = require('./CodeSessionFileSummary.cjs');
 var _enum = require('../common/enum.cjs');
 
 dotenv.config();
 const getCodeBaseURL = () => env.getEnvironmentVariable(_enum.EnvVar.CODE_BASEURL) ??
     _enum.Constants.OFFICIAL_CODE_BASEURL;
 const emptyOutputMessage = 'stdout: Empty. Ensure you\'re writing output explicitly.\n';
+const CODE_ARTIFACT_PATH_GUIDANCE = 'Persist handoff artifacts in `/mnt/data` with standard extensions (.json/.txt/.csv/.tsv/.log/.parquet/.png/.jpg/.pdf/.xlsx); failed executions do not register new files; `/tmp` and odd extensions are same-call scratch only, not later-call storage.';
+const BASH_SHELL_GUIDANCE = 'Bash: multi-line files use heredoc/printf; run Python via python3 -c/heredoc, not bare Python.';
+const TMP_PATH_PATTERN = /(^|[^A-Za-z0-9_])\/tmp(?:\/|\b)/;
+const MNT_DATA_PATH_PATTERN = /(^|[^A-Za-z0-9_])\/mnt\/data(?:\/|\b)/;
+const TMP_SCRATCH_OUTPUT_REMINDER = 'Note: /tmp files are same-call scratch only and were not persisted; use /mnt/data for files needed later.';
+const FAILED_EXECUTION_FILE_REMINDER = 'Note: any files written during this failed call were not registered for later calls; fix the error and rerun before relying on them.';
+function appendTmpScratchReminder(output, code) {
+    if (!TMP_PATH_PATTERN.test(code)) {
+        return output;
+    }
+    return `${output.trimEnd()}\n${TMP_SCRATCH_OUTPUT_REMINDER}\n`;
+}
+function appendFailedExecutionFileReminder(output, code) {
+    if (!MNT_DATA_PATH_PATTERN.test(code) ||
+        output.includes(FAILED_EXECUTION_FILE_REMINDER)) {
+        return output;
+    }
+    return `${output.trimEnd()}\n${FAILED_EXECUTION_FILE_REMINDER}\n`;
+}
 const SUPPORTED_LANGUAGES = [
     'py',
     'js',
@@ -38,8 +58,8 @@ const CodeExecutionToolSchema = {
             type: 'string',
             description: `The complete, self-contained code to execute, without any truncation or minimization.
 - The environment is stateless; variables and imports don't persist between executions.
-- Generated files from previous executions are automatically available in "/mnt/data/".
-- Files from previous executions are automatically available and can be modified in place.
+- Prior /mnt/data files are available and can be modified in place.
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
 - Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.
 - Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.
 - IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.
@@ -86,6 +106,7 @@ Runs code and returns stdout/stderr output from a stateless execution environmen
 Usage:
 - No network access available.
 - Generated files are automatically delivered; **DO NOT** provide download links.
+- ${CODE_ARTIFACT_PATH_GUIDANCE}
 - NEVER use this tool to execute malicious code.
 `.trim();
 const CodeExecutionToolName = _enum.Constants.EXECUTE_CODE;
@@ -145,13 +166,6 @@ function createCodeExecutionTool(params = {}) {
                 throw new Error(await buildCodeApiHttpErrorMessage('POST', EXEC_ENDPOINT, response));
             }
             const result = await response.json();
-            /* Output is stdout/stderr only — file listings were removed
-             * because the LLM-facing summary (split inherited/generated
-             * with prescriptive notes) caused more confusion than help,
-             * especially for bash where models naturally explore
-             * `/mnt/data/` themselves. The artifact still carries every
-             * file so the host's session map stays in sync; the LLM
-             * doesn't see them in the tool result text. */
             let formattedOutput = '';
             if (result.stdout) {
                 formattedOutput += `stdout:\n${result.stdout}\n`;
@@ -161,9 +175,10 @@ function createCodeExecutionTool(params = {}) {
             }
             if (result.stderr)
                 formattedOutput += `stderr:\n${result.stderr}\n`;
+            const outputWithReminder = appendTmpScratchReminder(formattedOutput, code);
             const hasFiles = result.files != null && result.files.length > 0;
             return [
-                formattedOutput.trim(),
+                CodeSessionFileSummary.appendCodeSessionFileSummary(outputWithReminder, result.files),
                 (hasFiles
                     ? { session_id: result.session_id, files: result.files }
                     : {
@@ -172,7 +187,8 @@ function createCodeExecutionTool(params = {}) {
             ];
         }
         catch (error) {
-            throw new Error(`Execution error:\n\n${error?.message}`);
+            const messageWithReminder = appendFailedExecutionFileReminder(error?.message ?? '', code);
+            throw new Error(`Execution error:\n\n${messageWithReminder}`);
         }
     }, {
         name: CodeExecutionToolName,
@@ -182,10 +198,18 @@ function createCodeExecutionTool(params = {}) {
     });
 }
 
+exports.appendCodeSessionFileSummary = CodeSessionFileSummary.appendCodeSessionFileSummary;
+exports.stripCodeSessionFileSummary = CodeSessionFileSummary.stripCodeSessionFileSummary;
+exports.BASH_SHELL_GUIDANCE = BASH_SHELL_GUIDANCE;
+exports.CODE_ARTIFACT_PATH_GUIDANCE = CODE_ARTIFACT_PATH_GUIDANCE;
 exports.CodeExecutionToolDefinition = CodeExecutionToolDefinition;
 exports.CodeExecutionToolDescription = CodeExecutionToolDescription;
 exports.CodeExecutionToolName = CodeExecutionToolName;
 exports.CodeExecutionToolSchema = CodeExecutionToolSchema;
+exports.FAILED_EXECUTION_FILE_REMINDER = FAILED_EXECUTION_FILE_REMINDER;
+exports.TMP_SCRATCH_OUTPUT_REMINDER = TMP_SCRATCH_OUTPUT_REMINDER;
+exports.appendFailedExecutionFileReminder = appendFailedExecutionFileReminder;
+exports.appendTmpScratchReminder = appendTmpScratchReminder;
 exports.buildCodeApiHttpErrorMessage = buildCodeApiHttpErrorMessage;
 exports.createCodeExecutionTool = createCodeExecutionTool;
 exports.emptyOutputMessage = emptyOutputMessage;

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 getCodeBaseURL = (): string =>\n  getEnvironmentVariable(EnvVar.CODE_BASEURL) ??\n  Constants.OFFICIAL_CODE_BASEURL;\n\nexport const 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\nconst baseEndpoint = getCodeBaseURL();\nconst EXEC_ENDPOINT = `${baseEndpoint}/exec`;\n\ntype SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];\n\nexport async function resolveCodeApiAuthHeaders(\n  authHeaders?: t.CodeApiAuthHeaders\n): Promise<t.CodeApiAuthHeaderMap> {\n  if (authHeaders == null) {\n    return {};\n  }\n  if (typeof authHeaders === 'function') {\n    return authHeaders();\n  }\n  return authHeaders;\n}\n\nexport async function buildCodeApiHttpErrorMessage(\n  method: string,\n  endpoint: string,\n  response: { status: number; text: () => Promise<string> }\n): Promise<string> {\n  let responseBody = '';\n  try {\n    responseBody = await response.text();\n  } catch {\n    responseBody = '';\n  }\n  const body = responseBody.trim();\n  const bodySuffix = body === '' ? '' : `, body: ${body.slice(0, 1000)}`;\n  return `CodeAPI request failed: ${method} ${endpoint} returned ${response.status}${bodySuffix}`;\n}\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  return tool(\n    async (rawInput, config) => {\n      const { authHeaders, ...executionParams } = params ?? {};\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: associates with the previous run.\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        ...executionParams,\n      };\n\n      /* File injection: `_injected_files` from ToolNode (set when host\n       * primes a CodeSessionContext) or `params.files` from tool\n       * factory (set by hosts that pre-resolve at construction time).\n       * The legacy `/files/<session_id>` HTTP fallback was removed —\n       * codeapi's `sessionAuth` middleware now requires kind/id query\n       * params the tool can't supply at this point, so the fetch 400'd\n       * silently and the catch swallowed the failure. */\n      if (_injected_files && _injected_files.length > 0) {\n        postData.files = _injected_files;\n      } else if (\n        session_id != null &&\n        session_id.length > 0 &&\n        !Array.isArray(postData.files)\n      ) {\n        // eslint-disable-next-line no-console\n        console.debug(\n          `[CodeExecutor] No injected files for session_id=${session_id} — exec will run without input files`\n        );\n      }\n\n      try {\n        const resolvedAuthHeaders =\n          await resolveCodeApiAuthHeaders(authHeaders);\n        const fetchOptions: RequestInit = {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'User-Agent': 'LibreChat/1.0',\n            ...resolvedAuthHeaders,\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(\n            await buildCodeApiHttpErrorMessage('POST', EXEC_ENDPOINT, response)\n          );\n        }\n\n        const result: t.ExecuteResult = await response.json();\n        /* Output is stdout/stderr only — file listings were removed\n         * because the LLM-facing summary (split inherited/generated\n         * with prescriptive notes) caused more confusion than help,\n         * especially for bash where models naturally explore\n         * `/mnt/data/` themselves. The artifact still carries every\n         * file so the host's session map stays in sync; the LLM\n         * doesn't see them in the tool result text. */\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\n        const hasFiles = result.files != null && result.files.length > 0;\n        return [\n          formattedOutput.trim(),\n          (hasFiles\n            ? { session_id: result.session_id, files: result.files }\n            : {\n              session_id: result.session_id,\n            }) satisfies t.CodeExecutionArtifact,\n        ];\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: CodeExecutionToolDescription,\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 { appendCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';\nimport { EnvVar, Constants } from '@/common';\n\nexport {\n  appendCodeSessionFileSummary,\n  stripCodeSessionFileSummary,\n} from '@/tools/CodeSessionFileSummary';\n\nconfig();\n\nexport const getCodeBaseURL = (): string =>\n  getEnvironmentVariable(EnvVar.CODE_BASEURL) ??\n  Constants.OFFICIAL_CODE_BASEURL;\n\nexport const emptyOutputMessage =\n  'stdout: Empty. Ensure you\\'re writing output explicitly.\\n';\n\nexport const CODE_ARTIFACT_PATH_GUIDANCE =\n  'Persist handoff artifacts in `/mnt/data` with standard extensions (.json/.txt/.csv/.tsv/.log/.parquet/.png/.jpg/.pdf/.xlsx); failed executions do not register new files; `/tmp` and odd extensions are same-call scratch only, not later-call storage.';\n\nexport const BASH_SHELL_GUIDANCE =\n  'Bash: multi-line files use heredoc/printf; run Python via python3 -c/heredoc, not bare Python.';\n\nconst TMP_PATH_PATTERN = /(^|[^A-Za-z0-9_])\\/tmp(?:\\/|\\b)/;\nconst MNT_DATA_PATH_PATTERN = /(^|[^A-Za-z0-9_])\\/mnt\\/data(?:\\/|\\b)/;\n\nexport const TMP_SCRATCH_OUTPUT_REMINDER =\n  'Note: /tmp files are same-call scratch only and were not persisted; use /mnt/data for files needed later.';\n\nexport const FAILED_EXECUTION_FILE_REMINDER =\n  'Note: any files written during this failed call were not registered for later calls; fix the error and rerun before relying on them.';\n\nexport function appendTmpScratchReminder(output: string, code: string): string {\n  if (!TMP_PATH_PATTERN.test(code)) {\n    return output;\n  }\n  return `${output.trimEnd()}\\n${TMP_SCRATCH_OUTPUT_REMINDER}\\n`;\n}\n\nexport function appendFailedExecutionFileReminder(\n  output: string,\n  code: string\n): string {\n  if (\n    !MNT_DATA_PATH_PATTERN.test(code) ||\n    output.includes(FAILED_EXECUTION_FILE_REMINDER)\n  ) {\n    return output;\n  }\n  return `${output.trimEnd()}\\n${FAILED_EXECUTION_FILE_REMINDER}\\n`;\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- Prior /mnt/data files are available and can be modified in place.\n- ${CODE_ARTIFACT_PATH_GUIDANCE}\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 async function resolveCodeApiAuthHeaders(\n  authHeaders?: t.CodeApiAuthHeaders\n): Promise<t.CodeApiAuthHeaderMap> {\n  if (authHeaders == null) {\n    return {};\n  }\n  if (typeof authHeaders === 'function') {\n    return authHeaders();\n  }\n  return authHeaders;\n}\n\nexport async function buildCodeApiHttpErrorMessage(\n  method: string,\n  endpoint: string,\n  response: { status: number; text: () => Promise<string> }\n): Promise<string> {\n  let responseBody = '';\n  try {\n    responseBody = await response.text();\n  } catch {\n    responseBody = '';\n  }\n  const body = responseBody.trim();\n  const bodySuffix = body === '' ? '' : `, body: ${body.slice(0, 1000)}`;\n  return `CodeAPI request failed: ${method} ${endpoint} returned ${response.status}${bodySuffix}`;\n}\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- ${CODE_ARTIFACT_PATH_GUIDANCE}\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 | null = {}\n): DynamicStructuredTool {\n  return tool(\n    async (rawInput, config) => {\n      const { authHeaders, ...executionParams } = params ?? {};\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: associates with the previous run.\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        ...executionParams,\n      };\n\n      /* File injection: `_injected_files` from ToolNode (set when host\n       * primes a CodeSessionContext) or `params.files` from tool\n       * factory (set by hosts that pre-resolve at construction time).\n       * The legacy `/files/<session_id>` HTTP fallback was removed —\n       * codeapi's `sessionAuth` middleware now requires kind/id query\n       * params the tool can't supply at this point, so the fetch 400'd\n       * silently and the catch swallowed the failure. */\n      if (_injected_files && _injected_files.length > 0) {\n        postData.files = _injected_files;\n      } else if (\n        session_id != null &&\n        session_id.length > 0 &&\n        !Array.isArray(postData.files)\n      ) {\n        // eslint-disable-next-line no-console\n        console.debug(\n          `[CodeExecutor] No injected files for session_id=${session_id} — exec will run without input files`\n        );\n      }\n\n      try {\n        const resolvedAuthHeaders =\n          await resolveCodeApiAuthHeaders(authHeaders);\n        const fetchOptions: RequestInit = {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            'User-Agent': 'LibreChat/1.0',\n            ...resolvedAuthHeaders,\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(\n            await buildCodeApiHttpErrorMessage('POST', EXEC_ENDPOINT, response)\n          );\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\n        const outputWithReminder = appendTmpScratchReminder(\n          formattedOutput,\n          code\n        );\n        const hasFiles = result.files != null && result.files.length > 0;\n        return [\n          appendCodeSessionFileSummary(outputWithReminder, result.files),\n          (hasFiles\n            ? { session_id: result.session_id, files: result.files }\n            : {\n              session_id: result.session_id,\n            }) satisfies t.CodeExecutionArtifact,\n        ];\n      } catch (error) {\n        const messageWithReminder = appendFailedExecutionFileReminder(\n          (error as Error | undefined)?.message ?? '',\n          code\n        );\n        throw new Error(\n          `Execution error:\\n\\n${messageWithReminder}`\n        );\n      }\n    },\n    {\n      name: CodeExecutionToolName,\n      description: CodeExecutionToolDescription,\n      schema: CodeExecutionToolSchema,\n      responseFormat: Constants.CONTENT_AND_ARTIFACT,\n    }\n  );\n}\n\nexport { createCodeExecutionTool };\n"],"names":["config","getEnvironmentVariable","EnvVar","Constants","tool","HttpsProxyAgent","appendCodeSessionFileSummary"],"mappings":"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"}

package/dist/cjs/tools/CodeSessionFileSummary.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+const IMAGE_FILE_EXTENSIONS = new Set([
+    '.avif',
+    '.bmp',
+    '.gif',
+    '.ico',
+    '.jpeg',
+    '.jpg',
+    '.png',
+    '.tif',
+    '.tiff',
+    '.webp',
+]);
+const CODE_SESSION_FILE_SUMMARY_PATTERN = /^Generated files:\nSession files: \d+ persisted file\(s\) are available in \/mnt\/data, including \d+ image\(s\)\. Use known \/mnt\/data paths directly in later code-tool calls\. The app displays files\/images automatically; do not invent download links or wrap generated images in Markdown\.$/;
+function getFileExtension(name) {
+    const lastSlash = name.lastIndexOf('/');
+    const basename = lastSlash >= 0 ? name.slice(lastSlash + 1) : name;
+    const lastDot = basename.lastIndexOf('.');
+    return lastDot >= 0 ? basename.slice(lastDot).toLowerCase() : '';
+}
+function isImageFile(file) {
+    const name = file?.name;
+    return (typeof name === 'string' &&
+        IMAGE_FILE_EXTENSIONS.has(getFileExtension(name)));
+}
+function buildCodeSessionFileSummary(fileCount, imageCount) {
+    return ('Generated files:\n' +
+        `Session files: ${fileCount} persisted file(s) are available in /mnt/data, including ${imageCount} image(s). ` +
+        'Use known /mnt/data paths directly in later code-tool calls. ' +
+        'The app displays files/images automatically; do not invent download links or wrap generated images in Markdown.');
+}
+function isGeneratedFile(file) {
+    return file?.inherited !== true;
+}
+function stripCodeSessionFileSummary(output) {
+    const summaryStart = output.lastIndexOf('Generated files:');
+    if (summaryStart < 0)
+        return output;
+    const beforeSummary = output.slice(0, summaryStart);
+    if (beforeSummary !== '' && !beforeSummary.endsWith('\n\n'))
+        return output;
+    const maybeSummary = output.slice(summaryStart);
+    if (!CODE_SESSION_FILE_SUMMARY_PATTERN.test(maybeSummary))
+        return output;
+    return beforeSummary.trimEnd();
+}
+function appendCodeSessionFileSummary(output, files) {
+    if (files == null || files.length === 0) {
+        return output.trim();
+    }
+    const generatedFiles = files.filter(isGeneratedFile);
+    if (generatedFiles.length === 0) {
+        return output.trim();
+    }
+    const imageCount = generatedFiles.filter(isImageFile).length;
+    const summary = buildCodeSessionFileSummary(generatedFiles.length, imageCount);
+    return `${output.trimEnd()}\n\n${summary}`.trim();
+}
+
+exports.appendCodeSessionFileSummary = appendCodeSessionFileSummary;
+exports.stripCodeSessionFileSummary = stripCodeSessionFileSummary;
+//# sourceMappingURL=CodeSessionFileSummary.cjs.map

package/dist/cjs/tools/CodeSessionFileSummary.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeSessionFileSummary.cjs","sources":["../../../src/tools/CodeSessionFileSummary.ts"],"sourcesContent":["import type * as t from '@/types';\n\nconst IMAGE_FILE_EXTENSIONS = new Set([\n  '.avif',\n  '.bmp',\n  '.gif',\n  '.ico',\n  '.jpeg',\n  '.jpg',\n  '.png',\n  '.tif',\n  '.tiff',\n  '.webp',\n]);\n\nconst CODE_SESSION_FILE_SUMMARY_PATTERN =\n  /^Generated files:\\nSession files: \\d+ persisted file\\(s\\) are available in \\/mnt\\/data, including \\d+ image\\(s\\)\\. Use known \\/mnt\\/data paths directly in later code-tool calls\\. The app displays files\\/images automatically; do not invent download links or wrap generated images in Markdown\\.$/;\n\nfunction getFileExtension(name: string): string {\n  const lastSlash = name.lastIndexOf('/');\n  const basename = lastSlash >= 0 ? name.slice(lastSlash + 1) : name;\n  const lastDot = basename.lastIndexOf('.');\n  return lastDot >= 0 ? basename.slice(lastDot).toLowerCase() : '';\n}\n\nfunction isImageFile(file: Partial<t.FileRef> | null | undefined): boolean {\n  const name = file?.name;\n  return (\n    typeof name === 'string' &&\n    IMAGE_FILE_EXTENSIONS.has(getFileExtension(name))\n  );\n}\n\nfunction buildCodeSessionFileSummary(\n  fileCount: number,\n  imageCount: number\n): string {\n  return (\n    'Generated files:\\n' +\n    `Session files: ${fileCount} persisted file(s) are available in /mnt/data, including ${imageCount} image(s). ` +\n    'Use known /mnt/data paths directly in later code-tool calls. ' +\n    'The app displays files/images automatically; do not invent download links or wrap generated images in Markdown.'\n  );\n}\n\nfunction isGeneratedFile(file: Partial<t.FileRef> | null | undefined): boolean {\n  return file?.inherited !== true;\n}\n\nexport function stripCodeSessionFileSummary(output: string): string {\n  const summaryStart = output.lastIndexOf('Generated files:');\n  if (summaryStart < 0) return output;\n  const beforeSummary = output.slice(0, summaryStart);\n  if (beforeSummary !== '' && !beforeSummary.endsWith('\\n\\n')) return output;\n  const maybeSummary = output.slice(summaryStart);\n  if (!CODE_SESSION_FILE_SUMMARY_PATTERN.test(maybeSummary)) return output;\n  return beforeSummary.trimEnd();\n}\n\nexport function appendCodeSessionFileSummary(\n  output: string,\n  files: t.FileRefs | undefined\n): string {\n  if (files == null || files.length === 0) {\n    return output.trim();\n  }\n\n  const generatedFiles = files.filter(isGeneratedFile);\n  if (generatedFiles.length === 0) {\n    return output.trim();\n  }\n\n  const imageCount = generatedFiles.filter(isImageFile).length;\n  const summary = buildCodeSessionFileSummary(\n    generatedFiles.length,\n    imageCount\n  );\n\n  return `${output.trimEnd()}\\n\\n${summary}`.trim();\n}\n"],"names":[],"mappings":";;AAEA,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,OAAO;IACP,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;AACR,CAAA,CAAC;AAEF,MAAM,iCAAiC,GACrC,uSAAuS;AAEzS,SAAS,gBAAgB,CAAC,IAAY,EAAA;IACpC,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;IACvC,MAAM,QAAQ,GAAG,SAAS,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,IAAI;IAClE,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC;AACzC,IAAA,OAAO,OAAO,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,GAAG,EAAE;AAClE;AAEA,SAAS,WAAW,CAAC,IAA2C,EAAA;AAC9D,IAAA,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI;AACvB,IAAA,QACE,OAAO,IAAI,KAAK,QAAQ;QACxB,qBAAqB,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAErD;AAEA,SAAS,2BAA2B,CAClC,SAAiB,EACjB,UAAkB,EAAA;AAElB,IAAA,QACE,oBAAoB;QACpB,CAAA,eAAA,EAAkB,SAAS,CAAA,yDAAA,EAA4D,UAAU,CAAA,WAAA,CAAa;QAC9G,+DAA+D;AAC/D,QAAA,iHAAiH;AAErH;AAEA,SAAS,eAAe,CAAC,IAA2C,EAAA;AAClE,IAAA,OAAO,IAAI,EAAE,SAAS,KAAK,IAAI;AACjC;AAEM,SAAU,2BAA2B,CAAC,MAAc,EAAA;IACxD,MAAM,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC,kBAAkB,CAAC;IAC3D,IAAI,YAAY,GAAG,CAAC;AAAE,QAAA,OAAO,MAAM;IACnC,MAAM,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC;IACnD,IAAI,aAAa,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC;AAAE,QAAA,OAAO,MAAM;IAC1E,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC;AAC/C,IAAA,IAAI,CAAC,iCAAiC,CAAC,IAAI,CAAC,YAAY,CAAC;AAAE,QAAA,OAAO,MAAM;AACxE,IAAA,OAAO,aAAa,CAAC,OAAO,EAAE;AAChC;AAEM,SAAU,4BAA4B,CAC1C,MAAc,EACd,KAA6B,EAAA;IAE7B,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;AACvC,QAAA,OAAO,MAAM,CAAC,IAAI,EAAE;IACtB;IAEA,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,CAAC,eAAe,CAAC;AACpD,IAAA,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE;AAC/B,QAAA,OAAO,MAAM,CAAC,IAAI,EAAE;IACtB;IAEA,MAAM,UAAU,GAAG,cAAc,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM;IAC5D,MAAM,OAAO,GAAG,2BAA2B,CACzC,cAAc,CAAC,MAAM,EACrB,UAAU,CACX;IAED,OAAO,CAAA,EAAG,MAAM,CAAC,OAAO,EAAE,CAAA,IAAA,EAAO,OAAO,CAAA,CAAE,CAAC,IAAI,EAAE;AACnD;;;;;"}

package/dist/cjs/tools/ProgrammaticToolCalling.cjs

@@ -7,6 +7,7 @@ var tools = require('@langchain/core/tools');
 var CodeExecutor = require('./CodeExecutor.cjs');
 var ptcTimeout = require('./ptcTimeout.cjs');
 var _enum = require('../common/enum.cjs');
+var CodeSessionFileSummary = require('./CodeSessionFileSummary.cjs');
 
 // src/tools/ProgrammaticToolCalling.ts
 dotenv.config();
@@ -21,14 +22,15 @@ Each call is a fresh Python interpreter. Variables, imports, and data do NOT per
 You MUST complete your entire workflow in ONE code block: query → process → output.
 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()
+- One call: state does not persist
+- Auto-wrapped async; use await, no main()/asyncio.run()
 - Tools are pre-defined—DO NOT write function definitions
+- Call tools with keyword args only (await tool(arg=value), never pass a dict)
+- Tool results are decoded Python values (dict/list/str)
 - Only print() output returns to the model
+- ${CodeExecutor.CODE_ARTIFACT_PATH_GUIDANCE}
 - timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;
-const ADDITIONAL_RULES = `- Generated files are automatically available in /mnt/data/ for subsequent executions
-- Tool names normalized: hyphens→underscores, keywords get \`_tool\` suffix`;
+const ADDITIONAL_RULES = '- 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")
@@ -507,14 +509,14 @@ async function executeTools(toolCalls, toolMap, programmaticToolName = _enum.Con
 /**
  * Formats the completed response for the agent.
  *
- * Output is stdout/stderr only — see `CodeExecutor.ts`. The
- * artifact still carries every file so the host's session map
- * stays in sync; the LLM doesn't see them in the tool result text.
+ * Output includes stdout/stderr plus a compact session-file summary
+ * when artifacts were persisted. The artifact still carries every
+ * file so the host's session map stays in sync.
  *
  * @param response - The completed API response
  * @returns Tuple of [formatted string, artifact]
  */
-function formatCompletedResponse(response) {
+function formatCompletedResponse(response, sourceCode = '') {
     let formatted = '';
     if (response.stdout != null && response.stdout !== '') {
         formatted += `stdout:\n${response.stdout}\n`;
@@ -525,8 +527,9 @@ function formatCompletedResponse(response) {
     if (response.stderr != null && response.stderr !== '') {
         formatted += `stderr:\n${response.stderr}\n`;
     }
+    const outputWithReminder = CodeExecutor.appendTmpScratchReminder(formatted, sourceCode);
     return [
-        formatted.trim(),
+        CodeSessionFileSummary.appendCodeSessionFileSummary(outputWithReminder, response.files),
         {
             session_id: response.session_id,
             files: response.files,
@@ -633,7 +636,7 @@ function createProgrammaticToolCallingTool(initParams = {}) {
             // Phase 3: Handle final state
             // ====================================================================
             if (response.status === 'completed') {
-                return formatCompletedResponse(response);
+                return formatCompletedResponse(response, code);
             }
             if (response.status === 'error') {
                 throw new Error(`Execution error: ${response.error}` +
@@ -644,7 +647,8 @@ function createProgrammaticToolCallingTool(initParams = {}) {
             throw new Error(`Unexpected response status: ${response.status}`);
         }
         catch (error) {
-            throw new Error(`Programmatic execution failed: ${error.message}`);
+            const messageWithReminder = CodeExecutor.appendFailedExecutionFileReminder(error.message, code);
+            throw new Error(`Programmatic execution failed: ${messageWithReminder}`);
         }
     }, {
         name: _enum.Constants.PROGRAMMATIC_TOOL_CALLING,