Shared types and errors
The cua.env.v1 types every spacesd service shares: ErrorInfo, principals and geometry.
The cua.env.v1 types every spacesd service shares: ErrorInfo, principals and geometry.
Errors (google.rpc.Status carrying ErrorInfo), principals and geometry, used by every cua.env.v1 service.
Source: libs/cua/proto/cua/env/v1/common.proto.
cua/env/v1/common.proto#A point in a two-dimensional coordinate space. Which space is always stated
by the enclosing message (see CoordinateSpace).
| Field | # | Type | Description |
|---|---|---|---|
x | 1 | double | Horizontal coordinate, growing to the right. |
y | 2 | double | Vertical coordinate, growing downward. |
An axis-aligned rectangle in a coordinate space stated by the enclosing message.
| Field | # | Type | Description |
|---|---|---|---|
x | 1 | double | Left edge. |
y | 2 | double | Top edge. |
width | 3 | double | Width. Never negative. |
height | 4 | double | Height. Never negative. |
A size in device (physical) pixels.
| Field | # | Type | Description |
|---|---|---|---|
width | 1 | uint32 | Width in pixels. |
height | 2 | uint32 | Height in pixels. |
Opaque, server-issued reference to a window.
Native window identifiers (CGWindowID, HWND, X11 Window, portal tokens) are
never exposed. id stays stable for the life of the native window. epoch
changes whenever the server recycles an id or the window's identity is no
longer trustworthy (for example, the owning process restarted). A request
with a stale epoch fails with FAILED_PRECONDITION and
ERROR_REASON_STALE_HANDLE.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Opaque window identifier. Compare only for equality. |
epoch | 2 | uint64 | Identity generation of id. |
A display (monitor) attached to the guest desktop.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Opaque, stable display identifier. The alias "primary" is accepted wherever a display id is expected. |
name | 2 | string | Human-readable name, for example "Built-in Retina Display" or "XVFB-0". |
primary | 3 | bool | True for the primary display. |
bounds | 4 | Rect | Display bounds in global logical points (COORDINATE_SPACE_SCREEN). |
native_size | 5 | PixelSize | Size of the display's framebuffer in physical pixels. |
scale_factor | 6 | double | Physical pixels per logical point (for example 2.0 on Retina, 1.0 on most Linux framebuffers). |
refresh_rate_hz | 7 | uint32 | Nominal refresh rate in hertz, 0 when unknown (for example Xvfb). |
rotation_degrees | 8 | uint32 | Clockwise rotation in degrees: 0, 90, 180 or 270. |
What the server actually did for an input or action request.
| Field | # | Type | Description |
|---|---|---|---|
delivery | 1 | Delivery | The delivery mode that was used. Never DELIVERY_AUTO or unspecified. |
focus_changed | 2 | bool | True if the focused window or frontmost app changed as a result. |
pointer_moved | 3 | bool | True if the user-visible pointer moved as a result. |
detail | 4 | string | Free-form, human-readable note (for example which platform path was used). Not for programmatic use. |
Who is making a call. Sent as serialized bytes in the x-cua-principal-bin
metadata entry.
| Field | # | Type | Description |
|---|---|---|---|
id | 1 | string | Stable identifier chosen by the client (for example a user id or an agent run id). |
display_name | 2 | string | Name shown to other participants. |
color | 3 | string | Preferred cursor color as #RRGGBB. The server may substitute a different color to keep participants distinguishable. |
kind | 4 | PrincipalKind | Whether the principal is a human or an automated agent. |
Machine-readable error detail, packed as google.protobuf.Any inside the
google.rpc.Status in the grpc-status-details-bin trailer.
| Field | # | Type | Description |
|---|---|---|---|
reason | 1 | ErrorReason | The specific reason. More precise than the gRPC status code. |
message | 2 | string | Human-readable description. Not for programmatic use. |
feature | 3 | string | Capability feature name involved, when reason is ERROR_REASON_FEATURE_UNSUPPORTED (for example "a11y"). |
metadata | 4 | map of string to string | Structured context. Well-known keys: "expected_sequence", "expected_offset", "path", "pid", "tag", "retry_after_ms". |
Periodic empty message sent on long-lived server streams so proxies (the Fleet gateway, load balancers) do not time out an idle stream. Clients ignore it apart from resetting their own liveness timers.
No fields.
The coordinate space a Point or Rect is expressed in.
| Value | # | Description |
|---|---|---|
COORDINATE_SPACE_UNSPECIFIED | 0 | Not set. Servers treat it as COORDINATE_SPACE_SCREEN. |
COORDINATE_SPACE_SCREEN | 1 | Global desktop space in logical points, origin at the top-left of the primary display. This is the space Display.bounds uses. |
COORDINATE_SPACE_WINDOW | 2 | Logical points relative to the top-left corner of the target window's frame. Requires a target window on the request. |
COORDINATE_SPACE_SCREENSHOT | 3 | Pixels of a screenshot previously returned by ComputerService.Screenshot, identified by screenshot_id on the request. The server performs the one conversion to native coordinates and fails with ERROR_REASON_STALE_GEOMETRY if the display or window geometry changed since the screenshot was taken. |
COORDINATE_SPACE_NORMALIZED | 4 | Normalized coordinates in [0, 1] relative to the target window, or the target display when no window is given. |
How synthetic input or an action is delivered to the guest.
| Value | # | Description |
|---|---|---|
DELIVERY_UNSPECIFIED | 0 | Not set. Servers treat it as DELIVERY_AUTO. |
DELIVERY_AUTO | 1 | Prefer background delivery and fall back to foreground delivery when the platform or target cannot receive background input. |
DELIVERY_BACKGROUND | 2 | Deliver without moving the user-visible pointer, changing the focused window or activating the target app. Fails with ERROR_REASON_WOULD_REQUIRE_ACTIVATION rather than falling back. |
DELIVERY_FOREGROUND | 3 | Activate the target (if any) and deliver through the global input stream, moving the real pointer and focus. |
Kind of principal behind a call.
| Value | # | Description |
|---|---|---|
PRINCIPAL_KIND_UNSPECIFIED | 0 | Not set. Servers treat it as PRINCIPAL_KIND_HUMAN. |
PRINCIPAL_KIND_HUMAN | 1 | A person driving a client UI. |
PRINCIPAL_KIND_AGENT | 2 | An automated agent. |
Machine-readable error reasons shared by every service.
| Value | # | Description |
|---|---|---|
ERROR_REASON_UNSPECIFIED | 0 | Not set. |
ERROR_REASON_UNAUTHENTICATED | 1 | Missing or wrong bearer token, or an expired ticket. |
ERROR_REASON_FEATURE_UNSUPPORTED | 2 | The operation needs a feature the guest does not support. See ErrorInfo.feature and SystemService.GetCapabilities. |
ERROR_REASON_PERMISSION_DENIED | 3 | The guest OS denied permission (for example macOS TCC, UAC, AT-SPI disabled). |
ERROR_REASON_STALE_HANDLE | 4 | A WindowRef epoch no longer matches. |
ERROR_REASON_STALE_GEOMETRY | 5 | Geometry changed since the referenced screenshot or media frame. |
ERROR_REASON_STALE_SNAPSHOT | 6 | An accessibility element's snapshot is no longer current. |
ERROR_REASON_WOULD_REQUIRE_ACTIVATION | 7 | DELIVERY_BACKGROUND was requested but only foreground delivery could reach the target. |
ERROR_REASON_TARGET_UNAVAILABLE | 8 | The target window, app, display or element is gone. |
ERROR_REASON_DELIVERY_FAILED | 9 | The platform accepted the request but native delivery failed. |
ERROR_REASON_PROCESS_NOT_FOUND | 10 | No process matches the given pid or tag. |
ERROR_REASON_PATH_NOT_FOUND | 11 | The path does not exist. |
ERROR_REASON_PATH_EXISTS | 12 | The path already exists and overwrite was not requested. |
ERROR_REASON_NOT_A_DIRECTORY | 13 | A directory was required. |
ERROR_REASON_IS_A_DIRECTORY | 14 | A regular file was required. |
ERROR_REASON_DISK_FULL | 15 | The guest disk is full (HTTP 507 on the /files route). |
ERROR_REASON_CHECKSUM_MISMATCH | 16 | Received content does not match the declared SHA-256. |
ERROR_REASON_SESSION_NOT_FOUND | 17 | Unknown or expired upload, transfer, watcher, media session or forward. |
ERROR_REASON_OFFSET_MISMATCH | 18 | A chunk arrived at the wrong offset. metadata["expected_offset"] holds the offset the server expects next. |
ERROR_REASON_SEQUENCE_GAP | 19 | A sequenced input chunk skipped ahead. metadata["expected_sequence"] holds the sequence the server expects next. |
ERROR_REASON_RATE_LIMITED | 20 | Too many requests. metadata["retry_after_ms"] may hint a delay. |
ERROR_REASON_LIMIT_EXCEEDED | 21 | A request limit was exceeded (chunk size, message size, tree depth). |
ERROR_REASON_NOT_INITIALIZED | 22 | SystemService.Init has not configured a required default yet. |
ERROR_REASON_INTERNAL | 23 | An internal server error. Report a bug. |