@voidly/agent-sdk 3.0.0 → 3.1.0

package/dist/index.d.mts

@@ -181,6 +181,10 @@ declare class VoidlyAgent {
     private _identityCache;
     private _seenMessageIds;
     private _decryptFailCount;
+    private _rpcHandlers;
+    private _rpcPending;
+    private _coverTrafficTimer;
+    private _rpcListener;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -996,6 +1000,100 @@ declare class VoidlyAgent {
      * Stop all active listeners. Useful for clean shutdown.
      */
     stopAll(): void;
+    /**
+     * 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);
+     * ```
+     */
+    invoke(targetDid: string, method: string, params?: any, timeoutMs?: number): Promise<any>;
+    /**
+     * 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: string, handler: (params: any, callerDid: string) => Promise<any>): void;
+    /**
+     * Remove an RPC handler.
+     */
+    offInvoke(method: string): void;
+    /** @internal Start listening for RPC requests and responses */
+    private _ensureRpcListener;
+    /**
+     * 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
+     * ```
+     */
+    sendDirect(recipientDid: string, message: string, options?: {
+        contentType?: string;
+        messageType?: string;
+        threadId?: string;
+        ttl?: number;
+    }): Promise<SendResult & {
+        direct: boolean;
+    }>;
+    /**
+     * 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?: {
+        intervalMs?: number;
+    }): void;
+    /**
+     * Disable cover traffic.
+     */
+    disableCoverTraffic(): void;
+    /**
+     * Fetch from primary relay with fallback to alternate relays.
+     * Unlike _timedFetch which only hits one URL, this tries all known relays.
+     * @internal
+     */
+    private _resilientFetch;
     /**
      * Start or resume a conversation with another agent.
      * Automatically manages thread IDs, message history, and reply chains.

package/dist/index.d.ts

@@ -181,6 +181,10 @@ declare class VoidlyAgent {
     private _identityCache;
     private _seenMessageIds;
     private _decryptFailCount;
+    private _rpcHandlers;
+    private _rpcPending;
+    private _coverTrafficTimer;
+    private _rpcListener;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -996,6 +1000,100 @@ declare class VoidlyAgent {
      * Stop all active listeners. Useful for clean shutdown.
      */
     stopAll(): void;
+    /**
+     * 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);
+     * ```
+     */
+    invoke(targetDid: string, method: string, params?: any, timeoutMs?: number): Promise<any>;
+    /**
+     * 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: string, handler: (params: any, callerDid: string) => Promise<any>): void;
+    /**
+     * Remove an RPC handler.
+     */
+    offInvoke(method: string): void;
+    /** @internal Start listening for RPC requests and responses */
+    private _ensureRpcListener;
+    /**
+     * 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
+     * ```
+     */
+    sendDirect(recipientDid: string, message: string, options?: {
+        contentType?: string;
+        messageType?: string;
+        threadId?: string;
+        ttl?: number;
+    }): Promise<SendResult & {
+        direct: boolean;
+    }>;
+    /**
+     * 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?: {
+        intervalMs?: number;
+    }): void;
+    /**
+     * Disable cover traffic.
+     */
+    disableCoverTraffic(): void;
+    /**
+     * Fetch from primary relay with fallback to alternate relays.
+     * Unlike _timedFetch which only hits one URL, this tries all known relays.
+     * @internal
+     */
+    private _resilientFetch;
     /**
      * Start or resume a conversation with another agent.
      * Automatically manages thread IDs, message history, and reply chains.

package/dist/index.js

@@ -3983,19 +3983,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 {
@@ -4073,6 +4083,14 @@ 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;
     this.did = identity.did;
     this.apiKey = identity.apiKey;
     this.signingKeyPair = identity.signingKeyPair;
@@ -4343,7 +4361,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) {
@@ -4458,12 +4481,14 @@ 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;
+    }
     const relays = [this.baseUrl, ...this.fallbackRelays];
     let lastError = null;
     for (const relay of relays) {
@@ -4514,7 +4539,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) {
@@ -4526,7 +4551,20 @@ var VoidlyAgent = class _VoidlyAgent {
     for (const msg of data.messages) {
       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;
@@ -4694,11 +4732,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;
@@ -4719,12 +4765,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 {
@@ -4744,10 +4789,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
@@ -4808,7 +4854,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() });
@@ -4826,7 +4872,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;
@@ -6180,6 +6226,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
@@ -6318,13 +6643,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: [
@@ -6334,7 +6657,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: [
@@ -6352,22 +6679,32 @@ 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.longPoll ? ["Long-poll transport (25s server-held connection \u2014 near-real-time delivery)"] : [],
+        ...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)",
+        ...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.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"] : []
       ]
     };
   }

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,14 @@ 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;
     this.did = identity.did;
     this.apiKey = identity.apiKey;
     this.signingKeyPair = identity.signingKeyPair;
@@ -4332,7 +4350,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 +4470,14 @@ 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;
+    }
     const relays = [this.baseUrl, ...this.fallbackRelays];
     let lastError = null;
     for (const relay of relays) {
@@ -4503,7 +4528,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) {
@@ -4515,7 +4540,20 @@ var VoidlyAgent = class _VoidlyAgent {
     for (const msg of data.messages) {
       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;
@@ -4683,11 +4721,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 +4754,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 +4778,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
@@ -4797,7 +4843,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 +4861,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;
@@ -6169,6 +6215,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 +6632,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 +6646,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 +6668,32 @@ 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.longPoll ? ["Long-poll transport (25s server-held connection \u2014 near-real-time delivery)"] : [],
+        ...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)",
+        ...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.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"] : []
       ]
     };
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@voidly/agent-sdk",
-  "version": "3.0.0",
-  "description": "E2E encrypted agent-to-agent communication SDK — Double Ratchet, X3DH, deniable auth, ML-KEM-768 post-quantum, client-side channels",
+  "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",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",