@uuaid/pillar 0.2.0-alpha.8 → 0.2.0-alpha.9

package/README.md

@@ -31,6 +31,19 @@ pillar id
 pillar ask <their-uuaid> "<your question>"
 ```
 
+Check your mail any time — `pillar-ask` never drains your inbox, so replies
+and messages queue at the carrier until you pull them:
+
+```sh
+pillar inbox            # one-shot: fetch pending envelopes, print, exit
+pillar inbox --unread   # also print older stored-but-never-shown envelopes
+pillar inbox --notify 'osascript -e "display notification ..."'  # hook when mail waits
+```
+
+For automated checking, put `pillar inbox --notify <cmd>` on a cron/launchd
+interval — the hook gets `PILLAR_NEW` / `PILLAR_UNREAD` / `PILLAR_UUAID` env
+vars and a JSON summary on stdin, and only fires when there is mail.
+
 `--directory` fetches the directory and configures every carrier + seed listed
 there, and writes every `agents[]` entry (uuaid + publicKey) into
 `<home>/fleet.json` as your address book — so step 3 works immediately, no key
@@ -44,7 +57,7 @@ to build a private mesh.
 |---|---|---|
 | `pillar-responder` | Always-on auto-attendant: acks requests instantly, replies from fixed text or a command hook. Run it as a service; agents anywhere get ack+reply without you being live. | one process, outbound HTTPS |
 | `pillar-seed` | A carrier seed — makes you part of the p2p mesh. Any agent that lists your URL replicates every envelope to you and polls you in parallel with other seeds. | one process, one SQLite file, TLS-terminating proxy in front |
-| `pillar` | The full CLI (`init`, `id`, `send`, `send-group`, `recv`, `peers`) — optional libp2p DHT, or carrier-only. | only when used interactively |
+| `pillar` | The full CLI (`init`, `id`, `send`, `send-group`, `recv`, `inbox`, `peers`) — optional libp2p DHT, or carrier-only. | only when used interactively |
 
 ```sh
 pillar-responder --home ~/.pillar-responder --reply-text "ack" &

package/bin/pillar.mjs

@@ -7,6 +7,8 @@
  *   pillar id    [--home ~/.pillar]              print our UUAID + PeerId + addrs
  *   pillar send  <recipient> <kind> <json>       send a signed envelope
  *   pillar recv  [--home ~/.pillar] [--follow]   listen for envelopes and print them
+ *   pillar inbox [--home ~/.pillar] [--unread] [--notify CMD] [--mark-read]
+ *                                                one-shot: pull pending mail, print, exit
  *   pillar peers                                 list currently connected peers
  *
  * All commands respect --home to point at an alternate pillar directory,
@@ -397,6 +399,52 @@ async function cmdRecv(args) {
   await new Promise(() => {});
 }
 
+async function cmdInbox(args) {
+  // One-shot mail check for ANY identity: point --home at the pillar dir that
+  // minted the uuaid.  Pulls pending envelopes from the carrier (no long-poll),
+  // prints them decrypted, reports unread backlog, exits.  --notify CMD runs a
+  // shell hook when there is mail (cron/launchd-friendly); --mark-read stamps
+  // read_at on everything printed.
+  args["carrier-only"] = true; // inbox check needs the carrier only — no libp2p listener
+  const p = loadPillar(args);
+  const fresh = [];
+  p.onEnvelope((env) => { fresh.push(env); });
+  await p.start();
+  const pulled = await p.drainCarrierInbox();
+  for (const env of fresh) {
+    console.log(JSON.stringify({ new: true, id: env.id, from: env.sender, kind: env.kind, at: env.createdAt, payload: env.payload }));
+  }
+  // Backlog: rows stored earlier (e.g. by a recv daemon) but never surfaced.
+  const { decrypt } = await import("../src/net/envelope.mjs");
+  const freshIds = new Set(fresh.map(e => e.id));
+  const backlog = (p.mailbox.inboxUnread?.(500) ?? []).filter(r => !freshIds.has(r.envelope_id));
+  if (args.unread) {
+    for (const row of backlog) {
+      const env = JSON.parse(row.envelope_json);
+      let payload = null;
+      try { payload = decrypt(p.keychain, env); } catch (_e) { payload = { error: "decrypt failed" }; }
+      console.log(JSON.stringify({ new: false, id: env.id, from: env.sender, kind: env.kind, at: env.createdAt, payload }));
+    }
+  }
+  console.log(`inbox: ${pulled} new, ${backlog.length} older unread${args.unread ? "" : " (--unread to print)"}`);
+  if (args["mark-read"]) {
+    for (const env of fresh) p.mailbox.markInboxRead?.(env.id);
+    if (args.unread) for (const row of backlog) p.mailbox.markInboxRead?.(row.envelope_id);
+  }
+  if (args.notify && typeof args.notify === "string" && (pulled > 0 || backlog.length > 0)) {
+    const { spawnSync } = await import("node:child_process");
+    const r = spawnSync(args.notify, {
+      shell: true,
+      input: JSON.stringify({ uuaid: p.uuaid, new: pulled, unread: backlog.length }) + "\n",
+      env: { ...process.env, PILLAR_NEW: String(pulled), PILLAR_UNREAD: String(backlog.length), PILLAR_UUAID: p.uuaid },
+      stdio: ["pipe", "inherit", "inherit"],
+    });
+    if (r.status !== 0) console.error(`notify hook exited ${r.status}`);
+  }
+  await p.stop();
+  exit(0);
+}
+
 async function cmdPeers(args) {
   const p = loadPillar(args);
   await p.start();
@@ -416,9 +464,10 @@ async function main() {
     case "send-group": return cmdSendGroup(args);
     case "groups": return cmdGroups(args);
     case "recv":  return cmdRecv(args);
+    case "inbox": return cmdInbox(args);
     case "peers": return cmdPeers(args);
     default:
-      console.error(`usage: pillar <init|id|send|send-group|groups|recv|peers> [--home DIR]`);
+      console.error(`usage: pillar <init|id|send|send-group|groups|recv|inbox|peers> [--home DIR]`);
       exit(2);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuaid/pillar",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.0-alpha.9",
   "description": "IAASO-3050 reference implementation. Every agent runs its own PDP pillar, discovers peers via a Kademlia DHT, and exchanges cryptographically signed + Noise-encrypted messages over libp2p. One command to install and join the network.",
   "license": "Apache-2.0",
   "type": "module",

package/src/mailbox/mailbox.mjs

@@ -155,6 +155,16 @@ export class Mailbox {
     return this.db.prepare("select * from inbox where seq > ? order by seq asc limit ?").all(seq, limit);
   }
 
+  /** Envelopes never shown to the operator (read_at null). Oldest first. */
+  inboxUnread(limit = 100) {
+    return this.db.prepare("select * from inbox where read_at is null order by seq asc limit ?").all(limit);
+  }
+
+  markInboxRead(envelopeId) {
+    this.db.prepare("update inbox set read_at = ? where envelope_id = ? and read_at is null")
+      .run(new Date().toISOString(), envelopeId);
+  }
+
   /**
    * Recompute the outbox chain from scratch and compare to stored chain_hash column.
    * Returns { ok, badSeq? }.  Used by adversarial tests + operator-driven audits.

package/src/pillar.mjs

@@ -338,6 +338,32 @@ export class Pillar {
     if (this._carrierPoller) { this._carrierPoller.stop(); this._carrierPoller = null; }
   }
 
+  /**
+   * One-shot inbox pull: fetch every pending envelope from every carrier
+   * (no long-poll) through the same verification + mailbox + handler
+   * pipeline, then return.  Complements startCarrierPolling for CLI /
+   * cron-style "check my mail now" callers.  Returns envelopes fetched.
+   */
+  async drainCarrierInbox() {
+    if (!this.carrierClient) return 0;
+    let total = 0;
+    const cursors = this.mailbox.getCarrierCursors?.() ?? {};
+    for (const base of this.carriers) {
+      let since = cursors[base] ?? 0;
+      for (;;) { // carrier pages at 200/fetch — loop until an empty page
+        const r = await this.carrierClient.fetchInbox(base, { since, waitS: 0 });
+        if (!r.envelopes.length) break;
+        for (const { seq, envelope } of r.envelopes) {
+          await this._receive(JSON.stringify(envelope), null);
+          this.mailbox.setCarrierCursor?.(base, seq);
+          since = Math.max(since, seq);
+          total++;
+        }
+      }
+    }
+    return total;
+  }
+
   async _deliverToPeer(envelope, peerIdStr, multiaddrStr) {
     const { peerIdFromString } = await import("@libp2p/peer-id");
     const { multiaddr } = await import("@multiformats/multiaddr");