import type { FeatureFlagReader } from '../../runtime/feature-flags/index.js';
export declare const DEFAULT_MAX_CHARS = 50000;
/**
 * RetentionPolicyConfig, limits enforced during cleanup for a spill backend.
 *
 * All three limits are applied independently; whichever is most restrictive
 * wins. Prune candidates are deleted oldest-first.
 */
export interface RetentionPolicyConfig {
    /** Maximum age of a spill entry in milliseconds. Default: 1 hour. */
    maxAgeMs?: number | undefined;
    /** Maximum number of retained entries. Default: unlimited. */
    maxCount?: number | undefined;
    /** Maximum total size of retained entries in bytes. Default: unlimited. */
    maxSizeBytes?: number | undefined;
}
/**
 * SpillEntry, a single overflow/spill record as seen by the backend.
 */
export interface SpillEntry {
    /** Stable identifier for this entry (used in refs and cleanup). */
    id: string;
    /** Display-friendly filename or key. */
    filename: string;
    /** Content written to the backend. */
    content: string;
    /** Entry size in bytes (UTF-8 encoded). */
    sizeBytes: number;
    /** Unix timestamp (ms) when the entry was written. */
    createdAt: number;
    /** Backend type that owns this entry. */
    backendType: SpillBackendType;
}
/** Discriminated union of supported backend types. */
export type SpillBackendType = 'file' | 'ledger' | 'diagnostics';
/**
 * SpillBackend, pluggable interface for persisting overflow content.
 *
 * Implementations must be synchronous so they can be called from
 * `OverflowHandler.handle()` without async overhead in the hot path.
 */
export interface SpillBackend {
    /** Backend type discriminant used in overflow references. */
    readonly type: SpillBackendType;
    write(filename: string, content: string): SpillEntry | null;
    read(id: string): string | null;
    cleanup(policy?: RetentionPolicyConfig): void;
    list(): SpillEntry[];
}
export interface OverflowResult {
    content: string;
    /** Typed ref: `file:path`, `ledger:key`, or `diagnostics:key`. */
    overflowRef?: string | undefined;
    /** Backend type that stored the overflow content. */
    spillBackend?: SpillBackendType | undefined;
}
export interface OverflowOptions {
    maxChars?: number | undefined;
    label?: string | undefined;
}
/**
 * FileBackend, spills overflow content to `.goodvibes/.overflow/` on disk.
 */
export declare class FileBackend implements SpillBackend {
    readonly type: SpillBackendType;
    private readonly overflowDir;
    constructor(baseDir: string);
    private ensureDir;
    private _safePath;
    write(filename: string, content: string): SpillEntry | null;
    read(id: string): string | null;
    cleanup(policy?: RetentionPolicyConfig): void;
    /** Lists all overflow entries. Reads file content eagerly, acceptable for small overflow directories. */
    list(): SpillEntry[];
}
/**
 * LedgerBackend, stores overflow entries in-process (Map).
 * Ephemeral: entries are lost on process exit.
 */
export declare class LedgerBackend implements SpillBackend {
    readonly type: SpillBackendType;
    private readonly entries;
    write(filename: string, content: string): SpillEntry | null;
    read(id: string): string | null;
    cleanup(policy?: RetentionPolicyConfig): void;
    list(): SpillEntry[];
}
/**
 * DiagnosticsBackend, records overflow events as structured log entries.
 * Does NOT store content; `read()` always returns null.
 */
export declare class DiagnosticsBackend implements SpillBackend {
    readonly type: SpillBackendType;
    private readonly log;
    write(filename: string, content: string): SpillEntry | null;
    read(_id: string): string | null;
    cleanup(policy?: RetentionPolicyConfig): void;
    list(): SpillEntry[];
}
/**
 * Create a spill backend by type.
 */
export declare function createSpillBackend(type?: SpillBackendType, baseDir?: string): SpillBackend;
export interface OverflowHandlerConfig {
    /**
     * Which backend to use. Defaults to `'file'`.
     */
    spillBackend?: SpillBackendType | undefined;
    /** Base directory for FileBackend. */
    baseDir?: string | undefined;
    /** Retention policy applied during cleanup(). */
    retention?: RetentionPolicyConfig | undefined;
    /** Inject a custom backend directly (takes precedence over spillBackend). */
    backend?: SpillBackend | undefined;
    /** The capability gates control alternate spill backends when supplied by SDK runtime services. */
    featureFlags?: FeatureFlagReader | undefined;
}
/**
 * Handles large tool output by delegating overflow content to a pluggable
 * backend and returning a truncated version with a typed reference URI.
 *
 * Overflow references encode the backend type:
 *   `file:.goodvibes/.overflow/{filename}`
 *   `ledger:{filename}`
 *   `diagnostics:{filename}`
 *
 * Never throws, on write failure, returns truncated content without ref.
 */
export declare class OverflowHandler {
    private readonly backend;
    private readonly retention;
    constructor(config?: OverflowHandlerConfig);
    private sanitizeLabel;
    private buildRef;
    /**
     * Handle potentially large content.
     * Returns unchanged content if within limit.
     * On overflow: delegates to active backend and returns typed ref.
     */
    handle(content: string, options?: OverflowOptions): OverflowResult;
    /**
     * Prune entries that violate the retention policy.
     */
    cleanup(policy?: RetentionPolicyConfig): void;
    /** List current overflow entries from the active backend. */
    list(): SpillEntry[];
    /** Return the active backend type. */
    get backendType(): SpillBackendType;
}
/**
 * overflowCleanup, operator-facing cleanup command.
 *
 * Prunes overflow entries from the provided overflow handler.
 * Suitable for scripted operator invocations (e.g. CLI, cron).
 */
export declare function overflowCleanup(handler: OverflowHandler, policy?: RetentionPolicyConfig): {
    beforeCount: number;
};
//# sourceMappingURL=overflow.d.ts.map