refactor(zoo-gateway): split error classification from UX, extract callback fan-out

Address review feedback on PR #347:

- zoo-gateway.ts: split surfaceGatewayApiError into a pure
  classifyGatewayApiError (error -> action) plus a thin UX layer that
  switches on the action. The classifier is exported and covered by
  focused unit tests, so the status/code -> action mapping no longer
  needs the VS Code notification mocks to verify.
- handleUri.ts: extract the per-instance token propagation loop into a
  propagateZooGatewayCallback helper, keeping the /auth-callback case
  focused on routing. Behaviour (sequential read-modify-write, per
  instance error isolation) is unchanged.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: JamesRobert20

src/activate/handleUri.ts

@@ -4,6 +4,34 @@ import { getRouterUnavailableSignInMessage } from "../core/config/routerRemoval"
 import { ClineProvider } from "../core/webview/ClineProvider"
 import { handleAuthCallback as handleZooCodeAuthCallback, setZooCodeUserInfo } from "../services/zoo-code-auth"
 
+/**
+ * Persist the Zoo Code session token to every active provider instance.
+ *
+ * The profile settings write (handleZooCodeCallback) must run on any active
+ * instance — not just the visible one — so the zoo-gateway zooSessionToken is
+ * persisted even when the sidebar/panel is hidden at callback time.
+ *
+ * Run sequentially (NOT Promise.all): each ClineProvider's handleZooCodeCallback
+ * does a read-modify-write on the same backing provider settings store
+ * (listConfig → getProfile → saveConfig / upsertProviderProfile). Fanning out
+ * concurrently across N instances can interleave reads/writes and clobber
+ * updates. Serialization is cheap (at most a handful of instances) and avoids
+ * the race.
+ */
+async function propagateZooGatewayCallback(token: string): Promise<void> {
+	const allInstances = ClineProvider.getAllInstances()
+	for (const instance of allInstances) {
+		try {
+			await instance.handleZooCodeCallback(token)
+		} catch (error) {
+			console.error(
+				"Failed to persist Zoo Gateway token for a provider instance:",
+				error instanceof Error ? error.message : error,
+			)
+		}
+	}
+}
+
 export const handleUri = async (uri: vscode.Uri) => {
 	const path = uri.path
 	const query = new URLSearchParams(uri.query.replace(/\+/g, "%2B"))
@@ -50,28 +78,7 @@ export const handleUri = async (uri: vscode.Uri) => {
 						email,
 						image,
 					})
-					// Write the token to all active provider instances regardless of visibility.
-					// The profile settings write (handleZooCodeCallback) must run on any active
-					// instance — not just the visible one — so the zoo-gateway zooSessionToken
-					// is persisted even when the sidebar/panel is hidden at callback time.
-					//
-					// Run sequentially (NOT Promise.all): each ClineProvider's
-					// handleZooCodeCallback does a read-modify-write on the same backing
-					// provider settings store (listConfig → getProfile → saveConfig /
-					// upsertProviderProfile). Fanning out concurrently across N instances
-					// can interleave reads/writes and clobber updates. Serialization here
-					// is cheap (at most a handful of instances) and avoids the race.
-					const allInstances = ClineProvider.getAllInstances()
-					for (const instance of allInstances) {
-						try {
-							await instance.handleZooCodeCallback(token)
-						} catch (error) {
-							console.error(
-								"Failed to persist Zoo Gateway token for a provider instance:",
-								error instanceof Error ? error.message : error,
-							)
-						}
-					}
+					await propagateZooGatewayCallback(token)
 				}
 			}
 			break

src/api/providers/__tests__/zoo-gateway.spec.ts

@@ -19,7 +19,7 @@ import OpenAI from "openai"
 
 import { zooGatewayDefaultModelId, ZOO_GATEWAY_DEFAULT_TEMPERATURE } from "@roo-code/types"
 
-import { ZooGatewayHandler } from "../zoo-gateway"
+import { ZooGatewayHandler, classifyGatewayApiError } from "../zoo-gateway"
 import { ApiHandlerOptions } from "../../../shared/api"
 import { Package } from "../../../shared/package"
 import { clearZooCodeToken } from "../../../services/zoo-code-auth"
@@ -410,6 +410,39 @@ describe("ZooGatewayHandler", () => {
 		})
 	})
 
+	describe("classifyGatewayApiError", () => {
+		it("returns sign_in on 401", () => {
+			expect(classifyGatewayApiError(makeApiError(401))).toEqual({ kind: "sign_in" })
+		})
+
+		it("returns add_credits (not budget) on 402", () => {
+			expect(classifyGatewayApiError(makeApiError(402))).toEqual({ kind: "add_credits", budgetExceeded: false })
+		})
+
+		it("returns add_credits with budgetExceeded on 429 budget codes", () => {
+			expect(classifyGatewayApiError(makeApiError(429, { code: "monthly_budget_exceeded" }))).toEqual({
+				kind: "add_credits",
+				budgetExceeded: true,
+			})
+			expect(classifyGatewayApiError(makeApiError(429, { code: "daily_budget_exceeded" }))).toEqual({
+				kind: "add_credits",
+				budgetExceeded: true,
+			})
+		})
+
+		it("returns none on 429 without a budget code", () => {
+			expect(classifyGatewayApiError(makeApiError(429, { code: "rate_limited" }))).toEqual({ kind: "none" })
+		})
+
+		it("returns contact_support on 403", () => {
+			expect(classifyGatewayApiError(makeApiError(403))).toEqual({ kind: "contact_support" })
+		})
+
+		it("returns none for errors without an HTTP status", () => {
+			expect(classifyGatewayApiError(new Error("network down"))).toEqual({ kind: "none" })
+		})
+	})
+
 	describe("surfaceGatewayApiError", () => {
 		it("clears the cached token and offers re-sign-in on 401", async () => {
 			const handler = new ZooGatewayHandler(mockOptions)

src/api/providers/zoo-gateway.ts

@@ -46,46 +46,75 @@ function buildZooCodeSignInUrl(): string {
 	return `${getZooCodeBaseUrl()}/dashboard/connect?device=${device}&editor=${editor}&version=${Package.version}&callback_uri=${callbackUri}`
 }
 
-// Caller must always rethrow — this only surfaces UX, never swallows.
-async function surfaceGatewayApiError(error: unknown): Promise<void> {
+type ZooGatewayApiErrorAction =
+	| { kind: "sign_in" }
+	| { kind: "add_credits"; budgetExceeded: boolean }
+	| { kind: "contact_support" }
+	| { kind: "none" }
+
+// Pure mapping from an API error to the UX action it warrants. No side effects,
+// so this is trivial to unit test independently of the VS Code notification flow.
+// Exported for unit tests.
+export function classifyGatewayApiError(error: unknown): ZooGatewayApiErrorAction {
 	const status = getApiErrorStatus(error)
-	if (status === undefined) return
+	if (status === undefined) return { kind: "none" }
 	const code = getApiErrorCode(error)
 
 	if (status === 401) {
-		// Wipe before sign-in so the callback rebinds against an empty slot.
-		await clearZooCodeToken()
-		const action = await vscode.window.showErrorMessage(
-			t("common:zooAuth.errors.session_expired"),
-			t("common:zooAuth.buttons.sign_in"),
-		)
-		if (action) {
-			void vscode.env.openExternal(vscode.Uri.parse(buildZooCodeSignInUrl()))
-		}
-		return
+		return { kind: "sign_in" }
 	}
 
 	const isBudgetExceeded = status === 429 && (code === "monthly_budget_exceeded" || code === "daily_budget_exceeded")
 	if (status === 402 || isBudgetExceeded) {
-		const message = isBudgetExceeded
-			? t("common:zooAuth.errors.budget_exceeded")
-			: t("common:zooAuth.errors.out_of_credits")
-		const action = await vscode.window.showErrorMessage(message, t("common:zooAuth.buttons.add_credits"))
-		if (action) {
-			void vscode.env.openExternal(vscode.Uri.parse(`${getZooCodeBaseUrl()}/dashboard/credits`))
-		}
-		return
+		return { kind: "add_credits", budgetExceeded: isBudgetExceeded }
 	}
 
 	if (status === 403) {
-		const action = await vscode.window.showErrorMessage(
-			t("common:zooAuth.errors.account_unavailable"),
-			t("common:zooAuth.buttons.contact_support"),
-		)
-		if (action) {
-			void vscode.env.openExternal(vscode.Uri.parse(`${getZooCodeBaseUrl()}/support`))
+		return { kind: "contact_support" }
+	}
+
+	return { kind: "none" }
+}
+
+// Caller must always rethrow — this only surfaces UX, never swallows.
+async function surfaceGatewayApiError(error: unknown): Promise<void> {
+	const action = classifyGatewayApiError(error)
+
+	switch (action.kind) {
+		case "sign_in": {
+			// Wipe before sign-in so the callback rebinds against an empty slot.
+			await clearZooCodeToken()
+			const clicked = await vscode.window.showErrorMessage(
+				t("common:zooAuth.errors.session_expired"),
+				t("common:zooAuth.buttons.sign_in"),
+			)
+			if (clicked) {
+				void vscode.env.openExternal(vscode.Uri.parse(buildZooCodeSignInUrl()))
+			}
+			return
+		}
+		case "add_credits": {
+			const message = action.budgetExceeded
+				? t("common:zooAuth.errors.budget_exceeded")
+				: t("common:zooAuth.errors.out_of_credits")
+			const clicked = await vscode.window.showErrorMessage(message, t("common:zooAuth.buttons.add_credits"))
+			if (clicked) {
+				void vscode.env.openExternal(vscode.Uri.parse(`${getZooCodeBaseUrl()}/dashboard/credits`))
+			}
+			return
+		}
+		case "contact_support": {
+			const clicked = await vscode.window.showErrorMessage(
+				t("common:zooAuth.errors.account_unavailable"),
+				t("common:zooAuth.buttons.contact_support"),
+			)
+			if (clicked) {
+				void vscode.env.openExternal(vscode.Uri.parse(`${getZooCodeBaseUrl()}/support`))
+			}
+			return
 		}
-		return
+		default:
+			return
 	}
 }