feat: refactor AI response handling by introducing parseAiJsonResponse and related utilities to improve JSON parsing and error handling. Streamline response processing in client and pipeline modules, enhancing robustness against HTML error pages and reasoning blocks. Add tests for new parsing functions to ensure reliability.

packages/ai/src/__tests__/client.test.ts

@@ -5,6 +5,24 @@ const BASE_URL = "https://api.openai.com/v1";
 const API_KEY = "sk-test-key-12345";
 const MODEL = "gpt-4";
 
+type FetchFn = typeof globalThis.fetch;
+
+/** Bun/TS types fetch as an object with static helpers (e.g. preconnect), not just a function. */
+function asFetchMock(fn: (...args: Parameters<FetchFn>) => ReturnType<FetchFn>): FetchFn {
+  return fn as FetchFn;
+}
+
+function setMockFetch(fn: (...args: Parameters<FetchFn>) => ReturnType<FetchFn>): void {
+  globalThis.fetch = asFetchMock(fn);
+}
+
+function parseRequestBody(opts?: RequestInit): Record<string, unknown> {
+  if (opts?.body == null) {
+    throw new Error("Expected request body in mock fetch");
+  }
+  return JSON.parse(String(opts.body));
+}
+
 function makeMockStream(chunks: string[]): ReadableStream {
   const encoder = new TextEncoder();
   return new ReadableStream({
@@ -17,16 +35,17 @@ function makeMockStream(chunks: string[]): ReadableStream {
   });
 }
 
-function makeFetchMock(streamChunks: string[], status = 200) {
-  return async () =>
+function makeFetchMock(streamChunks: string[], status = 200): FetchFn {
+  return asFetchMock(async () =>
     new Response(makeMockStream(streamChunks), {
       status,
       headers: { "content-type": "text/event-stream" },
-    });
+    }),
+  );
 }
 
 describe("OpenAICompatibleClient", () => {
-  let originalFetch: typeof globalThis.fetch;
+  let originalFetch: FetchFn;
 
   beforeAll(() => {
     originalFetch = globalThis.fetch;
@@ -87,8 +106,9 @@ describe("OpenAICompatibleClient", () => {
   });
 
   it("throws on non-OK response", async () => {
-    globalThis.fetch = async () =>
-      new Response("Bad Request", { status: 400, headers: { "content-type": "text/plain" } });
+    setMockFetch(async () =>
+      new Response("Bad Request", { status: 400, headers: { "content-type": "text/plain" } }),
+    );
 
     const client = new OpenAICompatibleClient(BASE_URL, API_KEY);
     expect(
@@ -100,8 +120,7 @@ describe("OpenAICompatibleClient", () => {
   });
 
   it("throws on empty response body", async () => {
-    globalThis.fetch = async () =>
-      new Response(null, { status: 200 });
+    setMockFetch(async () => new Response(null, { status: 200 }));
 
     const client = new OpenAICompatibleClient(BASE_URL, API_KEY);
     expect(
@@ -134,17 +153,17 @@ describe("OpenAICompatibleClient", () => {
 
   it("retries without response_format on 400 with response_format error", async () => {
     let callCount = 0;
-    globalThis.fetch = async (_url: string, opts: any) => {
+    setMockFetch(async (_input, opts) => {
       callCount++;
       if (callCount === 1) {
-        const body = JSON.parse(opts.body);
+        const body = parseRequestBody(opts);
         expect(body.response_format).toBeDefined();
         return new Response("response_format is not supported", {
           status: 400,
           headers: { "content-type": "text/plain" },
         });
       }
-      const body = JSON.parse(opts.body);
+      const body = parseRequestBody(opts);
       expect(body.response_format).toBeUndefined();
       return new Response(makeMockStream([
         `data: ${JSON.stringify({ choices: [{ delta: { content: "retried" } }] })}\n`,
@@ -153,7 +172,7 @@ describe("OpenAICompatibleClient", () => {
         status: 200,
         headers: { "content-type": "text/event-stream" },
       });
-    };
+    });
 
     const client = new OpenAICompatibleClient(BASE_URL, API_KEY);
     const result = await client.chatCompletion({
@@ -168,7 +187,7 @@ describe("OpenAICompatibleClient", () => {
 
   it("retries with more tokens on truncated response", async () => {
     let callCount = 0;
-    globalThis.fetch = async (_url: string, opts: any) => {
+    setMockFetch(async (_input, _opts) => {
       callCount++;
       const responseContent = callCount === 1
         ? `data: ${JSON.stringify({ choices: [{ delta: { content: '{"incomplete":' } }] })}\n` + "data: [DONE]\n"
@@ -178,7 +197,7 @@ describe("OpenAICompatibleClient", () => {
         status: 200,
         headers: { "content-type": "text/event-stream" },
       });
-    };
+    });
 
     const client = new OpenAICompatibleClient(BASE_URL, API_KEY);
     const result = await client.chatCompletion({
@@ -191,15 +210,49 @@ describe("OpenAICompatibleClient", () => {
     expect(result.content).toBe('{"complete": true}');
   });
 
-  it("throws on HTML response in stream", async () => {
-    globalThis.fetch = async () =>
+  it("strips reasoning blocks and returns JSON from GLM-style streams", async () => {
+    const json = '{"questions":[{"format":"mcq"}]}';
+    globalThis.fetch = makeFetchMock([
+      `data: ${JSON.stringify({ choices: [{ delta: { content: "<think>\nPlanning questions...\n</think>" } }] })}\n`,
+      `data: ${JSON.stringify({ choices: [{ delta: { content: json } }] })}\n`,
+      "data: [DONE]\n",
+    ]);
+
+    const client = new OpenAICompatibleClient(BASE_URL, API_KEY);
+    const result = await client.chatCompletion({
+      model: MODEL,
+      messages: [{ role: "user", content: "Test" }],
+    });
+
+    expect(result.content).toBe(json);
+  });
+
+  it("ignores reasoning_content delta and keeps final content", async () => {
+    globalThis.fetch = makeFetchMock([
+      `data: ${JSON.stringify({ choices: [{ delta: { reasoning_content: "internal reasoning only" } }] })}\n`,
+      `data: ${JSON.stringify({ choices: [{ delta: { content: '{"ok":true}' } }] })}\n`,
+      "data: [DONE]\n",
+    ]);
+
+    const client = new OpenAICompatibleClient(BASE_URL, API_KEY);
+    const result = await client.chatCompletion({
+      model: MODEL,
+      messages: [{ role: "user", content: "Test" }],
+    });
+
+    expect(result.content).toBe('{"ok":true}');
+  });
+
+  it("throws on HTML error page in stream", async () => {
+    setMockFetch(async () =>
       new Response(makeMockStream([
-        `data: ${JSON.stringify({ choices: [{ delta: { content: "<html>Not JSON</html>" } }] })}\n`,
+        `data: ${JSON.stringify({ choices: [{ delta: { content: "<!DOCTYPE html><html><body>502 Bad Gateway</body></html>" } }] })}\n`,
         "data: [DONE]\n",
       ]), {
         status: 200,
         headers: { "content-type": "text/event-stream" },
-      });
+      }),
+    );
 
     const client = new OpenAICompatibleClient(BASE_URL, API_KEY);
     expect(
@@ -209,4 +262,24 @@ describe("OpenAICompatibleClient", () => {
       }),
     ).rejects.toThrow("HTML");
   });
+
+  it("falls back to non-stream JSON body when SSE yields no tokens", async () => {
+    const body = JSON.stringify({
+      choices: [{ message: { content: '{"questions":[]}' } }],
+    });
+    setMockFetch(async () =>
+      new Response(body, {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+
+    const client = new OpenAICompatibleClient(BASE_URL, API_KEY);
+    const result = await client.chatCompletion({
+      model: MODEL,
+      messages: [{ role: "user", content: "Test" }],
+    });
+
+    expect(result.content).toBe('{"questions":[]}');
+  });
 });

packages/ai/src/__tests__/parse-response.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import {
+  extractContentFromCompletionBody,
+  parseAiJsonResponse,
+  stripReasoningBlocks,
+} from "../parse-response";
+
+describe("stripReasoningBlocks", () => {
+  it("removes closed redacted_thinking blocks", () => {
+    const input = "<think>plan</think>\n{\"ok\":true}";
+    expect(stripReasoningBlocks(input)).toBe('{"ok":true}');
+  });
+
+  it("removes think blocks", () => {
+    const input = ["<", "think", ">planning</", "think", ">\n", '{"ok":true}'].join("");
+    expect(stripReasoningBlocks(input)).toBe('{"ok":true}');
+  });
+
+  it("removes unclosed thinking at start", () => {
+    const input = "<think>still streaming...";
+    expect(stripReasoningBlocks(input)).toBe("");
+  });
+
+  it("does not treat XML-like tags in JSON as reasoning", () => {
+    const input = '{"questionText":"<b>highlight</b>"}';
+    expect(stripReasoningBlocks(input)).toBe(input);
+  });
+});
+
+describe("parseAiJsonResponse", () => {
+  it("parses JSON after reasoning preamble", () => {
+    const parsed = parseAiJsonResponse(
+      "<think>planning</think>\n```json\n{\"questions\":[]}\n```",
+    );
+    expect(parsed).toEqual({ questions: [] });
+  });
+
+  it("extracts JSON object embedded in prose", () => {
+    const parsed = parseAiJsonResponse(
+      "Here is the result:\n{\"questions\":[{\"format\":\"multiple_choice\"}]}\nThanks!",
+    );
+    expect(parsed).toEqual({ questions: [{ format: "multiple_choice" }] });
+  });
+
+  it("throws on empty content after stripping", () => {
+    expect(() => parseAiJsonResponse("<think>only thinking")).toThrow(
+      "Empty response from AI",
+    );
+  });
+});
+
+describe("extractContentFromCompletionBody", () => {
+  it("reads non-stream chat completion JSON", () => {
+    const body = JSON.stringify({
+      choices: [{ message: { content: '{"questions":[]}' } }],
+    });
+    expect(extractContentFromCompletionBody(body)).toBe('{"questions":[]}');
+  });
+
+  it("returns null for non-JSON bodies", () => {
+    expect(extractContentFromCompletionBody("<html>error</html>")).toBeNull();
+  });
+});

packages/ai/src/agentic.ts

@@ -1,5 +1,6 @@
 import { OpenAICompatibleClient } from "./client";
 import { GenerationError } from "./errors";
+import { parseAiJsonResponse } from "./parse-response";
 import {
   getPassageJsonSchemaDescription,
   getValidationJsonSchemaDescription,
@@ -68,18 +69,7 @@ function calculateMaxTokens(
 }
 
 function parseJsonResponse(content: string): unknown {
-  if (!content) throw new Error("Empty response from AI");
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    const cleaned = content
-      .replace(/^```json\s*/, "")
-      .replace(/```\s*$/, "")
-      .trim();
-    parsed = JSON.parse(cleaned);
-  }
-  return parsed;
+  return parseAiJsonResponse(content);
 }
 
 async function step1GeneratePassage(

packages/ai/src/client.ts

@@ -1,3 +1,9 @@
+import {
+  extractContentFromCompletionBody,
+  looksLikeHtmlErrorPage,
+  stripReasoningBlocks,
+} from "./parse-response";
+
 export interface ChatMessage {
   role: "system" | "user" | "assistant";
   content: string;
@@ -42,7 +48,8 @@ function parseSSELine(line: string): { content?: string; usage?: ChatCompletionR
   if (data === "[DONE]") return null;
   try {
     const chunk = JSON.parse(data);
-    const content = chunk.choices?.[0]?.delta?.content;
+    const choice = chunk.choices?.[0];
+    const content = choice?.delta?.content ?? choice?.message?.content;
     const usage = chunk.usage;
     return { content: typeof content === "string" ? content : undefined, usage };
   } catch {
@@ -53,9 +60,10 @@ function parseSSELine(line: string): { content?: string; usage?: ChatCompletionR
 async function readSSEStream(
   reader: any,
   callbacks: StreamCallbacks,
-): Promise<{ content: string; usage?: ChatCompletionResult["usage"] }> {
+): Promise<{ content: string; usage?: ChatCompletionResult["usage"]; rawBody: string }> {
   const decoder = new TextDecoder();
   let buffer = "";
+  let rawBody = "";
   let fullContent = "";
   let lastUsage: ChatCompletionResult["usage"] | undefined;
 
@@ -63,12 +71,16 @@ async function readSSEStream(
     const { done, value } = await reader.read();
     if (done) break;
 
-    buffer += decoder.decode(value, { stream: true });
+    const chunkText = decoder.decode(value, { stream: true });
+    rawBody += chunkText;
+    buffer += chunkText;
     const lines = buffer.split("\n");
     buffer = lines.pop() ?? "";
 
     for (const line of lines) {
-      const parsed = parseSSELine(line);
+      const trimmedLine = line.trim();
+      if (!trimmedLine || trimmedLine.startsWith(":")) continue;
+      const parsed = parseSSELine(trimmedLine);
       if (!parsed) continue;
       if (parsed.content) {
         fullContent += parsed.content;
@@ -94,7 +106,15 @@ async function readSSEStream(
     }
   }
 
-  return { content: fullContent, usage: lastUsage };
+  if (!fullContent) {
+    const nonStreamContent = extractContentFromCompletionBody(rawBody);
+    if (nonStreamContent) {
+      fullContent = nonStreamContent;
+      callbacks.onToken(nonStreamContent);
+    }
+  }
+
+  return { content: fullContent, usage: lastUsage, rawBody };
 }
 
 function looksTruncated(content: string): boolean {
@@ -224,7 +244,7 @@ export class OpenAICompatibleClient {
         status: res.status,
         statusText: res.statusText,
         preview,
-        isHtml: preview.trim().startsWith("<"),
+        isHtml: looksLikeHtmlErrorPage(preview),
       });
 
       // Retry without response_format if provider doesn't support it
@@ -237,10 +257,10 @@ export class OpenAICompatibleClient {
         });
       }
 
-      if (preview.trim().startsWith("<")) {
+      if (looksLikeHtmlErrorPage(preview)) {
         throw new Error(
-          `Provider returned HTML instead of JSON (status ${res.status}). ` +
-            `This usually means the base URL or endpoint is wrong, or the provider does not support this API. ` +
+          `Upstream returned an HTML error page (status ${res.status}), not AI JSON. ` +
+            `Check base URL, proxy, or gateway configuration. ` +
             `Preview: ${preview.slice(0, 200)}`,
         );
       }
@@ -253,20 +273,24 @@ export class OpenAICompatibleClient {
     }
 
     const reader = res.body.getReader() as any;
-    const result = await readSSEStream(
+    const streamResult = await readSSEStream(
       reader,
       callbacks ?? { onToken: () => {} },
     );
+    const result = {
+      ...streamResult,
+      content: stripReasoningBlocks(streamResult.content),
+    };
 
-    // Defense: if content looks like HTML, something went wrong with streaming
-    if (result.content.trim().startsWith("<")) {
+    // Defense: reject actual HTML error pages, not model thinking tags like <think>
+    if (looksLikeHtmlErrorPage(result.content)) {
       const preview = result.content.slice(0, 500);
-      log("error", "Stream returned HTML instead of JSON", {
+      log("error", "Stream returned HTML error page instead of AI content", {
         preview: preview.slice(0, 200),
       });
       throw new Error(
-        `Provider returned HTML in stream instead of JSON. ` +
-          `The provider may not support SSE streaming. ` +
+        `Upstream returned an HTML error page in the stream, not AI JSON. ` +
+          `Check base URL, proxy, or gateway configuration. ` +
           `Preview: ${preview.slice(0, 200)}`,
       );
     }

packages/ai/src/parse-response.ts

@@ -0,0 +1,109 @@
+/**
+ * Normalize model output before JSON parsing.
+ * Reasoning models (GLM, DeepSeek, etc.) often wrap chain-of-thought in tags
+ * that are NOT HTML error pages.
+ */
+
+const THINK_TAG = "think";
+
+const REASONING_BLOCK_PATTERNS: RegExp[] = [
+  /<think>[\s\S]*?<\/redacted_thinking>/gi,
+  /<thinking>[\s\S]*?<\/thinking>/gi,
+  new RegExp(`<${THINK_TAG}>[\\s\\S]*?</${THINK_TAG}>`, "gi"),
+];
+
+const UNCLOSED_REASONING_PREFIXES = [
+  /^<think>[\s\S]*/i,
+  /^<thinking>[\s\S]*/i,
+  new RegExp(`^<${THINK_TAG}>[\\s\\S]*`, "i"),
+];
+
+export function stripReasoningBlocks(content: string): string {
+  let text = content;
+  for (const pattern of REASONING_BLOCK_PATTERNS) {
+    text = text.replace(pattern, "");
+  }
+  for (const pattern of UNCLOSED_REASONING_PREFIXES) {
+    text = text.replace(pattern, "");
+  }
+  return text.trim();
+}
+
+function extractJsonCandidate(content: string): string {
+  const trimmed = content.trim();
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fenced?.[1]) return fenced[1].trim();
+
+  const objIdx = trimmed.indexOf("{");
+  const arrIdx = trimmed.indexOf("[");
+  let start = -1;
+  if (objIdx === -1) start = arrIdx;
+  else if (arrIdx === -1) start = objIdx;
+  else start = Math.min(objIdx, arrIdx);
+
+  if (start < 0) return trimmed;
+
+  const slice = trimmed.slice(start);
+  const lastBrace = slice.lastIndexOf("}");
+  const lastBracket = slice.lastIndexOf("]");
+  const end = Math.max(lastBrace, lastBracket);
+  if (end === -1) return slice;
+  return slice.slice(0, end + 1);
+}
+
+export function parseAiJsonResponse(content: string): unknown {
+  const normalized = stripReasoningBlocks(content);
+  if (!normalized) throw new Error("Empty response from AI");
+
+  const candidates = [normalized, extractJsonCandidate(normalized)];
+  const uniqueCandidates = [...new Set(candidates.filter(Boolean))];
+
+  let lastError: Error | undefined;
+  for (const candidate of uniqueCandidates) {
+    try {
+      return JSON.parse(candidate);
+    } catch (err: unknown) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      const markdownCleaned = candidate
+        .replace(/^```json\s*/i, "")
+        .replace(/```\s*$/, "")
+        .trim();
+      if (markdownCleaned !== candidate) {
+        try {
+          return JSON.parse(markdownCleaned);
+        } catch (inner: unknown) {
+          lastError = inner instanceof Error ? inner : new Error(String(inner));
+        }
+      }
+    }
+  }
+
+  throw new Error(
+    `Failed to parse AI response as JSON: ${lastError?.message ?? "unknown error"}. Preview: ${normalized.slice(0, 200)}`,
+  );
+}
+
+export function extractContentFromCompletionBody(body: string): string | null {
+  const trimmed = body.trim();
+  if (!trimmed.startsWith("{")) return null;
+  try {
+    const json = JSON.parse(trimmed) as {
+      choices?: Array<{ message?: { content?: string } }>;
+    };
+    const content = json.choices?.[0]?.message?.content;
+    return typeof content === "string" ? content : null;
+  } catch {
+    return null;
+  }
+}
+
+export function looksLikeHtmlErrorPage(content: string): boolean {
+  const head = content.trim().slice(0, 300).toLowerCase();
+  return (
+    head.startsWith("<!doctype") ||
+    head.startsWith("<html") ||
+    head.startsWith("<head") ||
+    head.startsWith("<body") ||
+    /^<\?(xml|php)/.test(head)
+  );
+}

packages/ai/src/pipeline.ts

@@ -1,5 +1,6 @@
 import { OpenAICompatibleClient } from "./client";
 import { GenerationError } from "./errors";
+import { parseAiJsonResponse } from "./parse-response";
 import { buildQuickModePrompt } from "./prompts";
 import { repairAndParseQuestions } from "./repair";
 import { regenerateQuestions, buildRegenerationContext } from "./regenerate-questions";
@@ -76,28 +77,19 @@ export async function generateQuestionsQuick(
 
   let parsed: unknown;
   try {
-    parsed = JSON.parse(content);
-    log("info", "JSON parsed successfully (direct)");
+    parsed = parseAiJsonResponse(content);
+    log("info", "JSON parsed successfully");
   } catch (parseErr: any) {
-    log("warn", "Direct JSON parse failed, trying markdown strip", { error: parseErr.message });
-    const cleaned = content
-      .replace(/^```json\s*/, "")
-      .replace(/```\s*$/, "")
-      .trim();
-    try {
-      parsed = JSON.parse(cleaned);
-      log("info", "JSON parsed successfully after markdown strip");
-    } catch (stripErr: any) {
-      log("error", "JSON parse failed even after markdown strip", {
-        error: stripErr.message,
-        cleanedPreview: cleaned.slice(0, 500),
-        originalPreview: content.slice(0, 500),
-      });
-      throw new GenerationError(
-        `Failed to parse AI response as JSON: ${stripErr.message}. Preview: ${content.slice(0, 200)}`,
-        { tokensUsed },
-      );
-    }
+    log("error", "JSON parse failed", {
+      error: parseErr.message,
+      originalPreview: content.slice(0, 500),
+    });
+    throw new GenerationError(
+      parseErr.message.includes("Failed to parse AI response")
+        ? parseErr.message
+        : `Failed to parse AI response as JSON: ${parseErr.message}. Preview: ${content.slice(0, 200)}`,
+      { tokensUsed },
+    );
   }
 
   if (!parsed || typeof parsed !== "object") {

packages/ai/src/regenerate-questions.ts

@@ -1,20 +1,12 @@
 import { OpenAICompatibleClient } from "./client";
+import { parseAiJsonResponse } from "./parse-response";
 import { getGenericQuestionJsonSchemaDescription } from "./repair";
 import { OPTION_QUALITY_RULES } from "./prompts";
 import { buildContentLanguageRules, buildExplanationLanguageRule } from "./language-rules";
 import type { GenerationInput } from "./schemas";
 
 function parseJsonResponse(content: string): unknown {
-  if (!content) throw new Error("Empty response from AI");
-  try {
-    return JSON.parse(content);
-  } catch {
-    const cleaned = content
-      .replace(/^```json\s*/, "")
-      .replace(/```\s*$/, "")
-      .trim();
-    return JSON.parse(cleaned);
-  }
+  return parseAiJsonResponse(content);
 }
 
 function calculateRegenerateMaxTokens(userMax: number, count: number): number {

packages/api/src/__tests__/generation-outcome.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import {
+  collectShardFailureCause,
+  formatGenerationErrorMessage,
   isNonRetryableProviderError,
   resolveGenerationJobOutcome,
   sectionsWithNoQuestions,
@@ -23,6 +25,14 @@ describe("isNonRetryableProviderError", () => {
   it("returns false for JSON parse failures", () => {
     expect(isNonRetryableProviderError(new Error("Failed to parse AI response as JSON"))).toBe(false);
   });
+
+  it("detects upstream HTML error pages", () => {
+    expect(
+      isNonRetryableProviderError(
+        new Error("Upstream returned an HTML error page in the stream, not AI JSON."),
+      ),
+    ).toBe(true);
+  });
 });
 
 describe("resolveGenerationJobOutcome", () => {
@@ -47,7 +57,7 @@ describe("resolveGenerationJobOutcome", () => {
     expect(outcome.errorMessage).toContain("WRITING");
   });
 
-  it("marks zero questions as failed", () => {
+  it("marks zero questions as failed without blaming provider when cause is unknown", () => {
     const outcome = resolveGenerationJobOutcome({
       requestedCount: 20,
       generatedCount: 0,
@@ -55,6 +65,40 @@ describe("resolveGenerationJobOutcome", () => {
     });
     expect(outcome.status).toBe("failed");
     expect(outcome.errorMessage).toContain("Tidak ada soal");
+    expect(outcome.errorMessage).not.toContain("Periksa model/API provider");
+  });
+
+  it("surfaces JSON parse cause instead of generic provider hint", () => {
+    const outcome = resolveGenerationJobOutcome({
+      requestedCount: 5,
+      generatedCount: 0,
+      failedSections: ["READING"],
+      cause: "Failed to parse AI response as JSON: Unexpected token. Preview: {broken",
+    });
+    expect(outcome.errorMessage).toContain("tidak valid JSON");
+    expect(outcome.errorMessage).toContain("Failed to parse AI response");
+    expect(outcome.errorMessage).not.toContain("Periksa model/API provider");
+  });
+});
+
+describe("formatGenerationErrorMessage", () => {
+  it("labels upstream provider failures clearly", () => {
+    const message = formatGenerationErrorMessage({
+      cause: "OpenAI-compatible API error 500: upstream timeout",
+      failedSections: ["READING"],
+    });
+    expect(message).toContain("Gagal menghubungi API provider");
+    expect(message).toContain("500");
+  });
+
+  it("detects legacy false-positive HTML guard on reasoning output", () => {
+    const message = formatGenerationErrorMessage({
+      cause:
+        "Provider returned HTML in stream instead of JSON. Preview: <think>planning",
+      failedSections: ["READING"],
+    });
+    expect(message).toContain("reasoning tidak kompatibel");
+    expect(message).not.toContain("Gagal menghubungi API provider");
   });
 });
 

packages/api/src/lib/generation-outcome.ts

@@ -6,6 +6,7 @@ export function isNonRetryableProviderError(error: unknown): boolean {
   if (/api error 5\d\d/i.test(message)) return true;
   if (lower.includes("midstreamfallbackerror")) return true;
   if (lower.includes("apiconnectionerror")) return true;
+  if (lower.includes("upstream returned an html error page")) return true;
   if (lower.includes("provider returned html")) return true;
   if (/\berror 502\b/.test(lower) || /\berror 503\b/.test(lower) || /\berror 504\b/.test(lower)) {
     return true;
@@ -14,32 +15,97 @@ export function isNonRetryableProviderError(error: unknown): boolean {
   return false;
 }
 
+function truncate(text: string, maxLen: number): string {
+  return text.length <= maxLen ? text : `${text.slice(0, maxLen)}…`;
+}
+
+function sectionHint(failedSections: string[]): string {
+  return failedSections.length > 0 ? ` Section gagal: ${failedSections.join(", ")}.` : "";
+}
+
+/** Turn raw pipeline/client errors into user-facing messages that name the real cause. */
+export function formatGenerationErrorMessage(input: {
+  cause?: string;
+  failedSections?: string[];
+}): string {
+  const failedSections = [...new Set(input.failedSections ?? [])];
+  const hint = sectionHint(failedSections);
+  const cause = input.cause?.trim();
+
+  if (!cause) {
+    return `Tidak ada soal yang berhasil dibuat.${hint}`;
+  }
+
+  const lower = cause.toLowerCase();
+
+  if (
+    lower.includes("redacted_thinking") ||
+    lower.includes("<thinking>") ||
+    /<\/?think>/.test(lower)
+  ) {
+    return `Model reasoning tidak kompatibel dengan parser Labas.${hint} Coba non-reasoning model, atau update server ke versi terbaru.`;
+  }
+
+  if (lower.includes("failed to parse ai response") || lower.includes("invalid json response")) {
+    return `Model merespons, tapi output tidak valid JSON.${hint} ${truncate(cause, 280)}`;
+  }
+
+  if (lower.includes("empty response from ai") || lower.includes("empty response body")) {
+    return `Model tidak mengembalikan konten.${hint} Coba model lain atau kurangi jumlah soal.`;
+  }
+
+  if (lower.includes("no valid questions")) {
+    return `Model menghasilkan soal, tapi semuanya gagal validasi.${hint} ${truncate(cause, 280)}`;
+  }
+
+  if (
+    lower.includes("upstream returned an html error page") ||
+    lower.includes("provider returned html") ||
+    lower.includes("openai-compatible api error") ||
+    /api error 5\d\d/i.test(cause) ||
+    lower.includes("apiconnectionerror") ||
+    lower.includes("midstreamfallbackerror")
+  ) {
+    return `Gagal menghubungi API provider.${hint} ${truncate(cause, 280)}`;
+  }
+
+  if (lower.includes("metadata/private network") || lower.includes("invalid base url")) {
+    return `Base URL provider tidak valid atau tidak dapat diakses dari server.${hint}`;
+  }
+
+  return `Generasi gagal.${hint} ${truncate(cause, 280)}`;
+}
+
 export function resolveGenerationJobOutcome(input: {
   requestedCount: number;
   generatedCount: number;
   failedSections?: string[];
+  cause?: string;
 }): {
   status: "completed" | "completed_partial" | "failed";
   progressMessage: string;
   errorMessage: string | null;
 } {
   const failedSections = [...new Set(input.failedSections ?? [])];
-  const sectionHint =
-    failedSections.length > 0 ? ` Section gagal: ${failedSections.join(", ")}.` : "";
 
   if (input.generatedCount <= 0) {
     return {
       status: "failed",
       progressMessage: "Generation failed",
-      errorMessage: `Tidak ada soal yang berhasil dibuat.${sectionHint} Periksa model/API provider.`,
+      errorMessage: formatGenerationErrorMessage({
+        cause: input.cause,
+        failedSections,
+      }),
     };
   }
 
   if (input.generatedCount < input.requestedCount) {
+    const sectionHintText =
+      failedSections.length > 0 ? ` Section gagal: ${failedSections.join(", ")}.` : "";
     return {
       status: "completed_partial",
       progressMessage: `Selesai sebagian: ${input.generatedCount}/${input.requestedCount} soal`,
-      errorMessage: `Hanya ${input.generatedCount} dari ${input.requestedCount} soal berhasil dibuat.${sectionHint}`,
+      errorMessage: `Hanya ${input.generatedCount} dari ${input.requestedCount} soal berhasil dibuat.${sectionHintText}`,
     };
   }
 
@@ -58,3 +124,13 @@ export function sectionsWithNoQuestions(
     .filter((split) => !questions.some((q) => q.section === split.section))
     .map((split) => split.section);
 }
+
+export function collectShardFailureCause(
+  failures: Iterable<{ error: string } | undefined>,
+): string | undefined {
+  for (const failure of failures) {
+    const message = failure?.error?.trim();
+    if (message) return message;
+  }
+  return undefined;
+}

packages/api/src/queue.ts

@@ -27,6 +27,7 @@ import {
 import { and, eq, notInArray } from "drizzle-orm";
 import { encryptApiKey, decryptApiKey } from "./lib/encryption";
 import {
+  collectShardFailureCause,
   isNonRetryableProviderError,
   resolveGenerationJobOutcome,
   sectionsWithNoQuestions,
@@ -955,6 +956,9 @@ export const generationWorker = new Worker<FastJobData>(
         requestedCount: input.questionCount,
         generatedCount: allQuestions.length,
         failedSections: sectionsWithNoQuestions(sectionSplits, allQuestions),
+        cause: collectShardFailureCause(
+          failedShards.map((shard) => shardFailureInfo.get(shardKey(shard))),
+        ),
       });
 
       if (outcome.status === "failed") {