import { type AgentTelemetry } from "@oh-my-pi/pi-agent-core";
import type { ModelRegistry } from "../config/model-registry.js";
import type { Settings } from "../config/settings.js";
import { type CostGateApi } from "../session/cost-gate.js";
import type { Skill } from "./skills.js";
/** Background compression through a fast model; the model key scopes cached unusable answers. */
export interface SkillDescriptionCompressor {
    /** `provider/id` of the model the next request would use; `undefined` when none is available. */
    modelKey(): string | undefined;
    /** @throws on transport failures, missing models or credentials, and non-`stop` completions. */
    compress(name: string, description: string, request: string): Promise<string>;
}
/**
 * Resolve the fast role for each background request the way `/models` shows it — configured `smol`,
 * the inherited `default` when `smol` is unset, then the built-in chain — before a configured `tiny`.
 * Never uses the session's foreground model. `getCostGate` returns the session tree's gate per request,
 * following it across new sessions and switches; each provider attempt is admitted and metered there.
 */
export declare function createSkillDescriptionCompressor(registry: ModelRegistry, settings: Settings, options?: {
    sessionId?: string;
    getTelemetry?: () => AgentTelemetry | undefined;
    getCostGate?: () => CostGateApi | undefined;
}): SkillDescriptionCompressor;
/** A deterministic, bounded routing hint while model compression is pending. */
export declare function previewSkillDescription(description: string): string;
/**
 * Process-wide store at {@link getSkillDescriptionsDbPath}, opened on first use
 * and closed at exit. Opening per render and per compression write created and
 * deleted the `-wal`/`-shm` sidecars and re-ran PRAGMA/CREATE/chmod every time.
 * `undefined` when it cannot be opened (logged once; prompts keep the bounded
 * previews) and under the test runner, so tests never read or write the user's
 * cache; tests open {@link SkillDescriptionStore.open} explicitly.
 */
export declare function sharedSkillDescriptionStore(): SkillDescriptionStore | undefined;
/**
 * Store under an SDK session's own `agentDir` when it differs from the process
 * agent dir; the caller closes it with the session. `undefined` under the test
 * runner (same isolation as {@link sharedSkillDescriptionStore}) or when it
 * cannot be opened (logged; the catalog then uses the shared store).
 */
export declare function openSessionSkillDescriptionStore(agentDir: string): SkillDescriptionStore | undefined;
/**
 * SQLite store of compressed descriptions, keyed by prompt + skill content hash. A
 * `<key>:v<revision>:<provider/id>` row records that model's unusable answer, so it is not asked
 * again while new models and validation revisions still are.
 */
export declare class SkillDescriptionStore {
    #private;
    /** Database file; scopes in-flight compression jobs shared by catalogs on this store. */
    readonly path: string;
    private constructor();
    /**
     * Open (creating if needed) the store at `dbPath`.
     * @throws when the directory or database cannot be created.
     */
    static open(dbPath?: string): SkillDescriptionStore;
    /** @throws on SQLite errors. */
    get(key: string): string | undefined;
    /** @throws on SQLite errors. */
    put(key: string, description: string): void;
    /** Whether closing has begun and no new compression work is admitted. */
    get isClosing(): boolean;
    /** Whether the database is closed and late replies are discarded; false while draining. */
    get isClosed(): boolean;
    /** Stop admitting requests and give already-running compressions a bounded chance to persist. */
    close(): Promise<void>;
    /** Start bounded closure on disposal; await close() to wait for pending writes. */
    [Symbol.dispose](): void;
}
/** One prompt/session snapshot; completing a background job never mutates its rendered descriptions. */
export declare class SkillDescriptionCatalog {
    #private;
    /**
     * `store` defaults to {@link sharedSkillDescriptionStore}; without one, prompts keep previews.
     * `deferCompression` holds model work until {@link startCompression}: until the owning session's
     * cost gate exists, and off a startup path (resolving the compression model composes the catalog).
     */
    constructor(options?: {
        store?: SkillDescriptionStore;
        compress?: SkillDescriptionCompressor;
        deferCompression?: boolean;
    });
    /** Read the session's frozen prompt hints without starting new model work. */
    snapshot(skills: readonly Skill[]): Array<Skill & {
        description: string;
    }>;
    render(skills: readonly Skill[]): Array<Skill & {
        description: string;
    }>;
    /** Start compression held by `deferCompression`; later renders schedule theirs immediately. */
    startCompression(): void;
    /** Await background writes already scheduled by this catalog (for shutdown or tests). */
    waitForPending(): Promise<void>;
}