@gobing-ai/knowledge-kit 0.0.13 → 0.0.14

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

@@ -0,0 +1,110 @@
+import { Buffer } from 'node:buffer';
+import { refToDataUri } from './refs';
+import { extensionFromUrl } from './seedream';
+import type { ImageProvider, ImageRequest, ImageResult, ProviderFactory, ProviderOptions } from './types';
+
+/**
+ * Agnes adapter (0115 R1) — port of
+ * vendors/baoyu-skills/skills/baoyu-image-gen/scripts/providers/agnes.ts
+ * (MIT © 2026 Jim Liu). `CliArgs.size` becomes `ImageRequest.width/height`.
+ */
+
+const DEFAULT_MODEL = 'agnes-image-2.1-flash';
+const DEFAULT_BASE_URL = 'https://apihub.agnes-ai.com/v1';
+const DEFAULT_SIZE = '1024x1024';
+
+interface AgnesResponse {
+    created?: number;
+    data: Array<{ url?: string; b64_json?: string }>;
+}
+
+export function parseAspectRatio(ar: string): { width: number; height: number } | null {
+    const match = ar.match(/^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?)$/);
+    if (match === null) return null;
+    const w = Number.parseFloat(match[1] as string);
+    const h = Number.parseFloat(match[2] as string);
+    if (w <= 0 || h <= 0) return null;
+    return { width: w, height: h };
+}
+
+export function snapDim(n: number): number {
+    return Math.max(32, Math.round(n / 32) * 32);
+}
+
+type SizeArgs = Pick<ImageRequest, 'aspectRatio' | 'width' | 'height'>;
+
+export function resolveSize(args: SizeArgs): string {
+    if (args.width !== undefined && args.height !== undefined) return `${args.width}x${args.height}`;
+    if (args.aspectRatio !== undefined) {
+        const parsed = parseAspectRatio(args.aspectRatio);
+        if (parsed !== null) {
+            if (parsed.width === 1 && parsed.height === 1) return '1024x1024';
+            const maxEdge = 2048;
+            const scale = Math.max(1, Math.floor(maxEdge / Math.max(parsed.width, parsed.height)));
+            return `${snapDim(parsed.width * scale)}x${snapDim(parsed.height * scale)}`;
+        }
+    }
+    return DEFAULT_SIZE;
+}
+
+export function buildRequestBody(
+    prompt: string,
+    model: string,
+    args: SizeArgs & { referenceImages: string[] },
+): Record<string, unknown> {
+    const body: Record<string, unknown> = { model, prompt, size: resolveSize(args) };
+    if (args.referenceImages.length > 0) body.image = args.referenceImages;
+    body.extra_body = { response_format: 'url' };
+    return body;
+}
+
+export async function extractImageFromResponse(
+    result: AgnesResponse,
+    fetchFn: typeof fetch = fetch,
+): Promise<Uint8Array> {
+    const img = result.data[0];
+    if (img?.b64_json !== undefined && img.b64_json !== '') {
+        return Uint8Array.from(Buffer.from(img.b64_json, 'base64'));
+    }
+    if (img?.url !== undefined) {
+        const imgRes = await fetchFn(img.url);
+        if (!imgRes.ok) throw new Error(`Failed to download image from Agnes: ${imgRes.status}`);
+        return new Uint8Array(await imgRes.arrayBuffer());
+    }
+    throw new Error('No image in Agnes response');
+}
+
+export const createAgnes: ProviderFactory = (options?: ProviderOptions): ImageProvider => {
+    const fetchFn = options?.fetch ?? fetch;
+    const env = options?.env ?? process.env;
+    const readEnv = (key: string): string => env[key] ?? '';
+
+    return {
+        name: 'agnes',
+        defaultModel: () => DEFAULT_MODEL,
+        isAvailable: () => readEnv('AGNES_API_KEY') !== '',
+        supportsReferenceImages: () => true,
+        async generate(req: ImageRequest): Promise<ImageResult> {
+            const apiKey = readEnv('AGNES_API_KEY');
+            if (apiKey === '') throw new Error('AGNES_API_KEY is required. Get one from https://apihub.agnes-ai.com.');
+            const referenceImages = await Promise.all((req.referenceImages ?? []).map(refToDataUri));
+            const body = buildRequestBody(req.prompt, req.model, { ...req, referenceImages });
+            const base = (readEnv('AGNES_BASE_URL') || DEFAULT_BASE_URL).replace(/\/+$/, '');
+            const res = await fetchFn(`${base}/images/generations`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) throw new Error(`Agnes API error (${res.status}): ${await res.text()}`);
+            const result = (await res.json()) as AgnesResponse;
+            const bytes = await extractImageFromResponse(result, fetchFn);
+            const url = result.data[0]?.url;
+            return {
+                bytes,
+                extension: url === undefined || url.startsWith('data:') ? 'png' : extensionFromUrl(url),
+                provider: 'agnes',
+                model: req.model,
+            };
+        },
+    };
+};

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

@@ -0,0 +1,153 @@
+import { extname } from 'node:path';
+import { readBytes } from '../bytes';
+import { extractImageFromResponse, getOpenAISize, type OpenAIImageResponse } from './openai';
+import type { ImageProvider, ImageRequest, ImageResult, ProviderFactory, ProviderOptions } from './types';
+
+/**
+ * Azure OpenAI adapter (0115 R1) — port of
+ * vendors/baoyu-skills/skills/baoyu-image-gen/scripts/providers/azure.ts
+ * (MIT © 2026 Jim Liu). `CliArgs.size` becomes `ImageRequest.width/height`.
+ */
+
+const DEFAULT_AZURE_API_VERSION = '2025-04-01-preview';
+const AZURE_EDIT_IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg']);
+
+interface AzureEndpoint {
+    resourceBaseURL: string;
+    deployment: string | null;
+}
+
+export function parseAzureBaseURL(url: string): AzureEndpoint {
+    const parsed = new URL(url);
+    const trimmedPath = parsed.pathname.replace(/\/+$/, '');
+    const deploymentMatch = trimmedPath.match(/^(.*?)(?:\/openai)?\/deployments\/([^/]+)$/);
+    if (deploymentMatch !== null) {
+        parsed.pathname = `${deploymentMatch[1] ?? ''}/openai`;
+        return {
+            resourceBaseURL: parsed.toString().replace(/\/+$/, ''),
+            deployment: decodeURIComponent(deploymentMatch[2] as string),
+        };
+    }
+    parsed.pathname = trimmedPath.endsWith('/openai') ? trimmedPath : `${trimmedPath}/openai`;
+    return { resourceBaseURL: parsed.toString().replace(/\/+$/, ''), deployment: null };
+}
+
+function azureEndpoint(env: Record<string, string | undefined>): AzureEndpoint {
+    const url = env.AZURE_OPENAI_BASE_URL ?? '';
+    if (url === '') {
+        throw new Error(
+            'AZURE_OPENAI_BASE_URL is required. Set it to your Azure resource or deployment endpoint, e.g.: https://your-resource.openai.azure.com or https://your-resource.openai.azure.com/openai/deployments/your-deployment',
+        );
+    }
+    return parseAzureBaseURL(url);
+}
+
+function getApiKey(env: Record<string, string | undefined>): string {
+    const key = env.AZURE_OPENAI_API_KEY ?? '';
+    if (key === '') {
+        throw new Error(
+            'AZURE_OPENAI_API_KEY is required. Get it from Azure Portal → your OpenAI resource → Keys and Endpoint.',
+        );
+    }
+    return key;
+}
+
+function buildURL(
+    endpoint: AzureEndpoint,
+    deployment: string,
+    pathSuffix: string,
+    env: Record<string, string | undefined>,
+): string {
+    const apiVersion = env.AZURE_API_VERSION ?? DEFAULT_AZURE_API_VERSION;
+    return `${endpoint.resourceBaseURL}/deployments/${encodeURIComponent(deployment)}${pathSuffix}?api-version=${apiVersion}`;
+}
+
+function getAzureQuality(quality: 'normal' | '2k' | undefined): 'medium' | 'high' {
+    return quality === '2k' ? 'high' : 'medium';
+}
+
+/** Azure reference images must be PNG or JPG/JPEG before the API call is spent. */
+export function validateReferenceImages(referenceImages: readonly string[]): void {
+    for (const refPath of referenceImages) {
+        if (!AZURE_EDIT_IMAGE_EXTENSIONS.has(extname(refPath).toLowerCase())) {
+            throw new Error(`Azure OpenAI reference images must be PNG or JPG/JPEG. Unsupported file: ${refPath}`);
+        }
+    }
+}
+
+export const createAzure: ProviderFactory = (options?: ProviderOptions): ImageProvider => {
+    const fetchFn = options?.fetch ?? fetch;
+    const env = options?.env ?? process.env;
+    // Azure's own env-precedence for a default model: explicit deployment, then the base URL,
+    // then the frozen 'gpt-image-2' (matches the baoyu getDefaultModel chain; spec facts unchanged).
+    function defaultModel(): string {
+        const explicit = env.AZURE_OPENAI_DEPLOYMENT?.trim();
+        if (explicit !== undefined && explicit !== '') return explicit;
+        const baseURL = env.AZURE_OPENAI_BASE_URL;
+        if (baseURL !== undefined) {
+            try {
+                const { deployment } = parseAzureBaseURL(baseURL);
+                if (deployment !== null) return deployment;
+            } catch {
+                // A malformed base URL surfaces later through the required-env check.
+            }
+        }
+        return 'gpt-image-2';
+    }
+
+    const supportsRef = (): boolean => true;
+
+    return {
+        name: 'azure',
+        defaultModel,
+        isAvailable: () => (env.AZURE_OPENAI_API_KEY ?? '') !== '',
+        supportsReferenceImages: supportsRef,
+        validate(req: ImageRequest): void {
+            validateReferenceImages(req.referenceImages ?? []);
+        },
+        async generate(req: ImageRequest): Promise<ImageResult> {
+            const apiKey = getApiKey(env);
+            const endpoint = azureEndpoint(env);
+            const deployment = req.model.trim();
+            if (deployment === '') {
+                throw new Error(
+                    'Azure deployment name is required. Use --model <deployment>, AZURE_OPENAI_DEPLOYMENT, AZURE_OPENAI_IMAGE_MODEL, or embed the deployment in AZURE_OPENAI_BASE_URL.',
+                );
+            }
+            const size =
+                (req.width !== undefined && req.height !== undefined ? `${req.width}x${req.height}` : undefined) ??
+                getOpenAISize(req.model, req.aspectRatio ?? null, req.quality);
+            const refs = req.referenceImages ?? [];
+            const bytes = await (async (): Promise<Uint8Array> => {
+                if (refs.length > 0) {
+                    const form = new FormData();
+                    form.append('prompt', req.prompt);
+                    form.append('size', size);
+                    form.append('n', '1');
+                    form.append('quality', getAzureQuality(req.quality));
+                    for (const refPath of refs) {
+                        const fileBytes = await readBytes(refPath);
+                        const filename = refPath.split('/').pop() ?? refPath;
+                        const mimeType = extname(filename).toLowerCase() === '.png' ? 'image/png' : 'image/jpeg';
+                        form.append('image[]', new Blob([fileBytes], { type: mimeType }), filename);
+                    }
+                    const res = await fetchFn(buildURL(endpoint, deployment, '/images/edits', env), {
+                        method: 'POST',
+                        headers: { 'api-key': apiKey },
+                        body: form,
+                    });
+                    if (!res.ok) throw new Error(`Azure OpenAI edits API error: ${await res.text()}`);
+                    return extractImageFromResponse((await res.json()) as OpenAIImageResponse, fetchFn);
+                }
+                const res = await fetchFn(buildURL(endpoint, deployment, '/images/generations', env), {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json', 'api-key': apiKey },
+                    body: JSON.stringify({ prompt: req.prompt, size, n: 1, quality: getAzureQuality(req.quality) }),
+                });
+                if (!res.ok) throw new Error(`Azure OpenAI API error: ${await res.text()}`);
+                return extractImageFromResponse((await res.json()) as OpenAIImageResponse, fetchFn);
+            })();
+            return { bytes, extension: 'png', provider: 'azure', model: req.model };
+        },
+    };
+};

package/plugins/generations/image-gen/src/providers/codex-cli.ts

@@ -0,0 +1,170 @@
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { access, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { readBytes } from '../bytes';
+import type { ImageProvider, ImageRequest, ImageResult, ProviderFactory, ProviderOptions } from './types';
+
+/**
+ * no-direct-fs-io / no-direct-process-spawn exemption is recorded as per-file
+ * exclusions in .spur/rules/strict/runtime-boundaries.yaml: this provider's
+ * transport IS spawning the local `codex` CLI and staging temp files for it
+ * (same vendor-CLI-boundary class as the file-cli publish transports).
+
+/**
+ * codex-cli adapter (0115 R1) — port of
+ * vendors/baoyu-skills/skills/baoyu-image-gen/scripts/providers/codex-cli.ts
+ * (MIT © 2026 Jim Liu). Never auto-selected (frozen NEVER_AUTO rule): readiness is
+ * the 'codex' CLI login, not an env fact, so isAvailable() stays false.
+ */
+
+const DEFAULT_MODEL = 'codex-image-gen';
+
+type WrapperOkResult = {
+    status: 'ok';
+    path?: string;
+};
+
+type WrapperErrorResult = {
+    status: 'error';
+    error: string;
+    error_kind: string;
+};
+
+type WrapperResult = WrapperOkResult | WrapperErrorResult;
+
+async function exists(filePath: string): Promise<boolean> {
+    try {
+        await access(filePath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Wrapper resolution keeps the baoyu env-override channel verbatim, including the
+ * inherited variable names (0115 straight port; kk has no bundled codex wrapper,
+ * so the override is the only supported location).
+ */
+export async function resolveWrapperPath(readEnv: (key: string) => string): Promise<string> {
+    const override = readEnv('BAOYU_CODEX_IMAGEGEN_BIN');
+    if (override.length > 0) {
+        if (!(await exists(override))) {
+            throw new Error(`Invalid BAOYU_CODEX_IMAGEGEN_BIN: ${override} does not exist.`);
+        }
+        return override;
+    }
+    throw new Error(
+        'codex-cli wrapper not found. Set BAOYU_CODEX_IMAGEGEN_BIN to a codex-imagegen main.ts (or .sh) path.',
+    );
+}
+
+type SpawnResult = { stdout: string; stderr: string; code: number };
+
+function spawnWrapper(wrapperPath: string, cliArgs: string[]): Promise<SpawnResult> {
+    return new Promise((resolveSpawn, rejectSpawn) => {
+        const isTs = wrapperPath.endsWith('.ts');
+        const command = isTs ? 'bun' : wrapperPath;
+        const args = isTs ? [wrapperPath, ...cliArgs] : cliArgs;
+        const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk: Buffer) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk: Buffer) => {
+            const text = chunk.toString('utf8');
+            stderr += text;
+        });
+        child.on('error', (err) => rejectSpawn(err));
+        child.on('close', (code) => resolveSpawn({ stdout, stderr, code: code ?? 1 }));
+    });
+}
+
+function parseWrapperJson(stdout: string): WrapperResult {
+    const trimmed = stdout.trim();
+    if (trimmed === '') throw new Error('Invalid codex-cli response: empty stdout from wrapper.');
+    const lastLine = trimmed.split(/\r?\n/).pop() ?? trimmed;
+    try {
+        return JSON.parse(lastLine) as WrapperResult;
+    } catch (parseErr: unknown) {
+        throw new Error(
+            `Invalid codex-cli response: could not parse JSON from wrapper stdout (${parseErr instanceof Error ? parseErr.message : String(parseErr)}).`,
+        );
+    }
+}
+
+function parsePositiveInt(value: string): number | null {
+    if (value === '') return null;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+export const createCodexCli: ProviderFactory = (options?: ProviderOptions): ImageProvider => {
+    const env = options?.env ?? process.env;
+    const readEnv = (key: string): string => env[key] ?? '';
+
+    return {
+        name: 'codex-cli',
+        defaultModel: () => DEFAULT_MODEL,
+        isAvailable: () => false,
+        supportsReferenceImages: () => true,
+        validate(req: ImageRequest): void {
+            if ((req.n ?? 1) > 1) {
+                throw new Error(
+                    'codex-cli provider supports only n=1 (Codex image_gen returns a single image per call).',
+                );
+            }
+        },
+        async generate(req: ImageRequest): Promise<ImageResult> {
+            const wrapperPath = await resolveWrapperPath(readEnv);
+
+            const sessionDir = resolve(tmpdir(), 'kk-image-gen-codex-cli');
+            await mkdir(sessionDir, { recursive: true });
+            const token = randomBytes(8).toString('hex');
+            const tmpOutput = resolve(sessionDir, `out-${token}.png`);
+            const tmpPrompt = resolve(sessionDir, `prompt-${token}.md`);
+            await writeFile(tmpPrompt, req.prompt, 'utf8');
+
+            const cliArgs: string[] = [
+                '--image',
+                tmpOutput,
+                '--prompt-file',
+                tmpPrompt,
+                '--aspect',
+                req.aspectRatio ?? '1:1',
+            ];
+            for (const ref of req.referenceImages ?? []) {
+                cliArgs.push('--ref', resolve(ref));
+            }
+
+            const cacheDir = readEnv('BAOYU_CODEX_IMAGEGEN_CACHE_DIR');
+            if (cacheDir !== '') cliArgs.push('--cache-dir', cacheDir);
+            const timeoutMs = parsePositiveInt(readEnv('BAOYU_CODEX_IMAGEGEN_TIMEOUT_MS'));
+            if (timeoutMs !== null) cliArgs.push('--timeout', String(timeoutMs));
+            const retries = parsePositiveInt(readEnv('BAOYU_CODEX_IMAGEGEN_RETRIES'));
+            if (retries !== null) cliArgs.push('--retries', String(retries));
+            const logFile = readEnv('BAOYU_CODEX_IMAGEGEN_LOG_FILE');
+            if (logFile !== '') cliArgs.push('--log-file', logFile);
+
+            try {
+                const spawnResult = await spawnWrapper(wrapperPath, cliArgs);
+                const parsed = parseWrapperJson(spawnResult.stdout);
+                if (parsed.status === 'error') {
+                    throw new Error(`Invalid codex-cli result (${parsed.error_kind}): ${parsed.error}`);
+                }
+                if (spawnResult.code !== 0) {
+                    throw new Error(
+                        `Invalid codex-cli result: wrapper exited with code ${spawnResult.code} despite reporting status=ok.`,
+                    );
+                }
+                const bytes = await readBytes(parsed.path ?? tmpOutput);
+                return { bytes, extension: 'png', provider: 'codex-cli', model: req.model };
+            } finally {
+                await Promise.allSettled([rm(tmpOutput, { force: true }), rm(tmpPrompt, { force: true })]);
+            }
+        },
+    };
+};