zas-agent 0.5.1 → 0.6.1

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",
@@ -822,89 +830,6 @@ async function runPair(opts) {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
-// src/direct.ts
-import { randomBytes } from "node:crypto";
-import { openAsBlob } from "node:fs";
-import { basename as basename2 } from "node:path";
-
-// src/shared/manifest.ts
-import { xchacha20poly1305 } from "@noble/ciphers/chacha";
-
-// src/shared/constants.ts
-var CHUNKER_VERSION = "chunker_v1";
-var CHUNK_MIN = 1 * 1024 * 1024;
-var CHUNK_AVG_BITS = 22;
-var CHUNK_MAX = 8 * 1024 * 1024;
-var STORAGE_V2_PART_BYTES = 16 * 1024 * 1024;
-var GEAR_SEED = "zas-gear-v1:";
-var HKDF_INFO_CHUNK_KEY = "zas-chunk-key-v1";
-var HKDF_INFO_CHUNK_NONCE = "zas-chunk-nonce-v1";
-var OPRF_CONTEXT = "OPRFV1-\0-ristretto255-SHA512";
-var MANIFEST_VERSION = 1;
-var ANON_EMPTY_TTL_MS = 30 * 60 * 1e3;
-var FREE_RELAY_MAX_BYTES = 50 * 1024 * 1024;
-var SAFE_STORED_FILE_LIMITS = {
-  anon: 30 * 1024 * 1024,
-  free: FREE_RELAY_MAX_BYTES,
-  pro: 200 * 1024 * 1024,
-  max: 200 * 1024 * 1024
-};
-var STORED_FILE_LIMITS_V2 = {
-  anon: 30 * 1024 * 1024,
-  free: FREE_RELAY_MAX_BYTES,
-  pro: 5 * 1024 * 1024 * 1024,
-  max: 20 * 1024 * 1024 * 1024
-};
-var STORAGE_LIMITS = {
-  anon: 30 * 1024 * 1024,
-  free: 100 * 1024 * 1024,
-  pro: null,
-  max: null
-};
-var THUMBNAIL_MAX_EDGE = 640;
-var THUMBNAIL_MAX_BYTES = 14e4;
-
-// src/shared/manifest.ts
-function newManifest(partial) {
-  return { v: MANIFEST_VERSION, chunker: CHUNKER_VERSION, ...partial };
-}
-var ENVELOPE_MAGIC = 90;
-var KEY_VERSION_LEGACY = 1;
-function envelopeVersion(sealed) {
-  if (sealed.length > 26 && sealed[0] === ENVELOPE_MAGIC && sealed[1] >= 1) return sealed[1];
-  return KEY_VERSION_LEGACY;
-}
-function sealBytes(key, version, plain) {
-  if (version < 1 || version > 255) throw new Error("key version out of range");
-  const nonce = new Uint8Array(24);
-  crypto.getRandomValues(nonce);
-  const ct = xchacha20poly1305(key, nonce).encrypt(plain);
-  return concatBytes(new Uint8Array([ENVELOPE_MAGIC, version]), nonce, ct);
-}
-function openSealed(key, sealed) {
-  const versioned = envelopeVersion(sealed) !== KEY_VERSION_LEGACY || sealed[0] === ENVELOPE_MAGIC;
-  if (versioned && sealed.length > 26) {
-    try {
-      return xchacha20poly1305(key, sealed.slice(2, 26)).decrypt(sealed.slice(26));
-    } catch {
-    }
-  }
-  return xchacha20poly1305(key, sealed.slice(0, 24)).decrypt(sealed.slice(24));
-}
-var sealRaw = sealBytes;
-var openRaw = openSealed;
-function sealManifest(channelKey, manifest, version = KEY_VERSION_LEGACY) {
-  return sealBytes(channelKey, version, new TextEncoder().encode(JSON.stringify(manifest)));
-}
-function openManifest(channelKey, sealed) {
-  const m = JSON.parse(new TextDecoder().decode(openSealed(channelKey, sealed)));
-  if (!Array.isArray(m.chunks)) m.chunks = [];
-  return m;
-}
-function decryptChannelName(channelKey, sealed) {
-  return new TextDecoder().decode(openSealed(channelKey, sealed));
-}
-
 // src/shared/direct.ts
 var DIRECT_OFFER_TTL_MS = 10 * 60 * 1e3;
 var DIRECT_CLAIMED_TTL_MS = 6 * 60 * 60 * 1e3;
@@ -940,6 +865,13 @@ var FRAME_CHUNK = 2;
 var FRAME_DONE = 3;
 var FRAME_ABORT = 4;
 var FRAME_CREDIT = 5;
+function directMetaOf(file, fallbackName) {
+  return {
+    name: file.name || fallbackName || "zas",
+    size: file.size,
+    mime: file.type || "application/octet-stream"
+  };
+}
 function encodeMeta(meta) {
   const body = new TextEncoder().encode(JSON.stringify(meta));
   const frame = new Uint8Array(1 + body.length);
@@ -1012,9 +944,63 @@ function candType(candidate) {
   const m = /\styp\s+(\S+)/.exec(candidate?.candidate ?? "");
   return m ? m[1] : "other";
 }
+function candProto(candidate) {
+  const line = candidate?.candidate ?? "";
+  const m = /^(?:a=)?(?:candidate:)?\S+\s+\d+\s+(\S+)/.exec(line);
+  const proto = m ? m[1].toLowerCase() : "?";
+  const tcp = /\stcptype\s+(\S+)/.exec(line);
+  return tcp ? `${proto}/${tcp[1]}` : proto;
+}
+var TRACE_MAX = 200;
+var DETAIL_MAX = 200;
+function errText(e) {
+  const raw = e instanceof Error ? e.message || e.name : String(e);
+  const line = raw.replace(/\s+/g, " ").trim();
+  return line.length > DETAIL_MAX ? `${line.slice(0, DETAIL_MAX)}\u2026` : line;
+}
+var traceStart = /* @__PURE__ */ new WeakMap();
+function traceAdd(diag, line) {
+  if (diag.trace.length >= TRACE_MAX) return;
+  if (diag.trace.length === TRACE_MAX - 1) {
+    diag.trace.push("trace full");
+    return;
+  }
+  const t0 = traceStart.get(diag);
+  const at = t0 === void 0 ? 0 : (Date.now() - t0) / 1e3;
+  diag.trace.push(`${at.toFixed(2)} ${line}`);
+}
+function iceShapes(servers) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const server of servers ?? []) {
+    const urls = typeof server.urls === "string" ? [server.urls] : server.urls;
+    for (const url of urls ?? []) {
+      const scheme = /^(stuns?|turns?):/i.exec(url)?.[1]?.toLowerCase() ?? "other";
+      const transport = /[?&]transport=(\w+)/i.exec(url)?.[1]?.toLowerCase();
+      const shape = transport ? `${scheme}/${transport}` : scheme;
+      seen.set(shape, (seen.get(shape) ?? 0) + 1);
+    }
+  }
+  const parts = [...seen].map(([shape, n]) => `${shape}x${n}`);
+  return parts.length > 0 ? parts.join(" ") : "none";
+}
+function formatDirectDiagLines(d) {
+  const connect = d.msConnect === void 0 ? "-" : `${d.msConnect}ms`;
+  const pair = d.pairLocal || d.pairRemote ? `${d.pairLocal || "?"}/${d.pairRemote || "?"}` : "none";
+  return [
+    `ms=${d.ms} connect=${connect} bytes=${d.bytes} restarts=${d.restarts} pair=${pair}`,
+    ...d.detail === void 0 ? [] : [`detail ${d.detail}`],
+    `local host=${d.localHost} srflx=${d.localSrflx} relay=${d.localRelay}   remote host=${d.remoteHost} srflx=${d.remoteSrflx} relay=${d.remoteRelay}`,
+    `turn supplied=${d.turnUrlsSupplied} configured=${d.turnUrlsConfigured}   ice=${d.iceState} gather=${d.gatherState} remote_desc=${d.hadRemoteDesc}`,
+    ...d.trace ?? []
+  ];
+}
 function countCand(diag, side, c) {
-  if (!c) return;
+  if (!c) {
+    traceAdd(diag, `${side} end-of-candidates`);
+    return;
+  }
   const t = candType(c);
+  traceAdd(diag, `${side} ${t} ${candProto(c)}`);
   if (t === "host") diag[side === "local" ? "localHost" : "remoteHost"]++;
   else if (t === "srflx" || t === "prflx") diag[side === "local" ? "localSrflx" : "remoteSrflx"]++;
   else if (t === "relay") diag[side === "local" ? "localRelay" : "remoteRelay"]++;
@@ -1055,7 +1041,17 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
   const initialIce = ice ?? DIRECT_ICE;
   const pc = new RTCPeerConnection({
     iceServers: initialIce,
-    iceTransportPolicy
+    iceTransportPolicy,
+    // Gather before there is anything to gather for. A receiver whose peer
+    // is an agent gets the whole remote candidate set at once — the agent
+    // writes it and leaves — so checking starts in the same tick as the local
+    // description, a pair comes up on the first candidate found, and
+    // gathering is reported complete before any relay allocation returns.
+    // Measured 2026-09-04: one host candidate, no relay, gathering done at
+    // 240 ms, and when that pair died five seconds later there was nothing
+    // to fall back to. The pool does the allocations up front, at construction,
+    // so the relay candidates exist before the first check is ever sent.
+    iceCandidatePoolSize: 1
   });
   let phase = "connecting";
   let disconnectTimer;
@@ -1077,7 +1073,13 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     turnUrlsSupplied: countTurnUrls(initialIce),
     turnUrlsConfigured: 0,
     bytes: 0,
-    restarts: 0
+    restarts: 0,
+    trace: []
+  };
+  traceStart.set(diag, startedAt);
+  traceAdd(diag, `ice servers ${iceShapes(initialIce)} policy=${iceTransportPolicy}`);
+  pc.onicegatheringstatechange = () => {
+    traceAdd(diag, `gather ${String(pc.iceGatheringState ?? "")}`);
   };
   const cleanup = () => {
     clearTimeout(waitTimer);
@@ -1086,6 +1088,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     clearTimeout(restartTimer);
     pc.onicecandidate = null;
     pc.oniceconnectionstatechange = null;
+    pc.onicegatheringstatechange = null;
     pc.close();
   };
   const setPhase = (p) => {
@@ -1097,6 +1100,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
       diag.gatherState = String(pc.iceGatheringState ?? "");
       diag.hadRemoteDesc = hasRemoteDescription(pc);
       diag.turnUrlsConfigured = countTurnUrls(pc.getConfiguration().iceServers);
+      traceAdd(diag, `${p}${diag.reason ? ` ${diag.reason}` : ""} ice=${diag.iceState} gather=${diag.gatherState}`);
       onDiag?.(diag);
       onPhase(p);
       cleanup();
@@ -1104,9 +1108,13 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     }
     onPhase(p);
   };
-  const fail = (reason) => {
+  const fail = (reason, cause) => {
     if (phase === "done" || phase === "failed") return;
     if (!diag.reason) diag.reason = reason;
+    if (cause !== void 0 && diag.detail === void 0) {
+      diag.detail = errText(cause);
+      traceAdd(diag, `detail ${diag.detail}`);
+    }
     setPhase("failed");
   };
   const waitTimer = setTimeout(() => fail("peer_silent"), DIRECT_SIGNAL_WAIT_MS);
@@ -1130,12 +1138,14 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     }
     stallState = "restarting";
     diag.restarts++;
+    traceAdd(diag, "ice restart");
     clearTimeout(restartTimer);
     restartTimer = setTimeout(() => fail("disconnected"), stallWindowMs);
     onStall();
   };
   pc.oniceconnectionstatechange = () => {
     const s = pc.iceConnectionState;
+    traceAdd(diag, `ice ${String(s ?? "")}`);
     if (s === "failed") {
       if (diag.msConnect !== void 0 && onStall) stalled();
       else fail("ice_failed");
@@ -1160,7 +1170,10 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     connected: () => {
       clearTimeout(waitTimer);
       clearTimeout(connectTimer);
-      if (diag.msConnect === void 0) diag.msConnect = Date.now() - startedAt;
+      if (diag.msConnect === void 0) {
+        diag.msConnect = Date.now() - startedAt;
+        traceAdd(diag, "channel open");
+      }
     },
     isTerminal: () => phase === "done" || phase === "failed",
     setStall: (fn, windowMs) => {
@@ -1169,6 +1182,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     },
     setIceServers: (iceServers) => {
       diag.turnUrlsSupplied = countTurnUrls(iceServers);
+      traceAdd(diag, `ice servers replaced ${iceShapes(iceServers)}`);
       pc.setConfiguration({ iceServers });
     }
   };
@@ -1250,7 +1264,7 @@ function startSender(opts) {
       const offer = await pc.createOffer({ iceRestart: true });
       await pc.setLocalDescription(offer);
       await opts.send({ kind: "offer", sdp: offer.sdp, protocol: 2, generation });
-    })().catch(() => s.fail("signaling"));
+    })().catch((e) => s.fail("signaling", e));
   }, DIRECT_CONNECT_TIMEOUT_MS);
   const dc = pc.createDataChannel("zas-direct", { ordered: true });
   dc.binaryType = "arraybuffer";
@@ -1277,9 +1291,7 @@ function startSender(opts) {
   };
   const pump = async () => {
     const meta = {
-      name: opts.file.name ?? opts.name ?? "zas",
-      size: opts.file.size,
-      mime: opts.file.type || "application/octet-stream",
+      ...directMetaOf(opts.file, opts.name),
       ...opts.label !== void 0 ? { label: opts.label } : {}
     };
     dc.send(encodeMeta(meta));
@@ -1318,7 +1330,7 @@ function startSender(opts) {
       s.diag.pairRemote = pair.remote;
       opts.onPath?.(pathOf(pair));
     }).catch(() => void 0);
-    void pump().catch(() => s.fail("transfer"));
+    void pump().catch((e) => s.fail("transfer", e));
   };
   dc.onmessage = (e) => {
     try {
@@ -1344,7 +1356,7 @@ function startSender(opts) {
     plumbing.setLocalGeneration(generation);
     plumbing.expectRemoteGeneration(generation);
     await opts.send({ kind: "offer", sdp: offer.sdp, protocol: 2, generation });
-  })().catch(() => s.fail("signaling"));
+  })().catch((e) => s.fail("signaling", e));
   return {
     accept: (msg) => {
       if (s.isTerminal()) return;
@@ -1354,7 +1366,7 @@ function startSender(opts) {
         if (msg.generation !== void 0 && answerGeneration !== generation) return;
         peerProtocol = msg.protocol === 2 ? 2 : 1;
         plumbing.expectRemoteGeneration(answerGeneration);
-        void pc.setRemoteDescription({ type: "answer", sdp: msg.sdp }).then(() => plumbing.remoteDescriptionSet(answerGeneration)).catch(() => s.fail("signaling"));
+        void pc.setRemoteDescription({ type: "answer", sdp: msg.sdp }).then(() => plumbing.remoteDescriptionSet(answerGeneration)).catch((e) => s.fail("signaling", e));
       }
       if (msg.kind === "ice") plumbing.applyIce(msg.candidate, msg.generation);
     },
@@ -1427,7 +1439,7 @@ function startReceiver(opts) {
             s.fail(frame.meta.size > DIRECT_FILE_MAX_BYTES ? "too_big" : "protocol");
             return;
           }
-          if (opts.expectedMeta && (frame.meta.name !== opts.expectedMeta.name || frame.meta.size !== opts.expectedMeta.size || frame.meta.mime !== opts.expectedMeta.mime)) {
+          if (opts.expectedMeta && (frame.meta.name !== opts.expectedMeta.name || frame.meta.size !== opts.expectedMeta.size)) {
             dc?.send(ABORT_FRAME);
             s.fail("protocol");
             return;
@@ -1439,7 +1451,7 @@ function startReceiver(opts) {
             sinkRef = sink;
             return sink;
           });
-          pipeline.catch(() => s.fail("sink"));
+          pipeline.catch((e3) => s.fail("sink", e3));
         } else if (frame.type === "chunk") {
           if (!pipeline || finished) throw new Error("chunk_before_meta");
           queued += frame.payload.length;
@@ -1457,7 +1469,7 @@ function startReceiver(opts) {
             }
             return sink;
           });
-          pipeline.catch(() => s.fail("sink"));
+          pipeline.catch((e3) => s.fail("sink", e3));
         } else if (frame.type === "done") {
           if (!pipeline || finished) throw new Error("done_before_meta");
           finished = true;
@@ -1468,7 +1480,7 @@ function startReceiver(opts) {
             await sink.close();
             dc?.send(DONE_FRAME);
             s.setPhase("done");
-          }).catch(() => s.fail("integrity"));
+          }).catch((e3) => s.fail("integrity", e3));
         } else if (frame.type === "abort") {
           s.fail("peer_abort");
         }
@@ -1502,7 +1514,7 @@ function startReceiver(opts) {
           const answer = await pc.createAnswer();
           await pc.setLocalDescription(answer);
           await opts.send({ kind: "answer", sdp: answer.sdp, protocol: 2, generation });
-        })().catch(() => s.fail("signaling"));
+        })().catch((e) => s.fail("signaling", e));
       }
       if (msg.kind === "ice") plumbing.applyIce(msg.candidate, msg.generation);
     },
@@ -1519,6 +1531,89 @@ function startReceiver(opts) {
   };
 }
 
+// src/direct.ts
+import { randomBytes } from "node:crypto";
+import { openAsBlob } from "node:fs";
+import { basename as basename2 } from "node:path";
+
+// src/shared/manifest.ts
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
+
+// src/shared/constants.ts
+var CHUNKER_VERSION = "chunker_v1";
+var CHUNK_MIN = 1 * 1024 * 1024;
+var CHUNK_AVG_BITS = 22;
+var CHUNK_MAX = 8 * 1024 * 1024;
+var STORAGE_V2_PART_BYTES = 16 * 1024 * 1024;
+var GEAR_SEED = "zas-gear-v1:";
+var HKDF_INFO_CHUNK_KEY = "zas-chunk-key-v1";
+var HKDF_INFO_CHUNK_NONCE = "zas-chunk-nonce-v1";
+var OPRF_CONTEXT = "OPRFV1-\0-ristretto255-SHA512";
+var MANIFEST_VERSION = 1;
+var ANON_EMPTY_TTL_MS = 30 * 60 * 1e3;
+var FREE_RELAY_MAX_BYTES = 50 * 1024 * 1024;
+var SAFE_STORED_FILE_LIMITS = {
+  anon: 30 * 1024 * 1024,
+  free: FREE_RELAY_MAX_BYTES,
+  pro: 200 * 1024 * 1024,
+  max: 200 * 1024 * 1024
+};
+var STORED_FILE_LIMITS_V2 = {
+  anon: 30 * 1024 * 1024,
+  free: FREE_RELAY_MAX_BYTES,
+  pro: 5 * 1024 * 1024 * 1024,
+  max: 20 * 1024 * 1024 * 1024
+};
+var STORAGE_LIMITS = {
+  anon: 30 * 1024 * 1024,
+  free: 100 * 1024 * 1024,
+  pro: null,
+  max: null
+};
+var THUMBNAIL_MAX_EDGE = 640;
+var THUMBNAIL_MAX_BYTES = 14e4;
+
+// src/shared/manifest.ts
+function newManifest(partial) {
+  return { v: MANIFEST_VERSION, chunker: CHUNKER_VERSION, ...partial };
+}
+var ENVELOPE_MAGIC = 90;
+var KEY_VERSION_LEGACY = 1;
+function envelopeVersion(sealed) {
+  if (sealed.length > 26 && sealed[0] === ENVELOPE_MAGIC && sealed[1] >= 1) return sealed[1];
+  return KEY_VERSION_LEGACY;
+}
+function sealBytes(key, version, plain) {
+  if (version < 1 || version > 255) throw new Error("key version out of range");
+  const nonce = new Uint8Array(24);
+  crypto.getRandomValues(nonce);
+  const ct = xchacha20poly1305(key, nonce).encrypt(plain);
+  return concatBytes(new Uint8Array([ENVELOPE_MAGIC, version]), nonce, ct);
+}
+function openSealed(key, sealed) {
+  const versioned = envelopeVersion(sealed) !== KEY_VERSION_LEGACY || sealed[0] === ENVELOPE_MAGIC;
+  if (versioned && sealed.length > 26) {
+    try {
+      return xchacha20poly1305(key, sealed.slice(2, 26)).decrypt(sealed.slice(26));
+    } catch {
+    }
+  }
+  return xchacha20poly1305(key, sealed.slice(0, 24)).decrypt(sealed.slice(24));
+}
+var sealRaw = sealBytes;
+var openRaw = openSealed;
+function sealManifest(channelKey, manifest, version = KEY_VERSION_LEGACY) {
+  return sealBytes(channelKey, version, new TextEncoder().encode(JSON.stringify(manifest)));
+}
+function openManifest(channelKey, sealed) {
+  const m = JSON.parse(new TextDecoder().decode(openSealed(channelKey, sealed)));
+  if (!Array.isArray(m.chunks)) m.chunks = [];
+  return m;
+}
+function decryptChannelName(channelKey, sealed) {
+  return new TextDecoder().decode(openSealed(channelKey, sealed));
+}
+
 // src/shared/direct-fallback.ts
 function createFallbackMeta(file) {
   const key = crypto.getRandomValues(new Uint8Array(32));
@@ -1636,15 +1731,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 +1756,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,13 +2567,13 @@ 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);
   const key = channelKeyOf(ctx.identity, grant);
   const channelName = channelLabel(ctx, grant);
-  const file = await (deps.openFile ?? openAsBlob)(input.path).catch(() => {
+  const file = await (deps.openFile ?? openAsBlob)(input.path, { type: mimeFor(input.path) }).catch(() => {
     throw new ZasError("upload_failed", 400);
   });
   if (file.size > DIRECT_FILE_MAX_BYTES) throw new ZasError("file_too_big", 413);
@@ -2489,8 +2584,8 @@ 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");
-  const meta = { name, size: file.size, mime: mimeFor(input.path) };
+  report2("offer");
+  const meta = directMetaOf(file, name);
   const { id } = await ctx.client.api("POST", `/direct/${cid}`, {
     meta_enc: seal(meta),
     key_version: grant.key_version,
@@ -2523,7 +2618,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 +2635,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);
@@ -2552,6 +2647,7 @@ async function sendDirect(ctx, input, report, deps = {}) {
     },
     onDiag: (d) => {
       diag = d;
+      deps.onDiag?.(d);
     }
   });
   let over = false;
@@ -2580,7 +2676,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 +2715,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 +2726,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 +2735,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 +2743,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 +2757,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 +3143,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 +3156,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 +3208,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 +3224,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) => {
@@ -3136,6 +3232,7 @@ async function receiveDirect(ctx, input, report, deps = {}) {
     },
     onDiag: (d) => {
       diag = d;
+      deps.onDiag?.(d);
     },
     sink: async (m) => {
       sink.open(m);
@@ -3167,7 +3264,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 +3299,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 +3321,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 +3337,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 +3378,13 @@ 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(
+    const note = (diag) => {
+      job.diag = diag;
+    };
+    this.settled.set(job, work(report2, note).then(
       (result) => {
         job.status = "done";
         job.result = result;
@@ -3328,9 +3428,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.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;
@@ -3344,9 +3912,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);
@@ -3366,10 +3958,17 @@ function buildServer(profile, deps = {}) {
     return { isError: true, ...text2(`${err.code}: ${humanSentence(err)}`) };
   };
   const settled = (job) => {
-    if (job.status === "done") return text2(job.result);
+    if (job.status === "done") {
+      return job.diag ? text2({ ...job.result, diag: formatDirectDiagLines(job.diag) }) : text2(job.result);
+    }
     if (job.status === "failed") {
       const e = job.error;
-      return failed(e ? new ZasError(e.code, e.status, e.message, e.retryAfterMs, e.serverCode) : new ZasError("internal", 0));
+      const answer = failed(e ? new ZasError(e.code, e.status, e.message, e.retryAfterMs, e.serverCode) : new ZasError("internal", 0));
+      if (!job.diag) return answer;
+      const said = answer.content[0].text;
+      return { isError: true, ...text2(`${said}
+
+${formatDirectDiagLines(job.diag).join("\n")}`) };
     }
     return text2({ job_id: job.id, status: "running", phase: job.phase });
   };
@@ -3394,7 +3993,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 +4088,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,9 +4114,10 @@ function buildServer(profile, deps = {}) {
         "direct",
         input.path,
         input.channel ?? "",
-        (report) => sendDirect(c, input, report, {
+        (report2, note) => sendDirect(c, input, report2, {
           ...deps.direct ?? {},
-          onFailed: (record) => rememberFailed(job.id, record)
+          onFailed: (record) => rememberFailed(job.id, record),
+          onDiag: note
         })
       );
       return settled(await runner.wait(job));
@@ -3538,7 +4139,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,9 +4167,10 @@ function buildServer(profile, deps = {}) {
         "receive",
         input.dest ?? "Directo",
         input.channel ?? "",
-        (report) => receiveDirect(c, input, report, {
+        (report2, note) => receiveDirect(c, input, report2, {
           ...deps.receive ?? {},
-          onFailed: (record) => rememberFailedReceive(job.id, record)
+          onFailed: (record) => rememberFailedReceive(job.id, record),
+          onDiag: note
         })
       );
       return settled(await runner.wait(job));
@@ -3590,7 +4192,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 +4269,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 +4301,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 +4319,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 +4358,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;
 }