[Tonours]

Customer-facing strings say "Gateway API" instead of "BFF", config errors from addGateway({ api }) name the option the customer wrote, and browsers can read the deprecation and version headers. refs PRD-1354

What

• OpenAPI info.title → Forest Gateway API, and every product-noun "BFF" in document descriptions (errors, retry-after headers, AI relay, timezone, servers, security schemes — "a Gateway API key") → "Gateway API"; env-var mentions (BFF_AGENT_TIMEOUT_MS, BFF_OPENAPI_ENABLED, BFF_PUBLIC_URL) unchanged.
• Docs page, CORS 403 message, sessionExpired default, Invalid Gateway API base path error, embedded 503 messages under addGateway() → "Gateway API" (the addBff() 503s stay byte-identical per AC2; error type codes unchanged).
• Access-Control-Expose-Headers: Deprecation, Link, Retry-After, X-Forest-Gateway-Version, X-Forest-Bff-Version on allowed responses.
• X-Forest-Gateway-Version carries @forestadmin/agent's version in embedded mode (both addBff() and addGateway({ api })), next to the unchanged X-Forest-Bff-Version.
• parseConfig(env, labels?) + buildBff({ labels?, name? }): a label map covering every key their messages name; addGateway({ api }) passes option labels (api.tokenEncryptionKey, …), addBff() and forest-bff keep today's messages byte-identical.
• Under addGateway(): [Gateway API] log tag, "The Gateway API mounted on …" mount log, Gateway API wording of the no-allowed-origin boot warning.

Why

The embedded API is sold as the Gateway API; every string the customer reads must name it, and errors must point at the option the customer actually wrote rather than an internal env key the embedded mode never reads.

How

• agent-bff: label resolver (CONFIG_KEYS/ConfigLabels) feeds every config-error message and boot warning; CORS middleware exposes the five headers next to Access-Control-Allow-Origin; string sweep in openapi-document.ts, schemas.ts, unfolded-paths.ts, docs-page.ts, docs-samples.ts.
• agent: EmbeddedBffMount.gateway flag drives tag/labels/name; buildBff gets gatewayVersion = the agent's own version.
• First commit cherry-picks feat(agent-bff): prepare a prebuilt listener for the gateway #1966 (PRD-1383, gatewayVersion option) from main: the train was cut before it landed, and this story builds on the option. No edits to its content, so the wave merge back to main sees identical bytes on both sides.

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

Verification

Check	Result
yarn workspace @forestadmin/agent-bff test	✅ 111 suites, 2226 tests
yarn workspace @forestadmin/agent test	✅ 93 suites, 1859 tests
ESLint + Prettier on touched files	✅ 0 errors
tsc via lerna run build (agent-bff, agent + deps)	✅
AC1 invalid api.tokenEncryptionKey names the option	✅ unit + embedded test
AC2 addBff() invalid option keeps today's message	✅ byte-identical, pinned
AC3 all listed strings say "Gateway API"	✅ per-file string tests + no-bare-BFF sweep of the OpenAPI document
AC4 headers readable from JS on a /bff route	✅ cors test + embedded e2e through the alias
AC5 OpenAPI title + security schemes	✅ Forest Gateway API, no "BFF"
AC6 addGateway() warnings say "Gateway API"	✅ log tests + boot-warning tests
Real-stack e2e (bench matrix, pinned builds vs feat/gateway-r1)	✅ PASS — subject 4/4 cells; baseline refusals confirmed (frozen pre-rename strings fail as expected). AC1–AC6 proven live incl. byte-level: addBff()/forest-bff messages byte-identical across legs; OpenAPI title Forest Gateway API, 0 bare "BFF" (env-var mentions literal); Access-Control-Expose-Headers + X-Forest-Gateway-Version carrying the agent version; [Gateway API] boot tags. Guards identical across legs: conformance, context/discovery signatures, boot no-drift, error type codes. Not replayed: MCP describe (diff touches 0 mcp-server files). Replayed on fix head 562284e84 after review fixes: exhaustive probe-output diff vs the previous run = exactly the 2 restored addBff() 503 strings, every other frozen value byte-identical, guards identical; CI 23 pass / 0 fail. Replayed on review-fix head 010887a98: subject exit 0 PASS (all measurable cells), baseline exit 3 negative-confirmed (frozen pre-rename strings refuse as expected); CI 29 pass / 0 fail. Review threads on this head: OpenAPI Gateway API key dedup, per-key-origin label naming api.allowedOrigins under addGateway(), gateway drain log pin — fixed; addBff() 503 wording — byte-identical per AC2/AC3 of the ticket (amended 2026-10-07)
CI	✅ all checks pass

[linear-code]

PRD-1354

[qltysh]

2 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 8): buildAgentMiddlewares	1
qlty	Structure	High total complexity (count = 64)	1

[qltysh]

Coverage Impact

Unable to calculate total coverage change because base branch coverage was not found.

Modified Files with Diff Coverage (16)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/openapi/openapi-document.ts	100.0%
	packages/agent-bff/src/http/bff-http-error.ts	100.0%
	packages/agent-bff/src/http/version-header-middleware.ts	100.0%
	packages/agent-bff/src/http/health-route.ts	100.0%
	packages/agent/src/embedded-bff.ts	90.9%	57
	packages/agent-bff/src/cli-dispatch.ts	100.0%
	packages/agent-bff/src/config/missing-config-warning.ts	100.0%
	packages/agent-bff/src/cors/cors-middleware.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/config/env-config.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/cors/per-key-origin.ts	100.0%
	packages/agent/src/gateway.ts	100.0%
	packages/agent-bff/src/openapi/render-openapi.ts	100.0%
	Total	99.1%

🤖 Increase coverage with AI coding...

In the `hp/gateway-mcp-bff/t-0049-prd-1354-rename-gateway-api-plan-impleme` branch, add test coverage for this new code:

- `packages/agent/src/embedded-bff.ts` -- Line 57

🚦 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-1354): conforms, except the addBff() 503 messages, which keep "The embedded BFF" against ruling 4 of the grill.

[nbouliol]

Approved after /verify-fixes run 1979-20261007084553-nbouliol-verify: 4 findings of 1979-20261007073258-nbouliol closed or accepted, none reopened.