@opencode/codemode 2.0.10 → 2.0.12

package/README.md

@@ -13,8 +13,8 @@ The idea of code mode was originally introduced by Cloudflare. See
 
 ## How it differs from JavaScript
 
-- **Only supported APIs are available.** Programs can use the provided tools and supported JavaScript built-ins. APIs
-  such as `fetch`, timers, `process`, filesystem access, imports, and modules are unavailable.
+- **Only supported APIs are available.** Programs can use the provided tools, supported JavaScript built-ins, and the
+  globals the host adds through extensions. Timers, `process`, filesystem access, imports, and modules are unavailable.
 - **Unfinished work is interrupted.** Tool calls and async functions start when called. When the program finishes,
   anything still running is interrupted. Unhandled rejections from un-awaited promises are returned as warnings.
 - **REPL-style results.** Without an explicit `return`, the final top-level expression becomes the result. `undefined`
@@ -94,11 +94,19 @@ receive `{ extension, name, args }`. An `after` hook also receives how the call
 `failure` with its error, or `interrupted`). A failing `before` hook denies the call, and the program catches the
 failure as a thrown error.
 
-### `Values`
+### `Extension.make`
 
-`Values` exports the runtime's non-JSON value classes: `Values.URL`, `Values.URLSearchParams`, `Values.Date`,
-`Values.RegExp`, `Values.Map`, `Values.Set`, and `Values.Promise`. The interpreter recognizes these by class; a
-program's `new URL(...)` is a `Values.URL` wrapping the host `URL`. `Values.isValue` narrows to the data-like kinds.
+Extensions are host functions a program calls directly as globals, such as `fetch`. Unlike tools they are not in the
+catalog, not counted against `maxToolCalls`, and not described to the model; the host decides what they mean.
+
+```ts
+const web = Extension.make({ name: "web", globals: { fetch: (url: string) => globalThis.fetch(url) } })
+const runtime = CodeMode.make({ tools, extensions: [web] })
+```
+
+Every value crossing in either direction is converted, never shared: arguments come in as copies, results go out as
+copies, and a function inside a result is callable the same way. A global that shadows a built-in or another
+extension throws at `CodeMode.make`.
 
 ### OpenAPI tools
 

package/dist/data.js

@@ -2,7 +2,7 @@ export * as Data from "./data.js";
 import { Effect } from "effect";
 import { MAX_VALUE_DEPTH } from "./interpreter/limits.js";
 import { invalidData, rangeError, typeError } from "./interpreter/model.js";
-import { Arr, Bytes, Callable, define, ErrorObj, get, keys, Obj, PromiseObj, record, SetObj, URLSearchParamsObj, } from "./interpreter/objects.js";
+import { Arr, Bytes, Callable, define, ErrorObj, get, keys, Obj, PromiseObj, record, SetObj, URLSearchParamsObj, HeadersObj, } from "./interpreter/objects.js";
 import { typeofValue } from "./interpreter/references.js";
 /**
  * What `JSON.stringify` would serialize for a program value, as host JSON: `toJSON` is honored, functions and
@@ -42,6 +42,8 @@ const walk = (ctx, value, replacer, boundary) => {
         }
         if (boundary && value instanceof URLSearchParamsObj)
             return value.params.toString();
+        if (value instanceof HeadersObj)
+            return Object.fromEntries(value.headers);
         const target = boundary && value instanceof SetObj ? new Arr(ctx.builtins.Array, [...value.set]) : value;
         if (stack.has(target))
             throw typeError("Converting circular structure to JSON.");

package/dist/interpreter/callback.d.ts

@@ -14,6 +14,8 @@ export declare const preserveConsumerError: <A, R>(cursor: IteratorCursor<R>, ef
  * default hint as "string", like their `Symbol.toPrimitive`.
  */
 export declare const toPrimitive: <R>(ctx: Interpreter<R>, value: unknown, hint: "number" | "string" | "default") => Effect.Effect<unknown, unknown, R>;
+/** Invoke(value, name): calls the method the value would find through its prototype. */
+export declare const invoke: <R>(ctx: Interpreter<R>, value: unknown, name: string, label: string) => Effect.Effect<unknown, unknown, R>;
 export declare const toPrimitiveString: <R>(ctx: Interpreter<R>, value: unknown) => Effect.Effect<string, unknown, R>;
 export declare const toPrimitiveNumber: <R>(ctx: Interpreter<R>, value: unknown) => Effect.Effect<number, unknown, R>;
 export declare const isSupportedCallback: (value: unknown) => value is Callable;

package/dist/interpreter/callback.js

@@ -1,5 +1,6 @@
 import { Effect, Exit } from "effect";
 import { coerceToNumber, coerceToString } from "../stdlib/value.js";
+import { primitivePrototype } from "./intrinsics.js";
 import { typeError } from "./model.js";
 import { Callable, get, Native, DateObj, Obj } from "./objects.js";
 import { typeofValue } from "./references.js";
@@ -27,6 +28,13 @@ export const toPrimitive = (ctx, value, hint) => {
         throw typeError("Cannot convert object to primitive value.");
     });
 };
+/** Invoke(value, name): calls the method the value would find through its prototype. */
+export const invoke = (ctx, value, name, label) => {
+    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 = (ctx, value) => Effect.map(toPrimitive(ctx, value, "string"), coerceToString);
 export const toPrimitiveNumber = (ctx, value) => Effect.map(toPrimitive(ctx, value, "number"), coerceToNumber);
 // The single acceptance list for callbacks: collections, sort, string replacers,

package/dist/interpreter/errors.js

@@ -150,6 +150,7 @@ export const errorGlobal = (type, ctx) => {
         methods(builtins, prototype, [
             ["toString", 0, (thisValue) => errorToString(receiver(Obj, thisValue, "Error.prototype.toString"))],
         ]);
+        methods(builtins, ctor, [["isError", 1, (_, args) => args[0] instanceof ErrorObj]]);
     }
     return ctor;
 };

package/dist/interpreter/extensions.js

@@ -5,7 +5,7 @@ import { createErrorValue, isErrorType } from "./intrinsics.js";
 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, keys, Arr, Bytes, DateObj, ErrorObj, GeneratorObj, MapObj, Obj, PromiseObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, } from "./objects.js";
+import { Callable, define, entries, get, has, hidden, keys, Arr, Bytes, DateObj, ErrorObj, GeneratorObj, IteratorObj, MapObj, Obj, PromiseObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, HeadersObj, } from "./objects.js";
 import { describeValue } from "./references.js";
 /**
  * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
@@ -32,6 +32,8 @@ export const extensionGlobals = (ctx, extensions) => {
             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) => toHost(item, label, depth + 1, seen);
         if (value instanceof MapObj)
             return new Map([...value.map].map(([key, item]) => [next(key), next(item)]));
@@ -40,6 +42,7 @@ export const extensionGlobals = (ctx, extensions) => {
         if (!(value instanceof Obj) ||
             value instanceof Callable ||
             value instanceof GeneratorObj ||
+            value instanceof IteratorObj ||
             value instanceof PromiseObj) {
             throw typeError(`${label} contains ${describeValue(value)}, which cannot be passed to an extension.`);
         }
@@ -114,6 +117,8 @@ export const extensionGlobals = (ctx, extensions) => {
             if (value instanceof URLSearchParams) {
                 return new URLSearchParamsObj(builtins.URLSearchParams, new URLSearchParams(value));
             }
+            if (value instanceof Headers)
+                return new HeadersObj(builtins.Headers, new Headers(value));
             if (value instanceof Map) {
                 const wrapped = new MapObj(builtins.Map);
                 for (const [key, item] of value)

package/dist/interpreter/globals.js

@@ -11,6 +11,8 @@ import { objectGlobal } from "../stdlib/object.js";
 import { regexpGlobal } from "../stdlib/regexp.js";
 import { stringGlobal } from "../stdlib/string.js";
 import { uriGlobal, urlGlobal, urlSearchParamsGlobal } from "../stdlib/url.js";
+import { headersGlobal } from "../stdlib/headers.js";
+import { iteratorGlobals } from "../stdlib/iterator.js";
 import { coercion } from "../stdlib/value.js";
 import { base64Global, cryptoGlobal } from "../stdlib/web.js";
 import { ToolReference } from "../tool-runtime.js";
@@ -71,6 +73,7 @@ const table = {
     Set: (ctx) => setGlobal(ctx),
     URL: (ctx) => urlGlobal(ctx),
     URLSearchParams: (ctx) => urlSearchParamsGlobal(ctx),
+    Headers: (ctx) => headersGlobal(ctx),
     Uint8Array: (ctx) => uint8ArrayGlobal(ctx),
     TextEncoder: (ctx) => textEncoderGlobal(ctx),
     TextDecoder: (ctx) => textDecoderGlobal(ctx),
@@ -88,5 +91,6 @@ export const globalNames = new Set(Object.keys(table));
 /** The immutable global bindings of every program, in declaration order. */
 export const globals = (ctx) => {
     generatorGlobals(ctx);
+    iteratorGlobals(ctx);
     return Object.entries(table).map(([name, factory]) => [name, factory(ctx)]);
 };

package/dist/interpreter/interpreter.d.ts

@@ -2,7 +2,7 @@ import type { Program } from "acorn";
 import { Effect } from "effect";
 import { type Json } from "../data.js";
 import { type ToolRuntime } from "../tool-runtime.js";
-import type { Builtins } from "./intrinsics.js";
+import { type Builtins } from "./intrinsics.js";
 import { PromiseObj } from "./objects.js";
 import { Pending } from "./promises.js";
 /** One program execution: the tool bridge, promise scheduler, captured logs, and the global scope built once. */
@@ -23,6 +23,12 @@ export declare class Interpreter<R> {
     call(callable: unknown, thisValue: unknown, args: Array<unknown>): Effect.Effect<unknown, unknown, R>;
     await(promise: PromiseObj): Effect.Effect<unknown, unknown, never>;
     iterate(value: unknown): Effect.Effect<{
+        next: Effect.Effect<{
+            done: boolean;
+            value: any;
+        }, never, never>;
+        close: Effect.Effect<void, never, never>;
+    }, never, never> | Effect.Effect<{
         next: Effect.Effect<{
             done: boolean;
             value: unknown;

package/dist/interpreter/interpreter.js

@@ -4,8 +4,9 @@ import { ToolReference } from "../tool-runtime.js";
 import { AsyncIteratorSymbol, CallSite, GeneratorReturn, IteratorSymbol, OptionalShortCircuit, invalidData, Throw, rangeError, typeError, unsupportedSyntax, } from "./model.js";
 import { checkStringLength } from "./limits.js";
 import { locate, materialize } from "./errors.js";
+import { primitivePrototype } from "./intrinsics.js";
 import { globals } from "./globals.js";
-import { assign, Callable, define, get, has, hasPrototype, keys, Native, parseArrayIndex, Arr, Bytes, DateObj, Fn, GeneratorObj, MapObj, Obj, PromiseObj, SetObj, URLSearchParamsObj, record, remove, set, } from "./objects.js";
+import { assign, Callable, define, get, has, hasPrototype, keys, Native, parseArrayIndex, Arr, Bytes, DateObj, Fn, GeneratorObj, IteratorObj, MapObj, Obj, PromiseObj, SetObj, URLSearchParamsObj, HeadersObj, record, remove, set, } from "./objects.js";
 import { preserveConsumerError } from "./callback.js";
 import { Pending, resolvePromise, resolvePromiseValue } from "./promises.js";
 import { containsOpaqueReference, describeValue, rejectCircularInsertion, typeofValue } from "./references.js";
@@ -27,21 +28,27 @@ const loopExit = (result, labels) => {
         return result;
     return undefined;
 };
-const calleeDescription = (callee) => {
-    if (callee?.type === "Identifier")
-        return callee.name;
-    if (callee?.type === "MemberExpression") {
-        const object = callee.object;
-        const property = callee.property;
-        const key = !callee.computed && property.type === "Identifier"
-            ? property.name
-            : property.type === "Literal" && typeof property.value === "string"
-                ? property.value
-                : undefined;
-        if (object.type === "Identifier" && key !== undefined)
-            return `${object.name}.${key}`;
-    }
-    return "The called value";
+// Native engines name the callee (`search(...).catch is not a function`), including call chains. Returns
+// undefined when a link cannot be named, so a chain is either named completely or not at all.
+const calleeDescription = (node) => {
+    if (node?.type === "Identifier")
+        return node.name;
+    if (node?.type === "CallExpression") {
+        const target = calleeDescription(node.callee);
+        return target === undefined ? undefined : `${target}(...)`;
+    }
+    if (node?.type !== "MemberExpression")
+        return undefined;
+    const property = node.property;
+    const key = !node.computed && property.type === "Identifier"
+        ? property.name
+        : property.type === "Literal" && typeof property.value === "string"
+            ? property.value
+            : undefined;
+    if (key === undefined)
+        return undefined;
+    const object = calleeDescription(node.object);
+    return object === undefined ? undefined : `${object}.${key}`;
 };
 // OrdinaryHasInstance: walk the left operand's chain looking for the constructor's `prototype`.
 const instanceofValue = (lhs, rhs, node) => {
@@ -477,10 +484,10 @@ class Frame {
             if (declared?.lexical)
                 self.predeclarePattern(declared.pattern, declared.mutable, left);
             const right = yield* self.evaluateExpression(node.right);
-            const iterator = yield* self.customIterator(right, node, awaiting);
-            const cursor = iterator === undefined ? yield* self.iterate(right, node) : undefined;
+            const cursor = self.hostCursor(right);
+            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, or URLSearchParams, or custom iterator value.`, node);
+                throw invalidData(`${awaiting ? "for await...of" : "for...of"} requires an array, string, Map, Set, URLSearchParams, or Headers, or custom iterator value.`, node);
             }
             const close = () => iterator
                 ? self.closeIterator(iterator, node, awaiting)
@@ -550,6 +557,18 @@ class Frame {
         });
     }
     iterate(value, node) {
+        const cursor = this.hostCursor(value);
+        if (cursor !== undefined)
+            return Effect.succeed(cursor);
+        const self = this;
+        return Effect.map(this.customIterator(value, node, false), (iterator) => iterator === undefined
+            ? undefined
+            : {
+                next: self.nextIteratorResult(iterator, node, false),
+                close: Effect.suspend(() => self.closeIterator(iterator, node, false)),
+            });
+    }
+    hostCursor(value) {
         const iterator = value instanceof Arr
             ? value.items[Symbol.iterator]()
             : typeof value === "string"
@@ -560,29 +579,26 @@ class Frame {
                         ? value.set.values()
                         : value instanceof URLSearchParamsObj
                             ? value.params.entries()
-                            : value instanceof Bytes
-                                ? value.bytes.values()
-                                : undefined;
-        if (iterator !== undefined) {
-            const proto = this.ctx.builtins.Array;
-            return Effect.succeed({
-                next: Effect.sync(() => {
-                    const step = iterator.next();
-                    return {
-                        done: Boolean(step.done),
-                        value: Array.isArray(step.value) ? new Arr(proto, step.value) : step.value,
-                    };
-                }),
-                close: Effect.void,
-            });
-        }
-        const self = this;
-        return Effect.map(this.customIterator(value, node, false), (iterator) => iterator === undefined
-            ? undefined
-            : {
-                next: self.nextIteratorResult(iterator, node, false),
-                close: Effect.suspend(() => self.closeIterator(iterator, node, false)),
-            });
+                            : value instanceof HeadersObj
+                                ? value.headers.entries()
+                                : value instanceof Bytes
+                                    ? value.bytes.values()
+                                    : value instanceof IteratorObj
+                                        ? value.iterator
+                                        : 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,
+                };
+            }),
+            close: Effect.void,
+        };
     }
     customIterator(value, node, allowAsync = true) {
         if (!(value instanceof Obj))
@@ -1016,7 +1032,7 @@ class Frame {
                 // `new` itself is supported, so a non-constructible callee is a TypeError like JS rather than
                 // unsupported syntax. Built-ins like Number are real constructors in JS, so do not claim
                 // otherwise; say `new` is unsupported for them and point at the plain call.
-                const name = calleeDescription(node.callee);
+                const name = calleeDescription(node.callee) ?? "The called value";
                 const message = callee instanceof Fn
                     ? `${name} cannot be constructed: user-defined constructors and classes are not supported. Call it as a function that returns a plain object instead.`
                     : callee instanceof Native
@@ -1303,7 +1319,7 @@ class Frame {
             if (callable instanceof Native) {
                 return yield* self.native(() => callable.call(thisValue, args), node);
             }
-            throw typeError(`${calleeDescription(callee)} is not a function.`, callee ?? node);
+            throw typeError(`${calleeDescription(callee) ?? "The called value"} is not a function.`, callee ?? node);
         });
     }
     // Built-ins throw without a location, synchronously or inside their Effect; the call site supplies it.
@@ -1513,6 +1529,7 @@ class Frame {
                 value instanceof MapObj ||
                 value instanceof SetObj ||
                 value instanceof URLSearchParamsObj ||
+                value instanceof HeadersObj ||
                 value instanceof Bytes) {
                 const cursor = yield* self.iterate(value, node);
                 if (!cursor)
@@ -1702,20 +1719,17 @@ class Frame {
             }
             if (objectValue instanceof Obj)
                 return { target: objectValue, key, receiver: objectValue };
-            // Primitives read through their wrapper prototype without being boxed; strings own length and indexes.
-            const builtins = self.ctx.builtins;
+            // Strings own length and indexes; every other primitive property reads through the wrapper prototype.
             if (typeof objectValue === "string") {
                 if (key === "length")
                     return { value: objectValue.length };
                 const index = typeof key === "symbol" ? undefined : parseArrayIndex(key);
                 if (index !== undefined)
                     return { value: objectValue[index] };
-                return { target: builtins.String, key, receiver: objectValue };
             }
-            if (typeof objectValue === "number")
-                return { target: builtins.Number, key, receiver: objectValue };
-            if (typeof objectValue === "boolean")
-                return { target: builtins.Boolean, key, receiver: objectValue };
+            const proto = primitivePrototype(self.ctx.builtins, objectValue);
+            if (proto !== undefined)
+                return { target: proto, key, receiver: objectValue };
             if (objectValue === null || objectValue === undefined) {
                 throw typeError(`Cannot read properties of ${objectValue} (reading '${String(key)}').`, objectNode);
             }

package/dist/interpreter/intrinsics.d.ts

@@ -2,12 +2,14 @@ import { ErrorObj, Obj } from "./objects.js";
 export declare const errorTypes: readonly ["Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError", "EvalError", "URIError", "AggregateError"];
 export type ErrorType = (typeof errorTypes)[number];
 export declare const isErrorType: (name: string) => name is ErrorType;
-declare const builtins: readonly ["Object", "Function", "Array", "String", "Number", "Boolean", "Date", "RegExp", "Map", "Set", "URL", "URLSearchParams", "Uint8Array", "TextEncoder", "TextDecoder", "Promise", "Iterator", "AsyncIterator", "Generator", "AsyncGenerator"];
+declare const builtins: readonly ["Object", "Function", "Array", "String", "Number", "Boolean", "Date", "RegExp", "Map", "Set", "URL", "URLSearchParams", "Headers", "Uint8Array", "TextEncoder", "TextDecoder", "Promise", "Iterator", "AsyncIterator", "Generator", "AsyncGenerator"];
 /**
  * The built-in prototype objects of one runtime, allocated empty in dependency order. The globals populate them
  * and attach their constructors when the runtime is built.
  */
 export type Builtins = Readonly<Record<(typeof builtins)[number] | ErrorType, Obj>>;
 export declare const createErrorValue: (prototype: Obj, message: string | undefined) => ErrorObj;
+/** The prototype a primitive reads its methods from without being boxed; none for null, undefined, and symbols. */
+export declare const primitivePrototype: (builtins: Builtins, value: unknown) => Obj | undefined;
 export declare const createBuiltins: () => Builtins;
 export {};

package/dist/interpreter/intrinsics.js

@@ -24,6 +24,7 @@ const builtins = [
     "Set",
     "URL",
     "URLSearchParams",
+    "Headers",
     "Uint8Array",
     "TextEncoder",
     "TextDecoder",
@@ -39,6 +40,16 @@ export const createErrorValue = (prototype, message) => {
         define(value, "message", message, hidden);
     return value;
 };
+/** The prototype a primitive reads its methods from without being boxed; none for null, undefined, and symbols. */
+export const primitivePrototype = (builtins, value) => {
+    if (typeof value === "string")
+        return builtins.String;
+    if (typeof value === "number")
+        return builtins.Number;
+    if (typeof value === "boolean")
+        return builtins.Boolean;
+    return undefined;
+};
 export const createBuiltins = () => {
     const object = new Obj(null);
     // Function.prototype is itself callable and returns undefined.
@@ -68,6 +79,7 @@ export const createBuiltins = () => {
         Set: plain(),
         URL: plain(),
         URLSearchParams: plain(),
+        Headers: plain(),
         Uint8Array: plain(),
         TextEncoder: plain(),
         TextDecoder: plain(),

package/dist/interpreter/model.js

@@ -52,9 +52,10 @@ export const uriError = failure("URIError");
 export const supportedSyntaxMessage = "This is a restricted JavaScript-like language. Supported: plain and async functions, data literals, destructuring, standard control flow, await and Promise, and built-ins such as Array, Object, Math, JSON, Date, RegExp, Map, Set, and URL. Unsupported: classes, this, getters/setters, tagged templates, BigInt, and custom Symbols. Use plain functions and data objects instead.";
 export const unsupportedSyntax = (kind, node) => new PendingThrow("SyntaxError", `Syntax '${kind}' is not supported. ${supportedSyntaxMessage}`, node, "UnsupportedSyntax", [supportedSyntaxMessage]);
 export const isRecord = (value) => 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) => ({
-    line: Math.max(1, (node.loc?.start.line ?? 2) - 1),
-    column: Math.max(1, (node.loc?.start.column ?? 4) - 3),
+    line: node.loc?.start.line ?? 1,
+    column: (node.loc?.start.column ?? 0) + 1,
 });
 export const formatLocation = (node) => {
     if (!node?.loc)

package/dist/interpreter/objects.d.ts

@@ -81,6 +81,11 @@ export declare class GeneratorObj extends Obj {
     readonly request: (kind: GeneratorRequestKind, value: unknown) => Effect.Effect<unknown, unknown, unknown>;
     constructor(proto: Obj, asynchronous: boolean, request: (kind: GeneratorRequestKind, value: unknown) => Effect.Effect<unknown, unknown, unknown>);
 }
+/** A built-in collection iterator: live over the host collection, yielding program values. */
+export declare class IteratorObj extends Obj {
+    readonly iterator: IteratorObject<unknown>;
+    constructor(proto: Obj, iterator: IteratorObject<unknown>);
+}
 export declare class DateObj extends Obj {
     time: number;
     constructor(proto: Obj, time: number);
@@ -99,6 +104,10 @@ export declare class URLSearchParamsObj extends Obj {
     readonly params: URLSearchParams;
     constructor(proto: Obj, params: URLSearchParams);
 }
+export declare class HeadersObj extends Obj {
+    readonly headers: Headers;
+    constructor(proto: Obj, headers: Headers);
+}
 export declare class URLObj extends Obj {
     readonly url: URL;
     readonly searchParams: URLSearchParamsObj;
@@ -110,7 +119,7 @@ export declare class Bytes extends Obj {
     constructor(proto: Obj, bytes: Uint8Array);
 }
 /** Built-in objects that wrap a host value; data-like, but never plain data. */
-export declare const isWrapper: (value: unknown) => value is DateObj | RegExpObj | MapObj | SetObj | URLObj | URLSearchParamsObj | Bytes;
+export declare const isWrapper: (value: unknown) => value is DateObj | RegExpObj | MapObj | SetObj | URLObj | URLSearchParamsObj | HeadersObj | Bytes;
 export declare const parseArrayIndex: (key: string | number) => number | undefined;
 /** The own property under `key`, including an array's live indexes and `length`. */
 export declare const own: (target: Obj, key: PropertyKey) => Slot | undefined;

package/dist/interpreter/objects.js

@@ -78,6 +78,14 @@ export class GeneratorObj extends Obj {
         this.request = request;
     }
 }
+/** A built-in collection iterator: live over the host collection, yielding program values. */
+export class IteratorObj extends Obj {
+    iterator;
+    constructor(proto, iterator) {
+        super(proto);
+        this.iterator = iterator;
+    }
+}
 export class DateObj extends Obj {
     time;
     constructor(proto, time) {
@@ -105,6 +113,13 @@ export class URLSearchParamsObj extends Obj {
         this.params = params;
     }
 }
+export class HeadersObj extends Obj {
+    headers;
+    constructor(proto, headers) {
+        super(proto);
+        this.headers = headers;
+    }
+}
 export class URLObj extends Obj {
     url;
     searchParams;
@@ -129,6 +144,7 @@ export const isWrapper = (value) => value instanceof DateObj ||
     value instanceof SetObj ||
     value instanceof URLObj ||
     value instanceof URLSearchParamsObj ||
+    value instanceof HeadersObj ||
     value instanceof Bytes;
 const MAX_ARRAY_INDEX = 4_294_967_295;
 export const parseArrayIndex = (key) => {

package/dist/interpreter/references.js

@@ -1,9 +1,10 @@
 import { ToolReference } from "../tool-runtime.js";
 import { invalidData } from "./model.js";
-import { Callable, getOwn, isWrapper, ownKeys, Arr, Bytes, DateObj, GeneratorObj, MapObj, Obj, PromiseObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, } from "./objects.js";
+import { Callable, getOwn, isWrapper, ownKeys, Arr, Bytes, DateObj, GeneratorObj, IteratorObj, MapObj, Obj, PromiseObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, HeadersObj, } from "./objects.js";
 /** Values that cannot cross the data boundary. */
 export const isRuntimeReference = (value) => value instanceof Callable ||
     value instanceof GeneratorObj ||
+    value instanceof IteratorObj ||
     value instanceof ToolReference ||
     value instanceof PromiseObj ||
     isWrapper(value);
@@ -63,10 +64,14 @@ export const describeValue = (value) => {
         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")

package/dist/stdlib/array.js

@@ -1,10 +1,10 @@
 import { Effect } from "effect";
 import { constructor, methods, prototypeFrom, receiver } from "../interpreter/native.js";
 import { checkArrayLength, checkStringLength, MAX_ARRAY_LENGTH } from "../interpreter/limits.js";
-import { invalidData, rangeError, typeError } from "../interpreter/model.js";
-import { get, Arr, GeneratorObj, Obj } from "../interpreter/objects.js";
+import { invalidData, IteratorSymbol, rangeError, typeError } from "../interpreter/model.js";
+import { define, get, hidden, Arr, GeneratorObj, IteratorObj, Obj } from "../interpreter/objects.js";
 import { describeValue, rejectCircularInsertion } from "../interpreter/references.js";
-import { applyCollectionCallback, preserveConsumerError } from "../interpreter/callback.js";
+import { applyCollectionCallback, invoke, preserveConsumerError } from "../interpreter/callback.js";
 import { compareText } from "../tool-runtime.js";
 import { coerceToNumber, coerceToString } from "./value.js";
 const arrayLikeSource = (source) => {
@@ -317,12 +317,21 @@ export const arrayGlobal = (ctx) => {
                 return target;
             },
         ],
-        ["keys", 0, (thisValue) => wrap(Array.from(self(thisValue, "keys").items.keys()))],
-        ["values", 0, (thisValue) => wrap([...self(thisValue, "values").items])],
+        [
+            "toLocaleString",
+            0,
+            (thisValue) => Effect.map(Effect.forEach(self(thisValue, "toLocaleString").items, (item) => item === null || item === undefined
+                ? Effect.succeed("")
+                : Effect.map(invoke(ctx, item, "toLocaleString", "Array.prototype.toLocaleString"), coerceToString)), (parts) => parts.join(",")),
+        ],
+        ["keys", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "keys").items.keys())],
+        ["values", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "values").items.values())],
         [
             "entries",
             0,
-            (thisValue) => wrap(Array.from(self(thisValue, "entries").items.entries(), ([index, item]) => wrap([index, item]))),
+            (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "entries")
+                .items.entries()
+                .map(([index, item]) => wrap([index, item]))),
         ],
         iterate("map", 1, (target, receiver, apply) => Effect.gen(function* () {
             const length = target.length;
@@ -461,5 +470,6 @@ export const arrayGlobal = (ctx) => {
             return accumulator;
         })),
     ]);
+    define(proto, IteratorSymbol, get(proto, "values"), hidden);
     return array;
 };

package/dist/stdlib/bytes.js

@@ -1,8 +1,8 @@
 import { Effect } from "effect";
 import { checkArrayLength, checkStringLength } from "../interpreter/limits.js";
 import { constructor, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js";
-import { rangeError, syntaxError, typeError } from "../interpreter/model.js";
-import { defineAccessor, get, Arr, Bytes, Obj } from "../interpreter/objects.js";
+import { IteratorSymbol, rangeError, syntaxError, typeError } from "../interpreter/model.js";
+import { define, defineAccessor, get, hidden, Arr, Bytes, IteratorObj, Obj } from "../interpreter/objects.js";
 import { describeValue } from "../interpreter/references.js";
 import { coerceToNumber, coerceToString } from "./value.js";
 /** The bytes a Uint8Array, array, or other iterable of numbers describes; the host array clamps each value. */
@@ -152,14 +152,17 @@ export const uint8ArrayGlobal = (ctx) => {
         ["toString", 0, (thisValue) => self(thisValue, "toString").bytes.join(",")],
         ["toBase64", 0, (thisValue) => self(thisValue, "toBase64").bytes.toBase64()],
         ["toHex", 0, (thisValue) => self(thisValue, "toHex").bytes.toHex()],
-        ["keys", 0, (thisValue) => wrapAll(Array.from(self(thisValue, "keys").bytes.keys()))],
-        ["values", 0, (thisValue) => wrapAll(Array.from(self(thisValue, "values").bytes.values()))],
+        ["keys", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "keys").bytes.keys())],
+        ["values", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "values").bytes.values())],
         [
             "entries",
             0,
-            (thisValue) => wrapAll(Array.from(self(thisValue, "entries").bytes.entries(), ([index, byte]) => wrapAll([index, byte]))),
+            (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "entries")
+                .bytes.entries()
+                .map(([index, byte]) => wrapAll([index, byte]))),
         ],
     ]);
+    define(proto, IteratorSymbol, get(proto, "values"), hidden);
     return uint8Array;
 };
 export const textEncoderGlobal = (ctx) => {

package/dist/stdlib/collections.js

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 import { constructor, fn, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js";
-import { invalidData, typeError } from "../interpreter/model.js";
-import { define, defineAccessor, get, getOwn, hidden, isWrapper, Arr, MapObj, Obj, PromiseObj, SetObj, } from "../interpreter/objects.js";
+import { invalidData, IteratorSymbol, typeError } from "../interpreter/model.js";
+import { define, defineAccessor, get, getOwn, hidden, isWrapper, Arr, IteratorObj, MapObj, Obj, PromiseObj, SetObj, } from "../interpreter/objects.js";
 import { describeValue, isRuntimeReference } from "../interpreter/references.js";
 import { applyCollectionCallback, isSupportedCallback, preserveConsumerError, toPrimitiveNumber, toPrimitiveString, } from "../interpreter/callback.js";
 const coerceGroupByPropertyKey = (ctx, value) => {
@@ -123,6 +123,31 @@ export const mapGlobal = (ctx) => {
                 return target;
             },
         ],
+        [
+            "getOrInsert",
+            2,
+            (thisValue, args) => {
+                const target = self(thisValue, "getOrInsert").map;
+                if (!target.has(args[0]))
+                    target.set(args[0], args[1]);
+                return target.get(args[0]);
+            },
+        ],
+        [
+            "getOrInsertComputed",
+            2,
+            (thisValue, args) => {
+                const target = self(thisValue, "getOrInsertComputed").map;
+                const apply = applyCollectionCallback(ctx, args[1], "Map.getOrInsertComputed");
+                if (target.has(args[0]))
+                    return target.get(args[0]);
+                // The callback sees the stored key (-0 is +0) and its result wins over anything it inserted itself.
+                return Effect.map(apply([args[0] === 0 ? 0 : args[0]]), (value) => {
+                    target.set(args[0], value);
+                    return value;
+                });
+            },
+        ],
         ["delete", 1, (thisValue, args) => self(thisValue, "delete").map.delete(args[0])],
         [
             "clear",
@@ -132,12 +157,14 @@ export const mapGlobal = (ctx) => {
                 return undefined;
             },
         ],
-        ["keys", 0, (thisValue) => wrap(Array.from(self(thisValue, "keys").map.keys()))],
-        ["values", 0, (thisValue) => wrap(Array.from(self(thisValue, "values").map.values()))],
+        ["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) => wrap(Array.from(self(thisValue, "entries").map.entries(), ([key, item]) => wrap([key, item]))),
+            (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "entries")
+                .map.entries()
+                .map(([key, item]) => wrap([key, item]))),
         ],
         [
             "forEach",
@@ -153,6 +180,7 @@ export const mapGlobal = (ctx) => {
             },
         ],
     ]);
+    define(proto, IteratorSymbol, get(proto, "entries"), hidden);
     return map;
 };
 const loadSetRecord = (ctx, source, name) => {
@@ -187,6 +215,8 @@ const loadSetRecord = (ctx, source, name) => {
             size: Math.max(Math.trunc(size), 0),
             has: (item) => Effect.map(ctx.call(has, source, [item]), Boolean),
             keys: () => Effect.flatMap(ctx.call(keys, source, []), (result) => {
+                if (result instanceof IteratorObj)
+                    return Effect.succeed(result.iterator);
                 if (result instanceof Arr)
                     return Effect.succeed(result.items);
                 throw typeError(`Set.${name} expected 'keys' to return an iterator.`);
@@ -313,12 +343,14 @@ export const setGlobal = (ctx) => {
                 return undefined;
             },
         ],
-        ["keys", 0, (thisValue) => wrap(Array.from(self(thisValue, "keys").set.values()))],
-        ["values", 0, (thisValue) => wrap(Array.from(self(thisValue, "values").set.values()))],
+        ["keys", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "keys").set.values())],
+        ["values", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "values").set.values())],
         [
             "entries",
             0,
-            (thisValue) => wrap(Array.from(self(thisValue, "entries").set.values(), (item) => wrap([item, item]))),
+            (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "entries")
+                .set.values()
+                .map((item) => wrap([item, item]))),
         ],
         [
             "forEach",
@@ -341,5 +373,6 @@ export const setGlobal = (ctx) => {
         operation("isSupersetOf"),
         operation("isDisjointFrom"),
     ]);
+    define(proto, IteratorSymbol, get(proto, "values"), hidden);
     return set;
 };

package/dist/stdlib/console.js

@@ -1,5 +1,5 @@
 import { methods } from "../interpreter/native.js";
-import { entries, get, Arr, Bytes, DateObj, MapObj, Obj, PromiseObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, } from "../interpreter/objects.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 { coerceToString } from "./value.js";
 const consoleMethods = ["log", "info", "debug", "warn", "error", "dir", "table"];
@@ -53,6 +53,8 @@ const formatConsoleValue = (value, seen, depth) => {
         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 (depth > MAX_CONSOLE_DEPTH)

package/dist/stdlib/date.js

@@ -92,6 +92,11 @@ export const dateGlobal = (ctx) => {
         ["toTimeString", 0, (thisValue) => new Date(self(thisValue, "toTimeString").time).toTimeString()],
         ["toUTCString", 0, (thisValue) => new Date(self(thisValue, "toUTCString").time).toUTCString()],
         ["toGMTString", 0, (thisValue) => new Date(self(thisValue, "toGMTString").time).toUTCString()],
+        ...["toLocaleString", "toLocaleDateString", "toLocaleTimeString"].map((name) => [
+            name,
+            0,
+            (thisValue) => new Date(self(thisValue, name).time)[name]("en-US", { timeZone: "UTC" }),
+        ]),
         ...getters.map((name) => [name, 0, (thisValue) => new Date(self(thisValue, name).time)[name]()]),
         ...setters.map(([name, length]) => [
             name,

package/dist/stdlib/headers.d.ts

@@ -0,0 +1,2 @@
+import type { Interpreter } from "../interpreter/interpreter.js";
+export declare const headersGlobal: <R>(ctx: Interpreter<R>) => import("../interpreter/objects.js").Native<R>;

package/dist/stdlib/headers.js

@@ -0,0 +1,127 @@
+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 { applyCollectionCallback } from "../interpreter/callback.js";
+import { isRuntimeReference } from "../interpreter/references.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.
+const attempt = (run) => {
+    try {
+        return run();
+    }
+    catch (error) {
+        throw typeError(error instanceof Error ? error.message : String(error));
+    }
+};
+const constructHeaders = (ctx, init, proto) => {
+    const wrap = (headers) => new HeadersObj(proto, headers);
+    if (init === undefined)
+        return Effect.succeed(wrap(new Headers()));
+    return Effect.gen(function* () {
+        const pairs = init instanceof Obj ? yield* readPairs(ctx, init, "new Headers(...)") : undefined;
+        if (pairs !== undefined)
+            return wrap(attempt(() => new Headers(pairs)));
+        if (!(init instanceof Obj) || isRuntimeReference(init)) {
+            throw typeError("new Headers(...) expects a record of names to values, iterable [name, value] pairs, or Headers.");
+        }
+        return wrap(attempt(() => new Headers(Object.fromEntries(entries(init).map(([key, value]) => [key, coerceToString(value)])))));
+    });
+};
+export const headersGlobal = (ctx) => {
+    const builtins = ctx.builtins;
+    const proto = builtins.Headers;
+    const headers = constructor(builtins, proto, {
+        name: "Headers",
+        call: requiresNew("Headers"),
+        construct: (args, newTarget) => constructHeaders(ctx, args[0], prototypeFrom(newTarget, proto)),
+    });
+    const self = (thisValue, name) => receiver(HeadersObj, thisValue, `Headers.prototype.${name}`);
+    const wrap = (items) => new Arr(builtins.Array, items);
+    const arg = (args, index) => coerceToString(args[index]);
+    const requireArgs = (name, args, count) => {
+        if (args.length < count)
+            throw typeError(`Headers.${name} requires ${count} argument${count === 1 ? "" : "s"}.`);
+    };
+    methods(builtins, proto, [
+        [
+            "append",
+            2,
+            (thisValue, args) => {
+                requireArgs("append", args, 2);
+                const target = self(thisValue, "append").headers;
+                return attempt(() => target.append(arg(args, 0), arg(args, 1)));
+            },
+        ],
+        [
+            "delete",
+            1,
+            (thisValue, args) => {
+                requireArgs("delete", args, 1);
+                const target = self(thisValue, "delete").headers;
+                return attempt(() => target.delete(arg(args, 0)));
+            },
+        ],
+        [
+            "get",
+            1,
+            (thisValue, args) => {
+                requireArgs("get", args, 1);
+                const target = self(thisValue, "get").headers;
+                return attempt(() => target.get(arg(args, 0)));
+            },
+        ],
+        ["getSetCookie", 0, (thisValue) => wrap(self(thisValue, "getSetCookie").headers.getSetCookie())],
+        [
+            "has",
+            1,
+            (thisValue, args) => {
+                requireArgs("has", args, 1);
+                const target = self(thisValue, "has").headers;
+                return attempt(() => target.has(arg(args, 0)));
+            },
+        ],
+        [
+            "set",
+            2,
+            (thisValue, args) => {
+                requireArgs("set", args, 2);
+                const target = self(thisValue, "set").headers;
+                return attempt(() => target.set(arg(args, 0), arg(args, 1)));
+            },
+        ],
+        // Iterator.from because Bun's Headers typings predate iterator helpers; the runtime iterators already have them.
+        [
+            "keys",
+            0,
+            (thisValue) => new IteratorObj(builtins.Iterator, Iterator.from(self(thisValue, "keys").headers.keys())),
+        ],
+        [
+            "values",
+            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]))),
+        ],
+        [
+            "forEach",
+            1,
+            (thisValue, args) => {
+                requireArgs("forEach", args, 1);
+                const target = self(thisValue, "forEach");
+                const apply = applyCollectionCallback(ctx, args[0], "Headers.forEach");
+                return Effect.gen(function* () {
+                    for (const [key, value] of Array.from(target.headers.entries()))
+                        yield* apply([value, key, target]);
+                    return undefined;
+                });
+            },
+        ],
+    ]);
+    define(proto, IteratorSymbol, get(proto, "entries"), hidden);
+    return headers;
+};

package/dist/stdlib/iterator.d.ts

@@ -0,0 +1,2 @@
+import type { Interpreter } from "../interpreter/interpreter.js";
+export declare const iteratorGlobals: <R>(ctx: Interpreter<R>) => void;

package/dist/stdlib/iterator.js

@@ -0,0 +1,17 @@
+import { methods, receiver } from "../interpreter/native.js";
+import { IteratorObj, record } from "../interpreter/objects.js";
+// Every built-in collection iterator shares the Iterator prototype; JS gives each collection its own, which is only
+// observable through getPrototypeOf.
+export const iteratorGlobals = (ctx) => {
+    const builtins = ctx.builtins;
+    methods(builtins, builtins.Iterator, [
+        [
+            "next",
+            0,
+            (thisValue) => {
+                const step = receiver(IteratorObj, thisValue, "Iterator.prototype.next").iterator.next();
+                return record(builtins.Object, { value: step.value, done: Boolean(step.done) });
+            },
+        ],
+    ]);
+};

package/dist/stdlib/number.js

@@ -50,6 +50,7 @@ export const numberGlobal = (ctx) => {
     };
     methods(builtins, builtins.Number, [
         ["toFixed", 1, (thisValue, args) => self(thisValue, "toFixed").toFixed(optNum("toFixed", args[0]))],
+        ["toLocaleString", 0, (thisValue) => self(thisValue, "toLocaleString").toLocaleString("en-US")],
         [
             "toExponential",
             1,

package/dist/stdlib/object.js

@@ -3,7 +3,7 @@ import { constructor, methods, receiver } from "../interpreter/native.js";
 import { AsyncIteratorSymbol, invalidData, IteratorSymbol, rangeError, typeError, } from "../interpreter/model.js";
 import { Callable, define, entries, enumerableKeys, getOwn, hasOwn, hasPrototype, hidden, keys, own, Arr, Bytes, DateObj, ErrorObj, Obj, PromiseObj, RegExpObj, set, } from "../interpreter/objects.js";
 import { containsOpaqueReference, describeValue, rejectCircularInsertion } from "../interpreter/references.js";
-import { preserveConsumerError } from "../interpreter/callback.js";
+import { invoke, preserveConsumerError } from "../interpreter/callback.js";
 import { ToolReference } from "../tool-runtime.js";
 import { groupBy } from "./collections.js";
 import { coerceToString } from "./value.js";
@@ -161,7 +161,7 @@ export const objectGlobal = (ctx) => {
                 true,
         ],
         ["toString", 0, (thisValue) => `[object ${classTag(thisValue)}]`],
-        ["toLocaleString", 0, (thisValue) => `[object ${classTag(thisValue)}]`],
+        ["toLocaleString", 0, (thisValue) => invoke(ctx, thisValue, "toString", "Object.prototype.toLocaleString")],
         [
             "valueOf",
             0,

package/dist/stdlib/string.js

@@ -1,8 +1,8 @@
 import { Effect } from "effect";
-import { constructor, methods } from "../interpreter/native.js";
+import { constructor, fn, methods } from "../interpreter/native.js";
 import { checkArrayLength, checkStringLength } from "../interpreter/limits.js";
-import { invalidData, rangeError, typeError } from "../interpreter/model.js";
-import { Arr, PromiseObj, RegExpObj, record } from "../interpreter/objects.js";
+import { invalidData, IteratorSymbol, rangeError, typeError } from "../interpreter/model.js";
+import { define, hidden, Arr, IteratorObj, PromiseObj, RegExpObj, record } from "../interpreter/objects.js";
 import { containsOpaqueReference, typeofValue } from "../interpreter/references.js";
 import { applyCollectionCallback, isSupportedCallback } from "../interpreter/callback.js";
 import { matchToValue, toHostRegex } from "./regexp.js";
@@ -130,6 +130,8 @@ export const stringGlobal = (ctx) => {
         simple("valueOf", 0, (value) => value),
         simple("toLowerCase", 0, (value) => value.toLowerCase()),
         simple("toUpperCase", 0, (value) => value.toUpperCase()),
+        simple("toLocaleLowerCase", 0, (value) => value.toLowerCase()),
+        simple("toLocaleUpperCase", 0, (value) => value.toUpperCase()),
         simple("trim", 0, (value) => value.trim()),
         simple("trimStart", 0, (value) => value.trimStart()),
         simple("trimLeft", 0, (value) => value.trimStart()),
@@ -232,5 +234,6 @@ export const stringGlobal = (ctx) => {
             return joined;
         }),
     ]);
+    define(builtins.String, IteratorSymbol, fn(builtins, "[Symbol.iterator]", 0, (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "[Symbol.iterator]")[Symbol.iterator]())), hidden);
     return string;
 };

package/dist/stdlib/url.d.ts

@@ -1,6 +1,12 @@
+import { Effect } from "effect";
 import type { Interpreter } from "../interpreter/interpreter.js";
 type UriFunction = "encodeURI" | "encodeURIComponent" | "decodeURI" | "decodeURIComponent";
 export declare const uriGlobal: <R>(ctx: Interpreter<R>, name: UriFunction) => import("../interpreter/objects.js").Native<R>;
 export declare const urlGlobal: <R>(ctx: Interpreter<R>) => import("../interpreter/objects.js").Native<R>;
+/**
+ * Reads a synchronous iterable of `[name, value]` pairs as strings; `undefined` when `init` is not iterable. As in
+ * WebIDL, the whole sequence is converted before any pair's length is checked.
+ */
+export declare const readPairs: <R>(ctx: Interpreter<R>, init: unknown, label: string) => Effect.Effect<Array<[string, string]> | undefined, unknown, R>;
 export declare const urlSearchParamsGlobal: <R>(ctx: Interpreter<R>) => import("../interpreter/objects.js").Native<R>;
 export {};

package/dist/stdlib/url.js

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 import { constructor, fn, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js";
-import { PendingThrow, typeError, uriError } from "../interpreter/model.js";
-import { defineAccessor, entries, isWrapper, Arr, Obj, URLObj, URLSearchParamsObj } from "../interpreter/objects.js";
+import { IteratorSymbol, PendingThrow, typeError, uriError } from "../interpreter/model.js";
+import { define, defineAccessor, entries, get, hidden, isWrapper, Arr, IteratorObj, Obj, URLObj, URLSearchParamsObj, } from "../interpreter/objects.js";
 import { isRuntimeReference } from "../interpreter/references.js";
 import { applyCollectionCallback, preserveConsumerError } from "../interpreter/callback.js";
 import { coerceToString } from "./value.js";
@@ -98,11 +98,10 @@ export const urlGlobal = (ctx) => {
     ]);
     return url;
 };
-const readPair = (ctx, value) => Effect.gen(function* () {
+const readPair = (ctx, value, label) => Effect.gen(function* () {
     const cursor = yield* ctx.iterate(value);
-    if (cursor === undefined) {
-        throw typeError("new URLSearchParams(...) expects iterable [name, value] pairs.");
-    }
+    if (cursor === undefined)
+        throw typeError(`${label} expects iterable [name, value] pairs.`);
     const items = [];
     while (true) {
         const step = yield* cursor.next;
@@ -111,6 +110,25 @@ const readPair = (ctx, value) => Effect.gen(function* () {
         items.push(yield* preserveConsumerError(cursor, Effect.sync(() => coerceToString(step.value))));
     }
 });
+/**
+ * Reads a synchronous iterable of `[name, value]` pairs as strings; `undefined` when `init` is not iterable. As in
+ * WebIDL, the whole sequence is converted before any pair's length is checked.
+ */
+export const readPairs = (ctx, init, label) => Effect.gen(function* () {
+    const cursor = yield* ctx.iterate(init);
+    if (cursor === undefined)
+        return undefined;
+    const pairs = [];
+    while (true) {
+        const step = yield* cursor.next;
+        if (step.done) {
+            if (pairs.some((entry) => entry.length !== 2))
+                throw typeError(`${label} expects iterable [name, value] pairs.`);
+            return pairs;
+        }
+        pairs.push(yield* preserveConsumerError(cursor, readPair(ctx, step.value, label)));
+    }
+});
 const constructURLSearchParams = (ctx, init, proto) => {
     const wrap = (params) => new URLSearchParamsObj(proto, params);
     if (init === undefined)
@@ -123,20 +141,9 @@ const constructURLSearchParams = (ctx, init, proto) => {
         return Effect.succeed(wrap(new URLSearchParams(coerceToString(init))));
     }
     return Effect.gen(function* () {
-        const cursor = yield* ctx.iterate(init);
-        if (cursor !== undefined) {
-            const pairs = [];
-            while (true) {
-                const step = yield* cursor.next;
-                if (step.done) {
-                    if (pairs.some((entry) => entry.length !== 2)) {
-                        throw typeError("new URLSearchParams(...) expects iterable [name, value] pairs.");
-                    }
-                    return wrap(new URLSearchParams(pairs.map((entry) => [entry[0] ?? "", entry[1] ?? ""])));
-                }
-                pairs.push(yield* preserveConsumerError(cursor, readPair(ctx, step.value)));
-            }
-        }
+        const pairs = yield* readPairs(ctx, init, "new URLSearchParams(...)");
+        if (pairs !== undefined)
+            return wrap(new URLSearchParams(pairs));
         if (isRuntimeReference(init)) {
             throw typeError("new URLSearchParams(...) expects a query string, data object, or synchronous iterable pairs.");
         }
@@ -230,12 +237,14 @@ export const urlSearchParamsGlobal = (ctx) => {
                 return undefined;
             },
         ],
-        ["keys", 0, (thisValue) => wrap(Array.from(self(thisValue, "keys").params.keys()))],
-        ["values", 0, (thisValue) => wrap(Array.from(self(thisValue, "values").params.values()))],
+        ["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) => wrap(Array.from(self(thisValue, "entries").params.entries(), ([key, value]) => wrap([key, value]))),
+            (thisValue) => new IteratorObj(builtins.Iterator, self(thisValue, "entries")
+                .params.entries()
+                .map(([key, value]) => wrap([key, value]))),
         ],
         ["toString", 0, (thisValue) => self(thisValue, "toString").params.toString()],
         [
@@ -253,5 +262,6 @@ export const urlSearchParamsGlobal = (ctx) => {
             },
         ],
     ]);
+    define(proto, IteratorSymbol, get(proto, "entries"), hidden);
     return searchParams;
 };

package/dist/stdlib/value.js

@@ -1,6 +1,6 @@
 import { fn } from "../interpreter/native.js";
 import { typeError } from "../interpreter/model.js";
-import { get, isWrapper, Arr, Bytes, DateObj, ErrorObj, MapObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, } from "../interpreter/objects.js";
+import { get, isWrapper, Arr, Bytes, DateObj, ErrorObj, MapObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, HeadersObj, } from "../interpreter/objects.js";
 export const compoundOperators = new Set(["+=", "-=", "*=", "/=", "%=", "**=", "&=", "|=", "^=", "<<=", ">>=", ">>>="]);
 /** The built-in string form of a value, without consulting program-defined `toString` methods. */
 export const coerceToString = (value) => {
@@ -20,6 +20,8 @@ export const coerceToString = (value) => {
         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) {

package/dist/tool-runtime.d.ts

@@ -66,6 +66,8 @@ export type Prepared<R = never> = {
 };
 export type SearchEntry = {
     readonly description: ToolDescription;
+    /** The path split into words, so `zones` matches `get_zones` as a word rather than as a substring of `timezones`. */
+    readonly pathWords: ReadonlyArray<string>;
     readonly searchText: string;
 };
 /** Exact callable signature of the built-in `search` function, for host-owned instructions. */

package/dist/tool-runtime.js

@@ -136,6 +136,7 @@ const makeSearchTool = (searchIndex) => ({
                 const description = entry.description.description.toLowerCase();
                 const score = terms.reduce((total, forms) => total +
                     (forms.some((form) => path === form || path.endsWith(`.${form}`)) ? 20 : 0) +
+                    (forms.some((form) => entry.pathWords.includes(form)) ? 12 : 0) +
                     (forms.some((form) => path.includes(form)) ? 8 : 0) +
                     (forms.some((form) => description.includes(form)) ? 4 : 0) +
                     (forms.some((form) => entry.searchText.includes(form)) ? 2 : 0), 0);
@@ -163,6 +164,7 @@ export const searchSignature = (() => {
 })();
 const toSearchEntry = (visible) => ({
     description: describeTool(visible),
+    pathWords: tokenize(visible.path),
     searchText: [
         visible.path,
         visible.tool.description,

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@opencode/codemode",
-  "version": "2.0.10",
+  "version": "2.0.12",
   "description": "Effect-native confined code execution over schema-described tools",
   "type": "module",
   "license": "MIT",