dsh-draw 0.1.0

package/src/drawer.ts

@@ -0,0 +1,234 @@
+/**
+ * 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, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
+import type { Session, SessionStore } from '@deepseek-ai/dsh-session'
+import type { ResolvedConfig } from './config.ts'
+import type { EngineDeps, ProducedImage } from './engine.ts'
+import { checkQuotaBytes, checkQuotaGenerations, type QuotaLimits, type QuotaState } from './quota.ts'
+import { EngineRouter, type AttemptView } from './router.ts'
+import { appendDrawGenerated } from './session-events.ts'
+import { normalizeRequest } from './translate.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 class Drawer {
+  /**
+   * @param config - resolved plugin configuration.
+   * @param router - the engine router.
+   * @param deps - per-call dependencies (public: the remote service reads them for probes).
+   */
+  constructor(
+    private readonly config: ResolvedConfig,
+    private readonly router: EngineRouter,
+    readonly 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.
+   */
+  async generate(args: unknown, options: DrawOptions): Promise<DrawOutcome> {
+    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: QuotaLimits = {
+      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: readonly ImageAttachmentRef[]
+    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: DrawImage[] = 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. */
+  private async saveImages(
+    attachments: AttachmentStore,
+    engineId: string,
+    produced: readonly ProducedImage[],
+    signal?: AbortSignal,
+  ): Promise<readonly ImageAttachmentRef[]> {
+    const refs: ImageAttachmentRef[] = []
+    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/src/engine.ts

@@ -0,0 +1,182 @@
+/**
+ * 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 { decodeBase64, fusedSignal, type HttpTransport } from './http.ts'
+import { sanitizeError } from './sanitize.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 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 }) {
+    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
+  }
+}
+
+/** 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>
+}
+
+/** Wire response shape of `POST /images/generations` (the fields we consume). */
+interface ImagesResponseItem {
+  /** Base64-encoded image (b64_json response format). */
+  b64_json?: string
+  /** Download URL (url response format). */
+  url?: string
+}
+
+/** Wire response envelope. */
+interface ImagesResponse {
+  /** Produced images. */
+  data?: unknown[]
+}
+
+/** 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: ResolvedEngineConfig,
+  request: TranslatedImageRequest,
+  deps: EngineDeps,
+  signal?: AbortSignal,
+): Promise<ProducedImage[]> {
+  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: Record<string, string> = {
+    'content-type': 'application/json',
+    authorization: `Bearer ${credential}`,
+  }
+  const body: Record<string, unknown> = {
+    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: ImagesResponse
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(response.body)) as ImagesResponse
+  } 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: ProducedImage[] = []
+  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 as ImagesResponseItem
+    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: ResolvedEngineConfig,
+  url: string,
+  credential: string,
+  deps: EngineDeps,
+  signal?: AbortSignal,
+): Promise<Uint8Array> {
+  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/src/http.ts

@@ -0,0 +1,161 @@
+/**
+ * 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 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 }) {
+    super(message, options?.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'HttpError'
+    this.code = code
+    if (options?.status !== undefined) this.status = options.status
+  }
+}
+
+/** 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 function fusedSignal(signal: AbortSignal | undefined, timeoutMs: number): { signal: AbortSignal; dispose: () => void } {
+  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: AbortSignal, error: unknown): HttpError {
+  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: number, maxBytes: number): HttpTransport {
+  return {
+    async request(request: HttpRequest): Promise<HttpResponse> {
+      const { signal, dispose } = fusedSignal(request.signal, timeoutMs)
+      try {
+        let response: 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: Uint8Array
+        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: string): Uint8Array {
+  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/src/index.ts

@@ -0,0 +1,93 @@
+/**
+ * `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 type { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+import type { CredentialProvider } from '@deepseek-ai/dsh-credentials'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import type { SessionStore } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-tools'
+import { Config, resolveConfig } from './config.ts'
+import { Drawer } from './drawer.ts'
+import { defaultHttpTransport, type HttpTransport } from './http.ts'
+import { EngineRouter } from './router.ts'
+import { DrawService } from './service.ts'
+import { imageGenerateTool } from './tool.ts'
+
+export const name = 'dsh-draw'
+
+/** Hard services: the tool registry every contribution lands in. */
+export const inject = ['tools']
+
+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'
+
+/** 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: Context, config: Config): Promise<void> {
+  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: HttpTransport = (ctx.get('dsh-draw/transport') as HttpTransport | undefined)
+    ?? defaultHttpTransport(resolved.requestTimeoutMs, MAX_RESPONSE_BYTES)
+  const router = new EngineRouter(resolved, {
+    failureThreshold: resolved.failureThreshold,
+    cooldownMs: resolved.cooldownMs,
+  })
+
+  const credentials = () => ctx.get('credentials') as CredentialProvider | undefined
+
+  const drawer = new Drawer(resolved, router, {
+    engine: {
+      transport,
+      resolveCredential: async (reference: string): Promise<string | undefined> => {
+        const service = credentials()
+        if (service === undefined) return undefined
+        const resolvedCredential = await service.resolve(credentialRef(reference))
+        return resolvedCredential?.value
+      },
+    },
+    attachments: () => ctx.get('attachments') as AttachmentStore | undefined,
+    sessions: () => ctx.get('sessions') as SessionStore | undefined,
+  })
+
+  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})`)
+}