simulator-use 0.10.1 → 0.12.0

package/dist/state-archive.js

@@ -0,0 +1,196 @@
+import { spawn } from "node:child_process";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdtemp, rename, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip, createGzip } from "node:zlib";
+/**
+ * A saved phone state as NoMac keeps it in its storage (October 25, 2026), so any phone of the same model and iOS
+ * restores it, on any host: its folder as a tar, gzipped, in AES-256-GCM frames of up to 4 MiB under the state's own
+ * key (NoMac's, given for one transfer). Each frame is authenticated with its index and whether it is the last, so an
+ * archive cut short, reordered or changed is refused before anything of it is kept.
+ */
+const MAGIC = Buffer.from("NMS1");
+const FRAME = 4 * 1024 * 1024;
+const NONCE = 12;
+const TAG = 16;
+/** The longest a frame may claim: a corrupt length never makes the reader hold gigabytes. */
+const MOST = FRAME + 64 * 1024;
+const aad = (index, last) => {
+    const b = Buffer.alloc(MAGIC.length + 9);
+    MAGIC.copy(b);
+    b.writeBigUInt64BE(BigInt(index), MAGIC.length);
+    b[MAGIC.length + 8] = last ? 1 : 0;
+    return b;
+};
+export function stateKey(key) {
+    const raw = Buffer.from(key, "base64url");
+    if (raw.length !== 32 || raw.toString("base64url") !== key)
+        throw new Error("invalid_state_key");
+    return raw;
+}
+/** Plain bytes in, sealed frames out. The last frame is sealed as last at the end, empty if need be. */
+export function sealer(key) {
+    let pending = Buffer.alloc(0), index = 0, started = false;
+    const frame = (t, plain, last) => {
+        const nonce = randomBytes(NONCE);
+        const cipher = createCipheriv("aes-256-gcm", key, nonce);
+        cipher.setAAD(aad(index++, last));
+        const body = Buffer.concat([cipher.update(plain), cipher.final()]);
+        const length = Buffer.alloc(4);
+        length.writeUInt32BE(plain.length);
+        t.push(Buffer.concat([length, nonce, body, cipher.getAuthTag()]));
+    };
+    return new Transform({
+        transform(chunk, _enc, done) {
+            if (!started) {
+                this.push(MAGIC);
+                started = true;
+            }
+            pending = pending.length ? Buffer.concat([pending, chunk]) : chunk;
+            // A full frame goes out only once more data follows it, so the one at the end is the one sealed as last.
+            while (pending.length > FRAME) {
+                frame(this, pending.subarray(0, FRAME), false);
+                pending = pending.subarray(FRAME);
+            }
+            done();
+        },
+        flush(done) {
+            if (!started)
+                this.push(MAGIC);
+            frame(this, pending, true);
+            done();
+        },
+    });
+}
+/** Sealed frames in, plain bytes out: refused at the first frame that does not open, or an end with no last frame. */
+export function opener(key) {
+    let buffered = Buffer.alloc(0), index = 0, header = false, ended = false;
+    return new Transform({
+        transform(chunk, _enc, done) {
+            buffered = buffered.length ? Buffer.concat([buffered, chunk]) : chunk;
+            try {
+                if (!header) {
+                    if (buffered.length < MAGIC.length)
+                        return done();
+                    if (!buffered.subarray(0, MAGIC.length).equals(MAGIC))
+                        throw new Error("not a NoMac phone state");
+                    buffered = buffered.subarray(MAGIC.length);
+                    header = true;
+                }
+                for (;;) {
+                    if (buffered.length < 4)
+                        break;
+                    const length = buffered.readUInt32BE(0);
+                    if (length > MOST)
+                        throw new Error("a frame claims too much");
+                    const whole = 4 + NONCE + length + TAG;
+                    if (buffered.length < whole)
+                        break;
+                    if (ended)
+                        throw new Error("data after the last frame");
+                    const nonce = buffered.subarray(4, 4 + NONCE), body = buffered.subarray(4 + NONCE, 4 + NONCE + length), tag = buffered.subarray(4 + NONCE + length, whole);
+                    // A frame opens as the last or as not: which, its sealing says.
+                    let plain;
+                    for (const last of [false, true]) {
+                        try {
+                            const decipher = createDecipheriv("aes-256-gcm", key, nonce);
+                            decipher.setAAD(aad(index, last));
+                            decipher.setAuthTag(tag);
+                            plain = Buffer.concat([decipher.update(body), decipher.final()]);
+                            ended = last;
+                            break;
+                        }
+                        catch { /* the other way, or neither */ }
+                    }
+                    if (!plain)
+                        throw new Error("the state does not open with its key (changed, or another state's)");
+                    index++;
+                    buffered = buffered.subarray(whole);
+                    if (plain.length)
+                        this.push(plain);
+                }
+                done();
+            }
+            catch (error) {
+                done(error);
+            }
+        },
+        flush(done) {
+            done(!header || !ended || buffered.length ? new Error("the state is cut short") : undefined);
+        },
+    });
+}
+/** tar as a stream, its errors and exit status kept: a tar that fails mid-way fails the pipeline. */
+function tar(args, cwd) {
+    const child = spawn("/usr/bin/tar", args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (d) => { stderr = (stderr + d).slice(-2000); });
+    const exited = new Promise((resolve, reject) => {
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`tar exited ${code}: ${stderr.trim().split("\n").pop() ?? ""}`))));
+    });
+    return { child, exited };
+}
+/**
+ * The state named name, in statesDir, sealed under key and PUT to url (a link NoMac signed). It is sealed into a file
+ * in tmp first, since the storage takes a PUT of a known length. Answers the bytes sent.
+ */
+export async function uploadState(statesDir, name, url, key, tmp) {
+    const dir = await mkdtemp(join(tmp, "state-")), sealed = join(dir, `${name}.nms`);
+    try {
+        const packing = tar(["-cf", "-", name], statesDir);
+        packing.child.stdin.end();
+        try {
+            await pipeline(packing.child.stdout, createGzip({ level: 1 }), sealer(stateKey(key)), createWriteStream(sealed, { mode: 0o600 }));
+        }
+        catch (error) {
+            packing.child.kill();
+            await packing.exited.catch(() => { });
+            throw error;
+        }
+        await packing.exited;
+        const { size } = await stat(sealed);
+        const body = Readable.toWeb(createReadStream(sealed));
+        const response = await fetch(url, { method: "PUT", body, headers: { "content-length": String(size) }, duplex: "half" });
+        await response.body?.cancel();
+        if (!response.ok)
+            throw new Error(`the state's upload failed: storage answered ${response.status}`);
+        return size;
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/**
+ * The state at url (sealed under key) unpacked into statesDir as name, replacing a copy there only once all of it
+ * opened: it is unpacked beside it first, then moved into place.
+ */
+export async function fetchState(statesDir, name, url, key) {
+    const response = await fetch(url);
+    if (!response.ok || !response.body)
+        throw new Error(`the state's download failed: storage answered ${response.status}`);
+    const into = await mkdtemp(join(statesDir, `.${name}.fetching-`));
+    try {
+        // bsdtar keeps entries inside into: no absolute paths, no .., no writes through a symlink.
+        const unpacking = tar(["-xf", "-"], into);
+        try {
+            await pipeline(Readable.fromWeb(response.body), opener(stateKey(key)), createGunzip(), unpacking.child.stdin);
+        }
+        catch (error) {
+            // Stopped and gone before its folder is removed, so nothing is written into it after.
+            unpacking.child.kill();
+            await unpacking.exited.catch(() => { });
+            throw error;
+        }
+        await unpacking.exited;
+        await stat(join(into, name, "state.json"));
+        await rm(join(statesDir, name), { recursive: true, force: true });
+        await rename(join(into, name), join(statesDir, name));
+    }
+    finally {
+        await rm(into, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/dist/tools/app-control.js

@@ -2,12 +2,26 @@ 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 { engineCall } from "../engine/native.js";
 import { currentApp, heldDevice, setCurrentApp, setDeviceTimeZone } from "../engine/state.js";
 import { ToolError } from "../errors.js";
+import { setting } from "../settings.js";
 import { readScreen } from "../look/read.js";
 import { render } from "../look/snapshot.js";
 import { grantAll, openInPrompt, setPermissionMode } from "../engine/prompts.js";
 import { launchAndLook, tapPrompt } from "./launch-app.js";
+/**
+ * A link opens through the engine, which reads it from its input: simctl openurl takes it as an argument, which every
+ * user of a Mac can read, so a shared host (SIMULATOR_USE_HOSTED) never falls back to it.
+ */
+export async function openUrl(udid, url) {
+    const answer = await engineCall(udid, { op: "open_url", url }, 20_000);
+    if (answer?.ok)
+        return;
+    if (setting("HOSTED"))
+        throw new ToolError(`Could not open the link${answer?.error ? `: ${answer.error}` : ""}.`, "Check it is a full link with its scheme (https://, or the app's own), then try again.");
+    await simctlAction(["openurl", udid, url], "open the link");
+}
 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",
@@ -99,7 +113,7 @@ export const appControl = {
             if (!path || !existsSync(path))
                 throw new ToolError("install needs app: the path to a .app built for the Simulator.", "Build with xcodebuild -sdk iphonesimulator; the .app is under Build/Products/Debug-iphonesimulator.");
             const bundleId = await bundleIdOf(path);
-            await install(device.udid, path);
+            await install(device.udid, path, device.runtime);
             const info = await appInfo(device.udid, bundleId);
             await setCurrentApp(device.udid, { bundleId, executable: info?.executable });
             const refused = await grantAll(device.udid, bundleId);
@@ -128,13 +142,13 @@ export const appControl = {
                 await simctlAction(["uninstall", device.udid, bundleId], `remove ${bundleId}`);
                 return { text: `Removed ${bundleId} and its data from ${label}.` };
             case "open_url": {
-                await simctlAction(["openurl", device.udid, value], `open ${value}`);
+                await openUrl(device.udid, value);
                 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 })}` };
+                return { text: `Opened the link.${asked ? ` iOS asked "${asked}": answered Open.` : ""}\n${render(snap, { device: label })}` };
             }
             case "grant":
             case "revoke":

package/dist/tools/app-logs.js

@@ -64,9 +64,9 @@ export const appLogs = {
             // Swift's own message ("App.swift:64: Fatal error: ...") goes to stderr, not into the report: show both.
             const last = await readFile(await consoleFile(device.udid, bundleId), "utf8").then((t) => cleanConsole(t).slice(-5).map(clip), () => []);
             const output = last.length ? `\nThe app's last output:\n${last.join("\n")}` : "";
-            const crashes = await crashReports(executable, Date.now() - Math.max(seconds, 3_600) * 1000);
+            const crashes = await crashReports(executable, Date.now() - Math.max(seconds, 3_600) * 1000, { bundleId, udid: device.udid });
             if (!crashes.length) {
-                return { text: `No crash report for ${executable} in the last hour. macOS writes one up to a minute after a crash (44 s measured).${output}\nNext: if the app just crashed, call app_logs {crashes: true} again in 30 s.` };
+                return { text: `No crash report for ${bundleId} on ${device.name} in the last hour. macOS writes one up to a minute after a crash (44 s measured).${output}\nNext: if the app just crashed, call app_logs {crashes: true} again in 30 s.` };
             }
             return { text: crashes.map((c) => [`crash at ${c.time} (${c.file})`, ...c.summary].join("\n")).join("\n\n") + output };
         }

package/dist/tools/app-run.js

@@ -2,7 +2,7 @@ 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, setDeviceEnv } from "../engine/state.js";
-import { build, builtApp, formatIssue, knownFix, noDestination, projectFor, remember } from "../engine/xcode.js";
+import { build, builtApp, formatIssue, knownFix, noDestination, projectFor, remember, targetTooNew } from "../engine/xcode.js";
 import { pickXcode } from "../engine/xcodes.js";
 import { grantAll, setPermissionMode } from "../engine/prompts.js";
 import { ToolError } from "../errors.js";
@@ -74,7 +74,7 @@ export const appRun = {
         // 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, xcode: kept } = await projectFor(args.path, args.scheme);
+            const { project, scheme, dir, note, xcode: kept } = await projectFor(args.path, args.scheme, progress);
             const asked = args.xcode ?? kept;
             const xcode = await pickXcode(asked);
             const other = xcode && !xcode.default ? xcode : undefined;
@@ -99,6 +99,13 @@ export const appRun = {
                 onCancel: (cancel) => progress.setCancel(cancel),
             };
             let result = await build(project, scheme, device.udid, options);
+            // A deployment target later than the phone's iOS leaves no destination either, and no build would install.
+            const tooNew = !result.ok && noDestination(result) ? await targetTooNew(project, scheme, device, "app_run again", other) : undefined;
+            if (tooNew) {
+                progress.setCancel(undefined);
+                progress.setLog(result.log);
+                return { text: `${note}Build of ${scheme} failed: ${tooNew}`, isError: true };
+            }
             // 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)) {
@@ -125,7 +132,7 @@ export const appRun = {
             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 install(device.udid, app, device.runtime);
             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.

package/dist/tools/cloud.js

@@ -3,16 +3,24 @@ 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 { keepFiles } from "../cloud/files.js";
+import { forward, stopNotice } from "../cloud/forward.js";
 import { describeRequest, Tunnel } from "../cloud/tunnel.js";
 import { randomKey } from "../cloud/sync.js";
+import { onSignalExit } from "../engine/jobs.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 ACTIONS = ["start", "status", "extend", "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;
+const readPhone = async (api, id) => {
+    const read = await api.json("GET", `/api/v1/simulator/sessions/${id}`);
+    return { phone: read.session, links: (read.links ?? {}) };
+};
+const phoneOf = async (api, id) => (await readPhone(api, id)).phone;
+const gone = (error) => error instanceof CloudError && (error.status === 404 || error.code === "session_not_found");
+const watchLine = (links) => (links.view && links.control ? `\nA person can watch it at ${links.view} or use it at ${links.control}.` : "");
 /** 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);
@@ -22,7 +30,9 @@ async function untilReady(api, id, waitMs) {
     }
     return phone;
 }
-async function start(context) {
+const DEVICE_NAMES = { iphone: "iPhone", ipad: "iPad" };
+async function start(args, context) {
+    const device = typeof args.device === "string" ? args.device : undefined;
     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).` };
@@ -30,14 +40,23 @@ async function start(context) {
     const { api } = signed;
     const state = await cloudState();
     if (state.session) {
-        const phone = await phoneOf(api, state.session).catch(() => undefined);
+        // A phone NoMac no longer has is gone; any other failure (the network) is NoMac's answer, never a second phone.
+        const read = await readPhone(api, state.session).catch((error) => {
+            if (gone(error))
+                return undefined;
+            throw error;
+        });
+        const phone = read?.phone;
         if (phone && (phone.state === "ready" || phone.state === "queued" || phone.state === "provisioning")) {
+            if (device && phone.device && phone.device !== device) {
+                throw new ToolError(`Cloud already has phone ${phone.id}, an ${DEVICE_NAMES[phone.device] ?? phone.device}.`, `cloud stop, then cloud start with device ${device}.`);
+            }
             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.` };
+            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.${watchLine(read.links)}` };
         }
     }
     const started = Date.now();
-    const created = await api.json("POST", "/api/v1/simulator/sessions", {}, `cli-start-${randomKey()}`);
+    const created = await api.json("POST", "/api/v1/simulator/sessions", device ? { device } : {}, `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);
@@ -50,12 +69,18 @@ async function start(context) {
         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}` };
+    const watch = watchLine((created.links ?? {}));
+    return { text: `Cloud phone ready in ${((Date.now() - started) / 1000).toFixed(1)} s: an ${DEVICE_NAMES[device ?? "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;
+/** The tunnel's notice (its port changed), once: said after the next answer from the phone. */
+export function tunnelNotice() {
+    const notice = tunnel?.notice;
+    if (tunnel)
+        tunnel.notice = undefined;
+    return notice;
+}
 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>
@@ -76,7 +101,8 @@ async function openTunnel(args, context) {
         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}.` : ""}` };
+        const notice = tunnelNotice();
+        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}.` : ""}${notice ? `\n${notice}` : ""}` };
     }
     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.");
@@ -87,7 +113,7 @@ async function openTunnel(args, context) {
         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);
+        const opened = new Tunnel(api, state.session, port, "127.0.0.1", context.waitForJobs ? (r) => console.log(describeRequest(r, false)) : undefined, context.waitForJobs ? (n) => console.log(n) : undefined);
         await opened.start();
         tunnel = opened;
     }
@@ -113,55 +139,142 @@ async function status() {
     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 { phone, links } = await readPhone(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)}` : ""}` };
+    const limit = phone;
+    const until = phone.state === "ready" && limit.ready_at && limit.limits?.max_duration_seconds ? new Date(Date.parse(limit.ready_at) + limit.limits.max_duration_seconds * 1000).toISOString().slice(11, 16) : undefined;
+    const stops = until ? ` It stops by ${until} UTC at the latest; cloud extend keeps it longer.` : "";
+    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.${stops}${tunnel ? `\n${tunnelLine(tunnel)}` : ""}${phone.state === "ready" ? watchLine(links) : ""}` };
 }
-async function stop() {
+/**
+ * The phone kept running longer: its time limit (and its spend cap with it) up by minutes, an hour by default (the
+ * command line takes the minutes: cloud extend 30), up to 8 hours in all. The account's credit still decides.
+ */
+async function extend(args) {
+    const state = await cloudState();
+    const api = await account();
+    if (!api || !state.on || !state.session)
+        throw new ToolError("Cloud has no phone to extend.", "cloud start.");
+    const minutes = typeof args.path === "string" && /^\d+$/.test(args.path) ? Number(args.path) : 60;
+    if (minutes < 1 || minutes > 480)
+        throw new ToolError(`${minutes} minutes is not an extension.`, "cloud extend with 1 to 480 minutes.");
+    let answer;
+    try {
+        answer = await api.json("POST", `/api/v1/simulator/sessions/${state.session}/extend`, { minutes });
+    }
+    catch (error) {
+        if (error instanceof CloudError && error.code === "session_at_longest")
+            throw new ToolError(`NoMac: ${error.message}`, "When it stops, cloud start: the next build is incremental.");
+        if (error instanceof CloudError && error.code === "session_not_ready")
+            throw new ToolError(`The cloud phone ${state.session} is not running, so it cannot be extended.`, "cloud status, or cloud start for a new one.");
+        throw error;
+    }
+    const phone = answer.session;
+    const until = phone.ready_at && phone.limits?.max_duration_seconds ? new Date(Date.parse(phone.ready_at) + phone.limits.max_duration_seconds * 1000).toISOString().slice(11, 16) : undefined;
+    const runs = until ? `runs until ${until} UTC at the latest` : `has ${minutes} more minutes`;
+    return { text: `The cloud phone ${phone.id} ${runs}, if the account's credit lasts. cloud extend again near then, up to 8 hours in all.${stopNotice(answer)}` };
+}
+/** NoMac's links that open without signing in: a phone's view and control, its replay and its files. */
+const OPEN_LINK = /https?:\/\/[^\s/]+\/(?:simulator-use\/(?:view|replay)|api\/v1\/simulator\/files)\/[A-Za-z0-9_.-]+/g;
+/** A CI job, whose log and pull request comment can be public. */
+const inCI = () => Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
+async function stop(options = {}) {
     tunnel?.stop();
     tunnel = undefined;
     const state = await cloudState();
     const api = await account();
-    await setCloudState({ on: false });
-    if (!state.session || !api)
+    if (!state.session || !api) {
+        await setCloudState({ on: false });
         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;
-    });
+    }
+    // The phone is forgotten only once NoMac took the stop: a stop that did not reach it leaves the phone billing.
+    let stopped;
+    try {
+        stopped = await api.json("DELETE", `/api/v1/simulator/sessions/${state.session}`);
+    }
+    catch (error) {
+        if (!gone(error)) {
+            return { text: `Could not stop the cloud phone ${state.session}: ${error.message.replace(/\.$/, "")}. It runs, and bills, until its idle stop.\nNext: cloud stop again.`, isError: true };
+        }
+    }
+    await setCloudState({ on: false });
     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 cost = phone ? `after ${Math.ceil((phone.cost?.billable_seconds ?? 0) / 60)} min, ${dollars(phone.cost?.accrued_microunits)}` : "(its cost is on NoMac's dashboard)";
     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).` : ""}` };
+    // In CI the link stays out of the log and the comment, which can be public: the account's key reads it.
+    const replayLine = !replay ? "" : options.linkless
+        ? `\nIts replay, the screen and every call, is kept 7 days. Its link opens without signing in, so it is left out here: GET https://nomac.app/api/v1/simulator/sessions/${state.session} with the account's key answers it (links.replay).`
+        : `\nIts replay, the screen and every call, opens at ${replay} in a minute (kept 7 days).`;
+    return { text: `Stopped the cloud phone ${cost}. The tools run on this machine again. A file link from its answers keeps working only if it was opened before this stop.${replayLine}` };
+}
+/** A phone stopped at once, as the process ends (a signal): no waiting for its cleanup. */
+async function stopNow(session) {
+    const api = await account();
+    await api?.json("DELETE", `/api/v1/simulator/sessions/${session}`).catch(() => undefined);
+    await setCloudState({ on: false });
+}
+/**
+ * The phone an MCP server started, stopped as the server ends (its client closed it, or a signal): it was that
+ * agent's alone, and would otherwise bill until its idle stop. A CLI command keeps its phone for the next one.
+ */
+export async function stopServerPhone() {
+    tunnel?.stop();
+    tunnel = undefined;
+    const { session } = await cloudState();
+    if (session)
+        await stopNow(session);
 }
 /**
  * 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) {
+    // A run waits for a phone, the build and the tests, which takes minutes, past what an MCP call waits for; and its
+    // steps are tools an agent already has.
+    if (!context.waitForJobs) {
+        throw new ToolError("cloud run is for the command line and CI: it takes minutes, longer than a tool call waits. Nothing ran.", "cloud start, then app_run (tests_run for the tests), then cloud stop.");
+    }
     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 };
+    // The phone this run started: stopped at its end, and before the process ends on a signal (Ctrl-C, a cancelled
+    // CI job), so a run never leaves a phone billing.
+    let created;
+    let signingIn = false;
+    const startedHere = async () => {
+        const now = await cloudState().catch(() => undefined);
+        if (now?.session && now.session !== before.session)
+            created = now.session;
+        return created;
+    };
+    const release = onSignalExit(async () => {
+        const session = (await startedHere()) ?? (before.on ? undefined : (await cloudState()).session);
+        if (session)
+            await stopNow(session);
+    });
     try {
+        const ensure = await start(args, { waitForJobs: true });
+        // Not signed in yet: nothing started, and the pending sign-in is kept for the next call.
+        if (/^Sign in to NoMac/.test(ensure.text)) {
+            signingIn = true;
+            return { text: ensure.text, isError: true };
+        }
         const path = typeof args.path === "string" ? args.path : ".";
+        const scheme = typeof args.scheme === "string" && args.scheme ? { scheme: args.scheme } : {};
         // 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 });
+        const ran = await forward("app_run", { path, ...scheme }, { 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 });
+            const tested = await forward("tests_run", { path, ...scheme }, { waitForJobs: true });
             lines.push(tested.text);
             failed ||= Boolean(tested.isError);
         }
@@ -193,28 +306,34 @@ async function runOnce(args, context) {
                 lines.push(`Recording: ${link}`);
             }
         }
+        await keepFiles(lines, out);
     }
     finally {
-        if (!before.on)
-            lines.push((await stop()).text);
+        release();
+        if (!signingIn && ((await startedHere()) || !before.on))
+            lines.push((await stop({ linkless: inCI() })).text);
     }
+    // In CI, a link that opens without signing in (one keepFiles could not save) stays out of the log and the comment.
+    const text = inCI() ? lines.join("\n\n").replace(OPEN_LINK, "(a link left out: CI's log can be public)") : lines.join("\n\n");
     // 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 } : {}) };
+    return { text, ...(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.",
+    description: "A NoMac cloud iPhone or iPad Simulator, $0.80 an hour by the minute, for Linux, Windows, cloud agents, CI. start signs in (a link; NOMAC_API_KEY headless) and starts one: until stop every tool runs there, app_run and tests_run send the project. status: phone, cost. extend: an hour more. stop: ends it. run (CLI, CI): start, build and run path, tests, screenshot, recording, stop. tunnel: the phone reaches port here.",
     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" },
+            action: { type: "string", enum: ACTIONS, description: "what to do" },
+            device: { type: "string", enum: ["iphone", "ipad"], description: "start, run" },
+            port: { type: "number", description: "tunnel: a local port; 0 closes it" },
+            path: { type: "string", description: "run: project folder" },
+            tests: { type: "boolean", description: "run: tests too" },
+            scheme: { type: "string", description: "run: scheme" },
+            out: { type: "string", description: "run: output folder" },
         },
         required: ["action"],
         additionalProperties: false,
@@ -226,9 +345,11 @@ export const cloud = {
         try {
             switch (args.action) {
                 case "start":
-                    return await start(context);
+                    return await start(args, context);
                 case "status":
                     return await status();
+                case "extend":
+                    return await extend(args);
                 case "stop":
                     return await stop();
                 case "run":

package/dist/tools/device-use.js

@@ -13,7 +13,7 @@ export const deviceUse = {
     inputSchema: {
         type: "object",
         properties: {
-            device: { type: "string", description: "Name, name with runtime (\"iPhone 17 Pro (iOS 26.5)\") or UDID; default: the booted one, else the newest iPhone" },
+            device: { type: "string", description: "Name, name with runtime (\"iPhone 17 Pro (iOS 27.0)\") or UDID; default: the booted one, else the newest iPhone" },
             appearance: { type: "string", enum: ["light", "dark"], description: "Light or dark mode" },
             status_bar: { type: "string", enum: ["clean", "real"], description: "clean: 9:41 and full bars; real: undo" },
         },