Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

8.8 KB
Raw Blame
/**
 * Image Gen — mode enum.
 *
 * Standalone so the dispatcher (`index.js`) and the provider modules
 * (`codex.js`, `local.js`, `external.js`) can both import without forming a
 * cycle (index.js already imports from each provider).
 *
 * `IMAGE_GEN_MODE.X` is the preferred form at branching/tagging sites.
 * `IMAGE_GEN_MODES` is the alphabet for Zod / OpenAI tool-spec enums.
 * Single source of truth: derive the array from `Object.values(...)`.
 *
 * The backend alphabets live in `lib/generationModes.js` and the per-backend
 * capability literals in `lib/imageGenCapabilities.js`, both below validation
 * and this service module. They are re-exported here so existing generation
 * callers keep the same service-local import path.
 */

import { ServerError } from '../../lib/errorHandler.js';
import {
  CLOUD_IMAGE_GEN_MODES, IMAGE_GEN_MODE, IMAGE_GEN_MODES, QUEUEABLE_IMAGE_MODES,
} from '../../lib/generationModes.js';
import {
  AGY_ASPECT_RATIOS,
  AGY_IMAGEGEN_DEFAULT_MODEL,
  AGY_IMAGEGEN_IMAGE_MODEL,
  CODEX_IMAGEGEN_DEFAULT_EFFORT,
  CODEX_IMAGEGEN_DEFAULT_MODEL,
  EDIT_INCAPABLE_IMAGE_MODES,
  LOCAL_IMAGEGEN_DEFAULT_MODEL,
  isEditCapableMode,
} from '../../lib/imageGenCapabilities.js';

export {
  CLOUD_IMAGE_GEN_MODES, IMAGE_GEN_MODE, IMAGE_GEN_MODES, QUEUEABLE_IMAGE_MODES,
};

// The per-backend capability literals live in `lib/imageGenCapabilities.js`,
// a dependency-free leaf the browser bundle can import — this module cannot be,
// because `editIncapableModeError` below needs `ServerError` and through it
// Node's `events`. Re-exported here so every existing service-local import site
// keeps its path.
export {
  AGY_ASPECT_RATIOS,
  AGY_IMAGEGEN_DEFAULT_MODEL,
  AGY_IMAGEGEN_IMAGE_MODEL,
  CODEX_IMAGEGEN_DEFAULT_EFFORT,
  CODEX_IMAGEGEN_DEFAULT_MODEL,
  EDIT_INCAPABLE_IMAGE_MODES,
  // The local runner's fallback model id. Re-exported so provenance writers
  // (sprite candidate sidecars, #2896) keep their service-local import path.
  LOCAL_IMAGEGEN_DEFAULT_MODEL,
  isEditCapableMode,
};

// The provider-side image tool each cloud CLI is directed to call. Single
// source: the prompt builders name it, the fabrication guard names it when it
// rejects a code-drawn stand-in, and the usage card labels its quota row with
// it — six string literals before this existed. Grok is the one backend with
// two, picked by whether the render has any input image.
export const IMAGE_TOOL_NAMES = Object.freeze({
  [IMAGE_GEN_MODE.AGY]: 'generate_image',
  [IMAGE_GEN_MODE.GROK]: 'image_gen',
  [IMAGE_GEN_MODE.CODEX]: 'image_gen',
});

/**
 * Grok's tool depends on the direction: anything with an input image goes to
 * `image_edit`. Grok's `image_gen` schema has NO image parameter at all (probed
 * 2026-08-09), so a reference-only render must route to `image_edit` too — its
 * `image` parameter is an array of references, not a single source.
 */
export const grokImageTool = (hasInputImage) => (hasInputImage ? 'image_edit' : IMAGE_TOOL_NAMES[IMAGE_GEN_MODE.GROK]);

/**
 * The clause every cloud-CLI prompt uses to say what a reference image is FOR.
 * Shared (like describeFidelity) so the three prompt builders describe
 * reference conditioning identically and agree on singular/plural.
 */
export const visualReferenceRole = (count) => (count === 1
  ? 'a visual reference for style, characters, and subject matter'
  : 'visual references for style, characters, and subject matter');

/**
 * Cloud image backends the user has enabled in Settings → Image Gen. Hoisted
 * here so callers outside the dispatcher (the usage card) don't re-encode how
 * a backend is enabled — `settings.imageGen[mode].enabled` was already spelled
 * out at a dozen sites and drifts the moment enablement grows a nuance.
 */
export const enabledCloudImageModes = (settings) =>
  CLOUD_IMAGE_GEN_MODES.filter((mode) => settings?.imageGen?.[mode]?.enabled === true);

/**
 * Human-facing backend names — the server half of the client's MODE_LABELS
 * (client/src/lib/imageGenModes.js). A map rather than a capitalization of the
 * mode id, so a backend whose id isn't a single lowercase word ('lm-studio')
 * still gets a real name instead of 'Lm-studio'.
 */
const MODE_LABELS = Object.freeze({
  [IMAGE_GEN_MODE.LOCAL]: 'Local',
  [IMAGE_GEN_MODE.CODEX]: 'Codex',
  [IMAGE_GEN_MODE.GROK]: 'Grok',
  [IMAGE_GEN_MODE.AGY]: 'Agy',
  [IMAGE_GEN_MODE.FAL]: 'fal.ai',
  [IMAGE_GEN_MODE.RUNWAY]: 'Runway',
  [IMAGE_GEN_MODE.EXTERNAL]: 'External',
});

/**
 * Sentence-case backend name for user-facing messages ('Codex', 'Agy', …).
 * Shared so error messages don't grow a per-backend ternary ladder each time a
 * backend is added, and so one backend never appears under two names across
 * the UI. Falls back to 'This' for an absent mode, which reads correctly in
 * `editIncapableModeError`'s sentence.
 */
export const modeLabel = (mode) => MODE_LABELS[mode] || mode || 'This';

/**
 * The one 400 for "this backend was handed an input image and cannot take one".
 *
 * Four verbatim copies of this throw existed — `agy.js`, the dispatcher,
 * `prepareParams.js` and the imageGen route — before the sprite reference paths
 * needed a fifth (#3331), so it now lives beside the predicate that decides it.
 * Every caller gates on `isEditCapableMode`, so adding a backend to
 * EDIT_INCAPABLE_IMAGE_MODES still stays a one-line change.
 */
export const editIncapableModeError = (mode) => new ServerError(
  `${modeLabel(mode)} image generation supports text-to-image only`,
  { status: 400, code: 'IMAGE_EDIT_UNSUPPORTED_MODE' },
);

// Cloud-CLI providers expose no numeric i2i denoise knob, so map the
// local-runner-style strength (0..1, lower = more faithful to the source)
// onto a phrase the model reliably honors. Mirrors
// PROOF_AS_BASE_DEFAULT_STRENGTH (0.25) defaulting toward
// composition-preserving edits. Lives here (the shared no-dependency module)
// so codex.js and grok.js both import it without a provider→provider import.
export const describeFidelity = (strength) => {
  const n = Number.isFinite(strength) ? Math.max(0, Math.min(1, Number(strength))) : 0.25;
  if (n <= 0.2) return 'preserve composition, characters, and layout exactly — only refine detail and resolution';
  if (n <= 0.4) return 'preserve composition and characters while adding rendered detail at higher fidelity';
  if (n <= 0.7) return 'use the attached image as a strong reference while refining art and detail';
  return 'use the attached image as a loose reference; you may reinterpret freely';
};

/**
 * Map a pixel width/height onto the closest ratio in `ratios` ('W:H' strings).
 * Returns null when either dimension is missing or non-positive, so the caller
 * omits its ratio directive entirely rather than asserting one the user never
 * chose (each tool then applies its own documented default).
 *
 * Lives here rather than in a provider module because every cloud CLI needs the
 * same mapping against its own alphabet — grok's `deriveAspectRatio` delegates
 * to it, and agy's prompt builder calls it with AGY_ASPECT_RATIOS.
 */
export function nearestAspectRatio(width, height, ratios) {
  const w = Number(width);
  const h = Number(height);
  if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0) return null;
  const target = w / h;
  let best = null;
  let bestDelta = Infinity;
  for (const ratio of ratios) {
    const [rw, rh] = ratio.split(':').map(Number);
    const delta = Math.abs((rw / rh) - target);
    if (delta < bestDelta) {
      bestDelta = delta;
      best = ratio;
    }
  }
  return best;
}

/** `nearestAspectRatio` bound to agy's alphabet. */
export const nearestAgyAspectRatio = (width, height) => nearestAspectRatio(width, height, AGY_ASPECT_RATIOS);

/**
 * Resolve the queue-capable image mode for a render request: the per-request
 * override (honored only when that backend is enabled/available), else the
 * saved dispatcher default, else the first enabled cloud backend in
 * CLOUD_IMAGE_GEN_MODES order (codex → grok → agy → fal → runway) → local. External
 * never queues. Hoisted from the pipeline visual stages (#2896) so sprite renders and
 * any future queued surface share one enable-gating ladder — see issue #2881
 * for the wider param-assembly consolidation.
 *
 * There is no separate edit-mode ladder: every queueable backend accepts input
 * images (see EDIT_INCAPABLE_IMAGE_MODES), so an i2i render resolves through
 * this exact same ladder.
 */
export function resolveQueueImageMode(requested, settings) {
  const cloudEnabled = (mode) => CLOUD_IMAGE_GEN_MODES.includes(mode) && settings?.imageGen?.[mode]?.enabled === true;
  if (cloudEnabled(requested)) return requested;
  if (requested === IMAGE_GEN_MODE.LOCAL) return IMAGE_GEN_MODE.LOCAL;
  const settingsMode = settings?.imageGen?.mode;
  if (cloudEnabled(settingsMode)) return settingsMode;
  if (settingsMode === IMAGE_GEN_MODE.LOCAL) return IMAGE_GEN_MODE.LOCAL;
  return CLOUD_IMAGE_GEN_MODES.find(cloudEnabled) || IMAGE_GEN_MODE.LOCAL;
}