zas-agent 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-03
+
+### Fixed
+
+- The `claude mcp add` and `codex mcp add` lines the terminal prints after
+  pairing quote the `--` separator. In PowerShell the npm-installed `claude`
+  and `codex` commands are script shims, and PowerShell kept a bare `--` for
+  itself, so `claude mcp add` refused `-y` as an unknown option.
+
+## [0.2.0] - 2026-09-03
+
+### Changed
+
+- Pairing no longer prints a code to type. The terminal listens on
+  `127.0.0.1`, the approval page hands it a one-time claim code, and the
+  agent is created only when the terminal claims. A page that cannot reach
+  the terminal shows the code, and the terminal asks for it. `pair` opens
+  the browser; `--no-open` and `ZAS_NO_OPEN=1` keep it closed.
+- `zas_pair` takes an optional `code` for the case where the page shows one.
+- Older servers are not supported by this release: the claim route is
+  required. Older CLIs keep working against the server.
+
 ## [0.1.1] - 2026-09-02
 
 ### Changed
@@ -36,6 +58,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   two separate identities that cannot read each other's keys.
 - Install snippets for Claude Code and Codex, printed by `zas-agent pair`.
 
-[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/soke1556/zas-agent/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/soke1556/zas-agent/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/soke1556/zas-agent/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/soke1556/zas-agent/releases/tag/v0.1.0

package/README.md

@@ -46,13 +46,13 @@ npx -y zas-agent pair --profile claude-code
 **Claude Code**
 
 ```
-claude mcp add zas -- npx -y zas-agent --profile claude-code
+claude mcp add zas "--" npx -y zas-agent --profile claude-code
 ```
 
 **Codex**
 
 ```
-codex mcp add zas -- npx -y zas-agent --profile codex
+codex mcp add zas "--" npx -y zas-agent --profile codex
 ```
 
 Codex by hand, if you would rather edit `~/.codex/config.toml`:
@@ -63,28 +63,37 @@ command = "npx"
 args = ["-y", "zas-agent", "--profile", "codex"]
 ```
 
-### What pairing prints
+### What pairing does
 
-`zas-agent pair` mints the key pair, registers the public halves, and waits. The
-terminal shows four things:
+`zas-agent pair` mints the key pair, registers the public halves, opens the
+approval page in your browser, and waits. The terminal shows:
 
 ```
 Open this page signed in to your Zas account:
-  https://zas.red/agents/pair?p=...
-Code:        ABCD-EFGH
+  https://zas.red/agents/pair?p=...#port=53211
 Fingerprint: 1a2b 3c4d 5e6f 7a8b
 Waiting for approval… (expires in 10 minutes)
 ```
 
-Open the link signed in to your Zas account. Check that the fingerprint on the
-page is the one in your terminal, name the agent, and tick the channels it may
-use — sending is the default, reading is a separate switch. The code is eight
-characters in two groups, and it is what you compare before you approve. The
-pairing is good for ten minutes; past that, run the command again.
-
-You can also start the flow from the coding agent with the `zas_pair` tool: the
-first call hands back the URL and the code, and a later call says whether the
-approval landed.
+Signed in, name the agent and tick the channels it may use — sending is the
+default, reading is a separate switch — and approve. Approval creates
+nothing by itself: the page hands a one-time claim code to this terminal
+over `127.0.0.1` (the port in the link), and the agent exists only once the
+terminal claims with that code and the secret it holds. A link that reached
+somebody else is approved on their machine, where nothing listens, and
+expires with nothing created.
+
+If the browser cannot reach the terminal — the link was opened on a phone,
+or the browser refused the local connection — the page shows the code and
+the terminal asks for it. Type it there and nowhere else: with that code,
+another terminal that started a pairing could claim it. Pass `--no-open` or
+set `ZAS_NO_OPEN=1` to keep the browser closed; the link is printed either
+way. The pairing is good for ten minutes before approval and five after;
+past that, run the command again.
+
+You can also start the flow from the coding agent with the `zas_pair` tool:
+the first call hands back the URL, a later call says whether the approval
+landed, and if the page shows a code, a call with `code` claims with it.
 
 ## Why you can trust it
 
@@ -98,9 +107,11 @@ source, the sentence says so.
   account key, and the key-derivation service refuses account-key derivation to
   an agent *(server-side)*.
 - **You approve it, and you choose the channels.** Pairing never
-  auto-approves. The approval page shows the harness, the host, the key
-  fingerprint and the code, and you compare the code with your terminal before
-  anything is granted.
+  auto-approves. The approval page shows the harness, the host and the key
+  fingerprint, and nothing exists until the terminal that started the
+  pairing claims it with a code only the approving page received
+  *(server-side)*. A pairing link sent to you by someone else creates
+  nothing on your account.
 - **It holds one key per granted channel, and no key for any other.** Each
   grant carries that channel's key sealed to the agent's X25519 public key. A
   channel you did not grant has no key here to decrypt with, and the server
@@ -193,7 +204,7 @@ stack trace.
 | Tool | What it does |
 | --- | --- |
 | `zas_status` | Says whether this machine is paired with a Zas account, and lists the owner's channels this agent may send to or read from. |
-| `zas_pair` | Pairs this machine with a Zas account. The first call returns a URL and a code for the owner to approve; a later call says whether they did. |
+| `zas_pair` | Pairs this machine with a Zas account. The first call returns a URL for the owner to open; a later call says whether they approved. If the page shows a code, a call with `code` claims with it. |
 | `zas_send_file` | Sends a file from this machine into one of the owner's channels. Returns the item id, or a job id when the upload takes longer than a minute. |
 | `zas_send_note` | Sends a note — plain text, or a code snippet with its language — into one of the owner's channels. |
 | `zas_list_items` | Lists the most recent items in one of the owner's channels. Needs a grant that includes reading. |
@@ -232,8 +243,8 @@ crash mid-write cannot leave half a file behind:
 
 - `identity.json` — the agent uid, the owner uid, the name, and the two key
   pairs. Back it up like a private key, or delete it and pair again.
-- `pending.json` — a pairing that has not been approved yet. Removed on
-  approval, and on a pairing that expired or was cancelled.
+- `pending.json` — a pairing that has not been claimed yet. Removed on
+  completion, and on a pairing that expired or was cancelled.
 - `grants.json` — a one-minute cache of `GET /v1/agents/me`: which channels,
   and the sealed key for each. The channel name stays encrypted here.
   Disposable.

package/dist/cli.js

@@ -3,6 +3,7 @@ import { createRequire as __cr } from "node:module"; const require = __cr(import
 
 // src/cli.ts
 import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -76,6 +77,17 @@ var AGENT_TOKEN_TTL_SEC = 3600;
 var AGENT_LAST_SEEN_BUCKET_MS = 5 * 60 * 1e3;
 var AGENT_HOST_MAX = 60;
 var AGENT_CHALLENGE_DOMAIN = "ZAS-AGENT-CHALLENGE-V1";
+var AGENT_PAIRING_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+var AGENT_PAIRING_CODE_LENGTH = 8;
+var AGENT_CLAIM_TTL_MS = 5 * 60 * 1e3;
+function keepPairingCodeChars(raw) {
+  return raw.toUpperCase().split("").filter((c) => AGENT_PAIRING_CODE_ALPHABET.includes(c)).join("");
+}
+function normalizePairingCode(raw) {
+  if (typeof raw !== "string") return "";
+  const kept = keepPairingCodeChars(raw);
+  return kept.length === AGENT_PAIRING_CODE_LENGTH ? kept : "";
+}
 var text = new TextEncoder();
 function field(bytes) {
   const length = new Uint8Array(4);
@@ -156,6 +168,11 @@ var SENTENCES = {
   duplicate: "That item is already in the channel.",
   pairing_expired: "The pairing expired. Run \u201Czas-agent pair\u201D again.",
   pairing_cancelled: "The owner cancelled the pairing.",
+  claim_mismatch: "The code does not match. Try again.",
+  pairing_not_approved: "Nobody has approved this pairing yet.",
+  pairing_claimed: "This pairing was already claimed. Pair again with \u201Czas-agent pair\u201D.",
+  agent_limit: "The account cannot take another agent. The owner deletes one from Settings \u2192 Agents.",
+  grant_limit: "The plan allows fewer channels per agent than this pairing grants.",
   feature_disabled: "Agents are not enabled for this account yet.",
   upload_failed: "The upload failed. Try again.",
   oprf_failed: "Zas did not answer correctly while preparing the file. Try again.",
@@ -278,12 +295,138 @@ function defaultEndpoints() {
   };
 }
 
+// src/open.ts
+import { spawn } from "node:child_process";
+function openInBrowser(url, platform = process.platform) {
+  try {
+    const [command, args] = platform === "win32" ? ["cmd", ["/c", "start", "", url]] : platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+    const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.on("error", () => void 0);
+    child.unref();
+  } catch {
+  }
+}
+
 // src/pair.ts
 import { hostname } from "node:os";
 
+// src/claim-listener.ts
+import { createServer } from "node:http";
+var BODY_MAX = 1024;
+function readBody(req) {
+  return new Promise((resolve2) => {
+    let size = 0;
+    let resolved = false;
+    const chunks = [];
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > BODY_MAX) {
+        if (!resolved) {
+          resolved = true;
+          resolve2(null);
+        }
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (!resolved) {
+        resolved = true;
+        resolve2(Buffer.concat(chunks).toString("utf8"));
+      }
+    });
+    req.on("error", () => {
+      if (!resolved) {
+        resolved = true;
+        resolve2(null);
+      }
+    });
+  });
+}
+async function startClaimListener(opts) {
+  let taken = false;
+  const server = createServer(async (req, res) => {
+    const origin = String(req.headers.origin ?? "");
+    const json = (status, body2) => {
+      res.writeHead(status, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(body2));
+    };
+    if (req.url !== "/claim") {
+      json(404, { error: "not_found" });
+      return;
+    }
+    if (req.method === "OPTIONS") {
+      if (origin !== opts.webOrigin) {
+        res.writeHead(403);
+        res.end();
+        return;
+      }
+      res.writeHead(204, {
+        "Access-Control-Allow-Origin": origin,
+        "Access-Control-Allow-Methods": "POST",
+        "Access-Control-Allow-Headers": "content-type",
+        "Access-Control-Allow-Private-Network": "true",
+        "Access-Control-Max-Age": "300",
+        Vary: "Origin"
+      });
+      res.end();
+      return;
+    }
+    if (req.method !== "POST") {
+      json(404, { error: "not_found" });
+      return;
+    }
+    if (origin !== opts.webOrigin) {
+      json(403, { error: "forbidden" });
+      return;
+    }
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Vary", "Origin");
+    if (!String(req.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) {
+      json(400, { error: "bad_request" });
+      return;
+    }
+    const raw = await readBody(req);
+    let body = {};
+    try {
+      body = raw === null ? {} : JSON.parse(raw);
+    } catch {
+      body = {};
+    }
+    if (typeof body !== "object" || body === null || body.pairing_id !== opts.pairingId || typeof body.code !== "string") {
+      json(400, { error: "bad_request" });
+      return;
+    }
+    if (taken) {
+      json(409, { error: "claim_taken" });
+      return;
+    }
+    taken = true;
+    const outcome = await opts.onCode(body.code);
+    if ("error" in outcome) json(outcome.status, { error: outcome.error });
+    else json(200, { status: "claimed" });
+  });
+  await new Promise((resolve2, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve2();
+    });
+  });
+  const address = server.address();
+  return {
+    host: address.address,
+    port: address.port,
+    close: () => new Promise((resolve2) => {
+      server.closeAllConnections();
+      server.close(() => resolve2());
+    })
+  };
+}
+
 // src/client.ts
 var REFRESH_MARGIN_MS = 5 * 60 * 1e3;
-async function readBody(res) {
+async function readBody2(res) {
   const text2 = await res.text();
   if (!text2) return {};
   try {
@@ -302,7 +445,7 @@ function jsonInit(method, body, headers) {
 async function apiPublic(base, method, path, body, headers = {}, fetchImpl) {
   const call = fetchImpl ?? ((input, init) => fetch(input, init));
   const res = await call(`${base}${path}`, jsonInit(method, body, headers));
-  const parsed = res.status === 204 ? void 0 : await readBody(res);
+  const parsed = res.status === 204 ? void 0 : await readBody2(res);
   if (!res.ok) throw errorFromResponse(res.status, parsed);
   return parsed;
 }
@@ -368,7 +511,7 @@ var ZasClient = class _ZasClient {
   }
   async api(method, path, body, headers = {}) {
     const res = await this.authedRetrying(`${this.identity.api_base}/v1${path}`, method, body, headers);
-    const parsed = res.status === 204 ? void 0 : await readBody(res);
+    const parsed = res.status === 204 ? void 0 : await readBody2(res);
     if (!res.ok) throw errorFromResponse(res.status, parsed);
     return parsed;
   }
@@ -391,7 +534,7 @@ var ZasClient = class _ZasClient {
   }
   async oprfEvaluate(blinded) {
     const res = await this.authedRetrying(`${this.identity.oprf_base}/evaluate`, "POST", { blinded }, {});
-    const parsed = await readBody(res);
+    const parsed = await readBody2(res);
     if (!res.ok) throw errorFromResponse(res.status, parsed);
     return parsed.evaluated ?? [];
   }
@@ -402,7 +545,7 @@ var ZasClient = class _ZasClient {
     const base = _ZasClient.firestoreBase(this.identity.firestore_project);
     const url = `${base}${parentPath ? `/${parentPath}` : ""}:runQuery`;
     const res = await this.authed(url, "POST", { structuredQuery: query }, {});
-    const parsed = await readBody(res);
+    const parsed = await readBody2(res);
     if (!res.ok) throw errorFromResponse(res.status, parsed);
     if (!Array.isArray(parsed)) return [];
     return parsed.filter((row) => !!row && typeof row === "object" && "document" in row).map((row) => row.document);
@@ -427,10 +570,10 @@ function packageName() {
   return true ? "zas-agent" : "zas-agent";
 }
 function claudeSnippet(profile) {
-  return `claude mcp add zas -- npx -y ${packageName()} --profile ${profile}`;
+  return `claude mcp add zas "--" npx -y ${packageName()} --profile ${profile}`;
 }
 function codexSnippet(profile) {
-  return `codex mcp add zas -- npx -y ${packageName()} --profile ${profile}`;
+  return `codex mcp add zas "--" npx -y ${packageName()} --profile ${profile}`;
 }
 function kindForProfile(profile) {
   if (profile === "claude-code") return "claude_code";
@@ -440,13 +583,23 @@ function kindForProfile(profile) {
 
 // src/pair.ts
 var POLL_INTERVAL_MS = 2e3;
-function pairUrl(webBase, pairingId) {
-  return `${webBase}/agents/pair?p=${pairingId}`;
+var NO_TTY_LINE = "This terminal cannot take a code. If the page shows one, run zas-agent pair again from an interactive terminal.";
+var CODE_SHAPE_LINE = "The code is eight letters and digits, like ABCD-EFGH.";
+function pairUrl(webBase, pairingId, port) {
+  const link = `${webBase}/agents/pair?p=${pairingId}`;
+  return port ? `${link}#port=${port}` : link;
 }
-function formatCode(code) {
-  return `${code.slice(0, 4)}-${code.slice(4)}`;
+function webOriginOf(webBase) {
+  return new URL(webBase).origin;
 }
 var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+function deferred() {
+  let resolve2;
+  const promise = new Promise((r) => {
+    resolve2 = r;
+  });
+  return { promise, resolve: resolve2 };
+}
 async function runPair(opts) {
   const sleep2 = opts.sleep ?? defaultSleep;
   const now = opts.now ?? (() => Date.now());
@@ -463,67 +616,152 @@ async function runPair(opts) {
     opts.apiBase,
     "POST",
     "/v1/agents/pairings",
-    { kind: opts.kind, host, x25519_public: keys.x25519_public, p256_public: keys.p256_public },
+    { kind: opts.kind, host, x25519_public: keys.x25519_public, p256_public: keys.p256_public, claim: true },
     {},
     opts.fetch
   );
-  const pending = {
-    version: 1,
-    profile: opts.profile,
-    pairing_id: created.pairing_id,
-    poll_secret: created.poll_secret,
-    code: created.code,
-    fingerprint: created.fingerprint,
-    expires_at: created.expires_at,
-    kind: opts.kind,
-    host,
-    ...keys,
-    ...endpoints,
-    created_at: now()
+  let claimed = null;
+  let inFlight = null;
+  const wake = deferred();
+  const claimOnce = (code) => {
+    if (claimed) return Promise.resolve({ error: "pairing_claimed", status: 409 });
+    if (inFlight) return inFlight;
+    inFlight = (async () => {
+      try {
+        const answer = await apiPublic(
+          opts.apiBase,
+          "POST",
+          `/v1/agents/pairings/${created.pairing_id}/claim`,
+          { code },
+          { "X-Zas-Poll-Secret": created.poll_secret },
+          opts.fetch
+        );
+        claimed = { agent_uid: answer.agent_uid, owner_uid: answer.owner_uid };
+        wake.resolve();
+        return { status: "claimed" };
+      } catch (err) {
+        if (err instanceof ZasError) return { error: err.code, status: err.status };
+        return { error: "network", status: 502 };
+      } finally {
+        inFlight = null;
+      }
+    })();
+    return inFlight;
   };
-  savePending(opts.profile, pending);
-  const minutesLeft = Math.max(0, Math.round((created.expires_at - now()) / 6e4));
-  opts.log(
-    [
-      "Open this page signed in to your Zas account:",
-      `  ${pairUrl(opts.webBase, created.pairing_id)}`,
-      `Code:        ${formatCode(created.code)}`,
-      `Fingerprint: ${agentFingerprintShort(created.fingerprint)}`,
-      `Waiting for approval\u2026 (expires in ${minutesLeft} minutes)`
-    ].join("\n")
-  );
-  let approved = null;
-  for (; ; ) {
-    let answer;
+  let listener = null;
+  if (opts.listen !== false) {
     try {
-      answer = await apiPublic(
-        opts.apiBase,
-        "POST",
-        `/v1/agents/pairings/${created.pairing_id}/poll`,
-        void 0,
-        { "X-Zas-Poll-Secret": created.poll_secret },
-        opts.fetch
-      );
-    } catch (err) {
-      if (!(err instanceof ZasError) || err.code !== "rate_limited") throw err;
-      if (now() >= created.expires_at) throw new ZasError("pairing_expired", 410);
-      await sleep2(err.retryAfterMs ?? 1e4);
-      continue;
-    }
-    if (answer.status === "approved") {
-      approved = { agent_uid: answer.agent_uid, owner_uid: answer.owner_uid };
-      break;
+      listener = await startClaimListener({
+        webOrigin: webOriginOf(opts.webBase),
+        pairingId: created.pairing_id,
+        onCode: (code) => claimOnce(normalizePairingCode(code) || code)
+      });
+    } catch {
+      listener = null;
     }
-    if (answer.status === "expired" || answer.status === "cancelled") {
-      clearPending(opts.profile);
-      throw new ZasError(`pairing_${answer.status}`, 410);
+  }
+  let askFailed = null;
+  try {
+    const port = listener?.port;
+    const link = pairUrl(opts.webBase, created.pairing_id, port);
+    const pending = {
+      version: 1,
+      profile: opts.profile,
+      pairing_id: created.pairing_id,
+      poll_secret: created.poll_secret,
+      fingerprint: created.fingerprint,
+      expires_at: created.expires_at,
+      kind: opts.kind,
+      host,
+      ...keys,
+      ...endpoints,
+      created_at: now(),
+      protocol: 2,
+      ...port ? { port } : {}
+    };
+    savePending(opts.profile, pending);
+    const minutesLeft = Math.max(0, Math.round((created.expires_at - now()) / 6e4));
+    opts.log(
+      [
+        "Open this page signed in to your Zas account:",
+        `  ${link}`,
+        `Fingerprint: ${agentFingerprintShort(created.fingerprint)}`,
+        `Waiting for approval\u2026 (expires in ${minutesLeft} minutes)`
+      ].join("\n")
+    );
+    opts.open?.(link);
+    let asking = false;
+    let toldNoTty = false;
+    const askLoop = async () => {
+      try {
+        while (!claimed) {
+          const code = normalizePairingCode(await opts.askCode());
+          if (!code) {
+            opts.log(CODE_SHAPE_LINE);
+            continue;
+          }
+          const outcome = await claimOnce(code);
+          if (!("error" in outcome) || outcome.error === "pairing_claimed") return;
+          if (outcome.error === "claim_mismatch") {
+            opts.log(humanSentence(new ZasError("claim_mismatch", 403)));
+            continue;
+          }
+          throw new ZasError(outcome.error, outcome.status);
+        }
+      } catch (e) {
+        askFailed = e;
+        wake.resolve();
+      }
+    };
+    for (; ; ) {
+      if (claimed) break;
+      if (askFailed) throw askFailed;
+      let answer;
+      try {
+        answer = await apiPublic(
+          opts.apiBase,
+          "POST",
+          `/v1/agents/pairings/${created.pairing_id}/poll`,
+          void 0,
+          { "X-Zas-Poll-Secret": created.poll_secret },
+          opts.fetch
+        );
+      } catch (err) {
+        if (!(err instanceof ZasError) || err.code !== "rate_limited") throw err;
+        if (now() >= created.expires_at) throw new ZasError("pairing_expired", 410);
+        await Promise.race([sleep2(err.retryAfterMs ?? 1e4), wake.promise]);
+        continue;
+      }
+      if (claimed) break;
+      if (answer.status === "claimed") {
+        claimed = { agent_uid: answer.agent_uid, owner_uid: answer.owner_uid };
+        break;
+      }
+      if (answer.status === "expired" || answer.status === "cancelled") {
+        clearPending(opts.profile);
+        throw new ZasError(`pairing_${answer.status}`, 410);
+      }
+      if (answer.status === "approved") {
+        if (opts.askCode && !asking) {
+          asking = true;
+          void askLoop();
+        }
+        if (!opts.askCode && !toldNoTty) {
+          toldNoTty = true;
+          opts.log(NO_TTY_LINE);
+        }
+      }
+      await Promise.race([sleep2(POLL_INTERVAL_MS), wake.promise]);
     }
-    await sleep2(POLL_INTERVAL_MS);
+  } finally {
+    await listener?.close();
   }
+  if (askFailed) throw askFailed;
+  if (!claimed) throw new ZasError("pairing_expired", 410);
   const baseIdentity = {
     version: 1,
-    agent_uid: approved.agent_uid,
-    owner_uid: approved.owner_uid,
+    agent_uid: claimed.agent_uid,
+    owner_uid: claimed.owner_uid,
     name: "",
     kind: opts.kind,
     host,
@@ -1631,7 +1869,7 @@ async function sendNote(ctx, input) {
 
 // src/server.ts
 function agentVersion() {
-  return true ? "0.1.1" : "0.0.0-dev";
+  return true ? "0.2.1" : "0.0.0-dev";
 }
 var AGENT_CUE = " The owner sees every item this agent sends with the >_ agent mark and this agent's name, on every device.";
 var PAIR_ANNOUNCE_MS = 15e3;
@@ -1703,10 +1941,14 @@ function buildServer(profile, deps = {}) {
   });
   let pairing = null;
   server.registerTool("zas_pair", {
-    description: "Pair this machine with a Zas account. The first call returns a URL and a code for the owner to approve; a later call says whether they did." + AGENT_CUE
-  }, async () => {
+    description: "Pair this machine with a Zas account. The first call returns a URL for the owner to open; a later call says whether they approved. If the page shows a code, call again with `code`." + AGENT_CUE,
+    inputSchema: {
+      code: z.string().optional().describe("The code the pairing page shows when the browser could not reach this machine.")
+    }
+  }, async (input) => {
     if (!pairing) {
-      const state = { logs: [], status: "running" };
+      if (input.code !== void 0) return failed(new ZasError("pairing_not_approved", 409));
+      const state = { logs: [], status: "running", ask: null };
       pairing = state;
       (deps.runPair ?? runPair)({
         profile,
@@ -1717,7 +1959,13 @@ function buildServer(profile, deps = {}) {
         apiBase: defaultEndpoints().api_base,
         log: (line) => {
           state.logs.push(line);
-        }
+        },
+        // The person cannot type into this process; the coding agent relays
+        // the code as an argument, and this promise is what it answers.
+        askCode: () => new Promise((resolve2) => {
+          state.ask = resolve2;
+        }),
+        ...process.env.ZAS_NO_OPEN === "1" ? {} : { open: openInBrowser }
       }).then(
         (identity) => {
           state.status = "paired";
@@ -1744,6 +1992,25 @@ function buildServer(profile, deps = {}) {
       pairing = null;
       return failed(error);
     }
+    if (input.code !== void 0) {
+      const state = pairing;
+      const ask = state.ask;
+      if (!ask) return failed(new ZasError("pairing_not_approved", 409));
+      state.ask = null;
+      ask(normalizePairingCode(input.code) || input.code);
+      const until = Date.now() + (deps.announceMs ?? PAIR_ANNOUNCE_MS);
+      while (state.status === "running" && state.ask === null && Date.now() < until) {
+        await delay(10);
+      }
+      if (state.status === "paired") return text2(`paired as ${state.identity?.name ?? ""}`.trim());
+      if (state.status === "failed") {
+        const error = state.error;
+        pairing = null;
+        return failed(error);
+      }
+      if (state.ask !== null) return failed(new ZasError("claim_mismatch", 403));
+      return text2(["pending", ...state.logs].join("\n"));
+    }
     return text2(["pending", ...pairing.logs].join("\n"));
   });
   server.registerTool("zas_send_file", {
@@ -1846,7 +2113,8 @@ function parseArgs(argv) {
       const kind = take();
       if (!isAgentKind(kind)) return { ...parsed, command: "help", unknown: `--kind ${kind}` };
       parsed.kind = kind;
-    } else if (name === "--host") parsed.host = take() || void 0;
+    } else if (name === "--no-open") parsed.noOpen = true;
+    else if (name === "--host") parsed.host = take() || void 0;
     else return { ...parsed, command: "help", unknown: arg };
   }
   return parsed;
@@ -1856,7 +2124,7 @@ var USAGE = [
   "",
   "  zas-agent [--profile <name>]                serve the MCP tools over stdio",
   "  zas-agent pair [--profile <name>]           pair this machine with a Zas account",
-  "                 [--kind claude_code|codex|other] [--host <name>]",
+  "                 [--kind claude_code|codex|other] [--host <name>] [--no-open]",
   "  zas-agent --version"
 ].join("\n");
 async function main(argv, log = (l) => console.error(l)) {
@@ -1875,6 +2143,14 @@ async function main(argv, log = (l) => console.error(l)) {
     return args.unknown ? 2 : 0;
   }
   if (args.command === "pair") {
+    let rl = null;
+    const askCode = process.stdin.isTTY ? () => {
+      rl ??= createInterface({ input: process.stdin, output: process.stderr });
+      return new Promise((resolve2) => {
+        rl.question("Type the code shown in the browser: ", resolve2);
+      });
+    } : void 0;
+    const noOpen = args.noOpen === true || process.env.ZAS_NO_OPEN === "1";
     try {
       await runPair({
         profile: args.profile,
@@ -1882,12 +2158,16 @@ async function main(argv, log = (l) => console.error(l)) {
         ...args.host !== void 0 ? { host: args.host } : {},
         webBase: process.env.ZAS_WEB_BASE || "https://zas.red",
         apiBase: defaultEndpoints().api_base,
-        log
+        log,
+        ...askCode ? { askCode } : {},
+        ...noOpen ? {} : { open: openInBrowser }
       });
     } catch (e) {
       const err = e instanceof ZasError ? e : new ZasError("internal", 0, String(e));
       log(humanSentence(err));
       return 1;
+    } finally {
+      rl?.close();
     }
     return 0;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zas-agent",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "MCP server that lets a coding agent send files and notes into your Zas channels.",
   "type": "module",
   "license": "MIT",