fix(isolate-quickjs): enforce timeout while suspended in host calls

.changeset/quickjs-timeout-host-calls.md

@@ -0,0 +1,22 @@
+---
+'@tanstack/ai-isolate-quickjs': patch
+---
+
+Enforce `timeout` as a wall-clock deadline that covers host-call suspensions.
+
+Previously the only deadline mechanism was QuickJS's `setInterruptHandler`, which
+fires only while the sandbox is stepping bytecode. While the isolate is
+asyncify-suspended awaiting a host binding's Promise, no interrupt fires, so the
+configured `timeout` was silently ignored: a run with `timeout: 100` and an
+800 ms host binding resolved successfully after ~800 ms, and a hung host binding
+could hang `execute()` indefinitely.
+
+`execute()` now races the run against a wall-clock timer, so `timeout` bounds the
+entire execution including time spent suspended in a host call. On the deadline
+it returns a normalized `TimeoutError` immediately. The suspended host Promise
+cannot be cancelled and the VM cannot be freed mid-asyncify, so disposal and the
+internal execution-queue turn are deferred until the orphaned run unwinds (the
+still-armed interrupt handler aborts it the moment the host Promise settles),
+which prevents a late host result from resuming a dead execution and avoids
+leaking the context. CPU-bound loops are still interrupted as before and leave
+the context reusable. The public API is unchanged.

packages/ai-isolate-quickjs/src/error-normalizer.ts

@@ -2,6 +2,7 @@ import type { NormalizedError } from '@tanstack/ai-code-mode'
 
 const MEMORY_LIMIT_ERROR = 'MemoryLimitError'
 const STACK_OVERFLOW_ERROR = 'StackOverflowError'
+const TIMEOUT_ERROR = 'TimeoutError'
 
 /**
  * Whether this normalized error indicates the QuickJS VM should not be reused
@@ -21,6 +22,17 @@ export function normalizeError(error: unknown): NormalizedError {
  const msg = error.message
  const lower = msg.toLowerCase()
 
+ // QuickJS raises `InternalError: interrupted` when the interrupt handler
+ // trips the execution deadline. Surface it as a timeout so a CPU-bound
+ // deadline and a wall-clock (host-call) deadline report the same error.
+ if (lower.includes('interrupted')) {
+ return {
+ name: TIMEOUT_ERROR,
+ message: 'Code execution exceeded timeout',
+ stack: error.stack,
+ }
+ }
+
  if (
  lower.includes('out of memory') ||
  lower.includes('memory alloc') ||

packages/ai-isolate-quickjs/src/isolate-context.ts

@@ -10,6 +10,21 @@ import type { ExecutionResult, IsolateContext } from '@tanstack/ai-code-mode'
  */
 let globalExecQueue: Promise<void> = Promise.resolve()
 
+/** Sentinel resolved by the wall-clock deadline race. */
+const TIMED_OUT = Symbol('quickjs-isolate-timeout')
+
+/**
+ * Grace window granted, after the wall-clock timer fires, for the in-VM
+ * interrupt handler to settle a CPU-bound run before it is treated as a host
+ * call still suspended in asyncify. A CPU-bound loop trips the interrupt at
+ * (almost) the same instant the timer fires; the grace keeps that path on the
+ * normal, reusable-context branch instead of orphaning the VM.
+ */
+const TIMEOUT_INTERRUPT_GRACE_MS = 10
+
+const delay = (ms: number): Promise<void> =>
+ new Promise((resolve) => setTimeout(resolve, ms))
+
 /**
  * IsolateContext implementation using QuickJS WASM
  */
@@ -19,6 +34,13 @@ export class QuickJSIsolateContext implements IsolateContext {
  private readonly timeout: number
  private disposed = false
  private executing = false
+ private timedOut = false
+ /**
+ * A run that timed out while a host call was suspended in asyncify. The VM
+ * cannot be disposed until this settles, so disposal and the global-queue
+ * turn are handed off to a continuation on it. `null` when no run is orphaned.
+ */
+ private orphanedRun: Promise<void> | null = null
 
  constructor(vm: QuickJSAsyncContext, logs: Array<string>, timeout: number) {
  this.vm = vm
@@ -28,21 +50,14 @@ export class QuickJSIsolateContext implements IsolateContext {
 
  async execute<T = unknown>(code: string): Promise<ExecutionResult<T>> {
  if (this.disposed) {
- return {
- success: false,
- error: {
- name: 'DisposedError',
- message: 'Context has been disposed',
- },
- logs: [],
- }
+ return this.disposedResult<T>()
  }
 
  // Serialize through the global queue to prevent concurrent
  // WASM asyncify suspensions across contexts.
- let resolve!: () => void
+ let releaseTurn!: () => void
  const myTurn = new Promise<void>((r) => {
-resolve = r
+releaseTurn = r
  })
  const waitForPrev = globalExecQueue
  globalExecQueue = myTurn
@@ -51,114 +66,206 @@ export class QuickJSIsolateContext implements IsolateContext {
 
  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose() may be called concurrently while awaiting the queue
  if (this.disposed) {
- resolve()
- return {
- success: false,
- error: {
- name: 'DisposedError',
- message: 'Context has been disposed',
- },
- logs: [],
- }
+ releaseTurn()
+ return this.disposedResult<T>()
  }
 
  this.executing = true
  this.logs.length = 0
 
- const releaseVmAfterFatalLimit = () => {
- if (this.disposed) return
- try {
- this.vm.runtime.setInterruptHandler(() => false)
- } catch {
- // ignore if runtime is already torn down
- }
- this.disposed = true
- this.vm.dispose()
- }
+ // Set when a wall-clock timeout leaves a host call suspended in asyncify:
+ // interrupt-handler reset, VM disposal, and the queue-turn release are then
+ // owned by the orphaned-run continuation rather than the finally block.
+ let deferredToOrphan = false
 
- const fail = (error: unknown) => {
+ const fail = (error: unknown): ExecutionResult<T> => {
  const normalized = normalizeError(error)
  if (isFatalQuickJSLimitError(normalized)) {
-releaseVmAfterFatalLimit()
+this.disposeVm()
  }
  return {
- success: false as const,
+ success: false,
  error: normalized,
  logs: [...this.logs],
  }
  }
 
- try {
- const wrappedCode = wrapCode(code)
-
- const deadline = Date.now() + this.timeout
- this.vm.runtime.setInterruptHandler(() => {
- return Date.now() > deadline
- })
+ // Drives the wrapped code to completion and marshals its result. On a
+ // deadline interrupt `evalCodeAsync` resolves with an error result, which
+ // `unwrapResult` throws and `fail` normalizes.
+ const runToSettled = async (): Promise<ExecutionResult<T>> => {
+ const result = await this.vm.evalCodeAsync(wrapCode(code))
 
  try {
- const result = await this.vm.evalCodeAsync(wrappedCode)
+ const promiseHandle = this.vm.unwrapResult(result)
+
+ // evalCodeAsync returns a Promise handle (our wrapper is an async IIFE).
+ // Use resolvePromise + executePendingJobs to properly await the
+ // QuickJS promise without re-entering the WASM asyncify state.
+ const nativePromise = this.vm.resolvePromise(promiseHandle)
+ promiseHandle.dispose()
+ this.vm.runtime.executePendingJobs()
+ const resolvedResult = await nativePromise
+
+ const valueHandle = this.vm.unwrapResult(resolvedResult)
+ const dumpedResult = this.vm.dump(valueHandle)
+ valueHandle.dispose()
 
  let parsedResult: T
- try {
- const promiseHandle = this.vm.unwrapResult(result)
-
- // evalCodeAsync returns a Promise handle (our wrapper is an async IIFE).
- // Use resolvePromise + executePendingJobs to properly await the
- // QuickJS promise without re-entering the WASM asyncify state.
- const nativePromise = this.vm.resolvePromise(promiseHandle)
- promiseHandle.dispose()
- this.vm.runtime.executePendingJobs()
- const resolvedResult = await nativePromise
-
- const valueHandle = this.vm.unwrapResult(resolvedResult)
- const dumpedResult = this.vm.dump(valueHandle)
- valueHandle.dispose()
-
- if (typeof dumpedResult === 'string') {
- try {
- parsedResult = JSON.parse(dumpedResult) as T
- } catch {
- parsedResult = dumpedResult as T
- }
- } else {
+ if (typeof dumpedResult === 'string') {
+ try {
+ parsedResult = JSON.parse(dumpedResult) as T
+ } catch {
  parsedResult = dumpedResult as T
  }
+ } else {
+ parsedResult = dumpedResult as T
+ }
 
- return {
- success: true,
- value: parsedResult,
- logs: [...this.logs],
- }
- } catch (unwrapError) {
- return fail(unwrapError)
+ // The wall-clock deadline may have fired while this run was suspended in
+ // a host call; the caller already received the timeout result, so a late
+ // success must not be surfaced as if the execution had finished in time.
+ if (this.timedOut) {
+ return this.timeoutResult<T>()
  }
- } finally {
-// fail() may set disposed when releasing the VM after memory/stack limit errors
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- disposed set in fail()
-if (!this.disposed) {
-this.vm.runtime.setInterruptHandler(() => false)
+
+return {
+ success: true,
+ value: parsedResult,
+logs: [...this.logs],
  }
+ } catch (unwrapError) {
+ return fail(unwrapError)
+ }
+ }
+
+ try {
+ // The interrupt handler only fires while the VM is stepping bytecode, so
+ // it cannot preempt a host binding whose Promise is awaited via asyncify.
+ // Keep it for CPU-bound loops, but also race the run against a wall-clock
+ // timer so `timeout` bounds the whole execution, host suspensions included.
+ const deadline = Date.now() + this.timeout
+ this.vm.runtime.setInterruptHandler(() => Date.now() > deadline)
+
+ const run = runToSettled()
+
+ let timeoutTimer: ReturnType<typeof setTimeout> | undefined
+ const wallClock = new Promise<typeof TIMED_OUT>((resolve) => {
+ timeoutTimer = setTimeout(() => resolve(TIMED_OUT), this.timeout)
+ })
+
+ const outcome = await Promise.race([run, wallClock])
+ if (timeoutTimer !== undefined) {
+ clearTimeout(timeoutTimer)
+ }
+
+ if (outcome !== TIMED_OUT) {
+ return outcome
+ }
+
+ // The interrupt fires at (almost) the same instant for a CPU-bound loop;
+ // give the in-VM interrupt a brief window to settle the run before
+ // treating this as a host call still suspended in asyncify.
+ const graced = await Promise.race([
+ run,
+ delay(TIMEOUT_INTERRUPT_GRACE_MS).then(
+ (): typeof TIMED_OUT => TIMED_OUT,
+ ),
+ ])
+ if (graced !== TIMED_OUT) {
+ return graced
  }
+
+ // Still suspended in a host call. The VM cannot be disposed now (freeing
+ // it mid-asyncify corrupts the stack the suspended call resumes into) and
+ // the host Promise cannot be cancelled. Leave the interrupt handler armed
+ // so the VM aborts the instant the host Promise resolves and it resumes
+ // stepping, then dispose the VM and release the queue turn once the
+ // orphaned run unwinds. This keeps the single-asyncify-suspension
+ // invariant that the global queue exists to protect.
+ this.timedOut = true
+ deferredToOrphan = true
+ this.orphanedRun = run
+ .catch(() => undefined)
+ .then(() => {
+ this.disposeVm()
+ releaseTurn()
+ })
+
+ return this.timeoutResult<T>()
  } catch (error) {
  return fail(error)
  } finally {
+ // On the orphan path the continuation owns interrupt-handler reset, VM
+ // disposal, and the queue-turn release; the still-armed handler is what
+ // lets the suspended run abort when it resumes.
+ // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- disposed may be set by fail() after a fatal limit error
+ if (!deferredToOrphan && !this.disposed) {
+ this.vm.runtime.setInterruptHandler(() => false)
+ }
  this.executing = false
- resolve()
+ if (!deferredToOrphan) {
+ releaseTurn()
+ }
  }
  }
 
  async dispose(): Promise<void> {
  if (this.disposed) return
 
+ // A timed-out execution may have left a host call suspended in asyncify.
+ // Its continuation disposes the VM once the call unwinds; wait for that
+ // rather than freeing the VM out from under the suspended call.
+ if (this.orphanedRun) {
+ await this.orphanedRun
+ return
+ }
+
  // If an execution is in flight, wait for the global queue to drain
  // before disposing the VM. Otherwise the asyncified callback would
  // try to access a freed context.
  if (this.executing) {
  await globalExecQueue
  }
 
+ // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the orphaned continuation may have disposed while we awaited the queue
+ if (this.disposed) return
+
  this.disposed = true
  this.vm.dispose()
  }
+
+ /** Reset the interrupt handler and tear the VM down exactly once. */
+ private disposeVm(): void {
+ if (this.disposed) return
+ try {
+ this.vm.runtime.setInterruptHandler(() => false)
+ } catch {
+ // ignore if the runtime is already torn down
+ }
+ this.disposed = true
+ this.vm.dispose()
+ }
+
+ private disposedResult<T>(): ExecutionResult<T> {
+ return {
+ success: false,
+ error: {
+ name: 'DisposedError',
+ message: 'Context has been disposed',
+ },
+ logs: [],
+ }
+ }
+
+ private timeoutResult<T>(): ExecutionResult<T> {
+ return {
+ success: false,
+ error: {
+ name: 'TimeoutError',
+ message: `Code execution exceeded timeout of ${this.timeout}ms`,
+ },
+ logs: [...this.logs],
+ }
+ }
 }