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

[Scra3]

Summary

• 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
• MCP OAuth token extraction/injection handled in createAiProvider wrapper
• @forestadmin/ai-proxy fully removed from agent dependencies (not even a peer dep)

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.

Multiple AI support (future)

When we need to support multiple AI configurations, only createAiProvider needs to change:

// createAiProvider accepts variadic configs - Router already supports aiConfigurations[]
export function createAiProvider(...configs: AiConfiguration[]): AiProviderDefinition

// Usage
agent.addAi(createAiProvider(
  { name: 'gpt4o', provider: 'openai', model: 'gpt-4o', apiKey: '...' },
  { name: 'claude', provider: 'anthropic', model: 'claude-sonnet-4-5-20250929', apiKey: '...' },
));

No changes needed in agent - addAi already accepts AiProviderDefinition which has providers: AiProviderMeta[]. The Router already handles config selection via the ai-name query parameter.

Test plan

• All 3 packages build successfully (datasource-toolkit, ai-proxy, agent)
• datasource-toolkit tests pass
• ai-proxy tests pass (99 tests) including createAiProvider wrapper tests
• agent tests pass (883 tests)
• ai-proxy not present in agent package.json at all
• No changes to packages/ai-proxy/src/router.ts

Generated with Claude Code

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): makeRoutes	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.08%.

Modified Files with Diff Coverage (7)

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/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.

[Scra3]

Code Review Summary

Reviewed 22 changed files across packages/agent, packages/ai-proxy, and packages/datasource-toolkit.

Result: No issues found ✅

The refactoring cleanly decouples @forestadmin/ai-proxy from @forestadmin/agent using the factory injection pattern. Key observations:

• Error handling: Cross-package error identification via error.name is a sound approach for the decoupling goal
• Type design: AiProviderDefinition and AiRouter interfaces provide clean contracts between packages
• Test coverage: Comprehensive tests including error inheritance, MCP config handling, and edge cases
• No bugs, security issues, or CLAUDE.md violations detected

🤖 Generated with Claude Code

[Scra3]

type was wrong