feat: unsafe local code executor

Author: kalenkevich

core/src/code_executors/base_code_executor.ts

@@ -72,16 +72,18 @@ export abstract class BaseCodeExecutor {
 
   /**
    * The list of the enclosing delimiters to identify the code blocks.
-   * For example, the delimiter('```python\\n', '\\n```') can be  used to
-   * identify code blocks with the following format::
+   * For example, the delimiter('```javascript\\n', '\\n```') can be used to
+   * identify code blocks with the following format:
    *
-   * ```python
-   *  print("hello")
+   * ```javascript
+   *  console.log("hello")
    * ```
    */
   codeBlockDelimiters: Array<[string, string]> = [
     ['```tool_code\n', '\n```'],
     ['```python\n', '\n```'],
+    ['```javascript\n', '\n```'],
+    ['```typescript\n', '\n```'],
   ];
 
   /**

core/src/code_executors/unsafe_local_code_executor.ts

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {spawn} from 'child_process';
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {BaseCodeExecutor, ExecuteCodeParams} from './base_code_executor.js';
+import {CodeExecutionResult} from './code_execution_utils.js';
+
+/**
+ * Options for UnsafeLocalCodeExecutor.
+ */
+export interface UnsafeLocalCodeExecutorOptions {
+  /**
+   * Timeout for code execution in seconds. Default is 30.
+   */
+  timeoutSeconds?: number;
+  /**
+   * The command to run the code. Default is `process.execPath` (Node.js).
+   */
+  commandPath?: string;
+}
+
+async function createTempJsFile(code: string): Promise<string> {
+  const tempDir = path.join(
+    os.tmpdir(),
+    'adk_js_unsafe_code_executor',
+    Date.now().toString(),
+  );
+  await fs.mkdir(tempDir, {recursive: true});
+  const filePath = path.join(tempDir, 'script.js');
+  await fs.writeFile(filePath, code);
+
+  return filePath;
+}
+
+/**
+ * A code executor that unsafely executes code in the local context.
+ * By default, it executes JavaScript code using the current Node.js executable.
+ */
+export class UnsafeLocalCodeExecutor extends BaseCodeExecutor {
+  private readonly timeoutSeconds: number;
+  private readonly commandPath: string;
+
+  constructor(options: UnsafeLocalCodeExecutorOptions = {}) {
+    super();
+    this.timeoutSeconds = options.timeoutSeconds ?? 30;
+    this.commandPath = options.commandPath ?? process.execPath;
+    this.stateful = false;
+    this.optimizeDataFile = false;
+  }
+
+  async executeCode(params: ExecuteCodeParams): Promise<CodeExecutionResult> {
+    const {code} = params.codeExecutionInput;
+
+    let filePath: string | undefined;
+    try {
+      filePath = await createTempJsFile(code);
+
+      return await new Promise<CodeExecutionResult>((resolve) => {
+        const child = spawn(this.commandPath, [filePath!], {
+          timeout: this.timeoutSeconds * 1000,
+          killSignal: 'SIGKILL',
+        });
+
+        let stdout = '';
+        let stderr = '';
+
+        if (child.stdout) {
+          child.stdout.on('data', (data) => {
+            stdout += data.toString();
+          });
+        }
+
+        if (child.stderr) {
+          child.stderr.on('data', (data) => {
+            stderr += data.toString();
+          });
+        }
+
+        child.on('error', (err) => {
+          stderr += `Process error: ${err.message}\n`;
+        });
+
+        child.on('close', (exitCode, signal) => {
+          if (signal === 'SIGKILL' || signal === 'SIGTERM') {
+            stderr += `\nCode execution timed out after ${this.timeoutSeconds} seconds.`;
+          }
+          resolve({
+            stdout,
+            stderr,
+            outputFiles: [],
+          });
+        });
+      });
+    } finally {
+      if (filePath) {
+        await fs.rm(filePath, {recursive: true, force: true});
+      }
+    }
+  }
+}

core/src/index.ts

@@ -26,6 +26,7 @@ export type {ExecutorContext} from './a2a/executor_context.js';
 export {FileArtifactService} from './artifacts/file_artifact_service.js';
 export {GcsArtifactService} from './artifacts/gcs_artifact_service.js';
 export {getArtifactServiceFromUri} from './artifacts/registry.js';
+export {UnsafeLocalCodeExecutor} from './code_executors/unsafe_local_code_executor.js';
 export * from './common.js';
 export {DatabaseSessionService} from './sessions/database_session_service.js';
 export {getSessionServiceFromUri} from './sessions/registry.js';

core/test/code_executors/base_code_executor_test.ts

@@ -0,0 +1,63 @@
+import {describe, expect, it} from 'vitest';
+import {
+  BaseCodeExecutor,
+  ExecuteCodeParams,
+  isBaseCodeExecutor,
+} from '../../src/code_executors/base_code_executor.js';
+import {CodeExecutionResult} from '../../src/code_executors/code_execution_utils.js';
+
+class TestExecutor extends BaseCodeExecutor {
+  async executeCode(_params: ExecuteCodeParams): Promise<CodeExecutionResult> {
+    return {stdout: '', stderr: '', outputFiles: []};
+  }
+}
+
+describe('BaseCodeExecutor', () => {
+  it('should have default values', () => {
+    const executor = new TestExecutor();
+    expect(executor.optimizeDataFile).toBe(false);
+    expect(executor.stateful).toBe(false);
+    expect(executor.errorRetryAttempts).toBe(2);
+  });
+
+  it('should have default delimiters', () => {
+    const executor = new TestExecutor();
+    const bt = String.fromCharCode(96);
+    const threeBt = bt + bt + bt;
+
+    expect(executor.codeBlockDelimiters).toEqual([
+      [threeBt + 'tool_code\n', '\n' + threeBt],
+      [threeBt + 'python\n', '\n' + threeBt],
+      [threeBt + 'javascript\n', '\n' + threeBt],
+      [threeBt + 'typescript\n', '\n' + threeBt],
+    ]);
+
+    expect(executor.executionResultDelimiters).toEqual([
+      threeBt + 'tool_output\n',
+      '\n' + threeBt,
+    ]);
+  });
+
+  it('should identify instances', () => {
+    const executor = new TestExecutor();
+    expect(isBaseCodeExecutor(executor)).toBe(true);
+  });
+
+  it('should reject non-instances', () => {
+    expect(isBaseCodeExecutor({})).toBe(false);
+    expect(isBaseCodeExecutor(null)).toBe(false);
+    expect(isBaseCodeExecutor(undefined)).toBe(false);
+
+    // Test with symbol
+    const objWithSymbol = {};
+    Object.defineProperty(
+      objWithSymbol,
+      Symbol.for('google.adk.baseCodeExecutor'),
+      {
+        value: true,
+        enumerable: true,
+      },
+    );
+    expect(isBaseCodeExecutor(objWithSymbol)).toBe(true);
+  });
+});

core/test/code_executors/unsafe_local_code_executor_test.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  ExecuteCodeParams,
+  InvocationContext,
+  LlmAgent,
+  PluginManager,
+  UnsafeLocalCodeExecutor,
+  createSession,
+} from '@google/adk';
+import {beforeEach, describe, expect, it} from 'vitest';
+
+function createMockInvocationContext(): InvocationContext {
+  const agent = new LlmAgent({
+    name: 'test_agent',
+    model: 'gemini-2.5-flash',
+  });
+
+  return new InvocationContext({
+    invocationId: 'test-invocation',
+    agent,
+    session: createSession({
+      id: 'test-session',
+      events: [],
+      appName: 'test-app',
+      userId: 'test-user',
+    }),
+    pluginManager: new PluginManager([]),
+  });
+}
+
+describe('UnsafeLocalCodeExecutor', () => {
+  let executor: UnsafeLocalCodeExecutor;
+  const invocationContext = createMockInvocationContext();
+
+  beforeEach(() => {
+    executor = new UnsafeLocalCodeExecutor();
+  });
+
+  it('should execute code and return stdout', async () => {
+    const params: ExecuteCodeParams = {
+      invocationContext,
+      codeExecutionInput: {
+        code: 'console.log("Hello, World!");',
+        inputFiles: [],
+      },
+    };
+
+    const result = await executor.executeCode(params);
+
+    expect(result.stdout).toContain('Hello, World!');
+    expect(result.stderr).toBe('');
+  });
+
+  it('should capture stderr', async () => {
+    const params: ExecuteCodeParams = {
+      invocationContext,
+      codeExecutionInput: {
+        code: 'console.error("An error occurred");',
+        inputFiles: [],
+      },
+    };
+
+    const result = await executor.executeCode(params);
+
+    expect(result.stderr).toContain('An error occurred');
+  });
+
+  it('should handle execution errors', async () => {
+    const params: ExecuteCodeParams = {
+      invocationContext,
+      codeExecutionInput: {
+        code: 'throw new Error("Fatal error");',
+        inputFiles: [],
+      },
+    };
+
+    const result = await executor.executeCode(params);
+
+    expect(result.stderr).toContain('Fatal error');
+  });
+
+  it('should respect timeout', async () => {
+    // Create executor with 1 second timeout
+    const shortTimeoutExecutor = new UnsafeLocalCodeExecutor({
+      timeoutSeconds: 1,
+    });
+
+    const params: ExecuteCodeParams = {
+      invocationContext,
+      codeExecutionInput: {
+        code: 'setTimeout(() => {}, 5000);', // Sleep for 5 seconds
+        inputFiles: [],
+      },
+    };
+
+    const result = await shortTimeoutExecutor.executeCode(params);
+
+    expect(result.stderr).toContain(
+      'Code execution timed out after 1 seconds.',
+    );
+  });
+});