@uuaid/pillar 0.2.0-alpha.10

package/bin/pillar.mjs

@@ -0,0 +1,479 @@
+#!/usr/bin/env node
+/**
+ * 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
+ *   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,
+ * useful for running multiple pillars on one machine (Zestro dogfood etc.).
+ */
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { argv, exit } from "node:process";
+import { Keychain } from "../src/identity/keychain.mjs";
+import { Pillar } from "../src/pillar.mjs";
+import { loadFleetAddressBook } from "../src/address-book.mjs";
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, ...rest] = a.slice(2).split("=");
+      args[k] = rest.length ? rest.join("=") : (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : true);
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function homePath(args) {
+  return args.home || process.env.PILLAR_HOME || join(homedir(), ".pillar");
+}
+
+// Address book default: <home>/fleet.json unless --fleet points elsewhere.
+function fleetPath(args) {
+  return args.fleet || join(homePath(args), "fleet.json");
+}
+
+function loadPillar(args) {
+  const home = homePath(args);
+  const kcPath = join(home, "keychain.json");
+  const mbPath = join(home, "mailbox.db");
+  const cfgPath = join(home, "config.json");
+  if (!existsSync(kcPath)) {
+    console.error(`no pillar found at ${home}. run: pillar init`);
+    exit(2);
+  }
+  const cfg = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, "utf-8")) : {};
+  const kc = new Keychain(kcPath);
+  kc.load({ passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  const carriers = args.carrier
+    ? [args.carrier]
+    : (process.env.PILLAR_CARRIERS ? process.env.PILLAR_CARRIERS.split(",") : (cfg.carriers ?? []));
+  return new Pillar({
+    keychain: kc,
+    mailboxPath: mbPath,
+    listenAddrs: cfg.listenAddrs ?? ["/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/tcp/0/ws"],
+    bootstrapPeers: cfg.bootstrapPeers ?? [],
+    enableRelay: cfg.enableRelay ?? false,
+    dhtClientMode: cfg.dhtClientMode ?? true,
+    carriers,
+    enableLibp2p: !(args["carrier-only"] || cfg.carrierOnly === true),
+  });
+}
+
+function loadGroups(args) {
+  // groups.json lives next to fleet.json by default:
+  // { "groups": { "<name>": { "members": ["uuaid:...", ...] } } }
+  const p = args.groups || (args.fleet ? join(dirname(args.fleet), "groups.json") : null);
+  if (!p || !existsSync(p)) return { path: p, groups: {} };
+  return { path: p, groups: JSON.parse(readFileSync(p, "utf-8")).groups ?? {} };
+}
+
+function writeRuntimeFile(pillar, home) {
+  if (!pillar.node) return;
+  const rt = {
+    uuaid: pillar.uuaid,
+    peerId: pillar.node.peerId.toString(),
+    addrs: pillar.node.getMultiaddrs().map(a => a.toString()),
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+  };
+  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.`);
+    exit(1);
+  }
+  const kc = new Keychain(kcPath);
+  const id = Keychain.generate();
+  kc.save(id, { passphrase: process.env.PILLAR_PASSPHRASE ?? "" });
+  const cfg = {
+    listenAddrs: ["/ip4/0.0.0.0/tcp/0", "/ip4/0.0.0.0/tcp/0/ws"],
+    bootstrapPeers: [],
+    enableRelay: false,
+    dhtClientMode: true,
+  };
+  // P2P seed discovery: --directory fetches a pillar directory.json and wires
+  // 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 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);
+    }
+    cfg.carriers = list;
+    console.log(`carriers from directory (${args.directory}): ${list.join(", ")}`);
+    // 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.
+    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);
+  }
+  writeFileSync(join(home, "config.json"), JSON.stringify(cfg, null, 2));
+  console.log(`initialized pillar at ${home}`);
+  console.log(`uuaid: ${id.uuaid}`);
+  console.log(`publicKey: ${id.publicKeyHex}`);
+  console.log(`\nconfig: ${join(home, "config.json")}`);
+  console.log(`edit bootstrapPeers to join a network, or run again with --directory <url> / --carriers a,b to wire seeds.`);
+}
+
+async function cmdId(args) {
+  const p = loadPillar(args);
+  await p.start();
+  console.log(`uuaid:     ${p.uuaid}`);
+  console.log(`publicKey: ${p.publicKeyHex}`);
+  if (p.node) {
+    console.log(`peerId:    ${p.node.peerId.toString()}`);
+    console.log(`addrs:`);
+    for (const a of p.node.getMultiaddrs()) console.log(`  ${a.toString()}`);
+  } else {
+    console.log(`mode:      carrier-only (no libp2p)`);
+  }
+  if (p.carriers?.length) console.log(`carriers:  ${p.carriers.join(", ")}`);
+  await p.stop();
+}
+
+async function cmdSend(args) {
+  const [recipient, kind, jsonStr] = args._.slice(1);
+  if (!recipient || !kind) {
+    console.error("usage: pillar send <recipient-uuaid> <kind> [json-payload] [--fleet FLEET.json]");
+    exit(2);
+  }
+  const payload = jsonStr ? JSON.parse(jsonStr) : {};
+  const p = loadPillar(args);
+  await p.start();
+  const n = loadFleetAddressBook(fleetPath(args), p);
+  if (n > 0) console.log(`address book: ${n} peers`);
+  try {
+    const { envelope, delivery } = await p.send({
+      recipient, kind, payload,
+      recipientPublicKey: args["to-pubkey"],  // explicit key for peers outside fleet.json
+      resolveTimeoutMs: 5000,
+    });
+    console.log(`sent envelope ${envelope.id}`);
+    console.log(`  to:   ${recipient}`);
+    console.log(`  kind: ${kind}`);
+    if (delivery?.peerId) console.log(`  via peerId: ${delivery.peerId}`);
+  } finally {
+    await p.stop();
+  }
+}
+
+async function cmdSendGroup(args) {
+  const [groupName, kind, jsonStr] = args._.slice(1);
+  if (!groupName || !kind) {
+    console.error("usage: pillar send-group <group> <kind> [json-payload] --fleet FLEET.json [--groups GROUPS.json]");
+    exit(2);
+  }
+  const { path: gPath, groups } = loadGroups(args);
+  const group = groups[groupName];
+  if (!group?.members?.length) {
+    console.error(`group "${groupName}" not found or empty (looked in ${gPath ?? "no groups file"})`);
+    exit(2);
+  }
+  const payload = jsonStr ? JSON.parse(jsonStr) : {};
+  const p = loadPillar(args);
+  await p.start();
+  loadFleetAddressBook(fleetPath(args), p);
+  try {
+    const { results } = await p.sendGroup({ group: groupName, members: group.members, kind, payload });
+    let failed = 0;
+    for (const r of results) {
+      if (r.ok) console.log(`  ✓ ${r.member}  via ${r.via}  ${r.envelopeId}`);
+      else { failed++; console.error(`  ✗ ${r.member}  ${r.error}`); }
+    }
+    console.log(`group "${groupName}": ${results.length - failed}/${results.length} delivered`);
+    if (failed) exit(1);
+  } finally {
+    await p.stop();
+  }
+}
+
+async function cmdGroups(args) {
+  const { path: gPath, groups } = loadGroups(args);
+  const names = Object.keys(groups);
+  if (!names.length) { console.log(`no groups defined (${gPath ?? "no groups file"})`); return; }
+  for (const n of names) {
+    console.log(`${n} (${groups[n].members.length} members):`);
+    for (const m of groups[n].members) console.log(`  ${m}`);
+  }
+}
+
+// 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();
+  writeRuntimeFile(p, homePath(args)); // warm handoff: publish live addr for senders
+  const n = loadFleetAddressBook(fleetPath(args), p);
+  console.log(`listening as ${p.uuaid}`);
+  if (p.node) {
+    console.log(`peerId ${p.node.peerId.toString()}`);
+    for (const a of p.node.getMultiaddrs()) console.log(`  ${a.toString()}`);
+  } else {
+    console.log(`(carrier-only mode: no libp2p listener)`);
+  }
+  if (p.carrierClient) {
+    p.startCarrierPolling();
+    console.log(`polling carriers: ${p.carriers.join(", ")}`);
+  }
+  if (n > 0) console.log(`address book: ${n} peers from ${fleetPath(args)}`);
+
+  let bridge = null;
+  if (args["zestro-bridge"] || process.env.PILLAR_ZESTRO_URL) {
+    const { ZestroBridge } = await import("../src/bridges/zestro.mjs");
+    bridge = new ZestroBridge({
+      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.
+    console.log(`zestro bridge connected to ${bridge.url.replace(/\/[0-9a-f-]{36}\/ws$/, "/<token>/ws")}`);
+  }
+
+  p.onEnvelope(async (env) => {
+    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 && 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 && env.kind !== "ack" && env.kind !== "reply") {
+      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) {
+        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}`);
+        }
+      }
+    } else if (bridge) {
+      // ack/reply are receipts for OUR earlier sends — bridging them would
+      // inject a Zestro agent turn per receipt. Print-only (line above).
+      console.log(`  → zestro: not bridged (kind=${env.kind} is a receipt)`);
+    }
+  });
+
+  const shutdown = async () => { if (bridge) bridge.close(); await p.stop(); exit(0); };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  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();
+  const peers = p.node.getPeers();
+  console.log(`${peers.length} connected peers:`);
+  for (const peer of peers) console.log(`  ${peer.toString()}`);
+  await p.stop();
+}
+
+async function main() {
+  const args = parseArgs(argv.slice(2));
+  const cmd = args._[0];
+  switch (cmd) {
+    case "init":  return cmdInit(args);
+    case "id":    return cmdId(args);
+    case "send":  return cmdSend(args);
+    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|inbox|peers> [--home DIR]`);
+      exit(2);
+  }
+}
+
+main().catch(e => { console.error(e); exit(1); });

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@uuaid/pillar",
+  "version": "0.2.0-alpha.10",
+  "description": "Pillar (Protocol for Inter-agent Linked Ledger And Relay) — the secure delivery layer of UACP, the Universal Agent Communication Protocol. UACP = UUAID (identity) + Envelope (signed, encrypted container) + Pillar (relay, mailbox, routing, store-and-forward). IAASO-3050 reference implementation: one command to mint an identity and join the network.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "src/index.mjs",
+  "bin": {
+    "pillar": "bin/pillar.mjs",
+    "pillar-carrier": "bin/carrier.mjs",
+    "pillar-ask": "bin/pillar-ask.mjs",
+    "pillar-responder": "bin/pillar-responder.mjs",
+    "pillar-seed": "bin/pillar-seed.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "INTERACTION-CONVENTION.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --test-reporter spec test/unit/*.test.mjs",
+    "test:int": "node --test --test-reporter spec test/integration/*.test.mjs",
+    "test:chaos": "node --test --test-reporter spec test/chaos/*.test.mjs",
+    "test:all": "node --test --test-reporter spec test/unit/*.test.mjs test/integration/*.test.mjs test/chaos/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@chainsafe/libp2p-noise": "^17.0.0",
+    "@chainsafe/libp2p-yamux": "^8.0.1",
+    "@libp2p/autonat": "^3.0.26",
+    "@libp2p/bootstrap": "^12.0.29",
+    "@libp2p/circuit-relay-v2": "^4.2.11",
+    "@libp2p/crypto": "^5.1.22",
+    "@libp2p/dcutr": "^3.0.26",
+    "@libp2p/identify": "^4.1.12",
+    "@libp2p/kad-dht": "^16.4.3",
+    "@libp2p/peer-id": "^6.0.14",
+    "@libp2p/ping": "^3.1.11",
+    "@libp2p/tcp": "^11.0.26",
+    "@libp2p/webrtc": "^6.0.29",
+    "@libp2p/websockets": "^10.1.19",
+    "@multiformats/multiaddr": "^13.0.3",
+    "@noble/curves": "^2.3.0",
+    "better-sqlite3": "^11.10.0",
+    "it-pipe": "^3.0.1",
+    "it-pushable": "^3.2.4",
+    "libp2p": "^3.3.8",
+    "multiformats": "^14.0.5",
+    "uint8arrays": "^5.1.1",
+    "ws": "^8.21.3"
+  }
+}

package/src/address-book.mjs

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * Load a fleet.json address book into a Pillar instance.
+ *
+ * Shape: { "fleet": { "<role>": { uuaid, addrs?, peerId?, publicKey } } }.
+ * `pillar init --directory` writes one from the directory's agents[] so a
+ * fresh agent can `ask`/`send` with no manual key plumbing.
+ */
+export function loadFleetAddressBook(fleetPath, pillar) {
+  if (!fleetPath || !existsSync(fleetPath)) return 0;
+  const fleet = JSON.parse(readFileSync(fleetPath, "utf-8")).fleet ?? {};
+  // Warm handoff: fleet.json addrs come from a short-lived `pillar id` probe
+  // on /tcp/0, so a running daemon's REAL addr differs. Each daemon writes
+  // <home>/runtime.json on boot; prefer that addr when fresh.
+  const fleetRoot = dirname(fleetPath);
+  let n = 0;
+  for (const [role, id] of Object.entries(fleet)) {
+    if (!id.uuaid) continue;
+    if (id.uuaid === pillar.uuaid) continue; // don't self-register
+    let multiaddr = id.addrs?.[0];
+    let peerId = id.peerId;
+    const rtPath = join(fleetRoot, role, "runtime.json");
+    if (existsSync(rtPath)) {
+      try {
+        const rt = JSON.parse(readFileSync(rtPath, "utf-8"));
+        if (rt.uuaid === id.uuaid && rt.addrs?.[0]) {
+          multiaddr = rt.addrs[0];
+          peerId = rt.peerId ?? peerId;
+        }
+      } catch (_e) {}
+    }
+    pillar.registerAddress(id.uuaid, {
+      peerId,
+      multiaddr,
+      publicKey: id.publicKey, // REQUIRED for E2E sends
+    });
+    n++;
+  }
+  return n;
+}