|
| 1 | +// altimate_change - new file |
| 2 | +// |
| 3 | +// The FinOps tools run their SQL through connections configured on this machine — |
| 4 | +// `~/.altimate-code/connections.json`, the project's, `ALTIMATE_CODE_CONN_*` — and |
| 5 | +// nothing else. A project bound to a workspace whose warehouse credentials live in the |
| 6 | +// workspace has none of those, so every `finops_*` call fails, and the workspace's own |
| 7 | +// cost skills steer the model to exactly these tools first. A bare `FAILED` there sends |
| 8 | +// the model through four failures before it thinks of the engine tool that works. |
| 9 | +// |
| 10 | +// This is the reason and the way out, appended to every FinOps failure when the |
| 11 | +// session's bound workspace serves a type the tool supports. It is advice, not a |
| 12 | +// redirect: the FinOps SQL is not routed through the engine (that is the option the |
| 13 | +// issue prefers and a larger change — the engine's result shape is not a contract the |
| 14 | +// native handlers can parse), so the model is told which engine tool to run the same |
| 15 | +// usage-table query through instead. |
| 16 | +import * as Precedence from "../workspace/precedence" |
| 17 | + |
| 18 | +/** Where each served type keeps the usage data the FinOps tools read, so the model |
| 19 | + * can write the query the tool would have run. Keyed by canonical local driver type, |
| 20 | + * the key `servedInventory` reports. */ |
| 21 | +const USAGE_SOURCE: Readonly<Record<string, string>> = { |
| 22 | + snowflake: |
| 23 | + "the `SNOWFLAKE.ACCOUNT_USAGE` views (`QUERY_HISTORY`, `WAREHOUSE_METERING_HISTORY`, " + |
| 24 | + "`WAREHOUSE_LOAD_HISTORY`, `GRANTS_TO_ROLES`, `GRANTS_TO_USERS`)", |
| 25 | + bigquery: "`INFORMATION_SCHEMA.JOBS_BY_PROJECT`", |
| 26 | + databricks: "`system.query.history` and `system.billing.usage`", |
| 27 | + postgres: "`pg_stat_statements`", |
| 28 | +} |
| 29 | + |
| 30 | +export interface WorkspaceFallback { |
| 31 | + workspaceName: string |
| 32 | + /** Canonical local driver type the workspace serves, e.g. `snowflake`. */ |
| 33 | + type: string |
| 34 | + /** The engine execute tool the model should call, e.g. |
| 35 | + * `datamate_snowflake_execute_database_query`. */ |
| 36 | + modelKey: string |
| 37 | +} |
| 38 | + |
| 39 | +/** |
| 40 | + * The workspace-served execute tools for the types a FinOps operation supports, if |
| 41 | + * the session is bound to a workspace that serves any. Reads the session's precedence |
| 42 | + * snapshot only — the same reachability-filtered projection the awareness section |
| 43 | + * uses, so this never names a tool the caller's agent cannot call. |
| 44 | + */ |
| 45 | +export function workspaceFallbacks(sessionID: string, supportedTypes: readonly string[]): WorkspaceFallback[] { |
| 46 | + const precedence = Precedence.forSession(sessionID) |
| 47 | + if (!precedence?.enabled) return [] |
| 48 | + return Precedence.servedInventory(precedence).flatMap(({ type, served }) => { |
| 49 | + if (!supportedTypes.includes(type)) return [] |
| 50 | + const execute = served.find((row) => row.capability === "sql_execute") |
| 51 | + return execute ? [{ workspaceName: precedence.workspaceName, type, modelKey: execute.modelKey }] : [] |
| 52 | + }) |
| 53 | +} |
| 54 | + |
| 55 | +/** The sentence appended to a FinOps failure, or nothing when the workspace serves |
| 56 | + * none of the operation's types — then the local error stands on its own. */ |
| 57 | +export function workspaceFallbackNote(fallbacks: WorkspaceFallback[]): string | undefined { |
| 58 | + if (fallbacks.length === 0) return undefined |
| 59 | + const name = fallbacks[0].workspaceName |
| 60 | + const routes = fallbacks |
| 61 | + .map(({ type, modelKey }) => { |
| 62 | + const source = USAGE_SOURCE[type] |
| 63 | + return source ? `for ${type}, query ${source} with \`${modelKey}\`` : `for ${type}, use \`${modelKey}\`` |
| 64 | + }) |
| 65 | + .join("; ") |
| 66 | + return ( |
| 67 | + `This tool only uses warehouse connections configured on this machine, and workspace "${name}" ` + |
| 68 | + `serves ${fallbacks.map((f) => f.type).join(", ")} through its integration engine instead. ` + |
| 69 | + `Run the same analysis through the workspace: ${routes}.` |
| 70 | + ) |
| 71 | +} |
| 72 | + |
| 73 | +/** |
| 74 | + * Attach the workspace note to a failed FinOps result. The failure text is kept — the |
| 75 | + * local reason may still be the one to fix — and the engine tool is stamped on the |
| 76 | + * metadata so telemetry can tell a failure the model could route around from a dead |
| 77 | + * end. |
| 78 | + */ |
| 79 | +export function withWorkspaceFallback<T extends { metadata: Record<string, unknown>; output: string }>( |
| 80 | + sessionID: string, |
| 81 | + supportedTypes: readonly string[], |
| 82 | + result: T, |
| 83 | +): T { |
| 84 | + const fallbacks = workspaceFallbacks(sessionID, supportedTypes) |
| 85 | + const note = workspaceFallbackNote(fallbacks) |
| 86 | + if (!note) return result |
| 87 | + return { |
| 88 | + ...result, |
| 89 | + metadata: { ...result.metadata, workspace_fallback: fallbacks.map((f) => f.modelKey) }, |
| 90 | + output: `${result.output}\n\n${note}`, |
| 91 | + } |
| 92 | +} |
0 commit comments