/**
 * Session-aware filesystem operations.
 *
 * Routes file operations to the correct filesystem based on whether the
 * session is sandboxed (Docker) or local. Paths are always in the agent's
 * coordinate system — container paths for sandbox, host paths for non-sandbox.
 *
 * For sandboxed sessions, operations go through `docker exec` when the
 * container is available, with a bind-mount fallback for archived sessions
 * whose containers may be stopped.
 */
import type { SandboxManager } from "./sandbox-manager.js";
/**
 * Thrown by `sessionFileCopy` when the (src, dst) sandbox/project realms
 * differ in a way the helper does not currently support. Callers should
 * map this to HTTP 422 (`{error: "cross-realm continue not supported"}`).
 */
export declare class CrossRealmCopyError extends Error {
    constructor(message: string);
}
/**
 * Context describing the session's sandbox state and project affiliation.
 */
export interface SessionFsContext {
    sandboxed?: boolean;
    projectId?: string;
}
/**
 * Check whether a file exists at the given path.
 *
 * For sandboxed sessions, tries `docker exec test -f` first. If the container
 * is unavailable (stopped/archived), falls back to translating the container
 * path to a host path via the known bind-mount table.
 *
 * For non-sandboxed sessions, checks the host filesystem directly.
 *
 * @param ctx - Session context (sandboxed flag and project ID)
 * @param filePath - Path in the agent's coordinate system
 * @param sandboxManager - Sandbox manager instance (may be null)
 * @returns true if the file exists
 */
export declare function sessionFileExists(ctx: SessionFsContext, filePath: string, sandboxManager: SandboxManager | null): Promise<boolean>;
/**
 * Read a file's contents as a UTF-8 string.
 *
 * For sandboxed sessions, tries `docker exec cat` first. If the container
 * is unavailable, falls back to reading from the host via bind-mount
 * path translation.
 *
 * For non-sandboxed sessions, reads from the host filesystem directly.
 *
 * @param ctx - Session context (sandboxed flag and project ID)
 * @param filePath - Path in the agent's coordinate system
 * @param sandboxManager - Sandbox manager instance (may be null)
 * @returns File contents, or null if the file doesn't exist or can't be read
 */
export declare function sessionFileRead(ctx: SessionFsContext, filePath: string, sandboxManager: SandboxManager | null): Promise<string | null>;
/**
 * Copy a file from `srcPath` to `dstPath`, dispatched on whether the source
 * and destination sessions are sandboxed.
 *
 *   src \ dst | non-sandboxed                 | sandboxed (same project)
 *   ──────────┼───────────────────────────────┼──────────────────────────
 *   non-sb    | host fs.copyFileSync          | CrossRealmCopyError
 *   sandboxed | CrossRealmCopyError           | docker exec cp
 *
 * Cross-realm and cross-project copies throw `CrossRealmCopyError`. Same-
 * realm copies create the destination directory (host-side or via
 * `docker exec mkdir -p`) before copying.
 */
export declare function sessionFileCopy(srcCtx: SessionFsContext, srcPath: string, dstCtx: SessionFsContext, dstPath: string, sandboxManager: SandboxManager | null): Promise<void>;
/**
 * Delete a file at the given path.
 *
 * For sandboxed sessions, tries `docker exec rm` first. If the container
 * is unavailable, falls back to deleting from the host via bind-mount
 * path translation.
 *
 * For non-sandboxed sessions, deletes from the host filesystem directly.
 *
 * @param ctx - Session context (sandboxed flag and project ID)
 * @param filePath - Path in the agent's coordinate system
 * @param sandboxManager - Sandbox manager instance (may be null)
 * @returns true if the file was deleted (or didn't exist), false on error
 */
export declare function sessionFileDelete(ctx: SessionFsContext, filePath: string, sandboxManager: SandboxManager | null): Promise<boolean>;
//# sourceMappingURL=session-fs.d.ts.map