Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.
/**
* The contract between the web UI and the native hosts: the SwiftUI app's
* WKWebView (apps/cua-spaces-macos, `WebHost/WebUIBridge.swift`) and the
* Electron shell's main process (apps/cua-spaces-desktop, `src/bridge/`),
* which answers the same methods with the same shapes over its own
* transport (`electron-channels.ts`, `transport.ts`).
*
* Page -> host: `window.webkit.messageHandlers.cua.postMessage(request)`.
* The handler is a `WKScriptMessageHandlerWithReply`, so `postMessage`
* returns a Promise that resolves with the response:
*
* { id, method, args? } -> { id, ok: true, result } | { id, ok: false, error: { code, message } }
*
* `code`: `unimplemented`, `bad_args`, `not_found`, `cancelled`,
* `native_only`, `forbidden` or `failed`. A failed host setup or This
* machine button also says `title`, `details` (the raw error),
* `actionLabel`, `kind` (`HostSetupFailure.Kind`, e.g. `needsProof`) and the
* relay's `refusalCode` when it gave one, and `message` is then the plain words.
*
* Host -> page events: `window.dispatchEvent(new CustomEvent("cua:event",
* { detail: { event, payload } }))`, where `event` is one of `WEBKIT_EVENTS`.
* The page asks again for what it shows.
*
* Results are the app core's records as the SwiftUI views get them
* (`BridgeValue.swift`): camelCase fields, enums as their case name, or
* `{ type, ...fields }` with a payload. `adapters/webkit.ts` maps them onto
* `HostOperations` (`protocol.ts`).
*/
import type { MachineAccessNotice } from "./contracts/devices";
import type { MachinePageRow, MachinesView, RuntimesInput } from "./contracts/host";
import { AGENT_DETAIL_WEBKIT_METHODS } from "./ops/agent-detail";
import { AGENT_KEYS_WEBKIT_METHODS } from "./ops/agent-keys";
import { GITHUB_WEBKIT_METHODS } from "./ops/github";
import { CI_WEBKIT_METHODS } from "./ops/ci";
import { KEYVAULT_MANAGE_WEBKIT_METHODS } from "./ops/keyvault-manage";
import { KEYVAULT_SETUP_WEBKIT_METHODS } from "./ops/keyvault-setup";
import { THREAD_WEBKIT_METHODS } from "./ops/thread";
import { AGENT_THREADS_WEBKIT_METHODS } from "./ops/agent-threads";
import { SPACES_SETTINGS_WEBKIT_METHODS } from "./ops/spaces-settings";
export const WEBKIT_HANDLER_NAME = "cua";
/** The window event the host dispatches. */
export const WEBKIT_EVENT = "cua:event";
/** Every method the SwiftUI host routes (`WebUIBridge.methods`).
* `spaces.cancelCreate`, `host.status`, `keyvault.approve`, `keyvault.deny`,
* `keyvault.revokeGrant` and the `agents.*` methods have the operation's own
* name and arguments (`HostOperations`), like the Electron router's
* `cua:<op>` channels. */
export const WEBKIT_METHODS = [
"app.info",
"session.get",
"session.signIn",
"session.signOut",
"onboarding.get",
"onboarding.complete",
"onboarding.reset",
"spaces.list",
"spaces.open",
"spaces.createOptions",
"spaces.create",
"spaces.setPower",
"spaces.delete",
"spaces.deleteMany",
"spaces.leave",
"spaces.rename",
"network.get",
"network.set",
"network.log",
"network.ackNotice",
"spaces.setAccess",
"spaces.tree",
"children.set",
"budget.get",
"budget.set",
"services.list",
"services.control",
"spaces.cancelCreate",
"machines.list",
"host.status",
"agents.list",
"agents.runs",
"agents.events",
"agents.start",
"agents.message",
"agents.pause",
"agents.resume",
"agents.setup",
"agents.configure",
"agents.signIn",
"agents.status",
"agents.connect",
"agents.disconnect",
"agents.signInStart",
"agents.signInWait",
...AGENT_DETAIL_WEBKIT_METHODS,
...AGENT_KEYS_WEBKIT_METHODS,
...GITHUB_WEBKIT_METHODS,
...KEYVAULT_SETUP_WEBKIT_METHODS,
...KEYVAULT_MANAGE_WEBKIT_METHODS,
// The pages beyond Spaces, the Keyvault and Agents (ops/webkit-pages.ts).
"spaces.add",
"clouds.status",
"clouds.test",
"clouds.connect",
"clouds.disconnect",
"clouds.approve",
"teleport.catalog",
"teleport.entryForPath",
"teleport.windows",
"teleport.remoteWindows",
"teleport.icon",
"teleport.thumbnail",
"teleport.plan",
"teleport.run",
"teleport.sites",
"teleport.readiness",
"teleport.remembered",
"teleport.streamWindow",
"sharing.list",
"sharing.share",
"sharing.unshare",
"sharing.removals",
"sharing.ackRemovals",
"volume.overview",
"volume.storage",
"volume.storageSet",
"volume.mount",
"volume.unmount",
"volume.approve",
"volume.deny",
"volume.revoke",
"volume.resolve",
"volume.reveal",
"agents.setupDriver",
"about.get",
"about.set",
"about.checkNow",
"update.get",
"update.install",
"loginItem.get",
"loginItem.set",
"loginItem.openSettings",
"runtimes.check",
"runtimes.browse",
"repoCache.get",
"repoCache.set",
"repoCache.clear",
"devices.get",
"devices.enroll",
"devices.checkEnrolled",
"devices.approve",
"devices.rename",
"devices.revoke",
"devices.confirmMachine",
"devices.createPairingCode",
"devices.pairingCodes",
"devices.revokePairingCode",
"teams.list",
"storage.get",
"storage.run",
"notifications.list",
"notifications.markAllRead",
"notifications.markRead",
"telemetry.track",
"telemetry.linkNotice",
"telemetry.acknowledgeLinkNotice",
"crashReporting.config",
"spaces.usage",
"spaces.windows",
"stream.pip",
"spaces.thumbnail",
"spaces.chooseFiles",
"spaces.droppedFiles",
"spaces.sendFiles",
"host.setUp",
"host.joinWithCode",
"host.action",
"host.limits",
"host.openSettings",
"settings.get",
"settings.choose",
"settings.update",
"keyvault.get",
"keyvault.lock",
"keyvault.unlock",
"keyvault.unlockVault",
"keyvault.setDisabled",
"keyvault.approve",
"keyvault.deny",
"keyvault.revokeGrant",
"window.setBackgroundColor",
"window.setDragRegions",
"window.setDropTargets",
"startup.get",
"startup.act",
"relay.usage",
"nudges.pending",
"nudges.answer",
"driver.status",
"driver.list",
"driver.config",
"driver.setConfig",
"driver.test",
"driver.pause",
"driver.setup",
"driver.setApp",
"driver.permissions",
"resources.get",
"machines.rename",
"machines.remove",
"machines.checkHealth",
...SPACES_SETTINGS_WEBKIT_METHODS,
"checklist.get",
"checklist.send",
"links.list",
"links.create",
"links.stop",
"links.approve",
"links.deny",
"shares.settings.get",
"shares.settings.set",
"shares.edge.remove",
"cli.plan",
"cli.install",
...CI_WEBKIT_METHODS,
...THREAD_WEBKIT_METHODS,
...AGENT_THREADS_WEBKIT_METHODS,
] as const;
export type WebkitMethod = (typeof WEBKIT_METHODS)[number];
/** What only the Electron host answers: it draws a Space's video in the
* page (WebCodecs), so the page asks it for a media ticket
* (`ops/stream.ts`); the Mac app draws video natively. (Both hosts run
* this page's first run: `onboarding.get`, `onboarding.complete`.) It also joins presence for the video the page draws
* (`presence.*`, `ops/presence.ts`). */
export const ELECTRON_HOST_METHODS = ["spaces.openStream", "presence.join", "presence.publish", "presence.leave", "spaces.fixRuntime"] as const;
/** `onboarding.get` and `onboarding.complete`'s answer: whether the first run finished, and as what. */
export interface WkOnboarding {
completed: boolean;
mode: "client" | "host";
}
export type HostMethod = WebkitMethod | (typeof ELECTRON_HOST_METHODS)[number];
/** The app menu's Settings command (⌘,) while the SwiftUI app's New UI window is in front: go to Settings. */
export const WEBKIT_OPEN_SETTINGS_EVENT = "settings.openRequested";
/** The SwiftUI app's notch and menu bar item while New UI is on: go to `payload.path` (`/spaces/<id>`, `/settings`, ...). */
export const WEBKIT_OPEN_ROUTE_EVENT = "route.openRequested";
/** The app menu's Help > Getting Started: show the getting-started checklist again. */
export const WEBKIT_OPEN_CHECKLIST_EVENT = "checklist.openRequested";
export const WEBKIT_EVENTS = [
"spaces.changed",
"machines.changed",
"keyvault.changed",
"session.changed",
"settings.changed",
"update.changed",
"agents.changed",
"teleport.progress",
"startup.changed",
] as const;
export type WebkitEventName = (typeof WEBKIT_EVENTS)[number];
export interface WebkitRequest {
/** Unique per page load; the host echoes it. */
id: string;
method: HostMethod;
args?: Record<string, unknown>;
}
export type WebkitResponse =
| { id: string; ok: true; result: unknown }
| { id: string; ok: false; error: { code: string; message: string; title?: string; details?: string; actionLabel?: string; kind?: string; refusalCode?: string } };
/** `CustomEvent("cua:event").detail`. */
export interface WebkitEventDetail {
event: WebkitEventName | (string & {});
payload?: unknown;
}
export function isWebkitResponse(m: unknown): m is WebkitResponse {
return typeof m === "object" && m !== null && typeof (m as { ok?: unknown }).ok === "boolean";
}
/* ---- What the host's read methods return (the parts the bridge reads) ---- */
/** `model::Space` as Swift encodes it (`AppSpace`). */
export interface WkSpace {
id: string;
name: string;
os: "macos" | "windows" | "linux" | "unknown";
status: "local" | "running" | "approval" | "suspended" | "provisioning" | "deleting";
detail: string;
lastUsedAt: number;
startedAt?: number | null;
provider?: "local" | "direct" | "relay" | null;
sdk?: { features: string[]; spacesdVersion: string; reachable: boolean; error?: string | null } | null;
osName?: string | null;
osPrettyName?: string | null;
image?: string | null;
imageDigest?: string | null;
kind?: "container" | "vm" | "microvm" | null;
arch?: string | null;
host?: string | null;
hostName?: string | null;
power?: { control: "suspend" | "stop" | (string & {}); off: boolean; turningOn?: boolean | null; error?: string | null; stopReason?: string | null } | null;
cloud?: string | null;
cloudPlace?: string | null;
cloudDelete?: string | null;
/** Whose it is and what you may do with it (`model::SpaceAccess`). */
access?: import("./contracts/spaces").SpaceAccess | null;
/** A create the app runs (its own pending row): its progress, or why it failed. */
progress?: import("./contracts/spaces").SpaceProgress | null;
}
/** `spaces.list`, `spaces.refresh`, `spaces.select`, `spaces.setPower`, `spaces.delete`. */
export interface WkSpaces {
loaded: boolean;
selectedId: string | null;
spaces: { space: WkSpace; deleting: boolean }[];
/** The last registry read failed (`AppModel.rosterError`): the rows are
* the ones listed before, and this says so. Null when it worked. */
rosterError?: string | null;
/** Another app keeps its own daemon running and this app uses it
* (`AppModel.daemonNotice`): a line above every page. Null otherwise. */
daemonNotice?: string | null;
/** Some of the account's computers have not answered the last read yet
* (`Spaces.list_known`): the list may grow, and is not "no Spaces".
* Absent from a host that lists complete lists only. */
incomplete?: boolean;
/** How many computers are still being reached (0 when unknown). */
reaching?: number;
/** Your other computers' rows are the last known ones (kept across a
* daemon restart), not yet confirmed by the relay. */
stale?: boolean;
/** Spaces your other computers are creating now (CUA-2349). Absent from
* a host that does not read them. */
creatingElsewhere?: import("./contracts/spaces").CreatingElsewhere[];
}
/** `machines.list`: the sidebar and the account's devices. */
export interface WkMachines {
/** The sidebar's "This machine" row (`spaces::sidebar::SidebarRow`):
* `detail` is the host summary, `status` is `local` while it is set up
* and sharing. */
thisMachine?: { status: string; statusText: string; detail: string } | null;
/** The account's devices (`devices::DevicesView`, the parts read here). */
devices: {
rows: { id: string; name: string; platform: string; current: boolean; detail?: string; lastSeen?: number | null }[];
} | null;
signedIn: boolean;
/** This Mac's host status, as `host.status` answers it (null until the
* host answered). The Machines page shows the core's "This machine" panel. */
host?: WkHostState | null;
/** What each machine on the relay reported as its hostname, by machine
* id (to list a machine and its enrolled device once). */
hostnames?: Record<string, string> | null;
/** Whether the relay sees each of the account's machines connected now,
* by machine id (the devices snapshot's machines). */
presence?: Record<string, boolean> | null;
/** Each device's state (`enrolled`, `pending`, `expired`, `revoked`), by id. */
deviceStates?: Record<string, string> | null;
/** Signed in, but this Mac cannot open the account's machines (never
* enrolled, waiting, expired, revoked): `DevicesModel.accessNotice`. */
accessNotice?: MachineAccessNotice | null;
/** The page's rows as the core lists them (`machines::page_rows`, what
* the SwiftUI Machines page shows); absent from an older host. */
rows?: MachinePageRow[] | null;
/** The Machines page as the core draws it (`machines_view::view`, what
* the SwiftUI Machines page shows); absent from an older host. */
view?: MachinesView | null;
}
/** `session.get`, `session.signIn`, `session.signOut`. */
export interface WkSession {
identity: string | null;
signedIn: boolean;
cloudConfigured: boolean;
/** `idle`, `starting`, `{type: "waiting", userCode, opened}`, `{type: "failed", reason, message, detail}`. */
signIn: string | { type: string; userCode?: string | null; opened?: boolean; reason?: string; message?: string; detail?: string | null };
/** The page a waiting sign-in finishes on (null otherwise), to show and copy. */
signInUrl?: string | null;
}
export interface WkSettingsRow {
id: string;
kind: string;
label: string;
enabled: boolean;
help?: string | null;
/** A text row's value (the Keyvault's protection facts). */
value?: string | null;
options: { id: string; label: string; active: boolean }[];
}
/** `settings.get`, `settings.choose`, `settings.press`: the core's Settings page. */
export interface WkSettings {
page: { title: string; sections: { id: string; rows: WkSettingsRow[] }[] };
/** `AppSettings.updateChannel` (`stable` or `nightly`; `beta` from an older host); null while the build
* has no updater. Set with `settings.choose {row: "update-channel"}`. */
updateChannel?: string | null;
/** The global shortcut the host registered; absent or null: none. */
globalShortcut?: { label: string; registered: boolean } | null;
/** The host's account app (`app_account_app_url`); absent or null: none named. */
accountUrl?: string | null;
/** The CLI the app installs (its install plan's file name) and whether it
* is on this computer; absent or null: not known. */
cli?: { name: string; installed: boolean } | null;
/** `AppSettings.tips`; absent: an older host that keeps none. Saved with `settings.update`. */
tips?: { off: boolean; done: string[] };
/** `AppSettings.notchPinned`: the Spaces and desktops pinned to the notch, in pin order; absent: an older host. Saved with `settings.update`. */
notchPinned?: string[];
/** `AppSettings.agentMenu*`: which coding apps the agent menu shows; absent: an older host. Saved with `settings.update`. */
agentMenu?: { shown: string[]; hidden: string[]; seen: string[] };
/** Settings, Advanced's runtimes as the host read them (`runtimes::RuntimesInput`); absent: not read. */
runtimes?: RuntimesInput | null;
}
/** `keyvault.*`: the core's page views, plus the overview (camelCase records). */
export interface WkKeyvault {
availability: string;
overview?: Record<string, unknown> | null;
/** Import ids of the copies hidden from the notch. */
dismissed?: string[];
busy: boolean;
error: string | null;
}
/** `host.status`: `HostModel.state` (the core's flattened `HostStatus`) plus
* the relay machine id; null until the host answered. */
export interface WkHostState {
configured: boolean;
mode?: string | null;
relayUrl?: string | null;
directUrl?: string | null;
machineId?: string | null;
name?: string | null;
sharing: boolean;
serviceInstalled: boolean;
serviceRunning: boolean;
serviceKind: string;
online?: boolean | null;
clients: { id: string; email?: string | null; name?: string | null; streams?: number | null }[];
permissions: { id: string; title: string; settingsUrl?: string | null; instructions?: string | null; granted: boolean }[];
error?: string | null;
shareDesktop: boolean;
provideSpaces: boolean;
maxSpaces: number;
maxMacosVms?: number | null;
maxMemoryGb?: number | null;
maxDiskGb?: number | null;
maxRunMinutes?: number | null;
usedMemoryGb?: number | null;
usedDiskGb?: number | null;
totalMemoryGb?: number | null;
totalDiskGb?: number | null;
recentAccess?: { atMs: number; via: string; who: string; what: string }[] | null;
accessLogError?: string | null;
providedSpaces?: import("./contracts/host").HostProvidedSpace[] | null;
spacesAudit?: import("./contracts/host").HostSpacesAudit[] | null;
spacesAuditError?: string | null;
pausedSignedOut?: boolean | null;
owner?: string | null;
ownerEmail?: string | null;
/** Who is signed in, as `HostModel` last checked it. */
account?: { id?: string | null; email?: string | null; display?: string | null } | null;
/** `HostModel.progress`: what a running setup or Sign In waits for. */
progress?: string | null;
/** The app's name as System Settings lists it ("Cua Spaces Local"). */
appName?: string | null;
}