@voidly/agent-sdk 3.0.0 → 3.2.0

package/dist/index.mjs

@@ -3972,19 +3972,29 @@ async function ratchetStep(chainKey) {
   );
   return { nextChainKey, messageKey };
 }
-function sealEnvelope(senderDid, plaintext) {
-  return JSON.stringify({
-    v: 2,
+function sealEnvelope(senderDid, plaintext, meta) {
+  const obj = {
+    v: 3,
     from: senderDid,
     msg: plaintext,
     ts: (/* @__PURE__ */ new Date()).toISOString()
-  });
+  };
+  if (meta?.contentType && meta.contentType !== "text/plain") obj.ct = meta.contentType;
+  if (meta?.messageType && meta.messageType !== "text") obj.mt = meta.messageType;
+  if (meta?.threadId) obj.tid = meta.threadId;
+  if (meta?.replyTo) obj.rto = meta.replyTo;
+  return JSON.stringify(obj);
 }
 function unsealEnvelope(plaintext) {
   try {
     const parsed = JSON.parse(plaintext);
-    if (parsed.v === 2 && parsed.from && parsed.msg) {
-      return { from: parsed.from, msg: parsed.msg, ts: parsed.ts };
+    if ((parsed.v === 2 || parsed.v === 3) && parsed.from && parsed.msg) {
+      const result = { from: parsed.from, msg: parsed.msg, ts: parsed.ts };
+      if (parsed.ct) result.contentType = parsed.ct;
+      if (parsed.mt) result.messageType = parsed.mt;
+      if (parsed.tid) result.threadId = parsed.tid;
+      if (parsed.rto) result.replyTo = parsed.rto;
+      return result;
     }
     return null;
   } catch {
@@ -4062,6 +4072,17 @@ var VoidlyAgent = class _VoidlyAgent {
     this._identityCache = /* @__PURE__ */ new Map();
     this._seenMessageIds = /* @__PURE__ */ new Set();
     this._decryptFailCount = 0;
+    // RPC handlers: method → handler function
+    this._rpcHandlers = /* @__PURE__ */ new Map();
+    // RPC pending responses: rpc_id → { resolve, reject, timer }
+    this._rpcPending = /* @__PURE__ */ new Map();
+    // Cover traffic state
+    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;
@@ -4081,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 ────────────────────────────────────────────────────────
   /**
@@ -4285,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.
@@ -4332,7 +4538,12 @@ var VoidlyAgent = class _VoidlyAgent {
     const recipientPubKey = (0, import_tweetnacl_util.decodeBase64)(profile.encryption_public_key);
     let plaintext = message;
     if (useSealed) {
-      plaintext = sealEnvelope(this.did, message);
+      plaintext = sealEnvelope(this.did, message, {
+        contentType: options.contentType,
+        messageType: options.messageType,
+        threadId: options.threadId,
+        replyTo: options.replyTo
+      });
     }
     let contentBytes;
     if (usePadding) {
@@ -4447,12 +4658,16 @@ var VoidlyAgent = class _VoidlyAgent {
       nonce: (0, import_tweetnacl_util.encodeBase64)(nonce),
       signature: (0, import_tweetnacl_util.encodeBase64)(signature),
       envelope: envelopeData,
-      content_type: options.contentType || "text/plain",
-      message_type: options.messageType || "text",
-      thread_id: options.threadId,
-      reply_to: options.replyTo,
       ttl: options.ttl
     };
+    if (!useSealed) {
+      payload.content_type = options.contentType || "text/plain";
+      payload.message_type = options.messageType || "text";
+      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) {
@@ -4503,7 +4718,7 @@ var VoidlyAgent = class _VoidlyAgent {
     if (options.contentType) params.set("content_type", options.contentType);
     if (options.messageType) params.set("message_type", options.messageType);
     if (options.unreadOnly) params.set("unread", "true");
-    const res = await this._timedFetch(`${this.baseUrl}/v1/agent/receive/raw?${params}`, {
+    const res = await this._resilientFetch(`/v1/agent/receive/raw?${params}`, {
       headers: { "X-Agent-Key": this.apiKey }
     });
     if (!res.ok) {
@@ -4511,11 +4726,28 @@ 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;
-        const senderEncPub = (0, import_tweetnacl_util.decodeBase64)(msg.sender_encryption_key);
+        let senderEncPub;
+        let senderSignPubBytes = null;
+        if (msg.sender_encryption_key) {
+          senderEncPub = (0, import_tweetnacl_util.decodeBase64)(msg.sender_encryption_key);
+          if (msg.sender_signing_key) senderSignPubBytes = (0, import_tweetnacl_util.decodeBase64)(msg.sender_signing_key);
+        } else if (msg.envelope) {
+          const env = JSON.parse(msg.envelope);
+          const senderProfile = await this.getIdentity(env.from);
+          if (!senderProfile) continue;
+          senderEncPub = (0, import_tweetnacl_util.decodeBase64)(senderProfile.encryption_public_key);
+          if (senderProfile.signing_public_key) senderSignPubBytes = (0, import_tweetnacl_util.decodeBase64)(senderProfile.signing_public_key);
+        } else {
+          continue;
+        }
         const ciphertext = (0, import_tweetnacl_util.decodeBase64)(msg.ciphertext);
         const nonce = (0, import_tweetnacl_util.decodeBase64)(msg.nonce);
         let rawPlaintext = null;
@@ -4523,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);
@@ -4683,11 +4914,19 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         let content = (0, import_tweetnacl_util.encodeUTF8)(plaintextBytes);
         let senderDid = msg.from;
+        let innerContentType;
+        let innerMessageType;
+        let innerThreadId;
+        let innerReplyTo;
         if (wasSealed || !proto) {
           const unsealed = unsealEnvelope(content);
           if (unsealed) {
             content = unsealed.msg;
             senderDid = unsealed.from;
+            innerContentType = unsealed.contentType;
+            innerMessageType = unsealed.messageType;
+            innerThreadId = unsealed.threadId;
+            innerReplyTo = unsealed.replyTo;
           }
         }
         let signatureValid = false;
@@ -4708,12 +4947,11 @@ var VoidlyAgent = class _VoidlyAgent {
               for (let i = 0; i < expectedHmac.length; i++) diff |= expectedHmac[i] ^ signatureBytes[i];
               signatureValid = diff === 0;
             }
-          } else {
-            const senderSignPub = (0, import_tweetnacl_util.decodeBase64)(msg.sender_signing_key);
+          } else if (senderSignPubBytes) {
             signatureValid = import_tweetnacl.default.sign.detached.verify(
               (0, import_tweetnacl_util.decodeUTF8)(envelopeStr),
               signatureBytes,
-              senderSignPub
+              senderSignPubBytes
             );
           }
         } catch {
@@ -4733,10 +4971,11 @@ var VoidlyAgent = class _VoidlyAgent {
           from: senderDid,
           to: msg.to,
           content,
-          contentType: msg.content_type,
-          messageType: msg.message_type || "text",
-          threadId: msg.thread_id,
-          replyTo: msg.reply_to,
+          // v3: prefer metadata from inside ciphertext (relay can't see it)
+          contentType: innerContentType || msg.content_type || "text/plain",
+          messageType: innerMessageType || msg.message_type || "text",
+          threadId: innerThreadId || msg.thread_id || null,
+          replyTo: innerReplyTo || msg.reply_to || null,
           signatureValid,
           timestamp: msg.timestamp,
           expiresAt: msg.expires_at
@@ -4745,6 +4984,10 @@ var VoidlyAgent = class _VoidlyAgent {
         this._decryptFailCount++;
       }
     }
+    if (decrypted.length > 0) {
+      this._persistRatchetState().catch(() => {
+      });
+    }
     return decrypted;
   }
   // ─── Message Management ─────────────────────────────────────────────────────
@@ -4797,7 +5040,7 @@ var VoidlyAgent = class _VoidlyAgent {
     if (cached && Date.now() - cached.cachedAt < 3e5) {
       return cached.profile;
     }
-    const res = await this._timedFetch(`${this.baseUrl}/v1/agent/identity/${did}`);
+    const res = await this._resilientFetch(`/v1/agent/identity/${did}`);
     if (!res.ok) return null;
     const profile = await res.json();
     this._identityCache.set(did, { profile, cachedAt: Date.now() });
@@ -4815,7 +5058,7 @@ var VoidlyAgent = class _VoidlyAgent {
     if (options.query) params.set("query", options.query);
     if (options.capability) params.set("capability", options.capability);
     if (options.limit) params.set("limit", String(options.limit));
-    const res = await this._timedFetch(`${this.baseUrl}/v1/agent/discover?${params}`);
+    const res = await this._resilientFetch(`/v1/agent/discover?${params}`);
     if (!res.ok) return [];
     const data = await res.json();
     return data.agents;
@@ -6033,6 +6276,84 @@ 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;
+      }
+    };
+    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 res = await this._timedFetch(sseUrl, {
+          headers: { "X-Agent-Key": this.apiKey }
+        });
+        if (!res.ok || !res.body) return false;
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        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 = "";
+          for (const line of lines) {
+            if (line.startsWith("event: ")) {
+              eventType = line.slice(7).trim();
+            } else if (line.startsWith("data: ")) {
+              dataStr = line.slice(6);
+            } else if (line === "" && dataStr) {
+              if (eventType === "message" && dataStr) {
+                try {
+                  const rawMsg = JSON.parse(dataStr);
+                  const decrypted = await this._decryptMessages([rawMsg]);
+                  if (decrypted.length > 0) {
+                    consecutiveEmpty = 0;
+                    await deliverMessages(decrypted);
+                  }
+                } catch {
+                }
+              } else if (eventType === "reconnect") {
+                break;
+              }
+              eventType = "";
+              dataStr = "";
+            }
+          }
+        }
+        reader.releaseLock();
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    const sseLoop = async () => {
+      while (active && !options.signal?.aborted) {
+        const ok = await startSSE();
+        if (!active || options.signal?.aborted) break;
+        if (!ok) {
+          poll();
+          return;
+        }
+        await new Promise((r) => setTimeout(r, 500));
+      }
+    };
     const useLongPoll = this.longPoll;
     const poll = async () => {
       if (!active || options.signal?.aborted) {
@@ -6040,62 +6361,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) {
@@ -6110,7 +6387,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;
   }
   /**
@@ -6169,6 +6451,285 @@ var VoidlyAgent = class _VoidlyAgent {
       listener.stop();
     }
     this._listeners.clear();
+    if (this._rpcListener) {
+      this._rpcListener.stop();
+      this._rpcListener = null;
+    }
+    for (const [id, pending] of this._rpcPending) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Agent stopped"));
+    }
+    this._rpcPending.clear();
+    this.disableCoverTraffic();
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // AGENT RPC — Synchronous Function Invocation Between Agents
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Invoke a function on a remote agent. Synchronous RPC over encrypted messaging.
+   * The remote agent must have registered a handler via `onInvoke()`.
+   *
+   * @example
+   * ```ts
+   * // Call a translator agent
+   * const result = await agent.invoke('did:voidly:translator', 'translate', {
+   *   text: 'Hello, world!',
+   *   to: 'ja',
+   * });
+   * console.log(result.translation); // こんにちは
+   *
+   * // With timeout
+   * const data = await agent.invoke(peerDid, 'analyze', { url: '...' }, 15000);
+   * ```
+   */
+  async invoke(targetDid, method, params = {}, timeoutMs = 3e4) {
+    const rpcId = `rpc-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+    return new Promise(async (resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._rpcPending.delete(rpcId);
+        reject(new Error(`RPC timeout: ${method}@${targetDid} after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this._rpcPending.set(rpcId, { resolve, reject, timer });
+      try {
+        await this.send(targetDid, JSON.stringify({
+          jsonrpc: "2.0",
+          method,
+          params,
+          id: rpcId
+        }), { messageType: "rpc-request", threadId: rpcId });
+      } catch (err) {
+        clearTimeout(timer);
+        this._rpcPending.delete(rpcId);
+        reject(err);
+      }
+    });
+  }
+  /**
+   * Register a handler for incoming RPC invocations.
+   * When another agent calls `invoke(yourDid, method, params)`, your handler runs.
+   *
+   * @example
+   * ```ts
+   * // Register a translation capability
+   * agent.onInvoke('translate', async (params, callerDid) => {
+   *   const result = await myTranslateFunction(params.text, params.to);
+   *   return { translation: result };
+   * });
+   *
+   * // Register a search capability
+   * agent.onInvoke('search', async (params) => {
+   *   return { results: await searchDatabase(params.query) };
+   * });
+   * ```
+   */
+  onInvoke(method, handler) {
+    this._rpcHandlers.set(method, handler);
+    this._ensureRpcListener();
+  }
+  /**
+   * Remove an RPC handler.
+   */
+  offInvoke(method) {
+    this._rpcHandlers.delete(method);
+    if (this._rpcHandlers.size === 0 && this._rpcListener) {
+      this._rpcListener.stop();
+      this._rpcListener = null;
+    }
+  }
+  /** @internal Start listening for RPC requests and responses */
+  _ensureRpcListener() {
+    if (this._rpcListener) return;
+    this._rpcListener = this.listen(async (msg) => {
+      try {
+        const payload = JSON.parse(msg.content);
+        if (payload.jsonrpc !== "2.0") return;
+        if (payload.id && (payload.result !== void 0 || payload.error)) {
+          const pending = this._rpcPending.get(payload.id);
+          if (pending) {
+            clearTimeout(pending.timer);
+            this._rpcPending.delete(payload.id);
+            if (payload.error) {
+              pending.reject(new Error(payload.error.message || "RPC error"));
+            } else {
+              pending.resolve(payload.result);
+            }
+          }
+          return;
+        }
+        if (payload.method && payload.id) {
+          const handler = this._rpcHandlers.get(payload.method);
+          if (!handler) {
+            await this.send(msg.from, JSON.stringify({
+              jsonrpc: "2.0",
+              id: payload.id,
+              error: { code: -32601, message: `Method not found: ${payload.method}` }
+            }), { messageType: "rpc-response", threadId: payload.id });
+            return;
+          }
+          try {
+            const result = await handler(payload.params || {}, msg.from);
+            await this.send(msg.from, JSON.stringify({
+              jsonrpc: "2.0",
+              id: payload.id,
+              result
+            }), { messageType: "rpc-response", threadId: payload.id });
+          } catch (err) {
+            await this.send(msg.from, JSON.stringify({
+              jsonrpc: "2.0",
+              id: payload.id,
+              error: { code: -32e3, message: err.message || "Handler error" }
+            }), { messageType: "rpc-response", threadId: payload.id });
+          }
+        }
+      } catch {
+      }
+    }, { interval: 500, adaptive: false, heartbeat: false });
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // P2P DIRECT MODE — Bypass Relay When Possible
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Send a message directly to a peer's webhook endpoint, bypassing the relay entirely.
+   * The relay never sees the message — true peer-to-peer encrypted delivery.
+   *
+   * Falls back to relay-based send if direct delivery fails.
+   *
+   * @example
+   * ```ts
+   * // Try direct first, fall back to relay
+   * const result = await agent.sendDirect('did:voidly:peer', 'Hello P2P!');
+   * console.log(result.direct); // true if delivered directly, false if via relay
+   * ```
+   */
+  async sendDirect(recipientDid, message, options = {}) {
+    try {
+      const profile = await this.getIdentity(recipientDid);
+      if (profile) {
+        const webhookRes = await this._timedFetch(
+          `${this.baseUrl}/v1/agent/identity/${recipientDid}`,
+          { headers: { "X-Agent-Key": this.apiKey } }
+        );
+        if (webhookRes.ok) {
+          const data = await webhookRes.json();
+          const webhookUrl = data.webhook_url;
+          if (webhookUrl) {
+            const nonce = import_tweetnacl.default.randomBytes(import_tweetnacl.default.box.nonceLength);
+            const recipientPubKey = (0, import_tweetnacl_util.decodeBase64)(profile.encryption_public_key);
+            const plaintext = (0, import_tweetnacl_util.decodeUTF8)(message);
+            const ciphertext = import_tweetnacl.default.box(plaintext, nonce, recipientPubKey, this.encryptionKeyPair.secretKey);
+            const envelope = JSON.stringify({
+              from: this.did,
+              to: recipientDid,
+              ciphertext: (0, import_tweetnacl_util.encodeBase64)(ciphertext),
+              nonce: (0, import_tweetnacl_util.encodeBase64)(nonce),
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              message_type: options.messageType || "text",
+              thread_id: options.threadId
+            });
+            const signature = import_tweetnacl.default.sign.detached((0, import_tweetnacl_util.decodeUTF8)(envelope), this.signingKeyPair.secretKey);
+            const directRes = await this._timedFetch(webhookUrl, {
+              method: "POST",
+              headers: {
+                "Content-Type": "application/json",
+                "X-Voidly-Signature": `sha256=${(0, import_tweetnacl_util.encodeBase64)(signature)}`,
+                "X-Voidly-Sender": this.did
+              },
+              body: envelope
+            });
+            if (directRes.ok) {
+              const now = /* @__PURE__ */ new Date();
+              return {
+                id: `direct-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                from: this.did,
+                to: recipientDid,
+                timestamp: now.toISOString(),
+                expiresAt: new Date(now.getTime() + 864e5).toISOString(),
+                encrypted: true,
+                clientSide: true,
+                direct: true
+              };
+            }
+          }
+        }
+      }
+    } catch {
+    }
+    const result = await this.send(recipientDid, message, options);
+    return { ...result, direct: false };
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // COVER TRAFFIC — Noise Protocol for Traffic Analysis Resistance
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Enable cover traffic — sends encrypted noise at random intervals.
+   * Makes real messages indistinguishable from cover traffic for any observer
+   * monitoring message timing and frequency.
+   *
+   * Cover messages are encrypted and padded identically to real messages.
+   * The relay cannot distinguish them from real traffic.
+   *
+   * @example
+   * ```ts
+   * // Send noise every ~30s (randomized ±50%)
+   * agent.enableCoverTraffic({ intervalMs: 30000 });
+   *
+   * // Stop cover traffic
+   * agent.disableCoverTraffic();
+   * ```
+   */
+  enableCoverTraffic(options = {}) {
+    this.disableCoverTraffic();
+    const baseInterval = options.intervalMs || 3e4;
+    const sendNoise = async () => {
+      try {
+        const noise = import_tweetnacl.default.randomBytes(128 + Math.floor(Math.random() * 384));
+        await this.send(this.did, (0, import_tweetnacl_util.encodeBase64)(noise), {
+          messageType: "ping",
+          // use 'ping' type — indistinguishable in encrypted payload
+          ttl: 60
+          // short TTL — noise auto-expires
+        });
+      } catch {
+      }
+    };
+    const scheduleNext = () => {
+      const jitter = baseInterval * (0.5 + Math.random());
+      this._coverTrafficTimer = setTimeout(async () => {
+        await sendNoise();
+        if (this._coverTrafficTimer !== null) scheduleNext();
+      }, jitter);
+    };
+    scheduleNext();
+  }
+  /**
+   * Disable cover traffic.
+   */
+  disableCoverTraffic() {
+    if (this._coverTrafficTimer !== null) {
+      clearTimeout(this._coverTrafficTimer);
+      this._coverTrafficTimer = null;
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // RESILIENT OPERATIONS — Fallback for All Operations
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Fetch from primary relay with fallback to alternate relays.
+   * Unlike _timedFetch which only hits one URL, this tries all known relays.
+   * @internal
+   */
+  async _resilientFetch(path, init) {
+    const relays = [this.baseUrl, ...this.fallbackRelays];
+    let lastError = null;
+    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;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    throw lastError || new Error("All relays failed");
   }
   // ═══════════════════════════════════════════════════════════════════════════
   // CONVERSATIONS — Thread Management
@@ -6307,13 +6868,11 @@ var VoidlyAgent = class _VoidlyAgent {
     return {
       relayCanSee: [
         "Your DID (public identifier)",
-        ...this.sealedSender ? [] : ["Who you message (recipient DIDs)"],
+        "Recipient DIDs (relay needs them for routing)",
         ...this.jitterMs > 0 ? ["Approximate timing (jittered timestamps)"] : ["When you message (timestamps)"],
-        "Message types (text, task-request, etc.)",
-        "Thread structure (which messages are replies)",
+        ...this.sealedSender ? [] : ["Message types, thread IDs, content types (sent in cleartext without sealed sender)"],
         "Channel membership (but NOT channel message content with client-side encryption)",
         "Capability registrations",
-        "Online/offline status",
         "Approximate message size (even with padding, bounded to power-of-2)"
       ],
       relayCannotSee: [
@@ -6323,7 +6882,11 @@ var VoidlyAgent = class _VoidlyAgent {
         "Past message keys (forward secrecy \u2014 hash ratchet + DH ratchet, old keys deleted)",
         "Future message keys (post-compromise recovery via DH ratchet \u2014 compromise heals after one round-trip)",
         "Channel message content (client-side nacl.secretbox encryption \u2014 relay stores only ciphertext)",
-        ...this.sealedSender ? ["Sender identity (sealed inside ciphertext)"] : [],
+        ...this.sealedSender ? [
+          'Sender identity (sealed inside ciphertext \u2014 relay stores "sealed" not your DID)',
+          "Message types, thread IDs, reply chains (packed inside ciphertext in v3)",
+          "Message count (not incremented for sealed senders)"
+        ] : [],
         ...this.deniable ? ["Who authored a message (HMAC is symmetric \u2014 either party could have produced it)"] : []
       ],
       protections: [
@@ -6341,22 +6904,34 @@ var VoidlyAgent = class _VoidlyAgent {
         "Request timeouts (AbortController on all HTTP, configurable)",
         "Request validation (fromCredentials validates key sizes and format)",
         ...this.paddingEnabled ? ["Message padding to power-of-2 boundary (traffic analysis resistance)"] : [],
-        ...this.sealedSender ? ["Sealed sender (relay cannot see who sent a message)"] : [],
+        ...this.sealedSender ? [
+          "Sealed sender (relay cannot see who sent a message)",
+          "Metadata privacy (v3 \u2014 thread_id, message_type, reply_to packed inside ciphertext, stripped from relay storage)"
+        ] : [],
         ...this.requireSignatures ? ["Strict signature enforcement (reject unsigned/invalid messages)"] : [],
-        ...this.fallbackRelays.length > 0 ? [`Multi-relay fallback (${this.fallbackRelays.length} backup relays)`] : [],
+        ...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)",
+        "Resilient operations (receive, discover, identity \u2014 all try fallback relays)",
         "Auto-retry with exponential backoff",
         "Offline message queue",
         "did:key interoperability (W3C standard DID format)"
       ],
       gaps: [
         ...!this.postQuantum || !this.mlkemPublicKey ? ["No post-quantum protection \u2014 enable postQuantum option and re-register"] : [],
-        "Single relay architecture (no onion routing, no mix network \u2014 mitigated by multi-relay fallback)",
-        "Ratchet state is in-memory (lost on process restart \u2014 export credentials to persist)",
+        ...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"] : [],
+        ...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"] : []
+        ...this.jitterMs === 0 ? ["No timing jitter \u2014 enable jitterMs option for metadata protection"] : [],
+        ...this._coverTrafficTimer === null ? ["No cover traffic \u2014 call enableCoverTraffic() to resist traffic analysis"] : []
       ]
     };
   }