Improve provider auth diagnostics

Author: eddmpython

docs/skills/architecture/live-provider-ops.md

@@ -40,6 +40,8 @@ Codaro의 기본 gate는 deterministic scripted provider를 사용한다. 실제
 - network timeout/connection: 네트워크 문제.
 - endpoint/header/SSE 변경: OAuth provider compatibility 점검 필요.
 
+HTTP/stream/UI 경계에는 `code`, `message`, `action`, `provider`, `detail`, `recoverable`을 가진 진단 payload를 넘긴다. 기본 화면은 `message`만 보여주고, raw detail은 trace나 확장 진단에서만 본다. editor는 `connect-provider`, `relogin-provider`, `restart-login`, `check-network`, `check-provider-compatibility` action을 구분해 설정 열기/재로그인/네트워크 점검/호환성 점검으로 안내한다.
+
 ## Live Smoke Gate
 
 명령:

editor/src/hooks/useAssistantTurnState.ts

@@ -225,8 +225,7 @@ export function useAssistantTurnState({
       }
       onNotice(application.notice);
     } catch (error) {
-      const detail = error instanceof Error ? error.message : String(error);
-      const failure = providerAssistantFailure(detail);
+      const failure = providerAssistantFailure(error);
       setMessages((current) => failAssistantMessage({
         action: failure.action,
         assistantMessageId,

editor/src/hooks/useProviderConnection.ts

@@ -45,8 +45,7 @@ export function useProviderConnection({
       onNotice({ tone: "default", title: "Provider 로그인 열림", detail: "새 탭에서 provider 로그인을 완료하세요." });
       applyProviderActionResult(await loginOauthProvider(providerId));
     } catch (error) {
-      const detail = error instanceof Error ? error.message : String(error);
-      onNotice(providerAuthFailureNotice(detail));
+      onNotice(providerAuthFailureNotice(error));
     } finally {
       setAiConnecting(false);
     }

editor/src/lib/api.ts

@@ -17,6 +17,8 @@ import type {
   OauthStatusPayload,
   PackageInfo,
   PackageInstallResult,
+  ProviderDiagnostic,
+  ProviderValidationPayload,
   ProgressSummary,
   SchedulerStatus,
   TaskListPayload,
@@ -32,6 +34,18 @@ import {
 
 const configuredApiBase = import.meta.env.VITE_CODARO_API_BASE?.replace(/\/$/, "") ?? "";
 
+export class CodaroApiError extends Error {
+  readonly status: number;
+  readonly diagnostic?: ProviderDiagnostic;
+
+  constructor(status: number, message: string, diagnostic?: ProviderDiagnostic) {
+    super(message);
+    this.name = "CodaroApiError";
+    this.status = status;
+    this.diagnostic = diagnostic;
+  }
+}
+
 export function shouldUseApi() {
   if (configuredApiBase) return true;
   if (typeof window === "undefined") return true;
@@ -49,20 +63,16 @@ async function requestJson<T>(path: string, init?: RequestInit): Promise<T> {
 
   if (!response.ok) {
     let detail = response.statusText;
+    let diagnostic: ProviderDiagnostic | undefined;
     try {
-      const payload = (await response.json()) as {
-        detail?: string;
-        message?: string;
-        error?: {
-          code?: string;
-          message?: string;
-        };
-      };
-      detail = payload.detail ?? payload.message ?? payload.error?.message ?? detail;
+      const payload = (await response.json()) as ApiErrorPayload;
+      const parsed = parseApiErrorPayload(payload, detail);
+      detail = parsed.message;
+      diagnostic = parsed.diagnostic;
     } catch {
       detail = response.statusText;
     }
-    throw new Error(`${response.status} ${detail}`);
+    throw new CodaroApiError(response.status, `${response.status} ${detail}`, diagnostic);
   }
 
   if (response.status === 204) {
@@ -103,17 +113,16 @@ async function postStreamChat(
 
   if (!response.ok) {
     let detail = response.statusText;
+    let diagnostic: ProviderDiagnostic | undefined;
     try {
-      const payload = (await response.json()) as {
-        detail?: string;
-        message?: string;
-        error?: { message?: string };
-      };
-      detail = payload.detail ?? payload.message ?? payload.error?.message ?? detail;
+      const payload = (await response.json()) as ApiErrorPayload;
+      const parsed = parseApiErrorPayload(payload, detail);
+      detail = parsed.message;
+      diagnostic = parsed.diagnostic;
     } catch {
       detail = response.statusText;
     }
-    throw new Error(`${response.status} ${detail}`);
+    throw new CodaroApiError(response.status, `${response.status} ${detail}`, diagnostic);
   }
 
   if (!response.body) {
@@ -149,7 +158,7 @@ async function postStreamChat(
   }
 
   if (streamState.error) {
-    throw new Error(streamState.error);
+    throw new CodaroApiError(503, streamState.error, streamState.diagnostic);
   }
 
   if (!streamState.donePayload) {
@@ -228,6 +237,11 @@ export const codaroApi = {
   aiProviders: () => requestJson<AiProviderCatalogPayload>("/api/ai/providers"),
   aiTools: () => requestJson<AiToolCatalogPayload>("/api/ai/tools"),
   aiProfile: () => requestJson<AiProfile>("/api/ai/profile"),
+  validateAiProvider: (provider: string, model?: string | null) => {
+    const params = new URLSearchParams({ provider });
+    if (model) params.set("model", model);
+    return postJson<ProviderValidationPayload>(`/api/ai/provider/validate?${params.toString()}`, {});
+  },
   updateAiProfile: (payload: {
     provider?: string | null;
     model?: string | null;
@@ -251,6 +265,38 @@ export const codaroApi = {
   requestJson,
 };
 
+type ApiErrorPayload = {
+  detail?: string | ProviderDiagnostic;
+  message?: string;
+  error?: ProviderDiagnostic;
+};
+
+function parseApiErrorPayload(payload: ApiErrorPayload, fallback: string): {
+  message: string;
+  diagnostic?: ProviderDiagnostic;
+} {
+  const detail = payload.detail;
+  if (isProviderDiagnostic(detail)) {
+    return {
+      message: detail.message ?? fallback,
+      diagnostic: detail,
+    };
+  }
+  if (payload.error) {
+    return {
+      message: payload.error.message ?? payload.message ?? fallback,
+      diagnostic: payload.error,
+    };
+  }
+  return {
+    message: typeof detail === "string" ? detail : payload.message ?? fallback,
+  };
+}
+
+function isProviderDiagnostic(value: unknown): value is ProviderDiagnostic {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 export async function optional<T>(load: () => Promise<T>, fallback: T): Promise<{ data: T; online: boolean; error?: string }> {
   try {
     return { data: await load(), online: true };

editor/src/lib/assistantStream.ts

@@ -1,4 +1,4 @@
-import type { AiChatRequest, AiChatResponse } from "@/types";
+import type { AiChatRequest, AiChatResponse, ProviderDiagnostic } from "@/types";
 
 export type StreamEvent = {
   type?: string;
@@ -13,12 +13,14 @@ export type StreamEvent = {
   toolCalls?: AiChatResponse["toolCalls"];
   trace?: AiChatResponse["trace"];
   error?: string;
+  diagnostic?: ProviderDiagnostic;
 };
 
 export type AssistantStreamState = {
   conversationId: string;
   donePayload: AiChatResponse | null;
   error: string | null;
+  diagnostic?: ProviderDiagnostic;
 };
 
 export function initialAssistantStreamState(request: AiChatRequest): AssistantStreamState {
@@ -39,6 +41,7 @@ export function applyAssistantStreamProtocolEvent(
       ...state,
       conversationId,
       error: event.error ?? "provider stream failed",
+      diagnostic: event.diagnostic,
     };
   }
   if (event.type === "done") {

editor/src/lib/providerConnection.ts

@@ -1,5 +1,5 @@
-import { codaroApi } from "@/lib/api";
-import type { AiProfile, AppNotice } from "@/types";
+import { CodaroApiError, codaroApi } from "@/lib/api";
+import type { AiProfile, AppNotice, ProviderDiagnostic, ProviderValidationPayload } from "@/types";
 
 export type ProviderActionResult = {
   closeSettings?: boolean;
@@ -45,13 +45,18 @@ export async function loginOauthProvider(providerId = "oauth-chatgpt"): Promise<
     await sleep(1000);
     const status = await codaroApi.oauthStatus();
     if (!status.done) continue;
-    if (status.error) throw new Error(status.error);
+    if (status.error) {
+      throw new CodaroApiError(
+        Number(status.diagnostic?.statusCode ?? 503),
+        status.message ?? status.error,
+        status.diagnostic ?? undefined,
+      );
+    }
     const profile = await codaroApi.aiProfile();
-    return {
+    return withProviderValidation(profile, {
       closeSettings: true,
-      notice: { tone: "success", title: "Provider 연결됨", detail: providerName(profile) },
       profile,
-    };
+    });
   }
 
   return {
@@ -75,10 +80,9 @@ export async function logoutOauthProvider(providerId = "oauth-chatgpt"): Promise
 export async function selectProvider(providerId: string): Promise<ProviderActionResult> {
   const profile = await codaroApi.updateAiProfile({ provider: providerId });
   const latestProfile = await codaroApi.aiProfile().catch(() => profile);
-  return {
-    notice: { tone: "success", title: "Provider 선택됨", detail: providerName(latestProfile) },
+  return withProviderValidation(latestProfile, {
     profile: latestProfile,
-  };
+  });
 }
 
 export async function saveApiProvider(providerId: string, apiKey: string, baseUrl?: string): Promise<ProviderActionResult> {
@@ -87,38 +91,43 @@ export async function saveApiProvider(providerId: string, apiKey: string, baseUr
   }
   const profile = await codaroApi.saveAiSecret(providerId, apiKey);
   const latestProfile = await codaroApi.aiProfile().catch(() => profile);
-  return {
-    notice: { tone: "success", title: "Provider 연결됨", detail: providerName(latestProfile) },
+  return withProviderValidation(latestProfile, {
     profile: latestProfile,
-  };
+  });
 }
 
-export function providerAuthFailureNotice(detail: string): AppNotice {
+export function providerAuthFailureNotice(error: unknown): AppNotice {
+  const diagnostic = providerDiagnosticFromError(error);
   return {
     tone: "error",
     title: "Provider 로그인 실패",
-    detail: isProviderAuthError(detail) ? "provider 로그인을 다시 시작하세요." : detail,
+    detail: diagnostic?.message ?? errorMessage(error),
   };
 }
 
-export function providerAssistantFailure(detail: string): ProviderAssistantFailure {
-  const authIssue = isProviderAuthError(detail);
+export function providerAssistantFailure(error: unknown): ProviderAssistantFailure {
+  const diagnostic = providerDiagnosticFromError(error);
+  const authIssue = isProviderAuthError(error);
   const content = authIssue
-    ? "provider 로그인이 필요합니다. Provider 설정에서 브라우저 로그인을 완료한 뒤 다시 요청하세요."
-    : detail;
+    ? diagnostic?.message ?? "Provider 로그인이 필요합니다. Provider 설정에서 브라우저 로그인을 완료한 뒤 다시 요청하세요."
+    : diagnostic?.message ?? errorMessage(error);
   return {
     action: authIssue ? "connect-provider" : undefined,
     content,
     notice: {
       tone: "error",
-      title: authIssue ? "Provider 연결 필요" : "AI 사용 불가",
+      title: authIssue ? "Provider 연결 필요" : "Provider 사용 불가",
       detail: content,
     },
   };
 }
 
-export function isProviderAuthError(detail: string) {
-  const normalized = detail.toLowerCase();
+export function isProviderAuthError(error: unknown) {
+  const diagnostic = providerDiagnosticFromError(error);
+  if (diagnostic?.action && ["connect-provider", "relogin-provider", "restart-login"].includes(diagnostic.action)) {
+    return true;
+  }
+  const normalized = errorMessage(error).toLowerCase();
   return (
     normalized.includes("oauth authentication required") ||
     normalized.includes("authentication expired") ||
@@ -132,10 +141,69 @@ export function isProviderAuthError(detail: string) {
   );
 }
 
+function providerDiagnosticFromError(error: unknown): ProviderDiagnostic | undefined {
+  if (error instanceof CodaroApiError) return error.diagnostic;
+  if (isRecord(error) && isRecord(error.diagnostic)) return error.diagnostic as ProviderDiagnostic;
+  return undefined;
+}
+
+async function withProviderValidation(
+  profile: AiProfile,
+  base: Omit<ProviderActionResult, "notice">,
+): Promise<ProviderActionResult> {
+  const provider = String(profile.activeProvider ?? profile.defaultProvider ?? "");
+  if (!provider) {
+    return {
+      ...base,
+      notice: { tone: "warning", title: "Provider 확인 필요", detail: "선택된 provider가 없습니다." },
+    };
+  }
+  const validation = await validateProvider(provider, profile.activeModel);
+  if (validation.valid) {
+    return {
+      ...base,
+      notice: {
+        tone: "success",
+        title: "Provider 연결됨",
+        detail: validation.model ? `${provider} · ${validation.model}` : providerName(profile),
+      },
+    };
+  }
+  return {
+    ...base,
+    notice: {
+      tone: "warning",
+      title: "Provider 확인 필요",
+      detail: validation.diagnostic?.message ?? validation.error ?? "Provider 연결 상태를 확인하지 못했습니다.",
+    },
+  };
+}
+
+async function validateProvider(provider: string, model?: unknown): Promise<ProviderValidationPayload> {
+  try {
+    return await codaroApi.validateAiProvider(provider, typeof model === "string" ? model : undefined);
+  } catch (error) {
+    const diagnostic = providerDiagnosticFromError(error);
+    return {
+      valid: false,
+      error: diagnostic?.message ?? errorMessage(error),
+      diagnostic,
+    };
+  }
+}
+
+function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function providerName(profile: AiProfile | null) {
   return String(profile?.activeProvider ?? profile?.provider ?? profile?.defaultProvider ?? "provider 없음");
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 function sleep(milliseconds: number) {
   return new Promise((resolve) => window.setTimeout(resolve, milliseconds));
 }

editor/src/types.ts

@@ -234,6 +234,23 @@ export type AiProviderCatalogPayload = {
   catalog: AiProvider[] | Record<string, AiProvider>;
 };
 
+export type ProviderDiagnostic = {
+  code?: string;
+  message?: string;
+  action?: string;
+  provider?: string;
+  detail?: string;
+  recoverable?: boolean;
+  statusCode?: number;
+};
+
+export type ProviderValidationPayload = {
+  valid: boolean;
+  model?: string | null;
+  error?: string | null;
+  diagnostic?: ProviderDiagnostic | null;
+};
+
 export type AiToolCatalogPayload = {
   groups: Array<{
     id: string;
@@ -367,6 +384,8 @@ export type OauthAuthorizePayload = {
 export type OauthStatusPayload = {
   done: boolean;
   error?: string | null;
+  message?: string | null;
+  diagnostic?: ProviderDiagnostic | null;
 };
 
 export type AppNotice = {