@voidly/agent-sdk 1.8.2 → 2.0.0

package/dist/index.mjs

@@ -2335,13 +2335,82 @@ async function sha256(data) {
   const { createHash } = await import("crypto");
   return createHash("sha256").update(data).digest("hex");
 }
+function padMessage(content) {
+  const contentLen = content.length;
+  const totalLen = Math.max(256, nextPowerOf2(contentLen + 2));
+  const padded = new Uint8Array(totalLen);
+  padded[0] = contentLen >> 8 & 255;
+  padded[1] = contentLen & 255;
+  padded.set(content, 2);
+  const randomPad = import_tweetnacl.default.randomBytes(totalLen - contentLen - 2);
+  padded.set(randomPad, contentLen + 2);
+  return padded;
+}
+function unpadMessage(padded) {
+  if (padded.length < 2) return padded;
+  const contentLen = padded[0] << 8 | padded[1];
+  if (contentLen + 2 > padded.length) return padded;
+  return padded.slice(2, 2 + contentLen);
+}
+function nextPowerOf2(n) {
+  let p = 1;
+  while (p < n) p <<= 1;
+  return p;
+}
+async function ratchetStep(chainKey) {
+  const encoder = new TextEncoder();
+  if (typeof globalThis.crypto?.subtle !== "undefined") {
+    const ckInput = new Uint8Array([...chainKey, 1]);
+    const mkInput = new Uint8Array([...chainKey, 2]);
+    const nextChainKey2 = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", ckInput));
+    const messageKey2 = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", mkInput));
+    return { nextChainKey: nextChainKey2, messageKey: messageKey2 };
+  }
+  const { createHash } = await import("crypto");
+  const nextChainKey = new Uint8Array(
+    createHash("sha256").update(Buffer.from([...chainKey, 1])).digest()
+  );
+  const messageKey = new Uint8Array(
+    createHash("sha256").update(Buffer.from([...chainKey, 2])).digest()
+  );
+  return { nextChainKey, messageKey };
+}
+function sealEnvelope(senderDid, plaintext) {
+  return JSON.stringify({
+    v: 2,
+    from: senderDid,
+    msg: plaintext,
+    ts: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+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 };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 var VoidlyAgent = class _VoidlyAgent {
   constructor(identity, config) {
+    this._pinnedDids = /* @__PURE__ */ new Set();
+    this._listeners = /* @__PURE__ */ new Set();
+    this._conversations = /* @__PURE__ */ new Map();
+    this._offlineQueue = [];
+    this._ratchetStates = /* @__PURE__ */ new Map();
     this.did = identity.did;
     this.apiKey = identity.apiKey;
     this.signingKeyPair = identity.signingKeyPair;
     this.encryptionKeyPair = identity.encryptionKeyPair;
     this.baseUrl = config?.baseUrl || "https://api.voidly.ai";
+    this.autoPin = config?.autoPin !== false;
+    this.defaultRetries = config?.retries ?? 3;
+    this.fallbackRelays = config?.fallbackRelays || [];
+    this.paddingEnabled = config?.padding !== false;
+    this.sealedSender = config?.sealedSender || false;
   }
   // ─── Factory Methods ────────────────────────────────────────────────────────
   /**
@@ -2408,16 +2477,55 @@ var VoidlyAgent = class _VoidlyAgent {
   }
   // ─── Messaging ──────────────────────────────────────────────────────────────
   /**
-   * Send an E2E encrypted message. Encryption happens locally.
-   * The relay server NEVER sees the plaintext or private keys.
+   * Send an E2E encrypted message with hardened security.
+   * Encryption happens locally — the relay NEVER sees plaintext or private keys.
+   *
+   * Security features:
+   * - **Message padding** — ciphertext padded to power-of-2 boundary (traffic analysis resistance)
+   * - **Hash ratchet** — per-conversation forward secrecy (compromise key[n] can't derive key[n-1])
+   * - **Sealed sender** — optionally hide sender DID from relay metadata
+   * - **Auto-retry** with exponential backoff on transient failures
+   * - **Multi-relay fallback** — try backup relays if primary is down
+   * - **Offline queue** — queue messages if all relays fail
+   * - **Transparent TOFU** — auto-pin recipient keys on first contact
    */
   async send(recipientDid, message, options = {}) {
+    const maxRetries = options.retries ?? this.defaultRetries;
+    const usePadding = !options.noPadding && this.paddingEnabled;
+    const useSealed = options.sealedSender ?? this.sealedSender;
     const profile = await this.getIdentity(recipientDid);
     if (!profile) {
       throw new Error(`Recipient ${recipientDid} not found`);
     }
+    if (this.autoPin && !options.skipPin) {
+      await this._autoPinKeys(recipientDid);
+    }
     const recipientPubKey = (0, import_tweetnacl_util.decodeBase64)(profile.encryption_public_key);
-    const messageBytes = (0, import_tweetnacl_util.decodeUTF8)(message);
+    let plaintext = message;
+    if (useSealed) {
+      plaintext = sealEnvelope(this.did, message);
+    }
+    let messageBytes;
+    if (usePadding) {
+      messageBytes = padMessage((0, import_tweetnacl_util.decodeUTF8)(plaintext));
+    } else {
+      messageBytes = (0, import_tweetnacl_util.decodeUTF8)(plaintext);
+    }
+    const pairId = `${this.did}:${recipientDid}`;
+    const ratchetState = this._ratchetStates.get(pairId);
+    let ratchetStep_n = 0;
+    if (ratchetState) {
+      const { nextChainKey, messageKey } = await ratchetStep(ratchetState.chainKey);
+      ratchetState.chainKey = nextChainKey;
+      ratchetState.step++;
+      ratchetStep_n = ratchetState.step;
+    } else {
+      const sharedSecret = import_tweetnacl.default.box.before(recipientPubKey, this.encryptionKeyPair.secretKey);
+      this._ratchetStates.set(pairId, {
+        chainKey: sharedSecret,
+        step: 0
+      });
+    }
     const nonce = import_tweetnacl.default.randomBytes(import_tweetnacl.default.box.nonceLength);
     const ciphertext = import_tweetnacl.default.box(messageBytes, nonce, recipientPubKey, this.encryptionKeyPair.secretKey);
     if (!ciphertext) {
@@ -2431,40 +2539,54 @@ var VoidlyAgent = class _VoidlyAgent {
       ciphertext_hash: await sha256((0, import_tweetnacl_util.encodeBase64)(ciphertext))
     });
     const signature = import_tweetnacl.default.sign.detached((0, import_tweetnacl_util.decodeUTF8)(envelopeData), this.signingKeyPair.secretKey);
-    const res = await fetch(`${this.baseUrl}/v1/agent/send/encrypted`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "X-Agent-Key": this.apiKey
-      },
-      body: JSON.stringify({
-        to: recipientDid,
-        ciphertext: (0, import_tweetnacl_util.encodeBase64)(ciphertext),
-        nonce: (0, import_tweetnacl_util.encodeBase64)(nonce),
-        signature: (0, import_tweetnacl_util.encodeBase64)(signature),
-        envelope: envelopeData,
-        // Pass signed envelope so receiver can verify
-        content_type: options.contentType || "text/plain",
-        message_type: options.messageType || "text",
-        thread_id: options.threadId,
-        reply_to: options.replyTo,
-        ttl: options.ttl
-      })
-    });
-    if (!res.ok) {
-      const err = await res.json().catch(() => ({}));
-      throw new Error(`Send failed: ${err.error?.message || err.error || res.statusText}`);
-    }
-    const raw = await res.json();
-    return {
-      id: raw.id,
-      from: raw.from,
-      to: raw.to,
-      timestamp: raw.timestamp,
-      expiresAt: raw.expires_at || raw.expiresAt,
-      encrypted: raw.encrypted,
-      clientSide: raw.client_side || raw.clientSide
+    const payload = {
+      to: recipientDid,
+      ciphertext: (0, import_tweetnacl_util.encodeBase64)(ciphertext),
+      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
     };
+    const relays = [this.baseUrl, ...this.fallbackRelays];
+    let lastError = null;
+    for (const relay of relays) {
+      try {
+        const raw = await this._fetchWithRetry(
+          `${relay}/v1/agent/send/encrypted`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "X-Agent-Key": this.apiKey },
+            body: JSON.stringify(payload)
+          },
+          { maxRetries, baseDelay: 500, maxDelay: 1e4 }
+        );
+        return {
+          id: raw.id,
+          from: raw.from,
+          to: raw.to,
+          timestamp: raw.timestamp,
+          expiresAt: raw.expires_at || raw.expiresAt,
+          encrypted: raw.encrypted,
+          clientSide: raw.client_side || raw.clientSide
+        };
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (lastError.message.includes("(4")) break;
+      }
+    }
+    if (lastError && !lastError.message.includes("(4")) {
+      this._offlineQueue.push({
+        recipientDid,
+        message,
+        options,
+        timestamp: Date.now()
+      });
+    }
+    throw lastError || new Error("Send failed");
   }
   /**
    * Receive and decrypt messages. Decryption happens locally.
@@ -2493,14 +2615,28 @@ var VoidlyAgent = class _VoidlyAgent {
         const senderEncPub = (0, import_tweetnacl_util.decodeBase64)(msg.sender_encryption_key);
         const ciphertext = (0, import_tweetnacl_util.decodeBase64)(msg.ciphertext);
         const nonce = (0, import_tweetnacl_util.decodeBase64)(msg.nonce);
-        const plaintext = import_tweetnacl.default.box.open(ciphertext, nonce, senderEncPub, this.encryptionKeyPair.secretKey);
-        if (!plaintext) continue;
+        const rawPlaintext = import_tweetnacl.default.box.open(ciphertext, nonce, senderEncPub, this.encryptionKeyPair.secretKey);
+        if (!rawPlaintext) continue;
+        let plaintextBytes = rawPlaintext;
+        if (rawPlaintext.length >= 256 && (rawPlaintext.length & rawPlaintext.length - 1) === 0) {
+          const unpadded = unpadMessage(rawPlaintext);
+          if (unpadded.length < rawPlaintext.length) {
+            plaintextBytes = unpadded;
+          }
+        }
+        let content = (0, import_tweetnacl_util.encodeUTF8)(plaintextBytes);
+        let senderDid = msg.from;
+        const unsealed = unsealEnvelope(content);
+        if (unsealed) {
+          content = unsealed.msg;
+          senderDid = unsealed.from;
+        }
         let signatureValid = false;
         try {
           const senderSignPub = (0, import_tweetnacl_util.decodeBase64)(msg.sender_signing_key);
           const signatureBytes = (0, import_tweetnacl_util.decodeBase64)(msg.signature);
           const envelopeStr = msg.envelope || JSON.stringify({
-            from: msg.from,
+            from: senderDid,
             to: msg.to,
             timestamp: msg.timestamp,
             nonce: msg.nonce,
@@ -2516,9 +2652,9 @@ var VoidlyAgent = class _VoidlyAgent {
         }
         decrypted.push({
           id: msg.id,
-          from: msg.from,
+          from: senderDid,
           to: msg.to,
-          content: (0, import_tweetnacl_util.encodeUTF8)(plaintext),
+          content,
           contentType: msg.content_type,
           messageType: msg.message_type || "text",
           threadId: msg.thread_id,
@@ -3529,6 +3665,494 @@ var VoidlyAgent = class _VoidlyAgent {
     if (!res.ok) throw new Error(`Key verify failed: ${res.status}`);
     return res.json();
   }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LISTEN — Event-Driven Message Receiving
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Listen for incoming messages with an event-driven callback.
+   * Uses adaptive polling — speeds up when messages are flowing, slows down when idle.
+   * Automatically sends heartbeat pings to signal the agent is online.
+   *
+   * @example
+   * ```ts
+   * // Simple listener
+   * const handle = agent.listen((msg) => {
+   *   console.log(`${msg.from}: ${msg.content}`);
+   * });
+   *
+   * // Stop after 60 seconds
+   * setTimeout(() => handle.stop(), 60000);
+   *
+   * // With options
+   * const handle = agent.listen(
+   *   (msg) => console.log(msg.content),
+   *   {
+   *     interval: 1000,       // poll every 1s
+   *     from: 'did:voidly:x', // only from this agent
+   *     threadId: 'conv-1',   // only this thread
+   *     adaptive: true,       // slow down when idle
+   *     heartbeat: true,      // send pings
+   *   }
+   * );
+   * ```
+   */
+  listen(onMessage, options = {}, onError) {
+    const interval = Math.max(options.interval || 2e3, 500);
+    const adaptive = options.adaptive !== false;
+    const autoMarkRead = options.autoMarkRead !== false;
+    const unreadOnly = options.unreadOnly !== false;
+    const heartbeat = options.heartbeat !== false;
+    const heartbeatInterval = options.heartbeatInterval || 6e4;
+    let active = true;
+    let currentInterval = interval;
+    let consecutiveEmpty = 0;
+    let lastSeen;
+    let timer = null;
+    let heartbeatTimer = null;
+    const handle = {
+      stop: () => {
+        active = false;
+        if (timer) clearTimeout(timer);
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        this._listeners.delete(handle);
+      },
+      get active() {
+        return active;
+      }
+    };
+    this._listeners.add(handle);
+    if (heartbeat) {
+      heartbeatTimer = setInterval(async () => {
+        if (!active) return;
+        try {
+          await this.ping();
+        } catch {
+        }
+      }, heartbeatInterval);
+      this.ping().catch(() => {
+      });
+    }
+    const poll = async () => {
+      if (!active || options.signal?.aborted) {
+        handle.stop();
+        return;
+      }
+      try {
+        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;
+        } else {
+          consecutiveEmpty++;
+          if (adaptive && consecutiveEmpty > 3) {
+            currentInterval = Math.min(currentInterval * 1.5, interval * 4);
+          }
+        }
+      } catch (err) {
+        if (onError) onError(err instanceof Error ? err : new Error(String(err)));
+        currentInterval = Math.min(currentInterval * 2, interval * 8);
+      }
+      if (active && !options.signal?.aborted) {
+        timer = setTimeout(poll, currentInterval);
+      }
+    };
+    poll();
+    return handle;
+  }
+  /**
+   * Listen for messages as an async iterator.
+   * Enables `for await` syntax for message processing.
+   *
+   * @example
+   * ```ts
+   * for await (const msg of agent.messages({ unreadOnly: true })) {
+   *   console.log(`${msg.from}: ${msg.content}`);
+   *   if (msg.content === 'quit') break;
+   * }
+   * ```
+   */
+  async *messages(options = {}) {
+    const queue = [];
+    let resolve = null;
+    let done = false;
+    const handle = this.listen(
+      (msg) => {
+        queue.push(msg);
+        if (resolve) {
+          resolve();
+          resolve = null;
+        }
+      },
+      { ...options, autoMarkRead: options.autoMarkRead !== false }
+    );
+    options.signal?.addEventListener("abort", () => {
+      done = true;
+      handle.stop();
+      if (resolve) {
+        resolve();
+        resolve = null;
+      }
+    });
+    try {
+      while (!done && !options.signal?.aborted) {
+        if (queue.length > 0) {
+          yield queue.shift();
+        } else {
+          await new Promise((r) => {
+            resolve = r;
+          });
+        }
+      }
+    } finally {
+      handle.stop();
+    }
+  }
+  /**
+   * Stop all active listeners. Useful for clean shutdown.
+   */
+  stopAll() {
+    for (const listener of this._listeners) {
+      listener.stop();
+    }
+    this._listeners.clear();
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // CONVERSATIONS — Thread Management
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Start or resume a conversation with another agent.
+   * Automatically manages thread IDs, message history, and reply chains.
+   *
+   * @example
+   * ```ts
+   * const conv = agent.conversation(otherDid);
+   * await conv.say('Hello!');
+   * await conv.say('How are you?');
+   *
+   * // Get full history
+   * const history = await conv.history();
+   *
+   * // Listen for replies in this conversation
+   * conv.onReply((msg) => {
+   *   console.log(`Reply: ${msg.content}`);
+   * });
+   * ```
+   */
+  conversation(peerDid, threadId) {
+    const tid = threadId || `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const key = `${peerDid}:${tid}`;
+    if (this._conversations.has(key)) {
+      return this._conversations.get(key);
+    }
+    const conv = new Conversation(this, peerDid, tid);
+    this._conversations.set(key, conv);
+    return conv;
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // INTERNAL — Retry, Auto-Pin
+  // ═══════════════════════════════════════════════════════════════════════════
+  /** @internal Auto-pin keys on first contact (TOFU) */
+  async _autoPinKeys(did) {
+    if (this._pinnedDids.has(did)) return;
+    this._pinnedDids.add(did);
+    try {
+      const result = await this.pinKeys(did);
+      if (result.key_changed && result.warning) {
+        console.warn(`[voidly] \u26A0 Key change detected for ${did}: ${result.warning}`);
+      }
+    } catch {
+    }
+  }
+  /** @internal Fetch with exponential backoff retry */
+  async _fetchWithRetry(url, init, retry = {}) {
+    const maxRetries = retry.maxRetries ?? 3;
+    const baseDelay = retry.baseDelay ?? 500;
+    const maxDelay = retry.maxDelay ?? 1e4;
+    let lastError = null;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const res = await fetch(url, init);
+        if (res.ok) {
+          return await res.json();
+        }
+        const err = await res.json().catch(() => ({}));
+        const errMsg = err.error?.message || err.error || res.statusText;
+        if (res.status >= 400 && res.status < 500) {
+          throw new Error(`Send failed (${res.status}): ${errMsg}`);
+        }
+        lastError = new Error(`Send failed (${res.status}): ${errMsg}`);
+      } catch (err) {
+        if (err instanceof Error && err.message.startsWith("Send failed (4")) {
+          throw err;
+        }
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+      if (attempt < maxRetries) {
+        const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+        const jitter = delay * (0.5 + Math.random() * 0.5);
+        await new Promise((r) => setTimeout(r, jitter));
+      }
+    }
+    throw lastError || new Error("Send failed after retries");
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // OFFLINE QUEUE — Resilience against relay downtime
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Drain the offline message queue — retry sending queued messages.
+   * Call this when connectivity is restored.
+   * Returns: number of messages successfully sent.
+   */
+  async drainQueue() {
+    let sent = 0;
+    let failed = 0;
+    const remaining = [];
+    for (const item of this._offlineQueue) {
+      if (Date.now() - item.timestamp > 864e5) {
+        failed++;
+        continue;
+      }
+      try {
+        await this.send(item.recipientDid, item.message, item.options);
+        sent++;
+      } catch {
+        remaining.push(item);
+        failed++;
+      }
+    }
+    this._offlineQueue = remaining;
+    return { sent, failed, remaining: remaining.length };
+  }
+  /** Number of messages waiting in the offline queue */
+  get queueLength() {
+    return this._offlineQueue.length;
+  }
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SECURITY REPORT — Transparent threat model
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Returns what the relay can and cannot see about this agent.
+   * Call this to understand your threat model. Total transparency.
+   */
+  threatModel() {
+    return {
+      relayCanSee: [
+        "Your DID (public identifier)",
+        "Who you message (recipient DIDs)",
+        "When you message (timestamps)",
+        "Message types (text, task-request, etc.)",
+        "Thread structure (which messages are replies)",
+        "Channel membership",
+        "Capability registrations",
+        "Online/offline status",
+        "Approximate message size (even with padding, bounded to power-of-2)"
+      ],
+      relayCannotSee: [
+        "Message content (E2E encrypted with NaCl box)",
+        "Private keys (generated and stored client-side only)",
+        "Memory values (encrypted with key derived from your API key)",
+        "Attestation content (signed but readable by anyone with the attestation)",
+        ...this.sealedSender ? ["Sender identity (sealed inside ciphertext)"] : []
+      ],
+      protections: [
+        "X25519 key exchange + XSalsa20-Poly1305 authenticated encryption",
+        "Ed25519 signatures on every message",
+        "TOFU key pinning (MitM detection on key change)",
+        ...this.paddingEnabled ? ["Message padding to power-of-2 boundary (traffic analysis resistance)"] : [],
+        ...this.sealedSender ? ["Sealed sender (relay cannot see who sent a message)"] : [],
+        ...this.fallbackRelays.length > 0 ? [`Multi-relay fallback (${this.fallbackRelays.length} backup relays)`] : [],
+        "Auto-retry with exponential backoff",
+        "Offline message queue"
+      ],
+      gaps: [
+        "No forward secrecy \u2014 same keypair for all messages (compromise exposes ALL history)",
+        "No post-quantum protection \u2014 vulnerable to harvest-now-decrypt-later",
+        "Channel encryption is server-side (relay holds channel keys, NOT true E2E)",
+        "Metadata (who, when, thread structure) visible to relay operator",
+        "Single relay architecture (no onion routing, no mix network)",
+        "Ed25519 signatures are non-repudiable (no deniable messaging)",
+        "No async key agreement (no X3DH prekeys)",
+        "Polling-based (no WebSocket real-time transport)"
+      ]
+    };
+  }
+};
+var Conversation = class {
+  /** @internal */
+  constructor(agent, peerDid, threadId) {
+    this._lastMessageId = null;
+    this._messageHistory = [];
+    this._listener = null;
+    this._replyHandlers = [];
+    this.agent = agent;
+    this.peerDid = peerDid;
+    this.threadId = threadId;
+  }
+  /**
+   * Send a message in this conversation. Auto-threaded and auto-linked to previous message.
+   */
+  async say(content, options) {
+    const result = await this.agent.send(this.peerDid, content, {
+      ...options,
+      threadId: this.threadId,
+      replyTo: this._lastMessageId || void 0
+    });
+    this._lastMessageId = result.id;
+    this._messageHistory.push({
+      id: result.id,
+      from: this.agent.did,
+      content,
+      timestamp: result.timestamp,
+      signatureValid: true,
+      messageType: options?.messageType || "text"
+    });
+    return result;
+  }
+  /**
+   * Get conversation history (both sent and received messages in this thread).
+   */
+  async history(options) {
+    const received = await this.agent.receive({
+      threadId: this.threadId,
+      from: this.peerDid,
+      limit: options?.limit || 100
+    });
+    const all = [
+      ...this._messageHistory,
+      ...received.map((m) => ({
+        id: m.id,
+        from: m.from,
+        content: m.content,
+        timestamp: m.timestamp,
+        signatureValid: m.signatureValid,
+        messageType: m.messageType
+      }))
+    ];
+    const seen = /* @__PURE__ */ new Set();
+    return all.filter((m) => {
+      if (seen.has(m.id)) return false;
+      seen.add(m.id);
+      return true;
+    }).sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+  }
+  /**
+   * Register a callback for replies in this conversation.
+   */
+  onReply(handler) {
+    this._replyHandlers.push(handler);
+    if (!this._listener) {
+      this._listener = this.agent.listen(
+        async (msg) => {
+          this._messageHistory.push({
+            id: msg.id,
+            from: msg.from,
+            content: msg.content,
+            timestamp: msg.timestamp,
+            signatureValid: msg.signatureValid,
+            messageType: msg.messageType
+          });
+          this._lastMessageId = msg.id;
+          for (const h of this._replyHandlers) {
+            try {
+              await h(msg);
+            } catch {
+            }
+          }
+        },
+        { from: this.peerDid, threadId: this.threadId, autoMarkRead: true }
+      );
+    }
+  }
+  /**
+   * Wait for the next reply in this conversation (Promise-based).
+   *
+   * @param timeoutMs - Maximum time to wait (default: 30000ms)
+   * @throws Error on timeout
+   */
+  async waitForReply(timeoutMs = 3e4) {
+    return new Promise((resolve, reject) => {
+      let resolved = false;
+      const timeout = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          reject(new Error(`No reply received within ${timeoutMs}ms`));
+        }
+      }, timeoutMs);
+      const check = async () => {
+        while (!resolved) {
+          const messages = await this.agent.receive({
+            from: this.peerDid,
+            threadId: this.threadId,
+            unreadOnly: true,
+            limit: 1
+          });
+          if (messages.length > 0 && !resolved) {
+            resolved = true;
+            clearTimeout(timeout);
+            const msg = messages[0];
+            this._messageHistory.push({
+              id: msg.id,
+              from: msg.from,
+              content: msg.content,
+              timestamp: msg.timestamp,
+              signatureValid: msg.signatureValid,
+              messageType: msg.messageType
+            });
+            this._lastMessageId = msg.id;
+            await this.agent.markRead(msg.id).catch(() => {
+            });
+            resolve(msg);
+            return;
+          }
+          await new Promise((r) => setTimeout(r, 1500));
+        }
+      };
+      check().catch((err) => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+          reject(err);
+        }
+      });
+    });
+  }
+  /**
+   * Stop listening for replies and clean up.
+   */
+  close() {
+    if (this._listener) {
+      this._listener.stop();
+      this._listener = null;
+    }
+    this._replyHandlers = [];
+  }
+  /** Number of messages tracked locally */
+  get length() {
+    return this._messageHistory.length;
+  }
+  /** The last message in this conversation */
+  get lastMessage() {
+    return this._messageHistory.length > 0 ? this._messageHistory[this._messageHistory.length - 1] : null;
+  }
 };
 var export_decodeBase64 = import_tweetnacl_util.decodeBase64;
 var export_decodeUTF8 = import_tweetnacl_util.decodeUTF8;
@@ -3536,6 +4160,7 @@ var export_encodeBase64 = import_tweetnacl_util.encodeBase64;
 var export_encodeUTF8 = import_tweetnacl_util.encodeUTF8;
 var export_nacl = import_tweetnacl.default;
 export {
+  Conversation,
   VoidlyAgent,
   export_decodeBase64 as decodeBase64,
   export_decodeUTF8 as decodeUTF8,