zas-agent 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ 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

package/README.md

@@ -25,9 +25,9 @@ scope to the channels you choose, and that you can revoke.
 
 ## What it does
 
-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.
+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
@@ -151,8 +151,10 @@ ones marked *(server-side)* are enforced by the Zas server.
 - **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.
+- **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
@@ -182,9 +184,11 @@ string ever reaches a terminal.
 | `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. |
+| `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 send that 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. |
@@ -220,17 +224,19 @@ stack trace.
 | `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 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`,
-`zas_send_note` and `zas_send_direct` can leave it out.
+`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 `zas_send_direct` runs, and a machine where it
+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:
@@ -238,13 +244,13 @@ Two things worth knowing before you point a model at your account:
 - `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
 

package/dist/cli.js

@@ -167,9 +167,11 @@ var SENTENCES = {
   direct_mode: "That channel is in Directo mode. Use zas_send_direct.",
   not_direct_mode: "That channel is not in Directo mode. Use zas_send_file.",
   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 ({path}). Ask the owner before you use zas_send_direct_fallback.",
-  direct_not_failed: "That job is not a Directo send that failed in flight.",
+  no_offer: "Nobody offered a file through Directo while this call waited. Ask the owner to press Send Direct, then call again.",
+  offer_taken: "Another device received that file first.",
+  direct_cancelled: "The offer was cancelled from the other side.",
+  direct_failed: "The Directo transfer failed ({path}). Ask the owner before you use zas_send_direct_fallback or zas_receive_direct_fallback.",
+  direct_not_failed: "That job is not a Directo transfer that failed in flight.",
   file_changed: "The file changed since the Directo offer. Send it again.",
   webrtc_unavailable: "The WebRTC engine (node-datachannel) could not be loaded on this machine.",
   fallback_unavailable: "Reliable delivery is not available right now. Try again later.",
@@ -960,6 +962,14 @@ function encodeDone(digest) {
   frame.set(body, 1);
   return frame;
 }
+function encodeCredit(received) {
+  if (!Number.isSafeInteger(received) || received < 0) throw new Error("bad_credit");
+  const body = new TextEncoder().encode(String(received));
+  const frame = new Uint8Array(1 + body.length);
+  frame[0] = FRAME_CREDIT;
+  frame.set(body, 1);
+  return frame;
+}
 var DONE_FRAME = encodeDone();
 var ABORT_FRAME = new Uint8Array([FRAME_ABORT]);
 function parseFrame(data) {
@@ -1357,6 +1367,154 @@ function startSender(opts) {
     }
   };
 }
+function startReceiver(opts) {
+  let sinkRef = null;
+  const s = session(
+    opts.ice,
+    (p) => {
+      if (p === "failed") {
+        try {
+          sinkRef?.abort?.();
+        } catch {
+        }
+        sinkRef = null;
+      }
+      opts.onPhase(p);
+    },
+    opts.onDiag,
+    opts.iceTransportPolicy
+  );
+  s.setStall(() => void 0, DIRECT_CONNECT_TIMEOUT_MS * 2);
+  opts.onPhase("connecting");
+  const { pc } = s;
+  const plumbing = signalPlumbing(pc, opts.send, () => s.fail("signal_send"), s.diag);
+  let protocol = 1;
+  let generation = 1;
+  let dc;
+  let pipeline = null;
+  let total = 0;
+  let got = 0;
+  let queued = 0;
+  let nextCredit = DIRECT_RECEIVE_WINDOW_BYTES;
+  let hasherPromise = null;
+  let finished = false;
+  pc.ondatachannel = (e) => {
+    dc = e.channel;
+    dc.binaryType = "arraybuffer";
+    dc.onopen = () => {
+      s.connected();
+      s.setPhase("flight");
+      void pc.getStats().then((stats) => {
+        const pair = pairFromStats(stats);
+        if (!pair) return;
+        s.diag.pairLocal = pair.local;
+        s.diag.pairRemote = pair.remote;
+        opts.onPath?.(pathOf(pair));
+      }).catch(() => void 0);
+    };
+    dc.onmessage = (e2) => {
+      try {
+        const frame = parseFrame(e2.data);
+        if (frame.type === "meta") {
+          if (pipeline || !Number.isSafeInteger(frame.meta.size) || frame.meta.size < 0 || frame.meta.size > DIRECT_FILE_MAX_BYTES || typeof frame.meta.name !== "string" || frame.meta.name.length === 0 || typeof frame.meta.mime !== "string") {
+            try {
+              dc?.send(ABORT_FRAME);
+            } catch {
+            }
+            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)) {
+            dc?.send(ABORT_FRAME);
+            s.fail("protocol");
+            return;
+          }
+          total = frame.meta.size;
+          hasherPromise = createSHA256();
+          opts.onMeta?.(frame.meta);
+          pipeline = opts.sink(frame.meta).then((sink) => {
+            sinkRef = sink;
+            return sink;
+          });
+          pipeline.catch(() => s.fail("sink"));
+        } else if (frame.type === "chunk") {
+          if (!pipeline || finished) throw new Error("chunk_before_meta");
+          queued += frame.payload.length;
+          if (queued > total) throw new Error("too_many_bytes");
+          pipeline = pipeline.then(async (sink) => {
+            await sink.write(frame.payload);
+            const hasher = await hasherPromise;
+            hasher.update(frame.payload);
+            got += frame.payload.length;
+            s.diag.bytes = got;
+            opts.onProgress?.(got, total);
+            if (protocol >= 2 && (got >= nextCredit || got === total)) {
+              dc?.send(encodeCredit(got));
+              while (nextCredit <= got) nextCredit += DIRECT_RECEIVE_WINDOW_BYTES;
+            }
+            return sink;
+          });
+          pipeline.catch(() => s.fail("sink"));
+        } else if (frame.type === "done") {
+          if (!pipeline || finished) throw new Error("done_before_meta");
+          finished = true;
+          void pipeline.then(async (sink) => {
+            if (got !== total || queued !== total) throw new Error("size_mismatch");
+            const sha2563 = (await hasherPromise).digest();
+            if (protocol >= 2 && (!frame.digest || frame.digest.size !== got || frame.digest.sha256 !== sha2563)) throw new Error("digest_mismatch");
+            await sink.close();
+            dc?.send(DONE_FRAME);
+            s.setPhase("done");
+          }).catch(() => s.fail("integrity"));
+        } else if (frame.type === "abort") {
+          s.fail("peer_abort");
+        }
+      } catch {
+        s.fail("protocol");
+      }
+    };
+    dc.onclose = () => {
+      if (!s.isTerminal()) s.fail("peer_closed");
+    };
+  };
+  return {
+    accept: (msg) => {
+      if (s.isTerminal()) return;
+      s.signaled();
+      if (msg.kind === "offer" && (!pc.remoteDescription || pc.signalingState === "stable")) {
+        const isRestart = !!pc.remoteDescription;
+        const offerGeneration = msg.generation ?? (isRestart ? generation + 1 : 1);
+        if (isRestart && msg.generation !== void 0 && offerGeneration <= generation) return;
+        generation = offerGeneration;
+        protocol = msg.protocol === 2 ? 2 : 1;
+        plumbing.expectRemoteGeneration(generation);
+        plumbing.setLocalGeneration(generation);
+        void (async () => {
+          if (isRestart && opts.refreshIce) {
+            const iceServers = await opts.refreshIce();
+            s.setIceServers(iceServers);
+          }
+          await pc.setRemoteDescription({ type: "offer", sdp: msg.sdp });
+          plumbing.remoteDescriptionSet(generation);
+          const answer = await pc.createAnswer();
+          await pc.setLocalDescription(answer);
+          await opts.send({ kind: "answer", sdp: answer.sdp, protocol: 2, generation });
+        })().catch(() => s.fail("signaling"));
+      }
+      if (msg.kind === "ice") plumbing.applyIce(msg.candidate, msg.generation);
+    },
+    close: () => {
+      if (!s.isTerminal() && dc?.readyState === "open") {
+        try {
+          dc.send(ABORT_FRAME);
+        } catch {
+        }
+      }
+      sinkRef?.abort?.();
+      s.cleanup();
+    }
+  };
+}
 
 // src/shared/direct-fallback.ts
 function createFallbackMeta(file) {
@@ -1396,6 +1554,15 @@ function partPlainBytes(meta, partNumber) {
   if (partNumber < meta.part_count) return meta.part_bytes;
   return meta.size - meta.part_bytes * (meta.part_count - 1);
 }
+function fallbackCipherPartBytes(meta, partNumber) {
+  return partPlainBytes(meta, partNumber) + meta.tag_bytes;
+}
+function fallbackCipherOffset(meta, partNumber) {
+  if (!Number.isInteger(partNumber) || partNumber < 1 || partNumber > meta.part_count) {
+    throw new Error("bad_fallback_part");
+  }
+  return (partNumber - 1) * (meta.part_bytes + meta.tag_bytes);
+}
 function ivFor(meta, partNumber) {
   const iv = new Uint8Array(12);
   iv.set(b64ToBytes(meta.nonce_b64), 0);
@@ -1431,6 +1598,21 @@ async function encryptFallbackPart(meta, offerId, partNumber, plain, key) {
   );
   return new Uint8Array(out);
 }
+async function decryptFallbackPart(meta, offerId, partNumber, cipher, key) {
+  const plainBytes = partPlainBytes(meta, partNumber);
+  if (cipher.length !== plainBytes + meta.tag_bytes) throw new Error("bad_fallback_part_size");
+  const out = await crypto.subtle.decrypt(
+    {
+      name: "AES-GCM",
+      iv: ivFor(meta, partNumber),
+      additionalData: aadFor(offerId, partNumber, plainBytes),
+      tagLength: 128
+    },
+    key ?? await aesKey(meta),
+    cipher
+  );
+  return new Uint8Array(out);
+}
 var RETRIES = 3;
 var URL_BATCH = 16;
 var CONCURRENCY = 2;
@@ -1500,6 +1682,74 @@ async function uploadFallback(options) {
   }
   return completed.sort((a, b) => a.partNumber - b.partNumber);
 }
+async function downloadFallback(options) {
+  const { meta, offerId, sink, signal } = options;
+  fallbackMetaOf(meta);
+  const key = await aesKey(meta);
+  const fetcher = options.fetcher ?? fetch;
+  let partNumber = 1;
+  let plainDone = 0;
+  let attempts = 0;
+  try {
+    while (partNumber <= meta.part_count) {
+      aborted(signal);
+      const cipherOffset = fallbackCipherOffset(meta, partNumber);
+      try {
+        const url = await options.getUrl();
+        const response = await fetcher(url, {
+          headers: cipherOffset > 0 ? { Range: `bytes=${cipherOffset}-` } : void 0,
+          signal
+        });
+        if (!response.ok || cipherOffset > 0 && response.status !== 206 || !response.body) {
+          throw new Error(`fallback_get_${response.status}`);
+        }
+        const reader = response.body.getReader();
+        const held = [];
+        let heldBytes = 0;
+        while (partNumber <= meta.part_count) {
+          const needed = fallbackCipherPartBytes(meta, partNumber);
+          while (heldBytes < needed) {
+            const next = await reader.read();
+            if (next.done) throw new Error("fallback_get_short");
+            held.push(next.value);
+            heldBytes += next.value.length;
+          }
+          const cipher = new Uint8Array(needed);
+          let copied = 0;
+          while (copied < needed) {
+            const chunk = held.shift();
+            const take = Math.min(chunk.length, needed - copied);
+            cipher.set(chunk.subarray(0, take), copied);
+            copied += take;
+            heldBytes -= take;
+            if (take < chunk.length) held.unshift(chunk.subarray(take));
+          }
+          const plain = await decryptFallbackPart(meta, offerId, partNumber, cipher, key);
+          await sink.write(plain);
+          plainDone += plain.length;
+          partNumber++;
+          attempts = 0;
+          options.onProgress?.(plainDone, meta.size);
+        }
+        if (heldBytes > 0) throw new Error("fallback_get_long");
+      } catch (error) {
+        if (error.name === "AbortError") throw error;
+        if (error.name === "OperationError" || error.message === "fallback_get_long") {
+          throw error;
+        }
+        attempts++;
+        if (attempts >= RETRIES) throw error;
+        options.onRetry?.();
+        await pause(250 * 2 ** (attempts - 1), signal);
+      }
+    }
+    if (plainDone !== meta.size) throw new Error("fallback_plain_size");
+    await sink.close();
+  } catch (error) {
+    sink.abort?.();
+    throw error;
+  }
+}
 
 // src/shared/sharedchannel.ts
 import { xchacha20poly1305 as xchacha20poly13052 } from "@noble/ciphers/chacha";
@@ -2206,7 +2456,7 @@ async function directGrantFor(ctx, channel) {
   if (!grant.direct_mode) throw new ZasError("not_direct_mode", 409);
   return grant;
 }
-function nameOf(ctx, grant) {
+function channelLabel(ctx, grant) {
   try {
     return channelNameOf(ctx.identity, grant);
   } catch {
@@ -2224,7 +2474,7 @@ async function sendDirect(ctx, input, report, deps = {}) {
   const sleep2 = deps.sleep ?? defaultSleep2;
   const grant = await directGrantFor(ctx, input.channel);
   const key = channelKeyOf(ctx.identity, grant);
-  const channelName = nameOf(ctx, grant);
+  const channelName = channelLabel(ctx, grant);
   const file = await (deps.openFile ?? openAsBlob)(input.path).catch(() => {
     throw new ZasError("upload_failed", 400);
   });
@@ -2423,80 +2673,19 @@ async function sendDirectFallback(ctx, record, report, deps = {}) {
   };
 }
 
-// src/jobs.ts
-import { randomUUID } from "node:crypto";
-var DEFAULT_WAIT_MS = 6e4;
-var HISTORY = 50;
-var JobRunner = class {
-  now;
-  waitMs;
-  /** Newest first, and trimmed. */
-  jobs = [];
-  /** Keyed on the job object, not its id, so a caller holding a job that has
-   *  already aged out of the list can still wait for it to finish. */
-  settled = /* @__PURE__ */ new WeakMap();
-  constructor(opts = {}) {
-    this.now = opts.now ?? (() => Date.now());
-    this.waitMs = opts.waitMs ?? DEFAULT_WAIT_MS;
-  }
-  start(kind, title, channel, work) {
-    const job = {
-      id: randomUUID(),
-      kind,
-      title,
-      channel,
-      started_at: this.now(),
-      phase: null,
-      status: "running"
-    };
-    this.jobs.unshift(job);
-    this.jobs.length = Math.min(this.jobs.length, HISTORY);
-    const report = (phase) => {
-      if (job.status === "running") job.phase = phase;
-    };
-    this.settled.set(job, work(report).then(
-      (result) => {
-        job.status = "done";
-        job.result = result;
-        return job;
-      },
-      (error) => {
-        job.status = "failed";
-        job.error = error instanceof ZasError ? {
-          code: error.code,
-          status: error.status,
-          sentence: humanSentence(error),
-          message: error.message,
-          ...error.retryAfterMs !== void 0 ? { retryAfterMs: error.retryAfterMs } : {},
-          ...error.serverCode !== void 0 ? { serverCode: error.serverCode } : {}
-        } : { code: "upload_failed", status: 0, sentence: humanSentence(new ZasError("upload_failed", 0)) };
-        return job;
-      }
-    ));
-    return job;
-  }
-  /** Resolves when the work settles, or when the wait runs out — the same job
-   *  object either way, so the caller reads `status` rather than guessing. */
-  async wait(job) {
-    const settled = this.settled.get(job);
-    if (!settled) return job;
-    let timer;
-    const deadline = new Promise((resolve2) => {
-      timer = setTimeout(() => resolve2(job), this.waitMs);
-    });
-    try {
-      return await Promise.race([settled, deadline]);
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-  list() {
-    return this.jobs.slice(0, HISTORY);
-  }
-  get(id) {
-    return this.jobs.find((job) => job.id === id);
-  }
-};
+// src/receive.ts
+import { randomBytes as randomBytes3 } from "node:crypto";
+import {
+  closeSync as closeSync2,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  openSync as openSync2,
+  renameSync as renameSync3,
+  rmdirSync as rmdirSync2,
+  unlinkSync as unlinkSync2,
+  writeSync as writeSync2
+} from "node:fs";
+import { dirname as dirname2 } from "node:path";
 
 // src/read.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
@@ -2753,9 +2942,392 @@ async function getItem(ctx, channel, id, dest) {
   return { path: target, bytes: written };
 }
 
+// src/receive.ts
+var OFFER_WAIT_MS2 = 9.5 * 60 * 1e3;
+var OFFER_POLL_MS2 = 1e3;
+var SIGNAL_POLL_MS2 = 400;
+var OFFER_PAGE = 10;
+var OPEN_OFFERS = {
+  from: [{ collectionId: "direct" }],
+  orderBy: [{ field: { fieldPath: "created_at" }, direction: "DESCENDING" }],
+  limit: OFFER_PAGE
+};
+var SIGNALS_FOR_RECEIVER = {
+  from: [{ collectionId: "signals" }],
+  where: { fieldFilter: { field: { fieldPath: "for" }, op: "EQUAL", value: { stringValue: "receiver" } } }
+};
+var stringField2 = (doc, key) => doc?.fields?.[key]?.stringValue;
+var idOf = (doc) => (doc.name ?? "").split("/").pop() ?? "";
+async function receiveGrantFor(ctx, channel) {
+  const grant = resolveChannel(ctx.identity, await grantsFor(ctx.client, ctx.profile), channel);
+  if (!grant.read) throw new ZasError("read_forbidden", 403);
+  if (!grant.direct_mode) throw new ZasError("not_direct_mode", 409);
+  return grant;
+}
+var DiskSink = class {
+  constructor(dest, fallbackName) {
+    this.dest = dest;
+    this.fallbackName = fallbackName;
+  }
+  /** Where the bytes will be once `close` has run. */
+  target;
+  written = 0;
+  /** A filesystem refusal, kept so the run can answer `write_failed` rather
+   *  than reporting the engine's generic sink failure. */
+  failure;
+  created;
+  tmp;
+  fd;
+  open(meta) {
+    try {
+      const chosen = destinationOf(this.dest, meta.name, this.fallbackName);
+      this.target = chosen.target;
+      this.created = chosen.created;
+      mkdirSync3(dirname2(this.target), { recursive: true, mode: 448 });
+      this.tmp = `${this.target}.${randomBytes3(6).toString("hex")}.tmp`;
+      this.fd = openSync2(this.tmp, "wx", 384);
+    } catch (error) {
+      throw this.remember(error);
+    }
+  }
+  write(bytes) {
+    try {
+      if (this.fd === void 0) throw new Error("sink_closed");
+      this.written += writeSync2(this.fd, bytes);
+    } catch (error) {
+      throw this.remember(error);
+    }
+  }
+  close() {
+    try {
+      if (this.fd === void 0) return;
+      closeSync2(this.fd);
+      this.fd = void 0;
+      renameSync3(this.tmp, this.target);
+      this.tmp = void 0;
+    } catch (error) {
+      throw this.remember(error);
+    }
+  }
+  /** Best effort, and safe to call twice: the engine aborts on every failure
+   *  path of its own, and the job aborts again on the way out. */
+  abort() {
+    if (this.fd !== void 0) {
+      try {
+        closeSync2(this.fd);
+      } catch {
+      }
+      this.fd = void 0;
+    }
+    if (this.tmp !== void 0) {
+      if (existsSync3(this.tmp)) try {
+        unlinkSync2(this.tmp);
+      } catch {
+      }
+      this.tmp = void 0;
+    }
+    if (this.created !== void 0) {
+      try {
+        rmdirSync2(this.created);
+      } catch {
+      }
+      this.created = void 0;
+    }
+  }
+  /** A `ZasError` says what happened already. An errno does not, so it is kept
+   *  and turned into one sentence by the caller — recognised by the shape Node
+   *  puts on it (`syscall`/`errno`) rather than by `code`, which `ZasError`
+   *  also carries. */
+  remember(error) {
+    const failure = error;
+    if (typeof failure?.syscall === "string" || typeof failure?.errno === "number") this.failure = failure;
+    return error;
+  }
+};
+async function receiveDirect(ctx, input, report, deps = {}) {
+  const now = deps.now ?? (() => Date.now());
+  const sleep2 = deps.sleep ?? defaultSleep2;
+  const grant = await receiveGrantFor(ctx, input.channel);
+  const key = channelKeyOf(ctx.identity, grant);
+  const channelName = channelLabel(ctx, grant);
+  const cid = grant.channel_id;
+  const owner = ctx.identity.owner_uid;
+  const device = deps.device ?? newDeviceToken();
+  const { seal, open } = sealer(key, grant.key_version);
+  const stamp = { device, owner_uid: owner };
+  const startedAt = now();
+  const channelPath = `accounts/${owner}/channels/${cid}`;
+  report("waiting");
+  const waitUntil = startedAt + (deps.offerWaitMs ?? OFFER_WAIT_MS2);
+  let id;
+  let meta;
+  while (id === void 0) {
+    const rows = await ctx.client.firestoreRunQuery(channelPath, OPEN_OFFERS).catch(() => []);
+    for (const row of rows) {
+      if (stringField2(row, "state") !== "open") continue;
+      if (stringField2(row, "sender") === ctx.identity.agent_uid) continue;
+      const enc = stringField2(row, "meta_enc");
+      if (enc === void 0) continue;
+      let candidate;
+      try {
+        candidate = open(enc);
+      } catch {
+        continue;
+      }
+      if (typeof candidate?.name !== "string" || typeof candidate?.size !== "number") continue;
+      if (candidate.size > DIRECT_FILE_MAX_BYTES) throw new ZasError("file_too_big", 413);
+      const offerId2 = idOf(row);
+      if (offerId2 === "") continue;
+      try {
+        await ctx.client.api("POST", `/direct/${cid}/${offerId2}/claim`, { size_bytes: candidate.size, ...stamp });
+      } catch (error) {
+        const word = error instanceof ZasError ? error.serverCode ?? error.code : "";
+        if (word === "claimed") throw new ZasError("offer_taken", 409);
+        if (word === "expired" || word === "own_offer" || word === "not_found") continue;
+        throw error;
+      }
+      id = offerId2;
+      meta = candidate;
+      break;
+    }
+    if (id !== void 0) break;
+    if (now() >= waitUntil) throw new ZasError("no_offer", 0);
+    await sleep2(deps.offerPollMs ?? OFFER_POLL_MS2);
+  }
+  const offered = meta;
+  const offerId = id;
+  const route = `/direct/${cid}/${offerId}`;
+  const offerPath = `${channelPath}/direct/${offerId}`;
+  const setState = (state) => ctx.client.api("POST", `${route}/state`, { state, ...stamp }).then(() => void 0, () => void 0);
+  await (deps.installWebRtc ?? installWebRtc)();
+  const fetchIce = async () => {
+    try {
+      const r = await ctx.client.api("POST", `${route}/ice`, stamp);
+      return Array.isArray(r.ice) ? r.ice : [];
+    } catch {
+      return [];
+    }
+  };
+  const turn = await fetchIce();
+  report("connecting");
+  const sink = new DiskSink(input.dest, offerId);
+  let resolveOutcome;
+  const outcome = new Promise((resolve2) => {
+    resolveOutcome = resolve2;
+  });
+  let diag;
+  let via;
+  const handle = (deps.engine ?? startReceiver)({
+    ice: [...DIRECT_ICE, ...turn],
+    refreshIce: async () => [...DIRECT_ICE, ...await fetchIce()],
+    // The name and size this end read off the offer. The engine refuses a
+    // sender that announces anything else.
+    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 === "done" || phase2 === "failed") resolveOutcome(phase2);
+    },
+    onPath: (p) => {
+      via = p;
+    },
+    onDiag: (d) => {
+      diag = d;
+    },
+    sink: async (m) => {
+      sink.open(m);
+      return sink;
+    }
+  });
+  let over = false;
+  const pump = (async () => {
+    const seen = /* @__PURE__ */ new Set();
+    while (!over) {
+      let rows = [];
+      try {
+        rows = await ctx.client.firestoreRunQuery(offerPath, SIGNALS_FOR_RECEIVER);
+      } catch {
+      }
+      for (const row of rows) {
+        if (!row?.name || seen.has(row.name)) continue;
+        seen.add(row.name);
+        const enc = stringField2(row, "payload_enc");
+        if (!enc) continue;
+        try {
+          handle.accept(open(enc));
+        } catch {
+        }
+      }
+      if (!over) await Promise.race([outcome, sleep2(deps.signalPollMs ?? SIGNAL_POLL_MS2)]);
+    }
+  })();
+  const phase = await outcome;
+  over = true;
+  await pump;
+  report("finishing");
+  if (phase === "done") {
+    await setState("done");
+    return {
+      offer_id: offerId,
+      channel_id: cid,
+      channel_name: channelName,
+      name: offered.name,
+      bytes: sink.written,
+      path: sink.target,
+      ...via ? { via } : {},
+      duration_ms: now() - startedAt
+    };
+  }
+  sink.abort();
+  const doc = await ctx.client.firestoreGet(offerPath).catch(() => null);
+  const withdrawn = doc === null || stringField2(doc, "state") === "cancelled";
+  await setState("failed");
+  if (sink.failure) throw new ZasError("write_failed", 0, sink.failure.message);
+  if (withdrawn) throw new ZasError("direct_cancelled", 0);
+  const reason = diag?.reason || "unknown";
+  deps.onFailed?.({
+    channel_id: cid,
+    channel_name: channelName,
+    offer_id: offerId,
+    owner_uid: owner,
+    device,
+    ...input.dest !== void 0 ? { dest: input.dest } : {},
+    meta: offered,
+    key,
+    key_version: grant.key_version,
+    reason
+  });
+  throw new ZasError("direct_failed", 0, reason);
+}
+async function receiveDirectFallback(ctx, record, report, deps = {}) {
+  const now = deps.now ?? (() => Date.now());
+  const startedAt = now();
+  const { open } = 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`;
+  const offerPath = `accounts/${record.owner_uid}/channels/${record.channel_id}/direct/${record.offer_id}`;
+  const doc = await ctx.client.firestoreGet(offerPath);
+  const enc = stringField2(doc, "fallback_meta_enc");
+  let meta;
+  if (enc !== void 0) {
+    try {
+      meta = fallbackMetaOf(open(enc));
+    } catch {
+      meta = void 0;
+    }
+  }
+  if (!meta) throw new ZasError("fallback_unavailable", 409);
+  if (meta.name !== record.meta.name || meta.size !== record.meta.size || meta.mime !== record.meta.mime) {
+    throw new ZasError("file_changed", 0);
+  }
+  const sink = new DiskSink(record.dest, record.offer_id);
+  report("downloading");
+  try {
+    sink.open(meta);
+    await downloadFallback({
+      offerId: record.offer_id,
+      meta,
+      sink,
+      getUrl: async () => (await ctx.client.api("POST", `${base}/download`, stamp)).url,
+      ...deps.fetcher ? { fetcher: deps.fetcher } : {}
+    });
+  } catch (error) {
+    sink.abort();
+    if (sink.failure) throw new ZasError("write_failed", 0, sink.failure.message);
+    if (error instanceof ZasError) throw error;
+    throw new ZasError("network", 0, error instanceof Error ? error.message : String(error));
+  }
+  report("finishing");
+  await ctx.client.api("POST", `${base}/received`, stamp);
+  return {
+    offer_id: record.offer_id,
+    channel_id: record.channel_id,
+    channel_name: record.channel_name,
+    name: meta.name,
+    bytes: sink.written,
+    path: sink.target,
+    duration_ms: now() - startedAt
+  };
+}
+
+// src/jobs.ts
+import { randomUUID } from "node:crypto";
+var DEFAULT_WAIT_MS = 6e4;
+var HISTORY = 50;
+var JobRunner = class {
+  now;
+  waitMs;
+  /** Newest first, and trimmed. */
+  jobs = [];
+  /** Keyed on the job object, not its id, so a caller holding a job that has
+   *  already aged out of the list can still wait for it to finish. */
+  settled = /* @__PURE__ */ new WeakMap();
+  constructor(opts = {}) {
+    this.now = opts.now ?? (() => Date.now());
+    this.waitMs = opts.waitMs ?? DEFAULT_WAIT_MS;
+  }
+  start(kind, title, channel, work) {
+    const job = {
+      id: randomUUID(),
+      kind,
+      title,
+      channel,
+      started_at: this.now(),
+      phase: null,
+      status: "running"
+    };
+    this.jobs.unshift(job);
+    this.jobs.length = Math.min(this.jobs.length, HISTORY);
+    const report = (phase) => {
+      if (job.status === "running") job.phase = phase;
+    };
+    this.settled.set(job, work(report).then(
+      (result) => {
+        job.status = "done";
+        job.result = result;
+        return job;
+      },
+      (error) => {
+        job.status = "failed";
+        job.error = error instanceof ZasError ? {
+          code: error.code,
+          status: error.status,
+          sentence: humanSentence(error),
+          message: error.message,
+          ...error.retryAfterMs !== void 0 ? { retryAfterMs: error.retryAfterMs } : {},
+          ...error.serverCode !== void 0 ? { serverCode: error.serverCode } : {}
+        } : { code: "upload_failed", status: 0, sentence: humanSentence(new ZasError("upload_failed", 0)) };
+        return job;
+      }
+    ));
+    return job;
+  }
+  /** Resolves when the work settles, or when the wait runs out — the same job
+   *  object either way, so the caller reads `status` rather than guessing. */
+  async wait(job) {
+    const settled = this.settled.get(job);
+    if (!settled) return job;
+    let timer;
+    const deadline = new Promise((resolve2) => {
+      timer = setTimeout(() => resolve2(job), this.waitMs);
+    });
+    try {
+      return await Promise.race([settled, deadline]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  list() {
+    return this.jobs.slice(0, HISTORY);
+  }
+  get(id) {
+    return this.jobs.find((job) => job.id === id);
+  }
+};
+
 // src/server.ts
 function agentVersion() {
-  return true ? "0.4.0" : "0.0.0-dev";
+  return true ? "0.5.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;
@@ -2766,7 +3338,7 @@ var delay = (ms) => new Promise((resolve2) => {
 function rightsOf(grant) {
   const rights = [];
   if (grant.send && grant.mode !== "view") rights.push(grant.direct_mode ? "send (Directo)" : "send");
-  if (grant.read) rights.push("read");
+  if (grant.read) rights.push(grant.direct_mode ? "receive (Directo)" : "read");
   return rights.length > 0 ? rights.join(" \xB7 ") : "no access";
 }
 function buildServer(profile, deps = {}) {
@@ -2972,6 +3544,58 @@ function buildServer(profile, deps = {}) {
       return failed(e);
     }
   });
+  const failedReceives = /* @__PURE__ */ new Map();
+  const rememberFailedReceive = (jobId, record) => {
+    failedReceives.set(jobId, record);
+    if (failedReceives.size > 50) failedReceives.delete(failedReceives.keys().next().value);
+  };
+  server.registerTool("zas_receive_direct", {
+    description: "Receive a file the owner sends through Directo, straight onto this machine. Call it when the owner says they are sending you something: it waits for the offer, takes it, and writes the file to disk. Nothing is stored anywhere. Only for a channel in Directo mode, and only with a grant that includes reading. The call waits a minute and then returns a job id to check with zas_jobs; the wait for an offer alone can take ten minutes. Returns the path written; it never overwrites an existing file." + AGENT_CUE,
+    inputSchema: {
+      channel: z.string().optional().describe("Channel name or id. Optional when the agent holds exactly one channel."),
+      dest: z.string().optional().describe('Where to write the file. A directory means "inside it". Defaults to a fresh temporary directory.')
+    }
+  }, async (input) => {
+    try {
+      const c = ctx();
+      let job;
+      job = runner.start(
+        "receive",
+        input.dest ?? "Directo",
+        input.channel ?? "",
+        (report) => receiveDirect(c, input, report, {
+          ...deps.receive ?? {},
+          onFailed: (record) => rememberFailedReceive(job.id, record)
+        })
+      );
+      return settled(await runner.wait(job));
+    } catch (e) {
+      return failed(e);
+    }
+  });
+  server.registerTool("zas_receive_direct_fallback", {
+    description: "After a zas_receive_direct job failed in flight, download the encrypted copy the sender chose to store instead. It works only if the person who was sending picked reliable delivery for that transfer. The file is decrypted on this machine and written to the same destination. Pass the failed job\u2019s id." + AGENT_CUE,
+    inputSchema: {
+      job: z.string().describe("The job id zas_receive_direct or zas_jobs reported for the receive that failed.")
+    }
+  }, async (input) => {
+    try {
+      const c = ctx();
+      const record = failedReceives.get(input.job);
+      if (!record) return failed(new ZasError("direct_not_failed", 0));
+      const job = runner.start(
+        "fallback",
+        record.meta.name,
+        record.channel_name,
+        (report) => receiveDirectFallback(c, record, report, deps.receive)
+      );
+      const outcome = await runner.wait(job);
+      if (outcome.status === "done") failedReceives.delete(input.job);
+      return settled(outcome);
+    } catch (e) {
+      return failed(e);
+    }
+  });
   server.registerTool("zas_send_note", {
     description: "Send a note \u2014 plain text, or a code snippet with its language \u2014 into one of the owner's Zas channels." + AGENT_CUE,
     inputSchema: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zas-agent",
-  "version": "0.4.0",
-  "description": "MCP server that lets a coding agent send files and notes into your Zas channels, and files through Directo.",
+  "version": "0.5.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",
   "author": "Sebastian Fernandez Quezada",