import type { CostSessionRecord } from '../../utils/cost-session-history';
import type { DiagnosticEntry } from './diagnostics';
import type { PersistedSession } from './session-snapshot';
/**
 * Storage backend for chat-session persistence. The library ships this
 * interface only and wires nothing by default; the host app provides an
 * implementation and opts in via `chatConfig` (GENC-1351 §5.2/D2). Every method
 * is async so a server-backed provider satisfies the same contract as a
 * browser-storage one.
 *
 * @public
 */
export interface SessionPersistenceProvider {
    /**
     * Minimum milliseconds between autosaves for this backend — a throttle the
     * assistant applies to its "save on every transcript change" signal. `0`
     * means save as soon as the current tick settles (coalescing only writes
     * within the same tick), which is right for synchronous, cheap storage like
     * `sessionStorage`/`localStorage`. A network/server backend should set a
     * higher value (e.g. 1000–2000) so it doesn't hammer the wire mid tool-loop.
     *
     * **Required** — not optional — so every implementation makes a deliberate
     * choice for its own write-cost profile rather than inheriting a guess.
     */
    saveDebounceMs: number;
    /** Load the snapshot for `sessionKey`, or `null` if none / unreadable. */
    load(sessionKey: string): Promise<PersistedSession | null>;
    /** Persist `snapshot` for `sessionKey`, overwriting any existing one. */
    save(sessionKey: string, snapshot: PersistedSession): Promise<void>;
    /** Remove any stored snapshot for `sessionKey`. */
    clear(sessionKey: string): Promise<void>;
    /**
     * Load the user's remembered UI preferences for `sessionKey` (GENC-1351) — the
     * "remember chat" toggle plus the cog-menu display switches. Stored
     * **independently of the session snapshot** (survives `clear`) and **independently
     * of the `enabled` toggle** — a user's display choices persist whether or not
     * they remember the chat. `undefined` means none were ever saved → the host's
     * configured `chatConfig.ui` defaults apply. Only the fields the user has changed
     * are present; absent fields keep their config default. Optional: a provider that
     * omits it simply doesn't remember preferences across reloads.
     */
    loadPreferences?(sessionKey: string): Promise<SessionPreferences | undefined>;
    /** Persist the user's UI preferences for `sessionKey` (kept across `clear`). */
    savePreferences?(sessionKey: string, preferences: SessionPreferences): Promise<void>;
    /**
     * Scoped cost/build history — the per-project usage rows behind the Usage tab.
     *
     * ‼️ **Keyed by SCOPE, not `sessionKey`**, unlike every other method on this interface.
     * A row holds one project's lifetime usage and the list spans projects, so keying it
     * per session would defeat the model. The scope comes from
     * `chatConfig.costHistory.scope`, falling back to the element `id`, then `'default'`.
     *
     * Optional: when a provider omits these, the assistant falls back to `localStorage`, so
     * hosts that don't implement them are unaffected. Implementing them moves the ledger to
     * the host's own backend, which is what stops it being stranded in one browser.
     *
     * Read/written **independently of the `enabled` toggle** (as with preferences and
     * diagnostics): usage accounting is not conversation content, so a user turning off
     * chat retention should not lose their cost ledger. Best-effort — a failed write must
     * never affect the chat.
     *
     * `undefined` from `loadCostHistory` means "nothing stored", the same as `[]`.
     */
    loadCostHistory?(scope: string): Promise<CostSessionRecord[] | undefined>;
    /** Replace the stored row list for `scope`. See {@link SessionPersistenceProvider.loadCostHistory}. */
    saveCostHistory?(scope: string, records: CostSessionRecord[]): Promise<void>;
    /**
     * Server-saved diagnostics (GENC-1351 §5.8) — a **forward-only append** stream
     * that lets the downloadable debug log span the whole session lifetime, not just
     * the current page load. Optional and **capacious-backends-only**: `WebStorage`
     * omits it (the log dwarfs the restore core), so the feature is simply off there.
     * The element emits *what happened* (new entries since the last flush); the
     * provider owns *how it's filed* (one object per session / per run / per day —
     * its call). Best-effort: a failed write must never affect the chat.
     *
     * Captured **independently of the `enabled` toggle** (like preferences): the
     * forensic log is orthogonal to whether the *chat* is remembered, so it runs
     * whenever a provider implements this — even with "remember chat" off.
     */
    appendDiagnostics?(sessionKey: string, entries: DiagnosticEntry[]): Promise<void>;
    /** Load the full diagnostics stream for `sessionKey` (all appends, any run), for download-reassembly. */
    loadDiagnostics?(sessionKey: string): Promise<DiagnosticEntry[]>;
    /** Hard-delete the diagnostics stream for `sessionKey`. Host/GDPR use — NOT wired to the UI Clear. */
    clearDiagnostics?(sessionKey: string): Promise<void>;
    /**
     * Min ms between diagnostics appends — coarser than `saveDebounceMs` because
     * the log is heavy. Defaults to a sensible coarse value if omitted.
     */
    diagnosticsDebounceMs?: number;
}
/**
 * User-changeable settings that persist across reloads, independently of the chat
 * snapshot and of the "remember chat" toggle (GENC-1351). All optional — an absent
 * field keeps its `chatConfig.ui` default rather than being forced off.
 *
 * @public
 */
export interface SessionPreferences {
    /** "Remember chat" — whether the session snapshot itself is persisted. */
    enabled?: boolean;
    showToolCalls?: boolean;
    showThinkingSteps?: boolean;
    showNarration?: boolean;
    showAgentSwitchIndicator?: boolean;
    /** Enabled loading-animation ids (`AiAssistantAnimation` values, as plain strings). */
    animations?: string[];
}
/**
 * Host-supplied persistence configuration, passed to the assistant via its
 * `persistence` property. Persistence stays inert unless `enabled` is true and
 * a `provider` is set — so existing consumers are unaffected (GENC-1351 D2/D3).
 *
 * @public
 */
export interface SessionPersistenceConfig {
    /** Master switch — persistence does nothing unless this is true. */
    enabled?: boolean;
    /** Storage backend. Required for persistence to take effect. */
    provider?: SessionPersistenceProvider;
}
/**
 * A {@link SessionPersistenceProvider} backed by a Web Storage area. Both
 * `window.sessionStorage` and `window.localStorage` implement the `Storage`
 * API, so one class serves both: point it at `sessionStorage` for
 * refresh-survival that clears on tab close (the showcase default, O6), or at
 * `localStorage` for durable local persistence.
 *
 * Opt-in: a host constructs it and passes it through `chatConfig`; the library
 * never instantiates it on its own.
 *
 * @public
 */
export declare class WebStorageSessionProvider implements SessionPersistenceProvider {
    private readonly storage;
    private readonly keyPrefix;
    /**
     * Web storage is synchronous and cheap, so the default is `0` — save as
     * soon as the tick settles, no throttle. Override via `options.saveDebounceMs`
     * (e.g. if pointing at `localStorage` and you'd rather coalesce large writes).
     */
    readonly saveDebounceMs: number;
    constructor(storage: Storage, options?: {
        keyPrefix?: string;
        saveDebounceMs?: number;
    });
    private storageKey;
    /** Preferences key, namespaced apart from the session key so `clear` leaves it. */
    private preferencesKey;
    load(sessionKey: string): Promise<PersistedSession | null>;
    save(sessionKey: string, snapshot: PersistedSession): Promise<void>;
    clear(sessionKey: string): Promise<void>;
    loadPreferences(sessionKey: string): Promise<SessionPreferences | undefined>;
    savePreferences(sessionKey: string, preferences: SessionPreferences): Promise<void>;
}
//# sourceMappingURL=session-persistence-provider.d.ts.map