connect-windows-vm

name	connect-windows-vm
description	Use when the user wants to RDP into a Windows GCE VM through IAP — open an existing saved connection, or set one up from scratch and launch the Microsoft 'Windows App' RDP client. Triggers on phrases like "RDP into <vm>", "open Windows VM", "connect to my Windows server".

Connect to a Windows GCE VM via IAP

Preconditions

1. Confirm auth: call auth_check. If authenticated is false, run auth_login (opens a browser; user must finish the OAuth flow).
2. Confirm the user has the macOS RDP client: call windows_app_check. If not installed, tell the user to install "Windows App" from the Mac App Store before continuing.

If the user already has a saved connection

1. connections_list → find the entry by displayName / instanceName.
2. tunnels_active → if a tunnel for that connection is already running, skip step 3.
3. tunnels_start_for_connection { connectionId } → wait for status running.
4. (Optional) windows_reset_password { connectionId, saveToKeychain: true, updateBookmark: true } — only when the user explicitly asks to rotate. Always confirm first — this invalidates the previous password instantly on the VM.
5. freerdp_launch { connectionId } if FreeRDP is installed (freerdp_check), otherwise windows_app_open and tell the user to click the "IAP Tunnels" group bookmark.

If no saved connection exists yet

1. projects_list { filter } to locate the GCP project.
2. vms_list { projectId, filter } to find the VM. Confirm isWindows: true.
3. connections_add with platform: "windows". Default remotePort: 3389. Use a clear displayName (e.g. "prod-bastion-01 (us-central1-a)").
4. Continue from step 2 of "saved connection".

Pitfalls

• Password rotation is destructive. Anyone who has the old password loses access immediately. Never rotate without explicit user confirmation.
• The Windows guest agent reset takes ~30–60s; surface that to the user instead of looking like the call hangs.
• tunnels_start_* may report port X is in use by another tunnel. Suggested alternative: Y — call tunnels_free_port and either reuse Y or update the connection's stored port via the desktop UI.