fix(oauth): include the transport root cause in connection error messages

.changeset/oauth-connection-error-cause.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Include the underlying network cause (DNS failure, refused connection, TLS or timeout errors) in OAuth connection error messages instead of a bare "fetch failed".

packages/oauth/src/errors.ts

@@ -16,8 +16,8 @@
  */
 
 export class OAuthError extends Error {
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
     this.name = 'OAuthError';
   }
 }
@@ -30,8 +30,8 @@ export class OAuthUnauthorizedError extends OAuthError {
 }
 
 export class OAuthConnectionError extends OAuthError {
-  constructor(message: string) {
-    super(message);
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
     this.name = 'OAuthConnectionError';
   }
 }

packages/oauth/src/oauth.ts

@@ -82,7 +82,8 @@ async function postForm(
     });
   } catch (error) {
     throw new OAuthConnectionError(
-      `OAuth request to ${url} failed: ${error instanceof Error ? error.message : String(error)}`,
+      `OAuth request to ${url} failed: ${describeFetchFailure(error)}`,
+      { cause: error },
     );
   }
   const status = response.status;
@@ -96,6 +97,23 @@ async function postForm(
   return { status, data };
 }
 
+/**
+ * Flatten a fetch rejection into a readable message. undici throws a generic
+ * `TypeError: fetch failed` and hides the real reason (DNS, refused, TLS,
+ * timeout) in a nested `cause` chain — walk it so the surfaced message names
+ * the actual failure instead of just "fetch failed".
+ */
+function describeFetchFailure(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  const messages = new Set<string>();
+  let current: Error | undefined = error;
+  while (current !== undefined) {
+    messages.add(current.message);
+    current = current.cause instanceof Error ? current.cause : undefined;
+  }
+  return [...messages].join(': ');
+}
+
 // ── requestDeviceAuthorization ────────────────────────────────────────
 
 export async function requestDeviceAuthorization(

packages/oauth/test/oauth.test.ts

@@ -575,6 +575,27 @@ describe('refreshAccessToken', () => {
     ).rejects.toBeInstanceOf(OAuthConnectionError);
   });
 
+  it('names the transport root cause in the connection error message', async () => {
+    const badConfig: OAuthFlowConfig = {
+      ...flowConfig(),
+      oauthHost: 'http://127.0.0.1:1', // reserved port, ECONNREFUSED
+    };
+
+    const failure = await refreshToken(badConfig, 'rt', {
+      maxRetries: 1,
+      backoffMs: () => 0,
+    }).catch((error: unknown) => error);
+
+    expect(failure).toBeInstanceOf(OAuthConnectionError);
+    const error = failure as OAuthConnectionError;
+    expect(error.cause).toBeInstanceOf(Error);
+    // The undici root cause (e.g. `connect ECONNREFUSED 127.0.0.1:1`) must be
+    // visible in the surfaced message, not just the generic "fetch failed".
+    const rootCause = error.cause instanceof Error ? error.cause : undefined;
+    expect(rootCause?.message).toBeTruthy();
+    expect(error.message).toContain(rootCause?.message);
+  });
+
   it('sends grant_type=refresh_token + refresh_token', async () => {
     server.enqueue('/api/oauth/token', {
       status: 200,