@opencode/codemode 2.0.10 → 2.0.11

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

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

@@ -5,7 +5,7 @@ import { AsyncIteratorSymbol, CallSite, GeneratorReturn, IteratorSymbol, Optiona
 import { checkStringLength } from "./limits.js";
 import { locate, materialize } from "./errors.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";
@@ -477,10 +477,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 +550,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 +572,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))
@@ -1513,6 +1522,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)

package/dist/interpreter/intrinsics.d.ts

@@ -2,7 +2,7 @@ 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.

package/dist/interpreter/intrinsics.js

@@ -24,6 +24,7 @@ const builtins = [
     "Set",
     "URL",
     "URLSearchParams",
+    "Headers",
     "Uint8Array",
     "TextEncoder",
     "TextDecoder",
@@ -68,6 +69,7 @@ export const createBuiltins = () => {
         Set: plain(),
         URL: plain(),
         URLSearchParams: plain(),
+        Headers: plain(),
         Uint8Array: plain(),
         TextEncoder: plain(),
         TextDecoder: plain(),

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,8 +1,8 @@
 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 { compareText } from "../tool-runtime.js";
@@ -317,12 +317,14 @@ 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])],
+        ["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 +463,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) => {
@@ -132,12 +132,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 +155,7 @@ export const mapGlobal = (ctx) => {
             },
         ],
     ]);
+    define(proto, IteratorSymbol, get(proto, "entries"), hidden);
     return map;
 };
 const loadSetRecord = (ctx, source, name) => {
@@ -187,6 +190,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 +318,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 +348,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/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/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";
@@ -232,5 +232,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/package.json

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