@nestjs/ai 0.0.0-stage → 0.0.2

package/dist/tools/ai-tools.service.d.ts

@@ -0,0 +1,77 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { DiscoveryService, ExternalContextCreator, MetadataScanner } from '@nestjs/core';
+import type { Schema, ToolSet } from 'ai';
+import type { AgentFunctionContext } from '../interfaces/agent-function.interface.js';
+import type { AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiCaller, AiToolSelection } from '../interfaces/ai-tool.interface.js';
+/** A method behind Nest's enhancers: called as `(input, context)`. */
+export type AiToolHandler = (input: unknown, context: AgentFunctionContext) => Promise<unknown>;
+/** An agent function of the application: a provider method with `@AgentFunction()`, offered to models as a tool. */
+export interface AiToolEntry {
+    name: string;
+    description?: string;
+    scopes?: string[];
+    /** The `ai` schema of its arguments. */
+    inputSchema: Schema<unknown>;
+    handler: AiToolHandler;
+    /** The provider class it is a method of. */
+    host: Function;
+    /** `Class.method`, for messages. */
+    where: string;
+}
+/** An agent function's progress (`ctx.reportProgress()`), which a streamed answer sends as a transient data chunk. */
+export interface AiToolProgress {
+    toolCallId: string;
+    toolName: string;
+    progress: number;
+    total?: number;
+    message?: string;
+}
+/**
+ * The application's agent functions: the `@AgentFunction()` methods of its providers (or of the `include` modules),
+ * found once at startup, each wrapped by Nest's enhancers with the context type `'ai'`, and called with an
+ * `AgentFunctionContext`. `select()` turns some of them into `ai` tools for one caller.
+ */
+export declare class AiTools implements OnModuleInit {
+    private readonly discovery;
+    private readonly scanner;
+    private readonly options;
+    private readonly logger;
+    private readonly entries;
+    private readonly paramsFactory;
+    private readonly contextCreator;
+    private scanned;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner, externalContextCreator: ExternalContextCreator, options: AiModuleOptions);
+    onModuleInit(): void;
+    /** Every agent function, by name. */
+    get tools(): ReadonlyMap<string, AiToolEntry>;
+    /**
+     * `ai` tools for `names` (agent function names, or provider classes for all their agent functions), whose calls run
+     * as `caller`: what `AiService` calls pass the model, and what code that calls `ai` itself can pass `generateText()`.
+     */
+    select(selection: AiToolSelection, { caller, onExecute, onProgress, execute, }?: {
+        caller?: AiCaller;
+        /** @internal */
+        onExecute?: () => void;
+        /** @internal Where `ctx.reportProgress()` goes: a streamed answer. */
+        onProgress?: (progress: AiToolProgress) => void;
+        /** @internal `false`: the tools are offered to the model, and their calls returned, not run (durable runs). */
+        execute?: boolean;
+    }): ToolSet;
+    /**
+     * Runs the agent function `name` with `input` (validated by its schema) as `caller`, through its enhancers, as an
+     * agent's call does. Resolves with what the model would read; rejects with the `AiToolError` it would read.
+     */
+    call(entryOrName: AiToolEntry | string, input: unknown, caller?: AiCaller, options?: {
+        toolCallId?: string;
+        messages?: unknown[];
+        abortSignal?: AbortSignal;
+        idempotencyKey?: string;
+        onProgress?: (progress: AiToolProgress) => void;
+    }): Promise<unknown>;
+    /** The agent functions a selection names, each once, in order. Unknown names throw. */
+    resolve(selection: AiToolSelection): AiToolEntry[];
+    /** Finds the agent functions, once. */
+    scan(): void;
+    private known;
+}

package/dist/tools/ai-tools.service.js

@@ -0,0 +1,234 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { DiscoveryService, ExternalContextCreator, MetadataScanner } from '@nestjs/core';
+import { AGENT_FUNCTION_METADATA, AI_CONTEXT_TYPE, AI_MODULE_OPTIONS, AI_PARAMS_METADATA } from '../ai.constants.js';
+import { AiParamsFactory, recordHandlerParams } from '../context/ai-params.js';
+import { AiConfigurationError, AiToolError } from '../errors/ai.errors.js';
+import { toToolError } from '../utils/errors.util.js';
+import { assertProviderToolName } from '../utils/names.util.js';
+import { EMPTY_OBJECT_SCHEMA, toModelSchema } from '../utils/schema.util.js';
+import { toToolOutput } from './tool-output.util.js';
+const NEVER_ABORTED = new AbortController().signal;
+/**
+ * The application's agent functions: the `@AgentFunction()` methods of its providers (or of the `include` modules),
+ * found once at startup, each wrapped by Nest's enhancers with the context type `'ai'`, and called with an
+ * `AgentFunctionContext`. `select()` turns some of them into `ai` tools for one caller.
+ */
+let AiTools = class AiTools {
+    constructor(discovery, scanner, externalContextCreator, options) {
+        this.discovery = discovery;
+        this.scanner = scanner;
+        this.options = options;
+        this.logger = new Logger('AiModule');
+        this.entries = new Map();
+        this.paramsFactory = new AiParamsFactory();
+        this.scanned = false;
+        this.contextCreator = withOwnHandlerMetadata(externalContextCreator);
+    }
+    onModuleInit() {
+        this.scan();
+    }
+    /** Every agent function, by name. */
+    get tools() {
+        this.scan();
+        return this.entries;
+    }
+    /**
+     * `ai` tools for `names` (agent function names, or provider classes for all their agent functions), whose calls run
+     * as `caller`: what `AiService` calls pass the model, and what code that calls `ai` itself can pass `generateText()`.
+     */
+    select(selection, { caller = {}, onExecute, onProgress, execute = true, } = {}) {
+        this.scan();
+        const tools = {};
+        for (const entry of this.resolve(selection)) {
+            // An `ai` tool is a plain object; `ai` validates the input against the schema before `execute`.
+            tools[entry.name] = {
+                ...(entry.description !== undefined && { description: entry.description }),
+                inputSchema: entry.inputSchema,
+                ...(execute && {
+                    execute: (input, options) => {
+                        onExecute?.();
+                        return this.call(entry, input, caller, { ...options, ...(onProgress && { onProgress }) });
+                    },
+                }),
+            };
+        }
+        return tools;
+    }
+    /**
+     * Runs the agent function `name` with `input` (validated by its schema) as `caller`, through its enhancers, as an
+     * agent's call does. Resolves with what the model would read; rejects with the `AiToolError` it would read.
+     */
+    async call(entryOrName, input, caller = {}, options = {}) {
+        const entry = typeof entryOrName === 'string' ? this.resolve([entryOrName])[0] : entryOrName;
+        if (typeof entryOrName === 'string') {
+            const validated = await entry.inputSchema.validate?.(input);
+            if (validated && !validated.success) {
+                throw new AiToolError(`Invalid input: ${validated.error.message}`, entry.name);
+            }
+            input = validated ? validated.value : input;
+        }
+        if (entry.scopes?.length) {
+            const held = new Set(caller.scopes ?? []);
+            const missing = entry.scopes.filter((scope) => !held.has(scope));
+            if (missing.length > 0) {
+                throw new AiToolError(`Forbidden: this tool needs the scope(s) ${missing.join(', ')}`, entry.name);
+            }
+        }
+        const toolCallId = options.toolCallId ?? '';
+        // Where `@nestjs/authentication` and `@nestjs/authorization` look on an `'ai'` call, as on an `'mcp'` one: the
+        // request it runs in, else the context itself, with its `user`.
+        const context = {
+            name: entry.name,
+            ...(caller.request !== undefined && { request: caller.request }),
+            ...(caller.user !== undefined && { user: caller.user }),
+            ...(caller.scopes !== undefined && { scopes: caller.scopes }),
+            signal: options.abortSignal ?? NEVER_ABORTED,
+            reportProgress: async (progress, total, message) => options.onProgress?.({
+                toolCallId,
+                toolName: entry.name,
+                progress,
+                ...(total !== undefined && { total }),
+                ...(message !== undefined && { message }),
+            }),
+            toolCallId,
+            ...(options.idempotencyKey !== undefined && { idempotencyKey: options.idempotencyKey }),
+            messages: (options.messages ?? []),
+        };
+        let value;
+        try {
+            value = await entry.handler(input ?? {}, context);
+        }
+        catch (error) {
+            // Nest's exception handler has run the filters, and logged the error.
+            throw toToolError(error, entry.name);
+        }
+        try {
+            return toToolOutput(value, entry.name, entry.where);
+        }
+        catch (error) {
+            if (!(error instanceof AiToolError)) {
+                this.logger.error(`${entry.where} returned a value that is not JSON`, error?.stack);
+            }
+            throw toToolError(error, entry.name);
+        }
+    }
+    /** The agent functions a selection names, each once, in order. Unknown names throw. */
+    resolve(selection) {
+        this.scan();
+        if (!Array.isArray(selection)) {
+            throw new AiConfigurationError("`tools` lists agent function names and provider classes, e.g. ['find-order', OrdersTools].");
+        }
+        const picked = new Map();
+        for (const item of selection) {
+            if (typeof item === 'string') {
+                const entry = this.entries.get(item);
+                if (!entry) {
+                    throw new AiConfigurationError(`There is no agent function named "${item}". ${this.known()}`);
+                }
+                picked.set(entry.name, entry);
+            }
+            else if (typeof item === 'function') {
+                const matches = [...this.entries.values()].filter((entry) => entry.host === item || entry.host.prototype instanceof item);
+                if (matches.length === 0) {
+                    throw new AiConfigurationError(`${item.name} has no agent functions, or is not a provider of the application. ${this.known()}`);
+                }
+                for (const entry of matches) {
+                    picked.set(entry.name, entry);
+                }
+            }
+            else {
+                throw new AiConfigurationError(`\`tools\` lists agent function names and provider classes; got ${String(item)}.`);
+            }
+        }
+        return [...picked.values()];
+    }
+    /** Finds the agent functions, once. */
+    scan() {
+        if (this.scanned) {
+            return;
+        }
+        this.scanned = true;
+        const seen = new Set();
+        const wrappers = this.discovery.getProviders(this.options.include ? { include: this.options.include } : undefined);
+        for (const wrapper of wrappers) {
+            const { instance } = wrapper;
+            if (!instance || typeof instance !== 'object' || wrapper.isAlias || seen.has(instance)) {
+                continue;
+            }
+            seen.add(instance);
+            const prototype = Object.getPrototypeOf(instance);
+            for (const methodName of this.scanner.getAllMethodNames(prototype)) {
+                const method = prototype[methodName];
+                const definition = Reflect.getMetadata(AGENT_FUNCTION_METADATA, method);
+                if (!definition) {
+                    continue;
+                }
+                const where = `${wrapper.metatype?.name ?? instance.constructor.name}.${methodName}`;
+                if (!wrapper.isDependencyTreeStatic()) {
+                    throw new AiConfigurationError(`${where}: agent functions must be on singleton providers, and this one is request-scoped or transient (or ` +
+                        'depends on a request-scoped provider). Pass what a call needs through `caller` instead.');
+                }
+                const name = definition.name ?? methodName;
+                assertProviderToolName(name, where);
+                const existing = this.entries.get(name);
+                if (existing) {
+                    throw new AiConfigurationError(`${where}: there is already an agent function named "${name}" (${existing.where}). Give one of them ` +
+                        'another { name }.');
+                }
+                recordHandlerParams(instance.constructor, methodName);
+                const handler = this.contextCreator.create(instance, method, methodName, AI_PARAMS_METADATA, this.paramsFactory, undefined, undefined, undefined, AI_CONTEXT_TYPE);
+                this.entries.set(name, {
+                    name,
+                    ...(definition.description !== undefined && { description: definition.description }),
+                    ...(definition.scopes?.length && { scopes: [...definition.scopes] }),
+                    inputSchema: definition.inputSchema
+                        ? toModelSchema(definition.inputSchema, `${where} inputSchema`, { object: true })
+                        : EMPTY_OBJECT_SCHEMA,
+                    handler,
+                    host: instance.constructor,
+                    where,
+                });
+            }
+        }
+    }
+    known() {
+        const names = [...this.entries.keys()];
+        return names.length
+            ? `Agent functions: ${names.join(', ')}.`
+            : 'The application has no agent functions (@AgentFunction() methods).';
+    }
+};
+AiTools = __decorate([
+    Injectable(),
+    __param(3, Inject(AI_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [DiscoveryService,
+        MetadataScanner,
+        ExternalContextCreator, Object])
+], AiTools);
+export { AiTools };
+/**
+ * Nest's `ExternalContextCreator`, with a cache of handler metadata of its own. Nest's keeps what it reads of a
+ * method's parameters by class and method name, and builds the context type of the first `create()` for the method into
+ * it: the `ExecutionContext` that `createParamDecorator()` decorators receive. A method that is an `@nestjs/mcp` tool
+ * too is wrapped by both packages, and its parameter decorators would see the type of whichever wrapped it first,
+ * `'ai'` or `'mcp'`, on every call. Guards, interceptors and filters get the type of each `create()` either way. Each
+ * agent function is wrapped once, at startup, so nothing needs caching here.
+ */
+function withOwnHandlerMetadata(creator) {
+    // `handlerMetadataStorage` is the private field `getMetadata()` reads, in every 12.x release.
+    return Object.create(creator, {
+        handlerMetadataStorage: { value: { get: () => undefined, set: () => { } } },
+    });
+}

package/dist/tools/tool-output.util.d.ts

@@ -0,0 +1,6 @@
+/**
+ * What the model reads of an agent function's return value: JSON (a `Date` becomes its ISO string; `undefined` is
+ * `null`). An MCP `CallToolResult` becomes its `structuredContent`, else its text blocks joined; `isError: true` is a
+ * tool error. Blocks other than text (images, audio, resources) are dropped.
+ */
+export declare function toToolOutput(value: unknown, toolName: string, where: string): unknown;

package/dist/tools/tool-output.util.js

@@ -0,0 +1,38 @@
+import { Logger } from '@nestjs/common';
+import { AiToolError } from '../errors/ai.errors.js';
+const logger = new Logger('AiModule');
+function isCallToolResult(value) {
+    if (typeof value !== 'object' || value === null || !Array.isArray(value.content)) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return (keys.every((key) => ['content', 'structuredContent', 'isError', '_meta'].includes(key)) &&
+        value.content.every((block) => typeof block?.type === 'string'));
+}
+/**
+ * What the model reads of an agent function's return value: JSON (a `Date` becomes its ISO string; `undefined` is
+ * `null`). An MCP `CallToolResult` becomes its `structuredContent`, else its text blocks joined; `isError: true` is a
+ * tool error. Blocks other than text (images, audio, resources) are dropped.
+ */
+export function toToolOutput(value, toolName, where) {
+    if (isCallToolResult(value)) {
+        const text = value.content
+            .filter((block) => block.type === 'text' && typeof block.text === 'string')
+            .map((block) => block.text)
+            .join('\n');
+        if (value.isError) {
+            throw new AiToolError(text || 'The tool failed', toolName);
+        }
+        if (value.content.some((block) => block.type !== 'text')) {
+            logger.warn(`${where} returned content other than text, which agents are not sent; only its text is.`);
+        }
+        return value.structuredContent !== undefined ? toJson(value.structuredContent) : text;
+    }
+    return value === undefined ? null : toJson(value);
+}
+function toJson(value) {
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    return JSON.parse(JSON.stringify(value));
+}

package/dist/utils/duration.util.d.ts

@@ -0,0 +1,3 @@
+import type { Duration } from '@nestjs/resilience';
+/** A duration (`@nestjs/resilience`'s: milliseconds, or `'30s'`, `'2m'`, ...) in milliseconds. */
+export declare function toMilliseconds(value: Duration | string, option: string): number;

package/dist/utils/duration.util.js

@@ -0,0 +1,17 @@
+import { AiConfigurationError } from '../errors/ai.errors.js';
+const UNITS = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+/** A duration (`@nestjs/resilience`'s: milliseconds, or `'30s'`, `'2m'`, ...) in milliseconds. */
+export function toMilliseconds(value, option) {
+    if (typeof value === 'number') {
+        if (Number.isFinite(value) && value >= 0) {
+            return value;
+        }
+    }
+    else if (typeof value === 'string') {
+        const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$/.exec(value.trim());
+        if (match) {
+            return Number(match[1]) * UNITS[match[2]];
+        }
+    }
+    throw new AiConfigurationError(`\`${option}\` must be a number of milliseconds or a duration such as "30s" or "2m". Got ${JSON.stringify(value)}.`);
+}

package/dist/utils/errors.util.d.ts

@@ -0,0 +1,16 @@
+import { HttpException } from '@nestjs/common';
+import { AiToolError } from '../errors/ai.errors.js';
+/** What the model is told about an error that is not meant for it. */
+export declare const INTERNAL_ERROR_MESSAGE = "Internal server error";
+/**
+ * The message of an `HttpException`, as its response body carries it: a string response, the body's `message`
+ * (`ValidationPipe`'s list joined), else the exception's own.
+ */
+export declare function httpExceptionMessage(exception: HttpException): string;
+/**
+ * An agent function's failure, as the model reads it: an `HttpException`'s message, `Internal server error` for
+ * anything else (Nest's exception handler has logged it). A raw error message never reaches the model.
+ */
+export declare function toToolError(error: unknown, toolName: string): AiToolError;
+/** Whether `error` is an abort: the caller's signal, or a request cancelled with it. */
+export declare function isAbortError(error: unknown): boolean;

package/dist/utils/errors.util.js

@@ -0,0 +1,35 @@
+import { HttpException } from '@nestjs/common';
+import { AiToolError } from '../errors/ai.errors.js';
+/** What the model is told about an error that is not meant for it. */
+export const INTERNAL_ERROR_MESSAGE = 'Internal server error';
+/**
+ * The message of an `HttpException`, as its response body carries it: a string response, the body's `message`
+ * (`ValidationPipe`'s list joined), else the exception's own.
+ */
+export function httpExceptionMessage(exception) {
+    const response = exception.getResponse();
+    if (typeof response === 'string') {
+        return response;
+    }
+    const message = response?.message;
+    if (Array.isArray(message)) {
+        return message.map(String).join('; ');
+    }
+    return typeof message === 'string' ? message : exception.message;
+}
+/**
+ * An agent function's failure, as the model reads it: an `HttpException`'s message, `Internal server error` for
+ * anything else (Nest's exception handler has logged it). A raw error message never reaches the model.
+ */
+export function toToolError(error, toolName) {
+    if (error instanceof AiToolError) {
+        return error;
+    }
+    const message = error instanceof HttpException ? httpExceptionMessage(error) : INTERNAL_ERROR_MESSAGE;
+    return new AiToolError(message, toolName, { cause: error });
+}
+/** Whether `error` is an abort: the caller's signal, or a request cancelled with it. */
+export function isAbortError(error) {
+    return (error instanceof Error &&
+        (error.name === 'AbortError' || error.code === 'ABORT_ERR'));
+}

package/dist/utils/names.util.d.ts

@@ -0,0 +1,2 @@
+/** Throws for an agent function name model providers refuse, naming the method. */
+export declare function assertProviderToolName(name: string, where: string): void;

package/dist/utils/names.util.js

@@ -0,0 +1,10 @@
+import { AiConfigurationError } from '../errors/ai.errors.js';
+/** What OpenAI, Anthropic and Google accept as a tool name, which is what an agent function's name is to the model. */
+const PROVIDER_TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+/** Throws for an agent function name model providers refuse, naming the method. */
+export function assertProviderToolName(name, where) {
+    if (typeof name !== 'string' || !PROVIDER_TOOL_NAME.test(name)) {
+        throw new AiConfigurationError(`${where}: the name ${JSON.stringify(name)} is not one model providers accept as a tool name: 1 to 64 ` +
+            'characters out of A-Z a-z 0-9 _ -. Give @AgentFunction() a { name } that fits.');
+    }
+}

package/dist/utils/schema.util.d.ts

@@ -0,0 +1,16 @@
+import { type Schema } from 'ai';
+import type { AiSchema, AiSchemaResult } from '../interfaces/ai-schema.interface.js';
+/** The `ai` schema of a tool without arguments. */
+export declare const EMPTY_OBJECT_SCHEMA: Schema<Record<string, never>>;
+/**
+ * The `ai` schema for a Standard Schema with JSON Schema: its JSON Schema (the input side: what the model writes),
+ * computed once, and its validation, whose issues become the error the model reads. `object: true` requires an
+ * object at the root (tool arguments).
+ */
+export declare function toModelSchema<T = unknown>(schema: AiSchema, where: string, { object }?: {
+    object?: boolean | undefined;
+}): Schema<T>;
+/** Validation issues as one line each, with their path: what the model reads to correct itself. */
+export declare function formatIssues(issues: NonNullable<Extract<AiSchemaResult<unknown>, {
+    issues: unknown;
+}>['issues']>): string;

package/dist/utils/schema.util.js

@@ -0,0 +1,70 @@
+import { jsonSchema } from 'ai';
+import { AiConfigurationError } from '../errors/ai.errors.js';
+/** JSON Schema drafts, in order of preference: what `ai` sends providers, then what MCP uses. */
+const TARGETS = ['draft-07', 'draft-2020-12'];
+const converted = new WeakMap();
+/** The `ai` schema of a tool without arguments. */
+export const EMPTY_OBJECT_SCHEMA = jsonSchema({
+    type: 'object',
+    properties: {},
+    additionalProperties: false,
+});
+/**
+ * The `ai` schema for a Standard Schema with JSON Schema: its JSON Schema (the input side: what the model writes),
+ * computed once, and its validation, whose issues become the error the model reads. `object: true` requires an
+ * object at the root (tool arguments).
+ */
+export function toModelSchema(schema, where, { object = false } = {}) {
+    const cached = converted.get(schema);
+    if (cached) {
+        return cached;
+    }
+    const standard = schema?.['~standard'];
+    if (!standard || typeof standard.validate !== 'function') {
+        throw new AiConfigurationError(`${where}: not a Standard Schema. Pass a Zod 4.2+ schema (z.object({ ... })), an ArkType type, a Valibot schema ` +
+            'wrapped with toStandardJsonSchema(), or a JSON Schema wrapped with fromJsonSchema() from @modelcontextprotocol/server.');
+    }
+    if (typeof standard.jsonSchema?.input !== 'function') {
+        throw new AiConfigurationError(`${where}: the "${standard.vendor}" schema cannot produce JSON Schema (no ~standard.jsonSchema), which the ` +
+            'model needs. Zod needs 4.2 or later (Zod 3 is not supported); Valibot needs toStandardJsonSchema() from ' +
+            '@valibot/to-json-schema.');
+    }
+    let root;
+    let failure;
+    for (const target of TARGETS) {
+        try {
+            root = standard.jsonSchema.input({ target });
+            break;
+        }
+        catch (error) {
+            failure = error;
+        }
+    }
+    if (!root) {
+        throw new AiConfigurationError(`${where}: the schema cannot be converted to JSON Schema: ${failure?.message ?? failure}`);
+    }
+    if (object && root.type !== undefined && root.type !== 'object') {
+        throw new AiConfigurationError(`${where}: arguments are an object, and this schema describes ${JSON.stringify(root.type)}. Wrap it in z.object({ ... }).`);
+    }
+    const result = jsonSchema(root, {
+        validate: async (value) => {
+            const outcome = (await standard.validate(value));
+            return outcome.issues
+                ? { success: false, error: new TypeError(formatIssues(outcome.issues)) }
+                : { success: true, value: outcome.value };
+        },
+    });
+    converted.set(schema, result);
+    return result;
+}
+/** Validation issues as one line each, with their path: what the model reads to correct itself. */
+export function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = (issue.path ?? [])
+            .map((segment) => String(typeof segment === 'object' && segment !== null ? segment.key : segment))
+            .join('.');
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join('\n');
+}

package/dist/utils/usage.util.d.ts

@@ -0,0 +1,10 @@
+import type { LanguageModelUsage } from 'ai';
+import type { AiModelPricing } from '../interfaces/ai-module-options.interface.js';
+import type { AiUsage } from '../interfaces/ai-usage.interface.js';
+export declare const ZERO_USAGE: AiUsage;
+/** `ai`'s usage of one model call, with what the provider did not report as 0. */
+export declare function toUsage(usage: LanguageModelUsage | undefined): AiUsage;
+export declare function addUsage(a: AiUsage, b: AiUsage): AiUsage;
+/** The cost of `usage` at `pricing` (per million tokens); `undefined` without pricing. */
+export declare function costOf(usage: AiUsage, pricing: AiModelPricing | undefined): number | undefined;
+export declare function addCost(a: number | undefined, b: number | undefined): number | undefined;

package/dist/utils/usage.util.js

@@ -0,0 +1,42 @@
+export const ZERO_USAGE = Object.freeze({
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    cachedInputTokens: 0,
+    reasoningTokens: 0,
+});
+/** `ai`'s usage of one model call, with what the provider did not report as 0. */
+export function toUsage(usage) {
+    const inputTokens = usage?.inputTokens ?? 0;
+    const outputTokens = usage?.outputTokens ?? 0;
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens: usage?.totalTokens ?? inputTokens + outputTokens,
+        cachedInputTokens: usage?.inputTokenDetails?.cacheReadTokens ?? 0,
+        reasoningTokens: usage?.outputTokenDetails?.reasoningTokens ?? 0,
+    };
+}
+export function addUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        totalTokens: a.totalTokens + b.totalTokens,
+        cachedInputTokens: a.cachedInputTokens + b.cachedInputTokens,
+        reasoningTokens: a.reasoningTokens + b.reasoningTokens,
+    };
+}
+/** The cost of `usage` at `pricing` (per million tokens); `undefined` without pricing. */
+export function costOf(usage, pricing) {
+    if (!pricing) {
+        return undefined;
+    }
+    const cached = Math.min(usage.cachedInputTokens, usage.inputTokens);
+    const cost = (usage.inputTokens - cached) * pricing.input +
+        cached * (pricing.cachedInput ?? pricing.input) +
+        usage.outputTokens * pricing.output;
+    return cost / 1_000_000;
+}
+export function addCost(a, b) {
+    return a === undefined && b === undefined ? undefined : (a ?? 0) + (b ?? 0);
+}