zas-agent 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-03
+
+### Added
+
+- Pairing again in a profile that is already paired replaces the agent
+  instead of adding a second one. The terminal opens the pairing as the old
+  agent, the approval page says which agent it replaces and fills in its
+  name and channels, and the old agent is revoked in the same step that
+  creates the new one. If the server no longer accepts the old agent, `pair`
+  says so and creates a new agent.
+
+### Changed
+
+- The help text, the tool descriptions and the README say "this agent" where
+  they said "this machine": a pairing is one profile's key pair, and one
+  machine can hold several.
+
 ## [0.2.1] - 2026-09-03
 
 ### Fixed
@@ -58,7 +75,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.2.1...HEAD
+[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/soke1556/zas-agent/compare/v0.2.1...v0.3.0
 [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

package/README.md

@@ -35,7 +35,7 @@ get a short-lived session.
 
 ## Install
 
-Pair the machine first, then hand the command to your harness.
+Pair the agent first, then hand the command to your harness.
 
 **Pair**
 
@@ -168,7 +168,7 @@ string ever reaches a terminal.
 
 | Code | What it means |
 | --- | --- |
-| `not_paired` | This machine is not paired yet. |
+| `not_paired` | This agent is not paired yet. |
 | `identity_corrupt` | The identity file on disk is damaged. |
 | `agent_revoked` | The owner revoked this agent. |
 | `agent_forbidden` | Only the account owner can do that. |
@@ -203,8 +203,8 @@ 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 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_status` | Says whether this agent is paired with a Zas account, and lists the owner's channels it may send to or read from. |
+| `zas_pair` | Pairs this agent 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. In a profile that is already paired, approval replaces the old agent. |
 | `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. |
@@ -260,6 +260,22 @@ 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 → Agents → Revoke.
 
+## Pairing again
+
+A pairing is one profile's key pair, not the machine and not the program. A
+profile holds one agent. Running `zas-agent pair` in a profile that is already
+paired opens a replacement: the terminal signs the request with the old
+identity, the approval page says which agent it replaces and fills in its name
+and channels, and the old agent is revoked in the same step that creates the
+new one. Its row stays under Settings → Agents as revoked until you remove it,
+and it keeps costing a slot until then. If the old agent was already revoked
+or removed, `pair` says so and creates a new agent.
+
+One machine that runs Claude Code and Codex has two profiles (`claude-code`
+and `codex`), two agents, two approvals and two rows. Revoking one does not
+touch the other. Two programs pointed at the same `--profile` act as one
+agent: same keys, same channels, one row.
+
 ## Configuration
 
 | Setting | Default | What it changes |

package/dist/cli.js

@@ -604,22 +604,28 @@ async function runPair(opts) {
   const sleep2 = opts.sleep ?? defaultSleep;
   const now = opts.now ?? (() => Date.now());
   const existing = loadIdentity(opts.profile);
-  if (existing) {
-    opts.log(
-      `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);
   const keys = newKeyMaterial();
   const endpoints = { ...defaultEndpoints(), api_base: opts.apiBase };
-  const created = await apiPublic(
-    opts.apiBase,
-    "POST",
-    "/v1/agents/pairings",
-    { kind: opts.kind, host, x25519_public: keys.x25519_public, p256_public: keys.p256_public, claim: true },
-    {},
-    opts.fetch
-  );
+  const request = { kind: opts.kind, host, x25519_public: keys.x25519_public, p256_public: keys.p256_public, claim: true };
+  let created = null;
+  let replacing = false;
+  if (existing) {
+    try {
+      const old = new ZasClient({ ...existing, api_base: opts.apiBase }, { fetch: opts.fetch, now });
+      created = await old.api("POST", "/agents/me/pairings", request);
+      replacing = true;
+      opts.log(`This profile is paired as \u201C${existing.name}\u201D. Approving this pairing replaces that agent.`);
+    } catch (err) {
+      const code = err instanceof ZasError ? err.code : "network";
+      opts.log(
+        `This profile was paired as \u201C${existing.name}\u201D, but the server no longer accepts that agent (${code}). A new agent will be created; remove the old one from Settings \u2192 Agents.`
+      );
+    }
+  }
+  if (!created) {
+    created = await apiPublic(opts.apiBase, "POST", "/v1/agents/pairings", request, {}, opts.fetch);
+  }
   let claimed = null;
   let inFlight = null;
   const wake = deferred();
@@ -780,6 +786,7 @@ async function runPair(opts) {
   opts.log(
     [
       `Done: the agent \u201C${identity.name}\u201D is paired with your account.`,
+      ...replacing ? ["It replaces the previous agent of this profile, which is now revoked."] : [],
       ...install
     ].join("\n")
   );
@@ -1869,7 +1876,7 @@ async function sendNote(ctx, input) {
 
 // src/server.ts
 function agentVersion() {
-  return true ? "0.2.1" : "0.0.0-dev";
+  return true ? "0.3.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;
@@ -1913,7 +1920,7 @@ function buildServer(profile, deps = {}) {
     return text2({ job_id: job.id, status: "running", phase: job.phase });
   };
   server.registerTool("zas_status", {
-    description: "Say whether this machine is paired with a Zas account, and list the owner's channels this agent may send to or read from." + AGENT_CUE
+    description: "Say whether this agent is paired with a Zas account, and list the owner's channels it may send to or read from." + AGENT_CUE
   }, async () => {
     try {
       if (!(deps.identity ?? loadIdentity(profile))) {
@@ -1941,7 +1948,7 @@ 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 for the owner to open; a later call says whether they approved. If the page shows a code, call again with `code`." + AGENT_CUE,
+    description: "Pair this agent 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`. In a profile that is already paired, approval replaces the old agent." + AGENT_CUE,
     inputSchema: {
       code: z.string().optional().describe("The code the pairing page shows when the browser could not reach this machine.")
     }
@@ -2123,7 +2130,7 @@ var USAGE = [
   "zas-agent \u2014 send files and notes from a coding agent into your Zas channels.",
   "",
   "  zas-agent [--profile <name>]                serve the MCP tools over stdio",
-  "  zas-agent pair [--profile <name>]           pair this machine with a Zas account",
+  "  zas-agent pair [--profile <name>]           pair this agent with a Zas account",
   "                 [--kind claude_code|codex|other] [--host <name>] [--no-open]",
   "  zas-agent --version"
 ].join("\n");

package/package.json

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