zas-agent 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- Every line the agent prints and every tool result is in English. The pairing
+  prompt, the status report and the error sentences were in Spanish.
+- The README opens with what Zas is. The README, the package keywords and the
+  registry entry no longer call the design end-to-end encryption: the
+  product's own privacy page does not, because a separate service derives
+  account keys.
+
 ## [0.1.0] - 2026-09-02
 
 ### Added
@@ -25,5 +49,6 @@ 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.0...HEAD
+[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.1.1...HEAD
+[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

@@ -10,6 +10,19 @@ read items back out of them.
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/soke1556/zas-agent/badge)](https://scorecard.dev/viewer/?uri=github.com/soke1556/zas-agent)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+## What is Zas
+
+[Zas](https://zas.red) moves things between your devices and the people you
+choose: files, photos, text, code. You put something into a channel on one
+device and use it on another. Whatever you do not pin leaves on its own after a
+few days, so there is nothing to tidy up later. Everything is encrypted on the
+device before it is uploaded: the database and the object storage receive
+encrypted bytes, not filenames, content or previews.
+
+This package is the piece that lets a coding agent use your channels the way
+your other devices do, under an identity of its own that you approve, that you
+scope to the channels you choose, and that you can revoke.
+
 ## What it does
 
 Your coding agent gets seven tools. It can send a file or a note into a channel
@@ -50,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:
 
 ```
-Abrí esta página con tu cuenta de Zas:
-  https://zas.red/agents/pair?p=...
-Código:  ABCD-EFGH
-Huella:  1a2b 3c4d 5e6f 7a8b
-Esperando la aprobación… (vence en 10 minutos)
+Open this page signed in to your Zas account:
+  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
 
@@ -85,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
@@ -98,11 +122,12 @@ source, the sentence says so.
 - **Everything it sends is visible as its work.** Every item carries the `>_`
   agent mark and the agent's name, in the channel, on every device you read Zas
   from.
-- **You can revoke it at any time.** Settings → Agentes → the agent → Revocar.
+- **You can revoke it at any time.** Settings → Agents → the agent → Revoke.
   The session stops, its refresh tokens are revoked *(server-side)*, and the
   next tool call answers "the owner revoked this agent". What it already sent
   stays where it is. You can also drop a single channel and keep the rest.
-- **Content is end-to-end encrypted, the same way the app does it.** The
+- **Content is encrypted on your machine before it leaves, the same way the
+  app does it.** The
   chunking, the manifest and the envelope formats under `src/shared/` are the
   same modules the Zas web app ships. The server stores ciphertext and never
   sees a channel key, a channel name or item plaintext *(server-side)*.
@@ -131,7 +156,7 @@ ones marked *(server-side)* are enforced by the Zas server.
 - **Rate limited by the server**, on its own buckets, with the key-derivation
   budget charged to your account so ten agents are not ten times your own
   allowance *(server-side)*.
-- **Ten agents per account** *(server-side)*.
+- **As many agents as your plan or your organization allows** *(server-side)*.
 - **Files up to 5 GiB**, and in practice less: the agent reads a file into
   memory to hash it, so the machine's memory is the real ceiling.
 
@@ -171,7 +196,7 @@ string ever reaches a terminal.
 | `missing_token` | The session token is missing; pair the agent again. |
 | `internal` | Something failed inside the agent. |
 
-Every code comes back as one sentence in Spanish and one in English, never as a
+Every code comes back as one sentence in English, never as a
 stack trace.
 
 ## Tools
@@ -179,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. |
@@ -218,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.
@@ -233,7 +258,7 @@ profile they live in, and the package does not try to set any others.
 
 Deleting the directory makes this machine forget the agent. It does not revoke
 anything: the account side is closed from the web app, under
-Settings → Agentes → Revocar.
+Settings → Agents → Revoke.
 
 ## Configuration
 

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);
@@ -136,38 +148,43 @@ function errorFromResponse(status, body) {
   return new ZasError(code, status, raw, retryAfterMs, raw);
 }
 var SENTENCES = {
-  identity_corrupt: { es: "El archivo de identidad del agente est\xE1 da\xF1ado: {path}. Restauralo o borralo y volv\xE9 a emparejar.", en: "The agent identity file is damaged: {path}. Restore it, or delete it and pair again." },
-  not_paired: { es: "Este agente todav\xEDa no est\xE1 emparejado. Corr\xE9 \xABnpx -y zas-agent pair\xBB en la terminal.", en: "This agent is not paired yet. Run \u201Cnpx -y zas-agent pair\u201D in the terminal." },
-  internal: { es: "Algo fall\xF3 dentro del agente. Prob\xE1 de nuevo.", en: "Something failed inside the agent. Try again." },
-  agent_forbidden: { es: "Este agente no puede hacer eso; solo el due\xF1o de la cuenta.", en: "This agent cannot do that; only the account owner can." },
-  agent_revoked: { es: "El due\xF1o revoc\xF3 este agente. Volv\xE9 a emparejar con \xABzas-agent pair\xBB.", en: "The owner revoked this agent. Pair again with \u201Czas-agent pair\u201D." },
-  grant_missing: { es: "Este agente no tiene acceso a ese canal. El due\xF1o lo agrega desde Ajustes \u2192 Agentes.", en: "This agent has no access to that channel. The owner adds it from Settings \u2192 Agents." },
-  not_found: { es: "Ese \xEDtem no est\xE1 en el canal.", en: "That item is not in the channel." },
-  invalid_cap: { es: "Ese archivo ya no est\xE1 disponible.", en: "That file is no longer available." },
-  write_failed: { es: "No se pudo guardar el archivo en el destino.", en: "The file could not be saved to the destination." },
-  send_forbidden: { es: "Este agente no puede enviar a ese canal.", en: "This agent cannot send to that channel." },
-  read_forbidden: { es: "Este agente no puede leer ese canal.", en: "This agent cannot read that channel." },
-  direct_mode: { es: "Ese canal est\xE1 en modo Directo. Us\xE1 zas_send_direct.", en: "That channel is in Directo mode. Use zas_send_direct." },
-  not_direct_mode: { es: "Ese canal no est\xE1 en modo Directo. Us\xE1 zas_send_file.", en: "That channel is not in Directo mode. Use zas_send_file." },
-  key_stale: { es: "La clave del canal cambi\xF3. El due\xF1o la renueva al abrir Zas.", en: "The channel key changed. The owner refreshes it by opening Zas." },
-  quota_exceeded: { es: "La cuenta lleg\xF3 a su l\xEDmite de almacenamiento.", en: "The account reached its storage limit." },
-  rate_limited: { es: "Demasiados env\xEDos seguidos. Esper\xE1 un momento.", en: "Too many sends in a row. Wait a moment." },
-  file_too_big: { es: "El archivo supera el m\xE1ximo del plan.", en: "The file is over the plan limit." },
-  duplicate: { es: "Ese \xEDtem ya est\xE1 en el canal.", en: "That item is already in the channel." },
-  pairing_expired: { es: "El emparejamiento venci\xF3. Corr\xE9 \xABzas-agent pair\xBB de nuevo.", en: "The pairing expired. Run \u201Czas-agent pair\u201D again." },
-  pairing_cancelled: { es: "El due\xF1o cancel\xF3 el emparejamiento.", en: "The owner cancelled the pairing." },
-  feature_disabled: { es: "Los agentes todav\xEDa no est\xE1n habilitados para esta cuenta.", en: "Agents are not enabled for this account yet." },
-  upload_failed: { es: "No se pudo subir el archivo. Prob\xE1 de nuevo.", en: "The upload failed. Try again." },
-  oprf_failed: { es: "Zas no respondi\xF3 bien al preparar el archivo. Prob\xE1 de nuevo.", en: "Zas did not answer correctly while preparing the file. Try again." },
-  network: { es: "No hay conexi\xF3n con Zas. Prob\xE1 de nuevo en un momento.", en: "Zas cannot be reached. Try again in a moment." },
-  sign_in_failed: { es: "Zas no acept\xF3 la sesi\xF3n de este agente. Prob\xE1 de nuevo o volv\xE9 a emparejar.", en: "Zas did not accept this agent session. Try again, or pair again." },
-  bad_signature: { es: "Zas rechaz\xF3 la firma de este agente. Emparejalo de nuevo.", en: "Zas rejected this agent's signature. Pair it again." },
-  missing_token: { es: "Falta el token de sesi\xF3n. Emparej\xE1 el agente de nuevo.", en: "The session token is missing. Pair the agent again." }
+  identity_corrupt: "The agent identity file is damaged: {path}. Restore it, or delete it and pair again.",
+  not_paired: "This agent is not paired yet. Run \u201Cnpx -y zas-agent pair\u201D in the terminal.",
+  internal: "Something failed inside the agent. Try again.",
+  agent_forbidden: "This agent cannot do that; only the account owner can.",
+  agent_revoked: "The owner revoked this agent. Pair again with \u201Czas-agent pair\u201D.",
+  grant_missing: "This agent has no access to that channel. The owner adds it from Settings \u2192 Agents.",
+  not_found: "That item is not in the channel.",
+  invalid_cap: "That file is no longer available.",
+  write_failed: "The file could not be saved to the destination.",
+  send_forbidden: "This agent cannot send to that channel.",
+  read_forbidden: "This agent cannot read that channel.",
+  direct_mode: "That channel is in Directo mode. Use zas_send_direct.",
+  not_direct_mode: "That channel is not in Directo mode. Use zas_send_file.",
+  key_stale: "The channel key changed. The owner refreshes it by opening Zas.",
+  quota_exceeded: "The account reached its storage limit.",
+  rate_limited: "Too many sends in a row. Wait a moment.",
+  file_too_big: "The file is over the plan limit.",
+  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.",
+  network: "Zas cannot be reached. Try again in a moment.",
+  sign_in_failed: "Zas did not accept this agent session. Try again, or pair again.",
+  bad_signature: "Zas rejected this agent's signature. Pair it again.",
+  missing_token: "The session token is missing. Pair the agent again."
 };
-function humanSentence(error, locale = "es") {
-  const sentence = SENTENCES[error.code]?.[locale];
+function humanSentence(error) {
+  const sentence = SENTENCES[error.code];
   if (sentence) return sentence.replace("{path}", () => error.message);
-  return locale === "es" ? `Zas respondi\xF3 ${error.code} (${error.status}).` : `Zas answered ${error.code} (${error.status}).`;
+  return `Zas answered ${error.code} (${error.status}).`;
 }
 
 // src/identity.ts
@@ -185,7 +202,7 @@ function agentHome() {
 }
 var PROFILE_RE = /^(?!\.)[A-Za-z0-9._-]{1,64}$/;
 function profileDir(profile) {
-  if (!PROFILE_RE.test(profile)) throw new ZasError("internal", 0, `Perfil inv\xE1lido: ${profile}`);
+  if (!PROFILE_RE.test(profile)) throw new ZasError("internal", 0, `Invalid profile: ${profile}`);
   return join(agentHome(), profile);
 }
 function ensureDir(dir) {
@@ -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);
@@ -440,20 +583,30 @@ 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());
   const existing = loadIdentity(opts.profile);
   if (existing) {
     opts.log(
-      `Este perfil ya est\xE1 emparejado como \xAB${existing.name}\xBB. Se va a crear un agente nuevo; revoc\xE1 el anterior desde Ajustes \u2192 Agentes.`
+      `This profile is already paired as \u201C${existing.name}\u201D. A new agent will be created; revoke the old one from Settings \u2192 Agents.`
     );
   }
   const host = (opts.host ?? hostname()).slice(0, AGENT_HOST_MAX);
@@ -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(
-    [
-      "Abr\xED esta p\xE1gina con tu cuenta de Zas:",
-      `  ${pairUrl(opts.webBase, created.pairing_id)}`,
-      `C\xF3digo:  ${formatCode(created.code)}`,
-      `Huella:  ${agentFingerprintShort(created.fingerprint)}`,
-      `Esperando la aprobaci\xF3n\u2026 (vence en ${minutesLeft} minutos)`
-    ].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,
@@ -538,10 +776,10 @@ async function runPair(opts) {
   clearPending(opts.profile);
   const claudeLines = (lead) => [lead, `  ${claudeSnippet(opts.profile)}`];
   const codexLines = (lead) => [lead, `  ${codexSnippet(opts.profile)}`];
-  const install = opts.kind === "claude_code" ? claudeLines("Agregalo a Claude Code:") : opts.kind === "codex" ? codexLines("Agregalo a Codex:") : [...claudeLines("Agregalo a Claude Code:"), ...codexLines("O a Codex:")];
+  const install = opts.kind === "claude_code" ? claudeLines("Add it to Claude Code:") : opts.kind === "codex" ? codexLines("Add it to Codex:") : [...claudeLines("Add it to Claude Code:"), ...codexLines("Or to Codex:")];
   opts.log(
     [
-      `Listo: el agente \xAB${identity.name}\xBB qued\xF3 emparejado con tu cuenta.`,
+      `Done: the agent \u201C${identity.name}\u201D is paired with your account.`,
       ...install
     ].join("\n")
   );
@@ -1631,7 +1869,7 @@ async function sendNote(ctx, input) {
 
 // src/server.ts
 function agentVersion() {
-  return true ? "0.1.0" : "0.0.0-dev";
+  return true ? "0.2.0" : "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;
@@ -1641,9 +1879,9 @@ var delay = (ms) => new Promise((resolve2) => {
 });
 function rightsOf(grant) {
   const rights = [];
-  if (grant.send && grant.mode !== "view" && !grant.direct_mode) rights.push("env\xEDa");
-  if (grant.read) rights.push("lee");
-  return rights.length > 0 ? rights.join(" \xB7 ") : "sin permisos";
+  if (grant.send && grant.mode !== "view" && !grant.direct_mode) rights.push("send");
+  if (grant.read) rights.push("read");
+  return rights.length > 0 ? rights.join(" \xB7 ") : "no access";
 }
 function buildServer(profile, deps = {}) {
   const server = new McpServer({ name: "zas", version: agentVersion() });
@@ -1664,7 +1902,7 @@ function buildServer(profile, deps = {}) {
   });
   const failed = (e) => {
     const err = e instanceof ZasError ? e : new ZasError("internal", 0, String(e));
-    return { isError: true, ...text2(`${err.code}: ${humanSentence(err, "es")} / ${humanSentence(err, "en")}`) };
+    return { isError: true, ...text2(`${err.code}: ${humanSentence(err)}`) };
   };
   const settled = (job) => {
     if (job.status === "done") return text2(job.result);
@@ -1679,7 +1917,7 @@ function buildServer(profile, deps = {}) {
   }, async () => {
     try {
       if (!(deps.identity ?? loadIdentity(profile))) {
-        return text2(humanSentence(new ZasError("not_paired", 0), "es"));
+        return text2(humanSentence(new ZasError("not_paired", 0)));
       }
       const c = ctx();
       const grants = await grantsFor(c.client, profile);
@@ -1692,10 +1930,10 @@ function buildServer(profile, deps = {}) {
         return `  ${name} \xB7 ${rightsOf(grant)}`;
       });
       return text2([
-        `Emparejado como \xAB${c.identity.name}\xBB (${c.identity.kind}) con la cuenta ${c.identity.owner_uid}.`,
-        grants.length > 0 ? "Canales:" : "Sin canales: el due\xF1o todav\xEDa no le dio acceso a ninguno.",
+        `Paired as \u201C${c.identity.name}\u201D (${c.identity.kind}) with account ${c.identity.owner_uid}.`,
+        grants.length > 0 ? "Channels:" : "No channels: the owner has not granted access to any yet.",
         ...lines,
-        `${packageName()} ${agentVersion()} \xB7 perfil ${profile}`
+        `${packageName()} ${agentVersion()} \xB7 profile ${profile}`
       ].join("\n"));
     } catch (e) {
       return failed(e);
@@ -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";
@@ -1736,7 +1984,7 @@ function buildServer(profile, deps = {}) {
         pairing = null;
         return failed(state.error);
       }
-      return text2(state.logs.join("\n") || "Abriendo el emparejamiento\u2026");
+      return text2(state.logs.join("\n") || "Opening the pairing\u2026");
     }
     if (pairing.status === "paired") return text2(`paired as ${pairing.identity?.name ?? ""}`.trim());
     if (pairing.status === "failed") {
@@ -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", {
@@ -1840,13 +2107,14 @@ function parseArgs(argv) {
     else if (name === "--profile") {
       parsed.profile = take() || DEFAULT_PROFILE;
       if (!PROFILE_RE.test(parsed.profile)) {
-        return { ...parsed, command: "invalid", message: `Perfil inv\xE1lido: ${parsed.profile}` };
+        return { ...parsed, command: "invalid", message: `Invalid profile: ${parsed.profile}` };
       }
     } else if (name === "--kind") {
       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)) {
@@ -1870,11 +2138,19 @@ async function main(argv, log = (l) => console.error(l)) {
     return 2;
   }
   if (args.command === "help") {
-    if (args.unknown) log(`No entiendo \xAB${args.unknown}\xBB.`);
+    if (args.unknown) log(`Unknown argument \u201C${args.unknown}\u201D.`);
     log(USAGE);
     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, "es"));
+      log(humanSentence(err));
       return 1;
+    } finally {
+      rl?.close();
     }
     return 0;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zas-agent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server that lets a coding agent send files and notes into your Zas channels.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "claude-code",
     "codex",
     "zas",
-    "end-to-end-encryption"
+    "encryption"
   ],
   "mcpName": "io.github.soke1556/zas-agent",
   "bin": {