refactor(codemode): extensions are host functions only (#49196)

This commit is contained in:
Aiden Cline
2026-09-15 13:42:51 -05:00
committed by GitHub
Unverified
parent c921067eb8
commit d9dfc5c1d6
7 changed files with 184 additions and 386 deletions
+11 -15
View File
@@ -22,7 +22,7 @@ ultimate source of truth. Upstream test262 files run verbatim from `test/test262
- [x] The host boundary is `JSON.stringify` plus a short table. The program result and tool arguments cross as
what `JSON.stringify` would serialize: `toJSON` is honored, functions and `undefined` properties vanish,
`undefined` array elements and non-finite numbers become `null`, a cyclic value throws the same `TypeError`,
and Map, RegExp, generators, and extension handles serialize as `{}`. A bare `undefined` result is `null`.
and Map, RegExp, and generators serialize as `{}`. A bare `undefined` result is `null`.
Tool results come back the way `JSON.parse(JSON.stringify(result))` would. The table, where a value cannot
be JSON but what the program meant is clear: a promise is awaited (a rejection fails the program), a Set
crosses as an array, a URLSearchParams as its query string, an Error as `{ name, message, ...own }`, a
@@ -452,29 +452,25 @@ with a hint to encode as text first (`TextDecoder`, `toBase64`, `toHex`).
## Extensions
Host classes and functions a host opts in through `Extension.make({ name, globals })` and `CodeMode.make({ extensions })`.
Host functions a host opts in through `Extension.make({ name, globals })` and `CodeMode.make({ extensions })`.
Nothing is exposed unless a host provides it; extension calls are not tool calls.
- [x] Each global is a class or a function, exposed as-is: constructors with `new`, prototype methods, accessors,
and statics (including through an exposed subclass, so `new this()` works), plus inheritance
up to the nearest exposed ancestor. A global that shadows a built-in or another extension throws at `make`.
- [x] Instances of exposed classes stay on the host; the program holds a handle whose only members are the class's.
The same host instance is always the same handle within a run, so identity and `instanceof` hold. A handle
serializes as `{}` like any object without enumerable properties, so the host object never crosses.
- [x] Each global is a function, callable but not constructible, run with `this` undefined. A global that shadows
a built-in or another extension throws at `make`.
- [x] Every value crossing in either direction is converted, never shared: plain objects and arrays are copied,
`Date`, `RegExp`, `URL`, `URLSearchParams`, `Map`, `Set`, and `Uint8Array` become fresh copies with their
contents converted (a host `ArrayBuffer` comes in as a `Uint8Array`; other typed arrays cannot come out),
errors cross as errors with their name and message, and a `__proto__` key is dropped. Functions, generators,
un-awaited promises, and symbols cannot be passed in; an instance of an unexposed class, a symbol, or a BigInt
cannot come out.
un-awaited promises, and symbols cannot be passed in; a class instance, a symbol, or a BigInt cannot come out.
- [x] A host function inside a result becomes a program function whose calls cross the same way, so a result can
carry methods (`res.json()`) whose host closures keep the host state. Diagnostics name it by its path
(`fetch.json`). Like any program function it vanishes at the data boundary.
- [x] A host `Promise` becomes a program promise. Whatever host code returns, resolves, throws, or rejects with
crosses the same way, so `catch (e)` receives a copy of the thrown value (an `Error` of the matching type, or
plain data). A getter must be synchronous.
- [x] A prototype member runs only with a handle of its own class as `this`; a detached call, a plain object, or a
handle of another class throws `TypeError: Illegal invocation`. Program edits to an exposed prototype affect
that run only. Data properties on a class or prototype are not exposed, since a program write would change the
host class itself; expose one through an accessor.
plain data).
- [ ] Program functions as arguments to extension code (callbacks such as `forEach`).
- [ ] Host classes. Stateful host objects are expressed as closures; a declared method table would be the next
step if `new X()` in a program is ever needed.
## Errors and diagnostics
+1 -1
View File
@@ -37,7 +37,7 @@ export type ResolvedExecutionLimits = {
export type Options<Provided extends Record<string, unknown> = {}> = ToolRuntime.ToolCallHooks<Services<Provided>> & {
/** Explicit tools exposed to the program as `tools`. */
tools?: Provided & Tools<Services<Provided>>
/** Host classes and functions exposed as globals; see `Extension.make`. */
/** Host functions exposed as globals; see `Extension.make`. */
extensions?: ReadonlyArray<Extension>
/** Resource limits enforced on each execution. */
limits?: ExecutionLimits
+4 -5
View File
@@ -1,20 +1,19 @@
export * as Extension from "./extension.js"
/**
* Host classes and functions a program uses directly, like JavaScript. Values crossing in either direction are
* converted, never shared: plain data is copied, instances of the classes stay on the host behind program-side
* handles. Extension calls are not tool calls.
* Host functions a program calls directly as globals. Values crossing in either direction are converted, never
* shared: arguments come in as copies, results go out as copies, and a function inside a result is callable the
* same way. Extension calls are not tool calls.
*/
export type Extension = {
readonly name: string
/** Each value is a class or a function; everything on a class is exposed, including statics and accessors. */
readonly globals: Readonly<Record<string, Function>>
}
export const make = (options: Extension): Extension => {
for (const [name, value] of Object.entries(options.globals)) {
if (typeof value !== "function") {
throw new TypeError(`Extension "${options.name}" global "${name}" must be a class or a function.`)
throw new TypeError(`Extension "${options.name}" global "${name}" must be a function.`)
}
}
return { name: options.name, globals: { ...options.globals } }
+38 -178
View File
@@ -5,21 +5,18 @@ import type { Interpreter } from "./interpreter.js"
import { createErrorValue, isErrorType } from "./intrinsics.js"
import { MAX_VALUE_DEPTH } from "./limits.js"
import { Throw, typeError } from "./model.js"
import { constructor, fn } from "./native.js"
import { fn } from "./native.js"
import {
Callable,
define,
defineAccessor,
entries,
get,
hidden,
type Native,
Arr,
Bytes,
DateObj,
ErrorObj,
GeneratorObj,
Handle,
MapObj,
Obj,
PromiseObj,
@@ -30,31 +27,16 @@ import {
} from "./objects.js"
import { describeValue } from "./references.js"
type Class = Function & { readonly prototype: object }
const isClass = (value: unknown): value is Class =>
typeof value === "function" && typeof value.prototype === "object" && value.prototype !== null
// Own keys the native function already carries.
const ownFunctionKeys = new Set(["length", "name", "prototype"])
const ownPrototypeKeys = new Set(["constructor"])
/**
* The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data is
* copied, built-in wrappers are copied, instances of exposed classes travel as handles, and a host Promise becomes
* a program promise. Prototypes, constructors, and handle identity are all per run.
* The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
* built-in wrappers are copied, a host function becomes a program function whose calls cross the same way, and a
* host Promise becomes a program promise.
*/
export const extensionGlobals = <R>(
ctx: Interpreter<R>,
extensions: ReadonlyArray<Extension>,
): ReadonlyArray<readonly [string, unknown]> => {
const builtins = ctx.builtins
const classes = new Set(extensions.flatMap((extension) => Object.values(extension.globals)).filter(isClass))
// Host prototype object → this run's program prototype, so an instance wraps as its most-derived exposed class.
const protoOf = new Map<object, Obj>()
const exposed = new Map<Class, { ctor: Native<R>; proto: Obj }>()
const classOf = new Map<unknown, Class>()
const handles = new WeakMap<object, Handle>()
const toHost = (value: unknown, label: string, depth = 0, seen = new Set<object>()): unknown => {
if (depth > MAX_VALUE_DEPTH) throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`)
@@ -62,7 +44,6 @@ export const extensionGlobals = <R>(
if (isPrimitive(value)) return value
throw typeError(`${label} contains ${describeValue(value)}, which cannot be passed to an extension.`)
}
if (value instanceof Handle) return value.instance
if (value instanceof Bytes) return new Uint8Array(value.bytes)
if (value instanceof DateObj) return new Date(value.time)
if (value instanceof RegExpObj) return new RegExp(value.regex.source, value.regex.flags)
@@ -83,7 +64,7 @@ export const extensionGlobals = <R>(
const name = coerceToString(get(value, "name"))
const message = get(value, "message")
const text = message === undefined ? "" : coerceToString(message)
return name === "AggregateError" ? new AggregateError([], text) : new (hostErrors[name] ?? Error)(text)
return name === "AggregateError" ? new AggregateError([], text) : new (hostErrors.get(name) ?? Error)(text)
}
if (seen.has(value)) throw typeError(`${label} contains a circular value.`)
seen.add(value)
@@ -102,15 +83,8 @@ export const extensionGlobals = <R>(
const fromHost = (value: unknown, label: string, depth = 0, seen = new Set<object>()): unknown => {
if (depth > MAX_VALUE_DEPTH) throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`)
if (isPrimitive(value)) return value
if (typeof value === "function") return wrap(value, label)
if (value !== null && typeof value === "object") {
const existing = handles.get(value)
if (existing !== undefined) return existing
const proto = handlePrototype(value)
if (proto !== undefined) {
const handle = new Handle(proto, value)
handles.set(value, handle)
return handle
}
if (value instanceof Date) return new DateObj(builtins.Date, value.getTime())
if (value instanceof RegExp) return new RegExpObj(builtins.RegExp, value.source, value.flags)
if (value instanceof Uint8Array) return new Bytes(builtins.Uint8Array, new Uint8Array(value))
@@ -122,28 +96,31 @@ export const extensionGlobals = <R>(
if (value instanceof URLSearchParams) {
return new URLSearchParamsObj(builtins.URLSearchParams, new URLSearchParams(value))
}
const next = (item: unknown) => fromHost(item, label, depth + 1, seen)
const next = (item: unknown, path: string) => fromHost(item, path, depth + 1, seen)
if (value instanceof Map) {
const wrapped = new MapObj(builtins.Map)
for (const [key, item] of value) wrapped.map.set(next(key), next(item))
for (const [key, item] of value) wrapped.map.set(next(key, label), next(item, label))
return wrapped
}
if (value instanceof Set) {
const wrapped = new SetObj(builtins.Set)
for (const item of value) wrapped.set.add(next(item))
for (const item of value) wrapped.set.add(next(item, label))
return wrapped
}
if (seen.has(value)) throw typeError(`${label} produced a circular value.`)
seen.add(value)
if (Array.isArray(value)) {
const copied = new Arr(builtins.Array, value.map(next))
const copied = new Arr(
builtins.Array,
value.map((item, index) => next(item, `${label}[${index}]`)),
)
seen.delete(value)
return copied
}
const prototype = Object.getPrototypeOf(value)
if (prototype === Object.prototype || prototype === null) {
const copied = new Obj(builtins.Object)
for (const [key, item] of Object.entries(value)) define(copied, key, next(item))
for (const [key, item] of Object.entries(value)) define(copied, key, next(item, `${label}.${key}`))
seen.delete(value)
return copied
}
@@ -151,153 +128,37 @@ export const extensionGlobals = <R>(
throw typeError(`${label} produced ${describeHost(value)}, which the program cannot hold.`)
}
const handlePrototype = (instance: object): Obj | undefined => {
for (let level = Object.getPrototypeOf(instance); level !== null; level = Object.getPrototypeOf(level)) {
const proto = protoOf.get(level)
if (proto !== undefined) return proto
}
return undefined
}
// Runs host code with already-converted inputs. Whatever it returns, resolves, throws, or rejects with crosses
// the same way, so the program catches what the author threw.
const invoke = (run: () => unknown, label: string): Effect.Effect<unknown, unknown, R> => {
const thrown = (reason: unknown) => new Throw(fromHost(reason, label))
let result: unknown
try {
result = run()
} catch (reason) {
return Effect.fail(thrown(reason))
}
if (!(result instanceof Promise)) return Effect.succeed(fromHost(result, label))
return ctx.pending.create(
Effect.map(Effect.tryPromise({ try: () => result, catch: thrown }), (settled) => fromHost(settled, label)),
)
}
const args = (values: Array<unknown>, label: string): Array<unknown> =>
values.map((value, index) => toHost(value, `Argument ${index + 1} to ${label}`))
// Own members of each level from `from` up to (excluding) `root`, child first, as JS resolves them.
const members = (
target: Obj,
from: object,
root: object,
skip: ReadonlySet<string>,
label: string,
receiver: (thisValue: unknown, member: string) => unknown,
): void => {
for (let level: object | null = from; level !== null && level !== root; level = Object.getPrototypeOf(level)) {
for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(level))) {
if (skip.has(key) || target.props.has(key)) continue
const name = `${label}.${key}`
if (typeof descriptor.value === "function") {
const method: Function = descriptor.value
const impl = (thisValue: unknown, values: Array<unknown>) => {
const self = receiver(thisValue, name)
const converted = args(values, name)
return invoke(() => method.apply(self, converted), name)
}
define(target, key, fn<R>(builtins, key, method.length, impl), hidden)
continue
}
// Data properties stay host-side: a program write to one would change the host class itself.
if ("value" in descriptor) continue
const get = descriptor.get
const set = descriptor.set
defineAccessor(
target,
key,
get === undefined
? undefined
: (thisValue) => {
const value = get.call(receiver(thisValue, name))
if (value instanceof Promise)
throw typeError(`${name} returned a Promise; a getter must be synchronous.`)
return fromHost(value, name)
},
set === undefined
? undefined
: (thisValue, value) => {
set.call(receiver(thisValue, name), toHost(value, `${name} value`))
},
)
// A host function as a program function: arguments cross in, and whatever it returns, resolves, throws, or
// rejects with crosses out, so the program catches what the author threw.
const wrap = (value: Function, label: string): Native<R> =>
fn<R>(builtins, value.name, value.length, (_, values) => {
const converted = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`))
const thrown = (reason: unknown) => new Throw(fromHost(reason, label))
let result: unknown
try {
result = value.apply(undefined, converted)
} catch (reason) {
return Effect.fail(thrown(reason))
}
}
}
const expose = (cls: Class): { ctor: Native<R>; proto: Obj } => {
const existing = exposed.get(cls)
if (existing !== undefined) return existing
const ancestor = exposedAncestor(cls)
const base = ancestor === undefined ? undefined : expose(ancestor)
const proto = new Obj(base === undefined ? builtins.Object : base.proto)
protoOf.set(cls.prototype, proto)
const name = cls.name
const ctor = constructor<R>(builtins, proto, {
name,
length: cls.length,
call: (_, values) => {
const converted = args(values, name)
return invoke(() => cls.apply(undefined, converted), name)
},
construct: (values) => {
const label = `new ${name}`
const construct = cls as new (...values: Array<unknown>) => object
const converted = args(values, label)
return invoke(() => new construct(...converted), label)
},
if (!(result instanceof Promise)) return fromHost(result, label)
return ctx.pending.create(
Effect.map(Effect.tryPromise({ try: () => result, catch: thrown }), (settled) => fromHost(settled, label)),
)
})
if (base !== undefined) ctor.proto = base.ctor
const entry = { ctor, proto }
exposed.set(cls, entry)
classOf.set(ctor, cls)
// A static called through an exposed subclass sees that subclass as `this`, like JS.
members(ctor, cls, ancestor ?? Function.prototype, ownFunctionKeys, name, (thisValue) => {
const called = classOf.get(thisValue)
return called !== undefined && (called === cls || called.prototype instanceof cls) ? called : cls
})
members(
proto,
cls.prototype,
ancestor?.prototype ?? Object.prototype,
ownPrototypeKeys,
`${name}.prototype`,
(thisValue, member) => {
if (thisValue instanceof Handle && thisValue.instance instanceof cls) return thisValue.instance
throw typeError(`Illegal invocation: ${member} called on ${describeValue(thisValue)}.`)
},
)
return entry
}
const exposedAncestor = (cls: Class): Class | undefined => {
for (let level = Object.getPrototypeOf(cls); isClass(level); level = Object.getPrototypeOf(level)) {
if (classes.has(level)) return level
}
return undefined
}
return extensions.flatMap((extension) =>
Object.entries(extension.globals).map(([name, value]) => {
if (isClass(value)) return [name, expose(value).ctor] as const
const impl = (_: unknown, values: Array<unknown>) => {
const converted = args(values, name)
return invoke(() => value.apply(undefined, converted), name)
}
return [name, fn<R>(builtins, name, value.length, impl)] as const
}),
Object.entries(extension.globals).map(([name, value]) => [name, wrap(value, name)] as const),
)
}
const hostErrors: Record<string, ErrorConstructor | undefined> = {
TypeError,
RangeError,
SyntaxError,
ReferenceError,
EvalError,
URIError,
}
const hostErrors = new Map<string, ErrorConstructor>([
["TypeError", TypeError],
["RangeError", RangeError],
["SyntaxError", SyntaxError],
["ReferenceError", ReferenceError],
["EvalError", EvalError],
["URIError", URIError],
])
// The primitives the interpreter operates on; symbols and BigInts are not among them.
const isPrimitive = (value: unknown): boolean =>
@@ -308,7 +169,6 @@ const isPrimitive = (value: unknown): boolean =>
typeof value === "boolean"
const describeHost = (value: unknown): string => {
if (typeof value === "function") return "a function"
if (typeof value !== "object" || value === null) return `a ${typeof value}`
const name = (value as { constructor?: { name?: string } }).constructor?.name
return name === undefined || name === "" ? "an object" : `a ${name}`
@@ -179,16 +179,6 @@ export class Bytes extends Obj {
}
}
/** An instance of an extension class: the host object lives in a field no property path reaches. */
export class Handle extends Obj {
constructor(
proto: Obj,
readonly instance: object,
) {
super(proto)
}
}
/** Built-in objects that wrap a host value; data-like, but never plain data. */
export const isWrapper = (
value: unknown,
@@ -9,7 +9,6 @@ import {
Bytes,
DateObj,
GeneratorObj,
Handle,
MapObj,
Obj,
PromiseObj,
@@ -23,7 +22,6 @@ import {
export const isRuntimeReference = (value: unknown): boolean =>
value instanceof Callable ||
value instanceof GeneratorObj ||
value instanceof Handle ||
value instanceof ToolReference ||
value instanceof PromiseObj ||
isWrapper(value)
@@ -89,7 +87,6 @@ export const describeValue = (value: unknown): string => {
if (value instanceof URLSearchParamsObj) return "a URLSearchParams"
if (value instanceof Bytes) return "a Uint8Array"
if (value instanceof GeneratorObj) return "a generator"
if (value instanceof Handle) return `a ${value.instance.constructor.name}`
if (isRuntimeReference(value)) return "a function"
if (typeof value === "object") return "a data object"
return `a ${typeof value}`
+130 -174
View File
@@ -2,67 +2,12 @@ import { describe, expect, test } from "bun:test"
import { Effect, Schema } from "effect"
import { CodeMode, Extension, Tool } from "../src/index.js"
class Bag {
static made = 0
static of(...items: Array<string>) {
return new this(items)
}
constructor(readonly items: Array<string> = []) {
Bag.made++
}
get size() {
return this.items.length
}
set size(length: number) {
this.items.length = length
}
add(item: string) {
this.items.push(item)
return this
}
toArray() {
return [...this.items]
}
pair() {
return { self: this, list: [this, new Bag()] }
}
async later<T>(value: T) {
return value
}
async reject(reason: unknown) {
throw reason
}
fail() {
throw new RangeError("boom")
}
get lazy() {
return Promise.resolve(1)
}
detached() {
return new Other()
}
}
class Other {}
class Big extends Bag {
double() {
return this.items.length * 2
}
}
class Vault {
secrets = new Map<string, string>()
set(key: string, value: string) {
this.secrets.set(key, value)
}
}
const held: Array<unknown> = []
const config = { retries: 3, nested: { deep: true } }
const requests: Array<unknown> = []
const extension = Extension.make({
name: "bag",
name: "web",
globals: {
Bag,
Big,
Vault,
keep: (value: unknown) => {
held.push(value)
return value
@@ -70,6 +15,19 @@ const extension = Extension.make({
settings: () => config,
later: async (value: number) => value + 1,
first: (map: Map<unknown, unknown>) => map.get("k"),
fetch: async (url: string, init?: { method?: string }) => {
requests.push([url, init])
const bytes = new TextEncoder().encode(`{"url":"${url}"}`)
return {
status: 200,
ok: true,
headers: { get: (name: string) => (name === "content-type" ? "application/json" : null) },
text: () => new TextDecoder().decode(bytes),
json: () => JSON.parse(new TextDecoder().decode(bytes)),
bytes: () => bytes,
handlers: [(step: number) => step + 1],
}
},
},
})
@@ -87,66 +45,61 @@ const failure = async (code: string, target = runtime) => {
return result.error
}
describe("extension classes behave like JS", () => {
test("construct, call methods, read and write accessors", async () => {
expect(await value(`const b = new Bag(["a"]); b.add("b"); return [b.size, b.toArray()]`)).toEqual([2, ["a", "b"]])
expect(await value(`const b = new Bag(["a", "b"]); b.size = 1; return b.toArray()`)).toEqual(["a"])
})
test("instanceof, constructor, typeof, and prototype identity", async () => {
expect(
await value(
`const b = new Bag(); return [b instanceof Bag, b.constructor === Bag, typeof Bag, Bag.prototype.constructor === Bag]`,
),
).toEqual([true, true, "function", true])
})
test("statics, including `new this()` through an exposed subclass", async () => {
expect(await value(`return [Bag.of("x", "y").toArray(), Big.of("q") instanceof Big, Big.of === Bag.of]`)).toEqual([
["x", "y"],
true,
true,
])
})
test("data properties are invisible, so a program write never reaches the host class", async () => {
Bag.made = 0
expect(await value(`Bag.made = 999; return Bag.made`)).toBe(999)
expect(Bag.made).toBe(0)
expect(await value(`return [Bag.made, new Bag(["a"]).items]`)).toEqual([null, null])
})
test("inheritance chains to the exposed ancestor", async () => {
expect(
await value(`const b = new Big(["a"]); return [b.double(), b.add("b").size, b instanceof Bag, b instanceof Big]`),
).toEqual([2, 2, true, true])
})
test("calling a class without new throws the host TypeError", async () => {
const error = await failure(`Bag()`)
expect(error.message).toStartWith("TypeError: ")
expect(error.message).toContain("new")
})
test("a function global is callable, awaitable, and not constructible", async () => {
describe("extension functions", () => {
test("a global is callable, awaitable, and not constructible", async () => {
expect(await value(`return await later(1)`)).toBe(2)
expect(await value(`return [typeof later, later.name, later.length]`)).toEqual(["function", "later", 1])
expect((await failure(`new later()`)).message).toContain("new later(...) is not supported")
})
test("a program can patch a prototype for its own run only", async () => {
expect(await value(`Bag.prototype.add = () => "patched"; return new Bag().add("x")`)).toBe("patched")
expect(await value(`return new Bag().add("x").toArray()`)).toEqual(["x"])
test("a function inside a result is callable and crosses the same way", async () => {
requests.length = 0
expect(
await value(
`const res = await fetch("https://a.test/", { method: "GET" }); return [res.status, res.ok, res.headers.get("content-type"), res.text(), res.json(), [...res.bytes()].length, typeof res.json, res.json.name, res.handlers[0](1)]`,
),
).toEqual([
200,
true,
"application/json",
'{"url":"https://a.test/"}',
{ url: "https://a.test/" },
25,
"function",
"json",
2,
])
expect(requests).toEqual([["https://a.test/", { method: "GET" }]])
})
test("a function inside a result is named by its path in diagnostics", async () => {
expect((await failure(`const res = await fetch("https://a.test/"); res.handlers[0](() => 1)`)).message).toContain(
"Argument 1 to fetch.handlers[0] contains a function",
)
const target = CodeMode.make({
extensions: [Extension.make({ name: "odd", globals: { make: () => ({ sym: () => Symbol("s") }) } })],
})
expect((await failure(`make().sym()`, target)).message).toContain("make.sym produced a symbol")
})
test("a function is invisible to the data boundary like any program function", async () => {
expect(await value(`return await fetch("https://a.test/")`)).toEqual({
status: 200,
ok: true,
headers: {},
handlers: [null],
})
expect(await value(`return JSON.stringify((await fetch("https://a.test/")).headers)`)).toBe("{}")
})
test("a class global is only a function; calling it throws the host TypeError", async () => {
const target = CodeMode.make({ extensions: [Extension.make({ name: "cls", globals: { Bag: class Bag {} } })] })
expect((await failure(`Bag()`, target)).message).toContain("without")
expect((await failure(`new Bag()`, target)).message).toContain("new Bag(...) is not supported")
})
})
describe("values are converted at the boundary, never shared", () => {
test("the same host instance is the same handle", async () => {
expect(
await value(`const b = new Bag(); const p = b.pair(); return [p.self === b, p.list[0] === b, keep(b) === b]`),
).toEqual([true, true, true])
expect(await value(`const p = new Bag().pair(); return p.list[1] instanceof Bag`)).toBe(true)
})
test("plain data passed in is a copy the program cannot change afterwards", async () => {
held.length = 0
await value(
@@ -163,8 +116,12 @@ describe("values are converted at the boundary, never shared", () => {
expect(config).toEqual({ retries: 3, nested: { deep: true } })
})
test("Map and Set contents are converted element-wise, so handles unwrap inside them", async () => {
expect(await value(`const b = new Bag(); return first(new Map([["k", b]])) === b`)).toBe(true)
test("the same host value returned twice is two program values", async () => {
expect(await value(`return settings() === settings()`)).toBe(false)
expect(await value(`return keep(settings()) === settings()`)).toBe(false)
})
test("Map and Set contents are converted element-wise", async () => {
expect(await value(`return first(new Map([["k", { z: 1 }]]))`)).toEqual({ z: 1 })
held.length = 0
await value(`const inner = { z: 1 }; keep(new Set([inner])); inner.z = 2`)
@@ -214,6 +171,13 @@ describe("values are converted at the boundary, never shared", () => {
expect(Object.keys(held[0] as object)).toEqual([])
})
test("an Error with an unknown name crosses as a plain Error", async () => {
held.length = 0
await value(`const e = new Error("x"); e.name = "constructor"; keep(e); e.name = "__proto__"; keep(e)`)
expect(held[0]).toBeInstanceOf(Error)
expect(held[1]).toBeInstanceOf(Error)
})
test("functions, promises, and symbols cannot be passed in", async () => {
expect((await failure(`keep(() => 1)`)).message).toContain("Argument 1 to keep contains a function")
expect((await failure(`keep(later(1))`)).message).toContain("un-awaited Promise")
@@ -228,82 +192,45 @@ describe("values are converted at the boundary, never shared", () => {
expect((await failure(`big()`, target)).message).toContain("big produced a bigint")
})
test("an instance of an unexposed class cannot come out", async () => {
expect((await failure(`new Bag().detached()`)).message).toContain("produced a Other, which the program cannot hold")
})
test("a getter must be synchronous", async () => {
expect((await failure(`new Bag().lazy`)).message).toContain("Bag.prototype.lazy returned a Promise")
})
})
describe("the host object behind a handle is unreachable", () => {
test("enumeration, spread, and JSON see no own properties", async () => {
expect(
await value(`const b = new Bag(["a"]); return [Object.keys(b), Object.entries({ ...b }), String(b)]`),
).toEqual([[], [], "[object Object]"])
})
test("a handle serializes as {} when returned, stringified, or handed to a tool", async () => {
expect(await value(`return new Bag()`)).toEqual({})
expect(await value(`return JSON.stringify(new Bag())`)).toBe("{}")
const tools = CodeMode.make({
extensions: [extension],
tools: {
echo: Tool.make({
description: "Echo",
input: Schema.Struct({ v: Schema.Unknown }),
output: Schema.Unknown,
execute: (input) => Effect.succeed(input.v),
}),
},
})
expect(await value(`return await tools.echo({ v: new Bag() })`, tools)).toEqual({})
})
test("a method only runs on a handle of its own class", async () => {
expect((await failure(`const add = new Bag().add; add("x")`)).message).toContain(
"Illegal invocation: Bag.prototype.add called on undefined",
)
expect((await failure(`const o = { add: Bag.prototype.add }; o.add("x")`)).message).toContain(
"called on a data object",
)
const vault = new Vault()
test("a class instance cannot come out", async () => {
class Other {}
const target = CodeMode.make({
extensions: [Extension.make({ name: "vault", globals: { Bag, Vault, vault: () => vault } })],
extensions: [Extension.make({ name: "odd", globals: { detached: () => new Other() } })],
})
expect((await failure(`const v = vault(); v.add = Bag.prototype.add; v.add("x")`, target)).message).toContain(
"Illegal invocation: Bag.prototype.add called on a Vault",
)
expect(vault.secrets.size).toBe(0)
})
test("reading an accessor off the prototype itself is an illegal invocation", async () => {
expect((await failure(`Bag.prototype.size`)).message).toContain("Illegal invocation")
expect((await failure(`detached()`, target)).message).toContain("produced a Other, which the program cannot hold")
})
})
describe("host errors", () => {
test("a synchronous throw becomes the matching program error", async () => {
expect(await value(`try { new Bag().fail() } catch (e) { return [e instanceof RangeError, e.message] }`)).toEqual([
const target = CodeMode.make({
extensions: [
Extension.make({
name: "odd",
globals: {
fail: () => {
throw new RangeError("boom")
},
},
}),
],
})
expect(await value(`try { fail() } catch (e) { return [e instanceof RangeError, e.message] }`, target)).toEqual([
true,
"boom",
])
})
test("a thrown or rejected value crosses like a return, so the program catches what was thrown", async () => {
expect(
await value(
`try { await new Bag().reject(new TypeError("bad")) } catch (e) { return [e instanceof TypeError, e.message] }`,
),
).toEqual([true, "bad"])
expect(await value(`try { await new Bag().reject("plain") } catch (e) { return e }`)).toBe("plain")
const reason = { status: 404, nested: { a: 1 } }
const target = CodeMode.make({
extensions: [
Extension.make({
name: "api",
globals: {
reject: async (reason: unknown) => {
throw reason
},
get: async () => Promise.reject(reason),
boom: () => {
throw reason
@@ -312,6 +239,13 @@ describe("host errors", () => {
}),
],
})
expect(
await value(
`try { await reject(new TypeError("bad")) } catch (e) { return [e instanceof TypeError, e.message] }`,
target,
),
).toEqual([true, "bad"])
expect(await value(`try { await reject("plain") } catch (e) { return e }`, target)).toBe("plain")
expect(await value(`try { await get() } catch (e) { e.status = 0; return e }`, target)).toEqual({
status: 0,
nested: { a: 1 },
@@ -325,23 +259,45 @@ describe("host errors", () => {
describe("configuration", () => {
test("extension calls are not tool calls", async () => {
const limited = CodeMode.make({ extensions: [extension], limits: { maxToolCalls: 0 } })
const result = await Effect.runPromise(limited.execute(`new Bag().add("x"); return await later(1)`))
const result = await Effect.runPromise(
limited.execute(`(await fetch("https://a.test/")).json(); return await later(1)`),
)
expect(result.ok).toBe(true)
expect(result.toolCalls).toEqual([])
})
test("a global must be a class or a function", () => {
test("a result handed to a tool is plain data", async () => {
const tools = CodeMode.make({
extensions: [extension],
tools: {
echo: Tool.make({
description: "Echo",
input: Schema.Struct({ v: Schema.Unknown }),
output: Schema.Unknown,
execute: (input) => Effect.succeed(input.v),
}),
},
})
expect(await value(`return await tools.echo({ v: await fetch("https://a.test/") })`, tools)).toEqual({
status: 200,
ok: true,
headers: {},
handlers: [null],
})
})
test("a global must be a function", () => {
expect(() => Extension.make({ name: "bad", globals: { n: 1 as never } })).toThrow(
'Extension "bad" global "n" must be a class or a function.',
'Extension "bad" global "n" must be a function.',
)
})
test("a global may not shadow a built-in or another extension", () => {
expect(() => CodeMode.make({ extensions: [Extension.make({ name: "web", globals: { URL: class {} } })] })).toThrow(
expect(() => CodeMode.make({ extensions: [Extension.make({ name: "web", globals: { URL: () => 1 } })] })).toThrow(
'Extension "web" global "URL" is already defined.',
)
expect(() =>
CodeMode.make({ extensions: [extension, Extension.make({ name: "again", globals: { Bag: class {} } })] }),
).toThrow('Extension "again" global "Bag" is already defined.')
CodeMode.make({ extensions: [extension, Extension.make({ name: "again", globals: { fetch: () => 1 } })] }),
).toThrow('Extension "again" global "fetch" is already defined.')
})
})