dsh-click 0.1.0

package/lib/types/platform/types.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Wire vocabulary shared by the harness-side backends and the native helper
+ * process (the platform seam). Every `DesktopBackend` implementation — the
+ * Windows helper runner today, reserved macOS/Linux backends later — speaks
+ * these types; helper JSON responses are validated against them at the wire
+ * boundary because they cross a process trust line.
+ *
+ * @module dsh-click/platform/types
+ */
+import type { ProcessFacts } from '../events.ts';
+/** Error with a stable machine-routing code, model-readable message included. */
+export declare class DshClickError extends Error {
+    readonly code: string;
+    /** @param message - human- and model-readable failure text. */
+    /** @param code - stable code for policy and diagnostics. */
+    constructor(message: string, code: string);
+}
+/** How a window may be addressed in an observation request. */
+export interface WindowRef {
+    /** Native window handle (HWND on Windows). */
+    windowId?: number;
+    /** Window title; the helper matches the first visible window containing it. */
+    windowTitle?: string;
+    /** Owning process id. */
+    processId?: number;
+}
+/** Screen-space rectangle, integer pixel coordinates. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One top-level application window. */
+export interface WindowInfo {
+    windowId: number;
+    processId: number | null;
+    title: string;
+    className: string;
+    rect: Rect;
+    executablePath: string | null;
+    visible: boolean;
+}
+/** One accessibility element inside the observed window. */
+export interface ElementInfo {
+    /** Stable per-instance element id (UIA runtime id on Windows). */
+    elementId: string;
+    /** Control type, e.g. "Button" or "Edit". */
+    controlType: string;
+    /** Accessibility name; empty when unnamed. */
+    name: string;
+    /** Automation id; empty when unset. */
+    automationId: string;
+    /** Bounding rectangle in screen coordinates. */
+    rect: Rect;
+    /** Whether the element is enabled. */
+    enabled: boolean;
+    /** Patterns the element supports (value/invoke/scroll), so the model can pick the right action. */
+    patterns: string[];
+}
+/** One pixel-location hint: a labeled point and its observed color. */
+export interface PixelHint {
+    /** Element or region label the hint describes. */
+    label: string;
+    /** Screen x coordinate. */
+    x: number;
+    /** Screen y coordinate. */
+    y: number;
+    /** RGB color at the point, like "rgb(12, 34, 56)". */
+    color: string;
+}
+/** Fresh identity + content hashes for one window, captured at observation time. */
+export interface WindowSnapshot {
+    windowId: number;
+    processId: number;
+    executablePath: string | null;
+    title: string;
+    className: string;
+    rect: Rect;
+    /** True when the window currently owns the foreground. */
+    foreground: boolean;
+    /** Hash of the accessibility subtree (element ids, rects, names, types). */
+    treeHash: string;
+    /** Hash of the window's current pixels. */
+    shotHash: string;
+    /** Number of elements the tree walk captured. */
+    elementCount: number;
+}
+/** A captured screenshot plus the snapshot facts it was taken with. */
+export interface Screenshot {
+    /** PNG bytes, base64-encoded. */
+    pngBase64: string;
+    width: number;
+    height: number;
+    snapshot: WindowSnapshot;
+}
+/** An accessibility tree read plus pixel hints. */
+export interface Tree {
+    snapshot: WindowSnapshot;
+    elements: ElementInfo[];
+    pixels: PixelHint[];
+}
+/** One running desktop application. */
+export interface AppInfo {
+    processId: number;
+    name: string;
+    executablePath: string | null;
+    windows: WindowInfo[];
+}
+/** A click request: exactly one of element id or coordinates. */
+export interface ClickRequest {
+    windowId: number;
+    elementId?: string;
+    x?: number;
+    y?: number;
+    button: 'left' | 'right';
+}
+/** A type request addressed to a value-pattern element. */
+export interface TypeRequest {
+    windowId: number;
+    elementId: string;
+    text: string;
+    /** Whether the helper backs up and restores the control text on failure. */
+    rollback: boolean;
+}
+/** A scroll request. */
+export interface ScrollRequest {
+    windowId: number;
+    elementId?: string;
+    direction: 'up' | 'down' | 'page-up' | 'page-down';
+    /** Number of increments; positive only. */
+    amount: number;
+}
+/** A key-combination request (e.g. "Ctrl+S", "Enter"). */
+export interface KeyRequest {
+    windowId: number;
+    keys: string;
+}
+/** The settled outcome of one mutating action, as reported by the helper. */
+export interface ActionOutcome {
+    windowId: number;
+    /** Which action ran, for the audit trail. */
+    action: string;
+    /** Delivery mechanism actually used. */
+    delivered: 'uia' | 'posted' | 'none';
+    processBefore: ProcessFacts;
+    processAfter: ProcessFacts;
+    /** Present on `type`: whether failed typing restored the original text. */
+    restored?: boolean;
+    /** Short helper-side detail. */
+    detail?: string;
+}
+/** The settled outcome of an app launch. */
+export interface LaunchOutcome {
+    processId: number;
+    executablePath: string | null;
+}
+/**
+ * The platform abstraction every desktop backend implements. Backends must
+ * never move input focus themselves; the `focusFallback` flag is the ONLY
+ * sanctioned escape hatch and stays `false` by default.
+ */
+export interface DesktopBackend {
+    /** Platform id this backend serves (`win32`, reserved `darwin`/`linux`). */
+    readonly platform: string;
+    /** Whether the backend can run at all (services mounted, platform supported). */
+    readonly available: boolean;
+    /** Why the backend is unavailable, when it is. */
+    readonly unavailableReason?: string;
+    /** List every visible top-level window across running applications. */
+    listWindows(signal?: AbortSignal): Promise<WindowInfo[]>;
+    /** Capture a screenshot of the addressed window (or the primary screen). */
+    shot(ref: WindowRef, maxSide: number, signal?: AbortSignal): Promise<Screenshot>;
+    /** Read the accessibility tree plus pixel hints of the addressed window. */
+    tree(ref: WindowRef, maxElements: number, maxDepth: number, includePixels: boolean, signal?: AbortSignal): Promise<Tree>;
+    /** Re-capture fresh identity + hashes for one window (the stale check). */
+    snapshot(windowId: number, signal?: AbortSignal): Promise<WindowSnapshot>;
+    /** Perform a click inside the target window. */
+    click(request: ClickRequest, focusFallback: boolean, signal?: AbortSignal): Promise<ActionOutcome>;
+    /** Type text into the target element. */
+    type(request: TypeRequest, focusFallback: boolean, signal?: AbortSignal): Promise<ActionOutcome>;
+    /** Scroll the target element or window. */
+    scroll(request: ScrollRequest, focusFallback: boolean, signal?: AbortSignal): Promise<ActionOutcome>;
+    /** Send a key combination to the target window. */
+    key(request: KeyRequest, focusFallback: boolean, signal?: AbortSignal): Promise<ActionOutcome>;
+    /** List running desktop applications. */
+    apps(signal?: AbortSignal): Promise<AppInfo[]>;
+    /** Launch one application by name or path. */
+    launch(name: string, args: readonly string[], signal?: AbortSignal): Promise<LaunchOutcome>;
+}
+/** The JSON request the harness writes to the helper's stdin. */
+export interface HelperRequest {
+    protocol: number;
+    pluginVersion: string;
+    requestId: string;
+    op: string;
+    args: Record<string, unknown>;
+}
+/** The JSON response the helper writes to stdout: either a result or an error. */
+export type HelperResponse = {
+    ok: true;
+    result: unknown;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** Assert one helper response field is a finite number; throws on violation. */
+export declare function expectNumber(record: Record<string, unknown>, field: string, op: string): number;
+/** Assert one helper response field is a string; throws on violation. */
+export declare function expectString(record: Record<string, unknown>, field: string, op: string): string;
+/** Assert one helper response field is a plain record; throws on violation. */
+export declare function expectRecord(record: Record<string, unknown>, field: string, op: string): Record<string, unknown>;
+/** Assert an entire helper payload is a plain record; throws on violation. */
+export declare function expectRecordValue(value: unknown, op: string): Record<string, unknown>;
+/** Parse the helper's `processBefore`/`processAfter` facts at the wire boundary. */
+export declare function expectProcessFacts(value: unknown, op: string): ProcessFacts;
+//# sourceMappingURL=types.d.ts.map

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

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

package/lib/types/sanitize.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure display/audit redaction for everything dsh-click shows to the model or
+ * writes to a session log: window titles, executable paths, and free text that
+ * may contain credentials. Every function is pure and total on string input;
+ * extreme cases are covered by `tests/sanitize.spec.ts`.
+ *
+ * @module dsh-click/sanitize
+ */
+/**
+ * Strip control characters and truncate to `maxLength`.
+ *
+ * @param text - the raw string.
+ * @param maxLength - maximum returned length (including the truncation marker).
+ * @returns the sanitized string.
+ */
+export declare function sanitizeText(text: string, maxLength: number): string;
+/**
+ * Sanitize a filesystem path for display: control characters removed, and the
+ * TAIL (filename side) preserved when truncating, since the head is the part
+ * that usually repeats.
+ *
+ * @param path - the raw path.
+ * @param maxLength - maximum returned length (including the truncation marker).
+ * @returns the sanitized path.
+ */
+export declare function sanitizePath(path: string, maxLength: number): string;
+/**
+ * Redact credential-shaped fragments from free text before it reaches a log or
+ * display surface: `key=`/`key:` assignments, JWTs, and bearer tokens.
+ *
+ * @param text - the raw text.
+ * @returns the redacted text.
+ */
+export declare function redactSensitive(text: string): string;
+/**
+ * The one entry point for model-visible strings: redact first (secret values
+ * stop at control characters), then sanitize (control characters removed,
+ * tabs collapsed, length capped).
+ *
+ * @param text - the raw string.
+ * @param maxLength - truncation length.
+ * @returns the sanitized, redacted string.
+ */
+export declare function sanitizeVisible(text: string, maxLength: number): 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;;;;;;;GAOG;AAiBH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvE"}

package/lib/types/tools.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The eight model tools dsh-click registers: two observers
+ * (`screen_shot`, `screen_read`), four window-scoped actions
+ * (`click`, `type`, `scroll`, `key`), and two application tools
+ * (`app_list`, `app_launch`). Observers are read-only; every action crosses
+ * {@link ActionExecutor} — freshness check, approval gate, process-identity
+ * check — before anything happens. Tool outputs are canonical JSON plus a
+ * pure text renderer; `screen_shot` additionally emits an image content block
+ * when the model accepts images (vision routing).
+ *
+ * @module dsh-click/tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { ActionExecutor } from './actions.ts';
+import type { ResolvedConfig } from './config.ts';
+import { ObservationStore } from './observe.ts';
+import type { DesktopBackend, Rect } from './platform/types.ts';
+/** Everything one tool needs at runtime; injected by `src/index.ts`. */
+export interface ToolServices {
+    /** The mounting context. */
+    readonly ctx: Context;
+    /** Resolved plugin config. */
+    readonly config: ResolvedConfig;
+    /** The active desktop backend. */
+    readonly backend: DesktopBackend;
+    /** The observation cache. */
+    readonly observations: ObservationStore;
+    /** The action executor. */
+    readonly actions: ActionExecutor;
+}
+/** The sanitized, model-visible window facts shared by observer outputs. */
+export interface ObservedWindowValue {
+    windowId: number;
+    processId: number;
+    title: string;
+    className: string;
+    executablePath: string | null;
+    rect: Rect;
+    foreground: boolean;
+}
+/**
+ * `screen_shot` — capture the addressed window (or the primary screen).
+ * In `imageMode: 'auto'` the result carries an image attachment when the
+ * current model accepts images; otherwise a text description keeps text-only
+ * models working.
+ *
+ * @param services - runtime services.
+ * @returns the tool definition.
+ */
+export declare function screenShotTool(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * `screen_read` — the structured observation for text-only models: the
+ * window's accessibility tree plus pixel-location hints. The returned
+ * elementIds are what click/type/scroll address.
+ *
+ * @param services - runtime services.
+ * @returns the tool definition.
+ */
+export declare function screenReadTool(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * `click` — click an element (by elementId) or a coordinate inside the
+ * observed window. Never steals foreground focus; delivery is UIA invoke
+ * where possible, posted window messages otherwise.
+ *
+ * @param services - runtime services.
+ * @returns the tool definition.
+ */
+export declare function clickTool(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * `type` — type text into a value-pattern element. The helper backs up the
+ * control text first and restores it when the action fails (config
+ * `rollbackEnabled`).
+ *
+ * @param services - runtime services.
+ * @returns the tool definition.
+ */
+export declare function typeTool(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * `scroll` — scroll an element (scroll pattern) or the observed window
+ * (posted wheel messages). Never steals foreground focus.
+ *
+ * @param services - runtime services.
+ * @returns the tool definition.
+ */
+export declare function scrollTool(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * `key` — send a key combination to the observed window as posted window
+ * messages. Never steals foreground focus; apps that ignore posted input
+ * fail with a clear error.
+ *
+ * @param services - runtime services.
+ * @returns the tool definition.
+ */
+export declare function keyTool(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * `app_list` — enumerate running desktop applications and their windows.
+ * Read-only: never needs approval.
+ *
+ * @param services - runtime services.
+ * @returns the tool definition.
+ */
+export declare function appListTool(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * `app_launch` — launch one application by name or path. Gated by approval
+ * (allowlist matching applies against the requested name/path).
+ *
+ * @param services - runtime services.
+ * @returns the tool definition.
+ */
+export declare function appLaunchTool(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** Every tool definition, in registration order. */
+export declare function allTools(services: ToolServices): import("@deepseek-ai/dsh-tools").ToolDefinition[];
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG/C,OAAO,KAAK,EAAE,cAAc,EAA0B,IAAI,EAAyC,MAAM,qBAAqB,CAAA;AAE9H,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAA;IACvC,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CACjC;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,IAAI,EAAE,IAAI,CAAA;IACV,UAAU,EAAE,OAAO,CAAA;CACpB;AA+ED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,mDAoIpD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,mDA+IpD;AAiED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,mDAoD/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,mDAyC9C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,YAAY,mDA0ChD;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,YAAY,mDAkC7C;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,mDA+EjD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,mDAwCnD;AAED,oDAAoD;AACpD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,YAAY,qDAW9C"}

package/lib/types/version.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The plugin version, hardcoded on purpose: it rides the helper-process
+ * protocol handshake, so it must track `package.json` or released helpers
+ * report a stale plugin. Bumping `package.json` without touching this file
+ * fails `tests/version.spec.ts`, and `scripts/release.mjs` bumps both.
+ *
+ * @module dsh-click/version
+ */
+/** Plugin version advertised in the helper-protocol handshake. */
+export declare const VERSION = "0.1.0";
+/** The helper protocol revision; bump only on incompatible wire changes. */
+export declare const HELPER_PROTOCOL_VERSION = 1;
+//# 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;;;;;;;GAOG;AAEH,kEAAkE;AAClE,eAAO,MAAM,OAAO,UAAU,CAAA;AAE9B,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,IAAI,CAAA"}

package/lib/types/vision.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Vision routing: whether the calling agent's model accepts image input.
+ * `screen_shot` uses this in `imageMode: 'auto'` to decide between an image
+ * block (vision model) and a text description (text-only model). Every
+ * failure — no agent, no llm service, no provider/model on the agent, adapter
+ * errors — resolves to `false`, so the text fallback is the fail-closed
+ * default.
+ *
+ * @module dsh-click/vision
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/**
+ * Resolve whether the calling agent's current model declares image input.
+ *
+ * @param agent - the calling agent (may be undefined).
+ * @param ctx - the mounting context.
+ * @param signal - cancellation for the model-info lookup.
+ * @returns true only when the resolved model declares the `image` modality.
+ */
+export declare function sessionAcceptsImages(agent: Agent | undefined, ctx: Context, signal?: AbortSignal): Promise<boolean>;
+//# sourceMappingURL=vision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vision.d.ts","sourceRoot":"","sources":["../../src/vision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAGnD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAazH"}