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 app: offer to let an agent use the first ready Space (CUA-1958) (#5645)

Francesco Bonaccic797b9ba62cf
diff --git a/apps/cua-spaces-web/docs b/apps/cua-spaces-web/docs
new file mode 100644
index 0000000000..d342687b0c
Binary files /dev/null and b/apps/cua-spaces-web/docs differ
diff --git a/apps/cua-spaces-web/src/bridge/hooks.ts b/apps/cua-spaces-web/src/bridge/hooks.ts
index 394e615a7e..3f9839999c 100644
--- a/apps/cua-spaces-web/src/bridge/hooks.ts
+++ b/apps/cua-spaces-web/src/bridge/hooks.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.
-import { useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
import type { BridgeMode, DataAdapter } from "./adapter";
import { BridgeContext, type BridgeContextValue } from "./BridgeProvider";
import type { CoreClient } from "./core";
@@ -96,6 +96,17 @@ export function useFeatureRecorded(feature: string, when = true): void {
}, [ready, feature, when]);
}
+/** Records one named feature now, for a click or a step rather than a page opening. */
+export function useFeatureRecorder(): (feature: string) => void {
+ const ready = useContext(BridgeContext)?.ready;
+ return useCallback(
+ (feature: string) => {
+ void ready?.then((s) => s.telemetry.track([{ type: "feature", feature }]));
+ },
+ [ready],
+ );
+}
+
/** The host, the app core and the raw adapter. */
export function useBridge(): { mode: BridgeMode; core: CoreClient; data: DataAdapter | null } {
const { mode, core, adapter } = useBridgeContext();
diff --git a/apps/cua-spaces-web/src/bridge/index.ts b/apps/cua-spaces-web/src/bridge/index.ts
index f797137b8e..d418fafe20 100644
--- a/apps/cua-spaces-web/src/bridge/index.ts
+++ b/apps/cua-spaces-web/src/bridge/index.ts
@@ -13,6 +13,7 @@ export {
useAgents,
useBridge,
useFeatureRecorded,
+ useFeatureRecorder,
useKeyvault,
useMachines,
useOnboarding,
diff --git a/apps/cua-spaces-web/src/components/__tests__/first-space-ready.test.tsx b/apps/cua-spaces-web/src/components/__tests__/first-space-ready.test.tsx
index 08fcab180b..06d6c203a4 100644
--- a/apps/cua-spaces-web/src/components/__tests__/first-space-ready.test.tsx
+++ b/apps/cua-spaces-web/src/components/__tests__/first-space-ready.test.tsx
@@ -1,12 +1,15 @@
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.
-import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { act, cleanup, fireEvent, render, renderHook, screen, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ReactNode } from "react";
+
import type { AgentSetupRow, Space } from "@/bridge";
+import { BridgeContext, type BridgeContextValue } from "@/bridge/BridgeProvider";
import { RunAgentDialog, runAgentPrompt } from "@/components/agents/run-agent-dialog";
-import { SpaceReadyCard } from "@/components/space-ready-card";
+import { SpaceReadyCard, useAgentOffer } from "@/components/space-ready-card";
import { EXPLAINED_KEY, needsExplainer, TeleportExplainer } from "@/components/teleport/explainer";
const nav = vi.fn();
@@ -30,12 +33,67 @@ beforeEach(() => {
afterEach(cleanup);
describe("SpaceReadyCard", () => {
- it("has one primary action, Run an agent here", () => {
+ it("lists the agents it found and has one action", async () => {
+ rows = [row({}), row({ agent: "codex", name: "Codex", configured: true }), row({ agent: "hermes", name: "Hermes", installed: false })];
const onRun = vi.fn();
render(<SpaceReadyCard space={space} onRun={onRun} />);
- expect(screen.getAllByRole("button")).toHaveLength(1);
- fireEvent.click(screen.getByRole("button", { name: "Run an agent here" }));
+ expect(await screen.findByText(/We found Claude Code and Codex on this computer/)).toBeTruthy();
+ fireEvent.click(screen.getByRole("button", { name: "Start with Codex" }));
expect(onRun).toHaveBeenCalledOnce();
+ expect(document.body.textContent).not.toMatch(/relay|MCP|\bhost\b/i);
+ });
+
+ it("offers to connect an agent that is installed but not connected", async () => {
+ rows = [row({})];
+ render(<SpaceReadyCard space={space} onRun={() => {}} />);
+ expect(await screen.findByRole("button", { name: "Connect Claude Code" })).toBeTruthy();
+ });
+
+ it("says how when no agent is found, and can be closed", async () => {
+ rows = [];
+ const onDismiss = vi.fn();
+ render(<SpaceReadyCard space={space} onRun={() => {}} onDismiss={onDismiss} />);
+ expect(await screen.findByRole("button", { name: "Show me how" })).toBeTruthy();
+ fireEvent.click(screen.getByRole("button", { name: "Not now" }));
+ expect(onDismiss).toHaveBeenCalledOnce();
+ });
+});
+
+describe("useAgentOffer", () => {
+ const track = vi.fn();
+ const wrapper = ({ children }: { children?: ReactNode }) => {
+ const store = { telemetry: { track } };
+ const value = { mode: "electron", core: {}, adapter: null, store, ready: Promise.resolve(store) } as unknown as BridgeContextValue;
+ return <BridgeContext.Provider value={value}>{children}</BridgeContext.Provider>;
+ };
+ const events = () => track.mock.calls.map((c) => (c[0] as { feature: string }[])[0]!.feature);
+ beforeEach(() => track.mockClear());
+
+ it("records shown once, then clicked and completed, and never shows again", async () => {
+ const { result, rerender } = renderHook(() => useAgentOffer(true), { wrapper });
+ await waitFor(() => expect(events()).toEqual(["agent_offer_shown"]));
+ act(() => result.current.clicked());
+ act(() => result.current.completed());
+ await waitFor(() => expect(events()).toEqual(["agent_offer_shown", "agent_offer_clicked", "agent_offer_completed"]));
+ expect(result.current.visible).toBe(false);
+ rerender();
+ const again = renderHook(() => useAgentOffer(true), { wrapper });
+ expect(again.result.current.visible).toBe(false);
+ expect(events()).toHaveLength(3);
+ });
+
+ it("stays closed after Not now, and counts shown once per install", async () => {
+ const first = renderHook(() => useAgentOffer(true), { wrapper });
+ await waitFor(() => expect(events()).toEqual(["agent_offer_shown"]));
+ act(() => first.result.current.dismiss());
+ expect(first.result.current.visible).toBe(false);
+ expect(renderHook(() => useAgentOffer(true), { wrapper }).result.current.visible).toBe(false);
+ expect(events()).toEqual(["agent_offer_shown"]);
+ });
+
+ it("is hidden until a Space is ready", () => {
+ expect(renderHook(() => useAgentOffer(false), { wrapper }).result.current.visible).toBe(false);
+ expect(track).not.toHaveBeenCalled();
});
});
diff --git a/apps/cua-spaces-web/src/components/agents/run-agent-dialog.tsx b/apps/cua-spaces-web/src/components/agents/run-agent-dialog.tsx
index 9e1398dd24..5a94eb1c8c 100644
--- a/apps/cua-spaces-web/src/components/agents/run-agent-dialog.tsx
+++ b/apps/cua-spaces-web/src/components/agents/run-agent-dialog.tsx
@@ -20,7 +20,7 @@ export const runAgentPrompt = (spaceName: string) => `Open the Cua Space "${spac
* first (one button) and then shows the request. The agent's work shows up
* on the Agents page.
*/
-export function RunAgentDialog({ open, space, onOpenChange, onManual }: { open: boolean; space: Space; onOpenChange: (open: boolean) => void; onManual?: () => void }) {
+export function RunAgentDialog({ open, space, onOpenChange, onManual, onConnected }: { open: boolean; space: Space; onOpenChange: (open: boolean) => void; onManual?: () => void; onConnected?: () => void }) {
const { agentSetup, configureAgents } = useAgents();
const navigate = useNavigate();
const [rows, setRows] = useState<AgentSetupRow[] | null>(null);
@@ -50,11 +50,15 @@ export function RunAgentDialog({ open, space, onOpenChange, onManual }: { open:
const setUp = () => {
setBusy(true);
configureAgents()
- .then(setRows)
+ .then((r) => {
+ setRows(r);
+ if (r.some((x) => x.installed && x.configured)) onConnected?.();
+ })
.catch((e: unknown) => toast("Couldn't connect your agent", { description: e instanceof Error ? e.message : String(e) }))
.finally(() => setBusy(false));
};
const copy = () => {
+ onConnected?.();
void navigator.clipboard?.writeText(prompt).then(() => {
setCopied(true);
setTimeout(() => setCopied(false), 1500);
diff --git a/apps/cua-spaces-web/src/components/space-ready-card.tsx b/apps/cua-spaces-web/src/components/space-ready-card.tsx
index d8b1b7dc35..a871242353 100644
--- a/apps/cua-spaces-web/src/components/space-ready-card.tsx
+++ b/apps/cua-spaces-web/src/components/space-ready-card.tsx
@@ -1,16 +1,97 @@
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.
-import { BotIcon } from "lucide-react";
+import { BotIcon, XIcon } from "lucide-react";
+import { useCallback, useEffect, useState } from "react";
-import type { Space } from "@/bridge";
+import { useAgents, useFeatureRecorder, type AgentSetupRow, type Space } from "@/bridge";
import { Button } from "@/components/ui/button";
+const KEY = "cua.agentOffer";
+
+type Outcome = "dismissed" | "done";
+
+const read = (): Outcome | null => {
+ try {
+ const v = globalThis.localStorage?.getItem(KEY);
+ return v === "dismissed" || v === "done" ? v : null;
+ } catch {
+ return null;
+ }
+};
+
/**
- * The moment a user's first Space is ready: one thing to do next, "Run an
- * agent here". Add computer and Share stay in the checklist below it.
+ * The offer to connect an agent after the first Space is ready. It stays
+ * until the person closes it or connects an agent, then never comes back.
+ * Events: `agent_offer_shown` (once per install), `agent_offer_clicked`,
+ * `agent_offer_completed` (an agent got connected, or its request was copied).
*/
-export function SpaceReadyCard({ space, onRun }: { space: Space; onRun: () => void }) {
+export function useAgentOffer(eligible: boolean) {
+ const record = useFeatureRecorder();
+ const [outcome, setOutcome] = useState<Outcome | null>(read);
+ const visible = eligible && outcome === null;
+ useEffect(() => {
+ if (!visible) return;
+ try {
+ if (globalThis.localStorage?.getItem(`${KEY}.shown`)) return;
+ globalThis.localStorage?.setItem(`${KEY}.shown`, "1");
+ } catch {
+ // Not kept: it may count again on the next launch.
+ }
+ record("agent_offer_shown");
+ }, [visible, record]);
+ const finish = useCallback((next: Outcome) => {
+ try {
+ globalThis.localStorage?.setItem(KEY, next);
+ } catch {
+ // Not kept: it may show again on the next launch.
+ }
+ setOutcome(next);
+ }, []);
+ return {
+ visible,
+ clicked: () => record("agent_offer_clicked"),
+ completed: () => {
+ if (!visible) return;
+ record("agent_offer_completed");
+ finish("done");
+ },
+ dismiss: () => finish("dismissed"),
+ };
+}
+
+/** "Claude Code", "Claude Code and Codex", "Claude Code, Codex and Hermes". */
+export function listNames(names: string[]): string {
+ return names.length < 2 ? (names[0] ?? "") : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+
+/**
+ * The moment a user's first Space is ready: let an agent use it. Shows the
+ * agents found on this computer and one action. Add computer and Share stay
+ * in the checklist below it.
+ */
+export function SpaceReadyCard({ space, onRun, onDismiss }: { space: Space; onRun: () => void; onDismiss?: () => void }) {
+ const { agentSetup } = useAgents();
+ const [rows, setRows] = useState<AgentSetupRow[] | null>(null);
+ useEffect(() => {
+ let live = true;
+ agentSetup().then(
+ (r) => live && setRows(r),
+ () => live && setRows([]),
+ );
+ return () => {
+ live = false;
+ };
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
+ const found = (rows ?? []).filter((r) => r.installed);
+ const first = found.find((r) => r.configured) ?? found[0];
+ const action = !first ? "Show me how" : first.configured ? `Start with ${first.name}` : `Connect ${first.name}`;
+ const line = found.length
+ ? `We found ${listNames(found.map((r) => r.name))} on this computer. Let one work in ${space.name} while you watch.`
+ : "Connect an agent such as Claude Code or Codex, give it a task, and watch it work on this computer.";
+
return (
<section data-space-ready="" aria-labelledby="space-ready-title" className="mb-6 flex items-center gap-4 rounded-xl border bg-card px-5 py-4 shadow-xs">
<span aria-hidden className="flex size-10 shrink-0 items-center justify-center rounded-[10px] bg-brand/10 text-brand">
@@ -18,13 +99,18 @@ export function SpaceReadyCard({ space, onRun }: { space: Space; onRun: () => vo
</span>
<div className="min-w-0 flex-1">
<h2 id="space-ready-title" className="text-[14px] font-semibold">
- {space.name} is ready
+ Let an agent use this Space
</h2>
- <p className="mt-0.5 text-xs text-muted-foreground">Give an agent a task and watch it work on this computer.</p>
+ <p className="mt-0.5 text-xs text-muted-foreground">{rows === null ? "Looking for your agents…" : line}</p>
</div>
- <Button data-space-ready-run="" onClick={onRun}>
- Run an agent here
+ <Button data-space-ready-run="" disabled={rows === null} onClick={onRun}>
+ {action}
</Button>
+ {onDismiss ? (
+ <Button data-space-ready-dismiss="" size="icon-sm" variant="ghost" aria-label="Not now" onClick={onDismiss}>
+ <XIcon className="size-3.5" />
+ </Button>
+ ) : null}
</section>
);
}
diff --git a/apps/cua-spaces-web/src/routes/spaces/index.tsx b/apps/cua-spaces-web/src/routes/spaces/index.tsx
index 9821d3a774..4a0d7bc6c2 100644
--- a/apps/cua-spaces-web/src/routes/spaces/index.tsx
+++ b/apps/cua-spaces-web/src/routes/spaces/index.tsx
@@ -10,7 +10,7 @@ import { EmptyHome } from "@/components/empty-home";
import { ConnectAgentDialog } from "@/components/agents/connect-dialog";
import { RunAgentDialog } from "@/components/agents/run-agent-dialog";
import { GettingStarted } from "@/components/getting-started";
-import { SpaceReadyCard } from "@/components/space-ready-card";
+import { SpaceReadyCard, useAgentOffer } from "@/components/space-ready-card";
import { FirstRunTodosCard, useFirstRunTodosShown } from "@/components/first-run-todos";
import { OsIcon } from "@/components/os-icon";
import { EmptyState, Page, PageHeader } from "@/components/page";
@@ -72,7 +72,8 @@ function SpacesPage() {
const { data: agents } = useAgents();
const readySpace = spaces.find((s) => spaceState(s) === "running");
const agentRan = checklist.done.run_agent || (agents?.runs.length ?? 0) > 0 || (agents?.agents.length ?? 0) > 0;
- const runHere = readySpace && !agentRan ? readySpace : undefined;
+ const offer = useAgentOffer(Boolean(readySpace) && !agentRan);
+ const runHere = readySpace && !agentRan && offer.visible ? readySpace : undefined;
const [runOpen, setRunOpen] = useState(false);
const [connectOpen, setConnectOpen] = useState(false);
// The cards above the list (ready, checklist, computers) and the list come from separate host reads. Draw them
@@ -95,11 +96,11 @@ function SpacesPage() {
{settled ? (
<>
<FirstRunTodosCard />
- {runHere ? <SpaceReadyCard space={runHere} onRun={() => setRunOpen(true)} /> : null}
+ {runHere ? <SpaceReadyCard space={runHere} onRun={() => { offer.clicked(); setRunOpen(true); }} onDismiss={offer.dismiss} /> : null}
{firstRunTodos ? null : <GettingStarted onRunAgent={runHere ? () => setRunOpen(true) : undefined} />}
{readySpace ? (
<>
- <RunAgentDialog open={runOpen} space={readySpace} onOpenChange={setRunOpen} onManual={() => setConnectOpen(true)} />
+ <RunAgentDialog open={runOpen} space={readySpace} onOpenChange={setRunOpen} onManual={() => setConnectOpen(true)} onConnected={offer.completed} />
<ConnectAgentDialog open={connectOpen} onOpenChange={setConnectOpen} />
</>
) : null}