@xenon-device-management/xenon 2.13.2 → 2.14.0

package/lib/src/generated/client/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "prisma-client-ef3fbf8faed5c4c712a2dce2686e5afc3ad0aa576aedb9c4cd9e5c99cfc0f03c",
+  "name": "prisma-client-ec1ae6fb328d1bc102086acd1f77e77477081d17b653d7f5092f083d0c8a4d34",
   "main": "index.js",
   "types": "index.d.ts",
   "browser": "index-browser.js",

package/lib/src/generated/client/schema.prisma

@@ -242,6 +242,33 @@ model Device {
   @@index([claimSessionId])
 }
 
+/// The settings people give one phone (an admin's team, tags and maintenance,
+/// a member's reservation), kept apart from its Device row. That row is
+/// deleted whenever the phone goes: unplugged, rebooted, offline in adb, a
+/// restart, its node gone. This one stays, and a new row for the phone starts
+/// from it, in the same write (src/data-service/deviceSettings.ts). Keyed as
+/// Device is: a phone is a udid on the server that drives it, so another
+/// server's phone with the same udid (an emulator's) never takes these. A hub
+/// keeps the settings of its nodes' phones here too; a node's report never
+/// writes them.
+model DeviceSetting {
+  udid              String
+  host              String
+  teamId            String?
+  team              Team?    @relation(fields: [teamId], references: [id], onDelete: SetNull)
+  /// JSON array, as Device.tags.
+  tags              String?
+  userBlocked       Boolean  @default(false)
+  reservationReason String?
+  reservedBy        String?
+  reservedByUserId  String?
+  reservedUntil     Float?
+  updatedAt         DateTime @updatedAt
+
+  @@id([udid, host])
+  @@index([teamId])
+}
+
 model PendingSession {
   id            Int    @id @default(autoincrement())
   capability_id String @unique
@@ -348,13 +375,14 @@ model ApiKey {
 }
 
 model Team {
-  id        String       @id @default(uuid())
-  name      String       @unique
-  createdAt DateTime     @default(now())
-  devices   Device[]
-  apiKeys   ApiKey[]
-  members   TeamMember[]
-  apps      App[]
+  id             String          @id @default(uuid())
+  name           String          @unique
+  createdAt      DateTime        @default(now())
+  devices        Device[]
+  deviceSettings DeviceSetting[]
+  apiKeys        ApiKey[]
+  members        TeamMember[]
+  apps           App[]
 }
 
 model SelectorState {

package/lib/src/generated/client/wasm.js

@@ -302,6 +302,19 @@ exports.Prisma.DeviceScalarFieldEnum = {
   nodeHold: 'nodeHold'
 };
 
+exports.Prisma.DeviceSettingScalarFieldEnum = {
+  udid: 'udid',
+  host: 'host',
+  teamId: 'teamId',
+  tags: 'tags',
+  userBlocked: 'userBlocked',
+  reservationReason: 'reservationReason',
+  reservedBy: 'reservedBy',
+  reservedByUserId: 'reservedByUserId',
+  reservedUntil: 'reservedUntil',
+  updatedAt: 'updatedAt'
+};
+
 exports.Prisma.PendingSessionScalarFieldEnum = {
   id: 'id',
   capability_id: 'capability_id',
@@ -536,6 +549,7 @@ exports.Prisma.ModelName = {
   SessionMetric: 'SessionMetric',
   App: 'App',
   Device: 'Device',
+  DeviceSetting: 'DeviceSetting',
   PendingSession: 'PendingSession',
   CLIArgs: 'CLIArgs',
   WebhookConfig: 'WebhookConfig',

package/lib/src/interceptors/CommandInterceptor.js

@@ -65,6 +65,8 @@ const sessionContext_1 = require("../logging/sessionContext");
 const ProcessMetricsService_1 = require("../services/ProcessMetricsService");
 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");
 let CommandInterceptor = class CommandInterceptor {
     constructor() {
         this.log = logger_1.default.scope('CommandInterceptor');
@@ -182,10 +184,14 @@ let CommandInterceptor = class CommandInterceptor {
                         }
                         if (aiCommand === 'assertVisualState') {
                             this.log.info(`[Interceptor] Routing AI command: ${script} with payload: ${JSON.stringify(scriptArgs)}`);
-                            const instruction = typeof scriptArgs === 'string'
-                                ? scriptArgs
-                                : typeof scriptArgs === 'object' && (scriptArgs === null || scriptArgs === void 0 ? void 0 : scriptArgs.instruction)
-                                    ? scriptArgs.instruction
+                            // The condition as a plain string (`execute(script, 'The cart is
+                            // empty')`, which arrives as ['The cart is empty']) or as
+                            // { instruction }. A plain string used to arrive as ''.
+                            const first = Array.isArray(scriptArgs) ? scriptArgs[0] : scriptArgs;
+                            const instruction = typeof first === 'string'
+                                ? first
+                                : typeof first === 'object' && typeof (first === null || first === void 0 ? void 0 : first.instruction) === 'string'
+                                    ? first.instruction
                                     : '';
                             return yield typedi_1.Container.get(AICommandService_1.AICommandService).assertVisualState(driver, instruction);
                         }
@@ -216,13 +222,28 @@ let CommandInterceptor = class CommandInterceptor {
                             }
                         }
                     }
+                    // A session-details command (`xenon: setSessionName`, ...) is answered
+                    // by the before-hook; its answer is what the test gets.
+                    let answered = null;
                     const shouldProceed = yield event_manager_1.DASHBORD_EVENT_MANAGER.beforeSessionCommand(sessionId, commandName, { body: { script: args[0], args: args[1] } }, {
-                        status: () => ({ json: (d) => d }),
+                        status: () => ({
+                            json: (d) => {
+                                var _a;
+                                answered = (_a = d === null || d === void 0 ? void 0 : d.value) !== null && _a !== void 0 ? _a : null;
+                                return d;
+                            },
+                        }),
                         setHeader: () => { },
                         getHeader: () => { },
                     });
                     if (shouldProceed === false) {
-                        return null;
+                        return answered;
+                    }
+                    // Every Xenon script this server has was answered above. Any other
+                    // name used to be answered with null, as if it had worked.
+                    if (commandName === 'execute' && (0, xenonScripts_1.xenonScriptName)(args[0]) !== null) {
+                        const { errors } = yield Promise.resolve().then(() => __importStar(require('@appium/base-driver')));
+                        throw new errors.UnknownCommandError((0, xenonScripts_1.unknownXenonScriptMessage)(args[0]));
                     }
                 }
                 // --- OMNI-VISION: PROACTIVE SEARCH ---
@@ -288,7 +309,7 @@ let CommandInterceptor = class CommandInterceptor {
             catch (error) {
                 if (this.isNoSuchElementError(error) &&
                     ['findElement', 'findElements'].includes(commandName) &&
-                    pluginArgs.enableSelfHealing !== false) {
+                    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,
@@ -456,7 +477,7 @@ let CommandInterceptor = class CommandInterceptor {
                 }, {}, JSON.stringify({ value: response, sessionId }));
                 if (commandName === 'findElement' &&
                     response &&
-                    pluginArgs.enableSelfHealing !== false) {
+                    typedi_1.Container.get(SelfHealingSwitch_1.SelfHealingSwitch).isEnabled(pluginArgs)) {
                     this.triggerLearning(driver, args, response, sessionId);
                 }
             }

package/lib/src/interceptors/xenonScripts.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Xenon's execute scripts: `driver.execute('xenon: <name>', ...)`, or `xe:`.
+ *
+ * Who answers them:
+ * - The five session-details commands (SESSION_DETAILS_COMMANDS in
+ *   dashboard/commands.ts) are answered by the server that keeps the
+ *   session's record: a hub, for a session on a node's phone, when its
+ *   dashboard is on (its gateway's before-hook), otherwise the server that
+ *   drives the phone.
+ * - Every other one is answered by the server that drives the phone
+ *   (CommandInterceptor), because that is where the session's autowait
+ *   settings, Omni-Vision and network capture live. A hub forwards them.
+ * - A name Xenon doesn't have fails with `unknown command`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XENON_SCRIPT_NAMES = void 0;
+exports.xenonScriptName = xenonScriptName;
+exports.unknownXenonScriptMessage = unknownXenonScriptMessage;
+/** The names CommandInterceptor and the session-details commands answer. Keep in step with both. */
+exports.XENON_SCRIPT_NAMES = [
+    'setAutowaitProperties',
+    'getAutowaitProperties',
+    'smartTap',
+    'omniClick',
+    'visualTap',
+    'uiInventory',
+    'uiScanExport',
+    'analyzeScreen',
+    'omniScan',
+    'assertVisualState',
+    'addMock',
+    'removeMock',
+    'clearMocks',
+    'getMocks',
+    'getRequests',
+    'exportHar',
+    'setSessionName',
+    'setSessionStatus',
+    'debug',
+    'addTag',
+    'captureEvidence',
+];
+/** The name in a `xenon: <name>` or `xe: <name>` script, or null for any other script. */
+function xenonScriptName(script) {
+    if (typeof script !== 'string')
+        return null;
+    const match = /^\s*(?:xenon|xe)\s*:\s*(\S+)\s*$/.exec(script);
+    return match ? match[1] : null;
+}
+/** The message for a `xenon:` / `xe:` script Xenon doesn't have. */
+function unknownXenonScriptMessage(script) {
+    return (`Unknown Xenon command "${script.trim()}". ` +
+        `Xenon's execute commands are: ${exports.XENON_SCRIPT_NAMES.join(', ')}.`);
+}

package/lib/src/interfaces/IPluginArgs.js

@@ -30,7 +30,7 @@ exports.DefaultPluginArgs = {
     bindHostOrIp: 'auto',
     enableDashboard: false,
     bootedSimulators: false,
-    healthCheckIntervalMs: 86400000,
+    healthCheckIntervalMs: 300000,
     healthCheckSchedule: undefined,
     removeDevicesFromDatabaseBeforeRunningThePlugin: false,
     databaseProvider: undefined,
@@ -50,7 +50,6 @@ exports.DefaultPluginArgs = {
     recordingCleanupMaxCount: 100,
     recordingFailedCleanupDays: 2,
     sessionHeartbeatIntervalMs: 30000,
-    enableJsonLogging: false,
     autowait: {
         enabled: false,
         timeoutMs: 10000,

package/lib/src/plugin.js

@@ -67,6 +67,7 @@ const NodeDevices_1 = __importDefault(require("./device-managers/NodeDevices"));
 const appiumUmbrella_1 = require("./sessions/appiumUmbrella");
 const LiveSessionOwners_1 = require("./services/device-access/LiveSessionOwners");
 const SessionMetricsService_1 = require("./services/metrics/SessionMetricsService");
+const PhoneNetworkRestore_1 = require("./services/network/PhoneNetworkRestore");
 const config_1 = require("./config");
 const SessionManager_1 = require("./sessions/SessionManager");
 const event_manager_1 = require("./dashboard/event-manager");
@@ -75,13 +76,22 @@ const session_service_1 = require("./dashboard/services/session-service");
 const DEVICE_MANAGER_LOCK_NAME = 'DeviceManager';
 class XenonPlugin extends base_plugin_1.default {
     constructor(pluginName, cliArgs) {
+        var _a;
         super(pluginName, cliArgs);
         this.xenonLog = logger_1.default.scope('Plugin');
         this.pluginArgs = Object.assign({}, IPluginArgs_1.DefaultPluginArgs);
         this.aiCommandService = typedi_1.Container.get(AICommandService_1.AICommandService);
         this.xenonLog.debug(`📱 Plugin Args: ${JSON.stringify(cliArgs)}`);
         this.pluginArgs = Object.assign({}, IPluginArgs_1.DefaultPluginArgs, this.cliArgs);
-        logger_1.XenonLogger.configure({ enableJsonLogging: this.pluginArgs.enableJsonLogging });
+        // The option as it was given, not the merged copy above: JSON logging is on
+        // when the option says so, or when it isn't given and XENON_JSON_LOGGING does.
+        // schema.json gives the option no default, so Appium leaves it out when
+        // nobody set it; a default here (the merge above used to add `false`) would
+        // overwrite the variable on every start. `configure` ignores undefined.
+        const jsonLogging = (_a = this.cliArgs) === null || _a === void 0 ? void 0 : _a.enableJsonLogging;
+        logger_1.XenonLogger.configure({
+            enableJsonLogging: typeof jsonLogging === 'boolean' ? jsonLogging : undefined,
+        });
         if ((0, networkAddresses_1.shouldAutoResolveBindHost)(this.pluginArgs.bindHostOrIp)) {
             this.pluginArgs.bindHostOrIp = (0, networkAddresses_1.resolveAdvertisedBindHost)(this.pluginArgs.bindHostOrIp);
         }
@@ -101,6 +111,10 @@ class XenonPlugin extends base_plugin_1.default {
             typedi_1.Container.get(LiveSessionOwners_1.LiveSessionOwners).forget(sessionId);
             if (sessionId)
                 yield typedi_1.Container.get(SessionMetricsService_1.SessionMetricsService).stop(sessionId);
+            // Appium's new-command timeout ends a session here, not in deleteSession:
+            // the phone's network (profile, interceptor proxy) and the capture are
+            // put back before the phone is released.
+            yield typedi_1.Container.get(PhoneNetworkRestore_1.PhoneNetworkRestore).restoreSession(sessionId, 'driver shut down');
             const deviceFilter = {
                 session_id: sessionId ? sessionId : undefined,
                 udid: driver.caps && driver.caps.udid ? driver.caps.udid : undefined,

package/lib/src/prisma.js

@@ -33,7 +33,7 @@ exports.getPrismaClient = getPrismaClient;
  * can stub individual methods (Prisma's internal Proxy blocks property assignment).
  */
 const MODEL_DELEGATES = new Set([
-    'build', 'session', 'sessionLog', 'log', 'profiling', 'app', 'device',
+    'build', 'session', 'sessionLog', 'log', 'profiling', 'app', 'device', 'deviceSetting',
     'pendingSession', 'cLIArgs', 'webhookConfig', 'webConfig', 'locatorEtalon',
     'lease', 'portLease', 'apiKey', 'selectorState', 'user', 'userSession',
     'passwordResetToken', 'team', 'teamMember', 'eventLog', 'project', 'recording', 'bookmark',

package/lib/src/scripts/database-check.js

@@ -0,0 +1,124 @@
+"use strict";
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clientProviderFromSchema = clientProviderFromSchema;
+exports.describeDatabaseUrl = describeDatabaseUrl;
+exports.checkDatabase = checkDatabase;
+exports.assertSupportedDatabase = assertSupportedDatabase;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const logger_1 = __importDefault(require("../logger"));
+const config_1 = require("../config");
+const LABEL = { sqlite: 'SQLite', postgresql: 'PostgreSQL' };
+function providerOfUrl(url) {
+    if (url.startsWith('file:'))
+        return 'sqlite';
+    if (/^postgres(ql)?:\/\//.test(url))
+        return 'postgresql';
+    return null;
+}
+/** The datasource provider in a Prisma schema's text, or null if it has none. */
+function clientProviderFromSchema(schema) {
+    const match = /datasource\s+\w+\s*{[^}]*?provider\s*=\s*"([^"]+)"/.exec(schema);
+    return match ? match[1] : null;
+}
+/** A database URL fit for a log line: a SQLite file's path, or a server URL without credentials. */
+function describeDatabaseUrl(url) {
+    if (url.startsWith('file:'))
+        return url.slice('file:'.length);
+    try {
+        const parsed = new URL(url);
+        return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+    }
+    catch (_a) {
+        return url.split(':')[0] + ':';
+    }
+}
+/**
+ * Decide whether the server may start on `url`. Throws an Error whose message
+ * says what to change; returns a warning when `configured` disagrees with the
+ * client but the URL is usable.
+ */
+function checkDatabase(opts) {
+    var _a;
+    const { configured, url, client } = opts;
+    const clientLabel = (_a = LABEL[client]) !== null && _a !== void 0 ? _a : client;
+    const urlProvider = providerOfUrl(url);
+    const where = describeDatabaseUrl(url);
+    if (urlProvider !== client) {
+        const kind = urlProvider
+            ? `a ${LABEL[urlProvider]} database`
+            : 'not a database this install knows';
+        const fix = client === 'sqlite'
+            ? 'Set DATABASE_URL (or databaseUrl) to a SQLite file, `file:/path/to/xenon.db`, or leave it ' +
+                'unset to use the default under ~/.cache/xenon. The published plugin stores its data in SQLite only.'
+            : `Set DATABASE_URL (or databaseUrl) to a ${clientLabel} URL.`;
+        throw new Error(`[Database] Cannot start: the database URL (${where}) is ${kind}, but this install's ` +
+            `database client is built for ${clientLabel}. ${fix}`);
+    }
+    if (configured && configured !== client) {
+        return {
+            warning: `[Database] databaseProvider is "${configured}", but this install's database client is ` +
+                `built for ${clientLabel}, so the setting has no effect. Your data is in ${where}. ` +
+                `Set databaseProvider to "${client}", or remove it.`,
+        };
+    }
+    return {};
+}
+/** The provider the generated client next to this file was built for. */
+function generatedClientProvider() {
+    var _a;
+    const schemaPath = path.join(__dirname, '..', 'generated', 'client', 'schema.prisma');
+    try {
+        return (_a = clientProviderFromSchema(fs.readFileSync(schemaPath, 'utf8'))) !== null && _a !== void 0 ? _a : 'sqlite';
+    }
+    catch (_b) {
+        // The published plugin's client is SQLite; a missing copy means a plain install.
+        return 'sqlite';
+    }
+}
+/** Startup gate: log the warning, or throw so the server doesn't start on the wrong database. */
+function assertSupportedDatabase() {
+    const { warning } = checkDatabase({
+        configured: config_1.config.databaseProvider,
+        url: config_1.config.databaseUrl,
+        client: generatedClientProvider(),
+    });
+    if (warning)
+        logger_1.default.warn(warning);
+}

package/lib/src/services/AIService.js

@@ -46,6 +46,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AI_SERVICE = exports.AIService = void 0;
+exports.parseVisualVerdict = parseVisualVerdict;
 const generative_ai_1 = require("@google/generative-ai");
 const openai_1 = __importDefault(require("openai"));
 const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
@@ -55,6 +56,41 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const config_1 = require("../config");
 const CircuitBreaker_1 = require("./CircuitBreaker");
+/** What GeminiProvider answers, instead of throwing, when the provider is rate-limited (429). */
+const RATE_LIMITED = 'CONNECTION_OK_RATE_LIMITED';
+/**
+ * A provider's answer to the assertion prompt, `{ "result": true|false,
+ * "reason": "..." }`, read leniently (code fences, text around the JSON,
+ * `message` for `reason`, "true"/"false" as strings) but never guessed: null
+ * when it holds no true/false `result`.
+ */
+function parseVisualVerdict(answer) {
+    const text = answer.replace(/```(?:json)?/gi, '').trim();
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start === -1 || end <= start)
+        return null;
+    let data;
+    try {
+        data = JSON.parse(text.slice(start, end + 1));
+    }
+    catch (_a) {
+        return null;
+    }
+    const raw = data === null || data === void 0 ? void 0 : data.result;
+    const result = raw === true || raw === 'true' ? true : raw === false || raw === 'false' ? false : null;
+    if (result === null)
+        return null;
+    const reason = typeof data.reason === 'string'
+        ? data.reason
+        : typeof data.message === 'string'
+            ? data.message
+            : '';
+    return {
+        result,
+        message: reason.trim() || (result ? 'The condition holds.' : 'The condition does not hold.'),
+    };
+}
 class GeminiProvider {
     constructor(apiKey, modelName) {
         this.genAI = new generative_ai_1.GoogleGenerativeAI(apiKey.trim());
@@ -365,6 +401,69 @@ Fix: Add a pre-emptive check for the location permission dialog or use the \`aut
             }
         });
     }
+    /**
+     * Asks the provider whether `condition` holds on the screenshot
+     * (`xenon: assertVisualState`). Answers only with the provider's own
+     * verdict: with no provider, a failed call, a rate limit or an answer that
+     * isn't true or false it throws, saying the condition was not checked. A
+     * `false` there would pass a test asserting that something is absent.
+     */
+    assertVisual(screenshotBase64, condition) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            this.initializeProvider();
+            const notChecked = 'so the condition was not checked';
+            if (!this.provider) {
+                throw new Error(`No AI provider is configured, ${notChecked}. Set XENON_AI_PROVIDER and the provider's key.`);
+            }
+            const prompt = `
+You are checking a screenshot of a mobile app for an automated test.
+
+Condition: ${JSON.stringify(condition)}
+
+Is the condition true of what the screenshot shows? Judge only what is visible on the screen.
+Answer with JSON only, exactly: {"result": true or false, "reason": "one sentence on what you see"}
+        `.trim();
+            let answer;
+            try {
+                answer = yield this.callProvider(prompt, screenshotBase64);
+            }
+            catch (err) {
+                throw new Error(`The AI provider failed, ${notChecked}: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
+            }
+            if (answer === RATE_LIMITED) {
+                throw new Error(`The AI provider is rate-limited, ${notChecked}. Try again later.`);
+            }
+            const verdict = parseVisualVerdict(answer);
+            if (!verdict) {
+                const said = answer.replace(/\s+/g, ' ').trim().slice(0, 200);
+                throw new Error(`Xenon could not read the AI provider's answer as true or false, ${notChecked}. ` +
+                    `It answered: ${JSON.stringify(said)}`);
+            }
+            return verdict;
+        });
+    }
+    /**
+     * A short description of the screen in the screenshot, for
+     * `xenon: analyzeScreen` and device control's Omni-Scan. Throws when there
+     * is no provider or the call fails, so the caller can say why there is none.
+     */
+    describeScreen(screenshotBase64) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.initializeProvider();
+            if (!this.provider)
+                throw new Error('No AI provider is configured');
+            const prompt = `
+You are looking at a screenshot of a mobile app, for a software tester.
+Describe the screen in a few short sentences: which screen it is, its main elements and their state (for example filled in, empty, selected or disabled), and anything unexpected, such as an error message, a system dialog, a crash or a loading indicator.
+Describe only what is visible. Answer in plain text.
+        `.trim();
+            const answer = yield this.callProvider(prompt, screenshotBase64);
+            if (answer === RATE_LIMITED)
+                throw new Error('The AI provider is rate-limited');
+            return answer;
+        });
+    }
     /**
      * Heals a broken locator using deep LLM reasoning (Tier 5)
      */

package/lib/src/services/CleanupService.js

@@ -25,6 +25,7 @@ const logger_1 = __importDefault(require("../logger"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../config");
+const labSettings_1 = require("./settings/labSettings");
 const recordingCleanup_1 = require("./recording/recordingCleanup");
 /** Subdirectory holding composite (multi-device) outputs, keyed by group id. */
 const GROUPS_DIR = '_groups';
@@ -34,6 +35,8 @@ let CleanupService = class CleanupService {
     }
     /**
      * Orchestrates build + session + recording cleanup based on retention policy.
+     * The build retention window, the build cap and the asset purge are the ones
+     * saved on the dashboard's Maintenance page, else `pluginArgs`'.
      *
      * Phases:
      *  1. Purge old builds (by age AND count cap) together with their sessions.
@@ -44,7 +47,9 @@ let CleanupService = class CleanupService {
      */
     runCleanup(pluginArgs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { buildCleanupDays = 30, buildCleanupMaxCount = 100, deleteBuildAssets = true, } = pluginArgs;
+            // What the Maintenance page saved wins over the startup options, and is
+            // read here, at each run, so a change needs no restart. See labSettings.ts.
+            const { buildCleanupDays, buildCleanupMaxCount, deleteBuildAssets } = yield (0, labSettings_1.loadEffectiveSettings)(pluginArgs);
             this.log.info(`Starting cleanup: Retention = ${buildCleanupDays} days, Max Builds = ${buildCleanupMaxCount}, Purge Assets = ${deleteBuildAssets}`);
             const expirationDate = new Date();
             expirationDate.setDate(expirationDate.getDate() - buildCleanupDays);