feat(sandboxes): expose custom deployments and build logs (#388)

* feat(sandboxes): expose custom source deployments and build logs

Keep the existing Project.plan response compatibility values FREE and PRO in the consumer snapshot while syncing the new producer operations. Preserve existing rollout tests.

* fix(sandboxes): remove multipart schema memory default

* fix(sandboxes): accept canonical regions in deployment logs

* test(sandboxes): cover deployment boundaries and align service credentials

* fix(sandboxes): expose deployment history page limits

* fix(openapi): match sandbox deployment credentials to runtime

* fix(sandboxes): preserve typed errors and validate deployment ports

* fix: reject non-integer sandbox deployment ports

Author: shawnwu-kong

docs/sandboxes.md

@@ -114,3 +114,42 @@ that management scope for reads, commands, files, and HTTP access, even if the
 client signs in or switches users. Handles returned by `get()` use the current
 signed-in user's grant when available. Public preset discovery requires no
 service key or signed-in session.
+
+## Custom image deployments
+
+Upload a tar.gz source archive containing a root Dockerfile fragment. Volcano
+supplies the base image; use `RUN`, `COPY`, and `CMD` without `FROM`, `USER`, or
+`ENTRYPOINT`.
+
+```python
+from pathlib import Path
+from uuid import uuid4
+
+sandbox_id = str(uuid4())
+request_id = str(uuid4())
+deployment = client.sandboxes.deploy(
+    project_id,
+    sandbox_id,
+    Path("source.tar.gz").read_bytes(),
+    name="custom-image",
+    memory_mb=1024,
+    ports=[8080],
+    request_id=request_id,
+)
+state = client.sandboxes.deployment(project_id, sandbox_id, deployment.id)
+```
+
+Retain both IDs, the source bytes, and build options when retrying a request.
+Wait for status `active` before creating sessions with this `sandbox_id`.
+Redeploy with the same template ID and a new request ID to update the image;
+existing sessions retain their original image.
+
+`deployments(project_id, sandbox_id, cursor=..., limit=10)` returns history and a
+`next_cursor`. `source(project_id, sandbox_id, deployment_id)` returns the
+original archive bytes. `logs(project_id, sandbox_id, deployment_id,
+region="aws-us-east-1", cursor=..., limit=100)` returns regional build messages.
+`delete_template(project_id, sandbox_id)` deletes the template and terminates
+its sessions and requires the `sandboxes.terminate` permission. History page
+limits range from 1 to 100. Archives are limited to 32 MiB compressed and expanded.
+
+Custom deployments accept at most 16 unique ports, from 1 through 65532.

maintainers/typed-boundaries.md

@@ -35,3 +35,8 @@ CI retains the Python 3.11–3.14 check names and selects exact patch versions
 listed by the native [setup-python manifest](https://github.com/actions/python-versions/blob/main/versions-manifest.json).
 `UV_PYTHON` selects each matrix interpreter; `.python-version` pins the local
 3.12 environment. The isolated coverage command pins the same 3.12 patch.
+
+The `ProjectPlan` literal-enum template retains the legacy response values
+`FREE` and `PRO` for earlier Hosting releases. This compatibility applies only
+to the response-only `Project.plan` model; the vendored producer contract and
+all other enum constraints stay unchanged.

openapi-python-client.yaml

@@ -8,6 +8,7 @@ post_hooks:
   - ruff check --isolated --no-cache --preview --select W291,W293,W391 --fix --unsafe-fixes api/sandboxes models/*sandbox*.py
 # Parse binary bodies without changing their wire Content-Type.
 content_type_overrides:
+  application/gzip: application/octet-stream
   application/yaml: application/octet-stream
   image/png: application/octet-stream
   image/jpeg: application/octet-stream