@oar-sh/oar 0.9.24 → 0.9.26

package/shared/remote-relay-contract.mjs

@@ -35,6 +35,18 @@ import {
   REMOTE_RELAY_APPROVAL_SOURCE,
   normalizeRelayAskInput,
 } from './relay-asks.mjs';
+import {
+  OPENAI_IMAGE_BACKGROUNDS,
+  OPENAI_IMAGE_LIMITS,
+  OPENAI_IMAGE_OUTPUT_FORMATS,
+  validateOpenAIImageOptions,
+} from './openai-image-options.mjs';
+import {
+  OPENAI_IMAGE_BUILTIN_PRESETS,
+  OPENAI_IMAGE_PRESET_LIMITS,
+  cleanOpenAIImagePresetName,
+  splitOpenAIImagePreset,
+} from './openai-image-presets.mjs';
 
 // The one name every provider lists the tool under. Up to 0.9.17 it was
 // `remote_relay`; that name is still accepted where a runtime dispatches a
@@ -156,6 +168,8 @@ export const REMOTE_RELAY_SESSION_SETTINGS = Object.freeze([
   // Plan-only: agents may set and clear it; set, a send or an
   // update_session naming another mode is refused.
   'planOnly',
+  // An image session's defaults (size, quality, count, format, background).
+  'image',
 ]);
 export const REMOTE_RELAY_THINKING_DISPLAYS = THINKING_DISPLAY_MODES;
 // update_session's `group` value that takes a session out of its group (JSON
@@ -237,6 +251,10 @@ export const REMOTE_RELAY_LIMITS = Object.freeze({
   healthIntervalMs: 60_000,
   requestTimeoutMs: 15_000,
   responseMaxBytes: 5 * 1024 * 1024,
+  // send / create_session to an image session: paths of images on the target
+  // relay that go to the model with the prompt.
+  imagesMax: OPENAI_IMAGE_LIMITS.inputImagesMax,
+  imagePathMaxChars: 4096,
 });
 
 export const REMOTE_RELAY_ERROR_CODES = Object.freeze({
@@ -313,6 +331,8 @@ export const AGENT_SESSIONS_SOCKET_EVENT = 'agent_sessions_settings_updated';
 export const REMOTE_RELAY_LOCAL_ALIAS = 'this';
 export const REMOTE_RELAY_LOCAL_ID = 'self';
 export const REMOTE_RELAY_CLOUD_PROVIDER = 'claude-cloud';
+// The provider of image sessions (gpt-image-*, dall-e-*): images and image go there.
+export const REMOTE_RELAY_IMAGE_PROVIDER = 'openai';
 
 export const REMOTE_RELAY_TOOL_DESCRIPTION =
   'Work with sessions on OAR relays: the other relays this relay is paired with ("remote relays") '
@@ -360,8 +380,14 @@ export const REMOTE_RELAY_TOOL_DESCRIPTION =
   + 'answer: ask the user (unless they told you to decide yourself) and pass the answer '
   + 'with answer_question. Write actions can first need the user\'s approval. Always '
   + 'tell the user which relay and session you worked on. '
+  + 'Image sessions (provider "openai" with a gpt-image or dall-e model): send and create_session take images (absolute paths '
+  + 'on the target relay to edit or work from) and image {size, quality, count, output_format, background, preset} for that turn '
+  + '(preset: a name relay_info lists in imagePresets; the fields named win over it); '
+  + 'update_session image sets the session\'s defaults. Their replies list images [{path, width, height, mime}] (absolute paths '
+  + 'on that relay, which a later send can attach) with a line on size and model; a failed image call is not repeated more than once. '
   + 'usage reports what the provider plans of a relay have left (Copilot, Claude, Claude Cloud, Cursor, Grok: '
-  + 'meters with used, allowance, remaining, utilization and reset time; providers not set up or not tracked say so) '
+  + 'meters with used, allowance, remaining, utilization and reset time; providers not set up or not tracked say so; '
+  + 'OpenAI images: today\'s spend against the relay\'s daily cap) '
   + 'and whether a Claude usage limit has paused turns there, before you start work that costs. '
   + 'read_task_output {session, task_id} reads the end of a background shell or Monitor task\'s output there '
   + '(task ids from read_session\'s tasks; also for an hour after the task ended): the last lines, minutes '
@@ -436,7 +462,7 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
         + 'workspaces of a relay. usage: what each provider\'s plan has left there and any usage-limit pause. list_sessions / read_session: discover and read sessions. '
         + 'read_task_output: the end of a background shell task\'s output. send: prompt an '
         + 'existing session. create_session: start a new session with a first prompt. update_session: change '
-        + 'another session\'s settings (model, effort, mode, auto-compact window, title, group, thinking, cwd). wait: keep waiting for '
+        + 'another session\'s settings (model, effort, mode, auto-compact window, title, group, thinking, cwd, image defaults). wait: keep waiting for '
         + 'a reply. answer_question: answer a question the remote agent asked. stop: stop the running turn. '
         + 'archive: archive a session. subscribe / unsubscribe / list_subscriptions / transfer_subscriptions: '
         + 'be woken by events of sessions on this relay or a paired one (relay may be left out: "this"). '
@@ -545,6 +571,35 @@ export const REMOTE_RELAY_TOOL_INPUT_SCHEMA = Object.freeze({
       enum: [...THINKING_DISPLAY_MODES],
       description: 'update_session: whether a Claude session\'s thinking text shows in its transcript (summarized) or not (omitted).',
     },
+    images: {
+      type: 'array',
+      items: { type: 'string' },
+      maxItems: REMOTE_RELAY_LIMITS.imagesMax,
+      description: `send / create_session to an OpenAI image session (provider openai, a gpt-image or dall-e model): up to ${REMOTE_RELAY_LIMITS.imagesMax} `
+        + `absolute paths of PNG, JPEG or WebP files on the target relay (each at most ${OPENAI_IMAGE_LIMITS.inputImageBytesMax / (1024 * 1024)} MB) that the model edits or works from, `
+        + 'with text as the instruction. Allowed: files inside the target session\'s working directory, or images any session there '
+        + 'generated (the paths its replies list). Refused for other models; a paired relay must run an OAR that takes them.',
+    },
+    image: {
+      type: 'object',
+      properties: {
+        size: { type: 'string', description: '"auto" or WIDTHxHEIGHT, e.g. 1536x1024: gpt-image takes both edges multiples of 16, the longer at most 3840, at most 3840x2160 pixels (gpt-image-2 and later: at least 655360 pixels, e.g. 1024x640), aspect 1:3 to 3:1; dall-e-3 1024x1024, 1792x1024 or 1024x1792; dall-e-2 256x256, 512x512 or 1024x1024.' },
+        quality: { type: 'string', description: 'gpt-image: auto, low, medium or high, and xhigh or max on the gpt-image 2.5 and 2.6 models (checked against the session\'s model); dall-e-3: standard or hd.' },
+        count: { type: 'integer', minimum: 1, maximum: OPENAI_IMAGE_LIMITS.countMax, description: `Images per turn, 1 to ${OPENAI_IMAGE_LIMITS.countMax} (dall-e-3: 1). Default 1.` },
+        output_format: { type: 'string', enum: [...OPENAI_IMAGE_OUTPUT_FORMATS], description: 'gpt-image only: png (default), webp or jpeg.' },
+        background: { type: 'string', enum: [...OPENAI_IMAGE_BACKGROUNDS], description: 'gpt-image only: auto (default), transparent (png or webp) or opaque.' },
+        preset: {
+          type: 'string',
+          maxLength: OPENAI_IMAGE_PRESET_LIMITS.nameChars,
+          description: `send / create_session only: a named set of these options, e.g. ${OPENAI_IMAGE_BUILTIN_PRESETS.map((preset) => `"${preset.name}"`).join(', ')} `
+            + '(the built-ins; relay_info lists imagePresets with the relay owner\'s own). It sits over the session\'s defaults, '
+            + 'and the fields named next to it win over it. An unknown name is refused with the list; nothing is sent.',
+        },
+      },
+      description: 'send / create_session: image options for that turn, over the session\'s defaults. update_session: the image '
+        + 'session\'s defaults from now on (the fields named replace those defaults; auto, 1 and png set one back; no preset). '
+        + 'Refused for a session whose model makes no images.',
+    },
     question_id: { type: 'string', description: 'answer_question: id from pendingQuestions. withdraw: the id ask returned.' },
     question: {
       type: 'string',
@@ -696,8 +751,8 @@ export const REMOTE_RELAY_ACTION_ARGUMENTS = Object.freeze({
   read_session: Object.freeze(['session', 'last', 'before', 'include_activity', 'max_chars']),
   read_task_output: Object.freeze(['session', 'task_id', 'lines']),
   wait: Object.freeze(['session', 'message_id', 'wait_seconds']),
-  send: Object.freeze(['session', 'text', 'wait_seconds', 'model', 'mode', 'effort', 'if_busy', 'provider']),
-  create_session: Object.freeze(['text', 'provider', 'model', 'cwd', 'repo', 'branch', 'mode', 'effort', 'title', 'group', 'wait_seconds', 'planOnly']),
+  send: Object.freeze(['session', 'text', 'wait_seconds', 'model', 'mode', 'effort', 'if_busy', 'provider', 'images', 'image']),
+  create_session: Object.freeze(['text', 'provider', 'model', 'cwd', 'repo', 'branch', 'mode', 'effort', 'title', 'group', 'wait_seconds', 'planOnly', 'images', 'image']),
   update_session: Object.freeze(['session', ...REMOTE_RELAY_SESSION_SETTINGS]),
   answer_question: Object.freeze(['question_id', 'answer', 'choices']),
   stop: Object.freeze(['session']),
@@ -913,6 +968,12 @@ function validateToolInput(input, { maxWaitSeconds, now, providers, sendProvider
       }
       args.effort = effort;
     }
+    const imagesCheck = readImagePaths(input?.images);
+    if (!imagesCheck.ok) return imagesCheck;
+    if (imagesCheck.paths.length) args.images = imagesCheck.paths;
+    const imageCheck = readTurnImageOptions(input?.image);
+    if (!imageCheck.ok) return imageCheck;
+    if (Object.keys(imageCheck.values).length) args.image = imageCheck.values;
     if (action === 'send') {
       const busyCheck = optionalEnum('if_busy', REMOTE_RELAY_IF_BUSY);
       if (!busyCheck.ok) return busyCheck;
@@ -920,10 +981,16 @@ function validateToolInput(input, { maxWaitSeconds, now, providers, sendProvider
       const providerCheck = optionalProvider(sendProviders, (value, list) =>
         `provider "${value}" can't be used with send; send takes one of: ${list} (the Claude session's subscription or API key)`);
       if (!providerCheck.ok) return providerCheck;
+      if (args.provider && (args.images || args.image)) {
+        return invalid('images and image go to an OpenAI image session, not with provider (a Claude session\'s billing)');
+      }
     } else {
       const providerCheck = optionalProvider(providers, (value, list) =>
         `provider "${value}" is not a provider here; this relay offers: ${list}`);
       if (!providerCheck.ok) return providerCheck;
+      if (args.provider && args.provider !== REMOTE_RELAY_IMAGE_PROVIDER && (args.images || args.image)) {
+        return invalid(`images and image go with provider "${REMOTE_RELAY_IMAGE_PROVIDER}" and an image model (gpt-image-*, dall-e-*), not provider "${args.provider}"`);
+      }
       optionalText('cwd', 1000);
       optionalText('title', 200);
       // An empty group is no group: the default grouping applies.
@@ -982,6 +1049,53 @@ function validateToolInput(input, { maxWaitSeconds, now, providers, sendProvider
   return { ok: true, action, args, ...(waits ? waitLimited : {}) };
 }
 
+// Image paths are read on the target relay, whose platform this relay may not
+// share: a POSIX path or a drive path (C:\ or C:/). Network and device paths
+// (\\host\share, //host/share, \\?\, \\.\) are refused: merely touching one can
+// open a connection that hands out the relay's credentials.
+const ABSOLUTE_PATH_PATTERN = /^(?:\/(?!\/)|[A-Za-z]:[\\/])/;
+
+/**
+ * send / create_session's `images`: absolute paths, at most imagesMax, the
+ * same path named twice kept once. A single text is one path.
+ */
+function readImagePaths(value) {
+  if (value === undefined || value === null || value === '') return { ok: true, paths: [] };
+  const list = typeof value === 'string' ? [value] : value;
+  if (!Array.isArray(list)) return invalid('images must be a list of absolute file paths on the target relay');
+  const paths = [];
+  for (const entry of list) {
+    if (typeof entry !== 'string') return invalid('images must be a list of absolute file paths on the target relay');
+    const path = entry.trim();
+    if (!path) continue;
+    if (path.length > REMOTE_RELAY_LIMITS.imagePathMaxChars || path.includes('\0')) return invalid('images: a path is too long or not a path');
+    if (!ABSOLUTE_PATH_PATTERN.test(path)) {
+      return invalid(`images: "${path.slice(0, 120)}" is not an absolute local path; give the full path on the target relay (no network paths)`);
+    }
+    if (!paths.includes(path)) paths.push(path);
+  }
+  if (paths.length > REMOTE_RELAY_LIMITS.imagesMax) return invalid(`images takes at most ${REMOTE_RELAY_LIMITS.imagesMax} paths`);
+  return { ok: true, paths };
+}
+
+/**
+ * send / create_session's `image`: the options as the validator checks them
+ * (without a model; the target checks them against its session's), and
+ * `preset` as a clean name. Only its shape is checked here: the target
+ * relay knows its presets and resolves the name.
+ */
+function readTurnImageOptions(value) {
+  const { preset, own } = splitOpenAIImagePreset(value);
+  const checked = validateOpenAIImageOptions(own, { field: 'image' });
+  if (!checked.ok) return invalid(checked.error);
+  if (preset === null || preset === undefined || (typeof preset === 'string' && !preset.trim())) {
+    return { ok: true, values: checked.values };
+  }
+  const name = cleanOpenAIImagePresetName(preset);
+  if (name.error) return invalid(`image.preset: ${name.error}`);
+  return { ok: true, values: { ...checked.values, preset: name.name } };
+}
+
 function readBoolean(value) {
   if (value === true || value === false) return value;
   const text = toText(value).toLowerCase();
@@ -1060,6 +1174,14 @@ export function validateRemoteRelaySessionSettings(input) {
     if (!THINKING_DISPLAY_MODES.includes(display)) return invalid(`thinking_display must be one of: ${THINKING_DISPLAY_MODES.join(', ')}`);
     values.thinking_display = display;
   }
+  // A preset is a turn's: the defaults are the fields themselves.
+  const { preset: defaultsPreset, own: defaults } = splitOpenAIImagePreset(input?.image);
+  if (defaultsPreset !== null && defaultsPreset !== undefined && toText(defaultsPreset) !== '') {
+    return invalid('image.preset: a preset is per turn (send, create_session); name its fields to set defaults');
+  }
+  const image = validateOpenAIImageOptions(defaults, { field: 'image' });
+  if (!image.ok) return invalid(image.error);
+  if (Object.keys(image.values).length) values.image = image.values;
   if (!Object.keys(values).length) {
     return invalid(`update_session needs at least one setting to change: ${REMOTE_RELAY_SESSION_SETTINGS.join(', ')}`);
   }

package/shared/worker-runtime/direct-openai-image.mjs

@@ -6,16 +6,18 @@
 //
 // With image continuity on (the default) the relay created an image operation
 // when the message was sent, and `POST /api/image-operations/:id/execute` does
-// everything: the provider call, the generated-image reply, and on a failure
-// the failure note or the requeue. The caller only reports the outcome. Without
-// an operation the worker calls `POST /api/openai/images/generate` and
-// publishes the reply itself.
+// everything: the provider call with its one retry, the generated-image reply,
+// and on a failure the failure note. The caller only reports the outcome.
+// Without an operation the worker calls `POST /api/openai/images/generate`
+// (the same request, the same retry) and publishes the reply or the note
+// itself. Neither path requeues a row whose request may have reached OpenAI:
+// a second run is billed again.
 
 export const DIRECT_IMAGE_OUTCOMES = Object.freeze(['completed', 'executing', 'terminal', 'uncertain', 'retryable']);
 
-// The code of the error thrown when the provider refused the request outright:
-// a retry would be refused the same way, so the turn fails instead of being
-// requeued.
+// The code of the error thrown when the direct request failed: the relay
+// already retried what could pass, so the turn fails with the relay's note
+// instead of being requeued. `imageCode` carries the relay's own code.
 export const OPENAI_IMAGE_TERMINAL_CODE = 'RELAY_OPENAI_IMAGE_TERMINAL';
 
 export function shouldUseDirectOpenAIImageApi(message = {}) {
@@ -25,28 +27,51 @@ export function shouldUseDirectOpenAIImageApi(message = {}) {
   return model.startsWith('gpt-image-') || model.startsWith('dall-e-');
 }
 
-export function isDirectOpenAIImageTerminalStatus(status) {
-  const numeric = Number(status);
-  if (!Number.isFinite(numeric)) return false;
-  return [400, 401, 403, 404, 409, 422, 429, 503].includes(numeric);
-}
-
 export function isOpenAIImageTerminalError(error) {
   return String(error?.code || '').trim() === OPENAI_IMAGE_TERMINAL_CODE;
 }
 
 const isAutoModel = (value) => String(value || '').trim().toLowerCase() === 'auto';
 
+function imageTerminalError(message, { imageCode = '', status, detail = null, relayProcessing = false } = {}) {
+  const error = new Error(message);
+  error.code = OPENAI_IMAGE_TERMINAL_CODE;
+  error.imageCode = String(imageCode || '').trim().toLowerCase().replace(/_/g, '-');
+  error.relayProcessing = relayProcessing;
+  error.status = status;
+  error.detail = detail;
+  return error;
+}
+
+/**
+ * The image options of a direct request: the message's `imageOptions`
+ * ({ size, quality, count, output_format, background }) first, then the
+ * composer's quality and size fields.
+ */
+function directImageOptions(message = {}) {
+  const options = message?.imageOptions && typeof message.imageOptions === 'object' ? message.imageOptions : {};
+  const pick = (...values) => values.find((value) => value !== undefined && value !== null && String(value).trim() !== '');
+  return {
+    n: pick(options.count, message?.n),
+    size: pick(options.size, message?.size, message?.contextTier),
+    quality: pick(options.quality, message?.quality, message?.reasoningEffort),
+    output_format: pick(options.output_format),
+    background: pick(options.background),
+  };
+}
+
 /**
  * Run one image turn. `requestOptions` goes to every `api` call that may wait
- * on the provider (a worker passes `{ longCall: true }`: an edit can take
- * minutes); `responseFields` is merged into the reply the worker publishes
- * itself (the attempt fence).
+ * on the provider (a worker passes `{ longCall: true }`: an edit with its
+ * retry can take minutes); `responseFields` is merged into the reply the
+ * worker publishes itself (the attempt fence).
  *
- * Resolves `{ via: 'operation', outcome }` or `{ via: 'direct', outcome:
- * 'completed', imageCount, model }`. Throws an error with `code`
- * `OPENAI_IMAGE_TERMINAL_CODE` when the provider refused the direct request,
- * and a plain error for anything else (the caller requeues).
+ * Resolves `{ via: 'operation', outcome, usage }` or `{ via: 'direct',
+ * outcome: 'completed', imageCount, model, usage }`. On the direct path every
+ * failure, once the request may have gone out, throws an error with `code`
+ * `OPENAI_IMAGE_TERMINAL_CODE` and the relay's note as its message: the
+ * caller publishes it and never requeues. A plain error comes only from the
+ * operation path (the relay's execute route guards a second run itself).
  */
 export async function runDirectOpenAIImageTurn({
   api,
@@ -61,8 +86,8 @@ export async function runDirectOpenAIImageTurn({
       { messageId: message.id },
       requestOptions,
     ).catch((error) => {
-      // The route answers a failure it already handled (published or
-      // requeued) with 409 or 503 and the outcome in the body.
+      // The route answers a failure it already published with 409 (503 on
+      // an older relay that requeued it) and the outcome in the body.
       if (error?.status === 409 || error?.status === 503) {
         return error?.body || error?.payload || { outcome: error?.status === 503 ? 'retryable' : 'terminal' };
       }
@@ -72,14 +97,15 @@ export async function runDirectOpenAIImageTurn({
     if (!DIRECT_IMAGE_OUTCOMES.includes(outcome)) {
       throw new Error('Image operation returned an invalid outcome');
     }
-    return { via: 'operation', outcome };
+    return { via: 'operation', outcome, usage: result?.usage || null };
   }
 
   const requestedModel = isAutoModel(message?.model) ? '' : String(message?.model || '').trim();
   const directModel = String(message?.providerModel || requestedModel || message?.model || '').trim();
   const prompt = String(message?.text || '').trim();
-  if (!directModel) throw new Error('OpenAI image request is missing model');
-  if (!prompt) throw new Error('OpenAI image request is missing prompt');
+  // Nothing was sent: a note, not a requeue that fails the same way.
+  if (!directModel) throw imageTerminalError('OpenAI image request is missing model', { imageCode: 'image-request-invalid' });
+  if (!prompt) throw imageTerminalError('OpenAI image request is missing prompt', { imageCode: 'image-request-invalid' });
   await api('POST', '/api/activity', {
     messageId: message.id,
     conversationId: message.conversationId,
@@ -93,40 +119,60 @@ export async function runDirectOpenAIImageTurn({
       conversationId: message.conversationId,
       model: directModel,
       prompt,
-      n: message?.n,
-      size: message?.size || message?.contextTier,
-      quality: message?.quality || message?.reasoningEffort,
+      ...directImageOptions(message),
       attachments: Array.isArray(message?.attachments) ? message.attachments : [],
     }, requestOptions);
   } catch (error) {
+    // The relay answered with its note (it retried what could pass), or the
+    // call to the relay itself broke off while OpenAI may have been working.
     // `relayProcessing`: the provider answered 2xx and the relay could not
-    // process the reply; the generation is billed, so no requeue either.
+    // process the reply; the generation is billed.
     const relayProcessing = error?.body?.relayProcessing === true;
-    if (isDirectOpenAIImageTerminalStatus(error?.status) || relayProcessing) {
-      const terminalError = new Error(relayProcessing
-        ? `The relay could not process the image OpenAI returned (${error?.detail || 'unknown error'}). The generation was billed; the message was not retried.`
-        : `OpenAI image request failed: ${error?.detail || `HTTP ${error?.status || 'error'}`}`);
-      terminalError.code = OPENAI_IMAGE_TERMINAL_CODE;
-      terminalError.relayProcessing = relayProcessing;
-      terminalError.status = error?.status;
-      terminalError.detail = error?.detail || null;
-      throw terminalError;
+    const note = String(error?.body?.error || '').trim();
+    if (error?.status) {
+      throw imageTerminalError(note || `OpenAI image request failed: ${error?.detail || `HTTP ${error.status}`}`, {
+        imageCode: error?.body?.code || (relayProcessing ? 'image-reply-unprocessed' : 'image-provider-rejected'),
+        status: error.status,
+        // The relay's detail (a network error's code), not its note again.
+        detail: error?.body?.detail || null,
+        relayProcessing,
+      });
     }
-    throw error;
+    throw imageTerminalError(
+      `The relay did not finish the image request (${error?.message || 'connection error'}); the request may have been billed; retry the message.`,
+      { imageCode: 'image-provider-no-answer', detail: error?.message || null },
+    );
   }
   const generatedImages = Array.isArray(directResult?.generatedImages) ? directResult.generatedImages : [];
   if (!generatedImages.length) {
-    throw new Error('OpenAI image API returned no images');
+    throw imageTerminalError('OpenAI image API returned no images. The generation may have been billed; the message was not retried.', {
+      imageCode: 'image-reply-unprocessed',
+      relayProcessing: true,
+    });
   }
   const model = String(directResult?.model || directModel).trim() || directModel;
-  await api('POST', '/api/response', {
-    messageId: message.id,
-    conversationId: message.conversationId,
-    text: '',
-    generatedImages,
-    model,
-    modelOrigin: isAutoModel(message?.model) ? 'auto' : 'manual',
-    ...responseFields,
-  });
-  return { via: 'direct', outcome: 'completed', imageCount: generatedImages.length, model };
+  const usage = directResult?.usage || null;
+  // The relay's note when the first try may have been billed as well.
+  const note = String(directResult?.note || '').trim();
+  try {
+    await api('POST', '/api/response', {
+      messageId: message.id,
+      conversationId: message.conversationId,
+      text: '',
+      generatedImages,
+      model,
+      modelOrigin: isAutoModel(message?.model) ? 'auto' : 'manual',
+      // What OpenAI counted for this request, for the cost booking.
+      ...(usage ? { imageUsage: usage } : {}),
+      ...(note ? { imageNote: note } : {}),
+      ...responseFields,
+    });
+  } catch (error) {
+    // The images are billed; a requeue would pay for them again.
+    throw imageTerminalError(
+      `The images OpenAI returned could not be saved (${error?.detail || error?.message || 'unknown error'}). The generation was billed; the message was not retried.`,
+      { imageCode: 'image-finalization-uncertain', status: error?.status, detail: error?.detail || null, relayProcessing: true },
+    );
+  }
+  return { via: 'direct', outcome: 'completed', imageCount: generatedImages.length, model, usage };
 }

package/server/public/app/math-dollars.mjs

@@ -1,89 +0,0 @@
-// Which `$` in a run of text delimit inline maths, and which are plain dollar
-// signs. Prices are the common case of the second kind: without a rule,
-// "$5 for one and $9 for two" reads as one formula running from the first
-// sign to the second.
-//
-// The rule is the one pandoc uses for dollar maths: the opening `$` has a
-// non-space character directly after it, the closing `$` is the next dollar
-// sign, has a non-space character directly before it and no digit directly
-// after it. A `$$` pair is
-// display maths and is left alone, and a `$` behind a backslash is escaped.
-
-const TEX_LOOKING = /[\\^_{}=]/;
-
-function isEscaped(text, index) {
-  let backslashes = 0;
-  for (let i = index - 1; i >= 0 && text[i] === '\\'; i -= 1) backslashes += 1;
-  return backslashes % 2 === 1;
-}
-
-function isSpace(char) {
-  return char === undefined || /\s/.test(char);
-}
-
-// A formula holds no dollar sign of its own, so only the next one can close
-// it. When that one does not qualify ("$5, and $x^2$": it follows a space),
-// the opening sign is a plain dollar and the next one gets its own turn.
-function findClosingDollar(text, openIndex) {
-  let i = openIndex + 1;
-  while (i < text.length && (text[i] !== '$' || isEscaped(text, i))) i += 1;
-  if (i >= text.length) return -1;
-  // Part of a `$$`: not the end of an inline formula.
-  if (text[i + 1] === '$') return -1;
-  if (isSpace(text[i - 1])) return -1;
-  const content = text.slice(openIndex + 1, i);
-  // "$5/$10": a digit right behind the sign means the sign starts a number.
-  // Real maths directly followed by a digit ("$x^2$3") is told apart by
-  // looking like TeX.
-  if (/\d/.test(text[i + 1] || '') && !TEX_LOOKING.test(content)) return -1;
-  return i;
-}
-
-/**
- * Scan `text` for single-dollar maths.
- * @returns {{ spans: Array<[number, number]>, literals: number[] }} `spans`
- *   are [open, close] index pairs of formulas, `literals` the indexes of `$`
- *   that are plain dollar signs.
- */
-export function scanInlineDollars(text) {
-  const source = String(text ?? '');
-  const spans = [];
-  const literals = [];
-  let index = 0;
-  while (index < source.length) {
-    if (source[index] !== '$' || isEscaped(source, index)) {
-      index += 1;
-      continue;
-    }
-    if (source[index + 1] === '$') {
-      const close = source.indexOf('$$', index + 2);
-      index = close < 0 ? index + 2 : close + 2;
-      continue;
-    }
-    const close = isSpace(source[index + 1]) ? -1 : findClosingDollar(source, index);
-    if (close < 0) {
-      literals.push(index);
-      index += 1;
-      continue;
-    }
-    spans.push([index, close]);
-    index = close + 1;
-  }
-  return { spans, literals };
-}
-
-/** `text` cut at its plain dollar signs: `[{ text, literal }]`, in order. */
-export function splitAtLiteralDollars(text) {
-  const source = String(text ?? '');
-  const { literals } = scanInlineDollars(source);
-  if (!literals.length) return [{ text: source, literal: false }];
-  const parts = [];
-  let from = 0;
-  for (const index of literals) {
-    if (index > from) parts.push({ text: source.slice(from, index), literal: false });
-    parts.push({ text: '$', literal: true });
-    from = index + 1;
-  }
-  if (from < source.length) parts.push({ text: source.slice(from), literal: false });
-  return parts;
-}