@oar-sh/oar 0.9.23 → 0.9.25

package/shared/model-refresh-schedule.mjs

@@ -0,0 +1,120 @@
+// "Check for new models" (Settings → General → Models): the relay asks each
+// enabled provider for its model list on a timer, skipping a provider whose
+// list was refreshed recently by anything (the Refresh button, a settings
+// save, a login, an install, the boot). Relay-wide app_settings keys:
+//
+//   model_refresh_auto            'true' / 'false'; absent = on
+//   model_refresh_interval_hours  6 / 12 / 24 / 72 / 168; absent = 24
+//   model_refresh_excluded        JSON list of provider ids left out; absent = none
+//   model_refresh_last            JSON { <provider>: { at, ok, error, lastOkAt, lastFailureAt } }
+
+export const MODEL_REFRESH_AUTO_SETTING_KEY = 'model_refresh_auto';
+export const MODEL_REFRESH_INTERVAL_HOURS_SETTING_KEY = 'model_refresh_interval_hours';
+export const MODEL_REFRESH_EXCLUDED_SETTING_KEY = 'model_refresh_excluded';
+export const MODEL_REFRESH_LAST_SETTING_KEY = 'model_refresh_last';
+
+export const DEFAULT_MODEL_REFRESH_AUTO = true;
+export const MODEL_REFRESH_INTERVAL_HOURS_CHOICES = Object.freeze([6, 12, 24, 72, 168]);
+export const DEFAULT_MODEL_REFRESH_INTERVAL_HOURS = 24;
+// A failed check is tried again at most this often, whatever the interval.
+export const MODEL_REFRESH_FAILURE_RETRY_MS = 60 * 60 * 1000;
+// The first look a minute after boot (overdue providers are checked then),
+// then every quarter of an hour.
+export const MODEL_REFRESH_FIRST_TICK_MS = 60 * 1000;
+export const MODEL_REFRESH_TICK_MS = 15 * 60 * 1000;
+
+// The providers in the order Settings and Select Models list them; `github`
+// is Copilot. `tab` is the provider's Select Models tab.
+export const MODEL_REFRESH_PROVIDERS = Object.freeze([
+  Object.freeze({ id: 'github', label: 'Copilot', tab: 'copilot' }),
+  Object.freeze({ id: 'openai', label: 'OpenAI', tab: 'openai' }),
+  Object.freeze({ id: 'claude', label: 'Claude', tab: 'anthropic' }),
+  Object.freeze({ id: 'claude-api', label: 'Claude API', tab: 'claude-api' }),
+  Object.freeze({ id: 'cursor', label: 'Cursor', tab: 'cursor' }),
+  Object.freeze({ id: 'grok', label: 'Grok', tab: 'grok' }),
+  Object.freeze({ id: 'deepseek', label: 'DeepSeek', tab: 'deepseek' }),
+]);
+const PROVIDER_IDS = new Set(MODEL_REFRESH_PROVIDERS.map((provider) => provider.id));
+
+export function modelRefreshProvider(id) {
+  return MODEL_REFRESH_PROVIDERS.find((provider) => provider.id === String(id || '').trim().toLowerCase()) || null;
+}
+
+/** An unset or unreadable setting is on. */
+export function readModelRefreshAutoSetting(storedValue) {
+  const text = String(storedValue ?? '').trim().toLowerCase();
+  if (text === 'false') return false;
+  if (text === 'true') return true;
+  return DEFAULT_MODEL_REFRESH_AUTO;
+}
+
+export function parseModelRefreshAutoUpdate(value) {
+  if (typeof value !== 'boolean') return { ok: false, error: 'auto must be true or false' };
+  return { ok: true, auto: value };
+}
+
+/** One of the choices; an unset or unknown value is the default. */
+export function readModelRefreshIntervalHoursSetting(storedValue) {
+  const hours = Number(String(storedValue ?? '').trim());
+  return MODEL_REFRESH_INTERVAL_HOURS_CHOICES.includes(hours) ? hours : DEFAULT_MODEL_REFRESH_INTERVAL_HOURS;
+}
+
+export function parseModelRefreshIntervalHoursUpdate(value) {
+  const hours = typeof value === 'number' ? value : (typeof value === 'string' && value.trim() ? Number(value.trim()) : NaN);
+  if (!MODEL_REFRESH_INTERVAL_HOURS_CHOICES.includes(hours)) {
+    return { ok: false, error: `intervalHours must be one of ${MODEL_REFRESH_INTERVAL_HOURS_CHOICES.join(', ')}` };
+  }
+  return { ok: true, intervalHours: hours };
+}
+
+function knownProviderIds(values) {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .map((value) => String(value || '').trim().toLowerCase())
+    .filter((value) => PROVIDER_IDS.has(value)))];
+}
+
+/** The providers left out of the check; unknown ids are dropped. */
+export function readModelRefreshExcludedSetting(storedValue) {
+  try {
+    return knownProviderIds(JSON.parse(String(storedValue || '[]')));
+  } catch {
+    return [];
+  }
+}
+
+export function parseModelRefreshExcludedUpdate(value) {
+  if (!Array.isArray(value)) return { ok: false, error: 'excluded must be a list of provider ids' };
+  const unknown = value.map((entry) => String(entry || '').trim().toLowerCase()).filter((entry) => entry && !PROVIDER_IDS.has(entry));
+  if (unknown.length) return { ok: false, error: `Unknown provider: ${unknown[0]}` };
+  return { ok: true, excluded: knownProviderIds(value) };
+}
+
+function isoOrNull(value) {
+  const text = String(value ?? '').trim();
+  return text && Number.isFinite(Date.parse(text)) ? new Date(text).toISOString() : null;
+}
+
+/** The last refresh of each provider; entries that cannot be read are dropped. */
+export function readModelRefreshLastSetting(storedValue) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(storedValue || '{}'));
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+  const out = {};
+  for (const [id, entry] of Object.entries(parsed)) {
+    if (!PROVIDER_IDS.has(id) || !entry || typeof entry !== 'object') continue;
+    const at = isoOrNull(entry.at);
+    if (!at) continue;
+    out[id] = {
+      at,
+      ok: entry.ok === true,
+      error: entry.ok === true ? null : (String(entry.error || '').trim().slice(0, 300) || null),
+      lastOkAt: isoOrNull(entry.lastOkAt),
+      lastFailureAt: isoOrNull(entry.lastFailureAt),
+    };
+  }
+  return out;
+}

package/shared/openai-image-options.mjs

@@ -0,0 +1,299 @@
+// The options of an OpenAI image turn (gpt-image-*, dall-e-*): size, quality,
+// count, output format and background, checked in one place for the
+// relay_tool contract, the relay's routes and the composer.
+//
+// SDK-free and side-effect free: imported by the server, the session workers
+// and the browser.
+
+// The models a new image session gets when the caller names none, in this
+// order, the first the relay's OpenAI list has; else the first gpt-image id
+// listed. A newer model the list offers (2.6 and up) is never picked by
+// itself: a session gets one only when it is named.
+export const OPENAI_IMAGE_DEFAULT_MODELS = Object.freeze([
+  'gpt-image-2.5-flare',
+  'gpt-image-2.5-flare-2026-09-08',
+  'gpt-image-2',
+]);
+export const OPENAI_IMAGE_DEFAULT_MODEL = OPENAI_IMAGE_DEFAULT_MODELS[0];
+// An image session asked for without a model on a relay whose OpenAI list
+// has no gpt-image model at all.
+export const OPENAI_IMAGE_NO_MODEL_CODE = 'OPENAI_IMAGE_NO_MODEL';
+
+// Images one turn may produce (count) and attach (images): one number for both.
+export const OPENAI_IMAGE_PER_TURN_MAX = 4;
+
+// POST /api/message refuses an image path, a file that is no image, a model
+// that makes no images or an option that model does not take with this code
+// (400); nothing is queued then.
+export const IMAGE_INPUT_REFUSED_CODE = 'IMAGE_INPUT_REFUSED';
+
+export const OPENAI_IMAGE_LIMITS = Object.freeze({
+  countMax: OPENAI_IMAGE_PER_TURN_MAX,
+  inputImagesMax: OPENAI_IMAGE_PER_TURN_MAX,
+  // One attached image, read from disk on the target relay.
+  inputImageBytesMax: 20 * 1024 * 1024,
+  // gpt-image sizes: both edges a multiple of sizeStep, the longer at most
+  // edgeMax, the area at most pixelsMax (3840x2160), the long edge at most
+  // aspectMax times the short one.
+  sizeStep: 16,
+  edgeMax: 3840,
+  pixelsMax: 3840 * 2160,
+  aspectMax: 3,
+  // The fewest pixels gpt-image-2 and the 2.5 models take ("The total pixel
+  // count must be between 655,360 and 8,294,400", OpenAI's image-generation
+  // guide, "Size and quality options" and the gpt-image-2 settings, read
+  // 2026-11-08). It goes by family: gpt-image-2 and every later 2.x model
+  // (2.6 included); earlier models keep their sizes.
+  pixelsMin: 655_360,
+});
+
+export const OPENAI_IMAGE_OPTION_KEYS = Object.freeze(['size', 'quality', 'count', 'output_format', 'background']);
+
+export const OPENAI_IMAGE_OUTPUT_FORMATS = Object.freeze(['png', 'webp', 'jpeg']);
+export const OPENAI_IMAGE_BACKGROUNDS = Object.freeze(['auto', 'transparent', 'opaque']);
+export const OPENAI_IMAGE_MIME_BY_FORMAT = Object.freeze({ png: 'image/png', webp: 'image/webp', jpeg: 'image/jpeg' });
+
+// What each model family takes. dall-e keep their fixed size lists; `auto`
+// size or quality on a dall-e model means "not sent" (the API's own default).
+export const OPENAI_IMAGE_FAMILIES = Object.freeze({
+  'gpt-image': Object.freeze({
+    sizes: null,
+    // Every gpt-image model takes these; the 2.5 and 2.6 models take
+    // OPENAI_IMAGE_EXTENDED_QUALITIES too (openAIImageModelQualities).
+    qualities: Object.freeze(['auto', 'low', 'medium', 'high']),
+    countMax: OPENAI_IMAGE_LIMITS.countMax,
+    formats: true,
+  }),
+  'dall-e-3': Object.freeze({
+    sizes: Object.freeze(['1024x1024', '1792x1024', '1024x1792']),
+    qualities: Object.freeze(['auto', 'standard', 'hd']),
+    countMax: 1,
+    formats: false,
+  }),
+  'dall-e-2': Object.freeze({
+    sizes: Object.freeze(['256x256', '512x512', '1024x1024']),
+    qualities: Object.freeze(['auto', 'standard']),
+    countMax: OPENAI_IMAGE_LIMITS.countMax,
+    formats: false,
+  }),
+});
+
+// "gpt-image-2.5-sunburst and gpt-image-2.5-flare add xhigh and max quality
+// settings … Earlier GPT Image models support quality settings up to high",
+// and the calculator's note: "For GPT Image 2.6 and 2.5 Sunburst and Flare,
+// the quality options are low, medium, high, xhigh, and max. For
+// gpt-image-2, the options are low, medium, and high." (OpenAI's
+// image-generation guide, "Size and quality options" and "Calculating
+// costs", read 2026-11-08). A gpt-image id the relay does not know gets the
+// narrower set.
+export const OPENAI_IMAGE_EXTENDED_QUALITIES = Object.freeze(['xhigh', 'max']);
+const EXTENDED_QUALITY_MODEL = /^gpt-image-2\.[56](?:-|$)/;
+// gpt-image-2 and later 2.x ids: the pixel floor applies (pixelsMin).
+const PIXEL_FLOOR_MODEL = /^gpt-image-2(?:$|[.-])/;
+
+const ALL_QUALITIES = Object.freeze([
+  ...new Set([...Object.values(OPENAI_IMAGE_FAMILIES).flatMap((family) => family.qualities), ...OPENAI_IMAGE_EXTENDED_QUALITIES]),
+]);
+
+function bareModelId(model) {
+  return String(model || '').trim().toLowerCase().replace(/^openai\//, '');
+}
+
+export function isOpenAIImageModelId(model = '') {
+  const id = bareModelId(model);
+  return id.startsWith('gpt-image-') || id.startsWith('dall-e-');
+}
+
+// Copilot lists image ids its runtime cannot serve: a Copilot chat on one is
+// refused with this code (creation, model switch, send), pointing to an
+// OpenAI Image chat.
+export const OPENAI_IMAGE_MODEL_NEEDS_OPENAI_CODE = 'IMAGE_MODEL_NEEDS_OPENAI';
+
+export function openAIImageModelNeedsOpenAIText(model = '') {
+  return `"${String(model || '').trim().slice(0, 120)}" makes images: start an OpenAI Image chat (provider openai) for it.`;
+}
+
+/**
+ * The model a new image session gets when the caller names none, from the
+ * ids the relay's OpenAI provider lists: the first of
+ * OPENAI_IMAGE_DEFAULT_MODELS listed, else the first gpt-image id in the
+ * list's order, else '' (the caller refuses with OPENAI_IMAGE_NO_MODEL_CODE).
+ * Returned in the list's own casing.
+ */
+export function pickOpenAIImageDefaultModel(models = []) {
+  const ids = (Array.isArray(models) ? models : []).map((value) => String(value || '').trim()).filter(Boolean);
+  for (const wanted of OPENAI_IMAGE_DEFAULT_MODELS) {
+    const listed = ids.find((id) => bareModelId(id) === wanted);
+    if (listed) return listed;
+  }
+  return ids.find((id) => bareModelId(id).startsWith('gpt-image-')) || '';
+}
+
+export function openAIImageNoModelText(where = 'this relay') {
+  return `The OpenAI model list on ${where} has no gpt-image model, so an image session has none to start on: `
+    + 'name a model the list has, or turn a gpt-image model on in Settings → Providers → OpenAI.';
+}
+
+/**
+ * The qualities `model` takes: its family's, and xhigh and max for the
+ * gpt-image 2.5 and 2.6 models. Without a model, every value any model takes.
+ */
+export function openAIImageModelQualities(model = '') {
+  const family = openAIImageModelFamily(model);
+  if (!family) return [...ALL_QUALITIES];
+  const base = OPENAI_IMAGE_FAMILIES[family].qualities;
+  return family === 'gpt-image' && EXTENDED_QUALITY_MODEL.test(bareModelId(model)) ? [...base, ...OPENAI_IMAGE_EXTENDED_QUALITIES] : [...base];
+}
+
+/** Whether `model`'s sizes have the pixel floor (gpt-image-2 and later 2.x). */
+export function openAIImageModelHasPixelFloor(model = '') {
+  return PIXEL_FLOOR_MODEL.test(bareModelId(model));
+}
+
+/** 'gpt-image', 'dall-e-3', 'dall-e-2', or null for a model that makes no images. */
+export function openAIImageModelFamily(model = '') {
+  const id = bareModelId(model);
+  if (id.startsWith('gpt-image-')) return 'gpt-image';
+  if (id.startsWith('dall-e-3')) return 'dall-e-3';
+  if (id.startsWith('dall-e-')) return 'dall-e-2';
+  return null;
+}
+
+function invalid(error) {
+  return { ok: false, error };
+}
+
+/** `{ width, height }` of a "WxH" text (also "W×H", "W X H"), or null. */
+export function parseOpenAIImageSize(value) {
+  const match = /^\s*(\d{1,5})\s*[x×]\s*(\d{1,5})\s*$/i.exec(String(value ?? ''));
+  if (!match) return null;
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+
+/**
+ * A size as the API takes it ("auto" or "WxH"), or `{ error }`. Without a
+ * family the gpt-image rules apply, or a dall-e list entry passes as well
+ * (the contract does not know the model; the relay checks again with it).
+ * `model` adds the pixel floor of gpt-image-2 and later.
+ */
+export function checkOpenAIImageSize(value, family = null, { model = '' } = {}) {
+  const text = String(value ?? '').trim().toLowerCase();
+  if (text === 'auto') return { size: 'auto' };
+  const parsed = parseOpenAIImageSize(text);
+  if (!parsed) return { error: 'size must be "auto" or WIDTHxHEIGHT in pixels, e.g. 1536x1024' };
+  const size = `${parsed.width}x${parsed.height}`;
+  const fixed = family ? OPENAI_IMAGE_FAMILIES[family]?.sizes : null;
+  if (fixed) {
+    return fixed.includes(size) ? { size } : { error: `size must be one of: ${fixed.join(', ')} for ${family}` };
+  }
+  if (!family && Object.values(OPENAI_IMAGE_FAMILIES).some((entry) => entry.sizes?.includes(size))) return { size };
+  const { sizeStep, edgeMax, pixelsMax, aspectMax } = OPENAI_IMAGE_LIMITS;
+  const { width, height } = parsed;
+  if (width % sizeStep || height % sizeStep) return { error: `size ${size}: both edges must be multiples of ${sizeStep}` };
+  if (Math.max(width, height) > edgeMax) return { error: `size ${size}: the longer edge may be at most ${edgeMax}` };
+  if (width * height > pixelsMax) return { error: `size ${size}: at most ${pixelsMax} pixels (3840x2160)` };
+  if (model && openAIImageModelHasPixelFloor(model) && width * height < OPENAI_IMAGE_LIMITS.pixelsMin) {
+    return { error: `size ${size}: ${bareModelId(model)} takes ${OPENAI_IMAGE_LIMITS.pixelsMin} to ${pixelsMax} pixels, this is ${width * height}` };
+  }
+  if (Math.max(width, height) > aspectMax * Math.min(width, height)) {
+    return { error: `size ${size}: the aspect ratio must lie between 1:${aspectMax} and ${aspectMax}:1` };
+  }
+  return { size };
+}
+
+/**
+ * Checks the image options of one call or one session's defaults. `input` is
+ * an object with any of OPENAI_IMAGE_OPTION_KEYS; empty values (null, '')
+ * are left out. `model` names the image model when it is known (the relay);
+ * without it every family's values pass that one of them takes. Returns
+ * `{ ok:true, values }` (only the keys named, normalised) or `{ ok:false, error }`.
+ * `field` prefixes the messages (the contract's "image").
+ */
+export function validateOpenAIImageOptions(input, { model = '', field = 'image' } = {}) {
+  if (input === undefined || input === null) return { ok: true, values: {} };
+  if (typeof input !== 'object' || Array.isArray(input)) {
+    return invalid(`${field} must be an object with any of: ${OPENAI_IMAGE_OPTION_KEYS.join(', ')}`);
+  }
+  const unknown = Object.keys(input).filter((key) => !OPENAI_IMAGE_OPTION_KEYS.includes(key) && !isEmpty(input[key]));
+  if (unknown.length) {
+    return invalid(`${field} does not take: ${unknown.slice(0, 10).join(', ')}. It takes: ${OPENAI_IMAGE_OPTION_KEYS.join(', ')}`);
+  }
+  const family = model ? openAIImageModelFamily(model) : null;
+  if (model && !family) return invalid(`${field} options go with an OpenAI image model (gpt-image-*, dall-e-*), not ${String(model).slice(0, 80)}`);
+  const rules = family ? OPENAI_IMAGE_FAMILIES[family] : null;
+  const values = {};
+
+  if (!isEmpty(input.size)) {
+    const checked = checkOpenAIImageSize(input.size, family, { model });
+    if (checked.error) return invalid(`${field}.${checked.error}`);
+    values.size = checked.size;
+  }
+  if (!isEmpty(input.quality)) {
+    const quality = String(input.quality).trim().toLowerCase();
+    const allowed = openAIImageModelQualities(model);
+    if (!allowed.includes(quality)) {
+      const extendedNote = family === 'gpt-image' && OPENAI_IMAGE_EXTENDED_QUALITIES.includes(quality)
+        ? ` (${OPENAI_IMAGE_EXTENDED_QUALITIES.join(' and ')}: the gpt-image 2.5 and 2.6 models only)`
+        : '';
+      return invalid(`${field}.quality must be one of: ${allowed.join(', ')}${model ? ` for ${bareModelId(model)}` : ''}${extendedNote}`);
+    }
+    values.quality = quality;
+  }
+  if (!isEmpty(input.count)) {
+    const count = Number(input.count);
+    const max = rules ? rules.countMax : OPENAI_IMAGE_LIMITS.countMax;
+    if (typeof input.count === 'boolean' || !Number.isInteger(count) || count < 1 || count > max) {
+      return invalid(`${field}.count must be a whole number from 1 to ${max}${family ? ` for ${family}` : ''}`);
+    }
+    values.count = count;
+  }
+  for (const [key, allowed] of [['output_format', OPENAI_IMAGE_OUTPUT_FORMATS], ['background', OPENAI_IMAGE_BACKGROUNDS]]) {
+    if (isEmpty(input[key])) continue;
+    const value = String(input[key]).trim().toLowerCase();
+    if (rules && !rules.formats) return invalid(`${field}.${key} goes with gpt-image models only, not ${family}`);
+    if (!allowed.includes(value)) return invalid(`${field}.${key} must be one of: ${allowed.join(', ')}`);
+    values[key] = value;
+  }
+  if (values.background === 'transparent' && values.output_format === 'jpeg') {
+    return invalid(`${field}.background "transparent" needs output_format png or webp`);
+  }
+  return { ok: true, values };
+}
+
+/**
+ * The options of one turn: the session's defaults with the turn's own values
+ * over them, and count 1 when neither names one.
+ */
+export function mergeOpenAIImageOptions(defaults, override) {
+  const merged = {};
+  for (const source of [defaults, override]) {
+    if (!source || typeof source !== 'object') continue;
+    for (const key of OPENAI_IMAGE_OPTION_KEYS) {
+      if (!isEmpty(source[key])) merged[key] = source[key];
+    }
+  }
+  if (!merged.count) merged.count = 1;
+  return merged;
+}
+
+/**
+ * The reply line of an image turn, for agents and the transcript alike when
+ * the model wrote no text: "2 images · 1536x1024 · gpt-image-2 · ~USD 0.08".
+ * `images` are `{ width, height }` entries; the cost part only when known.
+ */
+export function formatOpenAIImageSummary({ images = [], model = '', costUsd = null } = {}) {
+  const list = Array.isArray(images) ? images : [];
+  const parts = [`${list.length} image${list.length === 1 ? '' : 's'}`];
+  const sizes = [...new Set(list.filter((image) => image?.width > 0 && image?.height > 0).map((image) => `${image.width}x${image.height}`))];
+  if (sizes.length) parts.push(sizes.join(', '));
+  const id = String(model || '').trim();
+  if (id) parts.push(id);
+  if (Number.isFinite(costUsd) && costUsd >= 0) parts.push(`~USD ${costUsd < 0.01 && costUsd > 0 ? costUsd.toFixed(3) : costUsd.toFixed(2)}`);
+  return parts.join(' · ');
+}
+
+function isEmpty(value) {
+  return value === undefined || value === null || (typeof value === 'string' && value.trim() === '');
+}

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']);