mixdog 0.9.69 → 0.9.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.69",
+  "version": "0.9.71",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -85,6 +85,9 @@
     "test:session": "node --test scripts/session-orphan-sweep-test.mjs scripts/interrupted-turn-history-test.mjs scripts/session-heartbeat-lifecycle-test.mjs scripts/remote-transition-order-test.mjs",
     "test:rebindtail": "node --test scripts/forwarder-rebind-tail-test.mjs",
     "test:workflow-editor": "node --test scripts/workflow-id-test.mjs scripts/workflow-pack-editor-test.mjs",
+    "test:route-scope": "node --test scripts/route-scope-isolation-test.mjs",
+    "test:schedule-reload": "node --test scripts/schedule-reload-arm-test.mjs",
+    "test:media": "node --test src/runtime/media/store.test.mjs",
     "failures": "node scripts/tool-failures.mjs",
     "trace:llm": "node scripts/llm-trace-summary.mjs",
     "diag:sessions": "node scripts/session-diag.mjs",

package/src/runtime/agent/orchestrator/session/manager/pending-messages.mjs

@@ -706,8 +706,22 @@ export function enqueueRemotePendingMessage(sessionId, message) {
 }
 
 // Spool-file mtime gate so the owner's idle poller costs one stat per tick,
-// not a locked read-modify-write.
-let _foreignSpoolScanMtime = 0;
+// not a locked read-modify-write. Keyed PER SESSION: one process can own
+// several sessions (desktop tabs, TUI + engine hosts) and a single shared
+// counter let the first drain of a tick swallow the mtime bump for every
+// other session, stranding their foreign submits until the next spool write.
+const FOREIGN_SPOOL_SCAN_LIMIT = 64;
+const _foreignSpoolScanMtimes = new Map();
+
+function _rememberForeignSpoolScan(sessionId, mtime) {
+    _foreignSpoolScanMtimes.delete(sessionId);
+    _foreignSpoolScanMtimes.set(sessionId, mtime);
+    while (_foreignSpoolScanMtimes.size > FOREIGN_SPOOL_SCAN_LIMIT) {
+        const oldest = _foreignSpoolScanMtimes.keys().next().value;
+        if (oldest === undefined) break;
+        _foreignSpoolScanMtimes.delete(oldest);
+    }
+}
 
 /**
  * Owner-side drain of FOREIGN user injections for a session this process
@@ -721,8 +735,8 @@ export function drainForeignUserInjections(sessionId) {
     if (!isValidPendingSessionId(sessionId)) return [];
     let mtime = 0;
     try { mtime = statSync(pendingMessagesPath()).mtimeMs || 0; } catch { return []; }
-    if (mtime === _foreignSpoolScanMtime) return [];
-    _foreignSpoolScanMtime = mtime;
+    if (_foreignSpoolScanMtimes.get(sessionId) === mtime) return [];
+    _rememberForeignSpoolScan(sessionId, mtime);
     const localIds = new Set();
     for (const map of [_sessionPendingMessages, _pendingPersistBuffers, _hydratedPendingMessages]) {
         for (const entry of map.get(sessionId) || []) {

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -6,7 +6,7 @@
 import { getProvider } from '../../providers/registry.mjs';
 import { normalizeCompactType, DEFAULT_COMPACT_TYPE } from '../compact.mjs';
 import { collectPromptSkillsCached, buildSkillManifest, composeSystemPrompt } from '../../context/collect.mjs';
-import { saveSession, saveSessionAsync, saveSessionAsyncDeferred, loadSession, setLiveSession, readSessionHeartbeatMtime, readSessionPresenceMtime, isSessionPresenceOwnerDead, deleteSessionPresence } from '../store.mjs';
+import { saveSession, saveSessionAsync, saveSessionAsyncDeferred, loadSession, setLiveSession, readSessionHeartbeatMtime, readSessionPresenceMtime, isSessionPresenceOwnerDead, deleteSessionPresence, isSessionHeartbeatOwnerDead, readSessionHeartbeatOwnerPid, deleteHeartbeat, isProcessAlive } from '../store.mjs';
 import { _getRuntimeEntry } from './runtime-liveness.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
 import { getHiddenAgent } from '../../internal-agents.mjs';
@@ -547,6 +547,18 @@ export function prefetchSession(sessionId, preset = 'full') {
     return true;
 }
 
+// Owner-pid hint for liveness signals that carry NO pid of their own:
+// `session.lastHeartbeatAt` is persisted in the session file and therefore
+// survives its writer forever, and pre-pid `.hb` sidecars only hold a
+// timestamp. The recorded client host is the process that created/claimed the
+// runtime for this session; the session-id prefix is the legacy fallback.
+function _recordedOwnerPid(session, sessionId) {
+    const recorded = Number(session?.clientHostPid) || 0;
+    if (recorded > 0) return recorded;
+    const match = /^sess_(\d+)_/.exec(String(sessionId || ''));
+    return Number(match?.[1]) || 0;
+}
+
 function _isActivelyOwnedElsewhere(session, sessionId) {
     // This process already owns the runtime for the id — switching back to
     // one of our own sessions (desktop tab switch, TUI /resume) never attaches.
@@ -560,19 +572,40 @@ function _isActivelyOwnedElsewhere(session, sessionId) {
         deleteSessionPresence(sessionId);
         return false;
     }
+    const now = Date.now();
+    // Presence (`.own`, pid-verified just above) covers the idle gaps between
+    // turns: a live interactive surface keeps refreshing it (~20s) for its
+    // CURRENT session, so cross-opening an idle-but-open session still
+    // attaches as a viewer instead of splitting ownership into two writers
+    // that clobber each other's saves.
+    const presenceAt = Number(readSessionPresenceMtime(sessionId)) || 0;
+    if (presenceAt > 0 && now - presenceAt <= ACTIVE_OWNER_HB_FRESH_MS) return true;
     // Heartbeats publish only while a turn is running (≤5s cadence) and the
     // sidecar is deleted on detach/close, so freshness here means another
-    // process is mid-conversation on this session right now. Presence (`.own`)
-    // covers the idle gaps between turns: a live interactive surface keeps
-    // refreshing it (~20s) for its CURRENT session, so cross-opening an
-    // idle-but-open session still attaches as a viewer instead of splitting
-    // ownership into two writers that clobber each other's saves.
-    const lastHb = Math.max(
-        Number(readSessionHeartbeatMtime(sessionId)) || 0,
-        Number(session.lastHeartbeatAt) || 0,
-        Number(readSessionPresenceMtime(sessionId)) || 0,
-    );
-    return lastHb > 0 && Date.now() - lastHb <= ACTIVE_OWNER_HB_FRESH_MS;
+    // process is mid-conversation on this session right now — PROVIDED that
+    // process still exists. Without the pid check a force-killed owner (app
+    // upgrade restart, crash) kept looking live for the whole freshness
+    // window, so every cross-open attached as a viewer and the user's
+    // messages spooled to a queue nobody drains (silently dropped 30m later).
+    if (isSessionHeartbeatOwnerDead(sessionId)) {
+        void deleteHeartbeat(sessionId);
+        return false;
+    }
+    const sidecarAt = Number(readSessionHeartbeatMtime(sessionId)) || 0;
+    if (sidecarAt > 0 && now - sidecarAt <= ACTIVE_OWNER_HB_FRESH_MS
+        && readSessionHeartbeatOwnerPid(sessionId) > 0) {
+        // Fresh sidecar whose recorded pid is alive: a real owner is driving
+        // this session right now, whatever the session file remembers.
+        return true;
+    }
+    const heartbeatAt = Math.max(sidecarAt, Number(session.lastHeartbeatAt) || 0);
+    if (!(heartbeatAt > 0 && now - heartbeatAt <= ACTIVE_OWNER_HB_FRESH_MS)) return false;
+    // Pid-less evidence only (persisted field / legacy sidecar): fall back to
+    // the recorded client-host pid. A dead host means no owner; an unknown pid
+    // keeps the conservative attach.
+    const ownerPid = _recordedOwnerPid(session, sessionId);
+    if (ownerPid > 0 && !isProcessAlive(ownerPid)) return false;
+    return true;
 }
 
 // Viewer self-heal probe: true when a re-resume of this session would NO

package/src/runtime/agent/orchestrator/session/store/listing.mjs

@@ -10,6 +10,7 @@ import { resolveAgentTerminalReapMs } from '../../../../../session-runtime/confi
 import { getStoreDir, sessionPath } from './paths-heartbeat.mjs';
 import { isCancelledWrite as _isCancelledWrite } from './write-guards.mjs';
 import {
+    SESSION_SUMMARY_INDEX_VERSION,
     summaryIndexPath,
     _sessionSummary,
     _normalizeSummaryIndex,

package/src/runtime/agent/orchestrator/session/store/paths-heartbeat.mjs

@@ -19,13 +19,40 @@ export function sessionPath(id) {
     return join(getStoreDir(), `${id}.json`);
 }
 
+// ── Sidecar owner-pid helpers ─────────────────────────────
+// Liveness sidecars record the publishing process id on their SECOND line so
+// a reader can tell a genuinely live owner from a force-killed one whose
+// timestamp still looks fresh. Legacy (pid-less) sidecars read back as 0.
+export function isProcessAlive(pid) {
+    const target = Number(pid) || 0;
+    if (target <= 0) return false;
+    try {
+        process.kill(target, 0);
+        return true;
+    } catch (error) {
+        // ESRCH: no such process. EPERM means the pid exists (alive).
+        return error?.code !== 'ESRCH';
+    }
+}
+
+function _readSidecarOwnerPid(path) {
+    try {
+        if (!existsSync(path)) return 0;
+        return Number(String(readFileSync(path, 'utf8')).split('\n')[1]) || 0;
+    } catch {
+        return 0;
+    }
+}
+
 // ── Heartbeat publish ─────────────────────────────────────
 // Lightweight per-session timestamp file (`<id>.hb`) consumed by the
 // status aggregator for fresh-session detection. Decoupled from the
 // full session JSON save so it can fire at a tight cadence (≤5s)
-// without serialising the whole payload. The .hb file holds a single
-// ASCII line: `<msTimestamp>\n`. Aggregator scans the same sessions/
-// directory and matches `<id>.hb` to `<id>.json`.
+// without serialising the whole payload. The .hb file holds
+// `<msTimestamp>\n<pid>\n` — readers that only need liveness use the file
+// mtime, while the attach-on-resume guard verifies the recorded pid.
+// Aggregator scans the same sessions/ directory and matches `<id>.hb` to
+// `<id>.json`.
 const _HEARTBEAT_THROTTLE_MS = 5_000;
 const _hbLastAt = new Map();
 const _hbOperations = new Map();
@@ -56,7 +83,7 @@ export function publishHeartbeat(id, ts) {
     }
     const target = _heartbeatPath(id);
     _hbLastAt.set(id, now);
-    return _queueHeartbeatOperation(id, () => fsp.writeFile(target, `${now}\n`, 'utf8'));
+    return _queueHeartbeatOperation(id, () => fsp.writeFile(target, `${now}\n${process.pid}\n`, 'utf8'));
 }
 
 export function deleteHeartbeat(id) {
@@ -91,6 +118,24 @@ export function listSessionHeartbeatMtimes() {
     return result;
 }
 
+// Owner pid recorded in the `<id>.hb` sidecar (0 when absent or written by a
+// pre-pid build).
+export function readSessionHeartbeatOwnerPid(id) {
+    if (!id) return 0;
+    try { return _readSidecarOwnerPid(_heartbeatPath(id)); } catch { return 0; }
+}
+
+// A killed owner never deletes its `.hb` sidecar, so bare mtime freshness
+// would keep the session "actively driven" for the whole freshness window and
+// every cross-open would attach as a viewer whose submits spool to nobody.
+// The recorded pid is authoritative proof; pid-less legacy sidecars return
+// false (unknown, not dead).
+export function isSessionHeartbeatOwnerDead(id) {
+    const pid = readSessionHeartbeatOwnerPid(id);
+    if (!pid) return false;
+    return !isProcessAlive(pid);
+}
+
 // ── Interactive presence publish ──────────────────────────
 // `<id>.own` marks a live interactive surface (TUI/desktop engine) HOLDING
 // the session open — including idle time between turns. Kept separate from
@@ -144,19 +189,7 @@ export function readSessionPresenceMtime(id) {
 export function isSessionPresenceOwnerDead(id) {
     if (!id) return false;
     let pid = 0;
-    try {
-        const path = _presencePath(id);
-        if (!existsSync(path)) return false;
-        pid = Number(String(readFileSync(path, 'utf8')).split('\n')[1]) || 0;
-    } catch {
-        return false;
-    }
+    try { pid = _readSidecarOwnerPid(_presencePath(id)); } catch { return false; }
     if (!pid) return false;
-    try {
-        process.kill(pid, 0);
-        return false;
-    } catch (error) {
-        // ESRCH: no such process. EPERM means the pid exists (alive).
-        return error?.code === 'ESRCH';
-    }
+    return !isProcessAlive(pid);
 }

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -54,6 +54,9 @@ export {
     deleteSessionPresence,
     readSessionPresenceMtime,
     isSessionPresenceOwnerDead,
+    readSessionHeartbeatOwnerPid,
+    isSessionHeartbeatOwnerDead,
+    isProcessAlive,
 } from './store/paths-heartbeat.mjs';
 import { _readStoredSessionCached } from './store/load-cache.mjs';
 import { _sessionForDisk, _renameWithRetrySync, _ensureLifecycleFields, _storedSessionFromFile } from './store/serialize.mjs';

package/src/runtime/channels/lib/owned-runtime.mjs

@@ -477,7 +477,14 @@ async function reloadRuntimeConfig() {
     getConfig().interactive ?? [],
     // Single resolved main-channel id used for the schedule `channel` flag.
     getConfig().channelId,
-    { restart: getBridgeRuntimeConnected() }
+    // The scheduler must be RE-ARMED by the reload whenever it is supposed to
+    // be running. `restart: false` only destroys the cron/one-shot bindings and
+    // hands lifecycle back to the caller — but on an automation-only install
+    // (no messaging backend) startAutomationRuntime() is already past its
+    // `automationRunning` guard, so nobody would ever call scheduler.start()
+    // again and every saved/edited schedule stayed silently disarmed until the
+    // daemon restarted.
+    { restart: automationRunning || getBridgeRuntimeConnected() }
   );
   const nextBackend = createBackend(getConfig());
   const backendTypeChanged = (nextBackend?.name || "") !== previousBackendName;

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

@@ -0,0 +1,109 @@
+/**
+ * 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.
+ */
+import { randomBytes } from 'crypto';
+import { resolveCodexAuth } from '../auth.mjs';
+import { mediaError } from '../lanes.mjs';
+import { upstreamError } from '../upstream-error.mjs';
+import { CODEX_OAUTH_ORIGINATOR, CODEX_RESPONSES_URL } from '../../agent/orchestrator/providers/openai-oauth.mjs';
+
+const REQUEST_TIMEOUT_MS = 400_000;
+
+function imageTool(options = {}) {
+  const tool = { type: 'image_generation' };
+  const size = String(options.size || 'auto');
+  if (size && size !== 'auto') tool.size = size;
+  const quality = String(options.quality || 'auto');
+  if (quality && quality !== 'auto') tool.quality = quality;
+  return tool;
+}
+
+function collectImage(event, state) {
+  const item = event?.item;
+  if (event?.type === 'response.output_item.done' && item?.type === 'image_generation_call') {
+    if (typeof item.result === 'string' && item.result.length > 0) state.final = item.result;
+    if (typeof item.revised_prompt === 'string') state.revisedPrompt = item.revised_prompt;
+    return;
+  }
+  if (event?.type === 'response.image_generation_call.partial_image') {
+    const partial = event?.partial_image_b64;
+    if (typeof partial === 'string' && partial.length > (state.partial?.length || 0)) state.partial = partial;
+  }
+}
+
+export async function generateImage({ model, prompt, options = {}, references = [], signal }) {
+  const auth = await resolveCodexAuth();
+  // 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}`,
+    })),
+    { type: 'input_text', text: prompt },
+  ];
+  const body = {
+    model,
+    stream: true,
+    store: false,
+    instructions: 'You generate images with the image_generation tool. Call the tool once for the user request; do not ask follow-up questions.',
+    input: [{ type: 'message', role: 'user', content }],
+    tools: [imageTool(options)],
+    tool_choice: 'auto',
+  };
+  const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+  const res = await fetch(CODEX_RESPONSES_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${auth.access_token}`,
+      'Content-Type': 'application/json',
+      Accept: 'text/event-stream',
+      'OpenAI-Beta': 'responses=experimental',
+      originator: CODEX_OAUTH_ORIGINATOR,
+      'chatgpt-account-id': auth.account_id || '',
+      'x-client-request-id': randomBytes(16).toString('hex'),
+    },
+    body: JSON.stringify(body),
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+  });
+  if (!res.ok || !res.body) throw upstreamError('ChatGPT image', res.status, await res.text().catch(() => ''));
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  const state = { final: '', partial: '', revisedPrompt: null };
+  let buffer = '';
+  let failure = null;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      for (const line of lines) {
+        if (!line.startsWith('data:')) continue;
+        const raw = line.slice(5).trim();
+        if (!raw || raw === '[DONE]') continue;
+        let event;
+        try { event = JSON.parse(raw); } catch { continue; }
+        if (event?.type === 'response.failed' || event?.type === 'error') {
+          failure = event?.response?.error?.message || event?.message || 'stream failed';
+        }
+        collectImage(event, state);
+      }
+    }
+  } finally {
+    try { reader.releaseLock(); } catch {}
+  }
+
+  const b64 = state.final || state.partial;
+  if (!b64) {
+    throw mediaError(`ChatGPT returned no image data${failure ? `: ${failure}` : ''}`, 'MEDIA_EMPTY_RESULT', 502);
+  }
+  return { bytes: Buffer.from(b64, 'base64'), mime: 'image/png', revisedPrompt: state.revisedPrompt };
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Gemini image adapter (API key lane).
+ *
+ * Calls the Generative Language `generateContent` route and pulls the first
+ * inline image part out of the candidate. Aspect ratio rides in `imageConfig`,
+ * which older image models reject — a 400 there retries once without it so a
+ * control the model does not know never fails the whole generation.
+ */
+import { resolveGeminiKey } from '../auth.mjs';
+import { mediaError } from '../lanes.mjs';
+import { upstreamError } from '../upstream-error.mjs';
+
+const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta/models';
+const REQUEST_TIMEOUT_MS = 180_000;
+
+function requestBody(prompt, options, withImageConfig, references = []) {
+  const body = {
+    contents: [{
+      role: 'user',
+      parts: [
+        ...references.map((ref) => ({
+          inlineData: { mimeType: ref.mime || 'image/png', data: ref.base64 },
+        })),
+        { text: prompt },
+      ],
+    }],
+  };
+  const aspect = String(options?.aspectRatio || 'auto');
+  if (withImageConfig && aspect !== 'auto') {
+    body.generationConfig = { imageConfig: { aspectRatio: aspect } };
+  }
+  return body;
+}
+
+async function post(model, key, body, signal) {
+  return await fetch(`${BASE_URL}/${encodeURIComponent(model)}:generateContent`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'x-goog-api-key': key },
+    body: JSON.stringify(body),
+    signal: AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)].filter(Boolean)),
+  });
+}
+
+export async function generateImage({ model, prompt, options = {}, references = [], signal }) {
+  const key = resolveGeminiKey();
+  const wantsImageConfig = String(options.aspectRatio || 'auto') !== 'auto';
+  let res = await post(model, key, requestBody(prompt, options, wantsImageConfig, references), signal);
+  if (!res.ok && res.status === 400 && wantsImageConfig) {
+    res = await post(model, key, requestBody(prompt, options, false, references), signal);
+  }
+  if (!res.ok) throw upstreamError('Gemini image', res.status, await res.text().catch(() => ''));
+  const data = await res.json();
+  const parts = data?.candidates?.[0]?.content?.parts || [];
+  const image = parts.find((part) => part?.inlineData?.data);
+  if (!image) {
+    const refusal = parts.find((part) => typeof part?.text === 'string')?.text || '';
+    throw mediaError(
+      `Gemini returned no image data${refusal ? `: ${refusal.slice(0, 200)}` : ''}`,
+      'MEDIA_EMPTY_RESULT',
+      502,
+    );
+  }
+  return {
+    bytes: Buffer.from(image.inlineData.data, 'base64'),
+    mime: image.inlineData.mimeType || 'image/png',
+    revisedPrompt: null,
+  };
+}

package/src/runtime/media/adapters/gemini-video.mjs

@@ -0,0 +1,119 @@
+/**
+ * Gemini video adapter (API key lane).
+ *
+ * Two different upstream shapes live behind one lane:
+ *   - Omni Flash answers on the Interactions API in a single call, with the
+ *     mp4 inline as base64 on a `model_output` step.
+ *   - Veo 3.1 is a long-running predict: submit, poll the operation, then pull
+ *     the sample URI with `alt=media`.
+ */
+import { resolveGeminiKey } from '../auth.mjs';
+import { mediaError } from '../lanes.mjs';
+import { upstreamError } from '../upstream-error.mjs';
+
+const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta';
+const OMNI_TIMEOUT_MS = 600_000;
+const POLL_INTERVAL_MS = 8_000;
+const TOTAL_TIMEOUT_MS = 900_000;
+
+export function isOmniModel(model) {
+  return /omni/i.test(String(model || ''));
+}
+
+function aspectFor(options) {
+  const aspect = String(options?.aspectRatio || 'auto');
+  return aspect === 'auto' ? '16:9' : aspect;
+}
+
+async function generateViaOmni({ model, prompt, options, references = [], signal, key }) {
+  // Omni takes a multimodal input array; a reference image switches the task
+  // from text-to-video to image-to-video.
+  const input = references.length
+    ? [
+      ...references.map((ref) => ({ type: 'image', data: ref.base64, mime_type: ref.mime || 'image/png' })),
+      { type: 'text', text: prompt },
+    ]
+    : prompt;
+  const res = await fetch(`${BASE_URL}/interactions`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'x-goog-api-key': key },
+    body: JSON.stringify({
+      model,
+      input,
+      response_format: { type: 'video', aspect_ratio: aspectFor(options) },
+      generation_config: {
+        video_config: { task: references.length ? 'image_to_video' : 'text_to_video' },
+      },
+    }),
+    signal: AbortSignal.any([signal, AbortSignal.timeout(OMNI_TIMEOUT_MS)].filter(Boolean)),
+  });
+  if (!res.ok) throw upstreamError('Gemini Omni video', res.status, await res.text().catch(() => ''));
+  const data = await res.json();
+  for (const step of data?.steps || []) {
+    const content = Array.isArray(step?.content) ? step.content : [step?.content].filter(Boolean);
+    const video = content.find((item) => item?.type === 'video' && typeof item?.data === 'string');
+    if (video) {
+      return { bytes: Buffer.from(video.data, 'base64'), mime: video.mime_type || 'video/mp4' };
+    }
+  }
+  throw mediaError('Gemini Omni returned no video data', 'MEDIA_EMPTY_RESULT', 502);
+}
+
+async function generateViaVeo({ model, prompt, options, references = [], signal, onProgress, key }) {
+  const headers = { 'Content-Type': 'application/json', 'x-goog-api-key': key };
+  const parameters = { aspectRatio: aspectFor(options) };
+  const instance = { prompt };
+  // Veo accepts a single seed image for image-to-video.
+  if (references[0]) {
+    instance.image = { bytesBase64Encoded: references[0].base64, mimeType: references[0].mime || 'image/png' };
+  }
+  const resolution = String(options?.resolution || '');
+  if (resolution === '720p' || resolution === '1080p') parameters.resolution = resolution;
+  // Veo takes discrete clip lengths; anything else is rejected upstream, so an
+  // out-of-contract value is dropped rather than forwarded.
+  const duration = Math.trunc(Number(options?.duration) || 0);
+  if ([4, 6, 8].includes(duration)) parameters.durationSeconds = duration;
+
+  const started = await fetch(`${BASE_URL}/models/${encodeURIComponent(model)}:predictLongRunning`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ instances: [instance], parameters }),
+    signal,
+  });
+  if (!started.ok) throw upstreamError('Veo video', started.status, await started.text().catch(() => ''));
+  const operation = await started.json();
+  if (!operation?.name) throw mediaError('Veo returned no operation name', '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('Veo poll budget exceeded', 'MEDIA_TIMEOUT', 504);
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    const poll = await fetch(`${BASE_URL}/${operation.name}`, { headers, signal });
+    if (!poll.ok) throw upstreamError('Veo poll', poll.status, await poll.text().catch(() => ''));
+    const data = await poll.json();
+    if (!data?.done) {
+      // The operation exposes no percentage; keep the UI moving with a coarse
+      // heartbeat instead of a fake number.
+      if (typeof onProgress === 'function') onProgress(50);
+      continue;
+    }
+    if (data.error) {
+      throw mediaError(`Veo generation failed: ${data.error.message || 'unknown error'}`, 'MEDIA_UPSTREAM_FAILED', 502);
+    }
+    const sample = data?.response?.generateVideoResponse?.generatedSamples?.[0]
+      || data?.response?.generatedVideos?.[0];
+    const uri = sample?.video?.uri || sample?.video?.fileUri;
+    if (!uri) throw mediaError('Veo finished without a video URI', 'MEDIA_EMPTY_RESULT', 502);
+    const file = await fetch(`${uri}${uri.includes('?') ? '&' : '?'}alt=media`, { headers, signal });
+    if (!file.ok) throw upstreamError('Veo download', file.status, await file.text().catch(() => ''));
+    return { bytes: Buffer.from(await file.arrayBuffer()), mime: 'video/mp4' };
+  }
+}
+
+export async function generateVideo({ model, prompt, options = {}, references = [], signal, onProgress }) {
+  const key = resolveGeminiKey();
+  return isOmniModel(model)
+    ? await generateViaOmni({ model, prompt, options, references, signal, key })
+    : await generateViaVeo({ model, prompt, options, references, signal, onProgress, key });
+}