mixdog 1.2.3 → 1.2.4

package/src/runtime/media/adapters/codex-image.mjs

@@ -1,17 +1,27 @@
 /**
  * ChatGPT OAuth image adapter (`openai-oauth` lane).
  *
- * Runs the hosted `image_generation` tool on the Codex responses backend — the
- * same endpoint/headers the chat provider uses, so the subscription session is
- * the only credential involved. The final image arrives as base64 on the
- * image_generation_call item; partial frames are kept as a fallback.
+ * Primary path: the subscription's Images endpoints on the Codex backend
+ * (`images/generations`, or `images/edits` when reference images are given),
+ * a plain JSON request answered with the finished image as base64.
+ *
+ * Fallback path, used only when those endpoints are not served (404/405/501,
+ * or the edge's HTML 403 for an unknown route): the hosted `image_generation`
+ * tool on the responses backend. Its final image arrives on the
+ * image_generation_call item; a stream that only produced partial preview
+ * frames fails instead of saving a draft as the result.
+ *
+ * Both paths use the chat provider's session, so the subscription login is the
+ * only credential involved. Usage-limit failures name the reset time, looked up
+ * from the account's usage summary when the failure itself omits it.
  */
 import { randomBytes } from 'node:crypto';
 import { resolveCodexAuth } from '../auth.mjs';
 import { timeoutSignal } from '../bounded-signal.mjs';
+import { chatgptLimitResetAt } from '../chatgpt-usage.mjs';
 import { decodeBase64Media } from '../download.mjs';
 import { mediaError } from '../lanes.mjs';
-import { upstreamError } from '../upstream-error.mjs';
+import { upstreamError, usageLimitError, usageLimitFromResponse, usageLimitInfo } from '../upstream-error.mjs';
 import { responsesUsage, withReportedUsage } from '../media-usage.mjs';
 import { CODEX_OAUTH_ORIGINATOR, CODEX_RESPONSES_URL } from '../../agent/orchestrator/providers/openai-oauth.mjs';
 import {
@@ -21,6 +31,13 @@ import {
 } from '../../agent/orchestrator/providers/codex-client-meta.mjs';
 
 const REQUEST_TIMEOUT_MS = 400_000;
+const LABEL = 'ChatGPT image';
+export const CODEX_IMAGE_MODEL = 'gpt-image-2';
+export const CODEX_IMAGES_GENERATIONS_URL = new URL('images/generations', CODEX_RESPONSES_URL).href;
+export const CODEX_IMAGES_EDITS_URL = new URL('images/edits', CODEX_RESPONSES_URL).href;
+const BACKGROUNDS = new Set(['transparent', 'opaque', 'auto']);
+
+const dataUrl = (ref) => `data:${ref.mime || 'image/png'};base64,${ref.base64}`;
 
 function imageTool(options = {}) {
   const tool = { type: 'image_generation' };
@@ -28,9 +45,91 @@ function imageTool(options = {}) {
   if (size && size !== 'auto') tool.size = size;
   const quality = String(options.quality || 'auto');
   if (quality && quality !== 'auto') tool.quality = quality;
+  if (options.background && options.background !== 'auto') tool.background = options.background;
   return tool;
 }
 
+/** Images endpoint request: generation, or an edit when references are given. */
+export function codexImagesRequest({ prompt, options = {}, references = [] }) {
+  const body = { prompt, model: CODEX_IMAGE_MODEL, size: 'auto', quality: 'auto' };
+  if (options.background) body.background = options.background;
+  if (!references.length) return { url: CODEX_IMAGES_GENERATIONS_URL, body };
+  return {
+    url: CODEX_IMAGES_EDITS_URL,
+    body: { images: references.map((ref) => ({ image_url: dataUrl(ref) })), ...body },
+  };
+}
+
+export function codexImagesRequestHeaders(auth) {
+  const headers = {
+    Authorization: `Bearer ${auth.access_token}`,
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    originator: CODEX_OAUTH_ORIGINATOR,
+    'x-client-request-id': randomBytes(16).toString('hex'),
+    version: codexVersionHeader(),
+    'User-Agent': codexUserAgent(),
+  };
+  if (auth.account_id) headers['ChatGPT-Account-ID'] = auth.account_id;
+  return headers;
+}
+
+// The endpoint is not served for this backend: a missing route or method, or
+// the edge's HTML 403 page that unknown backend routes answer with. Auth,
+// billing and limit failures come back as JSON and are reported, not retried.
+function imagesEndpointUnavailable(res) {
+  if ([404, 405, 501].includes(res.status)) return true;
+  return res.status === 403 && !/json/i.test(res.headers.get('content-type') || '');
+}
+
+function imagesUsage(usage) {
+  const tokens = responsesUsage(usage);
+  const imageTokens = Math.trunc(Number(usage?.output_tokens_details?.image_tokens) || 0);
+  return imageTokens > 0 ? { ...tokens, outputImageTokens: imageTokens } : tokens;
+}
+
+async function limitError(limit, { auth, fetchFn, lookupReset, signal }) {
+  const resetsAt = limit.resetsAt || (await lookupReset({ auth, limitId: limit.limitId, fetchFn, signal }));
+  return usageLimitError(LABEL, { limitId: limit.limitId, resetsAt });
+}
+
+async function failedResponse(res, ctx) {
+  const text = await res.text().catch(() => '');
+  const limit = usageLimitFromResponse(res.status, text, res.headers);
+  if (limit) return await limitError(limit, ctx);
+  return upstreamError(LABEL, res.status, text);
+}
+
+/** Returns the image, or null when the Images endpoint is unavailable. */
+async function generateViaImagesEndpoint({ prompt, options, references, signal }, ctx) {
+  const { url, body } = codexImagesRequest({ prompt, options, references });
+  const res = await ctx.fetchFn(url, {
+    method: 'POST',
+    headers: codexImagesRequestHeaders(ctx.auth),
+    body: JSON.stringify(body),
+    redirect: 'error',
+    signal: timeoutSignal(signal, REQUEST_TIMEOUT_MS),
+  });
+  if (imagesEndpointUnavailable(res)) {
+    await res.body?.cancel().catch(() => {});
+    return null;
+  }
+  if (!res.ok) throw await failedResponse(res, ctx);
+  const json = await res.json().catch(() => null);
+  const usage = imagesUsage(json?.usage);
+  const b64 = json?.data?.[0]?.b64_json;
+  if (typeof b64 !== 'string' || !b64) {
+    throw withReportedUsage(mediaError(`${LABEL}: returned no image data`, 'MEDIA_EMPTY_RESULT', 502), usage);
+  }
+  return {
+    bytes: decodeBase64Media(b64, LABEL),
+    mime: 'image/png',
+    revisedPrompt: null,
+    actualModel: CODEX_IMAGE_MODEL,
+    usage: usage || null,
+  };
+}
+
 function collectImage(event, state) {
   const item = event?.item;
   // Terminal Responses events carry the orchestrator's token usage. It does
@@ -55,10 +154,7 @@ export function codexImageRequestBody({ model, prompt, options = {}, references
   // Reference images ride as input_image parts on the user turn — the same
   // shape the chat path uses for pasted images.
   const content = [
-    ...references.map((ref) => ({
-      type: 'input_image',
-      image_url: `data:${ref.mime || 'image/png'};base64,${ref.base64}`,
-    })),
+    ...references.map((ref) => ({ type: 'input_image', image_url: dataUrl(ref) })),
     { type: 'input_text', text: prompt },
   ];
   return {
@@ -91,7 +187,12 @@ export function codexImageRequestHeaders(auth) {
 
 export async function generateImage(
   { model, prompt, options = {}, references = [], signal },
-  { fetchFn = fetch, resolveAuth = resolveCodexAuth, warmVersion = warmCodexClientVersion } = {}
+  {
+    fetchFn = fetch,
+    resolveAuth = resolveCodexAuth,
+    warmVersion = warmCodexClientVersion,
+    lookupReset = chatgptLimitResetAt,
+  } = {}
 ) {
   if (['size', 'quality', 'resolution', 'aspectRatio'].some((key) => options[key] && options[key] !== 'auto')) {
     throw mediaError(
@@ -99,19 +200,28 @@ export async function generateImage(
       'MEDIA_OPTION_UNSUPPORTED'
     );
   }
+  if (options.background && !BACKGROUNDS.has(options.background)) {
+    throw mediaError('background must be transparent, opaque or auto.', 'MEDIA_OPTION_UNSUPPORTED');
+  }
   const auth = await resolveAuth();
   // Discovery and generation must report the same client version; otherwise
   // a newly discovered model can still be rejected by the Codex version gate.
   await warmVersion();
+  const ctx = { auth, fetchFn, lookupReset, signal };
+  const image = await generateViaImagesEndpoint({ prompt, options, references, signal }, ctx);
+  return image || (await generateViaResponses({ model, prompt, options, references, signal }, ctx));
+}
+
+async function generateViaResponses({ model, prompt, options, references, signal }, ctx) {
   const body = codexImageRequestBody({ model, prompt, options, references });
-  const res = await fetchFn(CODEX_RESPONSES_URL, {
+  const res = await ctx.fetchFn(CODEX_RESPONSES_URL, {
     method: 'POST',
-    headers: codexImageRequestHeaders(auth),
+    headers: codexImageRequestHeaders(ctx.auth),
     body: JSON.stringify(body),
     redirect: 'error',
     signal: timeoutSignal(signal, REQUEST_TIMEOUT_MS),
   });
-  if (!res.ok || !res.body) throw upstreamError('ChatGPT image', res.status, await res.text().catch(() => ''));
+  if (!res.ok || !res.body) throw await failedResponse(res, ctx);
 
   const reader = res.body.getReader();
   const decoder = new TextDecoder();
@@ -136,7 +246,8 @@ export async function generateImage(
           continue;
         }
         if (event?.type === 'response.failed' || event?.type === 'error') {
-          failure = event?.response?.error?.message || event?.message || 'stream failed';
+          // A top-level `error` event carries code/type/resets_at on itself.
+          failure = event?.response?.error || event?.error || event;
         }
         collectImage(event, state);
       }
@@ -147,15 +258,23 @@ export async function generateImage(
     } catch {}
   }
 
-  const b64 = state.final || state.partial;
-  if (!b64) {
-    throw withReportedUsage(
-      mediaError(`ChatGPT returned no image data${failure ? `: ${failure}` : ''}`, 'MEDIA_EMPTY_RESULT', 502),
-      state.usage
-    );
+  if (!state.final) {
+    const limit = failure && usageLimitInfo(failure, res.headers);
+    if (limit) throw withReportedUsage(await limitError(limit, ctx), state.usage);
+    const reason = (typeof failure === 'string' ? failure : failure?.message) || 'stream failed';
+    // A partial frame is a low-fidelity preview of an unfinished render; it is
+    // never saved as the result.
+    const error = state.partial
+      ? mediaError(
+          `${LABEL}: generation stopped after a partial preview; no final image was produced${failure ? ` (${reason})` : ''}`,
+          'MEDIA_PARTIAL_ONLY',
+          502
+        )
+      : mediaError(`ChatGPT returned no image data${failure ? `: ${reason}` : ''}`, 'MEDIA_EMPTY_RESULT', 502);
+    throw withReportedUsage(error, state.usage);
   }
   return {
-    bytes: decodeBase64Media(b64, 'ChatGPT image'),
+    bytes: decodeBase64Media(state.final, LABEL),
     mime: 'image/png',
     revisedPrompt: state.revisedPrompt,
     actualModel: state.actualModel || null,

package/src/runtime/media/catalog.mjs

@@ -145,12 +145,12 @@ export function projectMediaModels(lane, rows) {
     result.image = orchestrator
       ? [
           {
-            id: 'chatgpt-image-auto',
-            label: 'ChatGPT Image · Auto',
+            id: 'gpt-image-2',
+            label: 'GPT Image 2',
             description:
-              'ChatGPT selects the image engine. GPT Image 2.5 selection and output size/quality are not verified on this connection.',
+              'ChatGPT image engine. Output size/quality are chosen by ChatGPT; background can be transparent.',
             requestModel: orchestrator.id,
-            controls: { maxReferences: 5 },
+            controls: { maxReferences: 5, background: ['auto', 'transparent', 'opaque'] },
           },
         ]
       : [];

package/src/runtime/media/chatgpt-usage.mjs

@@ -0,0 +1,55 @@
+/**
+ * ChatGPT subscription usage lookup.
+ *
+ * A usage-limit failure does not always say when the window reopens. The
+ * account's usage summary does: each metered limit lists its windows with
+ * `used_percent` and an epoch `reset_at`.
+ */
+import { timeoutSignal } from './bounded-signal.mjs';
+import { codexUserAgent } from '../agent/orchestrator/providers/codex-client-meta.mjs';
+
+export const CHATGPT_USAGE_URL = 'https://chatgpt.com/backend-api/wham/usage';
+const LOOKUP_TIMEOUT_MS = 10_000;
+
+function exhaustedResetAt(rateLimit) {
+  if (!rateLimit || typeof rateLimit !== 'object') return null;
+  const windows = [rateLimit.primary_window, rateLimit.secondary_window].filter((w) => Number(w?.reset_at) > 0);
+  const full = windows.filter((w) => Number(w.used_percent) >= 100);
+  const candidates = full.length ? full : rateLimit.limit_reached ? windows : [];
+  return candidates.length ? Math.max(...candidates.map((w) => Math.trunc(Number(w.reset_at)))) : null;
+}
+
+/**
+ * Reset time (epoch seconds) of the exhausted limit in a usage summary. The
+ * limit named `limitId` wins; an image limit is next; the account's main
+ * window is last.
+ */
+export function limitResetFromUsage(payload, limitId = '') {
+  const extra = Array.isArray(payload?.additional_rate_limits) ? payload.additional_rate_limits : [];
+  const id = String(limitId).toLowerCase();
+  const names = (entry) => [entry?.metered_feature, entry?.limit_name].map((name) => String(name || '').toLowerCase());
+  const named =
+    (id && extra.find((entry) => names(entry).includes(id))) ||
+    extra.find((entry) => names(entry).some((name) => name.includes('image')));
+  return exhaustedResetAt(named ? named.rate_limit : payload?.rate_limit);
+}
+
+/**
+ * Look the reset time up for the signed-in account. A failed lookup yields
+ * null: the caller still reports the limit, just without a time.
+ */
+export async function chatgptLimitResetAt({ auth, limitId = '', fetchFn = fetch, signal } = {}) {
+  try {
+    const headers = { Authorization: `Bearer ${auth.access_token}`, 'User-Agent': codexUserAgent() };
+    if (auth.account_id) headers['ChatGPT-Account-Id'] = auth.account_id;
+    const res = await fetchFn(CHATGPT_USAGE_URL, {
+      headers,
+      redirect: 'error',
+      signal: timeoutSignal(signal, LOOKUP_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    return limitResetFromUsage(await res.json(), limitId);
+  } catch {
+    return null;
+  }
+}

package/src/runtime/media/defaults.mjs

@@ -41,6 +41,43 @@ export function getMediaDefault(kind) {
   return lane ? { kind: key, lane, model: text(row?.model) } : null;
 }
 
+// Settings → Built-in → Media generation. Unlike the remembered selection above
+// (rewritten by every generation), a pin is only ever written by the user:
+// `{ lane, model, account }` per kind, where an empty model is the lane default
+// and an empty account follows that provider's currently selected account.
+const PINNED = 'pinned';
+
+function readPins() {
+  const pins = readAll()[PINNED];
+  return pins && typeof pins === 'object' && !Array.isArray(pins) ? pins : {};
+}
+
+/** `{ kind, lane, model, account }` for the kind, or null when it is on auto. */
+export function getMediaPin(kind) {
+  const key = text(kind);
+  if (!MEDIA_KINDS.includes(key)) return null;
+  const row = readPins()[key];
+  const lane = text(row?.lane);
+  return lane ? { kind: key, lane, model: text(row?.model), account: text(row?.account) } : null;
+}
+
+export function getMediaPins() {
+  return Object.fromEntries(MEDIA_KINDS.map((kind) => [kind, getMediaPin(kind)]));
+}
+
+/** Pin one kind to a lane/model/account; an empty `lane` returns it to auto. */
+export function setMediaPin({ kind, lane, model, account } = {}) {
+  const key = text(kind);
+  if (!MEDIA_KINDS.includes(key)) throw new TypeError(`kind must be one of ${MEDIA_KINDS.join(', ')}`);
+  const laneId = text(lane);
+  const { [key]: _previous, ...others } = readPins();
+  const pins = laneId ? { ...others, [key]: { lane: laneId, model: text(model), account: text(account) } } : others;
+  const path = defaultsPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeJsonAtomicSync(path, { ...readAll(), [PINNED]: pins });
+  return getMediaPin(key);
+}
+
 /** Remember the lane (and model) for one kind. `model` may be empty: the lane default then applies. */
 export function setMediaDefault({ kind, lane, model } = {}) {
   const key = text(kind);

package/src/runtime/media/jobs.mjs

@@ -8,7 +8,8 @@
  */
 import { randomUUID } from 'node:crypto';
 import { MAX_GENERATED_MEDIA_BYTES } from './download.mjs';
-import { mediaError, resolveMediaRequest } from './lanes.mjs';
+import { mediaError, mediaLaneAccountProvider, resolveMediaRequest } from './lanes.mjs';
+import { withProviderAccount } from '../shared/provider-auth-binding.mjs';
 import { saveMediaAsset } from './store.mjs';
 import { setMediaDefault } from './defaults.mjs';
 import { recordMediaUsage } from './media-usage.mjs';
@@ -77,8 +78,17 @@ async function runAdapter({ lane, kind, model, requestModel, prompt, options, re
 /**
  * Validate + start one generation. Returns the initial snapshot immediately;
  * the caller polls getMediaJob for progress and the finished asset id.
+ * `account` runs the whole job (catalog check, credentials, adapter) as that
+ * connected account of the lane's provider, whatever the chat is using; an
+ * account that cannot serve the call fails it, never another account.
  */
-export async function startMediaJob({
+export async function startMediaJob(input = {}) {
+  const account = String(input?.account || '').trim();
+  const provider = account ? mediaLaneAccountProvider(input.lane) : '';
+  return provider ? withProviderAccount(provider, account, () => beginMediaJob(input)) : beginMediaJob(input);
+}
+
+async function beginMediaJob({
   lane: laneId,
   kind,
   model,

package/src/runtime/media/lanes.mjs

@@ -8,6 +8,7 @@
  * an unauthenticated lane fails closed.
  */
 import { hasAgentApiKey } from '../shared/provider-api-key.mjs';
+import { ACCOUNT_PROVIDERS } from '../shared/provider-accounts.mjs';
 // Credential probes are file-level checks: the catalog must not drag the whole
 // provider graph in just to render lane availability.
 import {
@@ -64,6 +65,7 @@ const LANES = Object.freeze([
     image: Object.freeze({
       controls: Object.freeze({
         maxReferences: 5,
+        background: Object.freeze(['auto', 'transparent', 'opaque']),
       }),
     }),
   }),
@@ -100,6 +102,13 @@ const LANES = Object.freeze([
 
 const LANE_BY_ID = new Map(LANES.map((lane) => [lane.id, lane]));
 
+/** The provider whose connected accounts a lane can generate through, or ''
+ *  for a lane that authenticates with a single API key. */
+export function mediaLaneAccountProvider(laneId) {
+  const provider = LANE_BY_ID.get(String(laneId || '').trim())?.auth.provider;
+  return ACCOUNT_PROVIDERS.includes(provider) ? provider : '';
+}
+
 const OAUTH_PROBES = Object.freeze({
   'grok-oauth': hasGrokOAuthCredentials,
   'openai-oauth': hasOpenAIOAuthCredentials,
@@ -143,6 +152,9 @@ export function createMediaLaneCatalog({ loadModels = loadMediaModels, authentic
       authType: lane.auth.type,
       authProvider: lane.auth.provider,
       authenticated: signedIn,
+      // What the lane can generate once signed in; `kinds` lists only what its
+      // live catalog offers right now.
+      supportedKinds: MEDIA_KINDS.filter((kind) => lane[kind]),
       kinds: [],
       image: null,
       video: null,

package/src/runtime/media/tool-defs.mjs

@@ -31,7 +31,7 @@ export const TOOL_DEFS = [
         lane: {
           type: 'string',
           description:
-            'Lane id from list; omitted = the lane the user last chose for the kind (Studio selection or last generation), else the first signed-in lane.',
+            'Lane id from list; pass it when the user names a source. Omitted = the lane the user last chose for the kind, else the default signed-in lane.',
         },
         model: {
           type: 'string',
@@ -44,10 +44,21 @@ export const TOOL_DEFS = [
           description:
             'generate: output file (png/jpg/mp4); relative to the project. status: copy a finished asset here.',
         },
-        aspect: { type: 'string', description: 'Aspect ratio, e.g. 16:9, 9:16, 1:1; must be one the model lists.' },
-        resolution: { type: 'string', description: 'Model resolution token from list (1k, 2k, 720p, 1080p).' },
+        aspect: {
+          type: 'string',
+          description: 'Aspect ratio, e.g. 16:9, 9:16, 1:1; only when the model lists aspectRatio, else omit.',
+        },
+        resolution: {
+          type: 'string',
+          description: 'Resolution token (1k, 2k, 720p, 1080p); only when the model lists it, else omit.',
+        },
         duration: { type: 'number', description: "video: seconds, within the model's listed durations." },
-        quality: { type: 'string', description: 'Quality token when the model lists one.' },
+        quality: { type: 'string', description: 'Quality token; only when the model lists one, else omit.' },
+        background: {
+          type: 'string',
+          enum: ['auto', 'transparent', 'opaque'],
+          description: 'image: transparent for real alpha; only when the model lists background, else omit.',
+        },
         references: {
           type: 'array',
           items: { type: 'string' },

package/src/runtime/media/tool.mjs

@@ -8,6 +8,7 @@ import { MEDIA_ACTIONS, MEDIA_KINDS } from './tool-defs.mjs';
 import { clean } from '../shared/clean.mjs';
 
 const POLL_MS = 750;
+const DEFAULT_LANE = 'openai-oauth';
 const TIMEOUT_MS = Object.freeze({ image: 180_000, video: 900_000 });
 // OpenAI's image lane takes pixel sizes, not ratios; the placement still speaks in ratios.
 const OPENAI_SIZE = Object.freeze({
@@ -36,6 +37,7 @@ async function mediaGraph(deps) {
     jobs: await import('./jobs.mjs'),
     store: await import('./store.mjs'),
     defaults: await import('./defaults.mjs'),
+    accounts: await import('../shared/provider-auth-binding.mjs'),
   };
   return graph;
 }
@@ -130,8 +132,9 @@ export function listMediaCatalog(lanes, { kind = '', model = '' } = {}, remember
 
 /**
  * Lane for a generate: the requested one, else the lane the user last chose
- * for this kind (Studio selection or last generation), else the first
- * signed-in lane. `laneSource` tells the caller which of the three applied.
+ * for this kind (Studio selection or last generation), else the signed-in
+ * ChatGPT-subscription lane, else the first signed-in lane. `laneSource` is
+ * `first` for either default.
  */
 function pickLane(lanes, kind, requested, remembered = null) {
   const available = lanes.filter((lane) => lane.authenticated && lane.kinds.includes(kind));
@@ -153,9 +156,8 @@ function pickLane(lanes, kind, requested, remembered = null) {
     );
   }
   const rememberedLane = remembered?.lane ? available.find((entry) => entry.id === remembered.lane) : null;
-  return rememberedLane
-    ? { lane: rememberedLane, laneSource: 'remembered' }
-    : { lane: available[0], laneSource: 'first' };
+  if (rememberedLane) return { lane: rememberedLane, laneSource: 'remembered' };
+  return { lane: available.find((entry) => entry.id === DEFAULT_LANE) || available[0], laneSource: 'first' };
 }
 
 function readRemembered(defaults, kind) {
@@ -166,6 +168,14 @@ function readRemembered(defaults, kind) {
   }
 }
 
+function readPin(defaults, kind) {
+  try {
+    return defaults?.getMediaPin?.(kind) || null;
+  } catch {
+    return null;
+  }
+}
+
 function allowed(controls, key) {
   const list = controls?.[key];
   return Array.isArray(list) && list.length ? list : null;
@@ -185,9 +195,13 @@ export function buildOptions(
   lane,
   kind,
   controls,
-  { aspect = '', resolution = '', duration = null, quality = '' } = {}
+  { aspect = '', resolution = '', duration = null, quality = '', background = '' } = {}
 ) {
   const options = {};
+  if (background) {
+    validateChoice(controls, 'background', background, 'background');
+    if (background !== 'auto') options.background = background;
+  }
   if (lane.id === 'openai-oauth') {
     if (!allowed(controls, 'size')) {
       if ([aspect, resolution, quality].some((value) => value && value !== 'auto')) {
@@ -291,9 +305,21 @@ async function generate(args, { cwd, signal, deps, sessionId, sourceType }) {
   const requestedPath = clean(args.path);
   if (!requestedPath) throw new MediaToolError('generate requires path: where to write the file');
   const target = fullPath(requestedPath, cwd);
-  const { lanes, jobs, store, defaults } = await mediaGraph(deps);
-  const remembered = readRemembered(defaults, kind);
-  const { lane, laneSource } = pickLane(await lanes.listMediaLanes(), kind, clean(args.lane), remembered);
+  const { lanes, jobs, store, defaults, accounts } = await mediaGraph(deps);
+  // A generator the chat names (lane or model) wins for this call; otherwise
+  // the pinned default for the kind applies, and with none the remembered
+  // choice / ordered default. A pin never falls back: its lane, model and
+  // account errors surface as they are.
+  const pin = clean(args.lane) || clean(args.model) ? null : readPin(defaults, kind);
+  const remembered = pin ? null : readRemembered(defaults, kind);
+  const accountProvider = pin?.account ? lanes.mediaLaneAccountProvider?.(pin.lane) || '' : '';
+  const listLanes = () =>
+    accountProvider
+      ? accounts.withProviderAccount(accountProvider, pin.account, () => lanes.listMediaLanes())
+      : lanes.listMediaLanes();
+  const picked = pickLane(await listLanes(), kind, pin ? pin.lane : clean(args.lane), remembered);
+  const { lane } = picked;
+  const laneSource = pin ? 'pinned' : picked.laneSource;
   const spec = lane[kind];
   // The remembered model only applies on the remembered lane and only while
   // that lane still lists it; otherwise the lane default is the safe choice.
@@ -301,7 +327,7 @@ async function generate(args, { cwd, signal, deps, sessionId, sourceType }) {
     laneSource === 'remembered' && remembered.model && spec.models.some((entry) => entry.id === remembered.model)
       ? remembered.model
       : '';
-  const modelId = clean(args.model) || rememberedModel || spec.defaultModel;
+  const modelId = clean(args.model) || pin?.model || rememberedModel || spec.defaultModel;
   const model = modelControls(lane, kind, modelId);
   if (!model)
     throw new MediaToolError(`model "${modelId}" is not available on ${lane.id} for ${kind}`, {
@@ -312,6 +338,7 @@ async function generate(args, { cwd, signal, deps, sessionId, sourceType }) {
     resolution: clean(args.resolution),
     duration: args.duration ?? null,
     quality: clean(args.quality),
+    background: clean(args.background),
   });
   const references = await readReferences(args.references, cwd, model.controls);
   const started = await jobs.startMediaJob({
@@ -323,6 +350,7 @@ async function generate(args, { cwd, signal, deps, sessionId, sourceType }) {
     references,
     sessionId,
     sourceType,
+    ...(accountProvider ? { account: pin.account } : {}),
   });
   const base = { lane: lane.id, model: modelId, laneSource, options, referenceCount: references.length, prompt };
   if (args.wait === false) {
@@ -396,11 +424,12 @@ export async function executeMediaTool(
         ...listMediaCatalog(
           await lanes.listMediaLanes(),
           { kind, model: clean(args.model) },
-          readRemembered(defaults, kind)
+          readPin(defaults, kind) || readRemembered(defaults, kind)
         ),
       });
     }
-    if (action === 'generate') return mediaToolResult(await generate(args, { cwd, signal, deps, sessionId, sourceType }));
+    if (action === 'generate')
+      return mediaToolResult(await generate(args, { cwd, signal, deps, sessionId, sourceType }));
     if (action === 'status') return mediaToolResult(await status(args, { cwd, deps }));
     return mediaToolResult(await cancel(args, { deps }));
   } catch (error) {