@modelrelay/sdk 0.5.0 → 0.14.1

package/dist/index.d.cts

@@ -1,7 +1,5 @@
 declare const SDK_VERSION: string;
 declare const DEFAULT_BASE_URL = "https://api.modelrelay.ai/api/v1";
-declare const STAGING_BASE_URL = "https://api-stg.modelrelay.ai/api/v1";
-declare const SANDBOX_BASE_URL = "https://api.sandbox.modelrelay.ai/api/v1";
 declare const DEFAULT_CLIENT_HEADER: string;
 declare const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
@@ -27,8 +25,8 @@ type StopReason = KnownStopReason | {
 declare const Providers: {
     readonly OpenAI: "openai";
     readonly Anthropic: "anthropic";
-    readonly Grok: "grok";
-    readonly OpenRouter: "openrouter";
+    readonly XAI: "xai";
+    readonly GoogleAIStudio: "google-ai-studio";
     readonly Echo: "echo";
 };
 type KnownProvider = (typeof Providers)[keyof typeof Providers];
@@ -36,22 +34,123 @@ type ProviderId = KnownProvider | {
     other: string;
 };
 declare const Models: {
-    readonly OpenAIGpt4o: "openai/gpt-4o";
-    readonly OpenAIGpt4oMini: "openai/gpt-4o-mini";
-    readonly OpenAIGpt51: "openai/gpt-5.1";
-    readonly AnthropicClaude35HaikuLatest: "anthropic/claude-3-5-haiku-latest";
-    readonly AnthropicClaude35SonnetLatest: "anthropic/claude-3-5-sonnet-latest";
-    readonly AnthropicClaudeOpus45: "anthropic/claude-opus-4-5-20251101";
-    readonly OpenRouterClaude35Haiku: "anthropic/claude-3.5-haiku";
+    readonly Gpt4o: "gpt-4o";
+    readonly Gpt4oMini: "gpt-4o-mini";
+    readonly Gpt51: "gpt-5.1";
+    readonly Claude35HaikuLatest: "claude-3-5-haiku-latest";
+    readonly Claude35SonnetLatest: "claude-3-5-sonnet-latest";
+    readonly ClaudeOpus45: "claude-opus-4-5";
+    readonly Claude35Haiku: "claude-3.5-haiku";
     readonly Grok2: "grok-2";
-    readonly Grok4Fast: "grok-4-fast";
+    readonly Grok4_1FastNonReasoning: "grok-4-1-fast-non-reasoning";
+    readonly Grok4_1FastReasoning: "grok-4-1-fast-reasoning";
     readonly Echo1: "echo-1";
 };
 type KnownModel = (typeof Models)[keyof typeof Models];
 type ModelId = KnownModel | {
     other: string;
-} | string;
-interface ModelRelayOptions {
+};
+/**
+ * Common configuration options for the ModelRelay client.
+ */
+interface ModelRelayBaseOptions {
+    /**
+     * Optional base URL override. Defaults to production API.
+     */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /**
+     * Default customer metadata used when exchanging publishable keys for frontend tokens.
+     */
+    customer?: FrontendCustomer;
+    /**
+     * Optional client header override for telemetry.
+     */
+    clientHeader?: string;
+    /**
+     * Default connect timeout in milliseconds (applies to each attempt).
+     */
+    connectTimeoutMs?: number;
+    /**
+     * Default request timeout in milliseconds (non-streaming). Set to 0 to disable.
+     */
+    timeoutMs?: number;
+    /**
+     * Retry configuration applied to all requests (can be overridden per call). Set to `false` to disable retries.
+     */
+    retry?: RetryConfig | false;
+    /**
+     * Default HTTP headers applied to every request.
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Default metadata merged into every chat completion request.
+     */
+    defaultMetadata?: Record<string, string>;
+    /**
+     * Optional metrics callbacks for latency/usage.
+     */
+    metrics?: MetricsCallbacks;
+    /**
+     * Optional trace/log hooks for request + stream lifecycle.
+     */
+    trace?: TraceCallbacks;
+}
+/**
+ * Configuration options requiring an API key.
+ */
+interface ModelRelayKeyOptions extends ModelRelayBaseOptions {
+    /**
+     * API key (secret or publishable). Required.
+     * - Secret keys (`mr_sk_...`) are for server-side API calls.
+     * - Publishable keys (`mr_pk_...`) are for frontend token exchange.
+     */
+    key: string;
+    /**
+     * Optional bearer token (takes precedence over key for requests when provided).
+     */
+    token?: string;
+}
+/**
+ * Configuration options requiring an access token.
+ */
+interface ModelRelayTokenOptions extends ModelRelayBaseOptions {
+    /**
+     * Optional API key.
+     */
+    key?: string;
+    /**
+     * Bearer token to call the API directly (server or frontend token). Required.
+     */
+    token: string;
+}
+/**
+ * ModelRelay client configuration.
+ *
+ * You must provide at least one of `key` or `token` for authentication.
+ * This is enforced at compile time through discriminated union types.
+ *
+ * @example With API key (server-side)
+ * ```typescript
+ * const client = new ModelRelay({ key: "mr_sk_..." });
+ * ```
+ *
+ * @example With access token (frontend or after token exchange)
+ * ```typescript
+ * const client = new ModelRelay({ token: frontendToken });
+ * ```
+ *
+ * @example With publishable key (frontend token exchange)
+ * ```typescript
+ * const client = new ModelRelay({ key: "mr_pk_...", customer: { id: "user123" } });
+ * ```
+ */
+type ModelRelayOptions = ModelRelayKeyOptions | ModelRelayTokenOptions;
+/**
+ * @deprecated Use ModelRelayOptions instead. This type allows empty configuration
+ * which will fail at runtime.
+ */
+interface ModelRelayOptionsLegacy {
     /**
      * API key (secret or publishable). Publishable keys are required for frontend token exchange.
      */
@@ -61,9 +160,8 @@ interface ModelRelayOptions {
      */
     token?: string;
     /**
-     * Optional environment preset; overridden by `baseUrl` when provided.
+     * Optional base URL override. Defaults to production API.
      */
-    environment?: Environment;
     baseUrl?: string;
     fetch?: typeof fetch;
     /**
@@ -103,7 +201,6 @@ interface ModelRelayOptions {
      */
     trace?: TraceCallbacks;
 }
-type Environment = "production" | "staging" | "sandbox";
 interface FrontendCustomer {
     id: string;
     deviceId?: string;
@@ -142,6 +239,10 @@ interface Usage {
     outputTokens: number;
     totalTokens: number;
 }
+/**
+ * Creates a Usage object with automatic totalTokens calculation if not provided.
+ */
+declare function createUsage(inputTokens: number, outputTokens: number, totalTokens?: number): Usage;
 interface UsageSummary {
     plan: string;
     planType?: string;
@@ -164,9 +265,68 @@ interface Project {
 interface ChatMessage {
     role: string;
     content: string;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+}
+declare const ToolTypes: {
+    readonly Function: "function";
+    readonly Web: "web";
+    readonly XSearch: "x_search";
+    readonly CodeExecution: "code_execution";
+};
+type ToolType = (typeof ToolTypes)[keyof typeof ToolTypes];
+interface FunctionTool {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+type WebToolMode = "auto" | "search_only" | "fetch_only" | "search_and_fetch";
+interface WebToolConfig {
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+    maxUses?: number;
+    mode?: WebToolMode;
+}
+interface XSearchConfig {
+    allowedHandles?: string[];
+    excludedHandles?: string[];
+    fromDate?: string;
+    toDate?: string;
+}
+interface CodeExecConfig {
+    language?: string;
+    timeoutMs?: number;
+}
+interface Tool {
+    type: ToolType;
+    function?: FunctionTool;
+    web?: WebToolConfig;
+    xSearch?: XSearchConfig;
+    codeExecution?: CodeExecConfig;
+}
+declare const ToolChoiceTypes: {
+    readonly Auto: "auto";
+    readonly Required: "required";
+    readonly None: "none";
+};
+type ToolChoiceType = (typeof ToolChoiceTypes)[keyof typeof ToolChoiceTypes];
+interface ToolChoice {
+    type: ToolChoiceType;
+}
+interface FunctionCall {
+    name: string;
+    arguments: string;
+}
+interface ToolCall {
+    id: string;
+    type: ToolType;
+    function?: FunctionCall;
 }
 interface ChatCompletionCreateParams {
-    model: ModelId;
+    /**
+     * Model to use for the request. Optional - if omitted, the tier's default model is used.
+     */
+    model?: KnownModel;
     messages: NonEmptyArray<ChatMessage>;
     provider?: ProviderId;
     maxTokens?: number;
@@ -174,6 +334,14 @@ interface ChatCompletionCreateParams {
     metadata?: Record<string, string>;
     stop?: string[];
     stopSequences?: string[];
+    /**
+     * Tools available for the model to call.
+     */
+    tools?: Tool[];
+    /**
+     * Controls how the model responds to tool calls.
+     */
+    toolChoice?: ToolChoice;
     /**
      * When using publishable keys, a customer id is required to mint a frontend token.
      */
@@ -195,6 +363,7 @@ interface ChatCompletionResponse {
     model?: ModelId;
     usage: Usage;
     requestId?: string;
+    toolCalls?: ToolCall[];
 }
 interface FieldError {
     field?: string;
@@ -267,7 +436,7 @@ declare function normalizeProvider(value?: unknown): ProviderId | undefined;
 declare function providerToString(value?: ProviderId): string | undefined;
 declare function normalizeModelId(value: unknown): ModelId | undefined;
 declare function modelToString(value: ModelId): string;
-type ChatEventType = "message_start" | "message_delta" | "message_stop" | "ping" | "custom";
+type ChatEventType = "message_start" | "message_delta" | "message_stop" | "tool_use_start" | "tool_use_delta" | "tool_use_stop" | "ping" | "custom";
 interface MessageStartData {
     responseId?: string;
     model?: string;
@@ -290,11 +459,27 @@ interface MessageStopData {
     model?: ModelId;
     [key: string]: unknown;
 }
+/** Incremental update to a tool call during streaming. */
+interface ToolCallDelta {
+    index: number;
+    id?: string;
+    type?: string;
+    function?: FunctionCallDelta;
+}
+/** Incremental function call data. */
+interface FunctionCallDelta {
+    name?: string;
+    arguments?: string;
+}
 interface ChatCompletionEvent<T = unknown> {
     type: ChatEventType;
     event: string;
     data?: T;
     textDelta?: string;
+    /** Incremental tool call update during streaming. */
+    toolCallDelta?: ToolCallDelta;
+    /** Completed tool calls when type is tool_use_stop or message_stop. */
+    toolCalls?: ToolCall[];
     responseId?: string;
     model?: ModelId;
     stopReason?: StopReason;
@@ -424,7 +609,6 @@ declare class HTTPClient {
         timeoutMs?: number;
         retry?: RetryConfig | false;
         defaultHeaders?: Record<string, string>;
-        environment?: Environment;
         metrics?: MetricsCallbacks;
         trace?: TraceCallbacks;
     });
@@ -441,6 +625,14 @@ interface AuthHeaders {
     apiKey?: string;
     accessToken?: string;
 }
+/**
+ * Creates AuthHeaders with an API key.
+ */
+declare function createApiKeyAuth(apiKey: string): AuthHeaders;
+/**
+ * Creates AuthHeaders with an access token.
+ */
+declare function createAccessTokenAuth(accessToken: string): AuthHeaders;
 declare class AuthClient {
     private readonly http;
     private readonly apiKey?;
@@ -560,7 +752,7 @@ interface Customer {
     tier_id: string;
     tier_code?: string;
     external_id: string;
-    email?: string;
+    email: string;
     metadata?: CustomerMetadata;
     stripe_customer_id?: string;
     stripe_subscription_id?: string;
@@ -576,7 +768,7 @@ interface Customer {
 interface CustomerCreateRequest {
     tier_id: string;
     external_id: string;
-    email?: string;
+    email: string;
     metadata?: CustomerMetadata;
 }
 /**
@@ -585,7 +777,7 @@ interface CustomerCreateRequest {
 interface CustomerUpsertRequest {
     tier_id: string;
     external_id: string;
-    email?: string;
+    email: string;
     metadata?: CustomerMetadata;
 }
 /**
@@ -668,8 +860,7 @@ interface Tier {
     project_id: string;
     tier_code: string;
     display_name: string;
-    actions_limit: number;
-    token_limit: number;
+    spend_limit_cents: number;
     stripe_price_id?: string;
     price_amount?: number;
     price_currency?: string;
@@ -700,6 +891,24 @@ declare class TiersClient {
     get(tierId: string): Promise<Tier>;
 }
 
+/**
+ * API error codes returned by the server.
+ * These constants can be used for programmatic error handling.
+ */
+declare const ErrorCodes: {
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly RATE_LIMIT: "RATE_LIMIT";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly CONFLICT: "CONFLICT";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
+    readonly METHOD_NOT_ALLOWED: "METHOD_NOT_ALLOWED";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
 type ErrorCategory = "config" | "transport" | "api";
 declare class ModelRelayError extends Error {
     category: ErrorCategory;
@@ -741,9 +950,438 @@ declare class APIError extends ModelRelayError {
         data?: unknown;
         retries?: RetryMetadata;
     });
+    /** Returns true if the error is a not found error. */
+    isNotFound(): boolean;
+    /** Returns true if the error is a validation error. */
+    isValidation(): boolean;
+    /** Returns true if the error is a rate limit error. */
+    isRateLimit(): boolean;
+    /** Returns true if the error is an unauthorized error. */
+    isUnauthorized(): boolean;
+    /** Returns true if the error is a forbidden error. */
+    isForbidden(): boolean;
+    /** Returns true if the error is a service unavailable error. */
+    isUnavailable(): boolean;
 }
 declare function parseErrorResponse(response: Response, retries?: RetryMetadata): Promise<APIError>;
 
+/**
+ * Creates a user message.
+ */
+declare function createUserMessage(content: string): ChatMessage;
+/**
+ * Creates an assistant message.
+ */
+declare function createAssistantMessage(content: string): ChatMessage;
+/**
+ * Creates a system message.
+ */
+declare function createSystemMessage(content: string): ChatMessage;
+/**
+ * Creates a tool call object.
+ */
+declare function createToolCall(id: string, name: string, args: string, type?: ToolType): ToolCall;
+/**
+ * Creates a function call object.
+ */
+declare function createFunctionCall(name: string, args: string): FunctionCall;
+/**
+ * Interface for Zod-like schema types.
+ * Compatible with Zod's ZodType and similar libraries.
+ */
+interface ZodLikeSchema {
+    _def: {
+        typeName: string;
+        [key: string]: unknown;
+    };
+    parse(data: unknown): unknown;
+    safeParse(data: unknown): {
+        success: boolean;
+        data?: unknown;
+        error?: unknown;
+    };
+}
+/**
+ * Options for JSON Schema generation.
+ */
+interface JsonSchemaOptions {
+    /** Whether to include $schema property. Defaults to false. */
+    includeSchema?: boolean;
+    /** Target JSON Schema version. Defaults to "draft-07". */
+    target?: "draft-04" | "draft-07" | "draft-2019-09" | "draft-2020-12";
+}
+/**
+ * Converts a Zod schema to JSON Schema.
+ * This is a simplified implementation that handles common Zod types.
+ * For full Zod support, consider using the 'zod-to-json-schema' package.
+ *
+ * @param schema - A Zod schema
+ * @param options - Optional JSON Schema generation options
+ * @returns A JSON Schema object
+ */
+declare function zodToJsonSchema(schema: ZodLikeSchema, options?: JsonSchemaOptions): Record<string, unknown>;
+/**
+ * Creates a function tool from a Zod schema.
+ *
+ * This function automatically converts a Zod schema to a JSON Schema
+ * and creates a tool definition. It eliminates the need to manually
+ * write JSON schemas for tool parameters.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { createFunctionToolFromSchema } from "@modelrelay/sdk";
+ *
+ * const weatherParams = z.object({
+ *   location: z.string().describe("City name"),
+ *   unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
+ * });
+ *
+ * const weatherTool = createFunctionToolFromSchema(
+ *   "get_weather",
+ *   "Get weather for a location",
+ *   weatherParams
+ * );
+ * ```
+ *
+ * @param name - The tool name
+ * @param description - A description of what the tool does
+ * @param schema - A Zod schema defining the tool's parameters
+ * @param options - Optional JSON Schema generation options
+ * @returns A Tool definition with the JSON schema derived from the Zod schema
+ */
+declare function createFunctionToolFromSchema(name: string, description: string, schema: ZodLikeSchema, options?: JsonSchemaOptions): Tool;
+/**
+ * Creates a function tool with the given name, description, and JSON schema.
+ */
+declare function createFunctionTool(name: string, description: string, parameters?: Record<string, unknown>): Tool;
+/**
+ * Creates a web tool with optional domain filters and mode.
+ */
+declare function createWebTool(options?: {
+    mode?: WebToolMode;
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+    maxUses?: number;
+}): Tool;
+/**
+ * Returns a ToolChoice that lets the model decide when to use tools.
+ */
+declare function toolChoiceAuto(): ToolChoice;
+/**
+ * Returns a ToolChoice that forces the model to use a tool.
+ */
+declare function toolChoiceRequired(): ToolChoice;
+/**
+ * Returns a ToolChoice that prevents the model from using tools.
+ */
+declare function toolChoiceNone(): ToolChoice;
+/**
+ * Returns true if the response contains tool calls.
+ */
+declare function hasToolCalls(response: ChatCompletionResponse): boolean;
+/**
+ * Returns the first tool call from a response, or undefined if none exist.
+ */
+declare function firstToolCall(response: ChatCompletionResponse): ToolCall | undefined;
+/**
+ * Creates a message containing the result of a tool call.
+ */
+declare function toolResultMessage(toolCallId: string, result: unknown): ChatMessage;
+/**
+ * Creates a tool result message from a ToolCall.
+ * Convenience wrapper around toolResultMessage using the call's ID.
+ */
+declare function respondToToolCall(call: ToolCall, result: unknown): ChatMessage;
+/**
+ * Creates an assistant message that includes tool calls.
+ * Used to include the assistant's tool-calling turn in conversation history.
+ */
+declare function assistantMessageWithToolCalls(content: string, toolCalls: ToolCall[]): ChatMessage;
+/**
+ * Accumulates streaming tool call deltas into complete tool calls.
+ */
+declare class ToolCallAccumulator {
+    private calls;
+    /**
+     * Processes a streaming tool call delta.
+     * Returns true if this started a new tool call.
+     */
+    processDelta(delta: ToolCallDelta): boolean;
+    /**
+     * Returns all accumulated tool calls in index order.
+     */
+    getToolCalls(): ToolCall[];
+    /**
+     * Returns a specific tool call by index, or undefined if not found.
+     */
+    getToolCall(index: number): ToolCall | undefined;
+    /**
+     * Clears all accumulated tool calls.
+     */
+    reset(): void;
+}
+/**
+ * Error thrown when tool argument parsing or validation fails.
+ * Contains a descriptive message suitable for sending back to the model.
+ */
+declare class ToolArgsError extends Error {
+    /** The tool call ID for correlation */
+    readonly toolCallId: string;
+    /** The tool name that was called */
+    readonly toolName: string;
+    /** The raw arguments string that failed to parse */
+    readonly rawArguments: string;
+    constructor(message: string, toolCallId: string, toolName: string, rawArguments: string);
+}
+/**
+ * Schema interface compatible with Zod, Yup, and similar validation libraries.
+ * Any object with a `parse` method that returns the validated type works.
+ */
+interface Schema<T> {
+    parse(data: unknown): T;
+}
+/**
+ * Parses and validates tool call arguments using a schema.
+ *
+ * Works with any schema library that has a `parse` method (Zod, Yup, etc.).
+ * Throws a descriptive ToolArgsError if parsing or validation fails.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ *
+ * const WeatherArgs = z.object({
+ *   location: z.string(),
+ *   unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
+ * });
+ *
+ * // In your tool handler:
+ * const args = parseToolArgs(toolCall, WeatherArgs);
+ * // args is typed as { location: string; unit: "celsius" | "fahrenheit" }
+ * ```
+ *
+ * @param call - The tool call containing arguments to parse
+ * @param schema - A schema with a `parse` method (Zod, Yup, etc.)
+ * @returns The parsed and validated arguments with proper types
+ * @throws {ToolArgsError} If JSON parsing or schema validation fails
+ */
+declare function parseToolArgs<T>(call: ToolCall, schema: Schema<T>): T;
+/**
+ * Attempts to parse tool arguments, returning a result object instead of throwing.
+ *
+ * @example
+ * ```typescript
+ * const result = tryParseToolArgs(toolCall, WeatherArgs);
+ * if (result.success) {
+ *   console.log(result.data.location);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ *
+ * @param call - The tool call containing arguments to parse
+ * @param schema - A schema with a `parse` method
+ * @returns An object with either { success: true, data: T } or { success: false, error: ToolArgsError }
+ */
+declare function tryParseToolArgs<T>(call: ToolCall, schema: Schema<T>): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: ToolArgsError;
+};
+/**
+ * Parses raw JSON arguments without schema validation.
+ * Useful when you want JSON parsing error handling but not schema validation.
+ *
+ * @param call - The tool call containing arguments to parse
+ * @returns The parsed JSON as an unknown type
+ * @throws {ToolArgsError} If JSON parsing fails
+ */
+declare function parseToolArgsRaw(call: ToolCall): unknown;
+/**
+ * Handler function type for tool execution.
+ * Can be sync or async, receives parsed arguments and returns a result.
+ */
+type ToolHandler<T = unknown, R = unknown> = (args: T, call: ToolCall) => R | Promise<R>;
+/**
+ * Result of executing a tool call.
+ */
+interface ToolExecutionResult {
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    error?: string;
+    /**
+     * True if the error is due to malformed arguments (JSON parse or validation failure)
+     * and the model should be given a chance to retry with corrected arguments.
+     */
+    isRetryable?: boolean;
+}
+/**
+ * Registry for mapping tool names to handler functions with automatic dispatch.
+ *
+ * @example
+ * ```typescript
+ * const registry = new ToolRegistry()
+ *   .register("get_weather", async (args) => {
+ *     return { temp: 72, unit: "fahrenheit" };
+ *   })
+ *   .register("search", async (args) => {
+ *     return { results: ["result1", "result2"] };
+ *   });
+ *
+ * // Execute all tool calls from a response
+ * const results = await registry.executeAll(response.toolCalls);
+ *
+ * // Convert results to messages for the next request
+ * const messages = registry.resultsToMessages(results);
+ * ```
+ */
+declare class ToolRegistry {
+    private handlers;
+    /**
+     * Registers a handler function for a tool name.
+     * @param name - The tool name (must match the function name in the tool definition)
+     * @param handler - Function to execute when this tool is called
+     * @returns this for chaining
+     */
+    register<T = unknown, R = unknown>(name: string, handler: ToolHandler<T, R>): this;
+    /**
+     * Unregisters a tool handler.
+     * @param name - The tool name to unregister
+     * @returns true if the handler was removed, false if it didn't exist
+     */
+    unregister(name: string): boolean;
+    /**
+     * Checks if a handler is registered for the given tool name.
+     */
+    has(name: string): boolean;
+    /**
+     * Returns the list of registered tool names.
+     */
+    getRegisteredTools(): string[];
+    /**
+     * Executes a single tool call.
+     * @param call - The tool call to execute
+     * @returns The execution result
+     */
+    execute(call: ToolCall): Promise<ToolExecutionResult>;
+    /**
+     * Executes multiple tool calls in parallel.
+     * @param calls - Array of tool calls to execute
+     * @returns Array of execution results in the same order as input
+     */
+    executeAll(calls: ToolCall[]): Promise<ToolExecutionResult[]>;
+    /**
+     * Converts execution results to tool result messages.
+     * Useful for appending to the conversation history.
+     * @param results - Array of execution results
+     * @returns Array of ChatMessage objects with role "tool"
+     */
+    resultsToMessages(results: ToolExecutionResult[]): ChatMessage[];
+}
+/**
+ * Formats a tool execution error into a message suitable for sending back to the model.
+ * The message is designed to help the model understand what went wrong and correct it.
+ *
+ * @example
+ * ```typescript
+ * const result = await registry.execute(toolCall);
+ * if (result.error && result.isRetryable) {
+ *   const errorMessage = formatToolErrorForModel(result);
+ *   messages.push(toolResultMessage(result.toolCallId, errorMessage));
+ *   // Continue conversation to let model retry
+ * }
+ * ```
+ */
+declare function formatToolErrorForModel(result: ToolExecutionResult): string;
+/**
+ * Checks if any results have retryable errors.
+ *
+ * @example
+ * ```typescript
+ * const results = await registry.executeAll(toolCalls);
+ * if (hasRetryableErrors(results)) {
+ *   // Send error messages back to model and continue conversation
+ * }
+ * ```
+ */
+declare function hasRetryableErrors(results: ToolExecutionResult[]): boolean;
+/**
+ * Filters results to only those with retryable errors.
+ */
+declare function getRetryableErrors(results: ToolExecutionResult[]): ToolExecutionResult[];
+/**
+ * Creates tool result messages for retryable errors, formatted to help the model correct them.
+ *
+ * @example
+ * ```typescript
+ * const results = await registry.executeAll(toolCalls);
+ * if (hasRetryableErrors(results)) {
+ *   const retryMessages = createRetryMessages(results);
+ *   messages.push(...retryMessages);
+ *   // Make another API call to let model retry
+ * }
+ * ```
+ */
+declare function createRetryMessages(results: ToolExecutionResult[]): ChatMessage[];
+/**
+ * Options for executeWithRetry.
+ */
+interface RetryOptions {
+    /**
+     * Maximum number of retry attempts for parse/validation errors.
+     * @default 2
+     */
+    maxRetries?: number;
+    /**
+     * Callback invoked when a retryable error occurs.
+     * Should return new tool calls from the model's response.
+     * If not provided, executeWithRetry will not retry automatically.
+     *
+     * @param errorMessages - Messages to send back to the model
+     * @param attempt - Current attempt number (1-based)
+     * @returns New tool calls from the model, or empty array to stop retrying
+     */
+    onRetry?: (errorMessages: ChatMessage[], attempt: number) => Promise<ToolCall[]>;
+}
+/**
+ * Executes tool calls with automatic retry on parse/validation errors.
+ *
+ * This is a higher-level utility that wraps registry.executeAll with retry logic.
+ * When a retryable error occurs, it calls the onRetry callback to get new tool calls
+ * from the model and continues execution.
+ *
+ * **Result Preservation**: Successful results are preserved across retries. If you
+ * execute multiple tool calls and only some fail, the successful results are kept
+ * and merged with the results from retry attempts. Results are keyed by toolCallId,
+ * so if a retry returns a call with the same ID as a previous result, the newer
+ * result will replace it.
+ *
+ * @example
+ * ```typescript
+ * const results = await executeWithRetry(registry, toolCalls, {
+ *   maxRetries: 2,
+ *   onRetry: async (errorMessages, attempt) => {
+ *     console.log(`Retry attempt ${attempt}`);
+ *     // Add error messages to conversation and call the model again
+ *     messages.push(assistantMessageWithToolCalls("", toolCalls));
+ *     messages.push(...errorMessages);
+ *     const response = await client.chat.completions.create({ messages, tools });
+ *     return response.toolCalls ?? [];
+ *   },
+ * });
+ * ```
+ *
+ * @param registry - The tool registry to use for execution
+ * @param toolCalls - Initial tool calls to execute
+ * @param options - Retry configuration
+ * @returns Final execution results after all retries, including preserved successes
+ */
+declare function executeWithRetry(registry: ToolRegistry, toolCalls: ToolCall[], options?: RetryOptions): Promise<ToolExecutionResult[]>;
+
 declare class ModelRelay {
     readonly chat: ChatClient;
     readonly auth: AuthClient;
@@ -753,4 +1391,4 @@ declare class ModelRelay {
     constructor(options: ModelRelayOptions);
 }
 
-export { type APIChatResponse, type APIChatUsage, type APICheckoutSession, type APICustomerRef, APIError, type APIFrontendToken, type APIKey, AuthClient, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutSession, type CheckoutSessionRequest, ConfigError, type Customer, type CustomerCreateRequest, type CustomerMetadata, type CustomerUpsertRequest, CustomersClient, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, type Environment, type ErrorCategory, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenRequest, type HttpRequestMetrics, type KnownModel, type KnownProvider, type KnownStopReason, type MessageDeltaData, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, ModelRelayError, type ModelRelayOptions, Models, type NonEmptyArray, type PriceInterval, type Project, type ProviderId, Providers, type RequestContext, type RetryConfig, type RetryMetadata, SANDBOX_BASE_URL, SDK_VERSION, STAGING_BASE_URL, type StopReason, StopReasons, type StreamFirstTokenMetrics, type SubscriptionStatus, type Tier, TiersClient, type TokenUsageMetrics, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeProvider, normalizeStopReason, parseErrorResponse, providerToString, stopReasonToString };
+export { type APIChatResponse, type APIChatUsage, type APICheckoutSession, type APICustomerRef, APIError, type APIFrontendToken, type APIKey, AuthClient, type AuthHeaders, ChatClient, type ChatCompletionCreateParams, type ChatCompletionEvent, type ChatCompletionResponse, ChatCompletionsStream, type ChatEventType, type ChatMessage, type CheckoutSession, type CheckoutSessionRequest, type CodeExecConfig, ConfigError, type Customer, type CustomerCreateRequest, type CustomerMetadata, type CustomerUpsertRequest, CustomersClient, DEFAULT_BASE_URL, DEFAULT_CLIENT_HEADER, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_REQUEST_TIMEOUT_MS, type ErrorCategory, type ErrorCode, ErrorCodes, type FieldError, type FrontendCustomer, type FrontendToken, type FrontendTokenRequest, type FunctionCall, type FunctionCallDelta, type FunctionTool, type HttpRequestMetrics, type JsonSchemaOptions, type KnownModel, type KnownProvider, type KnownStopReason, type MessageDeltaData, type MessageStartData, type MessageStopData, type MetricsCallbacks, type ModelId, ModelRelay, type ModelRelayBaseOptions, ModelRelayError, type ModelRelayKeyOptions, type ModelRelayOptions, type ModelRelayOptionsLegacy, type ModelRelayTokenOptions, Models, type NonEmptyArray, type PriceInterval, type Project, type ProviderId, Providers, type RequestContext, type RetryConfig, type RetryMetadata, type RetryOptions, SDK_VERSION, type Schema, type StopReason, StopReasons, type StreamFirstTokenMetrics, type SubscriptionStatus, type Tier, TiersClient, type TokenUsageMetrics, type Tool, ToolArgsError, type ToolCall, ToolCallAccumulator, type ToolCallDelta, type ToolChoice, type ToolChoiceType, ToolChoiceTypes, type ToolExecutionResult, type ToolHandler, ToolRegistry, type ToolType, ToolTypes, type TraceCallbacks, TransportError, type TransportErrorKind, type Usage, type UsageSummary, type WebToolConfig, type WebToolMode, type XSearchConfig, type ZodLikeSchema, assistantMessageWithToolCalls, createAccessTokenAuth, createApiKeyAuth, createAssistantMessage, createFunctionCall, createFunctionTool, createFunctionToolFromSchema, createRetryMessages, createSystemMessage, createToolCall, createUsage, createUserMessage, createWebTool, executeWithRetry, firstToolCall, formatToolErrorForModel, getRetryableErrors, hasRetryableErrors, hasToolCalls, isPublishableKey, mergeMetrics, mergeTrace, modelToString, normalizeModelId, normalizeProvider, normalizeStopReason, parseErrorResponse, parseToolArgs, parseToolArgsRaw, providerToString, respondToToolCall, stopReasonToString, toolChoiceAuto, toolChoiceNone, toolChoiceRequired, toolResultMessage, tryParseToolArgs, zodToJsonSchema };