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.

17.9 KB
Raw Blame
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.

import type { SpaceRow } from "../model/spaces";
import type { Location, Runtime, SpaceKind } from "../model/types";
import { hasTauri } from "./bridge";
import type { LocalStatus } from "./local";

/**
 * Typed wrapper over the shell's Spaces commands. The shell is a thin layer over the cua
 * SDK (`cua-spaces` + `cua daemon`): every location (this Mac, your machines
 * and clouds, Spaces added by address) comes back through one registry.
 *
 * Outside Tauri (browser dev, Vitest) the fallback reports "not native" so the
 * portal keeps its synthetic fixtures and no network is ever touched.
 */

/**
 * What starting a sign-in returns. `browser`: finish in the tab that just
 * opened. `device`: enter `userCode` at `verificationUri`.
 */
export interface SignInStart {
  method?: "browser" | "device";
  userCode?: string;
  verificationUri: string;
}

/** Who is signed in to Cua (the shell reads its local session). */
export interface AccountStatus {
  /** A user is signed in. */
  configured: boolean;
  authMode: "user" | "none";
  /** Signed-in user identity (email/subject), when a user session is active. */
  identity?: string;
}

/** The local `cua daemon` the app shares Spaces with (CLI / MCP clients). */
export interface DaemonStatus {
  connected: boolean;
  version?: string;
  socketPath?: string;
  loopbackUrl?: string;
  error?: string;
}

/** What the viewer page needs to know about its Space. */
export interface ViewerWindowRequest {
  id: string;
  name: string;
  /** Who is driving the Space (PiP badge); informational only. */
  controller?: "agent" | "you";
  os?: string;
}

export interface ViewerConfig {
  view: "space" | "pip" | "windows";
  space: ViewerWindowRequest;
  /** Most recent cached screenshot (`data:` URL) for the blurred connecting
   * background (item D); absent when nothing is cached yet. */
  lastScreenshot?: string;
  /** An in-flight teleport transfer overlaying this Space window (item B). */
  transfer?: {
    phase: "active" | "error";
    appName: string;
    message?: string;
    sentBytes?: number;
    totalBytes?: number;
  };
  /** The single remote window this stream window is dedicated to (the
   * `winone-*` per-window path). When present the viewer runs in SINGLE mode.
   * `mediaUrl` (MCP-driven `stream_space_window`) is a ready media ticket URL
   * to attach to instead of opening a session itself. */
  targetWindow?: {
    id: string;
    appName: string;
    title: string;
    replica?: boolean;
    mediaUrl?: string;
    mediaSessionId?: string;
  };
}

/**
 * `create_space` options, the SDK's placement model: where (`on`), what
 * (`kind`) and which engine (`runtime`). Omitted, `on` is the default
 * location (Settings, `cua config set default.on`), `kind` and `runtime`
 * are `auto`. The SDK validates the combination; its error lists the valid
 * values and is user-facing.
 */
export interface SpaceCreateConfig {
  image?: string;
  /** `local`, or a connected cloud's word (`aws`, `gcp`, `hetzner`, `modal`). */
  on?: Location | string;
  kind?: SpaceKind | "auto";
  runtime?: Runtime;
  name?: string;
  /** This Mac only. */
  cpus?: number;
  /** This Mac only. */
  memoryMb?: number;
  /** This Mac's VMs only: grow the disk to this many GB. */
  diskGb?: number;
  /** Whether the image runs cua-spacesd; omitted, the SDK decides. */
  spacesd?: boolean;
  /** Return a reachable registered Space in that location instead. */
  reuse?: boolean;
  /** A GPU option of the runtime (`paravirtual`, from `gpuSupport`). */
  gpu?: string;
}

/** Where new Spaces go by default (`default.on`), and where that came from. */
export interface DefaultLocation {
  /** `local`, or a connected cloud's word (`aws`). */
  value: Location | string;
  /** `env` (CUA_DEFAULT_ON, read-only here), `config` or `default`. */
  source: "env" | "config" | "default";
  /** The environment variable, when `source` is `env`. */
  env?: string;
  /** The config file (`$CUA_HOME/config.toml`). */
  path: string;
}

/** Used off the native shell, and when the shell cannot read the setting. */
export const BUILTIN_DEFAULT_LOCATION: DefaultLocation = {
  value: "local",
  source: "default",
  path: "~/.cua/config.toml",
};

export type StreamTarget = { kind: "display"; displayId?: string } | { kind: "window"; windowId: string };

export interface StreamOpts {
  maxFps?: number;
  maxDimension?: number;
  audio?: boolean;
  codecs?: string[];
  /** Input policy. The shell defaults to `allow_activation`; the view-only
   * PiP passes `view_only`. Without an input-capable policy the driver
   * refuses InteractiveInput. */
  policy?: "view_only" | "background_only" | "allow_activation";
  /** Single-window mode that resizes the remote window (geometry control). */
  geometryControl?: boolean;
}

/** A minted media ticket (rcdp wire v2). The ticket is scoped to one session
 * and safe in a URL. */
export interface StreamTicketInfo {
  spaceId: string;
  mediaSessionId: string;
  wsUrl: string;
  ticket: string;
  ticketExpiresAt?: string;
  codec: "h264" | "bgra" | "png";
  wireVersion: number;
  frameSize: [number, number];
  via: "direct" | "daemon";
  audio: boolean;
}

/** Whether this Mac is currently sharing its network to a Space, and which. */
export interface HotspotStatus {
  active: boolean;
  spaceId: string | null;
}

/** `spaces:create-progress`: what a create is doing. */
export interface CreateProgress {
  pendingId: string;
  /** `preparing`, `pulling`, `creating`, `booting`, `waiting_for_services`,
   * `connecting` or `ready`. */
  phase: string;
  /** 0 to 1 through the phase, when its size is known. */
  fraction?: number | null;
  detail: string;
  /** An image download's bytes so far, of how many, and how fast
   * (smoothed), when the step counts them. */
  bytesDone?: number | null;
  bytesTotal?: number | null;
  bytesPerSecond?: number | null;
  /** The id the Space will have (`local:<name>`), when known. */
  space?: string | null;
}

/** `cancel_create`: what a cancel found and did (the SDK's `CancelOutcome`). */
/** What turning a Space off or on did (the SDK's `SpacePower`). */
export interface SpacePowerReport {
  space: string;
  /** `running`, `suspended` or `stopped`: the state it is in now. */
  state: string;
  /** How it turns off: `suspend` or `stop`. */
  power: string;
  /** For people. */
  message: string;
}

export interface CancelOutcome {
  /** The Space id the create had, when known. */
  id: string;
  state: "cancelled" | "not_creating" | "already_created";
  /** For people: what was removed and what stays. */
  message: string;
}

/** A runtime's GPU option, as the New Space wizard offers it (the app
 * core's `GpuChoice`). */
export interface GpuChoice {
  runtime: string;
  id: string;
  label: string;
  experimental: boolean;
  supported: boolean;
  reason?: string | null;
  learnMore?: string | null;
}

export interface SpacesBridge {
  readonly isNative: boolean;
  status(): Promise<AccountStatus>;
  daemonStatus(): Promise<DaemonStatus>;
  ensureDaemon(): Promise<DaemonStatus>;
  localStatus(): Promise<LocalStatus>;
  /** The SDK registry, every provider. */
  listSpaces(): Promise<SpaceRow[]>;
  /** One registered Space, connected (cheaper than `listSpaces` for a viewer). */
  spaceInfo?(spaceId: string): Promise<SpaceRow>;
  /** "Add Space by address": `host:port` or `http(s)://host:port`. */
  addSpace(url: string, token?: string, name?: string): Promise<SpaceRow>;
  /** Creates a Space (in the default location unless `config.on` says);
   * resolves once its spacesd answers. With `pendingId`, its progress
   * arrives on `onCreateProgress` under that id. */
  createSpace(config?: SpaceCreateConfig, pendingId?: string): Promise<SpaceRow>;
  /** Cancels the create started with `pendingId`: it stops and what it
   * made is removed; resolves once that is done. The create then rejects
   * with an error starting `cancelled: `. */
  cancelCreate?(pendingId: string): Promise<CancelOutcome>;
  /** The GPU option of each local runtime that has one (the wizard's
   * GPU row). */
  gpuSupport?(): Promise<GpuChoice[]>;
  /** Your machines that provide Spaces (the wizard's Run on menu). */
  listHosts?(): Promise<import("../components/desktop/NewSpaceWizard").SpaceHost[]>;
  /** This Mac's CPU architecture (`aarch64`, `x86_64`). */
  hostArch?(): Promise<string>;
  /** The SDK's create progress (pulling, booting, waiting for cua-spacesd,
   * connecting) of creates started with a pending id. */
  onCreateProgress?(handler: (progress: CreateProgress) => void): Promise<() => void>;
  /** Deletes a created Space's sandbox; a Space added by address is only
   * forgotten. */
  deleteSpace(spaceId: string): Promise<string>;
  /** Turns a Space off (`on` false: suspended or stopped, as its provider
   * can) or back on: the power button next to Delete. */
  setSpacePower?(spaceId: string, on: boolean): Promise<SpacePowerReport>;
  /** Forget only (the machine is untouched). */
  removeSpace(spaceId: string): Promise<void>;
  /** Where new Spaces go by default. */
  defaultLocation(): Promise<DefaultLocation>;
  /** Fires after add/create/delete/remove anywhere in the app. */
  onSpacesChanged(handler: () => void): Promise<() => void>;
  /** Returns a `data:image/…;base64,…` URL. */
  screenshot(spaceId: string, maxDimension?: number): Promise<string>;
  openStream(spaceId: string, target: StreamTarget, options?: StreamOpts): Promise<StreamTicketInfo>;
  closeStream(spaceId: string, mediaSessionId: string): Promise<void>;
  /**
   * Start sharing THIS Mac's network with `spaceId` (the Mac becomes the
   * egress "hotspot"). Replaces any previous hotspot.
   */
  startHotspot(spaceId: string): Promise<HotspotStatus>;
  /** Stop sharing the network. Idempotent. */
  stopHotspot(): Promise<HotspotStatus>;
  /** Current hotspot state (for reconciling the notch indicator on launch). */
  hotspotStatus(): Promise<HotspotStatus>;
  /** Fires whenever the hotspot turns on/off (including if the tunnel drops). */
  onHotspotChanged(handler: (status: HotspotStatus) => void): Promise<() => void>;
  viewerConfig(): Promise<ViewerConfig>;
  openSpaceWindow(space: ViewerWindowRequest): Promise<void>;
  /** Open (or re-target) the teleport picker window for this Space. */
  openTeleportPicker(space: ViewerWindowRequest): Promise<void>;
  /** Open the teleport picker PRE-TARGETED to a coding-agent provider. */
  launchAgent(space: ViewerWindowRequest, appId: string, appName: string): Promise<void>;
  /**
   * Install a coding agent (cua-agents harness id) in the Space and open its
   * interactive CLI in a terminal on the Space's desktop. Resolves once the
   * terminal is launched; the user signs in inside it.
   */
  launchAgentTerminal(space: ViewerWindowRequest, harness: string): Promise<void>;
  pinSpacePip(space: ViewerWindowRequest): Promise<void>;
  unpinSpacePip(spaceId: string): Promise<void>;
  /** Size the PiP window to the remote desktop's aspect ratio and lock it. */
  setPipAspect(spaceId: string, width: number, height: number): Promise<void>;
  /** Toggle per-window streaming (each remote window as its own native window). */
  setWindowStream(space: ViewerWindowRequest, enabled: boolean): Promise<void>;
  /** Resize the CURRENT stream window's inner area (single mode). */
  resizeStreamWindow(width: number, height: number): Promise<void>;
  /** Open a URL in the user's default browser. */
  openExternal(url: string): Promise<void>;
  /**
   * "Sign in to Cua" through the SDK: browser sign-in (PKCE, loopback
   * redirect), else a device code. The session is shared with the cua CLI.
   */
  beginSignIn(): Promise<SignInStart>;
  /** Clear the signed-in user session. */
  signOut(): Promise<void>;
  onSignedIn(handler: (identity?: string) => void): Promise<() => void>;
  onSignInFailed(handler: (reason: string) => void): Promise<() => void>;
  onSignedOut(handler: () => void): Promise<() => void>;
}

const NOT_NATIVE = "Spaces commands need the Tauri shell";

export function createFallbackSpacesBridge(): SpacesBridge {
  const unavailable = () => Promise.reject(new Error(NOT_NATIVE));
  const noopUnsub = async () => () => {};
  return {
    isNative: false,
    status: async () => ({ configured: false, authMode: "none" }),
    daemonStatus: async () => ({ connected: false, error: "not running in the app" }),
    ensureDaemon: unavailable,
    localStatus: async () => ({
      available: false,
      backends: [],
      containerImage: "",
      macosImage: null,
      error: "not running in the app",
    }),
    listSpaces: async () => [],
    addSpace: unavailable,
    createSpace: unavailable,
    deleteSpace: unavailable,
    removeSpace: unavailable,
    defaultLocation: async () => BUILTIN_DEFAULT_LOCATION,
    onSpacesChanged: noopUnsub,
    screenshot: unavailable,
    openStream: unavailable,
    closeStream: async () => {},
    startHotspot: unavailable,
    stopHotspot: async () => ({ active: false, spaceId: null }),
    hotspotStatus: async () => ({ active: false, spaceId: null }),
    onHotspotChanged: noopUnsub,
    viewerConfig: unavailable,
    openSpaceWindow: async () => {},
    openTeleportPicker: async () => {},
    launchAgent: async () => {},
    launchAgentTerminal: unavailable,
    pinSpacePip: async () => {},
    unpinSpacePip: async () => {},
    setPipAspect: async () => {},
    setWindowStream: async () => {},
    resizeStreamWindow: async () => {},
    openExternal: async () => {},
    beginSignIn: unavailable,
    signOut: async () => {},
    onSignedIn: noopUnsub,
    onSignInFailed: noopUnsub,
    onSignedOut: noopUnsub,
  };
}

export function createTauriSpacesBridge(): SpacesBridge {
  // Imported lazily so the browser/test bundle never touches Tauri globals.
  const core = import("@tauri-apps/api/core");
  const event = import("@tauri-apps/api/event");
  const invoke = async <T>(command: string, args?: Record<string, unknown>) =>
    (await core).invoke<T>(command, args);
  const on = async <T>(name: string, handler: (payload: T) => void) => {
    const { listen } = await event;
    return listen<T>(name, (e) => handler(e.payload));
  };
  return {
    isNative: true,
    status: () => invoke<AccountStatus>("account_status"),
    daemonStatus: () => invoke<DaemonStatus>("daemon_status"),
    ensureDaemon: () => invoke<DaemonStatus>("ensure_daemon"),
    localStatus: () => invoke<LocalStatus>("local_status"),
    listSpaces: () => invoke<SpaceRow[]>("list_spaces"),
    spaceInfo: (spaceId) => invoke<SpaceRow>("space_info", { spaceId }),
    addSpace: (url, token, name) =>
      invoke<SpaceRow>("add_space", { url, token: token || null, name: name || null }),
    createSpace: (config, pendingId) =>
      invoke<SpaceRow>("create_space", { config: config ?? null, pendingId: pendingId ?? null }),
    onCreateProgress: (handler) => on<CreateProgress>("spaces:create-progress", handler),
    cancelCreate: (pendingId) => invoke<CancelOutcome>("cancel_create", { pendingId }),
    gpuSupport: () => invoke<GpuChoice[]>("gpu_support"),
    listHosts: () => invoke<import("../components/desktop/NewSpaceWizard").SpaceHost[]>("list_hosts"),
    hostArch: () => invoke<string>("host_arch"),
    deleteSpace: (spaceId) => invoke<string>("delete_space", { spaceId }),
    setSpacePower: (spaceId, on) => invoke<SpacePowerReport>("set_space_power", { spaceId, on }),
    removeSpace: (spaceId) => invoke<void>("remove_space", { spaceId }),
    defaultLocation: () => invoke<DefaultLocation>("get_default_location"),
    onSpacesChanged: (handler) => on<unknown>("spaces:changed", () => handler()),
    screenshot: (spaceId, maxDimension) =>
      invoke<string>("space_screenshot", { spaceId, maxDimension: maxDimension ?? null }),
    openStream: (spaceId, target, options) =>
      invoke<StreamTicketInfo>("open_space_stream", { spaceId, target, options: options ?? null }),
    closeStream: (spaceId, mediaSessionId) =>
      invoke<void>("close_space_stream", { spaceId, mediaSessionId }),
    startHotspot: (spaceId) => invoke<HotspotStatus>("start_hotspot", { spaceId }),
    stopHotspot: () => invoke<HotspotStatus>("stop_hotspot"),
    hotspotStatus: () => invoke<HotspotStatus>("hotspot_status"),
    onHotspotChanged: (handler) =>
      on<HotspotStatus>("hotspot:changed", (p) => handler(p ?? { active: false, spaceId: null })),
    viewerConfig: () => invoke<ViewerConfig>("viewer_config"),
    openSpaceWindow: (space) => invoke<void>("open_space_window", { space }),
    // `TeleportPickerRequest` is camelCase: `spaceId`/`spaceName`/`app`.
    openTeleportPicker: (space) =>
      invoke<void>("open_teleport_picker", {
        request: { spaceId: space.id, spaceName: space.name },
      }),
    launchAgent: (space, appId, appName) =>
      invoke<void>("open_teleport_picker", {
        request: {
          spaceId: space.id,
          spaceName: space.name,
          app: { id: appId, name: appName },
        },
      }),
    launchAgentTerminal: (space, harness) =>
      invoke<void>("launch_agent_terminal", { spaceId: space.id, harness }),
    pinSpacePip: (space) => invoke<void>("pin_space_pip", { space }),
    unpinSpacePip: (spaceId) => invoke<void>("unpin_space_pip", { spaceId }),
    setPipAspect: (spaceId, width, height) =>
      invoke<void>("set_pip_aspect", { spaceId, width, height }),
    setWindowStream: (space, enabled) => invoke<void>("set_window_stream", { space, enabled }),
    resizeStreamWindow: (width, height) =>
      invoke<void>("resize_stream_window", { width, height }),
    openExternal: (url) => invoke<void>("open_external", { url }),
    beginSignIn: () => invoke<SignInStart>("begin_sign_in"),
    signOut: () => invoke<void>("sign_out"),
    onSignedIn: (handler) =>
      on<{ identity?: string } | null>("auth:signed-in", (p) => handler(p?.identity)),
    onSignInFailed: (handler) =>
      on<{ reason?: string } | null>("auth:sign-in-failed", (p) =>
        handler(p?.reason ?? "Sign-in failed"),
      ),
    onSignedOut: (handler) => on<unknown>("auth:signed-out", () => handler()),
  };
}

export function createSpacesBridge(): SpacesBridge {
  return hasTauri() ? createTauriSpacesBridge() : createFallbackSpacesBridge();
}