fix: address multiple bugs from issue #79

- text/chat: warn instead of silent skip on SSE parse errors
- text/chat: add SSE content-type validation before parsing
- text/chat: proper error handling for tool JSON parsing
- poll: include API failure context in task failed error
- auth/refresh: add retry with exponential backoff (2 retries)
- output/audio: validate audio hex before Buffer.from, handle ENOSPC
- vision/describe: add 50MB size limit before base64 encoding
- speech/voices: fix greedy language filter (substring → prefix match)
- image/generate: warn on file overwrite, respect --output json in quiet
- config/detect-region: improve fallback error message

Fixes #79

Author: NianJiuZst

src/auth/refresh.ts

@@ -6,45 +6,68 @@ import { ExitCode } from "../errors/codes";
 // OAuth config — endpoints TBD pending MiniMax OAuth documentation
 const TOKEN_URL = "https://api.minimax.io/v1/oauth/token";
 
+const MAX_REFRESH_RETRIES = 2;
+const RETRY_DELAY_MS = 500;
+
 export async function refreshAccessToken(
   refreshToken: string,
 ): Promise<OAuthTokens> {
-  let res: Response;
-  try {
-    res = await fetch(TOKEN_URL, {
-      method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded" },
-      body: new URLSearchParams({
-        grant_type: "refresh_token",
-        refresh_token: refreshToken,
-      }),
-      signal: AbortSignal.timeout(10_000),
-    });
-  } catch (err) {
-    const isTimeout =
-      err instanceof Error &&
-      (err.name === "AbortError" ||
-        err.name === "TimeoutError" ||
-        err.message.includes("timed out"));
-    throw new CLIError(
-      isTimeout
-        ? "Token refresh timed out — auth server did not respond within 10 s."
-        : `Token refresh failed: ${err instanceof Error ? err.message : String(err)}`,
-      ExitCode.AUTH,
-      "Check your network connection.\nRe-authenticate: mmx auth login",
-    );
-  }
+  let lastErr: Error | null = null;
+
+  for (let attempt = 0; attempt <= MAX_REFRESH_RETRIES; attempt++) {
+    if (attempt > 0) {
+      // Exponential backoff before retry
+      await new Promise(r => setTimeout(r, RETRY_DELAY_MS * attempt));
+    }
+
+    let res: Response;
+    try {
+      res = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: refreshToken,
+        }),
+        signal: AbortSignal.timeout(10_000),
+      });
+    } catch (err) {
+      const isTimeout =
+        err instanceof Error &&
+        (err.name === "AbortError" ||
+          err.name === "TimeoutError" ||
+          err.message.includes("timed out"));
+      lastErr = new Error(
+        isTimeout
+          ? "Token refresh timed out — auth server did not respond within 10 s."
+          : `Token refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      continue; // retry
+    }
+
+    if (!res.ok) {
+      // 4xx errors won't recover with retry
+      if (res.status >= 400 && res.status < 500) {
+        throw new CLIError(
+          "OAuth session expired and could not be refreshed.",
+          ExitCode.AUTH,
+          "Re-authenticate: mmx auth login",
+        );
+      }
+      lastErr = new Error(`Token refresh failed: HTTP ${res.status}`);
+      continue; // retry 5xx errors
+    }
 
-  if (!res.ok) {
-    throw new CLIError(
-      "OAuth session expired and could not be refreshed.",
-      ExitCode.AUTH,
-      "Re-authenticate: mmx auth login",
-    );
+    const data = (await res.json()) as OAuthTokens;
+    return data;
   }
 
-  const data = (await res.json()) as OAuthTokens;
-  return data;
+  // All retries exhausted
+  throw new CLIError(
+    `Token refresh failed after ${MAX_REFRESH_RETRIES + 1} attempts: ${lastErr?.message}`,
+    ExitCode.AUTH,
+    "Check your network connection.\nRe-authenticate: mmx auth login",
+  );
 }
 
 export async function ensureFreshToken(creds: CredentialFile): Promise<string> {

src/commands/image/generate.ts

@@ -158,11 +158,26 @@ export default defineCommand({
     for (let i = 0; i < imageUrls.length; i++) {
       const filename = `${prefix}_${String(i + 1).padStart(3, '0')}.jpg`;
       const destPath = join(outDir, filename);
+
+      // Warn if overwriting existing file (but don't block)
+      if (existsSync(destPath)) {
+        process.stderr.write(`Warning: overwriting existing file: ${destPath}\n`);
+      }
+
       await downloadFile(imageUrls[i]!, destPath, { quiet: config.quiet });
       saved.push(destPath);
     }
 
-    if (config.quiet) {
+    // --output json is respected even in --quiet mode (JSON is the actual output, not progress)
+    if (format === 'json') {
+      console.log(formatOutput({
+        id: response.data.task_id,
+        saved,
+        success_count: response.data.success_count,
+        failed_count: response.data.failed_count,
+      }, format));
+    } else if (config.quiet) {
+      // Non-JSON quiet mode: just print file paths
       console.log(saved.join('\n'));
     } else {
       console.log(formatOutput({

src/commands/speech/voices.ts

@@ -15,7 +15,11 @@ function extractLanguage(voiceId: string): string {
 
 function filterByLanguage(voices: SystemVoiceInfo[], language: string): SystemVoiceInfo[] {
   const lang = language.toLowerCase();
-  return voices.filter(v => extractLanguage(v.voice_id).toLowerCase().includes(lang));
+  return voices.filter(v => {
+    const voiceLang = extractLanguage(v.voice_id).toLowerCase();
+    // Exact prefix match: "english" matches "English_*" but not "Korean_*"
+    return voiceLang === lang || voiceLang.startsWith(lang + '_') || voiceLang.startsWith(lang + ' (');
+  });
 }
 
 export default defineCommand({

src/commands/text/chat.ts

@@ -3,6 +3,8 @@ import { request, requestJson } from '../../client/http';
 import { chatEndpoint } from '../../client/endpoints';
 import { parseSSE } from '../../client/stream';
 import { formatOutput, detectOutputFormat } from '../../output/formatter';
+import { CLIError } from '../../errors/base';
+import { ExitCode } from '../../errors/codes';
 import type { Config } from '../../config/schema';
 import type { GlobalFlags } from '../../types/flags';
 import type {
@@ -139,8 +141,16 @@ export default defineCommand({
         try {
           return JSON.parse(t);
         } catch {
-          const raw = readFileSync(t, 'utf-8');
-          return JSON.parse(raw);
+          // Not JSON — treat as file path
+          try {
+            const raw = readFileSync(t, 'utf-8');
+            return JSON.parse(raw);
+          } catch {
+            throw new CLIError(
+              `Invalid tool definition: "${t}" is neither valid JSON nor a readable file.`,
+              ExitCode.USAGE,
+            );
+          }
         }
       });
       body.tools = tools;
@@ -162,6 +172,15 @@ export default defineCommand({
         authStyle: 'x-api-key',
       });
 
+      // Validate response is actually SSE before attempting to parse
+      const contentType = res.headers.get('content-type') || '';
+      if (!contentType.includes('text/event-stream') && !contentType.includes('stream')) {
+        throw new CLIError(
+          `Expected SSE stream but got content-type "${contentType}". Server may be experiencing issues.`,
+          ExitCode.GENERAL,
+        );
+      }
+
       let textContent = '';
       let inThinking = false;
       const dim = config.noColor ? '' : '\x1b[2m';
@@ -193,8 +212,9 @@ export default defineCommand({
               statusOut.write(parsed.delta.thinking);
             }
           }
-        } catch {
-          // Skip unparseable chunks
+        } catch (err) {
+          // Warn but don't crash — partial output is better than nothing
+          process.stderr.write(`\n${dim}[warning] Failed to parse stream chunk: ${err instanceof Error ? err.message : String(err)}${reset}\n`);
         }
       }
       if (inThinking) statusOut.write(reset);

src/commands/vision/describe.ts

@@ -22,6 +22,8 @@ const MIME_TYPES: Record<string, string> = {
   '.webp': 'image/webp',
 };
 
+const MAX_IMAGE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB limit
+
 async function toDataUri(image: string): Promise<string> {
   if (image.startsWith('data:')) return image;
 
@@ -31,6 +33,12 @@ async function toDataUri(image: string): Promise<string> {
     const contentType = res.headers.get('content-type') || 'image/jpeg';
     const mime = contentType.split(';')[0]!.trim();
     const buf = await res.arrayBuffer();
+    if (buf.byteLength > MAX_IMAGE_SIZE_BYTES) {
+      throw new CLIError(
+        `Image too large (${(buf.byteLength / 1024 / 1024).toFixed(1)} MB). Maximum is 50 MB.`,
+        ExitCode.USAGE,
+      );
+    }
     const b64 = Buffer.from(buf).toString('base64');
     return `data:${mime};base64,${b64}`;
   }

src/config/detect-region.ts

@@ -52,7 +52,10 @@ export async function detectRegion(apiKey: string): Promise<Region> {
   if (!match) {
     process.stderr.write(" failed\n");
     process.stderr.write(
-      "Warning: API key failed validation against all regions. Falling back to global.\n",
+      `Warning: API key failed validation against all regions (global, cn).\n` +
+      `  This usually means the API key is invalid or the network is blocking requests.\n` +
+      `  Falling back to 'global'. Subsequent requests may fail.\n` +
+      `  Run 'mmx auth status' to verify your credentials.\n`,
     );
     return "global";
   }

src/output/audio.ts

@@ -1,6 +1,8 @@
 import { writeFileSync } from 'fs';
 import type { OutputFormat } from './formatter';
 import { formatOutput } from './formatter';
+import { CLIError } from '../errors/base';
+import { ExitCode } from '../errors/codes';
 
 interface AudioExtraInfo {
   audio_length?: number;
@@ -20,7 +22,39 @@ export function saveAudioOutput(
   quiet: boolean,
 ): void {
   if (outPath) {
-    writeFileSync(outPath, Buffer.from(response.data.audio!, 'hex'));
+    const audioHex = response.data.audio;
+    if (!audioHex) {
+      throw new CLIError(
+        'API response missing audio data (audio field is empty).',
+        ExitCode.GENERAL,
+      );
+    }
+    // Validate hex string before attempting conversion
+    if (!/^[0-9a-fA-F]*$/.test(audioHex)) {
+      throw new CLIError(
+        'API returned invalid audio data (not valid hex).',
+        ExitCode.GENERAL,
+      );
+    }
+    if (audioHex.length % 2 !== 0) {
+      throw new CLIError(
+        'API returned truncated audio data (odd-length hex string).',
+        ExitCode.GENERAL,
+      );
+    }
+    try {
+      writeFileSync(outPath, Buffer.from(audioHex, 'hex'));
+    } catch (err) {
+      const e = err as NodeJS.ErrnoException;
+      if (e.code === 'ENOSPC') {
+        throw new CLIError(
+          'Disk full — cannot write audio file.',
+          ExitCode.GENERAL,
+          'Free up disk space and try again.',
+        );
+      }
+      throw err;
+    }
     if (quiet) {
       console.log(outPath);
     } else {

src/polling/poll.ts

@@ -34,9 +34,15 @@ export async function poll<T>(config: Config, opts: PollOptions): Promise<T> {
 
       if (opts.isFailed(data)) {
         spinner.stop('Failed.');
+        // Include API status context to help users diagnose failures
+        const status = opts.getStatus ? opts.getStatus(data) : 'failed';
+        const extra = (data as Record<string, unknown>)?.base_resp
+          ? ` (${(data as { base_resp: { status_code?: number; status_msg?: string } }).base_resp.status_msg})`
+          : '';
         throw new CLIError(
-          'Task failed.',
+          `Task ${status}.${extra}`,
           ExitCode.GENERAL,
+          'Check the MiniMax dashboard or --verbose output for details.',
         );
       }