Code mode SDK and limits

requires: codemode

A code mode script runs in the MCP gateway's sandbox each time an agent calls execute. This page lists what the script can reach, what each call returns and which limits apply. The code mode page explains when and how to use it.

The execute tool

Unknown arguments are rejected. execute is the only tool a code-mode gateway lists, and calling any other name returns JSON-RPC error -32002 (Tool '<name>' not found).

How a script runs

• Async body. The code is the body of an async function, so await works at the top level and return ends the run. The returned value is serialized as JSON, and undefined becomes null.
• Strip-only TypeScript. Type annotations, interfaces and type aliases are removed without moving any line or column. enum, namespace declarations and decorators are rejected with a ParseError.
• Engine. The engine is QuickJS. Standard ECMAScript built-ins such as JSON, Promise, Map and Math are available. There is no fetch, no setTimeout, no module loading, no filesystem, no network and no environment.
• Fresh state. Each run starts from a fresh copy of the engine, and nothing carries over between runs.
• Shutdown. When the script returns, calls still in flight are cancelled. A script whose promise never settles while no calls are pending ends with an ExecutionFailure.

Globals

tools

The name is split at its first ., so a local tool name may contain dots but a namespace may not. tools cannot be enumerated or changed: Object.keys(tools) and assignments throw. To see what exists, use catalog.

catalog

Every catalog operation takes one object argument and resolves to a call envelope. Only tools the caller is authorized to use are counted, listed, searched or described.

• Search uses the gateway's tool search ranking (BM25, or remote embeddings when configured) over every permitted tool, whatever its disclosure mode. limit defaults to search.max_allowable_results (5 unless configured) and is clamped to it.
• Pages have the shape { items, total, limit, offset, hasMore, nextOffset }. limit defaults to 20 and is capped at 100. nextOffset is present only when hasMore is true.
• Toolkit visibility. A toolkit is listed and returned only when every tool in it exists and the caller may use all of them.

console

console.log, console.info, console.warn, console.error and console.debug each append one line to the result's logs. Arguments are joined with spaces, and anything other than a string is JSON-encoded. Each call counts toward max_host_calls. At most 128 lines are kept, and a line longer than 4096 bytes is truncated.

Call envelopes

Tool and catalog calls resolve to one of two shapes and never throw for a failed call:

{ "ok": true, "data": { "id": "c-1042" }, "meta": { "omitted": 0 } }
{ "ok": false, "error": { "code": "access_denied", "message": "Access to the requested tool was denied", "retryable": false } }

For tool calls, data is the tool's structured result when it has one: a REST tool with an output_schema, or an upstream MCP result with structuredContent. Otherwise data is the result's text content as a string (blocks joined by newlines), or null. meta.omitted counts non-text content blocks, such as images, that the envelope dropped. Catalog envelopes carry data only.

Tool call error codes

Catalog error codes

The execute result

A run always returns a normal tools/call result whose structuredContent looks like this:

{
  "status": "completed",
  "result": { "ticket": "T-8821" },
  "error": null,
  "diagnostics": [],
  "logs": ["recent tickets: 3"],
  "toolCalls": [
    { "tool": "crm.find_customer", "ok": true, "durationMs": 38 },
    { "tool": "support.recent_tickets", "ok": true, "durationMs": 52 },
    { "tool": "billing.current_plan", "ok": true, "durationMs": 47 },
    { "tool": "support.create_ticket", "ok": true, "durationMs": 61 }
  ]
}

If the whole object is larger than max_output_bytes, the gateway keeps result and drops entries from the end of toolCalls, then from logs, until it fits. The result's _meta then carries "arion/codemodeTruncation": { "logsOmitted": N, "toolCallsOmitted": N }. If result alone does not fit, the run reports a ResourceLimitExceeded error instead.

Diagnostics

Errors outside the result

These come back as JSON-RPC errors, not as an execute result:

Limits

Numeric code_mode fields left at 0 take their defaults.

The sandbox

• Engine. Scripts run in a WebAssembly component on Wasmtime: QuickJS compiled for WASI and initialized ahead of time with Wizer, so each run starts from a snapshot rather than booting an interpreter.
• Pool. Instances come from a pooling allocator sized by runtime.codemode.pool_capacity. The thread that enforces the compute budget runs only while a script is executing, so an idle gateway does no background work.
• Isolation. The sandbox has no preopened directories, no environment variables and no sockets. Its only link to the host is an interface with three calls: request (a log line), submit (start a tool or catalog call) and next-completion (wait for one to finish). Every tool call lands on the same registry checks as a normal tools/call.
• Custom engine. code_mode.engine_artifact_path replaces the bundled component with your own build. When the listener loads, Arion checks the component's imports against the allowed set and rejects anything else.