feat(workspace): BigQuery support for workspace query (0.58.0)

[padak]

What

Adds BigQuery support to kbagent workspace query and the surrounding workspace classification, matching what keboola-mcp-server already does. Bumps to 0.58.0.

Why

The team enabled BigQuery in the Query Service server-side. Investigating against the real e2e-bigquery project (id 9621, connection.keboola.com) showed the query execution path was already backend-agnostic — POST .../queries + CSV export are identical for Snowflake and BigQuery, so a SELECT against a BigQuery workspace already returned rows. The actual defects were elsewhere:

1. qs_compatible was Snowflake-only. BigQuery workspaces carry login_type: "default", which IS Query-Service-compatible, but default was off the whitelist, so every BigQuery workspace was reported qs_compatible: false and hidden by workspace list --qs-compatible — misleading data-app developers into thinking BigQuery can't run Query-Service SELECTs.
2. BigQuery errors leaked the wrapper. The Query Service serializes a failed BigQuery statement as {Location: "query"; Message: "Syntax error: ..."; Reason: "invalidQuery"} instead of plain text.

Changes

Code

• constants.py — new QUERY_SERVICE_COMPATIBLE_LOGIN_TYPES_BIGQUERY ({default}), kept separate from the Snowflake set because Snowflake's own legacy default is rejected by the Query Service (JWT token is invalid). Same string, opposite meaning per backend.
• services/workspace_service.py — _classify_qs_compatibility(login_type, backend) is now keyed by (backend, loginType); workspace create on BigQuery requests login_type="default" explicitly (parity with mcp-server) instead of relying on the backend default.
• client.py — _unwrap_bigquery_error (regex on Message: "...") wired into _extract_query_job_error; Snowflake plain text passes through untouched.

Docs — corrected gotchas.md (the whitelist now documents the backend-keyed semantics) and workspace-workflow.md. Changelog + plugin.json + marketplace.json + uv.lock synced to 0.58.0.

Testing

Unit — TestBigQueryQueryServiceSupport (backend-aware classification, Snowflake-default regression guard, BigQuery login-type, qs-compatible filter), TestUnwrapBigQueryError + a BigQuery case in TestExtractQueryJobError, updated TestAutoDetectBackend BigQuery create asserts. Full suite: 3854 passed, 0 failures. Lint/format/ty/skill/version gates green.

Live — verified end-to-end against project 9621 (e2e-bigquery, connection.keboola.com):

Check	Result
workspace query (constant + real data via workspace load)	rows returned; BigQuery back-tick FQN works
workspace detail / list --qs-compatible	qs_compatible: true (was false); 6 BigQuery workspaces surfaced (was 0)
bad query	clean message Unrecognized name: nonexistent_col at [1:8] (no {Location...} wrapper)
workspace create (explicit default)	qs_compatible: true, query runs

Test workspaces created during verification were cleaned up.

Reviewer notes

• test_e2e.py workspace query is now backend-aware (BigQuery back-tick vs Snowflake double-quote identifier quoting) — running the E2E suite against a BigQuery project no longer fails on quoting; detail also asserts login_type/qs_compatible.
• The workspace create behaviour change (explicit login_type="default") updated 3 existing TestAutoDetectBackend asserts that pinned the old omit-loginType behaviour.

---

---

Rebased onto main 2026-06-05: version re-bumped 0.56.0 -> 0.58.0 (0.56.0 was taken by the #399 maintenance re-release, main is now at 0.57.0). Changelog moved under the 0.58.0 key; full suite green (3879 passed).

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

[padak]

Review of #398 — feat(workspace): BigQuery support for workspace query (0.58.0)

Generated by kbagent-pr-reviewer subagent. Verdict and findings below
are advisory; the human author retains every veto. CI-coverable issues
(lint, format, tests) are confirmed via make check, not duplicated here.

Summary

This PR extends workspace query / workspace list / workspace detail to
correctly classify BigQuery workspaces as Query-Service-compatible, adds
backend-aware error unwrapping for BigQuery query failures, and aligns
workspace create on BigQuery projects with keboola-mcp-server. The
implementation is clean (3-layer compliant, well-tested, good constant
hygiene), the regression guard for the Snowflake-default-stays-false case
is in place, and all prerequisite sync surfaces have been updated (gotchas.md,
workspace-workflow.md, changelog, version files). Two NON-BLOCKING gaps were
found: (1) commands-reference.md and keboola-expert.md §2 / §3 do not
note the 0.58.0 semantics change to qs_compatible classification for BigQuery
callers; (2) client.py crossed the 2000-LOC hard ceiling already on main
and this PR adds 25 more lines without splitting — the split obligation existed
before this PR but this PR is additive in a file above hard budget.

Verdict: APPROVE — no blocking findings, two non-blocking findings, one nit.

Verdict

• Verdict: APPROVE
• Blocking findings: 0
• Non-blocking findings: 2
• Nits: 1

Blocking findings

(none)

Non-blocking findings

[NB-1] plugins/kbagent/skills/kbagent/references/commands-reference.md:167-168 — workspace list / workspace detail entries carry no (updated v0.58.0) tag for the BigQuery qs_compatible change

The entries at lines 167-168 document the qs_compatible field with a bare
"Since v0.42.0 (#304)" tag. The semantics changed in 0.58.0: qs_compatible
is now keyed by (backend, loginType), not loginType alone, so BigQuery
workspaces (previously always false) are now true. An agent running on an
older kbagent install would follow the same --qs-compatible filter and get
zero results for a BigQuery project — identical symptom to pre-0.42.0 behavior.
Per CONTRIBUTING.md > references/gotchas.md, behavior changes that agents
would get wrong on older installs need a version tag.

Fix: append (updated v0.58.0 -- BigQuery workspaces carry loginType "default" and are now qs_compatible: true; before 0.58.0 they were always false) to the
workspace list and workspace detail bullet descriptions.

[NB-2] src/keboola_agent_cli/client.py:3194 — file is above the 2000-LOC hard ceiling

client.py is 3194 LOC after this PR (+25 from main's 3169). The hard
ceiling per CONTRIBUTING.md > "File-size budgets" is 2000 LOC for clients.
The split obligation predates this PR (the file was 3169 LOC on main), but
this PR adds material to a file that is already 60% over hard budget. Per the
guideline: "When a file crosses the hard ceiling, splitting is required before
merging more functionality into it." The split itself is likely a multi-PR
undertaking; flagging here so the next PR author does not inherit the rule
silently.

Fix: open a follow-up issue (or do it before merge if straightforward) to
extract the Query Service helpers (wait_for_query_job, _extract_query_job_error,
_unwrap_bigquery_error) plus the workspace query helpers into a sibling
client_query.py or client/workspace_query.py.

Nits

• [NIT-1] plugins/kbagent/agents/keboola-expert.md:103 — the "Ad-hoc SQL / row-count / type audit" row in §2 references workspace list --qs-compatible (0.42.0+, #304) without noting that BigQuery workspaces are now included in the compatible set since 0.58.0. An agent working against a BigQuery project on 0.58.0+ could still be surprised by the default login_type appearing in qs_compatible: true output when the §2 row implies Snowflake-only semantics. One-liner addition to the "First choice" cell: append (since 0.58.0 also covers BigQuery workspaces; loginType "default" is QS-compatible on BigQuery but rejected on Snowflake).

Verification log

• gh pr view 398 --json title,body,files,additions,deletions,baseRefName,headRefName,labels,state → 13 files changed, +311/-30, state OPEN, headRefName claude/exciting-ride-fbf6e2 matching working tree ✓
• git rev-parse --abbrev-ref HEAD → claude/exciting-ride-fbf6e2 (matches PR branch) ✓
• Read CONTRIBUTING.md, CLAUDE.md, plugins/kbagent/agents/keboola-expert.md, plugins/kbagent/skills/kbagent/references/gotchas.md ✓
• gh pr diff 398 → 602 diff lines, no new @app.command(...) decorators → no new CLI command surface; no OPERATION_REGISTRY / context.py / CLAUDE.md command-list update required ✓
• Layer check: grep -E 'from typer|import typer' /tmp/kbagent-pr-398.diff | grep services/ → empty ✓; grep -E 'from httpx|import httpx' diff | grep commands/ → empty ✓; grep -E 'formatter\.|console\.print' diff | grep client\.py → empty ✓
• Convention checks: magic numbers → none; raw error_code="..." strings → none; bare except: → none; print() in src/ → none; token in logged output → none ✓
• _classify_qs_compatibility callers: all three call sites in workspace_service.py (lines 518, 684) pass the new backend argument; no missed call sites ✓
• QUERY_SERVICE_COMPATIBLE_LOGIN_TYPES_BIGQUERY and BIGQUERY_WORKSPACE_LOGIN_TYPE added in constants.py with detailed rationale comments ✓
• gotchas.md "workspace list / workspace detail" section updated with (since v0.58.0) inline tag for BigQuery qs_compatible semantics ✓
• workspace-workflow.md updated: Query Service line now says "Backend-agnostic: runs SELECTs against both Snowflake and BigQuery workspaces (BigQuery since v0.58.0)" ✓
• plugins/kbagent/agents/keboola-expert.md §3: no inline gotcha for BigQuery workspace create login_type change; the behavior IS documented in gotchas.md, so this is advisory only (not blocking per CONTRIBUTING.md notes on §3)
• commands-reference.md workspace entries: no (updated v0.58.0) tag for the qs_compatible semantics change → NB-1 above
• keboola-expert.md byte size: 48840 bytes (well under 62000 cap) ✓
• make check (full suite) → 3879 passed, 8 skipped, 124 deselected, 16 warnings in 80.90s exit 0; All checks passed! ✓
• Test coverage: TestBigQueryQueryServiceSupport (6 unit tests in test_workspace_service.py) covers backend-aware classification, Snowflake-default regression guard, login-type helper, and end-to-end qs_compatible filter; TestUnwrapBigQueryError (4 unit tests in test_client.py) covers the regex extractor; 3 existing TestAutoDetectBackend asserts updated for the login_type="default" BigQuery change; test_e2e.py backend-aware query + login_type/qs_compatible asserts ✓
• client.py LOC: 3194 (main was 3169; hard ceiling is 2000) → NB-2 above
• workspace_service.py LOC: 1021 (main was 999; crossed soft ceiling of 1000 in this PR; hard ceiling 1500 still has headroom) → tracked as context for NB-2
• Behavior verification via live run not performed (no credentials in CI environment). PR description provides detailed live test matrix against project 9621 (e2e-bigquery, connection.keboola.com); results are internally consistent with the code changes.

Open questions for the author

(none)

[padak]

Review feedback addressed

Both reviews (Devin + kbagent-pr-reviewer) are top-level COMMENTED reviews with no inline comment threads, so there is nothing to resolve thread-by-thread. Disposition:

• NB-1 (commands-reference.md workspace list/detail/query) — FIXED in 82faf3d. The entries now document the v0.58.0 backend-aware change: qs_compatible is keyed by (backend, loginType), BigQuery default workspaces are qs_compatible: true and pass --qs-compatible (Snowflake's legacy default stays false), and workspace query is backend-agnostic (with the Snowflake double-quote vs BigQuery back-tick dialect note). This was the actionable silent-drift gap I introduced — gotchas.md and workspace-workflow.md were updated in the original commit but commands-reference.md was missed.

• NB-2 (client.py 3194 LOC > 2000 LOC ceiling) — acknowledged, out of scope. Pre-existing; this PR adds 25 lines (_unwrap_bigquery_error + regex). Not CI-enforced (make check is green). Recommend tracking a client.py split as a separate follow-up in the team's tracker rather than scope-creeping this PR.

• Devin "4 additional findings" — not accessible. Devin's GitHub verdict is "No Issues Found"; the 4 findings live behind the Devin app link and were not posted as GitHub review comments, so they can't be addressed or resolved from the PR. If any are real, please surface them here and I'll act.

make check remains green after the doc fix (3879 passed).