replicas-engine 0.1.610 → 0.1.611

package/dist/src/index.js

@@ -60,6 +60,9 @@ var VALID_CODING_AGENT_PROVIDERS = VALID_AGENT_PROVIDERS.filter(
 function isValidAgentProvider(value) {
   return VALID_AGENT_PROVIDERS.some((p) => p === value);
 }
+function isValidCodingAgentProvider(value) {
+  return VALID_CODING_AGENT_PROVIDERS.some((provider) => provider === value);
+}
 var VALID_THINKING_LEVELS = ["low", "medium", "high", "xhigh", "max", "ultra", "ultracode"];
 var STANDARD_THINKING_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 var THINKING_LEVELS_BY_AGENT = {
@@ -86,6 +89,117 @@ function codexReasoningEffortForThinkingLevel(thinkingLevel) {
   return thinkingLevel ? CODEX_REASONING_EFFORT_BY_THINKING_LEVEL[thinkingLevel] : void 0;
 }
 
+// ../shared/src/agent-quota.ts
+var OUT_OF_CREDITS_PATTERNS = [
+  /credit balance is too low/,
+  /out.of.credits/,
+  /credits?.?(?:depleted|exhausted|remaining)/,
+  /insufficient credits/,
+  /insufficient_quota/
+];
+var RATE_LIMIT_PATTERNS = [
+  // Loose on purpose: providers word this as "rate limit", "rate_limit",
+  // "usageLimitExceeded" and so on, and these only ever run against error text.
+  /rate.?limit/,
+  /usage.?limit/,
+  /too many requests/,
+  /\bquota\b/
+];
+var HTTP_429_PATTERN = /(?:^|[^0-9])429(?:$|[^0-9])/;
+var HTTP_CONTEXT_PATTERN = /(api error|request|response|status|http)/;
+function detectAgentQuotaLimit(text) {
+  const normalized = text.toLowerCase();
+  if (!normalized) return null;
+  if (OUT_OF_CREDITS_PATTERNS.some((pattern) => pattern.test(normalized))) return "out_of_credits";
+  if (RATE_LIMIT_PATTERNS.some((pattern) => pattern.test(normalized))) return "rate_limit";
+  return HTTP_429_PATTERN.test(normalized) && HTTP_CONTEXT_PATTERN.test(normalized) ? "rate_limit" : null;
+}
+
+// ../shared/src/credentials/types.ts
+var CREDENTIAL_SCOPE = {
+  USER: "user",
+  ORG: "org"
+};
+var CREDENTIAL_SCOPES = Object.values(CREDENTIAL_SCOPE);
+var CREDENTIAL_SCOPE_PRIORITY = [CREDENTIAL_SCOPE.USER, CREDENTIAL_SCOPE.ORG];
+
+// ../shared/src/credentials/agents.ts
+var CREDENTIAL_METHOD = {
+  OAUTH: "oauth",
+  API_KEY: "api_key",
+  FOUNDRY: "foundry",
+  BEDROCK: "bedrock",
+  OPENCODE_GO: "opencode-go",
+  ASTER: "aster",
+  OPENROUTER: "openrouter"
+};
+var CREDENTIAL_TYPE = {
+  CLAUDE_OAUTH: "claude",
+  ANTHROPIC_API_KEY: "claude_anthropic_api_key",
+  CLAUDE_FOUNDRY: "claude_foundry",
+  CLAUDE_BEDROCK: "claude_bedrock",
+  CODEX_OAUTH: "codex",
+  OPENAI_API_KEY: "openai_api_key",
+  CODEX_FOUNDRY: "codex_foundry",
+  CURSOR_API_KEY: "cursor_api_key",
+  OPENCODE_GO_API_KEY: "opencode_go_api_key",
+  ASTER_API_KEY: "aster_api_key",
+  OPENROUTER_API_KEY: "openrouter_api_key"
+};
+var AGENT_CREDENTIAL_METHODS_IN_ORDER = {
+  [AGENT.CLAUDE]: [
+    { method: CREDENTIAL_METHOD.OAUTH, credentialType: CREDENTIAL_TYPE.CLAUDE_OAUTH },
+    { method: CREDENTIAL_METHOD.API_KEY, credentialType: CREDENTIAL_TYPE.ANTHROPIC_API_KEY },
+    { method: CREDENTIAL_METHOD.FOUNDRY, credentialType: CREDENTIAL_TYPE.CLAUDE_FOUNDRY },
+    { method: CREDENTIAL_METHOD.BEDROCK, credentialType: CREDENTIAL_TYPE.CLAUDE_BEDROCK }
+  ],
+  [AGENT.CODEX]: [
+    { method: CREDENTIAL_METHOD.OAUTH, credentialType: CREDENTIAL_TYPE.CODEX_OAUTH },
+    { method: CREDENTIAL_METHOD.API_KEY, credentialType: CREDENTIAL_TYPE.OPENAI_API_KEY },
+    { method: CREDENTIAL_METHOD.FOUNDRY, credentialType: CREDENTIAL_TYPE.CODEX_FOUNDRY }
+  ],
+  [AGENT.CURSOR]: [
+    { method: CREDENTIAL_METHOD.API_KEY, credentialType: CREDENTIAL_TYPE.CURSOR_API_KEY }
+  ],
+  [AGENT.OPENCODE]: [
+    { method: CREDENTIAL_METHOD.OPENCODE_GO, credentialType: CREDENTIAL_TYPE.OPENCODE_GO_API_KEY },
+    { method: CREDENTIAL_METHOD.ASTER, credentialType: CREDENTIAL_TYPE.ASTER_API_KEY },
+    { method: CREDENTIAL_METHOD.OPENROUTER, credentialType: CREDENTIAL_TYPE.OPENROUTER_API_KEY }
+  ],
+  [AGENT.PI]: [
+    { method: CREDENTIAL_METHOD.ASTER, credentialType: CREDENTIAL_TYPE.ASTER_API_KEY },
+    { method: CREDENTIAL_METHOD.OPENROUTER, credentialType: CREDENTIAL_TYPE.OPENROUTER_API_KEY }
+  ]
+};
+
+// ../shared/src/analytics/types.ts
+function isAgentChatActivityRecord(value) {
+  return isRecord(value) && typeof value.chatId === "string" && typeof value.provider === "string" && isValidAgentProvider(value.provider) && typeof value.model === "string" && (value.credentialMethod === void 0 || isAuthMethod(value.credentialMethod)) && (value.credentialScope === void 0 || isCredentialScope(value.credentialScope)) && value.credentialMethod === void 0 === (value.credentialScope === void 0) && (value.senderUserId === void 0 || typeof value.senderUserId === "string") && typeof value.occurredAt === "string";
+}
+function isAuthMethod(value) {
+  return typeof value === "string" && Object.values(CREDENTIAL_METHOD).some((method) => method === value);
+}
+function isCredentialScope(value) {
+  return typeof value === "string" && CREDENTIAL_SCOPES.some((scope) => scope === value);
+}
+function isAgentChatTurnActivityRecord(value) {
+  return isAgentChatActivityRecord(value) && typeof value.turnId === "string" && typeof value.seconds === "number" && Number.isFinite(value.seconds) && value.seconds >= 0;
+}
+function isAgentChatActivityCallRecord(value) {
+  return isAgentChatActivityRecord(value) && typeof value.callId === "string" && value.callId.length > 0;
+}
+function isNamedAgentChatActivityRecord(value, field) {
+  if (!isAgentChatActivityCallRecord(value)) return false;
+  const name = value[field];
+  return typeof name === "string" && name.length > 0;
+}
+function isAgentChatSkillActivityRecord(value) {
+  return isNamedAgentChatActivityRecord(value, "skillName");
+}
+function isAgentChatMcpActivityRecord(value) {
+  return isNamedAgentChatActivityRecord(value, "mcpName");
+}
+
 // ../shared/src/event.ts
 var CLAUDE_PARTIAL_MESSAGE_EVENT_TYPE = "claude-partial-message";
 function coerceClaudePartialMessagePayload(payload) {
@@ -112,6 +226,23 @@ var COMPACTION_STATUS_EVENT_TYPE = "compaction-status";
 var CHAT_INTERRUPTED_EVENT_TYPE = "replicas-interrupted";
 var CHAT_GOAL_EVENT_TYPE = "chat-goal";
 var AUTH_RETRY_STATUS_EVENT_TYPE = "auth-retry-status";
+var AUTH_FALLBACK_EVENT_TYPE = "auth-fallback";
+function coerceAuthFallbackPayload(payload) {
+  const { provider, reason, exhaustedMethod, exhaustedScope, candidateMethod, candidateScope, status, detail } = payload;
+  if (typeof provider !== "string" || !isValidCodingAgentProvider(provider) || reason !== "rate_limit" && reason !== "out_of_credits" || !isAuthMethod(exhaustedMethod) || !isAuthMethod(candidateMethod) || !isCredentialScope(candidateScope) || status !== "switched" && status !== "failed") {
+    return null;
+  }
+  return {
+    provider,
+    reason,
+    exhaustedMethod,
+    ...isCredentialScope(exhaustedScope) ? { exhaustedScope } : {},
+    candidateMethod,
+    candidateScope,
+    status,
+    ...typeof detail === "string" && detail ? { detail } : {}
+  };
+}
 var CONTEXT_USAGE_EVENT_TYPE = "context-usage";
 
 // ../shared/src/languages.ts
@@ -205,91 +336,6 @@ function detectLanguageByPath(filePath) {
   return EXT_TO_LANGUAGE[ext] ?? null;
 }
 
-// ../shared/src/credentials/types.ts
-var CREDENTIAL_SCOPE = {
-  USER: "user",
-  ORG: "org"
-};
-var CREDENTIAL_SCOPES = Object.values(CREDENTIAL_SCOPE);
-var CREDENTIAL_SCOPE_PRIORITY = [CREDENTIAL_SCOPE.USER, CREDENTIAL_SCOPE.ORG];
-
-// ../shared/src/credentials/agents.ts
-var CREDENTIAL_METHOD = {
-  OAUTH: "oauth",
-  API_KEY: "api_key",
-  FOUNDRY: "foundry",
-  BEDROCK: "bedrock",
-  OPENCODE_GO: "opencode-go",
-  ASTER: "aster",
-  OPENROUTER: "openrouter"
-};
-var CREDENTIAL_TYPE = {
-  CLAUDE_OAUTH: "claude",
-  ANTHROPIC_API_KEY: "claude_anthropic_api_key",
-  CLAUDE_FOUNDRY: "claude_foundry",
-  CLAUDE_BEDROCK: "claude_bedrock",
-  CODEX_OAUTH: "codex",
-  OPENAI_API_KEY: "openai_api_key",
-  CODEX_FOUNDRY: "codex_foundry",
-  CURSOR_API_KEY: "cursor_api_key",
-  OPENCODE_GO_API_KEY: "opencode_go_api_key",
-  ASTER_API_KEY: "aster_api_key",
-  OPENROUTER_API_KEY: "openrouter_api_key"
-};
-var AGENT_CREDENTIAL_METHODS_IN_ORDER = {
-  [AGENT.CLAUDE]: [
-    { method: CREDENTIAL_METHOD.OAUTH, credentialType: CREDENTIAL_TYPE.CLAUDE_OAUTH },
-    { method: CREDENTIAL_METHOD.API_KEY, credentialType: CREDENTIAL_TYPE.ANTHROPIC_API_KEY },
-    { method: CREDENTIAL_METHOD.FOUNDRY, credentialType: CREDENTIAL_TYPE.CLAUDE_FOUNDRY },
-    { method: CREDENTIAL_METHOD.BEDROCK, credentialType: CREDENTIAL_TYPE.CLAUDE_BEDROCK }
-  ],
-  [AGENT.CODEX]: [
-    { method: CREDENTIAL_METHOD.OAUTH, credentialType: CREDENTIAL_TYPE.CODEX_OAUTH },
-    { method: CREDENTIAL_METHOD.API_KEY, credentialType: CREDENTIAL_TYPE.OPENAI_API_KEY },
-    { method: CREDENTIAL_METHOD.FOUNDRY, credentialType: CREDENTIAL_TYPE.CODEX_FOUNDRY }
-  ],
-  [AGENT.CURSOR]: [
-    { method: CREDENTIAL_METHOD.API_KEY, credentialType: CREDENTIAL_TYPE.CURSOR_API_KEY }
-  ],
-  [AGENT.OPENCODE]: [
-    { method: CREDENTIAL_METHOD.OPENCODE_GO, credentialType: CREDENTIAL_TYPE.OPENCODE_GO_API_KEY },
-    { method: CREDENTIAL_METHOD.ASTER, credentialType: CREDENTIAL_TYPE.ASTER_API_KEY },
-    { method: CREDENTIAL_METHOD.OPENROUTER, credentialType: CREDENTIAL_TYPE.OPENROUTER_API_KEY }
-  ],
-  [AGENT.PI]: [
-    { method: CREDENTIAL_METHOD.ASTER, credentialType: CREDENTIAL_TYPE.ASTER_API_KEY },
-    { method: CREDENTIAL_METHOD.OPENROUTER, credentialType: CREDENTIAL_TYPE.OPENROUTER_API_KEY }
-  ]
-};
-
-// ../shared/src/analytics/types.ts
-function isAgentChatActivityRecord(value) {
-  return isRecord(value) && typeof value.chatId === "string" && typeof value.provider === "string" && isValidAgentProvider(value.provider) && typeof value.model === "string" && (value.credentialMethod === void 0 || isAuthMethod(value.credentialMethod)) && (value.credentialScope === void 0 || isCredentialScope(value.credentialScope)) && value.credentialMethod === void 0 === (value.credentialScope === void 0) && (value.senderUserId === void 0 || typeof value.senderUserId === "string") && typeof value.occurredAt === "string";
-}
-function isAuthMethod(value) {
-  return typeof value === "string" && Object.values(CREDENTIAL_METHOD).some((method) => method === value);
-}
-function isCredentialScope(value) {
-  return typeof value === "string" && CREDENTIAL_SCOPES.some((scope) => scope === value);
-}
-function isAgentChatTurnActivityRecord(value) {
-  return isAgentChatActivityRecord(value) && typeof value.turnId === "string" && typeof value.seconds === "number" && Number.isFinite(value.seconds) && value.seconds >= 0;
-}
-function isAgentChatActivityCallRecord(value) {
-  return isAgentChatActivityRecord(value) && typeof value.callId === "string" && value.callId.length > 0;
-}
-function isNamedAgentChatActivityRecord(value, field) {
-  if (!isAgentChatActivityCallRecord(value)) return false;
-  const name = value[field];
-  return typeof name === "string" && name.length > 0;
-}
-function isAgentChatSkillActivityRecord(value) {
-  return isNamedAgentChatActivityRecord(value, "skillName");
-}
-function isAgentChatMcpActivityRecord(value) {
-  return isNamedAgentChatActivityRecord(value, "mcpName");
-}
-
 // ../shared/src/aster.ts
 var ASTER_PROVIDER = "aster";
 var ASTER_BASE_URL = "https://api.asterlab.ai/v1";
@@ -2501,7 +2547,8 @@ var DEFAULT_USER_PREFERENCES = {
   auto_draft_prs: false,
   open_prs_in_graphite: false,
   default_fast_mode: false,
-  agent_defaults: { ...EMPTY_AGENT_DEFAULT_SETTINGS }
+  agent_defaults: { ...EMPTY_AGENT_DEFAULT_SETTINGS },
+  credential_priority: null
 };
 function defaultReplicasAgentAbilities() {
   const abilities = {};
@@ -2686,7 +2733,7 @@ var TRANSIENT_NETWORK_ERROR_PATTERNS = [
   /connection closed/,
   /closed unexpectedly/
 ];
-var HTTP_CONTEXT_PATTERN = /(api error|request|response|status|http)/;
+var HTTP_CONTEXT_PATTERN2 = /(api error|request|response|status|http)/;
 var HTTP_STATUS_PATTERN = /(^|[^0-9])([1-5][0-9]{2})(?=$|[^0-9])/g;
 function extractErrorText(error) {
   const parts = [];
@@ -2728,7 +2775,7 @@ function isTransientErrorText(text, options = {}) {
   const httpStatuses = new Set(options.httpStatuses ?? []);
   const httpStatusClasses = new Set(options.httpStatusClasses ?? []);
   if (httpStatuses.size === 0 && httpStatusClasses.size === 0) return false;
-  if (options.requireHttpContext !== false && !HTTP_CONTEXT_PATTERN.test(normalized)) return false;
+  if (options.requireHttpContext !== false && !HTTP_CONTEXT_PATTERN2.test(normalized)) return false;
   for (const match of normalized.matchAll(HTTP_STATUS_PATTERN)) {
     const status = Number(match[2]);
     if (httpStatuses.has(status) || httpStatusClasses.has(Math.floor(status / 100))) return true;
@@ -2739,7 +2786,7 @@ function isTransientErrorText(text, options = {}) {
 // ../shared/src/claude-auth.ts
 function isClaudeAuthErrorText(text) {
   const lower = text.toLowerCase();
-  return lower.includes("failed to authenticate") || lower.includes("authentication_error") || lower.includes("authentication_failed") || lower.includes("authentication failed") || lower.includes("invalid authentication credentials") || lower.includes("not logged in") || lower.includes("please run /login") || lower.includes("credit balance is too low") || lower.includes("401") && lower.includes("authentic");
+  return lower.includes("failed to authenticate") || lower.includes("authentication_error") || lower.includes("authentication_failed") || lower.includes("authentication failed") || lower.includes("invalid authentication credentials") || lower.includes("not logged in") || lower.includes("please run /login") || lower.includes("401") && lower.includes("authentic");
 }
 
 // ../shared/src/codex-auth.ts
@@ -5122,21 +5169,24 @@ function parseDisplayMessages(events, agentType, codexAspTranscript, options = {
   const shouldFilter = options.filter ?? true;
   const parsedEvents = agentType === "claude" || agentType === "relay" ? parseClaudeEvents(events, options.parentToolUseId) : parseAgentEvents(events, agentType);
   const legacyMessages = shouldFilter ? filterDisplayMessages(parsedEvents, agentType) : parsedEvents;
+  const finalize = (messages) => shouldFilter ? applyAuthFallbackNotices(applyInterruptions(messages, events), events) : messages;
   if (agentType !== "codex" || !codexAspTranscript) {
-    return shouldFilter ? applyInterruptions(legacyMessages, events) : legacyMessages;
+    return finalize(legacyMessages);
   }
   const nativeCodexMessages = shouldFilter ? filterDisplayMessages(parseCodexAspTranscript(codexAspTranscript), agentType) : parseCodexAspTranscript(codexAspTranscript);
-  const merged = mergeCodexAspDisplayMessages(nativeCodexMessages, legacyMessages);
-  return shouldFilter ? applyInterruptions(merged, events) : merged;
+  return finalize(mergeCodexAspDisplayMessages(nativeCodexMessages, legacyMessages));
+}
+function insertByTimestamp(messages, message) {
+  const messageMs = parseTimestampMs(message.timestamp);
+  let index = messages.length;
+  while (index > 0 && parseTimestampMs(messages[index - 1].timestamp) > messageMs) index--;
+  messages.splice(index, 0, message);
 }
 function applyInterruptions(messages, events) {
   const result = [...messages];
   for (const event of events) {
     if (event.type !== CHAT_INTERRUPTED_EVENT_TYPE) continue;
-    const eventMs = parseTimestampMs(event.timestamp);
-    let index = result.length;
-    while (index > 0 && parseTimestampMs(result[index - 1].timestamp) > eventMs) index--;
-    result.splice(index, 0, {
+    insertByTimestamp(result, {
       id: `interruption-${event.timestamp}`,
       type: "interruption",
       timestamp: event.timestamp
@@ -5168,6 +5218,24 @@ function applyInterruptions(messages, events) {
   }
   return finalized;
 }
+function applyAuthFallbackNotices(messages, events) {
+  const notices = [];
+  events.forEach((event, index) => {
+    if (event.type !== AUTH_FALLBACK_EVENT_TYPE) return;
+    const payload = coerceAuthFallbackPayload(event.payload);
+    if (!payload) return;
+    notices.push({
+      ...payload,
+      id: `auth-fallback-${event.timestamp}-${index}`,
+      type: "auth_fallback",
+      timestamp: event.timestamp
+    });
+  });
+  if (notices.length === 0) return messages;
+  const result = [...messages];
+  for (const notice of notices) insertByTimestamp(result, notice);
+  return result;
+}
 function isCodexInitializationPrompt(message) {
   return message.type === "user" && removeReplicasInstructions(message.content).trim() === "Hello";
 }
@@ -5392,6 +5460,28 @@ function setAgentCredentialSnapshot(provider, snapshot) {
   process.env.REPLICAS_AGENT_CREDENTIALS = JSON.stringify(ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS);
 }
 
+// src/services/credential-fallbacks.ts
+var fallbacksByAgent = /* @__PURE__ */ new Map();
+var exhaustedByAgent = /* @__PURE__ */ new Map();
+function recordCredentialFallback(notice) {
+  fallbacksByAgent.set(notice.provider, notice);
+}
+function listCredentialFallbacks() {
+  return [...fallbacksByAgent.values()].filter((notice) => {
+    const live = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS[notice.provider];
+    if (!live) return false;
+    return notice.status === "switched" ? live.method === notice.candidateMethod && live.scope === notice.candidateScope : live.method === notice.exhaustedMethod && live.scope === notice.exhaustedScope;
+  });
+}
+function listExhaustedCredentials(provider) {
+  return [...exhaustedByAgent.get(provider)?.values() ?? []];
+}
+function recordExhaustedCredential(provider, credential) {
+  const spent = exhaustedByAgent.get(provider) ?? /* @__PURE__ */ new Map();
+  spent.set(`${credential.method}|${credential.scope}`, credential);
+  exhaustedByAgent.set(provider, spent);
+}
+
 // src/managers/base-refresh-manager.ts
 var BaseRefreshManager = class {
   constructor(managerName, intervalMs = 15 * 60 * 1e3) {
@@ -5446,6 +5536,29 @@ var BaseRefreshManager = class {
     }
     this.scheduleNextRefresh();
   }
+  async swapCredentials(params) {
+    if (!this.getRuntimeConfig()) {
+      return createErrorResult({ message: `${this.managerName} has no runtime config`, code: "not_configured" });
+    }
+    try {
+      console.log(`[${this.managerName}] Fetching fresh credentials from monolith (${params.failureKind})...`);
+      const excludeCredentials = listExhaustedCredentials(params.provider);
+      await params.refresh(excludeCredentials.length > 0 ? { excludeCredentials } : {});
+      if (params.isOauthNow()) {
+        this.start().catch((error) => {
+          console.error(`[${this.managerName}] Failed to restart OAuth refresh service after fallback:`, error);
+        });
+      }
+      return createSuccessResult();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`[${this.managerName}] Failed to fetch fresh credentials:`, error);
+      return createErrorResult({
+        message,
+        code: message.includes('"code":"no_credentials"') ? "no_credentials" : "refresh_failed"
+      });
+    }
+  }
   stop() {
     if (!this.intervalHandle) {
       return;
@@ -6465,26 +6578,14 @@ var ClaudeTokenManager = class extends BaseRefreshManager {
     if (data.scope) setAgentCredentialSnapshot("claude", { method: data.type, scope: data.scope });
     console.log(`[ClaudeTokenManager] Credentials refreshed (method=${data.type})`);
   }
-  async fetchFreshCredentials(failureReason) {
-    const config = this.getRuntimeConfig();
-    if (!config) return false;
-    try {
-      console.log("[ClaudeTokenManager] Fetching fresh credentials from monolith after auth failure...");
-      const failedMethod = ENGINE_ENV.REPLICAS_CLAUDE_AUTH_METHOD;
-      await this.refreshWithRequest(failedMethod && failedMethod !== "none" ? {
-        failedMethod,
-        failureReason
-      } : void 0);
-      if (ENGINE_ENV.REPLICAS_CLAUDE_AUTH_METHOD === "oauth") {
-        this.start().catch((error) => {
-          console.error("[ClaudeTokenManager] Failed to restart OAuth refresh service after fallback:", error);
-        });
-      }
-      return true;
-    } catch (error) {
-      console.error("[ClaudeTokenManager] Failed to fetch fresh credentials:", error);
-      return false;
-    }
+  async fetchFreshCredentials(failureReason, failureKind = "rejected") {
+    const failedMethod = ENGINE_ENV.REPLICAS_CLAUDE_AUTH_METHOD;
+    return this.swapCredentials({
+      provider: "claude",
+      failureKind,
+      refresh: (exclusions) => this.refreshWithRequest(failedMethod && failedMethod !== "none" ? { failedMethod, failureReason, failureKind, ...exclusions } : exclusions),
+      isOauthNow: () => ENGINE_ENV.REPLICAS_CLAUDE_AUTH_METHOD === "oauth"
+    });
   }
   async applyCredentialsResponse(response) {
     if (response.type === "oauth") {
@@ -6573,26 +6674,16 @@ var CodexTokenManager = class extends BaseRefreshManager {
     if (data.scope) setAgentCredentialSnapshot("codex", { method: data.type, scope: data.scope });
     console.log(`[CodexTokenManager] Credentials refreshed (method=${data.type})`);
   }
-  async fetchFreshCredentials(failureReason) {
-    const config = this.getRuntimeConfig();
-    if (!config) return false;
-    try {
-      console.log("[CodexTokenManager] Fetching fresh credentials from monolith after auth failure...");
-      const failedMethod = ENGINE_ENV.REPLICAS_CODEX_AUTH_METHOD;
-      await this.refreshWithRequest(failedMethod === "oauth" || failedMethod === "api_key" || failedMethod === "foundry" ? {
-        failedMethod,
-        failureReason
-      } : void 0);
-      if (ENGINE_ENV.REPLICAS_CODEX_AUTH_METHOD === "oauth") {
-        this.start().catch((error) => {
-          console.error("[CodexTokenManager] Failed to restart OAuth refresh service after fallback:", error);
-        });
-      }
-      return true;
-    } catch (error) {
-      console.error("[CodexTokenManager] Failed to fetch fresh credentials:", error);
-      return false;
-    }
+  async fetchFreshCredentials(failureReason, failureKind = "rejected") {
+    const failedMethod = ENGINE_ENV.REPLICAS_CODEX_AUTH_METHOD;
+    return this.swapCredentials({
+      provider: "codex",
+      failureKind,
+      refresh: (exclusions) => this.refreshWithRequest(
+        failedMethod === "oauth" || failedMethod === "api_key" || failedMethod === "foundry" ? { failedMethod, failureReason, failureKind, ...exclusions } : exclusions
+      ),
+      isOauthNow: () => ENGINE_ENV.REPLICAS_CODEX_AUTH_METHOD === "oauth"
+    });
   }
   async applyCredentialsResponse(response) {
     if (response.type === "oauth") {
@@ -6990,6 +7081,7 @@ var EnvironmentDetailsService = class {
     details.cursorAuthMethod = detectCursorAuthMethod();
     details.opencodeAuthMethod = detectOpencodeAuthMethod();
     details.piAuthMethod = detectPiAuthMethod();
+    details.credentialFallbacks = listCredentialFallbacks();
     details.gitIdentityConfigured = gitIdentityConfigured;
     const ghConfigured = existsSync2(GH_HOSTS_PATH);
     details.githubAccessConfigured = ghConfigured;
@@ -8262,6 +8354,48 @@ async function removeTempImageFiles(paths) {
   await Promise.allSettled(paths.map((path6) => unlink2(path6)));
 }
 
+// src/managers/auth-fallback.ts
+var SWAPPABLE_AGENTS = {
+  claude: claudeTokenManager,
+  codex: codexTokenManager
+};
+var AuthFallbackCoordinator = class {
+  constructor(provider, record) {
+    this.provider = provider;
+    this.record = record;
+  }
+  provider;
+  record;
+  async fallBack(reason, detail) {
+    const tokenManager = SWAPPABLE_AGENTS[this.provider];
+    if (!tokenManager) return "unavailable";
+    const exhausted = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS[this.provider];
+    if (!exhausted) return "unavailable";
+    recordExhaustedCredential(this.provider, exhausted);
+    const swap = await tokenManager.fetchFreshCredentials(
+      `${this.provider} ${reason === "out_of_credits" ? "is out of credits" : "hit its usage limit"}: ${detail}`,
+      "exhausted"
+    );
+    if (!swap.ok && swap.error.code === "no_credentials") return "unavailable";
+    const applied = ENGINE_ENV.REPLICAS_AGENT_CREDENTIALS[this.provider] ?? exhausted;
+    const moved = swap.ok && !(applied.method === exhausted.method && applied.scope === exhausted.scope);
+    const payload = {
+      provider: this.provider,
+      reason,
+      exhaustedMethod: exhausted.method,
+      exhaustedScope: exhausted.scope,
+      candidateMethod: applied.method,
+      candidateScope: applied.scope,
+      status: moved ? "switched" : "failed",
+      detail: moved ? detail : "Replicas could not load an alternate credential."
+    };
+    const at = (/* @__PURE__ */ new Date()).toISOString();
+    this.record({ timestamp: at, type: AUTH_FALLBACK_EVENT_TYPE, payload: { ...payload } });
+    recordCredentialFallback({ ...payload, at });
+    return moved ? "switched" : "failed";
+  }
+};
+
 // src/services/message-queue-service.ts
 var MessageQueueService = class {
   queue = [];
@@ -8445,6 +8579,7 @@ var CodingAgentManager = class {
   onEvent;
   hostOnTurnComplete;
   onProcessingChanged;
+  authFallback;
   compacting = false;
   constructor(options) {
     this.workingDirectory = options.workingDirectory ?? ENGINE_ENV.WORKSPACE_ROOT;
@@ -8454,6 +8589,14 @@ var CodingAgentManager = class {
     this.hostOnTurnComplete = options.onTurnComplete;
     this.onProcessingChanged = options.onProcessingChanged ?? (() => {
     });
+    this.authFallback = options.provider ? new AuthFallbackCoordinator(options.provider, (event) => {
+      this.onEvent(event);
+      this.getHistorySink()?.append(event);
+    }) : null;
+  }
+  async fallBackCredential(reason, detail) {
+    if (!this.authFallback) return "unavailable";
+    return this.authFallback.fallBack(reason, detail);
   }
   onTurnComplete = async () => {
     if (this.compacting) {
@@ -9444,7 +9587,16 @@ var ClaudeTransientTurnError = class extends Error {
   }
   midTurn;
 };
+var ClaudeQuotaError = class extends Error {
+  constructor(message, kind) {
+    super(message);
+    this.kind = kind;
+    this.name = "ClaudeQuotaError";
+  }
+  kind;
+};
 var MAX_AUTH_RETRIES = 2;
+var MAX_QUOTA_FALLBACKS = 2;
 var MAX_TRANSIENT_RETRIES = 2;
 var MAX_MIDTURN_CONTINUE_RETRIES = 2;
 var TRANSIENT_RETRY_DELAYS_MS = [1e3, 2500];
@@ -9490,7 +9642,7 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
   slashCommandsDiscovery = null;
   authRetrying = false;
   constructor(options) {
-    super(options);
+    super({ ...options, provider: AGENT.CLAUDE });
     this.historyFilePath = options.historyFilePath ?? join16(homedir12(), ".replicas", "claude", "history.jsonl");
     this.historyFile = new CodexHistoryFile(this.historyFilePath);
     this.systemPromptOverride = options.systemPromptOverride;
@@ -9722,6 +9874,7 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
   async processMessageInternal(request) {
     let lastError;
     let authRetryExhausted = false;
+    let quotaFallbacks = 0;
     let attempt = 0;
     let authRetries = 0;
     let transientRetries = 0;
@@ -9734,6 +9887,19 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
           return;
         } catch (error) {
           lastError = error;
+          const quotaKind = _ClaudeManager.quotaLimitKind(error);
+          if (quotaKind) {
+            const detail = error instanceof ClaudeQuotaError ? error.message : extractErrorText(error);
+            const outcome = quotaFallbacks < MAX_QUOTA_FALLBACKS ? await this.fallBackCredential(quotaKind, detail) : "unavailable";
+            if (outcome === "switched") {
+              quotaFallbacks++;
+              await this.tearDownSession();
+              attempt++;
+              continue;
+            }
+            await this.emitQuotaExhaustedEvent(quotaKind, outcome, detail);
+            return;
+          }
           if (_ClaudeManager.isAuthError(error)) {
             if (authRetries >= MAX_AUTH_RETRIES) {
               authRetryExhausted = true;
@@ -9748,7 +9914,7 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
             const refreshed = await claudeTokenManager.fetchFreshCredentials(
               error instanceof Error ? error.message : String(error)
             );
-            if (!refreshed) {
+            if (!refreshed.ok) {
               authRetryExhausted = true;
               throw error;
             }
@@ -9840,6 +10006,11 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
         return "Claude authentication failed after multiple attempts. Check your Claude, Anthropic API key, or Bedrock credentials in Settings \u2192 Agents and try again.";
     }
   }
+  async emitQuotaExhaustedEvent(kind, outcome, detail) {
+    const limit = kind === "out_of_credits" ? "Claude ran out of credits on the credential this workspace is using." : "Claude hit the usage limit on the credential this workspace is using.";
+    const next = outcome === "failed" ? "Switching to the alternate credential failed. Check the credentials in Settings \u2192 Agents and try again." : "No other credential is available for this workspace. Add one in Settings \u2192 Agents, or try again once the limit resets.";
+    await this.emitTerminalErrorResult(detail, [`${limit} ${next}`]);
+  }
   async emitMidTurnExhaustedEvent(error) {
     const detail = error instanceof Error ? error.message : String(error);
     await this.emitTerminalErrorResult(
@@ -10097,6 +10268,17 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
           }
           return;
         }
+        const quotaError = _ClaudeManager.detectQuotaErrorInMessage(msg);
+        if (quotaError) {
+          suppressLinearResponseFlush = true;
+          this.failPendingTurn(quotaError);
+          try {
+            response.close();
+          } catch (err) {
+            console.warn("[ClaudeManager] query.close() during quota error failed:", err);
+          }
+          return;
+        }
         const transientErrorMessage = _ClaudeManager.detectTransientTurnErrorInMessage(msg);
         if (transientErrorMessage) {
           suppressLinearResponseFlush = true;
@@ -10293,6 +10475,22 @@ var ClaudeManager = class _ClaudeManager extends CodingAgentManager {
     if (error instanceof ClaudeAuthError) return true;
     return isClaudeAuthErrorText(error instanceof Error ? error.message : String(error));
   }
+  static quotaLimitKind(error) {
+    if (error instanceof ClaudeQuotaError) return error.kind;
+    return detectAgentQuotaLimit(extractErrorText(error));
+  }
+  static detectQuotaErrorInMessage(message) {
+    if (message.type === "assistant" && "error" in message) {
+      const content = Array.isArray(message.message?.content) ? message.message.content.map((block) => "text" in block ? block.text : "").join("\n") : "";
+      const text2 = [typeof message.error === "string" ? message.error : "", content].filter(Boolean).join("\n");
+      const kind2 = detectAgentQuotaLimit(text2);
+      if (kind2) return new ClaudeQuotaError(text2, kind2);
+    }
+    if (message.type !== "result" || !message.is_error) return null;
+    const text = message.subtype === "success" ? message.result : message.errors.join("\n");
+    const kind = detectAgentQuotaLimit(text);
+    return kind ? new ClaudeQuotaError(text, kind) : null;
+  }
   static isTransientTurnError(error) {
     if (error instanceof ClaudeTransientTurnError) return true;
     return _ClaudeManager.isTransientTurnErrorText(extractErrorText(error));
@@ -10670,7 +10868,7 @@ var DEFAULT_CODEX_ARGS = ["app-server", "--listen", "stdio://"];
 var MIN_CODEX_CLI_VERSION = "0.144.6";
 var CODEX_UPGRADE_TIMEOUT_MS = 12e4;
 var codexCliVersionEnsured = null;
-var ENGINE_PACKAGE_VERSION = "0.1.610";
+var ENGINE_PACKAGE_VERSION = "0.1.611";
 var INITIALIZE_METHOD = "initialize";
 var INITIALIZED_NOTIFICATION = "initialized";
 var ACCOUNT_LOGIN_START_METHOD = "account/login/start";
@@ -11267,7 +11465,7 @@ function isQuotaTurnFailure(turn) {
   return false;
 }
 function isQuotaErrorMessage(error) {
-  return error instanceof Error && /\b429\b|rate.?limit|usage.?limit|quota|out.of.credits|credits?.?(?:depleted|exhausted|remaining)/i.test(error.message);
+  return error instanceof Error && detectAgentQuotaLimit(error.message) !== null;
 }
 function formatTurnFailure(turn) {
   const turnError = turn.error;
@@ -11637,6 +11835,12 @@ var DuplicateDefaultChatError = class extends Error {
 };
 
 // src/managers/codex-asp/codex-asp-manager.ts
+var CodexQuotaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CodexQuotaError";
+  }
+};
 var GOAL_TURN_CONTINUATION_GRACE_MS = 5e3;
 var CODEX_SLASH_COMMANDS_CACHE_MS = 3e4;
 var POLICY_REASON_INJECTION_TIMEOUT_MS = 5e3;
@@ -11721,7 +11925,7 @@ var CodexAspManager = class extends CodingAgentManager {
   steeredTempImagePaths = [];
   steerLock = new AsyncLock();
   constructor(options) {
-    super(options);
+    super({ ...options, provider: AGENT.CODEX });
     this.historyFile = options.historyFilePath ? new CodexHistoryFile(options.historyFilePath) : null;
     this.initializeManager(this.processMessageInternal.bind(this));
   }
@@ -11901,6 +12105,7 @@ var CodexAspManager = class extends CodingAgentManager {
   }
   async processMessageInternal(request) {
     let userMessageRecorded = false;
+    let quotaFallbackAttempted = false;
     const recordUserMessage = (extraPayload = {}) => {
       if (userMessageRecorded) return;
       userMessageRecorded = true;
@@ -11946,17 +12151,26 @@ var CodexAspManager = class extends CodingAgentManager {
       await dispatch();
     } catch (error) {
       let terminalError = error;
+      if (terminalError instanceof CodexQuotaError && !quotaFallbackAttempted) {
+        quotaFallbackAttempted = true;
+        const outcome = await this.fallBackCredential(
+          detectAgentQuotaLimit(terminalError.message) ?? "rate_limit",
+          terminalError.message
+        );
+        if (outcome === "switched") {
+          const retryFailure = await this.restartAndRetry(dispatch);
+          if (!retryFailure) return;
+          terminalError = retryFailure.error;
+        } else if (await this.confirmOutOfCredits(await getCodexAspHost())) {
+          return;
+        }
+      }
       if (isCodexAuthError(terminalError)) {
         const refreshed = await codexTokenManager.fetchFreshCredentials(terminalError instanceof Error ? terminalError.message : String(terminalError));
-        if (refreshed) {
-          try {
-            await restartCodexAspHost();
-            this.threadAttached = false;
-            await dispatch();
-            return;
-          } catch (retryError) {
-            terminalError = retryError;
-          }
+        if (refreshed.ok) {
+          const retryFailure = await this.restartAndRetry(dispatch);
+          if (!retryFailure) return;
+          terminalError = retryFailure.error;
         }
       }
       const event = this.recordHistoryEvent("codex-asp-error", {
@@ -12008,16 +12222,14 @@ var CodexAspManager = class extends CodingAgentManager {
     try {
       completedTurn = await runTurn(host, threadId);
     } catch (error) {
-      if (isQuotaErrorMessage(error) && await this.confirmOutOfCredits(host)) {
-        return;
+      if (isQuotaErrorMessage(error)) {
+        throw new CodexQuotaError(error instanceof Error ? error.message : String(error));
       }
       throw error;
     }
     if (completedTurn.status === "failed") {
-      if (isQuotaTurnFailure(completedTurn) && await this.confirmOutOfCredits(host)) {
-        return;
-      }
-      throw new Error(formatTurnFailure(completedTurn));
+      const failure = formatTurnFailure(completedTurn);
+      throw isQuotaTurnFailure(completedTurn) ? new CodexQuotaError(failure) : new Error(failure);
     }
     this.emitQuotaEvent(this.quotaStatus.recordTurnSuccess());
   }
@@ -12887,6 +13099,16 @@ var CodexAspManager = class extends CodingAgentManager {
     } catch {
     }
   }
+  async restartAndRetry(dispatch) {
+    try {
+      await restartCodexAspHost();
+      this.threadAttached = false;
+      await dispatch();
+      return null;
+    } catch (error) {
+      return { error };
+    }
+  }
   async confirmOutOfCredits(host) {
     await this.refreshQuotaSnapshot(host);
     const event = this.quotaStatus.confirmOutOfCredits();
@@ -16653,7 +16875,7 @@ var ChatService = class {
       }
     }).catch(() => {
     });
-    if (event.type === "replicas-tool-input-request" || event.type === "replicas-tool-input-resolved" || event.type === "compaction-status" || event.type === AUTH_RETRY_STATUS_EVENT_TYPE || event.type === CHAT_GOAL_EVENT_TYPE || event.type === CLAUDE_ACTIVITY_STATUS_EVENT_TYPE || event.type === "claude-result" || event.type === "claude-system" && (event.payload.subtype === "init" || event.payload.subtype === "session_state_changed" || event.payload.subtype === "background_tasks_changed" || coerceBackgroundTaskPayload(event.payload) !== null)) {
+    if (event.type === "replicas-tool-input-request" || event.type === "replicas-tool-input-resolved" || event.type === "compaction-status" || event.type === AUTH_RETRY_STATUS_EVENT_TYPE || event.type === AUTH_FALLBACK_EVENT_TYPE || event.type === CHAT_GOAL_EVENT_TYPE || event.type === CLAUDE_ACTIVITY_STATUS_EVENT_TYPE || event.type === "claude-result" || event.type === "claude-system" && (event.payload.subtype === "init" || event.payload.subtype === "session_state_changed" || event.payload.subtype === "background_tasks_changed" || coerceBackgroundTaskPayload(event.payload) !== null)) {
       this.publish({
         type: "chat.updated",
         payload: { chat: this.toSummary(chat) }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-engine",
-  "version": "0.1.610",
+  "version": "0.1.611",
   "description": "Lightweight API server for Replicas workspaces",
   "type": "module",
   "main": "dist/src/index.js",