fix(ai-proxy): use proper AI error classes instead of generic Error

- ForestIntegrationClient.checkConnection(): Error → AIBadRequestError
- assertResponseOk(): Error → AIToolUnprocessableError
- Add CLAUDE.md with error handling guidelines

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: alban bertolini

packages/ai-proxy/CLAUDE.md

@@ -0,0 +1,20 @@
+# @forestadmin/ai-proxy
+
+## Overview
+
+This package is used by both the Forest Admin agent (`@forestadmin/agent`) and the Forest Admin server. Both consumers bind AI error classes to HTTP status codes via their error middleware.
+
+## Error Handling
+
+All errors thrown in this package must extend an AI error class from `src/errors.ts`, never `new Error(...)` directly.
+
+Both the agent and the Forest Admin server map error classes to HTTP status codes. A bare `Error` will result in a generic 500 instead of the correct status.
+
+Choose the right error class based on context:
+- `AIBadRequestError` — invalid config, bad input from caller
+- `AIToolUnprocessableError` — tool invocation failed at runtime (e.g. Zendesk API returned an error)
+- `McpConnectionError` — MCP server connection validation failed
+- `AINotFoundError` / `AIToolNotFoundError` — resource or tool not found
+- `AIProviderError` — AI provider call failed
+
+See `src/errors.ts` for the full list.

packages/ai-proxy/src/forest-integration-client.ts

@@ -2,6 +2,7 @@ import type RemoteTool from './remote-tool';
 import type { ToolProvider } from './tool-provider';
 import type { Logger } from '@forestadmin/datasource-toolkit';
 
+import { AIBadRequestError } from './errors';
 import getZendeskTools, { type ZendeskConfig } from './integrations/zendesk/tools';
 import { validateZendeskConfig } from './integrations/zendesk/utils';
 
@@ -54,7 +55,7 @@ export default class ForestIntegrationClient implements ToolProvider {
           case 'Zendesk':
             return validateZendeskConfig(config as ZendeskConfig);
           default:
-            throw new Error(`Unsupported integration: ${integrationName}`);
+            throw new AIBadRequestError(`Unsupported integration: ${integrationName}`);
         }
       }),
     );

packages/ai-proxy/src/integrations/zendesk/utils.ts

@@ -1,6 +1,6 @@
 import type { ZendeskConfig } from './tools';
 
-import { McpConnectionError } from '../../errors';
+import { AIToolUnprocessableError, McpConnectionError } from '../../errors';
 
 export function getZendeskConfig(config: ZendeskConfig) {
   const baseUrl = `https://${config.subdomain}.zendesk.com/api/v2`;
@@ -24,7 +24,9 @@ export async function assertResponseOk(response: Response, action: string) {
       // Response body is not JSON
     }
 
-    throw new Error(`Zendesk ${action} failed (${response.status}): ${errorMessage}`);
+    throw new AIToolUnprocessableError(
+      `Zendesk ${action} failed (${response.status}): ${errorMessage}`,
+    );
   }
 }