zas-agent 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-03
+
+### Added
+
+- Usage reporting, so a defect like 0.5.0's — a release that could not
+  receive a file at all — is visible without somebody writing in. One report
+  after each tool call: the tool, whether it worked, the closed error code
+  when it did not, a duration bucket and the version. Never a file name, a
+  path, a channel name, a message or a stack. It goes to Zas, not to an
+  analytics service: this package holds no analytics token and opens no
+  connection to a third party.
+- `zas-agent telemetry [on|off]`, `ZAS_AGENT_TELEMETRY` and `DO_NOT_TRACK`.
+  Reporting is on by default; `pair` prints what it collects before it opens
+  a browser, the first `serve` on a machine prints it once, and `zas_status`
+  always says which way it is set. The choice lives in
+  `~/.zas/agent/settings.json` and survives pairing again.
+
 ## [0.5.1] - 2026-09-03
 
 ### Fixed

package/README.md

@@ -252,6 +252,36 @@ Two things worth knowing before you point a model at your account:
 Everything those tools touch lands inside your own account and your own
 machine. Revoking the agent stops all of them.
 
+## What it sends back
+
+This package reports how it is used, so defects like a release that could not
+receive a file at all stop being invisible. It is on by default and it is
+yours to turn off:
+
+```bash
+npx -y zas-agent telemetry off     # and `on` again, and `telemetry` to see
+```
+
+`ZAS_AGENT_TELEMETRY=0` and the cross-vendor `DO_NOT_TRACK=1` do the same
+without writing anything. The choice lives in `~/.zas/agent/settings.json` and
+covers every profile on the machine; pairing again does not reset it.
+`zas_status` always says which way it is set.
+
+What one report carries, and nothing else: the tool that ran, whether it
+worked, the closed error code when it did not, which of four duration buckets
+it fell in, and the package version. No file name, no file contents, no path,
+no channel name, no error message, no stack.
+
+Where it goes: to Zas, never to an analytics service directly. This package
+holds no analytics token and opens no connection to a third party, so no
+address of yours reaches one. The report is attributed to the Zas account the
+agent is paired with, which the server reads from the session — the request
+carries no identifier of its own. Nothing is reported before pairing, because
+until then there is no account it could belong to.
+
+A report is never allowed to matter: it is sent after the answer, waited on
+for at most five seconds, tried once, and dropped in silence if it fails.
+
 ## Data on disk
 
 One directory per profile, so one machine can hold a Claude Code agent and a
@@ -262,8 +292,8 @@ Codex agent side by side without either reading the other's keys:
 | macOS, Linux | `~/.zas/agent/<profile>/` |
 | Windows | `%USERPROFILE%\.zas\agent\<profile>\` |
 
-Four files, all written through a temporary file and renamed into place, so a
-crash mid-write cannot leave half a file behind:
+Four files in the profile directory, all written through a temporary file and
+renamed into place, so a 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.
@@ -276,6 +306,12 @@ crash mid-write cannot leave half a file behind:
   ten minutes, so a retried tool call answers without touching the network. It
   stores hashes, never a title or a note's first line. Disposable.
 
+One more file sits next to the profiles, in `~/.zas/agent/`:
+
+- `settings.json` — whether this machine reports usage, and when the notice
+  above was last printed. It belongs to the machine, not to a profile, so one
+  decision covers every agent on it.
+
 On macOS and Linux the directory is created `0700` and every file `0600`. On
 Windows those bits have no effect: the files carry the permissions of the user
 profile they live in, and the package does not try to set any others.
@@ -306,6 +342,8 @@ agent: same keys, same channels, one row.
 | --- | --- | --- |
 | `--profile <name>` | `claude-code` | Which identity directory this process uses. Letters, digits, `.`, `_` and `-`, up to 64, and it may not start with a dot. |
 | `ZAS_AGENT_HOME` | `~/.zas/agent` | Where the profile directories live. |
+| `ZAS_AGENT_TELEMETRY` | unset | `0` turns usage reporting off for this process, `1` on. It outranks the stored choice. |
+| `DO_NOT_TRACK` | unset | `1` turns usage reporting off. Read only to turn it off. |
 | `ZAS_WEB_BASE` | `https://zas.red` | The web app the pairing URL points at. |
 | `ZAS_API_BASE` | `https://zas.red/api` | The API. |
 | `ZAS_TOKEN_BASE` | `https://zas.red/anon-token` | The challenge and token routes. |
@@ -313,7 +351,8 @@ agent: same keys, same channels, one row.
 | `ZAS_FIREBASE_PROJECT` | `zas-me` | The project whose Firestore the read path queries. |
 | `ZAS_FIREBASE_API_KEY` | the public web key | The key used to exchange a custom token for a session. |
 
-Only `--profile` and `ZAS_AGENT_HOME` are worth setting by hand. The rest exist
+Only `--profile`, `ZAS_AGENT_HOME` and the two telemetry switches are worth
+setting by hand. The rest exist
 so the package can be pointed at a test deployment.
 
 ## Development

package/dist/cli.js

@@ -211,6 +211,7 @@ var IDENTITY_FILE = "identity.json";
 var PENDING_FILE = "pending.json";
 var GRANTS_FILE = "grants.json";
 var FINGERPRINTS_FILE = "fingerprints.json";
+var SETTINGS_FILE = "settings.json";
 function agentHome() {
   return process.env.ZAS_AGENT_HOME || join(homedir(), ".zas", "agent");
 }
@@ -300,6 +301,13 @@ function loadFingerprints(profile) {
 function saveFingerprints(profile, cache) {
   writePrivate(profileDir(profile), FINGERPRINTS_FILE, cache);
 }
+function loadSettings() {
+  const stored = readCache(agentHome(), SETTINGS_FILE);
+  return isPlainObject(stored) ? stored : null;
+}
+function saveSettings(settings) {
+  writePrivate(agentHome(), SETTINGS_FILE, settings);
+}
 function defaultEndpoints() {
   return {
     api_base: process.env.ZAS_API_BASE || "https://zas.red/api",
@@ -1636,15 +1644,15 @@ async function uploadFallback(options) {
   const key = await aesKey(meta);
   const completed = [];
   const partProgress = /* @__PURE__ */ new Map();
-  const report = () => options.onProgress?.(
+  const report2 = () => options.onProgress?.(
     Math.min(meta.cipher_size, [...partProgress.values()].reduce((sum, value) => sum + value, 0)),
     meta.cipher_size
   );
   for (let first = 1; first <= meta.part_count; first += URL_BATCH) {
     aborted(signal);
-    const count = Math.min(URL_BATCH, meta.part_count - first + 1);
-    const signed = await options.getUrls(first, count);
-    if (signed.length !== count || signed.some((entry, i) => entry.part_number !== first + i || typeof entry.url !== "string")) throw new Error("bad_fallback_urls");
+    const count2 = Math.min(URL_BATCH, meta.part_count - first + 1);
+    const signed = await options.getUrls(first, count2);
+    if (signed.length !== count2 || signed.some((entry, i) => entry.part_number !== first + i || typeof entry.url !== "string")) throw new Error("bad_fallback_urls");
     let cursor = 0;
     const workers = Array.from({ length: Math.min(CONCURRENCY, signed.length) }, async () => {
       for (; ; ) {
@@ -1661,11 +1669,11 @@ async function uploadFallback(options) {
         for (let attempt = 0; attempt < RETRIES; attempt++) {
           aborted(signal);
           partProgress.set(partNumber, 0);
-          report();
+          report2();
           try {
             etag = await options.put(entry.url, cipher, signal, (loaded) => {
               partProgress.set(partNumber, loaded);
-              report();
+              report2();
             });
             break;
           } catch (error) {
@@ -2472,7 +2480,7 @@ function sealer(key, keyVersion) {
     open: (enc) => JSON.parse(new TextDecoder().decode(openRaw(key, b64ToBytes(enc))))
   };
 }
-async function sendDirect(ctx, input, report, deps = {}) {
+async function sendDirect(ctx, input, report2, deps = {}) {
   const now = deps.now ?? (() => Date.now());
   const sleep2 = deps.sleep ?? defaultSleep2;
   const grant = await directGrantFor(ctx, input.channel);
@@ -2489,7 +2497,7 @@ async function sendDirect(ctx, input, report, deps = {}) {
   const { seal, open } = sealer(key, grant.key_version);
   const stamp = { device, owner_uid: owner };
   const startedAt = now();
-  report("offer");
+  report2("offer");
   const meta = { name, size: file.size, mime: mimeFor(input.path) };
   const { id } = await ctx.client.api("POST", `/direct/${cid}`, {
     meta_enc: seal(meta),
@@ -2523,7 +2531,7 @@ async function sendDirect(ctx, input, report, deps = {}) {
     }
   };
   const turn = await fetchIce();
-  report("connecting");
+  report2("connecting");
   let resolveOutcome;
   const outcome = new Promise((resolve2) => {
     resolveOutcome = resolve2;
@@ -2540,7 +2548,7 @@ async function sendDirect(ctx, input, report, deps = {}) {
     send: (msg) => ctx.client.api("POST", `${route}/signal`, { payload_enc: seal(msg), for: "receiver", ...stamp }).then(() => void 0),
     onPhase: (phase2) => {
       if (phase2 === "flight") {
-        report("flight");
+        report2("flight");
         heartbeat ??= setInterval(() => {
           void ctx.client.api("POST", `${route}/heartbeat`, stamp).catch(() => void 0);
         }, deps.heartbeatMs ?? HEARTBEAT_MS);
@@ -2580,7 +2588,7 @@ async function sendDirect(ctx, input, report, deps = {}) {
   over = true;
   clearInterval(heartbeat);
   await pump;
-  report("finishing");
+  report2("finishing");
   if (phase === "done") {
     await setState("done");
     return {
@@ -2619,7 +2627,7 @@ var fetchPut = async (url, bytes, signal, onLoaded) => {
   onLoaded(bytes.length);
   return etag;
 };
-async function sendDirectFallback(ctx, record, report, deps = {}) {
+async function sendDirectFallback(ctx, record, report2, deps = {}) {
   const now = deps.now ?? (() => Date.now());
   const startedAt = now();
   const opened = await (deps.openFile ?? openAsBlob)(record.path).catch(() => {
@@ -2630,7 +2638,7 @@ async function sendDirectFallback(ctx, record, report, deps = {}) {
   const { seal } = sealer(record.key, record.key_version);
   const stamp = { device: record.device, owner_uid: record.owner_uid };
   const base = `/direct/${record.channel_id}/${record.offer_id}/fallback`;
-  report("encrypting");
+  report2("encrypting");
   const meta = createFallbackMeta(file);
   await ctx.client.api("POST", `${base}/start`, {
     meta_enc: seal(meta),
@@ -2639,7 +2647,7 @@ async function sendDirectFallback(ctx, record, report, deps = {}) {
     part_count: meta.part_count,
     ...stamp
   });
-  report("uploading");
+  report2("uploading");
   let parts;
   try {
     parts = await uploadFallback({
@@ -2647,11 +2655,11 @@ async function sendDirectFallback(ctx, record, report, deps = {}) {
       offerId: record.offer_id,
       meta,
       put: deps.put ?? fetchPut,
-      getUrls: async (from, count) => {
+      getUrls: async (from, count2) => {
         const r = await ctx.client.api(
           "POST",
           `${base}/parts`,
-          { from, count, ...stamp }
+          { from, count: count2, ...stamp }
         );
         return r.urls;
       }
@@ -2661,7 +2669,7 @@ async function sendDirectFallback(ctx, record, report, deps = {}) {
     if (error instanceof ZasError) throw error;
     throw new ZasError("upload_failed", 0, error instanceof Error ? error.message : String(error));
   }
-  report("finishing");
+  report2("finishing");
   await ctx.client.api("POST", `${base}/complete`, {
     parts: parts.map((part) => ({ part_number: part.partNumber, etag: part.etag })),
     ...stamp
@@ -3047,7 +3055,7 @@ var DiskSink = class {
     return error;
   }
 };
-async function receiveDirect(ctx, input, report, deps = {}) {
+async function receiveDirect(ctx, input, report2, deps = {}) {
   const now = deps.now ?? (() => Date.now());
   const sleep2 = deps.sleep ?? defaultSleep2;
   const grant = await receiveGrantFor(ctx, input.channel);
@@ -3060,7 +3068,7 @@ async function receiveDirect(ctx, input, report, deps = {}) {
   const stamp = { device, owner_uid: owner };
   const startedAt = now();
   const channelPath = `accounts/${owner}/channels/${cid}`;
-  report("waiting");
+  report2("waiting");
   const waitUntil = startedAt + (deps.offerWaitMs ?? OFFER_WAIT_MS2);
   let id;
   let meta;
@@ -3112,7 +3120,7 @@ async function receiveDirect(ctx, input, report, deps = {}) {
     }
   };
   const turn = await fetchIce();
-  report("connecting");
+  report2("connecting");
   const sink = new DiskSink(input.dest, offerId);
   let resolveOutcome;
   const outcome = new Promise((resolve2) => {
@@ -3128,7 +3136,7 @@ async function receiveDirect(ctx, input, report, deps = {}) {
     expectedMeta: offered,
     send: (msg) => ctx.client.api("POST", `${route}/signal`, { payload_enc: seal(msg), for: "sender", ...stamp }).then(() => void 0),
     onPhase: (phase2) => {
-      if (phase2 === "flight") report("flight");
+      if (phase2 === "flight") report2("flight");
       if (phase2 === "done" || phase2 === "failed") resolveOutcome(phase2);
     },
     onPath: (p) => {
@@ -3167,7 +3175,7 @@ async function receiveDirect(ctx, input, report, deps = {}) {
   const phase = await outcome;
   over = true;
   await pump;
-  report("finishing");
+  report2("finishing");
   if (phase === "done") {
     await setState("done");
     return {
@@ -3202,7 +3210,7 @@ async function receiveDirect(ctx, input, report, deps = {}) {
   });
   throw new ZasError("direct_failed", 0, reason);
 }
-async function receiveDirectFallback(ctx, record, report, deps = {}) {
+async function receiveDirectFallback(ctx, record, report2, deps = {}) {
   const now = deps.now ?? (() => Date.now());
   const startedAt = now();
   const { open } = sealer(record.key, record.key_version);
@@ -3224,7 +3232,7 @@ async function receiveDirectFallback(ctx, record, report, deps = {}) {
     throw new ZasError("file_changed", 0);
   }
   const sink = new DiskSink(record.dest, record.offer_id);
-  report("downloading");
+  report2("downloading");
   try {
     sink.open(meta);
     await downloadFallback({
@@ -3240,7 +3248,7 @@ async function receiveDirectFallback(ctx, record, report, deps = {}) {
     if (error instanceof ZasError) throw error;
     throw new ZasError("network", 0, error instanceof Error ? error.message : String(error));
   }
-  report("finishing");
+  report2("finishing");
   await ctx.client.api("POST", `${base}/received`, stamp);
   return {
     offer_id: record.offer_id,
@@ -3281,10 +3289,10 @@ var JobRunner = class {
     };
     this.jobs.unshift(job);
     this.jobs.length = Math.min(this.jobs.length, HISTORY);
-    const report = (phase) => {
+    const report2 = (phase) => {
       if (job.status === "running") job.phase = phase;
     };
-    this.settled.set(job, work(report).then(
+    this.settled.set(job, work(report2).then(
       (result) => {
         job.status = "done";
         job.result = result;
@@ -3328,9 +3336,477 @@ var JobRunner = class {
   }
 };
 
+// src/shared/product-analytics.ts
+var PRODUCT_EVENTS = [
+  "account_created",
+  "item.created",
+  "item.downloaded",
+  "item.copied",
+  "item.shared",
+  "item.pinned",
+  "item.unpinned",
+  "item.deleted",
+  "item.departed",
+  "channel_shared",
+  "channel_mode_set",
+  "invite_created",
+  "invite_link_copied",
+  "invite_qr_shown",
+  "invite_system_sheet_opened",
+  "invite_joined",
+  "invite_converted",
+  "channel.invite_preview",
+  "channel.invite_accept",
+  "channel.invite_signin",
+  "enterprise.invite_preview",
+  "enterprise.invite_identity",
+  "enterprise.invite_signin",
+  "enterprise.invite_account_switch",
+  "enterprise.invite_attach",
+  "enterprise.invite_accept",
+  "enterprise.invite_admin",
+  "enterprise.workspace_opened",
+  "enterprise.workspace_switched",
+  "enterprise.channel_created",
+  "enterprise.channel_members_added",
+  "share_link_copied",
+  "share_qr_shown",
+  "share_system_sheet_opened",
+  "share_opened",
+  "share_content_copied",
+  "share_downloaded",
+  "share_signin_click",
+  "share.saved",
+  "share_bar_on",
+  "share_bar_off",
+  "upload.phase_timing",
+  "auth.signin_started",
+  "auth.signin_result",
+  "auth.session_started",
+  "auth.signed_out",
+  "auth.session_lost",
+  "auth.token_refresh_failed",
+  "account_switch.started",
+  "account_switch.completed",
+  "account_switch.failed",
+  "bootstrap.result",
+  "direct_mode_set",
+  "direct.offered",
+  "direct.claimed",
+  "direct.connected",
+  "direct.completed",
+  "direct.received",
+  "direct.failed",
+  "direct.fallback_started",
+  "direct.fallback_ready",
+  "direct.fallback_received",
+  "direct.fallback_failed",
+  "direct.fallback_aborted",
+  "direct.too_big",
+  "agent.pair_opened",
+  "agent.pair_approved",
+  "agent.pair_refused",
+  "agent.paired",
+  "agent.revoked",
+  "agent.send",
+  "agent.tool_call"
+];
+var SERVER_OWNED_PRODUCT_EVENTS = [
+  "account_created",
+  "item.departed",
+  "invite_created",
+  "invite_joined",
+  "invite_converted",
+  "share_opened",
+  "share_content_copied",
+  "share_downloaded",
+  "share_signin_click",
+  "agent.send",
+  "agent.tool_call"
+];
+var SERVER_OWNED_PRODUCT_EVENT_SET = new Set(SERVER_OWNED_PRODUCT_EVENTS);
+var CLIENT_PRODUCT_EVENTS = PRODUCT_EVENTS.filter(
+  (event) => !SERVER_OWNED_PRODUCT_EVENT_SET.has(event)
+);
+var bool = { type: "boolean" };
+var count = { type: "number", min: 0 };
+var oneOf = (...values) => ({ type: "string", values: new Set(values) });
+var sizeBucket = oneOf("lt_1mb", "1_10mb", "10_100mb", "100_512mb", "512mb_5gb", "gt_5gb");
+var itemKind = oneOf("file", "text");
+var itemKindOrUnknown = oneOf("file", "text", "unknown");
+var role = oneOf("sender", "receiver");
+var candidateType = oneOf("", "host", "srflx", "relay", "prflx", "other");
+var enterpriseRole = oneOf("owner", "admin", "billing_admin", "member", "guest");
+var agentKind = oneOf("claude_code", "codex", "other");
+var pairHandoff = oneOf("loopback", "manual", "unknown");
+var AGENT_TOOL_NAMES = [
+  "status",
+  "pair",
+  "send_file",
+  "send_note",
+  "send_direct",
+  "send_direct_fallback",
+  "receive_direct",
+  "receive_direct_fallback",
+  "list_items",
+  "get_item",
+  "jobs"
+];
+var AGENT_ERROR_CODES = [
+  "none",
+  "other",
+  "identity_corrupt",
+  "not_paired",
+  "internal",
+  "agent_forbidden",
+  "agent_revoked",
+  "grant_missing",
+  "not_found",
+  "invalid_cap",
+  "write_failed",
+  "send_forbidden",
+  "read_forbidden",
+  "direct_mode",
+  "not_direct_mode",
+  "not_claimed",
+  "no_offer",
+  "offer_taken",
+  "direct_cancelled",
+  "direct_failed",
+  "direct_not_failed",
+  "file_changed",
+  "webrtc_unavailable",
+  "fallback_unavailable",
+  "key_stale",
+  "quota_exceeded",
+  "rate_limited",
+  "file_too_big",
+  "duplicate",
+  "pairing_expired",
+  "pairing_cancelled",
+  "claim_mismatch",
+  "pairing_not_approved",
+  "pairing_claimed",
+  "agent_limit",
+  "grant_limit",
+  "feature_disabled",
+  "upload_failed",
+  "oprf_failed",
+  "network",
+  "sign_in_failed",
+  "bad_signature",
+  "missing_token"
+];
+function agentDurationBucket(ms) {
+  if (ms < 1e3) return "lt_1s";
+  if (ms < 1e4) return "1_10s";
+  if (ms < 6e4) return "10_60s";
+  return "gt_60s";
+}
+var EVENT_PROPERTY_RULES = {
+  account_created: {},
+  "item.created": { kind: itemKind, size_bytes: count, size_bucket: sizeBucket },
+  "item.downloaded": { size_bytes: count, size_bucket: sizeBucket },
+  "item.copied": {},
+  "item.shared": { kind: itemKind },
+  "item.pinned": { age_ms: count },
+  "item.unpinned": {},
+  "item.deleted": { age_ms: count, was_pinned: bool, kind: itemKindOrUnknown },
+  "item.departed": {},
+  channel_shared: {},
+  channel_mode_set: { mode: oneOf("edit", "view") },
+  invite_created: {},
+  invite_link_copied: {},
+  invite_qr_shown: {},
+  invite_system_sheet_opened: {},
+  invite_joined: {},
+  invite_converted: {},
+  "channel.invite_preview": {
+    outcome: oneOf("ready", "unavailable", "missing_key"),
+    signed_in: bool
+  },
+  "channel.invite_accept": {
+    outcome: oneOf("started", "completed", "already_member", "unavailable", "failed")
+  },
+  "channel.invite_signin": {
+    stage: oneOf("link_requested", "link_sent", "link_completed", "failed")
+  },
+  "enterprise.invite_preview": {
+    outcome: oneOf("pending", "resumable", "unavailable"),
+    role: enterpriseRole
+  },
+  "enterprise.invite_identity": {
+    outcome: oneOf("matched", "mismatched", "unavailable", "failed")
+  },
+  "enterprise.invite_signin": {
+    stage: oneOf("link_requested", "link_sent", "link_completed", "failed")
+  },
+  "enterprise.invite_account_switch": { stage: oneOf("started", "completed", "failed") },
+  "enterprise.invite_attach": {
+    stage: oneOf("link_requested", "link_sent", "verify_started", "completed", "address_taken", "link_invalid", "failed")
+  },
+  "enterprise.invite_accept": {
+    outcome: oneOf("started", "completed", "recovered", "timeout", "unavailable", "email_mismatch", "seat_limit", "failed"),
+    role: enterpriseRole,
+    destination: oneOf("workspace", "admin_console"),
+    duration_ms: count
+  },
+  "enterprise.invite_admin": {
+    outcome: oneOf("created", "email_sent", "email_failed", "reissued", "revoked"),
+    role: enterpriseRole,
+    external: bool
+  },
+  "enterprise.workspace_opened": { role: enterpriseRole, first_visit: bool },
+  "enterprise.workspace_switched": { destination: oneOf("personal", "organization"), role: enterpriseRole },
+  "enterprise.channel_created": { member_count: count },
+  "enterprise.channel_members_added": { member_count: count },
+  share_link_copied: {},
+  share_qr_shown: {},
+  share_system_sheet_opened: {},
+  share_opened: {},
+  share_content_copied: {},
+  share_downloaded: {},
+  share_signin_click: {},
+  "share.saved": {},
+  share_bar_on: {},
+  share_bar_off: {},
+  "upload.phase_timing": {
+    stage: oneOf("staging", "bootstrap", "thumbnail", "encrypting", "uploading", "finishing"),
+    duration_ms: count,
+    size_bucket: sizeBucket,
+    outcome: oneOf("success", "failure", "cancelled"),
+    attempt: { type: "number", min: 1 }
+  },
+  "auth.signin_started": { provider: oneOf("google.com", "apple.com") },
+  "auth.signin_result": {
+    provider: oneOf("google.com", "apple.com"),
+    outcome: oneOf("signed_in", "cancelled", "taken", "failed", "needs_link"),
+    flow: oneOf("signin", "link", "connect")
+  },
+  "account_switch.started": { operation: oneOf("remember", "switch"), provider: oneOf("google.com", "apple.com", "email_link", "qr", "code") },
+  "account_switch.completed": { operation: oneOf("remember", "switch"), provider: oneOf("google.com", "apple.com", "email_link", "qr", "code") },
+  "account_switch.failed": { operation: oneOf("remember", "switch"), provider: oneOf("google.com", "apple.com", "email_link", "qr", "code") },
+  "auth.session_started": { cold: bool },
+  "auth.signed_out": { reason: oneOf("user", "account_switch", "abandoned_new_account", "account_deleted") },
+  "auth.session_lost": { session_age_ms: count, foreground: bool },
+  "auth.token_refresh_failed": {
+    code: oneOf("network", "token_invalid", "user_disabled", "user_missing", "rate_limited", "internal", "unknown")
+  },
+  "bootstrap.result": {
+    outcome: oneOf("offline", "ok", "timeout_warm", "timeout", "failed_warm", "failed"),
+    stage: oneOf("cached", "done", "unknown", "keyring", "account_init", "listeners"),
+    duration_ms: count,
+    fault: oneOf("intercepted", "offline", "unknown")
+  },
+  direct_mode_set: { on: bool },
+  "direct.offered": { size_bucket: sizeBucket },
+  // `via_agent`: the offer came from a paired agent's process, not from one
+  // of the person's devices. The claim and the two receiver outcomes carry it.
+  "direct.claimed": { size_bucket: sizeBucket, via_agent: bool },
+  "direct.connected": { role, ms: count },
+  "direct.completed": {
+    via: oneOf("lan", "wan", "relay", "unknown"),
+    pair_local: candidateType,
+    pair_remote: candidateType,
+    connect_ms: count,
+    duration_ms: count,
+    size_bucket: sizeBucket,
+    turn_urls_supplied: count,
+    turn_urls_configured: count,
+    restarts: count
+  },
+  "direct.received": {
+    via_agent: bool,
+    via: oneOf("lan", "wan", "relay", "unknown"),
+    pair_local: candidateType,
+    pair_remote: candidateType,
+    connect_ms: count,
+    duration_ms: count,
+    size_bucket: sizeBucket,
+    turn_urls_supplied: count,
+    turn_urls_configured: count,
+    restarts: count
+  },
+  "direct.failed": {
+    role,
+    via_agent: bool,
+    reason: oneOf(
+      "peer_silent",
+      "connect_timeout",
+      "ice_failed",
+      "disconnected",
+      "peer_closed",
+      "peer_abort",
+      "signaling",
+      "signal_send",
+      "protocol",
+      "sink",
+      "transfer",
+      "integrity",
+      "too_big",
+      "unknown"
+    ),
+    ms: count,
+    ice_state: oneOf("", "new", "checking", "connected", "completed", "failed", "disconnected", "closed"),
+    gather_state: oneOf("", "new", "gathering", "complete"),
+    had_remote: bool,
+    local_host: count,
+    local_srflx: count,
+    local_relay: count,
+    remote_host: count,
+    remote_srflx: count,
+    remote_relay: count,
+    turn_urls_supplied: count,
+    turn_urls_configured: count,
+    moved_bucket: sizeBucket,
+    size_bucket: sizeBucket,
+    restarts: count,
+    // Whether the reporting tab was on screen when the run died — the lead a
+    // slept machine or a frozen background tab leaves behind.
+    visibility: oneOf("visible", "hidden", "prerender")
+  },
+  "direct.fallback_started": { size_bucket: sizeBucket },
+  "direct.fallback_ready": { size_bucket: sizeBucket, duration_ms: count, retries: count },
+  "direct.fallback_received": { size_bucket: sizeBucket, duration_ms: count, retries: count },
+  "direct.fallback_failed": {
+    stage: oneOf("upload", "download"),
+    size_bucket: sizeBucket,
+    retries: count
+  },
+  "direct.fallback_aborted": {},
+  "direct.too_big": { size_bucket: sizeBucket },
+  "agent.pair_opened": { agent_kind: agentKind, protocol: count, replaces: bool },
+  "agent.pair_approved": {
+    agent_kind: agentKind,
+    destination: oneOf("new_channel", "existing"),
+    channels: count,
+    handoff: pairHandoff
+  },
+  "agent.pair_refused": {
+    agent_kind: agentKind,
+    step: oneOf("open", "approve", "claim"),
+    reason: oneOf(
+      "agent_limit",
+      "grant_limit",
+      "channel_limit",
+      "code_mismatch",
+      "pairing_expired",
+      "pairing_cancelled",
+      "pairing_claimed",
+      "feature_disabled",
+      "rate_limited",
+      "network",
+      "other"
+    )
+  },
+  "agent.paired": {
+    agent_kind: agentKind,
+    destination: oneOf("new_channel", "existing"),
+    channels: count,
+    handoff: pairHandoff,
+    protocol: count
+  },
+  "agent.revoked": { agent_kind: agentKind },
+  "agent.send": { size_bucket: sizeBucket, agent_kind: agentKind },
+  // What the CLI reports after every tool call: the tool, whether it worked,
+  // the code when it did not, and the version that answered. No path, no file
+  // name, no channel, no sentence.
+  "agent.tool_call": {
+    tool: oneOf(...AGENT_TOOL_NAMES),
+    result: oneOf("ok", "error"),
+    code: oneOf(...AGENT_ERROR_CODES),
+    agent_kind: agentKind,
+    duration_bucket: oneOf("lt_1s", "1_10s", "10_60s", "gt_60s"),
+    version_major: count,
+    version_minor: count,
+    version_patch: count
+  }
+};
+var platformRule = oneOf("web", "android", "ios", "agent", "unknown");
+var PERSON_PROPERTY_RULES = {
+  plan: oneOf("anon", "free", "pro", "max"),
+  locale: oneOf("es-AR", "pt-BR", "en"),
+  storage_bytes: count
+};
+
+// src/telemetry.ts
+var OFF_WORDS = /* @__PURE__ */ new Set(["0", "off", "false", "no"]);
+var ON_WORDS = /* @__PURE__ */ new Set(["1", "on", "true", "yes"]);
+function telemetryState() {
+  const env = (process.env.ZAS_AGENT_TELEMETRY ?? "").toLowerCase();
+  if (OFF_WORDS.has(env)) return { on: false, source: "env" };
+  if (ON_WORDS.has(env)) return { on: true, source: "env" };
+  if (process.env.DO_NOT_TRACK === "1") return { on: false, source: "do_not_track" };
+  const stored = loadSettings();
+  if (stored && typeof stored.telemetry === "boolean") return { on: stored.telemetry, source: "file" };
+  return { on: true, source: "default" };
+}
+function setTelemetry(on) {
+  const stored = loadSettings();
+  saveSettings({ ...stored ?? {}, version: 1, telemetry: on, decided_at: Date.now() });
+}
+function noticeShown() {
+  return typeof loadSettings()?.notified_at === "number";
+}
+function markNoticeShown() {
+  const stored = loadSettings();
+  saveSettings({ ...stored ?? {}, version: 1, notified_at: Date.now() });
+}
+var TELEMETRY_NOTICE = [
+  "Zas collects usage data from this agent to improve the product: which tool",
+  "ran, whether it worked, the error code when it did not, how long it took,",
+  "and the version. Never file names, file contents, paths or channel names.",
+  "The data is linked to your Zas account.",
+  "Turn it off with: npx -y zas-agent telemetry off"
+].join("\n");
+var SOURCE_WORDS = {
+  env: "ZAS_AGENT_TELEMETRY",
+  do_not_track: "DO_NOT_TRACK",
+  file: "zas-agent telemetry",
+  default: "default"
+};
+function telemetryLine() {
+  const state = telemetryState();
+  return `telemetry: ${state.on ? "on" : "off"} (${SOURCE_WORDS[state.source]})`;
+}
+var TOOL_NAMES = new Set(AGENT_TOOL_NAMES);
+function versionParts(version) {
+  const [major = 0, minor = 0, patch = 0] = version.split("-")[0].split(".").map((part) => {
+    const value = Number.parseInt(part, 10);
+    return Number.isFinite(value) && value >= 0 ? value : 0;
+  });
+  return { major, minor, patch };
+}
+function toolCallProperties(input) {
+  const tool = input.tool.startsWith("zas_") ? input.tool.slice(4) : input.tool;
+  if (!TOOL_NAMES.has(tool)) return null;
+  const version = versionParts(input.version);
+  return {
+    tool,
+    result: input.code === null ? "ok" : "error",
+    // `other` is the server's word for a code outside the vocabulary. The
+    // shared list is the one that decides, and it drops anything else.
+    code: input.code ?? "none",
+    duration_bucket: agentDurationBucket(input.ms),
+    version_major: version.major,
+    version_minor: version.minor,
+    version_patch: version.patch
+  };
+}
+var REPORT_TIMEOUT_MS = 5e3;
+async function report(client, properties) {
+  if (properties === null || !telemetryState().on) return;
+  const timeout = new Promise((resolve2) => {
+    const timer = setTimeout(resolve2, REPORT_TIMEOUT_MS);
+    timer.unref?.();
+  });
+  const sent = client.api("POST", "/agents/telemetry", { event: "agent.tool_call", properties }).then(() => void 0).catch(() => void 0);
+  await Promise.race([sent, timeout]);
+}
+
 // src/server.ts
 function agentVersion() {
-  return true ? "0.5.1" : "0.0.0-dev";
+  return true ? "0.6.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;
@@ -3344,9 +3820,33 @@ function rightsOf(grant) {
   if (grant.read) rights.push(grant.direct_mode ? "receive (Directo)" : "read");
   return rights.length > 0 ? rights.join(" \xB7 ") : "no access";
 }
+function answeredCode(answer) {
+  if (!answer?.isError) return null;
+  const match = /^([a-z_]{2,40}):/.exec(answer.content?.[0]?.text ?? "");
+  return match ? match[1] : "other";
+}
 function buildServer(profile, deps = {}) {
   const server = new McpServer({ name: "zas", version: agentVersion() });
   const runner = deps.runner ?? new JobRunner();
+  const reportCall = async (tool, ms, code) => {
+    try {
+      if (!(deps.identity ?? loadIdentity(profile))) return;
+      await report(ctx().client, toolCallProperties({ tool, ms, code, version: agentVersion() }));
+    } catch {
+    }
+  };
+  const registerRaw = server.registerTool.bind(server);
+  server.registerTool = (name, meta, handler) => registerRaw(name, meta, async (...args) => {
+    const started = Date.now();
+    try {
+      const answer = await handler(...args);
+      void reportCall(name, Date.now() - started, answeredCode(answer));
+      return answer;
+    } catch (e) {
+      void reportCall(name, Date.now() - started, e instanceof ZasError ? e.code : "internal");
+      throw e;
+    }
+  });
   let client = null;
   const ctx = () => {
     const identity = deps.identity ?? loadIdentity(profile);
@@ -3394,7 +3894,8 @@ function buildServer(profile, deps = {}) {
         `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 profile ${profile}`
+        `${packageName()} ${agentVersion()} \xB7 profile ${profile}`,
+        `${telemetryLine()} \xB7 change it with \u201Cnpx -y ${packageName()} telemetry off\u201D`
       ].join("\n"));
     } catch (e) {
       return failed(e);
@@ -3488,7 +3989,7 @@ function buildServer(profile, deps = {}) {
         "file",
         input.title ?? input.path,
         input.channel ?? "",
-        (report) => sendFile(c, input, report)
+        (report2) => sendFile(c, input, report2)
       );
       return settled(await runner.wait(job));
     } catch (e) {
@@ -3514,7 +4015,7 @@ function buildServer(profile, deps = {}) {
         "direct",
         input.path,
         input.channel ?? "",
-        (report) => sendDirect(c, input, report, {
+        (report2) => sendDirect(c, input, report2, {
           ...deps.direct ?? {},
           onFailed: (record) => rememberFailed(job.id, record)
         })
@@ -3538,7 +4039,7 @@ function buildServer(profile, deps = {}) {
         "fallback",
         record.name,
         record.channel_name,
-        (report) => sendDirectFallback(c, record, report, deps.direct)
+        (report2) => sendDirectFallback(c, record, report2, deps.direct)
       );
       const outcome = await runner.wait(job);
       if (outcome.status === "done") failedDirects.delete(input.job);
@@ -3566,7 +4067,7 @@ function buildServer(profile, deps = {}) {
         "receive",
         input.dest ?? "Directo",
         input.channel ?? "",
-        (report) => receiveDirect(c, input, report, {
+        (report2) => receiveDirect(c, input, report2, {
           ...deps.receive ?? {},
           onFailed: (record) => rememberFailedReceive(job.id, record)
         })
@@ -3590,7 +4091,7 @@ function buildServer(profile, deps = {}) {
         "fallback",
         record.meta.name,
         record.channel_name,
-        (report) => receiveDirectFallback(c, record, report, deps.receive)
+        (report2) => receiveDirectFallback(c, record, report2, deps.receive)
       );
       const outcome = await runner.wait(job);
       if (outcome.status === "done") failedReceives.delete(input.job);
@@ -3667,7 +4168,16 @@ function parseArgs(argv) {
     const inline = arg.startsWith("--") && eq > 0 ? arg.slice(eq + 1) : void 0;
     const take = () => inline !== void 0 ? inline : argv[++i] ?? "";
     if (name === "pair") parsed.command = "pair";
-    else if (name === "--version" || name === "-v") parsed.command = "version";
+    else if (name === "telemetry") {
+      parsed.command = "telemetry";
+      const next = argv[i + 1];
+      if (next === "on" || next === "off") {
+        parsed.telemetry = next;
+        i++;
+      } else if (next !== void 0 && !next.startsWith("--")) {
+        return { ...parsed, command: "invalid", message: `Unknown telemetry setting \u201C${next}\u201D. Use \u201Con\u201D or \u201Coff\u201D.` };
+      }
+    } else if (name === "--version" || name === "-v") parsed.command = "version";
     else if (name === "--help" || name === "-h") parsed.command = "help";
     else if (name === "--profile") {
       parsed.profile = take() || DEFAULT_PROFILE;
@@ -3690,6 +4200,7 @@ var USAGE = [
   "  zas-agent [--profile <name>]                serve the MCP tools over stdio",
   "  zas-agent pair [--profile <name>]           pair this agent with a Zas account",
   "                 [--kind claude_code|codex|other] [--host <name>] [--no-open]",
+  "  zas-agent telemetry [on|off]                say what this machine reports, or change it",
   "  zas-agent --version"
 ].join("\n");
 async function main(argv, log = (l) => console.error(l)) {
@@ -3707,7 +4218,17 @@ async function main(argv, log = (l) => console.error(l)) {
     log(USAGE);
     return args.unknown ? 2 : 0;
   }
+  if (args.command === "telemetry") {
+    if (args.telemetry) setTelemetry(args.telemetry === "on");
+    markNoticeShown();
+    log(telemetryLine());
+    log(args.telemetry === "off" ? `Nothing is sent. Turn it on again with: npx -y ${packageName()} telemetry on` : TELEMETRY_NOTICE);
+    return 0;
+  }
   if (args.command === "pair") {
+    log(TELEMETRY_NOTICE);
+    log("");
+    markNoticeShown();
     let rl = null;
     const askCode = process.stdin.isTTY ? () => {
       rl ??= createInterface({ input: process.stdin, output: process.stderr });
@@ -3736,6 +4257,10 @@ async function main(argv, log = (l) => console.error(l)) {
     }
     return 0;
   }
+  if (!noticeShown()) {
+    log(TELEMETRY_NOTICE);
+    markNoticeShown();
+  }
   await buildServer(args.profile).connect(new StdioServerTransport());
   return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zas-agent",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "MCP server that lets a coding agent send files and notes into your Zas channels, and send or receive files live through Directo.",
   "type": "module",
   "license": "MIT",