@jaypie/llm 1.1.27 → 1.1.30-rc.0

package/dist/esm/operate/OperateLoop.d.ts

@@ -0,0 +1,61 @@
+import { LlmHistory, LlmInputMessage, LlmOperateOptions, LlmOperateResponse } from "../types/LlmProvider.interface.js";
+import { ProviderAdapter } from "./adapters/ProviderAdapter.interface.js";
+import { HookRunner } from "./hooks/index.js";
+import { InputProcessor } from "./input/index.js";
+import { RetryPolicy } from "./retry/index.js";
+export interface OperateLoopConfig {
+    adapter: ProviderAdapter;
+    client: unknown;
+    hookRunner?: HookRunner;
+    inputProcessor?: InputProcessor;
+    maxRetries?: number;
+    retryPolicy?: RetryPolicy;
+}
+/**
+ * OperateLoop implements the core multi-turn conversation loop.
+ * It orchestrates provider adapters, retry logic, hook execution, and tool calling.
+ *
+ * This class uses Template Method + Strategy patterns:
+ * - Template Method: The execute() method defines the algorithm skeleton
+ * - Strategy: Provider adapters handle provider-specific operations
+ */
+export declare class OperateLoop {
+    private readonly adapter;
+    private readonly client;
+    private readonly hookRunnerInstance;
+    private readonly inputProcessorInstance;
+    private readonly maxRetries;
+    private readonly retryPolicy;
+    constructor(config: OperateLoopConfig);
+    /**
+     * Execute the operate loop for multi-turn conversations with tool calling.
+     */
+    execute(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): Promise<LlmOperateResponse>;
+    private initializeState;
+    private createContext;
+    private buildInitialRequest;
+    private executeOneTurn;
+    /**
+     * Sync the current input state from the updated provider request.
+     * This is necessary because appendToolResult modifies the provider-specific request,
+     * and we need to keep our state in sync.
+     */
+    private syncInputFromRequest;
+    /**
+     * Convert Gemini contents format to internal history format.
+     */
+    private convertGeminiContentsToHistory;
+    /**
+     * Append response items to the provider request.
+     * This adds all output items from a response (including reasoning, function_calls, etc.)
+     * to the request's input/messages array.
+     *
+     * This is critical for OpenAI which requires reasoning items to be present
+     * when function_call items reference them.
+     */
+    private appendResponseItemsToRequest;
+}
+/**
+ * Create an OperateLoop instance with the specified configuration.
+ */
+export declare function createOperateLoop(config: OperateLoopConfig): OperateLoop;

package/dist/esm/operate/adapters/AnthropicAdapter.d.ts

@@ -0,0 +1,32 @@
+import { Anthropic } from "@anthropic-ai/sdk";
+import { JsonObject, NaturalSchema } from "@jaypie/types";
+import { z } from "zod/v4";
+import { Toolkit } from "../../tools/Toolkit.class.js";
+import { LlmHistory, LlmOperateOptions, LlmUsageItem } from "../../types/LlmProvider.interface.js";
+import { ClassifiedError, OperateRequest, ParsedResponse, ProviderToolDefinition, StandardToolCall, StandardToolResult } from "../types.js";
+import { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
+/**
+ * AnthropicAdapter implements the ProviderAdapter interface for Anthropic's API.
+ * It handles request building, response parsing, and error classification
+ * specific to Anthropic's Messages API.
+ */
+export declare class AnthropicAdapter extends BaseProviderAdapter {
+    readonly name: "anthropic";
+    readonly defaultModel: "claude-opus-4-1";
+    buildRequest(request: OperateRequest): Anthropic.MessageCreateParams;
+    formatTools(toolkit: Toolkit, outputSchema?: JsonObject): ProviderToolDefinition[];
+    formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;
+    executeRequest(client: unknown, request: unknown): Promise<Anthropic.Message>;
+    parseResponse(response: unknown, _options?: LlmOperateOptions): ParsedResponse;
+    extractToolCalls(response: unknown): StandardToolCall[];
+    extractUsage(response: unknown, model: string): LlmUsageItem;
+    formatToolResult(toolCall: StandardToolCall, result: StandardToolResult): Anthropic.ToolResultBlockParam;
+    appendToolResult(request: unknown, toolCall: StandardToolCall, result: StandardToolResult): Anthropic.MessageCreateParams;
+    responseToHistoryItems(response: unknown): LlmHistory;
+    classifyError(error: unknown): ClassifiedError;
+    isComplete(response: unknown): boolean;
+    hasStructuredOutput(response: unknown): boolean;
+    extractStructuredOutput(response: unknown): JsonObject | undefined;
+    private extractContent;
+}
+export declare const anthropicAdapter: AnthropicAdapter;

package/dist/esm/operate/adapters/GeminiAdapter.d.ts

@@ -0,0 +1,37 @@
+import { JsonObject, NaturalSchema } from "@jaypie/types";
+import { z } from "zod/v4";
+import { Toolkit } from "../../tools/Toolkit.class.js";
+import { LlmHistory, LlmOperateOptions, LlmUsageItem } from "../../types/LlmProvider.interface.js";
+import { ClassifiedError, OperateRequest, ParsedResponse, ProviderToolDefinition, StandardToolCall, StandardToolResult } from "../types.js";
+import { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
+import { GeminiPart, GeminiRawResponse, GeminiRequest } from "../../providers/gemini/types.js";
+/**
+ * GeminiAdapter implements the ProviderAdapter interface for Google's Gemini API.
+ * It handles request building, response parsing, and error classification
+ * specific to Gemini's generateContent API.
+ */
+export declare class GeminiAdapter extends BaseProviderAdapter {
+    readonly name: "gemini";
+    readonly defaultModel: "gemini-2.5-flash";
+    buildRequest(request: OperateRequest): GeminiRequest;
+    formatTools(toolkit: Toolkit, outputSchema?: JsonObject): ProviderToolDefinition[];
+    formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;
+    executeRequest(client: unknown, request: unknown): Promise<GeminiRawResponse>;
+    parseResponse(response: unknown, options?: LlmOperateOptions): ParsedResponse;
+    extractToolCalls(response: unknown): StandardToolCall[];
+    extractUsage(response: unknown, model: string): LlmUsageItem;
+    formatToolResult(toolCall: StandardToolCall, result: StandardToolResult): GeminiPart;
+    appendToolResult(request: unknown, toolCall: StandardToolCall, result: StandardToolResult): GeminiRequest;
+    responseToHistoryItems(response: unknown): LlmHistory;
+    classifyError(error: unknown): ClassifiedError;
+    isComplete(response: unknown): boolean;
+    hasStructuredOutput(response: unknown): boolean;
+    extractStructuredOutput(response: unknown): JsonObject | undefined;
+    private convertMessagesToContents;
+    private mapRole;
+    private hasToolCalls;
+    private getFinishReason;
+    private extractContent;
+    private generateCallId;
+}
+export declare const geminiAdapter: GeminiAdapter;

package/dist/esm/operate/adapters/OpenAiAdapter.d.ts

@@ -0,0 +1,30 @@
+import { JsonObject, NaturalSchema } from "@jaypie/types";
+import { z } from "zod/v4";
+import { Toolkit } from "../../tools/Toolkit.class.js";
+import { LlmHistory, LlmOperateOptions, LlmToolResult, LlmUsageItem } from "../../types/LlmProvider.interface.js";
+import { ClassifiedError, OperateRequest, ParsedResponse, ProviderToolDefinition, StandardToolCall, StandardToolResult } from "../types.js";
+import { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
+/**
+ * OpenAiAdapter implements the ProviderAdapter interface for OpenAI's API.
+ * It handles request building, response parsing, and error classification
+ * specific to OpenAI's Responses API.
+ */
+export declare class OpenAiAdapter extends BaseProviderAdapter {
+    readonly name: "openai";
+    readonly defaultModel: "gpt-5";
+    buildRequest(request: OperateRequest): unknown;
+    formatTools(toolkit: Toolkit, _outputSchema?: JsonObject): ProviderToolDefinition[];
+    formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;
+    executeRequest(client: unknown, request: unknown): Promise<unknown>;
+    parseResponse(response: unknown, options?: LlmOperateOptions): ParsedResponse;
+    extractToolCalls(response: unknown): StandardToolCall[];
+    extractUsage(response: unknown, model: string): LlmUsageItem;
+    formatToolResult(toolCall: StandardToolCall, result: StandardToolResult): LlmToolResult;
+    appendToolResult(request: unknown, toolCall: StandardToolCall, result: StandardToolResult): unknown;
+    responseToHistoryItems(response: unknown): LlmHistory;
+    classifyError(error: unknown): ClassifiedError;
+    isComplete(response: unknown): boolean;
+    private hasToolCalls;
+    private extractContent;
+}
+export declare const openAiAdapter: OpenAiAdapter;

package/dist/esm/operate/adapters/ProviderAdapter.interface.d.ts

@@ -0,0 +1,177 @@
+import { JsonObject, NaturalSchema } from "@jaypie/types";
+import { z } from "zod/v4";
+import { LlmHistory, LlmOperateOptions, LlmUsageItem } from "../../types/LlmProvider.interface.js";
+import { Toolkit } from "../../tools/Toolkit.class.js";
+import { ClassifiedError, OperateRequest, ParsedResponse, ProviderToolDefinition, StandardToolCall, StandardToolResult } from "../types.js";
+/**
+ * ProviderAdapter defines the contract that each LLM provider must implement
+ * to work with the shared operate loop.
+ *
+ * The adapter pattern allows the core operate loop to be provider-agnostic
+ * while each provider handles its specific API format and quirks.
+ */
+export interface ProviderAdapter {
+    /**
+     * Unique identifier for this provider (e.g., "openai", "anthropic")
+     */
+    readonly name: string;
+    /**
+     * Default model for this provider
+     */
+    readonly defaultModel: string;
+    /**
+     * Build a provider-specific request from the standardized format
+     *
+     * @param request - Standardized request options
+     * @returns Provider-specific request object ready for the API
+     */
+    buildRequest(request: OperateRequest): unknown;
+    /**
+     * Convert a Toolkit to provider-specific tool definitions
+     *
+     * @param toolkit - The toolkit containing tool definitions
+     * @param outputSchema - Optional JSON schema for structured output
+     * @returns Array of provider-specific tool definitions
+     */
+    formatTools(toolkit: Toolkit, outputSchema?: JsonObject): ProviderToolDefinition[];
+    /**
+     * Format a structured output schema for the provider
+     *
+     * @param schema - JSON schema, NaturalSchema, or Zod schema for the expected output
+     * @returns Provider-specific format configuration
+     */
+    formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;
+    /**
+     * Execute an API request to the provider
+     *
+     * @param client - The provider's SDK client instance
+     * @param request - Provider-specific request object (from buildRequest)
+     * @returns Raw provider response
+     */
+    executeRequest(client: unknown, request: unknown): Promise<unknown>;
+    /**
+     * Parse a provider response into standardized format
+     *
+     * @param response - Raw provider response
+     * @param options - Original operate options (for context)
+     * @returns Parsed response with content, tool calls, usage, etc.
+     */
+    parseResponse(response: unknown, options?: LlmOperateOptions): ParsedResponse;
+    /**
+     * Extract tool calls from a provider response
+     *
+     * @param response - Raw provider response
+     * @returns Array of standardized tool calls
+     */
+    extractToolCalls(response: unknown): StandardToolCall[];
+    /**
+     * Extract usage information from a provider response
+     *
+     * @param response - Raw provider response
+     * @param model - The model used (for tracking)
+     * @returns Usage item with token counts
+     */
+    extractUsage(response: unknown, model: string): LlmUsageItem;
+    /**
+     * Format a tool result to append to the conversation
+     *
+     * @param toolCall - The original tool call
+     * @param result - The standardized tool result
+     * @returns Provider-specific message/item to add to history
+     */
+    formatToolResult(toolCall: StandardToolCall, result: StandardToolResult): unknown;
+    /**
+     * Append tool call and result to the request for the next turn
+     *
+     * @param request - Current provider request
+     * @param toolCall - The tool call that was made
+     * @param result - The result of the tool call
+     * @returns Updated request with tool result appended
+     */
+    appendToolResult(request: unknown, toolCall: StandardToolCall, result: StandardToolResult): unknown;
+    /**
+     * Convert provider response items to LlmHistory format for storage
+     *
+     * @param response - Raw provider response
+     * @returns History items to append
+     */
+    responseToHistoryItems(response: unknown): LlmHistory;
+    /**
+     * Classify an error for retry logic
+     *
+     * @param error - The error that occurred
+     * @returns Classified error with retry recommendation
+     */
+    classifyError(error: unknown): ClassifiedError;
+    /**
+     * Check if an error is retryable
+     *
+     * @param error - The error to check
+     * @returns True if the error can be retried
+     */
+    isRetryableError(error: unknown): boolean;
+    /**
+     * Check if an error is due to rate limiting
+     *
+     * @param error - The error to check
+     * @returns True if this is a rate limit error
+     */
+    isRateLimitError(error: unknown): boolean;
+    /**
+     * Check if a response indicates the model wants to stop (vs tool use)
+     *
+     * @param response - Raw provider response
+     * @returns True if the model has finished responding
+     */
+    isComplete(response: unknown): boolean;
+    /**
+     * Check if a response contains a structured output result
+     *
+     * @param response - Raw provider response
+     * @returns True if structured output was returned
+     */
+    hasStructuredOutput(response: unknown): boolean;
+    /**
+     * Extract structured output from a response
+     *
+     * @param response - Raw provider response
+     * @returns Parsed JSON object
+     */
+    extractStructuredOutput(response: unknown): JsonObject | undefined;
+}
+/**
+ * BaseProviderAdapter provides default implementations for common adapter methods.
+ * Providers can extend this class to reduce boilerplate.
+ */
+export declare abstract class BaseProviderAdapter implements ProviderAdapter {
+    abstract readonly name: string;
+    abstract readonly defaultModel: string;
+    abstract buildRequest(request: OperateRequest): unknown;
+    abstract formatTools(toolkit: Toolkit, outputSchema?: JsonObject): ProviderToolDefinition[];
+    abstract formatOutputSchema(schema: JsonObject | NaturalSchema | z.ZodType): JsonObject;
+    abstract executeRequest(client: unknown, request: unknown): Promise<unknown>;
+    abstract parseResponse(response: unknown, options?: LlmOperateOptions): ParsedResponse;
+    abstract extractToolCalls(response: unknown): StandardToolCall[];
+    abstract extractUsage(response: unknown, model: string): LlmUsageItem;
+    abstract formatToolResult(toolCall: StandardToolCall, result: StandardToolResult): unknown;
+    abstract appendToolResult(request: unknown, toolCall: StandardToolCall, result: StandardToolResult): unknown;
+    abstract responseToHistoryItems(response: unknown): LlmHistory;
+    abstract classifyError(error: unknown): ClassifiedError;
+    abstract isComplete(response: unknown): boolean;
+    /**
+     * Default implementation checks if error is retryable via classifyError
+     */
+    isRetryableError(error: unknown): boolean;
+    /**
+     * Default implementation checks error category via classifyError
+     */
+    isRateLimitError(error: unknown): boolean;
+    /**
+     * Default implementation returns false - override for providers with native structured output
+     */
+    hasStructuredOutput(_response: unknown): boolean;
+    /**
+     * Default implementation returns undefined - override for providers with native structured output
+     */
+    extractStructuredOutput(_response: unknown): JsonObject | undefined;
+}

package/dist/esm/operate/adapters/index.d.ts

@@ -0,0 +1,5 @@
+export { BaseProviderAdapter } from "./ProviderAdapter.interface.js";
+export type { ProviderAdapter } from "./ProviderAdapter.interface.js";
+export { AnthropicAdapter, anthropicAdapter } from "./AnthropicAdapter.js";
+export { GeminiAdapter, geminiAdapter } from "./GeminiAdapter.js";
+export { OpenAiAdapter, openAiAdapter } from "./OpenAiAdapter.js";

package/dist/esm/operate/hooks/HookRunner.d.ts

@@ -0,0 +1,78 @@
+import { JsonObject } from "@jaypie/types";
+import { LlmHistory, LlmInputMessage, LlmOperateOptions, LlmUsage } from "../../types/LlmProvider.interface.js";
+export interface BeforeModelRequestContext {
+    input: string | LlmHistory | LlmInputMessage;
+    options?: LlmOperateOptions;
+    providerRequest: unknown;
+}
+export interface AfterModelResponseContext {
+    content: string | JsonObject;
+    input: string | LlmHistory | LlmInputMessage;
+    options?: LlmOperateOptions;
+    providerRequest: unknown;
+    providerResponse: unknown;
+    usage: LlmUsage;
+}
+export interface BeforeToolContext {
+    args: string;
+    toolName: string;
+}
+export interface AfterToolContext {
+    args: string;
+    result: unknown;
+    toolName: string;
+}
+export interface ToolErrorContext {
+    args: string;
+    error: Error;
+    toolName: string;
+}
+export interface RetryableErrorContext {
+    error: unknown;
+    input: string | LlmHistory | LlmInputMessage;
+    options?: LlmOperateOptions;
+    providerRequest: unknown;
+}
+export interface UnrecoverableErrorContext {
+    error: unknown;
+    input: string | LlmHistory | LlmInputMessage;
+    options?: LlmOperateOptions;
+    providerRequest: unknown;
+}
+export type LlmHooks = LlmOperateOptions["hooks"];
+/**
+ * HookRunner provides a centralized, consistent way to execute lifecycle hooks
+ * during the LLM operate loop. It handles async resolution and provides error
+ * isolation for hook execution.
+ */
+export declare class HookRunner {
+    /**
+     * Execute the beforeEachModelRequest hook if defined
+     */
+    runBeforeModelRequest(hooks: LlmHooks, context: BeforeModelRequestContext): Promise<void>;
+    /**
+     * Execute the afterEachModelResponse hook if defined
+     */
+    runAfterModelResponse(hooks: LlmHooks, context: AfterModelResponseContext): Promise<void>;
+    /**
+     * Execute the beforeEachTool hook if defined
+     */
+    runBeforeTool(hooks: LlmHooks, context: BeforeToolContext): Promise<void>;
+    /**
+     * Execute the afterEachTool hook if defined
+     */
+    runAfterTool(hooks: LlmHooks, context: AfterToolContext): Promise<void>;
+    /**
+     * Execute the onToolError hook if defined
+     */
+    runOnToolError(hooks: LlmHooks, context: ToolErrorContext): Promise<void>;
+    /**
+     * Execute the onRetryableModelError hook if defined
+     */
+    runOnRetryableError(hooks: LlmHooks, context: RetryableErrorContext): Promise<void>;
+    /**
+     * Execute the onUnrecoverableModelError hook if defined
+     */
+    runOnUnrecoverableError(hooks: LlmHooks, context: UnrecoverableErrorContext): Promise<void>;
+}
+export declare const hookRunner: HookRunner;

package/dist/esm/operate/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { HookRunner, hookRunner } from "./HookRunner.js";
+export type { AfterModelResponseContext, AfterToolContext, BeforeModelRequestContext, BeforeToolContext, LlmHooks, RetryableErrorContext, ToolErrorContext, UnrecoverableErrorContext, } from "./HookRunner.js";

package/dist/esm/operate/index.d.ts

@@ -0,0 +1,14 @@
+export { AnthropicAdapter, anthropicAdapter, BaseProviderAdapter, GeminiAdapter, geminiAdapter, OpenAiAdapter, openAiAdapter, } from "./adapters/index.js";
+export type { ProviderAdapter } from "./adapters/index.js";
+export { createOperateLoop, OperateLoop } from "./OperateLoop.js";
+export type { OperateLoopConfig } from "./OperateLoop.js";
+export { HookRunner, hookRunner } from "./hooks/index.js";
+export type { AfterModelResponseContext, AfterToolContext, BeforeModelRequestContext, BeforeToolContext, LlmHooks, RetryableErrorContext, ToolErrorContext, UnrecoverableErrorContext, } from "./hooks/index.js";
+export { InputProcessor, inputProcessor } from "./input/index.js";
+export type { ProcessedInput } from "./input/index.js";
+export { createResponseBuilder, ResponseBuilder } from "./response/index.js";
+export type { LlmError, ResponseBuilderConfig } from "./response/index.js";
+export { DEFAULT_BACKOFF_FACTOR, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_MAX_RETRIES, defaultRetryPolicy, MAX_RETRIES_ABSOLUTE_LIMIT, RetryExecutor, RetryPolicy, } from "./retry/index.js";
+export type { ErrorClassifier, ExecuteOptions, RetryContext, RetryExecutorConfig, RetryPolicyConfig, } from "./retry/index.js";
+export { ErrorCategory, LlmMessageType } from "./types.js";
+export type { ClassifiedError, OperateContext, OperateLoopState, OperateRequest, ParsedResponse, ProviderToolDefinition, StandardToolCall, StandardToolResult, } from "./types.js";

package/dist/esm/operate/input/InputProcessor.d.ts

@@ -0,0 +1,40 @@
+import { LlmHistory, LlmInputMessage, LlmOperateOptions } from "../../types/LlmProvider.interface.js";
+export interface ProcessedInput {
+    /** The processed history with all messages formatted */
+    history: LlmHistory;
+    /** Processed instructions with placeholders applied */
+    instructions?: string;
+    /** Processed system prompt with placeholders applied */
+    system?: string;
+}
+/**
+ * InputProcessor handles input normalization, placeholder substitution,
+ * and history merging for the operate loop.
+ */
+export declare class InputProcessor {
+    /**
+     * Process input with placeholders, history merging, and system message handling
+     *
+     * @param input - The raw input (string, message, or history)
+     * @param options - The operate options containing data, history, system, etc.
+     * @returns Processed input with all transformations applied
+     */
+    process(input: string | LlmHistory | LlmInputMessage, options?: LlmOperateOptions): ProcessedInput;
+    /**
+     * Format input and apply placeholders if data is provided
+     */
+    private formatInputWithPlaceholders;
+    /**
+     * Process instructions with placeholder substitution
+     */
+    private processInstructions;
+    /**
+     * Process system prompt with placeholder substitution
+     */
+    private processSystem;
+    /**
+     * Prepend system message to history, handling duplicates
+     */
+    private prependSystemMessage;
+}
+export declare const inputProcessor: InputProcessor;

package/dist/esm/operate/input/index.d.ts

@@ -0,0 +1,2 @@
+export { InputProcessor, inputProcessor } from "./InputProcessor.js";
+export type { ProcessedInput } from "./InputProcessor.js";

package/dist/esm/operate/response/ResponseBuilder.d.ts

@@ -0,0 +1,89 @@
+import { JsonObject, JsonReturn } from "@jaypie/types";
+import { LlmHistory, LlmOperateResponse, LlmResponseStatus, LlmUsage, LlmUsageItem } from "../../types/LlmProvider.interface.js";
+type LlmOutput = LlmOperateResponse["output"];
+export interface ResponseBuilderConfig {
+    model: string;
+    provider: string;
+}
+export interface LlmError {
+    detail?: string;
+    status: number | string;
+    title: string;
+}
+/**
+ * ResponseBuilder provides a fluent API for constructing LlmOperateResponse objects.
+ * It standardizes response construction across providers.
+ */
+export declare class ResponseBuilder {
+    private response;
+    constructor(config: ResponseBuilderConfig);
+    /**
+     * Set the response content
+     */
+    setContent(content: string | JsonObject | undefined): this;
+    /**
+     * Set the response status
+     */
+    setStatus(status: LlmResponseStatus): this;
+    /**
+     * Set an error on the response
+     */
+    setError(error: LlmError): this;
+    /**
+     * Set the history
+     */
+    setHistory(history: LlmHistory): this;
+    /**
+     * Append items to the history
+     */
+    appendToHistory(...items: LlmHistory): this;
+    /**
+     * Set the output
+     */
+    setOutput(output: LlmOutput): this;
+    /**
+     * Append items to the output
+     */
+    appendToOutput(...items: LlmOutput): this;
+    /**
+     * Add a raw provider response
+     */
+    addResponse(response: JsonReturn): this;
+    /**
+     * Add a usage entry for a single API call
+     */
+    addUsage(usage: LlmUsageItem): this;
+    /**
+     * Set the entire usage array
+     */
+    setUsage(usage: LlmUsage): this;
+    /**
+     * Get the current usage array for modifications
+     */
+    getUsage(): LlmUsage;
+    /**
+     * Get the current history for modifications
+     */
+    getHistory(): LlmHistory;
+    /**
+     * Get the current output for modifications
+     */
+    getOutput(): LlmOutput;
+    /**
+     * Mark response as completed
+     */
+    complete(): this;
+    /**
+     * Mark response as incomplete (e.g., max turns exceeded)
+     */
+    incomplete(): this;
+    /**
+     * Build and return the final response object
+     */
+    build(): LlmOperateResponse;
+}
+/**
+ * Factory function to create a new ResponseBuilder
+ */
+export declare function createResponseBuilder(config: ResponseBuilderConfig): ResponseBuilder;
+export {};

package/dist/esm/operate/response/index.d.ts

@@ -0,0 +1,2 @@
+export { createResponseBuilder, ResponseBuilder } from "./ResponseBuilder.js";
+export type { LlmError, ResponseBuilderConfig } from "./ResponseBuilder.js";

package/dist/esm/operate/retry/RetryExecutor.d.ts

@@ -0,0 +1,39 @@
+import { HookRunner, LlmHooks } from "../hooks/HookRunner.js";
+import { RetryPolicy } from "./RetryPolicy.js";
+export interface RetryContext {
+    input: unknown;
+    options?: unknown;
+    providerRequest: unknown;
+}
+export interface ErrorClassifier {
+    isRetryable(error: unknown): boolean;
+    isKnownError(error: unknown): boolean;
+}
+export interface RetryExecutorConfig {
+    errorClassifier: ErrorClassifier;
+    hookRunner?: HookRunner;
+    policy?: RetryPolicy;
+}
+export interface ExecuteOptions {
+    context: RetryContext;
+    hooks?: LlmHooks;
+}
+/**
+ * RetryExecutor handles the retry loop logic for LLM API calls.
+ * It provides exponential backoff, error classification, and hook execution.
+ */
+export declare class RetryExecutor {
+    private readonly policy;
+    private readonly hookRunner;
+    private readonly errorClassifier;
+    constructor(config: RetryExecutorConfig);
+    /**
+     * Execute an operation with retry logic
+     *
+     * @param operation - The async operation to execute
+     * @param options - Execution options including context and hooks
+     * @returns The result of the operation
+     * @throws BadGatewayError if all retries are exhausted or error is not retryable
+     */
+    execute<T>(operation: () => Promise<T>, options: ExecuteOptions): Promise<T>;
+}

package/dist/esm/operate/retry/RetryPolicy.d.ts

@@ -0,0 +1,35 @@
+export declare const DEFAULT_INITIAL_DELAY_MS = 1000;
+export declare const DEFAULT_MAX_DELAY_MS = 32000;
+export declare const DEFAULT_BACKOFF_FACTOR = 2;
+export declare const DEFAULT_MAX_RETRIES = 6;
+export declare const MAX_RETRIES_ABSOLUTE_LIMIT = 72;
+export interface RetryPolicyConfig {
+    /** Initial delay in milliseconds before first retry. Default: 1000 */
+    initialDelayMs?: number;
+    /** Maximum delay in milliseconds between retries. Default: 32000 */
+    maxDelayMs?: number;
+    /** Backoff multiplier for exponential backoff. Default: 2 */
+    backoffFactor?: number;
+    /** Maximum number of retries. Default: 6 */
+    maxRetries?: number;
+}
+/**
+ * RetryPolicy encapsulates retry configuration and delay calculation
+ * for the operate loop's retry logic.
+ */
+export declare class RetryPolicy {
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    readonly backoffFactor: number;
+    readonly maxRetries: number;
+    constructor(config?: RetryPolicyConfig);
+    /**
+     * Calculate the delay for a given attempt number (0-indexed)
+     */
+    getDelayForAttempt(attempt: number): number;
+    /**
+     * Check if another retry should be attempted
+     */
+    shouldRetry(currentAttempt: number): boolean;
+}
+export declare const defaultRetryPolicy: RetryPolicy;

package/dist/esm/operate/retry/index.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_BACKOFF_FACTOR, DEFAULT_INITIAL_DELAY_MS, DEFAULT_MAX_DELAY_MS, DEFAULT_MAX_RETRIES, defaultRetryPolicy, MAX_RETRIES_ABSOLUTE_LIMIT, RetryPolicy, } from "./RetryPolicy.js";
+export type { RetryPolicyConfig } from "./RetryPolicy.js";
+export { RetryExecutor } from "./RetryExecutor.js";
+export type { ErrorClassifier, ExecuteOptions, RetryContext, RetryExecutorConfig, } from "./RetryExecutor.js";