@opencode/codemode 0.0.0-reserved → 2.0.1

package/dist/tool-runtime.js

@@ -0,0 +1,254 @@
+import { Cause, Effect, Exit, Formatter, Schema } from "effect";
+import { fromData, toData, ToolRuntimeError } from "./data.js";
+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";
+export 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 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)}>`,
+});
+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 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));
+    return {
+        root,
+        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;
+};
+/** Per-execution call state over tools prepared once for the runtime. */
+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}.`);
+        }
+        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: () => fromData(decodeToolOutput(tool, raw), `Result from tool '${name}'`),
+                catch: (cause) => new ToolRuntimeError("InvalidToolOutput", `Invalid output from tool '${name}': ${cause}`),
+            });
+        }), call);
+    });
+    return {
+        calls,
+        keys: (path) => namespaceKeys(root, path),
+        search: (args) => Effect.suspend(() => executeTool("search", searchTool, args.map((arg) => toData(arg, "Arguments for tool 'search'")))),
+        execute: (path, args) => Effect.gen(function* () {
+            const name = canonicalSegments(path).join(".");
+            const externalArgs = args.map((arg) => toData(arg, `Arguments for tool '${name}'`));
+            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;

package/dist/tool-schema.js

@@ -0,0 +1,263 @@
+import { JsonPointer, Schema } from "effect";
+const isEffectSchema = (schema) => Schema.isSchema(schema);
+const renderLiteral = (value) => JSON.stringify(value) ?? "unknown";
+export const identifierSegment = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const renderKey = (name) => (identifierSegment.test(name) ? name : JSON.stringify(name));
+const effectNumberSentinel = (schema) => schema.type === "string" &&
+    Array.isArray(schema.enum) &&
+    schema.enum.length === 1 &&
+    (schema.enum[0] === "NaN" || schema.enum[0] === "Infinity" || schema.enum[0] === "-Infinity");
+const intersection = (members) => {
+    const concrete = members.filter((member) => member !== "unknown");
+    if (concrete.length === 0)
+        return "unknown";
+    if (concrete.length === 1)
+        return concrete[0];
+    return concrete.map((member) => (member.includes(" | ") ? `(${member})` : member)).join(" & ");
+};
+const MAX_RENDER_DEPTH = 8;
+const hasUnresolvedRef = (schema, definitions, seen = new Set(), visited = new Set()) => {
+    if (visited.has(schema))
+        return false;
+    const nextVisited = new Set([...visited, schema]);
+    if (schema.$ref !== undefined) {
+        const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1];
+        const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment);
+        if (name === undefined || definitions[name] === undefined || seen.has(name))
+            return true;
+        if (hasUnresolvedRef(definitions[name], definitions, new Set([...seen, name]), nextVisited))
+            return true;
+    }
+    return [
+        ...(schema.anyOf ?? []),
+        ...(schema.oneOf ?? []),
+        ...(schema.allOf ?? []),
+        ...Object.values(schema.properties ?? {}),
+        ...(schema.items === undefined ? [] : [schema.items]),
+        ...(typeof schema.additionalProperties === "object" ? [schema.additionalProperties] : []),
+    ].some((item) => hasUnresolvedRef(item, definitions, seen, nextVisited));
+};
+const docTags = (schema) => {
+    const tags = [];
+    if (schema.deprecated === true)
+        tags.push("@deprecated");
+    if (schema.default !== undefined) {
+        try {
+            const rendered = JSON.stringify(schema.default);
+            if (rendered !== undefined)
+                tags.push(`@default ${rendered}`);
+        }
+        catch { }
+    }
+    if (typeof schema.format === "string")
+        tags.push(`@format ${schema.format}`);
+    if (schema.type === "integer")
+        tags.push("@integer");
+    if (typeof schema.minimum === "number")
+        tags.push(`@minimum ${schema.minimum}`);
+    if (typeof schema.maximum === "number")
+        tags.push(`@maximum ${schema.maximum}`);
+    if (typeof schema.exclusiveMinimum === "number")
+        tags.push(`@exclusiveMinimum ${schema.exclusiveMinimum}`);
+    if (typeof schema.exclusiveMaximum === "number")
+        tags.push(`@exclusiveMaximum ${schema.exclusiveMaximum}`);
+    if (typeof schema.multipleOf === "number")
+        tags.push(`@multipleOf ${schema.multipleOf}`);
+    if (typeof schema.minLength === "number")
+        tags.push(`@minLength ${schema.minLength}`);
+    if (typeof schema.maxLength === "number")
+        tags.push(`@maxLength ${schema.maxLength}`);
+    if (typeof schema.pattern === "string")
+        tags.push(`@pattern ${schema.pattern}`);
+    if (typeof schema.minItems === "number")
+        tags.push(`@minItems ${schema.minItems}`);
+    if (typeof schema.maxItems === "number")
+        tags.push(`@maxItems ${schema.maxItems}`);
+    if (schema.uniqueItems === true)
+        tags.push("@uniqueItems true");
+    return tags;
+};
+const docLines = (schema, width) => {
+    const summary = docTags(schema).join(" ");
+    const lines = (schema.description ?? "").split("\n").map((line) => line.replace(/\s+$/, ""));
+    while (lines.length > 0 && lines[0].trim() === "")
+        lines.shift();
+    while (lines.length > 0 && lines[lines.length - 1].trim() === "")
+        lines.pop();
+    const inline = lines.length === 1 ? `${lines[0]}${lines[0].endsWith(".") ? "" : "."} ${summary}` : summary;
+    return summary && lines.length === 1 && !summary.includes("\n") && width + inline.length + 7 <= 120
+        ? [inline]
+        : [...lines, ...(summary ? summary.split("\n") : [])];
+};
+// Neutralize `*\/` so model-provided schema text cannot terminate generated documentation.
+const jsdoc = (schema, pad) => {
+    const content = docLines(schema, pad.length);
+    const types = typeof schema.type === "string" ? [schema.type] : (schema.type ?? []);
+    const append = (label, child) => {
+        docLines(child, pad.length + label.length + 2).forEach((line, index) => {
+            if (index === 0) {
+                content.push(`${label}: ${line}`);
+                return;
+            }
+            content.push(line ? `  ${line}` : "");
+        });
+    };
+    // Document only the immediate contents; recursive labels obscure which level a constraint belongs to.
+    if (types.includes("array") && schema.items)
+        append("Each item", schema.items);
+    if ((types.includes("object") || schema.properties) && typeof schema.additionalProperties === "object") {
+        const label = Object.keys(schema.properties ?? {}).length > 0 ? "Each additional value" : "Each value";
+        append(label, schema.additionalProperties);
+    }
+    if (content.length === 0)
+        return "";
+    const escaped = content.map((line) => line.replaceAll("*/", "* /"));
+    if (escaped.length === 1 && pad.length + escaped[0].length + 7 <= 120)
+        return `${pad}/** ${escaped[0]} */\n`;
+    const body = escaped.map((line) => `${pad} *${line === "" ? "" : ` ${line}`}`).join("\n");
+    return `${pad}/**\n${body}\n${pad} */\n`;
+};
+const renderSchema = (schema, ctx, depth = 0, seen = new Set()) => {
+    if (depth > MAX_RENDER_DEPTH)
+        return "unknown";
+    const nested = schema.definitions === undefined && schema.$defs === undefined
+        ? ctx
+        : { ...ctx, definitions: { ...ctx.definitions, ...(schema.definitions ?? {}), ...(schema.$defs ?? {}) } };
+    if (schema.$ref) {
+        const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1];
+        const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment);
+        if (!name || !nested.definitions[name] || seen.has(name))
+            return "unknown";
+        return intersection([
+            renderSchema(nested.definitions[name], nested, depth, new Set([...seen, name])),
+            renderSchema({ ...schema, $ref: undefined }, nested, depth + 1, seen),
+        ]);
+    }
+    if (schema.const !== undefined)
+        return renderLiteral(schema.const);
+    if (schema.enum)
+        return schema.enum.map(renderLiteral).join(" | ");
+    const alternatives = schema.anyOf ?? schema.oneOf;
+    if (alternatives) {
+        if (alternatives.some((item) => item.type === "number") &&
+            alternatives.every((item) => item.type === "number" || effectNumberSentinel(item)))
+            return "number";
+        if (alternatives.length === 2 &&
+            alternatives[0]?.type === "object" &&
+            alternatives[0].properties === undefined &&
+            alternatives[1]?.type === "array" &&
+            alternatives[1].items === undefined) {
+            return "{}";
+        }
+        const members = alternatives.map((item) => renderSchema(item, nested, depth + 1, seen));
+        if (members.some((member) => member === "unknown"))
+            return "unknown";
+        return intersection([
+            members.join(" | "),
+            renderSchema({ ...schema, anyOf: undefined, oneOf: undefined }, nested, depth + 1, seen),
+        ]);
+    }
+    if (schema.allOf) {
+        if (schema.allOf.some((item) => hasUnresolvedRef(item, nested.definitions)))
+            return "unknown";
+        const members = schema.allOf.map((item) => renderSchema(item, nested, depth + 1, seen));
+        return intersection([renderSchema({ ...schema, allOf: undefined }, nested, depth + 1, seen), ...members]);
+    }
+    if (Array.isArray(schema.type)) {
+        return schema.type.map((item) => renderSchema({ ...schema, type: item }, nested, depth + 1, seen)).join(" | ");
+    }
+    if (schema.type === "string")
+        return "string";
+    if (schema.type === "number" || schema.type === "integer")
+        return "number";
+    if (schema.type === "boolean")
+        return "boolean";
+    if (schema.type === "null")
+        return "null";
+    if (schema.type === "array")
+        return `Array<${renderSchema(schema.items ?? {}, nested, depth + 1, seen)}>`;
+    if (schema.type === "object" || schema.properties) {
+        const required = new Set(schema.required ?? []);
+        const properties = Object.entries(schema.properties ?? {});
+        const additional = schema.additionalProperties;
+        const indexType = additional && typeof additional === "object" ? renderSchema(additional, nested, depth + 1, seen) : undefined;
+        const field = ([name, value]) => `${renderKey(name)}${required.has(name) ? "" : "?"}: ${renderSchema(value, nested, depth + 1, seen)}`;
+        if (!ctx.pretty) {
+            const fields = properties.map(field);
+            if (indexType !== undefined)
+                fields.push(`[key: string]: ${indexType}`);
+            return fields.length === 0 ? "{}" : `{ ${fields.join("; ")} }`;
+        }
+        if (properties.length === 0 && indexType === undefined)
+            return "{}";
+        const pad = "  ".repeat(depth + 1);
+        const lines = properties.map((entry) => `${jsdoc(entry[1], pad)}${pad}${field(entry)},`);
+        if (indexType !== undefined)
+            lines.push(`${pad}[key: string]: ${indexType},`);
+        return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`;
+    }
+    return "unknown";
+};
+export const toTypeScript = (schema, decoded = false, pretty = false) => {
+    try {
+        const visible = decoded ? Schema.toType(schema) : schema;
+        const document = Schema.toJsonSchemaDocument(visible);
+        return renderSchema(document.schema, { definitions: document.definitions ?? {}, pretty });
+    }
+    catch {
+        return "unknown";
+    }
+};
+export const jsonSchemaToTypeScript = (schema, pretty = false) => {
+    try {
+        return renderSchema(schema, { definitions: {}, pretty });
+    }
+    catch {
+        return "unknown";
+    }
+};
+export const inputProperties = (tool) => {
+    try {
+        const document = isEffectSchema(tool.input)
+            ? Schema.toJsonSchemaDocument(tool.input)
+            : {
+                schema: tool.input,
+                definitions: { ...(tool.input.definitions ?? {}), ...(tool.input.$defs ?? {}) },
+            };
+        const definitions = document.definitions ?? {};
+        let schema = document.schema;
+        if (schema.$ref !== undefined) {
+            const segment = schema.$ref.match(/^#\/(?:\$defs|definitions)\/([^/]+)$/)?.[1];
+            const name = segment === undefined ? undefined : JsonPointer.unescapeToken(segment);
+            const resolved = name === undefined ? undefined : definitions[name];
+            if (resolved === undefined)
+                return [];
+            schema = resolved;
+        }
+        const required = new Set(schema.required ?? []);
+        return Object.entries(schema.properties ?? {}).map(([name, value]) => ({
+            name,
+            description: typeof value.description === "string" ? value.description : undefined,
+            required: required.has(name),
+        }));
+    }
+    catch {
+        return [];
+    }
+};
+export const inputTypeScript = (tool, pretty = false) => isEffectSchema(tool.input) ? toTypeScript(tool.input, false, pretty) : jsonSchemaToTypeScript(tool.input, pretty);
+// Empty object schemas render as `{}` in compact form; anything with properties,
+// an index signature, or union members renders differently, so equality is a
+// conservative emptiness test for both Effect and JSON Schema inputs.
+export const isEmptyInput = (tool) => inputTypeScript(tool) === "{}";
+export const outputTypeScript = (tool, pretty = false) => tool.output === undefined
+    ? "void"
+    : isEffectSchema(tool.output)
+        ? toTypeScript(tool.output, true, pretty)
+        : jsonSchemaToTypeScript(tool.output, pretty);
+export const decodeInput = (tool, value) => isEffectSchema(tool.input) ? Schema.decodeUnknownSync(tool.input)(value) : value;
+export const decodeOutput = (tool, value) => tool.output === undefined
+    ? undefined
+    : isEffectSchema(tool.output)
+        ? Schema.decodeUnknownSync(tool.output)(value)
+        : value;

package/dist/tool.d.ts

@@ -0,0 +1,66 @@
+import { Effect, Schema } from "effect";
+import type { Namespace } from "./namespace.js";
+import type { Tools } from "./tools.js";
+/**
+ * JSON Schema subset for model-visible signatures. CodeMode does not validate values against
+ * these schemas.
+ */
+export type JsonSchema = {
+    readonly type?: string | ReadonlyArray<string>;
+    readonly enum?: ReadonlyArray<unknown>;
+    readonly const?: unknown;
+    readonly anyOf?: ReadonlyArray<JsonSchema>;
+    readonly oneOf?: ReadonlyArray<JsonSchema>;
+    readonly allOf?: ReadonlyArray<JsonSchema>;
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: ReadonlyArray<string>;
+    readonly items?: JsonSchema;
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly format?: string;
+    readonly deprecated?: boolean;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly exclusiveMinimum?: number;
+    readonly exclusiveMaximum?: number;
+    readonly multipleOf?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly uniqueItems?: boolean;
+    readonly $ref?: string;
+    readonly $defs?: Readonly<Record<string, JsonSchema>>;
+    readonly definitions?: Readonly<Record<string, JsonSchema>>;
+};
+/** Either a validating Effect Schema or a render-only JSON Schema document. */
+export type SchemaType = Schema.Decoder<unknown> | JsonSchema;
+/** Executable tool exposed through CodeMode's `tools` object. */
+export type Tool<R = never> = {
+    readonly _tag: "CodeModeTool";
+    readonly description: string;
+    readonly input: SchemaType;
+    readonly output: SchemaType | undefined;
+    readonly execute: (input: unknown) => Effect.Effect<unknown, unknown, R>;
+};
+type InputType<S> = S extends Schema.Decoder<unknown> ? S["Type"] : unknown;
+type ResultType<S> = S extends undefined ? void : S extends Schema.Decoder<unknown> ? S["Encoded"] : unknown;
+/** Options for declaring one CodeMode tool. */
+export type Options<I extends SchemaType, O extends SchemaType | undefined, R = never> = {
+    readonly description: string;
+    readonly input: I;
+    readonly output?: O;
+    readonly execute: (input: InputType<I>) => Effect.Effect<ResultType<O>, unknown, R>;
+};
+export declare const isTool: <R = never>(value: Tool<R> | Namespace<R> | Tools<R> | undefined) => value is Tool<R>;
+/**
+ * Declares one schema-described tool available to a CodeMode program through `tools.*`.
+ *
+ * Effect Schemas validate values; JSON Schemas only shape the model-visible signature.
+ * Without `output`, results are exposed as `void`. Hosts remain responsible for authorization
+ * and durable side effects.
+ */
+export declare const make: <I extends SchemaType, const O extends SchemaType | undefined = undefined, R = never>(options: Options<I, O, R>) => Tool<R>;
+export {};

package/dist/tool.js

@@ -0,0 +1,16 @@
+import { Effect, Schema } from "effect";
+export const isTool = (value) => value !== undefined && Object.hasOwn(value, "_tag") && value._tag === "CodeModeTool";
+/**
+ * Declares one schema-described tool available to a CodeMode program through `tools.*`.
+ *
+ * Effect Schemas validate values; JSON Schemas only shape the model-visible signature.
+ * Without `output`, results are exposed as `void`. Hosts remain responsible for authorization
+ * and durable side effects.
+ */
+export const make = (options) => ({
+    _tag: "CodeModeTool",
+    description: options.description,
+    input: options.input,
+    output: options.output,
+    execute: (input) => options.execute(input),
+});

package/dist/tools.d.ts

@@ -0,0 +1,5 @@
+import type { Namespace } from "./namespace.js";
+import type { Tool } from "./tool.js";
+export type Tools<R = never> = {
+    readonly [name: string]: Tool<R> | Namespace<R> | Tools<R>;
+};

package/dist/tools.js

@@ -0,0 +1 @@
+export {};

package/dist/values.d.ts

@@ -0,0 +1,37 @@
+export * as Values from "./values.js";
+import type { Fiber } from "effect";
+/**
+ * Runtime values the interpreter recognizes by class. Each wraps the host value it stands for,
+ * so hosts construct these to hand a value to a program and receive them back unchanged.
+ */
+export declare class Promise {
+    readonly fiber: Fiber.Fiber<unknown, unknown>;
+    constructor(fiber: Fiber.Fiber<unknown, unknown>);
+}
+export declare class Date {
+    time: number;
+    constructor(time: number);
+}
+export declare class RegExp {
+    readonly regex: globalThis.RegExp;
+    constructor(pattern: string, flags: string);
+    get lastIndex(): unknown;
+    set lastIndex(value: unknown);
+}
+export declare class Map {
+    readonly map: globalThis.Map<unknown, unknown>;
+}
+export declare class Set {
+    readonly set: globalThis.Set<unknown>;
+}
+export declare class URLSearchParams {
+    readonly params: globalThis.URLSearchParams;
+    constructor(params: globalThis.URLSearchParams);
+}
+export declare class URL {
+    readonly url: globalThis.URL;
+    readonly searchParams: URLSearchParams;
+    constructor(url: globalThis.URL);
+}
+/** Data-like runtime values; excludes Promise, which never crosses a boundary. */
+export declare const isValue: (value: unknown) => value is Date | RegExp | Map | Set | URL | URLSearchParams;