@oar-sh/oar 0.9.24 → 0.9.26

package/server/services/remote-relay-registry-service.mjs

@@ -226,12 +226,16 @@ export function createRemoteRelayRegistry({
       version: toText(version) || null,
       platform: toText(platform) || null,
       publicUrl: settings.publicUrl || null,
-      remoteRelays: { protocol: REMOTE_RELAY_PROTOCOL, inbound: settings.inboundEnabled },
+      // imageInputs: send and create_session may carry images and image
+      // options here; an older relay would drop them and run the turn without.
+      remoteRelays: { protocol: REMOTE_RELAY_PROTOCOL, inbound: settings.inboundEnabled, imageInputs: true },
     };
   }
 
+  // For this relay's own Settings only, never for other relays: `defaultName`
+  // is the name it goes by while the relay name is empty.
   function selfPayload() {
-    return { ...selfIdentity(), ...getSelfSettings() };
+    return { ...selfIdentity(), ...getSelfSettings(), defaultName: toText(hostname) || 'OAR' };
   }
 
   function emitChange() {
@@ -620,8 +624,12 @@ export function createRemoteRelayRegistry({
     instanceId,
     selfName,
     selfIdentity,
+    selfPayload,
     getSelfSettings,
     setSelfSettings,
+    // The relay name lives outside the registry: its setter calls this so
+    // every open Settings sees the new name.
+    notifySelfChanged: emitChange,
     getAgentSessionsSettings,
     setAgentSessionsSettings,
     list,

package/server/services/session-worker-stop-service.mjs

@@ -25,13 +25,24 @@ function toPidList(rows, extraPid) {
 // read: the caller must not pretend it stopped what it could not see. The
 // registry's pid counts only while that process is alive: a worker that is
 // gone is stopped already (on Windows its stop call alone could fail).
+//
+// On POSIX the list is every process with its command line, so a live worker
+// of the session is on it as long as its argv carries the session id within
+// ps's width (procps-ng cuts `args` at 128 KiB even with -ww), and the
+// registry's pid counts only when it is: a pid that is alive but not listed
+// is no worker of this session. It is
+// the old worker's pid handed to another process (another user's, which no
+// signal reaches, or one of the relay user's own, which the stop would
+// kill), or the worker ended and its parent has not reaped it yet (a zombie
+// answers signal 0 and has no command line left).
 async function enumeratePids({ sdkSessionId, worker, processInspector, platform, isPidAliveImpl }) {
   const rows = platform === 'win32'
     ? await processInspector?.findWindowsProcessTreeForSessionAsync?.(sdkSessionId, { fresh: true })
     : await processInspector?.findProcessesForSessionAsync?.(sdkSessionId, { fresh: true });
   const listed = toPidList(rows || []);
   const workerPid = Number(worker?.pid);
-  const workerAlive = Number.isInteger(workerPid) && workerPid > 0 && (listed.includes(workerPid) || isPidAliveImpl(workerPid));
+  const workerAlive = Number.isInteger(workerPid) && workerPid > 0
+    && (listed.includes(workerPid) || (platform === 'win32' && isPidAliveImpl(workerPid)));
   return workerAlive ? toPidList(rows || [], workerPid) : listed;
 }
 
@@ -98,6 +109,36 @@ export async function stopSessionWorkerProcesses({
 
   const survivors = (list) => list.filter((pid) => isPidAliveImpl(pid));
 
+  // POSIX: a signal no process takes (ESRCH) is ignored; one it is not ours
+  // to send (EPERM: another user's process) is remembered and the others
+  // still get theirs; the re-check below decides about that pid.
+  const refused = new Map();
+  const signal = (pid, name) => {
+    try {
+      killImpl(pid, name);
+    } catch (error) {
+      const code = String(error?.code || '');
+      if (code === 'EPERM') refused.set(pid, error);
+      else if (code !== 'ESRCH') throw error;
+    }
+  };
+
+  // POSIX: a pid that outlived the stop counts only while a fresh list still
+  // shows it as the session's. The list matches command lines, so a match
+  // can be a process that was ending anyway (a shell that carried the
+  // session's arguments, another user's one included), and a process that
+  // ended but is not reaped yet (a zombie) still answers signal 0 with no
+  // command line left. A list that cannot be read changes nothing.
+  const stillListed = async (list) => {
+    if (platform === 'win32' || !list.length) return list;
+    try {
+      const fresh = await enumeratePids({ sdkSessionId: sid, worker, processInspector, platform, isPidAliveImpl });
+      return list.filter((pid) => fresh.includes(pid) && isPidAliveImpl(pid));
+    } catch {
+      return list;
+    }
+  };
+
   const waitFor = async (list, timeoutMs) => {
     const deadline = nowMs() + Math.max(0, Number(timeoutMs) || 0);
     let remaining = survivors(list);
@@ -114,13 +155,7 @@ export async function stopSessionWorkerProcesses({
       // Stop-Process -Force, so there is no gentler first pass to attempt.
       await stopWindowsPids(processInspector, pids);
     } else {
-      for (const pid of pids) {
-        try {
-          killImpl(pid, 'SIGTERM');
-        } catch (error) {
-          if (String(error?.code || '') !== 'ESRCH') throw error;
-        }
-      }
+      for (const pid of pids) signal(pid, 'SIGTERM');
       // The tmux session can outlive its child after SIGTERM.
       killTmuxSessionImpl?.(sid);
     }
@@ -140,13 +175,7 @@ export async function stopSessionWorkerProcesses({
       escalationTargets = [...new Set([...remainingPids, ...rediscovered.filter((pid) => isPidAliveImpl(pid))])];
       await stopWindowsPids(processInspector, escalationTargets);
     } else {
-      for (const pid of escalationTargets) {
-        try {
-          killImpl(pid, 'SIGKILL');
-        } catch (error) {
-          if (String(error?.code || '') !== 'ESRCH') throw error;
-        }
-      }
+      for (const pid of escalationTargets) signal(pid, 'SIGKILL');
     }
   } catch (error) {
     return done({
@@ -158,15 +187,18 @@ export async function stopSessionWorkerProcesses({
     });
   }
 
-  remainingPids = await waitFor(escalationTargets, escalationTimeoutMs);
+  remainingPids = await stillListed(await waitFor(escalationTargets, escalationTimeoutMs));
   if (remainingPids.length) {
+    // A refused signal is the reason only when every survivor refused one;
+    // a survivor that took its signals and lives on is a timeout.
+    const refusal = remainingPids.every((pid) => refused.has(pid)) ? refused.get(remainingPids[0]) : null;
     return done({
       ok: false,
       pids,
       remainingPids,
       escalated: true,
-      timedOut: true,
-      error: `worker-stop-timeout:${remainingPids.join(',')}`,
+      timedOut: !refusal,
+      error: refusal ? (refusal.message || 'Failed to stop the CLI') : `worker-stop-timeout:${remainingPids.join(',')}`,
     });
   }
   return done({ pids, escalated: true });

package/server/services/token-usage-service.mjs

@@ -219,6 +219,8 @@ export function createTokenUsageService({
       listAllDayRows: db.prepare(`SELECT * FROM ${TOKEN_USAGE_DAYS_TABLE}`),
       listTurnRows: db.prepare(`SELECT * FROM ${TURN_TOKEN_USAGE_TABLE} WHERE turn_id = ? ORDER BY at, run_id, model`),
       listConversationRows: db.prepare(`SELECT * FROM ${TURN_TOKEN_USAGE_TABLE} WHERE conversation_id = ? ORDER BY at, turn_id, run_id, model`),
+      listBillingDayRows: db.prepare(`SELECT * FROM ${TURN_TOKEN_USAGE_TABLE} WHERE day = ? AND provider = ? AND billing = ? ORDER BY at, turn_id, run_id, model`),
+      listBillingConversationRows: db.prepare(`SELECT * FROM ${TURN_TOKEN_USAGE_TABLE} WHERE conversation_id = ? AND provider = ? AND billing = ? ORDER BY at, turn_id, run_id, model`),
       deleteConversationRows: db.prepare(`DELETE FROM ${TURN_TOKEN_USAGE_TABLE} WHERE conversation_id = ?`),
     };
   }
@@ -410,6 +412,18 @@ export function createTokenUsageService({
     };
   }
 
+  /**
+   * The turn rows of one provider and billing, of one day or of one chat
+   * (`day` or `conversationId`), for the views that need what the day rows
+   * do not keep (cost_source); null when the tables are not there.
+   */
+  function readTurnRows({ provider, billing = '', day = null, conversationId = null } = {}) {
+    const s = ready();
+    if (!s) return null;
+    if (conversationId) return s.listBillingConversationRows.all(String(conversationId), provider, billing).map(turnRowOut);
+    return s.listBillingDayRows.all(String(day || localDay(now())), provider, billing).map(turnRowOut);
+  }
+
   /** The chat is deleted: its turn rows go, the day rows stay. */
   function forgetConversation(conversationId) {
     const s = ready();
@@ -423,6 +437,7 @@ export function createTokenUsageService({
     readPeriods,
     readTurn,
     readConversation,
+    readTurnRows,
     forgetConversation,
     localDay: (ms = now()) => localDay(ms),
     timeZone: formatDay.resolvedOptions().timeZone,

package/shared/image-header.mjs

@@ -0,0 +1,90 @@
+// The type and pixel size of a PNG, JPEG or WebP image, read from its first
+// bytes alone (no decoding). Anything else, or a header that does not hold
+// together, gives null.
+//
+// SDK-free and side-effect free: imported by the server and the browser.
+
+// Enough for every PNG and WebP header and for the JPEG frame header after
+// usual EXIF/ICC blocks; a JPEG whose frame header lies further in gives null.
+export const IMAGE_HEADER_BYTES = 256 * 1024;
+
+function asBytes(input) {
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  return null;
+}
+
+function u16be(bytes, at) {
+  return (bytes[at] << 8) | bytes[at + 1];
+}
+
+function u32be(bytes, at) {
+  return ((bytes[at] << 24) >>> 0) + (bytes[at + 1] << 16) + (bytes[at + 2] << 8) + bytes[at + 3];
+}
+
+function u24le(bytes, at) {
+  return bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+}
+
+function ascii(bytes, at, length) {
+  let text = '';
+  for (let index = at; index < at + length && index < bytes.length; index += 1) text += String.fromCharCode(bytes[index]);
+  return text;
+}
+
+function sized(mime, width, height) {
+  return width > 0 && height > 0 ? { mime, width, height } : null;
+}
+
+function readPng(bytes) {
+  // Signature, then IHDR as the first chunk: length 13, width, height.
+  if (bytes.length < 24 || ascii(bytes, 12, 4) !== 'IHDR') return null;
+  return sized('image/png', u32be(bytes, 16), u32be(bytes, 20));
+}
+
+function readJpeg(bytes) {
+  let at = 2;
+  while (at + 9 < bytes.length) {
+    if (bytes[at] !== 0xff) return null;
+    const marker = bytes[at + 1];
+    // Fill bytes, and markers without a length.
+    if (marker === 0xff) { at += 1; continue; }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) { at += 2; continue; }
+    if (marker === 0xd9 || marker === 0xda) return null;
+    const length = u16be(bytes, at + 2);
+    if (length < 2) return null;
+    const isFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+    if (isFrame) return sized('image/jpeg', u16be(bytes, at + 7), u16be(bytes, at + 5));
+    at += 2 + length;
+  }
+  return null;
+}
+
+function readWebp(bytes) {
+  if (bytes.length < 30) return null;
+  const chunk = ascii(bytes, 12, 4);
+  if (chunk === 'VP8X') return sized('image/webp', u24le(bytes, 24) + 1, u24le(bytes, 27) + 1);
+  if (chunk === 'VP8 ') {
+    // Key frame start code, then 14-bit width and height.
+    if (bytes[23] !== 0x9d || bytes[24] !== 0x01 || bytes[25] !== 0x2a) return null;
+    return sized('image/webp', (bytes[26] | (bytes[27] << 8)) & 0x3fff, (bytes[28] | (bytes[29] << 8)) & 0x3fff);
+  }
+  if (chunk === 'VP8L') {
+    if (bytes[20] !== 0x2f) return null;
+    const bits = bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24);
+    return sized('image/webp', (bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1);
+  }
+  return null;
+}
+
+/** `{ mime, width, height }` of a PNG, JPEG or WebP image's first bytes, or null. */
+export function readImageHeader(input) {
+  const bytes = asBytes(input);
+  if (!bytes || bytes.length < 12) return null;
+  if (bytes[0] === 0x89 && ascii(bytes, 1, 3) === 'PNG' && bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) {
+    return readPng(bytes);
+  }
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return readJpeg(bytes);
+  if (ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WEBP') return readWebp(bytes);
+  return null;
+}

package/shared/math-instructions.mjs

@@ -0,0 +1,30 @@
+// How agents write formulas in their reply messages, taught once per provider
+// through the same four seams as shared/media-embed-instructions.mjs: Claude
+// (system-prompt append), Copilot (relay tool guidance document), Cursor and
+// Grok (once-per-worker prompt prefix). The web app reads a formula from its
+// delimiters only (server/public/app/markdown-math.mjs); a model that writes
+// TeX in bare parentheses or brackets gets its source shown, so every agent
+// is told the notation that renders.
+
+export const MATH_INSTRUCTION_HEADING = '## Formulas in replies';
+
+export const MATH_INSTRUCTION_TEXT =
+  'To show a formula in a reply, write it in TeX between dollar signs: '
+  + '$E = mc^2$ inside a sentence, and $$ ... $$ on lines of its own for a '
+  + 'displayed formula. The web app renders both with KaTeX; \\( ... \\) and '
+  + '\\[ ... \\] work as well. TeX in bare parentheses or square brackets is '
+  + 'not rendered. A dollar amount such as $5 stays text.';
+
+export function renderMathInstructionBlock() {
+  return `${MATH_INSTRUCTION_HEADING}\n\n${MATH_INSTRUCTION_TEXT}`;
+}
+
+/**
+ * Append the formula block to a guidance document unless it already carries
+ * one (idempotent, like applyMediaEmbedInstructions).
+ */
+export function applyMathInstructions(baseInstructions = '') {
+  const base = String(baseInstructions || '').trimEnd();
+  if (base.includes(MATH_INSTRUCTION_HEADING)) return base;
+  return [base, renderMathInstructionBlock()].filter(Boolean).join('\n\n');
+}

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() === '');
+}