Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
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.tsindex 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.tsindex 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-sideimport { 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.tsindex 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.tsindex 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.tsindex 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: nuexport 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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';