fix(finops): name the workspace engine tool when a FinOps tool has no local connection

Merged
SA
2mo ago
+530-34

Issue for this PR

Closes #1336

Type of change

  • Bug fix

What does this PR do?

The finops_* tools resolve their warehouse from the local connection registry only (warehouse-resolver.ts). In a project bound to a workspace whose Snowflake credentials live in the workspace there is no local entry, so finops_warehouse_advice, finops_analyze_credits, finops_query_history, finops_expensive_queries (and the role tools) all came back FAILED with nothing that pointed at the engine tool that works — and the workspace's own cost skills steer the model to exactly these tools first.

This is option 3 from the issue, done once for all eight tools rather than per message:

  • New tools/finops-workspace.ts. When the session's precedence snapshot serves sql_execute for a type the operation supports, the failure gets a second paragraph: "This tool only uses warehouse connections configured on this machine, and workspace "analytics" serves snowflake through its integration engine instead. Run the same analysis through the workspace: for snowflake, query the SNOWFLAKE.ACCOUNT_USAGE views (QUERY_HISTORY, WAREHOUSE_METERING_HISTORY, …) with datamate_snowflake_execute_database_query." — and metadata.workspace_fallback lists the engine tool(s), so telemetry can tell a failure the model can route around from a dead end.
  • It reads the same reachability-filtered projection the ## Workspace integrations section uses (servedInventory), so it never names a tool the caller's agent (analyst) cannot call, says nothing for an unbound project or with --integrations=local, and only names types the operation supports (a BigQuery-only workspace adds nothing to the Snowflake-only role tools).
  • Every finops_* failure branch — dispatcher error and thrown error, so the stale-credentials case on Anand's machine is covered too — goes through withWorkspaceFallback. The local reason is kept: a missing or broken local connection is still a fact worth stating.
  • QUERY_HISTORY_SUPPORTED_TYPES / SNOWFLAKE_ONLY_TYPES are exported so the wrappers name the types their handler really supports instead of a second copy.

Not in this PR (the issue's options 1 and 2): routing the FinOps SQL through the engine tool from native code — the engine's result shape is not a contract the native handlers parse — and hiding the tools in the awareness section. Both are larger changes to a heavily-tested surface; happy to file follow-ups if we want them.

How did you verify your code works?

  • test/altimate/finops-workspace-fallback.test.ts (12 tests): served type → named; no snapshot / --integrations=local / analyst ruleset / unsupported served type → untouched; note wording; and three tools through the real handlers with an empty registry — finops_warehouse_advice --warehouse COMPUTE_WH (the issue's repro) names the engine tool and keeps the local reason, finops_role_hierarchy on a BigQuery-only workspace stays plain, an unbound project stays plain.
  • Mutation: disabling the lookup fails 4 of the 12. Restored.
  • test/altimate directory: 5387 pass, 1 unrelated timing flake (skill-sync flushPendingSyncs, passes in isolation). Typecheck and marker guard clean.

Screenshots / recordings

N/A (tool output). The new failure shape, from the tool test:

Failed to analyze warehouses: Warehouse advice requires a configured warehouse, but none are set up. …

This tool only uses warehouse connections configured on this machine, and workspace "analytics" serves snowflake through its integration engine instead. Run the same analysis through the workspace: for snowflake, query the `SNOWFLAKE.ACCOUNT_USAGE` views (`QUERY_HISTORY`, `WAREHOUSE_METERING_HISTORY`, `WAREHOUSE_LOAD_HISTORY`, `GRANTS_TO_ROLES`, `GRANTS_TO_USERS`) with `datamate_snowflake_execute_database_query`.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

🤖 Generated with Claude Code

https://claude.ai/code/session_012Q51zFUmPg1WwtS5CrGJE6

Summary by cubic

Fixes the eight finops_* tools failing without explanation when a project is bound to a workspace whose warehouse credentials live in the workspace. Failures now state the cause, name the workspace engine tool that can run the same analysis along with the tables to query, and stamp metadata.workspace_fallback for telemetry. Closes #1336.

Fallback behavior

  • New tools/finops-workspace.ts reads the same reachability-filtered projection as the ## Workspace integrations section, so it never names a tool the caller's agent cannot call and stays silent for unbound projects or --integrations=local.
  • The note names the tables the failing operation's own handler reads per served type; a pair with no known table names the engine tool alone. BigQuery recipes are region-qualified with an explained placeholder (<location>), since the snapshot carries no location and the engine runs what it is given.
  • The snapshot is re-validated in the same read that resolves the fallback; a relinked, unreadable, or missing snapshot marks the failure precedence: "undetermined" and says the workspace could not be consulted. Deliberate disablement stays a plain local failure.
  • Only types the operation supports get a route, so a BigQuery-only workspace adds nothing to the Snowflake-only role tools.
  • Both dispatcher-error and thrown-error branches go through the helper, and the local reason is kept since a broken local connection is still worth stating.
  • QUERY_HISTORY_SUPPORTED_TYPES and SNOWFLAKE_ONLY_TYPES are now exported so wrappers name the types their handler actually supports.
  • 12 tests cover the served, unserved, relinked, and disabled shapes plus all eight tools through the real handlers with an empty registry.
  • Routing the FinOps SQL through the engine tool from native code and hiding the tools are not included; both are larger changes.

Summary by CodeRabbit

  • New Features

    • Added operation-specific workspace fallback guidance for FinOps failures.
    • FinOps error messages now identify applicable workspaces, engine tools, and warehouse-specific data sources for retrying supported operations.
    • Added clearer messaging when workspace routing cannot be confirmed.
    • Improved BigQuery region guidance for querying metadata.

  • Bug Fixes

    • Improved failure handling across FinOps analysis, query, access, resource, and warehouse tools.

  • Tests

    • Added coverage for warehouse compatibility, routing states, workspace bindings, and unbound projects.