Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
test(host): fail when the wire shape older apps decode changes
leepokaie5e17a862f97
diff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.mdindex 33223e08..25bdd7d4 100644--- a/docs/reference/compatibility.md+++ b/docs/reference/compatibility.md@@ -53,13 +53,35 @@ that stays undecodable after the one rewind, or a `hello` whose other fields canThe iPhone part of this release must actually ship (it changes `kit/`, so `Submit iOS`includes it).2. After that iPhone version is **live on the App Store**, a later host release drops the- old form and sets `MIN_APP` to the version from step 1.+ old form, sets `MIN_APP` to the version from step 1, and re-records the wire shape+ snapshot (below).Raising `MIN_APP` before the App Store has that version locks every iPhone out with noupdate to install.- **Raise `minHost`** only when the client's core flows need something older hosts lack. Anoptional feature that needs a newer host hides its control instead.- Floors never exceed the release that ships them (unit tests in both crates check this).++### Wire shape snapshot++`wire_shape_matches_the_snapshot` (`host/tests/e2e.rs`) runs a full turn against a real host+(fake agent: user message, narration, tool call with a diff, plan, permission, final reply),+then records every field path and JSON type of `hello` and the event stream's catch-up (bot+and entry events, entries per kind) in `host/tests/fixtures/wire-shape.json`, together with+the host's `minApp`.++| Change | Test |+|---|---|+| Nothing on the wire | Passes |+| New field | Fails until recorded: `CODYNC_UPDATE_WIRE_SHAPE=1 cargo test --test e2e wire_shape`, no decision needed |+| Field removed, renamed or retyped | Fails, and recording is refused, until `MIN_APP` differs from the recorded one; then record |++So a breaking change can't land by accident: it either keeps the old field or raises the+floor, and the floor is raised only by the two-release rule above. `null` fields match any+type. Not covered: subtrees that depend on the machine rather than the code (`backends`,+`screen`, `urls`, `usage`), fields the sample turn doesn't produce (thread replies, group+chats, routines and other method responses), and what the host accepts in requests. Changes+there still follow the rule by review.- The encrypted channel's handshake version (`v` in its `hello`, rejected with`unsupportedVersion`, close code 4400) is separate: the host must keep accepting every `v`a supported client sends.diff --git a/host/tests/e2e.rs b/host/tests/e2e.rsindex 46a2f4d5..865e7f5e 100644--- a/host/tests/e2e.rs+++ b/host/tests/e2e.rs@@ -361,3 +361,173 @@ async fn personal_workspaces_are_unique_persistent_and_optional() {assert_eq!(group["bot"]["cwd"], "");assert_eq!(group["bot"]["managedWorkspace"], false);}++// ---------- wire shape snapshot (docs/reference/compatibility.md) ----------++/// Snapshot of what clients decode: field paths and JSON types of `hello` and the event+/// stream after a full turn. Values aren't kept, only the shape.+const WIRE_SHAPE: &str = "tests/fixtures/wire-shape.json";+/// Re-records the snapshot (refused while a field is removed or retyped without a new `minApp`).+const UPDATE_ENV: &str = "CODYNC_UPDATE_WIRE_SHAPE";+/// Depends on the machine (installed harnesses, displays, addresses, local usage), not the code.+const MACHINE_DEPENDENT: [&str; 4] = ["backends", "screen", "urls", "usage"];++fn json_type(v: &Value) -> &'static str {+ match v {+ Value::Null => "null",+ Value::Bool(_) => "bool",+ Value::Number(_) => "number",+ Value::String(_) => "string",+ Value::Array(_) => "array",+ Value::Object(_) => "object",+ }+}++/// Every field path under `v` with its type; array elements merge under `[]`.+fn shape(v: &Value, path: &str, out: &mut std::collections::BTreeMap<String, String>) {+ out.insert(path.to_owned(), json_type(v).to_owned());+ match v {+ Value::Object(map) => {+ for (k, child) in map {+ if !MACHINE_DEPENDENT.contains(&k.as_str()) {+ shape(child, &format!("{path}.{k}"), out);+ }+ }+ }+ Value::Array(items) => {+ for item in items {+ shape(item, &format!("{path}[]"), out);+ }+ }+ _ => {}+ }+}++/// The shape of a stream event, keyed by its type (and an entry's kind: their data differ).+fn event_shape(ev: &Value, out: &mut std::collections::BTreeMap<String, String>) {+ let ty = ev["type"].as_str().unwrap_or("?");+ let key = match ev["entry"]["kind"].as_str() {+ Some(kind) if ty == "entry" => format!("event:entry({kind})"),+ _ => format!("event:{ty}"),+ };+ shape(ev, &key, out);+}++/// What changed between the recorded and the current shape: (breaking, additions).+/// A field that was `null` on either side can't be judged by its type.+fn shape_diff(+ recorded: &std::collections::BTreeMap<String, String>,+ current: &std::collections::BTreeMap<String, String>,+) -> (Vec<String>, Vec<String>) {+ let mut breaking = vec![];+ for (path, ty) in recorded {+ match current.get(path) {+ None => breaking.push(format!("removed {path} ({ty})")),+ Some(now) if now != ty && now != "null" && ty != "null" => {+ breaking.push(format!("retyped {path}: {ty} → {now}"));+ }+ Some(_) => {}+ }+ }+ let added = current+ .iter()+ .filter(|(path, ty)| recorded.get(*path).is_none_or(|old| old == "null" && *ty != "null"))+ .map(|(path, ty)| format!("{path} ({ty})"))+ .collect();+ (breaking, added)+}++#[test]+fn shape_diff_tells_breaking_from_additive() {+ let map = |pairs: &[(&str, &str)]| pairs.iter().map(|(k, v)| ((*k).to_owned(), (*v).to_owned())).collect();+ let recorded = map(&[("a", "object"), ("a.x", "string"), ("a.y", "null"), ("a.z", "number")]);+ let current = map(&[("a", "object"), ("a.x", "number"), ("a.y", "string"), ("a.w", "bool")]);+ let (breaking, added) = shape_diff(&recorded, ¤t);+ assert_eq!(breaking, ["retyped a.x: string → number", "removed a.z (number)"]);+ assert_eq!(added, ["a.w (bool)", "a.y (string)"]);+}++/// Reads the event stream's catch-up until it goes quiet.+async fn catch_up(host: &Host) -> Vec<Value> {+ let res = reqwest::Client::new()+ .get(format!("{}/events?since=0&client=test", host.base))+ .bearer_auth(&host.token)+ .send()+ .await+ .unwrap();+ let mut body = res.bytes_stream();+ let (mut buf, mut events) = (String::new(), vec![]);+ while let Ok(Some(Ok(chunk))) = tokio::time::timeout(Duration::from_millis(1500), body.next()).await {+ buf.push_str(&String::from_utf8_lossy(&chunk));+ while let Some(i) = buf.find('\n') {+ let line: String = buf.drain(..=i).collect();+ if let Some(data) = line.trim_end().strip_prefix("data:")+ && let Ok(v) = serde_json::from_str::<Value>(data.trim_start())+ {+ events.push(v);+ }+ }+ }+ events+}++/// Older apps read what the host sends: a removed or retyped field breaks them. This fails+/// until the field is kept, or `MIN_APP` is raised the two-release way and the snapshot+/// re-recorded. New fields only need recording (`CODYNC_UPDATE_WIRE_SHAPE=1`).+#[tokio::test]+async fn wire_shape_matches_the_snapshot() {+ if Command::new("python3").arg("--version").output().is_err() {+ eprintln!("skipping: python3 not available");+ return;+ }+ let host = start_host().await;+ let agent = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fake_agent.py");+ let bot = host+ .call(+ "createBot",+ json!({+ "name": "Tester", "backend": "custom", "command": format!("python3 '{}'", agent.display()),+ "cwd": host.home.to_string_lossy(), "permission": "ask",+ }),+ )+ .await["bot"]["id"]+ .as_str()+ .unwrap()+ .to_owned();+ host.call("send", json!({"botId": bot, "text": "go", "clientNonce": "n1"})).await;+ let card = host.wait_for(&bot, |e| e["kind"] == "permission" && e["data"]["status"] == "pending").await;+ host.call("respondPermission", json!({"entryId": card["id"], "optionId": "allow"})).await;+ host.wait_for(&bot, |e| e["kind"] == "agent" && e["data"]["final"] == true).await;++ let hello = host.call("hello", json!({})).await;+ let min_app = hello["minApp"].as_str().unwrap().to_owned();+ let mut current = std::collections::BTreeMap::new();+ shape(&hello, "hello", &mut current);+ for ev in catch_up(&host).await {+ event_shape(&ev, &mut current);+ }+ assert!(current.keys().any(|k| k.starts_with("event:entry(tool)")), "the turn's entries are missing");++ let file = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join(WIRE_SHAPE);+ let recorded: Value = std::fs::read_to_string(&file).map_or(Value::Null, |s| serde_json::from_str(&s).unwrap());+ let recorded_shapes: std::collections::BTreeMap<String, String> =+ serde_json::from_value(recorded["shapes"].clone()).unwrap_or_default();+ let (breaking, added) = shape_diff(&recorded_shapes, ¤t);+ let floor_raised = recorded["minApp"].as_str() != Some(min_app.as_str());+ assert!(+ breaking.is_empty() || floor_raised,+ "Older apps would break: {breaking:#?}\nKeep these fields, or follow the two-release rule \+ in docs/reference/compatibility.md: raise MIN_APP (host/src/compat.rs) once that iPhone \+ version is live, then re-record with {UPDATE_ENV}=1 cargo test --test e2e wire_shape"+ );+ if std::env::var_os(UPDATE_ENV).is_some() {+ let json = json!({"minApp": min_app, "shapes": current});+ std::fs::write(&file, serde_json::to_string_pretty(&json).unwrap() + "\n").unwrap();+ return;+ }+ assert!(+ breaking.is_empty() && added.is_empty() && !floor_raised,+ "The wire shape changed.\nAdded: {added:#?}\nRemoved or retyped (minApp was raised): {breaking:#?}\n\+ Record it with {UPDATE_ENV}=1 cargo test --test e2e wire_shape"+ );+}diff --git a/host/tests/fixtures/wire-shape.json b/host/tests/fixtures/wire-shape.jsonnew file mode 100644index 00000000..8b23c687--- /dev/null+++ b/host/tests/fixtures/wire-shape.json@@ -0,0 +1,170 @@+{+ "minApp": "2.3.0",+ "shapes": {+ "event:bot": "object",+ "event:bot.bot": "object",+ "event:bot.bot.activity": "string",+ "event:bot.bot.autoName": "bool",+ "event:bot.bot.avatarColor": "string",+ "event:bot.bot.avatarShape": "string",+ "event:bot.bot.backend": "string",+ "event:bot.bot.command": "string",+ "event:bot.bot.computer": "bool",+ "event:bot.bot.connectors": "array",+ "event:bot.bot.createdAt": "number",+ "event:bot.bot.cwd": "string",+ "event:bot.bot.deleted": "bool",+ "event:bot.bot.description": "string",+ "event:bot.bot.hidden": "bool",+ "event:bot.bot.id": "string",+ "event:bot.bot.kind": "string",+ "event:bot.bot.lastAt": "number",+ "event:bot.bot.lastMessage": "string",+ "event:bot.bot.managedWorkspace": "bool",+ "event:bot.bot.members": "array",+ "event:bot.bot.model": "null",+ "event:bot.bot.name": "string",+ "event:bot.bot.notify": "null",+ "event:bot.bot.permission": "string",+ "event:bot.bot.pinned": "bool",+ "event:bot.bot.rev": "number",+ "event:bot.bot.skills": "array",+ "event:bot.bot.startedAt": "null",+ "event:bot.bot.status": "string",+ "event:bot.bot.unread": "number",+ "event:bot.bot.workingChat": "null",+ "event:bot.bot.workingThread": "null",+ "event:bot.rev": "number",+ "event:bot.type": "string",+ "event:entry(agent)": "object",+ "event:entry(agent).entry": "object",+ "event:entry(agent).entry.botId": "string",+ "event:entry(agent).entry.createdAt": "number",+ "event:entry(agent).entry.data": "object",+ "event:entry(agent).entry.data.author": "string",+ "event:entry(agent).entry.data.final": "bool",+ "event:entry(agent).entry.data.text": "string",+ "event:entry(agent).entry.id": "string",+ "event:entry(agent).entry.kind": "string",+ "event:entry(agent).entry.rev": "number",+ "event:entry(agent).entry.seq": "number",+ "event:entry(agent).entry.threadId": "null",+ "event:entry(agent).entry.turn": "number",+ "event:entry(agent).entry.updatedAt": "number",+ "event:entry(agent).rev": "number",+ "event:entry(agent).type": "string",+ "event:entry(permission)": "object",+ "event:entry(permission).entry": "object",+ "event:entry(permission).entry.botId": "string",+ "event:entry(permission).entry.createdAt": "number",+ "event:entry(permission).entry.data": "object",+ "event:entry(permission).entry.data.author": "string",+ "event:entry(permission).entry.data.command": "string",+ "event:entry(permission).entry.data.cwd": "string",+ "event:entry(permission).entry.data.detail": "string",+ "event:entry(permission).entry.data.diffs": "array",+ "event:entry(permission).entry.data.options": "array",+ "event:entry(permission).entry.data.options[]": "object",+ "event:entry(permission).entry.data.options[].kind": "string",+ "event:entry(permission).entry.data.options[].name": "string",+ "event:entry(permission).entry.data.options[].optionId": "string",+ "event:entry(permission).entry.data.selected": "string",+ "event:entry(permission).entry.data.status": "string",+ "event:entry(permission).entry.data.title": "string",+ "event:entry(permission).entry.data.toolKind": "string",+ "event:entry(permission).entry.id": "string",+ "event:entry(permission).entry.kind": "string",+ "event:entry(permission).entry.rev": "number",+ "event:entry(permission).entry.seq": "number",+ "event:entry(permission).entry.threadId": "null",+ "event:entry(permission).entry.turn": "number",+ "event:entry(permission).entry.updatedAt": "number",+ "event:entry(permission).rev": "number",+ "event:entry(permission).type": "string",+ "event:entry(plan)": "object",+ "event:entry(plan).entry": "object",+ "event:entry(plan).entry.botId": "string",+ "event:entry(plan).entry.createdAt": "number",+ "event:entry(plan).entry.data": "object",+ "event:entry(plan).entry.data.author": "string",+ "event:entry(plan).entry.data.entries": "array",+ "event:entry(plan).entry.data.entries[]": "object",+ "event:entry(plan).entry.data.entries[].content": "string",+ "event:entry(plan).entry.data.entries[].priority": "string",+ "event:entry(plan).entry.data.entries[].status": "string",+ "event:entry(plan).entry.id": "string",+ "event:entry(plan).entry.kind": "string",+ "event:entry(plan).entry.rev": "number",+ "event:entry(plan).entry.seq": "number",+ "event:entry(plan).entry.threadId": "null",+ "event:entry(plan).entry.turn": "number",+ "event:entry(plan).entry.updatedAt": "number",+ "event:entry(plan).rev": "number",+ "event:entry(plan).type": "string",+ "event:entry(tool)": "object",+ "event:entry(tool).entry": "object",+ "event:entry(tool).entry.botId": "string",+ "event:entry(tool).entry.createdAt": "number",+ "event:entry(tool).entry.data": "object",+ "event:entry(tool).entry.data.author": "string",+ "event:entry(tool).entry.data.diffs": "array",+ "event:entry(tool).entry.data.diffs[]": "object",+ "event:entry(tool).entry.data.diffs[].added": "number",+ "event:entry(tool).entry.data.diffs[].isNew": "bool",+ "event:entry(tool).entry.data.diffs[].patch": "string",+ "event:entry(tool).entry.data.diffs[].path": "string",+ "event:entry(tool).entry.data.diffs[].removed": "number",+ "event:entry(tool).entry.data.diffs[].startLine": "number",+ "event:entry(tool).entry.data.locations": "null",+ "event:entry(tool).entry.data.output": "string",+ "event:entry(tool).entry.data.status": "string",+ "event:entry(tool).entry.data.title": "string",+ "event:entry(tool).entry.data.toolCallId": "string",+ "event:entry(tool).entry.data.toolKind": "string",+ "event:entry(tool).entry.id": "string",+ "event:entry(tool).entry.kind": "string",+ "event:entry(tool).entry.rev": "number",+ "event:entry(tool).entry.seq": "number",+ "event:entry(tool).entry.threadId": "null",+ "event:entry(tool).entry.turn": "number",+ "event:entry(tool).entry.updatedAt": "number",+ "event:entry(tool).rev": "number",+ "event:entry(tool).type": "string",+ "event:entry(user)": "object",+ "event:entry(user).entry": "object",+ "event:entry(user).entry.botId": "string",+ "event:entry(user).entry.createdAt": "number",+ "event:entry(user).entry.data": "object",+ "event:entry(user).entry.data.attachments": "array",+ "event:entry(user).entry.data.clientNonce": "string",+ "event:entry(user).entry.data.status": "string",+ "event:entry(user).entry.data.text": "string",+ "event:entry(user).entry.id": "string",+ "event:entry(user).entry.kind": "string",+ "event:entry(user).entry.rev": "number",+ "event:entry(user).entry.seq": "number",+ "event:entry(user).entry.threadId": "null",+ "event:entry(user).entry.turn": "number",+ "event:entry(user).entry.updatedAt": "number",+ "event:entry(user).rev": "number",+ "event:entry(user).type": "string",+ "event:hello": "object",+ "event:hello.computerId": "string",+ "event:hello.hostId": "string",+ "event:hello.rev": "number",+ "event:hello.type": "string",+ "hello": "object",+ "hello.boxKey": "string",+ "hello.cloud": "null",+ "hello.computerId": "string",+ "hello.device": "string",+ "hello.home": "string",+ "hello.hostId": "string",+ "hello.minApp": "string",+ "hello.name": "string",+ "hello.os": "string",+ "hello.rev": "number",+ "hello.signKey": "string",+ "hello.version": "string"+ }+}