@aexol/spectral 0.9.212 → 0.9.215

package/dist/extensions/desktop-control/macos.js

@@ -0,0 +1,382 @@
+/**
+ * macOS adapter for desktop-control.
+ *
+ * Mouse/keyboard injection via JXA (`osascript -l JavaScript`) using the ObjC
+ * bridge to CoreGraphics: CGEventCreateMouseEvent + CGEventPost,
+ * CGEventCreateKeyboardEvent for keys, CGEventCreateScrollWheelEvent for
+ * scrolling. Numeric enum constants are inlined (kCGEventLeftMouseDown = 1,
+ * kCGHIDEventTap = 0, ...) so the script never depends on enum bridging.
+ *
+ * type_text uses CGEvent key events for ASCII; any non-ASCII text falls back
+ * to System Events `keystroke` via AppleScript (handles unicode).
+ *
+ * Every JXA action ends with a CGEventGetLocation read-back (cursor position)
+ * that the safety layer appends to the tool result — CGEventPost itself never
+ * errors, so the read-back is how silent injection failures surface.
+ *
+ * checkPermissions also preflights Screen Recording via
+ * CGPreflightScreenCaptureAccess (read-only) so mutating actions fail with
+ * fix instructions BEFORE the BEFORE screenshot would silently capture the
+ * desktop wallpaper.
+ *
+ * Accessibility (TCC) check + frontmost app query go through a read-only
+ * System Events query: `name of first application process whose frontmost is
+ * true`. When accessibility is missing, osascript fails with
+ * "osascript is not allowed assistive access" and we return guidance pointing
+ * to System Settings > Privacy & Security > Accessibility.
+ */
+import { execFile } from "node:child_process";
+import { unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { MACOS_KEYCODES, MACOS_MODIFIER_FLAGS, MACOS_SHIFTED, isModifierToken, } from "./keys.js";
+const TIMEOUT_MS = 10_000;
+const JXA_PRELUDE = `ObjC.import('CoreGraphics');
+var HID = 0; // kCGHIDEventTap
+var EVT_MOVED = 5, L_DOWN = 1, L_UP = 2, R_DOWN = 3, R_UP = 4, M_DOWN = 25, M_UP = 26;
+var DRAG = { 1: 6, 2: 7, 25: 27 }; // down event type -> dragged event type
+var FLAG_SHIFT = 131072, FLAG_CTRL = 262144, FLAG_ALT = 524288, FLAG_CMD = 1048576;
+var UNIT_LINE = 1; // kCGScrollEventUnitLine
+var CLICK_STATE = 1; // kCGMouseEventClickState field id
+function mouseEvent(type, x, y, btn, clickState) {
+  var ev = $.CGEventCreateMouseEvent($(), type, { x: x, y: y }, btn);
+  if (clickState > 1) { $.CGEventSetIntegerValueField(ev, CLICK_STATE, clickState); }
+  return ev;
+}
+function keyEvent(code, isDown, flags) {
+  var ev = $.CGEventCreateKeyboardEvent($(), code, isDown);
+  if (flags) { $.CGEventSetFlags(ev, flags); }
+  return ev;
+}
+function post(ev) { $.CGEventPost(HID, ev); }
+function pointer() {
+  var p = $.CGEventGetLocation($()); // NULL event -> merged HID state = current cursor location
+  var x = Math.round(p.x), y = Math.round(p.y);
+  return (isNaN(x) || isNaN(y)) ? "" : x + "," + y; // "" -> caller skips the read-back
+}`;
+const MOUSE_BTN = {
+    left: { btn: 0, down: "L_DOWN", up: "L_UP" },
+    right: { btn: 1, down: "R_DOWN", up: "R_UP" },
+    middle: { btn: 2, down: "M_DOWN", up: "M_UP" },
+};
+const DRAG_STEPS = 10;
+// ---------------------------------------------------------------------------
+// JXA builders (exported for unit tests — pure, never executed by tests)
+// ---------------------------------------------------------------------------
+export function buildMouseJxa(action) {
+    switch (action.kind) {
+        case "mouse_move":
+            return `${JXA_PRELUDE}
+post(mouseEvent(EVT_MOVED, ${action.x}, ${action.y}, 0, 0));
+pointer();`;
+        case "mouse_click": {
+            const b = MOUSE_BTN[action.button];
+            return `${JXA_PRELUDE}
+post(mouseEvent(EVT_MOVED, ${action.x}, ${action.y}, ${b.btn}, 0));
+for (var i = 1; i <= ${action.clickCount}; i++) {
+  post(mouseEvent(${b.down}, ${action.x}, ${action.y}, ${b.btn}, i));
+  post(mouseEvent(${b.up}, ${action.x}, ${action.y}, ${b.btn}, i));
+}
+pointer();`;
+        }
+        case "mouse_drag": {
+            const b = MOUSE_BTN.left;
+            return `${JXA_PRELUDE}
+post(mouseEvent(EVT_MOVED, ${action.fromX}, ${action.fromY}, ${b.btn}, 0));
+post(mouseEvent(${b.down}, ${action.fromX}, ${action.fromY}, ${b.btn}, 1));
+for (var i = 1; i <= ${DRAG_STEPS}; i++) {
+  var t = i / ${DRAG_STEPS};
+  post(mouseEvent(DRAG[${b.down}], ${action.fromX} + (${action.toX} - ${action.fromX}) * t, ${action.fromY} + (${action.toY} - ${action.fromY}) * t, ${b.btn}, 1));
+}
+post(mouseEvent(${b.up}, ${action.toX}, ${action.toY}, ${b.btn}, 1));
+pointer();`;
+        }
+        case "scroll": {
+            // CG positive wheel values scroll UP, so invert dy; dx positive = right.
+            // When x/y are given the cursor is moved there first, so the wheel lands
+            // under the requested coordinates instead of wherever the pointer was.
+            const wheel1 = -action.dy;
+            const wheel2 = action.dx;
+            const move = action.x !== undefined
+                ? `post(mouseEvent(EVT_MOVED, ${action.x}, ${action.y}, 0, 0));\n`
+                : "";
+            return `${JXA_PRELUDE}
+${move}var ev = $.CGEventCreateScrollWheelEvent($(), UNIT_LINE, 2, ${wheel1}, ${wheel2});
+post(ev);
+pointer();`;
+        }
+    }
+}
+/** Build the key sequence [[keycode, shift], ...] for ASCII text; null when any char is unmappable. */
+export function buildAsciiTypeSeq(text) {
+    const seq = [];
+    for (const ch of text) {
+        if (ch === "\n")
+            seq.push([MACOS_KEYCODES.return, false]);
+        else if (ch === "\t")
+            seq.push([MACOS_KEYCODES.tab, false]);
+        else if (ch === " ")
+            seq.push([MACOS_KEYCODES.space, false]);
+        else if (ch in MACOS_SHIFTED)
+            seq.push([MACOS_KEYCODES[MACOS_SHIFTED[ch]], true]);
+        else if (ch in MACOS_KEYCODES && !isModifierToken(ch))
+            seq.push([MACOS_KEYCODES[ch], false]);
+        else
+            return null; // non-ASCII or unknown -> caller falls back to AppleScript keystroke
+    }
+    return seq;
+}
+export function buildTypeJxa(seq) {
+    const rows = seq.map(([code, shift]) => `[${code},${shift ? "true" : "false"}]`).join(",");
+    return `${JXA_PRELUDE}
+var seq = [${rows}];
+for (var i = 0; i < seq.length; i++) {
+  var f = seq[i][1] ? FLAG_SHIFT : 0;
+  post(keyEvent(seq[i][0], true, f));
+  post(keyEvent(seq[i][0], false, f));
+}
+pointer();`;
+}
+/** Tokens: leading modifiers + exactly one key. Throws on unsupported keys. */
+export function resolveChordTokens(tokens) {
+    const flags = tokens.slice(0, -1).reduce((acc, t) => {
+        if (!isModifierToken(t))
+            throw new Error(`unsupported hotkey token "${t}" (expected modifier)`);
+        return acc | MACOS_MODIFIER_FLAGS[t];
+    }, 0);
+    const keyName = tokens[tokens.length - 1];
+    const code = MACOS_KEYCODES[keyName];
+    if (code === undefined) {
+        throw new Error(`unsupported key "${keyName}" for macOS CGEvent injection (supported: letters, digits, f1-f12, return/tab/space/escape/backspace/delete, arrows, home/end/pageup/pagedown, punctuation)`);
+    }
+    return { key: code, flags };
+}
+export function buildHotkeyJxa(key, flags) {
+    return `${JXA_PRELUDE}
+var codes = [${key}];
+var flags = ${flags};
+for (var i = 0; i < codes.length; i++) { post(keyEvent(codes[i], true, flags)); }
+for (var i = codes.length - 1; i >= 0; i--) { post(keyEvent(codes[i], false, flags)); }
+pointer();`;
+}
+// ---------------------------------------------------------------------------
+// AppleScript builders (System Events — unicode typing + window focus)
+// ---------------------------------------------------------------------------
+function escapeAppleScriptString(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/** System Events keystroke; \n -> `return`, \t -> `tab` via concatenation. */
+export function buildKeystrokeAppleScript(text) {
+    const segments = text.split("\n").map((seg) => escapeAppleScriptString(seg)
+        .split("\t")
+        .map((t) => `"${t}"`)
+        .join(" & tab & "));
+    const expr = segments.map((s) => (s === '""' ? '""' : s)).join(" & return & ");
+    return `tell application "System Events"
+\tkeystroke ${expr}
+end tell`;
+}
+export function buildFocusAppleScript(owner, title) {
+    const ownerEscaped = escapeAppleScriptString(owner);
+    if (!title) {
+        return `tell application "System Events"
+\tset frontmost of (first application process whose name is "${ownerEscaped}") to true
+end tell`;
+    }
+    // System Events windows carry no CGWindowNumber — match the concrete window
+    // by title (exact, then case-insensitive substring), AXRaise it, and keep
+    // "set frontmost" as the always-available fallback. A missing process fails
+    // with a readable error instead of a bare AppleScript -1728.
+    const titleEscaped = escapeAppleScriptString(title);
+    return `tell application "System Events"
+\tset procs to (application processes whose name is "${ownerEscaped}")
+\tif (count of procs) is 0 then error "no application process named \\"${ownerEscaped}\\" - is it running? (list_windows shows live windows)"
+\ttell item 1 of procs
+\t\tset frontmost to true
+\t\tset matches to (windows whose name is "${titleEscaped}")
+\t\tif (count of matches) is 0 then set matches to (windows whose name contains "${titleEscaped}")
+\t\tif (count of matches) > 0 then perform action "AXRaise" of item 1 of matches
+\tend tell
+end tell`;
+}
+// ---------------------------------------------------------------------------
+// Runners + adapter
+// ---------------------------------------------------------------------------
+function runOsa(args) {
+    return new Promise((resolve, reject) => {
+        execFile("osascript", args, { timeout: TIMEOUT_MS }, (err, stdout, stderr) => {
+            if (err) {
+                const tail = String(stderr || err.message).trim().split("\n").pop() ?? err.message;
+                reject(new Error(`osascript: ${tail}`));
+            }
+            else {
+                resolve(stdout);
+            }
+        });
+    });
+}
+/** Runs the JXA script from a 0600 temp file; returns trimmed stdout (post-action read-back) or null. */
+async function runJxa(script) {
+    const path = join(tmpdir(), `desktop-control-${randomUUID()}.jxa`);
+    // 0600: temp scripts may contain typed text; always unlink after execution.
+    writeFileSync(path, script, { encoding: "utf-8", mode: 0o600 });
+    try {
+        const out = await runOsa(["-l", "JavaScript", path]);
+        return out.trim() || null;
+    }
+    finally {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* best effort — already gone */ }
+    }
+}
+async function runAppleScript(script) {
+    const path = join(tmpdir(), `desktop-control-${randomUUID()}.applescript`);
+    // 0600: temp scripts may contain typed text; always unlink after execution.
+    writeFileSync(path, script, { encoding: "utf-8", mode: 0o600 });
+    try {
+        await runOsa([path]);
+        return null; // AppleScript paths carry no pointer read-back (frontmost before->after covers them)
+    }
+    finally {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* best effort — already gone */ }
+    }
+}
+/**
+ * Read-only probe: frontmost app via System Events. Doubles as the TCC
+ * accessibility/automation check — no input is ever injected by this call.
+ */
+function systemEventsProbe() {
+    return new Promise((resolve) => {
+        execFile("osascript", ["-e", 'tell application "System Events" to name of first application process whose frontmost is true'], { timeout: TIMEOUT_MS }, (err, stdout, stderr) => {
+            if (err) {
+                resolve({ ok: false, error: accessibilityError(String(stderr || err.message)) });
+            }
+            else {
+                resolve({ ok: true, name: stdout.trim() });
+            }
+        });
+    });
+}
+export function accessibilityError(rawStderr) {
+    const s = rawStderr.toLowerCase();
+    if (s.includes("assistive access") || s.includes("accessib")) {
+        return ("macOS blocked desktop control: Accessibility permission is missing.\n" +
+            "Fix: System Settings > Privacy & Security > Accessibility -> add (and enable) the app that runs " +
+            "spectral (your terminal, or the Electron host). Then retry. " +
+            "You can verify from the terminal with: osascript -e 'tell application \"System Events\" to get name of first process whose frontmost is true'");
+    }
+    if (s.includes("not allowed to send apple events") || s.includes("-1743") || s.includes("automat")) {
+        return ("macOS blocked desktop control: Automation permission is missing (osascript -> System Events).\n" +
+            "Fix: System Settings > Privacy & Security > Automation -> allow your terminal/host to control System Events.");
+    }
+    return `macOS System Events query failed: ${rawStderr.trim().split("\n").pop() ?? "unknown error"}`;
+}
+// ---------------------------------------------------------------------------
+// Screen Recording preflight (read-only)
+// ---------------------------------------------------------------------------
+export const SCREEN_RECORDING_ERROR = "macOS blocked the safety screenshots: Screen Recording permission is missing.\n" +
+    "Without it the BEFORE/AFTER captures silently show only the desktop wallpaper, so the action was refused before mutating anything.\n" +
+    "Fix: System Settings > Privacy & Security > Screen Recording -> add (and enable) the app that runs " +
+    "spectral (your terminal, or the Electron host). Then retry.";
+/**
+ * One-shot JXA probe: CGPreflightScreenCaptureAccess() — true when Screen
+ * Recording TCC is granted. The function is missing from CoreGraphics'
+ * bridgesupport on current macOS, so it is bound explicitly via ObjC.bindFunction.
+ */
+export function buildScreenCapturePreflightJxa() {
+    return (`ObjC.import('CoreGraphics'); ` +
+        `ObjC.bindFunction('CGPreflightScreenCaptureAccess', ['bool', []]); ` +
+        `$.CGPreflightScreenCaptureAccess()`);
+}
+/**
+ * False only when macOS definitively denies capture; null when the probe is
+ * unavailable (e.g. macOS < 10.15) or ambiguous — never block on an unreadable
+ * probe, the AFTER screenshot still gives the model feedback in that case.
+ */
+async function screenCaptureAllowed() {
+    try {
+        const out = (await runOsa(["-l", "JavaScript", "-e", buildScreenCapturePreflightJxa()])).trim();
+        return out === "true" ? true : out === "false" ? false : null;
+    }
+    catch {
+        return null;
+    }
+}
+function plan(action, detail) {
+    return `osascript -l JavaScript <tempfile>  # JXA CGEvent: ${detail}`;
+}
+export const macosAdapter = {
+    platform: "darwin",
+    capabilities: ["mouse_move", "mouse_click", "mouse_drag", "scroll", "type_text", "hotkey", "focus_window"],
+    async checkPermissions() {
+        // Both probes are read-only and run in parallel. checkPermissions is only
+        // invoked by the mutating envelope, so the Screen Recording preflight runs
+        // exactly where the BEFORE screenshot needs it (and nowhere else).
+        const [probe, capture] = await Promise.all([systemEventsProbe(), screenCaptureAllowed()]);
+        if (!probe.ok)
+            return { ok: false, error: probe.error };
+        if (capture === false)
+            return { ok: false, error: SCREEN_RECORDING_ERROR };
+        return { ok: true };
+    },
+    async frontmostApp() {
+        const probe = await systemEventsProbe();
+        return probe.ok ? probe.name ?? null : null;
+    },
+    buildPlan(action) {
+        switch (action.kind) {
+            case "mouse_move":
+                return plan(action, `CGEventCreateMouseEvent(null, kCGEventMouseMoved, {x:${action.x},y:${action.y}}, 0) + CGEventPost + CGEventGetLocation read-back`);
+            case "mouse_click":
+                return plan(action, `CGEventCreateMouseEvent(null, kCGEvent${action.button}Down/Up, {x:${action.x},y:${action.y}}, clickState=${action.clickCount}) + CGEventPost + CGEventGetLocation read-back`);
+            case "mouse_drag":
+                return plan(action, `LeftDown@(${action.fromX},${action.fromY}) + ${DRAG_STEPS}x Dragged -> LeftUp@(${action.toX},${action.toY}) + CGEventPost + CGEventGetLocation read-back`);
+            case "scroll":
+                return plan(action, `${action.x !== undefined ? `MouseMoved to (${action.x},${action.y}) + ` : ""}` +
+                    `CGEventCreateScrollWheelEvent(unit=line, wheel1=${-action.dy}, wheel2=${action.dx}) + CGEventPost + CGEventGetLocation read-back`);
+            case "type_text": {
+                const seq = buildAsciiTypeSeq(action.text);
+                return seq
+                    ? plan(action, `${seq.length}x CGEventCreateKeyboardEvent(keycode+shift flags) + CGEventPost`)
+                    : `osascript <tempfile>  # System Events keystroke (unicode fallback) for ${action.text.length} chars`;
+            }
+            case "hotkey":
+                return plan(action, `CGEventCreateKeyboardEvent(keycode for ${action.tokens.join("+")}) + CGEventSetFlags + CGEventPost`);
+            case "focus_window":
+                return action.title
+                    ? `osascript <tempfile>  # System Events: set frontmost of process "${action.owner ?? action.title}" + AXRaise on window "${action.title}"`
+                    : `osascript <tempfile>  # System Events: set frontmost of process "${action.owner ?? action.title}" to true`;
+        }
+    },
+    async execute(action) {
+        switch (action.kind) {
+            case "mouse_move":
+            case "mouse_click":
+            case "mouse_drag":
+            case "scroll":
+                return runJxa(buildMouseJxa(action));
+            case "type_text": {
+                const seq = buildAsciiTypeSeq(action.text);
+                if (seq)
+                    return runJxa(buildTypeJxa(seq));
+                return runAppleScript(buildKeystrokeAppleScript(action.text));
+            }
+            case "hotkey": {
+                const { key, flags } = resolveChordTokens(action.tokens);
+                return runJxa(buildHotkeyJxa(key, flags));
+            }
+            case "focus_window": {
+                if (!action.owner) {
+                    throw new Error('focus_window requires a resolved window owner (use list_windows, then retry with an exact title)');
+                }
+                return runAppleScript(buildFocusAppleScript(action.owner, action.title));
+            }
+        }
+    },
+};

package/dist/extensions/desktop-control/safety.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Safety layer for the desktop-control extension.
+ *
+ * - Session policy: by DEFAULT there is no confirmation prompt at all —
+ *   enabling the extension (enabledNativeExtensions contains
+ *   "desktop-control") is the explicit user consent, and every mutating
+ *   action runs immediately (including headless/serve/RPC sessions).
+ *   Opt-in SPECTRAL_DESKTOP_REQUIRE_CONFIRM=1|true restores the interactive
+ *   confirmation gate: the first mutating call asks once (ctx.hasUI); an
+ *   explicit user decision applies to the whole session (grant or lockout).
+ *   AUTO-deny causes — headless, non-TTY terminal, dialog timeout,
+ *   cancelled/unsupported client — deny only the current action with a
+ *   precise reason and never lock the session.
+ * - Dry-run: SPECTRAL_DESKTOP_DRY_RUN=1|true returns action plans without
+ *   touching the OS (no injection, no screenshots).
+ * - Allowlist: SPECTRAL_DESKTOP_ALLOWLIST="Safari, Code" restricts mutating
+ *   actions to sessions where the frontmost app (or the focus target's owner)
+ *   matches one of the comma-separated names (case-insensitive, substring).
+ */
+import type { DesktopAction } from "./types.js";
+export declare const DESKTOP_CONTROL_TOOLS: readonly ["desktop_mouse_move", "desktop_mouse_click", "desktop_mouse_drag", "desktop_scroll", "desktop_type_text", "desktop_press_key", "desktop_hotkey", "desktop_focus_window"];
+export type DesktopControlToolName = (typeof DESKTOP_CONTROL_TOOLS)[number];
+export declare function isDesktopControlTool(name: string): boolean;
+export declare function isDryRun(env?: NodeJS.ProcessEnv): boolean;
+/** Opt-in confirmation gate: SPECTRAL_DESKTOP_REQUIRE_CONFIRM=1|true restores the per-session prompt. */
+export declare function isRequireConfirm(env?: NodeJS.ProcessEnv): boolean;
+export declare function parseAllowlist(raw: string | undefined): string[];
+/** Case-insensitive substring match in both directions ("Safari" matches "com.apple.Safari"). */
+export declare function matchesAllowlist(app: string, allowlist: string[]): boolean;
+export interface PolicyDecision {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Why a confirmation dialog ended without an explicit human decision.
+ * These are AUTO-deny causes: they deny the current action only and must
+ * never lock the whole session (unlike an explicit user denial).
+ */
+export type ConfirmFailureKind = "no_tty" | "timeout" | "cancelled";
+export interface ConfirmFailure {
+    kind: ConfirmFailureKind;
+    /** For kind "timeout": how long the dialog waited before timing out (ms). */
+    timeoutMs?: number;
+}
+export interface ConfirmAllowed {
+    allowed: true;
+}
+export interface ConfirmDenied {
+    allowed: false;
+    /**
+     * Why the dialog did not end in an explicit human denial. Omit (or return
+     * a plain `false`) when a real user answered "No" in an interactive dialog.
+     */
+    failure?: ConfirmFailure;
+}
+/**
+ * Result of the `confirm` callback: a plain boolean (legacy — always treated
+ * as an explicit interactive user decision) or a rich result that can report
+ * AUTO-deny causes (`failure`) so the session is not locked by them.
+ */
+export type ConfirmResult = boolean | ConfirmAllowed | ConfirmDenied;
+export interface AuthorizeInput {
+    dryRun: boolean;
+    hasUI: boolean;
+    /** One-line description of the action for the confirmation dialog. */
+    actionSummary: string;
+    confirm?: (title: string, message: string) => Promise<ConfirmResult>;
+}
+/** Precise auto-deny message per cause (headless/no-UI are handled in authorize). */
+export declare function autoDenyReason(failure: ConfirmFailure): string;
+/**
+ * Session-scoped allow/deny state machine for mutating desktop actions.
+ * Pure logic — the confirm callback is injected so tests can stub it.
+ * Only used when SPECTRAL_DESKTOP_REQUIRE_CONFIRM is enabled (opt-in).
+ *
+ * Only an EXPLICIT user denial (the confirm callback reporting a human "No")
+ * moves the session into the locked "denied" state. AUTO-deny causes — no UI,
+ * non-TTY terminal, dialog timeout, cancelled/unsupported client — deny only
+ * the current action (fail-closed) and leave the session undecided.
+ */
+export declare class DesktopActionPolicy {
+    private state;
+    get decided(): boolean;
+    get isGranted(): boolean;
+    authorize(input: AuthorizeInput): Promise<PolicyDecision>;
+}
+/** One-line human-readable action summary (used in confirm dialogs, plans and result text). */
+export declare function describeAction(action: DesktopAction): string;
+//# sourceMappingURL=safety.d.ts.map

package/dist/extensions/desktop-control/safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../../../src/extensions/desktop-control/safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,qBAAqB,oLASxB,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,QAAQ,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAGtE;AAED,yGAAyG;AACzG,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAG9E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAGhE;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAO1E;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;AAEpE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,cAAc,GAAG,aAAa,CAAC;AAErE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CACtE;AAQD,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAmB9D;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,KAAK,CAAmD;IAEhE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;CA8ChE;AAOD,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAiB5D"}

package/dist/extensions/desktop-control/safety.js

@@ -0,0 +1,157 @@
+/**
+ * Safety layer for the desktop-control extension.
+ *
+ * - Session policy: by DEFAULT there is no confirmation prompt at all —
+ *   enabling the extension (enabledNativeExtensions contains
+ *   "desktop-control") is the explicit user consent, and every mutating
+ *   action runs immediately (including headless/serve/RPC sessions).
+ *   Opt-in SPECTRAL_DESKTOP_REQUIRE_CONFIRM=1|true restores the interactive
+ *   confirmation gate: the first mutating call asks once (ctx.hasUI); an
+ *   explicit user decision applies to the whole session (grant or lockout).
+ *   AUTO-deny causes — headless, non-TTY terminal, dialog timeout,
+ *   cancelled/unsupported client — deny only the current action with a
+ *   precise reason and never lock the session.
+ * - Dry-run: SPECTRAL_DESKTOP_DRY_RUN=1|true returns action plans without
+ *   touching the OS (no injection, no screenshots).
+ * - Allowlist: SPECTRAL_DESKTOP_ALLOWLIST="Safari, Code" restricts mutating
+ *   actions to sessions where the frontmost app (or the focus target's owner)
+ *   matches one of the comma-separated names (case-insensitive, substring).
+ */
+export const DESKTOP_CONTROL_TOOLS = [
+    "desktop_mouse_move",
+    "desktop_mouse_click",
+    "desktop_mouse_drag",
+    "desktop_scroll",
+    "desktop_type_text",
+    "desktop_press_key",
+    "desktop_hotkey",
+    "desktop_focus_window",
+];
+export function isDesktopControlTool(name) {
+    return DESKTOP_CONTROL_TOOLS.includes(name);
+}
+export function isDryRun(env = process.env) {
+    const v = env.SPECTRAL_DESKTOP_DRY_RUN;
+    return v === "1" || v === "true";
+}
+/** Opt-in confirmation gate: SPECTRAL_DESKTOP_REQUIRE_CONFIRM=1|true restores the per-session prompt. */
+export function isRequireConfirm(env = process.env) {
+    const v = env.SPECTRAL_DESKTOP_REQUIRE_CONFIRM;
+    return v === "1" || v === "true";
+}
+export function parseAllowlist(raw) {
+    if (!raw)
+        return [];
+    return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/** Case-insensitive substring match in both directions ("Safari" matches "com.apple.Safari"). */
+export function matchesAllowlist(app, allowlist) {
+    if (allowlist.length === 0)
+        return true;
+    const a = app.toLowerCase();
+    return allowlist.some((entry) => {
+        const n = entry.toLowerCase();
+        return a.includes(n) || n.includes(a);
+    });
+}
+const USER_DENIED_REASON = "User denied desktop control for this session. Start a new session to ask again, or set SPECTRAL_DESKTOP_DRY_RUN=1 to preview action plans without executing.";
+const NOT_LOCKED_SUFFIX = "The current action was denied (fail-closed), but the session is not locked — the next desktop action will ask for confirmation again.";
+/** Precise auto-deny message per cause (headless/no-UI are handled in authorize). */
+export function autoDenyReason(failure) {
+    switch (failure.kind) {
+        case "no_tty":
+            return ("Desktop control was not confirmed: the confirmation terminal is not interactive (stdin is not a TTY), so no user could answer the prompt. " +
+                NOT_LOCKED_SUFFIX +
+                " Run `spectral serve` in an interactive terminal, or set SPECTRAL_DESKTOP_DRY_RUN=1 to preview action plans without executing.");
+        case "timeout":
+            return (`Desktop control was not confirmed: the confirmation dialog timed out after ${failure.timeoutMs ?? "the configured"} ms (SPECTRAL_CONFIRM_TIMEOUT_MS) without a user answer. ` +
+                NOT_LOCKED_SUFFIX);
+        case "cancelled":
+            return ("Desktop control was not confirmed: the confirmation dialog was cancelled or is not supported by the client (e.g. RPC mode), so no user decision was made. " +
+                NOT_LOCKED_SUFFIX);
+    }
+}
+/**
+ * Session-scoped allow/deny state machine for mutating desktop actions.
+ * Pure logic — the confirm callback is injected so tests can stub it.
+ * Only used when SPECTRAL_DESKTOP_REQUIRE_CONFIRM is enabled (opt-in).
+ *
+ * Only an EXPLICIT user denial (the confirm callback reporting a human "No")
+ * moves the session into the locked "denied" state. AUTO-deny causes — no UI,
+ * non-TTY terminal, dialog timeout, cancelled/unsupported client — deny only
+ * the current action (fail-closed) and leave the session undecided.
+ */
+export class DesktopActionPolicy {
+    state = "undecided";
+    get decided() {
+        return this.state !== "undecided";
+    }
+    get isGranted() {
+        return this.state === "granted";
+    }
+    async authorize(input) {
+        if (input.dryRun)
+            return { allowed: true, reason: "dry-run" };
+        if (this.state === "granted")
+            return { allowed: true };
+        if (this.state === "denied") {
+            return {
+                allowed: false,
+                reason: "Desktop control was denied by the user for this session. Re-enable it in settings (enabledNativeExtensions) or start a new session to ask again.",
+            };
+        }
+        if (!input.hasUI) {
+            return {
+                allowed: false,
+                reason: "Desktop control is denied in headless mode (no interactive UI to confirm real input injection). " +
+                    NOT_LOCKED_SUFFIX +
+                    " Run `spectral serve` in an interactive terminal, or set SPECTRAL_DESKTOP_DRY_RUN=1 to preview action plans without executing.",
+            };
+        }
+        if (!input.confirm) {
+            return {
+                allowed: false,
+                reason: "No confirmation UI available for desktop control. " +
+                    NOT_LOCKED_SUFFIX +
+                    " Run spectral in a mode with an interactive UI, or set SPECTRAL_DESKTOP_DRY_RUN=1 to preview action plans without executing.",
+            };
+        }
+        const result = await input.confirm("Desktop control", `Allow REAL input injection: ${input.actionSummary}?\n` +
+            "The action runs on your desktop and returns before/after screenshots. Granting it applies to the whole session.");
+        if (result === true || (typeof result === "object" && result.allowed)) {
+            this.state = "granted";
+            return { allowed: true };
+        }
+        const failure = typeof result === "object" ? result.failure : undefined;
+        if (!failure) {
+            // Explicit human denial in an interactive dialog — locks the session.
+            this.state = "denied";
+            return { allowed: false, reason: USER_DENIED_REASON };
+        }
+        // Auto-deny (no human decision): fail closed for this action only.
+        return { allowed: false, reason: autoDenyReason(failure) };
+    }
+}
+function truncate(s, max) {
+    const oneLine = s.replace(/\r?\n/g, "\\n").replace(/\t/g, "\\t");
+    return oneLine.length > max ? oneLine.slice(0, max - 1) + "…" : oneLine;
+}
+/** One-line human-readable action summary (used in confirm dialogs, plans and result text). */
+export function describeAction(action) {
+    switch (action.kind) {
+        case "mouse_move":
+            return `mouse_move x=${action.x} y=${action.y}`;
+        case "mouse_click":
+            return `mouse_click x=${action.x} y=${action.y} button=${action.button} clickCount=${action.clickCount}`;
+        case "mouse_drag":
+            return `mouse_drag from=(${action.fromX},${action.fromY}) to=(${action.toX},${action.toY})`;
+        case "scroll":
+            return `scroll dy=${action.dy} dx=${action.dx}${action.x !== undefined ? ` at=(${action.x},${action.y})` : ""}`;
+        case "type_text":
+            return `type_text "${truncate(action.text, 80)}" (${action.text.length} chars)`;
+        case "hotkey":
+            return `hotkey ${action.tokens.join("+")}`;
+        case "focus_window":
+            return `focus_window "${action.title}"`;
+    }
+}