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

main
ts 262 lines 11 KB
Raw
1 import {
2 BrowserNavigationTarget,
3 OrchestratorMcpFailure,
4 ToolActivityIcon,
5 PreviewAutomationActInput,
6 PreviewAutomationDialogInput,
7 PreviewAutomationError,
8 PreviewAutomationEvaluateInput,
9 PreviewAutomationNavigateInput,
10 PreviewAutomationOpenInput,
11 PreviewAutomationRecordingArtifact,
12 PreviewAutomationRecordingStatus,
13 PreviewAutomationResizeInput,
14 PreviewAutomationResizeResult,
15 PreviewAutomationSelectResult,
16 PreviewAutomationSetColorSchemeInput,
17 PreviewAutomationSetColorSchemeResult,
18 PreviewAutomationSnapshot,
19 PreviewAutomationSnapshotMetadata,
20 PreviewAutomationStatus,
21 PreviewAutomationTabTargetInput,
22 PreviewAutomationWaitForInput,
23 } from "@t3tools/contracts";
24 import * as Schema from "effect/Schema";
25 import * as FileSystem from "effect/FileSystem";
26 import { McpSchema, Tool, Toolkit } from "effect/ai";
27
28 import * as McpInvocationContext from "../../McpInvocationContext.ts";
29 import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
30 import * as ServerConfig from "../../../config.ts";
31 import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
32
33 const dependencies = [
34 McpInvocationContext.McpInvocationContext,
35 ThreadManagementService.ThreadManagementService,
36 PreviewAutomationBroker.PreviewAutomationBroker,
37 ];
38
39 const PreviewToolFailure = Schema.Union([PreviewAutomationError, OrchestratorMcpFailure]);
40
41 const presentationFields = { toolIcon: Schema.optional(ToolActivityIcon) };
42
43 const PreviewActionResult = Schema.Struct(presentationFields);
44
45 const browserTool = <T extends Tool.Any>(tool: T): T =>
46 tool
47 .annotate(Tool.OpenWorld, true)
48 .annotate(Tool.Destructive, true)
49 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenFromOutsideClients) as T;
50
51 const safeBrowserTool = <T extends Tool.Any>(tool: T): T =>
52 tool
53 .annotate(Tool.OpenWorld, true)
54 .annotate(Tool.Destructive, false)
55 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenFromOutsideClients) as T;
56
57 const readonlyBrowserTool = <T extends Tool.Any>(tool: T): T =>
58 safeBrowserTool(tool).annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true) as T;
59
60 const PreviewStatusTool = Tool.make("preview_status", {
61 description:
62 "Report preview tab state: owner, pending dialog, URL, title, loading, viewport, and size. `tabs` lists this thread's tabs. `profiles` lists logins for `preview_open`. Read any listed tab. Act only on your tab, or an unclaimed tab with no human in control.",
63 parameters: PreviewAutomationTabTargetInput,
64 success: PreviewAutomationStatus,
65 failure: PreviewToolFailure,
66 dependencies,
67 })
68 .annotate(Tool.Title, "Get preview status")
69 .annotate(Tool.Readonly, true)
70 .annotate(Tool.Destructive, false)
71 .annotate(Tool.Idempotent, true)
72 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenFromOutsideClients);
73
74 // `url` already covers websites, so open only adds the dev-server target.
75 const EnvironmentPortTarget = BrowserNavigationTarget.members[1];
76
77 const PreviewOpenTool = browserTool(
78 Tool.make("preview_open", {
79 description:
80 "Open a preview tab in this thread and show it. For a dev server, pass `target` instead of `url`. `open=false` keeps it in the background. Reuses your current tab unless `tabId` or `reuseExistingTab=false` says otherwise. Parallel subagents in one session must each use `reuseExistingTab=false`, then their own returned `tabId`.",
81 parameters: PreviewAutomationOpenInput.mapFields(
82 (fields) => ({ ...fields, target: Schema.optional(EnvironmentPortTarget) }),
83 { unsafePreserveChecks: true },
84 ),
85 success: PreviewAutomationStatus,
86 failure: PreviewToolFailure,
87 dependencies,
88 })
89 .annotate(Tool.Title, "Open browser preview")
90 .annotate(Tool.Destructive, false),
91 );
92
93 const PreviewDialogTool = browserTool(
94 Tool.make("preview_dialog", {
95 description:
96 "Accept or dismiss the dialog `preview_status` reports. Pass `promptText` to accept a prompt. Needs your own tab, or an unclaimed one. Desktop hosts may not support this.",
97 parameters: PreviewAutomationDialogInput,
98 success: PreviewAutomationStatus,
99 failure: PreviewToolFailure,
100 dependencies,
101 }).annotate(Tool.Title, "Resolve browser dialog"),
102 );
103
104 const PreviewNavigateTool = safeBrowserTool(
105 Tool.make("preview_navigate", {
106 description:
107 "Navigate the chosen tab. Pass `url` for a website, or `target:{kind:'environment-port',port}` for a dev server. Exactly one of `url` and `target`.",
108 parameters: PreviewAutomationNavigateInput,
109 success: PreviewAutomationStatus,
110 failure: PreviewToolFailure,
111 dependencies,
112 }).annotate(Tool.Title, "Navigate browser preview"),
113 );
114
115 const PreviewResizeTool = safeBrowserTool(
116 Tool.make("preview_resize", {
117 description:
118 "Resize the chosen tab: {mode:'fill'}, {mode:'freeform',width,height}, or {mode:'preset',preset,orientation}. Changes CSS size only, not the user agent.",
119 parameters: PreviewAutomationResizeInput,
120 success: Schema.Struct({ ...PreviewAutomationResizeResult.fields, ...presentationFields }),
121 failure: PreviewToolFailure,
122 dependencies,
123 })
124 .annotate(Tool.Title, "Resize browser viewport")
125 .annotate(Tool.Idempotent, true),
126 );
127
128 const PreviewSetAppearanceTool = safeBrowserTool(
129 Tool.make("preview_set_appearance", {
130 description:
131 "Set `prefers-color-scheme` for the chosen tab: 'dark', 'light', or 'system' to clear the override.",
132 parameters: PreviewAutomationSetColorSchemeInput,
133 success: Schema.Struct({
134 ...PreviewAutomationSetColorSchemeResult.fields,
135 ...presentationFields,
136 }),
137 failure: PreviewToolFailure,
138 dependencies,
139 })
140 .annotate(Tool.Title, "Set preview appearance")
141 .annotate(Tool.Idempotent, true),
142 );
143
144 // Not read-only: save=true writes the screenshot to disk.
145 export const PreviewSnapshotTool = safeBrowserTool(
146 Tool.make("preview_snapshot", {
147 description:
148 "Use it only when the current request asks for browser work, including checking an edit in the browser. Never use it unasked to verify your own edit, or to repeat a snapshot from an earlier turn. Works on a tab the user is driving. Returns page state, elements, diagnostics, and screenshot size. Target one element with `locator='aria-ref=<ref>'` from `accessibilityTree`, even in frames. Refs die on navigation, a new snapshot, or handoff. Text caps near 20 KB; on your own or an unclaimed tab, `preview_evaluate` reads more. To show a screenshot when asked: `save=true`, then embed ![alt](screenshotPath).",
149 parameters: Schema.Struct({
150 ...PreviewAutomationTabTargetInput.fields,
151 includeImage: Schema.optional(
152 Schema.Boolean.annotate({
153 description: "Default false. True only to see the page.",
154 }),
155 ),
156 save: Schema.optional(
157 Schema.Boolean.annotate({
158 description: "Write PNG, return `screenshotPath`.",
159 }),
160 ),
161 }),
162 success: Schema.Union([PreviewAutomationSnapshot, PreviewAutomationSnapshotMetadata]),
163 failure: PreviewToolFailure,
164 dependencies,
165 }).annotate(Tool.Title, "Inspect browser page"),
166 );
167
168 const PreviewActTool = browserTool(
169 Tool.make("preview_act", {
170 description:
171 "Act on the chosen tab. Target with `locator='aria-ref=<ref>'` from `preview_snapshot`; `x` and `y` go together. `timeoutMs` defaults to 15000. click: `button`, `clickCount` 1 to 3. type: literal `text`, `clear=true` replaces it. hover: shows menus or tooltips. select: `values` in one native <select>, by value or label; for a custom dropdown, click it open, then click the option. drag: `source` onto `target`. upload: absolute `paths` answer the file picker `preview_status` reports, [] cancels it, or a `locator` sets an <input type=file>. press: one `key`, such as 'Enter', with `modifiers`, to the focused element; click a field first to focus it. scroll: the tab, or one container with a locator; positive `deltaY` scrolls down, positive `deltaX` right.",
172 parameters: PreviewAutomationActInput,
173 success: Schema.Union([
174 Schema.Struct({ ...PreviewAutomationSelectResult.fields, ...presentationFields }),
175 PreviewActionResult,
176 ]),
177 failure: PreviewToolFailure,
178 dependencies,
179 }).annotate(Tool.Title, "Act in preview page"),
180 );
181
182 /** Wrap non-objects: MCP requires object structuredContent, and Claude Code rejects invalid results entirely. */
183 export const PreviewEvaluateResult = Schema.Struct({
184 ...presentationFields,
185 value: Schema.Unknown.annotate({
186 description: "The JSON-serializable value the expression produced, or null.",
187 }),
188 });
189
190 const PreviewEvaluateTool = browserTool(
191 Tool.make("preview_evaluate", {
192 description:
193 "Run JavaScript in the page. It can change page state. Returns `{value}`, up to 64 KB. Needs your tab, or an unclaimed one. To read a tab the user drives, use `preview_snapshot`. Page tools write only on user request. Show results with `html_render`, never page tools.",
194 parameters: PreviewAutomationEvaluateInput,
195 success: PreviewEvaluateResult,
196 failure: PreviewToolFailure,
197 dependencies,
198 }).annotate(Tool.Title, "Evaluate JavaScript in preview"),
199 );
200
201 const PreviewWaitForTool = readonlyBrowserTool(
202 Tool.make("preview_wait_for", {
203 description:
204 "Wait until all given locator, selector, text, and URL conditions match in the chosen tab.",
205 parameters: PreviewAutomationWaitForInput,
206 success: PreviewActionResult,
207 failure: PreviewToolFailure,
208 dependencies,
209 }).annotate(Tool.Title, "Wait for preview page condition"),
210 );
211
212 const PreviewRecordingStartTool = safeBrowserTool(
213 Tool.make("preview_recording_start", {
214 description: "Start recording the chosen tab.",
215 parameters: PreviewAutomationTabTargetInput,
216 success: Schema.Struct({ ...PreviewAutomationRecordingStatus.fields, ...presentationFields }),
217 failure: PreviewToolFailure,
218 dependencies,
219 }).annotate(Tool.Title, "Start browser recording"),
220 );
221
222 const PreviewRecordingStopTool = safeBrowserTool(
223 Tool.make("preview_recording_stop", {
224 description:
225 "Stop recording the chosen tab. Returns a local path to the recording file (max 50 MiB).",
226 parameters: PreviewAutomationTabTargetInput,
227 success: Schema.Struct({ ...PreviewAutomationRecordingArtifact.fields, ...presentationFields }),
228 failure: PreviewToolFailure,
229 dependencies: [...dependencies, FileSystem.FileSystem, ServerConfig.ServerConfig],
230 }).annotate(Tool.Title, "Stop browser recording"),
231 );
232
233 export const PreviewToolkit = Toolkit.make(
234 PreviewDialogTool,
235 PreviewStatusTool,
236 PreviewOpenTool,
237 PreviewNavigateTool,
238 PreviewResizeTool,
239 PreviewSetAppearanceTool,
240 PreviewSnapshotTool,
241 PreviewActTool,
242 PreviewEvaluateTool,
243 PreviewWaitForTool,
244 PreviewRecordingStartTool,
245 PreviewRecordingStopTool,
246 );
247
248 export const PreviewStandardToolkit = Toolkit.make(
249 PreviewDialogTool,
250 PreviewStatusTool,
251 PreviewOpenTool,
252 PreviewNavigateTool,
253 PreviewResizeTool,
254 PreviewSetAppearanceTool,
255 PreviewActTool,
256 PreviewEvaluateTool,
257 PreviewWaitForTool,
258 PreviewRecordingStartTool,
259 PreviewRecordingStopTool,
260 );
261
262 export const PreviewSnapshotToolkit = Toolkit.make(PreviewSnapshotTool);