@xenon-device-management/xenon 2.14.0 → 2.16.0

package/lib/src/interceptors/CommandInterceptor.js

@@ -58,6 +58,8 @@ const event_manager_1 = require("../dashboard/event-manager");
 const SessionManager_1 = require("../sessions/SessionManager");
 const HealingOrchestrator_1 = require("../services/healing/HealingOrchestrator");
 const HealEtalonService_1 = require("../services/healing/HealEtalonService");
+const resilioPath_1 = require("../services/healing/resilioPath");
+const fingerprintIdentity_1 = require("../services/healing/fingerprintIdentity");
 const OmniVisionService_1 = require("../services/omni-vision/OmniVisionService");
 const AICommandService_1 = require("../services/AICommandService");
 const logger_1 = __importDefault(require("../logger"));
@@ -67,10 +69,46 @@ const AutowaitService_1 = require("../services/autowait/AutowaitService");
 const waitFor_1 = require("../services/autowait/waitFor");
 const SelfHealingSwitch_1 = require("../services/settings/SelfHealingSwitch");
 const xenonScripts_1 = require("./xenonScripts");
+const healReport_1 = require("../gateway/healReport");
+const W3C_ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
+/**
+ * The commands the interceptor answers itself for an element Xenon found in a
+ * screenshot (Omni-Vision's `-custom:ai-*` finds, self-healing's OCR and
+ * Visual AI tiers). Any other command naming one is refused.
+ */
+const VIRTUAL_ELEMENT_COMMANDS = [
+    'click',
+    'getElementRect',
+    'getElementLocation',
+    'getElementSize',
+    'getText',
+    'setValue',
+    'elementDisplayed',
+    'elementEnabled',
+];
+/** An id Xenon gave an element it found in a screenshot. */
+function isVirtualElementId(id) {
+    return (typeof id === 'string' &&
+        (id.startsWith('omni_') || id.startsWith('healed_ocr') || id.startsWith('healed_visual')));
+}
+/**
+ * The element an element command is about. Appium passes a command's body
+ * first and the ids from its path after it: setValue is (text, elementId),
+ * the other commands Xenon looks at are (elementId, ...). Through 2.14 the
+ * text of a setValue was read as its element.
+ */
+function elementIdOf(commandName, args) {
+    return commandName === 'setValue' ? args[1] : args[0];
+}
 let CommandInterceptor = class CommandInterceptor {
     constructor() {
         this.log = logger_1.default.scope('CommandInterceptor');
+        // The sessions already told about their healingTiers, by driver: a driver
+        // lives as long as its session, so nothing has to forget it.
+        this.warnedHealingTiers = new WeakSet();
         this.learningSessions = new Set();
+        /** Selectors whose fingerprint was learnt again for its path in this process (bounded). */
+        this.relearnt = new Set();
     }
     handle(next, driver, commandName, args, pluginArgs, isHub) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -80,6 +118,7 @@ let CommandInterceptor = class CommandInterceptor {
                 return yield next();
             const sessionId = driver.sessionId || args[args.length - 1];
             const tracingService = typedi_1.Container.get(TracingService_1.TracingService);
+            const spanId = `${sessionId}:${commandName}`;
             let span;
             if (isHub && sessionId) {
                 span = tracingService.startCommandSpan(sessionId, commandName, {
@@ -92,6 +131,7 @@ let CommandInterceptor = class CommandInterceptor {
             // those services having to accept a context parameter.
             const spanCtx = span === null || span === void 0 ? void 0 : span.spanContext();
             const cmdStart = Date.now();
+            let failure;
             try {
                 return yield sessionContext_1.sessionContext.run({
                     sessionId: sessionId || undefined,
@@ -99,9 +139,16 @@ let CommandInterceptor = class CommandInterceptor {
                     commandName,
                     traceId: spanCtx === null || spanCtx === void 0 ? void 0 : spanCtx.traceId,
                     spanId: spanCtx === null || spanCtx === void 0 ? void 0 : spanCtx.spanId,
-                }, () => this.handleInContext(next, driver, commandName, args, pluginArgs, isHub, sessionId, span, tracingService));
+                }, () => this.handleInContext(next, driver, commandName, args, pluginArgs, isHub, sessionId));
+            }
+            catch (error) {
+                // What the client gets: a healed find returned an element instead.
+                failure = { error };
+                throw error;
             }
             finally {
+                if (span)
+                    tracingService.endCommandSpan(spanId, span, failure);
                 // Aggregate counter — no per-session label, just fleet-wide throughput
                 // so Prom rate() gives commands/sec and the duration sum gives avg
                 // latency. Errors still count: a 429-hit dashboard poll is still hub
@@ -110,9 +157,8 @@ let CommandInterceptor = class CommandInterceptor {
             }
         });
     }
-    handleInContext(next, driver, commandName, args, pluginArgs, isHub, sessionId, span, tracingService) {
+    handleInContext(next, driver, commandName, args, pluginArgs, isHub, sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
             if (commandName === 'createSession' || commandName === 'deleteSession') {
                 try {
                     return yield next();
@@ -121,8 +167,6 @@ let CommandInterceptor = class CommandInterceptor {
                     if (commandName === 'deleteSession' && sessionId) {
                         typedi_1.Container.get(AutowaitService_1.AutowaitService).clearSession(sessionId);
                     }
-                    if (span)
-                        tracingService.endSpan(`${sessionId}:${commandName}`);
                 }
             }
             try {
@@ -144,7 +188,7 @@ let CommandInterceptor = class CommandInterceptor {
                                 scriptArgs = {};
                             }
                         }
-                        const aiCommand = script.replace(/^(xe|xenon)\s*:\s*/, '').trim();
+                        const aiCommand = (0, xenonScripts_1.interceptorScriptName)(script);
                         // appium-wait-plugin compatible alias — strip the `plugin:` prefix
                         // and map the old camelCase names so existing tests Just Work.
                         const legacyWaitCommand = script.replace(/^plugin\s*:\s*/, '').trim();
@@ -195,12 +239,7 @@ let CommandInterceptor = class CommandInterceptor {
                                     : '';
                             return yield typedi_1.Container.get(AICommandService_1.AICommandService).assertVisualState(driver, instruction);
                         }
-                        if (aiCommand === 'addMock' ||
-                            aiCommand === 'removeMock' ||
-                            aiCommand === 'clearMocks' ||
-                            aiCommand === 'getRequests' ||
-                            aiCommand === 'getMocks' ||
-                            aiCommand === 'exportHar') {
+                        if ((0, xenonScripts_1.isNetworkCaptureScript)(script)) {
                             const payload = typeof scriptArgs === 'object' && scriptArgs !== null ? scriptArgs : {};
                             const { InterceptorService } = yield Promise.resolve().then(() => __importStar(require('../services/InterceptorService')));
                             const interceptor = typedi_1.Container.get(InterceptorService);
@@ -254,37 +293,23 @@ let CommandInterceptor = class CommandInterceptor {
                     return yield this.handleOmniVisionSearch(sessionId, driver, commandName, strategy, selector);
                 }
                 // --- OMNI-VISION: VIRTUAL ELEMENT INTERACTION ---
-                const elementCommands = [
-                    'click',
-                    'getElementRect',
-                    'getElementLocation',
-                    'getElementSize',
-                    'getText',
-                    'setValue',
-                    'elementDisplayed',
-                    'elementEnabled',
-                ];
-                if (elementCommands.includes(commandName)) {
-                    const elementId = args[0];
-                    if (typeof elementId === 'string' &&
-                        (elementId.startsWith('omni_') ||
-                            elementId.startsWith('healed_ocr') ||
-                            elementId.startsWith('healed_visual'))) {
-                        return yield this.handleVirtualElementCommand(sessionId, driver, commandName, elementId, args[1]);
-                    }
+                // The driver doesn't know these elements, so nothing about one reaches it.
+                const virtualId = this.virtualElementIn(commandName, args, sessionId);
+                if (virtualId !== null) {
+                    return yield this.handleVirtualElementCommand(sessionId, driver, commandName, virtualId, args[0]);
                 }
                 // --- AUTOWAIT: pre-action elementEnabled check for click/setValue/clear ---
                 // Mirrors appium-wait-plugin behavior; runs before native command so
                 // a NotEnabled state surfaces as a wait-then-retry rather than an
                 // immediate failure. Skips elements managed by other Xenon subsystems.
                 const autowait = typedi_1.Container.get(AutowaitService_1.AutowaitService).getProps(sessionId, pluginArgs);
+                const actedOn = elementIdOf(commandName, args);
                 if (autowait.enabled &&
                     ['click', 'setValue', 'clear'].includes(commandName) &&
                     !autowait.excludeEnabledCheck.includes(commandName) &&
-                    typeof args[0] === 'string' &&
-                    !args[0].startsWith('omni_') &&
-                    !args[0].startsWith('healed_')) {
-                    yield this.waitForElementEnabled(driver, args[0], autowait);
+                    typeof actedOn === 'string' &&
+                    !isVirtualElementId(actedOn)) {
+                    yield this.waitForElementEnabled(driver, actedOn, autowait);
                 }
                 // --- AUTOWAIT: polling find for findElement/findElements ---
                 // Wraps next() in a poll loop so transient NoSuchElement errors get
@@ -296,91 +321,58 @@ let CommandInterceptor = class CommandInterceptor {
                     !this.isVisualStrategy(strategy)) {
                     const response = yield this.runFindWithAutowait(next, commandName, autowait);
                     if (isHub && !!pluginArgs.enableDashboard && SessionManager_1.SESSION_MANAGER.isValidSession(sessionId)) {
-                        yield this.runPostCommandHooks(sessionId, commandName, driver, args, response, pluginArgs);
+                        yield this.runPostCommandHooks(sessionId, commandName, driver, args, response);
                     }
+                    this.learnFromFind(sessionId, commandName, driver, args, response, pluginArgs);
                     return response;
                 }
                 const response = yield next();
                 if (isHub && !!pluginArgs.enableDashboard && SessionManager_1.SESSION_MANAGER.isValidSession(sessionId)) {
-                    yield this.runPostCommandHooks(sessionId, commandName, driver, args, response, pluginArgs);
+                    yield this.runPostCommandHooks(sessionId, commandName, driver, args, response);
                 }
+                this.learnFromFind(sessionId, commandName, driver, args, response, pluginArgs);
                 return response;
             }
             catch (error) {
                 if (this.isNoSuchElementError(error) &&
                     ['findElement', 'findElements'].includes(commandName) &&
+                    // A -custom:ai-* find already looked at the screen; the tiers would
+                    // only look again for the words of its description.
+                    !this.isVisualStrategy(args[0]) &&
                     typedi_1.Container.get(SelfHealingSwitch_1.SelfHealingSwitch).isEnabled(pluginArgs)) {
                     // §2.7 healing-tier capability gate: a session created with
                     // xe:options.healingTiers (or the xenon:options alias) restricts
                     // self-healing to those tier indices (1=Resilio, 2=Fuzzy XML, 3=OCR,
-                    // 4=Visual AI, 5=LLM).
-                    // Every optional hop is guarded — a missing/unrecoverable session,
-                    // capability, or malformed value all fall back to "run all tiers"
-                    // (fail open). coerceHealingTiersCap enforces that: an all-non-numeric
-                    // array (e.g. ["1","2"]) or an empty [] coerces to undefined instead
-                    // of [] — pre-fix, [] silently disabled healing entirely.
-                    const allowedHealingTiers = (0, HealingOrchestrator_1.healingTiersFromCaps)((_a = SessionManager_1.SESSION_MANAGER.getSession(sessionId)) === null || _a === void 0 ? void 0 : _a.getCapabilities());
-                    const healed = yield typedi_1.Container.get(HealingOrchestrator_1.HealingOrchestrator).attemptHealing(sessionId, driver, args[0], args[1], allowedHealingTiers);
+                    // 4=Visual AI, 5=LLM), and so keeps its screen from the AI provider.
+                    // Read from the session's own driver, which Appium hands the plugin
+                    // with every command. SESSION_MANAGER holds a local session only with
+                    // the dashboard on or a video recorded, and through 2.14 every other
+                    // session ran every tier. A value that isn't a list of tier numbers
+                    // runs only the tiers that stay on this server (coerceHealingTiersCap).
+                    const asked = (0, HealingOrchestrator_1.healingTiersFromCaps)(driver === null || driver === void 0 ? void 0 : driver.caps);
+                    if (asked.unreadable !== undefined) {
+                        this.warnUnreadableHealingTiers(driver, sessionId, asked.unreadable);
+                    }
+                    const healed = yield typedi_1.Container.get(HealingOrchestrator_1.HealingOrchestrator).attemptHealing(sessionId, driver, args[0], args[1], asked.tiers);
                     if (healed) {
-                        yield this.logHealingEvent(sessionId, commandName, driver, args, healed);
-                        let finalId = healed.id;
-                        // OCR/Visual AI tiers return virtual IDs with rect coordinates
-                        // We need to resolve a REAL element that Appium can interact with
+                        yield this.recordHeal(sessionId, commandName, driver, args, healed);
+                        // The OCR and Visual AI tiers can find only a position. The test gets
+                        // a virtual element there, which its own click taps; nothing acts on
+                        // the screen during the find. Through 2.14 the interceptor tapped
+                        // the spot here, so the test's click tapped it a second time. On an
+                        // iPhone it first asked for the first element covering the spot in
+                        // tree order, which is an outer container such as the window.
                         if (healed.id.startsWith('healed_') && healed.rect) {
-                            // REGISTER the virtual element for subsequent state checks
-                            typedi_1.Container.get(OmniVisionService_1.OmniVisionService).addVirtualElement({
+                            typedi_1.Container.get(OmniVisionService_1.OmniVisionService).remember(sessionId, {
                                 id: healed.id,
                                 rect: healed.rect,
                                 confidence: healed.confidence,
-                                text: healed.message,
+                                text: healed.text,
                             });
-                            this.log.info(`[Interceptor] Visual healing returned coordinates. Resolving real element at (${healed.rect.x}, ${healed.rect.y})...`);
-                            let resolved = false;
-                            // Strategy 1: Try to find element at the center of the detected area
-                            try {
-                                const cx = Math.round(healed.rect.x + healed.rect.width / 2);
-                                const cy = Math.round(healed.rect.y + healed.rect.height / 2);
-                                const touchEl = yield driver.findElement('-ios class chain', `**/XCUIElementTypeAny[\`rect.x <= ${cx} AND rect.x + rect.width >= ${cx} AND rect.y <= ${cy} AND rect.y + rect.height >= ${cy}\`]`);
-                                if (touchEl) {
-                                    finalId =
-                                        touchEl.ELEMENT || touchEl['element-6066-11e4-a52e-4f735466cecf'] || finalId;
-                                    resolved = !!finalId && !finalId.startsWith('healed_');
-                                }
-                            }
-                            catch (e) {
-                                // Strategy 1 failed
-                            }
-                            // Strategy 2: Use coordinate tap action (W3C Actions API)
-                            if (!resolved) {
-                                this.log.info('[Interceptor] Falling back to coordinate-based tap for visual healing');
-                                try {
-                                    const cx = Math.round(healed.rect.x + healed.rect.width / 2);
-                                    const cy = Math.round(healed.rect.y + healed.rect.height / 2);
-                                    yield driver.performActions([
-                                        {
-                                            type: 'pointer',
-                                            id: 'xenon-heal-tap',
-                                            parameters: { pointerType: 'touch' },
-                                            actions: [
-                                                { type: 'pointerMove', duration: 0, x: cx, y: cy },
-                                                { type: 'pointerDown', button: 0 },
-                                                { type: 'pause', duration: 100 },
-                                                { type: 'pointerUp', button: 0 },
-                                            ],
-                                        },
-                                    ]);
-                                    yield driver.releaseActions();
-                                    this.log.info(`[Interceptor] ✅ Visual healing: tapped at (${cx}, ${cy})`);
-                                    // Return the virtual ID — the tap already happened
-                                }
-                                catch (tapErr) {
-                                    this.log.error(`[Interceptor] Coordinate tap failed: ${tapErr.message}`);
-                                }
-                            }
                         }
                         const elementResponse = {
-                            ELEMENT: finalId,
-                            'element-6066-11e4-a52e-4f735466cecf': finalId,
+                            ELEMENT: healed.id,
+                            [W3C_ELEMENT_KEY]: healed.id,
                         };
                         return commandName === 'findElement' ? elementResponse : [elementResponse];
                     }
@@ -395,12 +387,18 @@ let CommandInterceptor = class CommandInterceptor {
                 }
                 throw error;
             }
-            finally {
-                if (isHub && sessionId && span)
-                    tracingService.endSpan(`${sessionId}:${commandName}`);
-            }
         });
     }
+    warnUnreadableHealingTiers(driver, sessionId, unreadable) {
+        if (driver && typeof driver === 'object') {
+            if (this.warnedHealingTiers.has(driver))
+                return;
+            this.warnedHealingTiers.add(driver);
+        }
+        this.log.warn(`Session ${sessionId}: ${unreadable}. It heals with tiers 1, 2 and 3 only (Resilio, ` +
+            'Fuzzy XML, OCR), which run on this server: healing never sends its screen to the AI ' +
+            'provider.');
+    }
     isNoSuchElementError(error) {
         var _a;
         return (error.name === 'NoSuchElementError' ||
@@ -466,7 +464,8 @@ let CommandInterceptor = class CommandInterceptor {
             }
         });
     }
-    runPostCommandHooks(sessionId, commandName, driver, args, response, pluginArgs) {
+    /** The dashboard's record of a command: only where enableDashboard records the session. */
+    runPostCommandHooks(sessionId, commandName, driver, args, response) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 yield event_manager_1.DASHBORD_EVENT_MANAGER.afterSessionCommand(sessionId, commandName, driver, {
@@ -475,17 +474,38 @@ let CommandInterceptor = class CommandInterceptor {
                     path: `/${commandName}`,
                     originalUrl: `/${commandName}`,
                 }, {}, JSON.stringify({ value: response, sessionId }));
-                if (commandName === 'findElement' &&
-                    response &&
-                    typedi_1.Container.get(SelfHealingSwitch_1.SelfHealingSwitch).isEnabled(pluginArgs)) {
-                    this.triggerLearning(driver, args, response, sessionId);
-                }
             }
             catch (postCommandErr) {
                 this.log.warn(`[Interceptor] Post-command hooks failed: ${postCommandErr.message}`);
             }
         });
     }
+    /**
+     * Learn the fingerprint of a selector a findElement found, which the Resilio
+     * and Fuzzy XML tiers heal it with later. On every session this server
+     * drives while self-healing is on, whatever enableDashboard says, nodes
+     * included. Through 2.14 it ran only behind the dashboard's record above,
+     * so a server with enableDashboard off, and every node, learnt nothing.
+     * A session that turned its own healing off (`healingTiers: []`) isn't
+     * learnt from, as the switch stops learning for every session.
+     * It reads the element in the background; the find has already answered.
+     */
+    learnFromFind(sessionId, commandName, driver, args, response, pluginArgs) {
+        var _a, _b;
+        // The find has its element: nothing here may fail it.
+        try {
+            if (commandName !== 'findElement' ||
+                !response ||
+                !typedi_1.Container.get(SelfHealingSwitch_1.SelfHealingSwitch).isEnabled(pluginArgs) ||
+                ((_a = (0, HealingOrchestrator_1.healingTiersFromCaps)(driver === null || driver === void 0 ? void 0 : driver.caps).tiers) === null || _a === void 0 ? void 0 : _a.length) === 0) {
+                return;
+            }
+            this.triggerLearning(driver, args, response, sessionId).catch((err) => { var _a; return this.log.debug(`[Learning] Failed: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`); });
+        }
+        catch (err) {
+            this.log.debug(`[Learning] Skipped: ${(_b = err === null || err === void 0 ? void 0 : err.message) !== null && _b !== void 0 ? _b : err}`);
+        }
+    }
     handleOmniVisionSearch(sessionId, driver, commandName, strategy, selector) {
         return __awaiter(this, void 0, void 0, function* () {
             const omniService = typedi_1.Container.get(OmniVisionService_1.OmniVisionService);
@@ -497,41 +517,70 @@ let CommandInterceptor = class CommandInterceptor {
                 if (match)
                     results = [match];
             }
+            // The session's test gets these ids, so the session keeps the elements.
+            for (const element of results)
+                omniService.remember(sessionId, element);
             const appiumResults = results.map((r) => ({
                 ELEMENT: r.id,
                 'element-6066-11e4-a52e-4f735466cecf': r.id,
             }));
             if (commandName === 'findElement') {
-                if (appiumResults.length === 0)
-                    throw new Error('NoSuchElement: AI Vision failed to find matching element');
+                if (appiumResults.length === 0) {
+                    const { errors } = yield Promise.resolve().then(() => __importStar(require('@appium/base-driver')));
+                    throw new errors.NoSuchElementError(`Xenon found nothing on the screen matching ${strategy} "${selector}".`);
+                }
                 return appiumResults[0];
             }
             return appiumResults;
         });
     }
+    /**
+     * The virtual element a command is about, or null. A command the
+     * interceptor answers for one is recognised by its element id; any other
+     * command naming a virtual element Xenon holds is caught too, so it is
+     * refused rather than sent to a driver that doesn't know the id.
+     */
+    virtualElementIn(commandName, args, sessionId) {
+        if (VIRTUAL_ELEMENT_COMMANDS.includes(commandName)) {
+            const id = elementIdOf(commandName, args);
+            return isVirtualElementId(id) ? id : null;
+        }
+        const omni = typedi_1.Container.get(OmniVisionService_1.OmniVisionService);
+        const named = args.find((a) => isVirtualElementId(a) && omni.getVirtualElement(a, sessionId));
+        return named !== null && named !== void 0 ? named : null;
+    }
+    tapAt(driver, x, y) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield driver.performActions([
+                {
+                    type: 'pointer',
+                    id: 'finger1',
+                    parameters: { pointerType: 'touch' },
+                    actions: [
+                        { type: 'pointerMove', duration: 0, x, y },
+                        { type: 'pointerDown', button: 0 },
+                        { type: 'pause', duration: 100 },
+                        { type: 'pointerUp', button: 0 },
+                    ],
+                },
+            ]);
+        });
+    }
     handleVirtualElementCommand(sessionId, driver, commandName, elementId, value) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { errors } = yield Promise.resolve().then(() => __importStar(require('@appium/base-driver')));
             const omniService = typedi_1.Container.get(OmniVisionService_1.OmniVisionService);
-            const element = omniService.getVirtualElement(elementId);
-            if (!element)
-                throw new Error(`NoSuchElement: Virtual element ${elementId} not found`);
+            // Another session's element is unknown here, as one that has gone is.
+            const element = omniService.getVirtualElement(elementId, sessionId);
+            if (!element) {
+                throw new errors.NoSuchElementError(`Xenon has no element ${elementId}.`);
+            }
             const centerX = Math.round(element.rect.x + element.rect.width / 2);
             const centerY = Math.round(element.rect.y + element.rect.height / 2);
             switch (commandName) {
                 case 'click':
-                    yield driver.performActions([
-                        {
-                            type: 'pointer',
-                            id: 'finger1',
-                            parameters: { pointerType: 'touch' },
-                            actions: [
-                                { type: 'pointerMove', duration: 0, x: centerX, y: centerY },
-                                { type: 'pointerDown', button: 0 },
-                                { type: 'pause', duration: 100 },
-                                { type: 'pointerUp', button: 0 },
-                            ],
-                        },
-                    ]);
+                    yield this.tapAt(driver, centerX, centerY);
                     return null;
                 case 'getElementRect':
                     return element.rect;
@@ -543,33 +592,50 @@ let CommandInterceptor = class CommandInterceptor {
                 case 'elementEnabled':
                     return true;
                 case 'getText':
-                    return element.text || '';
-                case 'setValue':
-                    yield driver.performActions([
-                        {
-                            type: 'pointer',
-                            id: 'finger1',
-                            parameters: { pointerType: 'touch' },
-                            actions: [
-                                { type: 'pointerMove', duration: 0, x: centerX, y: centerY },
-                                { type: 'pointerDown', button: 0 },
-                                { type: 'pause', duration: 100 },
-                                { type: 'pointerUp', button: 0 },
-                            ],
-                        },
-                    ]);
+                    // The text OCR read there. An element Visual AI found has none: it
+                    // used to answer '' (or, healed, Xenon's note about the match).
+                    if (typeof element.text === 'string')
+                        return element.text;
+                    throw new errors.UnsupportedOperationError(`Element ${elementId} was found by AI vision, which reads no text, so Xenon has no text for it.`);
+                case 'setValue': {
+                    // The driver doesn't know this element, so the text goes to the field
+                    // the tap gives the keyboard focus. A driver that can't say which
+                    // field that is gets no tap at all.
+                    if (typeof driver.active !== 'function') {
+                        throw new errors.UnsupportedOperationError(`Xenon can't type into ${elementId}, an element it found in a screenshot: ` +
+                            "this driver can't tell which field has the keyboard focus. Tap the element, then type with key actions.");
+                    }
+                    yield this.tapAt(driver, centerX, centerY);
+                    let focused = null;
                     try {
-                        return yield driver.setValue(elementId, value);
+                        focused = yield driver.active();
+                    }
+                    catch (_b) {
+                        focused = null;
+                    }
+                    const focusedId = (_a = focused === null || focused === void 0 ? void 0 : focused[W3C_ELEMENT_KEY]) !== null && _a !== void 0 ? _a : focused === null || focused === void 0 ? void 0 : focused.ELEMENT;
+                    if (typeof focusedId !== 'string' || !focusedId) {
+                        throw new errors.ElementNotInteractableError(`Xenon tapped ${elementId} at (${centerX}, ${centerY}), but no field took the keyboard focus, so there was nowhere to type.`);
+                    }
+                    try {
+                        return yield driver.setValue(value, focusedId);
                     }
                     catch (e) {
                         this.log.error(`setValue failed for virtual element ${elementId} on session ${sessionId}: ${e.message}`);
                         throw e;
                     }
+                }
                 default:
-                    throw new Error(`Command ${commandName} not supported for visual elements`);
+                    throw new errors.UnsupportedOperationError(`${commandName} isn't available on ${elementId}: Xenon found it in a screenshot, and ` +
+                        `it is only a position on the screen. It answers ${VIRTUAL_ELEMENT_COMMANDS.join(', ')}.`);
             }
         });
     }
+    rememberRelearnt(selector) {
+        if (this.relearnt.size >= 10000)
+            this.relearnt.clear();
+        this.relearnt.add(selector);
+    }
     triggerLearning(driver, args, response, sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.learningSessions.has(sessionId))
@@ -583,31 +649,34 @@ let CommandInterceptor = class CommandInterceptor {
                 return;
             }
             (() => __awaiter(this, void 0, void 0, function* () {
+                var _a;
                 try {
                     const etalonService = typedi_1.Container.get(HealEtalonService_1.HealEtalonService);
                     // CRITICAL PERFORMANCE OPTIMIZATION:
                     // Only trigger the heavy metadata collection if we don't already have an etalon for this selector.
                     // Collecting page source and element rects for every single action is too CPU-intensive.
+                    // A fingerprint stored without a usable path, or without anything
+                    // that says which element it is (all learnt ones through 2.14), is
+                    // learnt again, once per selector per process, so the Resilio tier
+                    // gets its path and Fuzzy XML can use it.
                     const existing = yield etalonService.getSignature(selector);
-                    if (existing) {
+                    const complete = existing && (0, resilioPath_1.isResilioPath)(existing.path) && (0, fingerprintIdentity_1.hasIdentity)(existing.attributes);
+                    if (existing && (complete || this.relearnt.has(selector))) {
                         this.log.debug(`[Learning] Etalon already exists for selector: ${selector}. Skipping...`);
                         return;
                     }
-                    const anchors = [
-                        'content-desc',
-                        'resource-id',
-                        'text',
-                        'name',
-                        'id',
-                        'hint',
-                        'label',
-                        'value', // iOS-specific identity attributes
-                    ];
+                    if (existing)
+                        this.rememberRelearnt(selector);
                     const nodeAttrs = [];
-                    for (const attr of anchors) {
+                    // The WebDriver command is getAttribute(name, elementId). Through
+                    // 2.14 this asked for getElementAttribute, which neither UiAutomator2
+                    // nor XCUITest has, so no attribute was ever read. Only the attributes
+                    // the driver has are asked for, and "null" (UiAutomator2's answer for
+                    // one the element hasn't set) isn't kept.
+                    for (const attr of (0, fingerprintIdentity_1.attributesToLearn)((_a = driver === null || driver === void 0 ? void 0 : driver.caps) === null || _a === void 0 ? void 0 : _a.platformName)) {
                         try {
-                            const val = yield driver.getElementAttribute(elementId, attr);
-                            if (val)
+                            const val = yield driver.getAttribute(attr, elementId);
+                            if ((0, fingerprintIdentity_1.meaningful)(val))
                                 nodeAttrs.push({ name: attr, value: val });
                         }
                         catch (e) {
@@ -652,22 +721,14 @@ let CommandInterceptor = class CommandInterceptor {
                     // Final safety check to ensure nodeName is a valid string
                     if (!nodeName)
                         nodeName = 'Unknown';
-                    // Path capture logic
+                    // The element's path through the page source, for the Resilio tier:
+                    // the element there that has the most of the attributes just read,
+                    // and none when two have as many.
                     let resiliotreePathJson = null;
                     try {
-                        const { JSDOMParser, Path } = yield Promise.resolve().then(() => __importStar(require('resiliotree')));
                         const pageSource = yield driver.getPageSource();
-                        const rootNode = new JSDOMParser().parse(pageSource);
-                        const foundNode = this.findMatchingNode(rootNode, nodeName, nodeAttrs);
-                        if (foundNode) {
-                            const pathNodes = [];
-                            let curr = foundNode;
-                            while (curr) {
-                                pathNodes.unshift(curr);
-                                curr = curr.parent;
-                            }
-                            resiliotreePathJson = new Path(pathNodes).toJSON();
-                        }
+                        const element = (0, resilioPath_1.findLearntElement)(pageSource, nodeName, nodeAttrs);
+                        resiliotreePathJson = element ? (0, resilioPath_1.resilioPathOf)(element, pageSource) : null;
                     }
                     catch (e) {
                         // Silently ignore: path capture is optional for learning
@@ -683,43 +744,42 @@ let CommandInterceptor = class CommandInterceptor {
             }))();
         });
     }
-    findMatchingNode(root, tag, attributes) {
-        const attrMap = new Map(attributes.map((a) => [a.name.toLowerCase(), a.value]));
-        const queue = [root];
-        while (queue.length > 0) {
-            const node = queue.shift();
-            if (node.tag.toLowerCase() === tag.toLowerCase()) {
-                let matchCount = 0;
-                for (const [name, value] of attrMap) {
-                    if (node.otherAttributes.get(name) === value ||
-                        node.id === value ||
-                        node.classes.has(value))
-                        matchCount++;
-                }
-                if (matchCount > 0)
-                    return node;
+    /**
+     * A heal of a command a hub sent goes back to the hub, which owns the
+     * session's record (healReport.ts); this server records any other.
+     */
+    recordHeal(sessionId, commandName, driver, args, healed) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const reported = (0, healReport_1.reportHeal)(this.healReportOf(args, healed));
+            if (reported === 'reported')
+                return;
+            if (reported === 'too-long') {
+                // The session is the hub's: this server has no record to write it to.
+                this.log.warn(`[Interceptor] The heal of ${args[0]}=${args[1]} is too long to send to the hub; it isn't recorded.`);
+                return;
             }
-            if (node.children)
-                queue.push(...node.children);
-        }
-        return null;
+            yield this.logHealingEvent(sessionId, commandName, driver, args, healed);
+        });
+    }
+    healReportOf(args, healed) {
+        var _a;
+        return {
+            originalSelector: args[1],
+            originalStrategy: args[0],
+            healedSelector: healed.recommendedSelector,
+            healedStrategy: (_a = healed.recommendedStrategy) !== null && _a !== void 0 ? _a : args[0],
+            confidence: healed.confidence,
+            tier: healed.tier,
+        };
     }
     logHealingEvent(sessionId, commandName, driver, args, healed) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
             yield event_manager_1.DASHBORD_EVENT_MANAGER.afterSessionCommand(sessionId, commandName, driver, {
                 body: args,
                 method: 'POST',
                 path: `/${commandName}`,
                 originalUrl: `/${commandName}`,
-            }, {}, JSON.stringify({ value: { ELEMENT: healed.id }, sessionId }), {
-                originalSelector: args[1],
-                originalStrategy: args[0],
-                healedSelector: healed.recommendedSelector,
-                healedStrategy: (_a = healed.recommendedStrategy) !== null && _a !== void 0 ? _a : args[0],
-                confidence: healed.confidence,
-                tier: healed.tier,
-            });
+            }, {}, JSON.stringify({ value: { ELEMENT: healed.id }, sessionId }), this.healReportOf(args, healed));
         });
     }
 };