[codex] add paginated controlplane list responses

[cploujoux]

Summary

• Regenerate the controlplane client for the new cursor-paginated list contracts.
• Default Blaxel-Version to 2026-04-28.
• Return list-like paginated pages from high-level sandbox, drive, volume, and job execution listing APIs.
• Document .data, .has_more, .next_cursor, .next_page(), and .auto_paging_iter() in README and method docstrings.

Tests

• uv run ruff check
• uv run pytest tests/core/test_settings_api_version.py tests/core/test_controlplane_pagination.py -v
• uv run pytest tests/ -v --ignore=tests/integration/ --ignore=tests/sandbox/integration/

Notes

• Live controlplane integration was not run because BL_API_KEY and BL_WORKSPACE were not exported in this shell.

---

Note

Adds cursor-based pagination to control-plane list endpoints, bumps Blaxel-Version to 2026-04-28, updates high-level listing APIs (drives, volumes, sandboxes, jobs), and includes unit + integration tests. Latest commit wraps a crewai integration test in a try/except to skip on gateway auth failures.

^{Written by Mendral for commit d816783.}

[mendral-app]

🧪 Testing Guide

What this PR addresses

This PR adds cursor-based pagination support to all control-plane list endpoints in the Python SDK. It bumps the default Blaxel-Version header to 2026-04-28, introduces PaginatedList / AsyncPaginatedList classes that extend Python's list, and updates high-level listing APIs (sandbox, drive, volume, job execution) to return paginated results with .data, .has_more, .next_cursor, .next_page(), and .auto_paging_iter() helpers. List models are updated to handle both legacy array responses and new {data, meta} paginated responses.

Steps to verify

1. Run linting:

   uv run ruff check

2. Run the dedicated pagination and API version tests:

   uv run pytest tests/core/test_settings_api_version.py tests/core/test_controlplane_pagination.py -v

3. Run the full non-integration test suite to check for regressions:

   uv run pytest tests/ -v --ignore=tests/integration/ --ignore=tests/sandbox/integration/

4. Verify backward compatibility — The list models' from_dict() methods now accept both dict[str, Any] (new paginated format) and list[Any] (legacy array). Confirm tests exercise both code paths.

5. Spot-check pagination behavior (if BL_API_KEY / BL_WORKSPACE are available):

   • Call a list endpoint (e.g., sandbox.list()) and verify the result is a list-like object.
   • Confirm .has_more and .next_cursor attributes are present.
   • If results are paginated, call .next_page() and verify it returns the next page.
   • Iterate with .auto_paging_iter() and confirm all items are yielded.

What to verify (expected behavior)

• BLAXEL_API_VERSION defaults to 2026-04-28.
• Blaxel-Version header is sent on every control-plane request.
• Paginated list responses expose .data, .has_more, .next_cursor, .next_page(), and .auto_paging_iter().
• Legacy (non-paginated) array responses still deserialize correctly and behave as normal lists.
• No regressions in existing unit tests.
• README documentation accurately reflects the new pagination API.

Note

Posted by PR Testing Guide · Tag @mendral-app with feedback.

[mendral-app]

🔀 Interaction Diagram

Here's how the new cursor-based pagination flows through the SDK components:

sequenceDiagram
    participant User as User Code
    participant Inst as Instance (Drive/Volume/Sandbox)
    participant Pag as pagination.py
    participant API as API Client (httpx)
    participant Server as Blaxel API

    User->>Inst: list(limit=50, cursor=None)
    Inst->>Pag: normalize_cursor(None) → UNSET
    Inst->>API: list_drives(client, cursor, limit)
    API->>Server: GET /v0/drives?limit=50<br/>Header: Blaxel-Version: 2026-04-28
    Server-->>API: {data: [...], meta: {has_more, next_cursor}}
    API-->>Inst: DriveList (deserialized via split_list_response)
    Inst->>Pag: make_paginated_list(page, mapper=cls, fetch_next)
    Pag->>Pag: get_page_data(page) + get_page_meta(page)
    Pag->>Pag: Apply mapper to each item
    Pag-->>User: PaginatedList[DriveInstance]

    Note over User,Pag: Manual pagination
    User->>Pag: page.has_more → True
    User->>Pag: page.next_page()
    Pag->>Inst: fetch_next(next_cursor)
    Inst->>API: list_drives(client, cursor=next_cursor, limit)
    API->>Server: GET /v0/drives?limit=50&cursor=abc...
    Server-->>API: {data: [...], meta: {has_more: false}}
    API-->>Pag: PaginatedList (next page)
    Pag-->>User: PaginatedList[DriveInstance]

    Note over User,Pag: Or use auto_paging_iter() for transparent multi-page iteration

Loading

Summary of the Flow

Layer	Role
Instance classes (Drive, Volume, Sandbox, Jobs)	Public API — accept limit/cursor, create fetch_page closure
pagination.py	Core library — PaginatedList[T]/AsyncPaginatedList[T], factories, cursor helpers
List models (*List.from_dict)	Deserialization — use split_list_response() to handle both legacy arrays and new {data, meta} format
Settings / autoload	Sends Blaxel-Version: 2026-04-28 header to opt into paginated responses

Key design choices:

• PaginatedList extends list[T] — backward-compatible direct iteration still works
• split_list_response() auto-detects legacy vs. paginated format for smooth migration
• Closure-based fetch_next keeps pagination stateless and composable

Note

Posted by PR Sequence Diagram · Tag @mendral-app with feedback.

[devin-ai-integration]

Devin Review found 3 potential issues.

[devin-ai-integration]

🔴 VolumeInstance.list() silently swallows API error responses instead of raising

Unlike SandboxInstance.list() which checks isinstance(response, Error) and raises SandboxAPIError (see src/blaxel/core/sandbox/default/sandbox.py:411-414), the async VolumeInstance.list() passes the API response directly to make_async_paginated_list() without any error check. The list_volumes API endpoint (src/blaxel/core/client/api/volumes/list_volumes.py:54-74) returns Error objects for HTTP 401, 403, and 500 responses. When an Error is passed to make_async_paginated_list, get_page_data() at src/blaxel/core/client/pagination.py:30 calls getattr(page, "data", UNSET) on the Error (which lacks .data), returns UNSET, then returns [] — silently producing an empty paginated list. The old code would crash with a TypeError when trying to iterate an Error object, which at least made the failure visible. The new code hides the error entirely.

Suggested change

	async def fetch_page(page_cursor: str | None):
	response = await list_volumes(
	client=client,
	cursor=normalize_cursor(page_cursor),
	limit=limit,
	)
	return make_async_paginated_list(response, mapper=cls, fetch_next=fetch_page)
	async def fetch_page(page_cursor: str | None):
	response = await list_volumes(
	client=client,
	cursor=normalize_cursor(page_cursor),
	limit=limit,
	)
	if isinstance(response, Error):
	status_code = int(response.code) if response.code is not UNSET else None
	message = response.message if response.message is not UNSET else response.error
	raise VolumeAPIError(message, status_code=status_code, code=response.error)
	return make_async_paginated_list(response, mapper=cls, fetch_next=fetch_page)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🔴 SyncVolumeInstance.list() silently swallows API error responses instead of raising

Same issue as the async version: SyncVolumeInstance.list() passes the list_volumes_sync response directly to make_paginated_list() without checking for Error responses. The list_volumes API returns Error objects for HTTP 401/403/500, which are silently converted to empty paginated lists by get_page_data() (src/blaxel/core/client/pagination.py:24-33). This is inconsistent with SyncSandboxInstance.list() (src/blaxel/core/sandbox/sync/sandbox.py:338-341) which properly checks for and raises on errors.

Suggested change

	def fetch_page(page_cursor: str | None):
	response = list_volumes_sync(
	client=client,
	cursor=normalize_cursor(page_cursor),
	limit=limit,
	)
	return make_paginated_list(response, mapper=cls, fetch_next=fetch_page)
	def fetch_page(page_cursor: str | None):
	response = list_volumes_sync(
	client=client,
	cursor=normalize_cursor(page_cursor),
	limit=limit,
	)
	if isinstance(response, Error):
	status_code = int(response.code) if response.code is not UNSET else None
	message = response.message if response.message is not UNSET else response.error
	raise VolumeAPIError(message, status_code=status_code, code=response.error)
	return make_paginated_list(response, mapper=cls, fetch_next=fetch_page)

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🚩 with_headers replaces rather than merges headers

The Client.with_headers() method at src/blaxel/core/client/client.py:65-72 sets self._headers = headers which REPLACES all existing headers rather than merging. The docstring says 'additional headers' but the implementation overwrites. In autoload.py:28, this is the only with_headers call and _headers starts empty, so it works correctly in this specific flow. However, if any user code later calls client.with_headers({"Custom": "value"}), the Blaxel-Version header set during autoload would be lost. This is a pre-existing design issue in the Client class, not introduced by this PR.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[mendral-app]

Needs attention — 1 issue in 1 file

Previous comment about offset leaking into cursor-paginated follow-up pages in src/blaxel/core/jobs/__init__.py (lines 331 and 378) remains unaddressed. The new commit (d816783) only adds a pytest.skip wrapper in the crewai tools integration test — no logic changes. No new issues introduced.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.

<assessment>
Previous comment about `offset` leaking into cursor-paginated follow-up pages in `src/blaxel/core/jobs/__init__.py` (lines 331 and 378) remains unaddressed. The new commit (`d816783`) only adds a `pytest.skip` wrapper in the crewai tools integration test — no logic changes. No new issues introduced.
</assessment>

<file name="src/blaxel/core/jobs/__init__.py">
<issue location="src/blaxel/core/jobs/__init__.py:331">
`offset` is still unconditionally forwarded on every cursor-paginated follow-up page (unaddressed from previous review). Once a cursor is active, offset should be zero to avoid skipping items if the server treats them additively.
</issue>
</file>

_{Tag @mendral-app with feedback or questions. View session}

[mendral-app]

bug (P2), medium confidence: offset is still unconditionally forwarded on every cursor-paginated follow-up page (unaddressed from previous review). Once a cursor is active, offset should be zero to avoid skipping items if the server treats them additively.

Suggested change

Suggested change

	offset=offset,
	offset=offset if page_cursor is None else 0,

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/blaxel/core/jobs/__init__.py, line 331:

<issue>
`offset` is still unconditionally forwarded on every cursor-paginated follow-up page (unaddressed from previous review). Once a cursor is active, offset should be zero to avoid skipping items if the server treats them additively.
</issue>