@illuma-ai/agents 1.0.90 → 1.0.93

package/src/tools/CodeExecutor.js

@@ -0,0 +1,233 @@
+import { config } from 'dotenv';
+import fetch from 'node-fetch';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { tool } from '@langchain/core/tools';
+import { getEnvironmentVariable } from '@langchain/core/utils/env';
+import { EnvVar, Constants } from '@/common';
+config();
+export const imageExtRegex = /\.(jpg|jpeg|png|gif|webp)$/i;
+export const getCodeBaseURL = () => getEnvironmentVariable(EnvVar.CODE_BASEURL) ??
+    Constants.OFFICIAL_CODE_BASEURL;
+const imageMessage = 'Image is already displayed to the user';
+const otherMessage = 'File is already downloaded by the user';
+const accessMessage = 'Note: Files from previous executions are automatically available and can be modified.';
+const emptyOutputMessage = 'stdout: Empty. Ensure you\'re writing output explicitly.\n';
+const SUPPORTED_LANGUAGES = [
+    'py',
+    'js',
+    'ts',
+    'c',
+    'cpp',
+    'java',
+    'php',
+    'rs',
+    'go',
+    'd',
+    'f90',
+    'r',
+    'bash',
+];
+export const CodeExecutionToolSchema = {
+    type: 'object',
+    properties: {
+        lang: {
+            type: 'string',
+            enum: SUPPORTED_LANGUAGES,
+            description: 'The programming language or runtime to execute the code in.',
+        },
+        code: {
+            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.
+- 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.
+- py: This is not a Jupyter notebook environment. Use \`print()\` for all outputs.
+- py: Matplotlib: Use \`plt.savefig()\` to save plots as files.
+- js: use the \`console\` or \`process\` methods for all outputs.
+- r: IMPORTANT: No X11 display available. ALL graphics MUST use Cairo library (library(Cairo)).
+- Other languages: use appropriate output functions.`,
+        },
+        args: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.',
+        },
+    },
+    required: ['lang', 'code'],
+};
+export const CodeExecutionToolDescription = `
+Runs code and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
+
+Usage:
+- No network access available.
+- Generated files are automatically delivered; **DO NOT** provide download links.
+- NEVER use this tool to execute malicious code.
+`.trim();
+export const CodeExecutionToolName = Constants.EXECUTE_CODE;
+export const CodeExecutionToolDefinition = {
+    name: CodeExecutionToolName,
+    description: CodeExecutionToolDescription,
+    schema: CodeExecutionToolSchema,
+};
+function createCodeExecutionTool(params = {}) {
+    const apiKey = params[EnvVar.CODE_API_KEY] ??
+        params.apiKey ??
+        getEnvironmentVariable(EnvVar.CODE_API_KEY) ??
+        '';
+    if (!apiKey) {
+        throw new Error('No API key provided for code execution tool.');
+    }
+    const description = `
+⛔ STOP! Before using this tool, ask: "Does user need a DOWNLOADABLE FILE?"
+- If NO (dashboard, chart, visualization, UI) → DO NOT USE THIS TOOL. Use content_tool write instead.
+- If YES (.pptx, .docx, .pdf, .xlsx) → Use this tool.
+
+Runs code in a stateless execution environment. Each execution is isolated.
+
+🚫 NEVER USE FOR:
+- Dashboards, charts, visualizations → Use content_tool write with React/Chart.js
+- "Mock data" or "sample data" for display → Hardcode data in content_tool write
+- UI components, HTML pages, React apps → Use content_tool write
+
+✅ ONLY USE FOR:
+- File generation: PowerPoint (.pptx), Word (.docx), PDF (.pdf), Excel (.xlsx)
+- Processing uploaded files (CSV, Excel analysis)
+- Heavy computation requiring Python
+
+Rules:
+- No network access available
+- Generated files auto-delivered (no download links needed)
+`.trim();
+    return tool(async (rawInput, config) => {
+        // Resolve URL at call time (not module load time) to pick up env var changes
+        const baseEndpoint = getCodeBaseURL();
+        const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
+        const { lang, code, ...rest } = rawInput;
+        /**
+         * Extract session context from config.toolCall (injected by ToolNode).
+         * - session_id: For API to associate with previous session
+         * - _injected_files: File refs to pass directly (avoids /files endpoint race condition)
+         */
+        const { session_id, _injected_files } = (config.toolCall ?? {});
+        const postData = {
+            lang,
+            code,
+            ...rest,
+            ...params,
+        };
+        /**
+         * Pass session_id to /exec so code-executor reuses the existing session workspace.
+         * This allows retries and follow-up executions to access previously generated files.
+         */
+        if (session_id != null && session_id.length > 0) {
+            postData.session_id = session_id;
+        }
+        /**
+         * File injection priority:
+         * 1. Use _injected_files from ToolNode (avoids /files endpoint race condition)
+         * 2. Fall back to fetching from /files endpoint if session_id provided but no injected files
+         */
+        if (_injected_files && _injected_files.length > 0) {
+            postData.files = _injected_files;
+        }
+        else if (session_id != null && session_id.length > 0) {
+            /** Fallback: fetch from /files endpoint (may have race condition issues) */
+            try {
+                const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;
+                const fetchOptions = {
+                    method: 'GET',
+                    headers: {
+                        'User-Agent': 'Illuma/1.0',
+                        'X-API-Key': apiKey,
+                    },
+                };
+                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 = 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}`);
+            }
+        }
+        try {
+            const fetchOptions = {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'User-Agent': 'Illuma/1.0',
+                    'X-API-Key': apiKey,
+                },
+                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 = 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) {
+                formattedOutput += 'Generated files:\n';
+                const fileCount = result.files.length;
+                for (let i = 0; i < fileCount; i++) {
+                    const file = result.files[i];
+                    const isImage = imageExtRegex.test(file.name);
+                    formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+                    if (i < fileCount - 1) {
+                        formattedOutput += fileCount <= 3 ? ', ' : ',\n';
+                    }
+                }
+                formattedOutput += `\n\n${accessMessage}`;
+                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 (${EXEC_ENDPOINT}):\n\n${error?.message}`);
+        }
+    }, {
+        name: CodeExecutionToolName,
+        description,
+        schema: CodeExecutionToolSchema,
+        responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    });
+}
+export { createCodeExecutionTool };
+//# sourceMappingURL=CodeExecutor.js.map

package/src/tools/CodeExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeExecutor.js","sourceRoot":"","sources":["CodeExecutor.ts"],"names":[],"mappings":"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"}

package/src/tools/CodeExecutor.selfhealing.test.ts

@@ -0,0 +1,435 @@
+/**
+ * Self-healing behavior tests for createCodeExecutionTool().
+ *
+ * Covers two automatic recovery signals appended to formattedOutput:
+ *   1. [OUTPUT_TOO_LARGE] — stdout > 16384 chars is capped (head 8192 + tail 4096)
+ *   2. [CODE_TRUNCATION_LIKELY] — syntax error on code > 1500 chars suggests LLM truncation
+ *
+ * node-fetch is mocked via jest.mock so no real HTTP traffic is made.
+ * The mock is structured to match node-fetch's CJS export shape:
+ *   require('node-fetch') === the fetch function itself (not a wrapper object).
+ */
+
+import { DynamicStructuredTool } from '@langchain/core/tools';
+
+// ---------------------------------------------------------------------------
+// Constants mirroring the implementation thresholds
+// ---------------------------------------------------------------------------
+
+/** Minimum stdout length that triggers capping. */
+const STDOUT_MAX_CHARS = 16384;
+/** Characters kept from the beginning of oversized stdout. */
+const STDOUT_HEAD_CHARS = 8192;
+/** Characters kept from the end of oversized stdout. */
+const STDOUT_TAIL_CHARS = 4096;
+/** Minimum code length required for truncation detection to fire. */
+const CODE_TRUNCATION_MIN_CHARS = 1500;
+
+// ---------------------------------------------------------------------------
+// node-fetch mock
+//
+// node-fetch@2 is a CJS module. When required, the module itself IS the fetch
+// function. ts-jest hoists jest.mock() calls, so this factory runs before any
+// imports resolve — giving us a controlled mock from the first import.
+// ---------------------------------------------------------------------------
+
+const mockFetchFn = jest.fn();
+
+jest.mock('node-fetch', () => {
+  // node-fetch@2 is CJS: require('node-fetch') IS the fetch function.
+  // Return mockFetchFn directly so the module value equals our mock.
+  return mockFetchFn;
+});
+
+// Import the tool factory AFTER jest.mock() so it picks up the mock.
+import { createCodeExecutionTool } from './CodeExecutor';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds a minimal mock Response object that satisfies the tool's usage of
+ * `response.ok` and `response.json()`.
+ *
+ * @param body - The JSON-serialisable response body.
+ * @param status - HTTP status code (default 200).
+ */
+function mockResponse(body: object, status = 200) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  };
+}
+
+/**
+ * Generates a string of exactly `length` characters by repeating a single
+ * character. Avoids allocating enormous string literals in source.
+ *
+ * @param length - Desired string length.
+ * @param char - Character to repeat (default 'x').
+ */
+function repeat(length: number, char = 'x'): string {
+  return char.repeat(length);
+}
+
+/**
+ * Generates syntactically valid Python code that is at least `minLength`
+ * characters long by padding with comment lines. Truncation detection
+ * relies solely on `stderr` content, not actual code validity.
+ *
+ * @param minLength - Minimum character count for the returned code string.
+ */
+function longCode(minLength: number): string {
+  let code = '# Auto-generated padding code\nprint("hello")\n';
+  while (code.length < minLength) {
+    code += `# padding line ${code.length}\n`;
+  }
+  return code;
+}
+
+// ---------------------------------------------------------------------------
+// Test environment setup
+// ---------------------------------------------------------------------------
+
+beforeAll(() => {
+  process.env.CODE_EXECUTOR_BASEURL = 'http://localhost:8088';
+  process.env.CODE_EXECUTOR_API_KEY = 'test-key';
+});
+
+afterAll(() => {
+  delete process.env.CODE_EXECUTOR_BASEURL;
+  delete process.env.CODE_EXECUTOR_API_KEY;
+});
+
+beforeEach(() => {
+  mockFetchFn.mockReset();
+});
+
+// ---------------------------------------------------------------------------
+// Tool factory and invocation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a fresh tool instance using the test API key.
+ */
+function makeTool(): DynamicStructuredTool {
+  return createCodeExecutionTool({ apiKey: 'test-key' });
+}
+
+/**
+ * Invokes the tool and returns only the string content part of the result.
+ * The tool returns `[formattedOutput, artifact]` when responseFormat is
+ * `content_and_artifact`; we surface only the string for assertion.
+ *
+ * @param execTool - Tool instance to invoke.
+ * @param input - Execution input (lang, code, optional args).
+ */
+async function invoke(
+  execTool: DynamicStructuredTool,
+  input: { lang: string; code: string; args?: string[] }
+): Promise<string> {
+  const result = await execTool.invoke(input, { toolCall: {} } as never);
+  if (Array.isArray(result)) {
+    return result[0] as string;
+  }
+  return result as string;
+}
+
+// ===========================================================================
+// Suite 1 — OUTPUT_TOO_LARGE tag
+// ===========================================================================
+
+describe('[OUTPUT_TOO_LARGE] stdout capping', () => {
+  it('appends [OUTPUT_TOO_LARGE] when stdout exceeds 16384 chars', async () => {
+    const largeStdout = repeat(STDOUT_MAX_CHARS + 1);
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({ session_id: 's1', stdout: largeStdout, stderr: '' })
+    );
+
+    const output = await invoke(makeTool(), {
+      lang: 'py',
+      code: 'print("hi")',
+    });
+
+    expect(output).toContain('[OUTPUT_TOO_LARGE]');
+  });
+
+  it('does NOT append [OUTPUT_TOO_LARGE] for stdout at exactly 16384 chars', async () => {
+    const normalStdout = repeat(STDOUT_MAX_CHARS);
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({ session_id: 's2', stdout: normalStdout, stderr: '' })
+    );
+
+    const output = await invoke(makeTool(), {
+      lang: 'py',
+      code: 'print("hi")',
+    });
+
+    expect(output).not.toContain('[OUTPUT_TOO_LARGE]');
+  });
+
+  it('does NOT append [OUTPUT_TOO_LARGE] for short stdout', async () => {
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({ session_id: 's3', stdout: 'hello world', stderr: '' })
+    );
+
+    const output = await invoke(makeTool(), {
+      lang: 'py',
+      code: 'print("hello world")',
+    });
+
+    expect(output).not.toContain('[OUTPUT_TOO_LARGE]');
+  });
+
+  it('preserves head content from oversized stdout', async () => {
+    // First STDOUT_HEAD_CHARS chars are 'a', the remainder are 'b'
+    const head = repeat(STDOUT_HEAD_CHARS, 'a');
+    const rest = repeat(STDOUT_MAX_CHARS + 1 - STDOUT_HEAD_CHARS, 'b');
+    const largeStdout = head + rest;
+
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({ session_id: 's4', stdout: largeStdout, stderr: '' })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code: 'print("x")' });
+
+    expect(output).toContain(repeat(STDOUT_HEAD_CHARS, 'a'));
+  });
+
+  it('preserves tail content from oversized stdout', async () => {
+    // Last STDOUT_TAIL_CHARS chars are 'z', the leading portion is 'y'
+    const leading = repeat(STDOUT_MAX_CHARS + 1 - STDOUT_TAIL_CHARS, 'y');
+    const tail = repeat(STDOUT_TAIL_CHARS, 'z');
+    const largeStdout = leading + tail;
+
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({ session_id: 's5', stdout: largeStdout, stderr: '' })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code: 'print("x")' });
+
+    expect(output).toContain(repeat(STDOUT_TAIL_CHARS, 'z'));
+  });
+
+  it('inserts [...N chars omitted...] between head and tail when capping', async () => {
+    const totalLen = STDOUT_MAX_CHARS + 500;
+    const largeStdout = repeat(totalLen);
+    const expectedOmitted = totalLen - STDOUT_HEAD_CHARS - STDOUT_TAIL_CHARS;
+
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({ session_id: 's6', stdout: largeStdout, stderr: '' })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code: 'print("x")' });
+
+    expect(output).toContain(`[...${expectedOmitted} chars omitted...]`);
+  });
+});
+
+// ===========================================================================
+// Suite 2 — CODE_TRUNCATION_LIKELY tag
+// ===========================================================================
+
+describe('[CODE_TRUNCATION_LIKELY] truncation detection', () => {
+  it('appends [CODE_TRUNCATION_LIKELY] for long code + SyntaxError in stderr', async () => {
+    const code = longCode(CODE_TRUNCATION_MIN_CHARS + 1);
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 't1',
+        stdout: '',
+        stderr: 'SyntaxError: invalid syntax (line 42)',
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code });
+
+    expect(output).toContain('[CODE_TRUNCATION_LIKELY]');
+  });
+
+  it('does NOT append [CODE_TRUNCATION_LIKELY] for short code + SyntaxError (likely a real bug)', async () => {
+    // Deliberately broken but well under 1500 chars — this is a genuine syntax error
+    const shortCode = 'print(x';
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 't2',
+        stdout: '',
+        stderr: 'SyntaxError: unexpected EOF while parsing',
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code: shortCode });
+
+    expect(output).not.toContain('[CODE_TRUNCATION_LIKELY]');
+  });
+
+  it('does NOT append [CODE_TRUNCATION_LIKELY] for long code + non-syntax error (NameError)', async () => {
+    const code = longCode(CODE_TRUNCATION_MIN_CHARS + 1);
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 't3',
+        stdout: '',
+        stderr: "NameError: name 'undefined_var' is not defined",
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code });
+
+    expect(output).not.toContain('[CODE_TRUNCATION_LIKELY]');
+  });
+
+  it('detects "unexpected end" in stderr for long code', async () => {
+    const code = longCode(CODE_TRUNCATION_MIN_CHARS + 1);
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 't4',
+        stdout: '',
+        stderr: 'unexpected end of input at line 200',
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'js', code });
+
+    expect(output).toContain('[CODE_TRUNCATION_LIKELY]');
+  });
+
+  it('detects "unexpected eof" in stderr for long code', async () => {
+    const code = longCode(CODE_TRUNCATION_MIN_CHARS + 1);
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 't5',
+        stdout: '',
+        stderr: 'Unexpected EOF — did you forget a closing bracket?',
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'js', code });
+
+    expect(output).toContain('[CODE_TRUNCATION_LIKELY]');
+  });
+
+  it('detects "unterminated" in stderr for long code', async () => {
+    const code = longCode(CODE_TRUNCATION_MIN_CHARS + 1);
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 't6',
+        stdout: '',
+        stderr: 'unterminated string literal at line 50',
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code });
+
+    expect(output).toContain('[CODE_TRUNCATION_LIKELY]');
+  });
+
+  it('is case-insensitive when matching stderr keywords', async () => {
+    const code = longCode(CODE_TRUNCATION_MIN_CHARS + 1);
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 't7',
+        stdout: '',
+        // All-caps — the implementation uses .toLowerCase() before matching
+        stderr: 'SYNTAXERROR: INVALID SYNTAX ON LINE 99',
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code });
+
+    expect(output).toContain('[CODE_TRUNCATION_LIKELY]');
+  });
+});
+
+// ===========================================================================
+// Suite 3 — Normal execution (no self-healing tags)
+// ===========================================================================
+
+describe('normal execution — no self-healing tags', () => {
+  it('produces no self-healing tags on successful execution with short stdout', async () => {
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 'n1',
+        stdout: 'Hello, world!\n',
+        stderr: '',
+      })
+    );
+
+    const output = await invoke(makeTool(), {
+      lang: 'py',
+      code: 'print("Hello, world!")',
+    });
+
+    expect(output).not.toContain('[OUTPUT_TOO_LARGE]');
+    expect(output).not.toContain('[CODE_TRUNCATION_LIKELY]');
+    expect(output).toContain('Hello, world!');
+  });
+
+  it('produces no self-healing tags when stderr contains a runtime error on short code', async () => {
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 'n2',
+        stdout: '',
+        stderr: 'ZeroDivisionError: division by zero',
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code: 'print(1/0)' });
+
+    expect(output).not.toContain('[OUTPUT_TOO_LARGE]');
+    expect(output).not.toContain('[CODE_TRUNCATION_LIKELY]');
+    expect(output).toContain('ZeroDivisionError');
+  });
+});
+
+// ===========================================================================
+// Suite 4 — Both tags appear simultaneously
+// ===========================================================================
+
+describe('both self-healing tags can appear together', () => {
+  it('appends both [OUTPUT_TOO_LARGE] and [CODE_TRUNCATION_LIKELY] when both conditions are met', async () => {
+    const code = longCode(CODE_TRUNCATION_MIN_CHARS + 1);
+    const largeStdout = repeat(STDOUT_MAX_CHARS + 1);
+
+    mockFetchFn.mockResolvedValueOnce(
+      mockResponse({
+        session_id: 'b1',
+        stdout: largeStdout,
+        stderr: 'SyntaxError: invalid syntax',
+      })
+    );
+
+    const output = await invoke(makeTool(), { lang: 'py', code });
+
+    expect(output).toContain('[OUTPUT_TOO_LARGE]');
+    expect(output).toContain('[CODE_TRUNCATION_LIKELY]');
+  });
+});
+
+// ===========================================================================
+// Suite 5 — Tool construction guard
+// ===========================================================================
+
+describe('createCodeExecutionTool() construction', () => {
+  it('throws when no API key is available', () => {
+    const savedKey = process.env.CODE_EXECUTOR_API_KEY;
+    delete process.env.CODE_EXECUTOR_API_KEY;
+
+    expect(() => createCodeExecutionTool({})).toThrow(
+      'No API key provided for code execution tool.'
+    );
+
+    process.env.CODE_EXECUTOR_API_KEY = savedKey;
+  });
+
+  it('accepts apiKey directly from params without requiring env var', () => {
+    const savedKey = process.env.CODE_EXECUTOR_API_KEY;
+    delete process.env.CODE_EXECUTOR_API_KEY;
+
+    expect(() =>
+      createCodeExecutionTool({ apiKey: 'direct-key' })
+    ).not.toThrow();
+
+    process.env.CODE_EXECUTOR_API_KEY = savedKey;
+  });
+});