@xenon-device-management/xenon 2.13.2 → 2.14.0

package/lib/src/app/routers/streamType.js

@@ -9,10 +9,15 @@ exports.resolveStreamType = resolveStreamType;
  * MJPEG path so the recording pipeline (which reads the MJPEG server) is
  * unaffected (spec phase-1 rule). iOS/tvOS always use MJPEG (WDA emits it
  * directly).
+ *
+ * `clientCanPlayH264` is false when the page that starts the stream shows
+ * MJPEG: device control, or a browser without WebCodecs (exposed only on
+ * https and localhost). Starting an H.264 capture for it would run a second
+ * capture beside the screencap loop its `<img>` starts.
  */
-function resolveStreamType(platform, flagOn, recording) {
+function resolveStreamType(platform, flagOn, recording, clientCanPlayH264 = true) {
     const isAndroid = platform === 'android' || platform === 'androidtv' || platform === 'android-tv';
-    if (!isAndroid || !flagOn || recording)
+    if (!isAndroid || !flagOn || recording || !clientCanPlayH264)
         return 'mjpeg';
     return 'h264';
 }

package/lib/src/app/routers/webhook.js

@@ -14,6 +14,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const express_1 = require("express");
 const NotificationService_1 = require("../../services/NotificationService");
+const webhookEvents_1 = require("../../services/webhookEvents");
 const typedi_1 = require("typedi");
 const logger_1 = __importDefault(require("../../logger"));
 const scopeGuard_1 = require("../../middleware/scopeGuard");
@@ -63,17 +64,20 @@ function deleteConfig(req, res) {
         }
     });
 }
-// Sends a sample event the way the webhook's real events go out (its type
-// and template), and says whether it was delivered.
+// Sends a sample of an event the way the webhook's real events go out (its
+// type and template), and says whether it was delivered.
 function testWebhook(req, res) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b;
-        const { url, type, payloadTemplate } = (_a = req.body) !== null && _a !== void 0 ? _a : {};
+        const { url, type, payloadTemplate, event } = (_a = req.body) !== null && _a !== void 0 ? _a : {};
         if (!url || typeof url !== 'string') {
             return res.status(400).json({ error: 'url is required' });
         }
+        if (event !== undefined && !(0, webhookEvents_1.isEventType)(event)) {
+            return res.status(400).json({ error: `event must be one of: ${webhookEvents_1.EVENT_TYPES.join(', ')}` });
+        }
         try {
-            yield typedi_1.Container.get(NotificationService_1.NotificationService).sendTest(url, type || 'slack', payloadTemplate);
+            yield typedi_1.Container.get(NotificationService_1.NotificationService).sendTest(url, type || 'slack', payloadTemplate, event);
             res.json({ success: true });
         }
         catch (err) {

package/lib/src/config.js

@@ -32,14 +32,20 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.config = void 0;
+exports.config = exports.DEFAULT_MAX_CONCURRENT_RECORDINGS = void 0;
 exports.updateConfig = updateConfig;
 exports.resolveAuthDisabled = resolveAuthDisabled;
+exports.resolveMaxConcurrentRecordings = resolveMaxConcurrentRecordings;
+exports.resolveRecordingsAssetsPath = resolveRecordingsAssetsPath;
+exports.recordingConfigFrom = recordingConfigFrom;
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const basePath = path.join(os.homedir(), '.cache', 'xenon');
+/** Where free-form recordings go unless the option or the environment says otherwise. */
+const DEFAULT_RECORDINGS_ASSETS_PATH = path.join(basePath, 'assets', 'sessions', 'recordings');
+/** The server-wide cap on simultaneous free-form recordings, unless set. */
+exports.DEFAULT_MAX_CONCURRENT_RECORDINGS = 4;
 exports.config = {
     cacheDir: basePath,
     databaseProvider: process.env.XENON_DB_PROVIDER || 'sqlite',
@@ -87,9 +93,8 @@ exports.config = {
     passwordResetLogFallback: process.env.XENON_PASSWORD_RESET_LOG_FALLBACK === 'true',
     resetRateLimitAttempts: Number(process.env.XENON_RESET_RATE_LIMIT_ATTEMPTS) || 3,
     resetRateLimitWindowMs: Number(process.env.XENON_RESET_RATE_LIMIT_WINDOW_MS) || 15 * 60 * 1000,
-    recordingsAssetsPath: process.env.XENON_RECORDINGS_ASSETS_PATH ||
-        path.join(basePath, 'assets', 'sessions', 'recordings'),
-    maxConcurrentRecordings: Number((_a = process.env.XENON_MAX_CONCURRENT_RECORDINGS) !== null && _a !== void 0 ? _a : 4),
+    recordingsAssetsPath: resolveRecordingsAssetsPath(undefined, process.env.XENON_RECORDINGS_ASSETS_PATH),
+    maxConcurrentRecordings: resolveMaxConcurrentRecordings(undefined, process.env.XENON_MAX_CONCURRENT_RECORDINGS),
 };
 function updateConfig(newConfig) {
     Object.assign(exports.config, newConfig);
@@ -113,3 +118,43 @@ function updateConfig(newConfig) {
 function resolveAuthDisabled(pluginArgValue, envDisabled) {
     return pluginArgValue === true || envDisabled === true;
 }
+function wholeNumberAtLeastOne(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : undefined;
+}
+function nonBlankString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/**
+ * The cap on simultaneous free-form recordings: the `maxConcurrentRecordings`
+ * plugin option when it is set, else XENON_MAX_CONCURRENT_RECORDINGS, else 4.
+ * Both options are `schema.json` options Appium accepts, but only the variable
+ * was ever read. A value that is not a whole number of at least 1 is ignored,
+ * so the next source answers: the variable used to be taken as `Number(env)`,
+ * and `many` made that NaN, which no recording count exceeds (no cap at all).
+ * Pure, so the precedence is testable without booting a server.
+ */
+function resolveMaxConcurrentRecordings(optionValue, envValue) {
+    var _a, _b;
+    const fromEnv = (envValue === null || envValue === void 0 ? void 0 : envValue.trim()) ? Number(envValue) : undefined;
+    return ((_b = (_a = wholeNumberAtLeastOne(optionValue)) !== null && _a !== void 0 ? _a : wholeNumberAtLeastOne(fromEnv)) !== null && _b !== void 0 ? _b : exports.DEFAULT_MAX_CONCURRENT_RECORDINGS);
+}
+/**
+ * Where free-form recordings are stored: the `recordingsAssetsPath` plugin
+ * option when it is set, else XENON_RECORDINGS_ASSETS_PATH, else
+ * `~/.cache/xenon/assets/sessions/recordings`. A blank value counts as unset.
+ */
+function resolveRecordingsAssetsPath(optionValue, envValue) {
+    var _a, _b;
+    return (_b = (_a = nonBlankString(optionValue)) !== null && _a !== void 0 ? _a : nonBlankString(envValue)) !== null && _b !== void 0 ? _b : DEFAULT_RECORDINGS_ASSETS_PATH;
+}
+/**
+ * The part of `config` the recording plugin options set, from the options the
+ * server started with and the environment as it is now. Applied at boot,
+ * before the artifact store and the concurrency gate read them.
+ */
+function recordingConfigFrom(pluginArgs, env = process.env) {
+    return {
+        maxConcurrentRecordings: resolveMaxConcurrentRecordings(pluginArgs.maxConcurrentRecordings, env.XENON_MAX_CONCURRENT_RECORDINGS),
+        recordingsAssetsPath: resolveRecordingsAssetsPath(pluginArgs.recordingsAssetsPath, env.XENON_RECORDINGS_ASSETS_PATH),
+    };
+}

package/lib/src/dashboard/commands.js

@@ -45,56 +45,123 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dashboardCommands = exports.DashboardCommands = void 0;
+exports.dashboardCommands = exports.DashboardCommands = exports.SESSION_DETAILS_COMMANDS = void 0;
+exports.sessionDetailsCommandOf = sessionDetailsCommandOf;
 const session_service_1 = require("./services/session-service");
 const prisma_1 = require("../prisma");
 const logger_1 = __importDefault(require("../logger"));
-const lodash_1 = __importDefault(require("lodash"));
 const SessionManager_1 = require("../sessions/SessionManager");
 const asset_manager_1 = require("./asset-manager");
+const xenonScripts_1 = require("../interceptors/xenonScripts");
+/**
+ * The execute commands that write to a session's record (its Session row):
+ * `driver.execute('xenon: setSessionName', 'Checkout')` and the like.
+ *
+ * Each answers `{ recorded: true }` when it wrote, or `{ recorded: false,
+ * message }` saying why nothing was written: no record of the session on this
+ * server (its dashboard is off, or it is a node, which keeps none for the
+ * hub's sessions), an argument it can't use, or a failed write. None of them
+ * fails the test's command. They are bookkeeping, and a test shouldn't die
+ * because the server it ran on keeps no dashboard. Through 2.13.2
+ * setSessionName, setSessionStatus and debug failed the command there
+ * (Prisma's P2025, a foreign-key error), and addTag and captureEvidence
+ * answered `null` as if they had worked.
+ */
+exports.SESSION_DETAILS_COMMANDS = [
+    'setSessionName',
+    'setSessionStatus',
+    'debug',
+    'addTag',
+    'captureEvidence',
+];
+const RECORDED = { recorded: true };
+const notRecorded = (message) => ({ recorded: false, message });
+/** The session-details command a script names (`xenon: addTag`), or null for any other script. */
+function sessionDetailsCommandOf(script) {
+    const name = (0, xenonScripts_1.xenonScriptName)(script);
+    return name !== null && exports.SESSION_DETAILS_COMMANDS.includes(name)
+        ? name
+        : null;
+}
+/** The script's arguments as a list, as both the W3C body and Appium's executeScript give them. */
+function argumentList(args) {
+    if (Array.isArray(args))
+        return args;
+    return args === undefined || args === null ? [] : [args];
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** A string argument, or the named field of an object argument. */
+function stringArg(value, field) {
+    if (typeof value === 'string')
+        return value;
+    if (isObject(value) && typeof value[field] === 'string')
+        return value[field];
+    return undefined;
+}
 class DashboardCommands {
-    isDashboardCommand(commandName) {
-        return commandName.startsWith('xenon') || commandName.startsWith('xe');
-    }
+    /**
+     * Answers a session-details command on an Express-style response, as
+     * `{ value: <answer> }`, and returns the answer. The hub's gateway passes
+     * the client's response; CommandInterceptor passes one that keeps it.
+     */
     process(sessionId, request, response) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { script } = request.body;
-            logger_1.default.info(`[DashboardCommands] Processing command: ${script}`);
-            if (!script) {
-                return this.sendSuccessResponse(response);
-            }
-            const commandName = script.split(':')[1];
-            logger_1.default.info(`[DashboardCommands] Parsed command name: ${commandName}`);
-            if (commandName && commandName.trim()) {
-                const trimmedCommand = commandName.trim();
-                logger_1.default.info(`[DashboardCommands] Trimmed command: ${trimmedCommand}`);
-                switch (trimmedCommand) {
-                    case 'setSessionName':
-                        logger_1.default.info('[DashboardCommands] Executing setSessionName');
-                        return yield this.setSessionName(sessionId, request, response);
-                    case 'setSessionStatus':
-                        logger_1.default.info('[DashboardCommands] Executing setSessionStatus');
-                        return yield this.setSessionStatus(sessionId, request, response);
-                    case 'debug':
-                        logger_1.default.info('[DashboardCommands] Executing debug command');
-                        return yield this.debug(sessionId, request, response);
-                    case 'captureEvidence':
-                        logger_1.default.info('[DashboardCommands] Executing captureEvidence');
-                        return yield this.captureEvidence(sessionId, request, response);
-                    case 'addTag':
-                        logger_1.default.info('[DashboardCommands] Executing addTag');
-                        return yield this.addTag(sessionId, request, response);
-                    default:
-                        logger_1.default.warn(`[DashboardCommands] Unknown command: ${trimmedCommand}`);
-                        return this.sendSuccessResponse(response);
+            var _a;
+            const { script, args } = (_a = request.body) !== null && _a !== void 0 ? _a : {};
+            const command = sessionDetailsCommandOf(script);
+            const answer = command
+                ? yield this.run(sessionId, command, args)
+                : notRecorded(`"${script}" is not a command that records session details.`);
+            response.status(200).json({ value: answer });
+            return answer;
+        });
+    }
+    /** Runs one command. Never throws: a failure is `{ recorded: false, message }`. */
+    run(sessionId, command, args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            logger_1.default.info(`[DashboardCommands] ${command} for session ${sessionId}`);
+            const list = argumentList(args);
+            let answer;
+            try {
+                const row = yield prisma_1.prisma.session.findUnique({
+                    where: { id: sessionId },
+                    select: { id: true, tags: true },
+                });
+                if (!row) {
+                    answer = notRecorded(`This server keeps no record of session ${sessionId}, so nothing was saved. ` +
+                        'Sessions are recorded on a hub with its dashboard turned on.');
+                }
+                else {
+                    switch (command) {
+                        case 'setSessionName':
+                            answer = yield this.setSessionName(sessionId, list);
+                            break;
+                        case 'setSessionStatus':
+                            answer = yield this.setSessionStatus(sessionId, list);
+                            break;
+                        case 'debug':
+                            answer = yield this.debug(sessionId, list);
+                            break;
+                        case 'captureEvidence':
+                            answer = yield this.captureEvidence(sessionId, list);
+                            break;
+                        case 'addTag':
+                            answer = yield this.addTag(sessionId, list, row.tags);
+                            break;
+                    }
                 }
             }
-            return this.sendSuccessResponse(response);
+            catch (err) {
+                answer = notRecorded(`Xenon could not save it: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
+            }
+            if (!answer.recorded)
+                logger_1.default.warn(`[DashboardCommands] ${command}: ${answer.message}`);
+            return answer;
         });
     }
-    sendSuccessResponse(response) {
-        return response.status(200).json({ value: null });
-    }
     /* Commands */
     /**
      * Set the name of current test(session)
@@ -103,63 +170,50 @@ class DashboardCommands {
      * or
      * driver.executeScript("xenon: setSessionName", {"name": "MyTestName"})
      */
-    setSessionName(sessionId, request, response) {
+    setSessionName(sessionId, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { args } = request.body;
-            yield (0, session_service_1.updateSessionDetails)(sessionId, {
-                name: typeof args[0] === 'object' && args[0].name ? args[0].name : args[0],
-            });
-            return this.sendSuccessResponse(response);
+            const name = stringArg(args[0], 'name');
+            if (!name || !name.trim()) {
+                return notRecorded('setSessionName needs a name, as a string or { name }.');
+            }
+            yield (0, session_service_1.updateSessionDetails)(sessionId, { name });
+            return RECORDED;
         });
     }
     /**
      * Update the status of the session
      *
      * driver.executeScript("xenon: setSessionStatus", {"status": "passed/failed", "reason": "optional reason"})
+     * or, positionally, ("xe:setSessionStatus", "failed", "reason")
      */
-    setSessionStatus(sessionId, request, response) {
+    setSessionStatus(sessionId, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { args } = request.body;
-            let statusArg = {};
-            if (lodash_1.default.isArray(args)) {
-                if (typeof args[0] === 'object') {
-                    statusArg = args[0];
-                }
-                else {
-                    // Handle positional: executeScript("xe:setSessionStatus", "failed", "reason")
-                    statusArg = {
-                        status: args[0],
-                        reason: args[1],
-                    };
-                }
-            }
-            else if (typeof args === 'object') {
-                statusArg = args;
-            }
-            // Normalize input
-            const inputStatus = (statusArg.status || '').toLowerCase();
+            const statusArg = isObject(args[0]) ? args[0] : { status: args[0], reason: args[1] };
+            const given = statusArg.status;
+            const inputStatus = typeof given === 'string' ? given.toLowerCase() : '';
             const validStatuses = ['success', 'failed', 'passed'];
             if (!validStatuses.includes(inputStatus)) {
-                logger_1.default.warn(`[DashboardCommands] Invalid status: ${statusArg.status}. Valid: ${validStatuses.join(', ')}`);
-                return this.sendSuccessResponse(response);
+                return notRecorded('setSessionStatus takes "passed" or "failed" ("success" also means passed); ' +
+                    `it was given ${JSON.stringify(given !== null && given !== void 0 ? given : null)}.`);
             }
             // Normalize 'passed' to 'success' for consistency with SessionStatus enum
             const normalizedStatus = inputStatus === 'passed' ? 'success' : inputStatus;
+            const reason = typeof statusArg.reason === 'string' ? statusArg.reason : undefined;
             const updated = yield (0, session_service_1.updateSessionDetails)(sessionId, {
                 status: normalizedStatus,
-                failure_reason: statusArg.reason || undefined,
+                failure_reason: reason || undefined,
             });
             // --- REAL-TIME UI UPDATE ---
-            // Principal Speed: Emit a socket event so the dashboard row updates immediately.
+            // Emit a socket event so the dashboard row updates immediately.
             const { SocketServer } = yield Promise.resolve().then(() => __importStar(require('../services/SocketServer')));
             const { Container } = yield Promise.resolve().then(() => __importStar(require('typedi')));
             const { SocketEvents } = yield Promise.resolve().then(() => __importStar(require('../enums/SocketEvents')));
             void Container.get(SocketServer).emitToDashboardForDevices(SocketEvents.SESSION_STOPPED, {
                 id: sessionId,
                 status: normalizedStatus,
-                failure_reason: args.reason || undefined,
+                failure_reason: reason || undefined,
             }, { udid: updated === null || updated === void 0 ? void 0 : updated.device_udid });
-            return this.sendSuccessResponse(response);
+            return RECORDED;
         });
     }
     /**
@@ -169,12 +223,18 @@ class DashboardCommands {
      * or
      * driver.executeScript("xenon: debug", "Debug message")
      */
-    debug(sessionId, request, response) {
+    debug(sessionId, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { args } = request.body;
-            const logData = lodash_1.default.isArray(args) ? args[0] : args;
-            // Support both string and object format
-            const message = typeof logData === 'string' ? logData : logData.message || JSON.stringify(logData);
+            const logData = args[0];
+            let message;
+            if (typeof logData === 'string')
+                message = logData;
+            else if (isObject(logData)) {
+                message = typeof logData.message === 'string' ? logData.message : JSON.stringify(logData);
+            }
+            if (!message) {
+                return notRecorded('debug needs a message, as a string or { message }.');
+            }
             yield prisma_1.prisma.log.create({
                 data: {
                     session_id: sessionId,
@@ -182,7 +242,7 @@ class DashboardCommands {
                     message: message,
                 },
             });
-            return this.sendSuccessResponse(response);
+            return RECORDED;
         });
     }
     /**
@@ -192,44 +252,43 @@ class DashboardCommands {
      * or
      * driver.executeScript("xenon: captureEvidence", "Checkpoint reached")
      */
-    captureEvidence(sessionId, request, response) {
+    captureEvidence(sessionId, args) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { args } = request.body;
-            const evidenceData = lodash_1.default.isArray(args) ? args[0] : args;
-            const reason = typeof evidenceData === 'string' ? evidenceData : evidenceData.reason || 'Manual capture';
-            const label = typeof evidenceData === 'object' ? evidenceData.label : undefined;
+            var _a;
+            const evidenceData = args[0];
+            const reason = stringArg(evidenceData, 'reason') || 'Manual capture';
+            const label = isObject(evidenceData) ? evidenceData.label : undefined;
+            const session = SessionManager_1.SESSION_MANAGER.getSession(sessionId);
+            if (!session) {
+                return notRecorded(`Session ${sessionId} isn't running here, so no screenshot was taken.`);
+            }
+            let screenshotBase64;
             try {
-                const session = SessionManager_1.SESSION_MANAGER.getSession(sessionId);
-                if (!session) {
-                    logger_1.default.warn(`[DashboardCommands] captureEvidence: Session ${sessionId} not found`);
-                    return this.sendSuccessResponse(response);
-                }
-                const screenshotBase64 = yield session.getScreenShot();
-                if (screenshotBase64) {
-                    const screenshotPath = (0, asset_manager_1.saveScreenShot)(sessionId, screenshotBase64);
-                    // Log the evidence capture
-                    yield prisma_1.prisma.sessionLog.create({
-                        data: {
-                            session_id: sessionId,
-                            command_name: 'captureEvidence',
-                            body: JSON.stringify({ reason, label }),
-                            response: JSON.stringify({ captured: true }),
-                            is_success: true,
-                            is_error: false,
-                            method: 'POST',
-                            title: 'Evidence Captured',
-                            subtitle: reason,
-                            screenshot: screenshotPath,
-                            url: '/execute/sync',
-                        },
-                    });
-                    logger_1.default.info(`[DashboardCommands] Evidence captured for ${sessionId}: ${reason}`);
-                }
+                screenshotBase64 = yield session.getScreenShot();
             }
             catch (err) {
-                logger_1.default.error(`[DashboardCommands] captureEvidence failed: ${err.message}`);
+                return notRecorded(`No screenshot could be taken: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
             }
-            return this.sendSuccessResponse(response);
+            if (!screenshotBase64)
+                return notRecorded('No screenshot could be taken.');
+            const screenshotPath = (0, asset_manager_1.saveScreenShot)(sessionId, screenshotBase64);
+            yield prisma_1.prisma.sessionLog.create({
+                data: {
+                    session_id: sessionId,
+                    command_name: 'captureEvidence',
+                    body: JSON.stringify({ reason, label }),
+                    response: JSON.stringify({ captured: true }),
+                    is_success: true,
+                    is_error: false,
+                    method: 'POST',
+                    title: 'Evidence Captured',
+                    subtitle: reason,
+                    screenshot: screenshotPath,
+                    url: '/execute/sync',
+                },
+            });
+            logger_1.default.info(`[DashboardCommands] Evidence captured for ${sessionId}: ${reason}`);
+            return RECORDED;
         });
     }
     /**
@@ -239,44 +298,29 @@ class DashboardCommands {
      * or
      * driver.executeScript("xenon: addTag", "smoke-test")
      */
-    addTag(sessionId, request, response) {
+    addTag(sessionId, args, tags) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { args } = request.body;
-            const tagData = lodash_1.default.isArray(args) ? args[0] : args;
-            const newTag = typeof tagData === 'string' ? tagData : tagData.tag;
-            if (!newTag) {
-                logger_1.default.warn('[DashboardCommands] addTag: No tag provided');
-                return this.sendSuccessResponse(response);
+            const newTag = stringArg(args[0], 'tag');
+            if (!newTag || !newTag.trim()) {
+                return notRecorded('addTag needs a tag, as a string or { tag }.');
             }
-            try {
-                // Get current session to append tag
-                const session = yield prisma_1.prisma.session.findUnique({
-                    where: { id: sessionId },
-                    select: { tags: true },
-                });
-                // Parse existing tags or initialize empty array
-                let existingTags = [];
-                if (session === null || session === void 0 ? void 0 : session.tags) {
-                    try {
-                        existingTags = JSON.parse(session.tags);
-                    }
-                    catch (_a) {
-                        existingTags = [];
-                    }
+            let existingTags = [];
+            if (tags) {
+                try {
+                    const parsed = JSON.parse(tags);
+                    if (Array.isArray(parsed))
+                        existingTags = parsed;
                 }
-                // Add new tag if not already present
-                if (!existingTags.includes(newTag)) {
-                    existingTags.push(newTag);
-                    yield (0, session_service_1.updateSessionDetails)(sessionId, {
-                        tags: JSON.stringify(existingTags),
-                    });
-                    logger_1.default.info(`[DashboardCommands] Tag added to ${sessionId}: ${newTag}`);
+                catch (_a) {
+                    existingTags = [];
                 }
             }
-            catch (err) {
-                logger_1.default.error(`[DashboardCommands] addTag failed: ${err.message}`);
+            if (!existingTags.includes(newTag)) {
+                existingTags.push(newTag);
+                yield (0, session_service_1.updateSessionDetails)(sessionId, { tags: JSON.stringify(existingTags) });
+                logger_1.default.info(`[DashboardCommands] Tag added to ${sessionId}: ${newTag}`);
             }
-            return this.sendSuccessResponse(response);
+            return RECORDED;
         });
     }
 }

package/lib/src/dashboard/event-manager.js

@@ -78,6 +78,7 @@ const SocketEvents_1 = require("../enums/SocketEvents");
 const types_1 = require("../services/healing/types");
 const SelectorStateService_1 = require("../services/SelectorStateService");
 const recording_store_1 = require("../services/recording/recording-store");
+const NotificationService_1 = require("../services/NotificationService");
 const SessionMetricsService_1 = require("../services/metrics/SessionMetricsService");
 const nodeMetrics_1 = require("../services/metrics/nodeMetrics");
 const typedi_2 = require("typedi");
@@ -190,8 +191,16 @@ let DashboardEventManager = class DashboardEventManager {
             }
         });
     }
-    onSessionStopped(sessionId, status, failureReason) {
-        return __awaiter(this, void 0, void 0, function* () {
+    /**
+     * Closes a session's record: its end time, its final status, the device's
+     * release. Every way a session ends comes here (the client's delete, an
+     * inactivity timeout, a driver crash, a heartbeat timeout, a shutdown), so
+     * this is where a failed one is announced to the `session_failed` webhooks.
+     * `notify: false` records the failure without announcing it: a server
+     * shutting down fails the sessions it drains, which no test caused.
+     */
+    onSessionStopped(sessionId_1, status_1, failureReason_1) {
+        return __awaiter(this, arguments, void 0, function* (sessionId, status, failureReason, options = {}) {
             var _a, _b, _c, _d;
             // Idempotency Guard: If this session is already being stopped by another actor
             // (heartbeat, stream watchdog, plugin.deleteSession), skip to avoid double-cleanup.
@@ -341,6 +350,12 @@ let DashboardEventManager = class DashboardEventManager {
                     else if (updateData.status === SessionStatus_1.SessionStatus.FAILED) {
                         typedi_1.Container.get(MetricsService_1.MetricsService).incrementSessionFailure();
                     }
+                    // Webhooks: not awaited, since a slow or dead webhook must not hold up
+                    // the end of the session. The service sends once per session even
+                    // though a session can end twice (a crash, then the client's delete).
+                    if (updateData.status === SessionStatus_1.SessionStatus.FAILED && options.notify !== false) {
+                        this.announceFailure(Object.assign(Object.assign({}, sessionEntry), updateData));
+                    }
                     // Principal Triage: If session failed, perform intelligent failure analysis
                     if (updateData.status === SessionStatus_1.SessionStatus.FAILED) {
                         try {
@@ -363,6 +378,18 @@ let DashboardEventManager = class DashboardEventManager {
             }
         });
     }
+    /** Starts the `session_failed` webhooks; never throws and never waits for them. */
+    announceFailure(session) {
+        var _a;
+        try {
+            void typedi_1.Container.get(NotificationService_1.NotificationService)
+                .notifySessionFailed(session)
+                .catch((err) => { var _a; return logger_1.default.warn(`session_failed webhook for ${session.id} not sent: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`); });
+        }
+        catch (err) {
+            logger_1.default.warn(`session_failed webhook for ${session.id} not sent: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
+        }
+    }
     beforeSessionCommand(sessionId, commandName, request, response) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -370,16 +397,22 @@ let DashboardEventManager = class DashboardEventManager {
                 this.commandStartTime.set(`${sessionId}:${commandName}`, Date.now());
                 logger_1.default.debug(`[EventManager] beforeSessionCommand: sessionId=${sessionId}, commandName=${commandName}`);
             }
-            // Principal Interception: Handle Xenon-specific commands regardless of session state in memory
+            // The session-details commands (`xenon: setSessionName`, ...) are answered
+            // here, from this server's record of the session, whether or not the
+            // session is in memory. Every other `xenon:` script goes on: to the
+            // plugin's CommandInterceptor on the server that drives the phone, which
+            // a hub reaches by forwarding it. Taking them all here answered a node
+            // phone's autowait, Omni-Vision and network-capture scripts with null on
+            // the hub, and they never reached the node.
             if (commandName === 'execute') {
                 const script = ((_a = request.body) === null || _a === void 0 ? void 0 : _a.script) || (Array.isArray(request.body) ? request.body[0] : undefined);
-                if (script && commands_1.dashboardCommands.isDashboardCommand(script)) {
+                if ((0, commands_1.sessionDetailsCommandOf)(script)) {
                     logger_1.default.info(`[EventManager] Intercepting Xenon command: ${script} for session ${sessionId}`);
                     yield commands_1.dashboardCommands.process(sessionId, request, response);
                     return false;
                 }
-                else if (script && script.includes(':')) {
-                    logger_1.default.debug(`[EventManager] Custom command ${script} not handled by Xenon. Passing to driver.`);
+                else if (typeof script === 'string' && script.includes(':')) {
+                    logger_1.default.debug(`[EventManager] Script ${script} is not a session-details command; passing it on.`);
                 }
             }
             const session = SessionManager_1.SESSION_MANAGER.getSession(sessionId);