zas-agent 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-03
+
+### Added
+
+- `zas_send_direct` sends a file through Directo: a live, device-to-device
+  transfer into a channel in Directo mode. Nothing is stored. The agent
+  offers, the owner presses Receive on another device within ten minutes,
+  and the bytes travel encrypted over WebRTC. The call returns the result,
+  or a job id after a minute; `zas_jobs` follows the phases `offer`,
+  `connecting`, `flight`, `finishing`.
+- `zas_send_direct_fallback` delivers the file of a Directo send that
+  failed in flight through reliable delivery: encrypted on this machine,
+  stored in Cloudflare R2 for up to 24 hours, off the owner's quota. It is
+  the owner's choice; the tool description tells the model to ask.
+- A native dependency: `node-datachannel`, WebRTC for Node. npm installs a
+  prebuilt binary; the module loads the first time `zas_send_direct` runs,
+  and a machine where it cannot load answers `webrtc_unavailable`.
+- New error codes: `not_claimed`, `direct_cancelled`, `direct_failed`,
+  `direct_not_failed`, `file_changed`, `webrtc_unavailable`,
+  `fallback_unavailable`.
+
+### Changed
+
+- `zas_status` says `send (Directo)` for a channel in Directo mode, where it
+  said nothing. `zas_send_file` still refuses such a channel.
+
+## [0.3.0] - 2026-09-03
+
+### Added
+
+- Pairing again in a profile that is already paired replaces the agent
+  instead of adding a second one. The terminal opens the pairing as the old
+  agent, the approval page says which agent it replaces and fills in its
+  name and channels, and the old agent is revoked in the same step that
+  creates the new one. If the server no longer accepts the old agent, `pair`
+  says so and creates a new agent.
+
+### Changed
+
+- The help text, the tool descriptions and the README say "this agent" where
+  they said "this machine": a pairing is one profile's key pair, and one
+  machine can hold several.
+
 ## [0.2.1] - 2026-09-03
 
 ### Fixed
@@ -58,7 +101,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   two separate identities that cannot read each other's keys.
 - Install snippets for Claude Code and Codex, printed by `zas-agent pair`.
 
-[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/soke1556/zas-agent/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/soke1556/zas-agent/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/soke1556/zas-agent/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/soke1556/zas-agent/compare/v0.1.0...v0.1.1

package/README.md

@@ -25,8 +25,9 @@ scope to the channels you choose, and that you can revoke.
 
 ## What it does
 
-Your coding agent gets seven tools. It can send a file or a note into a channel
-you picked, list what is in that channel, and pull one item back onto disk.
+Your coding agent gets nine tools. It can send a file or a note into a channel
+you picked, send a file live through Directo, list what is in that channel,
+and pull one item back onto disk.
 Everything it sends is encrypted on your machine before it leaves, lands in your
 account, and is marked in the channel as sent by that agent. The agent has an
 identity of its own and never holds your account key: pairing mints a key pair
@@ -35,7 +36,7 @@ get a short-lived session.
 
 ## Install
 
-Pair the machine first, then hand the command to your harness.
+Pair the agent first, then hand the command to your harness.
 
 **Pair**
 
@@ -147,8 +148,11 @@ ones marked *(server-side)* are enforced by the Zas server.
   *(server-side)*.
 - **No reading unless the grant says so.** `read` is a separate switch from
   `send`; without it, `zas_list_items` and `zas_get_item` are refused.
-- **No sending into a view-only channel, and none into a channel in Directo
-  mode.** Both are refused before a byte is uploaded.
+- **No stored sending into a view-only channel, and none into a channel in
+  Directo mode.** Both are refused before a byte is uploaded. A channel in
+  Directo mode takes `zas_send_direct`, a live transfer that stores nothing.
+- **No receiving.** The agent sends through Directo; it never claims an
+  offer, so nothing can be pushed onto this machine through it.
 - **Nothing outside its allowlist.** The API refuses an agent on every route
   that is not on a short, explicit list, and Firestore rules refuse it your
   account document, your devices, and any channel without an active read grant
@@ -168,7 +172,7 @@ string ever reaches a terminal.
 
 | Code | What it means |
 | --- | --- |
-| `not_paired` | This machine is not paired yet. |
+| `not_paired` | This agent is not paired yet. |
 | `identity_corrupt` | The identity file on disk is damaged. |
 | `agent_revoked` | The owner revoked this agent. |
 | `agent_forbidden` | Only the account owner can do that. |
@@ -177,6 +181,13 @@ string ever reaches a terminal.
 | `read_forbidden` | This agent cannot read that channel. |
 | `direct_mode` | That channel is in Directo mode. |
 | `not_direct_mode` | That channel is not in Directo mode. |
+| `not_claimed` | Nobody received the file within ten minutes; the offer was withdrawn. |
+| `direct_cancelled` | The offer was cancelled from the receiving side. |
+| `direct_failed` | The Directo transfer failed in flight. |
+| `direct_not_failed` | That job is not a Directo send that failed in flight. |
+| `file_changed` | The file changed since the Directo offer. |
+| `webrtc_unavailable` | The WebRTC engine could not be loaded on this machine. |
+| `fallback_unavailable` | Reliable delivery is not available right now. |
 | `key_stale` | The channel key changed; the owner refreshes it by opening Zas. |
 | `quota_exceeded` | The account reached its storage limit. |
 | `rate_limited` | Too many sends in a row. |
@@ -203,22 +214,29 @@ stack trace.
 
 | Tool | What it does |
 | --- | --- |
-| `zas_status` | Says whether this machine is paired with a Zas account, and lists the owner's channels this agent may send to or read from. |
-| `zas_pair` | Pairs this machine with a Zas account. The first call returns a URL for the owner to open; a later call says whether they approved. If the page shows a code, a call with `code` claims with it. |
+| `zas_status` | Says whether this agent is paired with a Zas account, and lists the owner's channels it may send to or read from. |
+| `zas_pair` | Pairs this agent with a Zas account. The first call returns a URL for the owner to open; a later call says whether they approved. If the page shows a code, a call with `code` claims with it. In a profile that is already paired, approval replaces the old agent. |
 | `zas_send_file` | Sends a file from this machine into one of the owner's channels. Returns the item id, or a job id when the upload takes longer than a minute. |
 | `zas_send_note` | Sends a note — plain text, or a code snippet with its language — into one of the owner's channels. |
+| `zas_send_direct` | Sends a file through Directo: a live, device-to-device transfer into a channel in Directo mode. Nothing is stored. The owner presses Receive on another device within ten minutes; the call returns the result, or a job id after a minute. |
+| `zas_send_direct_fallback` | After a Directo send failed in flight, delivers the same file through reliable delivery: encrypted on this machine, stored in Cloudflare R2 for up to 24 hours, off the owner's quota. The owner's choice; the model is told to ask. |
 | `zas_list_items` | Lists the most recent items in one of the owner's channels. Needs a grant that includes reading. |
 | `zas_get_item` | Fetches one item. A note comes back as text; a file is written to disk. It never overwrites, so the path it answers with can differ from the one you asked for. |
-| `zas_jobs` | Lists the sends this server started, newest first, with the phase each one reached — and where a `job_id` from a long send is redeemed. |
+| `zas_jobs` | Lists the sends and Directo transfers this server started, newest first, with the phase each one reached — and where a `job_id` from a long send is redeemed. |
 
 `channel` takes a channel name or a channel id. A name has to match exactly one
-of the channels you granted; with exactly one grant, `zas_send_file` and
-`zas_send_note` can leave it out.
+of the channels you granted; with exactly one grant, `zas_send_file`,
+`zas_send_note` and `zas_send_direct` can leave it out.
+
+Directo needs a native module, [node-datachannel](https://github.com/murat-dogan/node-datachannel),
+WebRTC for Node. npm installs a prebuilt binary for Windows, macOS and Linux;
+the module loads the first time `zas_send_direct` runs, and a machine where it
+cannot load answers `webrtc_unavailable`. Every other tool works without it.
 
 Two things worth knowing before you point a model at your account:
 
-- `zas_send_file` sends any file this process can read — `~/.ssh/id_rsa` and a
-  `.env` included. Confirm with the owner before sending secrets, keys or
+- `zas_send_file` and `zas_send_direct` send any file this process can read —
+  `~/.ssh/id_rsa` and a `.env` included. Confirm with the owner before sending secrets, keys or
   credentials. Its tool description says so, so the model reads it too.
 - `zas_get_item` writes a new file under `dest`, or under the system temp
   directory when you leave `dest` out. It never overwrites an existing file: a
@@ -260,6 +278,22 @@ Deleting the directory makes this machine forget the agent. It does not revoke
 anything: the account side is closed from the web app, under
 Settings → Agents → Revoke.
 
+## Pairing again
+
+A pairing is one profile's key pair, not the machine and not the program. A
+profile holds one agent. Running `zas-agent pair` in a profile that is already
+paired opens a replacement: the terminal signs the request with the old
+identity, the approval page says which agent it replaces and fills in its name
+and channels, and the old agent is revoked in the same step that creates the
+new one. Its row stays under Settings → Agents as revoked until you remove it,
+and it keeps costing a slot until then. If the old agent was already revoked
+or removed, `pair` says so and creates a new agent.
+
+One machine that runs Claude Code and Codex has two profiles (`claude-code`
+and `codex`), two agents, two approvals and two rows. Revoking one does not
+touch the other. Two programs pointed at the same `--profile` act as one
+agent: same keys, same channels, one row.
+
 ## Configuration
 
 | Setting | Default | What it changes |