Versioning

Each SDK package follows Semantic Versioning independently. The wire protocol carries no version of its own — it evolves additively, and each session identifies the SDK that opened it; how that works is covered in Protocol compatibility. This page covers the packages.

SDK package versions

Each package's current release lives on its registry, which is always right by construction:

• cosmo-ai on npm (TypeScript)
• cosmo-ai-sdk on PyPI (Python)
• CosmoAI releases on GitHub (Swift)

These docs deliberately name no version numbers: the install commands resolve the latest release, and the changelog records what each release changed.

MAJOR — incremented on breaking changes to the public API surface (renamed exports, removed methods, changed required parameters). Requires a migration step.

MINOR — new capabilities added in a backward-compatible way (new methods, new optional fields, new events).

PATCH — backward-compatible bug fixes, documentation updates, internal refactors that don't change behavior.

An SDK version bump doesn't imply a wire change — an SDK may ship new hooks, helpers, or performance improvements that never touch the protocol. When the wire protocol does gain a capability, the three SDKs adopt it in coordinated releases.

Backward compatibility guarantees

For minor and patch releases:

• Existing optional fields remain optional.
• New fields added to request bodies are optional with backward-compatible defaults.
• New server message types are silently ignored by SDKs that don't handle them.
• ErrorCode is a closed union in every SDK, so a value added to the wire is one an older SDK does not name. Match it with a default branch rather than assuming the set is complete.
• New event names on RealtimeEventMap are ignored by handlers that don't subscribe to them.

Upgrade path

When a new major version ships:

1. The breaking changes are listed in the changelog entry for that release, and its migration guide gives the code change for each.
2. The old major remains supported for a deprecation window (announced in the changelog).
3. A wire change that requires client-side migration ships only in a new major — the server keeps accepting what the old major sends for its deprecation window.

Runtime package version

Every SDK can report the version it runs as — the same value it sends as its SDK identity at session start. All three expose it at module scope — SDK_NAME and SDK_VERSION in TypeScript and Python, sdkName and sdkVersion in Swift:

from cosmo_ai import SDK_NAME, SDK_VERSION
print(f"{SDK_NAME} {SDK_VERSION}")