@zmdb/ai 1.0.0-beta.1

package/src/chat/index.ts

@@ -0,0 +1,202 @@
+import type { ToolSpec } from '../index.js';
+import { invokeTool } from '../tool-runtime.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 function defineTools<const I extends ToolInputs, const R extends LinkedRegistry<I>>(
+  tools: R & LinkedRegistry<I>,
+): R {
+  return tools;
+}
+
+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;
+  }[];
+}
+
+interface RunState {
+  readonly messages: ChatMessage[];
+  readonly declined: ToolCall[];
+  readonly errors: {
+    readonly callId: string;
+    readonly name: string;
+    readonly errorId: string;
+    readonly error: unknown;
+  }[];
+  turns: number;
+  toolCalls: number;
+}
+
+const DEFAULT_MAX_TOOL_CALLS_PER_TURN = 8;
+
+const toolErrorId = (): string =>
+  [...globalThis.crypto.getRandomValues(new Uint8Array(4))].map(byte => byte.toString(16).padStart(2, '0')).join('');
+
+const toolResult = (callId: string, content: string, isError?: boolean): ChatMessage =>
+  isError === undefined ? { role: 'tool', callId, content } : { role: 'tool', callId, content, isError };
+
+const finish = (state: RunState, stop: RunResult['stop'], budget: number): RunResult => ({
+  messages: state.messages,
+  stop,
+  turns: state.turns,
+  toolCalls: state.toolCalls,
+  budget,
+  declined: state.declined,
+  errors: state.errors,
+});
+
+export async function run<const I extends ToolInputs, R extends LinkedRegistry<I>>(
+  driver: ChatDriver,
+  messages: readonly ChatMessage[],
+  tools: R & LinkedRegistry<I>,
+  opts: RunOptionsFor<R>,
+): Promise<RunResult> {
+  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: RunState = {
+    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);
+}

package/src/compiler.ts

@@ -0,0 +1,2 @@
+export { ToolSpecRefusalError, toolSchemaForProvider } from './providers.js';
+export type { ToolSpecRefusal } from './providers.js';

package/src/http/caller.ts

@@ -0,0 +1,132 @@
+// Runtime binding for provider-neutral OpenAPI tools owned by @zmdb/ai.
+import {
+  OpenApiHttpError,
+  type BoundOpenApiTool,
+  type OpenApiCallerOptions,
+  type OpenApiGeneratedTool,
+  type OpenApiToolRequest,
+} from './types.js';
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 1_048_576;
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function positive(name: string, value: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive safe integer`);
+}
+
+function canonicalBase(value: string): URL {
+  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: string, allowlist: readonly string[]): URL {
+  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: unknown, name: string): string {
+  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: unknown, name: string): string {
+  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: URL, request: OpenApiToolRequest, input: Readonly<Record<string, unknown>>): URL {
+  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: OpenApiToolRequest, input: Readonly<Record<string, unknown>>): string | undefined {
+  if (!request.hasBody) return undefined;
+  const body: Record<string, unknown> = {};
+  for (const name of request.bodyParameters) {
+    if (input[name] !== undefined) body[name] = input[name];
+  }
+  return JSON.stringify(body);
+}
+
+async function responseBody(response: Response, maximum: number): Promise<string> {
+  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: Response, body: string): unknown {
+  if (body === '') return undefined;
+  const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+  return contentType.includes('json') ? JSON.parse(body) : body;
+}
+
+export function bindOpenApiTool<T>(tool: OpenApiGeneratedTool<T>, options: OpenApiCallerOptions): BoundOpenApiTool<T> {
+  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: T): Promise<unknown> {
+      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);
+    },
+  };
+}

package/src/http/generate.ts

@@ -0,0 +1,218 @@
+// Checked-in source generation for the public @zmdb/ai/http boundary.
+import { compileOpenApiTools, type CompiledOpenApiTool } from './parse.js';
+import type { OpenApiToolsOptions } from './types.js';
+
+type ConstraintTag = 'Max' | 'MaxLength' | 'Min' | 'MinLength' | 'Pattern';
+
+interface RenderContext {
+  readonly tags: Set<ConstraintTag>;
+  readonly path: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function stringLiteral(value: string): string {
+  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n').replaceAll('\r', '\\r')}'`;
+}
+
+function literal(value: unknown): string {
+  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: RenderContext, name: ConstraintTag, value: unknown): string | undefined {
+  if (typeof value !== (name === 'Pattern' ? 'string' : 'number')) return undefined;
+  context.tags.add(name);
+  return `${name}<${literal(value)}>`;
+}
+
+function constrained(base: string, schema: Record<string, unknown>, context: RenderContext): string {
+  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: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : stringLiteral(name);
+}
+
+function requiredNames(schema: Record<string, unknown>): ReadonlySet<string> {
+  const value = schema['required'];
+  return new Set(Array.isArray(value) ? value.filter(name => typeof name === 'string') : []);
+}
+
+function objectType(schema: Record<string, unknown>, context: RenderContext): string {
+  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: Record<string, unknown>, key: 'anyOf' | 'oneOf', context: RenderContext): string | undefined {
+  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: Record<string, unknown>, context: RenderContext): string {
+  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: string;
+  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: string, used: Set<string>): string {
+  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: string): string {
+  return `${type[0]?.toLowerCase() ?? 't'}${type.slice(1).replace(/Arguments$/, 'Tool')}`;
+}
+
+function renderValue(value: unknown, depth = 0): string {
+  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: CompiledOpenApiTool, type: string, variable: string, tags: Set<ConstraintTag>): string {
+  const context: RenderContext = { 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: unknown, options: OpenApiToolsOptions = {}): string {
+  const tools = compileOpenApiTools(document, options);
+  const tags = new Set<ConstraintTag>();
+  const names = new Set<string>();
+  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}`;
+}

package/src/http/index.ts

@@ -0,0 +1,16 @@
+// Public @zmdb/ai/http surface.
+export { bindOpenApiTool } from './caller.js';
+export { generateOpenApiToolsModule } from './generate.js';
+export { toolsFromOpenApi } from './parse.js';
+export {
+  OpenApiHttpError,
+  ToolSpecRefusalError,
+  type BoundOpenApiTool,
+  type OpenApiCallerOptions,
+  type OpenApiGeneratedTool,
+  type OpenApiOperationIdentity,
+  type OpenApiToolRequest,
+  type OpenApiToolsOptions,
+  type ToolProvider,
+  type ToolSpecRefusal,
+} from './types.js';