apps/api-client-go/api/openapi.yaml (4)

9938-10002: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

id is still documented as a UUID in both public box schemas.

The PR objective says the UUID/legacy-boxId split is gone and id is now the single 12-character base62 identifier. These descriptions and examples still say "internal UUID", so the generated docs and example payloads will contradict the new contract.

🛠️ Proposed OpenAPI fix

-        id: fd955d93-e74a-48e7-9f2d-fcbe6dd9e920
+        id: A1b2C3d4E5f6
@@
         id:
-          description: The internal UUID of the box
-          example: fd955d93-e74a-48e7-9f2d-fcbe6dd9e920
+          description: The public box identifier
+          example: A1b2C3d4E5f6
           type: string

Update the inherited `PaginatedBoxes` item examples too so the example set stays internally consistent.

Also applies to: 12487-12552

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api-client-go/api/openapi.yaml` around lines 9938 - 10002, The OpenAPI
docs still describe the Box "id" as an internal UUID and use a UUID example;
update the Box schemas and any public-box schema examples (the schema that
defines properties.id and the example block under "example: id") to describe
"id" as the 12-character base62 identifier and replace the UUID example with a
representative 12-char base62 value (e.g., a-zA-Z0-9 string of length 12); also
update the PaginatedBoxes example set so its box examples use the same 12-char
base62 id and adjusted description text for properties.id to match the new
contract.

---

13450-13472: ⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Don't overload organizationId with the box public ID.

The stack context says AdminBoxItem.organizationId is only becoming optional in the generated contract. Re-describing and re-exampleing that field as "Public box ID shown to users" changes its meaning for every generated client and leaks the same mismatch into the observability investigate response.

If admin views need a separate user-facing box identifier, add that as its own optional field and keep organizationId reserved for the organization foreign key. The AdminObservabilityInvestigateResponse.boxes[] examples should then be updated to match the corrected AdminBoxItem shape.

Also applies to: 14788-14804

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api-client-go/api/openapi.yaml` around lines 13450 - 13472, The OpenAPI
spec incorrectly repurposes AdminBoxItem.organizationId as a user-facing public
box ID; revert organizationId to its original organization foreign-key meaning
(restore description and example to an organization ID) and add a new optional
property (e.g., publicBoxId or publicId) on AdminBoxItem with the description
"Public box ID shown to users" and an example like "box_abc123"; then update the
example objects used by AdminObservabilityInvestigateResponse.boxes[] to
populate the new publicBoxId/publicId instead of overloading organizationId so
generated clients and observability responses reflect the correct shapes.

---

10216-10321: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add image to CreateBox before regenerating clients.

POST /box still points at CreateBox, but this request schema has no image field even though this PR makes image selection part of box creation. Any SDK regenerated from this spec will be unable to send the selected image and will stay on the legacy create contract.

🛠️ Proposed OpenAPI fix

     CreateBox:
       example:
         name: MyBox
+        image: ghcr.io/boxlite-ai/boxlite-agent-python@sha256:80d562a57f4bc12def4e54dbdb9e7d26d3268fe0767a2955ab5ad718041145d6
         user: boxlite
         env:
           NODE_ENV: production
@@
       properties:
         name:
           description: "The name of the box. If not provided, the box ID will be used as the name"
           example: MyBox
           type: string
+        image:
+          description: OCI image ref to boot the box from. When omitted, the server selects the default curated image.
+          example: ghcr.io/boxlite-ai/boxlite-agent-python@sha256:80d562a57f4bc12def4e54dbdb9e7d26d3268fe0767a2955ab5ad718041145d6
+          type: string
         user:
           description: The user associated with the project
           example: boxlite
           type: string

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api-client-go/api/openapi.yaml` around lines 10216 - 10321, The
CreateBox schema is missing the image field so generated SDKs can't send the
selected image; update the CreateBox object (schema name "CreateBox") to include
an "image" property (string, with an example like "ubuntu:22.04" or whatever
project expects) and appropriate description, and ensure it's added alongside
other properties (e.g., near cpu/gpu/memory) and included in the example block
at the top of CreateBox so clients and regenerated SDKs will include it.

---

1678-1686: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Remove the legacy UUID/boxId query contract from listBoxesPaginated.

This endpoint still documents filtering by internal UUID and still exposes sort=boxId, but the PR collapses box identity to a single id. Leaving those values in the spec will regenerate stale SDK enums and advertise unsupported query behavior.

🛠️ Proposed OpenAPI fix

-      - description: "Filter by partial Box ID, internal UUID, or name match"
+      - description: Filter by partial box ID or name match
         explode: true
         in: query
         name: id
@@
         schema:
           default: createdAt
           enum:
           - id
-          - boxId
           - name
           - state
           - region
           - updatedAt

Also applies to: 1827-1836

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api-client-go/api/openapi.yaml` around lines 1678 - 1686, The OpenAPI
docs still advertise filtering by internal UUID/`boxId` and exposing sort=boxId
for the listBoxesPaginated operation; update the parameter and enums to reflect
the collapsed identity model: change the query parameter "id" description to
remove any mention of "internal UUID" or "boxId" (e.g., "Filter by partial id or
name match"), ensure the example/type remain string, and remove the "boxId"
value from any sort enum/options so SDKs won't regenerate the legacy enum;
target the listBoxesPaginated operation and the "id" parameter and the related
sort enum entries to make these removals.

apps/runner/pkg/boxlite/stubs.go (1)

95-108: ⚠️ Potential issue | 🔴 Critical

Remove hardcoded alpine:latest from RecoverBox (bypasses curated image allowlist)

• apps/runner/pkg/boxlite/stubs.go RecoverBox always recreates using dto.CreateBoxDTO{ Image: "alpine:latest" }.
• apps/runner/pkg/boxlite/client.go Create() passes boxDto.Image directly to c.runtime.Create(...), so recovery will attempt to pull alpine:latest.
• The API allowlist/assertSupportedImage gate in apps/api/src/box/constants/curated-images.constant.ts is applied only at request-boundary create/warm-pool; RecoverBoxDTO does not include image, so recovery bypasses the allowlist.
• Fix RecoverBox to use the box’s original/metadata image (or include a vetted/pinned image in RecoverBoxDTO) instead of a hardcoded fallback.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/runner/pkg/boxlite/stubs.go` around lines 95 - 108, RecoverBox currently
hardcodes the image to "alpine:latest" when constructing dto.CreateBoxDTO (see
dto.CreateBoxDTO in RecoverBox), which bypasses the curated image allowlist
applied elsewhere; change RecoverBox to populate CreateBoxDTO.Image from the
box's original metadata image (e.g., the stored box record or Inspect/metadata
lookup) or, if Recovery DTO should carry it, extend RecoverBoxDTO to include
Image and use that vetted value instead of the hardcoded literal; ensure this
value flows unchanged to client.Create and ultimately c.runtime.Create so the
assertSupportedImage/curated-images gate is not bypassed.

scripts/test/e2e/cases/test_go_entry.py (1)

23-25: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Shared root cause: e2e tests still parse legacy UUID box IDs after migration to 12-char base62 IDs. This will cause brittle or failing ID extraction in SDK entry tests despite successful create flows.

• scripts/test/e2e/cases/test_go_entry.py#L23-L25: replace UUID regex with BOX_ID=([0-9A-Za-z]{12}) capture and use capture group 1 as box_id.
• scripts/test/e2e/cases/test_node_entry.py#L28-L30: replace UUID regex with BOX_ID=([0-9A-Za-z]{12}) capture and use capture group 1 as box_id.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/test/e2e/cases/test_go_entry.py` around lines 23 - 25, Replace the
legacy UUID regex and extraction with a 12-char base62 box ID capture: in
scripts/test/e2e/cases/test_go_entry.py (lines 23-25) replace the UUID_RE
definition with BOX_ID = re.compile(r"BOX_ID=([0-9A-Za-z]{12})") and update any
extraction sites that used UUID_RE to read group(1) into box_id; in
scripts/test/e2e/cases/test_node_entry.py (lines 28-30) do the same replacement
(define BOX_ID = re.compile(r"BOX_ID=([0-9A-Za-z]{12})")) and change code that
previously used UUID_RE to extract box_id = match.group(1). Ensure all
references to the old UUID_RE are updated to use BOX_ID and group(1) for the
box_id value.