"""Type stubs for the _microsandbox native extension module."""

from __future__ import annotations

import builtins
import os
from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence
from datetime import timedelta
from typing import Any, Literal

from microsandbox.inspection import SandboxConfigInspection
from microsandbox.jobs import JobEvent, JobExit, JobInfo, JobLogEntry, JobOutputSource, JobPage
from microsandbox.types import (
    ContextKind,
    CpuPlacement,
    DeploymentProfile,
    DiskCompactionResult,
    DiskImageFormat,
    ExecEventType,
    ExecOptions,
    FsEntryKind,
    GuestFlush,
    HostPermissions,
    ImageArchiveFormat,
    ImageSource,
    InitConfig,
    InitOptions,
    LogLevel,
    LogReadSource,
    LogSource,
    ModificationPolicy,
    MountConfig,
    NamedVolumeMode,
    Network,
    NetworkPolicy,
    OutboundProxy,
    PatchConfig,
    PortBinding,
    PortEndpoint,
    PullEventType,
    PullPolicy,
    RegistryAuth,
    ResizeOperation,
    ResourceResizeStatus,
    Rlimit,
    RootDiskConfig,
    SandboxInfo,
    SandboxModificationPlan,
    SandboxModificationResult,
    SandboxStatus,
    SecretEntry,
    SecretModifySpec,
    SecurityProfile,
    ServiceStatus,
    ServiceTarget,
    Size,
    SnapshotFormat,
    SnapshotGroupInfo,
    SnapshotScope,
    SnapshotStateKind,
    StatVirtualization,
    Stdin,
    ViolationAction,
    VolumeInfo,
    VolumeKind,
    VsockRoute,
)

class ForkOutcome:
    @property
    def name(self) -> str: ...
    @property
    def sandbox(self) -> Sandbox | None: ...
    @property
    def error(self) -> Exception | None: ...

# Deprecated: use ForkOutcome.
BranchOutcome = ForkOutcome

class PyAgentClient:
    """Raw agent client.

    Sandbox names passed to connect_sandbox are limited to 128 UTF-8 bytes.
    """

    @staticmethod
    async def connect_sandbox(
        name: str,
        *,
        timeout: float | timedelta | None = None,
    ) -> PyAgentClient: ...
    @staticmethod
    async def connect(
        path: str,
        *,
        timeout: float | timedelta | None = None,
    ) -> PyAgentClient: ...
    @staticmethod
    def socket_path(name: str) -> str: ...
    async def request(self, flags: int, body: bytes) -> dict[str, int | bytes]: ...
    async def stream_open(self, flags: int, body: bytes) -> dict[str, int]: ...
    async def stream_next(self, handle: int) -> dict[str, int | bytes] | None: ...
    async def stream_close(self, handle: int) -> None: ...
    async def send(self, id: int, flags: int, body: bytes) -> None: ...
    def ready_bytes(self) -> bytes: ...
    async def close(self) -> None: ...

class SandboxPage:
    @property
    def sandboxes(self) -> list[Sandbox]: ...
    @property
    def next_cursor(self) -> str | None: ...

class StorageRecovery:
    @property
    def name(self) -> str: ...
    @property
    def ready(self) -> bool: ...
    @property
    def originals_retained(self) -> bool: ...

class Sandbox:
    async def snapshot(
        self,
        name: str,
        *,
        initial_checkpoint: str | None = None,
        dest_dir: str | os.PathLike[str] | None = None,
        labels: dict[str, str] | None = None,
        full: bool = False,
        record_integrity: bool = False,
        guest_flush: str | None = None,
    ) -> SnapshotCreateResult: ...
    @staticmethod
    def local() -> Sandboxes: ...
    @staticmethod
    def remote() -> Sandboxes: ...
    @property
    def context_kind(self) -> ContextKind: ...
    async def checkpoint(self, name: str) -> Snapshot: ...
    async def storage_usage(self) -> StorageItemUsage: ...
    @staticmethod
    def ctx(context: Context) -> Sandboxes: ...
    @property
    def context(self) -> Context: ...

    """Sandbox lifecycle API.

    Sandbox names are limited to 128 UTF-8 bytes.
    """

    @staticmethod
    async def recover_storage(
        name: str,
        *,
        selections: Mapping[str, str] | None = None,
        accept_selected_view: bool = False,
        legacy_writers_stopped: bool = False,
    ) -> StorageRecovery: ...
    async def get_job(self, id: str) -> Job: ...
    async def list_jobs(
        self, *, all: bool = False, limit: int = 50, cursor: str | None = None
    ) -> JobPage: ...
    @staticmethod
    async def restore(
        snapshot: Snapshot | str | os.PathLike[str],
        *,
        name: str,
        cpus: int | None = None,
        memory: int | Size | None = None,
        max_cpus: int | None = None,
        max_memory: int | None = None,
        labels: Mapping[str, str] | None = None,
        workdir: str | None = None,
        shell: str | None = None,
        entrypoint: Sequence[str] | None = None,
        cmd: Sequence[str] | None = None,
        env: Mapping[str, str] | None = None,
        init: str | InitConfig | Mapping[str, Any] | None = None,
        hostname: str | None = None,
        network_policy: NetworkPolicy | None = None,
        pull_policy: PullPolicy | None = None,
        proxy: OutboundProxy | None = None,
        max_connections: int | None = None,
        max_tcp_connections: int | None = None,
        max_udp_connections: int | None = None,
        disable_network: bool = False,
        security: SecurityProfile | None = None,
        max_duration: float | timedelta | None = None,
        idle_timeout: float | timedelta | None = None,
        guest_clock: Literal["sync", "off"] | None = None,
        cow_memory: bool = False,
        forked: bool = False,  # Deprecated: use cow_memory.
        disk_only: bool = False,
        snapshot_base: str | None = None,
        user: str | None = None,
        log_level: LogLevel | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
        captured_volumes: Sequence[str] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        tcp_accept_queue_size: int | None = None,
        max_inbound_tcp_connections: int | None = None,
        vsock: Mapping[str, int] | Sequence[VsockRoute] | None = None,
        external_mount_policy: Literal["strict", "relaxed"] = "strict",
        dangerously_inherit_resources: bool = False,
        allow_missing_resources: bool = False,
    ) -> Sandbox: ...
    @staticmethod
    def restore_with_progress(
        snapshot: Snapshot | str | os.PathLike[str],
        *,
        name: str,
        cpus: int | None = None,
        memory: int | Size | None = None,
        max_cpus: int | None = None,
        max_memory: int | None = None,
        labels: Mapping[str, str] | None = None,
        workdir: str | None = None,
        shell: str | None = None,
        entrypoint: Sequence[str] | None = None,
        cmd: Sequence[str] | None = None,
        env: Mapping[str, str] | None = None,
        init: str | InitConfig | Mapping[str, Any] | None = None,
        hostname: str | None = None,
        network_policy: NetworkPolicy | None = None,
        pull_policy: PullPolicy | None = None,
        proxy: OutboundProxy | None = None,
        max_connections: int | None = None,
        max_tcp_connections: int | None = None,
        max_udp_connections: int | None = None,
        disable_network: bool = False,
        security: SecurityProfile | None = None,
        max_duration: float | timedelta | None = None,
        idle_timeout: float | timedelta | None = None,
        guest_clock: Literal["sync", "off"] | None = None,
        cow_memory: bool = False,
        forked: bool = False,  # Deprecated: use cow_memory.
        disk_only: bool = False,
        snapshot_base: str | None = None,
        user: str | None = None,
        log_level: LogLevel | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
        captured_volumes: Sequence[str] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        tcp_accept_queue_size: int | None = None,
        max_inbound_tcp_connections: int | None = None,
        vsock: Mapping[str, int] | Sequence[VsockRoute] | None = None,
        external_mount_policy: Literal["strict", "relaxed"] = "strict",
        dangerously_inherit_resources: bool = False,
        allow_missing_resources: bool = False,
    ) -> PullSession: ...
    @staticmethod
    async def create(
        name: str,
        *,
        image: str | os.PathLike[str] | ImageSource | None = None,
        memory: int | Size | None = None,
        cpus: int | None = None,
        max_memory: int | Size | None = None,
        max_cpus: int | None = None,
        cpu_placement: CpuPlacement | Literal["inherit", "auto", "spread", "compact"] | None = None,
        placement_profile: str | None = None,
        thp: Literal["always", "madvise", "never"] | None = None,
        nested_virt: bool | None = None,
        workdir: str | None = None,
        shell: str | None = None,
        security: SecurityProfile | None = None,
        deployment_profile: DeploymentProfile | None = None,
        hostname: str | None = None,
        user: str | None = None,
        entrypoint: Sequence[str] | None = None,
        cmd: Sequence[str] | None = None,
        init: str | InitConfig | InitOptions | None = None,
        replace: bool = False,
        replace_with_timeout: float | timedelta | None = None,
        max_duration: float | timedelta | None = None,
        idle_timeout: float | timedelta | None = None,
        ephemeral: bool = False,
        env: Mapping[str, str] | None = None,
        labels: Mapping[str, str] | None = None,
        scripts: Mapping[str, str] | None = None,
        pull_policy: PullPolicy | None = None,
        log_level: LogLevel | None = None,
        registry_auth: RegistryAuth | None = None,
        registry_insecure: bool = False,
        registry_ca_certs: list[bytes | bytearray | str | os.PathLike[str]] | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
        patches: Sequence[PatchConfig] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        vsock: Mapping[str, int] | Sequence[VsockRoute] | None = None,
        network: Network | None = None,
        intercept_tls: bool = False,
        proxy: OutboundProxy | None = None,
        secrets: Sequence[SecretEntry] | None = None,
        secret_violation_action: ViolationAction | None = None,
        detached: bool = False,
    ) -> Sandbox: ...
    @staticmethod
    async def connect_or_create(
        name: str,
        *,
        image: str | os.PathLike[str] | ImageSource | None = None,
        memory: int | Size | None = None,
        cpus: int | None = None,
        max_memory: int | Size | None = None,
        max_cpus: int | None = None,
        cpu_placement: CpuPlacement | Literal["inherit", "auto", "spread", "compact"] | None = None,
        placement_profile: str | None = None,
        thp: Literal["always", "madvise", "never"] | None = None,
        nested_virt: bool | None = None,
        workdir: str | None = None,
        shell: str | None = None,
        security: SecurityProfile | None = None,
        deployment_profile: DeploymentProfile | None = None,
        hostname: str | None = None,
        user: str | None = None,
        entrypoint: Sequence[str] | None = None,
        cmd: Sequence[str] | None = None,
        init: str | InitConfig | InitOptions | None = None,
        replace: bool = False,
        replace_with_timeout: float | timedelta | None = None,
        max_duration: float | timedelta | None = None,
        idle_timeout: float | timedelta | None = None,
        ephemeral: bool = False,
        env: Mapping[str, str] | None = None,
        labels: Mapping[str, str] | None = None,
        scripts: Mapping[str, str] | None = None,
        pull_policy: PullPolicy | None = None,
        log_level: LogLevel | None = None,
        registry_auth: RegistryAuth | None = None,
        registry_insecure: bool = False,
        registry_ca_certs: list[bytes | bytearray | str | os.PathLike[str]] | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
        patches: Sequence[PatchConfig] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        vsock: Mapping[str, int] | Sequence[VsockRoute] | None = None,
        network: Network | None = None,
        intercept_tls: bool = False,
        proxy: OutboundProxy | None = None,
        secrets: Sequence[SecretEntry] | None = None,
        secret_violation_action: ViolationAction | None = None,
        detached: bool = False,
    ) -> Sandbox: ...
    @staticmethod
    async def start(name: str, *, detached: bool = False) -> Sandbox: ...
    @staticmethod
    async def get(name: str) -> Sandbox: ...
    @staticmethod
    async def get_running(name: str) -> Sandbox: ...
    async def ensure_running(self) -> None: ...
    async def info(self) -> SandboxInfo: ...
    async def status(self) -> SandboxStatus: ...
    async def last_failure_message(self) -> str | None: ...
    async def config(self) -> SandboxConfigInspection: ...
    @staticmethod
    async def list() -> SandboxPage: ...
    @staticmethod
    async def list_with(
        *,
        cursor: str | None = None,
        limit: int | None = None,
        labels: Mapping[str, str] | None = None,
    ) -> SandboxPage: ...
    @staticmethod
    async def remove(name: str) -> None: ...
    @staticmethod
    def create_with_progress(
        name: str,
        *,
        image: str | os.PathLike[str] | ImageSource | None = None,
        memory: int | Size | None = None,
        cpus: int | None = None,
        max_memory: int | Size | None = None,
        max_cpus: int | None = None,
        cpu_placement: CpuPlacement | Literal["inherit", "auto", "spread", "compact"] | None = None,
        placement_profile: str | None = None,
        thp: Literal["always", "madvise", "never"] | None = None,
        nested_virt: bool | None = None,
        workdir: str | None = None,
        shell: str | None = None,
        security: SecurityProfile | None = None,
        deployment_profile: DeploymentProfile | None = None,
        hostname: str | None = None,
        user: str | None = None,
        entrypoint: Sequence[str] | None = None,
        cmd: Sequence[str] | None = None,
        init: str | InitConfig | InitOptions | None = None,
        replace: bool = False,
        replace_with_timeout: float | timedelta | None = None,
        max_duration: float | timedelta | None = None,
        idle_timeout: float | timedelta | None = None,
        ephemeral: bool = False,
        env: Mapping[str, str] | None = None,
        labels: Mapping[str, str] | None = None,
        scripts: Mapping[str, str] | None = None,
        pull_policy: PullPolicy | None = None,
        log_level: LogLevel | None = None,
        registry_auth: RegistryAuth | None = None,
        registry_insecure: bool = False,
        registry_ca_certs: builtins.list[bytes | bytearray | str | os.PathLike[str]] | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
        patches: Sequence[PatchConfig] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        vsock: Mapping[str, int] | Sequence[VsockRoute] | None = None,
        network: Network | None = None,
        intercept_tls: bool = False,
        proxy: OutboundProxy | None = None,
        secrets: Sequence[SecretEntry] | None = None,
        secret_violation_action: ViolationAction | None = None,
        detached: bool = False,
    ) -> PullSession: ...
    @property
    def name(self) -> str: ...
    @property
    def id(self) -> str: ...
    @property
    def owns_lifecycle(self) -> Awaitable[bool]: ...
    @property
    def fs(self) -> SandboxFsOps: ...
    async def exec_default(
        self,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        timeout: float | timedelta | None = None,
        stdin: Stdin | bytes | None = None,
        tty: bool = False,
        rlimits: builtins.list[Rlimit] | None = None,
    ) -> ExecOutput: ...
    async def exec_default_stream(
        self,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        timeout: float | timedelta | None = None,
        stdin: Stdin | bytes | None = None,
        tty: bool = False,
        rlimits: builtins.list[Rlimit] | None = None,
    ) -> ExecHandle: ...
    async def exec(
        self,
        cmd: str,
        args: builtins.list[str] | ExecOptions | None = None,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        timeout: float | timedelta | None = None,
        stdin: Stdin | bytes | None = None,
        tty: bool = False,
        rlimits: builtins.list[Rlimit] | None = None,
    ) -> ExecOutput: ...
    async def exec_detached(
        self,
        cmd: str,
        args: builtins.list[str] | ExecOptions | None = None,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        timeout: float | timedelta | None = None,
        stdin: Stdin | bytes | None = None,
        tty: bool = False,
        rlimits: builtins.list[Rlimit] | None = None,
    ) -> Job: ...
    async def exec_stream(
        self,
        cmd: str,
        args: builtins.list[str] | ExecOptions | None = None,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        timeout: float | timedelta | None = None,
        stdin: Stdin | bytes | None = None,
        tty: bool = False,
        rlimits: builtins.list[Rlimit] | None = None,
    ) -> ExecHandle: ...
    async def shell(
        self,
        script: str,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        timeout: float | timedelta | None = None,
        stdin: Stdin | bytes | None = None,
        tty: bool = False,
        rlimits: builtins.list[Rlimit] | None = None,
    ) -> ExecOutput: ...
    async def shell_stream(
        self,
        script: str,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        timeout: float | timedelta | None = None,
        stdin: Stdin | bytes | None = None,
        tty: bool = False,
        rlimits: builtins.list[Rlimit] | None = None,
    ) -> ExecHandle: ...
    def ssh(self) -> SandboxSshOps: ...
    async def attach_default(
        self,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        detach_keys: str | None = None,
    ) -> int: ...
    async def attach(
        self,
        cmd: str,
        args: builtins.list[str] | None = None,
        *,
        cwd: str | None = None,
        user: str | None = None,
        env: Mapping[str, str] | None = None,
        detach_keys: str | None = None,
    ) -> int: ...
    async def attach_shell(self) -> int: ...
    async def metrics(self) -> SandboxMetrics: ...
    async def ping(self) -> SandboxPingResult: ...
    async def touch(self) -> SandboxTouchResult: ...
    async def compact(
        self,
        *,
        layers: int | None = None,
        dry_run: bool = False,
        disk: str | None = None,
        root_disk_only: bool = False,
    ) -> DiskCompactionResult: ...
    async def modify(
        self,
        *,
        cpus: int | None = None,
        max_cpus: int | None = None,
        memory: int | Size | None = None,
        max_memory: int | Size | None = None,
        root_disk_size: int | None = None,
        env: Mapping[str, str] | None = None,
        env_rm: builtins.list[str] | None = None,
        labels: Mapping[str, str] | None = None,
        labels_rm: builtins.list[str] | None = None,
        workdir: str | None = None,
        secrets: Mapping[str, SecretModifySpec] | None = None,
        secrets_rm: builtins.list[str] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        ports_rm: Sequence[PortEndpoint] | None = None,
        policy: ModificationPolicy | None = None,
        dry_run: bool = False,
    ) -> SandboxModificationPlan: ...
    async def modify_with_resize_tracking(
        self,
        *,
        cpus: int | None = None,
        max_cpus: int | None = None,
        memory: int | Size | None = None,
        max_memory: int | Size | None = None,
        root_disk_size: int | None = None,
        env: Mapping[str, str] | None = None,
        env_rm: builtins.list[str] | None = None,
        labels: Mapping[str, str] | None = None,
        labels_rm: builtins.list[str] | None = None,
        workdir: str | None = None,
        secrets: Mapping[str, SecretModifySpec] | None = None,
        secrets_rm: builtins.list[str] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        ports_rm: Sequence[PortEndpoint] | None = None,
        policy: ModificationPolicy | None = None,
        dry_run: bool = False,
    ) -> SandboxModificationResult: ...
    async def resize_status(self) -> list[ResourceResizeStatus]: ...
    async def resize_operations(self) -> list[ResizeOperation]: ...
    async def wait_for_resize_operations(
        self, operations: list[ResizeOperation], *, timeout: float | None = None
    ) -> list[ResourceResizeStatus]: ...
    async def wait_until_resized(
        self, *, timeout: float | None = None
    ) -> list[ResourceResizeStatus]: ...
    async def metrics_stream(self, interval: float = 1.0) -> MetricsStream: ...
    async def logs(
        self,
        tail: int | None = None,
        since_ms: float | None = None,
        until_ms: float | None = None,
        sources: builtins.list[LogReadSource] | None = None,
    ) -> builtins.list[LogEntry]: ...
    async def log_stream(
        self,
        sources: builtins.list[LogReadSource] | None = None,
        since_ms: float | None = None,
        from_cursor: str | None = None,
        until_ms: float | None = None,
        follow: bool = False,
    ) -> LogStream: ...
    async def restore_warnings(self) -> builtins.list[ExternalMountWarning]: ...
    async def stop(self, timeout: float | timedelta | None = None) -> None: ...
    async def stop_with_timeout(self, timeout: float | timedelta) -> None: ...
    async def fork(
        self,
        name: str,
        *,
        record_integrity: bool = False,
        guest_flush: GuestFlush | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
    ) -> Sandbox: ...
    # Deprecated: use fork.
    async def branch(
        self,
        name: str,
        *,
        record_integrity: bool = False,
        guest_flush: GuestFlush | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
    ) -> Sandbox: ...
    async def fork_many(
        self,
        names: builtins.list[str],
        *,
        record_integrity: bool = False,
        guest_flush: GuestFlush | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
    ) -> builtins.list[ForkOutcome]: ...
    # Deprecated: use fork_many.
    async def branch_many(
        self,
        names: builtins.list[str],
        *,
        record_integrity: bool = False,
        guest_flush: GuestFlush | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
    ) -> builtins.list[ForkOutcome]: ...
    async def pause(self, *, guest_flush: GuestFlush | None = None) -> None: ...
    async def resume(self) -> None: ...
    async def request_stop(self) -> None: ...
    async def kill(self, timeout: float | timedelta | None = None) -> None: ...
    async def request_kill(self) -> None: ...
    async def request_drain(self) -> None: ...
    async def wait_for_status(self, status: SandboxStatus) -> None: ...
    async def restart(
        self,
        *,
        force: bool = False,
        timeout: float | timedelta | None = None,
        detached: bool = False,
    ) -> Sandbox: ...
    async def destroy(
        self, *, force: bool = False, timeout: float | timedelta | None = None
    ) -> None: ...
    async def wait_until_stopped(self) -> SandboxStopResult: ...
    async def detach(self) -> None: ...
    async def __aenter__(self) -> Sandbox: ...
    async def __aexit__(
        self, exc_type: type | None, exc_val: BaseException | None, exc_tb: Any
    ) -> bool: ...

class SandboxStopResult:
    @property
    def name(self) -> str: ...
    @property
    def status(self) -> SandboxStatus: ...
    @property
    def exit_code(self) -> int | None: ...
    @property
    def signal(self) -> int | None: ...
    @property
    def observed_at(self) -> float: ...
    @property
    def source(self) -> str | None: ...

class SandboxPingResult:
    @property
    def name(self) -> str: ...
    @property
    def latency_ms(self) -> float: ...

class SandboxTouchResult:
    @property
    def name(self) -> str: ...
    @property
    def activity_seq(self) -> int: ...

class ExecOutput:
    @property
    def exit_code(self) -> int: ...
    @property
    def success(self) -> bool: ...
    @property
    def stdout_text(self) -> str: ...
    @property
    def stderr_text(self) -> str: ...
    @property
    def stdout_bytes(self) -> bytes: ...
    @property
    def stderr_bytes(self) -> bytes: ...

class ExecHandle:
    @property
    def id(self) -> str: ...
    def take_stdin(self) -> ExecSink | None: ...
    async def recv(self) -> ExecEvent | None: ...
    async def wait(self) -> tuple[int, bool]: ...
    async def collect(self) -> ExecOutput: ...
    async def signal(self, sig: int) -> None: ...
    async def kill(self) -> None: ...
    async def resize(self, rows: int, cols: int) -> None: ...
    def __aiter__(self) -> AsyncIterator[ExecEvent]: ...
    async def __anext__(self) -> ExecEvent: ...

class ExecSink:
    async def write(self, data: bytes) -> None: ...
    async def close(self) -> None: ...

class ExecEvent:
    event_type: ExecEventType
    pid: int | None
    data: bytes | None
    code: int | None

class SandboxSshOps:
    async def open_client(
        self,
        *,
        user: str = "root",
        term: str | None = None,
        sftp: bool = True,
        inactivity_timeout: float | timedelta | None = None,
    ) -> SshClient: ...
    async def prepare_server(
        self,
        *,
        host_key_path: str | os.PathLike[str] | None = None,
        authorized_keys_path: str | os.PathLike[str] | None = None,
        user: str | None = None,
        sftp: bool = True,
        inactivity_timeout: float | timedelta | None = None,
    ) -> SshServer: ...

class SshOutput:
    @property
    def status(self) -> int: ...
    @property
    def success(self) -> bool: ...
    @property
    def stdout_text(self) -> str: ...
    @property
    def stderr_text(self) -> str: ...
    @property
    def stdout_bytes(self) -> bytes: ...
    @property
    def stderr_bytes(self) -> bytes: ...

class SshClient:
    async def exec(self, command: str, *, tty: bool = False) -> SshOutput: ...
    async def attach(
        self,
        *,
        term: str | None = None,
        detach_keys: str | None = None,
    ) -> int: ...
    async def sftp(self) -> SftpClient: ...
    async def close(self) -> None: ...

class SftpClient:
    async def read(self, path: str) -> bytes: ...
    async def write(self, path: str, data: bytes) -> None: ...
    async def mkdir(self, path: str) -> None: ...
    async def remove_file(self, path: str) -> None: ...
    async def remove_dir(self, path: str) -> None: ...
    async def rename(self, old_path: str, new_path: str) -> None: ...
    async def real_path(self, path: str) -> str: ...
    async def read_link(self, path: str) -> str: ...
    async def symlink(self, target: str, link_path: str) -> None: ...
    async def close(self) -> None: ...

class SshServer:
    async def serve_connection(self) -> None: ...
    def close(self) -> None: ...

class SandboxFsOps:
    async def read(self, path: str) -> bytes: ...
    async def read_text(self, path: str) -> str: ...
    async def read_stream(self, path: str) -> FsReadStream: ...
    async def write(self, path: str, data: bytes) -> None: ...
    async def write_stream(self, path: str) -> FsWriteSink: ...
    async def list(self, path: str) -> list[FsEntry]: ...
    async def mkdir(self, path: str) -> None: ...
    async def remove(self, path: str) -> None: ...
    async def remove_dir(self, path: str) -> None: ...
    async def copy(self, src: str, dst: str) -> None: ...
    async def rename(self, src: str, dst: str) -> None: ...
    async def stat(self, path: str) -> FsMetadata: ...
    async def exists(self, path: str) -> bool: ...
    async def copy_from_host(self, host_path: str, guest_path: str) -> None: ...
    async def copy_to_host(self, guest_path: str, host_path: str) -> None: ...

class FsReadStream:
    def __aiter__(self) -> AsyncIterator[bytes]: ...
    async def __anext__(self) -> bytes: ...
    async def collect(self) -> bytes: ...

class FsWriteSink:
    async def write(self, data: bytes) -> None: ...
    async def close(self) -> None: ...
    async def __aenter__(self) -> FsWriteSink: ...
    async def __aexit__(
        self, exc_type: type | None, exc_val: BaseException | None, exc_tb: Any
    ) -> bool: ...

class FsEntry:
    path: str
    kind: FsEntryKind
    size: int
    mode: int
    modified: float | None

class FsMetadata:
    kind: FsEntryKind
    size: int
    mode: int
    readonly: bool
    modified: float | None
    created: float | None

class SandboxMetrics:
    cpu_percent: float
    vcpu_time_ns: int
    memory_bytes: int
    memory_available_bytes: int | None
    memory_host_resident_bytes: int | None
    memory_limit_bytes: int
    disk_read_bytes: int
    disk_write_bytes: int
    net_rx_bytes: int
    net_tx_bytes: int
    upper_used_bytes: int | None
    upper_free_bytes: int | None
    upper_host_allocated_bytes: int | None
    uptime_ms: int
    timestamp_ms: float

class MetricsStream:
    def __aiter__(self) -> AsyncIterator[SandboxMetrics]: ...
    async def __anext__(self) -> SandboxMetrics: ...

class LogEntry:
    timestamp_ms: float
    source: LogSource
    session_id: int | None  # None for `system` entries
    cursor: str  # opaque resume token, pass back via `from_cursor`
    @property
    def data(self) -> bytes: ...
    def text(self) -> str: ...

class LogStream:
    def __aiter__(self) -> AsyncIterator[LogEntry]: ...
    async def __anext__(self) -> LogEntry: ...

class Volume:
    @staticmethod
    def local() -> Volumes: ...
    @staticmethod
    def remote() -> Volumes: ...
    @staticmethod
    def ctx(context: Context) -> Volumes: ...
    @property
    def context(self) -> Context: ...
    @staticmethod
    async def create(
        name: str,
        *,
        kind: VolumeKind = VolumeKind.DIRECTORY,
        size_mib: int | None = None,
        quota_mib: int | None = None,
        labels: dict[str, str] | None = None,
    ) -> Volume: ...
    @staticmethod
    async def get(name: str) -> Volume: ...
    @staticmethod
    async def get_default() -> Volume: ...
    @staticmethod
    async def list() -> list[Volume]: ...
    @staticmethod
    async def remove(name: str) -> None: ...
    @staticmethod
    def bind(
        path: str,
        *,
        readonly: bool = False,
        noexec: bool = False,
        nosuid: bool = False,
        nodev: bool = False,
        stat_virtualization: StatVirtualization | None = None,
        host_permissions: HostPermissions | None = None,
        uid: int | None = None,
        gid: int | None = None,
    ) -> MountConfig: ...
    @staticmethod
    def named(
        name: str,
        *,
        mode: NamedVolumeMode | None = None,
        kind: VolumeKind | None = None,
        size_mib: int | None = None,
        quota_mib: int | None = None,
        readonly: bool = False,
        noexec: bool = False,
        nosuid: bool = False,
        nodev: bool = False,
        stat_virtualization: StatVirtualization | None = None,
        host_permissions: HostPermissions | None = None,
        uid: int | None = None,
        gid: int | None = None,
    ) -> MountConfig: ...
    @staticmethod
    def owned(
        *,
        kind: VolumeKind | None = None,
        size_mib: int | None = None,
        quota_mib: int | None = None,
        readonly: bool = False,
        noexec: bool = False,
        nosuid: bool = False,
        nodev: bool = False,
        stat_virtualization: StatVirtualization | None = None,
        host_permissions: HostPermissions | None = None,
        uid: int | None = None,
        gid: int | None = None,
    ) -> MountConfig: ...
    @staticmethod
    def tmpfs(
        *,
        size_mib: int | None = None,
        readonly: bool = False,
        noexec: bool = False,
        nosuid: bool = False,
        nodev: bool = False,
    ) -> MountConfig: ...
    @staticmethod
    def disk(
        path: str,
        *,
        format: DiskImageFormat | None = None,
        fstype: str | None = None,
        readonly: bool = False,
        noexec: bool = False,
        nosuid: bool = False,
        nodev: bool = False,
    ) -> MountConfig: ...
    @property
    def name(self) -> str: ...
    @property
    def path(self) -> str: ...
    @property
    def id(self) -> str: ...
    @property
    def is_default(self) -> bool: ...
    @property
    def kind(self) -> VolumeKind: ...
    @property
    def disk_format(self) -> DiskImageFormat | None: ...
    @property
    def disk_fstype(self) -> str | None: ...
    @property
    def created_at(self) -> float | None: ...
    @property
    def fs(self) -> VolumeFs: ...
    async def info(self) -> VolumeInfo: ...
    async def destroy(self) -> None: ...

class Service:
    @staticmethod
    async def create(slug: str, *, target: ServiceTarget) -> Service: ...
    @staticmethod
    async def get(slug: str) -> Service: ...
    @staticmethod
    async def list() -> ServicePage: ...
    @staticmethod
    async def list_with(
        *,
        sandbox: str | None = None,
        cursor: str | None = None,
        limit: int | None = None,
    ) -> ServicePage: ...
    @property
    def slug(self) -> str: ...
    @property
    def url(self) -> str: ...
    @property
    def status(self) -> ServiceStatus: ...
    @property
    def target(self) -> ServiceTarget | None: ...
    @property
    def created_at(self) -> float: ...
    @property
    def updated_at(self) -> float: ...
    async def update(
        self,
        *,
        target: ServiceTarget,
    ) -> Service: ...
    async def enable(self) -> Service: ...
    async def disable(self) -> Service: ...
    async def remove(self) -> None: ...
    async def refresh(self) -> Service: ...

class ServicePage:
    @property
    def services(self) -> list[Service]: ...
    @property
    def next_cursor(self) -> str | None: ...

class VolumeFs:
    async def read(self, path: str) -> bytes: ...
    async def read_text(self, path: str) -> str: ...
    async def write(self, path: str, data: bytes) -> None: ...
    async def list(self, path: str) -> list[FsEntry]: ...
    async def mkdir(self, path: str) -> None: ...
    async def remove_file(self, path: str) -> None: ...
    async def remove_dir(self, path: str) -> None: ...
    async def copy(self, from_: str, to: str) -> None: ...
    async def rename(self, from_: str, to: str) -> None: ...
    async def stat(self, path: str) -> FsMetadata: ...
    async def exists(self, path: str) -> bool: ...

class Storage:
    """Backend-scoped observations and explicit runtime-cache cleanup."""

    @staticmethod
    async def usage() -> StorageUsage: ...
    @staticmethod
    async def prune(
        *,
        dry_run: bool = False,
        older_than_seconds: int | None = None,
    ) -> MemoryCacheReport:
        """Revalidate ownership before removing unused RAM; None applies no age filter."""
        ...

class StorageUsage:
    @property
    def images(self) -> StorageCategoryUsage: ...
    @property
    def snapshots(self) -> StorageCategoryUsage: ...
    @property
    def sandboxes(self) -> StorageCategoryUsage: ...
    @property
    def volumes(self) -> StorageCategoryUsage: ...
    @property
    def branch_memory(self) -> StorageCategoryUsage: ...
    @property
    def snapshot_memory(self) -> StorageCategoryUsage: ...
    @property
    def notes(self) -> list[str]: ...

class StorageCategoryUsage:
    @property
    def count(self) -> int | None: ...
    @property
    def in_use(self) -> int | None: ...
    @property
    def logical_bytes(self) -> int | None: ...
    @property
    def allocated_bytes(self) -> int | None: ...
    @property
    def reclaimable_logical_bytes(self) -> int | None: ...
    @property
    def items(self) -> list[StorageItemUsage]: ...
    @property
    def notes(self) -> list[str]: ...

class StorageItemUsage:
    @property
    def name(self) -> str: ...
    @property
    def path(self) -> str: ...
    @property
    def logical_bytes(self) -> int | None: ...
    @property
    def allocated_bytes(self) -> int | None: ...
    @property
    def in_use(self) -> bool | None: ...
    @property
    def reclaimable(self) -> bool | None: ...
    @property
    def reasons(self) -> list[str]: ...

class MemoryCacheEntry:
    @property
    def path(self) -> str: ...
    @property
    def kind(self) -> Literal["branch_memory", "snapshot_memory"]: ...
    @property
    def logical_bytes(self) -> int | None: ...
    @property
    def allocated_bytes(self) -> int | None: ...
    @property
    def state(
        self,
    ) -> Literal[
        "reclaimable",
        "in_use",
        "pending_handoff",
        "too_young",
        "missing_handoff_lock",
        "changed",
        "removed",
        "error",
    ]: ...
    @property
    def error(self) -> str | None: ...

class MemoryCacheReport:
    @property
    def dry_run(self) -> bool: ...
    @property
    def entries(self) -> list[MemoryCacheEntry]: ...
    @property
    def files_removed(self) -> int: ...
    @property
    def logical_bytes_removed(self) -> int: ...
    @property
    def physical_bytes_reclaimed(self) -> int | None: ...
    @property
    def truncated(self) -> bool: ...

class Image:
    @staticmethod
    def oci(
        reference: str,
        *,
        root_disk: RootDiskConfig | int | None = None,
        upper_size_mib: int | None = None,
    ) -> ImageSource: ...
    @staticmethod
    def bind(path: str) -> ImageSource: ...
    @staticmethod
    def disk(path: str, *, fstype: str | None = None) -> ImageSource: ...
    @staticmethod
    async def get(reference: str) -> ImageHandle: ...
    @staticmethod
    async def list() -> list[ImageHandle]: ...
    @staticmethod
    async def inspect(reference: str) -> ImageDetail: ...
    @staticmethod
    async def remove(reference: str, *, force: bool = False) -> None: ...
    @staticmethod
    async def prune() -> ImagePruneReport: ...
    @staticmethod
    async def load(input_path: str, *, tag: str | None = None) -> builtins.list[ImageHandle]: ...
    @staticmethod
    async def save(
        reference: str | Sequence[str],
        *,
        output_path: str,
        format: ImageArchiveFormat = ImageArchiveFormat.DOCKER,
    ) -> None: ...

class ImageHandle:
    @property
    def reference(self) -> str: ...
    @property
    def size_bytes(self) -> int | None: ...
    @property
    def manifest_digest(self) -> str | None: ...
    @property
    def architecture(self) -> str | None: ...
    @property
    def os(self) -> str | None: ...
    @property
    def layer_count(self) -> int: ...
    @property
    def last_used_at(self) -> float | None: ...
    @property
    def created_at(self) -> float | None: ...
    async def inspect(self) -> ImageDetail: ...
    async def remove(self, *, force: bool = False) -> None: ...

class ImageDetail:
    @property
    def handle(self) -> ImageHandle: ...
    @property
    def config(self) -> ImageConfigDetail | None: ...
    @property
    def layers(self) -> list[ImageLayerDetail]: ...

class ImageConfigDetail:
    @property
    def digest(self) -> str: ...
    @property
    def env(self) -> list[str]: ...
    @property
    def cmd(self) -> list[str] | None: ...
    @property
    def entrypoint(self) -> list[str] | None: ...
    @property
    def working_dir(self) -> str | None: ...
    @property
    def user(self) -> str | None: ...
    @property
    def labels(self) -> dict[str, Any] | None: ...
    @property
    def stop_signal(self) -> str | None: ...

class ImageLayerDetail:
    @property
    def diff_id(self) -> str: ...
    @property
    def blob_digest(self) -> str: ...
    @property
    def media_type(self) -> str | None: ...
    @property
    def compressed_size_bytes(self) -> int | None: ...
    @property
    def erofs_size_bytes(self) -> int | None: ...
    @property
    def position(self) -> int: ...

class ImagePruneReport:
    @property
    def skipped_in_use(self) -> int: ...
    @property
    def image_refs_removed(self) -> int: ...
    @property
    def manifests_removed(self) -> int: ...
    @property
    def layers_removed(self) -> int: ...
    @property
    def fsmeta_removed(self) -> int: ...
    @property
    def vmdk_removed(self) -> int: ...
    @property
    def bytes_reclaimed(self) -> int | None: ...

class ExternalMountWarning:
    @property
    def guest_path(self) -> str: ...
    @property
    def reason(self) -> str: ...
    @property
    def stale_inodes(self) -> list[int]: ...

class Snapshot:
    async def spawn_sandbox(self, *, name: str | None = None, **kwargs: Any) -> Sandbox: ...
    async def spawn_sandbox_with_progress(
        self, *, name: str | None = None, **kwargs: Any
    ) -> PullSession: ...
    async def save(
        self,
        out: str | os.PathLike[str],
        *,
        with_parents: bool = False,
        with_image: bool = False,
        plain_tar: bool = False,
        since: str | None = None,
        last_layers: int | None = None,
        compatibility: Literal["current", "0.7.8"] = "current",
    ) -> None: ...
    @staticmethod
    def local() -> Checkpoints: ...
    @staticmethod
    def remote() -> Checkpoints: ...
    @staticmethod
    def ctx(context: Context) -> Checkpoints: ...
    @property
    def context(self) -> Context: ...
    async def storage_usage(self) -> StorageItemUsage: ...
    @staticmethod
    async def create(
        name: str = "",
        *,
        from_sandbox: str,
        group: str | None = None,
        dest_dir: str | os.PathLike[str] | None = None,
        labels: dict[str, str] | None = None,
        force: bool = False,
        record_integrity: bool = False,
        full: bool = False,
        guest_flush: GuestFlush | None = None,
    ) -> Snapshot: ...
    @staticmethod
    async def create_archive(
        name: str,
        archive: str | os.PathLike[str],
        *,
        from_sandbox: str,
        group: str | None = None,
        labels: dict[str, str] | None = None,
        force: bool = False,
        record_integrity: bool = False,
        full: bool = False,
        plain_tar: bool = False,
        guest_flush: GuestFlush | None = None,
    ) -> SnapshotArchive: ...
    @staticmethod
    async def open(path_or_name: str) -> Snapshot: ...
    @staticmethod
    async def get(name_or_digest: str) -> Snapshot: ...
    @staticmethod
    async def list() -> list[Snapshot]: ...
    @staticmethod
    async def remove_by_reference(path_or_name: str, *, force: bool = False) -> None: ...
    async def remove(self, *, force: bool = False) -> CheckpointRemoveResult: ...
    @staticmethod
    async def reindex(dir: str | os.PathLike[str] | None = None) -> int: ...
    @staticmethod
    async def save_by_reference(
        name_or_path: str,
        out: str | os.PathLike[str],
        *,
        with_parents: bool = False,
        with_image: bool = False,
        plain_tar: bool = False,
        since: str | None = None,
        last_layers: int | None = None,
        compatibility: Literal["current", "0.7.8"] = "current",
    ) -> None: ...
    @staticmethod
    async def load(
        archive: str | os.PathLike[str],
        *,
        dest: str | os.PathLike[str] | None = None,
        base: str | None = None,
        group: str | None = None,
        set_head: bool = False,
    ) -> Snapshot: ...
    @staticmethod
    async def load_many(
        archives: Sequence[str | os.PathLike[str]],
        *,
        dest: str | os.PathLike[str] | None = None,
        base: str | None = None,
        group: str | None = None,
        set_head: bool = False,
    ) -> builtins.list[Snapshot]: ...
    @staticmethod
    async def group_head(group: str) -> str | None: ...
    @staticmethod
    async def set_group_head(group: str, id: str) -> dict[str, str | bool | None]: ...
    @property
    def head_update(self) -> dict[str, str | bool | None] | None: ...
    @property
    def id(self) -> str: ...
    @property
    def reference(self) -> str: ...
    @property
    def path(self) -> str:
        """Deprecated: use reference. Raises UnsupportedError for remote snapshots."""
        ...
    @property
    def reference_kind(self) -> Literal["id", "path"]: ...
    @property
    def digest(self) -> str: ...
    @property
    def size_bytes(self) -> int | None: ...
    @property
    def image_ref(self) -> str: ...
    async def image_manifest_digest(self) -> str: ...
    @property
    def state_kind(self) -> SnapshotStateKind: ...
    @property
    def format(self) -> SnapshotFormat | None: ...
    @property
    def fstype(self) -> str | None: ...
    async def checkpoint_id(self) -> str | None: ...
    @property
    def checkpoint_manifest_digest(self) -> str | None: ...
    @property
    def parent(self) -> str | None: ...
    @property
    def scope(self) -> SnapshotScope: ...
    @property
    def created_at(self) -> str: ...
    async def labels(self) -> dict[str, str]: ...
    async def source_sandbox(self) -> str | None: ...
    @staticmethod
    async def list_dir(dir: str | os.PathLike[str]) -> builtins.list[Snapshot]: ...
    async def save_to(
        self,
        out: str | os.PathLike[str],
        *,
        with_parents: bool = False,
        with_image: bool = False,
        plain_tar: bool = False,
        since: str | None = None,
        last_layers: int | None = None,
        compatibility: Literal["current", "0.7.8"] = "current",
    ) -> None: ...
    def copy_to(self, output_archive_path: str | os.PathLike[str]) -> SnapshotCopyBuilder: ...
    async def verify(self) -> dict[str, Any]: ...
    @property
    def name(self) -> str | None: ...
    @property
    def group(self) -> str | None: ...
    @property
    def parent_digest(self) -> str | None: ...
    @property
    def locality(self) -> str: ...
    @property
    def availability(self) -> str: ...
    @property
    def migration_state(self) -> str: ...
    @property
    def migration_error_code(self) -> str | None: ...
    async def manifest(self) -> dict[str, Any]: ...
    async def state(self) -> dict[str, Any]: ...
    async def destroy(self, *, force: bool = False) -> None: ...

class SnapshotArchive:
    @property
    def id(self) -> str: ...
    @property
    def descriptor_digest(self) -> str: ...
    @property
    def path(self) -> str: ...

class SnapshotCopyBuilder:
    def labels(self, labels: dict[str, str]) -> SnapshotCopyBuilder: ...
    def record_integrity(self, enabled: bool) -> SnapshotCopyBuilder: ...
    async def save(self) -> None: ...

class PullSession:
    def cancel(self) -> None: ...
    @property
    def progress(self) -> PullProgressIter: ...
    async def result(self) -> Sandbox: ...
    async def __aenter__(self) -> PullSession: ...
    async def __aexit__(
        self, exc_type: type | None, exc_val: BaseException | None, exc_tb: Any
    ) -> bool: ...

class PullProgressIter:
    def __aiter__(self) -> AsyncIterator[PullEvent]: ...
    async def __anext__(self) -> PullEvent: ...

class PullEvent:
    event_type: PullEventType
    phase: str | None
    completed_bytes: int | None
    reference: str | None
    manifest_digest: str | None
    layer_count: int | None
    total_download_bytes: int | None
    layer_index: int | None
    digest: str | None
    diff_id: str | None
    downloaded_bytes: int | None
    total_bytes: int | None
    bytes_read: int | None

async def all_sandbox_metrics() -> dict[str, SandboxMetrics]: ...
async def install_runtime(config_json: str, options_json: str) -> str: ...
async def ensure_runtime(config_json: str, options_json: str) -> str: ...
def resolve_runtime(config_json: str) -> str: ...
def is_runtime_installed(config_json: str) -> bool: ...
def resolved_msb_path() -> str: ...
def resolved_cli_msb_path() -> str: ...
def set_runtime_msb_path(path: str) -> None: ...
def set_packaged_msb_path(path: str) -> None: ...
def version() -> str: ...

class Job:
    @property
    def id(self) -> str: ...
    async def inspect(self) -> JobInfo: ...
    async def wait(self) -> JobExit: ...
    async def signal(self, signal: int) -> None: ...
    async def kill(self) -> None: ...
    async def eof(self) -> None: ...
    async def attach(
        self,
        *,
        read_only: bool = False,
        replay_bytes: int | None = None,
        cursor: str | None = None,
    ) -> JobAttachment: ...
    async def logs(
        self,
        *,
        tail: int | None = None,
        since: int | None = None,
        until: int | None = None,
        sources: Sequence[JobOutputSource | Literal["stdout", "stderr", "output", "stdin_error"]]
        | None = None,
        from_cursor: str | None = None,
    ) -> list[JobLogEntry]: ...
    async def log_stream(
        self,
        *,
        tail: int | None = None,
        since: int | None = None,
        until: int | None = None,
        sources: Sequence[JobOutputSource | Literal["stdout", "stderr", "output", "stdin_error"]]
        | None = None,
        from_cursor: str | None = None,
        follow: bool = False,
    ) -> JobLogStream: ...
    async def follow_logs(
        self,
        *,
        tail: int | None = None,
        since: int | None = None,
        until: int | None = None,
        sources: Sequence[JobOutputSource | Literal["stdout", "stderr", "output", "stdin_error"]]
        | None = None,
        from_cursor: str | None = None,
    ) -> JobLogStream: ...

class JobAttachment:
    async def recv(self) -> JobEvent | None: ...
    async def write_stdin(self, data: bytes) -> None: ...
    async def resize(self, rows: int, cols: int) -> None: ...
    async def detach(self) -> None: ...
    def __aiter__(self) -> JobAttachment: ...
    async def __anext__(self) -> JobEvent: ...

class JobLogStream:
    async def close(self) -> None: ...
    def __aiter__(self) -> JobLogStream: ...
    async def __anext__(self) -> JobLogEntry: ...


class SnapshotGroup:
    @staticmethod
    def local() -> Snapshots: ...
    @staticmethod
    def remote() -> Snapshots: ...
    @staticmethod
    def ctx(context: Context) -> Snapshots: ...
    @property
    def context(self) -> Context: ...
    async def inspect(self) -> SnapshotGroupInfo: ...
    async def remove(self) -> SnapshotRemoveResult: ...
    async def verify(self) -> dict[str, Any]: ...
    @staticmethod
    async def load(
        group: str,
        files: list[str | os.PathLike[str]],
        *,
        dest: str | os.PathLike[str] | None = None,
        base: str | None = None,
        set_head: bool = False,
    ) -> SnapshotImportResult: ...
    async def spawn_sandbox(self, *, name: str | None = None, **kwargs: Any) -> Sandbox: ...
    async def spawn_sandbox_with_progress(
        self, *, name: str | None = None, **kwargs: Any
    ) -> PullSession: ...
    """Named checkpoint history; a cleared head does not remove its members."""
    @staticmethod
    async def get(name: str) -> SnapshotGroup: ...
    @staticmethod
    async def open(path: str | os.PathLike[str]) -> SnapshotGroup: ...
    @staticmethod
    async def list() -> list[SnapshotGroup]: ...
    @property
    def name(self) -> str: ...
    async def head(self) -> Snapshot | None: ...
    async def checkpoints(self) -> list[Snapshot]: ...
    async def get_checkpoint(self, member: str) -> Snapshot: ...
    async def set_head(self, member: str) -> dict[str, Any]: ...
    async def clear_head(self) -> dict[str, Any]: ...
    async def checkpoint(
        self,
        *,
        name: str | None = None,
        labels: dict[str, str] | None = None,
        full: bool = False,
        record_integrity: bool = False,
        guest_flush: str | None = None,
    ) -> CheckpointCaptureResult: ...

class SnapshotCreateResult:
    @property
    def snapshot(self) -> SnapshotGroup: ...
    @property
    def checkpoint(self) -> Snapshot: ...
    @property
    def head_update(self) -> dict[str, Any]: ...

class CheckpointCaptureResult:
    @property
    def checkpoint(self) -> Snapshot: ...
    @property
    def head_update(self) -> dict[str, Any]: ...

class SnapshotImportResult:
    @property
    def operation_id(self) -> str: ...
    @property
    def snapshot(self) -> SnapshotGroup: ...
    @property
    def checkpoints(self) -> list[Snapshot]: ...
    @property
    def added(self) -> list[str]: ...
    @property
    def reused(self) -> list[str]: ...
    @property
    def head_update(self) -> dict[str, Any]: ...
    @property
    def warnings(self) -> list[str]: ...

class CheckpointRemoveResult:
    """One removal's committed identity and head outcome; never a later head read."""
    @property
    def id(self) -> str: ...
    @property
    def head_update(self) -> dict[str, Any] | None: ...
    @property
    def warnings(self) -> list[str]: ...

class SnapshotRemoveResult:
    """Whole-history removal and its operation-owned head outcome."""
    @property
    def group(self) -> str: ...
    @property
    def removed(self) -> list[str]: ...
    @property
    def head_update(self) -> dict[str, Any]: ...
    @property
    def warnings(self) -> list[str]: ...

async def diagnose_storage(config_json: str, selection_json: str) -> str: ...

class Context:
    def __new__(cls, options_json: str, base: Context | None = None) -> Context: ...
    @property
    def kind(self) -> ContextKind: ...
    @property
    def sandboxes(self) -> Sandboxes: ...
    @property
    def volumes(self) -> Volumes: ...
    @property
    def snapshots(self) -> Snapshots: ...
    @property
    def checkpoints(self) -> Checkpoints: ...

class Sandboxes:
    async def restore(
        self, snapshot: Snapshot | str | os.PathLike[str], *, name: str, **kwargs: Any
    ) -> Sandbox: ...
    def restore_with_progress(
        self, snapshot: Snapshot | str | os.PathLike[str], *, name: str, **kwargs: Any
    ) -> PullSession: ...
    def create_with_progress(
        self,
        name: str,
        *,
        image: str | os.PathLike[str] | ImageSource | None = None,
        memory: int | Size | None = None,
        cpus: int | None = None,
        max_memory: int | Size | None = None,
        max_cpus: int | None = None,
        cpu_placement: CpuPlacement | Literal["inherit", "auto", "spread", "compact"] | None = None,
        placement_profile: str | None = None,
        thp: Literal["always", "madvise", "never"] | None = None,
        nested_virt: bool | None = None,
        workdir: str | None = None,
        shell: str | None = None,
        security: SecurityProfile | None = None,
        deployment_profile: DeploymentProfile | None = None,
        hostname: str | None = None,
        user: str | None = None,
        entrypoint: Sequence[str] | None = None,
        cmd: Sequence[str] | None = None,
        init: str | InitConfig | InitOptions | None = None,
        replace: bool = False,
        replace_with_timeout: float | timedelta | None = None,
        max_duration: float | timedelta | None = None,
        idle_timeout: float | timedelta | None = None,
        ephemeral: bool = False,
        env: Mapping[str, str] | None = None,
        labels: Mapping[str, str] | None = None,
        scripts: Mapping[str, str] | None = None,
        pull_policy: PullPolicy | None = None,
        log_level: LogLevel | None = None,
        registry_auth: RegistryAuth | None = None,
        registry_insecure: bool = False,
        registry_ca_certs: builtins.list[bytes | bytearray | str | os.PathLike[str]] | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
        patches: Sequence[PatchConfig] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        vsock: Mapping[str, int] | Sequence[VsockRoute] | None = None,
        network: Network | None = None,
        intercept_tls: bool = False,
        proxy: OutboundProxy | None = None,
        secrets: Sequence[SecretEntry] | None = None,
        secret_violation_action: ViolationAction | None = None,
        detached: bool = False,
    ) -> PullSession: ...
    @property
    def context(self) -> Context: ...
    async def create(
        self,
        name: str,
        *,
        image: str | os.PathLike[str] | ImageSource | None = None,
        memory: int | Size | None = None,
        cpus: int | None = None,
        max_memory: int | Size | None = None,
        max_cpus: int | None = None,
        cpu_placement: CpuPlacement | Literal["inherit", "auto", "spread", "compact"] | None = None,
        placement_profile: str | None = None,
        thp: Literal["always", "madvise", "never"] | None = None,
        nested_virt: bool | None = None,
        workdir: str | None = None,
        shell: str | None = None,
        security: SecurityProfile | None = None,
        deployment_profile: DeploymentProfile | None = None,
        hostname: str | None = None,
        user: str | None = None,
        entrypoint: Sequence[str] | None = None,
        cmd: Sequence[str] | None = None,
        init: str | InitConfig | InitOptions | None = None,
        replace: bool = False,
        replace_with_timeout: float | timedelta | None = None,
        max_duration: float | timedelta | None = None,
        idle_timeout: float | timedelta | None = None,
        ephemeral: bool = False,
        env: Mapping[str, str] | None = None,
        labels: Mapping[str, str] | None = None,
        scripts: Mapping[str, str] | None = None,
        pull_policy: PullPolicy | None = None,
        log_level: LogLevel | None = None,
        registry_auth: RegistryAuth | None = None,
        registry_insecure: bool = False,
        registry_ca_certs: list[bytes | bytearray | str | os.PathLike[str]] | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
        patches: Sequence[PatchConfig] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        vsock: Mapping[str, int] | Sequence[VsockRoute] | None = None,
        network: Network | None = None,
        intercept_tls: bool = False,
        proxy: OutboundProxy | None = None,
        secrets: Sequence[SecretEntry] | None = None,
        secret_violation_action: ViolationAction | None = None,
        detached: bool = False,
    ) -> Sandbox: ...
    async def connect_or_create(
        self,
        name: str,
        *,
        image: str | os.PathLike[str] | ImageSource | None = None,
        memory: int | Size | None = None,
        cpus: int | None = None,
        max_memory: int | Size | None = None,
        max_cpus: int | None = None,
        cpu_placement: CpuPlacement | Literal["inherit", "auto", "spread", "compact"] | None = None,
        placement_profile: str | None = None,
        thp: Literal["always", "madvise", "never"] | None = None,
        nested_virt: bool | None = None,
        workdir: str | None = None,
        shell: str | None = None,
        security: SecurityProfile | None = None,
        deployment_profile: DeploymentProfile | None = None,
        hostname: str | None = None,
        user: str | None = None,
        entrypoint: Sequence[str] | None = None,
        cmd: Sequence[str] | None = None,
        init: str | InitConfig | InitOptions | None = None,
        replace: bool = False,
        replace_with_timeout: float | timedelta | None = None,
        max_duration: float | timedelta | None = None,
        idle_timeout: float | timedelta | None = None,
        ephemeral: bool = False,
        env: Mapping[str, str] | None = None,
        labels: Mapping[str, str] | None = None,
        scripts: Mapping[str, str] | None = None,
        pull_policy: PullPolicy | None = None,
        log_level: LogLevel | None = None,
        registry_auth: RegistryAuth | None = None,
        registry_insecure: bool = False,
        registry_ca_certs: list[bytes | bytearray | str | os.PathLike[str]] | None = None,
        volumes: Mapping[str, MountConfig] | None = None,
        patches: Sequence[PatchConfig] | None = None,
        ports: Mapping[int, int] | Sequence[PortBinding] | None = None,
        vsock: Mapping[str, int] | Sequence[VsockRoute] | None = None,
        network: Network | None = None,
        intercept_tls: bool = False,
        proxy: OutboundProxy | None = None,
        secrets: Sequence[SecretEntry] | None = None,
        secret_violation_action: ViolationAction | None = None,
        detached: bool = False,
    ) -> Sandbox: ...
    async def get(self, name: str) -> Sandbox: ...
    async def get_running(self, name: str) -> Sandbox: ...
    async def start(self, name: str, *, detached: bool = False) -> Sandbox: ...
    async def list(
        self,
        *,
        limit: int | None = None,
        cursor: str | None = None,
        labels: dict[str, str] | None = None,
    ) -> SandboxPage: ...
    async def remove(self, name: str) -> None: ...

class Volumes:
    @property
    def context(self) -> Context: ...
    async def create(
        self,
        name: str,
        *,
        kind: VolumeKind | None = None,
        size_mib: int | None = None,
        quota_mib: int | None = None,
        labels: dict[str, str] | None = None,
    ) -> Volume: ...
    async def get(self, name: str) -> Volume: ...
    async def get_default(self) -> Volume: ...
    async def list(self) -> list[Volume]: ...
    async def remove(self, name: str) -> None: ...

class Checkpoints:
    async def group_head(self, group: str) -> str | None: ...
    async def set_group_head(self, group: str, id: str) -> dict[str, str | bool | None]: ...
    @property
    def context(self) -> Context: ...
    async def create(
        self,
        name: str = "",
        *,
        from_sandbox: str,
        group: str | None = None,
        dest_dir: str | os.PathLike[str] | None = None,
        labels: dict[str, str] | None = None,
        force: bool = False,
        record_integrity: bool = False,
        full: bool = False,
        guest_flush: GuestFlush | None = None,
    ) -> Snapshot: ...
    async def get(self, reference: str) -> Snapshot: ...
    async def list(self) -> list[Snapshot]: ...
    async def remove(self, reference: str, *, force: bool = False) -> None: ...


class Snapshots:
    async def load(
        self,
        group: str,
        files: list[str | os.PathLike[str]],
        *,
        dest: str | os.PathLike[str] | None = None,
        base: str | None = None,
        set_head: bool = False,
    ) -> SnapshotImportResult: ...
    @property
    def context(self) -> Context: ...
    async def open(self, path: str | os.PathLike[str]) -> SnapshotGroup: ...
    async def get(self, name: str) -> SnapshotGroup: ...
    async def list(self) -> list[SnapshotGroup]: ...
