@nomac/cli 0.6.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomac/cli",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Cloud Mac sessions over SSH and HTTPS, plus iOS builds and publishing — built for agents.",
   "license": "UNLICENSED",
   "type": "module",

package/skill/SKILL.md

@@ -6,7 +6,7 @@ description: >
   stop.
 ---
 
-# nomac — a Mac for your agent
+# nomac: a Mac for your agent
 
 NoMac 2.0 provides a full macOS VM with administrator access. You choose the
 commands and tools. Mac time is prepaid credit, separate from Builder.
@@ -45,10 +45,14 @@ Keep the same request key and arguments after uncertain responses; inspect
 the original job before retrying. Output retrieval failure is not job failure.
 Managed jobs have a 600-second limit; SSH can run longer within session limits.
 CLI sync skips symlinks and preserves remote extra files; use native SSH/rsync
-when needed. Commands can take screenshots (`screencapture -x shot.png`, then
-`read_mac_file`) and drive apps with AppleScript without a permission prompt;
-drive the Simulator with simctl, and give the human `open_mac_desktop` when a
-screen needs a person. `get_mac_session` (and `nomac status --json`) lists what
+when needed. See the screen with `nomac screenshot` (saves
+`nomac-screenshot.jpg`; `--simulator` for the iOS Simulator) or MCP
+`screenshot_mac`, which returns an image you can look at. Record a video for
+the human with `nomac record`, do the work, then `nomac record stop` (saves the
+MP4 and prints a share link); MCP `start_mac_recording`, `stop_mac_recording`.
+Commands drive any app with AppleScript without a permission prompt; drive the
+Simulator with simctl, and give the human `open_mac_desktop` when a screen
+needs a person. `get_mac_session` (and `nomac status --json`) lists what
 is installed: Ruby with CocoaPods, xcbeautify, xcodegen, gh, Git LFS, jq.
 Pipe xcodebuild through `xcbeautify`. Persistent disks are not currently offered.
 Report failures using `report_issue` with `session_id`, optional `job_id` and

package/src/cli.mjs

@@ -20,6 +20,8 @@ Use it:
   nomac sync .                 upload changed project files
   nomac pull ./build           download a folder from the Mac
   nomac desktop                the Mac's desktop in your browser
+  nomac screenshot             save the Mac's screen as nomac-screenshot.jpg
+  nomac record                 record a video; nomac record stop saves it with a share link
   nomac status                 state, cost so far and when it stops
 
 Agents:
@@ -28,6 +30,28 @@ Agents:
 More: nomac start --help, nomac whoami, nomac start --host user@mac (a Mac you own)
 Environment: NOMAC_API_KEY, NOMAC_API_URL`;
 
+// The Builder commands act at once (a release build uses one of the plan's builds),
+// so they take only their own flags and print usage for --help instead of running.
+const LEGACY_HELP = {
+  push: "Usage: nomac push\n  Upload this folder as a project snapshot (respects .gitignore; secrets are excluded).",
+  build: "Usage: nomac build [--smoke] [--testflight | --wait]\n  Start a signed release build for TestFlight (uses one build from your plan).\n  --smoke       unsigned compile check instead\n  --testflight  wait until the build is on TestFlight (--wait for a smoke build)",
+  status: "Usage: nomac status [build-id]\n  Show a build's state as JSON (the last build in this folder by default).",
+  logs: "Usage: nomac logs [build-id]\n  Show a build's steps and failure excerpt (the last build in this folder by default).",
+  mcp: "Usage: nomac mcp\n  Run the NoMac MCP server on stdin/stdout. Add it to your agent's MCP settings as the command `nomac mcp`.",
+};
+const isHelp = (args) => args.some((a) => a === "--help" || a === "-h" || a === "help");
+function onlyFlags(args, allowed, command) {
+  const unknown = args.find((a) => !allowed.includes(a));
+  if (unknown !== undefined) throw new CliError(`unknown option: ${unknown}`, `Unknown option "${unknown}" for nomac ${command}.\n\n${LEGACY_HELP[command]}`);
+}
+/** A build ID argument: bld_..., or none for the folder's last build. Never a flag. */
+function buildIdArg(args, command) {
+  const [first, ...more] = args.filter((a) => a !== "--json");
+  if (first === undefined) return undefined;
+  if (!/^bld_[A-Za-z0-9]+$/.test(first) || more.length) throw new CliError(`not a build id: ${first}`, `"${[first, ...more].join(" ")}" is not a build ID (bld_...).\n\n${LEGACY_HELP[command]}`);
+  return first;
+}
+
 export async function main(argv) {
   const [cmd, ...rest] = argv;
   switch (cmd) {
@@ -49,7 +73,10 @@ export async function main(argv) {
     }
     case "status":
       // A legacy build ID, or a folder that only ever built with the old pipeline, keeps build status.
-      if (/^bld_/.test(rest[0] ?? "") || (loadProjectState().last_build && !(await import("./session-store.mjs")).sessionStore().load())) return status(rest[0]);
+      if (/^bld_/.test(rest[0] ?? "") || (loadProjectState().last_build && !(await import("./session-store.mjs")).sessionStore().load())) {
+        if (isHelp(rest)) return console.log(LEGACY_HELP.status);
+        return status(buildIdArg(rest, "status"));
+      }
     // falls through: everyone else sees their Mac
     case "start":
     case "exec":
@@ -58,6 +85,8 @@ export async function main(argv) {
     case "sync":
     case "ssh":
     case "desktop":
+    case "screenshot":
+    case "record":
     case "pull":
     case "stop":
     case "session": {
@@ -80,19 +109,26 @@ export async function main(argv) {
         }
         saveApiKey(key);
         const me = await api("GET", "/api/v1/me");
-        console.log(`✅ logged in — org "${me.org.name}" (${me.org.id})`);
+        console.log(`✅ logged in: org "${me.org.name}" (${me.org.id})`);
         return;
       }
       const { deviceLogin } = await import("./login.mjs");
       return deviceLogin();
     }
     case "push":
+      if (isHelp(rest)) return console.log(LEGACY_HELP.push);
+      onlyFlags(rest, [], "push");
       return push();
     case "build":
+      if (isHelp(rest)) return console.log(LEGACY_HELP.build);
+      onlyFlags(rest, ["--smoke", "--testflight", "--wait"], "build");
       return build(rest);
     case "logs":
-      return logs(rest[0]);
+      if (isHelp(rest)) return console.log(LEGACY_HELP.logs);
+      return logs(buildIdArg(rest, "logs"));
     case "mcp": {
+      // Agents start this as a stdio server; --help must not start it and wait on stdin.
+      if (isHelp(rest)) return console.log(LEGACY_HELP.mcp);
       const { runMcpServer } = await import("./mcp.mjs");
       return runMcpServer();
     }
@@ -145,10 +181,10 @@ async function push() {
     const icon = res.lint.grade === "green" ? "🟢" : res.lint.grade === "yellow" ? "🟡" : "🔴";
     const n = res.lint.findings ?? 0;
     console.log(
-      `   review lint: ${icon} ${res.lint.grade}${n ? ` — ${n} finding${n === 1 ? "" : "s"}` : ""}`,
+      `   review lint: ${icon} ${res.lint.grade}${n ? ` · ${n} finding${n === 1 ? "" : "s"}` : ""}`,
     );
     if (res.lint.grade === "red") {
-      console.log("   ⚠  red findings will block publish — fix them before `nomac build`/publish.");
+      console.log("   ⚠  red findings will block publish: fix them before `nomac build`/publish.");
     }
   }
   if (res.warning) console.log(`⚠  ${res.warning}`);
@@ -158,7 +194,7 @@ async function push() {
 async function build(rest) {
   const state = loadProjectState();
   if (!state.project_id) {
-    throw new CliError("no project", "No project here — run `nomac push` first.");
+    throw new CliError("no project", "No project here. Run `nomac push` first.");
   }
   const smoke = rest.includes("--smoke");
   const wait = rest.includes("--testflight") || rest.includes("--wait");
@@ -204,8 +240,8 @@ async function waitForBuild(id) {
     if (b.state === "ready") {
       console.log(
         b.workflow === "smoke"
-          ? "\n🎉 smoke build passed — the project compiles clean on macOS."
-          : "\n🎉 build ready — open TestFlight on your phone, the new build is live.",
+          ? "\n🎉 smoke build passed: the project compiles clean on macOS."
+          : "\n🎉 build ready: open TestFlight on your phone, the new build is live.",
       );
       return;
     }

package/src/hosted-sessions.mjs

@@ -8,6 +8,7 @@ import { forwardingArg, runProcess, sshArgs, workspaceCommand } from "./session-
 import { pullProject, syncProject } from "./session-transfer.mjs";
 import { macRequest, sessionId, transportOptions } from "./mac-transport.mjs";
 import { desktop, DESKTOP_HELP } from "./desktop.mjs";
+import { screenshot, startRecording, stopRecording } from "./mac-screen.mjs";
 
 const HELP = `Nomac cloud Mac sessions
   nomac start [--wait 300] [--max-duration 7200] [--idle-timeout 600] [--max-cost 5] [--json]
@@ -23,6 +24,12 @@ const HELP = `Nomac cloud Mac sessions
   nomac job JOB_ID [--wait 600]     wait for a command that outlasted --wait
   nomac output JOB_ID [--cursor 0] [--stream stdout|stderr]
   nomac pull ./output [--from PATH] retrieve files before stopping
+  nomac screenshot [--simulator] [-o FILE]
+                                    save the screen (or the Simulator) as a JPEG,
+                                    nomac-screenshot.jpg unless -o
+  nomac record [--simulator] [--max 300]
+                                    start a screen video; nomac record stop saves it
+                                    as nomac-recording.mp4 (or -o) with a share link
   nomac status [--json]             state, cost so far and when it stops
   nomac stop [--wait 60] [--json]   stop the Mac: deletes it and its files
 
@@ -39,7 +46,7 @@ const options = {
   "max-cost": { type: "string" }, "request-key": { type: "string" }, timeout: { type: "string" },
   overwrite: { type: "boolean" }, "dry-run": { type: "boolean" }, from: { type: "string" },
   forward: { type: "string", multiple: true }, cursor: { type: "string" }, stream: { type: "string" },
-  "no-open": { type: "boolean" },
+  "no-open": { type: "boolean" }, simulator: { type: "boolean" }, output: { type: "string", short: "o" }, max: { type: "string" },
 };
 function budget(value = "5") {
   if (!/^(?:0|[1-9][0-9]{0,5})(?:\.[0-9]{1,6})?$/.test(value)) throw new CliError("--max-cost must be a positive USD amount, for example 5 or 2.50.");
@@ -83,7 +90,7 @@ async function waitForCommand(id, base, started, waitSeconds, { request, transpo
   let job = started;
   const deadline = now() + waitSeconds * 1000;
   const begun = now();
-  let announced = false;
+  let announced = false, busy = false;
   for (let polls = 0; waitSeconds && !["exited", "unknown"].includes(job.state) && now() < deadline; polls++) {
     // A slow command can outlive the shell waiting for it (agent shells time out); leave a way back.
     if (!json && !announced && now() - begun >= NOTICE_MS && deadline - now() > 1000) {
@@ -91,16 +98,19 @@ async function waitForCommand(id, base, started, waitSeconds, { request, transpo
       stderr(`nomac: ${job.id} is still running; waiting up to ${waitSeconds} s. If interrupted: nomac job ${job.id} --wait 600\n`);
     }
     await sleep(Math.min(POLL_MS[polls] ?? 1000, Math.max(0, deadline - now())));
-    job = await hostedRequest(id, "GET", `${base}/jobs/${job.id}`, {}, { request, transport, cache });
+    // A saturated Mac (a booting Simulator) answers late; the command still runs, so keep waiting.
+    try { job = await hostedRequest(id, "GET", `${base}/jobs/${job.id}`, {}, { request, transport, cache }); busy = false; }
+    catch (error) { if (error?.code !== "guest_busy") throw error; busy = true; }
   }
   if (job.state !== "exited") {
     if (!waitSeconds) { print(JSON.stringify(job, null, 2)); return job; }
     const unknown = job.state === "unknown";
+    const busyNote = busy ? "The Mac is busy (for example, the iOS Simulator is booting) and answers slowly. " : "";
     const next = unknown ? `The Mac could not confirm whether ${job.id} finished. Inspect it with nomac job ${job.id}; do not rerun it.`
-      : `Still running after ${waitSeconds} s; it keeps running on the Mac. Wait for it: nomac job ${job.id} --wait 600. Next time wait up front: nomac exec --wait 600 -- command. Over 10 minutes: nomac ssh -- command. Do not rerun it.`;
-    if (json) print(JSON.stringify({ ...job, next_step: next }, null, 2));
+      : `${busyNote}Still running after ${waitSeconds} s; it keeps running on the Mac. Wait for it: nomac job ${job.id} --wait 600. Next time wait up front: nomac exec --wait 600 -- command. Over 10 minutes: nomac ssh -- command. Do not rerun it.`;
+    if (json) print(JSON.stringify({ ...job, ...(busy ? { busy: true } : {}), next_step: next }, null, 2));
     else if (unknown) stderr(`nomac: ${next}\n`);
-    else stderr(`nomac: still running after ${waitSeconds} s (${job.id}); it keeps running on the Mac.\n  wait for it:            nomac job ${job.id} --wait 600\n  next time, wait longer: nomac exec --wait 600 -- command\n  over 10 minutes:        nomac ssh -- command\n`);
+    else stderr(`nomac: ${busy ? "the Mac is busy (for example, the iOS Simulator is booting); " : ""}still running after ${waitSeconds} s (${job.id}); it keeps running on the Mac.\n  wait for it:            nomac job ${job.id} --wait 600\n  next time, wait longer: nomac exec --wait 600 -- command\n  over 10 minutes:        nomac ssh -- command\n`);
     exitWith(unknown ? 1 : STILL_RUNNING);
     return job;
   }
@@ -111,7 +121,7 @@ async function waitForCommand(id, base, started, waitSeconds, { request, transpo
     for (let cursor = 0; ;) {
       const part = await hostedRequest(id, "GET", `${base}/jobs/${job.id}/output?cursor=${cursor}&stream=${stream}`, {}, { request, transport, cache });
       parts.push(Buffer.from(part.data_base64 ?? "", "base64"));
-      if (part.eof && part.tail_base64) parts.push(Buffer.from(`\n[output over 8 MiB was not kept; its last part follows]\n`), Buffer.from(part.tail_base64, "base64"));
+      if (part.eof && part.tail_base64) parts.push(...tailAfter(part));
       if (part.eof || part.next_cursor === cursor) break;
       cursor = part.next_cursor;
     }
@@ -125,6 +135,24 @@ async function waitForCommand(id, base, started, waitSeconds, { request, transpo
   return job;
 }
 
+/**
+ * The 8 MiB output budget is shared by both streams, and once it runs out each
+ * stream's final 64 KiB comes back as a tail. Keep only what the retained prefix
+ * does not already hold: nothing for a stream that was not cut, the rest after a
+ * gap note for one that was.
+ */
+export function tailAfter(part) {
+  const tail = Buffer.from(part.tail_base64, "base64"), have = part.next_cursor;
+  const start = Number.isSafeInteger(part.tail_offset) ? part.tail_offset : have;
+  const total = Number.isSafeInteger(part.total_bytes) ? part.total_bytes : start + tail.length;
+  if (total <= have) return [];
+  if (start > have) return [Buffer.from(`\n[output over 8 MiB was not kept; its last part follows]\n`), tail];
+  return [tail.subarray(have - start)];
+}
+/** A command line the person can paste back: simple words as they are, the rest single-quoted. */
+const shellWords = words => words.map(w => /^[A-Za-z0-9_\/.:=@%+,-]+$/.test(w) ? w : `'${w.replaceAll("'", "'\\''")}'`).join(" ");
+/** Errors after which the command may or may not have started on the Mac. */
+const uncertainOutcome = error => !Number.isInteger(error?.status) || error.status >= 500 || ["outcome_unknown", "operation_pending"].includes(error?.code);
 const usd = microunits => `$${(Number(microunits ?? 0) / 1_000_000).toFixed(2)}`;
 const clockUtc = ms => new Date(ms).toISOString().slice(11, 16) + " UTC";
 /** One readable paragraph for nomac status. */
@@ -162,7 +190,10 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     const usage = billing?.mode === "weekly_included"
       ? `Included time used: ${billing.used_seconds} seconds. No extra charge.`
       : `Cost so far: $${(Number(result.session?.cost?.accrued_microunits ?? 0) / 1_000_000).toFixed(2)} ($0.80/hour, billed by the minute while the Mac is ready). Credit left: nomac credits`;
-    print(values.json || !["start", "stop"].includes(command) ? JSON.stringify(result, null, 2) : `${result.session.id}: ${result.session.state}\n${result.session.state === "ready" ? "Next: nomac sync . → nomac ssh" : "Check: nomac session status --json"}\n${usage}`);
+    const next = result.session.state === "ready" ? "Next: nomac sync . → nomac ssh"
+      : result.session.failure_code === "capacity_unavailable" ? "No Mac was free within 5 minutes; nothing was charged. Run nomac start again in a few minutes."
+      : result.session.state === "queued" ? "Waiting for a free Mac (waiting is free). Check again: nomac start" : "Check: nomac session status --json";
+    print(values.json || !["start", "stop"].includes(command) ? JSON.stringify(result, null, 2) : `${result.session.id}: ${result.session.state}\n${next}\n${usage}`);
     return result;
   };
   const saveView = (local, view) => {
@@ -207,9 +238,11 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
       if (!positionals.length || !argv.includes("--")) throw new CliError("Use nomac exec -- command args");
       if (values["request-key"] !== undefined && !/^[A-Za-z0-9_.:-]{8,128}$/.test(values["request-key"])) throw new CliError("A request key is 8 to 128 letters, digits, underscores, periods, colons or hyphens.");
       // A person running a command once needs no key; scripts pass one so a lost response can be retried safely.
-      // A long wait implies a long command, so the command's own limit follows it unless set.
+      // Without a key, a long wait implies a long command, so the command's own limit follows it unless set.
+      // With a key the limit must not depend on --wait: a retry with another --wait is the same command.
       const waitFor = integer(values.wait, 30, 0, 600);
-      method = "POST"; path = `${base}/jobs`; params = { requestKey: values["request-key"] ?? `cli-${randomUUID()}`, body: { argv: positionals, timeout_seconds: integer(values.timeout, Math.max(300, waitFor), 1, 600) } };
+      const timeout = integer(values.timeout, values["request-key"] === undefined ? Math.max(300, waitFor) : 600, 1, 600);
+      method = "POST"; path = `${base}/jobs`; params = { requestKey: values["request-key"] ?? `cli-${randomUUID()}`, body: { argv: positionals, timeout_seconds: timeout } };
     } else {
       if (positionals.length !== 1 || !/^job_[a-f0-9]{40}$/.test(positionals[0])) throw new CliError("Supply the existing job ID.");
       path = `${base}/jobs/${positionals[0]}`;
@@ -219,11 +252,42 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
         path += `/output?cursor=${cursor}&stream=${stream}`;
       }
     }
-    const cache = {}, result = await hostedRequest(local.id, method, path, params, { request, transport, cache });
     const waiting = command === "exec" || (command === "job" && values.wait !== undefined);
+    const cache = {}, result = await hostedRequest(local.id, method, path, params, { request, transport, cache }).catch(error => {
+      // The job exists; a busy Mac only delays its report.
+      if (command === "job" && waiting && error?.code === "guest_busy") return { id: positionals[0], state: "running" };
+      // The key this CLI made up is the only safe way to retry: say it, with the exact same command.
+      if (command === "exec" && values["request-key"] === undefined && uncertainOutcome(error)) {
+        error.friendly = `${error.friendly ?? error.message}\nThe command may have started. To retry it without running it twice: nomac exec --request-key ${params.requestKey} --timeout ${params.body.timeout_seconds}${values.wait !== undefined ? ` --wait ${values.wait}` : ""} -- ${shellWords(positionals)}`;
+      }
+      throw error;
+    });
     if (!waiting) return output(result);
     return waitForCommand(local.id, base, result, integer(values.wait, 30, 0, 600), { request, transport, cache, print, stdout, stderr, exitWith, sleep, now, json: Boolean(values.json) });
   }
+  if (command === "screenshot") {
+    if (positionals.length) throw new CliError("Usage: nomac screenshot [--simulator] [-o FILE]");
+    const shot = await screenshot(localSession().id, { target: values.simulator ? "simulator" : "screen", saveTo: values.output ?? "nomac-screenshot.jpg" });
+    print(values.json ? JSON.stringify(shot, null, 2) : `Saved ${shot.saved_to} (${shot.width}x${shot.height}${shot.front_app ? `, ${shot.front_app} in front` : ""})`);
+    return shot;
+  }
+  if (command === "record") {
+    const local = localSession();
+    if (positionals[0] === "stop" && positionals.length === 1) {
+      const saved = await stopRecording(local.id, { saveTo: values.output ?? "nomac-recording.mp4" });
+      const r = saved.recording, link = saved.link;
+      // Only a ready link can be shared; a failed or unfinished copy says so instead.
+      const share = link?.state === "ready" ? `Share it: ${link.url} (works until ${link.expires_at.slice(11, 16)} UTC, also after the Mac stops)`
+        : link?.state === "failed" ? `No share link: ${link.error?.message ?? "the copy from the Mac failed"}${saved.saved_to ? "" : ` The video is still on the Mac at ${r.path} until the Mac stops.`}`
+        : `The share link is still being prepared: ${link?.url} (check it in a minute; it works until ${link?.expires_at?.slice(11, 16)} UTC).`;
+      print(values.json ? JSON.stringify(saved, null, 2) : `${saved.saved_to ? `Saved ${saved.saved_to}` : `Saved on the Mac at ${r.path}`} (${Number(r.seconds).toFixed(1)} s, ${(r.size / 1024 / 1024).toFixed(1)} MB${r.ended_by === "time limit" ? ", stopped at its time limit" : ""}).\n${share}`);
+      return saved;
+    }
+    if (positionals.length) throw new CliError("Usage: nomac record [--simulator] [--max SECONDS], then nomac record stop [-o FILE]");
+    const started = await startRecording(local.id, { target: values.simulator ? "simulator" : "screen", maxSeconds: values.max === undefined ? undefined : integer(values.max, 300, 1, 1800) });
+    print(values.json ? JSON.stringify(started, null, 2) : `Recording the ${values.simulator ? "Simulator" : "screen"}; it stops by itself after ${started.max_seconds} s.\nSave it: nomac record stop`);
+    return started;
+  }
   if (command === "desktop") {
     if (positionals.length) throw new CliError("Usage: nomac desktop [--no-open] [--json]");
     return desktop(await ready(localSession()), { values, print });

package/src/mac-fetch.mjs

@@ -7,6 +7,8 @@ export const FETCH_SCRIPT = [
   "set -euo pipefail",
   'dest="$NOMAC_PATH"',
   'case "$dest" in "~") dest="$HOME" ;; "~/"*) dest="$HOME/${dest:2}" ;; esac',
+  // A plain download moved onto a folder would land inside it under a temporary name.
+  'if [ -z "${NOMAC_EXTRACT:-}" ] && [ -d "$dest" ]; then echo "$dest is a folder. Give the path of the file to create, for example $dest/NAME, or use extract to unpack an archive into the folder." >&2; exit 2; fi',
   'tmp="$(mktemp "${TMPDIR:-/tmp}/nomac-fetch.XXXXXX")"',
   "trap 'rm -f \"$tmp\"' EXIT",
   'curl -fsSL --retry 3 --retry-all-errors --max-time 590 -o "$tmp" -- "$NOMAC_URL"',

package/src/mac-screen.mjs

@@ -0,0 +1,32 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { api } from "./api.mjs";
+import { checkLink, saveFromLink } from "./mac-links.mjs";
+
+/**
+ * Seeing and recording a session's screen through the NoMac API: a screenshot
+ * comes back as base64 JPEG; a recording is started, then stopped, which saves
+ * the MP4 on the Mac and makes a download link for it.
+ */
+const base = id => `/api/v1/mac/sessions/${encodeURIComponent(id)}`;
+
+export async function screenshot(sessionId, { target = "screen", saveTo } = {}) {
+  const shot = await api("POST", `${base(sessionId)}/screenshot`, { body: { target } });
+  if (!saveTo) return shot;
+  const { image_base64: data, ...meta } = shot, file = resolve(saveTo);
+  mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, Buffer.from(data, "base64"));
+  return { ...meta, saved_to: file };
+}
+
+export function startRecording(sessionId, { target = "screen", maxSeconds, path } = {}) {
+  return api("POST", `${base(sessionId)}/recording`, { body: { target, ...(maxSeconds ? { max_seconds: maxSeconds } : {}), ...(path ? { path } : {}) } });
+}
+
+/** Stops the recording; with saveTo, also downloads the video to this machine once its link is ready. */
+export async function stopRecording(sessionId, { saveTo } = {}) {
+  const result = await api("DELETE", `${base(sessionId)}/recording`);
+  if (!saveTo) return result;
+  let link = result.link;
+  for (let checks = 0; link.state === "copying" && checks < 12; checks++) link = await checkLink(link.url, 50);
+  return { ...result, link, ...(link.state === "ready" ? await saveFromLink(link, saveTo) : {}) };
+}

package/src/mac-tools.mjs

@@ -5,7 +5,8 @@ import { readFileSync, statSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { FETCH_SCRIPT, imageType } from "./mac-fetch.mjs";
 import { checkLink, createLink, saveFromLink, uploadThroughLink } from "./mac-links.mjs";
-const MAX_WRITE_BYTES = 3 * 1024 * 1024;
+import { screenshot, startRecording, stopRecording } from "./mac-screen.mjs";
+const MAX_WRITE_BYTES = 3 * 1024 * 1024, MAX_READ_BYTES = 3 * 1024 * 1024;
 const text = value => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
 const session = { type: "string", pattern: "^ses_[A-Za-z0-9_-]{1,80}$" };
 const job = { type: "string", pattern: "^job_[a-f0-9]{40}$" };
@@ -29,7 +30,7 @@ export const MAC_TOOLS = [
     return text({ session_id, url, opened_in_browser: opened, message: opened ? "The desktop opened in the human's browser; they may need to sign in to nomac.app." : "Give the human this link; it opens after they sign in to nomac.app." });
   } },
   { name: "stop_mac", description: "Stop billing by shutting down the VM and deleting its files. Retrieve files first. Poll get_mac_session until cleanup_confirmed; stopping only acknowledges the request.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("DELETE", base(args))) },
-  { name: "exec_mac", description: "Run any argv command in your cloud Mac workspace. Waits up to wait_seconds (default 20, max 50): a command that finishes in time returns its exit_code, stdout and stderr (first 64 KiB each, as text) in this one call, as soon as it finishes. For builds, tests and other slow commands pass wait_seconds: 50. A longer one returns its job ID: poll get_mac_job, then read_mac_output. Reuse request_key and identical arguments after lost responses; never rerun to get output. Use bash -lc explicitly for shell syntax. timeout_seconds defaults to 300 and caps at 600; raise it for slow work such as a first simulator boot (about 90 seconds). A command (argv plus env) can be at most 64 KiB: put files on the Mac with write_mac_file (local_path, up to 2 GiB) or fetch_to_mac.", inputSchema: schema({ session_id: session, request_key: key, argv: { type: "array", items: { type: "string" }, minItems: 1 }, timeout_seconds: { type: "integer", minimum: 1, maximum: 600 }, wait_seconds: { type: "integer", minimum: 0, maximum: 50 } }, ["session_id", "request_key", "argv"]), handler: async ({ session_id, request_key, wait_seconds, ...body }) => text(await api("POST", `${base({ session_id })}/jobs?wait=${wait_seconds ?? 20}`, { body, idempotencyKey: request_key })) },
+  { name: "exec_mac", description: "Run any argv command in your cloud Mac workspace. Waits up to wait_seconds (default 20, max 50): a command that finishes in time returns its exit_code, stdout and stderr (first 64 KiB each, as text) in this one call, as soon as it finishes. For builds, tests and other slow commands pass wait_seconds: 50. A longer one returns its job ID: poll get_mac_job, then read_mac_output. Reuse request_key and identical arguments after lost responses; never rerun to get output. Use bash -lc explicitly for shell syntax. timeout_seconds defaults to 300 and caps at 600; raise it for slow work such as a first simulator boot (about 90 seconds). A command can be at most 64 KiB in total: put files on the Mac with write_mac_file (local_path, up to 2 GiB) or fetch_to_mac.", inputSchema: schema({ session_id: session, request_key: key, argv: { type: "array", items: { type: "string" }, minItems: 1 }, timeout_seconds: { type: "integer", minimum: 1, maximum: 600 }, wait_seconds: { type: "integer", minimum: 0, maximum: 50 } }, ["session_id", "request_key", "argv"]), handler: async ({ session_id, request_key, wait_seconds, ...body }) => text(await api("POST", `${base({ session_id })}/jobs?wait=${wait_seconds ?? 20}`, { body, idempotencyKey: request_key })) },
   { name: "write_mac_file", description: "Write a file on the Mac: local_path uploads a file from this machine, up to 2 GiB, without its content passing through you; or give content as text, or content_base64 for binary, up to 3 MiB. Relative Mac paths are in the session workspace; ~ is the home folder. Creates missing folders and replaces an existing file in one step; set executable for scripts. Safe to repeat. For a whole project use nomac sync; for larger files fetch_to_mac.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024 }, local_path: { type: "string" }, content: { type: "string" }, content_base64: { type: "string" }, executable: { type: "boolean" } }, ["session_id", "path"]), handler: async ({ session_id, path, local_path, content, content_base64, executable }) => {
     const given = [local_path, content, content_base64].filter(v => v !== undefined).length;
     if (given !== 1) return text({ error: { code: "invalid_request", message: "Give exactly one of local_path, content or content_base64." } });
@@ -41,18 +42,42 @@ export const MAC_TOOLS = [
     }
     return text(await api("POST", `${base({ session_id })}/files`, { body: { path, ...(content !== undefined ? { content } : { content_base64 }), executable: Boolean(executable) } }));
   } },
-  { name: "read_mac_file", description: "Read a file on the Mac, up to max_bytes (default 1 MiB, max 4 MiB). save_to writes it to this machine instead of returning it. Otherwise text comes back as text, binary as base64, and PNG, JPEG, GIF and WebP files as an image you can see: for example a Simulator screenshot from `xcrun simctl io booted screenshot shot.png`. Relative Mac paths are in the session workspace. Read-only on the Mac.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024 }, max_bytes: { type: "integer", minimum: 1, maximum: 4194304 }, save_to: { type: "string" } }, ["session_id", "path"]), handler: async ({ session_id, path, max_bytes, save_to }) => {
-    const file = await api("GET", `${base({ session_id })}/files?${new URLSearchParams({ path, ...(max_bytes ? { max_bytes: String(max_bytes) } : {}) })}`);
+  { name: "read_mac_file", description: "Read a file on the Mac, up to max_bytes (default 1 MiB, max 3 MiB). save_to writes the whole file to this machine instead of returning it (larger files come through a download link). Otherwise text comes back as text, binary as base64, and PNG, JPEG, GIF and WebP files as an image you can see, read whole up to 3 MiB. To see the screen or the Simulator, use screenshot_mac. Relative Mac paths are in the session workspace. Read-only on the Mac.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024 }, max_bytes: { type: "integer", minimum: 1, maximum: MAX_READ_BYTES }, save_to: { type: "string" } }, ["session_id", "path"]), handler: async ({ session_id, path, max_bytes, save_to }) => {
+    const read = max => api("GET", `${base({ session_id })}/files?${new URLSearchParams({ path, ...(max ? { max_bytes: String(max) } : {}) })}`);
+    const head = file => file.encoding === "base64" ? imageType(Buffer.from(String(file.content_base64 ?? "").slice(0, 32), "base64")) : undefined;
+    // An image file, or one being saved here, is read whole in one go; others start with the default 1 MiB.
+    let file = await read(max_bytes ?? (save_to || /\.(png|jpe?g|gif|webp)$/i.test(path) ? MAX_READ_BYTES : undefined));
+    // Screenshots are often over the default 1 MiB: read an image whole rather than return part of it as base64.
+    if (file.truncated && max_bytes === undefined && head(file) && file.size <= MAX_READ_BYTES) file = await read(MAX_READ_BYTES);
     const bytes = file.encoding === "utf8" ? Buffer.from(file.content ?? "", "utf8") : Buffer.from(file.content_base64 ?? "", "base64");
     const meta = Object.fromEntries(Object.entries(file).filter(([k]) => !["content", "content_base64"].includes(k)));
     if (save_to) {
+      // Never save part of a file as if it were whole: a file over one read comes through a download link.
+      if (file.truncated && max_bytes === undefined) {
+        let link = await createLink(session_id, { direction: "download", path, wait_seconds: 30 });
+        for (let checks = 0; link.state === "copying" && checks < 12; checks++) link = await checkLink(link.url, 50);
+        if (link.state !== "ready") return text({ ...link, next_step: link.state === "copying" ? "The file is still being copied from the Mac. Call get_mac_file_link with this url and save_to to finish." : "The file could not be copied from the Mac; see error." });
+        return text({ ...meta, truncated: false, ...await saveFromLink(link, save_to) });
+      }
       const target = resolve(save_to); mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, bytes);
       return text({ ...meta, saved_to: target, saved_bytes: bytes.length });
     }
-    const mimeType = !file.truncated && file.encoding === "base64" ? imageType(bytes) : undefined;
-    if (!mimeType) return text(file);
-    return { content: [{ type: "image", data: file.content_base64, mimeType }, { type: "text", text: JSON.stringify({ ...meta, mime_type: mimeType }, null, 2) }] };
+    const mimeType = !file.truncated ? head(file) : undefined;
+    if (mimeType) return { content: [{ type: "image", data: file.content_base64, mimeType }, { type: "text", text: JSON.stringify({ ...meta, mime_type: mimeType }, null, 2) }] };
+    // Part of a binary file as base64 would only fill the context; say how to get it instead.
+    if (file.truncated && max_bytes === undefined && file.encoding === "base64") return text({ ...meta, next_step: head(file)
+      ? "This image is over 3 MiB. Make a smaller copy on the Mac and read that: exec_mac [\"sips\", \"-Z\", \"1568\", \"-s\", \"format\", \"jpeg\", PATH, \"--out\", \"small.jpg\"]. save_to or create_mac_download_link fetches the original."
+      : "This binary file is over 1 MiB. Pass save_to to download it to this machine, or max_bytes to read its first bytes as base64." });
+    return text(file);
   } },
+  { name: "screenshot_mac", description: "See the Mac's screen: returns a screenshot as an image you can look at. target screen (default) is the whole macOS desktop at 1440x900, where image pixels are screen coordinates; target simulator is the booted iOS Simulator's display. Use it to check an app's UI, Xcode or system dialogs and error messages, or what the human sees in open_mac_desktop. Also returns front_app (the app in front) and path, the JPEG on the Mac. save_to writes the image to this machine instead of returning it.", inputSchema: schema({ session_id: session, target: { type: "string", enum: ["screen", "simulator"] }, save_to: { type: "string" } }, ["session_id"]), handler: async ({ session_id, target, save_to }) => {
+    const shot = await screenshot(session_id, { target, saveTo: save_to });
+    if (save_to) return text(shot);
+    const { image_base64: data, ...meta } = shot;
+    return { content: [{ type: "image", data, mimeType: meta.mime_type }, { type: "text", text: JSON.stringify(meta, null, 2) }] };
+  } },
+  { name: "start_mac_recording", description: "Start recording a video of the Mac. target screen (default) records the whole desktop; target simulator records the iOS Simulator's window. Returns at once while it records: then do what should be shown (with exec_mac: launch the app, run UI tests, open a URL) and call stop_mac_recording, which saves the MP4 and can download it here. Stops by itself after max_seconds (default 300, max 1800). One recording at a time per session; a stopped Mac deletes it.", inputSchema: schema({ session_id: session, target: { type: "string", enum: ["screen", "simulator"] }, max_seconds: { type: "integer", minimum: 1, maximum: 1800 }, path: { type: "string", minLength: 1, maxLength: 1024 } }, ["session_id"]), handler: async ({ session_id, target, max_seconds, path }) => text(await startRecording(session_id, { target, maxSeconds: max_seconds, path })) },
+  { name: "stop_mac_recording", description: "Stop the recording started with start_mac_recording and save it as an MP4. Returns its path, length in seconds and size, and a download link for the human (url). save_to downloads the video to this machine. If the recording already reached its max_seconds, returns that video. Safe to repeat.", inputSchema: schema({ session_id: session, save_to: { type: "string" } }, ["session_id"]), handler: async ({ session_id, save_to }) => text(await stopRecording(session_id, { saveTo: save_to })) },
   { name: "fetch_to_mac", description: "Download a URL straight onto the Mac: any size, as fast as the Mac's connection. path is the file to create, or with extract (zip or tar, including .tar.gz) the folder to unpack into. Relative paths are in the session workspace. Waits up to wait_seconds (default 30, max 50) like exec_mac; a longer download keeps running as a job. For a git repository, run git clone with exec_mac instead.", inputSchema: schema({ session_id: session, request_key: key, url: { type: "string", pattern: "^https?://", maxLength: 4096 }, path: { type: "string", minLength: 1, maxLength: 1024 }, extract: { type: "string", enum: ["zip", "tar"] }, wait_seconds: { type: "integer", minimum: 0, maximum: 50 } }, ["session_id", "request_key", "url", "path"]), handler: async ({ session_id, request_key, url, path, extract, wait_seconds }) => text(await api("POST", `${base({ session_id })}/jobs?wait=${wait_seconds ?? 30}`, { body: { argv: ["/bin/bash", "-c", FETCH_SCRIPT], env: { NOMAC_URL: url, NOMAC_PATH: path, NOMAC_EXTRACT: extract ?? "" }, timeout_seconds: 600 }, idempotencyKey: request_key })) },
   { name: "create_mac_upload_link", description: "Get a link that puts one file of up to 2 GiB on the Mac at path. With local_path, the file is uploaded from this machine now and placed on the Mac. Otherwise give url to the human (open: true opens it in this machine's browser): they choose a file in the browser and it lands on the Mac, no account needed. Then call get_mac_file_link until state is placed. With extract (zip or tar), path is the folder to unpack into. The link takes one file and expires after expires_in_minutes (default 60, max 1440).", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024 }, local_path: { type: "string" }, executable: { type: "boolean" }, extract: { type: "string", enum: ["zip", "tar"] }, expires_in_minutes: { type: "integer", minimum: 1, maximum: 1440 }, open: { type: "boolean", default: false, description: "Open the link in this machine's browser for the human." } }, ["session_id", "path"]), handler: async ({ session_id, path, local_path, executable, extract, expires_in_minutes, open }) => {
     if (local_path !== undefined) return text(await uploadThroughLink(session_id, local_path, { path, executable: Boolean(executable), extract }));

package/src/mcp-args.mjs

@@ -0,0 +1,64 @@
+/**
+ * Checks MCP tool arguments against the tool's JSON Schema before calling the
+ * API, so a missing or misnamed argument (job_id sent as id) is named to the
+ * agent instead of becoming a request for /jobs/undefined.
+ *
+ * Deliberately lenient where being strict could break a call that works today:
+ * unknown extra keys are ignored and a number may arrive as a numeric string.
+ * Returns the first problem as a sentence, or undefined when the arguments fit.
+ */
+export function argumentProblem(schema, value, path = "") {
+  if (!schema || typeof schema !== "object") return undefined;
+  const name = path || "arguments";
+  if (Array.isArray(schema.anyOf) && !schema.anyOf.some(option => argumentProblem(option, value, path) === undefined)) {
+    return argumentProblem(schema.anyOf[0], value, path) ?? `${name} does not match any allowed form.`;
+  }
+  if (value === undefined) return undefined;
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) return `${name} must be one of ${schema.enum.map(v => JSON.stringify(v)).join(", ")}.`;
+  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+  if (types.length && !types.some(type => fits(type, value))) return `${name} must be ${types.map(article).join(" or ")}.`;
+  if (typeof value === "string" || (typeof value === "number" && types.some(t => t === "integer" || t === "number"))) {
+    const number = typeof value === "number" ? value : Number(value);
+    if (types.some(t => t === "integer" || t === "number")) {
+      if (typeof schema.minimum === "number" && number < schema.minimum) return `${name} must be at least ${schema.minimum}.`;
+      if (typeof schema.maximum === "number" && number > schema.maximum) return `${name} must be at most ${schema.maximum}.`;
+    }
+  }
+  if (typeof value === "string" && types.includes("string")) {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) return `${name} must be at least ${schema.minLength} characters.`;
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength) return `${name} must be at most ${schema.maxLength} characters.`;
+    if (typeof schema.pattern === "string" && !matches(schema.pattern, value)) return `${name} has the wrong format (expected ${schema.pattern}).`;
+  }
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) return `${name} needs at least ${schema.minItems} item${schema.minItems === 1 ? "" : "s"}.`;
+    if (typeof schema.maxItems === "number" && value.length > schema.maxItems) return `${name} can have at most ${schema.maxItems} items.`;
+    if (schema.items) for (let i = 0; i < value.length; i++) { const problem = argumentProblem(schema.items, value[i], `${name}[${i}]`); if (problem) return problem; }
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    for (const required of schema.required ?? []) if (value[required] === undefined) return `${path ? `${path}.` : ""}${required} is required.`;
+    for (const [key, property] of Object.entries(schema.properties ?? {})) {
+      const problem = argumentProblem(property, value[key], path ? `${path}.${key}` : key);
+      if (problem) return problem;
+    }
+  }
+  return undefined;
+}
+
+/** A pattern this checker cannot compile is the server's to enforce, never a reason to refuse a call. */
+function matches(pattern, value) {
+  try { return new RegExp(pattern).test(value); } catch { return true; }
+}
+const numeric = value => typeof value === "string" && /^-?\d+(\.\d+)?$/.test(value);
+function fits(type, value) {
+  switch (type) {
+    case "string": return typeof value === "string";
+    case "integer": return (typeof value === "number" && Number.isInteger(value)) || (numeric(value) && Number.isInteger(Number(value)));
+    case "number": return (typeof value === "number" && Number.isFinite(value)) || numeric(value);
+    case "boolean": return typeof value === "boolean";
+    case "array": return Array.isArray(value);
+    case "object": return value !== null && typeof value === "object" && !Array.isArray(value);
+    case "null": return value === null;
+    default: return true;
+  }
+}
+const article = type => ({ integer: "an integer", object: "an object", array: "an array", null: "null" })[type] ?? `a ${type}`;

package/src/mcp.mjs

@@ -7,7 +7,8 @@ import { readFileSync } from "node:fs";
 const lifecycleSchemas = JSON.parse(readFileSync(new URL("./lifecycle-schemas.json", import.meta.url), "utf8"));
 import { createInterface } from "node:readline";
 import { api } from "./api.mjs";
-import { mcpClientName, mcpContext, toolScope } from "./client-info.mjs";
+import { CLI_VERSION, mcpClientName, mcpContext, toolScope } from "./client-info.mjs";
+import { argumentProblem } from "./mcp-args.mjs";
 import { loadProjectState, saveProjectState } from "./config.mjs";
 import { packTarball } from "./pack.mjs";
 import { uploadSourceSnapshot } from "./upload.mjs";
@@ -15,6 +16,15 @@ import { uploadStoreAsset } from "./store-upload.mjs";
 import { MAC_TOOLS } from "./mac-tools.mjs";
 
 const PROTOCOL_FALLBACK = "2025-06-18";
+/** How the tools fit together, sent once at initialize (the hosted server sends the same kind of text). */
+const INSTRUCTIONS = [
+  "NoMac gives you a cloud Mac with Xcode, billed from prepaid credit ($0.80 an hour, by the minute).",
+  "Typical flow: get_mac_credits, start_mac, poll get_mac_session until ready, put code there (exec_mac with git clone, write_mac_file, fetch_to_mac, create_mac_upload_link), run exec_mac, get results with read_mac_file or create_mac_download_link, then stop_mac.",
+  "exec_mac returns a quick command's output in the same call; pass wait_seconds: 50 for builds and tests. A command still running comes back as a job: poll get_mac_job with its job_id, then read_mac_output.",
+  "Never rerun a command to get its output; after a lost response, repeat the call with the same request_key and arguments.",
+  "Write files with write_mac_file, not heredocs in exec_mac: a command is at most 64 KiB.",
+  "Always stop_mac when finished, after reading any output you need, so credit is not spent on an idle Mac.",
+].join(" ");
 
 const text = (obj) => ({
   content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }],
@@ -25,7 +35,7 @@ async function resolveProjectId(args) {
   if (args?.project_id) return args.project_id;
   const state = loadProjectState(args?.directory ?? process.cwd());
   if (state.project_id) return state.project_id;
-  throw new Error("no project here — run push_project first (or pass project_id)");
+  throw new Error("no project here: run push_project first (or pass project_id)");
 }
 
 export const TOOLS = [
@@ -126,7 +136,7 @@ export const TOOLS = [
   {
     name: "build",
     description:
-      "Start a build. workflow=release (signed, uploads to TestFlight; costs one build from the plan quota) or smoke (unsigned compile check, fastest way to verify the project builds on macOS). Returns a build_id — poll with status.",
+      "Start a build. workflow=release (signed, uploads to TestFlight; costs one build from the plan quota) or smoke (unsigned compile check, fastest way to verify the project builds on macOS). Returns a build_id; poll it with status.",
     inputSchema: {
       type: "object",
       properties: {
@@ -415,7 +425,8 @@ export async function runMcpServer() {
           reply({
             protocolVersion: params?.protocolVersion ?? PROTOCOL_FALLBACK,
             capabilities: { tools: {} },
-            serverInfo: { name: "nomac", version: "0.1.0" },
+            serverInfo: { name: "nomac", version: CLI_VERSION },
+            instructions: INSTRUCTIONS,
           });
           break;
         case "notifications/initialized":
@@ -432,6 +443,11 @@ export async function runMcpServer() {
         case "tools/call": {
           const tool = TOOLS.find((t) => t.name === params?.name);
           if (!tool) return fail(-32602, `unknown tool: ${params?.name}`);
+          const problem = argumentProblem(tool.inputSchema, params?.arguments ?? {});
+          if (problem) {
+            reply({ content: [{ type: "text", text: JSON.stringify({ error: { code: "invalid_arguments", message: `${problem} Nothing was sent to the Mac; fix the arguments and call ${tool.name} again.` } }, null, 2) }], isError: true });
+            break;
+          }
           try {
             reply(await toolScope.run({ tool: tool.name }, () => tool.handler(params?.arguments ?? {})));
           } catch (err) {

package/src/session-ssh.mjs

@@ -35,7 +35,9 @@ export function multiplexArgs(session, { platform = process.platform, home = hom
   const dir = join(home, ".nomac", "cm");
   const name = createHash("sha256").update(`${session.id}:${session.generation ?? 0}`).digest("hex").slice(0, 20);
   const path = join(dir, name);
-  if (path.length > 100) return off; // Unix socket paths are limited to about 104 bytes
+  // macOS socket paths hold 103 bytes, and ssh first binds a temporary socket at the path
+  // plus a 17-byte suffix (".XXXXXXXXXXXXXXXX"): longer paths make ssh exit 255.
+  if (Buffer.byteLength(path) > 86) return off;
   try { mkdirSync(dir, { recursive: true, mode: 0o700 }); chmodSync(dir, 0o700); } catch { return off; }
   return ["-o", "ControlMaster=auto", "-o", `ControlPath=${path}`, "-o", "ControlPersist=120"];
 }