feat(agent-bff): validate relation filters against the foreign collection

[Tonours]

fixes PRD-677

Problem

Relation list and count requests were forwarded without validating filters, projections, and sorts against the capabilities of the foreign collection.

Fix

• Validate relation list filters, projections, and sorts against the foreign collection.
• Validate relation count filters against the foreign collection.
• Re-check the parent collection, relation target, and foreign collection after capability reads.
• Return a local 404 when a foreign collection disappears during a failed capability read.
• Preserve the filter_too_deep error type and maxDepth details for deeply nested filters.
• Add regression coverage for list/count validation, schema refreshes, stale targets, and error contracts.

Scope and safety

• Changes are limited to packages/agent-bff.
• No change to agent, agent-client, or MCP packages.
• Requests without constrained inputs still skip the capabilities fetch.
• The agent remains the authority for access control.

How to test

yarn workspace @forestadmin/agent-bff test
yarn workspace @forestadmin/agent-bff build
yarn workspace @forestadmin/agent-bff lint

Verified: 733 tests passing across 54 suites.

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-677

[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/data/agent-query.ts	100.0%
	packages/agent-bff/src/validation/capabilities-validator.ts	100.0%
	packages/agent-bff/src/data/data-routes-middleware.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.