dsh-click 0.1.0

package/lib/index.js

@@ -0,0 +1,1810 @@
+import z from "@deepseek-ai/schemastery";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/events.ts
+/** The observation audit event type. */
+const OBSERVED_EVENT = "dsh-click/observed";
+/** The action audit event type. */
+const ACTION_EVENT = "dsh-click/action";
+//#endregion
+//#region src/sanitize.ts
+/**
+* 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
+*/
+/** Control characters replaced by a space (tab) or removed entirely (the rest). */
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000B-\u000C\u000E-\u001F\u007F]/gu;
+/** Truncation marker appended when a string is cut to `maxLength`. */
+const TRUNCATION_MARKER = "…";
+/** Credential-shaped `name=value` / `name: value` pairs; values stop at control characters too. */
+const SECRET_ASSIGNMENT = /((?:api[_-]?key|token|secret|password|passwd)\s*[=:])\s*[^\s"'<>\u0000-\u001F\u007F]+/giu;
+/** JSON Web Tokens (three base64url segments separated by dots). */
+const JWT_PATTERN = /\beyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{4,}\b/gu;
+/** `Bearer` credentials. */
+const BEARER_PATTERN = /(\bbearer\s+)[A-Za-z0-9._~+/=-]{8,}/giu;
+/**
+* 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.
+*/
+function sanitizeText(text, maxLength) {
+	const cleaned = text.replace(CONTROL_CHARACTERS, "").replace(/\t+/gu, " ");
+	if (cleaned.length <= maxLength) return cleaned;
+	return cleaned.slice(0, Math.max(0, maxLength - 1)) + TRUNCATION_MARKER;
+}
+/**
+* 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.
+*/
+function sanitizePath(path, maxLength) {
+	const cleaned = path.replace(CONTROL_CHARACTERS, "").replace(/\t+/gu, " ");
+	if (cleaned.length <= maxLength) return cleaned;
+	return TRUNCATION_MARKER + cleaned.slice(cleaned.length - (maxLength - 1));
+}
+/**
+* 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.
+*/
+function redactSensitive(text) {
+	return text.replace(SECRET_ASSIGNMENT, "$1[redacted]").replace(JWT_PATTERN, "[redacted]").replace(BEARER_PATTERN, "$1[redacted]");
+}
+/**
+* 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.
+*/
+function sanitizeVisible(text, maxLength) {
+	return sanitizeText(redactSensitive(text), maxLength);
+}
+//#endregion
+//#region src/platform/types.ts
+/** Error with a stable machine-routing code, model-readable message included. */
+var DshClickError = class extends Error {
+	code;
+	/** @param message - human- and model-readable failure text. */
+	/** @param code - stable code for policy and diagnostics. */
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "DshClickError";
+	}
+};
+/** Assert one helper response field is a finite number; throws on violation. */
+function expectNumber(record, field, op) {
+	const value = record[field];
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new DshClickError(`helper "${op}" returned a non-numeric "${field}" field`, "BAD_HELPER_RESPONSE");
+	return value;
+}
+/** Assert one helper response field is a string; throws on violation. */
+function expectString(record, field, op) {
+	const value = record[field];
+	if (typeof value !== "string") throw new DshClickError(`helper "${op}" returned a non-string "${field}" field`, "BAD_HELPER_RESPONSE");
+	return value;
+}
+/** Assert an entire helper payload is a plain record; throws on violation. */
+function expectRecordValue(value, op) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new DshClickError(`helper "${op}" returned a non-object payload`, "BAD_HELPER_RESPONSE");
+	return value;
+}
+/** Parse the helper's `processBefore`/`processAfter` facts at the wire boundary. */
+function expectProcessFacts(value, op) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new DshClickError(`helper "${op}" returned malformed process facts`, "BAD_HELPER_RESPONSE");
+	const record = value;
+	const pid = expectNumber(record, "pid", op);
+	const executablePath = record["executablePath"];
+	if (executablePath !== null && typeof executablePath !== "string") throw new DshClickError(`helper "${op}" returned malformed process facts`, "BAD_HELPER_RESPONSE");
+	return {
+		pid,
+		executablePath
+	};
+}
+//#endregion
+//#region src/actions.ts
+/** Approval failure detail, model-readable. */
+const APPROVAL_DETAIL = {
+	rejected: "rejected by the approval answerer",
+	cancelled: "cancelled while waiting for approval",
+	unavailable: "no approval answerer is available (fail closed)"
+};
+/** Executes mutating desktop actions behind the full safety boundary. */
+var ActionExecutor = class {
+	deps;
+	/** @param deps - executor dependencies. */
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** The mounting context. */
+	get ctx() {
+		return this.deps.ctx;
+	}
+	/** The resolved config. */
+	get config() {
+		return this.deps.config;
+	}
+	/** Append one action audit event; a failed append never changes the outcome. */
+	audit(exec, event) {
+		const session = exec.agent?.session;
+		if (session === void 0) return;
+		try {
+			session.append(ACTION_EVENT, event);
+		} catch {}
+	}
+	/**
+	* The staleness boundary: resolve the cited observation, re-observe the
+	* window right now, and compare.
+	*
+	* @param observationId - the observation the action cites.
+	* @param windowId - the window the action addresses.
+	* @param signal - cancellation.
+	* @returns the cited record and the fresh snapshot.
+	*/
+	async requireFreshWindow(observationId, windowId, signal) {
+		const record = this.deps.observations.get(observationId);
+		if (record === void 0) throw new DshClickError(`unknown observation "${observationId}" — run screen_read or screen_shot again and cite the returned observationId`, "UNKNOWN_OBSERVATION");
+		if (record.windowId !== windowId) throw new DshClickError(`observation ${observationId} belongs to window ${record.windowId}, not ${windowId}`, "UNKNOWN_OBSERVATION");
+		const fresh = await this.deps.backend.snapshot(windowId, signal);
+		const verdict = this.deps.observations.verify(record, fresh);
+		if (!verdict.ok) throw new DshClickError(`${verdict.detail} — run screen_read or screen_shot again before acting`, verdict.code);
+		return {
+			record,
+			fresh
+		};
+	}
+	/**
+	* The approval gate. Matchers run against the sanitized window title and
+	* the executable path; a match skips the ask (still audited as allowlist).
+	* With no matcher, a missing approval service or a missing calling agent
+	* fails closed; the real approval service is asked otherwise.
+	*
+	* @param exec - the calling tool execution.
+	* @param toolName - the tool asking (audit + prompt identity).
+	* @param subject - what the action targets, for the reason and the matchers.
+	* @param signal - cancellation.
+	* @returns which gate allowed the action.
+	*/
+	async gate(exec, toolName, subject, signal) {
+		if (!this.config.requireApproval) return "none";
+		if (this.config.autoApproveMatchers.some((matcher) => subject.title !== null && matcher.test(subject.title) || subject.executablePath !== null && matcher.test(subject.executablePath))) return "allowlist";
+		const approval = this.ctx.get("approval");
+		if (approval === void 0) throw new DshClickError("approval is required but the approval service is not mounted — mount @deepseek-ai/dsh-user-approval or allowlist this window", "APPROVAL_UNAVAILABLE");
+		if (exec.agent === void 0) throw new DshClickError("approval is required but no agent owns this call — refusing (fail closed)", "APPROVAL_UNAVAILABLE");
+		const target = subject.title ?? subject.executablePath ?? "unknown target";
+		const outcome = await approval.request({
+			agent: exec.agent,
+			toolName,
+			callId: exec.callId,
+			reason: `${toolName} on ${sanitizeVisible(target, this.config.maxTextLength)}`,
+			signal
+		});
+		if (outcome !== "allowed-once") throw new DshClickError(`action denied by approval: ${APPROVAL_DETAIL[outcome] ?? outcome}`, "APPROVAL_DENIED");
+		return "approval";
+	}
+	/**
+	* Compare the process identity captured before and after an action.
+	*
+	* @param before - facts captured pre-action.
+	* @param after - facts captured post-action.
+	*/
+	assertProcessUnchanged(before, after) {
+		if (before.pid !== after.pid || before.executablePath !== after.executablePath) throw new DshClickError(`the target process changed during the action (before: pid ${before.pid} ${before.executablePath ?? "?"}; after: pid ${after.pid} ${after.executablePath ?? "?"}) — the action was delivered to a different process identity and must be reviewed`, "PROCESS_CHANGED");
+	}
+	/**
+	* Run one window-scoped mutating action through the shared boundary:
+	* freshness, approval, perform, process check, audit.
+	*
+	* @param toolName - the calling tool name.
+	* @param exec - the calling execution.
+	* @param observationId - the cited observation.
+	* @param windowId - the target window.
+	* @param run - the backend call (receives the resolved focus flag).
+	* @returns the validated backend outcome.
+	*/
+	async perform(toolName, exec, observationId, windowId, run) {
+		let approved = "none";
+		let observationIdAudited;
+		let windowIdAudited;
+		try {
+			const { record } = await this.requireFreshWindow(observationId, windowId, exec.signal);
+			observationIdAudited = observationId;
+			windowIdAudited = windowId;
+			approved = await this.gate(exec, toolName, {
+				title: record.title,
+				executablePath: record.executablePath
+			}, exec.signal);
+			const outcome = await run(this.config.focusFallback === "allow");
+			this.assertProcessUnchanged(outcome.processBefore, outcome.processAfter);
+			this.audit(exec, {
+				tool: toolName,
+				approved,
+				outcome: "ok",
+				observationId: observationIdAudited,
+				windowId: windowIdAudited,
+				processBefore: outcome.processBefore,
+				processAfter: outcome.processAfter,
+				...outcome.restored !== void 0 ? { restored: outcome.restored } : {},
+				...outcome.detail !== void 0 ? { detail: outcome.detail } : {}
+			});
+			return outcome;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			this.audit(exec, {
+				tool: toolName,
+				approved,
+				outcome: "error",
+				...observationIdAudited !== void 0 ? { observationId: observationIdAudited } : {},
+				...windowIdAudited !== void 0 ? { windowId: windowIdAudited } : {},
+				detail: message
+			});
+			throw error;
+		}
+	}
+	/**
+	* Gate and launch one application. No window observation exists yet, so the
+	* gate runs against the requested name/path alone and the launch outcome's
+	* process facts are the post-identity proof.
+	*
+	* @param exec - the calling execution.
+	* @param name - the app name or executable path.
+	* @param args - launch arguments.
+	* @returns the launch outcome.
+	*/
+	async launch(exec, name, args) {
+		const toolName = "app_launch";
+		let approved = "none";
+		try {
+			approved = await this.gate(exec, toolName, {
+				title: null,
+				executablePath: name
+			}, exec.signal);
+			const outcome = await this.deps.backend.launch(name, args, exec.signal);
+			this.audit(exec, {
+				tool: toolName,
+				approved,
+				outcome: "ok",
+				processAfter: {
+					pid: outcome.processId,
+					executablePath: outcome.executablePath
+				},
+				detail: name
+			});
+			return outcome;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			this.audit(exec, {
+				tool: toolName,
+				approved,
+				outcome: "error",
+				detail: message
+			});
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* Plugin configuration and its explicit resolve step. `resolveConfig` re-judges
+* every default and bound so programmatic construction that bypasses
+* Schemastery normalization still fails loud instead of running with hidden
+* defaults (the explicit-resolve contract).
+*
+* @module dsh-click/config
+*/
+/** Default per-helper-call timeout in milliseconds. */
+const DEFAULT_HELPER_TIMEOUT_MS = 3e4;
+/** Ceiling for one helper call: a screenshot of a large desktop can take a while. */
+const MAX_HELPER_TIMEOUT_MS = 3e5;
+/** Default cap on one helper response in bytes (PNG screenshots are base64-heavy). */
+const DEFAULT_MAX_HELPER_OUTPUT_BYTES = 25165824;
+/** Ceiling on one helper response. */
+const MAX_HELPER_OUTPUT_BYTES = 67108864;
+/** Default longest side of a captured screenshot in pixels (larger captures downscale). */
+const DEFAULT_MAX_SCREENSHOT_SIDE = 2560;
+const MAX_SCREENSHOT_SIDE = 7680;
+/** Default maximum age of an observation that an action may still base on. */
+const DEFAULT_MAX_OBSERVATION_AGE_MS = 3e4;
+/** Bounds for the observation age. */
+const MIN_OBSERVATION_AGE_MS = 1e3;
+const MAX_OBSERVATION_AGE_MS = 6e5;
+/** Ceiling on the element cap. */
+const MAX_ELEMENTS = 2e3;
+/** Ceiling on the sanitization truncation length. */
+const MAX_TEXT_LENGTH = 1e4;
+/** Schemastery schema for loader-validated configuration. */
+const Config = z.object({
+	requireApproval: z.boolean().default(true),
+	autoApproveWindows: z.array(z.string()).default([]),
+	focusFallback: z.union(["never", "allow"]).default("never"),
+	imageMode: z.union(["auto", "text"]).default("auto"),
+	helperTimeoutMs: z.number().min(1).max(MAX_HELPER_TIMEOUT_MS).default(DEFAULT_HELPER_TIMEOUT_MS),
+	maxHelperOutputBytes: z.number().min(1024).max(MAX_HELPER_OUTPUT_BYTES).default(DEFAULT_MAX_HELPER_OUTPUT_BYTES),
+	maxScreenshotSide: z.number().min(320).max(MAX_SCREENSHOT_SIDE).default(DEFAULT_MAX_SCREENSHOT_SIDE),
+	staleCheckPixels: z.boolean().default(true),
+	maxObservationAgeMs: z.number().min(MIN_OBSERVATION_AGE_MS).max(MAX_OBSERVATION_AGE_MS).default(DEFAULT_MAX_OBSERVATION_AGE_MS),
+	maxCachedObservations: z.number().min(1).max(64).default(8),
+	maxElements: z.number().min(1).max(MAX_ELEMENTS).default(500),
+	maxTreeDepth: z.number().min(1).max(64).default(32),
+	maxTextLength: z.number().min(16).max(MAX_TEXT_LENGTH).default(200),
+	rollbackEnabled: z.boolean().default(true)
+});
+/** Throw the standard fail-loud config error for one invalid field. */
+function invalid(field, detail) {
+	throw new Error(`dsh-click: config.${field} ${detail}`);
+}
+/** Compile one allowlist pattern; an invalid regex fails at load, not at match time. */
+function compileMatcher(source, index) {
+	try {
+		return new RegExp(source, "iu");
+	} catch {
+		invalid("autoApproveWindows", `entry ${index} (${JSON.stringify(source)}) is not a valid regular expression`);
+	}
+}
+/**
+* Resolve raw config to the runtime policy, re-validating defaults and bounds.
+*
+* @param config - raw loader config; `undefined` for a bare row.
+* @returns the frozen resolved config.
+*/
+function resolveConfig(config) {
+	const requireApproval = config?.requireApproval ?? true;
+	if (typeof requireApproval !== "boolean") invalid("requireApproval", "must be a boolean");
+	const autoApproveMatchers = (config?.autoApproveWindows ?? []).map(compileMatcher);
+	const focusFallback = config?.focusFallback ?? "never";
+	if (focusFallback !== "never" && focusFallback !== "allow") invalid("focusFallback", "must be \"never\" or \"allow\"");
+	const imageMode = config?.imageMode ?? "auto";
+	if (imageMode !== "auto" && imageMode !== "text") invalid("imageMode", "must be \"auto\" or \"text\"");
+	const helperTimeoutMs = config?.helperTimeoutMs ?? 3e4;
+	if (!Number.isFinite(helperTimeoutMs) || helperTimeoutMs < 1 || helperTimeoutMs > 3e5) invalid("helperTimeoutMs", `must be a finite number between 1 and ${MAX_HELPER_TIMEOUT_MS}`);
+	const maxHelperOutputBytes = config?.maxHelperOutputBytes ?? 25165824;
+	if (!Number.isInteger(maxHelperOutputBytes) || maxHelperOutputBytes < 1024 || maxHelperOutputBytes > 67108864) invalid("maxHelperOutputBytes", `must be an integer between 1024 and ${MAX_HELPER_OUTPUT_BYTES}`);
+	const maxScreenshotSide = config?.maxScreenshotSide ?? 2560;
+	if (!Number.isInteger(maxScreenshotSide) || maxScreenshotSide < 320 || maxScreenshotSide > 7680) invalid("maxScreenshotSide", `must be an integer between 320 and ${MAX_SCREENSHOT_SIDE}`);
+	const staleCheckPixels = config?.staleCheckPixels ?? true;
+	if (typeof staleCheckPixels !== "boolean") invalid("staleCheckPixels", "must be a boolean");
+	const maxObservationAgeMs = config?.maxObservationAgeMs ?? 3e4;
+	if (!Number.isFinite(maxObservationAgeMs) || maxObservationAgeMs < 1e3 || maxObservationAgeMs > 6e5) invalid("maxObservationAgeMs", `must be a finite number between ${MIN_OBSERVATION_AGE_MS} and ${MAX_OBSERVATION_AGE_MS}`);
+	const maxCachedObservations = config?.maxCachedObservations ?? 8;
+	if (!Number.isInteger(maxCachedObservations) || maxCachedObservations < 1 || maxCachedObservations > 64) invalid("maxCachedObservations", `must be an integer between 1 and 64`);
+	const maxElements = config?.maxElements ?? 500;
+	if (!Number.isInteger(maxElements) || maxElements < 1 || maxElements > 2e3) invalid("maxElements", `must be an integer between 1 and ${MAX_ELEMENTS}`);
+	const maxTreeDepth = config?.maxTreeDepth ?? 32;
+	if (!Number.isInteger(maxTreeDepth) || maxTreeDepth < 1 || maxTreeDepth > 64) invalid("maxTreeDepth", `must be an integer between 1 and 64`);
+	const maxTextLength = config?.maxTextLength ?? 200;
+	if (!Number.isInteger(maxTextLength) || maxTextLength < 16 || maxTextLength > 1e4) invalid("maxTextLength", `must be an integer between 16 and ${MAX_TEXT_LENGTH}`);
+	const rollbackEnabled = config?.rollbackEnabled ?? true;
+	if (typeof rollbackEnabled !== "boolean") invalid("rollbackEnabled", "must be a boolean");
+	return Object.freeze({
+		requireApproval,
+		autoApproveMatchers: Object.freeze(autoApproveMatchers),
+		focusFallback,
+		imageMode,
+		helperTimeoutMs,
+		maxHelperOutputBytes,
+		maxScreenshotSide,
+		staleCheckPixels,
+		maxObservationAgeMs,
+		maxCachedObservations,
+		maxElements,
+		maxTreeDepth,
+		maxTextLength,
+		rollbackEnabled
+	});
+}
+//#endregion
+//#region src/observe.ts
+/**
+* Observation cache and the staleness boundary. Every observation stores the
+* window's identity facts plus content hashes; before any action the executor
+* re-observes the window and this store compares. Identity, tree, or pixel
+* drift — or an expired observation — refuses the action, so the model must
+* re-observe instead of acting on a screen that changed.
+*
+* @module dsh-click/observe
+*/
+/**
+* Hash the observable state of one window into a stable observation id.
+*
+* @param snapshot - the snapshot facts.
+* @returns a hex observation id.
+*/
+function observationIdOf(snapshot) {
+	const material = JSON.stringify([
+		snapshot.windowId,
+		snapshot.processId,
+		snapshot.executablePath,
+		snapshot.title,
+		snapshot.className,
+		snapshot.rect,
+		snapshot.treeHash,
+		snapshot.shotHash
+	]);
+	return createHash("sha256").update(material).digest("hex").slice(0, 32);
+}
+/** Bounded LRU cache of observations, plus the staleness verdict logic. */
+var ObservationStore = class {
+	config;
+	entries = /* @__PURE__ */ new Map();
+	/** @param config - resolved caps (cache size, max age, pixel check). */
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Cache one observation and return it.
+	*
+	* @param snapshot - the snapshot facts it came from.
+	* @returns the stored record (id = hash of the state).
+	*/
+	record(snapshot) {
+		const record = {
+			id: observationIdOf(snapshot),
+			windowId: snapshot.windowId,
+			processId: snapshot.processId,
+			executablePath: snapshot.executablePath,
+			title: snapshot.title,
+			className: snapshot.className,
+			rect: { ...snapshot.rect },
+			treeHash: snapshot.treeHash,
+			shotHash: snapshot.shotHash,
+			elementCount: snapshot.elementCount,
+			observedAt: Date.now()
+		};
+		this.entries.delete(record.id);
+		this.entries.set(record.id, record);
+		while (this.entries.size > this.config.maxCachedObservations) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === void 0) break;
+			this.entries.delete(oldest);
+		}
+		return record;
+	}
+	/**
+	* Look one observation up by id.
+	*
+	* @param id - the observation id an action cites.
+	* @returns the record, or undefined when unknown or evicted.
+	*/
+	get(id) {
+		return this.entries.get(id);
+	}
+	/**
+	* Compare a fresh re-observation against the cited record. The verdict is
+	* `ok` only when identity (window/pid/exe/title/class/rect), the tree hash,
+	* and — when `staleCheckPixels` is on — the pixel hash all still match, and
+	* the record is not older than `maxObservationAgeMs`.
+	*
+	* @param record - the observation the action cites.
+	* @param fresh - the re-observation captured immediately before the action.
+	* @param now - wall-clock now (injectable for tests).
+	* @returns the verdict.
+	*/
+	verify(record, fresh, now = Date.now()) {
+		if (now - record.observedAt > this.config.maxObservationAgeMs) return {
+			ok: false,
+			code: "EXPIRED",
+			detail: `observation ${record.id} is older than ${this.config.maxObservationAgeMs} ms`
+		};
+		if (fresh.windowId !== record.windowId || fresh.processId !== record.processId || fresh.executablePath !== record.executablePath || fresh.title !== record.title || fresh.className !== record.className || fresh.rect.x !== record.rect.x || fresh.rect.y !== record.rect.y || fresh.rect.width !== record.rect.width || fresh.rect.height !== record.rect.height) return {
+			ok: false,
+			code: "STALE_IDENTITY",
+			detail: `window ${record.windowId} no longer matches observation ${record.id} (title/class/process or rect changed)`
+		};
+		if (fresh.treeHash !== record.treeHash) return {
+			ok: false,
+			code: "STALE_TREE",
+			detail: `the accessibility tree of window ${record.windowId} changed since observation ${record.id}`
+		};
+		if (this.config.staleCheckPixels && fresh.shotHash !== record.shotHash) return {
+			ok: false,
+			code: "STALE_PIXELS",
+			detail: `the pixels of window ${record.windowId} changed since observation ${record.id}`
+		};
+		return { ok: true };
+	}
+};
+//#endregion
+//#region src/version.ts
+/**
+* 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. */
+const VERSION = "0.1.0";
+/** The helper protocol revision; bump only on incompatible wire changes. */
+const HELPER_PROTOCOL_VERSION = 1;
+//#endregion
+//#region src/platform/runner.ts
+/**
+* The Windows backend: every operation spawns the native PowerShell helper
+* (`native/win32/dsh-click-helper.ps1`) through the harness's `ctx.subprocess`
+* seam. The request travels as JSON on stdin; the response is JSON on stdout
+* and is validated field-by-field at this wire boundary. Each call is
+* deadline-bounded (config `helperTimeoutMs`) and aborts with the caller's
+* signal (the subprocess service escalates to tree termination).
+*
+* @module dsh-click/platform/runner
+*/
+/** Locate the shipped helper script from either source or bundle layout. */
+function findHelperPath() {
+	const override = process.env["DSH_CLICK_HELPER"];
+	if (override !== void 0 && override !== "") return override;
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let depth = 0; depth < 8; depth += 1) {
+		const candidate = path.join(dir, "native", "win32", "dsh-click-helper.ps1");
+		if (existsSync(candidate)) return candidate;
+		dir = path.dirname(dir);
+	}
+	throw new DshClickError("cannot locate native/win32/dsh-click-helper.ps1 next to the package", "HELPER_MISSING");
+}
+/** Validate a helper rect at the wire boundary. */
+function expectRect(value, op) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new DshClickError(`helper "${op}" returned a malformed rect`, "BAD_HELPER_RESPONSE");
+	const record = value;
+	return {
+		x: expectNumber(record, "x", op),
+		y: expectNumber(record, "y", op),
+		width: expectNumber(record, "width", op),
+		height: expectNumber(record, "height", op)
+	};
+}
+/** Validate one helper window record. */
+function expectWindow(value, op) {
+	const record = expectRecordValue(value, op);
+	const processIdRaw = record["processId"];
+	const processId = typeof processIdRaw === "number" ? processIdRaw : null;
+	const executablePath = record["executablePath"];
+	if (executablePath !== null && typeof executablePath !== "string") throw new DshClickError(`helper "${op}" returned malformed executablePath`, "BAD_HELPER_RESPONSE");
+	return {
+		windowId: expectNumber(record, "windowId", op),
+		processId,
+		title: expectString(record, "title", op),
+		className: expectString(record, "className", op),
+		rect: expectRect(record["rect"], op),
+		executablePath,
+		visible: record["visible"] !== false
+	};
+}
+/** Validate one helper snapshot record. */
+function expectSnapshot(value, op) {
+	const record = expectRecordValue(value, op);
+	const executablePath = record["executablePath"];
+	if (executablePath !== null && typeof executablePath !== "string") throw new DshClickError(`helper "${op}" returned malformed executablePath`, "BAD_HELPER_RESPONSE");
+	return {
+		windowId: expectNumber(record, "windowId", op),
+		processId: expectNumber(record, "processId", op),
+		executablePath,
+		title: expectString(record, "title", op),
+		className: expectString(record, "className", op),
+		rect: expectRect(record["rect"], op),
+		foreground: record["foreground"] === true,
+		treeHash: expectString(record, "treeHash", op),
+		shotHash: expectString(record, "shotHash", op),
+		elementCount: expectNumber(record, "elementCount", op)
+	};
+}
+/** Validate one helper element record. */
+function expectElement(value, op) {
+	const record = expectRecordValue(value, op);
+	const patterns = record["patterns"];
+	if (!Array.isArray(patterns) || patterns.some((item) => typeof item !== "string")) throw new DshClickError(`helper "${op}" returned malformed element patterns`, "BAD_HELPER_RESPONSE");
+	return {
+		elementId: expectString(record, "elementId", op),
+		controlType: expectString(record, "controlType", op),
+		name: expectString(record, "name", op),
+		automationId: expectString(record, "automationId", op),
+		rect: expectRect(record["rect"], op),
+		enabled: record["enabled"] === true,
+		patterns
+	};
+}
+/** Validate one helper pixel hint. */
+function expectPixel(value, op) {
+	const record = expectRecordValue(value, op);
+	return {
+		label: expectString(record, "label", op),
+		x: expectNumber(record, "x", op),
+		y: expectNumber(record, "y", op),
+		color: expectString(record, "color", op)
+	};
+}
+/** Validate one helper action outcome. */
+function expectActionOutcome(value, op) {
+	const record = expectRecordValue(value, op);
+	const delivered = expectString(record, "delivered", op);
+	if (delivered !== "uia" && delivered !== "posted" && delivered !== "none") throw new DshClickError(`helper "${op}" returned an unknown delivered mechanism`, "BAD_HELPER_RESPONSE");
+	const restored = record["restored"];
+	if (restored !== void 0 && typeof restored !== "boolean") throw new DshClickError(`helper "${op}" returned a non-boolean restored flag`, "BAD_HELPER_RESPONSE");
+	const detail = record["detail"];
+	if (detail !== void 0 && typeof detail !== "string") throw new DshClickError(`helper "${op}" returned a non-string detail`, "BAD_HELPER_RESPONSE");
+	return {
+		windowId: expectNumber(record, "windowId", op),
+		action: expectString(record, "action", op),
+		delivered,
+		processBefore: expectProcessFacts(record["processBefore"], op),
+		processAfter: expectProcessFacts(record["processAfter"], op),
+		...restored !== void 0 ? { restored } : {},
+		...detail !== void 0 ? { detail } : {}
+	};
+}
+/** The Windows helper backend over `ctx.subprocess`. */
+var HelperBackend = class {
+	config;
+	subprocess;
+	/** Resolved powershell executable path, cached across calls. */
+	powershell;
+	available = true;
+	/** @param config - resolved limits for timeout and output size. */
+	/** @param subprocess - the subprocess service that runs the helper. */
+	constructor(config, subprocess) {
+		this.config = config;
+		this.subprocess = subprocess;
+	}
+	platform = "win32";
+	/** Run one helper operation and return its validated result payload. */
+	async invoke(op, args, signal) {
+		const request = {
+			protocol: 1,
+			pluginVersion: VERSION,
+			requestId: randomUUID(),
+			op,
+			args
+		};
+		const helperPath = findHelperPath();
+		const executable = await this.resolvePowershell();
+		const deadline = AbortSignal.timeout(this.config.helperTimeoutMs);
+		const fused = signal === void 0 ? deadline : AbortSignal.any([signal, deadline]);
+		const handle = this.subprocess.spawn({
+			argv: [
+				executable,
+				"-NoProfile",
+				"-NonInteractive",
+				"-ExecutionPolicy",
+				"Bypass",
+				"-File",
+				helperPath
+			],
+			cwd: process.cwd(),
+			stdio: {
+				stdin: { data: JSON.stringify(request) },
+				stdout: { maxBytes: this.config.maxHelperOutputBytes },
+				stderr: { maxBytes: 65536 }
+			},
+			graceMs: 5e3,
+			signal: fused
+		});
+		const outcome = await handle.done;
+		const stdoutText = handle.collected.stdout?.readFrom(0).text ?? "";
+		const stderrText = handle.collected.stderr?.readFrom(0).text ?? "";
+		if (outcome.exitCode !== 0) {
+			const tail = stderrText.trim().split(/\r?\n/u).slice(-3).join(" | ");
+			throw new DshClickError(`helper "${op}" failed (exit ${outcome.exitCode}${tail === "" ? "" : `: ${tail}`})`, "HELPER_FAILED");
+		}
+		let response;
+		try {
+			response = JSON.parse(stdoutText);
+		} catch {
+			throw new DshClickError(`helper "${op}" produced ${stdoutText.length === 0 ? "no stdout" : "malformed JSON on stdout"}`, "BAD_HELPER_RESPONSE");
+		}
+		if (typeof response !== "object" || response === null || typeof response.ok !== "boolean") throw new DshClickError(`helper "${op}" returned a malformed response envelope`, "BAD_HELPER_RESPONSE");
+		if (!response.ok) {
+			const error = response.error;
+			if (typeof error !== "object" || error === null || typeof error.code !== "string" || typeof error.message !== "string") throw new DshClickError(`helper "${op}" returned a malformed error envelope`, "BAD_HELPER_RESPONSE");
+			throw new DshClickError(`helper "${op}": ${error.message}`, error.code);
+		}
+		return response.result;
+	}
+	/** Resolve (and cache) the powershell executable through the subprocess seam. */
+	resolvePowershell() {
+		this.powershell ??= this.subprocess.resolveExecutable("powershell.exe").catch((error) => {
+			this.powershell = void 0;
+			throw new DshClickError(`cannot resolve powershell.exe for the desktop helper: ${error instanceof Error ? error.message : String(error)}`, "HELPER_MISSING");
+		});
+		return this.powershell;
+	}
+	async listWindows(signal) {
+		const result = await this.invoke("windows", {}, signal);
+		if (!Array.isArray(result)) throw new DshClickError("helper \"windows\" returned a non-array result", "BAD_HELPER_RESPONSE");
+		return result.map((item) => expectWindow(item, "windows"));
+	}
+	async shot(ref, maxSide, signal) {
+		const record = expectRecordValue(await this.invoke("shot", {
+			target: ref,
+			maxSide,
+			maxElements: this.config.maxElements,
+			maxDepth: this.config.maxTreeDepth
+		}, signal), "shot");
+		return {
+			pngBase64: expectString(record, "pngBase64", "shot"),
+			width: expectNumber(record, "width", "shot"),
+			height: expectNumber(record, "height", "shot"),
+			snapshot: expectSnapshot(record["snapshot"], "shot")
+		};
+	}
+	async tree(ref, maxElements, maxDepth, includePixels, signal) {
+		const record = expectRecordValue(await this.invoke("tree", {
+			target: ref,
+			maxElements,
+			maxDepth,
+			includePixels
+		}, signal), "tree");
+		const elements = record["elements"];
+		const pixels = record["pixels"];
+		if (!Array.isArray(elements) || !Array.isArray(pixels)) throw new DshClickError("helper \"tree\" returned malformed elements/pixels arrays", "BAD_HELPER_RESPONSE");
+		return {
+			snapshot: expectSnapshot(record["snapshot"], "tree"),
+			elements: elements.map((item) => expectElement(item, "tree")),
+			pixels: pixels.map((item) => expectPixel(item, "tree"))
+		};
+	}
+	async snapshot(windowId, signal) {
+		return expectSnapshot(await this.invoke("snapshot", {
+			windowId,
+			maxElements: this.config.maxElements,
+			maxDepth: this.config.maxTreeDepth
+		}, signal), "snapshot");
+	}
+	async click(request, focusFallback, signal) {
+		return expectActionOutcome(await this.invoke("click", {
+			request,
+			focusFallback
+		}, signal), "click");
+	}
+	async type(request, focusFallback, signal) {
+		return expectActionOutcome(await this.invoke("type", {
+			request,
+			focusFallback
+		}, signal), "type");
+	}
+	async scroll(request, focusFallback, signal) {
+		return expectActionOutcome(await this.invoke("scroll", {
+			request,
+			focusFallback
+		}, signal), "scroll");
+	}
+	async key(request, focusFallback, signal) {
+		return expectActionOutcome(await this.invoke("key", {
+			request,
+			focusFallback
+		}, signal), "key");
+	}
+	async apps(signal) {
+		const result = await this.invoke("apps", {}, signal);
+		if (!Array.isArray(result)) throw new DshClickError("helper \"apps\" returned a non-array result", "BAD_HELPER_RESPONSE");
+		return result.map((item) => {
+			const record = expectRecordValue(item, "apps");
+			const windows = record["windows"];
+			if (!Array.isArray(windows)) throw new DshClickError("helper \"apps\" returned malformed windows", "BAD_HELPER_RESPONSE");
+			const executablePath = record["executablePath"];
+			if (executablePath !== null && typeof executablePath !== "string") throw new DshClickError("helper \"apps\" returned malformed executablePath", "BAD_HELPER_RESPONSE");
+			return {
+				processId: expectNumber(record, "processId", "apps"),
+				name: expectString(record, "name", "apps"),
+				executablePath,
+				windows: windows.map((windowInfo) => expectWindow(windowInfo, "apps"))
+			};
+		});
+	}
+	async launch(name, args, signal) {
+		const record = expectRecordValue(await this.invoke("launch", {
+			name,
+			args
+		}, signal), "launch");
+		const executablePath = record["executablePath"];
+		if (executablePath !== null && typeof executablePath !== "string") throw new DshClickError("helper \"launch\" returned malformed executablePath", "BAD_HELPER_RESPONSE");
+		return {
+			processId: expectNumber(record, "processId", "launch"),
+			executablePath
+		};
+	}
+};
+//#endregion
+//#region src/platform/selection.ts
+/** A backend that cannot act: every operation fails closed with the given reason. */
+var UnavailableBackend = class {
+	platform;
+	reason;
+	/** @param platform - the platform id this stub stands in for. */
+	/** @param reason - model-readable reason why the backend cannot act. */
+	constructor(platform, reason) {
+		this.platform = platform;
+		this.reason = reason;
+	}
+	available = false;
+	get unavailableReason() {
+		return this.reason;
+	}
+	/** Throw the shared backend-unavailable failure. */
+	refuse() {
+		throw new DshClickError(`dsh-click backend unavailable on ${this.platform}: ${this.reason}`, "BACKEND_UNAVAILABLE");
+	}
+	listWindows() {
+		this.refuse();
+	}
+	shot() {
+		this.refuse();
+	}
+	tree() {
+		this.refuse();
+	}
+	snapshot() {
+		this.refuse();
+	}
+	click() {
+		this.refuse();
+	}
+	type() {
+		this.refuse();
+	}
+	scroll() {
+		this.refuse();
+	}
+	key() {
+		this.refuse();
+	}
+	apps() {
+		this.refuse();
+	}
+	launch() {
+		this.refuse();
+	}
+};
+/** The reserved-but-unimplemented backends, by platform. */
+const RESERVED_BACKENDS = {
+	darwin: "macOS backend is reserved but not implemented yet (Windows-first); only Windows can act today",
+	linux: "Linux backend is reserved but not implemented yet (Windows-first); only Windows can act today"
+};
+/**
+* Select the backend for this deployment. Windows needs `ctx.subprocess` to
+* run the native helper; every other platform is reserved and fails closed.
+*
+* @param ctx - the mounting context.
+* @param config - resolved plugin config (helper limits).
+* @returns the active backend (possibly unavailable).
+*/
+function createBackend(ctx, config) {
+	if (process.platform === "win32") {
+		const subprocess = ctx.get("subprocess");
+		if (subprocess === void 0) return new UnavailableBackend("win32", "ctx.subprocess is not mounted — required to run the native Windows helper");
+		return new HelperBackend(config, subprocess);
+	}
+	return new UnavailableBackend(process.platform, RESERVED_BACKENDS[process.platform] ?? "unsupported platform");
+}
+//#endregion
+//#region src/vision.ts
+/**
+* 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.
+*/
+async function sessionAcceptsImages(agent, ctx, signal) {
+	if (agent === void 0) return false;
+	const provider = agent.options.provider;
+	const model = agent.options.model;
+	if (provider === void 0 || model === void 0) return false;
+	const llm = ctx.get("llm");
+	if (llm === void 0) return false;
+	try {
+		return (await llm.resolveModelInfo(provider, model, signal)).inputModalities?.includes("image") ?? false;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/tools.ts
+/** Sanitize one snapshot into the model-visible window value. */
+function observedWindow(snapshot, maxTextLength) {
+	return {
+		windowId: snapshot.windowId,
+		processId: snapshot.processId,
+		title: sanitizeVisible(snapshot.title, maxTextLength),
+		className: sanitizeVisible(snapshot.className, maxTextLength),
+		executablePath: snapshot.executablePath === null ? null : sanitizePath(snapshot.executablePath, maxTextLength),
+		rect: { ...snapshot.rect },
+		foreground: snapshot.foreground
+	};
+}
+/** Sanitize one accessibility element into the model-visible form. */
+function observedElement(element, maxTextLength) {
+	return {
+		elementId: element.elementId,
+		controlType: sanitizeVisible(element.controlType, 64),
+		name: sanitizeVisible(element.name, maxTextLength),
+		automationId: sanitizeVisible(element.automationId, 64),
+		rect: element.rect,
+		enabled: element.enabled,
+		patterns: element.patterns
+	};
+}
+/** Sanitize one pixel hint into the model-visible form. */
+function observedPixel(pixel, maxTextLength) {
+	return {
+		label: sanitizeVisible(pixel.label, maxTextLength),
+		x: pixel.x,
+		y: pixel.y,
+		color: pixel.color
+	};
+}
+/** Sanitize one window listing entry. */
+function observedWindowInfo(info, maxTextLength) {
+	return {
+		windowId: info.windowId,
+		processId: info.processId,
+		title: sanitizeVisible(info.title, maxTextLength),
+		className: sanitizeVisible(info.className, maxTextLength),
+		rect: info.rect,
+		executablePath: info.executablePath === null ? null : sanitizePath(info.executablePath, maxTextLength),
+		visible: info.visible
+	};
+}
+/** Append the `dsh-click/observed` audit event; a failed append is swallowed. */
+function auditObservation(exec, event) {
+	const session = exec.agent?.session;
+	if (session === void 0) return;
+	try {
+		session.append(OBSERVED_EVENT, event);
+	} catch {}
+}
+/** One-line window identity for render text. */
+function windowLine(window) {
+	return `"${window.title}" (windowId ${window.windowId}, pid ${window.processId}, ${window.executablePath ?? "unknown executable"})`;
+}
+/** Refuse an unusable backend before any backend call. */
+function backendGuard(services) {
+	if (!services.backend.available) throw new Error(`dsh-click backend unavailable on ${services.backend.platform}: ${services.backend.unavailableReason ?? "unknown reason"}`);
+}
+/** Plain-text fallback description for a captured screenshot. */
+function shotDescription(window, width, height) {
+	return `${width}x${height} screenshot of ${windowLine(window)}; run screen_read on the same window for the structured element list and pixel positions.`;
+}
+/**
+* `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.
+*/
+function screenShotTool(services) {
+	const { ctx, config, backend, observations } = services;
+	return defineTool({
+		name: "screen_shot",
+		description: "Capture a screenshot of a desktop window (or the primary screen when no window is given). Returns an observationId that later actions cite in `basedOn`. When the current model accepts images the result includes the image; otherwise it includes a text description. Read-only: never needs approval.",
+		parameters: {
+			target: {
+				type: "object",
+				description: "Which window to capture (windowId, windowTitle, or processId); omitted = the foreground window.",
+				properties: {
+					windowId: {
+						type: "integer",
+						description: "Native window handle from app_list or screen_read."
+					},
+					windowTitle: {
+						type: "string",
+						description: "Visible window title (matched case-insensitively by substring)."
+					},
+					processId: {
+						type: "integer",
+						description: "Owning process id."
+					}
+				},
+				additionalProperties: false
+			},
+			maxSide: {
+				type: "integer",
+				description: "Longest side in pixels; larger captures are downscaled."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					ok: {
+						type: "boolean",
+						const: true
+					},
+					observationId: { type: "string" },
+					window: {
+						type: "object",
+						properties: {
+							windowId: { type: "integer" },
+							processId: { type: "integer" },
+							title: { type: "string" },
+							className: { type: "string" },
+							executablePath: { oneOf: [{ type: "string" }, { type: "null" }] },
+							rect: {
+								type: "object",
+								properties: {
+									x: { type: "integer" },
+									y: { type: "integer" },
+									width: { type: "integer" },
+									height: { type: "integer" }
+								},
+								additionalProperties: false
+							},
+							foreground: { type: "boolean" }
+						},
+						additionalProperties: false
+					},
+					image: {
+						type: "object",
+						properties: {
+							attachmentId: { type: "string" },
+							mediaType: { type: "string" },
+							bytes: { type: "integer" },
+							width: { type: "integer" },
+							height: { type: "integer" },
+							name: { type: "string" }
+						},
+						additionalProperties: false
+					},
+					description: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render(_args, value) {
+				const result = value;
+				const blocks = [{
+					type: "text",
+					text: `Screenshot of ${windowLine(result.window)} captured.\nobservationId: ${result.observationId}\n${result.image === void 0 ? result.description : "Image attached; cite this observationId in later actions."}`
+				}];
+				if (result.image !== void 0) blocks.push({
+					type: "image",
+					attachment: result.image
+				});
+				return blocks;
+			}
+		},
+		timeoutMs: config.helperTimeoutMs + 15e3,
+		async execute(args, exec) {
+			backendGuard(services);
+			const target = args.target ?? {};
+			const requestedSide = args.maxSide;
+			const maxSide = requestedSide === void 0 ? config.maxScreenshotSide : Math.min(requestedSide, config.maxScreenshotSide);
+			const shot = await backend.shot(target, maxSide, exec.signal);
+			const sanitized = observedWindow(shot.snapshot, config.maxTextLength);
+			const record = observations.record(shot.snapshot);
+			const description = shotDescription(sanitized, shot.width, shot.height);
+			let image;
+			const attachments = ctx.get("attachments");
+			if (config.imageMode !== "text" && attachments !== void 0 && await sessionAcceptsImages(exec.agent, ctx, exec.signal)) try {
+				image = await attachments.saveImage({
+					data: Buffer.from(shot.pngBase64, "base64"),
+					mediaType: "image/png",
+					name: `dsh-click-${record.id.slice(0, 12)}.png`
+				});
+			} catch {
+				image = void 0;
+			}
+			auditObservation(exec, {
+				observationId: record.id,
+				windowId: shot.snapshot.windowId,
+				processId: shot.snapshot.processId,
+				executablePath: sanitized.executablePath,
+				windowTitle: sanitized.title,
+				elementCount: shot.snapshot.elementCount,
+				...image !== void 0 ? { image: {
+					attachmentId: image.attachmentId,
+					mediaType: image.mediaType,
+					bytes: image.bytes,
+					width: image.width,
+					height: image.height
+				} } : {}
+			});
+			return {
+				ok: true,
+				observationId: record.id,
+				window: sanitized,
+				...image !== void 0 ? { image } : {},
+				description
+			};
+		}
+	});
+}
+/**
+* `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.
+*/
+function screenReadTool(services) {
+	const { config, backend, observations } = services;
+	return defineTool({
+		name: "screen_read",
+		description: "Read a desktop window as structured text: its accessibility tree (element ids, types, names, rectangles, supported patterns) plus pixel-location hints with colors. Returns an observationId that later actions cite in `basedOn`; elements are addressed by their elementId. Read-only: never needs approval.",
+		parameters: {
+			target: {
+				type: "object",
+				description: "Which window to read (windowId, windowTitle, or processId); omitted = the foreground window.",
+				properties: {
+					windowId: {
+						type: "integer",
+						description: "Native window handle from app_list or screen_read."
+					},
+					windowTitle: {
+						type: "string",
+						description: "Visible window title (matched case-insensitively by substring)."
+					},
+					processId: {
+						type: "integer",
+						description: "Owning process id."
+					}
+				},
+				additionalProperties: false
+			},
+			includePixels: {
+				type: "boolean",
+				description: "Include pixel-location hints (default true)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					ok: {
+						type: "boolean",
+						const: true
+					},
+					observationId: { type: "string" },
+					window: {
+						type: "object",
+						properties: {
+							windowId: { type: "integer" },
+							processId: { type: "integer" },
+							title: { type: "string" },
+							className: { type: "string" },
+							executablePath: { oneOf: [{ type: "string" }, { type: "null" }] },
+							rect: {
+								type: "object",
+								properties: {
+									x: { type: "integer" },
+									y: { type: "integer" },
+									width: { type: "integer" },
+									height: { type: "integer" }
+								},
+								additionalProperties: false
+							},
+							foreground: { type: "boolean" }
+						},
+						additionalProperties: false
+					},
+					elements: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								elementId: { type: "string" },
+								controlType: { type: "string" },
+								name: { type: "string" },
+								automationId: { type: "string" },
+								rect: {
+									type: "object",
+									properties: {
+										x: { type: "integer" },
+										y: { type: "integer" },
+										width: { type: "integer" },
+										height: { type: "integer" }
+									},
+									additionalProperties: false
+								},
+								enabled: { type: "boolean" },
+								patterns: {
+									type: "array",
+									items: { type: "string" }
+								}
+							},
+							additionalProperties: false
+						}
+					},
+					pixels: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								label: { type: "string" },
+								x: { type: "integer" },
+								y: { type: "integer" },
+								color: { type: "string" }
+							},
+							additionalProperties: false
+						}
+					}
+				},
+				additionalProperties: false
+			},
+			render(_args, value) {
+				const result = value;
+				const lines = [
+					`Window read: ${windowLine(result.window)}`,
+					`observationId: ${result.observationId}`,
+					`${result.elements.length} element(s):`
+				];
+				for (const element of result.elements) lines.push(`- [${element.elementId}] ${element.controlType} ${JSON.stringify(element.name)} at (${element.rect.x}, ${element.rect.y}) ${element.rect.width}x${element.rect.height}${element.enabled ? "" : " (disabled)"}${element.patterns.length > 0 ? ` patterns: ${element.patterns.join(",")}` : ""}`);
+				if (result.pixels.length > 0) {
+					lines.push(`${result.pixels.length} pixel hint(s):`);
+					for (const pixel of result.pixels) lines.push(`- ${pixel.label} at (${pixel.x}, ${pixel.y}) ${pixel.color}`);
+				}
+				lines.push("Actions (click/type/scroll/key) must cite this observationId in `basedOn` and address elements by elementId.");
+				return [{
+					type: "text",
+					text: lines.join("\n")
+				}];
+			}
+		},
+		timeoutMs: config.helperTimeoutMs + 15e3,
+		async execute(args, exec) {
+			backendGuard(services);
+			const parsed = args;
+			const tree = await backend.tree(parsed.target ?? {}, config.maxElements, config.maxTreeDepth, parsed.includePixels ?? true, exec.signal);
+			const sanitized = observedWindow(tree.snapshot, config.maxTextLength);
+			const record = observations.record(tree.snapshot);
+			auditObservation(exec, {
+				observationId: record.id,
+				windowId: tree.snapshot.windowId,
+				processId: tree.snapshot.processId,
+				executablePath: sanitized.executablePath,
+				windowTitle: sanitized.title,
+				elementCount: tree.elements.length
+			});
+			return {
+				ok: true,
+				observationId: record.id,
+				window: sanitized,
+				elements: tree.elements.map((element) => observedElement(element, config.maxTextLength)),
+				pixels: tree.pixels.map((pixel) => observedPixel(pixel, config.maxTextLength))
+			};
+		}
+	});
+}
+/** The shared window-action output schema (click/scroll/key). */
+function actionOutputSchema(withRestored) {
+	return {
+		type: "object",
+		properties: {
+			ok: {
+				type: "boolean",
+				const: true
+			},
+			windowId: { type: "integer" },
+			delivered: {
+				type: "string",
+				enum: [
+					"uia",
+					"posted",
+					"none"
+				]
+			},
+			process: {
+				type: "object",
+				properties: {
+					before: {
+						type: "object",
+						properties: {
+							pid: { type: "integer" },
+							executablePath: { oneOf: [{ type: "string" }, { type: "null" }] }
+						},
+						additionalProperties: false
+					},
+					after: {
+						type: "object",
+						properties: {
+							pid: { type: "integer" },
+							executablePath: { oneOf: [{ type: "string" }, { type: "null" }] }
+						},
+						additionalProperties: false
+					}
+				},
+				additionalProperties: false
+			},
+			detail: { type: "string" },
+			...withRestored ? { restored: { type: "boolean" } } : {}
+		},
+		additionalProperties: false
+	};
+}
+/** The cited-observation parameters shared by the four action tools. */
+const basedOnParameters = { basedOn: {
+	type: "object",
+	description: "The observation this action is based on; the action fails if the screen changed since that observation.",
+	properties: {
+		observationId: {
+			type: "string",
+			description: "observationId returned by screen_shot or screen_read.",
+			required: true
+		},
+		windowId: {
+			type: "integer",
+			description: "windowId of the observed window.",
+			required: true
+		}
+	},
+	additionalProperties: false,
+	required: true
+} };
+/** One-line action summary for render text. */
+function actionLine(toolName, value) {
+	const before = value.process.before;
+	const after = value.process.after;
+	return `${toolName} delivered via ${value.delivered} to window ${value.windowId}; process pid ${before.pid} → ${after.pid}${value.restored === void 0 ? "" : value.restored ? " (original text restored)" : " (text restore unavailable)"}.`;
+}
+/**
+* `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.
+*/
+function clickTool(services) {
+	const { config, backend, actions } = services;
+	return defineTool({
+		name: "click",
+		description: "Click an element or a coordinate inside an observed desktop window. Requires `basedOn` (a fresh observationId from screen_shot/screen_read); the call fails if the screen changed since that observation. Never steals foreground focus. Requires approval unless the window is allowlisted.",
+		parameters: {
+			...basedOnParameters,
+			target: {
+				type: "object",
+				description: "Exactly one of elementId or (x, y) — screen coordinates.",
+				properties: {
+					elementId: {
+						type: "string",
+						description: "Element id from screen_read."
+					},
+					x: {
+						type: "integer",
+						description: "Screen x coordinate."
+					},
+					y: {
+						type: "integer",
+						description: "Screen y coordinate."
+					}
+				},
+				additionalProperties: false,
+				required: true
+			},
+			button: {
+				type: "string",
+				enum: ["left", "right"],
+				description: "Mouse button (default left)."
+			}
+		},
+		output: {
+			schema: actionOutputSchema(false),
+			render(_args, value) {
+				return [{
+					type: "text",
+					text: actionLine("click", value)
+				}];
+			}
+		},
+		timeoutMs: config.helperTimeoutMs + 15e3,
+		async execute(args, exec) {
+			backendGuard(services);
+			const parsed = args;
+			const target = parsed.target;
+			const byElement = target.elementId !== void 0;
+			if (byElement === (target.x !== void 0 && target.y !== void 0)) throw new Error("click target must name exactly one of elementId or (x, y)");
+			const outcome = await actions.perform("click", exec, parsed.basedOn.observationId, parsed.basedOn.windowId, (focusFallback) => backend.click({
+				windowId: parsed.basedOn.windowId,
+				...byElement ? { elementId: target.elementId } : {
+					x: target.x,
+					y: target.y
+				},
+				button: parsed.button ?? "left"
+			}, focusFallback, exec.signal));
+			return {
+				ok: true,
+				windowId: outcome.windowId,
+				delivered: outcome.delivered,
+				process: {
+					before: outcome.processBefore,
+					after: outcome.processAfter
+				},
+				...outcome.detail !== void 0 ? { detail: outcome.detail } : {}
+			};
+		}
+	});
+}
+/**
+* `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.
+*/
+function typeTool(services) {
+	const { config, backend, actions } = services;
+	return defineTool({
+		name: "type",
+		description: "Type text into an editable element of an observed desktop window (addressed by elementId from screen_read; the element must expose a value pattern). Requires `basedOn`; fails if the screen changed since that observation. Never steals foreground focus. Requires approval unless the window is allowlisted. On failure the previous control text is restored when rollback is enabled.",
+		parameters: {
+			...basedOnParameters,
+			elementId: {
+				type: "string",
+				description: "Editable element id from screen_read.",
+				required: true
+			},
+			text: {
+				type: "string",
+				description: "The exact text to type (up to 10000 characters).",
+				required: true
+			}
+		},
+		output: {
+			schema: actionOutputSchema(true),
+			render(_args, value) {
+				return [{
+					type: "text",
+					text: actionLine("type", value)
+				}];
+			}
+		},
+		timeoutMs: config.helperTimeoutMs + 15e3,
+		async execute(args, exec) {
+			backendGuard(services);
+			const parsed = args;
+			if (parsed.text.length > 1e4) throw new Error("type text must be at most 10000 characters");
+			const outcome = await actions.perform("type", exec, parsed.basedOn.observationId, parsed.basedOn.windowId, (focusFallback) => backend.type({
+				windowId: parsed.basedOn.windowId,
+				elementId: parsed.elementId,
+				text: parsed.text,
+				rollback: config.rollbackEnabled
+			}, focusFallback, exec.signal));
+			return {
+				ok: true,
+				windowId: outcome.windowId,
+				delivered: outcome.delivered,
+				process: {
+					before: outcome.processBefore,
+					after: outcome.processAfter
+				},
+				restored: outcome.restored ?? false,
+				...outcome.detail !== void 0 ? { detail: outcome.detail } : {}
+			};
+		}
+	});
+}
+/**
+* `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.
+*/
+function scrollTool(services) {
+	const { config, backend, actions } = services;
+	return defineTool({
+		name: "scroll",
+		description: "Scroll an element (by elementId) or the observed window. Requires `basedOn`; fails if the screen changed since that observation. Never steals foreground focus. Requires approval unless the window is allowlisted.",
+		parameters: {
+			...basedOnParameters,
+			elementId: {
+				type: "string",
+				description: "Optional scrollable element id from screen_read; omitted = scroll the window itself."
+			},
+			direction: {
+				type: "string",
+				enum: [
+					"up",
+					"down",
+					"page-up",
+					"page-down"
+				],
+				description: "Scroll direction.",
+				required: true
+			},
+			amount: {
+				type: "integer",
+				description: "Number of increments (default 3)."
+			}
+		},
+		output: {
+			schema: actionOutputSchema(false),
+			render(_args, value) {
+				return [{
+					type: "text",
+					text: actionLine("scroll", value)
+				}];
+			}
+		},
+		timeoutMs: config.helperTimeoutMs + 15e3,
+		async execute(args, exec) {
+			backendGuard(services);
+			const parsed = args;
+			const amount = parsed.amount ?? 3;
+			if (!Number.isInteger(amount) || amount < 1) throw new Error("scroll amount must be a positive integer");
+			const outcome = await actions.perform("scroll", exec, parsed.basedOn.observationId, parsed.basedOn.windowId, (focusFallback) => backend.scroll({
+				windowId: parsed.basedOn.windowId,
+				...parsed.elementId !== void 0 ? { elementId: parsed.elementId } : {},
+				direction: parsed.direction,
+				amount
+			}, focusFallback, exec.signal));
+			return {
+				ok: true,
+				windowId: outcome.windowId,
+				delivered: outcome.delivered,
+				process: {
+					before: outcome.processBefore,
+					after: outcome.processAfter
+				},
+				...outcome.detail !== void 0 ? { detail: outcome.detail } : {}
+			};
+		}
+	});
+}
+/**
+* `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.
+*/
+function keyTool(services) {
+	const { config, backend, actions } = services;
+	return defineTool({
+		name: "key",
+		description: "Send a key combination (e.g. \"Ctrl+S\", \"Enter\", \"Alt+F4\") to an observed desktop window via posted window messages. Requires `basedOn`; fails if the screen changed since that observation. Never steals foreground focus — applications that ignore posted input will not react; prefer click/type for those. Requires approval unless the window is allowlisted.",
+		parameters: {
+			...basedOnParameters,
+			keys: {
+				type: "string",
+				description: "Key combination, e.g. \"Ctrl+S\" or \"Enter\".",
+				required: true
+			}
+		},
+		output: {
+			schema: actionOutputSchema(false),
+			render(_args, value) {
+				return [{
+					type: "text",
+					text: actionLine("key", value)
+				}];
+			}
+		},
+		timeoutMs: config.helperTimeoutMs + 15e3,
+		async execute(args, exec) {
+			backendGuard(services);
+			const parsed = args;
+			if (parsed.keys.trim() === "") throw new Error("keys must not be empty");
+			const outcome = await actions.perform("key", exec, parsed.basedOn.observationId, parsed.basedOn.windowId, (focusFallback) => backend.key({
+				windowId: parsed.basedOn.windowId,
+				keys: parsed.keys.trim()
+			}, focusFallback, exec.signal));
+			return {
+				ok: true,
+				windowId: outcome.windowId,
+				delivered: outcome.delivered,
+				process: {
+					before: outcome.processBefore,
+					after: outcome.processAfter
+				},
+				...outcome.detail !== void 0 ? { detail: outcome.detail } : {}
+			};
+		}
+	});
+}
+/**
+* `app_list` — enumerate running desktop applications and their windows.
+* Read-only: never needs approval.
+*
+* @param services - runtime services.
+* @returns the tool definition.
+*/
+function appListTool(services) {
+	const { config, backend } = services;
+	return defineTool({
+		name: "app_list",
+		description: "List running desktop applications and their visible windows (windowId, title, process id, executable path). Read-only: never needs approval. Use the returned windowIds as screen_shot/screen_read targets.",
+		parameters: {},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					ok: {
+						type: "boolean",
+						const: true
+					},
+					apps: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								processId: { type: "integer" },
+								name: { type: "string" },
+								executablePath: { oneOf: [{ type: "string" }, { type: "null" }] },
+								windows: {
+									type: "array",
+									items: {
+										type: "object",
+										properties: {
+											windowId: { type: "integer" },
+											processId: { oneOf: [{ type: "integer" }, { type: "null" }] },
+											title: { type: "string" },
+											className: { type: "string" },
+											rect: {
+												type: "object",
+												properties: {
+													x: { type: "integer" },
+													y: { type: "integer" },
+													width: { type: "integer" },
+													height: { type: "integer" }
+												},
+												additionalProperties: false
+											},
+											executablePath: { oneOf: [{ type: "string" }, { type: "null" }] },
+											visible: { type: "boolean" }
+										},
+										additionalProperties: false
+									}
+								}
+							},
+							additionalProperties: false
+						}
+					}
+				},
+				additionalProperties: false
+			},
+			render(_args, value) {
+				const result = value;
+				const lines = [`${result.apps.length} running application(s) with windows:`];
+				for (const app of result.apps) {
+					lines.push(`- ${app.name} (pid ${app.processId}, ${app.executablePath ?? "unknown executable"})`);
+					for (const window of app.windows) lines.push(`  - [windowId ${window.windowId}] ${JSON.stringify(window.title)} at (${window.rect.x}, ${window.rect.y}) ${window.rect.width}x${window.rect.height}`);
+				}
+				return [{
+					type: "text",
+					text: lines.join("\n")
+				}];
+			}
+		},
+		timeoutMs: config.helperTimeoutMs + 15e3,
+		async execute(_args, exec) {
+			backendGuard(services);
+			return {
+				ok: true,
+				apps: (await backend.apps(exec.signal)).map((app) => ({
+					processId: app.processId,
+					name: sanitizeVisible(app.name, config.maxTextLength),
+					executablePath: app.executablePath === null ? null : sanitizePath(app.executablePath, config.maxTextLength),
+					windows: app.windows.map((window) => observedWindowInfo(window, config.maxTextLength))
+				}))
+			};
+		}
+	});
+}
+/**
+* `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.
+*/
+function appLaunchTool(services) {
+	const { config, actions } = services;
+	return defineTool({
+		name: "app_launch",
+		description: "Launch a desktop application by name (e.g. \"notepad\") or executable path, with optional arguments. Requires approval unless requireApproval is off or the name/path is allowlisted. Returns the new process identity.",
+		parameters: {
+			name: {
+				type: "string",
+				description: "Application name (resolved through the executable search path) or full path.",
+				required: true
+			},
+			args: {
+				type: "array",
+				items: { type: "string" },
+				description: "Optional command-line arguments."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					ok: {
+						type: "boolean",
+						const: true
+					},
+					processId: { type: "integer" },
+					executablePath: { oneOf: [{ type: "string" }, { type: "null" }] }
+				},
+				additionalProperties: false
+			},
+			render(_args, value) {
+				const result = value;
+				return [{
+					type: "text",
+					text: `Launched: pid ${result.processId} (${result.executablePath ?? "unknown executable"}).`
+				}];
+			}
+		},
+		timeoutMs: config.helperTimeoutMs + 15e3,
+		async execute(args, exec) {
+			backendGuard(services);
+			const parsed = args;
+			if (parsed.name.trim() === "") throw new Error("app_launch name must not be empty");
+			const outcome = await actions.launch(exec, parsed.name.trim(), parsed.args ?? []);
+			return {
+				ok: true,
+				processId: outcome.processId,
+				executablePath: outcome.executablePath === null ? null : sanitizePath(outcome.executablePath, config.maxTextLength)
+			};
+		}
+	});
+}
+/** Every tool definition, in registration order. */
+function allTools(services) {
+	return [
+		screenShotTool(services),
+		screenReadTool(services),
+		clickTool(services),
+		typeTool(services),
+		scrollTool(services),
+		keyTool(services),
+		appListTool(services),
+		appLaunchTool(services)
+	];
+}
+//#endregion
+//#region src/index.ts
+const name = "dsh-click";
+/** Hard services: the tool registry every contribution lands in. */
+const inject = ["tools"];
+/**
+* Mount the plugin: resolve config, select the platform backend, and register
+* every tool through `ctx.tools.register` (each registration is an effect
+* whose disposer removes exactly that tool on stop/HMR).
+*
+* @param ctx - context carrying the tools registry.
+* @param config - raw loader config; defaults applied through {@link resolveConfig}.
+*/
+function apply(ctx, config) {
+	const resolved = resolveConfig(config);
+	const backend = ctx.get("dsh-click/backend") ?? createBackend(ctx, resolved);
+	const observations = new ObservationStore(resolved);
+	const services = {
+		ctx,
+		config: resolved,
+		backend,
+		observations,
+		actions: new ActionExecutor({
+			ctx,
+			config: resolved,
+			backend,
+			observations
+		})
+	};
+	for (const tool of allTools(services)) ctx.effect(() => ctx.tools.register(tool), `dsh-click: ${tool.name} tool`);
+}
+//#endregion
+export { ACTION_EVENT, ActionExecutor, Config, DshClickError, HELPER_PROTOCOL_VERSION, HelperBackend, OBSERVED_EVENT, ObservationStore, UnavailableBackend, VERSION, allTools, apply, createBackend, inject, name, observationIdOf, redactSensitive, resolveConfig, sanitizePath, sanitizeText, sanitizeVisible };