zas-agent 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-05
+
+### Added
+
+- `expires_in_days` on `zas_send_file` and `zas_send_note`. An agent can ask
+  an item to live for as little as one whole day — worth setting for output
+  that is stale tomorrow, such as a build log, a test run, or a screenshot of
+  a bug already fixed, so a channel is not left holding five days of noise.
+  It can only ever shorten an item. The server clamps the request to what the
+  account's plan grants, so asking for longer is answered with the plan's own
+  life rather than refused.
+- The lifetime is part of a send's identity. Both replay guards — the receipt
+  on disk and the server's idempotency key — hash it in, so "send that again,
+  but for one day" no longer matches the five-day receipt and answers with the
+  old item's id, having created nothing. A send that asks for nothing hashes
+  exactly as it did before, so every receipt already on disk still matches.
+
+### Fixed
+
+- A Directo send of a file of 4 GiB or more delivered only its first
+  gigabytes, and both ends agreed the transfer was whole. Node's `openAsBlob`
+  truncates `Blob.size` to 32 bits and its own `slice()` clamps to that
+  truncated size, so a 9 GiB file offered 1 GiB and sent 1 GiB. The sender now
+  trusts the on-disk size and reads true 64-bit offsets. A file under 4 GiB is
+  handed to the engine exactly as it was.
+- A receiver restricted to relay candidates could not gather at all, so a
+  browser on a `relay` transport policy never received from an agent. Its ICE
+  is trimmed only when it genuinely cannot allocate over UDP.
+- Chromium 152 returns no candidate from an ICE url on port 53, and that url
+  also suppresses the UDP relay and the server-reflexive candidate, so a
+  browser on that version could not reach an agent at all. The port-53 urls
+  are dropped for Chromium 152 and later, under every transport policy.
+- The selected candidate pair is read twice — when ICE connects and when the
+  data channel opens — and a local `srflx` is re-identified as `prflx` once
+  the peer's check reveals the same address. The summary kept the last read
+  and the trace kept the first, so one pair was named two ways. The trace now
+  says `pair now …` when the read changes.
+
+### Changed
+
+- The install and register commands know which shell they are pasted into.
+  Windows takes `npx.cmd` and a `cmd /d /c ` prefix, because npm installs
+  `claude` and `codex` as PowerShell script shims that keep a bare `--` for
+  themselves. Every command now names `@latest`, so npm requests the published
+  package instead of selecting an unbuilt local workspace copy. The README
+  gives both platforms, and the prerequisites, in order.
+
+## [0.6.3] - 2026-09-04
+
+### Fixed
+
+- The selected candidate pair is read from the transport, which names its
+  own pair on every engine. A transfer that connected and carried its whole
+  file could report `pair=none`, because the browser at the other end does
+  not mark a pair `nominated` on the controlled side. The empty field was
+  read as a missing pair and sent two rounds of diagnosis after a
+  connection that had been there all along.
+- A peer connection state of `failed` has to hold before the engine acts on
+  it. Chrome reports `failed` while it is still gathering and returns to
+  `connecting` in the same millisecond; acting on the first one killed a
+  receiver at 0.88 s with pairs still waiting to be tried. The settle window
+  is shorter than the ICE grace, so a connection that really is dead still
+  gives up sooner than it did before.
+
+### Added
+
+- The trace counts candidate pairs by check state just before the verdict:
+  `checks failed=24 in-progress=4`, or `checks none`. No pair selected could
+  not tell a run that formed no pairs from one that formed pairs and lost
+  every check, and those are different faults.
+- A candidate the peer refuses is traced as `ice apply rejected <type>
+  <ErrorName>`. The rejection used to be swallowed, so a refused candidate
+  looked exactly like one the network lost.
+
 ## [0.6.2] - 2026-09-04
 
 ### Added
@@ -205,7 +279,9 @@ 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.6.2...HEAD
+[Unreleased]: https://github.com/soke1556/zas-agent/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/soke1556/zas-agent/compare/v0.6.3...v0.7.0
+[0.6.3]: https://github.com/soke1556/zas-agent/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/soke1556/zas-agent/compare/v0.6.1...v0.6.2
 [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

package/README.md

@@ -36,33 +36,48 @@ get a short-lived session.
 
 ## Install
 
-Pair the agent first, then hand the command to your harness.
+Install [Node.js LTS](https://nodejs.org/en/download) (22 or newer) and your
+agent's command-line tool first. Reopen your terminal after installing.
+Run these commands on the computer where you use the agent.
 
-**Pair**
+Choose your agent and pair it. On Windows (PowerShell or CMD):
+
+**Codex**
 
 ```
-npx -y zas-agent pair --profile claude-code
+npx.cmd -y zas-agent@latest pair --profile codex
 ```
 
 **Claude Code**
 
 ```
-claude mcp add zas "--" npx -y zas-agent --profile claude-code
+npx.cmd -y zas-agent@latest pair --profile claude-code
 ```
 
+Open the printed link, approve the channels, and enter the code in the terminal
+if the page shows one. Leave the terminal open until pairing finishes.
+Then run the matching registration command:
+
 **Codex**
 
 ```
-codex mcp add zas "--" npx -y zas-agent --profile codex
+cmd /d /c codex mcp add zas "--" npx.cmd -y zas-agent@latest --profile codex
 ```
 
-Codex by hand, if you would rather edit `~/.codex/config.toml`:
+**Claude Code**
 
-```toml
-[mcp_servers.zas]
-command = "npx"
-args = ["-y", "zas-agent", "--profile", "codex"]
 ```
+cmd /d /c claude mcp add zas "--" npx.cmd -y zas-agent@latest --profile claude-code
+```
+
+On macOS, Linux, or WSL, use `npx` in place of `npx.cmd` and omit
+`cmd /d /c `. Pair and register in the same environment. Restart your agent
+and ask it to send something to Zas.
+
+If a command is not recognized, install Node.js or the named agent's CLI and
+reopen the terminal. The first download needs internet access and may take a
+few minutes. Use `@latest` as shown so npm requests the published package
+instead of selecting an unbuilt local workspace.
 
 ### What pairing does
 

package/dist/cli.js

@@ -598,15 +598,27 @@ var ZasClient = class _ZasClient {
   }
 };
 
+// src/shared/agent-snippets.ts
+function agentSnippets(profile, windows = false, pkg = "zas-agent") {
+  const runner = windows ? "npx.cmd" : "npx";
+  const command = `${runner} -y ${pkg}@latest`;
+  const shell = windows ? "cmd /d /c " : "";
+  return {
+    pair: `${command} pair --profile ${profile}`,
+    claude: `${shell}claude mcp add zas "--" ${command} --profile ${profile}`,
+    codex: `${shell}codex mcp add zas "--" ${command} --profile ${profile}`
+  };
+}
+
 // src/snippets.ts
 function packageName() {
   return true ? "zas-agent" : "zas-agent";
 }
-function claudeSnippet(profile) {
-  return `claude mcp add zas "--" npx -y ${packageName()} --profile ${profile}`;
+function claudeSnippet(profile, windows = process.platform === "win32") {
+  return agentSnippets(profile, windows, packageName()).claude;
 }
-function codexSnippet(profile) {
-  return `codex mcp add zas "--" npx -y ${packageName()} --profile ${profile}`;
+function codexSnippet(profile, windows = process.platform === "win32") {
+  return agentSnippets(profile, windows, packageName()).codex;
 }
 function kindForProfile(profile) {
   if (profile === "claude-code") return "claude_code";
@@ -830,6 +842,41 @@ async function runPair(opts) {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
+// 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 MIN_EXPIRY_DAYS = 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/direct.ts
 var DIRECT_OFFER_TTL_MS = 10 * 60 * 1e3;
 var DIRECT_CLAIMED_TTL_MS = 6 * 60 * 60 * 1e3;
@@ -854,6 +901,8 @@ function directFallbackCipherSize(size) {
 }
 var DIRECT_CONNECT_TIMEOUT_MS = 30 * 1e3;
 var DIRECT_STALL_GRACE_MS = 5 * 1e3;
+var DIRECT_CENSUS_WAIT_MS = 250;
+var DIRECT_CONN_FAILED_SETTLE_MS = 1500;
 var DIRECT_SIGNAL_WAIT_MS = 90 * 1e3;
 
 // src/shared/direct-engine.ts
@@ -969,6 +1018,29 @@ function traceAdd(diag, line) {
   const at = t0 === void 0 ? 0 : (Date.now() - t0) / 1e3;
   diag.trace.push(`${at.toFixed(2)} ${line}`);
 }
+function usableForRelay(url) {
+  const scheme = /^(stuns?|turns?):/i.exec(url)?.[1]?.toLowerCase();
+  if (scheme !== "turn" && scheme !== "turns") return false;
+  return !onPort53(url);
+}
+function onPort53(url) {
+  return /^(stuns?|turns?):[^?]*:53(\?|$)/i.test(url);
+}
+function withoutPort53(servers) {
+  return keepUrls(servers, (url) => !onPort53(url));
+}
+function relayIceServers(servers) {
+  return keepUrls(servers, usableForRelay);
+}
+function keepUrls(servers, keep) {
+  const kept = [];
+  for (const server of servers) {
+    const urls = typeof server.urls === "string" ? [server.urls] : server.urls ?? [];
+    const usable = urls.filter(keep);
+    if (usable.length > 0) kept.push({ ...server, urls: usable });
+  }
+  return kept;
+}
 function urlShape(url) {
   const scheme = /^(stuns?|turns?):/i.exec(url)?.[1]?.toLowerCase() ?? "other";
   const transport = /[?&]transport=(\w+)/i.exec(url)?.[1]?.toLowerCase();
@@ -1022,17 +1094,36 @@ function countTurnUrls(servers) {
 }
 function pairFromStats(stats) {
   let pair;
+  let selectedId;
   stats.forEach((s) => {
+    if (s.type === "transport" && typeof s.selectedCandidatePairId === "string") {
+      selectedId = s.selectedCandidatePairId;
+    }
     if (s.type === "candidate-pair" && s.state === "succeeded" && (s.nominated || s.selected)) {
       pair = s;
     }
   });
+  if (selectedId) {
+    const named = stats.get(selectedId);
+    if (named?.localCandidateId && named.remoteCandidateId) pair = named;
+  }
   if (!pair?.localCandidateId || !pair.remoteCandidateId) return void 0;
   const local = stats.get(pair.localCandidateId);
   const remote = stats.get(pair.remoteCandidateId);
   if (!local?.candidateType || !remote?.candidateType) return void 0;
   return { local: local.candidateType, remote: remote.candidateType };
 }
+function checkCensus(stats) {
+  const counts = /* @__PURE__ */ new Map();
+  stats.forEach((s) => {
+    if (s.type !== "candidate-pair") return;
+    const state = String(s.state ?? "?");
+    counts.set(state, (counts.get(state) ?? 0) + 1);
+  });
+  if (counts.size === 0) return "checks none";
+  const parts = [...counts].map(([state, n]) => `${state}=${n}`);
+  return `checks ${parts.join(" ")}`;
+}
 function pathOf(pair) {
   if (pair.local === "relay" || pair.remote === "relay") return "relay";
   return pair.local === "host" && pair.remote === "host" ? "lan" : "wan";
@@ -1040,8 +1131,14 @@ function pathOf(pair) {
 function hasRemoteDescription(pc) {
   return !!pc.remoteDescription?.sdp;
 }
-function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
-  const initialIce = ice ?? DIRECT_ICE;
+function session(ice, onPhase, onDiag, iceTransportPolicy = "all", skipPort53Urls = false) {
+  const trimIce = (servers) => {
+    if (!skipPort53Urls) return servers;
+    if (iceTransportPolicy !== "relay") return withoutPort53(servers);
+    const trimmed = relayIceServers(servers);
+    return countTurnUrls(trimmed) > 0 ? trimmed : servers;
+  };
+  const initialIce = trimIce(ice ?? DIRECT_ICE);
   const pc = new RTCPeerConnection({
     iceServers: initialIce,
     iceTransportPolicy,
@@ -1059,6 +1156,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
   let phase = "connecting";
   let disconnectTimer;
   let restartTimer;
+  let connFailTimer;
   let stallState = "idle";
   const startedAt = Date.now();
   const diag = {
@@ -1081,12 +1179,32 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
   };
   traceStart.set(diag, startedAt);
   traceAdd(diag, `ice servers ${iceShapes(initialIce)} policy=${iceTransportPolicy}`);
+  const notePair = (pair) => {
+    if (diag.pairLocal === pair.local && diag.pairRemote === pair.remote) return;
+    const changed = diag.pairLocal !== void 0;
+    diag.pairLocal = pair.local;
+    diag.pairRemote = pair.remote;
+    traceAdd(diag, `${changed ? "pair now" : "pair"} ${pair.local}/${pair.remote}`);
+  };
   pc.onicegatheringstatechange = () => {
     traceAdd(diag, `gather ${String(pc.iceGatheringState ?? "")}`);
   };
   const connState = () => String(pc.connectionState ?? "");
   pc.onconnectionstatechange = () => {
-    traceAdd(diag, `conn ${connState()}`);
+    const state = connState();
+    traceAdd(diag, `conn ${state}`);
+    if (state !== "failed") {
+      clearTimeout(connFailTimer);
+      connFailTimer = void 0;
+      return;
+    }
+    if (connFailTimer !== void 0) return;
+    connFailTimer = setTimeout(() => {
+      connFailTimer = void 0;
+      if (connState() !== "failed") return;
+      if (diag.msConnect !== void 0 && onStall) stalled();
+      else failWithCensus("ice_failed");
+    }, DIRECT_CONN_FAILED_SETTLE_MS);
   };
   let channel;
   pc.onicecandidateerror = (e) => {
@@ -1095,6 +1213,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
   };
   const cleanup = () => {
     clearTimeout(waitTimer);
+    clearTimeout(connFailTimer);
     clearTimeout(connectTimer);
     clearTimeout(disconnectTimer);
     clearTimeout(restartTimer);
@@ -1134,6 +1253,20 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     }
     setPhase("failed");
   };
+  const failWithCensus = (reason) => {
+    if (phase === "done" || phase === "failed") return;
+    let reported = false;
+    const report2 = () => {
+      if (reported) return;
+      reported = true;
+      fail(reason);
+    };
+    const guard = setTimeout(report2, DIRECT_CENSUS_WAIT_MS);
+    void pc.getStats().then((stats) => traceAdd(diag, checkCensus(stats))).catch(() => void 0).then(() => {
+      clearTimeout(guard);
+      report2();
+    });
+  };
   const waitTimer = setTimeout(() => fail("peer_silent"), DIRECT_SIGNAL_WAIT_MS);
   let connectTimer;
   let heard = false;
@@ -1143,7 +1276,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     clearTimeout(waitTimer);
     connectTimer = setTimeout(() => {
       const iceUp = pc.iceConnectionState === "connected" || pc.iceConnectionState === "completed";
-      fail(iceUp ? "channel_never_opened" : "connect_timeout");
+      failWithCensus(iceUp ? "channel_never_opened" : "connect_timeout");
     }, DIRECT_CONNECT_TIMEOUT_MS);
   };
   let onStall;
@@ -1153,7 +1286,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     clearTimeout(disconnectTimer);
     if (stallState === "restarting") return;
     if (diag.msConnect === void 0 || !onStall) {
-      fail("disconnected");
+      failWithCensus(diag.msConnect === void 0 ? "ice_failed" : "disconnected");
       return;
     }
     stallState = "restarting";
@@ -1168,7 +1301,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
     traceAdd(diag, `ice ${String(s ?? "")}`);
     if (s === "failed") {
       if (diag.msConnect !== void 0 && onStall) stalled();
-      else fail("ice_failed");
+      else failWithCensus("ice_failed");
     }
     if (s === "disconnected" && stallState === "idle") {
       stallState = "grace";
@@ -1180,10 +1313,7 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
       stallState = "idle";
       void pc.getStats().then((stats) => {
         const pair = pairFromStats(stats);
-        if (!pair || diag.pairLocal) return;
-        diag.pairLocal = pair.local;
-        diag.pairRemote = pair.remote;
-        traceAdd(diag, `pair ${pair.local}/${pair.remote}`);
+        if (pair) notePair(pair);
       }).catch(() => void 0);
     }
   };
@@ -1208,10 +1338,12 @@ function session(ice, onPhase, onDiag, iceTransportPolicy = "all") {
       onStall = fn;
       stallWindowMs = windowMs;
     },
+    notePair,
     setIceServers: (iceServers) => {
-      diag.turnUrlsSupplied = countTurnUrls(iceServers);
-      traceAdd(diag, `ice servers replaced ${iceShapes(iceServers)}`);
-      pc.setConfiguration({ iceServers });
+      const next = trimIce(iceServers);
+      diag.turnUrlsSupplied = countTurnUrls(next);
+      traceAdd(diag, `ice servers replaced ${iceShapes(next)}`);
+      pc.setConfiguration({ iceServers: next });
     }
   };
 }
@@ -1231,8 +1363,14 @@ function signalPlumbing(pc, send, onSendError, diag) {
       generation: localGeneration
     }).catch(onSendError);
   };
+  let applyRejects = 0;
   const apply = (candidate) => {
-    void pc.addIceCandidate(candidate ?? void 0).catch(() => void 0);
+    void pc.addIceCandidate(candidate ?? void 0).catch((e) => {
+      if (applyRejects >= 3) return;
+      applyRejects++;
+      const name = e?.name || "Error";
+      traceAdd(diag, `ice apply rejected ${candidate ? candType(candidate) : "end"} ${name}`);
+    });
   };
   const applyIce = (candidate, generation) => {
     countCand(diag, "remote", candidate);
@@ -1273,7 +1411,13 @@ function signalPlumbing(pc, send, onSendError, diag) {
   };
 }
 function startSender(opts) {
-  const s = session(opts.ice, opts.onPhase, opts.onDiag, opts.iceTransportPolicy);
+  const s = session(
+    opts.ice,
+    opts.onPhase,
+    opts.onDiag,
+    opts.iceTransportPolicy,
+    opts.skipPort53Urls
+  );
   opts.onPhase("connecting");
   const { pc } = s;
   const plumbing = signalPlumbing(pc, opts.send, () => s.fail("signal_send"), s.diag);
@@ -1355,8 +1499,7 @@ function startSender(opts) {
     void pc.getStats().then((stats) => {
       const pair = pairFromStats(stats);
       if (!pair) return;
-      s.diag.pairLocal = pair.local;
-      s.diag.pairRemote = pair.remote;
+      s.notePair(pair);
       opts.onPath?.(pathOf(pair));
     }).catch(() => void 0);
     void pump().catch((e) => s.fail("transfer", e));
@@ -1426,7 +1569,8 @@ function startReceiver(opts) {
       opts.onPhase(p);
     },
     opts.onDiag,
-    opts.iceTransportPolicy
+    opts.iceTransportPolicy,
+    opts.skipPort53Urls
   );
   s.setStall(() => void 0, DIRECT_CONNECT_TIMEOUT_MS * 2);
   opts.onPhase("connecting");
@@ -1452,8 +1596,7 @@ function startReceiver(opts) {
       void pc.getStats().then((stats) => {
         const pair = pairFromStats(stats);
         if (!pair) return;
-        s.diag.pairLocal = pair.local;
-        s.diag.pairRemote = pair.remote;
+        s.notePair(pair);
         opts.onPath?.(pathOf(pair));
       }).catch(() => void 0);
     };
@@ -1568,42 +1711,6 @@ 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 };
 }
@@ -1644,6 +1751,46 @@ function decryptChannelName(channelKey, sealed) {
   return new TextDecoder().decode(openSealed(channelKey, sealed));
 }
 
+// src/file-source.ts
+import { promises as fsp, statSync } from "node:fs";
+async function readFileRange(path, start, length) {
+  const fh = await fsp.open(path, "r");
+  try {
+    const buf = Buffer.allocUnsafe(Math.max(0, length));
+    let read = 0;
+    while (read < length) {
+      const { bytesRead } = await fh.read(buf, read, length - read, start + read);
+      if (bytesRead === 0) break;
+      read += bytesRead;
+    }
+    const out = new Uint8Array(read);
+    out.set(buf.subarray(0, read));
+    return out.buffer;
+  } finally {
+    await fh.close();
+  }
+}
+function directFileFrom(path, raw) {
+  let statSize;
+  try {
+    statSize = statSync(path).size;
+  } catch {
+    return raw;
+  }
+  if (statSize <= raw.size) return raw;
+  const type = raw.type;
+  const file = {
+    size: statSize,
+    type,
+    slice(start, end) {
+      const from = Math.max(0, Math.min(start, statSize));
+      const to = Math.max(from, Math.min(end, statSize));
+      return { arrayBuffer: () => readFileRange(path, from, to - from) };
+    }
+  };
+  return file;
+}
+
 // src/shared/direct-fallback.ts
 function createFallbackMeta(file) {
   const key = crypto.getRandomValues(new Uint8Array(32));
@@ -1950,7 +2097,7 @@ function resolveChannel(identity, grants, channel) {
 }
 
 // src/send.ts
-import { promises as fsp } from "node:fs";
+import { promises as fsp2 } from "node:fs";
 import { basename, extname } from "node:path";
 
 // src/shared/chunker.ts
@@ -2226,6 +2373,10 @@ async function receiptKey(ctx, channelId, contentHash, title) {
   const raw = `${ctx.identity.agent_uid}\0${channelId}\0${contentHash}\0${title}`;
   return blake3Hex(new TextEncoder().encode(raw));
 }
+async function sendIdentity(contentHash, days) {
+  if (days === void 0) return contentHash;
+  return blake3Hex(new TextEncoder().encode(`${contentHash}\0expires_in_days:${days}`));
+}
 function receiptFor(ctx, key) {
   const entries = loadFingerprints(ctx.profile).entries;
   if (!Object.prototype.hasOwnProperty.call(entries, key)) return void 0;
@@ -2374,7 +2525,7 @@ async function placeChunks(ctx, encs) {
     };
   });
 }
-async function postLink(ctx, grant, manifest, placed, idempotencyKey) {
+async function postLink(ctx, grant, manifest, placed, idempotencyKey, expiresInDays) {
   const channelKey = channelKeyOf(ctx.identity, grant);
   const sealed = sealManifest(channelKey, manifest, grant.key_version);
   const created = await ctx.client.api("POST", "/links", {
@@ -2385,7 +2536,10 @@ async function postLink(ctx, grant, manifest, placed, idempotencyKey) {
     // nothing left for the server to verify here. The field stays because the
     // server reads it, and an absent array is not the same as an empty one.
     proofs: [],
-    idempotency_key: idempotencyKey
+    idempotency_key: idempotencyKey,
+    // Absent unless the caller asked. The server clamps whatever arrives to
+    // the account's own plan, so this can only ever shorten the item's life.
+    ...expiresInDays === void 0 ? {} : { expires_in_days: expiresInDays }
   });
   const bound = created.caps ?? {};
   let patched = false;
@@ -2404,7 +2558,7 @@ async function postLink(ctx, grant, manifest, placed, idempotencyKey) {
   return created.link_id;
 }
 async function sendFile(ctx, input, onPhase) {
-  const stat = await fsp.stat(input.path).catch(() => {
+  const stat = await fsp2.stat(input.path).catch(() => {
     throw new ZasError("upload_failed", 400);
   });
   if (!stat.isFile()) throw new ZasError("upload_failed", 400);
@@ -2412,10 +2566,10 @@ async function sendFile(ctx, input, onPhase) {
   const grant = await grantFor(ctx, input.channel);
   const name = basename(input.path);
   const title = input.title ?? name;
-  const file = await fsp.readFile(input.path);
+  const file = await fsp2.readFile(input.path);
   if (file.byteLength > MAX_FILE_BYTES) throw new ZasError("file_too_big", 413);
   const bytes = new Uint8Array(file.buffer, file.byteOffset, file.byteLength);
-  const contentHash = await blake3Hex(bytes);
+  const contentHash = await sendIdentity(await blake3Hex(bytes), input.expires_in_days);
   const key = await receiptKey(ctx, grant.channel_id, contentHash, title);
   const stored = receiptFor(ctx, key);
   if (stored) {
@@ -2466,7 +2620,8 @@ async function sendFile(ctx, input, onPhase) {
     grant,
     manifest,
     placed,
-    agentSendIdempotencyKey(grant.channel_id, contentHash, title)
+    agentSendIdempotencyKey(grant.channel_id, contentHash, title),
+    input.expires_in_days
   );
   const deduplicated = placed.filter((p) => p.proven).length;
   remember(ctx, key, {
@@ -2493,9 +2648,12 @@ async function sendNote(ctx, input) {
   const grant = await grantFor(ctx, input.channel);
   const name = input.title ?? noteName(input.text);
   const encoded = new TextEncoder().encode(input.text);
-  const contentHash = await blake3Hex(new TextEncoder().encode(
-    `${input.lang ?? ""}\0${input.secret ? "1" : "0"}\0${input.text}`
-  ));
+  const contentHash = await sendIdentity(
+    await blake3Hex(new TextEncoder().encode(
+      `${input.lang ?? ""}\0${input.secret ? "1" : "0"}\0${input.text}`
+    )),
+    input.expires_in_days
+  );
   const key = await receiptKey(ctx, grant.channel_id, contentHash, name);
   const stored = receiptFor(ctx, key);
   if (stored) {
@@ -2528,7 +2686,8 @@ async function sendNote(ctx, input) {
     grant,
     manifest,
     [],
-    agentSendIdempotencyKey(grant.channel_id, contentHash, name)
+    agentSendIdempotencyKey(grant.channel_id, contentHash, name),
+    input.expires_in_days
   );
   remember(ctx, key, {
     link_id: linkId,
@@ -2603,9 +2762,10 @@ async function sendDirect(ctx, input, report2, deps = {}) {
   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, { type: mimeFor(input.path) }).catch(() => {
+  const raw = await (deps.openFile ?? openAsBlob)(input.path, { type: mimeFor(input.path) }).catch(() => {
     throw new ZasError("upload_failed", 400);
   });
+  const file = directFileFrom(input.path, raw);
   if (file.size > DIRECT_FILE_MAX_BYTES) throw new ZasError("file_too_big", 413);
   const name = basename2(input.path);
   const cid = grant.channel_id;
@@ -2826,7 +2986,7 @@ import {
   openSync,
   renameSync as renameSync2,
   rmdirSync,
-  statSync,
+  statSync as statSync2,
   unlinkSync,
   writeSync
 } from "node:fs";
@@ -2999,7 +3159,7 @@ function destinationOf(dest, name, fallback) {
     const created = mkdtempSync(join2(tmpdir(), DOWNLOAD_PREFIX));
     return { target: freeName(join2(created, base)), created };
   }
-  const at = statSync(dest, { throwIfNoEntry: false })?.isDirectory() ? join2(dest, base) : dest;
+  const at = statSync2(dest, { throwIfNoEntry: false })?.isDirectory() ? join2(dest, base) : dest;
   return { target: freeName(at) };
 }
 async function getItem(ctx, channel, id, dest) {
@@ -3928,11 +4088,12 @@ async function report(client, properties) {
 
 // src/server.ts
 function agentVersion() {
-  return true ? "0.6.2" : "0.0.0-dev";
+  return true ? "0.7.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;
 var NOTE_LABEL_MAX = 40;
+var EXPIRES_IN_DAYS = z.number().int().min(MIN_EXPIRY_DAYS).optional().describe("How many whole days the item should live for, at least 1. Leave it out for the account's normal life (5 days). It can only shorten an item, never extend one: a longer request is clamped to what the plan grants. Worth setting for output that is stale tomorrow, such as a build log or a test run.");
 var delay = (ms) => new Promise((resolve2) => {
   setTimeout(resolve2, ms);
 });
@@ -4109,7 +4270,8 @@ ${formatDirectDiagLines(job.diag).join("\n")}`) };
     inputSchema: {
       path: z.string().describe("Absolute or relative path of the file to send."),
       channel: z.string().optional().describe("Channel name or id. Optional when the agent holds exactly one channel."),
-      title: z.string().optional().describe("Label for the item. Defaults to the file name.")
+      title: z.string().optional().describe("Label for the item. Defaults to the file name."),
+      expires_in_days: EXPIRES_IN_DAYS
     }
   }, async (input) => {
     try {
@@ -4238,7 +4400,8 @@ ${formatDirectDiagLines(job.diag).join("\n")}`) };
       channel: z.string().optional().describe("Channel name or id. Optional when the agent holds exactly one channel."),
       title: z.string().optional().describe("Label for the item. Defaults to the first line."),
       lang: z.string().optional().describe('Language of the snippet, for highlighting (for example "ts", "py").'),
-      secret: z.boolean().optional().describe("Hide the body behind a cover until the reader opens it.")
+      secret: z.boolean().optional().describe("Hide the body behind a cover until the reader opens it."),
+      expires_in_days: EXPIRES_IN_DAYS
     }
   }, async (input) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zas-agent",
-  "version": "0.6.2",
+  "version": "0.7.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",