fix(web): surface BYOK migration validation errors (#6280)

* fix(web): surface BYOK migration validation errors

Preserve structured daemon errors during legacy credential migration and reserve offline guidance for fetch failures.

Keep legacy browser credentials until migration succeeds, and cover HTTP validation, malformed responses, and network failures.

Validated with focused web tests, web typecheck, workspace guard, and workspace typecheck.

* fix(web): stabilize BYOK persistence error telemetry

Map secure-profile HTTP and network failures to semantic error codes before emitting settings_byok_test_result, while preserving existing fallback behavior for unrelated connection-test errors.

Validated with the complete web test suite, web typecheck, workspace typecheck, guard, and git diff --check.

---------

Co-authored-by: Cheems <94773058+itscheems@users.noreply.github.com>

Author: open-design-crew[bot]

apps/web/src/App.tsx

@@ -82,6 +82,7 @@ import {
   fetchMediaProvidersFromDaemon,
   hasAnyConfiguredProvider,
   fetchComposioConfigFromDaemon,
+  legacyByokMigrationErrorPresentation,
   loadConfig,
   migrateLegacyByokCredentialsToDaemon,
   mergeDaemonConfig,
@@ -454,7 +455,7 @@ function AppInner() {
   const [workingDirError, setWorkingDirError] = useState<string | null>(null);
   const [projectOpenError, setProjectOpenError] = useState<string | null>(null);
   const [legacyByokMigrationError, setLegacyByokMigrationError] =
-    useState<string | null>(null);
+    useState<Error | null>(null);
   const [settingsWelcome, setSettingsWelcome] = useState(false);
   const [settingsInitialSection, setSettingsInitialSection] = useState<SettingsSection>('execution');
   const [settingsHighlight, setSettingsHighlight] = useState<SettingsHighlight>(null);
@@ -1013,7 +1014,7 @@ function AppInner() {
       if (cancelled) return;
       setLegacyByokMigrationError(
         legacyByokMigration.status === 'failed'
-          ? legacyByokMigration.error.message
+          ? legacyByokMigration.error
           : null,
       );
       const migrationBaseConfig = legacyByokMigration.config;
@@ -2629,6 +2630,12 @@ function AppInner() {
       />
     );
   }
+  const legacyByokMigrationErrorView = legacyByokMigrationError
+    ? legacyByokMigrationErrorPresentation(
+        legacyByokMigrationError,
+        t('settings.autosaveError'),
+      )
+    : null;
   return (
     <>
       <div
@@ -2739,10 +2746,10 @@ function AppInner() {
           onDismiss={() => setProjectOpenError(null)}
         />
       ) : null}
-      {legacyByokMigrationError ? (
+      {legacyByokMigrationErrorView ? (
         <Toast
-          message={t('settings.autosaveError')}
-          details={legacyByokMigrationError}
+          message={legacyByokMigrationErrorView.message}
+          details={legacyByokMigrationErrorView.details}
           actionLabel={t('settings.title')}
           onAction={() => {
             setLegacyByokMigrationError(null);

apps/web/src/components/SettingsDialog.tsx

@@ -74,6 +74,7 @@ import {
 } from './modelOptions';
 import {
   BYOK_PROVIDER_PRESETS,
+  classifyByokCredentialProfileFailure,
   DEFAULT_NOTIFICATIONS,
   DEFAULT_ORBIT,
   applySavedByokCredentialProfile,
@@ -2669,13 +2670,14 @@ export function SettingsDialog({
       });
       const byokProviderId = byokProtocolToTracking(apiProtocol);
       if (byokProviderId) {
+        const failure = classifyByokCredentialProfileFailure(err);
         trackSettingsByokTestResult(analytics.track, {
           page_name: 'settings',
           area: 'execution_model',
           provider_id: byokProviderId,
           result: 'failed',
-          error_code: err instanceof Error ? err.name : 'UNKNOWN',
-          error_kind: err instanceof Error ? err.name : 'UNKNOWN',
+          error_code: failure.errorCode,
+          error_kind: failure.errorKind,
           field_missing: 'none',
           config_key_changed: configKeyChanged,
           success_after_action: false,

apps/web/src/state/config.ts

@@ -848,16 +848,111 @@ export async function fetchByokCredentialProfilesFromDaemon(): Promise<
   }
 }
 
+export class ByokCredentialProfileHttpError extends Error {
+  readonly status: number;
+  readonly code?: string;
+
+  constructor(status: number, message: string, code?: string) {
+    super(message);
+    this.name = 'ByokCredentialProfileHttpError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export class ByokCredentialProfileNetworkError extends Error {
+  constructor(message: string, cause: unknown) {
+    super(message, { cause });
+    this.name = 'ByokCredentialProfileNetworkError';
+  }
+}
+
+export function classifyByokCredentialProfileFailure(error: unknown): {
+  errorCode: string;
+  errorKind: string;
+} {
+  if (error instanceof ByokCredentialProfileHttpError) {
+    return {
+      errorCode: error.code || `HTTP_${error.status}`,
+      errorKind: 'unknown',
+    };
+  }
+  if (error instanceof ByokCredentialProfileNetworkError) {
+    return {
+      errorCode: 'DAEMON_UNREACHABLE',
+      errorKind: 'unknown',
+    };
+  }
+  const fallback = error instanceof Error ? error.name : 'UNKNOWN';
+  return { errorCode: fallback, errorKind: fallback };
+}
+
+export function legacyByokMigrationErrorPresentation(
+  error: Error,
+  daemonUnavailableMessage: string,
+): { message: string; details?: string } {
+  if (error instanceof ByokCredentialProfileNetworkError) {
+    return {
+      message: daemonUnavailableMessage,
+      details: error.message,
+    };
+  }
+  return { message: error.message };
+}
+
+async function byokCredentialProfileHttpError(
+  response: Response,
+): Promise<ByokCredentialProfileHttpError> {
+  const fallback = `Failed to save BYOK credential (${response.status})`;
+  try {
+    const payload = await response.json() as unknown;
+    if (
+      payload
+      && typeof payload === 'object'
+      && 'error' in payload
+      && payload.error
+      && typeof payload.error === 'object'
+    ) {
+      const message = 'message' in payload.error
+        && typeof payload.error.message === 'string'
+        ? payload.error.message.trim()
+        : '';
+      const code = 'code' in payload.error
+        && typeof payload.error.code === 'string'
+        ? payload.error.code.trim()
+        : '';
+      if (message) {
+        return new ByokCredentialProfileHttpError(
+          response.status,
+          message,
+          code || undefined,
+        );
+      }
+    }
+  } catch {
+    // Keep the status-bearing fallback when the daemon/proxy body is invalid.
+  }
+  return new ByokCredentialProfileHttpError(response.status, fallback);
+}
+
 export async function persistByokCredentialProfileToDaemon(
   input: UpsertByokCredentialProfileRequest,
 ): Promise<ByokCredentialProfile> {
-  const response = await fetch('/api/byok/profiles', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify(input),
-  });
+  let response: Response;
+  try {
+    response = await fetch('/api/byok/profiles', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(input),
+    });
+  } catch (error) {
+    const message = error instanceof Error && error.message.trim()
+      ? error.message
+      : 'Failed to reach the local daemon while saving the BYOK credential.';
+    throw new ByokCredentialProfileNetworkError(message, error);
+  }
   if (!response.ok) {
-    throw new Error(`Failed to save BYOK credential (${response.status})`);
+    throw await byokCredentialProfileHttpError(response);
   }
   const payload = await response.json() as { profile?: ByokCredentialProfile };
   if (!payload.profile?.id || !payload.profile.configured) {

apps/web/tests/components/SettingsDialog.execution.test.tsx

@@ -112,6 +112,7 @@ import { reconcileAmrProfileEnv } from '../../src/components/SettingsDialog';
 import { providerModelsCacheKey } from '../../src/components/providerModelsCache';
 import { I18nProvider } from '../../src/i18n';
 import { LOCALES } from '../../src/i18n/types';
+import { ByokCredentialProfileHttpError } from '../../src/state/config';
 import { MAX_MAX_TOKENS, MIN_MAX_TOKENS } from '../../src/state/maxTokens';
 import type {
   AgentInfo,
@@ -2380,6 +2381,60 @@ describe('SettingsDialog execution settings BYOK interactions', () => {
     );
   });
 
+  it('reports secure profile persistence failures with stable BYOK telemetry', async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
+      const url = input.toString();
+      if (url === '/api/memory') {
+        return new Response(
+          JSON.stringify({ enabled: true, memories: [], extraction: null }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        );
+      }
+      expect(url).toBe('/api/test/connection');
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          kind: 'ok',
+          latencyMs: 20,
+          model: 'claude-sonnet-4-5',
+          sample: 'pong',
+        }),
+        { status: 200, headers: { 'content-type': 'application/json' } },
+      );
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { onPersistByokCredential } = renderSettingsDialog({
+      apiKey: 'sk-ant-test-provider',
+    });
+    onPersistByokCredential.mockRejectedValueOnce(
+      new ByokCredentialProfileHttpError(
+        400,
+        'Invalid secure profile',
+        'VALIDATION_FAILED',
+      ),
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'Test' }));
+
+    await waitFor(() => {
+      expect(analyticsTrackMock).toHaveBeenCalledWith(
+        'settings_byok_test_result',
+        expect.objectContaining({
+          page_name: 'settings',
+          area: 'execution_model',
+          provider_id: 'anthropic',
+          result: 'failed',
+          error_code: 'VALIDATION_FAILED',
+          error_kind: 'unknown',
+          field_missing: 'none',
+          success_after_action: false,
+        }),
+        undefined,
+      );
+    });
+  });
+
   it('renders invalid Base URL test failures on the Base URL field', async () => {
     const fetchMock = vi.fn(async (input: RequestInfo | URL) => {
       const url = input.toString();