@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 03:37 UTC

main
ts 1,045 lines 38.7 KB
Raw
1 import { Schema } from "effect";
2
3 import { EnvironmentId, ThreadId, TrimmedNonEmptyString } from "./baseSchemas.ts";
4 import {
5 PREVIEW_VIEWPORT_MAX_AREA,
6 PreviewRenderedViewportSize,
7 PreviewTabId,
8 PreviewViewportPresetId,
9 PreviewViewportSetting,
10 PreviewViewportSize,
11 } from "./preview.ts";
12 import { ProviderInstanceId } from "./providerInstance.ts";
13 import { BrowserProfileId } from "./browserProfile.ts";
14
15 const BoundedUrl = Schema.String.check(Schema.isTrimmed())
16 .check(Schema.isNonEmpty())
17 .check(Schema.isMaxLength(2048));
18 const URL_GUIDANCE = "Absolute http(s) URL, or a bare host (https; http for loopback).";
19 const PROFILE_GUIDANCE =
20 "Profile id or name from preview_status, for a new tab. Default: the user's. A tab keeps its profile.";
21 const OptionalTimeoutMs = Schema.optional(
22 Schema.Int.check(Schema.isGreaterThan(0)).check(Schema.isLessThanOrEqualTo(60_000)),
23 ).annotate({ description: "Default 15000." });
24
25 export const PREVIEW_AUTOMATION_V1_OPERATIONS = [
26 "status",
27 "open",
28 "navigate",
29 "snapshot",
30 "click",
31 "type",
32 "press",
33 "scroll",
34 "evaluate",
35 "waitFor",
36 "recordingStart",
37 "recordingStop",
38 ] as const;
39
40 const PREVIEW_AUTOMATION_OPERATIONS = [
41 ...PREVIEW_AUTOMATION_V1_OPERATIONS,
42 "resize",
43 "setColorScheme",
44 ] as const;
45
46 export const PREVIEW_AUTOMATION_SERVER_OPERATIONS = [
47 ...PREVIEW_AUTOMATION_OPERATIONS,
48 "dialog",
49 "close",
50 "upload",
51 "hover",
52 "select",
53 "drag",
54 ] as const;
55 export const PreviewAutomationOperation = Schema.Literals(PREVIEW_AUTOMATION_SERVER_OPERATIONS);
56 export type PreviewAutomationOperation = typeof PreviewAutomationOperation.Type;
57
58 const PreviewAutomationTabTargetFields = {
59 tabId: Schema.optional(PreviewTabId),
60 };
61
62 export const PreviewAutomationTabTargetInput = Schema.Struct(PreviewAutomationTabTargetFields);
63 export type PreviewAutomationTabTargetInput = typeof PreviewAutomationTabTargetInput.Type;
64
65 export const PreviewAutomationTabOwner = Schema.Literals(["agent", "human", "unclaimed"]);
66
67 export const PreviewAutomationProfile = Schema.Struct({
68 id: BrowserProfileId,
69 name: Schema.String,
70 incognito: Schema.optional(Schema.Boolean),
71 });
72 export type PreviewAutomationProfile = typeof PreviewAutomationProfile.Type;
73
74 const VISIBLE_DESCRIPTION =
75 "True while a client shows this tab: a streamed live view, or the desktop app's own browser panel.";
76
77 /** Why the tab shows the browser's error page instead of the page it tried to load. */
78 export const PreviewAutomationLoadError = Schema.Struct({
79 url: Schema.String,
80 code: Schema.Int,
81 description: Schema.String,
82 });
83 export type PreviewAutomationLoadError = typeof PreviewAutomationLoadError.Type;
84
85 export const PreviewAutomationStatus = Schema.Struct({
86 available: Schema.Boolean,
87 visible: Schema.Boolean.annotate({ description: VISIBLE_DESCRIPTION }),
88 tabId: Schema.NullOr(PreviewTabId),
89 url: Schema.NullOr(Schema.String),
90 title: Schema.NullOr(Schema.String),
91 loading: Schema.Boolean,
92 loadError: Schema.optional(PreviewAutomationLoadError),
93 control: Schema.optional(
94 Schema.Struct({
95 owner: PreviewAutomationTabOwner,
96 ownedByCaller: Schema.Boolean,
97 generation: Schema.Number,
98 }),
99 ),
100 dialog: Schema.optional(
101 Schema.NullOr(
102 Schema.Struct({
103 type: Schema.String,
104 message: Schema.String,
105 defaultValue: Schema.String,
106 }),
107 ),
108 ),
109 viewportSetting: Schema.optional(PreviewViewportSetting),
110 viewport: Schema.optional(PreviewRenderedViewportSize),
111 fileChooser: Schema.optional(
112 Schema.NullOr(Schema.Struct({ multiple: Schema.Boolean, accept: Schema.String })),
113 ),
114 downloads: Schema.optional(
115 Schema.Array(
116 Schema.Struct({
117 fileName: Schema.String,
118 path: Schema.String,
119 sizeBytes: Schema.Number,
120 url: Schema.String,
121 completedAt: Schema.String,
122 }),
123 ),
124 ),
125 /** Server hosts: all thread tabs are readable; actions require ownedByCaller or an unclaimed tab without human control. */
126 tabs: Schema.optional(
127 Schema.Array(
128 Schema.Struct({
129 tabId: PreviewTabId,
130 url: Schema.NullOr(Schema.String),
131 openerTabId: Schema.optional(PreviewTabId),
132 owner: Schema.optional(PreviewAutomationTabOwner),
133 ownedByCaller: Schema.optional(Schema.Boolean),
134 visible: Schema.optional(Schema.Boolean.annotate({ description: VISIBLE_DESCRIPTION })),
135 profileId: Schema.optional(BrowserProfileId),
136 }),
137 ),
138 ),
139 profiles: Schema.optional(Schema.Array(PreviewAutomationProfile)),
140 defaultProfileId: Schema.optional(BrowserProfileId),
141 });
142 export type PreviewAutomationStatus = typeof PreviewAutomationStatus.Type;
143
144 export const PreviewAutomationDialogInput = Schema.Struct({
145 ...PreviewAutomationTabTargetFields,
146 accept: Schema.Boolean,
147 promptText: Schema.optional(Schema.String),
148 });
149 export type PreviewAutomationDialogInput = typeof PreviewAutomationDialogInput.Type;
150
151 export const PreviewAutomationOpenInput = Schema.Struct({
152 ...PreviewAutomationTabTargetFields,
153 url: Schema.optional(BoundedUrl).annotate({
154 description: `First page URL. ${URL_GUIDANCE} Omit to open a blank tab.`,
155 }),
156 open: Schema.optional(
157 Schema.Boolean.annotate({
158 description: "Show the preview to the user. Default true. False for background only.",
159 }),
160 ),
161 show: Schema.optional(
162 Schema.Boolean.annotate({
163 description: "Old alias for `open`.",
164 }),
165 ),
166 reuseExistingTab: Schema.optional(
167 Schema.Boolean.annotate({
168 description: "Reuse `tabId`, or your current tab. Default true. False makes a new tab.",
169 }),
170 ),
171 profileId: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(64))).annotate({
172 description: PROFILE_GUIDANCE,
173 }),
174 }).check(
175 Schema.makeFilter(
176 (input) =>
177 !(input.tabId !== undefined && input.reuseExistingTab === false) ||
178 "tabId cannot be combined with reuseExistingTab=false.",
179 ),
180 );
181 export type PreviewAutomationOpenInput = typeof PreviewAutomationOpenInput.Type;
182
183 export const BrowserNavigationTarget = Schema.Union([
184 Schema.Struct({
185 kind: Schema.Literal("url"),
186 url: BoundedUrl.annotate({
187 description: `Website URL. ${URL_GUIDANCE}`,
188 }),
189 }),
190 Schema.Struct({
191 kind: Schema.Literal("environment-port"),
192 port: Schema.Int.check(Schema.isGreaterThan(0))
193 .check(Schema.isLessThan(65_536))
194 .annotate({ description: "Dev-server port here." }),
195 protocol: Schema.optional(
196 Schema.Literals(["http", "https"]).annotate({
197 description: "Default http.",
198 }),
199 ),
200 path: Schema.optional(
201 Schema.String.annotate({
202 description: "Path, query, and fragment, such as /settings?tab=account.",
203 }),
204 ),
205 }),
206 ]);
207 export type BrowserNavigationTarget = typeof BrowserNavigationTarget.Type;
208
209 export const PreviewAutomationNavigateInput = Schema.Struct({
210 ...PreviewAutomationTabTargetFields,
211 url: Schema.optional(BoundedUrl).annotate({
212 description: `Website URL. ${URL_GUIDANCE} For public pages.`,
213 }),
214 target: Schema.optional(BrowserNavigationTarget),
215 readiness: Schema.optional(Schema.Literals(["load", "domContentLoaded", "none"])).annotate({
216 description: "Default 'load'. 'none': return at once.",
217 }),
218 timeoutMs: OptionalTimeoutMs,
219 }).check(
220 Schema.makeFilter(
221 (input) =>
222 Number(input.url !== undefined) + Number(input.target !== undefined) === 1 ||
223 "Provide exactly one of url or target.",
224 ),
225 );
226 export type PreviewAutomationNavigateInput = typeof PreviewAutomationNavigateInput.Type;
227
228 export const PreviewAutomationResizeInput = Schema.Struct({
229 ...PreviewAutomationTabTargetFields,
230 mode: Schema.Literals(["fill", "freeform", "preset"]),
231 preset: Schema.optional(PreviewViewportPresetId),
232 width: Schema.optional(PreviewViewportSize.fields.width),
233 height: Schema.optional(PreviewViewportSize.fields.height),
234 orientation: Schema.optional(Schema.Literals(["portrait", "landscape"])),
235 timeoutMs: OptionalTimeoutMs,
236 }).check(
237 Schema.makeFilter((input) => {
238 const hasPreset = input.preset !== undefined;
239 const hasWidth = input.width !== undefined;
240 const hasHeight = input.height !== undefined;
241 if (hasWidth !== hasHeight) return "Custom dimensions require both width and height.";
242 if (input.mode === "fill") {
243 return !hasPreset && !hasWidth && input.orientation === undefined
244 ? true
245 : "Fill mode does not accept a preset, dimensions, or orientation.";
246 }
247 if (input.mode === "freeform") {
248 if (!hasWidth || !hasHeight || hasPreset || input.orientation !== undefined) {
249 return "Freeform mode requires width and height and does not accept a preset or orientation.";
250 }
251 } else if (!hasPreset || hasWidth || hasHeight) {
252 return "Preset mode requires a preset and does not accept custom dimensions.";
253 }
254 if (hasWidth && hasHeight && input.width! * input.height! > PREVIEW_VIEWPORT_MAX_AREA) {
255 return `Custom viewport area must not exceed ${PREVIEW_VIEWPORT_MAX_AREA} pixels.`;
256 }
257 return true;
258 }),
259 );
260 export type PreviewAutomationResizeInput = typeof PreviewAutomationResizeInput.Type;
261
262 export const PreviewAutomationResizeResult = Schema.Struct({
263 tabId: PreviewTabId,
264 setting: PreviewViewportSetting,
265 viewport: Schema.optional(PreviewRenderedViewportSize).annotate({
266 description: "Viewport size after the resize. Omitted when it could not be measured.",
267 }),
268 });
269 export type PreviewAutomationResizeResult = typeof PreviewAutomationResizeResult.Type;
270
271 // Mirrors DesktopPreviewColorScheme without importing ipc.ts.
272 export const PreviewAutomationColorScheme = Schema.Literals(["system", "light", "dark"]);
273 export type PreviewAutomationColorScheme = typeof PreviewAutomationColorScheme.Type;
274
275 export const PreviewAutomationSetColorSchemeInput = Schema.Struct({
276 ...PreviewAutomationTabTargetFields,
277 colorScheme: PreviewAutomationColorScheme,
278 });
279 export type PreviewAutomationSetColorSchemeInput = typeof PreviewAutomationSetColorSchemeInput.Type;
280
281 export const PreviewAutomationSetColorSchemeResult = Schema.Struct({
282 tabId: PreviewTabId,
283 colorScheme: PreviewAutomationColorScheme,
284 });
285 export type PreviewAutomationSetColorSchemeResult =
286 typeof PreviewAutomationSetColorSchemeResult.Type;
287
288 const Locator = TrimmedNonEmptyString;
289 const LegacySelector = TrimmedNonEmptyString;
290
291 const PointerTargetFields = {
292 ...PreviewAutomationTabTargetFields,
293 selector: Schema.optional(LegacySelector),
294 locator: Schema.optional(Locator),
295 x: Schema.optional(Schema.Finite),
296 y: Schema.optional(Schema.Finite),
297 timeoutMs: OptionalTimeoutMs,
298 };
299
300 const singlePointerTarget = Schema.makeFilter(
301 (input: {
302 readonly selector?: string | undefined;
303 readonly locator?: string | undefined;
304 readonly x?: number | undefined;
305 readonly y?: number | undefined;
306 }) => {
307 const selectorModes =
308 Number(input.selector !== undefined) + Number(input.locator !== undefined);
309 const hasX = input.x !== undefined;
310 const hasY = input.y !== undefined;
311 if (hasX !== hasY) return "Coordinates require both x and y.";
312 const coordinateModes = hasX && hasY ? 1 : 0;
313 return selectorModes + coordinateModes === 1 || "Provide exactly one target.";
314 },
315 );
316
317 export const PreviewAutomationClickInput = Schema.Struct({
318 ...PointerTargetFields,
319 button: Schema.optional(
320 Schema.Literals(["left", "right", "middle"]).annotate({
321 description: "Button. Default left. Right opens the menu.",
322 }),
323 ),
324 clickCount: Schema.optional(
325 Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 3 })).annotate({
326 description: "1 click, 2 double, 3 triple. Default 1.",
327 }),
328 ),
329 }).check(singlePointerTarget);
330 export type PreviewAutomationClickInput = typeof PreviewAutomationClickInput.Type;
331
332 export const PreviewAutomationHoverInput =
333 Schema.Struct(PointerTargetFields).check(singlePointerTarget);
334 export type PreviewAutomationHoverInput = typeof PreviewAutomationHoverInput.Type;
335
336 export const PreviewAutomationSelectInput = Schema.Struct({
337 ...PreviewAutomationTabTargetFields,
338 selector: Schema.optional(LegacySelector),
339 locator: Schema.optional(Locator),
340 values: Schema.Array(Schema.String).check(Schema.isMaxLength(100)).annotate({
341 description: "Empty clears it.",
342 }),
343 timeoutMs: OptionalTimeoutMs,
344 }).check(
345 Schema.makeFilter(
346 (input) =>
347 Number(input.selector !== undefined) + Number(input.locator !== undefined) === 1 ||
348 "Provide exactly one of selector or locator.",
349 ),
350 );
351 export type PreviewAutomationSelectInput = typeof PreviewAutomationSelectInput.Type;
352
353 export const PreviewAutomationSelectResult = Schema.Struct({
354 selected: Schema.Array(Schema.String).annotate({
355 description: "The values of the options now selected.",
356 }),
357 });
358 export type PreviewAutomationSelectResult = typeof PreviewAutomationSelectResult.Type;
359
360 export const PreviewAutomationDragInput = Schema.Struct({
361 ...PreviewAutomationTabTargetFields,
362 source: Locator,
363 target: Locator,
364 timeoutMs: OptionalTimeoutMs,
365 });
366 export type PreviewAutomationDragInput = typeof PreviewAutomationDragInput.Type;
367
368 export const PreviewAutomationUploadInput = Schema.Struct({
369 ...PreviewAutomationTabTargetFields,
370 paths: Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(20)),
371 selector: Schema.optional(LegacySelector),
372 locator: Schema.optional(Locator).annotate({
373 description: "Set files on this <input type=file> instead of the open picker.",
374 }),
375 timeoutMs: OptionalTimeoutMs,
376 }).check(
377 Schema.makeFilter(
378 (input) =>
379 !(input.selector !== undefined && input.locator !== undefined) ||
380 "Provide at most one of selector or locator.",
381 ),
382 );
383 export type PreviewAutomationUploadInput = typeof PreviewAutomationUploadInput.Type;
384
385 export const PreviewAutomationTypeInput = Schema.Struct({
386 ...PreviewAutomationTabTargetFields,
387 text: Schema.String,
388 selector: Schema.optional(LegacySelector),
389 locator: Schema.optional(Locator),
390 clear: Schema.optional(
391 Schema.Boolean.annotate({
392 description: "Clear the input first. Default false.",
393 }),
394 ),
395 timeoutMs: OptionalTimeoutMs,
396 }).check(
397 Schema.makeFilter(
398 (input) =>
399 !(input.selector !== undefined && input.locator !== undefined) ||
400 "Provide at most one of selector or locator.",
401 ),
402 );
403 export type PreviewAutomationTypeInput = typeof PreviewAutomationTypeInput.Type;
404
405 export const PreviewAutomationPressInput = Schema.Struct({
406 ...PreviewAutomationTabTargetFields,
407 key: Schema.String.check(Schema.isTrimmed()).check(Schema.isNonEmpty()),
408 modifiers: Schema.optional(Schema.Array(Schema.Literals(["Alt", "Control", "Meta", "Shift"]))),
409 });
410 export type PreviewAutomationPressInput = typeof PreviewAutomationPressInput.Type;
411
412 export const PreviewAutomationScrollInput = Schema.Struct({
413 ...PreviewAutomationTabTargetFields,
414 deltaX: Schema.optional(Schema.Finite),
415 deltaY: Schema.optional(Schema.Finite),
416 selector: Schema.optional(LegacySelector),
417 locator: Schema.optional(Locator),
418 }).check(
419 Schema.makeFilter((input) => {
420 if (input.selector !== undefined && input.locator !== undefined) {
421 return "Provide at most one of selector or locator.";
422 }
423 return input.deltaX !== undefined || input.deltaY !== undefined || "Provide deltaX or deltaY.";
424 }),
425 );
426 export type PreviewAutomationScrollInput = typeof PreviewAutomationScrollInput.Type;
427
428 /** Strict input for each `preview_act` action. */
429 export const PreviewAutomationActInputs = {
430 click: PreviewAutomationClickInput,
431 type: PreviewAutomationTypeInput,
432 hover: PreviewAutomationHoverInput,
433 select: PreviewAutomationSelectInput,
434 drag: PreviewAutomationDragInput,
435 upload: PreviewAutomationUploadInput,
436 press: PreviewAutomationPressInput,
437 scroll: PreviewAutomationScrollInput,
438 } as const;
439 export type PreviewAutomationAction = keyof typeof PreviewAutomationActInputs;
440
441 /** One flat shape for every page action. The server decodes it with the action's strict input. */
442 export const PreviewAutomationActInput = Schema.Struct({
443 action: Schema.Literals([
444 "click",
445 "type",
446 "hover",
447 "select",
448 "drag",
449 "upload",
450 "press",
451 "scroll",
452 ]),
453 ...PreviewAutomationTabTargetFields,
454 locator: Schema.optional(Locator),
455 selector: Schema.optional(LegacySelector),
456 x: Schema.optional(Schema.Finite),
457 y: Schema.optional(Schema.Finite),
458 button: Schema.optional(Schema.Literals(["left", "right", "middle"])),
459 clickCount: Schema.optional(Schema.Int),
460 text: Schema.optional(Schema.String),
461 clear: Schema.optional(Schema.Boolean),
462 values: Schema.optional(Schema.Array(Schema.String)),
463 source: Schema.optional(Locator),
464 target: Schema.optional(Locator),
465 paths: Schema.optional(Schema.Array(Schema.String)),
466 key: Schema.optional(Schema.String),
467 modifiers: PreviewAutomationPressInput.fields.modifiers,
468 deltaX: Schema.optional(Schema.Finite),
469 deltaY: Schema.optional(Schema.Finite),
470 timeoutMs: Schema.optional(Schema.Int),
471 });
472 export type PreviewAutomationActInput = typeof PreviewAutomationActInput.Type;
473
474 export const PreviewAutomationEvaluateInput = Schema.Struct({
475 ...PreviewAutomationTabTargetFields,
476 expression: Schema.String.check(Schema.isTrimmed())
477 .check(Schema.isNonEmpty())
478 .check(Schema.isMaxLength(64_000)),
479 awaitPromise: Schema.optional(Schema.Boolean.annotate({ description: "Default true." })),
480 });
481 export type PreviewAutomationEvaluateInput = typeof PreviewAutomationEvaluateInput.Type;
482
483 export const PreviewAutomationWaitForInput = Schema.Struct({
484 ...PreviewAutomationTabTargetFields,
485 selector: Schema.optional(LegacySelector),
486 locator: Schema.optional(Locator),
487 text: Schema.optional(TrimmedNonEmptyString).annotate({
488 description: "Case counts.",
489 }),
490 urlIncludes: Schema.optional(TrimmedNonEmptyString),
491 timeoutMs: OptionalTimeoutMs,
492 }).check(
493 Schema.makeFilter((input) => {
494 if (input.selector !== undefined && input.locator !== undefined) {
495 return "Provide at most one of selector or locator.";
496 }
497 return (
498 input.selector !== undefined ||
499 input.locator !== undefined ||
500 input.text !== undefined ||
501 input.urlIncludes !== undefined ||
502 "Provide at least one wait condition."
503 );
504 }),
505 );
506 export type PreviewAutomationWaitForInput = typeof PreviewAutomationWaitForInput.Type;
507
508 export const PreviewAutomationElement = Schema.Struct({
509 tag: Schema.String,
510 role: Schema.NullOr(Schema.String),
511 name: Schema.String,
512 selector: Schema.String,
513 x: Schema.Number,
514 y: Schema.Number,
515 width: Schema.Number,
516 height: Schema.Number,
517 });
518 export type PreviewAutomationElement = typeof PreviewAutomationElement.Type;
519
520 export const PreviewAutomationConsoleEntry = Schema.Struct({
521 level: Schema.String,
522 text: Schema.String,
523 timestamp: Schema.String,
524 source: Schema.optional(Schema.String),
525 });
526 export type PreviewAutomationConsoleEntry = typeof PreviewAutomationConsoleEntry.Type;
527
528 export const PreviewAutomationNetworkEntry = Schema.Struct({
529 url: Schema.String,
530 method: Schema.String,
531 status: Schema.NullOr(Schema.Number),
532 failed: Schema.Boolean,
533 errorText: Schema.optional(Schema.String),
534 timestamp: Schema.String,
535 });
536 export type PreviewAutomationNetworkEntry = typeof PreviewAutomationNetworkEntry.Type;
537
538 export const PreviewAutomationActionEvent = Schema.Struct({
539 id: Schema.String,
540 action: Schema.String,
541 status: Schema.Literals(["running", "succeeded", "failed", "interrupted"]),
542 startedAt: Schema.String,
543 completedAt: Schema.optional(Schema.String),
544 error: Schema.optional(Schema.String),
545 });
546 export type PreviewAutomationActionEvent = typeof PreviewAutomationActionEvent.Type;
547
548 export const PreviewAutomationSnapshot = Schema.Struct({
549 url: Schema.String,
550 title: Schema.String,
551 loading: Schema.Boolean,
552 loadError: Schema.optional(PreviewAutomationLoadError),
553 visibleText: Schema.String,
554 interactiveElements: Schema.Array(PreviewAutomationElement),
555 accessibilityTree: Schema.Unknown,
556 consoleEntries: Schema.Array(PreviewAutomationConsoleEntry),
557 networkEntries: Schema.Array(PreviewAutomationNetworkEntry),
558 actionTimeline: Schema.Array(PreviewAutomationActionEvent),
559 screenshot: Schema.Struct({
560 mimeType: Schema.Literal("image/png"),
561 data: Schema.String,
562 width: Schema.Int,
563 height: Schema.Int,
564 }),
565 /** The capture before `screenshot` was capped for the agent, when requested and larger. */
566 fullScreenshot: Schema.optional(
567 Schema.Struct({ data: Schema.String, width: Schema.Int, height: Schema.Int }),
568 ),
569 });
570 export type PreviewAutomationSnapshot = typeof PreviewAutomationSnapshot.Type;
571
572 // pixelsRequired is false when the caller discards the screenshot; hosts that ignore it still return a PNG.
573 export const PreviewAutomationSnapshotInput = Schema.Struct({
574 fullScreenshot: Schema.optional(Schema.Boolean),
575 pixelsRequired: Schema.optional(Schema.Boolean),
576 });
577 export type PreviewAutomationSnapshotInput = typeof PreviewAutomationSnapshotInput.Type;
578
579 export const PreviewAutomationSnapshotMetadata = Schema.Struct({
580 ...PreviewAutomationSnapshot.fields,
581 screenshot: Schema.Struct({ width: Schema.Int, height: Schema.Int }),
582 });
583 export type PreviewAutomationSnapshotMetadata = typeof PreviewAutomationSnapshotMetadata.Type;
584
585 export const PreviewAutomationRecordingStatus = Schema.Struct({
586 tabId: PreviewTabId,
587 recording: Schema.Boolean,
588 startedAt: Schema.NullOr(Schema.String),
589 });
590 export type PreviewAutomationRecordingStatus = typeof PreviewAutomationRecordingStatus.Type;
591
592 export const PREVIEW_RECORDING_STOP_TIMEOUT_MS = 120_000;
593
594 export const PreviewAutomationRecordingArtifact = Schema.Struct({
595 id: Schema.String,
596 tabId: PreviewTabId,
597 path: Schema.String,
598 mimeType: Schema.String,
599 sizeBytes: Schema.Int,
600 createdAt: Schema.String,
601 });
602 export type PreviewAutomationRecordingArtifact = typeof PreviewAutomationRecordingArtifact.Type;
603
604 export const PreviewAutomationClientId = TrimmedNonEmptyString.check(Schema.isMaxLength(128));
605 export type PreviewAutomationClientId = typeof PreviewAutomationClientId.Type;
606 export const PreviewAutomationConnectionId = TrimmedNonEmptyString.check(Schema.isMaxLength(64));
607 export type PreviewAutomationConnectionId = typeof PreviewAutomationConnectionId.Type;
608
609 export const PreviewAutomationHostIdentity = Schema.Struct({
610 clientId: PreviewAutomationClientId,
611 environmentId: EnvironmentId,
612 });
613 export type PreviewAutomationHostIdentity = typeof PreviewAutomationHostIdentity.Type;
614
615 export const PreviewAutomationHost = Schema.Struct({
616 ...PreviewAutomationHostIdentity.fields,
617 /** Missing means the V1 operation set from before capability negotiation. */
618 supportedOperations: Schema.optional(Schema.Array(PreviewAutomationOperation)),
619 });
620 export type PreviewAutomationHost = typeof PreviewAutomationHost.Type;
621
622 export const PreviewAutomationHostFocus = Schema.Struct({
623 ...PreviewAutomationHostIdentity.fields,
624 connectionId: PreviewAutomationConnectionId,
625 focused: Schema.Boolean,
626 liveTabs: Schema.optional(
627 Schema.Array(
628 Schema.Struct({
629 threadId: ThreadId,
630 tabId: PreviewTabId,
631 visible: Schema.optional(Schema.Boolean),
632 }),
633 ),
634 ),
635 });
636 export type PreviewAutomationHostFocus = typeof PreviewAutomationHostFocus.Type;
637
638 export const PreviewAutomationRequest = Schema.Struct({
639 requestId: TrimmedNonEmptyString,
640 threadId: ThreadId,
641 tabId: Schema.optional(PreviewTabId),
642 tabIdExplicit: Schema.optional(Schema.Boolean),
643 /** Supplied by the broker from authenticated scope, never from tool input. */
644 agentSessionId: Schema.optional(Schema.String),
645 operation: PreviewAutomationOperation,
646 input: Schema.Unknown,
647 timeoutMs: Schema.Int.check(Schema.isGreaterThan(0)),
648 });
649 export type PreviewAutomationRequest = typeof PreviewAutomationRequest.Type;
650
651 export const PreviewAutomationStreamEvent = Schema.Union([
652 Schema.Struct({
653 type: Schema.Literal("connected"),
654 connectionId: PreviewAutomationConnectionId,
655 }),
656 Schema.Struct({
657 type: Schema.Literal("request"),
658 connectionId: PreviewAutomationConnectionId,
659 request: PreviewAutomationRequest,
660 }),
661 ]);
662 export type PreviewAutomationStreamEvent = typeof PreviewAutomationStreamEvent.Type;
663
664 export const PreviewAutomationResponse = Schema.Struct({
665 clientId: PreviewAutomationClientId,
666 connectionId: PreviewAutomationConnectionId,
667 requestId: TrimmedNonEmptyString,
668 ok: Schema.Boolean,
669 result: Schema.optional(Schema.Unknown),
670 error: Schema.optional(
671 Schema.Struct({
672 _tag: TrimmedNonEmptyString,
673 message: Schema.String,
674 detail: Schema.optional(Schema.Unknown),
675 }),
676 ),
677 });
678 export type PreviewAutomationResponse = typeof PreviewAutomationResponse.Type;
679
680 const McpCapabilityErrorFields = {
681 environmentId: EnvironmentId,
682 threadId: Schema.optional(ThreadId),
683 providerSessionId: Schema.optional(TrimmedNonEmptyString),
684 providerInstanceId: Schema.optional(ProviderInstanceId),
685 };
686
687 export class PreviewAutomationUnavailableError extends Schema.TaggedError<PreviewAutomationUnavailableError>()(
688 "PreviewAutomationUnavailableError",
689 {
690 capability: Schema.Literal("preview"),
691 ...McpCapabilityErrorFields,
692 },
693 ) {
694 override get message(): string {
695 return `MCP credential does not grant the ${this.capability} capability: browser preview tools are off for this thread. Do not retry them. To check a page, use a headless browser from the shell, such as Playwright, or curl. The user can turn on "Agent browser access" in Settings; it applies when the agent session next starts.`;
696 }
697 }
698
699 export class McpCapabilityUnavailableError extends Schema.TaggedError<McpCapabilityUnavailableError>()(
700 "McpCapabilityUnavailableError",
701 {
702 capability: TrimmedNonEmptyString,
703 ...McpCapabilityErrorFields,
704 },
705 ) {
706 override get message(): string {
707 return `MCP credential does not grant the ${this.capability} capability.`;
708 }
709 }
710
711 const PreviewAutomationScopeErrorFields = {
712 operation: PreviewAutomationOperation,
713 environmentId: EnvironmentId,
714 threadId: ThreadId,
715 providerSessionId: TrimmedNonEmptyString,
716 providerInstanceId: ProviderInstanceId,
717 };
718
719 export const SERVER_BROWSER_AUTOMATION_CLIENT_ID = "server-browser";
720
721 const PreviewAutomationRequestErrorFields = {
722 ...PreviewAutomationScopeErrorFields,
723 clientId: TrimmedNonEmptyString,
724 connectionId: PreviewAutomationConnectionId,
725 requestId: TrimmedNonEmptyString,
726 tabId: Schema.optional(PreviewTabId),
727 timeoutMs: Schema.Int.check(Schema.isGreaterThan(0)),
728 };
729
730 const PreviewAutomationRemoteDiagnosticFields = {
731 remoteTag: TrimmedNonEmptyString,
732 remoteMessageLength: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
733 remoteDetailKind: Schema.optional(
734 Schema.Literals(["null", "array", "object", "string", "number", "boolean"]),
735 ),
736 cause: Schema.Defect(),
737 };
738
739 const PreviewAutomationOptionalRemoteDiagnosticFields = {
740 remoteTag: Schema.optional(TrimmedNonEmptyString),
741 remoteMessageLength: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
742 remoteDetailKind: Schema.optional(
743 Schema.Literals(["null", "array", "object", "string", "number", "boolean"]),
744 ),
745 cause: Schema.optional(Schema.Defect()),
746 };
747
748 export class PreviewAutomationNoAvailableHostError extends Schema.TaggedError<PreviewAutomationNoAvailableHostError>()(
749 "PreviewAutomationNoAvailableHostError",
750 {
751 ...PreviewAutomationScopeErrorFields,
752 clientId: Schema.optional(TrimmedNonEmptyString),
753 connectionId: Schema.optional(PreviewAutomationConnectionId),
754 requestId: Schema.optional(TrimmedNonEmptyString),
755 tabId: Schema.optional(PreviewTabId),
756 timeoutMs: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
757 ...PreviewAutomationOptionalRemoteDiagnosticFields,
758 },
759 ) {
760 override get message(): string {
761 return `No preview automation host is available for ${this.operation} in environment ${this.environmentId}. The server-owned browser may be starting or reconnecting. Retry preview_status, then call preview_open if no tab is available. If it remains unavailable, report the browser connection failure.`;
762 }
763 }
764
765 export class PreviewAutomationUnsupportedClientError extends Schema.TaggedError<PreviewAutomationUnsupportedClientError>()(
766 "PreviewAutomationUnsupportedClientError",
767 {
768 ...PreviewAutomationRequestErrorFields,
769 ...PreviewAutomationRemoteDiagnosticFields,
770 },
771 ) {
772 override get message(): string {
773 return `Preview automation client ${this.clientId} does not support ${this.operation}.`;
774 }
775 }
776
777 export class PreviewAutomationTabNotFoundError extends Schema.TaggedError<PreviewAutomationTabNotFoundError>()(
778 "PreviewAutomationTabNotFoundError",
779 {
780 ...PreviewAutomationRequestErrorFields,
781 ...PreviewAutomationRemoteDiagnosticFields,
782 },
783 ) {
784 override get message(): string {
785 return this.tabId
786 ? `Preview tab ${this.tabId} was not found for ${this.operation}. Omit tabId to use the current tab, or call preview_open.`
787 : `No active preview tab was found for ${this.operation}. Call preview_open first.`;
788 }
789 }
790
791 export const PreviewAutomationSnapshotStage = Schema.Literals([
792 "metrics",
793 "frames",
794 "page state",
795 "screenshot",
796 "accessibility tree",
797 ]);
798
799 export const PreviewAutomationTimeoutDetail = Schema.Struct({
800 timeoutMs: Schema.Int.check(Schema.isGreaterThan(0)),
801 pendingStages: Schema.Array(PreviewAutomationSnapshotStage).check(Schema.isMaxLength(5)),
802 });
803
804 export class PreviewAutomationTimeoutError extends Schema.TaggedError<PreviewAutomationTimeoutError>()(
805 "PreviewAutomationTimeoutError",
806 {
807 ...PreviewAutomationRequestErrorFields,
808 ...PreviewAutomationOptionalRemoteDiagnosticFields,
809 pendingStages: Schema.optional(PreviewAutomationTimeoutDetail.fields.pendingStages),
810 reason: Schema.optional(Schema.String),
811 },
812 ) {
813 override get message(): string {
814 const summary = `Preview automation ${this.operation} timed out after ${this.timeoutMs}ms.`;
815 const stages = this.pendingStages?.length
816 ? ` Waiting for: ${this.pendingStages.join(", ")}.`
817 : "";
818 const reason = this.reason === undefined ? "" : ` ${this.reason}`;
819 return `${summary}${stages}${reason}`;
820 }
821 }
822
823 export const PreviewAutomationControlReason = Schema.Literals([
824 "agentMismatch",
825 "unclaimedTab",
826 "humanControl",
827 "tabRequired",
828 "closed",
829 "interrupted",
830 "dialogPending",
831 "tabLimit",
832 ]);
833 export type PreviewAutomationControlReason = typeof PreviewAutomationControlReason.Type;
834
835 export class PreviewAutomationControlInterruptedError extends Schema.TaggedError<PreviewAutomationControlInterruptedError>()(
836 "PreviewAutomationControlInterruptedError",
837 {
838 ...PreviewAutomationRequestErrorFields,
839 ...PreviewAutomationRemoteDiagnosticFields,
840 reason: Schema.optional(PreviewAutomationControlReason),
841 },
842 ) {
843 override get message(): string {
844 if (this.reason === "agentMismatch")
845 return "This browser tab belongs to another agent session or a human. Open your own tab.";
846 if (this.reason === "unclaimedTab")
847 return "This tab has no agent owner. Ask the user to close it in the browser panel.";
848 if (this.reason === "humanControl")
849 return "A human controls this browser tab. Wait until they release control.";
850 if (this.reason === "tabRequired")
851 return "Multiple browser tabs belong to this session. Pass a tabId from preview_open or from the tabs listed by preview_status.";
852 if (this.reason === "dialogPending")
853 return "A browser dialog is pending. Read preview_status and resolve it with preview_dialog.";
854 if (this.reason === "tabLimit")
855 return "Too many server browser tabs are open. Close one with t3_preview_close, or reuse a tabId from preview_status tabs.";
856 if (this.reason === "closed") return "This browser tab is closed. Call preview_open.";
857 if (this.reason === "interrupted")
858 return "Browser control changed. Take a fresh snapshot before trying again.";
859 return `Preview automation ${this.operation} was interrupted on client ${this.clientId}.`;
860 }
861 }
862
863 export class PreviewAutomationExecutionError extends Schema.TaggedError<PreviewAutomationExecutionError>()(
864 "PreviewAutomationExecutionError",
865 {
866 ...PreviewAutomationRequestErrorFields,
867 ...PreviewAutomationRemoteDiagnosticFields,
868 reason: Schema.optional(Schema.String),
869 },
870 ) {
871 override get message(): string {
872 return this.reason === undefined
873 ? `Preview automation ${this.operation} failed on client ${this.clientId}.`
874 : `Preview automation ${this.operation} failed: ${this.reason}`;
875 }
876 }
877
878 export class PreviewAutomationInvalidSelectorError extends Schema.TaggedError<PreviewAutomationInvalidSelectorError>()(
879 "PreviewAutomationInvalidSelectorError",
880 {
881 ...PreviewAutomationRequestErrorFields,
882 ...PreviewAutomationRemoteDiagnosticFields,
883 selectorKind: Schema.optional(Schema.Literals(["locator", "selector"])),
884 selectorLength: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
885 staleRef: Schema.optional(Schema.Boolean),
886 },
887 ) {
888 override get message(): string {
889 if (this.staleRef)
890 return "This element ref is stale. Navigation, dialogs, and new snapshots replace refs; take a fresh snapshot and use its refs.";
891 if (this.selectorKind !== undefined && this.selectorLength !== undefined) {
892 const guidance =
893 this.selectorKind === "locator"
894 ? "Use aria-ref=<ref> from the latest snapshot or a Playwright role/text selector; put CSS in selector."
895 : "selector takes CSS; use locator for aria-ref=<ref>, role, or text targets.";
896 return `Preview automation ${this.operation} received an invalid ${this.selectorKind} (${this.selectorLength} characters). ${guidance}`;
897 }
898 return `Preview automation ${this.operation} received an invalid selector.`;
899 }
900 }
901
902 export class PreviewAutomationTargetNotEditableError extends Schema.TaggedError<PreviewAutomationTargetNotEditableError>()(
903 "PreviewAutomationTargetNotEditableError",
904 {
905 ...PreviewAutomationRequestErrorFields,
906 ...PreviewAutomationRemoteDiagnosticFields,
907 selectorKind: Schema.optional(Schema.Literals(["focused-element", "locator", "selector"])),
908 selectorLength: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
909 },
910 ) {
911 override get message(): string {
912 if (this.selectorKind === "focused-element") {
913 return `Preview automation ${this.operation} requires an editable focused element.`;
914 }
915 if (this.selectorKind !== undefined && this.selectorLength !== undefined) {
916 return `Preview automation ${this.operation} requires an editable ${this.selectorKind} (${this.selectorLength} characters).`;
917 }
918 return `Preview automation ${this.operation} requires an editable target.`;
919 }
920 }
921
922 export class PreviewAutomationResultTooLargeError extends Schema.TaggedError<PreviewAutomationResultTooLargeError>()(
923 "PreviewAutomationResultTooLargeError",
924 {
925 ...PreviewAutomationRequestErrorFields,
926 ...PreviewAutomationRemoteDiagnosticFields,
927 maximumBytes: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
928 },
929 ) {
930 override get message(): string {
931 const summary =
932 this.maximumBytes === undefined
933 ? `Preview automation ${this.operation} produced a result that is too large.`
934 : `Preview automation ${this.operation} produced a result larger than ${this.maximumBytes} bytes.`;
935 return summary;
936 }
937 }
938
939 export class PreviewAutomationClientDisconnectedError extends Schema.TaggedError<PreviewAutomationClientDisconnectedError>()(
940 "PreviewAutomationClientDisconnectedError",
941 PreviewAutomationRequestErrorFields,
942 ) {
943 override get message(): string {
944 return `Preview automation client ${this.clientId} disconnected during ${this.operation}.`;
945 }
946 }
947
948 export class PreviewAutomationRequestQueueClosedError extends Schema.TaggedError<PreviewAutomationRequestQueueClosedError>()(
949 "PreviewAutomationRequestQueueClosedError",
950 PreviewAutomationRequestErrorFields,
951 ) {
952 override get message(): string {
953 return `Preview automation client ${this.clientId} stopped accepting ${this.operation} requests.`;
954 }
955 }
956
957 export class PreviewAutomationRemoteUnavailableError extends Schema.TaggedError<PreviewAutomationRemoteUnavailableError>()(
958 "PreviewAutomationRemoteUnavailableError",
959 {
960 ...PreviewAutomationRequestErrorFields,
961 ...PreviewAutomationRemoteDiagnosticFields,
962 },
963 ) {
964 override get message(): string {
965 return `Preview automation ${this.operation} is unavailable on client ${this.clientId}.`;
966 }
967 }
968
969 export class PreviewAutomationMalformedResponseError extends Schema.TaggedError<PreviewAutomationMalformedResponseError>()(
970 "PreviewAutomationMalformedResponseError",
971 PreviewAutomationRequestErrorFields,
972 ) {
973 override get message(): string {
974 return `Preview automation client ${this.clientId} returned a malformed response for ${this.operation}.`;
975 }
976 }
977
978 export class PreviewAutomationRecordingTransferError extends Schema.TaggedError<PreviewAutomationRecordingTransferError>()(
979 "PreviewAutomationRecordingTransferError",
980 {
981 threadId: ThreadId,
982 cause: Schema.optional(Schema.Defect()),
983 },
984 ) {
985 override get message(): string {
986 return "Preview recording could not be saved to the agent environment.";
987 }
988 }
989
990 export class PreviewAutomationRecordingDesktopUpdateRequiredError extends Schema.TaggedError<PreviewAutomationRecordingDesktopUpdateRequiredError>()(
991 "PreviewAutomationRecordingDesktopUpdateRequiredError",
992 { threadId: ThreadId, cause: Schema.optional(Schema.Defect()) },
993 ) {
994 override get message(): string {
995 return "Update the desktop app to transfer recordings. The recording remains on the desktop.";
996 }
997 }
998
999 export class PreviewAutomationRecordingTooLargeError extends Schema.TaggedError<PreviewAutomationRecordingTooLargeError>()(
1000 "PreviewAutomationRecordingTooLargeError",
1001 { threadId: ThreadId, cause: Schema.optional(Schema.Defect()) },
1002 ) {
1003 override get message(): string {
1004 return "The recording exceeds 50 MiB. Make a shorter recording.";
1005 }
1006 }
1007
1008 export class PreviewAutomationRecordingDeadlineExpiredError extends Schema.TaggedError<PreviewAutomationRecordingDeadlineExpiredError>()(
1009 "PreviewAutomationRecordingDeadlineExpiredError",
1010 { threadId: ThreadId, cause: Schema.optional(Schema.Defect()) },
1011 ) {
1012 override get message(): string {
1013 return "The recording transfer deadline expired.";
1014 }
1015 }
1016
1017 export const PreviewAutomationError = Schema.Union([
1018 PreviewAutomationRecordingTransferError,
1019 PreviewAutomationRecordingDesktopUpdateRequiredError,
1020 PreviewAutomationRecordingTooLargeError,
1021 PreviewAutomationRecordingDeadlineExpiredError,
1022 PreviewAutomationUnavailableError,
1023 PreviewAutomationNoAvailableHostError,
1024 PreviewAutomationUnsupportedClientError,
1025 PreviewAutomationTabNotFoundError,
1026 PreviewAutomationTimeoutError,
1027 PreviewAutomationControlInterruptedError,
1028 PreviewAutomationExecutionError,
1029 PreviewAutomationInvalidSelectorError,
1030 PreviewAutomationTargetNotEditableError,
1031 PreviewAutomationResultTooLargeError,
1032 PreviewAutomationClientDisconnectedError,
1033 PreviewAutomationRequestQueueClosedError,
1034 PreviewAutomationRemoteUnavailableError,
1035 PreviewAutomationMalformedResponseError,
1036 ]);
1037 export type PreviewAutomationError = typeof PreviewAutomationError.Type;
1038
1039 export const PreviewUrlResolution = Schema.Struct({
1040 requestedUrl: Schema.String,
1041 resolvedUrl: Schema.String,
1042 resolutionKind: Schema.Literals(["direct", "direct-private-network"]),
1043 environmentId: EnvironmentId,
1044 });
1045 export type PreviewUrlResolution = typeof PreviewUrlResolution.Type;