@xenon-device-management/xenon 2.12.0 → 2.13.0

package/lib/src/app/swagger.js

@@ -7,97 +7,220 @@ exports.swaggerSpec = void 0;
 exports.setupSwagger = setupSwagger;
 const swagger_jsdoc_1 = __importDefault(require("swagger-jsdoc"));
 const swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
+const package_json_1 = __importDefault(require("../../package.json"));
+/**
+ * The API reference served at /xenon/api-docs (and as JSON at
+ * /xenon/api-docs.json). The shared parts live here: the introduction,
+ * authentication, the error and rate-limit responses, and the tags. Each
+ * area's paths live in src/app/openapi/<area>.yaml.
+ *
+ * test/unit/openapi-coverage.spec.ts keeps it whole: every route the server
+ * serves must be documented, every documented route must be served, and the
+ * result must be valid OpenAPI 3.
+ */
+const errorExample = (error, message) => ({
+    'application/json': {
+        schema: { $ref: '#/components/schemas/Error' },
+        example: message ? { error, message } : { error },
+    },
+});
 const swaggerDefinition = {
-    openapi: '3.0.0',
-    servers: [
-        {
-            url: '/xenon',
-            description: 'Local Grid Node Registry',
-        },
-    ],
+    openapi: '3.0.3',
+    servers: [{ url: '/xenon', description: 'This Xenon server' }],
     info: {
         title: 'Xenon API',
-        version: '1.0.0',
+        version: package_json_1.default.version,
         description: `
-# Xenon Edge • Intelligent Infrastructure API
-**The foundation for autonomous mobile device orchestration.**
+The REST API of a Xenon server: the devices in your lab, the Appium sessions that run on them, live device control, recordings, selector health and administration. The dashboard uses this same API.
+
+This reference describes version **${package_json_1.default.version}**. Every path below is relative to \`/xenon\`, so \`/api/devices\` is \`https://<your-xenon-host>/xenon/api/devices\`. The raw OpenAPI document is at [\`/xenon/api-docs.json\`](/xenon/api-docs.json).
+
+## Authentication
+
+Every endpoint needs a credential, except the few marked as public (health checks, sign-in, password reset and the JWKS). The four ways to authenticate are:
+
+| Credential | How to send it | Typical use |
+|---|---|---|
+| **Access key and API token** | \`x-xenon-access-key\` and \`x-xenon-token\` headers | Scripts, CI, SDKs, a node reporting to its hub |
+| **Bearer token** | \`Authorization: Bearer <jwt>\` | Short-lived access; mint one with \`POST /api/auth/token\` (audience \`xenon-rest\`, 1 hour) |
+| **Dashboard session** | \`xenon_dashboard_session\` cookie, set by \`POST /api/auth/login\` | The browser dashboard |
+| **Hub token** | \`x-xenon-hub-token\` header | Hub to node only; Xenon sends it itself |
+
+Find your access key and create API tokens on your profile page (\`/xenon/profile\`, **API tokens**).
+
+**Scopes.** An API token carries scopes: \`read\`, \`sessions\`, \`devices\` and \`admin\`. \`admin\` satisfies any scope. A signed-in dashboard user gets the scopes of their role: members have \`devices\`, \`sessions\` and \`read\`; admins also have \`admin\`. A request without the scope it needs gets \`403\`.
+
+**Roles.** Some endpoints also need a role: \`MEMBER\`, \`ADMIN\` or \`SUPER_ADMIN\`. Each says so in its description.
+
+**Teams.** A member sees only their teams' devices and the shared pool, and the sessions, apps and selectors that go with them. Something outside your teams answers exactly as if it didn't exist: \`404\`.
+
+**Same-origin check.** A state-changing request (POST, PUT, PATCH, DELETE) must carry an \`Origin\` or \`Referer\` header from the same host as the server, or it gets \`403\`. Requests sent with the access key and token headers, an \`Authorization: Bearer\` token, or a hub token are exempt: a browser can't send those headers from another site. So only a script that calls a public endpoint such as \`POST /api/auth/login\` needs to send an \`Origin\` header.
+
+## Errors
+
+Errors are JSON with an \`error\` field. An unexpected server error is \`500\` with \`{ "error": "internal", "message": "Internal server error" }\`; the details go to the server's log. Newer endpoints put a stable, machine-readable code there (\`not_found\`, \`device_held_by_another_user\`) with a human-readable \`message\`. Older ones put the message itself in \`error\`, or \`true\` with a \`message\`. Branch on the HTTP status first.
+
+## Rate limits
 
-Xenon's high-performance API provides programmatic access to the core orchestration engine, enabling complex automation workflows for distributed device farms.
+Every request with a credential is rate limited, except single-use tickets. An access key has its own budgets; a signed-in user's dashboard sessions and bearer tokens share one set of budgets per user (300 a minute). Each has three request budgets, refilled every minute:
+- \`read\`: GET requests (ten times the budget for a signed-in user or a bearer token, since a dashboard page loads many images at once);
+- \`heavy\`: AI, healing and visual endpoints (a quarter of the budget, at least 10);
+- \`control\`: everything else.
 
-### Key Capabilities:
-*   **Elastic Device Grid**: Real-time discovery and state management of physical nodes.
-*   **Autonomous Sessions**: Self-healing Appium session management with automated retries.
-*   **Deep Control**: Direct low-latency interaction logic (Input injection, thermal monitoring).
-*   **Security Protocol**: Industrial-grade isolation for sensitive test environments.
+Each such response carries \`X-RateLimit-Category\`, \`X-RateLimit-Remaining\` and \`X-RateLimit-Capacity\`. Past the budget the answer is \`429\` with \`Retry-After\` in seconds.
 
----
-### Authentication
-Every endpoint authenticates with the per-user \`(x-xenon-access-key, x-xenon-token)\` pair. Each token carries one or more scopes — \`read\`, \`sessions\`, \`devices\`, or \`admin\` (admin always satisfies any scope check). Mint tokens at \`/profile\` → **API Tokens**; the access key is shown at the top of that page and is rotatable. Browser dashboards may use the \`xenon_dashboard_session\` cookie set by \`POST /api/auth/login\`.
+## Appium sessions
 
-### Appium sessions
-Appium's own \`POST /session\` is not under this API. A session authenticates with capabilities in \`xe:options\`, Xenon's capability namespace: \`accessKey\` + \`token\` (a token with the \`sessions\` scope), or a \`sessionToken\` minted by \`POST /api/auth/token\`. A leased device is named by \`leaseId\` + \`leaseToken\`, which the lease-create response's \`appiumCapabilities\` already carry. \`xenon:options\` is read as an alias (\`xe:options\` wins field by field); \`df:options\` is not read. Xenon removes the credentials before the driver or any stored record sees them.
+Appium's WebDriver API (\`POST /session\` and the session's commands, under Appium's own base path) is not part of this reference. A session authenticates in its capabilities, under \`xe:options\`, with one of:
+- \`accessKey\` and \`token\`;
+- \`sessionToken\`, minted by \`POST /api/auth/token\`.
 
-### Rate limiting
-Every authenticated response carries \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, and \`X-RateLimit-Reset\` headers. Requests beyond the configured budget receive \`429 Too Many Requests\`.
-        `,
+A leased device also takes \`leaseId\` and \`leaseToken\`, which the lease's \`appiumCapabilities\` already carry. Xenon removes these credentials before the driver or any stored record sees them.
+
+## Live streams
+
+Device previews and live logs use WebSockets, outside this reference:
+- \`/xenon/api/control/{udid}/stream/h264\`
+- \`/xenon/api/control/{udid}/logcat\`
+
+Both are opened with a ticket from \`POST /api/control/{udid}/stream/ticket\`. Socket.IO at \`/socket.io/\` carries the dashboard's live events.
+`,
         contact: {
-            name: 'Xenon Architecture Team',
-            url: 'https://github.com/xenon-platform/xenon',
+            name: 'Xenon',
+            url: 'https://github.com/Rabindra184/xenon',
         },
         license: {
-            name: 'ISC License',
+            name: 'ISC',
             url: 'https://opensource.org/licenses/ISC',
         },
     },
     tags: [
-        { name: 'Health & Ops', description: 'Liveness, version, metrics, runtime args' },
-        { name: 'Authentication', description: 'Browser dashboard login' },
-        { name: 'Devices', description: 'Real-time grid discovery' },
-        { name: 'Sessions', description: 'Orchestration & Logs' },
-        { name: 'Builds', description: 'Telemetry tracking' },
-        { name: 'Control', description: 'Direct interaction engine' },
-        { name: 'Reservations', description: 'Resource locking' },
-        { name: 'Applications', description: 'Artifact management' },
-        { name: 'Grid', description: 'Cluster topology' },
-        { name: 'Webhooks', description: 'Event propagation' },
-        { name: 'Configuration', description: 'Edge node parameters' },
-        { name: 'Selector Health', description: 'Heal-rate analytics & lifecycle' },
-        { name: 'Network Interceptor', description: 'Per-session HTTP capture, mocks, HAR export' },
-        { name: 'Admin', description: 'API keys, teams, process snapshots' },
-        { name: 'Hub-Node', description: 'Hub↔node device registration channel' },
+        { name: 'Health & Ops', description: 'Liveness, version, metrics and server information.' },
+        { name: 'Authentication', description: 'Sign-in, sign-out, password reset and tokens.' },
+        { name: 'Profile', description: 'Your own account: API tokens and access key.' },
+        { name: 'Users', description: 'User accounts. Admin only.' },
+        { name: 'Teams', description: 'Teams, their members and the devices they own.' },
+        { name: 'API Keys', description: 'Every API key in the lab. Admin only.' },
+        { name: 'Projects', description: 'Projects that group work in the lab.' },
+        { name: 'Audit', description: 'Audit events sent in by Xenon services.' },
+        { name: 'Devices', description: 'The devices in the lab, and blocking them for maintenance.' },
+        {
+            name: 'Control',
+            description: 'Drive one device: input, screenshots, live preview, apps, logs and inspection.',
+        },
+        { name: 'Reservations', description: 'Reserving a device for a person for a while.' },
+        {
+            name: 'Leases',
+            description: 'Claiming devices from code (SDKs, MCP tools), with a heartbeat.',
+        },
+        { name: 'Queue', description: 'Sessions waiting for a free device.' },
+        {
+            name: 'Hub-Node',
+            description: 'How nodes report their devices to a hub, and what a node answers its hub.',
+        },
+        {
+            name: 'Sessions',
+            description: 'Appium sessions: their history, commands, logs, assets and performance.',
+        },
+        { name: 'Builds', description: 'Groups of sessions from one test run.' },
+        {
+            name: 'Selector Health',
+            description: 'Selectors your tests found only with self-healing, and their fixes.',
+        },
+        {
+            name: 'Network Interceptor',
+            description: "A session's captured HTTP traffic, mocks and HAR export.",
+        },
+        {
+            name: 'Recordings',
+            description: 'Recordings of one or more devices, with marks, bookmarks and proof bundles.',
+        },
+        { name: 'Applications', description: 'Uploaded app builds and which team sees them.' },
+        { name: 'Webhooks', description: 'Where Xenon sends its events.' },
+        { name: 'Configuration', description: 'Server settings, including AI providers.' },
+        { name: 'Admin', description: 'Operations views for administrators.' },
     ],
     components: {
         schemas: {
-            Device: {
+            Error: {
                 type: 'object',
+                description: 'An error. `error` is a machine-readable code on newer endpoints, otherwise the message itself (or `true`, with `message`).',
+                required: ['error'],
                 properties: {
-                    udid: {
-                        type: 'string',
-                        description: 'Unique identity',
-                        example: '00008110-00084CE80E51401E',
+                    error: {
+                        oneOf: [{ type: 'string' }, { type: 'boolean', enum: [true] }],
+                        example: 'not_found',
                     },
+                    message: { type: 'string', example: 'Device not found' },
+                },
+                additionalProperties: true,
+            },
+            Success: {
+                type: 'object',
+                properties: { success: { type: 'boolean', example: true } },
+            },
+            Device: {
+                type: 'object',
+                description: 'A device in the lab, as the device list returns it.',
+                properties: {
+                    udid: { type: 'string', example: '00008110-00084CE80E51401E' },
                     name: { type: 'string', example: 'iPhone 14 Pro' },
                     platform: { type: 'string', enum: ['ios', 'android'] },
-                    host: { type: 'string', example: '192.168.1.100' },
+                    host: {
+                        type: 'string',
+                        description: 'The server the device is attached to.',
+                        example: 'http://192.168.1.100:4723',
+                    },
+                    nodeId: {
+                        type: 'string',
+                        nullable: true,
+                        description: 'The node that reported it, on a hub.',
+                    },
                     busy: { type: 'boolean' },
-                    session_id: { type: 'string', nullable: true },
-                    state: { type: 'string' },
+                    session_id: {
+                        type: 'string',
+                        nullable: true,
+                        description: 'The Appium session on it, or a preview or recording hold (`manual_<userId>_<udid>`).',
+                    },
+                    state: { type: 'string', example: 'device' },
                     sdk: { type: 'string', example: '17.0' },
-                    deviceType: { type: 'string' },
+                    deviceType: { type: 'string', enum: ['real', 'simulator', 'emulator'] },
+                    realDevice: { type: 'boolean' },
+                    offline: { type: 'boolean' },
+                    userBlocked: { type: 'boolean', description: 'Blocked for maintenance.' },
+                    teamId: {
+                        type: 'string',
+                        nullable: true,
+                        description: 'The owning team; null is the shared pool.',
+                    },
+                    reservedBy: { type: 'string', nullable: true },
+                    reservedByUserId: {
+                        type: 'string',
+                        nullable: true,
+                        description: 'The user who took the reservation; null before 2.13.',
+                    },
+                    reservedUntil: { type: 'integer', nullable: true, description: 'Epoch milliseconds.' },
+                    healthStatus: { type: 'string', example: 'Healthy' },
+                    batteryLevel: { type: 'integer', nullable: true },
+                    screenWidth: { type: 'string', nullable: true },
+                    screenHeight: { type: 'string', nullable: true },
                 },
+                additionalProperties: true,
             },
-            // ... (rest of schemas remain same for internal completeness)
             Session: {
                 type: 'object',
                 properties: {
                     id: { type: 'string' },
-                    name: { type: 'string' },
-                    status: { type: 'string', enum: ['running', 'success', 'failed'] },
+                    name: { type: 'string', nullable: true },
+                    status: { type: 'string', example: 'success' },
+                    build_id: { type: 'string', nullable: true },
                     device_udid: { type: 'string' },
                     device_name: { type: 'string' },
                     device_platform: { type: 'string' },
                     createdAt: { type: 'string', format: 'date-time' },
+                    updatedAt: { type: 'string', format: 'date-time' },
                 },
+                additionalProperties: true,
             },
             Build: {
                 type: 'object',
@@ -110,95 +233,7 @@ Every authenticated response carries \`X-RateLimit-Limit\`, \`X-RateLimit-Remain
                     runningCount: { type: 'integer' },
                     createdAt: { type: 'string', format: 'date-time' },
                 },
-            },
-            Reservation: {
-                type: 'object',
-                properties: {
-                    udid: { type: 'string' },
-                    host: { type: 'string' },
-                    reservedBy: { type: 'string' },
-                    reservedUntil: { type: 'integer' },
-                    reservationReason: { type: 'string' },
-                    remainingMs: { type: 'integer' },
-                },
-            },
-            App: {
-                type: 'object',
-                properties: {
-                    id: { type: 'string' },
-                    name: { type: 'string' },
-                    filename: { type: 'string' },
-                    filepath: { type: 'string' },
-                    platform: { type: 'string', enum: ['ios', 'android'] },
-                    uploadedAt: { type: 'string', format: 'date-time' },
-                },
-            },
-            WebhookConfig: {
-                type: 'object',
-                properties: {
-                    id: { type: 'string' },
-                    url: { type: 'string', format: 'uri' },
-                    events: { type: 'array', items: { type: 'string' } },
-                    type: { type: 'string', enum: ['slack', 'webhook'] },
-                },
-            },
-            LocatorSuggestion: {
-                type: 'object',
-                properties: {
-                    strategy: { type: 'string' },
-                    value: { type: 'string' },
-                    priority: { type: 'integer' },
-                    isUnique: { type: 'boolean' },
-                },
-            },
-            InspectorNode: {
-                type: 'object',
-                properties: {
-                    id: { type: 'string' },
-                    type: { type: 'string' },
-                    text: { type: 'string' },
-                    path: { type: 'string' },
-                    rect: {
-                        type: 'object',
-                        properties: {
-                            x: { type: 'number' },
-                            y: { type: 'number' },
-                            width: { type: 'number' },
-                            height: { type: 'number' },
-                        },
-                    },
-                    attributes: { type: 'object', additionalProperties: true },
-                    locators: {
-                        type: 'array',
-                        items: { $ref: '#/components/schemas/LocatorSuggestion' },
-                    },
-                    children: {
-                        type: 'array',
-                        items: { $ref: '#/components/schemas/InspectorNode' },
-                    },
-                },
-            },
-            InspectorSnapshot: {
-                type: 'object',
-                properties: {
-                    udid: { type: 'string' },
-                    platform: { type: 'string' },
-                    screenshot: { type: 'string', description: 'Base64 encoded screenshot' },
-                    root: { $ref: '#/components/schemas/InspectorNode' },
-                },
-            },
-            Error: {
-                type: 'object',
-                properties: {
-                    error: { type: 'boolean', example: true },
-                    message: { type: 'string' },
-                },
-            },
-            Success: {
-                type: 'object',
-                properties: {
-                    success: { type: 'boolean', example: true },
-                },
+                additionalProperties: true,
             },
         },
         securitySchemes: {
@@ -206,77 +241,107 @@ Every authenticated response carries \`X-RateLimit-Limit\`, \`X-RateLimit-Remain
                 type: 'apiKey',
                 in: 'header',
                 name: 'x-xenon-access-key',
-                description: 'Per-user access key (`xen_…`). Paired with `x-xenon-token` for programmatic + hub-node calls. Visible to its owner at `/profile`; rotate via the **Rotate** button there.',
+                description: 'Your access key (`xen_…`), always sent together with `x-xenon-token`. Shown on your profile page, where you can also rotate it.',
             },
             TokenAuth: {
                 type: 'apiKey',
                 in: 'header',
                 name: 'x-xenon-token',
-                description: 'Per-user API token, paired with `x-xenon-access-key`. Mint via `/profile` → API Tokens. Carries the token-specific scopes, not the user\'s broader role.',
+                description: 'An API token from your profile page, sent together with `x-xenon-access-key`. It carries its own scopes.',
+            },
+            BearerAuth: {
+                type: 'http',
+                scheme: 'bearer',
+                bearerFormat: 'JWT',
+                description: 'A token from `POST /api/auth/token` (audience `xenon-rest`), valid for one hour. Verified against `/api/auth/jwks.json`; revoking its user takes effect at once.',
+            },
+            CookieAuth: {
+                type: 'apiKey',
+                in: 'cookie',
+                name: 'xenon_dashboard_session',
+                description: 'The dashboard session cookie set by `POST /api/auth/login`. State-changing requests also need a same-host `Origin` or `Referer`.',
+            },
+            HubToken: {
+                type: 'apiKey',
+                in: 'header',
+                name: 'x-xenon-hub-token',
+                description: "A hub's short-lived signed token, verified by the node against the hub's JWKS. Used only between a hub and its nodes.",
             },
         },
         headers: {
-            'X-RateLimit-Limit': {
-                description: 'Maximum requests allowed in the current window for the matched bucket (read / heavy / control).',
-                schema: { type: 'integer' },
+            'X-RateLimit-Category': {
+                description: 'The budget this request counted against: `read`, `heavy` or `control`.',
+                schema: { type: 'string', enum: ['read', 'heavy', 'control'] },
             },
             'X-RateLimit-Remaining': {
-                description: 'Remaining requests in the current window.',
+                description: 'Requests left in that budget.',
                 schema: { type: 'integer' },
             },
-            'X-RateLimit-Reset': {
-                description: 'Unix epoch seconds at which the window resets.',
+            'X-RateLimit-Capacity': {
+                description: "The budget's size per minute.",
+                schema: { type: 'integer' },
+            },
+            'Retry-After': {
+                description: 'Seconds until a request in this budget will be accepted.',
                 schema: { type: 'integer' },
             },
         },
         responses: {
+            BadRequest: {
+                description: 'The request is malformed or a field is missing or invalid.',
+                content: errorExample('bad_request', 'udid is required'),
+            },
             Unauthorized: {
-                description: 'Missing or invalid API key / node secret.',
-                content: {
-                    'application/json': {
-                        schema: { $ref: '#/components/schemas/Error' },
-                        example: { error: true, message: 'Unauthorized' },
-                    },
-                },
+                description: 'No credential, or one that is invalid, expired or revoked.',
+                content: errorExample('unauthenticated'),
             },
             Forbidden: {
-                description: "API key lacks the required scope, or CSRF check failed for a browser caller.",
-                content: {
-                    'application/json': {
-                        schema: { $ref: '#/components/schemas/Error' },
-                        example: { error: true, message: 'Forbidden: scope `admin` required' },
-                    },
-                },
+                description: 'The credential is valid but lacks the scope or role this needs, or a browser request failed the same-origin check.',
+                content: errorExample('insufficient scope'),
+            },
+            NotFound: {
+                description: "It doesn't exist, or it is outside your teams (the two answer the same).",
+                content: errorExample('not_found', 'Not found'),
+            },
+            Conflict: {
+                description: 'It conflicts with the current state, for example a device held by another user.',
+                content: errorExample('device_held_by_another_user', 'This device is in use by another user.'),
             },
             RateLimited: {
-                description: 'Per-key rate limit exceeded for this bucket.',
+                description: "The API key's budget for the request's category is spent. Only requests made with an access key and token are limited.",
                 headers: {
-                    'X-RateLimit-Limit': { $ref: '#/components/headers/X-RateLimit-Limit' },
+                    'X-RateLimit-Category': { $ref: '#/components/headers/X-RateLimit-Category' },
                     'X-RateLimit-Remaining': { $ref: '#/components/headers/X-RateLimit-Remaining' },
-                    'X-RateLimit-Reset': { $ref: '#/components/headers/X-RateLimit-Reset' },
+                    'X-RateLimit-Capacity': { $ref: '#/components/headers/X-RateLimit-Capacity' },
+                    'Retry-After': { $ref: '#/components/headers/Retry-After' },
                 },
                 content: {
                     'application/json': {
                         schema: { $ref: '#/components/schemas/Error' },
-                        example: { error: true, message: 'Too Many Requests' },
+                        example: { error: 'rate limit exceeded', category: 'control', retryAfter: 2 },
                     },
                 },
             },
+            ServiceUnavailable: {
+                description: 'A dependency needed to answer could not be reached; try again.',
+                content: errorExample('internal', 'Service unavailable'),
+            },
+            InternalError: {
+                description: 'An unexpected server error.',
+                content: errorExample('internal', 'Internal server error'),
+            },
         },
     },
-    security: [{ AccessKeyAuth: [], TokenAuth: [] }],
+    security: [{ AccessKeyAuth: [], TokenAuth: [] }, { BearerAuth: [] }, { CookieAuth: [] }],
 };
 const path_1 = __importDefault(require("path"));
-// @ts-ignore - Types will be available after package install
 const options = {
     swaggerDefinition,
     apis: [
-        // Load from compiled JS (execution runtime)
-        path_1.default.join(__dirname, 'swagger-docs.js'),
-        path_1.default.join(__dirname, 'routers', '*.js'),
-        // Fallback to TS source (development environment)
-        path_1.default.join(__dirname, '..', '..', '..', 'src', 'app', 'swagger-docs.ts'),
-        path_1.default.join(__dirname, '..', '..', '..', 'src', 'app', 'routers', '*.ts'),
+        // One YAML file per API area: src/app/openapi, copied to lib/src/app/openapi
+        // by build:copy. YAML, not JSDoc in a .ts file: tsc dropped most of those
+        // free-standing comments, and the served page lost 54 of its 100 paths.
+        path_1.default.join(__dirname, 'openapi', '*.yaml'),
     ],
 };
 const swaggerSpec = (0, swagger_jsdoc_1.default)(options);
@@ -425,6 +490,23 @@ function setupSwagger(app, basePath = '/xenon') {
         .swagger-ui .dialog-ux .modal-ux-header h3 { font-family: 'Outfit', sans-serif; font-size: 28px; color: #fff !important; margin-bottom: 16px; }
         .swagger-ui .dialog-ux .modal-ux-content h4 { color: var(--xenon-text-dim) !important; margin-top: 24px; }
         
+        /* Readability. The title's gradient text left the version badges blank, and
+           Swagger UI's own light section bars and dim greys sat on the dark page. */
+        .swagger-ui .info .title small, .swagger-ui .info .title small pre { -webkit-text-fill-color: #020617; color: #020617 !important; font-family: 'JetBrains Mono', monospace; }
+        .swagger-ui .info .markdown h1, .swagger-ui .info .markdown h2, .swagger-ui .info .markdown h3 { color: var(--xenon-text) !important; font-family: 'Outfit', sans-serif; margin-top: 40px; }
+        .swagger-ui .markdown p, .swagger-ui .markdown li, .swagger-ui .renderedMarkdown p, .swagger-ui .renderedMarkdown li { color: #cbd5e1 !important; }
+        .swagger-ui .markdown table td, .swagger-ui .markdown table th { color: #cbd5e1 !important; border-color: var(--xenon-border-bright) !important; padding: 8px 12px; vertical-align: top; }
+        .swagger-ui .markdown strong, .swagger-ui .renderedMarkdown strong { color: var(--xenon-text) !important; }
+        .swagger-ui .markdown a, .swagger-ui .info a { color: var(--xenon-blue) !important; }
+        .swagger-ui .opblock .opblock-section-header { background: var(--xenon-surface-hover) !important; box-shadow: none !important; border-top: 1px solid var(--xenon-border-bright); }
+        .swagger-ui .opblock .opblock-section-header h4, .swagger-ui .opblock .opblock-section-header label, .swagger-ui .opblock-title_normal { color: var(--xenon-text) !important; }
+        .swagger-ui .opblock-description-wrapper p, .swagger-ui .opblock-description-wrapper li, .swagger-ui .response-col_description, .swagger-ui .parameter__name, .swagger-ui .parameter__type, .swagger-ui .parameter__in, .swagger-ui table thead tr td, .swagger-ui table thead tr th, .swagger-ui .response-col_status, .swagger-ui .responses-inner h4, .swagger-ui .responses-inner h5, .swagger-ui .tab li, .swagger-ui .opblock-summary-description { color: #cbd5e1 !important; }
+        .swagger-ui .dialog-ux .modal-ux-content p, .swagger-ui .dialog-ux .modal-ux-content label, .swagger-ui .dialog-ux .modal-ux-content h4, .swagger-ui .dialog-ux .modal-ux-content h6 { color: #cbd5e1 !important; }
+        .swagger-ui .model, .swagger-ui .model-title, .swagger-ui .property-row td { color: #cbd5e1 !important; }
+        .swagger-ui .info h1, .swagger-ui .info h2, .swagger-ui .info h3, .swagger-ui .info h4 { color: var(--xenon-text) !important; font-family: 'Outfit', sans-serif; }
+        .swagger-ui .info table td, .swagger-ui .info table th, .swagger-ui .info li { color: #cbd5e1 !important; }
+        .swagger-ui table.headers td, .swagger-ui .header-row td, .swagger-ui .headers-wrapper td { color: #cbd5e1 !important; }
+
         /* Custom Scrollbar */
         ::-webkit-scrollbar { width: 10px; height: 10px; }
         ::-webkit-scrollbar-track { background: var(--xenon-bg); }

package/lib/src/data-service/device-service.js

@@ -454,13 +454,15 @@ function emitUnblocked(device) {
  * @param reservedBy Username or identifier
  * @param durationMs Duration in milliseconds
  * @param reason Optional reservation reason
+ * @param reservedByUserId The user taking it, who alone (or an admin) may release or extend it
  */
-function reserveDevice(udid, host, reservedBy, durationMs, reason) {
+function reserveDevice(udid, host, reservedBy, durationMs, reason, reservedByUserId) {
     return __awaiter(this, void 0, void 0, function* () {
         const reservedUntil = Date.now() + durationMs;
         logger_1.default.info(`Reserving device ${udid} for ${reservedBy} until ${new Date(reservedUntil).toISOString()}`);
         yield store.updateDevice(udid, host, {
             reservedBy,
+            reservedByUserId: reservedByUserId !== null && reservedByUserId !== void 0 ? reservedByUserId : null,
             reservedUntil,
             reservationReason: reason,
         });
@@ -476,6 +478,7 @@ function releaseReservation(udid, host) {
         logger_1.default.info(`Releasing reservation for device ${udid}`);
         yield store.updateDevice(udid, host, {
             reservedBy: null,
+            reservedByUserId: null,
             reservedUntil: null,
             reservationReason: null,
         });

package/lib/src/data-service/deviceFieldOwners.js

@@ -74,6 +74,7 @@ const OWNER = {
     userBlocked: 'runtime',
     reservationReason: 'runtime',
     reservedBy: 'runtime',
+    reservedByUserId: 'runtime',
     reservedUntil: 'runtime',
     teamId: 'runtime',
     tags: 'runtime',

package/lib/src/device-managers/AndroidDeviceManager.js

@@ -1043,9 +1043,12 @@ let AndroidDeviceManager = class AndroidDeviceManager {
     }
     getLogs(udid) {
         return __awaiter(this, void 0, void 0, function* () {
+            // A failure throws. It used to come back as the log text itself, so
+            // device control answered 200 with the error as a "line", and the
+            // session log stored it as one.
             const { adbInstance } = yield this.getAdb();
             if (!adbInstance)
-                return 'ADB is not available';
+                throw new Error('ADB is not available');
             try {
                 // Get last 500 lines of logcat
                 return yield adbInstance.adbExec([
@@ -1062,7 +1065,7 @@ let AndroidDeviceManager = class AndroidDeviceManager {
             }
             catch (err) {
                 logger_1.default.warn(`Failed to fetch Android logs for ${udid}: ${err instanceof Error ? err.message : err}`);
-                return `Failed to fetch logs: ${err instanceof Error ? err.message : err}`;
+                throw err;
             }
         });
     }