[Tonours]

Moves the agent edge (read model, transport, unfold source, agent and AI middlewares) out of build-bff.ts into agent-edge.ts. Pure move: middleware order unchanged, no public export change.

fixes PRD-1544

What

File	Change
packages/agent-bff/src/agent-edge.ts (new, 297 lines)	resolveReadModelBundle, resolveTransport, toUnfoldSource, resolveUnfoldSource, buildAgentRouteMiddlewares, buildAiMiddlewares, buildAgentMiddlewares, agentScoped, copied verbatim with their comments
packages/agent-bff/src/api-key/api-key-edge.ts (new, 59 lines)	resolveApiKeyConfig, buildApiKeyMiddleware, createApiKeyUnavailableGuard
packages/agent-bff/src/build-bff.ts (635 to 313 lines)	Keeps options and types, body guards, the OAuth edge and buildBff. Re-exports resolveUnfoldSource, so render-openapi.ts is untouched
packages/agent-bff/test/openapi/openapi-mount-invariant.test.ts	Allowlist only: the openapi/* imports move from build-bff.ts to agent-edge.ts with the code

Why

• Follow-up promised in the R1 review (PRD-1542): build-bff.ts mixed body guards, the OAuth edge, the API key edge and the agent routes.
• The ticket kept the API key edge in build-bff.ts, but only the agent edge calls it: leaving it there would make build-bff.ts and agent-edge.ts import each other at runtime. It moves to a leaf module next to the other api-key/ files instead.
• agent-edge.ts reads OAuthEdge from build-bff.ts as a type import only, erased at compile time.
• The mount invariant test is the one test edit: it pins which non-openapi/ files may import openapi/*, and that import moved with the code. The rule it guards is unchanged.

How to test

Check	Result
yarn workspace @forestadmin/agent-bff test	111 suites, 2290 tests passed
git diff --stat origin/main -- packages/agent-bff/test	only openapi-mount-invariant.test.ts, +2/-1
chain in buildAgentMiddlewares and middlewares in buildBff vs origin/main	diff identical
npx tsc --noEmit -p packages/agent-bff, npx eslint on the three files	clean
Trust bench, subject 4ac5d17 vs baseline e98f1bd (main), real stack: smoke (forest-bff CLI against a v1-express agent, API key) and gateway-api-rename (cli, bff, gateway, boot mounts)	0 differences over 164 assertions; smoke PASS on both roles; api-rename fails the same 13 assertions on both roles (recipe pins old package versions and fixture tables), so no PR effect
git diff origin/main -- packages/agent-bff/src/index.ts	empty

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

[linear-code]

PRD-1544

[qltysh]

2 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): buildAgentRouteMiddlewares	2

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (3)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/build-bff.ts	100.0%
	packages/agent-bff/src/agent-edge.ts	100.0%
	packages/agent-bff/src/api-key/api-key-edge.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.

[PMerlet]

Approved after /validator run 2037-20261023150648-PMerlet: nothing blocking posted, 0 preferential or code style, 0 suppressed below all.