@opencode/codemode 0.0.0-beta-19275

package/dist/stdlib/value.js

@@ -0,0 +1,120 @@
+export const errorConstructors = new Set([
+    "Error",
+    "TypeError",
+    "RangeError",
+    "SyntaxError",
+    "ReferenceError",
+    "EvalError",
+    "URIError",
+    "AggregateError",
+]);
+export const valueConstructors = new Set(["Date", "RegExp", "Map", "Set", "URL", "URLSearchParams"]);
+export const compoundOperators = new Set(["+=", "-=", "*=", "/=", "%=", "**=", "&=", "|=", "^=", "<<=", ">>=", ">>>="]);
+const ErrorBrand = Symbol("codemode.error");
+export const createErrorValue = (name, message) => {
+    const value = Object.assign(Object.create(null), { name, message });
+    Object.defineProperty(value, ErrorBrand, { value: name });
+    return value;
+};
+export const createAggregateErrorValue = (errors, message) => Object.assign(createErrorValue("AggregateError", message), { errors });
+export const errorBrandName = (value) => value !== null && typeof value === "object"
+    ? value[ErrorBrand]
+    : undefined;
+export const boundedData = (value, label) => copyIn(value, label, true);
+export const coerceToString = (value) => {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (value instanceof CodeModeDate)
+        return Number.isFinite(value.time) ? new Date(value.time).toISOString() : "Invalid Date";
+    if (value instanceof CodeModeRegExp)
+        return `/${value.regex.source}/${value.regex.flags}`;
+    if (value instanceof CodeModeMap)
+        return "[object Map]";
+    if (value instanceof CodeModeSet)
+        return "[object Set]";
+    if (value instanceof CodeModeURL)
+        return value.url.href;
+    if (value instanceof CodeModeURLSearchParams)
+        return value.params.toString();
+    if (errorBrandName(value) !== undefined) {
+        // Match Error.prototype.toString: "name: message", or just one when the other is empty.
+        const error = value;
+        const name = typeof error.name === "string" ? error.name : "Error";
+        const message = typeof error.message === "string" ? error.message : "";
+        if (message === "")
+            return name;
+        if (name === "")
+            return message;
+        return `${name}: ${message}`;
+    }
+    if (typeof value === "object") {
+        return Array.isArray(value)
+            ? value.map((item) => (item === null || item === undefined ? "" : coerceToString(item))).join(",")
+            : "[object Object]";
+    }
+    return String(value);
+};
+export const coerceToNumber = (value) => {
+    if (value instanceof CodeModeDate)
+        return value.time;
+    if (isCodeModeValue(value))
+        return Number.NaN;
+    // Arrays coerce through our own string coercion: host Number(array) joins with host
+    // ToPrimitive, which throws on the null-prototype objects the interpreter produces.
+    if (Array.isArray(value))
+        return Number(coerceToString(value));
+    return value !== null && typeof value === "object" ? Number.NaN : Number(value);
+};
+export const invokeCoercion = (ref, args, node) => {
+    // Native: Number() is 0 and String() is "", unlike their undefined-argument forms; the
+    // other coercers match native through the undefined-argument path below.
+    if (args.length === 0) {
+        if (ref.name === "Number")
+            return 0;
+        if (ref.name === "String")
+            return "";
+    }
+    const raw = args[0];
+    // Error values are plain SafeObjects; the boundedData path below would strip their brand.
+    if (ref.name === "String" && errorBrandName(raw) !== undefined)
+        return coerceToString(raw);
+    if (isCodeModeValue(raw)) {
+        if (ref.name === "Boolean")
+            return true;
+        if (ref.name === "Number")
+            return coerceToNumber(raw);
+        if (ref.name === "String")
+            return coerceToString(raw);
+        if (ref.name === "isFinite")
+            return Number.isFinite(coerceToNumber(raw));
+        if (ref.name === "isNaN")
+            return Number.isNaN(coerceToNumber(raw));
+        if (ref.name === "parseInt")
+            return parseInt(coerceToString(raw));
+        return parseFloat(coerceToString(raw));
+    }
+    const value = boundedData(raw, `${ref.name} input`);
+    if (ref.name === "Number")
+        return coerceToNumber(value);
+    if (ref.name === "Boolean")
+        return Boolean(value);
+    if (ref.name === "isFinite")
+        return Number.isFinite(coerceToNumber(value));
+    if (ref.name === "isNaN")
+        return Number.isNaN(coerceToNumber(value));
+    if (ref.name === "parseInt") {
+        const radix = args[1];
+        if (radix !== undefined && typeof radix !== "number") {
+            throw new InterpreterRuntimeError("parseInt expects a numeric radix.", node);
+        }
+        return parseInt(coerceToString(value), radix);
+    }
+    if (ref.name === "parseFloat")
+        return parseFloat(coerceToString(value));
+    return coerceToString(value);
+};
+import { CoercionFunction, InterpreterRuntimeError } from "../interpreter/model.js";
+import { copyIn } from "../tool-runtime.js";
+import { isCodeModeValue, CodeModeDate, CodeModeMap, CodeModeRegExp, CodeModeSet, CodeModeURL, CodeModeURLSearchParams, } from "../values.js";

package/dist/tool-error.d.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+declare const ToolError_base: Schema.Class<ToolError, Schema.TaggedStruct<"ToolError", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/** Tool failure reported as `ToolFailure`. */
+export declare class ToolError extends ToolError_base {
+}
+/** Creates a tool failure with an optional underlying cause. */
+export declare const toolError: (message: string, cause?: unknown) => ToolError;
+export {};

package/dist/tool-error.js

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+/** Tool failure reported as `ToolFailure`. */
+export class ToolError extends Schema.TaggedError()("ToolError", {
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Defect()),
+}) {
+}
+/** Creates a tool failure with an optional underlying cause. */
+export const toolError = (message, cause) => new ToolError({ message, ...(cause === undefined ? {} : { cause }) });

package/dist/tool-runtime.d.ts

@@ -0,0 +1,68 @@
+import { Effect } from "effect";
+import type { Tools } from "./tools.js";
+export type Services<T> = ServicesOf<T, []>;
+type ServicesOf<T, Depth extends ReadonlyArray<unknown>> = Depth["length"] extends 8 ? never : T extends {
+    readonly _tag: "CodeModeTool";
+    readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, infer R>;
+} ? R : T extends object ? string extends keyof T ? ServicesOf<T[string], [...Depth, unknown]> : ServicesOf<T[keyof T], [...Depth, unknown]> : never;
+export type ToolCall = {
+    readonly name: string;
+};
+export type ToolCallStarted = {
+    readonly index: number;
+    readonly name: string;
+    readonly input: unknown;
+};
+export type ToolCallEnded = {
+    readonly index: number;
+    readonly name: string;
+    readonly input: unknown;
+    readonly durationMs: number;
+    readonly outcome: "success" | "failure" | "interrupted";
+    readonly message?: string;
+};
+export type ToolCallHooks<R = never> = {
+    readonly onToolCallStart?: ((call: ToolCallStarted) => Effect.Effect<void, never, R>) | undefined;
+    readonly onToolCallEnd?: ((call: ToolCallEnded) => Effect.Effect<void, never, R>) | undefined;
+};
+export type ToolDescription = {
+    readonly path: string;
+    readonly description: string;
+    readonly signature: string;
+};
+export type SafeObject = Record<string, unknown>;
+export declare const toolExpression: (path: string) => string;
+export declare class ToolReference {
+    readonly path: ReadonlyArray<string>;
+    constructor(path: ReadonlyArray<string>);
+}
+export declare class ToolRuntimeError extends Error {
+    readonly kind: "UnknownTool" | "InvalidToolInput" | "InvalidToolOutput" | "InvalidDataValue" | "ToolCallLimitExceeded";
+    readonly suggestions: ReadonlyArray<string>;
+    constructor(kind: "UnknownTool" | "InvalidToolInput" | "InvalidToolOutput" | "InvalidDataValue" | "ToolCallLimitExceeded", message: string, suggestions?: ReadonlyArray<string>);
+}
+export declare const isBlockedMember: (name: string) => boolean;
+export declare const copyIn: (value: unknown, label: string, preserveCodeModeValues?: boolean) => unknown;
+export type CopyOutMode = "json" | "nullify";
+export declare const copyOut: (value: unknown, mode: CopyOutMode) => unknown;
+export type DiscoveryPlan = {
+    readonly catalog: ReadonlyArray<ToolDescription>;
+    readonly searchIndex: ReadonlyArray<SearchEntry>;
+};
+export type SearchEntry = {
+    readonly description: ToolDescription;
+    readonly searchText: string;
+};
+/** Exact callable signature of the built-in `search` function, for host-owned instructions. */
+export declare const searchSignature: string;
+export declare const searchIndex: <R>(tools: Tools<R>) => ReadonlyArray<SearchEntry>;
+export declare const prepare: <R>(tools: Tools<R>) => DiscoveryPlan;
+export type ToolRuntime<R = never> = {
+    readonly root: ToolReference;
+    readonly calls: Array<ToolCall>;
+    readonly execute: (path: ReadonlyArray<string>, args: Array<unknown>) => Effect.Effect<unknown, unknown, R>;
+    readonly search: (args: Array<unknown>) => Effect.Effect<unknown, unknown, R>;
+    readonly keys: (path: ReadonlyArray<string>) => ReadonlyArray<string>;
+};
+export declare const make: <R>(tools: Tools<R>, maxToolCalls: number | undefined, searchIndex: ReadonlyArray<SearchEntry>, hooks?: ToolCallHooks<R>) => ToolRuntime<R>;
+export * as ToolRuntime from "./tool-runtime.js";

package/dist/tool-runtime.js

@@ -0,0 +1,391 @@
+import { Cause, Effect, Exit, Formatter, Schema } from "effect";
+import { toolError } from "./tool-error.js";
+import { decodeInput as decodeToolInput, decodeOutput as decodeToolOutput, identifierSegment, inputProperties, inputTypeScript, isEmptyInput, outputTypeScript, } from "./tool-schema.js";
+import { isNamespace } from "./namespace.js";
+import { isTool } from "./tool.js";
+import { CodeModeDate, CodeModeMap, CodeModePromise, CodeModeRegExp, CodeModeSet, CodeModeURL, CodeModeURLSearchParams, } from "./values.js";
+const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+const defaultSearchLimit = 10;
+const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
+const NonNegativeInt = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+const SearchInput = Schema.Struct({
+    query: Schema.optionalKey(Schema.String),
+    namespace: Schema.optionalKey(Schema.String),
+    limit: Schema.optionalKey(PositiveInt),
+    offset: Schema.optionalKey(NonNegativeInt),
+});
+const SearchItem = Schema.Struct({
+    path: Schema.String,
+    description: Schema.String,
+    signature: Schema.String,
+});
+const SearchOutput = Schema.Struct({
+    items: Schema.Array(SearchItem),
+    remaining: NonNegativeInt,
+    next: Schema.NullOr(Schema.Struct({ offset: NonNegativeInt })),
+});
+export const toolExpression = (path) => "tools" +
+    path
+        .split(".")
+        .map((segment) => (identifierSegment.test(segment) ? `.${segment}` : `[${JSON.stringify(segment)}]`))
+        .join("");
+export class ToolReference {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+}
+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);
+// Checkpoint mode preserves CodeMode values; boundary mode JSON-normalizes them.
+export const copyIn = (value, label, preserveCodeModeValues = false) => copyBounded(value, label, 0, new Set(), preserveCodeModeValues);
+const copyBounded = (value, label, depth, seen, preserveCodeModeValues) => {
+    if (depth > MAX_VALUE_DEPTH) {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`);
+    }
+    if (value === null ||
+        value === undefined ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        typeof value === "number") {
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} must contain data only.`);
+    }
+    if (value instanceof CodeModePromise) {
+        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 (preserveCodeModeValues) {
+        if (value instanceof CodeModeDate ||
+            value instanceof CodeModeRegExp ||
+            value instanceof CodeModeMap ||
+            value instanceof CodeModeSet ||
+            value instanceof CodeModeURL ||
+            value instanceof CodeModeURLSearchParams) {
+            return value;
+        }
+        if (value instanceof Date)
+            return new CodeModeDate(value.getTime());
+        if (value instanceof RegExp)
+            return new CodeModeRegExp(value.source, value.flags);
+        if (value instanceof Map) {
+            const wrapped = new CodeModeMap();
+            for (const [key, item] of value.entries()) {
+                wrapped.map.set(copyBounded(key, label, depth + 1, seen, true), copyBounded(item, label, depth + 1, seen, true));
+            }
+            return wrapped;
+        }
+        if (value instanceof Set) {
+            const wrapped = new CodeModeSet();
+            for (const item of value.values())
+                wrapped.set.add(copyBounded(item, label, depth + 1, seen, true));
+            return wrapped;
+        }
+        if (value instanceof URL)
+            return new CodeModeURL(new URL(value.href));
+        if (value instanceof URLSearchParams)
+            return new CodeModeURLSearchParams(new URLSearchParams(value));
+    }
+    if (value instanceof CodeModeDate) {
+        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 CodeModeURL)
+        return value.url.href;
+    if (value instanceof URL)
+        return value.href;
+    if (value instanceof CodeModeRegExp ||
+        value instanceof CodeModeMap ||
+        value instanceof CodeModeSet ||
+        value instanceof CodeModeURLSearchParams ||
+        value instanceof RegExp ||
+        value instanceof Map ||
+        value instanceof Set ||
+        value instanceof URLSearchParams) {
+        return Object.create(null);
+    }
+    if (seen.has(value)) {
+        throw new ToolRuntimeError("InvalidDataValue", `${label} contains a circular value.`);
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        const copied = value.map((item) => copyBounded(item, label, depth + 1, seen, preserveCodeModeValues));
+        if (preserveCodeModeValues) {
+            // Checkpoint copies retain array metadata that boundary copies omit.
+            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, copyBounded(item, label, depth + 1, seen, true));
+            }
+        }
+        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 = Object.create(null);
+    for (const [key, item] of Object.entries(value)) {
+        if (isBlockedMember(key)) {
+            throw new ToolRuntimeError("InvalidDataValue", `${label} contains blocked property '${key}'.`);
+        }
+        copied[key] = copyBounded(item, label, depth + 1, seen, preserveCodeModeValues);
+    }
+    seen.delete(value);
+    return copied;
+};
+export const copyOut = (value, mode) => {
+    if (value === undefined && mode === "nullify")
+        return null;
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        // Array.from densifies holes so sparse arrays normalize at the boundary like JSON does.
+        return Array.from(value, (item) => {
+            const copied = copyOut(item, mode);
+            return copied === undefined && mode === "json" ? null : copied;
+        });
+    }
+    if (value !== null && typeof value === "object" && !(value instanceof ToolReference)) {
+        return Object.fromEntries(Object.entries(value)
+            .map(([key, item]) => [key, copyOut(item, mode)])
+            .filter(([, item]) => !(item === undefined && mode === "json")));
+    }
+    return value;
+};
+const toolTrie = (tools) => {
+    const root = { children: new Map() };
+    const insert = (node, group) => {
+        for (const [name, value] of Object.entries(group)) {
+            let current = node;
+            for (const segment of name.split(".")) {
+                if (segment === "")
+                    throw new TypeError(`Tool name '${name}' contains an empty segment.`);
+                const child = current.children.get(segment) ?? { children: new Map() };
+                current.children.set(segment, child);
+                current = child;
+            }
+            if (isTool(value))
+                current.tool = value;
+            else if (isNamespace(value)) {
+                current.namespace = value;
+                insert(current, value.tools);
+            }
+            else
+                insert(current, value);
+        }
+    };
+    insert(root, tools);
+    return root;
+};
+const canonicalSegments = (path) => path.flatMap((segment) => segment.split("."));
+const flattenTools = (node, path = [], namespaces = []) => {
+    const next = node.namespace === undefined ? namespaces : [...namespaces, node.namespace];
+    return [
+        ...(node.tool === undefined ? [] : [{ path: path.join("."), tool: node.tool, namespaces: next }]),
+        ...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)}>`,
+});
+// Discovery bytes are durable instructions, so order only after canonical-path collisions settle.
+const visibleTools = (tools) => flattenTools(toolTrie(tools)).sort((left, right) => compareText(left.path, right.path));
+const tokenize = (query) => query
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((term) => term.length > 0 && term !== "*");
+const termForms = (term) => {
+    const forms = [term];
+    if (term.endsWith("es") && term.length > 3)
+        forms.push(term.slice(0, -2));
+    if (term.endsWith("s") && term.length > 2)
+        forms.push(term.slice(0, -1));
+    return forms;
+};
+const makeSearchTool = (searchIndex) => ({
+    _tag: "CodeModeTool",
+    description: "Search available tools",
+    input: SearchInput,
+    output: SearchOutput,
+    execute: (input) => Effect.sync(() => {
+        const request = input;
+        const query = request.query ?? "";
+        const offset = request.offset ?? 0;
+        const scoped = request.namespace === undefined
+            ? searchIndex
+            : searchIndex.filter((entry) => entry.description.path === request.namespace ||
+                entry.description.path.startsWith(`${request.namespace}.`));
+        const trimmed = query.trim();
+        const pathQuery = trimmed.startsWith("tools.") ? trimmed.slice("tools.".length) : trimmed;
+        const exact = pathQuery === ""
+            ? undefined
+            : scoped.find((entry) => entry.description.path === pathQuery || toolExpression(entry.description.path) === trimmed);
+        const terms = tokenize(query).map(termForms);
+        const ranked = exact !== undefined
+            ? [exact]
+            : scoped
+                .map((entry) => {
+                const path = entry.description.path.toLowerCase();
+                const description = entry.description.description.toLowerCase();
+                const score = terms.reduce((total, forms) => total +
+                    (forms.some((form) => path === form || path.endsWith(`.${form}`)) ? 20 : 0) +
+                    (forms.some((form) => path.includes(form)) ? 8 : 0) +
+                    (forms.some((form) => description.includes(form)) ? 4 : 0) +
+                    (forms.some((form) => entry.searchText.includes(form)) ? 2 : 0), 0);
+                return { entry, score };
+            })
+                .filter(({ score }) => terms.length === 0 || score > 0)
+                .sort((left, right) => right.score - left.score || compareText(left.entry.description.path, right.entry.description.path))
+                .map(({ entry }) => entry);
+        const items = ranked.slice(offset, offset + (request.limit ?? defaultSearchLimit)).map(({ description }) => ({
+            ...description,
+            path: toolExpression(description.path),
+        }));
+        const remaining = Math.max(0, ranked.length - offset - items.length);
+        return {
+            items,
+            remaining,
+            next: remaining > 0 ? { offset: offset + items.length } : null,
+        };
+    }),
+});
+/** Exact callable signature of the built-in `search` function, for host-owned instructions. */
+export const searchSignature = (() => {
+    const tool = makeSearchTool([]);
+    return `search(input: ${inputTypeScript(tool, true)}): ${outputTypeScript(tool, true)}`;
+})();
+const toSearchEntry = (visible) => ({
+    description: describeTool(visible),
+    searchText: [
+        visible.path,
+        visible.tool.description,
+        ...visible.namespaces.flatMap((namespace) => (namespace.description === undefined ? [] : [namespace.description])),
+        ...inputProperties(visible.tool).flatMap(({ name, description: property }) => property === undefined ? [name] : [name, property]),
+    ]
+        .join("\n")
+        .toLowerCase(),
+});
+export const searchIndex = (tools) => visibleTools(tools).map(toSearchEntry);
+export const prepare = (tools) => {
+    const visible = visibleTools(tools);
+    return {
+        catalog: visible.map(describeTool),
+        searchIndex: visible.map(toSearchEntry),
+    };
+};
+const lookup = (root, segments) => segments.reduce((node, segment) => node?.children.get(segment), root);
+const namespaceKeys = (root, path) => {
+    const segments = canonicalSegments(path);
+    const node = lookup(root, segments);
+    if (node === undefined) {
+        throw new ToolRuntimeError("UnknownTool", `Unknown tool namespace '${segments.join(".")}'.`);
+    }
+    return Array.from(node.children.keys());
+};
+const resolve = (root, path) => {
+    const segments = canonicalSegments(path);
+    const node = lookup(root, segments);
+    if (node === undefined) {
+        throw new ToolRuntimeError("UnknownTool", `Unknown tool '${segments.join(".")}'.`, [
+            "The tool may have been removed or renamed. Use search to find available tools.",
+        ]);
+    }
+    if (node.tool === undefined) {
+        throw new ToolRuntimeError("UnknownTool", `Tool '${segments.join(".")}' is not callable.`);
+    }
+    return node.tool;
+};
+export const make = (tools, maxToolCalls, searchIndex, hooks) => {
+    const calls = [];
+    const root = toolTrie(tools);
+    const searchTool = makeSearchTool(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}.`);
+        }
+        calls.push(call);
+    };
+    const executeTool = (name, tool, externalArgs) => Effect.gen(function* () {
+        const normalized = externalArgs.length === 0 ? [{}] : externalArgs;
+        if (normalized.length !== 1)
+            throw new ToolRuntimeError("InvalidToolInput", `Tool '${name}' expects at most one input object.`);
+        const input = yield* Effect.try({
+            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);
+            const raw = yield* Effect.suspend(() => tool.execute(input)).pipe(Effect.catchCause((cause) => {
+                if (Cause.hasInterruptsOnly(cause))
+                    return Effect.interrupt;
+                return Effect.fail(toolError(Cause.prettyErrors(cause)
+                    .map((error) => (error.cause ? Formatter.format(error) : error.message || error.name))
+                    .join("\n")));
+            }));
+            return yield* Effect.try({
+                try: () => copyIn(decodeToolOutput(tool, raw), `Result from tool '${name}'`),
+                catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
+            });
+        }), call);
+    });
+    return {
+        root: new ToolReference([]),
+        calls,
+        keys: (path) => namespaceKeys(root, path),
+        search: (args) => Effect.suspend(() => executeTool("search", searchTool, args.map((arg) => copyOut(copyIn(arg, "Arguments for tool 'search'"), "json")))),
+        execute: (path, args) => Effect.gen(function* () {
+            const name = canonicalSegments(path).join(".");
+            const externalArgs = args.map((arg) => copyOut(copyIn(arg, `Arguments for tool '${name}'`), "json"));
+            const tool = resolve(root, path);
+            return yield* executeTool(name, tool, externalArgs);
+        }),
+    };
+};
+export * as ToolRuntime from "./tool-runtime.js";

package/dist/tool-schema.d.ts

@@ -0,0 +1,16 @@
+import { Schema } from "effect";
+import type { Tool, JsonSchema } from "./tool.js";
+export declare const identifierSegment: RegExp;
+export declare const toTypeScript: (schema: Schema.Top, decoded?: boolean, pretty?: boolean) => string;
+export declare const jsonSchemaToTypeScript: (schema: JsonSchema, pretty?: boolean) => string;
+export type InputProperty = {
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly required: boolean;
+};
+export declare const inputProperties: <R>(tool: Tool<R>) => Array<InputProperty>;
+export declare const inputTypeScript: <R>(tool: Tool<R>, pretty?: boolean) => string;
+export declare const isEmptyInput: <R>(tool: Tool<R>) => boolean;
+export declare const outputTypeScript: <R>(tool: Tool<R>, pretty?: boolean) => string;
+export declare const decodeInput: <R>(tool: Tool<R>, value: unknown) => unknown;
+export declare const decodeOutput: <R>(tool: Tool<R>, value: unknown) => unknown;