CodeInterpreter Module

The CodeInterpreter interface lets your agent execute source code (Python, JavaScript, etc.) in a provider-chosen runtime. Two modes: stateless one-shot execution, or persistent Jupyter-style contexts.

Interface

type CodeContextId = string & { readonly __brand: 'CodeContextId' };

type CodeOutput =
  | { readonly type: 'stdout'; readonly data: Uint8Array }
  | { readonly type: 'stderr'; readonly data: Uint8Array }
  | { readonly type: 'display'; readonly mime: string; readonly data: Uint8Array }
  | { readonly type: 'result'; readonly value: unknown };

interface RunCodeOptions {
  readonly signal?: AbortSignal;
  readonly timeoutMs?: number;
  readonly onOutput?: (chunk: CodeOutput) => Promise<void>;
}

interface RunCodeResult {
  readonly outputs: readonly CodeOutput[];
  readonly exitCode: number;
  readonly error?: string;
}

interface CodeInterpreter {
  readonly languages: readonly string[];
  readonly isStateful: boolean;
  runCode(language: string, code: string, opts?: RunCodeOptions): Promise<RunCodeResult>;
  createContext?(language: string): Promise<CodeContextId>;
  runInContext?(ctxId: CodeContextId, code: string, opts?: RunCodeOptions): Promise<RunCodeResult>;
  deleteContext?(ctxId: CodeContextId): Promise<void>;
}

Stateless vs stateful

The isStateful flag controls whether the optional context methods (createContext, runInContext, deleteContext) are present:

• isStateful: false (default): each runCode(lang, code) call is independent. No context methods. Auto-injected tools omit the context-management trio.
• isStateful: true: persistent Jupyter-style contexts. createContext('python') returns an opaque CodeContextId; subsequent runInContext(ctxId, code) calls share variable state with prior calls in that context. deleteContext releases the kernel.

Important provider implementation note: when isStateful: false, the createContext / runInContext / deleteContext properties on the returned CodeInterpreter MUST be undefined (not present-but-throwing). Pattern 3e's tool-injection uses property presence to decide which tools to inject. The createCloudflareSandboxCodeInterpreter factory in runtime-cloudflare uses a factory-function pattern (returning different object shapes) to guarantee this.

CodeOutput discriminated union

Code execution produces structured output beyond raw stdout/stderr:

• stdout / stderr — raw text streams as bytes (typically UTF-8).
• display — rich content with a MIME type. Common values: image/png, image/svg+xml, text/html. Used by Python's matplotlib for inline plots, Jupyter's rich display protocol, etc.
• result — the value of the last expression (Python REPL convention). Type is unknown.

The auto-injected run_code tool serializes display.data as base64 and result.value as JSON for the LLM to consume.

Streaming via onOutput

When onOutput is provided, providers stream each output chunk as it's produced (analogous to onStdout / onStderr for the shell module). The auto-injected tool always passes a callback that emits workspace_code_output events to the agent's event stream — your downstream consumers see live progress for long-running code.

Auto-injected tools

For a workspace named <name> with code: { languages, isStateful }:

Tool	Schema	Returns	When
workspace__<name>__run_code	{ language: string; code: string; timeoutMs? }	RunCodeResult	Always (when code is declared)
workspace__<name>__create_code_context	{ language: string }	{ contextId: CodeContextId }	Only when isStateful: true
workspace__<name>__run_in_code_context	{ contextId: CodeContextId; code: string; timeoutMs? }	RunCodeResult	Only when isStateful: true
workspace__<name>__delete_code_context	{ contextId: CodeContextId }	{ ok: true }	Only when isStateful: true

Capability config

interface CodeInterpreterCapConfig {
  readonly languages: readonly string[];  // required
  readonly isStateful?: boolean;
}

languages is REQUIRED — it tells both the framework (which tool descriptions to populate) and the provider (which runtimes to support). Common values: 'python', 'javascript', 'typescript'. Provider-specific support varies (the Cloudflare Sandbox image determines what's actually installed in the container).

The auto-injected run_code tool validates the language argument at the framework layer — calling with a language outside the declared set throws before reaching the provider.

isStateful defaults to false. Set to true to enable persistent contexts (and the corresponding tool injections).

Provider support matrix

Provider	code supported
In-Memory	❌
Local Bash	❌ (use shell to invoke python -c '...' directly)
Cloudflare Filestore	❌
Cloudflare Sandbox	✅ (Python + JavaScript via container; persistent contexts opt-in)

Source

• Interface: packages/core/src/workspace/types/modules/code.ts
• Tool injection: packages/core/src/workspace/tool-injection.ts (search for makeCodeTools)