The best way to control Claude Code, Codex and more from any computer or phone
| 1 | // @effect-diagnostics nodeBuiltinImport:off globalJsonInEffect:off - drives agent-device and the Hermes inspector; the probe types its own JSON. |
| 2 | /** |
| 3 | * One simulator, driven two ways: T3's `agent-device` CLI for real touches and system actions, |
| 4 | * and the dev-only behavior probe (`apps/mobile/src/features/development/behavior-probe.ts`) |
| 5 | * through Metro's Hermes inspector for exact app state. |
| 6 | */ |
| 7 | import * as NodeChildProcess from "node:child_process"; |
| 8 | import * as NodeOS from "node:os"; |
| 9 | import * as NodePath from "node:path"; |
| 10 | import * as NodeWS from "@effect/platform-node/NodeWS"; |
| 11 | import * as Clock from "effect/Clock"; |
| 12 | import * as Effect from "effect/Effect"; |
| 13 | import * as Schedule from "effect/Schedule"; |
| 14 | import * as Schema from "effect/Schema"; |
| 15 | import { FetchHttpClient, HttpClient, HttpClientResponse } from "effect/http"; |
| 16 | import { Socket } from "effect/socket"; |
| 17 | |
| 18 | import { poolError } from "../mobile-e2e/device.ts"; |
| 19 | |
| 20 | const InspectorTargets = Schema.Array( |
| 21 | Schema.Struct({ |
| 22 | appId: Schema.String, |
| 23 | deviceName: Schema.optional(Schema.String), |
| 24 | webSocketDebuggerUrl: Schema.String, |
| 25 | }), |
| 26 | ); |
| 27 | |
| 28 | export class DeviceError extends Schema.TaggedError<DeviceError>()("DeviceError", { |
| 29 | message: Schema.String, |
| 30 | }) {} |
| 31 | |
| 32 | export const APP_ID = "com.t3tools.t3code.dev"; |
| 33 | export const SCHEME = "t3code-dev"; |
| 34 | |
| 35 | export interface ProbeState { |
| 36 | readonly route: { |
| 37 | readonly name: string | null; |
| 38 | readonly params: Record<string, unknown>; |
| 39 | readonly columns: boolean; |
| 40 | } | null; |
| 41 | readonly feed: FeedSample | null; |
| 42 | readonly composer: { |
| 43 | readonly key: string | null; |
| 44 | readonly draft: string | null; |
| 45 | readonly drafts: Record<string, string>; |
| 46 | readonly editors: ReadonlyArray<{ readonly value: string; readonly expanded: boolean }>; |
| 47 | readonly error: string | null; |
| 48 | readonly keyboard: boolean; |
| 49 | }; |
| 50 | readonly floatingStatus: string | null; |
| 51 | readonly environments: ReadonlyArray<string>; |
| 52 | /** The app's status for every thread it knows, by thread id. */ |
| 53 | readonly threads: Record<string, string>; |
| 54 | readonly homeList: ReadonlyArray<{ |
| 55 | readonly type: string; |
| 56 | readonly threadId?: string; |
| 57 | readonly status?: string; |
| 58 | readonly pinned?: boolean; |
| 59 | readonly count?: number; |
| 60 | readonly expanded?: boolean; |
| 61 | }> | null; |
| 62 | } |
| 63 | |
| 64 | export interface FeedSample { |
| 65 | readonly at?: number; |
| 66 | readonly threadId: string; |
| 67 | readonly ready: boolean; |
| 68 | readonly scroll?: number; |
| 69 | readonly viewport?: number; |
| 70 | readonly content?: number; |
| 71 | readonly fromEnd?: number; |
| 72 | readonly atEnd?: boolean; |
| 73 | readonly following?: boolean | null; |
| 74 | readonly count?: number; |
| 75 | readonly rows?: Record<string, number>; |
| 76 | } |
| 77 | |
| 78 | export interface Recording { |
| 79 | readonly js: ReadonlyArray<number>; |
| 80 | readonly ui: ReadonlyArray<number>; |
| 81 | readonly feed: ReadonlyArray<FeedSample>; |
| 82 | } |
| 83 | |
| 84 | export interface AxNode { |
| 85 | readonly type?: string; |
| 86 | readonly label?: string; |
| 87 | readonly value?: string; |
| 88 | readonly kind?: string; |
| 89 | readonly editable?: boolean; |
| 90 | readonly enabled?: boolean; |
| 91 | readonly rect?: { |
| 92 | readonly x: number; |
| 93 | readonly y: number; |
| 94 | readonly width: number; |
| 95 | readonly height: number; |
| 96 | }; |
| 97 | } |
| 98 | |
| 99 | export interface DeviceOptions { |
| 100 | /** `agent-device` executable and the target args `device_open` returned. */ |
| 101 | readonly agentDevice: string; |
| 102 | readonly targetArgs: ReadonlyArray<string>; |
| 103 | readonly metro: string; |
| 104 | /** Simulator name as Metro's inspector lists it; empty for the only app on this run's Metro. */ |
| 105 | readonly deviceName: string; |
| 106 | } |
| 107 | |
| 108 | export function makeDevice(options: DeviceOptions) { |
| 109 | const run = (args: ReadonlyArray<string>, timeoutMs = 90_000) => |
| 110 | Effect.try({ |
| 111 | try: () => |
| 112 | NodeChildProcess.execFileSync(options.agentDevice, [...args, ...options.targetArgs], { |
| 113 | encoding: "utf8", |
| 114 | timeout: timeoutMs, |
| 115 | stdio: ["ignore", "pipe", "pipe"], |
| 116 | }), |
| 117 | catch: (cause) => { |
| 118 | // The thrown message starts with the full command line; the reason is in its output. |
| 119 | const output = cause as { readonly stdout?: string; readonly stderr?: string }; |
| 120 | const reason = `${output.stderr ?? ""}${output.stdout ?? ""}`.trim() || String(cause); |
| 121 | return new DeviceError({ |
| 122 | message: `agent-device ${args.join(" ")} failed: ${reason.slice(-400)}`, |
| 123 | }); |
| 124 | }, |
| 125 | }).pipe( |
| 126 | // A shared pool's workers drop off the gateway for seconds at a time. |
| 127 | Effect.retry({ |
| 128 | times: 4, |
| 129 | while: (error) => poolError(error.message), |
| 130 | schedule: Schedule.spaced("5 seconds"), |
| 131 | }), |
| 132 | Effect.withSpan("device.agentDevice", { attributes: { command: args[0] } }), |
| 133 | ); |
| 134 | |
| 135 | const evaluate = Effect.fn("device.evaluate")( |
| 136 | function* (expression: string) { |
| 137 | const targets = yield* HttpClient.get(`${options.metro}/json/list`).pipe( |
| 138 | Effect.flatMap(HttpClientResponse.schemaBodyJson(InspectorTargets)), |
| 139 | Effect.provide(FetchHttpClient.layer), |
| 140 | Effect.mapError( |
| 141 | () => new DeviceError({ message: `Metro at ${options.metro} did not answer.` }), |
| 142 | ), |
| 143 | ); |
| 144 | // Pool simulators carry generated names; a run's own Metro then serves only its device. |
| 145 | const target = targets.findLast( |
| 146 | (entry) => |
| 147 | entry.appId === APP_ID && |
| 148 | (!options.deviceName || entry.deviceName === options.deviceName), |
| 149 | ); |
| 150 | if (!target) |
| 151 | return yield* new DeviceError({ |
| 152 | message: `No app on ${options.deviceName} is attached to Metro.`, |
| 153 | }); |
| 154 | // Expo drops inspector sockets whose Origin is not the URL Metro advertises. |
| 155 | const socket = yield* Socket.makeWebSocket(target.webSocketDebuggerUrl, { |
| 156 | headers: { origin: new URL(options.metro).origin }, |
| 157 | openTimeout: "10 seconds", |
| 158 | }); |
| 159 | const writer = yield* socket.writer; |
| 160 | const reader = yield* socket.reader; |
| 161 | yield* writer.write( |
| 162 | JSON.stringify({ |
| 163 | id: 1, |
| 164 | method: "Runtime.evaluate", |
| 165 | params: { expression, returnByValue: true, awaitPromise: true }, |
| 166 | }), |
| 167 | ); |
| 168 | while (true) { |
| 169 | for (const frame of yield* reader.pull) { |
| 170 | const reply = JSON.parse( |
| 171 | typeof frame === "string" ? frame : new TextDecoder().decode(frame), |
| 172 | ) as { |
| 173 | id?: number; |
| 174 | result?: { result?: { value?: unknown }; exceptionDetails?: unknown }; |
| 175 | }; |
| 176 | if (reply.id !== 1) continue; |
| 177 | if (reply.result?.exceptionDetails) |
| 178 | return yield* new DeviceError({ |
| 179 | message: `${expression} threw ${JSON.stringify(reply.result.exceptionDetails).slice(0, 400)}`, |
| 180 | }); |
| 181 | return reply.result?.result?.value; |
| 182 | } |
| 183 | } |
| 184 | }, |
| 185 | Effect.scoped, |
| 186 | Effect.provide(NodeWS.layerWebSocketConstructor), |
| 187 | Effect.timeoutOrElse({ |
| 188 | duration: "20 seconds", |
| 189 | orElse: () => Effect.fail(new DeviceError({ message: "The inspector did not answer." })), |
| 190 | }), |
| 191 | Effect.mapError((error) => |
| 192 | error._tag === "DeviceError" |
| 193 | ? error |
| 194 | : new DeviceError({ message: `Inspector: ${error.message}` }), |
| 195 | ), |
| 196 | ); |
| 197 | |
| 198 | const state = evaluate("__t3Behavior.state()").pipe( |
| 199 | Effect.map((value) => JSON.parse(String(value)) as ProbeState), |
| 200 | ); |
| 201 | |
| 202 | /** Polls the probe until `predicate` holds; fails with the last state after `timeoutMs`. */ |
| 203 | const waitFor = Effect.fn("device.waitFor")(function* ( |
| 204 | description: string, |
| 205 | predicate: (state: ProbeState) => boolean, |
| 206 | timeoutMs = 15_000, |
| 207 | ) { |
| 208 | const deadline = (yield* Clock.currentTimeMillis) + timeoutMs; |
| 209 | let last: ProbeState | null = null; |
| 210 | while ((yield* Clock.currentTimeMillis) < deadline) { |
| 211 | last = yield* state.pipe(Effect.orElseSucceed(() => null)); |
| 212 | if (last && predicate(last)) return last; |
| 213 | yield* Effect.sleep("250 millis"); |
| 214 | } |
| 215 | return yield* new DeviceError({ |
| 216 | message: `Timed out waiting for ${description}. Last route: ${JSON.stringify(last?.route ?? null)}`, |
| 217 | }); |
| 218 | }); |
| 219 | |
| 220 | const nodes = run(["snapshot", "--json"]).pipe( |
| 221 | Effect.map((out) => (JSON.parse(out) as { data: { nodes: ReadonlyArray<AxNode> } }).data.nodes), |
| 222 | ); |
| 223 | |
| 224 | const center = (node: AxNode) => ({ |
| 225 | x: Math.round(node.rect!.x + node.rect!.width / 2), |
| 226 | y: Math.round(node.rect!.y + node.rect!.height / 2), |
| 227 | }); |
| 228 | |
| 229 | const screenSize = run([ |
| 230 | "screenshot", |
| 231 | NodePath.join(NodeOS.tmpdir(), "t3-mobile-behavior-screen.png"), |
| 232 | "--json", |
| 233 | ]).pipe( |
| 234 | Effect.map((out) => { |
| 235 | const { data } = JSON.parse(out) as { data: { logicalWidth: number; logicalHeight: number } }; |
| 236 | return { width: data.logicalWidth, height: data.logicalHeight }; |
| 237 | }), |
| 238 | ); |
| 239 | |
| 240 | return { |
| 241 | options, |
| 242 | run, |
| 243 | evaluate, |
| 244 | state, |
| 245 | waitFor, |
| 246 | nodes, |
| 247 | center, |
| 248 | open: (path: string) => |
| 249 | evaluate(`__t3Behavior.open(${JSON.stringify(`${SCHEME}://${path.replace(/^\//, "")}`)})`), |
| 250 | openUrl: (url: string) => evaluate(`__t3Behavior.open(${JSON.stringify(url)})`), |
| 251 | /** Reloads JS, then opens Home; the app restores the last thread, and split layouts keep one open. */ |
| 252 | reload: Effect.fn("device.reload")(function* (ready: (state: ProbeState) => boolean) { |
| 253 | yield* evaluate("__t3Behavior.reload()").pipe(Effect.ignore); |
| 254 | yield* Effect.sleep("2 seconds"); |
| 255 | yield* waitFor("the thread list after reload", ready, 60_000); |
| 256 | yield* evaluate(`__t3Behavior.open(${JSON.stringify(`${SCHEME}://`)})`); |
| 257 | // Split layouts may keep a thread beside Home, so they get a short wait for the Home route. |
| 258 | const home = (value: ProbeState) => ready(value) && value.route?.name === "Home"; |
| 259 | const state = yield* waitFor("Home", home, 5_000).pipe(Effect.option); |
| 260 | if (state._tag === "Some") return state.value; |
| 261 | return yield* waitFor( |
| 262 | "the split layout", |
| 263 | (value) => ready(value) && value.route?.columns === true, |
| 264 | ); |
| 265 | }), |
| 266 | recordStart: (withFeed: boolean) => evaluate(`__t3Behavior.recordStart(${withFeed})`), |
| 267 | recordStop: evaluate("__t3Behavior.recordStop()").pipe( |
| 268 | Effect.map((value) => JSON.parse(String(value)) as Recording), |
| 269 | ), |
| 270 | press: (selector: string) => run(["press", selector]), |
| 271 | pressAt: (x: number, y: number) => run(["press", String(x), String(y)]), |
| 272 | longPress: (selector: string) => run(["longpress", selector, "800"]), |
| 273 | type: (text: string) => run(["type", text]), |
| 274 | /** Drags from y1 to y2 at x; a downward drag scrolls the content up. */ |
| 275 | swipe: (x: number, y1: number, y2: number) => |
| 276 | run(["swipe", String(x), String(y1), String(x), String(y2)]), |
| 277 | /** |
| 278 | * Answers iOS's "Open in" prompt. XCTest cannot see the iOS 27.1 prompt, so when `alert` fails |
| 279 | * this taps where its Open button sits, just right of and below the screen's center. |
| 280 | */ |
| 281 | acceptOpenPrompt: run(["alert", "accept"], 60_000).pipe( |
| 282 | Effect.catch(() => |
| 283 | screenSize.pipe( |
| 284 | Effect.flatMap(({ width, height }) => |
| 285 | run(["press", String(Math.round(width / 2 + 76)), String(Math.round(height / 2 + 8))]), |
| 286 | ), |
| 287 | ), |
| 288 | ), |
| 289 | ), |
| 290 | home: run(["home"]), |
| 291 | /** The Duo simulator often follows a fold without a hinge reading, so the screen's shape confirms it. */ |
| 292 | fold: (pose: "closed" | "open") => |
| 293 | run(["fold", pose]).pipe( |
| 294 | Effect.catch((error) => |
| 295 | screenSize.pipe( |
| 296 | Effect.filterOrFail( |
| 297 | ({ width, height }) => (pose === "closed") === width < height, |
| 298 | () => error, |
| 299 | ), |
| 300 | ), |
| 301 | ), |
| 302 | ), |
| 303 | back: run(["back"]), |
| 304 | }; |
| 305 | } |
| 306 | |
| 307 | export type Device = ReturnType<typeof makeDevice>; |