dsh-draw 0.1.0

package/src/quota.ts

@@ -0,0 +1,98 @@
+/**
+ * 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'
+import { drawGeneratedEvents } from './session-events.ts'
+
+/** 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 function quotaState(session: Session): QuotaState {
+  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: Session, limits: QuotaLimits): QuotaCheck {
+  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: Session, limits: QuotaLimits, incomingBytes: number): QuotaCheck {
+  const state = quotaState(session)
+  if (state.bytes + incomingBytes > limits.maxBytes) {
+    return { allowed: false, reason: 'bytes', state }
+  }
+  return { allowed: true, state }
+}

package/src/router.ts

@@ -0,0 +1,309 @@
+/**
+ * Engine routing with health-aware fallback: the configured chain is walked
+ * top-down, every engine is attempted at most once per call, and consecutive
+ * failures push an engine into cooldown so a broken engine stops eating the
+ * request budget. The router is a plain class (not a Cordis Service): it is
+ * plugin-owned state, not a published capability.
+ *
+ * @module dsh-draw/router
+ */
+
+import type { ResolvedConfig, ResolvedEngineConfig } from './config.ts'
+import { callEngine, EngineCallError, type EngineDeps, type ProducedImage } from './engine.ts'
+import { sanitizeError, sanitizeText, sanitizeUrl } from './sanitize.ts'
+import { translateRequest, type StandardImageRequest } from './translate.ts'
+
+/** One recorded attempt against one engine, success or failure. */
+export interface AttemptView {
+  /** Engine id. */
+  engine: string
+  /** Failure phase for a failed attempt; absent on success. */
+  phase?: 'credential' | 'request' | 'parse'
+  /** Stable machine code: `unconfigured`, `auth`, `http`, `parse`, `disabled`, `cooldown`. */
+  code: string
+  /** Display-safe failure detail; absent on success. */
+  message?: string
+  /** HTTP status when one existed. */
+  status?: number
+}
+
+/** A successful routed generation. */
+export interface RouterSuccess {
+  /** Discriminant. */
+  ok: true
+  /** Engine id that produced the images. */
+  engine: string
+  /** Engine model name. */
+  model: string
+  /** Standard size vocabulary value of the request. */
+  size: string
+  /** Produced images. */
+  images: readonly ProducedImage[]
+  /** Whether an earlier engine in the chain failed first. */
+  fallbackUsed: boolean
+  /** Every attempt in chain order. */
+  attempts: readonly AttemptView[]
+}
+
+/** A routed generation where every usable engine failed or was skipped. */
+export interface RouterFailure {
+  /** Discriminant. */
+  ok: false
+  /** Every attempt in chain order. */
+  attempts: readonly AttemptView[]
+}
+
+/** Router result. */
+export type RouterResult = RouterSuccess | RouterFailure
+
+/** One engine's health state for the settings panel. */
+export interface EngineStatus {
+  /** Engine id. */
+  engineId: string
+  /** Consecutive failures since the last success. */
+  consecutiveFailures: number
+  /** Epoch ms until which the engine is in cooldown; `null` = not cooling down. */
+  cooldownUntil: number | null
+  /** Display-safe last failure detail; `null` = none recorded. */
+  lastError: string | null
+  /** HTTP status of the last failure, when one existed. */
+  lastStatus: number | null
+}
+
+/** One probe outcome (never mutates routing health). */
+export interface ProbeOutcome {
+  /** Engine id. */
+  engineId: string
+  /** Whether the endpoint answered with any HTTP status. */
+  reachable: boolean
+  /** HTTP status when one existed. */
+  httpStatus: number | null
+  /** Sanitized base URL probed (the models listing endpoint). */
+  target: string
+  /** Display-safe result note. */
+  note: string
+  /** Whether the credential was resolvable at probe time. */
+  credentialConfigured: boolean
+}
+
+/** Engine bookkeeping the router mutates. */
+interface EngineHealth {
+  /** Consecutive failures since the last success. */
+  consecutiveFailures: number
+  /** Epoch ms until which the engine is in cooldown; `null` = not cooling down. */
+  cooldownUntil: number | null
+  /** Display-safe last failure detail. */
+  lastError: string | null
+  /** HTTP status of the last failure. */
+  lastStatus: number | null
+}
+
+/** Router construction options. */
+export interface RouterOptions {
+  /** Consecutive failures before an engine enters cooldown. */
+  failureThreshold: number
+  /** Cooldown length in milliseconds. */
+  cooldownMs: number
+  /** Clock override for tests. */
+  now?: () => number
+}
+
+/**
+ * The engine chain with per-engine health and cooldown. All mutations are
+ * synchronous bookkeeping guarded by `generate`'s single-writer path (the
+ * tool is not concurrency-safe, so generations serialize).
+ */
+export class EngineRouter {
+  private readonly health = new Map<string, EngineHealth>()
+  private readonly now: () => number
+
+  /**
+   * @param config - resolved plugin configuration (engine order and bounds).
+   * @param options - failure threshold, cooldown, and clock.
+   */
+  constructor(
+    private readonly config: ResolvedConfig,
+    options: RouterOptions,
+  ) {
+    this.now = options.now ?? Date.now
+    for (const engine of config.engines) {
+      this.health.set(engine.id, { consecutiveFailures: 0, cooldownUntil: null, lastError: null, lastStatus: null })
+    }
+  }
+
+  /**
+   * Route one standardized request through the configured chain. The chain
+   * order is the config array order, except an explicit `request.engine`
+   * promotes that engine to the front; every engine is attempted at most
+   * once, and an engine in cooldown or without a resolved credential is
+   * skipped with a recorded attempt.
+   *
+   * @param request - normalized standard request.
+   * @param deps - transport and credential resolution.
+   * @param signal - caller cancellation.
+   * @returns success with images, or the complete failure record.
+   */
+  async generate(request: StandardImageRequest, deps: EngineDeps, signal?: AbortSignal): Promise<RouterResult> {
+    const ordered = this.chainOrder(request.engine)
+    const attempts: AttemptView[] = []
+    let tried = 0
+    for (const engine of ordered) {
+      if (tried > 0) signal?.throwIfAborted()
+      const skip = this.skipReason(engine)
+      if (skip !== undefined) {
+        attempts.push({ engine: engine.id, code: skip.code, message: skip.message })
+        continue
+      }
+      tried += 1
+      try {
+        const images = await callEngine(engine, this.translate(engine, request), deps, signal)
+        this.recordSuccess(engine.id)
+        attempts.push({ engine: engine.id, code: 'ok' })
+        return {
+          ok: true,
+          engine: engine.id,
+          model: engine.model,
+          size: request.size ?? 'square',
+          images,
+          fallbackUsed: tried > 1,
+          attempts,
+        }
+      } catch (error) {
+        const view = this.recordFailure(engine.id, error)
+        attempts.push(view)
+        if (view.phase === 'credential' || view.code === 'auth' || view.code === 'parse') {
+          // Credential and schema failures are deterministic for this engine —
+          // continue the chain so a healthy next engine still serves the call.
+          continue
+        }
+        if (signal !== undefined && signal.aborted) throw signal.reason
+        continue
+      }
+    }
+    return { ok: false, attempts }
+  }
+
+  /** One engine's current health snapshot. */
+  statusOf(engineId: string): EngineStatus | undefined {
+    const health = this.health.get(engineId)
+    if (health === undefined) return undefined
+    return {
+      engineId,
+      consecutiveFailures: health.consecutiveFailures,
+      cooldownUntil: health.cooldownUntil,
+      lastError: health.lastError,
+      lastStatus: health.lastStatus,
+    }
+  }
+
+  /** Health snapshots for every configured engine in chain order. */
+  statuses(): readonly EngineStatus[] {
+    return this.config.engines
+      .map(engine => this.statusOf(engine.id))
+      .filter((status): status is EngineStatus => status !== undefined)
+  }
+
+  /**
+   * Probe one engine with a cheap authenticated `GET {baseUrl}/models` call.
+   * The probe reports reachability and credential validity without mutating
+   * routing health — it is a settings-panel check, not the router's memory.
+   *
+   * @param engine - engine to probe.
+   * @param deps - transport and credential resolution.
+   * @returns the probe outcome.
+   */
+  async probe(engine: ResolvedEngineConfig, deps: EngineDeps): Promise<ProbeOutcome> {
+    const target = sanitizeUrl(`${engine.baseUrl}/models`)
+    const credential = await deps.resolveCredential(engine.apiKeyRef)
+    if (credential === undefined) {
+      return { engineId: engine.id, reachable: false, httpStatus: null, target, note: `credential reference ${engine.apiKeyRef} is not configured`, credentialConfigured: false }
+    }
+    try {
+      const response = await deps.transport.request({
+        method: 'GET',
+        url: `${engine.baseUrl}/models`,
+        headers: { authorization: `Bearer ${credential}` },
+      })
+      if (response.status === 401 || response.status === 403) {
+        return { engineId: engine.id, reachable: true, httpStatus: response.status, target, note: `endpoint answered but rejected the credential (HTTP ${response.status})`, credentialConfigured: true }
+      }
+      if (response.status === 404 || response.status === 405 || response.status === 501) {
+        return { engineId: engine.id, reachable: true, httpStatus: response.status, target, note: `endpoint answered (HTTP ${response.status}); the models listing may be absent but generation can still work`, credentialConfigured: true }
+      }
+      if (response.status < 200 || response.status >= 300) {
+        return { engineId: engine.id, reachable: true, httpStatus: response.status, target, note: `endpoint answered with HTTP ${response.status}`, credentialConfigured: true }
+      }
+      return { engineId: engine.id, reachable: true, httpStatus: response.status, target, note: 'endpoint reachable and credential accepted', credentialConfigured: true }
+    } catch (error) {
+      return { engineId: engine.id, reachable: false, httpStatus: null, target, note: sanitizeError(error), credentialConfigured: true }
+    }
+  }
+
+  /** Chain order: an explicit engine override first, then config order minus the override. */
+  private chainOrder(override: string | undefined): readonly ResolvedEngineConfig[] {
+    const engines = [...this.config.engines]
+    if (override === undefined || override === this.config.defaultEngine) {
+      const index = engines.findIndex(engine => engine.id === this.config.defaultEngine)
+      if (index > 0) {
+        const [preferred] = engines.splice(index, 1)
+        engines.unshift(preferred!)
+      }
+      return engines
+    }
+    const index = engines.findIndex(engine => engine.id === override)
+    if (index < 0) {
+      // Unknown override: fall back to the configured chain (the override
+      // intent is recorded nowhere else; the tool output names the engine).
+      return engines
+    }
+    const [preferred] = engines.splice(index, 1)
+    engines.unshift(preferred!)
+    return engines
+  }
+
+  /** Why an engine may not even be attempted: disabled, cooling down. */
+  private skipReason(engine: ResolvedEngineConfig): { code: string; message: string } | undefined {
+    if (!engine.enabled) return { code: 'disabled', message: `engine "${engine.id}" is disabled` }
+    const health = this.health.get(engine.id)
+    const now = this.now()
+    const cooldown = health?.cooldownUntil
+    if (cooldown !== null && cooldown !== undefined && cooldown > now) {
+      return { code: 'cooldown', message: `engine "${engine.id}" is cooling down after repeated failures` }
+    }
+    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)
+    if (health === undefined) return
+    health.consecutiveFailures = 0
+    health.cooldownUntil = null
+    health.lastError = null
+    health.lastStatus = null
+  }
+
+  /** Record a failure: bump the counter, trip cooldown at the threshold, and build the attempt view. */
+  private recordFailure(engineId: string, error: unknown): AttemptView {
+    const health = this.health.get(engineId)
+    const engineError = error instanceof EngineCallError ? error : undefined
+    const phase = engineError?.phase ?? 'request'
+    const code = engineError?.code ?? 'http'
+    const message = sanitizeText(sanitizeError(error))
+    const status = engineError?.status
+    if (health !== undefined) {
+      health.consecutiveFailures += 1
+      health.lastError = message
+      health.lastStatus = status ?? null
+      if (health.consecutiveFailures >= this.config.failureThreshold) {
+        health.cooldownUntil = this.now() + this.config.cooldownMs
+      }
+    }
+    return { engine: engineId, phase, code, message, ...(status !== undefined ? { status } : {}) }
+  }
+}

package/src/sanitize.ts

@@ -0,0 +1,113 @@
+/**
+ * Display sanitization for dsh-draw surfaces. Everything shown to a human —
+ * the tool result text, the settings panel snapshot, probe details, engine
+ * errors — passes through these pure functions so URL credentials, API keys,
+ * bearer tokens, and JWTs never reach a display. Secrets themselves are
+ * credential references; this module redacts what can still leak through
+ * configured URLs and provider error text.
+ *
+ * @module dsh-draw/sanitize
+ */
+
+/** Replacement for every redacted credential value. */
+export const REDACTED = '***'
+
+/** Query/field keys whose values are credentials regardless of their name casing. */
+const CREDENTIAL_KEY = /^(?:access[_-]?token|api[_-]?key|apikey|auth|authorization|client[_-]?secret|key|password|passwd|pwd|secret|sig|signature|token)$/iu
+
+/** Credential keys for the unparseable-URL fallback and embedded-text scans. */
+const CREDENTIAL_KEY_SOURCE = '(?:access[_-]?token|api[_-]?key|apikey|auth(?:orization)?|client[_-]?secret|key|passw(?:or)?d|passwd|pwd|secret|sig(?:nature)?|token)'
+
+/** Whole userinfo before `@` (unparseable URLs only — parsed URLs redact just the password). */
+const USERINFO = /([a-z][a-z0-9+.-]*:\/\/)([^/@\s]+)@/giu
+
+/** `?key=value` / `&key=value` credential pairs inside arbitrary text. */
+const QUERY_CREDENTIAL = new RegExp(`([?&](?:[^=&#\\s]*${CREDENTIAL_KEY_SOURCE}[^=&#\\s]*)=)[^&#\\s]*`, 'giu')
+
+/** `#key=value` credential pairs in URL fragments and arbitrary text. */
+const FRAGMENT_CREDENTIAL = new RegExp(`(#[^=&#\\s]*${CREDENTIAL_KEY_SOURCE}[^=&#\\s]*=)[^&#\\s]*`, 'giu')
+
+/** `Authorization: <value>`-style header lines in arbitrary text (quoted value first). */
+const HEADER_CREDENTIAL_QUOTED = new RegExp(`(\\b${CREDENTIAL_KEY_SOURCE}\\s*[:=]\\s*["'])[^"']*(["'])`, 'giu')
+
+/** `Authorization: <value>`-style header lines with unquoted values. */
+const HEADER_CREDENTIAL_BARE = new RegExp(`(\\b${CREDENTIAL_KEY_SOURCE}\\s*[:=]\\s*)[^\\s,;)\\]}]+`, 'giu')
+
+/** Environment-variable-shaped credentials (`GITHUB_TOKEN=…`) in spawn errors. */
+const ENV_VAR_CREDENTIAL = /\b[A-Za-z0-9_]*(?:TOKEN|API[_-]?KEY|SECRET|PASSWORD|PASSWD)[A-Za-z0-9_]*\s*=\s*[^\s,;)\]}]+/gu
+
+/** Bearer tokens, including the `Bearer ` keyword and the token itself. */
+const BEARER = /(bearer)\s+[A-Za-z0-9._~+/=-]+/giu
+
+/** Quoted JSON-ish `"token": "value"` pairs in arbitrary text. */
+const QUOTED_CREDENTIAL = new RegExp(`(["'](?:access[_-]?token|api[_-]?key|client[_-]?secret|secret|token)["']\\s*[:=]\\s*["'])[^"']*(["'])`, 'giu')
+
+/** Raw JWT bodies, wherever they appear. */
+const JWT = /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/gu
+
+/**
+ * Redact a URL for display: userinfo password, credential query values, and
+ * credential fragment pairs. Query keys are read through `URLSearchParams`,
+ * so percent-encoded key names are decoded before matching. Unparseable
+ * inputs fall back to pattern redaction (whole userinfo, credential query
+ * pairs, credential fragment pairs) instead of throwing.
+ *
+ * @param url - candidate URL text.
+ * @returns display-safe URL text.
+ */
+export function sanitizeUrl(url: string): string {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return url
+      .replace(USERINFO, '$1***@')
+      .replace(QUERY_CREDENTIAL, `$1${REDACTED}`)
+      .replace(FRAGMENT_CREDENTIAL, `$1${REDACTED}`)
+  }
+  if (parsed.password !== '') parsed.password = REDACTED
+  for (const key of [...parsed.searchParams.keys()]) {
+    if (CREDENTIAL_KEY.test(key)) parsed.searchParams.set(key, REDACTED)
+  }
+  if (parsed.hash !== '') parsed.hash = parsed.hash.replace(FRAGMENT_CREDENTIAL, `$1${REDACTED}`)
+  return parsed.toString()
+}
+
+/**
+ * Redact credential-shaped fragments from free text: header lines, bearer
+ * tokens, raw JWTs, embedded query pairs, and quoted token values.
+ *
+ * @param text - candidate display text.
+ * @returns display-safe text.
+ */
+export function sanitizeText(text: string): string {
+  return text
+    .replace(BEARER, `$1 ${REDACTED}`)
+    .replace(HEADER_CREDENTIAL_QUOTED, `$1${REDACTED}$2`)
+    .replace(HEADER_CREDENTIAL_BARE, `$1${REDACTED}`)
+    .replace(ENV_VAR_CREDENTIAL, value => {
+      const equals = value.indexOf('=')
+      return equals < 0 ? value : `${value.slice(0, equals)}=${REDACTED}`
+    })
+    .replace(QUOTED_CREDENTIAL, `$1${REDACTED}$2`)
+    .replace(QUERY_CREDENTIAL, `$1${REDACTED}`)
+    .replace(FRAGMENT_CREDENTIAL, `$1${REDACTED}`)
+    .replace(JWT, REDACTED)
+}
+
+/**
+ * Stringify an arbitrary thrown value safely and redact it for display.
+ * Never throws: unrenderable values degrade to a fixed marker.
+ *
+ * @param error - thrown value from an engine call or probe.
+ * @returns display-safe error text.
+ */
+export function sanitizeError(error: unknown): string {
+  let text: string
+  try {
+    text = typeof error === 'string' ? error : String(error)
+  } catch {
+    text = '<unrenderable error>'
+  }
+  return sanitizeText(text)
+}

package/src/service.ts

@@ -0,0 +1,169 @@
+/**
+ * The `draw` host service: the Typert Remote namespace the settings panel and
+ * the result card consume (`draw/status`, `draw/probe`, `draw/setCredential`,
+ * `draw/unsetCredential`, `draw/regenerate`). Status snapshots are read-only;
+ * credential writes go through the official `ctx.credentials` seam (values
+ * never enter a log or a snapshot); regenerate re-runs the full drawer path
+ * so a panel regeneration is as durable and quota-accounted as a tool call.
+ *
+ * @module dsh-draw/service
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { credentialRef, type CredentialProvider } from '@deepseek-ai/dsh-credentials'
+import type {} from '@deepseek-ai/dsh-attachment'
+import type {} from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-tools'
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { ResolvedConfig } from './config.ts'
+import type { Drawer, DrawSuccess } from './drawer.ts'
+import { engineById } from './config.ts'
+import type { EngineRouter } from './router.ts'
+import { PLUGIN_VERSION } from './version.ts'
+import {
+  imageToWire,
+  probeToWire,
+  statusToView,
+  type CredentialActionResult,
+  type DrawProbeResult,
+  type DrawRegenerateResult,
+  type DrawStatusSnapshot,
+} from './wire.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Image-generation host service (this package). */
+    draw: DrawService
+  }
+}
+
+/** Bindings the service reads at call time (hot-swappable optional seams). */
+export interface DrawServiceOptions {
+  /** Resolved plugin configuration. */
+  config: ResolvedConfig
+  /** The engine router (health state for the status snapshot). */
+  router: EngineRouter
+  /** The generation drawer (regenerate path). */
+  drawer: Drawer
+  /** Per-call credential service; undefined = credential actions degrade. */
+  credentials: CredentialProvider | undefined
+}
+
+/**
+ * The `draw` Typert Remote service.
+ */
+export class DrawService extends TypertRemoteService {
+  /** Per-call bindings (replaced on plugin reload). */
+  options: DrawServiceOptions
+
+  /**
+   * @param ctx - the mounting context.
+   * @param options - runtime bindings.
+   */
+  constructor(ctx: Context, options: DrawServiceOptions) {
+    super(ctx, 'draw')
+    this.options = options
+  }
+
+  /** Resolve one engine's credential view for the status snapshot. */
+  private async credentialView(reference: string) {
+    const credentials = this.options.credentials
+    if (credentials === undefined) return { configured: false, writable: false }
+    try {
+      const info = await credentials.describe(credentialRef(reference))
+      return { configured: info.configured, writable: info.writable, ...(info.source !== undefined ? { source: info.source } : {}) }
+    } catch {
+      return { configured: false, writable: false }
+    }
+  }
+
+  /** Read-only panel snapshot: engine chain, health, credential facts, quota. */
+  async status(): Promise<DrawStatusSnapshot> {
+    const { config, router } = this.options
+    const engines = []
+    for (const engine of config.engines) {
+      const status = router.statusOf(engine.id)
+      const view = statusToView(
+        status ?? { engineId: engine.id, consecutiveFailures: 0, cooldownUntil: null, lastError: null, lastStatus: null },
+        {
+          id: engine.id,
+          model: engine.model,
+          baseUrl: engine.baseUrl,
+          apiKeyRef: engine.apiKeyRef,
+          enabled: engine.enabled,
+          preferred: engine.id === config.defaultEngine,
+        },
+        await this.credentialView(engine.apiKeyRef),
+      )
+      engines.push(view)
+    }
+    return {
+      pluginVersion: PLUGIN_VERSION,
+      engines,
+      quota: { maxGenerationsPerSession: config.maxGenerationsPerSession, maxBytesPerSession: config.maxBytesPerSession },
+      requestTimeoutMs: config.requestTimeoutMs,
+      maxImagesPerCall: config.maxImagesPerCall,
+    }
+  }
+
+  /** Probe one engine's connectivity without mutating routing health. */
+  async probe(engineId: string): Promise<DrawProbeResult> {
+    const engine = engineById(this.options.config, engineId)
+    if (engine === undefined) {
+      return { engineId, reachable: false, httpStatus: null, target: '', note: `unknown engine "${engineId}"`, credentialConfigured: false }
+    }
+    const outcome = await this.options.router.probe(engine, {
+      transport: this.options.drawer.deps.engine.transport,
+      resolveCredential: this.options.drawer.deps.engine.resolveCredential,
+    })
+    return probeToWire(outcome)
+  }
+
+  /** Store one API key under the engine's credential reference (credentials seam). */
+  async setCredential(engineId: string, value: string): Promise<CredentialActionResult> {
+    const engine = engineById(this.options.config, engineId)
+    if (engine === undefined) throw new TypeError(`unknown engine "${engineId}"`)
+    const credentials = this.options.credentials
+    if (credentials === undefined) throw new TypeError('the credential service is not composed on this profile')
+    if (typeof value !== 'string' || value.length === 0) throw new TypeError('credential value must be a non-empty string')
+    await credentials.set(credentialRef(engine.apiKeyRef), value)
+    return { engineId, reference: engine.apiKeyRef, note: `stored under the ${engine.apiKeyRef} credential reference` }
+  }
+
+  /** Remove a stored API key for the engine's credential reference. */
+  async unsetCredential(engineId: string): Promise<CredentialActionResult> {
+    const engine = engineById(this.options.config, engineId)
+    if (engine === undefined) throw new TypeError(`unknown engine "${engineId}"`)
+    const credentials = this.options.credentials
+    if (credentials === undefined) throw new TypeError('the credential service is not composed on this profile')
+    await credentials.unset(credentialRef(engine.apiKeyRef))
+    return { engineId, reference: engine.apiKeyRef, note: `removed from the ${engine.apiKeyRef} credential reference` }
+  }
+
+  /** Re-run a generation from the result card through the full drawer path. */
+  async regenerate(sessionId: string, args: unknown): Promise<DrawRegenerateResult> {
+    const sessions = this.options.drawer.deps.sessions?.()
+    if (sessions === undefined) throw new TypeError('the session store is not composed on this profile')
+    const session = sessions.get(SessionId(sessionId))
+    if (session === undefined) throw new TypeError(`unknown session "${sessionId}"`)
+    const outcome = await this.options.drawer.generate(args, { session, source: 'regenerate' })
+    if (!outcome.ok) throw new TypeError(outcome.message)
+    return projectRegenerate(outcome)
+  }
+}
+
+/** Project a successful draw onto the regenerate wire shape. */
+function projectRegenerate(outcome: DrawSuccess): DrawRegenerateResult {
+  return {
+    engine: outcome.engine,
+    model: outcome.model,
+    size: outcome.size,
+    images: outcome.images.map(imageToWire),
+    quota: outcome.quota,
+    quotaLimits: outcome.limits,
+    fallbackUsed: outcome.fallbackUsed,
+    elapsedMs: outcome.elapsedMs,
+    attempts: outcome.attempts,
+  }
+}