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.

Spaces onboarding: ask once to let coding apps use Cua (CUA-2315) (#5986)

cua-agents[bot]99ede183981e
diff --git a/.github/scripts/spaces_release_notes.sh b/.github/scripts/spaces_release_notes.sh
index 561c8b05ec..30bee7d50a 100755
--- a/.github/scripts/spaces_release_notes.sh
+++ b/.github/scripts/spaces_release_notes.sh
@@ -1,6 +1,4 @@
#!/usr/bin/env bash
-# SPDX-License-Identifier: FSL-1.1-MIT
-# Copyright (c) 2026 Cua AI, Inc.
# Prints the real notes for a Cua Spaces version on stdout.
#
# spaces_release_notes.sh <version> (GH_TOKEN and GITHUB_REPOSITORY set)
diff --git a/apps/cua-spaces-web/src/__tests__/first-run.test.tsx b/apps/cua-spaces-web/src/__tests__/first-run.test.tsx
index 80bb2104a1..1ee73a60f1 100644
--- a/apps/cua-spaces-web/src/__tests__/first-run.test.tsx
+++ b/apps/cua-spaces-web/src/__tests__/first-run.test.tsx
@@ -19,6 +19,7 @@ import type { NewSpaceOptions } from "@/bridge/contracts/new-space";
import { readFirstRun, resetFirstRunCache, useFirstRun, writeFirstRun } from "@/bridge/first-run";
import { CLOSED_NEW_SPACE, updateNewSpaceSession } from "@/bridge/new-space";
import { resetSavedOnboardingCache } from "@/bridge/onboarding";
+import { connectedAppsState, resetConnectedAppsState } from "@/hooks/use-connected-apps";
import { mountApp, stubBrowserApis } from "./app-harness";
stubBrowserApis();
@@ -27,19 +28,20 @@ beforeEach(() => {
resetSavedOnboardingCache();
resetFirstRunCache();
updateNewSpaceSession(() => CLOSED_NEW_SPACE);
+ resetConnectedAppsState();
});
afterEach(cleanup);
type Calls = { op: string; args: unknown }[];
-async function mount(opts: { signedIn?: boolean; host?: (h: HostStatus) => HostStatus; local?: (l: NonNullable<NewSpaceOptions["local"]>) => NewSpaceOptions["local"]; agents?: (rows: AgentSetupRow[]) => AgentSetupRow[]; cli?: "missing" | "local" } = {}) {
+async function mount(opts: { signedIn?: boolean; host?: (h: HostStatus) => HostStatus; local?: (l: NonNullable<NewSpaceOptions["local"]>) => NewSpaceOptions["local"]; agents?: (rows: AgentSetupRow[]) => AgentSetupRow[]; cli?: "missing" | "local"; demo?: object } = {}) {
await testCore();
const calls: Calls = [];
await mountApp("/onboarding", {
failsCreates: false,
listsGhost: false,
// A first run: signed out, and Cua in no agent's settings yet.
- demo: { signedIn: opts.signedIn ?? false, onboarded: false, cli: opts.cli },
+ demo: { signedIn: opts.signedIn ?? false, onboarded: false, cli: opts.cli, ...opts.demo },
intercept: (op, args) => {
calls.push({ op, args });
return undefined;
@@ -97,26 +99,81 @@ describe("first-run detection on window focus", () => {
});
});
+/** The one question Pick your agent asks (or its answer once every app is ready). */
+const ASK = /^Let .+ use Cua\?$|^.+ can use Cua\.$/;
+const onlyCodex = (rows: AgentSetupRow[]) => rows.map((r) => ({ ...r, installed: r.agent === "codex" }));
const agents = () => [...document.querySelectorAll<HTMLElement>("[data-first-run-agent]")].map((e) => e.dataset.firstRunAgent);
const click = (sel: string) => fireEvent.click(document.querySelector<HTMLElement>(sel)!);
/** No agent on this computer. */
const noAgents = (rows: AgentSetupRow[]) => rows.map((r) => ({ ...r, installed: false, configured: false }));
describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
- it("walks Welcome, Pick your agent, Connect your devices and Try it, connecting only what is clicked", async () => {
+ it("asks once, naming the apps found, and connects nothing until Set up", async () => {
const calls = await mount();
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
click("[data-onboarding-primary]");
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
- // The agents found here, most preferred first; nothing connected by itself.
+ await waitFor(() => expect(heading()).toBe("Let your 5 coding apps use Cua?"));
+ // The apps found here, most preferred first; nothing connected by itself, no per-app buttons or file paths.
await waitFor(() => expect(agents()).toEqual(["hermes", "claude-code", "codex", "cursor", "openclaw"]));
expect([...document.querySelectorAll<HTMLElement>("[data-first-run-agent]")].every((e) => e.dataset.connected === "false")).toBe(true);
+ expect(document.querySelector("[data-first-run-connect]")).toBeNull();
+ expect(document.body.textContent).not.toMatch(/\.hermes|config\.yaml|MCP/);
expect(calls.some((c) => c.op === "agents.configure")).toBe(false);
- // Each row names the file Connect changes.
- expect(document.querySelector('[data-first-run-agent="hermes"]')!.textContent).toMatch(/~\/\.hermes\/config\.yaml/);
- click('[data-first-run-connect="codex"]');
+ // The consent says it covers apps installed later, and how to undo.
+ expect(document.querySelector("[data-first-run-consent]")!.textContent).toMatch(/Apps you install later are set up the same way, with a notice and Undo\./);
+ expect(connectedAppsState().auto).toBeNull();
+ click("[data-first-run-set-up]");
+ await waitFor(() => expect(calls.filter((c) => c.op === "agents.configure").map((c) => (c.args as { agents: string[] }).agents)).toHaveLength(5));
+ await waitFor(() => expect(heading()).toBe("Your 5 coding apps can use Cua."));
+ expect(document.querySelector("[data-first-run-prompt]")!.textContent).toBe("Reproduce the crash from issue #4821 on a fresh Windows 11 Space and show me a recording.");
+ expect(document.body.textContent).toMatch(/restart it first/);
+ expect(connectedAppsState().auto).toBe(true);
+ expect(connectedAppsState().known).toEqual(expect.arrayContaining(["hermes", "claude-code", "codex", "cursor", "openclaw"]));
+ expect(readFirstRun().picked).toEqual(expect.arrayContaining(["codex", "claude-code"]));
+ });
+
+ it("Not now moves on and sets up nothing, and Cua never sets up later installs on its own", async () => {
+ const calls = await mount();
+ await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
+ click("[data-onboarding-primary]");
+ await waitFor(() => expect(heading()).toMatch(ASK));
+ click("[data-first-run-secondary]");
+ await waitFor(() => expect(heading()).toBe("Add your other computers."));
+ expect(calls.some((c) => c.op === "agents.configure")).toBe(false);
+ expect(connectedAppsState().auto).toBe(false);
+ });
+
+ it("says plainly which app needs a hand, with Try again and the text to paste", { timeout: 30_000 }, async () => {
+ await mount({ demo: { agentsReadOnly: ["cursor"] }, agents: (rows) => rows.map((r) => ({ ...r, installed: ["codex", "cursor"].includes(r.agent) })) });
+ await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
+ click("[data-onboarding-primary]");
+ await waitFor(() => expect(heading()).toBe("Let OpenAI Codex and Cursor use Cua?"));
+ click("[data-first-run-set-up]");
+ await waitFor(() => expect(heading()).toBe("OpenAI Codex can use Cua. Cursor needs a hand."), { timeout: 8000 });
+ const row = document.querySelector<HTMLElement>('[data-first-run-agent="cursor"]')!;
+ await waitFor(() => expect(row.textContent).toContain("Couldn't set up Cursor. Cua can't change this file because it is read-only or belongs to another user."), { timeout: 8000 });
+ expect(document.body.textContent).not.toMatch(/os error/);
+ expect(row.querySelector("[data-first-run-retry]")).toBeTruthy();
+ expect(document.querySelector('[data-first-run-agent="codex"]')!.textContent).toContain("Ready");
+ fireEvent.click(screen.getByRole("button", { name: "Add it by hand" }));
+ const hand = await waitFor(() => {
+ const el = document.querySelector("[data-first-run-by-hand]");
+ expect(el, document.body.textContent ?? "").not.toBeNull();
+ return el!;
+ });
+ expect(hand.textContent).toContain("mcpServers");
+ // Continue is still there: Cursor can wait.
+ expect(document.querySelector("[data-onboarding-primary]")!.textContent).toBe("Continue");
+ });
+
+ it("walks Welcome, the question, Connect your devices and Try it, connecting only what is asked", async () => {
+ const calls = await mount({ agents: onlyCodex });
+ await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
+ click("[data-onboarding-primary]");
+ await waitFor(() => expect(heading()).toBe("Let OpenAI Codex use Cua?"));
+ click("[data-first-run-set-up]");
await waitFor(() => expect(calls.find((c) => c.op === "agents.configure")?.args).toEqual({ agents: ["codex"] }));
- await waitFor(() => expect(document.querySelector<HTMLElement>('[data-first-run-agent="codex"]')!.dataset.connected).toBe("true"));
+ await waitFor(() => expect(heading()).toBe("OpenAI Codex can use Cua."));
expect(readFirstRun().picked).toEqual(["codex"]);
expect(calls.filter((c) => c.op === "agents.configure")).toHaveLength(1);
click("[data-onboarding-primary]");
@@ -149,8 +206,8 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
.map((s) => `${s.page} ${s.action}${s.choice === "none" ? "" : ` ${s.choice}`}`);
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
click("[data-onboarding-primary]");
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
- click("[data-onboarding-primary]");
+ await waitFor(() => expect(heading()).toMatch(ASK));
+ click("[data-first-run-secondary]");
await waitFor(() => expect(heading()).toBe("Add your other computers."));
click("[data-first-run-secondary]");
await waitFor(() => expect(document.querySelector("[data-step]")?.getAttribute("data-step")).toBe("setup"));
@@ -161,7 +218,7 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
"welcome step_viewed",
"welcome step_completed",
"connect_agent step_viewed",
- "connect_agent step_completed",
+ "connect_agent step_skipped step",
"sign_in step_viewed",
"sign_in step_skipped step",
"create_space step_viewed",
@@ -185,19 +242,20 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
});
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
click("[data-onboarding-primary]");
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
+ await waitFor(() => expect(heading()).toMatch(ASK));
await new Promise((r) => setTimeout(r, 50));
expect(calls.some((c) => c.op === "telemetry.track")).toBe(false);
});
it("Back works from every step after Welcome, all the way to Welcome, keeping what was picked", async () => {
- const calls = await mount();
+ const calls = await mount({ agents: onlyCodex });
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
expect(document.querySelector("[data-first-run-back]")).toBeNull();
click("[data-onboarding-primary]");
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
- click('[data-first-run-connect="codex"]');
+ await waitFor(() => expect(heading()).toMatch(ASK));
+ click("[data-first-run-set-up]");
await waitFor(() => expect(readFirstRun().picked).toEqual(["codex"]));
+ await waitFor(() => expect(heading()).toBe("OpenAI Codex can use Cua."));
click("[data-onboarding-primary]");
await waitFor(() => expect(heading()).toBe("Add your other computers."));
click("[data-first-run-secondary]");
@@ -206,7 +264,7 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
click("[data-first-run-back]");
await waitFor(() => expect(heading()).toBe("Add your other computers."));
click("[data-first-run-back]");
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
+ await waitFor(() => expect(heading()).toMatch(ASK));
expect(document.querySelector<HTMLElement>('[data-first-run-agent="codex"]')!.dataset.connected).toBe("true");
click("[data-first-run-back]");
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
@@ -230,7 +288,7 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
expect(screen.getByRole("button", { name: "Not now" })).toBe(secondary);
expect(document.getElementById(secondary.getAttribute("aria-describedby")!)?.textContent).toBe("Not now keeps Cua on this Mac only. You can sign in later.");
fireEvent.keyDown(window, { key: "Escape" });
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
+ await waitFor(() => expect(heading()).toMatch(ASK));
fireEvent.keyDown(window, { key: "Escape" });
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
// Welcome has no Back, so Esc stays.
@@ -238,23 +296,12 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
expect(heading()).toBe("Your computers, shared by your team and its agents.");
});
- it("Codex: its ChatGPT sign-in and OpenAI key follow it, and the sign-in starts on this computer", async () => {
+ it("shows no sign-ins or keys: those live in Settings, Connected apps", async () => {
writeFirstRun({ step: "connect" });
- const calls = await mount({ agents: (rows) => rows.map((r) => ({ ...r, installed: r.agent === "codex" })) });
- await waitFor(() => expect(agents()).toEqual(["codex"]));
+ await mount({ agents: (rows) => rows.map((r) => ({ ...r, installed: r.agent === "codex", configured: r.agent === "codex" })) });
+ await waitFor(() => expect(heading()).toBe("OpenAI Codex can use Cua."));
expect(document.querySelector("[data-first-run-credentials]")).toBeNull();
- click('[data-first-run-connect="codex"]');
- const signIn = await waitFor(() => {
- const r = document.querySelector('[data-first-run-credential="sign-in:codex"]');
- expect(r).toBeTruthy();
- return r!;
- });
- expect(signIn.textContent).toMatch(/ChatGPT sign-in/);
- expect(signIn.textContent).toMatch(/uses it on this (Mac|PC|computer)/);
- expect(document.querySelector("[data-first-run-credentials-note]")!.textContent).toMatch(/^Sign-ins and keys stay on this (Mac|PC|computer)\.$/);
- expect(document.querySelector('[data-first-run-credential="key:anthropic"]')).toBeNull();
- fireEvent.click(signIn.querySelector('[data-first-run-credential-action="agent-sign-in"]')!);
- await waitFor(() => expect(calls.find((c) => c.op === "agents.signIn")?.args).toEqual({ agent: "codex" }));
+ expect(document.body.textContent).not.toMatch(/ChatGPT sign-in|API key|Sign-ins and keys/);
});
it("Sign in starts the one sign-in; Not now skips it", async () => {
@@ -270,10 +317,10 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
const calls = await mount({ cli: "missing" });
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
click("[data-onboarding-primary]");
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
+ await waitFor(() => expect(heading()).toMatch(ASK));
// The install plan is read: the run has the CLI's screen.
await waitFor(() => expect(document.querySelector("ol[aria-label]")!.getAttribute("aria-label")).toBe("Step 2 of 5"));
- click("[data-onboarding-primary]");
+ click("[data-first-run-secondary]");
await waitFor(() => expect(heading()).toBe("Use Cua from the Terminal."));
const facts = [...document.querySelectorAll<HTMLElement>("[data-first-run-cli-fact]")].map((e) => e.textContent);
expect(facts).toEqual(["Installs~/.local/bin/cua", "Adds to PATH~/.local/bin, in ~/.zshrc"]);
@@ -297,10 +344,10 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
const calls = await mount({ cli: "missing" });
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
click("[data-onboarding-primary]");
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
+ await waitFor(() => expect(heading()).toMatch(ASK));
// The install plan is read: the run has the CLI's screen.
await waitFor(() => expect(document.querySelector("ol[aria-label]")!.getAttribute("aria-label")).toBe("Step 2 of 5"));
- click("[data-onboarding-primary]");
+ click("[data-first-run-secondary]");
await waitFor(() => expect(heading()).toBe("Use Cua from the Terminal."));
click("[data-first-run-secondary]");
await waitFor(() => expect(heading()).toBe("Add your other computers."));
@@ -312,8 +359,8 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
await mount();
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
click("[data-onboarding-primary]");
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
- click("[data-onboarding-primary]");
+ await waitFor(() => expect(heading()).toMatch(ASK));
+ click("[data-first-run-secondary]");
await waitFor(() => expect(heading()).toBe("Add your other computers."));
});
@@ -383,12 +430,14 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
const calls = await mount({ agents: noAgents, local: (l) => ({ ...l, backends: ["docker"], macosImage: null, hostArch: "amd64" }) });
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
click("[data-onboarding-primary]");
- await waitFor(() => expect(heading()).toBe("Connect an agent."));
+ await waitFor(() => expect(heading()).toBe("We didn\u2019t find a coding app yet."));
expect(agents()).toEqual([]);
- const alts = [...document.querySelectorAll<HTMLElement>("[data-first-run-alternative]")].map((e) => e.dataset.firstRunAlternative);
- expect(alts).toEqual(["install", "cli"]);
- expect(document.querySelector('[data-first-run-alternative="cli"]')!.textContent).toMatch(/cua spaces create linux --on local/);
- click("[data-onboarding-primary]");
+ const missing = [...document.querySelectorAll<HTMLElement>("[data-first-run-missing]")].map((e) => e.dataset.firstRunMissing);
+ expect(missing).toEqual(["claude-code", "codex", "cursor"]);
+ expect(screen.getAllByRole("button", { name: /Download/ })).toHaveLength(3);
+ expect(document.body.textContent).toMatch(/Spaces work without a coding app\./);
+ expect(screen.getByRole("button", { name: "Check again" })).toBeTruthy();
+ fireEvent.click(screen.getByRole("button", { name: "Continue without one" }));
await waitFor(() => expect(heading()).toBe("Add your other computers."));
click("[data-first-run-secondary]");
await waitFor(() => expect(heading()).toBe("Try a first Space."));
@@ -413,7 +462,7 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
it("says in plain words that usage data is on, and turns it off with one tap", async () => {
writeFirstRun({ step: "connect" });
const calls = await mount();
- await waitFor(() => expect(heading()).toBe("Pick your agent."));
+ await waitFor(() => expect(heading()).toMatch(ASK));
const note = await waitFor(() => {
const n = document.querySelector("[data-first-run-usage]");
expect(n).toBeTruthy();
diff --git a/apps/cua-spaces-web/src/bridge/first-run.ts b/apps/cua-spaces-web/src/bridge/first-run.ts
index 576715b9c3..8823b0c634 100644
--- a/apps/cua-spaces-web/src/bridge/first-run.ts
+++ b/apps/cua-spaces-web/src/bridge/first-run.ts
@@ -466,7 +466,7 @@ export interface FirstRunHook {
connect(agent: string): Promise<void>;
/** Starts an agent's own sign-in on this computer (`codex login`). */
signIn(agent: string): Promise<void>;
- /** A screen's button: `start`, `continue`, `skip`, `not-now` (next screen), `install` (the CLI), `sign-in`, `set-up`, `open-settings`, `allow` (the app's guide to that System Settings pane), `copy`, `add`. */
+ /** A screen's button: `start`, `continue`, `skip`, `not-now` (next screen), `recheck` (read the agents again), `install` (the CLI), `sign-in`, `set-up`, `open-settings`, `allow` (the app's guide to that System Settings pane), `copy`, `add`. */
act(id: string, settingsUrl?: string | null): Promise<void>;
/** Copies `text` (the tab shown), else the selected request. */
copyPrompt(text?: string): Promise<void>;
@@ -827,9 +827,15 @@ export function useFirstRun(active = true, pollMs = FIRST_RUN_POLL_MS): FirstRun
setConnecting(agent);
setConnectError(null);
try {
- setAgents(await adapter.call("agents.configure", { agents: [agent] }));
- const was = readFirstRun().picked ?? [];
- writeFirstRun({ picked: was.includes(agent) ? was : [...was, agent] });
+ const rows = await adapter.call("agents.configure", { agents: [agent] });
+ setAgents(rows);
+ // Only an app Cua really got into counts as picked: one that failed is not "connected".
+ if (rows.find((r) => r.agent === agent)?.configured) {
+ const was = readFirstRun().picked ?? [];
+ writeFirstRun({ picked: was.includes(agent) ? was : [...was, agent] });
+ } else {
+ setConnectError(rows.find((r) => r.agent === agent)?.detail ?? "Cua is not in its settings.");
+ }
} catch (e) {
setConnectError(e instanceof Error ? e.message : String(e));
} finally {
@@ -930,6 +936,9 @@ export function useFirstRun(active = true, pollMs = FIRST_RUN_POLL_MS): FirstRun
).catch(() => {});
}
break;
+ case "recheck":
+ // "Check again": the agents are read again below.
+ break;
case "copy":
await copyPrompt();
break;
diff --git a/apps/cua-spaces-web/src/lib/connected-apps.test.ts b/apps/cua-spaces-web/src/lib/connected-apps.test.ts
index b9794dd14b..c07378d4ef 100644
--- a/apps/cua-spaces-web/src/lib/connected-apps.test.ts
+++ b/apps/cua-spaces-web/src/lib/connected-apps.test.ts
@@ -88,5 +88,6 @@ describe("failureText", () => {
expect(failureText("Hermes", "Permission denied (os error 13)")).toBe("Couldn't set up Hermes. Cua can't change this file because it is read-only or belongs to another user.");
expect(failureText("Hermes", "boom")).toBe("Couldn't set up Hermes. Cua said: boom.");
expect(failureText("Hermes", "Not set up")).toBe("Couldn't set up Hermes.");
+ expect(failureText("Hermes", "")).toBe("Couldn't set up Hermes.");
});
});
diff --git a/apps/cua-spaces-web/src/lib/connected-apps.ts b/apps/cua-spaces-web/src/lib/connected-apps.ts
index 982da02a99..07e4dfbbf3 100644
--- a/apps/cua-spaces-web/src/lib/connected-apps.ts
+++ b/apps/cua-spaces-web/src/lib/connected-apps.ts
@@ -112,5 +112,6 @@ export function failureText(name: string, detail: string): string {
if (/permission|read-only|readonly|EACCES|EPERM|os error 13|not writable/i.test(detail)) {
return `Couldn't set up ${name}. Cua can't change this file because it is read-only or belongs to another user.`;
}
- return `Couldn't set up ${name}. ${/^not set up$/i.test(detail) ? "" : "Cua said: " + detail.replace(/\.$/, "") + "."}`.trim();
+ const said = detail.trim();
+ return `Couldn't set up ${name}. ${!said || /^not set up$/i.test(said) ? "" : "Cua said: " + said.replace(/\.$/, "") + "."}`.trim();
}
diff --git a/apps/cua-spaces-web/src/routes/onboarding/index.tsx b/apps/cua-spaces-web/src/routes/onboarding/index.tsx
index ee197b8709..da3f427e47 100644
--- a/apps/cua-spaces-web/src/routes/onboarding/index.tsx
+++ b/apps/cua-spaces-web/src/routes/onboarding/index.tsx
@@ -2,12 +2,11 @@
// Copyright (c) 2026 Cua AI, Inc.
import { createFileRoute, redirect, useNavigate } from "@tanstack/react-router";
-import { ArrowLeftIcon, CheckIcon, CopyIcon } from "lucide-react";
+import { ArrowLeftIcon, CheckIcon, CopyIcon, ExternalLinkIcon } from "lucide-react";
import { useEffect, useState, type ReactNode } from "react";
-import { useAgentKeys, useFirstRun, type FirstRunArt, type FirstRunCredential, type FirstRunExtraView, type FirstRunHook, type FirstRunRow, type FirstRunView } from "@/bridge";
+import { useBridge, useFirstRun, type FirstRunArt, type FirstRunExtraView, type FirstRunHook, type FirstRunRow, type FirstRunView } from "@/bridge";
import { readSavedOnboarding } from "@/bridge/onboarding";
-import { KeySheet } from "@/components/agents/key-sheet";
import { CuaLogo } from "@/components/cua-logo";
import { OsIcon } from "@/components/os-icon";
import { Button } from "@/components/ui/button";
@@ -15,6 +14,10 @@ import { Segmented } from "@/components/ui/segmented";
import { Switch } from "@/components/ui/switch";
import { toast } from "@/components/ui/toast";
import { RuntimeFixRow } from "@/components/new-space/runtime-fix";
+import { Snippet } from "@/components/settings/snippet";
+import { listNames } from "@/components/space-ready-card";
+import { setConnectedAppsState, useConnectedAppsState } from "@/hooks/use-connected-apps";
+import { BY_HAND, failureText, getItUrl } from "@/lib/connected-apps";
import { cn } from "@/lib/utils";
export const Route = createFileRoute("/onboarding/")({
@@ -240,133 +243,218 @@ function AgentMark({ agent, name, className }: { agent: string; name?: string; c
return <img src={src} alt="" aria-hidden className={cn("size-4 shrink-0 object-contain", agent !== "claude-code" && agent !== "openclaw" && "dark:invert", className)} draggable={false} />;
}
+/** The prompt "done" hands over: a real job where a fresh computer matters. */
+/** First letter up: "your 5 coding apps can use Cua." as a sentence. */
+const sentence = (text: string) => text.charAt(0).toUpperCase() + text.slice(1);
+
+const FIRST_PROMPT = "Reproduce the crash from issue #4821 on a fresh Windows 11 Space and show me a recording.";
+
+/** The coding apps named when none is installed, in this order. */
+const HEADLINE_APPS = [
+ { agent: "claude-code", name: "Claude Code" },
+ { agent: "codex", name: "OpenAI Codex" },
+ { agent: "cursor", name: "Cursor" },
+];
+
+/**
+ * 2 · Let your coding apps use Cua: one question, asked once. It names the
+ * coding apps found on this computer; Set up adds Cua to all of them, Not now
+ * moves on. Later installs are set up the same way, with a notice and Undo
+ * (Settings, Connected apps). Which apps there are, and what Connect does for
+ * each, is still the app core's (`firstRun.view`).
+ */
function Connect({ fr, view }: { fr: FirstRunHook; view: FirstRunView }) {
const c = view.connect!;
- const keys = useAgentKeys();
+ const { data } = useBridge();
+ const remembered = useConnectedAppsState();
+ const [tried, setTried] = useState(false);
+ const [busy, setBusy] = useState(false);
+ const [byHand, setByHand] = useState(false);
const [copied, setCopied] = useState(false);
+ const rows = c.agents;
+ const looking = rows.length === 0 && /^Looking/.test(c.lede);
+ const none = rows.length === 0 && !looking;
+ const pending = rows.filter((a) => !a.connected);
+ const ready = rows.filter((a) => a.connected);
+ const working = busy || rows.some((a) => a.note === "Connecting\u2026");
+ const failed = tried && !working ? pending : [];
+ const why = (agent: string, name: string) =>
+ failureText(name, fr.agents.find((r) => r.agent === agent)?.detail || (c.error ?? "").replace(/^Couldn't connect Cua:\s*/, ""));
+ const ids = rows.map((a) => a.agent);
+
+ const setUp = async () => {
+ setTried(true);
+ setBusy(true);
+ // One yes covers these apps and the ones installed later (each with a notice and Undo).
+ setConnectedAppsState({ ...remembered, known: [...new Set([...(remembered.known ?? []), ...ids])], auto: true });
+ try {
+ for (const a of pending) await fr.connect(a.agent);
+ // One consent: they may also use the computer in the background, where Cua Driver is here.
+ if (data) await data.call("agents.setupDriver", { agents: pending.map((a) => a.agent) }).catch(() => {});
+ } finally {
+ setBusy(false);
+ }
+ };
+ const notNow = () => {
+ setConnectedAppsState({ ...remembered, known: [...new Set([...(remembered.known ?? []), ...ids])], auto: false });
+ void fr.act("skip");
+ };
+ const retry = async (agent: string) => {
+ setBusy(true);
+ try {
+ await fr.connect(agent);
+ } finally {
+ setBusy(false);
+ }
+ };
+ const copy = () => {
+ void navigator.clipboard?.writeText(FIRST_PROMPT).catch(() => {});
+ setCopied(true);
+ setTimeout(() => setCopied(false), 1500);
+ };
+ const usage = fr.usage ? (
+ <label className="mt-5 flex items-center gap-2.5 text-[13px] text-muted-foreground" data-first-run-usage="">
+ <Switch checked={fr.usage.on} disabled={!fr.usage.enabled} onCheckedChange={(on) => void fr.setUsage(on).catch(() => {})} aria-label={fr.usage.label} />
+ <span>
+ {fr.usage.label}.{" "}
+ <button type="button" className="underline hover:text-foreground" onClick={fr.openUsageLink}>
+ {fr.usage.linkLabel}
+ </button>
+ </span>
+ </label>
+ ) : null;
+
+ if (looking) {
+ return (
+ <Step id="connect" onBack={fr.back}>
+ <Heading>Looking for your coding apps…</Heading>
+ </Step>
+ );
+ }
+
+ if (none) {
+ return (
+ <Step id="connect" onBack={fr.back}>
+ <div data-first-run-connect-state="none">
+ <Heading>We didn’t find a coding app yet.</Heading>
+ <Lede>Cua works with coding apps such as Claude Code, Codex and Cursor. Install one and Cua will notice.</Lede>
+ <Rows className="mt-8" data-first-run-agents="">
+ {HEADLINE_APPS.map((a) => {
+ const url = getItUrl(a.agent);
+ return (
+ <div key={a.agent} className="flex min-h-12 items-center gap-3 py-2" data-first-run-missing={a.agent}>
+ <AgentMark agent={a.agent} name={a.name} />
+ <span className="min-w-0 flex-1 text-[14px]">{a.name}</span>
+ {url ? (
+ <Button variant="outline" className="h-9 shrink-0 gap-1.5 rounded-full border-foreground/25 px-4 text-[13px] font-medium" onClick={() => void fr.openUrl(url)}>
+ Download <ExternalLinkIcon className="size-3.5" />
+ </Button>
+ ) : null}
+ </div>
+ );
+ })}
+ </Rows>
+ <div className="mt-8 flex flex-wrap items-center gap-3">
+ <Primary label="Check again" onClick={() => void fr.act("recheck")} data-first-run-recheck="" />
+ <Secondary label="Continue without one" onClick={() => void fr.act("skip")} />
+ </div>
+ <p className="mt-4 text-[13px] text-muted-foreground">Spaces work without a coding app. You can set one up later in Settings.</p>
+ {usage}
+ </div>
+ </Step>
+ );
+ }
+
+ const all = pending.length === 0;
+ // Up to three names read well in a heading; more are "your 5 coding apps" and the rows name them.
+ const phrase = (list: { name: string }[]) => (list.length <= 3 ? listNames(list.map((a) => a.name)) : `your ${list.length} coding apps`);
+ const title = all
+ ? sentence(`${phrase(rows)} can use Cua.`)
+ : failed.length
+ ? `${ready.length ? sentence(`${phrase(ready)} can use Cua.`) + " " : ""}${sentence(`${phrase(failed)} ${failed.length === 1 ? "needs" : "need"} a hand.`)}`
+ : `Let ${phrase(rows)} use Cua?`;
+
return (
<Step id="connect" onBack={fr.back}>
- <Heading>{c.title}</Heading>
- <Lede>{c.lede}</Lede>
- {c.agents.length ? (
+ <div data-first-run-connect-state={all ? "done" : failed.length ? "failed" : "ask"}>
+ <Heading>{title}</Heading>
+ <Lede>
+ {all
+ ? "If one of them is open, restart it first. Then try this:"
+ : failed.length
+ ? failed.length === 1
+ ? `Cua couldn\u2019t change ${failed[0]!.name}\u2019s settings, so ${failed[0]!.name} can\u2019t use Cua yet.`
+ : `Cua couldn\u2019t change their settings, so ${listNames(failed.map((a) => a.name))} can\u2019t use Cua yet.`
+ : "Then you can ask them for things like \u201cReproduce this bug on a fresh Windows machine.\u201d They create the Space, work in it and tell you what they found."}
+ </Lede>
+ {all ? (
+ <div className="mt-6 flex items-start gap-3 rounded-2xl border border-foreground/15 px-5 py-4" data-first-run-prompt="">
+ <p className="min-w-0 flex-1 text-[15px] leading-relaxed select-text">{FIRST_PROMPT}</p>
+ <button type="button" aria-label="Copy the prompt" onClick={copy} className="mt-0.5 text-muted-foreground hover:text-foreground">
+ {copied ? <CheckIcon className="size-4" /> : <CopyIcon className="size-4" />}
+ </button>
+ </div>
+ ) : null}
<Rows className="mt-8" data-first-run-agents="">
- {c.agents.map((a) => (
- <div key={a.agent} className="flex min-h-12 items-center gap-3 py-2" data-first-run-agent={a.agent} data-connected={String(a.connected)}>
- <AgentMark agent={a.agent} name={a.name} />
- <div className="min-w-0 flex-1">
- <span className="text-[14px]">{a.name}</span>
- {a.file ? <span className="ml-2 font-mono text-[12px] text-muted-foreground">{a.file}</span> : null}
+ {rows.map((a) => {
+ const bad = failed.some((f) => f.agent === a.agent);
+ return (
+ <div key={a.agent} className="flex min-h-12 items-center gap-3 py-2" data-first-run-agent={a.agent} data-connected={String(a.connected)} data-failed={bad ? "" : undefined}>
+ <AgentMark agent={a.agent} name={a.name} />
+ <div className="min-w-0 flex-1">
+ <div className="text-[14px]">{a.name}</div>
+ {bad ? <div className="text-[13px] text-destructive">{why(a.agent, a.name)}</div> : null}
+ </div>
+ {a.connected ? (
+ <span className="flex shrink-0 items-center gap-1 text-[13px] text-[#1f9d55] dark:text-[#4ade80]">
+ <CheckIcon className="size-3.5" /> Ready
+ </span>
+ ) : bad ? (
+ <Button variant="outline" disabled={working} className="h-9 shrink-0 rounded-full border-foreground/25 px-4 text-[13px] font-medium" onClick={() => void retry(a.agent)} data-first-run-retry={a.agent}>
+ Try again
+ </Button>
+ ) : working ? (
+ <span className="shrink-0 text-[13px] text-muted-foreground">Setting up…</span>
+ ) : null}
</div>
- {a.note ? (
- <span className={cn("shrink-0 text-[13px]", a.connected ? "text-[#1f9d55]" : "text-muted-foreground")}>{a.note}</span>
- ) : null}
- {a.action ? (
- <Button variant="outline" className="h-9 shrink-0 rounded-full border-foreground/25 px-4 text-[13px] font-medium" onClick={() => void fr.connect(a.agent)} data-first-run-connect={a.agent}>
- {a.action.label}
- </Button>
- ) : null}
- </div>
- ))}
+ );
+ })}
</Rows>
- ) : null}
- {c.alternatives.length ? (
- <Rows className="mt-6" data-first-run-alternatives="">
- {c.alternatives.map((alt) => (
- <div key={alt.id} className="flex min-h-16 items-center gap-3 py-2" data-first-run-alternative={alt.id}>
- <div className="min-w-0 flex-1">
- <div className="text-[14px]">{alt.title}</div>
- <div className="text-[13px] text-muted-foreground">{alt.note}</div>
- {alt.command ? <code className="mt-1 block font-mono text-[12.5px]">{alt.command}</code> : null}
- </div>
- {alt.url ? (
- <Button variant="outline" className="h-9 shrink-0 rounded-full border-foreground/25 px-4 text-[13px] font-medium" onClick={() => void fr.openUrl(alt.url!)}>
- Open
- </Button>
- ) : alt.command ? (
- <Button
- variant="outline"
- className="h-9 shrink-0 gap-1.5 rounded-full border-foreground/25 px-4 text-[13px] font-medium"
- onClick={() => {
- void navigator.clipboard?.writeText(alt.command!).catch(() => {});
- setCopied(true);
- setTimeout(() => setCopied(false), 1500);
- }}
- >
- {copied ? <CheckIcon className="size-3.5" /> : <CopyIcon className="size-3.5" />}
- {copied ? "Copied" : "Copy"}
- </Button>
- ) : null}
- </div>
- ))}
- </Rows>
- ) : null}
- {c.credentials.length ? (
- <>
- <Rows className="mt-6" data-first-run-credentials="">
- {c.credentials.map((r) => (
- <CredentialRowView
- key={r.id}
- row={r}
- onAct={() => {
- if (r.action?.id === "agent-sign-in" && r.agent) void fr.signIn(r.agent);
- else if (r.action?.id === "add-key" && (r.provider === "anthropic" || r.provider === "openai")) keys.openSheet(r.provider);
- }}
- />
- ))}
- </Rows>
- <p className="mt-3 text-xs text-muted-foreground" data-first-run-credentials-note="">
- {c.credentialsNote}
- </p>
- </>
- ) : null}
- {c.error ? (
- <p role="alert" className="mt-3 text-[13px] text-destructive">
- {c.error}
- </p>
- ) : null}
- <div className="mt-8 flex flex-wrap items-center gap-3">
- <Primary label={c.primary.label} onClick={() => void fr.act(c.primary.id)} />
- {c.secondary ? <Secondary label={c.secondary.label} onClick={() => void fr.act(c.secondary!.id)} /> : null}
- </div>
- {fr.usage ? (
- <label className="mt-5 flex items-center gap-2.5 text-[13px] text-muted-foreground" data-first-run-usage="">
- <Switch checked={fr.usage.on} disabled={!fr.usage.enabled} onCheckedChange={(on) => void fr.setUsage(on).catch(() => {})} aria-label={fr.usage.label} />
- <span>
- {fr.usage.label}.{" "}
- <button type="button" className="underline hover:text-foreground" onClick={fr.openUsageLink}>
- {fr.usage.linkLabel}
- </button>
- </span>
- </label>
- ) : null}
- {keys.sheet ? <KeySheet key={keys.sheet.provider} keys={keys} provider={keys.sheet.provider} env={keys.sheet.env} /> : null}
- </Step>
- );
-}
-
-function CredentialRowView({ row: r, onAct }: { row: FirstRunCredential; onAct: () => void }) {
- return (
- <div className="flex min-h-16 items-center gap-3 py-2" data-first-run-credential={r.id}>
- <div className="min-w-0 flex-1">
- <div className="text-[14px]">{r.title}</div>
- <div className="text-xs text-muted-foreground">{r.note}</div>
- {r.error ? (
- <div role="alert" className="mt-0.5 text-xs text-destructive">
- {r.error}
+ <div className="mt-8 flex flex-wrap items-center gap-3">
+ {all || failed.length ? (
+ <>
+ <Primary label="Continue" onClick={() => void fr.act(c.primary.id)} />
+ {all ? <Secondary label={copied ? "Copied" : "Copy the prompt"} onClick={copy} /> : <Secondary label="Add it by hand" onClick={() => setByHand(!byHand)} />}
+ </>
+ ) : (
+ <>
+ <Primary label="Set up" onClick={() => void setUp()} data-first-run-set-up="" />
+ <Secondary label="Not now" onClick={notNow} />
+ </>
+ )}
+ </div>
+ {byHand && failed.length ? (
+ <div className="mt-4 space-y-3" data-first-run-by-hand="">
+ {failed.map((a) =>
+ BY_HAND[a.agent] ? (
+ <div key={a.agent}>
+ <Snippet file={BY_HAND[a.agent]!.file} text={BY_HAND[a.agent]!.snippet} />
+ <p className="mt-2 text-xs text-muted-foreground">Paste this into the file, then restart {a.name}.</p>
+ </div>
+ ) : null,
+ )}
</div>
) : null}
+ <p className="mt-4 max-w-[460px] text-[13px] text-muted-foreground" data-first-run-consent="">
+ {all
+ ? "Cua added itself to each app\u2019s settings and left everything else alone."
+ : failed.length
+ ? `${listNames(ready.map((a) => a.name))} ${ready.length === 1 ? "is" : "are"} done. ${listNames(failed.map((a) => a.name))} can wait: Settings has the same button.`
+ : "Cua adds itself to each app\u2019s settings and leaves everything else alone. Apps you install later are set up the same way, with a notice and Undo. You can turn it off any time in Settings."}
+ </p>
+ {usage}
</div>
- {r.status ? (
- <span className={cn("shrink-0 text-[13px]", r.ok ? "text-[#1f9d55]" : "text-muted-foreground")} data-first-run-credential-status="">
- {r.status}
- </span>
- ) : null}
- {r.action ? (
- <Button variant="outline" className="h-9 shrink-0 rounded-full border-foreground/25 px-4 text-[13px] font-medium" onClick={onAct} data-first-run-credential-action={r.action.id}>
- {r.action.label}
- </Button>
- ) : null}
- </div>
+ </Step>
);
}
@@ -691,7 +779,7 @@ function Dots({ view }: { view: FirstRunView }) {
return (
<ol className="relative z-10 flex shrink-0 justify-start gap-2 pt-4 pb-6 pl-[var(--ob-x)]" aria-label={`Step ${view.current + 1} of ${view.dots}`}>
{Array.from({ length: view.dots }, (_, i) => (
- <li key={i} aria-current={i === view.current ? "step" : undefined} className={cn("h-0.5 w-6 rounded-full bg-foreground/20", i <= view.current && "bg-foreground/80")} />
+ <li key={i} aria-current={i === view.current ? "step" : undefined} className={cn("h-1 w-7 rounded-full bg-foreground/30", i <= view.current && "bg-foreground")} />
))}
</ol>
);