@animalabs/agent-framework 0.23.2 → 0.24.0

package/src/code-execution/tool-definition.ts

@@ -1,104 +1,212 @@
 /**
- * Synthesized `code_execution` tool definition.
- *
- * The name, input shape ({code}), and description framing deliberately track
- * Anthropic's server-side programmatic tool calling so models' trained
- * priors transfer: python scripts, tools as async functions taking a single
- * dict and returning a string, stdout as the return channel, persistent
- * interpreter state, asyncio.gather for fan-out.
+ * `code_execution`: its configuration, the check that refuses one that still
+ * sets what the Python runner took, and the tool's definition, the text an
+ * agent reads before it writes a script. It follows the surface of Code Mode
+ * tools elsewhere (exact names, one result shape, top-level await), and says
+ * each rule once.
  */
 
-import type { ToolDefinition } from '../types/index.js';
-import { assertBooleanSetting, holdsSettings, kindOf } from '../config-checks.js';
-import { formatLimit, MAX_TIMER_MS } from './py-runner.js';
+import type { CodeExecutionConfig, ToolDefinition } from '../types/index.js';
+import { assertBooleanSetting, holdsSettings } from '../config-checks.js';
+import { MAX_MEMORY_BYTES, MAX_RESULT_DEPTH, MIN_MEMORY_BYTES } from './engine.js';
+import { DEFAULT_OUTPUT_BOUNDS } from './isolate/output.js';
+import { MAX_ARGUMENT_BYTES, MAX_ARGUMENT_VALUES, MAX_CALLS_IN_FLIGHT, MAX_WAKE_PAYLOAD_BYTES } from './isolate/protocol.js';
+import { formatMs, VALUE_CHARS } from './isolate/render.js';
+
+const PAGE_BYTES = 64 * 1024;
 
 export const CODE_EXECUTION_TOOL_NAME = 'code_execution';
 
-export function buildCodeExecutionToolDefinition(opts?: {
-  idleReclaimMs?: number;
-  toolCallTimeoutMs?: number;
-  scriptTimeoutMs?: number;
-  maxScriptTimeoutMs?: number;
-  backgroundMaxLifetimeMs?: number;
-}): ToolDefinition {
-  const idleMinutes = Math.max(1, Math.round((opts?.idleReclaimMs ?? 300_000) / 60_000));
-  const callTimeoutSeconds = Math.round((opts?.toolCallTimeoutMs ?? 270_000) / 1000);
-  const limits = scriptTimeLimits(opts);
+/** The isolate's settings. Each has a default. */
+export interface IsolateSettings {
+  /** The bound a run or wait yields at, unless the agent asks otherwise. */
+  yieldMs: number;
+  /** The most an agent may ask for. */
+  maxYieldMs: number;
+  /** A script's limit: there it's stopped. */
+  scriptLifetimeMs: number;
+  /** Scripts one agent may have running at once, yielded ones included. */
+  maxRunningScripts: number;
+  /** Script children a host runs at once. */
+  maxScriptChildren: number;
+  /** How long a call may go unanswered before the script is told it timed out. */
+  toolCallTimeoutMs: number;
+  wakeMinIntervalMs: number;
+  maxWakesPerScript: number;
+  /**
+   * The WebAssembly memory's maximum for each script: its budget, a whole
+   * number of 64 KiB pages from 4 MiB to 2 GiB. A child stays within about its
+   * runtime's base plus 2.7 times this: the linear memory itself, and a result
+   * in transit, which takes two to five times its size and is refused past a
+   * third of this. Beside that come the script's calls as they go out, held
+   * while a result settles or not: at most 16 at once, the calls the prelude
+   * lets out, each with at most 4 MiB of JSON arguments, which the child holds
+   * as text and encodes, up to about 200 MiB under Node and 410 MiB under
+   * Bun. Measured on the child under Node 24.22.0 and Bun 1.4.3, whose base
+   * was about 85 and 55 MiB, at budgets from 32 MiB to 1 GiB.
+   *
+   * The host holds, for each script, the calls it has out and their answers:
+   * at most 16 calls out in the host at once, timed-out ones whose tools still
+   * run included, each with at most 4 MiB of JSON arguments holding 100,000
+   * values (about 25 MiB as text and parsed, by a probe of the costliest
+   * shapes under Node 24 and Bun 1.4), up to 16 more waiting for those as
+   * their text (at most 8 MiB each), up to 16 answers until the child takes
+   * them, each at most a third of this as its frame, and the one being
+   * encoded also as its JSON text (up to twice its bytes), the frame from the
+   * child being read (at most 25 MiB, and its text and its parse up to twice
+   * that each, since a string can take two bytes a character: 125 MiB), and
+   * its waiting wakes, at most 64 KiB of JSON each, up to 128 KiB as text.
+   * That's at most about 6 times this, plus 653 MiB,
+   * plus 128 KiB for each wake maxWakesPerScript allows: about 1.4 GiB a
+   * script at the defaults. A tool's
+   * own result, and the one serialization the bridge makes of it to check its
+   * size, are the tool's, outside this. Size a host by that and by the
+   * child's own memory.
+   *
+   * A result is sent only if it's at most a third of this; within that, what
+   * fits the script depends on its shape, since parsing builds it in this
+   * memory: at 128 MiB, a string or an array of numbers up to that third fits,
+   * and an array of small objects up to about 24 MiB, by a probe of each
+   * shape. A result that doesn't fit reaches the script as ResultTooLarge,
+   * which says the call took effect.
+   */
+  memoryMaxBytes: number;
+}
+
+export const DEFAULT_SETTINGS: IsolateSettings = {
+  yieldMs: 30_000,
+  maxYieldMs: 600_000,
+  scriptLifetimeMs: 86_400_000,
+  maxRunningScripts: 3,
+  maxScriptChildren: 16,
+  toolCallTimeoutMs: 270_000,
+  wakeMinIntervalMs: 60_000,
+  maxWakesPerScript: 100,
+  memoryMaxBytes: 128 * 1024 * 1024,
+};
+
+/** What the Python runner took that the isolate doesn't, and what to set instead. */
+const RETIRED: Record<string, string> = {
+  pythonPath: 'scripts are JavaScript now, run by an engine built into agent-framework, so there is no interpreter to name; leave it out',
+  idleReclaimMs: 'each script starts fresh and keeps nothing after it ends, so there is nothing to reclaim; leave it out',
+  env: "a script's world holds only your agent's tools, with no environment; leave it out",
+  inheritEnv: "a script's world holds only your agent's tools, with no environment; leave it out",
+  scriptTimeoutMs: 'a script now yields at its bound and keeps running: set yieldMs for the bound',
+  maxScriptTimeoutMs: 'set maxYieldMs, the most an agent may ask a run or a wait to wait',
+  backgroundMaxLifetimeMs: "every script now has one limit: set scriptLifetimeMs",
+  maxBackgroundScripts: 'set maxRunningScripts, how many scripts an agent may have running at once, yielded ones included',
+};
+
+const MS_KEYS = ['yieldMs', 'maxYieldMs', 'scriptLifetimeMs', 'toolCallTimeoutMs', 'wakeMinIntervalMs'] as const;
+const COUNT_KEYS = ['maxRunningScripts', 'maxScriptChildren', 'maxWakesPerScript', 'memoryMaxBytes'] as const;
+/** Node's timer range: a timer longer than this fires at once. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/**
+ * The isolate's settings from a `codeExecution` configuration that's on, with each
+ * default filled in. Throws, naming the key and what to do, for a key the
+ * Python runner took, or a value that isn't a whole number in range.
+ */
+export function isolateSettings(cfg: Record<string, unknown>): IsolateSettings {
+  for (const [key, why] of Object.entries(RETIRED)) {
+    if (cfg[key] !== undefined && cfg[key] !== null) throw new Error(`codeExecution.${key} is no longer read: ${why}`);
+  }
+  const out: IsolateSettings = { ...DEFAULT_SETTINGS };
+  for (const key of [...MS_KEYS, ...COUNT_KEYS]) {
+    const value = cfg[key];
+    if (value === undefined || value === null) continue;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+      throw new Error(`codeExecution.${key} must be a whole number of ${MS_KEYS.includes(key as never) ? 'milliseconds' : 'units'} of 0 or more`);
+    }
+    if (MS_KEYS.includes(key as never) && value > MAX_TIMER_MS) {
+      throw new Error(`codeExecution.${key} must be at most ${MAX_TIMER_MS} ms, the longest a timer can wait`);
+    }
+    (out as unknown as Record<string, number>)[key] = value;
+  }
+  if (out.maxYieldMs < out.yieldMs) {
+    throw new Error(`codeExecution.maxYieldMs (${out.maxYieldMs}) must be at least yieldMs (${out.yieldMs}): the default is always allowed`);
+  }
+  if (out.maxRunningScripts < 1 || out.maxScriptChildren < 1) {
+    throw new Error('codeExecution.maxRunningScripts and maxScriptChildren must each be at least 1');
+  }
+  if (out.memoryMaxBytes % PAGE_BYTES !== 0 || out.memoryMaxBytes < MIN_MEMORY_BYTES || out.memoryMaxBytes > MAX_MEMORY_BYTES) {
+    throw new Error(
+      `codeExecution.memoryMaxBytes must be a whole number of 64 KiB pages from ${MIN_MEMORY_BYTES} (4 MiB) to ${MAX_MEMORY_BYTES} (2 GiB), not ${out.memoryMaxBytes}`,
+    );
+  }
+  return out;
+}
+
+function formatBytes(bytes: number): string {
+  const MiB = 1024 * 1024;
+  if (bytes % (1024 * MiB) === 0) return `${bytes / (1024 * MiB)} GiB`;
+  if (bytes % MiB === 0) return `${bytes / MiB} MiB`;
+  if (bytes % 1024 === 0) return `${bytes / 1024} KiB`;
+  return `${bytes} bytes`;
+}
+
+/**
+ * The `code_execution` tool as an agent is offered it under these settings,
+ * the `codeExecution` that `create()` takes (each left out has its default).
+ * A setting the Python runner took is refused by name, as `create()` refuses it.
+ */
+export function buildCodeExecutionToolDefinition(config: Partial<CodeExecutionConfig> = {}): ToolDefinition {
+  return describeCodeExecution(isolateSettings(config as unknown as Record<string, unknown>));
+}
+
+/** The tool's definition under settings already resolved. */
+export function describeCodeExecution(s: IsolateSettings): ToolDefinition {
+  const { headChars, tailChars } = DEFAULT_OUTPUT_BOUNDS;
+  const chars = (n: number) => n.toLocaleString('en-US');
   return {
     name: CODE_EXECUTION_TOOL_NAME,
     description:
-      'Run Python code that can call your other tools programmatically. ' +
-      'Every tool you have is available inside the script as an async Python function: ' +
-      "the function name is the tool name with '--' replaced by '__' and any other " +
-      "non-identifier character replaced by '_' " +
-      "(e.g. tool 'mcpl--discord--fetch_history' is the function mcpl__discord__fetch_history, " +
-      "and tool 'mcpl--dog-events--status' is mcpl__dog_events__status). " +
-      'Each function takes a single dict of arguments and returns a string: the text the tool ' +
-      'would have returned to you directly, or "Error: ..." if the call failed. For a result ' +
-      'with structured content, the string is a JSON object to parse with json.loads: ' +
-      '{"content": [...], "structuredContent": ..., "isError": false}, with "error" added when ' +
-      `"isError" is true. "content" holds the server's content blocks. A reference to a payload ` +
-      'appears there as {"type": ..., "refId": ..., "savedTo": ...}, where "savedTo" is the ' +
-      `workspace path the payload was saved to (null if it wasn't) and "refId" is fetch_reference's ` +
-      'ref_id. A structured result over 5 MB is saved to the workspace instead, and the string is ' +
-      '{"isError": ..., "oversized": {"chars": ..., "savedTo": ...}}. ' +
-      'Each string also carries .is_error (True if the result is an error, else False; test it ' +
-      'rather than an "Error:" prefix) and .structured (the parsed "structuredContent" of the ' +
-      'JSON object above, or None). ' +
-      "An exact-name lookup dict is also available: tools['mcpl--discord--fetch_history']({...}). " +
-      'Use top-level await; run independent calls in parallel with asyncio.gather. ' +
-      'Only what you print() (plus stderr and the exit code) comes back to you — intermediate ' +
-      'tool results stay in the script, so filter or aggregate large data there and print only ' +
-      'what you need. Interpreter state (variables, imports) persists across code_execution ' +
-      `calls but is reclaimed after ~${idleMinutes} minutes idle. Relative paths resolve in a ` +
-      'scratch directory of the interpreter\'s, which goes whenever it stops or is reclaimed, so a file meant to ' +
-      'outlast the interpreter needs an absolute path. A tool call that receives no ' +
-      `response within ~${callTimeoutSeconds}s raises TimeoutError inside the script. ` +
-      `A foreground script is stopped after ${formatLimit(limits.defaultMs)}; pass time_limit_ms to set this call's limit ` +
-      `(at most ${formatLimit(limits.maxMs)}; a background script runs up to ${formatLimit(limits.backgroundMaxMs)}). ` +
-      'Stopping a script does not stop tools it already called. ' +
-      'Use this when fanning out across many items, looping over tool calls, or when tool ' +
-      'results are large and you only need a slice or summary. Call tools directly (not via ' +
-      'code) when a single call answers the question or when you need to reason about each ' +
-      'result before deciding the next step. ' +
-      'BACKGROUND MODE: pass background=true to run the script as a detached watcher that ' +
-      'outlives this turn — the tool returns immediately with a script_id and you can end ' +
-      'your turn (e.g. sleep). Inside a background script, await wake_agent(payload) wakes ' +
-      'you: the payload plus provenance (script id, the line number in your script, elapsed ' +
-      'time) is delivered into your context and starts a turn for you. A script that ends ' +
-      'without calling wake_agent wakes nobody — that silence is the point (poll cheaply, ' +
-      'wake only on signal). If your background script CRASHES you are woken with the error. ' +
-      'Its print() output streams to a workspace log file you can read any time. Wakes are ' +
-      'rate-limited (early wakes are delayed, not dropped) and capped per script. ' +
-      'CAUTION: background scripts die silently if the host process restarts — for a wake ' +
-      'you absolutely must not miss, also arm a wake rule as backup. ' +
-      'Manage your scripts with {"action": "list"} and {"action": "cancel", "script_id": "..."}.',
+      'Run JavaScript that calls your other tools, so that many calls, and the results between them, happen in one step and stay out of your context. ' +
+      'The script is the body of an async function: await at its top level, and return a value to see it. ' +
+      `The value comes back as JSON, and past ${chars(VALUE_CHARS)} characters as its first and last ${chars(VALUE_CHARS / 2)}. It's made in the script's memory, so a large one needs room there for its text twice over. ` +
+      'Call a tool by its exact name, as ALL_TOOLS gives it: await tools["module--tool"]({ ...its arguments }). ' +
+      'Every tool answers one shape, { content, structuredContent, isError }: content is a list of blocks, what you would have read, most often one { type: "text", text }; ' +
+      "structuredContent is the tool's data as a value, when it gives one beside that text, otherwise null; and isError is true when the tool failed, its text saying why. " +
+      'With no structuredContent, the answer is in content, most often its text: JSON.parse(result.content[0].text) reads one given as JSON. ' +
+      'A tool that turns a call down itself, such as for a missing argument, answers this way, with isError. ' +
+      "A call that can't go out (the tool isn't yours now, or its arguments aren't an object) doesn't answer: its await throws a ToolRefused error, and nothing is sent for it. " +
+      'A Promise.all holding it rejects with that error, while the calls beside it still go out. ' +
+      `A call's arguments may be up to ${formatBytes(MAX_ARGUMENT_BYTES)} of JSON with at most ${chars(MAX_ARGUMENT_VALUES)} values: ` +
+      'a generated file of a few MB of ordinary text fits as one string (quotes, backslashes and control characters take more room once escaped), and more goes in parts, over several calls. ' +
+      `ALL_TOOLS lists your tools, each with its name, description and inputSchema. Run independent calls together with Promise.all: up to ${MAX_CALLS_IN_FLIGHT} are out at once, and the rest wait their turn. ` +
+      `A call out that gets no answer within ${formatMs(s.toolCallTimeoutMs)} throws a TimeoutError that says whether it was sent: one never sent did nothing, but one sent may still take effect, so a retry may do it twice. ` +
+      'Write output with text(value) or console.log(...): only what the script writes and returns comes back to you, with how it ended and what became of its calls, ' +
+      'so filter large results in the script. ' +
+      'Each script starts fresh and keeps nothing after it ends: write what must last with a tool. ' +
+      'A script reaches nothing but your tools: no network, files, timers or packages. ' +
+      `A script has ${formatBytes(s.memoryMaxBytes)} of memory. A result too large for it, or nested more than ${chars(MAX_RESULT_DEPTH)} deep, doesn't reach the script: the call's ResultTooLarge error says the tool ran. ` +
+      `A run or a wait takes yield_time_ms, how long to wait for the script (default ${formatMs(s.yieldMs)}, at most ${formatMs(s.maxYieldMs)}). ` +
+      'If the script is still running then, you get what it has written, and it keeps running: ' +
+      '{"action": "wait", "script_id": ...} waits again, {"action": "stop", "script_id": ...} stops it, and {"action": "list"} lists your scripts. ' +
+      `Each return shows what the script wrote since the previous one: its first ${chars(headChars)} and last ${chars(tailChars)} characters, with a count of what was dropped between them. ` +
+      "A return longer than your inline cap for tool results (tool_result_inline_max_chars in agent_settings) has its output's first and last parts cut alike to fit; " +
+      "if the rest of the return leaves the output no room, the return is cut there as any long tool result is, keeping its start. " +
+      "You may leave a script running past your turn, unless the host names another agent as its primary agent, whose scripts alone outlive a turn: " +
+      'a yield says when yours will be stopped at your turn\'s end. ' +
+      `A script left running can wake you with await wake_agent(payload), a payload of at most ${formatBytes(MAX_WAKE_PAYLOAD_BYTES)} of JSON, ` +
+      `and you are woken if it fails, crashes or reaches its limit of ${formatMs(s.scriptLifetimeMs)}; a clean finish waits for your wait or list. ` +
+      'A script whose body returns while its calls are still running waits for them, and for the calls its pending work goes on to make: ' +
+      "it's still running until they're done. " +
+      'When a script ends, the result says how, what became of its calls (any still running when it was stopped may or may not have taken effect), ' +
+      `what it returned, and its output. You may have ${s.maxRunningScripts} scripts running at once.`,
     inputSchema: {
       type: 'object' as const,
       properties: {
-        code: {
-          type: 'string',
-          description: 'Python code to execute. Top-level await is allowed.',
-        },
-        background: {
-          type: 'boolean',
-          description: 'Run detached as a background watcher with wake_agent() available (default false).',
-        },
+        code: { type: 'string', description: 'JavaScript to run, as the body of an async function.' },
         action: {
           type: 'string',
-          enum: ['run', 'list', 'cancel'],
-          description: 'run (default) executes `code`; list shows your background scripts; cancel stops one.',
+          enum: ['run', 'wait', 'stop', 'list'],
+          description: 'run (default) runs code; wait and stop take a script_id; list shows your scripts.',
         },
-        script_id: {
-          type: 'string',
-          description: 'Background script id (for action: cancel).',
-        },
-        time_limit_ms: {
+        script_id: { type: 'string', description: 'The script to wait for or stop.' },
+        yield_time_ms: {
           type: 'integer',
-          description:
-            `Time limit for this script in milliseconds; it is stopped when the limit is reached. ` +
-            `Default ${limits.defaultMs}, at most ${limits.maxMs}; a background script defaults to and is capped at ` +
-            `its ${formatLimit(limits.backgroundMaxMs)} lifetime.`,
+          description: `For a run or a wait: how long to wait for the script, in milliseconds, before it yields. Default ${s.yieldMs}, at most ${s.maxYieldMs}.`,
         },
       },
       required: [],
@@ -106,98 +214,59 @@ export function buildCodeExecutionToolDefinition(opts?: {
   };
 }
 
+/** The first Bun a script's process runs on reliably. */
+export const MIN_BUN_VERSION = '1.4.0';
+
 /**
- * A script's time limits: the default, the most an agent may ask for with
- * `time_limit_ms`, and the background lifetime (default and ceiling at once).
+ * Why code execution can't run on this Bun, or null when it can (and under
+ * Node, where `bun` is undefined). Bun 1.3.14 loses a child's fd 3, the pipe a
+ * script's process answers on, at some starts: in a probe, 30 of 200 children
+ * started one at a time lost it before their first write, where under Bun
+ * 1.4.0 through 1.4.3, and Node 24, none of 200 did.
  */
-export function scriptTimeLimits(opts?: {
-  scriptTimeoutMs?: number;
-  maxScriptTimeoutMs?: number;
-  backgroundMaxLifetimeMs?: number;
-}): { defaultMs: number; maxMs: number; backgroundMaxMs: number } {
-  // Every limit fits Node's timer range (MAX_TIMER_MS, ~24.8 days).
-  const defaultMs = Math.min(MAX_TIMER_MS, opts?.scriptTimeoutMs ?? 600_000);
-  return {
-    defaultMs,
-    // A ceiling below the default is refused when a framework with code
-    // execution on is created (validateCodeExecutionConfig); never below the
-    // default here either.
-    maxMs: Math.min(MAX_TIMER_MS, Math.max(defaultMs, opts?.maxScriptTimeoutMs ?? defaultMs)),
-    backgroundMaxMs: Math.min(MAX_TIMER_MS, opts?.backgroundMaxLifetimeMs ?? 86_400_000),
-  };
+export function bunVersionProblem(bun: string | null): string | null {
+  if (bun === null) return null;
+  const parts = (v: string) => v.split(/[.-]/).slice(0, 3).map((n) => Number.parseInt(n, 10) || 0);
+  const [have, need] = [parts(bun), parts(MIN_BUN_VERSION)];
+  for (let i = 0; i < 3; i++) {
+    if (have[i]! > need[i]!) return null;
+    if (have[i]! < need[i]!) {
+      return `codeExecution needs Bun ${MIN_BUN_VERSION} or later, and this host runs Bun ${bun}, ` +
+        "which at some starts loses the pipe a script's process answers on, crashing the script: " +
+        `move the host to Bun ${MIN_BUN_VERSION} or later, or run it on Node`;
+    }
+  }
+  // The floor's own version, as a prerelease (1.4.0-canary.1), comes before it,
+  // and no such build was checked.
+  return /^\d+\.\d+\.\d+-/.test(bun)
+    ? `codeExecution needs Bun ${MIN_BUN_VERSION} or later, and this host runs Bun ${bun}, a build from before ${MIN_BUN_VERSION}'s release, ` +
+      `which hasn't been checked with it: move the host to Bun ${MIN_BUN_VERSION} or later, or run it on Node`
+    : null;
 }
 
 /**
  * Refuse a codeExecution that isn't an object, or whose switch is set to
- * anything but true or false, and, once it's on, one whose time limits
- * contradict each other or whose interpreter environment would be misread. A
- * JSON config, or a `${VAR}` substituted as a string, can carry a quoted
- * "false" where the type says boolean, and only `true` turns code execution
- * on, so the quotes would hide what the value does; a bare
- * `codeExecution: true` would be read as off. Likewise the runner passes the
- * host's environment only for an `inheritEnv` of `true`, so a quoted "true"
- * would quietly keep the allowlist. A null or false codeExecution, and a null
- * setting, count as not set, as left-out ones do. The refusal names the
- * value's kind, not the value. A configuration that isn't on has nothing else
+ * anything but true or false, and, once it's on, one that sets what the
+ * Python runner took or a value out of range (isolateSettings), or that a Bun
+ * too old to run it would run (bunVersionProblem). A JSON config,
+ * or a `${VAR}` substituted as a string, can carry a quoted "false" where the
+ * type says boolean, and only `true` turns code execution on, so the quotes
+ * would hide what the value does. A null or false codeExecution counts as not
+ * set, as a left-out one does. A configuration that isn't on has nothing else
  * read.
  */
-export function validateCodeExecutionConfig(cfg: {
-  enabled?: unknown;
-  scriptTimeoutMs?: number;
-  maxScriptTimeoutMs?: number;
-  env?: unknown;
-  inheritEnv?: unknown;
-}): void {
+/** `bun` is the Bun this runs on, null under Node: the running one's when left out. */
+export function validateCodeExecutionConfig(cfg: unknown, bun: string | null = process.versions.bun ?? null): void {
   if (!holdsSettings('codeExecution', cfg, '{ enabled: true }')) return;
+  const settings = cfg as Record<string, unknown>;
   assertBooleanSetting(
     'codeExecution.enabled',
-    cfg.enabled,
-    'true gives agents the code_execution tool, which runs their scripts in a python interpreter on the host, ' +
-      'and false or leaving it out doesn\'t',
-  );
-  if (cfg.enabled !== true) return;
-  const defaultMs = cfg.scriptTimeoutMs ?? 600_000;
-  if (cfg.maxScriptTimeoutMs !== undefined && !(cfg.maxScriptTimeoutMs >= defaultMs)) {
-    throw new Error(
-      `codeExecution.maxScriptTimeoutMs (${cfg.maxScriptTimeoutMs}) must be at least scriptTimeoutMs (${defaultMs}): ` +
-        'it is the most an agent may ask for, and the default is always allowed',
-    );
-  }
-  // None of the environment's refusals below shows the value it refuses,
-  // at most its kind: a substituted value can be a credential. null counts
-  // as not set, so a generated config that writes an unset setting as null
-  // keeps working.
-  assertBooleanSetting(
-    'codeExecution.inheritEnv',
-    cfg.inheritEnv,
-    "true hands the interpreter the host's whole environment, and false or leaving it out keeps the allowlist",
+    settings.enabled,
+    "true gives agents the code_execution tool, which runs their scripts in a JavaScript engine of the host's, " +
+      "and false or leaving it out doesn't",
   );
-  if (cfg.env !== undefined && cfg.env !== null) {
-    if (!isPlainObject(cfg.env)) {
-      throw new Error(`codeExecution.env must be an object of variable names and string values, not ${kindOf(cfg.env)}`);
-    }
-    for (const [name, value] of Object.entries(cfg.env)) {
-      // spawn writes each variable as name=value: a name that is empty or
-      // holds '=' doesn't reach the interpreter as written, and a NUL in a
-      // name or a value makes spawn throw at every start.
-      // Only what comes before an '=' or NUL is shown: what follows can be a
-      // value pasted into the name.
-      if (name === '' || name.includes('=') || name.includes('\0')) {
-        const shown = name === '' ? 'that is empty' : `starting ${JSON.stringify(name.split(/[=\0]/, 1)[0])} that holds '=' or NUL`;
-        throw new Error(`codeExecution.env has a variable name ${shown}, and a name can't be empty or hold '=' or NUL`);
-      }
-      if (typeof value !== 'string') {
-        throw new Error(`codeExecution.env.${name} must be a string, not ${kindOf(value)}: give its value as a string, or leave ${name} out`);
-      }
-      if (value.includes('\0')) {
-        throw new Error(`codeExecution.env.${name} holds a NUL character, which no environment variable can carry`);
-      }
-    }
-  }
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== 'object' || value === null) return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
+  if (settings.enabled !== true) return;
+  isolateSettings(settings);
+  const problem = bunVersionProblem(bun);
+  if (problem) throw new Error(problem);
 }

package/src/deadline-timer.ts

@@ -1,6 +1,6 @@
 /** The longest delay one setTimeout holds (2^31 - 1 ms, about 24.8 days).
  *  Node fires a longer one almost at once, with a TimeoutOverflowWarning. */
-const MAX_TIMER_MS = 2_147_483_647;
+export const MAX_TIMER_MS = 2_147_483_647;
 
 type Hold = (timer: ReturnType<typeof setTimeout>) => void;