Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(sandbox): define the Image API contract (#3327)

r33drichardsa52500167b85
diff --git a/.github/workflows/cd-image-api.yml b/.github/workflows/cd-image-api.yml
new file mode 100644
index 0000000000..20626488a2
--- /dev/null
+++ b/.github/workflows/cd-image-api.yml
@@ -0,0 +1,112 @@
+name: "CD: Image API"
+
+on:
+ push:
+ tags:
+ - "image-api-v*"
+ workflow_dispatch:
+ inputs:
+ version:
+ description: "Image API version without the v prefix"
+ required: true
+ type: string
+
+concurrency:
+ group: "image-api-${{ github.event_name == 'workflow_dispatch' && format('image-api-v{0}', inputs.version) || github.ref_name }}"
+ cancel-in-progress: false
+
+permissions:
+ contents: read
+ packages: write
+
+jobs:
+ publish:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ env:
+ MANUAL_VERSION: ${{ inputs.version }}
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Determine version
+ id: version
+ shell: bash
+ run: |
+ set -euo pipefail
+ if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+ VERSION="${MANUAL_VERSION}"
+ else
+ VERSION="${GITHUB_REF_NAME#image-api-v}"
+ fi
+ if [[ ! "${VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "invalid Image API version: ${VERSION}" >&2
+ exit 1
+ fi
+ RELEASE_TAG="image-api-v${VERSION}"
+ if [[ "${GITHUB_EVENT_NAME}" == "push" && "${GITHUB_REF_NAME}" != "${RELEASE_TAG}" ]]; then
+ echo "unexpected Image API tag: ${GITHUB_REF_NAME}" >&2
+ exit 1
+ fi
+ if ! git show-ref --verify --quiet "refs/tags/${RELEASE_TAG}"; then
+ echo "Image API release tag not found: ${RELEASE_TAG}" >&2
+ exit 1
+ fi
+ TAG_COMMIT="$(git rev-list -n 1 "${RELEASE_TAG}")"
+ CHECKED_OUT_COMMIT="$(git rev-parse HEAD)"
+ if [[ "${TAG_COMMIT}" != "${CHECKED_OUT_COMMIT}" ]]; then
+ echo "Image API version ${VERSION} must run from ${RELEASE_TAG}" >&2
+ exit 1
+ fi
+ echo "version=${VERSION}" >>"${GITHUB_OUTPUT}"
+ echo "release_tag=${RELEASE_TAG}" >>"${GITHUB_OUTPUT}"
+ echo "commit=${TAG_COMMIT}" >>"${GITHUB_OUTPUT}"
+
+ - name: Install Flux CLI 2.9.4
+ shell: bash
+ run: |
+ set -euo pipefail
+ curl -fsSLo /tmp/flux.tar.gz \
+ https://github.com/fluxcd/flux2/releases/download/v2.9.4/flux_2.9.4_linux_amd64.tar.gz
+ echo "c2c397a52930f52d2005c01d276116b059d062de379386d58e98115380a766a2 /tmp/flux.tar.gz" \
+ | sha256sum -c -
+ tar -xzf /tmp/flux.tar.gz -C /tmp flux
+ sudo install -m 0755 /tmp/flux /usr/local/bin/flux
+ flux version --client
+
+ - name: Authenticate to GHCR
+ shell: bash
+ run: |
+ echo "${{ github.token }}" | docker login ghcr.io \
+ --username "${{ github.actor }}" \
+ --password-stdin
+
+ - name: Publish Image API artifact
+ env:
+ VERSION: ${{ steps.version.outputs.version }}
+ RELEASE_TAG: ${{ steps.version.outputs.release_tag }}
+ COMMIT: ${{ steps.version.outputs.commit }}
+ shell: bash
+ run: |
+ set -euo pipefail
+ ARTIFACT_DESTINATION="oci://ghcr.io/trycua/cua-image-api:v${VERSION}"
+ ARTIFACT_REFERENCE="${ARTIFACT_DESTINATION#oci://}"
+ set +e
+ MANIFEST_OUTPUT="$(docker manifest inspect "${ARTIFACT_REFERENCE}" 2>&1)"
+ MANIFEST_STATUS=$?
+ set -e
+ if [[ "${MANIFEST_STATUS}" -eq 0 ]]; then
+ echo "Image API artifact already exists: ${ARTIFACT_DESTINATION}" >&2
+ exit 1
+ fi
+ if ! grep -Eiq 'manifest unknown|no such manifest' <<<"${MANIFEST_OUTPUT}"; then
+ echo "could not verify Image API artifact absence: ${ARTIFACT_DESTINATION}" >&2
+ printf '%s\n' "${MANIFEST_OUTPUT}" >&2
+ exit 1
+ fi
+ flux push artifact "${ARTIFACT_DESTINATION}" \
+ --path=clusters/base/cua-images \
+ --source="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}" \
+ --revision="${RELEASE_TAG}@sha1:${COMMIT}"
diff --git a/.github/workflows/ci-image-api.yml b/.github/workflows/ci-image-api.yml
new file mode 100644
index 0000000000..fd944c0c16
--- /dev/null
+++ b/.github/workflows/ci-image-api.yml
@@ -0,0 +1,106 @@
+name: "CI: Image API"
+
+on:
+ push:
+ paths:
+ - "clusters/base/cua-images/**"
+ - "libs/python/cua-sandbox/cua_sandbox/image.py"
+ - "libs/python/cua-sandbox/cua_sandbox/__init__.py"
+ - "libs/python/cua-sandbox/cua_sandbox/generated/**"
+ - "libs/python/cua-sandbox/schemas/**"
+ - "libs/python/cua-sandbox/scripts/generate_image_models.py"
+ - "libs/python/cua-sandbox/tests/test_image*.py"
+ - "libs/python/cua-sandbox/pyproject.toml"
+ - "libs/python/cua-sandbox/uv.lock"
+ - ".github/workflows/ci-image-api.yml"
+ - ".github/workflows/cd-image-api.yml"
+ pull_request:
+ paths:
+ - "clusters/base/cua-images/**"
+ - "libs/python/cua-sandbox/cua_sandbox/image.py"
+ - "libs/python/cua-sandbox/cua_sandbox/__init__.py"
+ - "libs/python/cua-sandbox/cua_sandbox/generated/**"
+ - "libs/python/cua-sandbox/schemas/**"
+ - "libs/python/cua-sandbox/scripts/generate_image_models.py"
+ - "libs/python/cua-sandbox/tests/test_image*.py"
+ - "libs/python/cua-sandbox/pyproject.toml"
+ - "libs/python/cua-sandbox/uv.lock"
+ - ".github/workflows/ci-image-api.yml"
+ - ".github/workflows/cd-image-api.yml"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+
+ - name: Set up Go
+ uses: actions/setup-go@v5
+ with:
+ go-version: "1.25.x"
+
+ - name: Install dependencies
+ run: |
+ pip install uv
+ uv sync --project libs/python/cua-sandbox --group dev --extra dev
+ go install sigs.k8s.io/kustomize/kustomize/[email protected]
+ go install sigs.k8s.io/[email protected]
+
+ - name: Verify generated Image API artifacts
+ run: |
+ uv run --project libs/python/cua-sandbox \
+ python libs/python/cua-sandbox/scripts/generate_image_models.py --check
+
+ - name: Render the CRD package
+ run: |
+ export PATH="$(go env GOPATH)/bin:$PATH"
+ kustomize build clusters/base/cua-images >/tmp/cua-image-crd.yaml
+ grep -q '^kind: CustomResourceDefinition$' /tmp/cua-image-crd.yaml
+ grep -q 'name: images.images.cua.ai' /tmp/cua-image-crd.yaml
+
+ - name: Validate CRD API-server admission
+ run: |
+ export PATH="$(go env GOPATH)/bin:$PATH"
+ kind create cluster --name cua-image-api --wait 120s
+ kubectl apply --server-side --dry-run=server -f clusters/base/cua-images/crd.yaml
+
+ - name: Delete temporary Kind cluster
+ if: always()
+ run: |
+ export PATH="$(go env GOPATH)/bin:$PATH"
+ kind delete cluster --name cua-image-api
+
+ - name: Run focused tests
+ run: |
+ uv run --project libs/python/cua-sandbox pytest \
+ libs/python/cua-sandbox/tests/test_image_crd.py \
+ libs/python/cua-sandbox/tests/test_image_model_generation.py \
+ libs/python/cua-sandbox/tests/test_image_build_recipe.py \
+ libs/python/cua-sandbox/tests/test_image_api_workflows.py \
+ libs/python/cua-sandbox/tests/test_image.py \
+ -q
+
+ - name: Check formatting and repository hygiene
+ run: |
+ uv run --project libs/python/cua-sandbox ruff check \
+ libs/python/cua-sandbox/cua_sandbox/image.py \
+ libs/python/cua-sandbox/scripts/generate_image_models.py \
+ libs/python/cua-sandbox/tests/test_image_crd.py \
+ libs/python/cua-sandbox/tests/test_image_model_generation.py \
+ libs/python/cua-sandbox/tests/test_image_build_recipe.py \
+ libs/python/cua-sandbox/tests/test_image_api_workflows.py
+ uv run --project libs/python/cua-sandbox ruff format --check \
+ libs/python/cua-sandbox/cua_sandbox/image.py \
+ libs/python/cua-sandbox/tests/test_image_api_workflows.py
+ git diff --check
diff --git a/clusters/base/cua-images/crd.yaml b/clusters/base/cua-images/crd.yaml
new file mode 100644
index 0000000000..e7794059df
--- /dev/null
+++ b/clusters/base/cua-images/crd.yaml
@@ -0,0 +1,335 @@
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+ name: images.images.cua.ai
+spec:
+ group: images.cua.ai
+ names:
+ kind: Image
+ listKind: ImageList
+ plural: images
+ shortNames:
+ - cuaimg
+ singular: image
+ scope: Namespaced
+ versions:
+ - name: v1alpha1
+ served: true
+ storage: true
+ additionalPrinterColumns:
+ - name: Phase
+ type: string
+ jsonPath: .status.phase
+ - name: Ready
+ type: string
+ jsonPath: .status.conditions[?(@.type=="Ready")].status
+ - name: Generation
+ type: integer
+ format: int64
+ jsonPath: .status.observedGeneration
+ - name: Age
+ type: date
+ jsonPath: .metadata.creationTimestamp
+ subresources:
+ status: {}
+ schema:
+ openAPIV3Schema:
+ title: ImageResource
+ type: object
+ required:
+ - spec
+ properties:
+ apiVersion:
+ type: string
+ enum:
+ - images.cua.ai/v1alpha1
+ kind:
+ type: string
+ enum:
+ - Image
+ metadata:
+ type: object
+ spec:
+ title: ImageSpec
+ type: object
+ required:
+ - recipe
+ properties:
+ recipe:
+ title: ImageRecipe
+ type: object
+ required:
+ - osType
+ - distro
+ - version
+ - kind
+ - layers
+ properties:
+ osType:
+ type: string
+ enum:
+ - linux
+ distro:
+ type: string
+ minLength: 1
+ maxLength: 64
+ version:
+ type: string
+ minLength: 1
+ maxLength: 64
+ kind:
+ type: string
+ enum:
+ - vm
+ layers:
+ type: array
+ maxItems: 128
+ items:
+ title: ImageLayer
+ type: object
+ required:
+ - type
+ properties:
+ type:
+ type: string
+ enum:
+ - apt_install
+ - pip_install
+ - uv_install
+ - app_install
+ - run
+ packages:
+ type: array
+ minItems: 1
+ maxItems: 256
+ items:
+ type: string
+ minLength: 1
+ maxLength: 256
+ appId:
+ type: string
+ minLength: 1
+ maxLength: 256
+ command:
+ type: string
+ minLength: 1
+ maxLength: 16384
+ oneOf:
+ - properties:
+ type:
+ enum:
+ - apt_install
+ - pip_install
+ - uv_install
+ required:
+ - packages
+ not:
+ anyOf:
+ - required:
+ - appId
+ - required:
+ - command
+ - properties:
+ type:
+ enum:
+ - app_install
+ required:
+ - appId
+ not:
+ anyOf:
+ - required:
+ - packages
+ - required:
+ - command
+ - properties:
+ type:
+ enum:
+ - run
+ required:
+ - command
+ not:
+ anyOf:
+ - required:
+ - packages
+ - required:
+ - appId
+ env:
+ type: object
+ maxProperties: 128
+ additionalProperties:
+ type: string
+ maxLength: 8192
+ ports:
+ type: array
+ maxItems: 32
+ x-kubernetes-list-type: set
+ items:
+ type: integer
+ minimum: 1
+ maximum: 65535
+ files:
+ type: array
+ maxItems: 128
+ items:
+ title: ImageFile
+ type: object
+ required:
+ - source
+ - destination
+ properties:
+ source:
+ title: ImageFileReference
+ type: object
+ required:
+ - reference
+ - digest
+ - sizeBytes
+ properties:
+ reference:
+ type: string
+ minLength: 1
+ maxLength: 2048
+ pattern: ^uploads/[a-z0-9]([-a-z0-9]*[a-z0-9])?/[A-Za-z0-9_-]+$
+ digest:
+ type: string
+ pattern: ^sha256:[0-9a-f]{64}$
+ sizeBytes:
+ type: integer
+ format: int64
+ minimum: 0
+ maximum: 9223372036854775807
+ destination:
+ type: string
+ pattern: ^/.*
+ maxLength: 4096
+ metadata:
+ title: ImageUserMetadata
+ type: object
+ properties:
+ tags:
+ type: object
+ maxProperties: 32
+ additionalProperties:
+ type: string
+ maxLength: 256
+ build:
+ title: ImageBuildOptions
+ type: object
+ properties:
+ timeoutSeconds:
+ type: integer
+ minimum: 60
+ maximum: 86400
+ default: 7200
+ diskSize:
+ type: string
+ pattern: ^[1-9][0-9]*(Gi|Ti)$
+ default: 40Gi
+ status:
+ title: ImageStatus
+ type: object
+ properties:
+ observedGeneration:
+ type: integer
+ format: int64
+ minimum: 0
+ phase:
+ type: string
+ enum:
+ - Pending
+ - Validating
+ - Building
+ - PushingOCI
+ - Importing
+ - Quiescing
+ - Snapshotting
+ - Ready
+ - Failed
+ - Cancelling
+ buildIdentity:
+ type: string
+ maxLength: 63
+ recipeDigest:
+ type: string
+ pattern: ^sha256:[0-9a-f]{64}$
+ artifacts:
+ title: ImageArtifacts
+ type: object
+ properties:
+ oci:
+ title: ImageOciArtifact
+ type: object
+ required:
+ - reference
+ - digest
+ properties:
+ reference:
+ type: string
+ minLength: 1
+ maxLength: 2048
+ digest:
+ type: string
+ pattern: ^sha256:[0-9a-f]{64}$
+ volumeSnapshot:
+ title: ImageVolumeSnapshotArtifact
+ type: object
+ required:
+ - namespace
+ - name
+ properties:
+ namespace:
+ type: string
+ minLength: 1
+ maxLength: 63
+ name:
+ type: string
+ minLength: 1
+ maxLength: 253
+ logs:
+ title: ImageLogs
+ type: object
+ properties:
+ livePodName:
+ type: string
+ maxLength: 253
+ retainedReference:
+ type: string
+ maxLength: 2048
+ conditions:
+ type: array
+ x-kubernetes-list-type: map
+ x-kubernetes-list-map-keys:
+ - type
+ items:
+ title: ImageCondition
+ type: object
+ required:
+ - type
+ - status
+ - reason
+ - lastTransitionTime
+ properties:
+ type:
+ type: string
+ minLength: 1
+ maxLength: 64
+ status:
+ type: string
+ enum:
+ - "True"
+ - "False"
+ - Unknown
+ reason:
+ type: string
+ minLength: 1
+ maxLength: 128
+ message:
+ type: string
+ maxLength: 32768
+ observedGeneration:
+ type: integer
+ format: int64
+ minimum: 0
+ lastTransitionTime:
+ type: string
+ format: date-time
diff --git a/clusters/base/cua-images/kustomization.yaml b/clusters/base/cua-images/kustomization.yaml
new file mode 100644
index 0000000000..8106ed5b81
--- /dev/null
+++ b/clusters/base/cua-images/kustomization.yaml
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+ - crd.yaml
diff --git a/libs/python/cua-sandbox/cua_sandbox/__init__.py b/libs/python/cua-sandbox/cua_sandbox/__init__.py
index e3cab04103..bafa360eb5 100644
--- a/libs/python/cua-sandbox/cua_sandbox/__init__.py
+++ b/libs/python/cua-sandbox/cua_sandbox/__init__.py
@@ -20,6 +20,7 @@ __version__ = "0.1.0"
from cua_sandbox._auth import login, whoami
from cua_sandbox._config import configure
+from cua_sandbox.generated.image_models import ImageFileReference
from cua_sandbox.image import Image
from cua_sandbox.localhost import Localhost, localhost
from cua_sandbox.pool import Pool, Template
@@ -62,6 +63,7 @@ __all__ = [
"login",
"whoami",
"Image",
+ "ImageFileReference",
"Pool",
"PoolAccessDeniedError",
"Template",
diff --git a/libs/python/cua-sandbox/cua_sandbox/generated/__init__.py b/libs/python/cua-sandbox/cua_sandbox/generated/__init__.py
new file mode 100644
index 0000000000..7fa623d111
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/generated/__init__.py
@@ -0,0 +1 @@
+"""Generated API models. Regenerate with scripts/generate_image_models.py."""
diff --git a/libs/python/cua-sandbox/cua_sandbox/generated/image_models.py b/libs/python/cua-sandbox/cua_sandbox/generated/image_models.py
new file mode 100644
index 0000000000..00d59458a1
--- /dev/null
+++ b/libs/python/cua-sandbox/cua_sandbox/generated/image_models.py
@@ -0,0 +1,283 @@
+# Source: clusters/base/cua-images/crd.yaml
+# Source SHA-256: c97a1f9bcfd48cd4890807a9f4bfe38c71ba380fd3b47efb217de0eaf4bcc2b3
+# generated by datamodel-codegen:
+# filename: image.schema.json
+
+from __future__ import annotations
+
+import json as _json
+from enum import StrEnum
+from typing import Any as _Any
+from typing import Literal
+
+from jsonschema import Draft202012Validator as _Draft202012Validator
+from pydantic import (
+ AwareDatetime,
+ BaseModel,
+ ConfigDict,
+ Field,
+ RootModel,
+ conint,
+ constr,
+)
+from pydantic import model_validator as _model_validator
+
+
+class Metadata(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ annotations: dict[str, constr(max_length=4096)] | None = Field(None, max_length=64)
+ labels: dict[str, constr(max_length=4096)] | None = Field(None, max_length=64)
+ name: constr(pattern=r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", min_length=1, max_length=63)
+ namespace: constr(pattern=r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$", min_length=1, max_length=63)
+
+
+class Build(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ disk_size: constr(pattern=r"^[1-9][0-9]*(Gi|Ti)$") | None = Field("40Gi", alias="diskSize")
+ timeout_seconds: conint(ge=60, le=86400) | None = Field(7200, alias="timeoutSeconds")
+
+
+class Metadata1(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ tags: dict[str, constr(max_length=256)] | None = Field(None, max_length=32)
+
+
+class Source(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ digest: constr(pattern=r"^sha256:[0-9a-f]{64}$")
+ reference: constr(
+ pattern=r"^uploads/[a-z0-9]([-a-z0-9]*[a-z0-9])?/[A-Za-z0-9_-]+$",
+ min_length=1,
+ max_length=2048,
+ )
+ size_bytes: conint(ge=0, le=9223372036854775807) = Field(..., alias="sizeBytes")
+
+
+class File(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ destination: constr(pattern=r"^/.*", max_length=4096)
+ source: Source = Field(..., title="ImageFileReference")
+
+
+class Kind(StrEnum):
+ vm = "vm"
+
+
+class Package(RootModel[constr(min_length=1, max_length=256)]):
+ root: constr(min_length=1, max_length=256)
+
+
+class Type(StrEnum):
+ apt_install = "apt_install"
+ pip_install = "pip_install"
+ uv_install = "uv_install"
+ app_install = "app_install"
+ run = "run"
+ apt_install_1 = "apt_install"
+ pip_install_1 = "pip_install"
+ uv_install_1 = "uv_install"
+
+
+class Layers(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ app_id: constr(min_length=1, max_length=256) | None = Field(None, alias="appId")
+ command: constr(min_length=1, max_length=16384) | None = None
+ packages: list[Package] = Field(..., max_length=256, min_length=1)
+ type: Type
+
+
+class Type1(StrEnum):
+ apt_install = "apt_install"
+ pip_install = "pip_install"
+ uv_install = "uv_install"
+ app_install = "app_install"
+ run = "run"
+ app_install_1 = "app_install"
+
+
+class Layers1(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ app_id: constr(min_length=1, max_length=256) = Field(..., alias="appId")
+ command: constr(min_length=1, max_length=16384) | None = None
+ packages: list[Package] | None = Field(None, max_length=256, min_length=1)
+ type: Type1
+
+
+class Type2(StrEnum):
+ apt_install = "apt_install"
+ pip_install = "pip_install"
+ uv_install = "uv_install"
+ app_install = "app_install"
+ run = "run"
+ run_1 = "run"
+
+
+class Layers2(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ app_id: constr(min_length=1, max_length=256) | None = Field(None, alias="appId")
+ command: constr(min_length=1, max_length=16384)
+ packages: list[Package] | None = Field(None, max_length=256, min_length=1)
+ type: Type2
+
+
+class OsType(StrEnum):
+ linux = "linux"
+
+
+class Port(RootModel[conint(ge=1, le=65535)]):
+ root: conint(ge=1, le=65535)
+
+
+class Recipe(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ distro: constr(min_length=1, max_length=64)
+ env: dict[str, constr(max_length=8192)] | None = Field(None, max_length=128)
+ files: list[File] | None = Field(None, max_length=128)
+ kind: Kind
+ layers: list[Layers | Layers1 | Layers2] = Field(..., max_length=128)
+ os_type: OsType = Field(..., alias="osType")
+ ports: list[Port] | None = Field(None, max_length=32)
+ version: constr(min_length=1, max_length=64)
+
+
+class Spec(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ build: Build | None = Field(None, title="ImageBuildOptions")
+ metadata: Metadata1 | None = Field(None, title="ImageUserMetadata")
+ recipe: Recipe = Field(..., title="ImageRecipe")
+
+
+class Oci(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ digest: constr(pattern=r"^sha256:[0-9a-f]{64}$")
+ reference: constr(min_length=1, max_length=2048)
+
+
+class VolumeSnapshot(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ name: constr(min_length=1, max_length=253)
+ namespace: constr(min_length=1, max_length=63)
+
+
+class Artifacts(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ oci: Oci | None = Field(None, title="ImageOciArtifact")
+ volume_snapshot: VolumeSnapshot | None = Field(
+ None, alias="volumeSnapshot", title="ImageVolumeSnapshotArtifact"
+ )
+
+
+class Status1(StrEnum):
+ true = "True"
+ false = "False"
+ unknown = "Unknown"
+
+
+class Condition(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ last_transition_time: AwareDatetime = Field(..., alias="lastTransitionTime")
+ message: constr(max_length=32768) | None = None
+ observed_generation: conint(ge=0) | None = Field(None, alias="observedGeneration")
+ reason: constr(min_length=1, max_length=128)
+ status: Status1
+ type: constr(min_length=1, max_length=64)
+
+
+class Logs(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ live_pod_name: constr(max_length=253) | None = Field(None, alias="livePodName")
+ retained_reference: constr(max_length=2048) | None = Field(None, alias="retainedReference")
+
+
+class Phase(StrEnum):
+ pending = "Pending"
+ validating = "Validating"
+ building = "Building"
+ pushing_oci = "PushingOCI"
+ importing = "Importing"
+ quiescing = "Quiescing"
+ snapshotting = "Snapshotting"
+ ready = "Ready"
+ failed = "Failed"
+ cancelling = "Cancelling"
+
+
+class Status(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ artifacts: Artifacts | None = Field(None, title="ImageArtifacts")
+ build_identity: constr(max_length=63) | None = Field(None, alias="buildIdentity")
+ conditions: list[Condition] | None = None
+ logs: Logs | None = Field(None, title="ImageLogs")
+ observed_generation: conint(ge=0) | None = Field(None, alias="observedGeneration")
+ phase: Phase | None = None
+ recipe_digest: constr(pattern=r"^sha256:[0-9a-f]{64}$") | None = Field(
+ None, alias="recipeDigest"
+ )
+
+
+class ImageResource(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ api_version: Literal["images.cua.ai/v1alpha1"] = Field(..., alias="apiVersion")
+ kind: Literal["Image"]
+ metadata: Metadata = Field(..., title="ImageObjectMeta")
+ spec: Spec = Field(..., title="ImageSpec")
+ status: Status | None = Field(None, title="ImageStatus")
+
+
+_GENERATED_IMAGE_SCHEMA = _json.loads(
+ '{\n "$id": "https://cua.ai/schemas/images.cua.ai/v1alpha1/image.json",\n "$schema": "https://json-schema.org/draft/2020-12/schema",\n "additionalProperties": false,\n "properties": {\n "apiVersion": {\n "const": "images.cua.ai/v1alpha1",\n "type": "string"\n },\n "kind": {\n "const": "Image",\n "type": "string"\n },\n "metadata": {\n "additionalProperties": false,\n "properties": {\n "annotations": {\n "additionalProperties": {\n "maxLength": 4096,\n "type": "string"\n },\n "maxProperties": 64,\n "type": "object"\n },\n "labels": {\n "additionalProperties": {\n "maxLength": 4096,\n "type": "string"\n },\n "maxProperties": 64,\n "type": "object"\n },\n "name": {\n "maxLength": 63,\n "minLength": 1,\n "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",\n "type": "string"\n },\n "namespace": {\n "maxLength": 63,\n "minLength": 1,\n "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",\n "type": "string"\n }\n },\n "required": [\n "name",\n "namespace"\n ],\n "title": "ImageObjectMeta",\n "type": "object"\n },\n "spec": {\n "additionalProperties": false,\n "properties": {\n "build": {\n "additionalProperties": false,\n "properties": {\n "diskSize": {\n "default": "40Gi",\n "pattern": "^[1-9][0-9]*(Gi|Ti)$",\n "type": "string"\n },\n "timeoutSeconds": {\n "default": 7200,\n "maximum": 86400,\n "minimum": 60,\n "type": "integer"\n }\n },\n "title": "ImageBuildOptions",\n "type": "object"\n },\n "metadata": {\n "additionalProperties": false,\n "properties": {\n "tags": {\n "additionalProperties": {\n "maxLength": 256,\n "type": "string"\n },\n "maxProperties": 32,\n "type": "object"\n }\n },\n "title": "ImageUserMetadata",\n "type": "object"\n },\n "recipe": {\n "additionalProperties": false,\n "properties": {\n "distro": {\n "maxLength": 64,\n "minLength": 1,\n "type": "string"\n },\n "env": {\n "additionalProperties": {\n "maxLength": 8192,\n "type": "string"\n },\n "maxProperties": 128,\n "type": "object"\n },\n "files": {\n "items": {\n "additionalProperties": false,\n "properties": {\n "destination": {\n "maxLength": 4096,\n "pattern": "^/.*",\n "type": "string"\n },\n "source": {\n "additionalProperties": false,\n "properties": {\n "digest": {\n "pattern": "^sha256:[0-9a-f]{64}$",\n "type": "string"\n },\n "reference": {\n "maxLength": 2048,\n "minLength": 1,\n "pattern": "^uploads/[a-z0-9]([-a-z0-9]*[a-z0-9])?/[A-Za-z0-9_-]+$",\n "type": "string"\n },\n "sizeBytes": {\n "format": "int64",\n "maximum": 9223372036854775807,\n "minimum": 0,\n "type": "integer"\n }\n },\n "required": [\n "reference",\n "digest",\n "sizeBytes"\n ],\n "title": "ImageFileReference",\n "type": "object"\n }\n },\n "required": [\n "source",\n "destination"\n ],\n "title": "ImageFile",\n "type": "object"\n },\n "maxItems": 128,\n "type": "array"\n },\n "kind": {\n "enum": [\n "vm"\n ],\n "type": "string"\n },\n "layers": {\n "items": {\n "additionalProperties": false,\n "oneOf": [\n {\n "not": {\n "anyOf": [\n {\n "required": [\n "appId"\n ]\n },\n {\n "required": [\n "command"\n ]\n }\n ]\n },\n "properties": {\n "type": {\n "enum": [\n "apt_install",\n "pip_install",\n "uv_install"\n ]\n }\n },\n "required": [\n "packages"\n ]\n },\n {\n "not": {\n "anyOf": [\n {\n "required": [\n "packages"\n ]\n },\n {\n "required": [\n "command"\n ]\n }\n ]\n },\n "properties": {\n "type": {\n "enum": [\n "app_install"\n ]\n }\n },\n "required": [\n "appId"\n ]\n },\n {\n "not": {\n "anyOf": [\n {\n "required": [\n "packages"\n ]\n },\n {\n "required": [\n "appId"\n ]\n }\n ]\n },\n "properties": {\n "type": {\n "enum": [\n "run"\n ]\n }\n },\n "required": [\n "command"\n ]\n }\n ],\n "properties": {\n "appId": {\n "maxLength": 256,\n "minLength": 1,\n "type": "string"\n },\n "command": {\n "maxLength": 16384,\n "minLength": 1,\n "type": "string"\n },\n "packages": {\n "items": {\n "maxLength": 256,\n "minLength": 1,\n "type": "string"\n },\n "maxItems": 256,\n "minItems": 1,\n "type": "array"\n },\n "type": {\n "enum": [\n "apt_install",\n "pip_install",\n "uv_install",\n "app_install",\n "run"\n ],\n "type": "string"\n }\n },\n "required": [\n "type"\n ],\n "title": "ImageLayer",\n "type": "object"\n },\n "maxItems": 128,\n "type": "array"\n },\n "osType": {\n "enum": [\n "linux"\n ],\n "type": "string"\n },\n "ports": {\n "items": {\n "maximum": 65535,\n "minimum": 1,\n "type": "integer"\n },\n "maxItems": 32,\n "type": "array",\n "uniqueItems": true\n },\n "version": {\n "maxLength": 64,\n "minLength": 1,\n "type": "string"\n }\n },\n "required": [\n "osType",\n "distro",\n "version",\n "kind",\n "layers"\n ],\n "title": "ImageRecipe",\n "type": "object"\n }\n },\n "required": [\n "recipe"\n ],\n "title": "ImageSpec",\n "type": "object"\n },\n "status": {\n "additionalProperties": false,\n "properties": {\n "artifacts": {\n "additionalProperties": false,\n "properties": {\n "oci": {\n "additionalProperties": false,\n "properties": {\n "digest": {\n "pattern": "^sha256:[0-9a-f]{64}$",\n "type": "string"\n },\n "reference": {\n "maxLength": 2048,\n "minLength": 1,\n "type": "string"\n }\n },\n "required": [\n "reference",\n "digest"\n ],\n "title": "ImageOciArtifact",\n "type": "object"\n },\n "volumeSnapshot": {\n "additionalProperties": false,\n "properties": {\n "name": {\n "maxLength": 253,\n "minLength": 1,\n "type": "string"\n },\n "namespace": {\n "maxLength": 63,\n "minLength": 1,\n "type": "string"\n }\n },\n "required": [\n "namespace",\n "name"\n ],\n "title": "ImageVolumeSnapshotArtifact",\n "type": "object"\n }\n },\n "title": "ImageArtifacts",\n "type": "object"\n },\n "buildIdentity": {\n "maxLength": 63,\n "type": "string"\n },\n "conditions": {\n "items": {\n "additionalProperties": false,\n "properties": {\n "lastTransitionTime": {\n "format": "date-time",\n "type": "string"\n },\n "message": {\n "maxLength": 32768,\n "type": "string"\n },\n "observedGeneration": {\n "format": "int64",\n "minimum": 0,\n "type": "integer"\n },\n "reason": {\n "maxLength": 128,\n "minLength": 1,\n "type": "string"\n },\n "status": {\n "enum": [\n "True",\n "False",\n "Unknown"\n ],\n "type": "string"\n },\n "type": {\n "maxLength": 64,\n "minLength": 1,\n "type": "string"\n }\n },\n "required": [\n "type",\n "status",\n "reason",\n "lastTransitionTime"\n ],\n "title": "ImageCondition",\n "type": "object"\n },\n "type": "array"\n },\n "logs": {\n "additionalProperties": false,\n "properties": {\n "livePodName": {\n "maxLength": 253,\n "type": "string"\n },\n "retainedReference": {\n "maxLength": 2048,\n "type": "string"\n }\n },\n "title": "ImageLogs",\n "type": "object"\n },\n "observedGeneration": {\n "format": "int64",\n "minimum": 0,\n "type": "integer"\n },\n "phase": {\n "enum": [\n "Pending",\n "Validating",\n "Building",\n "PushingOCI",\n "Importing",\n "Quiescing",\n "Snapshotting",\n "Ready",\n "Failed",\n "Cancelling"\n ],\n "type": "string"\n },\n "recipeDigest": {\n "pattern": "^sha256:[0-9a-f]{64}$",\n "type": "string"\n }\n },\n "title": "ImageStatus",\n "type": "object"\n }\n },\n "required": [\n "spec",\n "apiVersion",\n "kind",\n "metadata"\n ],\n "title": "ImageResource",\n "type": "object"\n}\n'
+)
+_GENERATED_IMAGE_SCHEMA_VALIDATOR = _Draft202012Validator(_GENERATED_IMAGE_SCHEMA)
+GeneratedImageResource = ImageResource
+
+
+class ImageResource(GeneratedImageResource):
+ @_model_validator(mode="before")
+ @classmethod
+ def _validate_generated_schema(cls, value: _Any) -> _Any:
+ errors = sorted(
+ _GENERATED_IMAGE_SCHEMA_VALIDATOR.iter_errors(value),
+ key=lambda error: (error.json_path, error.message),
+ )
+ if errors:
+ messages = "; ".join(f"{error.json_path}: {error.message}" for error in errors)
+ raise ValueError(messages)
+ return value
+
+
+# Stable public name derived from the CRD title.
+ImageFileReference = Source
diff --git a/libs/python/cua-sandbox/cua_sandbox/image.py b/libs/python/cua-sandbox/cua_sandbox/image.py
index f165a163ec..a186014636 100644
--- a/libs/python/cua-sandbox/cua_sandbox/image.py
+++ b/libs/python/cua-sandbox/cua_sandbox/image.py
@@ -24,7 +24,9 @@ from __future__ import annotations
import logging
from dataclasses import dataclass
from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+from cua_sandbox.generated.image_models import ImageFileReference, ImageResource
logger = logging.getLogger(__name__)
@@ -411,6 +413,87 @@ class Image:
# ── Serialization ────────────────────────────────────────────────────
+ def to_build_recipe(
+ self,
+ *,
+ name: str,
+ namespace: str,
+ tags: Mapping[str, str] | None = None,
+ timeout_seconds: int | None = None,
+ disk_size: str | None = None,
+ file_references: Mapping[str, ImageFileReference] | None = None,
+ ) -> Dict[str, Any]:
+ """Return a CRD-validated Image custom-resource manifest."""
+ if self._registry is not None:
+ raise ValueError("remote builds do not accept registry-only images")
+ if self._disk_path is not None:
+ raise ValueError("remote builds do not accept local disk images")
+ if self._snapshot_source is not None:
+ raise ValueError("remote builds do not accept snapshot source images")
+ if self.os_type != "linux" or self.kind != "vm":
+ raise ValueError("remote builds currently support only Linux VM recipes")
+
+ references = dict(file_references or {})
+ required_sources = {source for source, _ in self._files}
+ missing_sources = sorted(required_sources - references.keys())
+ if missing_sources:
+ raise ValueError(f"missing file reference for {missing_sources[0]}")
+ unused_sources = sorted(references.keys() - required_sources)
+ if unused_sources:
+ raise ValueError(f"unused file references: {', '.join(unused_sources)}")
+
+ layers = []
+ for layer in self._layers:
+ if layer["type"] == "app_install":
+ layers.append({"type": "app_install", "appId": layer["app_id"]})
+ else:
+ layers.append(layer)
+
+ recipe: Dict[str, Any] = {
+ "osType": self.os_type,
+ "distro": self.distro,
+ "version": self.version,
+ "kind": self.kind,
+ "layers": layers,
+ }
+ if self._env:
+ recipe["env"] = dict(self._env)
+ if self._ports:
+ recipe["ports"] = list(self._ports)
+ if self._files:
+ recipe["files"] = [
+ {
+ "source": references[source].model_dump(
+ by_alias=True,
+ exclude_none=True,
+ mode="json",
+ ),
+ "destination": destination,
+ }
+ for source, destination in self._files
+ ]
+
+ spec: Dict[str, Any] = {"recipe": recipe}
+ if tags:
+ spec["metadata"] = {"tags": dict(tags)}
+ build: Dict[str, Any] = {}
+ if timeout_seconds is not None:
+ build["timeoutSeconds"] = timeout_seconds
+ if disk_size is not None:
+ build["diskSize"] = disk_size
+ if build:
+ spec["build"] = build
+
+ validated = ImageResource.model_validate(
+ {
+ "apiVersion": "images.cua.ai/v1alpha1",
+ "kind": "Image",
+ "metadata": {"name": name, "namespace": namespace},
+ "spec": spec,
+ }
+ )
+ return validated.model_dump(by_alias=True, exclude_none=True, mode="json")
+
def to_dict(self) -> Dict[str, Any]:
"""Serialize to a plain dict suitable for JSON or cloud API."""
d: Dict[str, Any] = {
diff --git a/libs/python/cua-sandbox/pyproject.toml b/libs/python/cua-sandbox/pyproject.toml
index d6d1a212ce..32bdedc5fd 100644
--- a/libs/python/cua-sandbox/pyproject.toml
+++ b/libs/python/cua-sandbox/pyproject.toml
@@ -30,6 +30,8 @@ dependencies = [
"cua-core>=0.3.0,<0.4.0",
"cua-auto>=0.1.2",
"cua-fleet==0.1.14",
+ "pydantic>=2.11,<3.0",
+ "jsonschema>=4.23,<5.0",
"websockets>=12.0",
"httpx>=0.27.0",
"oras>=0.2.40",
@@ -90,6 +92,8 @@ testpaths = [
[dependency-groups]
dev = [
"cua-agent>=0.8.0",
+ "datamodel-code-generator==0.74.0",
+ "PyYAML>=6.0,<7.0",
"pytest>=9.0.2",
"pytest-asyncio>=1.3.0",
]
diff --git a/libs/python/cua-sandbox/schemas/image-v1alpha1.schema.json b/libs/python/cua-sandbox/schemas/image-v1alpha1.schema.json
new file mode 100644
index 0000000000..181e541c32
--- /dev/null
+++ b/libs/python/cua-sandbox/schemas/image-v1alpha1.schema.json
@@ -0,0 +1,478 @@
+{
+ "$id": "https://cua.ai/schemas/images.cua.ai/v1alpha1/image.json",
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "additionalProperties": false,
+ "properties": {
+ "apiVersion": {
+ "const": "images.cua.ai/v1alpha1",
+ "type": "string"
+ },
+ "kind": {
+ "const": "Image",
+ "type": "string"
+ },
+ "metadata": {
+ "additionalProperties": false,
+ "properties": {
+ "annotations": {
+ "additionalProperties": {
+ "maxLength": 4096,
+ "type": "string"
+ },
+ "maxProperties": 64,
+ "type": "object"
+ },
+ "labels": {
+ "additionalProperties": {
+ "maxLength": 4096,
+ "type": "string"
+ },
+ "maxProperties": 64,
+ "type": "object"
+ },
+ "name": {
+ "maxLength": 63,
+ "minLength": 1,
+ "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+ "type": "string"
+ },
+ "namespace": {
+ "maxLength": 63,
+ "minLength": 1,
+ "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "name",
+ "namespace"
+ ],
+ "title": "ImageObjectMeta",
+ "type": "object"
+ },
+ "spec": {
+ "additionalProperties": false,
+ "properties": {
+ "build": {
+ "additionalProperties": false,
+ "properties": {
+ "diskSize": {
+ "default": "40Gi",
+ "pattern": "^[1-9][0-9]*(Gi|Ti)$",
+ "type": "string"
+ },
+ "timeoutSeconds": {
+ "default": 7200,
+ "maximum": 86400,
+ "minimum": 60,
+ "type": "integer"
+ }
+ },
+ "title": "ImageBuildOptions",
+ "type": "object"
+ },
+ "metadata": {
+ "additionalProperties": false,
+ "properties": {
+ "tags": {
+ "additionalProperties": {
+ "maxLength": 256,
+ "type": "string"
+ },
+ "maxProperties": 32,
+ "type": "object"
+ }
+ },
+ "title": "ImageUserMetadata",
+ "type": "object"
+ },
+ "recipe": {
+ "additionalProperties": false,
+ "properties": {
+ "distro": {
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ },
+ "env": {
+ "additionalProperties": {
+ "maxLength": 8192,
+ "type": "string"
+ },
+ "maxProperties": 128,
+ "type": "object"
+ },
+ "files": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "destination": {
+ "maxLength": 4096,
+ "pattern": "^/.*",
+ "type": "string"
+ },
+ "source": {
+ "additionalProperties": false,
+ "properties": {
+ "digest": {
+ "pattern": "^sha256:[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "reference": {
+ "maxLength": 2048,
+ "minLength": 1,
+ "pattern": "^uploads/[a-z0-9]([-a-z0-9]*[a-z0-9])?/[A-Za-z0-9_-]+$",
+ "type": "string"
+ },
+ "sizeBytes": {
+ "format": "int64",
+ "maximum": 9223372036854775807,
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "reference",
+ "digest",
+ "sizeBytes"
+ ],
+ "title": "ImageFileReference",
+ "type": "object"
+ }
+ },
+ "required": [
+ "source",
+ "destination"
+ ],
+ "title": "ImageFile",
+ "type": "object"
+ },
+ "maxItems": 128,
+ "type": "array"
+ },
+ "kind": {
+ "enum": [
+ "vm"
+ ],
+ "type": "string"
+ },
+ "layers": {
+ "items": {
+ "additionalProperties": false,
+ "oneOf": [
+ {
+ "not": {
+ "anyOf": [
+ {
+ "required": [
+ "appId"
+ ]
+ },
+ {
+ "required": [
+ "command"
+ ]
+ }
+ ]
+ },
+ "properties": {
+ "type": {
+ "enum": [
+ "apt_install",
+ "pip_install",
+ "uv_install"
+ ]
+ }
+ },
+ "required": [
+ "packages"
+ ]
+ },
+ {
+ "not": {
+ "anyOf": [
+ {
+ "required": [
+ "packages"
+ ]
+ },
+ {
+ "required": [
+ "command"
+ ]
+ }
+ ]
+ },
+ "properties": {
+ "type": {
+ "enum": [
+ "app_install"
+ ]
+ }
+ },
+ "required": [
+ "appId"
+ ]
+ },
+ {
+ "not": {
+ "anyOf": [
+ {
+ "required": [
+ "packages"
+ ]
+ },
+ {
+ "required": [
+ "appId"
+ ]
+ }
+ ]
+ },
+ "properties": {
+ "type": {
+ "enum": [
+ "run"
+ ]
+ }
+ },
+ "required": [
+ "command"
+ ]
+ }
+ ],
+ "properties": {
+ "appId": {
+ "maxLength": 256,
+ "minLength": 1,
+ "type": "string"
+ },
+ "command": {
+ "maxLength": 16384,
+ "minLength": 1,
+ "type": "string"
+ },
+ "packages": {
+ "items": {
+ "maxLength": 256,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 256,
+ "minItems": 1,
+ "type": "array"
+ },
+ "type": {
+ "enum": [
+ "apt_install",
+ "pip_install",
+ "uv_install",
+ "app_install",
+ "run"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "title": "ImageLayer",
+ "type": "object"
+ },
+ "maxItems": 128,
+ "type": "array"
+ },
+ "osType": {
+ "enum": [
+ "linux"
+ ],
+ "type": "string"
+ },
+ "ports": {
+ "items": {
+ "maximum": 65535,
+ "minimum": 1,
+ "type": "integer"
+ },
+ "maxItems": 32,
+ "type": "array",
+ "uniqueItems": true
+ },
+ "version": {
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "osType",
+ "distro",
+ "version",
+ "kind",
+ "layers"
+ ],
+ "title": "ImageRecipe",
+ "type": "object"
+ }
+ },
+ "required": [
+ "recipe"
+ ],
+ "title": "ImageSpec",
+ "type": "object"
+ },
+ "status": {
+ "additionalProperties": false,
+ "properties": {
+ "artifacts": {
+ "additionalProperties": false,
+ "properties": {
+ "oci": {
+ "additionalProperties": false,
+ "properties": {
+ "digest": {
+ "pattern": "^sha256:[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "reference": {
+ "maxLength": 2048,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "reference",
+ "digest"
+ ],
+ "title": "ImageOciArtifact",
+ "type": "object"
+ },
+ "volumeSnapshot": {
+ "additionalProperties": false,
+ "properties": {
+ "name": {
+ "maxLength": 253,
+ "minLength": 1,
+ "type": "string"
+ },
+ "namespace": {
+ "maxLength": 63,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "namespace",
+ "name"
+ ],
+ "title": "ImageVolumeSnapshotArtifact",
+ "type": "object"
+ }
+ },
+ "title": "ImageArtifacts",
+ "type": "object"
+ },
+ "buildIdentity": {
+ "maxLength": 63,
+ "type": "string"
+ },
+ "conditions": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "lastTransitionTime": {
+ "format": "date-time",
+ "type": "string"
+ },
+ "message": {
+ "maxLength": 32768,
+ "type": "string"
+ },
+ "observedGeneration": {
+ "format": "int64",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "reason": {
+ "maxLength": 128,
+ "minLength": 1,
+ "type": "string"
+ },
+ "status": {
+ "enum": [
+ "True",
+ "False",
+ "Unknown"
+ ],
+ "type": "string"
+ },
+ "type": {
+ "maxLength": 64,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "status",
+ "reason",
+ "lastTransitionTime"
+ ],
+ "title": "ImageCondition",
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "logs": {
+ "additionalProperties": false,
+ "properties": {
+ "livePodName": {
+ "maxLength": 253,
+ "type": "string"
+ },
+ "retainedReference": {
+ "maxLength": 2048,
+ "type": "string"
+ }
+ },
+ "title": "ImageLogs",
+ "type": "object"
+ },
+ "observedGeneration": {
+ "format": "int64",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "phase": {
+ "enum": [
+ "Pending",
+ "Validating",
+ "Building",
+ "PushingOCI",
+ "Importing",
+ "Quiescing",
+ "Snapshotting",
+ "Ready",
+ "Failed",
+ "Cancelling"
+ ],
+ "type": "string"
+ },
+ "recipeDigest": {
+ "pattern": "^sha256:[0-9a-f]{64}$",
+ "type": "string"
+ }
+ },
+ "title": "ImageStatus",
+ "type": "object"
+ }
+ },
+ "required": [
+ "spec",
+ "apiVersion",
+ "kind",
+ "metadata"
+ ],
+ "title": "ImageResource",
+ "type": "object"
+}
diff --git a/libs/python/cua-sandbox/scripts/generate_image_models.py b/libs/python/cua-sandbox/scripts/generate_image_models.py
new file mode 100644
index 0000000000..c37aab278c
--- /dev/null
+++ b/libs/python/cua-sandbox/scripts/generate_image_models.py
@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+import tempfile
+from copy import deepcopy
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[4]
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+CRD_PATH = REPO_ROOT / "clusters/base/cua-images/crd.yaml"
+SCHEMA_PATH = PACKAGE_ROOT / "schemas/image-v1alpha1.schema.json"
+MODEL_PATH = PACKAGE_ROOT / "cua_sandbox/generated/image_models.py"
+API_VERSION = "images.cua.ai/v1alpha1"
+SCHEMA_ID = "https://cua.ai/schemas/images.cua.ai/v1alpha1/image.json"
+
+DNS_LABEL = r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
+
+
+def _load_crd() -> dict[str, Any]:
+ documents = list(yaml.safe_load_all(CRD_PATH.read_text()))
+ if len(documents) != 1:
+ raise ValueError(f"expected one CRD document, found {len(documents)}")
+ return documents[0]
+
+
+def _select_version(crd: dict[str, Any]) -> dict[str, Any]:
+ versions = [
+ version
+ for version in crd["spec"]["versions"]
+ if version["name"] == "v1alpha1" and version["served"] and version["storage"]
+ ]
+ if len(versions) != 1:
+ raise ValueError("expected one served storage version named v1alpha1")
+ return versions[0]
+
+
+def _writable_metadata_schema() -> dict[str, Any]:
+ string_map = {
+ "type": "object",
+ "additionalProperties": {"type": "string", "maxLength": 4096},
+ "maxProperties": 64,
+ }
+ return {
+ "title": "ImageObjectMeta",
+ "type": "object",
+ "additionalProperties": False,
+ "required": ["name", "namespace"],
+ "properties": {
+ "name": {"type": "string", "minLength": 1, "maxLength": 63, "pattern": DNS_LABEL},
+ "namespace": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 63,
+ "pattern": DNS_LABEL,
+ },
+ "labels": deepcopy(string_map),
+ "annotations": deepcopy(string_map),
+ },
+ }
+
+
+def _translate_kubernetes_extensions(value: Any) -> Any:
+ if isinstance(value, list):
+ return [_translate_kubernetes_extensions(item) for item in value]
+ if not isinstance(value, dict):
+ return value
+ translated = {key: _translate_kubernetes_extensions(item) for key, item in value.items()}
+ if translated.get("x-kubernetes-list-type") == "set":
+ translated["uniqueItems"] = True
+ return translated
+
+
+def _strip_kubernetes_extensions(value: Any) -> Any:
+ if isinstance(value, list):
+ return [_strip_kubernetes_extensions(item) for item in value]
+ if not isinstance(value, dict):
+ return value
+ return {
+ key: _strip_kubernetes_extensions(item)
+ for key, item in value.items()
+ if not key.startswith("x-kubernetes-")
+ }
+
+
+def _derive_strict_object_schemas(value: Any) -> Any:
+ if isinstance(value, list):
+ return [_derive_strict_object_schemas(item) for item in value]
+ if not isinstance(value, dict):
+ return value
+ strict = {key: _derive_strict_object_schemas(item) for key, item in value.items()}
+ if (
+ strict.get("type") == "object"
+ and "properties" in strict
+ and not isinstance(strict.get("additionalProperties"), dict)
+ ):
+ strict["additionalProperties"] = False
+ return strict
+
+
+def build_schema() -> dict[str, Any]:
+ crd = _load_crd()
+ version = _select_version(crd)
+ schema = _derive_strict_object_schemas(
+ _strip_kubernetes_extensions(
+ _translate_kubernetes_extensions(deepcopy(version["schema"]["openAPIV3Schema"]))
+ )
+ )
+ schema["$schema"] = "https://json-schema.org/draft/2020-12/schema"
+ schema["$id"] = SCHEMA_ID
+ schema["title"] = "ImageResource"
+ schema.setdefault("required", [])
+ for field in ("apiVersion", "kind", "metadata", "spec"):
+ if field not in schema["required"]:
+ schema["required"].append(field)
+ schema["properties"]["apiVersion"] = {"type": "string", "const": API_VERSION}
+ schema["properties"]["kind"] = {"type": "string", "const": "Image"}
+ schema["properties"]["metadata"] = _writable_metadata_schema()
+ return schema
+
+
+def _render_models(schema_path: Path, output_path: Path) -> None:
+ subprocess.run(
+ [
+ sys.executable,
+ "-m",
+ "datamodel_code_generator",
+ "--input",
+ str(schema_path),
+ "--input-file-type",
+ "jsonschema",
+ "--output",
+ str(output_path),
+ "--output-model-type",
+ "pydantic_v2.BaseModel",
+ "--target-python-version",
+ "3.11",
+ "--snake-case-field",
+ "--use-standard-collections",
+ "--use-union-operator",
+ "--use-schema-description",
+ "--use-field-description",
+ "--disable-timestamp",
+ ],
+ check=True,
+ )
+
+
+def _format_model(output_path: Path) -> None:
+ subprocess.run(
+ [
+ sys.executable,
+ "-m",
+ "isort",
+ "--settings-path",
+ str(REPO_ROOT / "pyproject.toml"),
+ str(output_path),
+ ],
+ check=True,
+ cwd=REPO_ROOT,
+ )
+ subprocess.run(
+ [
+ sys.executable,
+ "-m",
+ "black",
+ "--quiet",
+ "--config",
+ str(REPO_ROOT / "pyproject.toml"),
+ str(output_path),
+ ],
+ check=True,
+ cwd=REPO_ROOT,
+ )
+
+
+def _schema_validation_imports() -> str:
+ return """
+import json as _json
+from typing import Any as _Any
+
+from jsonschema import Draft202012Validator as _Draft202012Validator
+from pydantic import model_validator as _model_validator
+"""
+
+
+def _schema_validation_wrapper(schema_content: str) -> str:
+ schema_literal = json.dumps(schema_content)
+ return f"""
+_GENERATED_IMAGE_SCHEMA = _json.loads({schema_literal})
+_GENERATED_IMAGE_SCHEMA_VALIDATOR = _Draft202012Validator(_GENERATED_IMAGE_SCHEMA)
+GeneratedImageResource = ImageResource
+
+
+class ImageResource(GeneratedImageResource):
+ @_model_validator(mode="before")
+ @classmethod
+ def _validate_generated_schema(cls, value: _Any) -> _Any:
+ errors = sorted(
+ _GENERATED_IMAGE_SCHEMA_VALIDATOR.iter_errors(value),
+ key=lambda error: (error.json_path, error.message),
+ )
+ if errors:
+ messages = "; ".join(
+ f"{{error.json_path}}: {{error.message}}" for error in errors
+ )
+ raise ValueError(messages)
+ return value
+"""
+
+
+def _source_header() -> str:
+ digest = hashlib.sha256(CRD_PATH.read_bytes()).hexdigest()
+ return f"# Source: clusters/base/cua-images/crd.yaml\n# Source SHA-256: {digest}\n"
+
+
+def _write_or_check(path: Path, content: str, *, check: bool) -> None:
+ if check:
+ if not path.exists() or path.read_text() != content:
+ raise SystemExit(f"generated artifact is stale: {path.relative_to(REPO_ROOT)}")
+ return
+ path.parent.mkdir(parents=True, exist_ok=True)
+ temporary = path.with_suffix(path.suffix + ".tmp")
+ temporary.write_text(content)
+ temporary.replace(path)
+
+
+def generate(*, check: bool) -> None:
+ schema = build_schema()
+ schema_content = json.dumps(schema, indent=2, sort_keys=True) + "\n"
+ with tempfile.TemporaryDirectory() as temporary_directory:
+ temporary_root = Path(temporary_directory)
+ temporary_schema = temporary_root / "image.schema.json"
+ temporary_model = temporary_root / "image_models.py"
+ temporary_schema.write_text(schema_content)
+ _render_models(temporary_schema, temporary_model)
+ generated_model = temporary_model.read_text()
+ future_import = "from __future__ import annotations\n"
+ if generated_model.count(future_import) != 1:
+ raise ValueError("expected one future annotations import in generated model")
+ generated_model = generated_model.replace(
+ future_import,
+ future_import + _schema_validation_imports(),
+ 1,
+ )
+ model_content = _source_header() + generated_model
+ if "class Source(BaseModel):" not in model_content:
+ raise ValueError("expected datamodel-code-generator to emit Source")
+ if "class ImageResource(BaseModel):" not in model_content:
+ raise ValueError("expected datamodel-code-generator to emit ImageResource")
+ model_content += _schema_validation_wrapper(schema_content)
+ model_content += (
+ "\n# Stable public name derived from the CRD title.\nImageFileReference = Source\n"
+ )
+ temporary_model.write_text(model_content)
+ _format_model(temporary_model)
+ model_content = temporary_model.read_text()
+ _write_or_check(SCHEMA_PATH, schema_content, check=check)
+ _write_or_check(MODEL_PATH, model_content, check=check)
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("--check", action="store_true")
+ arguments = parser.parse_args()
+ generate(check=arguments.check)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/libs/python/cua-sandbox/tests/test_image_api_workflows.py b/libs/python/cua-sandbox/tests/test_image_api_workflows.py
new file mode 100644
index 0000000000..a6ddc8d73e
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_image_api_workflows.py
@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import re
+import shlex
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[4]
+CI_WORKFLOW = REPO_ROOT / ".github/workflows/ci-image-api.yml"
+CD_WORKFLOW = REPO_ROOT / ".github/workflows/cd-image-api.yml"
+
+
+def test_image_api_ci_covers_the_contract_and_generated_artifacts() -> None:
+ workflow = yaml.safe_load(CI_WORKFLOW.read_text())
+ pull_request_paths = workflow[True]["pull_request"]["paths"]
+ push_paths = workflow[True]["push"]["paths"]
+ assert "clusters/base/cua-images/**" in pull_request_paths
+ assert "libs/python/cua-sandbox/cua_sandbox/image.py" in pull_request_paths
+ assert "libs/python/cua-sandbox/cua_sandbox/generated/**" in pull_request_paths
+ assert "libs/python/cua-sandbox/schemas/**" in pull_request_paths
+ assert "libs/python/cua-sandbox/scripts/generate_image_models.py" in pull_request_paths
+ assert "libs/python/cua-sandbox/uv.lock" in pull_request_paths
+ assert ".github/workflows/cd-image-api.yml" in pull_request_paths
+ assert ".github/workflows/cd-image-api.yml" in push_paths
+ commands = "\n".join(step.get("run", "") for step in workflow["jobs"]["validate"]["steps"])
+ assert "uv sync --project libs/python/cua-sandbox --group dev --extra dev" in commands
+ assert "generate_image_models.py --check" in commands
+ assert 'export PATH="$(go env GOPATH)/bin:$PATH"' in commands
+ assert "kustomize build clusters/base/cua-images" in commands
+ assert "test_image_crd.py" in commands
+ assert "test_image_model_generation.py" in commands
+ assert "test_image_build_recipe.py" in commands
+ assert "test_image_api_workflows.py" in commands
+ assert "test_image.py" in commands
+
+ assert workflow["jobs"]["validate"]["timeout-minutes"] >= 15
+ admission = next(
+ step
+ for step in workflow["jobs"]["validate"]["steps"]
+ if step["name"] == "Validate CRD API-server admission"
+ )["run"]
+ assert "go install sigs.k8s.io/[email protected]" in commands
+ assert "kind create cluster --name cua-image-api" in admission
+ assert (
+ "kubectl apply --server-side --dry-run=server -f clusters/base/cua-images/crd.yaml"
+ in admission
+ )
+
+
+def test_image_api_cd_publishes_only_versioned_artifacts() -> None:
+ workflow = yaml.safe_load(CD_WORKFLOW.read_text())
+ assert workflow[True]["push"]["tags"] == ["image-api-v*"]
+ assert workflow["permissions"] == {"contents": "read", "packages": "write"}
+ commands = "\n".join(step.get("run", "") for step in workflow["jobs"]["publish"]["steps"])
+ assert "flux_2.9.4_linux_amd64.tar.gz" in commands
+ assert "c2c397a52930f52d2005c01d276116b059d062de379386d58e98115380a766a2" in commands
+ assert "flux push artifact" in commands
+
+
+def test_image_api_cd_binds_manual_publication_to_the_release_tag_commit() -> None:
+ workflow = yaml.safe_load(CD_WORKFLOW.read_text())
+ steps = workflow["jobs"]["publish"]["steps"]
+ checkout = next(step for step in steps if step["name"] == "Checkout repository")
+ version = next(step for step in steps if step["name"] == "Determine version")["run"]
+
+ assert checkout.get("with", {}).get("fetch-depth") == 0
+ assert 'VERSION="${MANUAL_VERSION}"' in version
+ assert 'VERSION="${GITHUB_REF_NAME#image-api-v}"' in version
+ assert '[[ ! "${VERSION}" =~ ^[0-9]+\\.[0-9]+\\.[0-9]+$ ]]' in version
+ assert 'RELEASE_TAG="image-api-v${VERSION}"' in version
+ assert 'TAG_COMMIT="$(git rev-list -n 1 "${RELEASE_TAG}")"' in version
+ assert 'CHECKED_OUT_COMMIT="$(git rev-parse HEAD)"' in version
+ assert 'if [[ "${TAG_COMMIT}" != "${CHECKED_OUT_COMMIT}" ]]; then' in version
+ assert 'echo "release_tag=${RELEASE_TAG}" >>"${GITHUB_OUTPUT}"' in version
+ assert 'echo "commit=${TAG_COMMIT}" >>"${GITHUB_OUTPUT}"' in version
+
+
+def test_image_api_cd_authenticates_and_rejects_existing_artifacts_before_push() -> None:
+ workflow = yaml.safe_load(CD_WORKFLOW.read_text())
+ steps = workflow["jobs"]["publish"]["steps"]
+ authenticate = next(step for step in steps if step["name"] == "Authenticate to GHCR")["run"]
+ publish = next(step for step in steps if step["name"] == "Publish Image API artifact")["run"]
+
+ assert "docker login ghcr.io" in authenticate
+ assert 'echo "${{ github.token }}"' in authenticate
+ assert '--username "${{ github.actor }}"' in authenticate
+ assert "--password-stdin" in authenticate
+ assert 'ARTIFACT_REFERENCE="${ARTIFACT_DESTINATION#oci://}"' in publish
+ assert 'docker manifest inspect "${ARTIFACT_REFERENCE}"' in publish
+ assert 'echo "Image API artifact already exists: ${ARTIFACT_DESTINATION}" >&2' in publish
+ assert publish.index("docker manifest inspect") < publish.index("flux push artifact")
+
+
+def test_image_api_cd_uses_an_exact_immutable_artifact_destination_and_metadata() -> None:
+ workflow = yaml.safe_load(CD_WORKFLOW.read_text())
+ publish = next(
+ step
+ for step in workflow["jobs"]["publish"]["steps"]
+ if step["name"] == "Publish Image API artifact"
+ )
+ commands = publish["run"]
+ destination_match = re.search(
+ r'^ARTIFACT_DESTINATION="(?P<destination>[^"]+)"$', commands, re.MULTILINE
+ )
+
+ assert destination_match is not None
+ destination = destination_match.group("destination")
+ assert re.fullmatch(r"oci://ghcr\.io/trycua/cua-image-api:v\$\{VERSION\}", destination)
+
+ tokens = shlex.split(commands)
+ flux_push = tokens.index("flux")
+ assert tokens[flux_push : flux_push + 4] == [
+ "flux",
+ "push",
+ "artifact",
+ "${ARTIFACT_DESTINATION}",
+ ]
+ assert "--path=clusters/base/cua-images" in tokens
+ assert "--source=${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}" in tokens
+ assert "--revision=${RELEASE_TAG}@sha1:${COMMIT}" in tokens
+
+
+def test_image_api_cd_serializes_publication_by_version_across_triggers() -> None:
+ workflow = yaml.safe_load(CD_WORKFLOW.read_text())
+
+ assert workflow.get("concurrency") == {
+ "group": "image-api-${{ github.event_name == 'workflow_dispatch' && format('image-api-v{0}', inputs.version) || github.ref_name }}",
+ "cancel-in-progress": False,
+ }
+
+
+def test_image_api_cd_fails_closed_unless_the_manifest_is_confirmed_missing() -> None:
+ workflow = yaml.safe_load(CD_WORKFLOW.read_text())
+ publish = next(
+ step
+ for step in workflow["jobs"]["publish"]["steps"]
+ if step["name"] == "Publish Image API artifact"
+ )["run"]
+
+ assert 'MANIFEST_OUTPUT="$(docker manifest inspect "${ARTIFACT_REFERENCE}" 2>&1)"' in publish
+ assert "MANIFEST_STATUS=$?" in publish
+ assert 'if [[ "${MANIFEST_STATUS}" -eq 0 ]]; then' in publish
+ assert "grep -Eiq 'manifest unknown|no such manifest'" in publish
+ assert (
+ 'echo "could not verify Image API artifact absence: ${ARTIFACT_DESTINATION}" >&2' in publish
+ )
+ assert publish.index("MANIFEST_STATUS=$?") < publish.index("flux push artifact")
+
+
+def test_image_api_cd_passes_manual_version_through_the_environment() -> None:
+ workflow = yaml.safe_load(CD_WORKFLOW.read_text())
+ publish = workflow["jobs"]["publish"]
+ version = next(step for step in publish["steps"] if step["name"] == "Determine version")["run"]
+
+ assert publish.get("env", {}).get("MANUAL_VERSION") == "${{ inputs.version }}"
+ assert 'VERSION="${MANUAL_VERSION}"' in version
+ assert "${{ inputs.version }}" not in version
diff --git a/libs/python/cua-sandbox/tests/test_image_build_recipe.py b/libs/python/cua-sandbox/tests/test_image_build_recipe.py
new file mode 100644
index 0000000000..facaa3379b
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_image_build_recipe.py
@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import hashlib
+import json
+
+import pytest
+from cua_sandbox import Image, ImageFileReference
+from pydantic import ValidationError
+
+
+def _reference(character: str = "a", *, size_bytes: int = 12) -> ImageFileReference:
+ return ImageFileReference.model_validate(
+ {
+ "reference": f"uploads/tenant-a/{character}",
+ "digest": "sha256:" + character * 64,
+ "sizeBytes": size_bytes,
+ }
+ )
+
+
+def test_to_build_recipe_returns_a_complete_validated_resource() -> None:
+ resource = (
+ Image.linux("ubuntu", "24.04")
+ .apt_install("curl", "git")
+ .pip_install("playwright")
+ .run("python -m playwright install chromium")
+ .env(APP_ENV="test")
+ .expose(8000)
+ .to_build_recipe(
+ name="browser-test",
+ namespace="tenant-a",
+ tags={"team": "evals"},
+ timeout_seconds=3600,
+ disk_size="40Gi",
+ )
+ )
+ assert resource == {
+ "apiVersion": "images.cua.ai/v1alpha1",
+ "kind": "Image",
+ "metadata": {"name": "browser-test", "namespace": "tenant-a"},
+ "spec": {
+ "recipe": {
+ "osType": "linux",
+ "distro": "ubuntu",
+ "version": "24.04",
+ "kind": "vm",
+ "layers": [
+ {"type": "apt_install", "packages": ["curl", "git"]},
+ {"type": "pip_install", "packages": ["playwright"]},
+ {"type": "run", "command": "python -m playwright install chromium"},
+ ],
+ "env": {"APP_ENV": "test"},
+ "ports": [8000],
+ },
+ "metadata": {"tags": {"team": "evals"}},
+ "build": {"timeoutSeconds": 3600, "diskSize": "40Gi"},
+ },
+ }
+ assert "status" not in resource
+
+
+def test_to_build_recipe_normalizes_app_install_to_crd_field_names() -> None:
+ image = Image.linux().app_install("playwright")
+
+ assert image.to_dict()["layers"] == [{"type": "app_install", "app_id": "playwright"}]
+ assert image.to_build_recipe(name="app-test", namespace="tenant-a")["spec"]["recipe"][
+ "layers"
+ ] == [{"type": "app_install", "appId": "playwright"}]
+
+
+def test_to_build_recipe_resolves_copied_files_without_emitting_local_paths() -> None:
+ resource = (
+ Image.linux()
+ .copy("./secret.txt", "/opt/input.txt")
+ .to_build_recipe(
+ name="with-file",
+ namespace="tenant-a",
+ file_references={"./secret.txt": _reference()},
+ )
+ )
+ serialized = json.dumps(resource, sort_keys=True, separators=(",", ":"))
+ assert "./secret.txt" not in serialized
+ assert resource["spec"]["recipe"]["files"] == [
+ {
+ "source": {
+ "reference": "uploads/tenant-a/a",
+ "digest": "sha256:" + "a" * 64,
+ "sizeBytes": 12,
+ },
+ "destination": "/opt/input.txt",
+ }
+ ]
+
+
+ "reference",
+ [
+ "/tmp/secret.txt",
+ "file:///tmp/secret.txt",
+ "data:text/plain;base64,c2VjcmV0",
+ "uploads/tenant-a/../secret",
+ ],
+)
+def test_to_build_recipe_rejects_non_uploaded_file_references(reference: str) -> None:
+ invalid_reference = _reference().model_copy(update={"reference": reference})
+
+ with pytest.raises(ValidationError):
+ Image.linux().copy("./input.txt", "/opt/input.txt").to_build_recipe(
+ name="with-file",
+ namespace="tenant-a",
+ file_references={"./input.txt": invalid_reference},
+ )
+
+
+def test_to_build_recipe_rejects_missing_and_unused_file_references() -> None:
+ image = Image.linux().copy("./input.txt", "/opt/input.txt")
+ with pytest.raises(ValueError, match="missing file reference for ./input.txt"):
+ image.to_build_recipe(name="missing", namespace="tenant-a")
+ with pytest.raises(ValueError, match="unused file references: ./extra.txt"):
+ Image.linux().to_build_recipe(
+ name="unused",
+ namespace="tenant-a",
+ file_references={"./extra.txt": _reference()},
+ )
+
+
+ "image, message",
+ [
+ (Image.windows(), "only Linux VM recipes"),
+ (Image.macos(), "only Linux VM recipes"),
+ (Image.android(), "only Linux VM recipes"),
+ (Image.linux(kind="container"), "only Linux VM recipes"),
+ (Image.from_registry("example.invalid/image:tag"), "registry-only images"),
+ (Image.from_file("/tmp/example.qcow2", os_type="linux"), "local disk images"),
+ (
+ Image.linux()._with(_snapshot_source={"snapshotId": "snapshot-123"}),
+ "snapshot source images",
+ ),
+ ],
+)
+def test_to_build_recipe_rejects_unsupported_image_sources(image: Image, message: str) -> None:
+ with pytest.raises(ValueError, match=message):
+ image.to_build_recipe(name="unsupported", namespace="tenant-a")
+
+
+def test_to_build_recipe_uses_generated_validation() -> None:
+ with pytest.raises(ValidationError):
+ Image.linux().to_build_recipe(name="Invalid_Name", namespace="tenant-a")
+ with pytest.raises(ValidationError):
+ Image.linux().to_build_recipe(name="demo", namespace="tenant-a", disk_size="40GB")
+
+
+def test_to_build_recipe_is_deterministic() -> None:
+ image = Image.linux().apt_install("curl").env(A="1", B="2")
+ first = image.to_build_recipe(name="demo", namespace="tenant-a")
+ second = image.to_build_recipe(name="demo", namespace="tenant-a")
+ canonical_first = json.dumps(first, sort_keys=True, separators=(",", ":"))
+ canonical_second = json.dumps(second, sort_keys=True, separators=(",", ":"))
+ assert canonical_first == canonical_second
+ assert (
+ hashlib.sha256(canonical_first.encode()).hexdigest()
+ == hashlib.sha256(canonical_second.encode()).hexdigest()
+ )
+
+
+def test_to_dict_remains_the_legacy_local_contract() -> None:
+ image = Image.linux().copy("./input.txt", "/opt/input.txt")
+ assert image.to_dict()["files"] == [["./input.txt", "/opt/input.txt"]]
diff --git a/libs/python/cua-sandbox/tests/test_image_crd.py b/libs/python/cua-sandbox/tests/test_image_crd.py
new file mode 100644
index 0000000000..2fbd40fd2d
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_image_crd.py
@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[4]
+CRD_PATH = REPO_ROOT / "clusters/base/cua-images/crd.yaml"
+KUSTOMIZATION_PATH = REPO_ROOT / "clusters/base/cua-images/kustomization.yaml"
+
+
+def _crd() -> dict:
+ documents = list(yaml.safe_load_all(CRD_PATH.read_text()))
+ assert len(documents) == 1
+ return documents[0]
+
+
+def _version() -> dict:
+ versions = _crd()["spec"]["versions"]
+ assert len(versions) == 1
+ return versions[0]
+
+
+def _schema_nodes(value: Any) -> list[dict[str, Any]]:
+ if isinstance(value, list):
+ return [node for item in value for node in _schema_nodes(item)]
+ if not isinstance(value, dict):
+ return []
+ return [value, *[node for item in value.values() for node in _schema_nodes(item)]]
+
+
+def test_image_crd_identity_and_scope() -> None:
+ crd = _crd()
+ assert crd["apiVersion"] == "apiextensions.k8s.io/v1"
+ assert crd["kind"] == "CustomResourceDefinition"
+ assert crd["metadata"]["name"] == "images.images.cua.ai"
+ assert crd["spec"]["group"] == "images.cua.ai"
+ assert crd["spec"]["scope"] == "Namespaced"
+ assert crd["spec"]["names"] == {
+ "kind": "Image",
+ "listKind": "ImageList",
+ "plural": "images",
+ "shortNames": ["cuaimg"],
+ "singular": "image",
+ }
+
+
+def test_image_crd_serves_one_storage_version_with_status() -> None:
+ version = _version()
+ assert version["name"] == "v1alpha1"
+ assert version["served"] is True
+ assert version["storage"] is True
+ assert version["subresources"] == {"status": {}}
+ assert [column["name"] for column in version["additionalPrinterColumns"]] == [
+ "Phase",
+ "Ready",
+ "Generation",
+ "Age",
+ ]
+
+
+def test_image_crd_restricts_the_initial_recipe_contract() -> None:
+ schema = _version()["schema"]["openAPIV3Schema"]
+ recipe = schema["properties"]["spec"]["properties"]["recipe"]
+ assert recipe["properties"]["osType"]["enum"] == ["linux"]
+ assert recipe["properties"]["kind"]["enum"] == ["vm"]
+ assert recipe["properties"]["layers"]["maxItems"] == 128
+ assert recipe["properties"]["files"]["maxItems"] == 128
+ assert "registry" not in recipe["properties"]
+ assert "diskPath" not in recipe["properties"]
+ assert "snapshotSource" not in recipe["properties"]
+
+
+def test_image_crd_files_use_external_references() -> None:
+ schema = _version()["schema"]["openAPIV3Schema"]
+ file_item = schema["properties"]["spec"]["properties"]["recipe"]["properties"]["files"]["items"]
+ assert file_item["required"] == ["source", "destination"]
+ assert file_item["properties"]["source"]["required"] == [
+ "reference",
+ "digest",
+ "sizeBytes",
+ ]
+ reference = file_item["properties"]["source"]["properties"]["reference"]
+ assert reference["pattern"] == "^uploads/[a-z0-9]([-a-z0-9]*[a-z0-9])?/[A-Za-z0-9_-]+$"
+ assert (
+ file_item["properties"]["source"]["properties"]["sizeBytes"]["maximum"]
+ == 9223372036854775807
+ )
+ assert "content" not in file_item["properties"]
+ assert "path" not in file_item["properties"]["source"]["properties"]
+
+
+def test_image_crd_uses_only_kubernetes_valid_structural_keywords() -> None:
+ schema = _version()["schema"]["openAPIV3Schema"]
+ nodes = _schema_nodes(schema)
+
+ assert all(node.get("additionalProperties") is not False for node in nodes)
+ assert all(node.get("uniqueItems") is not True for node in nodes)
+ ports = schema["properties"]["spec"]["properties"]["recipe"]["properties"]["ports"]
+ assert ports["x-kubernetes-list-type"] == "set"
+
+
+def test_image_crd_layers_reject_fields_from_other_layer_shapes() -> None:
+ layer = _version()["schema"]["openAPIV3Schema"]["properties"]["spec"]["properties"]["recipe"][
+ "properties"
+ ]["layers"]["items"]
+ exclusions = [
+ {field for alternative in branch["not"]["anyOf"] for field in alternative["required"]}
+ for branch in layer["oneOf"]
+ ]
+
+ assert all("additionalProperties" not in branch for branch in layer["oneOf"])
+ assert exclusions == [{"appId", "command"}, {"command", "packages"}, {"appId", "packages"}]
+
+
+def test_image_crd_has_controller_owned_status_contract() -> None:
+ schema = _version()["schema"]["openAPIV3Schema"]
+ status = schema["properties"]["status"]
+ assert status["properties"]["observedGeneration"]["format"] == "int64"
+ assert status["properties"]["recipeDigest"]["pattern"] == "^sha256:[0-9a-f]{64}$"
+ assert status["properties"]["artifacts"]["properties"]["oci"]["required"] == [
+ "reference",
+ "digest",
+ ]
+ assert status["properties"]["artifacts"]["properties"]["volumeSnapshot"]["required"] == [
+ "namespace",
+ "name",
+ ]
+
+
+def test_image_crd_kustomization_contains_only_the_crd() -> None:
+ kustomization = yaml.safe_load(KUSTOMIZATION_PATH.read_text())
+ assert kustomization == {
+ "apiVersion": "kustomize.config.k8s.io/v1beta1",
+ "kind": "Kustomization",
+ "resources": ["crd.yaml"],
+ }
diff --git a/libs/python/cua-sandbox/tests/test_image_model_generation.py b/libs/python/cua-sandbox/tests/test_image_model_generation.py
new file mode 100644
index 0000000000..93088cf993
--- /dev/null
+++ b/libs/python/cua-sandbox/tests/test_image_model_generation.py
@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from cua_sandbox.generated.image_models import ImageFileReference, ImageResource
+from pydantic import ValidationError
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = PACKAGE_ROOT / "scripts/generate_image_models.py"
+SCHEMA = PACKAGE_ROOT / "schemas/image-v1alpha1.schema.json"
+MODEL = PACKAGE_ROOT / "cua_sandbox/generated/image_models.py"
+
+
+def test_generated_artifacts_match_the_canonical_crd() -> None:
+ subprocess.run([sys.executable, str(SCRIPT), "--check"], check=True)
+
+
+def test_generated_model_is_black_formatted() -> None:
+ subprocess.run([sys.executable, "-m", "black", "--check", str(MODEL)], check=True)
+
+
+def test_generated_model_is_ruff_clean() -> None:
+ subprocess.run([sys.executable, "-m", "ruff", "check", str(MODEL)], check=True)
+
+
+def test_generated_schema_identifies_the_image_resource() -> None:
+ schema = json.loads(SCHEMA.read_text())
+ assert schema["$id"] == "https://cua.ai/schemas/images.cua.ai/v1alpha1/image.json"
+ assert schema["title"] == "ImageResource"
+ assert schema["properties"]["spec"]["title"] == "ImageSpec"
+ assert "status" in schema["properties"]
+
+
+def test_generated_models_validate_the_resource_and_file_reference() -> None:
+ file_reference = ImageFileReference.model_validate(
+ {
+ "reference": "uploads/tenant-a/sha256-demo",
+ "digest": "sha256:" + "a" * 64,
+ "sizeBytes": 123,
+ }
+ )
+ resource = ImageResource.model_validate(
+ {
+ "apiVersion": "images.cua.ai/v1alpha1",
+ "kind": "Image",
+ "metadata": {"name": "browser-test", "namespace": "tenant-a"},
+ "spec": {
+ "recipe": {
+ "osType": "linux",
+ "distro": "ubuntu",
+ "version": "24.04",
+ "kind": "vm",
+ "layers": [{"type": "apt_install", "packages": ["curl"]}],
+ "files": [
+ {
+ "source": file_reference.model_dump(by_alias=True, mode="json"),
+ "destination": "/opt/input.txt",
+ }
+ ],
+ }
+ },
+ }
+ )
+ assert resource.api_version == "images.cua.ai/v1alpha1"
+ assert resource.spec.recipe.os_type == "linux"
+
+
+ "reference",
+ [
+ "/tmp/secret.txt",
+ "file:///tmp/secret.txt",
+ "data:text/plain;base64,c2VjcmV0",
+ "uploads/tenant-a/../secret",
+ ],
+)
+def test_generated_models_reject_non_uploaded_file_references(reference: str) -> None:
+ with pytest.raises(ValidationError):
+ ImageFileReference.model_validate(
+ {
+ "reference": reference,
+ "digest": "sha256:" + "a" * 64,
+ "sizeBytes": 123,
+ }
+ )
+
+
+def test_generated_models_reject_unknown_file_reference_fields() -> None:
+ with pytest.raises(ValidationError):
+ ImageFileReference.model_validate(
+ {
+ "reference": "uploads/tenant-a/a",
+ "digest": "sha256:" + "a" * 64,
+ "sizeBytes": 123,
+ "path": "/tmp/secret.txt",
+ }
+ )
+
+
+ "layer",
+ [
+ {"type": "apt_install", "packages": ["curl"], "appId": "playwright"},
+ {"type": "app_install", "appId": "playwright", "command": "echo unexpected"},
+ {"type": "run", "command": "echo ok", "packages": ["curl"]},
+ ],
+)
+def test_generated_models_reject_irrelevant_layer_fields(layer: dict[str, object]) -> None:
+ with pytest.raises(ValidationError):
+ ImageResource.model_validate(
+ {
+ "apiVersion": "images.cua.ai/v1alpha1",
+ "kind": "Image",
+ "metadata": {"name": "browser-test", "namespace": "tenant-a"},
+ "spec": {
+ "recipe": {
+ "osType": "linux",
+ "distro": "ubuntu",
+ "version": "24.04",
+ "kind": "vm",
+ "layers": [layer],
+ }
+ },
+ }
+ )
+
+
+def test_generated_models_accept_file_reference_at_kubernetes_int64_maximum() -> None:
+ reference = ImageFileReference.model_validate(
+ {
+ "reference": "uploads/tenant-a/a",
+ "digest": "sha256:" + "a" * 64,
+ "sizeBytes": 9223372036854775807,
+ }
+ )
+ assert reference.size_bytes == 9223372036854775807
+
+
+def test_generated_models_reject_file_reference_larger_than_kubernetes_int64() -> None:
+ with pytest.raises(ValidationError):
+ ImageFileReference.model_validate(
+ {
+ "reference": "uploads/tenant-a/a",
+ "digest": "sha256:" + "a" * 64,
+ "sizeBytes": 9223372036854775808,
+ }
+ )
+
+
+def test_generated_models_reject_duplicate_ports() -> None:
+ with pytest.raises(ValidationError):
+ ImageResource.model_validate(
+ {
+ "apiVersion": "images.cua.ai/v1alpha1",
+ "kind": "Image",
+ "metadata": {"name": "browser-test", "namespace": "tenant-a"},
+ "spec": {
+ "recipe": {
+ "osType": "linux",
+ "distro": "ubuntu",
+ "version": "24.04",
+ "kind": "vm",
+ "layers": [{"type": "apt_install", "packages": ["curl"]}],
+ "ports": [8080, 8080],
+ }
+ },
+ }
+ )
diff --git a/libs/python/cua-sandbox/uv.lock b/libs/python/cua-sandbox/uv.lock
index df081a6c48..4585b9fa45 100644
--- a/libs/python/cua-sandbox/uv.lock
+++ b/libs/python/cua-sandbox/uv.lock
@@ -132,6 +132,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/38/0e/27be9fdef66e72d64c0cdc3cc2823101b80585f8119b5c112c2e8f5f7dab/anyio-4.12.1-py3-none-any.whl", hash = "sha256:d405828884fc140aa80a3c667b8beed277f1dfedec42ba031bd6ac3db606ab6c", size = 113592, upload-time = "2026-01-06T11:45:19.497Z" },
]
+[[package]]
+name = "argcomplete"
+version = "3.7.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/87/6f/5a73f04007ca950701765949209f068da628bd11f9c2da287278ce91e0ee/argcomplete-3.7.2.tar.gz", hash = "sha256:aad8b69a0b9969edb62db0d1752354c0d50717b10e0cbb00e2a958381b9fc6b9", size = 74473, upload-time = "2026-08-06T04:53:21.662Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/46/bd/551ee6af426af84ca33e02622be722925c196608e9127d731ef17c47f06e/argcomplete-3.7.2-py3-none-any.whl", hash = "sha256:6029205678bdd9c1c728a155f5f9ecf5812393f969eef58807641a2bc2aa5b19", size = 43294, upload-time = "2026-08-06T04:53:20.246Z" },
+]
+
[[package]]
name = "attrs"
version = "25.4.0"
@@ -216,6 +225,38 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/e4/f8/972c96f5a2b6c4b3deca57009d93e946bbdbe2241dca9806d502f29dd3ee/bcrypt-5.0.0-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:6b8f520b61e8781efee73cba14e3e8c9556ccfb375623f4f97429544734545b4", size = 273375, upload-time = "2025-09-25T19:50:45.43Z" },
]
+[[package]]
+name = "black"
+version = "26.5.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "click" },
+ { name = "mypy-extensions" },
+ { name = "packaging" },
+ { name = "pathspec" },
+ { name = "platformdirs" },
+ { name = "pytokens" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/37/5628dd55bf2b34257fc7603f0fe97c40e3aaf24265f416a9c85c95ca1436/black-26.5.1.tar.gz", hash = "sha256:dd321f668053961824bcc1be1cc1df748b2d7e4fa28086b08331e577b0100a73", size = 679439, upload-time = "2026-05-18T16:53:36.107Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/4b/96/3c3e09f09f44a37aac36b178a279cd19aa7001bd796187a7b162a294c81f/black-26.5.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:96ae2c733b2aabdd9986e2c5df628ff3473676cd1c5faded1ff496cf6d74083c", size = 1970639, upload-time = "2026-05-18T17:05:11.461Z" },
+ { url = "https://files.pythonhosted.org/packages/83/ea/5ad117b9ee3ecd933c712bcbae610006e5b7cc9f41c526cd7ed3b6c4124c/black-26.5.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:0e48b87e03bf109288e55cfceadcfa15ff5470aca2851a851950ed2926f450d7", size = 1792130, upload-time = "2026-05-18T17:05:12.983Z" },
+ { url = "https://files.pythonhosted.org/packages/06/3a/7c448bc623fcdfa96672531beb5a616ea5e64f6975955254d7731ffb0ad9/black-26.5.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5119fa92ae61f786e8c3662fd60aece1d0a2dd5cca5d0c79417a95e7a4272a59", size = 1846134, upload-time = "2026-05-18T17:05:14.506Z" },
+ { url = "https://files.pythonhosted.org/packages/a1/5b/0b39b3a5917f0657ac014ad2edb58c139553a478adfe7f817abf1622ff6e/black-26.5.1-cp311-cp311-win_amd64.whl", hash = "sha256:30d3c14661f2792e9142cce3eeeb1cbc175b3eb5f733be0c8eeb99651e52b0c3", size = 1478883, upload-time = "2026-05-18T17:05:16.542Z" },
+ { url = "https://files.pythonhosted.org/packages/4c/48/dc222692e0f95030db1bbfb6c857e76858bad09058221ea7aae815255327/black-26.5.1-cp311-cp311-win_arm64.whl", hash = "sha256:1ef92b76f7733f282fd096ea406200b5a286c42947412b0eaff3a74e3616cefe", size = 1277776, upload-time = "2026-05-18T17:05:18.029Z" },
+ { url = "https://files.pythonhosted.org/packages/24/99/7744b906703228264ef73bdd534df88ec1ef3de45c4e78f6d31b9e32d0c9/black-26.5.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:4ad6fa01f941920f54f2bbb35f3df7673428a0ef98a0b0840c2eaef3b110efa8", size = 2012518, upload-time = "2026-05-18T17:05:20.108Z" },
+ { url = "https://files.pythonhosted.org/packages/b7/c0/c5a3b1636dfd09c42534f2b3cf33506814f6d3e066fb0879ffa16c1ae860/black-26.5.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:3915f256e75a2d7cf88d8953d37f780455dc586cc72dee059c528fe77f581217", size = 1816016, upload-time = "2026-05-18T17:05:21.84Z" },
+ { url = "https://files.pythonhosted.org/packages/1f/0e/36044316b65ca471d3bb6d3703fd06fb50c6b727c3562f6a5a3153634f88/black-26.5.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d98d4137277c75dfb898ec8d846c4fd68ba1e9cf77f95e2865c203dc18f4c3d", size = 1884150, upload-time = "2026-05-18T17:05:23.546Z" },
+ { url = "https://files.pythonhosted.org/packages/b3/33/dafc5808c2af43672912111d7c3354af1615f7e2be3bed7a878461abbe4d/black-26.5.1-cp312-cp312-win_amd64.whl", hash = "sha256:a1dca32d9f1784af512a13410ec204c6f7f0aa9797a111c42e1c03449821c264", size = 1486825, upload-time = "2026-05-18T17:05:25.004Z" },
+ { url = "https://files.pythonhosted.org/packages/82/14/b965ee6ad2a311f28bdbf692def3ee9848d2ae289dab28b27657fcee3e78/black-26.5.1-cp312-cp312-win_arm64.whl", hash = "sha256:1037d5ac7b7b310b2632ad867ec8d0e4c4819dcdb0b820f63135da746a24e418", size = 1288646, upload-time = "2026-05-18T17:05:26.477Z" },
+ { url = "https://files.pythonhosted.org/packages/3f/5c/c384363980e11e25ca6b93205949bb331fbf35f4e0dbec376dfa6326cec8/black-26.5.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:2b36cf2ddf5566e205f6535f782a62194a184d33e175b64ae8c40b1737522be3", size = 2009020, upload-time = "2026-05-18T17:05:28.132Z" },
+ { url = "https://files.pythonhosted.org/packages/0b/df/9f31c5e0babbfed77d505fc5d120beb98b21b33feaeded3924ea941fe360/black-26.5.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:1f7ea64ebfa01b50f693508fc39f875e264446d3b097088f84f203b9d09618a0", size = 1813335, upload-time = "2026-05-18T17:05:31.266Z" },
+ { url = "https://files.pythonhosted.org/packages/fb/24/8e7b9a2fa61b0afd82209efe937557d180a1fa055bd7f6161eb9defc3719/black-26.5.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ecb3e624844c798144e9bd986954e0adc81d8911a1f30f375e1252fe26e8c294", size = 1881614, upload-time = "2026-05-18T17:05:32.718Z" },
+ { url = "https://files.pythonhosted.org/packages/49/ad/b4e0d9365ba8ac34f6bbab62a4b1b2dd5d618fac3fa1b8db968c844201b5/black-26.5.1-cp313-cp313-win_amd64.whl", hash = "sha256:e1a26503279b6b310669fb0b219c39e4820b77e8189fe80f522bb511f247db0a", size = 1488925, upload-time = "2026-05-18T17:05:34.259Z" },
+ { url = "https://files.pythonhosted.org/packages/a1/4b/652b859bf5df88a751c30451b09338f7fd26a77d1271c666992f836b7711/black-26.5.1-cp313-cp313-win_arm64.whl", hash = "sha256:5c34b25da232ead53a6f335b76dbea124f4d152ad568b9080d6f944bc2b34b52", size = 1289883, upload-time = "2026-05-18T17:05:36.019Z" },
+ { url = "https://files.pythonhosted.org/packages/94/51/f975cae76d44274cc2868dc9040ac5d58d464784610234455b4e7b19c6ef/black-26.5.1-py3-none-any.whl", hash = "sha256:4ed7f7da04046d2e488437170797d3b4a4ad83906683bcb7dfc68b673bbce5e2", size = 213693, upload-time = "2026-05-18T16:53:33.964Z" },
+]
+
[[package]]
name = "certifi"
version = "2026.2.25"
@@ -548,10 +589,12 @@ dependencies = [
{ name = "cua-fleet" },
{ name = "grpcio" },
{ name = "httpx" },
+ { name = "jsonschema" },
{ name = "oras" },
{ name = "paramiko" },
{ name = "protobuf" },
{ name = "pycdlib" },
+ { name = "pydantic" },
{ name = "vncdotool" },
{ name = "websockets" },
]
@@ -569,8 +612,10 @@ dev = [
[package.dev-dependencies]
dev = [
{ name = "cua-agent" },
+ { name = "datamodel-code-generator" },
{ name = "pytest" },
{ name = "pytest-asyncio" },
+ { name = "pyyaml" },
]
[package.metadata]
@@ -580,10 +625,12 @@ requires-dist = [
{ name = "cua-fleet", specifier = "==0.1.14" },
{ name = "grpcio", specifier = "==1.78.0" },
{ name = "httpx", specifier = ">=0.27.0" },
+ { name = "jsonschema", specifier = ">=4.23,<5.0" },
{ name = "oras", specifier = ">=0.2.40" },
{ name = "paramiko", specifier = ">=5.0.0" },
{ name = "protobuf", specifier = "==6.33.6" },
{ name = "pycdlib", specifier = ">=1.14.0" },
+ { name = "pydantic", specifier = ">=2.11,<3.0" },
{ name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0.0" },
{ name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.23.0" },
{ name = "ruff", marker = "extra == 'dev'", specifier = ">=0.1.0" },
@@ -596,8 +643,29 @@ provides-extras = ["auth", "dev"]
[package.metadata.requires-dev]
dev = [
{ name = "cua-agent", editable = "../agent" },
+ { name = "datamodel-code-generator", specifier = "==0.74.0" },
{ name = "pytest", specifier = ">=9.0.2" },
{ name = "pytest-asyncio", specifier = ">=1.3.0" },
+ { name = "pyyaml", specifier = ">=6.0,<7.0" },
+]
+
+[[package]]
+name = "datamodel-code-generator"
+version = "0.74.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "argcomplete" },
+ { name = "black", marker = "sys_platform != 'emscripten'" },
+ { name = "genson" },
+ { name = "inflect" },
+ { name = "isort", marker = "sys_platform != 'emscripten'" },
+ { name = "jinja2" },
+ { name = "pydantic" },
+ { name = "pyyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/57/e8/8a46c8de96ec5c3b891172bf5db4bcf4797e75c31aa03d540d528e61ccd8/datamodel_code_generator-0.74.0.tar.gz", hash = "sha256:db0998d920e774f48442ca2702b901049be60c35ccb547086c574b1d261f1444", size = 2055535, upload-time = "2026-08-17T17:06:40.393Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/d3/81/5b79e507f1fab62ac953d3343708a345d8e74cbe862ca2f61ccc90c2c600/datamodel_code_generator-0.74.0-py3-none-any.whl", hash = "sha256:5e7d0b41d25077ac54f23775904573fc8b608bdabc7fc762885204322f596190", size = 592333, upload-time = "2026-08-17T17:06:38.185Z" },
]
[[package]]
@@ -759,6 +827,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/e6/ab/fb21f4c939bb440104cc2b396d3be1d9b7a9fd3c6c2a53d98c45b3d7c954/fsspec-2026.2.0-py3-none-any.whl", hash = "sha256:98de475b5cb3bd66bedd5c4679e87b4fdfe1a3bf4d707b151b3c07e58c9a2437", size = 202505, upload-time = "2026-02-05T21:50:51.819Z" },
]
+[[package]]
+name = "genson"
+version = "1.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f8/53/de162dc8e03fccd9ebe59d17c7812378fe8bd2b604f6b1b94d00165140ac/genson-1.4.0.tar.gz", hash = "sha256:bc7f1c1bae87a21ca44d81149aec95a3f4468d676de9b8b08caa064f3c50b3da", size = 47908, upload-time = "2026-07-06T08:21:50.331Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/16/02/767f744ab6d4cb7761e5008acc3d534b7a0481af62563d52e391fbcb2140/genson-1.4.0-py3-none-any.whl", hash = "sha256:03bc71bbe52defde70660cc4dcd1ea1097997da5a1cbb90a9dbd3acc7c9e1b65", size = 24484, upload-time = "2026-07-06T08:21:49.046Z" },
+]
+
[[package]]
name = "grpcio"
version = "1.78.0"
@@ -926,6 +1003,19 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/1d/55/0f4df2a44053867ea9cbea73fc588b03c55605cd695cee0a3d86f0029cb2/incremental-24.11.0-py3-none-any.whl", hash = "sha256:a34450716b1c4341fe6676a0598e88a39e04189f4dce5dc96f656e040baa10b3", size = 21109, upload-time = "2025-11-28T02:30:16.442Z" },
]
+[[package]]
+name = "inflect"
+version = "7.5.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "more-itertools" },
+ { name = "typeguard" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/78/c6/943357d44a21fd995723d07ccaddd78023eace03c1846049a2645d4324a3/inflect-7.5.0.tar.gz", hash = "sha256:faf19801c3742ed5a05a8ce388e0d8fe1a07f8d095c82201eb904f5d27ad571f", size = 73751, upload-time = "2024-12-28T17:11:18.897Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8a/eb/427ed2b20a38a4ee29f24dbe4ae2dafab198674fe9a85e3d6adf9e5f5f41/inflect-7.5.0-py3-none-any.whl", hash = "sha256:2aea70e5e70c35d8350b8097396ec155ffd68def678c7ff97f51aa69c1d92344", size = 35197, upload-time = "2024-12-28T17:11:15.931Z" },
+]
+
[[package]]
name = "iniconfig"
version = "2.3.0"
@@ -944,6 +1034,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/32/4b/b99e37f88336009971405cbb7630610322ed6fbfa31e1d7ab3fbf3049a2d/invoke-2.2.1-py3-none-any.whl", hash = "sha256:2413bc441b376e5cd3f55bb5d364f973ad8bdd7bf87e53c79de3c11bf3feecc8", size = 160287, upload-time = "2025-10-11T00:36:33.703Z" },
]
+[[package]]
+name = "isort"
+version = "8.0.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ef/7c/ec4ab396d31b3b395e2e999c8f46dec78c5e29209fac49d1f4dace04041d/isort-8.0.1.tar.gz", hash = "sha256:171ac4ff559cdc060bcfff550bc8404a486fee0caab245679c2abe7cb253c78d", size = 769592, upload-time = "2026-02-28T10:08:20.685Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3e/95/c7c34aa53c16353c56d0b802fba48d5f5caa2cdee7958acbcb795c830416/isort-8.0.1-py3-none-any.whl", hash = "sha256:28b89bc70f751b559aeca209e6120393d43fbe2490de0559662be7a9787e3d75", size = 89733, upload-time = "2026-02-28T10:08:19.466Z" },
+]
+
[[package]]
name = "jinja2"
version = "3.1.6"
@@ -1139,6 +1238,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
]
+[[package]]
+name = "more-itertools"
+version = "11.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/de/1d/f4da6f02cdffe04d6362210b807146a26044c88d839208aec273bb0d9184/more_itertools-11.1.0.tar.gz", hash = "sha256:48e8f4d9e7e5878571ecf6f2b4e57634f93cd474cc8cfbd2376f2d11b396e30d", size = 145772, upload-time = "2026-05-22T14:14:29.909Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/e8/3d/1087453384dbde46a8c7f9356eead2c58be8a7bf156bca40243377c85715/more_itertools-11.1.0-py3-none-any.whl", hash = "sha256:4b65538ae22f6fed0ce4874efd317463a7489796a0939fa66824dd542125a192", size = 72226, upload-time = "2026-05-22T14:14:28.824Z" },
+]
+
[[package]]
name = "multidict"
version = "6.7.1"
@@ -1220,6 +1328,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/81/08/7036c080d7117f28a4af526d794aab6a84463126db031b007717c1a6676e/multidict-6.7.1-py3-none-any.whl", hash = "sha256:55d97cc6dae627efa6a6e548885712d4864b81110ac76fa4e534c03819fa4a56", size = 12319, upload-time = "2026-01-26T02:46:44.004Z" },
]
+[[package]]
+name = "mypy-extensions"
+version = "1.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a2/6e/371856a3fb9d31ca8dac321cda606860fa4548858c0cc45d9d1d4ca2628b/mypy_extensions-1.1.0.tar.gz", hash = "sha256:52e68efc3284861e772bbcd66823fde5ae21fd2fdb51c62a211403730b916558", size = 6343, upload-time = "2025-04-22T14:54:24.164Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963, upload-time = "2025-04-22T14:54:22.983Z" },
+]
+
[[package]]
name = "openai"
version = "2.30.0"
@@ -1276,6 +1393,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/82/5b/eadf6d45de38d30ab603f49393b6cd2cbe7e233af8cf90197e32782b68a9/paramiko-5.0.0-py3-none-any.whl", hash = "sha256:b7044611c30140d9a75261653210e2002977b71a0497ff3ba0d98d7edbf62f7c", size = 208919, upload-time = "2026-05-09T18:28:50.295Z" },
]
+[[package]]
+name = "pathspec"
+version = "1.1.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5a/82/42f767fc1c1143d6fd36efb827202a2d997a375e160a71eb2888a925aac1/pathspec-1.1.1.tar.gz", hash = "sha256:17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a", size = 135180, upload-time = "2026-04-27T01:46:08.907Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f1/d9/7fb5aa316bc299258e68c73ba3bddbc499654a07f151cba08f6153988714/pathspec-1.1.1-py3-none-any.whl", hash = "sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189", size = 57328, upload-time = "2026-04-27T01:46:07.06Z" },
+]
+
[[package]]
name = "pillow"
version = "12.2.0"
@@ -1338,6 +1464,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/bc/60/5382c03e1970de634027cee8e1b7d39776b778b81812aaf45b694dfe9e28/pillow-12.2.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:bfa9c230d2fe991bed5318a5f119bd6780cda2915cca595393649fc118ab895e", size = 7080946, upload-time = "2026-04-01T14:46:11.734Z" },
]
+[[package]]
+name = "platformdirs"
+version = "4.11.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b8/d7/e7bfbc86e9f99ff7807e24de7703f032e9c9ba80bb355cf26e0e9bc5a75e/platformdirs-4.11.3.tar.gz", hash = "sha256:66a73d38a849810252df809a3d8bcbda8e26f6c189920e7535ad608a48dbb5ab", size = 33050, upload-time = "2026-08-13T22:43:27.52Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/19/a9/c34aebedd3a4c9afe5101b1b8713710b3fec18087c8a36c35d2f909861bd/platformdirs-4.11.3-py3-none-any.whl", hash = "sha256:5ed065d443751de711da036041a7a214122efc4a4de393b3f4137ba5576540e7", size = 23491, upload-time = "2026-08-13T22:43:26.121Z" },
+]
+
[[package]]
name = "pluggy"
version = "1.6.0"
@@ -4311,6 +4446,30 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/fc/b8/ff33610932e0ee81ae7f1269c890f697d56ff74b9f5b2ee5d9b7fa2c5355/python_xlib-0.33-py2.py3-none-any.whl", hash = "sha256:c3534038d42e0df2f1392a1b30a15a4ff5fdc2b86cfa94f072bf11b10a164398", size = 182185, upload-time = "2022-12-25T18:52:58.662Z" },
]
+[[package]]
+name = "pytokens"
+version = "0.4.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b6/34/b4e015b99031667a7b960f888889c5bd34ef585c85e1cb56a594b92836ac/pytokens-0.4.1.tar.gz", hash = "sha256:292052fe80923aae2260c073f822ceba21f3872ced9a68bb7953b348e561179a", size = 23015, upload-time = "2026-01-30T01:03:45.924Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/3d/92/790ebe03f07b57e53b10884c329b9a1a308648fc083a6d4a39a10a28c8fc/pytokens-0.4.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:d70e77c55ae8380c91c0c18dea05951482e263982911fc7410b1ffd1dadd3440", size = 160864, upload-time = "2026-01-30T01:02:57.882Z" },
+ { url = "https://files.pythonhosted.org/packages/13/25/a4f555281d975bfdd1eba731450e2fe3a95870274da73fb12c40aeae7625/pytokens-0.4.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4a58d057208cb9075c144950d789511220b07636dd2e4708d5645d24de666bdc", size = 248565, upload-time = "2026-01-30T01:02:59.912Z" },
+ { url = "https://files.pythonhosted.org/packages/17/50/bc0394b4ad5b1601be22fa43652173d47e4c9efbf0044c62e9a59b747c56/pytokens-0.4.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b49750419d300e2b5a3813cf229d4e5a4c728dae470bcc89867a9ad6f25a722d", size = 260824, upload-time = "2026-01-30T01:03:01.471Z" },
+ { url = "https://files.pythonhosted.org/packages/4e/54/3e04f9d92a4be4fc6c80016bc396b923d2a6933ae94b5f557c939c460ee0/pytokens-0.4.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:d9907d61f15bf7261d7e775bd5d7ee4d2930e04424bab1972591918497623a16", size = 264075, upload-time = "2026-01-30T01:03:04.143Z" },
+ { url = "https://files.pythonhosted.org/packages/d1/1b/44b0326cb5470a4375f37988aea5d61b5cc52407143303015ebee94abfd6/pytokens-0.4.1-cp311-cp311-win_amd64.whl", hash = "sha256:ee44d0f85b803321710f9239f335aafe16553b39106384cef8e6de40cb4ef2f6", size = 103323, upload-time = "2026-01-30T01:03:05.412Z" },
+ { url = "https://files.pythonhosted.org/packages/41/5d/e44573011401fb82e9d51e97f1290ceb377800fb4eed650b96f4753b499c/pytokens-0.4.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:140709331e846b728475786df8aeb27d24f48cbcf7bcd449f8de75cae7a45083", size = 160663, upload-time = "2026-01-30T01:03:06.473Z" },
+ { url = "https://files.pythonhosted.org/packages/f0/e6/5bbc3019f8e6f21d09c41f8b8654536117e5e211a85d89212d59cbdab381/pytokens-0.4.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6d6c4268598f762bc8e91f5dbf2ab2f61f7b95bdc07953b602db879b3c8c18e1", size = 255626, upload-time = "2026-01-30T01:03:08.177Z" },
+ { url = "https://files.pythonhosted.org/packages/bf/3c/2d5297d82286f6f3d92770289fd439956b201c0a4fc7e72efb9b2293758e/pytokens-0.4.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:24afde1f53d95348b5a0eb19488661147285ca4dd7ed752bbc3e1c6242a304d1", size = 269779, upload-time = "2026-01-30T01:03:09.756Z" },
+ { url = "https://files.pythonhosted.org/packages/20/01/7436e9ad693cebda0551203e0bf28f7669976c60ad07d6402098208476de/pytokens-0.4.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:5ad948d085ed6c16413eb5fec6b3e02fa00dc29a2534f088d3302c47eb59adf9", size = 268076, upload-time = "2026-01-30T01:03:10.957Z" },
+ { url = "https://files.pythonhosted.org/packages/2e/df/533c82a3c752ba13ae7ef238b7f8cdd272cf1475f03c63ac6cf3fcfb00b6/pytokens-0.4.1-cp312-cp312-win_amd64.whl", hash = "sha256:3f901fe783e06e48e8cbdc82d631fca8f118333798193e026a50ce1b3757ea68", size = 103552, upload-time = "2026-01-30T01:03:12.066Z" },
+ { url = "https://files.pythonhosted.org/packages/cb/dc/08b1a080372afda3cceb4f3c0a7ba2bde9d6a5241f1edb02a22a019ee147/pytokens-0.4.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8bdb9d0ce90cbf99c525e75a2fa415144fd570a1ba987380190e8b786bc6ef9b", size = 160720, upload-time = "2026-01-30T01:03:13.843Z" },
+ { url = "https://files.pythonhosted.org/packages/64/0c/41ea22205da480837a700e395507e6a24425151dfb7ead73343d6e2d7ffe/pytokens-0.4.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5502408cab1cb18e128570f8d598981c68a50d0cbd7c61312a90507cd3a1276f", size = 254204, upload-time = "2026-01-30T01:03:14.886Z" },
+ { url = "https://files.pythonhosted.org/packages/e0/d2/afe5c7f8607018beb99971489dbb846508f1b8f351fcefc225fcf4b2adc0/pytokens-0.4.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:29d1d8fb1030af4d231789959f21821ab6325e463f0503a61d204343c9b355d1", size = 268423, upload-time = "2026-01-30T01:03:15.936Z" },
+ { url = "https://files.pythonhosted.org/packages/68/d4/00ffdbd370410c04e9591da9220a68dc1693ef7499173eb3e30d06e05ed1/pytokens-0.4.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:970b08dd6b86058b6dc07efe9e98414f5102974716232d10f32ff39701e841c4", size = 266859, upload-time = "2026-01-30T01:03:17.458Z" },
+ { url = "https://files.pythonhosted.org/packages/a7/c9/c3161313b4ca0c601eeefabd3d3b576edaa9afdefd32da97210700e47652/pytokens-0.4.1-cp313-cp313-win_amd64.whl", hash = "sha256:9bd7d7f544d362576be74f9d5901a22f317efc20046efe2034dced238cbbfe78", size = 103520, upload-time = "2026-01-30T01:03:18.652Z" },
+ { url = "https://files.pythonhosted.org/packages/c6/78/397db326746f0a342855b81216ae1f0a32965deccfd7c830a2dbc66d2483/pytokens-0.4.1-py3-none-any.whl", hash = "sha256:26cef14744a8385f35d0e095dc8b3a7583f6c953c2e3d269c7f82484bf5ad2de", size = 13729, upload-time = "2026-01-30T01:03:45.029Z" },
+]
+
[[package]]
name = "pywin32"
version = "311"
@@ -4737,6 +4896,18 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/a6/57/bcf4e2370dd218c9aa68a9140a65d86729c73f1d529f7e94786c2766fc72/twisted-26.4.0-py3-none-any.whl", hash = "sha256:dc25ea0ebf6511c24f03232ee9f4afa54b291c5d897990e3a39cc4d14a1ef4c0", size = 3230362, upload-time = "2026-05-11T11:24:49.5Z" },
]
+[[package]]
+name = "typeguard"
+version = "4.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b4/de/4420db493fa8fc0856d5e5c1b159c63a323d2de2317babe36b01568928e8/typeguard-4.6.0.tar.gz", hash = "sha256:e7414f09111317de3e335de92cd397c5c0ca00b1cc1676de12e1d444a79b3f21", size = 82330, upload-time = "2026-07-26T08:40:23.207Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8f/eb/461d5f167b6f5c7d97696f397c82f82e3480e003fce3f0a1cd1dd26e2eb2/typeguard-4.6.0-py3-none-any.whl", hash = "sha256:79878165bb86f2cf5d41d159a0ff1792a796cf496882d2fe1b1c6c7049b9cdd7", size = 36884, upload-time = "2026-07-26T08:40:21.868Z" },
+]
+
[[package]]
name = "typer"
version = "0.24.1"