refactor(ai-proxy): make AIError extend BusinessError for native error handling

AIError and subclasses now extend BusinessError from datasource-toolkit
(BadRequestError, NotFoundError, UnprocessableError). The agent's error
middleware handles HTTP status mapping natively, removing the need for
duck-typed status checks and error re-wrapping in the route handler.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: alban bertolini

packages/agent/src/routes/ai/ai-proxy.ts

@@ -4,12 +4,6 @@ import type { AiRouter } from '@forestadmin/datasource-toolkit';
 import type KoaRouter from '@koa/router';
 import type { Context } from 'koa';
 
-import {
-  BadRequestError,
-  NotFoundError,
-  UnprocessableError,
-} from '@forestadmin/datasource-toolkit';
-
 import { HttpCode, RouteType } from '../../types';
 import BaseRoute from '../base-route';
 
@@ -31,30 +25,16 @@ export default class AiProxyRoute extends BaseRoute {
   }
 
   private async handleAiProxy(context: Context): Promise<void> {
-    try {
-      const mcpServerConfigs =
-        await this.options.forestAdminClient.mcpServerConfigService.getConfiguration();
-
-      context.response.body = await this.aiRouter.route({
-        route: context.params.route,
-        body: context.request.body,
-        query: context.query,
-        mcpServerConfigs,
-        requestHeaders: context.request.headers,
-      });
-      context.response.status = HttpCode.Ok;
-    } catch (error) {
-      const err = error as Error & { status?: number };
-
-      if (typeof err.status === 'number' && err.status >= 400 && err.status < 600) {
-        this.options.logger('Error', `AI proxy error: ${err.message}`, err);
-
-        if (err.status === 400) throw new BadRequestError(err.message);
-        if (err.status === 404) throw new NotFoundError(err.message);
-        throw new UnprocessableError(err.message);
-      }
-
-      throw error;
-    }
+    const mcpServerConfigs =
+      await this.options.forestAdminClient.mcpServerConfigService.getConfiguration();
+
+    context.response.body = await this.aiRouter.route({
+      route: context.params.route,
+      body: context.request.body,
+      query: context.query,
+      mcpServerConfigs,
+      requestHeaders: context.request.headers,
+    });
+    context.response.status = HttpCode.Ok;
   }
 }

packages/agent/test/routes/ai/ai-proxy.test.ts

@@ -1,10 +1,5 @@
 import type { AiRouter } from '@forestadmin/datasource-toolkit';
 
-import {
-  BadRequestError,
-  NotFoundError,
-  UnprocessableError,
-} from '@forestadmin/datasource-toolkit';
 import { createMockContext } from '@shopify/jest-koa-mocks';
 
 import AiProxyRoute from '../../../src/routes/ai/ai-proxy';
@@ -116,124 +111,20 @@ describe('AiProxyRoute', () => {
       );
     });
 
-    describe('error handling', () => {
-      test('should convert error with status 422 to UnprocessableError with original message', async () => {
-        const route = new AiProxyRoute(services, options, aiRouter);
-        const error = new Error('AI is not configured') as Error & { status: number };
-        error.status = 422;
-        mockRoute.mockRejectedValueOnce(error);
-
-        const context = createMockContext({
-          customProperties: {
-            params: { route: 'ai-query' },
-            query: {},
-          },
-          requestBody: {},
-        });
-
-        await expect((route as any).handleAiProxy(context)).rejects.toMatchObject({
-          name: 'UnprocessableError',
-          message: 'AI is not configured',
-        });
-      });
-
-      test('should convert error with status 404 to NotFoundError', async () => {
-        const route = new AiProxyRoute(services, options, aiRouter);
-        const error = new Error('Resource not found') as Error & { status: number };
-        error.status = 404;
-        mockRoute.mockRejectedValueOnce(error);
-
-        const context = createMockContext({
-          customProperties: {
-            params: { route: 'ai-query' },
-            query: {},
-          },
-          requestBody: {},
-        });
-
-        await expect((route as any).handleAiProxy(context)).rejects.toThrow(NotFoundError);
-      });
-
-      test('should convert error with status 400 to BadRequestError', async () => {
-        const route = new AiProxyRoute(services, options, aiRouter);
-        const error = new Error('Invalid input') as Error & { status: number };
-        error.status = 400;
-        mockRoute.mockRejectedValueOnce(error);
-
-        const context = createMockContext({
-          customProperties: {
-            params: { route: 'ai-query' },
-            query: {},
-          },
-          requestBody: {},
-        });
-
-        await expect((route as any).handleAiProxy(context)).rejects.toThrow(BadRequestError);
-      });
-
-      test('should convert error with other 4xx/5xx status to UnprocessableError', async () => {
-        const route = new AiProxyRoute(services, options, aiRouter);
-        const error = new Error('Server error') as Error & { status: number };
-        error.status = 500;
-        mockRoute.mockRejectedValueOnce(error);
-
-        const context = createMockContext({
-          customProperties: {
-            params: { route: 'ai-query' },
-            query: {},
-          },
-          requestBody: {},
-        });
-
-        await expect((route as any).handleAiProxy(context)).rejects.toThrow(UnprocessableError);
-      });
-
-      test('should re-throw unknown errors unchanged', async () => {
-        const route = new AiProxyRoute(services, options, aiRouter);
-        const unknownError = new Error('Unknown error');
-        mockRoute.mockRejectedValueOnce(unknownError);
-
-        const context = createMockContext({
-          customProperties: {
-            params: { route: 'ai-query' },
-          },
-          requestBody: {},
-        });
-        context.query = {};
-
-        const promise = (route as any).handleAiProxy(context);
+    test('should let errors from aiRouter propagate unchanged', async () => {
+      const route = new AiProxyRoute(services, options, aiRouter);
+      const error = new Error('AI error');
+      mockRoute.mockRejectedValueOnce(error);
 
-        await expect(promise).rejects.toBe(unknownError);
-        expect(unknownError).not.toBeInstanceOf(UnprocessableError);
+      const context = createMockContext({
+        customProperties: {
+          params: { route: 'ai-query' },
+          query: {},
+        },
+        requestBody: {},
       });
 
-      test('should log AI proxy errors before converting them', async () => {
-        const mockLogger = jest.fn();
-        const optionsWithLogger = factories.forestAdminHttpDriverOptions.build({
-          logger: mockLogger,
-        });
-        const route = new AiProxyRoute(services, optionsWithLogger, aiRouter);
-
-        const error = new Error('Some AI error') as Error & { status: number };
-        error.status = 422;
-        mockRoute.mockRejectedValueOnce(error);
-
-        const context = createMockContext({
-          customProperties: {
-            params: { route: 'ai-query' },
-            query: {},
-          },
-          requestBody: {},
-        });
-
-        await expect((route as any).handleAiProxy(context)).rejects.toThrow(UnprocessableError);
-
-        expect(mockLogger).toHaveBeenCalledWith(
-          'Error',
-          'AI proxy error: Some AI error',
-          expect.any(Error),
-        );
-      });
+      await expect((route as any).handleAiProxy(context)).rejects.toBe(error);
     });
   });
 });

packages/ai-proxy/src/errors.ts

@@ -1,34 +1,31 @@
 /**
- * -------------------------------------
- * -------------------------------------
- * -------------------------------------
  * All custom errors must extend the AIError class.
- * This inheritance is crucial for proper error translation
- * and consistent handling throughout the system.
- * -------------------------------------
- * -------------------------------------
- * -------------------------------------
+ * AIError extends BusinessError from datasource-toolkit, which means
+ * the agent's error middleware handles HTTP status mapping natively
+ * via baseBusinessErrorName.
  */
 
 // eslint-disable-next-line max-classes-per-file
-export class AIError extends Error {
-  readonly status: number;
-
-  constructor(message: string, status = 422) {
-    if (status < 100 || status > 599) {
-      throw new RangeError(`Invalid HTTP status code: ${status}`);
-    }
+import {
+  BadRequestError,
+  BusinessError,
+  NotFoundError,
+  UnprocessableError,
+} from '@forestadmin/datasource-toolkit';
 
+export class AIError extends BusinessError {
+  constructor(message: string) {
     super(message);
     this.name = 'AIError';
-    this.status = status;
+    this.baseBusinessErrorName = UnprocessableError.name;
   }
 }
 
 export class AIBadRequestError extends AIError {
   constructor(message: string) {
-    super(message, 400);
+    super(message);
     this.name = 'AIBadRequestError';
+    this.baseBusinessErrorName = BadRequestError.name;
   }
 }
 
@@ -43,21 +40,22 @@ export class AIModelNotSupportedError extends AIBadRequestError {
 
 export class AINotFoundError extends AIError {
   constructor(message: string) {
-    super(message, 404);
+    super(message);
     this.name = 'AINotFoundError';
+    this.baseBusinessErrorName = NotFoundError.name;
   }
 }
 
 export class AIUnprocessableError extends AIError {
   constructor(message: string) {
-    super(message, 422);
+    super(message);
     this.name = 'AIUnprocessableError';
   }
 }
 
 export class AINotConfiguredError extends AIError {
   constructor(message = 'AI is not configured') {
-    super(message, 422);
+    super(message);
     this.name = 'AINotConfiguredError';
   }
 }

packages/datasource-toolkit/src/interfaces/ai.ts

@@ -10,9 +10,8 @@ export interface AiRouter {
   /**
    * Route a request to the AI proxy.
    *
-   * Implementations should throw errors with a numeric `status` property (e.g. 400, 404, 422)
-   * for HTTP-status-based error translation. Errors without a `status` property
-   * are treated as unexpected internal errors and re-thrown as-is.
+   * Implementations should throw BusinessError subclasses (BadRequestError, NotFoundError,
+   * UnprocessableError) for proper HTTP status mapping by the agent's error middleware.
    */
   route(args: {
     route: string;