simulator-use 0.9.1 → 0.10.1

package/dist/look/read.js

@@ -1,6 +1,7 @@
 import { setTimeout as sleep } from "node:timers/promises";
 import { AccessibilityStarting, describeUi } from "../engine/axe.js";
 import { engineCall } from "../engine/native.js";
+import { setting } from "../settings.js";
 import { render, snapshot } from "./snapshot.js";
 /** Right after a launch the app's accessibility tree is empty for a moment (seen on Xcode 27). */
 const NOT_READY_RETRIES = 4;
@@ -48,13 +49,18 @@ export async function settle(udid, fromApp) {
     // With the engine: the screen buffer says when the screen stopped changing (up to 0.8 s for the first change
     // after an input, then 150 ms without one), and one read follows; a newly opened app's shell is read again
     // until its contents arrive (up to 2.5 s).
+    const started = Date.now();
     const answer = await engineCall(udid, { op: "settle", first_change_ms: 800, quiet_ms: 150, timeout_ms: SETTLE_TIMEOUT_MS }, SETTLE_TIMEOUT_MS + 5_000);
     if (answer?.ok) {
+        const quiet = Date.now();
         let snap = (await readScreen(udid, false)).snap;
-        for (const deadline = Date.now() + 2_500; opening(snap, fromApp) && Date.now() < deadline;) {
+        let reads = 1;
+        for (const deadline = Date.now() + 2_500; opening(snap, fromApp) && Date.now() < deadline; reads++) {
             await sleep(300);
             snap = (await readScreen(udid, false)).snap;
         }
+        if (setting("DEBUG"))
+            process.stderr.write(`simulator-use:   settle ${quiet - started} ms${answer.settled === false ? " (still changing)" : ""}, ${reads} read(s) ${Date.now() - quiet} ms\n`);
         return { snap, settled: answer.settled !== false };
     }
     const deadline = Date.now() + SETTLE_TIMEOUT_MS;

package/dist/mcp.js

@@ -5,7 +5,9 @@
  */
 import { createInterface } from "node:readline";
 import { cancelAllJobs } from "./engine/jobs.js";
+import { hosted, hostedAnswer, noteCall } from "./hosted.js";
 import { callTool, INSTRUCTIONS, toContent, TOOLS, VERSION } from "./registry.js";
+import { setting } from "./settings.js";
 const STATELESS = "2026-07-28";
 const HANDSHAKE_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
 export const SUPPORTED_VERSIONS = [STATELESS, ...HANDSHAKE_VERSIONS];
@@ -28,9 +30,18 @@ async function result(method, params, stateless) {
         case "tools/call": {
             const name = typeof params.name === "string" ? params.name : "";
             const args = params.arguments && typeof params.arguments === "object" ? params.arguments : {};
-            return toContent(await callTool(name, args));
+            const started = Date.now();
+            const out = toContent(await callTool(name, args));
+            // On NoMac Simulator's host the customer never reads a path of the host, and the replay lists the call (src/hosted.ts).
+            if (!setting("HOSTED"))
+                return out;
+            noteCall(name, args, started, out);
+            return hostedAnswer(out);
         }
         default:
+            // NoMac Simulator's host asks a hosted server for more than tool calls (src/hosted.ts).
+            if (method.startsWith("simulator-use/") && setting("HOSTED"))
+                return hosted(method, params);
             throw Object.assign(new Error(`Method not found: ${method}`), { code: -32601 });
     }
 }

package/dist/registry.js

@@ -1,8 +1,12 @@
 import { createRequire } from "node:module";
+import { cloudState } from "./cloud/account.js";
+import { forward } from "./cloud/forward.js";
 import { ToolError } from "./errors.js";
+import { setting } from "./settings.js";
 import { appControl } from "./tools/app-control.js";
 import { appLogs } from "./tools/app-logs.js";
 import { appRun } from "./tools/app-run.js";
+import { cloud } from "./tools/cloud.js";
 import { deviceUse } from "./tools/device-use.js";
 import { devices } from "./tools/devices.js";
 import { jobCancel, jobStatus } from "./tools/jobs.js";
@@ -12,7 +16,7 @@ import { uiAct } from "./tools/ui-act.js";
 import { uiLook } from "./tools/ui-look.js";
 export const VERSION = createRequire(import.meta.url)("../package.json").version;
 /** Every tool, in the order clients list them. The MCP server and the CLI are both built from this. */
-export const TOOLS = [devices, deviceUse, appRun, uiLook, uiAct, appControl, appLogs, testsRun, jobStatus, jobCancel, screenRecord];
+export const TOOLS = [devices, deviceUse, appRun, uiLook, uiAct, appControl, appLogs, testsRun, jobStatus, jobCancel, screenRecord, cloud];
 /** How the tools fit together, sent once to MCP clients. */
 export const INSTRUCTIONS = [
     "simulator-use drives iOS Simulators on this Mac.",
@@ -63,6 +67,9 @@ export async function callTool(name, args = {}, context = { waitForJobs: false }
     if (problem)
         return { text: problem, isError: true };
     try {
+        // With cloud on, every other tool runs on the NoMac phone (src/cloud/forward.ts).
+        if (tool !== cloud && !setting("HOSTED") && (await cloudState()).on)
+            return await forward(tool.name, args, context);
         return await tool.run(args, context);
     }
     catch (error) {

package/dist/tools/app-control.js

@@ -2,12 +2,16 @@ import { existsSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import { appInfo, BUNDLE_ID, bundleIdOf, install, pushPayload, simctlAction, stopLogStream } from "../engine/apps.js";
 import { listDevices, pickDevice } from "../engine/simctl.js";
-import { currentApp, heldDevice, setCurrentApp } from "../engine/state.js";
+import { currentApp, heldDevice, setCurrentApp, setDeviceTimeZone } from "../engine/state.js";
 import { ToolError } from "../errors.js";
 import { readScreen } from "../look/read.js";
 import { render } from "../look/snapshot.js";
-import { launchAndLook } from "./launch-app.js";
-const ACTIONS = ["launch", "install", "terminate", "uninstall", "open_url", "grant", "revoke", "reset_permissions", "location", "push"];
+import { grantAll, openInPrompt, setPermissionMode } from "../engine/prompts.js";
+import { launchAndLook, tapPrompt } from "./launch-app.js";
+const ACTIONS = ["launch", "install", "terminate", "uninstall", "open_url", "grant", "revoke", "reset_permissions", "location", "push", "appearance", "locale", "timezone", "text_size", "status_bar"];
+/** simctl ui content_size's sizes. */
+const TEXT_SIZES = ["extra-small", "small", "medium", "large", "extra-large", "extra-extra-large", "extra-extra-extra-large",
+    "accessibility-medium", "accessibility-large", "accessibility-extra-large", "accessibility-extra-extra-large", "accessibility-extra-extra-extra-large"];
 /** What simctl privacy takes (its help, plus camera, which it also accepts). */
 const PERMISSIONS = ["all", "calendar", "camera", "contacts", "contacts-limited", "location", "location-always", "media-library", "microphone", "motion", "photos", "photos-add", "reminders", "siri"];
 /** What `value` holds for each action that needs one. */
@@ -17,7 +21,33 @@ const VALUE = {
     revoke: "a permission, as for grant",
     location: '"latitude,longitude", or "clear"',
     push: 'the notification text, or a JSON payload with "aps"',
+    appearance: '"light" or "dark"',
+    locale: 'a language and region, like "fr_FR", "pt-BR" or "zh-Hans_CN"',
+    timezone: 'an IANA time zone, like "Europe/Paris", or "clear"',
+    text_size: `one of ${TEXT_SIZES.join(", ")}`,
+    status_bar: '"clean" (9:41, full signal and battery, for screenshots) or "clear"',
 };
+/** A locale as iOS keeps it: the language for AppleLanguages ("pt-BR") and the locale for AppleLocale ("pt_BR"). */
+export function localeParts(value) {
+    const m = /^\s*([a-z]{2,3})(?:[-_]([A-Z][a-z]{3}))?(?:[-_]([A-Z]{2}|\d{3}))?\s*$/.exec(value);
+    if (!m)
+        throw new ToolError(`"${value}" is not a language and region.`, 'For example "fr_FR", "pt-BR", "zh-Hans_CN" or "en".');
+    const [, lang, script, region] = m;
+    return { language: [lang, script, region].filter(Boolean).join("-"), locale: [[lang, script].filter(Boolean).join("-"), region].filter(Boolean).join("_") };
+}
+/** An IANA time zone this machine knows (Intl refuses any other). */
+export function timeZoneName(value) {
+    const zone = value.trim();
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: zone });
+        if (/^[A-Za-z_]+(?:\/[A-Za-z0-9_+-]+)*$/.test(zone))
+            return zone;
+    }
+    catch {
+        // Not a time zone.
+    }
+    throw new ToolError(`"${value}" is not a time zone.`, 'Use an IANA name, like "Europe/Paris" or "America/New_York".');
+}
 /** A push from plain text, or the agent's own JSON payload, checked the way simctl will. */
 export function pushJson(value) {
     const trimmed = value.trim();
@@ -39,13 +69,13 @@ export function pushJson(value) {
 export const appControl = {
     name: "app_control",
     title: "Control an app",
-    description: "Launch, install, stop or remove an app on the Simulator; open a URL or deep link; grant, revoke or reset a permission; set the location; send a push. launch answers with the app's first screen; later calls default to the app launched last.",
+    description: "Launch, install, stop or remove an app on the Simulator; open a URL or deep link; grant, revoke or reset a permission; set the location; send a push; set the phone's appearance, locale, time zone, text size or a clean status bar. launch answers with the app's first screen; later calls default to the app launched last.",
     inputSchema: {
         type: "object",
         properties: {
             action: { type: "string", enum: ACTIONS, description: "What to do" },
             app: { type: "string", description: "Bundle id, or for install the path to a Simulator .app" },
-            value: { type: "string", description: "URL, permission, latitude,longitude, or push text/JSON, per action" },
+            value: { type: "string", description: "URL, permission, lat,long, push text/JSON, light/dark, locale (fr_FR), time zone (Europe/Paris), text size or clean/clear, per action" },
             device: { type: "string", description: "Name or UDID; default: the one in use" },
         },
         required: ["action"],
@@ -72,13 +102,16 @@ export const appControl = {
             await install(device.udid, path);
             const info = await appInfo(device.udid, bundleId);
             await setCurrentApp(device.udid, { bundleId, executable: info?.executable });
-            return { text: `Installed ${info?.name ?? bundleId} (${bundleId}) on ${label}. Next: app_control {action: "launch"}.` };
+            const refused = await grantAll(device.udid, bundleId);
+            const granted = refused ? ` Its permissions could not be granted (${refused}).` : " Its permissions are granted, so no prompt stops it (reset_permissions brings iOS's prompts back).";
+            return { text: `Installed ${info?.name ?? bundleId} (${bundleId}) on ${label}.${granted} Next: app_control {action: "launch"}.` };
         }
         // Every other action works on an installed app: the one named, or the one launched last.
         const bundleId = app ?? (await currentApp(device.udid))?.bundleId;
         if (bundleId && !BUNDLE_ID.test(bundleId))
             throw new ToolError(`"${bundleId}" is not a bundle id.`, "A bundle id looks like com.example.app; install takes the path to a .app.");
-        const needsApp = !["open_url", "location", "reset_permissions"].includes(action);
+        // The phone's own settings need no app.
+        const needsApp = !["open_url", "location", "reset_permissions", "appearance", "locale", "timezone", "text_size", "status_bar"].includes(action);
         if (needsApp && !bundleId)
             throw new ToolError(`${action} needs app: the bundle id.`, "Pass app, or launch the app first.");
         switch (action) {
@@ -94,17 +127,28 @@ export const appControl = {
                 await stopLogStream(device.udid, bundleId);
                 await simctlAction(["uninstall", device.udid, bundleId], `remove ${bundleId}`);
                 return { text: `Removed ${bundleId} and its data from ${label}.` };
-            case "open_url":
+            case "open_url": {
                 await simctlAction(["openurl", device.udid, value], `open ${value}`);
-                return { text: `Opened ${value}.\n${render((await readScreen(device.udid)).snap, { device: label })}` };
+                let snap = (await readScreen(device.udid)).snap;
+                // A link that opens another app makes iOS ask "Open in “App”?": the agent asked for exactly that.
+                const asked = openInPrompt(snap);
+                if (asked)
+                    snap = await tapPrompt(device, "Open");
+                return { text: `Opened ${value}.${asked ? ` iOS asked "${asked}": answered Open.` : ""}\n${render(snap, { device: label })}` };
+            }
             case "grant":
             case "revoke":
                 if (!PERMISSIONS.includes(value))
                     throw new ToolError(`Unknown permission "${value}".`, `Permissions: ${PERMISSIONS.join(", ")}.`);
                 await simctlAction(["privacy", device.udid, action, value, bundleId], `${action} ${value}`);
+                // A permission taken away is for testing iOS's prompt: launches stop answering prompts for this app.
+                if (action === "revoke")
+                    await setPermissionMode(device.udid, bundleId, "ask");
                 return { text: `${action === "grant" ? "Granted" : "Revoked"} ${value} for ${bundleId}. The app may have been stopped: iOS does that when a permission changes.` };
             case "reset_permissions":
                 await simctlAction(["privacy", device.udid, "reset", value ?? "all", ...(bundleId ? [bundleId] : [])], "reset permissions");
+                if (bundleId)
+                    await setPermissionMode(device.udid, bundleId, "ask");
                 return { text: `Reset ${value ?? "all"} permissions${bundleId ? ` for ${bundleId}` : ""}: the app asks again on next use.` };
             case "location": {
                 if (value.trim() === "clear") {
@@ -120,6 +164,47 @@ export const appControl = {
             case "push":
                 await pushPayload(device.udid, bundleId, pushJson(value));
                 return { text: `Sent a push to ${bundleId}.` };
+            case "appearance": {
+                const mode = value.trim().toLowerCase();
+                if (mode !== "light" && mode !== "dark")
+                    throw new ToolError(`Appearance is "light" or "dark", not "${value}".`);
+                await simctlAction(["ui", device.udid, "appearance", mode], "set the appearance");
+                return { text: `${label} is in ${mode} mode.` };
+            }
+            case "locale": {
+                const { language, locale } = localeParts(value);
+                await simctlAction(["spawn", device.udid, "defaults", "write", "-g", "AppleLanguages", "-array", language], "set the language");
+                await simctlAction(["spawn", device.udid, "defaults", "write", "-g", "AppleLocale", "-string", locale], "set the region");
+                return { text: `${label}'s language and region are ${language} (${locale}). Apps read them when they launch: relaunch the app (app_control launch).` };
+            }
+            case "timezone": {
+                if (value.trim() === "clear") {
+                    await setDeviceTimeZone(device.udid, undefined);
+                    return { text: `Apps launched from now on run in this Mac's time zone again; relaunch the app (app_control launch).` };
+                }
+                const zone = timeZoneName(value);
+                await setDeviceTimeZone(device.udid, zone);
+                return { text: `Apps simulator-use launches from now on run in ${zone}: relaunch the app (app_control launch). The status bar's clock keeps this Mac's time.` };
+            }
+            case "text_size": {
+                const size = value.trim().toLowerCase();
+                if (!TEXT_SIZES.includes(size))
+                    throw new ToolError(`"${value}" is not a text size.`, `Use one of: ${TEXT_SIZES.join(", ")}.`);
+                await simctlAction(["ui", device.udid, "content_size", size], "set the text size");
+                return { text: `${label}'s text size is ${size}.` };
+            }
+            case "status_bar": {
+                const mode = value.trim().toLowerCase();
+                if (mode === "clear") {
+                    await simctlAction(["status_bar", device.udid, "clear"], "clear the status bar");
+                    return { text: "The status bar shows the real time, signal and battery again." };
+                }
+                if (mode !== "clean")
+                    throw new ToolError(`status_bar is "clean" or "clear", not "${value}".`);
+                await simctlAction(["status_bar", device.udid, "override", "--time", "9:41", "--dataNetwork", "wifi", "--wifiMode", "active", "--wifiBars", "3",
+                    "--cellularMode", "active", "--cellularBars", "4", "--batteryState", "charged", "--batteryLevel", "100"], "set the status bar");
+                return { text: "The status bar shows 9:41, full signal and a full battery, as App Store screenshots do." };
+            }
             default:
                 throw new ToolError(`Unknown action "${action}". Actions: ${ACTIONS.join(", ")}.`);
         }

package/dist/tools/app-run.js

@@ -1,8 +1,10 @@
 import { bundleIdOf, install } from "../engine/apps.js";
 import { answer, claimProject, currentJob, startJob } from "../engine/jobs.js";
 import { bootDevice, findDevice, listDevices, pickDevice } from "../engine/simctl.js";
-import { heldDevice, holdDevice } from "../engine/state.js";
-import { build, builtApp, formatIssue, knownFix, projectFor, remember } from "../engine/xcode.js";
+import { heldDevice, holdDevice, setDeviceEnv } from "../engine/state.js";
+import { build, builtApp, formatIssue, knownFix, noDestination, projectFor, remember } from "../engine/xcode.js";
+import { pickXcode } from "../engine/xcodes.js";
+import { grantAll, setPermissionMode } from "../engine/prompts.js";
 import { ToolError } from "../errors.js";
 import { launchAndLook } from "./launch-app.js";
 import { setting } from "../settings.js";
@@ -26,18 +28,41 @@ export async function runDevice(wanted) {
     }
     return target ?? pickDevice(devices, undefined, heldDevice());
 }
+/**
+ * app_run's env: "API_URL=http://127.0.0.1:20199 MODE=test" as the variables the app reads from its environment, as
+ * Xcode's scheme gives them; "" clears them. Undefined: the device keeps what it had.
+ */
+export function launchEnv(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new ToolError("env must be text: KEY=VALUE pairs, space-separated.");
+    const env = {};
+    for (const pair of value.split(/\s+/).filter(Boolean)) {
+        const m = /^([A-Za-z_][A-Za-z0-9_]{0,63})=(\S{0,2048})$/.exec(pair);
+        if (!m)
+            throw new ToolError(`env: "${pair.slice(0, 80)}" is not KEY=VALUE.`, 'Pass env like "API_URL=http://127.0.0.1:20199 MODE=test" (values without spaces).');
+        env[m[1]] = m[2];
+    }
+    if (Object.keys(env).length > 20)
+        throw new ToolError("env takes up to 20 variables.");
+    return env;
+}
 export const appRun = {
     name: "app_run",
     title: "Build and run the app",
-    description: "Build the Xcode project in a folder for the Simulator, install it, launch it, and answer with its first screen. Errors come back as file:line. A build past 40 s answers with a job for job_status. Later calls need no arguments: they use the same project.",
+    description: "Build the Xcode project in a folder for the Simulator, install and launch it, and answer with its first screen. Errors as file:line. A build past 40 s answers with a job for job_status. Later calls reuse the project.",
     inputSchema: {
         type: "object",
         properties: {
-            path: { type: "string", description: "Project folder, .xcodeproj or .xcworkspace; default: the current folder" },
-            scheme: { type: "string", description: "Default: the only scheme, or the one named like the project" },
+            path: { type: "string", description: "Project folder, .xcodeproj or .xcworkspace; default: here" },
+            scheme: { type: "string", description: "Default: the only scheme, or one named like the project" },
             configuration: { type: "string", enum: ["Debug", "Release"], description: "Default: Debug" },
             clean: { type: "boolean", description: "Build from scratch" },
             device: { type: "string", description: "Name or UDID; default: the one in use" },
+            permissions: { type: "string", enum: ["grant", "ask"], description: "grant (default) answers prompts; ask: iOS's prompts stay" },
+            xcode: { type: "string", description: "27.1, beta or default (kept)" },
+            env: { type: "string", description: "App env: \"K=V K2=V2\" (kept)" },
         },
         additionalProperties: false,
     },
@@ -45,10 +70,14 @@ export const appRun = {
     command: "run",
     positional: ["path"],
     async run(args, context) {
+        const env = launchEnv(args.env);
         // Finding the project (xcodebuild -list) and booting count toward the 40 s answer too: all of it is the job.
         const job = startJob("Build and run", async (progress) => {
             progress.step("finding the project");
-            const { project, scheme, dir, note } = await projectFor(args.path, args.scheme);
+            const { project, scheme, dir, note, xcode: kept } = await projectFor(args.path, args.scheme);
+            const asked = args.xcode ?? kept;
+            const xcode = await pickXcode(asked);
+            const other = xcode && !xcode.default ? xcode : undefined;
             job.title = `Build and run ${scheme}`;
             const busy = await claimProject(project.path, currentJob(job.id));
             if (typeof busy === "number")
@@ -60,13 +89,23 @@ export const appRun = {
             const device = await runDevice(args.device);
             holdDevice(device.udid);
             const label = `${device.name} (${device.runtime})`;
-            progress.step(`building ${scheme} for ${label}`);
-            const result = await build(project, scheme, device.udid, {
+            const withXcode = other ? ` with Xcode ${other.version}${other.beta ? " beta" : ""}` : "";
+            progress.step(`building ${scheme} for ${label}${withXcode}`);
+            const options = {
                 configuration,
                 clean: Boolean(args.clean),
+                xcode: other,
                 onLine: (line) => line.trim() && progress.line(line.length > 200 ? `${line.slice(0, 199)}…` : line),
                 onCancel: (cancel) => progress.setCancel(cancel),
-            });
+            };
+            let result = await build(project, scheme, device.udid, options);
+            // An Xcode older than the phone's iOS cannot name it: it builds for any Simulator, and the app installs all the same.
+            let anySimulator = false;
+            if (!result.ok && other && noDestination(result)) {
+                progress.step(`Xcode ${other.version} does not know ${device.runtime}: building for any Simulator`);
+                result = await build(project, scheme, device.udid, { ...options, destination: "generic/platform=iOS Simulator" });
+                anySimulator = true;
+            }
             // Past the build there is nothing to stop: install and launch take seconds.
             progress.setCancel(undefined);
             progress.setLog(result.log);
@@ -82,16 +121,23 @@ export const appRun = {
                 return { text: `${note}Build of ${scheme} failed after ${seconds} s ${found}${fix ? `\nNext: ${fix}` : ""}${quoted}`, isError: true };
             }
             progress.step("installing");
-            const app = builtApp(project, scheme, configuration);
+            const app = builtApp(project, scheme, configuration, other);
             if (!app)
                 return { text: `Built ${scheme} in ${seconds} s, but found no .app for the Simulator. Full log: ${result.log}`, isError: true };
             const bundleId = await bundleIdOf(app);
             await install(device.udid, app);
-            await remember(dir, { project: project.path, scheme, bundleId });
+            const keep = asked && xcode && !xcode.default ? asked : undefined;
+            await remember(dir, { project: project.path, scheme, bundleId, ...(keep ? { xcode: keep } : {}) });
+            // Granted by default, so no prompt stops the agent; "ask" leaves iOS's prompts for a test of them.
+            const refused = args.permissions === "ask" ? (await setPermissionMode(device.udid, bundleId, "ask"), undefined) : await grantAll(device.udid, bundleId);
             progress.step("launching");
+            if (env)
+                await setDeviceEnv(device.udid, env);
             const look = await launchAndLook(device, bundleId);
             const made = project.generated ? ` (generated ${project.name}.xcodeproj with XcodeGen first)` : "";
-            return { text: `${note}Built ${scheme} in ${seconds} s${result.warnings ? ` with ${result.warnings} warnings` : ""}${made}, installed ${bundleId}.\n${look}` };
+            const grant = refused ? `\nIts permissions could not be granted (${refused}).` : "";
+            const built = `${withXcode}${anySimulator ? ` (for any Simulator: it does not know ${device.runtime})` : ""}`;
+            return { text: `${note}Built ${scheme}${built} in ${seconds} s${result.warnings ? ` with ${result.warnings} warnings` : ""}${made}, installed ${bundleId}.${grant}\n${look}` };
         });
         return answer(job, context.waitForJobs);
     },

package/dist/tools/cloud.js

@@ -0,0 +1,247 @@
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { account, cloudState, setCloudState, signIn } from "../cloud/account.js";
+import { CloudError } from "../cloud/api.js";
+import { forward } from "../cloud/forward.js";
+import { describeRequest, Tunnel } from "../cloud/tunnel.js";
+import { randomKey } from "../cloud/sync.js";
+import { ToolError } from "../errors.js";
+import { setting } from "../settings.js";
+/** How long start waits for the phone before answering that it is still starting (an MCP call has about a minute). */
+const READY_WAIT_MS = 40_000;
+const ACTIONS = ["start", "status", "stop", "run", "tunnel"];
+const dollars = (micro) => `$${(Number(micro ?? 0) / 1e6).toFixed(2)}`;
+const phoneOf = async (api, id) => (await api.json("GET", `/api/v1/simulator/sessions/${id}`)).session;
+/** Waits for a phone to be ready, up to the time given. Answers it as it last read. */
+async function untilReady(api, id, waitMs) {
+    let phone = await phoneOf(api, id);
+    for (const deadline = Date.now() + waitMs; !["ready", "failed", "stopped", "stopping"].includes(phone.state) && Date.now() < deadline;) {
+        await new Promise((r) => setTimeout(r, 500));
+        phone = await phoneOf(api, id);
+    }
+    return phone;
+}
+async function start(context) {
+    const signed = await signIn();
+    if ("link" in signed) {
+        return { text: `Sign in to NoMac for a cloud phone: open ${signed.link} and approve code ${signed.code}.\nNext: cloud start again once it is approved (headless: set NOMAC_API_KEY instead).` };
+    }
+    const { api } = signed;
+    const state = await cloudState();
+    if (state.session) {
+        const phone = await phoneOf(api, state.session).catch(() => undefined);
+        if (phone && (phone.state === "ready" || phone.state === "queued" || phone.state === "provisioning")) {
+            await setCloudState({ ...state, on: true });
+            return { text: `Cloud is on: phone ${phone.id} is ${phone.state}, ${dollars(phone.cost?.accrued_microunits)} so far. Every tool runs there; cloud stop ends it.` };
+        }
+    }
+    const started = Date.now();
+    const created = await api.json("POST", "/api/v1/simulator/sessions", {}, `cli-start-${randomKey()}`);
+    const id = String(created.session.id);
+    await setCloudState({ on: true, session: id });
+    const phone = await untilReady(api, id, context.waitForJobs ? 5 * 60_000 : READY_WAIT_MS);
+    if (phone.state !== "ready") {
+        if (["failed", "stopped", "stopping"].includes(phone.state)) {
+            await setCloudState({ on: false });
+            throw new ToolError(`The cloud phone did not start: ${phone.failure_code ?? phone.state}.`, "Call cloud start again; report_issue on NoMac's MCP if it keeps failing.");
+        }
+        // Waiting for a free phone, NoMac says how many there are and its place.
+        const why = phone.state === "queued" && phone.message ? ` ${phone.message}` : "";
+        return { text: `The cloud phone ${id} is still starting after ${((Date.now() - started) / 1000).toFixed(0)} s.${why}\nNext: cloud status, or any tool: it waits for the phone.` };
+    }
+    const links = (created.links ?? {});
+    const watch = links.view && links.control ? `\nA person can watch it at ${links.view} or use it at ${links.control}.` : "";
+    return { text: `Cloud phone ready in ${((Date.now() - started) / 1000).toFixed(1)} s: an iPhone Simulator on a NoMac Mac, $0.80 an hour by the minute.\nEvery tool now runs there; app_run and tests_run send the project first. cloud stop ends it.${watch}` };
+}
+/** The phone's tunnel to a backend on this machine, while this process runs (one at a time). */
+let tunnel;
+const tunnelLine = (t) => t.state === "closed" ? `The tunnel closed${t.error ? `: ${t.error}` : ""}.` : `The phone reaches ${t.localHost}:${t.localPort} on this machine at http://127.0.0.1:${t.phonePort}${t.state === "connecting" ? " (reconnecting)" : ""}.`;
+/**
+ * tunnel with port: the phone's apps reach that port on this machine (a local backend) at http://127.0.0.1:<its port>
+ * on the phone; without port: what it carried; port 0: closes it. On the command line it runs until Ctrl-C, printing
+ * each request.
+ */
+async function openTunnel(args, context) {
+    const state = await cloudState();
+    const api = await account();
+    if (args.port === 0) {
+        const had = tunnel;
+        tunnel?.stop();
+        tunnel = undefined;
+        return { text: had ? "Closed the phone's tunnel." : "No tunnel is open." };
+    }
+    const port = typeof args.port === "number" ? args.port : typeof args.path === "string" && /^\d+$/.test(args.path) ? Number(args.path) : undefined;
+    if (port === undefined) {
+        if (!tunnel)
+            return { text: "No tunnel is open.\nNext: cloud tunnel with port, your backend's port on this machine." };
+        const recent = tunnel.requests.slice(-20).map((r) => describeRequest(r));
+        return { text: `${tunnelLine(tunnel)} ${tunnel.requests.length} requests so far${recent.length ? `, the last:\n${recent.join("\n")}` : "."}${tunnel.error && tunnel.state !== "closed" ? `\nLast problem: ${tunnel.error}.` : ""}` };
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new ToolError(`${port} is not a port.`, "Pass port: your backend's port on this machine, like 8080.");
+    if (!api || !state.on || !state.session)
+        throw new ToolError("Cloud has no phone.", "Call cloud start first.");
+    if (tunnel && (tunnel.session !== state.session || tunnel.localPort !== port || tunnel.state === "closed")) {
+        tunnel.stop();
+        tunnel = undefined;
+    }
+    if (!tunnel) {
+        const opened = new Tunnel(api, state.session, port, "127.0.0.1", context.waitForJobs ? (r) => console.log(describeRequest(r, false)) : undefined);
+        await opened.start();
+        tunnel = opened;
+    }
+    const url = `http://127.0.0.1:${tunnel.phonePort}`;
+    const text = `${tunnelLine(tunnel)}\nPoint the app's backend there: app_run env "API_URL=${url}" for an app that reads it from ProcessInfo, or its Debug configuration. It works while the phone runs; cloud tunnel shows the requests it carried, cloud tunnel with port 0 closes it.`;
+    if (!context.waitForJobs)
+        return { text };
+    // The command line keeps it open, printing each request, until Ctrl-C.
+    console.log(`${text}\nRequests as they pass (Ctrl-C closes it):`);
+    await new Promise((resolve) => {
+        process.once("SIGINT", resolve);
+        process.once("SIGTERM", resolve);
+    });
+    const carried = tunnel.requests.length;
+    tunnel.stop();
+    tunnel = undefined;
+    return { text: `Closed the tunnel after ${carried} request${carried === 1 ? "" : "s"}.` };
+}
+async function status() {
+    const state = await cloudState();
+    if (!state.on)
+        return { text: "Cloud is off: the tools run on this machine. cloud start runs them on a NoMac phone." };
+    const api = await account();
+    if (!api || !state.session)
+        return { text: "Cloud is on but has no phone yet. cloud start starts one." };
+    const phone = await phoneOf(api, state.session);
+    const minutes = Math.ceil((phone.cost?.billable_seconds ?? 0) / 60);
+    if (phone.state === "queued")
+        return { text: `Cloud is on: phone ${phone.id} is waiting.${phone.message ? ` ${phone.message}` : ""}` };
+    return { text: `Cloud is on: phone ${phone.id} is ${phone.state}; ${minutes} min so far, ${dollars(phone.cost?.accrued_microunits)} at $0.80 an hour.${tunnel ? `\n${tunnelLine(tunnel)}` : ""}` };
+}
+async function stop() {
+    tunnel?.stop();
+    tunnel = undefined;
+    const state = await cloudState();
+    const api = await account();
+    await setCloudState({ on: false });
+    if (!state.session || !api)
+        return { text: "Cloud is off: the tools run on this machine." };
+    const stopped = await api.json("DELETE", `/api/v1/simulator/sessions/${state.session}`).catch((error) => {
+        if (!(error instanceof CloudError && error.status === 404))
+            throw error;
+        return undefined;
+    });
+    let phone = await phoneOf(api, state.session).catch(() => undefined);
+    for (let i = 0; phone && !phone.cleanup_confirmed && i < 15; i++) {
+        await new Promise((r) => setTimeout(r, 2_000));
+        phone = await phoneOf(api, state.session).catch(() => undefined);
+    }
+    const minutes = Math.ceil((phone?.cost?.billable_seconds ?? 0) / 60);
+    const replay = (stopped?.links ?? {}).replay;
+    return { text: `Stopped the cloud phone after ${minutes} min, ${dollars(phone?.cost?.accrued_microunits)}. The tools run on this machine again.${replay ? `\nIts replay, the screen and every call, opens at ${replay} in a minute (kept 7 days).` : ""}` };
+}
+/**
+ * CI in one call: a phone, the project built and run, its tests with tests: true, a screenshot of its screen, and
+ * the phone stopped (unless cloud was already on). Fails when the build or a test fails.
+ */
+async function runOnce(args, context) {
+    const before = await cloudState();
+    const lines = [];
+    let failed = false;
+    let image;
+    const ensure = await start({ waitForJobs: true });
+    if (/^Sign in to NoMac/.test(ensure.text))
+        return { text: ensure.text, isError: true };
+    try {
+        const path = typeof args.path === "string" ? args.path : ".";
+        // A video of the whole run for the person reviewing it (the phone records up to its own limit).
+        const recording = await forward("screen_record", { action: "start" }, context);
+        const ran = await forward("app_run", { path }, { waitForJobs: true });
+        lines.push(ran.text);
+        failed ||= Boolean(ran.isError);
+        if (!ran.isError && args.tests === true) {
+            const tested = await forward("tests_run", { path }, { waitForJobs: true });
+            lines.push(tested.text);
+            failed ||= Boolean(tested.isError);
+        }
+        const out = typeof args.out === "string" ? args.out : tmpdir();
+        if (!ran.isError) {
+            const look = await forward("ui_look", { screenshot: true }, context);
+            image = look.image;
+            if (image && context.waitForJobs) {
+                const file = join(out, `simulator-use-cloud-${Date.now()}.${image.mimeType === "image/png" ? "png" : "jpg"}`);
+                await writeFile(file, image.data);
+                lines.push(`Screenshot: ${file}`);
+            }
+        }
+        if (!recording.isError) {
+            const stopped = await forward("screen_record", { action: "stop" }, context);
+            const link = /https?:\/\/\S+\/api\/v1\/simulator\/files\/[A-Za-z0-9_.-]+/.exec(stopped.text)?.[0];
+            if (link && context.waitForJobs) {
+                const response = await fetch(link);
+                if (response.ok) {
+                    const file = join(out, `simulator-use-cloud-${Date.now()}.mp4`);
+                    await writeFile(file, Buffer.from(await response.arrayBuffer()));
+                    lines.push(`Recording: ${file}`);
+                }
+                else {
+                    lines.push(`Recording: ${link}`);
+                }
+            }
+            else if (link) {
+                lines.push(`Recording: ${link}`);
+            }
+        }
+    }
+    finally {
+        if (!before.on)
+            lines.push((await stop()).text);
+    }
+    // The command line saved the screenshot above; an MCP client gets the picture itself.
+    return { text: lines.join("\n\n"), ...(image && !context.waitForJobs ? { image } : {}), ...(failed ? { isError: true } : {}) };
+}
+export const cloud = {
+    name: "cloud",
+    title: "Cloud phone",
+    command: "cloud",
+    positional: ["action", "path"],
+    description: "A NoMac cloud iPhone Simulator on a Mac with Xcode, $0.80 an hour by the minute: for Linux, Windows, cloud agents and CI. start signs in (a link the first time; NOMAC_API_KEY headless) and starts a phone: until stop, every tool runs there and app_run and tests_run send the project first. status: phone and cost. stop: ends it. run: start, build and run path, its tests with tests, a screenshot and a recording, stop, in one call. tunnel: the phone reaches port on this machine.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ACTIONS, description: "start, status, stop, run, or tunnel" },
+            port: { type: "number", description: "tunnel: a backend's port here; 0 closes it" },
+            path: { type: "string", description: "run: project folder; default: here" },
+            tests: { type: "boolean", description: "run: its tests too" },
+            out: { type: "string", description: "run (command line): screenshot folder; default: temp" },
+        },
+        required: ["action"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    async run(args, context) {
+        if (setting("HOSTED"))
+            throw new ToolError("This is a NoMac phone already.", "Call the other tools directly.");
+        try {
+            switch (args.action) {
+                case "start":
+                    return await start(context);
+                case "status":
+                    return await status();
+                case "stop":
+                    return await stop();
+                case "run":
+                    return await runOnce(args, context);
+                case "tunnel":
+                    return await openTunnel(args, context);
+            }
+            throw new ToolError(`Unknown action "${String(args.action)}".`, `Actions: ${ACTIONS.join(", ")}.`);
+        }
+        catch (error) {
+            if (error instanceof CloudError)
+                throw new ToolError(`NoMac: ${error.message}`, error.code === "insufficient_credit" ? "Add credit at https://nomac.app/dashboard, then cloud start again." : "Call cloud status, or try again in a minute.");
+            throw error;
+        }
+    },
+};