@nestjs/ai 0.0.0-stage → 0.0.2

package/dist/interfaces/ai-result.interface.d.ts

@@ -0,0 +1,57 @@
+import type { FinishReason, ModelMessage } from 'ai';
+import type { AiUsage } from './ai-usage.interface.js';
+/** Which model answered. */
+export interface AiModelInfo {
+    /**
+     * Its name in `models` or `embeddingModels`; `undefined` for an SDK model object passed directly
+     * to the call.
+     */
+    name?: string;
+    provider: string;
+    modelId: string;
+}
+export interface AiToolCall {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+export interface AiToolResult extends AiToolCall {
+    /** What the tool returned; absent when it failed. */
+    output?: unknown;
+    /** What the model was told about a failure. */
+    error?: string;
+}
+/** One model call of a text generation, with the tool calls it made and their results. */
+export interface AiStep {
+    index: number;
+    model: AiModelInfo;
+    text: string;
+    toolCalls: AiToolCall[];
+    toolResults: AiToolResult[];
+    finishReason: FinishReason;
+    usage: AiUsage;
+    cost?: number;
+    /** Attempts made for this step, over every model tried. */
+    attempts: number;
+}
+export interface AiTextResult {
+    /** The text of the last step. */
+    text: string;
+    /** The last step's: `tool-calls` when `maxSteps` ran out while the model still asked for tools. */
+    finishReason: FinishReason;
+    steps: AiStep[];
+    /** Summed over the steps. */
+    usage: AiUsage;
+    /** Summed over the steps whose model has `pricing`; `undefined` when none had. */
+    cost?: number;
+    toolCalls: AiToolCall[];
+    toolResults: AiToolResult[];
+    /** The assistant and tool messages of every step, to append to a conversation. */
+    responseMessages: ModelMessage[];
+    /** The model of the last step. */
+    model: AiModelInfo;
+}
+export interface AiObjectResult<T> extends AiTextResult {
+    /** The answer, validated by the schema. */
+    object: T;
+}

package/dist/interfaces/ai-result.interface.js

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

package/dist/interfaces/ai-schema.interface.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A schema the package accepts: a Standard Schema that also produces JSON Schema (`~standard.jsonSchema`), as
+ * `@nestjs/mcp`'s schemas are, so that one schema serves a method's `@AgentFunction()` and its `@Tool()`. Zod 4.2+
+ * and ArkType schemas are, as they are; Valibot through
+ * `toStandardJsonSchema()` from `@valibot/to-json-schema`; a JSON Schema document through `fromJsonSchema()` from
+ * `@modelcontextprotocol/server`. The model is sent the JSON Schema, and what it answers is validated by the schema.
+ *
+ * The shape of the [Standard Schema](https://standardschema.dev) interfaces, declared here so that the package has no
+ * dependency for them.
+ */
+export interface AiSchema<Input = any, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+        readonly validate: (value: unknown, options?: {
+            readonly libraryOptions?: Record<string, unknown> | undefined;
+        } | undefined) => AiSchemaResult<Output> | Promise<AiSchemaResult<Output>>;
+        readonly jsonSchema: {
+            readonly input: (options: AiJsonSchemaOptions) => Record<string, unknown>;
+            readonly output: (options: AiJsonSchemaOptions) => Record<string, unknown>;
+        };
+    };
+}
+export interface AiJsonSchemaOptions {
+    readonly target: 'draft-2020-12' | 'draft-07' | 'openapi-3.0' | ({} & string);
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+}
+export type AiSchemaResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<{
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | {
+            readonly key: PropertyKey;
+        }> | undefined;
+    }>;
+};
+/** The type a schema validates to. */
+export type InferSchemaOutput<S extends AiSchema> = NonNullable<S['~standard']['types']>['output'];

package/dist/interfaces/ai-schema.interface.js

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

package/dist/interfaces/ai-tool.interface.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Who an agent acts for. Agent functions receive it in their context (`AgentFunctionContext`), and guards read it
+ * there, as a route's guards read the request.
+ *
+ * ```ts
+ * caller: { request }                      // in a controller: the request's user, headers, session
+ * caller: { user: job.data.user, scopes }  // in a queue job
+ * ```
+ */
+export interface AiCaller<TUser = any, TRequest = any> {
+    /** The HTTP platform's request the agent runs in (Express, Fastify, the Node adapter). */
+    request?: TRequest;
+    /** The user, where there is no request (a queue job, a workflow); in a request, it is `request.user`. */
+    user?: TUser;
+    /** Scopes the caller holds, checked against an agent function's `scopes`. */
+    scopes?: readonly string[];
+}
+/**
+ * What a call's `tools` lists: agent function names, and provider classes (every agent function of the class). The
+ * model is offered each as a tool.
+ */
+export type AiToolSelection = ReadonlyArray<string | (abstract new (...args: any[]) => unknown)>;

package/dist/interfaces/ai-tool.interface.js

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

package/dist/interfaces/ai-usage.interface.d.ts

@@ -0,0 +1,30 @@
+import type { AiModelInfo } from './ai-result.interface.js';
+/** Tokens a model call used. A count the provider did not report is 0. */
+export interface AiUsage {
+    /** Every input token, cached ones included. */
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** The part of `inputTokens` read from the provider's prompt cache. */
+    cachedInputTokens: number;
+    /** The part of `outputTokens` spent on reasoning. */
+    reasoningTokens: number;
+}
+/** One model call that answered: a step of `generateText()`, `generateObject()` or `streamText()`. */
+export interface AiUsageEvent {
+    /** The call's `label`, to tell calls apart (`'triage'`). */
+    label?: string;
+    model: AiModelInfo;
+    /** 0-based step of the call: a call that uses tools makes several model calls. */
+    step: number;
+    /** 1-based attempt of this model for this step. */
+    attempt: number;
+    /** Whether it was a fallback model. */
+    fallback: boolean;
+    stream: boolean;
+    usage: AiUsage;
+    /** In the unit of the model's `pricing`; `undefined` without one. */
+    cost?: number;
+    durationMs: number;
+    finishReason: string;
+}

package/dist/interfaces/ai-usage.interface.js

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

package/dist/interfaces/index.d.ts

@@ -0,0 +1,8 @@
+export * from './agent-function.interface.js';
+export * from './ai-call-options.interface.js';
+export * from './ai-embedding.interface.js';
+export * from './ai-module-options.interface.js';
+export * from './ai-result.interface.js';
+export * from './ai-schema.interface.js';
+export * from './ai-tool.interface.js';
+export * from './ai-usage.interface.js';

package/dist/interfaces/index.js

@@ -0,0 +1,8 @@
+export * from './agent-function.interface.js';
+export * from './ai-call-options.interface.js';
+export * from './ai-embedding.interface.js';
+export * from './ai-module-options.interface.js';
+export * from './ai-result.interface.js';
+export * from './ai-schema.interface.js';
+export * from './ai-tool.interface.js';
+export * from './ai-usage.interface.js';

package/dist/models/ai-embedding-models.service.d.ts

@@ -0,0 +1,31 @@
+import type { EmbeddingModel } from 'ai';
+import type { AiEmbeddingModelPricing, AiEmbeddingModelReference, AiEmbeddingSettings } from '../interfaces/ai-embedding.interface.js';
+import type { AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiModelInfo } from '../interfaces/ai-result.interface.js';
+/** One resolved embedding model. Internal; embedding calls never switch to fallback models. */
+export interface ResolvedEmbeddingModel {
+    info: AiModelInfo;
+    model: EmbeddingModel;
+    pricing?: AiEmbeddingModelPricing;
+    settings: AiEmbeddingSettings;
+}
+/** The configured embedding models, independent of language-model names. */
+export declare class AiEmbeddingModels {
+    private readonly models;
+    constructor(options: AiModuleOptions, overrides?: Record<string, EmbeddingModel> | null);
+    names(): string[];
+    /** The SDK model, for direct calls without `AiService`'s resilience or usage events. */
+    get(name?: string): EmbeddingModel;
+    has(name: string): boolean;
+    /**
+     * @internal What `@InjectEmbeddingModel()` injects; unknown names fail during module
+     * initialization.
+     */
+    injected(name: string, inquirer: unknown): EmbeddingModel;
+    /**
+     * @internal Resolves a name or an SDK object. Direct objects have no registered settings or
+     * pricing.
+     */
+    resolve(reference: AiEmbeddingModelReference | undefined): ResolvedEmbeddingModel;
+    private known;
+}

package/dist/models/ai-embedding-models.service.js

@@ -0,0 +1,138 @@
+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, Optional } from '@nestjs/common';
+import { AI_EMBEDDING_MODEL_OVERRIDES, AI_MODULE_OPTIONS, DEFAULT_MODEL_NAME, } from '../ai.constants.js';
+import { AiConfigurationError } from '../errors/ai.errors.js';
+import { assertModelRegistries } from './model-registry.util.js';
+/** The configured embedding models, independent of language-model names. */
+let AiEmbeddingModels = class AiEmbeddingModels {
+    constructor(options, overrides) {
+        this.models = new Map();
+        assertModelRegistries(options);
+        assertSettings(options.embeddingDefaults, 'AiModule: `embeddingDefaults`');
+        for (const [name, entry] of Object.entries(options.embeddingModels ?? {})) {
+            const { model, pricing, ...settings } = isDefinition(entry) ? entry : { model: entry };
+            assertModel(model, `AiModule: the embedding model "${name}"`);
+            assertSettings(settings, `AiModule: the embedding model "${name}"`);
+            if (pricing !== undefined &&
+                (typeof pricing !== 'object' ||
+                    pricing === null ||
+                    !Number.isFinite(pricing.input) ||
+                    pricing.input < 0)) {
+                throw new AiConfigurationError(`AiModule: the embedding model "${name}" pricing.input must be ` +
+                    'a finite nonnegative number.');
+            }
+            const used = overrides?.[name] ?? model;
+            assertModel(used, `AiModule: the replacement embedding model "${name}"`);
+            this.models.set(name, {
+                info: { name, ...identify(used) },
+                model: used,
+                ...(pricing !== undefined && { pricing }),
+                settings,
+            });
+        }
+        for (const name of Object.keys(overrides ?? {})) {
+            if (!this.models.has(name)) {
+                throw new AiConfigurationError(`overrideEmbeddingModels(): there is no embedding model "${name}" to override. ` +
+                    this.known());
+            }
+        }
+    }
+    names() {
+        return [...this.models.keys()];
+    }
+    /** The SDK model, for direct calls without `AiService`'s resilience or usage events. */
+    get(name = DEFAULT_MODEL_NAME) {
+        return this.resolve(name).model;
+    }
+    has(name) {
+        return this.models.has(name);
+    }
+    /**
+     * @internal What `@InjectEmbeddingModel()` injects; unknown names fail during module
+     * initialization.
+     */
+    injected(name, inquirer) {
+        const resolved = this.models.get(name);
+        if (!resolved) {
+            const requester = inquirer?.constructor
+                ?.name;
+            throw new AiConfigurationError(`${requester ? `${requester}: ` : ''}@InjectEmbeddingModel('${name}') ` +
+                'asks for an embedding model AiModule does not configure. ' +
+                `${this.known()} Add "${name}" to \`embeddingModels\` ` +
+                '(in forRootAsync(), to what the factory returns).');
+        }
+        return resolved.model;
+    }
+    /**
+     * @internal Resolves a name or an SDK object. Direct objects have no registered settings or
+     * pricing.
+     */
+    resolve(reference) {
+        if (reference === undefined || typeof reference === 'string') {
+            const name = reference ?? DEFAULT_MODEL_NAME;
+            const resolved = this.models.get(name);
+            if (!resolved) {
+                throw new AiConfigurationError(`There is no embedding model named "${name}". ${this.known()}`);
+            }
+            return resolved;
+        }
+        assertModel(reference, 'The embedding `model` option');
+        return { info: identify(reference), model: reference, settings: {} };
+    }
+    known() {
+        return `Configured embedding models: ${this.names().join(', ')}.`;
+    }
+};
+AiEmbeddingModels = __decorate([
+    Injectable(),
+    __param(0, Inject(AI_MODULE_OPTIONS)),
+    __param(1, Optional()),
+    __param(1, Inject(AI_EMBEDDING_MODEL_OVERRIDES)),
+    __metadata("design:paramtypes", [Object, Object])
+], AiEmbeddingModels);
+export { AiEmbeddingModels };
+function isDefinition(entry) {
+    return (typeof entry === 'object' &&
+        entry !== null &&
+        'model' in entry &&
+        !('specificationVersion' in entry));
+}
+function assertModel(model, where) {
+    const valid = (typeof model === 'string' && model.length > 0) ||
+        (typeof model === 'object' &&
+            model !== null &&
+            typeof model.doEmbed === 'function');
+    if (!valid) {
+        throw new AiConfigurationError(`${where} is not an embedding model. ` +
+            'Pass an embedding model from an AI SDK provider package.');
+    }
+}
+function assertSettings(settings, where) {
+    if (settings === undefined) {
+        return;
+    }
+    if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+        throw new AiConfigurationError(`${where} must contain embedding settings.`);
+    }
+    if (settings.maxParallelCalls !== undefined &&
+        (!Number.isSafeInteger(settings.maxParallelCalls) || settings.maxParallelCalls < 1)) {
+        throw new AiConfigurationError(`${where} maxParallelCalls must be a finite positive safe integer.`);
+    }
+}
+/** Registered string ids are resolved by the SDK's default gateway provider. */
+function identify(model) {
+    return typeof model === 'string'
+        ? { provider: 'gateway', modelId: model }
+        : { provider: model.provider, modelId: model.modelId };
+}

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

@@ -0,0 +1,29 @@
+import type { LanguageModel } from 'ai';
+import type { AiModelReference } from '../interfaces/ai-call-options.interface.js';
+import type { AiCallSettings, AiModelPricing, AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiModelInfo } from '../interfaces/ai-result.interface.js';
+/** A model, as calls use it. Internal. */
+export interface ResolvedModel {
+    info: AiModelInfo;
+    model: LanguageModel;
+    pricing?: AiModelPricing;
+    settings: AiCallSettings;
+    /** The names of the models tried after it. */
+    fallback: string[];
+}
+/** The configured models, by name. */
+export declare class AiModels {
+    private readonly models;
+    constructor(options: AiModuleOptions, overrides?: Record<string, LanguageModel> | null);
+    /** The names of the configured models. */
+    names(): string[];
+    /** The `LanguageModel` called `name`, for code that calls `ai` directly. */
+    get(name?: string): LanguageModel;
+    /** Whether a model called `name` is configured. */
+    has(name: string): boolean;
+    /** @internal What `@InjectModel(name)` injects into `inquirer`; a name that is not configured fails at startup. */
+    injected(name: string, inquirer: unknown): LanguageModel;
+    /** @internal A name, or a `LanguageModel` given to a call (with no settings of its own). */
+    resolve(reference: AiModelReference | undefined): ResolvedModel;
+    private known;
+}

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

@@ -0,0 +1,112 @@
+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, Optional } from '@nestjs/common';
+import { AiConfigurationError } from '../errors/ai.errors.js';
+import { AI_MODEL_OVERRIDES, AI_MODULE_OPTIONS, DEFAULT_MODEL_NAME } from '../ai.constants.js';
+import { assertModelRegistries } from './model-registry.util.js';
+/** The configured models, by name. */
+let AiModels = class AiModels {
+    constructor(options, overrides) {
+        this.models = new Map();
+        assertModelRegistries(options);
+        const models = options.models ?? {};
+        for (const [name, entry] of Object.entries(models)) {
+            const { model, pricing, fallback, ...settings } = isDefinition(entry) ? entry : { model: entry };
+            assertModel(model, `AiModule: the model "${name}"`);
+            const replacement = overrides?.[name];
+            const used = replacement ?? model;
+            this.models.set(name, {
+                info: { name, ...identify(used) },
+                model: used,
+                ...(pricing !== undefined && { pricing }),
+                settings,
+                fallback: fallback === undefined ? [] : [fallback].flat(),
+            });
+        }
+        for (const name of Object.keys(overrides ?? {})) {
+            if (!this.models.has(name)) {
+                throw new AiConfigurationError(`overrideModels(): there is no model "${name}" to override. ${this.known()}`);
+            }
+        }
+        for (const [name, resolved] of this.models) {
+            for (const next of resolved.fallback) {
+                if (!this.models.has(next)) {
+                    throw new AiConfigurationError(`AiModule: the model "${name}" falls back to "${next}", which is not configured. ${this.known()}`);
+                }
+            }
+        }
+    }
+    /** The names of the configured models. */
+    names() {
+        return [...this.models.keys()];
+    }
+    /** The `LanguageModel` called `name`, for code that calls `ai` directly. */
+    get(name = DEFAULT_MODEL_NAME) {
+        return this.resolve(name).model;
+    }
+    /** Whether a model called `name` is configured. */
+    has(name) {
+        return this.models.has(name);
+    }
+    /** @internal What `@InjectModel(name)` injects into `inquirer`; a name that is not configured fails at startup. */
+    injected(name, inquirer) {
+        const resolved = this.models.get(name);
+        if (!resolved) {
+            const requester = inquirer?.constructor?.name;
+            throw new AiConfigurationError(`${requester ? `${requester}: ` : ''}@InjectModel('${name}') asks for a model AiModule does not configure. ` +
+                `${this.known()} Add "${name}" to \`models\` (in forRootAsync(), to what the factory returns).`);
+        }
+        return resolved.model;
+    }
+    /** @internal A name, or a `LanguageModel` given to a call (with no settings of its own). */
+    resolve(reference) {
+        if (reference === undefined || typeof reference === 'string') {
+            const name = reference ?? DEFAULT_MODEL_NAME;
+            const resolved = this.models.get(name);
+            if (!resolved) {
+                throw new AiConfigurationError(`There is no model named "${name}". ${this.known()}`);
+            }
+            return resolved;
+        }
+        assertModel(reference, 'The `model` option');
+        return { info: identify(reference), model: reference, settings: {}, fallback: [] };
+    }
+    known() {
+        return `Configured: ${this.names().join(', ')}.`;
+    }
+};
+AiModels = __decorate([
+    Injectable(),
+    __param(0, Inject(AI_MODULE_OPTIONS)),
+    __param(1, Optional()),
+    __param(1, Inject(AI_MODEL_OVERRIDES)),
+    __metadata("design:paramtypes", [Object, Object])
+], AiModels);
+export { AiModels };
+function isDefinition(entry) {
+    return typeof entry === 'object' && entry !== null && 'model' in entry && !('specificationVersion' in entry);
+}
+function assertModel(model, where) {
+    const valid = (typeof model === 'string' && model.length > 0) ||
+        (typeof model === 'object' && model !== null && typeof model.doGenerate === 'function');
+    if (!valid) {
+        throw new AiConfigurationError(`${where} is not a language model. Pass one from a provider package, e.g. anthropic('claude-opus-5-5') from @ai-sdk/anthropic.`);
+    }
+}
+/** A string model id goes through the AI Gateway (`ai`'s default provider). */
+function identify(model) {
+    if (typeof model === 'string') {
+        return { provider: 'gateway', modelId: model };
+    }
+    return { provider: model.provider, modelId: model.modelId };
+}

package/dist/models/model-registry.util.d.ts

@@ -0,0 +1,6 @@
+import type { AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+/**
+ * Checks registry structure without contacting a provider. Either kind may be omitted, but not
+ * both.
+ */
+export declare function assertModelRegistries(options: AiModuleOptions): void;

package/dist/models/model-registry.util.js

@@ -0,0 +1,21 @@
+import { AiConfigurationError } from '../errors/ai.errors.js';
+/**
+ * Checks registry structure without contacting a provider. Either kind may be omitted, but not
+ * both.
+ */
+export function assertModelRegistries(options) {
+    let count = 0;
+    for (const key of ['models', 'embeddingModels']) {
+        const entries = options?.[key];
+        if (entries === undefined) {
+            continue;
+        }
+        if (typeof entries !== 'object' || entries === null || Array.isArray(entries)) {
+            throw new AiConfigurationError(`AiModule: \`${key}\` must be a record of named models.`);
+        }
+        count += Object.keys(entries).length;
+    }
+    if (count === 0) {
+        throw new AiConfigurationError('AiModule: configure at least one model in `models` or `embeddingModels`.');
+    }
+}

package/dist/models/model-requests.d.ts

@@ -0,0 +1,5 @@
+export declare function recordModelRequest(name: string): void;
+export declare function requestedModelNames(): string[];
+/** Embedding injection requests use a separate namespace, even when the names are identical. */
+export declare function recordEmbeddingModelRequest(name: string): void;
+export declare function requestedEmbeddingModelNames(): string[];

package/dist/models/model-requests.js

@@ -0,0 +1,20 @@
+/**
+ * The model names `@InjectModel()` asks for, recorded as the decorators run. `AiModule` provides a token for each
+ * name asked for by the time it is defined (with `modelNames` and the names it configures), so that a name it does
+ * not configure fails with a message of its own, not with Nest's missing-provider error.
+ */
+const requested = new Set();
+const requestedEmbeddings = new Set();
+export function recordModelRequest(name) {
+    requested.add(name);
+}
+export function requestedModelNames() {
+    return [...requested];
+}
+/** Embedding injection requests use a separate namespace, even when the names are identical. */
+export function recordEmbeddingModelRequest(name) {
+    requestedEmbeddings.add(name);
+}
+export function requestedEmbeddingModelNames() {
+    return [...requestedEmbeddings];
+}

package/dist/runtime/agent-loop.d.ts

@@ -0,0 +1,30 @@
+import type { UIMessageChunk } from 'ai';
+import type { AiTextResult } from '../interfaces/ai-result.interface.js';
+import type { AiUsage, AiUsageEvent } from '../interfaces/ai-usage.interface.js';
+import { type StepAttempt } from './model-policy.js';
+import type { CallPlan } from './call-plan.js';
+import { type StepOutcome, type StepOutput } from './steps.js';
+export type LoopMode = {
+    stream: false;
+    output?: StepOutput;
+} | {
+    stream: true;
+    emit: (chunk: UIMessageChunk) => void;
+};
+export interface LoopResult {
+    result: AiTextResult;
+    /** The last step's parsed answer (structured output). */
+    output?: unknown;
+    /** The last step's `finish` chunk (streams). */
+    finish?: UIMessageChunk;
+}
+/**
+ * The agent loop: a model call, then, while the model asks for tools (which run inside the call), another one with
+ * the conversation so far, up to `maxSteps`. Each model call runs under its resilience policies (retry, timeout,
+ * fallback); the budget is checked before each. `report` receives a usage event per model call that answered.
+ */
+export declare function runLoop(plan: CallPlan, mode: LoopMode, report: (event: AiUsageEvent) => void): Promise<LoopResult>;
+/** The usage event of a model call that answered. */
+export declare function usageEvent(plan: CallPlan, attempt: StepAttempt, outcome: StepOutcome, stream: boolean): AiUsageEvent;
+/** Throws when the call has spent its budget. */
+export declare function assertWithinBudget(plan: Pick<CallPlan, 'budget'>, usage: AiUsage, cost: number | undefined): void;