@formstr/mcp 0.7.2 → 0.8.0

package/AGENTS.md

@@ -247,8 +247,8 @@ types: `short`, `paragraph`, `choice`, `dropdown`, `number`, `date`, `time`, `gr
 
 | Tool | Required args | Notes |
 | --- | --- | --- |
-| `list_mail` | — | Inbox, newest first: `id`, sender, subject, date. |
-| `read_mail` | `mailId` | Full body of one message. |
+| `list_mail` | — | A page of the inbox, newest first. Page with `until`. |
+| `read_mail` | `mailId` | Full body of one message (fetched by id). |
 | `who_is_my_mail_address` | — | Signed-in identity, default `From:`, and aliases. |
 | `list_mail_aliases` | — | Every address the account can send as, and the default. |
 | `send_mail` ⚠ | `to` | `to` = npub/hex **or** external email. Gated. |
@@ -262,6 +262,12 @@ choose which alias appears in the `From:`; call `list_mail_aliases` first to see
 `raw`. For external email, the `From:` must be a registered alias (not the bare npub) or the
 bridge bounces it.
 
+**Paging a large inbox.** `list_mail` returns a bounded **page** (default 50, newest first) —
+it does not scan the whole mailbox. When the page is full the result includes `oldestReceivedAt`
+and `hasMore: true`; to read further back, call again with `until` set to that value. `since`
+and `until` are unix seconds. If you only need one message you already have the id for, call
+`read_mail` — it fetches that exact wrap and never depends on the page window.
+
 > **Claiming is two-step and human-driven.** `claim_mailbox` returns a bolt11 invoice. The
 > user pays it in their own wallet. Then the address starts working once NIP-05 propagates.
 > You **cannot** complete payment from here.

package/dist/index.js

@@ -33501,7 +33501,14 @@ async function collectInbox(recipient, opts, unwrap) {
   const filter = {
     kinds: [KIND_GIFTWRAP],
     "#p": [recipient],
-    limit: opts.limit ?? 100
+    limit: opts.limit ?? 100,
+    // Time-window paging. Both optional: absent `until` means "newest", absent
+    // `since` means "all the way back". Together they turn a potentially huge
+    // inbox scan into bounded pages (oldest receivedAt → next `until`).
+    ...opts.since !== void 0 ? { since: opts.since } : {},
+    ...opts.until !== void 0 ? { until: opts.until } : {},
+    // Exact lookup by id — no time window, for reading one known message.
+    ...opts.ids !== void 0 ? { ids: opts.ids } : {}
   };
   const wraps = opts.queryWraps ? await opts.queryWraps(filter) : await new SimplePool().querySync(relays, filter);
   const seen = /* @__PURE__ */ new Map();
@@ -33544,7 +33551,8 @@ async function readInboxWith(signer, opts = {}) {
     recipient,
     opts,
     (wrap) => unwrapMailWith(wrap, signer, {
-      maxAgeSeconds: opts.maxAgeSeconds,
+      // See readInbox: the inbox has no staleness bound by default.
+      maxAgeSeconds: opts.maxAgeSeconds ?? Infinity,
       acceptKinds: opts.acceptKinds,
       now: opts.now
     })
@@ -33777,7 +33785,7 @@ async function publishEverywhere(pool, relays, event) {
   };
 }
 
-// ../agent/dist/chunk-5L26ARX5.js
+// ../agent/dist/chunk-CCSELOJL.js
 var service_exports2 = {};
 __export3(service_exports2, {
   defaultSenderAddress: () => defaultSenderAddress,
@@ -33785,6 +33793,7 @@ __export3(service_exports2, {
   mailIdentity: () => mailIdentity,
   publishMailSetup: () => publishMailSetup,
   readMail: () => readMail,
+  readMailById: () => readMailById,
   requestMailbox: () => requestMailbox,
   sendMail: () => sendMail
 });
@@ -33811,11 +33820,27 @@ async function defaultSenderAddress() {
 }
 async function readMail(opts = {}) {
   const signer = await mailSigner();
+  const limit = opts.limit ?? 50;
   const { mail, failures } = await readInboxWith(signer, {
     relays: inboxRelays(),
-    ...opts.limit !== void 0 ? { limit: opts.limit } : {}
+    limit,
+    ...opts.since !== void 0 ? { since: opts.since } : {},
+    ...opts.until !== void 0 ? { until: opts.until } : {}
   });
-  return { mail, failures };
+  mail.sort((a, b) => b.receivedAt - a.receivedAt);
+  return {
+    mail,
+    failures,
+    oldestReceivedAt: mail.length ? mail[mail.length - 1].receivedAt : void 0,
+    // A full page means there are probably older messages to page to. We cannot
+    // know for certain without a second query; this is a cheap, honest hint.
+    hasMore: mail.length >= limit
+  };
+}
+async function readMailById(mailId) {
+  const signer = await mailSigner();
+  const { mail } = await readInboxWith(signer, { relays: inboxRelays(), ids: [mailId] });
+  return mail[0] ?? null;
 }
 async function sendMail(params) {
   const signer = await mailSigner();
@@ -44770,7 +44795,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// ../agent/dist/chunk-JORUNTXB.js
+// ../agent/dist/chunk-XHSE23RE.js
 function ok(text, data) {
   return data !== void 0 ? { ok: true, text, data } : { ok: true, text };
 }
@@ -45967,25 +45992,35 @@ function buildMailTools() {
   server.registerTool(
     "list_mail",
     {
-      description: "List the mail in your mailstr inbox (kind-1059 gift-wrapped email). Returns each message's id, sender, subject and date, newest first.",
-      inputSchema: { limit: external_exports.number().optional() }
+      description: "List a page of the mailstr inbox (kind-1059 gift-wrapped email), newest first. Returns each message's id, sender, subject and date. Pages are bounded (default 50); when the page is full the result carries `oldestReceivedAt` \u2014 pass it back as `until` to page further back. `since`/`until` are unix seconds; omitted `until` means newest.",
+      inputSchema: {
+        limit: external_exports.number().optional(),
+        since: external_exports.number().optional(),
+        until: external_exports.number().optional()
+      }
     },
-    async ({ limit }) => {
-      const { mail: messages, failures } = await service_exports2.readMail(
-        limit !== void 0 ? { limit } : {}
-      );
-      messages.sort((a, b) => b.receivedAt - a.receivedAt);
+    async ({ limit, since, until }) => {
+      const { mail: messages, failures, oldestReceivedAt, hasMore } = await service_exports2.readMail({
+        ...limit !== void 0 ? { limit } : {},
+        ...since !== void 0 ? { since } : {},
+        ...until !== void 0 ? { until } : {}
+      });
       const rows = messages.map((m) => ({
         id: m.wrapId,
         from: m.from,
         subject: m.subject,
         date: new Date(m.receivedAt * 1e3).toISOString()
       }));
-      let text = `${messages.length} message(s) in your inbox.`;
+      let text = `${messages.length} message(s) in this page of your inbox.`;
+      if (hasMore && oldestReceivedAt !== void 0) {
+        text += ` Older mail may exist \u2014 call list_mail again with until: ${oldestReceivedAt}.`;
+      }
       if (failures.length > 0) text += ` ${failures.length} wrap(s) could not be decoded.`;
       return ok(text, {
         mail: rows,
         count: messages.length,
+        oldestReceivedAt,
+        hasMore,
         failures
       });
     }
@@ -45997,8 +46032,7 @@ function buildMailTools() {
       inputSchema: { mailId: external_exports.string() }
     },
     async ({ mailId }) => {
-      const { mail: messages } = await service_exports2.readMail();
-      const msg = messages.find((m) => m.wrapId === mailId);
+      const msg = await service_exports2.readMailById(mailId);
       if (!msg) {
         return fail(
           `No message with id "${mailId}". Use list_mail to see the ids in your inbox.`,