"""Sandbox class for interacting with a specific sandbox instance."""

from __future__ import annotations

from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any, Callable, Literal, Optional, Union, overload

from langsmith._openapi_client._httpx import httpx
from langsmith.sandbox._access_delegation import (
    AccessDelegation,
    _access_delegation_from_dict,
)
from langsmith.sandbox._exceptions import (
    DataplaneNotConfiguredError,
    ResourceNotFoundError,
    SandboxRetryableConnectionError,
)
from langsmith.sandbox._helpers import (
    build_range_header as _build_range_header,
)
from langsmith.sandbox._helpers import (
    file_chunk_from_response as _file_chunk_from_response,
)
from langsmith.sandbox._helpers import (
    file_stat_from_response as _file_stat_from_response,
)
from langsmith.sandbox._helpers import (
    handle_sandbox_http_error,
)
from langsmith.sandbox._helpers import (
    raise_file_http_error as _raise_file_http_error,
)
from langsmith.sandbox._helpers import (
    resolve_close_input as _resolve_close_input,
)
from langsmith.sandbox._helpers import (
    resolve_command_run_config as _resolve_command_run_config,
)
from langsmith.sandbox._models import (
    CommandHandle,
    DownloadContentDisposition,
    DownloadURL,
    ExecutionResult,
    FileChunk,
    FileStat,
    GlobResult,
    GrepResult,
    RunConfig,
    ServiceURL,
    Snapshot,
    _run_config_from_dict,
    _StreamEndedBeforeStarted,
)
from langsmith.sandbox._sse_execute import (
    MISSING_TRANSPORT_MSG,
    require_sse_supports,
    resume_sse_stream,
    run_sse_stream,
    sse_transport_selected,
)
from langsmith.sandbox._sse_execute import (
    start_payload as _sse_start_payload,
)
from langsmith.sandbox._tracing import add_sandbox_metadata
from langsmith.sandbox._tunnel import Tunnel
from langsmith.sandbox._ws_execute import (
    WEBSOCKETS_AVAILABLE,
    _retry_delay,
    connect_deadline,
    open_timeout_for,
)

if TYPE_CHECKING:
    from langsmith.sandbox._async_client import AsyncSandboxClient
    from langsmith.sandbox._async_sandbox import AsyncSandbox
    from langsmith.sandbox._client import SandboxClient


RequestHeaders = Optional[Mapping[str, str]]


@dataclass
class Sandbox:
    """Represents an active sandbox for running commands and file operations.

    This class is typically obtained from SandboxClient.sandbox() and supports
    the context manager protocol for automatic cleanup.

    Attributes:
        name: Display name (can be updated).
        dataplane_url: URL for data plane operations (file I/O, command execution).
            Only functional when status is "ready".
        id: Unique identifier (UUID). Remains constant even if name changes.
            May be None for resources created before ID support was added.
        status: Sandbox lifecycle status. One of "provisioning", "ready",
            "failed", "stopped".
        status_message: Human-readable details when status is "failed", None otherwise.
        created_at: Timestamp when the sandbox was created.
        updated_at: Timestamp when the sandbox was last updated.
        idle_ttl_seconds: Idle timeout TTL in seconds (``0`` means disabled).
            Newly-created sandboxes receive a server-side default of ``600``
            seconds (10 minutes) when the caller did not set ``idle_ttl_seconds``
            explicitly. The launcher stops the sandbox after this many idle
            seconds; deletion is anchored to ``stopped_at`` and controlled by
            ``delete_after_stop_seconds`` (see below).
        delete_after_stop_seconds: Seconds after a sandbox enters the
            ``stopped`` state before it (and its filesystem clone) are
            permanently deleted. ``0`` disables stop-anchored deletion;
            ``None`` falls back to the server default.
        stopped_at: Timestamp when the sandbox transitioned to ``stopped``,
            or ``None`` while running. The deletion deadline is
            ``stopped_at + delete_after_stop_seconds``.
        snapshot_id: Snapshot ID used to create this sandbox.
        vcpus: Number of vCPUs allocated.
        mem_bytes: Memory allocation in bytes.
        fs_capacity_bytes: Root filesystem capacity in bytes.
        run_config: User, working directory and environment the sandbox's
            commands run with. None on sandboxes created before the server
            recorded it.
        access_delegation: LangSmith access granted to code inside the sandbox,
            or None when it has none.

    Example:
        with client.sandbox(snapshot_id="<snapshot-uuid>") as sandbox:
            result = sandbox.run("python --version")
            print(result.stdout)
    """

    # Data fields (from API response)
    name: str
    dataplane_url: Optional[str] = None
    id: Optional[str] = None
    status: str = "ready"
    status_message: Optional[str] = None
    created_at: Optional[str] = None
    updated_at: Optional[str] = None
    idle_ttl_seconds: Optional[int] = None
    delete_after_stop_seconds: Optional[int] = None
    stopped_at: Optional[str] = None
    snapshot_id: Optional[str] = None
    vcpus: Optional[int] = None
    mem_bytes: Optional[int] = None
    fs_capacity_bytes: Optional[int] = None
    run_config: Optional[RunConfig] = None
    access_delegation: Optional[AccessDelegation] = None

    # Internal fields (not from API)
    _client: SandboxClient = field(repr=False, default=None)  # type: ignore
    _auto_delete: bool = field(repr=False, default=True)

    @classmethod
    def from_dict(
        cls,
        data: dict[str, Any],
        client: SandboxClient,
        auto_delete: bool = True,
    ) -> Sandbox:
        """Create a Sandbox from API response dict.

        Args:
            data: API response dictionary containing sandbox data.
            client: Parent SandboxClient for operations.
            auto_delete: Whether to delete the sandbox on context exit.

        Returns:
            Sandbox instance.
        """
        return cls(
            name=data.get("name", ""),
            dataplane_url=data.get("dataplane_url"),
            id=data.get("id"),
            status=data.get("status", "ready"),
            status_message=data.get("status_message"),
            created_at=data.get("created_at"),
            updated_at=data.get("updated_at"),
            idle_ttl_seconds=data.get("idle_ttl_seconds"),
            delete_after_stop_seconds=data.get("delete_after_stop_seconds"),
            stopped_at=data.get("stopped_at"),
            snapshot_id=data.get("snapshot_id"),
            vcpus=data.get("vcpus"),
            mem_bytes=data.get("mem_bytes"),
            fs_capacity_bytes=data.get("fs_capacity_bytes"),
            run_config=_run_config_from_dict(data.get("run_config")),
            access_delegation=_access_delegation_from_dict(
                data.get("access_delegation")
            ),
            _client=client,
            _auto_delete=auto_delete,
        )

    def to_async(self, *, client: Optional[AsyncSandboxClient] = None) -> AsyncSandbox:
        """Create an AsyncSandbox for the same underlying sandbox.

        The returned instance has ``auto_delete`` disabled so the sandbox's
        lifecycle stays tied to this instance; both refer to the same
        server-side sandbox.

        Args:
            client: AsyncSandboxClient to use for operations. If not provided,
                one is created with the same configuration as this sandbox's
                client (see :meth:`SandboxClient.to_async`).

        Returns:
            AsyncSandbox referring to the same sandbox.
        """
        from langsmith.sandbox._async_sandbox import AsyncSandbox

        return AsyncSandbox(
            name=self.name,
            dataplane_url=self.dataplane_url,
            id=self.id,
            status=self.status,
            status_message=self.status_message,
            created_at=self.created_at,
            updated_at=self.updated_at,
            idle_ttl_seconds=self.idle_ttl_seconds,
            delete_after_stop_seconds=self.delete_after_stop_seconds,
            stopped_at=self.stopped_at,
            snapshot_id=self.snapshot_id,
            vcpus=self.vcpus,
            mem_bytes=self.mem_bytes,
            fs_capacity_bytes=self.fs_capacity_bytes,
            run_config=self.run_config,
            access_delegation=self.access_delegation,
            _client=client if client is not None else self._client.to_async(),
            _auto_delete=False,
        )

    def __enter__(self) -> Sandbox:
        """Enter context manager."""
        add_sandbox_metadata(self.id)
        return self

    def __exit__(
        self,
        exc_type: Optional[type],
        exc_val: Optional[BaseException],
        exc_tb: Optional[Any],
    ) -> None:
        """Exit context manager, optionally deleting the sandbox."""
        add_sandbox_metadata(self.id)
        if self._auto_delete:
            try:
                self._client.delete_sandbox(self.name)
            except Exception:
                # Don't raise on cleanup errors
                pass

    def _require_dataplane_url(self) -> str:
        """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 ``SandboxNotReadyError`` from the request itself.

        Returns:
            The dataplane URL.

        Raises:
            DataplaneNotConfiguredError: If dataplane_url is not configured.
        """
        add_sandbox_metadata(self.id)
        if not self.dataplane_url:
            raise DataplaneNotConfiguredError(
                f"Sandbox '{self.name}' does not have a dataplane_url configured. "
                "Runtime operations require a dataplane URL."
            )
        return self.dataplane_url

    @overload
    def run(
        self,
        command: str,
        *,
        timeout: int = ...,
        env: Optional[dict[str, str]] = ...,
        cwd: Optional[str] = ...,
        run_config: Optional[Union[RunConfig, dict[str, Any]]] = ...,
        close_input: Optional[bool] = ...,
        shell: str = ...,
        on_stdout: Optional[Callable[[str], Any]] = ...,
        on_stderr: Optional[Callable[[str], Any]] = ...,
        idle_timeout: int = ...,
        kill_on_disconnect: bool = ...,
        ttl_seconds: int = ...,
        pty: bool = ...,
        headers: RequestHeaders = ...,
        wait: Literal[True] = ...,
    ) -> ExecutionResult: ...

    @overload
    def run(
        self,
        command: str,
        *,
        timeout: int = ...,
        env: Optional[dict[str, str]] = ...,
        cwd: Optional[str] = ...,
        run_config: Optional[Union[RunConfig, dict[str, Any]]] = ...,
        close_input: Optional[bool] = ...,
        shell: str = ...,
        on_stdout: Optional[Callable[[str], Any]] = ...,
        on_stderr: Optional[Callable[[str], Any]] = ...,
        idle_timeout: int = ...,
        kill_on_disconnect: bool = ...,
        ttl_seconds: int = ...,
        pty: bool = ...,
        headers: RequestHeaders = ...,
        wait: Literal[False],
    ) -> CommandHandle: ...

    def run(
        self,
        command: str,
        *,
        timeout: int = 60,
        env: Optional[dict[str, str]] = None,
        cwd: Optional[str] = None,
        run_config: Optional[Union[RunConfig, dict[str, Any]]] = None,
        close_input: Optional[bool] = None,
        shell: str = "/bin/bash",
        on_stdout: Optional[Callable[[str], Any]] = None,
        on_stderr: Optional[Callable[[str], Any]] = None,
        idle_timeout: int = 300,
        kill_on_disconnect: bool = False,
        ttl_seconds: int = 600,
        pty: bool = False,
        headers: RequestHeaders = None,
        wait: bool = True,
    ) -> Union[ExecutionResult, CommandHandle]:
        """Execute a command in the sandbox.

        Args:
            command: Shell command to execute.
            timeout: Command timeout in seconds.
            env: Environment variables to set for the command. Deprecated in
                favour of ``run_config.env_vars``; the two cannot be combined.
            cwd: Working directory for command execution. If None, uses sandbox
                default. Deprecated in favour of ``run_config.work_dir``; the
                two cannot be combined.
            run_config: User, working directory and environment for this one
                command, layered over the sandbox's own. Accepts a
                :class:`RunConfig` or a plain dict.
            close_input: Half-close the command's stdin so a command that
                reads it sees EOF rather than blocking until the timeout.
                Defaults to True for a non-PTY command, which means
                ``send_input()`` on the returned handle raises unless this is
                set to False. Ignored under ``pty=True``, where input and
                output share one terminal file descriptor -- send an EOT byte
                (``0x04``) as input instead.
            shell: Shell to use for command execution. Defaults to "/bin/bash".
            on_stdout: Callback invoked with each stdout chunk as it arrives.
                Blocks until the command completes and returns ExecutionResult.
                Cannot be combined with wait=False.
            on_stderr: Callback invoked with each stderr chunk as it arrives.
                Blocks until the command completes and returns ExecutionResult.
                Cannot be combined with wait=False.
            idle_timeout: Idle timeout in seconds. If the command has no
                connected clients for this duration, it is killed. Defaults
                to 300 (5 minutes). Set to -1 for no idle timeout.
                Only applies to WebSocket execution.
            kill_on_disconnect: If True, kill the command immediately when
                the last client disconnects. Defaults to False (command
                continues running and can be reconnected to).
            ttl_seconds: How long (in seconds) a finished command's session
                is kept for reconnection. Defaults to 600 (10 minutes).
                Set to -1 to keep indefinitely.
            pty: If True, allocate a pseudo-terminal for the command.
                Useful for commands that require a TTY (e.g., interactive
                programs, commands that use terminal control codes).
                Defaults to False.
            wait: If True (default), block until the command completes and
                return ExecutionResult. If False, return a
                CommandHandle immediately for streaming output,
                kill, stdin input, and reconnection. Cannot be combined with
                on_stdout/on_stderr callbacks.

        Returns:
            ExecutionResult when wait=True (default).
            CommandHandle when wait=False.

        Raises:
            ValueError: If wait=False is combined with callbacks.
            DataplaneNotConfiguredError: If dataplane_url is not configured.
            SandboxOperationError: If command execution fails.
            CommandTimeoutError: If command exceeds its timeout.
            SandboxConnectionError: If connection to sandbox fails after retries.
            SandboxNotReadyError: If sandbox is not ready.
            SandboxClientError: For other errors.
        """
        if not wait and (on_stdout or on_stderr):
            raise ValueError(
                "Cannot combine wait=False with on_stdout/on_stderr callbacks. "
                "Use wait=False and iterate the CommandHandle, or use callbacks."
            )
        resolved_run_config = _resolve_command_run_config(run_config, env=env, cwd=cwd)
        close_stdin = _resolve_close_input(close_input, pty=pty)

        self._require_dataplane_url()

        if sse_transport_selected():
            runner = self._run_sse
        elif WEBSOCKETS_AVAILABLE:
            runner = self._run_ws
        else:
            raise ImportError(MISSING_TRANSPORT_MSG)
        return runner(
            command,
            timeout=timeout,
            env=env,
            cwd=cwd,
            run_config=resolved_run_config,
            close_stdin=close_stdin,
            shell=shell,
            wait=wait,
            on_stdout=on_stdout,
            on_stderr=on_stderr,
            idle_timeout=idle_timeout,
            kill_on_disconnect=kill_on_disconnect,
            ttl_seconds=ttl_seconds,
            pty=pty,
            headers=headers,
        )

    def _run_ws(
        self,
        command: str,
        *,
        timeout: int,
        env: Optional[dict[str, str]],
        cwd: Optional[str],
        run_config: Optional[dict[str, Any]],
        close_stdin: bool,
        shell: str,
        wait: bool,
        on_stdout: Optional[Callable[[str], Any]],
        on_stderr: Optional[Callable[[str], Any]],
        idle_timeout: int = 300,
        kill_on_disconnect: bool = False,
        ttl_seconds: int = 600,
        pty: bool = False,
        headers: RequestHeaders = None,
    ) -> Union[ExecutionResult, CommandHandle]:
        """Execute via WebSocket /execute/ws."""
        import time

        from langsmith.sandbox._ws_execute import run_ws_stream
        from langsmith.uuid import uuid7

        dataplane_url = self._require_dataplane_url()
        api_key = self._client._api_key

        # A client-supplied command_id makes execute idempotent: the daemon does
        # get-or-create keyed on it, so if the tunnel closes before "started" we
        # can re-issue the same id and reattach to the existing command instead
        # of spawning a second one.
        command_id = uuid7().hex

        ws_kwargs: dict[str, Any] = {
            "command_id": command_id,
            "timeout": timeout,
            "env": env,
            "cwd": cwd,
            "shell": shell,
            "idle_timeout": idle_timeout,
            "kill_on_disconnect": kill_on_disconnect,
            "ttl_seconds": ttl_seconds,
            "pty": pty,
        }
        if run_config is not None:
            ws_kwargs["run_config"] = run_config
        if close_stdin:
            ws_kwargs["close_stdin"] = True
        merged = self._client._ws_default_headers(headers)
        if merged:
            ws_kwargs["headers"] = merged

        attempt = 0
        deadline = connect_deadline()
        while True:
            ws_kwargs["open_timeout"] = open_timeout_for(deadline)
            msg_stream, control = run_ws_stream(
                dataplane_url,
                api_key,
                command,
                **ws_kwargs,
            )
            try:
                handle = CommandHandle(
                    msg_stream,
                    control,
                    self,
                    on_stdout=on_stdout,
                    on_stderr=on_stderr,
                    stdin_closed=close_stdin,
                    pty=pty,
                )
                break
            except (
                _StreamEndedBeforeStarted,
                SandboxRetryableConnectionError,
            ) as exc:
                # Idempotent re-issue (same command_id): neither an early close
                # nor a failed connect can have started a second command.
                attempt += 1
                if attempt > CommandHandle.MAX_AUTO_RECONNECTS:
                    raise
                backoff = min(
                    CommandHandle._BACKOFF_BASE * (2 ** (attempt - 1)),
                    CommandHandle._BACKOFF_MAX,
                )
                if isinstance(exc, SandboxRetryableConnectionError):
                    backoff = _retry_delay(exc, backoff)
                if deadline is not None:
                    remaining = deadline - time.monotonic()
                    if remaining <= 0:
                        raise
                    backoff = min(backoff, remaining)
                time.sleep(backoff)

        if not wait:
            return handle

        return handle.result  # blocks until command completes

    def _run_sse(
        self,
        command: str,
        *,
        timeout: int,
        env: Optional[dict[str, str]],
        cwd: Optional[str],
        run_config: Optional[dict[str, Any]],
        close_stdin: bool,
        shell: str,
        wait: bool,
        on_stdout: Optional[Callable[[str], Any]],
        on_stderr: Optional[Callable[[str], Any]],
        idle_timeout: int = 300,
        kill_on_disconnect: bool = False,
        ttl_seconds: int = 600,
        pty: bool = False,
        headers: RequestHeaders = None,
    ) -> Union[ExecutionResult, CommandHandle]:
        """Execute via the SSE endpoints /execute/stream/{start,resume}."""
        from langsmith.uuid import uuid7

        require_sse_supports(
            pty=pty, close_stdin=close_stdin, kill_on_disconnect=kill_on_disconnect
        )
        dataplane_url = self._require_dataplane_url()

        # A client-supplied command_id makes start idempotent: the daemon does
        # get-or-create keyed on it, so a request that failed before "started"
        # is re-sent rather than spawning a second command.
        payload = _sse_start_payload(
            command,
            command_id=uuid7().hex,
            timeout=timeout,
            shell=shell,
            idle_timeout=idle_timeout,
            ttl_seconds=ttl_seconds,
            env=env,
            cwd=cwd,
            run_config=run_config,
        )
        msg_stream, control = run_sse_stream(
            self._client._http,
            dataplane_url,
            payload,
            headers=self._client._request_headers(headers),
        )
        handle = CommandHandle(
            msg_stream,
            control,
            self,
            on_stdout=on_stdout,
            on_stderr=on_stderr,
            stdin_closed=True,
        )
        if not wait:
            return handle
        return handle.result

    def reconnect(
        self,
        command_id: str,
        *,
        stdout_offset: int = 0,
        stderr_offset: int = 0,
        stdin_closed: bool = False,
        pty: bool = False,
        headers: RequestHeaders = None,
    ) -> CommandHandle:
        """Reconnect to a running or recently-finished command.

        Resumes output from the given byte offsets. Any output produced while
        the client was disconnected is replayed from the server's ring buffer.

        Args:
            command_id: The command ID from handle.command_id.
            stdout_offset: Byte offset to resume stdout from (default: 0).
            stderr_offset: Byte offset to resume stderr from (default: 0).

        Returns:
            A CommandHandle for the command.

        Raises:
            SandboxOperationError: If command_id is not found or session expired.
            SandboxConnectionError: If connection to sandbox fails after retries.
        """
        from langsmith.sandbox._ws_execute import reconnect_ws_stream

        dataplane_url = self._require_dataplane_url()

        if sse_transport_selected():
            msg_stream, control = resume_sse_stream(
                self._client._http,
                dataplane_url,
                command_id,
                stdout_offset=stdout_offset,
                stderr_offset=stderr_offset,
                headers=self._client._request_headers(headers),
            )
            return CommandHandle(
                msg_stream,
                control,
                self,
                command_id=command_id,
                stdout_offset=stdout_offset,
                stderr_offset=stderr_offset,
                stdin_closed=True,
            )

        reconnect_kwargs: dict[str, Any] = {
            "stdout_offset": stdout_offset,
            "stderr_offset": stderr_offset,
        }
        merged = self._client._ws_default_headers(headers)
        if merged:
            reconnect_kwargs["headers"] = merged

        ws_stream, ws_control = reconnect_ws_stream(
            dataplane_url,
            self._client._api_key,
            command_id,
            **reconnect_kwargs,
        )

        return CommandHandle(
            ws_stream,
            ws_control,
            self,
            command_id=command_id,
            stdout_offset=stdout_offset,
            stderr_offset=stderr_offset,
            stdin_closed=stdin_closed,
            pty=pty,
        )

    def write(
        self,
        path: str,
        content: Union[str, bytes],
        *,
        timeout: int = 60,
        headers: RequestHeaders = None,
    ) -> None:
        """Write content to a file in the sandbox.

        Args:
            path: Target file path in the sandbox.
            content: File content (str or bytes).
            timeout: Request timeout in seconds.

        Raises:
            DataplaneNotConfiguredError: If dataplane_url is not configured.
            SandboxOperationError: If file write fails.
            SandboxConnectionError: If connection to sandbox fails after retries.
            SandboxNotReadyError: If sandbox is not ready.
            SandboxClientError: For other errors.
        """
        dataplane_url = self._require_dataplane_url()
        url = f"{dataplane_url}/upload"

        # Ensure content is bytes for multipart upload
        if isinstance(content, str):
            content = content.encode("utf-8")

        files = {"file": ("file", content)}

        try:
            response = self._client._http.post(
                url,
                params={"path": path},
                files=files,
                timeout=timeout,
                headers=self._client._request_headers(headers),
            )
            response.raise_for_status()
        except httpx.HTTPStatusError as e:
            handle_sandbox_http_error(e)

    def read(
        self, path: str, *, timeout: int = 60, headers: RequestHeaders = None
    ) -> bytes:
        """Read a file from the sandbox.

        Args:
            path: File path to read. Supports both absolute paths (e.g., /tmp/file.txt)
                  and relative paths (resolved from /home/user/).
            timeout: Request timeout in seconds.

        Returns:
            File contents as bytes.

        Raises:
            DataplaneNotConfiguredError: If dataplane_url is not configured.
            ResourceNotFoundError: If the file doesn't exist.
            SandboxOperationError: If file read fails.
            SandboxConnectionError: If connection to sandbox fails after retries.
            SandboxNotReadyError: If sandbox is not ready.
            SandboxClientError: For other errors.
        """
        dataplane_url = self._require_dataplane_url()
        url = f"{dataplane_url}/download"

        try:
            response = self._client._http.get(
                url,
                params={"path": path},
                timeout=timeout,
                headers=self._client._request_headers(headers),
            )
            response.raise_for_status()
            return response.content
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 404:
                raise ResourceNotFoundError(
                    f"File '{path}' not found in sandbox '{self.name}'",
                    resource_type="file",
                ) from e
            handle_sandbox_http_error(e)
            # This line should never be reached but satisfies type checker
            raise  # pragma: no cover

    def stat(
        self, path: str, *, timeout: int = 60, headers: RequestHeaders = None
    ) -> FileStat:
        """Report a file's size and validators without transferring it.

        Args:
            path: File path to stat.
            timeout: Request timeout in seconds.
            headers: Extra request headers.

        Returns:
            FileStat with the size and the ``ETag`` to pass to
            :meth:`read_range`.

        Raises:
            ResourceNotFoundError: If the file doesn't exist.
        """
        dataplane_url = self._require_dataplane_url()
        try:
            response = self._client._http.request(
                "HEAD",
                f"{dataplane_url}/download",
                params={"path": path},
                timeout=timeout,
                headers=self._client._request_headers(headers),
            )
            response.raise_for_status()
        except httpx.HTTPStatusError as e:
            _raise_file_http_error(e, path=path, sandbox_name=self.name)
            raise  # pragma: no cover
        return _file_stat_from_response(response)

    def read_range(
        self,
        path: str,
        *,
        start: Optional[int] = None,
        end: Optional[int] = None,
        suffix_bytes: Optional[int] = None,
        if_range: Optional[str] = None,
        if_none_match: Optional[str] = None,
        timeout: int = 60,
        headers: RequestHeaders = None,
    ) -> FileChunk:
        """Read part of a file, for chunked reads and resumed downloads.

        Args:
            path: File path to read.
            start: First byte to return. With ``end``, an inclusive range.
            end: Last byte to return, inclusive. Clamped to EOF rather than
                rejected.
            suffix_bytes: Return the last N bytes. Mutually exclusive with
                ``start``/``end``.
            if_range: An ``ETag`` from an earlier chunk. The range is honored
                only while the file still matches it; a rewrite answers 200
                with the whole file, reported as ``partial=False`` so a
                resuming caller restarts instead of splicing two versions.
            if_none_match: An ``ETag`` the caller already holds. An unchanged
                file answers with ``unchanged=True`` and no bytes.
            timeout: Request timeout in seconds.
            headers: Extra request headers.

        Returns:
            FileChunk with the bytes and where they sit in the file.

        Raises:
            ValueError: If no range is given, or suffix_bytes is combined
                with start/end.
            SandboxOperationError: If the range starts past the end of the
                file (416).
            ResourceNotFoundError: If the file doesn't exist.
        """
        range_header = _build_range_header(
            start=start, end=end, suffix_bytes=suffix_bytes
        )
        request_headers = dict(self._client._request_headers(headers) or {})
        request_headers["Range"] = range_header
        if if_range:
            request_headers["If-Range"] = if_range
        if if_none_match:
            request_headers["If-None-Match"] = if_none_match

        dataplane_url = self._require_dataplane_url()
        try:
            response = self._client._http.get(
                f"{dataplane_url}/download",
                params={"path": path},
                timeout=timeout,
                headers=request_headers,
            )
            if response.status_code != 304:
                response.raise_for_status()
        except httpx.HTTPStatusError as e:
            _raise_file_http_error(e, path=path, sandbox_name=self.name)
            raise  # pragma: no cover
        return _file_chunk_from_response(response)

    def glob(
        self,
        pattern: str,
        path: str,
        *,
        limit: Optional[int] = None,
        timeout: int = 60,
        headers: RequestHeaders = None,
    ) -> GlobResult:
        """Find files and directories matching a pattern.

        Args:
            pattern: Match against each entry's path relative to ``path``.
                Supports ``**`` for any number of segments plus ``*``, ``?``
                and ``[...]`` within one segment.
            path: Absolute path of the directory to search under.
            limit: Maximum matches to return.
            timeout: Request timeout in seconds.
            headers: Extra request headers.

        Returns:
            GlobResult; check ``truncated`` before treating it as complete.
        """
        payload: dict[str, Any] = {"pattern": pattern, "path": path}
        if limit is not None:
            payload["limit"] = limit
        data = self._file_search("glob", payload, timeout=timeout, headers=headers)
        return GlobResult.from_dict(data)

    def ls(
        self,
        path: str,
        *,
        limit: Optional[int] = None,
        timeout: int = 60,
        headers: RequestHeaders = None,
    ) -> GlobResult:
        """List a directory's immediate entries, without recursing.

        A convenience over :meth:`glob` with the pattern ``*``.

        Args:
            path: Absolute path of the directory to list.
            limit: Maximum entries to return.
            timeout: Request timeout in seconds.
            headers: Extra request headers.

        Returns:
            GlobResult holding the directory's files and subdirectories.
        """
        return self.glob("*", path, limit=limit, timeout=timeout, headers=headers)

    def grep(
        self,
        pattern: str,
        path: str,
        *,
        glob: Optional[str] = None,
        limit: Optional[int] = None,
        timeout: int = 60,
        headers: RequestHeaders = None,
    ) -> GrepResult:
        """Search file contents for a literal string.

        Args:
            pattern: Literal text to search for. Not a regular expression.
            path: Absolute path of the directory to search under.
            glob: Restrict which files are searched. A bare ``*.py`` matches
                by basename at any depth; a pattern containing ``/`` or
                ``**`` matches the path relative to ``path``.
            limit: Maximum matches to return.
            timeout: Request timeout in seconds.
            headers: Extra request headers.

        Returns:
            GrepResult; check ``truncated`` before treating it as complete.
        """
        payload: dict[str, Any] = {"pattern": pattern, "path": path}
        if glob is not None:
            payload["glob"] = glob
        if limit is not None:
            payload["limit"] = limit
        data = self._file_search("grep", payload, timeout=timeout, headers=headers)
        return GrepResult.from_dict(data)

    def _file_search(
        self,
        operation: str,
        payload: dict[str, Any],
        *,
        timeout: int,
        headers: RequestHeaders,
    ) -> dict[str, Any]:
        """POST one of the read-only filesystem search endpoints."""
        dataplane_url = self._require_dataplane_url()
        try:
            response = self._client._http.post(
                f"{dataplane_url}/{operation}",
                json=payload,
                timeout=timeout,
                headers=self._client._request_headers(headers),
            )
            response.raise_for_status()
        except httpx.HTTPStatusError as e:
            _raise_file_http_error(e, path=payload["path"], sandbox_name=self.name)
            raise  # pragma: no cover
        return response.json()

    def tunnel(
        self,
        remote_port: int,
        *,
        local_port: int = 0,
        max_reconnects: int = 3,
        headers: RequestHeaders = None,
    ) -> Tunnel:
        """Open a TCP tunnel to a port inside the sandbox.

        Creates a local TCP listener that forwards connections through a
        yamux-multiplexed WebSocket to the specified port inside the sandbox.
        Works with any TCP protocol (databases, Redis, HTTP, etc.).

        Use as a context manager for automatic cleanup::

            with sandbox.tunnel(remote_port=5432) as t:
                conn = psycopg2.connect(host="127.0.0.1", port=t.local_port)

        Or manage the lifecycle explicitly::

            t = sandbox.tunnel(remote_port=5432)
            # ... use tunnel ...
            t.close()

        Args:
            remote_port: TCP port inside the sandbox to tunnel to (1-65535).
            local_port: Local port to listen on. Defaults to mirroring
                remote_port. Use 0 to let the OS pick an available port.
            max_reconnects: Maximum number of automatic reconnect attempts
                when the WebSocket session drops. Set to 0 to disable.

        Returns:
            A Tunnel instance (context manager).

        Raises:
            ValueError: If port values are out of range.
            DataplaneNotConfiguredError: If dataplane_url is not configured.
            SandboxNotReadyError: If sandbox is not ready.
        """
        if not 1 <= remote_port <= 65535:
            raise ValueError(
                f"remote_port must be between 1 and 65535 (got {remote_port})"
            )
        if local_port and not 1 <= local_port <= 65535:
            raise ValueError(
                f"local_port must be between 1 and 65535 (got {local_port})"
            )
        dataplane_url = self._require_dataplane_url()
        api_key = self._client._api_key
        t = Tunnel(
            dataplane_url,
            api_key,
            remote_port,
            local_port=local_port,
            max_reconnects=max_reconnects,
            headers=headers,
        )
        t._start()
        return t

    def service(
        self,
        port: int,
        *,
        expires_in_seconds: int = 600,
        headers: RequestHeaders = None,
    ) -> ServiceURL:
        """Get an authenticated URL for a service running in this sandbox.

        Returns a :class:`ServiceURL` whose properties auto-refresh the
        token transparently before it expires.

        Args:
            port: Port the service is listening on inside the sandbox.
            expires_in_seconds: Token TTL in seconds (1--86400, default 600).
            headers: Optional per-request header overrides.

        Returns:
            ServiceURL with auto-refreshing token and HTTP helpers.

        Raises:
            ResourceNotFoundError: If sandbox not found.
            ValueError: If port or expires_in_seconds is out of range.
            SandboxClientError: For other errors.
        """
        add_sandbox_metadata(self.id)
        service = self._client.service(
            self.name,
            port,
            expires_in_seconds=expires_in_seconds,
            headers=headers,
        )
        service._sandbox_id = self.id
        return service

    def generate_download_url(
        self,
        path: str,
        *,
        expires_in_seconds: Optional[int] = None,
        content_type: Optional[str] = None,
        content_disposition: Optional[DownloadContentDisposition] = None,
        headers: RequestHeaders = None,
    ) -> DownloadURL:
        """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.

        Args:
            path: File path inside the sandbox.
            expires_in_seconds: Link TTL in seconds. Omit for a link that
                never expires.
            content_type: Content-Type to serve the file as.
            content_disposition: Content-Disposition to serve the file with,
                either ``"attachment"`` or ``"inline"``.
            headers: Optional per-request header overrides.

        Returns:
            DownloadURL with the link and its expiry, if any.

        Raises:
            ResourceNotFoundError: If sandbox not found.
            ValueError: If expires_in_seconds is not positive.
            SandboxClientError: For other errors.
        """
        add_sandbox_metadata(self.id)
        return self._client.generate_download_url(
            self.name,
            path,
            expires_in_seconds=expires_in_seconds,
            content_type=content_type,
            content_disposition=content_disposition,
            headers=headers,
        )

    def start(
        self,
        *,
        timeout: int = 120,
        headers: RequestHeaders = None,
    ) -> None:
        """Start a stopped sandbox and wait until ready.

        After starting, the sandbox's status and dataplane_url are updated
        in place.

        Args:
            timeout: Timeout in seconds when waiting for ready.
            headers: Optional per-request header overrides.

        Raises:
            ResourceNotFoundError: If sandbox not found.
            ResourceCreationError: If sandbox fails during startup.
            ResourceTimeoutError: If sandbox doesn't become ready within timeout.
            SandboxClientError: For other errors.
        """
        add_sandbox_metadata(self.id)
        refreshed = self._client.start_sandbox(
            self.name, timeout=timeout, headers=headers
        )
        self.status = refreshed.status
        self.dataplane_url = refreshed.dataplane_url

    def stop(self, *, headers: RequestHeaders = None) -> None:
        """Stop a running sandbox (preserves sandbox files for later restart).

        Args:
            headers: Optional per-request header overrides.

        Raises:
            ResourceNotFoundError: If sandbox not found.
            SandboxClientError: For other errors.
        """
        add_sandbox_metadata(self.id)
        self._client.stop_sandbox(self.name, headers=headers)
        # dataplane_url stays set: it is stable across stop/start and a request
        # on it resumes the sandbox.
        self.status = "stopped"

    def delete(self, *, headers: RequestHeaders = None) -> None:
        """Delete this sandbox.

        Args:
            headers: Optional per-request header overrides.

        Raises:
            ResourceNotFoundError: If sandbox not found.
            SandboxClientError: For other errors.
        """
        add_sandbox_metadata(self.id)
        self._client.delete_sandbox(self.name, headers=headers)

    def capture_snapshot(
        self,
        name: str,
        *,
        run_config: Optional[Union[RunConfig, dict[str, Any]]] = None,
        timeout: int = 60,
        headers: RequestHeaders = None,
    ) -> Snapshot:
        """Capture a snapshot from this sandbox.

        Args:
            name: Snapshot name.
            run_config: Override applied over the configuration this sandbox
                is running with: ``user`` and ``work_dir`` replace,
                ``env_vars`` merge.
            timeout: Timeout in seconds when waiting for ready.
            headers: Optional per-request header overrides.

        Returns:
            Snapshot in "ready" status.

        Raises:
            ResourceNotFoundError: If sandbox not found.
            ResourceTimeoutError: If snapshot doesn't become ready within timeout.
            ResourceCreationError: If snapshot capture fails.
            SandboxClientError: For other errors.
        """
        add_sandbox_metadata(self.id)
        return self._client.capture_snapshot(
            self.name,
            name,
            run_config=run_config,
            timeout=timeout,
            headers=headers,
        )
