experimental-ai-sdk-code-mode weekly downloads statistics

AI SDK Code Mode

experimental-ai-sdk-code-mode provides an AI SDK tool that runs JavaScript or type-stripped TypeScript in an isolated QuickJS WASM sandbox. It is meant for agents that need to call several tools, combine their results, run independent tool calls concurrently, or do structured JSON transformations in one step.

Installation

The runtime uses Node.js worker threads and is intended for server-side AI SDK tools, not browser execution.

ai is a peer dependency. The package supports AI SDK 6 stable and AI SDK 7 beta:

Quick Start

What The Model Sees

createCodeModeTool(tools) generates the code-mode tool description from the provided AI SDK tools. The description includes:

• sandbox rules • whether fetch is available, plus the configured fetch policy when present • TypeScript call signatures for every provided tool, including return types when the tool provides an AI SDK outputSchema • examples for calling tools and returning the final value

For example, if you pass search and readDocument, the model sees guidance like this in the code-mode tool description:

Inside code mode, calls look like normal async JavaScript:

JSON.parse and JSON.stringify are available in the sandbox. Returned values and tool inputs/outputs must be JSON-serializable.

API

Returns an AI SDK tool() whose input schema is:

The js string is wrapped in an async function, so top-level await and return are supported:

The package also exports the lower-level runner:

Options

Defaults:

| Option | Default |

| executionPolicy.timeoutMs | 30_000 | | executionPolicy.memoryLimitBytes | 64 * 1024 * 1024 | | executionPolicy.maxStackSizeBytes | 2 * 1024 * 1024 | | executionPolicy.maxResultBytes | 1024 * 1024 | | executionPolicy.maxSourceBytes | 256 * 1024 | | executionPolicy.maxToolInputBytes | 1024 * 1024 | | executionPolicy.maxToolOutputBytes | 4 * 1024 * 1024 | | executionPolicy.maxBridgeRequests | 256 | | executionPolicy.maxInFlightBridgeRequests | 32 | | fetchPolicy | disabled | | fetchPolicy.maxResponseBytes | 1024 * 1024 | | fetchPolicy.allowRedirects | false | | fetchPolicy.maxRedirects | 10 | | approval.mode | "callback" |

Worker-pool size is process-global. By default, code mode uses a dynamic memory-based limit capped at 32 workers. The default admits at least one active invocation, then only admits another worker when available memory can cover the configured QuickJS memory limit plus runtime overhead. Override it explicitly with:

Bundled Worker Assets

Normal Node.js usage does not require worker asset configuration. By default, the package starts an inline Node.js worker from a generated data URL with the QuickJS runtime bundle and asyncify WASM bytes embedded in that worker source, so serverless packagers do not need to preserve sibling worker or WASM files next to the bundled package entry.

If an environment disallows data: URL workers, or if you want to ship an explicit custom worker asset, configure the runtime before starting code-mode invocations:

Custom workers must be self-contained. The package does not publish worker or WASM asset subpaths.

Concurrency

Code mode uses a bounded worker pool. Each active invocation checks out one worker and creates a fresh QuickJS module, runtime, and context for that run. When the run completes normally, the worker returns to the idle pool. When a run times out, aborts, or the worker fails, that worker is retired and replaced on a future invocation.

The worker boundary is intentional. QuickJS can suspend while host tools execute, so each active invocation still needs an independent asyncified QuickJS/WASM instance. Workers also give the host a hard termination boundary for runaway code; instantiating multiple WASM modules in the main thread would preserve asyncify independence, but it would not provide the same event-loop isolation or reliable timeout kill path.

Tool calls inside one sandbox can also run concurrently:

Use setMaxWorkers to cap the number of active pooled workers. When the limit is reached, new invocations fail with CodeModeConcurrencyError. The slot stays occupied until the sandbox result and any accepted host bridge work have settled or observed abort, so detached host work cannot silently outlive accounting.

Every tool or fetch promise created inside code mode must be awaited or otherwise handled before returning. An unawaited bridge call fails with CodeModeDetachedBridgeRequestError; an observed bridge call that is still pending when the script returns is aborted and also fails the invocation. maxBridgeRequests limits total bridge calls per invocation, and maxInFlightBridgeRequests limits concurrent tool/fetch calls inside one sandbox.

Tool Semantics

Nested tool calls preserve the important AI SDK behavior:

• tool inputs are validated against each tool's inputSchema • execute receives forwarded ToolExecutionOptions, including abort signals • nested calls get derived toolCallId values for tracing • thrown tool errors are propagated • async iterable tool outputs are consumed and the final output is returned • tools without execute are rejected • unknown tools fail clearly

Only top-level tool names are intended for the public API:

Observability

Code mode exposes nested bridge activity without parsing generated code or final tool results. Lifecycle hooks fire for nested tool calls, nested tool results, fetch requests, fetch results, interrupts, and the final per-invocation trace:

Lifecycle hook errors are isolated from sandbox execution. Provide lifecycle.onHookError if hook failures should be recorded.

For OpenTelemetry, pass an OTEL-compatible tracer:

This emits spans for the outer code-mode invocation and each nested tool/fetch bridge request. Raw source, inputs, and outputs are not recorded; telemetry attributes include names, ids, status, replay flags, and byte sizes. Set recordInputs: false or recordOutputs: false to omit size attributes for those directions.…

Description from the npm listing.