refactor(codemode): split runtime into focused interpreter modules (#36540)

packages/codemode/src/interpreter/errors.ts

@@ -0,0 +1,93 @@
+import type { Diagnostic } from "../codemode.js"
+import { ToolError } from "../tool-error.js"
+import { copyOut, ToolRuntimeError, type SafeObject } from "../tool-runtime.js"
+import { type AstNode, formatLocation, InterpreterRuntimeError, ProgramThrow, sourceLocation } from "./model.js"
+import { containsRuntimeReference } from "./references.js"
+import { spreadItems } from "../stdlib/collections.js"
+import { coerceToString, createAggregateErrorValue, createErrorValue, errorConstructors } from "../stdlib/value.js"
+
+export const normalizeError = (error: unknown): Diagnostic => {
+  if (error instanceof InterpreterRuntimeError) {
+    return {
+      kind: error.kind,
+      message: `${error.message}${formatLocation(error.node)}`,
+      ...(error.node?.loc ? { location: sourceLocation(error.node) } : {}),
+      ...(error.suggestions ? { suggestions: error.suggestions } : {}),
+    }
+  }
+
+  if (error instanceof ToolRuntimeError) {
+    return {
+      kind: error.kind,
+      message: error.message,
+      ...(error.suggestions.length > 0 ? { suggestions: error.suggestions } : {}),
+    }
+  }
+
+  if (error instanceof ToolError) {
+    return { kind: "ToolFailure", message: error.message }
+  }
+
+  if (error instanceof ProgramThrow) {
+    const value = error.value
+    let message: string
+    if (containsRuntimeReference(value)) {
+      // Never expose runtime reference internals through thrown values.
+      message = "a non-data value"
+    } else if (typeof value === "string") {
+      message = value
+    } else if (
+      value !== null &&
+      typeof value === "object" &&
+      typeof (value as { message?: unknown }).message === "string"
+    ) {
+      message = (value as { message: string }).message
+    } else {
+      try {
+        message = JSON.stringify(copyOut(value)) ?? String(value)
+      } catch {
+        message = String(value)
+      }
+    }
+    return { kind: "ExecutionFailure", message: `Uncaught: ${message}` }
+  }
+
+  if (error instanceof RangeError && /call stack|recursion/i.test(error.message)) {
+    return {
+      kind: "ExecutionFailure",
+      message: "Execution exceeded the maximum nesting depth.",
+    }
+  }
+
+  if (error instanceof Error) {
+    return {
+      kind: error.name === "SyntaxError" ? "ParseError" : "ExecutionFailure",
+      message: error.message,
+    }
+  }
+
+  return {
+    kind: "ExecutionFailure",
+    message: String(error),
+  }
+}
+
+export const caughtErrorValue = (thrown: unknown): unknown => {
+  if (thrown instanceof ProgramThrow) return thrown.value
+  if (thrown instanceof InterpreterRuntimeError) return createErrorValue(thrown.errorName, thrown.message)
+  const name = thrown instanceof Error && errorConstructors.has(thrown.name) ? thrown.name : "Error"
+  return createErrorValue(name, normalizeError(thrown).message)
+}
+
+export const constructErrorValue = (name: string, args: Array<unknown>, node: AstNode): SafeObject => {
+  if (name !== "AggregateError") return createErrorValue(name, args[0] === undefined ? "" : coerceToString(args[0]))
+  const errors = spreadItems(args[0])
+  if (errors === undefined) {
+    throw new InterpreterRuntimeError(
+      "new AggregateError(...) expects an array of errors (e.g. new AggregateError(errors, message?)).",
+      node,
+    ).as("TypeError")
+  }
+  // Error values must not alias caller-owned arrays.
+  return createAggregateErrorValue([...errors], args[1] === undefined ? "" : coerceToString(args[1]))
+}

packages/codemode/src/interpreter/execute.ts

@@ -0,0 +1,224 @@
+import { parse } from "acorn"
+import { Cause, Effect, Scope } from "effect"
+import { DiagnosticCategory, ModuleKind, ScriptTarget, flattenDiagnosticMessageText, transpileModule } from "typescript"
+import type { DataValue, Diagnostic, ExecuteOptions, ResolvedExecutionLimits, Result } from "../codemode.js"
+import { copyIn, copyOut, ToolRuntime, type HostTools, type Services } from "../tool-runtime.js"
+import { normalizeError } from "./errors.js"
+import { InterpreterRuntimeError, isRecord, type ProgramNode } from "./model.js"
+import { PromiseRuntime } from "./promises.js"
+import { Interpreter } from "./runtime.js"
+
+export const executeWithLimits = <const Tools extends Record<string, unknown>>(
+  options: ExecuteOptions<Tools>,
+  limits: ResolvedExecutionLimits,
+  searchIndex: ToolRuntime.DiscoveryPlan["searchIndex"],
+): Effect.Effect<Result, never, Services<Tools>> => {
+  if (options.code.trim().length === 0) {
+    return Effect.succeed({
+      ok: false,
+      error: { kind: "ParseError", message: "Code cannot be empty." },
+      toolCalls: [],
+    })
+  }
+
+  // Allocate execution state inside suspension so reused Effects never share it.
+  return Effect.suspend(() => {
+    const tools = ToolRuntime.make(
+      (options.tools ?? {}) as HostTools<Services<Tools>>,
+      limits.maxToolCalls,
+      searchIndex,
+      {
+        onToolCallStart: options.onToolCallStart,
+        onToolCallEnd: options.onToolCallEnd,
+      },
+    )
+    const logs: Array<string> = []
+    const logged = () => (logs.length > 0 ? { logs: [...logs] } : {})
+    // Set only after copy-out so timeouts cannot report invalid values as completed.
+    let returned: { value: DataValue; promises: PromiseRuntime<Services<Tools>> } | undefined
+
+    const base = Effect.acquireUseRelease(
+      Scope.make("parallel"),
+      (scope) =>
+        Effect.gen(function* () {
+          const program = parseProgram(options.code)
+          const promises = new PromiseRuntime<Services<Tools>>(scope)
+          const interpreter = new Interpreter<Services<Tools>>(tools.invoke, tools.search, tools.keys, promises, logs)
+          const value = yield* interpreter.run(program)
+          const result = copyOut(copyIn(value, "Execution result"), true) as DataValue
+          returned = { value: result, promises }
+          const warnings = yield* promises.interrupt()
+          return {
+            ok: true,
+            value: result,
+            ...(warnings.length > 0 ? { warnings } : {}),
+            ...logged(),
+            toolCalls: tools.calls,
+          } satisfies Result
+        }),
+      (scope, exit) => Scope.close(scope, exit),
+    )
+    const timeoutMs = limits.timeoutMs
+    const operation =
+      timeoutMs === undefined
+        ? base
+        : base.pipe(
+            Effect.timeoutOrElse({
+              duration: timeoutMs,
+              orElse: () =>
+                Effect.sync(() => {
+                  if (returned === undefined) {
+                    return {
+                      ok: false,
+                      error: { kind: "TimeoutExceeded", message: `Execution timed out after ${timeoutMs}ms.` },
+                      ...logged(),
+                      toolCalls: tools.calls,
+                    } satisfies Result
+                  }
+                  // Keep the timeout warning first so truncation preserves it.
+                  return {
+                    ok: true,
+                    value: returned.value,
+                    warnings: [
+                      {
+                        kind: "TimeoutExceeded",
+                        message: `The program returned, but background work was still running at the ${timeoutMs}ms timeout and was interrupted. Await all started promises.`,
+                      },
+                      ...returned.promises.diagnostics(),
+                    ],
+                    ...logged(),
+                    toolCalls: tools.calls,
+                  } satisfies Result
+                }),
+            }),
+          )
+
+    return operation.pipe(
+      Effect.catchCause((cause) =>
+        Cause.hasInterruptsOnly(cause)
+          ? Effect.interrupt
+          : Effect.succeed({
+              ok: false,
+              error: normalizeError(Cause.squash(cause)),
+              ...logged(),
+              toolCalls: tools.calls,
+            } satisfies Result),
+      ),
+      Effect.map((result) =>
+        limits.maxOutputBytes === undefined ? result : boundOutput(result, limits.maxOutputBytes),
+      ),
+    )
+  })
+}
+
+const parseProgram = (code: string): ProgramNode => {
+  const transpiled = transpileModule(`async function __codemode__() {\n${code}\n}`, {
+    reportDiagnostics: true,
+    compilerOptions: {
+      target: ScriptTarget.ESNext,
+      module: ModuleKind.ESNext,
+    },
+  })
+  const diagnostic = transpiled.diagnostics?.find((item) => item.category === DiagnosticCategory.Error)
+
+  if (diagnostic) {
+    throw new InterpreterRuntimeError(
+      `Failed to parse TypeScript: ${flattenDiagnosticMessageText(diagnostic.messageText, "\n")}`,
+      undefined,
+      "ParseError",
+    )
+  }
+
+  const bodyStart = transpiled.outputText.indexOf("{") + 1
+  const bodyEnd = transpiled.outputText.lastIndexOf("}")
+  const executableCode = transpiled.outputText.slice(bodyStart, bodyEnd)
+  const parsed = parse(executableCode, {
+    ecmaVersion: "latest",
+    sourceType: "script",
+    allowReturnOutsideFunction: true,
+    allowAwaitOutsideFunction: true,
+    locations: true,
+  }) as unknown
+
+  if (!isRecord(parsed) || parsed.type !== "Program" || !Array.isArray(parsed.body)) {
+    throw new InterpreterRuntimeError("Failed to parse script as a Program node.")
+  }
+
+  return parsed as ProgramNode
+}
+
+const utf8ByteLength = (value: string): number => new TextEncoder().encode(value).byteLength
+
+// Drop a replacement character produced by truncating inside a UTF-8 sequence.
+const utf8Truncate = (value: string, maxBytes: number): string => {
+  const bytes = new TextEncoder().encode(value)
+  if (bytes.byteLength <= maxBytes) return value
+  const text = new TextDecoder("utf-8").decode(bytes.slice(0, Math.max(0, maxBytes)))
+  return text.endsWith("\uFFFD") ? text.slice(0, -1) : text
+}
+
+// Warnings have a separate budget so result data cannot starve diagnostics.
+const boundOutput = (result: Result, maxOutputBytes: number): Result => {
+  let truncated = false
+
+  let value: DataValue = null
+  let valueBytes = 0
+  if (result.ok) {
+    const serialized = JSON.stringify(result.value) ?? "null"
+    const bytes = utf8ByteLength(serialized)
+    if (bytes > maxOutputBytes) {
+      truncated = true
+      value = `${utf8Truncate(serialized, maxOutputBytes)} [result truncated: ${bytes} bytes exceeds the ${maxOutputBytes}-byte output limit; return a smaller value]`
+      valueBytes = maxOutputBytes
+    } else {
+      value = result.value
+      valueBytes = bytes
+    }
+  }
+
+  const warnings = result.ok ? (result.warnings ?? []) : []
+  const keptWarnings: Array<Diagnostic> = []
+  let warningBytes = 0
+  for (const warning of warnings) {
+    const bytes = utf8ByteLength(JSON.stringify(warning)) + 1
+    if (warningBytes + bytes > maxOutputBytes) break
+    warningBytes += bytes
+    keptWarnings.push(warning)
+  }
+  if (keptWarnings.length < warnings.length) {
+    truncated = true
+    keptWarnings.push({
+      kind: "Truncated",
+      message: `${warnings.length - keptWarnings.length} additional warnings omitted by the output limit.`,
+    })
+  }
+
+  const logs = result.logs ?? []
+  const kept: Array<string> = []
+  const logBudget = Math.max(0, maxOutputBytes - valueBytes)
+  let logBytes = 0
+  for (const line of logs) {
+    const lineBytes = utf8ByteLength(line) + 1
+    if (logBytes + lineBytes > logBudget) break
+    logBytes += lineBytes
+    kept.push(line)
+  }
+  if (kept.length < logs.length) {
+    truncated = true
+    kept.push(`[logs truncated: showing ${kept.length} of ${logs.length} lines]`)
+  }
+
+  if (!truncated) return result
+  const warningsPart = keptWarnings.length > 0 ? { warnings: keptWarnings } : {}
+  const logsPart = kept.length > 0 ? { logs: kept } : {}
+  return result.ok
+    ? {
+        ok: true,
+        value,
+        ...warningsPart,
+        ...logsPart,
+        truncated: true,
+        toolCalls: result.toolCalls,
+      }
+    : { ok: false, error: result.error, ...logsPart, truncated: true, toolCalls: result.toolCalls }
+}

packages/codemode/src/interpreter/methods.ts

@@ -0,0 +1,819 @@
+import { Effect } from "effect"
+import {
+  type AstNode,
+  CodeModeFunction,
+  CoercionFunction,
+  GlobalMethodReference,
+  IntrinsicReference,
+  InterpreterRuntimeError,
+  PromiseCapabilityFunction,
+  supportedSyntaxMessage,
+  UriFunction,
+} from "./model.js"
+import { rejectCircularInsertion } from "./references.js"
+import { isBlockedMember, type SafeObject } from "../tool-runtime.js"
+import {
+  SandboxDate,
+  SandboxMap,
+  SandboxPromise,
+  SandboxRegExp,
+  SandboxSet,
+  SandboxURL,
+  SandboxURLSearchParams,
+} from "../values.js"
+import { invokeDateMethod, invokeDateStatic } from "../stdlib/date.js"
+import { invokeJsonMethod } from "../stdlib/json.js"
+import { invokeMathMethod } from "../stdlib/math.js"
+import { invokeNumberMethod, invokeNumberStatic } from "../stdlib/number.js"
+import { invokeObjectMethod } from "../stdlib/object.js"
+import { invokeRegExpMethod, matchToValue, toHostRegex } from "../stdlib/regexp.js"
+import { invokeStringStatic } from "../stdlib/string.js"
+import { invokeUriFunction, invokeURLMethod, invokeURLStatic, uriArgument } from "../stdlib/url.js"
+import { boundedData, coerceToNumber, coerceToString, invokeCoercion } from "../stdlib/value.js"
+
+export type CallbackRunner<R> = {
+  readonly invokeFunction: (fn: CodeModeFunction, args: Array<unknown>) => Effect.Effect<unknown, unknown, R>
+  readonly settlePromise: (promise: SandboxPromise) => Effect.Effect<unknown, unknown, never>
+}
+
+export const invokeIntrinsic = <R>(
+  runner: CallbackRunner<R>,
+  ref: IntrinsicReference,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  if (typeof ref.receiver === "string") {
+    if (
+      (ref.name === "replace" || ref.name === "replaceAll") &&
+      (args[1] instanceof CodeModeFunction || args[1] instanceof CoercionFunction || args[1] instanceof UriFunction)
+    ) {
+      return invokeStringReplacer(runner, ref.receiver, ref.name, args, node)
+    }
+    return Effect.succeed(invokeStringMethod(ref.receiver, ref.name, args, node))
+  }
+  if (typeof ref.receiver === "number") {
+    return Effect.succeed(invokeNumberMethod(ref.receiver, ref.name, args, node))
+  }
+  if (Array.isArray(ref.receiver)) {
+    return invokeArrayMethod(runner, ref.receiver, ref.name, args, node)
+  }
+  if (ref.receiver instanceof SandboxDate) {
+    return Effect.succeed(invokeDateMethod(ref.receiver, ref.name, node))
+  }
+  if (ref.receiver instanceof SandboxRegExp) {
+    return Effect.succeed(invokeRegExpMethod(ref.receiver, ref.name, args, node))
+  }
+  if (ref.receiver instanceof SandboxMap) {
+    return invokeMapMethod(runner, ref.receiver, ref.name, args, node)
+  }
+  if (ref.receiver instanceof SandboxSet) {
+    return invokeSetMethod(runner, ref.receiver, ref.name, args, node)
+  }
+  if (ref.receiver instanceof SandboxURL) {
+    return Effect.succeed(invokeURLMethod(ref.receiver, ref.name, node))
+  }
+  if (ref.receiver instanceof SandboxURLSearchParams) {
+    return invokeURLSearchParamsMethod(runner, ref.receiver, ref.name, args, node)
+  }
+  throw new InterpreterRuntimeError(`Method '${ref.name}' is not available in CodeMode.`, node)
+}
+
+export const invokeGlobalMethod = (ref: GlobalMethodReference, args: Array<unknown>, node: AstNode): unknown => {
+  if (ref.namespace === "console")
+    throw new InterpreterRuntimeError(`console.${ref.name} is not available in CodeMode.`, node)
+  if (ref.namespace === "Object") return invokeObjectMethod(ref.name, args, node)
+  if (ref.namespace === "Math") return invokeMathMethod(ref.name, args, node)
+  if (ref.namespace === "Array") return invokeArrayStatic(ref.name, args, node)
+  if (ref.namespace === "Number") return invokeNumberStatic(ref.name, args, node)
+  if (ref.namespace === "String") return invokeStringStatic(ref.name, args, node)
+  if (ref.namespace === "URL") return invokeURLStatic(ref.name, args, node)
+  if (ref.namespace === "Date") return invokeDateStatic(ref.name, args, node)
+  if (
+    ref.namespace === "RegExp" ||
+    ref.namespace === "Map" ||
+    ref.namespace === "Set" ||
+    ref.namespace === "URLSearchParams"
+  ) {
+    throw new InterpreterRuntimeError(`${ref.namespace}.${ref.name} is not available in CodeMode.`, node)
+  }
+  return invokeJsonMethod(ref.name, args, node)
+}
+
+const invokeStringMethod = (value: string, name: string, args: Array<unknown>, node: AstNode): unknown => {
+  const str = (index: number): string => {
+    const arg = args[index]
+    if (typeof arg !== "string")
+      throw new InterpreterRuntimeError(`String.${name} expects argument ${index + 1} to be a string.`, node)
+    return arg
+  }
+  const num = (index: number): number => {
+    const arg = args[index]
+    if (typeof arg !== "number")
+      throw new InterpreterRuntimeError(`String.${name} expects argument ${index + 1} to be a number.`, node)
+    return arg
+  }
+  const optNum = (index: number): number | undefined => (args[index] === undefined ? undefined : num(index))
+  const optStr = (index: number): string | undefined => (args[index] === undefined ? undefined : str(index))
+
+  let result: unknown
+  switch (name) {
+    case "toLowerCase":
+      result = value.toLowerCase()
+      break
+    case "toUpperCase":
+      result = value.toUpperCase()
+      break
+    case "trim":
+      result = value.trim()
+      break
+    case "trimStart":
+      result = value.trimStart()
+      break
+    case "trimEnd":
+      result = value.trimEnd()
+      break
+    // Locale/options are deliberately unsupported; comparison uses the host default locale.
+    case "localeCompare":
+      result = value.localeCompare(str(0))
+      break
+    case "normalize": {
+      const form = optStr(0)
+      try {
+        result = value.normalize(form)
+      } catch {
+        throw new InterpreterRuntimeError(
+          `String.normalize expects the form "NFC", "NFD", "NFKC", or "NFKD" (got ${JSON.stringify(form)}).`,
+          node,
+        ).as("RangeError")
+      }
+      break
+    }
+    case "split": {
+      if (args.length === 0) {
+        result = [value]
+        break
+      }
+      if (args[0] instanceof SandboxRegExp) {
+        result = value.split(args[0].regex, optNum(1))
+        break
+      }
+      const requestedLimit = optNum(1)
+      result = value.split(str(0), requestedLimit === undefined ? undefined : requestedLimit >>> 0)
+      break
+    }
+    case "slice":
+      result = value.slice(optNum(0), optNum(1))
+      break
+    case "includes":
+      result = value.includes(str(0), optNum(1))
+      break
+    case "startsWith":
+      result = value.startsWith(str(0), optNum(1))
+      break
+    case "endsWith":
+      result = value.endsWith(str(0), optNum(1))
+      break
+    case "indexOf":
+      result = value.indexOf(str(0), optNum(1))
+      break
+    case "lastIndexOf":
+      result = value.lastIndexOf(str(0), optNum(1))
+      break
+    case "replace":
+    case "replaceAll": {
+      if (args[0] instanceof SandboxRegExp) {
+        const pattern = args[0].regex
+        const replacement = str(1)
+        if (name === "replaceAll" && !pattern.global) {
+          throw new InterpreterRuntimeError(
+            `String.replaceAll requires a regular expression with the global (g) flag: write /${pattern.source}/${pattern.flags}g, or use String.replace to replace only the first match.`,
+            node,
+          )
+        }
+        result = name === "replace" ? value.replace(pattern, replacement) : value.replaceAll(pattern, replacement)
+        break
+      }
+      if (name === "replace") {
+        result = value.replace(str(0), str(1))
+        break
+      }
+      result = value.replaceAll(str(0), str(1))
+      break
+    }
+    case "match": {
+      const pattern = toHostRegex(args[0], name, node)
+      const matched = value.match(pattern)
+      if (matched === null) return null
+      // Preserve the own `index` and `groups` properties on non-global matches.
+      if (pattern.global) return boundedData(matched, "String.match result")
+      return matchToValue(matched)
+    }
+    case "matchAll": {
+      const pattern = toHostRegex(args[0], name, node, "g")
+      if (!pattern.global) {
+        throw new InterpreterRuntimeError(
+          `String.matchAll requires a regular expression with the global (g) flag: write /${pattern.source}/${pattern.flags}g, or use String.match for a single match.`,
+          node,
+        )
+      }
+      return Array.from(value.matchAll(pattern), matchToValue)
+    }
+    case "search": {
+      result = value.search(toHostRegex(args[0], name, node))
+      break
+    }
+    case "repeat": {
+      const count = num(0)
+      if (!Number.isFinite(count) || count < 0)
+        throw new InterpreterRuntimeError("String.repeat expects a finite non-negative count.", node)
+      result = value.repeat(count)
+      break
+    }
+    case "padStart":
+      result = value.padStart(num(0), optStr(1))
+      break
+    case "padEnd":
+      result = value.padEnd(num(0), optStr(1))
+      break
+    case "charAt":
+      result = value.charAt(optNum(0) ?? 0)
+      break
+    case "at":
+      result = value.at(optNum(0) ?? 0)
+      break
+    case "substring":
+      result = value.substring(optNum(0) ?? 0, optNum(1))
+      break
+    case "charCodeAt":
+      result = value.charCodeAt(optNum(0) ?? 0)
+      break
+    case "codePointAt":
+      result = value.codePointAt(optNum(0) ?? 0)
+      break
+    case "toString":
+      result = value
+      break
+    case "concat": {
+      result = value.concat(...args.map((_, index) => str(index)))
+      break
+    }
+    default:
+      throw new InterpreterRuntimeError(`String method '${name}' is not available in CodeMode.`, node)
+  }
+  return boundedData(result, `String.${name} result`)
+}
+
+const invokeArrayStatic = (name: string, args: Array<unknown>, node: AstNode): unknown => {
+  switch (name) {
+    case "isArray":
+      return Array.isArray(args[0])
+    case "of":
+      return [...args]
+    case "from": {
+      if (args.length > 1) {
+        throw new InterpreterRuntimeError(
+          "Array.from(...) does not support a map function in CodeMode; call .map() on the result instead.",
+          node,
+          "UnsupportedSyntax",
+          [supportedSyntaxMessage],
+        )
+      }
+      if (args[0] instanceof SandboxMap) return Array.from(args[0].map.entries(), ([key, item]) => [key, item])
+      if (args[0] instanceof SandboxSet) return Array.from(args[0].set.values())
+      if (args[0] instanceof SandboxURLSearchParams) {
+        return Array.from(args[0].params.entries(), ([key, value]) => [key, value])
+      }
+      const source = args[0]
+      if (source instanceof SandboxPromise) {
+        throw new InterpreterRuntimeError(
+          "Array.from received an un-awaited Promise; await it before creating the array.",
+          node,
+          "InvalidDataValue",
+        )
+      }
+      if (typeof source === "string") return Array.from(source)
+      if (Array.isArray(source)) return [...source]
+      if (
+        source !== null &&
+        typeof source === "object" &&
+        (Object.getPrototypeOf(source) === Object.prototype || Object.getPrototypeOf(source) === null) &&
+        typeof (source as { length?: unknown }).length === "number"
+      ) {
+        return Array.from(source as ArrayLike<unknown>)
+      }
+      throw new InterpreterRuntimeError(
+        "Array.from expects an array, string, Map, Set, or array-like value.",
+        node,
+        "InvalidDataValue",
+      )
+    }
+    default:
+      throw new InterpreterRuntimeError(`Array.${name} is not available in CodeMode.`, node)
+  }
+}
+
+const invokeStringReplacer = <R>(
+  runner: CallbackRunner<R>,
+  value: string,
+  name: "replace" | "replaceAll",
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  const apply = applyCollectionCallback(runner, args[1], `String.${name}`, node)
+  const matches: Array<{ readonly match: string; readonly offset: number; readonly args: Array<unknown> }> = []
+  const collect = (...callbackArgs: Array<unknown>): string => {
+    const match = callbackArgs[0]
+    const groups = callbackArgs[callbackArgs.length - 1]
+    const hasGroups = groups !== null && typeof groups === "object"
+    const offset = callbackArgs[callbackArgs.length - (hasGroups ? 3 : 2)]
+    if (typeof match !== "string" || typeof offset !== "number") {
+      throw new InterpreterRuntimeError(`String.${name} produced an invalid replacement match.`, node)
+    }
+    if (hasGroups) {
+      const safeGroups: SafeObject = Object.create(null) as SafeObject
+      for (const [key, group] of Object.entries(groups)) {
+        if (!isBlockedMember(key)) safeGroups[key] = group
+      }
+      callbackArgs[callbackArgs.length - 1] = safeGroups
+    }
+    matches.push({ match, offset, args: callbackArgs })
+    return match
+  }
+
+  const pattern = args[0]
+  if (pattern instanceof SandboxRegExp) {
+    if (name === "replaceAll" && !pattern.regex.global) {
+      throw new InterpreterRuntimeError(
+        `String.replaceAll requires a regular expression with the global (g) flag: write /${pattern.regex.source}/${pattern.regex.flags}g, or use String.replace to replace only the first match.`,
+        node,
+      )
+    }
+    if (name === "replace") value.replace(pattern.regex, collect)
+    else value.replaceAll(pattern.regex, collect)
+  } else {
+    if (typeof pattern !== "string") {
+      throw new InterpreterRuntimeError(`String.${name} expects argument 1 to be a string.`, node)
+    }
+    if (name === "replace") value.replace(pattern, collect)
+    else value.replaceAll(pattern, collect)
+  }
+
+  return Effect.gen(function* () {
+    const output: Array<string> = []
+    let end = 0
+    for (const match of matches) {
+      const replacement = yield* apply(match.args)
+      const resolved =
+        args[1] instanceof CodeModeFunction && args[1].async && replacement instanceof SandboxPromise
+          ? yield* runner.settlePromise(replacement)
+          : replacement
+      output.push(
+        value.slice(end, match.offset),
+        coerceToString(boundedData(resolved, `String.${name} replacer result`)),
+      )
+      end = match.offset + match.match.length
+    }
+    output.push(value.slice(end))
+    return boundedData(output.join(""), `String.${name} result`)
+  })
+}
+
+export const applyCollectionCallback = <R>(
+  runner: CallbackRunner<R>,
+  callback: unknown,
+  name: string,
+  node: AstNode,
+): ((args: Array<unknown>) => Effect.Effect<unknown, unknown, R>) => {
+  if (
+    !(callback instanceof CodeModeFunction) &&
+    !(callback instanceof CoercionFunction) &&
+    !(callback instanceof UriFunction) &&
+    !(callback instanceof PromiseCapabilityFunction)
+  ) {
+    throw new InterpreterRuntimeError(`${name} expects a function callback.`, node)
+  }
+  return (callbackArgs) =>
+    callback instanceof CoercionFunction
+      ? Effect.succeed(invokeCoercion(callback, callbackArgs, node))
+      : callback instanceof UriFunction
+        ? Effect.succeed(invokeUriFunction(callback, callbackArgs, node))
+        : callback instanceof PromiseCapabilityFunction
+          ? Effect.sync(() => callback.settle(callbackArgs[0]))
+          : runner.invokeFunction(callback, callbackArgs)
+}
+
+const invokeMapMethod = <R>(
+  runner: CallbackRunner<R>,
+  target: SandboxMap,
+  name: string,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  switch (name) {
+    case "get":
+      return Effect.succeed(target.map.get(args[0]))
+    case "has":
+      return Effect.succeed(target.map.has(args[0]))
+    case "set":
+      return Effect.sync(() => {
+        target.map.set(args[0], args[1])
+        return target
+      })
+    case "delete":
+      return Effect.sync(() => target.map.delete(args[0]))
+    case "clear":
+      return Effect.sync(() => {
+        target.map.clear()
+        return undefined
+      })
+    case "keys":
+      return Effect.sync(() => Array.from(target.map.keys()))
+    case "values":
+      return Effect.sync(() => Array.from(target.map.values()))
+    case "entries":
+      return Effect.sync(() => Array.from(target.map.entries(), ([key, item]): Array<unknown> => [key, item]))
+    case "forEach": {
+      const apply = applyCollectionCallback(runner, args[0], "Map.forEach", node)
+      return Effect.gen(function* () {
+        for (const [key, item] of Array.from(target.map.entries())) yield* apply([item, key, target])
+        return undefined
+      })
+    }
+    default:
+      throw new InterpreterRuntimeError(`Map method '${name}' is not available in CodeMode.`, node)
+  }
+}
+
+const invokeSetMethod = <R>(
+  runner: CallbackRunner<R>,
+  target: SandboxSet,
+  name: string,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  switch (name) {
+    case "has":
+      return Effect.succeed(target.set.has(args[0]))
+    case "add":
+      return Effect.sync(() => {
+        target.set.add(args[0])
+        return target
+      })
+    case "delete":
+      return Effect.sync(() => target.set.delete(args[0]))
+    case "clear":
+      return Effect.sync(() => {
+        target.set.clear()
+        return undefined
+      })
+    case "keys":
+    case "values":
+      return Effect.sync(() => Array.from(target.set.values()))
+    case "entries":
+      return Effect.sync(() => Array.from(target.set.values(), (item): Array<unknown> => [item, item]))
+    case "forEach": {
+      const apply = applyCollectionCallback(runner, args[0], "Set.forEach", node)
+      return Effect.gen(function* () {
+        for (const item of Array.from(target.set.values())) yield* apply([item, item, target])
+        return undefined
+      })
+    }
+    default:
+      throw new InterpreterRuntimeError(`Set method '${name}' is not available in CodeMode.`, node)
+  }
+}
+
+const invokeURLSearchParamsMethod = <R>(
+  runner: CallbackRunner<R>,
+  target: SandboxURLSearchParams,
+  name: string,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  const arg = (index: number): string => uriArgument(args[index], `URLSearchParams.${name} argument ${index + 1}`)
+  const requireArgs = (count: number): void => {
+    if (args.length < count) {
+      throw new InterpreterRuntimeError(
+        `URLSearchParams.${name} requires ${count} argument${count === 1 ? "" : "s"}.`,
+        node,
+      ).as("TypeError")
+    }
+  }
+  switch (name) {
+    case "append": {
+      requireArgs(2)
+      return Effect.sync(() => {
+        target.params.append(arg(0), arg(1))
+        return undefined
+      })
+    }
+    case "delete": {
+      requireArgs(1)
+      return Effect.sync(() => {
+        if (args[1] !== undefined) target.params.delete(arg(0), arg(1))
+        else target.params.delete(arg(0))
+        return undefined
+      })
+    }
+    case "get":
+      requireArgs(1)
+      return Effect.sync(() => target.params.get(arg(0)))
+    case "getAll":
+      requireArgs(1)
+      return Effect.sync(() => target.params.getAll(arg(0)))
+    case "has":
+      requireArgs(1)
+      return Effect.sync(() => (args[1] !== undefined ? target.params.has(arg(0), arg(1)) : target.params.has(arg(0))))
+    case "set": {
+      requireArgs(2)
+      return Effect.sync(() => {
+        target.params.set(arg(0), arg(1))
+        return undefined
+      })
+    }
+    case "sort":
+      return Effect.sync(() => {
+        target.params.sort()
+        return undefined
+      })
+    case "keys":
+      return Effect.sync(() => Array.from(target.params.keys()))
+    case "values":
+      return Effect.sync(() => Array.from(target.params.values()))
+    case "entries":
+      return Effect.sync(() => Array.from(target.params.entries(), ([key, value]): Array<unknown> => [key, value]))
+    case "toString":
+      return Effect.sync(() => target.params.toString())
+    case "forEach": {
+      requireArgs(1)
+      const apply = applyCollectionCallback(runner, args[0], "URLSearchParams.forEach", node)
+      return Effect.gen(function* () {
+        for (const [key, value] of Array.from(target.params.entries())) yield* apply([value, key, target])
+        return undefined
+      })
+    }
+    default:
+      throw new InterpreterRuntimeError(`URLSearchParams method '${name}' is not available in CodeMode.`, node)
+  }
+}
+
+const invokeArrayMethod = <R>(
+  runner: CallbackRunner<R>,
+  target: Array<unknown>,
+  name: string,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  const optNumber = (value: unknown, label: string): number | undefined => {
+    if (value === undefined) return undefined
+    if (typeof value !== "number")
+      throw new InterpreterRuntimeError(`Array.${name} expects ${label} to be a number.`, node)
+    return value
+  }
+  switch (name) {
+    case "join": {
+      if (args.length > 1 || (args.length === 1 && typeof args[0] !== "string")) {
+        throw new InterpreterRuntimeError("Array.join expects zero arguments or one string separator.", node)
+      }
+      const input = boundedData(target, "Array.join input") as Array<unknown>
+      return Effect.succeed(
+        input.map((item) => coerceToString(item ?? "")).join(args.length === 0 ? "," : (args[0] as string)),
+      )
+    }
+    case "includes":
+      if (args.length === 0 || args.length > 2)
+        throw new InterpreterRuntimeError("Array.includes expects a value and optional start index.", node)
+      return Effect.succeed(target.includes(args[0], optNumber(args[1], "start index")))
+    case "indexOf":
+      return Effect.succeed(target.indexOf(args[0], optNumber(args[1], "start index")))
+    case "lastIndexOf":
+      return Effect.succeed(
+        args[1] === undefined
+          ? target.lastIndexOf(args[0])
+          : target.lastIndexOf(args[0], optNumber(args[1], "start index")),
+      )
+    case "at":
+      return Effect.succeed(target.at(optNumber(args[0], "index") ?? 0))
+    case "slice":
+      return Effect.succeed(target.slice(optNumber(args[0], "start"), optNumber(args[1], "end")))
+    case "concat":
+      return Effect.succeed(target.concat(...args))
+    case "flat":
+      return Effect.succeed(target.flat(optNumber(args[0], "depth") ?? 1))
+    case "reverse":
+      return Effect.succeed(target.reverse())
+    case "sort":
+      return Effect.map(sortArray(runner, target, args[0], node), (sorted) => {
+        target.splice(0, target.length, ...sorted)
+        return target
+      })
+    case "toSorted":
+      return sortArray(runner, target, args[0], node)
+    case "toReversed":
+      return Effect.succeed([...target].reverse())
+    case "with": {
+      const index = optNumber(args[0], "index") ?? 0
+      const resolved = index < 0 ? target.length + index : index
+      if (resolved < 0 || resolved >= target.length) {
+        throw new InterpreterRuntimeError("Array.with index is out of range.", node)
+      }
+      const copied = [...target]
+      copied[resolved] = args[1]
+      return Effect.succeed(copied)
+    }
+    case "push": {
+      // Validate all insertions before mutating to avoid partial cyclic updates.
+      for (const item of args) rejectCircularInsertion(target, item, "Array.push result", node)
+      target.push(...args)
+      return Effect.succeed(target.length)
+    }
+    case "unshift": {
+      for (const item of args) rejectCircularInsertion(target, item, "Array.unshift result", node)
+      target.unshift(...args)
+      return Effect.succeed(target.length)
+    }
+    case "pop":
+      return Effect.succeed(target.pop())
+    case "shift":
+      return Effect.succeed(target.shift())
+    case "splice": {
+      if (args.length === 0) return Effect.succeed(target.splice(0, 0))
+      const start = optNumber(args[0], "start") ?? 0
+      if (args.length === 1) return Effect.succeed(target.splice(start))
+      const deleteCount = optNumber(args[1], "delete count") ?? 0
+      const inserted = args.slice(2)
+      for (const item of inserted) rejectCircularInsertion(target, item, "Array.splice result", node)
+      return Effect.succeed(target.splice(start, deleteCount, ...inserted))
+    }
+    case "fill": {
+      rejectCircularInsertion(target, args[0], "Array.fill result", node)
+      return Effect.succeed(target.fill(args[0], optNumber(args[1], "start"), optNumber(args[2], "end")))
+    }
+    case "copyWithin":
+      return Effect.succeed(
+        target.copyWithin(
+          optNumber(args[0], "target index") ?? 0,
+          optNumber(args[1], "start") ?? 0,
+          optNumber(args[2], "end"),
+        ),
+      )
+    case "keys":
+      return Effect.succeed(Array.from(target.keys()))
+    case "values":
+      return Effect.succeed([...target])
+    case "entries":
+      return Effect.succeed(Array.from(target.entries(), ([index, item]): Array<unknown> => [index, item]))
+  }
+
+  const apply = applyCollectionCallback(runner, args[0], `Array.${name}`, node)
+  return Effect.gen(function* () {
+    // Fix iteration length while reading existing elements live.
+    const length = target.length
+    switch (name) {
+      case "map": {
+        const values: Array<unknown> = []
+        values.length = length
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          values[index] = yield* apply([target[index], index, target])
+        }
+        return values
+      }
+      case "flatMap": {
+        const values: Array<unknown> = []
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          const mapped = yield* apply([target[index], index, target])
+          if (Array.isArray(mapped)) values.push(...mapped)
+          else values.push(mapped)
+        }
+        return values
+      }
+      case "filter": {
+        const values: Array<unknown> = []
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          const item = target[index]
+          if (yield* apply([item, index, target])) values.push(item)
+        }
+        return values
+      }
+      case "find":
+        for (let index = 0; index < length; index += 1) {
+          const item = target[index]
+          if (yield* apply([item, index, target])) return item
+        }
+        return undefined
+      case "findIndex":
+        for (let index = 0; index < length; index += 1) {
+          if (yield* apply([target[index], index, target])) return index
+        }
+        return -1
+      case "some":
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          if (yield* apply([target[index], index, target])) return true
+        }
+        return false
+      case "every":
+        for (let index = 0; index < length; index += 1) {
+          if (!(index in target)) continue
+          if (!(yield* apply([target[index], index, target]))) return false
+        }
+        return true
+      case "forEach":
+        for (let index = 0; index < length; index += 1) {
+          if (index in target) yield* apply([target[index], index, target])
+        }
+        return undefined
+      case "reduce": {
+        let accumulator: unknown
+        let start: number
+        if (args.length >= 2) {
+          accumulator = args[1]
+          start = 0
+        } else {
+          if (length === 0)
+            throw new InterpreterRuntimeError("Array.reduce of an empty array with no initial value.", node)
+          accumulator = target[0]
+          start = 1
+        }
+        for (let index = start; index < length; index += 1) {
+          if (!(index in target)) continue
+          accumulator = yield* apply([accumulator, target[index], index, target])
+        }
+        return accumulator
+      }
+      case "reduceRight": {
+        let accumulator: unknown
+        let start: number
+        if (args.length >= 2) {
+          accumulator = args[1]
+          start = length - 1
+        } else {
+          if (length === 0)
+            throw new InterpreterRuntimeError("Array.reduceRight of an empty array with no initial value.", node)
+          accumulator = target[length - 1]
+          start = length - 2
+        }
+        for (let index = start; index >= 0; index -= 1) {
+          if (!(index in target)) continue
+          accumulator = yield* apply([accumulator, target[index], index, target])
+        }
+        return accumulator
+      }
+      case "findLast":
+        for (let index = length - 1; index >= 0; index -= 1) {
+          if (yield* apply([target[index], index, target])) return target[index]
+        }
+        return undefined
+      case "findLastIndex":
+        for (let index = length - 1; index >= 0; index -= 1) {
+          if (yield* apply([target[index], index, target])) return index
+        }
+        return -1
+    }
+    throw new InterpreterRuntimeError(`Array method '${name}' is not available in CodeMode.`, node)
+  })
+}
+
+const sortArray = <R>(
+  runner: CallbackRunner<R>,
+  target: Array<unknown>,
+  comparator: unknown,
+  node: AstNode,
+): Effect.Effect<Array<unknown>, unknown, R> => {
+  if (comparator !== undefined && !(comparator instanceof CodeModeFunction)) {
+    throw new InterpreterRuntimeError("Array.sort expects an arrow function comparator.", node)
+  }
+  if (!(comparator instanceof CodeModeFunction)) {
+    return Effect.sync(() =>
+      [...target].sort((a, b) => {
+        const left = coerceToString(a)
+        const right = coerceToString(b)
+        return left < right ? -1 : left > right ? 1 : 0
+      }),
+    )
+  }
+  const mergeSort = (items: Array<unknown>): Effect.Effect<Array<unknown>, unknown, R> => {
+    if (items.length <= 1) return Effect.succeed(items)
+    const midpoint = Math.floor(items.length / 2)
+    return Effect.gen(function* () {
+      const left = yield* mergeSort(items.slice(0, midpoint))
+      const right = yield* mergeSort(items.slice(midpoint))
+      const merged: Array<unknown> = []
+      let leftIndex = 0
+      let rightIndex = 0
+      while (leftIndex < left.length && rightIndex < right.length) {
+        // Treat a NaN comparator result as equal to preserve stable ordering.
+        const order = coerceToNumber(yield* runner.invokeFunction(comparator, [left[leftIndex], right[rightIndex]]))
+        if (Number.isNaN(order) || order <= 0) merged.push(left[leftIndex++])
+        else merged.push(right[rightIndex++])
+      }
+      return [...merged, ...left.slice(leftIndex), ...right.slice(rightIndex)]
+    })
+  }
+  const defined = target.filter((item) => item !== undefined)
+  const undefinedCount = target.length - defined.length
+  return Effect.map(mergeSort(defined), (items) => [...items, ...Array(undefinedCount).fill(undefined)])
+}

packages/codemode/src/interpreter/model.ts

@@ -76,8 +76,6 @@ export class PromiseInstanceMethodReference {
   ) {}
 }
 
-// The resolve/reject callables handed to a `new Promise(executor)` executor. `settle` closes
-// over the promise's deferred and is first-settlement-wins; later calls are no-ops, as in JS.
 export class PromiseCapabilityFunction {
   constructor(readonly settle: (value: unknown) => void) {}
 }
@@ -114,8 +112,6 @@ export class UriFunction {
   constructor(readonly name: "encodeURI" | "encodeURIComponent" | "decodeURI" | "decodeURIComponent") {}
 }
 
-// The global `search` built-in: synchronous tool discovery that shares the tool admission
-// pipeline (budget, audit, hooks) without living in the `tools` tree.
 export class SearchFunction {}
 
 export class ProgramThrow {

packages/codemode/src/interpreter/promises.ts

@@ -0,0 +1,336 @@
+import { Cause, Deferred, Effect, Exit, Fiber, Scope } from "effect"
+import type { Diagnostic } from "../codemode.js"
+import type { SafeObject } from "../tool-runtime.js"
+import {
+  type AstNode,
+  CodeModeFunction,
+  CoercionFunction,
+  InterpreterRuntimeError,
+  ProgramThrow,
+  PromiseCapabilityFunction,
+  PromiseInstanceMethodReference,
+  PromiseMethodReference,
+  UriFunction,
+} from "./model.js"
+import { caughtErrorValue, normalizeError } from "./errors.js"
+import { applyCollectionCallback, type CallbackRunner } from "./methods.js"
+import { typeofValue } from "./references.js"
+import { spreadItems } from "../stdlib/collections.js"
+import { createAggregateErrorValue } from "../stdlib/value.js"
+import { SandboxPromise } from "../values.js"
+
+// Observation only controls rejection reporting; program completion interrupts all promise work.
+export class PromiseRuntime<R> {
+  private readonly active = new Set<SandboxPromise>()
+  private readonly ids = new WeakMap<SandboxPromise, number>()
+  private readonly observed = new WeakSet<SandboxPromise>()
+  private readonly failures = new Map<number, Diagnostic>()
+  private nextID = 0
+
+  constructor(private readonly scope: Scope.Scope) {}
+
+  create(effect: Effect.Effect<unknown, unknown, R>): Effect.Effect<SandboxPromise, never, R> {
+    return Effect.suspend(() => {
+      // Allocate before forking so reruns get distinct IDs and diagnostics retain creation order.
+      const id = this.nextID++
+      return Effect.map(Effect.forkIn(effect, this.scope, { startImmediately: true }), (fiber) => {
+        const promise = new SandboxPromise(fiber)
+        this.active.add(promise)
+        this.ids.set(promise, id)
+        fiber.addObserver((exit) => {
+          this.active.delete(promise)
+          if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) || this.observed.has(promise)) {
+            this.ids.delete(promise)
+            return
+          }
+          const failure = normalizeError(Cause.squash(exit.cause))
+          this.failures.set(id, {
+            ...failure,
+            message: `Unhandled rejection from an un-awaited promise: ${failure.message}`,
+          })
+        })
+        return promise
+      })
+    })
+  }
+
+  // Observation must be recorded when responsibility transfers, before the consumer fiber runs.
+  markObserved(promise: SandboxPromise): void {
+    this.observed.add(promise)
+    const id = this.ids.get(promise)
+    this.ids.delete(promise)
+    if (id !== undefined) this.failures.delete(id)
+  }
+
+  await(promise: SandboxPromise): Effect.Effect<Exit.Exit<unknown, unknown>> {
+    return Fiber.await(promise.fiber)
+  }
+
+  diagnostics(): Array<Diagnostic> {
+    return [...this.failures].sort(([left], [right]) => left - right).map(([, failure]) => failure)
+  }
+
+  // Re-check because a straggler can create promises before its interruption lands.
+  interrupt(): Effect.Effect<Array<Diagnostic>> {
+    const self = this
+    return Effect.gen(function* () {
+      while (self.active.size > 0) {
+        yield* Fiber.interruptAll([...self.active].map((promise) => promise.fiber))
+      }
+      return self.diagnostics()
+    })
+  }
+}
+
+export const selfResolutionError = (node?: AstNode): InterpreterRuntimeError =>
+  new InterpreterRuntimeError("Chaining cycle detected: a promise cannot resolve with itself.", node).as("TypeError")
+
+export const invokePromiseMethod = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  ref: PromiseMethodReference,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<unknown, unknown, R> => {
+  if (ref.name === "resolve") {
+    const value = args[0]
+    return value instanceof SandboxPromise ? Effect.succeed(value) : promises.create(Effect.succeed(value))
+  }
+  if (ref.name === "reject") {
+    return promises.create(Effect.fail(new ProgramThrow(args[0])))
+  }
+
+  const spread = spreadItems(args[0])
+  if (spread === undefined) {
+    return promises.create(
+      Effect.fail(
+        new InterpreterRuntimeError(
+          `Promise.${ref.name} expects an array of promises or plain values (e.g. Promise.${ref.name}(items.map((item) => tools.ns.tool(item)))).`,
+          node,
+        ).as("TypeError"),
+      ),
+    )
+  }
+  const items = Array.from(spread)
+
+  for (const item of items) {
+    if (item instanceof SandboxPromise) promises.markObserved(item)
+  }
+
+  switch (ref.name) {
+    case "all": {
+      const observations = items.map((item) =>
+        item instanceof SandboxPromise ? Effect.flatten(promises.await(item)) : Effect.succeed(item),
+      )
+      return promises.create(settleAfterTurn(Effect.all(observations, { concurrency: "unbounded" })))
+    }
+    case "allSettled": {
+      const observations = items.map((item) =>
+        item instanceof SandboxPromise ? promises.await(item) : Effect.succeed(Exit.succeed(item)),
+      )
+      return promises.create(
+        settleAfterTurn(
+          Effect.gen(function* () {
+            const outcomes: Array<unknown> = []
+            for (const observation of observations) {
+              const exit = yield* observation
+              if (Exit.isSuccess(exit)) {
+                outcomes.push(
+                  Object.assign(Object.create(null) as SafeObject, { status: "fulfilled", value: exit.value }),
+                )
+                continue
+              }
+              if (Cause.hasInterruptsOnly(exit.cause)) {
+                // Teardown interruption is not a program-level rejection.
+                return yield* Effect.failCause(exit.cause)
+              }
+              outcomes.push(
+                Object.assign(Object.create(null) as SafeObject, {
+                  status: "rejected",
+                  reason: caughtErrorValue(Cause.squash(exit.cause)),
+                }),
+              )
+            }
+            return outcomes
+          }),
+        ),
+      )
+    }
+    case "race": {
+      if (items.length === 0) {
+        return promises.create(
+          Effect.fail(
+            new InterpreterRuntimeError(
+              "Promise.race([]) would never settle; provide at least one promise or value.",
+              node,
+            ),
+          ),
+        )
+      }
+      const observations = items.map((item) =>
+        item instanceof SandboxPromise ? promises.await(item) : Effect.succeed(Exit.succeed(item)),
+      )
+      return promises.create(settleAfterTurn(Effect.flatten(Effect.raceAll(observations))))
+    }
+    case "any": {
+      const flipped = items.map((item) =>
+        item instanceof SandboxPromise
+          ? Effect.flatMap(promises.await(item), (exit) => {
+              if (Exit.isSuccess(exit)) return Effect.fail(new PromiseAnyFulfilled(exit.value))
+              if (Cause.hasInterruptsOnly(exit.cause)) return Effect.failCause(exit.cause)
+              return Effect.succeed(caughtErrorValue(Cause.squash(exit.cause)))
+            })
+          : Effect.fail(new PromiseAnyFulfilled(item)),
+      )
+      const body = Effect.all(flipped, { concurrency: "unbounded" }).pipe(
+        Effect.flatMap((reasons) =>
+          Effect.fail(new ProgramThrow(createAggregateErrorValue(reasons, "All promises were rejected"))),
+        ),
+        Effect.catch((error) =>
+          error instanceof PromiseAnyFulfilled ? Effect.succeed(error.value) : Effect.fail(error),
+        ),
+      )
+      return promises.create(settleAfterTurn(body))
+    }
+  }
+}
+
+export const invokePromiseInstanceMethod = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  ref: PromiseInstanceMethodReference,
+  args: Array<unknown>,
+  node: AstNode,
+): Effect.Effect<SandboxPromise, never, R> => {
+  const method = `Promise.prototype.${ref.name}`
+  promises.markObserved(ref.promise)
+  if (ref.name === "finally") {
+    return chainFinally(runner, promises, ref.promise, reactionHandler(args[0], method, node), method, node)
+  }
+  const onFulfilled = ref.name === "then" ? reactionHandler(args[0], method, node) : undefined
+  const onRejected = reactionHandler(ref.name === "then" ? args[1] : args[0], method, node)
+  return chainReaction(runner, promises, ref.promise, onFulfilled, onRejected, method, node)
+}
+
+export const constructPromise = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  executor: unknown,
+  node: AstNode,
+): Effect.Effect<SandboxPromise, unknown, R> => {
+  if (!(executor instanceof CodeModeFunction)) {
+    throw new InterpreterRuntimeError(
+      "new Promise(...) expects an executor function (e.g. new Promise((resolve, reject) => { ... })).",
+      node,
+    ).as("TypeError")
+  }
+  return Effect.gen(function* () {
+    const deferred = Deferred.makeUnsafe<unknown, unknown>()
+    const box: { own?: SandboxPromise } = {}
+    const promise = yield* promises.create(
+      Effect.flatMap(Deferred.await(deferred), (value) => {
+        if (!(value instanceof SandboxPromise)) return Effect.succeed(value)
+        if (value === box.own) return Effect.fail(selfResolutionError(node))
+        return runner.settlePromise(value)
+      }),
+    )
+    box.own = promise
+    const resolve = new PromiseCapabilityFunction((value) => {
+      Deferred.doneUnsafe(deferred, Exit.succeed(value))
+    })
+    const reject = new PromiseCapabilityFunction((value) => {
+      Deferred.doneUnsafe(deferred, Exit.fail(new ProgramThrow(value)))
+    })
+    const executed = yield* Effect.exit(runner.invokeFunction(executor, [resolve, reject]))
+    if (!Exit.isSuccess(executed)) {
+      if (Cause.hasInterruptsOnly(executed.cause)) return yield* Effect.failCause(executed.cause)
+      Deferred.doneUnsafe(deferred, Exit.fail(Cause.squash(executed.cause)))
+    }
+    return promise
+  })
+}
+
+// Settle one reaction turn after the deciding member, after its existing reactions.
+const settleAfterTurn = <A, E, R>(body: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.flatMap(Effect.exit(body), (exit) => Effect.andThen(Effect.yieldNow, exit))
+
+class PromiseAnyFulfilled {
+  constructor(readonly value: unknown) {}
+}
+
+type ReactionHandler = CodeModeFunction | CoercionFunction | UriFunction | PromiseCapabilityFunction
+
+const reactionHandler = (value: unknown, method: string, node: AstNode): ReactionHandler | undefined => {
+  if (
+    value instanceof CodeModeFunction ||
+    value instanceof CoercionFunction ||
+    value instanceof UriFunction ||
+    value instanceof PromiseCapabilityFunction
+  ) {
+    return value
+  }
+  if (typeofValue(value) === "function") {
+    throw new InterpreterRuntimeError(
+      `${method} handlers must be plain functions; wrap other callables in an arrow function, e.g. (value) => tools.ns.tool(value).`,
+      node,
+    )
+  }
+  return undefined
+}
+
+// Teardown bypasses handlers; settled reactions yield once so handlers never run inline.
+const reactionExit = <R>(
+  promises: PromiseRuntime<R>,
+  source: SandboxPromise,
+): Effect.Effect<Exit.Exit<unknown, unknown>, unknown, R> =>
+  Effect.gen(function* () {
+    const exit = yield* promises.await(source)
+    if (!Exit.isSuccess(exit) && Cause.hasInterruptsOnly(exit.cause)) return yield* Effect.failCause(exit.cause)
+    yield* Effect.yieldNow
+    return exit
+  })
+
+const chainReaction = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  source: SandboxPromise,
+  onFulfilled: ReactionHandler | undefined,
+  onRejected: ReactionHandler | undefined,
+  method: string,
+  node: AstNode,
+): Effect.Effect<SandboxPromise, never, R> => {
+  const box: { derived?: SandboxPromise } = {}
+  const body = Effect.gen(function* () {
+    const exit = yield* reactionExit(promises, source)
+    const handler = Exit.isSuccess(exit) ? onFulfilled : onRejected
+    if (handler === undefined) return yield* exit
+    const input = Exit.isSuccess(exit) ? exit.value : caughtErrorValue(Cause.squash(exit.cause))
+    const result = yield* applyCollectionCallback(runner, handler, method, node)([input])
+    if (result === box.derived) return yield* Effect.fail(selfResolutionError(node))
+    if (result instanceof SandboxPromise) return yield* runner.settlePromise(result)
+    return result
+  })
+  return Effect.map(promises.create(body), (derived) => {
+    box.derived = derived
+    return derived
+  })
+}
+
+const chainFinally = <R>(
+  runner: CallbackRunner<R>,
+  promises: PromiseRuntime<R>,
+  source: SandboxPromise,
+  cleanup: ReactionHandler | undefined,
+  method: string,
+  node: AstNode,
+): Effect.Effect<SandboxPromise, never, R> =>
+  promises.create(
+    Effect.gen(function* () {
+      const exit = yield* reactionExit(promises, source)
+      if (cleanup !== undefined) {
+        const result = yield* applyCollectionCallback(runner, cleanup, method, node)([])
+        if (result instanceof SandboxPromise) yield* runner.settlePromise(result)
+      }
+      return yield* exit
+    }),
+  )

packages/codemode/src/interpreter/references.ts

@@ -0,0 +1,99 @@
+import {
+  type AstNode,
+  CodeModeFunction,
+  CoercionFunction,
+  ErrorConstructorReference,
+  GlobalMethodReference,
+  GlobalNamespace,
+  InterpreterRuntimeError,
+  IntrinsicReference,
+  PromiseCapabilityFunction,
+  PromiseInstanceMethodReference,
+  PromiseMethodReference,
+  PromiseNamespace,
+  SearchFunction,
+  UriFunction,
+} from "./model.js"
+import { ToolReference } from "../tool-runtime.js"
+import { isSandboxValue, SandboxPromise } from "../values.js"
+
+export const isRuntimeReference = (value: unknown): boolean =>
+  value instanceof CodeModeFunction ||
+  value instanceof ToolReference ||
+  value instanceof IntrinsicReference ||
+  value instanceof GlobalNamespace ||
+  value instanceof GlobalMethodReference ||
+  value instanceof PromiseNamespace ||
+  value instanceof PromiseMethodReference ||
+  value instanceof PromiseInstanceMethodReference ||
+  value instanceof SandboxPromise ||
+  value instanceof CoercionFunction ||
+  value instanceof UriFunction ||
+  value instanceof SearchFunction ||
+  value instanceof PromiseCapabilityFunction ||
+  value instanceof ErrorConstructorReference ||
+  isSandboxValue(value)
+
+export const containsRuntimeReference = (value: unknown, seen = new Set<object>()): boolean => {
+  if (isRuntimeReference(value)) return true
+  if (value === null || typeof value !== "object") return false
+  if (seen.has(value)) return false
+  seen.add(value)
+  const contains = Array.isArray(value)
+    ? value.some((item) => containsRuntimeReference(item, seen))
+    : Object.values(value).some((item) => containsRuntimeReference(item, seen))
+  seen.delete(value)
+  return contains
+}
+
+// Sandbox values are data here, not opaque interpreter references.
+export const containsOpaqueReference = (value: unknown, seen = new Set<object>()): boolean => {
+  if (isSandboxValue(value)) return false
+  if (isRuntimeReference(value)) return true
+  if (value === null || typeof value !== "object") return false
+  if (seen.has(value)) return false
+  seen.add(value)
+  const contains = Array.isArray(value)
+    ? value.some((item) => containsOpaqueReference(item, seen))
+    : Object.values(value).some((item) => containsOpaqueReference(item, seen))
+  seen.delete(value)
+  return contains
+}
+
+// Reject cycles before mutation so later boundary walks remain safe.
+export const rejectCircularInsertion = (
+  container: object,
+  value: unknown,
+  label: string,
+  node: AstNode,
+  seen = new Set<object>(),
+): void => {
+  if (value === container)
+    throw new InterpreterRuntimeError(`${label} contains a circular value.`, node, "InvalidDataValue")
+  if (value === null || typeof value !== "object" || isRuntimeReference(value) || seen.has(value)) return
+  seen.add(value)
+  const items = Array.isArray(value) ? value : Object.values(value)
+  for (const item of items) rejectCircularInsertion(container, item, label, node, seen)
+  seen.delete(value)
+}
+
+export const typeofValue = (value: unknown): string => {
+  if (
+    value instanceof CodeModeFunction ||
+    value instanceof CoercionFunction ||
+    value instanceof IntrinsicReference ||
+    value instanceof GlobalMethodReference ||
+    value instanceof PromiseMethodReference ||
+    value instanceof PromiseInstanceMethodReference ||
+    value instanceof PromiseNamespace ||
+    value instanceof PromiseCapabilityFunction ||
+    value instanceof ErrorConstructorReference
+  )
+    return "function"
+  if (value instanceof UriFunction || value instanceof SearchFunction) return "function"
+  if (value instanceof ToolReference) return value.path.length > 0 ? "function" : "object"
+  if (value instanceof GlobalNamespace) {
+    return value.name === "Math" || value.name === "JSON" || value.name === "console" ? "object" : "function"
+  }
+  return typeof value
+}

packages/codemode/src/interpreter/scope.ts

@@ -0,0 +1,84 @@
+import { type AstNode, type Binding, InterpreterRuntimeError } from "./model.js"
+
+export class ScopeStack {
+  private readonly scopes: Array<Map<string, Binding>>
+
+  constructor(scopes: Array<Map<string, Binding>>) {
+    this.scopes = scopes
+  }
+
+  declare(name: string, value: unknown, mutable: boolean, node: AstNode): void {
+    const scope = this.current()
+
+    const existing = scope.get(name)
+    if (existing && existing.initialized !== false) {
+      throw new InterpreterRuntimeError(`Identifier '${name}' has already been declared.`, node)
+    }
+
+    scope.set(name, { mutable, value, initialized: true })
+  }
+
+  get(name: string, node: AstNode): unknown {
+    const binding = this.resolve(name)
+
+    if (!binding) {
+      throw new InterpreterRuntimeError(`Unknown identifier '${name}'.`, node).as("ReferenceError")
+    }
+
+    if (binding.initialized === false) {
+      throw new InterpreterRuntimeError(`Cannot access '${name}' before initialization.`, node).as("ReferenceError")
+    }
+
+    return binding.value
+  }
+
+  set(name: string, value: unknown, node: AstNode): unknown {
+    const binding = this.resolve(name)
+
+    if (!binding) {
+      throw new InterpreterRuntimeError(`Unknown identifier '${name}'.`, node).as("ReferenceError")
+    }
+
+    if (!binding.mutable) {
+      throw new InterpreterRuntimeError(`Cannot assign to constant '${name}'.`, node).as("TypeError")
+    }
+
+    binding.value = value
+    return value
+  }
+
+  resolve(name: string): Binding | undefined {
+    for (let index = this.scopes.length - 1; index >= 0; index -= 1) {
+      const scope = this.scopes[index]
+      const binding = scope?.get(name)
+
+      if (binding) {
+        return binding
+      }
+    }
+
+    return undefined
+  }
+
+  current(): Map<string, Binding> {
+    const scope = this.scopes[this.scopes.length - 1]
+
+    if (!scope) {
+      throw new InterpreterRuntimeError("Interpreter scope stack is empty.")
+    }
+
+    return scope
+  }
+
+  push(scope: Map<string, Binding> = new Map()): void {
+    this.scopes.push(scope)
+  }
+
+  pop(): void {
+    this.scopes.pop()
+  }
+
+  capture(): Array<Map<string, Binding>> {
+    return this.scopes.slice()
+  }
+}