@zmdb/ai 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,10 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+@zmdb/ai is free software licensed under the GNU General Public License,
+version 3 or (at your option) any later version.
+
+The complete license text is published by the Free Software Foundation at:
+https://www.gnu.org/licenses/gpl-3.0.txt
+
+SPDX-License-Identifier: GPL-3.0-or-later

package/README.md

@@ -0,0 +1,56 @@
+# @zmdb/ai
+
+`@zmdb/ai` provides provider-neutral tool documents, parsing, bounded chat orchestration, shared tool invocation, and OpenAPI-derived tools. Choosing a provider dialect changes a document shape; it
+does not install an SDK or make a network request.
+
+It is part of [zmdb](https://github.com/ambasta/zmdb). The root, chat, HTTP, compiler, and tool-runtime entry points are physically owned by this package. The dependency direction is `@zmdb/ai` →
+`@zmdb/schema`; schema-core never imports or re-exports this package.
+
+## Install
+
+```bash
+yarn add @zmdb/ai@1.0.0-beta.1
+```
+
+> **Prerelease** (`1.0.0-beta.1`). Requires **Node.js 26+** and is **ESM-only**. Ships built ESM `.js` + `.d.ts` under `./dist`.
+
+## Entry points
+
+- Tool documents and parsing: `@zmdb/ai`
+- Bounded provider-neutral chat loop: `@zmdb/ai/chat`
+- Build-time provider document compiler: `@zmdb/ai/compiler`
+- OpenAPI-derived tools and allowlisted callers: `@zmdb/ai/http`
+- Shared invocation machinery for integrations: `@zmdb/ai/tool-runtime`
+
+The only runtime dependency is `@zmdb/schema`. This package has no external dependency or peer dependency, and does not export Anthropic, LangChain, Vercel AI SDK, or MCP integrations.
+
+## Optional integrations
+
+- Anthropic chat driver: `yarn add @zmdb/ai-anthropic@1.0.0-beta.1 @anthropic-ai/sdk@0.124.0`
+- LangChain tool adapter: `yarn add @zmdb/ai-langchain@1.0.0-beta.1 @langchain/core@^1.2.9`
+- Vercel AI SDK tool adapter: `yarn add @zmdb/ai-vercel@1.0.0-beta.1 ai@^7.0.93`
+- MCP client and server cores: `yarn add @zmdb/mcp@1.0.0-beta.1`
+
+The three SDK/framework packages declare their external dependency as an optional peer. Applications that install only `@zmdb/ai` or `@zmdb/mcp` do not install an Anthropic, LangChain, Vercel AI, or
+MCP SDK.
+
+## Migrating from schema-core
+
+There are no compatibility aliases in `@zmdb/schema`. Replace every removed subpath from that package directly:
+
+| Removed schema-core subpath | Final import                                                                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/llm`                      | `@zmdb/ai` for tool APIs; `@zmdb/schema/openapi` for `toJsonSchema`; use the explicit chat, HTTP, and MCP entries below for former star exports |
+| `/llm/chat`                 | `@zmdb/ai/chat`; `anthropicDriver` and its types move to `@zmdb/ai-anthropic`                                                                   |
+| `/llm/http`                 | `@zmdb/ai/http`                                                                                                                                 |
+| `/llm/langchain`            | `@zmdb/ai-langchain`                                                                                                                            |
+| `/llm/ai-sdk`               | `@zmdb/ai-vercel`                                                                                                                               |
+| `/llm/mcp`                  | `@zmdb/mcp`                                                                                                                                     |
+
+## Documentation
+
+Full docs: **https://ambasta.github.io/zmdb/docs/llm-strategy.html**
+
+## License
+
+GNU General Public License v3.0 or later (GPL-3.0-or-later) — see [LICENSE](./LICENSE).

package/dist/chat/index.d.ts

@@ -0,0 +1,81 @@
+import type { ToolSpec } from '../index.js';
+export type ChatMessage = {
+    readonly role: 'system';
+    readonly content: string;
+} | {
+    readonly role: 'user';
+    readonly content: string;
+} | {
+    readonly role: 'assistant';
+    readonly content: string;
+    readonly toolCalls?: readonly ToolCall[];
+    readonly provider?: readonly ProviderPassthrough[];
+} | {
+    readonly role: 'tool';
+    readonly callId: string;
+    readonly content: string;
+    readonly isError?: boolean;
+};
+export interface ToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly args: unknown;
+}
+export interface ProviderPassthrough {
+    readonly kind: string;
+    readonly raw: unknown;
+}
+export interface ChatDriver {
+    next(messages: readonly ChatMessage[], tools: readonly ToolSpec[]): Promise<ChatMessage>;
+}
+type ToolHandler<T> = {
+    bivarianceHack(input: T, identity?: unknown): unknown | PromiseLike<unknown>;
+}['bivarianceHack'];
+export interface ToolEntry<T> {
+    readonly spec: ToolSpec;
+    readonly validate: (args: unknown) => T;
+    readonly handler: ToolHandler<T>;
+    readonly effectful?: boolean;
+}
+export type ToolRegistry = Readonly<Record<string, ToolEntry<unknown>>>;
+type ToolInputs = Readonly<Record<string, unknown>>;
+interface LinkedToolEntry<T> {
+    readonly spec: ToolSpec;
+    readonly validate: (args: unknown) => T;
+    readonly handler: (input: T, identity?: unknown) => unknown | PromiseLike<unknown>;
+    readonly effectful?: boolean;
+}
+type LinkedRegistry<I extends ToolInputs> = {
+    readonly [K in keyof I]: LinkedToolEntry<I[K]>;
+};
+export declare function defineTools<const I extends ToolInputs, const R extends LinkedRegistry<I>>(tools: R & LinkedRegistry<I>): R;
+export type HasEffectful<R> = {
+    [K in keyof R]: R[K] extends {
+        readonly effectful: false;
+    } ? never : K;
+}[keyof R] extends never ? false : true;
+export interface RunOptions {
+    readonly maxTurns: number;
+    readonly maxToolCallsPerTurn?: number;
+    readonly approve?: (call: ToolCall) => Promise<boolean>;
+}
+export type RunOptionsFor<R extends Readonly<Record<string, unknown>>> = HasEffectful<R> extends true ? RunOptions & {
+    readonly approve: (call: ToolCall) => Promise<boolean>;
+} : RunOptions;
+export interface RunResult {
+    readonly messages: readonly ChatMessage[];
+    readonly stop: 'complete' | 'max-turns' | 'max-tool-calls';
+    readonly turns: number;
+    readonly toolCalls: number;
+    readonly budget: number;
+    readonly declined: readonly ToolCall[];
+    readonly errors: readonly {
+        readonly callId: string;
+        readonly name: string;
+        readonly errorId: string;
+        readonly error: unknown;
+    }[];
+}
+export declare function run<const I extends ToolInputs, R extends LinkedRegistry<I>>(driver: ChatDriver, messages: readonly ChatMessage[], tools: R & LinkedRegistry<I>, opts: RunOptionsFor<R>): Promise<RunResult>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/chat/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chat/index.ts"],"names":[],"mappings":"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"}

package/dist/chat/index.js

@@ -0,0 +1,86 @@
+import { invokeTool } from '../tool-runtime.js';
+export function defineTools(tools) {
+    return tools;
+}
+const DEFAULT_MAX_TOOL_CALLS_PER_TURN = 8;
+const toolErrorId = () => [...globalThis.crypto.getRandomValues(new Uint8Array(4))].map(byte => byte.toString(16).padStart(2, '0')).join('');
+const toolResult = (callId, content, isError) => isError === undefined ? { role: 'tool', callId, content } : { role: 'tool', callId, content, isError };
+const finish = (state, stop, budget) => ({
+    messages: state.messages,
+    stop,
+    turns: state.turns,
+    toolCalls: state.toolCalls,
+    budget,
+    declined: state.declined,
+    errors: state.errors,
+});
+export async function run(driver, messages, tools, opts) {
+    if (!Number.isSafeInteger(opts.maxTurns) || opts.maxTurns <= 0) {
+        throw new RangeError('maxTurns must be a positive safe integer');
+    }
+    const maxToolCallsPerTurn = opts.maxToolCallsPerTurn ?? DEFAULT_MAX_TOOL_CALLS_PER_TURN;
+    if (!Number.isSafeInteger(maxToolCallsPerTurn) || maxToolCallsPerTurn <= 0) {
+        throw new RangeError('maxToolCallsPerTurn must be a positive safe integer');
+    }
+    const entries = Object.entries(tools);
+    const firstEffectful = entries.find(([, entry]) => entry.effectful !== false);
+    if (firstEffectful !== undefined && opts.approve === undefined) {
+        throw new Error(`approve is required for effectful tool ${firstEffectful[0]}`);
+    }
+    const budget = opts.maxTurns * maxToolCallsPerTurn;
+    const state = {
+        messages: [...messages],
+        declined: [],
+        errors: [],
+        turns: 0,
+        toolCalls: 0,
+    };
+    const specs = entries.map(([, entry]) => entry.spec);
+    while (state.turns < opts.maxTurns) {
+        const answer = await driver.next(state.messages, specs);
+        state.messages.push(answer);
+        state.turns += 1;
+        const calls = answer.role === 'assistant' ? (answer.toolCalls ?? []) : [];
+        if (calls.length === 0)
+            return finish(state, 'complete', budget);
+        if (calls.length > maxToolCallsPerTurn)
+            return finish(state, 'max-tool-calls', budget);
+        for (const call of calls) {
+            state.toolCalls += 1;
+            const entry = Object.hasOwn(tools, call.name) ? tools[call.name] : undefined;
+            if (entry === undefined) {
+                state.messages.push(toolResult(call.id, `unknown tool ${call.name}`, true));
+                continue;
+            }
+            if (entry.effectful !== false) {
+                const approved = await opts.approve?.(call);
+                if (approved !== true) {
+                    state.declined.push(call);
+                    state.messages.push(toolResult(call.id, 'declined by the operator', true));
+                    continue;
+                }
+            }
+            const invocation = await invokeTool(entry, call.args);
+            if (invocation.kind === 'validation-error') {
+                const { content } = invocation;
+                if (content !== undefined) {
+                    state.messages.push(toolResult(call.id, content, true));
+                    continue;
+                }
+                const id = toolErrorId();
+                state.errors.push({ callId: call.id, name: call.name, errorId: id, error: invocation.error });
+                state.messages.push(toolResult(call.id, `tool ${call.name} failed (${id})`, true));
+                continue;
+            }
+            if (invocation.kind === 'handler-error') {
+                const id = toolErrorId();
+                state.errors.push({ callId: call.id, name: call.name, errorId: id, error: invocation.error });
+                state.messages.push(toolResult(call.id, `tool ${call.name} failed (${id})`, true));
+                continue;
+            }
+            state.messages.push(toolResult(call.id, invocation.content));
+        }
+    }
+    return finish(state, 'max-turns', budget);
+}
+//# sourceMappingURL=index.js.map

package/dist/chat/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chat/index.ts"],"names":[],"mappings":"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"}

package/dist/compiler.d.ts

@@ -0,0 +1,3 @@
+export { ToolSpecRefusalError, toolSchemaForProvider } from './providers.js';
+export type { ToolSpecRefusal } from './providers.js';
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/compiler.js

@@ -0,0 +1,2 @@
+export { ToolSpecRefusalError, toolSchemaForProvider } from './providers.js';
+//# sourceMappingURL=compiler.js.map

package/dist/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/http/caller.d.ts

@@ -0,0 +1,3 @@
+import { type BoundOpenApiTool, type OpenApiCallerOptions, type OpenApiGeneratedTool } from './types.js';
+export declare function bindOpenApiTool<T>(tool: OpenApiGeneratedTool<T>, options: OpenApiCallerOptions): BoundOpenApiTool<T>;
+//# sourceMappingURL=caller.d.ts.map

package/dist/http/caller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller.d.ts","sourceRoot":"","sources":["../../src/http/caller.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAE1B,MAAM,YAAY,CAAC;AAgGpB,wBAAgB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,gBAAgB,CAAC,CAAC,CAAC,CA4BpH"}

package/dist/http/caller.js

@@ -0,0 +1,128 @@
+// Runtime binding for provider-neutral OpenAPI tools owned by @zmdb/ai.
+import { OpenApiHttpError, } from './types.js';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 1_048_576;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function positive(name, value) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new RangeError(`${name} must be a positive safe integer`);
+}
+function canonicalBase(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new TypeError('OpenAPI tool baseUrl must use http or https');
+    }
+    if (url.username !== '' || url.password !== '') {
+        throw new TypeError('OpenAPI tool baseUrl must not contain credentials');
+    }
+    if (url.search !== '' || url.hash !== '') {
+        throw new TypeError('OpenAPI tool baseUrl must not contain a query or fragment');
+    }
+    if (!url.pathname.endsWith('/'))
+        url.pathname += '/';
+    return url;
+}
+function allowlistedBase(baseUrl, allowlist) {
+    const base = canonicalBase(baseUrl);
+    const allowed = allowlist.some(candidate => canonicalBase(candidate).href === base.href);
+    if (!allowed)
+        throw new Error(`OpenAPI tool base URL is not allowlisted: ${base.href}`);
+    return base;
+}
+function scalar(value, name) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (value === null)
+        return 'null';
+    throw new TypeError(`validated OpenAPI argument ${name} is not a URL scalar`);
+}
+function pathSegment(value, name) {
+    const segment = scalar(value, name);
+    if (segment === '.' || segment === '..') {
+        throw new RangeError(`validated OpenAPI argument ${name} is a URL dot segment`);
+    }
+    return encodeURIComponent(segment);
+}
+function requestUrl(base, request, input) {
+    let pathname = request.path;
+    for (const name of request.pathParameters) {
+        pathname = pathname.replaceAll(`{${name}}`, pathSegment(input[name], name));
+    }
+    if (/\{[^{}]+\}/.test(pathname))
+        throw new Error(`OpenAPI tool path still contains a placeholder: ${pathname}`);
+    const url = new URL(pathname.replace(/^\/+/, ''), base);
+    for (const name of request.queryParameters) {
+        const value = input[name];
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                url.searchParams.append(name, scalar(item, name));
+        }
+        else {
+            url.searchParams.append(name, scalar(value, name));
+        }
+    }
+    return url;
+}
+function requestBody(request, input) {
+    if (!request.hasBody)
+        return undefined;
+    const body = {};
+    for (const name of request.bodyParameters) {
+        if (input[name] !== undefined)
+            body[name] = input[name];
+    }
+    return JSON.stringify(body);
+}
+async function responseBody(response, maximum) {
+    const announced = response.headers.get('content-length');
+    if (announced !== null && Number(announced) > maximum) {
+        throw new RangeError(`OpenAPI tool response exceeds ${maximum} bytes`);
+    }
+    const body = await response.text();
+    if (new TextEncoder().encode(body).byteLength > maximum) {
+        throw new RangeError(`OpenAPI tool response exceeds ${maximum} bytes`);
+    }
+    return body;
+}
+function parseResponse(response, body) {
+    if (body === '')
+        return undefined;
+    const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+    return contentType.includes('json') ? JSON.parse(body) : body;
+}
+export function bindOpenApiTool(tool, options) {
+    const base = allowlistedBase(options.baseUrl, options.allowedBaseUrls);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    positive('timeoutMs', timeoutMs);
+    positive('maxResponseBytes', maxResponseBytes);
+    const fetch = options.fetch ?? globalThis.fetch;
+    return {
+        spec: tool.spec,
+        validate: tool.validate,
+        async handler(input) {
+            if (!isRecord(input))
+                throw new TypeError('generated OpenAPI validator returned a non-object');
+            const url = requestUrl(base, tool.request, input);
+            const body = requestBody(tool.request, input);
+            const headers = new Headers(options.headers);
+            if (body !== undefined && !headers.has('content-type'))
+                headers.set('content-type', 'application/json');
+            const response = await fetch(url, {
+                method: tool.request.method,
+                headers,
+                ...(body === undefined ? {} : { body }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const text = await responseBody(response, maxResponseBytes);
+            if (!response.ok)
+                throw new OpenApiHttpError(response.status, text);
+            return parseResponse(response, text);
+        },
+    };
+}
+//# sourceMappingURL=caller.js.map

package/dist/http/caller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caller.js","sourceRoot":"","sources":["../../src/http/caller.ts"],"names":[],"mappings":"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"}

package/dist/http/generate.d.ts

@@ -0,0 +1,7 @@
+import type { OpenApiToolsOptions } from './types.js';
+/**
+ * Render a checked-in TypeScript module. The generated `assert<T>` calls are
+ * deliberately left for `@zmdb/validator`'s existing build transform.
+ */
+export declare function generateOpenApiToolsModule(document: unknown, options?: OpenApiToolsOptions): string;
+//# sourceMappingURL=generate.d.ts.map

package/dist/http/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/http/generate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAmLtD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAgCvG"}

package/dist/http/generate.js

@@ -0,0 +1,205 @@
+// Checked-in source generation for the public @zmdb/ai/http boundary.
+import { compileOpenApiTools } from './parse.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringLiteral(value) {
+    return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n').replaceAll('\r', '\\r')}'`;
+}
+function literal(value) {
+    if (typeof value === 'string')
+        return stringLiteral(value);
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null)
+        return String(value);
+    throw new TypeError(`OpenAPI enum contains an unsupported literal at generation: ${String(value)}`);
+}
+function tag(context, name, value) {
+    if (typeof value !== (name === 'Pattern' ? 'string' : 'number'))
+        return undefined;
+    context.tags.add(name);
+    return `${name}<${literal(value)}>`;
+}
+function constrained(base, schema, context) {
+    const tags = [
+        tag(context, 'Min', schema['minimum']),
+        tag(context, 'Max', schema['maximum']),
+        tag(context, 'MinLength', schema['minLength']),
+        tag(context, 'MaxLength', schema['maxLength']),
+        tag(context, 'Pattern', schema['pattern']),
+    ].filter(value => value !== undefined);
+    return tags.length === 0 ? base : `${base} & ${tags.join(' & ')}`;
+}
+function propertyName(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : stringLiteral(name);
+}
+function requiredNames(schema) {
+    const value = schema['required'];
+    return new Set(Array.isArray(value) ? value.filter(name => typeof name === 'string') : []);
+}
+function objectType(schema, context) {
+    const properties = schema['properties'];
+    if (!isRecord(properties))
+        return 'Readonly<Record<never, never>>';
+    const required = requiredNames(schema);
+    const lines = Object.keys(properties)
+        .toSorted()
+        .map(name => {
+        const child = properties[name];
+        if (!isRecord(child))
+            throw new TypeError(`OpenAPI property ${context.path}.${name} is not a schema`);
+        const optional = required.has(name) ? '' : '?';
+        return `  readonly ${propertyName(name)}${optional}: ${schemaType(child, { ...context, path: `${context.path}.${name}` })};`;
+    });
+    return lines.length === 0 ? 'Readonly<Record<never, never>>' : `{\n${lines.join('\n')}\n}`;
+}
+function union(schema, key, context) {
+    const value = schema[key];
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .map((member, index) => {
+        if (!isRecord(member))
+            throw new TypeError(`OpenAPI ${key} member ${index} at ${context.path} is not a schema`);
+        return schemaType(member, { ...context, path: `${context.path}.${key}[${index}]` });
+    })
+        .join(' | ');
+}
+function schemaType(schema, context) {
+    const oneOf = union(schema, 'oneOf', context);
+    if (oneOf !== undefined)
+        return oneOf;
+    const anyOf = union(schema, 'anyOf', context);
+    if (anyOf !== undefined)
+        return anyOf;
+    const values = schema['enum'];
+    if (Array.isArray(values) && values.length > 0)
+        return values.map(literal).join(' | ');
+    const type = schema['type'];
+    if (Array.isArray(type)) {
+        return type
+            .map(member => schemaType({ ...schema, type: member }, context))
+            .filter((member, index, all) => all.indexOf(member) === index)
+            .join(' | ');
+    }
+    let result;
+    switch (type) {
+        case 'string':
+            result = constrained('string', schema, context);
+            break;
+        case 'integer':
+        case 'number':
+            result = constrained('number', schema, context);
+            break;
+        case 'boolean':
+            result = 'boolean';
+            break;
+        case 'null':
+            result = 'null';
+            break;
+        case 'array': {
+            const items = schema['items'];
+            if (!isRecord(items))
+                throw new TypeError(`OpenAPI array ${context.path} has no item schema`);
+            result = `readonly (${schemaType(items, { ...context, path: `${context.path}[]` })})[]`;
+            break;
+        }
+        case 'object':
+            result = objectType(schema, context);
+            break;
+        default:
+            result = isRecord(schema['properties']) ? objectType(schema, context) : 'unknown';
+    }
+    return schema['nullable'] === true && result !== 'null' ? `${result} | null` : result;
+}
+function typeName(operationId, used) {
+    const words = operationId.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const base = `${words.map(word => `${word[0]?.toUpperCase() ?? ''}${word.slice(1)}`).join('') || 'Tool'}Arguments`;
+    let candidate = /^[A-Za-z_$]/.test(base) ? base : `Tool${base}`;
+    let suffix = 2;
+    while (used.has(candidate)) {
+        candidate = `${base}${suffix}`;
+        suffix += 1;
+    }
+    used.add(candidate);
+    return candidate;
+}
+function variableName(type) {
+    return `${type[0]?.toLowerCase() ?? 't'}${type.slice(1).replace(/Arguments$/, 'Tool')}`;
+}
+function renderValue(value, depth = 0) {
+    if (typeof value === 'string')
+        return stringLiteral(value);
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null)
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        if (value.every(item => item === null || ['string', 'number', 'boolean'].includes(typeof item))) {
+            return `[${value.map(item => renderValue(item, depth + 1)).join(', ')}]`;
+        }
+        const indent = '  '.repeat(depth + 1);
+        return `[\n${value.map(item => `${indent}${renderValue(item, depth + 1)},`).join('\n')}\n${'  '.repeat(depth)}]`;
+    }
+    if (isRecord(value)) {
+        const entries = Object.entries(value);
+        if (entries.length === 0)
+            return '{}';
+        const indent = '  '.repeat(depth + 1);
+        return `{\n${entries
+            .map(([key, item]) => `${indent}${propertyName(key)}: ${renderValue(item, depth + 1)},`)
+            .join('\n')}\n${'  '.repeat(depth)}}`;
+    }
+    throw new TypeError(`cannot render generated OpenAPI value: ${String(value)}`);
+}
+function renderTool(tool, type, variable, tags) {
+    const context = { tags, path: tool.spec.name };
+    const schema = {
+        type: 'object',
+        properties: tool.argumentSchemas,
+        required: tool.required,
+    };
+    const args = schemaType(schema, context);
+    const validationType = Object.keys(tool.argumentSchemas).length === 0 ? 'OpenApiNoArguments' : type;
+    return `export type ${type} = ${args};
+
+export const ${variable}: OpenApiGeneratedTool<${type}> = {
+  spec: ${renderValue(tool.spec, 1)},
+  request: ${renderValue(tool.request, 1)},
+  validate: (input: unknown): ${type} => assert<${validationType}>(input),
+};`;
+}
+/**
+ * Render a checked-in TypeScript module. The generated `assert<T>` calls are
+ * deliberately left for `@zmdb/validator`'s existing build transform.
+ */
+export function generateOpenApiToolsModule(document, options = {}) {
+    const tools = compileOpenApiTools(document, options);
+    const tags = new Set();
+    const names = new Set();
+    const rendered = tools.map(tool => {
+        const type = typeName(tool.spec.name, names);
+        return { tool, type, variable: variableName(type) };
+    });
+    const bodies = rendered.map(entry => renderTool(entry.tool, entry.type, entry.variable, tags));
+    const emptyArgumentsType = rendered.some(entry => Object.keys(entry.tool.argumentSchemas).length === 0)
+        ? `type OpenApiNoArguments = {
+  readonly __openApiNoArguments?: string;
+};
+
+`
+        : '';
+    const tagImport = tags.size === 0 ? '' : `import type { ${[...tags].toSorted().join(', ')} } from '@zmdb/schema/tags';\n`;
+    const registry = rendered.length === 0
+        ? 'export const openApiTools = {};\n'
+        : `export const openApiTools = {\n${rendered
+            .map(entry => `  ${propertyName(entry.tool.spec.name)}: ${entry.variable},`)
+            .join('\n')}\n};\n`;
+    return `// generated by @zmdb/ai/http — do not edit
+import type { OpenApiGeneratedTool } from '@zmdb/ai/http';
+${tagImport}import { assert } from '@zmdb/validator';
+
+${emptyArgumentsType}${bodies.join('\n\n')}
+
+${registry}`;
+}
+//# sourceMappingURL=generate.js.map