@oar-sh/oar 0.9.23 → 0.9.25

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)}`;
+}

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(', ')}`);
   }