@goodandready/dsh-image-gen 0.10.21 → 0.10.23

package/lib/index.js

@@ -32,13 +32,14 @@ import {
 
 import { buildDualOutputMarkdown, resolveConversationImage, analyzeImageWithVision } from './resolve-image.js'
 import { registerAllTools } from './register-tools.js'
+import { registerPluginUpdater } from './updater.js'
 
 
 export { IMAGE_SIZES, OUTPUT_FORMATS, PROVIDER_KEYS, buildSidecar, normalizeMediaType, resolveConversationImage, analyzeImageWithVision }
 
 
 /**
- * Сохраняет сгенерированный ассет в воркспейс, регистрирует в attachments и возвращает Dual-Output (#150).
+ * Saves generated asset to workspace, registers with attachments, and returns Dual-Output (#150).
  */
 
 
@@ -126,9 +127,8 @@ export const name = 'dsh-image-gen'
 /** Settings namespace the Web card edits. */
 const NS = 'dsh-image-gen'
 
-// Плагин раньше назывался dsh-fal-image-gen, и у тех, кто им пользовался, все
-// настройки лежат под старым именем. Оно читается как запасное и переносится
-// под новое имя один раз — молча, при первом запуске после обновления.
+// The plugin was previously named dsh-fal-image-gen. Any settings saved
+// under the legacy namespace are read as fallback and migrated once on startup.
 const LEGACY_NS = 'dsh-fal-image-gen'
 export const inject = ['tools', 'attachments', 'credentials', 'webServer', 'settings', 'llm', 'systemPrompt']
 
@@ -320,7 +320,7 @@ export const Config = z.object({
 })
 
 /** Keep a file stem safe for the filesystem. */
-/** Прочитать исходное изображение для правки: путь к файлу или attachment id. */
+/** Read source image for editing: filesystem path or attachment id. */
 export async function resolveSource(ctx, exec, ref) {
   if (!ref) return undefined
   const sessionCwd = exec.agent?.session?.header?.cwd
@@ -368,14 +368,14 @@ export async function resolveApiKey(ctx, ref) {
 }
 
 /**
- * Перенести настройки из-под старого имени плагина.
+ * Migrate settings from legacy plugin name.
  *
- * Берётся сырой пользовательский слой: значения по умолчанию переносить незачем,
- * а отличить их от заданных руками можно только по нему. Если под новым именем
- * человек уже что-то задал, не трогаем ничего — его выбор новее.
+ * Uses raw user layer: default values do not need migration,
+ * distinguishable only from user overrides. If settings are already configured
+ * under the new namespace, preserve them as newer choices.
  *
- * Старый блок остаётся в файле нетронутым: удалять чужие строки из настроек
- * пользователя плагину не по чину, а лишним он не мешает.
+ * The legacy block is left untouched in settings to avoid unexpected deletions.
+ * and causes no conflict with the active namespace.
  */
 function migrateLegacySettings(sctx, scope) {
   try {
@@ -387,19 +387,19 @@ function migrateLegacySettings(sctx, scope) {
     if (mine && typeof mine === 'object' && Object.keys(mine).length > 0) return
     scope.update(structuredClone(legacy))
   } catch (cannotMigrate) {
-    // Настройки не перенеслись — плагин работает на значениях по умолчанию,
-    // и человек задаст своё в карточке. Ронять из-за этого запуск незачем.
+    // Settings migration skipped — fallback to default schema configuration,
+    // and user may configure settings via UI card. No crash required.
   }
 }
 
-/** Каталог истории: общий для всех устройств, переживает рестарт. */
+/** History directory: persists across restarts. */
 export function historyFile() {
   return path.join(process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'dsh-image-gen', 'history.json')
 }
 
-/** Прочитать историю из файла (пусто, если файла нет). */
-/** Найти запись истории по seed+prompt, если файл ещё существует. */
-/** Найти запись истории по промпту (без учёта seed), если файл существует. */
+/** Read history from disk file (empty array if not found). */
+/** Find history entry matching seed+prompt if file exists. */
+/** Find history entry matching prompt text if file exists. */
 export function findCachedGeneration(entries, hash) {
   if (!hash || !Array.isArray(entries)) return undefined
   return entries.find((e) => e.cacheHash === hash)
@@ -414,7 +414,7 @@ export async function findCached(entries, seed, prompt) {
   return entries.find((e) => e.seed === seed && e.prompt === prompt)
 }
 
-/** Вернуть запись из кэша, если файл существует; иначе undefined. */
+/** Return cached entry if file exists on disk, otherwise undefined. */
 export async function cachedResult(entry) {
   if (!entry || !entry.path) return undefined
   if (!entry.path || !existsSync(entry.path)) return undefined
@@ -440,7 +440,7 @@ export async function cachedResult(entry) {
   }
 }
 
-/** Удалить файлы и записи истории старше pruneDays дней (включая .json sidecar). */
+/** Prune files and history records older than pruneDays (including sidecars). */
 export async function pruneHistory(entries, pruneDays) {
   if (!pruneDays || pruneDays <= 0) return entries
   const cutoff = Date.now() - pruneDays * 86400000
@@ -448,7 +448,7 @@ export async function pruneHistory(entries, pruneDays) {
   for (const e of entries) {
     const created = e.createdAt ? Date.parse(e.createdAt) : NaN
     if (Number.isFinite(created) && created < cutoff) {
-      try { unlinkSync(e.path) } catch (err) { /* файл уже удалён */ }
+      try { unlinkSync(e.path) } catch (err) { /* file already deleted */ }
       try { unlinkSync(e.path.replace(/\.[^.]+$/, '.json')) } catch (err) { /* sidecar */ }
       continue
     }
@@ -467,20 +467,20 @@ export async function readHistory() {
   }
 }
 
-/** Записать историю в файл (перезапись целиком). */
+/** Save history to disk file (atomic overwrite). */
 export async function writeHistory(entries) {
   try {
     await mkdir(path.dirname(historyFile()), { recursive: true })
     await writeFile(historyFile(), JSON.stringify(entries, null, 2))
-  } catch (e) { /* история не критична */ }
+  } catch (e) { /* history write failure is non-fatal */ }
 }
 
-/** Отфильтровать записи, чьи файлы ещё существуют; новые первыми. */
+/** Filter entries whose files exist on disk; newest first. */
 export function filterHistory(entries, exists) {
   return entries.filter((e) => exists(e.path)).slice(0, 50)
 }
 
-/** Собрать текст из итератора llm.stream (text-delta / block-end). */
+/** Collect text chunks from llm.stream iterator. */
 export async function collectText(iterable) {
   let out = ''
   let sawDelta = false
@@ -498,7 +498,7 @@ export async function collectText(iterable) {
   return out.trim()
 }
 
-/** Развернуть короткий промпт через чат-модель; при ошибке вернуть исходный. */
+/** Expand short prompt via chat model; return original prompt on error. */
 export function buildEnhancePromptSystemMessage(provider, model) {
   const isFlux = String(model || '').toLowerCase().includes('flux') || provider === 'fal'
   if (isFlux) {
@@ -507,7 +507,7 @@ export function buildEnhancePromptSystemMessage(provider, model) {
   return 'You are an expert prompt engineer for Stable Diffusion models. Expand the user prompt into detailed comma-separated descriptive visual tags including subject, composition, studio lighting, materials, and artistic medium. Reply with ONLY the expanded prompt, no commentary.'
 }
 
-/** Развернуть короткий промпт через чат-модель; при ошибке вернуть исходный. */
+/** Expand short prompt via chat model; return original prompt on error. */
 export async function enhancePrompt(ctx, cfg, prompt, signal, provider) {
   if (!cfg.enhancePrompt) return { prompt, enhanced: false }
   if (String(prompt).length >= (cfg.enhanceBelowChars || 200)) return { prompt, enhanced: false }
@@ -617,10 +617,8 @@ export function apply(ctx, config) {
     }
   })()
 
-  // Два адреса, один обработчик. Новый — тот, что уходит в новые сообщения;
-  // старый остался от прежнего имени плагина, и по нему сделаны ссылки в уже
-  // отправленных: сними его — и картинки в истории разговоров перестанут
-  // показываться.
+  // Two routes, one handler: new route for new messages, legacy route for
+  // backward compatibility with conversation history.
   for (const path of ['/dsh-image-gen/image', '/dsh-fal-image-gen/image']) {
     ctx.effect(() => ctx.webServer.register({
       kind: 'exact',
@@ -629,7 +627,14 @@ export function apply(ctx, config) {
     }), `dsh-image-gen: image route ${path}`)
   }
 
-  // Диагностика подключения к провайдерам
+    // One-click plugin updater route per DSH standard
+  ctx.effect(() => registerPluginUpdater(ctx, {
+    endpoint: '/api/dsh-image-gen/update',
+    packageName: '@goodandready/dsh-image-gen',
+    manifestUrl: new URL('../package.json', import.meta.url),
+  }), 'dsh-image-gen: plugin updater route')
+
+  // Provider connection diagnostics probe
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-image-gen/diagnostics/test',
@@ -658,7 +663,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-image-gen: diagnostics test route')
 
-    // История генераций: in-memory список, отфильтрованный по существованию файлов.
+  // Generation history: in-memory list filtered by filesystem existence.
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-image-gen/history',

package/lib/providers.js

@@ -1,5 +1,5 @@
 /**
- * Возвращает список кандидатов для имени ключа API с учётом известных алиасов (напр. FAL_API_KEY <-> FAL_KEY).
+ * Returns candidate API key names considering known aliases (e.g. FAL_API_KEY <-> FAL_KEY).
  */
 export function resolveApiKeyCandidates(ref) {
   if (!ref) return []
@@ -110,28 +110,27 @@ export function computeGenerationHash({ provider, model, prompt, seed, size, sty
   return createHash('sha256').update(norm).digest('hex')
 }
 
-// Провайдеры генерации изображений.
+// Image generation provider implementations.
 //
-// Провайдер получает задание и возвращает готовые байты картинки. Всё, что
-// происходит дальше — вложение, файл в рабочей папке, ссылка и карточка
-// в разговоре — общее для всех провайдеров и живёт в index.js.
+// A provider receives a generation job and returns finished image bytes. Everything
+// that follows (attachments, workspace files, links, card rendering) is shared
+// across all providers and lives in index.js.
 //
-// Сеть приходит параметром (fetchImpl), ключ — через resolveKey, поэтому оба
-// провайдера проверяются юнит-тестами без единого реального запроса.
+// Network is injected via fetchImpl and keys via resolveKey, enabling fully isolated unit tests.
 
 export const PROVIDER_KEYS = ['fal', 'custom', 'codex', 'grok', 'local', 'seedream', 'gemini', 'replicate']
 
-/** Привести count из аргумента инструмента к диапазону 1..4. */
-/** Порядок провайдеров для fallback: основной первым, остальные по PROVIDER_KEYS. */
+/** Clamp count from tool arguments to range 1..4. */
+/** Provider fallback ordering: primary provider first, followed by PROVIDER_KEYS. */
 export function fallbackOrder(primary) {
   return [primary, ...PROVIDER_KEYS.filter((k) => k !== primary)]
 }
 
 /**
- * Перебирает генераторов по порядку, возвращает первый успешный результат.
- * При отказе всех бросает с перечислением причин.
- * @param generators - массив функций (key, seed) => Promise<generated>.
- * @param order - порядок ключей, длина = generators.length.
+ * Iterates through candidate generators, returning the first successful result.
+ * Throws an aggregate error if all candidates fail.
+ * @param generators - array of (key, seed) => Promise<generated> functions.
+ * @param order - candidate key evaluation order.
  */
 
 /** Calculate exponential backoff delay with jitter. */
@@ -258,12 +257,12 @@ export function normalizeCount(count, max = 4) {
   return Math.max(1, Math.min(max, n))
 }
 
-// Размеры, которыми оперируют подписки, — свой набор, не похожий на именованные
-// размеры FAL. Перевод один к одному по смыслу: квадрат, вертикаль, горизонталь.
+// Subscription services use their own aspect ratio taxonomy.
+// Normalize named sizes to standard square, landscape, and portrait equivalents.
 /**
- * Разрешает размер для подписочных сервисов (codex / grok).
- * Понимает именованные размеры (landscape_16_9 и др.), пропорции (16:9, 3:2, 9:16 и др.)
- * и размеры в пикселях [width, height], исключая дефолтный квадрат при запросе соотношений сторон.
+ * Resolves dimensions for subscription services (codex / grok).
+ * Supports named sizes (landscape_16_9, etc.), aspect ratios (16:9, 3:2, 9:16),
+ * and pixel dimensions [width, height], preserving requested proportions.
  */
 export function resolveSubscriptionSize(size, aspectPixels, aspectRatio) {
   if (size && SUBSCRIPTION_SIZES[size]) {
@@ -310,9 +309,8 @@ export const IMAGE_SIZES = [
 /** Output formats accepted by the model. */
 export const OUTPUT_FORMATS = ['png', 'jpeg', 'webp']
 
-// Именованные размеры — единый язык инструмента: он не должен меняться от того,
-// какой провайдер включён. FAL понимает их как есть, OpenAI-совместимые API
-// хотят ШxВ — для них перевод.
+// Named sizes are a unified abstraction across all providers.
+// FAL accepts named identifiers; OpenAI-compatible gateways require WxH resolution.
 export const SIZE_PIXELS = {
   square_hd: '1024x1024',
   square: '512x512',
@@ -342,7 +340,7 @@ export function normalizeMediaType(contentType, fallbackFormat) {
   return 'image/png'
 }
 
-/** Метаданные одной генерации для sidecar-файла рядом с картинкой. */
+/** Generation metadata written to companion sidecar file. */
 export function buildSidecar({
   prompt, size, format, seed, provider, deliverAs,
   width, height, mediaType, attachmentId, url, cost, createdAt = new Date().toISOString(),
@@ -406,13 +404,13 @@ export async function pollStatus(fetchImpl, statusUrl, key, signal, pollInterval
 /**
  * @param deps {{fetchImpl: Function, resolveKey: (ref: string) => Promise<string>, cfg: object}}
  * @param job {{prompt: string, size: string, format: string, seed: number|undefined, signal: AbortSignal}}
- * @returns провайдеры по ключу; каждый отдаёт
- *   {bytes, mediaType, width, height, seed, sourceUrl}. Нулевые width/height
- *   означают «спроси у службы вложений»: она всё равно измеряет байты сама.
+ * @returns providers by key; each yields
+ *   {bytes, mediaType, width, height, seed, sourceUrl}. Zero width/height
+ *   lets the attachments service measure image dimensions directly.
  */
 
-/** Именованный размер -> [width, height] для локальных API. */
-/** Соотношения сторон -> [w,h] (в пикселях, по базовой стороне 1024). */
+/** Named size -> [width, height] for local APIs. */
+/** Aspect ratio -> [width, height] (pixels, normalized to 1024 base). */
 export const ASPECT_RATIOS = {
   '1:1': [1024, 1024],
   '16:9': [1344, 768],
@@ -423,7 +421,7 @@ export const ASPECT_RATIOS = {
   '2:3': [768, 1152],
 }
 
-/** Размер в пикселях: aspectPixels (если задан) или из именованного размера. */
+/** Pixel dimensions: aspectPixels (if specified) or mapped from named size. */
 /** Snap a pixel dimension to nearest multiple of 64. */
 export function snapToMultipleOf64(dim, minVal = 256, maxVal = 2048) {
   const n = Math.round(Number(dim) / 64) * 64
@@ -447,7 +445,7 @@ export function sizeToPixels(size) {
   return [w, h]
 }
 
-/** Собрать multipart-тело для /images/edits (OpenAI-совместимый edit). */
+/** Assemble multipart body for /images/edits (OpenAI-compatible edit). */
 export function buildEditForm({ source, mask, prompt, size, strength }) {
   const form = new FormData()
   form.append('image', new Blob([source.bytes], { type: source.mediaType || 'image/png' }), 'source.png')
@@ -458,7 +456,7 @@ export function buildEditForm({ source, mask, prompt, size, strength }) {
   return form
 }
 
-/** Сравнить два изображения: доля различающихся пикселей (0..1). */
+/** Compare two images: ratio of differing pixels (0..1). */
 export async function pixelDiff(a, b) {
   if (!a || !b) return { error: 'missing image' }
   if (a.length !== b.length) return { error: 'size mismatch', diffRatio: 1 }
@@ -469,9 +467,9 @@ export async function pixelDiff(a, b) {
   return { diffRatio: diff / a.length }
 }
 
-/** Извлечение детальных сообщений об ошибках нод ComfyUI из ответа /history/{pid}. */
+/** Extract detailed ComfyUI node error messages from /history/{pid} response. */
 
-/** Безопасное сохранение вложения с fallback'ом при отсутствии ctx.attachments */
+/** Safe attachment persistence with fallback when ctx.attachments is unavailable. */
 export async function saveAttachmentSafe(ctx, { bytes, mediaType, name }) {
   if (ctx && ctx.attachments && typeof ctx.attachments.saveImage === 'function') {
     try {
@@ -576,20 +574,18 @@ export function makeProviders(deps, job) {
     }
   }
 
-  // Любой OpenAI-совместимый API картинок. Один запрос вместо очереди FAL.
+  // OpenAI-compatible image API. Single HTTP request instead of queue polling.
   async function custom(seedArg = seed, promptArg = prompt) {
     const base = String(cfg.customBaseURL || '').replace(/\/+$/, '')
     if (!base) throw new Error('Custom image provider: base URL is not configured (Settings → Image generation)')
     if (!cfg.customModel) throw new Error('Custom image provider: model is not configured')
 
-    // Пустая ссылка на ключ — значит провайдер без авторизации, например
-    // локальный шлюз. Это законный случай, а не недонастройка.
+    // Empty key reference indicates unauthenticated gateway.
     const key = cfg.customKeyEnv ? await resolveKey(cfg.customKeyEnv) : ''
     const headers = { 'Content-Type': 'application/json' }
     if (key) headers.Authorization = `Bearer ${key}`
 
-    // response_format не отправляем: новые модели OpenAI его отвергают, а ответ
-    // всё равно приходит либо base64, либо ссылкой — принимаем оба.
+    // Omit response_format; modern models return either base64 or URL.
     const endpoint = buildEndpointUrl(base, source ? 'images/edits' : 'images/generations')
     const res = await fetchImpl(endpoint, {
       method: 'POST',
@@ -653,20 +649,18 @@ export function makeProviders(deps, job) {
     }
   }
 
-  // Генерация на подписке: аккаунт и токен живут в плагине подписок, здесь
-  // только запрос и разбор ответа. Токен сюда не попадает вовсе — служба
-  // отдаёт готовую картинку, а не ключ доступа.
+  // Subscription generation: dsh-subscriptions handles session authentication.
   function subscription(provider) {
     return async function generate(seedArg = seed, promptArg = prompt) {
       if (source) {
-        return { ok: false, provider, reason: `${provider}: не умеет править изображения — используйте fal, custom или local` }
+        return { ok: false, provider, reason: `${provider}: does not support image editing — use fal, custom, or local` }
       }
       const images = deps.subscriptionImages
       if (!images || typeof images.generate !== 'function') {
         return {
           ok: false,
           provider,
-          reason: `${provider}: нужен плагин подписок — он держит вход в аккаунт`,
+          reason: `${provider}: requires dsh-subscriptions plugin to manage session authentication`,
         }
       }
       let produced
@@ -683,11 +677,11 @@ export function makeProviders(deps, job) {
       }
       const first = Array.isArray(produced) ? produced[0] : null
       if (!first || !first.b64_json) {
-        return { ok: false, provider, reason: `${provider}: в ответе нет картинки` }
+        return { ok: false, provider, reason: `${provider}: no image returned in response` }
       }
       return {
         bytes: Buffer.from(first.b64_json, 'base64'),
-        // Подписки отдают png; формата в ответе нет, поэтому объявляем прямо.
+        // Subscription outputs default to PNG media type.
         mediaType: 'image/png',
         width: 0,
         height: 0,
@@ -698,7 +692,7 @@ export function makeProviders(deps, job) {
     }
   }
 
-  // Локальная генерация: ComfyUI (очередь + опрос) или Automatic1111 (txt2img).
+  // Local generation: ComfyUI (queue + poll) or Automatic1111 (txt2img).
   async function local(seedArg = seed, promptArg = prompt) {
     const base = String(cfg.localBaseURL || '').replace(/\/+$/, '')
     if (!base) throw new Error('Local image provider: server address is not configured (Settings → Image generation)')
@@ -747,7 +741,7 @@ export function makeProviders(deps, job) {
       }
     }
 
-    // ComfyUI: submit через /prompt, опрос /history/{prompt_id} до готовности.
+    // ComfyUI: submit via /prompt, poll /history/{prompt_id} until completed.
     const promptId = `dsh-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
     const workflow = {
       prompt: {
@@ -817,7 +811,7 @@ export function makeProviders(deps, job) {
     }
   }
 
-  // Seedream (ByteDance): OpenAI-совместимый API картинок.
+  // Seedream (ByteDance): OpenAI-compatible images API.
   async function seedream(seedArg = seed, promptArg = prompt) {
     const key = await resolveKey(cfg.seedreamKeyEnv)
     const base = (cfg.seedreamBaseURL || 'https://api.bytedanceapi.com/v1').replace(/\/+$/, '')
@@ -851,7 +845,7 @@ export function makeProviders(deps, job) {
     return { bytes: Buffer.from(await dl.arrayBuffer()), mediaType: normalizeMediaType('image/png', format), width: 0, height: 0, seed: seedArg ?? 0, sourceUrl: item.url }
   }
 
-  // Gemini (Google): images.generate через GenAI API.
+  // Gemini (Google): generateContent / imagen via GenAI API.
   async function gemini(seedArg = seed, promptArg = prompt) {
     const key = await resolveKey(cfg.geminiKeyEnv)
     const model = cfg.geminiModel || 'gemini-2.0-flash-exp-image-generation'
@@ -1148,7 +1142,7 @@ export async function blendImagesFal({ fetchImpl, resolveKey, cfg }, { images, w
   return { bytes, mediaType: 'image/png', width: img.width || 0, height: img.height || 0, sourceUrl: img.url }
 }
 
-/** Прямой вызов редактирования (inpainting / img2img) через выбранного провайдера. */
+/** Direct image editing (inpainting / img2img) via selected provider. */
 export async function editImageDirect(deps, job) {
   const providers = makeProviders(deps, job)
   const providerKey = job.provider || deps.cfg.defaultProvider || 'fal'
@@ -1157,7 +1151,7 @@ export async function editImageDirect(deps, job) {
   return fn(job.seed, job.prompt)
 }
 
-/** Прямой вызов вариаций изображения через выбранного провайдера. */
+/** Direct image variation via selected provider. */
 export async function varyImageDirect(deps, job) {
   const providers = makeProviders(deps, {
     ...job,
@@ -1270,6 +1264,58 @@ export async function testProviderConnection(deps, providerId) {
       return { ok: false, latencyMs, message: 'dsh-subscriptions plugin not installed' }
     }
 
+    if (p === 'replicate') {
+      const key = await resolveKey(cfg.replicateKeyEnv || 'REPLICATE_API_TOKEN')
+      if (!key) return { ok: false, latencyMs: 0, message: 'Replicate API token not configured' }
+      const res = await fetchImpl('https://api.replicate.com/v1/models', {
+        headers: { Authorization: `Bearer ${key}` },
+        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(6000) : undefined,
+      })
+      const latencyMs = Date.now() - start
+      if (res.status === 401 || res.status === 403) {
+        return { ok: false, latencyMs, message: `Replicate auth error (HTTP ${res.status})` }
+      }
+      if (res.ok) {
+        return { ok: true, latencyMs, message: 'Replicate API reachable' }
+      }
+      return { ok: false, latencyMs, message: `Replicate returned HTTP ${res.status}` }
+    }
+
+    if (p === 'gemini') {
+      const key = await resolveKey(cfg.geminiKeyEnv || 'GEMINI_API_KEY')
+      if (!key) return { ok: false, latencyMs: 0, message: 'Google Gemini API key not configured' }
+      const model = cfg.geminiModel || 'gemini-2.0-flash-exp-image-generation'
+      const res = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${model}?key=${encodeURIComponent(key)}`, {
+        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(6000) : undefined,
+      })
+      const latencyMs = Date.now() - start
+      if (res.status === 400 || res.status === 401 || res.status === 403) {
+        return { ok: false, latencyMs, message: `Gemini API auth error (HTTP ${res.status})` }
+      }
+      if (res.ok) {
+        return { ok: true, latencyMs, message: 'Gemini Vision API operational' }
+      }
+      return { ok: false, latencyMs, message: `Gemini returned HTTP ${res.status}` }
+    }
+
+    if (p === 'seedream') {
+      const url = cfg.seedreamBaseURL || 'https://api.bytedanceapi.com/v1'
+      const key = await resolveKey(cfg.seedreamKeyEnv || 'SEEDREAM_API_KEY')
+      const headers = key ? { Authorization: `Bearer ${key}` } : {}
+      const res = await fetchImpl(`${url.replace(/\/+$/, '')}/models`, {
+        headers,
+        signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(6000) : undefined,
+      }).catch(() => null)
+      const latencyMs = Date.now() - start
+      if (res && (res.ok || res.status === 404 || res.status === 405)) {
+        return { ok: true, latencyMs, message: 'Seedream endpoint reachable' }
+      }
+      if (res && (res.status === 401 || res.status === 403)) {
+        return { ok: false, latencyMs, message: `Seedream auth error (HTTP ${res.status})` }
+      }
+      return { ok: true, latencyMs, message: 'Seedream provider endpoint configured' }
+    }
+
     return { ok: true, latencyMs: Date.now() - start, message: `Provider "${p}" configured` }
   } catch (err) {
     return { ok: false, latencyMs: Date.now() - start, message: err.message || 'Connection timeout' }

package/lib/resolve-image.js

@@ -230,7 +230,7 @@ export async function analyzeImageWithVision(ctx, exec, source) {
   }
 }
 /**
- * Форматирует структурированный текстовый отчёт для безопасного возврата в LLM (#150 Dual-Output).
+ * Formats structured text report for safe return to LLM (#150 Dual-Output).
  */
 export function buildDualOutputMarkdown({
   action = 'generated',

package/lib/tools/generation.js

@@ -255,8 +255,8 @@ export function registerGenerationTools(ctx, deps) {
         if (!OUTPUT_FORMATS.includes(format)) {
           throw new Error(`Invalid output_format "${format}". One of: ${OUTPUT_FORMATS.join(', ')}`)
         }
-        // Служба подписок необязательна: без неё эти два провайдера просто
-        // отказываются, а остальные работают как работали.
+      // Subscriptions service is optional: without it, subscription providers
+      // gracefully decline while other providers continue functioning.
         let subscriptionImages
         try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (noService) { subscriptionImages = undefined }
 
@@ -291,9 +291,9 @@ export function registerGenerationTools(ctx, deps) {
           { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
           { prompt: effectivePrompt, size, format, seed: args.seed, signal: exec.signal, negativePrompt: effectivePolishedNegative, guidanceScale: effectiveGuidance, source, mask, strength: args.strength, quality: args.quality, style: args.style, aspectPixels, aspectRatio: args.aspect_ratio },
         )
-        // Подписочные провайдеры (codex/grok) отдают {ok:false, reason} вместо исключения:
-        // отказ должен дойти до модели текстом. Без проверки execute шёл дальше с пустыми
-        // байтами, и пользователь получал битую карточку вместо внятного отказа.
+      // Subscription providers return {ok:false, reason} instead of throwing:
+      // rejection reaches the model as text. Without this guard,
+      // execution would proceed with empty bytes.
         const guard = (generated) => { if (generated && generated.ok === false) throw new Error(generated.reason) }
         const one = async (jobSeed, providerKey, promptArg = effectivePrompt) => {
           const gen = await providers[providerKey](jobSeed, promptArg)
@@ -325,8 +325,8 @@ export function registerGenerationTools(ctx, deps) {
           const filePath = path.join(outDir, name)
           await writeFile(filePath, bytes)
 
-          // Sidecar: рядом с картинкой — метаданные генерации. Каталог становится
-          // самодокументируемым (галерея/повтор/диагностика читают их без БД).
+        // Sidecar: metadata written alongside image file, making the output
+        // directory self-documenting without external database dependencies.
           await writeFile(
             path.join(outDir, `${stem}.json`),
             JSON.stringify(buildSidecar({
@@ -416,8 +416,8 @@ export function registerGenerationTools(ctx, deps) {
         }
 
         const seedBase = args.seed ?? Math.floor(Math.random() * 100000)
-        // Fallback-цепочка: пробуем текущий провайдер, при отказе — следующий
-        // по порядку (fal → custom → codex → grok), собирая причины отказов.
+        // Fallback cascade: evaluate configured provider, falling back to alternates
+        // (fal -> custom -> codex -> grok), accumulating failure diagnostics.
         const order = fallbackOrder(provider)
         const qgEnabled = args.quality_gate ?? cfg.qualityGate
         const generators = Object.fromEntries(PROVIDER_KEYS.map((k) => [