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.

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

import { hasTauri } from "./bridge";

/**
 * "This machine" as a host: the shell's `cua-host` commands. Host setup installs cua-spacesd as a
 * per-OS service that joins the cua.ai relay (default) or listens on a direct
 * `ip:port` (Advanced). Outside Tauri the fallback reports "not configured"
 * and treats onboarding as done, so browser dev and tests never see the
 * first-run screen unless they inject a bridge.
 */

export type HostModeName = "relay" | "direct";
export type OnboardingMode = "client" | "host";

export interface ServiceState {
  installed: boolean;
  running: boolean;
  kind: "systemd" | "launchd" | "windows-task" | "process" | string;
  detail?: string;
}

/** Someone connected to this machine right now (relay presence). */
export interface ConnectedClient {
  id: string;
  email?: string;
  name?: string;
  streams?: number;
  since?: number;
}

/** An OS permission the host needs and the user must grant themselves. */
export interface PermissionHint {
  /** e.g. "screen-recording", "accessibility". */
  id: string;
  label: string;
  /** What to turn on there. */
  instructions?: string;
  /** Settings pane URL (opened only when the user clicks). */
  settingsUrl?: string;
  granted?: boolean;
}

export interface HostStatus {
  configured: boolean;
  mode?: HostModeName | null;
  relayUrl?: string | null;
  directUrl?: string | null;
  machineId?: string | null;
  name?: string | null;
  sharing: boolean;
  service: ServiceState;
  online?: boolean | null;
  clients: ConnectedClient[];
  permissions: PermissionHint[];
  error?: string | null;
  /** Who reached this machine recently, newest first (the access log). */
  recentAccess?: AccessRecord[];
  /** Set when the access log does not verify. */
  accessLogError?: string | null;
  /** This machine's own desktop is a Space (default on). */
  shareDesktop?: boolean;
  /** This machine creates Spaces for your other devices. */
  provideSpaces?: boolean;
  /** Provided Spaces at once (0: no limit). */
  maxSpaces?: number;
  /** macOS VMs at once (at most two). */
  maxMacosVms?: number;
  /** The Spaces this machine provides now. */
  providedSpaces?: ProvidedSpace[];
  /** Remote creates, deletes and refusals, and settings changes, newest first. */
  spacesAudit?: SpacesAuditRecord[];
  /** Set when the Spaces audit does not verify. */
  spacesAuditError?: string | null;
}

/** A Space this machine provides to one of your devices. */
export interface ProvidedSpace {
  relayMachine: string;
  localSpace: string;
  name: string;
  image: string;
  os: string;
  kind: string;
  createdBy: string;
  createdAtMs: number;
}

/** One line of the Spaces audit. */
export interface SpacesAuditRecord {
  atMs: number;
  action: string;
  who: string;
  space: string;
  detail: string;
}

/** A change to this machine's two settings (the core's `host.settingChange`). */
export interface HostSettingChange {
  shareDesktop?: boolean | null;
  provideSpaces?: boolean | null;
}

export interface AccessRecord {
  atMs: number;
  via: string;
  who: string;
  what: string;
}

export interface HostSetupRequest {
  mode: HostModeName;
  /** Relay URL; the shell defaults to https://relay.cua.ai. */
  relayUrl?: string;
  /** Direct `ip:port` (Advanced). */
  direct?: string;
  name?: string;
  allow?: string[];
  /** `desktop` (share this desktop) or `spare` (only run Spaces). */
  profile?: "desktop" | "spare" | null;
  shareDesktop?: boolean | null;
  provideSpaces?: boolean | null;
}

export interface OnboardingState {
  completed: boolean;
  mode?: OnboardingMode | null;
  /** Mode preselected by the installer (`--mode host|client` or MDM file). */
  installerMode?: OnboardingMode | null;
}

export interface HostBridge {
  readonly isNative: boolean;
  status(): Promise<HostStatus>;
  setup(request: HostSetupRequest): Promise<HostStatus>;
  stopSharing(): Promise<HostStatus>;
  startSharing(): Promise<HostStatus>;
  remove(): Promise<void>;
  /** Change what this machine shares (its desktop, Spaces for your devices). */
  configure(change: HostSettingChange): Promise<HostStatus>;
  onboardingState(): Promise<OnboardingState>;
  completeOnboarding(mode: OnboardingMode): Promise<void>;
  /** Open an OS settings pane (permission hints); only on a user click. */
  openSettings(url: string): Promise<void>;
}

export const DEFAULT_RELAY_URL = "https://relay.cua.ai";

export function unconfiguredStatus(error?: string): HostStatus {
  return {
    configured: false,
    sharing: false,
    service: { installed: false, running: false, kind: "process" },
    clients: [],
    permissions: [],
    error: error ?? null,
  };
}

export function createFallbackHostBridge(): HostBridge {
  const unavailable = () => Promise.reject(new Error("Host setup needs the Cua Spaces app"));
  return {
    isNative: false,
    status: async () => unconfiguredStatus(),
    setup: unavailable,
    stopSharing: unavailable,
    startSharing: unavailable,
    remove: unavailable,
    configure: unavailable,
    onboardingState: async () => ({ completed: true }),
    completeOnboarding: async () => {},
    openSettings: async () => {},
  };
}

export function createTauriHostBridge(): HostBridge {
  const core = import("@tauri-apps/api/core");
  const invoke = async <T>(command: string, args?: Record<string, unknown>) =>
    (await core).invoke<T>(command, args);
  return {
    isNative: true,
    status: () => invoke<HostStatus>("host_status"),
    setup: (request) => invoke<HostStatus>("host_setup", { request }),
    stopSharing: () => invoke<HostStatus>("host_stop_sharing"),
    startSharing: () => invoke<HostStatus>("host_start_sharing"),
    remove: () => invoke<void>("host_remove"),
    configure: (change) => invoke<HostStatus>("host_configure", { change }),
    onboardingState: () => invoke<OnboardingState>("onboarding_state"),
    completeOnboarding: (mode) => invoke<void>("complete_onboarding", { mode }),
    openSettings: (url) => invoke<void>("host_open_settings", { url }),
  };
}

export function createHostBridge(): HostBridge {
  return hasTauri() ? createTauriHostBridge() : createFallbackHostBridge();
}

/**
 * In-memory host for tests and design work: setup succeeds (or fails with
 * `failSetup`), sharing toggles, clients can be injected.
 */
export function createFakeHostBridge(
  options: {
    onboarding?: OnboardingState;
    status?: HostStatus;
    failSetup?: string;
    platform?: "macos" | "linux" | "windows";
  } = {},
): HostBridge & { calls: string[]; state: { status: HostStatus; onboarding: OnboardingState } } {
  const state = {
    status: options.status ?? unconfiguredStatus(),
    onboarding: options.onboarding ?? { completed: false },
  };
  const calls: string[] = [];
  return {
    isNative: true,
    calls,
    state,
    status: async () => state.status,
    setup: async (request) => {
      calls.push(`setup:${request.mode}:${request.mode === "direct" ? request.direct : request.relayUrl ?? DEFAULT_RELAY_URL}`);
      if (options.failSetup) throw new Error(options.failSetup);
      const spare = request.profile === "spare";
      state.status = {
        shareDesktop: request.shareDesktop ?? !spare,
        provideSpaces: request.provideSpaces ?? (request.mode !== "direct"),
        maxSpaces: 4,
        maxMacosVms: options.platform === "macos" ? 2 : 0,
        providedSpaces: [],
        spacesAudit: [],
        configured: true,
        mode: request.mode,
        relayUrl: request.mode === "relay" ? request.relayUrl ?? DEFAULT_RELAY_URL : null,
        directUrl: request.mode === "direct" ? `http://${request.direct}` : null,
        machineId: "0123abcd4567",
        name: request.name ?? "This computer",
        sharing: true,
        service: {
          installed: true,
          running: true,
          kind: options.platform === "macos" ? "launchd" : options.platform === "windows" ? "windows-task" : "systemd",
        },
        online: true,
        clients: [],
        permissions:
          options.platform === "macos"
            ? [
                {
                  id: "screen-recording",
                  label: "Screen Recording",
                  settingsUrl: "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture",
                },
                {
                  id: "accessibility",
                  label: "Accessibility",
                  settingsUrl: "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility",
                },
              ]
            : [],
      };
      return state.status;
    },
    stopSharing: async () => {
      calls.push("stop");
      state.status = { ...state.status, sharing: false, clients: [] };
      return state.status;
    },
    startSharing: async () => {
      calls.push("start");
      state.status = { ...state.status, sharing: true };
      return state.status;
    },
    remove: async () => {
      calls.push("remove");
      state.status = unconfiguredStatus();
    },
    configure: async (change) => {
      calls.push(`configure:${JSON.stringify(change)}`);
      state.status = {
        ...state.status,
        shareDesktop: change.shareDesktop ?? state.status.shareDesktop,
        provideSpaces: change.provideSpaces ?? state.status.provideSpaces,
      };
      return state.status;
    },
    onboardingState: async () => state.onboarding,
    completeOnboarding: async (mode) => {
      calls.push(`onboarding:${mode}`);
      state.onboarding = { ...state.onboarding, completed: true, mode };
    },
    openSettings: async (url) => {
      calls.push(`settings:${url}`);
    },
  };
}