@oar-sh/oar 0.9.24 → 0.9.26

package/shared/openai-image-presets.mjs

@@ -0,0 +1,175 @@
+// Image presets: named bundles of image options (size, quality, count,
+// output format, background). A built-in set, and the owner's own, stored
+// relay-wide in app_settings. A turn's options are layered: the session's
+// defaults, then a preset, then the turn's own fields; the merged result is
+// what the validator checks (validateOpenAIImageOptions with the model).
+//
+// SDK-free and side-effect free: imported by the server and the session
+// workers (the browser keeps a tested copy, as for the options).
+
+import { OPENAI_IMAGE_OPTION_KEYS, validateOpenAIImageOptions } from './openai-image-options.mjs';
+
+export const OPENAI_IMAGE_PRESETS_SETTING_KEY = 'openai_image_presets';
+
+export const OPENAI_IMAGE_PRESET_LIMITS = Object.freeze({
+  // Own presets one relay keeps, a name's characters, and the stored JSON.
+  ownMax: 30,
+  nameChars: 40,
+  storedBytesMax: 8 * 1024,
+});
+
+// The relay refuses a preset name it does not know, or an own preset that
+// breaks the rules (a built-in's name, too many, too long), with this code.
+export const OPENAI_IMAGE_PRESET_REFUSED_CODE = 'OPENAI_IMAGE_PRESET_REFUSED';
+
+export const OPENAI_IMAGE_BUILTIN_PRESETS = Object.freeze([
+  Object.freeze({ name: 'Draft square', size: '1024x1024', quality: 'low' }),
+  Object.freeze({ name: 'Photo landscape', size: '1536x1024', quality: 'medium' }),
+  Object.freeze({ name: 'Portrait', size: '1024x1536', quality: 'medium' }),
+  Object.freeze({ name: 'Wallpaper 4K', size: '3840x2160', quality: 'high' }),
+  Object.freeze({ name: 'Sticker', size: '1024x1024', quality: 'medium', output_format: 'png', background: 'transparent' }),
+]);
+
+// Control characters, and the invisible ones that make two names look alike.
+const HIDDEN_CHARACTERS = /[\u0000-\u001f\u007f-\u009f­؜᠎​-‏‪-‮⁠-⁤⁦-]/u;
+
+/**
+ * A preset name as shown: NFC, trimmed, runs of white space as one space;
+ * or `{ error }` for an empty, too long or hidden-character name.
+ */
+export function cleanOpenAIImagePresetName(value) {
+  if (typeof value !== 'string') return { error: 'a preset name must be text' };
+  const normalized = value.normalize('NFC');
+  if (HIDDEN_CHARACTERS.test(normalized)) return { error: 'a preset name may not hold control or invisible characters' };
+  const name = normalized.trim().replace(/\s+/gu, ' ');
+  if (!name) return { error: 'a preset name may not be empty' };
+  // "." and ".." would be path steps in the preset's URL (DELETE …/:name).
+  if (/^\.+$/.test(name)) return { error: 'a preset name may not be dots alone' };
+  if ([...name].length > OPENAI_IMAGE_PRESET_LIMITS.nameChars) {
+    return { error: `a preset name has at most ${OPENAI_IMAGE_PRESET_LIMITS.nameChars} characters` };
+  }
+  return { name };
+}
+
+/** The one key a name is saved and looked up by: the clean name, lower-cased. */
+export function openAIImagePresetKey(value) {
+  const cleaned = cleanOpenAIImagePresetName(value);
+  return cleaned.error ? '' : cleaned.name.toLowerCase();
+}
+
+function presetValues(preset) {
+  const values = {};
+  for (const key of OPENAI_IMAGE_OPTION_KEYS) {
+    if (preset?.[key] !== undefined && preset?.[key] !== null && preset?.[key] !== '') values[key] = preset[key];
+  }
+  return values;
+}
+
+/**
+ * An own preset as the owner saves it, checked without a model (a preset
+ * serves any image session; its use is checked against the session's
+ * model): `{ ok:true, preset:{ name, ...values } }` or `{ ok:false, error }`.
+ */
+export function validateOwnOpenAIImagePreset(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return { ok: false, error: 'a preset is an object with a name and image options' };
+  const cleaned = cleanOpenAIImagePresetName(input.name);
+  if (cleaned.error) return { ok: false, error: cleaned.error };
+  const key = cleaned.name.toLowerCase();
+  if (OPENAI_IMAGE_BUILTIN_PRESETS.some((preset) => preset.name.toLowerCase() === key)) {
+    return { ok: false, error: `"${cleaned.name}" is a built-in preset; pick another name` };
+  }
+  const { name: _name, ...rest } = input;
+  const checked = validateOpenAIImageOptions(rest, { field: 'preset' });
+  if (!checked.ok) return { ok: false, error: checked.error };
+  if (!Object.keys(checked.values).length) return { ok: false, error: `a preset needs at least one of: ${OPENAI_IMAGE_OPTION_KEYS.join(', ')}` };
+  return { ok: true, preset: { name: cleaned.name, ...checked.values } };
+}
+
+/**
+ * The owner's presets as stored (the app_settings JSON), the ones that still
+ * pass the rules, in their order; anything else is dropped.
+ */
+export function parseOwnOpenAIImagePresets(stored) {
+  let list = stored;
+  if (typeof stored === 'string') {
+    try { list = JSON.parse(stored); } catch { return []; }
+  }
+  if (!Array.isArray(list)) return [];
+  const seen = new Set();
+  const presets = [];
+  for (const entry of list) {
+    const checked = validateOwnOpenAIImagePreset(entry);
+    if (!checked.ok) continue;
+    const key = checked.preset.name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    presets.push(checked.preset);
+    if (presets.length >= OPENAI_IMAGE_PRESET_LIMITS.ownMax) break;
+  }
+  return presets;
+}
+
+/** Built-ins first (`builtIn: true`), then the owner's. */
+export function listOpenAIImagePresets(ownPresets = []) {
+  return [
+    ...OPENAI_IMAGE_BUILTIN_PRESETS.map((preset) => ({ ...preset, builtIn: true })),
+    ...(Array.isArray(ownPresets) ? ownPresets : []).map((preset) => ({ ...preset, builtIn: false })),
+  ];
+}
+
+/**
+ * The preset a turn names, by its key: `{ ok:true, values }` (the options
+ * alone), `{ ok:true, values:{} }` for no name, or `{ ok:false, error }` for
+ * a name the relay does not know, with the names it has.
+ */
+export function findOpenAIImagePreset(name, ownPresets = []) {
+  if (name === undefined || name === null || (typeof name === 'string' && !name.trim())) return { ok: true, values: {} };
+  const key = openAIImagePresetKey(name);
+  const all = listOpenAIImagePresets(ownPresets);
+  const found = key ? all.find((preset) => preset.name.toLowerCase() === key) : null;
+  if (!found) {
+    return { ok: false, error: `no image preset "${String(name).slice(0, 60)}" here; presets: ${all.map((preset) => preset.name).join(', ')}` };
+  }
+  return { ok: true, values: presetValues(found), name: found.name };
+}
+
+/**
+ * Splits a turn's `image` into the preset it names and its own fields (the
+ * validator takes no `preset` key): `{ preset, own }`.
+ */
+export function splitOpenAIImagePreset(image) {
+  if (!image || typeof image !== 'object' || Array.isArray(image)) return { preset: null, own: image };
+  const { preset = null, ...own } = image;
+  return { preset, own };
+}
+
+/**
+ * The stored list after one change, for the server to write in the same
+ * transaction it read in: `{ ok:true, presets }` or `{ ok:false, error }`.
+ * `op` is 'put' (add, or replace one of that name only with `replace`) or
+ * 'delete'.
+ */
+export function applyOwnOpenAIImagePresetChange(ownPresets, { op, preset = null, name = '', replace = false } = {}) {
+  const list = Array.isArray(ownPresets) ? [...ownPresets] : [];
+  if (op === 'delete') {
+    const key = openAIImagePresetKey(name);
+    if (OPENAI_IMAGE_BUILTIN_PRESETS.some((entry) => entry.name.toLowerCase() === key)) return { ok: false, error: 'a built-in preset cannot be deleted' };
+    const index = list.findIndex((entry) => entry.name.toLowerCase() === key);
+    if (index < 0) return { ok: false, error: `no own preset "${String(name).slice(0, 60)}"` };
+    list.splice(index, 1);
+    return { ok: true, presets: list };
+  }
+  if (op !== 'put') return { ok: false, error: 'op must be put or delete' };
+  const checked = validateOwnOpenAIImagePreset(preset);
+  if (!checked.ok) return checked;
+  const key = checked.preset.name.toLowerCase();
+  const index = list.findIndex((entry) => entry.name.toLowerCase() === key);
+  if (index >= 0 && !replace) return { ok: false, error: `a preset "${list[index].name}" exists; save with replace to change it` };
+  if (index >= 0) list[index] = checked.preset;
+  else if (list.length >= OPENAI_IMAGE_PRESET_LIMITS.ownMax) return { ok: false, error: `at most ${OPENAI_IMAGE_PRESET_LIMITS.ownMax} own presets` };
+  else list.push(checked.preset);
+  if (new TextEncoder().encode(JSON.stringify(list)).length > OPENAI_IMAGE_PRESET_LIMITS.storedBytesMax) {
+    return { ok: false, error: `the presets would take more than ${OPENAI_IMAGE_PRESET_LIMITS.storedBytesMax} bytes` };
+  }
+  return { ok: true, presets: list };
+}

package/shared/openai-image-previews.mjs

@@ -0,0 +1,40 @@
+// Partial previews of an OpenAI image turn: what the relay asks OpenAI to
+// stream, where the partial files live and the socket events the owner's
+// open clients get while the image is made. Agents never see previews: their
+// replies carry the final images only.
+//
+// SDK-free and side-effect free: imported by the server and the browser.
+
+// Partial images per image OpenAI streams before the final one (0 to 3; 0
+// turns streaming off).
+export const OPENAI_IMAGE_PARTIAL_IMAGES = 2;
+
+// The folder next to a turn's final images that holds its partials; emptied
+// and removed when the turn ends, well or not.
+export const OPENAI_IMAGE_PARTIALS_DIR = 'partials';
+
+// Socket events (owner clients only, never shared views):
+//
+// `image_started` — a try of an image turn went to OpenAI:
+//   { conversationId, messageId, attempt, size, quality, count, model, startedAt }
+//   The client shows a placeholder with an elapsed timer from `startedAt`
+//   and the size and quality; a client that opens the chat later sees the
+//   running turn without it (its timer starts from the turn's own time).
+//
+// `image_preview` — a partial image arrived:
+//   { conversationId, messageId, attempt, imageIndex, partialIndex,
+//     contentUrl, mime, size, quality, model, startedAt }
+//   `messageId` is the user message (queue row) the turn answers; `attempt`
+//   counts the tries of that turn (1, then 2 after a retry); `imageIndex`
+//   the image of a count > 1 turn (0-based); `partialIndex` OpenAI's
+//   partial_image_index; `startedAt` the ISO time the first try began, for
+//   the elapsed timer.
+//
+// `image_preview_reset` — drop the previews shown so far for that turn:
+//   { conversationId, messageId, attempt, reason }
+//   `reason` is 'retry' (a second try starts: the first try's partials go),
+//   'done' (the final message is there) or 'failed'.
+export const OPENAI_IMAGE_STARTED_EVENT = 'image_started';
+export const OPENAI_IMAGE_PREVIEW_EVENT = 'image_preview';
+export const OPENAI_IMAGE_PREVIEW_RESET_EVENT = 'image_preview_reset';
+export const OPENAI_IMAGE_PREVIEW_RESET_REASONS = Object.freeze(['retry', 'done', 'failed']);

package/shared/openai-image-prices.mjs

@@ -0,0 +1,291 @@
+// What an OpenAI image request costs: the price of the usage OpenAI reported,
+// and an estimate before (or instead of) one, for the daily cap
+// (shared/openai-image-spend.mjs) and the reply line.
+//
+// - A model is looked up by its bare lower-case id, then with a dated
+//   snapshot suffix (-YYYY-MM-DD) stripped. There is no family fallback.
+// - A model the table lacks gets the stand-in: never a missing cost (a cost
+//   the cap cannot add up is no cost to it), always `costUnknown: true`.
+// - `auto` quality is the model's dearest quality. `auto` size (and a size
+//   that cannot be read) counts as 1536x1024: OpenAI says what `auto` costs
+//   depends on the image it makes, and the landscape size is the one the
+//   relay's composer offers first.
+// - Partial images are added to estimates only (100 image output tokens
+//   each); a reported usage is priced as it is.
+//
+// SDK-free and side-effect free.
+
+import { OPENAI_IMAGE_COST_SOURCES } from './openai-image-spend.mjs';
+
+// The per-image cost of a size OpenAI chooses (`auto`), or of a size the
+// estimate cannot read.
+export const OPENAI_IMAGE_AUTO_SIZE = '1536x1024';
+// "each partial image will incur an additional 100 image output tokens"
+// (developers.openai.com/api/docs/guides/image-generation, "Partial images
+// cost", l.3673; read 2026-11-08).
+export const OPENAI_IMAGE_PARTIAL_OUTPUT_TOKENS = 100;
+// The input an estimate allows for, besides the images: the prompt as text
+// tokens, and each input image (edits) as image input tokens. Assumptions,
+// not published figures: OpenAI gives no input token counts for these
+// models; the guide says only that gpt-image-2 reads input images at high
+// fidelity, so edits "can use more input tokens" (l.3764-3765, 3788).
+export const OPENAI_IMAGE_ESTIMATE_PROMPT_TOKENS = 500;
+export const OPENAI_IMAGE_ESTIMATE_INPUT_IMAGE_TOKENS = 4000;
+
+const PER_MILLION = 1_000_000;
+
+// ---------------------------------------------------------------------------
+// TABLE. Each entry names its source and the day it was read. Rates are USD
+// per 1M tokens: text input, image input, image output. Standard rates only:
+// cached input rates apply to the Responses API's image tool alone, "not ...
+// direct Images API requests, including /v1/images/edits" (guide l.3644), and
+// cached counts are not in `usage` (l.3646).
+//
+// `outputTokens`: the guide's token calculator for the 2.x models, computed
+// for any size: base = per quality; d = base / (long edge / short edge),
+// rounded half to even; tokens = ceil(base * d * (2e6 + w * h) / 4e6); for
+// 2.6 that times a per-quality factor, rounded. The calculator "Excludes text
+// and image input tokens and streaming partial images." Source:
+// https://developers.openai.com/_astro/GptImageTokenCalculator.react.eSCKNoob.js
+// (read 2026-11-08); its gpt-image-2 figures match the guide's published
+// per-image table (l.3840-3854).
+//
+// `perImageUsd`: the published per-image prices of the older models, for
+// their three sizes (guide "Earlier GPT Image models", l.3858-3921, and the
+// model pages; read 2026-11-08).
+//
+// dall-e-3 and dall-e-2 have no entry: OpenAI lists no price for them (both
+// were shut down 2026-05-12, developers.openai.com/api/docs/deprecations);
+// they get the stand-in.
+// ---------------------------------------------------------------------------
+
+const GPT_IMAGE_2X_BASE = Object.freeze({ low: 16, medium: 24, high: 48, xhigh: 64, max: 96 });
+
+// Rates: developers.openai.com/api/docs/pricing (#image-generation) and the
+// model pages, read 2026-11-08. Output tokens: the calculator (above).
+const GPT_IMAGE_2_6 = Object.freeze({
+  rates: Object.freeze({ textInput: 5, imageInput: 8, imageOutput: 30 }),
+  outputTokens: Object.freeze({
+    base: GPT_IMAGE_2X_BASE,
+    factor: Object.freeze({ low: 4.2, medium: 3.3, high: 1, xhigh: 1, max: 1 }),
+  }),
+  qualities: Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']),
+});
+
+// Rates: the pricing page and the guide (l.3638: "Both GPT Image 2.5 models
+// use the same token rates"), read 2026-11-08. Output tokens: the calculator.
+const GPT_IMAGE_2_5 = Object.freeze({
+  rates: Object.freeze({ textInput: 5, imageInput: 8, imageOutput: 30 }),
+  outputTokens: Object.freeze({ base: GPT_IMAGE_2X_BASE }),
+  qualities: Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']),
+});
+
+const OPENAI_IMAGE_PRICE_TABLE = Object.freeze({
+  'gpt-image-2.6-sunburst': GPT_IMAGE_2_6,
+  'gpt-image-2.6-flare': GPT_IMAGE_2_6,
+  'gpt-image-2.5-sunburst': GPT_IMAGE_2_5,
+  'gpt-image-2.5-flare': GPT_IMAGE_2_5,
+  // Rates: the pricing page and the model page, read 2026-11-08. Output
+  // tokens: the calculator (= the guide's table, l.3840-3854).
+  'gpt-image-2': Object.freeze({
+    rates: Object.freeze({ textInput: 5, imageInput: 8, imageOutput: 30 }),
+    outputTokens: Object.freeze({ base: Object.freeze({ low: 16, medium: 48, high: 96 }) }),
+    qualities: Object.freeze(['low', 'medium', 'high']),
+  }),
+  // Rates: the pricing page and the model page (deprecated, off
+  // 2026-12-01), read 2026-11-08. Per image: guide l.3858-3921.
+  'gpt-image-1.5': Object.freeze({
+    rates: Object.freeze({ textInput: 5, imageInput: 8, imageOutput: 32 }),
+    perImageUsd: Object.freeze({
+      low: Object.freeze({ '1024x1024': 0.009, '1024x1536': 0.013, '1536x1024': 0.013 }),
+      medium: Object.freeze({ '1024x1024': 0.034, '1024x1536': 0.05, '1536x1024': 0.05 }),
+      high: Object.freeze({ '1024x1024': 0.133, '1024x1536': 0.2, '1536x1024': 0.2 }),
+    }),
+    qualities: Object.freeze(['low', 'medium', 'high']),
+  }),
+  // Rates: the pricing page and the model page (deprecated, off
+  // 2026-12-01), read 2026-11-08. Per image: guide l.3858-3921.
+  'gpt-image-1-mini': Object.freeze({
+    rates: Object.freeze({ textInput: 2, imageInput: 2.5, imageOutput: 8 }),
+    perImageUsd: Object.freeze({
+      low: Object.freeze({ '1024x1024': 0.005, '1024x1536': 0.006, '1536x1024': 0.006 }),
+      medium: Object.freeze({ '1024x1024': 0.011, '1024x1536': 0.015, '1536x1024': 0.015 }),
+      high: Object.freeze({ '1024x1024': 0.036, '1024x1536': 0.052, '1536x1024': 0.052 }),
+    }),
+    qualities: Object.freeze(['low', 'medium', 'high']),
+  }),
+  // Rates: the model page (shut down 2026-10-23), read 2026-11-08. Per
+  // image: guide l.3858-3921.
+  'gpt-image-1': Object.freeze({
+    rates: Object.freeze({ textInput: 5, imageInput: 10, imageOutput: 40 }),
+    perImageUsd: Object.freeze({
+      low: Object.freeze({ '1024x1024': 0.011, '1024x1536': 0.016, '1536x1024': 0.016 }),
+      medium: Object.freeze({ '1024x1024': 0.042, '1024x1536': 0.063, '1536x1024': 0.063 }),
+      high: Object.freeze({ '1024x1024': 0.167, '1024x1536': 0.25, '1536x1024': 0.25 }),
+    }),
+    qualities: Object.freeze(['low', 'medium', 'high']),
+  }),
+});
+// END OF TABLE
+// ---------------------------------------------------------------------------
+
+// The per-image stand-in for a model the table lacks: the dearest of every
+// model the table prices, at the quality and size asked for (a model's
+// dearest quality where it lacks the one asked for), so an unknown model is
+// never estimated below a known one.
+const STAND_IN_PER_IMAGE_MODELS = Object.freeze(Object.keys(OPENAI_IMAGE_PRICE_TABLE));
+
+// The token rates of the stand-in: the dearest rate of each kind the table
+// has, so a usage of an unknown model is never priced low.
+const STAND_IN_RATES = Object.freeze(Object.fromEntries(
+  ['textInput', 'imageInput', 'imageOutput'].map((key) => [
+    key,
+    Math.max(...Object.values(OPENAI_IMAGE_PRICE_TABLE).map((entry) => entry.rates[key])),
+  ]),
+));
+
+/** The models the table prices, for tests and the settings view. */
+export const OPENAI_IMAGE_PRICED_MODELS = Object.freeze(Object.keys(OPENAI_IMAGE_PRICE_TABLE));
+
+/** The id an image turn books under: bare (no `openai/`), lower-case. */
+export function openAIImageBookingModel(model) {
+  return String(model || '').trim().toLowerCase().replace(/^openai\//, '');
+}
+
+/** The table entry of a model: its exact id, else the id without a dated snapshot suffix; or null. */
+export function findOpenAIImagePriceEntry(model) {
+  const id = openAIImageBookingModel(model);
+  if (!id) return null;
+  if (Object.hasOwn(OPENAI_IMAGE_PRICE_TABLE, id)) return OPENAI_IMAGE_PRICE_TABLE[id];
+  const bare = id.replace(/-\d{4}-\d{2}-\d{2}$/, '');
+  return bare !== id && Object.hasOwn(OPENAI_IMAGE_PRICE_TABLE, bare) ? OPENAI_IMAGE_PRICE_TABLE[bare] : null;
+}
+
+function roundUsd(value) {
+  return Math.round(value * 1e9) / 1e9;
+}
+
+function sizeOf(size) {
+  const match = /^\s*(\d{1,5})\s*[x×]\s*(\d{1,5})\s*$/i.exec(String(size ?? ''));
+  const text = match ? `${Number(match[1])}x${Number(match[2])}` : OPENAI_IMAGE_AUTO_SIZE;
+  const [width, height] = text.split('x').map(Number);
+  return width > 0 && height > 0 ? { width, height, text } : { width: 1536, height: 1024, text: OPENAI_IMAGE_AUTO_SIZE };
+}
+
+// The quality an entry is priced at: the one asked for when it has it, else
+// (`auto`, empty, or one it does not know) its dearest.
+function qualityFor(entry, quality) {
+  const wanted = String(quality || '').trim().toLowerCase();
+  return entry.qualities.includes(wanted) ? wanted : entry.qualities[entry.qualities.length - 1];
+}
+
+function roundHalfEven(value) {
+  const floor = Math.floor(value);
+  return value - floor === 0.5 ? floor + (floor % 2) : Math.round(value);
+}
+
+/** Image output tokens of one image by the guide calculator's formula. */
+export function openAIImageOutputTokens({ model, size, quality }) {
+  const entry = findOpenAIImagePriceEntry(model);
+  if (!entry?.outputTokens) return null;
+  const { width, height } = sizeOf(size);
+  const priced = qualityFor(entry, quality);
+  const base = entry.outputTokens.base[priced];
+  const d = roundHalfEven(base / (Math.max(width, height) / Math.min(width, height)));
+  const tokens = Math.ceil((base * d * (2e6 + width * height)) / 4e6);
+  const factor = entry.outputTokens.factor?.[priced];
+  return factor ? Math.round(tokens * factor) : tokens;
+}
+
+// One image's price for a table entry: its output tokens at the output
+// rate, or the published price of the listed size the image is closest to
+// in shape, scaled by area.
+function entryPerImageUsd(entry, model, size, quality) {
+  if (entry.outputTokens) {
+    return (openAIImageOutputTokens({ model, size, quality }) * entry.rates.imageOutput) / PER_MILLION;
+  }
+  const prices = entry.perImageUsd[qualityFor(entry, quality)];
+  const { width, height, text } = sizeOf(size);
+  if (Object.hasOwn(prices, text)) return prices[text];
+  const listed = width > height * 1.25 ? '1536x1024' : (height > width * 1.25 ? '1024x1536' : '1024x1024');
+  const [listedWidth, listedHeight] = listed.split('x').map(Number);
+  return prices[listed] * ((width * height) / (listedWidth * listedHeight));
+}
+
+function standInPerImageUsd(size, quality) {
+  return Math.max(...STAND_IN_PER_IMAGE_MODELS.map((id) => (
+    entryPerImageUsd(OPENAI_IMAGE_PRICE_TABLE[id], id, size, quality)
+  )));
+}
+
+function rateOf(entry, key) {
+  return (entry ? entry.rates : STAND_IN_RATES)[key];
+}
+
+function countOf(value) {
+  const count = Math.trunc(Number(value));
+  return Number.isFinite(count) && count > 0 ? count : 1;
+}
+
+function tokensOf(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+/**
+ * One image's estimated price, times `count`: what the images of a request
+ * cost at least, without input or partials. `{ costUsd, costUnknown }`;
+ * `costUnknown` for the stand-in.
+ */
+export function openAIImageCostFloor({ model, size, quality, count = 1 } = {}) {
+  const entry = findOpenAIImagePriceEntry(model);
+  const perImage = entry ? entryPerImageUsd(entry, model, size, quality) : standInPerImageUsd(size, quality);
+  return { costUsd: roundUsd(perImage * countOf(count)), costUnknown: !entry };
+}
+
+/**
+ * What a request may cost before OpenAI has said: the floor, plus the
+ * partial images received (100 image output tokens each), plus an allowance
+ * for the prompt and each input image. `{ costUsd, costUnknown }`, never a
+ * missing cost.
+ */
+export function estimateOpenAIImageCost({ model, size, quality, count = 1, partials = 0, inputImages = 0 } = {}) {
+  const entry = findOpenAIImagePriceEntry(model);
+  const floor = openAIImageCostFloor({ model, size, quality, count });
+  const partialUsd = (tokensOf(partials) * OPENAI_IMAGE_PARTIAL_OUTPUT_TOKENS * rateOf(entry, 'imageOutput')) / PER_MILLION;
+  const inputUsd = (OPENAI_IMAGE_ESTIMATE_PROMPT_TOKENS * rateOf(entry, 'textInput')
+    + tokensOf(inputImages) * OPENAI_IMAGE_ESTIMATE_INPUT_IMAGE_TOKENS * rateOf(entry, 'imageInput')) / PER_MILLION;
+  return { costUsd: roundUsd(floor.costUsd + partialUsd + inputUsd), costUnknown: floor.costUnknown };
+}
+
+/**
+ * The price of a usage OpenAI reported (`input_tokens`, `output_tokens`,
+ * `input_tokens_details: { text_tokens, image_tokens }`):
+ * `{ costUsd, costUnknown, source, inputTokens, outputTokens }`, `source`
+ * being the cost_source to book. Input without the text/image split is
+ * priced at the image input rate (the dearer). A model the table lacks is
+ * priced at the dearest rates the table has, `costUnknown`. Null when the
+ * usage holds no token count.
+ */
+export function priceOpenAIImageUsage({ model, usage } = {}) {
+  if (!usage || typeof usage !== 'object') return null;
+  const hasInput = Number.isFinite(Number(usage.input_tokens)) && usage.input_tokens !== null;
+  const hasOutput = Number.isFinite(Number(usage.output_tokens)) && usage.output_tokens !== null;
+  if (!hasInput && !hasOutput) return null;
+  const entry = findOpenAIImagePriceEntry(model);
+  const input = tokensOf(usage.input_tokens);
+  const output = tokensOf(usage.output_tokens);
+  const details = usage.input_tokens_details && typeof usage.input_tokens_details === 'object' ? usage.input_tokens_details : null;
+  const textTokens = details ? Math.min(input, tokensOf(details.text_tokens)) : 0;
+  const imageTokens = input - textTokens;
+  const costUsd = (textTokens * rateOf(entry, 'textInput')
+    + imageTokens * rateOf(entry, 'imageInput')
+    + output * rateOf(entry, 'imageOutput')) / PER_MILLION;
+  return {
+    costUsd: roundUsd(costUsd),
+    costUnknown: !entry,
+    source: entry ? OPENAI_IMAGE_COST_SOURCES.table : OPENAI_IMAGE_COST_SOURCES.estimate,
+    inputTokens: hasInput ? input : null,
+    outputTokens: hasOutput ? output : null,
+  };
+}

package/shared/openai-image-spend.mjs

@@ -0,0 +1,90 @@
+// What OpenAI image turns cost a relay, and its daily cap: the setting keys,
+// the codes, the routes and the shape of the spend state the server, the
+// dispatcher and the web client share.
+//
+// "Today" is the relay's local day, the one turn_token_usage.day and
+// token_usage_days use. Image turns book there as provider 'openai',
+// billing 'image', one row per try (run_id image:<attempt or claim>:try<n>,
+// or …:recovered), priced from shared/openai-image-prices.mjs. Estimates and
+// the stand-in price of an unknown model count toward the cap, on purpose:
+// a cap that misses what may have been billed is no cap.
+//
+// SDK-free and side-effect free.
+
+export const OPENAI_IMAGE_BOOKING_PROVIDER = 'openai';
+export const OPENAI_IMAGE_BOOKING_BILLING = 'image';
+
+// cost_source of a booked row: priced from the usage OpenAI reported, or an
+// estimate (a try that may have been billed without a usage, a model the
+// table lacks: then cost_unknown is 1 too).
+export const OPENAI_IMAGE_COST_SOURCES = Object.freeze({
+  table: 'oar-openai-image-table',
+  estimate: 'oar-openai-image-estimate',
+});
+
+// app_settings keys (JSON values).
+export const OPENAI_IMAGE_SPEND_SETTING_KEYS = Object.freeze({
+  // USD. 0 means no cap; missing or unreadable means USD 5.
+  dailyCapUsd: 'openai_image_daily_cap_usd',
+  // The relay-local day ("YYYY-MM-DD") the owner allowed image turns past
+  // the cap, and when; it ends by itself when the day does.
+  overrideDay: 'openai_image_cap_override_day',
+  overrideAt: 'openai_image_cap_override_at',
+});
+
+export const OPENAI_IMAGE_DAILY_CAP_DEFAULT_USD = 5;
+// The share of the cap from which replies and image chats show a warning.
+export const OPENAI_IMAGE_CAP_WARN_RATIO = 0.8;
+
+// A try the cap stops before it is sent, and a send POST /api/message
+// refuses (409), when the cap is reached and today is not allowed.
+export const OPENAI_IMAGE_DAILY_CAP_REACHED_CODE = 'OPENAI_IMAGE_DAILY_CAP_REACHED';
+
+// GET: the spend state below. Owner token; a paired relay may read it (its
+// dispatcher checks before create_session) but never write the cap. With
+// `?conversationId=<id>` the state carries `conversation`: that chat's
+// { costUsd, estimatedUsd, images, tries }.
+export const OPENAI_IMAGE_USAGE_PATH = '/api/image-usage';
+
+// Socket event (owner clients) with the spend state after every booking and
+// every change of the cap or the override.
+export const OPENAI_IMAGE_USAGE_EVENT = 'image_usage_updated';
+
+// POST /api/settings/openai takes, besides its other fields:
+//   imageDailyCapUsd: number ≥ 0 (0 = no cap)
+//   allowImagesToday: true (sets the override for today) | false (clears it)
+// Refused with 403 for a paired relay's request.
+export const OPENAI_IMAGE_SETTINGS_FIELDS = Object.freeze({
+  dailyCapUsd: 'imageDailyCapUsd',
+  allowToday: 'allowImagesToday',
+});
+
+// The presets routes (owner token, never a paired relay's write):
+//   GET    /api/openai-image-presets           → { presets: [{ name, …values, builtIn }] }
+//   PUT    /api/openai-image-presets           body { preset: { name, …values }, replace? } → { presets }
+//   DELETE /api/openai-image-presets/:name     → { presets }
+export const OPENAI_IMAGE_PRESETS_PATH = '/api/openai-image-presets';
+
+/**
+ * The spend state (GET OPENAI_IMAGE_USAGE_PATH, the `usage` action's meter,
+ * the Check Usage card, the banner):
+ * {
+ *   day: 'YYYY-MM-DD',          // relay local
+ *   capUsd: number | null,      // null: no cap
+ *   spentUsd: number,           // booked today, estimates included
+ *   reservedUsd: number,        // tries in flight today
+ *   estimatedUsd: number,       // the part of spentUsd that is estimates
+ *   unknownPriceUsd: number,    // the part booked at the stand-in price
+ *   monthUsd: number,           // this relay-local month, booked
+ *   ratio: number | null,       // (spent + reserved) / cap
+ *   warning: boolean,           // ratio ≥ OPENAI_IMAGE_CAP_WARN_RATIO
+ *   reached: boolean,           // spent + reserved ≥ cap
+ *   allowedToday: boolean,      // the owner's override for this day
+ *   allowedAt: string | null,
+ * }
+ */
+export function formatOpenAIImageUsd(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return 'USD ?';
+  return `USD ${number > 0 && number < 0.01 ? number.toFixed(3) : number.toFixed(2)}`;
+}