feat(ai): Implement Navigation Control & History (#8184)

- Add getRouteHistory and setRoute to RuntimeService (client & server)
- Expose get_route_history and set_route via MCP
- Update OpenAPI spec
- Add tool mappings

Author: tobiu

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

@@ -368,6 +368,93 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
 
+  /navigation/history:
+    post:
+      summary: Get Route History
+      operationId: get_route_history
+      x-pass-as-object: true
+      description: |
+        Retrieves the navigation history stack and current route information.
+
+        **When to Use:**
+        To understand where the user is in the application and how they got there.
+      tags: [Navigation]
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GetRouteHistoryRequest'
+      responses:
+        '200':
+          description: Route history
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  count:
+                    type: integer
+                  windowId:
+                    type: integer
+                  history:
+                    type: array
+                    items:
+                      type: object
+        '400':
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /navigation/route/set:
+    post:
+      summary: Set Route
+      operationId: set_route
+      x-pass-as-object: true
+      description: |
+        Navigates the application to a specific route (hash).
+
+        **When to Use:**
+        To drive the application to a specific view or state.
+      tags: [Navigation]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SetRouteRequest'
+      responses:
+        '200':
+          description: Route set successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                  hash:
+                    type: string
+        '400':
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Internal server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
   /server/start:
     post:
       summary: Start WebSocket Server
@@ -609,6 +696,31 @@ components:
           type: string
           description: The target App Worker Session ID
 
+    GetRouteHistoryRequest:
+      type: object
+      properties:
+        windowId:
+          type: integer
+          description: Optional window ID to get history for.
+        sessionId:
+          type: string
+          description: The target App Worker Session ID
+
+    SetRouteRequest:
+      type: object
+      required:
+        - hash
+      properties:
+        hash:
+          type: string
+          description: The new hash value to set (e.g., "#mainview=home").
+        windowId:
+          type: integer
+          description: Optional window ID to target.
+        sessionId:
+          type: string
+          description: The target App Worker Session ID
+
     SetComponentPropertyRequest:
       type: object
       required:

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

@@ -25,6 +25,17 @@ class RuntimeService extends Base {
         singleton: true
     }
 
+    /**
+     * Retrieves the navigation history stack.
+     * @param {Object} opts            The options object.
+     * @param {String} opts.sessionId  The target session ID.
+     * @param {Number} [opts.windowId] Optional window ID.
+     * @returns {Promise<Object>}
+     */
+    async getRouteHistory({sessionId, windowId}) {
+        return await ConnectionService.call(sessionId, 'get_route_history', {windowId})
+    }
+
     /**
      * Retrieves the topology of all connected windows.
      * @returns {Promise<Object[]>} List of windows.
@@ -65,6 +76,18 @@ class RuntimeService extends Base {
     async reloadPage({sessionId}) {
         return await ConnectionService.call(sessionId, 'reload_page', {})
     }
+
+    /**
+     * Sets the application route (hash).
+     * @param {Object} opts            The options object.
+     * @param {String} opts.hash       The new hash value.
+     * @param {String} opts.sessionId  The target session ID.
+     * @param {Number} [opts.windowId] Optional window ID.
+     * @returns {Promise<Object>}
+     */
+    async setRoute({hash, sessionId, windowId}) {
+        return await ConnectionService.call(sessionId, 'set_route', {hash, windowId})
+    }
 }
 
 export default Neo.setupClass(RuntimeService);

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

@@ -17,6 +17,7 @@ const serviceMapping = {
     get_component_tree    : ComponentService  .getComponentTree    .bind(ComponentService),
     get_drag_state        : InteractionService.getDragState        .bind(InteractionService),
     get_record            : DataService       .getRecord           .bind(DataService),
+    get_route_history     : RuntimeService    .getRouteHistory     .bind(RuntimeService),
     get_vdom_tree         : ComponentService  .getVdomTree         .bind(ComponentService),
     get_vnode_tree        : ComponentService  .getVnodeTree        .bind(ComponentService),
     get_window_topology   : RuntimeService    .getWindowTopology   .bind(RuntimeService),
@@ -27,6 +28,7 @@ const serviceMapping = {
     query_component       : ComponentService  .queryComponent      .bind(ComponentService),
     reload_page           : RuntimeService    .reloadPage          .bind(RuntimeService),
     set_component_property: ComponentService  .setComponentProperty.bind(ComponentService),
+    set_route             : RuntimeService    .setRoute            .bind(RuntimeService),
     start_ws_server       : ConnectionService .startServer         .bind(ConnectionService),
     stop_ws_server        : ConnectionService .stopServer          .bind(ConnectionService)
 };

src/ai/Client.mjs

@@ -85,8 +85,10 @@ class Client extends Base {
             list_stores         : me.services.data,
 
             get_drag            : me.services.runtime,
+            get_route           : me.services.runtime,
             get_window          : me.services.runtime,
-            reload_page         : me.services.runtime
+            reload_page         : me.services.runtime,
+            set_route           : me.services.runtime
         };
 
         Neo.currentWorker.on({

src/ai/client/RuntimeService.mjs

@@ -1,4 +1,5 @@
-import Service from './Service.mjs';
+import HashHistory from '../../util/HashHistory.mjs';
+import Service     from './Service.mjs';
 
 /**
  * Handles runtime environment related Neural Link requests.
@@ -38,6 +39,22 @@ class RuntimeService extends Service {
         return {};
     }
 
+    /**
+     * @param {Object} params
+     * @returns {Object}
+     */
+    getRouteHistory(params) {
+        const
+            windowId = params.windowId,
+            stack    = HashHistory.getStack(windowId);
+
+        return {
+            count   : stack.length,
+            history : stack,
+            windowId: windowId || null
+        }
+    }
+
     /**
      * @param {Object} params
      * @returns {Object}
@@ -68,6 +85,19 @@ class RuntimeService extends Service {
         Neo.Main.reloadWindow();
         return {status: 'reloading'};
     }
+
+    /**
+     * @param {Object} params
+     * @returns {Object}
+     */
+    setRoute(params) {
+        Neo.Main.setRoute({
+            value   : params.hash,
+            windowId: params.windowId
+        });
+
+        return {status: 'ok', hash: params.hash}
+    }
 }
 
 export default Neo.setupClass(RuntimeService);