[Tonours]

fixes PRD-1383

agent-bff now exposes what a listener other than forest-bff needs, so the future forest-gateway (PRD-1337) can reuse it; forest-bff behaves exactly as today.

What

• BFFHttpServer: config optional with a prebuilt callback, new name option for its logs (default "Forest BFF"). Its assembled mode (version + middlewares) is now @deprecated, removed at the next major.
• installShutdownHandlers(target, logger, { name }) exported from the entry point, takes any { stop(): Promise<void> }, with one latch: a second SIGTERM/SIGINT is logged and ignored, stop() runs once.
• buildBff returns health(): the full GET /health body (status, version, configured), the same object the route serves.
• buildBff({ gatewayVersion }) sets X-Forest-Gateway-Version; X-Forest-Bff-Version keeps agent-bff's version. Named gatewayVersion, not version (Nico's call on PRD-1383): heads-up for PRD-1354 and PRD-1337.
• renderOpenApi(env, logger, { basePath }) moved to openapi/render-openapi.ts and exported, so the entry point doesn't load the CLI module; forest-bff openapi passes nothing.

Why

PRD-1337 serves the MCP and the API on one port with one process. It needs a listener that doesn't require a BFFConfig (MCP-only), doesn't log "Forest BFF", and one health source for its root /health. Landing this alone keeps the hosted API service redeploy a no-op.

How

• Health derivation moved out of the route into describeHealth; the route and health() read the same value.
• The OpenAPI invariant test now allows renderOpenApi on the public surface: it returns a string, it mounts nothing.

Verification

• Tests and CI: one test block per AC on the package entry point; /health key order is pinned on the wire. Suite 2191/2191, lint, tsc and CI (30 pass) green at 9123d9087.
• Independent review (read-only): GO WITH NOTES. Delta 114ebab4c..fd9b9b5e2 reviewed (t-0042): GO WITH NOTES.
• Real-stack e2e on 44b5dc134 against main on identical env: forest-bff CLI over the v2-ruby bench, plus addBff embedded in a harness agent.

Check	Result	Detail
Boot and shutdown log lines	✅	identical to main
/health GET + HEAD (ok, degraded, key-only)	✅	identical to main
Headers	✅	X-Forest-Bff-Version only, no Gateway header, as on main
Signals: single SIGTERM, then a second signal while stopping	✅	clean stop; intended delta: Ignoring the signal... replaces main's failed second stop
forest-bff openapi (generic + unfolded)	✅	byte-identical
addBff embedded harness	✅	diff-empty
Docker image	⛔	not run in the e2e; CI smoke job (and a local smoke run on 114ebab4c)

• The three commits after 44b5dc134 are unit-tested only: a doc-comment move, a guard for a synchronous stop() throw, and version added to health(). The /health body is unchanged: same keys, same order.
• Limits: the Gateway-path surfaces (no-config listener, name, gatewayVersion, renderOpenApi basePath) stay unit-tested only until PRD-1337 consumes them.

Release note

Merging republishes @forestadmin/agent-bff (and @forestadmin/agent through the exact pin) and redeploys the hosted API service, with no behavior change.

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

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (8)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/http/version-header-middleware.ts	100.0%
	packages/agent-bff/src/http/health-route.ts	100.0%
	packages/agent-bff/src/cli-dispatch.ts	100.0%
	packages/agent-bff/src/cli-core.ts	100.0%
	packages/agent-bff/src/build-bff.ts	100.0%
	packages/agent-bff/src/http/bff-http-server.ts	100.0%
	packages/agent-bff/src/index.ts	100.0%
	packages/agent-bff/src/openapi/render-openapi.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.

[nbouliol]

Spec (PRD-1383, prepare agent-bff for a prebuilt listener): the six acceptance criteria are met. One gap against the recorded decision on the health() shape, inline.

[nbouliol]

Approved after /verify-fixes run 1966-20261006080209-nbouliol-verify: 1 findings of 1966-20261006072011-nbouliol closed or accepted, none reopened.