dsh-draw 0.1.2 → 0.2.1

package/lib/types/router.d.ts

@@ -9,7 +9,7 @@
  */
 import type { ResolvedConfig, ResolvedEngineConfig } from './config.js';
 import { type EngineDeps, type ProducedImage } from './engine.js';
-import { type StandardImageRequest } from './translate.js';
+import type { StandardImageRequest } from './translate.js';
 /** One recorded attempt against one engine, success or failure. */
 export interface AttemptView {
     /** Engine id. */
@@ -131,8 +131,6 @@ export declare class EngineRouter {
     private chainOrder;
     /** Why an engine may not even be attempted: disabled, cooling down. */
     private skipReason;
-    /** Translate the standard request against one engine (the pure translate step). */
-    private translate;
     /** Record a success: reset consecutive failures and cooldown. */
     private recordSuccess;
     /** Record a failure: bump the counter, trip cooldown at the threshold, and build the attempt view. */

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

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

package/lib/types/router.js

@@ -7,9 +7,9 @@
  *
  * @module dsh-draw/router
  */
-import { callEngine, EngineCallError } from './engine.js';
+import { EngineCallError } from './engine.js';
+import { providerFor } from './provider.js';
 import { sanitizeError, sanitizeText, sanitizeUrl } from './sanitize.js';
-import { translateRequest } from './translate.js';
 /**
  * The engine chain with per-engine health and cooldown. All mutations are
  * synchronous bookkeeping guarded by `generate`'s single-writer path (the
@@ -56,7 +56,7 @@ export class EngineRouter {
             }
             tried += 1;
             try {
-                const images = await callEngine(engine, this.translate(engine, request), deps, signal);
+                const images = await providerFor(engine.provider).generate(engine, request, deps, signal);
                 this.recordSuccess(engine.id);
                 attempts.push({ engine: engine.id, code: 'ok' });
                 return {
@@ -172,10 +172,6 @@ export class EngineRouter {
         }
         return undefined;
     }
-    /** Translate the standard request against one engine (the pure translate step). */
-    translate(engine, request) {
-        return translateRequest(engine, request);
-    }
     /** Record a success: reset consecutive failures and cooldown. */
     recordSuccess(engineId) {
         const health = this.health.get(engineId);

package/lib/types/version.d.ts

@@ -1,10 +1,11 @@
 /**
  * The plugin version, hardcoded beside `package.json` so the release script
- * bumps both and `tests/version.spec.ts` trips when they drift. Served in the
- * `draw/status` snapshot so the settings panel shows which plugin build runs.
+ * bumps both and the version tripwire in `tests/session-events.spec.ts` trips
+ * when they drift. Served in the `draw/status` snapshot so the settings panel
+ * shows which plugin build runs.
  *
  * @module dsh-draw/version
  */
 /** Plugin version; must equal the `version` field in `package.json`. */
-export declare const PLUGIN_VERSION = "0.1.2";
+export declare const PLUGIN_VERSION = "0.2.1";
 //# sourceMappingURL=version.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wEAAwE;AACxE,eAAO,MAAM,cAAc,UAAU,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wEAAwE;AACxE,eAAO,MAAM,cAAc,UAAU,CAAA"}

package/lib/types/version.js

@@ -1,9 +1,10 @@
 /**
  * The plugin version, hardcoded beside `package.json` so the release script
- * bumps both and `tests/version.spec.ts` trips when they drift. Served in the
- * `draw/status` snapshot so the settings panel shows which plugin build runs.
+ * bumps both and the version tripwire in `tests/session-events.spec.ts` trips
+ * when they drift. Served in the `draw/status` snapshot so the settings panel
+ * shows which plugin build runs.
  *
  * @module dsh-draw/version
  */
 /** Plugin version; must equal the `version` field in `package.json`. */
-export const PLUGIN_VERSION = '0.1.2';
+export const PLUGIN_VERSION = '0.2.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-draw",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Unified static-image generation router for DeepSeek Harness: one image_generate tool with standard parameters, config-driven OpenAI-compatible engine routing (OpenAI Images, Zhipu CogView, and any compatible endpoint) with health-aware fallback, durable workspace attachment results, per-session quota accounting, an in-conversation result card, and a Plugins settings panel that stores API keys as credential references.",
   "repository": {
     "type": "git",
@@ -129,7 +129,33 @@
     "@deepseek-ai/dsh-session": ">=0.1.0-rc.8 <0.2.0",
     "@deepseek-ai/dsh-tools": ">=0.1.0-rc.8 <0.2.0",
     "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.8 <0.2.0",
-    "@deepseek-ai/schemastery": "^3.18.0"
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-runtime": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.1-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-client-ui-tool": ">=0.1.1-rc.2 <0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-client-connection": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-runtime": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-tool": {
+      "optional": true
+    }
   },
   "dependencies": {
     "tsdown": "^0.22.14",

package/src/client/present.ts

@@ -111,9 +111,11 @@ export interface PresentedDrawPanel {
  * Project the panel snapshot onto the settings row model.
  *
  * @param snapshot - the `draw/status` wire snapshot.
+ * @param now - clock override for the cooldown flag (default {@link Date.now});
+ *   injected so the presenter stays a pure function of its inputs.
  * @returns the presented panel model.
  */
-export function presentDrawPanel(snapshot: DrawStatusSnapshot): PresentedDrawPanel {
+export function presentDrawPanel(snapshot: DrawStatusSnapshot, now: () => number = Date.now): PresentedDrawPanel {
   return {
     pluginVersion: snapshot.pluginVersion,
     engines: snapshot.engines.map(engine => ({
@@ -127,7 +129,7 @@ export function presentDrawPanel(snapshot: DrawStatusSnapshot): PresentedDrawPan
       ...(engine.credential.source !== undefined ? { credentialSource: engine.credential.source } : {}),
       credentialWritable: engine.credential.writable,
       consecutiveFailures: engine.health.consecutiveFailures,
-      coolingDown: engine.health.cooldownUntil !== null && engine.health.cooldownUntil > Date.now(),
+      coolingDown: engine.health.cooldownUntil !== null && engine.health.cooldownUntil > now(),
       lastError: engine.health.lastError,
     })),
     quota: { maxGenerationsPerSession: snapshot.quota.maxGenerationsPerSession, maxBytesPerSession: snapshot.quota.maxBytesPerSession },

package/src/config.ts

@@ -70,6 +70,9 @@ export interface EngineSizeMap {
 /** Whether generated images arrive as base64 payloads or downloadable URLs. */
 export type EngineResponseFormat = 'b64_json' | 'url'
 
+/** The image-generation vocabularies a configured engine may declare (provider seam). */
+export type EngineVocabulary = 'openai' | 'replicate' | 'fal'
+
 /** One OpenAI-compatible image-generation endpoint the router may use. */
 export interface EngineConfig {
   /** Stable engine id used in tool args, results, and the settings panel. */
@@ -80,6 +83,8 @@ export interface EngineConfig {
   model: string
   /** Credential reference (environment-variable name) the API key resolves from; never a literal key. */
   apiKeyRef: string
+  /** Which request/response vocabulary this engine speaks (default `openai`). */
+  provider?: EngineVocabulary
   /** Whether the router may use this engine (default true). */
   enabled?: boolean
   /** Standard-size → concrete-size translation (default: the OpenAI sizes). */
@@ -123,6 +128,7 @@ export const DEFAULT_ENGINES: ReadonlyArray<Required<EngineConfig>> = Object.fre
     baseUrl: 'https://api.openai.com/v1',
     model: 'gpt-image-1',
     apiKeyRef: 'OPENAI_API_KEY',
+    provider: 'openai',
     enabled: true,
     sizeMap: Object.freeze({ square: '1024x1024', landscape: '1536x1024', portrait: '1024x1536', auto: 'auto' }),
     qualitySupported: true,
@@ -135,6 +141,7 @@ export const DEFAULT_ENGINES: ReadonlyArray<Required<EngineConfig>> = Object.fre
     baseUrl: 'https://open.bigmodel.cn/api/paas/v4',
     model: 'cogview-3-flash',
     apiKeyRef: 'ZHIPU_API_KEY',
+    provider: 'openai',
     enabled: true,
     sizeMap: Object.freeze({ square: '1024x1024', landscape: '1344x768', portrait: '768x1344', auto: '1024x1024' }),
     qualitySupported: false,
@@ -162,6 +169,8 @@ export interface ResolvedEngineConfig {
   model: string
   /** Credential reference the API key resolves from. */
   apiKeyRef: string
+  /** Request/response vocabulary this engine speaks. */
+  provider: EngineVocabulary
   /** Whether the router may use this engine. */
   enabled: boolean
   /** Standard-size → concrete-size translation. */
@@ -205,6 +214,7 @@ export const Config: z<Config> = z.object({
     baseUrl: z.string().min(1).max(2048),
     model: z.string().min(1).max(128),
     apiKeyRef: z.string().min(1).max(128),
+    provider: z.union(['openai', 'replicate', 'fal'] as const),
     enabled: z.boolean(),
     sizeMap: z.object({
       square: z.string().min(1).max(64),
@@ -269,6 +279,10 @@ export function resolveConfig(config: Config | undefined): ResolvedConfig {
     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 provider = engine.provider ?? 'openai'
+    if (provider !== 'openai' && provider !== 'replicate' && provider !== 'fal') {
+      throw new Error(`dsh-draw: engine "${id}" provider must be one of "openai", "replicate", "fal", got ${JSON.stringify(provider)}`)
+    }
     const sizeMap = engine.sizeMap === undefined ? DEFAULT_SIZE_MAP : engine.sizeMap
     for (const key of ['square', 'landscape', 'portrait', 'auto'] as const) {
       const value = sizeMap[key]
@@ -295,6 +309,7 @@ export function resolveConfig(config: Config | undefined): ResolvedConfig {
       baseUrl: baseUrl.replace(/\/+$/u, ''),
       model,
       apiKeyRef,
+      provider,
       enabled,
       sizeMap: Object.freeze({ ...sizeMap }),
       qualitySupported,

package/src/index.ts

@@ -40,6 +40,7 @@ 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 { providerFor, PROVIDERS, type EngineProvider, type EngineVocabulary } from './provider.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'

package/src/provider.ts

@@ -0,0 +1,237 @@
+/**
+ * The engine-provider seam: one adapter per image-generation vocabulary. The
+ * OpenAI provider is the existing OpenAI-compatible `POST /images/generations`
+ * adapter; `replicate` and `fal` adapters speak those vendors' native request
+ * and response shapes (prediction polling and `fal.run` queue respectively).
+ * A configured engine declares its vocabulary (`provider`); the router
+ * dispatches through {@link providerFor}, so cooldown fallback, quota, and the
+ * audit path stay vocabulary-agnostic.
+ *
+ * @module dsh-draw/provider
+ */
+
+import type { ResolvedEngineConfig } from './config.ts'
+import {
+  callEngine,
+  EngineCallError,
+  type EngineDeps,
+  type ProducedImage,
+} from './engine.ts'
+import type { StandardImageRequest } from './translate.ts'
+import { translateRequest } from './translate.ts'
+
+/** The image-generation vocabularies a configured engine may declare. */
+export type EngineVocabulary = 'openai' | 'replicate' | 'fal'
+
+/**
+ * One engine adapter: translates the standard tool request into a vendor
+ * request, calls it, and returns produced image bytes. A provider must never
+ * leak the credential — `deps.resolveCredential` resolves it per call.
+ */
+export interface EngineProvider {
+  /** Which vocabulary this adapter speaks. */
+  readonly vocabulary: EngineVocabulary
+  /**
+   * Generate images for one standardized request.
+   * @param engine - resolved engine configuration.
+   * @param request - normalized standard request.
+   * @param deps - transport and credential resolution.
+   * @param signal - caller cancellation.
+   * @returns the produced images.
+   */
+  generate(engine: ResolvedEngineConfig, request: StandardImageRequest, deps: EngineDeps, signal?: AbortSignal): Promise<ProducedImage[]>
+}
+
+/** The OpenAI-compatible adapter: delegates to the existing `/images/generations` path. */
+const openaiProvider: EngineProvider = {
+  vocabulary: 'openai',
+  generate(engine, request, deps, signal) {
+    return callEngine(engine, translateRequest(engine, request), deps, signal)
+  },
+}
+
+/** Replicate prediction polling interval (ms). */
+const REPLICATE_POLL_INTERVAL_MS = 1_000
+
+/** Maximum prediction polls before the call fails as a slow request. */
+const REPLICATE_MAX_POLLS = 120
+
+/** Parse one concrete `WIDTHxHEIGHT` size string into dimensions. */
+function dimensionsOf(size: string): { width: number; height: number } | undefined {
+  const match = /^(\d{2,5})x(\d{2,5})$/u.exec(size)
+  if (match === null) return undefined
+  return { width: Number(match[1]), height: Number(match[2]) }
+}
+
+/** Resolve an engine credential, failing closed when it is unconfigured. */
+async function requireCredential(engine: ResolvedEngineConfig, deps: EngineDeps): Promise<string> {
+  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}`)
+  }
+  return credential
+}
+
+/** Parse a JSON response body, failing with a structured parse error. */
+function parseJson(engine: ResolvedEngineConfig, body: Uint8Array): Record<string, unknown> {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(body))
+  } catch (cause) {
+    throw new EngineCallError('parse', 'parse', `engine "${engine.id}" returned a non-JSON response`, { cause })
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new EngineCallError('parse', 'parse', `engine "${engine.id}" returned a non-object payload`)
+  }
+  return parsed as Record<string, unknown>
+}
+
+/** Download one image URL with an explicit authorization header value. */
+async function downloadImage(
+  engine: ResolvedEngineConfig,
+  url: string,
+  authorization: string,
+  deps: EngineDeps,
+  signal?: AbortSignal,
+): Promise<Uint8Array> {
+  const response = await deps.transport.request({
+    method: 'GET',
+    url,
+    headers: { authorization },
+    ...(signal === undefined ? {} : { signal }),
+  })
+  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
+}
+
+/** Sleep without swallowing the caller's abort (checked by the caller's loop). */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/** The Replicate adapter: create a prediction, poll to completion, then download its output URLs. */
+const replicateProvider: EngineProvider = {
+  vocabulary: 'replicate',
+  async generate(engine, request, deps, signal) {
+    const credential = await requireCredential(engine, deps)
+    const dimensions = dimensionsOf(engine.sizeMap[request.size ?? 'square'])
+    const input: Record<string, unknown> = {
+      prompt: request.prompt,
+      num_outputs: request.count ?? 1,
+      ...(dimensions === undefined ? {} : { width: dimensions.width, height: dimensions.height }),
+    }
+    const create = await deps.transport.request({
+      method: 'POST',
+      url: `${engine.baseUrl}/models/${engine.model}/predictions`,
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${credential}` },
+      body: new TextEncoder().encode(JSON.stringify({ input })),
+      ...(signal === undefined ? {} : { signal }),
+    })
+    if (create.status === 401 || create.status === 403) {
+      throw new EngineCallError('request', 'auth', `engine "${engine.id}" rejected the credential (HTTP ${create.status})`, { status: create.status })
+    }
+    if (create.status < 200 || create.status >= 300) {
+      throw new EngineCallError('request', 'http', `engine "${engine.id}" failed with HTTP ${create.status}`, { status: create.status })
+    }
+    let prediction = parseJson(engine, create.body)
+    const id = typeof prediction['id'] === 'string' ? prediction['id'] : ''
+    const urls = typeof prediction['urls'] === 'object' && prediction['urls'] !== null
+      ? prediction['urls'] as Record<string, unknown>
+      : {}
+    const pollUrl = typeof urls['get'] === 'string' && urls['get'] !== '' ? urls['get'] : `${engine.baseUrl}/predictions/${id}`
+    for (let poll = 0; poll < REPLICATE_MAX_POLLS; poll += 1) {
+      signal?.throwIfAborted()
+      const status = typeof prediction['status'] === 'string' ? prediction['status'] : ''
+      if (status === 'succeeded') break
+      if (status === 'failed' || status === 'canceled') {
+        throw new EngineCallError('request', 'http', `engine "${engine.id}" prediction ${status}`)
+      }
+      await sleep(REPLICATE_POLL_INTERVAL_MS)
+      const polled = await deps.transport.request({
+        method: 'GET',
+        url: pollUrl,
+        headers: { authorization: `Bearer ${credential}` },
+        ...(signal === undefined ? {} : { signal }),
+      })
+      if (polled.status < 200 || polled.status >= 300) {
+        throw new EngineCallError('request', 'http', `engine "${engine.id}" prediction poll failed with HTTP ${polled.status}`, { status: polled.status })
+      }
+      prediction = parseJson(engine, polled.body)
+    }
+    if (prediction['status'] !== 'succeeded') {
+      throw new EngineCallError('request', 'http', `engine "${engine.id}" prediction did not finish within ${REPLICATE_MAX_POLLS} polls`)
+    }
+    const output = prediction['output']
+    if (!Array.isArray(output)) {
+      throw new EngineCallError('parse', 'parse', `engine "${engine.id}" prediction has no output array`)
+    }
+    const images: ProducedImage[] = []
+    for (const item of output) {
+      if (typeof item !== 'string' || item === '') {
+        throw new EngineCallError('parse', 'parse', `engine "${engine.id}" prediction returned a non-URL output entry`)
+      }
+      images.push({ data: await downloadImage(engine, item, `Bearer ${credential}`, deps, signal), mediaType: engine.imageMediaType })
+    }
+    if (images.length === 0) {
+      throw new EngineCallError('parse', 'parse', `engine "${engine.id}" prediction returned no images`)
+    }
+    return images
+  },
+}
+
+/** The fal.ai adapter: POST the `fal.run` queue endpoint and download the returned image URLs. */
+const falProvider: EngineProvider = {
+  vocabulary: 'fal',
+  async generate(engine, request, deps, signal) {
+    const credential = await requireCredential(engine, deps)
+    const body: Record<string, unknown> = {
+      prompt: request.prompt,
+      image_size: engine.sizeMap[request.size ?? 'square'],
+      num_images: request.count ?? 1,
+    }
+    const response = await deps.transport.request({
+      method: 'POST',
+      url: `${engine.baseUrl}/${engine.model}`,
+      headers: { 'content-type': 'application/json', authorization: `Key ${credential}` },
+      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 })
+    }
+    const payload = parseJson(engine, response.body)
+    const entries = payload['images']
+    if (!Array.isArray(entries)) {
+      throw new EngineCallError('parse', 'parse', `engine "${engine.id}" response has no images array`)
+    }
+    const images: ProducedImage[] = []
+    for (const raw of entries) {
+      const url = typeof raw === 'object' && raw !== null ? (raw as Record<string, unknown>)['url'] : undefined
+      if (typeof url !== 'string' || url === '') {
+        throw new EngineCallError('parse', 'parse', `engine "${engine.id}" returned an image entry without a URL`)
+      }
+      images.push({ data: await downloadImage(engine, url, `Key ${credential}`, deps, signal), mediaType: engine.imageMediaType })
+    }
+    if (images.length === 0) {
+      throw new EngineCallError('parse', 'parse', `engine "${engine.id}" returned no images`)
+    }
+    return images
+  },
+}
+
+/** The provider registry, keyed by vocabulary. */
+export const PROVIDERS: Readonly<Record<EngineVocabulary, EngineProvider>> = Object.freeze({
+  openai: openaiProvider,
+  replicate: replicateProvider,
+  fal: falProvider,
+})
+
+/** Resolve the provider for one vocabulary (always present — the config gate restricts the value). */
+export function providerFor(vocabulary: EngineVocabulary): EngineProvider {
+  return PROVIDERS[vocabulary]
+}

package/src/router.ts

@@ -9,9 +9,10 @@
  */
 
 import type { ResolvedConfig, ResolvedEngineConfig } from './config.ts'
-import { callEngine, EngineCallError, type EngineDeps, type ProducedImage } from './engine.ts'
+import { EngineCallError, type EngineDeps, type ProducedImage } from './engine.ts'
+import { providerFor } from './provider.ts'
 import { sanitizeError, sanitizeText, sanitizeUrl } from './sanitize.ts'
-import { translateRequest, type StandardImageRequest } from './translate.ts'
+import type { StandardImageRequest } from './translate.ts'
 
 /** One recorded attempt against one engine, success or failure. */
 export interface AttemptView {
@@ -156,7 +157,7 @@ export class EngineRouter {
       }
       tried += 1
       try {
-        const images = await callEngine(engine, this.translate(engine, request), deps, signal)
+        const images = await providerFor(engine.provider).generate(engine, request, deps, signal)
         this.recordSuccess(engine.id)
         attempts.push({ engine: engine.id, code: 'ok' })
         return {
@@ -273,11 +274,6 @@ export class EngineRouter {
     return undefined
   }
 
-  /** Translate the standard request against one engine (the pure translate step). */
-  private translate(engine: ResolvedEngineConfig, request: StandardImageRequest) {
-    return translateRequest(engine, request)
-  }
-
   /** Record a success: reset consecutive failures and cooldown. */
   private recordSuccess(engineId: string): void {
     const health = this.health.get(engineId)

package/src/version.ts

@@ -1,10 +1,11 @@
 /**
  * The plugin version, hardcoded beside `package.json` so the release script
- * bumps both and `tests/version.spec.ts` trips when they drift. Served in the
- * `draw/status` snapshot so the settings panel shows which plugin build runs.
+ * bumps both and the version tripwire in `tests/session-events.spec.ts` trips
+ * when they drift. Served in the `draw/status` snapshot so the settings panel
+ * shows which plugin build runs.
  *
  * @module dsh-draw/version
  */
 
 /** Plugin version; must equal the `version` field in `package.json`. */
-export const PLUGIN_VERSION = '0.1.2'
+export const PLUGIN_VERSION = '0.2.1'