Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

fix(spaces-desktop): send first-run, sign-in and Space events on Windows and Linux (CUA-1739) (#5277)

Francesco Bonaccie6a244a8dea2
diff --git a/apps/cua-spaces-desktop/src/bridge/onboarding.ts b/apps/cua-spaces-desktop/src/bridge/onboarding.ts
index 1a907e5655..3237179f89 100644
--- a/apps/cua-spaces-desktop/src/bridge/onboarding.ts
+++ b/apps/cua-spaces-desktop/src/bridge/onboarding.ts
@@ -19,6 +19,8 @@ export function onboardingMethods(ctx: BridgeContext): Handlers {
const mode = args.mode;
if (mode !== "client" && mode !== "host") throw Failure.badArgs("mode: client | host");
parts().onboarding.finish(mode);
+ // Done is past Welcome and its usage notice.
+ ctx.model.telemetry?.acknowledgeNotice();
// Every machine, host or not: its own macOS Spaces live on the local
// network (vmnet), so ask while someone is here.
ctx.model.host.requestLocalNetwork();
diff --git a/apps/cua-spaces-desktop/src/bridge/settings.ts b/apps/cua-spaces-desktop/src/bridge/settings.ts
index f78b4175af..51d54d2df3 100644
--- a/apps/cua-spaces-desktop/src/bridge/settings.ts
+++ b/apps/cua-spaces-desktop/src/bridge/settings.ts
@@ -174,6 +174,9 @@ export function settingsMethods(ctx: BridgeContext): Handlers {
return;
case "telemetry":
model.telemetry?.setEnabled(option === "on");
+ // The switch sits beside the usage note (Welcome, Settings): the
+ // notice was seen.
+ model.telemetry?.acknowledgeNotice();
model.changed("settings");
return;
default:
diff --git a/apps/cua-spaces-desktop/src/bridge/telemetry.ts b/apps/cua-spaces-desktop/src/bridge/telemetry.ts
index ce9b054261..abd23bb700 100644
--- a/apps/cua-spaces-desktop/src/bridge/telemetry.ts
+++ b/apps/cua-spaces-desktop/src/bridge/telemetry.ts
@@ -90,14 +90,29 @@ export function telemetrySignal(native: Native, raw: unknown): AppTelemetrySigna
}
}
+/** The page's first run moved past Welcome (its usage notice was on
+ * screen): any page left or shown other than Welcome being shown, or
+ * "Set up later". */
+export function leftWelcome(raw: unknown): boolean {
+ if (!raw || typeof raw !== "object") return false;
+ const s = raw as Record<string, unknown>;
+ if (s.type === "onboarding-page") return !(s.page === "welcome" && s.action === "shown");
+ return s.type === "step" && s.step === "onboarding_skipped";
+}
+
export function telemetryMethods({ model }: BridgeContext): Handlers {
return {
"telemetry.track": (args) => {
if (!Array.isArray(args.signals)) throw Failure.badArgs("signals: array");
const telemetry = model.telemetry;
if (!telemetry || !telemetry.status().enabled) return null;
- const signals = args.signals.map((raw) => telemetrySignal(model.native, raw)).filter((s): s is AppTelemetrySignal => s !== null);
- if (signals.length) telemetry.record(signals);
+ const kept = args.signals.flatMap((raw) => {
+ const signal = telemetrySignal(model.native, raw);
+ return signal ? [{ raw, signal }] : [];
+ });
+ // Held until the notice was shown; leaving Welcome sends them in order.
+ if (kept.length) telemetry.record(kept.map((k) => k.signal));
+ if (kept.some((k) => leftWelcome(k.raw))) telemetry.acknowledgeNotice();
return null;
},
};
diff --git a/apps/cua-spaces-desktop/src/main.ts b/apps/cua-spaces-desktop/src/main.ts
index 617ee48a5a..12dbe438cf 100644
--- a/apps/cua-spaces-desktop/src/main.ts
+++ b/apps/cua-spaces-desktop/src/main.ts
@@ -145,6 +145,13 @@ async function startNativeHost(showRoute: (route: string) => void, globalShortcu
app.on("will-quit", () => {
pip.closeAll();
viewers.closeAll();
+ // Closing the last window quits on Windows and Linux: send the usage
+ // events still queued (at most 1 s; the rest go with the next launch).
+ try {
+ native.telemetryFlush(1000);
+ } catch {
+ // Usage data never holds up quitting.
+ }
});
const prompts = await electronKeyvaultPrompts(native);
// macOS: a real window dragged onto a Space tile in the main window (the
diff --git a/apps/cua-spaces-desktop/src/model/environment.ts b/apps/cua-spaces-desktop/src/model/environment.ts
index 65635c161f..b311cf0b06 100644
--- a/apps/cua-spaces-desktop/src/model/environment.ts
+++ b/apps/cua-spaces-desktop/src/model/environment.ts
@@ -100,6 +100,9 @@ export function makeModel(o: EnvironmentOptions): Environment {
const backend = new PendingSpacesBackend(gate);
const account = new PendingAccount(gate);
const telemetry = new LiveTelemetry(native);
+ // A first run that finished here had the notice on its Welcome page;
+ // earlier builds never recorded that, so their machines sent nothing.
+ if (!firstRunDue) telemetry.acknowledgeNotice();
const host = new HostModel(native, null);
const devices = new DevicesModel(native, () => gate.current?.devices ?? null);
const cloud = new CloudModel(native, () => backend.current);
diff --git a/apps/cua-spaces-desktop/src/model/services.ts b/apps/cua-spaces-desktop/src/model/services.ts
index 8f9a86ee25..aa973e168e 100644
--- a/apps/cua-spaces-desktop/src/model/services.ts
+++ b/apps/cua-spaces-desktop/src/model/services.ts
@@ -110,11 +110,27 @@ export interface TelemetryRunning {
setEnabled(on: boolean): AppTelemetryInput;
/** Records signals the app core derived (`appTelemetry*`). */
record(signals: AppTelemetrySignal[]): void;
+ /** The first-run notice was on screen and the person moved on (left
+ * Welcome, finished the first run, or used the switch beside the note):
+ * from here usage events may be sent (the SwiftUI app's
+ * `appTelemetryWelcomeLeft`). */
+ acknowledgeNotice(): void;
}
+/** Signals held while the first-run notice is still on screen. */
+const MAX_HELD = 200;
+
/** The SDK's telemetry setting (`$CUA_HOME/config.toml`, the same switch as
- * `cua telemetry off`); the environment wins and locks it. */
+ * `cua telemetry off`); the environment wins and locks it.
+ *
+ * The SDK sends nothing from a machine before the app showed its first-run
+ * notice (`acknowledgeNotice`). Until then signals wait here, in order, so
+ * the first session's run start, sign-in and first Space still count once
+ * Welcome is left; turning usage data off drops them. */
export class LiveTelemetry implements TelemetryRunning {
+ private held: AppTelemetrySignal[] = [];
+ private noticeShown = false;
+
constructor(private readonly native: Native) {}
static input(s: TelemetryStatus): AppTelemetryInput {
@@ -127,10 +143,39 @@ export class LiveTelemetry implements TelemetryRunning {
}
setEnabled(on: boolean): AppTelemetryInput {
+ if (!on) this.held = [];
return LiveTelemetry.input(this.native.telemetrySetEnabled(on));
}
record(signals: AppTelemetrySignal[]): void {
- if (signals.length) this.native.appTelemetryRecord(signals);
+ if (!signals.length) return;
+ if (this.shown()) {
+ this.native.appTelemetryRecord(signals);
+ return;
+ }
+ this.held.push(...signals);
+ if (this.held.length > MAX_HELD) this.held.splice(0, this.held.length - MAX_HELD);
+ }
+
+ acknowledgeNotice(): void {
+ const s = this.native.telemetryStatus();
+ if (!s.noticeShown) {
+ try {
+ // Keeps the switch as it is, writes the notice marker, then records
+ // the `app_launched` that waited for it.
+ this.native.appTelemetryWelcomeLeft(s.enabled);
+ } catch (error) {
+ console.warn(`[cua-spaces] usage notice not recorded: ${error instanceof Error ? error.message : String(error)}`);
+ return;
+ }
+ }
+ this.noticeShown = true;
+ const held = this.held.splice(0);
+ if (held.length && s.enabled) this.native.appTelemetryRecord(held);
+ }
+
+ private shown(): boolean {
+ if (!this.noticeShown) this.noticeShown = this.native.telemetryStatus().noticeShown;
+ return this.noticeShown;
}
}
diff --git a/apps/cua-spaces-desktop/test/bridge-native.test.ts b/apps/cua-spaces-desktop/test/bridge-native.test.ts
index 902d53392d..ac018b1289 100644
--- a/apps/cua-spaces-desktop/test/bridge-native.test.ts
+++ b/apps/cua-spaces-desktop/test/bridge-native.test.ts
@@ -347,6 +347,18 @@ describe.skipIf(!built)("the bridge on the app core", () => {
expect(telemetrySignal(native, { type: "launched", onboardingEligible: null })).not.toBeNull();
});
+ it("records that the usage notice was seen once the first run leaves Welcome", async () => {
+ telemetry.current = { enabled: true, lockedBy: undefined, noticeShown: false };
+ const before = telemetry.acknowledged;
+ await call("telemetry.track", { signals: [{ type: "step", step: "onboarding_shown", ok: true }, { type: "onboarding-page", page: "welcome", action: "shown", choice: "none" }] });
+ expect(telemetry.acknowledged).toBe(before);
+ await call("telemetry.track", { signals: [{ type: "onboarding-page", page: "welcome", action: "completed", choice: "none" }, { type: "onboarding-page", page: "signin", action: "shown", choice: "none" }] });
+ expect(telemetry.acknowledged).toBe(before + 1);
+ // "Set up later" from Welcome counts too.
+ await call("telemetry.track", { signals: [{ type: "step", step: "onboarding_skipped", ok: true }] });
+ expect(telemetry.acknowledged).toBe(before + 2);
+ });
+
it("sets the calling window's background, and checks the drag regions", async () => {
await call("window.setBackgroundColor", { color: "16181C", appearance: "dark" });
expect(backgrounds).toEqual([["win-1", "#16181c", "dark"]]);
diff --git a/apps/cua-spaces-desktop/test/fixtures.ts b/apps/cua-spaces-desktop/test/fixtures.ts
index 0161271580..750665419e 100644
--- a/apps/cua-spaces-desktop/test/fixtures.ts
+++ b/apps/cua-spaces-desktop/test/fixtures.ts
@@ -386,4 +386,9 @@ export class FixtureTelemetry implements TelemetryRunning {
record(signals: AppTelemetrySignal[]) {
if (this.current.enabled) this.recorded.push(...signals);
}
+ acknowledged = 0;
+ acknowledgeNotice() {
+ this.acknowledged += 1;
+ this.current = { ...this.current, noticeShown: true };
+ }
}
diff --git a/apps/cua-spaces-desktop/test/host-bridge.test.ts b/apps/cua-spaces-desktop/test/host-bridge.test.ts
index f71189e948..4a7a50bfd0 100644
--- a/apps/cua-spaces-desktop/test/host-bridge.test.ts
+++ b/apps/cua-spaces-desktop/test/host-bridge.test.ts
@@ -762,6 +762,8 @@ describe.skipIf(!built)("This machine, Devices and Settings on the app core", ()
events.length = 0;
expect(await call("onboarding.complete", { mode: "host", launchAtLogin: true })).toEqual({ completed: true, mode: "host" });
expect(asked).toBe(1);
+ // Done is past Welcome's usage notice.
+ expect((model.telemetry as FixtureTelemetry).acknowledged).toBe(1);
expect(system.loginItem.calls).toEqual(["register"]);
expect(model.settings.launchAtLogin).toBe(true);
expect(events.some((e) => e.event === "session.changed")).toBe(true);
diff --git a/apps/cua-spaces-desktop/test/live-telemetry.test.ts b/apps/cua-spaces-desktop/test/live-telemetry.test.ts
new file mode 100644
index 0000000000..645011a3a7
--- /dev/null
+++ b/apps/cua-spaces-desktop/test/live-telemetry.test.ts
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+// The app's usage events on a first run: the SDK sends nothing before the
+// app records that its first-run notice was shown, so the app holds the
+// first session's signals until Welcome is left, then sends them in order
+// (CUA-1739: Windows and Linux sent no first run, sign-in or Space events).
+import { describe, expect, it } from "vitest";
+import { leftWelcome } from "../src/bridge/telemetry";
+import { LiveTelemetry } from "../src/model/services";
+import type { Native } from "../src/native/load";
+
+type Signal = { tag: string };
+
+function fakeNative(o: { noticeShown?: boolean; enabled?: boolean; failAck?: boolean } = {}) {
+ const state = { noticeShown: o.noticeShown ?? false, enabled: o.enabled ?? true };
+ const recorded: Signal[][] = [];
+ const welcomeLeft: boolean[] = [];
+ const status = () => ({ enabled: state.enabled, source: "default", sourceKind: "default", noticeShown: state.noticeShown, noticeText: "", docsUrl: "" });
+ const native = {
+ telemetryStatus: status,
+ telemetrySetEnabled: (on: boolean) => {
+ state.enabled = on;
+ return status();
+ },
+ appTelemetryRecord: (signals: Signal[]) => {
+ recorded.push(signals);
+ return signals.length;
+ },
+ appTelemetryWelcomeLeft: (on: boolean) => {
+ if (o.failAck) throw new Error("no home");
+ welcomeLeft.push(on);
+ state.noticeShown = true;
+ },
+ } as unknown as Native;
+ return { native, state, recorded, welcomeLeft };
+}
+
+const sig = (tag: string) => ({ tag }) as never;
+
+describe("LiveTelemetry before and after the first-run notice", () => {
+ it("holds the first session's signals until the notice was seen, then sends them in order", () => {
+ const f = fakeNative();
+ const t = new LiveTelemetry(f.native);
+ t.record([sig("Launched"), sig("OnboardingPage")]);
+ t.record([sig("Step")]);
+ expect(f.recorded).toEqual([]);
+ t.acknowledgeNotice();
+ expect(f.welcomeLeft).toEqual([true]);
+ expect(f.recorded).toEqual([[sig("Launched"), sig("OnboardingPage"), sig("Step")]]);
+ // Afterwards signals go straight through.
+ t.record([sig("SpaceCreateStarted")]);
+ expect(f.recorded.at(-1)).toEqual([sig("SpaceCreateStarted")]);
+ // Acknowledging again writes nothing and sends nothing twice.
+ t.acknowledgeNotice();
+ expect(f.welcomeLeft).toEqual([true]);
+ expect(f.recorded).toHaveLength(2);
+ });
+
+ it("sends at once on a machine that already showed the notice", () => {
+ const f = fakeNative({ noticeShown: true });
+ const t = new LiveTelemetry(f.native);
+ t.record([sig("Feature")]);
+ expect(f.recorded).toEqual([[sig("Feature")]]);
+ t.acknowledgeNotice();
+ expect(f.welcomeLeft).toEqual([]);
+ });
+
+ it("drops what it held when usage data is turned off on Welcome", () => {
+ const f = fakeNative();
+ const t = new LiveTelemetry(f.native);
+ t.record([sig("OnboardingPage")]);
+ t.setEnabled(false);
+ t.acknowledgeNotice();
+ // The notice is recorded with the switch as it is (off); nothing is sent.
+ expect(f.welcomeLeft).toEqual([false]);
+ expect(f.recorded).toEqual([]);
+ });
+
+ it("keeps holding when the notice could not be recorded", () => {
+ const f = fakeNative({ failAck: true });
+ const t = new LiveTelemetry(f.native);
+ t.record([sig("Step")]);
+ t.acknowledgeNotice();
+ expect(f.recorded).toEqual([]);
+ });
+
+ it("holds a bounded number of signals", () => {
+ const f = fakeNative();
+ const t = new LiveTelemetry(f.native);
+ for (let i = 0; i < 250; i++) t.record([sig(`S${i}`)]);
+ t.acknowledgeNotice();
+ expect(f.recorded[0]).toHaveLength(200);
+ expect(f.recorded[0]![0]).toEqual(sig("S50"));
+ });
+});
+
+describe("leaving Welcome", () => {
+ it("is any first-run page but Welcome being shown, or Set up later", () => {
+ expect(leftWelcome({ type: "onboarding-page", page: "welcome", action: "shown", choice: "none" })).toBe(false);
+ expect(leftWelcome({ type: "step", step: "onboarding_shown", ok: true })).toBe(false);
+ expect(leftWelcome({ type: "feature", feature: "space_open" })).toBe(false);
+ expect(leftWelcome({ type: "onboarding-page", page: "welcome", action: "completed", choice: "none" })).toBe(true);
+ expect(leftWelcome({ type: "onboarding-page", page: "signin", action: "shown", choice: "none" })).toBe(true);
+ expect(leftWelcome({ type: "step", step: "onboarding_skipped", ok: true })).toBe(true);
+ expect(leftWelcome(null)).toBe(false);
+ });
+});
diff --git a/apps/cua-spaces-web/src/bridge/README.md b/apps/cua-spaces-web/src/bridge/README.md
index 3f951b439d..8db40dc8a8 100644
--- a/apps/cua-spaces-web/src/bridge/README.md
+++ b/apps/cua-spaces-web/src/bridge/README.md
@@ -487,9 +487,10 @@ sends only while `settings.get`'s `telemetry` says on and the notice was
shown, read before every batch; with the first-run switch off the core
derives nothing. `sanitizeSignals` drops any signal that isn't a known type
with exactly its fields as fixed lowercase words, flags or durations, so
-names, emails, paths and URLs can't leave the page. Tauri and the SwiftUI
-app record `app_launched` themselves (`HOST_RECORDS_LAUNCH`); the page
-records it in Electron and demo.
+names, emails, paths and URLs can't leave the page. Tauri, the SwiftUI
+app and Electron record `app_launched` themselves (`HOST_RECORDS_LAUNCH`);
+the page records it only in demo. Electron holds the page's signals until
+the first run leaves Welcome (its usage notice), then sends them in order.
**Space detail.** `useSpaceDetail(space, hostArch)` gives the core's
`sidebar.detail` (facts, sections, Delete's question) and
diff --git a/apps/cua-spaces-web/src/bridge/telemetry.ts b/apps/cua-spaces-web/src/bridge/telemetry.ts
index 65d9ae5d26..4ca33c701a 100644
--- a/apps/cua-spaces-web/src/bridge/telemetry.ts
+++ b/apps/cua-spaces-web/src/bridge/telemetry.ts
@@ -77,9 +77,9 @@ export function telemetryEnroll(core: CoreClient, state: unknown, action: unknow
/* ---- Sending ---------------------------------------------------------------------- */
/** Hosts that record `app_launched` themselves when they start (Tauri's
- * `telemetry::init`, the SwiftUI app's `appTelemetryStart`); the page
- * records it only where nothing else does. */
-export const HOST_RECORDS_LAUNCH: Record<BridgeMode, boolean> = { tauri: true, webkit: true, electron: false, demo: false };
+ * `telemetry::init`, the SwiftUI and Electron apps' `appTelemetryStart`);
+ * the page records it only where nothing else does. */
+export const HOST_RECORDS_LAUNCH: Record<BridgeMode, boolean> = { tauri: true, webkit: true, electron: true, demo: false };
/** Usage data may be sent: the switch is on and the notice was shown. */
export function telemetryAllowed(view: TelemetryView | null | undefined): boolean {