@opencode/codemode 0.0.0-dev-19673 → 0.0.0-dev-19676

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

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

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,5 +1,6 @@
 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";
@@ -115,23 +116,27 @@ 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 }))]));
 };
 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;
@@ -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));
@@ -193,26 +206,10 @@ 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 +224,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,10 +241,11 @@ 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)),
         execute: (path, args) => Effect.suspend(() => {

package/package.json

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