@voidly/agent-sdk 1.8.1 → 1.9.0

package/dist/index.mjs

@@ -2337,11 +2337,16 @@ async function sha256(data) {
 }
 var VoidlyAgent = class _VoidlyAgent {
   constructor(identity, config) {
+    this._pinnedDids = /* @__PURE__ */ new Set();
+    this._listeners = /* @__PURE__ */ new Set();
+    this._conversations = /* @__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;
   }
   // ─── Factory Methods ────────────────────────────────────────────────────────
   /**
@@ -2408,14 +2413,23 @@ 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 automatic retry and transparent TOFU.
+   * Encryption happens locally — the relay NEVER sees plaintext or private keys.
+   *
+   * Features:
+   * - **Auto-retry** with exponential backoff on transient failures
+   * - **Transparent TOFU** — automatically pins recipient keys on first contact
+   * - **Key verification** — warns if pinned keys have changed (potential MitM)
    */
   async send(recipientDid, message, options = {}) {
+    const maxRetries = options.retries ?? this.defaultRetries;
     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);
     const nonce = import_tweetnacl.default.randomBytes(import_tweetnacl.default.box.nonceLength);
@@ -2431,31 +2445,36 @@ 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
+    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 raw = await this._fetchWithRetry(
+      `${this.baseUrl}/v1/agent/send/encrypted`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-Agent-Key": this.apiKey },
+        body: JSON.stringify(payload)
       },
-      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}`);
-    }
-    return await res.json();
+      { 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
+    };
   }
   /**
    * Receive and decrypt messages. Decryption happens locally.
@@ -3520,6 +3539,413 @@ 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");
+  }
+};
+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;
@@ -3527,6 +3953,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidly/agent-sdk",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "E2E encrypted agent-to-agent communication SDK — true client-side encryption",
   "main": "dist/index.js",
   "module": "dist/index.mjs",