@nomac/cli 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomac/cli",
-  "version": "0.7.0",
+  "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.

package/src/cli.mjs

@@ -30,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) {
@@ -51,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":
@@ -84,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();
     }
@@ -149,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}`);
@@ -162,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");
@@ -208,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

@@ -121,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;
     }
@@ -135,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. */
@@ -172,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) => {
@@ -217,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]}`;
@@ -233,6 +256,10 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     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);
@@ -248,8 +275,12 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
     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;
-      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" : ""}).\nShare it: ${saved.link.url} (works until ${saved.link.expires_at.slice(11, 16)} UTC, also after the Mac stops)`);
+      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]");

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-tools.mjs

@@ -6,7 +6,7 @@ import { dirname, resolve } from "node:path";
 import { FETCH_SCRIPT, imageType } from "./mac-fetch.mjs";
 import { checkLink, createLink, saveFromLink, uploadThroughLink } from "./mac-links.mjs";
 import { screenshot, startRecording, stopRecording } from "./mac-screen.mjs";
-const MAX_WRITE_BYTES = 3 * 1024 * 1024, MAX_READ_BYTES = 4 * 1024 * 1024;
+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}$" };
@@ -30,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." } });
@@ -42,7 +42,7 @@ 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, read whole up to 4 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 }) => {
+  { 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.
@@ -52,6 +52,13 @@ export const MAC_TOOLS = [
     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 });
     }
@@ -59,7 +66,7 @@ export const MAC_TOOLS = [
     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 4 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 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);
   } },
@@ -69,7 +76,7 @@ export const MAC_TOOLS = [
     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 booted iOS Simulator's display at full resolution. 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: "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 }) => {

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"];
 }