import { parse } from "acorn"

import { Cause, Effect, Exit, Fiber, Semaphore } from "effect"

import { DiagnosticCategory, ModuleKind, ScriptTarget, flattenDiagnosticMessageText, transpileModule } from "typescript"

import {

copyIn,

copyOut,

isBlockedMember,

ToolReference,

ToolRuntime,

ToolRuntimeError,

type HostTools,

type SafeObject,

type Services,

} from "../tool-runtime.js"

import { ToolError } from "../tool-error.js"

import type {

DataValue,

Diagnostic,

DiagnosticKind,

ExecuteOptions,

ResolvedExecutionLimits,

Result,

} from "../codemode.js"

import {

type AstNode,

asNode,

type Binding,

CodeModeFunction,

CoercionFunction,

ComputedValue,

ErrorConstructorReference,

GlobalMethodReference,

GlobalNamespace,

type GlobalNamespaceName,

formatLocation,

getArray,

getBoolean,

getNode,

getOptionalNode,

getString,

IntrinsicReference,

InterpreterRuntimeError,

isRecord,

type MemberReference,

OptionalShortCircuit,

PromiseMethodReference,

type PromiseMethodName,

PromiseNamespace,

ProgramThrow,

type ProgramNode,

type StatementResult,

sourceLocation,

supportedSyntaxMessage,

unsupportedSyntax,

UriFunction,

} from "./model.js"

import { arrayMethods, mapMethods, setMethods, spreadItems } from "../stdlib/collections.js"

import { consoleMethods, MAX_CONSOLE_DEPTH } from "../stdlib/console.js"

import { dateMethods, dateStatics, invokeDateMethod, invokeDateStatic } from "../stdlib/date.js"

import { invokeJsonMethod } from "../stdlib/json.js"

import { invokeMathMethod, mathConstants } from "../stdlib/math.js"

import {

invokeNumberMethod,

invokeNumberStatic,

numberConstants,

numberMethods,

numberStatics,

} from "../stdlib/number.js"

import { invokeObjectMethod } from "../stdlib/object.js"

import { promiseStatics, TOOL_CALL_CONCURRENCY } from "../stdlib/promise.js"

import {

escapeRegexHint,

invokeRegExpMethod,

matchToValue,

regexpMethods,

regexpProperties,

regexFailureReason,

toHostRegex,

} from "../stdlib/regexp.js"

import { invokeStringStatic, stringMethods, stringStatics } from "../stdlib/string.js"

import {

urlMethods,

urlProperties,

urlSearchParamsMethods,

urlStatics,

urlWritableProperties,

invokeUriFunction,

invokeURLMethod,

invokeURLStatic,

uriArgument,

urlArgument,

} from "../stdlib/url.js"

import {

boundedData,

coerceToNumber,

coerceToString,

compoundOperators,

createErrorValue,

errorBrandName,

errorConstructors,

invokeCoercion,

valueConstructors,

} from "../stdlib/value.js"

import {

isSandboxValue,

SandboxDate,

SandboxMap,

SandboxPromise,

SandboxRegExp,

SandboxSet,

SandboxURL,

SandboxURLSearchParams,

} from "../values.js"

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 publicErrorMessage = (message: string): string =>

message.replace(/\/(?:Users|home|private|tmp|var\/folders)\/[^\s"'`]+/g, "<redacted-path>")

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: publicErrorMessage(error.message) }

}

if (error instanceof ProgramThrow) {

const value = error.value

let message: string

if (containsRuntimeReference(value)) {

// A thrown tool/function reference must not leak its internal structure.

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: publicErrorMessage(error.message),

}

}

// A non-Error thrown by a host tool (raw string / number / Symbol) still routes through

// path redaction so filesystem paths can never leak through the catch-all branch.

return {

kind: "ExecutionFailure",

message: publicErrorMessage(String(error)),

}

}

// Shared by catch bindings, Promise.allSettled rejection reasons, and Promise.race losers.

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)

}

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 SandboxPromise ||

value instanceof CoercionFunction ||

value instanceof UriFunction ||

value instanceof ErrorConstructorReference ||

isSandboxValue(value)

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

}

// Like containsRuntimeReference, but sandbox standard-library values count as data:

// operators and switch treat them as ordinary object operands (identity equality, ToPrimitive

// coercion) rather than rejecting them as opaque interpreter machinery.

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

}

// `typeof` never throws in JS; map every interpreter value to its JS-visible category.

// A SandboxPromise falls through to the final `typeof value` and reports "object", exactly

// like a real JS promise.

const typeofValue = (value: unknown): string => {

if (

value instanceof CodeModeFunction ||

value instanceof CoercionFunction ||

value instanceof IntrinsicReference ||

value instanceof GlobalMethodReference ||

value instanceof PromiseMethodReference ||

value instanceof PromiseNamespace ||

value instanceof ErrorConstructorReference

)

return "function"

if (value instanceof UriFunction) 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

}

// `x instanceof C` against the constructors CodeMode knows. Like `typeof`, it observes any

// left-hand value (opaque references included) without coercing it. Error checks use the

// error brand: `instanceof Error` accepts every branded error; a specific error type matches

// its own brand only (as in JS, where TypeError instances are also Error instances).

const instanceofValue = (lhs: unknown, rhs: unknown, node: AstNode): boolean => {

if (rhs instanceof ErrorConstructorReference) {

const brand = errorBrandName(lhs)

return brand !== undefined && (rhs.name === "Error" || brand === rhs.name)

}

if (rhs instanceof GlobalNamespace) {

switch (rhs.name) {

case "Date":

return lhs instanceof SandboxDate

case "RegExp":

return lhs instanceof SandboxRegExp

case "Map":

return lhs instanceof SandboxMap

case "Set":

return lhs instanceof SandboxSet

case "URL":

return lhs instanceof SandboxURL

case "URLSearchParams":

return lhs instanceof SandboxURLSearchParams

case "Array":

return Array.isArray(lhs)

case "Object":

return lhs !== null && (typeof lhs === "object" || typeofValue(lhs) === "function")

}

}

if (rhs instanceof PromiseNamespace) return lhs instanceof SandboxPromise

// Number/String/Boolean wrap primitives in JS; no boxed values exist in CodeMode, so

// `x instanceof Number` is always false - exactly what it is for primitives in JS.

if (rhs instanceof CoercionFunction && (rhs.name === "Number" || rhs.name === "String" || rhs.name === "Boolean")) {

return false

}

throw new InterpreterRuntimeError(

"The right-hand side of 'instanceof' must be a constructor CodeMode knows: Error (or a specific error type like TypeError), Date, RegExp, Map, Set, URL, URLSearchParams, Array, Object, or Promise.",

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

// trimLeft/trimRight are the legacy aliases of trimStart/trimEnd, kept because models write them.

case "trimStart":

case "trimLeft":

result = value.trimStart()

break

case "trimEnd":

case "trimRight":

result = value.trimEnd()

break

// Locale/options arguments are ignored: comparison runs with the host default locale, and

// the common use is a sort comparator where any consistent order works.

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] as SandboxRegExp).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] as SandboxRegExp).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

// A global match is a plain array of matched strings; a non-global match carries

// index/groups own properties, so bypass the copying data checkpoint to keep them.

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,

)

}

// Materialized as an array (not an iterator); each entry is a match array with

// index/groups own properties. Match count is bounded by the subject length.

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 "substr":

result = value.substr(optNum(0) ?? 0, optNum(1))

break

// JS charCodeAt returns NaN out of range; NaN flows as an ordinary in-sandbox value

// (normalized to null only at the data boundary - see copyOut), so return it as-is.

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],

)

}

// Map/Set materialize directly (the data checkpoint would serialize them to {}).

if (args[0] instanceof SandboxMap)

return Array.from((args[0] as SandboxMap).map.entries(), ([key, item]) => [key, item])

if (args[0] instanceof SandboxSet) return Array.from((args[0] as SandboxSet).set.values())

if (args[0] instanceof SandboxURLSearchParams) {

return Array.from(args[0].params.entries(), ([key, value]) => [key, value])

}

const source = boundedData(args[0], "Array.from input")

if (typeof source === "string") return Array.from(source)

if (Array.isArray(source)) return [...source]

if (

source !== null &&

typeof source === "object" &&

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)

}

default:

throw new InterpreterRuntimeError(`Array.${name} is not available in CodeMode.`, node)

}

}

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") {

if (!dateStatics.has(ref.name))

throw new InterpreterRuntimeError(`Date.${ref.name} is not available in CodeMode.`, node)

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)

}

// Every identifier a parameter pattern binds, used to seed TDZ slots before defaults run.

const collectPatternNames = (pattern: AstNode, out: Array<string> = []): Array<string> => {

switch (pattern.type) {

case "Identifier":

out.push(getString(pattern, "name"))

break

case "AssignmentPattern":

collectPatternNames(getNode(pattern, "left"), out)

break

case "RestElement":

collectPatternNames(getNode(pattern, "argument"), out)

break

case "ArrayPattern":

for (const element of getArray(pattern, "elements")) {

if (element !== null) collectPatternNames(asNode(element, "elements"), out)

}

break

case "ObjectPattern":

for (const property of getArray(pattern, "properties")) {

const prop = asNode(property, "properties")

collectPatternNames(prop.type === "RestElement" ? getNode(prop, "argument") : getNode(prop, "value"), out)

}

break

}

return out

}

class Interpreter<R> {

private scopes: Array<Map<string, Binding>>

private readonly invokeTool: (path: ReadonlyArray<string>, args: Array<unknown>) => Effect.Effect<unknown, unknown, R>

// Enumerable namespace/tool names at a node of the host tool tree, threaded from

// ToolRuntime.make like invokeTool: the interpreter never holds the tree itself.

private readonly toolKeys: (path: ReadonlyArray<string>) => ReadonlyArray<string>

private readonly logs: Array<string>

private lastValue: unknown

// Caps how many eagerly forked tool calls run at once (the parallel-call concurrency cap).

private readonly callPermits: Semaphore.Semaphore

// Fiber-backed promises whose settlement no program construct has observed yet. Successful

// program completion drains these (like a runtime waiting on in-flight work at exit) and

// surfaces a never-awaited failure as an unhandled-rejection diagnostic.

private readonly pendingSettlements = new Set<SandboxPromise>()

constructor(

invokeTool: (path: ReadonlyArray<string>, args: Array<unknown>) => Effect.Effect<unknown, unknown, R>,

toolKeys: (path: ReadonlyArray<string>) => ReadonlyArray<string>,

logs: Array<string> = [],

) {

const globalScope = new Map<string, Binding>()

this.scopes = [globalScope]

this.invokeTool = invokeTool

this.toolKeys = toolKeys

this.logs = logs

this.lastValue = undefined

this.callPermits = Semaphore.makeUnsafe(TOOL_CALL_CONCURRENCY)

globalScope.set("tools", { mutable: false, value: new ToolReference([]) })

globalScope.set("Promise", { mutable: false, value: new PromiseNamespace() })

globalScope.set("undefined", { mutable: false, value: undefined })

globalScope.set("Object", { mutable: false, value: new GlobalNamespace("Object") })

globalScope.set("Math", { mutable: false, value: new GlobalNamespace("Math") })

globalScope.set("JSON", { mutable: false, value: new GlobalNamespace("JSON") })

globalScope.set("Number", { mutable: false, value: new CoercionFunction("Number") })

globalScope.set("String", { mutable: false, value: new CoercionFunction("String") })

globalScope.set("Boolean", { mutable: false, value: new CoercionFunction("Boolean") })

globalScope.set("Array", { mutable: false, value: new GlobalNamespace("Array") })

globalScope.set("console", { mutable: false, value: new GlobalNamespace("console") })

globalScope.set("parseInt", { mutable: false, value: new CoercionFunction("parseInt") })

globalScope.set("parseFloat", { mutable: false, value: new CoercionFunction("parseFloat") })

globalScope.set("Date", { mutable: false, value: new GlobalNamespace("Date") })

globalScope.set("RegExp", { mutable: false, value: new GlobalNamespace("RegExp") })

globalScope.set("Map", { mutable: false, value: new GlobalNamespace("Map") })

globalScope.set("Set", { mutable: false, value: new GlobalNamespace("Set") })

globalScope.set("URL", { mutable: false, value: new GlobalNamespace("URL") })

globalScope.set("URLSearchParams", { mutable: false, value: new GlobalNamespace("URLSearchParams") })

globalScope.set("encodeURI", { mutable: false, value: new UriFunction("encodeURI") })

globalScope.set("encodeURIComponent", { mutable: false, value: new UriFunction("encodeURIComponent") })

globalScope.set("decodeURI", { mutable: false, value: new UriFunction("decodeURI") })

globalScope.set("decodeURIComponent", { mutable: false, value: new UriFunction("decodeURIComponent") })

// Error constructors are real values, so `x instanceof Error` works and `Error("msg")`

// (with or without `new`) constructs a branded { name, message } error object.

for (const name of errorConstructors) {

globalScope.set(name, { mutable: false, value: new ErrorConstructorReference(name) })

}

// NaN/Infinity flow as ordinary in-sandbox values (normalized to null only at the data

// boundary - see copyOut), so their global bindings must exist too, e.g. `reduce(max, -Infinity)`.

globalScope.set("NaN", { mutable: false, value: NaN })

globalScope.set("Infinity", { mutable: false, value: Infinity })

}

run(program: ProgramNode): Effect.Effect<unknown, unknown, R> {

const self = this

// Run the program body in its own module scope on top of the builtin global scope, so

// top-level declarations (`let undefined = 5`, `const Object = ...`) shadow builtins like

// JS module scope, instead of colliding with the seeded globals.

this.pushScope()

return Effect.gen(function* () {

self.hoistFunctions(program.body)

let value: unknown = undefined

let returned = false

for (const statement of program.body) {

const result = yield* self.evaluateStatement(statement)

if (result.kind === "return") {

value = result.value

returned = true

break

}

if (result.kind === "break" || result.kind === "continue") {

throw new InterpreterRuntimeError(`Unexpected '${result.kind}' outside of a loop.`, statement)

}

if (result.kind === "value") {

self.lastValue = result.value

}

}

if (!returned) value = self.lastValue

// The program body runs inside an implicit async function, so a returned promise

// resolves before crossing the data boundary - `return tools.ns.tool(...)` works

// without an explicit await, exactly as in JS.

if (value instanceof SandboxPromise) value = yield* self.settlePromise(value)

yield* self.drainPendingSettlements()

return value

}).pipe(Effect.ensuring(Effect.sync(() => self.popScope())))

}

// Awaits every fiber-backed promise the program abandoned (fire-and-forget tool calls), so

// their work completes before the execution ends - mirroring a JS runtime waiting on

// in-flight I/O at exit. A failure nobody could have handled becomes an unhandled-rejection

// diagnostic (interrupted calls, e.g. Promise.race losers, are ignored).

private drainPendingSettlements(): Effect.Effect<void, unknown, never> {

const self = this

return Effect.gen(function* () {

for (const promise of [...self.pendingSettlements]) {

const exit = yield* self.observePromise(promise)

if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause)) continue

const failure = normalizeError(Cause.squash(exit.cause))

throw new InterpreterRuntimeError(

`Unhandled rejection from an un-awaited tool call: ${failure.message}`,

undefined,

failure.kind,

["Await tool calls - `const result = await tools.ns.tool(...)` - so failures can be caught and handled."],

)

}

})

}

// Eagerly starts a tool call on a supervised child fiber (so the execution timeout and

// scope teardown interrupt it) gated by the concurrency semaphore, and wraps the fiber in a

// first-class promise value. `startImmediately` makes the runtime admit the call - charging

// the tool-call budget and firing onToolCallStart - at the call site, before any await.

private createToolCallPromise(

path: ReadonlyArray<string>,

args: Array<unknown>,

): Effect.Effect<SandboxPromise, never, R> {

const self = this

return Effect.map(

Effect.forkChild(this.callPermits.withPermit(Effect.suspend(() => self.invokeTool(path, args))), {

startImmediately: true,

}),

(fiber) => {

const promise = new SandboxPromise(fiber)

self.pendingSettlements.add(promise)

return promise

},

)

}

// The promise's settlement as an Exit, marking it observed for unhandled-rejection tracking.

// Fiber settlement is idempotent, so observing the same promise repeatedly (await twice,

// Promise.all([p, p])) never re-runs the underlying call.

private observePromise(promise: SandboxPromise): Effect.Effect<Exit.Exit<unknown, unknown>> {

this.pendingSettlements.delete(promise)

return promise.fiber !== undefined ? Fiber.await(promise.fiber) : Effect.exit(promise.immediate ?? Effect.void)

}

// `await promise`: succeed with the fulfilled value or re-raise the failure so try/catch

// observes it exactly like a synchronous throw at the await site.

private settlePromise(promise: SandboxPromise, node?: AstNode): Effect.Effect<unknown, unknown, never> {

const self = this

return Effect.flatMap(this.observePromise(promise), (exit) => self.unwrapPromiseExit(promise, exit, node))

}

private unwrapPromiseExit(

promise: SandboxPromise | undefined,

exit: Exit.Exit<unknown, unknown>,

node?: AstNode,

): Effect.Effect<unknown, unknown> {

if (Exit.isSuccess(exit)) return Effect.succeed(exit.value)

// A call Promise.race interrupted after losing settles as a catchable program failure;

// any other interruption is execution teardown (timeout/host) and must keep propagating

// as interruption rather than becoming program-visible data.

if (promise?.interrupted === true && Cause.hasInterruptsOnly(exit.cause)) {

return Effect.fail(

new InterpreterRuntimeError(

"This tool call was interrupted because another value settled a Promise.race first.",

node,

),

)

}

return Effect.failCause(exit.cause)

}

private evaluateStatement(node: AstNode): Effect.Effect<StatementResult, unknown, R> {

switch (node.type) {

case "ExpressionStatement":

return Effect.map(this.evaluateExpression(getNode(node, "expression")), (value) => ({ kind: "value", value }))

case "VariableDeclaration":

return Effect.map(this.evaluateVariableDeclaration(node), () => ({ kind: "none" }))

case "ReturnStatement": {

const argumentNode = getOptionalNode(node, "argument")

return argumentNode

? Effect.map(this.evaluateExpression(argumentNode), (value) => ({ kind: "return", value }))

: Effect.succeed({ kind: "return", value: undefined })

}

case "BlockStatement":

return this.evaluateBlock(node)

case "IfStatement":

return this.evaluateIfStatement(node)

case "SwitchStatement":

return this.evaluateSwitchStatement(node)

case "WhileStatement":

return this.evaluateWhileStatement(node)

case "DoWhileStatement":

return this.evaluateDoWhileStatement(node)

case "ForStatement":

return this.evaluateForStatement(node)

case "ForOfStatement":

return this.evaluateForOfStatement(node)

case "ForInStatement":

return this.evaluateForInStatement(node)

case "BreakStatement":

return Effect.succeed(this.evaluateBreakStatement(node))

case "ContinueStatement":

return Effect.succeed(this.evaluateContinueStatement(node))

case "ThrowStatement":

return this.evaluateThrowStatement(node)

case "TryStatement":

return this.evaluateTryStatement(node)

case "EmptyStatement":

return Effect.succeed({ kind: "none" })

case "FunctionDeclaration":

return Effect.succeed({ kind: "none" }) // bound ahead of time by hoistFunctions

default:

throw unsupportedSyntax(node.type, node)

}

}

private evaluateBlock(node: AstNode): Effect.Effect<StatementResult, unknown, R> {

this.pushScope()

const self = this

return Effect.gen(function* () {

const body = getArray(node, "body")

self.hoistFunctions(body)

for (const statementValue of body) {

const statement = asNode(statementValue, "body")

const result = yield* self.evaluateStatement(statement)

if (result.kind === "value") {

self.lastValue = result.value

continue

}

if (result.kind !== "none") {

return result

}

}

return { kind: "none" } satisfies StatementResult

}).pipe(Effect.ensuring(Effect.sync(() => self.popScope())))

}

private createFunction(node: AstNode): CodeModeFunction {

if (node.generator === true) {

throw new InterpreterRuntimeError(

"Generator functions are not supported in CodeMode.",

node,

"UnsupportedSyntax",

[supportedSyntaxMessage],

)

}

return new CodeModeFunction(

getArray(node, "params").map((parameter, index) => asNode(parameter, `params[${index}]`)),

getNode(node, "body"),

this.scopes.slice(),

)

}

// Function declarations are hoisted: bound in their scope before the body runs, so a

// program can call a helper defined further down (matching JavaScript).

private hoistFunctions(statements: Array<unknown>): void {

for (const statementValue of statements) {

if (!isRecord(statementValue) || statementValue.type !== "FunctionDeclaration") continue

const node = statementValue as AstNode

this.declare(getString(getNode(node, "id"), "name"), this.createFunction(node), true, node)

}

}

private evaluateIfStatement(node: AstNode): Effect.Effect<StatementResult, unknown, R> {

const testNode = getNode(node, "test")

const consequentNode = getNode(node, "consequent")

const alternateNode = getOptionalNode(node, "alternate")

return Effect.flatMap(this.evaluateExpression(testNode), (test) =>

test

? this.evaluateStatement(consequentNode)

: alternateNode

? this.evaluateStatement(alternateNode)

: Effect.succeed({ kind: "none" }),

)

}

private evaluateSwitchStatement(node: AstNode): Effect.Effect<StatementResult, unknown, R> {

const self = this

this.pushScope()

return Effect.gen(function* () {

const discriminant = yield* self.evaluateExpression(getNode(node, "discriminant"))

if (containsOpaqueReference(discriminant)) {

throw new InterpreterRuntimeError(

"Switch discriminants must be data values in CodeMode.",

node,

"InvalidDataValue",

)

}

const cases = getArray(node, "cases").map((value, index) => asNode(value, `cases[${index}]`))

let defaultIndex: number | undefined

let selected: number | undefined

for (const [index, branch] of cases.entries()) {

const test = getOptionalNode(branch, "test")

if (!test) {

defaultIndex = index

continue

}

const candidate = yield* self.evaluateExpression(test)

if (containsOpaqueReference(candidate)) {

throw new InterpreterRuntimeError(

"Switch case values must be data values in CodeMode.",

test,

"InvalidDataValue",

)

}

if (candidate === discriminant) {

selected = index

break

}

}

const start = selected ?? defaultIndex

if (start === undefined) return { kind: "none" } satisfies StatementResult

for (let index = start; index < cases.length; index += 1) {

for (const statementValue of getArray(cases[index]!, "consequent")) {

const result = yield* self.evaluateStatement(asNode(statementValue, "consequent"))

if (result.kind === "break") return { kind: "none" } satisfies StatementResult

if (result.kind === "return" || result.kind === "continue") return result

if (result.kind === "value") self.lastValue = result.value

}

}

return { kind: "none" } satisfies StatementResult

}).pipe(Effect.ensuring(Effect.sync(() => self.popScope())))

}

private evaluateWhileStatement(node: AstNode): Effect.Effect<StatementResult, unknown, R> {

const testNode = getNode(node, "test")

const bodyNode = getNode(node, "body")

const self = this

return Effect.gen(function* () {

while (yield* self.evaluateExpression(testNode)) {

const result = yield* self.evaluateStatement(bodyNode)

if (result.kind === "continue") {

continue

}

if (result.kind === "break") {

return { kind: "none" } satisfies StatementResult

}

if (result.kind === "return") {

return result

}

if (result.kind === "value") {

self.lastValue = result.value

}

}

return { kind: "none" } satisfies StatementResult

})

}

private evaluateDoWhileStatement(node: AstNode): Effect.Effect<StatementResult, unknown, R> {

const bodyNode = getNode(node, "body")

const testNode = getNode(node, "test")

const self = this

return Effect.gen(function* () {

do {

const result = yield* self.evaluateStatement(bodyNode)

if (result.kind === "continue") {

continue

}

if (result.kind === "break") {

return { kind: "none" } satisfies StatementResult

}

if (result.kind === "return") {

return result

}

if (result.kind === "value") {

self.lastValue = result.value

}

} while (yield* self.evaluateExpression(testNode))

return { kind: "none" } satisfies StatementResult

})

}

private evaluateForStatement(node: AstNode): Effect.Effect<StatementResult, unknown, R> {

this.pushScope()

const self = this

return Effect.gen(function* () {

const initNode = getOptionalNode(node, "init")