Feat: Sync SDK with v2 Platform API + add route-drift guard

Brings the SDK back in line with compute/pkg/platform/v2/routes.go (26 routes):

- Fix sandbox resource path /v2/sandboxes -> /v2/sandcastles (the backend
  renamed it with no alias; every sandbox call was 404ing). Verified live
  against staging.
- Sandbox: add list/executions (cursor-paginated), optional sandbox_id on
  start, and tql_path/params/max_rows on query (exactly-one-of guard).
- Connectors: add types/create/test/update/delete (config passed through as
  proto-JSON; types() is self-describing).
- Bump 2.0.0 -> 2.1.0; CHANGELOG entry + backfilled 2.0.0 entry.

Drift prevention (SDK half of Tier 1):
- # v2:covers comment on all 26 methods + tests/test_route_coverage.py asserting
  SDK coverage == vendored tests/routes.manifest.json (byte-identical to the
  canonical manifest generated by the backend's TestRouteManifest golden test).
- Scheduled route-sync workflow opens a PR when the backend manifest drifts.
- respx unit tests for sandbox + connectors; live-staging coverage for the new
  read endpoints.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jlsajfj

.github/workflows/route-sync.yml

@@ -0,0 +1,53 @@
+name: Route Sync
+
+# Pulls the canonical v2 route manifest from the backend and opens a PR when it
+# drifts from the vendored copy. The PR then fails test_route_coverage until the
+# matching SDK methods + `# v2:covers` comments are added. Configure the repo
+# variable BACKEND_MANIFEST_URL (raw URL of compute/pkg/platform/v2/routes.manifest.json)
+# and, if the source is private, the BACKEND_REPO_TOKEN secret.
+
+on:
+  schedule:
+    - cron: "0 12 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Fetch upstream manifest
+        id: fetch
+        env:
+          BACKEND_MANIFEST_URL: ${{ vars.BACKEND_MANIFEST_URL }}
+          BACKEND_REPO_TOKEN: ${{ secrets.BACKEND_REPO_TOKEN }}
+        run: |
+          if [ -z "$BACKEND_MANIFEST_URL" ]; then
+            echo "BACKEND_MANIFEST_URL not set; skipping"
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          auth=()
+          if [ -n "$BACKEND_REPO_TOKEN" ]; then auth=(-H "Authorization: Bearer $BACKEND_REPO_TOKEN"); fi
+          curl -fsSL "${auth[@]}" "$BACKEND_MANIFEST_URL" -o upstream.json
+          changed=$(python -c "import json,sys; a=set(json.load(open('upstream.json'))); b=set(json.load(open('tests/routes.manifest.json'))); print('true' if a!=b else 'false')")
+          if [ "$changed" = "true" ]; then
+            python -c "import json; json.dump(sorted(json.load(open('upstream.json'))), open('tests/routes.manifest.json','w'), indent=2); open('tests/routes.manifest.json','a').write('\n')"
+          fi
+          echo "changed=$changed" >> "$GITHUB_OUTPUT"
+      - name: Open PR
+        if: steps.fetch.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          branch: route-sync
+          add-paths: tests/routes.manifest.json
+          commit-message: "chore: sync v2 route manifest from backend"
+          title: "chore: sync v2 route manifest from backend"
+          body: |
+            The backend `/v2` route set changed. Add/rename the matching SDK
+            methods and their `# v2:covers` comments until `test_route_coverage`
+            passes.

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to the `textql` Python SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] — 2026-06-18
+
+### Fixed
+- Sandbox resource now targets `/v2/sandcastles`; the backend renamed the path from `/v2/sandboxes` with no alias, so every sandbox call was 404ing.
+
+### Added
+- Sandbox: `list` and `executions` (both cursor-paginated), and an optional `sandbox_id` on `start` to restart a specific sandbox.
+- Sandbox `query`: `tql_path` (run a saved library `.tql`), `params`, and `max_rows`; enforces exactly one of `query`/`tql_path` client-side.
+- Connectors: `types`, `create`, `test`, `update`, `delete` — `config` is passed through as proto-JSON; call `connectors.types()` for per-type fields.
+- Route-drift guard: `tests/test_route_coverage.py` + vendored `tests/routes.manifest.json`, and a scheduled `route-sync` workflow that opens a PR when the backend route set changes.
+
+## [2.0.0] — 2026-05-14
+
+### Changed
+- Version realigned to 2.x to track the v2 Platform API surface.
+- Releases publish to PyPI via Trusted Publishing.
+
 ## [0.2.0] — 2026-05-14
 
 ### Added

src/textql/_version.py

@@ -1 +1 @@
-__version__ = "2.0.0"
+__version__ = "2.1.0"

src/textql/resources/chat.py

@@ -14,6 +14,7 @@ class Chat:
     def __init__(self, client: TextQL) -> None:
         self._client = client
 
+    # v2:covers GET /v2/chats
     def list(
         self,
         *,
@@ -36,6 +37,7 @@ def list(
             params["sort_direction"] = sort_direction
         return self._client.request("GET", "/v2/chats", params=params)
 
+    # v2:covers POST /v2/chats
     def create(
         self,
         question: str,
@@ -83,9 +85,11 @@ def _create_multipart(
 
         return self._client.request("POST", "/v2/chats", data=fields, files=file_tuples)
 
+    # v2:covers GET /v2/chats/:id
     def get(self, chat_id: str) -> Any:
         return self._client.request("GET", f"/v2/chats/{chat_id}")
 
+    # v2:covers POST /v2/chats/stream
     def stream(
         self,
         question: str,
@@ -103,5 +107,6 @@ def stream(
             body["tools"] = tools
         return self._client.stream_request("POST", "/v2/chats/stream", json=body)
 
+    # v2:covers POST /v2/chats/:id/cancel
     def cancel(self, chat_id: str) -> Any:
         return self._client.request("POST", f"/v2/chats/{chat_id}/cancel")

src/textql/resources/connectors.py

@@ -10,5 +10,52 @@ class Connectors:
     def __init__(self, client: TextQL) -> None:
         self._client = client
 
+    # v2:covers GET /v2/connectors
     def list(self) -> Any:
         return self._client.request("GET", "/v2/connectors")
+
+    # v2:covers GET /v2/connectors/types
+    def types(self) -> Any:
+        return self._client.request("GET", "/v2/connectors/types")
+
+    # v2:covers POST /v2/connectors
+    def create(
+        self,
+        config: dict[str, Any],
+        *,
+        allow_sql_write_operations: bool | None = None,
+        include_db_session_metadata: bool | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {"config": config}
+        if allow_sql_write_operations is not None:
+            body["allow_sql_write_operations"] = allow_sql_write_operations
+        if include_db_session_metadata is not None:
+            body["include_db_session_metadata"] = include_db_session_metadata
+        return self._client.request("POST", "/v2/connectors", json=body)
+
+    # v2:covers POST /v2/connectors/test
+    def test(self, config: dict[str, Any], *, connector_id: str | None = None) -> Any:
+        body: dict[str, Any] = {"config": config}
+        if connector_id is not None:
+            body["connector_id"] = connector_id
+        return self._client.request("POST", "/v2/connectors/test", json=body)
+
+    # v2:covers PATCH /v2/connectors/:id
+    def update(
+        self,
+        connector_id: int,
+        config: dict[str, Any],
+        *,
+        allow_sql_write_operations: bool | None = None,
+        include_db_session_metadata: bool | None = None,
+    ) -> Any:
+        body: dict[str, Any] = {"config": config}
+        if allow_sql_write_operations is not None:
+            body["allow_sql_write_operations"] = allow_sql_write_operations
+        if include_db_session_metadata is not None:
+            body["include_db_session_metadata"] = include_db_session_metadata
+        return self._client.request("PATCH", f"/v2/connectors/{connector_id}", json=body)
+
+    # v2:covers DELETE /v2/connectors/:id
+    def delete(self, connector_id: int) -> Any:
+        return self._client.request("DELETE", f"/v2/connectors/{connector_id}")

src/textql/resources/playbooks.py

@@ -10,6 +10,7 @@ class Playbooks:
     def __init__(self, client: TextQL) -> None:
         self._client = client
 
+    # v2:covers GET /v2/playbooks
     def list(
         self,
         *,
@@ -35,9 +36,11 @@ def list(
             params["status_filter"] = status_filter
         return self._client.request("GET", "/v2/playbooks", params=params)
 
+    # v2:covers POST /v2/playbooks
     def create(self) -> Any:
         return self._client.request("POST", "/v2/playbooks")
 
+    # v2:covers GET /v2/playbooks/:id
     def get(
         self,
         playbook_id: str,
@@ -52,6 +55,7 @@ def get(
             params["offset"] = offset
         return self._client.request("GET", f"/v2/playbooks/{playbook_id}", params=params)
 
+    # v2:covers PATCH /v2/playbooks/:id
     def update(
         self,
         playbook_id: str,
@@ -87,12 +91,15 @@ def update(
             body["selected_template_data_ids"] = selected_template_data_ids
         return self._client.request("PATCH", f"/v2/playbooks/{playbook_id}", json=body)
 
+    # v2:covers POST /v2/playbooks/:id/deploy
     def deploy(self, playbook_id: str) -> Any:
         return self._client.request("POST", f"/v2/playbooks/{playbook_id}/deploy")
 
+    # v2:covers DELETE /v2/playbooks/:id
     def delete(self, playbook_id: str) -> Any:
         return self._client.request("DELETE", f"/v2/playbooks/{playbook_id}")
 
+    # v2:covers POST /v2/playbooks/:id/run
     def run(self, playbook_id: str, *, dry_run: bool = False) -> Any:
         body: dict[str, Any] = {}
         if dry_run:

src/textql/resources/sandbox.py

@@ -13,33 +13,89 @@ class Sandbox:
     def __init__(self, client: TextQL) -> None:
         self._client = client
 
-    def start(self) -> Any:
-        return self._client.request("POST", "/v2/sandboxes")
+    # v2:covers POST /v2/sandcastles
+    def start(self, *, sandbox_id: str | None = None) -> Any:
+        body: dict[str, Any] = {}
+        if sandbox_id is not None:
+            body["sandbox_id"] = sandbox_id
+        return self._client.request("POST", "/v2/sandcastles", json=body or None)
 
+    # v2:covers GET /v2/sandcastles
+    def list(
+        self,
+        *,
+        status: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        return self._client.request("GET", "/v2/sandcastles", params=params)
+
+    # v2:covers GET /v2/sandcastles/:id
     def status(self, sandbox_id: str) -> Any:
-        return self._client.request("GET", f"/v2/sandboxes/{sandbox_id}")
+        return self._client.request("GET", f"/v2/sandcastles/{sandbox_id}")
+
+    # v2:covers GET /v2/sandcastles/:id/executions
+    def executions(
+        self,
+        sandbox_id: str,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        return self._client.request(
+            "GET", f"/v2/sandcastles/{sandbox_id}/executions", params=params
+        )
 
+    # v2:covers DELETE /v2/sandcastles/:id
     def stop(self, sandbox_id: str) -> Any:
-        return self._client.request("DELETE", f"/v2/sandboxes/{sandbox_id}")
+        return self._client.request("DELETE", f"/v2/sandcastles/{sandbox_id}")
 
+    # v2:covers POST /v2/sandcastles/:id/execute
     def execute(self, sandbox_id: str, *, code: str) -> Any:
         return self._client.request(
-            "POST", f"/v2/sandboxes/{sandbox_id}/execute", json={"code": code}
+            "POST", f"/v2/sandcastles/{sandbox_id}/execute", json={"code": code}
         )
 
+    # v2:covers POST /v2/sandcastles/:id/query
     def query(
         self,
         sandbox_id: str,
         *,
         connector_id: int,
-        query: str,
+        query: str | None = None,
+        tql_path: str | None = None,
+        params: dict[str, Any] | None = None,
+        max_rows: int | None = None,
         dataframe_name: str | None = None,
     ) -> Any:
-        body: dict[str, Any] = {"connector_id": connector_id, "query": query}
+        if (query is None) == (tql_path is None):
+            raise ValueError("exactly one of query or tql_path is required")
+        body: dict[str, Any] = {"connector_id": connector_id}
+        if query is not None:
+            body["query"] = query
+        if tql_path is not None:
+            body["tql_path"] = tql_path
+        if params is not None:
+            body["params"] = params
+        if max_rows is not None:
+            body["max_rows"] = max_rows
         if dataframe_name is not None:
             body["dataframe_name"] = dataframe_name
-        return self._client.request("POST", f"/v2/sandboxes/{sandbox_id}/query", json=body)
+        return self._client.request("POST", f"/v2/sandcastles/{sandbox_id}/query", json=body)
 
+    # v2:covers POST /v2/sandcastles/:id/files
     def upload_file(self, sandbox_id: str, file: FileInput) -> Any:
         if isinstance(file, tuple):
             name, content = file
@@ -49,6 +105,6 @@ def upload_file(self, sandbox_id: str, file: FileInput) -> Any:
             content = p.read_bytes()
         return self._client.request(
             "POST",
-            f"/v2/sandboxes/{sandbox_id}/files",
+            f"/v2/sandcastles/{sandbox_id}/files",
             files=[("file", (name, content))],
         )

tests/routes.manifest.json

@@ -0,0 +1,28 @@
+[
+  "DELETE /v2/connectors/:id",
+  "DELETE /v2/playbooks/:id",
+  "DELETE /v2/sandcastles/:id",
+  "GET /v2/chats",
+  "GET /v2/chats/:id",
+  "GET /v2/connectors",
+  "GET /v2/connectors/types",
+  "GET /v2/playbooks",
+  "GET /v2/playbooks/:id",
+  "GET /v2/sandcastles",
+  "GET /v2/sandcastles/:id",
+  "GET /v2/sandcastles/:id/executions",
+  "PATCH /v2/connectors/:id",
+  "PATCH /v2/playbooks/:id",
+  "POST /v2/chats",
+  "POST /v2/chats/:id/cancel",
+  "POST /v2/chats/stream",
+  "POST /v2/connectors",
+  "POST /v2/connectors/test",
+  "POST /v2/playbooks",
+  "POST /v2/playbooks/:id/deploy",
+  "POST /v2/playbooks/:id/run",
+  "POST /v2/sandcastles",
+  "POST /v2/sandcastles/:id/execute",
+  "POST /v2/sandcastles/:id/files",
+  "POST /v2/sandcastles/:id/query"
+]