@opencode/codemode 0.0.0-reserved → 2.0.1

package/README.md

@@ -1,5 +1,187 @@
 # @opencode/codemode
 
-Bootstrap placeholder for the official [OpenCode](https://opencode.ai) release pipeline.
+This is our take on code mode: a lightweight, pure interpreter for a JavaScript-like language built around calling
+tools. It supports familiar JavaScript syntax with a few key differences and limitations. See the
+[interpreter support checklist](./interpreter-support.md) for more details.
 
-This version contains no implementation or executable. Do not use it as a functional release.
+Rather than trying to sandbox arbitrary JavaScript, CodeMode only runs the language features we implement. Programs
+cannot directly access the network, filesystem, processes, or application APIs. They can interact with the outside
+world only through tools provided by the host, which can also limit execution time, tool calls, output size, and data.
+
+The idea of code mode was originally introduced by Cloudflare. See
+[their post](https://blog.cloudflare.com/code-mode/) to learn more about the concept and their isolate-based approach.
+
+## 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.
+- **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`
+  becomes `null`.
+
+Unsupported syntax returns an `UnsupportedSyntax` diagnostic with a source location. Current gaps are tracked in the
+[interpreter support checklist](./interpreter-support.md).
+
+## Quick Start
+
+```ts
+import { CodeMode, Namespace, Tool } from "@opencode/codemode"
+import { Effect, Schema } from "effect"
+
+const lookupOrder = Tool.make({
+  description: "Look up an order by ID",
+  input: Schema.Struct({ id: Schema.String }),
+  output: Schema.Struct({ id: Schema.String, status: Schema.String }),
+  execute: ({ id }) => Effect.succeed({ id, status: "open" }),
+})
+
+const runtime = CodeMode.make({
+  tools: { orders: { lookup: lookupOrder } },
+})
+
+const result = await Effect.runPromise(
+  runtime.execute(`
+    const order = await tools.orders.lookup({ id: "order_42" })
+    return { id: order.id, needsAttention: order.status !== "complete" }
+  `),
+)
+```
+
+`result` is always a [`CodeMode.Result`](#results).
+
+## API
+
+### `Tool.make`
+
+`input` and `output` accept either an Effect Schema or a render-only JSON Schema document. Effect Schema input is
+decoded before `execute`; Effect Schema output is decoded and safely copied before the program sees it. JSON Schemas
+only shape the model-visible signature. Without `output`, the signature uses `Promise<void>`.
+
+Descriptions and schemas are model-visible contracts. Authorization belongs in `execute`.
+
+Nested records are the shorthand for ordinary namespaces. Use `Namespace.make` when a namespace needs a description:
+
+```ts
+const runtime = CodeMode.make({
+  tools: {
+    orders: Namespace.make({
+      description: "Purchases, fulfillment, and shipment tracking",
+      tools: { lookup: lookupOrder },
+    }),
+  },
+})
+```
+
+Namespace descriptions are optional and participate in search matching for every descendant tool. Names still come
+from record keys, so the wrapper does not repeat `orders`. Dots in keys create nested paths; other characters use
+bracket notation, such as `tools.context7["resolve-library-id"](...)`.
+
+### `CodeMode.execute` and `CodeMode.make`
+
+`CodeMode.execute({ ...options, code })` runs once. `CodeMode.make(options)` creates a reusable runtime:
+
+```ts
+const runtime = CodeMode.make({ tools, limits: { timeoutMs: 30_000 } })
+
+runtime.catalog() // structured tool descriptions
+runtime.execute(source) // Effect<CodeMode.Result, never, ToolServices>
+```
+
+The Effect environment is inferred from the supplied tools. `onToolCallStart` observes admitted calls with decoded
+input; `onToolCallEnd` observes settled outcomes and duration. Both hooks return Effects and must not fail.
+
+### `Values`
+
+`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.
+
+### OpenAPI tools
+
+`OpenAPI.fromSpec` converts an OpenAPI 3.x document into one tool per supported operation. Dotted `operationId` values
+create namespaces:
+
+```ts
+const api = OpenAPI.fromSpec({ spec, auth: { resolve } })
+const runtime = CodeMode.make({ tools: { opencode: api.tools } })
+```
+
+The synchronous result is `{ tools, skipped }`. Operations with unsupported parameter encodings, request bodies
+without JSON content, WebSocket or SSE semantics, or binary responses are reported in `skipped`.
+
+Authentication is resolved by the host and never shown to the model. Generated tools require `HttpClient.HttpClient`.
+Request signatures omit `readOnly` properties; response signatures omit `writeOnly` properties. These JSON Schemas
+shape model-visible signatures but do not filter runtime values: nested JSON body properties and decoded server
+responses pass through unchanged. See `src/openapi/types.ts` for option details.
+
+## Results
+
+Every execution returns:
+
+```ts
+type Result =
+  | {
+      readonly ok: true
+      readonly value: CodeMode.DataValue
+      readonly warnings?: ReadonlyArray<CodeMode.Diagnostic>
+      readonly logs?: ReadonlyArray<string>
+      readonly truncated?: boolean
+      readonly toolCalls: ReadonlyArray<CodeMode.ToolCall>
+    }
+  | {
+      readonly ok: false
+      readonly error: CodeMode.Diagnostic
+      readonly logs?: ReadonlyArray<string>
+      readonly truncated?: boolean
+      readonly toolCalls: ReadonlyArray<CodeMode.ToolCall>
+    }
+```
+
+`value` is JSON-safe. `warnings` are non-fatal diagnostics, `logs` contain program console output, and `truncated`
+indicates that retained output was cut by `maxOutputBytes`. `toolCalls` retains admitted calls in order, including after
+failure.
+
+Diagnostic kinds:
+
+| Kind                    | Meaning                                                                                        |
+| ----------------------- | ---------------------------------------------------------------------------------------------- |
+| `ParseError`            | Source is empty or cannot be parsed.                                                           |
+| `UnsupportedSyntax`     | Parsed JavaScript is outside the supported subset.                                             |
+| `UnknownTool`           | The program referenced an unavailable tool.                                                    |
+| `InvalidToolInput`      | Tool input failed schema decoding or safe-data copying.                                        |
+| `InvalidToolOutput`     | Tool output failed schema decoding or safe-data copying.                                       |
+| `InvalidDataValue`      | Program data violated the plain-data contract.                                                 |
+| `ToolCallLimitExceeded` | The program exceeded `maxToolCalls`.                                                           |
+| `TimeoutExceeded`       | Execution timed out; as a warning, background work was interrupted after the program returned. |
+| `ToolFailure`           | A tool refused or failed.                                                                      |
+| `ExecutionFailure`      | The program threw or another execution error occurred.                                         |
+| `Truncated`             | Warning only: additional warnings were omitted by `maxOutputBytes`.                            |
+
+Host failures and defects report their messages and underlying causes. Invalid outputs include the validation or
+copying error. Interruption propagates without becoming an error diagnostic.
+
+## Discovery
+
+`runtime.catalog()` returns structured descriptors — exact path, description, and generated TypeScript signature — for
+every visible tool. Hosts render their own model-facing instructions from these descriptors; `CodeMode.searchSignature`
+and `CodeMode.toolExpression(path)` supply the exact callable forms.
+
+The synchronous `search(...)` built-in is always available. It supports exact-path lookup, namespace-scoped search,
+empty-query browsing, and pagination, and returns callable paths with full signatures. Search counts toward
+`maxToolCalls`. Search also matches descriptions from enclosing `Namespace` values.
+
+## Execution Limits
+
+| Limit            | Default   | Controls                        |
+| ---------------- | --------- | ------------------------------- |
+| `timeoutMs`      | unlimited | Total execution time.           |
+| `maxToolCalls`   | unlimited | Admitted tool calls.            |
+| `maxOutputBytes` | unlimited | Retained result value and logs. |
+
+Execution limits have no default values.
+
+Invalid limit configuration throws `RangeError`. Warnings receive a separate budget equal to `maxOutputBytes`.
+Truncation does not fail execution; an oversized value becomes a string with an in-band marker. Timeouts interrupt
+tool calls and busy loops, while a result returned before cleanup times out remains successful with a
+`TimeoutExceeded` warning. Tool-call concurrency is unrestricted. Boundary data is limited to 32 nested levels.

package/dist/codemode.d.ts

@@ -0,0 +1,145 @@
+import { Effect, Schema } from "effect";
+import { type Services, type ToolDescription, ToolRuntime } from "./tool-runtime.js";
+import type { Tools } from "./tools.js";
+/** A tool call admitted during an execution. */
+export type { ToolCall, ToolCallEnded, ToolCallHooks, ToolCallStarted, ToolDescription } from "./tool-runtime.js";
+/** Signature-construction helpers for host-owned catalog instructions. */
+export { searchSignature, toolExpression } from "./tool-runtime.js";
+/** Resource budgets enforced independently during each CodeMode program execution. */
+export type ExecutionLimits = {
+    /**
+     * Wall-clock milliseconds before interruption. Result delivery waits for tool cleanup.
+     * No default: absent means no timeout.
+     */
+    readonly timeoutMs?: number;
+    /** Maximum number of tool calls admitted by the runtime. No default: absent means unlimited. */
+    readonly maxToolCalls?: number;
+    /**
+     * Maximum UTF-8 bytes retained from the result and logs. Warnings have a separate equal budget;
+     * truncation notices and host formatting are additional.
+     */
+    readonly maxOutputBytes?: number;
+};
+export type ResolvedExecutionLimits = {
+    readonly timeoutMs: number | undefined;
+    readonly maxToolCalls: number | undefined;
+    readonly maxOutputBytes: number | undefined;
+};
+/** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */
+export type Options<Provided extends Record<string, unknown> = {}> = ToolRuntime.ToolCallHooks<Services<Provided>> & {
+    /** Explicit tools exposed to the program as `tools`. */
+    tools?: Provided & Tools<Services<Provided>>;
+    /** Resource limits enforced on each execution. */
+    limits?: ExecutionLimits;
+};
+/** Options for one CodeMode execution. */
+export type ExecuteOptions<Provided extends Record<string, unknown> = {}> = Options<Provided> & {
+    /** Source for one program in the supported JavaScript subset. */
+    code: string;
+};
+/** A JSON value that can cross the confined interpreter boundary. */
+export type DataValue = Schema.Json;
+/** Schema for a host tool input containing CodeMode source. */
+export declare const Input: Schema.Struct<{
+    readonly code: Schema.String;
+}>;
+export type Input = typeof Input.Type;
+export declare const DiagnosticKind: Schema.Literals<readonly ["ParseError", "UnsupportedSyntax", "UnknownTool", "InvalidToolInput", "InvalidToolOutput", "InvalidDataValue", "ToolCallLimitExceeded", "TimeoutExceeded", "ToolFailure", "ExecutionFailure", "Truncated"]>;
+/** Stable categories produced by program, schema, tool, limit, and truncation diagnostics. */
+export type DiagnosticKind = typeof DiagnosticKind.Type;
+export declare const Diagnostic: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["ParseError", "UnsupportedSyntax", "UnknownTool", "InvalidToolInput", "InvalidToolOutput", "InvalidDataValue", "ToolCallLimitExceeded", "TimeoutExceeded", "ToolFailure", "ExecutionFailure", "Truncated"]>;
+    readonly message: Schema.String;
+    readonly location: Schema.optionalKey<Schema.Struct<{
+        readonly line: Schema.Number;
+        readonly column: Schema.Number;
+    }>>;
+    readonly suggestions: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+/** A normalized program diagnostic safe to return across an agent tool boundary. */
+export type Diagnostic = typeof Diagnostic.Type;
+export declare const Success: Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly warnings: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["ParseError", "UnsupportedSyntax", "UnknownTool", "InvalidToolInput", "InvalidToolOutput", "InvalidDataValue", "ToolCallLimitExceeded", "TimeoutExceeded", "ToolFailure", "ExecutionFailure", "Truncated"]>;
+        readonly message: Schema.String;
+        readonly location: Schema.optionalKey<Schema.Struct<{
+            readonly line: Schema.Number;
+            readonly column: Schema.Number;
+        }>>;
+        readonly suggestions: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>>;
+    readonly logs: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly truncated: Schema.optionalKey<Schema.Boolean>;
+    readonly toolCalls: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+    }>>;
+}>;
+/** Successful execution after the result has crossed the plain-data boundary. */
+export type Success = typeof Success.Type;
+export declare const Failure: Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["ParseError", "UnsupportedSyntax", "UnknownTool", "InvalidToolInput", "InvalidToolOutput", "InvalidDataValue", "ToolCallLimitExceeded", "TimeoutExceeded", "ToolFailure", "ExecutionFailure", "Truncated"]>;
+        readonly message: Schema.String;
+        readonly location: Schema.optionalKey<Schema.Struct<{
+            readonly line: Schema.Number;
+            readonly column: Schema.Number;
+        }>>;
+        readonly suggestions: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>;
+    readonly logs: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly truncated: Schema.optionalKey<Schema.Boolean>;
+    readonly toolCalls: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+    }>>;
+}>;
+/** Failed execution with calls admitted before the diagnostic was produced. */
+export type Failure = typeof Failure.Type;
+/** Schema for the structured success or diagnostic returned by CodeMode execution. */
+export declare const Result: Schema.Union<readonly [Schema.Struct<{
+    readonly ok: Schema.Literal<true>;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly warnings: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["ParseError", "UnsupportedSyntax", "UnknownTool", "InvalidToolInput", "InvalidToolOutput", "InvalidDataValue", "ToolCallLimitExceeded", "TimeoutExceeded", "ToolFailure", "ExecutionFailure", "Truncated"]>;
+        readonly message: Schema.String;
+        readonly location: Schema.optionalKey<Schema.Struct<{
+            readonly line: Schema.Number;
+            readonly column: Schema.Number;
+        }>>;
+        readonly suggestions: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>>;
+    readonly logs: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly truncated: Schema.optionalKey<Schema.Boolean>;
+    readonly toolCalls: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+    }>>;
+}>, Schema.Struct<{
+    readonly ok: Schema.Literal<false>;
+    readonly error: Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["ParseError", "UnsupportedSyntax", "UnknownTool", "InvalidToolInput", "InvalidToolOutput", "InvalidDataValue", "ToolCallLimitExceeded", "TimeoutExceeded", "ToolFailure", "ExecutionFailure", "Truncated"]>;
+        readonly message: Schema.String;
+        readonly location: Schema.optionalKey<Schema.Struct<{
+            readonly line: Schema.Number;
+            readonly column: Schema.Number;
+        }>>;
+        readonly suggestions: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>;
+    readonly logs: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly truncated: Schema.optionalKey<Schema.Boolean>;
+    readonly toolCalls: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+    }>>;
+}>]>;
+/** Result of executing a CodeMode program. Program failures are data, not Effect failures. */
+export type Result = typeof Result.Type;
+/** Reusable confined runtime over explicit tools. */
+export type Runtime<R = never> = {
+    readonly catalog: ReadonlyArray<ToolDescription>;
+    readonly execute: (code: string) => Effect.Effect<Result, never, R>;
+};
+/** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
+export declare const execute: <const Provided extends Record<string, unknown>>(options: ExecuteOptions<Provided>) => Effect.Effect<Result, never, Services<Provided>>;
+/** Creates an Effect-native runtime over explicit, schema-described tools. */
+export declare const make: <const Provided extends Record<string, unknown> = {}>(options?: Options<Provided>) => Runtime<Services<Provided>>;

package/dist/codemode.js

@@ -0,0 +1,66 @@
+import { Effect, Schema } from "effect";
+import { executeProgram } from "./interpreter/execute.js";
+import { ToolRuntime } from "./tool-runtime.js";
+/** Signature-construction helpers for host-owned catalog instructions. */
+export { searchSignature, toolExpression } from "./tool-runtime.js";
+/** Schema for a host tool input containing CodeMode source. */
+export const Input = Schema.Struct({ code: Schema.String });
+export const DiagnosticKind = Schema.Literals([
+    "ParseError",
+    "UnsupportedSyntax",
+    "UnknownTool",
+    "InvalidToolInput",
+    "InvalidToolOutput",
+    "InvalidDataValue",
+    "ToolCallLimitExceeded",
+    "TimeoutExceeded",
+    "ToolFailure",
+    "ExecutionFailure",
+    "Truncated",
+]);
+export const Diagnostic = Schema.Struct({
+    kind: DiagnosticKind,
+    message: Schema.String,
+    location: Schema.optionalKey(Schema.Struct({ line: Schema.Number, column: Schema.Number })),
+    suggestions: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+const ToolCallSchema = Schema.Struct({ name: Schema.String });
+export const Success = Schema.Struct({
+    ok: Schema.Literal(true),
+    value: Schema.Json,
+    warnings: Schema.optionalKey(Schema.Array(Diagnostic)),
+    logs: Schema.optionalKey(Schema.Array(Schema.String)),
+    truncated: Schema.optionalKey(Schema.Boolean),
+    toolCalls: Schema.Array(ToolCallSchema),
+});
+export const Failure = Schema.Struct({
+    ok: Schema.Literal(false),
+    error: Diagnostic,
+    logs: Schema.optionalKey(Schema.Array(Schema.String)),
+    truncated: Schema.optionalKey(Schema.Boolean),
+    toolCalls: Schema.Array(ToolCallSchema),
+});
+/** Schema for the structured success or diagnostic returned by CodeMode execution. */
+export const Result = Schema.Union([Success, Failure]);
+const validateLimit = (name, value, minimum) => {
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < minimum)) {
+        throw new RangeError(`${name} must be a safe integer greater than or equal to ${minimum}.`);
+    }
+    return value;
+};
+const resolveExecutionLimits = (limits) => ({
+    timeoutMs: validateLimit("timeoutMs", limits?.timeoutMs, 1),
+    maxToolCalls: validateLimit("maxToolCalls", limits?.maxToolCalls, 0),
+    maxOutputBytes: validateLimit("maxOutputBytes", limits?.maxOutputBytes, 0),
+});
+/** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
+export const execute = (options) => make(options).execute(options.code);
+/** Creates an Effect-native runtime over explicit, schema-described tools. */
+export const make = (options = {}) => {
+    const prepared = ToolRuntime.prepare((options.tools ?? {}));
+    const limits = resolveExecutionLimits(options.limits);
+    return {
+        catalog: prepared.catalog,
+        execute: (code) => executeProgram(code, prepared, limits, options),
+    };
+};

package/dist/data.d.ts

@@ -0,0 +1,25 @@
+export * as Data from "./data.js";
+import type { DiagnosticKind } from "./codemode.js";
+export declare class ToolRuntimeError extends Error {
+    readonly kind: Extract<DiagnosticKind, "UnknownTool" | "InvalidToolInput" | "InvalidToolOutput" | "InvalidDataValue" | "ToolCallLimitExceeded">;
+    readonly suggestions: ReadonlyArray<string>;
+    constructor(kind: Extract<DiagnosticKind, "UnknownTool" | "InvalidToolInput" | "InvalidToolOutput" | "InvalidDataValue" | "ToolCallLimitExceeded">, message: string, suggestions?: ReadonlyArray<string>);
+}
+/**
+ * Brings a host-produced value into the program: program and runtime values pass through, their
+ * host counterparts (Date, RegExp, Map, Set, URL, URLSearchParams) are wrapped, and host objects
+ * and arrays are copied.
+ */
+export declare const toProgram: (value: unknown, label: string) => unknown;
+/**
+ * Brings host data into the program: Date and URL become strings, other host collections become
+ * empty objects, and objects become program copies. Used for tool results and parsed JSON.
+ */
+export declare const fromData: (value: unknown, label: string) => unknown;
+/**
+ * Takes a program value out as plain JSON: runtime values serialize like `JSON.stringify` would,
+ * non-finite numbers become null, and array holes become null. `undefined` object properties are
+ * dropped ("json") or become null ("result", for program results where the consumer must never see
+ * undefined); a bare `undefined` follows the same rule.
+ */
+export declare const toData: (value: unknown, label: string, undefinedAs?: "json" | "result") => unknown;

package/dist/data.js

@@ -0,0 +1,158 @@
+export * as Data from "./data.js";
+import { get, ownEntries, parseArrayIndex, ProgramArray, ProgramError, ProgramFunction, ProgramObject, set, } from "./interpreter/objects.js";
+import { Values } from "./values.js";
+const MAX_VALUE_DEPTH = 32;
+export class ToolRuntimeError extends Error {
+    kind;
+    suggestions;
+    constructor(kind, message, suggestions = []) {
+        super(message);
+        this.kind = kind;
+        this.suggestions = suggestions;
+        this.name = "ToolRuntimeError";
+    }
+}
+/**
+ * Brings a host-produced value into the program: program and runtime values pass through, their
+ * host counterparts (Date, RegExp, Map, Set, URL, URLSearchParams) are wrapped, and host objects
+ * and arrays are copied.
+ */
+export const toProgram = (value, label) => copy(value, label, "program", 0, new Set());
+/**
+ * Brings host data into the program: Date and URL become strings, other host collections become
+ * empty objects, and objects become program copies. Used for tool results and parsed JSON.
+ */
+export const fromData = (value, label) => copy(value, label, "data", 0, new Set());
+/**
+ * Takes a program value out as plain JSON: runtime values serialize like `JSON.stringify` would,
+ * non-finite numbers become null, and array holes become null. `undefined` object properties are
+ * dropped ("json") or become null ("result", for program results where the consumer must never see
+ * undefined); a bare `undefined` follows the same rule.
+ */
+export const toData = (value, label, undefinedAs = "json") => copy(value, label, undefinedAs, 0, new Set());
+const copy = (value, label, mode, depth, seen) => {
+    if (depth > MAX_VALUE_DEPTH) {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`);
+    }
+    if (value === undefined)
+        return mode === "result" ? null : undefined;
+    if (typeof value === "number")
+        return (mode === "json" || mode === "result") && !Number.isFinite(value) ? null : value;
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value !== "object") {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} must contain data only.`);
+    }
+    if (value instanceof Values.Promise) {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} contains an un-awaited Promise; await tool calls (e.g. \`const result = await tools.ns.tool(...)\`) before using their results.`);
+    }
+    if (value instanceof ProgramFunction && mode !== "program") {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} must contain data only.`);
+    }
+    const plain = mode === "program" || mode === "data";
+    if (mode === "program") {
+        if (value instanceof ProgramObject || Values.isValue(value))
+            return value;
+        if (value instanceof Date)
+            return new Values.Date(value.getTime());
+        if (value instanceof RegExp)
+            return new Values.RegExp(value.source, value.flags);
+        if (value instanceof Map) {
+            const wrapped = new Values.Map();
+            for (const [key, item] of value.entries()) {
+                wrapped.map.set(copy(key, label, mode, depth + 1, seen), copy(item, label, mode, depth + 1, seen));
+            }
+            return wrapped;
+        }
+        if (value instanceof Set) {
+            const wrapped = new Values.Set();
+            for (const item of value.values())
+                wrapped.set.add(copy(item, label, mode, depth + 1, seen));
+            return wrapped;
+        }
+        if (value instanceof URL)
+            return new Values.URL(new URL(value.href));
+        if (value instanceof URLSearchParams)
+            return new Values.URLSearchParams(new URLSearchParams(value));
+    }
+    if (value instanceof Values.Date)
+        return Number.isFinite(value.time) ? new Date(value.time).toISOString() : null;
+    if (value instanceof Date)
+        return Number.isFinite(value.getTime()) ? value.toISOString() : null;
+    if (value instanceof Values.URL)
+        return value.url.href;
+    if (value instanceof URL)
+        return value.href;
+    // Remaining runtime values and their host counterparts serialize as empty objects, like JSON.stringify.
+    if (Values.isValue(value) ||
+        value instanceof RegExp ||
+        value instanceof Map ||
+        value instanceof Set ||
+        value instanceof URLSearchParams) {
+        return plain ? new ProgramObject() : {};
+    }
+    if (seen.has(value)) {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} contains a circular value.`);
+    }
+    seen.add(value);
+    if (value instanceof ProgramArray) {
+        const copied = Array.from(value.items, (item) => copy(item, label, mode, depth + 1, seen) ?? null);
+        seen.delete(value);
+        return copied;
+    }
+    if (value instanceof ProgramObject) {
+        const copied = {};
+        // Errors serialize as { name, message, ...own }: both may be inherited, and neither is enumerable in JS.
+        if (value instanceof ProgramError) {
+            define(copied, "name", copy(get(value, "name"), label, mode, depth + 1, seen));
+            define(copied, "message", copy(get(value, "message"), label, mode, depth + 1, seen));
+        }
+        for (const [key, item] of ownEntries(value)) {
+            const next = copy(item, label, mode, depth + 1, seen);
+            if (next === undefined && mode === "json")
+                continue;
+            define(copied, key, next);
+        }
+        seen.delete(value);
+        return copied;
+    }
+    if (Array.isArray(value)) {
+        if (plain) {
+            const copied = new ProgramArray(value.map((item) => copy(item, label, mode, depth + 1, seen)));
+            for (const [key, item] of Object.entries(value)) {
+                if (parseArrayIndex(key) === undefined)
+                    set(copied, key, copy(item, label, mode, depth + 1, seen));
+            }
+            seen.delete(value);
+            return copied;
+        }
+        const copied = Array.from(value, (item) => copy(item, label, mode, depth + 1, seen) ?? null);
+        seen.delete(value);
+        return copied;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} must contain plain objects only.`);
+    }
+    if (plain) {
+        const copied = new ProgramObject();
+        for (const [key, item] of Object.entries(value))
+            set(copied, key, copy(item, label, mode, depth + 1, seen));
+        seen.delete(value);
+        return copied;
+    }
+    const copied = {};
+    for (const [key, item] of Object.entries(value)) {
+        const next = copy(item, label, mode, depth + 1, seen);
+        if (next === undefined && mode === "json")
+            continue;
+        define(copied, key, next);
+    }
+    seen.delete(value);
+    return copied;
+};
+// Own data property regardless of the target's prototype, so a "__proto__" key on a host object
+// never reaches the Object.prototype setter.
+const define = (target, key, value) => {
+    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * as CodeMode from "./codemode.js";
+export * as Namespace from "./namespace.js";
+export * as Tool from "./tool.js";
+export * as OpenAPI from "./openapi/index.js";
+export { Values } from "./values.js";
+export { searchSignature, toolExpression } from "./codemode.js";
+export { ToolError, toolError } from "./tool-error.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * as CodeMode from "./codemode.js";
+export * as Namespace from "./namespace.js";
+export * as Tool from "./tool.js";
+export * as OpenAPI from "./openapi/index.js";
+export { Values } from "./values.js";
+export { searchSignature, toolExpression } from "./codemode.js";
+export { ToolError, toolError } from "./tool-error.js";

package/dist/interpreter/errors.d.ts

@@ -0,0 +1,10 @@
+import type { Diagnostic } from "../codemode.js";
+import { HostFunction } from "./host.js";
+import { type ErrorType } from "./intrinsics.js";
+import { ProgramError } from "./objects.js";
+import { type Runner } from "./runner.js";
+export declare const normalizeError: (error: unknown) => Diagnostic;
+export declare const caughtErrorValue: <R>(runner: Runner<R>, thrown: unknown) => unknown;
+export declare const createAggregateErrorValue: <R>(runner: Runner<R>, errors: Array<unknown>, message: string) => ProgramError;
+/** An error constructor such as `Error` or `TypeError`; callable with or without `new`, like JS. */
+export declare const errorGlobal: <R>(type: ErrorType, runner: Runner<R>) => HostFunction<R>;