Repository navigation
Expand file tree
/
Copy pathinteractor-types.ts
More file actions
544 lines (518 loc) · 23.5 KB
/
Copy pathinteractor-types.ts
File metadata and controls
544 lines (518 loc) · 23.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
import type { ScreenshotScreenMask } from './screenshot.ts';
import type { AppStateRuntimeResult } from './app-state-runtime.ts';
import type { ElementTextTarget } from './element-text-target.ts';
import type { BackMode } from './back-mode.ts';
import type { IosSystemSurfaceProvenance } from './ios-system-surface.ts';
import type { DeviceRotation } from './device-rotation.ts';
import type { FillUnconfirmedVerification } from './fill-evidence.ts';
import type { ScrollDirection } from './scroll-gesture.ts';
import type { ScrollExecutionOptions } from './scroll-command.ts';
import type { TvRemoteButton } from './tv-remote.ts';
import type { GesturePlan } from './gesture-plan-types.ts';
import type { ReadSettingResult, SettingOptions } from './settings.ts';
import type { ReadableSetting } from './settings-catalog.ts';
import type { SessionSurface } from './session-surface.ts';
import type { BackendSnapshotResult } from './snapshot-types.ts';
import type { RunnerLogicalLeaseContext } from './runner-lease-context.ts';
import type {
IosAcquisitionProducer,
IosSnapshotAcquisitionFacts,
IosSnapshotComparisonIdentity,
} from './ios-snapshot.ts';
import type {
PresentedSurface,
RawSnapshotNode,
Point,
Rect,
IosTargetActivation,
SnapshotKeyboardBandFact,
SnapshotOptions as BaseSnapshotOptions,
SnapshotProvenance,
} from '@agent-device/kernel/snapshot';
export type RunnerContext = {
requestId?: string;
signal?: AbortSignal;
appBundleId?: string;
verbose?: boolean;
logPath?: string;
traceLogPath?: string;
iosXctestrunFile?: string;
iosXctestDerivedDataPath?: string;
iosXctestEnvDir?: string;
runnerLeaseContext?: RunnerLogicalLeaseContext;
};
/** Subset of {@link RunnerContext} forwarded to runner command invocations. */
export type RunnerCallOptions = Pick<
RunnerContext,
| 'signal'
| 'verbose'
| 'logPath'
| 'traceLogPath'
| 'requestId'
| 'iosXctestrunFile'
| 'iosXctestDerivedDataPath'
| 'iosXctestEnvDir'
| 'runnerLeaseContext'
>;
export type { BackMode };
export type ScreenshotOptions = {
appBundleId?: string;
pixelDensity?: number;
screenMask?: ScreenshotScreenMask;
fullscreen?: boolean;
normalizeStatusBar?: boolean;
stabilize?: boolean;
surface?: SessionSurface;
skipIosSimulatorBootCheck?: boolean;
captureBackend?: 'runner';
};
/**
* What the capture owner observed while writing the image. `displayRotation` is the rotation the display
* rendered the pixels in, so a landscape value pairs with a landscape image; it is absent when the
* owner has no rotation reading it can stand behind for this capture.
*/
export type ScreenshotCaptureFacts = Readonly<{
displayRotation?: DeviceRotation;
/** Actual physical iOS capture route, including any fallback from CoreDevice to XCTest. */
iosPhysicalCaptureBackend?: 'coredevice' | 'xctest';
}>;
export type ElementSelectorKey = 'id' | 'label' | 'text' | 'value';
export type ElementSelectorTapOptions = {
key: ElementSelectorKey;
value: string;
allowNonHittableCoordinateFallback?: boolean;
expectedPoint?: Point;
};
/** Text-input geometry from the capture that measured the tap point; the native owner decides admission. */
export type CoordinateTapTextInputEvidence = Readonly<{
targetBundleId: string;
point: Point;
textInputRects: readonly Rect[];
}>;
export type PressPointOptions = Readonly<{
button: 'primary' | 'secondary' | 'middle';
count: number;
intervalMs: number;
holdMs: number;
jitterPx: number;
doubleTap: boolean;
surface?: SessionSurface;
coordinateTapTextInputEvidence?: CoordinateTapTextInputEvidence;
}>;
/**
* Legacy success text retained for compatibility when the XCTest runner used
* the Maestro non-hittable coordinate fallback. Usage itself is carried by
* the structured `maestroNonHittableCoordinateFallbackUsed` runner field.
*/
export const MAESTRO_NON_HITTABLE_FALLBACK_MESSAGE = 'tapped via non-hittable coordinate fallback';
/**
* The channel the XCTest runner actually entered text through — the Swift
* `TextEntryResult.textEntryRoute` (RunnerTests+TextTyping.swift,
* RunnerTests+SynthesizedTextEntry.swift). Closed set, because the runner is
* its only producer and the boundary that narrows it
* (readTypeTextBackendResult, packages/platform-apple/src/interactions.ts) drops a
* route it cannot name — so a Swift-side addition would silently vanish. The
* route-parity test in packages/platform-apple/src/interactions.test.ts
* reads the Swift sources and fails instead.
*/
export const TEXT_ENTRY_ROUTES = [
'xctest-element',
'synthesized-first-responder',
'synthesized-first-responder-replacement',
'xctest-application-fallback',
] as const;
export type TextEntryRoute = (typeof TEXT_ENTRY_ROUTES)[number];
/**
* What `Interactor.type` reports back about the entry it performed. Only the
* Apple runner populates it; every other platform types blind and returns void.
*/
export type TypeTextBackendResult = {
textEntryRoute?: TextEntryRoute;
};
/**
* Focus evidence reported by a cloud `fill` before clearing or typing (#1658).
* The local Apple runner owns this discipline in Swift and reports it as a
* `textEntryRoute`; a cloud session has no runner,
* only what its provider will tell it, so it names what it observed instead of
* which channel it typed through. Listed strongest evidence first:
*
* - `focused-element`: after the tap, the element holding text-entry focus is the
* one this fill aimed at — positive evidence that THIS field, not merely some
* field, took focus. A field that focusing re-laid out still counts.
* Current cloud fills report `focused-element`, including clear-only fills.
* There is deliberately no value for "typed without evidence": nothing renders
* this field, so such a value would reach a caller as an ordinary success and
* recreate the #1658 silent false success it exists to remove. Every
* unwitnessed case throws without typing instead —
*
* - `text_entry_focus_not_observed`: the tap focused nothing or left the
* previous field focused outside the tapped point.
* - `text_entry_clear_target_unavailable`: the driver cannot report a focused
* element reference. An unsupported pre-tap lookup refuses before tapping.
*
* Closed set accepted by readFillBackendResult at the touch boundary. It drops
* values it cannot name.
*/
export const CLOUD_TEXT_ENTRY_READINESS = ['focused-element'] as const;
export type CloudTextEntryReadiness = (typeof CLOUD_TEXT_ENTRY_READINESS)[number];
/**
* What `Interactor.fill` reports back about the entry it performed. The cloud
* interactors using tree-based entry populate
* `textEntryReadiness`; Android and the Apple runner may return target-bound
* `verification: 'unconfirmed'` evidence when the field changed but its value
* cannot confirm the text (app-owned formatting, or an accessibility value that
* does not echo the entry). The Apple runner carries its own readiness
* equivalent in Swift.
*/
export type FillBackendResult =
| {
textEntryReadiness?: CloudTextEntryReadiness;
verification?: never;
}
| ({ textEntryReadiness?: CloudTextEntryReadiness } & FillUnconfirmedVerification);
export type SnapshotOptions = BaseSnapshotOptions & {
appBundleId?: string;
signal?: AbortSignal;
includeRects?: boolean;
includeHiddenContentHints?: boolean;
surface?: SessionSurface;
/** Internal capture purpose; action outcomes always require the full tree. */
acquisitionIntent?: 'full' | 'surface-observation';
/** A stored observation remains current; action and settling captures do not supply this fact. */
captureBasis?: 'unchanged-since-observation';
/**
* A one-off read, such as an open's launch observation. It may use a capture host the session
* already keeps warm, but it never installs one or leaves running one that it started. It starts
* no re-capture after `settleBy` (epoch ms); only `signal` cancels work already started.
*/
transient?: Readonly<{ settleBy: number }>;
};
/**
* Android's live IME status read. Optional on {@link Interactor}: parity with the retired leaf,
* which refused `status`/`get` on every other family (no other platform's runner exposes one).
* A single-member discriminated union rather than a bare object so the daemon can derive its wire
* `platform` label from `kind` the same way it does for dismiss and enter — an owner can only ever
* produce its own result shape.
*/
export type KeyboardStatusResult = Readonly<{
kind: 'ime-probe';
visible: boolean;
inputType?: string;
type?: string;
inputMethodPackage?: string;
focusedPackage?: string;
focusedResourceId?: string;
inputOwner?: string;
}>;
/**
* Owner-shaped dismiss evidence, discriminated by which owner produced it: Android's IME probe
* fields, or iOS's `mechanism` disclosure (#1598), or HarmonyOS's bare acknowledgment (its HDC
* key press reports nothing beyond success). The daemon derives the wire `platform` label from
* `kind` rather than re-deriving it from the device, so an owner can only ever produce its own
* result shape — an android-probe result under an `ios` label is unrepresentable.
*/
export type KeyboardDismissResult =
| Readonly<{
kind: 'ime-probe';
attempts?: number;
wasVisible?: boolean;
dismissed?: boolean;
visible?: boolean;
inputType?: string;
type?: string;
inputMethodPackage?: string;
focusedPackage?: string;
focusedResourceId?: string;
inputOwner?: string;
}>
| Readonly<{
kind: 'mechanism';
wasVisible?: boolean;
dismissed?: boolean;
visible?: boolean;
mechanism?: string;
}>
| Readonly<{ kind: 'acknowledged' }>;
/**
* Only the Apple runner echoes visibility around the return-key press; Android and HarmonyOS
* acknowledge with no fields beyond success. Kind is owner-specific, not just content-shaped —
* Android's and HarmonyOS's acknowledgments are structurally identical, so only the discriminant
* itself tells the daemon which owner actually pressed enter.
*/
export type KeyboardEnterResult =
| Readonly<{ kind: 'visibility-echo'; visible?: boolean; wasVisible?: boolean }>
| Readonly<{ kind: 'android-acknowledged' }>
| Readonly<{ kind: 'harmonyos-acknowledged' }>;
/**
* Every acquisition carries its provenance pair atomically: the channel alone cannot say who
* acquired the tree or which guarantees it carries, and `SnapshotProvenance`
* (`@agent-device/kernel/snapshot`) makes a cross-channel `backend`/`producer` combination
* fail to compile.
*/
export type SnapshotResult = Omit<BackendSnapshotResult, 'backend' | 'nodes'> & {
nodes?: RawSnapshotNode[];
comparisonIdentity?: IosSnapshotComparisonIdentity;
/**
* Set when the capture describes an in-place iOS system surface (a web sign-in sheet) presented
* over the session app rather than the app itself (#2438).
*/
systemSurface?: IosSystemSurfaceProvenance;
/**
* Whether this capture read a modal presentation over the app (#3565), computed by the producer on
* the acquired tree before any projection. Absent means the producer published no fact at all,
* which a consumer must treat as `'unknown'`.
*/
presentedSurface?: PresentedSurface;
/**
* Keyboard evidence acquired with this tree: measured `visible`, policy-derived `derived`,
* additive `visibility-only`, rejected `tree-rejected`, proven `absent`, or unknown `unmeasurable` facts. Measured and
* derived frames survive projection and take precedence over tree reconstruction. Visibility-only
* facts carry no band; rejected acquisition geometry stays rejected. Other failed measurements or
* an omitted fact may use tree geometry, but missing nodes never prove absence.
* See {@link SnapshotKeyboardBandFact}.
*/
keyboard?: SnapshotKeyboardBandFact;
/**
* Set when this capture's own command had to bring the session app back to the foreground, i.e.
* something else held it and an earlier observation described that instead (#2682).
*/
targetActivation?: IosTargetActivation;
} & SnapshotProvenance;
export type SnapshotRuntimeAcquiredResult = Readonly<{
stage: 'acquired';
acquisition: IosSnapshotAcquisitionFacts & Readonly<{ producer: IosAcquisitionProducer }>;
}>;
export type SnapshotRuntimeResult = SnapshotResult | SnapshotRuntimeAcquiredResult;
/** The application an owner's launch reports it started, when the launch names one. */
export type ApplicationLaunchReport = Readonly<{ launchedAppBundleId?: string }>;
export type Interactor = {
open(
app: string,
options?: {
activity?: string;
appBundleId?: string;
launchConsole?: string;
launchArgs?: string[];
terminateRunningApp?: boolean;
url?: string;
},
): Promise<ApplicationLaunchReport | void>;
openDevice(): Promise<void>;
close(app: string): Promise<void>;
tap(x: number, y: number): Promise<Record<string, unknown> | void>;
/** Complete point-press semantics for owners with fused series, alternate buttons, or surfaces. */
pressPoint?(point: Point, options: PressPointOptions): Promise<Record<string, unknown> | void>;
/** Alternate mouse buttons for owners that otherwise use the shared point-press series. */
alternateClick?(
point: Point,
button: 'secondary' | 'middle',
): Promise<Record<string, unknown> | void>;
/** Owner-native ref routes; currently the managed web runtime is their only local owner. */
tapRef?(ref: string): Promise<Record<string, unknown> | void>;
tapElementSelector?(selector: ElementSelectorTapOptions): Promise<Record<string, unknown> | void>;
/**
* Fused double-click for owners that have one. The shared `--count` series cannot stand in for it —
* it spaces and jitters independent presses rather than firing one pair the target reads as a
* double — so an owner with no such mechanic leaves this undefined and `press --double` reports the
* gap instead of resolving a denial.
*/
doubleTap?(x: number, y: number): Promise<Record<string, unknown> | void>;
longPress(x: number, y: number, durationMs?: number): Promise<Record<string, unknown> | void>;
/**
* How the app the runner context names is running, as the platform reports it. The Apple runner
* reads `XCUIApplication.state`; owners that read the foreground elsewhere leave it undefined.
*/
appState?(): Promise<AppStateRuntimeResult>;
/**
* Move the pointer to a point without pressing. Only pointer-driven
* platforms (web today) implement it; touch platforms have no hover state
* and leave it undefined, which the `hover` command reports as unsupported.
*/
hover?(x: number, y: number): Promise<Record<string, unknown> | void>;
hoverRef?(ref: string): Promise<Record<string, unknown> | void>;
focus(x: number, y: number): Promise<Record<string, unknown> | void>;
type(text: string, delayMs?: number): Promise<TypeTextBackendResult | void>;
/**
* Replace the target's text with `text`. The empty string is the clear request (#2063), not a
* no-op: an implementation must empty the field or fail — never report success over an
* untouched value. A backend with no clear mechanism refuses the empty text up front (see the
* webdriver interactor).
*/
fill(
x: number,
y: number,
text: string,
delayMs?: number,
options?: { allowNonHittableCoordinateFallback?: boolean },
): Promise<Record<string, unknown> | void>;
fillRef?(ref: string, text: string, delayMs?: number): Promise<Record<string, unknown> | void>;
scroll(
direction: ScrollDirection,
options?: ScrollExecutionOptions,
): Promise<Record<string, unknown> | void>;
screenshot(outPath: string, options?: ScreenshotOptions): Promise<ScreenshotCaptureFacts | void>;
setViewport?(width: number, height: number): Promise<Record<string, unknown> | void>;
snapshot(options?: SnapshotOptions): Promise<SnapshotRuntimeResult>;
/**
* Native reading of the live text at a point, when the backend has one. Answers the text the
* owner can see right now, which can exceed what an already-captured node carries (an editable
* field whose value is longer than its label). Optional: a backend without it leaves the
* captured tree as the complete answer.
*/
readTextAtPoint?(
point: Point,
options?: {
appBundleId?: string;
surface?: SessionSurface;
signal?: AbortSignal;
target?: ElementTextTarget;
},
): Promise<string | undefined>;
/**
* Native text-presence reading, when the backend has one that does not require a tree capture.
* A `true` answer is authoritative; anything else means "not proven here" and the caller
* consults the canonical tree (see `FindTextResult`).
*/
findText?(
text: string,
options?: { appBundleId?: string; signal?: AbortSignal },
): Promise<{
found: boolean;
}>;
gestureViewport?(): Promise<Rect>;
back(mode?: BackMode): Promise<void>;
/**
* Optional (parity with `actionButton`): opens the springboard, a control not every owner
* carries. An owner without it leaves it undefined; its fact refuses the press before binding,
* and the system-button binder fails closed rather than resolving an absent member as a
* successful no-op.
*/
home?(): Promise<void>;
setOrientation(orientation: DeviceRotation): Promise<{ orientation?: DeviceRotation } | void>;
/** Hands rotation back to the sensor; only an owner whose `setOrientation` locks it carries this. */
unlockOrientation?(): Promise<void>;
performGesture?(plan: GesturePlan): Promise<Record<string, unknown> | void>;
/**
* Optional (parity with `home`): opens the recents surface, a control not every owner carries.
* An owner without it leaves it undefined; its fact refuses the press before binding, and the
* system-button binder fails closed rather than resolving an absent member as a successful
* no-op.
*/
appSwitcher?(): Promise<void>;
/**
* Optional (parity with `home`): presses one TV remote key, a control only TV-capable owners
* carry. An owner without it leaves it undefined; its fact refuses the press before binding,
* and the TV remote binder fails closed rather than resolving an absent member as a silent
* no-op.
*/
tvRemote?(button: TvRemoteButton, durationMs?: number): Promise<void>;
/**
* Optional (parity with `keyboardDismiss`): presses the iPhone/iPad Action Button, hardware only
* the Apple owner carries. An owner without the button leaves it undefined; its fact refuses the
* press before binding, and the system-button binder fails closed rather than resolving an
* absent member as a successful no-op.
*/
actionButton?(): Promise<void>;
/**
* Optional (parity with `home`): presses the physical volume-up key once, a control phone
* owners with a volume button carry. An owner without it leaves it undefined; its fact refuses
* the press before binding, and the system-button binder fails closed rather than resolving an
* absent member as a silent no-op.
*/
volumeUp?(): Promise<void>;
/**
* Optional (parity with `volumeUp`): presses the physical volume-down key once.
*/
volumeDown?(): Promise<void>;
/**
* Optional (parity with `volumeUp`): presses the physical power key once, which toggles the
* screen on Android. Apple exposes no public power/lock button press, so no Apple leaf carries
* it; an owner without it leaves it undefined and its fact refuses before binding.
*/
power?(): Promise<void>;
/**
* Optional (parity with `volumeUp`): presses the media mute key once. Android-only today:
* Apple exposes no public mute press, so no Apple leaf carries it.
*/
mute?(): Promise<void>;
/**
* Optional (parity with `volumeUp`): sends the explicit Android sleep event (KEYCODE_SLEEP),
* which turns the screen off without toggling the way `power` does.
*/
sleep?(): Promise<void>;
/**
* Optional (parity with `volumeUp`): sends the explicit Android wake event (KEYCODE_WAKEUP),
* which turns the screen on without toggling the way `power` does.
*/
wake?(): Promise<void>;
/**
* Optional (parity with `volumeUp`): presses the media play/pause key once. The press goes to
* whatever media session the OS routes it to; it does not claim playback started.
*/
mediaPlayPause?(): Promise<void>;
/** Optional (parity with `mediaPlayPause`): presses the media next key once. */
mediaNext?(): Promise<void>;
/** Optional (parity with `mediaPlayPause`): presses the media previous key once. */
mediaPrevious?(): Promise<void>;
/** Optional (parity with `mediaPlayPause`): presses the media rewind key once. */
mediaRewind?(): Promise<void>;
/** Optional (parity with `mediaPlayPause`): presses the media fast-forward key once. */
mediaFastForward?(): Promise<void>;
/** Optional: only Android implements a live status read (see {@link KeyboardStatusResult}). */
keyboardStatus?(): Promise<KeyboardStatusResult>;
/** Optional: platforms with no keyboard-dismiss concept leave it undefined. */
keyboardDismiss?(): Promise<KeyboardDismissResult>;
/** Optional: platforms with no keyboard-return concept leave it undefined. */
keyboardEnter?(): Promise<KeyboardEnterResult>;
/**
* Optional (parity with `readSetting`): the owner's pasteboard read. An owner with no clipboard
* surface leaves both halves undefined; its fact refuses the half before binding, and the
* clipboard binder fails closed rather than resolving an absent member as an empty answer.
*/
readClipboard?(): Promise<string>;
/**
* Optional (parity with `readClipboard`): the owner's pasteboard write, with the same
* fact-then-guard contract as the read.
*/
writeClipboard?(text: string): Promise<void>;
setSetting(
setting: string,
state: string,
appId?: string,
options?: SettingOptions,
): Promise<Record<string, unknown> | void>;
/**
* Optional: reads back the value a device holds for one readable setting. The name is narrowed to
* `READABLE_SETTINGS`, which is not every setting the write switch serves, and an owner's dispatch
* is exhaustive over it — a setting joins the list only with an owner that answers it. An owner with
* no read path leaves the member undefined; its fact refuses the read before binding, so an absent
* method can never resolve into an empty answer.
*/
readSetting?(setting: ReadableSetting): Promise<ReadSettingResult>;
/**
* The four alert legs. Each owner runs its own observation and, where it needs one, its own
* poll: an alert is a transient device surface, and how long to look for it — and how to press
* its buttons — is family mechanics, not something a caller can supply. `timeoutMs` is the
* whole window the caller allows; the owner spends it however its backend requires.
*
* Optional: an owner with no alert surface leaves all four undefined. Its facts refuse every leg
* before binding, so the absent members are never resolved, and a fact that admitted a leg the
* interactor cannot serve fails closed instead of answering empty.
*/
readAlert?(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
awaitAlert?(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
acceptAlert?(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
dismissAlert?(options?: AlertInteractorOptions): Promise<Record<string, unknown>>;
};
/**
* The session-derived target one alert leg acts on. `appBundleId` is separate from the runner
* context's because the macOS helper reads a frontmost-app surface with no bundle at all, and
* the two must not collapse into one field that means both.
*/
export type AlertInteractorOptions = {
timeoutMs?: number;
/** The daemon request's cancellation; owners whose transport can abort thread it into the legs. */
signal?: AbortSignal;
appBundleId?: string;
surface?: SessionSurface;
};