@mengruo/dsh-vision-toolkit 0.0.1

package/lib/types/paste-images.d.ts

@@ -0,0 +1,73 @@
+/** Workspace-local storage for images pasted into the DSH Web composer. */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+/** Exact route used by the browser paste integration. */
+export declare const PASTE_IMAGES_ROUTE = "/_dsh/vision-toolkit/paste-images";
+/**
+ * Exact route the browser paste integration asks before taking a paste over:
+ * `GET ?sessionId=&model=&provider=&modelId=` answers the verdict from the
+ * live Session's model route.
+ */
+export declare const PASTE_POLICY_ROUTE = "/_dsh/vision-toolkit/paste-policy";
+/**
+ * One exact model route the browser should switch the Session to before the
+ * native attachment flow: the image-input variant of the current text-only
+ * model. The variant declares image input, so the paste keeps the composer
+ * thumbnail and the durable session image.
+ */
+export interface PasteSwitchRoute {
+    /** The variant provider route (`vision-toolkit-` + upstream provider id). */
+    provider: string;
+    /** The model id, identical to the upstream text-only model's id. */
+    model: string;
+    /** The variant's selector display name (upstream name + variant suffix). */
+    label: string;
+    /** The upstream reasoning effort, when the selection carries one. */
+    reasoningEffort?: string;
+}
+/** The exact model route the browser read from the live model catalog. */
+export interface PasteSelectionQuery {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** The paste-policy answer for one Session and model route. */
+export interface PasteVerdict {
+    /** Whether the browser should turn the paste into workspace paths instead of attachments. */
+    takeOver: boolean;
+    /** When present, the browser switches to this route first, then lets the paste flow natively. */
+    autoSwitch?: PasteSwitchRoute;
+}
+/**
+ * Hard per-image upload ceiling for pastes. Files between the configured
+ * `maxImageBytes` (default 4 MiB) and this ceiling are stored as-is and
+ * auto-compressed by the runtime on first use; matching the browser-side
+ * safety cap keeps the two bundles in agreement.
+ */
+export declare const MAX_PASTE_IMAGE_BYTES: number;
+/** Convert an untrusted browser label into one portable leaf filename. */
+export declare function safePastedImageName(raw: string, mediaType: string): string;
+/** Reject a resolved path that is not rooted below the expected directory. */
+export declare function ensurePathInside(root: string, target: string): void;
+export interface PasteRoot {
+    writeRoot: string;
+    visibleRoot: string;
+}
+/**
+ * Resolve the managed per-session image directory used by both browser pastes
+ * and native attachment bridging. Keeping both flows under the same workspace
+ * root makes the resulting absolute path valid for the model's visual tools.
+ */
+export declare function sessionPasteRoot(ctx: Context, sessionId: string): Promise<PasteRoot>;
+/** Runtime limit face kept separate for focused backend tests. */
+export interface PasteImageRuntime {
+    maxUploadBytes(): number;
+}
+/** Same-origin, live-Session-bound image upload endpoint. */
+export declare class PastedImageBackend {
+    private readonly ctx;
+    private readonly runtime;
+    constructor(ctx: Context, runtime: PasteImageRuntime);
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+//# sourceMappingURL=paste-images.d.ts.map

package/lib/types/paste-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paste-images.d.ts","sourceRoot":"","sources":["../../src/paste-images.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAI3E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,sCAAsC,CAAA;AAErE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,sCAAsC,CAAA;AAErE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,YAAY;IAC3B,6FAA6F;IAC7F,QAAQ,EAAE,OAAO,CAAA;IACjB,iGAAiG;IACjG,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAC9B;AAID;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAmB,CAAA;AAqErD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAiB1E;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKnE;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAkBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAoB1F;AAuCD,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,cAAc,IAAI,MAAM,CAAA;CACzB;AAED,6DAA6D;AAC7D,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,iBAAiB;IAGvC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CA+BvE"}

package/lib/types/paths.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Path fence shared by every tool: inputs must live in the workspace, the
+ * platform temporary directory, or an explicitly authorized directory;
+ * outputs stay inside the plugin-managed output directory, and a symbolic
+ * link is allowed only when its real target stays inside the fence.
+ * @module dsh-vision-toolkit/paths
+ */
+/** Supported input image extensions (the upstream client's allowlist). */
+export declare const SUPPORTED_IMAGE_EXTENSIONS: readonly [".png", ".jpg", ".jpeg", ".gif", ".webp"];
+/** Resolved path policy for one tool invocation. */
+export interface PathPolicy {
+    /** Real workspace root. */
+    workspace: string;
+    /** Real platform temporary directory, authorized for transient inputs. */
+    tempDir: string;
+    /** Real allowed roots: workspace, platform temp, and configured directories. */
+    allowedDirs: string[];
+    /** Real plugin-managed output directory inside the fence. */
+    outputDir: string;
+}
+/** Whether `child` equals or lies under `parent` on the same path root. */
+export declare function isWithin(parent: string, child: string): boolean;
+/** Current platform temporary directory before realpath canonicalization. */
+export declare function platformTempDirectory(platform?: NodeJS.Platform, environment?: NodeJS.ProcessEnv): string;
+/**
+ * Translate the POSIX-shaped `/tmp/...` paths commonly emitted by models to
+ * the actual Windows temporary directory. Other paths and platforms are left
+ * unchanged, and the normal realpath fence still validates the result.
+ */
+export declare function normalizePlatformTempPath(raw: string, platform?: NodeJS.Platform, tempDirectory?: string): string;
+/**
+ * Build the per-invocation path policy: realpath the workspace, resolve and
+ * realpath the platform temp directory and allowed directories, and create
+ * the output directory inside the fence.
+ * @param workspaceRaw - session workspace (or process cwd fallback).
+ * @param allowedDirs - configured extra allowed roots.
+ * @param outputDirRaw - configured output directory (default `.dsh-vision-toolkit/artifacts`).
+ * @returns the resolved policy.
+ */
+export declare function createPathPolicy(workspaceRaw: string, allowedDirs: readonly string[], outputDirRaw?: string): Promise<PathPolicy>;
+/**
+ * Validate one input image path and return its fence-checked absolute path
+ * and byte size.
+ * @param raw - image path, resolved against the workspace.
+ * @param policy - active path fence.
+ * @returns absolute path and file size.
+ */
+export declare function resolveInputFile(raw: string, policy: PathPolicy): Promise<{
+    path: string;
+    bytes: number;
+}>;
+/**
+ * Validate one authorized regular file against an explicit extension set.
+ * Realpath fencing makes local HTML and future non-image inputs follow the
+ * same symlink-safe policy as images.
+ * @param raw - path resolved against the workspace.
+ * @param policy - active path fence.
+ * @param extensions - accepted lowercase extensions including the leading dot.
+ * @param kind - user-facing noun used in stable errors.
+ * @returns absolute real path and file size.
+ */
+export declare function resolveAuthorizedFile(raw: string, policy: PathPolicy, extensions: readonly string[], kind: string): Promise<{
+    path: string;
+    bytes: number;
+}>;
+/** Validate a local HTML document; URL and data-URI inputs never reach Chrome. */
+export declare function resolveHtmlFile(raw: string, policy: PathPolicy): Promise<{
+    path: string;
+    bytes: number;
+}>;
+/**
+ * Resolve an optional user-supplied output filename inside the plugin output
+ * directory. Absolute paths, `..` segments, and wrong extensions are rejected.
+ * @param raw - output filename (workspace/outputDir-relative).
+ * @param policy - active path fence.
+ * @param defaultName - generated default filename.
+ * @param extensions - allowed extensions for this output kind.
+ * @returns absolute output path (not yet created).
+ */
+export declare function resolveOutputFile(raw: string | undefined, policy: PathPolicy, defaultName: string, extensions: readonly string[]): string;
+/**
+ * Reserve a random, non-user-controlled staging path inside the real output
+ * directory. Upstream writes here so an existing destination symlink can
+ * never redirect the write outside the fence.
+ * @param policy - active path fence.
+ * @param extension - output extension including the leading dot.
+ * @returns absent staging path inside {@link PathPolicy.outputDir}.
+ */
+export declare function createStagedOutput(policy: PathPolicy, extension: string): string;
+/** Resolve one direct child directory of the managed artifact root. */
+export declare function resolveOutputDirectory(raw: string | undefined, policy: PathPolicy, defaultName: string): string;
+/** Create a random staging directory that no upstream command can choose. */
+export declare function createStagedDirectory(policy: PathPolicy): Promise<string>;
+/**
+ * Copy an existing managed run into staging for an explicit resume operation.
+ * A missing destination is a normal first run; non-directory or symlink state
+ * fails closed instead of giving the upstream script an ambiguous workspace.
+ */
+export declare function seedStagedDirectory(finalPath: string, staged: string, policy: PathPolicy): Promise<boolean>;
+/**
+ * Atomically replace one managed artifact directory, restoring the previous
+ * complete run if the final rename fails. The upstream only ever writes the
+ * random staging path.
+ */
+export declare function commitStagedDirectory(staged: string, finalPath: string, policy: PathPolicy): Promise<void>;
+/**
+ * Validate a staged regular file and atomically place it at the resolved final
+ * filename. Replacing an existing symlink replaces the link itself; upstream
+ * never opens the user-selected destination.
+ * @param staged - random staging path returned by {@link createStagedOutput}.
+ * @param finalPath - final path returned by {@link resolveOutputFile}.
+ * @param policy - active path fence.
+ */
+export declare function commitStagedOutput(staged: string, finalPath: string, policy: PathPolicy): Promise<void>;
+/** Reject an output that would overwrite its own input file. */
+export declare function assertDistinctOutput(input: string, output: string): void;
+//# sourceMappingURL=paths.d.ts.map

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

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

package/lib/types/plugin-update.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Profile-scoped self-update support for the Web Settings page.
+ *
+ * Only registry-installed copies are mutable. Local `link:`, `file:`, git,
+ * URL, and workspace installs stay developer-owned and are reported as
+ * unsupported instead of being replaced behind the user's back.
+ * @module dsh-vision-toolkit/plugin-update
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const VISION_TOOLKIT_PACKAGE = "@mengruo/dsh-vision-toolkit";
+export type PluginUpdateUnavailableReason = 'profile-not-found' | 'not-direct-dependency' | 'unsupported-install-source' | 'profile-read-only' | 'pnpm-unavailable' | 'unsupported-platform' | 'restart-unmanaged' | 'restart-address-unavailable';
+export interface PluginUpdateCapability {
+    supported: boolean;
+    checkSupported?: boolean;
+    profile?: string;
+    dependencySpec?: string;
+    reason?: PluginUpdateUnavailableReason;
+}
+export interface PluginUpdateCheck extends PluginUpdateCapability {
+    currentVersion: string;
+    latestVersion?: string;
+    updateAvailable: boolean;
+    checkedAt: string;
+}
+interface PluginUpdateResultBase {
+    fromVersion: string;
+    toVersion: string;
+    profile: string;
+}
+export type PluginUpdateResult = PluginUpdateResultBase & ({
+    restarting: true;
+    manualRestartRequired?: false;
+    retryAfterMs: number;
+} | {
+    restarting: false;
+    manualRestartRequired: true;
+    retryAfterMs?: undefined;
+});
+export declare class PluginUpdateError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export interface RestartRequest {
+    pid: number;
+    execPath: string;
+    args: readonly string[];
+    cwd: string;
+    logPath: string;
+    lockPath: string;
+    lockToken: string;
+    backupDir: string;
+    handoffPath: string;
+    profileDir: string;
+    pnpmPath: string;
+    packageName: string;
+    fromVersion: string;
+    toVersion: string;
+    healthUrl: string;
+    baselineRuntimeReady: boolean;
+    rollbackTimeoutMs: number;
+    processKillGraceMs: number;
+    readinessTimeoutMs: number;
+    oldProcessExitTimeoutMs: number;
+}
+export interface PluginUpdateServiceOptions {
+    packageRoot?: string;
+    profileDir?: string;
+    dshHome?: string;
+    argv?: readonly string[];
+    now?: () => Date;
+    prepareRestart?: (request: RestartRequest) => void | Promise<void>;
+    terminateCurrent?: () => void;
+    schedule?: (callback: () => void, delayMs: number) => void;
+    allowDetachedRestart?: boolean;
+    healthUrl?: string;
+    runtimeReady?: () => boolean;
+    platform?: NodeJS.Platform;
+}
+/** @internal Restart helper source exported for lifecycle integration tests. */
+export declare const PLUGIN_RESTART_HELPER_SOURCE: string;
+/** Compare two strict SemVer versions. */
+export declare function compareVersions(left: string, right: string): number;
+/** Profile-aware updater used by the same-origin Settings backend. */
+export declare class VisionToolkitPluginUpdateService {
+    private readonly ctx;
+    private readonly currentVersion;
+    private readonly packageRoot;
+    private readonly profileDir;
+    private readonly dshHome;
+    private readonly argv;
+    private readonly now;
+    private readonly prepareRestart;
+    private readonly terminateCurrent;
+    private readonly schedule;
+    private readonly allowDetachedRestart;
+    private healthUrl;
+    private readonly runtimeReady;
+    private readonly platform;
+    private updating;
+    constructor(ctx: Pick<Context, 'subprocess'>, currentVersion: string, options?: PluginUpdateServiceOptions);
+    /** Bind readiness checks to the active WebServer and reject ports that cannot be reproduced on restart. */
+    configureWebServer(host: string, port: number): void;
+    private inspectProfile;
+    private locateProfile;
+    private profile;
+    private evaluate;
+    private checkContext;
+    /** Report whether the current installation can be safely replaced in place. */
+    capability(): Promise<PluginUpdateCapability>;
+    private runPnpm;
+    private rollbackInstall;
+    private acquireLock;
+    /** Query the configured npm registry without mutating the profile. */
+    check(): Promise<PluginUpdateCheck>;
+    /** Install the currently published version, then restart when this process can do so safely. */
+    installAndRestart(expectedVersion: string): Promise<PluginUpdateResult>;
+}
+export {};
+//# sourceMappingURL=plugin-update.d.ts.map

package/lib/types/plugin-update.d.ts.map

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

package/lib/types/runtime-install.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Reproducible upstream runtime preparation. Managed mode uses the packaged,
+ * hash-verified agent-vision-toolkit snapshot plus an atomic isolated Python
+ * environment; external mode accepts only the pinned clean Git commit or an
+ * exact exported copy of the packaged snapshot.
+ * @module dsh-vision-toolkit/runtime-install
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ResolvedVisionToolkitConfig } from './config.ts';
+/** One executable plus fixed prefix arguments (for example Windows `py -3`). */
+export interface RuntimeCommand {
+    program: string;
+    prefix: string[];
+    display: string;
+}
+/** Prepared source and interpreter facts consumed by the upstream adapter. */
+export interface PreparedUpstreamRuntime {
+    source: 'managed' | 'external';
+    root: string;
+    python: RuntimeCommand;
+    cleanHome: string;
+    pythonVersion: string;
+    dependencies: Record<string, string>;
+}
+interface UpstreamManifest {
+    schemaVersion: number;
+    repository: string;
+    version: string;
+    commit: string;
+    contentSha256: string;
+    files: Array<{
+        path: string;
+        bytes: number;
+        sha256: string;
+    }>;
+}
+/** Absolute root of the packaged upstream snapshot. */
+export declare function bundledUpstreamRoot(): string;
+/** Convert one command into a user-facing executable string. */
+export declare function displayCommand(command: RuntimeCommand): string;
+export declare function isolatedPythonEnvironment(home: string): NodeJS.ProcessEnv;
+/** Verify every packaged upstream file against the committed content manifest. */
+export declare function verifyBundledUpstream(): Promise<UpstreamManifest>;
+interface PythonBootstrapArtifact {
+    url: string;
+    sha256: string;
+    size: number;
+}
+interface PythonBootstrapManifest {
+    schemaVersion: 1;
+    pythonVersion: string;
+    buildTag: string;
+    /** Optional domestic mirror base that replaces the GitHub download prefix. */
+    mirrorBaseUrl?: string;
+    artifacts: Record<string, PythonBootstrapArtifact>;
+}
+/** Map Node platform/arch to the pinned artifact name, including musl Linux. */
+export declare function pythonBootstrapTarget(platform: string, arch: string, musl: boolean): string;
+interface DownloadResponse {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: NodeJS.ReadableStream;
+    close: () => Promise<void>;
+}
+type DownloadRequest = (url: string, signal: AbortSignal) => Promise<DownloadResponse>;
+export declare function acquireBundledPython(ctx: Context, stateRoot: string, cwd: string, manifestOverride?: PythonBootstrapManifest, requestImpl?: DownloadRequest): Promise<{
+    command: RuntimeCommand;
+    version: string;
+}>;
+export declare function resolveBootstrapPython(ctx: Context, configured: string | undefined, cwd: string, manifestOverride?: PythonBootstrapManifest, requestImpl?: DownloadRequest): Promise<{
+    command: RuntimeCommand;
+    version: string;
+    major: number;
+    minor: number;
+}>;
+/** Persistent per-DSH-home cache root shared by runtime and Web support files. */
+export declare function visionToolkitStateRoot(): string;
+/**
+ * Rewrite a staged venv's `pyvenv.cfg` `home`/`executable` to point at a given
+ * base directory (the app execution alias directory for the Microsoft Store
+ * Python). Pure helper so the transformation is testable cross-platform.
+ */
+export declare function rewriteVenvConfig(cfg: string, homeDir: string): string;
+/**
+ * Build the Microsoft Store probe environment while preserving Python-variable
+ * tombstones; only the user-directory variables must fall back to the host.
+ */
+export declare function storePythonProbeEnvironment(installEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Prepare the configured pinned runtime without making any vision API call. */
+export declare function prepareUpstreamRuntime(ctx: Context, config: ResolvedVisionToolkitConfig): Promise<PreparedUpstreamRuntime>;
+export {};
+//# sourceMappingURL=runtime-install.d.ts.map

package/lib/types/runtime-install.d.ts.map

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

package/lib/types/runtime-manager.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Atomic live configuration owner for the plugin's internal runtime. A new
+ * upstream adapter is fully prepared before it replaces the currently serving
+ * runtime, so failed Settings edits never interrupt in-flight or later calls.
+ * @module dsh-vision-toolkit/runtime-manager
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ResolvedVisionToolkitConfig, type VisionToolkitConfig } from './config.ts';
+import { VisionToolkitRuntime } from './runtime.ts';
+import { type UpstreamVersionInfo } from './upstream.ts';
+/** One completely prepared configuration generation. */
+export interface PreparedRuntimeGeneration {
+    config: ResolvedVisionToolkitConfig;
+    fingerprint: string;
+    runtime: VisionToolkitRuntime;
+}
+/** Public, secret-free status used by the Settings page. */
+export interface RuntimeManagerStatus {
+    ready: boolean;
+    generation: number;
+    activeConfig?: ResolvedVisionToolkitConfig;
+    upstream?: UpstreamVersionInfo;
+    lastError?: string;
+}
+/** Test seam for preparing one generation. */
+export type RuntimeGenerationFactory = (ctx: Context, config: ResolvedVisionToolkitConfig) => Promise<VisionToolkitRuntime>;
+/** Internal runtime source with prepare-before-swap semantics. */
+export declare class VisionToolkitRuntimeManager {
+    private readonly ctx;
+    private readonly factory;
+    private active;
+    private generation;
+    private reconfigureTicket;
+    private lastError;
+    constructor(ctx: Context, factory?: RuntimeGenerationFactory);
+    /** The currently serving runtime; unavailable until one generation prepares. */
+    current(): VisionToolkitRuntime;
+    /** Whether at least one generation is available. */
+    get ready(): boolean;
+    /** Resolve and fully prepare a candidate without changing the active runtime. */
+    prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration>;
+    /**
+     * Publish one already-prepared generation atomically.
+     * @param candidate - generation returned by {@link prepareCandidate}.
+     */
+    activateCandidate(candidate: PreparedRuntimeGeneration): void;
+    /** Prepare and publish the initial or explicitly validated generation. */
+    initialize(raw: VisionToolkitConfig): Promise<void>;
+    /**
+     * Apply an externally committed Settings generation. Concurrent edits are
+     * last-write-wins; a slower obsolete prepare can never overwrite a newer one.
+     * @returns whether this call published a new active generation.
+     */
+    reconfigure(raw: VisionToolkitConfig): Promise<boolean>;
+    /** Record a failed preflight while retaining the previous generation. */
+    recordFailure(error: unknown): void;
+    /** Secret-free status snapshot for health/configuration surfaces. */
+    status(): RuntimeManagerStatus;
+}
+//# sourceMappingURL=runtime-manager.d.ts.map

package/lib/types/runtime-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-manager.d.ts","sourceRoot":"","sources":["../../src/runtime-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAiB,KAAK,2BAA2B,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACvG,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAEzE,wDAAwD;AACxD,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,2BAA2B,CAAA;IACnC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,oBAAoB,CAAA;CAC9B;AAED,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,2BAA2B,CAAA;IAC1C,QAAQ,CAAC,EAAE,mBAAmB,CAAA;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,8CAA8C;AAC9C,MAAM,MAAM,wBAAwB,GAAG,CACrC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,2BAA2B,KAChC,OAAO,CAAC,oBAAoB,CAAC,CAAA;AAqBlC,kEAAkE;AAClE,qBAAa,2BAA2B;IAOpC,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,SAAS,CAAoB;gBAGlB,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,wBAAyC;IAGrE,gFAAgF;IAChF,OAAO,IAAI,oBAAoB;IAK/B,oDAAoD;IACpD,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,iFAAiF;IAC3E,gBAAgB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAUpF;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,yBAAyB,GAAG,IAAI;IAmB7D,0EAA0E;IACpE,UAAU,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IASzD;;;;OAIG;IACG,WAAW,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IA0B7D,yEAAyE;IACzE,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAInC,qEAAqE;IACrE,MAAM,IAAI,oBAAoB;CAgB/B"}