From 3916f0637ae80cc8339e7e9f087037f63ca15088 Mon Sep 17 00:00:00 2001 From: Shreyas Telkar Date: Tue, 17 Nov 2026 15:25:49 -0800 Subject: [PATCH 001/101] feat: `/savings`: Databricks savings check over altimate-code (1.8.0) - `hooks/features/savings.tsx`: `/savings [connection]` runs altimate-code's `finops_databricks_savings` tool through `runTool` with `ALTIMATE_TELEMETRY_DISABLED=true` and draws the findings, evidence and monthly ranges in a pane beside the chat; nothing enters the conversation - the plugin holds no detector logic: altimate-code measures the facts and altimate-core decides the savings - refusals are explained with the step that fixes them: no altimate-code, an altimate-code without the tool, no Databricks connection, a connection that is not a SQL warehouse, a refused system-table query - `runTool`/`runAltimate` take an optional environment for one CLI run - registered in `features/index.ts` like the other features; README, PRIVACY, SKILL tool table, CHANGELOG, version 1.8.0 Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 2 +- PRIVACY.md | 4 + .../altimate-code/.claude-plugin/plugin.json | 2 +- plugins/altimate-code/CHANGELOG.md | 6 + plugins/altimate-code/README.md | 8 + plugins/altimate-code/hooks/altimate-cli.ts | 13 +- plugins/altimate-code/hooks/features/index.ts | 31 +- .../hooks/features/savings.test.tsx | 307 ++++++++++++++++ .../altimate-code/hooks/features/savings.tsx | 327 ++++++++++++++++++ .../skills/altimate-code/SKILL.md | 1 + plugins/altimate-code/types/index.d.ts | 20 ++ 11 files changed, 713 insertions(+), 8 deletions(-) create mode 100644 plugins/altimate-code/hooks/features/savings.test.tsx create mode 100644 plugins/altimate-code/hooks/features/savings.tsx diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 2d8c3e81..2622c44e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,7 +7,7 @@ }, "metadata": { "description": "Altimate's Claude Code plugin — data tools through the altimate-code MCP server, or the model-free CLI where MCP is disallowed, plus delegation of long dbt jobs to the CLI agent.", - "version": "1.7.0" + "version": "1.8.0" }, "plugins": [ { diff --git a/PRIVACY.md b/PRIVACY.md index dec75bd0..f44e6f8a 100644 --- a/PRIVACY.md +++ b/PRIVACY.md @@ -112,6 +112,10 @@ Each event carries the step and the Claude Code session id (`claude:`) only: **Bring Your Own Key (BYOK):** if you configure your own provider (Anthropic, OpenAI, Bedrock, Azure OpenAI, Ollama, and others), your prompts go directly from your machine to that provider. Altimate is not in that delegation path; workspace service requests still go to Altimate. +## The Databricks savings check + +`/savings` runs altimate-code's `finops_databricks_savings` tool on your machine, with your own Databricks connection. It reads usage from your workspace's system tables and decides the savings locally. The plugin runs it with telemetry turned off, so no usage event about the run is sent to Altimate, and the findings are shown in a pane, not added to the conversation. When Claude runs the same tool itself, its answer is a tool result like any other and reaches your model provider. + ## Usage telemetry The altimate-code CLI emits anonymous product usage telemetry: event names, tool categories, token counts, timing, and error types. Telemetry never includes your code, queries, credentials, file paths, or prompt content, and error messages pass through a redaction layer (API keys, emails, and internal hostnames are masked). Events are keyed to an anonymous machine ID — a random UUID generated on first run and stored at `~/.altimate/machine-id`, not tied to your hardware or identity. For logged-in users, the email identifier is SHA-256 hashed before sending. The full event list is published in the [Telemetry reference](https://docs.altimate.sh/reference/telemetry/). diff --git a/plugins/altimate-code/.claude-plugin/plugin.json b/plugins/altimate-code/.claude-plugin/plugin.json index 5a71365a..e1b1dfc8 100644 --- a/plugins/altimate-code/.claude-plugin/plugin.json +++ b/plugins/altimate-code/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "altimate-code", "displayName": "Altimate Code", - "version": "1.7.0", + "version": "1.8.0", "description": "Gives Claude Code altimate-code's model-free data tools (column-level lineage, impact analysis, PII detection, data-diff, FinOps, query equivalence, dialect translation, warehouse queries) through its MCP server, or through `altimate tool run` when MCP servers are not allowed, with delegation to the altimate-code agent for long dbt jobs, access to a linked Altimate workspace's knowledge, and the workspace's team rules in each session.", "author": { "name": "AltimateAI", diff --git a/plugins/altimate-code/CHANGELOG.md b/plugins/altimate-code/CHANGELOG.md index fc00ea30..f4b9c2f0 100644 --- a/plugins/altimate-code/CHANGELOG.md +++ b/plugins/altimate-code/CHANGELOG.md @@ -2,6 +2,12 @@ All notable changes to this plugin will be documented in this file. +## [1.8.0] — 2026-11-17 + +### Added +- `/savings [connection]`: a Databricks SQL warehouse savings check beside the chat. It runs altimate-code's `finops_databricks_savings` tool (Migrate Classic/Pro to Serverless and Over-Sized Warehouse) with your own Databricks connection and telemetry off, and shows each finding with its evidence and a monthly range at list price, each warehouse counted once. Needs an altimate-code release with that tool; with an older one the pane says to update. It is a feature under `hooks/features/` like the others. +- `runTool` and `runAltimate` take an optional environment for one CLI run. + ## [1.7.0] — 2026-11-17 ### Added diff --git a/plugins/altimate-code/README.md b/plugins/altimate-code/README.md index e2594739..fcd04052 100644 --- a/plugins/altimate-code/README.md +++ b/plugins/altimate-code/README.md @@ -134,6 +134,14 @@ Rule drafting uses altimate-code's own model (sign in to the Altimate LLM Gatewa - **The per-turn hooks never block**: they hand off to altimate-code in the background. Session start makes one bounded synchronous call (at most 15 seconds). All of them run only in a linked folder (or below it), as recorded in altimate-code's link cache in your own state directory: nothing in the repository turns them on. - **`ALTIMATE_LEARN=0`** turns all of it off: the hooks start nothing. +## Databricks savings check + +`/savings [connection]` checks a Databricks workspace's SQL warehouses for savings with two of Altimate's Databricks checks: Classic or Pro warehouses that would cost less as serverless, and warehouses larger than their queries need. A pane beside the chat shows each finding with what it rests on (idle share, cores used, spill and queueing, DBUs and cost) and a monthly range at list price, each warehouse counted once at its largest saving. + +- **What runs.** altimate-code's `finops_databricks_savings` tool, with your own altimate-code Databricks connection (the first one, or the one named). It reads seven days of Databricks system tables (`system.billing`, `system.compute`, `system.query`) on the connection's SQL warehouse, which Databricks starts if it is stopped. Nothing is written. +- **What it needs.** An altimate-code with that tool, and a Databricks connection whose `http_path` is a SQL warehouse (`/sql/1.0/warehouses/`) with an access token that can read those system tables. +- **What leaves your machine.** The plugin runs the tool with `ALTIMATE_TELEMETRY_DISABLED=true`, so neither altimate-code nor altimate-core sends usage telemetry for it. The findings stay in the pane: they do not enter the conversation. Claude can also run the same tool itself (it is listed for it); its answer then reaches your model provider like any other tool result. + ## Settings The plugin has five settings, shown when you enable it (`userConfig` in `.claude-plugin/plugin.json`). None is used yet: the features that read them are not in this version, so changing one changes nothing. The table says what each will control. diff --git a/plugins/altimate-code/hooks/altimate-cli.ts b/plugins/altimate-code/hooks/altimate-cli.ts index 6fb0d6b4..adee9e75 100644 --- a/plugins/altimate-code/hooks/altimate-cli.ts +++ b/plugins/altimate-code/hooks/altimate-cli.ts @@ -15,12 +15,15 @@ const CLI_NAMES = ['altimate', 'altimate-code'] as const // reruns a command that may have taken effect. export const MISSING_BINARY = /ENOENT|not found|no such file|(cannot|could not|failed to) (start|spawn|run)/i -/** Runs the altimate CLI under the first name that is installed; 90 s unless the caller says otherwise. */ -export async function runAltimate($: EngineInterface, args: string[], timeoutMs = 90_000) { +/** + * Runs the altimate CLI under the first name that is installed; 90 s unless the caller says otherwise. + * `env` is set over the session's environment for this run only. + */ +export async function runAltimate($: EngineInterface, args: string[], timeoutMs = 90_000, env?: Record) { let lastError: unknown = null for (const bin of CLI_NAMES) { try { - return await $.process.run([bin, ...args], { timeoutMs }) + return await $.process.run([bin, ...args], env ? { timeoutMs, env } : { timeoutMs }) } catch (error) { if (!MISSING_BINARY.test(String(error))) throw error lastError = error @@ -124,6 +127,8 @@ export type RunToolOptions = { * item 4), as the skill does before it adds `--allow-write`. */ write?: boolean + /** Variables set for a CLI run (`cliOnly`), over the session's environment. */ + env?: Record } /** @@ -174,7 +179,7 @@ export async function runTool($: EngineInterface, name: string, args: Record) { @@ -207,6 +224,7 @@ export async function featuresSessionStart($: EngineInterface, e: Args<'session. await attempt($, 'sqlGraph', 'sessionStart', () => sqlGraphSessionStart($, e)) await attempt($, 'docs', 'sessionStart', () => docsSessionStart($, e)) await attempt($, 'cteProfile', 'sessionStart', () => cteProfileSessionStart($, e)) + await attempt($, 'savings', 'sessionStart', () => savingsSessionStart($, e)) } export async function featuresTurnStart($: EngineInterface, e: Args<'turn.start'>) { @@ -219,6 +237,7 @@ export async function featuresTurnStart($: EngineInterface, e: Args<'turn.start' await attempt($, 'sqlGraph', 'turnStart', () => sqlGraphTurnStart($, e)) await attempt($, 'docs', 'turnStart', () => docsTurnStart($, e)) await attempt($, 'cteProfile', 'turnStart', () => cteProfileTurnStart($, e)) + await attempt($, 'savings', 'turnStart', () => savingsTurnStart($, e)) } export async function featuresTurnComplete($: EngineInterface, e: Args<'turn.complete'>, out: EventResult<'turn.complete'>) { @@ -231,6 +250,7 @@ export async function featuresTurnComplete($: EngineInterface, e: Args<'turn.com await attempt($, 'sqlGraph', 'turnComplete', () => sqlGraphTurnComplete($, e, out)) await attempt($, 'docs', 'turnComplete', () => docsTurnComplete($, e, out)) await attempt($, 'cteProfile', 'turnComplete', () => cteProfileTurnComplete($, e, out)) + await attempt($, 'savings', 'turnComplete', () => savingsTurnComplete($, e, out)) } export async function featuresSessionEnd($: EngineInterface, e: Args<'session.end'>) { @@ -243,6 +263,7 @@ export async function featuresSessionEnd($: EngineInterface, e: Args<'session.en await attempt($, 'sqlGraph', 'sessionEnd', () => sqlGraphSessionEnd($, e)) await attempt($, 'docs', 'sessionEnd', () => docsSessionEnd($, e)) await attempt($, 'cteProfile', 'sessionEnd', () => cteProfileSessionEnd($, e)) + await attempt($, 'savings', 'sessionEnd', () => savingsSessionEnd($, e)) } /** Each feature's band line, in order, with its id; a feature with nothing to say is left out. */ @@ -260,6 +281,7 @@ export async function featureBandLines($: EngineInterface, ui: BandUi): Promise< add('sqlGraph', await attempt($, 'sqlGraph', 'bandLine', () => sqlGraphBandLine($, ui))) add('docs', await attempt($, 'docs', 'bandLine', () => docsBandLine($, ui))) add('cteProfile', await attempt($, 'cteProfile', 'bandLine', () => cteProfileBandLine($, ui))) + add('savings', await attempt($, 'savings', 'bandLine', () => savingsBandLine($, ui))) return lines } @@ -278,6 +300,7 @@ export async function featuresBashRewrite($: EngineInterface, e: BashCall): Prom take(await attempt($, 'sqlGraph', 'bashRewrite', () => sqlGraphBashRewrite($, { ...e, command }))) take(await attempt($, 'docs', 'bashRewrite', () => docsBashRewrite($, { ...e, command }))) take(await attempt($, 'cteProfile', 'bashRewrite', () => cteProfileBashRewrite($, { ...e, command }))) + take(await attempt($, 'savings', 'bashRewrite', () => savingsBashRewrite($, { ...e, command }))) return command } @@ -296,6 +319,7 @@ export async function featuresBashGate($: EngineInterface, e: BashCall): Promise if (!gate) take(await attempt($, 'sqlGraph', 'bashGate', () => sqlGraphBashGate($, e))) if (!gate) take(await attempt($, 'docs', 'bashGate', () => docsBashGate($, e))) if (!gate) take(await attempt($, 'cteProfile', 'bashGate', () => cteProfileBashGate($, e))) + if (!gate) take(await attempt($, 'savings', 'bashGate', () => savingsBashGate($, e))) return gate } @@ -311,11 +335,12 @@ export async function featuresBashAfter($: EngineInterface, e: BashCall, result: addLines(lines, await attempt($, 'sqlGraph', 'bashAfter', () => sqlGraphBashAfter($, e, result))) addLines(lines, await attempt($, 'docs', 'bashAfter', () => docsBashAfter($, e, result))) addLines(lines, await attempt($, 'cteProfile', 'bashAfter', () => cteProfileBashAfter($, e, result))) + addLines(lines, await attempt($, 'savings', 'bashAfter', () => savingsBashAfter($, e, result))) return lines } /** Whether any feature's `editAfter` needs the file's text from before the edit. */ -export const EDIT_READS_BEFORE: boolean = runsEditReadsBefore || deferEditReadsBefore || toModelEditReadsBefore || commentsEditReadsBefore || costEditReadsBefore || healthEditReadsBefore || sqlGraphEditReadsBefore || docsEditReadsBefore || cteProfileEditReadsBefore +export const EDIT_READS_BEFORE: boolean = runsEditReadsBefore || deferEditReadsBefore || toModelEditReadsBefore || commentsEditReadsBefore || costEditReadsBefore || healthEditReadsBefore || sqlGraphEditReadsBefore || docsEditReadsBefore || cteProfileEditReadsBefore || savingsEditReadsBefore /** The context lines every feature adds after an edit landed. */ export async function featuresEditAfter($: EngineInterface, e: FileCall, result: ToolCallResult, file: EditedFile): Promise { @@ -329,6 +354,7 @@ export async function featuresEditAfter($: EngineInterface, e: FileCall, result: addLines(lines, await attempt($, 'sqlGraph', 'editAfter', () => sqlGraphEditAfter($, e, result, sqlGraphEditReadsBefore ? file : { path: file.path, before: null }))) addLines(lines, await attempt($, 'docs', 'editAfter', () => docsEditAfter($, e, result, docsEditReadsBefore ? file : { path: file.path, before: null }))) addLines(lines, await attempt($, 'cteProfile', 'editAfter', () => cteProfileEditAfter($, e, result, cteProfileEditReadsBefore ? file : { path: file.path, before: null }))) + addLines(lines, await attempt($, 'savings', 'editAfter', () => savingsEditAfter($, e, result, savingsEditReadsBefore ? file : { path: file.path, before: null }))) return lines } @@ -344,6 +370,7 @@ export async function featuresReadOrEditAfter($: EngineInterface, e: FileCall, r addLines(lines, await attempt($, 'sqlGraph', 'readOrEditAfter', () => sqlGraphReadOrEditAfter($, e, result, file))) addLines(lines, await attempt($, 'docs', 'readOrEditAfter', () => docsReadOrEditAfter($, e, result, file))) addLines(lines, await attempt($, 'cteProfile', 'readOrEditAfter', () => cteProfileReadOrEditAfter($, e, result, file))) + addLines(lines, await attempt($, 'savings', 'readOrEditAfter', () => savingsReadOrEditAfter($, e, result, file))) return lines } diff --git a/plugins/altimate-code/hooks/features/savings.test.tsx b/plugins/altimate-code/hooks/features/savings.test.tsx new file mode 100644 index 00000000..da2eabbd --- /dev/null +++ b/plugins/altimate-code/hooks/features/savings.test.tsx @@ -0,0 +1,307 @@ +import { expect, mock, test } from 'claude-code/testing' + +import { SIGNUP_URL, dollars, explain } from './savings' + +const ROOT = '/repo' + +const PANE = { + plugin: 'altimate-code', + component: 'Pane', + requestId: 'altimate-savings', + props: { title: 'Databricks savings', isFocused: true, bodyColumns: 96, placement: 'dock', scroll: { offset: 0, bodyRows: 60 }, view: {} }, +} as const + +// `altimate tool run finops_databricks_savings --args '{}' --json` on a live workspace for the seven +// days to 2026-11-17 06:00 UTC (warehouse ids replaced). +const ANSWER = { + status: 'ok', + title: 'Databricks Savings: $85.17–$106 a month on 1 warehouse(s)', + output: 'Databricks SQL warehouse savings, 5 warehouses checked, …', + metadata: { + success: true, + window: { start: '2026-11-10', end: '2026-11-17' }, + warehouse: 'dbxmega', + ran_on: 'wh-xs', + warehouses_checked: 5, + truncated: false, + report: { + lookback_days: 7, + findings: [ + { + check_id: 'wh_classic_pro_to_serverless', + title: 'Migrate Classic/Pro to Serverless', + warehouse_id: 'wh-classic', + warehouse_name: 'Classic', + severity: 'critical', + daily_min: 2.8389970568078615, + daily_max: 3.5487463210098267, + monthly_min: 85.16991170423584, + monthly_max: 106.4623896302948, + evidence: { + kind: 'serverless', + warehouse_type: 'CLASSIC', + warehouse_size: 'SMALL', + idle_ratio: 0.9523043043299816, + wall_clock_uptime_hours: 10.828888888888889, + total_query_count: 2988, + price_per_dbu: 0.22, + serverless_price_per_dbu: 0.7, + current_dbu_cost: 29.28557470666667, + projected_serverless_dbu_cost: 4.44435045959788, + wasted_cost: 24.841224247068787, + }, + }, + { + check_id: 'wh_oversized', + title: 'Over-Sized Warehouse', + warehouse_id: 'wh-classic', + warehouse_name: 'Classic', + severity: 'medium', + daily_min: 1.1156410285714287, + daily_max: 1.9523717999999999, + monthly_min: 33.46923085714286, + monthly_max: 58.57115399999999, + evidence: { + kind: 'over_sized', + current_size: 'SMALL', + recommended_size: '2X_SMALL', + available_cores: 32, + p99_utilization: 0.10725396430349142, + parallelism_query_count: 2669, + no_spill_query_pct: 1, + no_queue_query_pct: 1, + current_dbu_per_hour: 12, + recommended_dbu_per_hour: 4, + total_cost: 29.285577, + wasted_cost: 19.523718, + }, + }, + ], + total: { monthly_min: 85.16991170423584, monthly_max: 106.4623896302948, warehouses: 1 }, + }, + }, +} + +/** The tool's failure as `tool run --json` prints it: `status: ok`, the reason in the metadata. */ +function failure(error: string) { + return { status: 'ok', title: 'Databricks Savings: FAILED', output: `The Databricks savings check failed: ${error}`, metadata: { success: false, error } } +} + +type Options = { + answer?: unknown + /** `tool run` exits 1 with this answer, as altimate-code does for a tool it does not have. */ + error?: unknown + missingCli?: boolean + hold?: Promise + isPlaced?: boolean + now?: number +} + +async function start($: any, on: any, options: Options = {}) { + const clock = mock.clock(on, { now: options.now ?? Date.parse('2026-11-17T10:00:00Z') }) + const runs: { argv: string[]; env: Record | undefined }[] = [] + const toasts: string[] = [] + on('command.register', () => ({ value: { command: 'savings' } })) + on('turn.start', (_: unknown, e: { turnId: string }) => ({ turnId: e.turnId })) + on('session.end', () => ({ sessionId: 'test' })) + on('turn.complete', (_: unknown, e: { answer: string }) => ({ text: e.answer })) + on('session.start', (_: unknown, e: { cwd: string }) => ({ cwd: e.cwd })) + on('session.root', () => ({ value: ROOT })) + on('ui.open', () => ({ value: options.isPlaced === false ? { isPlaced: false } : {} })) + on('ui.close', () => ({ value: undefined })) + on('ui.log', () => ({ value: undefined })) + on('ui.toast', (_: unknown, e: { text: string }) => { + toasts.push(e.text) + return { value: undefined } + }) + on('ui.render', ($$: any, e: any) => { + const { Box } = $$.ui.resolve(e) + return + }) + on('fs.exists', () => ({ value: false })) + on('fs.read', () => ({ value: '' })) + on('tool.list', () => ({ value: [] })) + on('mcp.connect', () => ({ value: { isConnected: false, reason: 'not_connected', message: 'off' } })) + on('process.run', async (_: unknown, e: { argv: readonly string[]; init?: { env?: Record } }) => { + const [, command, , tool] = e.argv + // The other halves of the plugin ask the CLI for other things at session start. + if (command !== 'tool' || tool !== 'finops_databricks_savings') return { value: { exitCode: 1, stdout: '', stderr: 'not this test' } } + runs.push({ argv: [...e.argv], env: e.init?.env }) + if (options.missingCli) return { deny: 'spawn altimate ENOENT' } + if (options.hold) await options.hold + if (options.error) return { value: { exitCode: 1, stdout: JSON.stringify(options.error), stderr: '' } } + return { value: { exitCode: 0, stdout: JSON.stringify(options.answer ?? ANSWER), stderr: '' } } + }) + on('tool.call', () => ({ result: { ok: true } })) + await $.session.start({ cwd: ROOT, surface: 'terminal', isInteractive: true }) + await clock.settle() + return { clock, runs, toasts } +} + +const composer = { origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 200 } } + +async function savings($: any, args = '') { + return $.command.run({ command: 'savings', args, ...composer }) +} + +test('/savings runs the altimate-code tool once with telemetry off and draws its findings, on every surface', async ($, on) => { + const { clock, runs, toasts } = await start($, on) + const said = await savings($) + await clock.settle() + + expect(runs.length).toBe(1) + expect(runs[0]!.argv.slice(1)).toEqual(['tool', 'run', 'finops_databricks_savings', '--args', '{}', '--json']) + expect(runs[0]!.env).toEqual({ ALTIMATE_TELEMETRY_DISABLED: 'true' }) + // The reply in the conversation names no figure, warehouse or workspace: the findings stay in the pane. + expect(said.text).toContain('Nothing is sent to Altimate') + expect(said.text).not.toMatch(/\$|Classic|dbxmega/) + expect(toasts.at(-1)).toBe('Databricks savings check: $85.17–$106 a month on 1 SQL warehouse.') + + for (const surface of ['terminal', 'desktop'] as const) { + const ui = await $.ui.mount({ ...PANE, surface }) + expect(await ui.find({ type: 'Text', text: /^\$85\.17–\$106 a month$/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /^Classic · Migrate Classic\/Pro to Serverless · \$85\.17–\$106 a month$/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /^Classic · Over-Sized Warehouse · \$33\.47–\$58\.57 a month$/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /^CLASSIC SMALL warehouse, 95% idle over 10\.8 running hours \(2,988 queries\)$/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /^2X-SMALL is enough: 12 → 4 DBU an hour, on \$29\.29 spent over 7 days$/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /5 SQL warehouses · the 7 days to 2026-11-17 06:00 UTC · connection dbxmega/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /These were 2 of Altimate's 15 Databricks checks/ })).toBeDefined() + expect((await ui.find({ type: 'Link' }))?.props.href).toBe(SIGNUP_URL) + await ui.unmount() + } +}) + +test('/savings asks for that connection', async ($, on) => { + const { clock, runs } = await start($, on) + await savings($, 'prod_dbx') + await clock.settle() + expect(JSON.parse(runs[0]!.argv[5]!)).toEqual({ warehouse: 'prod_dbx' }) +}) + +test('an argument that is not a connection name never reaches the CLI', async ($, on) => { + const { clock, runs } = await start($, on) + for (const args of ['--host=https://evil.example', 'a b', '$(whoami)', '-p']) { + expect((await savings($, args)).text).toContain('is not a connection name') + } + await clock.settle() + expect(runs).toEqual([]) +}) + +test('an altimate-code without the tool says to update it', async ($, on) => { + // What altimate-code prints for a tool it does not have. + const error = { status: 'error', title: 'Unknown tool', output: 'Unknown tool: finops_databricks_savings. Run `altimate-code tool list` to see the available tools.', metadata: {} } + const { clock } = await start($, on, { error }) + await savings($) + await clock.settle() + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /^This altimate-code has no Databricks savings check\.$/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /altimate upgrade/ })).toBeDefined() + await ui.unmount() +}) + +test('with no Databricks connection the pane says how to add one, and gives no verdict', async ($, on) => { + const answer = failure( + 'The Databricks savings check requires a configured warehouse, but none are set up. Add one with the warehouse_add tool, or via your altimate-code config. Supported types for this operation: databricks.', + ) + const { clock, toasts } = await start($, on, { answer }) + await savings($) + await clock.settle() + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /^altimate-code has no Databricks connection\.$/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /connections\.json/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /No savings found|a month$/ })).toBeUndefined() + expect(toasts.filter(text => text.startsWith('Databricks savings check'))).toEqual([]) + await ui.unmount() +}) + +test('a refused query says what to ask an admin for, and is no verdict', async ($, on) => { + const answer = failure('[TABLE_OR_VIEW_NOT_FOUND] The table or view `system`.`compute`.`warehouse_events` cannot be found. SQLSTATE: 42P01') + const { clock } = await start($, on, { answer }) + await savings($) + await clock.settle() + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /^A query was refused: \[TABLE_OR_VIEW_NOT_FOUND\]/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /ask a workspace admin for SELECT/ })).toBeDefined() + expect(await ui.find({ type: 'Text', text: /No savings found/ })).toBeUndefined() + await ui.unmount() +}) + +test('without altimate-code the pane says how to install it', async ($, on) => { + const { clock } = await start($, on, { missingCli: true }) + await savings($) + await clock.settle() + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /^altimate-code is not installed\.$/ })).toBeDefined() + await ui.unmount() +}) + +test('checks that ran and found nothing say so, and still link to the rest', async ($, on) => { + const answer = { ...ANSWER, metadata: { ...ANSWER.metadata, report: { lookback_days: 7, findings: [], total: { monthly_min: 0, monthly_max: 0, warehouses: 0 } } } } + const { clock, toasts } = await start($, on, { answer }) + await savings($) + await clock.settle() + expect(toasts.at(-1)).toBe('Databricks savings check: no savings found on 5 SQL warehouses.') + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /^No savings found by these 2 checks\.$/ })).toBeDefined() + expect((await ui.find({ type: 'Link' }))?.props.href).toBe(SIGNUP_URL) + await ui.unmount() +}) + +test('a run still waiting when the session ends never writes its report', async ($, on) => { + let release = () => {} + const { clock, toasts } = await start($, on, { hold: new Promise(resolve => (release = resolve)) }) + await savings($) + await clock.settle() + await $.session.end({ reason: 'clear' } as any) + release() + await clock.settle() + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + expect(await ui.find({ type: 'Text', text: /a month/ })).toBeUndefined() + expect(await ui.find({ type: 'Text', text: /Run \/savings/ })).toBeDefined() + expect(toasts.filter(text => text.startsWith('Databricks savings check'))).toEqual([]) + await ui.unmount() +}) + +test('a second /savings while one runs does not start another', async ($, on) => { + let release = () => {} + const { clock, runs } = await start($, on, { hold: new Promise(resolve => (release = resolve)) }) + await savings($) + await clock.settle() + expect((await savings($)).text).toContain('already running') + release() + await clock.settle() + expect(runs.length).toBe(1) +}) + +test('a terminal too narrow for the pane says so, and the figure still arrives as a notice', async ($, on) => { + const { clock, toasts } = await start($, on, { isPlaced: false }) + expect((await savings($)).text).toContain('too narrow for the side pane') + await clock.settle() + expect(toasts.at(-1)).toContain('$85.17–$106 a month') +}) + +test('Run again checks the same connection again', async ($, on) => { + const { clock, runs } = await start($, on) + await savings($, 'prod_dbx') + await clock.settle() + const ui = await $.ui.mount({ ...PANE, surface: 'terminal' }) + await ui.press({ key: 'again' }) + await clock.settle() + expect(runs.map(one => JSON.parse(one.argv[5]!))).toEqual([{ warehouse: 'prod_dbx' }, { warehouse: 'prod_dbx' }]) + await ui.unmount() +}) + +test('each refusal altimate-code gives is explained in the person\'s terms', () => { + expect(explain('Warehouse "x" is not configured. Available warehouses: a, b. Pass one of those as the \'warehouse\' parameter, or omit it to use the default.').text).toBe( + 'Warehouse "x" is not configured. Available warehouses: a, b.', + ) + expect(explain('Connection "dbx" does not go through a SQL warehouse. Its http_path must name one').recovery).toContain('/sql/1.0/warehouses/') + expect(explain("This altimate-code build's altimate-core has no Databricks savings rules. Update altimate-code, then try again.").text).toContain('no Databricks savings check') + expect(explain('socket hang up').text).toBe('The savings check failed: socket hang up') +}) + +test('dollars are whole from $100 and to the cent below it', () => { + expect(dollars(106.46)).toBe('$106') + expect(dollars(85.1699)).toBe('$85.17') + expect(dollars(35142.9)).toBe('$35,143') +}) diff --git a/plugins/altimate-code/hooks/features/savings.tsx b/plugins/altimate-code/hooks/features/savings.tsx new file mode 100644 index 00000000..d4a2e529 --- /dev/null +++ b/plugins/altimate-code/hooks/features/savings.tsx @@ -0,0 +1,327 @@ +// Savings: /savings checks a Databricks workspace's SQL warehouses for savings with Altimate's rules. +// +// The check is altimate-code's `finops_databricks_savings` tool: it measures each warehouse's usage +// from Databricks system tables with the person's own altimate-code connection, and altimate-core +// decides what qualifies and what it saves. This feature only asks for it and draws the answer +// beside the chat, with telemetry off for that run, so nothing about the run reaches Altimate. +import { atom, read, update } from 'claude-code' +import type { Args, EngineInterface, EventResult, On, RenderElement, ToolCallResult } from 'claude-code' + +import type { SavingsView } from '../../types' +import { MISSING_BINARY, later, runTool } from '../altimate-cli' +import type { BashCall, ContextLines, EditedFile, FileCall } from '../tool-chain' +import type { BandUi, FeatureContext } from './index' + +const COMMAND = 'savings' +const PANE = 'altimate-savings' +const PANE_TITLE = 'Databricks savings' +const PANE_SIZE = { columns: 96, rows: 34 } +const TOOL = 'finops_databricks_savings' +export const SIGNUP_URL = 'https://app.myaltimate.com/register' +/** How many Databricks detectors Altimate's pipeline runs; the check runs two of them. */ +export const SAAS_CHECK_COUNT = 15 +const CHECK_COUNT = 2 +// The queries read seven days of system tables and may start the connection's SQL warehouse. +const RUN_BUDGET_MS = 5 * 60_000 +// Set for the tool's run only: altimate-code and altimate-core both read it. +const NO_TELEMETRY = { ALTIMATE_TELEMETRY_DISABLED: 'true' } + +// An altimate-code connection name; anything else could read as a CLI flag. +const CONNECTION_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/ + +const ADD_CONNECTION = + 'Add a Databricks connection to altimate-code (in ~/.altimate-code/connections.json: type "databricks", server_hostname, the http_path of a SQL warehouse and an access_token), then run /savings again.' + +const reportAtom = atom({ plugin: 'altimate-code', key: 'savingsReport' } as const, null as SavingsView | null, { shape: 'savings-view-1' }) +const busyAtom = atom({ plugin: 'altimate-code', key: 'savingsBusy' } as const, null as { label: string } | null) +const messageAtom = atom({ plugin: 'altimate-code', key: 'savingsMessage' } as const, null as { text: string; recovery: string } | null) + +// Each run takes a number; /clear, a resume or a reload moves it on, so a run still waiting on +// Databricks when the conversation changed never writes its report into the new one. +let generation = 0 +let lastConnection: string | null = null + +export function dollars(value: number): string { + const rounded = value >= 100 ? Math.round(value) : Math.round(value * 100) / 100 + const [whole, cents] = rounded.toFixed(value >= 100 ? 0 : 2).split('.') + return `$${whole!.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}${cents ? `.${cents}` : ''}` +} + +function range(min: number, max: number): string { + return dollars(min) === dollars(max) ? dollars(max) : `${dollars(min)}–${dollars(max)}` +} + +const percent = (share: unknown) => `${Math.round(Number(share) * 100)}%` +const size = (value: unknown) => String(value ?? '?').replace(/_/g, '-') +const count = (value: unknown) => Math.round(Number(value) || 0).toLocaleString('en-US') + +/** What a finding rests on, one short line each, from the measured values core returned. */ +export function evidenceLines(evidence: Record): string[] { + if (evidence.kind === 'serverless') { + return [ + `${evidence.warehouse_type} ${size(evidence.warehouse_size)} warehouse, ${percent(evidence.idle_ratio)} idle over ${Number(evidence.wall_clock_uptime_hours).toFixed(1)} running hours (${count(evidence.total_query_count)} queries)`, + `$${Number(evidence.current_dbu_cost).toFixed(2)} in DBUs over 7 days; serverless would bill $${Number(evidence.projected_serverless_dbu_cost).toFixed(2)} for the busy time alone`, + ] + } + return [ + `${size(evidence.current_size)} warehouse used at most ${(Number(evidence.p99_utilization) * 100).toFixed(1)}% of its cores (p99 over ${count(evidence.parallelism_query_count)} queries)`, + `${percent(evidence.no_spill_query_pct)} of queries never spilled to disk, ${percent(evidence.no_queue_query_pct)} never queued`, + `${size(evidence.recommended_size)} is enough: ${count(evidence.current_dbu_per_hour)} → ${count(evidence.recommended_dbu_per_hour)} DBU an hour, on $${Number(evidence.total_cost).toFixed(2)} spent over 7 days`, + ] +} + +type ToolReport = { + lookback_days: number + findings: { + title: string + warehouse_id: string + warehouse_name: string + monthly_min: number + monthly_max: number + evidence: Record + }[] + total: { monthly_min: number; monthly_max: number; warehouses: number } +} + +type ToolMetadata = { + success?: boolean + error?: string + window?: { start: string; end: string } + warehouse?: string + ran_on?: string + warehouses_checked?: number + report?: ToolReport +} + +/** The tool's answer as the pane draws it, or null when it is not a report. */ +export function toView(metadata: ToolMetadata | null): SavingsView | null { + const report = metadata?.report + if (!metadata?.success || !report || !Array.isArray(report.findings) || !metadata.window) return null + return { + connection: metadata.warehouse ?? null, + ranOn: metadata.ran_on ?? null, + window: metadata.window, + warehousesChecked: metadata.warehouses_checked ?? 0, + total: { min: report.total.monthly_min, max: report.total.monthly_max, warehouses: report.total.warehouses }, + findings: report.findings.map(one => ({ + title: one.title, + warehouseName: one.warehouse_name, + monthlyMin: one.monthly_min, + monthlyMax: one.monthly_max, + evidence: evidenceLines(one.evidence), + })), + } +} + +/** The refusal in the person's terms, with the step that fixes it. */ +export function explain(error: string): { text: string; recovery: string } { + if (/^Unknown tool: finops_databricks_savings/.test(error) || /has no Databricks savings rules/.test(error)) { + return { text: 'This altimate-code has no Databricks savings check.', recovery: 'Update altimate-code (`altimate upgrade`), then run /savings again.' } + } + if (/requires a configured warehouse|not supported by any of your configured warehouses/.test(error)) { + return { text: 'altimate-code has no Databricks connection.', recovery: ADD_CONNECTION } + } + if (/is not configured\. Available warehouses/.test(error)) { + return { text: error.replace(/ Pass one of those.*$/, ''), recovery: 'Run /savings with one of those names, or /savings to use the first Databricks connection.' } + } + if (/does not go through a SQL warehouse/.test(error)) { + return { text: 'The Databricks connection does not go through a SQL warehouse.', recovery: 'Set its http_path to a SQL warehouse (/sql/1.0/warehouses/), then run /savings again.' } + } + if (/TABLE_OR_VIEW_NOT_FOUND|PERMISSION_DENIED|INSUFFICIENT_PERMISSIONS/.test(error)) { + return { + text: `A query was refused: ${error.split('\n')[0]!.slice(0, 200)}`, + recovery: 'The check reads system.billing, system.compute and system.query: ask a workspace admin for SELECT on those schemas, then run /savings again.', + } + } + return { text: `The savings check failed: ${error.split('\n')[0]!.slice(0, 300)}`, recovery: 'Run /savings again; if it fails again, run the same check in a terminal: `altimate tool run finops_databricks_savings --args \'{}\'`.' } +} + +function summary(view: SavingsView): string { + if (view.total.warehouses === 0) return `Databricks savings check: no savings found on ${view.warehousesChecked} SQL warehouses.` + return `Databricks savings check: ${range(view.total.min, view.total.max)} a month on ${view.total.warehouses} SQL warehouse${view.total.warehouses === 1 ? '' : 's'}.` +} + +async function openPane($: EngineInterface) { + return $.ui.open({ id: PANE, title: PANE_TITLE, ...PANE_SIZE, focus: true, closeOnEscape: true }).catch(() => null) +} + +async function runCheck($: EngineInterface, connection: string | null) { + const mine = ++generation + const live = () => mine === generation + lastConnection = connection + try { + await update($, messageAtom, () => null) + const until = (await $.clock.now()) + RUN_BUDGET_MS + const result = await runTool($, TOOL, connection ? { warehouse: connection } : {}, { cliOnly: true, until, env: NO_TELEMETRY }) + if (!live()) return + const view = toView(result.metadata as ToolMetadata | null) + if (!view) { + const error = (result.metadata as ToolMetadata | null)?.error ?? result.text + await update($, messageAtom, () => explain(error || 'no answer')) + return + } + await update($, reportAtom, () => view) + $.ui.toast(summary(view)) + } catch (error) { + if (!live()) return + const missing = MISSING_BINARY.test(String(error)) + await update($, messageAtom, () => + missing + ? { text: 'altimate-code is not installed.', recovery: 'Install it (`npm install -g altimate-code`), add a Databricks connection, then run /savings again.' } + : explain(String(error)), + ) + } finally { + if (live()) await update($, busyAtom, () => null) + } +} + +/** Adds this feature's own hooks. */ +export function register(on: On, _context: FeatureContext) { + on('command.run', { command: COMMAND }, async ($, e) => { + const asked = e.args.trim() + if (asked && !CONNECTION_NAME.test(asked)) { + return { text: `"${asked}" is not a connection name. Run /savings, or /savings with an altimate-code Databricks connection.` } + } + if (await read($, busyAtom)) { + await openPane($) + return { text: 'The Databricks savings check is already running in the side pane.' } + } + await update($, busyAtom, () => ({ label: "Checking the workspace's SQL warehouses…" })) + const opened = await openPane($) + later($, () => runCheck($, asked || null)) + if (opened && opened.isPlaced === false) { + return { text: 'Running the Databricks savings check. The terminal is too narrow for the side pane, so the result comes as a notice; widen the window to see the details.' } + } + return { text: 'Running the Databricks savings check in the side pane: read-only queries on your own Databricks connection. Nothing is sent to Altimate.' } + }) + + on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => { + const { Box, Button, Link, Text } = $.ui.resolve(e) + const report = await read($, reportAtom) + const running = await read($, busyAtom) + const message = await read($, messageAtom) + const again = () => later($, () => update($, busyAtom, () => ({ label: "Checking the workspace's SQL warehouses…" })).then(() => runCheck($, lastConnection))) + const close = () => later($, () => $.ui.close({ id: PANE })) + const buttons = ( + +