Skip to main content

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[]);
MethodContract
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​

NameInputSuccessful 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 in structuredContent, and its JSON encoding in a text content block. String return values remain strings; objects are JSON-encoded; undefined becomes "". Captured log entries are joined with newlines.
  • Guest failures and sandbox timeouts return isError: true. Driver-reported failures populate codeExecutionResult with the error name and message, such as TimeoutError: .... 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." }] }, without structuredContent.

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.

  • 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