feat(ai): Enhance Neural Link health check response (#8331)

- Remove redundant 'details' array
- Add structured 'sessions', 'windows', and 'agents' lists
- Include window dimensions in 'windows' list
- Update openapi.yaml schema

Author: tobiu

.github/ISSUE/issue-8169.md

@@ -66,7 +66,7 @@ subIssues:
   - '[x] 8280 [Neural Link] Feature: Tool inspect_class'
   - '[x] 8281 [Neural Link] Feature: Tool get_computed_styles'
 subIssuesCompleted: 68
-subIssuesTotal: 70
+subIssuesTotal: 71
 blockedBy: []
 blocking: []
 ---

.github/ISSUE/issue-8331.md

@@ -0,0 +1,51 @@
+---
+id: 8331
+title: Enhance Neural Link Health Check Response
+state: OPEN
+labels:
+  - enhancement
+  - ai
+  - architecture
+assignees:
+  - tobiu
+createdAt: '2026-01-05T11:51:14Z'
+updatedAt: '2026-01-05T11:51:31Z'
+githubUrl: 'https://github.com/neomjs/neo/issues/8331'
+author: tobiu
+commentsCount: 0
+parentIssue: 8169
+subIssues: []
+subIssuesCompleted: 0
+subIssuesTotal: 0
+blockedBy: []
+blocking: []
+---
+# Enhance Neural Link Health Check Response
+
+The current `healthcheck` response contains a redundant `details` array and lacks specific identification for active sessions and windows.
+
+**Goal:**
+1. Remove the `details` array.
+2. Enrich the response object to include:
+   - `sessions`: List of active App Worker Sessions (id, connectedAt).
+   - `windows`: List of connected Windows (id, appName, width, height, x, y).
+   - `agents`: List of other connected Agents (ids).
+
+**Rationale for Dimensions:**
+Including basic dimensions (width/height) helps immediately distinguish between main application windows and smaller popups/dialogs without requiring an extra `get_window_topology` call, saving agent turns.
+
+**Changes:**
+- `ConnectionService.getStatus()`: Return richer window metadata.
+- `HealthService.healthcheck()`: Construct the new response payload.
+- `openapi.yaml`: Update `HealthCheckResponse` schema.
+
+Reference: #8169 (Epic)
+
+## Activity Log
+
+- 2026-01-05 @tobiu added the `enhancement` label
+- 2026-01-05 @tobiu added the `ai` label
+- 2026-01-05 @tobiu added the `architecture` label
+- 2026-01-05 @tobiu assigned to @tobiu
+- 2026-01-05 @tobiu added parent issue #8169
+

ai/mcp/server/neural-link/openapi.yaml

@@ -1231,18 +1231,35 @@ components:
               type: string
             port:
               type: integer
-        session:
-          type: object
-          properties:
-            activeApps:
-              type: integer
-            connectedWindows:
-              type: integer
-            agents:
-              type: array
-              items:
+        sessions:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+              connectedAt:
+                type: number
+              activeApps:
+                type: integer
+        windows:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+              appName:
                 type: string
-        details:
+              width:
+                type: number
+              height:
+                type: number
+              x:
+                type: number
+              y:
+                type: number
+        agents:
           type: array
           items:
             type: string

ai/mcp/server/neural-link/services/ConnectionService.mjs

@@ -235,18 +235,33 @@ class ConnectionService extends Base {
      * @returns {Object}
      */
     getStatus() {
-        const windows = [];
+        const
+            sessions = [],
+            windows  = [];
+
+        for (const [id, meta] of this.sessionData.entries()) {
+            sessions.push({
+                id,
+                connectedAt: meta.connectedAt,
+                activeApps : meta.windows ? meta.windows.size : 0
+            });
 
-        for (const meta of this.sessionData.values()) {
             if (meta.windows) {
                 for (const win of meta.windows.values()) {
-                    windows.push(win)
+                    windows.push({
+                        id     : win.windowId,
+                        appName: win.appName,
+                        width  : win.outerRect?.width,
+                        height : win.outerRect?.height,
+                        x      : win.outerRect?.x,
+                        y      : win.outerRect?.y
+                    })
                 }
             }
         }
 
         return {
-            sessions       : this.sessionData.size,
+            sessions,
             windows,
             bridgeConnected: !!this.bridgeSocket,
             agentId        : this.agentId,

ai/mcp/server/neural-link/services/HealthService.mjs

@@ -33,26 +33,11 @@ class HealthService extends Base {
      */
     async healthcheck() {
         try {
-            const status  = ConnectionService.getStatus();
-            const details = [];
-            let   health  = 'healthy';
+            const status = ConnectionService.getStatus();
+            let   health = 'healthy';
 
             if (!status.bridgeConnected) {
-                health = 'unhealthy';
-                details.push('Not connected to Neural Link Bridge');
-            } else {
-                details.push('Connected to Neural Link Bridge');
-            }
-
-            if (status.sessions === 0) {
-                details.push('No active App Worker sessions');
-            } else {
-                details.push(`${status.sessions} active App Worker session(s)`);
-                details.push(`${status.windows.length} connected window(s)`);
-            }
-
-            if (status.agents && status.agents.length > 0) {
-                details.push(`${status.agents.length} other agent(s) connected`);
+                health = 'unhealthy'
             }
 
             return {
@@ -63,20 +48,16 @@ class HealthService extends Base {
                     agentId  : status.agentId,
                     port     : ConnectionService.port
                 },
-                session  : {
-                    activeApps      : status.sessions,
-                    connectedWindows: status.windows.length,
-                    agents          : status.agents || []
-                },
-                details,
+                sessions : status.sessions,
+                windows  : status.windows,
+                agents   : status.agents,
                 version  : process.env.npm_package_version || '1.0.0',
                 uptime   : process.uptime()
             };
         } catch (error) {
             logger.error('[HealthService] Unexpected error during health check:', error);
             return {
                 status : 'unhealthy',
-                details: [`Unexpected error: ${error.message}`],
                 error  : 'Health check failed unexpectedly',
                 message: error.message,
                 code   : 'HEALTH_CHECK_ERROR'