/**
 * MediaPersistence — Auto-download generated media to local storage.
 *
 * When LLM tools generate files (images, videos, audio) and return
 * cloud URLs, this service downloads them to a persistent local directory
 * so the user can access them offline without manual intervention.
 *
 * Storage layout:
 *   <project>/assets/images/image_20260520_143022_abc.png
 *   <project>/assets/videos/video_20260520_143055_def.mp4
 *   <project>/assets/audio/audio_20260520_143100_ghi.mp3
 *   <project>/assets/models/  <project>/assets/files/
 *
 * 产出归项目工作区可见的 assets/ 目录(按类型分),项目级、所有会话共享 —— 文件树可见可
 * 管理。文件名带时间戳+随机后缀保证多会话不冲突。(旧版曾存于 .qlogicagent/sessions/<id>/media/)
 *
 * Integration:
 *   Called from the tool result pipeline in tool-loop.ts.
 *   When a tool result's `details.mediaUrls` contains URLs,
 *   each URL is downloaded and the local path is added to details.
 */
export interface MediaDownloadResult {
    /** Original cloud URL. */
    remoteUrl: string;
    /** Local file path after download. */
    localPath: string;
    /** File size in bytes. */
    bytes: number;
    /** MIME type (from Content-Type header). */
    mimeType: string;
    /** First bytes of the saved file as uppercase hex pairs. */
    headerHex?: string;
}
export interface MediaSaveResult extends MediaDownloadResult {
}
export interface MediaPersistenceConfig {
    /**
     * Project working directory. Media downloads to:
     *   `{projectDir}/assets/{images|videos|audio|models|files}/`
     * 项目工作区可见目录,所有会话共享。
     */
    projectDir?: string;
    /** Maximum file size to download (bytes). Default: 500MB. */
    maxFileSize?: number;
    /** Download timeout per file (ms). Default: 300_000 (5 min). */
    timeoutMs?: number;
}
export declare class MediaPersistence {
    private projectDir;
    private readonly maxFileSize;
    private readonly timeoutMs;
    constructor(config?: MediaPersistenceConfig);
    /** Update project root directory. */
    setProjectDir(projectDir: string): void;
    /**
     * Resolve the media directory for a given media type.
     * Path: <project>/assets/<typeSubdir>/   (项目工作区可见目录,文件树可见可管理)
     *
     * 产出归项目级 assets 目录(images/videos/audio/models/files),所有会话共享 —— 一个项目
     * 不同会话的产出始终在工作区可见目录,而非会话级隐藏目录。文件名带时间戳+随机后缀保证不冲突。
     */
    private resolveMediaDir;
    /**
     * Download a remote URL to local storage.
     * Returns the local file path and metadata.
     *
     * Robustness:
     *   - Validates path length (Windows 260 char limit)
     *   - Cleans up partial files on download failure/timeout
     *   - Handles abort/network errors gracefully
     */
    download(remoteUrl: string, hint?: {
        type?: string;
        sessionId?: string;
    }): Promise<MediaDownloadResult>;
    /**
     * Download multiple URLs. Returns results for successful downloads.
     * Failed downloads are logged but don't throw.
     */
    downloadAll(urls: string[], hint?: {
        type?: string;
        sessionId?: string;
    }, log?: {
        warn: (msg: string) => void;
    }): Promise<MediaDownloadResult[]>;
    /**
     * Persist generated media to caller-requested artifact paths.
     *
     * This complements project-level archival downloads: generated assets remain
     * previewable in assets/images, while explicit user deliverables are also
     * written to their requested paths.
     */
    saveAllToPaths(urls: string[], outputPaths: string[], hint?: {
        type?: string;
        sessionId?: string;
    }, log?: {
        warn: (msg: string) => void;
    }): Promise<MediaSaveResult[]>;
    /** Get the project-level assets root (<project>/assets). */
    getMediaDir(): string;
    /** Get the project directory (for testing/inspection). */
    getProjectDir(): string | null;
}
export declare function toFileMediaUrl(filePath: string): string;
