Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

isolate-driver.ts

261 lines8.7 KB

1import { getQuickJS } from 'quickjs-emscripten'
2import { QuickJSIsolateContext } from './isolate-context'
3import type { ExecState } from './isolate-context'
4import type { QuickJSContext } from 'quickjs-emscripten'
5import type {
6 IsolateConfig,
7 IsolateContext,
8 IsolateDriver,
9 ToolBinding,
10} from '@tanstack/ai-code-mode'
11​
12/** Default memory limit in MB (matches Node isolate driver default). */
13const DEFAULT_MEMORY_LIMIT_MB = 128
14​
15/** Default max stack size in bytes for QuickJS runtime. */
16const DEFAULT_MAX_STACK_SIZE_BYTES = 512 * 1024
17​
18/**
19 * Configuration for the QuickJS WASM isolate driver
20 */
21export interface QuickJSIsolateDriverConfig {
22 /**
23 * Default execution timeout in ms (default: 30000)
24 */
25 timeout?: number
26​
27 /**
28 * Default memory limit in MB (default: 128).
29 * Applied via QuickJS `runtime.setMemoryLimit`.
30 */
31 memoryLimit?: number
32​
33 /**
34 * Default max stack size in bytes (default: 512 KiB).
35 * Applied via QuickJS `runtime.setMaxStackSize`.
36 */
37 maxStackSize?: number
39​
40/**
41 * Run a tool binding against JSON-encoded args. Never rejects: errors are
42 * encoded into the JSON envelope so the guest-side wrapper can rethrow them.
43 */
44async function invokeBinding(
45 binding: ToolBinding,
46 argsJson: string,
47): Promise<string> {
48 try {
49 const args = JSON.parse(argsJson)
50 const result = await binding.execute(args)
51 return JSON.stringify({ success: true, value: result })
52 } catch (error) {
53 const errorMessage = error instanceof Error ? error.message : String(error)
54 return JSON.stringify({ success: false, error: errorMessage })
55 }
57​
58/**
59 * Inject a tool binding as a host function that returns a QuickJS promise
60 * resolved from the host side.
61 *
62 * Deliberately avoids `newAsyncifiedFunction`: repeated asyncify suspensions
63 * corrupt QuickJS refcounts and abort the WASM module
64 * (https://github.com/justjake/quickjs-emscripten/issues/258). The promise
65 * bridge never suspends the WASM stack, so that bug cannot trigger.
66 */
67function injectBinding(
68 vm: QuickJSContext,
69 name: string,
70 binding: ToolBinding,
71 logs: Array<string>,
72 execState: ExecState,
73): void {
74 const toolFn = vm.newFunction(name, (argsHandle) => {
75 const argsJson = vm.getString(argsHandle)
76 const promise = vm.newPromise()
77​
78 // A timed-out execution cancels every outstanding tool call by settling
79 // its deferred with a timeout envelope, so the guest program itself can
80 // settle and the VM can be disposed (freeing a runtime that still holds
81 // an unsettled program promise aborts the shared WASM module).
82 const resolveWithPayload = (payloadJson: string) => {
83 execState.pendingCancels.delete(cancel)
84 if (!vm.alive || !promise.alive) return
85 const payloadHandle = vm.newString(payloadJson)
86 promise.resolve(payloadHandle)
87 payloadHandle.dispose()
88 }
89 const cancel = () =>
90 resolveWithPayload(
91 JSON.stringify({ success: false, error: 'Execution timed out' }),
92 )
93 execState.pendingCancels.add(cancel)
94​
95 void invokeBinding(binding, argsJson).then(resolveWithPayload)
96​
97 // Resume guest code waiting on the promise. Defense in depth: outside an
98 // active execute() the interrupt deadline is 0, so a stray job from an
99 // abandoned execution is interrupted instead of running unbounded.
100 void promise.settled.then(() => {
101 try {
102 if (vm.runtime.alive) {
103 const jobs = vm.runtime.executePendingJobs()
104 if (jobs.error) {
105 // Errors thrown inside guest async code reject the observed program
106 // promise instead of surfacing here; anything that does land here
107 // would otherwise be silently swallowed and leak its handle.
108 logs.push(
109 `ERROR: uncaught error in sandboxed code: ${JSON.stringify(vm.dump(jobs.error))}`,
110 )
111 jobs.error.dispose()
112 }
113 }
114 } finally {
115 promise.dispose()
116 }
117 })
118​
119 return promise.handle
120 })
121​
122 // Set on global - the VM keeps its own reference
123 vm.setProp(vm.global, `__${name}_impl`, toolFn)
124 toolFn.dispose()
125​
126 // Create wrapper that parses input and output
127 // Function names match the binding keys (e.g., external_fetchWeather)
128 const wrapperCode = `
129 async function ${name}(input) {
130 const resultJson = await __${name}_impl(JSON.stringify(input));
131 const result = JSON.parse(resultJson);
132 if (!result.success) {
133 throw new Error(result.error);
134 }
135 return result.value;
136 }
137 `
138 const wrapperResult = vm.evalCode(wrapperCode)
139 if (wrapperResult.error) {
140 const errorStr = vm.dump(wrapperResult.error)
141 wrapperResult.error.dispose()
142 throw new Error(`Failed to create wrapper for ${name}: ${errorStr}`)
143 }
144 wrapperResult.value.dispose()
146​
147/**
148 * Create a QuickJS WASM isolate driver
149 *
150 * This driver uses QuickJS compiled to WebAssembly via Emscripten.
151 * It provides a sandboxed JavaScript environment that runs anywhere
152 * (Node.js, browser, edge) without native dependencies.
153 *
154 * Tools are injected as async functions that bridge back to the host.
155 *
156 * @example
157 * ```typescript
158 * import { createQuickJSIsolateDriver } from '@tanstack/ai-isolate-quickjs'
159 *
160 * const driver = createQuickJSIsolateDriver({
161 * timeout: 30000,
162 * })
163 *
164 * const context = await driver.createContext({
165 * bindings: {
166 * readFile: {
167 * name: 'readFile',
168 * description: 'Read a file',
169 * inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
170 * execute: async ({ path }) => fs.readFile(path, 'utf-8'),
171 * },
172 * },
173 * })
174 *
175 * const result = await context.execute(`
176 * const content = await readFile({ path: './data.json' })
177 * return JSON.parse(content)
178 * `)
179 * ```
180 */
181export function createQuickJSIsolateDriver(
182 config: QuickJSIsolateDriverConfig = {},
183): IsolateDriver {
184 const defaultTimeout = config.timeout ?? 30000
185 const defaultMemoryLimit = config.memoryLimit ?? DEFAULT_MEMORY_LIMIT_MB
186 const defaultMaxStackSize =
187 config.maxStackSize ?? DEFAULT_MAX_STACK_SIZE_BYTES
188​
189 return {
190 async createContext(isolateConfig: IsolateConfig): Promise<IsolateContext> {
191 const timeout = isolateConfig.timeout ?? defaultTimeout
192 const memoryLimitMb = isolateConfig.memoryLimit ?? defaultMemoryLimit
193 const maxStackSizeBytes = defaultMaxStackSize
194​
195 // Create a plain (non-asyncify) QuickJS context. Host async functions
196 // are bridged with QuickJS promises instead of asyncify suspensions,
197 // so the sync WASM build is sufficient and sidesteps asyncify bugs.
198 const QuickJS = await getQuickJS()
199 const vm = QuickJS.newContext()
200​
201 // Enforce heap and stack limits so OOM/stack overflow surface as JS errors
202 // instead of growing WASM memory until the host process OOMs.
203 vm.runtime.setMemoryLimit(memoryLimitMb * 1024 * 1024)
204 vm.runtime.setMaxStackSize(maxStackSizeBytes)
205​
206 // Set up console.log capture
207 const logs: Array<string> = []
208​
209 // Create console object
210 const consoleObj = vm.newObject()
211​
212 // Helper to create console methods
213 const createConsoleMethod = (prefix: string) => {
214 return vm.newFunction(`console.${prefix}`, (...args) => {
215 const parts = args.map((arg) => {
216 const str = vm.getString(arg)
217 return str
218 })
219 const msg = prefix ? `${prefix}: ${parts.join(' ')}` : parts.join(' ')
220 logs.push(msg)
221 })
222 }
223​
224 const logFn = createConsoleMethod('')
225 const errorFn = createConsoleMethod('ERROR')
226 const warnFn = createConsoleMethod('WARN')
227 const infoFn = createConsoleMethod('INFO')
228​
229 vm.setProp(consoleObj, 'log', logFn)
230 vm.setProp(consoleObj, 'error', errorFn)
231 vm.setProp(consoleObj, 'warn', warnFn)
232 vm.setProp(consoleObj, 'info', infoFn)
233 vm.setProp(vm.global, 'console', consoleObj)
234​
235 // Dispose console handles
236 logFn.dispose()
237 errorFn.dispose()
238 warnFn.dispose()
239 infoFn.dispose()
240 consoleObj.dispose()
241​
242 // Shared between execute() and the tool bindings: the interrupt
243 // deadline (0 means "no execution active" — any guest job that tries
244 // to run outside execute() is interrupted immediately) and the cancel
245 // callbacks for tool calls still awaiting their host promise.
246 const execState: ExecState = {
247 deadline: 0,
248 pendingCancels: new Set<() => void>(),
249 }
250​
251 // Inject each tool binding as an async function
252 for (const [name, binding] of Object.entries(isolateConfig.bindings)) {
253 injectBinding(vm, name, binding, logs, execState)
254 }
255​
256 vm.runtime.setInterruptHandler(() => Date.now() > execState.deadline)
257​
258 return new QuickJSIsolateContext(vm, logs, timeout, execState)
259 },
260 }