Skip to content

Commit c4ab025

Browse files
anandgupta42claude
andcommitted
fix: [#827] resolve finops_* 100% failure with warehouse-resolver fallback
Telemetry (memory/telemetry-analysis-2026-05-21.md, 2,503 machines, 14 days) flagged `finops_analyze_credits` (8/8) and `finops_query_history` (1/1) as 100% broken. Every user who tried them hit a dead-end "Credit analysis is not available for unknown warehouses." error with no path forward. Unlike `sql.explain` (which auto-falls-back to `warehouses[0]`), the finops handlers had no resolution logic and returned an unhelpful error whenever the caller omitted the warehouse name, supplied an unknown one, or supplied one whose type wasn't supported. Changes - New shared helper `finops/warehouse-resolver.ts` with a 4-branch resolution contract (ok / not configured / unknown name / unsupported type) and actionable errors that name the available warehouses and suggest `warehouse_add` when nothing is configured. - `credit-analyzer.ts` (analyzeCredits, getExpensiveQueries) and `query-history.ts` (getQueryHistory) wired to the resolver. The dead `getWhType` helpers removed. - `warehouse` parameter made optional on the `finops_analyze_credits` and `finops_query_history` tool schemas; descriptions updated to document the auto-pick behaviour and the full supported-warehouse list. - `CreditAnalysisParams`, `ExpensiveQueriesParams`, `QueryHistoryParams` marked `warehouse?` to match the new optionality contract. - 12 new unit tests in `test/altimate/finops-warehouse-resolver.test.ts` pinning every resolution branch including empty-string and whitespace-only requested values. Expected impact - Error rate on `finops_analyze_credits` and `finops_query_history` drops from 100% to whatever the real operational failure rate is (warehouse unreachable, ACCOUNT_USAGE permission missing, etc.). The resolver no longer masks those as "unknown warehouse" — driver errors pass through with their original message. - Cost-audit wedge demo now works on any tenant with a Snowflake / BigQuery / Databricks warehouse configured, without the LLM needing to guess the exact warehouse name. Validation - `tsgo --noEmit`: pass, zero errors. - `bun test test/altimate/finops-*`: 37 pass / 0 fail (12 new + 25 existing). - `bun test test/altimate/finops-*-e2e.test.ts test/altimate/schema-finops-dbt.test.ts test/altimate/finops-role-access.test.ts`: 85 pass / 67 skip (credentials-gated) / 0 fail. - Marker check: pass — no upstream-shared files touched. Closes #827 Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent 476d234 commit c4ab025

7 files changed

Lines changed: 458 additions & 34 deletions

File tree

‎packages/opencode/src/altimate/native/finops/credit-analyzer.ts‎

Lines changed: 50 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,16 @@
66

77
import * as Registry from "../connections/registry"
88
import { bqRegionFor, interpolateBqRegion } from "./bq-utils"
9+
import { resolveFinopsWarehouse } from "./warehouse-resolver"
910
import type {
1011
CreditAnalysisParams,
1112
CreditAnalysisResult,
1213
ExpensiveQueriesParams,
1314
ExpensiveQueriesResult,
1415
} from "../types"
1516

17+
const CREDIT_SUPPORTED_TYPES = ["snowflake", "bigquery", "databricks"] as const
18+
1619
// ---------------------------------------------------------------------------
1720
// Snowflake SQL templates
1821
// ---------------------------------------------------------------------------
@@ -185,12 +188,6 @@ LIMIT ?
185188
// Helpers
186189
// ---------------------------------------------------------------------------
187190

188-
function getWhType(warehouse: string): string {
189-
const warehouses = Registry.list().warehouses
190-
const wh = warehouses.find((w) => w.name === warehouse)
191-
return wh?.type || "unknown"
192-
}
193-
194191
function buildCreditUsageSql(
195192
whType: string, days: number, limit: number, warehouseFilter?: string, bqRegion?: unknown,
196193
): { sql: string; binds: any[] } | null {
@@ -302,14 +299,35 @@ function generateRecommendations(
302299
// ---------------------------------------------------------------------------
303300

304301
export async function analyzeCredits(params: CreditAnalysisParams): Promise<CreditAnalysisResult> {
305-
const whType = getWhType(params.warehouse)
306302
const days = params.days ?? 30
307303
const limit = params.limit ?? 50
308-
const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
304+
305+
const resolved = resolveFinopsWarehouse({
306+
requested: params.warehouse,
307+
supportedTypes: CREDIT_SUPPORTED_TYPES,
308+
operationName: "Credit analysis",
309+
})
310+
if (resolved.kind === "error") {
311+
return {
312+
success: false,
313+
daily_usage: [],
314+
warehouse_summary: [],
315+
total_credits: 0,
316+
days_analyzed: days,
317+
recommendations: [],
318+
error: resolved.error,
319+
}
320+
}
321+
322+
const { warehouse: whName, type: whType } = resolved
323+
const bqRegion = whType === "bigquery" ? bqRegionFor(whName) : undefined
309324

310325
const dailyBuilt = buildCreditUsageSql(whType, days, limit, params.warehouse_filter, bqRegion)
311326
const summaryBuilt = buildCreditSummarySql(whType, days, bqRegion)
312327

328+
// CREDIT_SUPPORTED_TYPES is the contract with the resolver — if we got past
329+
// resolution, both builders are guaranteed to return non-null. Defensive null
330+
// check here only to satisfy the type system; not a real runtime path.
313331
if (!dailyBuilt || !summaryBuilt) {
314332
return {
315333
success: false,
@@ -318,12 +336,12 @@ export async function analyzeCredits(params: CreditAnalysisParams): Promise<Cred
318336
total_credits: 0,
319337
days_analyzed: days,
320338
recommendations: [],
321-
error: `Credit analysis is not available for ${whType} warehouses.`,
339+
error: `Internal error: credit SQL templates missing for ${whType}.`,
322340
}
323341
}
324342

325343
try {
326-
const connector = await Registry.get(params.warehouse)
344+
const connector = await Registry.get(whName)
327345
const dailyResult = await connector.execute(dailyBuilt.sql, limit, dailyBuilt.binds)
328346
const summaryResult = await connector.execute(summaryBuilt.sql, 1000, summaryBuilt.binds)
329347

@@ -348,16 +366,32 @@ export async function analyzeCredits(params: CreditAnalysisParams): Promise<Cred
348366
total_credits: 0,
349367
days_analyzed: days,
350368
recommendations: [],
351-
error: String(e),
369+
error: e instanceof Error ? e.message : String(e),
352370
}
353371
}
354372
}
355373

356374
export async function getExpensiveQueries(params: ExpensiveQueriesParams): Promise<ExpensiveQueriesResult> {
357-
const whType = getWhType(params.warehouse)
358375
const days = params.days ?? 7
359376
const limit = params.limit ?? 20
360-
const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
377+
378+
const resolved = resolveFinopsWarehouse({
379+
requested: params.warehouse,
380+
supportedTypes: CREDIT_SUPPORTED_TYPES,
381+
operationName: "Expensive query analysis",
382+
})
383+
if (resolved.kind === "error") {
384+
return {
385+
success: false,
386+
queries: [],
387+
query_count: 0,
388+
days_analyzed: days,
389+
error: resolved.error,
390+
}
391+
}
392+
393+
const { warehouse: whName, type: whType } = resolved
394+
const bqRegion = whType === "bigquery" ? bqRegionFor(whName) : undefined
361395

362396
const built = buildExpensiveSql(whType, days, limit, bqRegion)
363397
if (!built) {
@@ -366,12 +400,12 @@ export async function getExpensiveQueries(params: ExpensiveQueriesParams): Promi
366400
queries: [],
367401
query_count: 0,
368402
days_analyzed: days,
369-
error: `Expensive query analysis is not available for ${whType} warehouses.`,
403+
error: `Internal error: expensive-query SQL template missing for ${whType}.`,
370404
}
371405
}
372406

373407
try {
374-
const connector = await Registry.get(params.warehouse)
408+
const connector = await Registry.get(whName)
375409
const result = await connector.execute(built.sql, limit, built.binds)
376410
const queries = rowsToRecords(result)
377411

@@ -387,7 +421,7 @@ export async function getExpensiveQueries(params: ExpensiveQueriesParams): Promi
387421
queries: [],
388422
query_count: 0,
389423
days_analyzed: days,
390-
error: String(e),
424+
error: e instanceof Error ? e.message : String(e),
391425
}
392426
}
393427
}

‎packages/opencode/src/altimate/native/finops/query-history.ts‎

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,18 @@
66

77
import * as Registry from "../connections/registry"
88
import { bqRegionFor, interpolateBqRegion, sanitizeBqRegion } from "./bq-utils"
9+
import { resolveFinopsWarehouse } from "./warehouse-resolver"
910
import type { QueryHistoryParams, QueryHistoryResult } from "../types"
1011

12+
const QUERY_HISTORY_SUPPORTED_TYPES = [
13+
"snowflake",
14+
"postgres",
15+
"postgresql",
16+
"bigquery",
17+
"databricks",
18+
"clickhouse",
19+
] as const
20+
1121
// ---------------------------------------------------------------------------
1222
// SQL templates
1323
// ---------------------------------------------------------------------------
@@ -141,12 +151,6 @@ LIMIT __LIMIT__
141151
// Helpers
142152
// ---------------------------------------------------------------------------
143153

144-
function getWhType(warehouse: string): string {
145-
const warehouses = Registry.list().warehouses
146-
const wh = warehouses.find((w) => w.name === warehouse)
147-
return wh?.type || "unknown"
148-
}
149-
150154
function buildHistoryQuery(
151155
whType: string,
152156
days: number,
@@ -210,23 +214,38 @@ function rowsToRecords(result: { columns: string[]; rows: any[][] }): Record<str
210214
// ---------------------------------------------------------------------------
211215

212216
export async function getQueryHistory(params: QueryHistoryParams): Promise<QueryHistoryResult> {
213-
const whType = getWhType(params.warehouse)
214217
const days = params.days ?? 7
215218
const limit = params.limit ?? 100
216-
const bqRegion = whType === "bigquery" ? bqRegionFor(params.warehouse) : undefined
219+
220+
const resolved = resolveFinopsWarehouse({
221+
requested: params.warehouse,
222+
supportedTypes: QUERY_HISTORY_SUPPORTED_TYPES,
223+
operationName: "Query history",
224+
})
225+
if (resolved.kind === "error") {
226+
return {
227+
success: false,
228+
queries: [],
229+
summary: {},
230+
error: resolved.error,
231+
}
232+
}
233+
234+
const { warehouse: whName, type: whType } = resolved
235+
const bqRegion = whType === "bigquery" ? bqRegionFor(whName) : undefined
217236

218237
const built = buildHistoryQuery(whType, days, limit, params.user, params.warehouse_filter, bqRegion)
219238
if (!built) {
220239
return {
221240
success: false,
222241
queries: [],
223242
summary: {},
224-
error: `Query history is not available for ${whType} warehouses.`,
243+
error: `Internal error: query history SQL template missing for ${whType}.`,
225244
}
226245
}
227246

228247
try {
229-
const connector = await Registry.get(params.warehouse)
248+
const connector = await Registry.get(whName)
230249
const result = await connector.execute(built.sql, limit, built.binds)
231250
const queries = rowsToRecords(result)
232251

@@ -261,7 +280,7 @@ export async function getQueryHistory(params: QueryHistoryParams): Promise<Query
261280
success: false,
262281
queries: [],
263282
summary: {},
264-
error: String(e),
283+
error: e instanceof Error ? e.message : String(e),
265284
}
266285
}
267286
}
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
/**
2+
* Shared warehouse resolution for finops.* handlers.
3+
*
4+
* The finops tools (analyze_credits, query_history, etc.) all need to map a
5+
* caller-supplied warehouse name to a configured connection and validate that
6+
* its driver type supports the requested operation. Before this helper, each
7+
* handler returned `{ success: false, error: "Credit analysis is not available
8+
* for unknown warehouses." }` when the warehouse was missing or unknown —
9+
* which the LLM cannot fix because the error doesn't say which warehouses are
10+
* available or how to add one.
11+
*
12+
* Telemetry (memory/telemetry-analysis-2026-05-21.md) showed `finops_*` tools
13+
* at 100% error rate. The dominant failure mode was the LLM passing an
14+
* unconfigured warehouse name and getting a dead-end response. This helper
15+
* fixes both: it falls back to the first compatible warehouse when none is
16+
* specified, and produces actionable errors when resolution fails.
17+
*/
18+
19+
import * as Registry from "../connections/registry"
20+
21+
export type FinopsWarehouseResolution =
22+
| { kind: "ok"; warehouse: string; type: string; autoPicked: boolean }
23+
| { kind: "error"; error: string }
24+
25+
export interface ResolveOptions {
26+
/** Caller-supplied warehouse name. May be empty/undefined. */
27+
requested?: string
28+
/** Driver types this finops operation supports (e.g. ["snowflake", "bigquery", "databricks"]). */
29+
supportedTypes: readonly string[]
30+
/** Operation name for error messages (e.g. "Credit analysis"). */
31+
operationName: string
32+
}
33+
34+
/**
35+
* Resolve a warehouse for a finops operation.
36+
*
37+
* Resolution order:
38+
* 1. If `requested` is provided and configured AND its type is supported -> ok.
39+
* 2. If `requested` is provided but not configured -> error listing available.
40+
* 3. If `requested` is provided and configured but the type is unsupported -> error.
41+
* 4. If `requested` is not provided -> auto-pick first warehouse with a supported type.
42+
* 5. If no warehouses are configured at all -> error pointing at warehouse_add.
43+
*/
44+
export function resolveFinopsWarehouse(opts: ResolveOptions): FinopsWarehouseResolution {
45+
const { requested, supportedTypes, operationName } = opts
46+
const all = Registry.list().warehouses
47+
const supportedList = supportedTypes.join(", ")
48+
49+
if (all.length === 0) {
50+
return {
51+
kind: "error",
52+
error:
53+
`${operationName} requires a configured warehouse, but none are set up. ` +
54+
`Add one with the warehouse_add tool, or via your altimate-code config. ` +
55+
`Supported types for this operation: ${supportedList}.`,
56+
}
57+
}
58+
59+
if (requested && requested.trim() !== "") {
60+
const match = all.find((w) => w.name === requested)
61+
if (!match) {
62+
const availableNames = all.map((w) => w.name).join(", ")
63+
return {
64+
kind: "error",
65+
error:
66+
`Warehouse ${JSON.stringify(requested)} is not configured. ` +
67+
`Available warehouses: ${availableNames}. ` +
68+
`Pass one of those as the 'warehouse' parameter, or omit it to use the default.`,
69+
}
70+
}
71+
if (!supportedTypes.includes(match.type)) {
72+
const compatible = all.filter((w) => supportedTypes.includes(w.type)).map((w) => w.name)
73+
const hint =
74+
compatible.length > 0
75+
? `Try one of: ${compatible.join(", ")}.`
76+
: `Add a warehouse of one of these types: ${supportedList}.`
77+
return {
78+
kind: "error",
79+
error: `${operationName} is not available for ${match.type} warehouses. ${hint}`,
80+
}
81+
}
82+
return { kind: "ok", warehouse: match.name, type: match.type, autoPicked: false }
83+
}
84+
85+
// No requested warehouse — auto-pick first compatible.
86+
const compatible = all.find((w) => supportedTypes.includes(w.type))
87+
if (!compatible) {
88+
const availableTypes = Array.from(new Set(all.map((w) => w.type))).join(", ") || "(none)"
89+
return {
90+
kind: "error",
91+
error:
92+
`${operationName} is not supported by any of your configured warehouses ` +
93+
`(${availableTypes}). Supported types: ${supportedList}. ` +
94+
`Add a compatible warehouse with the warehouse_add tool.`,
95+
}
96+
}
97+
return { kind: "ok", warehouse: compatible.name, type: compatible.type, autoPicked: true }
98+
}

‎packages/opencode/src/altimate/native/types.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -522,7 +522,8 @@ export interface SqlAutocompleteResult {
522522
// --- FinOps: Query History ---
523523

524524
export interface QueryHistoryParams {
525-
warehouse: string
525+
/** Warehouse connection name. If omitted, the first compatible warehouse is auto-picked. */
526+
warehouse?: string
526527
days?: number
527528
limit?: number
528529
user?: string
@@ -540,7 +541,8 @@ export interface QueryHistoryResult {
540541
// --- FinOps: Credit Analysis ---
541542

542543
export interface CreditAnalysisParams {
543-
warehouse: string
544+
/** Warehouse connection name. If omitted, the first compatible warehouse is auto-picked. */
545+
warehouse?: string
544546
days?: number
545547
limit?: number
546548
warehouse_filter?: string
@@ -559,7 +561,8 @@ export interface CreditAnalysisResult {
559561
// --- FinOps: Expensive Queries ---
560562

561563
export interface ExpensiveQueriesParams {
562-
warehouse: string
564+
/** Warehouse connection name. If omitted, the first compatible warehouse is auto-picked. */
565+
warehouse?: string
563566
days?: number
564567
limit?: number
565568
}

‎packages/opencode/src/altimate/tools/finops-analyze-credits.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,14 @@ function formatCreditsAnalysis(
6363

6464
export const FinopsAnalyzeCreditsTool = Tool.define("finops_analyze_credits", {
6565
description:
66-
"Analyze Snowflake credit consumption — daily breakdown by warehouse, total credits, and cost optimization recommendations. Requires ACCOUNT_USAGE access.",
66+
"Analyze Snowflake/BigQuery/Databricks credit consumption — daily breakdown by warehouse, total credits, and cost optimization recommendations. Requires ACCOUNT_USAGE (Snowflake) / INFORMATION_SCHEMA.JOBS (BigQuery) / system.billing.usage (Databricks) access.",
6767
parameters: z.object({
68-
warehouse: z.string().describe("Warehouse connection name"),
68+
warehouse: z
69+
.string()
70+
.optional()
71+
.describe(
72+
"Warehouse connection name. Optional — if omitted, the first configured Snowflake/BigQuery/Databricks warehouse is used.",
73+
),
6974
days: z.number().optional().default(30).describe("Days of history to analyze"),
7075
limit: z.number().optional().default(50).describe("Max daily records"),
7176
warehouse_filter: z.string().optional().describe("Filter to a specific Snowflake warehouse"),

‎packages/opencode/src/altimate/tools/finops-query-history.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,14 @@ function formatQueryHistory(summary: Record<string, unknown>, queries: unknown[]
4545

4646
export const FinopsQueryHistoryTool = Tool.define("finops_query_history", {
4747
description:
48-
"Fetch recent query execution history from a warehouse. Shows query text, execution time, bytes scanned, and status. Snowflake: reads from QUERY_HISTORY. PostgreSQL: reads from pg_stat_statements.",
48+
"Fetch recent query execution history from a warehouse. Shows query text, execution time, bytes scanned, and status. Snowflake: reads from QUERY_HISTORY. PostgreSQL: reads from pg_stat_statements. Also supports BigQuery, Databricks, ClickHouse.",
4949
parameters: z.object({
50-
warehouse: z.string().describe("Warehouse connection name"),
50+
warehouse: z
51+
.string()
52+
.optional()
53+
.describe(
54+
"Warehouse connection name. Optional — if omitted, the first configured compatible warehouse is used.",
55+
),
5156
days: z.number().optional().default(7).describe("How many days of history to fetch"),
5257
limit: z.number().optional().default(100).describe("Maximum number of queries to return"),
5358
user: z.string().optional().describe("Filter to a specific user (Snowflake only)"),

0 commit comments

Comments
 (0)