feat(ai-proxy): add forest connectors

[nbouliol]

Definition of Done

General

• Write an explicit title for the Pull Request, following Conventional Commits specification
• Test manually the implemented changes
• Validate the code quality (indentation, syntax, style, simplicity, readability)

Security

• Consider the security impact of the changes made

Note

Add Zendesk connector and refactor tool providers into a unified ToolProvider abstraction

• Introduces a ToolProvider interface with loadTools, checkConnection, and dispose methods, replacing direct McpClient lifecycle management in the router.
• Adds ForestIntegrationClient supporting Zendesk as a Forest connector, exposing 6 Zendesk tools (get/create/update tickets, get/create comments) via ServerRemoteTool.
• Adds BraveToolProvider to wrap Brave search tools; Brave is no longer auto-injected into RemoteTools but supplied via the provider pipeline.
• Introduces createToolProviders factory that splits a heterogeneous Record<string, ToolConfig> into McpClient and ForestIntegrationClient instances.
• Renames the routing parameter from mcpConfigs/mcpServerConfigs to toolConfigs across the router, agent, and public API surface; validMcpConfigurationOrThrow is renamed to validToolConfigurationOrThrow.
• Behavioral Change: McpClient.loadTools now returns tools directly instead of accumulating internal state; testConnections/closeConnections are renamed to checkConnection/dispose.

^{Macroscope summarized 402767a.}

[qltysh]

5 new issues

Tool	Category	Rule	Count
qlty	Duplication	Found 27 lines of similar code in 2 locations (mass = 106)	2
qlty	Structure	Function with high complexity (count = 18): createUpdateTicketTool	2
qlty	Structure	Function with many returns (count = 4): route	1

[qltysh]

Coverage Impact

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

Modified Files with Diff Coverage (20)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-testing/src/forest-admin-client-mock.ts	0.0%	52
	packages/ai-proxy/src/remote-tools.ts	100.0%
	packages/ai-proxy/src/router.ts	100.0%
	packages/ai-proxy/src/oauth-token-injector.ts	100.0%
	packages/ai-proxy/src/mcp-client.ts	100.0%
	packages/ai-proxy/src/index.ts	100.0%
	packages/forestadmin-client/src/permissions/forest-http-api.ts	100.0%
	packages/ai-proxy/src/integrations/zendesk/tools/get-tickets.ts	100.0%
	packages/ai-proxy/src/integrations/zendesk/tools/create-ticket.ts	100.0%
	packages/ai-proxy/src/tool-provider-factory.ts	100.0%
	packages/ai-proxy/src/integrations/zendesk/tools.ts	100.0%
	packages/ai-proxy/src/forest-integration-client.ts	100.0%
	packages/ai-proxy/src/integrations/brave/tools.ts	75.0%	12
	packages/ai-proxy/src/integrations/zendesk/tools/update-ticket.ts	100.0%
	packages/ai-proxy/src/tool-source-checker.ts	100.0%
	packages/ai-proxy/src/integrations/zendesk/utils.ts	100.0%
	...-proxy/src/integrations/zendesk/tools/create-ticket-comment.ts	100.0%
	packages/ai-proxy/src/integrations/zendesk/tools/get-ticket.ts	100.0%
	...ai-proxy/src/integrations/zendesk/tools/get-ticket-comments.ts	100.0%
	packages/ai-proxy/src/integrations/brave/brave-tool-provider.ts	100.0%
	Total	98.9%

🤖 Increase coverage with AI coding...

In the `feat/ai-tools-integrations` branch, add test coverage for this new code:

- `packages/agent-testing/src/forest-admin-client-mock.ts` -- Line 52
- `packages/ai-proxy/src/integrations/brave/tools.ts` -- Line 12

🚦 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]

could be private

[macroscopeapp]

🟠 High zendesk/utils.ts:22

assertResponseOk extracts json.error directly into the error message, but the API can return { error: { title: '...' } }. When json.error is an object, string interpolation produces [object Object], discarding the actual error details. The sibling function validateZendeskConfig handles this correctly with json.error?.title.

-      errorMessage = json.error || json.title || json.description || errorMessage;
+      errorMessage = json.error?.title || json.error || json.title || json.description || errorMessage;

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/ai-proxy/src/integrations/zendesk/utils.ts around line 22:

`assertResponseOk` extracts `json.error` directly into the error message, but the API can return `{ error: { title: '...' } }`. When `json.error` is an object, string interpolation produces `[object Object]`, discarding the actual error details. The sibling function `validateZendeskConfig` handles this correctly with `json.error?.title`.

Evidence trail:
packages/ai-proxy/src/integrations/zendesk/utils.ts lines 16-28 (assertResponseOk) and lines 30-46 (validateZendeskConfig) at REVIEWED_COMMIT. Line 22 uses `json.error` directly, while line 40 correctly uses `json.error?.title` to extract nested error details.

[Scra3]

👌