Compatibility
An extension must be compatible across its package release, manifest format, extension API, Terminay release, Node runtime, and platform. Declare all but the package version in its manifest.
Declare your ranges
"terminay": {
"manifestVersion": 1,
"api": "^3.0.0",
"engines": {
"terminay": ">=1.0.0",
"node": ">=24"
},
"platforms": ["darwin", "linux"]
}| Axis | Rule |
|---|---|
| npm package version | Your release identity. Terminay installs an exact resolved version and integrity, never an implicit latest update. |
manifestVersion | Use 1. Unknown fields and unsupported formats fail validation. |
api | The Extension API range. A major is breaking; minors add capabilities. |
engines.terminay and engines.node | The Terminay and Node versions your compiled package requires. Node is the server's bundled runtime. |
platforms | Optional allowlist of darwin, linux, and win32. Omit it to allow every platform. |
extensionDependencies | Optional. A required dependency that is not installed, or whose API version does not satisfy apiRange, makes the extension incompatible. |
Range syntax
Terminay does not evaluate full npm SemVer ranges. api, engines,
and apiRange accept only these forms:
| Form | Matches |
|---|---|
^3.0.0 | The same major version, at or above the given version. |
>=1.0.0 | The given version or anything later. |
3.1.0 | Exactly that version. |
* | Any version. |
Any other form, such as ~3.0, 3.x, or a combined range, fails as an unsupported range.
API versions
The host implements Extension API 3.1.0.
| Version | Change |
|---|---|
| 2.0 | Removed project-environment providers. |
| 2.1 | Added language servers. |
| 3.0 | Replaced terminal-scoped agent providers, the observation broker, the lifecycle publisher, and the driver toolkit with machine-wide agent session sources. Added MCP install targets. |
| 3.1 | Added worktree insight sources. |
An extension declaring ^1 or ^2 is incompatible with a 3.x host and
must be ported. Declare ^3.0.0 unless you use worktree insights, which need
^3.1.0.
How activation is decided
- Terminay validates the manifest and checks that the entrypoint is exported.
- It checks the host's API version, the Terminay version, the Node version, the platform, and extension dependencies against the declared ranges.
- It imports and probes the package in a fresh extension host.
- Only a successful activation and registration becomes active.
Terminay never guesses or coerces an incompatible range. An incompatible extension stays visible as incompatible and its code is not executed.
Release safely
- Test the packed artifact, not only your working directory, against the intended Terminay release.
- Make a new package version when you change the compiled code, manifest, or permissions.
- Keep the API range as narrow as your implementation requires; do not claim a future major.
- Declare extension dependencies separately from ordinary npm library dependencies.
Updates install alongside the current slot and need fresh confirmation if permissions expand. Terminay retains a known-good slot; an update or activation failure leaves the prior active version in place.