ima2-gen 1.1.13 → 1.1.14

package/docs/PROMPT_STUDIO.md

@@ -0,0 +1,115 @@
+# Prompt Studio Manual
+
+Prompt Studio is the Classic workspace profile for repeated image iteration. It
+keeps the image viewer in the center, recent generations on the side, and the
+composer plus generation controls close to the current image.
+
+Use this page when you are not sure what a Prompt Studio control does or when
+you want a reproducible way to report a workspace issue.
+
+## Feature Map
+
+| Area | What it does | Notes |
+|---|---|---|
+| Composer | Holds the prompt for the next request. | Selecting an existing image is view-only. It should not overwrite the composer. |
+| Multimode | Starts several separate image requests from the current prompt. | Each slot is a candidate output, not a collage panel or a guaranteed scene sequence. |
+| 1:1 Direct | Sends the prompt through with less rewriting by the app. | Use it for exact wording, strict prompt experiments, or provider-side prompt syntax. |
+| Model quick menu | Changes the image model and reasoning effort from the sidebar header. | The full Settings workspace remains the detailed configuration page. |
+| Recent generations | Shows the visible Prompt Studio history domain. | Arrow keys move inside the same visible recent domain instead of hidden older rows. |
+| Gallery | Browses saved local images, All/Favorites tabs, and folders. | Favorite toggles should preserve the gallery viewport you were browsing. |
+| Prompt library | Imports saved prompt text into the composer intentionally. | Library insert/continue actions are explicit prompt imports; passive image selection is not. |
+
+## Multimode Prompting
+
+Multimode repeats one generation request shape across several candidate slots.
+It is useful when you want alternatives, not when you need one combined
+multi-panel image.
+
+For related candidates, put the shared subject first and the variation rule
+second:
+
+```text
+Same character design in every image: a silver-haired courier in a red raincoat.
+Make 4 alternatives that vary only camera angle, lighting, and background street.
+Keep face, outfit, age, and color palette consistent.
+```
+
+For unrelated candidates, say so directly:
+
+```text
+Create 4 unrelated sticker ideas for a local image generation app.
+Each image should use a different mascot, color palette, and composition.
+```
+
+If you need a true two-panel comic, contact sheet, before/after comparison, or
+collage, ask for that in a single normal image request instead of relying on
+multimode slots:
+
+```text
+Create one 2-panel comparison image. Left panel: rough sketch UI. Right panel:
+polished Prompt Studio UI. Add small labels inside each panel.
+```
+
+## Direct Mode
+
+Use **1:1 Direct** when the exact prompt text matters. It is helpful for:
+
+- comparing prompt wording changes,
+- preserving a structured prompt template,
+- using provider-specific instruction style,
+- avoiding app-side phrasing changes during troubleshooting.
+
+Direct mode can be used together with Multimode. In that case, each multimode
+slot receives the same direct prompt request shape.
+
+## Reasoning Effort
+
+Reasoning effort controls how much planning the selected model may spend before
+or during generation. Start with the default for everyday work. Raise it when
+the prompt has many constraints, references, or composition requirements.
+
+The sidebar model label opens quick settings for both model and reasoning. The
+Settings workspace still shows the full model configuration and explanatory
+copy.
+
+## Gallery And Prompt Safety
+
+Prompt Studio separates browsing from composing:
+
+- Passive image selection is view-only.
+- Clicking a history or gallery image focuses the image for viewing.
+- Favorite on/off changes the saved image metadata and should not jump your
+  gallery browsing position.
+- The All and Favorites tabs are browsing filters. Switching between them does
+  not intentionally import a prompt.
+- Prompt Library insert, "continue from this image", and explicit reuse actions
+  are the actions that intentionally change the composer.
+
+Before generating, glance at the composer if you were using explicit prompt
+import actions. Passive image selection should leave your draft alone.
+
+## Issue #75 Closeout Notes
+
+The v1.1.13 Prompt Studio fixes tightened these user-visible contracts:
+
+- concurrent multimode completions keep their slot/request identity,
+- keyboard navigation follows the visible recent history domain,
+- the gallery button remains reachable beside recent history,
+- long prompts no longer starve the default image viewer,
+- Direct and Multimode states can be seen at the same time,
+- gallery favorite toggles and tab changes preserve the browsing viewport,
+- passive image selection does not refill the composer.
+
+## Reporting A Prompt Studio Problem
+
+When opening an issue, include:
+
+- `ima2-gen` version and operating system,
+- browser and viewport size if layout is involved,
+- workspace profile, mode toggles, model, reasoning effort, and image count,
+- numbered steps from a fresh `ima2 serve` session,
+- whether the problem happens in All, Favorites, or recent history,
+- safe screenshots or screen recordings if they do not reveal private prompts.
+
+Do not share ChatGPT cookies, OAuth token files, API keys, raw upstream
+responses, private prompt history, or generated base64 data.

package/docs/README.ko.md

@@ -82,6 +82,10 @@ API 키가 env/config에 있으면 생성 엔드포인트에서 `provider: "api"
 4. 한 장을 만들거나, multimode를 켜서 같은 프롬프트에서 여러 후보 슬롯을 만듭니다.
 5. 생성 후 복사, 다운로드, 이어서 작업, Canvas Mode 정리를 선택합니다.
 
+Prompt Studio의 각 컨트롤, 멀티모드 작성법, 1:1 Direct, 추론 강도, 갤러리
+즐겨찾기 동작은 [Prompt Studio 사용 설명서](PROMPT_STUDIO.ko.md)에 정리되어
+있습니다.
+
 ![하나의 프롬프트에서 네 후보 슬롯이 생성 중이고 sidebar에 active job history가 보이는 multimode sequence 화면](../assets/screenshots/multimode-sequence.png)
 
 ### Node mode
@@ -186,7 +190,10 @@ environment variables > ~/.ima2/config.json > built-in defaults
 
 엔드포인트 목록은 [API Reference](API.md)로 분리했습니다.
 
-자주 묻는 질문은 [FAQ](FAQ.ko.md)에 정리했습니다. 업데이트 후 예전 이미지가 안 보이면 [예전 이미지 복구 안내](RECOVER_OLD_IMAGES.md)를 먼저 확인하세요.
+자주 묻는 질문은 [FAQ](FAQ.ko.md)에 정리했습니다. Prompt Studio 기능은
+[Prompt Studio 사용 설명서](PROMPT_STUDIO.ko.md)를 확인하세요. 업데이트 후
+예전 이미지가 안 보이면 [예전 이미지 복구 안내](RECOVER_OLD_IMAGES.md)를
+먼저 확인하세요.
 
 ## 문제 해결
 

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 156 (runtime: 46, contract: 110)
+Total: 161 (runtime: 49, contract: 112)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -47,6 +47,9 @@ Total: 156 (runtime: 46, contract: 110)
 - `tests/reference-image-compress.test.ts`
 - `tests/refs-size.test.ts`
 - `tests/request-logging.test.ts`
+- `tests/responses-adapter-safety.test.ts`
+- `tests/responses-empty-taxonomy.test.ts`
+- `tests/responses-parse-diagnostics.test.ts`
 - `tests/runtime-context-normalize.test.ts`
 - `tests/runtime-ports.test.ts`
 - `tests/serve-ui-build-contract.test.ts`
@@ -123,6 +126,7 @@ Total: 156 (runtime: 46, contract: 110)
 - `tests/inflight-list-tooltip-contract.test.js`
 - `tests/inflight-reload-race.test.js`
 - `tests/inflight-reload-reconcile-contract.test.js`
+- `tests/issue75-prompt-studio-state-contract.test.js`
 - `tests/mobile-generate-entry-contract.test.js`
 - `tests/multimode-backend-contract.test.js`
 - `tests/multimode-concurrent-store-contract.test.js`
@@ -150,6 +154,7 @@ Total: 156 (runtime: 46, contract: 110)
 - `tests/prompt-import-folder-ui-contract.test.js`
 - `tests/prompt-import-search-ux-contract.test.js`
 - `tests/prompt-library-ui-contract.test.js`
+- `tests/prompt-studio-docs-contract.test.js`
 - `tests/prompt-studio-ui-contract.test.js`
 - `tests/server-fallback-contract.test.js`
 - `tests/server.test.js`

package/lib/agentRuntime.js

@@ -187,7 +187,9 @@ async function generateAgentImageWithRetry(ctx, sessionId, prompt, manifest, web
         }
         catch (error) {
             lastError = error;
-            if (!isTextOnlyResult(error) || attempt === 1)
+            if (!isTextOnlyResult(error))
+                throw error;
+            if (attempt === 1)
                 break;
             appendAgentTurn({
                 sessionId,
@@ -264,7 +266,12 @@ function forceImagePrompt(prompt) {
 }
 function isTextOnlyResult(error) {
     const err = errInfo(error);
-    return err.code === "EMPTY_RESPONSE" || err.message.includes("No image data");
+    return [
+        "EMPTY_RESPONSE",
+        "IMAGE_TOOL_NOT_CALLED",
+        "WEB_SEARCH_ONLY_RESPONSE",
+        "IMAGE_TOOL_COMPLETED_WITHOUT_RESULT",
+    ].includes(err.code || "") || err.message.includes("No image data");
 }
 function textOnlyError(cause) {
     const err = new Error("Agent result did not include an image artifact.");

package/lib/agentRuntime.ts

@@ -252,7 +252,8 @@ async function generateAgentImageWithRetry(
       if (result.image) return result;
     } catch (error) {
       lastError = error;
-      if (!isTextOnlyResult(error) || attempt === 1) break;
+      if (!isTextOnlyResult(error)) throw error;
+      if (attempt === 1) break;
       appendAgentTurn({
         sessionId,
         role: "tool",
@@ -357,7 +358,12 @@ function forceImagePrompt(prompt: string) {
 
 function isTextOnlyResult(error: unknown) {
   const err = errInfo(error);
-  return err.code === "EMPTY_RESPONSE" || err.message.includes("No image data");
+  return [
+    "EMPTY_RESPONSE",
+    "IMAGE_TOOL_NOT_CALLED",
+    "WEB_SEARCH_ONLY_RESPONSE",
+    "IMAGE_TOOL_COMPLETED_WITHOUT_RESULT",
+  ].includes(err.code || "") || err.message.includes("No image data");
 }
 
 function textOnlyError(cause: unknown) {

package/lib/errorClassify.js

@@ -1,7 +1,7 @@
 // 0.09.8 — upstream error classifier.
 // Pattern-match upstream OpenAI / OAuth / network errors into stable ImaErrorCode
 // values so the UI can surface localized, actionable messages with CTAs.
-/** @typedef {"REF_TOO_LARGE"|"REF_NOT_BASE64"|"REF_EMPTY"|"REF_TOO_MANY"|"MODERATION_REFUSED"|"UPSTREAM_5XX"|"AUTH_CHATGPT_EXPIRED"|"AUTH_API_KEY_INVALID"|"NETWORK_FAILED"|"OAUTH_UNAVAILABLE"|"INVALID_REQUEST"|"INVALID_MODERATION"|"APIKEY_DISABLED"|"SAFETY_REFUSAL"|"EMPTY_RESPONSE"|"OAUTH_UPSTREAM_ERROR"|"DB_ERROR"|"UNKNOWN"} ImaErrorCode */
+/** @typedef {"REF_TOO_LARGE"|"REF_NOT_BASE64"|"REF_EMPTY"|"REF_TOO_MANY"|"MODERATION_REFUSED"|"UPSTREAM_5XX"|"AUTH_CHATGPT_EXPIRED"|"AUTH_API_KEY_INVALID"|"NETWORK_FAILED"|"OAUTH_UNAVAILABLE"|"INVALID_REQUEST"|"INVALID_MODERATION"|"APIKEY_DISABLED"|"SAFETY_REFUSAL"|"EMPTY_RESPONSE"|"STREAM_PARSE_FAILED"|"IMAGE_TOOL_NOT_CALLED"|"WEB_SEARCH_ONLY_RESPONSE"|"IMAGE_TOOL_FAILED"|"IMAGE_TOOL_COMPLETED_WITHOUT_RESULT"|"OAUTH_IMAGE_CAPABILITY_UNAVAILABLE"|"RESPONSES_STREAM_ERROR"|"OAUTH_UPSTREAM_ERROR"|"DB_ERROR"|"UNKNOWN"} ImaErrorCode */
 const INVALID_REQUEST_CODES = new Set([
     "bad_request",
     "invalid_request",

package/lib/errorClassify.ts

@@ -2,7 +2,7 @@
 // Pattern-match upstream OpenAI / OAuth / network errors into stable ImaErrorCode
 // values so the UI can surface localized, actionable messages with CTAs.
 
-/** @typedef {"REF_TOO_LARGE"|"REF_NOT_BASE64"|"REF_EMPTY"|"REF_TOO_MANY"|"MODERATION_REFUSED"|"UPSTREAM_5XX"|"AUTH_CHATGPT_EXPIRED"|"AUTH_API_KEY_INVALID"|"NETWORK_FAILED"|"OAUTH_UNAVAILABLE"|"INVALID_REQUEST"|"INVALID_MODERATION"|"APIKEY_DISABLED"|"SAFETY_REFUSAL"|"EMPTY_RESPONSE"|"OAUTH_UPSTREAM_ERROR"|"DB_ERROR"|"UNKNOWN"} ImaErrorCode */
+/** @typedef {"REF_TOO_LARGE"|"REF_NOT_BASE64"|"REF_EMPTY"|"REF_TOO_MANY"|"MODERATION_REFUSED"|"UPSTREAM_5XX"|"AUTH_CHATGPT_EXPIRED"|"AUTH_API_KEY_INVALID"|"NETWORK_FAILED"|"OAUTH_UNAVAILABLE"|"INVALID_REQUEST"|"INVALID_MODERATION"|"APIKEY_DISABLED"|"SAFETY_REFUSAL"|"EMPTY_RESPONSE"|"STREAM_PARSE_FAILED"|"IMAGE_TOOL_NOT_CALLED"|"WEB_SEARCH_ONLY_RESPONSE"|"IMAGE_TOOL_FAILED"|"IMAGE_TOOL_COMPLETED_WITHOUT_RESULT"|"OAUTH_IMAGE_CAPABILITY_UNAVAILABLE"|"RESPONSES_STREAM_ERROR"|"OAUTH_UPSTREAM_ERROR"|"DB_ERROR"|"UNKNOWN"} ImaErrorCode */
 
 const INVALID_REQUEST_CODES = new Set([
   "bad_request",

package/lib/generationErrors.js

@@ -1,4 +1,6 @@
 import { classifyUpstreamError, classifyUpstreamErrorCode } from "./errorClassify.js";
+import { safeDiagnosticLabel } from "./responsesParse.js";
+import { RESPONSE_DIAGNOSTIC_CODES } from "./responsesErrors.js";
 const PASSTHROUGH_CODES = new Set([
     "OAUTH_UNAVAILABLE",
     "NETWORK_FAILED",
@@ -22,13 +24,50 @@ function diagnosticReasonFrom(err) {
         return err.diagnosticReason;
     if (Number(err?.referenceMismatchCount) > 0)
         return "reference_mime_mismatch_candidate";
+    const responseDiagnosticReason = responseDiagnosticReasonFrom(err);
+    if (responseDiagnosticReason)
+        return responseDiagnosticReason;
     if (has4kSize(err?.size))
         return "experimental_4k_empty_response";
     return null;
 }
+function responseDiagnosticReasonFrom(err) {
+    if (!err?.responseDiagnostics || typeof err.responseDiagnostics !== "object")
+        return null;
+    const diagnostics = err.responseDiagnostics;
+    const bytesRead = Number(diagnostics.streamStats?.bytesRead);
+    if (Number.isFinite(bytesRead) && bytesRead > 0 && Number(err.eventCount) === 0)
+        return "stream_parse_failed";
+    if (diagnostics.imageCallFailed === true)
+        return "image_tool_failed";
+    if (diagnostics.imageCallCompleted === true && Number(diagnostics.imageResultCount) === 0)
+        return "image_tool_completed_without_result";
+    if (diagnostics.imageCallSeen !== true && Number(err.webSearchCalls) > 0)
+        return "web_search_only_response";
+    if (diagnostics.imageCallSeen !== true && diagnostics.messageOutputSeen === true)
+        return "image_tool_not_called";
+    return null;
+}
+function responseDiagnosticCodeFrom(err) {
+    const reason = responseDiagnosticReasonFrom(err);
+    if (reason === "stream_parse_failed")
+        return "STREAM_PARSE_FAILED";
+    if (reason === "web_search_only_response")
+        return "WEB_SEARCH_ONLY_RESPONSE";
+    if (reason === "image_tool_not_called")
+        return "IMAGE_TOOL_NOT_CALLED";
+    if (reason === "image_tool_failed")
+        return "IMAGE_TOOL_FAILED";
+    if (reason === "image_tool_completed_without_result")
+        return "IMAGE_TOOL_COMPLETED_WITHOUT_RESULT";
+    return null;
+}
 export function errorCodeFrom(err) {
     if (!err)
         return "UNKNOWN";
+    const appCode = err.code;
+    if (RESPONSE_DIAGNOSTIC_CODES.has(appCode) || appCode === "EMPTY_RESPONSE")
+        return appCode;
     const upstreamCode = classifyUpstreamErrorCode(err.upstreamCode);
     if (upstreamCode !== "UNKNOWN")
         return upstreamCode;
@@ -36,14 +75,17 @@ export function errorCodeFrom(err) {
     if (upstreamType !== "UNKNOWN")
         return upstreamType;
     // Known app-level codes pass through directly (before message heuristic)
-    if (PASSTHROUGH_CODES.has(err.code) || SAFETY_CODES.has(err.code))
-        return err.code;
+    if (PASSTHROUGH_CODES.has(appCode) || SAFETY_CODES.has(appCode))
+        return appCode;
     const rawCode = classifyUpstreamErrorCode(err.code);
     if (rawCode !== "UNKNOWN")
         return rawCode;
     const direct = classifyUpstreamError(err.message);
     if (direct !== "UNKNOWN")
         return direct;
+    const responseDiagnosticCode = responseDiagnosticCodeFrom(err);
+    if (responseDiagnosticCode)
+        return responseDiagnosticCode;
     const status = Number(err.status);
     if (Number.isFinite(status) && status >= 400 && status < 500 && !SAFETY_CODES.has(err.code)) {
         return "INVALID_REQUEST";
@@ -70,14 +112,66 @@ export function statusForErrorCode(code, fallback = 500) {
         return 401;
     if (code === "UPSTREAM_5XX")
         return 502;
+    if (code === "RESPONSES_STREAM_ERROR")
+        return 502;
     if (code === "OAUTH_IMAGE_TIMEOUT")
         return 504;
     if (code === "INVALID_REQUEST")
         return 400;
+    if (RESPONSE_DIAGNOSTIC_CODES.has(code))
+        return 422;
     if (code === "SAFETY_REFUSAL" || code === "MODERATION_REFUSED" || code === "moderation_blocked")
         return 422;
     return fallback;
 }
+function copyEmptyResponseMetadata(target, source) {
+    if (!source)
+        return;
+    if (typeof source.eventCount === "number")
+        target.eventCount = source.eventCount;
+    if (source.eventTypes)
+        target.eventTypes = source.eventTypes;
+    if (typeof source.webSearchCalls === "number")
+        target.webSearchCalls = source.webSearchCalls;
+    if (source.responseDiagnostics)
+        target.responseDiagnostics = source.responseDiagnostics;
+    if (typeof source.webSearchEnabled === "boolean")
+        target.webSearchEnabled = source.webSearchEnabled;
+    if (Array.isArray(source.toolTypes))
+        target.toolTypes = source.toolTypes;
+    if (source.toolChoiceKind)
+        target.toolChoiceKind = source.toolChoiceKind;
+    if (typeof source.promptChars === "number")
+        target.promptChars = source.promptChars;
+    if (typeof source.refsCount === "number")
+        target.refsCount = source.refsCount;
+    if (typeof source.inputImageCount === "number")
+        target.inputImageCount = source.inputImageCount;
+    if (Array.isArray(source.referenceDiagnostics))
+        target.referenceDiagnostics = source.referenceDiagnostics;
+    if (typeof source.referenceMismatchCount === "number")
+        target.referenceMismatchCount = source.referenceMismatchCount;
+    if (source.retryKind)
+        target.retryKind = source.retryKind;
+    if (typeof source.initialEventCount === "number")
+        target.initialEventCount = source.initialEventCount;
+    if (source.initialEventTypes)
+        target.initialEventTypes = source.initialEventTypes;
+    if (typeof source.referencesDroppedOnRetry === "boolean")
+        target.referencesDroppedOnRetry = source.referencesDroppedOnRetry;
+    if (typeof source.developerPromptDroppedOnRetry === "boolean")
+        target.developerPromptDroppedOnRetry = source.developerPromptDroppedOnRetry;
+    if (typeof source.webSearchDroppedOnRetry === "boolean")
+        target.webSearchDroppedOnRetry = source.webSearchDroppedOnRetry;
+    if (typeof source.fallbackEventCount === "number")
+        target.fallbackEventCount = source.fallbackEventCount;
+    if (source.fallbackEventTypes)
+        target.fallbackEventTypes = source.fallbackEventTypes;
+    if (typeof source.fallbackImageCallSeen === "boolean")
+        target.fallbackImageCallSeen = source.fallbackImageCallSeen;
+    if (typeof source.fallbackImageResultCount === "number")
+        target.fallbackImageResultCount = source.fallbackImageResultCount;
+}
 export function normalizeGenerationFailure(lastErr, options = {}) {
     const code = errorCodeFrom(lastErr);
     if (PASSTHROUGH_CODES.has(code)) {
@@ -86,11 +180,11 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
         err.status = lastErr?.status || statusForErrorCode(code);
         err.cause = lastErr;
         if (lastErr?.upstreamCode)
-            err.upstreamCode = lastErr.upstreamCode;
+            err.upstreamCode = safeDiagnosticLabel(lastErr.upstreamCode);
         if (lastErr?.upstreamType)
-            err.upstreamType = lastErr.upstreamType;
+            err.upstreamType = safeDiagnosticLabel(lastErr.upstreamType);
         if (lastErr?.upstreamParam)
-            err.upstreamParam = lastErr.upstreamParam;
+            err.upstreamParam = safeDiagnosticLabel(lastErr.upstreamParam);
         if (lastErr?.eventType)
             err.eventType = lastErr.eventType;
         if (typeof lastErr?.eventCount === "number")
@@ -104,6 +198,23 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
         err.cause = lastErr;
         return err;
     }
+    if (RESPONSE_DIAGNOSTIC_CODES.has(code)) {
+        const err = new Error(lastErr?.message || "Image generation did not return image data");
+        err.code = code;
+        err.status = lastErr?.status || statusForErrorCode(code, 422);
+        err.cause = lastErr;
+        if (lastErr?.upstreamCode)
+            err.upstreamCode = safeDiagnosticLabel(lastErr.upstreamCode);
+        if (lastErr?.upstreamType)
+            err.upstreamType = safeDiagnosticLabel(lastErr.upstreamType);
+        if (lastErr?.upstreamParam)
+            err.upstreamParam = safeDiagnosticLabel(lastErr.upstreamParam);
+        if (lastErr?.eventType)
+            err.eventType = lastErr.eventType;
+        copyEmptyResponseMetadata(err, lastErr);
+        err.diagnosticReason = diagnosticReasonFrom(lastErr) || code.toLowerCase();
+        return err;
+    }
     // Empty response with metadata → likely a technical limitation (unsupported size/quality/model)
     if (typeof lastErr?.eventCount === "number") {
         const meta = [];
@@ -126,24 +237,11 @@ export function normalizeGenerationFailure(lastErr, options = {}) {
             err.quality = lastErr.quality;
         if (lastErr.model)
             err.model = lastErr.model;
-        if (typeof lastErr.eventCount === "number")
-            err.eventCount = lastErr.eventCount;
-        if (lastErr.eventTypes)
-            err.eventTypes = lastErr.eventTypes;
-        if (typeof lastErr.refsCount === "number")
-            err.refsCount = lastErr.refsCount;
-        if (typeof lastErr.inputImageCount === "number")
-            err.inputImageCount = lastErr.inputImageCount;
-        if (Array.isArray(lastErr.referenceDiagnostics))
-            err.referenceDiagnostics = lastErr.referenceDiagnostics;
-        if (typeof lastErr.referenceMismatchCount === "number")
-            err.referenceMismatchCount = lastErr.referenceMismatchCount;
-        if (lastErr.retryKind)
-            err.retryKind = lastErr.retryKind;
-        if (typeof lastErr.referencesDroppedOnRetry === "boolean")
-            err.referencesDroppedOnRetry = lastErr.referencesDroppedOnRetry;
-        if (typeof lastErr.developerPromptDroppedOnRetry === "boolean")
-            err.developerPromptDroppedOnRetry = lastErr.developerPromptDroppedOnRetry;
+        if (lastErr.provider)
+            err.provider = lastErr.provider;
+        if (lastErr.moderation)
+            err.moderation = lastErr.moderation;
+        copyEmptyResponseMetadata(err, lastErr);
         const diagnosticReason = diagnosticReasonFrom(lastErr);
         if (diagnosticReason)
             err.diagnosticReason = diagnosticReason;

package/lib/generationErrors.ts

@@ -1,4 +1,6 @@
 import { classifyUpstreamError, classifyUpstreamErrorCode } from "./errorClassify.js";
+import { safeDiagnosticLabel } from "./responsesParse.js";
+import { RESPONSE_DIAGNOSTIC_CODES } from "./responsesErrors.js";
 
 const PASSTHROUGH_CODES = new Set([
   "OAUTH_UNAVAILABLE",
@@ -34,14 +36,29 @@ export interface UpstreamErr {
   eventType?: string;
   eventCount?: number;
   eventTypes?: unknown;
+  webSearchCalls?: number;
+  responseDiagnostics?: unknown;
+  webSearchEnabled?: boolean;
+  toolTypes?: unknown;
+  toolChoiceKind?: string;
+  promptChars?: number;
   quality?: string;
+  moderation?: string;
   model?: string;
+  provider?: string;
   refsCount?: number;
   inputImageCount?: number;
   referenceDiagnostics?: unknown;
   retryKind?: string;
+  initialEventCount?: number;
+  initialEventTypes?: unknown;
   referencesDroppedOnRetry?: boolean;
   developerPromptDroppedOnRetry?: boolean;
+  webSearchDroppedOnRetry?: boolean;
+  fallbackEventCount?: number;
+  fallbackEventTypes?: unknown;
+  fallbackImageCallSeen?: boolean;
+  fallbackImageResultCount?: number;
   name?: string;
   stack?: string;
 }
@@ -49,22 +66,57 @@ export interface UpstreamErr {
 function diagnosticReasonFrom(err: UpstreamErr | null | undefined) {
   if (typeof err?.diagnosticReason === "string" && err.diagnosticReason) return err.diagnosticReason;
   if (Number(err?.referenceMismatchCount) > 0) return "reference_mime_mismatch_candidate";
+  const responseDiagnosticReason = responseDiagnosticReasonFrom(err);
+  if (responseDiagnosticReason) return responseDiagnosticReason;
   if (has4kSize(err?.size)) return "experimental_4k_empty_response";
   return null;
 }
 
+function responseDiagnosticReasonFrom(err: UpstreamErr | null | undefined) {
+  if (!err?.responseDiagnostics || typeof err.responseDiagnostics !== "object") return null;
+  const diagnostics = err.responseDiagnostics as {
+    imageCallSeen?: unknown;
+    imageCallCompleted?: unknown;
+    imageCallFailed?: unknown;
+    imageResultCount?: unknown;
+    messageOutputSeen?: unknown;
+    streamStats?: { bytesRead?: unknown };
+  };
+  const bytesRead = Number(diagnostics.streamStats?.bytesRead);
+  if (Number.isFinite(bytesRead) && bytesRead > 0 && Number(err.eventCount) === 0) return "stream_parse_failed";
+  if (diagnostics.imageCallFailed === true) return "image_tool_failed";
+  if (diagnostics.imageCallCompleted === true && Number(diagnostics.imageResultCount) === 0) return "image_tool_completed_without_result";
+  if (diagnostics.imageCallSeen !== true && Number(err.webSearchCalls) > 0) return "web_search_only_response";
+  if (diagnostics.imageCallSeen !== true && diagnostics.messageOutputSeen === true) return "image_tool_not_called";
+  return null;
+}
+
+function responseDiagnosticCodeFrom(err: UpstreamErr | null | undefined) {
+  const reason = responseDiagnosticReasonFrom(err);
+  if (reason === "stream_parse_failed") return "STREAM_PARSE_FAILED";
+  if (reason === "web_search_only_response") return "WEB_SEARCH_ONLY_RESPONSE";
+  if (reason === "image_tool_not_called") return "IMAGE_TOOL_NOT_CALLED";
+  if (reason === "image_tool_failed") return "IMAGE_TOOL_FAILED";
+  if (reason === "image_tool_completed_without_result") return "IMAGE_TOOL_COMPLETED_WITHOUT_RESULT";
+  return null;
+}
+
 export function errorCodeFrom(err: UpstreamErr | null | undefined): string {
   if (!err) return "UNKNOWN";
+  const appCode = err.code as string;
+  if (RESPONSE_DIAGNOSTIC_CODES.has(appCode) || appCode === "EMPTY_RESPONSE") return appCode;
   const upstreamCode = classifyUpstreamErrorCode(err.upstreamCode);
   if (upstreamCode !== "UNKNOWN") return upstreamCode;
   const upstreamType = classifyUpstreamErrorCode(err.upstreamType);
   if (upstreamType !== "UNKNOWN") return upstreamType;
   // Known app-level codes pass through directly (before message heuristic)
-  if (PASSTHROUGH_CODES.has(err.code as string) || SAFETY_CODES.has(err.code as string)) return err.code as string;
+  if (PASSTHROUGH_CODES.has(appCode) || SAFETY_CODES.has(appCode)) return appCode;
   const rawCode = classifyUpstreamErrorCode(err.code);
   if (rawCode !== "UNKNOWN") return rawCode;
   const direct = classifyUpstreamError(err.message);
   if (direct !== "UNKNOWN") return direct;
+  const responseDiagnosticCode = responseDiagnosticCodeFrom(err);
+  if (responseDiagnosticCode) return responseDiagnosticCode;
   const status = Number(err.status);
   if (Number.isFinite(status) && status >= 400 && status < 500 && !SAFETY_CODES.has(err.code as string)) {
     return "INVALID_REQUEST";
@@ -86,12 +138,40 @@ export function statusForErrorCode(code: string, fallback = 500) {
   if (code === "AUTH_CHATGPT_EXPIRED" || code === "AUTH_API_KEY_INVALID") return 401;
   if (code === "API_KEY_REQUIRED") return 401;
   if (code === "UPSTREAM_5XX") return 502;
+  if (code === "RESPONSES_STREAM_ERROR") return 502;
   if (code === "OAUTH_IMAGE_TIMEOUT") return 504;
   if (code === "INVALID_REQUEST") return 400;
+  if (RESPONSE_DIAGNOSTIC_CODES.has(code)) return 422;
   if (code === "SAFETY_REFUSAL" || code === "MODERATION_REFUSED" || code === "moderation_blocked") return 422;
   return fallback;
 }
 
+function copyEmptyResponseMetadata(target: any, source: UpstreamErr | null | undefined) {
+  if (!source) return;
+  if (typeof source.eventCount === "number") target.eventCount = source.eventCount;
+  if (source.eventTypes) target.eventTypes = source.eventTypes;
+  if (typeof source.webSearchCalls === "number") target.webSearchCalls = source.webSearchCalls;
+  if (source.responseDiagnostics) target.responseDiagnostics = source.responseDiagnostics;
+  if (typeof source.webSearchEnabled === "boolean") target.webSearchEnabled = source.webSearchEnabled;
+  if (Array.isArray(source.toolTypes)) target.toolTypes = source.toolTypes;
+  if (source.toolChoiceKind) target.toolChoiceKind = source.toolChoiceKind;
+  if (typeof source.promptChars === "number") target.promptChars = source.promptChars;
+  if (typeof source.refsCount === "number") target.refsCount = source.refsCount;
+  if (typeof source.inputImageCount === "number") target.inputImageCount = source.inputImageCount;
+  if (Array.isArray(source.referenceDiagnostics)) target.referenceDiagnostics = source.referenceDiagnostics;
+  if (typeof source.referenceMismatchCount === "number") target.referenceMismatchCount = source.referenceMismatchCount;
+  if (source.retryKind) target.retryKind = source.retryKind;
+  if (typeof source.initialEventCount === "number") target.initialEventCount = source.initialEventCount;
+  if (source.initialEventTypes) target.initialEventTypes = source.initialEventTypes;
+  if (typeof source.referencesDroppedOnRetry === "boolean") target.referencesDroppedOnRetry = source.referencesDroppedOnRetry;
+  if (typeof source.developerPromptDroppedOnRetry === "boolean") target.developerPromptDroppedOnRetry = source.developerPromptDroppedOnRetry;
+  if (typeof source.webSearchDroppedOnRetry === "boolean") target.webSearchDroppedOnRetry = source.webSearchDroppedOnRetry;
+  if (typeof source.fallbackEventCount === "number") target.fallbackEventCount = source.fallbackEventCount;
+  if (source.fallbackEventTypes) target.fallbackEventTypes = source.fallbackEventTypes;
+  if (typeof source.fallbackImageCallSeen === "boolean") target.fallbackImageCallSeen = source.fallbackImageCallSeen;
+  if (typeof source.fallbackImageResultCount === "number") target.fallbackImageResultCount = source.fallbackImageResultCount;
+}
+
 export function normalizeGenerationFailure(lastErr: UpstreamErr | null | undefined, options: any = {}) {
   const code = errorCodeFrom(lastErr);
   if (PASSTHROUGH_CODES.has(code)) {
@@ -99,9 +179,9 @@ export function normalizeGenerationFailure(lastErr: UpstreamErr | null | undefin
     err.code = code;
     err.status = lastErr?.status || statusForErrorCode(code);
     err.cause = lastErr;
-    if (lastErr?.upstreamCode) err.upstreamCode = lastErr.upstreamCode;
-    if (lastErr?.upstreamType) err.upstreamType = lastErr.upstreamType;
-    if (lastErr?.upstreamParam) err.upstreamParam = lastErr.upstreamParam;
+    if (lastErr?.upstreamCode) err.upstreamCode = safeDiagnosticLabel(lastErr.upstreamCode);
+    if (lastErr?.upstreamType) err.upstreamType = safeDiagnosticLabel(lastErr.upstreamType);
+    if (lastErr?.upstreamParam) err.upstreamParam = safeDiagnosticLabel(lastErr.upstreamParam);
     if (lastErr?.eventType) err.eventType = lastErr.eventType;
     if (typeof lastErr?.eventCount === "number") err.eventCount = lastErr.eventCount;
     return err;
@@ -113,6 +193,19 @@ export function normalizeGenerationFailure(lastErr: UpstreamErr | null | undefin
     err.cause = lastErr;
     return err;
   }
+  if (RESPONSE_DIAGNOSTIC_CODES.has(code)) {
+    const err: any = new Error(lastErr?.message || "Image generation did not return image data");
+    err.code = code;
+    err.status = lastErr?.status || statusForErrorCode(code, 422);
+    err.cause = lastErr;
+    if (lastErr?.upstreamCode) err.upstreamCode = safeDiagnosticLabel(lastErr.upstreamCode);
+    if (lastErr?.upstreamType) err.upstreamType = safeDiagnosticLabel(lastErr.upstreamType);
+    if (lastErr?.upstreamParam) err.upstreamParam = safeDiagnosticLabel(lastErr.upstreamParam);
+    if (lastErr?.eventType) err.eventType = lastErr.eventType;
+    copyEmptyResponseMetadata(err, lastErr);
+    err.diagnosticReason = diagnosticReasonFrom(lastErr) || code.toLowerCase();
+    return err;
+  }
   // Empty response with metadata → likely a technical limitation (unsupported size/quality/model)
   if (typeof lastErr?.eventCount === "number") {
     const meta: string[] = [];
@@ -129,15 +222,9 @@ export function normalizeGenerationFailure(lastErr: UpstreamErr | null | undefin
     if (lastErr.size) err.size = lastErr.size;
     if (lastErr.quality) err.quality = lastErr.quality;
     if (lastErr.model) err.model = lastErr.model;
-    if (typeof lastErr.eventCount === "number") err.eventCount = lastErr.eventCount;
-    if (lastErr.eventTypes) err.eventTypes = lastErr.eventTypes;
-    if (typeof lastErr.refsCount === "number") err.refsCount = lastErr.refsCount;
-    if (typeof lastErr.inputImageCount === "number") err.inputImageCount = lastErr.inputImageCount;
-    if (Array.isArray(lastErr.referenceDiagnostics)) err.referenceDiagnostics = lastErr.referenceDiagnostics;
-    if (typeof lastErr.referenceMismatchCount === "number") err.referenceMismatchCount = lastErr.referenceMismatchCount;
-    if (lastErr.retryKind) err.retryKind = lastErr.retryKind;
-    if (typeof lastErr.referencesDroppedOnRetry === "boolean") err.referencesDroppedOnRetry = lastErr.referencesDroppedOnRetry;
-    if (typeof lastErr.developerPromptDroppedOnRetry === "boolean") err.developerPromptDroppedOnRetry = lastErr.developerPromptDroppedOnRetry;
+    if (lastErr.provider) err.provider = lastErr.provider;
+    if (lastErr.moderation) err.moderation = lastErr.moderation;
+    copyEmptyResponseMetadata(err, lastErr);
     const diagnosticReason = diagnosticReasonFrom(lastErr);
     if (diagnosticReason) err.diagnosticReason = diagnosticReason;
     return err;