import { type ContextAttemptReference, type ContextSnapshotScope, type ContextSnapshotV1 } from "../../llm/context-snapshot.js";
import type { ContextUsageSnapshot } from "../../llm/token-usage.js";
import type { ChatMessage, ProviderId, TokenUsage } from "../../types.js";
export interface ContextUsageTarget {
    readonly provider?: ProviderId | undefined;
    readonly model?: string | undefined;
    /** Explicit provider/model window for this session, if the user set one. */
    readonly contextLimitTokens?: number | undefined;
}
export type ContextClock = () => number;
export declare function contextUsageLimit(target: ContextUsageTarget): number;
/**
 * Keep the most recent request-scoped measurement. The message-history estimate
 * omits the system prefix and tool schemas, so substituting it for a live
 * measurement made the displayed number oscillate between two different scopes
 * every step; it is now only a cold-start fallback.
 */
export declare function resolveContextSnapshot(target: ContextUsageTarget, history: readonly ChatMessage[], current: ContextSnapshotV1 | undefined, now?: ContextClock): ContextSnapshotV1 | undefined;
/** Fold provider usage into one canonical provider-request observation. */
export declare function recordContextUsageSnapshot(target: ContextUsageTarget, current: ContextSnapshotV1 | undefined, usage: TokenUsage, attempt: ContextAttemptReference | undefined, now?: ContextClock): ContextSnapshotV1;
/** After compaction, exact provider fill is stale and the new scope is explicit. */
export declare function compactedContextSnapshot(target: ContextUsageTarget, current: ContextSnapshotV1 | undefined, history: readonly ChatMessage[], afterTokens: number | undefined, scope: Extract<ContextSnapshotScope, "message-history" | "assembled-request">, now?: ContextClock): ContextSnapshotV1;
export declare function estimatedContextSnapshot(target: ContextUsageTarget, current: ContextSnapshotV1 | undefined, estimatedTokens: number, now?: ContextClock): ContextSnapshotV1 | undefined;
export interface ContextProjection {
    readonly contextSnapshot: ContextSnapshotV1 | undefined;
    readonly contextUsage: ContextUsageSnapshot | undefined;
    readonly contextChip: string | undefined;
}
export declare function createContextProjector(formatChip: (snapshot: ContextUsageSnapshot) => string): (target: ContextUsageTarget, history: readonly ChatMessage[], current: ContextSnapshotV1 | undefined, now?: ContextClock) => ContextProjection;
/** Legacy persisted shape, optionally carrying the additive V1 object. */
export interface PartialUsageSnapshot {
    readonly contextTokens: number;
    readonly contextLimit?: number | undefined;
    readonly lastCompletionTokens?: number | undefined;
    readonly sessionPromptTokens?: number | undefined;
    readonly sessionCompletionTokens?: number | undefined;
    readonly exact: boolean;
    readonly contextSnapshot?: unknown;
}
/** Restore V1 when available, otherwise migrate the unversioned legacy shape. */
export declare function restoredContextSnapshot(target: ContextUsageTarget, usage: PartialUsageSnapshot | ContextUsageSnapshot | ContextSnapshotV1 | undefined, now?: ContextClock): ContextSnapshotV1 | undefined;
export declare function resolveContextUsageSnapshot(target: ContextUsageTarget, history: readonly ChatMessage[], current: ContextUsageSnapshot | undefined): ContextUsageSnapshot | undefined;
export declare function compactedUsageSnapshot(target: ContextUsageTarget, current: ContextUsageSnapshot | undefined, history: readonly ChatMessage[], afterTokens?: number): ContextUsageSnapshot;
export declare function estimatedUsageSnapshot(target: ContextUsageTarget, current: ContextUsageSnapshot | undefined, estimatedTokens: number): ContextUsageSnapshot | undefined;