@elisym/sdk 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -320,7 +320,9 @@ declare class NostrPool {
     publish(event: Event): Promise<void>;
     /** Publish to all relays and wait for all to settle. Throws if none accepted. */
     publishAll(event: Event): Promise<void>;
-    subscribe(filter: Filter, onEvent: (event: Event) => void): SubCloser;
+    subscribe(filter: Filter, onEvent: (event: Event) => void, opts?: {
+        oneose?: () => void;
+    }): SubCloser;
     /**
      * Subscribe and wait until at least one relay confirms the subscription
      * is active (EOSE). Resolves on the first relay that responds.
@@ -402,6 +404,43 @@ declare class DiscoveryService {
      * provider.
      */
     fetchAgents(network?: Network, limit?: number): Promise<Agent[]>;
+    /**
+     * Enrich an agent map with paid-job stats, feedback counters, and kind:0
+     * metadata, then return them sorted by `compareAgentsByRank`. Mutates the
+     * passed-in `Agent` objects in place.
+     *
+     * Shared between `fetchAgents` (one-shot) and `streamAgents` (post-EOSE
+     * second pass). The `signal` short-circuits the post-query work; in-flight
+     * pool queries are not cancellable today (they fall through to the standard
+     * timeout) and the caller drops the resolved value.
+     */
+    private runEnrichment;
+    /**
+     * Stream elisym agents progressively as relays deliver events.
+     *
+     * Two live subscriptions:
+     *   - kind:31990 (capability cards) - emits `onAgent(agent)` for every new or
+     *     updated `(pubkey, d-tag)`. The emitted Agent is the merged view across
+     *     all surviving cards for that author.
+     *   - kind:6100 (default-offset job results) tagged `t=elisym` since 30d ago -
+     *     emits `onPaidJob(pubkey, ts)` for each delivered result. Custom-kind
+     *     results (offset != 100) are not on this stream; they enter the final
+     *     ranking via the post-EOSE enrichment pass.
+     *
+     * After capabilities EOSE, an enrichment pass runs in parallel to the live
+     * subscriptions and produces a ranked snapshot via `onComplete`. The snapshot
+     * is a clone, so further live updates do not mutate it.
+     *
+     * `closer.close()` tears down both subscriptions and aborts an in-flight
+     * enrichment. If `opts.signal` is provided, aborting it does the same.
+     */
+    streamAgents(network: Network, opts: {
+        onAgent: (agent: Agent) => void;
+        onPaidJob?: (pubkey: string, ts: number) => void;
+        onEose?: () => void;
+        onComplete?: (agents: Agent[]) => void;
+        signal?: AbortSignal;
+    }): SubCloser;
     /**
      * Publish a capability card (kind:31990) as a provider.
      * Solana address is validated for Base58 format only - full decode

package/dist/index.d.ts

@@ -320,7 +320,9 @@ declare class NostrPool {
     publish(event: Event): Promise<void>;
     /** Publish to all relays and wait for all to settle. Throws if none accepted. */
     publishAll(event: Event): Promise<void>;
-    subscribe(filter: Filter, onEvent: (event: Event) => void): SubCloser;
+    subscribe(filter: Filter, onEvent: (event: Event) => void, opts?: {
+        oneose?: () => void;
+    }): SubCloser;
     /**
      * Subscribe and wait until at least one relay confirms the subscription
      * is active (EOSE). Resolves on the first relay that responds.
@@ -402,6 +404,43 @@ declare class DiscoveryService {
      * provider.
      */
     fetchAgents(network?: Network, limit?: number): Promise<Agent[]>;
+    /**
+     * Enrich an agent map with paid-job stats, feedback counters, and kind:0
+     * metadata, then return them sorted by `compareAgentsByRank`. Mutates the
+     * passed-in `Agent` objects in place.
+     *
+     * Shared between `fetchAgents` (one-shot) and `streamAgents` (post-EOSE
+     * second pass). The `signal` short-circuits the post-query work; in-flight
+     * pool queries are not cancellable today (they fall through to the standard
+     * timeout) and the caller drops the resolved value.
+     */
+    private runEnrichment;
+    /**
+     * Stream elisym agents progressively as relays deliver events.
+     *
+     * Two live subscriptions:
+     *   - kind:31990 (capability cards) - emits `onAgent(agent)` for every new or
+     *     updated `(pubkey, d-tag)`. The emitted Agent is the merged view across
+     *     all surviving cards for that author.
+     *   - kind:6100 (default-offset job results) tagged `t=elisym` since 30d ago -
+     *     emits `onPaidJob(pubkey, ts)` for each delivered result. Custom-kind
+     *     results (offset != 100) are not on this stream; they enter the final
+     *     ranking via the post-EOSE enrichment pass.
+     *
+     * After capabilities EOSE, an enrichment pass runs in parallel to the live
+     * subscriptions and produces a ranked snapshot via `onComplete`. The snapshot
+     * is a clone, so further live updates do not mutate it.
+     *
+     * `closer.close()` tears down both subscriptions and aborts an in-flight
+     * enrichment. If `opts.signal` is provided, aborting it does the same.
+     */
+    streamAgents(network: Network, opts: {
+        onAgent: (agent: Agent) => void;
+        onPaidJob?: (pubkey: string, ts: number) => void;
+        onEose?: () => void;
+        onComplete?: (agents: Agent[]) => void;
+        signal?: AbortSignal;
+    }): SubCloser;
     /**
      * Publish a capability card (kind:31990) as a provider.
      * Solana address is validated for Base58 format only - full decode

package/dist/index.js

@@ -1007,6 +1007,7 @@ async function createPaymentRequestWithOnchainConfig(rpc, programId, recipient,
 var RANKING_ACTIVITY_WINDOW_SECS = 30 * 24 * 60 * 60;
 var RANKING_BUCKET_SIZE_SECS = 60;
 var COLD_START_BUCKET = -Infinity;
+var NEVER_ABORTED_SIGNAL = new AbortController().signal;
 function toDTag(name) {
   const tag = name.toLowerCase().replace(/[^a-z0-9\s-]/g, (ch) => "_" + ch.charCodeAt(0).toString(16).padStart(2, "0")).replace(/\s+/g, "-").replace(/^-+|-+$/g, "");
   if (!tag) {
@@ -1036,13 +1037,63 @@ function compareAgentsByRank(a, b) {
   }
   return kb.lastSeen - ka.lastSeen;
 }
+function parseCapabilityEvent(event, network) {
+  if (!verifyEvent(event)) {
+    return null;
+  }
+  if (!event.content) {
+    return null;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(event.content);
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const candidate = raw;
+  if (typeof candidate.name !== "string" || !candidate.name) {
+    return null;
+  }
+  if (typeof candidate.description !== "string") {
+    return null;
+  }
+  if (!Array.isArray(candidate.capabilities) || !candidate.capabilities.every((cap) => typeof cap === "string")) {
+    return null;
+  }
+  if (candidate.deleted) {
+    return null;
+  }
+  const card = candidate;
+  if (card.payment && (typeof card.payment.chain !== "string" || typeof card.payment.network !== "string" || typeof card.payment.address !== "string")) {
+    return null;
+  }
+  if (card.payment?.job_price !== null && card.payment?.job_price !== void 0 && (!Number.isInteger(card.payment.job_price) || card.payment.job_price < 0)) {
+    return null;
+  }
+  const agentNetwork = card.payment?.network ?? "devnet";
+  if (agentNetwork !== network) {
+    return null;
+  }
+  const kTags = event.tags.filter((tag) => tag[0] === "k").map((tag) => parseInt(tag[1] ?? "", 10)).filter((kind) => !isNaN(kind));
+  return {
+    pubkey: event.pubkey,
+    npub: nip19.npubEncode(event.pubkey),
+    cards: [card],
+    eventId: event.id,
+    supportedKinds: kTags,
+    lastSeen: event.created_at
+  };
+}
 function buildAgentsFromEvents(events, network) {
   const latestByDTag = /* @__PURE__ */ new Map();
   for (const event of events) {
     if (!verifyEvent(event)) {
       continue;
     }
-    const dTag = event.tags.find((t) => t[0] === "d")?.[1] ?? "";
+    const dTag = event.tags.find((tag) => tag[0] === "d")?.[1] ?? "";
     const key = `${event.pubkey}:${dTag}`;
     const prev = latestByDTag.get(key);
     if (!prev || event.created_at > prev.created_at) {
@@ -1051,82 +1102,51 @@ function buildAgentsFromEvents(events, network) {
   }
   const accumMap = /* @__PURE__ */ new Map();
   for (const event of latestByDTag.values()) {
-    try {
-      if (!event.content) {
-        continue;
-      }
-      const raw = JSON.parse(event.content);
-      if (!raw || typeof raw !== "object") {
-        continue;
-      }
-      if (typeof raw.name !== "string" || !raw.name) {
-        continue;
-      }
-      if (typeof raw.description !== "string") {
-        continue;
-      }
-      if (!Array.isArray(raw.capabilities) || !raw.capabilities.every((c) => typeof c === "string")) {
-        continue;
-      }
-      if (raw.deleted) {
-        continue;
-      }
-      const card = raw;
-      if (card.payment && (typeof card.payment.chain !== "string" || typeof card.payment.network !== "string" || typeof card.payment.address !== "string")) {
-        continue;
-      }
-      if (card.payment?.job_price !== null && card.payment?.job_price !== void 0 && (!Number.isInteger(card.payment.job_price) || card.payment.job_price < 0)) {
-        continue;
-      }
-      const agentNetwork = card.payment?.network ?? "devnet";
-      if (agentNetwork !== network) {
-        continue;
-      }
-      const kTags = event.tags.filter((t) => t[0] === "k").map((t) => parseInt(t[1] ?? "", 10)).filter((k) => !isNaN(k));
-      const entry = { card, kTags, createdAt: event.created_at };
-      const existing = accumMap.get(event.pubkey);
-      if (existing) {
-        const dupIndex = existing.entries.findIndex((e) => e.card.name === card.name);
-        if (dupIndex >= 0) {
-          if (entry.createdAt >= existing.entries[dupIndex].createdAt) {
-            existing.entries[dupIndex] = entry;
+    const parsed = parseCapabilityEvent(event, network);
+    if (!parsed) {
+      continue;
+    }
+    const card = parsed.cards[0];
+    const cardKinds = parsed.supportedKinds;
+    const createdAt = parsed.lastSeen;
+    const existing = accumMap.get(parsed.pubkey);
+    if (existing) {
+      const prevForName = existing.perCard.get(card.name);
+      if (prevForName) {
+        if (createdAt >= prevForName.createdAt) {
+          const idx = existing.agent.cards.findIndex(
+            (existingCard) => existingCard.name === card.name
+          );
+          if (idx >= 0) {
+            existing.agent.cards[idx] = card;
           }
-        } else {
-          existing.entries.push(entry);
-        }
-        if (event.created_at > existing.lastSeen) {
-          existing.lastSeen = event.created_at;
-          existing.eventId = event.id;
+          existing.perCard.set(card.name, { createdAt, kTags: cardKinds });
         }
       } else {
-        accumMap.set(event.pubkey, {
-          pubkey: event.pubkey,
-          npub: nip19.npubEncode(event.pubkey),
-          entries: [entry],
-          eventId: event.id,
-          lastSeen: event.created_at
-        });
+        existing.agent.cards.push(card);
+        existing.perCard.set(card.name, { createdAt, kTags: cardKinds });
       }
-    } catch {
+      if (createdAt > existing.agent.lastSeen) {
+        existing.agent.lastSeen = createdAt;
+        existing.agent.eventId = parsed.eventId;
+      }
+    } else {
+      accumMap.set(parsed.pubkey, {
+        agent: parsed,
+        perCard: /* @__PURE__ */ new Map([[card.name, { createdAt, kTags: cardKinds }]])
+      });
     }
   }
   const agentMap = /* @__PURE__ */ new Map();
   for (const [pubkey, acc] of accumMap) {
     const kindsSet = /* @__PURE__ */ new Set();
-    for (const e of acc.entries) {
-      for (const k of e.kTags) {
-        kindsSet.add(k);
-      }
-    }
-    const supportedKinds = [...kindsSet];
-    agentMap.set(pubkey, {
-      pubkey: acc.pubkey,
-      npub: acc.npub,
-      cards: acc.entries.map((e) => e.card),
-      eventId: acc.eventId,
-      supportedKinds,
-      lastSeen: acc.lastSeen
-    });
+    for (const { kTags } of acc.perCard.values()) {
+      for (const kind of kTags) {
+        kindsSet.add(kind);
+      }
+    }
+    acc.agent.supportedKinds = [...kindsSet];
+    agentMap.set(pubkey, acc.agent);
   }
   return agentMap;
 }
@@ -1241,6 +1261,19 @@ var DiscoveryService = class {
     const events = await this.pool.querySync(filter);
     const agentMap = buildAgentsFromEvents(events, network);
     const agents = Array.from(agentMap.values());
+    return this.runEnrichment(agents, agentMap, NEVER_ABORTED_SIGNAL);
+  }
+  /**
+   * Enrich an agent map with paid-job stats, feedback counters, and kind:0
+   * metadata, then return them sorted by `compareAgentsByRank`. Mutates the
+   * passed-in `Agent` objects in place.
+   *
+   * Shared between `fetchAgents` (one-shot) and `streamAgents` (post-EOSE
+   * second pass). The `signal` short-circuits the post-query work; in-flight
+   * pool queries are not cancellable today (they fall through to the standard
+   * timeout) and the caller drops the resolved value.
+   */
+  async runEnrichment(agents, agentMap, signal) {
     const agentPubkeys = Array.from(agentMap.keys());
     if (agentPubkeys.length === 0) {
       return agents;
@@ -1248,9 +1281,9 @@ var DiscoveryService = class {
     const activitySince = Math.floor(Date.now() / 1e3) - RANKING_ACTIVITY_WINDOW_SECS;
     const resultKinds = /* @__PURE__ */ new Set();
     for (const agent of agentMap.values()) {
-      for (const k of agent.supportedKinds) {
-        if (k >= KIND_JOB_REQUEST_BASE && k < KIND_JOB_RESULT_BASE) {
-          resultKinds.add(KIND_JOB_RESULT_BASE + (k - KIND_JOB_REQUEST_BASE));
+      for (const supportedKind of agent.supportedKinds) {
+        if (supportedKind >= KIND_JOB_REQUEST_BASE && supportedKind < KIND_JOB_RESULT_BASE) {
+          resultKinds.add(KIND_JOB_RESULT_BASE + (supportedKind - KIND_JOB_REQUEST_BASE));
         }
       }
     }
@@ -1270,6 +1303,9 @@ var DiscoveryService = class {
       ),
       this.enrichWithMetadata(agents)
     ]);
+    if (signal.aborted) {
+      return agents;
+    }
     const deliveredJobsByProvider = /* @__PURE__ */ new Map();
     for (const ev of resultEvents) {
       if (!verifyEvent(ev)) {
@@ -1282,7 +1318,7 @@ var DiscoveryService = class {
       if (ev.created_at > agent.lastSeen) {
         agent.lastSeen = ev.created_at;
       }
-      const jobEventId = ev.tags.find((t) => t[0] === "e")?.[1];
+      const jobEventId = ev.tags.find((tag) => tag[0] === "e")?.[1];
       if (jobEventId) {
         let delivered = deliveredJobsByProvider.get(ev.pubkey);
         if (!delivered) {
@@ -1296,7 +1332,7 @@ var DiscoveryService = class {
       if (!verifyEvent(ev)) {
         continue;
       }
-      const targetPubkey = ev.tags.find((t) => t[0] === "p")?.[1];
+      const targetPubkey = ev.tags.find((tag) => tag[0] === "p")?.[1];
       if (!targetPubkey) {
         continue;
       }
@@ -1307,17 +1343,17 @@ var DiscoveryService = class {
       if (ev.created_at > agent.lastSeen) {
         agent.lastSeen = ev.created_at;
       }
-      const rating = ev.tags.find((t) => t[0] === "rating")?.[1];
+      const rating = ev.tags.find((tag) => tag[0] === "rating")?.[1];
       if (rating === "1" || rating === "0") {
         agent.totalRatingCount = (agent.totalRatingCount ?? 0) + 1;
         if (rating === "1") {
           agent.positiveCount = (agent.positiveCount ?? 0) + 1;
         }
       }
-      const status = ev.tags.find((t) => t[0] === "status")?.[1];
-      const txTag = ev.tags.find((t) => t[0] === "tx");
+      const status = ev.tags.find((tag) => tag[0] === "status")?.[1];
+      const txTag = ev.tags.find((tag) => tag[0] === "tx");
       const txSignature = txTag?.[1];
-      const jobEventId = ev.tags.find((t) => t[0] === "e")?.[1];
+      const jobEventId = ev.tags.find((tag) => tag[0] === "e")?.[1];
       const hasDeliveredResult = jobEventId !== void 0 && deliveredJobsByProvider.get(targetPubkey)?.has(jobEventId) === true;
       if (status === "payment-completed" && typeof txSignature === "string" && txSignature && hasDeliveredResult) {
         if (!agent.lastPaidJobAt || ev.created_at > agent.lastPaidJobAt) {
@@ -1329,6 +1365,135 @@ var DiscoveryService = class {
     agents.sort(compareAgentsByRank);
     return agents;
   }
+  /**
+   * Stream elisym agents progressively as relays deliver events.
+   *
+   * Two live subscriptions:
+   *   - kind:31990 (capability cards) - emits `onAgent(agent)` for every new or
+   *     updated `(pubkey, d-tag)`. The emitted Agent is the merged view across
+   *     all surviving cards for that author.
+   *   - kind:6100 (default-offset job results) tagged `t=elisym` since 30d ago -
+   *     emits `onPaidJob(pubkey, ts)` for each delivered result. Custom-kind
+   *     results (offset != 100) are not on this stream; they enter the final
+   *     ranking via the post-EOSE enrichment pass.
+   *
+   * After capabilities EOSE, an enrichment pass runs in parallel to the live
+   * subscriptions and produces a ranked snapshot via `onComplete`. The snapshot
+   * is a clone, so further live updates do not mutate it.
+   *
+   * `closer.close()` tears down both subscriptions and aborts an in-flight
+   * enrichment. If `opts.signal` is provided, aborting it does the same.
+   */
+  streamAgents(network, opts) {
+    const eventsByPubkey = /* @__PURE__ */ new Map();
+    const agentByPubkey = /* @__PURE__ */ new Map();
+    const eoseSeen = { caps: false, results: false };
+    let enrichmentStarted = false;
+    const enrichmentAbort = new AbortController();
+    const onExternalAbort = () => enrichmentAbort.abort();
+    if (opts.signal) {
+      if (opts.signal.aborted) {
+        enrichmentAbort.abort();
+      } else {
+        opts.signal.addEventListener("abort", onExternalAbort, { once: true });
+      }
+    }
+    const checkEose = () => {
+      if (eoseSeen.caps && eoseSeen.results) {
+        opts.onEose?.();
+      }
+    };
+    const startEnrichment = () => {
+      if (enrichmentStarted) {
+        return;
+      }
+      enrichmentStarted = true;
+      const snapshotAgents = Array.from(agentByPubkey.values()).map((agent) => ({ ...agent }));
+      const snapshotMap = new Map(snapshotAgents.map((agent) => [agent.pubkey, agent]));
+      void this.runEnrichment(snapshotAgents, snapshotMap, enrichmentAbort.signal).then(
+        (sorted) => {
+          if (enrichmentAbort.signal.aborted) {
+            return;
+          }
+          opts.onComplete?.(sorted);
+        },
+        () => {
+        }
+      );
+    };
+    const capSub = this.pool.subscribe(
+      { kinds: [KIND_APP_HANDLER], "#t": ["elisym"] },
+      (event) => {
+        const dTag = event.tags.find((tag) => tag[0] === "d")?.[1] ?? "";
+        let perDTag = eventsByPubkey.get(event.pubkey);
+        const prev = perDTag?.get(dTag);
+        if (prev && event.created_at <= prev.created_at) {
+          return;
+        }
+        if (!verifyEvent(event)) {
+          return;
+        }
+        if (!event.content) {
+          return;
+        }
+        let payload;
+        try {
+          payload = JSON.parse(event.content);
+        } catch {
+          return;
+        }
+        const isTombstone = payload !== null && typeof payload === "object" && Boolean(payload.deleted);
+        if (!isTombstone && !parseCapabilityEvent(event, network)) {
+          return;
+        }
+        if (!perDTag) {
+          perDTag = /* @__PURE__ */ new Map();
+          eventsByPubkey.set(event.pubkey, perDTag);
+        }
+        perDTag.set(dTag, event);
+        const merged = buildAgentsFromEvents(Array.from(perDTag.values()), network).get(
+          event.pubkey
+        );
+        if (!merged) {
+          agentByPubkey.delete(event.pubkey);
+          return;
+        }
+        agentByPubkey.set(event.pubkey, merged);
+        opts.onAgent(merged);
+      },
+      {
+        oneose: () => {
+          eoseSeen.caps = true;
+          startEnrichment();
+          checkEose();
+        }
+      }
+    );
+    const activitySince = Math.floor(Date.now() / 1e3) - RANKING_ACTIVITY_WINDOW_SECS;
+    const resultsSub = this.pool.subscribe(
+      { kinds: [KIND_JOB_RESULT], "#t": ["elisym"], since: activitySince },
+      (event) => {
+        if (!verifyEvent(event)) {
+          return;
+        }
+        opts.onPaidJob?.(event.pubkey, event.created_at);
+      },
+      {
+        oneose: () => {
+          eoseSeen.results = true;
+          checkEose();
+        }
+      }
+    );
+    return {
+      close: (reason) => {
+        capSub.close(reason);
+        resultsSub.close(reason);
+        enrichmentAbort.abort();
+        opts.signal?.removeEventListener("abort", onExternalAbort);
+      }
+    };
+  }
   /**
    * Publish a capability card (kind:31990) as a provider.
    * Solana address is validated for Base58 format only - full decode
@@ -2544,8 +2709,11 @@ var NostrPool = class {
       throw new Error(`Failed to publish to all ${this.relays.length} relays`);
     }
   }
-  subscribe(filter, onEvent) {
-    const rawSub = this.pool.subscribeMany(this.relays, filter, { onevent: onEvent });
+  subscribe(filter, onEvent, opts) {
+    const rawSub = this.pool.subscribeMany(this.relays, filter, {
+      onevent: onEvent,
+      oneose: opts?.oneose
+    });
     const tracked = {
       close: (reason) => {
         this.activeSubscriptions.delete(tracked);