@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, 04:45 UTC

main
ts 403 lines 17.6 KB
Raw
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 });