/**
 * Helper Model, lightweight LLM routing for grunt-work tasks.
 *
 * Routes tasks like cache planning, compaction, commit messages, etc. to a
 * cheaper/free model so expensive main models don't waste tokens on routine work.
 *
 * Resolution order:
 *   1. Per-provider helper (helper.providers.{currentProvider}.provider + model)
 *   2. Global helper (helper.globalProvider + helper.globalModel)
 *   3. Tool LLM (tools.llmProvider + tools.llmModel), when enabled/configured
 *
 * Design constraints:
 *   - Optional helper absence is explicit: helperOnly calls return null.
 *   - Configured routes are provider-qualified through the model registry.
 *   - HelperModel.chat() throws request and configuration failures.
 *   - Tracks token usage separately from the main model
 */
import type { ConfigManager } from './manager.js';
import type { LLMProvider } from '../providers/interface.js';
import type { ProviderRegistry } from '../providers/registry.js';
import type { RuntimeEventBus } from '../runtime/events/index.js';
/** Tasks that can be routed to a helper model. */
export type HelperTask = 'cache_strategy' | 'compaction' | 'intent_classify' | 'tool_summarize' | 'commit_message' | 'review_triage';
/** Resolved helper model: provider instance + model ID. */
export interface ResolvedHelper {
    provider: LLMProvider;
    modelId: string;
    /** true when a dedicated helper/tool-LLM route was configured. */
    isHelper: boolean;
}
/** Options for helper model invocation. */
export interface HelperChatOptions {
    maxTokens?: number | undefined;
    systemPrompt?: string | undefined;
    /** If true, return null when no dedicated helper route is available. */
    helperOnly?: boolean | undefined;
}
/** Token usage tracking for helper model calls. */
export interface HelperUsage {
    inputTokens: number;
    outputTokens: number;
    calls: number;
}
export interface HelperModelDeps {
    readonly configManager: Pick<ConfigManager, 'get' | 'getCategory'>;
    readonly providerRegistry: Pick<ProviderRegistry, 'getCurrentModel' | 'getForModel' | 'resolveModelPricing'>;
    /**
     * Runtime bus for usage events. When present, every helper-model call
     * emits LLM_RESPONSE_RECEIVED with its token actuals so the shared
     * cost-attribution pipeline records the spend under whatever tool/hook/MCP
     * origin scope the call ran inside.
     */
    readonly runtimeBus?: RuntimeEventBus | null | undefined;
    /** Optional session identity stamped on emitted usage events. */
    readonly sessionId?: (() => string | undefined) | undefined;
}
export declare class HelperModelUnavailableError extends Error {
    constructor(message: string);
}
/**
 * HelperRouter, resolves which model to use for a given helper task.
 *
 * Resolution order:
 *   1. Per-provider helper (helper.providers.{currentProvider}.provider + model)
 *   2. Global helper (helper.globalProvider + helper.globalModel)
 *   3. Tool LLM (tools.llmProvider + tools.llmModel), when enabled/configured
 */
export declare class HelperRouter {
    private readonly deps;
    constructor(deps: HelperModelDeps);
    private resolveConfiguredProviderModel;
    /**
     * Resolve the best helper for the given task.
     *
     * Returns null only when no dedicated helper route is configured.
     */
    resolve(_task: HelperTask): ResolvedHelper | null;
}
/**
 * HelperModel, lightweight LLM interface for helper tasks.
 *
 * Callers own HelperModel lifetimes explicitly. Provider and configuration
 * failures throw. Explicit optional-helper calls return null when unavailable.
 * Tracks token usage separately from the main model.
 */
export declare class HelperModel {
    private readonly deps;
    private readonly router;
    private _usage;
    constructor(deps: HelperModelDeps);
    /**
     * Send a prompt to the helper model for the given task.
     *
     * @param task     The helper task type (for routing).
     * @param prompt   The user prompt to send.
     * @param options  Optional maxTokens, systemPrompt, helperOnly.
     * @returns        The assistant's text response, or null for explicit optional helper absence.
     */
    chat(task: HelperTask, prompt: string, options?: HelperChatOptions): Promise<string | null>;
    /** Get cumulative helper usage since last reset. */
    getUsage(): Readonly<HelperUsage>;
    /** Reset usage counters. */
    resetUsage(): void;
}
//# sourceMappingURL=helper-model.d.ts.map