@opencode/codemode 0.0.0-beta-19296 → 0.0.0-beta-19365

package/README.md

@@ -91,6 +91,12 @@ 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

package/dist/codemode.d.ts

@@ -25,23 +25,20 @@ export type ResolvedExecutionLimits = {
     readonly maxToolCalls: number | undefined;
     readonly maxOutputBytes: number | undefined;
 };
-/** Options for one CodeMode execution. */
-export type ExecuteOptions<Provided extends Record<string, unknown> = {}> = {
-    /** Source for one program in the supported JavaScript subset. */
-    code: string;
+/** 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>>;
-    /** Per-execution overrides for the default resource limits. */
+    /** Resource limits enforced on each execution. */
     limits?: ExecutionLimits;
-    /** Observes decoded tool input immediately before tool execution. */
-    onToolCallStart?: (call: ToolRuntime.ToolCallStarted) => Effect.Effect<void, never, Services<Provided>>;
-    /** Observes each admitted tool call as it succeeds, fails, or is interrupted. */
-    onToolCallEnd?: (call: ToolRuntime.ToolCallEnded) => Effect.Effect<void, never, Services<Provided>>;
+};
+/** 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;
-/** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */
-export type Options<Provided extends Record<string, unknown> = {}> = Omit<ExecuteOptions<Provided>, "code">;
 /** Schema for a host tool input containing CodeMode source. */
 export declare const Input: Schema.Struct<{
     readonly code: Schema.String;

package/dist/codemode.js

@@ -1,5 +1,5 @@
 import { Effect, Schema } from "effect";
-import { executeWithLimits } from "./interpreter/execute.js";
+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";
@@ -54,17 +54,13 @@ const resolveExecutionLimits = (limits) => ({
     maxOutputBytes: validateLimit("maxOutputBytes", limits?.maxOutputBytes, 0),
 });
 /** Executes one Effect-native CodeMode program without constructing a reusable runtime. */
-export const execute = (options) => {
-    const tools = (options.tools ?? {});
-    return executeWithLimits(options, resolveExecutionLimits(options.limits), ToolRuntime.searchIndex(tools));
-};
+export const execute = (options) => make(options).execute(options.code);
 /** Creates an Effect-native runtime over explicit, schema-described tools. */
 export const make = (options = {}) => {
-    const tools = (options.tools ?? {});
+    const prepared = ToolRuntime.prepare((options.tools ?? {}));
     const limits = resolveExecutionLimits(options.limits);
-    const prepared = ToolRuntime.prepare(tools);
     return {
         catalog: () => prepared.catalog,
-        execute: (code) => executeWithLimits({ ...options, code }, limits, prepared.searchIndex),
+        execute: (code) => executeProgram(code, prepared, limits, options),
     };
 };

package/dist/data.d.ts

@@ -0,0 +1,28 @@
+export * as Data from "./data.js";
+import type { DiagnosticKind } from "./codemode.js";
+/** A null-prototype object owned by the program. */
+export type SafeObject = Record<string, unknown>;
+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>);
+}
+export declare const isBlockedMember: (name: string) => boolean;
+/**
+ * Brings a host-produced runtime value into the program: runtime values pass through, their host
+ * counterparts (Date, RegExp, Map, Set, URL, URLSearchParams) are wrapped, and objects become
+ * null-prototype copies. Arrays keep extra enumerable properties such as `index` and `groups`.
+ */
+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 null-prototype 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,130 @@
+export * as Data from "./data.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";
+    }
+}
+const blockedMemberNames = new Set(["__proto__", "constructor", "prototype"]);
+export const isBlockedMember = (name) => blockedMemberNames.has(name);
+/**
+ * Brings a host-produced runtime value into the program: runtime values pass through, their host
+ * counterparts (Date, RegExp, Map, Set, URL, URLSearchParams) are wrapped, and objects become
+ * null-prototype copies. Arrays keep extra enumerable properties such as `index` and `groups`.
+ */
+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 null-prototype 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 (mode === "program") {
+        if (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));
+    }
+    const plain = mode === "program" || mode === "data";
+    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 ? Object.create(null) : {};
+    }
+    if (seen.has(value)) {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} contains a circular value.`);
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        // Host output densifies holes to null like JSON; program copies keep them.
+        const copied = plain
+            ? value.map((item) => copy(item, label, mode, depth + 1, seen))
+            : Array.from(value, (item) => copy(item, label, mode, depth + 1, seen) ?? null);
+        if (mode === "program") {
+            for (const [key, item] of Object.entries(value)) {
+                if (Object.hasOwn(copied, key))
+                    continue;
+                if (isBlockedMember(key)) {
+                    throw new ToolRuntimeError("InvalidDataValue", `${label} contains blocked property '${key}'.`);
+                }
+                Reflect.set(copied, key, copy(item, label, mode, depth + 1, seen));
+            }
+        }
+        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.`);
+    }
+    const copied = plain ? Object.create(null) : {};
+    for (const [key, item] of Object.entries(value)) {
+        if (isBlockedMember(key)) {
+            throw new ToolRuntimeError("InvalidDataValue", `${label} contains blocked property '${key}'.`);
+        }
+        const next = copy(item, label, mode, depth + 1, seen);
+        if (next === undefined && mode === "json")
+            continue;
+        copied[key] = next;
+    }
+    seen.delete(value);
+    return copied;
+};

package/dist/index.d.ts

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

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

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
 import type { Diagnostic } from "../codemode.js";
-import { type SafeObject } from "../tool-runtime.js";
+import { type SafeObject } from "../data.js";
 import { type AstNode } from "./model.js";
 import { type SyncIteratorRunner } from "./iterator.js";
 export declare const normalizeError: (error: unknown) => Diagnostic;

package/dist/interpreter/errors.js

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
 import { ToolError } from "../tool-error.js";
-import { copyOut, ToolRuntimeError } from "../tool-runtime.js";
+import { toData, ToolRuntimeError } from "../data.js";
 import { formatLocation, InterpreterRuntimeError, ProgramThrow, sourceLocation } from "./model.js";
 import { containsRuntimeReference } from "./references.js";
 import {} from "./iterator.js";
@@ -41,7 +41,7 @@ export const normalizeError = (error) => {
         }
         else {
             try {
-                message = JSON.stringify(copyOut(value, "json")) ?? String(value);
+                message = JSON.stringify(toData(value, "Thrown value")) ?? String(value);
             }
             catch {
                 message = String(value);

package/dist/interpreter/execute.d.ts

@@ -1,4 +1,4 @@
 import { Effect } from "effect";
-import type { ExecuteOptions, ResolvedExecutionLimits, Result } from "../codemode.js";
-import { ToolRuntime, type Services } from "../tool-runtime.js";
-export declare const executeWithLimits: <const Provided extends Record<string, unknown>>(options: ExecuteOptions<Provided>, limits: ResolvedExecutionLimits, searchIndex: ToolRuntime.DiscoveryPlan["searchIndex"]) => Effect.Effect<Result, never, Services<Provided>>;
+import type { ResolvedExecutionLimits, Result } from "../codemode.js";
+import { ToolRuntime } from "../tool-runtime.js";
+export declare const executeProgram: <R>(code: string, prepared: ToolRuntime.Prepared<R>, limits: ResolvedExecutionLimits, hooks: ToolRuntime.ToolCallHooks<R>) => Effect.Effect<Result, never, R>;

package/dist/interpreter/execute.js

@@ -3,13 +3,14 @@ import { Cause, Effect, Scope } from "effect";
 // #transpile: conditional import — full typescript on node/bun, an identity
 // pass-through on workerd (the compiler is ~11 MiB and can't init there).
 import { transpile } from "#transpile";
-import { copyIn, copyOut, ToolRuntime } from "../tool-runtime.js";
+import { toData } from "../data.js";
+import { ToolRuntime } from "../tool-runtime.js";
 import { normalizeError } from "./errors.js";
-import { InterpreterRuntimeError, isRecord } from "./model.js";
+import { InterpreterRuntimeError } from "./model.js";
 import { PromiseRuntime } from "./promises.js";
 import { Interpreter } from "./runtime.js";
-export const executeWithLimits = (options, limits, searchIndex) => {
-    if (options.code.trim().length === 0) {
+export const executeProgram = (code, prepared, limits, hooks) => {
+    if (code.trim().length === 0) {
         return Effect.succeed({
             ok: false,
             error: { kind: "ParseError", message: "Code cannot be empty." },
@@ -18,20 +19,17 @@ export const executeWithLimits = (options, limits, searchIndex) => {
     }
     // Allocate execution state inside suspension so reused Effects never share it.
     return Effect.suspend(() => {
-        const tools = ToolRuntime.make((options.tools ?? {}), limits.maxToolCalls, searchIndex, {
-            onToolCallStart: options.onToolCallStart,
-            onToolCallEnd: options.onToolCallEnd,
-        });
+        const tools = ToolRuntime.make(prepared, limits.maxToolCalls, hooks);
         const logs = [];
         const logged = () => (logs.length > 0 ? { logs: [...logs] } : {});
         // Set only after copy-out so timeouts cannot report invalid values as completed.
         let returned;
         const base = Effect.acquireUseRelease(Scope.make("parallel"), (scope) => Effect.gen(function* () {
-            const program = parseProgram(options.code);
+            const program = parseProgram(code);
             const promises = new PromiseRuntime(scope);
             const interpreter = new Interpreter(tools.execute, tools.search, tools.keys, promises, logs);
             const value = yield* interpreter.run(program);
-            const result = copyOut(copyIn(value, "Execution result"), "nullify");
+            const result = toData(value, "Execution result", "result");
             returned = { value: result, promises };
             const warnings = yield* promises.interrupt();
             return {
@@ -90,17 +88,13 @@ const parseProgram = (code) => {
     const bodyStart = transpiled.outputText.indexOf("{") + 1;
     const bodyEnd = transpiled.outputText.lastIndexOf("}");
     const executableCode = transpiled.outputText.slice(bodyStart, bodyEnd);
-    const parsed = parse(executableCode, {
+    return parse(executableCode, {
         ecmaVersion: "latest",
         sourceType: "script",
         allowReturnOutsideFunction: true,
         allowAwaitOutsideFunction: true,
         locations: true,
     });
-    if (!isRecord(parsed) || parsed.type !== "Program" || !Array.isArray(parsed.body)) {
-        throw new InterpreterRuntimeError("Failed to parse script as a Program node.");
-    }
-    return parsed;
 };
 const utf8ByteLength = (value) => new TextEncoder().encode(value).byteLength;
 // Drop a replacement character produced by truncating inside a UTF-8 sequence.

package/dist/interpreter/methods.d.ts

@@ -1,15 +1,22 @@
 import { Effect } from "effect";
 import { type AstNode, CodeModeFunction, CoercionFunction, ErrorConstructorReference, GlobalMethodReference, GlobalNamespace, IntrinsicReference, JsonMethodReference, PromiseCapabilityFunction, PromiseNamespace, UriFunction } from "./model.js";
-import { CodeModePromise } from "../values.js";
+import { Values } from "../values.js";
 import { type SyncIteratorRunner } from "./iterator.js";
 export type CallbackRunner<R> = {
     readonly invokeFunction: (fn: CodeModeFunction, args: Array<unknown>) => Effect.Effect<unknown, unknown, R>;
     readonly invokeCallable: (callable: unknown, args: Array<unknown>, node: AstNode) => Effect.Effect<unknown, unknown, R>;
-    readonly settlePromise: (promise: CodeModePromise) => Effect.Effect<unknown, unknown, never>;
+    readonly settlePromise: (promise: Values.Promise) => Effect.Effect<unknown, unknown, never>;
 };
 export type SupportedCallback = CodeModeFunction | CoercionFunction | UriFunction | PromiseCapabilityFunction | GlobalMethodReference | JsonMethodReference | IntrinsicReference | ErrorConstructorReference | GlobalNamespace | PromiseNamespace;
 export declare const isSupportedCallback: (value: unknown) => value is SupportedCallback;
 export declare const invokeIntrinsic: <R>(runner: CallbackRunner<R>, ref: IntrinsicReference, args: Array<unknown>, node: AstNode) => Effect.Effect<unknown, unknown, R>;
+/**
+ * ToPrimitive: tries an object's own `valueOf`/`toString` in hint order and returns the first
+ * primitive result. Runtime values behave like their JS counterparts (Date yields its time under a
+ * number hint; the rest yield their string form). An inherited `toString` yields the default
+ * string form, so plain objects become "[object Object]" and arrays join.
+ */
+export declare const toPrimitive: <R>(runner: CallbackRunner<R>, value: unknown, hint: "number" | "string", node: AstNode) => Effect.Effect<unknown, unknown, R>;
 export declare const invokeGlobalMethod: (ref: GlobalMethodReference, args: Array<unknown>, node: AstNode) => unknown;
 export declare const arrayStatics: Set<string>;
 export declare const invokeArrayFrom: <R>(runner: CallbackRunner<R> & SyncIteratorRunner<R>, args: Array<unknown>, node: AstNode) => Effect.Effect<unknown, unknown, R>;