@@ -88,20 +88,32 @@ export interface WorkspaceFallback {
8888 * snapshot only — the same reachability-filtered projection the awareness section
8989 * uses, so this never names a tool the caller's agent cannot call.
9090 */
91- export async function workspaceFallbacks ( sessionID : string , supportedTypes : readonly string [ ] ) : Promise < WorkspaceFallback [ ] > {
91+ /** What the failure path learns about the workspace, in one read. */
92+ export type FallbackLookup =
93+ | { state : "current" ; fallbacks : WorkspaceFallback [ ] }
94+ | { state : "relinked" | "unreadable" }
95+
96+ /**
97+ * The workspace-served execute tools for the types a FinOps operation supports, if the
98+ * session is bound to a workspace that serves any. Reads the session's precedence
99+ * snapshot only — the same reachability-filtered projection the awareness section
100+ * uses, so this never names a tool the caller's agent cannot call — and re-validates
101+ * the snapshot once, as `check()` does before a redirect: a note naming a workspace
102+ * the project has since left would send the model to that workspace's engine.
103+ */
104+ export async function workspaceFallbacks ( sessionID : string , supportedTypes : readonly string [ ] ) : Promise < FallbackLookup > {
92105 const precedence = Precedence . forSession ( sessionID )
93- if ( ! precedence ?. enabled ) return [ ]
94- const served = Precedence . servedInventory ( precedence ) . flatMap ( ( { type, served } ) => {
106+ if ( ! precedence ?. enabled ) return { state : "current" , fallbacks : [ ] }
107+ const fallbacks = Precedence . servedInventory ( precedence ) . flatMap ( ( { type, served } ) => {
95108 if ( ! supportedTypes . includes ( type ) ) return [ ]
96109 const execute = served . find ( ( row ) => row . capability === "sql_execute" )
97110 return execute
98111 ? [ { workspaceName : precedence . workspaceName , workspaceId : precedence . workspaceId , type, modelKey : execute . modelKey } ]
99112 : [ ]
100113 } )
101- if ( served . length === 0 ) return [ ]
102- // Same re-validation `check()` does before a redirect: a note naming a workspace the
103- // project has since left would send the model to that workspace's engine.
104- return ( await Precedence . snapshotState ( precedence ) ) === "current" ? served : [ ]
114+ if ( fallbacks . length === 0 ) return { state : "current" , fallbacks }
115+ const state = await Precedence . snapshotState ( precedence )
116+ return state === "current" ? { state, fallbacks } : { state }
105117}
106118
107119/** The sentence appended to a FinOps failure, or nothing when the workspace serves
@@ -117,10 +129,16 @@ export function workspaceFallbackNote(operation: FinopsOperation, fallbacks: Wor
117129 return source ? `for ${ type } , query ${ source } with \`${ modelKey } \`` : `for ${ type } , use \`${ modelKey } \``
118130 } )
119131 . join ( "; " )
132+ // The snapshot does not carry a BigQuery integration's location, and the engine
133+ // runs what it is given: the placeholder has to be explained, not left to be sent.
134+ const region = fallbacks . some ( ( f ) => f . type === "bigquery" && SOURCE [ operation ] . bigquery )
135+ ? " Replace `<location>` with the BigQuery connection's location (for example `region-us`, `region-eu`); " +
136+ "if it is unknown, ask the engine for the connection's details first — the view is not reachable unqualified."
137+ : ""
120138 return (
121139 `This tool only uses warehouse connections configured on this machine, and workspace ${ label } ` +
122140 `serves ${ fallbacks . map ( ( f ) => f . type ) . join ( ", " ) } through its integration engine instead. ` +
123- `Run the same analysis through the workspace: ${ routes } .`
141+ `Run the same analysis through the workspace: ${ routes } .${ region } `
124142 )
125143}
126144
@@ -129,7 +147,13 @@ export function workspaceFallbackNote(operation: FinopsOperation, fallbacks: Wor
129147 * materialised) says nothing: that is the plain local failure. Uncertainty must say so
130148 * (the precedence module's first claim), so the failure is marked `undetermined` and
131149 * says the workspace could not be consulted — mirroring `check()`'s own cases. */
132- async function undeterminedNote ( sessionID : string ) : Promise < string | undefined > {
150+ function undeterminedNote ( sessionID : string , lookup : FallbackLookup ) : string | undefined {
151+ if ( lookup . state === "unreadable" ) {
152+ return "The workspace link could not be read while this call ran, so whether the workspace serves this connection type is unknown."
153+ }
154+ if ( lookup . state === "relinked" ) {
155+ return "The workspace binding changed while this call ran, so the previous routing decision no longer applies."
156+ }
133157 const precedence = Precedence . forSession ( sessionID )
134158 // No snapshot at all is the same unknown `check()` reports: a caller that never
135159 // resolved tools, or an entry evicted between resolution and this call.
@@ -143,13 +167,7 @@ async function undeterminedNote(sessionID: string): Promise<string | undefined>
143167 "(no routing decision was available), so no workspace alternative is offered here."
144168 )
145169 }
146- if ( ! precedence . enabled ) return undefined
147- // Enabled, but the link changed or could not be read while this call ran.
148- const state = await Precedence . snapshotState ( precedence )
149- if ( state === "current" ) return undefined
150- return state === "unreadable"
151- ? "The workspace link could not be read while this call ran, so whether the workspace serves this connection type is unknown."
152- : "The project was re-linked while this call ran, so the previous routing decision no longer applies."
170+ return undefined
153171}
154172
155173/**
@@ -164,16 +182,16 @@ export async function withWorkspaceFallback<T extends { metadata: Record<string,
164182 supportedTypes : readonly string [ ] ,
165183 result : T ,
166184) : Promise < T > {
167- const fallbacks = await workspaceFallbacks ( sessionID , supportedTypes )
168- const note = workspaceFallbackNote ( operation , fallbacks )
169- if ( note ) {
185+ const lookup = await workspaceFallbacks ( sessionID , supportedTypes )
186+ const note = lookup . state === "current" ? workspaceFallbackNote ( operation , lookup . fallbacks ) : undefined
187+ if ( note && lookup . state === "current" ) {
170188 return {
171189 ...result ,
172- metadata : { ...result . metadata , workspace_fallback : fallbacks . map ( ( f ) => f . modelKey ) } ,
190+ metadata : { ...result . metadata , workspace_fallback : lookup . fallbacks . map ( ( f ) => f . modelKey ) } ,
173191 output : `${ result . output } \n\n${ note } ` ,
174192 }
175193 }
176- const undetermined = await undeterminedNote ( sessionID )
194+ const undetermined = undeterminedNote ( sessionID , lookup )
177195 if ( ! undetermined ) return result
178196 return {
179197 ...result ,
0 commit comments