mixdog 0.9.69 → 0.9.71

package/src/runtime/media/renditions.mjs

@@ -0,0 +1,203 @@
+/**
+ * Derived renditions for the media gallery (thumb / display / video poster).
+ *
+ * A gallery tile is ~512px and a detail view never exceeds the viewport, so
+ * the original bytes are the wrong unit of transfer: over the remote link one
+ * full-size still costs more than the entire visible grid. Renditions are
+ * generated once, cached on disk beside the assets, and afterwards read back
+ * as small files.
+ *
+ * sharp (stills) and ffmpeg (video posters) are OPTIONAL. When neither can
+ * produce a rendition this module returns null and the caller reduces the
+ * feature (glyph tile) or explicitly asks for the original. It never silently
+ * substitutes full-size bytes for a thumbnail — that hidden path is exactly
+ * what made the remote gallery slow.
+ */
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+import { resolvePluginData } from '../shared/plugin-paths.mjs';
+
+// maxEdge is the long edge in pixels; quality is the webp setting.
+const SPECS = {
+  thumb: { maxEdge: 512, quality: 70 },
+  display: { maxEdge: 2048, quality: 82 },
+};
+// Probe order when reading a cached rendition: sharp writes webp, the
+// ffmpeg-only poster path writes png.
+const EXTENSION_MIME = { '.webp': 'image/webp', '.png': 'image/png' };
+const POSTER_TIMEOUT_MS = 20_000;
+const MAX_POSTER_BYTES = 32 * 1024 * 1024;
+
+export const MEDIA_VARIANTS = Object.keys(SPECS);
+
+/** Spec for a variant name, or null when the caller asked for the original. */
+export function renditionSpec(variant) {
+  return SPECS[String(variant || '')] || null;
+}
+
+let sharpPromise;
+async function loadSharp() {
+  sharpPromise ??= import('sharp').then((mod) => mod?.default || mod || null, () => null);
+  return sharpPromise;
+}
+
+let ffmpegPromise;
+// The managed voice runtime already installs ffmpeg; reuse it rather than
+// shipping a second copy. MIXDOG_FFMPEG_PATH overrides for hosts that have
+// their own build.
+async function resolveFfmpeg() {
+  ffmpegPromise ??= (async () => {
+    const explicit = String(process.env.MIXDOG_FFMPEG_PATH || '').trim();
+    if (explicit && existsSync(explicit)) return explicit;
+    try {
+      const { resolveVoiceRuntime } = await import('../channels/lib/voice-runtime-fetcher.mjs');
+      const runtime = resolveVoiceRuntime(resolvePluginData());
+      return runtime?.ffmpegPath && existsSync(runtime.ffmpegPath) ? runtime.ffmpegPath : null;
+    } catch {
+      return null;
+    }
+  })();
+  return ffmpegPromise;
+}
+
+function renditionPath(cacheDir, variant, id, extension) {
+  return join(cacheDir, variant, `${id}${extension}`);
+}
+
+function cachedRendition(cacheDir, variant, id) {
+  for (const [extension, mime] of Object.entries(EXTENSION_MIME)) {
+    const path = renditionPath(cacheDir, variant, id, extension);
+    if (existsSync(path)) return { path, mime, bytes: statSync(path).size };
+  }
+  return null;
+}
+
+/** Drop every cached rendition of one asset (called when the asset dies). */
+export function removeRenditions(cacheDir, id) {
+  for (const variant of MEDIA_VARIANTS) {
+    for (const extension of Object.keys(EXTENSION_MIME)) {
+      try { unlinkSync(renditionPath(cacheDir, variant, id, extension)); } catch { /* absent */ }
+    }
+  }
+}
+
+function writeRendition(cacheDir, variant, id, extension, buffer) {
+  const path = renditionPath(cacheDir, variant, id, extension);
+  mkdirSync(dirname(path), { recursive: true });
+  // Stage-then-rename: a reader must never observe a half-written cache file.
+  const staging = `${path}.${process.pid}.tmp`;
+  writeFileSync(staging, buffer);
+  renameSync(staging, path);
+  return { path, mime: EXTENSION_MIME[extension], bytes: buffer.length };
+}
+
+/** Downscale a still (path or buffer) into a webp; null without sharp. */
+async function encodeStill(input, spec) {
+  const sharp = await loadSharp();
+  if (!sharp) return null;
+  try {
+    const buffer = await sharp(input)
+      // EXIF-rotated phone photos would otherwise land sideways in the grid.
+      .rotate()
+      .resize(spec.maxEdge, spec.maxEdge, { fit: 'inside', withoutEnlargement: true })
+      .webp({ quality: spec.quality })
+      .toBuffer();
+    return { extension: '.webp', buffer };
+  } catch {
+    // sharp present but the source is not a decodable image.
+    return null;
+  }
+}
+
+function parseDurationSeconds(text) {
+  const match = /Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/.exec(text || '');
+  if (!match) return 0;
+  const seconds = Number(match[1]) * 3600 + Number(match[2]) * 60 + Number(match[3]);
+  return Number.isFinite(seconds) ? Math.round(seconds) : 0;
+}
+
+/** First frame + duration of a clip, straight from ffmpeg; null when the
+ *  managed runtime is not installed. */
+async function grabVideoFrame(sourcePath, spec) {
+  const ffmpeg = await resolveFfmpeg();
+  if (!ffmpeg) return null;
+  return new Promise((resolve) => {
+    const child = spawn(ffmpeg, [
+      '-hide_banner', '-nostdin',
+      '-i', sourcePath,
+      '-frames:v', '1',
+      // Never upscale a small clip: -2 keeps the height even for the encoder.
+      '-vf', `scale='min(${spec.maxEdge},iw)':-2`,
+      '-f', 'image2', '-vcodec', 'png', 'pipe:1',
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const chunks = [];
+    let total = 0;
+    let stderr = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child.kill(); } catch { /* already gone */ }
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(null), POSTER_TIMEOUT_MS);
+    timer.unref?.();
+    child.stdout.on('data', (chunk) => {
+      total += chunk.length;
+      // A corrupt clip could stream frames forever; the poster is one image.
+      if (total > MAX_POSTER_BYTES) {
+        finish(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    child.on('error', () => finish(null));
+    child.on('close', () => {
+      const buffer = Buffer.concat(chunks);
+      finish(buffer.length ? { buffer, durationSeconds: parseDurationSeconds(stderr) } : null);
+    });
+  });
+}
+
+// Two tiles asking for the same missing rendition must not both encode it.
+const inflight = new Map();
+
+async function generate({ id, kind, sourcePath, variant, spec, cacheDir }) {
+  if (kind === 'video') {
+    // Only the tile-sized poster is worth extracting: a "display" frame would
+    // be a still pretending to be a clip.
+    if (variant !== 'thumb') return null;
+    const frame = await grabVideoFrame(sourcePath, spec);
+    if (!frame) return null;
+    const encoded = await encodeStill(frame.buffer, spec);
+    const written = encoded
+      ? writeRendition(cacheDir, variant, id, encoded.extension, encoded.buffer)
+      : writeRendition(cacheDir, variant, id, '.png', frame.buffer);
+    return { ...written, durationSeconds: frame.durationSeconds };
+  }
+  const encoded = await encodeStill(sourcePath, spec);
+  return encoded ? writeRendition(cacheDir, variant, id, encoded.extension, encoded.buffer) : null;
+}
+
+/**
+ * Cached rendition for one asset, generating it on first use.
+ * Returns `{ path, mime, bytes, durationSeconds? }`, or null when this host
+ * cannot produce it (no sharp / no ffmpeg / undecodable source).
+ */
+export async function ensureRendition({ id, kind, sourcePath, variant, cacheDir }) {
+  const spec = renditionSpec(variant);
+  if (!spec) return null;
+  const cached = cachedRendition(cacheDir, variant, id);
+  if (cached) return cached;
+  const key = `${variant}:${id}`;
+  const pending = inflight.get(key)
+    ?? generate({ id, kind, sourcePath, variant, spec, cacheDir })
+      .catch(() => null)
+      .finally(() => { inflight.delete(key); });
+  inflight.set(key, pending);
+  return pending;
+}

package/src/runtime/media/store.mjs

@@ -0,0 +1,356 @@
+/**
+ * On-disk store for generated media.
+ *
+ * Assets live as real files under <data>/media/assets so nothing large is kept
+ * in memory or in a session transcript; index.json holds the metadata list
+ * (newest first) and is written atomically under a file lock because the
+ * desktop and CLI can generate concurrently.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, statSync } from 'fs';
+import { dirname, join, resolve, sep } from 'path';
+import { randomUUID } from 'crypto';
+import { spawn } from 'child_process';
+import { resolvePluginData } from '../shared/plugin-paths.mjs';
+import { writeJsonAtomicSync, withFileLockSync } from '../shared/atomic-file.mjs';
+import { ensureRendition, removeRenditions, renditionSpec } from './renditions.mjs';
+
+const MAX_INDEX_ENTRIES = 2_000;
+// Renderer transport is base64 over IPC: refuse to inline anything larger.
+const MAX_INLINE_BYTES = 48 * 1024 * 1024;
+
+const EXTENSIONS = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'video/mp4': 'mp4',
+};
+let layoutMigrationChecked = false;
+
+function mediaDir() {
+  return join(resolvePluginData(), 'media');
+}
+
+function assetsDir() {
+  return join(mediaDir(), 'assets');
+}
+
+// Derived tile/detail renditions live beside the assets: they are a rebuildable
+// cache, so they never share the asset tree the user browses.
+function renditionsDir() {
+  return join(mediaDir(), 'renditions');
+}
+
+function indexPath() {
+  return join(mediaDir(), 'index.json');
+}
+
+function indexLockPath() {
+  return `${indexPath()}.lock`;
+}
+
+function ensureDirs() {
+  mkdirSync(assetsDir(), { recursive: true });
+  if (!layoutMigrationChecked) {
+    migrateAssetLayout();
+    layoutMigrationChecked = true;
+  }
+}
+
+function readIndex() {
+  try {
+    const raw = readFileSync(indexPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed?.assets) ? parsed.assets : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeIndex(assets) {
+  writeJsonAtomicSync(indexPath(), { version: 2, assets });
+}
+
+function extensionFor(mime) {
+  return EXTENSIONS[String(mime || '').toLowerCase()] || 'bin';
+}
+
+function folderSegment(value, fallback) {
+  const normalized = String(value || '')
+    .normalize('NFKC')
+    .replace(/[<>:"/\\|?*\u0000-\u001f]/g, '-')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/[. ]+$/g, '')
+    .slice(0, 80);
+  if (!normalized || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(normalized)) {
+    return fallback;
+  }
+  return normalized;
+}
+
+function localDateFolder(createdAt) {
+  const date = new Date(Number(createdAt) || Date.now());
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function organizedAssetFile(entry) {
+  const kind = entry.kind === 'video' ? 'videos' : 'images';
+  const lane = folderSegment(entry.lane, 'unknown-provider');
+  const model = folderSegment(entry.model, 'unknown-model');
+  const date = localDateFolder(entry.createdAt);
+  const id = folderSegment(entry.id, 'asset');
+  return [kind, lane, model, date, `${id}.${extensionFor(entry.mime)}`].join('/');
+}
+
+function storedAssetPath(file) {
+  const root = resolve(assetsDir());
+  const path = resolve(root, String(file || ''));
+  return path === root || path.startsWith(`${root}${sep}`) ? path : null;
+}
+
+/** Move flat v1 assets into kind/provider/model/date folders without losing old indexes. */
+function migrateAssetLayout() {
+  withFileLockSync(indexLockPath(), () => {
+    const current = readIndex();
+    let changed = false;
+    const assets = current.map((entry) => {
+      const targetFile = organizedAssetFile(entry);
+      const sourcePath = storedAssetPath(entry.file);
+      const targetPath = storedAssetPath(targetFile);
+      if (!targetPath) return entry;
+      if (String(entry.file || '').replace(/\\/g, '/') === targetFile) return entry;
+      if (existsSync(targetPath)) {
+        changed = true;
+        return { ...entry, file: targetFile };
+      }
+      if (!sourcePath || !existsSync(sourcePath)) return entry;
+      try {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        renameSync(sourcePath, targetPath);
+        changed = true;
+        return { ...entry, file: targetFile };
+      } catch {
+        return entry;
+      }
+    });
+    if (changed) writeIndex(assets);
+  });
+}
+
+/** Persist one generated artifact and return its index entry. */
+export function saveMediaAsset({ kind, lane, model, prompt, options = {}, mime, bytes, meta = {} }) {
+  ensureDirs();
+  const id = randomUUID();
+  const createdAt = Date.now();
+  const entry = {
+    id,
+    kind,
+    lane,
+    model,
+    prompt: String(prompt || '').slice(0, 4_000),
+    options,
+    mime,
+    bytes: bytes.length,
+    createdAt,
+    ...meta,
+  };
+  const file = organizedAssetFile(entry);
+  const path = storedAssetPath(file);
+  if (!path) throw new Error('invalid media asset path');
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, bytes);
+  entry.file = file;
+  withFileLockSync(indexLockPath(), () => {
+    const assets = [entry, ...readIndex()];
+    const kept = assets.slice(0, MAX_INDEX_ENTRIES);
+    for (const dropped of assets.slice(MAX_INDEX_ENTRIES)) {
+      const droppedPath = storedAssetPath(dropped.file);
+      try { if (droppedPath) unlinkSync(droppedPath); } catch {}
+    }
+    writeIndex(kept);
+  });
+  // The first gallery paint after a generation would otherwise be the one that
+  // pays for the tile rendition; build it now, off the caller's path.
+  void ensureRendition({
+    id: entry.id,
+    kind: entry.kind,
+    sourcePath: path,
+    variant: 'thumb',
+    cacheDir: renditionsDir(),
+  });
+  return entry;
+}
+
+export function listMediaAssets({ limit = 60, offset = 0, kind = null } = {}) {
+  ensureDirs();
+  const all = readIndex().filter((entry) => (kind ? entry.kind === kind : true));
+  const start = Math.max(0, Math.trunc(Number(offset) || 0));
+  const count = Math.min(200, Math.max(1, Math.trunc(Number(limit) || 60)));
+  const assets = all.slice(start, start + count);
+  // Assets generated before this cache existed have no tile rendition, so the
+  // first gallery paint used to wait on an encode per visible tile. Listing is
+  // the earliest moment the host knows WHICH tiles are coming: warm them here,
+  // off the caller's path (ensureRendition dedupes the concurrent request).
+  void prewarmThumbs(assets);
+  return { total: all.length, assets };
+}
+
+// Bounded: the encoder is shared with generation, and a large page must not
+// turn one listing into dozens of parallel sharp/ffmpeg jobs.
+const PREWARM_LIMIT = 24;
+const PREWARM_CONCURRENCY = 2;
+
+async function prewarmThumbs(assets) {
+  const queue = assets.slice(0, PREWARM_LIMIT);
+  const workers = Array.from({ length: PREWARM_CONCURRENCY }, async () => {
+    for (let entry = queue.shift(); entry; entry = queue.shift()) {
+      const path = storedAssetPath(entry.file);
+      if (!path || !existsSync(path)) continue;
+      const rendition = await ensureRendition({
+        id: entry.id,
+        kind: entry.kind,
+        sourcePath: path,
+        variant: 'thumb',
+        cacheDir: renditionsDir(),
+      }).catch(() => null);
+      if (rendition?.durationSeconds) rememberDuration(entry, rendition.durationSeconds);
+    }
+  });
+  await Promise.all(workers).catch(() => {});
+}
+
+export function getMediaAsset(id) {
+  ensureDirs();
+  return readIndex().find((entry) => entry.id === id) || null;
+}
+
+/** Persist a duration probed while building a poster, so the gallery badge
+ *  survives a restart without decoding the clip again. */
+function rememberDuration(entry, durationSeconds) {
+  if (!durationSeconds || entry.durationSeconds === durationSeconds) return;
+  withFileLockSync(indexLockPath(), () => {
+    const assets = readIndex();
+    const row = assets.find((item) => item.id === entry.id);
+    if (!row || row.durationSeconds === durationSeconds) return;
+    row.durationSeconds = durationSeconds;
+    writeIndex(assets);
+  });
+  entry.durationSeconds = durationSeconds;
+}
+
+/** Base64 for the inline (RPC) path. Large files are refused: bytes that big
+ *  belong on the file route, not in a JSON frame. */
+function inlineBase64(path) {
+  const size = statSync(path).size;
+  if (size > MAX_INLINE_BYTES) {
+    const err = new Error('media asset is too large to preview');
+    err.code = 'MEDIA_ASSET_TOO_LARGE';
+    throw err;
+  }
+  return readFileSync(path).toString('base64');
+}
+
+/**
+ * Locate an asset (or one of its renditions) as a FILE — no inlining.
+ *
+ * This is the unit the media routes serve: the client receives a cacheable,
+ * range-able response instead of a base64 payload riding the RPC lane.
+ * `available: false` means this host cannot build the rendition (no sharp /
+ * no ffmpeg); the caller reduces the feature instead of substituting the
+ * original behind the client's back.
+ */
+export async function resolveMediaFile(id, { variant = 'original' } = {}) {
+  const entry = getMediaAsset(id);
+  if (!entry) return null;
+  const path = storedAssetPath(entry.file);
+  if (!path || !existsSync(path)) return null;
+  if (variant === 'original') return { ...entry, variant: 'original', path, available: true };
+  if (!renditionSpec(variant)) throw new Error(`unknown media variant: ${variant}`);
+  const rendition = await ensureRendition({
+    id: entry.id,
+    kind: entry.kind,
+    sourcePath: path,
+    variant,
+    cacheDir: renditionsDir(),
+  });
+  if (!rendition) return { ...entry, variant, path: '', available: false };
+  rememberDuration(entry, rendition.durationSeconds);
+  return {
+    ...entry,
+    ...(rendition.durationSeconds ? { durationSeconds: rendition.durationSeconds } : {}),
+    variant,
+    path: rendition.path,
+    mime: rendition.mime,
+    bytes: rendition.bytes,
+    available: true,
+  };
+}
+
+/**
+ * Inline an asset for the renderer (base64 + mime).
+ *
+ * `variant` selects a derived rendition ('thumb' | 'display'); the original is
+ * read only when it is asked for. A host that cannot build the rendition says
+ * so (`available: false`) instead of quietly shipping full-size bytes — the
+ * caller that can afford them (local IPC) opts in with `allowOriginal`.
+ */
+export async function readMediaAsset(id, { variant = 'original', allowOriginal = false } = {}) {
+  const file = await resolveMediaFile(id, { variant });
+  if (!file) return null;
+  if (file.available) return { ...file, base64: inlineBase64(file.path) };
+  if (!allowOriginal) return { ...file, base64: '' };
+  const original = await resolveMediaFile(id, { variant: 'original' });
+  if (!original) return null;
+  return { ...original, downgraded: true, base64: inlineBase64(original.path) };
+}
+
+export function mediaAssetPath(id) {
+  const entry = getMediaAsset(id);
+  return entry ? storedAssetPath(entry.file) : null;
+}
+
+/**
+ * Hand an asset to the OS viewer. The path is resolved from our own index, so
+ * no caller-supplied path ever reaches the shell.
+ */
+export function openMediaAsset(id) {
+  const path = mediaAssetPath(id);
+  if (!path || !existsSync(path)) return { id, opened: false };
+  return { id, opened: openWithOs(path) };
+}
+
+/** Open the assets directory itself (Studio → folder button). */
+export function openMediaFolder() {
+  ensureDirs();
+  return { path: assetsDir(), opened: openWithOs(assetsDir()) };
+}
+
+function openWithOs(path) {
+  const [command, args] = process.platform === 'win32'
+    ? ['cmd', ['/c', 'start', '', path]]
+    : process.platform === 'darwin'
+      ? ['open', [path]]
+      : ['xdg-open', [path]];
+  const child = spawn(command, args, { detached: true, stdio: 'ignore', windowsHide: true });
+  child.unref();
+  return true;
+}
+
+export function deleteMediaAsset(id) {
+  ensureDirs();
+  let removed = false;
+  withFileLockSync(indexLockPath(), () => {
+    const assets = readIndex();
+    const entry = assets.find((row) => row.id === id);
+    if (!entry) return;
+    const path = storedAssetPath(entry.file);
+    try { if (path) unlinkSync(path); } catch {}
+    removeRenditions(renditionsDir(), id);
+    writeIndex(assets.filter((row) => row.id !== id));
+    removed = true;
+  });
+  return { id, removed };
+}

package/src/runtime/media/store.test.mjs

@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+
+test('media assets are organized by kind, provider, model, and local date while flat files migrate', async () => {
+  const root = mkdtempSync(join(tmpdir(), 'mixdog-media-store-'));
+  const previousDataDir = process.env.MIXDOG_DATA_DIR;
+  process.env.MIXDOG_DATA_DIR = root;
+  const assetsDir = join(root, 'media', 'assets');
+  const createdAt = new Date(2026, 6, 5, 12, 0, 0).getTime();
+  mkdirSync(assetsDir, { recursive: true });
+  writeFileSync(join(assetsDir, 'legacy-image.jpg'), Buffer.from('image'));
+  writeFileSync(join(assetsDir, 'legacy-video.mp4'), Buffer.from('video'));
+  writeFileSync(join(root, 'media', 'index.json'), JSON.stringify({
+    version: 1,
+    assets: [
+      {
+        id: 'legacy-image',
+        file: 'legacy-image.jpg',
+        kind: 'image',
+        lane: 'gemini',
+        model: 'image-alpha',
+        prompt: 'image',
+        options: { aspectRatio: '4:3' },
+        mime: 'image/jpeg',
+        bytes: 5,
+        createdAt,
+      },
+      {
+        id: 'legacy-video',
+        file: 'legacy-video.mp4',
+        kind: 'video',
+        lane: 'grok',
+        model: 'video-beta',
+        prompt: 'video',
+        options: { aspectRatio: '16:9' },
+        mime: 'video/mp4',
+        bytes: 5,
+        createdAt,
+      },
+    ],
+  }));
+
+  try {
+    const store = await import(`./store.mjs?test=${Date.now()}`);
+    const listed = store.listMediaAssets({ limit: 10 }).assets;
+    assert.equal(listed[0].file, 'images/gemini/image-alpha/2026-07-05/legacy-image.jpg');
+    assert.equal(listed[1].file, 'videos/grok/video-beta/2026-07-05/legacy-video.mp4');
+    assert.equal(existsSync(join(assetsDir, ...listed[0].file.split('/'))), true);
+    assert.equal(existsSync(join(assetsDir, ...listed[1].file.split('/'))), true);
+    assert.equal(existsSync(join(assetsDir, 'legacy-image.jpg')), false);
+    assert.equal(
+      (await store.readMediaAsset('legacy-video')).base64,
+      Buffer.from('video').toString('base64'),
+    );
+
+    // A tile-sized rendition is impossible for these stub bytes (and video
+    // needs ffmpeg): the read must REPORT the miss instead of quietly
+    // shipping the original, which is what made the remote gallery slow.
+    const missing = await store.readMediaAsset('legacy-image', { variant: 'thumb' });
+    assert.equal(missing.available, false);
+    assert.equal(missing.base64, '');
+    // Callers that can afford full-size bytes (local IPC) opt in explicitly
+    // and get them labelled as a downgrade.
+    const downgraded = await store.readMediaAsset('legacy-image', {
+      variant: 'thumb',
+      allowOriginal: true,
+    });
+    assert.equal(downgraded.variant, 'original');
+    assert.equal(downgraded.downgraded, true);
+    assert.equal(downgraded.base64, Buffer.from('image').toString('base64'));
+
+    const saved = store.saveMediaAsset({
+      kind: 'video',
+      lane: 'gemini',
+      model: 'veo:3/preview',
+      prompt: 'new clip',
+      options: { aspectRatio: '16:9' },
+      mime: 'video/mp4',
+      bytes: Buffer.from('new-video'),
+    });
+    assert.match(saved.file, /^videos\/gemini\/veo-3-preview\/\d{4}-\d{2}-\d{2}\/[0-9a-f-]+\.mp4$/);
+    assert.equal(existsSync(join(assetsDir, ...saved.file.split('/'))), true);
+    assert.equal(store.deleteMediaAsset(saved.id).removed, true);
+    assert.equal(existsSync(join(assetsDir, ...saved.file.split('/'))), false);
+
+    const persisted = JSON.parse(readFileSync(join(root, 'media', 'index.json'), 'utf8'));
+    assert.equal(persisted.version, 2);
+  } finally {
+    if (previousDataDir === undefined) delete process.env.MIXDOG_DATA_DIR;
+    else process.env.MIXDOG_DATA_DIR = previousDataDir;
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/runtime/media/upstream-error.mjs

@@ -0,0 +1,39 @@
+/**
+ * Upstream failure translation for media lanes.
+ *
+ * A credential can be present and still unusable (exhausted credits, billing
+ * caps, per-account gating). Those come back as raw provider JSON, so the lane
+ * maps them to one legible sentence instead of leaking a wall of upstream text
+ * into the Studio.
+ */
+import { mediaError } from './lanes.mjs';
+
+const CREDIT_HINTS = /credit|spending limit|billing|quota|insufficient|payment/i;
+
+function reason(text) {
+  try {
+    const parsed = JSON.parse(text);
+    const message = parsed?.error?.message || parsed?.error || parsed?.message;
+    return typeof message === 'string' ? message : '';
+  } catch {
+    return '';
+  }
+}
+
+/** Build the error a lane throws for a non-OK upstream response. */
+export function upstreamError(label, status, text) {
+  const detail = reason(text) || String(text || '').slice(0, 300);
+  if (status === 401 || status === 403) {
+    if (CREDIT_HINTS.test(detail)) {
+      return mediaError(`${label}: account has no usable balance — ${detail}`, 'MEDIA_BILLING_BLOCKED', status);
+    }
+    return mediaError(`${label}: authentication rejected — sign in again in Settings → Providers`, 'MEDIA_AUTH_REJECTED', status);
+  }
+  if (status === 402 || CREDIT_HINTS.test(detail)) {
+    return mediaError(`${label}: account has no usable balance — ${detail}`, 'MEDIA_BILLING_BLOCKED', status || 402);
+  }
+  if (status === 429) {
+    return mediaError(`${label}: rate limited — retry in a moment`, 'MEDIA_RATE_LIMITED', 429);
+  }
+  return mediaError(`${label} failed (${status})${detail ? `: ${detail}` : ''}`, 'MEDIA_UPSTREAM_FAILED', status);
+}