Merge pull request #1032 from objectstack-ai/copilot/fix-discovery-api-routing-issues-again

Author: hotlong

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Discovery Schema — `ServiceStatus` enum & `handlerReady` field** — Added `'registered'`
+  status to `ServiceInfoSchema` to distinguish routes that are declared in the dispatcher
+  table but whose HTTP handler has not been verified. Added optional `handlerReady` boolean
+  field (omitted = unverified/unknown) so clients can filter handler-ready services before
+  displaying endpoints when the value is explicitly `true`.
+- **Discovery Schema — `RouteHealthReportSchema`** — New schema for automated route/handler
+  coverage reporting at startup. Includes per-route health entries (`pass`, `fail`, `missing`,
+  `skip`) and summary counters.
+- **Dispatcher Schema — `DispatcherErrorCode` & `DispatcherErrorResponseSchema`** — Semantic
+  error codes (`404`/`405`/`501`/`503`) with machine-readable `type` field
+  (`ROUTE_NOT_FOUND`, `METHOD_NOT_ALLOWED`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`) and
+  developer-facing `hint` strings.
+- **Dispatcher Schema — `/health` route** — Added health endpoint to `DEFAULT_DISPATCHER_ROUTES`.
+- **REST API Plugin — `handlerStatus` field** — Added `handlerStatus` (`implemented`, `stub`,
+  `planned`) to `RestApiEndpointSchema` to track handler implementation readiness.
+- **REST API Plugin — `RouteCoverageReportSchema`** — Schema for adapter-generated coverage
+  reports listing every declared endpoint and its implementation status.
+- `ai` v6 as a dependency of `@objectstack/spec` for type re-exports
+
 ### Changed
 - **AI Chat Protocol Aligned with Vercel AI SDK** — Removed custom AI chat protocol
   types and Zod schemas (`AIMessage`, `AIToolCall`, `AIStreamEvent`,
@@ -32,6 +52,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Conversation services serialize/deserialize `ModelMessage` union to flat DB columns
   - All 158 service-ai tests updated and passing
 
+### Fixed
+- **Runtime Dispatcher — semantic error differentiation** — `HttpDispatcher.dispatch()` now
+  returns typed 404 (`ROUTE_NOT_FOUND`) with diagnostic info instead of bare `{ handled: false }`.
+  Added `routeNotFound()` (404) helper method.
+- **Runtime Dispatcher — `/health` handler** — Added health endpoint returning `status`,
+  `timestamp`, `version`, and `uptime`.
+- **Runtime Dispatcher — `handlerReady` in discovery** — `getDiscoveryInfo()` now emits
+  `handlerReady: true` for services with confirmed handlers and `handlerReady: false` for
+  unavailable services.
+- **Dispatcher Plugin — semantic 404** — `sendResult()` now returns `ROUTE_NOT_FOUND` error
+  type with a hint pointing to the discovery endpoint. Added `/health` handler registration.
+- **Studio — handler-ready filtering** — `useApiDiscovery()` now checks both `enabled` and
+  `handlerReady` (or `status === 'available' | 'degraded'` for backward compatibility) before
+  displaying service endpoints in the UI.
+
 ### Removed
 - `AiChatRequestSchema` / `AiChatResponseSchema` Zod schemas from
   `@objectstack/spec/api` — the AI chat wire protocol now uses Vercel AI SDK's
@@ -40,9 +75,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `@ai-sdk/react/useChat` directly
 - AI `/chat` endpoint from `DEFAULT_AI_ROUTES` plugin REST API definition
 
-### Added
-- `ai` v6 as a dependency of `@objectstack/spec` for type re-exports
-
 ## [4.0.1] — 2026-03-31
 
 ### Fixed

apps/studio/src/hooks/use-api-discovery.ts

@@ -227,15 +227,23 @@ export function useApiDiscovery() {
       // 2. Build service endpoints from discovery
       const serviceEndpoints: EndpointDef[] = [];
       for (const [serviceName, catalog] of Object.entries(SERVICE_ENDPOINT_CATALOG)) {
-        const serviceInfo = discoveredServices[serviceName];
+        const serviceInfo = discoveredServices[serviceName] as
+          | { enabled: boolean; status?: string; handlerReady?: boolean; route?: string }
+          | undefined;
+
+        // Only include services that are both enabled and have a handler ready.
+        // Backwards-compatible: if handlerReady is not present (older backends),
+        // treat status === 'available' or status === 'degraded' as equivalent to handlerReady: true.
         const isEnabled = serviceInfo?.enabled ?? false;
+        const hasHandler = serviceInfo?.handlerReady
+          ?? (serviceInfo?.status === 'available' || serviceInfo?.status === 'degraded');
 
         // Use route from discovery services, discovery routes map, or catalog default
         const routePrefix = serviceInfo?.route
           ?? discoveredRoutes[serviceName]
           ?? catalog.defaultRoute;
 
-        if (isEnabled) {
+        if (isEnabled && hasHandler) {
           serviceEndpoints.push(...buildServiceEndpoints(serviceName, routePrefix));
         }
       }

packages/runtime/src/dispatcher-plugin.ts

@@ -12,7 +12,8 @@ export interface DispatcherPluginConfig {
 }
 
 /**
- * Send an HttpDispatcherResult through IHttpResponse
+ * Send an HttpDispatcherResult through IHttpResponse.
+ * Differentiates between handled, unhandled (404), and special results.
  */
 function sendResult(result: HttpDispatcherResult, res: any): void {
     if (result.handled) {
@@ -32,7 +33,16 @@ function sendResult(result: HttpDispatcherResult, res: any): void {
             return;
         }
     }
-    res.status(404).json({ success: false, error: { message: 'Not Found', code: 404 } });
+    // Semantic 404: no route matched — include diagnostic info
+    res.status(404).json({
+        success: false,
+        error: {
+            message: 'Not Found',
+            code: 404,
+            type: 'ROUTE_NOT_FOUND',
+            hint: 'No handler matched this request. Check the API discovery endpoint for available routes.',
+        },
+    });
 }
 
 function errorResponse(err: any, res: any): void {
@@ -96,6 +106,16 @@ export function createDispatcherPlugin(config: DispatcherPluginConfig = {}): Plu
                 res.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
             });
 
+            // ── Health ──────────────────────────────────────────────────
+            server.get(`${prefix}/health`, async (_req: any, res: any) => {
+                try {
+                    const result = await dispatcher.dispatch('GET', '/health', undefined, {}, { request: _req });
+                    sendResult(result, res);
+                } catch (err: any) {
+                    errorResponse(err, res);
+                }
+            });
+
             // ── Auth ────────────────────────────────────────────────────
             server.post(`${prefix}/auth/login`, async (req: any, res: any) => {
                 try {

packages/runtime/src/http-dispatcher.root.test.ts

@@ -61,13 +61,16 @@ describe('HttpDispatcher Root Handling', () => {
         expect(data.routes).toBeDefined();
     });
 
-    it('should NOT handle POST request to root path ("")', async () => {
+    it('should return semantic 404 for POST request to root path ("")', async () => {
         const context = { request: {} };
         const method = 'POST';
         const path = '';
 
         const result = await dispatcher.dispatch(method, path, {}, {}, context);
 
-        expect(result.handled).toBe(false);
+        // The dispatcher now returns a typed 404 (ROUTE_NOT_FOUND) instead of { handled: false }
+        expect(result.handled).toBe(true);
+        expect(result.response?.status).toBe(404);
+        expect(result.response?.body?.error?.type).toBe('ROUTE_NOT_FOUND');
     });
 });

packages/runtime/src/http-dispatcher.ts

@@ -59,6 +59,25 @@ export class HttpDispatcher {
         };
     }
 
+    /**
+     * 404 Route Not Found — no route is registered for this path.
+     */
+    private routeNotFound(route: string) {
+        return {
+            status: 404,
+            body: {
+                success: false,
+                error: {
+                    code: 404,
+                    message: `Route Not Found: ${route}`,
+                    type: 'ROUTE_NOT_FOUND' as const,
+                    route,
+                    hint: 'No route is registered for this path. Check the API discovery endpoint for available routes.',
+                },
+            },
+        };
+    }
+
     private ensureBroker() {
         if (!this.kernel.broker) {
             throw { statusCode: 500, message: 'Kernel Broker not available' };
@@ -133,11 +152,14 @@ export class HttpDispatcher {
         };
 
         // Build per-service status map
+        // handlerReady: true means the dispatcher has a real, bound handler for this route.
+        // handlerReady: false means the route is present in the discovery table but may not
+        // yet have a concrete implementation or may be served by a stub.
         const svcAvailable = (route?: string, provider?: string) => ({
-            enabled: true, status: 'available' as const, route, provider,
+            enabled: true, status: 'available' as const, handlerReady: true, route, provider,
         });
         const svcUnavailable = (name: string) => ({
-            enabled: false, status: 'unavailable' as const,
+            enabled: false, status: 'unavailable' as const, handlerReady: false,
             message: `Install a ${name} plugin to enable`,
         });
 
@@ -174,7 +196,7 @@ export class HttpDispatcher {
             },
             services: {
                 // Kernel-provided (always available via protocol implementation)
-                metadata:       { enabled: true, status: 'degraded' as const, route: routes.metadata, provider: 'kernel', message: 'In-memory registry; DB persistence pending' },
+                metadata:       { enabled: true, status: 'degraded' as const, handlerReady: true, route: routes.metadata, provider: 'kernel', message: 'In-memory registry; DB persistence pending' },
                 data:           svcAvailable(routes.data, 'kernel'),
                 // Plugin-provided — only available when a plugin registers the service
                 auth:           hasAuth ? svcAvailable(routes.auth) : svcUnavailable('auth'),
@@ -1207,6 +1229,19 @@ export class HttpDispatcher {
              };
         }
 
+        // 0b. Health Endpoint (GET /health)
+        if (cleanPath === '/health' && method === 'GET') {
+            return {
+                handled: true,
+                response: this.success({
+                    status: 'ok',
+                    timestamp: new Date().toISOString(),
+                    version: '1.0.0',
+                    uptime: typeof process !== 'undefined' ? process.uptime() : undefined,
+                }),
+            };
+        }
+
         // 1. System Protocols (Prefix-based)
         if (cleanPath.startsWith('/auth')) {
             return this.handleAuth(cleanPath.substring(5), method, body, context);
@@ -1265,8 +1300,11 @@ export class HttpDispatcher {
         const result = await this.handleApiEndpoint(cleanPath, method, body, query, context);
         if (result.handled) return result;
 
-        // 3. Fallback (404)
-        return { handled: false };
+        // 3. Fallback — return semantic 404 with diagnostic info
+        return {
+            handled: true,
+            response: this.routeNotFound(cleanPath),
+        };
     }
 
     /**