zas-agent 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-09-04
+
+### Added
+
+- A Directo run now answers with the engine's own account of itself, not
+  only with one word. `zas_send_direct`, `zas_receive_direct` and `zas_jobs`
+  carry the candidate counts by type for both ends, the ICE and gathering
+  states, how many TURN URLs were supplied against how many the connection
+  kept, the selected pair, the restarts, and a timestamped trace of the
+  session: every candidate as it arrived, the state changes, and the verdict.
+  Types, transports and timings only — never an address, a port, a host name
+  or a credential. A run that fails on a machine you are not sitting at can
+  now be diagnosed from the tool result.
+- The thrown error behind a failure is kept as `detail`. The reason stays a
+  closed word for grouping; `detail` is the sentence the exception carried,
+  which every failure used to discard at the catch.
+
+### Fixed
+
+- The receiver pre-gathers a candidate pool. An agent hands its whole
+  candidate set over at once, so the far end could start checking before its
+  own relay candidates existed, connect on the first pair it found, and be
+  left with nothing when that pair died seconds later.
+- The transport of a candidate is read whichever way the peer wrote the line.
+  This package prefixes the SDP attribute, so its candidates used to be
+  reported with an unknown transport.
+
+## [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
@@ -139,7 +183,12 @@ 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.3.0...HEAD
+[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/soke1556/zas-agent/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/soke1556/zas-agent/compare/v0.5.1...v0.6.0
+[0.5.1]: https://github.com/soke1556/zas-agent/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/soke1556/zas-agent/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/soke1556/zas-agent/compare/v0.3.0...v0.4.0
 [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

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