@mseep/clawdcursor 1.5.5

package/dist/core/sense/a11y-resolver.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A11y bounds resolver — math-only, zero LLM, zero vision.
+ *
+ * Ported from src/a11y-click-resolver.ts. Decoupled from the legacy
+ * `AccessibilityBridge` class — the unified pipeline hands in a resolver
+ * function that returns UI element bounds (typically from
+ * `PlatformAdapter.findElements`).
+ *
+ * The critical invariant v0.6.3 earned through real-world bug hunting:
+ * reject bounds with `y:-29503` and similar absurd values that some a11y
+ * APIs return for hidden/off-screen elements. This file's `isValidBounds`
+ * is the guard.
+ */
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface UiElementWithBounds {
+    name?: string;
+    controlType?: string;
+    bounds?: Bounds;
+    automationId?: string;
+}
+/**
+ * Bounds sanity check. Rejects:
+ *  - zero/negative width or height
+ *  - off-screen coordinates that indicate hidden elements
+ *    (e.g. macOS AX returns y:-29503 for some cached-but-invisible items)
+ *  - out-of-range coordinates > 10k (no real screen is that large; 8K is ~8000)
+ */
+export declare function isValidBounds(b: Bounds | undefined): boolean;
+/**
+ * Return the integer center of a bounds rect.
+ */
+export declare function centerOf(b: Bounds): {
+    x: number;
+    y: number;
+};
+/**
+ * Resolve an element name/automationId to its center coords.
+ *
+ * `lookup` is a caller-provided function so this module is decoupled from any
+ * specific `AccessibilityBridge` or `PlatformAdapter` instance — tests can
+ * stub it, and the pipeline can wire whatever adapter it has.
+ *
+ * Returns null if the element isn't found or its bounds fail the sanity
+ * check. Callers should fall back to OCR-based coord resolution on null.
+ */
+export declare function resolveByName(name: string, lookup: (q: {
+    name?: string;
+    controlType?: string;
+    processId?: number;
+}) => Promise<UiElementWithBounds[]>, opts?: {
+    controlType?: string;
+    processId?: number;
+}): Promise<{
+    x: number;
+    y: number;
+} | null>;
+/**
+ * Resolve by a11y automationId (Windows UIA only today; noop elsewhere).
+ */
+export declare function resolveById(automationId: string, lookup: (q: {
+    automationId?: string;
+    processId?: number;
+}) => Promise<UiElementWithBounds[]>, opts?: {
+    processId?: number;
+}): Promise<{
+    x: number;
+    y: number;
+} | null>;

package/dist/core/sense/a11y-resolver.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * A11y bounds resolver — math-only, zero LLM, zero vision.
+ *
+ * Ported from src/a11y-click-resolver.ts. Decoupled from the legacy
+ * `AccessibilityBridge` class — the unified pipeline hands in a resolver
+ * function that returns UI element bounds (typically from
+ * `PlatformAdapter.findElements`).
+ *
+ * The critical invariant v0.6.3 earned through real-world bug hunting:
+ * reject bounds with `y:-29503` and similar absurd values that some a11y
+ * APIs return for hidden/off-screen elements. This file's `isValidBounds`
+ * is the guard.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidBounds = isValidBounds;
+exports.centerOf = centerOf;
+exports.resolveByName = resolveByName;
+exports.resolveById = resolveById;
+/**
+ * Bounds sanity check. Rejects:
+ *  - zero/negative width or height
+ *  - off-screen coordinates that indicate hidden elements
+ *    (e.g. macOS AX returns y:-29503 for some cached-but-invisible items)
+ *  - out-of-range coordinates > 10k (no real screen is that large; 8K is ~8000)
+ */
+function isValidBounds(b) {
+    if (!b || b.width <= 0 || b.height <= 0)
+        return false;
+    if (b.x < -100 || b.y < -100)
+        return false;
+    if (b.x > 10_000 || b.y > 10_000)
+        return false;
+    return true;
+}
+/**
+ * Return the integer center of a bounds rect.
+ */
+function centerOf(b) {
+    return {
+        x: b.x + Math.floor(b.width / 2),
+        y: b.y + Math.floor(b.height / 2),
+    };
+}
+/**
+ * Resolve an element name/automationId to its center coords.
+ *
+ * `lookup` is a caller-provided function so this module is decoupled from any
+ * specific `AccessibilityBridge` or `PlatformAdapter` instance — tests can
+ * stub it, and the pipeline can wire whatever adapter it has.
+ *
+ * Returns null if the element isn't found or its bounds fail the sanity
+ * check. Callers should fall back to OCR-based coord resolution on null.
+ */
+async function resolveByName(name, lookup, opts) {
+    const results = await lookup({ name, ...opts });
+    if (!results?.length)
+        return null;
+    const first = results[0];
+    if (!isValidBounds(first.bounds))
+        return null;
+    return centerOf(first.bounds);
+}
+/**
+ * Resolve by a11y automationId (Windows UIA only today; noop elsewhere).
+ */
+async function resolveById(automationId, lookup, opts) {
+    const results = await lookup({ automationId, ...opts });
+    if (!results?.length)
+        return null;
+    const first = results[0];
+    if (!isValidBounds(first.bounds))
+        return null;
+    return centerOf(first.bounds);
+}
+//# sourceMappingURL=a11y-resolver.js.map

package/dist/core/sense/a11y-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y-resolver.js","sourceRoot":"","sources":["../../../src/core/sense/a11y-resolver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAuBH,sCAKC;AAKD,4BAKC;AAYD,sCAUC;AAKD,kCAUC;AA3DD;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,CAAqB;IACjD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM;QAAE,OAAO,KAAK,CAAC;IAC/C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,SAAgB,QAAQ,CAAC,CAAS;IAChC,OAAO;QACL,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;QAChC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;KAClC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,aAAa,CACjC,IAAY,EACZ,MAA0G,EAC1G,IAAmD;IAEnD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAO,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,WAAW,CAC/B,YAAoB,EACpB,MAA4F,EAC5F,IAA6B;IAE7B,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC,OAAO,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/core/sense/fingerprint.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Snapshot fingerprint — stagnation detection.
+ *
+ * Ported from src/snapshot-builder.ts. The idea: after every agent action,
+ * compute a stable hash of "what's on screen" (structured elements only —
+ * not pixels). If the fingerprint doesn't change across N consecutive
+ * actions, the agent is stuck doing the same thing.
+ *
+ * The orchestrator uses this to short-circuit infinite loops. A 2-iteration
+ * duplicate fingerprint + a verifier that says "not done" = abort, try a
+ * different layer (text-agent → vision-agent → retry).
+ */
+import type { SnapshotElement } from './types';
+/**
+ * Produce a deterministic short hash of the screen state.
+ *
+ * Order-insensitive (elements sorted before hash), position-quantized (to 8px
+ * buckets) so that sub-pixel jitter from OCR doesn't break the equality.
+ *
+ * Intentionally NOT based on pixel screenshots — that's what the verifier's
+ * pixel-diff signal handles. This is the a11y/OCR-level "same set of named
+ * buttons at roughly the same places" fingerprint.
+ */
+export declare function fingerprint(elements: SnapshotElement[], activeTitle?: string): string;
+/**
+ * A sliding history of recent fingerprints. Reports stagnation when the
+ * last `n` fingerprints are identical.
+ */
+export declare class FingerprintHistory {
+    private readonly maxSize;
+    private history;
+    constructor(maxSize?: number);
+    /** Append a new fingerprint. */
+    push(fp: string): void;
+    /** Stagnant if the last N entries are all equal and ≥ 2. */
+    isStagnant(n?: number): boolean;
+    /** Reset after a successful action so the agent gets a fresh window. */
+    reset(): void;
+    /** Internal — for tests and telemetry. */
+    getHistory(): string[];
+}

package/dist/core/sense/fingerprint.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Snapshot fingerprint — stagnation detection.
+ *
+ * Ported from src/snapshot-builder.ts. The idea: after every agent action,
+ * compute a stable hash of "what's on screen" (structured elements only —
+ * not pixels). If the fingerprint doesn't change across N consecutive
+ * actions, the agent is stuck doing the same thing.
+ *
+ * The orchestrator uses this to short-circuit infinite loops. A 2-iteration
+ * duplicate fingerprint + a verifier that says "not done" = abort, try a
+ * different layer (text-agent → vision-agent → retry).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FingerprintHistory = void 0;
+exports.fingerprint = fingerprint;
+const crypto = __importStar(require("crypto"));
+// NOTE on the SHA-1 below: these are NON-credential state checksums for
+// stagnation detection — not password/credential storage. The digests are
+// truncated, held only in-memory for the duration of one task run, and never
+// persisted or transmitted. Secure fields are already excluded upstream
+// (value === undefined). CodeQL's js/insufficient-password-hash flags the
+// `e.value` → SHA-1 flow as a "password hash"; that is a false positive here
+// (a KDF like bcrypt/scrypt would be the wrong tool for a per-frame checksum).
+/**
+ * Produce a deterministic short hash of the screen state.
+ *
+ * Order-insensitive (elements sorted before hash), position-quantized (to 8px
+ * buckets) so that sub-pixel jitter from OCR doesn't break the equality.
+ *
+ * Intentionally NOT based on pixel screenshots — that's what the verifier's
+ * pixel-diff signal handles. This is the a11y/OCR-level "same set of named
+ * buttons at roughly the same places" fingerprint.
+ */
+function fingerprint(elements, activeTitle) {
+    // Quantize coords to a grid to absorb OCR jitter.
+    const QUANT = 8;
+    const quant = (n) => Math.round(n / QUANT) * QUANT;
+    const tokens = elements.map(e => {
+        const cx = quant(e.x);
+        const cy = quant(e.y);
+        const role = e.role ?? e.source;
+        // Normalize name: trim + collapse whitespace + lowercase
+        const name = (e.name ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+        // Include the field VALUE (hashed short, never the raw text — it may be
+        // sensitive): typing changes value but not name/role/bounds, so a
+        // value-blind fingerprint made every successful type/fill look like "no
+        // observable change" and fed false stagnation nudges (audit 2026-06-10,
+        // finding D2). Secure fields carry value=undefined and stay excluded.
+        const val = e.value ? crypto.createHash('sha1').update(e.value).digest('hex').slice(0, 8) : '';
+        return `${role}|${name}|${cx}|${cy}|${val}`;
+    });
+    tokens.sort(); // order-insensitive
+    const payload = (activeTitle ?? '') + '\n' + tokens.join('\n');
+    return crypto.createHash('sha1').update(payload).digest('hex').slice(0, 16);
+}
+/**
+ * A sliding history of recent fingerprints. Reports stagnation when the
+ * last `n` fingerprints are identical.
+ */
+class FingerprintHistory {
+    maxSize;
+    history = [];
+    constructor(maxSize = 8) {
+        this.maxSize = maxSize;
+    }
+    /** Append a new fingerprint. */
+    push(fp) {
+        this.history.push(fp);
+        if (this.history.length > this.maxSize)
+            this.history.shift();
+    }
+    /** Stagnant if the last N entries are all equal and ≥ 2. */
+    isStagnant(n = 2) {
+        if (this.history.length < n)
+            return false;
+        const tail = this.history.slice(-n);
+        return tail.every(fp => fp === tail[0]);
+    }
+    /** Reset after a successful action so the agent gets a fresh window. */
+    reset() {
+        this.history = [];
+    }
+    /** Internal — for tests and telemetry. */
+    getHistory() {
+        return [...this.history];
+    }
+}
+exports.FingerprintHistory = FingerprintHistory;
+//# sourceMappingURL=fingerprint.js.map

package/dist/core/sense/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../../src/core/sense/fingerprint.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuBH,kCAwBC;AA7CD,+CAAiC;AAGjC,wEAAwE;AACxE,0EAA0E;AAC1E,6EAA6E;AAC7E,wEAAwE;AACxE,0EAA0E;AAC1E,6EAA6E;AAC7E,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,SAAgB,WAAW,CAAC,QAA2B,EAAE,WAAoB;IAC3E,kDAAkD;IAClD,MAAM,KAAK,GAAG,CAAC,CAAC;IAChB,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;IAE3D,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QAC9B,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC;QAChC,yDAAyD;QACzD,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACtE,wEAAwE;QACxE,kEAAkE;QAClE,wEAAwE;QACxE,wEAAwE;QACxE,sEAAsE;QACtE,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/F,OAAO,GAAG,IAAI,IAAI,IAAI,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,oBAAoB;IAEnC,MAAM,OAAO,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAa,kBAAkB;IAEA;IADrB,OAAO,GAAa,EAAE,CAAC;IAC/B,YAA6B,UAAkB,CAAC;QAAnB,YAAO,GAAP,OAAO,CAAY;IAAG,CAAC;IAEpD,gCAAgC;IAChC,IAAI,CAAC,EAAU;QACb,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC/D,CAAC;IAED,4DAA4D;IAC5D,UAAU,CAAC,IAAY,CAAC;QACtB,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,wEAAwE;IACxE,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED,0CAA0C;IAC1C,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;CACF;AA1BD,gDA0BC"}

package/dist/core/sense/rank.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Rank-before-truncate for a11y snapshots.
+ *
+ * Problem: Paint's a11y tree had "Pencil" at index 20 (it was NOT truncated),
+ * but Explorer / Outlook / Teams can easily spew 200+ a11y nodes where the
+ * buttons the agent actually needs sit at indices 80–150. The previous
+ * `slice(0, 80)` strategy threw those overboard.
+ *
+ * This module ranks elements by how likely the agent is to act on them, then
+ * the snapshot renderer truncates from the bottom. No app-specific rules —
+ * the signals come from accessibility roles and bounding-box geometry,
+ * nothing encoded per-app.
+ *
+ * Signals (additive, all non-app-specific):
+ *   + Interactive roles (Button, MenuItem, Hyperlink, Edit, ComboBox, Tab,
+ *     CheckBox, RadioButton, ListItem, TreeItem) get a strong boost.
+ *   + Named elements (non-empty `name`) beat anonymous ones.
+ *   + Focused element gets a big boost.
+ *   + Elements marked `interactive: true` get a small boost.
+ *   + Smaller elements (typical for buttons / icons) slightly preferred
+ *     over full-window panes / group containers.
+ *   + Top-edge and right-edge toolbars get a modest boost (Paint palette,
+ *     Office ribbon live there).
+ *   - Containers (Pane, Group, Document, ScrollBar) get a penalty — they
+ *     hold other interactive nodes but aren't themselves clickable.
+ *   - Huge elements (> 80% of screen) get a penalty — usually the window
+ *     body, not a target.
+ *
+ * The ranker is a pure function of the snapshot element list. It never
+ * consults app name / window title / anything app-specific. A new LOB app
+ * with exotic roles will rank cleanly because it obeys the same a11y
+ * contract every Windows/macOS/Linux UI toolkit does.
+ */
+import type { SnapshotElement } from './types';
+export interface RankOpts {
+    /** Physical screen width for "huge element" detection. */
+    screenWidth?: number;
+    /** Physical screen height for "huge element" detection. */
+    screenHeight?: number;
+    /** Active window processId — elements outside this process get penalized. */
+    focusProcessId?: number;
+    /** Explicitly-focused element coords, if the adapter reports one. */
+    focusPoint?: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Score one element. Higher = more likely the agent wants to act on it.
+ * Pure: no I/O, no app-specific tables.
+ */
+export declare function scoreElement(el: SnapshotElement, opts?: RankOpts): number;
+/**
+ * Rank elements from most-likely-to-act-on to least. Stable: equal scores
+ * preserve document order (often the left-to-right, top-to-bottom order
+ * Windows UIA returns, which tends to match visual scan order).
+ *
+ * Does NOT truncate — callers decide the cap based on their token budget.
+ * The snapshot renderer typically calls rank(), then slices the top N.
+ */
+export declare function rankElements(elements: SnapshotElement[], opts?: RankOpts): SnapshotElement[];
+/**
+ * Debug-friendly: return the top-N with their scores. Used by the
+ * observability logger so the user can see WHY "Pencil" ranked 3rd when
+ * the tree had 200 elements.
+ */
+export declare function rankWithScores(elements: SnapshotElement[], opts?: RankOpts): Array<{
+    el: SnapshotElement;
+    score: number;
+}>;

package/dist/core/sense/rank.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Rank-before-truncate for a11y snapshots.
+ *
+ * Problem: Paint's a11y tree had "Pencil" at index 20 (it was NOT truncated),
+ * but Explorer / Outlook / Teams can easily spew 200+ a11y nodes where the
+ * buttons the agent actually needs sit at indices 80–150. The previous
+ * `slice(0, 80)` strategy threw those overboard.
+ *
+ * This module ranks elements by how likely the agent is to act on them, then
+ * the snapshot renderer truncates from the bottom. No app-specific rules —
+ * the signals come from accessibility roles and bounding-box geometry,
+ * nothing encoded per-app.
+ *
+ * Signals (additive, all non-app-specific):
+ *   + Interactive roles (Button, MenuItem, Hyperlink, Edit, ComboBox, Tab,
+ *     CheckBox, RadioButton, ListItem, TreeItem) get a strong boost.
+ *   + Named elements (non-empty `name`) beat anonymous ones.
+ *   + Focused element gets a big boost.
+ *   + Elements marked `interactive: true` get a small boost.
+ *   + Smaller elements (typical for buttons / icons) slightly preferred
+ *     over full-window panes / group containers.
+ *   + Top-edge and right-edge toolbars get a modest boost (Paint palette,
+ *     Office ribbon live there).
+ *   - Containers (Pane, Group, Document, ScrollBar) get a penalty — they
+ *     hold other interactive nodes but aren't themselves clickable.
+ *   - Huge elements (> 80% of screen) get a penalty — usually the window
+ *     body, not a target.
+ *
+ * The ranker is a pure function of the snapshot element list. It never
+ * consults app name / window title / anything app-specific. A new LOB app
+ * with exotic roles will rank cleanly because it obeys the same a11y
+ * contract every Windows/macOS/Linux UI toolkit does.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scoreElement = scoreElement;
+exports.rankElements = rankElements;
+exports.rankWithScores = rankWithScores;
+/**
+ * Score weights. Tuned to be monotonic: the sum for a typical interactive
+ * button exceeds the sum for a container pane by a healthy margin. Exact
+ * numbers matter less than the ordering.
+ */
+const ROLE_BOOSTS = {
+    // ─── Clickable/commandable ────────────────────────────────
+    'button': 40,
+    'menuitem': 38,
+    'hyperlink': 38,
+    'link': 38,
+    'tab': 32,
+    'checkbox': 30,
+    'radiobutton': 30,
+    'splitbutton': 30,
+    'togglebutton': 30,
+    'listitem': 24,
+    'treeitem': 24,
+    'menubaritem': 30,
+    // ─── Editable ─────────────────────────────────────────────
+    'edit': 35,
+    'text': 18, // generic; raised only slightly
+    'combobox': 32,
+    'spinner': 26,
+    'slider': 26,
+    'datepicker': 26,
+    // ─── Informational but often targeted ─────────────────────
+    'image': 6,
+    'statictext': 5,
+    'statusbar': 8,
+    // ─── Containers (penalized, but not eliminated) ───────────
+    'pane': -12,
+    'group': -8,
+    'document': -10,
+    'scrollbar': -20,
+    'titlebar': -4,
+    'menubar': 0,
+    'toolbar': 6, // toolbars themselves aren't clicked, but they
+    // geographically concentrate buttons — keep them
+    // visible so the agent has orientation
+    'window': -18,
+};
+/** Extra boost when the element sits along a toolbar edge (top/right). */
+const TOOLBAR_EDGE_BOOST = 6;
+/** Boost for an explicitly focused element. */
+const FOCUSED_BOOST = 25;
+/** Boost for having a readable name. */
+const NAMED_BOOST = 10;
+/** Boost for interactive flag (set by the platform adapter). */
+const INTERACTIVE_FLAG_BOOST = 6;
+/** Penalty for being >= 80% of the screen area. */
+const HUGE_ELEMENT_PENALTY = -25;
+/** Penalty for being 0 bounds (invisible). */
+const ZERO_BOUNDS_PENALTY = -80;
+/**
+ * Score one element. Higher = more likely the agent wants to act on it.
+ * Pure: no I/O, no app-specific tables.
+ */
+function scoreElement(el, opts = {}) {
+    let score = 0;
+    // Role signal — the single biggest ranker.
+    const role = (el.role || '').toLowerCase().replace(/[^a-z]/g, '');
+    if (role && role in ROLE_BOOSTS)
+        score += ROLE_BOOSTS[role];
+    else if (role)
+        score += 4; // unknown role gets a small positive (don't zero-weight new a11y roles)
+    // Named elements beat anonymous.
+    const name = (el.name || '').trim();
+    if (name)
+        score += NAMED_BOOST;
+    // Longer readable names (up to ~30 chars) get a small additional weight.
+    if (name.length > 2)
+        score += Math.min(name.length, 20) * 0.15;
+    // Interactive flag from adapter.
+    if (el.interactive)
+        score += INTERACTIVE_FLAG_BOOST;
+    // A11y source beats OCR — a11y tree entries come with stable roles and
+    // names; OCR is often noisy text labels.
+    if (el.source === 'a11y')
+        score += 4;
+    // Geometric sanity:
+    const screenW = opts.screenWidth ?? 1920;
+    const screenH = opts.screenHeight ?? 1080;
+    const screenArea = screenW * screenH;
+    const elArea = Math.max(0, el.width) * Math.max(0, el.height);
+    if (el.width <= 0 || el.height <= 0) {
+        score += ZERO_BOUNDS_PENALTY;
+    }
+    else if (screenArea > 0 && elArea / screenArea > 0.8) {
+        score += HUGE_ELEMENT_PENALTY;
+    }
+    else {
+        // Smaller elements (typical of buttons) get a modest positive. Weighted
+        // so a 40×40 button scores +6, a 200×200 control scores ~+2, a big pane
+        // scores near 0.
+        const normalized = 1 - Math.min(1, elArea / (screenArea / 50));
+        score += normalized * 6;
+    }
+    // Toolbar-edge boost — elements near the top (y < 140) or right
+    // (x > screenW - 200) are often command buttons (Paint palette, Office
+    // ribbon, sidebar buttons). No app-specific code needed.
+    if (el.y < 140)
+        score += TOOLBAR_EDGE_BOOST;
+    else if (el.x > screenW - 200)
+        score += TOOLBAR_EDGE_BOOST * 0.7;
+    // Focused element wins big.
+    if (opts.focusPoint) {
+        const cx = el.x + el.width / 2;
+        const cy = el.y + el.height / 2;
+        const dx = cx - opts.focusPoint.x;
+        const dy = cy - opts.focusPoint.y;
+        const dist = Math.hypot(dx, dy);
+        // Within 40px — definitely focused.
+        if (dist < 40)
+            score += FOCUSED_BOOST;
+        // Within 200 — nearby / probably related.
+        else if (dist < 200)
+            score += FOCUSED_BOOST * 0.3;
+    }
+    // Prefer elements in the focused window's process.
+    if (opts.focusProcessId != null && el.processId != null && el.processId !== opts.focusProcessId) {
+        score -= 30;
+    }
+    return score;
+}
+/**
+ * Rank elements from most-likely-to-act-on to least. Stable: equal scores
+ * preserve document order (often the left-to-right, top-to-bottom order
+ * Windows UIA returns, which tends to match visual scan order).
+ *
+ * Does NOT truncate — callers decide the cap based on their token budget.
+ * The snapshot renderer typically calls rank(), then slices the top N.
+ */
+function rankElements(elements, opts = {}) {
+    // Attach indices to preserve stable order on ties.
+    const scored = elements.map((el, i) => ({ el, i, s: scoreElement(el, opts) }));
+    scored.sort((a, b) => {
+        if (b.s !== a.s)
+            return b.s - a.s;
+        return a.i - b.i;
+    });
+    return scored.map(x => x.el);
+}
+/**
+ * Debug-friendly: return the top-N with their scores. Used by the
+ * observability logger so the user can see WHY "Pencil" ranked 3rd when
+ * the tree had 200 elements.
+ */
+function rankWithScores(elements, opts = {}) {
+    return elements
+        .map(el => ({ el, score: scoreElement(el, opts) }))
+        .sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=rank.js.map

package/dist/core/sense/rank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.js","sourceRoot":"","sources":["../../../src/core/sense/rank.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;AA2EH,oCAgEC;AAUD,oCAQC;AAOD,wCAIC;AApKD;;;;GAIG;AACH,MAAM,WAAW,GAA2B;IAC1C,6DAA6D;IAC7D,QAAQ,EAAE,EAAE;IACZ,UAAU,EAAE,EAAE;IACd,WAAW,EAAE,EAAE;IACf,MAAM,EAAE,EAAE;IACV,KAAK,EAAE,EAAE;IACT,UAAU,EAAE,EAAE;IACd,aAAa,EAAE,EAAE;IACjB,aAAa,EAAE,EAAE;IACjB,cAAc,EAAE,EAAE;IAClB,UAAU,EAAE,EAAE;IACd,UAAU,EAAE,EAAE;IACd,aAAa,EAAE,EAAE;IACjB,6DAA6D;IAC7D,MAAM,EAAE,EAAE;IACV,MAAM,EAAE,EAAE,EAAY,gCAAgC;IACtD,UAAU,EAAE,EAAE;IACd,SAAS,EAAE,EAAE;IACb,QAAQ,EAAE,EAAE;IACZ,YAAY,EAAE,EAAE;IAChB,6DAA6D;IAC7D,OAAO,EAAE,CAAC;IACV,YAAY,EAAE,CAAC;IACf,WAAW,EAAE,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,CAAC,EAAE;IACX,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,CAAC,EAAE;IACf,WAAW,EAAE,CAAC,EAAE;IAChB,UAAU,EAAE,CAAC,CAAC;IACd,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC,EAAU,+CAA+C;IAC/C,iDAAiD;IACjD,uCAAuC;IAC7D,QAAQ,EAAE,CAAC,EAAE;CACd,CAAC;AAEF,0EAA0E;AAC1E,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAC7B,+CAA+C;AAC/C,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,wCAAwC;AACxC,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,gEAAgE;AAChE,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACjC,mDAAmD;AACnD,MAAM,oBAAoB,GAAG,CAAC,EAAE,CAAC;AACjC,8CAA8C;AAC9C,MAAM,mBAAmB,GAAG,CAAC,EAAE,CAAC;AAahC;;;GAGG;AACH,SAAgB,YAAY,CAAC,EAAmB,EAAE,OAAiB,EAAE;IACnE,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,2CAA2C;IAC3C,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAClE,IAAI,IAAI,IAAI,IAAI,IAAI,WAAW;QAAE,KAAK,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;SACvD,IAAI,IAAI;QAAE,KAAK,IAAI,CAAC,CAAC,CAAC,wEAAwE;IAEnG,iCAAiC;IACjC,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,IAAI,IAAI;QAAE,KAAK,IAAI,WAAW,CAAC;IAC/B,yEAAyE;IACzE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC;IAE/D,iCAAiC;IACjC,IAAI,EAAE,CAAC,WAAW;QAAE,KAAK,IAAI,sBAAsB,CAAC;IAEpD,uEAAuE;IACvE,yCAAyC;IACzC,IAAI,EAAE,CAAC,MAAM,KAAK,MAAM;QAAE,KAAK,IAAI,CAAC,CAAC;IAErC,oBAAoB;IACpB,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC;IAC1C,MAAM,UAAU,GAAG,OAAO,GAAG,OAAO,CAAC;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC;IAE9D,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACpC,KAAK,IAAI,mBAAmB,CAAC;IAC/B,CAAC;SAAM,IAAI,UAAU,GAAG,CAAC,IAAI,MAAM,GAAG,UAAU,GAAG,GAAG,EAAE,CAAC;QACvD,KAAK,IAAI,oBAAoB,CAAC;IAChC,CAAC;SAAM,CAAC;QACN,wEAAwE;QACxE,wEAAwE;QACxE,iBAAiB;QACjB,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC,CAAC;QAC/D,KAAK,IAAI,UAAU,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,gEAAgE;IAChE,uEAAuE;IACvE,yDAAyD;IACzD,IAAI,EAAE,CAAC,CAAC,GAAG,GAAG;QAAE,KAAK,IAAI,kBAAkB,CAAC;SACvC,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,GAAG,GAAG;QAAE,KAAK,IAAI,kBAAkB,GAAG,GAAG,CAAC;IAEjE,4BAA4B;IAC5B,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC;QAC/B,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;QAChC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAClC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAChC,oCAAoC;QACpC,IAAI,IAAI,GAAG,EAAE;YAAE,KAAK,IAAI,aAAa,CAAC;QACtC,0CAA0C;aACrC,IAAI,IAAI,GAAG,GAAG;YAAE,KAAK,IAAI,aAAa,GAAG,GAAG,CAAC;IACpD,CAAC;IAED,mDAAmD;IACnD,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,IAAI,EAAE,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,SAAS,KAAK,IAAI,CAAC,cAAc,EAAE,CAAC;QAChG,KAAK,IAAI,EAAE,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,YAAY,CAAC,QAA2B,EAAE,OAAiB,EAAE;IAC3E,mDAAmD;IACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/E,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnB,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAClC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,QAA2B,EAAE,OAAiB,EAAE;IAC7E,OAAO,QAAQ;SACZ,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;SAClD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/core/sense/reactive-check.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Layer C — reactive step discipline. After a consequential action, verify the
+ * agent-stated expected effect (hard) or a tolerant "did anything change" net
+ * (soft), so the agent never blindly proceeds on an action that didn't take.
+ * Pure over its inputs + PlatformAdapter reads (OS-agnostic, unit-testable).
+ * See docs/superpowers/specs/2026-06-07-ui-state-compiler-layer-c-design.md.
+ */
+import type { PlatformAdapter } from '../../platform/types';
+export interface ReactiveInput {
+    /** Raw `expect` arg from the tool call (assertions array), or undefined. */
+    expect: unknown;
+    /** The tool's own result text + success, to fold the note into. */
+    toolText: string;
+    toolSuccess: boolean;
+    /** Whether the tool is screen-changing (consequential). */
+    changesScreen: boolean;
+    /** Whether the loop observed a change after the action (fingerprint/pixel). */
+    observedChange: boolean;
+    adapter: PlatformAdapter;
+    /** Lazy OCR reader for ocr_contains assertions; omit when unavailable. */
+    ocrText?: () => Promise<string>;
+    /** Settle budget for hard checks (ms). Defaults to SETTLE_BUDGET_MS. */
+    settleMs?: number;
+}
+/**
+ * How long a failing hard check re-polls before declaring a DEVIATION. UIs
+ * are asynchronous: a recipient chip resolves via a directory lookup
+ * (0.5–3s), window titles update lazily after a save. Declaring DEVIATION
+ * off a single immediate check told the model to RETRY actions that had
+ * actually taken — a duplicate-send risk on Send/Submit (audit 2026-06-10,
+ * finding D1).
+ */
+export declare const SETTLE_BUDGET_MS = 2000;
+export declare const SETTLE_INTERVAL_MS = 250;
+/** A modified result (success/text) to replace the tool's, or null = leave as-is. */
+export interface ReactiveOutcome {
+    success: boolean;
+    text: string;
+}
+export declare function reactiveCheck(input: ReactiveInput): Promise<ReactiveOutcome | null>;