import { parse } from "acorn"

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

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

import {

copyIn,

copyOut,

isBlockedMember,

ToolReference,

ToolRuntime,

ToolRuntimeError,

type HostTools,

type SafeObject,

type ToolCall,

type ToolDescription,

type Services,

} from "./tool-runtime.js"

import type { Definition } from "./tool.js"

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

import { isSandboxValue, SandboxDate, SandboxMap, SandboxPromise, SandboxRegExp, SandboxSet } from "./values.js"

/** A tool call admitted during an execution. */

export type { ToolCall, ToolCallStarted, ToolDescription } from "./tool-runtime.js"

export { ToolError, toolError } from "./tool-error.js"

/** Resource budgets enforced independently during each CodeMode program execution. */

export type ExecutionLimits = {

/** Maximum wall-clock execution time in milliseconds. No default: absent means no timeout. */

readonly timeoutMs?: number

/** Maximum number of tool calls admitted by the runtime. No default: absent means unlimited. */

readonly maxToolCalls?: number

/**

* Maximum UTF-8 bytes of model-facing output: the serialized result value plus captured

* logs. Excess output is truncated with an explanatory marker instead of failing. No

* default: absent means no truncation (for hosts with their own output bounding).

*/

readonly maxOutputBytes?: number

}

/** Controls how much of the tool catalog is inlined in agent instructions. */

export type DiscoveryOptions = {

/**

* Estimated-token budget (chars/4, default 2000) for inlined full tool signatures in agent

* instructions. Signatures that fit are inlined round-robin across namespaces; every

* namespace is always listed with its tool count regardless of budget, and

* `tools.$codemode.search` is always registered.

*/

readonly maxInlineCatalogTokens?: number

}

type ToolTree<R = never> = {

readonly [name: string]: Definition<R> | ToolTree<R>

}

type ResolvedExecutionLimits = {

/** Undefined means no timeout. */

readonly timeoutMs: number | undefined

/** Undefined means unlimited tool calls. */

readonly maxToolCalls: number | undefined

/** Undefined means no output truncation. */

readonly maxOutputBytes: number | undefined

}

/** Options for one CodeMode execution. */

export type ExecuteOptions<Tools extends Record<string, unknown> = {}> = {

/** Source for one program in the supported JavaScript subset. */

code: string

/** Explicit tool tree exposed to the program as `tools`. */

tools?: Tools & ToolTree<Services<Tools>>

/** Per-execution overrides for the default resource limits. */

limits?: ExecutionLimits

/** Observes decoded tool input immediately before tool execution. */

onToolCallStart?: (call: ToolRuntime.ToolCallStarted) => Effect.Effect<void, never, Services<Tools>>

/** Observes each admitted tool call as it settles, with outcome and duration. */

onToolCallEnd?: (call: ToolRuntime.ToolCallEnded) => Effect.Effect<void, never, Services<Tools>>

}

/** A normalized program diagnostic safe to return across an agent tool boundary. */

export type Diagnostic = {

readonly kind: DiagnosticKind

readonly message: string

readonly location?: { readonly line: number; readonly column: number }

readonly suggestions?: ReadonlyArray<string>

}

/** A JSON value that can cross the confined interpreter boundary. */

export type DataValue = Schema.Json

/** Successful execution after the result has crossed the plain-data boundary. */

export type ExecuteSuccess = {

readonly ok: true

readonly value: DataValue

readonly logs?: ReadonlyArray<string>

/** Present when the value or logs were truncated to fit `maxOutputBytes`. */

readonly truncated?: boolean

readonly toolCalls: ReadonlyArray<ToolCall>

}

/** Failed execution with calls admitted before the diagnostic was produced. */

export type ExecuteFailure = {

readonly ok: false

readonly error: Diagnostic

readonly logs?: ReadonlyArray<string>

/** Present when the logs were truncated to fit `maxOutputBytes`. */

readonly truncated?: boolean

readonly toolCalls: ReadonlyArray<ToolCall>

}

/** Result of executing a CodeMode program. Program failures are data, not Effect failures. */

export type ExecuteResult = ExecuteSuccess | ExecuteFailure

/** Reusable CodeMode configuration shared by `execute` and `agentTool`. */

export type CodeModeOptions<Tools extends Record<string, unknown> = {}> = Omit<ExecuteOptions<Tools>, "code"> & {

/** Progressive-disclosure configuration for the agent-facing tool catalog. */

readonly discovery?: DiscoveryOptions

}

/** Input schema for the single agent-facing tool produced by `runtime.agentTool()`. */

export const ExecuteInputSchema = Schema.Struct({ code: Schema.String })

const DiagnosticKindSchema = Schema.Literals([

"ParseError",

"UnsupportedSyntax",

"UnknownTool",

"InvalidToolInput",

"InvalidToolOutput",

"InvalidDataValue",

"ToolCallLimitExceeded",

"TimeoutExceeded",

"ToolFailure",

"ExecutionFailure",

])

/** Structured success or diagnostic result schema returned by CodeMode execution. */

export const ExecuteResultSchema = Schema.Union([

Schema.Struct({

ok: Schema.Literal(true),

value: Schema.Json,

logs: Schema.optionalKey(Schema.Array(Schema.String)),

truncated: Schema.optionalKey(Schema.Boolean),

toolCalls: Schema.Array(Schema.Struct({ name: Schema.String })),

}),

Schema.Struct({

ok: Schema.Literal(false),

error: Schema.Struct({

kind: DiagnosticKindSchema,

message: Schema.String,

location: Schema.optionalKey(Schema.Struct({ line: Schema.Number, column: Schema.Number })),

suggestions: Schema.optionalKey(Schema.Array(Schema.String)),

}),

logs: Schema.optionalKey(Schema.Array(Schema.String)),

truncated: Schema.optionalKey(Schema.Boolean),

toolCalls: Schema.Array(Schema.Struct({ name: Schema.String })),

}),

])

/** Agent-facing projection of a configured CodeMode runtime. */

export type AgentToolDefinition<R = never> = {

readonly name: "code"

readonly description: string

readonly input: typeof ExecuteInputSchema

readonly output: typeof ExecuteResultSchema

readonly execute: (input: { readonly code: string }) => Effect.Effect<ExecuteResult, never, R>

}

/** Reusable confined runtime over one explicit tool tree. */

export type CodeModeRuntime<R = never> = {

/** Lists schema-described tool paths provided by the host. */

readonly catalog: () => ReadonlyArray<ToolDescription>

/** Builds model-facing syntax guidance and visible tool signatures. */

readonly instructions: () => string

/** Projects the configured runtime as one agent-facing `code` tool. */

readonly agentTool: () => AgentToolDefinition<R>

/** Executes a program using this runtime's configured host tools. */

readonly execute: (code: string) => Effect.Effect<ExecuteResult, never, R>

}

type SourcePosition = {

line: number

column: number

}

type SourceLocation = {

start: SourcePosition

end: SourcePosition

}

type AstNode = {

type: string

loc?: SourceLocation

[key: string]: unknown

}

type ProgramNode = AstNode & {

type: "Program"

body: Array<AstNode>

}

type Binding = {

mutable: boolean

value: unknown

// Absent means initialized. `false` marks a parameter binding seeded into its scope but not

// yet bound, so a default that forward-references a later parameter sees a TDZ error (as in JS)

// rather than silently resolving to an outer binding of the same name.

initialized?: boolean

}

type StatementResult =

| { kind: "none" }

| { kind: "value"; value: unknown }

| { kind: "return"; value: unknown }

| { kind: "break" }

| { kind: "continue" }

type MemberReference = {

target: SafeObject | Array<unknown>

key: string | number

}

class CodeModeFunction {

constructor(

readonly parameters: ReadonlyArray<AstNode>,

readonly body: AstNode,

readonly capturedScopes: ReadonlyArray<Map<string, Binding>>,

) {}

}

class IntrinsicReference {

constructor(

readonly receiver: unknown,

readonly name: string,

) {}

}

class ComputedValue {

constructor(readonly value: unknown) {}

}

class PromiseNamespace {}

type PromiseMethodName = "all" | "allSettled" | "race" | "resolve" | "reject"

class PromiseMethodReference {

constructor(readonly name: PromiseMethodName) {}

}

// A built-in global namespace (`Object`, `Math`, `JSON`, `Array`, ...); members resolve to a

// GlobalMethodReference, except known constants (e.g. `Math.PI`) which resolve to a value.

type GlobalNamespaceName = "Object" | "Math" | "JSON" | "Array" | "console" | "Date" | "RegExp" | "Map" | "Set"

class GlobalNamespace {

constructor(readonly name: GlobalNamespaceName) {}

}

class GlobalMethodReference {

constructor(

readonly namespace: GlobalNamespaceName | "Number" | "String",

readonly name: string,

) {}

}

class CoercionFunction {

constructor(readonly name: "Number" | "String" | "Boolean" | "parseInt" | "parseFloat") {}

}

class ProgramThrow {

constructor(readonly value: unknown) {}

}

class ErrorConstructorReference {

constructor(readonly name: string) {}

}

// Non-enumerable so spread/copyOut preserve the plain `{ name, message }` data shape.

const ErrorBrand: unique symbol = Symbol("codemode.error")

const brandError = (errorValue: SafeObject, name: string): SafeObject => {

Object.defineProperty(errorValue, ErrorBrand, { value: name })

return errorValue

}

const createErrorValue = (name: string, message: string): SafeObject =>

brandError(Object.assign(Object.create(null) as SafeObject, { name, message }), name)

const errorBrandName = (value: unknown): string | undefined =>

value !== null && typeof value === "object"

? ((value as Record<PropertyKey, unknown>)[ErrorBrand] as string | undefined)

: undefined

/** Stable categories produced by program, schema, tool, and limit failures. */

export type DiagnosticKind =

| "ParseError"

| "UnsupportedSyntax"

| "UnknownTool"

| "InvalidToolInput"

| "InvalidToolOutput"

| "InvalidDataValue"

| "ToolCallLimitExceeded"

| "TimeoutExceeded"

| "ToolFailure"

| "ExecutionFailure"

const arrayMethods = new Set([

"map",

"filter",

"find",

"findIndex",

"findLast",

"findLastIndex",

"some",

"every",

"includes",

"join",

"reduce",

"reduceRight",

"flatMap",

"forEach",

"sort",

"toSorted",

"slice",

"concat",

"indexOf",

"lastIndexOf",

"at",

"flat",

"reverse",

"toReversed",

"with",

"push",

"pop",

"shift",

"unshift",

"splice",

"fill",

"copyWithin",

"keys",

"values",

"entries",

])

const mathConstants = new Set(["PI", "E", "LN2", "LN10", "LOG2E", "LOG10E", "SQRT2", "SQRT1_2"])

const numberMethods = new Set(["toFixed", "toPrecision", "toExponential", "toString"])

const stringMethods = new Set([

"toLowerCase",

"toUpperCase",

"trim",

"trimStart",

"trimEnd",

"trimLeft",

"trimRight",

"split",

"slice",

"substring",

"substr",

"includes",

"startsWith",

"endsWith",

"indexOf",

"lastIndexOf",

"replace",

"replaceAll",

"repeat",

"padStart",

"padEnd",

"charAt",

"charCodeAt",

"codePointAt",

"at",

"concat",

"toString",

"match",

"matchAll",

"search",

"localeCompare",

"normalize",

])

const numberConstants = new Set(["MAX_SAFE_INTEGER", "MIN_SAFE_INTEGER", "MAX_VALUE", "MIN_VALUE", "EPSILON"])

const numberStatics = new Set(["isInteger", "isFinite", "isNaN", "isSafeInteger", "parseInt", "parseFloat"])

const stringStatics = new Set(["fromCharCode", "fromCodePoint"])

const consoleMethods = new Set(["log", "info", "debug", "warn", "error", "dir", "table"])

const promiseStatics = new Set<PromiseMethodName>(["all", "allSettled", "race", "resolve", "reject"])

const errorConstructors = new Set([

"Error",

"TypeError",

"RangeError",

"SyntaxError",

"ReferenceError",

"EvalError",

"URIError",

])

const valueConstructors = new Set(["Date", "RegExp", "Map", "Set"])

const dateMethods = new Set([

"getTime",

"valueOf",

"toISOString",

"toJSON",

"toString",

"getFullYear",

"getMonth",

"getDate",

"getDay",

"getHours",

"getMinutes",

"getSeconds",

"getMilliseconds",

"getUTCFullYear",

"getUTCMonth",

"getUTCDate",

"getUTCDay",

"getUTCHours",

"getUTCMinutes",

"getUTCSeconds",

"getUTCMilliseconds",

"getTimezoneOffset",

])

const dateStatics = new Set(["now", "parse", "UTC"])

const regexpMethods = new Set(["test", "exec", "toString"])

// Read-only host regex fields surfaced as plain values.

const regexpProperties = new Set([

"source",

"flags",

"lastIndex",

"global",

"ignoreCase",

"multiline",

"sticky",

"unicode",

"dotAll",

])

const mapMethods = new Set(["get", "set", "has", "delete", "clear", "forEach", "keys", "values", "entries"])

const setMethods = new Set(["add", "has", "delete", "clear", "forEach", "keys", "values", "entries"])

const OptionalShortCircuit: unique symbol = Symbol("codemode.optional-short-circuit")

const supportedSyntaxMessage =

"Supported orchestration syntax: tools.* calls (they return promises - resolve them with await), data literals, destructuring, optional chaining, template literals, conditionals, switch, loops (incl. for...of and for...in over object/array/tools keys), arrow functions, spread, try/catch, array methods (map/filter/find/findIndex/some/every/reduce/flatMap/forEach/sort/slice/concat/indexOf/lastIndexOf/at/flat/reverse/includes/join), string methods (incl. match/matchAll/replace/split with regular expressions), Date/RegExp/Map/Set, Object/Math/JSON helpers, captured console.log/warn/error/dir/table, and Promise.all/allSettled/race/resolve/reject over arrays mixing promises and plain values for parallel tool calls (promise chaining with .then/.catch is not supported - use await with try/catch)."

const unsupportedSyntax = (kind: string, node: AstNode): InterpreterRuntimeError =>

new InterpreterRuntimeError(

`Syntax '${kind}' is not supported in CodeMode. ${supportedSyntaxMessage}`,

node,

"UnsupportedSyntax",

[supportedSyntaxMessage],

)

/** How many eagerly forked tool calls may run at once. Fixed; not a configurable knob. */

const TOOL_CALL_CONCURRENCY = 8

/** Console formatting recursion ceiling; deeper values render as "...". Fixed; not a knob. */

const MAX_CONSOLE_DEPTH = 32

const validateLimit = <Value extends number | undefined>(

name: keyof ExecutionLimits,

value: Value,

minimum: number,

): Value => {

if (value !== undefined && (!Number.isSafeInteger(value) || value < minimum)) {

throw new RangeError(`${name} must be a safe integer greater than or equal to ${minimum}.`)

}

return value

}

// No limit has a default: absent means no timeout / unlimited calls / no output truncation -

// budgets are host policy, not library policy. A host without its own output bounding should

// pass maxOutputBytes explicitly, or oversized results flood model context.

const resolveExecutionLimits = (limits?: ExecutionLimits): ResolvedExecutionLimits => ({

timeoutMs: validateLimit("timeoutMs", limits?.timeoutMs, 1),

maxToolCalls: validateLimit("maxToolCalls", limits?.maxToolCalls, 0),

maxOutputBytes: validateLimit("maxOutputBytes", limits?.maxOutputBytes, 0),

})

class InterpreterRuntimeError extends Error {

readonly node?: AstNode

/**

* The constructor name a program observes when it catches this failure (`caught.name`, and

* the brand behind `caught instanceof SyntaxError` etc.). "Error" unless the failing

* operation names a standard type in real JS - e.g. JSON.parse and invalid regex patterns

* throw SyntaxError, an unknown identifier is a ReferenceError, a bad normalize form is a

* RangeError.

*/

errorName: string = "Error"

constructor(

message: string,

node?: AstNode,

readonly kind: DiagnosticKind = "ExecutionFailure",

readonly suggestions?: ReadonlyArray<string>,

) {

super(message)

this.name = "InterpreterRuntimeError"

if (node) {

this.node = node

}

}

as(errorName: string): this {

this.errorName = errorName

return this

}

}

const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null

const asNode = (value: unknown, context: string): AstNode => {

if (!isRecord(value) || typeof value.type !== "string") {

throw new InterpreterRuntimeError(`Invalid AST node while reading ${context}.`)

}

return value as AstNode

}

const getArray = (node: AstNode, key: string): Array<unknown> => {

const value = node[key]

if (!Array.isArray(value)) {

throw new InterpreterRuntimeError(`Expected '${key}' to be an array.`, node)

}

return value

}

const getString = (node: AstNode, key: string): string => {

const value = node[key]

if (typeof value !== "string") {

throw new InterpreterRuntimeError(`Expected '${key}' to be a string.`, node)

}

return value

}

const getBoolean = (node: AstNode, key: string): boolean => {

const value = node[key]

if (typeof value !== "boolean") {

throw new InterpreterRuntimeError(`Expected '${key}' to be a boolean.`, node)

}

return value

}

const getOptionalNode = (node: AstNode, key: string): AstNode | undefined => {

const value = node[key]

if (value === undefined || value === null) {

return undefined

}

return asNode(value, key)

}

const getNode = (node: AstNode, key: string): AstNode => {

const value = node[key]

return asNode(value, key)

}

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 formatLocation = (node?: AstNode): string => {

if (!node || !node.loc) {

return ""

}

const location = sourceLocation(node)

return ` (line ${location.line}, col ${location.column})`

}

const sourceLocation = (node: AstNode): { readonly line: number; readonly column: number } => ({

line: Math.max(1, (node.loc?.start.line ?? 2) - 1),

column: Math.max(1, (node.loc?.start.column ?? 4) - 3),

})

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 boundedData = (value: unknown, label: string): unknown => copyIn(value, label, true)

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 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 value types (Date/RegExp/Map/Set) 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 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 "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, Array, Object, or Promise.",

node,

)

}

// A regex engine failure message without the engine's own "Invalid regular expression:"

// prefix, so composed diagnostics read as one sentence instead of stuttering the phrase.

const regexFailureReason = (error: unknown): string =>

(error instanceof Error ? error.message : String(error)).replace(/^Invalid regular expression:\s*/i, "")

const escapeRegexHint =

'To match special characters like ( ) [ ] { } + * ? . literally, escape them with a backslash (e.g. "\\\\(") or test for them with String.includes instead.'

// A string method's pattern argument as a host regex: a sandbox regex passes its own host

// instance through (so `g` lastIndex semantics follow the spec across calls); a string becomes

// a pattern, exactly as String.prototype.match/matchAll/search do (`extraFlags` adds matchAll's

// implicit `g`). Invalid patterns fail as catchable program errors that say what was wrong

// with the pattern and how to fix it.

const toHostRegex = (arg: unknown, method: string, node: AstNode, extraFlags = ""): RegExp => {

if (arg instanceof SandboxRegExp) return arg.regex

if (typeof arg === "string") {

try {

return new RegExp(arg, extraFlags)

} catch (error) {

throw new InterpreterRuntimeError(

`String.${method} received the string ${JSON.stringify(arg)}, which is not a valid regular expression pattern (${regexFailureReason(error)}). ${escapeRegexHint}`,

node,

).as("SyntaxError")

}

}

throw new InterpreterRuntimeError(

`String.${method} expects a regular expression (a /pattern/flags literal or new RegExp(...)) or a string pattern, not ${arg === null ? "null" : typeof arg}.`,

node,

)

}

// A host match result as a sandbox value: a plain array of the full match and captures, with

// `index` and named `groups` attached as own array properties (readable, and dropped at data

// boundaries exactly like JSON.stringify drops them in JS). `input` is omitted - it duplicates

// the whole subject string per match.

const matchToValue = (match: RegExpMatchArray): Array<unknown> => {

const result: Array<unknown> = Array.from(match, (group) => group)

if (match.index !== undefined) (result as Record<string, unknown> & Array<unknown>).index = match.index

if (match.groups) {

const groups: SafeObject = Object.create(null) as SafeObject

for (const [key, group] of Object.entries(match.groups)) {

if (!isBlockedMember(key)) groups[key] = group

}

;(result as Record<string, unknown> & Array<unknown>).groups = groups

}

return result

}

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 CodeModeFunction || args[1] instanceof CodeModeFunction) {

throw new InterpreterRuntimeError(

`String.${name} does not support function replacers in CodeMode; use match/matchAll and rebuild the string instead.`,

node,

"UnsupportedSyntax",

[supportedSyntaxMessage],

)

}

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