@xpert-ai/chatkit-host-automation 0.3.7 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +848 -76
  2. package/dist/index.js +1972 -880
  3. package/package.json +2 -2
package/dist/index.d.ts CHANGED
@@ -1,18 +1,219 @@
1
1
  import { ClientToolMessageInput } from '../../chatkit/src/index.ts';
2
2
 
3
+ export declare type ActionExpectation = {
4
+ type: 'field_contains';
5
+ target: ObservationTargetDescriptor;
6
+ value: string;
7
+ } | {
8
+ type: 'checked_equals';
9
+ target: ObservationTargetDescriptor;
10
+ value: boolean;
11
+ } | {
12
+ type: 'element_visible';
13
+ target: ObservationTargetDescriptor;
14
+ } | {
15
+ type: 'element_hidden';
16
+ target: ObservationTargetDescriptor;
17
+ } | {
18
+ type: 'url_matches';
19
+ mode: 'exact' | 'prefix';
20
+ value: string;
21
+ } | {
22
+ type: 'text_visible';
23
+ scope: ObservationScope;
24
+ value: string;
25
+ };
26
+
27
+ export declare type ActionOutcome = 'verified' | 'verification_failed' | 'executed_unverified' | 'rejected_before_execution';
28
+
29
+ export declare function addBrowserActionEvidence(action: string, url: string, value: unknown): unknown;
30
+
31
+ export declare type BrowserActionApprovalReason = 'approval_required' | 'invalid_or_used_token' | 'expired_token' | 'state_mismatch' | 'action_mismatch';
32
+
33
+ export declare type BrowserActionResult = {
34
+ dispatched: boolean;
35
+ outcome: ActionOutcome;
36
+ requiresFreshSnapshot: boolean;
37
+ invalidatedPageStateId?: string;
38
+ resolution?: TargetResolution;
39
+ verification?: VerificationResult;
40
+ evidence?: ClientActionEvidence;
41
+ error?: BrowserAutomationError;
42
+ };
43
+
44
+ export declare type BrowserActionRisk = 'password_input' | 'file_input' | 'form_submit' | 'cross_origin_navigation' | 'download';
45
+
46
+ export declare type BrowserAutomationError = {
47
+ code: BrowserAutomationErrorCode;
48
+ message: string;
49
+ recoverable: boolean;
50
+ resolution?: TargetResolution;
51
+ actionToken?: string;
52
+ approvalReason?: BrowserActionApprovalReason;
53
+ expiresAt?: string;
54
+ risks?: BrowserActionRisk[];
55
+ };
56
+
57
+ export declare type BrowserAutomationErrorCode = 'stale_page_state' | 'stale_target' | 'target_not_found' | 'ambiguous_target' | 'unsafe_selector' | 'non_unique_selector' | 'target_disabled' | 'target_occluded' | 'coordinate_target_mismatch' | 'coordinate_target_ambiguous' | 'unsupported_target_scope' | 'approval_required';
58
+
59
+ export declare type BrowserAutomationV2Capabilities = {
60
+ targetingVersion: 2;
61
+ strictRefs: true;
62
+ strictCoordinates: true;
63
+ freshState: true;
64
+ postconditions: boolean;
65
+ policyGate: boolean;
66
+ actionTrace: boolean;
67
+ };
68
+
69
+ export declare type BrowserDocumentDescriptor = {
70
+ documentRef: string;
71
+ frameRef?: string;
72
+ parentDocumentRef?: string;
73
+ sameOrigin: boolean;
74
+ };
75
+
76
+ export declare type ClientActionEvidence = {
77
+ timestamp: string;
78
+ pageStateId: string;
79
+ url: string;
80
+ requested?: TargetDescriptor | CoordinateTargetDescriptor;
81
+ resolution?: TargetResolution;
82
+ action: HostPageAutomationToolName;
83
+ outcome: ActionOutcome;
84
+ verification?: VerificationResult;
85
+ beforeScreenshotId?: string;
86
+ afterScreenshotId?: string;
87
+ };
88
+
89
+ export declare type CoordinateTargetDescriptor = PageBoundTarget & {
90
+ kind: 'coordinate';
91
+ x: number;
92
+ y: number;
93
+ coordinateSpace: 'viewport-css-px' | 'viewport_normalized';
94
+ targetText: string;
95
+ targetRole?: string;
96
+ targetContext?: string;
97
+ };
98
+
3
99
  export declare function createHostPageAutomationClientToolHandler(options?: HostPageAutomationOptions): HostPageAutomationClientToolHandler;
4
100
 
101
+ export declare type ElementDescriptor = {
102
+ documentRef: string;
103
+ ref?: string;
104
+ axRef?: string;
105
+ tag: string;
106
+ role?: string;
107
+ name?: string;
108
+ text?: string;
109
+ testId?: string;
110
+ rect: {
111
+ x: number;
112
+ y: number;
113
+ width: number;
114
+ height: number;
115
+ };
116
+ };
117
+
5
118
  export declare const HOST_PAGE_AUTOMATION_TOOL_NAMES: readonly ["host_page_snapshot", "host_page_click", "host_page_fill", "host_page_press", "host_page_select", "host_page_scroll", "host_page_navigate", "host_page_hover", "host_page_focus", "host_page_pointer", "host_page_screenshot", "host_page_read", "host_page_wait_for"];
6
119
 
7
120
  export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
8
121
  readonly host_page_snapshot: {
9
122
  readonly type: "object";
10
- readonly properties: {};
123
+ readonly properties: {
124
+ readonly pageStateId: {
125
+ readonly type: "string";
126
+ readonly description: "Reuse the cached snapshot state when reading another paginated page.";
127
+ };
128
+ };
11
129
  readonly additionalProperties: false;
12
130
  };
13
131
  readonly host_page_click: {
14
132
  readonly type: "object";
15
133
  readonly properties: {
134
+ readonly expectation: {
135
+ type: string;
136
+ properties: {
137
+ type: {
138
+ type: string;
139
+ enum: string[];
140
+ };
141
+ target: {
142
+ type: string;
143
+ properties: {
144
+ documentScope: {
145
+ type: string;
146
+ enum: string[];
147
+ };
148
+ documentRef: {
149
+ type: string;
150
+ };
151
+ kind: {
152
+ type: string;
153
+ enum: string[];
154
+ };
155
+ testId: {
156
+ type: string;
157
+ };
158
+ selector: {
159
+ type: string;
160
+ };
161
+ match: {
162
+ const: string;
163
+ };
164
+ identity: {
165
+ type: string;
166
+ properties: {
167
+ role: {
168
+ type: string;
169
+ };
170
+ name: {
171
+ type: string;
172
+ };
173
+ text: {
174
+ type: string;
175
+ };
176
+ };
177
+ required: string[];
178
+ additionalProperties: false;
179
+ };
180
+ };
181
+ required: string[];
182
+ additionalProperties: false;
183
+ };
184
+ scope: {
185
+ type: string;
186
+ properties: {
187
+ documentScope: {
188
+ type: string;
189
+ enum: string[];
190
+ };
191
+ documentRef: {
192
+ type: string;
193
+ };
194
+ };
195
+ required: string[];
196
+ additionalProperties: false;
197
+ };
198
+ mode: {
199
+ type: string;
200
+ enum: string[];
201
+ };
202
+ value: {
203
+ type: string[];
204
+ };
205
+ };
206
+ required: string[];
207
+ additionalProperties: false;
208
+ };
209
+ readonly pageStateId: {
210
+ type: string;
211
+ description: string;
212
+ };
213
+ readonly documentRef: {
214
+ type: string;
215
+ description: string;
216
+ };
16
217
  readonly ref: {
17
218
  type: string[];
18
219
  description: string;
@@ -41,14 +242,6 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
41
242
  type: string;
42
243
  description: string;
43
244
  };
44
- readonly x: {
45
- type: string;
46
- description: string;
47
- };
48
- readonly y: {
49
- type: string;
50
- description: string;
51
- };
52
245
  };
53
246
  readonly additionalProperties: false;
54
247
  };
@@ -59,6 +252,89 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
59
252
  readonly type: "string";
60
253
  readonly description: "Text value to set on the target field.";
61
254
  };
255
+ readonly expectation: {
256
+ type: string;
257
+ properties: {
258
+ type: {
259
+ type: string;
260
+ enum: string[];
261
+ };
262
+ target: {
263
+ type: string;
264
+ properties: {
265
+ documentScope: {
266
+ type: string;
267
+ enum: string[];
268
+ };
269
+ documentRef: {
270
+ type: string;
271
+ };
272
+ kind: {
273
+ type: string;
274
+ enum: string[];
275
+ };
276
+ testId: {
277
+ type: string;
278
+ };
279
+ selector: {
280
+ type: string;
281
+ };
282
+ match: {
283
+ const: string;
284
+ };
285
+ identity: {
286
+ type: string;
287
+ properties: {
288
+ role: {
289
+ type: string;
290
+ };
291
+ name: {
292
+ type: string;
293
+ };
294
+ text: {
295
+ type: string;
296
+ };
297
+ };
298
+ required: string[];
299
+ additionalProperties: false;
300
+ };
301
+ };
302
+ required: string[];
303
+ additionalProperties: false;
304
+ };
305
+ scope: {
306
+ type: string;
307
+ properties: {
308
+ documentScope: {
309
+ type: string;
310
+ enum: string[];
311
+ };
312
+ documentRef: {
313
+ type: string;
314
+ };
315
+ };
316
+ required: string[];
317
+ additionalProperties: false;
318
+ };
319
+ mode: {
320
+ type: string;
321
+ enum: string[];
322
+ };
323
+ value: {
324
+ type: string[];
325
+ };
326
+ };
327
+ required: string[];
328
+ additionalProperties: false;
329
+ };
330
+ readonly pageStateId: {
331
+ type: string;
332
+ description: string;
333
+ };
334
+ readonly documentRef: {
335
+ type: string;
336
+ description: string;
337
+ };
62
338
  readonly ref: {
63
339
  type: string[];
64
340
  description: string;
@@ -87,14 +363,6 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
87
363
  type: string;
88
364
  description: string;
89
365
  };
90
- readonly x: {
91
- type: string;
92
- description: string;
93
- };
94
- readonly y: {
95
- type: string;
96
- description: string;
97
- };
98
366
  };
99
367
  readonly required: readonly ["value"];
100
368
  readonly additionalProperties: false;
@@ -106,6 +374,89 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
106
374
  readonly type: "string";
107
375
  readonly description: "Keyboard key to press.";
108
376
  };
377
+ readonly expectation: {
378
+ type: string;
379
+ properties: {
380
+ type: {
381
+ type: string;
382
+ enum: string[];
383
+ };
384
+ target: {
385
+ type: string;
386
+ properties: {
387
+ documentScope: {
388
+ type: string;
389
+ enum: string[];
390
+ };
391
+ documentRef: {
392
+ type: string;
393
+ };
394
+ kind: {
395
+ type: string;
396
+ enum: string[];
397
+ };
398
+ testId: {
399
+ type: string;
400
+ };
401
+ selector: {
402
+ type: string;
403
+ };
404
+ match: {
405
+ const: string;
406
+ };
407
+ identity: {
408
+ type: string;
409
+ properties: {
410
+ role: {
411
+ type: string;
412
+ };
413
+ name: {
414
+ type: string;
415
+ };
416
+ text: {
417
+ type: string;
418
+ };
419
+ };
420
+ required: string[];
421
+ additionalProperties: false;
422
+ };
423
+ };
424
+ required: string[];
425
+ additionalProperties: false;
426
+ };
427
+ scope: {
428
+ type: string;
429
+ properties: {
430
+ documentScope: {
431
+ type: string;
432
+ enum: string[];
433
+ };
434
+ documentRef: {
435
+ type: string;
436
+ };
437
+ };
438
+ required: string[];
439
+ additionalProperties: false;
440
+ };
441
+ mode: {
442
+ type: string;
443
+ enum: string[];
444
+ };
445
+ value: {
446
+ type: string[];
447
+ };
448
+ };
449
+ required: string[];
450
+ additionalProperties: false;
451
+ };
452
+ readonly pageStateId: {
453
+ type: string;
454
+ description: string;
455
+ };
456
+ readonly documentRef: {
457
+ type: string;
458
+ description: string;
459
+ };
109
460
  readonly ref: {
110
461
  type: string[];
111
462
  description: string;
@@ -134,14 +485,6 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
134
485
  type: string;
135
486
  description: string;
136
487
  };
137
- readonly x: {
138
- type: string;
139
- description: string;
140
- };
141
- readonly y: {
142
- type: string;
143
- description: string;
144
- };
145
488
  };
146
489
  readonly required: readonly ["key"];
147
490
  readonly additionalProperties: false;
@@ -163,6 +506,89 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
163
506
  readonly type: "string";
164
507
  };
165
508
  };
509
+ readonly expectation: {
510
+ type: string;
511
+ properties: {
512
+ type: {
513
+ type: string;
514
+ enum: string[];
515
+ };
516
+ target: {
517
+ type: string;
518
+ properties: {
519
+ documentScope: {
520
+ type: string;
521
+ enum: string[];
522
+ };
523
+ documentRef: {
524
+ type: string;
525
+ };
526
+ kind: {
527
+ type: string;
528
+ enum: string[];
529
+ };
530
+ testId: {
531
+ type: string;
532
+ };
533
+ selector: {
534
+ type: string;
535
+ };
536
+ match: {
537
+ const: string;
538
+ };
539
+ identity: {
540
+ type: string;
541
+ properties: {
542
+ role: {
543
+ type: string;
544
+ };
545
+ name: {
546
+ type: string;
547
+ };
548
+ text: {
549
+ type: string;
550
+ };
551
+ };
552
+ required: string[];
553
+ additionalProperties: false;
554
+ };
555
+ };
556
+ required: string[];
557
+ additionalProperties: false;
558
+ };
559
+ scope: {
560
+ type: string;
561
+ properties: {
562
+ documentScope: {
563
+ type: string;
564
+ enum: string[];
565
+ };
566
+ documentRef: {
567
+ type: string;
568
+ };
569
+ };
570
+ required: string[];
571
+ additionalProperties: false;
572
+ };
573
+ mode: {
574
+ type: string;
575
+ enum: string[];
576
+ };
577
+ value: {
578
+ type: string[];
579
+ };
580
+ };
581
+ required: string[];
582
+ additionalProperties: false;
583
+ };
584
+ readonly pageStateId: {
585
+ type: string;
586
+ description: string;
587
+ };
588
+ readonly documentRef: {
589
+ type: string;
590
+ description: string;
591
+ };
166
592
  readonly ref: {
167
593
  type: string[];
168
594
  description: string;
@@ -191,14 +617,6 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
191
617
  type: string;
192
618
  description: string;
193
619
  };
194
- readonly x: {
195
- type: string;
196
- description: string;
197
- };
198
- readonly y: {
199
- type: string;
200
- description: string;
201
- };
202
620
  };
203
621
  readonly additionalProperties: false;
204
622
  };
@@ -213,6 +631,97 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
213
631
  readonly type: "number";
214
632
  readonly description: "Vertical scroll delta.";
215
633
  };
634
+ readonly x: {
635
+ readonly type: "number";
636
+ readonly description: "Absolute horizontal scroll position.";
637
+ };
638
+ readonly y: {
639
+ readonly type: "number";
640
+ readonly description: "Absolute vertical scroll position.";
641
+ };
642
+ readonly expectation: {
643
+ type: string;
644
+ properties: {
645
+ type: {
646
+ type: string;
647
+ enum: string[];
648
+ };
649
+ target: {
650
+ type: string;
651
+ properties: {
652
+ documentScope: {
653
+ type: string;
654
+ enum: string[];
655
+ };
656
+ documentRef: {
657
+ type: string;
658
+ };
659
+ kind: {
660
+ type: string;
661
+ enum: string[];
662
+ };
663
+ testId: {
664
+ type: string;
665
+ };
666
+ selector: {
667
+ type: string;
668
+ };
669
+ match: {
670
+ const: string;
671
+ };
672
+ identity: {
673
+ type: string;
674
+ properties: {
675
+ role: {
676
+ type: string;
677
+ };
678
+ name: {
679
+ type: string;
680
+ };
681
+ text: {
682
+ type: string;
683
+ };
684
+ };
685
+ required: string[];
686
+ additionalProperties: false;
687
+ };
688
+ };
689
+ required: string[];
690
+ additionalProperties: false;
691
+ };
692
+ scope: {
693
+ type: string;
694
+ properties: {
695
+ documentScope: {
696
+ type: string;
697
+ enum: string[];
698
+ };
699
+ documentRef: {
700
+ type: string;
701
+ };
702
+ };
703
+ required: string[];
704
+ additionalProperties: false;
705
+ };
706
+ mode: {
707
+ type: string;
708
+ enum: string[];
709
+ };
710
+ value: {
711
+ type: string[];
712
+ };
713
+ };
714
+ required: string[];
715
+ additionalProperties: false;
716
+ };
717
+ readonly pageStateId: {
718
+ type: string;
719
+ description: string;
720
+ };
721
+ readonly documentRef: {
722
+ type: string;
723
+ description: string;
724
+ };
216
725
  readonly ref: {
217
726
  type: string[];
218
727
  description: string;
@@ -241,24 +750,99 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
241
750
  type: string;
242
751
  description: string;
243
752
  };
244
- readonly x: {
245
- type: string;
246
- description: string;
247
- };
248
- readonly y: {
249
- type: string;
250
- description: string;
251
- };
252
753
  };
253
754
  readonly additionalProperties: false;
254
755
  };
255
756
  readonly host_page_navigate: {
256
757
  readonly type: "object";
257
758
  readonly properties: {
759
+ readonly pageStateId: {
760
+ type: string;
761
+ description: string;
762
+ };
763
+ readonly documentRef: {
764
+ type: string;
765
+ description: string;
766
+ };
258
767
  readonly url: {
259
768
  readonly type: "string";
260
769
  readonly description: "HTTP(S) URL to navigate to.";
261
770
  };
771
+ readonly expectation: {
772
+ type: string;
773
+ properties: {
774
+ type: {
775
+ type: string;
776
+ enum: string[];
777
+ };
778
+ target: {
779
+ type: string;
780
+ properties: {
781
+ documentScope: {
782
+ type: string;
783
+ enum: string[];
784
+ };
785
+ documentRef: {
786
+ type: string;
787
+ };
788
+ kind: {
789
+ type: string;
790
+ enum: string[];
791
+ };
792
+ testId: {
793
+ type: string;
794
+ };
795
+ selector: {
796
+ type: string;
797
+ };
798
+ match: {
799
+ const: string;
800
+ };
801
+ identity: {
802
+ type: string;
803
+ properties: {
804
+ role: {
805
+ type: string;
806
+ };
807
+ name: {
808
+ type: string;
809
+ };
810
+ text: {
811
+ type: string;
812
+ };
813
+ };
814
+ required: string[];
815
+ additionalProperties: false;
816
+ };
817
+ };
818
+ required: string[];
819
+ additionalProperties: false;
820
+ };
821
+ scope: {
822
+ type: string;
823
+ properties: {
824
+ documentScope: {
825
+ type: string;
826
+ enum: string[];
827
+ };
828
+ documentRef: {
829
+ type: string;
830
+ };
831
+ };
832
+ required: string[];
833
+ additionalProperties: false;
834
+ };
835
+ mode: {
836
+ type: string;
837
+ enum: string[];
838
+ };
839
+ value: {
840
+ type: string[];
841
+ };
842
+ };
843
+ required: string[];
844
+ additionalProperties: false;
845
+ };
262
846
  };
263
847
  readonly required: readonly ["url"];
264
848
  readonly additionalProperties: false;
@@ -266,6 +850,14 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
266
850
  readonly host_page_hover: {
267
851
  readonly type: "object";
268
852
  readonly properties: {
853
+ readonly pageStateId: {
854
+ type: string;
855
+ description: string;
856
+ };
857
+ readonly documentRef: {
858
+ type: string;
859
+ description: string;
860
+ };
269
861
  readonly ref: {
270
862
  type: string[];
271
863
  description: string;
@@ -294,20 +886,20 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
294
886
  type: string;
295
887
  description: string;
296
888
  };
297
- readonly x: {
298
- type: string;
299
- description: string;
300
- };
301
- readonly y: {
302
- type: string;
303
- description: string;
304
- };
305
889
  };
306
890
  readonly additionalProperties: false;
307
891
  };
308
892
  readonly host_page_focus: {
309
893
  readonly type: "object";
310
894
  readonly properties: {
895
+ readonly pageStateId: {
896
+ type: string;
897
+ description: string;
898
+ };
899
+ readonly documentRef: {
900
+ type: string;
901
+ description: string;
902
+ };
311
903
  readonly ref: {
312
904
  type: string[];
313
905
  description: string;
@@ -336,14 +928,6 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
336
928
  type: string;
337
929
  description: string;
338
930
  };
339
- readonly x: {
340
- type: string;
341
- description: string;
342
- };
343
- readonly y: {
344
- type: string;
345
- description: string;
346
- };
347
931
  };
348
932
  readonly additionalProperties: false;
349
933
  };
@@ -365,7 +949,90 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
365
949
  };
366
950
  readonly targetText: {
367
951
  readonly type: "string";
368
- readonly description: "Required for explicit coordinate clicks. The actual hit target or near ancestor must contain this text.";
952
+ readonly description: "Required for explicit coordinate clicks. Must exactly match the hit target or a finite actionable ancestor.";
953
+ };
954
+ readonly targetRole: {
955
+ readonly type: "string";
956
+ readonly description: "Exact role used to disambiguate coordinate targets.";
957
+ };
958
+ readonly targetContext: {
959
+ readonly type: "string";
960
+ readonly description: "Nearby exact context used to disambiguate coordinates.";
961
+ };
962
+ readonly expectation: {
963
+ type: string;
964
+ properties: {
965
+ type: {
966
+ type: string;
967
+ enum: string[];
968
+ };
969
+ target: {
970
+ type: string;
971
+ properties: {
972
+ documentScope: {
973
+ type: string;
974
+ enum: string[];
975
+ };
976
+ documentRef: {
977
+ type: string;
978
+ };
979
+ kind: {
980
+ type: string;
981
+ enum: string[];
982
+ };
983
+ testId: {
984
+ type: string;
985
+ };
986
+ selector: {
987
+ type: string;
988
+ };
989
+ match: {
990
+ const: string;
991
+ };
992
+ identity: {
993
+ type: string;
994
+ properties: {
995
+ role: {
996
+ type: string;
997
+ };
998
+ name: {
999
+ type: string;
1000
+ };
1001
+ text: {
1002
+ type: string;
1003
+ };
1004
+ };
1005
+ required: string[];
1006
+ additionalProperties: false;
1007
+ };
1008
+ };
1009
+ required: string[];
1010
+ additionalProperties: false;
1011
+ };
1012
+ scope: {
1013
+ type: string;
1014
+ properties: {
1015
+ documentScope: {
1016
+ type: string;
1017
+ enum: string[];
1018
+ };
1019
+ documentRef: {
1020
+ type: string;
1021
+ };
1022
+ };
1023
+ required: string[];
1024
+ additionalProperties: false;
1025
+ };
1026
+ mode: {
1027
+ type: string;
1028
+ enum: string[];
1029
+ };
1030
+ value: {
1031
+ type: string[];
1032
+ };
1033
+ };
1034
+ required: string[];
1035
+ additionalProperties: false;
369
1036
  };
370
1037
  readonly expectedAfterClick: {
371
1038
  type: string;
@@ -386,11 +1053,27 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
386
1053
  required: string[];
387
1054
  additionalProperties: false;
388
1055
  };
1056
+ readonly x: {
1057
+ type: string;
1058
+ description: string;
1059
+ };
1060
+ readonly y: {
1061
+ type: string;
1062
+ description: string;
1063
+ };
389
1064
  readonly coordinateSpace: {
390
1065
  type: string;
391
1066
  enum: string[];
392
1067
  description: string;
393
1068
  };
1069
+ readonly pageStateId: {
1070
+ type: string;
1071
+ description: string;
1072
+ };
1073
+ readonly documentRef: {
1074
+ type: string;
1075
+ description: string;
1076
+ };
394
1077
  readonly ref: {
395
1078
  type: string[];
396
1079
  description: string;
@@ -419,14 +1102,6 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
419
1102
  type: string;
420
1103
  description: string;
421
1104
  };
422
- readonly x: {
423
- type: string;
424
- description: string;
425
- };
426
- readonly y: {
427
- type: string;
428
- description: string;
429
- };
430
1105
  };
431
1106
  readonly additionalProperties: false;
432
1107
  };
@@ -493,6 +1168,14 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
493
1168
  readonly type: "number";
494
1169
  readonly description: "Maximum wait time in seconds.";
495
1170
  };
1171
+ readonly pageStateId: {
1172
+ type: string;
1173
+ description: string;
1174
+ };
1175
+ readonly documentRef: {
1176
+ type: string;
1177
+ description: string;
1178
+ };
496
1179
  readonly ref: {
497
1180
  type: string[];
498
1181
  description: string;
@@ -521,14 +1204,6 @@ export declare const HOST_PAGE_AUTOMATION_TOOL_SCHEMAS: {
521
1204
  type: string;
522
1205
  description: string;
523
1206
  };
524
- readonly x: {
525
- type: string;
526
- description: string;
527
- };
528
- readonly y: {
529
- type: string;
530
- description: string;
531
- };
532
1207
  };
533
1208
  readonly additionalProperties: false;
534
1209
  };
@@ -553,6 +1228,7 @@ export declare type HostPageAutomationClientToolCall = {
553
1228
  export declare type HostPageAutomationClientToolHandler = (call: HostPageAutomationClientToolCall) => Promise<ClientToolMessageInput> | ClientToolMessageInput;
554
1229
 
555
1230
  export declare type HostPageAutomationElementSnapshot = {
1231
+ documentRef: string;
556
1232
  ref: string;
557
1233
  tag: string;
558
1234
  role?: string;
@@ -617,10 +1293,22 @@ export declare class HostPageAutomationExecutor {
617
1293
  private refs;
618
1294
  private nextRef;
619
1295
  private readableContent?;
1296
+ private pageStateId;
1297
+ private documentRefs;
1298
+ private documents;
1299
+ private lastResolution?;
1300
+ private pageStateInvalidated;
1301
+ private cachedSnapshot?;
1302
+ private cachedSnapshotCreatedAt;
1303
+ private mutationObservers;
1304
+ private pendingActionApprovals;
620
1305
  constructor(options?: HostPageAutomationOptions);
621
1306
  execute(name: HostPageAutomationToolName, params?: Record<string, unknown>): Promise<unknown>;
622
- snapshot(): HostPageSnapshot;
1307
+ snapshot(params?: Record<string, unknown>): HostPageSnapshot;
623
1308
  private getRoot;
1309
+ private indexDocuments;
1310
+ private disconnectMutationObservers;
1311
+ private observePageState;
624
1312
  private invalidateReadableContent;
625
1313
  private getNavigationState;
626
1314
  private getFrameState;
@@ -628,6 +1316,16 @@ export declare class HostPageAutomationExecutor {
628
1316
  private snapshotElementWithoutRef;
629
1317
  private createElementSnapshot;
630
1318
  private resolveElement;
1319
+ private rejectStalePageState;
1320
+ private assertCurrentPageState;
1321
+ private executeAction;
1322
+ private requireActionApproval;
1323
+ private getObservationDocument;
1324
+ private resolveObservationTarget;
1325
+ private checkExpectation;
1326
+ private verifyExpectation;
1327
+ private rejectTarget;
1328
+ private describeElementDescriptor;
631
1329
  private click;
632
1330
  private read;
633
1331
  private fill;
@@ -753,15 +1451,17 @@ declare type HostPageReadableContentSuggestedRead = {
753
1451
  };
754
1452
 
755
1453
  export declare type HostPageSnapshot = {
1454
+ pageStateId: string;
756
1455
  url: string;
757
1456
  title: string;
758
- capabilities?: {
1457
+ capabilities: BrowserAutomationV2Capabilities & {
759
1458
  cdp?: boolean;
760
1459
  realInput?: boolean;
761
1460
  screenshot?: boolean;
762
1461
  accessibility?: boolean;
763
1462
  networkState?: boolean;
764
1463
  };
1464
+ documents: BrowserDocumentDescriptor[];
765
1465
  viewport: {
766
1466
  width: number;
767
1467
  height: number;
@@ -823,4 +1523,76 @@ export declare type JsonSchema = {
823
1523
  additionalProperties?: boolean | JsonSchema;
824
1524
  };
825
1525
 
1526
+ export declare type ObservationScope = {
1527
+ documentScope: 'same_document';
1528
+ documentRef: string;
1529
+ } | {
1530
+ documentScope: 'current_top';
1531
+ };
1532
+
1533
+ export declare type ObservationTargetDescriptor = (ObservationScope & {
1534
+ kind: 'test_id';
1535
+ testId: string;
1536
+ }) | (ObservationScope & {
1537
+ kind: 'selector';
1538
+ selector: string;
1539
+ }) | (ObservationScope & {
1540
+ kind: 'semantic';
1541
+ match: 'exact';
1542
+ identity: SemanticIdentity;
1543
+ });
1544
+
1545
+ export declare type PageBoundTarget = {
1546
+ pageStateId: string;
1547
+ documentRef: string;
1548
+ };
1549
+
1550
+ export declare type SemanticIdentity = {
1551
+ role: string;
1552
+ name: string;
1553
+ } | {
1554
+ role: string;
1555
+ text: string;
1556
+ };
1557
+
1558
+ export declare type TargetDescriptor = (PageBoundTarget & {
1559
+ kind: 'ref';
1560
+ ref: string;
1561
+ }) | (PageBoundTarget & {
1562
+ kind: 'ax_ref';
1563
+ axRef: string;
1564
+ }) | (PageBoundTarget & {
1565
+ kind: 'test_id';
1566
+ testId: string;
1567
+ }) | (PageBoundTarget & {
1568
+ kind: 'selector';
1569
+ selector: string;
1570
+ }) | (PageBoundTarget & {
1571
+ kind: 'semantic';
1572
+ match: 'exact';
1573
+ identity: SemanticIdentity;
1574
+ });
1575
+
1576
+ export declare type TargetResolution = {
1577
+ requested: TargetDescriptor | CoordinateTargetDescriptor;
1578
+ strategy: 'ref' | 'ax_ref' | 'test_id' | 'unique_selector' | 'semantic_exact' | 'coordinate';
1579
+ resolved?: ElementDescriptor;
1580
+ candidates?: ElementDescriptor[];
1581
+ adjustment?: 'actionable_ancestor' | 'associated_label_control';
1582
+ point?: {
1583
+ x: number;
1584
+ y: number;
1585
+ };
1586
+ hitTarget?: ElementDescriptor;
1587
+ hitStack?: ElementDescriptor[];
1588
+ pageStateId: string;
1589
+ };
1590
+
1591
+ export declare type VerificationResult = {
1592
+ status: 'passed' | 'failed' | 'timed_out';
1593
+ expectation: ActionExpectation;
1594
+ elapsedMs: number;
1595
+ actual?: string | boolean | null;
1596
+ };
1597
+
826
1598
  export { }