FarisZR · FarisZR · Mar 6, 2026 · Mar 6, 2026 · Mar 6, 2026 · coderabbitai
diff --git a/README.md b/README.md
@@ -8,6 +8,7 @@ Multi-account GitHub Copilot load balancing for OpenCode. Routes requests across
 - Hybrid load-balancing with cooldowns and fallback
 - Per-request account attribution (toast, log, header)
 - Model availability cache with lazy detection
+- Automatic same-request fallback when a model is only available on some accounts
 
 ## Install
 
@@ -55,6 +56,12 @@ Select **Manage Accounts** from the login menu to:
 
 You can add multiple GitHub.com or Enterprise accounts by running `opencode auth login` and selecting the appropriate login method. The plugin will load-balance requests across all enabled accounts that support the requested model.
 
+### Model-Aware Fallback
+
+When a model is available on only some accounts, the plugin still tries the currently selected account first. If GitHub Copilot responds that the model is unavailable on that account, the plugin marks that account as unsupported for that model, retries the same request against another eligible account, and sticks to the working account for follow-up requests.
+
+For agent requests, the toast/log message explains why the plugin stayed on the fallback account.
+
 ## Configuration
 
 Create `~/.config/opencode/copilot-multi.json` or `.opencode/copilot-multi.json`:

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -22,20 +22,21 @@ A custom `fetch` implementation injected into the OpenCode auth hook.
 - **Interception**: It parses the request body to identify the model ID.
 - **Routing**: It calls the Account Manager to select an account and updates the `Authorization` header with that account's access token.
 - **Retries**: If a request fails with a rate limit, it automatically tries a different eligible account (if available).
+- **Model Fallback**: If Copilot says a model is unavailable on the chosen account, it marks that account as unsupported for that model and retries the same request on another eligible account.
 - **Token Refresh**: Automatically handles OAuth token refreshing before making requests.
 
 ### 3. Model Availability Cache (`src/models/availability.ts`)
 
 Tracks which models are supported by which accounts.
 
-- **Lazy Detection**: If an account returns a 404/400 indicating a model is not found, that model is marked as unsupported for that specific account.
+- **Lazy Detection**: If an account returns a 404/400 indicating a model is not available there, that model is marked as unsupported for that specific account.
 - **Filtering**: Future requests for that model will skip the unsupported account.
 
 ### 4. Observability (`src/observe/usage.ts`)
 
 Provides feedback on account usage.
 
-- **Toasts**: Shows a transient UI notification when an agent call is made, identifying the account label.
+- **Toasts**: Shows a transient UI notification when an agent call is made, identifying the account label and fallback reason when the plugin has to stay on a different account.
 - **Structured Logs**: Emits DEBUG level logs via the OpenCode TUI logging system, including the model ID and selection reason.
 - **Headers**: Optionally attaches `x-opencode-copilot-account` to outgoing requests for external debugging.
 

diff --git a/src/accounts/manager.ts b/src/accounts/manager.ts
@@ -118,13 +118,32 @@ export class CopilotAccountManager {
   async markModelUnsupported(id: string, model: string) {
     const account = this.accounts.find((item) => item.id === id);
     if (!account) return;
-    account.models = Array.isArray(account.models)
-      ? account.models.filter((item) => item !== model)
-      : [];
+    if (Array.isArray(account.models)) {
+      account.models = account.models.filter((item) => item !== model);
+    }
     this.availability.markUnsupported(account, model);
     await this.persist();
   }
 
+  isAccountEligible(
+    account: CopilotAccount,
+    modelId: string,
+    host: string,
+    excludedAccountIds: Set<string> = new Set()
+  ) {
+    if (excludedAccountIds.has(account.id)) return false;
+    if (!account.enabled) return false;
+    if (account.host !== host) return false;
+    if (account.cooldownUntil && account.cooldownUntil > Date.now()) return false;
+    if (this.availability.isUnsupported(account, modelId)) return false;
+
+    const cachedModels = this.availability.get(account);
+    const models = cachedModels ?? account.models ?? null;
+    if (!models || models.length === 0) return true;
+
+    return models.includes(modelId);
+  }
+
   async markFailure(id: string, cooldownMs: number) {
     const account = this.accounts.find((item) => item.id === id);
     if (!account) return;
@@ -167,15 +186,13 @@ export class CopilotAccountManager {
     };
   }
 
-  selectAccount(modelId: string, host: string): AccountSelection | null {
+  selectAccount(
+    modelId: string,
+    host: string,
+    excludedAccountIds: Set<string> = new Set()
+  ): AccountSelection | null {
     const eligible = this.accounts.filter((account) => {
-      if (!account.enabled) return false;
-      if (account.host !== host) return false;
-      if (account.cooldownUntil && account.cooldownUntil > Date.now()) return false;
-      const cached = this.availability.get(account);
-      const models = cached ?? account.models;
-      if (!models || models.length === 0) return true;
-      return models.includes(modelId);
+      return this.isAccountEligible(account, modelId, host, excludedAccountIds);
     });
 
     if (eligible.length === 0) return null;

diff --git a/src/fetch/copilot-fetch.ts b/src/fetch/copilot-fetch.ts
@@ -105,7 +105,8 @@ function sanitizeCopilotBody(body?: string): string | undefined {
 
 function getHeaderValue(headers: HeadersInit | undefined, key: string): string | undefined {
   if (!headers) return undefined;
-  if (headers instanceof Headers) return headers.get(key) ?? headers.get(key.toLowerCase()) ?? undefined;
+  if (headers instanceof Headers)
+    return headers.get(key) ?? headers.get(key.toLowerCase()) ?? undefined;
   if (Array.isArray(headers)) {
     const found = headers.find(([name]) => name.toLowerCase() === key.toLowerCase());
     return found ? found[1] : undefined;
@@ -121,20 +122,6 @@ function getInitiator(headers: HeadersInit | undefined): Initiator {
   return undefined;
 }
 
-function isAccountEligible(
-  account: { enabled: boolean; host: string; cooldownUntil?: number; models?: string[] },
-  modelId: string,
-  host: string,
-) {
-  if (!account.enabled) return false;
-  if (account.host !== host) return false;
-  if (account.cooldownUntil && account.cooldownUntil > Date.now()) return false;
-  if (Array.isArray(account.models) && account.models.length > 0) {
-    return account.models.includes(modelId);
-  }
-  return true;
-}
-
 function buildHeaders(base: HeadersInit | undefined, auth: string, parsed: ParsedRequest) {
   const headers = new Headers(base);
   headers.set('authorization', `Bearer ${auth}`);
@@ -160,6 +147,34 @@ function getRetryAfter(response: Response, fallback: number) {
   return fallback;
 }
 
+function isModelUnavailableBody(bodyText: string, modelId: string) {
+  const normalized = bodyText.toLowerCase();
+  const mentionsModel =
+    normalized.includes('model') ||
+    (modelId !== 'unknown' && normalized.includes(modelId.toLowerCase()));
+
+  if (!mentionsModel) return false;
+
+  return [
+    'not found',
+    'does not exist',
+    'not available',
+    'not supported',
+    'unsupported',
+    'no access to model',
+    'access to this model',
+  ].some((phrase) => normalized.includes(phrase));
+}
+
+async function isModelUnavailableResponse(response: Response, modelId: string) {
+  if (response.status !== 400 && response.status !== 404) return false;
+  const bodyText = await response
+    .clone()
+    .text()
+    .catch(() => '');
+  return isModelUnavailableBody(bodyText, modelId);
+}
+
 async function refreshToken(host: string, refresh: string) {
   const domain = host === 'github.com' ? 'github.com' : host;
   const response = await fetch(`https://${domain}/login/oauth/access_token`, {
@@ -203,105 +218,150 @@ export function createCopilotFetch({ config, manager, notifier }: FetchDeps) {
     const now = Date.now();
     const lock = lockByHost.get(host);
     const agentRecentlyActive = Boolean(
-      lock?.lastAgentAt && now - lock.lastAgentAt < AGENT_IDLE_TIMEOUT_MS,
+      lock?.lastAgentAt && now - lock.lastAgentAt < AGENT_IDLE_TIMEOUT_MS
     );
+    const attemptedAccountIds = new Set<string>();
+    const resolvedParsed = { ...parsed, isAgent };
+
+    const updateHostLock = (accountId: string) => {
+      const previous = lockByHost.get(host);
+      lockByHost.set(host, {
+        accountId,
+        lastAgentAt: isAgent ? Date.now() : (previous?.lastAgentAt ?? 0),
+      });
+    };
+
+    const prepareSelection = async (
+      selection: NonNullable<ReturnType<typeof manager.selectAccount>>
+    ) => {
+      updateHostLock(selection.account.id);
+
+      if (selection.account.expires > 0 && selection.account.expires < Date.now()) {
+        const refreshed = await refreshToken(host, selection.account.refresh);
+        if (refreshed) {
+          await manager.updateAccountTokens(
+            selection.account.id,
+            refreshed.access,
+            refreshed.refresh,
+            refreshed.expires
+          );
+          selection.account.access = refreshed.access;
+          selection.account.refresh = refreshed.refresh;
+          selection.account.expires = refreshed.expires;
+        }
+      }
+
+      return selection;
+    };
+
+    const buildFallbackMessage = (
+      nextAccountLabel: string,
+      previousAccountLabel: string,
+      message: string
+    ) => {
+      return `Copilot: sticking to ${nextAccountLabel} for ${modelId}; ${previousAccountLabel} ${message}`;
+    };
+
+    const selectFallback = (
+      previousSelection: NonNullable<ReturnType<typeof manager.selectAccount>>,
+      message: string
+    ) => {
+      const fallback = manager.selectAccount(modelId, host, attemptedAccountIds);
+      if (!fallback) return null;
+      return {
+        fallback,
+        message: buildFallbackMessage(
+          fallback.account.label,
+          previousSelection.account.label,
+          message
+        ),
+      };
+    };
 
     let selection = null;
     if (lock && (isAgent || agentRecentlyActive)) {
-      const locked = manager
-        .listAccounts()
-        .find((account) => account.id === lock.accountId && isAccountEligible(account, modelId, host));
+      const locked = manager.listAccounts().find((account) => {
+        return account.id === lock.accountId && manager.isAccountEligible(account, modelId, host);
+      });
       if (locked) {
         selection = { account: locked, index: 0, reason: 'sticky' as const };
       }
     }
 
     if (!selection) {
-      selection = manager.selectAccount(modelId, host);
+      selection = manager.selectAccount(modelId, host, attemptedAccountIds);
     }
     if (!selection) {
       throw new Error(`No eligible Copilot accounts available for ${modelId}`);
     }
 
-    lockByHost.set(host, {
-      accountId: selection.account.id,
-      lastAgentAt: isAgent ? now : lock?.lastAgentAt ?? 0,
-    });
-
-    if (selection.account.expires > 0 && selection.account.expires < Date.now()) {
-      const refreshed = await refreshToken(host, selection.account.refresh);
-      if (refreshed) {
-        await manager.updateAccountTokens(
-          selection.account.id,
-          refreshed.access,
-          refreshed.refresh,
-          refreshed.expires,
-        );
-        selection.account.access = refreshed.access;
-        selection.account.refresh = refreshed.refresh;
-        selection.account.expires = refreshed.expires;
+    let notificationMessage: string | undefined;
+
+    for (;;) {
+      attemptedAccountIds.add(selection.account.id);
+      const preparedSelection = await prepareSelection(selection);
+      const headers = buildHeaders(init?.headers, preparedSelection.account.access, resolvedParsed);
+      const sanitizedBody = sanitizeCopilotBody(init?.body);
+      const response = await fetch(request, {
+        ...init,
+        body: sanitizedBody,
+        headers,
+      });
+
+      if (await isModelUnavailableResponse(response, modelId)) {
+        await manager.markModelUnsupported(preparedSelection.account.id, modelId);
+        log.warn('model unavailable on account', {
+          account: preparedSelection.account.label,
+          modelId,
+        });
+
+        const next = selectFallback(preparedSelection, 'does not support that model');
+        if (!next) return response;
+        selection = next.fallback;
+        notificationMessage = next.message;
+        continue;
       }
-    }
 
-    if (isAgent) {
-      await manager.notifySelection(selection, modelId);
-    }
-    const resolvedParsed = { ...parsed, isAgent };
-    const headers = buildHeaders(init?.headers, selection.account.access, resolvedParsed);
-
-    const sanitizedBody = sanitizeCopilotBody(init?.body);
-    const response = await fetch(request, {
-      ...init,
-      body: sanitizedBody,
-      headers,
-    });
-
-    if (response.status === 404 || response.status === 400) {
-      const bodyText = await response
-        .clone()
-        .text()
-        .catch(() => '');
-      if (
-        bodyText.toLowerCase().includes('model') &&
-        bodyText.toLowerCase().includes('not found')
-      ) {
-        await manager.markModelUnsupported(selection.account.id, modelId);
+      if (response.status === 401 || response.status === 403) {
+        await manager.markFailure(preparedSelection.account.id, config.rateLimit.defaultBackoffMs);
+        log.warn('auth failure detected', { account: preparedSelection.account.label, modelId });
+
+        const next = selectFallback(preparedSelection, 'had an auth failure');
+        if (!next) return response;
+        selection = next.fallback;
+        notificationMessage = next.message;
+        continue;
       }
-    }
 
-    if (response.status === 401 || response.status === 403) {
-      await manager.markFailure(selection.account.id, config.rateLimit.defaultBackoffMs);
-      log.warn('auth failure detected', { account: selection.account.label, modelId });
-      const fallback = manager.selectAccount(modelId, host);
-      if (!fallback) return response;
-      await notifier.accountSelected(fallback.account, modelId, 'fallback');
-      lockByHost.set(host, {
-        accountId: fallback.account.id,
-        lastAgentAt: isAgent ? Date.now() : lockByHost.get(host)?.lastAgentAt ?? 0,
-      });
-      const retryHeaders = buildHeaders(init?.headers, fallback.account.access, resolvedParsed);
-      return fetch(request, { ...init, headers: retryHeaders });
-    }
+      if (response.status === 429 || response.status === 503) {
+        const backoff = getRetryAfter(response, config.rateLimit.defaultBackoffMs);
+        await manager.markFailure(
+          preparedSelection.account.id,
+          Math.min(backoff, config.rateLimit.maxBackoffMs)
+        );
+        log.warn('rate limit detected', { account: preparedSelection.account.label, modelId });
 
-    if (response.status === 429 || response.status === 503) {
-      const backoff = getRetryAfter(response, config.rateLimit.defaultBackoffMs);
-      await manager.markFailure(
-        selection.account.id,
-        Math.min(backoff, config.rateLimit.maxBackoffMs),
-      );
-      log.warn('rate limit detected', { account: selection.account.label, modelId });
-      const fallback = manager.selectAccount(modelId, host);
-      if (!fallback) return response;
-      await notifier.accountSelected(fallback.account, modelId, 'fallback');
-      lockByHost.set(host, {
-        accountId: fallback.account.id,
-        lastAgentAt: isAgent ? Date.now() : lockByHost.get(host)?.lastAgentAt ?? 0,
-      });
-      const retryHeaders = buildHeaders(init?.headers, fallback.account.access, resolvedParsed);
-      return fetch(request, { ...init, headers: retryHeaders });
-    }
+        const next = selectFallback(preparedSelection, 'hit a cooldown-worthy rate limit');
+        if (!next) return response;
+        selection = next.fallback;
+        notificationMessage = next.message;
+        continue;
+      }
 
-    await manager.markSuccess(selection.account.id);
-    return response;
+      await manager.markSuccess(preparedSelection.account.id);
+      if (isAgent) {
+        if (notificationMessage) {
+          await notifier.accountSelected(
+            preparedSelection.account,
+            modelId,
+            'fallback',
+            notificationMessage
+          );
+        } else {
+          await manager.notifySelection(preparedSelection, modelId);
+        }
+      }
+      return response;
+    }
   };
 }