dsh-draw 0.1.0

package/lib/types/engine.js

@@ -0,0 +1,135 @@
+/**
+ * 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 { decodeBase64, fusedSignal } from './http.js';
+import { sanitizeError } from './sanitize.js';
+/**
+ * A single engine call failure. `message` is display-safe (never carries the
+ * API key); `status` carries the HTTP status when a response existed.
+ */
+export class EngineCallError extends Error {
+    /** Which stage failed. */
+    phase;
+    /** Stable machine code: `unconfigured`, `auth`, `http`, `parse`. */
+    code;
+    /** HTTP status when a response existed. */
+    status;
+    /** @param phase - failing stage. @param code - stable code. @param message - display-safe message. @param options - optional status and cause. */
+    constructor(phase, code, message, options) {
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'EngineCallError';
+        this.phase = phase;
+        this.code = code;
+        if (options?.status !== undefined)
+            this.status = options.status;
+    }
+}
+/** Timeout for one image URL download (fraction of the request budget). */
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+/**
+ * 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 async function callEngine(engine, request, deps, signal) {
+    const credential = await deps.resolveCredential(engine.apiKeyRef);
+    if (credential === undefined) {
+        throw new EngineCallError('credential', 'unconfigured', `engine "${engine.id}" has no resolved credential reference ${engine.apiKeyRef}`);
+    }
+    const headers = {
+        'content-type': 'application/json',
+        authorization: `Bearer ${credential}`,
+    };
+    const body = {
+        model: request.model,
+        prompt: request.prompt,
+        size: request.size,
+        n: request.n,
+        ...(request.quality !== undefined ? { quality: request.quality } : {}),
+        ...(request.style !== undefined ? { style: request.style } : {}),
+        ...(request.responseFormat === 'b64_json' ? { response_format: request.responseFormat } : {}),
+    };
+    const response = await deps.transport.request({
+        method: 'POST',
+        url: `${engine.baseUrl}/images/generations`,
+        headers,
+        body: new TextEncoder().encode(JSON.stringify(body)),
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new EngineCallError('request', 'auth', `engine "${engine.id}" rejected the credential (HTTP ${response.status})`, { status: response.status });
+    }
+    if (response.status < 200 || response.status >= 300) {
+        throw new EngineCallError('request', 'http', `engine "${engine.id}" failed with HTTP ${response.status}`, { status: response.status });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(response.body));
+    }
+    catch (cause) {
+        throw new EngineCallError('parse', 'parse', `engine "${engine.id}" returned a non-JSON response`, { cause });
+    }
+    const items = Array.isArray(parsed.data) ? parsed.data : undefined;
+    if (items === undefined) {
+        throw new EngineCallError('parse', 'parse', `engine "${engine.id}" response has no data array`);
+    }
+    const images = [];
+    for (const raw of items) {
+        if (typeof raw !== 'object' || raw === null) {
+            throw new EngineCallError('parse', 'parse', `engine "${engine.id}" returned a malformed image entry`);
+        }
+        const item = raw;
+        if (typeof item.b64_json === 'string' && item.b64_json.length > 0) {
+            images.push({ data: decodeBase64(item.b64_json), mediaType: engine.imageMediaType });
+            continue;
+        }
+        if (typeof item.url === 'string' && item.url.length > 0) {
+            images.push({ data: await downloadImageUrl(engine, item.url, credential, deps, signal), mediaType: engine.imageMediaType });
+            continue;
+        }
+        throw new EngineCallError('parse', 'parse', `engine "${engine.id}" returned an image entry without bytes or a URL`);
+    }
+    if (images.length === 0) {
+        throw new EngineCallError('parse', 'parse', `engine "${engine.id}" returned no images`);
+    }
+    return images;
+}
+/**
+ * Download one image URL with the engine's bearer credential. The download is
+ * one GET request on the same transport; a non-2xx status is an engine
+ * failure, not silent emptiness.
+ */
+async function downloadImageUrl(engine, url, credential, deps, signal) {
+    const { signal: downloadSignal, dispose } = fusedSignal(signal, DOWNLOAD_TIMEOUT_MS);
+    try {
+        const response = await deps.transport.request({
+            method: 'GET',
+            url,
+            headers: { authorization: `Bearer ${credential}` },
+            signal: downloadSignal,
+        });
+        if (response.status < 200 || response.status >= 300) {
+            throw new EngineCallError('request', 'http', `engine "${engine.id}" image download failed with HTTP ${response.status}`, { status: response.status });
+        }
+        return response.body;
+    }
+    catch (error) {
+        if (error instanceof EngineCallError)
+            throw error;
+        throw new EngineCallError('request', 'http', `engine "${engine.id}" image download failed: ${sanitizeError(error)}`, { cause: error });
+    }
+    finally {
+        dispose();
+    }
+}

package/lib/types/http.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The HTTP transport seam: engine calls go through one injectable
+ * request function so tests can pin every wire interaction without network
+ * I/O. The default implementation is Node's global `fetch` (undici) with a
+ * per-call timeout fused onto the caller's cancellation signal.
+ *
+ * @module dsh-draw/http
+ */
+/** One transport request: URL, headers, optional body, and cancellation. */
+export interface HttpRequest {
+    /** HTTP method. */
+    method: string;
+    /** Absolute target URL. */
+    url: string;
+    /** Header map (values are raw secrets — never logged). */
+    headers?: Readonly<Record<string, string>>;
+    /** Request body bytes; omitted for body-less requests. */
+    body?: Uint8Array<ArrayBuffer>;
+    /** Caller cancellation; transport failures must observe it. */
+    signal?: AbortSignal;
+}
+/** One transport response: status plus raw bytes. */
+export interface HttpResponse {
+    /** HTTP status code. */
+    status: number;
+    /** Raw response body bytes. */
+    body: Uint8Array;
+}
+/** Machine-routable failure codes of the transport seam. */
+export type HttpErrorCode = 'timeout' | 'aborted' | 'network' | 'invalid-response';
+/**
+ * A transport-level failure. `status` is absent for network/timeout failures;
+ * `code` routes fallback and cooldown decisions.
+ */
+export declare class HttpError extends Error {
+    /** Stable failure code. */
+    readonly code: HttpErrorCode;
+    /** HTTP status when a response existed. */
+    readonly status?: number;
+    /** @param code - stable failure code. @param message - display-safe message. @param options - optional status and cause. */
+    constructor(code: HttpErrorCode, message: string, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+/** Transport face the engine and probe layers consume. */
+export interface HttpTransport {
+    /**
+     * Perform one request and return the raw response. Never resolves with a
+     * thrown engine business error; non-2xx statuses are ordinary results.
+     *
+     * @param request - method, URL, headers, body, and cancellation.
+     * @returns status plus raw bytes.
+     * @throws {@link HttpError} for timeouts, aborts, and network failures.
+     */
+    request(request: HttpRequest): Promise<HttpResponse>;
+}
+/**
+ * Fuse a caller signal with a per-call timeout into one signal and a disposer
+ * that clears the timer when the call settles.
+ *
+ * @param signal - caller signal, or undefined.
+ * @param timeoutMs - positive timeout.
+ * @returns the fused signal plus its disposer.
+ */
+export declare function fusedSignal(signal: AbortSignal | undefined, timeoutMs: number): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
+/**
+ * The production transport: global `fetch` (undici under Node ≥ 22) with the
+ * timeout fused onto the caller signal. The response body is read to bytes;
+ * oversized or unreadable bodies surface as `invalid-response`.
+ *
+ * @param timeoutMs - per-call timeout.
+ * @param maxBytes - response byte cap (the engine's image cap plus headroom).
+ * @returns a transport ready for the router.
+ */
+export declare function defaultHttpTransport(timeoutMs: number, maxBytes: number): HttpTransport;
+/**
+ * Decode a standard base64 string to bytes. A malformed string fails loud —
+ * a provider change would otherwise silently corrupt an image.
+ *
+ * @param data - base64 payload without a data: prefix.
+ * @returns decoded bytes.
+ * @throws when the payload is not valid base64.
+ */
+export declare function decodeBase64(data: string): Uint8Array;
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,0DAA0D;IAC1D,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC1C,0DAA0D;IAC1D,IAAI,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;IAC9B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,+BAA+B;IAC/B,IAAI,EAAE,UAAU,CAAA;CACjB;AAED,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,kBAAkB,CAAA;AAElF;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,4HAA4H;IAC5H,YAAY,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAK/F;CACF;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CACrD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAgB5H;AAcD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAgCvF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAMrD"}

package/lib/types/http.js

@@ -0,0 +1,127 @@
+/**
+ * The HTTP transport seam: engine calls go through one injectable
+ * request function so tests can pin every wire interaction without network
+ * I/O. The default implementation is Node's global `fetch` (undici) with a
+ * per-call timeout fused onto the caller's cancellation signal.
+ *
+ * @module dsh-draw/http
+ */
+/**
+ * A transport-level failure. `status` is absent for network/timeout failures;
+ * `code` routes fallback and cooldown decisions.
+ */
+export class HttpError extends Error {
+    /** Stable failure code. */
+    code;
+    /** HTTP status when a response existed. */
+    status;
+    /** @param code - stable failure code. @param message - display-safe message. @param options - optional status and cause. */
+    constructor(code, message, options) {
+        super(message, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'HttpError';
+        this.code = code;
+        if (options?.status !== undefined)
+            this.status = options.status;
+    }
+}
+/**
+ * Fuse a caller signal with a per-call timeout into one signal and a disposer
+ * that clears the timer when the call settles.
+ *
+ * @param signal - caller signal, or undefined.
+ * @param timeoutMs - positive timeout.
+ * @returns the fused signal plus its disposer.
+ */
+export function fusedSignal(signal, timeoutMs) {
+    if (signal === undefined) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new HttpError('timeout', `request exceeded ${timeoutMs} ms`)), timeoutMs);
+        return { signal: controller.signal, dispose: () => clearTimeout(timer) };
+    }
+    if (signal.aborted)
+        return { signal, dispose: () => undefined };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new HttpError('timeout', `request exceeded ${timeoutMs} ms`)), timeoutMs);
+    const forward = () => { controller.abort(signal.reason); };
+    signal.addEventListener('abort', forward, { once: true });
+    const dispose = () => {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', forward);
+    };
+    return { signal: controller.signal, dispose };
+}
+/** Map an undici/fetch rejection to an {@link HttpError} by its observable identity. */
+function mapFetchFailure(signal, error) {
+    const reason = signal.reason;
+    if (signal.aborted && reason instanceof HttpError)
+        return reason;
+    if (signal.aborted)
+        return new HttpError('aborted', reason instanceof Error ? reason.message : 'request aborted', { cause: error });
+    if (error instanceof Error && error.name === 'TimeoutError') {
+        return new HttpError('timeout', error.message, { cause: error });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new HttpError('network', message, { cause: error });
+}
+/**
+ * The production transport: global `fetch` (undici under Node ≥ 22) with the
+ * timeout fused onto the caller signal. The response body is read to bytes;
+ * oversized or unreadable bodies surface as `invalid-response`.
+ *
+ * @param timeoutMs - per-call timeout.
+ * @param maxBytes - response byte cap (the engine's image cap plus headroom).
+ * @returns a transport ready for the router.
+ */
+export function defaultHttpTransport(timeoutMs, maxBytes) {
+    return {
+        async request(request) {
+            const { signal, dispose } = fusedSignal(request.signal, timeoutMs);
+            try {
+                let response;
+                try {
+                    response = await fetch(request.url, {
+                        method: request.method,
+                        ...(request.headers === undefined ? {} : { headers: request.headers }),
+                        ...(request.body === undefined ? {} : { body: request.body }),
+                        signal,
+                        redirect: 'follow',
+                    });
+                }
+                catch (error) {
+                    throw mapFetchFailure(signal, error);
+                }
+                let body;
+                try {
+                    body = new Uint8Array(await response.arrayBuffer());
+                }
+                catch (error) {
+                    throw new HttpError('invalid-response', `failed to read response body: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                }
+                if (body.byteLength > maxBytes) {
+                    throw new HttpError('invalid-response', `response body exceeds ${maxBytes} bytes`, { status: response.status });
+                }
+                return { status: response.status, body };
+            }
+            finally {
+                dispose();
+            }
+        },
+    };
+}
+/**
+ * Decode a standard base64 string to bytes. A malformed string fails loud —
+ * a provider change would otherwise silently corrupt an image.
+ *
+ * @param data - base64 payload without a data: prefix.
+ * @returns decoded bytes.
+ * @throws when the payload is not valid base64.
+ */
+export function decodeBase64(data) {
+    if (data.length === 0)
+        throw new HttpError('invalid-response', 'empty base64 image payload');
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `dsh-draw` — the unified static-image generation router for DeepSeek Harness.
+ *
+ * Host half: resolves config, builds the health-aware engine router and the
+ * shared drawer (validation, quota, routing, durable attachment storage, and
+ * the `draw/generated` session audit event), registers the `image_generate`
+ * tool, and mounts the `draw` Typert Remote service the settings panel and
+ * result card consume. The browser half lives in `src/client/` and registers
+ * the keyed `tool.call.toolview` result card plus the Plugins settings tab.
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`).
+ *
+ * @module dsh-draw
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.ts';
+export declare const name = "dsh-draw";
+/** Hard services: the tool registry every contribution lands in. */
+export declare const inject: string[];
+export { Config, resolveConfig, type Config as DrawConfig, type ResolvedConfig, DEFAULT_ENGINES, engineById } from './config.ts';
+export { EngineRouter, type AttemptView, type EngineStatus, type ProbeOutcome } from './router.ts';
+export { Drawer, type DrawImage, type DrawFailureReason, type DrawOutcome, type DrawOptions, type DrawSuccess } from './drawer.ts';
+export { imageGenerateTool } from './tool.ts';
+export { DrawService } from './service.ts';
+export { defaultHttpTransport, fusedSignal, type HttpTransport, type HttpRequest, type HttpResponse, HttpError } from './http.ts';
+export { callEngine, EngineCallError, type EngineDeps, type ProducedImage } from './engine.ts';
+export { translateRequest, normalizeRequest, type StandardImageRequest } from './translate.ts';
+export { quotaState, checkQuotaGenerations, checkQuotaBytes, type QuotaLimits, type QuotaState } from './quota.ts';
+export { sanitizeUrl, sanitizeText, sanitizeError, REDACTED } from './sanitize.ts';
+export { appendDrawGenerated, drawGeneratedEvents, type DrawGeneratedEvent } from './session-events.ts';
+export { PLUGIN_VERSION } from './version.ts';
+export { DRAW_INVOCATIONS, imageToWire, statusToView, probeToWire, type DrawStatusSnapshot } from './wire.ts';
+/**
+ * Mount the plugin: router, drawer, the `image_generate` tool, and the `draw`
+ * Remote service. Every registration is an effect on this fiber, so
+ * unload/hot-reload removes the tool and the service together.
+ *
+ * @param ctx - context carrying tools plus the optional attachment/credentials seams.
+ * @param config - raw loader config; defaults applied through {@link resolveConfig}.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAA;AAOnD,eAAO,MAAM,IAAI,aAAa,CAAA;AAE9B,oEAAoE;AACpE,eAAO,MAAM,MAAM,UAAY,CAAA;AAE/B,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,MAAM,IAAI,UAAU,EAAE,KAAK,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAChI,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAClG,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AAClI,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACjI,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAC9F,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAC9F,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,eAAe,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAClH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAClF,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACvG,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAK7G;;;;;;;GAOG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCvE"}

package/lib/types/index.js

@@ -0,0 +1,78 @@
+/**
+ * `dsh-draw` — the unified static-image generation router for DeepSeek Harness.
+ *
+ * Host half: resolves config, builds the health-aware engine router and the
+ * shared drawer (validation, quota, routing, durable attachment storage, and
+ * the `draw/generated` session audit event), registers the `image_generate`
+ * tool, and mounts the `draw` Typert Remote service the settings panel and
+ * result card consume. The browser half lives in `src/client/` and registers
+ * the keyed `tool.call.toolview` result card plus the Plugins settings tab.
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`).
+ *
+ * @module dsh-draw
+ */
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { resolveConfig } from './config.js';
+import { Drawer } from './drawer.js';
+import { defaultHttpTransport } from './http.js';
+import { EngineRouter } from './router.js';
+import { DrawService } from './service.js';
+import { imageGenerateTool } from './tool.js';
+export const name = 'dsh-draw';
+/** Hard services: the tool registry every contribution lands in. */
+export const inject = ['tools'];
+export { Config, resolveConfig, DEFAULT_ENGINES, engineById } from './config.js';
+export { EngineRouter } from './router.js';
+export { Drawer } from './drawer.js';
+export { imageGenerateTool } from './tool.js';
+export { DrawService } from './service.js';
+export { defaultHttpTransport, fusedSignal, HttpError } from './http.js';
+export { callEngine, EngineCallError } from './engine.js';
+export { translateRequest, normalizeRequest } from './translate.js';
+export { quotaState, checkQuotaGenerations, checkQuotaBytes } from './quota.js';
+export { sanitizeUrl, sanitizeText, sanitizeError, REDACTED } from './sanitize.js';
+export { appendDrawGenerated, drawGeneratedEvents } from './session-events.js';
+export { PLUGIN_VERSION } from './version.js';
+export { DRAW_INVOCATIONS, imageToWire, statusToView, probeToWire } from './wire.js';
+/** Response byte ceiling: one engine call may carry several full-size images. */
+const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+/**
+ * Mount the plugin: router, drawer, the `image_generate` tool, and the `draw`
+ * Remote service. Every registration is an effect on this fiber, so
+ * unload/hot-reload removes the tool and the service together.
+ *
+ * @param ctx - context carrying tools plus the optional attachment/credentials seams.
+ * @param config - raw loader config; defaults applied through {@link resolveConfig}.
+ */
+export async function apply(ctx, config) {
+    const resolved = resolveConfig(config);
+    const logger = ctx.logger('draw');
+    // Optional test seam: an embedding context may pre-select the transport
+    // under 'dsh-draw/transport'; real deployments use the fetch transport.
+    const transport = ctx.get('dsh-draw/transport')
+        ?? defaultHttpTransport(resolved.requestTimeoutMs, MAX_RESPONSE_BYTES);
+    const router = new EngineRouter(resolved, {
+        failureThreshold: resolved.failureThreshold,
+        cooldownMs: resolved.cooldownMs,
+    });
+    const credentials = () => ctx.get('credentials');
+    const drawer = new Drawer(resolved, router, {
+        engine: {
+            transport,
+            resolveCredential: async (reference) => {
+                const service = credentials();
+                if (service === undefined)
+                    return undefined;
+                const resolvedCredential = await service.resolve(credentialRef(reference));
+                return resolvedCredential?.value;
+            },
+        },
+        attachments: () => ctx.get('attachments'),
+        sessions: () => ctx.get('sessions'),
+    });
+    ctx.effect(() => ctx.tools.register(imageGenerateTool(drawer, resolved)), 'dsh-draw: image_generate tool');
+    await ctx.plugin(DrawService, { config: resolved, router, drawer, credentials: credentials() });
+    logger.info(`image generation enabled: ${resolved.engines.map(engine => engine.id).join(', ')} (preferred ${resolved.defaultEngine})`);
+}

package/lib/types/quota.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Per-session quota accounting. The durable source of truth is the session
+ * log: every completed generation appends one `draw/generated` event, and
+ * quota is computed by folding those events, so usage survives restart and
+ * fork and cannot drift from what the log records.
+ *
+ * @module dsh-draw/quota
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+/** The two quota axes. */
+export interface QuotaLimits {
+    /** Cap on generation calls (each call may produce several images). */
+    maxGenerations: number;
+    /** Cap on generated image bytes. */
+    maxBytes: number;
+}
+/** Current usage, folded from the session log. */
+export interface QuotaState {
+    /** Generation calls recorded in the log. */
+    generations: number;
+    /** Sum of recorded image bytes. */
+    bytes: number;
+}
+/** A denied quota check with the blocking axis and current state. */
+export interface QuotaDenial {
+    /** Discriminant. */
+    allowed: false;
+    /** Which axis blocked the call. */
+    reason: 'generations' | 'bytes';
+    /** Usage at decision time. */
+    state: QuotaState;
+}
+/** An allowed quota check with the current state. */
+export interface QuotaAllowance {
+    /** Discriminant. */
+    allowed: true;
+    /** Usage at decision time. */
+    state: QuotaState;
+}
+/** Quota decision. */
+export type QuotaCheck = QuotaAllowance | QuotaDenial;
+/**
+ * Fold one session's `draw/generated` events into current usage.
+ *
+ * @param session - session whose log is folded.
+ * @returns generation and byte totals.
+ */
+export declare function quotaState(session: Session): QuotaState;
+/**
+ * Check the generation-call axis before any engine is contacted: a session at
+ * its cap fails fast without spending engine credits.
+ *
+ * @param session - owning session.
+ * @param limits - configured limits.
+ * @returns allowance or denial.
+ */
+export declare function checkQuotaGenerations(session: Session, limits: QuotaLimits): QuotaCheck;
+/**
+ * Check the byte axis after the engine produced images but before anything is
+ * stored: the incoming bytes must fit under the cap, otherwise the images are
+ * discarded without touching the attachment store.
+ *
+ * @param session - owning session.
+ * @param limits - configured limits.
+ * @param incomingBytes - bytes the new images would add.
+ * @returns allowance or denial.
+ */
+export declare function checkQuotaBytes(session: Session, limits: QuotaLimits, incomingBytes: number): QuotaCheck;
+//# sourceMappingURL=quota.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../src/quota.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAGvD,0BAA0B;AAC1B,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAA;IACtB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAA;IACnB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,OAAO,EAAE,KAAK,CAAA;IACd,mCAAmC;IACnC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAA;IAC/B,8BAA8B;IAC9B,KAAK,EAAE,UAAU,CAAA;CAClB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,oBAAoB;IACpB,OAAO,EAAE,IAAI,CAAA;IACb,8BAA8B;IAC9B,KAAK,EAAE,UAAU,CAAA;CAClB;AAED,sBAAsB;AACtB,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,WAAW,CAAA;AAErD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAQvD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,UAAU,CAMvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,GAAG,UAAU,CAMxG"}

package/lib/types/quota.js

@@ -0,0 +1,56 @@
+/**
+ * Per-session quota accounting. The durable source of truth is the session
+ * log: every completed generation appends one `draw/generated` event, and
+ * quota is computed by folding those events, so usage survives restart and
+ * fork and cannot drift from what the log records.
+ *
+ * @module dsh-draw/quota
+ */
+import { drawGeneratedEvents } from './session-events.js';
+/**
+ * Fold one session's `draw/generated` events into current usage.
+ *
+ * @param session - session whose log is folded.
+ * @returns generation and byte totals.
+ */
+export function quotaState(session) {
+    let generations = 0;
+    let bytes = 0;
+    for (const event of drawGeneratedEvents(session)) {
+        generations += 1;
+        bytes += event.data.bytes;
+    }
+    return { generations, bytes };
+}
+/**
+ * Check the generation-call axis before any engine is contacted: a session at
+ * its cap fails fast without spending engine credits.
+ *
+ * @param session - owning session.
+ * @param limits - configured limits.
+ * @returns allowance or denial.
+ */
+export function checkQuotaGenerations(session, limits) {
+    const state = quotaState(session);
+    if (state.generations >= limits.maxGenerations) {
+        return { allowed: false, reason: 'generations', state };
+    }
+    return { allowed: true, state };
+}
+/**
+ * Check the byte axis after the engine produced images but before anything is
+ * stored: the incoming bytes must fit under the cap, otherwise the images are
+ * discarded without touching the attachment store.
+ *
+ * @param session - owning session.
+ * @param limits - configured limits.
+ * @param incomingBytes - bytes the new images would add.
+ * @returns allowance or denial.
+ */
+export function checkQuotaBytes(session, limits, incomingBytes) {
+    const state = quotaState(session);
+    if (state.bytes + incomingBytes > limits.maxBytes) {
+        return { allowed: false, reason: 'bytes', state };
+    }
+    return { allowed: true, state };
+}