@reactive-agents/llm-provider 0.7.8 → 0.9.0

package/dist/index.d.ts

@@ -3,6 +3,27 @@ import * as effect_Cause from 'effect/Cause';
 import * as effect_Types from 'effect/Types';
 import * as effect_Duration from 'effect/Duration';
 
+/**
+ * ProviderCapabilities — static capability declaration for each LLM provider.
+ *
+ * These are coarse-grained, model-agnostic flags that reflect what the
+ * provider's API reliably supports. They let the framework choose between
+ * native function calling and structured-output fallback paths without
+ * querying the provider at runtime.
+ */
+interface ProviderCapabilities {
+    /** Provider supports native function / tool calling (structured tool_use). */
+    readonly supportsToolCalling: boolean;
+    /** Provider supports streaming completions. */
+    readonly supportsStreaming: boolean;
+    /** Provider supports structured / JSON output modes natively. */
+    readonly supportsStructuredOutput: boolean;
+    /** Provider can return per-token log probabilities. */
+    readonly supportsLogprobs: boolean;
+}
+/** Safe defaults — assumes minimal capabilities for unknown providers. */
+declare const DEFAULT_CAPABILITIES: ProviderCapabilities;
+
 /**
  * Schema for LLM provider selection.
  * Supported providers: anthropic, openai, ollama, gemini, litellm, custom.
@@ -482,6 +503,8 @@ type LLMMessage = {
     readonly role: "tool";
     /** Tool call ID this result corresponds to */
     readonly toolCallId: string;
+    /** Name of the tool that produced this result */
+    readonly toolName?: string;
     /** Plain text result/output */
     readonly content: string;
 };
@@ -499,6 +522,10 @@ type LLMMessage = {
  * };
  * ```
  */
+/**
+ * Schema for token usage statistics from an LLM response.
+ * Used for cost tracking, budget enforcement, and observability.
+ */
 declare const TokenUsageSchema: Schema.Struct<{
     /** Tokens consumed by the input (messages + system prompt) */
     inputTokens: typeof Schema.Number;
@@ -590,6 +617,30 @@ declare const ToolCallSchema: Schema.Struct<{
  * When the model decides to call a tool, this describes which tool and with what inputs.
  */
 type ToolCall = Schema.Schema.Type<typeof ToolCallSchema>;
+/**
+ * Log probability information for a single token.
+ * Returned by providers that support logprobs (OpenAI, Ollama).
+ *
+ * @example
+ * ```typescript
+ * const logprob: TokenLogprob = {
+ *   token: "Paris",
+ *   logprob: -0.0234,
+ *   topLogprobs: [
+ *     { token: "Paris", logprob: -0.0234 },
+ *     { token: "London", logprob: -3.89 },
+ *   ]
+ * };
+ * ```
+ */
+type TokenLogprob = {
+    readonly token: string;
+    readonly logprob: number;
+    readonly topLogprobs?: readonly {
+        token: string;
+        logprob: number;
+    }[];
+};
 /**
  * Request to the LLM for a completion.
  * Includes messages, model configuration, tool definitions, and sampling parameters.
@@ -630,6 +681,10 @@ type CompletionRequest = {
     readonly tools?: readonly ToolDefinition[];
     /** System prompt (optional, prepended to user messages) */
     readonly systemPrompt?: string;
+    /** Request log probabilities for each output token (optional) */
+    readonly logprobs?: boolean;
+    /** Number of most likely tokens to return log probabilities for (optional, 1-20) */
+    readonly topLogprobs?: number;
 };
 /**
  * Schema for LLM response.
@@ -675,6 +730,15 @@ declare const CompletionResponseSchema: Schema.Struct<{
     }>>>;
     /** Internal reasoning from thinking models (e.g. <think> blocks from qwen3, DeepSeek-R1) */
     thinking: Schema.optional<typeof Schema.String>;
+    /** Token-level log probabilities (when requested via logprobs in CompletionRequest) */
+    logprobs: Schema.optional<Schema.Array$<Schema.Struct<{
+        token: typeof Schema.String;
+        logprob: typeof Schema.Number;
+        topLogprobs: Schema.optional<Schema.Array$<Schema.Struct<{
+            token: typeof Schema.String;
+            logprob: typeof Schema.Number;
+        }>>>;
+    }>>>;
 }>;
 /**
  * LLM response to a completion request.
@@ -729,6 +793,11 @@ type StreamEvent = {
     readonly type: "usage";
     /** Final token usage for the request */
     readonly usage: TokenUsage;
+} | {
+    /** Token-level log probabilities (accumulated over the full response) */
+    readonly type: "logprobs";
+    /** Per-token logprob data */
+    readonly logprobs: readonly TokenLogprob[];
 } | {
     /** Error occurred during streaming */
     readonly type: "error";
@@ -923,8 +992,21 @@ declare const LLMService_base: Context.TagClass<LLMService, "LLMService", {
     /**
      * Report structured output capabilities for this provider.
      * Used by the structured output pipeline to select optimal JSON extraction strategy.
+     *
+     * @deprecated Superseded by `capabilities()`. This method is retained for backward
+     * compatibility. New code should use `capabilities()` and read
+     * `supportsStructuredOutput` from `ProviderCapabilities`.
      */
     readonly getStructuredOutputCapabilities: () => Effect.Effect<StructuredOutputCapabilities, never>;
+    /**
+     * Declare the provider's runtime capabilities.
+     * Returns a static, pure value — no API calls are made.
+     *
+     * Subsumes `getStructuredOutputCapabilities()`. Use this method for all
+     * new provider-capability checks (tool calling, streaming, structured output,
+     * logprobs).
+     */
+    readonly capabilities: () => Effect.Effect<ProviderCapabilities, never>;
 }>;
 /**
  * Core LLM service — all LLM interactions go through this.
@@ -1054,6 +1136,22 @@ declare const LLMConfig_base: Context.TagClass<LLMConfig, "LLMConfig", {
      * ```
      */
     readonly observabilityVerbosity: ObservabilityVerbosity;
+    /**
+     * Custom pricing registry for calculating token costs.
+     * Maps model identifiers to input/output token costs per 1 million tokens.
+     * Overrides built-in framework pricing if an exact match is found.
+     *
+     * @example
+     * ```typescript
+     * pricingRegistry: {
+     *   "my-fine-tuned-model": { input: 0.5, output: 1.5 }
+     * }
+     * ```
+     */
+    readonly pricingRegistry?: Record<string, {
+        readonly input: number;
+        readonly output: number;
+    }>;
 }>;
 /**
  * LLM service configuration.
@@ -1226,6 +1324,22 @@ declare const llmConfigFromEnv: {
      * ```
      */
     readonly observabilityVerbosity: ObservabilityVerbosity;
+    /**
+     * Custom pricing registry for calculating token costs.
+     * Maps model identifiers to input/output token costs per 1 million tokens.
+     * Overrides built-in framework pricing if an exact match is found.
+     *
+     * @example
+     * ```typescript
+     * pricingRegistry: {
+     *   "my-fine-tuned-model": { input: 0.5, output: 1.5 }
+     * }
+     * ```
+     */
+    readonly pricingRegistry?: Record<string, {
+        readonly input: number;
+        readonly output: number;
+    }>;
 };
 /**
  * Effect-TS Layer that provides LLMConfig from environment variables.
@@ -1286,23 +1400,49 @@ declare const GeminiProviderLive: Layer.Layer<LLMService, never, LLMConfig>;
 
 declare const LiteLLMProviderLive: Layer.Layer<LLMService, never, LLMConfig>;
 
+interface ToolCallSpec {
+    name: string;
+    args: Record<string, unknown>;
+    id?: string;
+}
+type TestTurn = {
+    text: string;
+    match?: string;
+} | {
+    json: unknown;
+    match?: string;
+} | {
+    toolCall: ToolCallSpec;
+    match?: string;
+} | {
+    toolCalls: ToolCallSpec[];
+    match?: string;
+} | {
+    error: string;
+    match?: string;
+};
 /**
- * Create a deterministic test LLM service.
- * Returns responses based on pattern matching against prompt content.
+ * Create a deterministic test LLM service using a scenario of sequential turns.
+ *
+ * Turns are consumed in order. Each LLM call scans forward from the current
+ * position for the first matching turn (or unconditional turn). The last turn
+ * repeats when the scenario is exhausted, so single-turn tests need no special
+ * handling.
  *
  * Usage:
  * ```ts
- * const layer = TestLLMServiceLayer({
- *   "capital of France": "Paris",
- *   "plan": '{"goal":"test","steps":[]}',
- * });
+ * const layer = TestLLMServiceLayer([
+ *   { toolCall: { name: "web-search", args: { query: "AI news" } } },
+ *   { text: "Here is the summary..." },
+ * ]);
  * ```
  */
-declare const TestLLMService: (responses: Record<string, string>) => typeof LLMService.Service;
+declare const TestLLMService: (scenario: TestTurn[]) => typeof LLMService.Service;
 /**
- * Create a test Layer for LLMService with optional pattern-matched responses.
+ * Create a test Layer for LLMService with a deterministic turn scenario.
+ * Turns are consumed sequentially; the last turn repeats when exhausted.
  */
-declare const TestLLMServiceLayer: (responses?: Record<string, string>) => Layer.Layer<LLMService, never, never>;
+declare const TestLLMServiceLayer: (scenario?: TestTurn[]) => Layer.Layer<LLMService, never, never>;
 
 /**
  * Estimate token count for messages.
@@ -1310,10 +1450,44 @@ declare const TestLLMServiceLayer: (responses?: Record<string, string>) => Layer
  * This is used as a fallback when the provider's token counting API is unavailable.
  */
 declare const estimateTokenCount: (messages: readonly LLMMessage[]) => Effect.Effect<number, never>;
+/**
+ * Provider-specific caching discount information.
+ * Each provider handles cached tokens differently:
+ * - Anthropic: cache_read = 0.1× base, cache_write = 1.25× base
+ * - OpenAI: cached = 0.5× base (automatic for >1024 token prompts)
+ * - Gemini: cached = ~0.25× base (context caching)
+ */
+interface CacheUsage {
+    /** Tokens read from Anthropic prompt cache (billed at 10% of base input price) */
+    readonly cache_read_input_tokens?: number;
+    /** Tokens written to Anthropic prompt cache (billed at 125% of base input price) */
+    readonly cache_creation_input_tokens?: number;
+    /** Tokens served from OpenAI's automatic prompt cache (billed at 50% of base input price) */
+    readonly cached_tokens?: number;
+    /** Tokens served from Gemini context cache (billed at ~25% of base input price) */
+    readonly cached_content_token_count?: number;
+}
 /**
  * Calculate cost in USD given token counts and model name.
- */
-declare const calculateCost: (inputTokens: number, outputTokens: number, model: string) => number;
+ * Supports provider-specific caching discounts:
+ * - Anthropic: prompt caching (10% read cost, 125% write cost)
+ * - OpenAI: automatic caching (50% cost for cached tokens)
+ * - Gemini: context caching (~25% cost for cached tokens)
+ *
+ * @param inputTokens - Total input tokens from provider response
+ * @param outputTokens - Total output tokens from provider response
+ * @param model - Model identifier for pricing lookup
+ * @param usage - Provider-specific cache token breakdown
+ * @param registry - Custom pricing overrides
+ * @param pricing - Direct per-1M pricing (e.g. from LiteLLM proxy)
+ */
+declare const calculateCost: (inputTokens: number, outputTokens: number, model: string, usage?: CacheUsage, registry?: Record<string, {
+    input: number;
+    output: number;
+}>, pricing?: {
+    input?: number;
+    output?: number;
+}) => number;
 
 /**
  * Retry policy for LLM calls.
@@ -1328,6 +1502,44 @@ type CircuitBreakerConfig = {
 };
 declare const defaultCircuitBreakerConfig: CircuitBreakerConfig;
 
+/**
+ * Token costs per 1 million tokens in USD.
+ */
+interface ModelPricing {
+    readonly input: number;
+    readonly output: number;
+}
+/**
+ * Normalized interface for dynamic LLM pricing providers.
+ * Implement this interface to fetch live pricing from APIs or custom sources.
+ */
+interface PricingProvider {
+    /**
+     * Fetch and return a pricing registry for all available models.
+     * Maps model identifiers (e.g. "gpt-4o", "anthropic/claude-3-opus") to their USD cost per 1M tokens.
+     */
+    fetchPricing(): Effect.Effect<Record<string, ModelPricing>, Error, never>;
+}
+/**
+ * OpenRouter Pricing Provider.
+ * Fetches the latest live pricing for all 100+ models available on OpenRouter.
+ * OpenRouter model IDs look like: "openai/gpt-4o", "meta-llama/llama-3-70b-instruct"
+ */
+declare const openRouterPricingProvider: PricingProvider;
+/**
+ * Custom URL Pricing Provider.
+ * Fetches pricing from a custom HTTP endpoint (like a GitHub Gist) that returns a JSON record.
+ *
+ * @example
+ * ```json
+ * {
+ *   "my-fine-tuned-model": { "input": 0.5, "output": 1.5 },
+ *   "another-model": { "input": 2.0, "output": 4.0 }
+ * }
+ * ```
+ */
+declare const urlPricingProvider: (url: string) => PricingProvider;
+
 /**
  * Schema for ReAct action parsing.
  */
@@ -1422,11 +1634,14 @@ declare function getProviderDefaultModel(provider: string): string | undefined;
  * Create the LLM provider layer for a specific provider.
  * Uses env vars for configuration by default.
  */
-declare const createLLMProviderLayer: (provider?: "anthropic" | "openai" | "ollama" | "gemini" | "litellm" | "test", testResponses?: Record<string, string>, model?: string, modelParams?: {
+declare const createLLMProviderLayer: (provider?: "anthropic" | "openai" | "ollama" | "gemini" | "litellm" | "test", testScenario?: TestTurn[], model?: string, modelParams?: {
     thinking?: boolean;
     temperature?: number;
     maxTokens?: number;
-}, circuitBreaker?: Partial<CircuitBreakerConfig>) => Layer.Layer<LLMService | PromptManager, never, never>;
+}, circuitBreaker?: Partial<CircuitBreakerConfig>, pricingRegistry?: Record<string, {
+    readonly input: number;
+    readonly output: number;
+}>) => Layer.Layer<LLMService | PromptManager, never, never>;
 /**
  * LLM layer with custom config (for programmatic use).
  */
@@ -1476,4 +1691,320 @@ interface CircuitBreaker {
  */
 declare const makeCircuitBreaker: (config?: Partial<CircuitBreakerConfig>) => CircuitBreaker;
 
-export { AnthropicProviderLive, type CacheControl, CacheControlSchema, type CacheableContentBlock, type CircuitBreaker, type CircuitBreakerConfig, type CompletionRequest, type CompletionResponse, CompletionResponseSchema, type ComplexityAnalysis, ComplexityAnalysisSchema, type ContentBlock, DefaultEmbeddingConfig, type EmbeddingCache, type EmbeddingConfig, EmbeddingConfigSchema, GeminiProviderLive, ImageContentBlockSchema, type ImageSource, ImageSourceSchema, LLMConfig, LLMConfigFromEnv, LLMContextOverflowError, LLMError, type LLMErrors, type LLMMessage, LLMParseError, type LLMProvider, LLMProviderType, LLMRateLimitError, LLMService, LLMTimeoutError, LiteLLMProviderLive, LocalProviderLive, type ModelConfig, ModelConfigSchema, type ModelPresetName, ModelPresets, OpenAIProviderLive, PROVIDER_DEFAULT_MODELS, type Plan, PlanSchema, PromptManager, PromptManagerLive, type ReActAction, ReActActionSchema, type Reflection, ReflectionSchema, type StopReason, StopReasonSchema, type StrategySelection, StrategySelectionSchema, type StreamEvent, type StructuredCompletionRequest, type StructuredOutputCapabilities, TestLLMService, TestLLMServiceLayer, TextContentBlockSchema, type ThoughtEvaluation, ThoughtEvaluationSchema, type TokenUsage, TokenUsageSchema, type ToolCall, ToolCallSchema, type ToolDefinition, ToolDefinitionSchema, ToolResultContentBlockSchema, ToolUseContentBlockSchema, type TruncationStrategy, calculateCost, createLLMProviderLayer, createLLMProviderLayerWithConfig, defaultCircuitBreakerConfig, estimateTokenCount, getProviderDefaultModel, llmConfigFromEnv, makeCacheable, makeCircuitBreaker, makeEmbeddingCache, retryPolicy };
+/**
+ * Rate Limiter — throttles LLM requests BEFORE they hit the API to prevent
+ * 429 errors. Uses a sliding window algorithm for both request-per-minute
+ * and token-per-minute limits, plus a concurrency semaphore.
+ */
+
+/**
+ * Configuration for the rate limiter.
+ *
+ * @example
+ * ```typescript
+ * const config: RateLimiterConfig = {
+ *   requestsPerMinute: 60,
+ *   tokensPerMinute: 100_000,
+ *   maxConcurrent: 10,
+ * };
+ * ```
+ */
+interface RateLimiterConfig {
+    /** Maximum requests per minute (sliding window). Default: 60 */
+    readonly requestsPerMinute?: number;
+    /** Maximum estimated input tokens per minute (sliding window). Default: 100,000 */
+    readonly tokensPerMinute?: number;
+    /** Maximum concurrent in-flight requests. Default: 10 */
+    readonly maxConcurrent?: number;
+}
+interface RateLimiter {
+    /**
+     * Acquire a rate limiter slot. Returns an Effect that resolves when a slot
+     * is available. If the limit is hit, the Effect will delay until the oldest
+     * entry in the sliding window expires.
+     *
+     * @param messages - Optional messages to estimate token count for token-based limiting.
+     *                   When omitted, only request-count and concurrency limits apply.
+     */
+    readonly acquire: (messages?: readonly LLMMessage[]) => Effect.Effect<void, never>;
+    /**
+     * Signal that a request has completed (decrements concurrent count).
+     * Must be called after every `acquire()` once the request finishes.
+     */
+    readonly release: () => void;
+    /**
+     * Current number of in-flight requests.
+     */
+    readonly concurrentCount: () => number;
+    /**
+     * Number of requests recorded in the current sliding window.
+     */
+    readonly windowRequestCount: () => number;
+    /**
+     * Number of estimated tokens recorded in the current sliding window.
+     */
+    readonly windowTokenCount: () => number;
+}
+/**
+ * Create a rate limiter with configurable thresholds.
+ *
+ * Uses a sliding window algorithm: timestamps of recent requests are stored
+ * in an array. On `acquire()`, expired entries (older than 60s) are pruned.
+ * If the remaining count >= limit, the caller waits until the oldest entry
+ * would expire from the window.
+ *
+ * @example
+ * ```typescript
+ * const limiter = makeRateLimiter({ requestsPerMinute: 30 });
+ * // In an Effect pipeline:
+ * yield* limiter.acquire(messages);
+ * try {
+ *   yield* llm.complete(request);
+ * } finally {
+ *   limiter.release();
+ * }
+ * ```
+ */
+declare const makeRateLimiter: (config?: RateLimiterConfig) => RateLimiter;
+
+/**
+ * Rate-Limited Provider — wraps an existing LLMService with rate limiting.
+ *
+ * Intercepts `complete()`, `stream()`, and `completeStructured()` calls,
+ * acquiring a rate limiter slot before each request and releasing it afterward.
+ * Passthrough for `embed()`, `countTokens()`, `getModelConfig()`, and
+ * `getStructuredOutputCapabilities()`.
+ */
+
+/**
+ * Create a Layer that wraps the existing LLMService with rate limiting.
+ *
+ * The returned layer depends on an upstream LLMService (i.e., it must be
+ * `.pipe(Layer.provide(baseLlmLayer))` to resolve the dependency).
+ *
+ * @example
+ * ```typescript
+ * const rateLimitedLlm = makeRateLimitedProvider({ requestsPerMinute: 30 })
+ *   .pipe(Layer.provide(AnthropicProviderLive));
+ * ```
+ */
+declare const makeRateLimitedProvider: (config?: RateLimiterConfig) => Layer.Layer<LLMService, never, LLMService>;
+
+/**
+ * Configuration for the FallbackChain graceful degradation strategy.
+ *
+ * Specifies ordered lists of fallback providers and models, along with
+ * the error threshold that triggers switching to the next provider.
+ *
+ * @example
+ * ```typescript
+ * const config: FallbackConfig = {
+ *   providers: ["anthropic", "openai", "gemini"],
+ *   models: ["claude-sonnet-4-20250514", "claude-haiku-3-20250520"],
+ *   errorThreshold: 3,
+ * };
+ * ```
+ */
+interface FallbackConfig {
+    /** Ordered list of provider names to try in sequence. */
+    readonly providers: string[];
+    /** Ordered list of model names to try within the same provider. */
+    readonly models?: string[];
+    /** Consecutive errors on a provider before switching to next. Default: 3 */
+    readonly errorThreshold?: number;
+}
+/**
+ * FallbackChain manages graceful degradation when LLM providers or models fail.
+ *
+ * Tracks consecutive errors per provider and automatically switches to the next
+ * provider when the error threshold is exceeded. On rate limits (429), falls back
+ * to a cheaper model within the same provider.
+ *
+ * Use case: Deploy with Anthropic as primary, OpenAI as secondary, Gemini as
+ * fallback. If Claude API goes down, automatically route to GPT. If quota exceeded,
+ * switch from claude-sonnet to claude-haiku to reduce cost/load.
+ *
+ * @example
+ * ```typescript
+ * const chain = new FallbackChain({
+ *   providers: ["anthropic", "openai"],
+ *   models: ["claude-sonnet-4-20250514", "claude-haiku-3-20250520"],
+ *   errorThreshold: 3,
+ * });
+ *
+ * // Record errors
+ * chain.recordError("anthropic");
+ * chain.recordError("anthropic");
+ * chain.recordError("anthropic"); // threshold met, switch to openai
+ *
+ * console.log(chain.currentProvider()); // "openai"
+ *
+ * // Record rate limit, fall back to cheaper model
+ * chain.recordRateLimit("openai");
+ * console.log(chain.currentModel()); // "claude-haiku-3-20250520"
+ *
+ * // Successful call resets error count
+ * chain.recordSuccess("openai");
+ *
+ * // Check if more fallbacks available
+ * if (!chain.hasFallback()) {
+ *   console.log("All providers exhausted!");
+ * }
+ * ```
+ */
+declare class FallbackChain {
+    private readonly config;
+    /** Error count per provider. */
+    private readonly errorCounts;
+    /** Current index in the providers list. */
+    private currentProviderIndex;
+    /** Current index in the models list. */
+    private currentModelIndex;
+    /** Threshold for switching to next provider. */
+    private readonly threshold;
+    constructor(config: FallbackConfig);
+    /**
+     * Record an error for the given provider.
+     * Increments the error count and switches to the next provider if threshold is met.
+     *
+     * @param provider - Provider name that errored
+     */
+    recordError(provider: string): void;
+    /**
+     * Record a rate limit error (429) for the given provider.
+     * Falls back to the next model in the chain.
+     *
+     * @param _provider - Provider name that was rate limited (parameter name _ to indicate unused)
+     */
+    recordRateLimit(_provider: string): void;
+    /**
+     * Record a successful call for the given provider.
+     * Resets the error count for that provider.
+     *
+     * @param provider - Provider name that succeeded
+     */
+    recordSuccess(provider: string): void;
+    /**
+     * Get the currently active provider.
+     *
+     * @returns Name of the provider to use
+     */
+    currentProvider(): string;
+    /**
+     * Get the currently active model.
+     * Returns undefined if no models are configured.
+     *
+     * @returns Name of the model to use, or undefined if no models configured
+     */
+    currentModel(): string | undefined;
+    /**
+     * Check if there are more fallbacks available (provider or model).
+     *
+     * @returns true if there are unused fallback providers or models, false if all exhausted
+     */
+    hasFallback(): boolean;
+}
+
+/**
+ * Validates and auto-repairs a message array before sending to any LLM provider.
+ * Silent — logs warnings in debug mode, never throws.
+ */
+declare function validateAndRepairMessages(messages: readonly LLMMessage[]): readonly LLMMessage[];
+
+/**
+ * Provider Behavior Adapters — lightweight hooks that compensate for
+ * model-specific behavior differences without polluting the core kernel.
+ *
+ * The kernel calls adapter methods at well-defined hook points.
+ * Frontier models return undefined (no intervention needed).
+ * Local/mid models return explicit guidance to improve task completion rates.
+ *
+ * Hook call sites in react-kernel.ts:
+ *   systemPromptPatch  — once, when building the static system prompt
+ *   taskFraming        — once, wrapping the initial user task message
+ *   toolGuidance       — once, appended to system prompt after tool schema block
+ *   continuationHint   — each iteration, injected as user message after tool results
+ *   errorRecovery      — when a tool returns a failed result
+ *   synthesisPrompt    — when transitioning from research → produce phase
+ *   qualityCheck       — optional self-eval prompt injected before final answer
+ */
+interface ProviderAdapter {
+    /**
+     * Patch the system prompt for model-specific needs.
+     * Called once when building the system prompt.
+     */
+    systemPromptPatch?(basePrompt: string, tier: string): string | undefined;
+    /**
+     * Wrap or annotate the initial task message.
+     * Called once when the first user message is constructed.
+     * Return undefined to use the task as-is.
+     */
+    taskFraming?(context: {
+        task: string;
+        requiredTools: readonly string[];
+        tier: string;
+    }): string | undefined;
+    /**
+     * Append inline tool usage guidance after the tool schema block in the system prompt.
+     * Helps local models that ignore JSON schema descriptions.
+     * Return undefined to add nothing.
+     */
+    toolGuidance?(context: {
+        toolNames: readonly string[];
+        requiredTools: readonly string[];
+        tier: string;
+    }): string | undefined;
+    /**
+     * Generate a continuation hint injected as a user message after tool results.
+     * Called each iteration when required tools are still pending.
+     */
+    continuationHint?(context: {
+        toolsUsed: ReadonlySet<string>;
+        requiredTools: readonly string[];
+        missingTools: readonly string[];
+        iteration: number;
+        maxIterations: number;
+        lastToolName?: string;
+        lastToolResultPreview?: string;
+    }): string | undefined;
+    /**
+     * Generate recovery guidance when a tool call fails or returns an error.
+     * Called after a failed tool execution. Return undefined to skip.
+     */
+    errorRecovery?(context: {
+        toolName: string;
+        errorContent: string;
+        missingTools: readonly string[];
+        tier: string;
+    }): string | undefined;
+    /**
+     * Generate a synthesis prompt injected when the model has gathered enough data
+     * and needs to transition to producing the output.
+     * Called when all research tools are satisfied and only output tools remain.
+     * Return undefined to skip.
+     */
+    synthesisPrompt?(context: {
+        toolsUsed: ReadonlySet<string>;
+        missingOutputTools: readonly string[];
+        observationCount: number;
+        tier: string;
+    }): string | undefined;
+    /**
+     * Generate a self-evaluation prompt injected just before the model declares
+     * a final answer. Return undefined to skip the quality check.
+     */
+    qualityCheck?(context: {
+        task: string;
+        requiredTools: readonly string[];
+        toolsUsed: ReadonlySet<string>;
+        tier: string;
+    }): string | undefined;
+}
+declare const defaultAdapter: ProviderAdapter;
+declare const localModelAdapter: ProviderAdapter;
+declare function selectAdapter(_capabilities: {
+    supportsToolCalling: boolean;
+}, tier?: string): ProviderAdapter;
+declare function recommendStrategyForTier(_tier: string | undefined, _configuredStrategy: string, _requiredTools?: readonly string[]): string | undefined;
+
+export { AnthropicProviderLive, type CacheControl, CacheControlSchema, type CacheUsage, type CacheableContentBlock, type CircuitBreaker, type CircuitBreakerConfig, type CompletionRequest, type CompletionResponse, CompletionResponseSchema, type ComplexityAnalysis, ComplexityAnalysisSchema, type ContentBlock, DEFAULT_CAPABILITIES, DefaultEmbeddingConfig, type EmbeddingCache, type EmbeddingConfig, EmbeddingConfigSchema, FallbackChain, type FallbackConfig, GeminiProviderLive, ImageContentBlockSchema, type ImageSource, ImageSourceSchema, LLMConfig, LLMConfigFromEnv, LLMContextOverflowError, LLMError, type LLMErrors, type LLMMessage, LLMParseError, type LLMProvider, LLMProviderType, LLMRateLimitError, LLMService, LLMTimeoutError, LiteLLMProviderLive, LocalProviderLive, type ModelConfig, ModelConfigSchema, type ModelPresetName, ModelPresets, type ModelPricing, OpenAIProviderLive, PROVIDER_DEFAULT_MODELS, type Plan, PlanSchema, type PricingProvider, PromptManager, PromptManagerLive, type ProviderAdapter, type ProviderCapabilities, type RateLimiter, type RateLimiterConfig, type ReActAction, ReActActionSchema, type Reflection, ReflectionSchema, type StopReason, StopReasonSchema, type StrategySelection, StrategySelectionSchema, type StreamEvent, type StructuredCompletionRequest, type StructuredOutputCapabilities, TestLLMService, TestLLMServiceLayer, type TestTurn, TextContentBlockSchema, type ThoughtEvaluation, ThoughtEvaluationSchema, type TokenLogprob, type TokenUsage, TokenUsageSchema, type ToolCall, ToolCallSchema, type ToolCallSpec, type ToolDefinition, ToolDefinitionSchema, ToolResultContentBlockSchema, ToolUseContentBlockSchema, type TruncationStrategy, calculateCost, createLLMProviderLayer, createLLMProviderLayerWithConfig, defaultAdapter, defaultCircuitBreakerConfig, estimateTokenCount, getProviderDefaultModel, llmConfigFromEnv, localModelAdapter, makeCacheable, makeCircuitBreaker, makeEmbeddingCache, makeRateLimitedProvider, makeRateLimiter, openRouterPricingProvider, recommendStrategyForTier, retryPolicy, selectAdapter, urlPricingProvider, validateAndRepairMessages };