feat(codemode): add the Headers built-in

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

packages/codemode/interpreter-support.md

@@ -29,7 +29,7 @@ ultimate source of truth. Upstream test262 files run verbatim from `test/test262
       Uint8Array is rejected with a hint to encode as text, and own `__proto__` keys are dropped so merging tool
       inputs or results cannot replace a prototype. In-program `JSON.stringify` keeps JS behavior except for the
       Error form and a promise, which is a `TypeError` with an await hint rather than a silent `{}`.
-- [x] Live Date, RegExp, Map, Set, URL, URLSearchParams, and Uint8Array values inside CodeMode.
+- [x] Live Date, RegExp, Map, Set, URL, URLSearchParams, Headers, and Uint8Array values inside CodeMode.
 - [x] Tool calls through the host-provided `tools` tree only.
 - [x] The global `search(...)` built-in: synchronous tool discovery that counts as an admitted tool call and is
       shadowable by program declarations like other globals.
@@ -47,8 +47,8 @@ ultimate source of truth. Upstream test262 files run verbatim from `test/test262
 ## Values and literals
 
 - [x] `null`, `undefined`, booleans, finite and non-finite numbers, and strings.
-- [x] Array literals, including holes and spread from arrays, strings, Maps, Sets, URLSearchParams, custom synchronous
-      iterators, and synchronous generators.
+- [x] Array literals, including holes and spread from arrays, strings, Maps, Sets, URLSearchParams, Headers, custom
+      synchronous iterators, and synchronous generators.
 - [x] Object literals with shorthand, computed string/number keys, and spread following ToObject: data objects and
       arrays copy own enumerable keys, strings copy index keys, and other values contribute nothing.
 - [x] Template literals with interpolation.
@@ -95,8 +95,8 @@ ultimate source of truth. Upstream test262 files run verbatim from `test/test262
 - [x] `if`/`else` and conditional expressions.
 - [x] `switch`, including default clauses and fallthrough.
 - [x] `for`, `while`, and `do...while`.
-- [x] `for...of` over arrays, strings, Maps, Sets, URLSearchParams, custom synchronous iterators, and confined
-      synchronous generators. Abrupt completion invokes the iterator's optional `return()`.
+- [x] `for...of` over arrays, strings, Maps, Sets, URLSearchParams, Headers, custom synchronous iterators, and
+      confined synchronous generators. Abrupt completion invokes the iterator's optional `return()`.
 - [x] `for...in` over own keys of plain objects, arrays, strings, and tool references; other values iterate nothing.
 - [x] Unlabeled `break` and `continue`.
 - [x] `try`, `catch`, optional catch bindings, and `finally`.
@@ -127,7 +127,7 @@ ultimate source of truth. Upstream test262 files run verbatim from `test/test262
       string). A detached method loses its receiver, as in JS: `values.filter("abc".includes)` is a `TypeError`
       because `includes` is called without a string `this`.
 - [x] Constructors work as callbacks with JS call semantics: `Error` types construct (`messages.map(Error)`),
-      and new-requiring constructors (`Map`, `Set`, `URL`, `URLSearchParams`, `Promise`) throw a `TypeError`,
+      and new-requiring constructors (`Map`, `Set`, `URL`, `URLSearchParams`, `Headers`, `Promise`) throw a `TypeError`,
       like JS.
 - [x] Tool references and detached `Promise` statics are rejected as callbacks with a hint to wrap them in an
       arrow function.
@@ -179,10 +179,10 @@ ultimate source of truth. Upstream test262 files run verbatim from `test/test262
 - [x] Sequence expressions (the comma operator).
 - [x] `await` for CodeMode promises and callable thenables; a plain value passes through unchanged, though every
       `await` still defers its continuation one reaction turn.
-- [x] `new` for Array, Object, Error types, Date, RegExp, Map, Set, URL, URLSearchParams, and Promise. `new` on any
-      other value throws a catchable `TypeError` naming the callee: other built-in functions such as `Number` say
-      `new` is unsupported and point at the plain call, user-defined functions report the constructor gap below, and
-      non-callable values are not constructors.
+- [x] `new` for Array, Object, Error types, Date, RegExp, Map, Set, URL, URLSearchParams, Headers, and Promise. `new`
+      on any other value throws a catchable `TypeError` naming the callee: other built-in functions such as `Number`
+      say `new` is unsupported and point at the plain call, user-defined functions report the constructor gap below,
+      and non-callable values are not constructors.
 - [x] Arithmetic operators: `+`, `-`, `*`, `/`, `%`, and `**`.
 - [x] Equality and ordering: `==`, `!=`, `===`, `!==`, `<`, `<=`, `>`, and `>=`.
 - [x] Bitwise operators: `&`, `|`, `^`, `~`, `<<`, `>>`, and `>>>`.
@@ -450,7 +450,13 @@ with a hint to encode as text first (`TextDecoder`, `toBase64`, `toHex`).
 - [x] `crypto.randomUUID()` and `crypto.getRandomValues(uint8Array)`.
 - [x] `TextEncoder` and `TextDecoder` for UTF-8 only: any other label is a `RangeError`. `TextDecoder` accepts the
       `fatal` and `ignoreBOM` options; `decode` takes a Uint8Array or nothing.
-- [ ] `crypto.subtle`, `Blob`, and `TextDecoder` streaming or non-UTF-8 encodings.
+- [x] `new Headers()` from records, synchronous iterables of pairs, and Headers, wrapping the host's `Headers`: names
+      fold to lowercase, values are normalized and combined, and invalid names or values throw a `TypeError`.
+- [x] Headers `append`, `delete`, `get`, `getSetCookie`, `has`, `set`, `forEach`, `keys`, `values`, and `entries`;
+      iteration is live and sorted by name, with `set-cookie` values kept apart.
+- [x] Headers serialize to a `{ name: value }` object in JSON, in results, and in tool arguments.
+- [ ] `Request`, `Response`, and `Blob`.
+- [ ] `crypto.subtle` and `TextDecoder` streaming or non-UTF-8 encodings.
 
 ## Extensions
 
@@ -460,8 +466,8 @@ Nothing is exposed unless a host provides it; extension calls are not tool calls
 - [x] Each global is a function, callable but not constructible, run with `this` undefined. A global that shadows
       a built-in or another extension throws at `make`.
 - [x] Every value crossing in either direction is converted, never shared: plain objects and arrays are copied,
-      `Date`, `RegExp`, `URL`, `URLSearchParams`, `Map`, `Set`, and `Uint8Array` become fresh copies with their
-      contents converted (a host `ArrayBuffer` comes in as a `Uint8Array`; other typed arrays cannot come out),
+      `Date`, `RegExp`, `URL`, `URLSearchParams`, `Headers`, `Map`, `Set`, and `Uint8Array` become fresh copies with
+      their contents converted (a host `ArrayBuffer` comes in as a `Uint8Array`; other typed arrays cannot come out),
       errors cross as errors with their name and message, and a `__proto__` key is dropped. Functions, generators,
       un-awaited promises, and symbols cannot be passed in; a class instance, a symbol, or a BigInt cannot come out.
 - [x] A host function inside a result becomes a program function whose calls cross the same way, so a result can

packages/codemode/src/data.ts

@@ -17,6 +17,7 @@ import {
   record,
   SetObj,
   URLSearchParamsObj,
+  HeadersObj,
 } from "./interpreter/objects.js"
 import { typeofValue } from "./interpreter/references.js"
 
@@ -69,6 +70,7 @@ const walk = <R>(
         )
       }
       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.")
       stack.add(target)

packages/codemode/src/interpreter/extensions.ts

@@ -24,6 +24,7 @@ import {
   SetObj,
   URLObj,
   URLSearchParamsObj,
+  HeadersObj,
 } from "./objects.js"
 import { describeValue } from "./references.js"
 
@@ -49,6 +50,7 @@ export const extensionGlobals = <R>(
     if (value instanceof RegExpObj) return new RegExp(value.regex.source, value.regex.flags)
     if (value instanceof URLObj) return new URL(value.url.href)
     if (value instanceof URLSearchParamsObj) return new URLSearchParams(value.params)
+    if (value instanceof HeadersObj) return new Headers(value.headers)
     const next = (item: unknown) => toHost(item, label, depth + 1, seen)
     if (value instanceof MapObj) return new Map([...value.map].map(([key, item]) => [next(key), next(item)]))
     if (value instanceof SetObj) return new Set([...value.set].map(next))
@@ -96,6 +98,7 @@ export const extensionGlobals = <R>(
       if (value instanceof URLSearchParams) {
         return new URLSearchParamsObj(builtins.URLSearchParams, new URLSearchParams(value))
       }
+      if (value instanceof Headers) return new HeadersObj(builtins.Headers, new Headers(value))
       const next = (item: unknown, path: string) => fromHost(item, path, depth + 1, seen)
       if (value instanceof Map) {
         const wrapped = new MapObj(builtins.Map)

packages/codemode/src/interpreter/globals.ts

@@ -11,6 +11,7 @@ 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 { coercion } from "../stdlib/value.js"
 import { base64Global, cryptoGlobal } from "../stdlib/web.js"
 import { ToolReference } from "../tool-runtime.js"
@@ -80,6 +81,7 @@ const table: Record<string, Factory> = {
   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),

packages/codemode/src/interpreter/interpreter.ts

@@ -84,6 +84,7 @@ import {
   PromiseObj,
   SetObj,
   URLSearchParamsObj,
+  HeadersObj,
   record,
   remove,
   set,
@@ -653,7 +654,7 @@ class Frame<R> {
       const cursor = iterator === undefined ? yield* self.iterate(right, node) : 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.`,
+          `${awaiting ? "for await...of" : "for...of"} requires an array, string, Map, Set, URLSearchParams, or Headers, or custom iterator value.`,
           node,
         )
       }
@@ -756,9 +757,11 @@ class Frame<R> {
               ? value.set.values()
               : value instanceof URLSearchParamsObj
                 ? value.params.entries()
-                : value instanceof Bytes
-                  ? value.bytes.values()
-                  : undefined
+                : value instanceof HeadersObj
+                  ? value.headers.entries()
+                  : value instanceof Bytes
+                    ? value.bytes.values()
+                    : undefined
     if (iterator !== undefined) {
       const proto = this.ctx.builtins.Array
       return Effect.succeed({
@@ -1848,6 +1851,7 @@ class Frame<R> {
         value instanceof MapObj ||
         value instanceof SetObj ||
         value instanceof URLSearchParamsObj ||
+        value instanceof HeadersObj ||
         value instanceof Bytes
       ) {
         const cursor = yield* self.iterate(value, node)

packages/codemode/src/interpreter/intrinsics.ts

@@ -29,6 +29,7 @@ const builtins = [
   "Set",
   "URL",
   "URLSearchParams",
+  "Headers",
   "Uint8Array",
   "TextEncoder",
   "TextDecoder",
@@ -80,6 +81,7 @@ export const createBuiltins = (): Builtins => {
     Set: plain(),
     URL: plain(),
     URLSearchParams: plain(),
+    Headers: plain(),
     Uint8Array: plain(),
     TextEncoder: plain(),
     TextDecoder: plain(),

packages/codemode/src/interpreter/objects.ts

@@ -156,6 +156,15 @@ export class URLSearchParamsObj extends Obj {
   }
 }
 
+export class HeadersObj extends Obj {
+  constructor(
+    proto: Obj,
+    readonly headers: Headers,
+  ) {
+    super(proto)
+  }
+}
+
 export class URLObj extends Obj {
   readonly searchParams: URLSearchParamsObj
   constructor(
@@ -181,13 +190,14 @@ export class Bytes extends Obj {
 /** Built-in objects that wrap a host value; data-like, but never plain data. */
 export const isWrapper = (
   value: unknown,
-): value is DateObj | RegExpObj | MapObj | SetObj | URLObj | URLSearchParamsObj | Bytes =>
+): value is DateObj | RegExpObj | MapObj | SetObj | URLObj | URLSearchParamsObj | HeadersObj | Bytes =>
   value instanceof DateObj ||
   value instanceof RegExpObj ||
   value instanceof MapObj ||
   value instanceof SetObj ||
   value instanceof URLObj ||
   value instanceof URLSearchParamsObj ||
+  value instanceof HeadersObj ||
   value instanceof Bytes
 
 const MAX_ARRAY_INDEX = 4_294_967_295

packages/codemode/src/interpreter/references.ts

@@ -16,6 +16,7 @@ import {
   SetObj,
   URLObj,
   URLSearchParamsObj,
+  HeadersObj,
 } from "./objects.js"
 
 /** Values that cannot cross the data boundary. */
@@ -85,6 +86,7 @@ export const describeValue = (value: unknown): string => {
   if (value instanceof SetObj) return "a Set"
   if (value instanceof URLObj) return "a URL"
   if (value instanceof URLSearchParamsObj) return "a URLSearchParams"
+  if (value instanceof HeadersObj) return "a Headers"
   if (value instanceof Bytes) return "a Uint8Array"
   if (value instanceof GeneratorObj) return "a generator"
   if (isRuntimeReference(value)) return "a function"

packages/codemode/src/stdlib/console.ts

@@ -12,6 +12,7 @@ import {
   SetObj,
   URLObj,
   URLSearchParamsObj,
+  HeadersObj,
 } from "../interpreter/objects.js"
 import { containsOpaqueReference, isRuntimeReference } from "../interpreter/references.js"
 import type { Interpreter } from "../interpreter/interpreter.js"
@@ -66,6 +67,7 @@ const formatConsoleValue = (value: unknown, seen: Set<object>, depth: number): s
   if (value instanceof RegExpObj) return coerceToString(value)
   if (value instanceof URLObj) return coerceToString(value)
   if (value instanceof URLSearchParamsObj) return coerceToString(value)
+  if (value instanceof HeadersObj) return `Headers ${JSON.stringify(Object.fromEntries(value.headers))}`
   if (value instanceof Bytes) return `Uint8Array(${value.bytes.length}) [${value.bytes.join(",")}]`
   if (depth > MAX_CONSOLE_DEPTH) return "..."
   if (seen.has(value)) return "[Circular]"