@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

package/src/test/mockTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mockTools.js","sourceRoot":"","sources":["mockTools.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB;;;GAGG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAI7C,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,wBAAwB;IACtC,OAAO,IAAI,CACT,KAAK,IAAI,EAAE;QACT,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QACxD,OAAO;YACL,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE;YACtD,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE;YAClD,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE;SACzD,CAAC;IACJ,CAAC,EACD;QACE,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,0FAA0F;QAC5F,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;KACzD,CACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,WAAW,GAGb;QACF,EAAE,EAAE;YACF,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE;YACrC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE;SACpC;QACD,EAAE,EAAE;YACF,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE;YACxC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE;YACnC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE;SACtC;QACD,EAAE,EAAE;YACF,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE;YACxC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE;YACrC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE;SACpC;KACF,CAAC;IAEF,OAAO,IAAI,CACT,KAAK,EAAE,KAAK,EAAE,EAAE;QACd,MAAM,EAAE,OAAO,EAAE,GAAG,KAA4B,CAAC;QACjD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QACxD,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACpC,CAAC,EACD;QACE,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,2FAA2F;QAC7F,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB;KACF,CACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,WAAW,GAGb;QACF,eAAe,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;QACxD,UAAU,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;QACnD,MAAM,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;QAC/C,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;QAC9C,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;QAC3C,GAAG,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;KAC7C,CAAC;IAEF,OAAO,IAAI,CACT,KAAK,EAAE,KAAK,EAAE,EAAE;QACd,MAAM,EAAE,IAAI,EAAE,GAAG,KAAyB,CAAC;QAC3C,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,EACD;QACE,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,yGAAyG;QAC3G,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE;aACnD;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF,CACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CACT,KAAK,EAAE,KAAK,EAAE,EAAE;QACd,MAAM,EAAE,UAAU,EAAE,GAAG,KAA+B,CAAC;QACvD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QACxD,iEAAiE;QAEjE,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAChC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAChC,CAAC,EACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,oCAAoC;QACjD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,qCAAqC;iBACnD;aACF;YACD,QAAQ,EAAE,CAAC,YAAY,CAAC;SACzB;KACF,CACF,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,8BAA8B;IAC5C,MAAM,QAAQ,GAAa;QACzB;YACE,IAAI,EAAE,kBAAkB;YACxB,WAAW,EACT,0FAA0F;YAC5F,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,EAAE;gBACd,QAAQ,EAAE,EAAE;aACb;YACD,eAAe,EAAE,CAAC,gBAAgB,CAAC,EAAE,oBAAoB;YACzD,aAAa,EAAE,KAAK;SACrB;QACD;YACE,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,2FAA2F;YAC7F,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,OAAO,EAAE;wBACP,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,mCAAmC;qBACjD;iBACF;gBACD,QAAQ,EAAE,CAAC,SAAS,CAAC;aACtB;YACD,eAAe,EAAE,CAAC,gBAAgB,CAAC,EAAE,oBAAoB;YACzD,aAAa,EAAE,KAAK;SACrB;QACD;YACE,IAAI,EAAE,aAAa;YACnB,WAAW,EACT,yGAAyG;YAC3G,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE;wBACJ,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,WAAW;qBACzB;iBACF;gBACD,QAAQ,EAAE,CAAC,MAAM,CAAC;aACnB;YACD,eAAe,EAAE,CAAC,QAAQ,EAAE,gBAAgB,CAAC,EAAE,gBAAgB;YAC/D,aAAa,EAAE,KAAK;SACrB;QACD;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,oCAAoC;YACjD,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,qCAAqC;qBACnD;iBACF;gBACD,QAAQ,EAAE,CAAC,YAAY,CAAC;aACzB;YACD,eAAe,EAAE,CAAC,gBAAgB,CAAC,EAAE,oBAAoB;YACzD,aAAa,EAAE,KAAK;SACrB;KACF,CAAC;IAEF,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,4BAA4B;IAC1C,MAAM,KAAK,GAAa;QACtB;YACE,IAAI,EAAE,cAAc;YACpB,WAAW,EACT,qGAAqG;YACvG,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,0BAA0B;qBACxC;oBACD,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wBAAwB,EAAE;oBACnE,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE;iBAC9D;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,0BAA0B;YAChC,WAAW,EACT,yFAAyF;YAC3F,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,QAAQ,EAAE;wBACR,IAAI,EAAE,QAAQ;wBACd,WAAW,EAAE,4BAA4B;qBAC1C;iBACF;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,eAAe;YACrB,WAAW,EACT,yEAAyE;YAC3E,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE;oBACpD,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0BAA0B,EAAE;iBACpE;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,0DAA0D;YACvE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE;iBACjE;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,0DAA0D;YACvE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE;oBAChE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4BAA4B,EAAE;iBACpE;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EACT,mEAAmE;YACrE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,EAAE,EAAE;wBACF,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACzB,WAAW,EAAE,YAAY;qBAC1B;oBACD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE;oBACzD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE;iBACpD;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,yDAAyD;YACtE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;oBACtD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wBAAwB,EAAE;iBAChE;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,oBAAoB;YAC1B,WAAW,EACT,8DAA8D;YAChE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE;oBAC9D,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE;iBAC7D;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,iBAAiB;YACvB,WAAW,EACT,uEAAuE;YACzE,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE;oBACjE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4BAA4B,EAAE;oBACrE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2BAA2B,EAAE;iBACnE;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,gBAAgB;YACtB,WAAW,EACT,6DAA6D;YAC/D,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mBAAmB,EAAE;oBAC1D,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE;oBACpE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE;iBACrE;aACF;YACD,aAAa,EAAE,IAAI;SACpB;QACD;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EACT,wFAAwF;YAC1F,aAAa,EAAE,KAAK,EAAE,+CAA+C;SACtE;KACF,CAAC;IAEF,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/src/tools/BashExecutor.ts

@@ -0,0 +1,281 @@
+import { config } from 'dotenv';
+import fetch, { RequestInit } from 'node-fetch';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { getEnvironmentVariable } from '@langchain/core/utils/env';
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { getCodeBaseURL, renderFileSection } from './CodeExecutor';
+import { Constants, EnvVar } from '@/common';
+
+config();
+
+const otherMessage = 'File is already downloaded by the user';
+const inheritedFileMessage =
+  'Available as an input — already known to 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 inheritedFilesHeader =
+  'Available files (inputs, not generated by this execution):';
+const generatedFilesHeader = 'Generated files:';
+const inheritedNote =
+  'Note: Files in "Available files" are inputs the user (or a skill) already provided to the sandbox. They were not produced by this execution and you should not present them as new outputs in your response.';
+
+export const BashExecutionToolSchema = {
+  type: 'object',
+  properties: {
+    command: {
+      type: 'string',
+      description: `The bash command or script to execute.
+- The environment is stateless; variables and state 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.
+- 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.
+- Use \`echo\`, \`printf\`, or \`cat\` for all outputs.`,
+    },
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.',
+    },
+  },
+  required: ['command'],
+} as const;
+
+export const BashExecutionToolDescription = `
+Runs bash commands 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.
+
+Usage:
+- No network access available.
+- Generated files are automatically delivered; **DO NOT** provide download links.
+- NEVER use this tool to execute malicious commands.
+`.trim();
+
+/**
+ * Supplemental prompt documenting the tool-output reference feature.
+ *
+ * Hosts should append this (separated by a blank line) to the base
+ * {@link BashExecutionToolDescription} only when
+ * `RunConfig.toolOutputReferences.enabled` is `true`. When the feature
+ * is disabled, including this text would tell the LLM to emit
+ * `{{tool0turn0}}` placeholders that pass through unsubstituted and
+ * leak into the shell.
+ */
+export const BashToolOutputReferencesGuide = `
+Referencing previous tool outputs:
+- Every successful tool result is tagged with a reference key of the form \`tool<idx>turn<turn>\` (e.g., \`tool0turn0\`). The key appears either as a \`[ref: tool0turn0]\` prefix line or, when the output is a JSON object, as a \`_ref\` field on the object.
+- To pipe a previous tool output into this tool, embed the placeholder \`{{tool<idx>turn<turn>}}\` literally anywhere in the \`command\` string (or any string arg). It will be substituted with the stored output verbatim before the command runs.
+- The substituted value is the original output string (no \`[ref: …]\` prefix, no \`_ref\` key), so it is safe to pipe directly into \`jq\`, \`grep\`, \`awk\`, etc.
+- Example (simple ASCII output): \`echo '{{tool0turn0}}' | jq '.foo'\` takes the full output of the first tool from the first turn and pipes it into jq.
+- For payloads that may contain quotes, parentheses, backticks, or arbitrary bytes (random/binary data, JSON with embedded quotes, multi-line strings), prefer a quoted-delimiter heredoc over \`echo '…'\`. The heredoc body is not interpreted by the shell, so substituted payloads pass through unchanged.
+- Heredoc example: \`wc -c << 'EOF'\\n{{tool0turn0}}\\nEOF\` (the quotes around \`'EOF'\` disable interpolation inside the body).
+- Unknown reference keys are left in place and surfaced as \`[unresolved refs: …]\` after the output.
+`.trim();
+
+/**
+ * Composes the bash tool description, optionally appending the
+ * tool-output references guide. Hosts that enable
+ * `RunConfig.toolOutputReferences` should pass `enableToolOutputReferences: true`
+ * when registering the tool so the LLM learns the `{{…}}` syntax it
+ * will actually be able to use.
+ */
+export function buildBashExecutionToolDescription(options?: {
+  enableToolOutputReferences?: boolean;
+}): string {
+  if (options?.enableToolOutputReferences === true) {
+    return `${BashExecutionToolDescription}\n\n${BashToolOutputReferencesGuide}`;
+  }
+  return BashExecutionToolDescription;
+}
+
+export const BashExecutionToolName = Constants.BASH_TOOL;
+
+/**
+ * Default bash tool definition using the base description.
+ *
+ * When `RunConfig.toolOutputReferences.enabled` is `true`, build a
+ * reference-aware description with
+ * {@link buildBashExecutionToolDescription}
+ * (`{ enableToolOutputReferences: true }`) and construct a custom
+ * definition using it — using this constant as-is leaves the LLM
+ * unaware of the `{{tool<i>turn<n>}}` syntax.
+ */
+export const BashExecutionToolDefinition = {
+  name: BashExecutionToolName,
+  description: BashExecutionToolDescription,
+  schema: BashExecutionToolSchema,
+} as const;
+
+function createBashExecutionTool(
+  params: t.BashExecutionToolParams = {}
+): DynamicStructuredTool {
+  const apiKey =
+    params[EnvVar.CODE_API_KEY] ??
+    params.apiKey ??
+    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
+    '';
+  if (!apiKey) {
+    throw new Error('No API key provided for bash execution tool.');
+  }
+
+  return tool(
+    async (rawInput, config) => {
+      const baseEndpoint = getCodeBaseURL();
+      const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
+
+      const { command, ...rest } = rawInput as {
+        command: string;
+        args?: string[];
+      };
+      const { session_id, _injected_files } = (config.toolCall ?? {}) as {
+        session_id?: string;
+        _injected_files?: t.CodeEnvFile[];
+      };
+
+      const postData: Record<string, unknown> = {
+        lang: 'bash',
+        code: command,
+        ...rest,
+        ...params,
+      };
+
+      if (_injected_files && _injected_files.length > 0) {
+        postData.files = _injected_files;
+      } else if (session_id != null && session_id.length > 0) {
+        try {
+          const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;
+          const userIdForFiles = params.user_id ?? '';
+          const fetchOptions: RequestInit = {
+            method: 'GET',
+            headers: {
+              'User-Agent': 'Illuma/1.0',
+              'X-API-Key': apiKey,
+              ...(userIdForFiles ? { 'User-Id': userIdForFiles } : {}),
+            },
+          };
+
+          if (process.env.PROXY != null && process.env.PROXY !== '') {
+            fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
+          }
+
+          const response = await fetch(filesEndpoint, fetchOptions);
+          if (!response.ok) {
+            throw new Error(
+              `Failed to fetch files for session: ${response.status}`
+            );
+          }
+
+          const files = await response.json();
+          if (Array.isArray(files) && files.length > 0) {
+            const fileReferences: t.CodeEnvFile[] = files.map((file) => {
+              const nameParts = file.name.split('/');
+              const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';
+
+              return {
+                session_id,
+                id,
+                name: file.metadata['original-filename'],
+              };
+            });
+
+            postData.files = fileReferences;
+          }
+        } catch {
+          // eslint-disable-next-line no-console
+          console.warn(`Failed to fetch files for session: ${session_id}`);
+        }
+      }
+
+      const userId = params.user_id ?? '';
+
+      try {
+        const fetchOptions: RequestInit = {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': 'Illuma/1.0',
+            'X-API-Key': apiKey,
+            ...(userId ? { 'User-Id': userId } : {}),
+          },
+          body: JSON.stringify(postData),
+        };
+
+        if (process.env.PROXY != null && process.env.PROXY !== '') {
+          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
+        }
+        const response = await fetch(EXEC_ENDPOINT, fetchOptions);
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        const result: t.ExecuteResult = await response.json();
+        let formattedOutput = '';
+        if (result.stdout) {
+          formattedOutput += `stdout:\n${result.stdout}\n`;
+        } else {
+          formattedOutput += emptyOutputMessage;
+        }
+        if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
+        if (result.files && result.files.length > 0) {
+          /* Split inherited (read-only / unchanged-input passthroughs from
+           * codeapi) from genuine generated outputs. The LLM was previously
+           * shown skill files under "Generated files:" with the message
+           * "File is already downloaded by the user", which led it to
+           * (a) believe it had just produced files it merely referenced
+           * and (b) sometimes invent paths like /mnt/user-data/uploads/
+           * trying to find the "originals". Labeling them as inputs makes
+           * the mental model accurate. */
+          const inheritedFiles = result.files.filter(
+            (f) => f.inherited === true
+          );
+          const generatedFiles = result.files.filter(
+            (f) => f.inherited !== true
+          );
+
+          formattedOutput += renderFileSection(
+            generatedFilesHeader,
+            generatedFiles,
+            otherMessage
+          );
+          formattedOutput += renderFileSection(
+            inheritedFilesHeader,
+            inheritedFiles,
+            inheritedFileMessage
+          );
+
+          if (generatedFiles.length > 0) {
+            formattedOutput += `\n\n${accessMessage}`;
+          }
+          if (inheritedFiles.length > 0) {
+            formattedOutput += `\n\n${inheritedNote}`;
+          }
+          return [
+            formattedOutput.trim(),
+            {
+              session_id: result.session_id,
+              files: result.files,
+            },
+          ];
+        }
+
+        return [formattedOutput.trim(), { session_id: result.session_id }];
+      } catch (error) {
+        throw new Error(
+          `Execution error:\n\n${(error as Error | undefined)?.message}`
+        );
+      }
+    },
+    {
+      name: BashExecutionToolName,
+      description: BashExecutionToolDescription,
+      schema: BashExecutionToolSchema,
+      responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    }
+  );
+}
+
+export { createBashExecutionTool };

package/src/tools/BashProgrammaticToolCalling.ts

@@ -0,0 +1,397 @@
+import { config } from 'dotenv';
+import { getEnvironmentVariable } from '@langchain/core/utils/env';
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type * as t from '@/types';
+import {
+  makeRequest,
+  executeTools,
+  fetchSessionFiles,
+  formatCompletedResponse,
+} from './ProgrammaticToolCalling';
+import { getCodeBaseURL } from './CodeExecutor';
+import { Constants, EnvVar } from '@/common';
+
+config();
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEFAULT_MAX_ROUND_TRIPS = 20;
+const DEFAULT_TIMEOUT = 60000;
+
+/** Bash reserved words that get `_tool` suffix when used as function names */
+const BASH_RESERVED = new Set([
+  'if',
+  'then',
+  'else',
+  'elif',
+  'fi',
+  'case',
+  'esac',
+  'for',
+  'while',
+  'until',
+  'do',
+  'done',
+  'in',
+  'function',
+  'select',
+  'time',
+  'coproc',
+  'declare',
+  'typeset',
+  'local',
+  'readonly',
+  'export',
+  'unset',
+]);
+
+// ============================================================================
+// Description Components
+// ============================================================================
+
+const STATELESS_WARNING = `CRITICAL - STATELESS EXECUTION:
+Each call is a fresh bash shell. Variables and state do NOT persist between calls.
+You MUST complete your entire workflow in ONE code block.
+DO NOT split work across multiple calls expecting to reuse variables.`;
+
+const CORE_RULES = `Rules:
+- EVERYTHING in one call—no state persists between executions
+- Tools are pre-defined as bash functions—DO NOT redefine them
+- Each tool function accepts a JSON string argument
+- Only echo/printf output returns to the model
+- Generated files are automatically available in /mnt/data/ for subsequent executions`;
+
+const ADDITIONAL_RULES =
+  '- Tool names normalized: hyphens→underscores, reserved words get `_tool` suffix';
+
+const EXAMPLES = `Example (Complete workflow in one call):
+  # Query data and process
+  data=$(query_database '{"sql": "SELECT * FROM users"}')
+  echo "$data" | jq '.[] | .name'
+
+Example (Parallel calls):
+  web_search '{"query": "SF weather"}' > /tmp/sf.txt &
+  web_search '{"query": "NY weather"}' > /tmp/ny.txt &
+  wait
+  echo "SF: $(cat /tmp/sf.txt)"
+  echo "NY: $(cat /tmp/ny.txt)"`;
+
+const CODE_PARAM_DESCRIPTION = `Bash code that calls tools programmatically. Tools are available as bash functions.
+
+${STATELESS_WARNING}
+
+Each tool function accepts a JSON string as its argument.
+Example: tool_name '{"key": "value"}'
+
+${EXAMPLES}
+
+${CORE_RULES}`;
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+export const BashProgrammaticToolCallingSchema = {
+  type: 'object',
+  properties: {
+    code: {
+      type: 'string',
+      minLength: 1,
+      description: CODE_PARAM_DESCRIPTION,
+    },
+    timeout: {
+      type: 'integer',
+      minimum: 1000,
+      maximum: 300000,
+      default: DEFAULT_TIMEOUT,
+      description:
+        'Maximum execution time in milliseconds. Default: 60 seconds. Max: 5 minutes.',
+    },
+  },
+  required: ['code'],
+} as const;
+
+export const BashProgrammaticToolCallingName =
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING;
+
+export const BashProgrammaticToolCallingDescription = `
+Run tools via bash code. Tools are available as bash functions that accept JSON string arguments.
+
+${STATELESS_WARNING}
+
+${CORE_RULES}
+${ADDITIONAL_RULES}
+
+When to use: shell pipelines, parallel execution (& and wait), file processing, text manipulation.
+
+${EXAMPLES}
+`.trim();
+
+export const BashProgrammaticToolCallingDefinition = {
+  name: BashProgrammaticToolCallingName,
+  description: BashProgrammaticToolCallingDescription,
+  schema: BashProgrammaticToolCallingSchema,
+} as const;
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Normalizes a tool name to a valid bash function identifier.
+ * 1. Replace hyphens, spaces, dots with underscores
+ * 2. Remove any other invalid characters
+ * 3. Prefix with underscore if starts with number
+ * 4. Append `_tool` if it's a bash reserved word
+ */
+export function normalizeToBashIdentifier(name: string): string {
+  let normalized = name.replace(/[-\s.]/g, '_');
+  normalized = normalized.replace(/[^a-zA-Z0-9_]/g, '');
+
+  if (/^[0-9]/.test(normalized)) {
+    normalized = '_' + normalized;
+  }
+
+  if (BASH_RESERVED.has(normalized)) {
+    normalized = normalized + '_tool';
+  }
+
+  return normalized;
+}
+
+/**
+ * Extracts tool names that are actually called in the bash code.
+ * Bash functions are invoked as commands (no parentheses), so we match
+ * the normalized name as a word boundary.
+ */
+export function extractUsedBashToolNames(
+  code: string,
+  toolNameMap: Map<string, string>
+): Set<string> {
+  const usedTools = new Set<string>();
+
+  for (const [bashName, originalName] of toolNameMap) {
+    const escapedName = bashName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`\\b${escapedName}\\b`, 'g');
+
+    if (pattern.test(code)) {
+      usedTools.add(originalName);
+    }
+  }
+
+  return usedTools;
+}
+
+/**
+ * Filters tool definitions to only include tools actually used in the bash code.
+ */
+export function filterBashToolsByUsage(
+  toolDefs: t.LCTool[],
+  code: string,
+  debug = false
+): t.LCTool[] {
+  const toolNameMap = new Map<string, string>();
+  for (const def of toolDefs) {
+    const bashName = normalizeToBashIdentifier(def.name);
+    toolNameMap.set(bashName, def.name);
+  }
+
+  const usedToolNames = extractUsedBashToolNames(code, toolNameMap);
+
+  if (debug) {
+    // eslint-disable-next-line no-console
+    console.log(
+      `[BashPTC Debug] Tool filtering: found ${usedToolNames.size}/${toolDefs.length} tools in code`
+    );
+    if (usedToolNames.size > 0) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[BashPTC Debug] Matched tools: ${Array.from(usedToolNames).join(', ')}`
+      );
+    }
+  }
+
+  if (usedToolNames.size === 0) {
+    if (debug) {
+      // eslint-disable-next-line no-console
+      console.log(
+        '[BashPTC Debug] No tools detected in code - sending all tools as fallback'
+      );
+    }
+    return toolDefs;
+  }
+
+  return toolDefs.filter((def) => usedToolNames.has(def.name));
+}
+
+// ============================================================================
+// Tool Factory
+// ============================================================================
+
+/**
+ * Creates a Bash Programmatic Tool Calling tool for multi-tool orchestration.
+ *
+ * This tool enables AI agents to write bash scripts that orchestrate multiple
+ * tool calls programmatically via the remote Code API, reducing LLM round-trips.
+ *
+ * The tool map must be provided at runtime via config.toolCall (injected by ToolNode).
+ */
+export function createBashProgrammaticToolCallingTool(
+  initParams: t.BashProgrammaticToolCallingParams = {}
+): DynamicStructuredTool {
+  const apiKey =
+    (initParams[EnvVar.CODE_API_KEY] as string | undefined) ??
+    initParams.apiKey ??
+    getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
+    '';
+
+  if (!apiKey) {
+    throw new Error(
+      'No API key provided for bash programmatic tool calling. ' +
+        'Set CODE_API_KEY environment variable or pass apiKey in initParams.'
+    );
+  }
+
+  const baseUrl = initParams.baseUrl ?? getCodeBaseURL();
+  const maxRoundTrips = initParams.maxRoundTrips ?? DEFAULT_MAX_ROUND_TRIPS;
+  const proxy = initParams.proxy ?? process.env.PROXY;
+  const debug = initParams.debug ?? process.env.BASH_PTC_DEBUG === 'true';
+  const EXEC_ENDPOINT = `${baseUrl}/exec/programmatic`;
+
+  return tool(
+    async (rawParams, config) => {
+      const params = rawParams as { code: string; timeout?: number };
+      const { code, timeout = DEFAULT_TIMEOUT } = params;
+
+      const { toolMap, toolDefs, session_id, _injected_files } =
+        (config.toolCall ?? {}) as ToolCall &
+          Partial<t.ProgrammaticCache> & {
+            session_id?: string;
+            _injected_files?: t.CodeEnvFile[];
+          };
+
+      if (toolMap == null || toolMap.size === 0) {
+        throw new Error(
+          'No toolMap provided. ' +
+            'ToolNode should inject this from AgentContext when invoked through the graph.'
+        );
+      }
+
+      if (toolDefs == null || toolDefs.length === 0) {
+        throw new Error(
+          'No tool definitions provided. ' +
+            'Either pass tools in the input or ensure ToolNode injects toolDefs.'
+        );
+      }
+
+      let roundTrip = 0;
+
+      try {
+        // ====================================================================
+        // Phase 1: Filter tools and make initial request
+        // ====================================================================
+
+        const effectiveTools = filterBashToolsByUsage(toolDefs, code, debug);
+
+        if (debug) {
+          // eslint-disable-next-line no-console
+          console.log(
+            `[BashPTC Debug] Sending ${effectiveTools.length} tools to API ` +
+              `(filtered from ${toolDefs.length})`
+          );
+        }
+
+        let files: t.CodeEnvFile[] | undefined;
+        if (_injected_files && _injected_files.length > 0) {
+          files = _injected_files;
+        } else if (session_id != null && session_id.length > 0) {
+          files = await fetchSessionFiles(baseUrl, apiKey, session_id, proxy);
+        }
+
+        let response = await makeRequest(
+          EXEC_ENDPOINT,
+          apiKey,
+          {
+            lang: 'bash',
+            code,
+            tools: effectiveTools,
+            session_id,
+            timeout,
+            ...(files && files.length > 0 ? { files } : {}),
+          },
+          proxy
+        );
+
+        // ====================================================================
+        // Phase 2: Handle response loop
+        // ====================================================================
+
+        while (response.status === 'tool_call_required') {
+          roundTrip++;
+
+          if (roundTrip > maxRoundTrips) {
+            throw new Error(
+              `Exceeded maximum round trips (${maxRoundTrips}). ` +
+                'This may indicate an infinite loop, excessive tool calls, ' +
+                'or a logic error in your code.'
+            );
+          }
+
+          if (debug) {
+            // eslint-disable-next-line no-console
+            console.log(
+              `[BashPTC Debug] Round trip ${roundTrip}: ${response.tool_calls?.length ?? 0} tool(s) to execute`
+            );
+          }
+
+          const toolResults = await executeTools(
+            response.tool_calls ?? [],
+            toolMap
+          );
+
+          response = await makeRequest(
+            EXEC_ENDPOINT,
+            apiKey,
+            {
+              continuation_token: response.continuation_token,
+              tool_results: toolResults,
+            },
+            proxy
+          );
+        }
+
+        // ====================================================================
+        // Phase 3: Handle final state
+        // ====================================================================
+
+        if (response.status === 'completed') {
+          return formatCompletedResponse(response);
+        }
+
+        if (response.status === 'error') {
+          throw new Error(
+            `Execution error: ${response.error}` +
+              (response.stderr != null && response.stderr !== ''
+                ? `\n\nStderr:\n${response.stderr}`
+                : '')
+          );
+        }
+
+        throw new Error(`Unexpected response status: ${response.status}`);
+      } catch (error) {
+        throw new Error(
+          `Bash programmatic execution failed: ${(error as Error).message}`
+        );
+      }
+    },
+    {
+      name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+      description: BashProgrammaticToolCallingDescription,
+      schema: BashProgrammaticToolCallingSchema,
+      responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    }
+  );
+}