dsh-draw 0.1.0

package/lib/types/router.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 { type EngineDeps, type ProducedImage } from './engine.ts';
+import { 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;
+}
+/** 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 declare class EngineRouter {
+    private readonly config;
+    private readonly health;
+    private readonly now;
+    /**
+     * @param config - resolved plugin configuration (engine order and bounds).
+     * @param options - failure threshold, cooldown, and clock.
+     */
+    constructor(config: ResolvedConfig, options: RouterOptions);
+    /**
+     * 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.
+     */
+    generate(request: StandardImageRequest, deps: EngineDeps, signal?: AbortSignal): Promise<RouterResult>;
+    /** One engine's current health snapshot. */
+    statusOf(engineId: string): EngineStatus | undefined;
+    /** Health snapshots for every configured engine in chain order. */
+    statuses(): readonly EngineStatus[];
+    /**
+     * 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.
+     */
+    probe(engine: ResolvedEngineConfig, deps: EngineDeps): Promise<ProbeOutcome>;
+    /** Chain order: an explicit engine override first, then config order minus the override. */
+    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. */
+    private recordFailure;
+}
+//# sourceMappingURL=router.d.ts.map

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

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

package/lib/types/router.js

@@ -0,0 +1,207 @@
+/**
+ * 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 { callEngine, EngineCallError } from './engine.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
+ * tool is not concurrency-safe, so generations serialize).
+ */
+export class EngineRouter {
+    config;
+    health = new Map();
+    now;
+    /**
+     * @param config - resolved plugin configuration (engine order and bounds).
+     * @param options - failure threshold, cooldown, and clock.
+     */
+    constructor(config, options) {
+        this.config = config;
+        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, deps, signal) {
+        const ordered = this.chainOrder(request.engine);
+        const attempts = [];
+        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) {
+        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() {
+        return this.config.engines
+            .map(engine => this.statusOf(engine.id))
+            .filter((status) => 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, deps) {
+        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. */
+    chainOrder(override) {
+        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. */
+    skipReason(engine) {
+        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). */
+    translate(engine, request) {
+        return translateRequest(engine, request);
+    }
+    /** Record a success: reset consecutive failures and cooldown. */
+    recordSuccess(engineId) {
+        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. */
+    recordFailure(engineId, error) {
+        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/lib/types/sanitize.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare const REDACTED = "***";
+/**
+ * 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 declare function sanitizeUrl(url: string): string;
+/**
+ * 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 declare function sanitizeText(text: string): string;
+/**
+ * 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 declare function sanitizeError(error: unknown): string;
+//# sourceMappingURL=sanitize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,uDAAuD;AACvD,eAAO,MAAM,QAAQ,QAAQ,CAAA;AAmC7B;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgB/C;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAajD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQpD"}

package/lib/types/sanitize.js

@@ -0,0 +1,103 @@
+/**
+ * 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) {
+    let parsed;
+    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) {
+    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) {
+    let text;
+    try {
+        text = typeof error === 'string' ? error : String(error);
+    }
+    catch {
+        text = '<unrenderable error>';
+    }
+    return sanitizeText(text);
+}

package/lib/types/service.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 { type CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { ResolvedConfig } from './config.ts';
+import type { Drawer } from './drawer.ts';
+import type { EngineRouter } from './router.ts';
+import { 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 declare 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);
+    /** Resolve one engine's credential view for the status snapshot. */
+    private credentialView;
+    /** Read-only panel snapshot: engine chain, health, credential facts, quota. */
+    status(): Promise<DrawStatusSnapshot>;
+    /** Probe one engine's connectivity without mutating routing health. */
+    probe(engineId: string): Promise<DrawProbeResult>;
+    /** Store one API key under the engine's credential reference (credentials seam). */
+    setCredential(engineId: string, value: string): Promise<CredentialActionResult>;
+    /** Remove a stored API key for the engine's credential reference. */
+    unsetCredential(engineId: string): Promise<CredentialActionResult>;
+    /** Re-run a generation from the result card through the full drawer path. */
+    regenerate(sessionId: string, args: unknown): Promise<DrawRegenerateResult>;
+}
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAA;AAIrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,aAAa,CAAA;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,WAAW,CAAA;AAElB,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,oDAAoD;QACpD,IAAI,EAAE,WAAW,CAAA;KAClB;CACF;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,MAAM,EAAE,cAAc,CAAA;IACtB,gEAAgE;IAChE,MAAM,EAAE,YAAY,CAAA;IACpB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,WAAW,EAAE,kBAAkB,GAAG,SAAS,CAAA;CAC5C;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,mBAAmB;IAClD,qDAAqD;IACrD,OAAO,EAAE,kBAAkB,CAAA;IAE3B;;;OAGG;IACH,YAAY,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAGpD;IAED,oEAAoE;YACtD,cAAc;IAW5B,+EAA+E;IACzE,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC,CA0B1C;IAED,uEAAuE;IACjE,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAUtD;IAED,oFAAoF;IAC9E,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAQpF;IAED,qEAAqE;IAC/D,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAOvE;IAED,6EAA6E;IACvE,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAQhF;CACF"}