@gobing-ai/knowledge-kit 0.0.12 → 0.0.13

package/plugins/generations/image-gen/src/job.ts

@@ -0,0 +1,143 @@
+import type { Doc } from '@gobing-ai/kk-core';
+import { z } from 'zod';
+
+/**
+ * Task 0104 — the frozen `--in` envelope. A plugin's only input channel is the
+ * `--in` JSON (the spawn argv is frozen at `--in`/`--out`,
+ * `apps/cli/src/invoke.ts:118-123`), so exactly one job spec rides on the
+ * first document's `metadata.imageGen`, and the array itself is the content.
+ */
+
+/** The three v1 job branches; a resolved format preset's `job` field must match. */
+export const IMAGE_JOBS = ['free', 'cover', 'illustration'] as const;
+export type ImageJob = (typeof IMAGE_JOBS)[number];
+
+/** Job spec parsed from `docs[0].metadata.imageGen` (frozen 0104 Design). */
+export interface ImageJobSpec {
+    job: ImageJob;
+    /** FormatPreset name (0102); default per job is the job's own preset name. */
+    format?: string;
+    /** StylePreset name; default = format.defaultStyle. */
+    style?: string;
+    /** Template variables (0102 composePrompt); caller values win over preset defaults. */
+    vars?: Record<string, string>;
+    /** Free text appended as composePrompt's 4th segment. */
+    extra?: string;
+    /** 0103 selectProvider's `requested` name. */
+    provider?: string;
+    model?: string;
+    /** Absolute paths (0105 pass-through). */
+    referenceImages?: string[];
+    /** Illustration only: images to produce; default 1. */
+    count?: number;
+    /** Budget cap (R6); wins over KK_IMAGE_MAX_IMAGES. */
+    maxImages?: number;
+    seed?: number;
+    /** Overrides the `--out` basename for artefact names. */
+    outputStem?: string;
+}
+
+/** Strict on purpose: the envelope is frozen and 0106 writes it — a typo'd key must fail loud, not vanish. */
+export const ImageJobSpecSchema = z.strictObject({
+    job: z.enum(IMAGE_JOBS),
+    format: z.string().optional(),
+    style: z.string().optional(),
+    vars: z.record(z.string(), z.string()).optional(),
+    extra: z.string().optional(),
+    provider: z.string().optional(),
+    model: z.string().optional(),
+    referenceImages: z.array(z.string()).optional(),
+    count: z.number().int().positive().optional(),
+    maxImages: z.number().int().positive().optional(),
+    seed: z.number().int().optional(),
+    outputStem: z.string().optional(),
+});
+
+/** One generated image inside `Content.metadata.images` (frozen 0104 Design). */
+export interface ImageArtifact {
+    /** Absolute; always a sibling of `--out`. */
+    path: string;
+    /** FormatPreset name. */
+    format: string;
+    /** StylePreset name. */
+    style: string;
+    provider: string;
+    model: string;
+    /** The exact prompt string sent. */
+    prompt: string;
+    seed?: number;
+    width?: number;
+    height?: number;
+    bytes: number;
+}
+
+/** One illustration caption, the wt captions.json payload reduced to what consumers read (R4). */
+export interface CaptionEntry {
+    index: number;
+    path: string;
+    caption: string;
+    altText: string;
+    anchor: string;
+}
+
+/** Typed shape of this plugin's `Content.metadata` (frozen keys, 0104 Design). */
+export interface ImageGenMetadata {
+    generator: 'kk:image-gen';
+    job: ImageJob;
+    images: ImageArtifact[];
+    /** Illustration/cover: the input doc's id — the original article is never mutated. */
+    sourceDocId?: string;
+    /** Illustration only: the captions payload. */
+    captions?: CaptionEntry[];
+    /** Set only when the run spent nothing (R6 dry run). */
+    dryRun?: true;
+}
+
+function jobList(): string {
+    return IMAGE_JOBS.map((job) => `'${job}'`).join(', ');
+}
+
+function zodIssues(error: z.ZodError): string {
+    return error.issues.map((issue) => `${issue.path.join('.') || 'spec'}: ${issue.message}`).join('; ');
+}
+
+/**
+ * Parse the job spec from `docs[0].metadata.imageGen`; fail loud, naming the
+ * frozen path and the valid `job` values, before any preset or provider work.
+ */
+export function parseJobSpec(docs: Doc[]): ImageJobSpec {
+    const raw = docs[0]?.metadata?.imageGen;
+    if (raw === undefined || raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(
+            `Invalid image job spec at metadata.imageGen: expected an object with a "job" of ${jobList()}, received ${
+                raw === undefined ? 'nothing' : JSON.stringify(raw)
+            }`,
+        );
+    }
+    const result = ImageJobSpecSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`Invalid image job spec at metadata.imageGen: ${zodIssues(result.error)}`);
+    }
+    return result.data;
+}
+
+const PositionsSchema = z.array(z.string());
+
+/**
+ * Read `docs[0].metadata.positions` — the caller's (0106) chosen insertion
+ * anchors for the illustration job. Shape-only here; the anchor-occurs-once
+ * check against the body belongs to the illustration branch.
+ */
+export function readPositions(docs: Doc[]): string[] | undefined {
+    const raw = docs[0]?.metadata?.positions;
+    if (raw === undefined) {
+        return undefined;
+    }
+    const result = PositionsSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(
+            `Invalid docs[0].metadata.positions: expected an array of string anchors: ${zodIssues(result.error)}`,
+        );
+    }
+    return result.data;
+}

package/plugins/generations/image-gen/src/paths.ts

@@ -0,0 +1,31 @@
+import { basename, dirname, extname, resolve } from 'node:path';
+
+/**
+ * Task 0104 R3 — artefacts are siblings of `--out` (the voice-gen rule): the
+ * invoker expands `works_dir` before building `--out`, and a plugin's cwd is
+ * its own package dir, so every path resolves against `--out`'s directory —
+ * never `process.cwd()`.
+ */
+
+/** `ImageJobSpec.outputStem` ?? the `--out` basename without extension. */
+export function outStemFor(outPath: string, override?: string): string {
+    return override ?? basename(outPath, extname(outPath));
+}
+
+/**
+ * `<outDir>/<stem>-<format>-<NN>.<ext>` — NN zero-padded from 01, so a
+ * deterministic re-run against the same `--out` overwrites instead of appending.
+ *
+ * 0107 R5: stem and extension guards keep a hostile spec/provider from escaping
+ * `--out`'s directory — this is the single choke point for all artefact paths.
+ */
+export function artifactPath(outPath: string, stem: string, format: string, index: number, extension: string): string {
+    if (stem.includes('/') || stem.includes('\\')) {
+        throw new Error(`Artefact stem must not contain path separators: '${stem}'`);
+    }
+    if (!/^[a-z0-9]{1,5}$/i.test(extension)) {
+        throw new Error(`Artefact extension must be a short alphanumeric segment: '${extension}'`);
+    }
+    const nn = String(index).padStart(2, '0');
+    return resolve(dirname(outPath), `${stem}-${format}-${nn}.${extension}`);
+}

package/plugins/generations/image-gen/src/presets.ts

@@ -0,0 +1,344 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+import { z } from 'zod';
+
+/**
+ * Image preset contract (task 0102): the format × style preset schemas, the
+ * frozen prompt-composition rule (R2), and multi-root resolution with
+ * shadowing (R4), mirroring ADR-012's plugin discovery
+ * (`docs/design/multi-root-plugin-discovery.md`).
+ */
+
+/** One colour entry in a structured (baoyu-style) palette. */
+export interface PaletteEntry {
+    role: string;
+    name: string;
+    hex: string;
+}
+
+/** Provenance of a style preset; 0105 populates it after extraction. */
+export interface PresetSource {
+    kind: 'authored' | 'extracted';
+    refImages?: string[];
+    extractedAt?: string;
+    confidence?: 'high' | 'medium' | 'low';
+}
+
+/** One declared template variable: caller-facing description plus default. */
+export interface FormatVariable {
+    description: string;
+    default: string;
+}
+
+/** R1 — `formats/<name>.yaml`: the job skeleton (template, keywords, variables). */
+export interface FormatPreset {
+    /** Filename stem must equal this. */
+    name: string;
+    description: string;
+    /** Which plugin job branch this format drives (0104). */
+    job: 'free' | 'cover' | 'illustration';
+    /** Portable primary dimension; width/height are the optional exact pixels. */
+    aspectRatio: string;
+    width?: number;
+    height?: number;
+    /** Style used when the caller names none. */
+    defaultStyle: string;
+    /** Quality/composition tail, joined with ', '. */
+    keywords: string[];
+    /** Same placeholder grammar as the template, e.g. '{{title | cover}}.png'. */
+    outputFilename: string;
+    variables: Record<string, FormatVariable>;
+    /** Prompt body; YAML block scalar, embedded newlines preserved. */
+    template: string;
+}
+
+/** R1 — `styles/<name>.yaml`; `modifiers` is the only required prompt field. */
+export interface StylePreset {
+    name: string;
+    description: string;
+    modifiers: string;
+    palette?: PaletteEntry[];
+    typography?: string;
+    visualElements?: string[];
+    bestFor?: string;
+    /** Provider negative prompt when supported, else appended as 'avoid: …'. */
+    negative?: string;
+    source?: PresetSource;
+}
+
+const PaletteEntrySchema = z.object({ role: z.string(), name: z.string(), hex: z.string() });
+
+const PresetSourceSchema = z.object({
+    kind: z.enum(['authored', 'extracted']),
+    refImages: z.array(z.string()).optional(),
+    extractedAt: z.string().optional(),
+    confidence: z.enum(['high', 'medium', 'low']).optional(),
+});
+
+/** Parse gate for `formats/<name>.yaml`. */
+export const FormatPresetSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    job: z.enum(['free', 'cover', 'illustration']),
+    aspectRatio: z.string(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    defaultStyle: z.string(),
+    keywords: z.array(z.string()),
+    outputFilename: z.string(),
+    variables: z.record(z.string(), z.object({ description: z.string(), default: z.string() })),
+    template: z.string(),
+});
+
+/** Parse gate for `styles/<name>.yaml`. */
+export const StylePresetSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    modifiers: z.string(),
+    palette: z.array(PaletteEntrySchema).optional(),
+    typography: z.string().optional(),
+    visualElements: z.array(z.string()).optional(),
+    bestFor: z.string().optional(),
+    negative: z.string().optional(),
+    source: PresetSourceSchema.optional(),
+});
+
+/**
+ * Merge caller vars over the format's declared defaults; the caller wins.
+ */
+export function mergeVars(
+    declared: Record<string, FormatVariable>,
+    vars: Record<string, string>,
+): Record<string, string> {
+    const merged: Record<string, string> = {};
+    for (const [name, def] of Object.entries(declared)) {
+        merged[name] = def.default;
+    }
+    for (const [name, value] of Object.entries(vars)) {
+        merged[name] = value;
+    }
+    return merged;
+}
+
+/**
+ * Match one `{{ … }}` expression with brace-depth counting, so a fallback
+ * that itself contains a placeholder survives whole. wt's `[^}]+` regex
+ * truncates at the first inner `}` (`{{subtitle | , subtitled
+ * "{{subtitle}}"}}` lost its tail); the R6 golden prompt pins that form as
+ * rendering correctly, so the port must balance the braces.
+ */
+function matchPlaceholder(template: string, start: number): { expr: string; end: number } | undefined {
+    let depth = 1;
+    for (let i = start + 2; i < template.length; i++) {
+        if (template.startsWith('{{', i)) {
+            depth++;
+            i++;
+        } else if (template.startsWith('}}', i)) {
+            depth--;
+            if (depth === 0) {
+                return { expr: template.slice(start + 2, i), end: i + 2 };
+            }
+            i++;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Resolve one expression against the merged vars. An empty value (including
+ * a caller-passed '') resolves to the fallback; an unknown placeholder with
+ * no fallback throws, naming the placeholder and the format — wt silently
+ * left it in place, and a literal `{{title}}` must not reach a paid provider.
+ * Leading trim on the fallback skips the `| ` separator; its trailing space
+ * is preserved (the R6 golden prompt pins it). Single pass: a fallback is
+ * emitted literally and never re-scanned, like wt's `re.sub`.
+ */
+function resolvePlaceholder(expr: string, vars: Record<string, string>, formatName: string): string {
+    const pipe = expr.indexOf('|');
+    if (pipe !== -1) {
+        const name = expr.slice(0, pipe).trim();
+        const fallback = expr.slice(pipe + 1).trimStart();
+        const value = vars[name];
+        if (!value) {
+            return fallback;
+        }
+        // A fallback that embeds its own '{{name}}' slot is a mini-template
+        // wrapping the value (the R6 golden's ', subtitled "…"' form); a
+        // plain-text fallback is just the default, so the value wins.
+        return fallback.includes(`{{${name}}}`) ? fallback.split(`{{${name}}}`).join(value) : value;
+    }
+    const name = expr.trim();
+    const value = vars[name];
+    if (value === undefined) {
+        throw new Error(`Format "${formatName}": placeholder {{${name}}} has no value and no fallback`);
+    }
+    return value;
+}
+
+/**
+ * Render `{{name}}` / `{{name | fallback}}` (wt's two-form grammar,
+ * `template_engine.py` `_substitute_variables`).
+ */
+export function renderTemplate(template: string, vars: Record<string, string>, formatName: string): string {
+    let rendered = '';
+    let cursor = 0;
+    while (cursor < template.length) {
+        const start = template.indexOf('{{', cursor);
+        if (start === -1) {
+            rendered += template.slice(cursor);
+            break;
+        }
+        const match = matchPlaceholder(template, start);
+        if (match === undefined) {
+            rendered += template.slice(cursor, start + 2);
+            cursor = start + 2;
+            continue;
+        }
+        rendered += template.slice(cursor, start);
+        rendered += resolvePlaceholder(match.expr, vars, formatName);
+        cursor = match.end;
+    }
+    return rendered;
+}
+
+/**
+ * R2 — the frozen composition rule, wt's order as built
+ * (`template_engine.py:174-190`): rendered body → keywords → style modifiers
+ * → caller extra, empty segments dropped. Keeping wt's order makes the ported
+ * presets render byte-identically to their wt originals; the extra segment is
+ * the only addition (0105's ref-derived traits land there).
+ */
+export function composePrompt(
+    format: FormatPreset,
+    style: StylePreset,
+    vars: Record<string, string>,
+    extra?: string,
+): string {
+    const body = renderTemplate(format.template, mergeVars(format.variables, vars), format.name);
+    return [body, format.keywords.join(', '), style.modifiers, extra].filter(Boolean).join(', ');
+}
+
+/** Discovery diagnostic, mirroring kk-core's `DiscoveryDiagnostic` shape. */
+export interface PresetDiagnostic {
+    code: 'shadowed' | 'invalid';
+    path: string;
+    reason: string;
+}
+
+export interface LoadedPresets {
+    formats: Map<string, FormatPreset>;
+    styles: Map<string, StylePreset>;
+    diagnostics: PresetDiagnostic[];
+}
+
+// File IO goes through the ts-runtime FileSystem seam (rule no-direct-fs-io). The
+// node backend uses sync fs APIs by default (file-system-node.d.ts); the interface
+// unions Promise for CF stubs, so pin the sync shape once here.
+const fs = createNodeFileSystem() as unknown as {
+    exists(path: string): boolean;
+    readFile(path: string): string;
+    readDir(path: string): string[];
+    stat(path: string): { isDirectory(): boolean } | null;
+};
+
+function isDirectory(path: string): boolean {
+    return fs.stat(path)?.isDirectory() ?? false;
+}
+
+/**
+ * R4 — preset roots, low → high, mirroring ADR-012's plugin roots
+ * (`docs/design/multi-root-plugin-discovery.md`): builtin → user → project →
+ * each `KK_IMAGE_PRESET_PATH` entry (colon-separated, left → right). The
+ * project root resolves against KNOWLEDGE_KIT_PROJECT_ROOT, not cwd, because
+ * plugins are spawned with cwd set to their own package dir
+ * (`apps/cli/src/invoke.ts`).
+ */
+export function resolvePresetRoots(): string[] {
+    const roots: string[] = [join(import.meta.dir, '..', 'presets')];
+    // process.env.HOME directly: Bun snapshots os.homedir() at startup, so a
+    // runtime HOME override (tests) would be invisible through homedir().
+    const userRoot = join(process.env.HOME ?? homedir(), '.config', 'kk', 'image-presets');
+    if (isDirectory(userRoot)) {
+        roots.push(userRoot);
+    }
+    const projectRoot = join(process.env.KNOWLEDGE_KIT_PROJECT_ROOT ?? process.cwd(), '.kk', 'image-presets');
+    if (isDirectory(projectRoot)) {
+        roots.push(projectRoot);
+    }
+    for (const entry of process.env.KK_IMAGE_PRESET_PATH?.split(':') ?? []) {
+        if (entry !== '' && isDirectory(entry)) {
+            roots.push(entry);
+        }
+    }
+    return roots;
+}
+
+/** Minimal structural shape of a Zod schema, so the loader stays generic. */
+interface SchemaLike<T extends { name: string }> {
+    safeParse(value: unknown): { success: true; data: T } | { success: false; error: Error };
+}
+
+/**
+ * Load one axis (`formats/` or `styles/`) from one root. A file that fails its
+ * schema parse (or YAML parse) is skipped with an `invalid` diagnostic, never
+ * fatal; a name already loaded from a lower root is replaced wholesale with a
+ * `shadowed` diagnostic naming the losing file — no field merging, because a
+ * half-overridden preset cannot be reproduced from its file alone.
+ */
+function loadAxis<T extends { name: string }>(
+    dir: string,
+    byName: Map<string, T>,
+    pathsByName: Map<string, string>,
+    schema: SchemaLike<T>,
+    diagnostics: PresetDiagnostic[],
+): void {
+    if (!isDirectory(dir)) {
+        return;
+    }
+    for (const entry of fs.readDir(dir).sort()) {
+        if (!entry.endsWith('.yaml') && !entry.endsWith('.yml')) {
+            continue;
+        }
+        const path = join(dir, entry);
+        let parsed: unknown;
+        try {
+            parsed = Bun.YAML.parse(fs.readFile(path));
+        } catch (error) {
+            diagnostics.push({ code: 'invalid', path, reason: `unreadable or unparseable: ${error}` });
+            continue;
+        }
+        const result = schema.safeParse(parsed);
+        if (!result.success) {
+            diagnostics.push({ code: 'invalid', path, reason: result.error.message });
+            continue;
+        }
+        const previousPath = pathsByName.get(result.data.name);
+        if (previousPath !== undefined) {
+            diagnostics.push({
+                code: 'shadowed',
+                path: previousPath,
+                reason: `Preset "${result.data.name}" shadowed by ${path}`,
+            });
+        }
+        byName.set(result.data.name, result.data);
+        pathsByName.set(result.data.name, path);
+    }
+}
+
+/**
+ * R4 — load formats and styles across all resolved roots; a later root
+ * shadows an earlier one by preset name within each axis.
+ */
+export function loadPresets(): LoadedPresets {
+    const diagnostics: PresetDiagnostic[] = [];
+    const formats = new Map<string, FormatPreset>();
+    const styles = new Map<string, StylePreset>();
+    const formatPaths = new Map<string, string>();
+    const stylePaths = new Map<string, string>();
+    for (const root of resolvePresetRoots()) {
+        loadAxis(join(root, 'formats'), formats, formatPaths, FormatPresetSchema, diagnostics);
+        loadAxis(join(root, 'styles'), styles, stylePaths, StylePresetSchema, diagnostics);
+    }
+    return { formats, styles, diagnostics };
+}

package/plugins/generations/image-gen/src/providers/seedream.ts

@@ -0,0 +1,128 @@
+import { Buffer } from 'node:buffer';
+import { readBytes } from '../bytes';
+import type { ImageProvider, ImageRequest, ImageResult, ProviderFactory, ProviderOptions } from './types';
+
+/**
+ * Seedream adapter (0107 R2) — the first wire-speaking 0103 adapter.
+ * Wire prior art: vendors/baoyu-skills/skills/baoyu-image-gen/scripts/providers/seedream.ts
+ * (MIT © 2026 Jim Liu). POST `{base}/images/generations`, Bearer ARK_API_KEY.
+ */
+
+const DEFAULT_BASE_URL = 'https://ark.cn-beijing.volces.com/api/v3';
+const DEFAULT_MODEL = 'doubao-seedream-5-0-260128';
+const REF_MODEL_FRAGMENTS = ['doubao-seedream-5-0', 'doubao-seedream-4-5-', 'doubao-seedream-4-0-'];
+
+interface SeedreamResponse {
+    data?: Array<{ url?: string; b64_json?: string; error?: { code?: string; message?: string } }>;
+    error?: { code?: string; message?: string };
+}
+
+/** ARK `size`: explicit pixels win; the aspect ratio rides verbatim (seedream 4.x accepts '21:9'); else 2K. */
+export function mapSize(req: ImageRequest): string {
+    if (req.width !== undefined && req.height !== undefined) {
+        return `${req.width}x${req.height}`;
+    }
+    if (req.aspectRatio !== undefined) {
+        return req.aspectRatio;
+    }
+    return '2K';
+}
+
+function extensionFromUrl(url: string): string {
+    // data.b64_json path carries no extension — default png; URL paths end ?sig=… so take the last clean segment.
+    const match = /(?:png|jpe?g|webp)/i.exec(url.split('?')[0] ?? '');
+    return match === null ? 'jpg' : match[0].toLowerCase().replace(/^jpeg$/, 'jpg');
+}
+
+export const createSeedream: ProviderFactory = (options?: ProviderOptions): ImageProvider => {
+    const fetchFn = options?.fetch ?? fetch;
+    const env = options?.env ?? process.env;
+    const readEnv = (key: string): string => env[key] ?? '';
+    const supportsRef = (model: string): boolean => REF_MODEL_FRAGMENTS.some((fragment) => model.includes(fragment));
+
+    return {
+        name: 'seedream',
+        defaultModel: () => DEFAULT_MODEL,
+        isAvailable: () => readEnv('ARK_API_KEY') !== '',
+        supportsReferenceImages: supportsRef,
+        validate(req: ImageRequest): void {
+            if (req.referenceImages !== undefined && req.referenceImages.length > 0 && !supportsRef(req.model)) {
+                throw new Error(
+                    `seedream model '${req.model}' does not accept reference images; use a doubao-seedream 4.x+ model`,
+                );
+            }
+        },
+        async generate(req: ImageRequest): Promise<ImageResult> {
+            const apiKey = readEnv('ARK_API_KEY');
+            if (apiKey === '') {
+                throw new Error("Provider 'seedream' requires ARK_API_KEY");
+            }
+            const base = readEnv('SEEDREAM_BASE_URL') || DEFAULT_BASE_URL;
+            const body: Record<string, unknown> = {
+                model: req.model,
+                prompt: req.prompt,
+                size: mapSize(req),
+                response_format: 'url',
+                watermark: false,
+            };
+            if (req.referenceImages !== undefined && req.referenceImages.length > 0) {
+                // Local paths cannot ride the wire: lift each to a base64 data URI.
+                const lifted = await Promise.all(
+                    req.referenceImages.map(async (path) => {
+                        const bytes = await readBytes(path);
+                        return `data:image/png;base64,${Buffer.from(bytes).toString('base64')}`;
+                    }),
+                );
+                body.image = lifted.length === 1 ? lifted[0] : lifted;
+                body.response_format = 'b64_json';
+            }
+            const resp = await fetchFn(`${base}/images/generations`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+            });
+            const text = await resp.text();
+            if (!resp.ok) {
+                throw new Error(`seedream HTTP ${resp.status}: ${text.slice(0, 200)}`);
+            }
+            let parsed: SeedreamResponse;
+            try {
+                parsed = JSON.parse(text) as SeedreamResponse;
+            } catch {
+                throw new Error(`seedream returned non-JSON: ${text.slice(0, 120)}`);
+            }
+            const image = parsed.data?.[0];
+            if (parsed.error !== undefined) {
+                throw new Error(`seedream error ${parsed.error.code ?? ''}: ${parsed.error.message ?? ''}`);
+            }
+            if (image === undefined) {
+                throw new Error('seedream returned no image data');
+            }
+            if (image.b64_json !== undefined) {
+                return {
+                    bytes: Uint8Array.from(Buffer.from(image.b64_json, 'base64')),
+                    extension: 'png',
+                    provider: 'seedream',
+                    model: req.model,
+                };
+            }
+            if (image.url !== undefined) {
+                const r = await fetchFn(image.url);
+                if (!r.ok) {
+                    throw new Error(`seedream fetch URL HTTP ${r.status}`);
+                }
+                return {
+                    bytes: new Uint8Array(await r.arrayBuffer()),
+                    extension: extensionFromUrl(image.url),
+                    provider: 'seedream',
+                    model: req.model,
+                };
+            }
+            throw new Error(
+                image.error === undefined
+                    ? 'seedream returned neither url nor b64_json'
+                    : `seedream image error ${image.error.code ?? ''}: ${image.error.message ?? ''}`,
+            );
+        },
+    };
+};