Compatibility

You will upgrade the host more often than you upgrade your client. This page says what keeps working when you do, one surface at a time, and — where a guarantee does not exist yet — says that plainly instead of leaving you to infer one.

The wire protocol

The wire evolves by addition. A newer host may add methods, notifications, error kinds, and optional fields. A client written against an earlier version of the protocol keeps working against it.

Three rules follow from that, and they are the ones worth building into your client:

• A schema fingerprint you do not recognise is a warning, never an error. The handshake result carries schema.fingerprint, and the SDK compares it to the one it was built against and sets fingerprintWarning when they differ. Surface it if you like; do not refuse to run on it. Treating a mismatch as fatal turns every routine host upgrade into an outage for your users.
• Treat every enumerated value as an open set. turn/completed carries a terminal that is "completed", "cancelled" or "failed" today, and the disposition on a turn/start ack is "started", "queued" or "steered" today. A future host may send a value neither this page nor your code knows. Handle the ones you act on and treat anything else as its category’s default — an unknown terminal is still terminal.
• An unknown member is not an error. Read the fields you need by name and ignore the rest, rather than validating that a frame contains exactly what you expected.

Changes that addition alone does not cover are the exception, and each one is listed on the protocol changelog. That page is generated from the record such a change has to be entered in before it can reach the schema, so it cannot fall behind the protocol.

While the protocol is before its 1.0 release, no removal window is owed: a surface can change without first shipping a deprecation notice. From 1.0 onward, removal follows a notice in an earlier release, and the changelog lists each completed one.

The SDK

The SDK pins the fingerprint it was generated against and compares it at handshake, which is where fingerprintWarning comes from. It does not refuse a host it does not recognise, and neither should you.

An older SDK against a newer host is the supported direction, and it is the direction that follows from additive evolution: fields the SDK does not know about are carried through untyped rather than rejected. The reverse — a newer SDK against an older host — is not a supported configuration. The SDK may call a method that host does not implement, and you will see the error for an unknown method rather than a graceful degradation.

Sessions already on disk

This is the surface with the least guarantee, and the honest answer matters more than a reassuring one.

The compatibility window for persisted sessions across host upgrades is not yet a stated contract. Which sessions written by an older host a newer host must still open and serve history for is an open question with a decision pending, not a settled answer being withheld. Do not read a guarantee into the fact that it usually works, and do not plan an upgrade on the assumption that history survives it.

What is contractual is how the host tells you, and that is what your client has to handle:

• session/resume returns a history whose mode must be read before items. For a short session it is { mode: "inline", items: [...] }. For a long or compacted one you get a snapshot with items: null.
• mode: "none" is a state your client must be able to render. It means the host is not serving history for this session. It is not an error and not an empty conversation, and today it does not distinguish between the reasons it can occur.
• The session itself still resumes. session/resume returning no history does not mean the session is unusable — resumed.session, resumed.viewCursor and resumed.pendingRequests are still yours to work with.

Build for that: show the user a session whose earlier turns cannot be displayed, rather than treating it as corrupt or hiding it. A client that assumes history is always available will show an empty conversation where there was a real one.

If you are planning a migration across host versions and need a stated window rather than current behaviour, ask for one. It is a known, tracked gap; this page will say what the window is once there is a window to state, and until then it will keep saying that there is not.

Where to go next

• Protocol changelog — the non-additive changes, and the deprecations, in full.
• Resume — the cursor and history contract in detail, including what each history.mode means for your UI.
• MSP concepts — sessions, turns, approvals and exit classification as one model.