/**
 * Storage backends for offloaded tool result content.
 *
 * This module defines the {@link Storage} interface and provides three built-in
 * implementations: {@link InMemoryStorage}, {@link FileStorage}, and {@link S3Storage}.
 * Each content block from a tool result is stored individually with its content type preserved.
 */
import type { Sandbox } from '../../sandbox/base.js';
/**
 * Backend for storing and retrieving offloaded content blocks.
 *
 * Implement this interface to create custom storage backends (e.g., Redis, DynamoDB).
 * The SDK ships three built-in implementations: {@link InMemoryStorage},
 * {@link FileStorage}, and {@link S3Storage}.
 */
export interface Storage {
    /**
     * Store content and return a reference identifier.
     *
     * @param key - Unique key for this content block
     * @param content - Raw content bytes to store
     * @param contentType - MIME type of the content (e.g., "text/plain", "image/png")
     * @returns Reference string for later retrieval
     */
    store(key: string, content: Uint8Array, contentType?: string): Promise<string>;
    /**
     * Retrieve previously stored content by reference.
     *
     * @param reference - Reference returned by a previous {@link store} call
     * @returns Content bytes and content type
     * @throws Error if the reference is not found
     */
    retrieve(reference: string): Promise<{
        content: Uint8Array;
        contentType: string;
    }>;
}
/**
 * In-memory storage backend.
 *
 * Useful for testing and serverless environments where disk access is not available.
 * Supports turn-based eviction: entries not accessed (stored or retrieved) within
 * `evictAfterTurns` agent loop cycles are automatically removed when the plugin
 * calls `_evict`. Eviction is enabled by default (20 cycles). Pass `null` to disable.
 *
 * Note: content does not survive process restarts. For multi-session persistence,
 * use {@link FileStorage} or {@link S3Storage}. Each agent should use its own
 * `InMemoryStorage` instance — sharing one across multiple agents is not supported
 * when eviction is enabled.
 *
 * Evicted entries are permanently deleted from memory. The agent will receive
 * an error if it attempts to retrieve evicted content.
 *
 * @param evictAfterTurns - Cycles of inactivity before eviction. Defaults to 20. `null` disables.
 */
export declare class InMemoryStorage implements Storage {
    private _store;
    private _counter;
    private _currentCycle;
    private readonly _evictAfterTurns;
    private _boundAgent;
    static readonly DEFAULT_EVICT_AFTER_TURNS = 20;
    constructor(evictAfterTurns?: number | null);
    /** {@inheritdoc} */
    store(key: string, content: Uint8Array, contentType?: string): Promise<string>;
    /** {@inheritdoc} */
    retrieve(reference: string): Promise<{
        content: Uint8Array;
        contentType: string;
    }>;
    /**
     * Claim this storage for a single agent. Throws if already bound to a different agent.
     * @internal
     */
    _bind(agent: object): void;
    /**
     * Update current cycle and evict stale entries.
     * Called by the ContextOffloader plugin on each BeforeModelCallEvent.
     * @internal
     */
    _evict(cycle: number): void;
    /** Remove all stored content. */
    clear(): void;
}
/**
 * File-based storage backend.
 *
 * Stores offloaded content as files on the host filesystem, or through a configured
 * {@link Sandbox}. File extensions are derived from the content type. A `.metadata.json`
 * sidecar file tracks content types across restarts. References are file paths preserving
 * the configured artifact directory form.
 *
 * When used by {@link ContextOffloader} without an explicit sandbox, FileStorage is
 * bound to each agent's sandbox, which may be the default NotASandboxLocalEnvironment.
 */
export interface FileStorageOptions {
    /** Directory path where artifact files will be stored. Defaults to `./artifacts`. */
    artifactDir?: string;
    /** Sandbox to use for direct store/retrieve calls. */
    sandbox?: Sandbox;
}
export declare class FileStorage implements Storage {
    private static readonly METADATA_FILE;
    private readonly _artifactDir;
    private readonly _sandbox;
    private _counter;
    private _contentTypes;
    private _metadataLoaded;
    private _metadataWriteChain;
    constructor(options?: string | FileStorageOptions);
    /**
     * Return a storage instance bound to the provided sandbox.
     *
     * Instances constructed with an explicit sandbox keep using that sandbox. Detached
     * instances produce a new storage object so a shared ContextOffloader can isolate
     * artifacts for each agent sandbox.
     *
     * @param sandbox - Sandbox to use for the returned storage instance.
     */
    forSandbox(sandbox: Sandbox): FileStorage;
    private static _extensionFor;
    private _artifactPath;
    private _ensureDir;
    private _ensureSandbox;
    private _loadMetadata;
    private _loadSandboxMetadata;
    private _saveMetadata;
    private _saveSandboxMetadata;
    /** {@inheritdoc} */
    store(key: string, content: Uint8Array, contentType?: string): Promise<string>;
    /** {@inheritdoc} */
    retrieve(reference: string): Promise<{
        content: Uint8Array;
        contentType: string;
    }>;
}
/**
 * S3-based storage backend.
 *
 * Stores offloaded content as S3 objects. Content type is preserved as S3 object metadata.
 * References are `s3://` URIs for direct access via AWS CLI or SDK.
 *
 * @param bucket - S3 bucket name
 * @param options - Optional configuration (prefix, region, pre-configured S3Client)
 */
export declare class S3Storage implements Storage {
    private readonly _bucket;
    private readonly _prefix;
    private _client;
    private readonly _region;
    private _counter;
    constructor(bucket: string, options?: {
        prefix?: string;
        region?: string;
        s3Client?: import('@aws-sdk/client-s3').S3Client;
    });
    private _getClient;
    /** {@inheritdoc} */
    store(key: string, content: Uint8Array, contentType?: string): Promise<string>;
    /** {@inheritdoc} */
    retrieve(reference: string): Promise<{
        content: Uint8Array;
        contentType: string;
    }>;
}
//# sourceMappingURL=storage.d.ts.map