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

package/bin/pillar.mjs

@@ -3,6 +3,7 @@
  * pillar — one-command CLI.
  *
  *   pillar init  [--home ~/.pillar]              first-time setup: mint UUAID + keys
+ *   pillar init --refresh [--directory URL]      re-sync carriers + address book (keychain untouched)
  *   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
@@ -89,9 +90,77 @@ function writeRuntimeFile(pillar, home) {
   writeFileSync(join(home, "runtime.json"), JSON.stringify(rt, null, 2));
 }
 
+// Carrier list + address book merge from a fetched directory — shared by
+// `init --directory` (first contact) and `init --refresh` (re-sync without
+// touching the keychain).
+function carriersFromDirectory(d) {
+  return [d.carrier, ...(Array.isArray(d.seeds) ? d.seeds.map((s) => s.url) : [])].filter(Boolean);
+}
+
+function mergeDirectoryAgents(home, d) {
+  if (!Array.isArray(d.agents)) return null;
+  const fleetPath = join(home, "fleet.json");
+  const prev = existsSync(fleetPath) ? JSON.parse(readFileSync(fleetPath, "utf-8")).fleet ?? {} : {};
+  const fleet = { ...prev };
+  let added = 0;
+  for (const a of d.agents) {
+    if (!a.uuaid || !a.publicKey) continue;
+    const key = typeof a.role === "string" && a.role ? a.role : a.uuaid;
+    fleet[key] = {
+      uuaid: a.uuaid,
+      publicKey: a.publicKey,
+      ...(prev[key]?.addrs ? { addrs: prev[key].addrs } : {}),
+      ...(prev[key]?.peerId ? { peerId: prev[key].peerId } : {}),
+    };
+    if (!prev[key]) added++;
+  }
+  writeFileSync(fleetPath, JSON.stringify({ fleet }, null, 2));
+  return { count: Object.keys(fleet).length, added };
+}
+
+async function fetchDirectory(url) {
+  const res = await fetch(url);
+  if (!res.ok) {
+    console.error(`directory fetch failed: ${url} -> ${res.status}`);
+    exit(1);
+  }
+  return res.json();
+}
+
 async function cmdInit(args) {
   const home = homePath(args);
   mkdirSync(home, { recursive: true });
+
+  // --refresh re-syncs carriers + address book from a directory WITHOUT
+  // touching the keychain (init --force would mint a NEW identity and break
+  // every enrolled sender).  Requires an existing identity.
+  if (args.refresh) {
+    const kcPath = join(home, "keychain.json");
+    if (!existsSync(kcPath)) {
+      console.error(`refresh: no keychain at ${kcPath} — run pillar init first (refresh never mints keys)`);
+      exit(1);
+    }
+    if (typeof args.directory !== "string") {
+      console.error("refresh: --directory <url> is required");
+      exit(1);
+    }
+    const d = await fetchDirectory(args.directory);
+    const list = carriersFromDirectory(d);
+    if (!list.length) {
+      console.error(`refresh: directory ${args.directory} lists no carrier and no seeds`);
+      exit(1);
+    }
+    const cfgPath = join(home, "config.json");
+    const cfg = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, "utf-8")) : {};
+    cfg.carriers = list;
+    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2));
+    console.log(`carriers refreshed from ${args.directory}: ${list.join(", ")}`);
+    const ab = mergeDirectoryAgents(home, d);
+    if (ab) console.log(`address book: ${ab.count} peers in ${join(home, "fleet.json")} (${ab.added} new from directory)`);
+    console.log(`refresh complete at ${home} (keychain untouched)`);
+    return;
+  }
+
   const kcPath = join(home, "keychain.json");
   if (existsSync(kcPath) && !args.force) {
     console.error(`keychain already exists at ${kcPath}. use --force to overwrite.`);
@@ -110,13 +179,8 @@ async function cmdInit(args) {
   // the primary carrier plus every seeds[] entry as carriers (the LimeWire
   // seed model — poll all, replicate to all); --carriers sets them directly.
   if (typeof args.directory === "string") {
-    const res = await fetch(args.directory);
-    if (!res.ok) {
-      console.error(`init: directory fetch failed: ${args.directory} -> ${res.status}`);
-      exit(1);
-    }
-    const d = await res.json();
-    const list = [d.carrier, ...(Array.isArray(d.seeds) ? d.seeds.map(s => s.url) : [])].filter(Boolean);
+    const d = await fetchDirectory(args.directory);
+    const list = carriersFromDirectory(d);
     if (!list.length) {
       console.error(`init: directory ${args.directory} lists no carrier and no seeds`);
       exit(1);
@@ -126,25 +190,8 @@ async function cmdInit(args) {
     // Seed the address book from the directory's agents[] so a fresh agent can
     // `pillar ask`/`pillar send` with zero key plumbing (keys required for E2E).
     // Merge — never clobber a hand-curated fleet.json.
-    if (Array.isArray(d.agents)) {
-      const fleetPath = join(home, "fleet.json");
-      const prev = existsSync(fleetPath) ? JSON.parse(readFileSync(fleetPath, "utf-8")).fleet ?? {} : {};
-      const fleet = { ...prev };
-      let added = 0;
-      for (const a of d.agents) {
-        if (!a.uuaid || !a.publicKey) continue;
-        const key = typeof a.role === "string" && a.role ? a.role : a.uuaid;
-        fleet[key] = {
-          uuaid: a.uuaid,
-          publicKey: a.publicKey,
-          ...(prev[key]?.addrs ? { addrs: prev[key].addrs } : {}),
-          ...(prev[key]?.peerId ? { peerId: prev[key].peerId } : {}),
-        };
-        if (!prev[key]) added++;
-      }
-      writeFileSync(fleetPath, JSON.stringify({ fleet }, null, 2));
-      console.log(`address book: ${Object.keys(fleet).length} peers in ${fleetPath} (${added} new from directory)`);
-    }
+    const ab = mergeDirectoryAgents(home, d);
+    if (ab) console.log(`address book: ${ab.count} peers in ${join(home, "fleet.json")} (${ab.added} new from directory)`);
   } else if (args.carriers) {
     cfg.carriers = args.carriers.split(",").map(s => s.trim()).filter(Boolean);
   }
@@ -238,6 +285,19 @@ async function cmdGroups(args) {
   }
 }
 
+// Extract human-readable text from a zestro command_result. The server-side
+// payload fields are unverified — defensively try the common shapes, cap at
+// 8192 bytes (pillar-responder's MAX_REPLY_BYTES convention).
+function replyTextFromResult(result) {
+  const text = result?.text ?? result?.result ?? result?.output ?? result?.response ?? result?.message;
+  if (typeof text === "string" && text.trim()) return text.slice(0, 8192);
+  if (typeof text !== "string" && text !== undefined && text !== null) {
+    const s = JSON.stringify(text);
+    if (s) return s.slice(0, 8192);
+  }
+  return JSON.stringify(result ?? {}).slice(0, 8192);
+}
+
 async function cmdRecv(args) {
   const p = loadPillar(args);
   await p.start();
@@ -263,6 +323,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.
@@ -273,16 +337,53 @@ async function cmdRecv(args) {
     const line = { at: new Date().toISOString(), from: env.sender, kind: env.kind, payload: env.payload };
     if (env.payload?._group?.name) line.group = env.payload._group.name;
     console.log(JSON.stringify(line));
-    if (bridge) {
+    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. 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 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) {
+        // 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)}` } });
+        }
+      }
+    } else if (bridge) {
       try {
         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) {
-        // 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)`);
+        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}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuaid/pillar",
-  "version": "0.2.0-alpha.6",
+  "version": "0.2.0-alpha.8",
   "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",
@@ -56,4 +56,4 @@
     "uint8arrays": "^5.1.1",
     "ws": "^8.21.3"
   }
-}
+}

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 } : {}),
       }));
     });
   }