mixdog 1.3.1 → 1.3.3

package/src/runtime/effort-judge/judge-client.mjs

@@ -8,12 +8,18 @@
 // effort. Decisions are logged locally (lengths and probabilities only, never
 // the request text).
 import { Worker } from 'node:worker_threads';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { appendFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 import { onnxRuntimeSupported } from '../shared/onnx-runtime-support.mjs';
-import { effortJudgeInstallCurrent, effortJudgeInstallStamped, installEffortJudgeModel } from './model-install.mjs';
+import { fileHasData } from '../shared/file-has-data.mjs';
+import {
+  effortJudgeInstallCurrent,
+  effortJudgeInstallStamped,
+  installEffortJudgeModel,
+  invalidateDamagedEffortJudgeInstall,
+} from './model-install.mjs';
 
 export const EFFORT_JUDGE_UNSUPPORTED = 'Auto effort is unsupported on darwin-x64 (no onnxruntime-node binding)';
 const WORKER_PATH = fileURLToPath(new URL('./judge-worker.mjs', import.meta.url));
@@ -86,7 +92,9 @@ export function effortJudgeModelDir() {
 // it is. Unstamped leftovers (hand-copied packs) never load.
 export function effortJudgeAvailable(dir = effortJudgeModelDir()) {
   if (!onnxRuntimeSupported()) return false;
-  if (!MODEL_FILES.every((file) => existsSync(join(dir, file)))) return false;
+  // A model file a crash left empty or NUL-filled is not installed: the refresh
+  // then re-verifies the folder against the manifest hashes and fetches it again.
+  if (!MODEL_FILES.every((file) => fileHasData(join(dir, file)))) return false;
   return Boolean(process.env.MIXDOG_EFFORT_JUDGE_DIR) || effortJudgeInstallStamped(dir);
 }
 
@@ -136,6 +144,7 @@ function ensureWorker(dir) {
       lastLoadError = msg.message;
       lastLoadErrorAt = Date.now();
       notifyReady(false);
+      void repairAfterLoadError(dir);
     } else if (msg.type === 'result') {
       settle(msg.id, (entry) => entry.resolve(msg.probs));
     } else if (msg.type === 'error') {
@@ -201,6 +210,49 @@ function request(target, { request: text, prev, prevRequest, step }) {
 // One install at a time (the settings install and the boot refresh can overlap).
 let installing = null;
 let refreshChecked = false;
+let verifying = false;
+
+/** Why the judge last failed to load; '' when it loaded or never failed. */
+export function effortJudgeLastError() {
+  return lastLoadError;
+}
+
+// Runs `task` as the one install: the slot stays taken until it settles, so
+// installs, refreshes and repairs never overlap.
+function occupyInstall(task) {
+  const run = task().finally(() => {
+    if (installing === run) installing = null;
+  });
+  installing = run;
+  return run;
+}
+
+// A model that fails to load may be damaged on disk (a crash can leave a
+// stamped file with a zeroed tail). Re-verify the hashes once per load error,
+// off the turn's path: a mismatch drops the stamp and re-downloads only the bad
+// files; matching hashes keep the plain LOAD_RETRY_MS back-off. Verifying and
+// invalidating hold the install slot, after any install in flight has settled,
+// so the stamp they remove is never one an installer just wrote.
+async function repairAfterLoadError(dir) {
+  if (verifying || process.env.MIXDOG_EFFORT_JUDGE_DIR || !onnxRuntimeSupported()) return;
+  verifying = true;
+  try {
+    while (installing) await installing.catch(() => {});
+    await occupyInstall(async () => {
+      const bad = await invalidateDamagedEffortJudgeInstall(dir);
+      if (!bad.length) return;
+      process.stderr.write(`[effort-judge] reinstalling damaged model files: ${bad.join(', ')}\n`);
+      await runInstall();
+      // The files are replaced: the next turn loads them without the back-off.
+      lastLoadErrorAt = 0;
+      lastLoadError = '';
+    });
+  } catch (error) {
+    process.stderr.write(`[effort-judge] model repair failed: ${error?.message || error}\n`);
+  } finally {
+    verifying = false;
+  }
+}
 
 /**
  * Installs or updates the judge model from the release the bundled manifest
@@ -210,19 +262,17 @@ let refreshChecked = false;
  */
 export function installEffortJudge() {
   if (!onnxRuntimeSupported()) return Promise.reject(new Error(EFFORT_JUDGE_UNSUPPORTED));
-  installing ??= (async () => {
-    const dir = effortJudgeModelDir();
-    if (process.env.MIXDOG_EFFORT_JUDGE_DIR || (effortJudgeAvailable(dir) && effortJudgeInstallCurrent(dir))) {
-      if (!effortJudgeAvailable(dir))
-        throw new Error(`The Auto reasoning model is not installed (expected in ${dir}).`);
-      return;
-    }
-    await installEffortJudgeModel(dir);
-    if (worker) await shutdownEffortJudge();
-  })().finally(() => {
-    installing = null;
-  });
-  return installing;
+  return installing ?? occupyInstall(runInstall);
+}
+
+async function runInstall() {
+  const dir = effortJudgeModelDir();
+  if (process.env.MIXDOG_EFFORT_JUDGE_DIR || (effortJudgeAvailable(dir) && effortJudgeInstallCurrent(dir))) {
+    if (!effortJudgeAvailable(dir)) throw new Error(`The Auto reasoning model is not installed (expected in ${dir}).`);
+    return;
+  }
+  await installEffortJudgeModel(dir);
+  if (worker) await shutdownEffortJudge();
 }
 
 /**

package/src/runtime/effort-judge/model-install.mjs

@@ -4,9 +4,11 @@
 // download never replaces a working file. Files that already match are kept.
 // install.json records the installed release; a newer bundled manifest makes
 // the install stale and the next refresh downloads only what changed.
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { open as openAsync } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isFileFsyncUnsupported, parseJsonText, writeJsonAtomicSync } from '../shared/atomic-file.mjs';
 import { downloadToFileWithRetry } from '../shared/bounded-download.mjs';
 import { sha256File, validSha256 } from '../shared/native-asset.mjs';
 
@@ -30,24 +32,61 @@ export function effortJudgeManifest() {
   return manifest;
 }
 
+// Release named by the stamp; '' when it is missing or damaged (empty,
+// NUL-filled), so a damaged stamp reads as not installed and the next refresh
+// re-verifies every file against its sha256 and stamps again.
+function stampedRelease(dir) {
+  try {
+    return String(parseJsonText(readFileSync(join(dir, STAMP), 'utf8')).release || '');
+  } catch {
+    return '';
+  }
+}
+
 /** True when `dir` holds a complete install of some release (stamped). */
 export function effortJudgeInstallStamped(dir) {
-  return existsSync(join(dir, STAMP));
+  return stampedRelease(dir) !== '';
 }
 
 /** True when `dir` holds the release the manifest names. */
 export function effortJudgeInstallCurrent(dir, manifest = effortJudgeManifest()) {
+  return stampedRelease(dir) === manifest.release;
+}
+
+/**
+ * Files in `dir` that are missing or differ from the manifest sha256. When any
+ * does, the stamp is removed so the folder reads as not installed and the next
+ * install re-downloads only those files (a crash can leave a stamped model with
+ * its tail zeroed: same size, wrong hash).
+ */
+export async function invalidateDamagedEffortJudgeInstall(dir, manifest = effortJudgeManifest()) {
+  const bad = [];
+  for (const [name, file] of Object.entries(manifest.files)) {
+    const target = join(dir, name);
+    if (!existsSync(target) || (await sha256File(target)) !== file.sha256) bad.push(name);
+  }
+  if (bad.length) rmSync(join(dir, STAMP), { force: true });
+  return bad;
+}
+
+// Flushes the downloaded file through a write handle (Windows refuses fsync on
+// a read-only one) so a crash right after the rename cannot publish a file
+// whose size is committed but whose tail never reached the disk.
+export async function fsyncFile(path, open = openAsync) {
+  const handle = await open(path, 'r+');
   try {
-    return JSON.parse(readFileSync(join(dir, STAMP), 'utf8')).release === manifest.release;
-  } catch {
-    return false;
+    await handle.sync();
+  } catch (err) {
+    if (!isFileFsyncUnsupported(err)) throw err;
+  } finally {
+    await handle.close();
   }
 }
 
 /** Download what is missing or different, then stamp the release. */
 export async function installEffortJudgeModel(
   dir,
-  { fetchFn = globalThis.fetch, manifest = effortJudgeManifest() } = {}
+  { fetchFn = globalThis.fetch, manifest = effortJudgeManifest(), syncFile = fsyncFile } = {}
 ) {
   mkdirSync(dir, { recursive: true });
   let replaced = false;
@@ -65,6 +104,7 @@ export async function installEffortJudgeModel(
       const actual = await sha256File(partial);
       if (actual !== file.sha256)
         throw new Error(`effort judge ${name}: sha256 mismatch (expected ${file.sha256}, got ${actual})`);
+      await syncFile(partial);
       // From the first replaced file until the new stamp, the folder is a mix of
       // releases: without a stamp it reads as not installed, so an interrupted
       // install is never loaded.
@@ -76,5 +116,5 @@ export async function installEffortJudgeModel(
     }
   }
   if (replaced) for (const name of DERIVED) rmSync(join(dir, name), { force: true });
-  writeFileSync(join(dir, STAMP), `${JSON.stringify({ release: manifest.release })}\n`);
+  writeJsonAtomicSync(join(dir, STAMP), { release: manifest.release }, { compact: true });
 }

package/src/runtime/local-provider/asset-installer.mjs

@@ -4,6 +4,7 @@ import { dirname, join } from 'node:path';
 import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 
+import { fileHasData } from '../shared/file-has-data.mjs';
 import { sha256File } from '../shared/native-asset.mjs';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 import {
@@ -125,9 +126,14 @@ export async function downloadVerifiedLocalAsset(
       callback(null, chunk);
     },
   });
-  await pipeline(Readable.fromWeb(response.body), meter, createWriteStream(partial, { flags: resumed ? 'a' : 'w' }), {
-    signal: operationSignal,
-  });
+  await pipeline(
+    Readable.fromWeb(response.body),
+    meter,
+    createWriteStream(partial, { flags: resumed ? 'a' : 'w', flush: true }),
+    {
+      signal: operationSignal,
+    }
+  );
   if (total !== asset.size) {
     throw new Error(`[local-provider] incomplete download for ${asset.name || destination}: ${total}/${asset.size}`);
   }
@@ -198,7 +204,7 @@ async function installRuntimeInternal({ dataDir, onProgress, fetchFn, signal })
   }
   const target = localProviderRuntimeDirectory(dataDir);
   const executable = join(target, entry.executable);
-  if (existsSync(executable)) return localProviderCatalogStatus({ dataDir, hardware });
+  if (fileHasData(executable)) return localProviderCatalogStatus({ dataDir, hardware });
   ensureDiskSpace(localProviderRuntimeRoot(dataDir), entry.downloadBytes);
   const staging = join(localProviderRuntimeRoot(dataDir), `.staging-${process.pid}`);
   const downloads = join(localProviderRuntimeRoot(dataDir), '.downloads');

package/src/runtime/local-provider/catalog.mjs

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { fileHasData } from '../shared/file-has-data.mjs';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 import { localProviderDiskStatus, partialAssetBytes } from './asset-storage.mjs';
 import { localProviderHardwareStatus, localProviderPlatformKey } from './hardware.mjs';
@@ -54,7 +55,9 @@ export function localProviderModelPath(entry, dataDir = resolvePluginData()) {
 export function exactLocalProviderFile(path, size) {
   try {
     const stat = statSync(path);
-    return stat.isFile() && stat.size === size;
+    // A crash can commit the size of a renamed download without its bytes: a
+    // file whose head is all NUL is not installed (it is fetched again).
+    return stat.isFile() && stat.size === size && fileHasData(path);
   } catch {
     return false;
   }
@@ -108,7 +111,7 @@ export function localProviderCatalogStatus({
     platformSupported: Boolean(platformEntry),
     available: Boolean(platformEntry && hardware?.supported && models.some((entry) => entry.compatible)),
     runtime: {
-      installed: Boolean(executable && existsSync(executable)),
+      installed: Boolean(executable && fileHasData(executable)),
       version: LOCAL_PROVIDER_MANIFEST.runtime.version,
       downloadBytes: platformEntry?.downloadBytes || 0,
       source: LOCAL_PROVIDER_MANIFEST.runtime.source,

package/src/runtime/local-provider/registered-models.mjs

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
-import { writeJsonAtomicSync } from '../shared/atomic-file.mjs';
+import { readJsonStateSync, unsupportedState, updateJsonAtomicSync } from '../shared/atomic-file.mjs';
 
 const MAX_REGISTRY_BYTES = 1024 * 1024;
 const cache = new Map();
@@ -42,44 +42,81 @@ function validateModel(entry) {
   return entry;
 }
 
-export function registeredLocalModels(dataDir = resolvePluginData()) {
-  const path = registryPath(dataDir);
-  if (!existsSync(path)) return [];
-  const stat = statSync(path);
-  if (stat.size > MAX_REGISTRY_BYTES) throw new Error('[local-provider] registered model index is too large');
-  const stamp = `${stat.mtimeMs}:${stat.size}`;
-  if (cache.get(path)?.stamp === stamp) return cache.get(path).models.map((entry) => ({ ...entry }));
-  const value = JSON.parse(readFileSync(path, 'utf8'));
+// Each candidate (the index or its backup) is bounded by its own bytes.
+function registryText(content) {
+  if (content.length > MAX_REGISTRY_BYTES) throw new Error('[local-provider] registered model index is too large');
+  return content.toString('utf8');
+}
+
+function parseRegistry(value) {
+  // A newer build's index is left in place (reads as no models), not discarded.
+  if (Number.isSafeInteger(value?.schema) && value.schema > 1) {
+    throw unsupportedState(`[local-provider] registered model index schema ${value.schema} is newer than this build`);
+  }
   if (value?.schema !== 1 || !Array.isArray(value.models) || value.models.length > 256) {
     throw new Error('[local-provider] invalid registered model index');
   }
   const models = value.models.map(validateModel);
   if (new Set(models.map((entry) => entry.id)).size !== models.length)
     throw new Error('[local-provider] duplicate registered model ids');
+  return models;
+}
+
+export function registeredLocalModels(dataDir = resolvePluginData()) {
+  const path = registryPath(dataDir);
+  if (!existsSync(path)) return [];
+  const stat = statSync(path);
+  const stamp = `${stat.mtimeMs}:${stat.size}`;
+  if (cache.get(path)?.stamp === stamp) return cache.get(path).models.map((entry) => ({ ...entry }));
+  // A damaged index (empty, NUL-filled, truncated, invalid) never blocks the
+  // provider: its bytes are kept as <file>.corrupt-<ts>, the last good copy
+  // (<file>.bak) is restored when there is one, else no model is registered.
+  // The downloaded weights are untouched.
+  const models = readJsonStateSync(path, { validate: parseRegistry, decode: registryText, fallback: [] });
   cache.set(path, { stamp, models });
   return models.map((entry) => ({ ...entry }));
 }
 
-export function registerLocalModel(entry, dataDir = resolvePluginData()) {
-  validateModel(entry);
-  const models = registeredLocalModels(dataDir);
-  const existing = models.find((model) => model.id === entry.id);
-  if (existing) {
-    if (existing.contextWindow !== entry.contextWindow)
-      throw new Error('[local-provider] this model is already registered with another context size');
-    return existing;
-  }
-  if (models.length >= 256) throw new Error('[local-provider] registered model limit reached');
+// Read-modify-write under the index lock. A damaged index was recovered by the
+// read first; a newer build's index makes the write refuse instead of
+// replacing it (and its backup) with this build's format.
+function mutateRegistry(dataDir, change) {
+  registeredLocalModels(dataDir);
   const path = registryPath(dataDir);
-  writeJsonAtomicSync(path, { schema: 1, models: [...models, entry] });
+  let result;
+  updateJsonAtomicSync(
+    path,
+    (raw) => {
+      const next = change(raw == null ? [] : parseRegistry(raw));
+      if (!next) return undefined;
+      result = next.result;
+      return { schema: 1, models: next.models };
+    },
+    { backup: true }
+  );
   cache.delete(path);
-  return entry;
+  return result;
+}
+
+export function registerLocalModel(entry, dataDir = resolvePluginData()) {
+  validateModel(entry);
+  let existing;
+  const registered = mutateRegistry(dataDir, (models) => {
+    existing = models.find((model) => model.id === entry.id);
+    if (existing) return null;
+    if (models.length >= 256) throw new Error('[local-provider] registered model limit reached');
+    return { models: [...models, entry], result: entry };
+  });
+  if (!existing) return registered;
+  if (existing.contextWindow !== entry.contextWindow)
+    throw new Error('[local-provider] this model is already registered with another context size');
+  return existing;
 }
 
 export function forgetRegisteredLocalModel(modelId, dataDir = resolvePluginData()) {
-  const models = registeredLocalModels(dataDir);
-  if (!models.some((entry) => entry.id === modelId)) return;
-  const path = registryPath(dataDir);
-  writeJsonAtomicSync(path, { schema: 1, models: models.filter((entry) => entry.id !== modelId) });
-  cache.delete(path);
+  mutateRegistry(dataDir, (models) =>
+    models.some((entry) => entry.id === modelId)
+      ? { models: models.filter((entry) => entry.id !== modelId), result: undefined }
+      : null
+  );
 }

package/src/runtime/local-provider/server.mjs

@@ -1,5 +1,4 @@
-import { existsSync } from 'node:fs';
-
+import { fileHasData } from '../shared/file-has-data.mjs';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 import {
   exactLocalProviderFile,
@@ -65,7 +64,7 @@ export async function ensureLocalProviderServer(modelId, { dataDir = resolvePlug
   const contextWindow = localContextSettings(entry, dataDir).contextWindow;
   const executable = localProviderRuntimeExecutable(dataDir);
   const weights = localProviderModelPath(entry, dataDir);
-  if (!executable || !existsSync(executable)) {
+  if (!executable || !fileHasData(executable)) {
     throw new Error('[local-provider] runtime is not installed');
   }
   if (!exactLocalProviderFile(weights, entry.size)) {

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

@@ -0,0 +1,89 @@
+/**
+ * Normalized Image API adapter for the `openrouter` and `nano-gpt` lanes.
+ *
+ * Both gateways document the same contract: POST {base}/images with `model`,
+ * `prompt`, the model's advertised enum parameters and `input_references`
+ * (image_url parts; data URLs accepted), answering `data[].b64_json` (NanoGPT
+ * may answer a signed `url` instead) plus `usage`.
+ *   https://openrouter.ai/docs/guides/overview/multimodal/image-generation
+ *   https://docs.nano-gpt.com/api-reference/image-generation
+ */
+import { resolveImageApiAuth } from '../auth.mjs';
+import { timeoutSignal } from '../bounded-signal.mjs';
+import { decodeBase64Media, downloadPublicMedia } from '../download.mjs';
+import { mediaError } from '../lanes.mjs';
+import { imageApiUsage, withReportedUsage } from '../media-usage.mjs';
+import { upstreamError } from '../upstream-error.mjs';
+
+const IMAGE_TIMEOUT_MS = 180_000;
+const LABELS = Object.freeze({ openrouter: 'OpenRouter image', 'nano-gpt': 'NanoGPT image' });
+// Request field per Studio option; values come from the model's own enums.
+const PARAMS = Object.freeze({
+  aspectRatio: 'aspect_ratio',
+  resolution: 'resolution',
+  quality: 'quality',
+  background: 'background',
+});
+
+function referenceUrl(reference) {
+  const data = String(reference?.base64 || '');
+  return data.startsWith('data:') ? data : `data:${reference?.mime || 'image/png'};base64,${data}`;
+}
+
+/** The stored format comes from the bytes, not a label: only rasters the store keeps. */
+function rasterMime(bytes) {
+  if (bytes.length >= 8 && bytes.readUInt32BE(0) === 0x89504e47) return 'image/png';
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg';
+  if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP')
+    return 'image/webp';
+  return '';
+}
+
+export async function generateImage({ lane, model, prompt, options = {}, references = [], signal }) {
+  const label = LABELS[lane] || 'Image API';
+  const { baseURL, token } = resolveImageApiAuth(lane);
+  const body = { model, prompt, n: 1 };
+  for (const [option, param] of Object.entries(PARAMS)) {
+    const value = String(options?.[option] || '').trim();
+    if (value) body[param] = value;
+  }
+  if (references.length) {
+    body.input_references = references.map((reference) => ({
+      type: 'image_url',
+      image_url: { url: referenceUrl(reference) },
+    }));
+  }
+  let res;
+  try {
+    res = await fetch(`${baseURL}/images`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal: timeoutSignal(signal, IMAGE_TIMEOUT_MS),
+    });
+  } catch (error) {
+    if (error?.name === 'TimeoutError') throw mediaError(`${label} timed out`, 'MEDIA_TIMEOUT', 504);
+    throw error;
+  }
+  if (!res.ok) throw upstreamError(label, res.status, (await res.text().catch(() => '')).slice(0, 400));
+  const data = await res.json().catch(() => null);
+  const usage = imageApiUsage(data);
+  const entry = Array.isArray(data?.data) ? data.data[0] : null;
+  let bytes;
+  try {
+    if (entry?.b64_json) bytes = decodeBase64Media(entry.b64_json, label);
+    else if (entry?.url) bytes = await downloadPublicMedia(entry.url, { signal, label });
+    else throw mediaError(`${label} returned no image data`, 'MEDIA_EMPTY_RESULT', 502);
+  } catch (error) {
+    throw withReportedUsage(error, usage);
+  }
+  const mime = rasterMime(bytes);
+  if (!mime) {
+    throw withReportedUsage(
+      mediaError(`${label} returned an unsupported image format`, 'MEDIA_UPSTREAM_FAILED', 502),
+      usage
+    );
+  }
+  return { bytes, mime, revisedPrompt: entry.revised_prompt || null, usage };
+}

package/src/runtime/media/auth.mjs

@@ -5,11 +5,74 @@
  * 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';
+import { readSection } from '../shared/config.mjs';
+import {
+  getAgentApiKey,
+  hasAgentApiKey,
+  hasProviderApiKey,
+  resolveProviderApiKey,
+} 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';
+// Both gateways serve the same normalized Image API (GET /images/models,
+// POST /images) under these documented bases.
+const IMAGE_API_BASE_URL = Object.freeze({
+  openrouter: 'https://openrouter.ai/api/v1',
+  'nano-gpt': 'https://api.nano-gpt.com/api/v1',
+});
+
+/** Lanes served by the normalized Image API adapter. */
+export function imageApiLane(laneId) {
+  return Object.hasOwn(IMAGE_API_BASE_URL, laneId);
+}
+
+function nanoGptHost(baseURL) {
+  try {
+    const host = new URL(String(baseURL || '')).hostname.toLowerCase();
+    return host === 'nano-gpt.com' || host.endsWith('.nano-gpt.com');
+  } catch {
+    return false;
+  }
+}
+
+// NanoGPT is not a built-in provider: it is connected as an OpenAI-compatible
+// custom provider, whose key lives under that provider's own id (keychain or
+// its configured environment variable). The first enabled, keyed endpoint on
+// a NanoGPT host is the lane's credential.
+function nanoGptProviders() {
+  const providers = readSection('agent')?.providers || {};
+  return Object.entries(providers).filter(
+    ([id, entry]) =>
+      id.startsWith('custom-') &&
+      entry?.type === 'custom' &&
+      entry.enabled !== false &&
+      entry.auth !== 'none' &&
+      nanoGptHost(entry.baseURL)
+  );
+}
+
+/** Presence-only probe for an Image API lane's key; no secret is read. */
+export function hasImageApiCredentials(laneId) {
+  if (laneId === 'openrouter') return hasAgentApiKey('openrouter');
+  if (laneId === 'nano-gpt') return nanoGptProviders().some(([id, entry]) => hasProviderApiKey(id, entry));
+  return false;
+}
+
+/** Base URL + bearer for an Image API lane (OpenRouter key, or the connected NanoGPT custom provider's key). */
+export function resolveImageApiAuth(laneId) {
+  let token = '';
+  if (laneId === 'openrouter') token = getAgentApiKey('openrouter') || '';
+  else if (laneId === 'nano-gpt') {
+    for (const [id, entry] of nanoGptProviders()) {
+      token = resolveProviderApiKey(id, entry);
+      if (token) break;
+    }
+  }
+  if (!imageApiLane(laneId) || !token) throw unauthenticated(`${laneId} API key is not configured`);
+  return { baseURL: IMAGE_API_BASE_URL[laneId], token };
+}
 
 // Built here rather than with lanes.mjs's mediaError: importing it would close
 // an auth -> lanes -> catalog -> auth module cycle.