@stim-cli/server 1.11.0 → 1.13.0

package/README.md

@@ -107,12 +107,13 @@ closes its open connections.
 ## Scopes
 
 A paired device has the `read` capability, which serves state, or also
-`control`, which runs [actions](#actions). Pairing grants `read` only, unless
+`control`, which runs [actions](#actions) and [controls devices](#control). Pairing grants `read` only, unless
 the pairing code came from `stim-server pair --control`. On the Mac,
 `stim-server devices grant <id> --control` adds control to a paired device and
 `--read` takes it away. Nothing a client sends changes its own capabilities.
-The server checks the device's capabilities in `devices.json` on every action,
-so taking control away applies to open connections at once. `hello` reports
+The server checks the device's capabilities in `devices.json` on every action
+and control session, and ends a device's control sessions when it loses
+`control`, so taking control away applies to open connections at once. `hello` reports
 the capabilities and actions of the connection's device when it connects; a
 connection sees a new grant after it reconnects.
 
@@ -164,23 +165,31 @@ Events are `{ "event", "subscription", ... }`.
   `$STIM_HOME/server/helpers/`, named by a hash of the sources and the
   compiler version. For a simulator it renders the display's framebuffer
   (CoreSimulator's IOSurface) when the display reports damage, turned
-  upright; for an emulator it keeps one gRPC `streamScreenshot` call open,
+  upright. An iPhone Duo lights one of its two panels, the cover while
+  folded and the inner panel while unfolded, and leaves the other black, so
+  the helper streams whichever panel is lit; its frames and video carry
+  `posture`, and the size changes with the panel. For an emulator it keeps one gRPC `streamScreenshot` call open,
   found through the discovery file and token the emulator writes when Stim
   boots it. It scales frames to fit the largest `maxEdge` and paces them to
   the highest `fps` its subscribers asked for. All subscribers of a device
-  share one helper, which sends a new subscriber the latest frame and exits
-  with the last subscriber or when the server's end of its stdin closes.
+  share one helper, which sends a new subscriber the latest frame. It keeps
+  running for 10 seconds after the last subscriber leaves, so a client that
+  subscribes for one frame at a time reuses it and gets the latest frame at
+  once, and exits after that or when the server's end of its stdin closes.
 
   A client that decodes H.264 adds `video: ["h264"]`. When the helper is
   built, the result carries `video: "h264"`, `fps` may go up to 60, and
   frames arrive as binary WebSocket messages instead of `frame` events: a
   big-endian header (u8 version 1, u8 flags with bit 0 set on a keyframe,
+  and on an iPhone Duo bit 1 while folded or bit 2 while unfolded,
   u16 header length, u32 sequence number of the messages sent on this
   subscription, f64 capture time in milliseconds since the epoch on the
   Mac's clock, u16 width, u16 height, u8 subscription id length and the
   ASCII id), then one Annex-B access unit. Every keyframe carries its SPS
   and PPS, and the stream has no B-frames, so each access unit is shown as
-  it arrives. The helper encodes with VideoToolbox in real time: Main
+  it arrives. A change of size, such as a rotation or a Duo fold, restarts
+  the encoder, and the next access unit is a keyframe with the new SPS and
+  PPS. The helper encodes with VideoToolbox in real time: Main
   profile, a keyframe at least every 2 seconds, straight from the
   simulator's IOSurface or from the emulator's RGBA frames, only when the
   screen changed. A subscriber starts at a keyframe, and `frames.keyframe`
@@ -194,13 +203,13 @@ Events are `{ "event", "subscription", ... }`.
   subscribers of the same device still get at most the `fps` they asked
   for. Watching video needs only `read`. Without the helper, the result has
   no `video`, `fps` above 30 is lowered to 30, and `frame` events arrive as
-  before; an iPhone Duo and a helper that fails before its first frame also
-  fall back to `frame` events within a video subscription.
+  before; a helper that fails before its first frame also falls back to
+  `frame` events within a video subscription.
 
   Without the helper (the compiler is missing or fails, which the server
-  retries every 5 minutes, or the helper fails before its first frame), for a
-  subscription made while it is still being built, and for an iPhone Duo,
-  frames come from screenshots, and `fps` and `maxEdge` only cap the rate. Simulators are
+  retries every 5 minutes, or the helper fails before its first frame), and
+  for a subscription made while it is still being built, frames come from
+  screenshots, and `fps` and `maxEdge` only cap the rate. Simulators are
   captured with `xcrun simctl io <udid> screenshot`, of the primary display,
   or of the default display when that `simctl` does not accept `primary`. An
   iPhone Duo lights one of two panels: the capture follows the lit one
@@ -221,12 +230,15 @@ Events are `{ "event", "subscription", ... }`.
   (`default` when absent), and returns the payload of
   `stim <platform> --plan --json` run in the workspace: the fingerprint, the
   cache result the next build would get (`local`, `remote` or `false`), the
-  prebuild decision, and `expectedMs` with its `basis`. It builds, boots and
+  prebuild decision, `expectedMs` with its `basis`, and on a predicted cold
+  build its `missReason`. It builds, boots and
   installs nothing and writes no Stim state; a remote cache check can
   download the artifact into a temporary directory, so it gets 150 seconds
   instead of 60. A plan predicting that the build would refuse is a result
   whose `refusal` holds the code, message and remedy. A plan that cannot be
-  computed is a `stim-failed` error.
+  computed is a `stim-failed` error. One plan runs per workspace at a time,
+  across all connections; later requests wait their turn, and the 150
+  seconds start when the plan starts.
 - `machine.get` returns cheap machine usage, read in the server process
   without running `stim`: `volumes`, one per volume that holds a Stim
   workspace, Stim home, or the simulators, with `mount`, `holds`, `freeBytes`
@@ -297,6 +309,80 @@ and `durationMs` when it ran. Strings from the client and error messages are
 cut to 256 characters. `stim-server log` prints them, with control characters
 replaced by `?`.
 
+## Control
+
+A device with `control` can drive a simulator or emulator that `stim status`
+lists as owned by a workspace. Nothing it sends reaches any other device.
+
+- `control.begin` takes `workspace`, `platform`, `slot` (`default` when
+  absent) and `takeOver`, and returns `{ "session", "platform", "lease",
+"postures" }`. `postures` lists what `input.posture` takes for the device:
+  `folded` and `unfolded` for an iPhone Duo, `folded`, `half-open` and
+  `unfolded` for an emulator with a hinge, such as a `pixel_fold` AVD, and
+  none otherwise.
+  The server refuses with `device-busy` when status reports the device driven
+  (agent-device, a `stim device lock`, a test runner) or another client
+  controls it, naming the driver. With `takeOver: true` it proceeds anyway;
+  another client's session then ends with `taken-over`.
+- The session holds a `stim device lock <platform> <id> --for 2m` lease,
+  renewed every minute, so `stim status` shows the device as driven by
+  `stim device lock` and agents leave it alone. `lease` carries its
+  `grantedAt`, the `since` of that driver, so a client can tell its own lease
+  from an agent's. The server releases the lease with `stim device unlock`
+  when the session ends, unless the lease was already held before the session
+  began, as when it took the device over from an agent in the same workspace;
+  it renews only a lease it took. Leases belong to the workspace, not to the
+  session: an agent in the same workspace that runs `stim device lock` on the
+  device during a session shares the lease, and the session's end releases
+  it.
+- `input.touch` takes `session`, `phase` (`down`, `move`, `up`), `x` and `y`
+  as fractions of the upright screen, and `display` (0, the main display).
+  `input.text` takes up to 256 printable ASCII characters, where `\n` presses
+  Return, `\t` Tab and `\b` Delete. `input.button` takes `home` or `lock`,
+  and on Android also `back` or `app-switch`. `input.rotate` takes
+  `direction` (`left` or `right`) and turns the device a quarter turn.
+  `input.posture` takes one of the session's `postures`. Each answers `{}` once the input
+  is handed to the device: when it goes through the helper, that is when the
+  helper receives it, so a failure there shows only in the server's log. A connection may send 120 inputs a second and type 40
+  characters a second, with a burst of 256, and rotate or change posture twice a
+  second; more fail with `limit-exceeded`.
+- `control.end` ends a session. The server also ends it with a
+  `control-ended` event `{ "session", "reason", "message" }` after 5 minutes
+  without input (`idle`), when another client takes the device over
+  (`taken-over`), when the device stops or changes owner (`device-gone`),
+  when the paired device loses `control` (`forbidden`), or when input cannot
+  reach the device (`failed`). Closing the connection ends its sessions.
+
+Input goes through the device's `stim-frames` helper, the process that
+streams its frames:
+
+- Simulators take touches, keys and buttons through the simulator's
+  CoreDevice HID service (`dtuhidd`), the one Xcode's Device Hub uses, so
+  input keeps working while Device Hub or Siniulator shows the simulator.
+  With an Xcode whose simulators have no such service, input goes through
+  SimulatorKit's legacy HID client instead. The first input starts that service, as Device
+  Hub does, and from then until the simulator reboots it ignores tools that
+  still use SimulatorKit's legacy HID client. Text is typed key by key on a US
+  layout. `lock` is the side button.
+- Emulators take touches through the emulator's gRPC `sendTouch`. Text and
+  buttons go through gRPC `sendKey` when the emulator reports a hardware
+  keyboard, which AVDs Stim creates have. An emulator without one drops key
+  events, so for it text and buttons go through `adb -s <serial> shell input`.
+- Rotation and posture go the way Stim Desktop sends them: a simulator turns
+  through the orientation message Simulator.app sends it, and an emulator
+  through gRPC `setPhysicalModel` for rotation and `setPosture` for its hinge.
+  An iPhone Duo folds with `sim-fold`, which the server builds from Stim
+  Desktop's sources on the first fold and runs inside the simulator with
+  `xcrun simctl spawn`; it answers `{}` once the fold finished, and fails
+  with `action-failed` when the fold does not finish within 40 seconds. `sim-fold`
+  swaps the posture, so the server runs it only when the Duo's latest frame
+  shows the other posture, and refuses the request until a frame showed one.
+
+Every session start, takeover and end, and every refused `control.begin`,
+appends a line to the action log, with `action` set to `control.begin`,
+`control.take-over` or `control.end`, and a `reason` that says why the session
+ended or whom it took the device from. Inputs are not logged.
+
 The error codes `unauthorized`, `pairing-expired`, and `protocol-unsupported`
 refuse the client until it pairs again or updates; clients retry the others.
 

package/dist/{protocol-CmlG7X7_.mjs → protocol-rC-5KT1O.mjs}

@@ -16,7 +16,14 @@ const METHODS = [
 	"machine.get",
 	"machine.history",
 	"unsubscribe",
-	"action"
+	"action",
+	"control.begin",
+	"control.end",
+	"input.touch",
+	"input.text",
+	"input.button",
+	"input.rotate",
+	"input.posture"
 ];
 /**
 * `unauthorized`, `pairing-expired` and `protocol-unsupported` refuse the client until it pairs again or
@@ -41,7 +48,9 @@ const ERROR_CODES = [
 	"forbidden",
 	"unknown-action",
 	"action-busy",
-	"action-failed"
+	"action-failed",
+	"device-busy",
+	"unknown-session"
 ];
 const LOG_SOURCES = [
 	"metro",
@@ -58,6 +67,12 @@ const LOG_LEVELS = [
 	"fatal"
 ];
 const MAX_LOG_TAIL = 5e3;
+/** `reload` also reaches the workspace's Stim-owned Chrome page. */
+const RELOAD_PLATFORMS = [
+	"ios",
+	"android",
+	"web"
+];
 const FRAME_FPS = {
 	default: 5,
 	max: 30,
@@ -72,8 +87,38 @@ const VIDEO_CODECS = ["h264"];
 const VIDEO_HEADER_VERSION = 1;
 /** The keyframe bit of a {@link VideoPacket}'s flags. */
 const VIDEO_KEYFRAME = 1;
+/** The flag bits of a {@link VideoPacket} that carry an iPhone Duo's posture, as `posture` on a `frame` event. */
+const VIDEO_FOLDED = 2;
+const VIDEO_UNFOLDED = 4;
 /** Each action runs one fixed `stim` command in the workspace. */
 const ACTIONS = ["reload", "stop"];
+const TOUCH_PHASES = [
+	"down",
+	"move",
+	"up"
+];
+const MAX_INPUT_TEXT = 256;
+/** `home` and `lock` on both platforms; `back` and `app-switch` on Android only. */
+const INPUT_BUTTONS = [
+	"home",
+	"lock",
+	"back",
+	"app-switch"
+];
+/** `left` turns the device a quarter turn counterclockwise, `right` clockwise. */
+const ROTATE_DIRECTIONS = ["left", "right"];
+const DEVICE_POSTURES = [
+	"folded",
+	"half-open",
+	"unfolded"
+];
+const CONTROL_END_REASONS = [
+	"idle",
+	"taken-over",
+	"device-gone",
+	"forbidden",
+	"failed"
+];
 const requestId = { type: ["integer", "string"] };
 const protocolError = {
 	type: "object",
@@ -103,6 +148,17 @@ function request(method, params) {
 		}
 	};
 }
+function session(properties, required = []) {
+	return {
+		type: "object",
+		required: ["session", ...required],
+		additionalProperties: false,
+		properties: {
+			session: { type: "string" },
+			...properties
+		}
+	};
+}
 function optionalParams(method, params) {
 	return {
 		type: "object",
@@ -216,7 +272,12 @@ function protocolJsonSchema() {
 					ts: { type: "number" },
 					src: { type: "string" },
 					level: { type: "string" },
-					msg: { type: "string" }
+					msg: { type: "string" },
+					context: {
+						type: "array",
+						items: { type: "string" },
+						description: "With `errors`: the code frame and stack lines Expo printed after this error."
+					}
 				}
 			},
 			LogFilter: {
@@ -236,10 +297,11 @@ function protocolJsonSchema() {
 					level: { enum: [...LOG_LEVELS] },
 					slot: {
 						type: "string",
-						minLength: 1
+						pattern: "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
 					},
 					grep: {
 						type: "string",
+						pattern: "^[^\\u0000]*$",
 						description: "A regular expression matched against each message."
 					},
 					errors: { type: "boolean" },
@@ -295,7 +357,7 @@ function protocolJsonSchema() {
 						type: "string",
 						description: "An environment path from a status payload."
 					},
-					platform: { enum: ["ios", "android"] }
+					platform: { enum: [...RELOAD_PLATFORMS] }
 				}
 			}, {
 				type: "object",
@@ -326,6 +388,61 @@ function protocolJsonSchema() {
 					}
 				}
 			},
+			ControlBeginParams: {
+				type: "object",
+				required: ["workspace", "platform"],
+				additionalProperties: false,
+				properties: {
+					workspace: {
+						type: "string",
+						description: "An environment path from a status payload."
+					},
+					platform: { enum: ["ios", "android"] },
+					slot: {
+						type: "string",
+						minLength: 1,
+						default: "default"
+					},
+					takeOver: {
+						type: "boolean",
+						default: false
+					}
+				}
+			},
+			ControlBeginResult: {
+				type: "object",
+				required: [
+					"session",
+					"platform",
+					"lease",
+					"postures"
+				],
+				additionalProperties: false,
+				properties: {
+					session: { type: "string" },
+					platform: { enum: ["ios", "android"] },
+					lease: { oneOf: [{ type: "null" }, {
+						type: "object",
+						required: ["grantedAt", "expiresAt"],
+						additionalProperties: false,
+						properties: {
+							grantedAt: {
+								type: ["string", "null"],
+								format: "date-time"
+							},
+							expiresAt: {
+								type: "string",
+								format: "date-time"
+							}
+						}
+					}] },
+					postures: {
+						type: "array",
+						items: { enum: [...DEVICE_POSTURES] },
+						uniqueItems: true
+					}
+				}
+			},
 			BuildPlanParams: {
 				type: "object",
 				required: ["workspace", "platform"],
@@ -495,7 +612,41 @@ function protocolJsonSchema() {
 					additionalProperties: false,
 					properties: { subscription: { type: "string" } }
 				}),
-				request("action", { $ref: "#/$defs/ActionParams" })
+				request("action", { $ref: "#/$defs/ActionParams" }),
+				request("control.begin", { $ref: "#/$defs/ControlBeginParams" }),
+				request("control.end", session({})),
+				request("input.touch", session({
+					phase: { enum: [...TOUCH_PHASES] },
+					x: {
+						type: "number",
+						minimum: 0,
+						maximum: 1
+					},
+					y: {
+						type: "number",
+						minimum: 0,
+						maximum: 1
+					},
+					display: {
+						type: "integer",
+						minimum: 0,
+						maximum: 3,
+						default: 0
+					}
+				}, [
+					"phase",
+					"x",
+					"y"
+				])),
+				request("input.text", session({ text: {
+					type: "string",
+					minLength: 1,
+					maxLength: 256,
+					pattern: "^[\\x20-\\x7e\\n\\t\\b]+$"
+				} }, ["text"])),
+				request("input.button", session({ button: { enum: [...INPUT_BUTTONS] } }, ["button"])),
+				request("input.rotate", session({ direction: { enum: [...ROTATE_DIRECTIONS] } }, ["direction"])),
+				request("input.posture", session({ posture: { enum: [...DEVICE_POSTURES] } }, ["posture"]))
 			] },
 			ServerResponse: { oneOf: [{
 				type: "object",
@@ -505,6 +656,7 @@ function protocolJsonSchema() {
 					id: requestId,
 					result: { anyOf: [
 						{ $ref: "#/$defs/HelloResult" },
+						{ $ref: "#/$defs/ControlBeginResult" },
 						{ $ref: "#/$defs/ActionResult" },
 						{ $ref: "#/$defs/MachineUsage" },
 						{ $ref: "#/$defs/MachineHistory" },
@@ -627,6 +779,22 @@ function protocolJsonSchema() {
 						delayed: { type: "boolean" }
 					}
 				},
+				{
+					type: "object",
+					required: [
+						"event",
+						"session",
+						"reason",
+						"message"
+					],
+					additionalProperties: false,
+					properties: {
+						event: { const: "control-ended" },
+						session: { type: "string" },
+						reason: { enum: [...CONTROL_END_REASONS] },
+						message: { type: "string" }
+					}
+				},
 				{
 					type: "object",
 					required: [
@@ -651,4 +819,4 @@ function protocolJsonSchema() {
 	};
 }
 //#endregion
-export { FRAME_FPS as a, MAX_LOG_TAIL as c, PROTOCOL_VERSION as d, VIDEO_CODECS as f, protocolJsonSchema as h, FRAME_EDGE as i, METHODS as l, VIDEO_KEYFRAME as m, CAPABILITIES as n, LOG_LEVELS as o, VIDEO_HEADER_VERSION as p, ERROR_CODES as r, LOG_SOURCES as s, ACTIONS as t, PROTOCOL_SCHEMA_FILE as u };
+export { VIDEO_UNFOLDED as C, VIDEO_KEYFRAME as S, ROTATE_DIRECTIONS as _, ERROR_CODES as a, VIDEO_FOLDED as b, INPUT_BUTTONS as c, MAX_INPUT_TEXT as d, MAX_LOG_TAIL as f, RELOAD_PLATFORMS as g, PROTOCOL_VERSION as h, DEVICE_POSTURES as i, LOG_LEVELS as l, PROTOCOL_SCHEMA_FILE as m, CAPABILITIES as n, FRAME_EDGE as o, METHODS as p, CONTROL_END_REASONS as r, FRAME_FPS as s, ACTIONS as t, LOG_SOURCES as u, TOUCH_PHASES as v, protocolJsonSchema as w, VIDEO_HEADER_VERSION as x, VIDEO_CODECS as y };

package/dist/protocol.d.mts

@@ -5,13 +5,13 @@ declare const PROTOCOL_SCHEMA_FILE = "protocol.schema.json";
 /** `read` serves state. `control` also runs {@link ACTIONS}; only the Mac grants it. */
 declare const CAPABILITIES: readonly ["read", "control"];
 type Capability = (typeof CAPABILITIES)[number];
-declare const METHODS: readonly ["hello", "status.subscribe", "logs.query", "logs.subscribe", "stats.get", "settings.get", "frames.subscribe", "frames.keyframe", "build.plan", "machine.get", "machine.history", "unsubscribe", "action"];
+declare const METHODS: readonly ["hello", "status.subscribe", "logs.query", "logs.subscribe", "stats.get", "settings.get", "frames.subscribe", "frames.keyframe", "build.plan", "machine.get", "machine.history", "unsubscribe", "action", "control.begin", "control.end", "input.touch", "input.text", "input.button", "input.rotate", "input.posture"];
 type Method = (typeof METHODS)[number];
 /**
  * `unauthorized`, `pairing-expired` and `protocol-unsupported` refuse the client until it pairs again or
  * updates; clients retry the others.
  */
-declare const ERROR_CODES: readonly ["unauthorized", "pairing-expired", "protocol-unsupported", "identity-unavailable", "bad-request", "unknown-method", "already-authenticated", "unknown-subscription", "unknown-workspace", "limit-exceeded", "slow-client", "status-failed", "logs-failed", "stim-failed", "frames-failed", "forbidden", "unknown-action", "action-busy", "action-failed"];
+declare const ERROR_CODES: readonly ["unauthorized", "pairing-expired", "protocol-unsupported", "identity-unavailable", "bad-request", "unknown-method", "already-authenticated", "unknown-subscription", "unknown-workspace", "limit-exceeded", "slow-client", "status-failed", "logs-failed", "stim-failed", "frames-failed", "forbidden", "unknown-action", "action-busy", "action-failed", "device-busy", "unknown-session"];
 type ErrorCode = (typeof ERROR_CODES)[number];
 type RequestId = number | string;
 /** Spends a single-use pairing token; the result carries the new device token. */
@@ -93,6 +93,9 @@ type StatsResult = Record<string, unknown>;
 /** `stim settings --json`; the CLI masks sensitive values. */
 type SettingsResult = Record<string, unknown>;
 type Platform = "ios" | "android";
+/** `reload` also reaches the workspace's Stim-owned Chrome page. */
+declare const RELOAD_PLATFORMS: readonly ["ios", "android", "web"];
+type ReloadPlatform = (typeof RELOAD_PLATFORMS)[number];
 declare const FRAME_FPS: {
   readonly default: 5;
   readonly max: 30;
@@ -122,7 +125,7 @@ declare const VIDEO_CODECS: readonly ["h264"];
 type VideoCodec = (typeof VIDEO_CODECS)[number];
 /**
  * With `video`, frames arrive as binary WebSocket messages, one H.264 access unit each; see {@link VideoPacket}.
- * A subscription whose device cannot be encoded, such as an iPhone Duo, still sends JSON `frame` events.
+ * A subscription whose device falls back to screenshots still sends JSON `frame` events.
  */
 interface FramesSubscribeResult extends SubscribeResult {
   video?: VideoCodec;
@@ -134,9 +137,12 @@ interface KeyframeParams {
 declare const VIDEO_HEADER_VERSION = 1;
 /** The keyframe bit of a {@link VideoPacket}'s flags. */
 declare const VIDEO_KEYFRAME = 1;
+/** The flag bits of a {@link VideoPacket} that carry an iPhone Duo's posture, as `posture` on a `frame` event. */
+declare const VIDEO_FOLDED = 2;
+declare const VIDEO_UNFOLDED = 4;
 /**
  * The layout of a binary video message, big-endian: u8 version ({@link VIDEO_HEADER_VERSION}), u8 flags
- * ({@link VIDEO_KEYFRAME}), u16 header length, u32 sequence number of the messages sent on this subscription, f64 capture time in milliseconds since the
+ * ({@link VIDEO_KEYFRAME}, and on an iPhone Duo {@link VIDEO_FOLDED} or {@link VIDEO_UNFOLDED}), u16 header length, u32 sequence number of the messages sent on this subscription, f64 capture time in milliseconds since the
  * epoch on the Mac's clock, u16 width, u16 height, u8 subscription id length N, N bytes of ASCII subscription
  * id. After the header comes one Annex-B H.264 access unit; a keyframe carries its SPS and PPS. The stream has
  * no B-frames, so each access unit is shown as it arrives.
@@ -148,19 +154,20 @@ interface VideoPacket {
   capturedAt: number;
   width: number;
   height: number;
+  posture?: "folded" | "unfolded";
   accessUnit: Uint8Array;
 }
 /** Each action runs one fixed `stim` command in the workspace. */
 declare const ACTIONS: readonly ["reload", "stop"];
 type ActionName = (typeof ACTIONS)[number];
 /**
- * `reload` runs `stim reload --json`, with `platform` when both platforms are live; `stop` runs
+ * `reload` runs `stim reload --json`, with `platform` when more than one platform is live; `stop` runs
  * `stim stop --json`. `workspace` is an environment `path` from a status payload. Needs `control`.
  */
 type ActionParams = {
   action: "reload";
   workspace: string;
-  platform?: Platform;
+  platform?: ReloadPlatform;
 } | {
   action: "stop";
   workspace: string;
@@ -171,6 +178,72 @@ interface ActionResult {
   workspace: string;
   output: Record<string, unknown>;
 }
+/**
+ * Starts a control session on the device `stim status` lists as owned by `workspace` in `slot`. Needs
+ * `control`. Refused with `device-busy` while an agent, a device lock or another client drives the device,
+ * unless `takeOver` is true.
+ */
+interface ControlBeginParams {
+  workspace: string;
+  platform: Platform;
+  slot?: string;
+  takeOver?: boolean;
+}
+/**
+ * `lease` is the `stim device lock` lease the server holds for the session, or null when it holds none, such
+ * as after taking over a device another workspace leases. `postures` lists what `input.posture` accepts for
+ * the device: `folded` and `unfolded` for an iPhone Duo, all three for an emulator with a hinge, and none
+ * otherwise.
+ */
+interface ControlBeginResult {
+  session: string;
+  platform: Platform;
+  lease: {
+    grantedAt: string | null;
+    expiresAt: string;
+  } | null;
+  postures: DevicePosture[];
+}
+interface ControlEndParams {
+  session: string;
+}
+declare const TOUCH_PHASES: readonly ["down", "move", "up"];
+type TouchPhase = (typeof TOUCH_PHASES)[number];
+/** `x` and `y` are fractions of the upright screen, origin top-left. `display` is 0 for the main display. */
+interface InputTouchParams {
+  session: string;
+  phase: TouchPhase;
+  x: number;
+  y: number;
+  display?: number;
+}
+declare const MAX_INPUT_TEXT = 256;
+/** Printable ASCII, where `\n` presses Return, `\t` Tab and `\b` Delete. */
+interface InputTextParams {
+  session: string;
+  text: string;
+}
+/** `home` and `lock` on both platforms; `back` and `app-switch` on Android only. */
+declare const INPUT_BUTTONS: readonly ["home", "lock", "back", "app-switch"];
+type InputButton = (typeof INPUT_BUTTONS)[number];
+interface InputButtonParams {
+  session: string;
+  button: InputButton;
+}
+/** `left` turns the device a quarter turn counterclockwise, `right` clockwise. */
+declare const ROTATE_DIRECTIONS: readonly ["left", "right"];
+type RotateDirection = (typeof ROTATE_DIRECTIONS)[number];
+interface InputRotateParams {
+  session: string;
+  direction: RotateDirection;
+}
+declare const DEVICE_POSTURES: readonly ["folded", "half-open", "unfolded"];
+type DevicePosture = (typeof DEVICE_POSTURES)[number];
+/** Moves the hinge of a device whose `control.begin` result lists `posture`. */
+interface InputPostureParams {
+  session: string;
+  posture: DevicePosture;
+}
 /** Predicts the next `ios` or `android` build of `workspace` in `slot` (`default` when absent). */
 interface BuildPlanParams {
   workspace: string;
@@ -292,6 +365,34 @@ interface Methods {
     params: ActionParams;
     result: ActionResult;
   };
+  "control.begin": {
+    params: ControlBeginParams;
+    result: ControlBeginResult;
+  };
+  "control.end": {
+    params: ControlEndParams;
+    result: Record<string, never>;
+  };
+  "input.touch": {
+    params: InputTouchParams;
+    result: Record<string, never>;
+  };
+  "input.text": {
+    params: InputTextParams;
+    result: Record<string, never>;
+  };
+  "input.button": {
+    params: InputButtonParams;
+    result: Record<string, never>;
+  };
+  "input.rotate": {
+    params: InputRotateParams;
+    result: Record<string, never>;
+  };
+  "input.posture": {
+    params: InputPostureParams;
+    result: Record<string, never>;
+  };
 }
 type ClientRequest = { [M in Method]: {
   id: RequestId;
@@ -357,10 +458,21 @@ interface FrameDelayedEvent {
   subscription: string;
   delayed: boolean;
 }
-type ServerEvent = StatusEvent | LogsEvent | FrameEvent | FrameDelayedEvent | ErrorEvent;
+declare const CONTROL_END_REASONS: readonly ["idle", "taken-over", "device-gone", "forbidden", "failed"];
+/**
+ * The server ended a control session: no input for 5 minutes, another client took the device over, the device
+ * stopped or changed owner, the device lost `control`, or input could not reach the device.
+ */
+interface ControlEndedEvent {
+  event: "control-ended";
+  session: string;
+  reason: (typeof CONTROL_END_REASONS)[number];
+  message: string;
+}
+type ServerEvent = StatusEvent | LogsEvent | FrameEvent | FrameDelayedEvent | ErrorEvent | ControlEndedEvent;
 type ServerMessage = ServerResponse | ServerEvent;
 type JsonSchema = Record<string, unknown>;
 /** The JSON Schema of every message on the wire, written to `dist/protocol.schema.json` at build time. */
 declare function protocolJsonSchema(): JsonSchema;
 //#endregion
-export { ACTIONS, ActionName, ActionParams, ActionResult, BuildPlanParams, BuildPlanResult, CAPABILITIES, Capability, ClientRequest, DeviceAuth, ERROR_CODES, ErrorCode, ErrorEvent, FRAME_EDGE, FRAME_FPS, FrameDelayedEvent, FrameEvent, FrameTarget, FramesSubscribeResult, HelloParams, HelloResult, KeyframeParams, LOG_LEVELS, LOG_SOURCES, LogFilter, LogLevel, LogRecord, LogSource, LogsEvent, LogsQueryResult, MAX_LOG_TAIL, METHODS, MachineHistory, MachineHistoryParams, MachineUsage, MachineVolume, MemoryPressure, Method, Methods, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, PairingAuth, Platform, ProtocolError, RequestId, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, UnsubscribeParams, UsageSample, VIDEO_CODECS, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VideoCodec, VideoPacket, WorkspaceParams, protocolJsonSchema };
+export { ACTIONS, ActionName, ActionParams, ActionResult, BuildPlanParams, BuildPlanResult, CAPABILITIES, CONTROL_END_REASONS, Capability, ClientRequest, ControlBeginParams, ControlBeginResult, ControlEndParams, ControlEndedEvent, DEVICE_POSTURES, DeviceAuth, DevicePosture, ERROR_CODES, ErrorCode, ErrorEvent, FRAME_EDGE, FRAME_FPS, FrameDelayedEvent, FrameEvent, FrameTarget, FramesSubscribeResult, HelloParams, HelloResult, INPUT_BUTTONS, InputButton, InputButtonParams, InputPostureParams, InputRotateParams, InputTextParams, InputTouchParams, KeyframeParams, LOG_LEVELS, LOG_SOURCES, LogFilter, LogLevel, LogRecord, LogSource, LogsEvent, LogsQueryResult, MAX_INPUT_TEXT, MAX_LOG_TAIL, METHODS, MachineHistory, MachineHistoryParams, MachineUsage, MachineVolume, MemoryPressure, Method, Methods, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, PairingAuth, Platform, ProtocolError, RELOAD_PLATFORMS, ROTATE_DIRECTIONS, ReloadPlatform, RequestId, RotateDirection, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, TOUCH_PHASES, TouchPhase, UnsubscribeParams, UsageSample, VIDEO_CODECS, VIDEO_FOLDED, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VIDEO_UNFOLDED, VideoCodec, VideoPacket, WorkspaceParams, protocolJsonSchema };

package/dist/protocol.mjs

@@ -1,2 +1,2 @@
-import { a as FRAME_FPS, c as MAX_LOG_TAIL, d as PROTOCOL_VERSION, f as VIDEO_CODECS, h as protocolJsonSchema, i as FRAME_EDGE, l as METHODS, m as VIDEO_KEYFRAME, n as CAPABILITIES, o as LOG_LEVELS, p as VIDEO_HEADER_VERSION, r as ERROR_CODES, s as LOG_SOURCES, t as ACTIONS, u as PROTOCOL_SCHEMA_FILE } from "./protocol-CmlG7X7_.mjs";
-export { ACTIONS, CAPABILITIES, ERROR_CODES, FRAME_EDGE, FRAME_FPS, LOG_LEVELS, LOG_SOURCES, MAX_LOG_TAIL, METHODS, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, VIDEO_CODECS, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, protocolJsonSchema };
+import { C as VIDEO_UNFOLDED, S as VIDEO_KEYFRAME, _ as ROTATE_DIRECTIONS, a as ERROR_CODES, b as VIDEO_FOLDED, c as INPUT_BUTTONS, d as MAX_INPUT_TEXT, f as MAX_LOG_TAIL, g as RELOAD_PLATFORMS, h as PROTOCOL_VERSION, i as DEVICE_POSTURES, l as LOG_LEVELS, m as PROTOCOL_SCHEMA_FILE, n as CAPABILITIES, o as FRAME_EDGE, p as METHODS, r as CONTROL_END_REASONS, s as FRAME_FPS, t as ACTIONS, u as LOG_SOURCES, v as TOUCH_PHASES, w as protocolJsonSchema, x as VIDEO_HEADER_VERSION, y as VIDEO_CODECS } from "./protocol-rC-5KT1O.mjs";
+export { ACTIONS, CAPABILITIES, CONTROL_END_REASONS, DEVICE_POSTURES, ERROR_CODES, FRAME_EDGE, FRAME_FPS, INPUT_BUTTONS, LOG_LEVELS, LOG_SOURCES, MAX_INPUT_TEXT, MAX_LOG_TAIL, METHODS, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, RELOAD_PLATFORMS, ROTATE_DIRECTIONS, TOUCH_PHASES, VIDEO_CODECS, VIDEO_FOLDED, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VIDEO_UNFOLDED, protocolJsonSchema };