📖 fix: Verify Agents OpenAPI contracts and disable external reporting

[dustinhealy]

Summary

Installing Swagger UI can report dependency analytics, and its browser UI enables an external validator by default. Disable both, document the application's non-JSON 500 responses accurately, and verify the generated contract and built documentation over HTTP.

Follows the merged #15928 and targets dev. This follow-up changes documentation and validation, not management API behavior. It also regenerates the contract to include the repositoryInstructions field already supported by current dev.

How it works

The response adapter preserves generated JSON schemas while allowing additional response media types. Both agent and skill contracts include the application's text-body fallback (text/html) alongside their existing JSON errors.

OpenAPI registry → generated specification → built package → HTTP docs smoke
Management HTTP requests → actual responses → generated response-schema validation

The root package opts out of Scarf reporting; backend CI and both Docker builds also disable it before dependency installation. Swagger continues using bundled assets and has its external validator disabled. Scarf remains a transitive dependency with reporting disabled.

Change Type

• Bug fix (non-breaking change which fixes an issue)
• This change requires a documentation update

Testing

Build the packages, then run the generated-spec and built-docs checks:

npm run build:data-provider
npm run build:data-schemas
npm run build:api
npm run -w @librechat/api openapi:check
npm run -w @librechat/api openapi:test
cd api
npx jest server/routes/agents/__tests__/openapi.contract.spec.js server/routes/agents/__tests__/management.spec.js server/routes/agents/__tests__/skills.spec.js --runInBand --coverage=false

All 20 tests passed. API TypeScript checking, generated-spec drift checking, built-docs smoke, and full-diff static checks (lint, formatting, import order, package validation, circular dependencies) also passed.

The HTTP contract suite uses local RSA/JWKS authentication, disposable MongoDB, and temporary local storage. It checks missing/wrong-audience credentials, a persisted multipart context upload, skill-file creation and overwrite with database/disk readback, malformed JSON, invalid and oversized UTF-8 content, and the existing non-JSON 500 responses—including the global JSON body-size failure. Selected response statuses, media types, and bodies are validated against the committed specification with JSON Schema 2020 and format validation.

The built-docs smoke covers absent/disabled/enabled configuration, /api and /chat/api paths, trailing slashes, bundled assets, and executed Swagger initializer URLs. A separate local Chromium check rendered all 14 operations at all four docs URLs with no browser errors or attempted third-party requests.

Scope: the contract harness composes production handlers and persistence but injects configuration and permissive authorization fixtures. It does not replace full application, ACL/ban/Redis, cloud-storage, or deployment acceptance tests. The other 12 operation success paths were source-audited, not executed by this focused suite. No Docker image or remote CI run is claimed.

Test Configuration:

Node 24.16.0; isolated local checkout based on merged dev commit 69f0dd2a121b629648a54dab2242d1b21ffc9eed. Built documentation tested over ephemeral loopback HTTP. Browser verification uses headless Chromium.

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• I have made pertinent documentation changes
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective or that my feature works
• Local unit tests pass with my changes

[dustinhealy]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-16T19:09:04.073588Z	32d9c81	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 32d9c81f2b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🟢 Approval recommended

The reviewed changes have no unresolved blocking issues.

Pull request overview

Updates Agents OpenAPI contracts and documentation validation while disabling Swagger and Scarf external reporting.

Changes:

• Documents text/html 500 responses and regenerates the contract.
• Adds HTTP contract, generated-spec, and built-docs smoke tests.
• Disables external analytics in packages, CI, and Docker builds.

File summaries

File	Description
packages/api/src/openapi/skills.ts	Applies the updated error response contract.
packages/api/src/openapi/router.ts	Disables external Swagger validation.
packages/api/src/openapi/errors.ts	Defines JSON and HTML server-error responses.
packages/api/src/openapi/agents.ts	Applies the updated agent error contract.
packages/api/src/openapi/adapter.ts	Supports additional response media types.
packages/api/package.json	Adds the OpenAPI smoke-test script.
packages/api/openapi/router.smoke.cjs	Adds built documentation smoke tests.
packages/api/openapi/agents.openapi.json	Regenerates the OpenAPI contract.
package.json	Disables Scarf reporting.
package-lock.json	Locks validation and test dependencies.
Dockerfile.multi	Disables Scarf during multi-stage builds.
Dockerfile	Disables Scarf during image builds.
api/server/routes/agents/__tests__/openapi.contract.spec.js	Adds HTTP contract validation coverage.
api/package.json	Adds contract-test dependencies.
.github/workflows/backend-review.yml	Adds CI analytics opt-out and documentation smoke testing.

Review details

• Files reviewed: 14/15 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[dustinhealy]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 32d9c81f2b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".