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

package/bin/pillar.mjs

@@ -323,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.
@@ -336,24 +340,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 +380,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}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uuaid/pillar",
-  "version": "0.2.0-alpha.7",
+  "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",

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