refactor(agent): decouple ai-proxy via factory injection pattern

[Scra3]

Summary

• Move @forestadmin/ai-proxy from hard dependency to optional peer dependency in @forestadmin/agent
• Introduce createAiProvider() factory in ai-proxy following the existing addDataSource(createSqlDataSource(...)) pattern
• Define shared AiRouter / AiProviderDefinition interfaces in datasource-toolkit
• Remove all @forestadmin/ai-proxy imports from agent source code (duck-typed error handling instead of instanceof)
• Router in ai-proxy now handles MCP OAuth token extraction/injection internally

Before:

agent.addAi({ provider: 'openai', model: 'gpt-4o', name: 'test', apiKey: '...' });

After:

import { createAiProvider } from '@forestadmin/ai-proxy';
agent.addAi(createAiProvider({ provider: 'openai', model: 'gpt-4o', name: 'test', apiKey: '...' }));

This eliminates ~6 langchain packages from the default install for users who don't use AI features.

Test plan

• All 3 packages build successfully (datasource-toolkit, ai-proxy, agent)
• datasource-toolkit tests pass (457 tests)
• ai-proxy tests pass (82 tests) including new createAiProvider test
• agent tests pass (886 tests) with updated mocks
• ai-proxy only appears in peerDependencies of agent's package.json

🤖 Generated with Claude Code

[qltysh]

2 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): makeRoutes	1
qlty	Structure	Function with many returns (count = 4): route	1

[Scra3]

Bundle size impact

By making @forestadmin/ai-proxy an optional peer dependency, users who don't use AI features no longer install the langchain ecosystem and LLM SDK dependencies.

Dependencies removed from default install:

Package	Size
@langchain/* (8 packages)	~58 MB
openai SDK	~13 MB
@anthropic-ai SDK	~5 MB
langsmith	~3 MB
ai-proxy transitive deps	~40 MB
Total saved	~119 MB

This represents a ~9% reduction of the total monorepo node_modules — but for end users doing a fresh npm install @forestadmin/agent, the savings are more significant since these AI/LLM packages represent a large chunk of the agent's own dependency tree.

Users who need AI features simply add npm install @forestadmin/ai-proxy and use the createAiProvider() factory.

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.05%.

Modified Files with Diff Coverage (8)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/agent.ts	100.0%
	packages/agent/src/routes/ai/ai-proxy.ts	100.0%
	packages/ai-proxy/src/router.ts	100.0%
	packages/ai-proxy/src/errors.ts	100.0%
	packages/agent/src/routes/index.ts	100.0%
	packages/ai-proxy/src/index.ts	100.0%
	packages/agent/src/utils/forest-schema/generator.ts	100.0%
	packages/ai-proxy/src/create-ai-provider.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[Scra3]

Breaking change: forestadmin-server error handling

AI errors now extend BusinessError subclasses directly instead of a single AIError base class:

• AIBadRequestError extends BadRequestError (was extends AIError)
• AINotFoundError extends NotFoundError (was extends AIError)
• AIUnprocessableError extends UnprocessableError (was extends AIError)
• AIError extends UnprocessableError (unchanged, still used by McpError, AINotConfiguredError)

Impact: instanceof AIError no longer catches AIBadRequestError, AINotFoundError, AIUnprocessableError.

Required change in forestadmin-server

packages/private-api/src/domain/ai/error-translator-http.ts:

 import {
-  AIError,
+  AIBadRequestError,
   AIToolNotFoundError,
   AIUnprocessableError,
   McpConfigError,
   McpConnectionError,
+  McpConflictError,
 } from '@forestadmin/ai-proxy';
 
 import {
+  BadRequestError,
   ConflictError,
   FailedDependencyError,
-  InternalServerError,
   NotFoundError,
   UnprocessableEntityError,
 } from '../../utils/errors/common-errors';

 export default function aiErrorTranslator(error: unknown) {
   if (!error || !(error instanceof Error)) return error;

   switch (true) {
+    case error instanceof AIBadRequestError:
+      return new BadRequestError(`AI: ${error.message}`);
     case error instanceof AIUnprocessableError:
       return new UnprocessableEntityError('AI command', `AI: ${error.message}`);
     case error instanceof AIToolNotFoundError:
       return new NotFoundError(`AI: ${error.message}`);
     case error instanceof McpConnectionError:
       return new FailedDependencyError('MCP Connection Error', null, error);
     case error instanceof McpConfigError:
       return new UnprocessableEntityError('MCP config', `MCP Config Error: ${error.message}`);
     case error instanceof McpConflictError:
       return new ConflictError('MCP config', `MCP Config Error: ${error.message}`);
-    case error instanceof AIError:
-      return new InternalServerError(`AI: ${error.message}`, null);
     default:
       return error;
   }
 }

This is actually more correct: AIBadRequestError was previously caught by the AIError catch-all and returned as 500 — it now correctly maps to 400.