Code Mode Overview
@interopio/code-mode exposes a session-based tool registry and a QuickJS WebAssembly execution API. Each session produces three model-facing meta-tools: getTools, getToolDefinition, and executeCode.
Installation
npm install @interopio/code-mode
Use the browser entry point in web applications and the Node.js entry point in server applications:
import { IoCodeModeFactory } from "@interopio/code-mode/browser";
import { IoCodeModeFactory } from "@interopio/code-mode/node";
The package includes the QuickJS WebAssembly file at @interopio/code-mode/dist/emscripten-module.wasm. The browser entry point needs a browser-served URL for wasmLocation; the Node.js entry point needs a filesystem path.
The WASM asset must match the installed package version. See WASM delivery for self-hosted and CDN configuration.
Main API
The following declarations belong to the exported IoCodeMode namespace, except for IoCodeModeFactory:
declare function IoCodeModeFactory(config: IoCodeMode.Config): Promise<IoCodeMode.API>;
interface API {
getSystemInstruction(): string;
createSession(): Session;
getSession(id: string): Session | undefined;
removeSession(id: string): void;
}
interface Session {
id: string;
setTools(update: ToolsUpdate): void;
getLlmTools(): LlmTool[];
}
type ToolsUpdate = RuntimeTool[] | ((current: RuntimeTool[]) => RuntimeTool[]);
| Method | Contract |
|---|---|
getSystemInstruction() | Returns model instructions, transformed by overwriteSystemInstruction if configured. |
createSession() | Creates and stores a session with an independent tool registry and session cancellation signal. |
getSession(id) | Returns the stored session, or undefined if the ID is unknown. |
removeSession(id) | Removes the session and aborts its in-flight executions; other sessions are unaffected. |
setTools(update) | Replaces the registry, or invokes the updater with a copy of the current filtered registry. Tools with enabled: false and tools rejected by toolFilter are excluded. |
getLlmTools() | Returns meta-tools bound to a snapshot of the current registry. Call again after setTools() to obtain a new snapshot. |
Tool Types
interface ToolDefinition {
name: string;
description?: string;
inputSchema?: Record<string, unknown>;
outputSchema?: Record<string, unknown>;
source?: { mcpName?: string };
_meta?: Record<string, unknown>;
}
interface RuntimeTool extends ToolDefinition {
enabled?: boolean;
execute: (args: Record<string, unknown>, options?: ExecuteOptions) => Promise<ToolResult>;
}
interface LlmTool {
name: string;
description: string;
inputSchema: Record<string, unknown>;
outputSchema: Record<string, unknown>;
_meta: Record<string, unknown>;
execute: (args: Record<string, unknown>, options?: ExecuteOptions) => Promise<ToolResult>;
}
interface ExecuteOptions {
signal?: AbortSignal;
context?: unknown;
}
interface TextContent {
type: "text";
text: string;
}
interface ToolResult {
content: TextContent[];
structuredContent?: Record<string, unknown>;
isError?: boolean;
}
RuntimeTool describes host implementations registered with setTools(). LlmTool describes the meta-tools returned by getLlmTools(). Both return ToolResult; see tool results for conversion to sandbox values.
Meta-Tools
| Name | Input | Successful structuredContent |
|---|---|---|
getTools | {} | { tools: [{ name, description }] } with sandbox binding names. |
getToolDefinition | { names: string[] } | { tools: [{ name, description, inputSchema, outputSchema }] }. Accepts binding names or original tool names. |
executeCode | { code: string, explanation: string } | { codeExecutionResult: string, codeExecutionLogs: string }. |
The executeCode JSON schema requires explanation; the TypeScript ExecuteParams type makes it optional. Supply it for model-facing calls. Guest code is plain JavaScript, not TypeScript. Each host tool is exposed as an async tool_* function taking one object argument; use the exact binding reported by getTools.
All meta-tools carry _meta: { "io.interop/code-mode": true }. The package exports CodeModeToolMetaKey with that key value.
Execution Results
executeCode.execute() resolves to a ToolResult for execution failure, timeout, or cancellation; inspect isError rather than relying on catch.
- Successful execution returns
isError: false, the result/log object instructuredContent, and its JSON encoding in a text content block. String return values remain strings; objects are JSON-encoded;undefinedbecomes"". Captured log entries are joined with newlines. - Guest failures and sandbox timeouts return
isError: true. Driver-reported failures populatecodeExecutionResultwith the error name and message, such asTimeoutError: .... Setup failures or rejected driver execution may instead return only a text error block. - Caller cancellation or session removal returns
{ isError: true, content: [{ type: "text", text: "Execution aborted." }] }, withoutstructuredContent.
Failures from individual tool_*() calls throw inside guest code and can be handled with guest try/catch. An uncaught guest error becomes an execution error result.
Related Documentation
- Configuration for sandbox, filtering, and interception options
- Examples for supported host integrations
- Upgrading for WASM asset, dependency compatibility, and CDN update requirements
- Code Mode Overview for choosing client-side or server-side ownership