@uuaid/pillar 0.2.0-alpha.7 → 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,
@@ -323,6 +325,10 @@ async function cmdRecv(args) {
       url:       process.env.PILLAR_ZESTRO_URL   ?? args["zestro-url"],
       token:     process.env.PILLAR_ZESTRO_TOKEN ?? args["zestro-token"],
       sessionId: process.env.PILLAR_ZESTRO_AGENT ?? args["zestro-agent"],
+      tabId:     process.env.PILLAR_ZESTRO_TAB   ?? args["zestro-tab"],
+      // Opt-in: force on a busy tab spawns a SECOND agent process resuming the
+      // same transcript (handle-spawn.js has no live-process guard). Default off.
+      force:     /^1|true|yes$/i.test(process.env.PILLAR_ZESTRO_FORCE ?? "") || !!args["zestro-force"],
     });
     await bridge.connect();
     // Never log the full URL — it embeds the auth token.
@@ -336,24 +342,36 @@ async function cmdRecv(args) {
     if (bridge && env.kind === "request") {
       // Interaction-convention return leg: ack FIRST — pillar-ask allows 120s
       // per phase but ZestroBridge times out at 30s, so the ack goes out before
-      // the bridged agent turn starts. Then reply with the turn's result text,
-      // or status:"pending" on bridge timeout (command queued, turn running),
-      // or status:"error" with the bridge failure as reason.
+      // the bridged agent turn starts. Reply statuses (verified against app code):
+      //   "ok"      = command_result received = renderer consumed / spawn initiated
+      //               (NOT turn-complete — the turn's answer returns via a separate
+      //               pillar send from the agent, if the prompt instructs one)
+      //   "busy"    = target tab busy, server rejected (fast, no 30s hang)
+      //   "pending" = bridge timeout — the request was never confirmed
+      //   "error"   = bridge failure
       const thread = env.payload?.thread ?? env.id;
       const senderKey = env.transportSignature.publicKey; // open() F1: sender derives from this key
       try {
         await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "ack", payload: { inReplyTo: env.id } });
         const result = await bridge.sendCommand({ command: JSON.stringify({ kind: env.kind, payload: env.payload, sender: env.sender }) });
-        const text = replyTextFromResult(result);
+        const hasText = result && typeof result === "object" &&
+          ["text", "result", "output", "response", "message"].some(k => k in result);
+        const text = hasText
+          ? replyTextFromResult(result)
+          : "zestro command_result received (server accepted) — agent turn answer, if any, returns via separate pillar send";
         await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "reply", payload: { thread, inReplyTo: env.id, status: "ok", text } });
         console.log(`  → zestro reply sent (${text.length} bytes)`);
       } catch (e) {
-        // command_result only arrives when the target agent's TURN completes —
-        // a busy agent (long turn) exceeds any sane timeout while the command
-        // is already queued in its tab. Timeout = accepted-unconfirmed, not failure.
-        if (/timed out/.test(e.message)) {
-          console.log(`  → zestro: queued (command_result pending — agent busy)`);
-          await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "reply", payload: { thread, inReplyTo: env.id, status: "pending", text: "request forwarded to zestro agent — turn still running" } });
+        // ZestroServerError SESSION_BUSY = server rejected: target tab busy and
+        // force off. Immediate distinct status — the sender can retry or drop.
+        if (e.code === "SESSION_BUSY") {
+          console.log(`  → zestro: busy (${e.message})`);
+          await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "reply", payload: { thread, inReplyTo: env.id, status: "busy", reason: e.message.slice(0, 300), text: `zestro agent busy: ${e.message.slice(0, 300)}` } });
+        } else if (/timed out/.test(e.message)) {
+          // Bridge timeout = the server never confirmed delivery (renderer drop,
+          // cli-server gone, etc.) — accepted-unconfirmed, not turn-running.
+          console.log(`  → zestro: unconfirmed (bridge timeout)`);
+          await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "reply", payload: { thread, inReplyTo: env.id, status: "pending", text: "request forwarded to zestro agent — delivery unconfirmed" } });
         } else {
           console.error(`  → zestro bridge error: ${e.message}`);
           await p.send({ recipient: env.sender, recipientPublicKey: senderKey, kind: "reply", payload: { thread, inReplyTo: env.id, status: "error", reason: e.message.slice(0, 300), text: `zestro bridge error: ${e.message.slice(0, 300)}` } });
@@ -364,8 +382,10 @@ async function cmdRecv(args) {
         const result = await bridge.sendCommand({ command: JSON.stringify({ kind: env.kind, payload: env.payload, sender: env.sender }) });
         console.log(`  → zestro result: ${JSON.stringify(result).slice(0, 200)}`);
       } catch (e) {
-        if (/timed out/.test(e.message)) {
-          console.log(`  → zestro: queued (command_result pending — agent busy)`);
+        if (e.code === "SESSION_BUSY") {
+          console.log(`  → zestro: busy (${e.message})`);
+        } else if (/timed out/.test(e.message)) {
+          console.log(`  → zestro: unconfirmed (bridge timeout)`);
         } else {
           console.error(`  → zestro bridge error: ${e.message}`);
         }
@@ -379,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();
@@ -398,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.7",
+  "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/bridges/zestro.mjs

@@ -1,21 +1,45 @@
 /**
  * Zestro WebSocket bridge.
  *
- * Wire protocol (from ZZ's Mac audit):
+ * Wire protocol — verified against the OFFICIAL client contract
+ * (Zestro app.asar: dist/cli/maestro-client.ts, sourcesContent from
+ * maestro-cli.js.map) and the app's own server/renderer handlers:
  *   ws://127.0.0.1:53522/<token>/ws
- *   -> { type: "send_command", id: <uuid>, sessionId: <agentId>, command: <str>, inputMode: "ai" }
- *   <- { type: "command_result", id: <uuid>, ... }
+ *   -> { type: "send_command", requestId: "req_...", sessionId: <agentId>,
+ *        command: <str>, inputMode: "ai", tabId?: <uuid>, force?: true }
+ *   <- { type: "command_result", success, sessionId, tabId?, requestId }  // echoes requestId
+ *   <- { type: "error", message, sessionId }                              // NO requestId echo
+ *
+ * Correlation is on `requestId`, NOT `id` — the server echoes only
+ * `requestId`, so a client correlating on `id` can never match a reply.
+ *
+ * Semantics (verified in app code, all four layers):
+ * - command_result arrives IMMEDIATELY after the renderer receives the
+ *   command — it means "consumed by the renderer / spawn initiated", NOT
+ *   "the agent's turn completed". The turn answer returns out-of-band.
+ * - A busy target session WITHOUT force is rejected by the server
+ *   ({type:"error"}), and the renderer has TWO more busy drops of its own.
+ *   Errors carry no requestId, so they must be handled single-flight.
+ * - force=true on a BUSY tab spawns a SECOND agent process resuming the
+ *   same session transcript (handle-spawn.js: no live-process guard,
+ *   --resume <agentSessionId>). Concurrent, not queued. Opt-in only.
  *
  * Token lives in ~/Library/Application Support/zestro/cli-server.json.
  * Agent id for ZZ was verified to be 7fbce535-3a2f-4e6b-96e6-64926403efa5.
- *
- * Correlation on `id` so multiple concurrent sends don't race.
  */
 import { WebSocket } from "ws";
-import { randomUUID } from "node:crypto";
+
+/** Server rejected the command (busy session, bad payload, ...). */
+export class ZestroServerError extends Error {
+  constructor(message, code = "ZESTRO_SERVER_ERROR") {
+    super(message);
+    this.name = "ZestroServerError";
+    this.code = code;
+  }
+}
 
 export class ZestroBridge {
-  constructor({ url, token, sessionId, timeoutMs = 30000 }) {
+  constructor({ url, token, sessionId, tabId, timeoutMs = 30000, force = false }) {
     if (!url || !token || !sessionId) {
       throw new Error("ZestroBridge requires { url, token, sessionId }");
     }
@@ -26,7 +50,9 @@ export class ZestroBridge {
     }
     this.url = url;
     this.sessionId = sessionId;
+    this.tabId = tabId ?? null;
     this.timeoutMs = timeoutMs;
+    this.force = force;
     this._ws = null;
     this._pending = new Map();
   }
@@ -44,35 +70,81 @@ export class ZestroBridge {
       ws.on("message", (buf) => {
         let msg;
         try { msg = JSON.parse(buf.toString()); } catch { return; }
-        if (msg.type === "command_result" && msg.id && this._pending.has(msg.id)) {
-          const p = this._pending.get(msg.id);
-          this._pending.delete(msg.id);
-          p.resolve(msg);
+
+        // `echo` = the app did not recognize the message type (older build).
+        if (msg.type === "echo") {
+          const original = msg.data ?? {};
+          const reqId = original.requestId ?? msg.originalRequestId;
+          if (reqId && this._pending.has(reqId)) {
+            this._settle(reqId, p => p.reject(new ZestroServerError(
+              `Zestro app does not support '${original.type ?? "unknown"}' (older build?)`,
+              "ZESTRO_UNSUPPORTED"
+            )));
+          }
+          return;
+        }
+
+        // Exact correlation: server echoes requestId on command_result.
+        if (msg.requestId && this._pending.has(msg.requestId)) {
+          this._settle(msg.requestId, p => p.resolve(msg));
+          return;
+        }
+
+        // Single-flight: server `error` replies carry NO requestId (verified:
+        // sendError sends {type:'error', message, ...extra}). The bridge keeps
+        // at most one request in flight, so route orphan replies to it.
+        if (msg.type === "error") {
+          const message = msg.message ?? "zestro server error";
+          const code = /busy/i.test(message) ? "SESSION_BUSY" : "ZESTRO_SERVER_ERROR";
+          this._settleOldest(p => p.reject(new ZestroServerError(message, code)));
+          return;
+        }
+        if (msg.type === "command_result") {
+          this._settleOldest(p => p.resolve(msg));
         }
       });
     });
   }
 
-  sendCommand({ command, inputMode = "ai" }) {
+  _settle(requestId, fn) {
+    const p = this._pending.get(requestId);
+    if (p) {
+      this._pending.delete(requestId);
+      fn(p);
+    }
+  }
+
+  _settleOldest(fn) {
+    const first = this._pending.entries().next();
+    if (!first.done) {
+      const [requestId, p] = first.value;
+      this._pending.delete(requestId);
+      fn(p);
+    }
+  }
+
+  sendCommand({ command, inputMode = "ai", force } = {}) {
     if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
       return Promise.reject(new Error("zestro bridge not connected"));
     }
-    const id = randomUUID();
+    const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
-        this._pending.delete(id);
-        reject(new Error(`zestro send_command ${id} timed out after ${this.timeoutMs}ms`));
+        this._pending.delete(requestId);
+        reject(new Error(`zestro send_command ${requestId} timed out after ${this.timeoutMs}ms`));
       }, this.timeoutMs);
-      this._pending.set(id, {
+      this._pending.set(requestId, {
         resolve: (msg) => { clearTimeout(timer); resolve(msg); },
         reject:  (e)   => { clearTimeout(timer); reject(e); },
       });
       this._ws.send(JSON.stringify({
         type: "send_command",
-        id,
+        requestId,
         sessionId: this.sessionId,
         command,
         inputMode,
+        ...(this.tabId ? { tabId: this.tabId } : {}),
+        ...((force ?? this.force) ? { force: true } : {}),
       }));
     });
   }

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");