Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

62.0 KB
Raw Blame
# Copyright 2025 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
Pydantic schemas for OpenSandbox Lifecycle API.

This module defines data models based on the OpenAPI specification
for request/response validation and serialization.
"""

import ipaddress
from datetime import datetime
from typing import Dict, List, Literal, Optional

from pydantic import BaseModel, Field, PrivateAttr, RootModel, field_validator, model_validator

from opensandbox_server.constants import (
    IDLE_TIMEOUT_MAX_SECONDS,
    IDLE_TIMEOUT_MIN_SECONDS,
    PROBE_TIMEOUT_MAX_SECONDS,
    PROBE_TIMEOUT_MIN_SECONDS,
    RENEW_EXTEND_MAX_SECONDS,
    RENEW_EXTEND_MIN_SECONDS,
)
from opensandbox_server.constants import OPENSANDBOX_LIFECYCLE


def _is_ip_or_cidr(value: str) -> bool:
    """
    Mirror policy.go's target-kind detection (netip.ParseAddr/ParsePrefix): a
    target is IP/CIDR if it parses as either; anything else (including
    domains) is not.
    """
    try:
        ipaddress.ip_address(value)
        return True
    except ValueError:
        pass
    # netip.ParsePrefix rejects netmask notation and scoped prefixes; the
    # sidecar would classify both as domains, so mirror it.
    if "/" in value and (not value.partition("/")[2].isdigit() or "%" in value):
        return False
    try:
        ipaddress.ip_network(value, strict=False)
        return True
    except ValueError:
        return False

# ============================================================================
# Image Specification
# ============================================================================

class ImageAuth(BaseModel):
    """
    Registry authentication credentials for private container registries.
    """
    username: str = Field(..., description="Registry username or service account")
    password: str = Field(..., description="Registry password or authentication token")


class ImageSpec(BaseModel):
    """
    Container image specification for sandbox provisioning.

    Supports public registry images and private registry images with authentication.
    """
    uri: str = Field(
        ...,
        description="Container image URI in standard format (e.g., 'python:3.11', 'gcr.io/my-project/app:v1.0')",
    )
    auth: Optional[ImageAuth] = Field(
        None,
        description="Registry authentication credentials (required for private registries)",
    )


class PlatformSpec(BaseModel):
    """
    Runtime platform constraint for scheduling/provisioning.
    """

    os: str = Field(
        ...,
        description="Target operating system (for example 'linux').",
    )
    arch: str = Field(
        ...,
        description="Target CPU architecture (for example 'amd64' or 'arm64').",
    )


# ============================================================================
# Resource Limits
# ============================================================================

class ResourceLimits(RootModel[Dict[str, str]]):
    """
    Runtime resource constraints as key-value pairs.

    Similar to Kubernetes resource specifications, allows flexible definition
    of resource limits. Common resource types include cpu, memory, and gpu.
    """
    root: Dict[str, str] = Field(
        default_factory=dict,
        example={"cpu": "500m", "memory": "512Mi", "gpu": "1"},
    )


class NetworkRule(BaseModel):
    """
    Egress rule: allow/deny a domain, wildcard, IP/CIDR, and/or a set of TCP ports.
    """

    action: str = Field(..., description="Whether to allow or deny matching targets (allow | deny).")
    target: Optional[str] = Field(
        None,
        description=(
            "FQDN, wildcard domain (e.g., 'example.com', '*.example.com'), IP address, or CIDR. "
            "May be omitted when `ports` is set; otherwise required. Blank normalizes to omitted "
            "(the sidecar marshals port-only rules as \"target\": \"\" on read-back)."
        ),
    )
    ports: Optional[List[int]] = Field(
        None,
        min_length=1,
        max_length=256,
        description=(
            "Restricts this rule to specific TCP destination ports (1-65535). Omitted target with "
            "ports set applies to all destinations; a domain target with ports is rejected. TCP "
            "only, max 256 ports per rule."
        ),
    )

    @field_validator("target")
    @classmethod
    def normalize_target(cls, target: Optional[str]) -> Optional[str]:
        # Mirror policy.go: trim before classifying.
        if target is None:
            return None
        target = target.strip()
        return target or None

    @field_validator("ports")
    @classmethod
    def validate_ports(cls, ports: Optional[List[int]]) -> Optional[List[int]]:
        # Mirrors policy.go's normalizePorts.
        if ports is None:
            return ports
        seen: set[int] = set()
        for port in ports:
            if port < 1 or port > 65535:
                raise ValueError(f"NetworkRule port {port} out of range 1-65535.")
            if port in seen:
                raise ValueError(f"NetworkRule has duplicate port {port}.")
            seen.add(port)
        return ports

    @model_validator(mode="after")
    def validate_target_or_ports(self) -> "NetworkRule":
        if self.target is None and self.ports is None:
            raise ValueError("NetworkRule requires target, ports, or both.")
        if self.ports is not None and self.target is not None and not _is_ip_or_cidr(self.target):
            raise ValueError("NetworkRule ports are not supported for domain targets yet.")
        return self

    class Config:
        populate_by_name = True
        extra = "forbid"


class NetworkPolicy(BaseModel):
    """
    Egress network policy matching the sidecar /policy payload.
    """

    default_action: Optional[str] = Field(
        default=None,
        alias="defaultAction",
        description="Default action when no egress rule matches (allow | deny). If omitted, sidecar defaults to deny.",
    )
    egress: list[NetworkRule] = Field(
        default_factory=list,
        description="Ordered egress rules. Empty/omitted yields allow-all at startup.",
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class CredentialProxyConfig(BaseModel):
    """
    Credential proxy startup options.
    """

    enabled: bool = Field(
        False,
        description=(
            "When true, the server enables transparent MITM support required by "
            "Credential Vault injection. Plain egress network policy does not enable "
            "transparent MITM unless this option is set."
        ),
    )

    class Config:
        populate_by_name = True


# ============================================================================
# Credential Vault (server-routed; mirrors specs/egress-api.yaml sidecar shapes)
# ============================================================================


class InlineCredentialSource(BaseModel):
    type: Literal["inline"] = Field(..., description="Credential source type.")
    value: str = Field(
        ...,
        description="Write-only credential value; never returned on any read.",
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class ExchangeCredentialSource(BaseModel):
    """Exchange source (OSEP-0025); endpoint semantics stay with the egress."""

    type: Literal["exchange"] = Field(..., description="Credential source type.")
    endpoint: str = Field(
        ...,
        description="Header-resolver endpoint; egress validates the scheme.",
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class Credential(BaseModel):
    name: str = Field(..., min_length=1, description="Unique credential name.")
    source: InlineCredentialSource | ExchangeCredentialSource = Field(
        ..., description="Credential value source."
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class CredentialSubstitution(BaseModel):
    """Literal case-sensitive placeholder replacement for selected request surfaces."""

    credential: str = Field(..., min_length=1, description="Credential name used as the replacement value.")
    placeholder: str = Field(..., min_length=1, description="Literal placeholder to replace.")
    in_: list[Literal["path", "query", "header", "body"]] = Field(
        ...,
        min_length=1,
        alias="in",
        description="Request surfaces where the placeholder may be replaced.",
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class CustomHeaderEntry(BaseModel):
    name: str = Field(
        ...,
        pattern=r"^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$",
        description="Header name injected by the binding.",
    )
    credential: str = Field(..., min_length=1, description="Credential name whose value is injected.")

    class Config:
        populate_by_name = True
        extra = "forbid"


class BearerCredentialAuth(BaseModel):
    type: Literal["bearer"]
    credential: str = Field(..., min_length=1, description="Credential name whose value becomes the bearer token.")
    substitutions: Optional[list[CredentialSubstitution]] = Field(
        default=None, description="Optional placeholder substitutions scoped to this binding."
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class BasicCredentialAuth(BaseModel):
    type: Literal["basic"]
    credential: str = Field(
        ...,
        min_length=1,
        description="Credential containing pre-encoded base64(username:password).",
    )
    substitutions: Optional[list[CredentialSubstitution]] = None

    class Config:
        populate_by_name = True
        extra = "forbid"


class ApiKeyCredentialAuth(BaseModel):
    type: Literal["apiKey"]
    name: str = Field(
        ...,
        pattern=r"^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$",
        description="Header name receiving the API key.",
    )
    credential: str = Field(..., min_length=1, description="Credential name whose value is the API key.")
    substitutions: Optional[list[CredentialSubstitution]] = None

    class Config:
        populate_by_name = True
        extra = "forbid"


class CustomHeadersCredentialAuth(BaseModel):
    type: Literal["customHeaders"]
    headers: list[CustomHeaderEntry] = Field(..., min_length=1, description="Headers injected by this binding.")
    substitutions: Optional[list[CredentialSubstitution]] = None

    class Config:
        populate_by_name = True
        extra = "forbid"


class PassthroughCredentialAuth(BaseModel):
    type: Literal["passthrough"]
    substitutions: Optional[list[CredentialSubstitution]] = None

    class Config:
        populate_by_name = True
        extra = "forbid"


class ExchangeCredentialAuth(BaseModel):
    """Typeless exchange auth (OSEP-0025); the cross-lock is egress-owned."""

    credential: str = Field(
        ...,
        min_length=1,
        description="Name of the exchange-sourced credential to resolve per request.",
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


# No discriminator: the typeless variant carries no `type` key, so union
# members are mutually exclusive by shape.
CredentialAuth = (
    BearerCredentialAuth
    | BasicCredentialAuth
    | ApiKeyCredentialAuth
    | CustomHeadersCredentialAuth
    | PassthroughCredentialAuth
    | ExchangeCredentialAuth
)


class CredentialMatch(BaseModel):
    schemes: Optional[list[Literal["https", "http"]]] = Field(
        default=None, description="Schemes the binding matches; defaults to [https]."
    )
    ports: Optional[list[int]] = Field(
        default=None,
        deprecated=True,
        description="Deprecated. Port is derived from scheme; other values are rejected with a validation error.",
    )
    hosts: list[str] = Field(..., min_length=1, description="Host patterns (FQDN or wildcard domain).")
    methods: Optional[list[str]] = Field(
        default=None,
        description="HTTP methods the binding matches; defaults to GET, POST, PUT, PATCH, DELETE.",
    )
    paths: Optional[list[str]] = Field(
        default=None, description="Path patterns the binding matches; defaults to ['/*']."
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class CredentialBinding(BaseModel):
    name: str = Field(..., min_length=1, description="Unique binding name.")
    match: CredentialMatch = Field(..., description="Request matcher for credential injection.")
    auth: CredentialAuth = Field(..., description="Injected credential shape.")

    class Config:
        populate_by_name = True
        extra = "forbid"


class CredentialVaultCreateRequest(BaseModel):
    """Create the initial Credential Vault revision (create-only)."""

    credentials: list[Credential] = Field(..., description="Initial credentials (inline sources).")
    bindings: list[CredentialBinding] = Field(..., description="Initial credential bindings.")

    class Config:
        populate_by_name = True
        extra = "forbid"


class CredentialMutationSet(BaseModel):
    add: Optional[list[Credential]] = Field(
        default=None, description="Credentials to create; fails when a name already exists."
    )
    replace: Optional[list[Credential]] = Field(
        default=None, description="Credentials to replace; fails when a name does not exist."
    )
    delete: Optional[list[str]] = Field(
        default=None, description="Credential names to remove; fails when a name does not exist."
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class CredentialBindingMutationSet(BaseModel):
    add: Optional[list[CredentialBinding]] = Field(
        default=None, description="Bindings to create; fails when a name already exists."
    )
    replace: Optional[list[CredentialBinding]] = Field(
        default=None, description="Bindings to replace; fails when a name does not exist."
    )
    delete: Optional[list[str]] = Field(
        default=None, description="Binding names to remove; fails when a name does not exist."
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class CredentialVaultMutationRequest(BaseModel):
    """Atomically mutate credentials and bindings (server-side merge commit)."""

    expected_revision: Optional[int] = Field(
        default=None,
        alias="expectedRevision",
        description="Optional optimistic concurrency guard; mismatch fails with 412.",
    )
    credentials: Optional[CredentialMutationSet] = Field(
        default=None, description="Credential mutations (add/replace/delete)."
    )
    bindings: Optional[CredentialBindingMutationSet] = Field(
        default=None, description="Binding mutations (add/replace/delete)."
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class CredentialAuthMetadata(BaseModel):
    """Sanitized auth shape; the typeless form carries `credential` only."""

    type: Optional[str] = Field(
        default=None, description="Injected credential shape type."
    )
    name: Optional[str] = Field(
        default=None, description="Header name, for the apiKey shape only."
    )
    credential: Optional[str] = Field(
        default=None,
        description="Exchange-sourced credential name, typeless form only.",
    )

    class Config:
        populate_by_name = True


class CredentialMetadata(BaseModel):
    name: str
    source_type: str = Field(
        ...,
        alias="sourceType",
        description="Credential source kind (inline or exchange).",
    )
    revision: int

    class Config:
        populate_by_name = True


class CredentialBindingMetadata(BaseModel):
    name: str
    revision: int
    match: Optional[CredentialMatch] = None
    auth: Optional[CredentialAuthMetadata] = None

    class Config:
        populate_by_name = True


class CredentialVaultState(BaseModel):
    """Sanitized Credential Vault state — credential values never appear."""

    revision: int
    credentials: list[CredentialMetadata]
    bindings: list[CredentialBindingMetadata]

    class Config:
        populate_by_name = True


class CredentialListResponse(BaseModel):
    revision: int
    credentials: list[CredentialMetadata]

    class Config:
        populate_by_name = True


class CredentialBindingListResponse(BaseModel):
    revision: int
    bindings: list[CredentialBindingMetadata]

    class Config:
        populate_by_name = True


class LifecycleHook(BaseModel):
    """Command executed by execd before the user entrypoint starts."""

    command: List[str] = Field(..., min_length=1)
    timeout_seconds: Optional[int] = Field(None, alias="timeoutSeconds", ge=1, le=10800)

    @model_validator(mode="after")
    def validate_command(self) -> "LifecycleHook":
        if not self.command[0].strip():
            raise ValueError("Lifecycle hook command must not be empty.")
        return self

    class Config:
        populate_by_name = True
        extra = "forbid"


class PeriodicLifecycleHook(BaseModel):
    """Named command scheduled by execd while the sandbox is running."""

    name: str = Field(..., min_length=1)
    schedule: str = Field(..., min_length=1)
    command: List[str] = Field(..., min_length=1)
    timeout_seconds: Optional[int] = Field(None, alias="timeoutSeconds", ge=1, le=300)

    @model_validator(mode="after")
    def normalize_and_validate(self) -> "PeriodicLifecycleHook":
        self.name = self.name.strip()
        self.schedule = self.schedule.strip()
        if not self.name:
            raise ValueError("Periodic lifecycle hook name must not be blank.")
        if not self.schedule:
            raise ValueError("Periodic lifecycle hook schedule must not be blank.")
        if not self.command[0].strip():
            raise ValueError("Periodic lifecycle hook command must not be empty.")
        return self

    class Config:
        populate_by_name = True
        extra = "forbid"


class ActivityProbe(BaseModel):
    """App-declared activity probe (``idlePolicy.activeProbe``, OSEP-0024).

    ``GET {path}`` on ``{port}`` answering ``200 {"active": true}`` counts
    as activity and resets the idle clock.
    """

    port: int = Field(..., ge=1, le=65535)
    path: str = Field(..., min_length=1, max_length=512)
    timeout_seconds: Optional[int] = Field(
        None,
        alias="timeoutSeconds",
        ge=PROBE_TIMEOUT_MIN_SECONDS,
        le=PROBE_TIMEOUT_MAX_SECONDS,
    )

    @model_validator(mode="after")
    def validate_path(self) -> "ActivityProbe":
        if not self.path.startswith("/"):
            raise ValueError("idlePolicy.activeProbe.path must be an absolute HTTP path.")
        if any(ord(char) < 0x20 or char == "\x7f" or char.isspace() for char in self.path):
            raise ValueError(
                "idlePolicy.activeProbe.path must not contain whitespace or control characters."
            )
        return self

    class Config:
        populate_by_name = True
        extra = "forbid"


class IdlePolicy(BaseModel):
    """Idle behavior declared by the sandbox (OSEP-0024).

    With a timeout the sandbox is auto-paused after X idle seconds; without
    it the policy is wake-only. Omitting ``idlePolicy`` preserves today's
    behavior exactly.
    """

    idle_timeout_seconds: Optional[int] = Field(
        None,
        alias="idleTimeoutSeconds",
        ge=IDLE_TIMEOUT_MIN_SECONDS,
        le=IDLE_TIMEOUT_MAX_SECONDS,
        description="Idle threshold X in seconds. Absent means a wake-only policy.",
    )
    on_idle: Optional[Literal["pause"]] = Field(
        None,
        alias="onIdle",
        description="Action taken at the idle threshold; only 'pause' exists today.",
    )
    wake_on_access: bool = Field(
        True,
        alias="wakeOnAccess",
        description=(
            "Whether traffic may wake the sandbox from Paused. False keeps "
            "today's manual-resume-only behavior."
        ),
    )
    active_probe: Optional[ActivityProbe] = Field(None, alias="activeProbe")

    @model_validator(mode="after")
    def validate_pairing(self) -> "IdlePolicy":
        if self.idle_timeout_seconds is None:
            if self.on_idle is not None:
                raise ValueError(
                    "idlePolicy.onIdle must be omitted when idleTimeoutSeconds is omitted "
                    "(a policy without a timeout is wake-only)."
                )
            if self.active_probe is not None:
                raise ValueError(
                    "idlePolicy.activeProbe requires idleTimeoutSeconds; the probe "
                    "governs auto-pause and a wake-only policy is never probed."
                )
        elif self.on_idle is None:
            raise ValueError(
                "idlePolicy.onIdle is required when idleTimeoutSeconds is set."
            )
        return self

    class Config:
        populate_by_name = True
        extra = "forbid"


class RenewalPolicy(BaseModel):
    """Renew-on-access behavior (OSEP-0009): observed access moves the
    expiration to ``max(now + extendSeconds, current)``. Control-plane
    policy; supersedes the deprecated ``access.renew.extend.seconds``
    extensions key.
    """

    extend_seconds: int = Field(
        ...,
        alias="extendSeconds",
        ge=RENEW_EXTEND_MIN_SECONDS,
        le=RENEW_EXTEND_MAX_SECONDS,
        description=(
            "Extension window X in seconds for each access-driven renewal: "
            "the expiration is moved to max(now + X, current expiresAt)."
        ),
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class SandboxLifecycle(BaseModel):
    """Extensible lifecycle configuration: hooks run in the guest via execd;
    ``idlePolicy`` (OSEP-0024) and ``renewalPolicy`` (OSEP-0009) are
    control-plane state and never reach it.
    """

    pre_start: Optional[LifecycleHook] = Field(None, alias="preStart")
    periodic: Optional[List[PeriodicLifecycleHook]] = None
    idle_policy: Optional[IdlePolicy] = Field(
        None,
        alias="idlePolicy",
        description="Auto-pause and wake-on-access behavior (fast-sandbox backend only).",
    )
    renewal_policy: Optional[RenewalPolicy] = Field(
        None,
        alias="renewalPolicy",
        description=(
            "Renew-on-access behavior (OSEP-0009); control-plane state. "
            "Supersedes the deprecated access.renew.extend.seconds extensions key."
        ),
    )

    @property
    def has_hooks(self) -> bool:
        return self.pre_start is not None or bool(self.periodic)

    @model_validator(mode="after")
    def validate_periodic_names(self) -> "SandboxLifecycle":
        names = [hook.name for hook in self.periodic or []]
        if len(names) != len(set(names)):
            raise ValueError("Periodic lifecycle hook names must be unique.")
        return self

    class Config:
        populate_by_name = True
        extra = "forbid"


# ============================================================================
# Volume Definitions
# ============================================================================


class Host(BaseModel):
    """
    Host path bind mount backend.

    Maps a directory on the host filesystem into the container.
    Only available when the runtime supports host mounts.

    Security note: Host paths are restricted by server-side allowlist.
    Users must specify paths under permitted prefixes.
    """

    path: str = Field(
        ...,
        description="Absolute path on the host filesystem to mount.",
        pattern=r"^(/|[A-Za-z]:[\\/])",
    )


class PVC(BaseModel):
    """
    Platform-managed named volume backend.

    A runtime-neutral abstraction for referencing a platform-managed named volume.
    If ``createIfNotExists`` is true (the default) and the volume does not
    yet exist, it will be created automatically using the provisioning hints below.

    - Kubernetes: maps to a PersistentVolumeClaim in the same namespace.
    - Docker: maps to a Docker named volume (created via ``docker volume create``).
    """

    claim_name: str = Field(
        ...,
        alias="claimName",
        description=(
            "Name of the volume on the target platform. "
            "In Kubernetes this is the PVC name; in Docker this is the named volume name."
        ),
        pattern=r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
        max_length=253,
    )

    create_if_not_exists: bool = Field(
        True,
        alias="createIfNotExists",
        description=(
            "When true, the volume is automatically created if it does not exist. "
            "When false, referencing a non-existent volume fails with an error."
        ),
    )
    delete_on_sandbox_termination: bool = Field(
        False,
        alias="deleteOnSandboxTermination",
        description=(
            "When true, the volume is automatically removed when the sandbox is "
            "deleted. Only applies to volumes that were auto-created by the server "
            "on this request; pre-existing volumes are never removed. For "
            "Kubernetes, the resulting PVC delete then triggers the bound PV's "
            "StorageClass reclaim policy (Retain/Delete)."
        ),
    )

    # Provisioning hints — used only when auto-creating a new volume.
    # Ignored if the volume already exists on the platform.
    storage_class: Optional[str] = Field(
        None,
        alias="storageClass",
        description=(
            "Kubernetes StorageClass name for auto-created PVCs. "
            "None means use the cluster default. Ignored for Docker volumes."
        ),
    )
    storage: Optional[str] = Field(
        None,
        description=(
            "Storage capacity request for auto-created PVCs (e.g. '1Gi', '10Gi'). "
            "Defaults to server-side configured value when omitted. "
            "Ignored for Docker volumes."
        ),
        pattern=r"^\d+(\.\d+)?(Ki|Mi|Gi|Ti|Pi|Ei)?$",
    )
    access_modes: Optional[List[str]] = Field(
        None,
        alias="accessModes",
        description=(
            "Access modes for auto-created PVCs (e.g. ['ReadWriteOnce']). "
            "Defaults to ['ReadWriteOnce'] when omitted. Ignored for Docker volumes."
        ),
    )

    class Config:
        populate_by_name = True


class OSSFS(BaseModel):
    """
    Alibaba Cloud OSS mount backend via ossfs.

    The runtime mounts a host-side OSS path under ``storage.ossfs_mount_root``
    and then bind-mounts the resolved path into the sandbox container. Prefix
    selection is expressed via ``Volume.subPath``.
    In Docker runtime, OSSFS backend requires the server host to be Linux with FUSE support.
    """

    bucket: str = Field(
        ...,
        description="OSS bucket name.",
        min_length=3,
        max_length=63,
    )
    endpoint: str = Field(
        ...,
        description="OSS endpoint, e.g. 'oss-cn-hangzhou.aliyuncs.com'.",
        min_length=1,
    )
    version: Literal["1.0", "2.0"] = Field(
        "2.0",
        description="ossfs major version used by runtime mount integration.",
    )
    options: Optional[List[str]] = Field(
        None,
        description=(
            "Additional ossfs mount options. Runtime encodes options by version: "
            "1.0 => 'ossfs ... -o <option>', 2.0 => 'ossfs2 config line --<option>'. "
            "Provide raw option payloads without leading '-'."
        ),
    )
    access_key_id: Optional[str] = Field(
        None,
        alias="accessKeyId",
        description="OSS access key ID for inline credentials mode.",
        min_length=1,
    )
    access_key_secret: Optional[str] = Field(
        None,
        alias="accessKeySecret",
        description="OSS access key secret for inline credentials mode.",
        min_length=1,
    )
    class Config:
        populate_by_name = True

    @model_validator(mode="after")
    def validate_inline_credentials(self) -> "OSSFS":
        """Ensure inline credentials are provided for current OSSFS mode."""
        if not self.access_key_id or not self.access_key_secret:
            raise ValueError(
                "OSSFS inline credentials are required: accessKeyId and accessKeySecret."
            )
        return self


class Volume(BaseModel):
    """
    Storage mount definition for a sandbox.

    Each volume entry contains:
    - A unique name identifier
    - Exactly one backend struct (host, pvc, etc.) with backend-specific fields
    - Common mount settings (mountPath, readOnly, subPath)
    """

    name: str = Field(
        ...,
        description="Unique identifier for the volume within the sandbox.",
        pattern=r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
        max_length=63,
    )
    host: Optional[Host] = Field(
        None,
        description="Host path bind mount backend.",
    )
    pvc: Optional[PVC] = Field(
        None,
        description="Platform-managed named volume backend (PVC in Kubernetes, named volume in Docker).",
    )
    ossfs: Optional[OSSFS] = Field(
        None,
        description="OSSFS mount backend.",
    )
    mount_path: str = Field(
        ...,
        alias="mountPath",
        description="Absolute path inside the container where the volume is mounted.",
        pattern=r"^/.*",
    )
    read_only: bool = Field(
        False,
        alias="readOnly",
        description="If true, the volume is mounted as read-only. Defaults to false (read-write).",
    )
    sub_path: Optional[str] = Field(
        None,
        alias="subPath",
        description="Optional subdirectory under the backend path to mount.",
    )

    class Config:
        populate_by_name = True

    @model_validator(mode="after")
    def validate_exactly_one_backend(self) -> "Volume":
        """Ensure exactly one backend type is specified."""
        backends = [self.host, self.pvc, self.ossfs]
        specified = [b for b in backends if b is not None]
        if len(specified) == 0:
            raise ValueError("Exactly one backend (host, pvc, ossfs) must be specified, but none was provided.")
        if len(specified) > 1:
            raise ValueError("Exactly one backend (host, pvc, ossfs) must be specified, but multiple were provided.")
        return self


# ============================================================================
# Sandbox Status
# ============================================================================

class SandboxStatus(BaseModel):
    """
    Detailed status information with lifecycle state and transition details.
    """
    state: str = Field(
        ...,
        description="Current lifecycle state (Pending, Running, Pausing, Paused, Resuming, Stopping, Terminated, Failed)",
    )
    reason: Optional[str] = Field(
        None,
        description="Short machine-readable reason code for the current state",
    )
    message: Optional[str] = Field(
        None,
        description="Human-readable message describing the current state or reason for state transition",
    )
    last_transition_at: Optional[datetime] = Field(
        None,
        alias="lastTransitionAt",
        description="Timestamp of the last state transition",
    )

    class Config:
        populate_by_name = True


# ============================================================================
# Sandbox Models
# ============================================================================

class CreateSandboxRequest(BaseModel):
    """
    Request to create a new sandbox from either a container image or a snapshot.
    """

    # Internal routing hint: set by snapshot restore resolution to the backend
    # that produced the snapshot (e.g. "fsb"); never serialized on the wire.
    _resolved_snapshot_backend: Optional[str] = PrivateAttr(default=None)

    image: Optional[ImageSpec] = Field(
        None,
        description="Container image specification for the sandbox",
    )
    snapshot_id: Optional[str] = Field(
        None,
        alias="snapshotId",
        description="Snapshot identifier to restore from",
    )
    platform: Optional[PlatformSpec] = Field(
        None,
        description=(
            "Optional platform constraint for sandbox scheduling/runtime selection. "
            "If omitted, runtime default behavior applies (runtime-specific and not a fixed "
            "architecture guarantee). If specified, runtime must satisfy this platform or fail "
            "explicitly."
        ),
    )
    timeout: Optional[int] = Field(
        None,
        ge=60,
        description=(
            "Sandbox timeout in seconds (minimum 60). "
            "The maximum is controlled by server.max_sandbox_timeout_seconds. "
            "When omitted or null, the sandbox will not auto-terminate and must be deleted explicitly. "
            "Note: manual cleanup support is runtime-dependent; Kubernetes providers may reject "
            "null timeout when the workload provider does not support non-expiring sandboxes."
        ),
    )
    resource_limits: Optional[ResourceLimits] = Field(
        None,
        alias="resourceLimits",
        description="Runtime resource constraints (hard caps) for the sandbox instance. Optional when poolRef is provided.",
    )
    resource_requests: Optional[ResourceLimits] = Field(
        None,
        alias="resourceRequests",
        description=(
            "Resource reservations (guaranteed minimums) for the sandbox instance. "
            "When provided, used as Kubernetes resource requests, enabling Burstable QoS. "
            "When omitted, resourceLimits values are used for both limits and requests."
        ),
    )
    env: Optional[Dict[str, Optional[str]]] = Field(
        None,
        description="Environment variables to inject into the sandbox runtime",
    )
    metadata: Optional[Dict[str, str]] = Field(
        None,
        description="Custom key-value metadata for management, filtering, and tagging",
    )
    lifecycle: Optional[SandboxLifecycle] = Field(
        None,
        description="Optional declarative lifecycle hooks executed by execd.",
    )
    entrypoint: Optional[List[str]] = Field(
        None,
        min_length=1,
        description=(
            "The command to execute as the sandbox's entry process. "
            "Required when image is provided. Optional when snapshotId is provided; "
            'the server defaults to ["tail", "-f", "/dev/null"] when omitted.'
        ),
        example=["python", "/app/main.py"],
    )
    network_policy: Optional[NetworkPolicy] = Field(
        None,
        alias="networkPolicy",
        description=(
            "Optional outbound network policy. Shape matches the egress sidecar /policy endpoint. "
            "Empty/omitted means allow-all until updated. Not supported together with "
            "extensions.poolRef because pooled pods are pre-created."
        ),
    )
    credential_proxy: Optional[CredentialProxyConfig] = Field(
        None,
        alias="credentialProxy",
        description=(
            "Optional Credential Vault proxy startup settings. Set enabled=true to "
            "enable transparent MITM support for credential injection."
        ),
    )
    secure_access: bool = Field(
        False,
        alias="secureAccess",
        description=(
            "Opts the sandbox into secured access for endpoint access. "
            "Currently supported only for Kubernetes sandboxes exposed through ingress gateway mode. "
            "When enabled, the server provisions access credentials and returns required endpoint headers."
        ),
    )
    volumes: Optional[List[Volume]] = Field(
        None,
        description=(
            "Storage mounts for the sandbox. Each volume entry specifies a named backend-specific "
            "storage source and common mount settings. Exactly one backend type must be specified per volume entry."
        ),
    )
    extensions: Optional[Dict[str, str]] = Field(
        None,
        description="Opaque container for provider-specific or transient parameters not covered by the core API",
    )
    template_id: Optional[str] = Field(
        None,
        alias="templateId",
        min_length=1,
        description=(
            "Fsb template to create the sandbox from. Mutually "
            "exclusive with image and snapshotId; in template mode the workload "
            "shape is fixed by the template's golden image, so entrypoint, env, "
            "resourceLimits, resourceRequests, volumes, platform, credentialProxy, "
            "secureAccess and lifecycle hooks are rejected. lifecycle.idlePolicy "
            "is allowed (control-plane state, not workload shape). timeout is "
            "required."
        ),
    )

    @model_validator(mode="after")
    def validate_source_and_entrypoint(self) -> "CreateSandboxRequest":
        if self.env and OPENSANDBOX_LIFECYCLE in self.env:
            raise ValueError(
                f"Environment variable '{OPENSANDBOX_LIFECYCLE}' is reserved. "
                "Use the lifecycle request field instead."
            )

        # Template mode (fsb): workload-shaping fields are rejected, not
        # ignored; idlePolicy is control-plane state, so a hooks-free
        # lifecycle may carry it.
        if self.template_id is not None and self.template_id.strip():
            conflicts = {
                "image": self.image is not None,
                "snapshotId": bool((self.snapshot_id or "").strip()),
                "entrypoint": self.entrypoint is not None,
                "env": self.env is not None,
                "resourceLimits": self.resource_limits is not None,
                "resourceRequests": self.resource_requests is not None,
                "volumes": self.volumes is not None,
                "platform": self.platform is not None,
                "credentialProxy": self.credential_proxy is not None,
                "secureAccess": self.secure_access,
                "lifecycle": self.lifecycle is not None and self.lifecycle.has_hooks,
            }
            present = [name for name, is_set in conflicts.items() if is_set]
            if present:
                raise ValueError(
                    f"templateId cannot be combined with: {', '.join(sorted(present))}; "
                    "the workload shape is fixed by the template's golden image."
                )
            if self.timeout is None:
                raise ValueError("timeout is required when templateId is provided.")
            return self
        if self.template_id is not None:
            self.template_id = None  # normalize blank templateId

        # When poolRef is set, image/snapshotId/entrypoint/resourceLimits are
        # all defined in the Pool CRD and not required from the caller.
        has_pool_ref = bool((self.extensions or {}).get("poolRef", "").strip())
        if has_pool_ref:
            if self.lifecycle is not None and self.lifecycle.has_hooks:
                raise ValueError(
                    "lifecycle hooks cannot be used together with poolRef; "
                    "lifecycle.idlePolicy is not a hook and is allowed where "
                    "the backend supports it."
                )
            # Reject conflicting fields that would be ignored in pool mode
            if bool((self.snapshot_id or "").strip()):
                raise ValueError("snapshotId cannot be used together with poolRef.")
            # Normalize blank snapshotId so downstream code won't see
            # a truthy whitespace string (e.g. "   ") as a real value.
            if self.snapshot_id is not None and not self.snapshot_id.strip():
                self.snapshot_id = None
            return self

        if self.credential_proxy and self.credential_proxy.enabled:
            if self.network_policy is None:
                raise ValueError("credentialProxy.enabled requires networkPolicy.")

        has_image = self.image is not None and bool(self.image.uri.strip())
        has_snapshot = bool((self.snapshot_id or "").strip())

        if has_image == has_snapshot:
            raise ValueError("Exactly one of image or snapshotId must be provided.")

        if has_image and not self.entrypoint:
            raise ValueError("Entrypoint is required when image is provided.")

        if self.image is not None and not has_image:
            self.image = None

        if self.snapshot_id is not None and not has_snapshot:
            self.snapshot_id = None

        if self.resource_limits is None:
            raise ValueError("resourceLimits is required when poolRef is not provided.")

        return self

    class Config:
        populate_by_name = True

    @property
    def resolved_snapshot_backend(self) -> Optional[str]:
        """Backend that produced the snapshot being restored, if resolved."""
        return self._resolved_snapshot_backend


class CreateSandboxResponse(BaseModel):
    """
    Response from creating a new sandbox.

    Contains essential information without image and updatedAt.
    """
    id: str = Field(..., description="Unique sandbox identifier")
    status: SandboxStatus = Field(..., description="Current lifecycle status and detailed state information")
    metadata: Optional[Dict[str, str]] = Field(None, description="Custom metadata from creation request")
    extensions: Optional[Dict[str, str]] = Field(
        None,
        description="Opaque extension data restored from provider-specific storage",
    )
    platform: Optional[PlatformSpec] = Field(
        None,
        description=(
            "Platform constraint echoed from request or workload template. "
            "Null when no scheduling constraint is provided."
        ),
    )
    expires_at: Optional[datetime] = Field(
        None,
        alias="expiresAt",
        description="Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled.",
    )
    created_at: datetime = Field(..., alias="createdAt", description="Sandbox creation timestamp")
    entrypoint: Optional[List[str]] = Field(None, description="Entry process specification from creation request")

    class Config:
        populate_by_name = True


class AllocationSummary(BaseModel):
    """Current runtime-confirmed pool allocation summary."""
    mode: Literal["pool"] = Field("pool", description="Allocation mode.")
    pool_ref: str = Field(..., alias="poolRef", description="Concrete pool reference currently allocated.")
    state: Literal["allocated"] = Field("allocated", description="Current confirmed allocation state.")

    class Config:
        populate_by_name = True
        extra = "forbid"


class Sandbox(BaseModel):
    """
    Runtime execution environment provisioned from a container image.

    This is the complete representation of the sandbox resource.
    """
    id: str = Field(..., description="Unique sandbox identifier")
    image: Optional[ImageSpec] = Field(None, description="Container image specification used to provision this sandbox")
    snapshot_id: Optional[str] = Field(
        None,
        alias="snapshotId",
        description="Snapshot identifier used to restore this sandbox",
    )
    platform: Optional[PlatformSpec] = Field(
        None,
        description=(
            "Platform constraint echoed from request or workload template. "
            "Null when no scheduling constraint is provided."
        ),
    )
    status: SandboxStatus = Field(..., description="Current lifecycle status and detailed state information")
    metadata: Optional[Dict[str, str]] = Field(None, description="Custom metadata from creation request")
    extensions: Optional[Dict[str, str]] = Field(
        None,
        description="Opaque extension data restored from provider-specific storage",
    )
    allocation: Optional[AllocationSummary] = Field(
        None,
        description=(
            "Current runtime-confirmed pool allocation summary. Omitted unless the runtime confirms "
            "an active pool allocation; it is not a request echo, allocation history, readiness signal, "
            "or Kubernetes introspection result."
        ),
    )
    entrypoint: Optional[List[str]] = Field(None, description="The command to execute as the sandbox's entry process")
    expires_at: Optional[datetime] = Field(
        None,
        alias="expiresAt",
        description="Timestamp when sandbox will auto-terminate. Null when manual cleanup is enabled.",
    )
    created_at: datetime = Field(..., alias="createdAt", description="Sandbox creation timestamp")

    class Config:
        populate_by_name = True


PatchSandboxMetadataRequest = Dict[str, Optional[str]]
"""Metadata merge-patch body: non-null values add/replace, null values delete, absent keys unchanged."""


# Snapshot Models
# ============================================================================

class SnapshotStatus(BaseModel):
    """
    Detailed snapshot status information with lifecycle state and transition details.
    """
    state: str = Field(
        ...,
        description="Current snapshot lifecycle state (Creating, Deleting, Ready, Failed)",
    )
    reason: Optional[str] = Field(
        None,
        description="Short machine-readable reason code for the current state",
    )
    message: Optional[str] = Field(
        None,
        description="Human-readable message describing the current state or failure reason",
    )
    last_transition_at: Optional[datetime] = Field(
        None,
        alias="lastTransitionAt",
        description="Timestamp of the last state transition",
    )

    class Config:
        populate_by_name = True


class CreateSnapshotRequest(BaseModel):
    """
    Request to create a snapshot from a sandbox.
    """
    name: Optional[str] = Field(
        None,
        min_length=1,
        description="Optional human-readable snapshot name",
    )


class Snapshot(BaseModel):
    """
    Persistent point-in-time capture of a sandbox.
    """
    id: str = Field(..., description="Unique snapshot identifier")
    sandbox_id: str = Field(
        ...,
        alias="sandboxId",
        description="Source sandbox identifier used to create this snapshot",
    )
    name: Optional[str] = Field(
        None,
        description="Optional human-readable snapshot name",
    )
    status: SnapshotStatus = Field(
        ...,
        description="Current snapshot lifecycle status and detailed state information",
    )
    created_at: datetime = Field(
        ...,
        alias="createdAt",
        description="Snapshot creation timestamp",
    )

    class Config:
        populate_by_name = True


class SnapshotFilter(BaseModel):
    """
    Filtering criteria for listing snapshots.
    """
    sandbox_id: Optional[str] = Field(
        None,
        alias="sandboxId",
        description="Filter snapshots by source sandbox identifier",
    )
    name: Optional[str] = Field(
        None,
        description="Filter snapshots by exact snapshot name",
    )
    state: Optional[List[str]] = Field(
        None,
        min_length=1,
        description="Filter by snapshot lifecycle state (status.state) - supports OR logic",
    )

    class Config:
        populate_by_name = True


class ListSnapshotsRequest(BaseModel):
    """
    Request body for snapshot listing queries.
    """
    filter: SnapshotFilter = Field(
        default_factory=SnapshotFilter,
        description="Filtering criteria (all conditions combined with AND logic)",
    )
    pagination: Optional["PaginationRequest"] = Field(None, description="Pagination parameters")


class ListSnapshotsResponse(BaseModel):
    """
    Paginated collection of snapshots.
    """
    items: List[Snapshot] = Field(..., description="List of snapshots")
    pagination: "PaginationInfo" = Field(..., description="Pagination metadata")


# ============================================================================
# List Sandboxes
# ============================================================================

class SandboxFilter(BaseModel):
    """
    Filtering criteria for listing sandboxes.
    """
    state: Optional[List[str]] = Field(
        None,
        min_length=1,
        description="Filter by lifecycle state (status.state) - supports OR logic",
    )
    metadata: Optional[Dict[str, str]] = Field(
        None,
        description="Filter by metadata key-value pairs (AND logic)",
    )


class PaginationRequest(BaseModel):
    """
    Pagination parameters for list requests.
    """
    page: int = Field(1, ge=1, description="Page number")
    page_size: int = Field(
        20,
        ge=1,
        le=200,
        alias="pageSize",
        description="Number of items per page",
    )

    class Config:
        populate_by_name = True


class ListSandboxesRequest(BaseModel):
    """
    Request body for complex listing queries.
    """
    filter: SandboxFilter = Field(
        default_factory=SandboxFilter,
        description="Filtering criteria (all conditions combined with AND logic)",
    )
    pagination: Optional[PaginationRequest] = Field(None, description="Pagination parameters")


class PaginationInfo(BaseModel):
    """
    Pagination metadata for list responses.
    """
    page: int = Field(..., ge=1, description="Current page number")
    page_size: int = Field(..., ge=1, alias="pageSize", description="Number of items per page")
    total_items: int = Field(..., ge=0, alias="totalItems", description="Total number of items matching the filter")
    total_pages: int = Field(..., ge=0, alias="totalPages", description="Total number of pages")
    has_next_page: bool = Field(..., alias="hasNextPage", description="Whether there are more pages after the current one")

    class Config:
        populate_by_name = True


class ListSandboxesResponse(BaseModel):
    """
    Paginated collection of sandboxes.
    """
    items: List[Sandbox] = Field(..., description="List of sandboxes")
    pagination: PaginationInfo = Field(..., description="Pagination metadata")


# ============================================================================
# Renew Expiration
# ============================================================================

class RenewSandboxExpirationRequest(BaseModel):
    """
    Request to renew sandbox expiration time.
    """
    expires_at: datetime = Field(
        ...,
        alias="expiresAt",
        description=(
            "New absolute expiration time in UTC (RFC 3339 format). Must be in the future. "
            "May be earlier than, equal to, or later than the current expiresAt. "
            "The creation-time limit server.max_sandbox_timeout_seconds does not apply."
        ),
    )

    class Config:
        populate_by_name = True


class RenewSandboxExpirationResponse(BaseModel):
    """
    Response for renewing sandbox expiration.
    """
    expires_at: datetime = Field(
        ...,
        alias="expiresAt",
        description="The new absolute expiration time in UTC (RFC 3339 format)",
    )

    class Config:
        populate_by_name = True


# ============================================================================
# Endpoint
# ============================================================================

class Endpoint(BaseModel):
    """
    Endpoint for accessing a service running in the sandbox.
    """
    endpoint: str = Field(
        ...,
        description="Public endpoint string (host[:port]/path) exposed for the sandbox service",
    )
    headers: Optional[dict[str, str]] = Field(
        default=None,
        description="Optional headers required when accessing the endpoint (e.g., for header-based routing).",
    )
    class Config:
        populate_by_name = True


# ============================================================================
# Error Response
# ============================================================================

class ErrorResponse(BaseModel):
    """
    Standard error response for all non-2xx HTTP responses.

    HTTP status code indicates the error category; code and message provide details.
    """
    code: str = Field(
        ...,
        description="Machine-readable error code (e.g., INVALID_REQUEST, NOT_FOUND, INTERNAL_ERROR)",
    )
    message: str = Field(
        ...,
        description="Human-readable error message describing what went wrong and how to fix it",
    )


# ============================================================================
# Pool Models
# ============================================================================

class PoolCapacitySpec(BaseModel):
    """
    Capacity configuration that controls the size of the resource pool.
    """
    buffer_max: int = Field(
        ...,
        alias="bufferMax",
        ge=0,
        description="Maximum number of nodes kept in the warm buffer.",
    )
    buffer_min: int = Field(
        ...,
        alias="bufferMin",
        ge=0,
        description="Minimum number of nodes that must remain in the buffer.",
    )
    pool_max: int = Field(
        ...,
        alias="poolMax",
        ge=0,
        description="Maximum total number of nodes allowed in the entire pool.",
    )
    pool_min: int = Field(
        ...,
        alias="poolMin",
        ge=0,
        description="Minimum total size of the pool.",
    )

    class Config:
        populate_by_name = True


class CreatePoolRequest(BaseModel):
    """
    Request to create a new pre-warmed resource pool.

    A Pool manages a set of pre-warmed pods that can be rapidly allocated
    to sandboxes, reducing cold-start latency.
    """
    name: str = Field(
        ...,
        description="Unique name for the pool (must be a valid Kubernetes resource name).",
        pattern=r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
        max_length=253,
    )
    template: Dict = Field(
        ...,
        description=(
            "Kubernetes PodTemplateSpec defining the pod configuration for pre-warmed nodes. "
            "Follows the same schema as spec.template in a Kubernetes Deployment."
        ),
    )
    capacity_spec: PoolCapacitySpec = Field(
        ...,
        alias="capacitySpec",
        description="Capacity configuration controlling pool size and buffer behavior.",
    )

    class Config:
        populate_by_name = True


class UpdatePoolRequest(BaseModel):
    """
    Request to update an existing pool's capacity configuration.

    Only capacity settings can be updated after pool creation.
    Updating the pod template requires recreating the pool.
    """
    capacity_spec: PoolCapacitySpec = Field(
        ...,
        alias="capacitySpec",
        description="New capacity configuration for the pool.",
    )

    class Config:
        populate_by_name = True


class PoolStatus(BaseModel):
    """
    Observed runtime state of a pool.
    """
    total: int = Field(..., description="Total number of nodes in the pool.")
    allocated: int = Field(..., description="Number of nodes currently allocated to sandboxes.")
    available: int = Field(..., description="Number of nodes currently available in the pool.")
    revision: str = Field(..., description="Latest revision identifier of the pool.")


class PoolResponse(BaseModel):
    """
    Full representation of a Pool resource.
    """
    name: str = Field(..., description="Unique pool name.")
    capacity_spec: PoolCapacitySpec = Field(
        ...,
        alias="capacitySpec",
        description="Capacity configuration of the pool.",
    )
    status: Optional[PoolStatus] = Field(
        None,
        description="Observed runtime state of the pool. May be absent if not yet reconciled.",
    )
    created_at: Optional[datetime] = Field(
        None,
        alias="createdAt",
        description="Pool creation timestamp.",
    )

    class Config:
        populate_by_name = True


class ListPoolsResponse(BaseModel):
    """
    Collection of pools.
    """
    items: List[PoolResponse] = Field(..., description="List of pools.")


# ============================================================================
# Fsb Templates
# ============================================================================

class FsbTemplateReadiness(BaseModel):
    """
    Build-side readiness gate for a fsb template.
    """
    probe: Optional[str] = Field(
        None,
        description=(
            "Readiness probe checked first during the golden-image build; "
            "e.g. 'tcp://127.0.0.1:44772' or 'cmd://<command>'."
        ),
    )
    warmup_seconds: Optional[int] = Field(
        None,
        ge=0,
        alias="warmupSeconds",
        description="Fallback warmup window in seconds (default 60).",
    )

    class Config:
        populate_by_name = True


class CreateFsbTemplateRequest(BaseModel):
    """
    Request to create a fsb template: a fast-sandbox golden-image build.

    The server persists the build intent, resolves it to a SandboxTemplate
    CRD, and reports the asynchronous build through the template status.
    Kernel, execd and guest init are server-side build inputs supplied from
    the [kubernetes] configuration, not client fields.
    """
    image: str = Field(
        ...,
        min_length=1,
        description="Source OCI image reference the golden image is built from",
    )
    resource_limits: Optional[ResourceLimits] = Field(
        None,
        alias="resourceLimits",
        description=(
            "Guest machine sizing: cpu -> guest vCPUs, memory -> guest memory, "
            "disk -> logical size of the guest rootfs. The artifact set is "
            "stored and P2P-pulled at the disk size, so keep it just above "
            "the expanded source image. Defaults: cpu 1, memory 512Mi, "
            "disk 2Gi."
        ),
    )
    entrypoint: Optional[List[str]] = Field(
        None,
        min_length=1,
        description="Guest business command (argv); empty defaults to ['tail', '-f', '/dev/null'].",
    )
    env: Optional[Dict[str, str]] = Field(
        None,
        description=(
            "Environment variables baked into the golden image (injected as "
            "/etc/sandbox-init.env in the guest; literal values only). The "
            "source image's own OCI Config.Env is inherited like a container "
            "runtime would; an env with the same name here overrides the "
            "inherited value. Names must be valid shell variable names "
            "([A-Za-z_][A-Za-z0-9_]*)."
        ),
    )
    metadata: Optional[Dict[str, str]] = Field(
        None,
        description="Custom key-value metadata for management, filtering, and tagging",
    )
    readiness: Optional[FsbTemplateReadiness] = Field(
        None,
        description="Optional build-side readiness gate",
    )
    publish: str = Field(
        ...,
        min_length=1,
        description=(
            "Publish destination for the built snapshot set: "
            "'oci://registry/repository' for format=overlaybd (default), "
            "'s3://bucket/prefix' for format=native."
        ),
    )
    format: Literal["native", "overlaybd"] = Field(
        "overlaybd",
        description="Storage encoding of the produced snapshot set",
    )

    class Config:
        populate_by_name = True
        extra = "forbid"


class FsbTemplateStatus(BaseModel):
    """
    Status of a fsb template build.
    """
    phase: Literal["Pending", "Building", "Succeeded", "Failed"] = Field(
        ...,
        description="Build lifecycle phase",
    )
    manifest_ref: Optional[str] = Field(
        None,
        alias="manifestRef",
        description=(
            "Published artifact reference — oci://...@sha256 for "
            "format=overlaybd, s3://.../manifest.json for native; present "
            "when Succeeded"
        ),
    )
    message: Optional[str] = Field(
        None,
        description="Failure reason when phase is Failed",
    )

    class Config:
        populate_by_name = True


class FsbTemplate(BaseModel):
    """
    A fsb template: a golden image whose build is declared and executed
    by fast-sandbox.
    """
    template_id: str = Field(..., alias="templateId", description="Server-generated template ID (tpl_<uuid>)")
    image: str = Field(..., description="Source OCI image reference")
    resource_limits: Optional[ResourceLimits] = Field(None, alias="resourceLimits")
    entrypoint: Optional[List[str]] = Field(None, description="Guest business command (argv)")
    env: Optional[Dict[str, str]] = Field(
        None, description="Environment variables baked into the golden image"
    )
    metadata: Optional[Dict[str, str]] = Field(None, description="Custom metadata from the creation request")
    readiness: Optional[FsbTemplateReadiness] = Field(None, description="Build-side readiness gate")
    publish: str = Field(
        ...,
        description=(
            "Artifact publish destination — oci://registry/repository for "
            "format=overlaybd (default), s3://bucket/prefix for format=native"
        ),
    )
    format: Literal["native", "overlaybd"] = Field(..., description="Snapshot storage encoding")
    status: FsbTemplateStatus = Field(..., description="Build status")
    created_at: datetime = Field(..., alias="createdAt", description="Creation timestamp")
    updated_at: datetime = Field(..., alias="updatedAt", description="Last update timestamp")

    class Config:
        populate_by_name = True


class ListFsbTemplatesResponse(BaseModel):
    """
    Paginated collection of fsb templates.
    """
    items: List[FsbTemplate] = Field(..., description="List of templates")
    pagination: PaginationInfo = Field(..., description="Pagination metadata")


# ============================================================================
# Metrics
# ============================================================================

class MetricsEvent(BaseModel):
    """
    SDK-reported metrics event (Phase 1: sandbox creation latency).
    """

    event_type: Literal["sandbox.create"] = Field(
        ...,
        alias="eventType",
        description="Metric event type",
    )
    sandbox_id: Optional[str] = Field(
        default=None,
        alias="sandboxId",
        description="Sandbox identifier when available",
    )
    image: Optional[str] = Field(
        default=None,
        description="Container image URI or snapshot startup source label",
    )
    create_duration_ms: int = Field(
        ...,
        alias="createDurationMs",
        ge=0,
        description="Wall-clock duration in milliseconds from create start to ready or failure",
    )
    success: bool = Field(
        ...,
        description="Whether create + readiness completed successfully",
    )

    class Config:
        populate_by_name = True