@renoxium/sdk 0.0.0-stage → 0.1.0

package/dist/test.d.ts

@@ -0,0 +1,169 @@
+/** What installing or upgrading a module reported (`renox check` and the migration plan). */
+export interface ModuleChange {
+    check: {
+        errors: {
+            message: string;
+            file?: string;
+        }[];
+        findings: {
+            rule: string;
+            severity: string;
+            message: string;
+            file: string;
+        }[];
+    };
+    migrate: {
+        ok: boolean;
+        module?: string;
+        error?: string;
+        modules: {
+            module: string;
+            applied: string[];
+            skipped: string[];
+        }[];
+    } | null;
+    project: string;
+}
+/** A response with its body read. */
+export interface Reply {
+    status: number;
+    headers: Headers;
+    html: string;
+    json<T = unknown>(): T;
+}
+export interface RequestInitLite {
+    headers?: Record<string, string>;
+    body?: string | Record<string, unknown>;
+}
+/** A service proxy: `service("notes").add("x")` resolves with the service's value or throws its error. */
+export type ServiceProxy = Record<string, (...args: unknown[]) => Promise<unknown>>;
+/** The error a service threw, as the broker reported it. */
+export declare class ServiceError extends Error {
+    readonly code: string | null;
+    readonly details: unknown;
+    constructor(message: string, code: string | null, details: unknown);
+}
+export interface TestApp {
+    /** Any request; a JSON object `body` is sent as JSON. */
+    request(method: string, path: string, init?: RequestInitLite): Promise<Reply>;
+    /** GET a page as this app's current user (its own cookie jar: session and CSRF). */
+    page(path: string, options?: {
+        user?: string;
+    }): Promise<Reply>;
+    /** POST a page action (`?/<name>`) with the form and the session's CSRF token. */
+    action(path: string, name: string, form: Record<string, string>, options?: {
+        user?: string;
+    }): Promise<Reply>;
+    /** Call an installed module's service through the broker. */
+    service(module: string): ServiceProxy;
+    /** Read-only SQL on the tenant file, for assertions. */
+    db: {
+        query<T = Record<string, unknown>>(sql: string, params?: (string | number | null)[]): T[];
+    };
+    /** The tenant file itself (to age a row in an expiry test, open it with bun:sqlite). */
+    dbFile: string;
+    /** The same app as another user: a separate session (cookie jar). */
+    as(user: string): TestApp;
+    /** Read a cookie of this user's jar, or plant one (an attacker's token, a forged state). */
+    cookie(name: string, value?: string): string | undefined;
+    /** Open a WebSocket route as this user (its cookies, the app's origin); read messages with `next`. */
+    ws(path: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<WsStream>;
+    /** Open an SSE route (`GET`, `Accept: text/event-stream`) as this user; read its events with `next`. */
+    sse(path: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<SseStream>;
+    /** Tenant log lines so far. */
+    logs(): Record<string, unknown>[];
+    /** Meter records so far (flushed about every second). */
+    meters(): Record<string, unknown>[];
+    stop(): Promise<void>;
+}
+/** One SSE event as received (ops.md section 18, "On the wire"). */
+export interface SseEvent {
+    id: string | null;
+    event: string | null;
+    data: string;
+}
+/** An open SSE connection of a test. */
+export interface SseStream {
+    status: number;
+    headers: Headers;
+    /** The next event, or null when none arrives within `ms` (default 2000) or the stream ended. */
+    next(ms?: number): Promise<SseEvent | null>;
+    /** Events received so far and not yet returned by `next`. */
+    pending(): SseEvent[];
+    close(): void;
+}
+/** An open WebSocket of a test. */
+export interface WsStream {
+    /** The next text message, or null when none arrives within `ms` (default 2000) or the socket closed. */
+    next(ms?: number): Promise<string | null>;
+    send(text: string): void;
+    /** Resolves with the close code (1008 for a refused subscribe, 1011 for a throwing `open`). */
+    closed: Promise<number>;
+    close(): void;
+}
+/**
+ * A fresh worker and tenant file for this test file (stopped after it):
+ * migrations applied, then `seeds/*.sql` and `renox test --seed` files.
+ */
+export declare function app(options?: {
+    project?: string;
+}): Promise<TestApp>;
+/**
+ * The page's HTML without what changes per request (request id, deployment,
+ * nonces, CSRF tokens, session ids), matched against the snapshot named by
+ * `role`. Returns the normalized HTML.
+ */
+export declare function snapshot(html: string, options: {
+    role: string;
+}): string;
+/** One policy test case (`policies/tests/*.json`, #283): evaluated by the engine the cell builds. */
+export interface PolicyCase {
+    principal: {
+        type: string;
+        id: string;
+        roles?: string[];
+        attrs?: Record<string, unknown>;
+    };
+    action: string;
+    /** `type` is an entity type of the app (`"Doc"`) or a module's (`"auth:Account"`), with its declared attributes. */
+    resource?: {
+        type: string;
+        id?: string;
+        [attr: string]: unknown;
+    };
+    context?: Record<string, unknown>;
+    expected: "allow" | "deny";
+    description?: string;
+}
+/**
+ * Reads `policies/tests/*.json` (each an array of cases, or `{ cases: [...] }`)
+ * and registers one test per case that evaluates it with the engine the
+ * cell builds (`renox-worker check-policies`, #283) and expects its
+ * `expected` decision. A file that is not in this format fails. `renox
+ * test` also runs the project's cases before the test files.
+ */
+export declare function policyCases(dir?: string): PolicyCase[];
+/** `policyCases` of the current project (`policies/tests/*.json`). */
+export declare const policies: () => PolicyCase[];
+/** A module change on a scratch copy of the app: install, then upgrade with the returned handle. */
+export interface ModuleHandle extends ModuleChange {
+    /** Re-install from `source`; `version` defaults to `^<version of its module.toml>`. */
+    upgrade(source: string, version?: string): Promise<ModuleHandle>;
+}
+/**
+ * `installModule("notes", "path:fixtures/notes@1")`: `renox add` + `renox
+ * build` + `renox migrate` on a scratch copy of the app and a scratch
+ * tenant file. `upgrade(source)` does it again on the same copy and file:
+ * what `renox check` reports then (drift, broken contracts) is the upgrade
+ * test.
+ */
+export declare function installModule(name: string, source: string, options?: {
+    project?: string;
+    version?: string;
+}): Promise<ModuleHandle>;
+/** Alias of `ModuleHandle.upgrade` for symmetry: `upgradeModule(installed, "path:…@2")`. */
+export declare const upgradeModule: (installed: ModuleHandle, source: string, version?: string) => Promise<ModuleHandle>;

package/dist/test.js

@@ -0,0 +1,381 @@
+// `@renoxium/sdk/test` (#238; docs/12-developer-experience.md, "renox test"):
+// helpers for `tests/*.test.ts` of an app or a module, run by `renox test`
+// on the same prebuilt renox-worker as `renox dev`, one temporary tenant
+// file per test file.
+//
+//   import { app, snapshot } from "@renoxium/sdk/test";
+//   const t = await app();                         // fresh worker + tenant file for this file
+//   await t.service("notes").add("hello");         // through the broker (a test-only route)
+//   const { html } = await t.as("bob").page("/notes/");
+//   snapshot(html, { role: "admin" });
+//
+// Bun-only (bun:test, bun:sqlite): not part of the runtime-neutral SDK
+// surface, and never loaded by tenant code in production.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { Database } from "bun:sqlite";
+import { afterAll, expect, test } from "bun:test";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+async function harness() {
+    const path = process.env.RENOX_TEST_HARNESS ?? join(import.meta.dir, "../../cli/src/lib/test-harness.ts");
+    if (!existsSync(path))
+        throw new Error("@renoxium/sdk/test: run the tests with `renox test` (RENOX_TEST_HARNESS is not set)");
+    return (await import(__rewriteRelativeImportExtension(path)));
+}
+/** The spec `renox test` prepared, or one built now for the current project (`bun test` with RENOX_WORKER_PATH). */
+async function spec(h, project) {
+    const file = process.env.RENOX_TEST_SPEC;
+    if (file)
+        return JSON.parse(readFileSync(file, "utf8"));
+    const worker = process.env.RENOX_WORKER_PATH;
+    if (!worker)
+        throw new Error("@renoxium/sdk/test: run the tests with `renox test`, or set RENOX_WORKER_PATH");
+    return h.prepare(project, [], worker);
+}
+/** The error a service threw, as the broker reported it. */
+export class ServiceError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "ServiceError";
+    }
+}
+/** Reads `body` as an SSE stream: comments and `retry:` are skipped. */
+function sseStream(res, abort) {
+    const queue = [];
+    const waiters = [];
+    let ended = false;
+    const push = (e) => {
+        const w = waiters.shift();
+        if (w)
+            w(e);
+        else if (e)
+            queue.push(e);
+    };
+    void (async () => {
+        const reader = res.body?.getReader();
+        if (!reader)
+            return;
+        const dec = new TextDecoder();
+        let buf = "";
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buf += dec.decode(value, { stream: true });
+                let cut;
+                while ((cut = buf.indexOf("\n\n")) >= 0) {
+                    const block = buf.slice(0, cut);
+                    buf = buf.slice(cut + 2);
+                    let id = null;
+                    let event = null;
+                    const data = [];
+                    for (const line of block.split("\n")) {
+                        if (line.startsWith(":"))
+                            continue;
+                        const i = line.indexOf(":");
+                        const field = i < 0 ? line : line.slice(0, i);
+                        const v = i < 0 ? "" : line.slice(i + 1).replace(/^ /u, "");
+                        if (field === "id")
+                            id = v;
+                        else if (field === "event")
+                            event = v;
+                        else if (field === "data")
+                            data.push(v);
+                    }
+                    if (data.length || event !== null)
+                        push({ id, event, data: data.join("\n") });
+                }
+            }
+        }
+        catch {
+            // aborted
+        }
+        ended = true;
+        while (waiters.length)
+            push(null);
+    })();
+    return {
+        status: res.status,
+        headers: res.headers,
+        next(ms = 2000) {
+            const e = queue.shift();
+            if (e)
+                return Promise.resolve(e);
+            if (ended)
+                return Promise.resolve(null);
+            return new Promise((resolve) => {
+                const w = (x) => {
+                    clearTimeout(timer);
+                    resolve(x);
+                };
+                const timer = setTimeout(() => {
+                    const i = waiters.indexOf(w);
+                    if (i >= 0)
+                        waiters.splice(i, 1);
+                    resolve(null);
+                }, ms);
+                waiters.push(w);
+            });
+        },
+        pending: () => queue.splice(0),
+        close: () => abort.abort(),
+    };
+}
+function wsStream(socket) {
+    const queue = [];
+    const waiters = [];
+    let ended = false;
+    let resolveClosed = () => { };
+    const closed = new Promise((r) => (resolveClosed = r));
+    socket.addEventListener("message", (e) => {
+        const text = typeof e.data === "string" ? e.data : new TextDecoder().decode(e.data);
+        const w = waiters.shift();
+        if (w)
+            w(text);
+        else
+            queue.push(text);
+    });
+    socket.addEventListener("close", (e) => {
+        ended = true;
+        while (waiters.length)
+            waiters.shift()(null);
+        resolveClosed(e.code);
+    });
+    const stream = {
+        next(ms = 2000) {
+            const m = queue.shift();
+            if (m !== undefined)
+                return Promise.resolve(m);
+            if (ended)
+                return Promise.resolve(null);
+            return new Promise((resolve) => {
+                const w = (x) => {
+                    clearTimeout(timer);
+                    resolve(x);
+                };
+                const timer = setTimeout(() => {
+                    const i = waiters.indexOf(w);
+                    if (i >= 0)
+                        waiters.splice(i, 1);
+                    resolve(null);
+                }, ms);
+                waiters.push(w);
+            });
+        },
+        send: (text) => socket.send(text),
+        closed,
+        close: () => socket.close(),
+    };
+    return new Promise((resolve) => {
+        if (socket.readyState === WebSocket.OPEN)
+            resolve(stream);
+        socket.addEventListener("open", () => resolve(stream));
+        socket.addEventListener("close", () => resolve(stream));
+    });
+}
+function remember(jar, res) {
+    for (const c of res.headers.getSetCookie()) {
+        const [pair] = c.split(";");
+        const eq = (pair ?? "").indexOf("=");
+        if (eq > 0)
+            jar.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());
+    }
+}
+/**
+ * A fresh worker and tenant file for this test file (stopped after it):
+ * migrations applied, then `seeds/*.sql` and `renox test --seed` files.
+ */
+export async function app(options = {}) {
+    const h = await harness();
+    const s = await spec(h, options.project ?? process.env.RENOX_TEST_PROJECT ?? process.cwd());
+    const w = await h.startTestWorker(s);
+    afterAll(() => w.stop());
+    const jars = new Map();
+    const jarOf = (user) => {
+        let j = jars.get(user);
+        if (j === undefined) {
+            j = new Map();
+            jars.set(user, j);
+        }
+        return j;
+    };
+    const sqlite = new Database(w.db, { readonly: true });
+    afterAll(() => sqlite.close());
+    const make = (user) => {
+        const send = async (method, path, init = {}) => {
+            const jar = jarOf(user);
+            const headers = { host: w.host, accept: "text/html", ...init.headers };
+            // An explicit `cookie` header is sent as given (a replayed token); else the user's jar.
+            if (jar.size && init.headers?.cookie === undefined)
+                headers.cookie = [...jar].map(([k, v]) => `${k}=${v}`).join("; ");
+            let body;
+            if (typeof init.body === "string")
+                body = init.body;
+            else if (init.body !== undefined) {
+                body = JSON.stringify(init.body);
+                headers["content-type"] ??= "application/json";
+            }
+            const res = await fetch(`${w.base}${path}`, { method, headers, redirect: "manual", ...(body !== undefined ? { body } : {}) });
+            remember(jar, res);
+            const text = await res.text();
+            return { status: res.status, headers: res.headers, html: text, json: () => JSON.parse(text) };
+        };
+        const self = {
+            request: send,
+            async ws(path, o = {}) {
+                const jar = jarOf(user);
+                const headers = { host: w.host, origin: `https://${w.host}`, ...o.headers };
+                if (jar.size && o.headers?.cookie === undefined)
+                    headers.cookie = [...jar].map(([k, v]) => `${k}=${v}`).join("; ");
+                // Bun's WebSocket takes request headers (the cookie, the Host the cell routes by).
+                const socket = new WebSocket(`${w.base.replace(/^http/u, "ws")}${path}`, { headers });
+                afterAll(() => socket.close());
+                return wsStream(socket);
+            },
+            async sse(path, o = {}) {
+                const jar = jarOf(user);
+                const headers = { host: w.host, accept: "text/event-stream", ...o.headers };
+                if (jar.size && o.headers?.cookie === undefined)
+                    headers.cookie = [...jar].map(([k, v]) => `${k}=${v}`).join("; ");
+                const abort = new AbortController();
+                const res = await fetch(`${w.base}${path}`, { headers, redirect: "manual", signal: abort.signal });
+                afterAll(() => abort.abort());
+                return sseStream(res, abort);
+            },
+            page: (path, o) => (o?.user ? make(o.user) : self).request("GET", path),
+            async action(path, name, form, o) {
+                const as = o?.user ? make(o.user) : self;
+                const jar = jarOf(o?.user ?? user);
+                if (!jar.has("__Host-renox_csrf"))
+                    await as.request("GET", path);
+                const token = jar.get("__Host-renox_csrf") ?? "";
+                const body = new URLSearchParams({ ...form }).toString();
+                return as.request("POST", `${path}?/${name}`, { headers: { "content-type": "application/x-www-form-urlencoded", "x-renox-csrf": token }, body });
+            },
+            service: (module) => new Proxy({}, {
+                get: (_t, service) => async (...args) => {
+                    const r = await send("POST", h.SERVICE_PATH, { body: { module, service: String(service), args } });
+                    const out = r.json();
+                    if (!out.ok)
+                        throw new ServiceError(out.error?.message ?? "service failed", out.error?.code ?? null, out.error?.details ?? null);
+                    return out.value;
+                },
+            }),
+            db: { query: (sql, params = []) => sqlite.query(sql).all(...params) },
+            dbFile: w.db,
+            as: (other) => make(other),
+            cookie: (name, value) => {
+                const jar = jarOf(user);
+                if (value !== undefined)
+                    jar.set(name, value);
+                return jar.get(name);
+            },
+            logs: () => w.logs(),
+            meters: () => w.meters(),
+            stop: () => w.stop(),
+        };
+        return self;
+    };
+    return make("anonymous");
+}
+/**
+ * The page's HTML without what changes per request (request id, deployment,
+ * nonces, CSRF tokens, session ids), matched against the snapshot named by
+ * `role`. Returns the normalized HTML.
+ */
+export function snapshot(html, options) {
+    const normalized = html
+        .replace(/(<meta name="renox-request-id" content=")[^"]*/gu, "$1<request-id>")
+        .replace(/(<meta name="renox-deployment" content=")[^"]*/gu, "$1<deployment>")
+        .replace(/nonce="[^"]*"/gu, 'nonce="<nonce>"')
+        .replace(/(name="_csrf"[^>]*value=")[^"]*/gu, "$1<csrf>")
+        .replace(/(value=")[^"]*("[^>]*name="_csrf")/gu, "$1<csrf>$2")
+        .replace(/("x-renox-csrf"\s*:\s*")[^"]*/gu, "$1<csrf>")
+        .replace(/\b[0-9A-HJKMNP-TV-Z]{26}\b/gu, "<ulid>")
+        .replace(/(\?v=)[0-9a-f]{16}/gu, "$1<version>");
+    expect(normalized).toMatchSnapshot(`role: ${options.role}`);
+    return normalized;
+}
+const isCase = (v) => {
+    const c = v;
+    return (typeof c === "object" &&
+        c !== null &&
+        typeof c.action === "string" &&
+        typeof c.principal?.type === "string" &&
+        typeof c.principal?.id === "string" &&
+        (c.resource === undefined || typeof c.resource?.type === "string") &&
+        (c.expected === "allow" || c.expected === "deny"));
+};
+/**
+ * Reads `policies/tests/*.json` (each an array of cases, or `{ cases: [...] }`)
+ * and registers one test per case that evaluates it with the engine the
+ * cell builds (`renox-worker check-policies`, #283) and expects its
+ * `expected` decision. A file that is not in this format fails. `renox
+ * test` also runs the project's cases before the test files.
+ */
+export function policyCases(dir = join(process.env.RENOX_TEST_PROJECT ?? process.cwd(), "policies", "tests")) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir).filter((n) => n.endsWith(".json")).sort()) {
+        const raw = JSON.parse(readFileSync(join(dir, f), "utf8"));
+        const list = Array.isArray(raw) ? raw : raw.cases;
+        if (!Array.isArray(list) || !list.every(isCase))
+            throw new Error(`policies/tests/${f}: expected [{ principal, action, resource, expected: "allow" | "deny" }]`);
+        for (const c of list)
+            out.push(c);
+    }
+    if (out.length === 0)
+        return out;
+    // One evaluation for all the cases of `dir`, shared by their tests.
+    const project = join(dir, "..", "..");
+    let outcomes;
+    const evaluated = () => {
+        outcomes ??= (async () => {
+            const h = await harness();
+            return h.evaluatePolicies(await spec(h, process.env.RENOX_TEST_PROJECT ?? project), project);
+        })();
+        return outcomes;
+    };
+    out.forEach((c, i) => {
+        const who = `${c.principal.type}::${c.principal.id}${c.principal.roles?.length ? ` (${c.principal.roles.join(", ")})` : ""}`;
+        test(`policy: ${c.description ?? `${who} ${c.action} ${c.resource?.type ?? ""}`} -> ${c.expected}`, async () => {
+            const o = (await evaluated())[i];
+            expect(o?.result.allow ? "allow" : "deny").toBe(c.expected);
+        });
+    });
+    return out;
+}
+/** `policyCases` of the current project (`policies/tests/*.json`). */
+export const policies = () => policyCases();
+/**
+ * `installModule("notes", "path:fixtures/notes@1")`: `renox add` + `renox
+ * build` + `renox migrate` on a scratch copy of the app and a scratch
+ * tenant file. `upgrade(source)` does it again on the same copy and file:
+ * what `renox check` reports then (drift, broken contracts) is the upgrade
+ * test.
+ */
+export async function installModule(name, source, options = {}) {
+    const h = await harness();
+    const project = options.project ?? process.env.RENOX_TEST_PROJECT ?? process.cwd();
+    const worker = process.env.RENOX_WORKER_PATH ?? (process.env.RENOX_TEST_SPEC ? JSON.parse(readFileSync(process.env.RENOX_TEST_SPEC, "utf8")).worker : undefined);
+    const wrap = (r) => ({
+        ...r,
+        upgrade: async (next, version) => wrap(await h.changeModule(project, name, next, { project: r.project, db: r.db }, worker, version)),
+    });
+    return wrap(await h.changeModule(project, name, source, undefined, worker, options.version));
+}
+/** Alias of `ModuleHandle.upgrade` for symmetry: `upgradeModule(installed, "path:…@2")`. */
+export const upgradeModule = (installed, source, version) => installed.upgrade(source, version);

package/dist/tools.d.ts

@@ -0,0 +1,24 @@
+import type { Tool, ToolContext, ToolDefinition } from "./ctx.ts";
+import type { StandardSchemaV1 } from "./validate.ts";
+/** The JSON Schema keywords a tool input may use (validate.ts subset, ops.md section 19). */
+export declare const INPUT_KEYWORDS: readonly ["type", "properties", "required", "additionalProperties", "items", "minItems", "maxItems", "enum", "const", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "minLength", "maxLength", "pattern", "format", "description", "default", "anyOf", "nullable"];
+/**
+ * The JSON Schema of a Standard Schema input: through the Standard JSON
+ * Schema interface (`~standard.jsonSchema.input`, zod 4.2+), else a
+ * `toJSONSchema()` method, else the schema itself when it is plain JSON
+ * Schema. Throws a TypeError when none applies.
+ */
+export declare function toolInputSchema(schema: unknown): Record<string, unknown>;
+/**
+ * Declares a tool. Checks `name`, `description`, `action` and that the
+ * input is a Standard Schema; returns the definition with `confirm`
+ * defaulted to false.
+ *
+ * ```ts
+ * export default tool({ name: "create_invoice", description: "...", input: z.object({ ... }), action: "invoice.create", async run(ctx) { ... } });
+ * ```
+ */
+export declare function tool<S extends StandardSchemaV1>(def: Omit<ToolDefinition<StandardSchemaV1.InferOutput<S>>, "input" | "run"> & {
+    input: S;
+    run(ctx: ToolContext<StandardSchemaV1.InferOutput<S>>): unknown;
+}): Tool<StandardSchemaV1.InferOutput<S>>;

package/dist/tools.js

@@ -0,0 +1,105 @@
+// App MCP tools (#284; docs/contracts/ops.md section 19). `tool()` checks a
+// tool's declaration and returns the `Tool` a `functions/tools/*.ts` (or a
+// module's `tools/*.ts`) default-exports. `renox build` imports the module,
+// takes `name`, `description`, `action` and `confirm`, and records
+// `toolInputSchema(tool.input)` as the route entry's `input`: the JSON
+// Schema of the input, restricted to the keywords the platform checks.
+/** `^[a-z][a-z0-9_]{0,63}$` (artifact.md 1.3, tool routes). */
+const NAME = /^[a-z][a-z0-9_]{0,63}$/u;
+const ACTION = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/u;
+/** The JSON Schema keywords a tool input may use (validate.ts subset, ops.md section 19). */
+export const INPUT_KEYWORDS = [
+    "type",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "minItems",
+    "maxItems",
+    "enum",
+    "const",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "format",
+    "description",
+    "default",
+    "anyOf",
+    "nullable",
+];
+const KEEP = new Set(INPUT_KEYWORDS);
+/** Values below which a number bound is the integer range zod adds, not the author's. */
+const SAFE = Number.MAX_SAFE_INTEGER;
+/** A JSON Schema reduced to `INPUT_KEYWORDS`, recursively; bounds at the safe-integer range are dropped. */
+function restrict(s) {
+    if (s === null || typeof s !== "object" || Array.isArray(s))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(s)) {
+        if (!KEEP.has(k))
+            continue;
+        if ((k === "minimum" || k === "maximum") && typeof v === "number" && Math.abs(v) >= SAFE)
+            continue;
+        if (k === "properties" && v && typeof v === "object")
+            out[k] = Object.fromEntries(Object.entries(v).map(([p, x]) => [p, restrict(x)]));
+        else if (k === "items")
+            out[k] = restrict(v);
+        else if (k === "anyOf" && Array.isArray(v))
+            out[k] = v.map(restrict);
+        else if (k === "additionalProperties" && typeof v === "object")
+            out[k] = restrict(v);
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * The JSON Schema of a Standard Schema input: through the Standard JSON
+ * Schema interface (`~standard.jsonSchema.input`, zod 4.2+), else a
+ * `toJSONSchema()` method, else the schema itself when it is plain JSON
+ * Schema. Throws a TypeError when none applies.
+ */
+export function toolInputSchema(schema) {
+    const std = schema?.["~standard"];
+    let raw;
+    if (typeof std?.jsonSchema?.input === "function")
+        raw = std.jsonSchema.input({ target: "draft-2020-12" });
+    else if (typeof schema?.toJSONSchema === "function")
+        raw = schema.toJSONSchema();
+    else if (schema && typeof schema === "object" && typeof schema.type === "string" && !std)
+        raw = schema;
+    else
+        throw new TypeError("tool: the input schema cannot be described as JSON Schema (use zod 4, or a schema with ~standard.jsonSchema)");
+    const out = restrict(raw);
+    if (out.type !== "object")
+        throw new TypeError("tool: the input schema must describe an object");
+    return out;
+}
+/**
+ * Declares a tool. Checks `name`, `description`, `action` and that the
+ * input is a Standard Schema; returns the definition with `confirm`
+ * defaulted to false.
+ *
+ * ```ts
+ * export default tool({ name: "create_invoice", description: "...", input: z.object({ ... }), action: "invoice.create", async run(ctx) { ... } });
+ * ```
+ */
+export function tool(def) {
+    if (!NAME.test(def.name))
+        throw new TypeError(`tool: name must match ^[a-z][a-z0-9_]{0,63}$, got ${JSON.stringify(def.name)}`);
+    if (typeof def.description !== "string" || def.description.length === 0 || def.description.length > 200)
+        throw new TypeError("tool: description is 1 to 200 characters");
+    if (!ACTION.test(def.action))
+        throw new TypeError(`tool: action must be <resource>.<verb>, got ${JSON.stringify(def.action)}`);
+    if (typeof def.input?.["~standard"]?.validate !== "function")
+        throw new TypeError("tool: input must be a Standard Schema (zod, valibot, arktype, ...)");
+    if (typeof def.run !== "function")
+        throw new TypeError("tool: run must be a function");
+    if (def.confirm !== undefined && typeof def.confirm !== "boolean")
+        throw new TypeError("tool: confirm is a boolean");
+    return { ...def, input: def.input, confirm: def.confirm ?? false };
+}