v4.0.0

supercorp-ai/supergatewayv4.0.0Sep 20, 2026by Nedomas

Upgrading?

AI Summary

This release marks the first stable version of the 4.0 line, upgrading the `latest` tag from 3.4.3. It introduces improved session management, better protocol compatibility, and enhanced error handling across Node.js 20 and newer.

Key Highlights

  • Stateful sessions now expire after 30 minutes of idleness to prevent stranded server processes, though indefinite sessions can be configured using `--sessionTimeout`.
  • The gateway now returns `404` instead of `400` for invalid session IDs, allowing clients to seamlessly start a new session when an old one expires.
  • Support for newer Model Context Protocol (MCP) versions is added while maintaining full compatibility with older servers.
  • Notifications and replies are now delivered directly to the server rather than the client, improving state synchronization.

Breaking Changes

  • Node.js 20 or newer is required to run the gateway.
  • Stateful sessions now expire after 30 minutes of idleness; previously they never expired without configuration.

New Features

  • Improved SSE reconnection, HTTP session handling, and subprocess cleanup.
  • Preservation of Unicode text split across subprocess output chunks.
  • Enhanced error handling with credentials redacted from diagnostic logs.
  • Fixes for the Deno container to ensure the requested Supergateway version is installed.
  • Exclusion of tests and development files from npm packages for cleaner distributions.

Full Release Notes

The first stable release of the 4.0 line. `latest` moves from 3.4.3 to 4.0.0.

## Breaking changes

* **Node.js 20 or newer is required.**
* **Stateful sessions now expire after 30 minutes of idleness.** Previously an unconfigured `--stateful` session never expired, so a client that disconnected without ending its session stranded the server process it was using. If you relied on sessions living indefinitely, pass a large `--sessionTimeout`.

## What's Changed

* Support newer MCP protocols while preserving compatibility with older servers
* Deliver a client's notifications and replies to the server instead of returning them to the client
* Deliver a stateful server's progress notifications on the call they belong to, so the first one is no longer lost when a client has not yet opened its event stream
* Answer `404` rather than `400` when a request carries a session id the gateway no longer holds, so a client whose session has expired or been ended starts a new one instead of failing every later call (#123)
* Keep interactive operations isolated when servers return identical continuation state, and preserve signed multi-round operations and explicit continuation retries after completion
* Improve SSE reconnection, HTTP session handling, and subprocess cleanup
* Preserve Unicode text split across subprocess output chunks
* Improve error handling and redact credentials from diagnostic logs
* Report the correct version with `--version`
* Fix the Deno container and install the requested Supergateway version in images
* Exclude tests and development files from npm packages

## Validation

This release ships the artifact that cleared a full six-hour soak across Node 20, 22, 24 and 26 on Linux, macOS and Windows — 36 of 36 hosted jobs, alongside a clean six-hour local campaign. Per-file coverage is held at 100% for lines, statements, functions, branches and MC/DC.

Thanks to:
- [@0xbrainkid](https://github.com/0xbrainkid)
- [@0xt3ch](https://github.com/0xt3ch)
- [@Avi-Robusta](https://github.com/Avi-Robusta)
- [@AxelFooley](https://github.com/AxelFooley)
- [@BishopMartin](https://github.com/BishopMartin)
- [@EvanSchalton](https://github.com/EvanSchalton)
- [@Farzy](https://github.com/Farzy)
- [@GhimBoon](https://github.com/GhimBoon)
- [@Growdy](https://github.com/Growdy)
- [@HalmSascha](https://github.com/HalmSascha)
- [@JamesSlocumIH](https://github.com/JamesSlocumIH)
- [@JoeLuker](https://github.com/JoeLuker)
- [@JuliaF1988](https://github.com/JuliaF1988)
- [@MartinZvelebil](https://github.com/MartinZvelebil)
- [@NathanNeves](https://github.com/NathanNeves)
- [@O7Furkan17](https://github.com/O7Furkan17)
- [@Paul-Kyle](https://github.com/Paul-Kyle)
- [@RussellZager](https://github.com/RussellZager)
- [@agerit-programator2](https://github.com/agerit-programator2)
- [@akirilyuk](https://github.com/akirilyuk)
- [@body-cmd](https://github.com/body-cmd)
- [@brainoir](https://github.com/brainoir)
- [@brendandebeasi](https://github.com/brendandebeasi)
- [@ckhsponge](https://github.com/ckhsponge)
- [@cosmic-fire-eng](https://github.com/cosmic-fire-eng)
- [@dangdinhquan](https://github.com/dangdinhquan)
- [@davidjitca](https://github.com/davidjitca)
- [@dparkmit24](https://github.com/dparkmit24)
- [@dustindoan](https://github.com/dustindoan)
- [@ecdesigns2007](https://github.com/ecdesigns2007)
- [@edmcman](https://github.com/edmcman)
- [@enxilium](https://github.com/enxilium)
- [@frankstupak](https://github.com/frankstupak)
- [@gkinter](https://github.com/gkinter)
- [@glani](https://github.com/glani)
- [@haissamtariqzaman](https://github.com/haissamtariqzaman)
- [@iandol](https://github.com/iandol)
- [@ildunari](https://github.com/ildunari)
- [@janosborst](https://github.com/janosborst)
- [@jmcgurk2](https://github.com/jmcgurk2)
- [@jstar0](https://github.com/jstar0)
- [@julioccorderoc](https://github.com/julioccorderoc)
- [@logan-crosby](https://github.com/logan-crosby)
- [@manmao](https://github.com/manmao)
- [@maxx3250](https://github.com/maxx3250)
- [@micci184](https://github.com/micci184)
- [@mike12806](https://github.com/mike12806)
- [@move-hoon](https://github.com/move-hoon)
- [@noyoa](https://github.com/noyoa)
- [@ongeluk](https://github.com/ongeluk)
- [@oscar-izval](https://github.com/oscar-izval)
- [@quigles1977](https://github.com/quigles1977)
- [@rubenmajor2](https://github.com/rubenmajor2)
- [@sbatista-uc](https://github.com/sbatista-uc)
- [@scalabreseGD](https://github.com/scalabreseGD)
- [@sfasching](https://github.com/sfasching)
- [@sibelius](https://github.com/sibelius)
- [@springbrookconsultingllc-byte](https://github.com/springbrookconsultingllc-byte)
- [@sulivanti](https://github.com/sulivanti)
- [@suneetagarwalre-boop](https://github.com/suneetagarwalre-boop)
- [@swarthyplacebo](https://github.com/swarthyplacebo)
- [@tamermina](https://github.com/tamermina)
- [@terafin](https://github.com/terafin)
- [@terjefl](https://github.com/terjefl)
- [@v8eta](https://github.com/v8eta)
- [@waldman](https://github.com/waldman)
- [@werebear73](https://github.com/werebear73)
- [@yakovyarmo](https://github.com/yakovyarmo)
- [@yangzinan](https://github.com/yangzinan)
- [@zaggash](https://github.com/zaggash)

**Full Changelog**: https://github.com/supercorp-ai/supergateway/compare/v3.4.3...v4.0.0

Related Repositories