Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(dash): declare versions on the connects clients already make (CHOO-1865)

Louis Amaudruzb9146a8233ee
diff --git a/dash/apps/switchdash-desktop/src/main/core/agent-runtime/impl/remote-sidecar-launcher.ts b/dash/apps/switchdash-desktop/src/main/core/agent-runtime/impl/remote-sidecar-launcher.ts
index a9303b796..b98cc329b 100644
--- a/dash/apps/switchdash-desktop/src/main/core/agent-runtime/impl/remote-sidecar-launcher.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/agent-runtime/impl/remote-sidecar-launcher.ts
@@ -1,5 +1,6 @@
import { createHash, randomUUID } from 'node:crypto';
import { readFile } from 'node:fs/promises';
+import type { ContractRange } from '@switchdash/shared';
import { exactTmuxTarget } from '@main/core/pty/tmux-session-name';
import { quoteShellArg } from '@main/utils/shellEscape';
import type { AgentLaunchSpec } from '../../../../sidecar/agent-launch-spec';
@@ -84,9 +85,14 @@ interface ReadyLine {
/** Monotonic per-start counter from the sidecar's durable state. Absent from
* a pre-CHOO-1425 sidecar. */
epoch: number | null;
- /** Human-readable `x.y` version; the major governs compatibility. Absent from
- * a sidecar predating versioning, which is treated as major 0. */
+ /** Release version, `MAJOR.MINOR.PATCH`. Says which release is running and
+ * nothing about compatibility — that is `contract`. Absent from a sidecar
+ * predating versioning, which is treated as major 0. */
version: string | null;
+ /** What the running sidecar says it speaks on `sidecar-control` (CHOO-1865).
+ * Null for a sidecar deployed before it declared anything, which means
+ * *unknown* — never agreement. Recorded, not yet acted on. */
+ contract: ContractRange | null;
/** OS process id of the running sidecar, for display. Absent from an older one. */
pid: number | null;
}
@@ -102,8 +108,11 @@ export interface SidecarRunStatus {
compatible: boolean;
/** Build fingerprint the running sidecar reports for itself. */
hash: string | null;
- /** Human-readable `x.y` version the running sidecar reports. */
+ /** Release version the running sidecar reports, `MAJOR.MINOR.PATCH`. */
version: string | null;
+ /** The `sidecar-control` range it declared, or null for unknown (CHOO-1865).
+ * Null must render as unknown, never as compatible. */
+ contract: ContractRange | null;
epoch: number | null;
pid: number | null;
/** Sessions the running sidecar currently owns, from its durable state. */
@@ -158,11 +167,37 @@ function parseReady(raw: string): ReadyLine | null {
const version =
'version' in parsed && typeof parsed.version === 'string' ? parsed.version : null;
const pid = 'pid' in parsed && typeof parsed.pid === 'number' ? parsed.pid : null;
- return { port: parsed.port, token: parsed.token, hash, epoch, version, pid };
+ return {
+ port: parsed.port,
+ token: parsed.token,
+ hash,
+ epoch,
+ version,
+ contract: parseContract(parsed),
+ pid,
+ };
}
return null;
}
+/**
+ * The `sidecar-control` range a sidecar declared, or null for unknown.
+ *
+ * A partial or malformed declaration reads as unknown rather than as the half
+ * that parsed: half a range is not a range, and guessing the other half would
+ * invent a number nobody declared.
+ */
+function parseContract(parsed: object): ContractRange | null {
+ if (!('contract' in parsed)) return null;
+ const contract = parsed.contract;
+ if (typeof contract !== 'object' || contract === null) return null;
+ if (!('speaks' in contract) || !('accepts' in contract)) return null;
+ const { speaks, accepts } = contract as { speaks: unknown; accepts: unknown };
+ if (typeof speaks !== 'number' || typeof accepts !== 'number') return null;
+ if (!Number.isInteger(speaks) || !Number.isInteger(accepts)) return null;
+ return { speaks, accepts };
+}
+
const defaultSleep = (ms: number): Promise<void> =>
new Promise((resolve) => setTimeout(resolve, ms));
@@ -523,6 +558,7 @@ export class RemoteSidecarLauncher {
compatible: false,
hash: null,
version: null,
+ contract: null,
epoch: null,
pid: null,
liveSessions: 0,
@@ -533,6 +569,7 @@ export class RemoteSidecarLauncher {
compatible: this.isCompatible(ready),
hash: ready.hash,
version: ready.version,
+ contract: ready.contract,
epoch: ready.epoch,
pid: ready.pid,
liveSessions: await this.runningSessionCount(),
diff --git a/dash/apps/switchdash-desktop/src/main/core/sidecar/verdict.test.ts b/dash/apps/switchdash-desktop/src/main/core/sidecar/verdict.test.ts
index 02218a65b..413ab706a 100644
--- a/dash/apps/switchdash-desktop/src/main/core/sidecar/verdict.test.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/sidecar/verdict.test.ts
@@ -3,13 +3,14 @@ import type { SidecarRunStatus } from '@main/core/agent-runtime/impl/remote-side
import { verdictFor } from './verdict';
const CLIENT = 'client-hash';
-const CLIENT_VERSION = '1.7';
+const CLIENT_VERSION = '1.7.0';
const status = (over: Partial<SidecarRunStatus>): SidecarRunStatus => ({
running: true,
compatible: true,
hash: CLIENT,
version: CLIENT_VERSION,
+ contract: { speaks: 1, accepts: 1 },
epoch: 1,
pid: 100,
liveSessions: 0,
diff --git a/dash/apps/switchdash-desktop/src/sidecar/index.ts b/dash/apps/switchdash-desktop/src/sidecar/index.ts
index 78e4560a8..664093348 100644
--- a/dash/apps/switchdash-desktop/src/sidecar/index.ts
+++ b/dash/apps/switchdash-desktop/src/sidecar/index.ts
@@ -27,7 +27,7 @@ import {
} from './sidecar-paths';
import { defaultRoomConnectionFactory, SidecarRuntime } from './sidecar-runtime';
import { SidecarStateStore } from './sidecar-state';
-import { SIDECAR_VERSION } from './sidecar-version';
+import { SIDECAR_CONTROL, SIDECAR_VERSION } from './sidecar-version';
import { exactTmuxTarget, parseAgentTmuxSessionName } from './vm-tmux';
/**
@@ -380,6 +380,11 @@ async function main(): Promise<void> {
token: server.getToken(),
hash: bundleHash,
version: SIDECAR_VERSION,
+ // What this sidecar speaks, declared in the file the client already reads
+ // (CHOO-1865). The version above says only which release this is;
+ // compatibility is this. A sidecar deployed before it existed omits the
+ // field, and the client must read that as unknown rather than as agreement.
+ contract: { speaks: SIDECAR_CONTROL.speaks, accepts: SIDECAR_CONTROL.accepts },
epoch: store.epoch,
pid: process.pid,
})}\n`;
diff --git a/dash/apps/switchdash-desktop/src/sidecar/sidecar-version.test.ts b/dash/apps/switchdash-desktop/src/sidecar/sidecar-version.test.ts
index 40a7a13b4..90fc45eb5 100644
--- a/dash/apps/switchdash-desktop/src/sidecar/sidecar-version.test.ts
+++ b/dash/apps/switchdash-desktop/src/sidecar/sidecar-version.test.ts
@@ -25,6 +25,28 @@ describe('compareSidecarVersions', () => {
expect(same('1.7', '1.7')).toBe(true);
});
+ it('orders by patch within a minor', () => {
+ expect(older('1.7.0', '1.7.1')).toBe(true);
+ expect(newer('1.7.10', '1.7.9')).toBe(true);
+ });
+
+ it('reads a two-part version as patch 0, so 1.7 and 1.7.0 are the same', () => {
+ // The property the three-part migration rests on (CHOO-1865). Sidecars
+ // deployed before it report `1.7`, and switchdash installs in the field
+ // parse only two parts. Both sides must read the pair as equal, or each
+ // sees the other as an upgrade and they replace one another forever
+ // (CHOO-1937).
+ expect(same('1.7', '1.7.0')).toBe(true);
+ expect(same('1.7.0', '1.7')).toBe(true);
+ });
+
+ it('keeps this release on major 1, so installs in the field still accept it', () => {
+ // Every switchdash already out there judges compatibility on the major.
+ // Going to 2.0.0 would make all of them treat this sidecar as incompatible
+ // and replace it on sight.
+ expect(sidecarMajor(SIDECAR_VERSION)).toBe(1);
+ });
+
it('treats a missing or unparseable version as the oldest', () => {
// A sidecar predating the version field reports none, and must never look
// newer than the client — that would make it un-upgradeable forever.
diff --git a/dash/apps/switchdash-desktop/src/sidecar/sidecar-version.ts b/dash/apps/switchdash-desktop/src/sidecar/sidecar-version.ts
index 374791413..516ac4ab2 100644
--- a/dash/apps/switchdash-desktop/src/sidecar/sidecar-version.ts
+++ b/dash/apps/switchdash-desktop/src/sidecar/sidecar-version.ts
@@ -1,33 +1,47 @@
+import { contractRange } from '@switchdash/shared';
+
/**
- * The sidecar's human-readable version, `x.y`.
+ * The sidecar's release version, `MAJOR.MINOR.PATCH`.
*
- * - `x` (major) — the wire contract between client and sidecar. Bump it on a
- * BREAKING change (the ready line, an endpoint's request/response, or the
- * on-disk layout the two sides share). Compatibility — "can this client talk
- * to that running sidecar" — is judged on the major alone.
- * - `y` (minor) — a release/patch counter, purely for humans to read. It drives
- * NO machine decision. Whether a running sidecar is the exact build this
- * client ships — and therefore whether an upgrade is available — is decided by
- * the content hash carried alongside, not by `y`.
+ * It says **where** this sidecar is — which release you are running — and
+ * nothing about what it can talk to. Compatibility lives in the
+ * `sidecar-control` contract (see `contracts.yaml`), which the sidecar declares
+ * in its ready file (CHOO-1865). The two move independently: a release that
+ * changes nothing on the wire bumps this and leaves the contract alone.
*
- * Keeping "is it the same build" on the hash rather than on `y` is deliberate: a
- * forgotten `y` bump then can never make a changed build look up-to-date, and
- * dev builds (which nobody bumps between iterations) still redeploy correctly.
- * The full identity a user sees is `x.y+<shorthash>` — semver build metadata —
- * so they read `1.0` while the machine compares the hash.
+ * Whether a running sidecar is the exact build this client ships — and so
+ * whether an upgrade exists — is decided by the content hash carried alongside,
+ * never by this number. That is deliberate: a forgotten bump then cannot make a
+ * changed build look up-to-date, and dev builds (which nobody bumps between
+ * iterations) still redeploy correctly. The full identity a user sees is
+ * `MAJOR.MINOR.PATCH+<shorthash>` — semver build metadata.
*
- * Bump policy: `x` on a wire break (and only then), `y` on every release that
- * changes the sidecar.
+ * **The major must stay at 1 through this transition.** switchdash installs
+ * already in the field judge compatibility on the major and parse only `x.y`,
+ * so `1.7` → `1.7.0` reads as the same version to them and nothing is replaced.
+ * Going to `2.0.0` would make every existing install see this sidecar as
+ * incompatible and replace it, while a newer install replaces it back —
+ * CHOO-1937, forever.
*
- * A *new* endpoint is not a wire break. Raising `x` past what a running sidecar
- * reports only helps if `MIN_SUPPORTED_SIDECAR_MAJOR` moves with it, and that
- * kills every older sidecar on sight — including one an older switchdash on the
- * same host will then kill right back, each replacing the other forever. So the
- * client owns this instead: call the endpoint, and when an older sidecar 404s
- * it, fail the operation with a message naming the upgrade rather than
- * continuing without whatever the endpoint was for.
+ * A *new* endpoint is not a wire break. Raising the contract past what a running
+ * sidecar reports only helps if the floor moves with it, and that kills every
+ * older sidecar on sight. So the client owns this instead: call the endpoint,
+ * and when an older sidecar 404s it, fail the operation with a message naming
+ * the upgrade rather than continuing without whatever the endpoint was for.
*/
-export const SIDECAR_VERSION = '1.7';
+export const SIDECAR_VERSION = '1.7.0';
+
+/** The artifact name the sidecar declares itself as. */
+export const SIDECAR_ARTIFACT = 'sidecar';
+
+/** The artifact name switchdash declares itself as, on the same contract. */
+export const SIDECAR_CLIENT_ARTIFACT = 'switchdash';
+
+/** What a sidecar of this build speaks. Written into its ready file. */
+export const SIDECAR_CONTROL = contractRange('sidecar-control', SIDECAR_ARTIFACT);
+
+/** What this switchdash speaks to a sidecar. */
+export const SIDECAR_CLIENT_CONTROL = contractRange('sidecar-control', SIDECAR_CLIENT_ARTIFACT);
/**
* Oldest major this client can still speak to. Raise it only when support for an
@@ -44,23 +58,33 @@ export function sidecarMajor(version: string | null): number {
return Number.isFinite(major) ? major : 0;
}
-/** An `x.y` version as numbers; a missing or unparseable part reads as 0. */
-function parseSidecarVersion(version: string | null): { major: number; minor: number } {
- if (!version) return { major: 0, minor: 0 };
- const [rawMajor, rawMinor] = version.split('.');
- const major = Number.parseInt(rawMajor ?? '', 10);
- const minor = Number.parseInt(rawMinor ?? '', 10);
- return {
- major: Number.isFinite(major) ? major : 0,
- minor: Number.isFinite(minor) ? minor : 0,
+/**
+ * A version as numbers; a missing or unparseable part reads as 0.
+ *
+ * Two-part versions still parse, and must keep doing so: sidecars deployed
+ * before three-part semver report `x.y` and are still running on hosts. Their
+ * patch reads as 0, which makes `1.7` and `1.7.0` compare equal — exactly what
+ * stops the two from replacing each other.
+ */
+function parseSidecarVersion(version: string | null): {
+ major: number;
+ minor: number;
+ patch: number;
+} {
+ if (!version) return { major: 0, minor: 0, patch: 0 };
+ const [rawMajor, rawMinor, rawPatch] = version.split('.');
+ const part = (raw: string | undefined): number => {
+ const value = Number.parseInt(raw ?? '', 10);
+ return Number.isFinite(value) ? value : 0;
};
+ return { major: part(rawMajor), minor: part(rawMinor), patch: part(rawPatch) };
}
/**
- * Order two `x.y` versions: negative when `a` is older, 0 when equal, positive
- * when `a` is newer.
+ * Order two versions: negative when `a` is older, 0 when equal, positive when
+ * `a` is newer.
*
- * This is the ONE machine decision the minor takes part in, and it is a
+ * This is the ONE machine decision the release number takes part in, and it is a
* tie-breaker rather than a build check. "Is this the same build" stays on the
* content hash, for the reasons above; this only answers "is the sidecar already
* on the host newer than what I ship", so a client never replaces a sidecar
@@ -71,7 +95,7 @@ function parseSidecarVersion(version: string | null): { major: number; minor: nu
export function compareSidecarVersions(a: string | null, b: string | null): number {
const left = parseSidecarVersion(a);
const right = parseSidecarVersion(b);
- return left.major - right.major || left.minor - right.minor;
+ return left.major - right.major || left.minor - right.minor || left.patch - right.patch;
}
/** This client's own major, for compatibility comparisons. */
diff --git a/dash/packages/switch-agent-runtime/src/event-stream.ts b/dash/packages/switch-agent-runtime/src/event-stream.ts
index 55c65fe9d..a9e457e97 100644
--- a/dash/packages/switch-agent-runtime/src/event-stream.ts
+++ b/dash/packages/switch-agent-runtime/src/event-stream.ts
@@ -1,5 +1,10 @@
+import { contractRange } from './contracts';
import { readSse, type SseFrame } from './sse';
import type { AgentBridgeEvent, SwitchCredentials } from './types';
+import { RUNTIME_ARTIFACT, RUNTIME_VERSION } from './version';
+
+/** This artifact's own range for the contract it speaks to Switch over. */
+const AGENT_PROTOCOL = contractRange('agent-protocol', RUNTIME_ARTIFACT);
/**
* The agent bridge's push transport (CHOO-1857), client side.
@@ -183,6 +188,14 @@ export class SwitchEventStream {
scope,
filter,
start_from: this.cursor > 0 ? String(this.cursor) : 'head',
+ // What we are and what we speak, declared on the connect we already
+ // make (CHOO-1865). A client that says nothing records as unknown
+ // server-side, and a declaration cannot be backfilled after the fact
+ // — every release that ships silent is a permanent blind spot.
+ protocol: String(AGENT_PROTOCOL.speaks),
+ protocol_accepts: String(AGENT_PROTOCOL.accepts),
+ client: RUNTIME_ARTIFACT,
+ client_version: RUNTIME_VERSION,
});
if (this.deps.spawnCapable) params.set('spawn_capable', 'true');
if (this.rooms.length) params.set('rooms', this.rooms.join(','));
@@ -235,6 +248,10 @@ export class SwitchEventStream {
log.debug('SwitchEventStream: connection established', {
event: 'switch_stream_connected',
rooms: frame.data.rooms,
+ // What the server says it is (CHOO-1865). Recorded, not acted on —
+ // logging it is what makes "which versions are actually talking to
+ // each other" answerable from a bug report rather than a guess.
+ server: frame.data.server ?? null,
});
this.reportRooms(frame.data.rooms);
return;
diff --git a/dash/packages/switch-agent-runtime/src/version.test.ts b/dash/packages/switch-agent-runtime/src/version.test.ts
new file mode 100644
index 000000000..10b8ff836
--- /dev/null
+++ b/dash/packages/switch-agent-runtime/src/version.test.ts
@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { CONTRACTS } from './contracts';
+import { RUNTIME_ARTIFACT, RUNTIME_VERSION } from './version';
+
+const manifest = JSON.parse(
+ readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')
+) as { version: string };
+
+describe('the runtime declares its own version', () => {
+ it('matches package.json', () => {
+ // The number is written twice because package.json cannot be imported
+ // without inlining the manifest into the bundle. This is what makes that
+ // safe: a release bump that misses one side fails here rather than
+ // shipping a runtime that lies about which release it is.
+ expect(RUNTIME_VERSION).toBe(manifest.version);
+ });
+
+ it('is three-part semver', () => {
+ // Every Switch artifact carries MAJOR.MINOR.PATCH.
+ expect(RUNTIME_VERSION).toMatch(/^\d+\.\d+\.\d+$/);
+ });
+
+ it('names an artifact the contract registry knows', () => {
+ // Declaring a name the server has no range for would report as unknown
+ // forever, and look like a client that simply never spoke up.
+ expect(CONTRACTS['agent-protocol']).toHaveProperty(RUNTIME_ARTIFACT);
+ });
+});
diff --git a/dash/packages/switch-agent-runtime/src/version.ts b/dash/packages/switch-agent-runtime/src/version.ts
new file mode 100644
index 000000000..5165aa97e
--- /dev/null
+++ b/dash/packages/switch-agent-runtime/src/version.ts
@@ -0,0 +1,17 @@
+/**
+ * This artifact's own release version (CHOO-1865).
+ *
+ * A semver says *where* an artifact is — which release you are running. It says
+ * nothing about whether it can talk to anything; that is what the contract
+ * revisions in `./contracts` are for. The two move independently and must never
+ * be derived from one another.
+ *
+ * package.json cannot be imported here without inlining the whole manifest into
+ * the bundle, so the number is written twice. `version.test.ts` fails if the two
+ * disagree, which is the part that makes the duplication safe — a comment
+ * reading "keep in sync" is what let COMPATIBLE_SWITCH_VERSION drift.
+ */
+export const RUNTIME_VERSION = '0.1.5';
+
+/** The artifact name this package declares itself as to Switch. */
+export const RUNTIME_ARTIFACT = 'agent-runtime';