fix(core): say plainly that catalog tools and search only work inside execute (#50384)

packages/codemode/AGENTS.md

@@ -6,6 +6,8 @@
 - Tool schemas are the model-facing Interface. Keep arguments minimal and natural to the operation; never add unrelated IDs as ambient capability tokens.
 - State model-visible diagnostics, logs, tool descriptions, and instructions directly. The execution context is already clear; do not repeat `Code Mode` or `CodeMode` unless the distinction is necessary.
 - When interpreter behavior or support changes, update `interpreter-support.md` and direct tests in the same PR.
+- Program values are `Value` (`src/interpreter/objects.ts`); host values are `unknown` and are copied in at the boundaries (`fromHost`, `fromJson`). Do not widen program-facing signatures back to `unknown`.
+- A built-in kind of object is one `Obj` subclass (`Wrapper` for host-backed data such as Date or Map, `Opaque` for machinery such as functions and promises) that overrides `tag`, `toString`, `toPrimitive`, `inspect`, `toHost`, and `iterator` as needed. Do not add `instanceof` ladders over the built-in classes elsewhere; ask the object.
 
 ## OpenAPI
 

packages/codemode/interpreter-support.md

@@ -275,7 +275,8 @@ ultimate source of truth. Upstream test262 files run verbatim from `test/test262
 - [x] `Object.is` for supported data values.
 - [x] `Object.groupBy` over finite collections and custom synchronous iterators/generators, with string-key coercion
       and plain-object results.
-- [x] `Object.prototype` methods on values: `toString` (`"[object Array]"`), `toLocaleString` (calls the value's
+- [x] `Object.prototype` methods on values: `toString` (`"[object Array]"`, `"[object Map]"`, `"[object Promise]"`, and so
+      on for every built-in kind, as JS reports through `Symbol.toStringTag`), `toLocaleString` (calls the value's
       `toString`, as in JS), `valueOf`, `hasOwnProperty`, `isPrototypeOf`, and `propertyIsEnumerable`.
 
 ## Arrays

packages/codemode/src/data.ts

@@ -15,6 +15,7 @@ import {
   Obj,
   PromiseObj,
   record,
+  type Value,
   SetObj,
   URLSearchParamsObj,
   HeadersObj,
@@ -23,14 +24,14 @@ import { typeofValue } from "./interpreter/references.js"
 
 export type Json = Schema.Json
 
-type Replacer<R> = (args: Array<unknown>) => Effect.Effect<unknown, unknown, R>
+type Replacer<R> = (args: Array<Value>) => Effect.Effect<Value, unknown, R>
 
 /**
  * What `JSON.stringify` would serialize for a program value, as host JSON: `toJSON` is honored, functions and
  * `undefined` vanish, non-finite numbers become null, and everything else is copied. Two departures from JS
  * so a mistake is not a silent `{}`: an Error serializes as `{ name, message, ...own }`, and a promise throws.
  */
-export const toJson = <R>(ctx: Interpreter<R>, value: unknown, replacer?: Replacer<R>) =>
+export const toJson = <R>(ctx: Interpreter<R>, value: Value, replacer?: Replacer<R>) =>
   walk(ctx, value, replacer, false)
 
 /**
@@ -38,11 +39,11 @@ export const toJson = <R>(ctx: Interpreter<R>, value: unknown, replacer?: Replac
  * awaited, a Set crosses as an array, a URLSearchParams as its query string, a Uint8Array asks to be encoded as
  * text first, and a `__proto__` key is dropped so host code can never receive one.
  */
-export const toBoundary = <R>(ctx: Interpreter<R>, value: unknown) => walk(ctx, value, undefined, true)
+export const toBoundary = <R>(ctx: Interpreter<R>, value: Value) => walk(ctx, value, undefined, true)
 
 const walk = <R>(
   ctx: Interpreter<R>,
-  value: unknown,
+  value: Value,
   replacer: Replacer<R> | undefined,
   boundary: boolean,
 ): Effect.Effect<Json | undefined, unknown, R> => {
@@ -104,7 +105,7 @@ const walk = <R>(
 }
 
 /** Host JSON as program values: objects and arrays are copied, primitives pass through. */
-export const fromJson = <R>(ctx: Interpreter<R>, value: unknown): unknown => {
+export const fromJson = <R>(ctx: Interpreter<R>, value: Json | undefined): Value => {
   if (value === null || typeof value !== "object") return value
   if (Array.isArray(value))
     return new Arr(

packages/codemode/src/interpreter/callback.ts

@@ -1,13 +1,12 @@
 import { Effect, Exit } from "effect"
-import { coerceToNumber, coerceToString } from "../stdlib/value.js"
 import type { Interpreter } from "./interpreter.js"
 import { primitivePrototype } from "./intrinsics.js"
 import { typeError } from "./model.js"
-import { Callable, get, Native, DateObj, Obj } from "./objects.js"
+import { Callable, get, Native, DateObj, Obj, coerceToNumber, coerceToString, type Value } from "./objects.js"
 import { typeofValue } from "./references.js"
 
 export type IteratorCursor<R> = {
-  readonly next: Effect.Effect<{ readonly done: boolean; readonly value: unknown }, unknown, R>
+  readonly next: Effect.Effect<{ readonly done: boolean; readonly value: Value }, unknown, R>
   readonly close: Effect.Effect<void, unknown, R>
 }
 
@@ -27,9 +26,9 @@ export const preserveConsumerError = <A, R>(
  */
 export const toPrimitive = <R>(
   ctx: Interpreter<R>,
-  value: unknown,
+  value: Value,
   hint: "number" | "string" | "default",
-): Effect.Effect<unknown, unknown, R> => {
+): Effect.Effect<Value, unknown, R> => {
   if (!(value instanceof Obj)) return Effect.succeed(value)
   const asString = hint === "string" || (hint === "default" && value instanceof DateObj)
   const order = asString ? ["toString", "valueOf"] : ["valueOf", "toString"]
@@ -45,30 +44,30 @@ export const toPrimitive = <R>(
 }
 
 /** Invoke(value, name): calls the method the value would find through its prototype. */
-export const invoke = <R>(ctx: Interpreter<R>, value: unknown, name: string, label: string) => {
+export const invoke = <R>(ctx: Interpreter<R>, value: Value, name: string, label: string) => {
   const target = value instanceof Obj ? value : primitivePrototype(ctx.builtins, value)
   if (target === undefined) throw typeError(`${label} called on null or undefined.`)
   return ctx.call(get(target, name), value, [])
 }
 
-export const toPrimitiveString = <R>(ctx: Interpreter<R>, value: unknown) =>
+export const toPrimitiveString = <R>(ctx: Interpreter<R>, value: Value) =>
   Effect.map(toPrimitive(ctx, value, "string"), coerceToString)
 
-export const toPrimitiveNumber = <R>(ctx: Interpreter<R>, value: unknown) =>
+export const toPrimitiveNumber = <R>(ctx: Interpreter<R>, value: Value) =>
   Effect.map(toPrimitive(ctx, value, "number"), coerceToNumber)
 
 // The single acceptance list for callbacks: collections, sort, string replacers,
 // Array.from mappers, and promise reactions all admit exactly these callables.
 // Admission means dispatchable, not necessarily invocable: new-requiring
 // constructors pass the gate and throw a TypeError on call, like JS.
-export const isSupportedCallback = (value: unknown): value is Callable =>
+export const isSupportedCallback = (value: Value): value is Callable =>
   value instanceof Callable && !(value instanceof Native && !value.callback)
 
 export const applyCollectionCallback = <R>(
   ctx: Interpreter<R>,
-  callback: unknown,
+  callback: Value,
   name: string,
-): ((args: Array<unknown>) => Effect.Effect<unknown, unknown, R>) => {
+): ((args: Array<Value>) => Effect.Effect<Value, unknown, R>) => {
   if (!isSupportedCallback(callback)) {
     if (typeofValue(callback) === "function") {
       throw typeError(

packages/codemode/src/interpreter/errors.ts

@@ -6,10 +6,21 @@ import { type AstNode, formatLocation, PendingThrow, Throw, sourceLocation, type
 import { containsRuntimeReference } from "./references.js"
 import { createErrorValue, type ErrorType, isErrorType } from "./intrinsics.js"
 import { constructor, methods, prototypeFrom, receiver } from "./native.js"
-import { type Callable, define, get, has, hidden, type Native, Arr, ErrorObj, Obj } from "./objects.js"
+import {
+  type Callable,
+  define,
+  get,
+  has,
+  hidden,
+  type Native,
+  Arr,
+  ErrorObj,
+  Obj,
+  coerceToString,
+  type Value,
+} from "./objects.js"
 import type { Interpreter } from "./interpreter.js"
 import { formatValue } from "../stdlib/console.js"
-import { coerceToString } from "../stdlib/value.js"
 
 export const normalizeError = (error: unknown): Diagnostic => {
   if (error instanceof PendingThrow) {
@@ -86,7 +97,7 @@ export const locate = (error: unknown, node?: AstNode): unknown => {
 }
 
 /** The program value a handler receives for a failure; one failure always yields the same value. */
-export const materialize = <R>(ctx: Interpreter<R>, thrown: unknown): unknown => {
+export const materialize = <R>(ctx: Interpreter<R>, thrown: unknown): Value => {
   if (thrown instanceof Throw) return thrown.value
   const builtins = ctx.builtins
   if (thrown instanceof PendingThrow) {
@@ -113,7 +124,7 @@ const errorToString = (self: Obj): string => {
 
 export const createAggregateErrorValue = <R>(
   ctx: Interpreter<R>,
-  errors: Array<unknown>,
+  errors: Array<Value>,
   message: string,
   proto: Obj = ctx.builtins.AggregateError,
 ) => {
@@ -124,13 +135,13 @@ export const createAggregateErrorValue = <R>(
 
 const constructAggregateErrorValue = <R>(
   ctx: Interpreter<R>,
-  args: Array<unknown>,
+  args: Array<Value>,
   proto: Obj,
 ): Effect.Effect<ErrorObj, unknown, R> =>
   Effect.gen(function* () {
     const cursor = yield* ctx.iterate(args[0])
     if (cursor === undefined) throw typeError("new AggregateError(...) expects a synchronous iterable of errors.")
-    const errors: Array<unknown> = []
+    const errors: Array<Value> = []
     while (true) {
       const step = yield* cursor.next
       if (step.done) {
@@ -144,7 +155,7 @@ const constructAggregateErrorValue = <R>(
 export const errorGlobal = <R>(type: ErrorType, ctx: Interpreter<R>) => {
   const builtins = ctx.builtins
   const prototype = builtins[type]
-  const construct = (args: Array<unknown>, newTarget: Callable) => {
+  const construct = (args: Array<Value>, newTarget: Callable) => {
     const proto = prototypeFrom(newTarget, prototype)
     const created =
       type === "AggregateError"

packages/codemode/src/interpreter/execute.ts

@@ -4,6 +4,7 @@ import type { DataValue, Diagnostic, ResolvedExecutionLimits, Result } from "../
 import { toBoundary } from "../data.js"
 import { ToolRuntime } from "../tool-runtime.js"
 import { normalizeError } from "./errors.js"
+import type { Value } from "./objects.js"
 import { createBuiltins } from "./intrinsics.js"
 import { Pending } from "./promises.js"
 import { Interpreter } from "./interpreter.js"
@@ -13,7 +14,7 @@ export const executeProgram = <R>(
   prepared: ToolRuntime.Prepared<R>,
   limits: ResolvedExecutionLimits,
   hooks: ToolRuntime.Hooks<R>,
-  globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, unknown]>,
+  globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>,
 ): Effect.Effect<Result, never, R> => {
   if (code.trim().length === 0) {
     return Effect.succeed({

packages/codemode/src/interpreter/extensions.ts

@@ -1,6 +1,5 @@
 import { Effect } from "effect"
 import type { Extension } from "../extension.js"
-import { coerceToString } from "../stdlib/value.js"
 import { type ExtensionInvocation, hooked } from "../tool-runtime.js"
 import type { Interpreter } from "./interpreter.js"
 import { createErrorValue, isErrorType } from "./intrinsics.js"
@@ -8,9 +7,7 @@ import { MAX_VALUE_DEPTH } from "./limits.js"
 import { PendingThrow, Throw, typeError } from "./model.js"
 import { fn } from "./native.js"
 import {
-  Callable,
   define,
-  entries,
   get,
   has,
   hidden,
@@ -19,18 +16,17 @@ import {
   Bytes,
   DateObj,
   ErrorObj,
-  GeneratorObj,
-  IteratorObj,
+  HeadersObj,
   MapObj,
   Obj,
-  PromiseObj,
   RegExpObj,
   SetObj,
   URLObj,
   URLSearchParamsObj,
-  HeadersObj,
+  coerceToString,
+  type Value,
 } from "./objects.js"
-import { describeValue } from "./references.js"
+import { describeValue, isOpaque } from "./references.js"
 
 /**
  * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
@@ -40,35 +36,18 @@ import { describeValue } from "./references.js"
 export const extensionGlobals = <R>(
   ctx: Interpreter<R>,
   extensions: ReadonlyArray<Extension>,
-): ReadonlyArray<readonly [string, unknown]> => {
+): ReadonlyArray<readonly [string, Value]> => {
   const builtins = ctx.builtins
 
-  const toHost = (value: unknown, label: string, depth = 0, seen = new Set<object>()): unknown => {
+  const toHost = (value: Value, 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 (value === null || typeof value !== "object") {
-      if (isPrimitive(value)) return value
-      throw typeError(`${label} contains ${describeValue(value)}, which cannot be passed to an extension.`)
-    }
-    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)
-    if (value instanceof URLObj) return new URL(value.url.href)
-    if (value instanceof URLSearchParamsObj) return new URLSearchParams(value.params)
-    if (value instanceof HeadersObj) return new Headers(value.headers)
-    const next = (item: unknown) => toHost(item, label, depth + 1, seen)
-    if (value instanceof MapObj) return new Map([...value.map].map(([key, item]) => [next(key), next(item)]))
-    if (value instanceof SetObj) return new Set([...value.set].map(next))
-    if (
-      !(value instanceof Obj) ||
-      value instanceof Callable ||
-      value instanceof GeneratorObj ||
-      value instanceof IteratorObj ||
-      value instanceof PromiseObj
-    ) {
+    if (isPrimitive(value)) return value
+    if (!(value instanceof Obj) || isOpaque(value)) {
       throw typeError(`${label} contains ${describeValue(value)}, which cannot be passed to an extension.`)
     }
     if (seen.has(value)) throw typeError(`${label} contains a circular value.`)
     seen.add(value)
+    const next = (item: Value) => toHost(item, label, depth + 1, seen)
     if (value instanceof ErrorObj) {
       const name = coerceToString(get(value, "name"))
       const message = get(value, "message")
@@ -89,19 +68,12 @@ export const extensionGlobals = <R>(
       seen.delete(value)
       return copied
     }
-    const copied =
-      value instanceof Arr
-        ? value.items.map(next)
-        : Object.fromEntries(
-            entries(value)
-              .filter(([key]) => key !== "__proto__")
-              .map(([key, item]) => [key, next(item)]),
-          )
+    const copied = value.toHost(next)
     seen.delete(value)
     return copied
   }
 
-  const fromHost = (value: unknown, label: string, depth = 0, seen = new Set<object>()): unknown => {
+  const fromHost = (value: unknown, label: string, depth = 0, seen = new Set<object>()): Value => {
     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)
@@ -200,7 +172,7 @@ export const extensionGlobals = <R>(
  */
 const uncrossed = new Set(["stack", "constructor", "toString", "__proto__"])
 const left = Symbol("left behind")
-const crossing = (convert: () => unknown): unknown => {
+const crossing = <T>(convert: () => T): T | typeof left => {
   try {
     return convert()
   } catch (reason) {
@@ -219,7 +191,7 @@ const hostErrors = new Map<string, ErrorConstructor>([
 ])
 
 // The primitives the interpreter operates on; symbols and BigInts are not among them.
-const isPrimitive = (value: unknown): boolean =>
+const isPrimitive = (value: unknown): value is string | number | boolean | null | undefined =>
   value === null ||
   value === undefined ||
   typeof value === "string" ||

packages/codemode/src/interpreter/generators.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { fn, type Method, methods, receiver } from "./native.js"
 import { AsyncIteratorSymbol, type GeneratorRequestKind, IteratorSymbol } from "./model.js"
-import { define, hidden, GeneratorObj } from "./objects.js"
+import { define, hidden, GeneratorObj, type Value } from "./objects.js"
 import type { Interpreter } from "./interpreter.js"
 
 /** `next`/`return`/`throw` on the generator prototypes; async generators answer with promises. */
@@ -13,9 +13,9 @@ export const generatorGlobals = <R>(ctx: Interpreter<R>): void => {
     const request = (kind: GeneratorRequestKind): Method => [
       kind,
       1,
-      (thisValue: unknown, args: Array<unknown>) => {
+      (thisValue: Value, args: Array<Value>) => {
         const generator = receiver(GeneratorObj, thisValue, `${label}.prototype.${kind}`)
-        const requested = generator.request(kind, args[0]) as Effect.Effect<unknown, unknown, R>
+        const requested = generator.request(kind, args[0]) as Effect.Effect<Value, unknown, R>
         return generator.asynchronous ? ctx.pending.create(requested) : requested
       },
     ]

packages/codemode/src/interpreter/globals.ts

@@ -1,4 +1,5 @@
 import { Effect } from "effect"
+import type { Value } from "./objects.js"
 import { arrayGlobal } from "../stdlib/array.js"
 import { textDecoderGlobal, textEncoderGlobal, uint8ArrayGlobal } from "../stdlib/bytes.js"
 import { mapGlobal, setGlobal } from "../stdlib/collections.js"
@@ -51,7 +52,7 @@ const symbolGlobal = <R>(ctx: Interpreter<R>) => {
   return symbol
 }
 
-type Factory = <R>(ctx: Interpreter<R>) => unknown
+type Factory = <R>(ctx: Interpreter<R>) => Value
 
 // A table rather than a list so the names are known before any runtime exists.
 const table: Record<string, Factory> = {
@@ -100,7 +101,7 @@ const table: Record<string, Factory> = {
 export const globalNames: ReadonlySet<string> = new Set(Object.keys(table))
 
 /** The immutable global bindings of every program, in declaration order. */
-export const globals = <R>(ctx: Interpreter<R>): ReadonlyArray<readonly [string, unknown]> => {
+export const globals = <R>(ctx: Interpreter<R>): ReadonlyArray<readonly [string, Value]> => {
   generatorGlobals(ctx)
   iteratorGlobals(ctx)
   return Object.entries(table).map(([name, factory]) => [name, factory(ctx)] as const)

packages/codemode/src/interpreter/interpreter.ts

@@ -32,6 +32,7 @@ import type {
   Statement,
   Super,
   SwitchStatement,
+  Literal,
   TemplateLiteral,
   ThrowStatement,
   TryStatement,
@@ -75,20 +76,16 @@ import {
   Native,
   parseArrayIndex,
   Arr,
-  Bytes,
-  DateObj,
   Fn,
   GeneratorObj,
-  IteratorObj,
-  MapObj,
   Obj,
   PromiseObj,
-  SetObj,
-  URLSearchParamsObj,
-  HeadersObj,
   record,
   remove,
   set,
+  coerceToNumber,
+  coerceToString,
+  type Value,
 } from "./objects.js"
 import { preserveConsumerError } from "./callback.js"
 import { Pending, resolvePromise, resolvePromiseValue } from "./promises.js"
@@ -96,7 +93,7 @@ import { containsOpaqueReference, describeValue, rejectCircularInsertion, typeof
 import { ScopeStack } from "./scope.js"
 import { constructRegExp } from "../stdlib/regexp.js"
 import { enumerableSource } from "../stdlib/object.js"
-import { coerceToNumber, coerceToString, compoundOperators } from "../stdlib/value.js"
+import { compoundOperators } from "../stdlib/value.js"
 
 // What a loop does with its body's result: exit with a StatementResult, or undefined to keep iterating.
 // Unlabelled break ends this loop; a label the loop does not carry propagates outward.
@@ -132,7 +129,14 @@ const calleeDescription = (node: Expression | Super | undefined): string | undef
 }
 
 // OrdinaryHasInstance: walk the left operand's chain looking for the constructor's `prototype`.
-const instanceofValue = (lhs: unknown, rhs: unknown, node: AstNode): boolean => {
+// acorn types every literal as possibly a BigInt or RegExp; regex literals become RegExp objects before this is asked.
+const literal = (node: Literal): Value => {
+  if (typeof node.value === "bigint") throw typeError("BigInt literals are not supported.", node)
+  if (node.value instanceof RegExp) throw unsupportedSyntax("RegExpLiteral", node)
+  return node.value
+}
+
+const instanceofValue = (lhs: Value, rhs: Value, node: AstNode): boolean => {
   if (!(rhs instanceof Callable)) {
     throw typeError("The right-hand side of 'instanceof' is not callable.", node)
   }
@@ -229,7 +233,7 @@ const loopDeclaration = (left: VariableDeclaration | Pattern, statement: "for...
 
 type CustomIterator = {
   iterator: Obj
-  next: unknown
+  next: Value
   asynchronous: boolean
 }
 
@@ -237,13 +241,13 @@ type CustomIterator = {
 type MemberReference = {
   target: Obj
   key: PropertyKey
-  receiver: unknown
+  receiver: Value
 }
 
 type GeneratorRequest = {
   kind: GeneratorRequestKind
-  value: unknown
-  response: Deferred.Deferred<unknown, unknown>
+  value: Value
+  response: Deferred.Deferred<Value, unknown>
 }
 
 type GeneratorState = {
@@ -269,7 +273,7 @@ export class Interpreter<R> {
     readonly pending: Pending<R>
     readonly builtins: Builtins
     readonly logs?: Array<string>
-    readonly globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, unknown]>
+    readonly globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, Value]>
   }) {
     this.tools = options.tools
     this.pending = options.pending
@@ -283,27 +287,27 @@ export class Interpreter<R> {
     }
   }
 
-  run(program: Program): Effect.Effect<unknown, unknown, R> {
+  run(program: Program): Effect.Effect<Value, unknown, R> {
     return this.root.run(program)
   }
 
-  call(callable: unknown, thisValue: unknown, args: Array<unknown>): Effect.Effect<unknown, unknown, R> {
+  call(callable: Value, thisValue: Value, args: Array<Value>): Effect.Effect<Value, unknown, R> {
     return this.root.call(callable, thisValue, args)
   }
 
-  await(promise: PromiseObj): Effect.Effect<unknown, unknown, never> {
+  await(promise: PromiseObj): Effect.Effect<Value, unknown, never> {
     return this.root.await(promise)
   }
 
-  iterate(value: unknown) {
+  iterate(value: Value) {
     return this.root.iterate(value)
   }
 
   /** Runs one host tool: arguments cross as JSON and the result comes back as program values. */
   tool(
     run: (args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>,
-    args: Array<unknown>,
-  ): Effect.Effect<unknown, unknown, R> {
+    args: Array<Value>,
+  ): Effect.Effect<Value, unknown, R> {
     const ctx = this
     return Effect.gen(function* () {
       const json = yield* Effect.forEach(args, (arg) => toBoundary(ctx, arg))
@@ -326,7 +330,7 @@ class Frame<R> {
     private depth = 0,
   ) {}
 
-  run(program: Program): Effect.Effect<unknown, unknown, R> {
+  run(program: Program): Effect.Effect<Value, unknown, R> {
     const self = this
     // Keep top-level declarations separate so they can shadow builtins.
     this.scopes.push()
@@ -334,7 +338,7 @@ class Frame<R> {
       self.predeclareLexical(program.body)
       self.hoistFunctions(program.body)
       self.hoistVars(program.body)
-      let value: unknown = undefined
+      let value: Value = undefined
       for (const [index, statement] of program.body.entries()) {
         if (index === program.body.length - 1 && statement.type === "ExpressionStatement") {
           value = yield* self.evaluateExpression(statement.expression)
@@ -359,15 +363,12 @@ class Frame<R> {
   }
 
   // Fork at the call site so admission and hooks occur when the call is made.
-  private createToolCallPromise(
-    path: ReadonlyArray<string>,
-    args: Array<unknown>,
-  ): Effect.Effect<PromiseObj, never, R> {
+  private createToolCallPromise(path: ReadonlyArray<string>, args: Array<Value>): Effect.Effect<PromiseObj, never, R> {
     return this.ctx.pending.create(this.ctx.tool((json) => this.ctx.tools.execute(path, json), args))
   }
 
   // Fiber exits make settlement idempotent; yielding prevents inline continuation.
-  await(promise: PromiseObj): Effect.Effect<unknown, unknown, never> {
+  await(promise: PromiseObj): Effect.Effect<Value, unknown, never> {
     const pending = this.ctx.pending
     return Effect.suspend(() => {
       pending.markObserved(promise)
@@ -458,7 +459,7 @@ class Frame<R> {
   }
 
   // NamedEvaluation: an anonymous function definition takes the name of what it is assigned to.
-  private evaluateNamed(node: Expression, name: string): Effect.Effect<unknown, unknown, R> {
+  private evaluateNamed(node: Expression, name: string): Effect.Effect<Value, unknown, R> {
     if (node.type === "ArrowFunctionExpression" || (node.type === "FunctionExpression" && !node.id)) {
       return Effect.sync(() => this.createFunction(node, name))
     }
@@ -660,7 +661,7 @@ class Frame<R> {
       const iterator = cursor === undefined ? yield* self.customIterator(right, node, awaiting) : undefined
       if (iterator === undefined && cursor === undefined) {
         throw invalidData(
-          `${awaiting ? "for await...of" : "for...of"} requires an array, string, Map, Set, URLSearchParams, or Headers, or custom iterator value.`,
+          `${awaiting ? "for await...of" : "for...of"} requires an iterable value, received ${describeValue(right)}.`,
           node,
         )
       }
@@ -676,7 +677,7 @@ class Frame<R> {
       }
       const assignment = left.type === "VariableDeclaration" ? undefined : left
 
-      const evaluateBody = (value: unknown) =>
+      const evaluateBody = (value: Value) =>
         Effect.gen(function* () {
           if (declared?.lexical) {
             self.scopes.push()
@@ -725,7 +726,7 @@ class Frame<R> {
     )
   }
 
-  private awaitValue(value: unknown): Effect.Effect<unknown, unknown, R> {
+  private awaitValue(value: Value): Effect.Effect<Value, unknown, R> {
     return Effect.flatMap(resolvePromise(this.ctx, value), (promise) =>
       Effect.ensuring(
         this.await(promise),
@@ -736,10 +737,10 @@ class Frame<R> {
 
   private awaitAsyncFromSyncValue(
     iterator: CustomIterator,
-    value: unknown,
+    value: Value,
     node: AstNode | undefined,
     closeOnRejection: boolean,
-  ): Effect.Effect<unknown, unknown, R> {
+  ): Effect.Effect<Value, unknown, R> {
     const self = this
     return Effect.gen(function* () {
       const settled = yield* Effect.exit(self.awaitValue(value))
@@ -751,7 +752,7 @@ class Frame<R> {
     })
   }
 
-  iterate(value: unknown, node?: AstNode) {
+  iterate(value: Value, node?: AstNode) {
     const cursor = this.hostCursor(value)
     if (cursor !== undefined) return Effect.succeed(cursor)
     const self = this
@@ -765,40 +766,24 @@ class Frame<R> {
     )
   }
 
-  private hostCursor(value: unknown) {
+  private hostCursor(value: Value) {
     const iterator =
-      value instanceof Arr
-        ? value.items[Symbol.iterator]()
-        : typeof value === "string"
-          ? value[Symbol.iterator]()
-          : value instanceof MapObj
-            ? value.map.entries()
-            : value instanceof SetObj
-              ? value.set.values()
-              : value instanceof URLSearchParamsObj
-                ? value.params.entries()
-                : value instanceof HeadersObj
-                  ? value.headers.entries()
-                  : value instanceof Bytes
-                    ? value.bytes.values()
-                    : value instanceof IteratorObj
-                      ? value.iterator
-                      : undefined
+      typeof value === "string"
+        ? value[Symbol.iterator]()
+        : value instanceof Obj
+          ? value.iterator(this.ctx.builtins)
+          : undefined
     if (iterator === undefined) return undefined
-    const proto = this.ctx.builtins.Array
     return {
       next: Effect.sync(() => {
         const step = iterator.next()
-        return {
-          done: Boolean(step.done),
-          value: Array.isArray(step.value) ? new Arr(proto, step.value) : step.value,
-        }
+        return { done: Boolean(step.done), value: step.value }
       }),
       close: Effect.void,
     }
   }
 
-  private customIterator(value: unknown, node: AstNode | undefined, allowAsync = true) {
+  private customIterator(value: Value, node: AstNode | undefined, allowAsync = true) {
     if (!(value instanceof Obj)) return Effect.undefined
     const asyncMethod = allowAsync ? get(value, AsyncIteratorSymbol) : undefined
     const method = asyncMethod ?? get(value, IteratorSymbol)
@@ -888,18 +873,18 @@ class Frame<R> {
     })
   }
 
-  private requireIteratorObject(value: unknown, context: string, node?: AstNode): Obj {
+  private requireIteratorObject(value: Value, context: string, node?: AstNode): Obj {
     if (value instanceof Obj) return value
     throw typeError(`${context} must be an object.`, node)
   }
 
-  private requireIteratorMethod(value: unknown, context: string, node?: AstNode): unknown {
+  private requireIteratorMethod(value: Value, context: string, node?: AstNode): Value {
     if (typeofValue(value) === "function") return value
     throw typeError(`${context} must be a function.`, node)
   }
 
   // for...in over null/undefined iterates nothing, like JS.
-  private enumerableKeys(value: unknown, node: AstNode): Array<string> {
+  private enumerableKeys(value: Value, node: AstNode): Array<string> {
     if (value instanceof ToolReference) return [...this.ctx.tools.keys(value.path)]
     if (value === null || value === undefined) return []
     return keys(enumerableSource(this.ctx, "for...in", value, node))
@@ -1063,7 +1048,7 @@ class Frame<R> {
 
   private declarePattern(
     pattern: Pattern,
-    value: unknown,
+    value: Value,
     mutable: boolean,
     node: AstNode,
     initialize = false,
@@ -1123,7 +1108,7 @@ class Frame<R> {
     })
   }
 
-  private assignPattern(pattern: Pattern, value: unknown, node: AstNode): Effect.Effect<void, unknown, R> {
+  private assignPattern(pattern: Pattern, value: Value, node: AstNode): Effect.Effect<void, unknown, R> {
     const self = this
     return Effect.gen(function* () {
       if (pattern.type === "Identifier") {
@@ -1175,7 +1160,7 @@ class Frame<R> {
     })
   }
 
-  private evaluateDefault(pattern: AssignmentPattern): Effect.Effect<unknown, unknown, R> {
+  private evaluateDefault(pattern: AssignmentPattern): Effect.Effect<Value, unknown, R> {
     return pattern.left.type === "Identifier"
       ? this.evaluateNamed(pattern.right, pattern.left.name)
       : this.evaluateExpression(pattern.right)
@@ -1183,8 +1168,8 @@ class Frame<R> {
 
   private destructureArrayPattern(
     pattern: ArrayPattern,
-    value: unknown,
-    consume: (target: Pattern, value: unknown, context: AstNode) => Effect.Effect<void, unknown, R>,
+    value: Value,
+    consume: (target: Pattern, value: Value, context: AstNode) => Effect.Effect<void, unknown, R>,
   ): Effect.Effect<void, unknown, R> {
     const self = this
     return Effect.gen(function* () {
@@ -1208,7 +1193,7 @@ class Frame<R> {
         done = step.done
         if (element === null) continue
         if (element.type === "RestElement") {
-          const rest: Array<unknown> = []
+          const rest: Array<Value> = []
           if (!step.done) rest.push(step.value)
           while (!done) {
             const next = yield* cursor.next
@@ -1238,13 +1223,12 @@ class Frame<R> {
     throw unsupportedSyntax(keyNode.type, keyNode)
   }
 
-  private evaluateExpression(node: Expression): Effect.Effect<unknown, unknown, R> {
+  private evaluateExpression(node: Expression): Effect.Effect<Value, unknown, R> {
     switch (node.type) {
       case "Literal": {
         const regex = node.regex
         if (regex) return Effect.sync(() => constructRegExp(this.ctx.builtins, [regex.pattern, regex.flags]))
-        if (typeof node.value === "bigint") throw typeError("BigInt literals are not supported.", node)
-        return Effect.succeed(node.value)
+        return Effect.succeed(literal(node))
       }
       case "Identifier":
         return Effect.sync(() => this.scopes.get(node.name, node))
@@ -1259,7 +1243,7 @@ class Frame<R> {
       case "SequenceExpression": {
         const self = this
         return Effect.gen(function* () {
-          let result: unknown
+          let result: Value
           for (const expression of node.expressions) {
             result = yield* self.evaluateExpression(expression)
           }
@@ -1300,7 +1284,7 @@ class Frame<R> {
     }
   }
 
-  private evaluateNewExpression(node: NewExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateNewExpression(node: NewExpression): Effect.Effect<Value, unknown, R> {
     const self = this
     return Effect.gen(function* () {
       const callee = yield* self.evaluateExpression(node.callee)
@@ -1324,7 +1308,7 @@ class Frame<R> {
     })
   }
 
-  private evaluateBinaryExpression(node: BinaryExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateBinaryExpression(node: BinaryExpression): Effect.Effect<Value, unknown, R> {
     const operator = node.operator
     const left = node.left
     if (left.type === "PrivateIdentifier") throw unsupportedSyntax(left.type, left)
@@ -1337,7 +1321,7 @@ class Frame<R> {
     })
   }
 
-  private applyBinaryOperator(operator: string, lhs: unknown, rhs: unknown, node: AstNode): unknown {
+  private applyBinaryOperator(operator: string, lhs: Value, rhs: Value, node: AstNode): Value {
     if (operator === "===") return lhs === rhs
     if (operator === "!==") return lhs !== rhs
     if (operator === "in" && rhs instanceof Obj && !containsOpaqueReference(lhs)) {
@@ -1346,14 +1330,9 @@ class Frame<R> {
     if (containsOpaqueReference(lhs) || containsOpaqueReference(rhs)) {
       throw invalidData("Binary operators require data values.", node)
     }
-    // Null-prototype data needs explicit primitive coercion; identity and `in` retain raw objects.
-    // Dates use their default string hint for addition and loose equality, and epoch time elsewhere.
-    const coerceOperand = (operand: unknown): unknown => {
-      if (operand instanceof DateObj) {
-        return operator === "+" || operator === "==" || operator === "!=" ? coerceToString(operand) : operand.time
-      }
-      return operand !== null && typeof operand === "object" ? coerceToString(operand) : operand
-    }
+    // Addition and loose equality use the default hint; every other operator asks for a number.
+    const hint = operator === "+" || operator === "==" || operator === "!=" ? "default" : "number"
+    const coerceOperand = (operand: Value) => (operand instanceof Obj ? operand.toPrimitive(hint) : operand)
     const bothObjects = lhs !== null && typeof lhs === "object" && rhs !== null && typeof rhs === "object"
     const l = coerceOperand(lhs)
     const r = coerceOperand(rhs)
@@ -1407,7 +1386,7 @@ class Frame<R> {
     }
   }
 
-  private evaluateLogicalExpression(node: LogicalExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateLogicalExpression(node: LogicalExpression): Effect.Effect<Value, unknown, R> {
     const operator = node.operator
     return Effect.flatMap(this.evaluateExpression(node.left), (left) => {
       if (operator === "&&") return left ? this.evaluateExpression(node.right) : Effect.succeed(left)
@@ -1418,7 +1397,7 @@ class Frame<R> {
     })
   }
 
-  private evaluateUnaryExpression(node: UnaryExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateUnaryExpression(node: UnaryExpression): Effect.Effect<Value, unknown, R> {
     const operator = node.operator
     const argument = node.argument
     if (operator === "delete") return this.evaluateDeleteExpression(argument)
@@ -1433,13 +1412,8 @@ class Frame<R> {
       if (containsOpaqueReference(value)) {
         throw invalidData("Unary operators require data values.", node)
       }
-      const operand =
-        value instanceof DateObj
-          ? value.time
-          : value !== null && typeof value === "object"
-            ? coerceToString(value)
-            : value
-      let result: unknown
+      const operand = value instanceof Obj ? value.toPrimitive("number") : value
+      let result: Value
       switch (operator) {
         case "+":
           result = +(operand as number)
@@ -1457,7 +1431,7 @@ class Frame<R> {
     })
   }
 
-  private evaluateAssignmentExpression(node: AssignmentExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateAssignmentExpression(node: AssignmentExpression): Effect.Effect<Value, unknown, R> {
     const left = node.left
     const operator = node.operator
     const self = this
@@ -1497,9 +1471,9 @@ class Frame<R> {
     node: AssignmentExpression,
     left: Pattern,
     operator: string,
-  ): Effect.Effect<unknown, unknown, R> {
+  ): Effect.Effect<Value, unknown, R> {
     const self = this
-    const shouldAssign = (current: unknown): boolean =>
+    const shouldAssign = (current: Value): boolean =>
       operator === "??=" ? current === null || current === undefined : operator === "||=" ? !current : Boolean(current)
     if (left.type === "Identifier") {
       const name = left.name
@@ -1524,7 +1498,7 @@ class Frame<R> {
     throw typeError("Assignment target must be an Identifier or MemberExpression.", left)
   }
 
-  private evaluateUpdateExpression(node: UpdateExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateUpdateExpression(node: UpdateExpression): Effect.Effect<Value, unknown, R> {
     const operator = node.operator
     const argument = node.argument
     const prefix = node.prefix
@@ -1537,7 +1511,7 @@ class Frame<R> {
 
     // CodeMode numeric coercion, not host Number(): null-prototype data objects would make
     // the host throw during ToPrimitive, and opaque runtime references must reject clearly.
-    const operand = (current: unknown): number => {
+    const operand = (current: Value): number => {
       if (containsOpaqueReference(current)) {
         throw invalidData(`'${operator}' requires a data value.`, argument)
       }
@@ -1566,7 +1540,7 @@ class Frame<R> {
   }
 
   // EvaluateCall: a member callee supplies its base object as `this`; anything else calls with undefined.
-  private evaluateCallExpression(node: CallExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateCallExpression(node: CallExpression): Effect.Effect<Value, unknown, R> {
     const callee = node.callee
 
     const self = this
@@ -1584,7 +1558,7 @@ class Frame<R> {
     })
   }
 
-  private readMethod(node: MemberExpression): Effect.Effect<{ callable: unknown; thisValue: unknown }, unknown, R> {
+  private readMethod(node: MemberExpression): Effect.Effect<{ callable: Value; thisValue: Value }, unknown, R> {
     return Effect.map(this.getMemberReference(node), (reference) => {
       if (reference === OptionalShortCircuit) return { callable: OptionalShortCircuit, thisValue: undefined }
       if (reference instanceof ToolReference) return { callable: reference, thisValue: undefined }
@@ -1595,12 +1569,12 @@ class Frame<R> {
 
   // The single dispatch for every invocation: call expressions and callbacks share it.
   call(
-    callable: unknown,
-    thisValue: unknown,
-    args: Array<unknown>,
+    callable: Value,
+    thisValue: Value,
+    args: Array<Value>,
     node?: AstNode,
     callee?: Expression,
-  ): Effect.Effect<unknown, unknown, R> {
+  ): Effect.Effect<Value, unknown, R> {
     const self = this
     return Effect.gen(function* () {
       if (callable instanceof ToolReference) {
@@ -1618,7 +1592,7 @@ class Frame<R> {
   }
 
   // Built-ins throw without a location, synchronously or inside their Effect; the call site supplies it.
-  private native(body: () => Effect.Effect<unknown, unknown, R>, node?: AstNode): Effect.Effect<unknown, unknown, R> {
+  private native(body: () => Effect.Effect<Value, unknown, R>, node?: AstNode): Effect.Effect<Value, unknown, R> {
     return Effect.provideService(
       Effect.catchDefect(Effect.suspend(body), (defect) => Effect.die(locate(defect, node))),
       CallSite,
@@ -1628,10 +1602,10 @@ class Frame<R> {
 
   private evaluateCallArguments(
     argNodes: ReadonlyArray<Expression | SpreadElement>,
-  ): Effect.Effect<Array<unknown>, unknown, R> {
+  ): Effect.Effect<Array<Value>, unknown, R> {
     const self = this
     return Effect.gen(function* () {
-      const args: Array<unknown> = []
+      const args: Array<Value> = []
       for (const argNode of argNodes) {
         if (argNode.type === "SpreadElement") {
           const spread = yield* self.evaluateExpression(argNode.argument)
@@ -1651,7 +1625,7 @@ class Frame<R> {
   }
 
   // A callback invoked by a built-in runs below the call that invoked the built-in, so the deeper of the two counts.
-  invokeFunction(fn: Fn, args: Array<unknown>, node?: AstNode): Effect.Effect<unknown, unknown, R> {
+  invokeFunction(fn: Fn, args: Array<Value>, node?: AstNode): Effect.Effect<Value, unknown, R> {
     const self = this
     return Effect.flatMap(CallSite, (site) => {
       const depth = Math.max(self.depth, site.depth) + 1
@@ -1698,16 +1672,16 @@ class Frame<R> {
 
   private createGenerator(
     invocation: Frame<R>,
-    run: Effect.Effect<unknown, unknown, R>,
+    run: Effect.Effect<Value, unknown, R>,
     asynchronous: boolean,
   ): GeneratorObj {
     const state: GeneratorState = { started: false, completed: false, draining: false, pending: [], pendingIndex: 0 }
     invocation.generatorState = state
     invocation.generatorAsync = asynchronous
     const builtins = this.ctx.builtins
-    const result = (value: unknown, done: boolean) => record(builtins.Object, { value, done })
-    const request = (kind: GeneratorRequestKind, value: unknown) => {
-      const request = { kind, value, response: Deferred.makeUnsafe<unknown, unknown>() }
+    const result = (value: Value, done: boolean) => record(builtins.Object, { value, done })
+    const request = (kind: GeneratorRequestKind, value: Value) => {
+      const request = { kind, value, response: Deferred.makeUnsafe<Value, unknown>() }
       if (!asynchronous && state.active) return Effect.die(typeError("Generator is already running."))
       if (asynchronous && (state.completed || (!state.started && kind !== "next"))) {
         state.started = true
@@ -1778,7 +1752,7 @@ class Frame<R> {
 
   private completeGeneratorRequests(state: GeneratorState, asynchronous: boolean): Effect.Effect<void, never, R> {
     const self = this
-    const result = (value: unknown, done: boolean) => record(self.ctx.builtins.Object, { value, done })
+    const result = (value: Value, done: boolean) => record(self.ctx.builtins.Object, { value, done })
     return Effect.gen(function* () {
       while (true) {
         const pending = self.dequeueGeneratorRequest(state)
@@ -1824,7 +1798,7 @@ class Frame<R> {
     return request
   }
 
-  private evaluateYieldExpression(node: YieldExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateYieldExpression(node: YieldExpression): Effect.Effect<Value, unknown, R> {
     const argument = node.argument
     const self = this
     return Effect.gen(function* () {
@@ -1839,7 +1813,7 @@ class Frame<R> {
     })
   }
 
-  private suspendGenerator(value: unknown, node: AstNode): Effect.Effect<unknown, unknown, R> {
+  private suspendGenerator(value: Value, node: AstNode): Effect.Effect<Value, unknown, R> {
     const state = this.generatorState
     if (!state?.active) throw typeError("Generator has no active request.", node)
     Deferred.doneUnsafe(state.active.response, Exit.succeed(record(this.ctx.builtins.Object, { value, done: false })))
@@ -1854,20 +1828,11 @@ class Frame<R> {
     })
   }
 
-  private delegateYield(value: unknown, node: AstNode): Effect.Effect<unknown, unknown, R> {
+  private delegateYield(value: Value, node: AstNode): Effect.Effect<Value, unknown, R> {
     const self = this
     return Effect.gen(function* () {
-      if (
-        value instanceof Arr ||
-        typeof value === "string" ||
-        value instanceof MapObj ||
-        value instanceof SetObj ||
-        value instanceof URLSearchParamsObj ||
-        value instanceof HeadersObj ||
-        value instanceof Bytes
-      ) {
-        const cursor = yield* self.iterate(value, node)
-        if (!cursor) throw typeError("Built-in iterator is unavailable.", node)
+      const cursor = self.hostCursor(value)
+      if (cursor !== undefined) {
         while (true) {
           const step = yield* cursor.next
           if (step.done) return undefined
@@ -1891,7 +1856,7 @@ class Frame<R> {
       const iterator = yield* self.customIterator(value, node, self.generatorAsync)
       if (!iterator) throw typeError("yield* requires a compatible iterable value.", node)
       let kind: GeneratorRequestKind = "next"
-      let input: unknown = undefined
+      let input: Value = undefined
       while (true) {
         const method = kind === "next" ? iterator.next : get(iterator.iterator, kind)
         if (method === undefined || method === null) {
@@ -1911,7 +1876,7 @@ class Frame<R> {
           node,
         )
         const done = Boolean(get(result, "done"))
-        const resultValue: unknown =
+        const resultValue: Value =
           self.generatorAsync && !iterator.asynchronous
             ? yield* self.awaitAsyncFromSyncValue(iterator, get(result, "value"), node, kind !== "return" && !done)
             : get(result, "value")
@@ -1920,7 +1885,7 @@ class Frame<R> {
           return resultValue
         }
 
-        const resumed: Exit.Exit<unknown, unknown> = yield* Effect.exit(self.suspendGenerator(resultValue, node))
+        const resumed: Exit.Exit<Value, unknown> = yield* Effect.exit(self.suspendGenerator(resultValue, node))
         if (Exit.isSuccess(resumed)) {
           kind = "next"
           input = resumed.value
@@ -1961,7 +1926,7 @@ class Frame<R> {
         } else if (keyNode.type === "Identifier") {
           key = keyNode.name
         } else if (keyNode.type === "Literal") {
-          key = self.toPropertyKey(keyNode.value, keyNode)
+          key = self.toPropertyKey(literal(keyNode), keyNode)
         } else {
           throw typeError("Unsupported object property key shape.", keyNode)
         }
@@ -1980,7 +1945,7 @@ class Frame<R> {
   }
 
   private evaluateArrayExpression(node: ArrayExpression): Effect.Effect<Arr, unknown, R> {
-    const values: Array<unknown> = []
+    const values: Array<Value> = []
 
     const self = this
     return Effect.gen(function* () {
@@ -2035,13 +2000,13 @@ class Frame<R> {
     })
   }
 
-  private evaluateConditionalExpression(node: ConditionalExpression): Effect.Effect<unknown, unknown, R> {
+  private evaluateConditionalExpression(node: ConditionalExpression): Effect.Effect<Value, unknown, R> {
     return Effect.flatMap(this.evaluateExpression(node.test), (test) =>
       this.evaluateExpression(test ? node.consequent : node.alternate),
     )
   }
 
-  private applyCompoundAssignment(operator: string, current: unknown, incoming: unknown, node: AstNode): unknown {
+  private applyCompoundAssignment(operator: string, current: Value, incoming: Value, node: AstNode): Value {
     if (!compoundOperators.has(operator)) {
       throw typeError(`Unsupported assignment operator '${operator}'.`, node)
     }
@@ -2050,7 +2015,7 @@ class Frame<R> {
 
   private getMemberReference(
     node: MemberExpression,
-  ): Effect.Effect<MemberReference | ToolReference | { value: unknown } | typeof OptionalShortCircuit, unknown, R> {
+  ): Effect.Effect<MemberReference | ToolReference | { value: Value } | typeof OptionalShortCircuit, unknown, R> {
     const objectNode = node.object
     const propertyNode = node.property
     if (objectNode.type === "Super") throw unsupportedSyntax(objectNode.type, objectNode)
@@ -2092,7 +2057,7 @@ class Frame<R> {
     })
   }
 
-  private readReference(reference: MemberReference, node: MemberExpression): unknown {
+  private readReference(reference: MemberReference, node: MemberExpression): Value {
     // Reject unknown promise properties so a missing await cannot hide.
     if (reference.target instanceof PromiseObj && !has(reference.target, reference.key)) {
       throw invalidData(
@@ -2104,7 +2069,7 @@ class Frame<R> {
   }
 
   // Accessors throw without a location; the member or pattern that read them supplies it.
-  private readProperty(target: Obj, key: PropertyKey, node: AstNode, receiver: unknown = target): unknown {
+  private readProperty(target: Obj, key: PropertyKey, node: AstNode, receiver: Value = target): Value {
     try {
       return get(target, key, receiver)
     } catch (error) {
@@ -2112,7 +2077,7 @@ class Frame<R> {
     }
   }
 
-  private readMember(node: MemberExpression): Effect.Effect<unknown, unknown, R> {
+  private readMember(node: MemberExpression): Effect.Effect<Value, unknown, R> {
     return Effect.map(this.getMemberReference(node), (reference) => {
       if (reference === OptionalShortCircuit) return OptionalShortCircuit
       if (reference instanceof ToolReference) return reference
@@ -2121,7 +2086,7 @@ class Frame<R> {
     })
   }
 
-  private writeMember(node: MemberExpression, value: unknown): Effect.Effect<unknown, unknown, R> {
+  private writeMember(node: MemberExpression, value: Value): Effect.Effect<Value, unknown, R> {
     return this.modifyMember(node, () => Effect.succeed({ write: true, next: value, result: value }))
   }
 
@@ -2143,8 +2108,8 @@ class Frame<R> {
   // Resolve side-effecting object and key expressions exactly once.
   private modifyMember(
     node: MemberExpression,
-    compute: (current: unknown) => Effect.Effect<{ write: boolean; next: unknown; result: unknown }, unknown, R>,
-  ): Effect.Effect<unknown, unknown, R> {
+    compute: (current: Value) => Effect.Effect<{ write: boolean; next: Value; result: Value }, unknown, R>,
+  ): Effect.Effect<Value, unknown, R> {
     const self = this
     return Effect.gen(function* () {
       const reference = yield* self.getMemberReference(node)
@@ -2164,7 +2129,7 @@ class Frame<R> {
     })
   }
 
-  private assignToReference(target: Obj, key: PropertyKey, next: unknown, node: AstNode): void {
+  private assignToReference(target: Obj, key: PropertyKey, next: Value, node: AstNode): void {
     const written = (() => {
       try {
         rejectCircularInsertion(
@@ -2182,7 +2147,7 @@ class Frame<R> {
     throw typeError(`Cannot assign to read only property '${String(key)}'.`, node)
   }
 
-  private toPropertyKey(value: unknown, node: AstNode): PropertyKey {
+  private toPropertyKey(value: Value, node: AstNode): PropertyKey {
     if (typeof value === "string" || typeof value === "number") {
       return value
     }

packages/codemode/src/interpreter/intrinsics.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect"
-import { define, hidden, Native, Arr, ErrorObj, Obj } from "./objects.js"
+import { define, hidden, Native, Arr, ErrorObj, Obj, type Value } from "./objects.js"
 
 export const errorTypes = [
   "Error",
@@ -53,7 +53,7 @@ export const createErrorValue = (prototype: Obj, message: string | undefined): E
 }
 
 /** The prototype a primitive reads its methods from without being boxed; none for null, undefined, and symbols. */
-export const primitivePrototype = (builtins: Builtins, value: unknown): Obj | undefined => {
+export const primitivePrototype = (builtins: Builtins, value: Value): Obj | undefined => {
   if (typeof value === "string") return builtins.String
   if (typeof value === "number") return builtins.Number
   if (typeof value === "boolean") return builtins.Boolean

packages/codemode/src/interpreter/model.ts

@@ -2,7 +2,7 @@ import type { Node } from "acorn"
 import { Context } from "effect"
 import type { ErrorType } from "./intrinsics.js"
 import type { DiagnosticKind } from "../codemode.js"
-import type { ErrorObj } from "./objects.js"
+import type { ErrorObj, Value } from "./objects.js"
 
 /** Any parsed node; the interpreter narrows on `type` and reads `loc` for diagnostics. */
 export type AstNode = Node
@@ -14,13 +14,13 @@ export const CallSite = Context.Reference<{ readonly node?: AstNode; readonly de
 
 export type Binding = {
   mutable: boolean
-  value: unknown
+  value: Value
   initialized?: boolean
 }
 
 export type StatementResult =
   | { kind: "none" }
-  | { kind: "return"; value: unknown }
+  | { kind: "return"; value: Value }
   | { kind: "break"; label?: string }
   | { kind: "continue"; label?: string }
 
@@ -31,11 +31,11 @@ export const IteratorSymbol: unique symbol = Symbol("codemode.iterator")
 export const IteratorSymbols = [AsyncIteratorSymbol, IteratorSymbol] as const
 
 export class Throw {
-  constructor(readonly value: unknown) {}
+  constructor(readonly value: Value) {}
 }
 
 export class GeneratorReturn {
-  constructor(readonly value: unknown) {}
+  constructor(readonly value: Value) {}
 }
 
 export const OptionalShortCircuit: unique symbol = Symbol("codemode.optional-short-circuit")
@@ -83,9 +83,6 @@ export const unsupportedSyntax = (kind: string, node: AstNode): PendingThrow =>
     [supportedSyntaxMessage],
   )
 
-export const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null
-
 // Acorn lines are 1-based and its columns are 0-based. Diagnostics use 1-based columns of the submitted source.
 export const sourceLocation = (node: AstNode): { readonly line: number; readonly column: number } => ({
   line: node.loc?.start.line ?? 1,

packages/codemode/src/interpreter/native.ts

@@ -1,18 +1,18 @@
 import { Effect } from "effect"
 import type { Builtins } from "./intrinsics.js"
 import { typeError } from "./model.js"
-import { type Callable, define, frozen, hidden, Native, type NativeOptions, Obj } from "./objects.js"
+import { type Callable, define, frozen, hidden, Native, type NativeOptions, Obj, type Value } from "./objects.js"
 import { describeValue } from "./references.js"
 
-/** A native function body: a plain value, a thrown `PendingThrow`, or an Effect. */
-export type Impl = (thisValue: unknown, args: Array<unknown>) => unknown
+/** A native function body: a value, a thrown `PendingThrow`, or an Effect of a value. */
+export type Impl = (thisValue: Value, args: Array<Value>) => Value | Effect.Effect<Value, unknown, unknown>
 
 // The dispatch in `Frame.call` suspends every native call, so a synchronous throw here is a defect.
 const lift =
   <R>(impl: Impl) =>
-  (thisValue: unknown, args: Array<unknown>): Effect.Effect<unknown, unknown, R> => {
+  (thisValue: Value, args: Array<Value>): Effect.Effect<Value, unknown, R> => {
     const result = impl(thisValue, args)
-    return Effect.isEffect(result) ? (result as Effect.Effect<unknown, unknown, R>) : Effect.succeed(result)
+    return Effect.isEffect(result) ? (result as Effect.Effect<Value, unknown, R>) : Effect.succeed(result)
   }
 
 export const native = <R>(builtins: Builtins, options: NativeOptions<R>): Native<R> =>
@@ -27,7 +27,7 @@ export const methods = (builtins: Builtins, target: Obj, table: ReadonlyArray<Me
   for (const [name, length, impl] of table) define(target, name, fn(builtins, name, length, impl), hidden)
 }
 
-export const constants = (target: Obj, table: Record<string, unknown>): void => {
+export const constants = (target: Obj, table: Record<string, Value>): void => {
   for (const [name, value] of Object.entries(table)) define(target, name, value, frozen)
 }
 
@@ -54,7 +54,7 @@ export const prototypeFrom = (newTarget: Callable, fallback: Obj): Obj => {
 /** Narrows a method receiver to the built-in it belongs to, or throws the TypeError JS would. */
 export const receiver = <T extends Obj>(
   cls: abstract new (...args: never) => T,
-  thisValue: unknown,
+  thisValue: Value,
   method: string,
 ): T => {
   if (thisValue instanceof cls) return thisValue

packages/codemode/src/interpreter/objects.ts

@@ -1,5 +1,7 @@
 import type { BlockStatement, Expression, Pattern } from "acorn"
 import type { Effect, Fiber } from "effect"
+import { ToolReference } from "../tool-runtime.js"
+import type { Builtins } from "./intrinsics.js"
 import { checkArrayLength } from "./limits.js"
 import {
   AsyncIteratorSymbol,
@@ -16,12 +18,12 @@ export type Attributes = {
   readonly configurable: boolean
 }
 
-export type Getter = (receiver: unknown) => unknown
-export type Setter = (receiver: unknown, value: unknown) => void
+export type Getter = (receiver: Value) => Value
+export type Setter = (receiver: Value, value: Value) => void
 
 /** One own property: a data slot or a native accessor pair. */
 export type Slot =
-  | { value: unknown; writable: boolean; enumerable: boolean; configurable: boolean }
+  | { value: Value; writable: boolean; enumerable: boolean; configurable: boolean }
   | { get: Getter | undefined; set: Setter | undefined; enumerable: boolean; configurable: boolean }
 
 /** Ordinary assignment: writable, enumerable, configurable. */
@@ -33,33 +35,119 @@ export const readonly: Attributes = { writable: false, enumerable: false, config
 /** Constants such as `Math.PI` and a constructor's `prototype`. */
 export const frozen: Attributes = { writable: false, enumerable: false, configurable: false }
 
-/** An object owned by the program: own properties plus a prototype link. */
+/**
+ * An object owned by the program: own properties plus a prototype link. Subclasses answer, in one place, how a
+ * built-in kind of object prints, coerces, iterates, and crosses to the host.
+ */
 export class Obj {
   readonly props = new Map<string | symbol, Slot>()
   constructor(public proto: Obj | null) {}
+
+  /** The class name `Object.prototype.toString` reports: `[object Map]`. */
+  readonly tag: string = "Object"
+
+  /** How diagnostics refer to a value of this kind. */
+  get describe(): string {
+    if (this.tag === "Object") return "a data object"
+    return `${/^[AEIO]/.test(this.tag) ? "an" : "a"} ${this.tag}`
+  }
+
+  /** ToString without consulting program-defined methods. */
+  toString(): string {
+    return `[object ${this.tag}]`
+  }
+
+  /** ToPrimitive without consulting program-defined methods: only a Date answers a number hint differently. */
+  toPrimitive(hint: "default" | "number" | "string"): string | number {
+    return this.toString()
+  }
+
+  /** ToNumber without consulting program-defined methods. */
+  toNumber(): number {
+    return Number(this.toPrimitive("number"))
+  }
+
+  /** How `console.log` shows the value; `item` formats a child with cycle and depth tracking. */
+  inspect(item: (value: Value) => string): string {
+    return `{${entries(this)
+      .map(([key, value]) => `${JSON.stringify(key)}:${item(value)}`)
+      .join(",")}}`
+  }
+
+  /** A copy the host can hold; `item` converts a child. A `__proto__` key never reaches host code. */
+  toHost(item: (value: Value) => unknown): unknown {
+    return Object.fromEntries(
+      entries(this)
+        .filter(([key]) => key !== "__proto__")
+        .map(([key, value]) => [key, item(value)]),
+    )
+  }
+
+  /** The built-in iteration `for...of` and spread use, when this kind of object has one. */
+  iterator(builtins: Builtins): Iterator<Value, undefined> | undefined {
+    return undefined
+  }
 }
 
 export class Arr extends Obj {
+  override readonly tag = "Array"
   constructor(
     proto: Obj,
-    readonly items: Array<unknown> = [],
+    readonly items: Array<Value> = [],
   ) {
     super(proto)
   }
+  override get describe() {
+    return "an array"
+  }
+  override toString() {
+    return this.items.map((item) => (item === null || item === undefined ? "" : coerceToString(item))).join(",")
+  }
+  override inspect(item: (value: Value) => string) {
+    return `[${this.items.map(item).join(",")}]`
+  }
+  override toHost(item: (value: Value) => unknown) {
+    return this.items.map(item)
+  }
+  override iterator() {
+    return this.items.values()
+  }
 }
 
 /** An object with the [[ErrorData]] slot: what `Error.prototype.toString` and the host boundary recognize as an error. */
 export class ErrorObj extends Obj {
+  override readonly tag = "Error"
   /** The interpreter failure this error materialized from, so rethrowing it keeps the diagnostic kind and location. */
   host?: PendingThrow
+  /** Error.prototype.toString: "name: message", or just one when the other is empty. */
+  override toString() {
+    const name = get(this, "name")
+    const message = get(this, "message")
+    const shownName = typeof name === "string" ? name : "Error"
+    const shownMessage = typeof message === "string" ? message : ""
+    if (shownMessage === "") return shownName
+    if (shownName === "") return shownMessage
+    return `${shownName}: ${shownMessage}`
+  }
 }
 
-export abstract class Callable extends Obj {
+/** Interpreter machinery a program can hold but never inspect, serialize, or hand to the host. */
+export abstract class Opaque extends Obj {
+  override inspect() {
+    return "[opaque reference]"
+  }
+}
+
+export abstract class Callable extends Opaque {
+  override readonly tag = "Function"
   constructor(proto: Obj, name: string, length: number) {
     super(proto)
     define(this, "length", length, readonly)
     define(this, "name", name, readonly)
   }
+  override get describe() {
+    return "a function"
+  }
 }
 
 export class Fn extends Callable {
@@ -77,8 +165,8 @@ export class Fn extends Callable {
   }
 }
 
-export type NativeCall<R> = (thisValue: unknown, args: Array<unknown>) => Effect.Effect<unknown, unknown, R>
-export type NativeConstruct<R> = (args: Array<unknown>, newTarget: Callable) => Effect.Effect<unknown, unknown, R>
+export type NativeCall<R> = (thisValue: Value, args: Array<Value>) => Effect.Effect<Value, unknown, R>
+export type NativeConstruct<R> = (args: Array<Value>, newTarget: Callable) => Effect.Effect<Value, unknown, R>
 
 export type NativeOptions<R> = {
   readonly name: string
@@ -103,79 +191,163 @@ export class Native<R = never> extends Callable {
   }
 }
 
-export class PromiseObj extends Obj {
+export class PromiseObj extends Opaque {
+  override readonly tag = "Promise"
   constructor(
     proto: Obj,
-    readonly fiber: Fiber.Fiber<unknown, unknown>,
+    readonly fiber: Fiber.Fiber<Value, unknown>,
   ) {
     super(proto)
   }
+  override get describe() {
+    return "an un-awaited Promise"
+  }
+  override inspect() {
+    return "[Promise (await it to get its value)]"
+  }
 }
 
-export class GeneratorObj extends Obj {
+export class GeneratorObj extends Opaque {
+  override readonly tag = "Generator"
   constructor(
     proto: Obj,
     readonly asynchronous: boolean,
-    readonly request: (kind: GeneratorRequestKind, value: unknown) => Effect.Effect<unknown, unknown, unknown>,
+    readonly request: (kind: GeneratorRequestKind, value: Value) => Effect.Effect<Value, unknown, unknown>,
   ) {
     super(proto)
   }
+  override get describe() {
+    return "a generator"
+  }
 }
 
 /** A built-in collection iterator: live over the host collection, yielding program values. */
-export class IteratorObj extends Obj {
+export class IteratorObj extends Opaque {
+  override readonly tag = "Iterator"
   constructor(
     proto: Obj,
-    readonly iterator: IteratorObject<unknown>,
+    readonly source: IteratorObject<Value, undefined>,
   ) {
     super(proto)
   }
+  override get describe() {
+    return "an iterator"
+  }
+  override iterator() {
+    return this.source
+  }
 }
 
-export class DateObj extends Obj {
+/** A built-in object around a host value: data-like, so it prints as itself and crosses to extensions as a copy. */
+export abstract class Wrapper extends Obj {
+  override inspect(item: (value: Value) => string) {
+    return this.toString()
+  }
+}
+
+export class DateObj extends Wrapper {
+  override readonly tag = "Date"
   constructor(
     proto: Obj,
     public time: number,
   ) {
     super(proto)
   }
+  override toString() {
+    return Number.isFinite(this.time) ? new Date(this.time).toISOString() : "Invalid Date"
+  }
+  override toPrimitive(hint: "default" | "number" | "string") {
+    return hint === "number" ? this.time : this.toString()
+  }
+  override toHost() {
+    return new Date(this.time)
+  }
 }
 
-export class RegExpObj extends Obj {
+export class RegExpObj extends Wrapper {
+  override readonly tag = "RegExp"
   readonly regex: RegExp
   constructor(proto: Obj, pattern: string, flags: string) {
     super(proto)
     this.regex = new RegExp(pattern, flags)
   }
+  override toString() {
+    return `/${this.regex.source}/${this.regex.flags}`
+  }
+  override toHost() {
+    return new RegExp(this.regex.source, this.regex.flags)
+  }
 }
 
-export class MapObj extends Obj {
-  readonly map = new Map<unknown, unknown>()
+export class MapObj extends Wrapper {
+  override readonly tag = "Map"
+  readonly map = new Map<Value, Value>()
+  override inspect(item: (value: Value) => string) {
+    return `Map(${this.map.size}) [${[...this.map].map(([key, value]) => `[${item(key)},${item(value)}]`).join(",")}]`
+  }
+  override toHost(item: (value: Value) => unknown) {
+    return new Map([...this.map].map(([key, value]) => [item(key), item(value)]))
+  }
+  override iterator(builtins: Builtins) {
+    return this.map.entries().map((entry) => new Arr(builtins.Array, entry))
+  }
 }
 
-export class SetObj extends Obj {
-  readonly set = new Set<unknown>()
+export class SetObj extends Wrapper {
+  override readonly tag = "Set"
+  readonly set = new Set<Value>()
+  override inspect(item: (value: Value) => string) {
+    return `Set(${this.set.size}) [${[...this.set].map(item).join(",")}]`
+  }
+  override toHost(item: (value: Value) => unknown) {
+    return new Set([...this.set].map(item))
+  }
+  override iterator() {
+    return this.set.values()
+  }
 }
 
-export class URLSearchParamsObj extends Obj {
+export class URLSearchParamsObj extends Wrapper {
+  override readonly tag = "URLSearchParams"
   constructor(
     proto: Obj,
     readonly params: URLSearchParams,
   ) {
     super(proto)
   }
+  override toString() {
+    return this.params.toString()
+  }
+  override toHost() {
+    return new URLSearchParams(this.params)
+  }
+  override iterator(builtins: Builtins) {
+    return this.params.entries().map((entry) => new Arr(builtins.Array, entry))
+  }
 }
 
-export class HeadersObj extends Obj {
+export class HeadersObj extends Wrapper {
+  override readonly tag = "Headers"
   constructor(
     proto: Obj,
     readonly headers: Headers,
   ) {
     super(proto)
   }
+  override inspect() {
+    return `Headers ${JSON.stringify(Object.fromEntries(this.headers))}`
+  }
+  override toHost() {
+    return new Headers(this.headers)
+  }
+  override iterator(builtins: Builtins) {
+    // Bun's Headers typings lack the iterator helpers, so the host iterator is lifted first.
+    return Iterator.from(this.headers.entries()).map((entry) => new Arr(builtins.Array, entry))
+  }
 }
 
-export class URLObj extends Obj {
+export class URLObj extends Wrapper {
+  override readonly tag = "URL"
   readonly searchParams: URLSearchParamsObj
   constructor(
     proto: Obj,
@@ -185,30 +357,52 @@ export class URLObj extends Obj {
     super(proto)
     this.searchParams = new URLSearchParamsObj(searchParamsProto, url.searchParams)
   }
+  override toString() {
+    return this.url.href
+  }
+  override toHost() {
+    return new URL(this.url.href)
+  }
 }
 
 /** A `Uint8Array`: the host array does the byte clamping and ignores out-of-range writes, as JS does. */
-export class Bytes extends Obj {
+export class Bytes extends Wrapper {
+  override readonly tag = "Uint8Array"
   constructor(
     proto: Obj,
     readonly bytes: Uint8Array,
   ) {
     super(proto)
   }
+  override toString() {
+    return this.bytes.join(",")
+  }
+  override inspect() {
+    return `Uint8Array(${this.bytes.length}) [${this.bytes.join(",")}]`
+  }
+  override toHost() {
+    return new Uint8Array(this.bytes)
+  }
+  override iterator() {
+    return this.bytes.values()
+  }
 }
 
-/** Built-in objects that wrap a host value; data-like, but never plain data. */
-export const isWrapper = (
-  value: unknown,
-): value is DateObj | RegExpObj | MapObj | SetObj | URLObj | URLSearchParamsObj | HeadersObj | Bytes =>
-  value instanceof DateObj ||
-  value instanceof RegExpObj ||
-  value instanceof MapObj ||
-  value instanceof SetObj ||
-  value instanceof URLObj ||
-  value instanceof URLSearchParamsObj ||
-  value instanceof HeadersObj ||
-  value instanceof Bytes
+/** Every value a program can hold. Host values never appear here; they are copied in at the boundaries. */
+export type Value = string | number | boolean | null | undefined | symbol | Obj | ToolReference
+
+/** ToString without consulting program-defined methods. */
+export const coerceToString = (value: Value): string => (value instanceof Obj ? value.toString() : String(value))
+
+/** ToNumber without consulting program-defined methods; tool references are not numbers. */
+export const coerceToNumber = (value: Value): number => {
+  if (value instanceof Obj) return value.toNumber()
+  return value instanceof ToolReference ? Number.NaN : Number(value)
+}
+
+/** Values that cannot cross the data boundary: opaque machinery and host-backed wrappers. */
+export const isRuntimeReference = (value: Value): boolean =>
+  value instanceof Opaque || value instanceof Wrapper || value instanceof ToolReference
 
 const MAX_ARRAY_INDEX = 4_294_967_295
 
@@ -226,7 +420,7 @@ type Indexed = Arr | Bytes
 
 const isIndexed = (target: Obj): target is Indexed => target instanceof Arr || target instanceof Bytes
 
-const elements = (target: Indexed): Array<unknown> | Uint8Array => (target instanceof Arr ? target.items : target.bytes)
+const elements = (target: Indexed): Array<Value> | Uint8Array => (target instanceof Arr ? target.items : target.bytes)
 
 const index = (target: Obj, key: string | symbol): number | undefined =>
   isIndexed(target) && typeof key === "string" ? parseArrayIndex(key) : undefined
@@ -247,18 +441,18 @@ export const own = (target: Obj, key: PropertyKey): Slot | undefined => {
   return target.props.get(name)
 }
 
-const read = (slot: Slot, receiver: unknown): unknown =>
+const read = (slot: Slot, receiver: Value): Value =>
   "value" in slot ? slot.value : slot.get === undefined ? undefined : slot.get(receiver)
 
 export const hasOwn = (target: Obj, key: PropertyKey): boolean => own(target, key) !== undefined
 
-export const getOwn = (target: Obj, key: PropertyKey): unknown => {
+export const getOwn = (target: Obj, key: PropertyKey): Value => {
   const slot = own(target, key)
   return slot === undefined ? undefined : read(slot, target)
 }
 
 /** [[Get]]: walks the prototype chain; accessors see `receiver`, which is the primitive for wrapper prototypes. */
-export const get = (target: Obj, key: PropertyKey, receiver: unknown = target): unknown => {
+export const get = (target: Obj, key: PropertyKey, receiver: Value = target): Value => {
   for (let current: Obj | null = target; current !== null; current = current.proto) {
     const slot = own(current, key)
     if (slot !== undefined) return read(slot, receiver)
@@ -273,14 +467,14 @@ export const has = (target: Obj, key: PropertyKey): boolean => {
   return false
 }
 
-export const hasPrototype = (value: unknown, proto: Obj): boolean => {
+export const hasPrototype = (value: Value, proto: Obj): boolean => {
   for (let current = value instanceof Obj ? value.proto : null; current !== null; current = current.proto) {
     if (current === proto) return true
   }
   return false
 }
 
-const writeElement = (target: Indexed, name: string | symbol, value: unknown): boolean | undefined => {
+const writeElement = (target: Indexed, name: string | symbol, value: Value): boolean | undefined => {
   const at = index(target, name)
   if (at !== undefined) {
     if (target instanceof Bytes) target.bytes[at] = typeof value === "number" ? value : Number(value)
@@ -296,7 +490,7 @@ const writeElement = (target: Indexed, name: string | symbol, value: unknown): b
 }
 
 /** [[Set]]: an inherited setter or read-only property decides before an own data property is created. */
-export const set = (target: Obj, key: PropertyKey, value: unknown): boolean => {
+export const set = (target: Obj, key: PropertyKey, value: Value): boolean => {
   const name = canonical(key)
   for (let current: Obj | null = target; current !== null; current = current.proto) {
     const slot = own(current, name)
@@ -324,7 +518,7 @@ export const set = (target: Obj, key: PropertyKey, value: unknown): boolean => {
 }
 
 /** [[DefineOwnProperty]] for a data property, ignoring the chain. */
-export const define = (target: Obj, key: PropertyKey, value: unknown, attrs: Attributes = data): void => {
+export const define = (target: Obj, key: PropertyKey, value: Value, attrs: Attributes = data): void => {
   const name = canonical(key)
   if (isIndexed(target) && writeElement(target, name, value) !== undefined) return
   target.props.set(name, { value, ...attrs })
@@ -375,9 +569,9 @@ export const keys = (target: Obj): Array<string> =>
   ownKeys(target).filter((key): key is string => typeof key === "string" && enumerable(target, key))
 
 /** Own enumerable string entries: `Object.entries` and serialization. */
-export const entries = (target: Obj): Array<[string, unknown]> => keys(target).map((key) => [key, getOwn(target, key)])
+export const entries = (target: Obj): Array<[string, Value]> => keys(target).map((key) => [key, getOwn(target, key)])
 
-export const record = (proto: Obj, fields: Record<string, unknown>): Obj => {
+export const record = (proto: Obj, fields: Record<string, Value>): Obj => {
   const target = new Obj(proto)
   for (const [key, value] of Object.entries(fields)) define(target, key, value)
   return target

packages/codemode/src/interpreter/promises.ts

@@ -2,7 +2,7 @@ import { Cause, Deferred, Effect, Exit, Fiber, Scope } from "effect"
 import type { Diagnostic } from "../codemode.js"
 import { MAX_PENDING_PROMISES } from "./limits.js"
 import { CallSite, Throw, rangeError, typeError } from "./model.js"
-import { Callable, define, get, hidden, Arr, Fn, Obj, PromiseObj, record } from "./objects.js"
+import { Callable, define, get, hidden, Arr, Fn, Obj, PromiseObj, record, type Value } from "./objects.js"
 import { constructor, fn, methods, native, receiver, requiresNew } from "./native.js"
 import { createAggregateErrorValue, locate, materialize, normalizeError } from "./errors.js"
 import { typeofValue } from "./references.js"
@@ -10,7 +10,7 @@ import { applyCollectionCallback, isSupportedCallback } from "./callback.js"
 import type { Interpreter } from "./interpreter.js"
 
 // A `resolve`/`reject` handed to an executor or thenable: calling it settles the capability.
-const capability = <R>(ctx: Interpreter<R>, name: string, settle: (value: unknown) => void) =>
+const capability = <R>(ctx: Interpreter<R>, name: string, settle: (value: Value) => void) =>
   fn(ctx.builtins, name, 1, (_, args) => {
     settle(args[0])
     return undefined
@@ -31,7 +31,7 @@ export class Pending<R> {
 
   // Resolution bodies need the promise's own identity to reject `resolve(promise)` self-resolution.
   createWithSelf(
-    body: (self: { promise?: PromiseObj }) => Effect.Effect<unknown, unknown, R>,
+    body: (self: { promise?: PromiseObj }) => Effect.Effect<Value, unknown, R>,
   ): Effect.Effect<PromiseObj, never, R> {
     const self: { promise?: PromiseObj } = {}
     return Effect.map(this.create(body(self)), (promise) => {
@@ -40,7 +40,7 @@ export class Pending<R> {
     })
   }
 
-  create(effect: Effect.Effect<unknown, unknown, R>): Effect.Effect<PromiseObj, never, R> {
+  create(effect: Effect.Effect<Value, unknown, R>): Effect.Effect<PromiseObj, never, R> {
     return Effect.flatMap(CallSite, (site) => {
       if (this.active.size >= MAX_PENDING_PROMISES) {
         throw rangeError(
@@ -79,7 +79,7 @@ export class Pending<R> {
     if (id !== undefined) this.failures.delete(id)
   }
 
-  await(promise: PromiseObj): Effect.Effect<Exit.Exit<unknown, unknown>> {
+  await(promise: PromiseObj): Effect.Effect<Exit.Exit<Value, unknown>> {
     return Fiber.await(promise.fiber)
   }
 
@@ -105,9 +105,9 @@ export class Pending<R> {
 
 export const resolvePromiseValue = <R>(
   ctx: Interpreter<R>,
-  value: unknown,
+  value: Value,
   own?: { promise?: PromiseObj },
-): Effect.Effect<unknown, unknown, R> => {
+): Effect.Effect<Value, unknown, R> => {
   if (own?.promise !== undefined && value === own.promise) {
     return Effect.die(typeError("Chaining cycle detected: a promise cannot resolve with itself."))
   }
@@ -119,7 +119,7 @@ export const resolvePromiseValue = <R>(
   return Effect.gen(function* () {
     // Promise resolution invokes a thenable's method in a later job.
     yield* Effect.yieldNow
-    const deferred = Deferred.makeUnsafe<unknown, unknown>()
+    const deferred = Deferred.makeUnsafe<Value, unknown>()
     const resolve = capability(ctx, "resolve", (result) => Deferred.doneUnsafe(deferred, Exit.succeed(result)))
     const reject = capability(ctx, "reject", (reason) => Deferred.doneUnsafe(deferred, Exit.fail(new Throw(reason))))
     const executed = yield* Effect.exit(ctx.call(then, value, [resolve, reject]))
@@ -131,7 +131,7 @@ export const resolvePromiseValue = <R>(
   })
 }
 
-export const resolvePromise = <R>(ctx: Interpreter<R>, value: unknown): Effect.Effect<PromiseObj, never, R> => {
+export const resolvePromise = <R>(ctx: Interpreter<R>, value: Value): Effect.Effect<PromiseObj, never, R> => {
   if (value instanceof PromiseObj) return Effect.succeed(value)
   return ctx.pending.createWithSelf((self) => resolvePromiseValue(ctx, value, self))
 }
@@ -141,8 +141,8 @@ const promiseStatics = ["all", "allSettled", "race", "any", "resolve", "reject"]
 const invokePromiseMethod = <R>(
   ctx: Interpreter<R>,
   name: (typeof promiseStatics)[number],
-  args: Array<unknown>,
-): Effect.Effect<unknown, unknown, R> => {
+  args: Array<Value>,
+): Effect.Effect<Value, unknown, R> => {
   if (name === "resolve") {
     return resolvePromise(ctx, args[0])
   }
@@ -175,7 +175,7 @@ const invokePromiseMethod = <R>(
         )
       }
       if (name === "allSettled") {
-        const outcomes: Array<unknown> = []
+        const outcomes: Array<Value> = []
         for (const item of items) {
           const exit = yield* ctx.pending.await(item)
           if (Exit.isSuccess(exit)) {
@@ -223,8 +223,8 @@ const invokePromiseMethod = <R>(
 const instanceMethod = <R>(
   ctx: Interpreter<R>,
   name: "then" | "catch" | "finally",
-  thisValue: unknown,
-  args: Array<unknown>,
+  thisValue: Value,
+  args: Array<Value>,
 ): Effect.Effect<PromiseObj, unknown, R> => {
   const method = `Promise.prototype.${name}`
   const promise = receiver(PromiseObj, thisValue, method)
@@ -237,12 +237,12 @@ const instanceMethod = <R>(
   return chainReaction(ctx, promise, onFulfilled, onRejected, method)
 }
 
-const constructPromise = <R>(ctx: Interpreter<R>, executor: unknown): Effect.Effect<PromiseObj, unknown, R> => {
+const constructPromise = <R>(ctx: Interpreter<R>, executor: Value): Effect.Effect<PromiseObj, unknown, R> => {
   if (!(executor instanceof Fn)) {
     throw typeError("new Promise(...) expects an executor function (e.g. new Promise((resolve, reject) => { ... })).")
   }
   return Effect.gen(function* () {
-    const deferred = Deferred.makeUnsafe<unknown, unknown>()
+    const deferred = Deferred.makeUnsafe<Value, unknown>()
     const promise = yield* ctx.pending.createWithSelf((self) =>
       Effect.flatMap(Deferred.await(deferred), (value) => resolvePromiseValue(ctx, value, self)),
     )
@@ -262,10 +262,10 @@ const settleAfterTurn = <A, E, R>(body: Effect.Effect<A, E, R>): Effect.Effect<A
   Effect.flatMap(Effect.exit(body), (exit) => Effect.andThen(Effect.yieldNow, exit))
 
 class PromiseAnyFulfilled {
-  constructor(readonly value: unknown) {}
+  constructor(readonly value: Value) {}
 }
 
-const reactionHandler = (value: unknown, method: string): Callable | undefined => {
+const reactionHandler = (value: Value, method: string): Callable | undefined => {
   if (isSupportedCallback(value)) return value
   if (typeofValue(value) === "function") {
     throw typeError(
@@ -279,7 +279,7 @@ const reactionHandler = (value: unknown, method: string): Callable | undefined =
 const reactionExit = <R>(
   ctx: Interpreter<R>,
   source: PromiseObj,
-): Effect.Effect<Exit.Exit<unknown, unknown>, unknown, R> =>
+): Effect.Effect<Exit.Exit<Value, unknown>, unknown, R> =>
   Effect.gen(function* () {
     const exit = yield* ctx.pending.await(source)
     if (!Exit.isSuccess(exit) && Cause.hasInterruptsOnly(exit.cause)) return yield* Effect.failCause(exit.cause)

packages/codemode/src/interpreter/references.ts

@@ -1,47 +1,18 @@
 import { ToolReference } from "../tool-runtime.js"
 import { invalidData } from "./model.js"
-import {
-  Callable,
-  getOwn,
-  isWrapper,
-  ownKeys,
-  Arr,
-  Bytes,
-  DateObj,
-  GeneratorObj,
-  IteratorObj,
-  MapObj,
-  Obj,
-  PromiseObj,
-  RegExpObj,
-  SetObj,
-  URLObj,
-  URLSearchParamsObj,
-  HeadersObj,
-} from "./objects.js"
+import { Callable, getOwn, isRuntimeReference, Obj, Opaque, ownKeys, type Value } from "./objects.js"
 
-/** Values that cannot cross the data boundary. */
-export const isRuntimeReference = (value: unknown): boolean =>
-  value instanceof Callable ||
-  value instanceof GeneratorObj ||
-  value instanceof IteratorObj ||
-  value instanceof ToolReference ||
-  value instanceof PromiseObj ||
-  isWrapper(value)
-
-function* childValues(value: object): Generator {
-  if (!(value instanceof Obj)) return
-  for (const key of ownKeys(value)) yield getOwn(value, key)
-}
+/** Interpreter machinery that is never data, unlike a Date or Map, which cross some boundaries as copies. */
+export const isOpaque = (value: Value): boolean => value instanceof Opaque || value instanceof ToolReference
 
 // Depth-first search over a value tree. `match` stops the walk; `skip` prunes a subtree without matching it.
 const find = (
-  value: unknown,
-  match: (current: unknown) => boolean,
-  skip: (current: unknown) => boolean,
+  value: Value,
+  match: (current: Value) => boolean,
+  skip: (current: Value) => boolean,
   seen: Set<object>,
 ): boolean => {
-  const pending: Array<Iterator<unknown>> = [[value].values()]
+  const pending: Array<Iterator<Value>> = [[value].values()]
   while (pending.length > 0) {
     const next = pending.at(-1)!.next()
     if (next.done) {
@@ -50,25 +21,28 @@ const find = (
     }
     const current = next.value
     if (match(current)) return true
-    if (current === null || typeof current !== "object" || skip(current) || seen.has(current)) continue
+    if (!(current instanceof Obj) || skip(current) || seen.has(current)) continue
     seen.add(current)
-    pending.push(childValues(current))
+    pending.push(
+      ownKeys(current)
+        .map((key) => getOwn(current, key))
+        .values(),
+    )
   }
   return false
 }
 
 const never = () => false
 
-export const containsRuntimeReference = (value: unknown): boolean => find(value, isRuntimeReference, never, new Set())
+export const containsRuntimeReference = (value: Value): boolean => find(value, isRuntimeReference, never, new Set())
 
-// Wrapper values are data here, not opaque interpreter references.
-export const containsOpaqueReference = (value: unknown): boolean =>
-  find(value, (current) => !isWrapper(current) && isRuntimeReference(current), isWrapper, new Set())
+export const containsOpaqueReference = (value: Value): boolean =>
+  find(value, isOpaque, (current) => isRuntimeReference(current) && !isOpaque(current), new Set())
 
 // Reject cycles before mutation so later boundary walks remain safe.
 export const rejectCircularInsertion = (
-  container: object,
-  value: unknown,
+  container: Obj,
+  value: Value,
   label: string,
   seen = new Set<object>(),
 ): void => {
@@ -77,27 +51,14 @@ export const rejectCircularInsertion = (
   }
 }
 
-export const describeValue = (value: unknown): string => {
+export const describeValue = (value: Value): string => {
   if (value === null || value === undefined) return String(value)
-  if (value instanceof Arr) return "an array"
-  if (value instanceof PromiseObj) return "an un-awaited Promise"
+  if (value instanceof Obj) return value.describe
   if (value instanceof ToolReference) return "a tool reference"
-  if (value instanceof DateObj) return "a Date"
-  if (value instanceof RegExpObj) return "a RegExp"
-  if (value instanceof MapObj) return "a Map"
-  if (value instanceof SetObj) return "a Set"
-  if (value instanceof URLObj) return "a URL"
-  if (value instanceof URLSearchParamsObj) return "a URLSearchParams"
-  if (value instanceof HeadersObj) return "a Headers"
-  if (value instanceof Bytes) return "a Uint8Array"
-  if (value instanceof GeneratorObj) return "a generator"
-  if (value instanceof IteratorObj) return "an iterator"
-  if (isRuntimeReference(value)) return "a function"
-  if (typeof value === "object") return "a data object"
   return `a ${typeof value}`
 }
 
-export const typeofValue = (value: unknown): string => {
+export const typeofValue = (value: Value): string => {
   if (value instanceof Callable) return "function"
   if (value instanceof ToolReference) return value.path.length > 0 ? "function" : "object"
   return typeof value

packages/codemode/src/interpreter/scope.ts

@@ -1,4 +1,5 @@
 import { type AstNode, type Binding, referenceError, typeError } from "./model.js"
+import type { Value } from "./objects.js"
 
 export class ScopeStack {
   private readonly scopes: Array<Map<string, Binding>>
@@ -15,7 +16,7 @@ export class ScopeStack {
     scope.set(name, { mutable, value: undefined, initialized: false })
   }
 
-  initialize(name: string, value: unknown, node: AstNode): void {
+  initialize(name: string, value: Value, node: AstNode): void {
     const binding = this.current().get(name)
     if (!binding || binding.initialized !== false) {
       throw typeError(`Identifier '${name}' has not been reserved for initialization.`, node)
@@ -24,7 +25,7 @@ export class ScopeStack {
     binding.initialized = true
   }
 
-  declare(name: string, value: unknown, mutable: boolean, node: AstNode): void {
+  declare(name: string, value: Value, mutable: boolean, node: AstNode): void {
     const scope = this.current()
     if (scope.has(name)) {
       throw typeError(`Identifier '${name}' has already been declared.`, node)
@@ -32,7 +33,7 @@ export class ScopeStack {
     scope.set(name, { mutable, value, initialized: true })
   }
 
-  get(name: string, node: AstNode): unknown {
+  get(name: string, node: AstNode): Value {
     const binding = this.resolve(name)
 
     if (!binding) {
@@ -46,7 +47,7 @@ export class ScopeStack {
     return binding.value
   }
 
-  set(name: string, value: unknown, node: AstNode): unknown {
+  set(name: string, value: Value, node: AstNode): Value {
     const binding = this.resolve(name)
 
     if (!binding) {

packages/codemode/src/stdlib/array.ts

@@ -2,14 +2,24 @@ import { Effect } from "effect"
 import { constructor, type Method, methods, prototypeFrom, receiver } from "../interpreter/native.js"
 import { checkArrayLength, checkStringLength, MAX_ARRAY_LENGTH } from "../interpreter/limits.js"
 import { invalidData, IteratorSymbol, rangeError, typeError } from "../interpreter/model.js"
-import { define, get, hidden, Arr, GeneratorObj, IteratorObj, Obj } from "../interpreter/objects.js"
+import {
+  define,
+  get,
+  hidden,
+  Arr,
+  GeneratorObj,
+  IteratorObj,
+  Obj,
+  coerceToNumber,
+  coerceToString,
+  type Value,
+} from "../interpreter/objects.js"
 import { describeValue, rejectCircularInsertion } from "../interpreter/references.js"
 import { applyCollectionCallback, invoke, preserveConsumerError } from "../interpreter/callback.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
 import { compareText } from "../tool-runtime.js"
-import { coerceToNumber, coerceToString } from "./value.js"
 
-const arrayLikeSource = (source: unknown): { readonly length: number; readonly source: Obj } => {
+const arrayLikeSource = (source: Value): { readonly length: number; readonly source: Obj } => {
   if (source instanceof Obj && typeof get(source, "length") === "number") {
     const length = get(source, "length") as number
     const normalized = Number.isNaN(length) || length <= 0 ? 0 : Math.trunc(length)
@@ -21,7 +31,7 @@ const arrayLikeSource = (source: unknown): { readonly length: number; readonly s
   )
 }
 
-const arrayFrom = <R>(ctx: Interpreter<R>, args: Array<unknown>): Effect.Effect<unknown, unknown, R> => {
+const arrayFrom = <R>(ctx: Interpreter<R>, args: Array<Value>): Effect.Effect<Value, unknown, R> => {
   const source = args[0]
   const proto = ctx.builtins.Array
   const apply =
@@ -33,14 +43,14 @@ const arrayFrom = <R>(ctx: Interpreter<R>, args: Array<unknown>): Effect.Effect<
         throw typeError("Array.from expects a synchronous iterable or array-like value.")
       }
       const arrayLike = arrayLikeSource(source)
-      const values: Array<unknown> = []
+      const values: Array<Value> = []
       for (let index = 0; index < arrayLike.length; index += 1) {
         const item = get(arrayLike.source, index)
         values.push(apply === undefined ? item : yield* apply([item, index]))
       }
       return new Arr(proto, values)
     }
-    const values: Array<unknown> = []
+    const values: Array<Value> = []
     let index = 0
     while (true) {
       const step = yield* cursor.next
@@ -53,21 +63,21 @@ const arrayFrom = <R>(ctx: Interpreter<R>, args: Array<unknown>): Effect.Effect<
 
 export const sortArray = <R>(
   ctx: Interpreter<R>,
-  target: Array<unknown>,
-  comparator: unknown,
+  target: Array<Value>,
+  comparator: Value,
   name: string,
-): Effect.Effect<Array<unknown>, unknown, R> => {
+): Effect.Effect<Array<Value>, unknown, R> => {
   if (comparator === undefined) {
     return Effect.sync(() => [...target].sort((a, b) => compareText(coerceToString(a), coerceToString(b))))
   }
   const apply = applyCollectionCallback(ctx, comparator, name)
-  const mergeSort = (items: Array<unknown>): Effect.Effect<Array<unknown>, unknown, R> => {
+  const mergeSort = (items: Array<Value>): Effect.Effect<Array<Value>, unknown, R> => {
     if (items.length <= 1) return Effect.succeed(items)
     const midpoint = Math.floor(items.length / 2)
     return Effect.gen(function* () {
       const left = yield* mergeSort(items.slice(0, midpoint))
       const right = yield* mergeSort(items.slice(midpoint))
-      const merged: Array<unknown> = []
+      const merged: Array<Value> = []
       let leftIndex = 0
       let rightIndex = 0
       while (leftIndex < left.length && rightIndex < right.length) {
@@ -88,8 +98,8 @@ export const sortArray = <R>(
 export const arrayGlobal = <R>(ctx: Interpreter<R>) => {
   const builtins = ctx.builtins
   const proto = builtins.Array
-  const wrap = (items: Array<unknown>) => new Arr(proto, items)
-  const construct = (args: Array<unknown>, into: Obj): Arr => {
+  const wrap = (items: Array<Value>) => new Arr(proto, items)
+  const construct = (args: Array<Value>, into: Obj): Arr => {
     if (args.length !== 1) return new Arr(into, [...args])
     const first = args[0]
     if (typeof first !== "number") return new Arr(into, [first])
@@ -109,8 +119,8 @@ export const arrayGlobal = <R>(ctx: Interpreter<R>) => {
     ["from", 1, (_, args) => arrayFrom(ctx, args)],
   ])
 
-  const self = (thisValue: unknown, name: string) => receiver(Arr, thisValue, `Array.prototype.${name}`)
-  const optNumber = (name: string, value: unknown, label: string): number | undefined => {
+  const self = (thisValue: Value, name: string) => receiver(Arr, thisValue, `Array.prototype.${name}`)
+  const optNumber = (name: string, value: Value, label: string): number | undefined => {
     if (value === undefined) return undefined
     if (typeof value !== "number") {
       throw typeError(`Array.${name} expects ${label} to be a number.`)
@@ -122,11 +132,11 @@ export const arrayGlobal = <R>(ctx: Interpreter<R>) => {
     name: string,
     length: number,
     body: (
-      target: Array<unknown>,
+      target: Array<Value>,
       receiver: Arr,
-      apply: (args: Array<unknown>) => Effect.Effect<unknown, unknown, R>,
-      args: Array<unknown>,
-    ) => Effect.Effect<unknown, unknown, R>,
+      apply: (args: Array<Value>) => Effect.Effect<Value, unknown, R>,
+      args: Array<Value>,
+    ) => Effect.Effect<Value, unknown, R>,
   ): Method => [
     name,
     length,
@@ -214,7 +224,7 @@ export const arrayGlobal = <R>(ctx: Interpreter<R>) => {
       "flat",
       0,
       (thisValue, args) => {
-        const flatten = (items: Array<unknown>, depth: number): Array<unknown> =>
+        const flatten = (items: Array<Value>, depth: number): Array<Value> =>
           items.flatMap((item) => (item instanceof Arr && depth > 0 ? flatten(item.items, depth - 1) : [item]))
         const flattened = flatten(self(thisValue, "flat").items, optNumber("flat", args[0], "depth") ?? 1)
         checkArrayLength(flattened.length)
@@ -369,7 +379,7 @@ export const arrayGlobal = <R>(ctx: Interpreter<R>) => {
     iterate("map", 1, (target, receiver, apply) =>
       Effect.gen(function* () {
         const length = target.length
-        const values: Array<unknown> = []
+        const values: Array<Value> = []
         values.length = length
         for (let index = 0; index < length; index += 1) {
           if (!(index in target)) continue
@@ -381,7 +391,7 @@ export const arrayGlobal = <R>(ctx: Interpreter<R>) => {
     iterate("flatMap", 1, (target, receiver, apply) =>
       Effect.gen(function* () {
         const length = target.length
-        const values: Array<unknown> = []
+        const values: Array<Value> = []
         for (let index = 0; index < length; index += 1) {
           if (!(index in target)) continue
           const mapped = yield* apply([target[index], index, receiver])
@@ -394,7 +404,7 @@ export const arrayGlobal = <R>(ctx: Interpreter<R>) => {
     iterate("filter", 1, (target, receiver, apply) =>
       Effect.gen(function* () {
         const length = target.length
-        const values: Array<unknown> = []
+        const values: Array<Value> = []
         for (let index = 0; index < length; index += 1) {
           if (!(index in target)) continue
           const item = target[index]

packages/codemode/src/stdlib/bytes.ts

@@ -2,13 +2,24 @@ import { Effect } from "effect"
 import { checkArrayLength, checkStringLength } from "../interpreter/limits.js"
 import { constructor, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js"
 import { IteratorSymbol, rangeError, syntaxError, typeError } from "../interpreter/model.js"
-import { define, defineAccessor, get, hidden, Arr, Bytes, IteratorObj, Obj } from "../interpreter/objects.js"
+import {
+  define,
+  defineAccessor,
+  get,
+  hidden,
+  Arr,
+  Bytes,
+  IteratorObj,
+  Obj,
+  coerceToNumber,
+  coerceToString,
+  type Value,
+} from "../interpreter/objects.js"
 import { describeValue } from "../interpreter/references.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
-import { coerceToNumber, coerceToString } from "./value.js"
 
 /** The bytes a Uint8Array, array, or other iterable of numbers describes; the host array clamps each value. */
-const collectBytes = <R>(ctx: Interpreter<R>, source: unknown, name: string): Effect.Effect<Uint8Array, unknown, R> => {
+const collectBytes = <R>(ctx: Interpreter<R>, source: Value, name: string): Effect.Effect<Uint8Array, unknown, R> => {
   if (source instanceof Bytes) return Effect.succeed(new Uint8Array(source.bytes))
   return Effect.gen(function* () {
     const cursor = yield* ctx.iterate(source)
@@ -27,7 +38,7 @@ const collectBytes = <R>(ctx: Interpreter<R>, source: unknown, name: string): Ef
   })
 }
 
-const constructBytes = <R>(ctx: Interpreter<R>, args: Array<unknown>, proto: Obj) => {
+const constructBytes = <R>(ctx: Interpreter<R>, args: Array<Value>, proto: Obj) => {
   const source = args[0]
   if (source !== null && typeof source === "object") {
     return Effect.map(collectBytes(ctx, source, "new Uint8Array(...)"), (bytes) => new Bytes(proto, bytes))
@@ -48,7 +59,7 @@ export const uint8ArrayGlobal = <R>(ctx: Interpreter<R>) => {
     call: requiresNew("Uint8Array"),
     construct: (args, newTarget) => constructBytes(ctx, args, prototypeFrom(newTarget, proto)),
   })
-  const decode = (name: string, args: Array<unknown>, from: (text: string) => Uint8Array) => {
+  const decode = (name: string, args: Array<Value>, from: (text: string) => Uint8Array) => {
     if (typeof args[0] !== "string") throw typeError(`Uint8Array.${name} expects a string.`)
     try {
       return wrap(from(args[0]))
@@ -63,13 +74,13 @@ export const uint8ArrayGlobal = <R>(ctx: Interpreter<R>) => {
     ["fromHex", 1, (_, args) => decode("fromHex", args, (text) => Uint8Array.fromHex(text))],
   ])
 
-  const self = (thisValue: unknown, name: string) => receiver(Bytes, thisValue, `Uint8Array.prototype.${name}`)
-  const optNumber = (name: string, value: unknown, label: string): number | undefined => {
+  const self = (thisValue: Value, name: string) => receiver(Bytes, thisValue, `Uint8Array.prototype.${name}`)
+  const optNumber = (name: string, value: Value, label: string): number | undefined => {
     if (value === undefined) return undefined
     if (typeof value !== "number") throw typeError(`Uint8Array.${name} expects ${label} to be a number.`)
     return value
   }
-  const wrapAll = (items: Array<unknown>) => new Arr(builtins.Array, items)
+  const wrapAll = (items: Array<Value>) => new Arr(builtins.Array, items)
   defineAccessor(proto, "length", (thisValue) => self(thisValue, "length").bytes.length)
   methods(builtins, proto, [
     ["at", 1, (thisValue, args) => self(thisValue, "at").bytes.at(optNumber("at", args[0], "index") ?? 0)],
@@ -222,8 +233,7 @@ const utf8Labels = new Set(["unicode-1-1-utf-8", "unicode11utf8", "unicode20utf8
 export const textDecoderGlobal = <R>(ctx: Interpreter<R>) => {
   const builtins = ctx.builtins
   const proto = builtins.TextDecoder
-  const self = (thisValue: unknown, name: string) =>
-    receiver(TextDecoderObj, thisValue, `TextDecoder.prototype.${name}`)
+  const self = (thisValue: Value, name: string) => receiver(TextDecoderObj, thisValue, `TextDecoder.prototype.${name}`)
   defineAccessor(proto, "encoding", (thisValue) => self(thisValue, "encoding").decoder.encoding)
   defineAccessor(proto, "fatal", (thisValue) => self(thisValue, "fatal").decoder.fatal)
   defineAccessor(proto, "ignoreBOM", (thisValue) => self(thisValue, "ignoreBOM").decoder.ignoreBOM)

packages/codemode/src/stdlib/collections.ts

@@ -7,15 +7,16 @@ import {
   get,
   getOwn,
   hidden,
-  isWrapper,
   Arr,
+  coerceToString,
   IteratorObj,
   MapObj,
   Obj,
   PromiseObj,
   SetObj,
+  type Value,
 } from "../interpreter/objects.js"
-import { describeValue, isRuntimeReference } from "../interpreter/references.js"
+import { describeValue, isOpaque } from "../interpreter/references.js"
 import {
   applyCollectionCallback,
   isSupportedCallback,
@@ -25,9 +26,9 @@ import {
 } from "../interpreter/callback.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
 
-const coerceGroupByPropertyKey = <R>(ctx: Interpreter<R>, value: unknown): Effect.Effect<string, unknown, R> => {
-  if (value instanceof PromiseObj) return Effect.succeed("[object Promise]")
-  if (!isWrapper(value) && isRuntimeReference(value)) {
+const coerceGroupByPropertyKey = <R>(ctx: Interpreter<R>, value: Value): Effect.Effect<string, unknown, R> => {
+  if (value instanceof PromiseObj) return Effect.succeed(coerceToString(value))
+  if (isOpaque(value)) {
     throw invalidData(`Object.groupBy callback must return a data value, received ${describeValue(value)}.`)
   }
   return toPrimitiveString(ctx, value)
@@ -81,7 +82,7 @@ export const groupBy = <R>(ctx: Interpreter<R>, namespace: "Map" | "Object") =>
     })
   })
 
-const constructMap = <R>(ctx: Interpreter<R>, init: unknown, proto: Obj) => {
+const constructMap = <R>(ctx: Interpreter<R>, init: Value, proto: Obj) => {
   const target = new MapObj(proto)
   if (init === undefined || init === null) return Effect.succeed(target)
   return Effect.gen(function* () {
@@ -105,7 +106,7 @@ const constructMap = <R>(ctx: Interpreter<R>, init: unknown, proto: Obj) => {
   })
 }
 
-const constructSet = <R>(ctx: Interpreter<R>, init: unknown, proto: Obj) => {
+const constructSet = <R>(ctx: Interpreter<R>, init: Value, proto: Obj) => {
   const target = new SetObj(proto)
   if (init === undefined || init === null) return Effect.succeed(target)
   return Effect.gen(function* () {
@@ -130,8 +131,7 @@ export const mapGlobal = <R>(ctx: Interpreter<R>) => {
     construct: (args, newTarget) => constructMap(ctx, args[0], prototypeFrom(newTarget, proto)),
   })
   define(map, "groupBy", groupBy(ctx, "Map"), hidden)
-  const self = (thisValue: unknown, name: string) => receiver(MapObj, thisValue, `Map.prototype.${name}`)
-  const wrap = (items: Array<unknown>) => new Arr(builtins.Array, items)
+  const self = (thisValue: Value, name: string) => receiver(MapObj, thisValue, `Map.prototype.${name}`)
   defineAccessor(proto, "size", (thisValue) => receiver(MapObj, thisValue, "Map.prototype.size").map.size)
   methods(builtins, proto, [
     ["get", 1, (thisValue, args) => self(thisValue, "get").map.get(args[0])],
@@ -179,17 +179,7 @@ export const mapGlobal = <R>(ctx: Interpreter<R>) => {
     ],
     ["keys", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "keys").map.keys())],
     ["values", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "values").map.values())],
-    [
-      "entries",
-      0,
-      (thisValue) =>
-        new IteratorObj(
-          builtins.Iterator,
-          self(thisValue, "entries")
-            .map.entries()
-            .map(([key, item]) => wrap([key, item])),
-        ),
-    ],
+    ["entries", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "entries").iterator(builtins))],
     [
       "forEach",
       1,
@@ -209,26 +199,26 @@ export const mapGlobal = <R>(ctx: Interpreter<R>) => {
 
 type SetRecord<R> = {
   readonly size: number
-  readonly has: (item: unknown) => Effect.Effect<boolean, unknown, R>
-  readonly keys: () => Effect.Effect<Iterable<unknown>, unknown, R>
+  readonly has: (item: Value) => Effect.Effect<boolean, unknown, R>
+  readonly keys: () => Effect.Effect<Iterable<Value>, unknown, R>
 }
 
 const loadSetRecord = <R>(
   ctx: Interpreter<R>,
-  source: unknown,
+  source: Value,
   name: string,
 ): Effect.Effect<SetRecord<R>, unknown, R> => {
   if (source instanceof SetObj) {
     return Effect.succeed({
       size: source.set.size,
-      has: (item: unknown) => Effect.succeed(source.set.has(item)),
+      has: (item: Value) => Effect.succeed(source.set.has(item)),
       keys: () => Effect.succeed(source.set.values()),
     })
   }
   if (source instanceof MapObj) {
     return Effect.succeed({
       size: source.map.size,
-      has: (item: unknown) => Effect.succeed(source.map.has(item)),
+      has: (item: Value) => Effect.succeed(source.map.has(item)),
       keys: () => Effect.succeed(source.map.keys()),
     })
   }
@@ -247,10 +237,10 @@ const loadSetRecord = <R>(
     }
     return {
       size: Math.max(Math.trunc(size), 0),
-      has: (item: unknown) => Effect.map(ctx.call(has, source, [item]), Boolean),
+      has: (item: Value) => Effect.map(ctx.call(has, source, [item]), Boolean),
       keys: () =>
-        Effect.flatMap(ctx.call(keys, source, []), (result): Effect.Effect<Iterable<unknown>> => {
-          if (result instanceof IteratorObj) return Effect.succeed(result.iterator)
+        Effect.flatMap(ctx.call(keys, source, []), (result): Effect.Effect<Iterable<Value>> => {
+          if (result instanceof IteratorObj) return Effect.succeed(result.source)
           if (result instanceof Arr) return Effect.succeed(result.items)
           throw typeError(`Set.${name} expected 'keys' to return an iterator.`)
         }),
@@ -262,8 +252,8 @@ const setOperation = <R>(
   ctx: Interpreter<R>,
   target: SetObj,
   name: string,
-  source: unknown,
-): Effect.Effect<unknown, unknown, R> =>
+  source: Value,
+): Effect.Effect<Value, unknown, R> =>
   Effect.gen(function* () {
     const other = yield* loadSetRecord(ctx, source, name)
     const copy = () => {
@@ -342,8 +332,8 @@ export const setGlobal = <R>(ctx: Interpreter<R>) => {
     call: requiresNew("Set"),
     construct: (args, newTarget) => constructSet(ctx, args[0], prototypeFrom(newTarget, proto)),
   })
-  const self = (thisValue: unknown, name: string) => receiver(SetObj, thisValue, `Set.prototype.${name}`)
-  const wrap = (items: Array<unknown>) => new Arr(builtins.Array, items)
+  const self = (thisValue: Value, name: string) => receiver(SetObj, thisValue, `Set.prototype.${name}`)
+  const wrap = (items: Array<Value>) => new Arr(builtins.Array, items)
   const operation = (name: string): Method => [
     name,
     1,

packages/codemode/src/stdlib/console.ts

@@ -1,22 +1,8 @@
 import { type Method, methods } from "../interpreter/native.js"
-import {
-  entries,
-  get,
-  Arr,
-  Bytes,
-  DateObj,
-  MapObj,
-  Obj,
-  PromiseObj,
-  RegExpObj,
-  SetObj,
-  URLObj,
-  URLSearchParamsObj,
-  HeadersObj,
-} from "../interpreter/objects.js"
-import { containsOpaqueReference, isRuntimeReference } from "../interpreter/references.js"
+import { entries, get, Arr, Obj, type Value } from "../interpreter/objects.js"
+import { ToolReference } from "../tool-runtime.js"
+import { containsOpaqueReference } from "../interpreter/references.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
-import { coerceToString } from "./value.js"
 
 const consoleMethods = ["log", "info", "debug", "warn", "error", "dir", "table"]
 
@@ -43,7 +29,7 @@ export const consoleGlobal = <R>(ctx: Interpreter<R>) => {
 
 const MAX_CONSOLE_DEPTH = 32
 
-const formatConsoleMessage = (name: string, args: Array<unknown>): string => {
+const formatConsoleMessage = (name: string, args: Array<Value>): string => {
   if (name === "dir") return args.length === 0 ? "undefined" : formatValue(args[0])
   if (name === "table") return formatConsoleTable(args[0], args[1])
   const prefix = name === "warn" ? "[warn] " : name === "error" ? "[error] " : name === "debug" ? "[debug] " : ""
@@ -51,60 +37,27 @@ const formatConsoleMessage = (name: string, args: Array<unknown>): string => {
 }
 
 /** One value as `console.log` shows it. */
-export const formatValue = (value: unknown): string => {
+export const formatValue = (value: Value): string => {
   if (value === undefined) return "undefined"
   if (typeof value === "string") return value
   return formatConsoleValue(value, new Set(), 0)
 }
 
-const formatConsoleValue = (value: unknown, seen: Set<object>, depth: number): string => {
+const formatConsoleValue = (value: Value, seen: Set<object>, depth: number): string => {
   if (value === null || value === undefined) return "null"
   if (typeof value === "string") return JSON.stringify(value)
-  if (typeof value === "number" || typeof value === "boolean") return String(value)
-  if (typeof value !== "object") return String(value)
-  if (value instanceof PromiseObj) return "[Promise (await it to get its value)]"
-  if (value instanceof DateObj) return coerceToString(value)
-  if (value instanceof RegExpObj) return coerceToString(value)
-  if (value instanceof URLObj) return coerceToString(value)
-  if (value instanceof URLSearchParamsObj) return coerceToString(value)
-  if (value instanceof HeadersObj) return `Headers ${JSON.stringify(Object.fromEntries(value.headers))}`
-  if (value instanceof Bytes) return `Uint8Array(${value.bytes.length}) [${value.bytes.join(",")}]`
+  if (!(value instanceof Obj)) return value instanceof ToolReference ? "[opaque reference]" : String(value)
   if (depth > MAX_CONSOLE_DEPTH) return "..."
   if (seen.has(value)) return "[Circular]"
-  if (value instanceof MapObj) {
-    seen.add(value)
-    try {
-      const items = Array.from(value.map.entries(), ([key, item]) => `[${formatItems([key, item], seen, depth + 1)}]`)
-      return `Map(${value.map.size}) [${items.join(",")}]`
-    } finally {
-      seen.delete(value)
-    }
-  }
-  if (value instanceof SetObj) {
-    seen.add(value)
-    try {
-      return `Set(${value.set.size}) [${formatItems([...value.set.values()], seen, depth + 1)}]`
-    } finally {
-      seen.delete(value)
-    }
-  }
-  if (isRuntimeReference(value)) return "[opaque reference]"
   seen.add(value)
   try {
-    if (value instanceof Arr) return `[${formatItems(value.items, seen, depth + 1)}]`
-    if (!(value instanceof Obj)) return "[object Object]"
-    return `{${entries(value)
-      .map(([key, item]) => `${JSON.stringify(key)}:${formatConsoleValue(item, seen, depth + 1)}`)
-      .join(",")}}`
+    return value.inspect((item) => formatConsoleValue(item, seen, depth + 1))
   } finally {
     seen.delete(value)
   }
 }
 
-const formatItems = (items: Array<unknown>, seen: Set<object>, depth: number): string =>
-  items.map((item) => formatConsoleValue(item, seen, depth)).join(",")
-
-const formatConsoleTable = (value: unknown, columnsArgument: unknown): string => {
+const formatConsoleTable = (value: Value, columnsArgument: Value): string => {
   if (value === undefined) return "undefined"
   if (containsOpaqueReference(value)) return "[opaque reference]"
   const columns = columnsArgument instanceof Arr ? columnsArgument.items.map(String) : undefined
@@ -118,9 +71,9 @@ const formatConsoleTable = (value: unknown, columnsArgument: unknown): string =>
 }
 
 const consoleTableRows = (
-  data: unknown,
+  data: Value,
   columns: ReadonlyArray<string> | undefined,
-): Array<{ readonly index: string; readonly values: Record<string, unknown> }> => {
+): Array<{ readonly index: string; readonly values: Record<string, Value> }> => {
   if (data instanceof Arr) {
     return data.items.map((item, index) => ({ index: String(index), values: consoleTableValues(item, columns) }))
   }
@@ -130,7 +83,7 @@ const consoleTableRows = (
   return [{ index: "0", values: { Value: data } }]
 }
 
-const consoleTableValues = (value: unknown, columns: ReadonlyArray<string> | undefined): Record<string, unknown> => {
+const consoleTableValues = (value: Value, columns: ReadonlyArray<string> | undefined): Record<string, Value> => {
   if (value instanceof Obj && !(value instanceof Arr)) {
     if (columns !== undefined) return Object.fromEntries(columns.map((column) => [column, get(value, column)]))
     return Object.fromEntries(entries(value))
@@ -138,7 +91,7 @@ const consoleTableValues = (value: unknown, columns: ReadonlyArray<string> | und
   return { Value: value }
 }
 
-const formatConsoleTableCell = (value: unknown): string => {
+const formatConsoleTableCell = (value: Value): string => {
   if (value === undefined) return ""
   if (typeof value === "string") return value
   return formatConsoleValue(value, new Set(), 0)

packages/codemode/src/stdlib/date.ts

@@ -1,12 +1,11 @@
 import { Effect } from "effect"
 import { constructor, type Method, methods, prototypeFrom, receiver } from "../interpreter/native.js"
 import { rangeError } from "../interpreter/model.js"
-import { DateObj, Obj } from "../interpreter/objects.js"
+import { DateObj, Obj, coerceToNumber, coerceToString, type Value } from "../interpreter/objects.js"
 import { toPrimitive, toPrimitiveNumber } from "../interpreter/callback.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
-import { coerceToNumber, coerceToString } from "./value.js"
 
-const constructDate = <R>(ctx: Interpreter<R>, args: Array<unknown>, proto: Obj) => {
+const constructDate = <R>(ctx: Interpreter<R>, args: Array<Value>, proto: Obj) => {
   if (args.length === 0) return Effect.succeed(new DateObj(proto, Date.now()))
   if (args.length === 1) {
     const arg = args[0]
@@ -83,7 +82,7 @@ export const dateGlobal = <R>(ctx: Interpreter<R>) => {
     ["UTC", 7, (_, args) => Date.UTC(...(args.map((arg) => coerceToNumber(arg)) as Parameters<typeof Date.UTC>))],
   ])
 
-  const self = (thisValue: unknown, name: string) => receiver(DateObj, thisValue, `Date.prototype.${name}`)
+  const self = (thisValue: Value, name: string) => receiver(DateObj, thisValue, `Date.prototype.${name}`)
   const iso = (value: DateObj) => {
     if (!Number.isFinite(value.time)) throw rangeError("Invalid time value.")
     return new Date(value.time).toISOString()

packages/codemode/src/stdlib/headers.ts

@@ -1,11 +1,21 @@
 import { Effect } from "effect"
 import { constructor, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js"
 import { IteratorSymbol, typeError } from "../interpreter/model.js"
-import { define, entries, get, hidden, Arr, HeadersObj, IteratorObj, Obj } from "../interpreter/objects.js"
+import {
+  define,
+  entries,
+  get,
+  hidden,
+  Arr,
+  HeadersObj,
+  IteratorObj,
+  Obj,
+  coerceToString,
+  isRuntimeReference,
+  type Value,
+} from "../interpreter/objects.js"
 import { applyCollectionCallback } from "../interpreter/callback.js"
-import { isRuntimeReference } from "../interpreter/references.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
-import { coerceToString } from "./value.js"
 import { readPairs } from "./url.js"
 
 // The host validates header names and values and throws its own TypeError; the program gets one of its own.
@@ -17,7 +27,7 @@ const attempt = <T>(run: () => T): T => {
   }
 }
 
-const constructHeaders = <R>(ctx: Interpreter<R>, init: unknown, proto: Obj): Effect.Effect<HeadersObj, unknown, R> => {
+const constructHeaders = <R>(ctx: Interpreter<R>, init: Value, proto: Obj): Effect.Effect<HeadersObj, unknown, R> => {
   const wrap = (headers: Headers) => new HeadersObj(proto, headers)
   if (init === undefined) return Effect.succeed(wrap(new Headers()))
   return Effect.gen(function* () {
@@ -40,10 +50,10 @@ export const headersGlobal = <R>(ctx: Interpreter<R>) => {
     call: requiresNew("Headers"),
     construct: (args, newTarget) => constructHeaders(ctx, args[0], prototypeFrom(newTarget, proto)),
   })
-  const self = (thisValue: unknown, name: string) => receiver(HeadersObj, thisValue, `Headers.prototype.${name}`)
-  const wrap = (items: Array<unknown>) => new Arr(builtins.Array, items)
-  const arg = (args: Array<unknown>, index: number): string => coerceToString(args[index])
-  const requireArgs = (name: string, args: Array<unknown>, count: number): void => {
+  const self = (thisValue: Value, name: string) => receiver(HeadersObj, thisValue, `Headers.prototype.${name}`)
+  const wrap = (items: Array<Value>) => new Arr(builtins.Array, items)
+  const arg = (args: Array<Value>, index: number): string => coerceToString(args[index])
+  const requireArgs = (name: string, args: Array<Value>, count: number): void => {
     if (args.length < count) throw typeError(`Headers.${name} requires ${count} argument${count === 1 ? "" : "s"}.`)
   }
   methods(builtins, proto, [
@@ -53,7 +63,8 @@ export const headersGlobal = <R>(ctx: Interpreter<R>) => {
       (thisValue, args) => {
         requireArgs("append", args, 2)
         const target = self(thisValue, "append").headers
-        return attempt(() => target.append(arg(args, 0), arg(args, 1)))
+        attempt(() => target.append(arg(args, 0), arg(args, 1)))
+        return undefined
       },
     ],
     [
@@ -62,7 +73,8 @@ export const headersGlobal = <R>(ctx: Interpreter<R>) => {
       (thisValue, args) => {
         requireArgs("delete", args, 1)
         const target = self(thisValue, "delete").headers
-        return attempt(() => target.delete(arg(args, 0)))
+        attempt(() => target.delete(arg(args, 0)))
+        return undefined
       },
     ],
     [
@@ -90,7 +102,8 @@ export const headersGlobal = <R>(ctx: Interpreter<R>) => {
       (thisValue, args) => {
         requireArgs("set", args, 2)
         const target = self(thisValue, "set").headers
-        return attempt(() => target.set(arg(args, 0), arg(args, 1)))
+        attempt(() => target.set(arg(args, 0), arg(args, 1)))
+        return undefined
       },
     ],
     // Iterator.from because Bun's Headers typings predate iterator helpers; the runtime iterators already have them.
@@ -104,15 +117,7 @@ export const headersGlobal = <R>(ctx: Interpreter<R>) => {
       0,
       (thisValue) => new IteratorObj(builtins.Iterator, Iterator.from(self(thisValue, "values").headers.values())),
     ],
-    [
-      "entries",
-      0,
-      (thisValue) =>
-        new IteratorObj(
-          builtins.Iterator,
-          Iterator.from(self(thisValue, "entries").headers.entries()).map(([key, value]) => wrap([key, value])),
-        ),
-    ],
+    ["entries", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "entries").iterator(builtins))],
     [
       "forEach",
       1,

packages/codemode/src/stdlib/iterator.ts

@@ -11,7 +11,7 @@ export const iteratorGlobals = <R>(ctx: Interpreter<R>): void => {
       "next",
       0,
       (thisValue) => {
-        const step = receiver(IteratorObj, thisValue, "Iterator.prototype.next").iterator.next()
+        const step = receiver(IteratorObj, thisValue, "Iterator.prototype.next").source.next()
         return record(builtins.Object, { value: step.value, done: Boolean(step.done) })
       },
     ],

packages/codemode/src/stdlib/json.ts

@@ -6,7 +6,7 @@ import { checkStringLength } from "../interpreter/limits.js"
 import { syntaxError, typeError } from "../interpreter/model.js"
 import { typeofValue } from "../interpreter/references.js"
 import { fromJson, toJson } from "../data.js"
-import { get, keys, Arr, Obj, record, remove, set } from "../interpreter/objects.js"
+import { get, keys, Arr, Obj, record, remove, set, type Value } from "../interpreter/objects.js"
 
 export const jsonGlobal = <R>(ctx: Interpreter<R>) => {
   const json = new Obj(ctx.builtins.Object)
@@ -17,7 +17,7 @@ export const jsonGlobal = <R>(ctx: Interpreter<R>) => {
   return json
 }
 
-const parse = <R>(ctx: Interpreter<R>, args: Array<unknown>): Effect.Effect<unknown, unknown, R> => {
+const parse = <R>(ctx: Interpreter<R>, args: Array<Value>): Effect.Effect<Value, unknown, R> => {
   const text = args[0]
   if (typeof text !== "string") throw typeError("JSON.parse expects a string.")
 
@@ -31,7 +31,7 @@ const parse = <R>(ctx: Interpreter<R>, args: Array<unknown>): Effect.Effect<unkn
   if (typeofValue(args[1]) !== "function") return Effect.succeed(parsed)
 
   const apply = applyCollectionCallback(ctx, args[1], "JSON.parse")
-  const visit = (holder: Obj, key: string): Effect.Effect<unknown, unknown, R> =>
+  const visit = (holder: Obj, key: string): Effect.Effect<Value, unknown, R> =>
     Effect.gen(function* () {
       const value = get(holder, key)
       if (value instanceof Obj) {
@@ -46,7 +46,7 @@ const parse = <R>(ctx: Interpreter<R>, args: Array<unknown>): Effect.Effect<unkn
   return visit(record(ctx.builtins.Object, { "": parsed }), "")
 }
 
-const stringify = <R>(ctx: Interpreter<R>, args: Array<unknown>): Effect.Effect<unknown, unknown, R> => {
+const stringify = <R>(ctx: Interpreter<R>, args: Array<Value>): Effect.Effect<Value, unknown, R> => {
   const space = args[2]
   const indent = typeof space === "number" || typeof space === "string" ? space : undefined
   const replacer = args[1]

packages/codemode/src/stdlib/math.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect"
 import { constants, type Method, methods } from "../interpreter/native.js"
 import { typeError } from "../interpreter/model.js"
-import { Obj } from "../interpreter/objects.js"
+import { Obj, type Value } from "../interpreter/objects.js"
 import { preserveConsumerError } from "../interpreter/callback.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
 
@@ -14,7 +14,7 @@ declare global {
 
 // Validate only the arguments a method consumes; like JS, extras are ignored
 // (so built-ins work as callbacks receiving (element, index, array)).
-const number = (name: string, args: Array<unknown>, index: number): number => {
+const number = (name: string, args: Array<Value>, index: number): number => {
   if (index >= args.length) return Number.NaN
   const arg = args[index]
   if (typeof arg !== "number") throw typeError(`Math.${name} expects number arguments.`)

packages/codemode/src/stdlib/number.ts

@@ -1,7 +1,8 @@
 import { constructor, constants, methods } from "../interpreter/native.js"
+import { coerceToString, type Value } from "../interpreter/objects.js"
 import { rangeError, typeError } from "../interpreter/model.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
-import { coercion, coerceToString } from "./value.js"
+import { coercion } from "./value.js"
 
 export const numberGlobal = <R>(ctx: Interpreter<R>) => {
   const builtins = ctx.builtins
@@ -39,11 +40,11 @@ export const numberGlobal = <R>(ctx: Interpreter<R>) => {
     ["parseFloat", 1, (_, args) => parseFloat(coerceToString(args[0]))],
   ])
 
-  const self = (thisValue: unknown, name: string): number => {
+  const self = (thisValue: Value, name: string): number => {
     if (typeof thisValue === "number") return thisValue
     throw typeError(`Number.prototype.${name} requires that 'this' be a Number.`)
   }
-  const optNum = (name: string, arg: unknown): number | undefined => {
+  const optNum = (name: string, arg: Value): number | undefined => {
     if (arg === undefined) return undefined
     if (typeof arg !== "number") throw typeError(`Number.${name} expects a number argument.`)
     return arg
@@ -89,7 +90,7 @@ export const booleanGlobal = <R>(ctx: Interpreter<R>) => {
     length: 1,
     call: coercion(ctx, "Boolean").call,
   })
-  const self = (thisValue: unknown, name: string): boolean => {
+  const self = (thisValue: Value, name: string): boolean => {
     if (typeof thisValue === "boolean") return thisValue
     throw typeError(`Boolean.prototype.${name} requires that 'this' be a Boolean.`)
   }

packages/codemode/src/stdlib/object.ts

@@ -9,7 +9,6 @@ import {
   typeError,
 } from "../interpreter/model.js"
 import {
-  Callable,
   define,
   entries,
   enumerableKeys,
@@ -20,23 +19,20 @@ import {
   keys,
   own,
   Arr,
-  Bytes,
-  DateObj,
-  ErrorObj,
   Obj,
   PromiseObj,
-  RegExpObj,
   set,
+  coerceToString,
+  type Value,
 } from "../interpreter/objects.js"
 import { containsOpaqueReference, describeValue, rejectCircularInsertion } from "../interpreter/references.js"
 import { invoke, preserveConsumerError } from "../interpreter/callback.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
 import { ToolReference } from "../tool-runtime.js"
 import { groupBy } from "./collections.js"
-import { coerceToString } from "./value.js"
 
 // ToObject for enumeration.
-export const enumerableSource = <R>(ctx: Interpreter<R>, label: string, value: unknown, node?: AstNode): Obj => {
+export const enumerableSource = <R>(ctx: Interpreter<R>, label: string, value: Value, node?: AstNode): Obj => {
   if (value === null || value === undefined) {
     throw typeError(`${label} cannot convert ${describeValue(value)} to an object.`, node)
   }
@@ -54,7 +50,7 @@ export const enumerableSource = <R>(ctx: Interpreter<R>, label: string, value: u
   return new Obj(ctx.builtins.Object)
 }
 
-export const objectAssign = <R>(ctx: Interpreter<R>, args: Array<unknown>): unknown => {
+export const objectAssign = <R>(ctx: Interpreter<R>, args: Array<Value>): Value => {
   const target = args[0]
   // JS would box a primitive target; wrappers and primitives cannot hold fields here.
   if (!(target instanceof Obj)) {
@@ -75,7 +71,7 @@ export const objectAssign = <R>(ctx: Interpreter<R>, args: Array<unknown>): unkn
   return target
 }
 
-const objectFromEntries = <R>(ctx: Interpreter<R>, source: unknown): Effect.Effect<Obj, unknown, R> => {
+const objectFromEntries = <R>(ctx: Interpreter<R>, source: Value): Effect.Effect<Obj, unknown, R> => {
   const out = new Obj(ctx.builtins.Object)
   return Effect.gen(function* () {
     const cursor = yield* ctx.iterate(source)
@@ -98,29 +94,24 @@ const objectFromEntries = <R>(ctx: Interpreter<R>, source: unknown): Effect.Effe
   })
 }
 
-export const classTag = (value: unknown): string => {
+const classTag = (value: Value): string => {
   if (value === null) return "Null"
   if (value === undefined) return "Undefined"
-  if (value instanceof Arr) return "Array"
-  if (value instanceof Callable) return "Function"
-  if (value instanceof ErrorObj) return "Error"
-  if (value instanceof DateObj) return "Date"
-  if (value instanceof RegExpObj) return "RegExp"
-  if (value instanceof Bytes) return "Uint8Array"
+  if (value instanceof Obj) return value.tag
   if (typeof value === "string") return "String"
   if (typeof value === "number") return "Number"
   if (typeof value === "boolean") return "Boolean"
   return "Object"
 }
 
-const propertyKey = (value: unknown): PropertyKey =>
+const propertyKey = (value: Value): PropertyKey =>
   value === AsyncIteratorSymbol || value === IteratorSymbol ? value : coerceToString(value)
 
 // Object constructs identically with or without new, like JS. Only `keys` copies its result into the
 // program; `values`, `entries`, `assign`, and `fromEntries` hand back the program's own values.
 export const objectGlobal = <R>(ctx: Interpreter<R>) => {
   const builtins = ctx.builtins
-  const construct = (args: Array<unknown>): unknown => {
+  const construct = (args: Array<Value>): Value => {
     const first = args[0]
     if (first === null || first === undefined) return new Obj(builtins.Object)
     if (first instanceof Obj) return first

packages/codemode/src/stdlib/regexp.ts

@@ -2,9 +2,18 @@ import { Effect } from "effect"
 import type { Builtins } from "../interpreter/intrinsics.js"
 import { constructor, type Method, methods, prototypeFrom, receiver } from "../interpreter/native.js"
 import { syntaxError, typeError } from "../interpreter/model.js"
-import { define, defineAccessor, Arr, Obj, RegExpObj, record } from "../interpreter/objects.js"
+import {
+  define,
+  defineAccessor,
+  Arr,
+  Obj,
+  RegExpObj,
+  record,
+  coerceToNumber,
+  coerceToString,
+  type Value,
+} from "../interpreter/objects.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
-import { coerceToNumber, coerceToString } from "./value.js"
 
 const flagProperties = [
   "hasIndices",
@@ -23,7 +32,7 @@ const regexFailureReason = (error: unknown): string =>
 const escapeRegexHint =
   'To match special characters like ( ) [ ] { } + * ? . literally, escape them with a backslash (e.g. "\\\\(") or test for them with String.includes instead.'
 
-export const toHostRegex = (arg: unknown, method: string, extraFlags = ""): RegExp => {
+export const toHostRegex = (arg: Value, method: string, extraFlags = ""): RegExp => {
   // Native parity: an undefined pattern behaves as an empty pattern.
   if (arg === undefined) return new RegExp("", extraFlags)
   if (arg instanceof RegExpObj) return arg.regex
@@ -53,7 +62,7 @@ export const matchToValue = (builtins: Builtins, match: RegExpMatchArray): Arr =
   return result
 }
 
-export const constructRegExp = (builtins: Builtins, args: Array<unknown>, proto: Obj = builtins.RegExp): RegExpObj => {
+export const constructRegExp = (builtins: Builtins, args: Array<Value>, proto: Obj = builtins.RegExp): RegExpObj => {
   const first = args[0]
   const pattern = first instanceof RegExpObj ? first.regex.source : first === undefined ? "" : coerceToString(first)
   const flagsArg = args[1]
@@ -96,7 +105,7 @@ export const regexpGlobal = <R>(ctx: Interpreter<R>) => {
     ],
   ])
 
-  const self = (thisValue: unknown, name: string) => receiver(RegExpObj, thisValue, `RegExp.prototype.${name}`)
+  const self = (thisValue: Value, name: string) => receiver(RegExpObj, thisValue, `RegExp.prototype.${name}`)
   defineAccessor(proto, "source", (thisValue) => self(thisValue, "source").regex.source)
   defineAccessor(proto, "flags", (thisValue) => self(thisValue, "flags").regex.flags)
   // The host regex holds the only lastIndex, so exec/test and the String methods share one counter.

packages/codemode/src/stdlib/string.ts

@@ -1,16 +1,26 @@
 import { Effect } from "effect"
-import { constructor, fn, type Method, methods } from "../interpreter/native.js"
+import { constructor, fn, type Impl, type Method, methods } from "../interpreter/native.js"
 import { checkArrayLength, checkStringLength } from "../interpreter/limits.js"
 import { invalidData, IteratorSymbol, rangeError, typeError } from "../interpreter/model.js"
-import { define, hidden, Arr, IteratorObj, PromiseObj, RegExpObj, record } from "../interpreter/objects.js"
+import {
+  define,
+  hidden,
+  Arr,
+  IteratorObj,
+  RegExpObj,
+  record,
+  coerceToNumber,
+  coerceToString,
+  type Value,
+} from "../interpreter/objects.js"
 import { containsOpaqueReference, typeofValue } from "../interpreter/references.js"
 import { applyCollectionCallback, isSupportedCallback } from "../interpreter/callback.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
 import { matchToValue, toHostRegex } from "./regexp.js"
-import { coerceToNumber, coerceToString, coercion } from "./value.js"
+import { coercion } from "./value.js"
 
 // console is intercepted by the interpreter before reaching here.
-const requireDataArgument = (name: string, index: number, arg: unknown): unknown => {
+const requireDataArgument = (name: string, index: number, arg: Value): Value => {
   if (containsOpaqueReference(arg)) {
     throw invalidData(`String.${name} expects argument ${index + 1} to be a data value.`)
   }
@@ -29,21 +39,23 @@ const replaceWithCallback = <R>(
   ctx: Interpreter<R>,
   value: string,
   name: "replace" | "replaceAll",
-  args: Array<unknown>,
-): Effect.Effect<unknown, unknown, R> => {
+  args: Array<Value>,
+): Effect.Effect<Value, unknown, R> => {
   const builtins = ctx.builtins
   const apply = applyCollectionCallback(ctx, args[1], `String.${name}`)
-  const matches: Array<{ readonly match: string; readonly offset: number; readonly args: Array<unknown> }> = []
-  const collect = (...callbackArgs: Array<unknown>): string => {
+  const matches: Array<{ readonly match: string; readonly offset: number; readonly args: Array<Value> }> = []
+  // The host calls back with (match, ...captures, offset, string, groups?); only groups is not already a Value.
+  const collect = (
+    ...callbackArgs: Array<string | number | undefined | Record<string, string | undefined>>
+  ): string => {
     const match = callbackArgs[0]
-    const groups = callbackArgs[callbackArgs.length - 1]
-    const hasGroups = groups !== null && typeof groups === "object"
+    const hasGroups = typeof callbackArgs.at(-1) === "object"
     const offset = callbackArgs[callbackArgs.length - (hasGroups ? 3 : 2)]
     if (typeof match !== "string" || typeof offset !== "number") {
       throw typeError(`String.${name} produced an invalid replacement match.`)
     }
-    if (hasGroups) callbackArgs[callbackArgs.length - 1] = record(builtins.Object, groups as Record<string, unknown>)
-    matches.push({ match, offset, args: callbackArgs })
+    const args = callbackArgs.map((arg) => (typeof arg === "object" ? record(builtins.Object, arg) : arg))
+    matches.push({ match, offset, args })
     return match
   }
 
@@ -63,10 +75,7 @@ const replaceWithCallback = <R>(
     let end = 0
     for (const match of matches) {
       const replacement = yield* apply(match.args)
-      output.push(
-        value.slice(end, match.offset),
-        replacement instanceof PromiseObj ? "[object Promise]" : coerceToString(replacement),
-      )
+      output.push(value.slice(end, match.offset), coerceToString(replacement))
       end = match.offset + match.match.length
     }
     output.push(value.slice(end))
@@ -99,7 +108,7 @@ export const stringGlobal = <R>(ctx: Interpreter<R>) => {
     codeUnits("fromCodePoint", String.fromCodePoint),
   ])
 
-  const self = (thisValue: unknown, name: string): string => {
+  const self = (thisValue: Value, name: string): string => {
     if (typeof thisValue === "string") return thisValue
     if (thisValue === null || thisValue === undefined) {
       throw typeError(`String.prototype.${name} called on null or undefined.`)
@@ -107,26 +116,26 @@ export const stringGlobal = <R>(ctx: Interpreter<R>) => {
     return coerceToString(thisValue)
   }
   // Coerce arguments like native JS; opaque runtime references still reject.
-  const str = (name: string, args: Array<unknown>, index: number): string =>
+  const str = (name: string, args: Array<Value>, index: number): string =>
     coerceToString(requireDataArgument(name, index, args[index]))
-  const num = (name: string, args: Array<unknown>, index: number): number =>
+  const num = (name: string, args: Array<Value>, index: number): number =>
     coerceToNumber(requireDataArgument(name, index, args[index]))
-  const optNum = (name: string, args: Array<unknown>, index: number): number | undefined =>
+  const optNum = (name: string, args: Array<Value>, index: number): number | undefined =>
     args[index] === undefined ? undefined : num(name, args, index)
-  const optStr = (name: string, args: Array<unknown>, index: number): string | undefined =>
+  const optStr = (name: string, args: Array<Value>, index: number): string | undefined =>
     args[index] === undefined ? undefined : str(name, args, index)
-  const rejectRegex = (name: string, args: Array<unknown>): void => {
+  const rejectRegex = (name: string, args: Array<Value>): void => {
     if (args[0] instanceof RegExpObj) {
       throw typeError(
         `String.${name} cannot take a regular expression; use regex.test(string) or String.search instead.`,
       )
     }
   }
-  const simple = (name: string, length: number, op: (value: string, args: Array<unknown>) => unknown): Method => [
-    name,
-    length,
-    (thisValue, args) => op(self(thisValue, name), args),
-  ]
+  const simple = (
+    name: string,
+    length: number,
+    op: (value: string, args: Array<Value>) => ReturnType<Impl>,
+  ): Method => [name, length, (thisValue, args) => op(self(thisValue, name), args)]
   const replace = (name: "replace" | "replaceAll") =>
     simple(name, 2, (value, args) => {
       if (isSupportedCallback(args[1])) return replaceWithCallback(ctx, value, name, args)
@@ -218,7 +227,7 @@ export const stringGlobal = <R>(ctx: Interpreter<R>) => {
           `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.`,
         )
       }
-      const matches: Array<unknown> = []
+      const matches: Array<Value> = []
       for (const match of value.matchAll(pattern)) {
         checkArrayLength(matches.length + 1)
         matches.push(matchToValue(builtins, match))

packages/codemode/src/stdlib/url.ts

@@ -7,17 +7,17 @@ import {
   entries,
   get,
   hidden,
-  isWrapper,
   Arr,
   IteratorObj,
   Obj,
   URLObj,
   URLSearchParamsObj,
+  coerceToString,
+  isRuntimeReference,
+  type Value,
 } from "../interpreter/objects.js"
-import { isRuntimeReference } from "../interpreter/references.js"
 import { applyCollectionCallback, preserveConsumerError } from "../interpreter/callback.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
-import { coerceToString } from "./value.js"
 
 const urlProperties = [
   "href",
@@ -52,12 +52,12 @@ export const uriGlobal = <R>(ctx: Interpreter<R>, name: UriFunction) =>
     }
   })
 
-const urlArgument = (value: unknown): string => (value instanceof URLObj ? value.url.href : coerceToString(value))
+const urlArgument = (value: Value): string => (value instanceof URLObj ? value.url.href : coerceToString(value))
 
 export const urlGlobal = <R>(ctx: Interpreter<R>) => {
   const builtins = ctx.builtins
   const proto = builtins.URL
-  const construct = (args: Array<unknown>, into: Obj): URLObj => {
+  const construct = (args: Array<Value>, into: Obj): URLObj => {
     if (args.length === 0) {
       throw typeError("new URL(...) requires a URL string and an optional base URL.")
     }
@@ -92,7 +92,7 @@ export const urlGlobal = <R>(ctx: Interpreter<R>) => {
   ]
   methods(builtins, url, [parse("canParse"), parse("parse")])
 
-  const self = (thisValue: unknown, name: string) => receiver(URLObj, thisValue, `URL.prototype.${name}`)
+  const self = (thisValue: Value, name: string) => receiver(URLObj, thisValue, `URL.prototype.${name}`)
   for (const name of urlProperties) {
     defineAccessor(
       proto,
@@ -119,7 +119,7 @@ export const urlGlobal = <R>(ctx: Interpreter<R>) => {
   return url
 }
 
-const readPair = <R>(ctx: Interpreter<R>, value: unknown, label: string): Effect.Effect<Array<string>, unknown, R> =>
+const readPair = <R>(ctx: Interpreter<R>, value: Value, label: string): Effect.Effect<Array<string>, unknown, R> =>
   Effect.gen(function* () {
     const cursor = yield* ctx.iterate(value)
     if (cursor === undefined) throw typeError(`${label} expects iterable [name, value] pairs.`)
@@ -142,7 +142,7 @@ const readPair = <R>(ctx: Interpreter<R>, value: unknown, label: string): Effect
  */
 export const readPairs = <R>(
   ctx: Interpreter<R>,
-  init: unknown,
+  init: Value,
   label: string,
 ): Effect.Effect<Array<[string, string]> | undefined, unknown, R> =>
   Effect.gen(function* () {
@@ -161,7 +161,7 @@ export const readPairs = <R>(
 
 const constructURLSearchParams = <R>(
   ctx: Interpreter<R>,
-  init: unknown,
+  init: Value,
   proto: Obj,
 ): Effect.Effect<URLSearchParamsObj, unknown, R> => {
   const wrap = (params: URLSearchParams) => new URLSearchParamsObj(proto, params)
@@ -177,7 +177,6 @@ const constructURLSearchParams = <R>(
     if (isRuntimeReference(init)) {
       throw typeError("new URLSearchParams(...) expects a query string, data object, or synchronous iterable pairs.")
     }
-    if (isWrapper(init)) return wrap(new URLSearchParams())
     if (!(init instanceof Obj)) {
       throw typeError(
         "new URLSearchParams(...) expects a query string, data object, iterable pairs, or URLSearchParams.",
@@ -197,11 +196,11 @@ export const urlSearchParamsGlobal = <R>(ctx: Interpreter<R>) => {
     call: requiresNew("URLSearchParams"),
     construct: (args, newTarget) => constructURLSearchParams(ctx, args[0], prototypeFrom(newTarget, proto)),
   })
-  const self = (thisValue: unknown, name: string) =>
+  const self = (thisValue: Value, name: string) =>
     receiver(URLSearchParamsObj, thisValue, `URLSearchParams.prototype.${name}`)
-  const wrap = (items: Array<unknown>) => new Arr(builtins.Array, items)
-  const arg = (args: Array<unknown>, index: number): string => coerceToString(args[index])
-  const requireArgs = (name: string, args: Array<unknown>, count: number): void => {
+  const wrap = (items: Array<Value>) => new Arr(builtins.Array, items)
+  const arg = (args: Array<Value>, index: number): string => coerceToString(args[index])
+  const requireArgs = (name: string, args: Array<Value>, count: number): void => {
     if (args.length < count) {
       throw typeError(`URLSearchParams.${name} requires ${count} argument${count === 1 ? "" : "s"}.`)
     }
@@ -272,17 +271,7 @@ export const urlSearchParamsGlobal = <R>(ctx: Interpreter<R>) => {
     ],
     ["keys", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "keys").params.keys())],
     ["values", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "values").params.values())],
-    [
-      "entries",
-      0,
-      (thisValue) =>
-        new IteratorObj(
-          builtins.Iterator,
-          self(thisValue, "entries")
-            .params.entries()
-            .map(([key, value]) => wrap([key, value])),
-        ),
-    ],
+    ["entries", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "entries").iterator(builtins))],
     ["toString", 0, (thisValue) => self(thisValue, "toString").params.toString()],
     [
       "forEach",

packages/codemode/src/stdlib/value.ts

@@ -1,64 +1,13 @@
 import { fn } from "../interpreter/native.js"
 import { typeError } from "../interpreter/model.js"
-import {
-  get,
-  isWrapper,
-  type Native,
-  Arr,
-  Bytes,
-  DateObj,
-  ErrorObj,
-  MapObj,
-  RegExpObj,
-  SetObj,
-  URLObj,
-  URLSearchParamsObj,
-  HeadersObj,
-} from "../interpreter/objects.js"
+import { coerceToNumber, coerceToString, type Native, type Value } from "../interpreter/objects.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
 
 export const compoundOperators = new Set(["+=", "-=", "*=", "/=", "%=", "**=", "&=", "|=", "^=", "<<=", ">>=", ">>>="])
 
-/** The built-in string form of a value, without consulting program-defined `toString` methods. */
-export const coerceToString = (value: unknown): string => {
-  if (value === null) return "null"
-  if (value === undefined) return "undefined"
-  if (value instanceof DateObj) return Number.isFinite(value.time) ? new Date(value.time).toISOString() : "Invalid Date"
-  if (value instanceof RegExpObj) return `/${value.regex.source}/${value.regex.flags}`
-  if (value instanceof MapObj) return "[object Map]"
-  if (value instanceof SetObj) return "[object Set]"
-  if (value instanceof URLObj) return value.url.href
-  if (value instanceof URLSearchParamsObj) return value.params.toString()
-  if (value instanceof HeadersObj) return "[object Headers]"
-  if (value instanceof Bytes) return value.bytes.join(",")
-  if (value instanceof ErrorObj) {
-    // Match Error.prototype.toString: "name: message", or just one when the other is empty.
-    const name = get(value, "name")
-    const message = get(value, "message")
-    const shownName = typeof name === "string" ? name : "Error"
-    const shownMessage = typeof message === "string" ? message : ""
-    if (shownMessage === "") return shownName
-    if (shownName === "") return shownMessage
-    return `${shownName}: ${shownMessage}`
-  }
-  if (value instanceof Arr) {
-    return value.items.map((item) => (item === null || item === undefined ? "" : coerceToString(item))).join(",")
-  }
-  if (typeof value === "object") return "[object Object]"
-  return String(value)
-}
-
-export const coerceToNumber = (value: unknown): number => {
-  if (value instanceof DateObj) return value.time
-  if (value instanceof Bytes) return Number(coerceToString(value))
-  if (isWrapper(value)) return Number.NaN
-  if (value instanceof Arr) return Number(coerceToString(value))
-  return value !== null && typeof value === "object" ? Number.NaN : Number(value)
-}
-
 export type Coercion = "Number" | "String" | "Boolean" | "parseInt" | "parseFloat" | "isFinite" | "isNaN"
 
-const coerce = <R>(ctx: Interpreter<R>, name: Coercion, args: Array<unknown>): unknown => {
+const coerce = <R>(ctx: Interpreter<R>, name: Coercion, args: Array<Value>): Value => {
   // Native: Number() is 0 and String() is "", unlike their undefined-argument forms; the
   // other coercers match native through the undefined-argument path below.
   if (args.length === 0) {
@@ -66,15 +15,6 @@ const coerce = <R>(ctx: Interpreter<R>, name: Coercion, args: Array<unknown>): u
     if (name === "String") return ""
   }
   const raw = args[0]
-  if (isWrapper(raw)) {
-    if (name === "Boolean") return true
-    if (name === "Number") return coerceToNumber(raw)
-    if (name === "String") return coerceToString(raw)
-    if (name === "isFinite") return Number.isFinite(coerceToNumber(raw))
-    if (name === "isNaN") return Number.isNaN(coerceToNumber(raw))
-    if (name === "parseInt") return parseInt(coerceToString(raw))
-    return parseFloat(coerceToString(raw))
-  }
   if (name === "Number") return coerceToNumber(raw)
   if (name === "Boolean") return Boolean(raw)
   if (name === "isFinite") return Number.isFinite(coerceToNumber(raw))

packages/codemode/src/stdlib/web.ts

@@ -1,9 +1,8 @@
 import { fn, methods } from "../interpreter/native.js"
 import { typeError } from "../interpreter/model.js"
-import { Bytes, Obj } from "../interpreter/objects.js"
+import { Bytes, Obj, coerceToString } from "../interpreter/objects.js"
 import { describeValue } from "../interpreter/references.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
-import { coerceToString } from "./value.js"
 
 // WebIDL DOMString conversion: a missing argument is a TypeError, anything else stringifies. Invalid input is a
 // TypeError as well; browsers throw a DOMException named InvalidCharacterError, which CodeMode does not have.

packages/codemode/test/for-await-test262.test.ts

@@ -529,6 +529,6 @@ describe("Test262 for-await-of adaptations", () => {
     const result = await execute(`for await (const item of { values: [1, 2] }) {}`)
     expect(result.ok).toBe(false)
     if (result.ok) return
-    expect(result.error.message).toContain("or custom iterator value")
+    expect(result.error.message).toContain("requires an iterable value, received a data object")
   })
 })

packages/codemode/test/generator-test262.test.ts

@@ -1030,7 +1030,7 @@ describe("confined generators", () => {
         const params = new URLSearchParams(entries())
         return [events, params.toString()]
       `),
-    ).toEqual([["first", "second", "pair close", "outer close"], "%5Bobject+Object%5D=2"])
+    ).toEqual([["first", "second", "pair close", "outer close"], "%5Bobject+Promise%5D=2"])
   })
 
   test("validates URLSearchParams pair lengths after converting the outer sequence", async () => {

packages/codemode/test/stdlib.test.ts

@@ -1267,6 +1267,32 @@ describe("built-in iterators", () => {
   })
 })
 
+describe("Object.prototype.toString", () => {
+  test("reports the built-in kind it is inherited by, as JS does through Symbol.toStringTag", async () => {
+    expect(
+      await value(`
+      return [
+        new Map().toString(), new Set().toString(), new Headers().toString(), Promise.resolve(1).toString(),
+        [1].values().toString(), ({}).toString(), String(new Map()), String(Promise.resolve(1)),
+        \`\${new Set([1])}\`, [new Map()] + "", new Map() == "[object Map]",
+      ]
+    `),
+    ).toEqual([
+      "[object Map]",
+      "[object Set]",
+      "[object Headers]",
+      "[object Promise]",
+      "[object Iterator]",
+      "[object Object]",
+      "[object Map]",
+      "[object Promise]",
+      "[object Set]",
+      "[object Map]",
+      true,
+    ])
+  })
+})
+
 describe("toLocaleString", () => {
   test("numbers and dates format as en-US in UTC; everything else falls back to toString", async () => {
     expect(

packages/codemode/test/test262/run.ts

@@ -9,7 +9,7 @@ import type { Interpreter } from "../../src/interpreter/interpreter.js"
 import { Throw } from "../../src/interpreter/model.js"
 import { createErrorValue } from "../../src/interpreter/intrinsics.js"
 import { constructor, fn, methods } from "../../src/interpreter/native.js"
-import { Callable, define, get, hidden, Arr, Fn, Obj } from "../../src/interpreter/objects.js"
+import { Callable, define, get, hidden, Arr, Fn, Obj, type Value } from "../../src/interpreter/objects.js"
 import { ToolRuntime } from "../../src/tool-runtime.js"
 
 export const root = import.meta.dir
@@ -64,10 +64,7 @@ export const run = async (file: string): Promise<Outcome> => {
   return { status: "pass" }
 }
 
-const harness = <R>(
-  ctx: Interpreter<R>,
-  onDone: (error: unknown) => void,
-): ReadonlyArray<readonly [string, unknown]> => {
+const harness = <R>(ctx: Interpreter<R>, onDone: (error: Value) => void): ReadonlyArray<readonly [string, Value]> => {
   const builtins = ctx.builtins
   const test262Prototype = new Obj(builtins.Object)
   define(test262Prototype, "name", "Test262Error", hidden)
@@ -90,7 +87,7 @@ const harness = <R>(
   methods(builtins, compareArray, [["format", 1, (_, args) => show(args[0])]])
   const assert = fn<R>(builtins, "assert", 2, (_, args) =>
     args[0] === true
-      ? Effect.void
+      ? Effect.undefined
       : fail(args[1] === undefined ? `Expected true but got ${show(args[0])}` : String(args[1])),
   )
   methods(builtins, assert, [
@@ -99,7 +96,7 @@ const harness = <R>(
       3,
       (_, args) =>
         Object.is(args[0], args[1])
-          ? Effect.void
+          ? Effect.undefined
           : fail(`${prefix(args[2])}Expected SameValue(«${show(args[0])}», «${show(args[1])}») to be true`),
     ],
     [
@@ -108,14 +105,14 @@ const harness = <R>(
       (_, args) =>
         Object.is(args[0], args[1])
           ? fail(`${prefix(args[2])}Expected SameValue(«${show(args[0])}», «${show(args[1])}») to be false`)
-          : Effect.void,
+          : Effect.undefined,
     ],
     [
       "compareArray",
       3,
       (_, args) =>
         compare(args[0], args[1])
-          ? Effect.void
+          ? Effect.undefined
           : fail(
               `Actual ${show(args[0])} and expected ${show(args[1])} should have the same contents. ${prefix(args[2])}`,
             ),
@@ -132,7 +129,7 @@ const harness = <R>(
               const thrown = materialize(ctx, Cause.squash(cause))
               if (!(thrown instanceof Obj)) return fail(`${prefix(args[2])}Thrown value was not an object!`)
               const actual = get(thrown, "constructor")
-              if (actual === args[0]) return Effect.void
+              if (actual === args[0]) return Effect.undefined
               return fail(`${prefix(args[2])}Expected a ${expected} but got a ${show(actual)}`)
             },
             onSuccess: () =>
@@ -146,7 +143,13 @@ const harness = <R>(
     ["assert", assert],
     ["compareArray", compareArray],
     ["Test262Error", test262Error],
-    ["$DONE", fn<R>(builtins, "$DONE", 1, (_, args) => onDone(args[0]))],
+    [
+      "$DONE",
+      fn<R>(builtins, "$DONE", 1, (_, args) => {
+        onDone(args[0])
+        return undefined
+      }),
+    ],
     [
       "$DONOTEVALUATE",
       fn<R>(builtins, "$DONOTEVALUATE", 0, () =>

packages/core/src/codemode/instructions.ts

@@ -6,15 +6,13 @@ import { Instructions } from "../instructions/index.js"
 import { CodeModeCatalog } from "./catalog.js"
 
 // prettier-ignore
-const prompt = (hasMoreTools: boolean) => `The Code Mode tool catalog below is ${hasMoreTools ? "partial" : "complete"}.
+const prompt = (hasMoreTools: boolean) => `# Code Mode
 
-${hasMoreTools ? "The Code Mode catalog and `search` results are" : "This catalog is"} the complete set of tools callable inside \`execute\`. It does not affect tools exposed directly outside Code Mode.${hasMoreTools ? `
+Use the \`execute\` tool to call the tools listed below. They cannot be called directly${hasMoreTools ? ", and neither can \`search\`. Both" : ". They"} only work inside code you pass to \`execute\`.
 
-## Search
+${hasMoreTools ? `The catalog is partial. Inside \`execute\`, use \`search(...)\` to find a tool, then call it by the \`path\` in the result. Do not guess tool names.
 
-Call \`search(...)\` to discover exact paths and signatures for additional tools:
-
-- ${searchSignature}` : ""}
+- ${searchSignature}` : "The catalog is complete. Do not guess tool names."}
 
 ## Available tools`
 

packages/core/src/config/plugin/policy.ts

@@ -4,6 +4,7 @@ import { define } from "@opencode/plugin/effect/plugin"
 import { Document } from "@opencode/schema/config"
 import { Effect } from "effect"
 import { Config } from "../../config.js"
+import { ManagedPolicy } from "../../managed-policy.js"
 import { Wildcard } from "../../util/wildcard.js"
 import { ConfigEntryObserver } from "./entry-observer.js"
 
@@ -11,16 +12,30 @@ export const Plugin = define({
   id: "opencode.config.policy",
   effect: Effect.fn(function* (ctx) {
     const config = yield* Config.Service
+    const managed = yield* ManagedPolicy.Service
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, ctx.provider.reload())
-    const policies = () =>
-      loaded.entries
-        .filter((entry): entry is Document => entry.type === "document")
-        .toReversed()
-        .flatMap((entry) => entry.info.experimental?.policies ?? [])
+    // Authored documents reverse so user-global policy outranks repository policy; organization statements
+    // from the connected Console follow every authored one and have the final say.
+    const policies = () => {
+      const organization = managed.current()
+      return [
+        ...loaded.entries
+          .filter((entry): entry is Document => entry.type === "document")
+          .toReversed()
+          .flatMap((entry) => entry.info.experimental?.policies ?? [])
+          .map((policy) => ({ ...policy, message: "Blocked by configuration policy" })),
+        ...organization.statements.map((policy) => ({
+          ...policy,
+          message: organization.organization
+            ? `Blocked by ${organization.organization}'s policy`
+            : "Blocked by your organization's policy",
+        })),
+      ]
+    }
     yield* ctx.provider.transform((providers) => {
-      // User-global policy takes priority over policy authored by a repository.
+      const current = policies()
       for (const record of providers.list()) {
-        const policy = policies().findLast(
+        const policy = current.findLast(
           (policy) => policy.action === "provider.use" && Wildcard.match(record.provider.id, policy.resource),
         )
         if (policy?.effect === "deny") providers.remove(record.provider.id)
@@ -29,16 +44,17 @@ export const Plugin = define({
     yield* ctx.permission.hook("evaluate", (event) =>
       Effect.sync(() => {
         const current = policies()
-        const denied = event.resources.some((resource) => {
-          const policy = current.findLast(
-            (policy) =>
-              policy.action === "permission" && Wildcard.match(`${event.action}:${resource}`, policy.resource),
+        const denied = event.resources
+          .map((resource) =>
+            current.findLast(
+              (policy) =>
+                policy.action === "permission" && Wildcard.match(`${event.action}:${resource}`, policy.resource),
+            ),
           )
-          return policy?.effect === "deny"
-        })
+          .find((policy) => policy?.effect === "deny")
         if (!denied) return
         event.effect = "deny"
-        event.message = "Blocked by configuration policy"
+        event.message = denied.message
       }),
     )
   }),

packages/core/src/managed-policy.ts

@@ -0,0 +1,34 @@
+export * as ManagedPolicy from "./managed-policy.js"
+
+import { ConfigPolicy } from "@opencode/schema/config/policy"
+import { Context, Effect, Layer } from "effect"
+import { makeGlobalNode } from "@opencode/util/effect/app-node"
+
+/** Policy statements the connected OpenCode Console compiled for whoever it authenticated. */
+export interface State {
+  readonly statements: ReadonlyArray<ConfigPolicy.Info>
+  /** Organization name for denial messages, when the connection knows it. */
+  readonly organization?: string
+}
+
+export interface Interface {
+  /** Synchronous so catalog transforms can consult the statements while they run. */
+  readonly current: () => State
+  /** Replaces the whole state; statements never merge across connections. */
+  readonly set: (state: State) => Effect.Effect<void>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/ManagedPolicy") {}
+
+const layer = Layer.sync(Service, () => {
+  const state: { current: State } = { current: { statements: [] } }
+  return Service.of({
+    current: () => state.current,
+    set: (next) =>
+      Effect.sync(() => {
+        state.current = next
+      }),
+  })
+})
+
+export const node = makeGlobalNode({ service: Service, layer, deps: [] })

packages/core/src/plugin/internal.ts

@@ -50,6 +50,7 @@ import { Integration } from "../integration.js"
 import { Job } from "../job.js"
 import { KV } from "../kv.js"
 import { Location } from "../location.js"
+import { ManagedPolicy } from "../managed-policy.js"
 import { ModelsDev } from "../models-dev.js"
 import { Mcp } from "../mcp/index.js"
 import { Npm } from "@opencode/util/npm"
@@ -92,6 +93,7 @@ import { PlanPlugin } from "./plan.js"
 import { ModelsDevPlugin } from "./models-dev.js"
 import { McpCodeModeExclusionPlugin } from "./mcp-codemode-exclusion.js"
 import { ProviderPlugins } from "./provider.js"
+import { OpencodePlugin } from "./provider/opencode.js"
 import { WebSearchPlugins } from "./websearch/index.js"
 import { SkillPlugin } from "./skill.js"
 import { VcsHgPlugin } from "./vcs/hg.js"
@@ -126,6 +128,7 @@ const services = [
   KV.Service,
   LLMClient.Service,
   Location.Service,
+  ManagedPolicy.Service,
   ModelsDev.Service,
   Mcp.Service,
   Npm.Service,
@@ -178,6 +181,7 @@ export const requirements = LayerNode.group([
   KV.node,
   llmClient,
   Location.node,
+  ManagedPolicy.node,
   ModelsDev.node,
   Mcp.node,
   Npm.node,
@@ -260,6 +264,10 @@ const post = [
   ConfigPolicyPlugin.Plugin,
 ] as const satisfies readonly InternalPlugin[]
 
+// Repository config must not switch off policy enforcement or the Console connection that delivers
+// organization statements, so plugin remove operations skip these IDs.
+export const guarded: ReadonlySet<string> = new Set([OpencodePlugin.id, ConfigPolicyPlugin.Plugin.id])
+
 export const list = Effect.fn("PluginInternal.list")(function* () {
   // Capture only services; activation supplies the child Scope and batching context.
   const context = Context.pick(...services)(yield* Effect.context<Requirements>())

packages/core/src/plugin/provider/opencode.ts

@@ -7,8 +7,10 @@ import { Bus } from "../../bus.js"
 import { Credential } from "../../credential.js"
 import { Integration } from "../../integration.js"
 import { IntegrationConnection } from "../../integration/connection.js"
+import { ManagedPolicy } from "../../managed-policy.js"
 import { Provider } from "../../provider.js"
 import { WebSearch } from "../../websearch.js"
+import { ConfigPolicy } from "@opencode/schema/config/policy"
 import { ConfigProvider } from "@opencode/schema/config/provider"
 import { Money } from "@opencode/schema/money"
 
@@ -20,6 +22,10 @@ const RemoteResponse = Schema.Struct({
   websearch: Schema.Struct({
     providerID: WebSearch.ID,
   }).pipe(Schema.optional),
+  // Organization policy compiled for the authenticated caller; omitted when there is none.
+  experimental: Schema.Struct({
+    policies: Schema.Array(ConfigPolicy.Info).pipe(Schema.optional),
+  }).pipe(Schema.optional),
 })
 const Device = Schema.Struct({
   device_code: Schema.String,
@@ -112,38 +118,50 @@ function oauth(http: HttpClient.HttpClient) {
   } satisfies IntegrationOAuthMethodRegistration
 }
 
-export const OpencodePlugin = define<HttpClient.HttpClient | Bus.Service | Scope.Scope>({
+export const OpencodePlugin = define<HttpClient.HttpClient | Bus.Service | ManagedPolicy.Service | Scope.Scope>({
   id: "opencode.provider.opencode",
   effect: Effect.fn(function* (ctx) {
     const bus = yield* Bus.Service
     const http = yield* HttpClient.HttpClient
+    const managed = yield* ManagedPolicy.Service
     const loading = Semaphore.makeUnsafe(1)
     type ActiveConnection = Effect.Success<ReturnType<typeof ctx.integration.connection.active>>
     let snapshot: {
       config: typeof RemoteResponse.Type | undefined
       connection: ActiveConnection
-    } = { config: undefined, connection: undefined }
+      organization: string | undefined
+    } = { config: undefined, connection: undefined, organization: undefined }
 
     const load = Effect.fn("OpencodePlugin.load")(function* () {
       const connection = yield* ctx.integration.connection.active("opencode")
-      const credential = connection
-        ? yield* ctx.integration.connection.resolve(connection).pipe(Effect.orElseSucceed(() => undefined))
-        : undefined
-      const config = credential
-        ? yield* fetchConfig(http, credential).pipe(
-            Effect.catch((cause) =>
-              Effect.logWarning("failed to load OpenCode provider config", { cause }).pipe(
-                Effect.as(
-                  IntegrationConnection.key(snapshot.connection) === IntegrationConnection.key(connection)
-                    ? snapshot.config
-                    : undefined,
-                ),
-              ),
-            ),
+      if (!connection) return { config: undefined, connection, organization: undefined }
+      return yield* ctx.integration.connection.resolve(connection).pipe(
+        Effect.flatMap((credential) => {
+          if (!credential) return Effect.succeed({ config: undefined, connection, organization: undefined })
+          return fetchConfig(http, credential).pipe(
+            Effect.map((config) => ({
+              config,
+              connection,
+              organization: typeof credential.metadata?.orgName === "string" ? credential.metadata.orgName : undefined,
+            })),
           )
-        : undefined
-      return { config, connection }
+        }),
+        Effect.catch((cause) =>
+          Effect.logWarning("failed to load OpenCode provider config", { cause }).pipe(
+            // A load that fails for the connection already in place keeps its last config: dropping it
+            // would lift organization policy while personal credentials keep working.
+            Effect.as(
+              IntegrationConnection.key(connection) === IntegrationConnection.key(snapshot.connection)
+                ? { config: snapshot.config, connection, organization: snapshot.organization }
+                : { config: undefined, connection, organization: undefined },
+            ),
+          ),
+        ),
+      )
     })
+    // Statements ride on the snapshot, so a credential switch, disconnect, or 404 replaces them too.
+    const publish = (next: typeof snapshot) =>
+      managed.set({ statements: next.config?.experimental?.policies ?? [], organization: next.organization })
 
     yield* ctx.integration.transform((editor) => {
       editor.update("opencode", (integration) => {
@@ -154,6 +172,7 @@ export const OpencodePlugin = define<HttpClient.HttpClient | Bus.Service | Scope
     })
 
     snapshot = yield* load()
+    yield* publish(snapshot)
     yield* ctx.provider.transform((providers) => {
       for (const [providerID, item] of Object.entries(snapshot.config?.providers ?? {})) {
         const source = providers.get(item.canonical ?? providerID)
@@ -316,6 +335,7 @@ export const OpencodePlugin = define<HttpClient.HttpClient | Bus.Service | Scope
 
     const apply = Effect.fn("OpencodePlugin.apply")(function* (next: typeof snapshot) {
       snapshot = next
+      yield* publish(next)
       yield* Effect.all([ctx.provider.reload(), ctx.websearch.reload()], { concurrency: 2, discard: true })
     })
     const refresh = () => loading.withPermit(load().pipe(Effect.andThen(apply)))

packages/core/src/plugin/supervisor.ts

@@ -39,7 +39,7 @@ const resolve = Effect.fn("PluginSupervisor.resolve")(function* (
     if (operation.type === "remove") {
       if (operation.target === "*") failures.clear()
       plugins()
-        .filter((plugin) => matches(operation.target, plugin.id))
+        .filter((plugin) => matches(operation.target, plugin.id) && !PluginInternal.guarded.has(plugin.id))
         .forEach((plugin) => enabled.delete(plugin.id))
       continue
     }

packages/core/test/codemode/catalog.test.ts

@@ -120,23 +120,19 @@ describe("CodeModeInstructions.render", () => {
     expect(instructions).toContain("## Available tools")
     expect(instructions).toContain("- orders (1 tool)")
     expect(instructions).toContain(`  - ${lookup.signature} // Look up an order by ID`)
-    expect(instructions).not.toContain("## Search")
-    expect(instructions).toContain("The Code Mode tool catalog below is complete.")
-    expect(instructions).toContain("This catalog is the complete set of tools callable inside `execute`.")
-    expect(instructions).toContain("It does not affect tools exposed directly outside Code Mode.")
+    expect(instructions).not.toContain("search")
+    expect(instructions).toContain("They cannot be called directly. They only work inside code you pass to `execute`.")
+    expect(instructions).toContain("The catalog is complete. Do not guess tool names.")
   })
 
   test("adds search guidance when the catalog exceeds the budget", () => {
     const partial = render([lookup], 0)
     expect(partial).toContain("## Available tools")
     expect(partial).toContain("- orders (1 tool, none shown)")
-    expect(partial).toContain("## Search")
-    expect(partial).toContain("Call `search(...)` to discover exact paths and signatures for additional tools:")
-    expect(partial).toContain("The Code Mode tool catalog below is partial.")
+    expect(partial).toContain("They cannot be called directly, and neither can `search`.")
     expect(partial).toContain(
-      "The Code Mode catalog and `search` results are the complete set of tools callable inside `execute`.",
+      "The catalog is partial. Inside `execute`, use `search(...)` to find a tool, then call it by the `path` in the result.",
     )
-    expect(partial).toContain("It does not affect tools exposed directly outside Code Mode.")
     expect(partial).toContain("- search(input: {")
     expect(partial).toContain("  /** @integer @exclusiveMinimum 0 */\n  limit?: number,")
     expect(partial).toContain("  /** @integer @minimum 0 */\n  offset?: number,")
@@ -158,7 +154,7 @@ describe("CodeModeInstructions.render", () => {
       { name: "beta", count: 1, entries: [] },
     ].reduce((total, namespace) => total + Math.round(CodeModeCatalog.namespaceLine(namespace).length / 4), 0)
     const instructions = render([cheapAlpha, expensive, cheapBeta], 40 + namespaceCost)
-    expect(instructions).toContain("## Search")
+    expect(instructions).toContain("The catalog is partial.")
     expect(instructions).toContain("- alpha (2 tools, 1 shown)")
     expect(instructions).toContain(`  - ${cheapAlpha.signature} // Cheap`)
     expect(instructions).not.toContain("tools.alpha.expensive(")
@@ -228,7 +224,7 @@ describe("CodeModeInstructions.update", () => {
     expect(text).toContain(
       "The Code Mode tool catalog has changed. This catalog supersedes the previous Code Mode tool catalog.",
     )
-    expect(text).toContain("## Search")
+    expect(text).toContain("The catalog is partial.")
     expect(text).toContain("## Available tools")
   })
 
@@ -237,7 +233,7 @@ describe("CodeModeInstructions.update", () => {
     const text = update([...previous, echo], [echo])
     expect(text).toContain("This catalog supersedes the previous Code Mode tool catalog.")
     expect(text).toContain("## Available tools")
-    expect(text).not.toContain("## Search")
+    expect(text).toContain("The catalog is complete.")
     expect(text).not.toContain("The following tools are no longer available")
   })
 

packages/core/test/codemode/instructions.test.ts

@@ -46,11 +46,9 @@ describe("CodeModeInstructions", () => {
   it.effect("renders the initial catalog, semantic deltas, and removal", () =>
     Effect.gen(function* () {
       const initialized = yield* readInitial(CodeModeInstructions.make({ tools: [echo] }))
-      expect(initialized.text).toContain(
-        "This catalog is the complete set of tools callable inside `execute`. It does not affect tools exposed directly outside Code Mode.",
-      )
+      expect(initialized.text).toContain("Use the `execute` tool to call the tools listed below.")
+      expect(initialized.text).toContain("The catalog is complete.")
       expect(initialized.text).toContain("## Available tools")
-      expect(initialized.text).not.toContain("## Search")
       expect(initialized.text).toContain(`  - ${echo.signature} // Echo text`)
 
       const added = yield* readUpdate(CodeModeInstructions.make({ tools: [echo, lookup] }), initialized)

packages/core/test/config/policy.test.ts

@@ -1,11 +1,16 @@
 import { describe, expect } from "bun:test"
 import { Document, Event, Info, type Entry } from "@opencode/schema/config"
+import { ConfigPolicy } from "@opencode/schema/config/policy"
+import { Permission } from "@opencode/schema/permission"
 import { Config } from "@opencode/core/config"
 import { ConfigPolicyPlugin } from "@opencode/core/config/plugin/policy"
 import { Bus } from "@opencode/core/bus"
+import { ManagedPolicy } from "@opencode/core/managed-policy"
 import { Plugin } from "@opencode/core/plugin"
+import { PluginHooks } from "@opencode/core/plugin/hooks"
 import { PluginHost } from "@opencode/core/plugin/host"
 import { Provider } from "@opencode/core/provider"
+import { Session } from "@opencode/core/session"
 import { Effect, Schema } from "effect"
 import { testEffect } from "../lib/effect"
 import { PluginTestLayer } from "../plugin/fixture"
@@ -13,15 +18,18 @@ import { PluginTestLayer } from "../plugin/fixture"
 const it = testEffect(PluginTestLayer)
 const decode = Schema.decodeUnknownSync(Info)
 
-const policies = (...items: { effect: "allow" | "deny"; resource: string }[]) =>
-  new Document({
-    type: "document",
-    info: decode({
-      experimental: {
-        policies: items.map((item) => ({ action: "provider.use", ...item })),
-      },
-    }),
-  })
+const document = (...policies: ConfigPolicy.Info[]) =>
+  new Document({ type: "document", info: decode({ experimental: { policies } }) })
+const provider = (effect: ConfigPolicy.Effect, resource: string): ConfigPolicy.Info => ({
+  action: "provider.use",
+  resource,
+  effect,
+})
+const permission = (effect: ConfigPolicy.Effect, resource: string): ConfigPolicy.Info => ({
+  action: "permission",
+  resource,
+  effect,
+})
 
 const addPlugin = Effect.fn(function* (entries: Entry[]) {
   const plugin = yield* Plugin.Service
@@ -29,6 +37,17 @@ const addPlugin = Effect.fn(function* (entries: Entry[]) {
   yield* ConfigPolicyPlugin.Plugin.effect(host).pipe(Effect.provide(Config.testLayer(entries)))
 })
 
+const evaluate = Effect.fn(function* (action: string, resources: string[], effect: Permission.Effect = "allow") {
+  const hooks = yield* PluginHooks.Service
+  const event = yield* hooks.trigger("permission", "evaluate", {
+    sessionID: Session.ID.make("ses_policy"),
+    action,
+    resources,
+    effect,
+  })
+  return { effect: event.effect, message: event.message }
+})
+
 describe("ConfigPolicyPlugin.Plugin", () => {
   it.effect("filters plugin-provided providers with ordered wildcard policies", () =>
     Effect.gen(function* () {
@@ -39,11 +58,7 @@ describe("ConfigPolicyPlugin.Plugin", () => {
         catalog.update(Provider.ID.make("company-internal"), () => {})
       })
       yield* addPlugin([
-        policies(
-          { effect: "deny", resource: "*" },
-          { effect: "allow", resource: "anthropic" },
-          { effect: "allow", resource: "company-*" },
-        ),
+        document(provider("deny", "*"), provider("allow", "anthropic"), provider("allow", "company-*")),
       ])
 
       expect(yield* catalog.get(Provider.ID.openai)).toBeUndefined()
@@ -56,10 +71,7 @@ describe("ConfigPolicyPlugin.Plugin", () => {
     Effect.gen(function* () {
       const catalog = yield* Provider.Service
       yield* catalog.transform((catalog) => catalog.update(Provider.ID.openai, () => {}))
-      yield* addPlugin([
-        policies({ effect: "deny", resource: "openai" }),
-        policies({ effect: "allow", resource: "openai" }),
-      ])
+      yield* addPlugin([document(provider("deny", "openai")), document(provider("allow", "openai"))])
 
       expect(yield* catalog.get(Provider.ID.openai)).toBeUndefined()
     }),
@@ -76,10 +88,122 @@ describe("ConfigPolicyPlugin.Plugin", () => {
       yield* ConfigPolicyPlugin.Plugin.effect(host)
       expect(yield* catalog.get(Provider.ID.openai)).toBeUndefined()
 
-      yield* test.setEntries([policies({ effect: "allow", resource: "openai" })])
+      yield* test.setEntries([document(provider("allow", "openai"))])
       yield* bus.publish(Event.Updated, {})
       yield* waitUntil(catalog.get(Provider.ID.openai).pipe(Effect.map((provider) => provider !== undefined)))
-    }).pipe(Effect.provide(Config.testLayer([policies({ effect: "deny", resource: "openai" })]))),
+    }).pipe(Effect.provide(Config.testLayer([document(provider("deny", "openai"))]))),
+  )
+
+  it.effect("denies permissions matched as action:resource", () =>
+    Effect.gen(function* () {
+      yield* addPlugin([document(permission("deny", "shell:git push *"))])
+
+      expect(yield* evaluate("shell", ["git push"])).toEqual({
+        effect: "deny",
+        message: "Blocked by configuration policy",
+      })
+      expect(yield* evaluate("shell", ["git push origin main"])).toEqual({
+        effect: "deny",
+        message: "Blocked by configuration policy",
+      })
+      // Compound commands check several resources; any denied resource denies the operation.
+      expect((yield* evaluate("shell", ["git status", "git push"])).effect).toBe("deny")
+      expect(yield* evaluate("shell", ["git status"])).toEqual({ effect: "allow", message: undefined })
+      expect(yield* evaluate("edit", ["git push"])).toEqual({ effect: "allow", message: undefined })
+    }),
+  )
+
+  it.effect("turns an ask into a deny but never grants", () =>
+    Effect.gen(function* () {
+      yield* addPlugin([document(permission("deny", "webfetch:*"), permission("allow", "shell:*"))])
+
+      expect((yield* evaluate("webfetch", ["https://example.com"], "ask")).effect).toBe("deny")
+      expect((yield* evaluate("shell", ["ls"], "ask")).effect).toBe("ask")
+    }),
+  )
+
+  it.effect("lets a later allow lift an earlier broad deny", () =>
+    Effect.gen(function* () {
+      yield* addPlugin([document(permission("deny", "shell:*"), permission("allow", "shell:git status *"))])
+
+      expect((yield* evaluate("shell", ["git status --short"])).effect).toBe("allow")
+      expect((yield* evaluate("shell", ["rm -rf /"])).effect).toBe("deny")
+    }),
+  )
+
+  it.effect("denies every permission with a bare wildcard", () =>
+    Effect.gen(function* () {
+      yield* addPlugin([document(permission("deny", "*"))])
+
+      expect((yield* evaluate("question", ["*"])).effect).toBe("deny")
+      expect((yield* evaluate("read", ["/tmp/notes.txt"])).effect).toBe("deny")
+      expect((yield* evaluate("github_delete_repository", ["*"])).effect).toBe("deny")
+    }),
+  )
+
+  it.effect("evaluates organization provider statements after every authored document", () =>
+    Effect.gen(function* () {
+      const catalog = yield* Provider.Service
+      const managed = yield* ManagedPolicy.Service
+      yield* catalog.transform((catalog) => {
+        catalog.update(Provider.ID.openai, () => {})
+        catalog.update(Provider.ID.anthropic, () => {})
+        catalog.update(Provider.ID.opencode, () => {})
+      })
+      yield* managed.set({ statements: [provider("deny", "*"), provider("allow", "opencode")] })
+      yield* addPlugin([document(provider("allow", "anthropic"))])
+
+      expect(yield* catalog.get(Provider.ID.anthropic)).toBeUndefined()
+      expect(yield* catalog.get(Provider.ID.openai)).toBeUndefined()
+      expect(yield* catalog.get(Provider.ID.opencode)).toBeDefined()
+    }),
+  )
+
+  it.effect("lets an organization allow restore a provider denied by the user", () =>
+    Effect.gen(function* () {
+      const catalog = yield* Provider.Service
+      const managed = yield* ManagedPolicy.Service
+      yield* catalog.transform((catalog) => catalog.update(Provider.ID.openai, () => {}))
+      yield* managed.set({ statements: [provider("allow", "openai")] })
+      yield* addPlugin([document(provider("deny", "openai"))])
+
+      expect(yield* catalog.get(Provider.ID.openai)).toBeDefined()
+    }),
+  )
+
+  it.effect("names the organization when its permission statement decides", () =>
+    Effect.gen(function* () {
+      const managed = yield* ManagedPolicy.Service
+      yield* managed.set({ statements: [permission("deny", "shell:sudo *")], organization: "Acme" })
+      yield* addPlugin([document(permission("allow", "shell:*"))])
+
+      expect(yield* evaluate("shell", ["sudo ls"])).toEqual({ effect: "deny", message: "Blocked by Acme's policy" })
+      expect((yield* evaluate("shell", ["ls"])).effect).toBe("allow")
+
+      yield* managed.set({ statements: [permission("deny", "shell:sudo *")] })
+      expect(yield* evaluate("shell", ["sudo ls"])).toEqual({
+        effect: "deny",
+        message: "Blocked by your organization's policy",
+      })
+    }),
+  )
+
+  it.effect("rebuilds the catalog from replaced organization statements", () =>
+    Effect.gen(function* () {
+      const catalog = yield* Provider.Service
+      const managed = yield* ManagedPolicy.Service
+      yield* catalog.transform((catalog) => catalog.update(Provider.ID.openai, () => {}))
+      yield* addPlugin([])
+      expect(yield* catalog.get(Provider.ID.openai)).toBeDefined()
+
+      yield* managed.set({ statements: [provider("deny", "openai")] })
+      yield* catalog.reload()
+      expect(yield* catalog.get(Provider.ID.openai)).toBeUndefined()
+
+      yield* managed.set({ statements: [] })
+      yield* catalog.reload()
+      expect(yield* catalog.get(Provider.ID.openai)).toBeDefined()
+    }),
   )
 })
 

packages/core/test/plugin/fixture.ts

@@ -14,6 +14,7 @@ import { Generate } from "@opencode/core/generate"
 import { Integration } from "@opencode/core/integration"
 import { KV } from "@opencode/core/kv"
 import { Location } from "@opencode/core/location"
+import { ManagedPolicy } from "@opencode/core/managed-policy"
 import { Mcp } from "@opencode/core/mcp/index"
 import { Model } from "@opencode/core/model"
 import { Npm } from "@opencode/util/npm"
@@ -85,6 +86,7 @@ export const PluginTestLayer = AppNodeBuilder.build(
     Command.node,
     Integration.node,
     KV.node,
+    ManagedPolicy.node,
     Mcp.node,
     Session.node,
     PersistentPty.node,

packages/core/test/plugin/provider-opencode.test.ts

@@ -1,12 +1,16 @@
 import { describe, expect } from "bun:test"
 import { LLM } from "@opencode/ai"
 import { LLMClient, RequestExecutor } from "@opencode/ai/route"
+import { ConfigPolicy } from "@opencode/schema/config/policy"
 import { Money } from "@opencode/schema/money"
 import { Effect, Layer, Stream } from "effect"
 import { TestClock } from "effect/testing"
 import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+import { Config } from "@opencode/core/config"
+import { ConfigPolicyPlugin } from "@opencode/core/config/plugin/policy"
 import { Credential } from "@opencode/core/credential"
 import { Integration } from "@opencode/core/integration"
+import { ManagedPolicy } from "@opencode/core/managed-policy"
 import { Model } from "@opencode/core/model"
 import { ModelResolver } from "@opencode/core/model-resolver"
 import { Plugin } from "@opencode/core/plugin"
@@ -628,6 +632,158 @@ describe("OpencodePlugin", () => {
     ),
   )
 
+  it.effect("enforces organization policy statements from the Console", () =>
+    Effect.acquireUseRelease(
+      Effect.sync(() =>
+        Bun.serve({
+          port: 0,
+          fetch: () =>
+            Response.json({
+              providers: { opencode: {} },
+              experimental: {
+                policies: [
+                  { action: "provider.use", resource: "*", effect: "deny" },
+                  { action: "provider.use", resource: "opencode", effect: "allow" },
+                  { action: "permission", resource: "shell:sudo *", effect: "deny", audience: "ignored" },
+                ],
+                unknown: true,
+              },
+            }),
+        }),
+      ),
+      (server) =>
+        Effect.gen(function* () {
+          const credentials = yield* Credential.Service
+          const catalog = yield* Provider.Service
+          const managed = yield* ManagedPolicy.Service
+          const plugins = yield* Plugin.Service
+          yield* catalog.transform((catalog) => catalog.update(Provider.ID.anthropic, () => {}))
+          yield* credentials.create({
+            integrationID: Integration.ID.make("opencode"),
+            value: Credential.Key.make({
+              type: "key",
+              key: "secret",
+              metadata: { server: server.url.origin, orgID: "org_test", orgName: "Acme" },
+            }),
+          })
+          const host = yield* PluginHost.make(plugins)
+          yield* OpencodePlugin.effect(host)
+          yield* ConfigPolicyPlugin.Plugin.effect(host).pipe(Effect.provide(Config.testLayer([])))
+
+          expect(managed.current()).toEqual({
+            statements: [
+              { action: "provider.use", resource: "*", effect: "deny" },
+              { action: "provider.use", resource: "opencode", effect: "allow" },
+              { action: "permission", resource: "shell:sudo *", effect: "deny" },
+            ],
+            organization: "Acme",
+          })
+          expect(yield* catalog.get(Provider.ID.anthropic)).toBeUndefined()
+          expect(yield* catalog.get(Provider.ID.opencode)).toBeDefined()
+        }),
+      (server) => Effect.promise(() => server.stop(true)),
+    ),
+  )
+
+  it.effect("keeps policy statements bound to the connected Console account", () =>
+    Effect.acquireUseRelease(
+      Effect.sync(() => {
+        const state: { status: number; policies: Record<string, unknown[]>; requests: number } = {
+          status: 200,
+          policies: {},
+          requests: 0,
+        }
+        const server = Bun.serve({
+          port: 0,
+          fetch: (request) => {
+            state.requests++
+            if (state.status !== 200) return new Response("Unavailable", { status: state.status })
+            const policies = state.policies[request.headers.get("x-org-id") ?? ""]
+            return Response.json({ providers: {}, ...(policies ? { experimental: { policies } } : {}) })
+          },
+        })
+        return { server, state }
+      }),
+      ({ server, state }) =>
+        Effect.gen(function* () {
+          const credentials = yield* Credential.Service
+          const providers = yield* Provider.Service
+          const managed = yield* ManagedPolicy.Service
+          const rebuilds = { count: 0 }
+          const account = (orgID: string, orgName: string) =>
+            credentials.create({
+              integrationID: Integration.ID.make("opencode"),
+              value: Credential.Key.make({
+                type: "key",
+                key: orgID,
+                metadata: { server: server.url.origin, orgID, orgName },
+              }),
+            })
+          const sudo: ConfigPolicy.Info = { action: "permission", resource: "shell:sudo *", effect: "deny" }
+          const env: ConfigPolicy.Info = { action: "permission", resource: "edit:*.env", effect: "deny" }
+          yield* providers.transform(() => {
+            rebuilds.count++
+          })
+          const alpha = yield* account("org_alpha", "Alpha")
+          yield* addPlugin()
+          yield* drain
+          const initial = rebuilds.count
+          expect(state.requests).toBe(1)
+          expect(managed.current()).toEqual({ statements: [], organization: "Alpha" })
+
+          state.policies.org_alpha = [sudo]
+          yield* TestClock.adjust("1 minute")
+          yield* drain
+          expect(state.requests).toBe(2)
+          expect(managed.current()).toEqual({ statements: [sudo], organization: "Alpha" })
+          expect(rebuilds.count).toBe(initial + 1)
+
+          yield* TestClock.adjust("1 minute")
+          yield* drain
+          expect(state.requests).toBe(3)
+          expect(rebuilds.count).toBe(initial + 1)
+
+          // An outage for the same connection keeps the last statements instead of lifting them.
+          state.status = 503
+          yield* TestClock.adjust("1 minute")
+          yield* drain
+          expect(state.requests).toBe(4)
+          expect(managed.current()).toEqual({ statements: [sudo], organization: "Alpha" })
+          expect(rebuilds.count).toBe(initial + 1)
+
+          state.status = 200
+          state.policies.org_beta = [env]
+          const beta = yield* account("org_beta", "Beta")
+          yield* eventually(
+            Effect.sync(() => managed.current()),
+            (current) => current.organization === "Beta",
+          )
+          expect(managed.current()).toEqual({ statements: [env], organization: "Beta" })
+
+          state.status = 404
+          yield* TestClock.adjust("1 minute")
+          yield* drain
+          expect(managed.current()).toEqual({ statements: [], organization: "Beta" })
+
+          state.status = 200
+          yield* credentials.remove(beta.id)
+          yield* eventually(
+            Effect.sync(() => managed.current()),
+            (current) => current.organization === "Alpha",
+          )
+          expect(managed.current()).toEqual({ statements: [sudo], organization: "Alpha" })
+
+          yield* credentials.remove(alpha.id)
+          yield* eventually(
+            Effect.sync(() => managed.current()),
+            (current) => current.organization === undefined,
+          )
+          expect(managed.current()).toEqual({ statements: [], organization: undefined })
+        }),
+      ({ server }) => Effect.promise(() => server.stop(true)),
+    ),
+  )
+
   it.live("loads and executes hosted web search from the connected OpenCode server", () =>
     Effect.acquireUseRelease(
       Effect.sync(() => {

packages/core/test/plugin/supervisor.test.ts

@@ -32,14 +32,14 @@ const greeter = (command: string, plugin: string = id) =>
   })
 
 // Every supervisor activation scans the config plugin operations once, so counting scans counts activations.
-const source = { activations: 0 }
+const source: { activations: number; operations: ConfigPluginSource.Operation[] } = { activations: 0, operations: [] }
 const sourceLayer = Layer.succeed(
   ConfigPluginSource.Service,
   ConfigPluginSource.Service.of({
     operations: () =>
       Effect.sync(() => {
         source.activations++
-        return []
+        return source.operations
       }),
     changes: () => Stream.never,
   }),
@@ -202,6 +202,36 @@ describe("PluginSupervisor", () => {
     }),
   )
 
+  for (const targets of [["opencode.config.policy", "opencode.provider.opencode", "opencode.config.agent"], ["*"]]) {
+    it.effect(`keeps policy enforcement and the Console connection through plugin removals: ${targets}`, () =>
+      Effect.gen(function* () {
+        source.operations = targets.map((target) => ({ type: "remove", target }))
+        const directory = yield* tmpdirScoped()
+        const locations = yield* LocationServiceMap.Service
+        const inventory = yield* Effect.gen(function* () {
+          const plugins = yield* Plugin.Service
+          yield* plugins.awaitActivation
+          return yield* plugins.list()
+        }).pipe(
+          Effect.scoped,
+          Effect.provide(locations.get(Location.Ref.make({ directory: AbsolutePath.make(directory.path) }))),
+        )
+        const status = (id: string) => inventory.find((plugin) => plugin.id === id)?.state.status
+        expect(status("opencode.config.policy")).toBe("active")
+        expect(status("opencode.provider.opencode")).toBe("active")
+        // Removals still apply to everything else, including instance and builtin plugins.
+        expect(status("opencode.config.agent")).toBeUndefined()
+        expect(inventory.some((plugin) => plugin.id === id)).toBe(targets[0] !== "*")
+      }).pipe(
+        Effect.ensuring(
+          Effect.sync(() => {
+            source.operations = []
+          }),
+        ),
+      ),
+    )
+  }
+
   it.effect("coalesces a burst of reload triggers after the initial generation into one activation", () =>
     Effect.gen(function* () {
       source.activations = 0

services/www/src/docs/content/config.mdx

@@ -179,6 +179,26 @@ matching resource.
 
 See the [permissions guide](/permissions) for rule matching and available actions.
 
+### Policies
+
+Allow or deny use of a provider, or hard-deny a permission check, with ordered
+statements that broader configuration can override.
+
+```jsonc
+{
+  "experimental": {
+    "policies": [
+      { "action": "provider.use", "resource": "*", "effect": "deny" },
+      { "action": "provider.use", "resource": "anthropic", "effect": "allow" },
+      { "action": "permission", "resource": "shell:git push *", "effect": "deny" },
+    ],
+  },
+}
+```
+
+See the [policies guide](/policies) for matching, precedence across configuration
+files, and Console-managed policy.
+
 ### Agents
 
 Override built-in agents or define specialized agents with their own model,

services/www/src/docs/content/console/index.mdx

@@ -11,3 +11,10 @@ using OpenCode particularly as a team
 - Deploy team wide policies to control OpenCode behavior
 - Web search
 - OpenCode Go, $10 subscription for open source model access
+
+## Policies
+
+Providers and Tools rules from the Policies page apply to every OpenCode V2 client
+connected to the workspace. They are delivered as [policy](/policies#console)
+statements with final authority over the member's own configuration and take effect
+within about a minute.

services/www/src/docs/content/migrate-v1.mdx

@@ -415,7 +415,8 @@ Most fields that keep the same shape, including `shell`, `model`, `default_agent
 V2 accepts and preserves `lsp` configuration, but it does not run language servers, expose LSP tools, or produce LSP
 diagnostics. Replace workflows that depend on those capabilities with the project's lint, typecheck, or compiler commands.
 
-The V1 provider filters do not have one-to-one native V2 config fields, but their behavior remains supported:
+The V1 provider filters do not have one-to-one native V2 config fields, but their behavior remains supported through
+[policies](/policies):
 
 - `enabled_providers` becomes an internal deny-by-default provider policy followed by allows for the listed providers.
 - `disabled_providers` becomes internal deny policies for the listed providers.

services/www/src/docs/content/permissions.mdx

@@ -277,3 +277,19 @@ Review broad approvals and remove those no longer needed.
 
 Clients may attach feedback when rejecting. Non-interactive clients must decide
 how to handle approval requests; configured `deny` rules always remain enforced.
+
+## Policies
+
+A [policy](/policies) can hard-deny a permission check after these rules and saved
+approvals run. It turns `allow` or `ask` into `deny` and never grants access.
+
+```jsonc
+{
+  "experimental": {
+    "policies": [{ "action": "permission", "resource": "shell:sudo *", "effect": "deny" }],
+  },
+}
+```
+
+Global and Console-managed policies override project configuration, which is how an
+organization blocks a command that a repository would allow.

services/www/src/docs/content/plugins.mdx

@@ -76,6 +76,11 @@ use `.*` to match an ID prefix. A later ID re-enables a plugin.
 }
 ```
 
+Two built-in plugins ignore removals so that a repository cannot switch off
+[policy](/policies) enforcement: `opencode.config.policy` and
+`opencode.provider.opencode`, the Console connection that delivers organization
+policy.
+
 ## Manage
 
 Install, list, check, update, or remove global package plugins with the CLI.

services/www/src/docs/content/policies.mdx

@@ -0,0 +1,216 @@
+---
+title: "Policies"
+description: "Allow or deny OpenCode actions on named resources, with organization policy taking final authority."
+---
+
+Policies decide whether OpenCode may perform an action on a named resource. They are
+authored under `experimental.policies` and can also be delivered by a connected
+[OpenCode Console](/console) workspace.
+
+Policies are separate from [permissions](/permissions). Permissions are per-agent tool
+rules that can `allow`, `deny`, or `ask`. Policies are binary, never prompt, and only
+ever tighten what permissions and providers would otherwise allow.
+
+## Configure
+
+Deny one provider everywhere by adding a statement to `opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "experimental": {
+    "policies": [{ "action": "provider.use", "resource": "openai", "effect": "deny" }],
+  },
+}
+```
+
+A denied provider disappears from the catalog and model selection even when it has
+valid credentials.
+
+## Statements
+
+Each statement has three fields:
+
+| Field      | Values                       | Meaning                                              |
+| ---------- | ---------------------------- | ---------------------------------------------------- |
+| `action`   | `provider.use`, `permission` | The operation being controlled                       |
+| `resource` | string or wildcard pattern   | What the statement applies to; depends on the action |
+| `effect`   | `allow`, `deny`              | The decision when this statement matches             |
+
+Statements that fail validation are dropped with a warning in the server log and
+the rest of the list still applies. Check the log after editing a `deny`.
+
+## Matching
+
+Resources use the same whole-value wildcards as permissions: `*` matches zero or
+more characters and `?` matches one.
+
+```jsonc
+{
+  "experimental": {
+    "policies": [{ "action": "provider.use", "resource": "company-*", "effect": "deny" }],
+  },
+}
+```
+
+This denies `company-us` and `company-eu`. A pattern ending in ` *` also matches the
+value without arguments, so `shell:git push *` covers `git push` on its own.
+
+## Order
+
+When several statements match, the last one wins. There is no specificity rule, so
+put broad statements first and exceptions after them. If nothing matches, the
+action is allowed.
+
+```jsonc
+{
+  "experimental": {
+    "policies": [
+      { "action": "provider.use", "resource": "*", "effect": "deny" },
+      { "action": "provider.use", "resource": "anthropic", "effect": "allow" },
+    ],
+  },
+}
+```
+
+Only Anthropic remains available.
+
+## Providers
+
+`provider.use` controls whether a provider is usable at all. The resource is the
+provider ID: `anthropic`, `openai`, `opencode`, or a custom ID from
+[`providers`](/providers).
+
+```jsonc
+{
+  "providers": {
+    "company-ai": {
+      "package": "@opencode/ai/providers/openai-compatible",
+      "settings": { "baseURL": "https://ai.company.example/v1" },
+    },
+  },
+  "experimental": {
+    "policies": [
+      { "action": "provider.use", "resource": "*", "effect": "deny" },
+      { "action": "provider.use", "resource": "company-ai", "effect": "allow" },
+    ],
+  },
+}
+```
+
+The `providers` entry configures the endpoint; the statements make it the only
+provider OpenCode will use. Policy applies however a provider became known: catalog
+data, environment variables, saved accounts, built-in plugins, or configuration.
+
+Use `provider.use` instead of the V1 `enabled_providers` and `disabled_providers`
+lists. V1 files still load; see
+[Migrate from V1](/migrate-v1#supported-fields-without-direct-native-equivalents).
+
+## Permissions
+
+`permission` statements hard-deny a [permission](/permissions) check. The resource is
+`<action>:<value>`, matched against every resource the tool checks.
+
+```jsonc
+{
+  "experimental": {
+    "policies": [
+      { "action": "permission", "resource": "shell:git push *", "effect": "deny" },
+      { "action": "permission", "resource": "edit:*.env", "effect": "deny" },
+      { "action": "permission", "resource": "webfetch:*", "effect": "deny" },
+    ],
+  },
+}
+```
+
+A denied check fails with `Blocked by configuration policy` instead of prompting. It
+applies after agent rules and saved approvals, so it overrides an `ask` and an
+"Allow always" approval alike.
+
+| Pattern                      | Blocks                                      |
+| ---------------------------- | ------------------------------------------- |
+| `shell:*`                    | Every shell command                         |
+| `read:*/.ssh/*`              | Reading SSH material                        |
+| `external_directory:*`       | Any access outside the Location or worktree |
+| `subagent:general`           | Launching one subagent                      |
+| `github_delete_repository:*` | One MCP tool                                |
+| `*`                          | Everything not already denied               |
+
+A `permission` statement with `allow` never grants access. It only lifts an earlier
+broader `deny`, after which the agent's own rules decide.
+
+```jsonc
+{
+  "experimental": {
+    "policies": [
+      { "action": "permission", "resource": "shell:*", "effect": "deny" },
+      { "action": "permission", "resource": "shell:git status *", "effect": "allow" },
+    ],
+  },
+}
+```
+
+`git status` falls back to the agent's `shell` rule; every other command is blocked.
+
+## Precedence
+
+Ordinary settings let the nearest configuration win. Policies reverse that: statements
+from broader configuration are evaluated later, so they override narrower ones.
+
+| Authority   | Source                                                          |
+| ----------- | --------------------------------------------------------------- |
+| 1 (highest) | Connected OpenCode Console workspace                            |
+| 2           | Global `~/.config/opencode/opencode.json(c)`                    |
+| 3           | Direct `opencode.json(c)`; outer directories beat inner ones    |
+| 4 (lowest)  | `.opencode/opencode.json(c)`; outer directories beat inner ones |
+
+A repository cannot re-enable a provider you deny globally:
+
+```jsonc title="~/.config/opencode/opencode.jsonc"
+{
+  "experimental": {
+    "policies": [{ "action": "provider.use", "resource": "openai", "effect": "deny" }],
+  },
+}
+```
+
+```jsonc title="project/opencode.jsonc"
+{
+  "experimental": {
+    "policies": [{ "action": "provider.use", "resource": "openai", "effect": "allow" }],
+  },
+}
+```
+
+`openai` stays denied. Within one file, statements keep their written order.
+
+## Console
+
+A workspace on the [OpenCode Console](/console) compiles its Providers and Tools
+policies into statements and returns them with the workspace configuration. OpenCode
+appends them after every authored statement, so they have the final say: an
+organization `deny` cannot be lifted by a repository or user `allow`, and an
+organization `allow` lifts a lower-authority `deny`.
+
+Denials from these statements name the workspace:
+
+```text
+Blocked by Acme's policy
+```
+
+Statements follow the connected account.
+
+| Event                       | Result                                             |
+| --------------------------- | -------------------------------------------------- |
+| Console policy changes      | Applied on the next fetch, about once a minute     |
+| Switch to another workspace | Statements replaced with that workspace's          |
+| Disconnect                  | Statements cleared                                 |
+| Console unreachable         | Last statements for that connection stay in effect |
+
+The Console plugin and the policy plugin cannot be disabled from `plugins`; see
+[plugin control](/plugins#control).
+
+<Callout type="note">
+  Policies do not configure endpoints or credentials, and they cannot make an unusable provider usable. They also do not
+  sandbox plugin code: a denied provider is blocked on the normal provider and model path.
+</Callout>

services/www/src/docs/lib/navigation.ts

@@ -49,6 +49,7 @@ export const docsSections: DocsSection[] = [
           { title: "Tools", slug: "tools" },
           { title: "MCP servers", slug: "mcp-servers" },
           { title: "Permissions", slug: "permissions" },
+          { title: "Policies", slug: "policies" },
           { title: "Instructions", slug: "instructions" },
           { title: "Sharing", slug: "sharing" },
           { title: "Warming", slug: "warming" },

specs/v2/README.md

@@ -26,10 +26,10 @@ Generated clients follow the assembled public `HttpApi`. GitHub issues own activ
 
 ## Decision Records
 
-| Document                                       | Status                   | Job                                                                      |
-| ---------------------------------------------- | ------------------------ | ------------------------------------------------------------------------ |
-| [Event stream](./event-stream-architecture.md) | Accepted and implemented | Record why public events use one encoded feed with independent queues.   |
-| [Provider policy](./provider-policy.md)        | Accepted and implemented | Record provider authorization independently from provider configuration. |
+| Document                                       | Status                   | Job                                                                                                       |
+| ---------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------- |
+| [Event stream](./event-stream-architecture.md) | Accepted and implemented | Record why public events use one encoded feed with independent queues.                                    |
+| [Provider policy](./provider-policy.md)        | Accepted and implemented | Allow or deny provider use and permission checks, with Console-managed statements having final authority. |
 
 ## Historical Context
 

specs/v2/provider-policy.md

@@ -4,13 +4,16 @@ Status: **Implemented.**
 
 ## Purpose
 
-Policies control whether an operation on a named resource is allowed. Statements are authored in configuration files and applied by a terminal catalog plugin.
+Policies control whether an operation on a named resource is allowed. Statements are authored in configuration files or delivered by the connected OpenCode Console, and applied by a terminal plugin.
 
-The first policy consumer is provider availability:
+Two consumers exist:
 
 ```text
 action:   provider.use
 resource: provider ID, such as openai or company-ai
+
+action:   permission
+resource: <permission action>:<resource>, such as shell:sudo * or edit:*.env
 ```
 
 Provider configuration and provider policy remain separate:
@@ -34,7 +37,7 @@ A provider can be correctly configured and have valid credentials while policy s
 - Policies do not configure endpoints, credentials, models, or provider options.
 - Policies do not make unusable resources usable.
 - Policies do not currently provide conditions, principals, approval prompts, or enforced configuration values.
-- This spec does not define how organization-managed policies are delivered.
+- A `permission` statement never grants access; permissions and saved approvals still decide `allow` versus `ask`.
 
 ## Statement Shape
 
@@ -55,12 +58,12 @@ A provider can be correctly configured and have valid credentials while policy s
 ```ts
 interface PolicyInfo {
   effect: "allow" | "deny"
-  action: string
+  action: "provider.use" | "permission"
   resource: string
 }
 ```
 
-`ConfigPolicy` owns the statement schema. The policy plugin interprets the supported `provider.use` action after all other catalog transforms have run.
+`ConfigPolicy` owns the statement schema; `action` is a closed set and a statement with any other value is dropped during normalization with a diagnostic. The policy plugin interprets `provider.use` after all other catalog transforms have run and `permission` after every other permission evaluation hook.
 
 ## Matching
 
@@ -68,11 +71,12 @@ Both `action` and `resource` use opencode's existing wildcard matching behavior.
 
 Examples:
 
-| Action         | Resource    | Matches                                                                      |
-| -------------- | ----------- | ---------------------------------------------------------------------------- |
-| `provider.use` | `openai`    | Only use of provider ID `openai`                                             |
-| `provider.use` | `company-*` | Use of provider IDs such as `company-us` and `company-eu`                    |
-| `provider.*`   | `*`         | Any provider operation on any provider, if more actions are introduced later |
+| Action         | Resource           | Matches                                                         |
+| -------------- | ------------------ | --------------------------------------------------------------- |
+| `provider.use` | `openai`           | Only use of provider ID `openai`                                |
+| `provider.use` | `company-*`        | Use of provider IDs such as `company-us` and `company-eu`       |
+| `permission`   | `shell:git push *` | The `shell` permission for `git push` with or without arguments |
+| `permission`   | `*`                | Every permission check on every resource                        |
 
 No pattern-specific precedence exists. A specific resource does not automatically beat a wildcard resource. Written/evaluation order controls the result.
 
@@ -193,26 +197,72 @@ The relative policy precedence of direct project files and `.opencode` files is
 
 ## Organization-Managed Policy
 
-Organization-managed policy is not ordinary authored config. When implemented, managed statements must be appended after the reversed authored statements so they have final authority.
+Organization-managed policy is not ordinary authored config. Managed statements are appended after the reversed authored statements so they have final authority: an organization `deny` cannot be lifted by a repository or user `allow`, and an organization `allow` lifts a lower-authority `deny`.
 
 ```text
 repository policy -> user-global policy -> organization-managed policy
 ```
 
+### Delivery
+
+The OpenCode Console compiles a workspace's Providers and Tools policies into statements for the authenticated caller and returns them from `GET /api/v2/config` alongside managed providers:
+
+```jsonc
+{
+  "providers": { "opencode": {} },
+  "experimental": {
+    "policies": [
+      { "action": "provider.use", "resource": "*", "effect": "deny" },
+      { "action": "provider.use", "resource": "opencode", "effect": "allow" },
+      { "action": "permission", "resource": "shell:sudo *", "effect": "deny" },
+    ],
+  },
+}
+```
+
+- `experimental` is omitted when the caller has no statements; omission and an empty array are equivalent.
+- The list is per caller and its order is significant. The client stores it exactly as received; it never reorders, dedupes, or normalizes statements.
+- `ManagedPolicy` (`packages/core/src/managed-policy.ts`) is the process-global home for the current statements and the organization name. The Console plugin (`opencode.provider.opencode`) writes it whenever its config snapshot is applied; the policy plugin reads it synchronously when evaluating.
+- Statements ride on the Console plugin's snapshot, so they follow the connection: a credential switch replaces them, and a disconnect or a 404 from the Console clears them. Statements from different connections never merge.
+- Freshness is the snapshot's freshness: the next poll (about one minute) or the next credential switch.
+
+### Failure
+
+A config fetch or credential refresh that fails for the connection already in place keeps that connection's last config, providers and statements alike, and logs a warning. Dropping the config would fail closed for managed providers but open for policy, because a member's personal credentials keep working while the organization's restrictions vanish. A disconnect, a credential switch, or a 404 still replaces the snapshot. There is no durable offline cache.
+
+### Messages
+
+When the deciding `permission` statement is organization-managed, the denial reads `Blocked by <organization>'s policy`, or `Blocked by your organization's policy` when the connection has no organization name. Authored statements produce `Blocked by configuration policy`.
+
+### Protection
+
 Plugins must not be allowed to add, remove, or override policy statements. Plugins can contribute functionality or configured providers; policy determines whether opencode permits an operation through its managed execution paths.
 
+Plugin `remove` operations in config ignore `opencode.config.policy` and `opencode.provider.opencode`, whatever the selector (`-*`, `-opencode.*`, or the exact ID). Otherwise a repository could switch off enforcement or the fetch that delivers organization statements.
+
 Provider policy is not a full sandbox for executable plugins. A denied provider must not be usable through the normal provider/model path, but arbitrary plugin code requires separate governance if that becomes a compliance requirement.
 
+## Permission Policy
+
+`permission` statements run in the `permission.evaluate` hook after agent and session rules, saved approvals, and every other plugin's hook. For each resource the tool checks, the string `<action>:<resource>` is matched against the statement resource; if the last matching statement for any resource is `deny`, the evaluation becomes `deny` with the message above.
+
+```text
+permission / shell:sudo ls        -> deny   (statement shell:sudo *)
+permission / shell:git status     -> unchanged: the agent's rules decide allow or ask
+```
+
+- A configured `deny` from agent or session rules already denies before the hook runs.
+- A statement `deny` overrides `allow` and `ask`, including saved "Allow always" approvals.
+- A statement `allow` never grants; it only cancels an earlier, broader statement `deny`.
+
 ## Interaction With Provider Configuration
 
 ```jsonc
 {
   "providers": {
     "company-ai": {
-      "endpoint": {
-        "type": "openai/responses",
-        "url": "https://ai.company.example/v1/responses",
-      },
+      "package": "@opencode/ai/providers/openai-compatible",
+      "settings": { "baseURL": "https://ai.company.example/v1" },
     },
   },
   "experimental": {
@@ -240,12 +290,12 @@ Provider records and model overrides are assembled before checking provider poli
 
 Flow:
 
-1. Build provider/model catalog entries.
+1. Build provider/model catalog entries, including providers managed by the connected Console.
 2. Apply configured provider and model overrides.
-3. Run the terminal config policy transform.
+3. Run the terminal config policy transform over the reversed authored statements followed by the organization-managed statements.
 4. Remove providers denied by the final matching `provider.use` statement.
 
-Config reload refreshes the plugin's policy snapshot and rebuilds the catalog.
+Config reload refreshes the plugin's policy snapshot and rebuilds the catalog. A changed Console snapshot rebuilds the catalog through the Console plugin's own reload, which re-runs the terminal transform.
 
 ## Legacy Migration