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

isolate-context.ts

327 lines10.4 KB

1import { wrapCode } from '@tanstack/ai-code-mode'
2import {
3 TIMEOUT_ERROR,
4 isFatalQuickJSLimitError,
5 normalizeError,
6} from './error-normalizer'
7import type {
8 QuickJSContext,
9 QuickJSHandle,
10 VmCallResult,
11} from 'quickjs-emscripten'
12import type { ExecutionResult, IsolateContext } from '@tanstack/ai-code-mode'
13​
14/**
15 * Execution state shared with the tool bindings created in the driver.
16 * `deadline === 0` means no execution is active, so any guest job that runs
17 * outside execute() is interrupted immediately. `pendingCancels` holds one
18 * cancel callback per tool call still awaiting its host promise; a timed-out
19 * execution invokes them to settle the guest program so the VM can be
20 * disposed safely.
21 */
22export interface ExecState {
23 deadline: number
24 pendingCancels: Set<() => void>
26​
27/** Grace window for cancellation continuations after a timeout. */
28const CANCEL_GRACE_MS = 100
29​
30/**
31 * Await the guest program's promise, but give up at `deadline`. Host tool
32 * calls are bridged as QuickJS promises, so a guest program that is stuck
33 * waiting (e.g. its continuation was interrupted) would otherwise never
34 * settle. A timeout is terminal for the context (see `fail()` in execute):
35 * the timed-out program's interrupted jobs stay queued in the VM and must
36 * never run inside a later execution. If the guest settles after the
37 * deadline, its result handle is disposed to avoid leaking it into the
38 * context's lifetime.
39 */
40function awaitWithDeadline(
41 promise: Promise<VmCallResult<QuickJSHandle>>,
42 deadline: number,
43): Promise<VmCallResult<QuickJSHandle>> {
44 return new Promise((resolve, reject) => {
45 let timedOut = false
46 const timer = setTimeout(
47 () => {
48 timedOut = true
49 const timeoutError = new Error('Code execution timed out')
50 timeoutError.name = TIMEOUT_ERROR
51 reject(timeoutError)
52 },
53 Math.max(0, deadline - Date.now()),
54 )
55​
56 promise.then(
57 (result) => {
58 if (timedOut) {
59 try {
60 if ('error' in result && result.error) {
61 result.error.dispose()
62 } else {
63 result.value.dispose()
64 }
65 } catch {
66 // context may already be disposed
67 }
68 return
69 }
70 clearTimeout(timer)
71 resolve(result)
72 },
73 (error) => {
74 if (timedOut) return
75 clearTimeout(timer)
76 reject(error)
77 },
78 )
79 })
81​
82/**
83 * IsolateContext implementation using QuickJS WASM
84 */
85export class QuickJSIsolateContext implements IsolateContext {
86 private readonly vm: QuickJSContext
87 private readonly logs: Array<string>
88 private readonly timeout: number
89 private readonly execState: ExecState
90 /** Serializes execute() calls so evaluations on this VM never interleave. */
91 private execQueue: Promise<void> = Promise.resolve()
92 private disposed = false
93 private executing = false
94​
95 constructor(
96 vm: QuickJSContext,
97 logs: Array<string>,
98 timeout: number,
99 execState: ExecState,
100 ) {
101 this.vm = vm
102 this.logs = logs
103 this.timeout = timeout
104 this.execState = execState
105 }
106​
107 async execute<T = unknown>(code: string): Promise<ExecutionResult<T>> {
108 if (this.disposed) {
109 return {
110 success: false,
111 error: {
112 name: 'DisposedError',
113 message: 'Context has been disposed',
114 },
115 logs: [],
116 }
117 }
118​
119 // Serialize through the queue so concurrent execute() calls on this
120 // context never interleave their pending jobs.
121 let resolve!: () => void
122 const myTurn = new Promise<void>((r) => {
123 resolve = r
124 })
125 const waitForPrev = this.execQueue
126 this.execQueue = myTurn
127​
128 await waitForPrev
129​
130 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose() may be called concurrently while awaiting the queue
131 if (this.disposed) {
132 resolve()
133 return {
134 success: false,
135 error: {
136 name: 'DisposedError',
137 message: 'Context has been disposed',
138 },
139 logs: [],
140 }
141 }
142​
143 this.executing = true
144 this.logs.length = 0
145​
146 // Starts true.
147 // Becomes false once the guest program promise is being awaited, and returns to true when it settles.
148 // Stays false if the program promise never settles (e.g. interrupt during a spin).
149 // Only pre-arm failures leave it true so timeout release can dispose.
150 let guestSettled = true
151​
152 const releaseVmAfterFatalError = async () => {
153 if (this.disposed) return
154 try {
155 this.vm.runtime.setInterruptHandler(() => false)
156 } catch {
157 // ignore if runtime is already torn down
158 }
159 this.disposed = true
160​
161 // Fatal limits can occur while host tools still own unsettled QuickJS
162 // deferreds. Settle them before freeing the runtime so their native
163 // handles cannot abort the shared WASM module during JS_FreeRuntime.
164 for (const cancel of [...this.execState.pendingCancels]) {
165 cancel()
166 }
167 this.execState.pendingCancels.clear()
168 await new Promise((r) => setTimeout(r, 0))
169​
170 this.vm.dispose()
171 }
172​
173 // A timed-out program or failed initial pending-job pump can leave jobs
174 // queued in the VM, where they would run inside the next execution's
175 // deadline. Both are terminal for the context. Cancel every outstanding
176 // tool call, then dispose once the guest has settled; if it cannot settle,
177 // leak the VM instead of aborting the shared WASM module.
178 const releaseAfterUnsettledExecution = async () => {
179 if (this.disposed) return
180 this.disposed = true
181 this.execState.deadline = Date.now() + CANCEL_GRACE_MS
182 for (const cancel of [...this.execState.pendingCancels]) {
183 cancel()
184 }
185 this.execState.pendingCancels.clear()
186 // Cancellation continuations run as microtasks; one macrotask tick
187 // lets the guest program settle and its result handles be reclaimed.
188 await new Promise((r) => setTimeout(r, 0))
189 this.execState.deadline = 0
190 if (guestSettled) {
191 this.vm.dispose()
192 }
193 }
194​
195 const fail = async (
196 error: unknown,
197 cleanup: 'reusable' | 'terminal' = 'reusable',
198 ) => {
199 const normalized = normalizeError(error)
200 if (normalized.name === TIMEOUT_ERROR) {
201 await releaseAfterUnsettledExecution()
202 } else if (isFatalQuickJSLimitError(normalized)) {
203 // Memory/stack limits leave the heap in an unknown state.
204 await releaseVmAfterFatalError()
205 } else if (cleanup === 'terminal') {
206 await releaseAfterUnsettledExecution()
207 }
208 return {
209 success: false as const,
210 error: normalized,
211 logs: [...this.logs],
212 }
213 }
214​
215 try {
216 const wrappedCode = wrapCode(code)
217​
218 const deadline = Date.now() + this.timeout
219 this.execState.deadline = deadline
220​
221 try {
222 const result = this.vm.evalCode(wrappedCode)
223​
224 let parsedResult: T
225 try {
226 const promiseHandle = this.vm.unwrapResult(result)
227​
228 // evalCode returns a Promise handle (our wrapper is an async IIFE).
229 // Await it via resolvePromise; guest continuations run when the
230 // tool bindings' promise-settled pumps call executePendingJobs.
231 const nativePromise = this.vm.resolvePromise(promiseHandle)
232 promiseHandle.dispose()
233 guestSettled = false
234 void nativePromise.then(
235 () => {
236 guestSettled = true
237 },
238 () => {
239 guestSettled = true
240 },
241 )
242 const jobs = this.vm.runtime.executePendingJobs()
243 if (jobs.error) {
244 const dumped: unknown = this.vm.dump(jobs.error)
245 jobs.error.dispose()
246 return await fail(dumped, 'terminal')
247 }
248 const resolvedResult = await awaitWithDeadline(
249 nativePromise,
250 deadline,
251 )
252​
253 const valueHandle = this.vm.unwrapResult(resolvedResult)
254 const dumpedResult = this.vm.dump(valueHandle)
255 valueHandle.dispose()
256​
257 if (typeof dumpedResult === 'string') {
258 try {
259 parsedResult = JSON.parse(dumpedResult) as T
260 } catch {
261 parsedResult = dumpedResult as T
262 }
263 } else {
264 parsedResult = dumpedResult as T
265 }
266​
267 return {
268 success: true,
269 value: parsedResult,
270 logs: [...this.logs],
271 }
272 } catch (unwrapError) {
273 return await fail(unwrapError)
274 }
275 } finally {
276 // fail() may set disposed when releasing the VM after memory/stack
277 // limit errors or timeouts
278 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- disposed set in fail()
279 if (!this.disposed) {
280 this.execState.deadline = 0
281 }
282 }
283 } catch (error) {
284 return await fail(error)
285 } finally {
286 this.executing = false
287 resolve()
288 }
289 }
290​
291 async dispose(): Promise<void> {
292 if (this.disposed) return
293​
294 // If an execution is in flight, wait for the queue to drain before
295 // disposing the VM. Otherwise a pending tool-binding callback would
296 // try to access a freed context.
297 if (this.executing) {
298 await this.execQueue
299 // The execution may have disposed the VM, or intentionally retained an
300 // unsettled VM, while dispose() was waiting for the queue.
301 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- execution cleanup may set disposed while awaiting
302 if (this.disposed) return
303 }
304​
305 this.disposed = true
306​
307 // A completed execution can leave tool calls still awaiting their host
308 // promise (e.g. a Promise.race loser abandoned by the guest program).
309 // Each holds an unsettled QuickJS deferred, and freeing a runtime with
310 // live deferred handles aborts the shared WASM module
311 // (`Assertion failed: list_empty(&rt->gc_obj_list)` in JS_FreeRuntime),
312 // poisoning every later context in this process. Settle them exactly like
313 // the timeout path does, then give the settled pumps one macrotask tick
314 // to dispose their deferreds before the VM goes away.
315 if (this.execState.pendingCancels.size > 0) {
316 this.execState.deadline = Date.now() + CANCEL_GRACE_MS
317 for (const cancel of [...this.execState.pendingCancels]) {
318 cancel()
319 }
320 this.execState.pendingCancels.clear()
321 await new Promise((r) => setTimeout(r, 0))
322 this.execState.deadline = 0
323 }
324​
325 this.vm.dispose()
326 }