@voidly/agent-sdk 3.2.4 → 3.2.6

package/README.md

@@ -191,13 +191,19 @@ const agent = await VoidlyAgent.register({
 
 ## Examples
 
-See the [examples directory](https://github.com/voidly-ai/agent-sdk/tree/main/examples):
+```bash
+node examples/quickstart.mjs
+```
+
+| Example | What it shows |
+|---------|---------------|
+| [quickstart.mjs](examples/quickstart.mjs) | Register, send, receive in 15 lines |
+| [encrypted-channel.mjs](examples/encrypted-channel.mjs) | Group messaging with client-side encryption |
+| [rpc.mjs](examples/rpc.mjs) | Remote procedure calls between agents |
+| [conversation.mjs](examples/conversation.mjs) | Threaded dialog with waitForReply |
+| [censorship-monitor.mjs](examples/censorship-monitor.mjs) | Real-world: censorship data + encrypted alerts |
 
-- **quickstart.mjs** — Register, send, receive in 15 lines
-- **encrypted-channel.mjs** — Group messaging with client-side encryption
-- **rpc.mjs** — Remote procedure calls between agents
-- **conversation.mjs** — Threaded dialog with waitForReply
-- **censorship-monitor.mjs** — Combine censorship data + agent messaging
+All examples are self-contained and run against the public relay. No API key needed.
 
 ## Protocol
 

package/dist/index.js

@@ -4362,14 +4362,16 @@ var VoidlyAgent = class _VoidlyAgent {
             method: "PUT",
             headers: { "Content-Type": "application/json", "X-Agent-Key": this.apiKey },
             body: JSON.stringify({ value: blob })
-          }).catch(() => {
+          }).catch((e) => {
+            console.warn(`[voidly] \u26A0 Relay ratchet persist failed: ${e instanceof Error ? e.message : e}`);
           });
           break;
         case "custom":
           if (this._onPersist) await this._onPersist(blob);
           break;
       }
-    } catch {
+    } catch (e) {
+      console.warn(`[voidly] \u26A0 Ratchet state persistence failed (${this._persistMode}): ${e instanceof Error ? e.message : e}`);
     }
   }
   /** Load persisted ratchet state and restore into memory */
@@ -4404,14 +4406,16 @@ var VoidlyAgent = class _VoidlyAgent {
               const data = await res.json();
               blob = data.value;
             }
-          } catch {
+          } catch (e) {
+            console.warn(`[voidly] \u26A0 Relay ratchet load failed: ${e instanceof Error ? e.message : e}`);
           }
           break;
         case "custom":
           if (this._onLoad) blob = await this._onLoad();
           break;
       }
-    } catch {
+    } catch (e) {
+      console.warn(`[voidly] \u26A0 Ratchet state load failed (${this._persistMode}): ${e instanceof Error ? e.message : e}`);
       return;
     }
     if (!blob) return;
@@ -4423,6 +4427,12 @@ var VoidlyAgent = class _VoidlyAgent {
       const states = JSON.parse((0, import_tweetnacl_util.encodeUTF8)(decrypted));
       for (const [pairId, rs] of Object.entries(states)) {
         if (this._ratchetStates.has(pairId)) continue;
+        if (!rs || typeof rs.sendStep !== "number" || typeof rs.recvStep !== "number" || typeof rs.sendChainKey !== "string" || typeof rs.recvChainKey !== "string") {
+          continue;
+        }
+        if (rs.sendStep < 0 || rs.recvStep < 0 || rs.sendStep > 4294967295 || rs.recvStep > 4294967295) {
+          continue;
+        }
         const state = {
           sendChainKey: (0, import_tweetnacl_util.decodeBase64)(rs.sendChainKey),
           sendStep: rs.sendStep,
@@ -4430,20 +4440,21 @@ var VoidlyAgent = class _VoidlyAgent {
           recvStep: rs.recvStep,
           skippedKeys: /* @__PURE__ */ new Map()
         };
-        if (rs.rootKey) state.rootKey = (0, import_tweetnacl_util.decodeBase64)(rs.rootKey);
-        if (rs.dhSendSecretKey && rs.dhSendPublicKey) {
+        if (rs.rootKey && typeof rs.rootKey === "string") state.rootKey = (0, import_tweetnacl_util.decodeBase64)(rs.rootKey);
+        if (typeof rs.dhSendSecretKey === "string" && typeof rs.dhSendPublicKey === "string") {
           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 (typeof rs.dhRecvPubKey === "string") state.dhRecvPubKey = (0, import_tweetnacl_util.decodeBase64)(rs.dhRecvPubKey);
+        if (typeof rs.prevSendStep === "number" && rs.prevSendStep >= 0) state.prevSendStep = rs.prevSendStep;
         if (state.sendChainKey.length === 32 && state.recvChainKey.length === 32) {
           this._ratchetStates.set(pairId, state);
         }
       }
-    } catch {
+    } catch (e) {
+      console.warn(`[voidly] \u26A0 Ratchet state restore failed (corrupt data, starting fresh): ${e instanceof Error ? e.message : e}`);
     }
   }
   /** IndexedDB put helper (browser only) */
@@ -4768,16 +4779,16 @@ var VoidlyAgent = class _VoidlyAgent {
         if (msg.envelope) {
           try {
             const env = JSON.parse(msg.envelope);
-            if (typeof env.ratchet_step === "number") {
+            if (typeof env.ratchet_step === "number" && Number.isInteger(env.ratchet_step) && env.ratchet_step >= 0 && env.ratchet_step <= 4294967295) {
               envelopeRatchetStep = env.ratchet_step;
             }
-            if (typeof env.pq_ciphertext === "string") {
+            if (typeof env.pq_ciphertext === "string" && env.pq_ciphertext.length <= 65536) {
               envelopePqCiphertext = env.pq_ciphertext;
             }
-            if (typeof env.dh_ratchet_key === "string") {
+            if (typeof env.dh_ratchet_key === "string" && env.dh_ratchet_key.length <= 256) {
               envelopeDhRatchetKey = env.dh_ratchet_key;
             }
-            if (typeof env.pn === "number") {
+            if (typeof env.pn === "number" && Number.isInteger(env.pn) && env.pn >= 0 && env.pn <= 4294967295) {
               envelopePn = env.pn;
             }
           } catch {
@@ -4842,9 +4853,10 @@ var VoidlyAgent = class _VoidlyAgent {
                   if (!state.dhSkippedKeys) state.dhSkippedKeys = /* @__PURE__ */ new Map();
                   state.dhSkippedKeys.set(skipKey, skippedMk);
                   ck = nextChainKey;
-                  if (state.dhSkippedKeys.size > MAX_SKIP) {
+                  while (state.dhSkippedKeys.size > MAX_SKIP) {
                     const oldest = state.dhSkippedKeys.keys().next().value;
                     if (oldest !== void 0) state.dhSkippedKeys.delete(oldest);
+                    else break;
                   }
                 }
               }
@@ -4877,16 +4889,18 @@ var VoidlyAgent = class _VoidlyAgent {
           } else if (targetStep > state.recvStep) {
             const skip = targetStep - state.recvStep;
             if (skip > MAX_SKIP) {
-              rawPlaintext = import_tweetnacl.default.box.open(ciphertext, nonce, senderEncPub, this.encryptionKeyPair.secretKey);
+              this._decryptFailCount++;
+              continue;
             } else {
               let ck = state.recvChainKey;
               for (let i = state.recvStep + 1; i < targetStep; i++) {
                 const { nextChainKey: nextChainKey2, messageKey: skippedMk } = await ratchetStep(ck);
                 state.skippedKeys.set(i, skippedMk);
                 ck = nextChainKey2;
-                if (state.skippedKeys.size > MAX_SKIP) {
+                while (state.skippedKeys.size > MAX_SKIP) {
                   const oldest = state.skippedKeys.keys().next().value;
                   if (oldest !== void 0) state.skippedKeys.delete(oldest);
+                  else break;
                 }
               }
               const { nextChainKey, messageKey } = await ratchetStep(ck);
@@ -4973,8 +4987,11 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         this._seenMessageIds.add(msg.id);
         if (this._seenMessageIds.size > 1e4) {
-          const first = this._seenMessageIds.values().next().value;
-          if (first !== void 0) this._seenMessageIds.delete(first);
+          const iter = this._seenMessageIds.values();
+          for (let i = 0; i < 1e3; i++) {
+            const v = iter.next().value;
+            if (v !== void 0) this._seenMessageIds.delete(v);
+          }
         }
         decrypted.push({
           id: msg.id,
@@ -5055,8 +5072,12 @@ var VoidlyAgent = class _VoidlyAgent {
     const profile = await res.json();
     this._identityCache.set(did, { profile, cachedAt: Date.now() });
     if (this._identityCache.size > 500) {
-      const oldest = this._identityCache.keys().next().value;
-      if (oldest !== void 0) this._identityCache.delete(oldest);
+      const excess = this._identityCache.size - 400;
+      const iter = this._identityCache.keys();
+      for (let i = 0; i < excess; i++) {
+        const key = iter.next().value;
+        if (key !== void 0) this._identityCache.delete(key);
+      }
     }
     return profile;
   }

package/dist/index.mjs

@@ -4352,14 +4352,16 @@ var VoidlyAgent = class _VoidlyAgent {
             method: "PUT",
             headers: { "Content-Type": "application/json", "X-Agent-Key": this.apiKey },
             body: JSON.stringify({ value: blob })
-          }).catch(() => {
+          }).catch((e) => {
+            console.warn(`[voidly] \u26A0 Relay ratchet persist failed: ${e instanceof Error ? e.message : e}`);
           });
           break;
         case "custom":
           if (this._onPersist) await this._onPersist(blob);
           break;
       }
-    } catch {
+    } catch (e) {
+      console.warn(`[voidly] \u26A0 Ratchet state persistence failed (${this._persistMode}): ${e instanceof Error ? e.message : e}`);
     }
   }
   /** Load persisted ratchet state and restore into memory */
@@ -4394,14 +4396,16 @@ var VoidlyAgent = class _VoidlyAgent {
               const data = await res.json();
               blob = data.value;
             }
-          } catch {
+          } catch (e) {
+            console.warn(`[voidly] \u26A0 Relay ratchet load failed: ${e instanceof Error ? e.message : e}`);
           }
           break;
         case "custom":
           if (this._onLoad) blob = await this._onLoad();
           break;
       }
-    } catch {
+    } catch (e) {
+      console.warn(`[voidly] \u26A0 Ratchet state load failed (${this._persistMode}): ${e instanceof Error ? e.message : e}`);
       return;
     }
     if (!blob) return;
@@ -4413,6 +4417,12 @@ var VoidlyAgent = class _VoidlyAgent {
       const states = JSON.parse((0, import_tweetnacl_util.encodeUTF8)(decrypted));
       for (const [pairId, rs] of Object.entries(states)) {
         if (this._ratchetStates.has(pairId)) continue;
+        if (!rs || typeof rs.sendStep !== "number" || typeof rs.recvStep !== "number" || typeof rs.sendChainKey !== "string" || typeof rs.recvChainKey !== "string") {
+          continue;
+        }
+        if (rs.sendStep < 0 || rs.recvStep < 0 || rs.sendStep > 4294967295 || rs.recvStep > 4294967295) {
+          continue;
+        }
         const state = {
           sendChainKey: (0, import_tweetnacl_util.decodeBase64)(rs.sendChainKey),
           sendStep: rs.sendStep,
@@ -4420,20 +4430,21 @@ var VoidlyAgent = class _VoidlyAgent {
           recvStep: rs.recvStep,
           skippedKeys: /* @__PURE__ */ new Map()
         };
-        if (rs.rootKey) state.rootKey = (0, import_tweetnacl_util.decodeBase64)(rs.rootKey);
-        if (rs.dhSendSecretKey && rs.dhSendPublicKey) {
+        if (rs.rootKey && typeof rs.rootKey === "string") state.rootKey = (0, import_tweetnacl_util.decodeBase64)(rs.rootKey);
+        if (typeof rs.dhSendSecretKey === "string" && typeof rs.dhSendPublicKey === "string") {
           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 (typeof rs.dhRecvPubKey === "string") state.dhRecvPubKey = (0, import_tweetnacl_util.decodeBase64)(rs.dhRecvPubKey);
+        if (typeof rs.prevSendStep === "number" && rs.prevSendStep >= 0) state.prevSendStep = rs.prevSendStep;
         if (state.sendChainKey.length === 32 && state.recvChainKey.length === 32) {
           this._ratchetStates.set(pairId, state);
         }
       }
-    } catch {
+    } catch (e) {
+      console.warn(`[voidly] \u26A0 Ratchet state restore failed (corrupt data, starting fresh): ${e instanceof Error ? e.message : e}`);
     }
   }
   /** IndexedDB put helper (browser only) */
@@ -4758,16 +4769,16 @@ var VoidlyAgent = class _VoidlyAgent {
         if (msg.envelope) {
           try {
             const env = JSON.parse(msg.envelope);
-            if (typeof env.ratchet_step === "number") {
+            if (typeof env.ratchet_step === "number" && Number.isInteger(env.ratchet_step) && env.ratchet_step >= 0 && env.ratchet_step <= 4294967295) {
               envelopeRatchetStep = env.ratchet_step;
             }
-            if (typeof env.pq_ciphertext === "string") {
+            if (typeof env.pq_ciphertext === "string" && env.pq_ciphertext.length <= 65536) {
               envelopePqCiphertext = env.pq_ciphertext;
             }
-            if (typeof env.dh_ratchet_key === "string") {
+            if (typeof env.dh_ratchet_key === "string" && env.dh_ratchet_key.length <= 256) {
               envelopeDhRatchetKey = env.dh_ratchet_key;
             }
-            if (typeof env.pn === "number") {
+            if (typeof env.pn === "number" && Number.isInteger(env.pn) && env.pn >= 0 && env.pn <= 4294967295) {
               envelopePn = env.pn;
             }
           } catch {
@@ -4832,9 +4843,10 @@ var VoidlyAgent = class _VoidlyAgent {
                   if (!state.dhSkippedKeys) state.dhSkippedKeys = /* @__PURE__ */ new Map();
                   state.dhSkippedKeys.set(skipKey, skippedMk);
                   ck = nextChainKey;
-                  if (state.dhSkippedKeys.size > MAX_SKIP) {
+                  while (state.dhSkippedKeys.size > MAX_SKIP) {
                     const oldest = state.dhSkippedKeys.keys().next().value;
                     if (oldest !== void 0) state.dhSkippedKeys.delete(oldest);
+                    else break;
                   }
                 }
               }
@@ -4867,16 +4879,18 @@ var VoidlyAgent = class _VoidlyAgent {
           } else if (targetStep > state.recvStep) {
             const skip = targetStep - state.recvStep;
             if (skip > MAX_SKIP) {
-              rawPlaintext = import_tweetnacl.default.box.open(ciphertext, nonce, senderEncPub, this.encryptionKeyPair.secretKey);
+              this._decryptFailCount++;
+              continue;
             } else {
               let ck = state.recvChainKey;
               for (let i = state.recvStep + 1; i < targetStep; i++) {
                 const { nextChainKey: nextChainKey2, messageKey: skippedMk } = await ratchetStep(ck);
                 state.skippedKeys.set(i, skippedMk);
                 ck = nextChainKey2;
-                if (state.skippedKeys.size > MAX_SKIP) {
+                while (state.skippedKeys.size > MAX_SKIP) {
                   const oldest = state.skippedKeys.keys().next().value;
                   if (oldest !== void 0) state.skippedKeys.delete(oldest);
+                  else break;
                 }
               }
               const { nextChainKey, messageKey } = await ratchetStep(ck);
@@ -4963,8 +4977,11 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         this._seenMessageIds.add(msg.id);
         if (this._seenMessageIds.size > 1e4) {
-          const first = this._seenMessageIds.values().next().value;
-          if (first !== void 0) this._seenMessageIds.delete(first);
+          const iter = this._seenMessageIds.values();
+          for (let i = 0; i < 1e3; i++) {
+            const v = iter.next().value;
+            if (v !== void 0) this._seenMessageIds.delete(v);
+          }
         }
         decrypted.push({
           id: msg.id,
@@ -5045,8 +5062,12 @@ var VoidlyAgent = class _VoidlyAgent {
     const profile = await res.json();
     this._identityCache.set(did, { profile, cachedAt: Date.now() });
     if (this._identityCache.size > 500) {
-      const oldest = this._identityCache.keys().next().value;
-      if (oldest !== void 0) this._identityCache.delete(oldest);
+      const excess = this._identityCache.size - 400;
+      const iter = this._identityCache.keys();
+      for (let i = 0; i < excess; i++) {
+        const key = iter.next().value;
+        if (key !== void 0) this._identityCache.delete(key);
+      }
     }
     return profile;
   }

package/examples/censorship-monitor.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Censorship Monitor — Real-world use case combining Voidly data + agent messaging.
+ *
+ * Run:  node examples/censorship-monitor.mjs
+ *
+ * Fetches live censorship data from the Voidly API, checks for high block
+ * rates, and sends an encrypted alert to a subscriber agent.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+const ALERT_THRESHOLD = 50; // Alert if censorship score > 50 (out of 100)
+
+// Register a monitor agent and a subscriber agent
+const monitor    = await VoidlyAgent.register({ name: 'censorship-monitor' });
+const subscriber = await VoidlyAgent.register({ name: 'alert-subscriber' });
+
+console.log(`Monitor:    ${monitor.did}`);
+console.log(`Subscriber: ${subscriber.did}\n`);
+
+// Fetch live censorship index from Voidly public API
+console.log('Fetching live censorship data...');
+const res = await fetch('https://api.voidly.ai/data/censorship-index.json');
+const index = await res.json();
+const countries = index.countries;
+console.log(`Loaded data for ${countries.length} countries.\n`);
+
+// Find countries above the alert threshold
+const alerts = countries
+  .filter((c) => c.score > ALERT_THRESHOLD)
+  .sort((a, b) => b.score - a.score)
+  .slice(0, 5);
+
+if (alerts.length === 0) {
+  console.log('No countries above alert threshold.');
+} else {
+  console.log(`${alerts.length} countries with censorship score > ${ALERT_THRESHOLD}:\n`);
+
+  for (const country of alerts) {
+    const alertMsg = JSON.stringify({
+      type: 'censorship_alert',
+      country: country.country,
+      code: country.code,
+      score: country.score,
+      level: country.level,
+      samples: country.samples,
+    });
+
+    // Send encrypted alert
+    await monitor.send(subscriber.did, alertMsg, {
+      contentType: 'application/json',
+      messageType: 'alert',
+    });
+
+    console.log(`  ⚠ ${country.country} (${country.code}): score ${country.score}/100 [${country.level}]`);
+  }
+
+  // Subscriber receives encrypted alerts
+  console.log('\nSubscriber receiving alerts...');
+  const messages = await subscriber.receive({ limit: 10 });
+  console.log(`Received ${messages.length} encrypted alerts.`);
+
+  for (const msg of messages) {
+    const data = JSON.parse(msg.content);
+    console.log(`  ✓ ${data.country}: score ${data.score}/100 — signature valid: ${msg.signatureValid}`);
+  }
+}
+
+console.log('\n✓ Done — censorship monitoring with E2E encrypted alerts.');

package/examples/conversation.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Conversations — Threaded dialog between agents.
+ *
+ * Run:  node examples/conversation.mjs
+ *
+ * Uses conversation() to auto-thread messages and waitForReply()
+ * for synchronous back-and-forth. Great for LLM agent dialogs.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+const researcher = await VoidlyAgent.register({ name: 'conv-researcher' });
+const analyst    = await VoidlyAgent.register({ name: 'conv-analyst' });
+
+console.log(`Researcher: ${researcher.did}`);
+console.log(`Analyst:    ${analyst.did}\n`);
+
+// Start a threaded conversation
+const conv = researcher.conversation(analyst.did);
+
+// Researcher sends first message
+await conv.say('Is twitter.com currently blocked in Iran?');
+console.log('Researcher: "Is twitter.com currently blocked in Iran?"');
+
+// Simulate the analyst responding (in a real app, the analyst's
+// listener would process the question and reply automatically)
+const analystConv = analyst.conversation(researcher.did, conv.threadId);
+await analystConv.say('Yes — DNS poisoning detected across 3 major ISPs. Block rate: 94%.');
+console.log('Analyst:    "Yes — DNS poisoning detected across 3 major ISPs."');
+
+// Researcher waits for the reply
+const reply = await conv.waitForReply(10000);
+console.log(`\nResearcher received reply: "${reply.content}"`);
+console.log(`  Thread:          ${reply.threadId}`);
+console.log(`  Signature valid: ${reply.signatureValid}`);
+
+// View full conversation history
+const history = await conv.history();
+console.log(`\nConversation history: ${history.length} messages`);
+for (const msg of history) {
+  const who = msg.from === researcher.did ? 'Researcher' : 'Analyst';
+  console.log(`  ${who}: "${msg.content}"`);
+}
+
+console.log('\n✓ Done — threaded conversation with E2E encryption.');

package/examples/encrypted-channel.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * Encrypted Channels — Group messaging with client-side encryption.
+ *
+ * Run:  node examples/encrypted-channel.mjs
+ *
+ * Channel key is generated locally. The relay stores opaque ciphertext
+ * and cannot read channel messages.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+// Register two agents
+const alice = await VoidlyAgent.register({ name: 'chan-alice' });
+const bob   = await VoidlyAgent.register({ name: 'chan-bob' });
+
+// Alice creates an encrypted channel (key generated client-side)
+const { id: channelId, channelKey } = await alice.createEncryptedChannel({
+  name: 'research-team',
+  description: 'Private research coordination',
+});
+console.log(`Channel created: ${channelId}\n`);
+
+// Bob joins
+await bob.joinChannel(channelId);
+console.log('Bob joined the channel.\n');
+
+// Alice posts an encrypted message
+await alice.postEncrypted(channelId, 'New censorship incident detected in IR', channelKey);
+console.log('Alice posted: "New censorship incident detected in IR"\n');
+
+// Bob reads and decrypts with the shared channel key
+const { messages } = await bob.readEncrypted(channelId, channelKey);
+for (const msg of messages) {
+  console.log(`Bob read: "${msg.content}"`);
+  console.log(`  From:            ${msg.from}`);
+  console.log(`  Signature valid: ${msg.signatureValid}`);
+}
+
+console.log('\n✓ Done — group messages encrypted with NaCl secretbox.');

package/examples/quickstart.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Quickstart — Register two agents, send an encrypted message, receive it.
+ *
+ * Run:  node examples/quickstart.mjs
+ *
+ * All encryption happens client-side. The relay never sees plaintext.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+const alice = await VoidlyAgent.register({ name: 'example-alice' });
+const bob   = await VoidlyAgent.register({ name: 'example-bob' });
+
+console.log(`Alice: ${alice.did}`);
+console.log(`Bob:   ${bob.did}\n`);
+
+// Alice sends an encrypted message to Bob
+await alice.send(bob.did, 'Hello from Alice!');
+console.log('Alice → Bob: "Hello from Alice!" (encrypted + signed)\n');
+
+// Bob receives and decrypts
+const messages = await bob.receive();
+for (const msg of messages) {
+  console.log(`Bob received: "${msg.content}"`);
+  console.log(`  From:            ${msg.from}`);
+  console.log(`  Signature valid: ${msg.signatureValid}`);
+  console.log(`  Encrypted:       client-side (relay never saw plaintext)`);
+}
+
+console.log('\n✓ Done — two agents communicated with E2E encryption.');

package/examples/rpc.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Agent RPC — Call functions on remote agents.
+ *
+ * Run:  node examples/rpc.mjs
+ *
+ * Agent A exposes a "translate" method. Agent B invokes it remotely.
+ * The RPC payload is E2E encrypted — the relay never sees the request or response.
+ */
+import { VoidlyAgent } from '@voidly/agent-sdk';
+
+// Register a "translator" agent and a "client" agent
+const translator = await VoidlyAgent.register({
+  name: 'rpc-translator',
+  capabilities: ['translate'],
+});
+const client = await VoidlyAgent.register({ name: 'rpc-client' });
+
+console.log(`Translator: ${translator.did}`);
+console.log(`Client:     ${client.did}\n`);
+
+// Translator registers an RPC handler
+translator.onInvoke('translate', async (params) => {
+  console.log(`Translator received RPC: translate("${params.text}" → ${params.to})`);
+  // Simulate translation (real agent would call an LLM or translation API)
+  const translations = { es: 'Hola', fr: 'Bonjour', de: 'Hallo', ja: 'こんにちは' };
+  return { translated: translations[params.to] || params.text, lang: params.to };
+});
+
+// Start the translator's listener so it can receive RPC calls
+const stop = translator.listen(() => {});
+
+// Client invokes the translator's "translate" method
+console.log('Client calling translate("Hello" → "es")...');
+const result = await client.invoke(translator.did, 'translate', {
+  text: 'Hello',
+  to: 'es',
+});
+console.log(`Result: ${JSON.stringify(result)}`);
+
+stop(); // Stop listening
+console.log('\n✓ Done — remote procedure call over E2E encrypted channel.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidly/agent-sdk",
-  "version": "3.2.4",
+  "version": "3.2.6",
   "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",
@@ -13,7 +13,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "examples"
   ],
   "scripts": {
     "build": "tsup",
@@ -31,13 +32,20 @@
   },
   "keywords": [
     "agent",
+    "ai-agent",
+    "multi-agent",
     "encryption",
     "e2e",
+    "double-ratchet",
+    "post-quantum",
     "nacl",
     "did",
+    "privacy",
     "voidly",
     "mcp",
-    "a2a"
+    "a2a",
+    "langchain",
+    "crewai"
   ],
   "license": "MIT",
   "repository": {