fix(runtime): classify provider capacity errors (#3365)

* fix(runtime): classify provider capacity errors

Fixes #3341

Generated-by: Codex

* fix(runtime): refine provider capacity retry classification

Keep xAI capacity errors distinct from quota exhaustion and fall back to bounded local retry when Retry-After is malformed.

Generated-by: gpt-5.6-sol

* fix(runtime): preserve provider capacity retry reason

Generated-by: gpt-5.6-sol

* fix(runtime): prioritize capacity evidence safely

* fix(runtime): preserve capacity diagnostics

Author: CxHsin

apps/desktop/src/main/__tests__/session-error-presentation.test.ts

@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { describeSessionErrorReason } from '../../renderer/session-error-presentation.js';
+import { deriveFailedTurnRecovery, describeTurnErrorClass } from '../../renderer/session-status-presentation.js';
+
+describe('provider capacity presentation', () => {
+  it('uses capacity-specific copy instead of the unknown error fallback', () => {
+    assert.match(describeSessionErrorReason('provider_capacity') ?? '', /满载/);
+    assert.match(describeTurnErrorClass('provider_capacity'), /满载/);
+  });
+
+  it('does not recommend an immediate direct retry', () => {
+    const recovery = deriveFailedTurnRecovery({
+      errorClass: 'provider_capacity',
+      partialOutputRetained: false,
+      toolActivityCount: 0,
+      erroredToolCount: 0,
+    });
+    assert.equal(recovery.action, 'retry');
+    assert.match(recovery.label, /等待几分钟|切换模型/);
+    assert.doesNotMatch(recovery.label, /直接重试/);
+  });
+});

apps/desktop/src/main/__tests__/session-status-presentation.test.ts

@@ -79,5 +79,19 @@ describe('failed turn recovery presentation', () => {
       ),
       { action: 'inspect_tool', label: 'Inspect the tool result before retrying' },
     );
+    assert.deepEqual(
+      deriveFailedTurnRecovery(
+        { ...outputFreeFailure, errorClass: 'provider_capacity', partialOutputRetained: true },
+        'en',
+      ),
+      { action: 'continue', label: 'Partial output was retained; continue from here' },
+    );
+    assert.deepEqual(
+      deriveFailedTurnRecovery(
+        { ...outputFreeFailure, errorClass: 'provider_capacity', toolActivityCount: 1 },
+        'en',
+      ),
+      { action: 'inspect_tool', label: 'Tool history was retained; inspect it before retrying' },
+    );
   });
 });

apps/desktop/src/renderer/locales/conversation-copy.ts

@@ -307,6 +307,7 @@ export interface DesktopConversationCopy {
     timeout: string;
     auth: string;
     providerBilling: string;
+    providerCapacity: string;
     rateLimit: string;
     network: string;
     provider: string;
@@ -315,7 +316,7 @@ export interface DesktopConversationCopy {
     permission: string;
     restarted: string;
     sandboxBoundaryClosed: string;
-    recovery: Record<'safeResume' | 'stepCap' | 'toolError' | 'connection' | 'partial' | 'toolRecord' | 'retry' | 'contextOverflow' | 'sandboxBoundaryClosed', string>;
+    recovery: Record<'safeResume' | 'stepCap' | 'toolError' | 'connection' | 'partial' | 'toolRecord' | 'retry' | 'capacity' | 'contextOverflow' | 'sandboxBoundaryClosed', string>;
   };
 }
 
@@ -588,7 +589,7 @@ const COPY = {
       reauth: { label: '上次连接测试鉴权失败', tooltip: '最近一次连接测试返回鉴权失败（401 / 403），密钥可能已过期或被吊销。这不会拦截发送，但若发送失败请到 设置 · 模型 重新登录。' },
       testError: { label: '上次连接测试失败', tooltip: '最近一次连接测试因网络 / 超时 / 5xx 失败。这不会拦截发送，但若问题持续请到 设置 · 模型 检查 Base URL / 代理。' },
     },
-    turnError: { unknown: '未知错误', contextOverflow: '上下文窗口已超出限制', timeout: '请求超时', auth: '鉴权失败', providerBilling: '模型服务计费受限', rateLimit: '触发模型速率限制', network: '网络错误', provider: '模型服务返回错误', stepCap: '达到工具步骤上限', tool: '工具调用失败', permission: '等待权限确认', restarted: '本地应用重启，上一轮没有完成', sandboxBoundaryClosed: '本地应用重启，等待确认的「允许访问工作区以外的内容」请求已按拒绝关闭', recovery: { safeResume: '检查当前状态后，可尝试安全恢复', stepCap: '任务可能尚未完成，可以继续', toolError: '先检查工具结果，再决定是否重试', connection: '先检查模型连接或登录状态', partial: '已保留部分输出，可从这里继续', toolRecord: '工具记录已保留，重试前先看结果', retry: '没有执行工具，可直接重试', contextOverflow: '上下文仍超出限制，请减少附件或开启新任务', sandboxBoundaryClosed: '访问范围没有放开，重试本轮后可重新决定' } },
+    turnError: { unknown: '未知错误', contextOverflow: '上下文窗口已超出限制', timeout: '请求超时', auth: '鉴权失败', providerBilling: '模型服务计费受限', providerCapacity: '模型服务暂时满载，请稍后重试或切换模型', rateLimit: '触发模型速率限制', network: '网络错误', provider: '模型服务返回错误', stepCap: '达到工具步骤上限', tool: '工具调用失败', permission: '等待权限确认', restarted: '本地应用重启，上一轮没有完成', sandboxBoundaryClosed: '本地应用重启，等待确认的「允许访问工作区以外的内容」请求已按拒绝关闭', recovery: { safeResume: '检查当前状态后，可尝试安全恢复', stepCap: '任务可能尚未完成，可以继续', toolError: '先检查工具结果，再决定是否重试', connection: '先检查模型连接或登录状态', partial: '已保留部分输出，可从这里继续', toolRecord: '工具记录已保留，重试前先看结果', retry: '没有执行工具，可直接重试', capacity: '模型服务暂时满载，请等待几分钟或切换模型后重试', contextOverflow: '上下文仍超出限制，请减少附件或开启新任务', sandboxBoundaryClosed: '访问范围没有放开，重试本轮后可重新决定' } },
   },
   en: {
     actions: { stopFailedTitle: 'Failed to stop', stopFailedFallback: 'The task action failed. Try again later.', refreshSessionsFailedTitle: 'Failed to refresh tasks', refreshSessionsFailedFallback: 'The task list could not be refreshed. Try again later.', conversationErrorTitle: 'Task error', conversationErrorFallback: 'The task run failed. Try again later.', regenerateStartedTitle: 'Regeneration started', regenerateStartedDescription: 'Generating a new response', branchCreatedTitle: 'Branch created', branchCreatedDescription: (name) => `New task: ${name}`, revisionStartedTitle: 'Edit draft ready', revisionStartedDescription: 'The original task is kept; sending creates a new version', revisionReadyTitle: 'Ready to edit and resend', revisionReadyDescription: 'Rewound to before that message; edit and send when ready', revisionUnavailableTitle: 'This message cannot be edited yet', revisionAttachmentsUnsupported: 'Edit & resend does not yet support historical attachments. Copy the text into a new message instead.', revisionTransformedTextUnsupported: 'Edit & resend does not yet support messages sent with an explicit skill. Copy the text and select the skill again instead.', revisionDraftAttachmentConflict: 'The composer already has pending attachments. Send or remove them before editing a sent message.', revisionCommandUnsupported: 'You cannot run /compact, /side, or orchestration commands while editing a sent message. Cancel the edit first.', revisionAlreadyActive: 'Another message is already being edited. Send or cancel that edit first.', revisionCancelLabel: 'Cancel', revisionBannerTitle: 'Editing sent message', revisionBannerDetail: '· New version on send', revisionUnchanged: 'Nothing changed. Use Regenerate if you only want a new answer.', operationFailedTitle: 'Action failed', operationFailedFallback: 'The task action failed. Try again later.', attachmentFailedTitle: 'Failed to add attachment', tryAgain: 'Try again later.', modelReboundTitle: 'Switched to an available model', modelReboundDescription: (modelId) => `The previous connection is unavailable${modelId ? ` · ${modelId}` : ''}`, messageReadFailedTitle: 'Failed to load task', returnLatest: 'Return to latest', scrollMainToBottom: 'Scroll main conversation to bottom' },
@@ -794,7 +795,7 @@ const COPY = {
       reauth: { label: 'Last connection test failed authentication', tooltip: 'The latest test returned 401 / 403. Sending is not blocked, but sign in again under Settings · Models if it fails.' },
       testError: { label: 'Last connection test failed', tooltip: 'The latest test failed because of a network, timeout, or 5xx error. Sending is not blocked; check Base URL or proxy settings if it persists.' },
     },
-    turnError: { unknown: 'Unknown error', contextOverflow: 'Context window exceeded', timeout: 'Request timed out', auth: 'Authentication failed', providerBilling: 'Provider billing required', rateLimit: 'Model rate limit reached', network: 'Network error', provider: 'Model service error', stepCap: 'Tool-step limit reached', tool: 'Tool call failed', permission: 'Waiting for permission', restarted: 'The app restarted before the previous turn completed', sandboxBoundaryClosed: 'The app restarted, so the pending request to reach outside the workspace was closed as denied', recovery: { safeResume: 'Inspect the current state, then try safe recovery', stepCap: 'The task may be incomplete; continue from here', toolError: 'Inspect the tool result before retrying', connection: 'Check the model connection or sign-in status', partial: 'Partial output was retained; continue from here', toolRecord: 'Tool history was retained; inspect it before retrying', retry: 'No tools ran; retry directly', contextOverflow: 'Context is still too large; reduce attachments or start a new task', sandboxBoundaryClosed: 'Access was not widened; retry the turn to decide again' } },
+    turnError: { unknown: 'Unknown error', contextOverflow: 'Context window exceeded', timeout: 'Request timed out', auth: 'Authentication failed', providerBilling: 'Provider billing required', providerCapacity: 'The model service is temporarily at capacity. Wait and retry, or switch models.', rateLimit: 'Model rate limit reached', network: 'Network error', provider: 'Model service error', stepCap: 'Tool-step limit reached', tool: 'Tool call failed', permission: 'Waiting for permission', restarted: 'The app restarted before the previous turn completed', sandboxBoundaryClosed: 'The app restarted, so the pending request to reach outside the workspace was closed as denied', recovery: { safeResume: 'Inspect the current state, then try safe recovery', stepCap: 'The task may be incomplete; continue from here', toolError: 'Inspect the tool result before retrying', connection: 'Check the model connection or sign-in status', partial: 'Partial output was retained; continue from here', toolRecord: 'Tool history was retained; inspect it before retrying', retry: 'No tools ran; retry directly', capacity: 'The model service is at capacity. Wait a few minutes or switch models before retrying.', contextOverflow: 'Context is still too large; reduce attachments or start a new task', sandboxBoundaryClosed: 'Access was not widened; retry the turn to decide again' } },
   },
 } satisfies UiCatalog<DesktopConversationCopy>;
 

apps/desktop/src/renderer/session-error-presentation.ts

@@ -36,6 +36,8 @@ export function describeSessionErrorReason(reason: string | undefined, locale: U
       return copy.auth;
     case 'provider_billing':
       return copy.providerBilling;
+    case 'provider_capacity':
+      return copy.providerCapacity;
     case 'provider_unavailable':
       return copy.provider;
     case 'rate_limit':

apps/desktop/src/renderer/session-status-presentation.ts

@@ -204,6 +204,9 @@ export function deriveFailedTurnRecovery(input: FailedTurnRecoveryInput, locale:
   if (input.toolActivityCount > 0) {
     return { action: 'inspect_tool', label: copy.toolRecord };
   }
+  if (lower === 'provider_capacity') {
+    return { action: 'retry', label: copy.capacity };
+  }
   if (lower === 'context_overflow') {
     return { action: 'continue', label: copy.contextOverflow };
   }

packages/core/src/events.ts

@@ -1096,6 +1096,7 @@ export interface QueueUpdateEvent extends BaseEvent {
 
 export type ProviderRetryReason =
   | 'network'
+  | 'provider_capacity'
   | 'provider_unavailable'
   | 'rate_limit'
   | 'timeout'

packages/runtime-host/src/__tests__/handshake-compatibility.test.ts

@@ -108,7 +108,7 @@ test('receives structured incompatibility guidance from the released v0.1.11 Hos
   );
 });
 
-test('rejects an epoch-23 Host before any domain command', async () => {
+test('rejects an epoch-39 Host before any domain command', async () => {
   let admittedRequest: RequestFrame | undefined;
   await withForgedHandshakePeer(
     async (transport, hostEpoch, rootId) => {
@@ -120,7 +120,7 @@ test('rejects an epoch-23 Host before any domain command', async () => {
         hostEpoch,
         connectionId: 'forged-epoch-connection',
         selectedProtocol: RUNTIME_HOST_PROTOCOL_VERSION,
-        compatibilityEpoch: 23,
+        compatibilityEpoch: 39,
         compositionId: 'maka.interactive',
         compositionRevision: '1',
         state: 'ready',

packages/runtime-host/src/__tests__/protocol.test.ts

@@ -205,8 +205,8 @@ describe('Runtime Host bootstrap protocol', () => {
     );
   });
 
-  test('publishes a new compatibility epoch for typed context compaction outcomes', () => {
-    assert.ok(RUNTIME_HOST_COMPATIBILITY_EPOCH > 39);
+  test('publishes a new compatibility epoch for provider capacity retry progress', () => {
+    assert.ok(RUNTIME_HOST_COMPATIBILITY_EPOCH > 41);
   });
 
   test('selects the highest mutually supported protocol and rejects a gap', () => {

packages/runtime-host/src/protocol/index.ts

@@ -91,7 +91,9 @@ export const RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION = 1 as const;
 export const RUNTIME_HOST_PROTOCOL_VERSION = 0 as const;
 // Increment when the same protocol version no longer guarantees safe Client-Host
 // interoperability. Mismatches are rejected before domain commands are admitted.
-export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 41 as const;
+export const RUNTIME_HOST_COMPATIBILITY_EPOCH = 42 as const;
+// 42: Turn provider retry progress adds `provider_capacity`. Older peers reject
+// that strict retry-reason enum value, so mixed versions must fail handshake.
 // 41: Context compaction returns a typed terminal outcome on both Turn
 // snapshots and context.compact results. Epoch-40 peers reject these closed
 // shapes after admission, so mixed peers must fail during the handshake.

packages/runtime-host/src/protocol/turn.ts

@@ -762,6 +762,7 @@ export function decodeTurnProviderRetry(value: unknown): TurnProviderRetry {
 function requireProviderRetryReason(value: unknown): ProviderRetryReason {
   if (
     value === 'network' ||
+    value === 'provider_capacity' ||
     value === 'provider_unavailable' ||
     value === 'rate_limit' ||
     value === 'timeout' ||