@goodandready/dsh-image-gen 0.8.0

package/lib/index.js

@@ -0,0 +1,389 @@
+// dsh-image-gen: a `generate_image` tool with pluggable providers.
+//
+// A provider turns a prompt into image bytes; everything after that is shared:
+//   1. save the bytes through ctx.attachments (renders in the conversation);
+//   2. write a durable copy under <workspace>/<outputDir>;
+//   3. hand the tool card a same-origin URL that outlives the provider's link.
+//
+// Providers live in providers.js — the FAL queue protocol and any
+// OpenAI-compatible images API. Which one runs is the `provider` setting.
+//
+// API keys are resolved per call through the credentials service (Settings ->
+// Credentials, or $DSH_HOME/.credentials.yaml) under the configured reference,
+// falling back to the process environment.
+
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import {
+  IMAGE_SIZES,
+  OUTPUT_FORMATS,
+  PROVIDER_KEYS,
+  makeProviders,
+  normalizeMediaType,
+} from './providers.js'
+
+export { IMAGE_SIZES, OUTPUT_FORMATS, PROVIDER_KEYS, normalizeMediaType }
+
+export const name = 'dsh-image-gen'
+
+/** Settings namespace the Web card edits. */
+const NS = 'dsh-image-gen'
+
+// Плагин раньше назывался dsh-fal-image-gen, и у тех, кто им пользовался, все
+// настройки лежат под старым именем. Оно читается как запасное и переносится
+// под новое имя один раз — молча, при первом запуске после обновления.
+const LEGACY_NS = 'dsh-fal-image-gen'
+export const inject = ['tools', 'attachments', 'credentials', 'webServer', 'settings']
+
+export const Config = z.object({
+  provider: z
+    .string()
+    .description(`Which provider generates the image. One of: ${PROVIDER_KEYS.join(', ')}. `
+      + '"fal" uses the FAL queue below; "custom" uses the OpenAI-compatible API configured under it.')
+    .default('fal'),
+  model: z
+    .string()
+    .description('FAL model id, called as {baseURL}/{model}.')
+    .default('fal-ai/flux-2/klein/9b'),
+  apiKeyEnv: z
+    .string()
+    .description('Credential reference / env var holding the FAL API key (the "Key " auth prefix is added automatically when missing).')
+    .default('FAL_API_KEY'),
+  baseURL: z
+    .string()
+    .description('FAL queue base URL.')
+    .default('https://queue.fal.run'),
+  defaultSize: z
+    .string()
+    .description(`Default image size when the tool call omits image_size. One of: ${IMAGE_SIZES.join(', ')}.`)
+    .default('landscape_4_3'),
+  defaultFormat: z
+    .string()
+    .description(`Default output format. One of: ${OUTPUT_FORMATS.join(', ')}.`)
+    .default('png'),
+  pollIntervalMs: z
+    .number()
+    .description('Status polling interval in milliseconds.')
+    .default(2000),
+  timeoutMs: z
+    .number()
+    .description('Total generation timeout in milliseconds (submit + poll + download).')
+    .default(180000),
+  deliverAs: z
+    .string()
+    .description(
+      'How the finished image reaches the conversation. '
+      + '"link": the tool returns a link and the card renders the picture from it — the chat model only ever sees text, so this works with any model. '
+      + '"image": the tool returns the image itself — the picture is part of the result, which a text-only chat model cannot read, so this mode needs dsh-vision-bridge (or a vision-capable chat model).'
+    )
+    .default('link'),
+  customBaseURL: z
+    .string()
+    .description('provider=custom: API root without a trailing slash, e.g. https://api.openai.com/v1. '
+      + 'The request goes to {customBaseURL}/images/generations.')
+    .default(''),
+  customModel: z
+    .string()
+    .description('provider=custom: model id, e.g. gpt-image-1.')
+    .default(''),
+  customKeyEnv: z
+    .string()
+    .description('provider=custom: credential reference / env var holding the API key. '
+      + 'Empty means no authorization header, for gateways that need none.')
+    .default('OPENAI_API_KEY'),
+  subscriptionQuality: z
+    .string()
+    .description('provider=codex or grok: quality asked of the subscription — low, medium, high or empty '
+      + 'for the provider default.')
+    .default(''),
+  customSize: z
+    .string()
+    .description('provider=custom: fixed size sent to the API, e.g. 1024x1024. '
+      + 'Empty means the named size is translated automatically — set this only for an API picky about sizes.')
+    .default(''),
+  outputDir: z
+    .string()
+    .description('Where generated images are saved. A relative path resolves against the session working directory; an absolute path is used as given.')
+    .default('generated/images'),
+})
+
+/** Keep a file stem safe for the filesystem. */
+export function slugify(input) {
+  const stem = String(input ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\u0400-\u04ff]+/gi, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+  return stem || 'image'
+}
+
+/** Resolve an API key for one call (credentials service first, then env). */
+export async function resolveApiKey(ctx, ref) {
+  if (!ref) return ''
+  try {
+    const resolved = await ctx.credentials.resolve(credentialRef(ref))
+    if (resolved && resolved.value) return resolved.value
+  } catch {
+    // fall through to the environment
+  }
+  const fromEnv = process.env[ref]
+  if (fromEnv) return fromEnv
+  throw new Error(
+    `API key not configured: set credential/env "${ref}" (Web: Settings → Credentials, or add "${ref}: <key>" to $DSH_HOME/.credentials.yaml)`,
+  )
+}
+
+/**
+ * Перенести настройки из-под старого имени плагина.
+ *
+ * Берётся сырой пользовательский слой: значения по умолчанию переносить незачем,
+ * а отличить их от заданных руками можно только по нему. Если под новым именем
+ * человек уже что-то задал, не трогаем ничего — его выбор новее.
+ *
+ * Старый блок остаётся в файле нетронутым: удалять чужие строки из настроек
+ * пользователя плагину не по чину, а лишним он не мешает.
+ */
+function migrateLegacySettings(sctx, scope) {
+  try {
+    const readSection = sctx.settings.section
+    if (typeof readSection !== 'function') return
+    const legacy = readSection.call(sctx.settings, LEGACY_NS)
+    if (!legacy || typeof legacy !== 'object' || Object.keys(legacy).length === 0) return
+    const mine = readSection.call(sctx.settings, NS)
+    if (mine && typeof mine === 'object' && Object.keys(mine).length > 0) return
+    scope.update(structuredClone(legacy))
+  } catch (cannotMigrate) {
+    // Настройки не перенеслись — плагин работает на значениях по умолчанию,
+    // и человек задаст своё в карточке. Ронять из-за этого запуск незачем.
+  }
+}
+
+export function apply(ctx, config) {
+
+  // The Web card edits this namespace; without registering it the card binds to
+  // a namespace nobody declared, stays unready and renders nothing — which is
+  // why the plugin's settings tab was empty. Reading through getConfig() also
+  // means an edit applies to the next call instead of after a restart.
+  let getConfig = () => config
+  const live = () => Config(structuredClone(getConfig() ?? {})) ?? config
+
+  ctx.inject(['settings'], (sctx) => {
+    const scope = sctx.settings.register(NS, Config, { base: config })
+    migrateLegacySettings(sctx, scope)
+    getConfig = () => scope.get() ?? config
+    sctx.effect(() => () => {
+      getConfig = () => config
+    })
+  })
+
+  // Serve the stored image so the tool card can show it inline. Tool cards do
+  // not render image blocks — only assistant messages do — so the picture a
+  // tool produces needs a URL of its own.
+  //
+  // Ids are content-addressed (`sha256:<hex>`), the store verifies them, and
+  // the route is same-origin like every other plugin route.
+  const imageHandler = (() => {
+    return async (req, res) => {
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'GET only' }))
+        return
+      }
+      const query = new URL(req.url ?? '/', 'http://x').searchParams
+      const id = query.get('id') ?? ''
+      if (!/^sha256:[0-9a-f]{64}$/.test(id)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'bad attachment id' }))
+        return
+      }
+      // The store verifies the whole reference, not just the id: mediaType,
+      // byte count and dimensions must match what it probes from the bytes.
+      // The tool result carries all of them, so the card sends them back.
+      // Nothing is gained by forging them — the bytes are still verified
+      // against the sha256 in the id, and a mismatch is simply a 404.
+      const ref = {
+        attachmentId: id,
+        mediaType: query.get('mt') || 'image/png',
+        bytes: Number(query.get('b')) || 0,
+        width: Number(query.get('w')) || 0,
+        height: Number(query.get('h')) || 0,
+      }
+      try {
+        const stored = await ctx.attachments.readImage(ref)
+        res.writeHead(200, {
+          'Content-Type': stored.ref?.mediaType || 'image/png',
+          // Content-addressed: the bytes behind an id never change.
+          'Cache-Control': 'public, max-age=31536000, immutable',
+        })
+        res.end(Buffer.from(stored.data))
+      } catch (error) {
+        res.writeHead(404, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: String(error && error.message ? error.message : error) }))
+      }
+    }
+  })()
+
+  // Два адреса, один обработчик. Новый — тот, что уходит в новые сообщения;
+  // старый остался от прежнего имени плагина, и по нему сделаны ссылки в уже
+  // отправленных: сними его — и картинки в истории разговоров перестанут
+  // показываться.
+  for (const path of ['/dsh-image-gen/image', '/dsh-fal-image-gen/image']) {
+    ctx.effect(() => ctx.webServer.register({
+      kind: 'exact',
+      path,
+      handler: imageHandler,
+    }), `dsh-image-gen: image route ${path}`)
+  }
+
+  ctx.tools.register(
+    defineTool({
+      name: 'generate_image',
+      description:
+        'Generate an image with the configured image provider. '
+        + 'Saves the image to the session workspace and shows it in the conversation. '
+        + 'Depending on how the deployment is configured the result carries either the image itself or a link to it; '
+        + 'when you only get a link, answer from the prompt and the link rather than claiming to see the picture. '
+        + 'Use for any text-to-image request.',
+      parameters: {
+        prompt: {
+          type: 'string',
+          required: true,
+          description: 'Detailed description of the image to generate (subject, style, lighting, composition, colors).',
+        },
+        image_size: {
+          type: 'string',
+          description: `One of: ${IMAGE_SIZES.join(', ')}. Default: ${config.defaultSize}.`,
+        },
+        seed: {
+          type: 'integer',
+          description: 'Optional seed for reproducible output.',
+        },
+        output_format: {
+          type: 'string',
+          enum: OUTPUT_FORMATS,
+          description: `Output format. Default: ${config.defaultFormat}.`,
+        },
+        output_name: {
+          type: 'string',
+          description: 'Optional file name stem for the saved image (defaults to a slug of the prompt).',
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            path: { type: 'string' },
+            url: { type: 'string' },
+            width: { type: 'integer' },
+            height: { type: 'integer' },
+            seed: { type: 'integer' },
+            prompt: { type: 'string' },
+            format: { type: 'string' },
+            attachment: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                attachmentId: { type: 'string' },
+                mediaType: { type: 'string' },
+                bytes: { type: 'integer' },
+                width: { type: 'integer' },
+                height: { type: 'integer' },
+                name: { type: 'string' },
+              },
+            },
+          },
+        },
+        render(args, value) {
+          const summary = `Image generated (${value.width}×${value.height}, ${value.format}, seed ${value.seed}): ${value.path}`
+          // "link": the result stays text-only, so a chat model without vision
+          // reads it fine; the card turns the link back into a picture.
+          // "image": the picture travels in the result itself, which only a
+          // vision-capable model — or dsh-vision-bridge — can handle.
+          if (live().deliverAs !== 'image') {
+            return [{ type: 'text', text: value.url ? `${summary}\n${value.url}` : summary }]
+          }
+          const blocks = [{ type: 'text', text: summary }]
+          if (value.attachment) blocks.push({ type: 'image', attachment: value.attachment })
+          return blocks
+        },
+      },
+      isConcurrencySafe: () => false,
+      timeoutMs: config.timeoutMs + 30000,
+      async execute(args, exec) {
+        const cfg = live()
+        const provider = PROVIDER_KEYS.includes(cfg.provider) ? cfg.provider : 'fal'
+        const deliverAs = cfg.deliverAs
+        const size = args.image_size ?? cfg.defaultSize
+        if (!IMAGE_SIZES.includes(size)) {
+          throw new Error(`Invalid image_size "${size}". One of: ${IMAGE_SIZES.join(', ')}`)
+        }
+        const format = args.output_format ?? cfg.defaultFormat
+        if (!OUTPUT_FORMATS.includes(format)) {
+          throw new Error(`Invalid output_format "${format}". One of: ${OUTPUT_FORMATS.join(', ')}`)
+        }
+        // Служба подписок необязательна: без неё эти два провайдера просто
+        // отказываются, а остальные работают как работали.
+        let subscriptionImages
+        try { subscriptionImages = ctx.get && ctx.get('subscriptionImages') } catch (noService) { subscriptionImages = undefined }
+
+        const providers = makeProviders(
+          { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
+          { prompt: args.prompt, size, format, seed: args.seed, signal: exec.signal },
+        )
+        const generated = await providers[provider]()
+        const bytes = generated.bytes
+
+        const mediaType = generated.mediaType
+        const extension = mediaType === 'image/jpeg' ? 'jpg' : mediaType === 'image/webp' ? 'webp' : 'png'
+        const stem = `${slugify(args.output_name || args.prompt)}-${Date.now().toString(36)}`
+        const name = `${stem}.${extension}`
+
+        const attachment = await ctx.attachments.saveImage({
+          data: new Uint8Array(bytes),
+          mediaType,
+          name,
+        })
+
+        // Relative outputDir belongs to the session's workspace, not to the
+        // directory the harness happens to be started from.
+        const sessionCwd = exec.agent?.session?.header?.cwd
+        const outDir = path.resolve(sessionCwd || process.cwd(), cfg.outputDir)
+        await mkdir(outDir, { recursive: true })
+        const filePath = path.join(outDir, name)
+        await writeFile(filePath, bytes)
+
+        // The plugin's own route outlives the fal.media link, and the card
+        // needs the reference anyway to verify the bytes.
+        const localUrl = '/dsh-image-gen/image?id=' + encodeURIComponent(attachment.attachmentId)
+          + '&mt=' + encodeURIComponent(attachment.mediaType)
+          + '&b=' + encodeURIComponent(String(attachment.bytes))
+          + '&w=' + encodeURIComponent(String(attachment.width))
+          + '&h=' + encodeURIComponent(String(attachment.height))
+
+        return {
+          path: filePath,
+          // Прямой ссылки может и не быть: провайдер, отдающий base64, ничего
+          // не публикует. Тогда и в режиме "image" остаётся наша ссылка.
+          url: deliverAs === 'image' && generated.sourceUrl ? generated.sourceUrl : localUrl,
+          width: generated.width || attachment.width,
+          height: generated.height || attachment.height,
+          seed: generated.seed,
+          prompt: args.prompt,
+          format: mediaType.replace('image/', ''),
+          attachment: {
+            attachmentId: attachment.attachmentId,
+            mediaType: attachment.mediaType,
+            bytes: attachment.bytes,
+            width: attachment.width,
+            height: attachment.height,
+            name: attachment.name,
+          },
+        }
+      },
+    }),
+  )
+}

package/lib/providers.js

@@ -0,0 +1,266 @@
+// Провайдеры генерации изображений.
+//
+// Провайдер получает задание и возвращает готовые байты картинки. Всё, что
+// происходит дальше — вложение, файл в рабочей папке, ссылка и карточка
+// в разговоре — общее для всех провайдеров и живёт в index.js.
+//
+// Сеть приходит параметром (fetchImpl), ключ — через resolveKey, поэтому оба
+// провайдера проверяются юнит-тестами без единого реального запроса.
+
+export const PROVIDER_KEYS = ['fal', 'custom', 'codex', 'grok']
+
+// Размеры, которыми оперируют подписки, — свой набор, не похожий на именованные
+// размеры FAL. Перевод один к одному по смыслу: квадрат, вертикаль, горизонталь.
+export const SUBSCRIPTION_SIZES = {
+  square_hd: '1024x1024',
+  square: '1024x1024',
+  portrait_4_3: '1024x1536',
+  portrait_16_9: '1024x1536',
+  landscape_4_3: '1536x1024',
+  landscape_16_9: '1536x1024',
+}
+
+/** Image sizes accepted by fal-ai/flux-2/klein (and most FAL flux models). */
+export const IMAGE_SIZES = [
+  'square_hd',
+  'square',
+  'portrait_4_3',
+  'portrait_16_9',
+  'landscape_4_3',
+  'landscape_16_9',
+]
+
+/** Output formats accepted by the model. */
+export const OUTPUT_FORMATS = ['png', 'jpeg', 'webp']
+
+// Именованные размеры — единый язык инструмента: он не должен меняться от того,
+// какой провайдер включён. FAL понимает их как есть, OpenAI-совместимые API
+// хотят ШxВ — для них перевод.
+export const SIZE_PIXELS = {
+  square_hd: '1024x1024',
+  square: '512x512',
+  portrait_4_3: '768x1024',
+  portrait_16_9: '576x1024',
+  landscape_4_3: '1024x768',
+  landscape_16_9: '1024x576',
+}
+
+/** Normalize a raw key into a FAL `Authorization: Key <key>` value. */
+export function falAuthHeader(key) {
+  const trimmed = String(key ?? '').trim()
+  if (!trimmed) return ''
+  return trimmed.startsWith('Key ') || trimmed.startsWith('key ')
+    ? trimmed
+    : `Key ${trimmed}`
+}
+
+/** Map a content type onto the attachment service's supported set. */
+export function normalizeMediaType(contentType, fallbackFormat) {
+  const raw = String(contentType ?? '').toLowerCase()
+  if (raw.includes('jpeg') || raw.includes('jpg')) return 'image/jpeg'
+  if (raw.includes('webp')) return 'image/webp'
+  if (raw.includes('png')) return 'image/png'
+  if (fallbackFormat === 'jpeg') return 'image/jpeg'
+  if (fallbackFormat === 'webp') return 'image/webp'
+  return 'image/png'
+}
+
+/** Submit a generation job to the FAL queue. */
+export async function submitJob(fetchImpl, baseURL, model, key, body, signal) {
+  const res = await fetchImpl(`${baseURL}/${model}`, {
+    method: 'POST',
+    headers: {
+      Authorization: falAuthHeader(key),
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+    signal,
+  })
+  const data = await res.json().catch(() => ({}))
+  if (!res.ok || !data.request_id) {
+    const detail = typeof data.detail === 'string' ? data.detail : JSON.stringify(data).slice(0, 600)
+    throw new Error(`FAL submit failed (HTTP ${res.status}): ${detail}`)
+  }
+  return data
+}
+
+/** Poll the FAL status endpoint until completion, failure, timeout, or abort. */
+export async function pollStatus(fetchImpl, statusUrl, key, signal, pollIntervalMs, timeoutMs) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    if (signal.aborted) throw new Error('FAL generation cancelled')
+    if (Date.now() > deadline) throw new Error(`FAL generation timed out after ${timeoutMs} ms`)
+    await new Promise((resolve) => {
+      const timer = setTimeout(resolve, pollIntervalMs)
+      signal.addEventListener('abort', () => {
+        clearTimeout(timer)
+        resolve()
+      }, { once: true })
+    })
+    if (signal.aborted) throw new Error('FAL generation cancelled')
+    const res = await fetchImpl(statusUrl, { headers: { Authorization: falAuthHeader(key) }, signal })
+    const data = await res.json().catch(() => ({}))
+    const status = data.status
+    if (status === 'COMPLETED') return data
+    if (status === 'ERROR' || data.error || data.detail) {
+      throw new Error(`FAL generation failed: ${JSON.stringify(data).slice(0, 600)}`)
+    }
+    if (status !== 'IN_QUEUE' && status !== 'IN_PROGRESS') {
+      throw new Error(`Unexpected FAL status "${status}": ${JSON.stringify(data).slice(0, 300)}`)
+    }
+  }
+}
+
+/**
+ * @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
+ *   означают «спроси у службы вложений»: она всё равно измеряет байты сама.
+ */
+export function makeProviders(deps, job) {
+  const { fetchImpl, resolveKey, cfg } = deps
+  const { prompt, size, format, seed, signal } = job
+
+  async function fal() {
+    const key = await resolveKey(cfg.apiKeyEnv)
+    const body = { prompt, image_size: size, num_images: 1 }
+    if (seed !== undefined) body.seed = seed
+    if (format !== 'png') body.output_format = format
+
+    const submit = await submitJob(fetchImpl, cfg.baseURL, cfg.model, key, body, signal)
+    const statusUrl = submit.status_url || `${cfg.baseURL}/${cfg.model}/requests/${submit.request_id}/status`
+    const statusBody = await pollStatus(fetchImpl, statusUrl, key, signal, cfg.pollIntervalMs, cfg.timeoutMs)
+
+    const resultRes = await fetchImpl(statusBody.response_url, {
+      headers: { Authorization: falAuthHeader(key) },
+      signal,
+    })
+    const result = await resultRes.json().catch(() => ({}))
+    const image = result.images && result.images[0]
+    if (!image || !image.url) {
+      throw new Error(`FAL returned no images: ${JSON.stringify(result).slice(0, 600)}`)
+    }
+    const download = await fetchImpl(image.url, { signal })
+    if (!download.ok) {
+      throw new Error(`Failed to download generated image (HTTP ${download.status})`)
+    }
+    return {
+      bytes: Buffer.from(await download.arrayBuffer()),
+      mediaType: normalizeMediaType(image.content_type, format),
+      width: image.width ?? 0,
+      height: image.height ?? 0,
+      seed: result.seed ?? seed ?? 0,
+      sourceUrl: image.url,
+    }
+  }
+
+  // Любой OpenAI-совместимый API картинок. Один запрос вместо очереди FAL.
+  async function custom() {
+    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')
+
+    // Пустая ссылка на ключ — значит провайдер без авторизации, например
+    // локальный шлюз. Это законный случай, а не недонастройка.
+    const key = cfg.customKeyEnv ? await resolveKey(cfg.customKeyEnv) : ''
+    const headers = { 'Content-Type': 'application/json' }
+    if (key) headers.Authorization = `Bearer ${key}`
+
+    // response_format не отправляем: новые модели OpenAI его отвергают, а ответ
+    // всё равно приходит либо base64, либо ссылкой — принимаем оба.
+    const res = await fetchImpl(`${base}/images/generations`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        model: cfg.customModel,
+        prompt,
+        n: 1,
+        size: cfg.customSize || SIZE_PIXELS[size] || size,
+      }),
+      signal,
+    })
+    const data = await res.json().catch(() => ({}))
+    if (!res.ok) {
+      const detail = data?.error?.message || JSON.stringify(data).slice(0, 600)
+      throw new Error(`Image API failed (HTTP ${res.status}): ${detail}`)
+    }
+    const item = data?.data?.[0]
+    if (!item) {
+      throw new Error(`Image API returned no images: ${JSON.stringify(data).slice(0, 600)}`)
+    }
+
+    if (item.b64_json) {
+      return {
+        bytes: Buffer.from(item.b64_json, 'base64'),
+        mediaType: normalizeMediaType(data.output_format || '', format),
+        width: 0,
+        height: 0,
+        seed: seed ?? 0,
+        sourceUrl: '',
+      }
+    }
+    if (!item.url) {
+      throw new Error(`Image API returned neither b64_json nor url: ${JSON.stringify(item).slice(0, 300)}`)
+    }
+    const download = await fetchImpl(item.url, { signal })
+    if (!download.ok) {
+      throw new Error(`Failed to download generated image (HTTP ${download.status})`)
+    }
+    const contentType = download.headers && typeof download.headers.get === 'function'
+      ? download.headers.get('content-type')
+      : ''
+    return {
+      bytes: Buffer.from(await download.arrayBuffer()),
+      mediaType: normalizeMediaType(contentType, format),
+      width: 0,
+      height: 0,
+      seed: seed ?? 0,
+      sourceUrl: item.url,
+    }
+  }
+
+  // Генерация на подписке: аккаунт и токен живут в плагине подписок, здесь
+  // только запрос и разбор ответа. Токен сюда не попадает вовсе — служба
+  // отдаёт готовую картинку, а не ключ доступа.
+  function subscription(provider) {
+    return async function generate() {
+      const images = deps.subscriptionImages
+      if (!images || typeof images.generate !== 'function') {
+        return {
+          ok: false,
+          provider,
+          reason: `${provider}: нужен плагин подписок — он держит вход в аккаунт`,
+        }
+      }
+      let produced
+      try {
+        produced = await images.generate({
+          provider,
+          prompt,
+          size: SUBSCRIPTION_SIZES[size] || '1024x1024',
+          quality: cfg.subscriptionQuality || undefined,
+          signal,
+        })
+      } catch (e) {
+        return { ok: false, provider, reason: `${provider}: ${String(e && e.message || e)}` }
+      }
+      const first = Array.isArray(produced) ? produced[0] : null
+      if (!first || !first.b64_json) {
+        return { ok: false, provider, reason: `${provider}: в ответе нет картинки` }
+      }
+      return {
+        bytes: Buffer.from(first.b64_json, 'base64'),
+        // Подписки отдают png; формата в ответе нет, поэтому объявляем прямо.
+        mediaType: 'image/png',
+        width: 0,
+        height: 0,
+        seed: seed ?? 0,
+        sourceUrl: '',
+        revisedPrompt: first.revisedPrompt || '',
+      }
+    }
+  }
+
+  return { fal, custom, codex: subscription('codex'), grok: subscription('grok') }
+}