@anionex/dsh-vision-toolkit 0.1.5

package/lib/types/artifact-access.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Capability-gated HTTP delivery for managed Vision Toolkit artifacts.
+ * Signed tokens are durable across process restarts, expose no secret, and
+ * are accepted only for the exact artifact facts projected into a tool result.
+ * @module dsh-vision-toolkit/artifact-access
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { JsonValue } from '@deepseek-ai/dsh-tools';
+import type { ArtifactDescriptor, ArtifactKind } from './artifacts.ts';
+/** Prefix owned by the plugin's artifact capability route. */
+export declare const ARTIFACT_ROUTE_PREFIX = "/_dsh/vision-toolkit/artifacts";
+/** Presentation metadata key reserved by the browser half of this package. */
+export declare const PRESENTATION_META_KEY = "$dshVisionToolkit";
+interface ArtifactTokenPayload {
+    v: 1;
+    path: string;
+    filename: string;
+    mimeType: string;
+    kind: ArtifactKind;
+    bytes: number;
+}
+/** Browser-only access grant paired to one model-visible artifact descriptor. */
+export interface ArtifactAccessGrant {
+    path: string;
+    previewUrl: string;
+    downloadUrl: string;
+}
+/**
+ * Load or atomically create the per-DSH-home signing key.
+ * @param root - state root override used by tests; defaults to the plugin cache.
+ * @returns the 32-byte signing key.
+ */
+export declare function prepareArtifactAccessKey(root?: string): Promise<Buffer>;
+/** Signed-capability encoder and safe Artifact route handler. */
+export declare class ArtifactAccessController {
+    private readonly key;
+    private routeCount;
+    constructor(key: Buffer);
+    /** Whether at least one HTTP carrier currently owns the route. */
+    get routeAvailable(): boolean;
+    /** Mark one route attachment; the returned disposer removes that attachment. */
+    attachRoute(): () => void;
+    /**
+     * Purely enrich a canonical tool-result value with browser access grants.
+     * @param value - schema-validated tool result.
+     * @returns the unchanged value when no route/artifact exists, otherwise a detached metadata envelope.
+     */
+    presentationMeta(value: JsonValue): JsonValue;
+    /** Mint a deterministic, tamper-evident capability for one descriptor. */
+    sign(artifact: ArtifactDescriptor): string;
+    /** Verify and decode one capability without touching the filesystem. */
+    verify(token: string): ArtifactTokenPayload | undefined;
+    /**
+     * Serve one GET/HEAD capability request with MIME, CSP, and symlink checks.
+     * @param req - Node HTTP request matched under {@link ARTIFACT_ROUTE_PREFIX}.
+     * @param res - response owned by this handler.
+     */
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+export {};
+//# sourceMappingURL=artifact-access.d.ts.map

package/lib/types/artifact-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-access.d.ts","sourceRoot":"","sources":["../../src/artifact-access.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAItE,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,mCAAmC,CAAA;AAErE,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,sBAAsB,CAAA;AAExD,UAAU,oBAAoB;IAC5B,CAAC,EAAE,CAAC,CAAA;IACJ,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,YAAY,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;CACpB;AAkGD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,SAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB/F;AAmFD,iEAAiE;AACjE,qBAAa,wBAAwB;IAGvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,UAAU,CAAI;gBAEO,GAAG,EAAE,MAAM;IAIxC,kEAAkE;IAClE,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,gFAAgF;IAChF,WAAW,IAAI,MAAM,IAAI;IAUzB;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS;IAc7C,0EAA0E;IAC1E,IAAI,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM;IAa1C,wEAAwE;IACxE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAkBvD;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CA+DvE"}

package/lib/types/artifacts.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Stable file-delivery descriptors owned by the plugin. DSH Core currently
+ * has no reusable Artifact service, so every file-producing tool returns this
+ * lossless contract and keeps the file inside the plugin-managed artifact
+ * directory for Web, Headless, and later tool calls alike.
+ * @module dsh-vision-toolkit/artifacts
+ */
+import { type PathPolicy } from './paths.ts';
+/** Artifact payload family used by clients to select a safe renderer. */
+export type ArtifactKind = 'image' | 'svg' | 'markdown' | 'json';
+/** Intended default client action for one artifact. */
+export type ArtifactPreviewIntent = 'image' | 'svg' | 'text' | 'download';
+/** Stable descriptor returned by every file-producing Vision Toolkit tool. */
+export interface ArtifactDescriptor {
+    path: string;
+    filename: string;
+    mimeType: string;
+    kind: ArtifactKind;
+    description: string;
+    sourceTool: string;
+    previewIntent: ArtifactPreviewIntent;
+    bytes: number;
+}
+/** Metadata needed to describe an already committed managed artifact. */
+export interface ArtifactDescription {
+    mimeType: string;
+    kind: ArtifactKind;
+    description: string;
+    sourceTool: string;
+    previewIntent: ArtifactPreviewIntent;
+}
+/**
+ * Validate and describe one committed regular file under the active artifact
+ * root. Symbolic links are rejected even when their targets remain in-bounds,
+ * so a later preview/download can never be redirected after delivery.
+ * @param path - final managed artifact path.
+ * @param policy - active workspace path policy.
+ * @param description - stable type and presentation facts.
+ * @returns a complete descriptor with the committed byte size.
+ */
+export declare function describeArtifact(path: string, policy: PathPolicy, description: ArtifactDescription): Promise<ArtifactDescriptor>;
+//# sourceMappingURL=artifacts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAEtD,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,CAAA;AAEhE,uDAAuD;AACvD,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAA;AAEzE,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,YAAY,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,qBAAqB,CAAA;IACpC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,YAAY,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,qBAAqB,CAAA;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,mBAAmB,GAC/B,OAAO,CAAC,kBAAkB,CAAC,CA+B7B"}

package/lib/types/client/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * DSH Vision Toolkit browser plugin: dedicated Tool cards plus the Settings,
+ * health, connection-test, and safe Artifact preview experience.
+ */
+import type { ClientContext, ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client';
+declare const en: {
+    readonly nav: "Vision";
+    readonly settingsTitle: "Vision Toolkit";
+    readonly settingsIntro: "Configure the pinned visual engineering runtime, its external vision endpoint, and local safety limits.";
+    readonly externalNotice: "Remote tools send the selected image bytes to the configured external vision API. Local crop, trace, pixel diff, palette, foreground extraction, and HTML rendering do not upload images.";
+    readonly provider: "Vision service";
+    readonly baseUrl: "Base URL";
+    readonly credential: "Credential reference";
+    readonly model: "Model";
+    readonly language: "Output language";
+    readonly limits: "Limits";
+    readonly timeout: "Request timeout (ms)";
+    readonly maxBytes: "Maximum image bytes";
+    readonly maxPixels: "Maximum image pixels";
+    readonly concurrency: "Concurrent calls per session";
+    readonly runtime: "Runtime";
+    readonly runtimeMode: "Runtime mode";
+    readonly toolkitPath: "Pinned checkout path";
+    readonly python: "Python override";
+    readonly allowedDirs: "Additional allowed directories";
+    readonly allowedDirsHint: "One path per line. The session workspace is always allowed.";
+    readonly save: "Save and apply";
+    readonly saving: "Validating runtime…";
+    readonly reload: "Reload";
+    readonly saved: "Settings validated and applied.";
+    readonly readOnly: "The active Settings provider is read-only.";
+    readonly configured: "Configured";
+    readonly missing: "Missing";
+    readonly source: "Source";
+    readonly health: "Health";
+    readonly runHealth: "Run health check";
+    readonly testConnection: "Test connection";
+    readonly testing: "Checking…";
+    readonly connectionHint: "Connection testing explicitly sends the configured credential to GET /models. It uploads no image and creates no completion.";
+    readonly pluginVersion: "Plugin";
+    readonly upstreamVersion: "Upstream";
+    readonly activeGeneration: "Runtime generation";
+    readonly runtimeUnavailable: "Runtime unavailable";
+    readonly runtimeCandidateRejected: "Last runtime candidate was rejected; the active generation remains available.";
+    readonly retry: "Retry";
+    readonly open: "Open file";
+    readonly download: "Download";
+    readonly previewUnavailable: "HTTP preview is unavailable in this host; use Open file.";
+    readonly running: "Running…";
+    readonly failed: "Failed";
+    readonly matches: "matches";
+    readonly elements: "elements";
+    readonly dimensions: "Dimensions";
+    readonly coordinates: "Coordinates";
+    readonly artifact: "Artifact";
+    readonly artifacts: "Artifacts";
+    readonly difference: "Overall difference";
+    readonly worstRegions: "Worst regions";
+    readonly colors: "Dominant colors";
+    readonly noResult: "Structured result unavailable; inspect the raw Tool result.";
+    readonly healthy: "Healthy";
+    readonly degraded: "Needs attention";
+    readonly notTested: "Not tested";
+};
+type LocaleKey = keyof typeof en;
+interface ToolCallOwnerProps {
+    callId: string;
+    toolName: string;
+    block: ToolCallBlock;
+    cwd?: string | undefined;
+    openFile: (path: string) => void;
+    inspect?: (() => void) | undefined;
+}
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /** Keyed atomic Tool call view, dispatched by wire Tool name. */
+        'tool.call.toolview': {
+            kind: 'keyed';
+            scope: 'session';
+            owner: ToolCallOwnerProps;
+        };
+    }
+    interface LocaleNamespaceMap {
+        /** DSH Vision Toolkit Tool cards and Settings copy. */
+        'vision-toolkit': LocaleKey;
+    }
+}
+interface HealthCheck {
+    status: 'ok' | 'warning' | 'error' | 'not_tested';
+    detail: string;
+}
+interface HealthResult {
+    pluginVersion: string;
+    checks: Record<string, HealthCheck>;
+    healthy: boolean;
+    connectionTested: boolean;
+}
+interface SettingsValue {
+    provider?: {
+        baseUrl?: string;
+        credential?: string;
+        model?: string;
+    };
+    language?: 'zh' | 'en';
+    timeoutMs?: number;
+    maxImageBytes?: number;
+    maxImagePixels?: number;
+    concurrency?: number;
+    runtime?: {
+        mode?: 'managed' | 'external';
+        agentVisionToolkitPath?: string;
+        python?: string;
+    };
+    allowedDirs?: string[];
+}
+interface SettingsSnapshot {
+    schemaVersion: 1;
+    writable: boolean;
+    settings: {
+        value: SettingsValue;
+        revision: number;
+        applies: 'live';
+    };
+    credential: {
+        ref: string;
+        configured: boolean;
+        source?: string;
+        writable: boolean;
+    };
+    runtime: {
+        ready: boolean;
+        generation: number;
+        activeConfig?: SettingsValue;
+        upstream?: {
+            source: 'managed' | 'external';
+            path: string;
+            runtimeHome: string;
+            python: string;
+            pythonVersion: string;
+        };
+        lastError?: string;
+    };
+    release: {
+        pluginVersion: string;
+        upstreamRepository: string;
+        upstreamVersion: string;
+        upstreamCommit: string;
+    };
+    artifactRouteAvailable: boolean;
+}
+/** Decode canonical presentation metadata with a JSON-text fallback. */
+export declare function decodeVisionResult(block: ToolCallBlock): Record<string, unknown> | undefined;
+interface SettingsState {
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    snapshot?: SettingsSnapshot | undefined;
+    health?: HealthResult | undefined;
+    action?: 'save' | 'health' | 'connection' | undefined;
+    message?: string | undefined;
+    error?: string | undefined;
+}
+/** Small external store shared by the Settings route and pushed invalidations. */
+export declare class VisionSettingsController {
+    private state;
+    private listeners;
+    private generation;
+    subscribe: (listener: () => void) => (() => void);
+    snapshot: () => SettingsState;
+    private set;
+    load(): Promise<void>;
+    refreshIfLoaded(): void;
+    save(value: SettingsValue, expectedRevision: number): Promise<void>;
+    runHealth(testConnection: boolean): Promise<void>;
+}
+/** Required client services. The pasted-image codec attaches to either trigger-service generation after load. */
+export declare const inject: string[];
+/** Register dedicated Tool views and the Vision Settings section. */
+export declare function apply(ctx: ClientContext): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.d.ts.map

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

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

@@ -0,0 +1,57 @@
+/** Clipboard-only multi-image input for DSH Web. */
+import { type ReactNode } from 'react';
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import type { InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+export declare const PASTE_IMAGES_ROUTE = "/_dsh/vision-toolkit/paste-images";
+interface PasteRecord {
+    ref: string;
+    file: File;
+    batch: PasteBatch;
+    status: 'ready' | 'copying' | 'copied' | 'error';
+    error?: string | undefined;
+    absolutePath?: string | undefined;
+}
+interface PasteBatch {
+    sessionId: string;
+    records: PasteRecord[];
+    inflight?: Promise<void> | undefined;
+    unsubscribe?: (() => void) | undefined;
+}
+interface PasteOccurrence {
+    occurrenceId: number;
+    source: string;
+    ref: string;
+    offset: number;
+    label: string;
+}
+type PasteDockProps = PropsRuntime<'conversation.input.dock'> & {
+    controller: PasteImageController;
+    remove: (occurrence: PasteOccurrence) => void;
+};
+/** Owns browser File objects until DSH serializes the corresponding text references. */
+export declare class PasteImageController {
+    private readonly ctx;
+    private readonly records;
+    private readonly listeners;
+    private revision;
+    constructor(ctx: ClientContext);
+    subscribe: (listener: () => void) => (() => void);
+    snapshot: () => number;
+    private changed;
+    source(): InputTriggerSource;
+    recordsFor(occurrences: readonly PasteOccurrence[]): PasteRecord[];
+    private inputFor;
+    private insertText;
+    private insertRecords;
+    handlePaste(event: ClipboardEvent): boolean;
+    remove(sessionId: string, occurrence: PasteOccurrence): void;
+    private upload;
+    private serialize;
+}
+/** Minimal per-image progress, failure, and removal feedback above the composer. */
+export declare function PasteImageDock(props: PasteDockProps): ReactNode;
+/** Install capture interception, the text-reference codec, and composer feedback. */
+export declare function installPasteImages(ctx: ClientContext): void;
+export {};
+//# sourceMappingURL=paste-images.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paste-images.d.ts","sourceRoot":"","sources":["../../../src/client/paste-images.tsx"],"names":[],"mappings":"AAAA,oDAAoD;AAEpD,OAAO,EAAwB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAA;AACzF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAGpE,eAAO,MAAM,kBAAkB,sCAAsC,CAAA;AAKrE,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,IAAI,CAAA;IACV,KAAK,EAAE,UAAU,CAAA;IACjB,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;IAChD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAClC;AAED,UAAU,UAAU;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,WAAW,EAAE,CAAA;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAA;IACpC,WAAW,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;CACvC;AAQD,UAAU,eAAe;IACvB,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,KAAK,cAAc,GAAG,YAAY,CAAC,yBAAyB,CAAC,GAAG;IAC9D,UAAU,EAAE,oBAAoB,CAAA;IAChC,MAAM,EAAE,CAAC,UAAU,EAAE,eAAe,KAAK,IAAI,CAAA;CAC9C,CAAA;AAkFD,wFAAwF;AACxF,qBAAa,oBAAoB;IAKnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwB;IAClD,OAAO,CAAC,QAAQ,CAAI;gBAES,GAAG,EAAE,aAAa;IAE/C,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAG/C;IAED,QAAQ,QAAO,MAAM,CAAiB;IAEtC,OAAO,CAAC,OAAO;IAKf,MAAM,IAAI,kBAAkB;IAc5B,UAAU,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,GAAG,WAAW,EAAE;IAOlE,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,aAAa;IAqDrB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;IAiC3C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI;YAuB9C,MAAM;YAsDN,SAAS;CAOxB;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAyB/D;AAED,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAyC3D"}

package/lib/types/config.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Plugin configuration: provider endpoint and credential reference, output
+ * language, limits, and the external upstream runtime location. Secrets never
+ * live here — `provider.credential` is a DSH Credential reference resolved per
+ * operation through `ctx.credentials`.
+ * @module dsh-vision-toolkit/config
+ */
+import type Schema from '@deepseek-ai/schemastery';
+import { type CredentialRef } from '@deepseek-ai/dsh-credentials';
+/** Settings document namespace owned by this plugin. */
+export declare const VISION_TOOLKIT_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Full user-facing configuration; every field defaults at the schema boundary. */
+export interface VisionToolkitConfig {
+    provider?: {
+        /** OpenAI-compatible chat/completions base URL. */
+        baseUrl?: string;
+        /** DSH Credential reference holding the API key (an environment-style name). */
+        credential?: string;
+        /** Multimodal model name. */
+        model?: string;
+    };
+    /** Vision output language (`zh` or `en`). */
+    language?: 'zh' | 'en';
+    /** Single remote/upstream call budget in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum accepted input image size in bytes. */
+    maxImageBytes?: number;
+    /** Maximum decoded pixel count per input image. */
+    maxImagePixels?: number;
+    /** In-flight tool execution cap per session. */
+    concurrency?: number;
+    runtime?: {
+        /** `managed` uses the packaged snapshot and isolated venv; `external` uses a clean pinned checkout. */
+        mode?: 'managed' | 'external';
+        /** Required path to the clean pinned checkout when `mode` is `external`. */
+        agentVisionToolkitPath?: string;
+        /** Optional Python 3.11+ bootstrap/interpreter override. */
+        python?: string;
+    };
+    /** Extra directories (besides the workspace) inputs may come from. */
+    allowedDirs?: string[];
+}
+/** Configuration schema with the documented P0 defaults. */
+export declare const Config: Schema<VisionToolkitConfig>;
+/** Configuration after static validation, with every default materialized. */
+export interface ResolvedVisionToolkitConfig {
+    provider: {
+        baseUrl: string;
+        credential: CredentialRef;
+        model: string;
+    };
+    language: 'zh' | 'en';
+    timeoutMs: number;
+    maxImageBytes: number;
+    maxImagePixels: number;
+    concurrency: number;
+    runtime: {
+        mode: 'managed' | 'external';
+        agentVisionToolkitPath?: string;
+        python?: string;
+    };
+    allowedDirs: string[];
+}
+/**
+ * Validate and normalize a config object (partial inputs receive the same
+ * defaults the schemastery schema applies). Configuration mistakes fail loud
+ * at plugin load (the earliest resolvable point); runtime availability is a
+ * separate, later concern.
+ * @param config - parsed config with defaults applied.
+ * @returns the fully defaulted, validated configuration.
+ */
+export declare function resolveConfig(config?: VisionToolkitConfig): ResolvedVisionToolkitConfig;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,MAAM,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAIhF,wDAAwD;AACxD,eAAO,MAAM,iCAAiC,uDAAsC,CAAA;AAEpF,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE;QACT,mDAAmD;QACnD,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,gFAAgF;QAChF,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,6BAA6B;QAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;IACD,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IACtB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE;QACR,uGAAuG;QACvG,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,CAAA;QAC7B,4EAA4E;QAC5E,sBAAsB,CAAC,EAAE,MAAM,CAAA;QAC/B,4DAA4D;QAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,CAAA;IACD,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,4DAA4D;AAC5D,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,mBAAmB,CAiB7C,CAAA;AAEF,8EAA8E;AAC9E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,CAAA;QACf,UAAU,EAAE,aAAa,CAAA;QACzB,KAAK,EAAE,MAAM,CAAA;KACd,CAAA;IACD,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE;QACP,IAAI,EAAE,SAAS,GAAG,UAAU,CAAA;QAC5B,sBAAsB,CAAC,EAAE,MAAM,CAAA;QAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,CAAA;IACD,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAOD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,mBAAwB,GAAG,2BAA2B,CA0E3F"}

package/lib/types/errors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stable error vocabulary shared by the runtime, upstream adapter, and tools.
+ * Every failure reaching the model carries one of these codes and a message
+ * that never contains credentials or raw upstream stack traces.
+ * @module dsh-vision-toolkit/errors
+ */
+/** Discriminant tag for every Vision Toolkit failure. */
+export declare const VISION_TOOLKIT_ERROR_CODES: readonly ["config", "input", "capacity", "service", "runtime", "output", "timeout", "cancelled", "path"];
+/** Stable machine-readable error category. */
+export type VisionToolkitErrorCode = typeof VISION_TOOLKIT_ERROR_CODES[number];
+/** Error with a stable category; safe to surface to the model. */
+export declare class VisionToolkitError extends Error {
+    readonly code: VisionToolkitErrorCode;
+    constructor(code: VisionToolkitErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Replace every known secret occurrence in untrusted text. Used before
+ * upstream stderr, exit messages, or trace reports enter logs or results.
+ * @param text - text that may embed a secret.
+ * @param secrets - values that must never be surfaced.
+ * @returns text with each secret replaced by a fixed marker.
+ */
+export declare function redactText(text: string, secrets: readonly string[]): string;
+/**
+ * Build a model-safe upstream failure line: the tool prefix plus the
+ * redacted stderr tail, never a JavaScript stack.
+ * @param tool - upstream CLI name.
+ * @param stderr - captured upstream stderr.
+ * @param secrets - values to redact.
+ * @returns one-line safe message.
+ */
+export declare function upstreamFailureMessage(tool: string, stderr: string, secrets: readonly string[]): string;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yDAAyD;AACzD,eAAO,MAAM,0BAA0B,0GAU7B,CAAA;AAEV,8CAA8C;AAC9C,MAAM,MAAM,sBAAsB,GAAG,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAA;AAE9E,kEAAkE;AAClE,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAA;gBAEzB,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKzF;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAO3E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGvG"}

package/lib/types/exposure.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Agent-scoped progressive exposure for the model-facing visual tools.
+ * Runtime readiness is global, while tool schemas enter only an Agent that has
+ * loaded the matching Skill; administrative diagnostics stay on the Web seam.
+ * @module dsh-vision-toolkit/exposure
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { Context } from '@deepseek-ai/cordis';
+/** Small bootstrap tool retained only until the current Agent gains visual tools. */
+export declare const VISION_TOOLKIT_ACTIVATE = "vision_toolkit_activate";
+/** Result returned by the one-shot activation transport. */
+export interface VisionToolkitActivationResult {
+    activated: boolean;
+    tools: string[];
+}
+/**
+ * Owns one progressive-exposure generation for a ready Vision Toolkit runtime.
+ * The bootstrap tool is global; visual definitions are created and registered
+ * in an Agent scope only after the Skill load is durable or just succeeded.
+ */
+export declare class VisionToolExposure {
+    private readonly ctx;
+    private readonly createTools;
+    readonly activationTool: ToolDefinition;
+    private readonly states;
+    private installed;
+    /**
+     * @param ctx - Plugin context with Tool and Agent registries.
+     * @param createTools - Fresh definitions bound to the current runtime generation.
+     */
+    constructor(ctx: Context, createTools: () => ToolDefinition[]);
+    /** Install lifecycle listeners and adopt Agents that already exist. */
+    install(): () => void;
+    private attach;
+    private activate;
+    private detach;
+    private disposeStates;
+    private disposeState;
+}
+//# sourceMappingURL=exposure.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../../src/exposure.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,qFAAqF;AACrF,eAAO,MAAM,uBAAuB,4BAA4B,CAAA;AAShE,4DAA4D;AAC5D,MAAM,WAAW,6BAA6B;IAC5C,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAqED;;;;GAIG;AACH,qBAAa,kBAAkB;IAU3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAV9B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IACzD,OAAO,CAAC,SAAS,CAAQ;IAEzB;;;OAGG;gBAEgB,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,MAAM,cAAc,EAAE;IA+BtD,uEAAuE;IACvE,OAAO,IAAI,MAAM,IAAI;IAiCrB,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,QAAQ;IA0BhB,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,YAAY;CAIrB"}

package/lib/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @anionex/dsh-vision-toolkit — DSH Vision Toolkit profile bundle.
+ *
+ * Plugin lifecycle follows the documented readiness chain: verify the pinned
+ * upstream checkout, publish the vision-tools Skill and its one-shot bootstrap,
+ * then mount the execution tools only in Agents that load that Skill. Any
+ * failure leaves no model capability behind, and disposal unregisters every
+ * global and Agent-scoped contribution the plugin mounted.
+ * @module @anionex/dsh-vision-toolkit
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, type VisionToolkitConfig } from './config.ts';
+export declare const name = "@anionex/dsh-vision-toolkit";
+export { Config };
+export declare const inject: string[];
+/** Plugin entry: validate configuration synchronously, then mount asynchronously. */
+export declare function apply(ctx: Context, config?: VisionToolkitConfig): Promise<() => void>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EACL,MAAM,EAGN,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAA;AASpB,eAAO,MAAM,IAAI,gCAAgC,CAAA;AAEjD,OAAO,EAAE,MAAM,EAAE,CAAA;AAEjB,eAAO,MAAM,MAAM,UAAqF,CAAA;AAExG,qFAAqF;AACrF,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAoF/F"}

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

@@ -0,0 +1,21 @@
+/** 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";
+/** 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;
+/** Runtime limit face kept separate for focused backend tests. */
+export interface PasteImageRuntime {
+    maxImageBytes(): 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;AAuErE,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;AAkFD,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,aAAa,IAAI,MAAM,CAAA;CACxB;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"}