Discoverability gap: finding a Query-Service-compatible workspace for data-app local dev is tedious and dead-ends silently

[davidesner]

What I was trying to do

Develop a Streamlit data app for a real project, reading from Storage via the Query Service (POST /v2/storage/branch/{BRANCH_ID}/workspaces/{WS}/query). The app eventually deploys to production, so I needed a workspace on main that the Query Service can route to.

What actually happened (in order)

1. The alias was silently pinned to a dev branch from a previous, unrelated session

kbagent project list showed:

Alias        Project Name              ID    Branch
keboola-…    Keboola AI                361   main      *
new-bran…    Chat Data Engineer Demo   3047  37363

I did not pin this alias to branch 37363 in the current session — that state was carried over from some earlier, unrelated work (presumably kbagent branch use 37363 or kbagent project add --branch ...). kbagent persists the alias's branch context across sessions, which is the right default for many workflows but means agents (and humans) walking in cold have no way to tell they're operating against a non-default state until things break in confusing ways downstream.

A one-line warning at session start (or on the first command after a fresh shell) along the lines of Note: alias 'new-branches' is currently pinned to dev branch '37363' — run 'kbagent branch reset --project new-branches' to switch to main would have prevented everything below.

2. kbagent workspace list silently scopes to the pinned branch

With the alias pinned to 37363, kbagent workspace list --project new-branches only returns workspaces in that branch. It has no --branch flag and no informational prefix.

Compare with kbagent storage buckets, which usefully prints:

Info: Using production branch for read (active dev branch '37363' ignored; pass --branch 37363 to override)

workspace list should print the analogous notice and accept --branch for parity.

3. parameters.id in a sandbox config is NOT the Storage workspace ID

Falling back to kbagent config list --component-id keboola.sandboxes --branch 8653 reveals main-branch sandbox configs, e.g. one named "RO" with body:

{
  "parameters": {
    "id": "29590864"
  }
}

Plausible reading: that's the Storage workspace ID. It is not. The actual Storage workspace ID for that sandbox is 13590754 — only the project owner knew this and had to correct me. kbagent workspace detail --workspace-id 29590864 returns Resource not found, which is correct but reinforces the wrong assumption.

config detail for keboola.sandboxes should either annotate the body output ("note: `parameters.id` is not the Storage workspace ID") or resolve and display the actual workspace ID alongside.

4. Once the right workspace ID is found, login-type incompatibility surfaces only at query time

Even after switching to workspace 13590754 (RO on main), the Query Service rejects it:

{
  "error": "Custom query execution is not supported for login type \"snowflake-legacy-service\".",
  "code": "storage.executeQuery.notSupportedLoginType"
}

There's no way to learn a workspace's login type from kbagent workspace detail or kbagent workspace list. For an RO-data-app workflow, this is the single most important compatibility signal — without it, every workspace selection is a coin-flip until you try a query.

Suggested fixes (rough priority)

1. Session-start / first-command warning when any alias is in a non-default state (pinned to a dev branch, etc.). Persistence is fine; lack of visibility is the problem.
2. `kbagent workspace list --branch ` for parity with `storage buckets` and `config list`. Print the same "using production branch / dev branch X ignored" notice these commands do.
3. `kbagent workspace list` output should include the workspace's login type (or a `qs_compatible` boolean) so callers can pick a Query-Service-compatible one at a glance.
4. `kbagent config detail --component-id keboola.sandboxes` should annotate output: `parameters.id` is not the Storage workspace ID, and the resolved Storage workspace ID should appear if available.
5. Consider a `kbagent workspace list --for data-app` filter that pre-filters to RO + Query-Service-compatible workspaces on the production branch.

Repro / context

• kbagent v0.41.9, keboola-mcp-server v1.32.0
• Stack: https://connection.us-east4.gcp.keboola.com (GCP us-east4)
• Project 3047 ("Chat Data Engineer Demo")
• Time spent: ~30 min and 4 wrong workspace IDs (including the parameters.id red herring) before getting one that surfaces a usable error (login-type mismatch), with the actual ID supplied by the project owner.

[padak]

Released in v0.42.0 via PR #311.

All four signals you flagged are now visible:

1. ✅ workspace list / workspace detail accept --branch and print the same Info: Using production branch for read ... banner as storage buckets / config list when an alias is pinned to a dev branch.
2. ✅ Every workspace entry exposes login_type, read_only, qs_compatible, database, warehouse (Storage API has always returned them; kbagent was discarding them).
3. ✅ workspace list --qs-compatible pre-filters to RO + whitelisted-loginType workspaces — the canonical data-app shape.
4. ✅ config detail --component-id keboola.sandboxes --config-id <ID> appends a sandbox_annotation block with both the misleading sandbox_service_id (the trap) AND the resolved storage_workspace_id (the answer).

Plus REST parity (GET /workspaces?branch=&qs_compatible= and GET /workspaces/{p}/{id}?branch=) so the web UI / scheduled agents get the same fields automatically.

The Query-Service compatibility whitelist (QUERY_SERVICE_COMPATIBLE_LOGIN_TYPES) is intentionally conservative — snowflake-service-keypair + snowflake-person-sso only — because your incident proved snowflake-legacy-service is per-stack flaky (works on connection.keboola.com, rejected on GCP us-east4). False negatives over false positives.

Thank you for the surgical report — every reproduction step, every error message, every fix you suggested landed in the release.

kbagent update