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, 04:45 UTC
| 1 | import { |
| 2 | type DeviceError, |
| 3 | type DeviceHostId, |
| 4 | type DeviceHostSummary, |
| 5 | type DeviceId, |
| 6 | type DevicePlatform, |
| 7 | type DeviceServiceState, |
| 8 | type DeviceSummary, |
| 9 | DeviceToolUnavailableError, |
| 10 | LOCAL_DEVICE_HOST_ID, |
| 11 | } from "@t3tools/contracts"; |
| 12 | import * as Effect from "effect/Effect"; |
| 13 | import * as Option from "effect/Option"; |
| 14 | import * as DeviceService from "../../../device/DeviceService.ts"; |
| 15 | import { threadWorkspaceRoot } from "../../../project/threadWorkspaceRoot.ts"; |
| 16 | import * as McpInvocationContext from "../../McpInvocationContext.ts"; |
| 17 | import * as McpToolAccess from "../../McpToolAccess.ts"; |
| 18 | import { DeviceScreenshotToolkit, DeviceStandardToolkit, DeviceToolkit } from "./tools.ts"; |
| 19 | |
| 20 | function agentDeviceTargetArgs(device: DeviceSummary): ReadonlyArray<string> { |
| 21 | return device.platform === "ios" |
| 22 | ? ["--platform", "ios", "--udid", device.id] |
| 23 | : ["--platform", "android", "--serial", device.id]; |
| 24 | } |
| 25 | |
| 26 | const shellWord = (value: string) => |
| 27 | /^[a-zA-Z0-9_./:-]+$/.test(value) ? value : "'" + value.replaceAll("'", "'\"'\"'") + "'"; |
| 28 | |
| 29 | /** `targetArgs` are the flags the command still needs; a bound launcher needs none. */ |
| 30 | export function agentDeviceQuickStart( |
| 31 | device: DeviceSummary, |
| 32 | targetArgs = agentDeviceTargetArgs(device), |
| 33 | command = "agent-device", |
| 34 | host?: |
| 35 | | { readonly kind: "eas" } |
| 36 | | { readonly kind: "simlock"; readonly installDirectory?: string }, |
| 37 | ): string { |
| 38 | const executable = shellWord(command); |
| 39 | const target = targetArgs.map(shellWord).join(" "); |
| 40 | const run = (args: string) => [executable, args, target].filter(Boolean).join(" "); |
| 41 | const platformNotes = |
| 42 | host?.kind === "simlock" |
| 43 | ? [ |
| 44 | "This device is leased from a Simlock pool (alpha in T3 Code). The lease returns it to the pool, wiped, when it ends, so call device_close with shutdown: true when you are done. It starts with no apps installed.", |
| 45 | host.installDirectory |
| 46 | ? `agent-device accepts install for this lease only when run from ${host.installDirectory}.` |
| 47 | : "", |
| 48 | ] |
| 49 | .filter(Boolean) |
| 50 | .join(" ") |
| 51 | : host?.kind === "eas" |
| 52 | ? "This is an Expo Simulators session in the cloud. It bills the Expo account per minute until it stops, so call device_close with shutdown: true when you are done. It starts with no apps installed: install-from-source <url> installs a build from a URL (iOS needs a .tar.gz containing a .app), and install uploads one from this machine." |
| 53 | : device.platform === "ios" |
| 54 | ? "First use builds an XCTest runner and can take a couple of minutes; later commands are fast." |
| 55 | : "The Android snapshot helper installs itself on first use."; |
| 56 | return [ |
| 57 | `The user is watching ${device.name} (${device.version}) in the Device panel.`, |
| 58 | target === "" |
| 59 | ? `Drive it with ${executable}. It is bound to this device and session, so it needs no --platform, --udid, --serial, --config or --session flags. Use this exact path; login shells may reset PATH.` |
| 60 | : `Drive it with ${executable}. Use this exact path; login shells may reset PATH. Always pass ${target}.`, |
| 61 | // Screenshots and input need the session agent-device's open starts, and an iOS snapshot also |
| 62 | // needs its app. device_open does not run open itself: on iOS that can start a minutes-long |
| 63 | // XCTest runner build. |
| 64 | "Every app launch, deep link, tap, text entry, alert, setting, screenshot and recording on this device goes through it. Run open <bundle-or-package-id> (apps lists them) before snapshots, CLI screenshots or input; it starts the session they need. Use device_screenshot just to look.", |
| 65 | ` ${run("open <bundle-or-package-id> --relaunch")} # restarts the app; Expo dev clients connect to their Metro, --metro-port <port> picks it`, |
| 66 | ` ${run("open <bundle-or-package-id> <deep-link-url>")}`, |
| 67 | ` ${run("snapshot -i")} # accessibility tree with @eN refs`, |
| 68 | ` ${run("press @e3 --settle")}`, |
| 69 | ` ${run('fill @e5 "text" --settle')}`, |
| 70 | ` ${run("alert accept")}`, |
| 71 | ` ${run("settings appearance dark")} # also text-size, permission grant <name>`, |
| 72 | ` ${run("screenshot /tmp/shot.png")} # ${device.platform === "ios" ? "iOS saves 1x points; add --pixel-density <n> (3 on most iPhones) for device resolution, " : ""}or call device_screenshot to look`, |
| 73 | ` ${run("record start --scope device /tmp/run.mp4")} # then record stop`, |
| 74 | ` ${run("install <app> <path-to-.app-or-.apk>")}`, |
| 75 | `Prefer snapshot refs over coordinates. Run ${executable} help <command> for flags and ${executable} help workflow for guides.`, |
| 76 | "Do not use simctl, idb, adb or ssh for those actions. They stay fine for builds, installs, code sync, Metro, port forwards, logs, test runners and what this command cannot do; come back to it for every UI action and screenshot so the user can watch.", |
| 77 | "Each device_open returns its own command; opening another device does not retarget this one.", |
| 78 | ...(target === "" |
| 79 | ? [ |
| 80 | "The command is removed when the device closes or T3 Code restarts. If it is missing, call device_open again.", |
| 81 | ] |
| 82 | : []), |
| 83 | platformNotes, |
| 84 | ].join("\n"); |
| 85 | } |
| 86 | |
| 87 | const requireDeviceAccess = McpInvocationContext.requireThreadMcpCapability("device").pipe( |
| 88 | Effect.mapError( |
| 89 | () => |
| 90 | new DeviceToolUnavailableError({ |
| 91 | reason: |
| 92 | "Agent device access is turned off for this environment. Ask the user to turn on the Device hub and Agent device access in Settings > Integrations > Devices; it applies when the agent session next starts, such as in a new thread.", |
| 93 | }), |
| 94 | ), |
| 95 | ); |
| 96 | |
| 97 | export const resolveHostId = Effect.fn("handlers.resolveHostId")(function* ( |
| 98 | hosts: ReadonlyArray<DeviceHostSummary>, |
| 99 | hostId: string | undefined, |
| 100 | ): Effect.fn.Return<DeviceHostId | undefined, DeviceToolUnavailableError> { |
| 101 | if (!hostId) return undefined; |
| 102 | const exact = hosts.find((host) => host.id === hostId); |
| 103 | if (exact) return exact.id; |
| 104 | const labelMatches = hosts.filter((host) => host.label.toLowerCase() === hostId.toLowerCase()); |
| 105 | if (labelMatches.length === 1) return labelMatches[0]!.id; |
| 106 | const candidates = labelMatches.length > 1 ? labelMatches : hosts; |
| 107 | const listed = [ |
| 108 | ...candidates.slice(0, 10).map((host) => `${host.label.slice(0, 64)} (${host.id})`), |
| 109 | ...(candidates.length > 10 ? [`${candidates.length - 10} more`] : []), |
| 110 | ].join(", "); |
| 111 | const selector = hostId.slice(0, 128); |
| 112 | return yield* new DeviceToolUnavailableError({ |
| 113 | reason: |
| 114 | labelMatches.length > 1 |
| 115 | ? `Several device hosts are named ${selector}; pass one id: ${listed}.` |
| 116 | : `No device host ${selector}. Known hosts: ${listed || "none"}.`, |
| 117 | }); |
| 118 | }); |
| 119 | |
| 120 | const hostName = (host: { readonly id: DeviceHostId; readonly label?: string | undefined }) => |
| 121 | host.label === undefined ? `hostId ${host.id}` : `'${host.label}' (hostId ${host.id})`; |
| 122 | |
| 123 | const mapLocateErrors = <A, R>( |
| 124 | effect: Effect.Effect< |
| 125 | A, |
| 126 | DeviceService.DeviceHostAmbiguousError | DeviceService.DeviceOnOtherHostError, |
| 127 | R |
| 128 | >, |
| 129 | ) => |
| 130 | effect.pipe( |
| 131 | Effect.catchTags({ |
| 132 | DeviceHostAmbiguousError: (error) => |
| 133 | Effect.fail( |
| 134 | new DeviceToolUnavailableError({ |
| 135 | reason: `Device ${error.deviceId} is on more than one host: ${error.hosts.map(hostName).join(", ")}. Pass hostId.`, |
| 136 | }), |
| 137 | ), |
| 138 | DeviceOnOtherHostError: (error) => |
| 139 | Effect.fail( |
| 140 | new DeviceToolUnavailableError({ |
| 141 | reason: `Device ${error.deviceId} is not on ${hostName(error.host)}. It is on ${error.hosts.map(hostName).join(", ")}; pass that hostId.`, |
| 142 | }), |
| 143 | ), |
| 144 | }), |
| 145 | ); |
| 146 | |
| 147 | const failedHosts = <H extends { readonly id: DeviceHostId }>( |
| 148 | state: { readonly hostStatuses: DeviceServiceState["hostStatuses"] }, |
| 149 | hosts: ReadonlyArray<H>, |
| 150 | ) => |
| 151 | hosts.flatMap((host) => { |
| 152 | const status = state.hostStatuses[host.id]; |
| 153 | return status?.status === "failed" && status.detail ? [{ host, detail: status.detail }] : []; |
| 154 | }); |
| 155 | |
| 156 | const pickDevice = Effect.fn("handlers.pickDevice")(function* ( |
| 157 | state: { |
| 158 | readonly hosts: ReadonlyArray<DeviceHostSummary>; |
| 159 | readonly hostStatuses: DeviceServiceState["hostStatuses"]; |
| 160 | readonly devices: ReadonlyArray<DeviceSummary>; |
| 161 | }, |
| 162 | input: { |
| 163 | readonly deviceId?: DeviceId | undefined; |
| 164 | readonly platform?: DevicePlatform | undefined; |
| 165 | readonly hostId?: DeviceHostId | undefined; |
| 166 | }, |
| 167 | ): Effect.fn.Return<DeviceSummary, DeviceToolUnavailableError, DeviceService.DeviceService> { |
| 168 | if (input.deviceId !== undefined) { |
| 169 | const { deviceId, hostId } = input; |
| 170 | const devices = yield* DeviceService.DeviceService; |
| 171 | const located = yield* devices.locateDevice({ deviceId, hostId }).pipe(mapLocateErrors); |
| 172 | if (Option.isSome(located)) return located.value; |
| 173 | const target = |
| 174 | hostId === undefined |
| 175 | ? undefined |
| 176 | : (state.hosts.find((host) => host.id === hostId) ?? { id: hostId }); |
| 177 | const failures = failedHosts(state, target === undefined ? state.hosts : [target]).map( |
| 178 | ({ host, detail }) => `${hostName(host)} failed to start: ${detail}`, |
| 179 | ); |
| 180 | return yield* new DeviceToolUnavailableError({ |
| 181 | reason: [ |
| 182 | `No device ${deviceId} on ${target === undefined ? "any host" : hostName(target)}.`, |
| 183 | ...failures, |
| 184 | "Call device_list for current ids.", |
| 185 | ].join(" "), |
| 186 | }); |
| 187 | } |
| 188 | const hostId = input.hostId ?? LOCAL_DEVICE_HOST_ID; |
| 189 | const candidates = state.devices.filter( |
| 190 | (device) => |
| 191 | device.hostId === hostId && |
| 192 | (input.platform === undefined || device.platform === input.platform), |
| 193 | ); |
| 194 | if (candidates.length === 0) { |
| 195 | const [failure] = failedHosts(state, [{ id: hostId }]); |
| 196 | return yield* new DeviceToolUnavailableError({ |
| 197 | reason: |
| 198 | failure !== undefined |
| 199 | ? failure.detail |
| 200 | : input.platform === undefined |
| 201 | ? "No simulators or emulators were found. Call device_list to see why." |
| 202 | : `No ${input.platform} devices were found on host ${hostId}. Call device_list to see why.`, |
| 203 | }); |
| 204 | } |
| 205 | const platforms = new Set(candidates.map((device) => device.platform)); |
| 206 | if (input.platform === undefined && platforms.size > 1) { |
| 207 | return yield* new DeviceToolUnavailableError({ |
| 208 | reason: "Both iOS and Android devices are available; pass platform or deviceId.", |
| 209 | }); |
| 210 | } |
| 211 | return candidates.find((device) => device.booted) ?? candidates[0]!; |
| 212 | }); |
| 213 | |
| 214 | const toolError = (error: DeviceError | DeviceToolUnavailableError) => error; |
| 215 | |
| 216 | const handlers = { |
| 217 | device_list: McpToolAccess.readsAsCaller((input) => |
| 218 | Effect.gen(function* () { |
| 219 | const scope = yield* requireDeviceAccess; |
| 220 | const devices = yield* DeviceService.DeviceService; |
| 221 | const state = yield* devices.list; |
| 222 | if (state.hostStatus === "disabled") { |
| 223 | return yield* new DeviceToolUnavailableError({ |
| 224 | reason: |
| 225 | "Device support is off. Ask the user to enable it in the Device panel before installing or starting device tools.", |
| 226 | }); |
| 227 | } |
| 228 | const hostId = yield* resolveHostId(state.hosts, input?.hostId); |
| 229 | const open = state.sessions |
| 230 | .filter((session) => session.threadId === scope.thread.threadId) |
| 231 | .map((session) => ({ hostId: session.hostId, deviceId: session.deviceId })); |
| 232 | return { |
| 233 | hostStatuses: Object.fromEntries( |
| 234 | Object.entries(state.hostStatuses).filter(([id]) => !hostId || id === hostId), |
| 235 | ), |
| 236 | hosts: hostId ? state.hosts.filter((host) => host.id === hostId) : state.hosts, |
| 237 | devices: hostId |
| 238 | ? state.devices.filter((device) => device.hostId === hostId) |
| 239 | : state.devices, |
| 240 | open, |
| 241 | }; |
| 242 | }).pipe(Effect.mapError(toolError)), |
| 243 | ), |
| 244 | device_open: McpToolAccess.actsAsCaller((input) => |
| 245 | Effect.gen(function* () { |
| 246 | const scope = yield* requireDeviceAccess; |
| 247 | const devices = yield* DeviceService.DeviceService; |
| 248 | const state = yield* devices.list; |
| 249 | if (state.hostStatus === "disabled") { |
| 250 | return yield* new DeviceToolUnavailableError({ |
| 251 | reason: |
| 252 | "Device support is off. Ask the user to enable it in the Device panel before installing or starting device tools.", |
| 253 | }); |
| 254 | } |
| 255 | const hostId = yield* resolveHostId(state.hosts, input.hostId); |
| 256 | const target = yield* pickDevice(state, { ...input, hostId }); |
| 257 | // Resolve consent and agent connectivity before booting or registering a session. |
| 258 | if (!(yield* devices.agentReadinessIfSupported(target.hostId))) { |
| 259 | return yield* new DeviceToolUnavailableError({ |
| 260 | reason: |
| 261 | "Agent device access requires enabled device support, agent access, and an available simulator platform on this host.", |
| 262 | }); |
| 263 | } |
| 264 | const session = yield* devices.open( |
| 265 | { |
| 266 | threadId: scope.thread.threadId, |
| 267 | hostId: target.hostId, |
| 268 | deviceId: target.id, |
| 269 | platform: target.platform, |
| 270 | }, |
| 271 | { workspaceRoot: yield* threadWorkspaceRoot(scope.thread.threadId) }, |
| 272 | ); |
| 273 | const after = yield* devices.state; |
| 274 | const device = |
| 275 | after.devices.find( |
| 276 | (candidate) => candidate.hostId === session.hostId && candidate.id === session.deviceId, |
| 277 | ) ?? target; |
| 278 | // Target the opened device: an Expo device and its agent-device daemon |
| 279 | // exist only once its session runs, and Android ids change on boot. |
| 280 | const opened = { |
| 281 | threadId: scope.thread.threadId, |
| 282 | hostId: session.hostId, |
| 283 | deviceId: session.deviceId, |
| 284 | }; |
| 285 | const agent = yield* devices.agentTarget(opened); |
| 286 | const hostKind = after.hosts.find((host) => host.id === device.hostId)?.kind; |
| 287 | const targetArgs = [ |
| 288 | ...(agent.agentDeviceId === null |
| 289 | ? [] |
| 290 | : agentDeviceTargetArgs({ ...device, id: agent.agentDeviceId })), |
| 291 | ...agent.args, |
| 292 | ]; |
| 293 | const launcher = yield* devices.agentLauncher({ ...opened, targetArgs }); |
| 294 | if (Option.isNone(launcher)) { |
| 295 | return yield* new DeviceToolUnavailableError({ |
| 296 | reason: |
| 297 | "The device was closed while device_open was preparing it. Call device_open again only if you still need it.", |
| 298 | }); |
| 299 | } |
| 300 | const command = launcher.value; |
| 301 | return { |
| 302 | device, |
| 303 | agentDevice: { command, targetArgs, session: agent.session }, |
| 304 | quickStart: agentDeviceQuickStart( |
| 305 | device, |
| 306 | [], |
| 307 | command, |
| 308 | hostKind === "simlock" |
| 309 | ? { |
| 310 | kind: "simlock", |
| 311 | ...(agent.installDirectory ? { installDirectory: agent.installDirectory } : {}), |
| 312 | } |
| 313 | : hostKind === "eas" |
| 314 | ? { kind: "eas" } |
| 315 | : undefined, |
| 316 | ), |
| 317 | }; |
| 318 | }).pipe(Effect.mapError(toolError)), |
| 319 | ), |
| 320 | device_screenshot: McpToolAccess.readsAsCaller((input) => |
| 321 | Effect.gen(function* () { |
| 322 | const scope = yield* requireDeviceAccess; |
| 323 | const devices = yield* DeviceService.DeviceService; |
| 324 | const threadId = scope.thread.threadId; |
| 325 | const hostId = |
| 326 | input.hostId === undefined |
| 327 | ? undefined |
| 328 | : yield* resolveHostId((yield* devices.state).hosts, input.hostId); |
| 329 | const target = |
| 330 | input.deviceId === undefined |
| 331 | ? (yield* devices.sessionsForThread(threadId)).findLast( |
| 332 | (session) => hostId === undefined || session.hostId === hostId, |
| 333 | ) |
| 334 | : Option.getOrUndefined( |
| 335 | yield* devices |
| 336 | .locateSession({ threadId, deviceId: input.deviceId, hostId }) |
| 337 | .pipe(mapLocateErrors), |
| 338 | ); |
| 339 | if (!target) { |
| 340 | return yield* new DeviceToolUnavailableError({ |
| 341 | reason: |
| 342 | input.deviceId === undefined |
| 343 | ? "No device is open in this thread. Call device_open first." |
| 344 | : `Device ${input.deviceId} is not open in this thread. Call device_open first.`, |
| 345 | }); |
| 346 | } |
| 347 | const shot = yield* devices.screenshot(target); |
| 348 | return { |
| 349 | device: shot.device, |
| 350 | screenshot: { |
| 351 | mimeType: "image/png" as const, |
| 352 | data: Buffer.from(shot.png).toString("base64"), |
| 353 | ...pngDimensions(shot.png), |
| 354 | }, |
| 355 | }; |
| 356 | }).pipe(Effect.mapError(toolError)), |
| 357 | ), |
| 358 | device_close: McpToolAccess.actsAsCaller((input) => |
| 359 | Effect.gen(function* () { |
| 360 | const scope = yield* requireDeviceAccess; |
| 361 | const devices = yield* DeviceService.DeviceService; |
| 362 | const deviceId = input.deviceId; |
| 363 | const inputHostId = |
| 364 | input.hostId === undefined |
| 365 | ? undefined |
| 366 | : yield* resolveHostId((yield* devices.state).hosts, input.hostId); |
| 367 | const open = |
| 368 | deviceId === undefined |
| 369 | ? Option.none() |
| 370 | : yield* devices |
| 371 | .locateSession({ threadId: scope.thread.threadId, deviceId, hostId: inputHostId }) |
| 372 | .pipe(mapLocateErrors); |
| 373 | const hostId = Option.isSome(open) ? open.value.hostId : inputHostId; |
| 374 | yield* devices.close({ |
| 375 | threadId: scope.thread.threadId, |
| 376 | ...(hostId === undefined ? {} : { hostId }), |
| 377 | ...(deviceId === undefined ? {} : { deviceId }), |
| 378 | ...(input.shutdown === undefined ? {} : { shutdown: input.shutdown }), |
| 379 | }); |
| 380 | return {}; |
| 381 | }).pipe(Effect.mapError(toolError)), |
| 382 | ), |
| 383 | } satisfies McpToolAccess.Handlers<typeof DeviceToolkit.tools>; |
| 384 | |
| 385 | export function pngDimensions(png: Uint8Array): { width: number; height: number } { |
| 386 | if (png.length < 24) return { width: 0, height: 0 }; |
| 387 | const view = new DataView(png.buffer, png.byteOffset, png.byteLength); |
| 388 | const isPng = |
| 389 | view.getUint32(0) === 0x89504e47 && |
| 390 | view.getUint32(4) === 0x0d0a1a0a && |
| 391 | view.getUint32(12) === 0x49484452; |
| 392 | return isPng |
| 393 | ? { width: view.getUint32(16), height: view.getUint32(20) } |
| 394 | : { width: 0, height: 0 }; |
| 395 | } |
| 396 | |
| 397 | const { device_screenshot, ...standardHandlers } = handlers; |
| 398 | |
| 399 | export const layerStandard = McpToolAccess.toLayer(DeviceStandardToolkit, standardHandlers); |
| 400 | |
| 401 | export const layerScreenshot = McpToolAccess.toLayer(DeviceScreenshotToolkit, { |
| 402 | device_screenshot, |
| 403 | }); |