@hiper2d/ai-agents 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1191 @@
+import { z } from 'zod';
+
+/**
+ * Core types shared by every agent and consumer app.
+ */
+declare const MESSAGE_ROLE: {
+    readonly SYSTEM: "system";
+    readonly USER: "user";
+    readonly ASSISTANT: "assistant";
+};
+interface AIMessage {
+    role: 'system' | 'user' | 'assistant' | 'developer';
+    content: string;
+    thinking?: string;
+    anthropicThinkingSignature?: string;
+    googleThoughtSignature?: string;
+    grokEncryptedReasoning?: string;
+}
+interface TokenUsage$1 {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUSD: number;
+    reasoningTokens?: number;
+    cachedInputTokens?: number;
+    durationMs?: number;
+}
+interface ApiKeyMap {
+    [id: string]: string;
+}
+interface AgentLoggingConfig {
+    enabled: boolean;
+    logSystemPrompt: boolean;
+    history: {
+        enabled: boolean;
+        maxCharactersPerMessage: number;
+    };
+    logCommand: boolean;
+    reply: {
+        mode: 'raw' | 'body-only';
+        maxReplyChars: number;
+        maxThinkingChars: number;
+        includeReasoning: boolean;
+        includeUsage: boolean;
+    };
+}
+interface LoggingConfig {
+    agents: AgentLoggingConfig;
+}
+declare const DEFAULT_LOGGING_CONFIG: LoggingConfig;
+declare class BotResponseError extends Error {
+    details: string;
+    context: Record<string, any>;
+    recoverable: boolean;
+    /**
+     * Model-facing explanation of the rejection, set where the failure is detected and carried
+     * through to the consumer's error surface. Used to enrich a user-triggered retry prompt.
+     */
+    explanation?: string;
+    constructor(message: string, details?: string, context?: Record<string, any>, recoverable?: boolean, explanation?: string);
+}
+
+/**
+ * Injectable logging seam. The library logs agent activity through this interface;
+ * consumers with a real logging pipeline (BetterStack, Datadog, …) plug it in via
+ * `setLlmLogger` once at startup. The default implementation logs to the console.
+ */
+interface AgentActivityData {
+    gameId?: string;
+    userId?: string;
+    systemPrompt?: string;
+    history?: AIMessage[];
+    command?: string;
+    reply?: any;
+    thinking?: string;
+    usage?: TokenUsage$1;
+}
+interface LlmLogger {
+    debug(message: string, args?: any): void;
+    info(message: string, args?: any): void;
+    warn(message: string, args?: any): void;
+    error(message: string, args?: any): void;
+    agentActivity(agentName: string, model: string, activity: string, data: AgentActivityData, customConfig?: AgentLoggingConfig): void;
+}
+/** Replace the library's logger. Call once at app startup, before agents are created. */
+declare function setLlmLogger(replacement: LlmLogger): void;
+/** Stable facade the library logs through; delegates to whatever setLlmLogger installed. */
+declare const logger: LlmLogger;
+
+/**
+ * Sentinel that splits a system prompt into cache tiers: [shared static tier, per-agent tier].
+ * AbstractAgent splits the instruction on it; providers with explicit cache breakpoints
+ * (Anthropic) place one per part, everyone else relies on implicit prefix caching over the
+ * joined, marker-free instruction. Consumers embed it between the stable and variable parts
+ * of their system prompts.
+ */
+declare const CACHE_TIER_MARKER = "\n<<<CACHE_TIER_BREAK>>>\n";
+
+/** Strips a wrapping markdown code fence (```json … ``` or ``` … ```) from a model response. */
+declare function cleanResponse(response: string): string;
+/**
+ * Stable non-cryptographic hex hash (FNV-1a, 64-bit as two 32-bit lanes).
+ * For derived identifiers — provider cache keys, conversation routing ids —
+ * where the only requirement is determinism. Pure JS on purpose: node:crypto
+ * would drag a node builtin into browser bundles of this library (the werewolf
+ * design kit bundles the catalog, and esbuild must resolve every import in the
+ * graph even for code that later tree-shakes away).
+ */
+declare function stableHashHex(input: string): string;
+
+/**
+ * Validates and parses a response using a Zod schema
+ * @param schema - The Zod schema to validate against
+ * @param data - The data to validate
+ * @returns Parsed and validated data
+ * @throws ZodError if validation fails
+ */
+declare function validateResponse<T>(schema: z.ZodSchema<T>, data: unknown): T;
+/**
+ * Safely validates a response, returning validation result
+ * @param schema - The Zod schema to validate against
+ * @param data - The data to validate
+ * @returns Success/error result object
+ */
+declare function safeValidateResponse<T>(schema: z.ZodSchema<T>, data: unknown): z.SafeParseReturnType<unknown, T>;
+
+type ProviderType = 'openai' | 'anthropic' | 'google' | 'mistral' | 'deepseek' | 'grok' | 'kimi';
+interface JsonSchemaOptions {
+    strict?: boolean;
+    includeDescription?: boolean;
+    additionalProperties?: boolean;
+}
+interface ProviderSchema {
+    type: 'json_schema' | 'prompt_description' | 'google_schema';
+    content: any;
+}
+/**
+ * Universal schema converter that transforms Zod schemas to provider-specific formats
+ */
+declare class ZodSchemaConverter {
+    /**
+     * Convert Zod schema to OpenAI-compatible JSON Schema
+     */
+    static toOpenAIJsonSchema(zodSchema: z.ZodSchema, schemaName: string): any;
+    /**
+     * Convert Zod schema to Google Gemini responseSchema format
+     * This follows the official Gemini structured output format
+     */
+    static toGoogleSchema(zodSchema: z.ZodSchema): any;
+    /**
+     * Internal method to convert Zod types to Google schema format
+     */
+    private static convertZodToGoogleType;
+    /**
+     * Convert Zod schema to standard JSON Schema format
+     * Public method for external use (e.g., Grok structured outputs)
+     */
+    static toJsonSchema(zodSchema: z.ZodSchema, options?: JsonSchemaOptions): any;
+    /**
+     * Convert Zod schema to Mistral/DeepSeek JSON Schema format
+     */
+    static toMistralSchema(zodSchema: z.ZodSchema): any;
+    /**
+     * Convert Zod schema to human-readable prompt description for Anthropic
+     */
+    static toPromptDescription(zodSchema: z.ZodSchema): string;
+    /**
+     * Get provider-specific schema format
+     */
+    static forProvider(zodSchema: z.ZodSchema, provider: ProviderType, schemaName?: string): ProviderSchema;
+    /**
+     * Core Zod to JSON Schema conversion
+     */
+    private static zodToJsonSchema;
+    /**
+     * Convert individual Zod types to JSON Schema format
+     */
+    private static convertZodType;
+    /**
+     * Recursively add additionalProperties: false to all object types for strict validation
+     */
+    private static makeSchemaStrict;
+    /**
+     * Build human-readable schema description for prompt-based providers
+     */
+    private static buildSchemaDescription;
+    /**
+     * Get type description for schema properties
+     */
+    private static getTypeDescription;
+    /**
+     * Build inline object description without leading indentation
+     */
+    private static buildInlineObjectDescription;
+}
+/**
+ * Helper function to generate schema instructions for any provider
+ */
+declare function generateSchemaInstructions(zodSchema: z.ZodSchema, provider: ProviderType, schemaName?: string): string;
+/**
+ * Validate that a provider supports native JSON Schema
+ */
+declare function supportsNativeJsonSchema(provider: ProviderType): boolean;
+/**
+ * Check if a provider needs prompt-based schema descriptions
+ */
+declare function needsPromptBasedSchema(provider: ProviderType): boolean;
+
+/**
+ * Extract the first balanced JSON object embedded in `text`.
+ * String- and escape-aware, so braces inside string values don't break the scan.
+ * If the first candidate fails to parse, scanning continues from the next '{'.
+ * Returns null when no parseable object is found.
+ */
+declare function extractFirstJsonObject(text: string): unknown | null;
+/**
+ * Lenient parse + Zod validation of an LLM text reply, shared by all agents.
+ *
+ * Order of attempts:
+ * 1. Strict JSON parse of the fence-stripped reply (plus a quote-unwrapped
+ *    variant for Gemini's quoted-JSON-string quirk).
+ * 2. Extraction of the first balanced JSON object embedded in prose
+ *    (rescues "Sure, here is my answer: {...}" replies).
+ * 3. Re-bracing replies that look like an object body missing its outer braces
+ *    (rescues MiniMax-M3's `"who": "...", "why": "..."` replies).
+ * 4. Wrapping raw prose as `{ reply: ... }` for BotAnswer-shaped schemas
+ *    (rescues bots that "speak in character" instead of returning JSON).
+ *
+ * Throws with the same message prefixes the agents have always used
+ * ("Failed to parse JSON response:", "Response validation failed:") so log
+ * queries and error handling stay stable.
+ */
+declare function parseAndValidateLlmJson<T>(rawReply: string, zodSchema: z.ZodSchema<T>, log?: (message: string) => void): T;
+
+/**
+ * Custom error classes for AI agent interactions
+ */
+declare abstract class ModelError extends Error {
+    modelType: string;
+    constructor(message: string, modelType: string);
+}
+declare class ModelOverloadError extends ModelError {
+    retryable: boolean;
+    constructor(message: string, modelType: string, retryable?: boolean);
+}
+declare class ModelRateLimitError extends ModelError {
+    retryAfter?: number;
+    constructor(message: string, modelType: string, retryAfter?: number);
+}
+declare class ModelUnavailableError extends ModelError {
+    reason: string;
+    constructor(message: string, modelType: string, reason?: string);
+}
+declare class ModelAuthenticationError extends ModelError {
+    constructor(message: string, modelType: string);
+}
+declare class ModelQuotaExceededError extends ModelError {
+    constructor(message: string, modelType: string);
+}
+/**
+ * The model declined to answer: Anthropic returns `stop_reason: "refusal"` with no content
+ * blocks when its safety layer rejects the request as a whole. Not retryable as-is — the
+ * same prompt will refuse again — the caller has to change the prompt or the model.
+ * Observed 2026-08-30 on Claude Fable 5: a persona system prompt plus a narrated multi-turn
+ * history that ends by asking the character what it does refuses, while either half alone
+ * answers; Sonnet 5 and Opus 4.8 answer the same requests.
+ */
+declare class ModelRefusalError extends ModelError {
+    constructor(modelType: string, message?: string);
+}
+
+/**
+ * Defense against chain-of-thought leaking into visible chat messages.
+ *
+ * The OpenAI-compatible reasoning providers (DeepSeek, GLM, Kimi, Qwen,
+ * MiniMax, Fugu) are all documented to return thinking in a separate field
+ * (`reasoning_content` / `reasoning_details`), but models occasionally
+ * misbehave and inline a `<think>…</think>` block into `message.content`
+ * instead — observed live with qwen-plus (2026-08), and MiniMax documents it
+ * as the default without `reasoning_split`. If that text reaches the lenient
+ * JSON parser, its wrap-as-reply fallback can surface the ENTIRE chain of
+ * thought — secret role included — as the bot's visible message.
+ *
+ * Every agent that reads `choices[0].message.content` must pass it through
+ * here before parsing, and merge the returned `thinking` into its thinking
+ * output so nothing is silently dropped.
+ */
+declare function stripInlineThinking(raw: string): {
+    text: string;
+    thinking: string;
+};
+/** Joins provider-reported reasoning with any inline thinking salvaged from content. */
+declare function mergeThinking(...parts: Array<string | undefined | null>): string;
+
+/**
+ * Model catalog and pricing.
+ *
+ * This is the library's single source of truth for how to talk to each supported model —
+ * API name, key name, thinking dialect, per-model tuning defaults (temperature, reasoning
+ * effort, thinking budgets, output ceilings) — and what each model costs. Tuning values are
+ * operational defaults discovered against the live APIs; consumers can adjust them per model
+ * via `createCatalog(overrides)`, but anything that would ever be fixed for *correctness*
+ * (a model rejecting a parameter, an effort level eating the output budget) belongs here,
+ * so every consumer inherits the fix with a version bump.
+ *
+ * App-level policy — tier limits, deprecated-id migration, markup — deliberately lives in
+ * the consumer, keyed by the same stable model ids.
+ */
+declare const API_KEY_CONSTANTS: {
+    readonly OPENAI: "OPENAI_API_KEY";
+    readonly ANTHROPIC: "ANTHROPIC_API_KEY";
+    readonly GOOGLE: "GOOGLE_API_KEY";
+    readonly MISTRAL: "MISTRAL_API_KEY";
+    readonly DEEPSEEK: "DEEPSEEK_API_KEY";
+    readonly GROK: "GROK_API_KEY";
+    readonly MOONSHOT: "MOONSHOT_API_KEY";
+    readonly Z_AI: "Z_AI_API_KEY";
+    readonly FUGU: "FUGU_API_KEY";
+    readonly QWEN: "QWEN_API_KEY";
+    readonly MINIMAX: "MINIMAX_API_KEY";
+};
+declare const SupportedAiKeyNames: Record<string, string>;
+declare const LLM_CONSTANTS: {
+    CLAUDE_FABLE: string;
+    CLAUDE_OPUS: string;
+    CLAUDE_SONNET: string;
+    CLAUDE_HAIKU: string;
+    DEEPSEEK_FLASH: string;
+    DEEPSEEK_PRO: string;
+    GPT_SOL: string;
+    GPT: string;
+    GPT_MINI: string;
+    GEMINI_PRO: string;
+    GEMINI_FLASH: string;
+    GEMINI_LITE: string;
+    MISTRAL_LARGE: string;
+    MISTRAL_MEDIUM: string;
+    MISTRAL_SMALL: string;
+    MISTRAL_MAGISTRAL: string;
+    GROK: string;
+    KIMI: string;
+    GLM: string;
+    GLM_FLASH: string;
+    FUGU_ULTRA: string;
+    QWEN_MAX: string;
+    QWEN_FLASH: string;
+    MINIMAX: string;
+};
+/**
+ * Per-request output ceiling for ordinary requests. Reasoning tokens are billed inside this
+ * budget on every provider, so the cap has to clear thinking AND the answer — set below what
+ * a request really emits and the *answer* is what gets truncated, producing malformed JSON
+ * rather than a cheaper request.
+ *
+ * NOTE this is a blast-radius cap, not a cost lever: providers bill tokens generated, never
+ * the unused ceiling. Lowering it saves nothing on a well-behaved request — it only bounds a
+ * runaway one. Reasoning effort and thinking budgets are the knobs that change spend.
+ */
+declare const DEFAULT_MAX_OUTPUT_TOKENS = 8192;
+type ModelTag = 'very-fast' | 'fast' | 'slow' | 'very-slow' | 'extremely-slow' | 'cheap' | 'expensive';
+type ReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * What a catalog entry produces. Only text agents exist today; TTS, STT and image
+ * generation are planned as subpath exports, and their catalog entries will carry the
+ * matching modality so consumers can filter (a text-model picker must not list a voice).
+ * Omitted means 'text'.
+ */
+type Modality = 'text' | 'tts' | 'stt' | 'image';
+interface ModelConfig {
+    displayName: string;
+    modelApiName: string;
+    apiKeyName: string;
+    modality?: Modality;
+    hasThinking: boolean;
+    temperature?: number;
+    reasoningEffort?: ReasoningEffort;
+    thinkingBudgetTokens?: number;
+    maxOutputTokens?: number;
+    tags?: ModelTag[];
+}
+declare const SupportedAiModels: Record<string, ModelConfig>;
+type LLMModel = keyof typeof SupportedAiModels;
+/**
+ * Builds a catalog from the library defaults with per-model partial overrides merged on top.
+ * The merge is per-model and shallow: `{ glm: { temperature: 0.9 } }` changes only that field
+ * and keeps the rest of the default entry. Ids absent from the defaults are added verbatim
+ * (they must then be complete ModelConfig entries).
+ */
+declare function createCatalog(overrides?: Record<string, Partial<ModelConfig>>): Record<string, ModelConfig>;
+declare function getModelTags(modelId: string): ModelTag[];
+declare function modelHasTag(modelId: string, tag: ModelTag): boolean;
+/** Speed is an ordered scale — "fast" filters must also admit very-fast models. */
+declare function modelIsFast(modelId: string): boolean;
+declare function getModelDisplayName(modelId: string): string;
+/** Human-readable provider name ("Anthropic", "Grok", …) for a model id, if known. */
+declare function getModelProviderName(modelId: string): string | undefined;
+/**
+ * Looks up a model's config by API name. Since the catalog went thinking-only (2026-08-05) each
+ * modelApiName has a single entry, so hasThinking no longer disambiguates anything; it is kept
+ * for call-site compatibility and as a filter should variants ever return.
+ */
+declare function getModelConfigByApiName(modelApiName: string, hasThinking?: boolean): ModelConfig | undefined;
+/**
+ * Model pricing configuration
+ * All prices are in USD per 1,000,000 tokens
+ */
+/**
+ * What a price is quoted per. Text models bill per million tokens; the planned TTS entries
+ * bill per million characters, STT per minute of audio, image models per image (or per
+ * output token, in which case they stay 'tokens'). Omitted means 'tokens'.
+ */
+type PricingUnit = 'tokens' | 'characters' | 'minutes' | 'images';
+interface ModelPricing {
+    unit?: PricingUnit;
+    inputPrice: number;
+    outputPrice: number;
+    cacheHitPrice?: number;
+    extendedContextInputPrice?: number;
+    extendedContextOutputPrice?: number;
+    extendedContextCacheHitPrice?: number;
+    extendedContextThresholdTokens?: number;
+    peakPricing?: PeakPricing;
+}
+/**
+ * Time-of-day surcharge applied to all billing items (input, output, cache) when the
+ * request falls inside one of the UTC windows.
+ */
+interface PeakPricing {
+    multiplier: number;
+    windowsUtc: Array<[number, number]>;
+    /** When set, the windows apply Monday–Friday only: a request that falls on a Saturday or
+     *  Sunday in the provider's local timezone (given as a UTC offset in hours) bills at the
+     *  base rate all day. */
+    weekendOffPeak?: {
+        utcOffsetHours: number;
+    };
+}
+/** True if the timestamp's UTC time-of-day falls inside any [startHour, endHour) window. */
+declare function isInPeakWindow(timestampMs: number, windowsUtc: Array<[number, number]>): boolean;
+/** True if the timestamp falls on a Saturday or Sunday in the timezone at the given UTC offset. */
+declare function isWeekendAt(timestampMs: number, utcOffsetHours: number): boolean;
+/** True if a request at this timestamp bills at the peak multiplier under the schedule. */
+declare function isPeakBilling(timestampMs: number, peak: PeakPricing): boolean;
+/** DeepSeek's peak-valley schedule: 2× during Beijing 09:00–12:00 and 14:00–18:00
+ *  (UTC 1–4, 6–10), Monday–Friday Beijing time only. */
+declare const DEEPSEEK_PEAK_SCHEDULE: PeakPricing;
+/**
+ * Centralized pricing configuration for all AI models
+ * All prices are per million (1,000,000) tokens
+ */
+declare const MODEL_PRICING: Record<string, ModelPricing>;
+/** True for hybrid thinking-only models — the ones whose effective output price is a known
+ *  multiple of the sticker price. Always-on reasoning models (GPT-5, Gemini, Grok, Kimi,
+ *  Fable, Magistral) also burn reasoning tokens, but their multiplier hasn't been measured. */
+declare function isHybridThinkingModel(modelApiName: string): boolean;
+interface CostCalculationOptions {
+    cacheHitTokens?: number;
+    contextTokens?: number;
+    totalTokens?: number;
+    timestamp?: number;
+}
+/**
+ * Helper function to calculate cost based on model pricing
+ * @param modelApiName - The API name of the model
+ * @param inputTokens - Number of input tokens
+ * @param outputTokens - Number of output tokens
+ * @param options - Additional calculation details (cache hits, context tokens, etc.)
+ * @returns Cost in USD
+ */
+declare function calculateModelCost(modelApiName: string, inputTokens: number, outputTokens: number, options?: CostCalculationOptions): number;
+/**
+ * Returns provider-specific signature fields based on the model's API name prefix.
+ * Used when storing messages with thinking signatures from different providers.
+ * @param aiType - The model API name (e.g. "claude-sonnet-5", "gemini-3.7-flash")
+ * @param signature - The thinking signature from the API response (may be undefined)
+ * @returns Object with appropriate signature fields for the message
+ */
+declare function getProviderSignatureFields(aiType: string, signature?: string): {
+    anthropicThinkingSignature?: string;
+    googleThoughtSignature?: string;
+    grokEncryptedReasoning?: string;
+};
+
+/**
+ * Per-provider reasoning-effort vocabularies.
+ *
+ * `ReasoningEffort` (catalog.ts) is the union of every provider's scale so a catalog entry or
+ * a per-call override can name any level; each provider accepts only its own slice and most
+ * reject the rest with a 400. The `to<Provider>Effort` helpers clamp a generic level to the
+ * nearest one the provider takes, so a consumer can say "high" for every model and let the
+ * agent translate. Nearest is by rank on the shared scale; a tie resolves upward (asking for
+ * "medium" from a provider with only low|high gets high — never less reasoning than asked).
+ *
+ * Verified against provider docs 2026-08-30:
+ * - OpenAI GPT-5.x: minimal|low|medium|high|xhigh
+ * - Anthropic adaptive thinking (Fable 5 / Opus 4.8 / Sonnet 5): low|medium|high|xhigh|max
+ * - Gemini 3.x thinkingLevel: minimal|low|medium|high (3.1 Pro and 3.7 Flash reject minimal)
+ * - Z.AI GLM-5.3 / 5.3-Flash: low|high|max only
+ * - DeepSeek V4: low|high|max (the API itself aliases medium → high)
+ * - Sakana Fugu: high|xhigh
+ * Qwen accepts reasoning_effort but ignores it (thinking_budget is its knob); MiniMax, Kimi,
+ * Grok and Mistral expose no effort parameter.
+ */
+type OpenAIReasoningEffort = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+type AnthropicReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+type GeminiReasoningEffort = 'minimal' | 'low' | 'medium' | 'high';
+type GlmReasoningEffort = 'low' | 'high' | 'max';
+type DeepSeekReasoningEffort = 'low' | 'high' | 'max';
+type FuguReasoningEffort = 'high' | 'xhigh';
+/** The shared scale, lowest first. */
+declare const REASONING_EFFORT_SCALE: readonly ReasoningEffort[];
+declare const OPENAI_REASONING_EFFORTS: readonly OpenAIReasoningEffort[];
+declare const ANTHROPIC_REASONING_EFFORTS: readonly AnthropicReasoningEffort[];
+declare const GEMINI_REASONING_EFFORTS: readonly GeminiReasoningEffort[];
+declare const GLM_REASONING_EFFORTS: readonly GlmReasoningEffort[];
+declare const DEEPSEEK_REASONING_EFFORTS: readonly DeepSeekReasoningEffort[];
+declare const FUGU_REASONING_EFFORTS: readonly FuguReasoningEffort[];
+/** Clamps `effort` to the nearest level in `allowed` (by rank on the shared scale, ties go up). */
+declare function clampReasoningEffort<T extends ReasoningEffort>(effort: ReasoningEffort, allowed: readonly T[]): T;
+declare const toOpenAIEffort: (effort: ReasoningEffort) => OpenAIReasoningEffort;
+declare const toAnthropicEffort: (effort: ReasoningEffort) => AnthropicReasoningEffort;
+declare const toGeminiEffort: (effort: ReasoningEffort) => GeminiReasoningEffort;
+declare const toGlmEffort: (effort: ReasoningEffort) => GlmReasoningEffort;
+declare const toDeepSeekEffort: (effort: ReasoningEffort) => DeepSeekReasoningEffort;
+declare const toFuguEffort: (effort: ReasoningEffort) => FuguReasoningEffort;
+
+/**
+ * Unified token usage utilities for all AI providers
+ * This module provides a consistent interface for token usage extraction and cost calculation
+ * across all supported AI providers (OpenAI, DeepSeek, Kimi, Grok, Anthropic, Google, Mistral)
+ */
+
+/**
+ * Generic token usage interface that covers all provider-specific fields
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheHitTokens?: number;
+    cacheMissTokens?: number;
+    reasoningTokens?: number;
+}
+/**
+ * Extract token usage from any AI provider's API response
+ * This function handles the common response formats used by different providers
+ * @param response - The raw API response from any provider
+ * @returns TokenUsage object with extracted values or null if extraction fails
+ */
+declare function extractTokenUsage(response: any): TokenUsage | null;
+/**
+ * Calculate cost for any AI provider using the centralized pricing
+ * @param modelApiName - The API name of the model (e.g., 'gpt-5.5', 'deepseek-v4-flash')
+ * @param inputTokens - Number of input tokens used
+ * @param outputTokens - Number of output tokens used
+ * @param options - Additional calculation details (cache hits, context tokens, etc.)
+ * @returns Cost in USD
+ */
+declare function calculateCost(modelApiName: string, inputTokens: number, outputTokens: number, options?: CostCalculationOptions): number;
+/**
+ * Extract token usage and calculate cost in one operation
+ * @param modelApiName - The API name of the model
+ * @param response - The raw API response from any provider
+ * @returns Object with token usage and calculated cost, or null if extraction fails
+ */
+declare function extractUsageAndCalculateCost(modelApiName: string, response: any): {
+    usage: TokenUsage;
+    cost: number;
+} | null;
+/**
+ * DeepSeek-specific token usage extraction
+ * Handles DeepSeek's specific cache and reasoning token fields
+ */
+declare function extractDeepSeekTokenUsage(response: any): TokenUsage | null;
+/**
+ * OpenAI-specific token usage extraction
+ * Handles OpenAI's cache tokens and reasoning tokens (for o1 models)
+ */
+declare function extractOpenAITokenUsage(response: any): TokenUsage | null;
+/**
+ * Kimi-specific token usage extraction
+ * Kimi uses OpenAI-compatible format
+ */
+declare function extractKimiTokenUsage(response: any): TokenUsage | null;
+/**
+ * Grok-specific token usage extraction
+ * Grok uses OpenAI-compatible format
+ */
+declare function extractGrokTokenUsage(response: any): TokenUsage | null;
+/**
+ * Anthropic-specific token usage extraction
+ * Anthropic may have different response format
+ */
+declare function extractAnthropicTokenUsage(response: any): TokenUsage | null;
+/**
+ * Google-specific token usage extraction
+ * Google may have different response format
+ */
+declare function extractGoogleTokenUsage(response: any): TokenUsage | null;
+/**
+ * Mistral-specific token usage extraction
+ * Mistral SDK uses camelCase (promptTokens, completionTokens, totalTokens)
+ * and reasoning tokens may be in additionalProperties for Magistral models
+ */
+declare function extractMistralTokenUsage(response: any): TokenUsage | null;
+
+/**
+ * OpenAI pricing utilities
+ * Re-exports unified utilities with OpenAI-specific naming for backward compatibility
+ */
+/**
+ * Calculate the cost for token usage based on OpenAI pricing
+ * @param model - The OpenAI model name
+ * @param inputTokens - Number of input tokens used
+ * @param outputTokens - Number of output tokens used
+ * @param cacheHitTokens - Number of cached input tokens (optional)
+ * @returns Cost in USD
+ */
+declare function calculateOpenAICost(model: string, inputTokens: number, outputTokens: number, cacheHitTokens?: number): number;
+/**
+ * Extract token usage from OpenAI API response
+ * @param response - The raw response from OpenAI API
+ * @returns Token usage object with extracted values
+ */
+interface OpenAITokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheHitTokens?: number;
+    reasoningTokens?: number;
+}
+declare function extractTokenUsageFromResponse$6(response: any): OpenAITokenUsage | null;
+
+/**
+ * DeepSeek pricing utilities
+ * Re-exports unified utilities with DeepSeek-specific naming for backward compatibility
+ */
+/**
+ * Calculate the cost for token usage based on DeepSeek pricing
+ * @param model - The DeepSeek model name
+ * @param inputTokens - Number of input tokens used
+ * @param outputTokens - Number of output tokens used
+ * @param cacheHitTokens - Number of cached input tokens (optional)
+ * @returns Cost in USD
+ */
+declare function calculateDeepSeekCost(model: string, inputTokens: number, outputTokens: number, cacheHitTokens?: number): number;
+/**
+ * Extract token usage from DeepSeek API response
+ * @param response - The raw response from DeepSeek API
+ * @returns TokenUsage object with extracted values
+ */
+interface DeepSeekTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheHitTokens?: number;
+    cacheMissTokens?: number;
+    reasoningTokens?: number;
+}
+declare function extractTokenUsageFromResponse$5(response: any): DeepSeekTokenUsage | null;
+
+/**
+ * Kimi (Moonshot AI) pricing utilities
+ * Re-exports unified utilities with Kimi-specific naming for backward compatibility
+ */
+/**
+ * Calculate the cost for token usage based on Kimi pricing
+ * @param model - The Kimi model name
+ * @param inputTokens - Number of input tokens used
+ * @param outputTokens - Number of output tokens used
+ * @returns Cost in USD
+ */
+declare function calculateKimiCost(model: string, inputTokens: number, outputTokens: number): number;
+/**
+ * Extract token usage from Kimi API response
+ * Since Kimi uses OpenAI-compatible format, the response structure should be similar
+ * @param response - The raw response from Kimi API
+ * @returns Token usage object with extracted values
+ */
+interface KimiTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+declare function extractTokenUsageFromResponse$4(response: any): KimiTokenUsage | null;
+
+/**
+ * Grok (xAI) pricing utilities
+ * Re-exports unified utilities with Grok-specific naming for backward compatibility
+ */
+/**
+ * Calculate the cost for token usage based on Grok pricing
+ * @param model - The Grok model name
+ * @param inputTokens - Number of input tokens used (prompt_tokens)
+ * @param outputTokens - Number of output tokens used (completion_tokens, includes reasoning_tokens)
+ * @param cacheHitTokens - Number of cached input tokens (optional, when supported)
+ * @returns Cost in USD
+ */
+declare function calculateGrokCost(model: string, inputTokens: number, outputTokens: number, cacheHitTokens?: number): number;
+/**
+ * Extract token usage from Grok API response
+ * @param response - The raw response from Grok API
+ * @returns Token usage object with extracted values
+ */
+interface GrokTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheHitTokens?: number;
+    reasoningTokens?: number;
+}
+declare function extractTokenUsageFromResponse$3(response: any): GrokTokenUsage | null;
+
+/**
+ * Anthropic pricing utilities
+ * Re-exports unified utilities with Anthropic-specific naming for consistency
+ */
+/**
+ * Calculate the cost for token usage based on Anthropic pricing
+ * @param model - The Anthropic model name
+ * @param inputTokens - Number of input tokens used
+ * @param outputTokens - Number of output tokens used
+ * @param cacheHitTokens - Number of cached input tokens (optional, when supported)
+ * @returns Cost in USD
+ */
+declare function calculateAnthropicCost(model: string, inputTokens: number, outputTokens: number, cacheHitTokens?: number): number;
+/**
+ * Extract token usage from Anthropic API response
+ * @param response - The raw response from Anthropic API
+ * @returns Token usage object with extracted values
+ */
+interface AnthropicTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+declare function extractTokenUsageFromResponse$2(response: any): AnthropicTokenUsage | null;
+
+/**
+ * Google pricing utilities
+ * Re-exports unified utilities with Google-specific naming for consistency
+ */
+
+/**
+ * Calculate the cost for token usage based on Google pricing
+ * @param model - The Google model name
+ * @param inputTokens - Number of input tokens used
+ * @param outputTokens - Number of output tokens used
+ * @param cacheHitTokens - Number of cached input tokens (optional, when supported)
+ * @returns Cost in USD
+ */
+declare function calculateGoogleCost(model: string, inputTokens: number, outputTokens: number, options?: CostCalculationOptions): number;
+/**
+ * Extract token usage from Google API response
+ * @param response - The raw response from Google API
+ * @returns Token usage object with extracted values
+ */
+interface GoogleTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+declare function extractTokenUsageFromResponse$1(response: any): GoogleTokenUsage | null;
+
+/**
+ * Mistral pricing utilities
+ * Re-exports unified utilities with Mistral-specific naming for consistency
+ */
+/**
+ * Calculate the cost for token usage based on Mistral pricing
+ * @param model - The Mistral model name
+ * @param inputTokens - Number of input tokens used
+ * @param outputTokens - Number of output tokens used
+ * @param cacheHitTokens - Number of cached input tokens (optional, when supported)
+ * @returns Cost in USD
+ */
+declare function calculateMistralCost(model: string, inputTokens: number, outputTokens: number, cacheHitTokens?: number): number;
+/**
+ * Extract token usage from Mistral API response
+ * @param response - The raw response from Mistral API
+ * @returns Token usage object with extracted values
+ */
+interface MistralTokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+declare function extractTokenUsageFromResponse(response: any): MistralTokenUsage | null;
+
+declare abstract class AbstractAgent {
+    name: string;
+    gameId?: string;
+    userId?: string;
+    /**
+     * Output ceiling sent with every request from this agent. Resolved once from the model's
+     * catalog override, else DEFAULT_MAX_OUTPUT_TOKENS. Callers needing more room raise it
+     * after construction (see story generation), the same way gameId/userId are assigned —
+     * so subclasses must read it when building a request, never snapshot it at construction.
+     */
+    maxOutputTokens: number;
+    /**
+     * Reasoning-depth knobs, resolved once from the catalog like maxOutputTokens and, like it,
+     * overridable per instance for calls whose profile differs from a turn (story generation
+     * runs deeper). Each provider speaks one dialect — effort (DeepSeek, GLM, Gemini, Claude
+     * adaptive) or a token budget (Qwen, Claude Haiku) — and reads only the field it
+     * understands; the other is ignored. Subclasses read these when building a request.
+     */
+    reasoningEffort?: ReasoningEffort;
+    thinkingBudgetTokens?: number;
+    protected readonly instruction: string;
+    /**
+     * The instruction split on CACHE_TIER_MARKER: [shared static tier, per-bot tier].
+     * Length 1 when the prompt has no marker (GM prompts, tests). Providers with
+     * explicit cache breakpoints (Anthropic) place one per part; everyone else uses
+     * the joined marker-free `instruction`, whose shared prefix implicit caches match.
+     */
+    protected readonly instructionParts: string[];
+    protected readonly temperature: number;
+    protected readonly model: string;
+    protected readonly enableThinking: boolean;
+    protected readonly agentLoggingConfig: AgentLoggingConfig;
+    protected constructor(name: string, instruction: string, model: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    /**
+     * Public ask API — template methods that time the provider call and stamp `durationMs`
+     * into the returned TokenUsage. Subclasses implement doAskWithZodSchema/doAskText and
+     * must NOT override these.
+     */
+    askWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    askText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    private stampDuration;
+    /** Failed calls carry their duration too — a 35s provider stall that errors is still signal. */
+    private stampErrorDuration;
+    protected abstract doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no schema appended to the prompt, no JSON mode, no parsing.
+     * Returns [content, thinkingContent, tokenUsage?, thinkingSignature?] — same tuple
+     * shape as doAskWithZodSchema but with the raw response string as content.
+     * Implementations must throw on empty content so the recoverable-error/retry UX
+     * is preserved (errors surface in the UI; the user triggers retries).
+     */
+    protected abstract doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    protected logger(message: string): void;
+    protected logAsking(messages: AIMessage[]): void;
+    protected logSystemPrompt(): void;
+    protected logMessages(messages: AIMessage[]): void;
+    protected logReply(reply: any, thinking?: string, usage?: TokenUsage$1): void;
+    /**
+     * Merges consecutive user messages (e.g. a GM command followed by the detached
+     * reminder postfix) into one, for providers that expect alternating roles — this
+     * reproduces the pre-detachment request shape. ClaudeAgent overrides this to keep
+     * them separate: Anthropic combines consecutive user turns into one turn but keeps
+     * distinct content blocks, which lets its fast cache breakpoint sit on the persisted
+     * command block while the throwaway reminder rides behind it.
+     */
+    protected prepareMessages(messages: AIMessage[]): AIMessage[];
+}
+
+declare class AgentFactory {
+    static createAgent(name: string, instruction: string, llmType: string, apiKeys: ApiKeyMap, enableThinking?: boolean): AbstractAgent;
+    private static validateLlmTypeAndGet;
+}
+
+declare class ClaudeAgent extends AbstractAgent {
+    private readonly client;
+    private get defaultParams();
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    /**
+     * Unlike the base class, does NOT merge consecutive user messages: the Messages API
+     * combines consecutive user turns into a single turn while preserving separate content
+     * blocks, so the trailing reminder stays out of the persisted command block and the
+     * fast cache breakpoint (see applyCacheBreakpoint) lands on bytes that repeat.
+     */
+    protected prepareMessages(messages: AIMessage[]): AIMessage[];
+    private convertToAnthropicMessages;
+    /**
+     * Converts messages for thinking-enabled requests.
+     * Assistant messages include thinking blocks ONLY if they have valid signatures.
+     * If a signature is missing, the thinking block is dropped to ensure API validity.
+     */
+    private convertToAnthropicMessagesWithThinking;
+    /**
+     * Breakpoint 2 (fast tier): the last message that will be re-sent byte-identically on
+     * the next request. That is the SECOND-to-last message, not the last one — the final
+     * user message carries unpersisted content (the reminder postfix / schema description)
+     * appended to the GM command, so its bytes never repeat and a breakpoint there would be
+     * a pure 1.25x write tax with no reads. The second-to-last message (the bot's previous
+     * reply, or an earlier flushed block) reappears verbatim next turn, where the moved-
+     * forward breakpoint finds it via the 20-block lookback.
+     *
+     * NOT the top-level auto-caching mode: that mode targets the LAST cacheable block,
+     * which for us is exactly the never-repeated tail — every entry it wrote would be dead.
+     */
+    private applyCacheBreakpoint;
+    /**
+     * Builds TokenUsage from the response. Anthropic's input_tokens EXCLUDES cached tokens
+     * (total prompt = input_tokens + cache_read + cache_creation), unlike the OpenAI-shaped
+     * providers whose prompt_tokens include them — so reconstruct the full prompt size here
+     * before pricing. Cache reads bill at the cacheHitPrice (~0.1x); cache writes bill at
+     * 1.25x input, which MODEL_PRICING doesn't model, so written tokens are priced at the
+     * plain input rate (~20% undercount on the written span only).
+     */
+    private buildTokenUsage;
+    private convertRole;
+    /**
+     * New method using Zod with Anthropic's Claude API
+     * Since Anthropic doesn't support native JSON schemas, we generate prompt descriptions
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: same request as askWithZodSchema but without a schema description
+     * appended to the prompt and without JSON parsing. Thinking blocks and signatures
+     * are extracted identically.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+declare class Gpt5Agent extends AbstractAgent {
+    private readonly client;
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    /**
+     * Structured output method using Zod with OpenAI's Responses API
+     * This provides better schema handling and runtime validation
+     *
+     * Uses responses.parse for models that support structured outputs
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask via the Responses API: no structured-output format, raw output_text.
+     * Note: askWithZodSchema surfaces "thinking" via a schema-injected field; that trick
+     * doesn't apply to plain text, so thinking content is empty here (OpenAI does not
+     * expose chain-of-thought directly).
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+declare class GoogleAgent extends AbstractAgent {
+    private readonly client;
+    private readonly defaultConfig;
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    private convertToContents;
+    private convertRole;
+    private calculateCost;
+    private calculateCostWithCacheHits;
+    private deriveContextTokens;
+    /**
+     * New method using Zod with Google's Gemini API
+     * This provides better schema handling and runtime validation
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: same request as askWithZodSchema but without responseSchema /
+     * responseMimeType, returning the raw text. Thinking parts and thought signatures
+     * are extracted identically.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    /**
+     * Handles Gemini API errors and throws appropriate specific exceptions
+     * @param error - The error to handle
+     */
+    private handleGeminiError;
+}
+
+declare class MistralAgent extends AbstractAgent {
+    private readonly client;
+    private get defaultParams();
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    private convertToMistralMessages;
+    private processReply;
+    private processStructuredReply;
+    private extractTokenUsage;
+    /**
+     * New method using Zod with Mistral API
+     * This provides better schema handling and runtime validation
+     *
+     * Uses Mistral Custom Structured Outputs (responseFormat json_schema), which
+     * enforces the response shape server-side and is more reliable than plain JSON
+     * mode. The human-readable schema description is still appended to the last
+     * message because the enforced schema omits field descriptions/semantics.
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no schema appended, no responseFormat. Note that Magistral
+     * reasoning models only return thinking traces when responseFormat is NOT
+     * json_object, so unlike askWithZodSchema this path can surface thinking content.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+declare class DeepSeekV2Agent extends AbstractAgent {
+    private readonly client;
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    private convertToOpenAIMessages;
+    private addSystemInstruction;
+    /**
+     * Thinking params for the request body. DeepSeek V4 toggles thinking with a top-level
+     * `thinking: { type }` (the docs' `extra_body` is a Python-SDK wrapper; openai-node has no
+     * such thing and sends the key literally, where the API ignores it — probed 2026-08-30:
+     * `extra_body: {thinking: {type: 'disabled'}}` still reasoned, top-level `thinking` did
+     * not). Thinking is on by default, so the flag matters only for turning it off.
+     * `reasoning_effort` takes low|high|max (default high, no budget parameter exists); it is
+     * the instance field (catalog default, per-call override) and is only sent when set.
+     */
+    private thinkingParams;
+    /**
+     * New method using Zod with DeepSeek API
+     * This provides better schema handling and runtime validation
+     *
+     * DeepSeek V4 uses thinking toggle via extra_body. JSON mode (response_format
+     * json_object) is supported with or without thinking, so we always request it.
+     * Thinking additionally surfaces reasoning via reasoning_content.
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: same request structure as askWithZodSchema but without JSON mode
+     * or a schema appended to the prompt. The raw response string is returned as-is.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+/**
+ * xAI Grok agent on the Responses API.
+ *
+ * grok-4.6 is an always-on reasoning model; we do not send `reasoning_effort` and use the
+ * xAI default ("high"). Reasoning cannot be disabled. Each response's encrypted reasoning
+ * items (requested via `include: ["reasoning.encrypted_content"]`) are returned as the 4th
+ * tuple element, stored on the game message as `grokEncryptedReasoning`, and replayed into
+ * `input` on later turns so the model keeps its chain-of-thought across the conversation.
+ */
+declare class GrokAgent extends AbstractAgent {
+    private readonly client;
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    /**
+     * Structured output implementation for Grok using json_object mode with prompt
+     * augmentation — more reliable than json_schema on OpenAI-compatible endpoints.
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no JSON mode and no schema appended to the prompt.
+     * Reasoning extraction and token accounting are identical to askWithZodSchema.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+    private createResponse;
+    /**
+     * Converts game history to Responses API input items. The system instruction is
+     * merged into the leading system message; assistant messages carrying stored
+     * encrypted reasoning get their reasoning items replayed right before them.
+     */
+    private buildResponsesInput;
+    /**
+     * Walks the response output items: reasoning items yield the human-readable summary
+     * plus the encrypted items (serialized for storage/replay); message items yield text.
+     */
+    private extractResponseParts;
+    private extractTokenUsage;
+}
+
+declare class KimiAgent extends AbstractAgent {
+    private readonly client;
+    private get defaultParams();
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    private convertToOpenAIMessages;
+    private extractThinkingAndUsage;
+    /**
+     * New method using Zod with Kimi/Moonshot AI API
+     * This provides better schema handling and runtime validation
+     *
+     * Kimi/Moonshot AI API is OpenAI-compatible, so we try JSON mode first,
+     * and fall back to prompt-based schema if not supported
+     */
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no JSON mode (and therefore no prompt-based schema fallback).
+     * Thinking toggle and reasoning_content extraction are identical to askWithZodSchema.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+declare class GlmAgent extends AbstractAgent {
+    private readonly client;
+    private get defaultParams();
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    private convertToOpenAIMessages;
+    private extractThinkingAndUsage;
+    /**
+     * Robust schema-aware coercion of a model reply.
+     * Order: strict JSON parse → embedded {…} extraction → wrap-as-reply (BotAnswer-shaped schemas).
+     * Returns the validated value or throws.
+     */
+    private parseAndValidate;
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no JSON mode and no schema appended to the prompt.
+     * Thinking toggle and reasoning_content extraction are identical to askWithZodSchema.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+declare class FuguAgent extends AbstractAgent {
+    private readonly client;
+    private get defaultParams();
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    private convertToOpenAIMessages;
+    private logRawUsageForCalibration;
+    private extractThinkingAndUsage;
+    private prependSystemInstruction;
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no schema appended to the prompt. Reasoning extraction and token
+     * accounting are identical to askWithZodSchema.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+declare class QwenAgent extends AbstractAgent {
+    private readonly client;
+    private get defaultParams();
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    /**
+     * Thinking params for the request body. `thinking_budget` caps reasoning length and is only
+     * sent when the instance has one (catalog default, or a per-call override like story
+     * generation); without it the model thinks at the provider default, and qwen3.8-max's
+     * latency then swings 30–100s.
+     *
+     * `reasoning_effort` is deliberately NOT sent. Probed live 2026-08-30 on qwen3.8-flash and
+     * qwen3.8-max: every value low..max is accepted, but reasoning length doesn't track it
+     * (max: low → 1,686 reasoning tokens / 44s, high → 226 / 7s, xhigh → 1,102 / 30s), while
+     * thinking_budget bounds it reliably (≤340 at 1024). The docs also call the two mutually
+     * exclusive on qwen3.8-max. So on Qwen the budget IS the effort knob; `reasoningEffort`
+     * on this agent is ignored.
+     */
+    private thinkingParams;
+    private convertToOpenAIMessages;
+    private extractThinkingAndUsage;
+    /**
+     * Robust schema-aware coercion of a model reply.
+     * Order: strict JSON parse → embedded {…} extraction → wrap-as-reply (BotAnswer-shaped schemas).
+     * Returns the validated value or throws.
+     */
+    private parseAndValidate;
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no schema appended to the prompt.
+     * Thinking toggle and reasoning_content extraction are identical to askWithZodSchema.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+declare class MiniMaxAgent extends AbstractAgent {
+    private readonly client;
+    private get defaultParams();
+    private readonly logTemplates;
+    private readonly errorMessages;
+    constructor(name: string, instruction: string, model: string, apiKey: string, temperature: number, enableThinking?: boolean, agentLoggingConfig?: AgentLoggingConfig);
+    private thinkingParams;
+    private convertToOpenAIMessages;
+    private extractThinkingAndUsage;
+    /**
+     * Robust schema-aware coercion of a model reply.
+     * Order: strict JSON parse → embedded {…} extraction → wrap-as-reply (BotAnswer-shaped schemas).
+     * Returns the validated value or throws.
+     */
+    private parseAndValidate;
+    doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
+    /**
+     * Plain-text ask: no schema appended to the prompt.
+     * Thinking handling and reasoning_content extraction are identical to askWithZodSchema.
+     */
+    doAskText(messages: AIMessage[]): Promise<[string, string, TokenUsage$1?, string?]>;
+}
+
+export { type AIMessage, ANTHROPIC_REASONING_EFFORTS, API_KEY_CONSTANTS, AbstractAgent, type AgentActivityData, AgentFactory, type AgentLoggingConfig, type AnthropicReasoningEffort, type AnthropicTokenUsage, type ApiKeyMap, BotResponseError, CACHE_TIER_MARKER, ClaudeAgent, type CostCalculationOptions, DEEPSEEK_PEAK_SCHEDULE, DEEPSEEK_REASONING_EFFORTS, DEFAULT_LOGGING_CONFIG, DEFAULT_MAX_OUTPUT_TOKENS, type DeepSeekReasoningEffort, type DeepSeekTokenUsage, DeepSeekV2Agent, FUGU_REASONING_EFFORTS, FuguAgent, type FuguReasoningEffort, GEMINI_REASONING_EFFORTS, GLM_REASONING_EFFORTS, type GeminiReasoningEffort, GlmAgent, type GlmReasoningEffort, GoogleAgent, type GoogleTokenUsage, Gpt5Agent, GrokAgent, type GrokTokenUsage, type JsonSchemaOptions, KimiAgent, type KimiTokenUsage, type LLMModel, LLM_CONSTANTS, type LlmLogger, type LoggingConfig, MESSAGE_ROLE, MODEL_PRICING, MiniMaxAgent, MistralAgent, type MistralTokenUsage, type Modality, ModelAuthenticationError, type ModelConfig, ModelError, ModelOverloadError, type ModelPricing, ModelQuotaExceededError, ModelRateLimitError, ModelRefusalError, type ModelTag, ModelUnavailableError, OPENAI_REASONING_EFFORTS, type OpenAIReasoningEffort, type OpenAITokenUsage, type PeakPricing, type PricingUnit, type ProviderSchema, type TokenUsage as ProviderTokenUsage, type ProviderType, QwenAgent, REASONING_EFFORT_SCALE, type ReasoningEffort, SupportedAiKeyNames, SupportedAiModels, type TokenUsage$1 as TokenUsage, ZodSchemaConverter, calculateAnthropicCost, calculateCost, calculateDeepSeekCost, calculateGoogleCost, calculateGrokCost, calculateKimiCost, calculateMistralCost, calculateModelCost, calculateOpenAICost, clampReasoningEffort, cleanResponse, createCatalog, extractAnthropicTokenUsage, extractTokenUsageFromResponse$2 as extractAnthropicTokenUsageFromResponse, extractDeepSeekTokenUsage, extractTokenUsageFromResponse$5 as extractDeepSeekTokenUsageFromResponse, extractFirstJsonObject, extractGoogleTokenUsage, extractTokenUsageFromResponse$1 as extractGoogleTokenUsageFromResponse, extractGrokTokenUsage, extractTokenUsageFromResponse$3 as extractGrokTokenUsageFromResponse, extractKimiTokenUsage, extractTokenUsageFromResponse$4 as extractKimiTokenUsageFromResponse, extractMistralTokenUsage, extractTokenUsageFromResponse as extractMistralTokenUsageFromResponse, extractOpenAITokenUsage, extractTokenUsageFromResponse$6 as extractOpenAITokenUsageFromResponse, extractTokenUsage, extractUsageAndCalculateCost, generateSchemaInstructions, getModelConfigByApiName, getModelDisplayName, getModelProviderName, getModelTags, getProviderSignatureFields, isHybridThinkingModel, isInPeakWindow, isPeakBilling, isWeekendAt, logger, mergeThinking, modelHasTag, modelIsFast, needsPromptBasedSchema, parseAndValidateLlmJson, safeValidateResponse, setLlmLogger, stableHashHex, stripInlineThinking, supportsNativeJsonSchema, toAnthropicEffort, toDeepSeekEffort, toFuguEffort, toGeminiEffort, toGlmEffort, toOpenAIEffort, validateResponse };