ima2-gen 1.1.0 → 1.1.2

package/lib/cardNewsPlannerSchema.js

@@ -0,0 +1,259 @@
+export const CARD_NEWS_TEXT_KINDS = ["headline", "body", "caption", "cta", "badge", "number"];
+export const CARD_NEWS_RENDER_MODES = ["in-image", "ui-only"];
+export const CARD_NEWS_PLACEMENTS = [
+  "top-left",
+  "top-center",
+  "top-right",
+  "center-left",
+  "center",
+  "center-right",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right",
+  "free",
+];
+export const CARD_NEWS_HIERARCHIES = ["primary", "secondary", "supporting"];
+export const CARD_NEWS_TEXT_SOURCES = ["planner", "user"];
+
+const TEXT_FIELD_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "id",
+    "kind",
+    "text",
+    "renderMode",
+    "placement",
+    "slotId",
+    "hierarchy",
+    "maxChars",
+    "language",
+    "source",
+  ],
+  properties: {
+    id: { type: "string" },
+    kind: { type: "string", enum: CARD_NEWS_TEXT_KINDS },
+    text: { type: "string" },
+    renderMode: { type: "string", enum: CARD_NEWS_RENDER_MODES },
+    placement: { type: "string", enum: CARD_NEWS_PLACEMENTS },
+    slotId: { type: ["string", "null"] },
+    hierarchy: { type: "string", enum: CARD_NEWS_HIERARCHIES },
+    maxChars: { type: ["integer", "null"] },
+    language: { type: ["string", "null"] },
+    source: { type: "string", enum: CARD_NEWS_TEXT_SOURCES },
+  },
+};
+
+export const CARD_NEWS_PLANNER_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["title", "topic", "cards"],
+  properties: {
+    title: { type: "string" },
+    topic: { type: "string" },
+    audience: { type: "string" },
+    goal: { type: "string" },
+    cards: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["order", "role", "headline", "body", "visualPrompt", "textFields", "references", "locked"],
+        properties: {
+          order: { type: "integer" },
+          role: { type: "string" },
+          headline: { type: "string" },
+          body: { type: "string" },
+          visualPrompt: { type: "string" },
+          textFields: { type: "array", items: TEXT_FIELD_SCHEMA },
+          references: { type: "array", items: { type: "string" } },
+          locked: { type: "boolean" },
+        },
+      },
+    },
+  },
+};
+
+function asText(value, fallback = "") {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function detectBriefLanguage(input = {}) {
+  const text = [input.topic, input.audience, input.goal, input.contentBrief].filter(Boolean).join(" ");
+  if (/[가-힣]/.test(text)) return "ko";
+  if (/[A-Za-z]/.test(text)) return "en";
+  return "und";
+}
+
+function fallbackCopy(input = {}, kind = "body") {
+  const lang = detectBriefLanguage(input);
+  const topic = asText(input.topic, asText(input.title, "Card news"));
+  const goal = asText(input.goal, topic);
+  const brief = asText(input.contentBrief, goal);
+  if (kind === "headline") return topic;
+  if (lang === "ko") return brief || `${topic} 핵심 내용을 정리합니다.`;
+  if (lang === "en") return brief || `Summarize the key point for ${topic}.`;
+  return brief || topic;
+}
+
+function normalizeTextField(field, index) {
+  if (!field || typeof field !== "object") return null;
+  const text = asText(field.text);
+  if (!text) return null;
+  return {
+    id: asText(field.id, `tf_${index + 1}`),
+    kind: CARD_NEWS_TEXT_KINDS.includes(field.kind) ? field.kind : "body",
+    text,
+    renderMode: CARD_NEWS_RENDER_MODES.includes(field.renderMode) ? field.renderMode : "in-image",
+    placement: CARD_NEWS_PLACEMENTS.includes(field.placement) ? field.placement : "free",
+    slotId: typeof field.slotId === "string" && field.slotId.trim() ? field.slotId.trim() : null,
+    hierarchy: CARD_NEWS_HIERARCHIES.includes(field.hierarchy) ? field.hierarchy : "supporting",
+    maxChars: Number.isInteger(field.maxChars) ? field.maxChars : null,
+    language: typeof field.language === "string" && field.language.trim() ? field.language.trim() : null,
+    source: CARD_NEWS_TEXT_SOURCES.includes(field.source) ? field.source : "planner",
+  };
+}
+
+function normalizeTextFields(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map(normalizeTextField).filter(Boolean);
+}
+
+function stripExactVisibleText(visualPrompt, textFields) {
+  let next = asText(visualPrompt);
+  for (const field of textFields) {
+    const text = asText(field.text);
+    if (text.length >= 4 && next.includes(text)) {
+      next = next.split(text).join("visible text box");
+    }
+  }
+  return next.trim();
+}
+
+function normalizeCard(card, role, index, input) {
+  const topic = asText(input.topic, "Card news");
+  const textFields = normalizeTextFields(card?.textFields);
+  return {
+    order: index + 1,
+    role: role.role,
+    headline: asText(card?.headline, index === 0 ? topic : fallbackCopy(input, "headline")),
+    body: asText(card?.body, fallbackCopy(input, "body")),
+    visualPrompt: stripExactVisibleText(
+      asText(card?.visualPrompt, `${asText(role.promptHint, role.role)}, ${topic}`),
+      textFields,
+    ),
+    textFields,
+    references: Array.isArray(card?.references)
+      ? card.references.filter((ref) => typeof ref === "string")
+      : [],
+    locked: false,
+  };
+}
+
+export function repairPlannerOutput(output, input = {}) {
+  const roles = input.roleTemplate?.roles || [];
+  const cards = roles.map((role, index) => {
+    const original = Array.isArray(output?.cards) ? output.cards[index] : null;
+    return normalizeCard(original, role, index, input);
+  });
+  return {
+    ok: true,
+    repaired: true,
+    errors: [],
+    plan: {
+      title: asText(output?.title, asText(input.topic, "Untitled card news")),
+      topic: asText(output?.topic, asText(input.topic, "Untitled card news")),
+      audience: asText(output?.audience, asText(input.audience)),
+      goal: asText(output?.goal, asText(input.goal)),
+      cards,
+    },
+  };
+}
+
+function validateTextField(field, path, errors) {
+  if (!field || typeof field !== "object") {
+    errors.push(`${path} must be object`);
+    return;
+  }
+  if (typeof field.id !== "string") errors.push(`${path}.id must be string`);
+  if (!CARD_NEWS_TEXT_KINDS.includes(field.kind)) errors.push(`${path}.kind invalid`);
+  if (typeof field.text !== "string") errors.push(`${path}.text must be string`);
+  if (typeof field.text === "string" && !field.text.trim()) errors.push(`${path}.text must not be empty`);
+  if (!CARD_NEWS_RENDER_MODES.includes(field.renderMode)) errors.push(`${path}.renderMode invalid`);
+  if (!CARD_NEWS_PLACEMENTS.includes(field.placement)) errors.push(`${path}.placement invalid`);
+  if (!(typeof field.slotId === "string" || field.slotId === null)) errors.push(`${path}.slotId invalid`);
+  if (!CARD_NEWS_HIERARCHIES.includes(field.hierarchy)) errors.push(`${path}.hierarchy invalid`);
+  if (!(Number.isInteger(field.maxChars) || field.maxChars === null)) errors.push(`${path}.maxChars invalid`);
+  if (!(typeof field.language === "string" || field.language === null)) errors.push(`${path}.language invalid`);
+  if (!CARD_NEWS_TEXT_SOURCES.includes(field.source)) errors.push(`${path}.source invalid`);
+}
+
+export function validatePlannerOutput(output, roleTemplate) {
+  const errors = [];
+  if (!output || typeof output !== "object" || Array.isArray(output)) {
+    return { ok: false, repaired: false, errors: ["output must be an object"] };
+  }
+  if (typeof output.title !== "string") errors.push("title must be a string");
+  if (typeof output.topic !== "string") errors.push("topic must be a string");
+  if (!Array.isArray(output.cards)) errors.push("cards must be an array");
+
+  const roles = roleTemplate?.roles || [];
+  if (Array.isArray(output.cards) && output.cards.length !== roles.length) {
+    errors.push("cards length must match role template");
+  }
+
+  const cards = Array.isArray(output.cards) ? output.cards : [];
+  cards.forEach((card, index) => {
+    const expected = roles[index];
+    if (!card || typeof card !== "object") {
+      errors.push(`card ${index + 1} must be an object`);
+      return;
+    }
+    if (card.order !== index + 1) errors.push(`card ${index + 1} order mismatch`);
+    if (expected && card.role !== expected.role) errors.push(`card ${index + 1} role mismatch`);
+    for (const key of ["headline", "body", "visualPrompt"]) {
+      if (typeof card[key] !== "string") errors.push(`card ${index + 1} ${key} must be string`);
+    }
+    if (!Array.isArray(card.textFields)) errors.push(`card ${index + 1} textFields must be array`);
+    if (Array.isArray(card.textFields)) {
+      card.textFields.forEach((field, fieldIndex) =>
+        validateTextField(field, `card ${index + 1} textFields ${fieldIndex + 1}`, errors));
+      for (const field of card.textFields) {
+        if (
+          field?.renderMode === "in-image" &&
+          typeof field.text === "string" &&
+          field.text.trim().length >= 4 &&
+          typeof card.visualPrompt === "string" &&
+          card.visualPrompt.includes(field.text.trim())
+        ) {
+          errors.push(`card ${index + 1} visualPrompt must not duplicate exact visible text`);
+        }
+      }
+    }
+    if (!Array.isArray(card.references)) errors.push(`card ${index + 1} references must be array`);
+    if (card.locked !== false) errors.push(`card ${index + 1} locked must be false`);
+  });
+
+  if (errors.length) return { ok: false, repaired: false, errors };
+  return {
+    ok: true,
+    repaired: false,
+    errors: [],
+    plan: {
+      title: output.title.trim(),
+      topic: output.topic.trim(),
+      audience: asText(output.audience),
+      goal: asText(output.goal),
+      cards: cards.map((card) => ({
+        order: card.order,
+        role: card.role,
+        headline: card.headline.trim(),
+        body: card.body.trim(),
+        visualPrompt: card.visualPrompt.trim(),
+        textFields: normalizeTextFields(card.textFields),
+        references: card.references.filter((ref) => typeof ref === "string"),
+        locked: false,
+      })),
+    },
+  };
+}

package/lib/cardNewsRoleTemplateStore.js

@@ -0,0 +1,47 @@
+const ROLE_TEMPLATES = [
+  {
+    id: "short-3",
+    name: "Short 3",
+    defaultCount: 3,
+    roles: [
+      { role: "hook", required: true, promptHint: "strong opening card", preferredSlots: ["title", "visual"] },
+      { role: "core", required: true, promptHint: "main explanation card", preferredSlots: ["visual", "body"] },
+      { role: "cta", required: true, promptHint: "clear call to action card", preferredSlots: ["cta"] },
+    ],
+  },
+  {
+    id: "mid-5",
+    name: "Mid 5",
+    defaultCount: 5,
+    roles: [
+      { role: "cover", required: true, promptHint: "cover card with strong headline", preferredSlots: ["title", "visual"] },
+      { role: "problem", required: true, promptHint: "problem framing card", preferredSlots: ["title", "body"] },
+      { role: "insight", required: true, promptHint: "insight or solution card", preferredSlots: ["visual", "body"] },
+      { role: "example", required: true, promptHint: "example or proof card", preferredSlots: ["visual", "body"] },
+      { role: "cta", required: true, promptHint: "closing call to action card", preferredSlots: ["cta"] },
+    ],
+  },
+  {
+    id: "long-8",
+    name: "Long 8",
+    defaultCount: 8,
+    roles: [
+      { role: "cover", required: true, promptHint: "cover card", preferredSlots: ["title"] },
+      { role: "problem", required: true, promptHint: "problem card", preferredSlots: ["body"] },
+      { role: "data", required: true, promptHint: "data card", preferredSlots: ["visual"] },
+      { role: "tip1", required: true, promptHint: "first tip card", preferredSlots: ["body"] },
+      { role: "tip2", required: true, promptHint: "second tip card", preferredSlots: ["body"] },
+      { role: "example", required: true, promptHint: "example card", preferredSlots: ["visual"] },
+      { role: "summary", required: true, promptHint: "summary card", preferredSlots: ["body"] },
+      { role: "cta", required: true, promptHint: "call to action card", preferredSlots: ["cta"] },
+    ],
+  },
+];
+
+export function listRoleTemplates() {
+  return ROLE_TEMPLATES;
+}
+
+export function getRoleTemplate(roleTemplateId = "mid-5") {
+  return ROLE_TEMPLATES.find((t) => t.id === roleTemplateId) || ROLE_TEMPLATES[1];
+}

package/lib/cardNewsTemplateStore.js

@@ -0,0 +1,210 @@
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, join, normalize, sep } from "node:path";
+
+const TEMPLATE_ROOT = ["assets", "card-news", "templates"];
+const IMAGE_TEMPLATE_REGISTRY = [
+  {
+    id: "clean-report-square",
+    label: "Clean editorial report",
+    recommendedOutputSizes: ["1024x1024", "2048x2048"],
+  },
+  {
+    id: "academy-lesson-square",
+    label: "Academy lesson carousel",
+    recommendedOutputSizes: ["1024x1024", "2048x2048"],
+  },
+];
+const OUTPUT_SIZE_RE = /^(1024|2048|[1-3][0-9]{3})x(1024|2048|[1-3][0-9]{3})$/;
+const PLACEMENTS = new Set([
+  "top-left",
+  "top-center",
+  "top-right",
+  "center-left",
+  "center",
+  "center-right",
+  "bottom-left",
+  "bottom-center",
+  "bottom-right",
+  "free",
+]);
+
+function assertSafeId(id) {
+  if (typeof id !== "string" || !/^[a-z0-9][a-z0-9-]{1,80}$/.test(id)) {
+    const err = new Error("Invalid template id");
+    err.status = 400;
+    err.code = "CARD_NEWS_BAD_TEMPLATE_ID";
+    throw err;
+  }
+}
+
+function templateDir(ctx, templateId) {
+  assertSafeId(templateId);
+  const root = join(ctx.rootDir, ...TEMPLATE_ROOT);
+  const dir = join(root, templateId);
+  const normalizedRoot = normalize(root + sep);
+  const normalizedDir = normalize(dir + sep);
+  if (!normalizedDir.startsWith(normalizedRoot)) {
+    const err = new Error("Template path escapes root");
+    err.status = 400;
+    err.code = "CARD_NEWS_BAD_TEMPLATE_PATH";
+    throw err;
+  }
+  return dir;
+}
+
+function publicTemplate(t) {
+  return {
+    id: t.id,
+    name: t.name,
+    description: t.description || "",
+    size: t.size,
+    previewUrl: `/api/cardnews/image-templates/${encodeURIComponent(t.id)}/preview`,
+    stylePrompt: t.stylePrompt,
+    negativePrompt: t.negativePrompt || "",
+    slots: normalizeSlots(t.slots),
+    palette: t.palette || [],
+    typography: t.typography || null,
+    recommendedOutputSizes: Array.isArray(t.recommendedOutputSizes) ? t.recommendedOutputSizes : [],
+    authoringLabel: t.authoringLabel || t.name,
+    recommendedRoleNodeIds: t.recommendedRoleNodeIds || [],
+    createdBy: t.createdBy || "system",
+  };
+}
+
+function normalizeLegacySlotKind(kind) {
+  if (kind === "title") return { kind: "text", textKind: "headline" };
+  if (kind === "body") return { kind: "text", textKind: "body" };
+  if (kind === "cta") return { kind: "text", textKind: "cta" };
+  if (kind === "image") return { kind: "image", textKind: null };
+  if (kind === "text" || kind === "mixed" || kind === "safe-area") return { kind, textKind: null };
+  return { kind: "mixed", textKind: null };
+}
+
+function normalizeSlot(slot = {}) {
+  const legacy = normalizeLegacySlotKind(slot.kind);
+  return {
+    ...slot,
+    id: typeof slot.id === "string" && slot.id ? slot.id : "slot",
+    kind: legacy.kind,
+    textKind: slot.textKind || legacy.textKind || null,
+    label: typeof slot.label === "string" && slot.label ? slot.label : (slot.id || "slot"),
+    placement: PLACEMENTS.has(slot.placement) ? slot.placement : "free",
+    x: Number.isFinite(slot.x) ? slot.x : 0,
+    y: Number.isFinite(slot.y) ? slot.y : 0,
+    w: Number.isFinite(slot.w) ? slot.w : 100,
+    h: Number.isFinite(slot.h) ? slot.h : 100,
+    required: Boolean(slot.required),
+    maxChars: Number.isFinite(slot.maxChars) ? slot.maxChars : null,
+    safeArea: Boolean(slot.safeArea),
+  };
+}
+
+function normalizeSlots(slots) {
+  return Array.isArray(slots) ? slots.map(normalizeSlot) : [];
+}
+
+function registryEntry(templateId) {
+  return IMAGE_TEMPLATE_REGISTRY.find((entry) => entry.id === templateId);
+}
+
+function validateTemplateAuthoring(template) {
+  const problems = [];
+  if (typeof template.name !== "string" || !template.name.trim()) problems.push("name");
+  if (typeof template.size !== "string" || !OUTPUT_SIZE_RE.test(template.size)) problems.push("size");
+  if (typeof template.stylePrompt !== "string" || !template.stylePrompt.trim()) problems.push("stylePrompt");
+  if (!Array.isArray(template.slots) || template.slots.length === 0) problems.push("slots");
+  const ids = new Set();
+  for (const slot of normalizeSlots(template.slots)) {
+    if (ids.has(slot.id)) problems.push(`duplicate slot ${slot.id}`);
+    ids.add(slot.id);
+    if (!PLACEMENTS.has(slot.placement)) problems.push(`slot ${slot.id} placement`);
+    if ((slot.kind === "text" || slot.textKind) && !slot.maxChars) problems.push(`slot ${slot.id} maxChars`);
+  }
+  if (
+    template.recommendedOutputSizes &&
+    (!Array.isArray(template.recommendedOutputSizes) ||
+      template.recommendedOutputSizes.some((size) => typeof size !== "string" || !OUTPUT_SIZE_RE.test(size)))
+  ) {
+    problems.push("recommendedOutputSizes");
+  }
+  if (problems.length) {
+    const err = new Error(`Template authoring metadata invalid: ${problems.join(", ")}`);
+    err.status = 500;
+    err.code = "CARD_NEWS_TEMPLATE_AUTHORING_INVALID";
+    throw err;
+  }
+}
+
+async function readTemplate(ctx, templateId) {
+  const dir = templateDir(ctx, templateId);
+  const raw = await readFile(join(dir, "template.json"), "utf8");
+  const parsed = JSON.parse(raw);
+  const id = parsed.id || templateId;
+  if (id !== templateId) {
+    const err = new Error("Template id mismatch");
+    err.status = 500;
+    err.code = "CARD_NEWS_TEMPLATE_ID_MISMATCH";
+    throw err;
+  }
+  const entry = registryEntry(templateId);
+  if (!entry) {
+    const err = new Error("Template is not registered");
+    err.status = 500;
+    err.code = "CARD_NEWS_TEMPLATE_NOT_REGISTERED";
+    throw err;
+  }
+  validateTemplateAuthoring(parsed);
+  return {
+    ...parsed,
+    authoringLabel: parsed.authoringLabel || entry.label,
+    recommendedOutputSizes: parsed.recommendedOutputSizes || entry.recommendedOutputSizes,
+    slots: normalizeSlots(parsed.slots),
+    previewFilename: parsed.previewFilename || "preview.png",
+    baseFilename: parsed.baseFilename || "base.png",
+    createdBy: "system",
+  };
+}
+
+export async function listImageTemplates(ctx) {
+  const templates = [];
+  for (const entry of IMAGE_TEMPLATE_REGISTRY) {
+    templates.push(publicTemplate(await readTemplate(ctx, entry.id)));
+  }
+  return templates;
+}
+
+export async function getImageTemplate(ctx, templateId) {
+  return readTemplate(ctx, templateId);
+}
+
+export async function readTemplatePreview(ctx, templateId) {
+  const template = await readTemplate(ctx, templateId);
+  const filename = basename(template.previewFilename || "preview.png");
+  const path = join(templateDir(ctx, templateId), filename);
+  if (!existsSync(path)) {
+    const err = new Error("Template preview not found");
+    err.status = 404;
+    err.code = "CARD_NEWS_TEMPLATE_PREVIEW_NOT_FOUND";
+    throw err;
+  }
+  return readFile(path);
+}
+
+export async function readTemplateBaseB64(ctx, templateId) {
+  const template = await readTemplate(ctx, templateId);
+  const filename = basename(template.baseFilename || "base.png");
+  const path = join(templateDir(ctx, templateId), filename);
+  if (!existsSync(path)) {
+    const err = new Error("Template base image not found");
+    err.status = 404;
+    err.code = "CARD_NEWS_TEMPLATE_BASE_NOT_FOUND";
+    throw err;
+  }
+  const buf = await readFile(path);
+  return {
+    template,
+    templateBase: join(...TEMPLATE_ROOT, templateId, filename),
+    b64: buf.toString("base64"),
+  };
+}

package/lib/db.js

@@ -59,6 +59,23 @@ function migrate(database) {
 
     CREATE INDEX IF NOT EXISTS idx_nodes_session ON nodes(session_id);
     CREATE INDEX IF NOT EXISTS idx_edges_session ON edges(session_id);
+
+    CREATE TABLE IF NOT EXISTS inflight (
+      request_id     TEXT PRIMARY KEY,
+      kind           TEXT NOT NULL,
+      prompt         TEXT NOT NULL DEFAULT '',
+      meta           TEXT NOT NULL DEFAULT '{}',
+      session_id     TEXT,
+      parent_node_id TEXT,
+      client_node_id TEXT,
+      started_at     INTEGER NOT NULL,
+      phase          TEXT NOT NULL DEFAULT 'queued',
+      phase_at       INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_inflight_started ON inflight(started_at);
+    CREATE INDEX IF NOT EXISTS idx_inflight_kind ON inflight(kind);
+    CREATE INDEX IF NOT EXISTS idx_inflight_session ON inflight(session_id);
   `);
 
   const sessionColumns = database
@@ -81,10 +98,10 @@ function migrate(database) {
 
   const row = database.prepare("SELECT value FROM _meta WHERE key = 'schema_version'").get();
   if (!row) {
-    database.prepare("INSERT INTO _meta (key, value) VALUES ('schema_version', '2')").run();
-  } else if (row.value !== "2") {
+    database.prepare("INSERT INTO _meta (key, value) VALUES ('schema_version', '3')").run();
+  } else if (row.value !== "3") {
     database
-      .prepare("UPDATE _meta SET value = '2' WHERE key = 'schema_version'")
+      .prepare("UPDATE _meta SET value = '3' WHERE key = 'schema_version'")
       .run();
   }
 }

package/lib/errorClassify.js

@@ -15,7 +15,7 @@ export function classifyUpstreamError(msg) {
   const s = String(msg || "").toLowerCase();
   if (!s) return "UNKNOWN";
 
-  if (s.includes("content generation refused") || s.includes("moderation_blocked") || s.includes("moderation refused")) {
+  if (s.includes("moderation_blocked") || s.includes("moderation refused")) {
     return "MODERATION_REFUSED";
   }
 
@@ -50,7 +50,7 @@ export function classifyUpstreamError(msg) {
     return "NETWORK_FAILED";
   }
 
-  if (s.includes("oauth") && (s.includes("not running") || s.includes("unavailable"))) {
+  if (s.includes("oauth") && (s.includes("not running") || s.includes("unavailable") || s.includes("not ready"))) {
     return "OAUTH_UNAVAILABLE";
   }
 

package/lib/generationErrors.js

@@ -0,0 +1,51 @@
+import { classifyUpstreamError } from "./errorClassify.js";
+
+const PASSTHROUGH_CODES = new Set([
+  "OAUTH_UNAVAILABLE",
+  "NETWORK_FAILED",
+  "AUTH_CHATGPT_EXPIRED",
+  "AUTH_API_KEY_INVALID",
+  "UPSTREAM_5XX",
+]);
+
+const SAFETY_CODES = new Set(["SAFETY_REFUSAL", "MODERATION_REFUSED", "moderation_blocked"]);
+
+export function errorCodeFrom(err) {
+  if (!err) return "UNKNOWN";
+  if (typeof err.code === "string" && err.code) return err.code;
+  const direct = classifyUpstreamError(err.message);
+  if (direct !== "UNKNOWN") return direct;
+  if (err.cause) return errorCodeFrom(err.cause);
+  return "UNKNOWN";
+}
+
+export function statusForErrorCode(code, fallback = 500) {
+  if (code === "OAUTH_UNAVAILABLE" || code === "NETWORK_FAILED") return 503;
+  if (code === "AUTH_CHATGPT_EXPIRED" || code === "AUTH_API_KEY_INVALID") return 401;
+  if (code === "UPSTREAM_5XX") return 502;
+  if (code === "SAFETY_REFUSAL" || code === "MODERATION_REFUSED" || code === "moderation_blocked") return 422;
+  return fallback;
+}
+
+export function normalizeGenerationFailure(lastErr, options = {}) {
+  const code = errorCodeFrom(lastErr);
+  if (PASSTHROUGH_CODES.has(code)) {
+    const err = new Error(lastErr?.message || options.proxyMessage || "OAuth proxy/network failure");
+    err.code = code;
+    err.status = lastErr?.status || statusForErrorCode(code);
+    err.cause = lastErr;
+    return err;
+  }
+  if (SAFETY_CODES.has(code)) {
+    const err = new Error(options.safetyMessage || lastErr?.message || "Content generation refused after retries");
+    err.code = "SAFETY_REFUSAL";
+    err.status = 422;
+    err.cause = lastErr;
+    return err;
+  }
+  const err = new Error(options.safetyMessage || "Content generation refused after retries");
+  err.code = "SAFETY_REFUSAL";
+  err.status = 422;
+  err.cause = lastErr;
+  return err;
+}