The best way to control Claude Code, Codex and more from any computer or phone
| 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 .", |
| 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); |