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

main
ts 408 lines 13.8 KB
Raw
1 import { Schema } from "effect";
2 import { NonNegativeInt, PositiveInt, ThreadId, TrimmedNonEmptyString } from "./baseSchemas.ts";
3 import { BROWSER_PROFILE_MAX_COUNT, BrowserProfile, BrowserProfileId } from "./browserProfile.ts";
4
5 export const PREVIEW_URL_MAX_LENGTH = 2_048;
6 export const CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS = 32;
7
8 const Url = TrimmedNonEmptyString.check(Schema.isMaxLength(PREVIEW_URL_MAX_LENGTH));
9
10 export const ConfiguredLocalServerUrls = Schema.Array(Url).check(
11 Schema.isMaxLength(CONFIGURED_LOCAL_SERVER_URLS_MAX_ITEMS),
12 );
13 const Title = Schema.String.check(Schema.isMaxLength(512));
14
15 export const PreviewTabId = TrimmedNonEmptyString.check(Schema.isMaxLength(128));
16 export type PreviewTabId = typeof PreviewTabId.Type;
17
18 export const PREVIEW_VIEWPORT_MIN_DIMENSION = 240;
19 export const PREVIEW_VIEWPORT_MAX_DIMENSION = 3840;
20 export const PREVIEW_VIEWPORT_MAX_AREA = 3840 * 2160;
21
22 const PreviewViewportDimension = Schema.Int.check(
23 Schema.isBetween({
24 minimum: PREVIEW_VIEWPORT_MIN_DIMENSION,
25 maximum: PREVIEW_VIEWPORT_MAX_DIMENSION,
26 }),
27 );
28
29 const viewportAreaFilter = Schema.makeFilter(
30 ({ width, height }: { readonly width: number; readonly height: number }) =>
31 width * height <= PREVIEW_VIEWPORT_MAX_AREA ||
32 `Viewport area must not exceed ${PREVIEW_VIEWPORT_MAX_AREA} pixels.`,
33 );
34
35 export const PreviewViewportSize = Schema.Struct({
36 width: PreviewViewportDimension,
37 height: PreviewViewportDimension,
38 }).check(viewportAreaFilter);
39 export type PreviewViewportSize = typeof PreviewViewportSize.Type;
40
41 /** Fill mode can measure below selectable minimum sizes; validate measurements separately. */
42 export const PreviewRenderedViewportSize = Schema.Struct({
43 width: Schema.Int.check(Schema.isGreaterThan(0)),
44 height: Schema.Int.check(Schema.isGreaterThan(0)),
45 });
46 export type PreviewRenderedViewportSize = typeof PreviewRenderedViewportSize.Type;
47
48 export const PREVIEW_VIEWPORT_PRESET_IDS = [
49 "iphone-se",
50 "iphone-xr",
51 "iphone-12-pro",
52 "iphone-14-pro-max",
53 "pixel-7",
54 "samsung-galaxy-s8-plus",
55 "samsung-galaxy-s20-ultra",
56 "ipad-mini",
57 "ipad-air",
58 "ipad-pro",
59 "surface-pro-7",
60 "surface-duo",
61 "galaxy-z-fold-5",
62 "asus-zenbook-fold",
63 "samsung-galaxy-a51-71",
64 "nest-hub",
65 "nest-hub-max",
66 ] as const;
67
68 export const PreviewViewportPresetId = Schema.Literals(PREVIEW_VIEWPORT_PRESET_IDS);
69 export type PreviewViewportPresetId = typeof PreviewViewportPresetId.Type;
70
71 const LEGACY_PREVIEW_VIEWPORT_PRESET_IDS = [
72 "desktop-1920x1080",
73 "desktop-1440x900",
74 "laptop-1366x768",
75 "laptop-1280x800",
76 "ipad-pro-11",
77 "iphone-15-pro",
78 "pixel-8",
79 "galaxy-s24",
80 ] as const;
81
82 const StoredPreviewViewportPresetId = Schema.Literals([
83 ...PREVIEW_VIEWPORT_PRESET_IDS,
84 ...LEGACY_PREVIEW_VIEWPORT_PRESET_IDS,
85 ]);
86
87 export const PreviewViewportSetting = Schema.Union([
88 Schema.TaggedStruct("fill", {}),
89 Schema.TaggedStruct("freeform", {
90 ...PreviewViewportSize.fields,
91 }).check(viewportAreaFilter),
92 Schema.TaggedStruct("preset", {
93 ...PreviewViewportSize.fields,
94 presetId: StoredPreviewViewportPresetId,
95 }).check(viewportAreaFilter),
96 ]);
97 export type PreviewViewportSetting = typeof PreviewViewportSetting.Type;
98
99 export const FILL_PREVIEW_VIEWPORT = {
100 _tag: "fill",
101 } as const satisfies PreviewViewportSetting;
102
103 /** Shared steps keep settings aligned with desktop Chromium zoom controls. */
104 export const PREVIEW_ZOOM_LEVELS = [
105 0.25, 0.33, 0.5, 0.67, 0.75, 0.8, 0.9, 1.0, 1.1, 1.25, 1.5, 1.75, 2.0, 2.5, 3.0, 4.0, 5.0,
106 ] as const;
107
108 export const PreviewZoomFactor = Schema.Literals(PREVIEW_ZOOM_LEVELS);
109 export type PreviewZoomFactor = typeof PreviewZoomFactor.Type;
110
111 export const DEFAULT_PREVIEW_ZOOM_FACTOR: PreviewZoomFactor = 1.0;
112
113 export const PreviewAppearancePreference = Schema.Literals(["system", "light", "dark"]);
114 export type PreviewAppearancePreference = typeof PreviewAppearancePreference.Type;
115
116 export const DEFAULT_PREVIEW_APPEARANCE: PreviewAppearancePreference = "system";
117
118 const PreviewFileDownload = Schema.Struct({ id: Schema.String, fileName: Schema.String });
119
120 export const PreviewNavStatus = Schema.Union([
121 Schema.TaggedStruct("Idle", {}),
122 Schema.TaggedStruct("Loading", {
123 url: Url,
124 title: Title,
125 }),
126 Schema.TaggedStruct("Success", {
127 url: Url,
128 title: Title,
129 }),
130 Schema.TaggedStruct("LoadFailed", {
131 url: Url,
132 title: Title,
133 code: Schema.Int,
134 description: Schema.String,
135 download: Schema.optional(PreviewFileDownload),
136 }),
137 ]);
138 export type PreviewNavStatus = typeof PreviewNavStatus.Type;
139
140 export const PreviewRuntime = Schema.Literals(["desktop", "server"]);
141 export type PreviewRuntime = typeof PreviewRuntime.Type;
142
143 /** JSON reason for preview stream close code 4503; must fit the 123-byte close-reason limit. */
144 export const PreviewStreamHostSetup = Schema.Struct({
145 need: Schema.Literals(["sandbox", "libraries"]),
146 command: Schema.String,
147 });
148 export type PreviewStreamHostSetup = typeof PreviewStreamHostSetup.Type;
149 export const PREVIEW_STREAM_HOST_SETUP_CLOSE_CODE = 4503;
150
151 export const PreviewSessionSnapshot = Schema.Struct({
152 threadId: TrimmedNonEmptyString,
153 tabId: PreviewTabId,
154 navStatus: PreviewNavStatus,
155 canGoBack: Schema.Boolean,
156 canGoForward: Schema.Boolean,
157 viewport: Schema.optional(PreviewViewportSetting),
158 colorScheme: Schema.optional(PreviewAppearancePreference),
159 zoomFactor: Schema.optional(PreviewZoomFactor),
160 /** Fixed at open; Electron cannot change a webview partition after attach without losing page state. */
161 profileId: Schema.optional(BrowserProfileId),
162 runtime: Schema.optional(PreviewRuntime),
163 /** The server runs this tab in headless Chromium, so the desktop streams it like other clients. */
164 headless: Schema.optional(Schema.Boolean),
165 automationOwner: Schema.optional(Schema.String),
166 reveal: Schema.optional(Schema.Boolean),
167 revealRequest: Schema.optional(Schema.Struct({ id: Schema.String, force: Schema.Boolean })),
168 updatedAt: Schema.String,
169 });
170 export type PreviewSessionSnapshot = typeof PreviewSessionSnapshot.Type;
171
172 export const PreviewOpenInput = Schema.Struct({
173 threadId: ThreadId,
174 url: Schema.optional(Url),
175 viewport: Schema.optional(PreviewViewportSetting),
176 profileId: Schema.optional(BrowserProfileId),
177 runtime: Schema.optional(PreviewRuntime),
178 colorScheme: Schema.optional(PreviewAppearancePreference),
179 zoomFactor: Schema.optional(PreviewZoomFactor),
180 reveal: Schema.optional(Schema.Boolean),
181 });
182 export type PreviewOpenInput = typeof PreviewOpenInput.Type;
183
184 export const PreviewReportStatusInput = Schema.Struct({
185 threadId: ThreadId,
186 tabId: PreviewTabId,
187 navStatus: PreviewNavStatus,
188 canGoBack: Schema.Boolean,
189 canGoForward: Schema.Boolean,
190 });
191 export type PreviewReportStatusInput = typeof PreviewReportStatusInput.Type;
192
193 export const PreviewResizeInput = Schema.Struct({
194 threadId: ThreadId,
195 tabId: PreviewTabId,
196 viewport: PreviewViewportSetting,
197 });
198 export type PreviewResizeInput = typeof PreviewResizeInput.Type;
199
200 /** Requires no tab control, unlike page input. */
201 export const PreviewAdjustInput = Schema.Struct({
202 threadId: ThreadId,
203 tabId: PreviewTabId,
204 colorScheme: Schema.optional(PreviewAppearancePreference),
205 zoomFactor: Schema.optional(PreviewZoomFactor),
206 hardReload: Schema.optional(Schema.Boolean),
207 clear: Schema.optional(Schema.Literals(["cookies", "cache"])),
208 });
209 export type PreviewAdjustInput = typeof PreviewAdjustInput.Type;
210
211 export const PreviewCloseInput = Schema.Struct({
212 threadId: ThreadId,
213 tabId: Schema.optional(PreviewTabId),
214 });
215 export type PreviewCloseInput = typeof PreviewCloseInput.Type;
216
217 export const BROWSER_RECORDING_FRAME_RATES = [30, 60] as const;
218 export const BrowserRecordingFrameRate = Schema.Literals(BROWSER_RECORDING_FRAME_RATES);
219 export type BrowserRecordingFrameRate = typeof BrowserRecordingFrameRate.Type;
220 export const DEFAULT_BROWSER_RECORDING_FRAME_RATE: BrowserRecordingFrameRate = 30;
221
222 export const PreviewReportProfilesInput = Schema.Struct({
223 profiles: Schema.Array(BrowserProfile).check(Schema.isMaxLength(BROWSER_PROFILE_MAX_COUNT)),
224 defaultProfileId: BrowserProfileId,
225 /** Optional so older clients keep reporting; omitting it keeps the last reported rate. */
226 recordingFrameRate: Schema.optional(BrowserRecordingFrameRate),
227 });
228 export type PreviewReportProfilesInput = typeof PreviewReportProfilesInput.Type;
229
230 export const PreviewClearProfileInput = Schema.Struct({
231 profileId: BrowserProfileId,
232 });
233 export type PreviewClearProfileInput = typeof PreviewClearProfileInput.Type;
234
235 export const PreviewListInput = Schema.Struct({
236 threadId: ThreadId,
237 });
238 export type PreviewListInput = typeof PreviewListInput.Type;
239
240 export const PreviewListResult = Schema.Struct({
241 sessions: Schema.Array(PreviewSessionSnapshot),
242 /** Identifies the current server process so revision resets are safe. */
243 serverEpoch: TrimmedNonEmptyString,
244 revision: NonNegativeInt,
245 });
246 export type PreviewListResult = typeof PreviewListResult.Type;
247
248 const PreviewEventBaseSchema = Schema.Struct({
249 threadId: TrimmedNonEmptyString,
250 tabId: PreviewTabId,
251 createdAt: Schema.String,
252 serverEpoch: TrimmedNonEmptyString,
253 /** Monotonic server state revision shared with PreviewListResult. */
254 revision: PositiveInt,
255 });
256
257 const PreviewOpenedEvent = Schema.Struct({
258 ...PreviewEventBaseSchema.fields,
259 type: Schema.Literal("opened"),
260 snapshot: PreviewSessionSnapshot,
261 });
262
263 const PreviewNavigatedEvent = Schema.Struct({
264 ...PreviewEventBaseSchema.fields,
265 type: Schema.Literal("navigated"),
266 snapshot: PreviewSessionSnapshot,
267 });
268
269 const PreviewResizedEvent = Schema.Struct({
270 ...PreviewEventBaseSchema.fields,
271 type: Schema.Literal("resized"),
272 snapshot: PreviewSessionSnapshot,
273 request: Schema.optional(
274 Schema.Struct({
275 hardReload: Schema.optional(Schema.Boolean),
276 clear: Schema.optional(Schema.Literals(["cookies", "cache"])),
277 }),
278 ),
279 });
280
281 const PreviewFailedEvent = Schema.Struct({
282 ...PreviewEventBaseSchema.fields,
283 type: Schema.Literal("failed"),
284 url: Url,
285 title: Title,
286 code: Schema.Int,
287 description: Schema.String,
288 download: Schema.optional(PreviewFileDownload),
289 });
290
291 const PreviewClosedEvent = Schema.Struct({
292 ...PreviewEventBaseSchema.fields,
293 type: Schema.Literal("closed"),
294 });
295
296 export const PreviewEvent = Schema.Union([
297 PreviewOpenedEvent,
298 PreviewNavigatedEvent,
299 PreviewResizedEvent,
300 PreviewFailedEvent,
301 PreviewClosedEvent,
302 ]);
303 export type PreviewEvent = typeof PreviewEvent.Type;
304
305 const LocalServerPort = Schema.Int.check(Schema.isGreaterThan(0)).check(Schema.isLessThan(65536));
306
307 export const DiscoveredLocalServer = Schema.Struct({
308 host: TrimmedNonEmptyString,
309 port: LocalServerPort,
310 url: Url,
311 processName: Schema.NullOr(TrimmedNonEmptyString),
312 pid: Schema.NullOr(Schema.Int.check(Schema.isGreaterThan(0))),
313 terminal: Schema.NullOr(
314 Schema.Struct({
315 threadId: ThreadId,
316 terminalId: TrimmedNonEmptyString,
317 }),
318 ),
319 /** Started by the thread's agent. Older servers omit it. */
320 agent: Schema.optionalKey(Schema.NullOr(Schema.Struct({ threadId: ThreadId }))),
321 });
322 export type DiscoveredLocalServer = typeof DiscoveredLocalServer.Type;
323
324 export const PreviewStopLocalServerInput = Schema.Struct({
325 pid: PositiveInt,
326 port: LocalServerPort,
327 });
328 export type PreviewStopLocalServerInput = typeof PreviewStopLocalServerInput.Type;
329
330 export class PreviewStopLocalServerError extends Schema.TaggedError<PreviewStopLocalServerError>()(
331 "PreviewStopLocalServerError",
332 {
333 reason: Schema.Literals(["not-found", "shared-group", "unsupported", "signal-failed"]),
334 cause: Schema.optional(Schema.Defect()),
335 },
336 ) {
337 override get message() {
338 switch (this.reason) {
339 case "not-found":
340 return "This server is no longer running.";
341 case "shared-group":
342 return "This server shares a process group with T3 Code, an agent, or a terminal shell, so it can't be stopped on its own.";
343 case "unsupported":
344 return "Stopping servers is not supported on this environment's platform.";
345 case "signal-failed":
346 return "The server's processes could not be signaled.";
347 }
348 }
349 }
350
351 export const DiscoveredLocalServerList = Schema.Struct({
352 servers: Schema.Array(DiscoveredLocalServer),
353 scannedAt: Schema.String,
354 configuredUrlProbing: Schema.optional(Schema.Literal(true)),
355 });
356 export type DiscoveredLocalServerList = typeof DiscoveredLocalServerList.Type;
357
358 export class PreviewSessionLookupError extends Schema.TaggedError<PreviewSessionLookupError>()(
359 "PreviewSessionLookupError",
360 {
361 threadId: Schema.String,
362 tabId: Schema.String,
363 },
364 ) {
365 override get message() {
366 return `Unknown preview session: thread=${this.threadId}, tab=${this.tabId}`;
367 }
368 }
369
370 export class PreviewInvalidUrlError extends Schema.TaggedError<PreviewInvalidUrlError>()(
371 "PreviewInvalidUrlError",
372 {
373 inputLength: Schema.Number,
374 reason: Schema.Literals(["empty", "parse", "unsupported-protocol", "unexpected"]),
375 protocol: Schema.optional(Schema.String),
376 cause: Schema.Defect(),
377 },
378 ) {
379 override get message() {
380 const protocol = this.protocol === undefined ? "" : `: ${this.protocol}`;
381 return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}). Use an http(s) URL or a schemeless host such as localhost:5173. With preview_open, omit url when creating a new tab to open a blank tab.`;
382 }
383 }
384
385 export class PreviewControlRequiredError extends Schema.TaggedError<PreviewControlRequiredError>()(
386 "PreviewControlRequiredError",
387 { tabId: Schema.String },
388 ) {
389 override get message() {
390 return "Take control of the server browser and use its viewer controls.";
391 }
392 }
393
394 export class PreviewClearProfileError extends Schema.TaggedError<PreviewClearProfileError>()(
395 "PreviewClearProfileError",
396 { profileId: Schema.String, cause: Schema.Defect() },
397 ) {
398 override get message() {
399 return "The environment could not delete this browser profile's data.";
400 }
401 }
402
403 export const PreviewError = Schema.Union([
404 PreviewSessionLookupError,
405 PreviewInvalidUrlError,
406 PreviewControlRequiredError,
407 ]);
408 export type PreviewError = typeof PreviewError.Type;