@voidly/agent-sdk 3.1.0 → 3.2.1

package/dist/index.d.mts

@@ -85,6 +85,17 @@ interface VoidlyAgentConfig {
     jitterMs?: number;
     /** Use long-poll for listen() instead of short-interval polling (default: true) */
     longPoll?: boolean;
+    /** Auto-persist ratchet state after every send/receive (default: 'memory' = no persistence) */
+    persist?: 'memory' | 'localStorage' | 'indexedDB' | 'file' | 'relay' | 'custom';
+    /** Custom persistence: called after each ratchet step with encrypted blob */
+    onPersist?: (encryptedState: string) => void | Promise<void>;
+    /** Custom persistence: called on startup to load encrypted blob */
+    onLoad?: () => string | null | Promise<string | null>;
+    /** File path for persist: 'file' (Node.js environments only) */
+    persistPath?: string;
+    /** Transport preference for listen() — tries in order, falls back automatically
+     * Default: ['sse', 'long-poll']. Options: 'websocket' | 'sse' | 'long-poll' */
+    transport?: ('websocket' | 'sse' | 'long-poll')[];
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -185,6 +196,12 @@ declare class VoidlyAgent {
     private _rpcPending;
     private _coverTrafficTimer;
     private _rpcListener;
+    private _persistMode;
+    private _onPersist?;
+    private _onLoad?;
+    private _persistPath?;
+    private _persistKey;
+    private _transportPrefs;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -248,6 +265,26 @@ declare class VoidlyAgent {
         signedPrekeyPublic?: string;
         signedPrekeyId?: number;
     };
+    /** Derive persistence encryption key from signing secret */
+    private _derivePersistKey;
+    /** Auto-persist ratchet state (called after every ratchet mutation) */
+    private _persistRatchetState;
+    /** Load persisted ratchet state and restore into memory */
+    private _loadPersistedRatchetState;
+    /** IndexedDB put helper (browser only) */
+    private _idbPut;
+    /** IndexedDB get helper (browser only) */
+    private _idbGet;
+    /**
+     * Force-persist current ratchet state.
+     * Useful to call before process exit to ensure state is saved.
+     */
+    flushRatchetState(): Promise<void>;
+    /**
+     * Restore an agent from credentials with async persistence loading.
+     * Use this instead of `fromCredentials()` when using file/relay/custom persistence.
+     */
+    static fromCredentialsAsync(creds: Parameters<typeof VoidlyAgent.fromCredentials>[0], config?: VoidlyAgentConfig): Promise<VoidlyAgent>;
     /**
      * Get the number of messages that failed to decrypt.
      * Useful for detecting key mismatches, attacks, or corruption.
@@ -300,6 +337,8 @@ declare class VoidlyAgent {
         messageType?: string;
         unreadOnly?: boolean;
     }): Promise<DecryptedMessage[]>;
+    /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+    private _decryptMessages;
     /**
      * Delete a message by ID (must be sender or recipient).
      */

package/dist/index.d.ts

@@ -85,6 +85,17 @@ interface VoidlyAgentConfig {
     jitterMs?: number;
     /** Use long-poll for listen() instead of short-interval polling (default: true) */
     longPoll?: boolean;
+    /** Auto-persist ratchet state after every send/receive (default: 'memory' = no persistence) */
+    persist?: 'memory' | 'localStorage' | 'indexedDB' | 'file' | 'relay' | 'custom';
+    /** Custom persistence: called after each ratchet step with encrypted blob */
+    onPersist?: (encryptedState: string) => void | Promise<void>;
+    /** Custom persistence: called on startup to load encrypted blob */
+    onLoad?: () => string | null | Promise<string | null>;
+    /** File path for persist: 'file' (Node.js environments only) */
+    persistPath?: string;
+    /** Transport preference for listen() — tries in order, falls back automatically
+     * Default: ['sse', 'long-poll']. Options: 'websocket' | 'sse' | 'long-poll' */
+    transport?: ('websocket' | 'sse' | 'long-poll')[];
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -185,6 +196,12 @@ declare class VoidlyAgent {
     private _rpcPending;
     private _coverTrafficTimer;
     private _rpcListener;
+    private _persistMode;
+    private _onPersist?;
+    private _onLoad?;
+    private _persistPath?;
+    private _persistKey;
+    private _transportPrefs;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -248,6 +265,26 @@ declare class VoidlyAgent {
         signedPrekeyPublic?: string;
         signedPrekeyId?: number;
     };
+    /** Derive persistence encryption key from signing secret */
+    private _derivePersistKey;
+    /** Auto-persist ratchet state (called after every ratchet mutation) */
+    private _persistRatchetState;
+    /** Load persisted ratchet state and restore into memory */
+    private _loadPersistedRatchetState;
+    /** IndexedDB put helper (browser only) */
+    private _idbPut;
+    /** IndexedDB get helper (browser only) */
+    private _idbGet;
+    /**
+     * Force-persist current ratchet state.
+     * Useful to call before process exit to ensure state is saved.
+     */
+    flushRatchetState(): Promise<void>;
+    /**
+     * Restore an agent from credentials with async persistence loading.
+     * Use this instead of `fromCredentials()` when using file/relay/custom persistence.
+     */
+    static fromCredentialsAsync(creds: Parameters<typeof VoidlyAgent.fromCredentials>[0], config?: VoidlyAgentConfig): Promise<VoidlyAgent>;
     /**
      * Get the number of messages that failed to decrypt.
      * Useful for detecting key mismatches, attacks, or corruption.
@@ -300,6 +337,8 @@ declare class VoidlyAgent {
         messageType?: string;
         unreadOnly?: boolean;
     }): Promise<DecryptedMessage[]>;
+    /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+    private _decryptMessages;
     /**
      * Delete a message by ID (must be sender or recipient).
      */

package/dist/index.js

@@ -2230,22 +2230,22 @@ var require_nacl_fast = __commonJS({
         randombytes = fn;
       };
       (function() {
-        var crypto2 = typeof self !== "undefined" ? self.crypto || self.msCrypto : null;
-        if (crypto2 && crypto2.getRandomValues) {
+        var crypto = typeof self !== "undefined" ? self.crypto || self.msCrypto : null;
+        if (crypto && crypto.getRandomValues) {
           var QUOTA = 65536;
           nacl2.setPRNG(function(x, n) {
             var i, v = new Uint8Array(n);
             for (i = 0; i < n; i += QUOTA) {
-              crypto2.getRandomValues(v.subarray(i, i + Math.min(n - i, QUOTA)));
+              crypto.getRandomValues(v.subarray(i, i + Math.min(n - i, QUOTA)));
             }
             for (i = 0; i < n; i++) x[i] = v[i];
             cleanup(v);
           });
         } else if (typeof require !== "undefined") {
-          crypto2 = require("crypto");
-          if (crypto2 && crypto2.randomBytes) {
+          crypto = require("crypto");
+          if (crypto && crypto.randomBytes) {
             nacl2.setPRNG(function(x, n) {
-              var i, v = crypto2.randomBytes(n);
+              var i, v = crypto.randomBytes(n);
               for (i = 0; i < n; i++) x[i] = v[i];
               cleanup(v);
             });
@@ -4091,6 +4091,9 @@ var VoidlyAgent = class _VoidlyAgent {
     this._coverTrafficTimer = null;
     // RPC listener handle (started on first onInvoke)
     this._rpcListener = null;
+    // Persistence (v3.2)
+    this._persistMode = "memory";
+    this._persistKey = null;
     this.did = identity.did;
     this.apiKey = identity.apiKey;
     this.signingKeyPair = identity.signingKeyPair;
@@ -4110,6 +4113,11 @@ var VoidlyAgent = class _VoidlyAgent {
     this.longPoll = config?.longPoll !== false;
     this.mlkemPublicKey = identity.mlkemPublicKey || null;
     this.mlkemSecretKey = identity.mlkemSecretKey || null;
+    this._persistMode = config?.persist || "memory";
+    this._onPersist = config?.onPersist;
+    this._onLoad = config?.onLoad;
+    this._persistPath = config?.persistPath;
+    this._transportPrefs = config?.transport || ["sse", "long-poll"];
   }
   // ─── Factory Methods ────────────────────────────────────────────────────────
   /**
@@ -4314,6 +4322,186 @@ var VoidlyAgent = class _VoidlyAgent {
       } : {}
     };
   }
+  // ─── Ratchet Persistence (v3.2) ────────────────────────────────────────────
+  /** Derive persistence encryption key from signing secret */
+  _derivePersistKey() {
+    if (this._persistKey) return this._persistKey;
+    const salt = (0, import_tweetnacl_util.decodeUTF8)("voidly-persist-v1");
+    const input = new Uint8Array(this.signingKeyPair.secretKey.length + salt.length);
+    input.set(this.signingKeyPair.secretKey, 0);
+    input.set(salt, this.signingKeyPair.secretKey.length);
+    this._persistKey = import_tweetnacl.default.hash(input).slice(0, 32);
+    return this._persistKey;
+  }
+  /** Auto-persist ratchet state (called after every ratchet mutation) */
+  async _persistRatchetState() {
+    if (this._persistMode === "memory") return;
+    try {
+      const creds = this.exportCredentials();
+      const data = JSON.stringify(creds.ratchetStates || {});
+      const key = this._derivePersistKey();
+      const nonce = import_tweetnacl.default.randomBytes(24);
+      const encrypted = import_tweetnacl.default.secretbox((0, import_tweetnacl_util.decodeUTF8)(data), nonce, key);
+      const blob = JSON.stringify({ n: (0, import_tweetnacl_util.encodeBase64)(nonce), c: (0, import_tweetnacl_util.encodeBase64)(encrypted), v: 1 });
+      switch (this._persistMode) {
+        case "localStorage":
+          if (typeof localStorage !== "undefined") {
+            localStorage.setItem(`voidly-ratchet-${this.did}`, blob);
+          }
+          break;
+        case "indexedDB":
+          await this._idbPut(blob);
+          break;
+        case "file":
+          if (this._persistPath) {
+            const fs = await import("fs/promises");
+            await fs.writeFile(this._persistPath, blob, "utf-8");
+          }
+          break;
+        case "relay":
+          await this._timedFetch(`${this.baseUrl}/v1/agent/memory/ratchet/state`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json", "X-Agent-Key": this.apiKey },
+            body: JSON.stringify({ value: blob })
+          }).catch(() => {
+          });
+          break;
+        case "custom":
+          if (this._onPersist) await this._onPersist(blob);
+          break;
+      }
+    } catch {
+    }
+  }
+  /** Load persisted ratchet state and restore into memory */
+  async _loadPersistedRatchetState() {
+    if (this._persistMode === "memory") return;
+    let blob = null;
+    try {
+      switch (this._persistMode) {
+        case "localStorage":
+          if (typeof localStorage !== "undefined") {
+            blob = localStorage.getItem(`voidly-ratchet-${this.did}`);
+          }
+          break;
+        case "indexedDB":
+          blob = await this._idbGet();
+          break;
+        case "file":
+          if (this._persistPath) {
+            try {
+              const fs = await import("fs/promises");
+              blob = await fs.readFile(this._persistPath, "utf-8");
+            } catch {
+            }
+          }
+          break;
+        case "relay":
+          try {
+            const res = await this._timedFetch(`${this.baseUrl}/v1/agent/memory/ratchet/state`, {
+              headers: { "X-Agent-Key": this.apiKey }
+            });
+            if (res.ok) {
+              const data = await res.json();
+              blob = data.value;
+            }
+          } catch {
+          }
+          break;
+        case "custom":
+          if (this._onLoad) blob = await this._onLoad();
+          break;
+      }
+    } catch {
+      return;
+    }
+    if (!blob) return;
+    try {
+      const { n, c } = JSON.parse(blob);
+      const key = this._derivePersistKey();
+      const decrypted = import_tweetnacl.default.secretbox.open((0, import_tweetnacl_util.decodeBase64)(c), (0, import_tweetnacl_util.decodeBase64)(n), key);
+      if (!decrypted) return;
+      const states = JSON.parse((0, import_tweetnacl_util.encodeUTF8)(decrypted));
+      for (const [pairId, rs] of Object.entries(states)) {
+        if (this._ratchetStates.has(pairId)) continue;
+        const state = {
+          sendChainKey: (0, import_tweetnacl_util.decodeBase64)(rs.sendChainKey),
+          sendStep: rs.sendStep,
+          recvChainKey: (0, import_tweetnacl_util.decodeBase64)(rs.recvChainKey),
+          recvStep: rs.recvStep,
+          skippedKeys: /* @__PURE__ */ new Map()
+        };
+        if (rs.rootKey) state.rootKey = (0, import_tweetnacl_util.decodeBase64)(rs.rootKey);
+        if (rs.dhSendSecretKey && rs.dhSendPublicKey) {
+          state.dhSendKeyPair = {
+            secretKey: (0, import_tweetnacl_util.decodeBase64)(rs.dhSendSecretKey),
+            publicKey: (0, import_tweetnacl_util.decodeBase64)(rs.dhSendPublicKey)
+          };
+        }
+        if (rs.dhRecvPubKey) state.dhRecvPubKey = (0, import_tweetnacl_util.decodeBase64)(rs.dhRecvPubKey);
+        if (rs.prevSendStep !== void 0) state.prevSendStep = rs.prevSendStep;
+        if (state.sendChainKey.length === 32 && state.recvChainKey.length === 32) {
+          this._ratchetStates.set(pairId, state);
+        }
+      }
+    } catch {
+    }
+  }
+  /** IndexedDB put helper (browser only) */
+  async _idbPut(blob) {
+    if (typeof indexedDB === "undefined") return;
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open("voidly-agent", 1);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains("ratchet")) db.createObjectStore("ratchet");
+      };
+      req.onsuccess = () => {
+        const tx = req.result.transaction("ratchet", "readwrite");
+        tx.objectStore("ratchet").put(blob, this.did);
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+  /** IndexedDB get helper (browser only) */
+  async _idbGet() {
+    if (typeof indexedDB === "undefined") return null;
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open("voidly-agent", 1);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains("ratchet")) db.createObjectStore("ratchet");
+      };
+      req.onsuccess = () => {
+        const tx = req.result.transaction("ratchet", "readonly");
+        const getReq = tx.objectStore("ratchet").get(this.did);
+        getReq.onsuccess = () => resolve(getReq.result || null);
+        getReq.onerror = () => reject(getReq.error);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+  /**
+   * Force-persist current ratchet state.
+   * Useful to call before process exit to ensure state is saved.
+   */
+  async flushRatchetState() {
+    const origMode = this._persistMode;
+    if (origMode === "memory") this._persistMode = "file";
+    await this._persistRatchetState();
+    this._persistMode = origMode;
+  }
+  /**
+   * Restore an agent from credentials with async persistence loading.
+   * Use this instead of `fromCredentials()` when using file/relay/custom persistence.
+   */
+  static async fromCredentialsAsync(creds, config) {
+    const agent = _VoidlyAgent.fromCredentials(creds, config);
+    await agent._loadPersistedRatchetState();
+    return agent;
+  }
   /**
    * Get the number of messages that failed to decrypt.
    * Useful for detecting key mismatches, attacks, or corruption.
@@ -4390,7 +4578,7 @@ var VoidlyAgent = class _VoidlyAgent {
           const combined = new Uint8Array(x25519Shared.length + pqShared.length);
           combined.set(x25519Shared, 0);
           combined.set(pqShared, x25519Shared.length);
-          initialKey = new Uint8Array(await crypto.subtle.digest("SHA-256", combined));
+          initialKey = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", combined));
         } catch {
           initialKey = x25519Shared;
         }
@@ -4489,6 +4677,8 @@ var VoidlyAgent = class _VoidlyAgent {
       payload.thread_id = options.threadId;
       payload.reply_to = options.replyTo;
     }
+    this._persistRatchetState().catch(() => {
+    });
     const relays = [this.baseUrl, ...this.fallbackRelays];
     let lastError = null;
     for (const relay of relays) {
@@ -4547,8 +4737,12 @@ var VoidlyAgent = class _VoidlyAgent {
       throw new Error(`Receive failed: ${err.error?.message || err.error || res.statusText}`);
     }
     const data = await res.json();
+    return this._decryptMessages(data.messages);
+  }
+  /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+  async _decryptMessages(rawMessages) {
     const decrypted = [];
-    for (const msg of data.messages) {
+    for (const msg of rawMessages) {
       try {
         if (this._seenMessageIds.has(msg.id)) continue;
         let senderEncPub;
@@ -4572,7 +4766,6 @@ var VoidlyAgent = class _VoidlyAgent {
         let envelopePqCiphertext = null;
         let envelopeDhRatchetKey = null;
         let envelopePn = 0;
-        let envelopeDeniable = false;
         if (msg.envelope) {
           try {
             const env = JSON.parse(msg.envelope);
@@ -4605,7 +4798,7 @@ var VoidlyAgent = class _VoidlyAgent {
                 const combined = new Uint8Array(x25519Shared.length + pqShared.length);
                 combined.set(x25519Shared, 0);
                 combined.set(pqShared, x25519Shared.length);
-                initialKey = new Uint8Array(await crypto.subtle.digest("SHA-256", combined));
+                initialKey = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", combined));
               } catch {
                 initialKey = x25519Shared;
               }
@@ -4802,6 +4995,10 @@ var VoidlyAgent = class _VoidlyAgent {
         this._decryptFailCount++;
       }
     }
+    if (decrypted.length > 0) {
+      this._persistRatchetState().catch(() => {
+      });
+    }
     return decrypted;
   }
   // ─── Message Management ─────────────────────────────────────────────────────
@@ -6090,6 +6287,114 @@ var VoidlyAgent = class _VoidlyAgent {
       this.ping().catch(() => {
       });
     }
+    const deliverMessages = async (messages) => {
+      for (const msg of messages) {
+        try {
+          await onMessage(msg);
+          if (autoMarkRead) {
+            await this.markRead(msg.id).catch(() => {
+            });
+          }
+        } catch (err) {
+          if (onError) onError(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+      if (messages.length > 0) {
+        lastSeen = messages[messages.length - 1].timestamp;
+      }
+    };
+    let lastEventId = "";
+    let sseFailures = 0;
+    const startSSE = async () => {
+      try {
+        const params = new URLSearchParams();
+        if (lastSeen) params.set("since", lastSeen);
+        if (options.from) params.set("from", options.from);
+        const sseUrl = `${this.baseUrl}/v1/agent/receive/sse?${params}`;
+        const headers = { "X-Agent-Key": this.apiKey };
+        if (lastEventId) headers["Last-Event-ID"] = lastEventId;
+        const controller = new AbortController();
+        const sseTimeout = setTimeout(() => controller.abort(), 6e4);
+        let res;
+        try {
+          res = await fetch(sseUrl, { headers, signal: controller.signal });
+        } catch (e) {
+          clearTimeout(sseTimeout);
+          throw e;
+        }
+        if (!res.ok || !res.body) {
+          clearTimeout(sseTimeout);
+          return false;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+          while (active && !options.signal?.aborted) {
+            const { done: streamDone, value } = await reader.read();
+            if (streamDone) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || "";
+            let eventType = "";
+            let dataStr = "";
+            let eventId = "";
+            for (const line of lines) {
+              if (line.startsWith("event: ")) {
+                eventType = line.slice(7).trim();
+              } else if (line.startsWith("data: ")) {
+                dataStr += (dataStr ? "\n" : "") + line.slice(6);
+              } else if (line.startsWith("id: ")) {
+                eventId = line.slice(4).trim();
+              } else if (line === "" && (dataStr || eventType)) {
+                if (eventId) lastEventId = eventId;
+                if (eventType === "message" && dataStr) {
+                  try {
+                    const rawMsg = JSON.parse(dataStr);
+                    const decrypted = await this._decryptMessages([rawMsg]);
+                    if (decrypted.length > 0) {
+                      consecutiveEmpty = 0;
+                      sseFailures = 0;
+                      await deliverMessages(decrypted);
+                    }
+                  } catch {
+                  }
+                } else if (eventType === "reconnect") {
+                  break;
+                }
+                eventType = "";
+                dataStr = "";
+                eventId = "";
+              }
+            }
+          }
+        } finally {
+          reader.releaseLock();
+          clearTimeout(sseTimeout);
+        }
+        sseFailures = 0;
+        return true;
+      } catch {
+        sseFailures++;
+        return false;
+      }
+    };
+    const sseLoop = async () => {
+      while (active && !options.signal?.aborted) {
+        const ok = await startSSE();
+        if (!active || options.signal?.aborted) break;
+        if (!ok) {
+          if (sseFailures >= 3) {
+            poll();
+            return;
+          }
+          const backoff = Math.min(1e3 * Math.pow(2, sseFailures - 1), 4e3);
+          await new Promise((r) => setTimeout(r, backoff));
+          continue;
+        }
+        await new Promise((r) => setTimeout(r, 500));
+      }
+    };
     const useLongPoll = this.longPoll;
     const poll = async () => {
       if (!active || options.signal?.aborted) {
@@ -6097,62 +6402,18 @@ var VoidlyAgent = class _VoidlyAgent {
         return;
       }
       try {
-        let messages;
-        if (useLongPoll) {
-          const params = new URLSearchParams({ timeout: "25" });
-          if (lastSeen) params.set("since", lastSeen);
-          if (options.from) params.set("from", options.from);
-          const res = await this._timedFetch(`${this.baseUrl}/v1/agent/receive/poll?${params}`, {
-            headers: { "X-Agent-Key": this.apiKey }
-          });
-          if (res.ok) {
-            const data = await res.json();
-            messages = [];
-            for (const raw of data.messages) {
-              try {
-                if (this._seenMessageIds.has(raw.id)) continue;
-                this._seenMessageIds.add(raw.id);
-              } catch {
-              }
-            }
-            if (data.messages.length > 0) {
-              messages = await this.receive({
-                since: lastSeen,
-                from: options.from,
-                threadId: options.threadId,
-                messageType: options.messageType,
-                unreadOnly,
-                limit: 50
-              });
-            }
-          } else {
-            messages = [];
-          }
-        } else {
-          messages = await this.receive({
-            since: lastSeen,
-            from: options.from,
-            threadId: options.threadId,
-            messageType: options.messageType,
-            unreadOnly,
-            limit: 50
-          });
-        }
+        const messages = await this.receive({
+          since: lastSeen,
+          from: options.from,
+          threadId: options.threadId,
+          messageType: options.messageType,
+          unreadOnly,
+          limit: 50
+        });
         if (messages.length > 0) {
           consecutiveEmpty = 0;
           if (adaptive) currentInterval = Math.max(interval / 2, 500);
-          for (const msg of messages) {
-            try {
-              await onMessage(msg);
-              if (autoMarkRead) {
-                await this.markRead(msg.id).catch(() => {
-                });
-              }
-            } catch (err) {
-              if (onError) onError(err instanceof Error ? err : new Error(String(err)));
-            }
-          }
-          lastSeen = messages[messages.length - 1].timestamp;
+          await deliverMessages(messages);
         } else {
           consecutiveEmpty++;
           if (adaptive && consecutiveEmpty > 3 && !useLongPoll) {
@@ -6167,7 +6428,12 @@ var VoidlyAgent = class _VoidlyAgent {
         timer = setTimeout(poll, useLongPoll ? 100 : currentInterval);
       }
     };
-    poll();
+    const prefs = this._transportPrefs;
+    if (prefs.includes("sse")) {
+      sseLoop();
+    } else {
+      poll();
+    }
     return handle;
   }
   /**
@@ -6499,7 +6765,12 @@ var VoidlyAgent = class _VoidlyAgent {
     for (const relay of relays) {
       try {
         const res = await this._timedFetch(`${relay}${path}`, init);
-        if (res.ok || res.status >= 400 && res.status < 500) return res;
+        if (res.ok || res.status >= 400 && res.status < 500 && res.status !== 429) return res;
+        if (res.status === 429) {
+          const retryAfter = res.headers.get("Retry-After");
+          const waitMs = retryAfter ? Math.min(parseInt(retryAfter, 10) * 1e3, 5e3) : 1e3;
+          await new Promise((r) => setTimeout(r, waitMs));
+        }
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err));
       }
@@ -6686,7 +6957,9 @@ var VoidlyAgent = class _VoidlyAgent {
         ...this.requireSignatures ? ["Strict signature enforcement (reject unsigned/invalid messages)"] : [],
         ...this.fallbackRelays.length > 0 ? [`Multi-relay fallback (${this.fallbackRelays.length} backup relays \u2014 receive, discover, identity all use fallbacks)`] : [],
         ...this.jitterMs > 0 ? [`Timing jitter (random ${this.jitterMs}ms delay \u2014 metadata timing protection)`] : [],
+        ...this._transportPrefs.includes("sse") ? ["SSE streaming transport (real-time push delivery from relay)"] : [],
         ...this.longPoll ? ["Long-poll transport (25s server-held connection \u2014 near-real-time delivery)"] : [],
+        ...this._persistMode !== "memory" ? [`Ratchet state auto-persistence (${this._persistMode} backend \u2014 survives process restart)`] : [],
         ...this._coverTrafficTimer !== null ? ["Cover traffic (encrypted noise at random intervals \u2014 traffic analysis resistance)"] : [],
         "Agent RPC (invoke/onInvoke \u2014 synchronous function calls between agents)",
         "P2P direct send (bypass relay via webhook \u2014 true peer-to-peer when possible)",
@@ -6700,7 +6973,7 @@ var VoidlyAgent = class _VoidlyAgent {
         ...this.sealedSender ? ["Relay sees to_did (needed for routing) but NOT from_did, thread_id, or message_type"] : ["Relay sees from_did, to_did, thread_id, message_type in cleartext \u2014 enable sealedSender to strip metadata"],
         "Relay sees channel membership, task delegation, trust scores (social graph)",
         ...this.fallbackRelays.length === 0 ? ["Single relay with no fallbacks \u2014 configure fallbackRelays for resilience"] : [],
-        "Ratchet state is in-memory (lost on process restart \u2014 export credentials to persist)",
+        ...this._persistMode === "memory" ? ["Ratchet state is in-memory (lost on process restart \u2014 use persist option or exportCredentials)"] : [],
         ...!this.deniable ? ["Ed25519 signatures are non-repudiable \u2014 enable deniable option for HMAC auth"] : [],
         ...!this.doubleRatchet ? ["Hash ratchet only \u2014 enable doubleRatchet option for post-compromise recovery"] : [],
         ...this.jitterMs === 0 ? ["No timing jitter \u2014 enable jitterMs option for metadata protection"] : [],

package/dist/index.mjs

@@ -2230,22 +2230,22 @@ var require_nacl_fast = __commonJS({
         randombytes = fn;
       };
       (function() {
-        var crypto2 = typeof self !== "undefined" ? self.crypto || self.msCrypto : null;
-        if (crypto2 && crypto2.getRandomValues) {
+        var crypto = typeof self !== "undefined" ? self.crypto || self.msCrypto : null;
+        if (crypto && crypto.getRandomValues) {
           var QUOTA = 65536;
           nacl2.setPRNG(function(x, n) {
             var i, v = new Uint8Array(n);
             for (i = 0; i < n; i += QUOTA) {
-              crypto2.getRandomValues(v.subarray(i, i + Math.min(n - i, QUOTA)));
+              crypto.getRandomValues(v.subarray(i, i + Math.min(n - i, QUOTA)));
             }
             for (i = 0; i < n; i++) x[i] = v[i];
             cleanup(v);
           });
         } else if (typeof __require !== "undefined") {
-          crypto2 = __require("crypto");
-          if (crypto2 && crypto2.randomBytes) {
+          crypto = __require("crypto");
+          if (crypto && crypto.randomBytes) {
             nacl2.setPRNG(function(x, n) {
-              var i, v = crypto2.randomBytes(n);
+              var i, v = crypto.randomBytes(n);
               for (i = 0; i < n; i++) x[i] = v[i];
               cleanup(v);
             });
@@ -4080,6 +4080,9 @@ var VoidlyAgent = class _VoidlyAgent {
     this._coverTrafficTimer = null;
     // RPC listener handle (started on first onInvoke)
     this._rpcListener = null;
+    // Persistence (v3.2)
+    this._persistMode = "memory";
+    this._persistKey = null;
     this.did = identity.did;
     this.apiKey = identity.apiKey;
     this.signingKeyPair = identity.signingKeyPair;
@@ -4099,6 +4102,11 @@ var VoidlyAgent = class _VoidlyAgent {
     this.longPoll = config?.longPoll !== false;
     this.mlkemPublicKey = identity.mlkemPublicKey || null;
     this.mlkemSecretKey = identity.mlkemSecretKey || null;
+    this._persistMode = config?.persist || "memory";
+    this._onPersist = config?.onPersist;
+    this._onLoad = config?.onLoad;
+    this._persistPath = config?.persistPath;
+    this._transportPrefs = config?.transport || ["sse", "long-poll"];
   }
   // ─── Factory Methods ────────────────────────────────────────────────────────
   /**
@@ -4303,6 +4311,186 @@ var VoidlyAgent = class _VoidlyAgent {
       } : {}
     };
   }
+  // ─── Ratchet Persistence (v3.2) ────────────────────────────────────────────
+  /** Derive persistence encryption key from signing secret */
+  _derivePersistKey() {
+    if (this._persistKey) return this._persistKey;
+    const salt = (0, import_tweetnacl_util.decodeUTF8)("voidly-persist-v1");
+    const input = new Uint8Array(this.signingKeyPair.secretKey.length + salt.length);
+    input.set(this.signingKeyPair.secretKey, 0);
+    input.set(salt, this.signingKeyPair.secretKey.length);
+    this._persistKey = import_tweetnacl.default.hash(input).slice(0, 32);
+    return this._persistKey;
+  }
+  /** Auto-persist ratchet state (called after every ratchet mutation) */
+  async _persistRatchetState() {
+    if (this._persistMode === "memory") return;
+    try {
+      const creds = this.exportCredentials();
+      const data = JSON.stringify(creds.ratchetStates || {});
+      const key = this._derivePersistKey();
+      const nonce = import_tweetnacl.default.randomBytes(24);
+      const encrypted = import_tweetnacl.default.secretbox((0, import_tweetnacl_util.decodeUTF8)(data), nonce, key);
+      const blob = JSON.stringify({ n: (0, import_tweetnacl_util.encodeBase64)(nonce), c: (0, import_tweetnacl_util.encodeBase64)(encrypted), v: 1 });
+      switch (this._persistMode) {
+        case "localStorage":
+          if (typeof localStorage !== "undefined") {
+            localStorage.setItem(`voidly-ratchet-${this.did}`, blob);
+          }
+          break;
+        case "indexedDB":
+          await this._idbPut(blob);
+          break;
+        case "file":
+          if (this._persistPath) {
+            const fs = await import("fs/promises");
+            await fs.writeFile(this._persistPath, blob, "utf-8");
+          }
+          break;
+        case "relay":
+          await this._timedFetch(`${this.baseUrl}/v1/agent/memory/ratchet/state`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json", "X-Agent-Key": this.apiKey },
+            body: JSON.stringify({ value: blob })
+          }).catch(() => {
+          });
+          break;
+        case "custom":
+          if (this._onPersist) await this._onPersist(blob);
+          break;
+      }
+    } catch {
+    }
+  }
+  /** Load persisted ratchet state and restore into memory */
+  async _loadPersistedRatchetState() {
+    if (this._persistMode === "memory") return;
+    let blob = null;
+    try {
+      switch (this._persistMode) {
+        case "localStorage":
+          if (typeof localStorage !== "undefined") {
+            blob = localStorage.getItem(`voidly-ratchet-${this.did}`);
+          }
+          break;
+        case "indexedDB":
+          blob = await this._idbGet();
+          break;
+        case "file":
+          if (this._persistPath) {
+            try {
+              const fs = await import("fs/promises");
+              blob = await fs.readFile(this._persistPath, "utf-8");
+            } catch {
+            }
+          }
+          break;
+        case "relay":
+          try {
+            const res = await this._timedFetch(`${this.baseUrl}/v1/agent/memory/ratchet/state`, {
+              headers: { "X-Agent-Key": this.apiKey }
+            });
+            if (res.ok) {
+              const data = await res.json();
+              blob = data.value;
+            }
+          } catch {
+          }
+          break;
+        case "custom":
+          if (this._onLoad) blob = await this._onLoad();
+          break;
+      }
+    } catch {
+      return;
+    }
+    if (!blob) return;
+    try {
+      const { n, c } = JSON.parse(blob);
+      const key = this._derivePersistKey();
+      const decrypted = import_tweetnacl.default.secretbox.open((0, import_tweetnacl_util.decodeBase64)(c), (0, import_tweetnacl_util.decodeBase64)(n), key);
+      if (!decrypted) return;
+      const states = JSON.parse((0, import_tweetnacl_util.encodeUTF8)(decrypted));
+      for (const [pairId, rs] of Object.entries(states)) {
+        if (this._ratchetStates.has(pairId)) continue;
+        const state = {
+          sendChainKey: (0, import_tweetnacl_util.decodeBase64)(rs.sendChainKey),
+          sendStep: rs.sendStep,
+          recvChainKey: (0, import_tweetnacl_util.decodeBase64)(rs.recvChainKey),
+          recvStep: rs.recvStep,
+          skippedKeys: /* @__PURE__ */ new Map()
+        };
+        if (rs.rootKey) state.rootKey = (0, import_tweetnacl_util.decodeBase64)(rs.rootKey);
+        if (rs.dhSendSecretKey && rs.dhSendPublicKey) {
+          state.dhSendKeyPair = {
+            secretKey: (0, import_tweetnacl_util.decodeBase64)(rs.dhSendSecretKey),
+            publicKey: (0, import_tweetnacl_util.decodeBase64)(rs.dhSendPublicKey)
+          };
+        }
+        if (rs.dhRecvPubKey) state.dhRecvPubKey = (0, import_tweetnacl_util.decodeBase64)(rs.dhRecvPubKey);
+        if (rs.prevSendStep !== void 0) state.prevSendStep = rs.prevSendStep;
+        if (state.sendChainKey.length === 32 && state.recvChainKey.length === 32) {
+          this._ratchetStates.set(pairId, state);
+        }
+      }
+    } catch {
+    }
+  }
+  /** IndexedDB put helper (browser only) */
+  async _idbPut(blob) {
+    if (typeof indexedDB === "undefined") return;
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open("voidly-agent", 1);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains("ratchet")) db.createObjectStore("ratchet");
+      };
+      req.onsuccess = () => {
+        const tx = req.result.transaction("ratchet", "readwrite");
+        tx.objectStore("ratchet").put(blob, this.did);
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+  /** IndexedDB get helper (browser only) */
+  async _idbGet() {
+    if (typeof indexedDB === "undefined") return null;
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open("voidly-agent", 1);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains("ratchet")) db.createObjectStore("ratchet");
+      };
+      req.onsuccess = () => {
+        const tx = req.result.transaction("ratchet", "readonly");
+        const getReq = tx.objectStore("ratchet").get(this.did);
+        getReq.onsuccess = () => resolve(getReq.result || null);
+        getReq.onerror = () => reject(getReq.error);
+      };
+      req.onerror = () => reject(req.error);
+    });
+  }
+  /**
+   * Force-persist current ratchet state.
+   * Useful to call before process exit to ensure state is saved.
+   */
+  async flushRatchetState() {
+    const origMode = this._persistMode;
+    if (origMode === "memory") this._persistMode = "file";
+    await this._persistRatchetState();
+    this._persistMode = origMode;
+  }
+  /**
+   * Restore an agent from credentials with async persistence loading.
+   * Use this instead of `fromCredentials()` when using file/relay/custom persistence.
+   */
+  static async fromCredentialsAsync(creds, config) {
+    const agent = _VoidlyAgent.fromCredentials(creds, config);
+    await agent._loadPersistedRatchetState();
+    return agent;
+  }
   /**
    * Get the number of messages that failed to decrypt.
    * Useful for detecting key mismatches, attacks, or corruption.
@@ -4379,7 +4567,7 @@ var VoidlyAgent = class _VoidlyAgent {
           const combined = new Uint8Array(x25519Shared.length + pqShared.length);
           combined.set(x25519Shared, 0);
           combined.set(pqShared, x25519Shared.length);
-          initialKey = new Uint8Array(await crypto.subtle.digest("SHA-256", combined));
+          initialKey = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", combined));
         } catch {
           initialKey = x25519Shared;
         }
@@ -4478,6 +4666,8 @@ var VoidlyAgent = class _VoidlyAgent {
       payload.thread_id = options.threadId;
       payload.reply_to = options.replyTo;
     }
+    this._persistRatchetState().catch(() => {
+    });
     const relays = [this.baseUrl, ...this.fallbackRelays];
     let lastError = null;
     for (const relay of relays) {
@@ -4536,8 +4726,12 @@ var VoidlyAgent = class _VoidlyAgent {
       throw new Error(`Receive failed: ${err.error?.message || err.error || res.statusText}`);
     }
     const data = await res.json();
+    return this._decryptMessages(data.messages);
+  }
+  /** Decrypt raw message objects (shared by receive(), SSE, WebSocket transports) */
+  async _decryptMessages(rawMessages) {
     const decrypted = [];
-    for (const msg of data.messages) {
+    for (const msg of rawMessages) {
       try {
         if (this._seenMessageIds.has(msg.id)) continue;
         let senderEncPub;
@@ -4561,7 +4755,6 @@ var VoidlyAgent = class _VoidlyAgent {
         let envelopePqCiphertext = null;
         let envelopeDhRatchetKey = null;
         let envelopePn = 0;
-        let envelopeDeniable = false;
         if (msg.envelope) {
           try {
             const env = JSON.parse(msg.envelope);
@@ -4594,7 +4787,7 @@ var VoidlyAgent = class _VoidlyAgent {
                 const combined = new Uint8Array(x25519Shared.length + pqShared.length);
                 combined.set(x25519Shared, 0);
                 combined.set(pqShared, x25519Shared.length);
-                initialKey = new Uint8Array(await crypto.subtle.digest("SHA-256", combined));
+                initialKey = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", combined));
               } catch {
                 initialKey = x25519Shared;
               }
@@ -4791,6 +4984,10 @@ var VoidlyAgent = class _VoidlyAgent {
         this._decryptFailCount++;
       }
     }
+    if (decrypted.length > 0) {
+      this._persistRatchetState().catch(() => {
+      });
+    }
     return decrypted;
   }
   // ─── Message Management ─────────────────────────────────────────────────────
@@ -6079,6 +6276,114 @@ var VoidlyAgent = class _VoidlyAgent {
       this.ping().catch(() => {
       });
     }
+    const deliverMessages = async (messages) => {
+      for (const msg of messages) {
+        try {
+          await onMessage(msg);
+          if (autoMarkRead) {
+            await this.markRead(msg.id).catch(() => {
+            });
+          }
+        } catch (err) {
+          if (onError) onError(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+      if (messages.length > 0) {
+        lastSeen = messages[messages.length - 1].timestamp;
+      }
+    };
+    let lastEventId = "";
+    let sseFailures = 0;
+    const startSSE = async () => {
+      try {
+        const params = new URLSearchParams();
+        if (lastSeen) params.set("since", lastSeen);
+        if (options.from) params.set("from", options.from);
+        const sseUrl = `${this.baseUrl}/v1/agent/receive/sse?${params}`;
+        const headers = { "X-Agent-Key": this.apiKey };
+        if (lastEventId) headers["Last-Event-ID"] = lastEventId;
+        const controller = new AbortController();
+        const sseTimeout = setTimeout(() => controller.abort(), 6e4);
+        let res;
+        try {
+          res = await fetch(sseUrl, { headers, signal: controller.signal });
+        } catch (e) {
+          clearTimeout(sseTimeout);
+          throw e;
+        }
+        if (!res.ok || !res.body) {
+          clearTimeout(sseTimeout);
+          return false;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+          while (active && !options.signal?.aborted) {
+            const { done: streamDone, value } = await reader.read();
+            if (streamDone) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || "";
+            let eventType = "";
+            let dataStr = "";
+            let eventId = "";
+            for (const line of lines) {
+              if (line.startsWith("event: ")) {
+                eventType = line.slice(7).trim();
+              } else if (line.startsWith("data: ")) {
+                dataStr += (dataStr ? "\n" : "") + line.slice(6);
+              } else if (line.startsWith("id: ")) {
+                eventId = line.slice(4).trim();
+              } else if (line === "" && (dataStr || eventType)) {
+                if (eventId) lastEventId = eventId;
+                if (eventType === "message" && dataStr) {
+                  try {
+                    const rawMsg = JSON.parse(dataStr);
+                    const decrypted = await this._decryptMessages([rawMsg]);
+                    if (decrypted.length > 0) {
+                      consecutiveEmpty = 0;
+                      sseFailures = 0;
+                      await deliverMessages(decrypted);
+                    }
+                  } catch {
+                  }
+                } else if (eventType === "reconnect") {
+                  break;
+                }
+                eventType = "";
+                dataStr = "";
+                eventId = "";
+              }
+            }
+          }
+        } finally {
+          reader.releaseLock();
+          clearTimeout(sseTimeout);
+        }
+        sseFailures = 0;
+        return true;
+      } catch {
+        sseFailures++;
+        return false;
+      }
+    };
+    const sseLoop = async () => {
+      while (active && !options.signal?.aborted) {
+        const ok = await startSSE();
+        if (!active || options.signal?.aborted) break;
+        if (!ok) {
+          if (sseFailures >= 3) {
+            poll();
+            return;
+          }
+          const backoff = Math.min(1e3 * Math.pow(2, sseFailures - 1), 4e3);
+          await new Promise((r) => setTimeout(r, backoff));
+          continue;
+        }
+        await new Promise((r) => setTimeout(r, 500));
+      }
+    };
     const useLongPoll = this.longPoll;
     const poll = async () => {
       if (!active || options.signal?.aborted) {
@@ -6086,62 +6391,18 @@ var VoidlyAgent = class _VoidlyAgent {
         return;
       }
       try {
-        let messages;
-        if (useLongPoll) {
-          const params = new URLSearchParams({ timeout: "25" });
-          if (lastSeen) params.set("since", lastSeen);
-          if (options.from) params.set("from", options.from);
-          const res = await this._timedFetch(`${this.baseUrl}/v1/agent/receive/poll?${params}`, {
-            headers: { "X-Agent-Key": this.apiKey }
-          });
-          if (res.ok) {
-            const data = await res.json();
-            messages = [];
-            for (const raw of data.messages) {
-              try {
-                if (this._seenMessageIds.has(raw.id)) continue;
-                this._seenMessageIds.add(raw.id);
-              } catch {
-              }
-            }
-            if (data.messages.length > 0) {
-              messages = await this.receive({
-                since: lastSeen,
-                from: options.from,
-                threadId: options.threadId,
-                messageType: options.messageType,
-                unreadOnly,
-                limit: 50
-              });
-            }
-          } else {
-            messages = [];
-          }
-        } else {
-          messages = await this.receive({
-            since: lastSeen,
-            from: options.from,
-            threadId: options.threadId,
-            messageType: options.messageType,
-            unreadOnly,
-            limit: 50
-          });
-        }
+        const messages = await this.receive({
+          since: lastSeen,
+          from: options.from,
+          threadId: options.threadId,
+          messageType: options.messageType,
+          unreadOnly,
+          limit: 50
+        });
         if (messages.length > 0) {
           consecutiveEmpty = 0;
           if (adaptive) currentInterval = Math.max(interval / 2, 500);
-          for (const msg of messages) {
-            try {
-              await onMessage(msg);
-              if (autoMarkRead) {
-                await this.markRead(msg.id).catch(() => {
-                });
-              }
-            } catch (err) {
-              if (onError) onError(err instanceof Error ? err : new Error(String(err)));
-            }
-          }
-          lastSeen = messages[messages.length - 1].timestamp;
+          await deliverMessages(messages);
         } else {
           consecutiveEmpty++;
           if (adaptive && consecutiveEmpty > 3 && !useLongPoll) {
@@ -6156,7 +6417,12 @@ var VoidlyAgent = class _VoidlyAgent {
         timer = setTimeout(poll, useLongPoll ? 100 : currentInterval);
       }
     };
-    poll();
+    const prefs = this._transportPrefs;
+    if (prefs.includes("sse")) {
+      sseLoop();
+    } else {
+      poll();
+    }
     return handle;
   }
   /**
@@ -6488,7 +6754,12 @@ var VoidlyAgent = class _VoidlyAgent {
     for (const relay of relays) {
       try {
         const res = await this._timedFetch(`${relay}${path}`, init);
-        if (res.ok || res.status >= 400 && res.status < 500) return res;
+        if (res.ok || res.status >= 400 && res.status < 500 && res.status !== 429) return res;
+        if (res.status === 429) {
+          const retryAfter = res.headers.get("Retry-After");
+          const waitMs = retryAfter ? Math.min(parseInt(retryAfter, 10) * 1e3, 5e3) : 1e3;
+          await new Promise((r) => setTimeout(r, waitMs));
+        }
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err));
       }
@@ -6675,7 +6946,9 @@ var VoidlyAgent = class _VoidlyAgent {
         ...this.requireSignatures ? ["Strict signature enforcement (reject unsigned/invalid messages)"] : [],
         ...this.fallbackRelays.length > 0 ? [`Multi-relay fallback (${this.fallbackRelays.length} backup relays \u2014 receive, discover, identity all use fallbacks)`] : [],
         ...this.jitterMs > 0 ? [`Timing jitter (random ${this.jitterMs}ms delay \u2014 metadata timing protection)`] : [],
+        ...this._transportPrefs.includes("sse") ? ["SSE streaming transport (real-time push delivery from relay)"] : [],
         ...this.longPoll ? ["Long-poll transport (25s server-held connection \u2014 near-real-time delivery)"] : [],
+        ...this._persistMode !== "memory" ? [`Ratchet state auto-persistence (${this._persistMode} backend \u2014 survives process restart)`] : [],
         ...this._coverTrafficTimer !== null ? ["Cover traffic (encrypted noise at random intervals \u2014 traffic analysis resistance)"] : [],
         "Agent RPC (invoke/onInvoke \u2014 synchronous function calls between agents)",
         "P2P direct send (bypass relay via webhook \u2014 true peer-to-peer when possible)",
@@ -6689,7 +6962,7 @@ var VoidlyAgent = class _VoidlyAgent {
         ...this.sealedSender ? ["Relay sees to_did (needed for routing) but NOT from_did, thread_id, or message_type"] : ["Relay sees from_did, to_did, thread_id, message_type in cleartext \u2014 enable sealedSender to strip metadata"],
         "Relay sees channel membership, task delegation, trust scores (social graph)",
         ...this.fallbackRelays.length === 0 ? ["Single relay with no fallbacks \u2014 configure fallbackRelays for resilience"] : [],
-        "Ratchet state is in-memory (lost on process restart \u2014 export credentials to persist)",
+        ...this._persistMode === "memory" ? ["Ratchet state is in-memory (lost on process restart \u2014 use persist option or exportCredentials)"] : [],
         ...!this.deniable ? ["Ed25519 signatures are non-repudiable \u2014 enable deniable option for HMAC auth"] : [],
         ...!this.doubleRatchet ? ["Hash ratchet only \u2014 enable doubleRatchet option for post-compromise recovery"] : [],
         ...this.jitterMs === 0 ? ["No timing jitter \u2014 enable jitterMs option for metadata protection"] : [],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@voidly/agent-sdk",
-  "version": "3.1.0",
-  "description": "E2E encrypted agent-to-agent communication SDK — Double Ratchet, X3DH, deniable auth, ML-KEM-768 post-quantum, metadata privacy, RPC, P2P direct, cover traffic",
+  "version": "3.2.1",
+  "description": "E2E encrypted agent-to-agent communication SDK — Double Ratchet, X3DH, deniable auth, ML-KEM-768 post-quantum, SSE streaming, ratchet persistence, multi-relay federation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",