@opencode/codemode 2.0.4 → 2.0.6

package/README.md

@@ -88,8 +88,11 @@ 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.
+The Effect environment is inferred from the supplied tools. `hooks` surround every call the program makes into the
+host: `tool.before`/`tool.after` receive `{ name, input }` with decoded input, `extension.before`/`extension.after`
+receive `{ extension, name, args }`. An `after` hook also receives how the call ended (`success` with its value,
+`failure` with its error, or `interrupted`). A failing `before` hook denies the call, and the program catches the
+failure as a thrown error.
 
 ### `Values`
 

package/dist/codemode.d.ts

@@ -3,7 +3,7 @@ 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. */
-export type { ToolCall, ToolCallEnded, ToolCallHooks, ToolCallStarted, ToolDescription } from "./tool-runtime.js";
+export type { CallResult, ExtensionInvocation, Hooks, ToolCall, ToolDescription, ToolInvocation, } 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. */
@@ -27,9 +27,11 @@ export type ResolvedExecutionLimits = {
     readonly maxOutputBytes: number | undefined;
 };
 /** Configuration shared by `CodeMode.make` and `CodeMode.execute`. */
-export type Options<Provided extends Record<string, unknown> = {}> = ToolRuntime.ToolCallHooks<Services<Provided>> & {
+export type Options<Provided extends Record<string, unknown> = {}> = {
     /** Explicit tools exposed to the program as `tools`. */
     tools?: Provided & Tools<Services<Provided>>;
+    /** Hooks around every tool and extension call the program makes; see `Hooks`. */
+    hooks?: ToolRuntime.Hooks<Services<Provided>>;
     /** Host functions exposed as globals; see `Extension.make`. */
     extensions?: ReadonlyArray<Extension>;
     /** Resource limits enforced on each execution. */

package/dist/codemode.js

@@ -71,7 +71,9 @@ export const make = (options = {}) => {
         }
     }
     return {
-        catalog: prepared.catalog,
-        execute: (code) => executeProgram(code, prepared, limits, options, (ctx) => extensionGlobals(ctx, extensions)),
+        get catalog() {
+            return prepared.catalog;
+        },
+        execute: (code) => executeProgram(code, prepared, limits, options.hooks ?? {}, (ctx) => extensionGlobals(ctx, extensions)),
     };
 };

package/dist/interpreter/errors.js

@@ -5,7 +5,7 @@ import { formatLocation, PendingThrow, Throw, sourceLocation, typeError } from "
 import { containsRuntimeReference } from "./references.js";
 import { createErrorValue, isErrorType } from "./intrinsics.js";
 import { constructor, methods, prototypeFrom, receiver } from "./native.js";
-import { define, get, hidden, Arr, ErrorObj, Obj } from "./objects.js";
+import { define, get, has, hidden, Arr, ErrorObj, Obj } from "./objects.js";
 import { formatValue } from "../stdlib/console.js";
 import { coerceToString } from "../stdlib/value.js";
 export const normalizeError = (error) => {
@@ -128,9 +128,17 @@ export const errorGlobal = (type, ctx) => {
     const prototype = builtins[type];
     const construct = (args, newTarget) => {
         const proto = prototypeFrom(newTarget, prototype);
-        return type === "AggregateError"
+        const created = type === "AggregateError"
             ? constructAggregateErrorValue(ctx, args, proto)
             : Effect.sync(() => createErrorValue(proto, args[0] === undefined ? undefined : coerceToString(args[0])));
+        // ES2022 `new Error(message, { cause })`: installed only when the options object has the property at all.
+        const options = args[type === "AggregateError" ? 2 : 1];
+        if (!(options instanceof Obj) || !has(options, "cause"))
+            return created;
+        return Effect.map(created, (value) => {
+            define(value, "cause", get(options, "cause"), hidden);
+            return value;
+        });
     };
     const ctor = constructor(builtins, prototype, {
         name: type,

package/dist/interpreter/execute.d.ts

@@ -2,4 +2,4 @@ import { Effect } from "effect";
 import type { ResolvedExecutionLimits, Result } from "../codemode.js";
 import { ToolRuntime } from "../tool-runtime.js";
 import { Interpreter } from "./interpreter.js";
-export declare const executeProgram: <R>(code: string, prepared: ToolRuntime.Prepared<R>, limits: ResolvedExecutionLimits, hooks: ToolRuntime.ToolCallHooks<R>, globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, unknown]>) => Effect.Effect<Result, never, R>;
+export declare const executeProgram: <R>(code: string, prepared: ToolRuntime.Prepared<R>, limits: ResolvedExecutionLimits, hooks: ToolRuntime.Hooks<R>, globals?: (ctx: Interpreter<R>) => ReadonlyArray<readonly [string, unknown]>) => Effect.Effect<Result, never, R>;

package/dist/interpreter/extensions.js

@@ -1,10 +1,11 @@
 import { Effect } from "effect";
 import { coerceToString } from "../stdlib/value.js";
+import { hooked } from "../tool-runtime.js";
 import { createErrorValue, isErrorType } from "./intrinsics.js";
 import { MAX_VALUE_DEPTH } from "./limits.js";
-import { Throw, typeError } from "./model.js";
+import { PendingThrow, Throw, typeError } from "./model.js";
 import { fn } from "./native.js";
-import { Callable, define, entries, get, Arr, Bytes, DateObj, ErrorObj, GeneratorObj, MapObj, Obj, PromiseObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, } from "./objects.js";
+import { Callable, define, entries, get, has, hidden, keys, Arr, Bytes, DateObj, ErrorObj, GeneratorObj, MapObj, Obj, PromiseObj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, } from "./objects.js";
 import { describeValue } from "./references.js";
 /**
  * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and
@@ -42,15 +43,30 @@ export const extensionGlobals = (ctx, extensions) => {
             value instanceof PromiseObj) {
             throw typeError(`${label} contains ${describeValue(value)}, which cannot be passed to an extension.`);
         }
+        if (seen.has(value))
+            throw typeError(`${label} contains a circular value.`);
+        seen.add(value);
         if (value instanceof ErrorObj) {
             const name = coerceToString(get(value, "name"));
             const message = get(value, "message");
             const text = message === undefined ? "" : coerceToString(message);
-            return name === "AggregateError" ? new AggregateError([], text) : new (hostErrors.get(name) ?? Error)(text);
+            const copied = name === "AggregateError" ? new AggregateError([], text) : new (hostErrors.get(name) ?? Error)(text);
+            for (const key of new Set(["cause", ...keys(value)])) {
+                if (uncrossed.has(key) || !has(value, key))
+                    continue;
+                const item = crossing(() => next(get(value, key)));
+                if (item === left)
+                    continue;
+                Object.defineProperty(copied, key, {
+                    value: item,
+                    writable: true,
+                    configurable: true,
+                    enumerable: key !== "cause",
+                });
+            }
+            seen.delete(value);
+            return copied;
         }
-        if (seen.has(value))
-            throw typeError(`${label} contains a circular value.`);
-        seen.add(value);
         const copied = value instanceof Arr
             ? value.items.map(next)
             : Object.fromEntries(entries(value)
@@ -67,6 +83,7 @@ export const extensionGlobals = (ctx, extensions) => {
         if (typeof value === "function")
             return wrap(value, label);
         if (value !== null && typeof value === "object") {
+            const next = (item, path) => fromHost(item, path, depth + 1, seen);
             if (value instanceof Date)
                 return new DateObj(builtins.Date, value.getTime());
             if (value instanceof RegExp)
@@ -76,14 +93,27 @@ export const extensionGlobals = (ctx, extensions) => {
             if (value instanceof ArrayBuffer)
                 return new Bytes(builtins.Uint8Array, new Uint8Array(value.slice(0)));
             if (value instanceof Error) {
-                return createErrorValue(builtins[isErrorType(value.name) ? value.name : "Error"], value.message);
+                if (seen.has(value))
+                    throw typeError(`${label} produced a circular value.`);
+                seen.add(value);
+                const copied = createErrorValue(builtins[isErrorType(value.name) ? value.name : "Error"], value.message);
+                const fields = value;
+                for (const key of new Set(["cause", ...Object.keys(value)])) {
+                    if (uncrossed.has(key) || !(key in value) || typeof fields[key] === "function")
+                        continue;
+                    const item = crossing(() => next(fields[key], `${label}.${key}`));
+                    if (item === left)
+                        continue;
+                    define(copied, key, item, key === "cause" ? hidden : undefined);
+                }
+                seen.delete(value);
+                return copied;
             }
             if (value instanceof URL)
                 return new URLObj(builtins.URL, builtins.URLSearchParams, new URL(value.href));
             if (value instanceof URLSearchParams) {
                 return new URLSearchParamsObj(builtins.URLSearchParams, new URLSearchParams(value));
             }
-            const next = (item, path) => fromHost(item, path, depth + 1, seen);
             if (value instanceof Map) {
                 const wrapped = new MapObj(builtins.Map);
                 for (const [key, item] of value)
@@ -115,23 +145,44 @@ export const extensionGlobals = (ctx, extensions) => {
         }
         throw typeError(`${label} produced ${describeHost(value)}, which the program cannot hold.`);
     };
-    // A host function as a program function: arguments cross in, and whatever it returns, resolves, throws, or
-    // rejects with crosses out, so the program catches what the author threw.
-    const wrap = (value, label) => fn(builtins, value.name, value.length, (_, values) => {
-        const converted = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`));
-        const thrown = (reason) => new Throw(fromHost(reason, label));
+    // A host function as a program function. Arguments cross in; a global's call runs inside the host's extension
+    // hooks, which see the host's own error on failure; then whatever came back, or was thrown, crosses out so the
+    // program catches a copy. Functions inside results are part of a value's API and skip the hooks.
+    const wrap = (value, label, describe) => fn(builtins, value.name, value.length, (_, values) => {
+        const args = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`));
+        const hooks = ctx.tools.hooks;
+        const settle = (run) => (describe === undefined
+            ? run
+            : hooked(describe(args), hooks["extension.before"], hooks["extension.after"], run)).pipe(Effect.mapError((reason) => new Throw(fromHost(reason, label))), Effect.map((settled) => fromHost(settled, label)));
         let result;
         try {
-            result = value.apply(undefined, converted);
+            result = value.apply(undefined, args);
         }
         catch (reason) {
-            return Effect.fail(thrown(reason));
+            return settle(Effect.fail(reason));
         }
         if (!(result instanceof Promise))
-            return fromHost(result, label);
-        return ctx.pending.create(Effect.map(Effect.tryPromise({ try: () => result, catch: thrown }), (settled) => fromHost(settled, label)));
+            return settle(Effect.succeed(result));
+        return ctx.pending.create(settle(Effect.tryPromise({ try: () => result, catch: (reason) => reason })));
     });
-    return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [name, wrap(value, name)]));
+    return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [name, wrap(value, name, (args) => ({ extension: extension.name, name, args }))]));
+};
+/**
+ * An error crosses as its name, message, `cause`, and own enumerable fields, such as Node's `code`, `errno`,
+ * `syscall`, and `path`. `stack` stays on its own side, and no field may shadow an Error method. A field that cannot
+ * cross (a socket, a handle, a function) is left behind so the error itself always arrives.
+ */
+const uncrossed = new Set(["stack", "constructor", "toString", "__proto__"]);
+const left = Symbol("left behind");
+const crossing = (convert) => {
+    try {
+        return convert();
+    }
+    catch (reason) {
+        if (reason instanceof PendingThrow)
+            return left;
+        throw reason;
+    }
 };
 const hostErrors = new Map([
     ["TypeError", TypeError],

package/dist/tool-runtime.d.ts

@@ -13,25 +13,36 @@ type ServicesOf<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] exten
 export type ToolCall = {
     readonly name: string;
 };
-export type ToolCallStarted = {
-    readonly index: number;
+/** A tool call the program is making, with its decoded input. */
+export type ToolInvocation = {
     readonly name: string;
     readonly input: unknown;
 };
-export type ToolCallEnded = {
-    readonly index: number;
+/** A call the program is making to an extension global, with its arguments. */
+export type ExtensionInvocation = {
+    readonly extension: string;
     readonly name: string;
-    readonly input: unknown;
-    readonly durationMs: number;
-    readonly outcome: "success" | "failure" | "interrupted";
-    readonly message?: string;
+    readonly args: ReadonlyArray<unknown>;
+};
+/** How a call ended; `after` hooks observe it and cannot change it. */
+export type CallResult = {
+    readonly status: "success";
+    readonly value: unknown;
+} | {
+    readonly status: "failure";
+    readonly error: unknown;
+} | {
+    readonly status: "interrupted";
 };
-export type ToolCallHooks<R = never> = {
-    /** Observes decoded tool input immediately before tool execution. */
-    readonly onToolCallStart?: ((call: ToolCallStarted) => Effect.Effect<void, never, R>) | undefined;
-    /** Observes each admitted tool call as it succeeds, fails, or is interrupted. */
-    readonly onToolCallEnd?: ((call: ToolCallEnded) => Effect.Effect<void, never, R>) | undefined;
+/** Hooks around every call the program makes into the host. A failing `before` denies the call. */
+export type Hooks<R = never> = {
+    readonly "tool.before"?: ((call: ToolInvocation) => Effect.Effect<void, unknown, R>) | undefined;
+    readonly "tool.after"?: ((call: ToolInvocation, result: CallResult) => Effect.Effect<void, never, R>) | undefined;
+    readonly "extension.before"?: ((call: ExtensionInvocation) => Effect.Effect<void, unknown, R>) | undefined;
+    readonly "extension.after"?: ((call: ExtensionInvocation, result: CallResult) => Effect.Effect<void, never, R>) | undefined;
 };
+/** Runs `before`, then `run`, then `after` with how it ended, including when interrupted. */
+export declare const hooked: <Call, A, R>(call: Call, before: ((call: Call) => Effect.Effect<void, unknown, R>) | undefined, after: ((call: Call, result: CallResult) => Effect.Effect<void, never, R>) | undefined, run: Effect.Effect<A, unknown, R>) => Effect.Effect<A, unknown, R>;
 export type ToolDescription = {
     readonly path: string;
     readonly description: string;
@@ -47,7 +58,7 @@ type ToolNode<R> = {
     namespace?: Namespace<R>;
     readonly children: Map<string, ToolNode<R>>;
 };
-/** Tools indexed once per runtime: the lookup trie plus the model-facing catalog and search index. */
+/** Tools indexed once per runtime, with discovery materialized on demand. */
 export type Prepared<R = never> = {
     readonly root: ToolNode<R>;
     readonly catalog: ReadonlyArray<ToolDescription>;
@@ -68,10 +79,11 @@ export declare class ToolRuntimeError extends Error {
 /** The tool bridge of one execution. Arguments arrive and results leave as JSON; program values never enter. */
 export type ToolRuntime<R = never> = {
     readonly calls: Array<ToolCall>;
+    readonly hooks: Hooks<R>;
     readonly execute: (path: ReadonlyArray<string>, args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>;
     readonly search: (args: Array<Json | undefined>) => Effect.Effect<Json | undefined, unknown, R>;
     readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>;
 };
 /** Per-execution call state over tools prepared once for the runtime. */
-export declare const make: <R>(prepared: Prepared<R>, maxToolCalls: number | undefined, hooks?: ToolCallHooks<R>) => ToolRuntime<R>;
+export declare const make: <R>(prepared: Prepared<R>, maxToolCalls: number | undefined, hooks?: Hooks<R>) => ToolRuntime<R>;
 export * as ToolRuntime from "./tool-runtime.js";

package/dist/tool-runtime.js

@@ -4,6 +4,19 @@ import { decodeInput as decodeToolInput, decodeOutput as decodeToolOutput, ident
 import { isNamespace } from "./namespace.js";
 import { isTool } from "./tool.js";
 export const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+/** Runs `before`, then `run`, then `after` with how it ended, including when interrupted. */
+export const hooked = (call, before, after, run) => {
+    const observed = after === undefined
+        ? run
+        : Effect.onExit(run, (exit) => {
+            if (Exit.isSuccess(exit))
+                return after(call, { status: "success", value: exit.value });
+            if (Cause.hasInterruptsOnly(exit.cause))
+                return after(call, { status: "interrupted" });
+            return after(call, { status: "failure", error: Cause.squash(exit.cause) });
+        });
+    return before === undefined ? observed : Effect.andThen(before(call), observed);
+};
 const defaultSearchLimit = 10;
 const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
 const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
@@ -67,13 +80,22 @@ const flattenTools = (node, path = [], namespaces = []) => {
         ...Array.from(node.children).flatMap(([name, child]) => flattenTools(child, [...path, name], next)),
     ];
 };
-const describeTool = (visible) => ({
-    path: visible.path,
-    description: visible.tool.description,
-    signature: isEmptyInput(visible.tool)
-        ? `${toolExpression(visible.path)}(): Promise<${outputTypeScript(visible.tool, true)}>`
-        : `${toolExpression(visible.path)}(input: ${inputTypeScript(visible.tool, true)}): Promise<${outputTypeScript(visible.tool, true)}>`,
-});
+const describeTool = (visible) => {
+    let signature;
+    return {
+        path: visible.path,
+        description: visible.tool.description,
+        get signature() {
+            // Search ranks paths and descriptions first; only returned matches need their schemas rendered.
+            // Joining the final fragments avoids retaining the rendering's intermediate string ropes in JSC.
+            return (signature ??= [
+                toolExpression(visible.path),
+                isEmptyInput(visible.tool) ? "()" : `(input: ${inputTypeScript(visible.tool, true)})`,
+                `: Promise<${outputTypeScript(visible.tool, true)}>`,
+            ].join(""));
+        },
+    };
+};
 const tokenize = (query) => query
     .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
     .toLowerCase()
@@ -152,12 +174,20 @@ const toSearchEntry = (visible) => ({
 });
 export const prepare = (tools) => {
     const root = toolTrie(tools);
-    // Discovery bytes are durable instructions, so order only after canonical-path collisions settle.
-    const visible = flattenTools(root).sort((left, right) => compareText(left.path, right.path));
+    let searchIndex;
+    let catalog;
     return {
         root,
-        catalog: visible.map(describeTool),
-        searchIndex: visible.map(toSearchEntry),
+        get catalog() {
+            return (catalog ??= this.searchIndex.map((entry) => entry.description));
+        },
+        get searchIndex() {
+            // Executing known tools only needs the trie. Render discovery when it is actually read,
+            // ordering after canonical-path collisions settle so instruction bytes stay deterministic.
+            return (searchIndex ??= flattenTools(root)
+                .sort((left, right) => compareText(left.path, right.path))
+                .map(toSearchEntry));
+        },
     };
 };
 const lookup = (root, segments) => segments.reduce((node, segment) => node?.children.get(segment), root);
@@ -193,26 +223,9 @@ export class ToolRuntimeError extends Error {
     }
 }
 /** Per-execution call state over tools prepared once for the runtime. */
-export const make = (prepared, maxToolCalls, hooks) => {
+export const make = (prepared, maxToolCalls, hooks = {}) => {
     const calls = [];
     const root = prepared.root;
-    const searchTool = makeSearchTool(prepared.searchIndex);
-    const observeEnd = (effect, call) => {
-        const onEnd = hooks?.onToolCallEnd;
-        if (onEnd === undefined)
-            return effect;
-        const startedAt = Date.now();
-        return effect.pipe(Effect.onExit((exit) => {
-            const durationMs = Date.now() - startedAt;
-            if (Exit.isSuccess(exit))
-                return onEnd({ ...call, durationMs, outcome: "success" });
-            if (Cause.hasInterruptsOnly(exit.cause))
-                return onEnd({ ...call, durationMs, outcome: "interrupted" });
-            const error = Cause.squash(exit.cause);
-            const message = error instanceof Error ? error.message : Cause.pretty(exit.cause);
-            return onEnd({ ...call, durationMs, outcome: "failure", message });
-        }));
-    };
     const recordCall = (call) => {
         if (maxToolCalls !== undefined && calls.length >= maxToolCalls) {
             throw new ToolRuntimeError("ToolCallLimitExceeded", `Execution exceeded its tool-call limit of ${maxToolCalls}.`);
@@ -227,14 +240,8 @@ export const make = (prepared, maxToolCalls, hooks) => {
             try: () => decodeToolInput(tool, normalized[0]),
             catch: (cause) => new ToolRuntimeError("InvalidToolInput", `Invalid input for tool '${name}': ${String(cause)}`, name === "search" ? [] : ["The signature may have changed. Use search to get the current signature."]),
         });
-        const index = yield* Effect.sync(() => {
-            recordCall({ name });
-            return calls.length - 1;
-        });
-        const call = { index, name, input };
-        return yield* observeEnd(Effect.gen(function* () {
-            if (hooks?.onToolCallStart !== undefined)
-                yield* hooks.onToolCallStart(call);
+        yield* Effect.sync(() => recordCall({ name }));
+        return yield* hooked({ name, input }, hooks["tool.before"], hooks["tool.after"], Effect.gen(function* () {
             const raw = yield* Effect.suspend(() => tool.execute(input)).pipe(Effect.catchCause((cause) => {
                 if (Cause.hasInterruptsOnly(cause))
                     return Effect.interrupt;
@@ -250,17 +257,18 @@ export const make = (prepared, maxToolCalls, hooks) => {
                 },
                 catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
             });
-        }), call);
+        }));
     });
     return {
         calls,
+        hooks,
         keys: (path) => namespaceKeys(root, path),
-        search: (args) => Effect.suspend(() => executeTool("search", searchTool, args)),
+        search: (args) => Effect.suspend(() => executeTool("search", makeSearchTool(prepared.searchIndex), args)),
         execute: (path, args) => Effect.suspend(() => {
             const segments = canonicalSegments(path);
             // Models often write `tools.search(...)` for the bare `search(...)`; honor it unless a tool owns that path.
             if (segments.length === 1 && segments[0] === "search" && lookup(root, segments) === undefined)
-                return executeTool("search", searchTool, args);
+                return executeTool("search", makeSearchTool(prepared.searchIndex), args);
             return executeTool(segments.join("."), resolve(root, path), args);
         }),
     };

package/package.json

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