mixdog 0.9.69 → 0.9.71

package/src/runtime/media/adapters/xai-media.mjs

@@ -0,0 +1,116 @@
+/**
+ * xAI Imagine adapter (images + video) for the `grok-oauth` and `xai` lanes.
+ *
+ * Both lanes speak the same api.x.ai contract; only the bearer differs. Video
+ * is a submit + poll job: POST /videos/generations returns a request id and the
+ * poll route answers 202 while pending, 200 with a signed URL when done.
+ */
+import { resolveXaiAuth } from '../auth.mjs';
+import { mediaError } from '../lanes.mjs';
+import { upstreamError } from '../upstream-error.mjs';
+
+const POLL_INTERVAL_MS = 4_000;
+const START_TIMEOUT_MS = 60_000;
+const TOTAL_TIMEOUT_MS = 900_000;
+
+async function readError(res) {
+  const text = await res.text().catch(() => '');
+  return text.slice(0, 400);
+}
+
+function sizeParams({ aspectRatio, resolution }) {
+  const params = {};
+  const aspect = String(aspectRatio || 'auto');
+  if (aspect && aspect !== 'auto') params.aspect_ratio = aspect;
+  const res = String(resolution || '').toLowerCase();
+  if (res === '1k' || res === '2k') params.resolution = res;
+  return params;
+}
+
+/** Reference images ride as data URLs — xAI accepts them in place of a host. */
+function referenceUrl(reference) {
+  const data = String(reference?.base64 || '');
+  if (data.startsWith('data:')) return data;
+  return `data:${reference?.mime || 'image/png'};base64,${data}`;
+}
+
+export async function generateImage({ lane, model, prompt, options = {}, references = [], signal }) {
+  const { baseURL, token } = await resolveXaiAuth(lane);
+  const refs = references.map(referenceUrl).map((url) => ({ type: 'image_url', url }));
+  const body = {
+    model,
+    prompt,
+    n: 1,
+    response_format: 'b64_json',
+    // One reference edits that image; several composite into a new one.
+    ...(refs.length === 1 ? { image: refs[0] } : refs.length > 1 ? { images: refs } : {}),
+    ...sizeParams(options),
+  };
+  const route = refs.length ? 'images/edits' : 'images/generations';
+  const res = await fetch(`${baseURL}/${route}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+    signal,
+  });
+  if (!res.ok) throw upstreamError('xAI image', res.status, await readError(res));
+  const data = await res.json();
+  const entry = data?.data?.[0];
+  if (!entry?.b64_json) throw mediaError('xAI returned no image data', 'MEDIA_EMPTY_RESULT', 502);
+  return {
+    bytes: Buffer.from(entry.b64_json, 'base64'),
+    mime: entry.mime_type || 'image/png',
+    revisedPrompt: entry.revised_prompt || null,
+  };
+}
+
+export async function generateVideo({ lane, model, prompt, options = {}, references = [], signal, onProgress }) {
+  const { baseURL, token } = await resolveXaiAuth(lane);
+  const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` };
+  const duration = Math.min(15, Math.max(1, Math.trunc(Number(options.duration) || 5)));
+  const resolution = ['480p', '720p', '1080p'].includes(options.resolution) ? options.resolution : '480p';
+  const body = { model, prompt, duration, resolution };
+  const aspect = String(options.aspectRatio || 'auto');
+  if (aspect && aspect !== 'auto') body.aspect_ratio = aspect;
+  // Mode is inferred from the reference count: 1 = image-to-video,
+  // 2+ = reference-to-video (capped at the documented 7).
+  const refs = references.slice(0, 7).map(referenceUrl);
+  if (refs.length === 1) body.image = { url: refs[0] };
+  else if (refs.length > 1) body.reference_images = refs.map((url) => ({ url }));
+
+  const started = await fetch(`${baseURL}/videos/generations`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.any([signal, AbortSignal.timeout(START_TIMEOUT_MS)].filter(Boolean)),
+  });
+  if (!started.ok) throw upstreamError('xAI video', started.status, await readError(started));
+  const startData = await started.json();
+  const requestId = startData?.request_id || startData?.id;
+  if (!requestId) throw mediaError('xAI video start returned no request id', 'MEDIA_UPSTREAM_FAILED', 502);
+
+  const deadline = Date.now() + TOTAL_TIMEOUT_MS;
+  for (;;) {
+    if (signal?.aborted) throw mediaError('canceled', 'MEDIA_CANCELED', 499);
+    if (Date.now() > deadline) throw mediaError('xAI video poll budget exceeded', 'MEDIA_TIMEOUT', 504);
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    const poll = await fetch(`${baseURL}/videos/${requestId}`, { headers, signal });
+    if (!poll.ok && poll.status !== 202) throw upstreamError('xAI video poll', poll.status, await readError(poll));
+    const data = await poll.json().catch(() => ({}));
+    if (typeof data?.progress === 'number' && typeof onProgress === 'function') onProgress(data.progress);
+    if (data?.status === 'done') {
+      const url = data?.video?.url;
+      if (!url) throw mediaError('xAI video finished without a URL', 'MEDIA_EMPTY_RESULT', 502);
+      const file = await fetch(url, { signal });
+      if (!file.ok) throw mediaError(`xAI video download failed (${file.status})`, 'MEDIA_UPSTREAM_FAILED', file.status);
+      return {
+        bytes: Buffer.from(await file.arrayBuffer()),
+        mime: 'video/mp4',
+        durationSeconds: Number(data?.video?.duration) || duration,
+      };
+    }
+    if (data?.status === 'failed' || data?.status === 'expired') {
+      throw mediaError(`xAI video ${data.status}${data?.error?.code ? `: ${data.error.code}` : ''}`, 'MEDIA_UPSTREAM_FAILED', 502);
+    }
+  }
+}

package/src/runtime/media/auth.mjs

@@ -0,0 +1,51 @@
+/**
+ * Credential resolution for media lanes.
+ *
+ * OAuth lanes reuse the chat providers' token stores (including their refresh
+ * paths) so the Studio never holds a second copy of a session. API-key lanes
+ * read the same keychain-backed store the agent providers use.
+ */
+import { getAgentApiKey } from '../shared/provider-api-key.mjs';
+
+export { hasGrokOAuthCredentials } from '../agent/orchestrator/providers/oauth-credential-probes.mjs';
+
+const XAI_BASE_URL = 'https://api.x.ai/v1';
+
+/**
+ * Bearer for the xAI media endpoints. `grok-oauth` refreshes through the chat
+ * provider; `xai` uses the stored API key. Both hit the same api.x.ai routes.
+ */
+export async function resolveXaiAuth(laneId) {
+  if (laneId === 'xai') {
+    const key = getAgentApiKey('xai');
+    if (!key) {
+      const err = new Error('xAI API key is not configured');
+      err.code = 'MEDIA_LANE_UNAUTHENTICATED';
+      err.status = 401;
+      throw err;
+    }
+    return { baseURL: XAI_BASE_URL, token: key };
+  }
+  const { GrokOAuthProvider } = await import('../agent/orchestrator/providers/grok-oauth.mjs');
+  const provider = new GrokOAuthProvider({});
+  const tokens = await provider.ensureAuth();
+  return { baseURL: XAI_BASE_URL, token: tokens.access_token };
+}
+
+/** Codex (ChatGPT OAuth) auth record: access token + account id for headers. */
+export async function resolveCodexAuth() {
+  const { OpenAIOAuthProvider } = await import('../agent/orchestrator/providers/openai-oauth.mjs');
+  const provider = new OpenAIOAuthProvider({});
+  return await provider.ensureAuth();
+}
+
+export function resolveGeminiKey() {
+  const key = getAgentApiKey('gemini');
+  if (!key) {
+    const err = new Error('Gemini API key is not configured');
+    err.code = 'MEDIA_LANE_UNAUTHENTICATED';
+    err.status = 401;
+    throw err;
+  }
+  return key;
+}

package/src/runtime/media/index.mjs

@@ -0,0 +1,18 @@
+/**
+ * Media studio surface (image / video generation).
+ *
+ * Single entry point for the session runtime: lane catalog, job control, and
+ * the on-disk asset store. Adapters are imported lazily by the job runner so a
+ * boot that never generates never pays for them.
+ */
+export { MEDIA_KINDS, listMediaLanes, getMediaLane } from './lanes.mjs';
+export { startMediaJob, getMediaJob, listMediaJobs, cancelMediaJob } from './jobs.mjs';
+export {
+  listMediaAssets,
+  readMediaAsset,
+  resolveMediaFile,
+  deleteMediaAsset,
+  mediaAssetPath,
+  openMediaAsset,
+  openMediaFolder,
+} from './store.mjs';

package/src/runtime/media/jobs.mjs

@@ -0,0 +1,174 @@
+/**
+ * Media generation jobs.
+ *
+ * Image lanes answer in one request, video lanes submit + poll for minutes, so
+ * both run as background jobs with a polled snapshot instead of a blocking
+ * call. The desktop reads snapshots over the normal capability bridge; nothing
+ * here streams, which keeps a long video job independent of window lifetime.
+ */
+import { randomUUID } from 'crypto';
+import { mediaError, resolveMediaRequest } from './lanes.mjs';
+import { saveMediaAsset } from './store.mjs';
+
+const JOBS = new Map();
+// Finished jobs stay readable for a while so a slow poller still sees the
+// terminal state, then drop out to bound memory.
+const TERMINAL_TTL_MS = 10 * 60_000;
+const MAX_PROMPT_CHARS = 8_000;
+
+function snapshot(job) {
+  return {
+    id: job.id,
+    status: job.status,
+    kind: job.kind,
+    lane: job.lane,
+    model: job.model,
+    prompt: job.prompt,
+    options: job.options,
+    progress: job.progress,
+    assetId: job.assetId,
+    error: job.error,
+    errorCode: job.errorCode,
+    startedAt: job.startedAt,
+    endedAt: job.endedAt,
+  };
+}
+
+function sweep() {
+  const now = Date.now();
+  for (const [id, job] of JOBS) {
+    if (job.endedAt && now - job.endedAt > TERMINAL_TTL_MS) JOBS.delete(id);
+  }
+}
+
+async function runAdapter({ lane, kind, model, prompt, options, references, signal, onProgress }) {
+  if (lane.id === 'grok-oauth' || lane.id === 'xai') {
+    const adapter = await import('./adapters/xai-media.mjs');
+    return kind === 'video'
+      ? await adapter.generateVideo({ lane: lane.id, model, prompt, options, references, signal, onProgress })
+      : await adapter.generateImage({ lane: lane.id, model, prompt, options, references, signal });
+  }
+  if (lane.id === 'openai-oauth') {
+    const adapter = await import('./adapters/codex-image.mjs');
+    return await adapter.generateImage({ model, prompt, options, references, signal });
+  }
+  if (lane.id === 'gemini') {
+    if (kind === 'video') {
+      const adapter = await import('./adapters/gemini-video.mjs');
+      return await adapter.generateVideo({ model, prompt, options, references, signal, onProgress });
+    }
+    const adapter = await import('./adapters/gemini-image.mjs');
+    return await adapter.generateImage({ model, prompt, options, references, signal });
+  }
+  throw mediaError(`lane "${lane.id}" has no adapter`, 'MEDIA_LANE_UNKNOWN');
+}
+
+/**
+ * Validate + start one generation. Returns the initial snapshot immediately;
+ * the caller polls getMediaJob for progress and the finished asset id.
+ */
+export function startMediaJob({ lane: laneId, kind, model, prompt, options = {}, references = [] } = {}) {
+  const text = String(prompt || '').trim();
+  if (!text) throw mediaError('prompt is required', 'MEDIA_PROMPT_REQUIRED');
+  if (text.length > MAX_PROMPT_CHARS) throw mediaError('prompt is too long', 'MEDIA_PROMPT_TOO_LONG');
+  const resolved = resolveMediaRequest({ lane: laneId, kind, model });
+  // Reference images: the MODEL publishes its own cap (Veo takes one start
+  // frame, Grok ref2v takes seven), so the bound follows the resolved model.
+  const modelEntry = resolved.spec.models.find((entry) => entry.id === resolved.model);
+  const maxRefs = Number(
+    modelEntry?.controls?.maxReferences ?? resolved.spec.controls?.maxReferences ?? 0,
+  ) || (resolved.kind === 'video' ? 7 : 5);
+  const refs = (Array.isArray(references) ? references : [])
+    .filter((ref) => typeof ref?.base64 === 'string' && ref.base64.length > 0)
+    .slice(0, maxRefs)
+    .map((ref) => ({ base64: ref.base64, mime: String(ref.mime || 'image/png') }));
+  sweep();
+
+  const controller = new AbortController();
+  const job = {
+    id: randomUUID(),
+    status: 'running',
+    kind: resolved.kind,
+    lane: resolved.lane.id,
+    model: resolved.model,
+    prompt: text,
+    options: { ...options },
+    referenceCount: refs.length,
+    progress: 0,
+    assetId: null,
+    error: null,
+    errorCode: null,
+    startedAt: Date.now(),
+    endedAt: null,
+    controller,
+  };
+  JOBS.set(job.id, job);
+
+  (async () => {
+    try {
+      const result = await runAdapter({
+        lane: resolved.lane,
+        kind: resolved.kind,
+        model: resolved.model,
+        prompt: text,
+        options,
+        references: refs,
+        signal: controller.signal,
+        onProgress: (value) => {
+          const raw = Number(value);
+          if (!Number.isFinite(raw)) return;
+          // Lanes report either a 0-1 fraction or a percentage, and a poll can
+          // come back stale — normalize and never let the rail walk backwards.
+          const next = Math.round(Math.max(0, Math.min(100, raw > 1 ? raw : raw * 100)));
+          if (next > job.progress) job.progress = next;
+        },
+      });
+      const asset = saveMediaAsset({
+        kind: resolved.kind,
+        lane: resolved.lane.id,
+        model: resolved.model,
+        prompt: text,
+        options: job.options,
+        mime: result.mime,
+        bytes: result.bytes,
+        meta: {
+          ...(result.revisedPrompt ? { revisedPrompt: result.revisedPrompt } : {}),
+          ...(result.durationSeconds ? { durationSeconds: result.durationSeconds } : {}),
+        },
+      });
+      job.assetId = asset.id;
+      job.progress = 100;
+      job.status = 'done';
+    } catch (err) {
+      const canceled = controller.signal.aborted || err?.code === 'MEDIA_CANCELED' || err?.name === 'AbortError';
+      job.status = canceled ? 'canceled' : 'failed';
+      job.error = canceled ? 'canceled' : String(err?.message || err).slice(0, 500);
+      job.errorCode = err?.code || null;
+    } finally {
+      job.endedAt = Date.now();
+    }
+  })();
+
+  return snapshot(job);
+}
+
+export function getMediaJob(id) {
+  const job = JOBS.get(String(id || ''));
+  return job ? snapshot(job) : null;
+}
+
+export function listMediaJobs() {
+  sweep();
+  return [...JOBS.values()]
+    .sort((a, b) => b.startedAt - a.startedAt)
+    .map(snapshot);
+}
+
+export function cancelMediaJob(id) {
+  const job = JOBS.get(String(id || ''));
+  if (!job) return { id, canceled: false };
+  if (job.status === 'running') {
+    try { job.controller.abort(); } catch {}
+  }
+  return { id: job.id, canceled: job.status === 'running' };
+}

package/src/runtime/media/lanes.mjs

@@ -0,0 +1,230 @@
+/**
+ * Media generation lanes (image / video).
+ *
+ * A lane is one credential path we can actually generate with. Auth state is
+ * resolved from the SAME stores the chat providers use (OAuth token stores and
+ * the keychain-backed API keys), so the Studio only ever offers lanes the user
+ * already signed in to. No lane owns a fallback to another lane's credential —
+ * an unauthenticated lane fails closed.
+ */
+import { getAgentApiKey } from '../shared/provider-api-key.mjs';
+// Credential probes are file-level checks: the catalog must not drag the whole
+// provider graph in just to render lane availability.
+import {
+  hasGrokOAuthCredentials,
+  hasOpenAIOAuthCredentials,
+} from '../agent/orchestrator/providers/oauth-credential-probes.mjs';
+
+export const MEDIA_KINDS = Object.freeze(['image', 'video']);
+
+const GROK_IMAGE_MODELS = Object.freeze([
+  Object.freeze({ id: 'grok-imagine-image', label: 'Imagine Image' }),
+  Object.freeze({ id: 'grok-imagine-image-quality', label: 'Imagine Image Q' }),
+]);
+// Per-model control overrides: video contracts differ per model (fixed clip
+// lengths on Veo, 1080p only on Grok 1.5, no length knob on Omni), so each
+// entry carries what it actually accepts instead of one lane-wide guess.
+const GROK_VIDEO_MODELS = Object.freeze([
+  Object.freeze({
+    id: 'grok-imagine-video',
+    label: 'Imagine Video',
+    controls: Object.freeze({ resolution: Object.freeze(['480p', '720p']) }),
+  }),
+]);
+// grok-imagine-video-1.5 is intentionally absent: upstream rejects prompt-only
+// text-to-video on it ("Text-to-video is not supported for this model"), and it
+// only works through an image/reference input we do not accept yet.
+
+// Aspect/resolution vocabularies are lane-native: xAI takes aspect_ratio +
+// resolution, Gemini/Codex take pixel sizes. The UI renders whatever the lane
+// declares instead of inventing a cross-provider size model.
+const GROK_ASPECTS = Object.freeze(['auto', '1:1', '16:9', '9:16', '4:3', '3:4', '3:2', '2:3']);
+
+const LANES = Object.freeze([
+  Object.freeze({
+    id: 'grok-oauth',
+    label: 'Grok Imagine (OAuth)',
+    auth: Object.freeze({ type: 'oauth', provider: 'grok-oauth' }),
+    image: Object.freeze({
+      models: GROK_IMAGE_MODELS,
+      defaultModel: 'grok-imagine-image',
+      controls: Object.freeze({ aspectRatio: GROK_ASPECTS, resolution: Object.freeze(['1k', '2k']), maxReferences: 5 }),
+    }),
+    video: Object.freeze({
+      models: GROK_VIDEO_MODELS,
+      defaultModel: 'grok-imagine-video',
+      controls: Object.freeze({
+        aspectRatio: GROK_ASPECTS,
+        resolution: Object.freeze(['480p', '720p', '1080p']),
+        durationRange: Object.freeze([1, 15]),
+        // 1 ref = image-to-video, 2-7 = reference-to-video.
+        maxReferences: 7,
+      }),
+    }),
+  }),
+  Object.freeze({
+    id: 'xai',
+    label: 'Grok Imagine (API key)',
+    auth: Object.freeze({ type: 'api-key', provider: 'xai' }),
+    image: Object.freeze({
+      models: GROK_IMAGE_MODELS,
+      defaultModel: 'grok-imagine-image',
+      controls: Object.freeze({ aspectRatio: GROK_ASPECTS, resolution: Object.freeze(['1k', '2k']), maxReferences: 5 }),
+    }),
+    video: Object.freeze({
+      models: GROK_VIDEO_MODELS,
+      defaultModel: 'grok-imagine-video',
+      controls: Object.freeze({
+        aspectRatio: GROK_ASPECTS,
+        resolution: Object.freeze(['480p', '720p', '1080p']),
+        durationRange: Object.freeze([1, 15]),
+        maxReferences: 7,
+      }),
+    }),
+  }),
+  Object.freeze({
+    id: 'openai-oauth',
+    label: 'ChatGPT Image (OAuth)',
+    auth: Object.freeze({ type: 'oauth', provider: 'openai-oauth' }),
+    image: Object.freeze({
+      // The hosted image_generation tool runs on the Codex responses backend,
+      // so the id is a chat model driving the tool. The catalog exposes it as
+      // an IMAGE choice (quality vs fast) — listing raw chat models here read
+      // as "why is a chat model in an image picker".
+      models: Object.freeze([
+        Object.freeze({ id: 'gpt-5.6-sol', label: 'GPT Image' }),
+        Object.freeze({ id: 'gpt-5.4-mini', label: 'GPT Image Fast' }),
+      ]),
+      defaultModel: 'gpt-5.6-sol',
+      controls: Object.freeze({
+        size: Object.freeze(['auto', '1024x1024', '1536x1024', '1024x1536']),
+        quality: Object.freeze(['auto', 'low', 'medium', 'high']),
+        maxReferences: 5,
+      }),
+    }),
+  }),
+  Object.freeze({
+    id: 'gemini',
+    label: 'Gemini Image (API key)',
+    auth: Object.freeze({ type: 'api-key', provider: 'gemini' }),
+    image: Object.freeze({
+      models: Object.freeze([
+        Object.freeze({ id: 'gemini-3-pro-image', label: 'Nano Banana Pro' }),
+        Object.freeze({ id: 'gemini-3.1-flash-image', label: 'Nano Banana 2' }),
+        Object.freeze({ id: 'gemini-2.5-flash-image', label: 'Nano Banana 2.5' }),
+      ]),
+      defaultModel: 'gemini-3.1-flash-image',
+      controls: Object.freeze({
+        aspectRatio: Object.freeze(['auto', '1:1', '16:9', '9:16', '4:3', '3:4']),
+        // Reference caps the image edit path at 3 inline references.
+        maxReferences: 3,
+      }),
+    }),
+    video: Object.freeze({
+      // Omni Flash answers inline on the Interactions API; the Veo trio runs as
+      // a long-running predict. Both are paid-tier only on this key.
+      models: Object.freeze([
+        Object.freeze({
+          id: 'gemini-omni-flash-preview',
+          label: 'Omni Flash',
+          // Omni picks its own clip length; only the frame shape is ours.
+          controls: Object.freeze({
+            resolution: Object.freeze([]),
+            durations: Object.freeze([]),
+            maxReferences: 3,
+          }),
+        }),
+        Object.freeze({ id: 'veo-3.1-fast-generate-preview', label: 'Veo 3.1 Fast' }),
+        Object.freeze({ id: 'veo-3.1-generate-preview', label: 'Veo 3.1' }),
+        Object.freeze({ id: 'veo-3.1-lite-generate-preview', label: 'Veo 3.1 Lite' }),
+      ]),
+      defaultModel: 'gemini-omni-flash-preview',
+      controls: Object.freeze({
+        aspectRatio: Object.freeze(['16:9', '9:16']),
+        resolution: Object.freeze(['720p', '1080p']),
+        // Veo 3.1 accepts discrete clip lengths, not a free range.
+        durations: Object.freeze([4, 6, 8]),
+        // Veo takes a single start frame; Omni overrides this below.
+        maxReferences: 1,
+      }),
+    }),
+  }),
+]);
+
+const LANE_BY_ID = new Map(LANES.map((lane) => [lane.id, lane]));
+
+function laneAuthenticated(lane) {
+  try {
+    if (lane.auth.type === 'api-key') return Boolean(getAgentApiKey(lane.auth.provider));
+    if (lane.auth.provider === 'grok-oauth') return hasGrokOAuthCredentials();
+    if (lane.auth.provider === 'openai-oauth') return hasOpenAIOAuthCredentials();
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+function laneKindView(lane, kind) {
+  const spec = lane[kind];
+  if (!spec) return null;
+  const laneControls = spec.controls || {};
+  return {
+    // Each model publishes its EFFECTIVE controls (lane defaults + its own
+    // overrides) so the UI never offers a knob the model rejects.
+    models: spec.models.map((model) => ({
+      id: model.id,
+      label: model.label,
+      controls: JSON.parse(JSON.stringify({ ...laneControls, ...(model.controls || {}) })),
+    })),
+    defaultModel: spec.defaultModel,
+    controls: JSON.parse(JSON.stringify(laneControls)),
+  };
+}
+
+/** Lane catalog with live auth state; the caller filters on `authenticated`. */
+export function listMediaLanes() {
+  return LANES.map((lane) => ({
+    id: lane.id,
+    label: lane.label,
+    authType: lane.auth.type,
+    authProvider: lane.auth.provider,
+    authenticated: laneAuthenticated(lane),
+    kinds: MEDIA_KINDS.filter((kind) => Boolean(lane[kind])),
+    image: laneKindView(lane, 'image'),
+    video: laneKindView(lane, 'video'),
+  }));
+}
+
+export function getMediaLane(laneId) {
+  return LANE_BY_ID.get(String(laneId || '').trim()) || null;
+}
+
+/**
+ * Resolve + validate a generation request against the lane contract. Throws a
+ * coded error rather than letting an unsupported model reach the network.
+ */
+export function resolveMediaRequest({ lane: laneId, kind, model } = {}) {
+  const kindName = String(kind || '').trim();
+  if (!MEDIA_KINDS.includes(kindName)) {
+    throw mediaError(`unsupported media kind "${kindName}"`, 'MEDIA_KIND_UNSUPPORTED');
+  }
+  const lane = getMediaLane(laneId);
+  if (!lane) throw mediaError(`unknown media lane "${laneId}"`, 'MEDIA_LANE_UNKNOWN');
+  const spec = lane[kindName];
+  if (!spec) throw mediaError(`${lane.id} does not support ${kindName}`, 'MEDIA_KIND_UNSUPPORTED');
+  if (!laneAuthenticated(lane)) {
+    throw mediaError(`${lane.label} is not authenticated — sign in from Settings → Providers first`, 'MEDIA_LANE_UNAUTHENTICATED');
+  }
+  const requested = String(model || '').trim() || spec.defaultModel;
+  if (!spec.models.some((entry) => entry.id === requested)) {
+    throw mediaError(`model "${requested}" is not available on ${lane.id}/${kindName}`, 'MEDIA_MODEL_UNSUPPORTED');
+  }
+  return { lane, kind: kindName, model: requested, spec };
+}
+
+export function mediaError(message, code, status = 400) {
+  const err = new Error(message);
+  err.code = code;
+  err.status = status;
+  return err;
+}