@agentier/core 0.1.0

package/dist/loop.d.ts

@@ -0,0 +1,24 @@
+import type { AgentConfig, AgentResult, RunOptions } from './types';
+/**
+ * Executes the core agent reasoning loop: repeatedly calls the model, executes
+ * any requested tools, appends results to the conversation, and repeats until
+ * the model responds without tool calls or a termination condition is met.
+ *
+ * This is the main engine behind {@link Agent.run}. It handles:
+ * - Building the initial message history (from memory, options, or scratch)
+ * - System prompt injection (with optional structured output instructions)
+ * - Model calls (streaming or non-streaming)
+ * - Parallel tool execution with validation
+ * - Middleware dispatch for all actions
+ * - Token budgeting, iteration limits, and timeouts
+ * - Structured output parsing with retry
+ * - Memory persistence
+ *
+ * @typeParam T - The expected output type. Defaults to `string`.
+ * @param config - The agent configuration.
+ * @param prompt - The user prompt to process.
+ * @param options - Optional per-run overrides and callbacks.
+ * @returns A promise resolving to the complete {@link AgentResult}.
+ * @throws {AgentError} When a model call fails, output parsing fails, or other unrecoverable errors occur.
+ */
+export declare function runAgentLoop<T = string>(config: AgentConfig, prompt: string, options?: RunOptions<T>): Promise<AgentResult<T>>;

package/dist/middleware.d.ts

@@ -0,0 +1,45 @@
+import type { AgentAction, AgentActionType, Middleware } from './types';
+/**
+ * Creates a new {@link AgentAction} with the given type, payload, and optional metadata.
+ *
+ * The `timestamp` is automatically set to the current time (`Date.now()`).
+ *
+ * @typeParam T - The specific action type being created.
+ * @param type - The action type discriminator.
+ * @param payload - The type-safe payload for this action.
+ * @param metadata - Optional arbitrary metadata to attach to the action.
+ * @returns A new {@link AgentAction} instance.
+ *
+ * @example
+ * ```ts
+ * const action = createAction('tool_call', {
+ *   id: 'call_1',
+ *   name: 'search',
+ *   arguments: { query: 'hello' },
+ * })
+ * ```
+ */
+export declare function createAction<T extends AgentActionType>(type: T, payload: AgentAction<T>['payload'], metadata?: Record<string, unknown>): AgentAction<T>;
+/**
+ * Executes an action through a chain of middleware functions using the "onion" pattern.
+ *
+ * Each middleware receives the action and a `next()` function. Calling `next()`
+ * passes control to the subsequent middleware, or to the core `execute` handler
+ * if all middleware has been traversed. Middleware can inspect, modify, or
+ * short-circuit the action before or after calling `next()`.
+ *
+ * @param middlewares - The ordered list of middleware functions to run.
+ * @param action - The action to process through the chain.
+ * @param execute - The core handler invoked after all middleware has run.
+ * @returns A promise resolving to the final (possibly modified) action.
+ *
+ * @example
+ * ```ts
+ * const result = await runMiddlewareChain(
+ *   [loggingMiddleware, metricsMiddleware],
+ *   action,
+ *   async () => coreHandler(action),
+ * )
+ * ```
+ */
+export declare function runMiddlewareChain(middlewares: Middleware[], action: AgentAction, execute: () => Promise<AgentAction>): Promise<AgentAction>;

package/dist/tool.d.ts

@@ -0,0 +1,68 @@
+import { type ZodType } from 'zod';
+import type { Tool, JsonSchema, ToolJsonSchema } from './types';
+/**
+ * Creates a fully configured {@link Tool} with resolved JSON Schema metadata.
+ *
+ * This is the recommended way to define tools. It accepts either a Zod schema
+ * or a plain JSON Schema for parameter validation, and eagerly resolves the
+ * internal JSON Schema representation used when communicating with model providers.
+ *
+ * @typeParam TParams - The validated parameter type for the tool.
+ * @typeParam TResult - The return type of the tool's execute function.
+ * @param config - The tool configuration object.
+ * @param config.name - A unique name identifying the tool.
+ * @param config.description - A human-readable description of what the tool does.
+ * @param config.parameters - A Zod schema or plain JSON Schema defining accepted parameters.
+ * @param config.execute - The async function that performs the tool's work.
+ * @returns A fully configured {@link Tool} instance ready to be passed to an agent.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { defineTool } from '@agenti/core'
+ *
+ * const weatherTool = defineTool({
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a city',
+ *   parameters: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => {
+ *     const data = await fetchWeather(city)
+ *     return `${data.temp}°C, ${data.condition}`
+ *   },
+ * })
+ * ```
+ */
+export declare function defineTool<TParams, TResult = unknown>(config: {
+    name: string;
+    description: string;
+    parameters: ZodType<TParams> | JsonSchema;
+    execute: (params: TParams, context: {
+        callId: string;
+        signal: AbortSignal;
+        messages: readonly import('./types').Message[];
+    }) => Promise<TResult>;
+}): Tool<TParams, TResult>;
+/**
+ * Converts a {@link Tool} into its JSON Schema wire format ({@link ToolJsonSchema})
+ * suitable for sending to a model provider.
+ *
+ * If the tool's internal JSON Schema has not been resolved yet (i.e. the tool was
+ * not created via {@link defineTool}), this function resolves it lazily.
+ *
+ * @param tool - The tool to convert.
+ * @returns The tool's name, description, and parameters as a {@link ToolJsonSchema}.
+ */
+export declare function toolToJsonSchema(tool: Tool): ToolJsonSchema;
+/**
+ * Validates tool call arguments against the tool's parameter schema.
+ *
+ * When the tool uses a Zod schema, full parsing and validation is performed.
+ * When the tool uses a plain JSON Schema, the arguments are returned as-is
+ * (validation is assumed to be handled by the model or externally).
+ *
+ * @param tool - The tool whose schema to validate against.
+ * @param args - The raw arguments from the model's tool call.
+ * @returns The validated (and possibly transformed) arguments.
+ * @throws {ZodError} If the tool uses a Zod schema and validation fails.
+ */
+export declare function validateToolArgs(tool: Tool, args: Record<string, unknown>): unknown;

package/dist/types/agent.d.ts

@@ -0,0 +1,185 @@
+import type { ZodType } from 'zod';
+import type { Message } from './message';
+import type { ModelProvider } from './provider';
+import type { Tool } from './tool';
+import type { Middleware } from './middleware';
+import type { MemoryProvider } from './memory';
+/**
+ * Configuration options for creating an agent via {@link createAgent}.
+ *
+ * @example
+ * ```ts
+ * const config: AgentConfig = {
+ *   model: 'gpt-4o',
+ *   provider: openaiProvider,
+ *   systemPrompt: 'You are a helpful assistant.',
+ *   tools: [searchTool, calculatorTool],
+ *   maxIterations: 15,
+ * }
+ * ```
+ */
+export interface AgentConfig {
+    /** The model identifier to use for completions (e.g. `'gpt-4o'`, `'claude-sonnet-4-20250514'`). */
+    model: string;
+    /** The model provider implementation that handles API communication. */
+    provider: ModelProvider;
+    /** An optional system prompt prepended to the conversation to guide the model's behavior. */
+    systemPrompt?: string;
+    /** Tools available for the agent to invoke during its reasoning loop. */
+    tools?: Tool[];
+    /** Middleware functions that intercept and can transform actions in the agent loop. */
+    middleware?: Middleware[];
+    /** A memory provider for persisting conversation history across sessions. */
+    memory?: MemoryProvider;
+    /** Maximum number of model call iterations before the loop terminates. Defaults to `10`. */
+    maxIterations?: number;
+    /** Maximum total token usage before the loop terminates. Defaults to `Infinity`. */
+    maxTokens?: number;
+    /** Maximum wall-clock time in milliseconds before the loop is aborted. Defaults to `60000`. */
+    timeout?: number;
+    /** Default sampling temperature for model calls. Can be overridden per-run. */
+    temperature?: number;
+    /** Default nucleus sampling parameter for model calls. */
+    topP?: number;
+    /** Default maximum output tokens for model responses. Can be overridden per-run. */
+    maxOutputTokens?: number;
+}
+/**
+ * A record of a single tool call that was executed during an agent run,
+ * including its arguments, result, and timing.
+ */
+export interface ExecutedToolCall {
+    /** The unique identifier of the tool call. */
+    id: string;
+    /** The name of the tool that was called. */
+    name: string;
+    /** The arguments that were passed to the tool. */
+    arguments: Record<string, unknown>;
+    /** The value returned by the tool (or an error message string if execution failed). */
+    result: unknown;
+    /** How long the tool execution took, in milliseconds. */
+    duration: number;
+}
+/**
+ * Aggregated token usage statistics for an agent run.
+ */
+export interface UsageStats {
+    /** Total tokens consumed (input + output). */
+    totalTokens: number;
+    /** Total input (prompt) tokens across all model calls. */
+    inputTokens: number;
+    /** Total output (completion) tokens across all model calls. */
+    outputTokens: number;
+    /** The number of model call iterations performed. */
+    iterations: number;
+    /** An optional estimated monetary cost for the run. */
+    estimatedCost?: number;
+}
+/**
+ * The result returned after an agent completes a run.
+ *
+ * @typeParam T - The type of the output. Defaults to `string`, but when an
+ *   `outputSchema` is provided it will be the validated type.
+ */
+export interface AgentResult<T = string> {
+    /** The final output produced by the agent. */
+    output: T;
+    /** The complete conversation history including all messages exchanged during the run. */
+    messages: Message[];
+    /** All tool calls that were executed during the run. */
+    toolCalls: ExecutedToolCall[];
+    /** Aggregated token usage statistics. */
+    usage: UsageStats;
+    /** Total wall-clock duration of the run in milliseconds. */
+    duration: number;
+}
+/**
+ * Options that can be passed to {@link Agent.run} to customize a single run.
+ *
+ * @typeParam T - The expected output type. When `outputSchema` is provided,
+ *   the agent will parse and validate the model's response into this type.
+ */
+export interface RunOptions<T = string> {
+    /** Initial messages to prepend to the conversation (overrides memory loading). */
+    messages?: Message[];
+    /**
+     * A Zod schema for structured output. When provided, the agent instructs the model
+     * to respond with JSON conforming to this schema and validates the result.
+     */
+    outputSchema?: ZodType<T>;
+    /** Sampling temperature override for this run. */
+    temperature?: number;
+    /** Maximum output tokens override for this run. */
+    maxOutputTokens?: number;
+    /**
+     * Callback invoked for each text token as it streams from the model.
+     *
+     * @param token - The text chunk received.
+     */
+    onToken?: (token: string) => void;
+    /**
+     * Callback invoked when the model requests a tool call.
+     *
+     * @param name - The name of the tool being called.
+     * @param args - The arguments passed to the tool.
+     */
+    onToolCall?: (name: string, args: Record<string, unknown>) => void;
+    /**
+     * Callback invoked when a tool returns a result.
+     *
+     * @param name - The name of the tool that returned.
+     * @param result - The value produced by the tool.
+     */
+    onToolResult?: (name: string, result: unknown) => void;
+    /**
+     * Callback invoked when the agent run completes successfully.
+     *
+     * @param result - The final agent result.
+     */
+    onComplete?: (result: AgentResult<T>) => void;
+    /**
+     * Callback invoked when the agent run encounters an error.
+     *
+     * @param error - The error that occurred.
+     */
+    onError?: (error: Error) => void;
+    /** Maximum number of model call iterations for this run. Overrides {@link AgentConfig.maxIterations}. */
+    maxIterations?: number;
+    /** Maximum total token budget for this run. Overrides {@link AgentConfig.maxTokens}. */
+    maxTokens?: number;
+    /** Maximum wall-clock time in milliseconds for this run. Overrides {@link AgentConfig.timeout}. */
+    timeout?: number;
+    /** An external abort signal to cancel the run. */
+    signal?: AbortSignal;
+    /** The session ID used for memory persistence. Defaults to `'default'`. */
+    sessionId?: string;
+    /** When `true`, skips saving the conversation to memory after the run completes. */
+    skipMemorySave?: boolean;
+}
+/**
+ * The public interface of an agent created by {@link createAgent}.
+ */
+export interface Agent {
+    /**
+     * Runs the agent with the given prompt and returns the result.
+     *
+     * @typeParam T - The output type. Defaults to `string`; when `outputSchema` is
+     *   provided in options, it matches the schema's output type.
+     * @param prompt - The user message to send to the agent.
+     * @param options - Optional run-time configuration and callbacks.
+     * @returns A promise resolving to the agent's result including output, messages, and usage stats.
+     *
+     * @example
+     * ```ts
+     * const result = await agent.run('What is the weather in Berlin?')
+     * console.log(result.output)
+     * ```
+     */
+    run<T = string>(prompt: string, options?: RunOptions<T>): Promise<AgentResult<T>>;
+    /**
+     * Returns a frozen (read-only) copy of the agent's configuration.
+     *
+     * @returns The agent's configuration object.
+     */
+    getConfig(): Readonly<AgentConfig>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-exports all public types from the `@agenti/core` type system.
+ *
+ * @module types
+ */
+export type { Role, ToolCall, Message } from './message';
+export type { ToolContext, JsonSchema, ToolJsonSchema, Tool } from './tool';
+export type { ChatParams, ModelResponse, StreamEvent, ModelProvider } from './provider';
+export type { AgentActionType, ActionPayloadMap, AgentAction, Middleware } from './middleware';
+export type { MemoryProvider } from './memory';
+export type { AgentConfig, ExecutedToolCall, UsageStats, AgentResult, RunOptions, Agent, } from './agent';

package/dist/types/memory.d.ts

@@ -0,0 +1,41 @@
+import type { Message } from './message';
+/**
+ * Interface for persisting and retrieving conversation history across sessions.
+ *
+ * Implementations can store messages in-memory, on disk, in a database, or
+ * any other backing store. The agent uses this to maintain context between
+ * separate `run()` invocations.
+ *
+ * @example
+ * ```ts
+ * const memory: MemoryProvider = {
+ *   async load(sessionId) { return db.getMessages(sessionId) },
+ *   async save(sessionId, messages) { await db.setMessages(sessionId, messages) },
+ *   async clear(sessionId) { await db.deleteMessages(sessionId) },
+ * }
+ * ```
+ */
+export interface MemoryProvider {
+    /**
+     * Loads the stored conversation history for the given session.
+     *
+     * @param sessionId - The unique identifier for the conversation session.
+     * @returns A promise resolving to the array of messages in this session.
+     */
+    load(sessionId: string): Promise<Message[]>;
+    /**
+     * Saves the conversation history for the given session, replacing any previously stored messages.
+     *
+     * @param sessionId - The unique identifier for the conversation session.
+     * @param messages - The complete message history to persist.
+     * @returns A promise that resolves when saving is complete.
+     */
+    save(sessionId: string, messages: Message[]): Promise<void>;
+    /**
+     * Clears all stored messages for the given session.
+     *
+     * @param sessionId - The unique identifier for the conversation session.
+     * @returns A promise that resolves when the session data has been deleted.
+     */
+    clear(sessionId: string): Promise<void>;
+}

package/dist/types/message.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Represents the role of a participant in a conversation.
+ *
+ * - `'system'` - System-level instructions that guide the model's behavior.
+ * - `'user'` - A message from the end user.
+ * - `'assistant'` - A response generated by the model.
+ * - `'tool'` - The result of a tool invocation.
+ */
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * Represents a tool invocation requested by the model.
+ *
+ * @example
+ * ```ts
+ * const call: ToolCall = {
+ *   id: 'call_abc123',
+ *   name: 'get_weather',
+ *   arguments: { city: 'Berlin' },
+ * }
+ * ```
+ */
+export interface ToolCall {
+    /** Unique identifier for this tool call, used to match results back to the request. */
+    id: string;
+    /** The name of the tool to invoke. */
+    name: string;
+    /** The parsed arguments to pass to the tool's execute function. */
+    arguments: Record<string, unknown>;
+}
+/**
+ * A single message in the conversation history exchanged between participants.
+ *
+ * @example
+ * ```ts
+ * const userMsg: Message = { role: 'user', content: 'Hello!' }
+ * const toolResult: Message = {
+ *   role: 'tool',
+ *   content: '{"temp": 22}',
+ *   toolCallId: 'call_abc123',
+ * }
+ * ```
+ */
+export interface Message {
+    /** The role of the message author. */
+    role: Role;
+    /** The text content of the message, or `null` when the assistant response consists solely of tool calls. */
+    content: string | null;
+    /** Tool calls requested by the assistant in this message, if any. */
+    toolCalls?: ToolCall[];
+    /** The ID of the tool call this message is a response to (only for `role: 'tool'`). */
+    toolCallId?: string;
+    /** An optional display name for the message author. */
+    name?: string;
+}

package/dist/types/middleware.d.ts

@@ -0,0 +1,123 @@
+import type { AgentConfig, AgentResult } from './agent';
+import type { Message } from './message';
+import type { ModelResponse, ToolJsonSchema } from '../types';
+/**
+ * The discriminated set of action types that flow through the middleware pipeline.
+ *
+ * - `'loop_start'` - The agent loop has begun processing a prompt.
+ * - `'loop_end'` - The agent loop has finished (successfully or due to a limit).
+ * - `'model_call'` - A request is about to be sent to the model provider.
+ * - `'model_response'` - A response has been received from the model provider.
+ * - `'tool_call'` - A tool is about to be invoked.
+ * - `'tool_result'` - A tool has returned a result.
+ * - `'error'` - An error occurred during model or tool execution.
+ */
+export type AgentActionType = 'loop_start' | 'loop_end' | 'model_call' | 'model_response' | 'tool_call' | 'tool_result' | 'error';
+/**
+ * Maps each {@link AgentActionType} to its corresponding payload shape.
+ * Used to provide type-safe payloads on {@link AgentAction}.
+ */
+export interface ActionPayloadMap {
+    /** Payload for the `loop_start` action. */
+    loop_start: {
+        /** The user prompt that initiated the loop. */
+        prompt: string;
+        /** The agent configuration in effect. */
+        config: AgentConfig;
+    };
+    /** Payload for the `loop_end` action. */
+    loop_end: {
+        /** The final result produced by the agent. */
+        result: AgentResult;
+        /** The reason the loop ended. */
+        reason: 'complete' | 'max_iterations' | 'max_tokens' | 'timeout' | 'aborted';
+    };
+    /** Payload for the `model_call` action. */
+    model_call: {
+        /** The messages being sent to the model. */
+        messages: Message[];
+        /** The tool definitions being sent to the model. */
+        tools: ToolJsonSchema[];
+        /** The model identifier being called. */
+        model: string;
+    };
+    /** Payload for the `model_response` action. */
+    model_response: {
+        /** The model's response. */
+        response: ModelResponse;
+        /** Token usage for this call. */
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    };
+    /** Payload for the `tool_call` action. */
+    tool_call: {
+        /** The tool call ID. */
+        id: string;
+        /** The name of the tool being called. */
+        name: string;
+        /** The arguments passed to the tool. */
+        arguments: Record<string, unknown>;
+    };
+    /** Payload for the `tool_result` action. */
+    tool_result: {
+        /** The tool call ID this result corresponds to. */
+        id: string;
+        /** The name of the tool that was called. */
+        name: string;
+        /** The value returned by the tool. */
+        result: unknown;
+        /** How long the tool execution took, in milliseconds. */
+        duration: number;
+    };
+    /** Payload for the `error` action. */
+    error: {
+        /** Where the error originated. */
+        source: 'model' | 'tool' | 'internal';
+        /** The error that occurred. */
+        error: Error;
+        /** The name of the tool, if the error originated from a tool. */
+        name?: string;
+        /** Whether the operation that caused this error can be retried. */
+        retryable: boolean;
+    };
+}
+/**
+ * A typed action object that flows through the middleware pipeline.
+ * Each action carries a discriminated type, its payload, a timestamp, and arbitrary metadata.
+ *
+ * @typeParam T - The specific {@link AgentActionType} this action represents.
+ */
+export interface AgentAction<T extends AgentActionType = AgentActionType> {
+    /** The action type discriminator. */
+    type: T;
+    /** The type-safe payload associated with this action. */
+    payload: T extends keyof ActionPayloadMap ? ActionPayloadMap[T] : never;
+    /** Unix timestamp (milliseconds) when the action was created. */
+    timestamp: number;
+    /** Arbitrary metadata attached to the action by middleware or the agent. */
+    metadata: Record<string, unknown>;
+}
+/**
+ * A middleware function that intercepts actions flowing through the agent loop.
+ *
+ * Middleware can inspect, modify, or short-circuit actions. It follows the
+ * standard "onion" pattern: call `next()` to pass control to the next
+ * middleware (or the core executor), and optionally transform the result.
+ *
+ * @param action - The action being processed.
+ * @param next - Calls the next middleware in the chain (or the core handler).
+ * @returns A promise resolving to the (possibly modified) action.
+ *
+ * @example
+ * ```ts
+ * const loggingMiddleware: Middleware = async (action, next) => {
+ *   console.log('Before:', action.type)
+ *   const result = await next()
+ *   console.log('After:', result.type)
+ *   return result
+ * }
+ * ```
+ */
+export type Middleware = (action: AgentAction, next: () => Promise<AgentAction>) => Promise<AgentAction>;

package/dist/types/provider.d.ts

@@ -0,0 +1,114 @@
+import type { Message, ToolCall } from './message';
+import type { ToolJsonSchema } from './tool';
+/**
+ * Parameters for a chat completion request sent to a model provider.
+ */
+export interface ChatParams {
+    /** The model identifier (e.g. `'gpt-4o'`, `'claude-sonnet-4-20250514'`). */
+    model: string;
+    /** The conversation messages to send to the model. */
+    messages: Message[];
+    /** Tool definitions available for the model to call. When omitted, no tools are provided. */
+    tools?: ToolJsonSchema[];
+    /** Sampling temperature (0-2). Lower values are more deterministic, higher values more creative. */
+    temperature?: number;
+    /** Nucleus sampling parameter. Only tokens with cumulative probability up to `topP` are considered. */
+    topP?: number;
+    /** Maximum number of tokens the model may generate in its response. */
+    maxOutputTokens?: number;
+    /**
+     * Constrains the model output to conform to a JSON schema.
+     * When set, the model will produce structured JSON output.
+     */
+    responseFormat?: {
+        /** The format type. Currently only `'json_schema'` is supported. */
+        type: 'json_schema';
+        /** The JSON Schema the model output must conform to. */
+        schema: Record<string, unknown>;
+    };
+    /** An abort signal that cancels the in-flight request when triggered. */
+    signal?: AbortSignal;
+}
+/**
+ * The complete response returned by a model provider after a non-streaming chat call.
+ */
+export interface ModelResponse {
+    /** The text content of the model's response, or `null` if the response is tool-calls only. */
+    content: string | null;
+    /** Any tool calls the model requested. Empty array when the model did not invoke tools. */
+    toolCalls: ToolCall[];
+    /** Token usage statistics for this request. */
+    usage: {
+        /** The number of tokens in the input (prompt). */
+        inputTokens: number;
+        /** The number of tokens in the output (completion). */
+        outputTokens: number;
+    };
+    /** The raw, provider-specific response object for advanced use cases. */
+    raw?: unknown;
+}
+/**
+ * Events emitted during a streaming model response.
+ *
+ * - `token` - A chunk of generated text.
+ * - `tool_call_start` - The model has begun a tool call.
+ * - `tool_call_delta` - An incremental chunk of tool call arguments.
+ * - `tool_call_end` - The tool call is complete with fully assembled arguments.
+ * - `done` - The stream has finished; includes the full {@link ModelResponse}.
+ * - `error` - An error occurred during streaming.
+ */
+export type StreamEvent = {
+    type: 'token';
+    text: string;
+} | {
+    type: 'tool_call_start';
+    id: string;
+    name: string;
+} | {
+    type: 'tool_call_delta';
+    id: string;
+    argumentsDelta: string;
+} | {
+    type: 'tool_call_end';
+    id: string;
+    call: ToolCall;
+} | {
+    type: 'done';
+    response: ModelResponse;
+} | {
+    type: 'error';
+    error: Error;
+};
+/**
+ * Interface that model providers must implement to be used with the agent.
+ *
+ * A provider adapts a specific LLM API (OpenAI, Anthropic, etc.) into the
+ * common interface the agent loop expects.
+ *
+ * @example
+ * ```ts
+ * const provider: ModelProvider = {
+ *   name: 'openai',
+ *   async chat(params) { ... },
+ *   async *stream(params) { ... },
+ * }
+ * ```
+ */
+export interface ModelProvider {
+    /** A human-readable name identifying this provider (e.g. `'openai'`, `'anthropic'`). */
+    readonly name: string;
+    /**
+     * Sends a chat completion request and returns the full response.
+     *
+     * @param params - The chat request parameters including model, messages, and tools.
+     * @returns A promise resolving to the model's complete response.
+     */
+    chat(params: ChatParams): Promise<ModelResponse>;
+    /**
+     * Sends a chat completion request and returns a stream of incremental events.
+     *
+     * @param params - The chat request parameters including model, messages, and tools.
+     * @returns An async iterable of {@link StreamEvent} objects.
+     */
+    stream(params: ChatParams): AsyncIterable<StreamEvent>;
+}