@mengruo/dsh-vision-toolkit 0.0.1

package/lib/types/upstream.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Structured adapter over the pinned agent-vision-toolkit snapshot. Every
+ * invocation is an argv vector through DSH Subprocess, runs from a clean home
+ * so upstream env files cannot override DSH configuration, and converts the
+ * pinned CLI contracts into stable data.
+ * @module dsh-vision-toolkit/upstream
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SubprocessOutcome } from '@deepseek-ai/dsh-subprocess';
+import type { ResolvedVisionToolkitConfig } from './config.ts';
+import { VisionToolkitError } from './errors.ts';
+import { type PreparedUpstreamRuntime } from './runtime-install.ts';
+/** One pinned upstream CLI/script exposed by the runtime. */
+export type UpstreamTool = 'glance' | 'ground' | 'detect' | 'crop' | 'trace' | 'pixel_diff' | 'long_screenshot_ocr' | 'extract_foreground' | 'dominant_colors' | 'html_screenshot';
+/** Vision configuration forwarded only to upstream commands that call the API. */
+export interface UpstreamEnvironment {
+    VISION_API_KEY: string;
+    VISION_BASE_URL: string;
+    VISION_MODEL: string;
+    VISION_API_PROTOCOL: 'chat_completions' | 'anthropic';
+    VISION_ANTHROPIC_THINKING: 'omit' | 'disabled' | 'adaptive';
+    VISION_SSL_VERIFY?: string;
+    VISION_USER_AGENT: string;
+    LANG: 'zh' | 'en';
+}
+/** Pinned upstream identity plus prepared runtime facts. */
+export interface UpstreamVersionInfo {
+    repository: string;
+    version: string;
+    commit: string;
+    path: string;
+    source: 'managed' | 'external';
+    python: string;
+    pythonVersion: string;
+    dependencies: Record<string, string>;
+    runtimeHome: string;
+}
+/** Settled upstream process facts plus bounded output. */
+export interface UpstreamRunResult {
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+    outcome: SubprocessOutcome;
+}
+/** Pixel box in original-image coordinates. */
+export interface PixelBox {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** One ground/detect match line converted to structure. */
+export interface LocatedElement {
+    label?: string;
+    box: PixelBox;
+}
+/** Parsed crop CLI result. */
+export interface CropOutput {
+    outputPath: string;
+    width: number;
+    height: number;
+    clamped: boolean;
+    note?: string;
+}
+/** Parsed trace CLI result from the pinned vtracer implementation. */
+export interface TraceOutput {
+    outputPath: string;
+    bytes: number;
+    pathCount: number;
+    tracedScale: number;
+}
+/** Parsed local pixel-diff report. */
+export interface PixelDiffOutput {
+    scaled: boolean;
+    rebuiltOriginalSize?: {
+        width: number;
+        height: number;
+    };
+    scaledToSize?: {
+        width: number;
+        height: number;
+    };
+    overallDifferencePct: number;
+    heatmapPath: string;
+    worstRegions: Array<{
+        index: number;
+        differencePct: number;
+        box: PixelBox;
+    }>;
+}
+/** Parsed transparent foreground extraction report. */
+export interface ExtractForegroundOutput {
+    box: PixelBox;
+    foregroundPixels: number;
+    keptComponents: number;
+    totalComponents: number;
+    largestComponentPct: number;
+    outputPath: string;
+    width: number;
+    height: number;
+    autoSummary?: string;
+}
+/** One significant palette cluster from `dominant_colors.py`. */
+export interface DominantColorCluster {
+    color: string;
+    sharePct: number;
+}
+/** One candidate-scoring row from `dominant_colors.py`. */
+export interface DominantColorCandidate {
+    color: string;
+    sharePct: number;
+    meanDistance: number;
+    weightedScorePct: number;
+    winner: boolean;
+}
+/** Structured dominant-colour result in palette or candidate mode. */
+export type DominantColorsOutput = {
+    mode: 'palette';
+    region: PixelBox;
+    width: number;
+    height: number;
+    requestedTop: number;
+    clusterCount: number;
+    mergeTolerance: number;
+    colors: DominantColorCluster[];
+} | {
+    mode: 'candidates';
+    region: PixelBox;
+    width: number;
+    height: number;
+    sampledPixels: number;
+    candidates: DominantColorCandidate[];
+    winner: string;
+    matchedWithinTolerance: boolean;
+    closestCandidate?: string;
+    note?: string;
+};
+/** Parsed local HTML screenshot result. */
+export interface HtmlScreenshotOutput {
+    outputPath: string;
+    width: number;
+    height: number;
+    pageHeight?: number;
+}
+/** Result of one automatic Pillow compression pass for an oversized image. */
+export interface CompressedImageInfo {
+    bytes: number;
+    width: number;
+    height: number;
+    format: 'png' | 'jpeg' | 'gif' | 'webp';
+    mode: string;
+    lossy: boolean;
+    resized: boolean;
+    candidate: string;
+    /** True when the source image had multiple animation frames. */
+    sourceAnimated: boolean;
+}
+/** Parse one numbered upstream location line (`N. position label x1: ..., ...`). */
+export declare function parseLocationLine(line: string): LocatedElement | undefined;
+/** Parse ground/detect stdout; non-empty unknown lines are an output contract failure. */
+export declare function parseLocationOutput(stdout: string): LocatedElement[];
+/** Parse the crop CLI's `wrote <path> (WxH)` line and clamp note. */
+export declare function parseCropOutput(stdout: string, stderr: string): CropOutput;
+/** Parse the pinned trace CLI's written-file summary. */
+export declare function parseTraceOutput(stdout: string): TraceOutput;
+/** Parse the complete `pixel_diff.py` stdout contract. */
+export declare function parsePixelDiffOutput(stdout: string): PixelDiffOutput;
+/** Parse the complete `extract_fg.py` stdout contract. */
+export declare function parseExtractForegroundOutput(stdout: string): ExtractForegroundOutput;
+/** Parse palette and candidate modes from `dominant_colors.py`. */
+export declare function parseDominantColorsOutput(stdout: string): DominantColorsOutput;
+/** Parse the local Chrome screenshot summary. */
+export declare function parseHtmlScreenshotOutput(stdout: string): HtmlScreenshotOutput;
+/** Find the first candidate with the five pinned core CLI entrypoints. */
+export declare function findCheckout(candidates: readonly string[]): Promise<string>;
+/** Adapter over one prepared pinned upstream runtime. */
+export declare class UpstreamAdapter {
+    private readonly ctx;
+    private readonly config;
+    private prepared;
+    constructor(ctx: Context, config: ResolvedVisionToolkitConfig, prepared?: PreparedUpstreamRuntime);
+    /** Upstream identity reported to tools and logs. */
+    get versionInfo(): UpstreamVersionInfo;
+    private requirePrepared;
+    /** Verify and prepare the configured source plus Python dependencies. */
+    prepare(): Promise<void>;
+    /** Run one upstream CLI without a shell. */
+    run(tool: UpstreamTool, args: readonly string[], options: {
+        signal: AbortSignal;
+        env?: UpstreamEnvironment;
+    }): Promise<UpstreamRunResult>;
+    /** Read image dimensions through the prepared Pillow dependency. */
+    probeImageSize(imagePath: string, options: {
+        signal: AbortSignal;
+    }): Promise<{
+        width: number;
+        height: number;
+        format: string;
+        mode: string;
+    }>;
+    /**
+     * Auto-compress one oversized image under the configured byte and pixel
+     * budgets. The Pillow helper prefers lossless re-encodes, then quality
+     * reduction, and only downscales when neither can reach the budget.
+     */
+    compressImage(sourcePath: string, destPath: string, maxBytes: number, maxPixels: number, options: {
+        signal: AbortSignal;
+    }): Promise<CompressedImageInfo>;
+    private runPythonCode;
+    /** Draw validated pixel boxes and labels into a PNG preview with Pillow. */
+    renderAnnotatedPreview(imagePath: string, outputPath: string, elements: readonly LocatedElement[], options: {
+        signal: AbortSignal;
+    }): Promise<void>;
+    /** Locate the same optional Chrome-family browser the pinned HTML script uses. */
+    findChrome(options: {
+        signal: AbortSignal;
+    }): Promise<string | undefined>;
+    private collect;
+    /** Report the pinned snapshot identity. */
+    readCheckoutVersion(): Promise<string>;
+    /** Whether the prepared snapshot carries one optional script path. */
+    hasScript(name: string): Promise<boolean>;
+    /** Read one prepared upstream text file for diagnostics or compatibility tests. */
+    readText(relativePath: readonly string[]): Promise<string>;
+    /** Turn a failed run into a model-safe classified error. */
+    classifyFailure(tool: UpstreamTool, result: UpstreamRunResult, options: {
+        timedOut: boolean;
+        cancelled: boolean;
+        secrets?: readonly string[];
+    }): VisionToolkitError;
+}
+//# sourceMappingURL=upstream.d.ts.map

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

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

package/lib/types/version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Plugin and pinned upstream version facts. The upstream snapshot is fixed at
+ * build time and recorded in package.json's `dsh.visionToolkit` metadata so
+ * the runtime, tool results, and docs all report the same source commit.
+ * @module dsh-vision-toolkit/version
+ */
+/** Plugin package version. */
+export declare const PLUGIN_VERSION: string;
+/** Pinned upstream repository URL. */
+export declare const UPSTREAM_REPOSITORY: string;
+/** Pinned upstream release tag. */
+export declare const UPSTREAM_VERSION: string;
+/** Pinned upstream source commit. */
+export declare const UPSTREAM_COMMIT: string;
+//# sourceMappingURL=version.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,8BAA8B;AAC9B,eAAO,MAAM,cAAc,QAAmB,CAAA;AAE9C,sCAAsC;AACtC,eAAO,MAAM,mBAAmB,QAAyF,CAAA;AAEzH,mCAAmC;AACnC,eAAO,MAAM,gBAAgB,QAA8D,CAAA;AAE3F,qCAAqC;AACrC,eAAO,MAAM,eAAe,QAA8E,CAAA"}

package/lib/types/web-request.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage } from 'node:http';
+/**
+ * Accept a request only from the DSH Web application's origin. Method-agnostic:
+ * the same fence guards state-changing POSTs and policy GETs.
+ * @param req - the incoming request whose headers carry the origin evidence.
+ * @returns whether the request may be answered.
+ */
+export declare function sameOriginRequest(req: IncomingMessage): boolean;
+/** Accept state-changing requests only from the DSH Web application's origin. */
+export declare function sameOriginPost(req: IncomingMessage): boolean;
+//# sourceMappingURL=web-request.d.ts.map

package/lib/types/web-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-request.d.ts","sourceRoot":"","sources":["../../src/web-request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAa/D;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAE5D"}

package/lib/types/web.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Optional Web-profile routes: signed Artifact delivery plus a same-origin
+ * Settings/health endpoint. The browser never receives credential values and
+ * connection tests run only after an explicit POST action.
+ * @module dsh-vision-toolkit/web
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import { ArtifactAccessController } from './artifact-access.ts';
+import { PastedImageBackend, type PasteSelectionQuery, type PasteVerdict } from './paste-images.ts';
+import { type VisionToolkitConfig } from './config.ts';
+import { type PluginUpdateCapability, type PluginUpdateCheck, type PluginUpdateResult } from './plugin-update.ts';
+import { VisionToolkitRuntimeManager, type PreparedRuntimeGeneration, type RuntimeManagerStatus } from './runtime-manager.ts';
+/** Exact route used by the browser Settings page. */
+export declare const SETTINGS_ROUTE = "/_dsh/vision-toolkit/settings";
+/** Same-origin route used by the browser client to read display-mode flags. */
+export declare const DISPLAY_CONFIG_ROUTE = "/_dsh/vision-toolkit/display-config";
+/** Public Settings snapshot; credential values are deliberately impossible here. */
+export interface VisionToolkitSettingsSnapshot {
+    schemaVersion: 1;
+    writable: boolean;
+    settings: {
+        value: VisionToolkitConfig;
+        user?: unknown;
+        base?: unknown;
+        revision: number;
+        applies: 'live';
+    };
+    credential: {
+        ref: string;
+        configured: boolean;
+        source?: string;
+        writable: boolean;
+    };
+    runtime: RuntimeManagerStatus;
+    release: {
+        pluginVersion: string;
+        upstreamRepository: string;
+        upstreamVersion: string;
+        upstreamCommit: string;
+        update: PluginUpdateCapability;
+    };
+    artifactRouteAvailable: boolean;
+}
+/** Minimal runtime-manager face used by the Web route and its tests. */
+export interface WebRuntimeManager {
+    readonly ready: boolean;
+    current(): ReturnType<VisionToolkitRuntimeManager['current']>;
+    prepareCandidate(raw: VisionToolkitConfig): Promise<PreparedRuntimeGeneration>;
+    activateCandidate(candidate: PreparedRuntimeGeneration): void;
+    recordFailure(error: unknown): void;
+    status(): RuntimeManagerStatus;
+}
+/** Minimal self-update face used by the Web route and its tests. */
+export interface WebPluginUpdater {
+    configureWebServer?(host: string, port: number): void;
+    capability(): Promise<PluginUpdateCapability>;
+    check(): Promise<PluginUpdateCheck>;
+    installAndRestart(expectedVersion: string): Promise<PluginUpdateResult>;
+}
+/** Callback invoked when a Settings save makes the first runtime available. */
+export type RuntimeActivated = () => void;
+/** Same-origin Settings and health handler. */
+export declare class VisionToolkitWebBackend {
+    private readonly ctx;
+    private readonly manager;
+    private readonly artifacts;
+    private readonly onRuntimeActivated;
+    private readonly updater;
+    constructor(ctx: Context, manager: WebRuntimeManager, artifacts: ArtifactAccessController, onRuntimeActivated: RuntimeActivated, updater?: WebPluginUpdater);
+    /** Supply the active listener address before the Settings route becomes reachable. */
+    configureWebServer(host: string, port: number): void;
+    private credential;
+    /** Build the current settings/runtime/credential snapshot without secrets. */
+    snapshot(): Promise<VisionToolkitSettingsSnapshot>;
+    private save;
+    private saveCredential;
+    private health;
+    /** Handle the exact Settings route. */
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+/**
+ * Same-origin policy handler for the paste route: whether the browser should
+ * take a paste over into workspace paths, or let it flow natively after an
+ * optional automatic switch to the image-input variant. The optional `model`
+ * query carries the model-selector label the client currently shows; the
+ * optional `provider`/`modelId`/`reasoningEffort` queries carry the exact
+ * route the client read from the live model catalog, which the resolver
+ * prefers (a label alone cannot pick a provider). Unresolvable routes answer
+ * native — the safe default.
+ * @param resolve - resolves one live Session's paste verdict.
+ * @returns the HTTP handler.
+ */
+export declare function createPastePolicyHandler(resolve: (sessionId: string, selection?: PasteSelectionQuery, modelLabel?: string) => Promise<PasteVerdict>): (req: IncomingMessage, res: ServerResponse) => void;
+/**
+ * Same-origin display-config handler: exposes whether transparent routing is
+ * active. The paste integration uses it to choose its notice text; the model
+ * selector hides upstream twins synchronously from DOM display names and does
+ * not depend on this route.
+ * @param getDisplayConfig - resolves the current display-mode flags.
+ * @returns the HTTP handler.
+ */
+export declare function createDisplayConfigHandler(getDisplayConfig: () => {
+    hidden: boolean;
+}): (req: IncomingMessage, res: ServerResponse) => void;
+/**
+ * Attach optional Web routes whenever a webServer service is present.
+ * @param ctx - plugin context owning route effects.
+ * @param backend - Settings handler.
+ * @param artifacts - signed Artifact handler.
+ * @param pastedImages - pasted-image workspace handler.
+ * @param pastePolicy - paste-policy verdict resolver (sessionId, selection, modelLabel).
+ * @param getDisplayConfig - resolves display-mode flags for the browser client.
+ */
+export declare function installVisionToolkitWeb(ctx: Context, backend: VisionToolkitWebBackend, artifacts: ArtifactAccessController, pastedImages: PastedImageBackend, pastePolicy: (sessionId: string, selection?: PasteSelectionQuery, modelLabel?: string) => Promise<PasteVerdict>, getDisplayConfig: () => {
+    hidden: boolean;
+}): void;
+//# sourceMappingURL=web.d.ts.map

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

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