@opencode/codemode 2.0.3 → 2.0.4

package/dist/codemode.d.ts

@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect";
+import type { Extension } from "./extension.js";
 import { type Services, type ToolDescription, ToolRuntime } from "./tool-runtime.js";
 import type { Tools } from "./tools.js";
 /** A tool call admitted during an execution. */
@@ -29,6 +30,8 @@ export type ResolvedExecutionLimits = {
 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>>;
+    /** Host functions exposed as globals; see `Extension.make`. */
+    extensions?: ReadonlyArray<Extension>;
     /** Resource limits enforced on each execution. */
     limits?: ExecutionLimits;
 };

package/dist/codemode.js

@@ -1,5 +1,7 @@
 import { Effect, Schema } from "effect";
 import { executeProgram } from "./interpreter/execute.js";
+import { extensionGlobals } from "./interpreter/extensions.js";
+import { globalNames } from "./interpreter/globals.js";
 import { ToolRuntime } from "./tool-runtime.js";
 /** Signature-construction helpers for host-owned catalog instructions. */
 export { searchSignature, toolExpression } from "./tool-runtime.js";
@@ -59,8 +61,17 @@ export const execute = (options) => make(options).execute(options.code);
 export const make = (options = {}) => {
     const prepared = ToolRuntime.prepare((options.tools ?? {}));
     const limits = resolveExecutionLimits(options.limits);
+    const extensions = options.extensions ?? [];
+    const bound = new Set(globalNames);
+    for (const extension of extensions) {
+        for (const name of Object.keys(extension.globals)) {
+            if (bound.has(name))
+                throw new TypeError(`Extension "${extension.name}" global "${name}" is already defined.`);
+            bound.add(name);
+        }
+    }
     return {
         catalog: prepared.catalog,
-        execute: (code) => executeProgram(code, prepared, limits, options),
+        execute: (code) => executeProgram(code, prepared, limits, options, (ctx) => extensionGlobals(ctx, extensions)),
     };
 };

package/dist/data.d.ts

@@ -1,26 +1,19 @@
 export * as Data from "./data.js";
-import type { DiagnosticKind } from "./codemode.js";
-import type { Prototypes } from "./interpreter/intrinsics.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>);
-}
+import { Effect, type Schema } from "effect";
+import type { Interpreter } from "./interpreter/interpreter.js";
+export type Json = Schema.Json;
+type Replacer<R> = (args: Array<unknown>) => Effect.Effect<unknown, unknown, R>;
 /**
- * Brings a host-produced value into the program: program values pass through, host Date, RegExp,
- * Map, Set, URL, and URLSearchParams become their built-in wrappers, and host objects and arrays
- * are copied.
+ * What `JSON.stringify` would serialize for a program value, as host JSON: `toJSON` is honored, functions and
+ * `undefined` vanish, non-finite numbers become null, and everything else is copied. Two departures from JS
+ * so a mistake is not a silent `{}`: an Error serializes as `{ name, message, ...own }`, and a promise throws.
  */
-export declare const toProgram: (protos: Prototypes, value: unknown, label: string) => unknown;
+export declare const toJson: <R>(ctx: Interpreter<R>, value: unknown, replacer?: Replacer<R>) => Effect.Effect<Schema.Json | undefined, unknown, R>;
 /**
- * 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.
+ * The host boundary: `toJson`, plus what a program most likely meant when a value cannot be JSON. A promise is
+ * awaited, a Set crosses as an array, a URLSearchParams as its query string, a Uint8Array asks to be encoded as
+ * text first, and a `__proto__` key is dropped so host code can never receive one.
  */
-export declare const fromData: (protos: Prototypes, 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;
+export declare const toBoundary: <R>(ctx: Interpreter<R>, value: unknown) => Effect.Effect<Schema.Json | undefined, unknown, R>;
+/** Host JSON as program values: objects and arrays are copied, primitives pass through. */
+export declare const fromJson: <R>(ctx: Interpreter<R>, value: unknown) => unknown;

package/dist/data.js

@@ -1,156 +1,88 @@
 export * as Data from "./data.js";
-import { Callable, define, entries, get, isWrapper, parseArrayIndex, ProgramArray, ProgramDate, ProgramError, ProgramGenerator, ProgramMap, ProgramObject, ProgramPromise, ProgramRegExp, ProgramSet, ProgramURL, ProgramURLSearchParams, } from "./interpreter/objects.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";
-    }
-}
+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 { typeofValue } from "./interpreter/references.js";
 /**
- * Brings a host-produced value into the program: program values pass through, host Date, RegExp,
- * Map, Set, URL, and URLSearchParams become their built-in wrappers, and host objects and arrays
- * are copied.
+ * What `JSON.stringify` would serialize for a program value, as host JSON: `toJSON` is honored, functions and
+ * `undefined` vanish, non-finite numbers become null, and everything else is copied. Two departures from JS
+ * so a mistake is not a silent `{}`: an Error serializes as `{ name, message, ...own }`, and a promise throws.
  */
-export const toProgram = (protos, value, label) => copy(value, label, "program", 0, new Set(), protos);
+export const toJson = (ctx, value, replacer) => walk(ctx, value, replacer, false);
 /**
- * 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.
+ * The host boundary: `toJson`, plus what a program most likely meant when a value cannot be JSON. A promise is
+ * awaited, a Set crosses as an array, a URLSearchParams as its query string, a Uint8Array asks to be encoded as
+ * text first, and a `__proto__` key is dropped so host code can never receive one.
  */
-export const fromData = (protos, value, label) => copy(value, label, "data", 0, new Set(), protos);
-/**
- * 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, protos) => {
-    const next = (item) => copy(item, label, mode, depth + 1, seen, protos);
-    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 ProgramPromise) {
-        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 Callable || value instanceof ProgramGenerator) && mode !== "program") {
-        throw new ToolRuntimeError("InvalidDataValue", `${label} must contain data only.`);
-    }
-    if (protos !== undefined && mode === "program") {
-        if (value instanceof ProgramObject)
+export const toBoundary = (ctx, value) => walk(ctx, value, undefined, true);
+const walk = (ctx, value, replacer, boundary) => {
+    const stack = new Set();
+    const visit = (holder, key, depth) => Effect.gen(function* () {
+        if (depth > MAX_VALUE_DEPTH)
+            throw rangeError(`Value exceeds the maximum depth of ${MAX_VALUE_DEPTH}.`);
+        const raw = get(holder, key);
+        if (raw instanceof PromiseObj && !boundary) {
+            throw invalidData("JSON.stringify received an un-awaited Promise; await it first - e.g. `const result = await tools.ns.tool(...)`.");
+        }
+        const settled = raw instanceof PromiseObj ? yield* ctx.await(raw) : raw;
+        const toJSON = settled instanceof Obj ? get(settled, "toJSON") : undefined;
+        const own = toJSON instanceof Callable ? yield* ctx.call(toJSON, settled, [key]) : settled;
+        const value = replacer === undefined ? own : yield* replacer([key, own]);
+        if (value === undefined || typeofValue(value) === "function")
+            return undefined;
+        if (typeof value === "number")
+            return Number.isFinite(value) ? value : null;
+        if (value === null || typeof value === "string" || typeof value === "boolean")
             return value;
-        if (value instanceof Date)
-            return new ProgramDate(protos.Date, value.getTime());
-        if (value instanceof RegExp)
-            return new ProgramRegExp(protos.RegExp, value.source, value.flags);
-        if (value instanceof Map) {
-            const wrapped = new ProgramMap(protos.Map);
-            for (const [key, item] of value.entries())
-                wrapped.map.set(next(key), next(item));
-            return wrapped;
+        if (!(value instanceof Obj))
+            return {};
+        if (boundary && value instanceof Bytes) {
+            throw invalidData("A Uint8Array cannot cross to the host; pass text instead, e.g. `new TextDecoder().decode(bytes)` or `bytes.toBase64()`.");
         }
-        if (value instanceof Set) {
-            const wrapped = new ProgramSet(protos.Set);
-            for (const item of value.values())
-                wrapped.set.add(next(item));
-            return wrapped;
+        if (boundary && value instanceof URLSearchParamsObj)
+            return value.params.toString();
+        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);
+        if (target instanceof Arr) {
+            const items = [];
+            for (let index = 0; index < target.items.length; index += 1) {
+                items.push((yield* visit(target, String(index), depth + 1)) ?? null);
+            }
+            stack.delete(target);
+            return items;
         }
-        if (value instanceof URL)
-            return new ProgramURL(protos.URL, protos.URLSearchParams, new URL(value.href));
-        if (value instanceof URLSearchParams)
-            return new ProgramURLSearchParams(protos.URLSearchParams, new URLSearchParams(value));
-    }
-    if (value instanceof ProgramDate)
-        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 ProgramURL)
-        return value.url.href;
-    if (value instanceof URL)
-        return value.href;
-    // Remaining wrappers and their host counterparts serialize as empty objects, like JSON.stringify.
-    if (isWrapper(value) ||
-        value instanceof RegExp ||
-        value instanceof Map ||
-        value instanceof Set ||
-        value instanceof URLSearchParams) {
-        return protos !== undefined ? new ProgramObject(protos.Object) : {};
-    }
-    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) => next(item) ?? null);
-        seen.delete(value);
-        return copied;
-    }
-    if (value instanceof ProgramObject) {
         const copied = {};
+        // Own data property regardless of the key, so "__proto__" never reaches the Object.prototype setter.
+        const put = (name, item) => {
+            if (item !== undefined)
+                Object.defineProperty(copied, name, { value: item, enumerable: true, writable: true, configurable: true });
+        };
         // Errors serialize as { name, message, ...own }: both may be inherited, and neither is enumerable in JS.
-        if (value instanceof ProgramError) {
-            defineHost(copied, "name", next(get(value, "name")));
-            defineHost(copied, "message", next(get(value, "message")));
+        if (target instanceof ErrorObj) {
+            put("name", yield* visit(target, "name", depth + 1));
+            put("message", yield* visit(target, "message", depth + 1));
         }
-        for (const [key, item] of entries(value)) {
-            const copiedItem = next(item);
-            if (copiedItem === undefined && mode === "json")
+        for (const name of keys(target)) {
+            if (boundary && name === "__proto__")
                 continue;
-            defineHost(copied, key, copiedItem);
+            put(name, yield* visit(target, name, depth + 1));
         }
-        seen.delete(value);
+        stack.delete(target);
         return copied;
-    }
-    if (Array.isArray(value)) {
-        if (protos !== undefined) {
-            const copied = new ProgramArray(protos.Array, value.map(next));
-            for (const [key, item] of Object.entries(value)) {
-                if (parseArrayIndex(key) === undefined)
-                    define(copied, key, next(item));
-            }
-            seen.delete(value);
-            return copied;
-        }
-        const copied = Array.from(value, (item) => next(item) ?? 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 (protos !== undefined) {
-        const copied = new ProgramObject(protos.Object);
-        for (const [key, item] of Object.entries(value))
-            define(copied, key, next(item));
-        seen.delete(value);
-        return copied;
-    }
-    const copied = {};
-    for (const [key, item] of Object.entries(value)) {
-        const copiedItem = next(item);
-        if (copiedItem === undefined && mode === "json")
-            continue;
-        defineHost(copied, key, copiedItem);
-    }
-    seen.delete(value);
-    return copied;
+    });
+    return visit(record(ctx.builtins.Object, { "": value }), "", 0);
 };
-// Own data property regardless of the target's prototype, so a "__proto__" key on a host object
-// never reaches the Object.prototype setter.
-const defineHost = (target, key, value) => {
-    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+/** Host JSON as program values: objects and arrays are copied, primitives pass through. */
+export const fromJson = (ctx, value) => {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return new Arr(ctx.builtins.Array, value.map((item) => fromJson(ctx, item)));
+    const copied = new Obj(ctx.builtins.Object);
+    for (const [key, item] of Object.entries(value))
+        define(copied, key, fromJson(ctx, item));
+    return copied;
 };

package/dist/extension.d.ts

@@ -0,0 +1,11 @@
+export * as Extension from "./extension.js";
+/**
+ * Host functions a program calls directly as globals. Values crossing in either direction are converted, never
+ * shared: arguments come in as copies, results go out as copies, and a function inside a result is callable the
+ * same way. Extension calls are not tool calls.
+ */
+export type Extension = {
+    readonly name: string;
+    readonly globals: Readonly<Record<string, Function>>;
+};
+export declare const make: (options: Extension) => Extension;

package/dist/extension.js

@@ -0,0 +1,9 @@
+export * as Extension from "./extension.js";
+export const make = (options) => {
+    for (const [name, value] of Object.entries(options.globals)) {
+        if (typeof value !== "function") {
+            throw new TypeError(`Extension "${options.name}" global "${name}" must be a function.`);
+        }
+    }
+    return { name: options.name, globals: { ...options.globals } };
+};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * as CodeMode from "./codemode.js";
+export * as Extension from "./extension.js";
 export * as Namespace from "./namespace.js";
 export * as Tool from "./tool.js";
 export * as OpenAPI from "./openapi/index.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * as CodeMode from "./codemode.js";
+export * as Extension from "./extension.js";
 export * as Namespace from "./namespace.js";
 export * as Tool from "./tool.js";
 export * as OpenAPI from "./openapi/index.js";

package/dist/interpreter/callback.d.ts

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import type { Interpreter } from "./interpreter.js";
+import { Callable } from "./objects.js";
+export type IteratorCursor<R> = {
+    readonly next: Effect.Effect<{
+        readonly done: boolean;
+        readonly value: unknown;
+    }, unknown, R>;
+    readonly close: Effect.Effect<void, unknown, R>;
+};
+export declare const preserveConsumerError: <A, R>(cursor: IteratorCursor<R>, effect: Effect.Effect<A, unknown, R>) => Effect.Effect<A, unknown, R>;
+/**
+ * ToPrimitive: calls `valueOf`/`toString` in hint order and returns the first primitive result. Dates treat the
+ * default hint as "string", like their `Symbol.toPrimitive`.
+ */
+export declare const toPrimitive: <R>(ctx: Interpreter<R>, value: unknown, hint: "number" | "string" | "default") => Effect.Effect<unknown, unknown, R>;
+export declare const toPrimitiveString: <R>(ctx: Interpreter<R>, value: unknown) => Effect.Effect<string, unknown, R>;
+export declare const toPrimitiveNumber: <R>(ctx: Interpreter<R>, value: unknown) => Effect.Effect<number, unknown, R>;
+export declare const isSupportedCallback: (value: unknown) => value is Callable;
+export declare const applyCollectionCallback: <R>(ctx: Interpreter<R>, callback: unknown, name: string) => ((args: Array<unknown>) => Effect.Effect<unknown, unknown, R>);

package/dist/interpreter/{runner.js → callback.js}

@@ -1,7 +1,7 @@
 import { Effect, Exit } from "effect";
 import { coerceToNumber, coerceToString } from "../stdlib/value.js";
-import { InterpreterRuntimeError } from "./model.js";
-import { Callable, get, NativeFunction, ProgramDate, ProgramObject, ProgramPromise } from "./objects.js";
+import { typeError } from "./model.js";
+import { Callable, get, Native, DateObj, Obj } from "./objects.js";
 import { typeofValue } from "./references.js";
 export const preserveConsumerError = (cursor, effect) => Effect.flatMap(Effect.exit(effect), (exit) => Exit.isSuccess(exit)
     ? Effect.succeed(exit.value)
@@ -10,36 +10,36 @@ export const preserveConsumerError = (cursor, effect) => Effect.flatMap(Effect.e
  * ToPrimitive: calls `valueOf`/`toString` in hint order and returns the first primitive result. Dates treat the
  * default hint as "string", like their `Symbol.toPrimitive`.
  */
-export const toPrimitive = (runner, value, hint, node) => {
-    if (!(value instanceof ProgramObject))
+export const toPrimitive = (ctx, value, hint) => {
+    if (!(value instanceof Obj))
         return Effect.succeed(value);
-    const asString = hint === "string" || (hint === "default" && value instanceof ProgramDate);
+    const asString = hint === "string" || (hint === "default" && value instanceof DateObj);
     const order = asString ? ["toString", "valueOf"] : ["valueOf", "toString"];
     return Effect.gen(function* () {
         for (const method of order) {
             const callable = get(value, method);
             if (!(callable instanceof Callable))
                 continue;
-            const result = yield* runner.invokeCallable(callable, value, [], node);
+            const result = yield* ctx.call(callable, value, []);
             if (result === null || (typeof result !== "object" && typeof result !== "function"))
                 return result;
         }
-        throw new InterpreterRuntimeError("Cannot convert object to primitive value.", node);
+        throw typeError("Cannot convert object to primitive value.");
     });
 };
-export const toPrimitiveString = (runner, value, node) => Effect.map(toPrimitive(runner, value, "string", node), coerceToString);
-export const toPrimitiveNumber = (runner, value, node) => Effect.map(toPrimitive(runner, value, "number", node), coerceToNumber);
+export const toPrimitiveString = (ctx, value) => Effect.map(toPrimitive(ctx, value, "string"), coerceToString);
+export const toPrimitiveNumber = (ctx, value) => Effect.map(toPrimitive(ctx, value, "number"), coerceToNumber);
 // The single acceptance list for callbacks: collections, sort, string replacers,
 // Array.from mappers, and promise reactions all admit exactly these callables.
 // Admission means dispatchable, not necessarily invocable: new-requiring
 // constructors pass the gate and throw a TypeError on call, like JS.
-export const isSupportedCallback = (value) => value instanceof Callable && !(value instanceof NativeFunction && !value.callback);
-export const applyCollectionCallback = (runner, callback, name, node) => {
+export const isSupportedCallback = (value) => value instanceof Callable && !(value instanceof Native && !value.callback);
+export const applyCollectionCallback = (ctx, callback, name) => {
     if (!isSupportedCallback(callback)) {
         if (typeofValue(callback) === "function") {
-            throw new InterpreterRuntimeError(`${name} cannot use this callable as a callback; wrap it in an arrow function, e.g. (value) => tools.ns.tool(value).`, node);
+            throw typeError(`${name} cannot use this callable as a callback; wrap it in an arrow function, e.g. (value) => tools.ns.tool(value).`);
         }
-        throw new InterpreterRuntimeError(`${name} expects a function callback.`, node);
+        throw typeError(`${name} expects a function callback.`);
     }
-    return (callbackArgs) => runner.invokeCallable(callback, undefined, callbackArgs, node);
+    return (callbackArgs) => ctx.call(callback, undefined, callbackArgs);
 };

package/dist/interpreter/errors.d.ts

@@ -1,9 +1,16 @@
 import type { Diagnostic } from "../codemode.js";
+import { type AstNode } from "./model.js";
 import { type ErrorType } from "./intrinsics.js";
-import { type NativeFunction, ProgramError, ProgramObject } from "./objects.js";
-import { type Runner } from "./runner.js";
+import { type Native, ErrorObj, Obj } from "./objects.js";
+import type { Interpreter } from "./interpreter.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, proto?: ProgramObject) => ProgramError;
+/**
+ * Gives a failure the source location of the expression that raised it, keeping the first one attached. Host errors
+ * that escape a built-in become the equivalent program error here.
+ */
+export declare const locate: (error: unknown, node?: AstNode) => unknown;
+/** The program value a handler receives for a failure; one failure always yields the same value. */
+export declare const materialize: <R>(ctx: Interpreter<R>, thrown: unknown) => unknown;
+export declare const createAggregateErrorValue: <R>(ctx: Interpreter<R>, errors: Array<unknown>, message: string, proto?: Obj) => ErrorObj;
 /** 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>) => NativeFunction<R>;
+export declare const errorGlobal: <R>(type: ErrorType, ctx: Interpreter<R>) => Native<R>;