fix(providers): restrict gateway-incompatible mapping to anthropic wire (#158)

The "not implemented" → PROVIDER_GATEWAY_INCOMPATIBLE remap (and the
matching retry short-circuit) only makes sense for Anthropic-compatible
endpoints — the actionable hint tells the user to switch wire to
openai-chat, which is misleading when the user is already on an
OpenAI/Google wire and just hit a transient 501.

Gate both call sites on wire === 'anthropic': non-anthropic wires fall
through to the generic PROVIDER_ERROR path and keep retrying 5xx
normally. Adds counter-example tests on openai-chat / openai-responses.

Signed-off-by: hqhq1025 <1506751656@qq.com>

Author: hqhq1025

packages/core/src/agent.ts

@@ -883,7 +883,7 @@ export async function generateViaAgent(
       ms: Date.now() - sendStart,
       errorClass: err instanceof Error ? err.constructor.name : typeof err,
     });
-    throw remapProviderError(err, input.model.provider);
+    throw remapProviderError(err, input.model.provider, input.wire);
   }
 
   const finalAssistant = findFinalAssistantMessage(agent.state.messages);
@@ -913,6 +913,7 @@ export async function generateViaAgent(
     throw remapProviderError(
       new CodesignError(message, ERROR_CODES.PROVIDER_ERROR),
       input.model.provider,
+      input.wire,
     );
   }
   log.info('[generate] step=send_request.ok', { ...ctx, ms: Date.now() - sendStart });

packages/core/src/errors.test.ts

@@ -83,20 +83,39 @@ describe('remapProviderError', () => {
     expect(out).toBe(err);
   });
 
-  it('tags 5xx "not implemented" bodies as PROVIDER_GATEWAY_INCOMPATIBLE', () => {
+  it('tags 5xx "not implemented" bodies as PROVIDER_GATEWAY_INCOMPATIBLE on anthropic wire', () => {
     const err = httpError(500, 'not implemented');
-    const out = remapProviderError(err, 'anthropic');
+    const out = remapProviderError(err, 'anthropic', 'anthropic');
     expect(out).toBeInstanceOf(CodesignError);
     expect((out as CodesignError).code).toBe('PROVIDER_GATEWAY_INCOMPATIBLE');
     expect((out as CodesignError).message).toContain('not implemented');
   });
 
-  it('tags status-less errors whose message mentions 501 as PROVIDER_GATEWAY_INCOMPATIBLE', () => {
-    const out = remapProviderError(new Error('HTTP 501 from gateway'), 'anthropic');
+  it('tags status-less errors whose message mentions 501 as PROVIDER_GATEWAY_INCOMPATIBLE on anthropic wire', () => {
+    const out = remapProviderError(new Error('HTTP 501 from gateway'), 'anthropic', 'anthropic');
     expect(out).toBeInstanceOf(CodesignError);
     expect((out as CodesignError).code).toBe('PROVIDER_GATEWAY_INCOMPATIBLE');
   });
 
+  it('does NOT remap 5xx "not implemented" to gateway-incompatible on openai-chat wire', () => {
+    const err = httpError(501, 'not implemented');
+    const out = remapProviderError(err, 'openai', 'openai-chat');
+    // Non-anthropic wire: 501 is just a generic upstream error, pass through.
+    expect(out).toBe(err);
+  });
+
+  it('does NOT remap 501 on openai-responses wire even when body matches gateway pattern', () => {
+    const err = httpError(501, 'messages api not supported');
+    const out = remapProviderError(err, 'openai', 'openai-responses');
+    expect(out).toBe(err);
+  });
+
+  it('does NOT remap when wire is undefined (safer default: pass through)', () => {
+    const err = httpError(500, 'not implemented');
+    const out = remapProviderError(err, 'anthropic');
+    expect(out).toBe(err);
+  });
+
   it('extracts status code from CodesignError messages that embed it', () => {
     const err = new CodesignError(
       'HTTP 401 — see https://platform.openai.com/account/api-keys',

packages/core/src/errors.ts

@@ -16,7 +16,7 @@
  */
 
 import { looksLikeGatewayMissingMessagesApi } from '@open-codesign/providers';
-import type { ProviderId } from '@open-codesign/shared';
+import type { ProviderId, WireApi } from '@open-codesign/shared';
 import { CodesignError, ERROR_CODES } from '@open-codesign/shared';
 
 export const PROVIDER_KEY_HELP_URL: Partial<Record<ProviderId, string>> = {
@@ -99,14 +99,22 @@ export function rewriteUpstreamMessage(
  * 4xx errors are rewritten — everything else is rethrown unchanged so the
  * retry/network layer keeps its own taxonomy.
  */
-export function remapProviderError(err: unknown, provider: string | undefined): unknown {
+export function remapProviderError(
+  err: unknown,
+  provider: string | undefined,
+  wire?: WireApi | undefined,
+): unknown {
   if (!(err instanceof Error)) return err;
   if (err instanceof CodesignError && err.code === ERROR_CODES.PROVIDER_ABORTED) return err;
   // Third-party Anthropic relays often reply to POST /v1/messages with 5xx +
   // "not implemented" while their /v1/models endpoint works. Catch that shape
   // before any other classification so the UI can suggest switching wire
-  // instead of the misleading default "check your API key" message.
+  // instead of the misleading default "check your API key" message. Guard on
+  // wire === 'anthropic' because the actionable hint ("switch wire to
+  // openai-chat") only makes sense for Anthropic-compatible endpoints — a 501
+  // from an OpenAI/Google wire is just a generic upstream error.
   if (
+    wire === 'anthropic' &&
     !(err instanceof CodesignError && err.code === ERROR_CODES.PROVIDER_GATEWAY_INCOMPATIBLE) &&
     looksLikeGatewayMissingMessagesApi(err)
   ) {

packages/core/src/index.ts

@@ -368,6 +368,7 @@ async function runModel(input: ModelRunInput): Promise<GenerateOutput> {
           ...(input.onRetry !== undefined ? { onRetry: input.onRetry } : {}),
           logger: log,
           provider: input.model.provider,
+          ...(input.wire !== undefined ? { wire: input.wire } : {}),
         },
         complete,
       );
@@ -396,7 +397,7 @@ async function runModel(input: ModelRunInput): Promise<GenerateOutput> {
         reasoning = undefined;
         continue;
       }
-      const remapped = remapProviderError(err, input.model.provider);
+      const remapped = remapProviderError(err, input.model.provider, input.wire);
       log.error(`[${scope}] step=send_request.fail`, {
         ...ctx,
         ms: Date.now() - sendStart,
@@ -808,6 +809,7 @@ export async function generateTitle(input: GenerateTitleInput): Promise<string>
       {
         logger: log,
         provider: input.model.provider,
+        ...(input.wire !== undefined ? { wire: input.wire } : {}),
       },
     );
     log.info('[title] step=send_request.ok', { ms: Date.now() - started });
@@ -821,6 +823,6 @@ export async function generateTitle(input: GenerateTitleInput): Promise<string>
       ms: Date.now() - started,
       errorClass: err instanceof Error ? err.constructor.name : typeof err,
     });
-    throw remapProviderError(err, input.model.provider);
+    throw remapProviderError(err, input.model.provider, input.wire);
   }
 }

packages/providers/src/retry.test.ts

@@ -24,11 +24,20 @@ describe('classifyError', () => {
   it('marks 5xx as retryable', () => {
     expect(classifyError(new HttpError('boom', 503))).toMatchObject({ retry: true });
   });
-  it('does not retry 5xx when body says Messages API is not implemented', () => {
-    const d = classifyError(new HttpError('500 not implemented', 500));
+  it('does not retry 5xx when body says Messages API is not implemented on anthropic wire', () => {
+    const d = classifyError(new HttpError('500 not implemented', 500), 'anthropic');
     expect(d.retry).toBe(false);
     expect(d.reason).toMatch(/gateway does not implement Messages API/);
   });
+  it('still retries 5xx "not implemented" on openai-chat wire (not a gateway-compat issue)', () => {
+    const d = classifyError(new HttpError('500 not implemented', 500), 'openai-chat');
+    expect(d.retry).toBe(true);
+    expect(d.reason).toMatch(/server error/);
+  });
+  it('still retries 5xx "not implemented" when wire is unknown (safer default)', () => {
+    const d = classifyError(new HttpError('500 not implemented', 500));
+    expect(d.retry).toBe(true);
+  });
   it('marks 4xx (non-429) as non-retryable', () => {
     expect(classifyError(new HttpError('bad', 400))).toMatchObject({ retry: false });
   });

packages/providers/src/retry.ts

@@ -13,7 +13,13 @@
  *   - any AbortSignal abort short-circuits immediately, no retry
  */
 
-import { type ChatMessage, CodesignError, ERROR_CODES, type ModelRef } from '@open-codesign/shared';
+import {
+  type ChatMessage,
+  CodesignError,
+  ERROR_CODES,
+  type ModelRef,
+  type WireApi,
+} from '@open-codesign/shared';
 import { normalizeProviderError } from './errors';
 import { looksLikeGatewayMissingMessagesApi } from './gateway-compat';
 import { type GenerateOptions, type GenerateResult, complete } from './index';
@@ -32,6 +38,7 @@ export interface CompleteWithRetryOptions {
   onRetry?: (info: RetryReason) => void;
   logger?: { warn: (event: string, data?: Record<string, unknown>) => void };
   provider?: string;
+  wire?: WireApi;
 }
 
 const DEFAULT_MAX_RETRIES = 3;
@@ -51,7 +58,7 @@ const RETRYABLE_NET_CODES = new Set([
   'ECONNREFUSED',
 ]);
 
-function classifyByStatus(status: number, err: unknown): RetryDecision | undefined {
+function classifyByStatus(status: number, err: unknown, wire?: WireApi): RetryDecision | undefined {
   if (status === 429) {
     const retryAfterMs = extractRetryAfterMs(err);
     const decision: RetryDecision = { retry: true, reason: 'rate-limited (429)' };
@@ -63,8 +70,10 @@ function classifyByStatus(status: number, err: unknown): RetryDecision | undefin
     // return 5xx + "not implemented" for POST /v1/messages even though their
     // /v1/models endpoint works. Retrying wastes 3 rounds of exponential
     // backoff on an endpoint that will never respond; short-circuit so the
-    // user sees the actionable error immediately.
-    if (looksLikeGatewayMissingMessagesApi(err)) {
+    // user sees the actionable error immediately. Only applies to
+    // anthropic-wire endpoints — OpenAI/Google wires can emit the same text
+    // for unrelated reasons and should retry normally.
+    if (wire === 'anthropic' && looksLikeGatewayMissingMessagesApi(err)) {
       return { retry: false, reason: 'gateway does not implement Messages API' };
     }
     return { retry: true, reason: `server error (${status})` };
@@ -85,13 +94,13 @@ function classifyByNetwork(err: unknown): RetryDecision | undefined {
   return undefined;
 }
 
-export function classifyError(err: unknown): RetryDecision {
+export function classifyError(err: unknown, wire?: WireApi): RetryDecision {
   if (err instanceof Error && (err.name === 'AbortError' || err.message === 'aborted')) {
     return { retry: false, reason: 'aborted' };
   }
   const status = extractStatus(err);
   if (status !== undefined) {
-    const byStatus = classifyByStatus(status, err);
+    const byStatus = classifyByStatus(status, err, wire);
     if (byStatus) return byStatus;
   }
   const byNet = classifyByNetwork(err);
@@ -289,7 +298,7 @@ export async function completeWithRetry(
     maxRetries,
     baseDelayMs,
     classify: (err) => {
-      const decision = classifyError(err);
+      const decision = classifyError(err, retryOpts.wire);
       const retryCount = Math.max(0, attemptForLog - 1);
       const normalized = normalizeProviderError(err, provider, retryCount);
       if (shouldStop(decision, attemptForLog, maxRetries)) {