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
import Darwin
import Foundation
enum TelemetryTransport: String, Sendable {
case cli
case http
case mcpStdio = "mcp_stdio"
}
enum TelemetryErrorClass: String, Sendable {
case none
case invalidParams = "invalid_params"
case notFound = "not_found"
case conflict
case permissionDenied = "permission_denied"
case unavailable
case transportError = "transport_error"
case operationError = "operation_error"
case internalError = "internal_error"
case unknownTool = "unknown_tool"
}
/// Pseudonymous, content-free product telemetry for Lume.
///
/// Telemetry is enabled by default, can be persistently disabled through
/// `lume config telemetry disable`, and can be overridden for the current
/// process with `LUME_TELEMETRY_ENABLED`. The environment always has highest
/// precedence. Installation and release events obey the same consent decision
/// as routine usage events.
final class TelemetryClient: @unchecked Sendable {
private enum Constants {
static let apiKey = "phc_eSkLnbLxsnYFaXksif1ksbrNzYlJShr35miFLDppF14"
static let captureURL = "https://eu.i.posthog.com/capture/"
static let telemetryIdFileName = ".telemetry_id"
static let installationRecordedFileName = ".installation_recorded"
static let releaseRecordedDirectoryName = ".telemetry_releases"
static let lifecycleRetryAfterFileName = ".telemetry_retry_after"
static let lifecycleLockFileName = ".telemetry_lifecycle.lock"
static let envTelemetryEnabled = "LUME_TELEMETRY_ENABLED"
static let envTelemetryDebug = "LUME_TELEMETRY_DEBUG"
static let envTelemetrySynthetic = "LUME_TELEMETRY_SYNTHETIC"
static let envInstallChannel = "LUME_INSTALL_CHANNEL"
static let requestTimeout: TimeInterval = 3
static let flushTimeout: TimeInterval = 1.5
static let lifecycleRetryBackoff: TimeInterval = 15 * 60
static let schemaVersion = 3
static let routineEventLimitPerHour = 1_000
static let routineEventWindow: TimeInterval = 60 * 60
static let processSessionId = UUID().uuidString
static let allowedInstallChannels: Swift.Set<String> = [
"install_script", "update_apply", "first_run",
]
}
struct Status: Sendable {
let enabled: Bool
let source: String
let persistedEnabled: Bool
let installationIdPresent: Bool
}
private struct InstallationIdentity {
let value: String
let persisted: Bool
}
typealias Poster = @Sendable (URLRequest) async -> Bool
static let shared = TelemetryClient()
private var installationIdentity: InstallationIdentity?
private let urlSession: URLSession
private let homeDirectory: URL
private let poster: Poster?
private let preferenceProvider: @Sendable () -> Bool
private let identityLock = NSLock()
private let rateLimitLock = NSLock()
private var rateLimitWindowStarted = Date()
private var rateLimitCaptured = 0
private var rateLimitCapturedValueEvent = false
private let pendingRequests = DispatchGroup()
init(
settingsManager: SettingsManager = .shared,
urlSession: URLSession? = nil,
homeDirectory: URL? = nil,
poster: Poster? = nil,
preferenceProvider: (@Sendable () -> Bool)? = nil
) {
self.homeDirectory = homeDirectory ?? LumeLayout.current.homeDir
self.poster = poster
self.preferenceProvider =
preferenceProvider ?? { settingsManager.getSettings().telemetryEnabled }
if let urlSession {
self.urlSession = urlSession
} else {
let config = URLSessionConfiguration.ephemeral
config.timeoutIntervalForRequest = Constants.requestTimeout
config.timeoutIntervalForResource = Constants.requestTimeout
self.urlSession = URLSession(configuration: config)
}
}
// MARK: - Public API
/// Record a routine event without blocking the command. Only fixed,
/// typed properties survive `sanitizeProperties`; strings originating
/// from image names, VM names, paths, prompts, or arguments are dropped.
func record(event: String, properties: [String: Any] = [:]) {
guard TelemetryEvent.allowed.contains(event), isEnabled(),
shouldCaptureRoutineEvent(event: event),
let request = makeRequest(event: event, properties: properties)
else {
return
}
pendingRequests.enter()
Task.detached { [self] in
_ = await send(request: request, event: event)
pendingRequests.leave()
}
}
func recordOperationCompleted(
operation: String,
transport: TelemetryTransport,
success: Bool,
errorClass: TelemetryErrorClass,
elapsed: TimeInterval,
guestOS: String? = nil,
phase: String = "completed"
) {
var properties: [String: Any] = [
"operation": Self.normalizedOperation(operation),
"transport": transport.rawValue,
"success": success,
"error_class": success ? TelemetryErrorClass.none.rawValue : errorClass.rawValue,
"duration_bucket": Self.durationBucket(elapsed),
"phase": phase == "accepted" ? "accepted" : "completed",
]
if let guestOS {
properties["guest_os"] = Self.normalizedGuestOS(guestOS)
}
record(event: TelemetryEvent.operationCompleted, properties: properties)
}
func recordMCPToolCompleted(
toolName: String,
success: Bool,
errorClass: TelemetryErrorClass,
elapsed: TimeInterval
) {
record(
event: TelemetryEvent.mcpToolCompleted,
properties: [
"tool_name": Self.normalizedMCPTool(toolName),
"operation": Self.normalizedMCPToolOperation(toolName),
"transport": TelemetryTransport.mcpStdio.rawValue,
"success": success,
"error_class": success ? TelemetryErrorClass.none.rawValue : errorClass.rawValue,
"duration_bucket": Self.durationBucket(elapsed),
])
}
func recordMCPSessionStarted() {
record(
event: TelemetryEvent.mcpSessionStarted,
properties: [
"transport": TelemetryTransport.mcpStdio.rawValue,
"protocol": "mcp",
])
}
func recordVMStarted(transport: TelemetryTransport, guestOS: String) {
record(
event: TelemetryEvent.vmStarted,
properties: [
"transport": transport.rawValue,
"guest_os": Self.normalizedGuestOS(guestOS),
"success": true,
])
}
func recordProvisioningStarted(
transport: TelemetryTransport, guestOS: String, asynchronous: Bool
) {
record(
event: TelemetryEvent.provisioningStarted,
properties: [
"transport": transport.rawValue,
"guest_os": Self.normalizedGuestOS(guestOS),
"asynchronous": asynchronous,
])
}
func recordProvisioningCompleted(
transport: TelemetryTransport,
guestOS: String,
asynchronous: Bool,
success: Bool,
errorClass: TelemetryErrorClass,
elapsed: TimeInterval
) {
record(
event: TelemetryEvent.provisioningCompleted,
properties: [
"transport": transport.rawValue,
"guest_os": Self.normalizedGuestOS(guestOS),
"asynchronous": asynchronous,
"success": success,
"error_class": success ? TelemetryErrorClass.none.rawValue : errorClass.rawValue,
"duration_bucket": Self.provisioningDurationBucket(elapsed),
])
}
func recordUpdateChecked(
source: String, outcome: String, targetVersion: String?, cacheHit: Bool
) {
var properties: [String: Any] = [
"source": Self.normalizedUpdateSource(source),
"outcome": Self.normalizedUpdateCheckOutcome(outcome),
"cache_hit": cacheHit,
"transport": source == "mcp"
? TelemetryTransport.mcpStdio.rawValue : TelemetryTransport.cli.rawValue,
]
if let targetVersion = Self.strictReleaseVersion(targetVersion) {
properties["target_version"] = targetVersion
}
record(event: TelemetryEvent.updateChecked, properties: properties)
}
func recordUpdateApplyStarted(targetVersion: String) {
var properties: [String: Any] = [
"transport": TelemetryTransport.cli.rawValue,
"daemon_was_running": false,
]
if let version = Self.strictReleaseVersion(targetVersion) {
properties["target_version"] = version
}
record(event: TelemetryEvent.updateApplyStarted, properties: properties)
}
func recordUpdateApplyCompleted(
targetVersion: String?, success: Bool, failureClass: String, elapsed: TimeInterval
) {
var properties: [String: Any] = [
"transport": TelemetryTransport.cli.rawValue,
"outcome": success ? "success" : "failed",
"failure_class": success ? "none" : Self.normalizedUpdateFailureClass(failureClass),
"daemon_was_running": false,
"duration_bucket": Self.durationBucket(elapsed),
]
if let version = Self.strictReleaseVersion(targetVersion) {
properties["target_version"] = version
}
record(event: TelemetryEvent.updateApplyCompleted, properties: properties)
}
/// Record the legacy installation event once and the release event once
/// per Lume version. Both events honor consent. Each marker is written
/// only after its corresponding request receives HTTP 2xx.
func recordInstallation(channel: String? = nil) async {
guard isEnabled(), !lifecycleRetryDeferred() else { return }
guard let lockFile = acquireLifecycleLock() else { return }
defer {
flock(lockFile, LOCK_UN)
close(lockFile)
}
// A concurrent process may have recorded the lifecycle while this process
// waited for the lock, so marker state must only be read after acquisition.
guard !lifecycleRetryDeferred() else { return }
let installChannel = Self.normalizedInstallChannel(
channel ?? ProcessInfo.processInfo.environment[Constants.envInstallChannel]
)
let installMarker = installationMarkerURL
let releaseMarker = releaseMarkerURL(version: Lume.Version.current)
let needsInstall = !FileManager.default.fileExists(atPath: installMarker.path)
let needsRelease = !FileManager.default.fileExists(atPath: releaseMarker.path)
guard needsInstall || needsRelease else { return }
let properties: [String: Any] = [
"install_channel": installChannel,
"product_version": Lume.Version.current,
]
if needsInstall && needsRelease,
let installRequest = makeRequest(event: TelemetryEvent.install, properties: properties),
let releaseRequest = makeRequest(
event: TelemetryEvent.releaseInstalled, properties: properties)
{
async let installAccepted = send(request: installRequest, event: TelemetryEvent.install)
async let releaseAccepted = send(
request: releaseRequest, event: TelemetryEvent.releaseInstalled)
let (didInstall, didRelease) = await (installAccepted, releaseAccepted)
let installRecorded = didInstall && writeMarker(installMarker)
let releaseRecorded = didRelease && writeMarker(releaseMarker)
finishLifecycleAttempt(succeeded: installRecorded && releaseRecorded)
return
}
if needsInstall,
let request = makeRequest(event: TelemetryEvent.install, properties: properties),
await send(request: request, event: TelemetryEvent.install)
{
if !writeMarker(installMarker) {
deferLifecycleRetry()
return
}
} else if needsInstall {
deferLifecycleRetry()
return
}
if needsRelease,
let request = makeRequest(
event: TelemetryEvent.releaseInstalled, properties: properties),
await send(request: request, event: TelemetryEvent.releaseInstalled)
{
if !writeMarker(releaseMarker) {
deferLifecycleRetry()
return
}
} else if needsRelease {
deferLifecycleRetry()
return
}
clearLifecycleRetry()
}
/// Wait a short, bounded interval for routine events queued by a
/// short-lived CLI command. Long-running `serve` processes do not reach
/// this path until shutdown.
@discardableResult
func flush(timeout: TimeInterval = Constants.flushTimeout) async -> Bool {
let group = pendingRequests
// The blocking wait runs on a GCD thread, never a Swift concurrency
// pool thread: the sends it waits for run on that pool, and blocking
// pool threads (a few flushes at once on a small machine) starves them
// until the timeout.
return await withCheckedContinuation { continuation in
DispatchQueue.global(qos: .utility).async {
continuation.resume(returning: Self.waitForPendingRequests(group, timeout: timeout))
}
}
}
private static func waitForPendingRequests(
_ group: DispatchGroup, timeout: TimeInterval
) -> Bool {
group.wait(timeout: .now() + timeout) == .success
}
func isEnabled() -> Bool {
effectiveState().enabled
}
func status() -> Status {
let state = effectiveState()
return Status(
enabled: state.enabled,
source: state.source,
persistedEnabled: state.persistedEnabled,
installationIdPresent: FileManager.default.fileExists(atPath: installationIdURL.path)
)
}
/// Delete the pseudonymous identity and its registration/release markers.
/// The persisted enabled/disabled preference is intentionally retained.
func resetInstallationId() throws {
identityLock.lock()
installationIdentity = nil
identityLock.unlock()
for url in [installationIdURL, installationMarkerURL, lifecycleRetryAfterURL] {
if FileManager.default.fileExists(atPath: url.path) {
try FileManager.default.removeItem(at: url)
}
}
if FileManager.default.fileExists(atPath: releaseMarkerDirectoryURL.path) {
try FileManager.default.removeItem(at: releaseMarkerDirectoryURL)
}
}
/// A direct release-asset/manual first run has no installer in which to
/// show the default-on notice. Telemetry management commands skip this
/// path so `disable` can be the first action without any event.
func shouldShowFirstRunNotice() -> Bool {
isEnabled() && !FileManager.default.fileExists(atPath: installationMarkerURL.path)
}
static func normalizedInstallChannel(_ raw: String?) -> String {
guard let raw, Constants.allowedInstallChannels.contains(raw) else {
return "first_run"
}
return raw
}
static func commandOperation(arguments: [String]) -> String {
guard let raw = arguments.first else { return "help" }
switch raw {
case "create", "pull", "push", "convert", "images", "clone", "get", "set", "run",
"stop", "ssh", "sip", "ipsw", "serve", "delete", "prune", "config", "logs",
"update", "setup", "channel":
return raw
case "ls": return "list"
case "check-update": return "check_update"
case "dump-docs": return "dump_docs"
case "help", "--help", "-h": return "help"
default: return "other"
}
}
static func httpOperation(method: String, routePath: String) -> String {
let key = "\(method.uppercased()) \(routePath)"
return [
"GET /lume/vms": "list", "GET /lume/vms/:name": "get",
"DELETE /lume/vms/:name": "delete", "POST /lume/vms": "create",
"POST /lume/vms/clone": "clone", "PATCH /lume/vms/:name": "set",
"POST /lume/vms/:name/run": "run", "POST /lume/vms/:name/stop": "stop",
"POST /lume/vms/:name/setup": "setup", "GET /lume/ipsw": "ipsw",
"POST /lume/pull": "pull", "POST /lume/pull/start": "pull_start",
"POST /lume/prune": "prune", "GET /lume/images": "images",
"GET /lume/config": "config_get", "POST /lume/config": "config_update",
"GET /lume/config/locations": "locations_list",
"POST /lume/config/locations": "locations_add",
"DELETE /lume/config/locations/:name": "locations_remove",
"POST /lume/config/locations/default/:name": "locations_default",
"GET /lume/logs": "logs", "POST /lume/vms/push": "push",
"GET /lume/host/status": "host_status",
][key] ?? "other"
}
static func durationBucket(_ elapsed: TimeInterval) -> String {
switch max(0, elapsed) {
case ..<0.1: "lt_100ms"
case ..<0.5: "100_499ms"
case ..<2: "500ms_1_999ms"
case ..<10: "2s_9_999ms"
default: "gte_10s"
}
}
static func provisioningDurationBucket(_ elapsed: TimeInterval) -> String {
switch max(0, elapsed) {
case ..<60: "lt_1min"
case ..<300: "1_4min"
case ..<900: "5_14min"
case ..<1_800: "15_29min"
default: "gte_30min"
}
}
// MARK: - Consent and identity
private func effectiveState() -> (enabled: Bool, source: String, persistedEnabled: Bool) {
let persisted = preferenceProvider()
if let raw = ProcessInfo.processInfo.environment[Constants.envTelemetryEnabled],
let enabled = Self.parseBoolean(raw)
{
return (enabled, "environment", persisted)
}
return (persisted, "persisted", persisted)
}
private static func parseBoolean(_ raw: String) -> Bool? {
switch raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() {
case "0", "false", "no", "off": false
case "1", "true", "yes", "on": true
default: nil
}
}
private func getOrCreateInstallationIdentity() -> InstallationIdentity {
identityLock.lock()
defer { identityLock.unlock() }
if let installationIdentity { return installationIdentity }
if let existing = try? String(contentsOf: installationIdURL, encoding: .utf8) {
let trimmed = existing.trimmingCharacters(in: .whitespacesAndNewlines)
if let parsed = UUID(uuidString: trimmed) {
let identity = InstallationIdentity(value: parsed.uuidString, persisted: true)
installationIdentity = identity
return identity
}
}
let newId = UUID().uuidString
var persisted = false
do {
try FileManager.default.createDirectory(
at: homeDirectory, withIntermediateDirectories: true)
try newId.write(to: installationIdURL, atomically: true, encoding: .utf8)
persisted = true
} catch {
debugLog("Failed to persist installation ID: \(error.localizedDescription)")
}
let identity = InstallationIdentity(value: newId, persisted: persisted)
installationIdentity = identity
return identity
}
// MARK: - Request construction and delivery
private func makeRequest(event: String, properties: [String: Any]) -> URLRequest? {
let identity = getOrCreateInstallationIdentity()
var eventProperties = sanitizeProperties(properties)
eventProperties["lume_version"] = Lume.Version.current
eventProperties["product_version"] = Lume.Version.current
eventProperties["telemetry_schema_version"] = Constants.schemaVersion
eventProperties["os_family"] = "macos"
eventProperties["os_major"] = String(
ProcessInfo.processInfo.operatingSystemVersion.majorVersion)
eventProperties["arch"] = architecture()
eventProperties["is_ci"] = isCI()
eventProperties["is_synthetic"] = isSynthetic()
eventProperties["transport"] =
eventProperties["transport"] as? String ?? transport(event: event, properties: properties)
eventProperties["process_session_id"] = Constants.processSessionId
eventProperties["id_persisted"] = identity.persisted
eventProperties["$lib"] = "lume-swift"
eventProperties["$lib_version"] = Lume.Version.current
eventProperties["$process_person_profile"] = false
eventProperties["$geoip_disable"] = true
let payload: [String: Any] = [
"api_key": Constants.apiKey,
"event": event,
"distinct_id": identity.value,
"properties": eventProperties,
]
guard let url = URL(string: Constants.captureURL),
let jsonData = try? JSONSerialization.data(withJSONObject: payload)
else {
debugLog("Failed to serialize event payload")
return nil
}
var request = URLRequest(url: url, timeoutInterval: Constants.requestTimeout)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = jsonData
return request
}
private func transport(event: String, properties: [String: Any]) -> String {
if event.hasPrefix("lume_api_") { return "http" }
if event == TelemetryEvent.serve, let mode = properties["mode"] as? String,
mode == "mcp" || mode == "http"
{
return mode == "mcp" ? TelemetryTransport.mcpStdio.rawValue : TelemetryTransport.http.rawValue
}
return "cli"
}
private func sanitizeProperties(_ properties: [String: Any]) -> [String: Any] {
let allowedKeys: Swift.Set<String> = [
"asynchronous", "cache_hit", "cpu", "daemon_was_running", "disk_size",
"disk_size_gb", "duration_bucket", "error_class", "failure_class", "guest_os",
"has_unattended", "headless", "image", "install_channel", "memory", "memory_gb", "mode",
"operation", "os_type", "outcome", "phase", "product_version", "protocol", "source",
"success", "target_version", "tool_name", "transport",
]
var sanitized: [String: Any] = [:]
for (key, value) in properties where allowedKeys.contains(key) {
switch value {
case let value as Bool:
sanitized[key] = value
case let value as Int:
sanitized[key] = value
case let value as Int64:
sanitized[key] = value
case let value as Double where value.isFinite:
sanitized[key] = value
case let value as String:
if key == "target_version" {
if let version = Self.strictReleaseVersion(value) {
sanitized[key] = version
}
} else if Self.allowedPropertyValue(key: key, value: value) {
sanitized[key] = value
} else {
sanitized[key] = "unknown"
}
default:
continue
}
}
return sanitized
}
private static func allowedPropertyValue(key: String, value: String) -> Bool {
switch key {
case "duration_bucket":
return [
"lt_100ms", "100_499ms", "500ms_1_999ms", "2s_9_999ms", "gte_10s",
"lt_1min", "1_4min", "5_14min", "15_29min", "gte_30min",
].contains(value)
case "error_class":
return [
"none", "invalid_params", "not_found", "conflict", "permission_denied",
"unavailable", "transport_error", "operation_error", "internal_error", "unknown_tool",
].contains(value)
case "failure_class":
return ["none", "installer_exit", "installer_launch", "unknown"].contains(value)
case "guest_os", "os_type":
return ["macos", "linux", "windows", "unknown"].contains(value)
case "image":
return value == "custom" || catalogImages.contains(value)
case "install_channel":
return Constants.allowedInstallChannels.contains(value)
case "mode":
return ["custom", "offline", "mcp", "http"].contains(value)
case "operation":
return normalizedOperation(value) == value
case "outcome":
return ["up_to_date", "available", "unavailable", "success", "failed"].contains(value)
case "phase":
return ["accepted", "completed"].contains(value)
case "protocol":
return value == "mcp"
case "source":
return ["cli", "mcp", "background"].contains(value)
case "tool_name":
return normalizedMCPTool(value) == value
case "transport":
return ["cli", "http", "mcp_stdio"].contains(value)
case "product_version":
return strictReleaseVersion(value) != nil
default:
return false
}
}
private static func normalizedOperation(_ raw: String) -> String {
let allowed: Swift.Set<String> = [
"check_update", "clone", "config", "config_get", "config_update", "convert", "create",
"delete", "dump_docs", "exec", "get", "help", "host_status", "images", "ipsw", "list",
"locations_add", "locations_default", "locations_list", "locations_remove", "logs", "pull",
"pull_start", "prune", "push", "resize", "run", "serve", "set", "setup", "sip", "ssh",
"stop", "update",
]
return allowed.contains(raw) ? raw : "other"
}
private static func normalizedMCPTool(_ raw: String) -> String {
let allowed: Swift.Set<String> = [
"check_for_update", "lume_clone_vm", "lume_create_vm", "lume_delete_vm", "lume_exec",
"lume_get_vm", "lume_list_vms", "lume_resize_disk", "lume_run_vm", "lume_stop_vm",
]
return allowed.contains(raw) ? raw : "other"
}
private static func normalizedMCPToolOperation(_ tool: String) -> String {
[
"check_for_update": "check_update", "lume_clone_vm": "clone", "lume_create_vm": "create",
"lume_delete_vm": "delete", "lume_exec": "exec", "lume_get_vm": "get",
"lume_list_vms": "list", "lume_resize_disk": "resize", "lume_run_vm": "run",
"lume_stop_vm": "stop",
][tool] ?? "other"
}
private static func normalizedGuestOS(_ raw: String) -> String {
let value = raw.lowercased()
return ["macos", "linux", "windows"].contains(value) ? value : "unknown"
}
private static func normalizedUpdateSource(_ raw: String) -> String {
["cli", "mcp", "background"].contains(raw) ? raw : "background"
}
private static func normalizedUpdateCheckOutcome(_ raw: String) -> String {
["up_to_date", "available", "unavailable"].contains(raw) ? raw : "unavailable"
}
private static func normalizedUpdateFailureClass(_ raw: String) -> String {
["installer_exit", "installer_launch"].contains(raw) ? raw : "unknown"
}
/// Images Cua publishes for Lume (the cua catalog's `macos:<major>` ids
/// and the trycua Lume repositories). Anything else is `custom`.
static let catalogImages: Swift.Set<String> = [
"macos:26", "macos:15",
"macos-tahoe-vanilla", "macos-tahoe-cua", "macos-tahoe-xcode",
"macos-sequoia-vanilla", "macos-sequoia-cua", "macos-sequoia-xcode",
]
/// The telemetry value of an image reference: its catalog id, else
/// `custom`. The reference itself (a private registry, org, repository,
/// tag or digest) is never sent.
static func imageId(
_ reference: String, registry: String = "ghcr.io", organization: String = "trycua"
) -> String {
guard registry.lowercased() == "ghcr.io", organization.lowercased() == "trycua" else {
return "custom"
}
var ref = reference.trimmingCharacters(in: .whitespaces).lowercased()
if let at = ref.firstIndex(of: "@") { ref = String(ref[..<at]) }
if ref.hasPrefix("ghcr.io/trycua/") { ref.removeFirst("ghcr.io/trycua/".count) }
guard !ref.isEmpty, !ref.contains("/") else { return "custom" }
if catalogImages.contains(ref) { return ref }
let parts = ref.split(separator: ":", maxSplits: 1).map(String.init)
let repo = parts.first ?? ref
let tag = parts.count > 1 ? parts[1] : "latest"
// `macos:<major>` is only an id with its tag; Lume repositories are
// ids by name with their published tags (`latest` or a version).
if repo != "macos", catalogImages.contains(repo),
tag == "latest" || tag.allSatisfy({ $0.isNumber || $0 == "." })
{
return repo
}
return "custom"
}
static func strictReleaseVersion(_ raw: String?) -> String? {
guard let raw else { return nil }
let value = raw.trimmingCharacters(in: .whitespacesAndNewlines)
let normalized = value.hasPrefix("v") ? String(value.dropFirst()) : value
guard !normalized.isEmpty, normalized.count <= 64, !normalized.contains("+") else { return nil }
let split = normalized.split(separator: "-", maxSplits: 1, omittingEmptySubsequences: false)
let core = split[0].split(separator: ".", omittingEmptySubsequences: false)
guard core.count == 3,
core.allSatisfy({
!$0.isEmpty && $0.count <= 6 && $0.allSatisfy({ $0.isASCII && $0.isNumber })
})
else { return nil }
if split.count == 2 {
let suffix = split[1]
guard !suffix.isEmpty, suffix.count <= 32,
suffix.allSatisfy({
$0.isASCII && ($0.isLetter || $0.isNumber || $0 == "." || $0 == "-")
})
else { return nil }
}
return normalized
}
private func send(request: URLRequest, event: String) async -> Bool {
if let poster {
return await poster(request)
}
do {
let (_, response) = try await urlSession.data(for: request)
let statusCode = (response as? HTTPURLResponse)?.statusCode ?? 0
debugLog("Event sent: \(event), status: \(statusCode)")
return (200..<300).contains(statusCode)
} catch {
debugLog("Failed to send event \(event): \(error.localizedDescription)")
return false
}
}
private func shouldCaptureRoutineEvent(event: String, now: Date = Date()) -> Bool {
rateLimitLock.lock()
defer { rateLimitLock.unlock() }
if now.timeIntervalSince(rateLimitWindowStarted) >= Constants.routineEventWindow {
rateLimitWindowStarted = now
rateLimitCaptured = 0
rateLimitCapturedValueEvent = false
}
let isValueEvent = event == TelemetryEvent.vmStarted
guard rateLimitCaptured < Constants.routineEventLimitPerHour else {
guard isValueEvent, !rateLimitCapturedValueEvent else { return false }
rateLimitCapturedValueEvent = true
return true
}
rateLimitCaptured += 1
rateLimitCapturedValueEvent = rateLimitCapturedValueEvent || isValueEvent
return true
}
// MARK: - Paths and platform fields
private var installationIdURL: URL {
homeDirectory.appendingPathComponent(Constants.telemetryIdFileName)
}
private var installationMarkerURL: URL {
homeDirectory.appendingPathComponent(Constants.installationRecordedFileName)
}
private var releaseMarkerDirectoryURL: URL {
homeDirectory.appendingPathComponent(Constants.releaseRecordedDirectoryName)
}
private var lifecycleRetryAfterURL: URL {
homeDirectory.appendingPathComponent(Constants.lifecycleRetryAfterFileName)
}
private var lifecycleLockURL: URL {
homeDirectory.appendingPathComponent(Constants.lifecycleLockFileName)
}
private func acquireLifecycleLock() -> Int32? {
do {
try FileManager.default.createDirectory(at: homeDirectory, withIntermediateDirectories: true)
} catch {
debugLog("Failed to create lifecycle lock directory: \(error.localizedDescription)")
return nil
}
let descriptor = Darwin.open(lifecycleLockURL.path, O_CREAT | O_RDWR, S_IRUSR | S_IWUSR)
guard descriptor >= 0 else { return nil }
guard flock(descriptor, LOCK_EX | LOCK_NB) == 0 else {
close(descriptor)
return nil
}
return descriptor
}
private func releaseMarkerURL(version: String) -> URL {
let safeVersion = version.map { character -> Character in
character.isLetter || character.isNumber || character == "." || character == "-"
? character : "_"
}
return releaseMarkerDirectoryURL.appendingPathComponent(String(safeVersion))
}
@discardableResult
private func writeMarker(_ url: URL) -> Bool {
do {
try FileManager.default.createDirectory(
at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
try "1".write(to: url, atomically: true, encoding: .utf8)
return true
} catch {
debugLog("Failed to write marker: \(error.localizedDescription)")
return false
}
}
private func lifecycleRetryDeferred(now: Date = Date()) -> Bool {
guard
let raw = try? String(contentsOf: lifecycleRetryAfterURL, encoding: .utf8),
let retryAfter = TimeInterval(raw.trimmingCharacters(in: .whitespacesAndNewlines))
else { return false }
let remaining = retryAfter - now.timeIntervalSince1970
return remaining > 0 && remaining <= Constants.lifecycleRetryBackoff
}
private func deferLifecycleRetry(now: Date = Date()) {
let retryAfter = now.timeIntervalSince1970 + Constants.lifecycleRetryBackoff
do {
try FileManager.default.createDirectory(at: homeDirectory, withIntermediateDirectories: true)
try String(retryAfter).write(
to: lifecycleRetryAfterURL, atomically: true, encoding: .utf8)
} catch {
debugLog("Failed to defer lifecycle retry: \(error.localizedDescription)")
}
}
private func clearLifecycleRetry() {
guard FileManager.default.fileExists(atPath: lifecycleRetryAfterURL.path) else { return }
do {
try FileManager.default.removeItem(at: lifecycleRetryAfterURL)
} catch {
debugLog("Failed to clear lifecycle retry: \(error.localizedDescription)")
}
}
private func finishLifecycleAttempt(succeeded: Bool) {
if succeeded {
clearLifecycleRetry()
} else {
deferLifecycleRetry()
}
}
private func architecture() -> String {
#if arch(arm64)
"arm64"
#elseif arch(x86_64)
"x86_64"
#else
"unknown"
#endif
}
private func isCI() -> Bool {
let variables = [
"CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI",
"JENKINS_URL", "CIRCLECI", "BUILDKITE", "TF_BUILD", "TEAMCITY_VERSION",
]
return variables.contains { ProcessInfo.processInfo.environment[$0] != nil }
}
private func isSynthetic() -> Bool {
ProcessInfo.processInfo.environment[Constants.envTelemetrySynthetic]
.flatMap(Self.parseBoolean) ?? false
}
private func debugLog(_ message: String) {
guard let value = ProcessInfo.processInfo.environment[Constants.envTelemetryDebug],
Self.parseBoolean(value) == true
else { return }
Logger.info("[Telemetry] \(message)")
}
}
// MARK: - Telemetry Events
enum TelemetryEvent {
static let install = "lume_install"
static let releaseInstalled = "lume_release_installed"
static let create = "lume_create"
static let run = "lume_run"
static let stop = "lume_stop"
static let delete = "lume_delete"
static let clone = "lume_clone"
static let convert = "lume_convert"
static let pull = "lume_pull"
static let push = "lume_push"
static let serve = "lume_serve"
static let setup = "lume_setup"
static let config = "lume_config"
static let sip = "lume_sip"
static let ssh = "lume_ssh"
static let operationCompleted = "lume_operation_completed"
static let mcpSessionStarted = "lume_mcp_session_started"
static let mcpToolCompleted = "lume_mcp_tool_completed"
static let vmStarted = "lume_vm_started"
static let provisioningStarted = "lume_provisioning_started"
static let provisioningCompleted = "lume_provisioning_completed"
static let updateChecked = "lume_update_checked"
static let updateApplyStarted = "lume_update_apply_started"
static let updateApplyCompleted = "lume_update_apply_completed"
static let apiVMList = "lume_api_vm_list"
static let apiVMGet = "lume_api_vm_get"
static let apiVMCreate = "lume_api_vm_create"
static let apiVMRun = "lume_api_vm_run"
static let apiVMStop = "lume_api_vm_stop"
static let apiVMDelete = "lume_api_vm_delete"
static let apiVMClone = "lume_api_vm_clone"
static let apiVMUpdate = "lume_api_vm_update"
static let apiPull = "lume_api_pull"
static let apiPush = "lume_api_push"
static let apiImages = "lume_api_images"
static let allowed: Swift.Set<String> = [
install, releaseInstalled, create, run, stop, delete, clone, convert, pull, push, serve, setup,
config,
sip, ssh, operationCompleted, mcpSessionStarted, mcpToolCompleted, vmStarted,
provisioningStarted,
provisioningCompleted, updateChecked, updateApplyStarted, updateApplyCompleted, apiVMList,
apiVMGet, apiVMCreate, apiVMRun, apiVMStop, apiVMDelete, apiVMClone, apiVMUpdate, apiPull,
apiPush, apiImages,
]
}