import {
type DeviceError,
type DeviceHostId,
type DeviceHostSummary,
type DeviceId,
type DevicePlatform,
type DeviceSummary,
DeviceToolUnavailableError,
LOCAL_DEVICE_HOST_ID,
} from "@t3tools/contracts";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as DeviceService from "../../../device/DeviceService.ts";
import { threadWorkspaceRoot } from "../../../project/threadWorkspaceRoot.ts";
import * as McpInvocationContext from "../../McpInvocationContext.ts";
import * as McpToolAccess from "../../McpToolAccess.ts";
import { DeviceScreenshotToolkit, DeviceStandardToolkit, DeviceToolkit } from "./tools.ts";
function agentDeviceTargetArgs(device: DeviceSummary): ReadonlyArray<string> {
return device.platform === "ios"
? ["--platform", "ios", "--udid", device.id]
: ["--platform", "android", "--serial", device.id];
}
const shellWord = (value: string) =>
/^[a-zA-Z0-9_./:-]+$/.test(value) ? value : "'" + value.replaceAll("'", "'\"'\"'") + "'";
/** `targetArgs` are the flags the command still needs; a bound launcher needs none. */
export function agentDeviceQuickStart(
device: DeviceSummary,
targetArgs = agentDeviceTargetArgs(device),
command = "agent-device",
host?:
| { readonly kind: "eas" }
| { readonly kind: "simlock"; readonly installDirectory?: string },
): string {
const executable = shellWord(command);
const target = targetArgs.map(shellWord).join(" ");
const run = (args: string) => [executable, args, target].filter(Boolean).join(" ");
const platformNotes =
host?.kind === "simlock"
? [
"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.",
host.installDirectory
? `agent-device accepts install for this lease only when run from ${host.installDirectory}.`
: "",
]
.filter(Boolean)
.join(" ")
: host?.kind === "eas"
? "This is an EAS Simulator 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."
: device.platform === "ios"
? "First use builds an XCTest runner and can take a couple of minutes; later commands are fast."
: "The Android snapshot helper installs itself on first use.";
return [
`The user is watching ${device.name} (${device.version}) in the Device panel.`,
target === ""
? `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.`
: `Drive it with ${executable}. Use this exact path; login shells may reset PATH. Always pass ${target}.`,
// Screenshots and input need the session agent-device's open starts, and an iOS snapshot also
// needs its app. device_open does not run open itself: on iOS that can start a minutes-long
// XCTest runner build.
"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.",
` ${run("open <bundle-or-package-id> --relaunch")} # restarts the app; Expo dev clients connect to their Metro, --metro-port <port> picks it`,
` ${run("open <bundle-or-package-id> <deep-link-url>")}`,
` ${run("snapshot -i")} # accessibility tree with @eN refs`,
` ${run("press @e3 --settle")}`,
` ${run('fill @e5 "text" --settle')}`,
` ${run("alert accept")}`,
` ${run("settings appearance dark")} # also text-size, permission grant <name>`,
` ${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`,
` ${run("record start --scope device /tmp/run.mp4")} # then record stop`,
` ${run("install <app> <path-to-.app-or-.apk>")}`,
`Prefer snapshot refs over coordinates. Run ${executable} help <command> for flags and ${executable} help workflow for guides.`,
"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.",
"Each device_open returns its own command; opening another device does not retarget this one.",
...(target === ""
? [
"The command is removed when the device closes or T3 Code restarts. If it is missing, call device_open again.",
]
: []),
platformNotes,
].join("\n");
}
const requireDeviceAccess = McpInvocationContext.requireThreadMcpCapability("device").pipe(
Effect.mapError(
() =>
new DeviceToolUnavailableError({
reason:
"Agent device access is turned off for this environment. Ask the user to turn on Agent device access in Settings > Integrations > Devices; it applies when the agent session next starts, such as in a new thread.",
}),
),
);
export const resolveHostId = Effect.fn("handlers.resolveHostId")(function* (
hosts: ReadonlyArray<DeviceHostSummary>,
hostId: string | undefined,
): Effect.fn.Return<DeviceHostId | undefined, DeviceToolUnavailableError> {
if (!hostId) return undefined;
const exact = hosts.find((host) => host.id === hostId);
if (exact) return exact.id;
const labelMatches = hosts.filter((host) => host.label.toLowerCase() === hostId.toLowerCase());
if (labelMatches.length === 1) return labelMatches[0]!.id;
const candidates = labelMatches.length > 1 ? labelMatches : hosts;
const listed = [
...candidates.slice(0, 10).map((host) => `${host.label.slice(0, 64)} (${host.id})`),
...(candidates.length > 10 ? [`${candidates.length - 10} more`] : []),
].join(", ");
const selector = hostId.slice(0, 128);
return yield* new DeviceToolUnavailableError({
reason:
labelMatches.length > 1
? `Several device hosts are named ${selector}; pass one id: ${listed}.`
: `No device host ${selector}. Known hosts: ${listed || "none"}.`,
});
});
const hostName = (host: { readonly id: DeviceHostId; readonly label?: string | undefined }) =>
host.label === undefined ? `hostId ${host.id}` : `'${host.label}' (hostId ${host.id})`;
const mapLocateErrors = <A, R>(
effect: Effect.Effect<
A,
DeviceService.DeviceHostAmbiguousError | DeviceService.DeviceOnOtherHostError,
R
>,
) =>
effect.pipe(
Effect.catchTags({
DeviceHostAmbiguousError: (error) =>
Effect.fail(
new DeviceToolUnavailableError({
reason: `Device ${error.deviceId} is on more than one host: ${error.hosts.map(hostName).join(", ")}. Pass hostId.`,
}),
),
DeviceOnOtherHostError: (error) =>
Effect.fail(
new DeviceToolUnavailableError({
reason: `Device ${error.deviceId} is not on ${hostName(error.host)}. It is on ${error.hosts.map(hostName).join(", ")}; pass that hostId.`,
}),
),
}),
);
const pickDevice = Effect.fn("handlers.pickDevice")(function* (
state: {
readonly hosts: ReadonlyArray<DeviceHostSummary>;
readonly devices: ReadonlyArray<DeviceSummary>;
},
input: {
readonly deviceId?: DeviceId | undefined;
readonly platform?: DevicePlatform | undefined;
readonly hostId?: DeviceHostId | undefined;
},
): Effect.fn.Return<DeviceSummary, DeviceToolUnavailableError, DeviceService.DeviceService> {
if (input.deviceId !== undefined) {
const { deviceId, hostId } = input;
const devices = yield* DeviceService.DeviceService;
const located = yield* devices.locateDevice({ deviceId, hostId }).pipe(mapLocateErrors);
if (Option.isSome(located)) return located.value;
return yield* new DeviceToolUnavailableError({
reason: `No device ${deviceId} on ${hostId === undefined ? "any host" : hostName(state.hosts.find((host) => host.id === hostId) ?? { id: hostId })}. Call device_list for current ids.`,
});
}
const hostId = input.hostId ?? LOCAL_DEVICE_HOST_ID;
const candidates = state.devices.filter(
(device) =>
device.hostId === hostId &&
(input.platform === undefined || device.platform === input.platform),
);
if (candidates.length === 0) {
return yield* new DeviceToolUnavailableError({
reason:
input.platform === undefined
? "No simulators or emulators were found. Call device_list to see why."
: `No ${input.platform} devices were found on host ${hostId}. Call device_list to see why.`,
});
}
const platforms = new Set(candidates.map((device) => device.platform));
if (input.platform === undefined && platforms.size > 1) {
return yield* new DeviceToolUnavailableError({
reason: "Both iOS and Android devices are available; pass platform or deviceId.",
});
}
return candidates.find((device) => device.booted) ?? candidates[0]!;
});
const toolError = (error: DeviceError | DeviceToolUnavailableError) => error;
const handlers = {
device_list: McpToolAccess.readsAsCaller((input) =>
Effect.gen(function* () {
const scope = yield* requireDeviceAccess;
const devices = yield* DeviceService.DeviceService;
const state = yield* devices.list;
if (state.hostStatus === "disabled") {
return yield* new DeviceToolUnavailableError({
reason:
"Device support is off. Ask the user to enable it in the Device panel before installing or starting device tools.",
});
}
const hostId = yield* resolveHostId(state.hosts, input?.hostId);
const open = state.sessions
.filter((session) => session.threadId === scope.thread.threadId)
.map((session) => ({ hostId: session.hostId, deviceId: session.deviceId }));
return {
hostStatuses: Object.fromEntries(
Object.entries(state.hostStatuses).filter(([id]) => !hostId || id === hostId),
),
hosts: hostId ? state.hosts.filter((host) => host.id === hostId) : state.hosts,
devices: hostId
? state.devices.filter((device) => device.hostId === hostId)
: state.devices,
open,
};
}).pipe(Effect.mapError(toolError)),
),
device_open: McpToolAccess.actsAsCaller((input) =>
Effect.gen(function* () {
const scope = yield* requireDeviceAccess;
const devices = yield* DeviceService.DeviceService;
const state = yield* devices.list;
if (state.hostStatus === "disabled") {
return yield* new DeviceToolUnavailableError({
reason:
"Device support is off. Ask the user to enable it in the Device panel before installing or starting device tools.",
});
}
const hostId = yield* resolveHostId(state.hosts, input.hostId);
const target = yield* pickDevice(state, { ...input, hostId });
// Resolve consent and agent connectivity before booting or registering a session.
if (!(yield* devices.agentReadinessIfSupported(target.hostId))) {
return yield* new DeviceToolUnavailableError({
reason:
"Agent device access requires enabled device support, agent access, and an available simulator platform on this host.",
});
}
const session = yield* devices.open(
{
threadId: scope.thread.threadId,
hostId: target.hostId,
deviceId: target.id,
platform: target.platform,
},
{ workspaceRoot: yield* threadWorkspaceRoot(scope.thread.threadId) },
);
const after = yield* devices.state;
const device =
after.devices.find(
(candidate) => candidate.hostId === session.hostId && candidate.id === session.deviceId,
) ?? target;
// Target the opened device: an EAS device and its agent-device daemon
// exist only once its session runs, and Android ids change on boot.
const opened = {
threadId: scope.thread.threadId,
hostId: session.hostId,
deviceId: session.deviceId,
};
const agent = yield* devices.agentTarget(opened);
const hostKind = after.hosts.find((host) => host.id === device.hostId)?.kind;
const targetArgs = [
...(agent.agentDeviceId === null
? []
: agentDeviceTargetArgs({ ...device, id: agent.agentDeviceId })),
...agent.args,
];
const launcher = yield* devices.agentLauncher({ ...opened, targetArgs });
if (Option.isNone(launcher)) {
return yield* new DeviceToolUnavailableError({
reason:
"The device was closed while device_open was preparing it. Call device_open again only if you still need it.",
});
}
const command = launcher.value;
return {
device,
agentDevice: { command, targetArgs, session: agent.session },
quickStart: agentDeviceQuickStart(
device,
[],
command,
hostKind === "simlock"
? {
kind: "simlock",
...(agent.installDirectory ? { installDirectory: agent.installDirectory } : {}),
}
: hostKind === "eas"
? { kind: "eas" }
: undefined,
),
};
}).pipe(Effect.mapError(toolError)),
),
device_screenshot: McpToolAccess.readsAsCaller((input) =>
Effect.gen(function* () {
const scope = yield* requireDeviceAccess;
const devices = yield* DeviceService.DeviceService;
const threadId = scope.thread.threadId;
const hostId =
input.hostId === undefined
? undefined
: yield* resolveHostId((yield* devices.state).hosts, input.hostId);
const target =
input.deviceId === undefined
? (yield* devices.sessionsForThread(threadId)).findLast(
(session) => hostId === undefined || session.hostId === hostId,
)
: Option.getOrUndefined(
yield* devices
.locateSession({ threadId, deviceId: input.deviceId, hostId })
.pipe(mapLocateErrors),
);
if (!target) {
return yield* new DeviceToolUnavailableError({
reason:
input.deviceId === undefined
? "No device is open in this thread. Call device_open first."
: `Device ${input.deviceId} is not open in this thread. Call device_open first.`,
});
}
const shot = yield* devices.screenshot(target);
return {
device: shot.device,
screenshot: {
mimeType: "image/png" as const,
data: Buffer.from(shot.png).toString("base64"),
...pngDimensions(shot.png),
},
};
}).pipe(Effect.mapError(toolError)),
),
device_close: McpToolAccess.actsAsCaller((input) =>
Effect.gen(function* () {
const scope = yield* requireDeviceAccess;
const devices = yield* DeviceService.DeviceService;
const deviceId = input.deviceId;
const inputHostId =
input.hostId === undefined
? undefined
: yield* resolveHostId((yield* devices.state).hosts, input.hostId);
const open =
deviceId === undefined
? Option.none()
: yield* devices
.locateSession({ threadId: scope.thread.threadId, deviceId, hostId: inputHostId })
.pipe(mapLocateErrors);
const hostId = Option.isSome(open) ? open.value.hostId : inputHostId;
yield* devices.close({
threadId: scope.thread.threadId,
...(hostId === undefined ? {} : { hostId }),
...(deviceId === undefined ? {} : { deviceId }),
...(input.shutdown === undefined ? {} : { shutdown: input.shutdown }),
});
return {};
}).pipe(Effect.mapError(toolError)),
),
} satisfies McpToolAccess.Handlers<typeof DeviceToolkit.tools>;
export function pngDimensions(png: Uint8Array): { width: number; height: number } {
if (png.length < 24) return { width: 0, height: 0 };
const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
const isPng =
view.getUint32(0) === 0x89504e47 &&
view.getUint32(4) === 0x0d0a1a0a &&
view.getUint32(12) === 0x49484452;
return isPng
? { width: view.getUint32(16), height: view.getUint32(20) }
: { width: 0, height: 0 };
}
const { device_screenshot, ...standardHandlers } = handlers;
export const layerStandard = McpToolAccess.toLayer(DeviceStandardToolkit, standardHandlers);
export const layerScreenshot = McpToolAccess.toLayer(DeviceScreenshotToolkit, {
device_screenshot,
});