/**
 * Sandbox class for interacting with a specific sandbox instance.
 */
import type { AccessDelegation } from "./access_delegation.js";
import type { CaptureSnapshotOptions, DownloadURL, ExecutionResult, FileChunk, FileStat, GenerateDownloadURLOptions, GlobOptions, GlobResult, GrepOptions, GrepResult, ReadRangeOptions, RunConfig, RunOptions, Snapshot, StartSandboxOptions } from "./types.js";
import { CommandHandle } from "./command_handle.js";
/**
 * Represents an active sandbox for running commands and file operations.
 *
 * This class is typically obtained from SandboxClient.createSandbox() and
 * provides methods for command execution and file I/O within the sandbox
 * environment.
 *
 * @example
 * ```typescript
 * const sandbox = await client.createSandbox(snapshot.id);
 * try {
 *   const result = await sandbox.run("python --version");
 *   console.log(result.stdout);
 * } finally {
 *   await sandbox.delete();
 * }
 * ```
 */
export declare class Sandbox {
    /** Display name (can be updated). */
    readonly name: string;
    /** URL for data plane operations (file I/O, command execution). */
    dataplane_url?: string;
    /** Provisioning status ("provisioning", "ready", "failed", "stopped"). */
    status?: string;
    /** Human-readable status message (e.g., error details when failed). */
    readonly status_message?: string;
    /** Unique identifier (UUID). Remains constant even if name changes. */
    readonly id?: string;
    /** Timestamp when the sandbox was created. */
    readonly created_at?: string;
    /** Timestamp when the sandbox was last updated. */
    readonly updated_at?: string;
    /**
     * Idle timeout TTL in seconds (`0` means disabled).
     * New sandboxes receive a server-side default of `600` seconds (10 minutes)
     * when the caller did not set `idleTtlSeconds` explicitly. The launcher
     * stops the sandbox after this many idle seconds.
     */
    readonly idle_ttl_seconds?: number;
    /**
     * Seconds after the sandbox enters the `stopped` state before it (and
     * its filesystem clone) are permanently deleted (`0` means disabled).
     */
    readonly delete_after_stop_seconds?: number;
    /**
     * Timestamp when the sandbox transitioned to `stopped`, or `undefined`
     * while running. The deletion deadline is
     * `stopped_at + delete_after_stop_seconds`.
     */
    readonly stopped_at?: string;
    /** Snapshot ID used to create this sandbox. */
    readonly snapshot_id?: string;
    /** Number of vCPUs allocated. */
    readonly vCpus?: number;
    /** Memory allocation in bytes. */
    readonly mem_bytes?: number;
    /** Root filesystem capacity in bytes. */
    readonly fs_capacity_bytes?: number;
    /**
     * User, working directory and environment this sandbox's commands run
     * with. Absent on sandboxes created before the server recorded it.
     */
    readonly run_config?: RunConfig;
    /**
     * LangSmith access granted to code inside the sandbox, or undefined when it
     * has none.
     */
    readonly access_delegation?: AccessDelegation;
    private _client;
    /**
     * Return the dataplane URL.
     *
     * The client does not gate on lifecycle status: a stopped sandbox is resumed
     * by the platform when the dataplane request arrives, so only the presence of
     * a URL is required here. A genuinely not-ready box surfaces the server's
     * LangSmithSandboxNotReadyError from the request itself.
     *
     * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
     */
    private requireDataplaneUrl;
    /**
     * Execute a command in the sandbox.
     *
     * When `wait` is true (default) and no streaming callbacks are provided,
     * uses WebSocket, falling back to HTTP POST only when the optional `ws`
     * package isn't installed.
     *
     * When `wait` is false or streaming callbacks are provided, uses WebSocket
     * (required). Returns a CommandHandle for streaming output.
     *
     * @param command - Shell command to execute.
     * @param options - Execution options.
     * @returns ExecutionResult when wait=true, CommandHandle when wait=false.
     *
     * @example
     * ```typescript
     * // Blocking (default)
     * const result = await sandbox.run("echo hello");
     * console.log(result.stdout);
     *
     * // Streaming with callbacks
     * const result = await sandbox.run("make build", {
     *   onStdout: (data) => process.stdout.write(data),
     * });
     *
     * // Non-blocking with CommandHandle
     * const handle = await sandbox.run("make build", { wait: false });
     * for await (const chunk of handle) {
     *   process.stdout.write(chunk.data);
     * }
     * const result = await handle.result;
     * ```
     */
    run(command: string, options: RunOptions & {
        wait: false;
    }): Promise<CommandHandle>;
    run(command: string, options?: RunOptions & {
        wait?: true;
    }): Promise<ExecutionResult>;
    run(command: string, options?: RunOptions): Promise<ExecutionResult | CommandHandle>;
    /**
     * Reconnect to a running command by its command ID.
     *
     * Returns a new CommandHandle that resumes output from the given offsets.
     *
     * @param commandId - The server-assigned command ID.
     * @param options - Reconnection options with byte offsets.
     * @returns A new CommandHandle.
     */
    reconnect(commandId: string, options?: {
        stdoutOffset?: number;
        stderrOffset?: number;
        stdinClosed?: boolean;
        pty?: boolean;
    }): Promise<CommandHandle>;
    /**
     * Write content to a file in the sandbox.
     *
     * @param path - Target file path in the sandbox.
     * @param content - File content (string or bytes).
     * @param timeout - Request timeout in seconds.
     *
     * @example
     * ```typescript
     * await sandbox.write("/tmp/script.py", 'print("Hello!")');
     * ```
     */
    write(path: string, content: string | Uint8Array, timeout?: number): Promise<void>;
    /**
     * Read a file from the sandbox.
     *
     * @param path - File path to read.
     * @param timeout - Request timeout in seconds.
     * @returns File contents as Uint8Array.
     *
     * @example
     * ```typescript
     * const content = await sandbox.read("/tmp/output.txt");
     * const text = new TextDecoder().decode(content);
     * console.log(text);
     * ```
     */
    read(path: string, timeout?: number): Promise<Uint8Array>;
    /**
     * Report a file's size and validators without transferring it.
     *
     * @param path - File path to stat.
     * @param timeout - Request timeout in seconds.
     * @returns The size and the `ETag` to pass to {@link readRange}.
     */
    stat(path: string, timeout?: number): Promise<FileStat>;
    /**
     * Read part of a file, for chunked reads and resumed downloads.
     *
     * @param path - File path to read.
     * @param options - The byte range, plus optional `ifRange`/`ifNoneMatch`
     *   validators. A 200 answer to a ranged request means the file changed and
     *   the server sent it whole -- restart rather than append.
     * @returns The bytes and where they sit in the file.
     *
     * @example
     * ```typescript
     * const head = await sandbox.readRange("/big.bin", { start: 0, end: 1023 });
     * const next = await sandbox.readRange("/big.bin", {
     *   start: head.end ?? 1024,
     *   ifRange: head.etag,
     * });
     * ```
     */
    readRange(path: string, options: ReadRangeOptions): Promise<FileChunk>;
    /**
     * Find files and directories matching a pattern.
     *
     * @param pattern - Match against each entry's path relative to `path`.
     *   Supports `**` for any number of segments plus `*`, `?` and `[...]`
     *   within one segment.
     * @param path - Absolute path of the directory to search under.
     * @param options - Result cap and request options.
     * @returns The matches; check `truncated` before treating them as complete.
     */
    glob(pattern: string, path: string, options?: GlobOptions): Promise<GlobResult>;
    /**
     * List a directory's immediate entries, without recursing.
     *
     * A convenience over {@link glob} with the pattern `*`.
     *
     * @param path - Absolute path of the directory to list.
     * @param options - Result cap and request options.
     * @returns The directory's files and subdirectories.
     */
    ls(path: string, options?: GlobOptions): Promise<GlobResult>;
    /**
     * Search file contents for a literal string.
     *
     * @param pattern - Literal text to search for. Not a regular expression.
     * @param path - Absolute path of the directory to search under.
     * @param options - Optional `glob` file filter, result cap, request options.
     * @returns The matching lines; check `truncated` for completeness.
     */
    grep(pattern: string, path: string, options?: GrepOptions): Promise<GrepResult>;
    /**
     * Create a link that downloads one file from this sandbox.
     *
     * The link carries its own token, so anyone holding the URL can fetch that
     * one file without a LangSmith credential. Fetching wakes a stopped sandbox.
     *
     * Do not modify the file after minting a link for it. The link is pinned to
     * a path, not to a snapshot of the contents, so a later write to that path
     * may or may not be reflected in what the link serves. Write a new file and
     * mint a new link when the contents change.
     *
     * @param path - File path inside the sandbox.
     * @param options - Expiry and response header overrides.
     * @returns The link and its expiry, if any.
     *
     * @example
     * ```typescript
     * const link = await sandbox.generateDownloadURL("/tmp/report.pdf", {
     *   expiresInSeconds: 3600,
     * });
     * console.log(link.download_url);
     * ```
     */
    generateDownloadURL(path: string, options?: GenerateDownloadURLOptions): Promise<DownloadURL>;
    /**
     * Delete this sandbox.
     *
     * @example
     * ```typescript
     * const sandbox = await client.createSandbox(snapshot.id);
     * try {
     *   await sandbox.run("echo hello");
     * } finally {
     *   await sandbox.delete();
     * }
     * ```
     */
    delete(): Promise<void>;
    /**
     * Start a stopped sandbox and wait until ready.
     *
     * Updates this sandbox's status and dataplane_url in place.
     *
     * @param timeout - Timeout in seconds when waiting for ready. Default: 120.
     */
    start(options?: StartSandboxOptions): Promise<void>;
    /**
     * Stop a running sandbox (preserves sandbox files for later restart).
     */
    stop(): Promise<void>;
    /**
     * Capture a snapshot from this sandbox.
     *
     * @param name - Snapshot name.
     * @param options - Capture options (timeout).
     * @returns Snapshot in "ready" status.
     */
    captureSnapshot(name: string, options?: CaptureSnapshotOptions): Promise<Snapshot>;
}