refactor(agent): serve root-mounted handlers through one registry

[nbouliol]

Stacked on #1874. Touches only packages/agent, so it can be reviewed independently of the agent-bff PRs below it in the stack.

Why

McpMiddleware held one callback and one matcher. That was enough while the MCP server was the only thing the agent served at the root of a host application, next to its own /{prefix}/forest router. The embedded BFF needs the same treatment on /bff/*, and two singletons wired into five mount points is how mount points drift apart.

What

RootMiddleware keeps handlers by name, each with the matcher declaring which urls it claims. Unclaimed urls fall through to the host untouched, exactly as before.

The five mount points (mountOnExpress, mountOnFastify, mountOnKoa, mountOnNestJs, and the connect callback mountOnStandaloneServer uses) change only in the type they call.

One behavior does tighten: on the connect and Express paths the MCP callback used to be handed every request and trusted to filter itself, while only the Koa path applied the matcher. The matcher now applies everywhere. makeIsMcpRoute is what the MCP server filters on internally, so the claimed set is the same.

Nothing registers a second handler yet — the BFF arrives in the next PR.

Tests

82 suites, 1502 tests in @forestadmin/agent. The old mcp-middleware suite becomes root-middleware, plus coverage for what is new: dispatch to the right handler among several, and a null callback while nothing is registered so the host keeps its untouched path.

Fixes PRD-1076

🤖 Generated with Claude Code

Note

Serve root-mounted handlers through one RootMiddleware registry

• Replaces the deleted McpMiddleware with a new RootMiddleware class in root-middleware.ts that hosts multiple named root-level handlers (e.g. MCP, BFF) keyed by URL matcher.
• Adds mcp-routes.ts exporting isMcpRoute(url), which matches /.well-known/, /oauth/, and /mcp prefixes; MCP callback registration in FrameworkMounter.setMcpCallback now delegates to RootMiddleware.set('mcp', ...).
• All framework mounts (mountOnExpress, mountOnFastify, mountOnKoa, mountOnNestJs) and getConnectCallback in framework-mounter.ts now dispatch through RootMiddleware; unclaimed URLs fall through to the host unchanged.
• Risk: RootMiddleware.getCallback() returns null when no handlers are registered, unlike the old single-callback path; any out-of-tree callers relying on McpMiddleware or a non-null root callback will break.

^{Macroscope summarized 46447d8.}

[linear-code]

PRD-1076

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (3)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/framework-mounter.ts	100.0%
	packages/agent/src/mcp-routes.ts	66.7%	8
	packages/agent/src/root-middleware.ts	100.0%
	Total	96.9%

🤖 Increase coverage with AI coding...

In the `feature/prd-1076-6-root-middleware` branch, add test coverage for this new code:

- `packages/agent/src/mcp-routes.ts` -- Line 8

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