@nomac/cli 0.7.0 → 0.9.0

package/bin/nomac.mjs

@@ -5,6 +5,7 @@ main(process.argv.slice(2)).catch((err) => {
   const args = process.argv.slice(2);
   if (["start", "sync", "pull", "stop", "session", "transport", "exec", "job", "output"].includes(args[0]) && args.includes("--json")) {
     console.error(JSON.stringify({ error: { code: err?.code ?? "session_error", message: err?.friendly ?? err?.message ?? String(err), ...(err?.details ? { details: err.details } : {}) } }));
-  } else console.error(err?.friendly ?? err?.message ?? String(err));
+  // An empty friendly message means the command already printed why it failed.
+  } else if (err?.friendly !== "") console.error(err?.friendly ?? err?.message ?? String(err));
   process.exit(err?.exitCode ?? 1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomac/cli",
-  "version": "0.7.0",
+  "version": "0.9.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.
@@ -44,8 +44,9 @@ with the same request key.
 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. See the screen with `nomac screenshot` (saves
+CLI sync sends every file (.env and keys included) and symlinks as links, and
+skips dependency and build folders, .git and folders .gitignore lists; a `!`
+line in .nomacignore sends any of them. It preserves remote extra files. 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
@@ -58,6 +59,36 @@ Pipe xcodebuild through `xcbeautify`. Persistent disks are not currently offered
 Report failures using `report_issue` with `session_id`, optional `job_id` and
 a description without secrets. Read https://nomac.app/llms.txt for full limits.
 
+## Secrets, signing and shipping
+
+Never ask for a secret in the chat. `nomac secrets request NAME --description
+TEXT` (MCP `request_secret`) gives the human a link to enter it; they can also
+run `nomac secrets set NAME` themselves. Every Mac receives the account's
+secrets as variables and files, masked in command output; `nomac secrets
+install` refreshes a running Mac.
+
+The human connects Apple once at https://nomac.app/apple; the App Store
+Connect key stays on NoMac's server. Then, on the Mac:
+
+1. `nomac sign [path]` (MCP `set_up_signing`) makes and installs the App Store
+   profiles the project needs and prints the files, the reserved build number
+   and the xcodebuild, Flutter and fastlane commands. The project is unchanged;
+   build with your own tools.
+2. `nomac testflight path/to/App.ipa` (MCP `send_to_testflight`) puts it on
+   TestFlight. Relay the human's answer to Apple's encryption question (asked
+   once per app), never guess.
+3. `nomac publish App.ipa --whats-new TEXT` stages the App Store version and
+   lists Apple's blockers; submit with the printed `--confirm` command only
+   after the human approves. MCP: `publish` with the send's project_id and
+   build_id.
+4. Mac apps: sign with the Developer ID certificate, `--options runtime
+   --timestamp`, then `nomac notarize App.app` (MCP `notarize`) notarizes and
+   staples it.
+
+A step only a person can take (creating the app in App Store Connect,
+agreements, an App Group) comes back as needs_human with its link: give it to
+the human, then call again.
+
 ## Builder (existing subscribers only)
 
 The separate iOS Builder publishing product is closed to new subscriptions.

package/src/api.mjs

@@ -65,13 +65,15 @@ export async function api(method, path, { body, raw, idempotencyKey } = {}) {
     throw new CliError(`API returned non-JSON (HTTP ${res.status})`, "The response could not be read. Reconcile the operation before retrying; reuse its request_key.", res.status, "bad_response", { code: "bad_response", ...(idempotencyKey ? { request_key: idempotencyKey } : {}) });
   }
   if (!res.ok) {
-    const err = json?.error ?? {};
+    // Some answers carry more beside the error, such as publish's blockers and findings.
+    const { error, ...beside } = json && typeof json === "object" && !Array.isArray(json) ? json : {};
+    const err = error && typeof error === "object" ? error : {};
     throw new CliError(
       `HTTP ${res.status} ${err.code ?? ""}`,
       err.message ?? `API error (HTTP ${res.status})`,
       res.status,
       err.code,
-      { ...err, ...(idempotencyKey ? { request_key: idempotencyKey } : {}) },
+      { ...beside, ...err, ...(idempotencyKey ? { request_key: idempotencyKey } : {}) },
     );
   }
   return json;

package/src/cli.mjs

@@ -23,6 +23,11 @@ Use it:
   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
+  nomac secrets                variables and files every Mac receives (nomac secrets --help)
+  nomac sign [path]            set up App Store signing for the project on the Mac
+  nomac testflight app.ipa     send a signed .ipa on the Mac to TestFlight
+  nomac publish app.ipa        submit it for App Review (--confirm sends it)
+  nomac notarize App.app       notarize a Developer ID-signed Mac app and staple it
 
 Agents:
   nomac mcp                    MCP server for Claude Code, Codex, Cursor and others
@@ -30,6 +35,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 +78,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":
@@ -75,6 +105,31 @@ export async function main(argv) {
       // A Mac you own reports through session status.
       return cmd === "status" ? sessionCommand("session", ["status", ...rest]) : sessionCommand(cmd, rest);
     }
+    case "sign": {
+      const { signCommand } = await import("./sign.mjs");
+      const { sessionStore } = await import("./session-store.mjs");
+      return signCommand(rest, { store: sessionStore() });
+    }
+    case "testflight": {
+      const { testflightCommand } = await import("./testflight.mjs");
+      const { sessionStore } = await import("./session-store.mjs");
+      return testflightCommand(rest, { store: sessionStore() });
+    }
+    case "publish": {
+      const { publishCommand } = await import("./publish.mjs");
+      const { sessionStore } = await import("./session-store.mjs");
+      return publishCommand(rest, { store: sessionStore() });
+    }
+    case "notarize": {
+      const { notarizeCommand } = await import("./notarize.mjs");
+      const { sessionStore } = await import("./session-store.mjs");
+      return notarizeCommand(rest, { store: sessionStore() });
+    }
+    case "secrets": {
+      const { secretsCommand } = await import("./secrets.mjs");
+      const { sessionStore } = await import("./session-store.mjs");
+      return secretsCommand(rest, { store: sessionStore() });
+    }
     case "login": {
       const key = rest[0];
       if (key) {
@@ -84,19 +139,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 +211,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 +224,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 +270,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. */
@@ -168,11 +186,16 @@ export async function hostedSessionCommand(command, argv, { store = sessionStore
   const wait = ["start", "stop"].includes(command) ? integer(values.wait, command === "start" ? 300 : 60, 0, command === "start" ? 600 : 300) : 0;
   if (command === "start" && values["request-key"] !== undefined && !validRequestKey(values["request-key"])) throw new CliError("Use a request key of 8–128 letters, digits, underscores, periods, colons or hyphens.");
   const output = result => {
+    // Sync, pull and the other commands answer with their own result, which has no session.
+    if (values.json || !["start", "stop"].includes(command)) { print(JSON.stringify(result, null, 2)); return result; }
     const billing = result.session?.billing;
     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(`${result.session.id}: ${result.session.state}\n${next}\n${usage}`);
     return result;
   };
   const saveView = (local, view) => {
@@ -217,9 +240,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 +258,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 +277,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}$" };
@@ -22,7 +22,13 @@ export const MAC_TOOLS = [
   { name: "get_mac_credits", description: "Read the prepaid Mac credit balance: spendable dollars, spendable_seconds (how long a Mac can run on it), amounts held by a running session, pricing (including bonus_tiers for bigger purchases), recent purchases and first_purchase (true until the first paid top-up). Credit never expires. If spendable_seconds is below what the task needs, call get_mac_checkout.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/credits")) },
   { name: "start_mac", description: "Allocate a full cloud Mac VM, billed from prepaid credit at $0.80 an hour by the minute. If it returns insufficient_credit, call get_mac_checkout, have the human pay, then retry with the same request_key. Supply a stable request_key; SSH public_key is optional for HTTPS-only agents; reuse both after a lost response. Inspect the returned offer and limits. Poll get_mac_session until ready. No project pipeline is imposed; stop_mac deletes the VM and files.", inputSchema: schema({ public_key: { type: "string" }, request_key: key, limits: { type: "object", properties: { max_duration_seconds: { type: "integer", minimum: 60, maximum: 28800 }, idle_timeout_seconds: { type: "integer", minimum: 60, maximum: 3600 }, spend_cap_microunits: { type: "string", pattern: "^[1-9][0-9]{0,17}$" } }, additionalProperties: false } }, ["request_key"]), handler: async ({ request_key, ...body }) => text(await api("POST", "/api/v1/mac/sessions", { body, idempotencyKey: request_key })) },
   { name: "list_mac_sessions", description: "Find existing Mac sessions, including after losing a response. Shows state, cost, limits and cleanup.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/mac/sessions")) },
-  { name: "get_mac_session", description: "Read live Mac allocation state, cost, funded time and cleanup confirmation. queued/provisioning means wait; stopping is not yet confirmed cleanup.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("GET", base(args))) },
+  { name: "get_mac_session", description: "Read live Mac allocation state, cost, funded time and cleanup confirmation, and once ready the credentials installed on it (secrets, signing identities and profiles, by name and path, never values). queued/provisioning means wait; stopping is not yet confirmed cleanup.", inputSchema: schema({ session_id: session }, ["session_id"]), handler: async args => text(await api("GET", base(args))) },
+  { name: "list_secrets", description: "List the account's secrets by name: variables (set in every shell and command on the Mac) and files (with their path on the Mac), whether every Mac receives them or only when asked, sizes, and secrets an agent asked for that the person has not entered yet. Values are never returned.", inputSchema: schema({}), handler: async () => text(await api("GET", "/api/v1/secrets")) },
+  { name: "request_secret", description: "Get a link where the person enters a secret in their browser, so its value never passes through this chat: an API token, a .env value, a .p12 certificate or a config file. kind variable is one line of text, set as an environment variable on the Mac; kind file is stored at destination (under the home folder, like ~/.netrc; default ~/.nomac/secrets/<name>). Give the person the url. Then list_secrets shows it, new Macs receive it, and install_secrets puts it on a running Mac. With a shell on this machine, the person can also run nomac secrets set NAME themselves. Never ask for a secret in the chat.", inputSchema: schema({ name: { type: "string", minLength: 1, maxLength: 128 }, kind: { type: "string", enum: ["variable", "file"] }, description: { type: "string", minLength: 1, maxLength: 500, description: "What the person should enter and why; shown to them" }, destination: { type: "string", maxLength: 256 }, delivery: { type: "string", enum: ["every_mac", "on_request"] } }, ["name", "kind", "description"]), handler: async body => text(await api("POST", "/api/v1/secrets/requests", { body })) },
+  { name: "set_up_signing", description: "Set up App Store signing for a project on the Mac, with the App Store Connect key kept on NoMac's server: reads the project at path (its scheme, app and every extension, with entitlements), registers missing bundle IDs, switches on the capabilities Apple's API can, makes the App Store profiles, and installs them with the account's certificate in a keychain on the Mac. The project never changes. Returns a build settings file (.xcconfig) and export options with the exact xcodebuild, Flutter and fastlane commands. Creates a distribution certificate at Apple only when the account has none. Expo and Capacitor apps need their ios folder first. A step only a person can take comes back as needs_human with its link.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024, description: "The project folder on the Mac, relative to the workspace" }, scheme: { type: "string", minLength: 1, maxLength: 256 }, container: { type: "string", minLength: 1, maxLength: 1024 }, issuer_id: { type: "string", maxLength: 64 } }, ["session_id"]), handler: async ({ session_id, ...body }) => text(await api("POST", `${base({ session_id })}/signing`, { body })) },
+  { name: "send_to_testflight", description: "Send a signed .ipa on the Mac to TestFlight, with the App Store Connect key kept on NoMac's server: NoMac creates the upload at Apple and the Mac sends only the file. Apple then processes the build, usually for 5 to 15 minutes with no Mac needed, and NoMac sets the app's export-compliance answer and What to Test and puts it on TestFlight for the internal testers. Repeat the call with the returned request_key to follow it: sending, processing, on_testflight or failed. Once on_testflight, publish with the returned project_id and build_id submits it for App Review. Apple asks once per app whether it uses encryption beyond HTTPS and Apple's own: pass the person's answer as uses_non_exempt_encryption, never a guess. A build number Apple already has comes back with the next free one. A step only a person can take, such as creating the app in App Store Connect, comes back as needs_human with its link.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024, description: "The signed .ipa on the Mac, relative to the workspace or absolute" }, notes: { type: "string", minLength: 1, maxLength: 4000, description: "What to Test, shown to testers" }, uses_non_exempt_encryption: { type: "boolean", description: "The person's answer, asked once per app: does it use encryption beyond HTTPS and Apple's own?" }, issuer_id: { type: "string", maxLength: 64 }, request_key: { ...key, description: "Repeat with the request_key from the first answer to follow that send" }, wait_seconds: { type: "integer", minimum: 0, maximum: 50, description: "Wait up to this long for progress (50 while following)" } }, ["session_id", "path"]), handler: async ({ session_id, ...body }) => text(await api("POST", `${base({ session_id })}/testflight`, { body })) },
+  { name: "notarize", description: "Notarize a Developer ID-signed Mac app, disk image or installer on the Mac (.app, .dmg, .pkg or .zip), with the App Store Connect key kept on NoMac's server: the Mac zips an .app and sends the file to Apple with temporary credentials for this one submission. Apple checks it, usually for a few minutes, then the Mac staples the ticket so it opens without a warning, even offline. Repeat the call with the returned request_key to follow it: preparing, uploading, in_progress, stapling, then accepted, invalid or rejected with Apple's issues. Sign first with the Developer ID Application certificate (the person uploads it at nomac.app/apple), the hardened runtime and a secure timestamp: codesign --force --options runtime --timestamp --sign \"Developer ID Application: …\". Keep the Mac running until it is stapled.", inputSchema: schema({ session_id: session, path: { type: "string", minLength: 1, maxLength: 1024, description: "The .app, .dmg, .pkg or .zip on the Mac, relative to the workspace or absolute" }, issuer_id: { type: "string", maxLength: 64 }, request_key: { ...key, description: "Repeat with the request_key from the first answer to follow that notarization" }, wait_seconds: { type: "integer", minimum: 0, maximum: 50, description: "Wait up to this long for progress (50 while following)" } }, ["session_id", "path"]), handler: async ({ session_id, ...body }) => text(await api("POST", `${base({ session_id })}/notarize`, { body })) },
+  { name: "install_secrets", description: "Install the account's secrets and signing identities on a running Mac now: every-Mac secrets, the on-request secrets named in names, and what the Mac already has; a deleted secret is removed. Macs receive every-Mac secrets on their own when they become ready, so call this after the person adds or changes one.", inputSchema: schema({ session_id: session, names: { type: "array", items: { type: "string", minLength: 1, maxLength: 128 }, maxItems: 100 } }, ["session_id"]), handler: async ({ session_id, names = [] }) => text(await api("POST", `${base({ session_id })}/secrets`, { body: { names } })) },
   { name: "open_mac_desktop", description: "Open the Mac's full macOS desktop in the human's browser on this machine, with mouse and keyboard and nothing to install. Use it when the human wants to see or click something on the Mac, for example Xcode, the Simulator or a sign-in window. The session must be ready. If opened_in_browser is false, give the human the returned url; it opens after they sign in to nomac.app. The session stays busy while the desktop is open and the page disconnects after 15 minutes without input. To show the iOS Simulator there, boot a device with simctl, then run open \"$(xcode-select -p)/Applications/Simulator.app\" with exec_mac. macOS has no RDP.", inputSchema: schema({ session_id: session, open: { type: "boolean", default: true, description: "Open the link in this machine's browser." } }, ["session_id"]), handler: async ({ session_id, open = true }) => {
     const view = await api("GET", base({ session_id }));
     if (view?.session?.state !== "ready") return text({ error: { code: "session_not_ready", message: "The Mac is not ready. Wait until get_mac_session shows ready, then call open_mac_desktop again." } });
@@ -30,7 +36,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 +48,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 +58,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 +72,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 +82,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,16 @@ 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.",
+  "Shipping without the Apple key on the Mac: set_up_signing on the project returns the files and commands that sign a build with the agent's own tools; send_to_testflight sends the signed .ipa to TestFlight; publish submits it for App Review; notarize notarizes and staples a Developer ID-signed Mac app. Never ask for a secret in the chat: request_secret gives the human a link, and every Mac receives the account's secrets.",
+  "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 +36,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 +137,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: {
@@ -288,12 +299,12 @@ export const TOOLS = [
   {
     name: "publish",
     description:
-      "Submit for App Store review (3-step reviewSubmissions). Requires confirm:true with authorization for this app/version; run once without confirm first to see the staged result + any Apple blockers. Costs nothing; the review decision takes ~1-3 days. On pending, repeat unchanged arguments with the returned request_key; get_store_operation recovers a lost response.",
+      "Submit for App Store review (3-step reviewSubmissions). Takes the app's newest build on TestFlight, or build_id: a Builder build or one sent with send_to_testflight, whose answer gives project_id and build_id. Requires confirm:true with authorization for this app/version; run once without confirm first to see the staged result + any Apple blockers. Costs nothing; the review decision takes ~1-3 days. On pending, repeat unchanged arguments with the returned request_key; get_store_operation recovers a lost response.",
     inputSchema: {
       type: "object",
       properties: {
         project_id: { type: "string" },
-        build_id: { type: "string", description: "Exact nomac release build to attach" },
+        build_id: { type: "string", description: "Exact NoMac build (bld_…) to attach, from send_to_testflight or build" },
         asc_submission_id: { type: "string", description: "Exact Apple submission from get_review" },
         resolve_rejection: { type: "boolean", default: false, description: "Assert this version rejection was fixed; mark its item ready for review" },
         confirm: { type: "boolean", default: false },
@@ -415,7 +426,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 +444,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) {