ima2-gen 1.0.6 → 1.0.8

package/lib/styleSheet.js

@@ -0,0 +1,128 @@
+// Style-sheet extractor (0.10)
+//
+// Uses GPT-5.4 (chat completions) to derive a structured "style guide" from a
+// user prompt and optional reference image. The style guide is stored per
+// session and automatically prepended to subsequent image generations so
+// continuations feel cohesive — closer to ChatGPT 4o's image carry-over.
+//
+// Shape:
+//   {
+//     palette: string[],         // e.g. ["deep navy", "gold leaf"]
+//     composition: string,       // e.g. "centered 3/4 portrait, shallow depth"
+//     mood: string,              // e.g. "melancholic, reverent"
+//     medium: string,            // e.g. "oil painting, glazed layers"
+//     subject_details: string,   // identity/pose/outfit cues for character continuity
+//     negative: string[]         // things to avoid
+//   }
+//
+// The module is pure JS + openai SDK. When no API key is configured it throws
+// STYLE_SHEET_NO_KEY so callers can surface a friendly "connect key" UI.
+
+import { config } from "../config.js";
+const STYLE_SHEET_MODEL = config.styleSheet.model;
+
+const SYSTEM_PROMPT = `You extract a reusable visual style guide from a user
+image prompt (and an optional reference image). Return ONLY a JSON object with
+these keys: palette (array of 3-6 concrete color names), composition (one
+sentence), mood (2-4 comma-separated adjectives), medium (one short phrase
+naming technique/material), subject_details (one sentence capturing identity
+cues: face, outfit, pose, distinctive features), negative (array of 0-4 short
+phrases of things to avoid). Keep entries tight — each under 120 characters.
+Do not wrap in markdown. Do not add commentary.`;
+
+function coerceStyleSheet(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const arr = (v, max = 6) =>
+    Array.isArray(v)
+      ? v
+          .filter((x) => typeof x === "string" && x.trim())
+          .slice(0, max)
+          .map((s) => s.trim())
+      : [];
+  const str = (v) => (typeof v === "string" ? v.trim().slice(0, 400) : "");
+  const sheet = {
+    palette: arr(raw.palette, 6),
+    composition: str(raw.composition),
+    mood: str(raw.mood),
+    medium: str(raw.medium),
+    subject_details: str(raw.subject_details),
+    negative: arr(raw.negative, 4),
+  };
+  const hasContent =
+    sheet.palette.length > 0 ||
+    sheet.negative.length > 0 ||
+    sheet.composition ||
+    sheet.mood ||
+    sheet.medium ||
+    sheet.subject_details;
+  return hasContent ? sheet : null;
+}
+
+export async function extractStyleSheet(openai, { prompt, referenceDataUrl }) {
+  if (!openai) {
+    const err = new Error("No OpenAI client configured for style-sheet extraction");
+    err.code = "STYLE_SHEET_NO_KEY";
+    throw err;
+  }
+  if (!prompt || typeof prompt !== "string" || !prompt.trim()) {
+    const err = new Error("prompt is required");
+    err.code = "STYLE_SHEET_BAD_INPUT";
+    throw err;
+  }
+
+  const userContent = referenceDataUrl
+    ? [
+        { type: "text", text: prompt },
+        { type: "image_url", image_url: { url: referenceDataUrl } },
+      ]
+    : prompt;
+
+  const resp = await openai.chat.completions.create({
+    model: STYLE_SHEET_MODEL,
+    response_format: { type: "json_object" },
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: userContent },
+    ],
+  });
+
+  const raw = resp.choices?.[0]?.message?.content;
+  if (!raw) {
+    const err = new Error("Empty response from style-sheet model");
+    err.code = "STYLE_SHEET_EMPTY";
+    throw err;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    const err = new Error("Style-sheet model returned non-JSON");
+    err.code = "STYLE_SHEET_PARSE";
+    throw err;
+  }
+
+  const sheet = coerceStyleSheet(parsed);
+  if (!sheet) {
+    const err = new Error("Style-sheet shape invalid");
+    err.code = "STYLE_SHEET_SHAPE";
+    throw err;
+  }
+  return sheet;
+}
+
+// Render a style sheet into a prompt preamble that gpt-image-1/2 can consume.
+// Kept short so it doesn't blow the 4K prompt window on long user prompts.
+export function renderStyleSheetPrefix(sheet) {
+  if (!sheet) return "";
+  const parts = [];
+  if (sheet.medium) parts.push(`Medium: ${sheet.medium}.`);
+  if (sheet.palette?.length) parts.push(`Palette: ${sheet.palette.join(", ")}.`);
+  if (sheet.composition) parts.push(`Composition: ${sheet.composition}.`);
+  if (sheet.mood) parts.push(`Mood: ${sheet.mood}.`);
+  if (sheet.subject_details) parts.push(`Subject: ${sheet.subject_details}.`);
+  if (sheet.negative?.length) parts.push(`Avoid: ${sheet.negative.join(", ")}.`);
+  return parts.join(" ");
+}
+
+export { STYLE_SHEET_MODEL, SYSTEM_PROMPT, coerceStyleSheet };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "GPT Image 2 generator with OAuth & API key support",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "test": "node scripts/run-tests.mjs",
     "setup": "node bin/ima2.js setup",
     "prepublishOnly": "npm run build && npm run lint:pkg",
-    "lint:pkg": "node -e \"const p=require('./package.json'); const req=['name','version','bin']; for(const k of req){if(!p[k])throw new Error('missing '+k)} const mustInclude=['bin/','lib/','server.js']; for(const f of mustInclude){if(!p.files.includes(f))throw new Error('files[] must include '+f)}\"",
+    "lint:pkg": "node -e \"const p=require('./package.json'); const req=['name','version','bin']; for(const k of req){if(!p[k])throw new Error('missing '+k)} const mustInclude=['bin/','lib/','routes/','server.js']; for(const f of mustInclude){if(!p.files.includes(f))throw new Error('files[] must include '+f)}\"",
     "release:patch": "npm version patch && npm publish && git push origin main --tags",
     "release:minor": "npm version minor && npm publish && git push origin main --tags",
     "release:major": "npm version major && npm publish && git push origin main --tags"
@@ -37,9 +37,11 @@
   "files": [
     "bin/",
     "lib/",
+    "routes/",
     "ui/dist/",
     "assets/",
     "server.js",
+    "config.js",
     ".env.example",
     "README.md"
   ],

package/routes/edit.js

@@ -0,0 +1,171 @@
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import { editViaOAuth } from "../lib/oauthProxy.js";
+import { classifyUpstreamError } from "../lib/errorClassify.js";
+import { normalizeOAuthParams } from "../lib/oauthNormalize.js";
+import { getStyleSheet } from "../lib/sessionStore.js";
+import { renderStyleSheetPrefix } from "../lib/styleSheet.js";
+import { startJob, finishJob } from "../lib/inflight.js";
+import { logEvent, logError } from "../lib/logger.js";
+
+function validateModeration(ctx, moderation) {
+  if (typeof moderation !== "string" || !ctx.config.oauth.validModeration.has(moderation)) {
+    return { error: "moderation must be one of: auto, low" };
+  }
+  return { moderation };
+}
+
+export function registerEditRoutes(app, ctx) {
+  app.post("/api/edit", async (req, res) => {
+    const requestId = typeof req.body?.requestId === "string" ? req.body.requestId : null;
+    let finishStatus = "completed";
+    let finishHttpStatus;
+    let finishErrorCode;
+    let finishMeta = {};
+    try {
+      const {
+        prompt,
+        image: imageB64,
+        quality: rawQuality = "medium",
+        size = "1024x1024",
+        moderation = "low",
+        provider = "oauth",
+        mode: promptMode = "auto",
+      } = req.body;
+      const { quality, warnings: qualityWarnings } = normalizeOAuthParams({ provider, quality: rawQuality });
+      const sessionId = typeof req.body?.sessionId === "string" ? req.body.sessionId : null;
+      const normalizedPromptMode = promptMode === "direct" ? "direct" : "auto";
+
+      startJob({
+        requestId,
+        kind: "classic",
+        prompt,
+        meta: {
+          kind: "edit",
+          sessionId,
+          quality,
+          size,
+          styleSheetApplied: false,
+        },
+      });
+
+      if (!prompt || !imageB64) {
+        finishStatus = "error";
+        finishHttpStatus = 400;
+        finishErrorCode = "INVALID_EDIT_INPUT";
+        return res.status(400).json({ error: "Prompt and image are required" });
+      }
+      const moderationCheck = validateModeration(ctx, moderation);
+      if (moderationCheck.error) {
+        finishStatus = "error";
+        finishHttpStatus = 400;
+        finishErrorCode = "INVALID_MODERATION";
+        return res.status(400).json({ error: moderationCheck.error });
+      }
+      if (provider === "api") {
+        finishStatus = "error";
+        finishHttpStatus = 403;
+        finishErrorCode = "APIKEY_DISABLED";
+        return res.status(403).json({ error: "API key provider is disabled. Use OAuth (Codex login).", code: "APIKEY_DISABLED" });
+      }
+
+      let effectivePrompt = prompt;
+      let styleSheetApplied = null;
+      if (sessionId) {
+        try {
+          const data = getStyleSheet(sessionId);
+          if (data && data.enabled && data.styleSheet) {
+            const prefix = renderStyleSheetPrefix(data.styleSheet);
+            if (prefix) {
+              effectivePrompt = `${prefix} ${prompt}`.slice(0, 4000);
+              styleSheetApplied = data.styleSheet;
+            }
+          }
+        } catch {}
+      }
+
+      logEvent("edit", "request", {
+        requestId,
+        client: req.get("x-ima2-client") || "ui",
+        provider: "oauth",
+        quality,
+        size,
+        moderation,
+        sessionId,
+        promptChars: typeof prompt === "string" ? prompt.length : 0,
+        promptMode: normalizedPromptMode,
+        styleSheetApplied: !!styleSheetApplied,
+        inputImageChars: typeof imageB64 === "string" ? imageB64.length : 0,
+      });
+      const startTime = Date.now();
+      const { b64: resultB64, usage, revisedPrompt } = await editViaOAuth(
+        effectivePrompt,
+        imageB64,
+        quality,
+        size,
+        moderation,
+        normalizedPromptMode,
+        ctx,
+        requestId,
+      );
+
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      await mkdir(ctx.config.storage.generatedDir, { recursive: true });
+      const filename = `${Date.now()}_${randomBytes(ctx.config.ids.generatedHexBytes).toString("hex")}.png`;
+      await writeFile(join(ctx.config.storage.generatedDir, filename), Buffer.from(resultB64, "base64"));
+      const meta = {
+        prompt,
+        userPrompt: prompt,
+        revisedPrompt: revisedPrompt || null,
+        promptMode: normalizedPromptMode,
+        effectivePrompt: styleSheetApplied ? effectivePrompt : undefined,
+        styleSheetApplied: styleSheetApplied || undefined,
+        quality,
+        size,
+        moderation,
+        format: "png",
+        provider: "oauth",
+        kind: "edit",
+        createdAt: Date.now(),
+        usage: usage || null,
+        webSearchCalls: 0,
+      };
+      await writeFile(join(ctx.config.storage.generatedDir, filename + ".json"), JSON.stringify(meta)).catch(() => {});
+      finishHttpStatus = 200;
+      finishMeta = { filename, imageChars: resultB64.length };
+      logEvent("edit", "saved", {
+        requestId,
+        filename,
+        imageChars: resultB64.length,
+        elapsedMs: Date.now() - startTime,
+      });
+
+      res.json({
+        image: `data:image/png;base64,${resultB64}`,
+        elapsed,
+        filename,
+        usage,
+        provider: "oauth",
+        moderation,
+        warnings: qualityWarnings,
+        revisedPrompt: revisedPrompt || null,
+        promptMode: normalizedPromptMode,
+      });
+    } catch (err) {
+      const fallbackCode = err.code || classifyUpstreamError(err.message);
+      finishStatus = "error";
+      finishHttpStatus = err.status || 500;
+      finishErrorCode = fallbackCode || "EDIT_FAILED";
+      logError("edit", "error", err, { requestId, code: finishErrorCode });
+      res.status(err.status || 500).json({ error: err.message, code: fallbackCode });
+    } finally {
+      finishJob(requestId, {
+        status: finishStatus,
+        httpStatus: finishHttpStatus,
+        errorCode: finishErrorCode,
+        meta: finishMeta,
+      });
+    }
+  });
+}

package/routes/generate.js

@@ -0,0 +1,254 @@
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import { validateAndNormalizeRefs } from "../lib/refs.js";
+import { classifyUpstreamError } from "../lib/errorClassify.js";
+import { normalizeOAuthParams } from "../lib/oauthNormalize.js";
+import { generateViaOAuth } from "../lib/oauthProxy.js";
+import { startJob, finishJob } from "../lib/inflight.js";
+import { getStyleSheet } from "../lib/sessionStore.js";
+import { renderStyleSheetPrefix } from "../lib/styleSheet.js";
+import { logEvent, logError } from "../lib/logger.js";
+
+function validateModeration(ctx, moderation) {
+  if (typeof moderation !== "string" || !ctx.config.oauth.validModeration.has(moderation)) {
+    return { error: "moderation must be one of: auto, low" };
+  }
+  return { moderation };
+}
+
+export function registerGenerateRoutes(app, ctx) {
+  app.post("/api/generate", async (req, res) => {
+    const requestId = typeof req.body?.requestId === "string" ? req.body.requestId : null;
+    let finishStatus = "completed";
+    let finishHttpStatus;
+    let finishErrorCode;
+    let finishMeta = {};
+    try {
+      const sessionId = typeof req.body?.sessionId === "string" ? req.body.sessionId : null;
+      const clientNodeId = typeof req.body?.clientNodeId === "string" ? req.body.clientNodeId : null;
+      const {
+        prompt,
+        quality: rawQuality = "medium",
+        size = "1024x1024",
+        format = "png",
+        moderation = "low",
+        provider = "auto",
+        n = 1,
+        references = [],
+        mode: promptMode = "auto",
+      } = req.body;
+      const { quality, warnings: qualityWarnings } = normalizeOAuthParams({ provider, quality: rawQuality });
+      const normalizedPromptMode = promptMode === "direct" ? "direct" : "auto";
+
+      if (!prompt) return res.status(400).json({ error: "Prompt is required" });
+      const moderationCheck = validateModeration(ctx, moderation);
+      if (moderationCheck.error) return res.status(400).json({ error: moderationCheck.error });
+      const count = Math.min(Math.max(parseInt(n) || 1, 1), 8);
+
+      let effectivePrompt = prompt;
+      let styleSheetApplied = null;
+      if (sessionId) {
+        try {
+          const data = getStyleSheet(sessionId);
+          if (data && data.enabled && data.styleSheet) {
+            const prefix = renderStyleSheetPrefix(data.styleSheet);
+            if (prefix) {
+              effectivePrompt = `${prefix} ${prompt}`.slice(0, 4000);
+              styleSheetApplied = data.styleSheet;
+            }
+          }
+        } catch {}
+      }
+
+      startJob({
+        requestId,
+        kind: "classic",
+        prompt: effectivePrompt,
+        meta: {
+          kind: "classic",
+          sessionId,
+          parentNodeId: null,
+          clientNodeId,
+          quality,
+          size,
+          n: count,
+          styleSheetApplied: !!styleSheetApplied,
+        },
+      });
+
+      const refCheck = validateAndNormalizeRefs(references);
+      if (refCheck.error) {
+        finishStatus = "error";
+        finishHttpStatus = 400;
+        finishErrorCode = refCheck.code;
+        return res.status(400).json({ error: refCheck.error, code: refCheck.code });
+      }
+
+      if (provider === "api") {
+        finishStatus = "error";
+        finishHttpStatus = 403;
+        finishErrorCode = "APIKEY_DISABLED";
+        return res.status(403).json({ error: "API key provider is disabled. Use OAuth (Codex login).", code: "APIKEY_DISABLED" });
+      }
+      const client = req.get("x-ima2-client") || "ui";
+      logEvent("generate", "request", {
+        requestId,
+        client,
+        provider: "oauth",
+        quality,
+        size,
+        moderation,
+        n: count,
+        refs: refCheck.refs.length,
+        sessionId,
+        clientNodeId,
+        promptChars: typeof prompt === "string" ? prompt.length : 0,
+        promptMode: normalizedPromptMode,
+        styleSheetApplied: !!styleSheetApplied,
+      });
+      const startTime = Date.now();
+
+      const mimeMap = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
+      const mime = mimeMap[format] || "image/png";
+      await mkdir(ctx.config.storage.generatedDir, { recursive: true });
+
+      const generateOne = async () => {
+        const MAX_RETRIES = 1;
+        let lastErr;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+          try {
+            const r = await generateViaOAuth(
+              effectivePrompt,
+              quality,
+              size,
+              moderation,
+              refCheck.refs,
+              requestId,
+              normalizedPromptMode,
+              ctx,
+            );
+            if (r.b64) return r;
+            lastErr = new Error("Empty response (safety refusal)");
+          } catch (e) {
+            lastErr = e;
+          }
+          if (attempt < MAX_RETRIES) {
+            logEvent("generate", "retry", { requestId, attempt: attempt + 1, errorCode: lastErr?.code });
+          }
+        }
+        const err = new Error("Content generation refused after retries");
+        err.code = "SAFETY_REFUSAL";
+        err.status = 422;
+        err.cause = lastErr;
+        throw err;
+      };
+
+      const results = await Promise.allSettled(Array.from({ length: count }, generateOne));
+      const images = [];
+      let totalUsage = null;
+      let totalWebSearchCalls = 0;
+      for (const r of results) {
+        if (r.status === "fulfilled" && r.value.b64) {
+          const rand = randomBytes(ctx.config.ids.generatedHexBytes).toString("hex");
+          const filename = `${Date.now()}_${rand}_${images.length}.${format}`;
+          await writeFile(join(ctx.config.storage.generatedDir, filename), Buffer.from(r.value.b64, "base64"));
+          const meta = {
+            prompt,
+            userPrompt: prompt,
+            revisedPrompt: r.value.revisedPrompt || null,
+            promptMode: normalizedPromptMode,
+            effectivePrompt: styleSheetApplied ? effectivePrompt : undefined,
+            styleSheetApplied: styleSheetApplied || undefined,
+            quality,
+            size,
+            format,
+            moderation,
+            provider: "oauth",
+            createdAt: Date.now(),
+            usage: r.value.usage || null,
+            webSearchCalls: r.value.webSearchCalls || 0,
+          };
+          await writeFile(join(ctx.config.storage.generatedDir, filename + ".json"), JSON.stringify(meta)).catch(() => {});
+          images.push({
+            image: `data:${mime};base64,${r.value.b64}`,
+            filename,
+            revisedPrompt: r.value.revisedPrompt || null,
+          });
+          if (r.value.usage) {
+            if (!totalUsage) totalUsage = { ...r.value.usage };
+            else Object.keys(r.value.usage).forEach((k) => {
+              if (typeof r.value.usage[k] === "number") totalUsage[k] = (totalUsage[k] || 0) + r.value.usage[k];
+            });
+          }
+          if (typeof r.value.webSearchCalls === "number") totalWebSearchCalls += r.value.webSearchCalls;
+        } else if (r.status === "rejected") {
+          logError("generate", "parallel_failed", r.reason, { requestId });
+        }
+      }
+
+      if (images.length === 0) {
+        const firstErr = results.find((r) => r.status === "rejected")?.reason;
+        if (firstErr?.code === "SAFETY_REFUSAL") {
+          finishStatus = "error";
+          finishHttpStatus = 422;
+          finishErrorCode = "SAFETY_REFUSAL";
+          return res.status(422).json({ error: firstErr.message, code: "SAFETY_REFUSAL" });
+        }
+        finishStatus = "error";
+        finishHttpStatus = 500;
+        finishErrorCode = "GENERATE_ALL_FAILED";
+        return res.status(500).json({ error: "All generation attempts failed" });
+      }
+
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      const firstRevised = images[0]?.revisedPrompt || null;
+      const extra = {
+        usage: totalUsage,
+        provider: "oauth",
+        webSearchCalls: totalWebSearchCalls,
+        quality,
+        size,
+        moderation,
+        warnings: qualityWarnings,
+        revisedPrompt: firstRevised,
+        promptMode: normalizedPromptMode,
+      };
+
+      if (count === 1) {
+        finishHttpStatus = 200;
+        finishMeta = { filenames: [images[0].filename], imageCount: 1 };
+        logEvent("generate", "saved", {
+          requestId,
+          imageCount: 1,
+          elapsedMs: Date.now() - startTime,
+          filename: images[0].filename,
+        });
+        res.json({ image: images[0].image, elapsed, filename: images[0].filename, requestId, ...extra });
+      } else {
+        finishHttpStatus = 200;
+        finishMeta = { filenames: images.map((image) => image.filename), imageCount: images.length };
+        logEvent("generate", "saved", {
+          requestId,
+          imageCount: images.length,
+          elapsedMs: Date.now() - startTime,
+        });
+        res.json({ images, elapsed, count: images.length, requestId, ...extra });
+      }
+    } catch (err) {
+      const fallbackCode = err.code || classifyUpstreamError(err.message);
+      finishStatus = "error";
+      finishHttpStatus = err.status || 500;
+      finishErrorCode = fallbackCode || "GENERATE_FAILED";
+      logError("generate", "error", err, { requestId, code: finishErrorCode });
+      res.status(err.status || 500).json({ error: err.message, code: fallbackCode, requestId });
+    } finally {
+      finishJob(requestId, {
+        status: finishStatus,
+        httpStatus: finishHttpStatus,
+        errorCode: finishErrorCode,
+        meta: finishMeta,
+      });
+    }
+  });
+}

package/routes/health.js

@@ -0,0 +1,89 @@
+import { listJobs, listTerminalJobs, finishJob } from "../lib/inflight.js";
+
+export function registerHealthRoutes(app, ctx) {
+  app.get("/api/providers", (_req, res) => {
+    res.json({
+      apiKey: false,
+      oauth: true,
+      oauthPort: ctx.oauthPort,
+      apiKeyDisabled: true,
+    });
+  });
+
+  app.get("/api/health", (_req, res) => {
+    res.json({
+      ok: true,
+      version: ctx.packageVersion,
+      provider: "oauth",
+      uptimeSec: Math.round(process.uptime()),
+      activeJobs: listJobs().length,
+      pid: process.pid,
+      startedAt: ctx.startedAt,
+    });
+  });
+
+  app.get("/api/oauth/status", async (_req, res) => {
+    try {
+      const r = await fetch(`${ctx.oauthUrl}/v1/models`, {
+        signal: AbortSignal.timeout(ctx.config.oauth.statusTimeoutMs),
+      });
+      if (r.ok) {
+        const data = await r.json();
+        res.json({ status: "ready", models: data.data?.map((m) => m.id) || [] });
+      } else {
+        res.json({ status: "auth_required" });
+      }
+    } catch {
+      res.json({ status: "offline" });
+    }
+  });
+
+  app.get("/api/inflight", (req, res) => {
+    const kind =
+      typeof req.query.kind === "string" && req.query.kind.length > 0
+        ? req.query.kind
+        : undefined;
+    const sessionId =
+      typeof req.query.sessionId === "string" && req.query.sessionId.length > 0
+        ? req.query.sessionId
+        : undefined;
+    const includeTerminal =
+      req.query.includeTerminal === "1" || req.query.includeTerminal === "true";
+    const jobs = listJobs({ kind, sessionId });
+    if (!includeTerminal) return res.json({ jobs });
+    return res.json({
+      jobs,
+      terminalJobs: listTerminalJobs({ kind, sessionId }),
+    });
+  });
+
+  app.delete("/api/inflight/:requestId", (req, res) => {
+    finishJob(req.params.requestId, { canceled: true });
+    res.status(204).end();
+  });
+
+  app.get("/api/billing", async (_req, res) => {
+    if (!ctx.hasApiKey) {
+      return res.json({ oauth: true, apiKeyValid: false, apiKeySource: "none" });
+    }
+
+    try {
+      const headers = { Authorization: `Bearer ${ctx.apiKey}`, "Content-Type": "application/json" };
+      const start = Math.floor(new Date(new Date().getFullYear(), new Date().getMonth(), 1).getTime() / 1000);
+      const end = Math.floor(Date.now() / 1000);
+      const [subRes, usageRes, modelsRes] = await Promise.allSettled([
+        fetch(`https://api.openai.com/v1/organization/costs?start_time=${start}&end_time=${end}&bucket_width=1d&limit=31`, { headers }),
+        fetch("https://api.openai.com/dashboard/billing/credit_grants", { headers }),
+        fetch("https://api.openai.com/v1/models", { headers }),
+      ]);
+
+      const billing = { apiKeySource: ctx.apiKeySource ?? "env" };
+      if (subRes.status === "fulfilled" && subRes.value.ok) billing.costs = await subRes.value.json();
+      if (usageRes.status === "fulfilled" && usageRes.value.ok) billing.credits = await usageRes.value.json();
+      billing.apiKeyValid = modelsRes.status === "fulfilled" && modelsRes.value.ok === true;
+      res.json(billing);
+    } catch (err) {
+      res.status(500).json({ error: err.message, apiKeyValid: false });
+    }
+  });
+}