dsh-draw 0.1.0

package/lib/types/config.js

@@ -0,0 +1,230 @@
+/**
+ * Plugin configuration for `dsh-draw` and its explicit resolve step.
+ * `resolveConfig` re-judges every default and bound so programmatic
+ * construction that bypasses Schemastery normalization still fails loud
+ * instead of running with hidden defaults (the explicit-resolve contract).
+ *
+ * @module dsh-draw/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Default per-generation HTTP timeout in milliseconds. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+/** Ceiling for one generation call: engines can take minutes per image. */
+export const MAX_REQUEST_TIMEOUT_MS = 600_000;
+/** Default cap on images a single call may produce. */
+export const DEFAULT_MAX_IMAGES_PER_CALL = 4;
+/** Ceiling on images a single call may produce. */
+export const MAX_IMAGES_PER_CALL = 10;
+/** Default prompt length cap (characters). */
+export const DEFAULT_MAX_PROMPT_LENGTH = 4_000;
+/** Ceiling on the prompt length cap. */
+export const MAX_PROMPT_LENGTH = 32_000;
+/** Default per-session generation-call cap. */
+export const DEFAULT_MAX_GENERATIONS_PER_SESSION = 200;
+/** Ceiling on the per-session generation-call cap. */
+export const MAX_GENERATIONS_PER_SESSION = 100_000;
+/** Default per-session image-byte cap (200 MiB). */
+export const DEFAULT_MAX_BYTES_PER_SESSION = 200 * 1024 * 1024;
+/** Ceiling on the per-session image-byte cap (4 GiB). */
+export const MAX_BYTES_PER_SESSION = 4 * 1024 * 1024 * 1024;
+/** Default consecutive failures before an engine enters cooldown. */
+export const DEFAULT_FAILURE_THRESHOLD = 2;
+/** Ceiling on the consecutive-failure threshold. */
+export const MAX_FAILURE_THRESHOLD = 10;
+/** Default engine cooldown after the failure threshold trips (ms). */
+export const DEFAULT_COOLDOWN_MS = 60_000;
+/** Ceiling on the engine cooldown. */
+export const MAX_COOLDOWN_MS = 3_600_000;
+/** The two shipped engine presets: OpenAI Images and Zhipu CogView. */
+export const DEFAULT_ENGINES = Object.freeze([
+    Object.freeze({
+        id: 'openai',
+        baseUrl: 'https://api.openai.com/v1',
+        model: 'gpt-image-1',
+        apiKeyRef: 'OPENAI_API_KEY',
+        enabled: true,
+        sizeMap: Object.freeze({ square: '1024x1024', landscape: '1536x1024', portrait: '1024x1536', auto: 'auto' }),
+        qualitySupported: true,
+        styleSupported: true,
+        responseFormat: 'b64_json',
+        imageMediaType: 'image/png',
+    }),
+    Object.freeze({
+        id: 'cogview',
+        baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
+        model: 'cogview-3-flash',
+        apiKeyRef: 'ZHIPU_API_KEY',
+        enabled: true,
+        sizeMap: Object.freeze({ square: '1024x1024', landscape: '1344x768', portrait: '768x1344', auto: '1024x1024' }),
+        qualitySupported: false,
+        styleSupported: false,
+        responseFormat: 'url',
+        imageMediaType: 'image/png',
+    }),
+]);
+/** Default size map for user-configured engines (the OpenAI vocabulary). */
+export const DEFAULT_SIZE_MAP = Object.freeze({
+    square: '1024x1024',
+    landscape: '1536x1024',
+    portrait: '1024x1536',
+    auto: 'auto',
+});
+/** Schemastery schema for loader-validated configuration. */
+export const Config = z.object({
+    engines: z.array(z.object({
+        id: z.string().min(1).max(64),
+        baseUrl: z.string().min(1).max(2048),
+        model: z.string().min(1).max(128),
+        apiKeyRef: z.string().min(1).max(128),
+        enabled: z.boolean(),
+        sizeMap: z.object({
+            square: z.string().min(1).max(64),
+            landscape: z.string().min(1).max(64),
+            portrait: z.string().min(1).max(64),
+            auto: z.string().min(1).max(64),
+        }),
+        qualitySupported: z.boolean(),
+        styleSupported: z.boolean(),
+        responseFormat: z.union(['b64_json', 'url']),
+        imageMediaType: z.union(['image/png', 'image/jpeg', 'image/webp', 'image/gif']),
+    })).default([...DEFAULT_ENGINES]),
+    defaultEngine: z.string().min(1).max(64).default('openai'),
+    requestTimeoutMs: z.number().min(1_000).max(MAX_REQUEST_TIMEOUT_MS).default(DEFAULT_REQUEST_TIMEOUT_MS),
+    maxImagesPerCall: z.number().min(1).max(MAX_IMAGES_PER_CALL).default(DEFAULT_MAX_IMAGES_PER_CALL),
+    maxPromptLength: z.number().min(1).max(MAX_PROMPT_LENGTH).default(DEFAULT_MAX_PROMPT_LENGTH),
+    maxGenerationsPerSession: z.number().min(1).max(MAX_GENERATIONS_PER_SESSION).default(DEFAULT_MAX_GENERATIONS_PER_SESSION),
+    maxBytesPerSession: z.number().min(1024 * 1024).max(MAX_BYTES_PER_SESSION).default(DEFAULT_MAX_BYTES_PER_SESSION),
+    failureThreshold: z.number().min(1).max(MAX_FAILURE_THRESHOLD).default(DEFAULT_FAILURE_THRESHOLD),
+    cooldownMs: z.number().min(1_000).max(MAX_COOLDOWN_MS).default(DEFAULT_COOLDOWN_MS),
+});
+const ENGINE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/u;
+/** Credential references are environment-variable names (POSIX identifiers). */
+const API_KEY_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/**
+ * Resolve raw config to the runtime policy, re-validating defaults and bounds
+ * plus the cross-field facts a per-field schema cannot see (duplicate engine
+ * ids, credential-bearing base URLs, an unknown default engine).
+ *
+ * @param config - raw loader config; `undefined` for a bare row.
+ * @returns the frozen resolved config.
+ * @throws on any invalid value (fail-loud at load).
+ */
+export function resolveConfig(config) {
+    const rawEngines = config?.engines ?? DEFAULT_ENGINES;
+    const engines = [];
+    const seen = new Set();
+    for (const engine of rawEngines) {
+        const id = typeof engine?.id === 'string' ? engine.id : '';
+        if (!ENGINE_ID_PATTERN.test(id)) {
+            throw new Error(`dsh-draw: engine id ${JSON.stringify(id)} must match ${ENGINE_ID_PATTERN}`);
+        }
+        if (seen.has(id))
+            throw new Error(`dsh-draw: duplicate engine id ${JSON.stringify(id)}`);
+        seen.add(id);
+        const baseUrl = engine.baseUrl ?? '';
+        let parsed;
+        try {
+            parsed = new URL(baseUrl);
+        }
+        catch {
+            throw new Error(`dsh-draw: engine "${id}" baseUrl ${JSON.stringify(baseUrl)} is not a valid URL`);
+        }
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            throw new Error(`dsh-draw: engine "${id}" baseUrl must use http or https`);
+        }
+        if (parsed.username !== '' || parsed.password !== '') {
+            throw new Error(`dsh-draw: engine "${id}" baseUrl must not embed credentials — use the apiKeyRef credential reference instead`);
+        }
+        const model = typeof engine.model === 'string' && engine.model.length > 0 && engine.model.length <= 128 ? engine.model : '';
+        if (model === '')
+            throw new Error(`dsh-draw: engine "${id}" model must be a non-empty string of at most 128 characters`);
+        const apiKeyRef = typeof engine.apiKeyRef === 'string' && API_KEY_REF_PATTERN.test(engine.apiKeyRef) ? engine.apiKeyRef : '';
+        if (apiKeyRef === '')
+            throw new Error(`dsh-draw: engine "${id}" apiKeyRef ${JSON.stringify(engine.apiKeyRef)} must be an environment-variable name`);
+        const sizeMap = engine.sizeMap === undefined ? DEFAULT_SIZE_MAP : engine.sizeMap;
+        for (const key of ['square', 'landscape', 'portrait', 'auto']) {
+            const value = sizeMap[key];
+            if (typeof value !== 'string' || value.length === 0 || value.length > 64) {
+                throw new Error(`dsh-draw: engine "${id}" sizeMap.${key} must be a non-empty string of at most 64 characters`);
+            }
+        }
+        const enabled = engine.enabled ?? true;
+        if (typeof enabled !== 'boolean')
+            throw new TypeError(`dsh-draw: engine "${id}" enabled must be a boolean`);
+        const qualitySupported = engine.qualitySupported ?? false;
+        if (typeof qualitySupported !== 'boolean')
+            throw new TypeError(`dsh-draw: engine "${id}" qualitySupported must be a boolean`);
+        const styleSupported = engine.styleSupported ?? false;
+        if (typeof styleSupported !== 'boolean')
+            throw new TypeError(`dsh-draw: engine "${id}" styleSupported must be a boolean`);
+        const responseFormat = engine.responseFormat ?? 'b64_json';
+        if (responseFormat !== 'b64_json' && responseFormat !== 'url') {
+            throw new Error(`dsh-draw: engine "${id}" responseFormat must be "b64_json" or "url"`);
+        }
+        const imageMediaType = engine.imageMediaType ?? 'image/png';
+        if (imageMediaType !== 'image/png' && imageMediaType !== 'image/jpeg' && imageMediaType !== 'image/webp' && imageMediaType !== 'image/gif') {
+            throw new Error(`dsh-draw: engine "${id}" imageMediaType ${JSON.stringify(imageMediaType)} is not a supported raster type`);
+        }
+        engines.push({
+            id,
+            baseUrl: baseUrl.replace(/\/+$/u, ''),
+            model,
+            apiKeyRef,
+            enabled,
+            sizeMap: Object.freeze({ ...sizeMap }),
+            qualitySupported,
+            styleSupported,
+            responseFormat,
+            imageMediaType,
+        });
+    }
+    if (engines.length === 0)
+        throw new Error('dsh-draw: at least one engine must be configured');
+    const defaultEngine = config?.defaultEngine ?? engines[0].id;
+    if (!seen.has(defaultEngine)) {
+        throw new Error(`dsh-draw: defaultEngine ${JSON.stringify(defaultEngine)} does not name a configured engine`);
+    }
+    const requestTimeoutMs = config?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs < 1_000 || requestTimeoutMs > MAX_REQUEST_TIMEOUT_MS) {
+        throw new Error(`dsh-draw: config.requestTimeoutMs must be a finite number between 1000 and ${MAX_REQUEST_TIMEOUT_MS}`);
+    }
+    const maxImagesPerCall = config?.maxImagesPerCall ?? DEFAULT_MAX_IMAGES_PER_CALL;
+    if (!Number.isInteger(maxImagesPerCall) || maxImagesPerCall < 1 || maxImagesPerCall > MAX_IMAGES_PER_CALL) {
+        throw new Error(`dsh-draw: config.maxImagesPerCall must be an integer between 1 and ${MAX_IMAGES_PER_CALL}`);
+    }
+    const maxPromptLength = config?.maxPromptLength ?? DEFAULT_MAX_PROMPT_LENGTH;
+    if (!Number.isInteger(maxPromptLength) || maxPromptLength < 1 || maxPromptLength > MAX_PROMPT_LENGTH) {
+        throw new Error(`dsh-draw: config.maxPromptLength must be an integer between 1 and ${MAX_PROMPT_LENGTH}`);
+    }
+    const maxGenerationsPerSession = config?.maxGenerationsPerSession ?? DEFAULT_MAX_GENERATIONS_PER_SESSION;
+    if (!Number.isInteger(maxGenerationsPerSession) || maxGenerationsPerSession < 1 || maxGenerationsPerSession > MAX_GENERATIONS_PER_SESSION) {
+        throw new Error(`dsh-draw: config.maxGenerationsPerSession must be an integer between 1 and ${MAX_GENERATIONS_PER_SESSION}`);
+    }
+    const maxBytesPerSession = config?.maxBytesPerSession ?? DEFAULT_MAX_BYTES_PER_SESSION;
+    if (!Number.isInteger(maxBytesPerSession) || maxBytesPerSession < 1024 * 1024 || maxBytesPerSession > MAX_BYTES_PER_SESSION) {
+        throw new Error(`dsh-draw: config.maxBytesPerSession must be an integer between 1048576 and ${MAX_BYTES_PER_SESSION}`);
+    }
+    const failureThreshold = config?.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
+    if (!Number.isInteger(failureThreshold) || failureThreshold < 1 || failureThreshold > MAX_FAILURE_THRESHOLD) {
+        throw new Error(`dsh-draw: config.failureThreshold must be an integer between 1 and ${MAX_FAILURE_THRESHOLD}`);
+    }
+    const cooldownMs = config?.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+    if (!Number.isInteger(cooldownMs) || cooldownMs < 1_000 || cooldownMs > MAX_COOLDOWN_MS) {
+        throw new Error(`dsh-draw: config.cooldownMs must be an integer between 1000 and ${MAX_COOLDOWN_MS}`);
+    }
+    return Object.freeze({
+        engines: Object.freeze(engines),
+        defaultEngine,
+        requestTimeoutMs,
+        maxImagesPerCall,
+        maxPromptLength,
+        maxGenerationsPerSession,
+        maxBytesPerSession,
+        failureThreshold,
+        cooldownMs,
+    });
+}
+/** Engine id by which an engine is addressed, or `undefined` for an unknown id. */
+export function engineById(config, id) {
+    return config.engines.find(engine => engine.id === id);
+}

package/lib/types/drawer.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The generation drawer: the shared orchestration behind the `image_generate`
+ * tool body and the settings-panel/card regenerate action. One path owns
+ * validation, quota, routing, durable attachment storage, and the session
+ * audit event, so the two entry points can never drift.
+ *
+ * @module dsh-draw/drawer
+ */
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { Session, SessionStore } from '@deepseek-ai/dsh-session';
+import type { ResolvedConfig } from './config.ts';
+import type { EngineDeps } from './engine.ts';
+import { type QuotaLimits, type QuotaState } from './quota.ts';
+import { EngineRouter, type AttemptView } from './router.ts';
+/** One durable result image as the canonical value and wire carry it. */
+export interface DrawImage {
+    /** Opaque attachment id. */
+    attachmentId: string;
+    /** Verified media type. */
+    mediaType: string;
+    /** Exact byte length. */
+    bytes: number;
+    /** Intrinsic width in pixels. */
+    width: number;
+    /** Intrinsic height in pixels. */
+    height: number;
+    /** Display name. */
+    name?: string;
+}
+/** A successful draw. */
+export interface DrawSuccess {
+    /** Discriminant. */
+    ok: true;
+    /** Engine id that produced the images. */
+    engine: string;
+    /** Engine model name. */
+    model: string;
+    /** Standard size vocabulary value of the request. */
+    size: 'square' | 'landscape' | 'portrait' | 'auto';
+    /** Durable result images. */
+    images: readonly DrawImage[];
+    /** Usage after this generation committed. */
+    quota: QuotaState;
+    /** Quota limits in force. */
+    limits: QuotaLimits;
+    /** Whether an earlier engine in the chain failed first. */
+    fallbackUsed: boolean;
+    /** Engine round-trip latency in milliseconds. */
+    elapsedMs: number;
+    /** Every router attempt in chain order. */
+    attempts: readonly AttemptView[];
+}
+/** Why a draw failed before or during routing. */
+export type DrawFailureReason = 'invalid-prompt' | 'quota-generations' | 'quota-bytes' | 'no-session' | 'attachments-unavailable' | 'all-engines-failed';
+/** A failed draw with a machine-routable reason and display-safe message. */
+export interface DrawFailure {
+    /** Discriminant. */
+    ok: false;
+    /** Which stage blocked the draw. */
+    reason: DrawFailureReason;
+    /** Display-safe explanation. */
+    message: string;
+    /** Quota usage at decision time for quota failures. */
+    quota?: QuotaState;
+    /** Router attempts for engine failures. */
+    attempts?: readonly AttemptView[];
+}
+/** Draw outcome. */
+export type DrawOutcome = DrawSuccess | DrawFailure;
+/** Options for one generation. */
+export interface DrawOptions {
+    /** Caller cancellation. */
+    signal?: AbortSignal;
+    /** Owning session (required: quota and the audit event live in the log). */
+    session: Session | undefined;
+    /** Who requested the generation (recorded in the audit event). */
+    source: 'tool' | 'regenerate';
+}
+/** Drawer dependencies, resolved per call so optional services stay hot-swappable. */
+export interface DrawerDeps {
+    /** Engine transport and credential resolution. */
+    engine: EngineDeps;
+    /** Per-call durable attachment store accessor (absent fails the draw closed). */
+    attachments?: () => AttachmentStore | undefined;
+    /** Per-call session store accessor for the regenerate path. */
+    sessions?: () => SessionStore | undefined;
+}
+/**
+ * The shared generation path.
+ */
+export declare class Drawer {
+    private readonly config;
+    private readonly router;
+    readonly deps: DrawerDeps;
+    /**
+     * @param config - resolved plugin configuration.
+     * @param router - the engine router.
+     * @param deps - per-call dependencies (public: the remote service reads them for probes).
+     */
+    constructor(config: ResolvedConfig, router: EngineRouter, deps: DrawerDeps);
+    /**
+     * Run one generation end to end: normalize and validate, check quota,
+     * route through the engine chain, commit images to the attachment store,
+     * and append the audit event.
+     *
+     * @param args - unvalidated standard request (tool args or card regenerate args).
+     * @param options - cancellation, session, and source.
+     * @returns the outcome.
+     */
+    generate(args: unknown, options: DrawOptions): Promise<DrawOutcome>;
+    /** Save every produced image to the attachment store; an empty image fails the batch. */
+    private saveImages;
+}
+//# sourceMappingURL=drawer.d.ts.map

package/lib/types/drawer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drawer.d.ts","sourceRoot":"","sources":["../../src/drawer.ts"],"names":[],"mappings":"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"}

package/lib/types/drawer.js

@@ -0,0 +1,138 @@
+/**
+ * The generation drawer: the shared orchestration behind the `image_generate`
+ * tool body and the settings-panel/card regenerate action. One path owns
+ * validation, quota, routing, durable attachment storage, and the session
+ * audit event, so the two entry points can never drift.
+ *
+ * @module dsh-draw/drawer
+ */
+import { checkQuotaBytes, checkQuotaGenerations } from './quota.js';
+import { appendDrawGenerated } from './session-events.js';
+import { normalizeRequest } from './translate.js';
+/**
+ * The shared generation path.
+ */
+export class Drawer {
+    config;
+    router;
+    deps;
+    /**
+     * @param config - resolved plugin configuration.
+     * @param router - the engine router.
+     * @param deps - per-call dependencies (public: the remote service reads them for probes).
+     */
+    constructor(config, router, deps) {
+        this.config = config;
+        this.router = router;
+        this.deps = deps;
+    }
+    /**
+     * Run one generation end to end: normalize and validate, check quota,
+     * route through the engine chain, commit images to the attachment store,
+     * and append the audit event.
+     *
+     * @param args - unvalidated standard request (tool args or card regenerate args).
+     * @param options - cancellation, session, and source.
+     * @returns the outcome.
+     */
+    async generate(args, options) {
+        const request = normalizeRequest(args, this.config.maxImagesPerCall);
+        if (request.prompt.trim().length === 0) {
+            return { ok: false, reason: 'invalid-prompt', message: 'image_generate: prompt must be a non-empty string' };
+        }
+        if (request.prompt.length > this.config.maxPromptLength) {
+            return { ok: false, reason: 'invalid-prompt', message: `image_generate: prompt exceeds the configured ${this.config.maxPromptLength}-character cap` };
+        }
+        const session = options.session;
+        if (session === undefined) {
+            return { ok: false, reason: 'no-session', message: 'image_generate: no session owns this call — quota accounting and the audit event need a session' };
+        }
+        const limits = {
+            maxGenerations: this.config.maxGenerationsPerSession,
+            maxBytes: this.config.maxBytesPerSession,
+        };
+        const generationCheck = checkQuotaGenerations(session, limits);
+        if (!generationCheck.allowed) {
+            return { ok: false, reason: 'quota-generations', message: `image_generate: session generation quota exhausted (${generationCheck.state.generations}/${limits.maxGenerations} calls)`, quota: generationCheck.state };
+        }
+        const startedAt = Date.now();
+        const routed = await this.router.generate(request, this.deps.engine, options.signal);
+        if (!routed.ok) {
+            return {
+                ok: false,
+                reason: 'all-engines-failed',
+                message: `image_generate: no configured engine produced images${routed.attempts.length === 0 ? '' : ` (${routed.attempts.map(attempt => attempt.engine).join(', ')})`}`,
+                attempts: routed.attempts,
+                quota: generationCheck.state,
+            };
+        }
+        const attachments = this.deps.attachments?.();
+        if (attachments === undefined) {
+            return { ok: false, reason: 'attachments-unavailable', message: 'image_generate: the attachment store is not composed — images cannot be saved durably', quota: generationCheck.state, attempts: routed.attempts };
+        }
+        const totalBytes = routed.images.reduce((sum, image) => sum + image.data.byteLength, 0);
+        const byteCheck = checkQuotaBytes(session, limits, totalBytes);
+        if (!byteCheck.allowed) {
+            return { ok: false, reason: 'quota-bytes', message: `image_generate: session image-byte quota exhausted (${byteCheck.state.bytes}/${limits.maxBytes} bytes)`, quota: byteCheck.state, attempts: routed.attempts };
+        }
+        let refs;
+        try {
+            refs = await this.saveImages(attachments, routed.engine, routed.images, options.signal);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { ok: false, reason: 'attachments-unavailable', message: `image_generate: saving images failed: ${message}`, quota: generationCheck.state, attempts: routed.attempts };
+        }
+        const images = refs.map(ref => ({
+            attachmentId: String(ref.attachmentId),
+            mediaType: ref.mediaType,
+            bytes: ref.bytes,
+            width: ref.width,
+            height: ref.height,
+            ...(ref.name !== undefined ? { name: ref.name } : {}),
+        }));
+        const elapsedMs = Date.now() - startedAt;
+        appendDrawGenerated(session, {
+            engine: routed.engine,
+            model: routed.model,
+            source: options.source,
+            prompt: request.prompt,
+            size: request.size ?? 'square',
+            quality: request.quality ?? 'auto',
+            count: images.length,
+            bytes: totalBytes,
+            attachmentIds: images.map(image => image.attachmentId),
+            elapsedMs,
+        });
+        const after = checkQuotaGenerations(session, limits);
+        return {
+            ok: true,
+            engine: routed.engine,
+            model: routed.model,
+            size: request.size ?? 'square',
+            images,
+            quota: after.state,
+            limits,
+            fallbackUsed: routed.fallbackUsed,
+            elapsedMs,
+            attempts: routed.attempts,
+        };
+    }
+    /** Save every produced image to the attachment store; an empty image fails the batch. */
+    async saveImages(attachments, engineId, produced, signal) {
+        const refs = [];
+        for (let index = 0; index < produced.length; index += 1) {
+            signal?.throwIfAborted();
+            const image = produced[index];
+            if (image.data.byteLength === 0) {
+                throw new Error(`engine "${engineId}" produced an empty image`);
+            }
+            refs.push(await attachments.saveImage({
+                data: image.data,
+                mediaType: image.mediaType,
+                name: `${engineId}-${index + 1}.${image.mediaType === 'image/jpeg' ? 'jpg' : image.mediaType.slice('image/'.length)}`,
+            }));
+        }
+        return refs;
+    }
+}

package/lib/types/engine.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The OpenAI-compatible images adapter: one implementation covers OpenAI
+ * Images, Zhipu CogView, and any config-driven compatible endpoint. The
+ * request is a `POST {baseUrl}/images/generations` JSON body; the response is
+ * `{ data: [{ b64_json } | { url }] }`. Engines declare their response format
+ * and media type in config, so no provider-specific code branches exist.
+ *
+ * @module dsh-draw/engine
+ */
+import type { ImageMediaType } from '@deepseek-ai/dsh-attachment';
+import type { ResolvedEngineConfig } from './config.ts';
+import { type HttpTransport } from './http.ts';
+import type { TranslatedImageRequest } from './translate.ts';
+/** Failure phases of one engine call, each mapping to a router decision. */
+export type EngineFailurePhase = 'credential' | 'request' | 'parse';
+/**
+ * A single engine call failure. `message` is display-safe (never carries the
+ * API key); `status` carries the HTTP status when a response existed.
+ */
+export declare class EngineCallError extends Error {
+    /** Which stage failed. */
+    readonly phase: EngineFailurePhase;
+    /** Stable machine code: `unconfigured`, `auth`, `http`, `parse`. */
+    readonly code: string;
+    /** HTTP status when a response existed. */
+    readonly status?: number;
+    /** @param phase - failing stage. @param code - stable code. @param message - display-safe message. @param options - optional status and cause. */
+    constructor(phase: EngineFailurePhase, code: string, message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+/** One produced image: bytes plus the engine-declared media type. */
+export interface ProducedImage {
+    /** Encoded image bytes. */
+    data: Uint8Array;
+    /** Engine-declared media type (validated by the attachment store). */
+    mediaType: ImageMediaType;
+}
+/** Dependencies the engine call resolves per operation. */
+export interface EngineDeps {
+    /** HTTP transport for the images request and any URL download. */
+    transport: HttpTransport;
+    /** Resolve the engine's credential reference to a secret value (per call; never cached). */
+    resolveCredential: (reference: string) => Promise<string | undefined>;
+}
+/**
+ * Call one engine for the given translated request.
+ *
+ * @param engine - resolved engine configuration.
+ * @param request - translated request body fields.
+ * @param deps - transport and credential resolution.
+ * @param signal - caller cancellation.
+ * @returns the produced images.
+ * @throws {@link EngineCallError} with a phase the router can act on.
+ */
+export declare function callEngine(engine: ResolvedEngineConfig, request: TranslatedImageRequest, deps: EngineDeps, signal?: AbortSignal): Promise<ProducedImage[]>;
+//# sourceMappingURL=engine.d.ts.map

package/lib/types/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAA6B,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAEzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAE5D,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAEnE;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;IAClC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,kJAAkJ;IAClJ,YAAY,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAMnH;CACF;AAED,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,IAAI,EAAE,UAAU,CAAA;IAChB,sEAAsE;IACtE,SAAS,EAAE,cAAc,CAAA;CAC1B;AAED,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,SAAS,EAAE,aAAa,CAAA;IACxB,4FAA4F;IAC5F,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CACtE;AAmBD;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,sBAAsB,EAC/B,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,EAAE,CAAC,CA6D1B"}