zas-agent 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-03
+
+### Added
+
+- `zas_receive_direct` receives a file the owner sends through Directo,
+  straight onto this machine. It waits for the offer, takes it, and writes
+  the file to disk; nothing is stored anywhere. Receiving is reading, so it
+  needs a grant with `read`, and the channel has to be in Directo mode. The
+  call returns the result, or a job id after a minute; `zas_jobs` follows the
+  phases `waiting`, `connecting`, `flight`, `finishing`.
+- `zas_receive_direct_fallback` finishes a receive that failed in flight,
+  when the sender chose reliable delivery for it: the encrypted copy is
+  downloaded and decrypted onto the same destination.
+- New error codes: `no_offer` and `offer_taken`.
+
+### Changed
+
+- The agent claims an offer only inside a tool call. It never watches a
+  channel: an exchange takes two devices and the first claim wins, so a
+  watcher would take files meant for the owner's own phone.
+- A received file never overwrites an existing one. It is written 0600
+  through a temporary name and renamed only once the transfer is verified,
+  so a run that breaks leaves nothing that reads as complete. The answered
+  `path` is where the bytes actually went.
+- `zas_status` says `receive (Directo)` where it said `read` for a channel
+  in Directo mode: such a channel stores nothing, so there is no list of
+  items behind the grant, only live offers to take.
+
+## [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

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 eleven tools. It can send a file or a note into a channel
+you picked, send or receive 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
@@ -147,8 +148,13 @@ 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 unless the grant says read.** Receiving through Directo
+  writes a file onto this machine, so `zas_receive_direct` takes the same
+  `read` switch as listing. And it only ever runs inside a tool call: the
+  agent never watches your channels, so nothing arrives unasked.
 - **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
@@ -177,6 +183,15 @@ 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. |
+| `no_offer` | Nobody offered a file through Directo while the call waited. |
+| `offer_taken` | Another device received that file first. |
+| `direct_cancelled` | The offer was cancelled from the other side. |
+| `direct_failed` | The Directo transfer failed in flight. |
+| `direct_not_failed` | That job is not a Directo transfer 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. |
@@ -207,26 +222,35 @@ stack trace.
 | `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_receive_direct` | Receives a file the owner sends through Directo, onto this machine. Waits for the offer, takes it, and writes the file to disk. Needs a grant that includes reading, and a channel in Directo mode. Returns the path written, or a job id after a minute. |
+| `zas_receive_direct_fallback` | After a Directo receive failed in flight, downloads the encrypted copy the sender chose to store, and decrypts it to the same destination. |
 | `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`, `zas_send_direct` and `zas_receive_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 a Directo tool 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
-  name that is taken gets a suffix, and the path it answers with is the one it
-  actually wrote.
+- `zas_get_item` and `zas_receive_direct` write a new file under `dest`, or
+  under the system temp directory when you leave `dest` out. Neither ever
+  overwrites an existing file: a name that is taken gets a suffix, and the path
+  they answer with is the one they actually wrote.
 
-Everything either tool touches lands inside your own account and your own
-machine. Revoking the agent stops both.
+Everything those tools touch lands inside your own account and your own
+machine. Revoking the agent stops all of them.
 
 ## Data on disk