AltimateAI / AltimateAI/altimate-code
BigQuery finops: surface bq_region + actionable error messages + warehouse_add warning
- Dominant language
- TypeScript
- Stars
- 811
- Forks
- 134
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 50
Description
Sub-issue split out of #754 to make a focused PR. Covers four of the seven items.
## Scope (this issue)
1. **Surface `bq_region` in BigQuery finops tool responses** — every finops tool (`finops_query_history`, `finops_analyze_credits`, `finops_expensive_queries`, `finops_warehouse_advice`, `finops_unused_resources`, `finops_role_grants`) returns the queried region as a top-level field on success and error paths. Lets the agent (and humans inspecting tool output) see which region was actually queried after the silent `us` fallback in #739.
2. **`augmentBqError(error, region)` helper** — appends a region hint to BQ errors that look region-related (anchored to `region-.INFORMATION_SCHEMA` and `Not found:` patterns), idempotent, safe on non-region errors. Wired into all five finops `catch` blocks.
3. **`isBqPermissionError(error)` helper** — detects the `TABLE_STORAGE` 403 pattern that `finops_unused_resources` hits routinely on project-scoped service accounts, with a word-boundary `\b403\b` check so unrelated numerics (`4031`, `40322`, `port 4030`) don't false-positive. Produces an actionable message naming `bigquery.resourceAdmin`.
4. **`warehouse_add` non-fatal warning** — fires when a BigQuery connection is registered without a `location` field (or with a whitespace-only value). Lists the affected finops tools and tells the user to re-add the connection with `"location": ""` for non-US projects.
## Out of scope (remain in #754)
5. Distinguish "no location provided" vs "location provided but sanitized to empty" — behaviour change with cross-region compliance implications, needs separate consideration.
6. Refactor BQ finops builders to options-object — pure code structure change.
7. E2E test silent-skip warning — test infrastructure improvement.
## Reference
Surfaced during the v0.6.1 release review (CTO/PM/Data Engineer/Tech Lead/Chaos Gremlin five-persona panel + 8-model consensus review).
Contributor guide
Assessment
This issue has not been assessed yet.