From cc88b3b8e5bb9f7d9f23ed6ae85a52fd7b5b9ed6 Mon Sep 17 00:00:00 2001 From: Can Celik Date: Wed, 2 Sep 2026 02:45:20 +0300 Subject: feat: add stable client endpoint compatibility (#3509) * feat: add stable client endpoint compatibility * fix: keep portable-pty patch checks composable * ci: run maintenance checks in pull requests * fix: reject endpoint errors from terminal clients * feat: keep compatible servers running across updates --- AGENTS.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index 685d7078..116436fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,6 +80,19 @@ Examples: - Sidebar layout, token placement, colors, selection, modals, mouse/viewport state: TUI/client. - Workspace/tab/pane remain shared session organization for now, but avoid making them mandatory identity for unrelated runtime features. +### Stable client endpoint contract + +The client-owned TUI endpoint generation is independent from the private same-install protocol. Generation 1 is the compatibility floor for Local, SSH, and Cloud connections and must remain available unless retired for a security reason. + +- Named core codecs are immutable. Do not add, remove, reorder, or reinterpret fields or enum variants reachable from a published codec. Introduce a new codec name and keep the old codec as a fallback instead. +- Keep baseline JSON handshake and snapshot fields required. New JSON fields must be optional or have field-specific defaults; new enum values need an `Unknown` fallback where older clients can safely ignore them. +- Add server features through advertised API methods and optional snapshot data when possible. A missing optional feature must disable only that action, not reject the connection. +- Do not change the meaning or load-bearing parameter shape of an advertised endpoint method. If an old server could ignore a new field and incorrectly report success, add a new method name or a separately advertised capability and omit that field without it. +- Missing methods, rejections, timeouts, and unavailable servers are client-local outcomes. They must not disconnect other compatible servers, and typing in a pane must not dismiss their notices. +- Frozen endpoint fixtures, bincode digests, wire-tag tests, and `tests/fixtures/endpoint-method-shapes-v1.json` are compatibility contracts. Never update a generation-1 expectation merely to bless a wire change; create and negotiate a new codec or method. +- Stable and preview update manifests advertise `endpoint_generation`. Keep release tooling aligned so an older updater knows when a new server generation really requires replacement. +- Existing-value digests cannot detect an appended enum variant. Review every enum reachable from a frozen codec as append-closed even when tests remain green. + ## Maintainer Workflow This section applies only to verified maintainers as defined under Scope and -- cgit v1.2.3