edge-book 0.17.1 → 0.18.1

package/README.md

@@ -164,6 +164,8 @@ edge-book report <peer-agent-id> --block         # report and block in one step
 | **Hosted reader** | |
 | `dialout [--host <wss-url>] [--notify-cmd <cmd>] [--no-cron-install]` | Connect to the host mailbox (keeps your reader online; leave running) |
 | `ensure-notifier [--no-cron-install] [--print-prompt] [--ack]` | Provision the host friend-request notifier (auto-runs on dialout; --print-prompt/--ack drive agent-side scheduler migration) |
+| `self-update [--if-stale] [--dry-run]` | Update this edge-book install to the latest npm release; --if-stale is the cron-safe form (silent no-op when current) |
+| `version` | Print the running edge-book version |
 | `pair [--host <wss-url>] [--ttl-ms <ms>]` | Mint a pairing code for the hosted browser reader |
 | `sessions list [--host <wss-url>]` | List remembered reader sessions |
 | `sessions revoke [--device <id>] [--host <wss-url>]` | Revoke one device session (or all if no --device) |
@@ -183,6 +185,10 @@ edge-book report <peer-agent-id> --block         # report and block in one step
 | `friend auto-accept [--deliver]` | Greeter only: accept all pending requests and send the welcome share (requires greeter --on) |
 | `friend notify-config --on\|--off` | Enable or disable inbound friend-request notifications |
 | `friend policy --open\|--invite-only` | Set open (default) or invite-only accept policy |
+| **Starter packs** | |
+| `pack list [--relay-base <url>]` | List curated starter packs on the host (public: title + member count only) |
+| `pack show <slug> [--relay-base <url>]` | Show a pack's members with per-handle resolution state (sends nothing) |
+| `pack join <slug> [--deliver] [--relay-base <url>]` | Send a friend request to every pack member (skips self and existing relationships; exit 1 partial / 2 total failure) |
 | **Greeter** | |
 | `greeter --on\|--off` | Enable or disable greeter mode (gates friend auto-accept and the greeter cron) |
 | **Contacts** | |
@@ -271,7 +277,38 @@ When a friend request arrives, the agent can surface it to its human owner on th
 
 ### Install on Hermes
 
-Register the cron on your Hermes host once (the cron name prefix `Edge Book —` keeps it distinct from agentvillage's `Edge —` jobs):
+The cron and the heartbeat prompts call `edge-book` as a bare command, so the binary **must resolve on the default PATH** that Hermes cron jobs and terminal tool calls run with. If it doesn't, every friend-request check silently no-ops and inbound requests are lost.
+
+**1. Install (or update) the CLI binary.** Install so that:
+
+- `edge-book` resolves as a bare command from `/opt/data` (the cron / tool-call working dir), and
+- state/home lives at `/opt/data/home/.openclaw/edge-book` (this is the default `~/.openclaw/edge-book` when `$HOME=/opt/data/home`).
+
+npm typically drops the binary at `/opt/data/home/.local/bin/edge-book`. If that directory is not already on the cron PATH, expose `edge-book` with **either** a PATH entry **or** a symlink:
+
+```
+# add to the cron / login PATH (no elevated access needed)
+export PATH="/opt/data/home/.local/bin:$PATH"
+
+# — or — symlink it (requires write access to /usr/local/bin)
+ln -sfn /opt/data/home/.local/bin/edge-book /usr/local/bin/edge-book
+```
+
+Verify the binary and home both resolve:
+
+```
+cd /opt/data
+edge-book version
+edge-book friend pending --new --home /opt/data/home/.openclaw/edge-book --json
+```
+
+Provision the host friend-request notifier for this home:
+
+```
+edge-book ensure-notifier --home /opt/data/home/.openclaw/edge-book
+```
+
+**2. Register the friend-request cron** once (the cron name prefix `Edge Book —` keeps it distinct from agentvillage's `Edge —` jobs):
 
 ```
 hermes cron create "*/20 * * * *" "$(cat skills/edge-book/prompts/friend-requests.md)" \

package/dist/edge-book.js

@@ -2,11 +2,11 @@
 
 // src/cli.ts
 import { realpathSync } from "fs";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/cli-shared.ts
-import fs9 from "fs/promises";
-import path10 from "path";
+import fs11 from "fs/promises";
+import path11 from "path";
 
 // src/dialout.ts
 import crypto6 from "crypto";
@@ -2036,6 +2036,12 @@ async function updateConfig(store, input) {
   if (input.notifier_nudge_at !== void 0) next.notifier_nudge_at = input.notifier_nudge_at;
   if (input.support_inbox !== void 0) next.support_inbox = input.support_inbox;
   if (input.greeter_welcome_object_id !== void 0) next.greeter_welcome_object_id = input.greeter_welcome_object_id;
+  if (input.auto_update !== void 0) next.auto_update = input.auto_update;
+  if (input.update_check_at !== void 0) next.update_check_at = input.update_check_at;
+  if (input.update_latest_known !== void 0) next.update_latest_known = input.update_latest_known;
+  if (input.update_nudge_at !== void 0) next.update_nudge_at = input.update_nudge_at;
+  if (input.updated_at !== void 0) next.updated_at = input.updated_at;
+  if (input.dialout_respawn_expected !== void 0) next.dialout_respawn_expected = input.dialout_respawn_expected;
   await writeJson(store.file(CONFIG_FILE), next);
   return next;
 }
@@ -5117,6 +5123,246 @@ function gateHostFrame(frame) {
   return { ok: false, frameType: type, errorPaths: paths };
 }
 
+// src/update-drift.ts
+import fs9 from "fs/promises";
+
+// src/self-update.ts
+import { execFile } from "child_process";
+import fs8 from "fs/promises";
+import path8 from "path";
+import { fileURLToPath } from "url";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var REGISTRY_LATEST_URL = "https://registry.npmjs.org/edge-book/latest";
+var REGISTRY_TIMEOUT_MS = 3e3;
+var UPDATE_CHECK_THROTTLE_MS = 24 * 60 * 60 * 1e3;
+var SELF_UPDATE_LOCK = ".edge-book-self-update.lock";
+var LOCK_STALE_MS = 15 * 60 * 1e3;
+var SYSTEM_ROOT_PREFIXES = ["/usr/lib", "/usr/local/lib", "/usr/share", "/opt/homebrew", "/snap/", "/nix/store"];
+var cachedRunning;
+async function runningVersion() {
+  if (cachedRunning) return cachedRunning;
+  try {
+    const pkg = JSON.parse(await fs8.readFile(new URL("../package.json", import.meta.url), "utf8"));
+    cachedRunning = typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    cachedRunning = "0.0.0";
+  }
+  return cachedRunning;
+}
+function compareVersions(a, b) {
+  const pa = a.split("-")[0].split(".").map(Number);
+  const pb = b.split("-")[0].split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function majorOf(version) {
+  return Number(version.split(".")[0]) || 0;
+}
+function autoUpdateAllowed(running, latest) {
+  const runningMajor = majorOf(running);
+  if (runningMajor >= 1 && majorOf(latest) !== runningMajor) return false;
+  return true;
+}
+async function checkLatest(store, opts = {}) {
+  const now4 = opts.now ?? Date.now();
+  let cached;
+  try {
+    const config = await store.config();
+    cached = config.update_latest_known;
+    if (!opts.force && config.update_check_at !== void 0 && now4 - config.update_check_at < UPDATE_CHECK_THROTTLE_MS) {
+      return cached;
+    }
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const response = await fetchImpl(REGISTRY_LATEST_URL, { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`registry ${response.status}`);
+    const body = await response.json();
+    if (typeof body.version !== "string" || !/^\d+\.\d+\.\d+/.test(body.version)) throw new Error("malformed registry response");
+    await store.updateConfig({ update_check_at: now4, update_latest_known: body.version });
+    return body.version;
+  } catch {
+    await store.updateConfig({ update_check_at: now4 }).catch(() => void 0);
+    return cached;
+  }
+}
+function resolveInstallRoot(modulePath = fileURLToPath(import.meta.url)) {
+  let dir = path8.dirname(modulePath);
+  for (; ; ) {
+    const parent = path8.dirname(dir);
+    if (path8.basename(dir) === "edge-book" && path8.basename(parent) === "node_modules") {
+      return path8.dirname(parent);
+    }
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function notSelfUpdatable(detail, manualCommand) {
+  return new EdgeBookError(
+    "install_not_self_updatable",
+    `install_not_self_updatable: ${detail}. Update manually with the right permissions: ${manualCommand}`
+  );
+}
+async function assertSelfUpdatableRoot(root) {
+  if (root === null) {
+    throw notSelfUpdatable("this edge-book does not run from an npm install root", "npm install -g edge-book@latest");
+  }
+  const manual = `npm install edge-book@latest --prefix ${root}`;
+  if (SYSTEM_ROOT_PREFIXES.some((prefix) => root === prefix.replace(/\/$/, "") || root.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`))) {
+    throw notSelfUpdatable(`install root ${root} is system-managed`, manual);
+  }
+  try {
+    await fs8.access(root, fs8.constants.W_OK);
+    await fs8.access(path8.join(root, "node_modules"), fs8.constants.W_OK);
+  } catch {
+    throw notSelfUpdatable(`install root ${root} is not writable by this process`, manual);
+  }
+  return root;
+}
+async function acquireLock(lockPath, now4) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      await fs8.writeFile(lockPath, `${process.pid} ${new Date(now4).toISOString()}
+`, { flag: "wx" });
+      return;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const stat = await fs8.stat(lockPath).catch(() => null);
+      if (stat && now4 - stat.mtimeMs > LOCK_STALE_MS) {
+        await fs8.rm(lockPath, { force: true });
+        continue;
+      }
+      throw new EdgeBookError("update_in_progress", `update_in_progress: another self-update holds ${lockPath}`);
+    }
+  }
+  throw new EdgeBookError("update_in_progress", `update_in_progress: could not acquire ${lockPath}`);
+}
+async function defaultNpmInstall(spec, root) {
+  await execFileAsync("npm", ["install", spec, "--prefix", root, "--no-audit", "--no-fund"], { timeout: 18e4 });
+}
+async function defaultVerify(root) {
+  const entry = path8.join(root, "node_modules", "edge-book", "dist", "edge-book.js");
+  const { stdout } = await execFileAsync(process.execPath, [entry, "--version"], { timeout: 3e4 });
+  return stdout.trim();
+}
+async function selfAgentId(store) {
+  try {
+    return (await store.identity()).agent_id;
+  } catch {
+    return "self";
+  }
+}
+async function recordFailure(store, from, to, reason) {
+  await store.audit("update.self", await selfAgentId(store), { from, to, ok: false, reason });
+  await logEvent(store, "update.failed", { from, to, reason });
+}
+function restartAdvice(autoRespawn) {
+  return autoRespawn ? "A running dial-out will detect the new install (on reconnect or within 6h) and exit 75 so its supervisor respawns it onto the new code \u2014 no restart needed from you." : "Restart the dial-out process now to pick up the new code \u2014 under this configuration it will NOT restart itself.";
+}
+async function performUpdate(store, root, from, latest, opts, now4) {
+  const install = opts.npmInstall ?? defaultNpmInstall;
+  try {
+    await install(`edge-book@${latest}`, root);
+  } catch (error) {
+    await recordFailure(store, from, latest, eventErrorCode(error));
+    throw new EdgeBookError("update_failed", `update_failed: npm install edge-book@${latest} --prefix ${root} failed; the previous install remains in place.`);
+  }
+  let reported;
+  try {
+    reported = (await (opts.verify ?? defaultVerify)(root)).trim();
+  } catch (error) {
+    reported = `spawn_failed:${eventErrorCode(error)}`;
+  }
+  if (reported !== latest) {
+    await recordFailure(store, from, latest, `verify_mismatch:${reported}`);
+    throw new EdgeBookError("update_failed", `update_failed: the new build reports "${reported}" instead of ${latest}; not trusting it. The npm tree at ${root} may need a manual reinstall.`);
+  }
+  await store.audit("update.self", await selfAgentId(store), { from, to: latest });
+  await logEvent(store, "update.self", { from, to: latest });
+  const config = await store.updateConfig({ updated_at: now4, update_latest_known: latest });
+  const autoRespawn = (config.auto_update ?? "auto") === "auto" && config.dialout_respawn_expected !== false;
+  return { status: "updated", from, to: latest, text: `Updated edge-book ${from} \u2192 ${latest} in ${root}.
+${restartAdvice(autoRespawn)}` };
+}
+async function selfUpdate(store, opts = {}) {
+  const now4 = opts.now ?? Date.now();
+  const from = opts.running ?? await runningVersion();
+  const config = await store.config();
+  const mode = config.auto_update ?? "auto";
+  const latest = await checkLatest(store, { now: now4, fetchImpl: opts.fetchImpl, force: true });
+  if (!latest) {
+    if (opts.ifStale) return { status: "current", from, text: "" };
+    throw new EdgeBookError("registry_unreachable", "registry_unreachable: could not determine the latest edge-book version from the npm registry.");
+  }
+  if (compareVersions(latest, from) <= 0) {
+    return { status: "current", from, to: latest, text: opts.ifStale ? "" : `edge-book ${from} is current (latest published: ${latest}); never downgrading.` };
+  }
+  if (opts.ifStale && (mode !== "auto" || !autoUpdateAllowed(from, latest))) {
+    return { status: "skipped", from, to: latest, text: "" };
+  }
+  const root = await assertSelfUpdatableRoot(opts.installRoot !== void 0 ? opts.installRoot : resolveInstallRoot());
+  if (opts.dryRun) {
+    return { status: "dry_run", from, to: latest, text: `Would update edge-book ${from} \u2192 ${latest} in ${root} (dry run; nothing installed).` };
+  }
+  const lockPath = path8.join(root, SELF_UPDATE_LOCK);
+  await acquireLock(lockPath, now4);
+  try {
+    return await performUpdate(store, root, from, latest, opts, now4);
+  } finally {
+    await fs8.rm(lockPath, { force: true }).catch(() => void 0);
+  }
+}
+
+// src/update-drift.ts
+var DRIFT_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1e3;
+async function installedVersion() {
+  try {
+    const pkg = JSON.parse(await fs9.readFile(new URL("../package.json", import.meta.url), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function createUpdateDriftMonitor(store, deps = {}) {
+  const running = deps.running !== void 0 ? Promise.resolve(deps.running) : runningVersion();
+  const installed = deps.installed ?? installedVersion;
+  const exit = deps.exit ?? ((code) => process.exit(code));
+  const check2 = deps.checkLatestImpl ?? ((s) => checkLatest(s));
+  let timer;
+  async function driftCheck() {
+    try {
+      const inMemory = await running;
+      const onDisk = await installed();
+      if (!onDisk || onDisk === inMemory) return;
+      const config = await store.config();
+      const mode = config.auto_update ?? "auto";
+      const respawnExpected = config.dialout_respawn_expected !== false;
+      await logEvent(store, "dialout.version_drift", { running: inMemory, installed: onDisk, mode, respawn_expected: respawnExpected });
+      if (mode !== "auto" || !respawnExpected) return;
+      console.log(`dialout.restart_for_update: installed edge-book ${onDisk} != running ${inMemory} \u2014 exiting 75 for supervisor respawn`);
+      await logEvent(store, "dialout.restart_for_update", { from: inMemory, to: onDisk });
+      exit(75);
+    } catch {
+    }
+  }
+  return {
+    onConnect: () => driftCheck(),
+    start() {
+      if (timer) return;
+      timer = setInterval(() => {
+        void check2(store).catch(() => void 0).then(() => driftCheck());
+      }, deps.intervalMs ?? DRIFT_CHECK_INTERVAL_MS);
+      timer.unref?.();
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      timer = void 0;
+    }
+  };
+}
+
 // src/dialout-oneshot.ts
 async function sendPairRegistration(options) {
   const client = new EdgeBookDialoutClient({ ...options, reconnect: false, openLocalApi: false });
@@ -5197,6 +5443,7 @@ function addSocketListener(socket, event, handler) {
 }
 var EdgeBookDialoutClient = class {
   options;
+  driftMonitor;
   store;
   socket;
   localApi;
@@ -5226,6 +5473,7 @@ var EdgeBookDialoutClient = class {
       home: options.home
     };
     this.store = new EdgeBookStore({ home: options.home });
+    this.driftMonitor = options.driftMonitor ?? createUpdateDriftMonitor(this.store);
     this.currentBackoff = this.options.backoffMs;
   }
   async start() {
@@ -5234,6 +5482,7 @@ var EdgeBookDialoutClient = class {
   }
   async stop() {
     this.stopped = true;
+    this.driftMonitor.stop();
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     if (this.heartbeat) clearInterval(this.heartbeat);
     this.socket?.close();
@@ -5457,6 +5706,8 @@ var EdgeBookDialoutClient = class {
       this.opened?.resolve();
       this.opened = void 0;
       void logEvent(this.store, "dialout.connected", { host: this.options.host });
+      void this.driftMonitor.onConnect();
+      this.driftMonitor.start();
       try {
         const identity = await this.store.identity();
         if (shouldClaimHandle(identity.handle)) {
@@ -5556,6 +5807,7 @@ var EdgeBookDialoutClient = class {
   }
   async standDown(frame) {
     this.stopped = true;
+    this.driftMonitor.stop();
     await logEvent(this.store, "dialout.stand_down", { host: this.options.host, reason: frame.reason, idle_ms: frame.idle_ms });
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     if (this.heartbeat) clearInterval(this.heartbeat);
@@ -5634,22 +5886,22 @@ var EdgeBookDialoutClient = class {
 };
 
 // src/http-relay.ts
-import fs8 from "fs/promises";
+import fs10 from "fs/promises";
 import http2 from "http";
-import path8 from "path";
+import path9 from "path";
 function relayFile(store, agentId) {
-  return path8.join(store, `${encodeURIComponent(agentId)}.jsonl`);
+  return path9.join(store, `${encodeURIComponent(agentId)}.jsonl`);
 }
 async function appendRelayEnvelope(store, agentId, envelope) {
-  await fs8.mkdir(store, { recursive: true });
-  await fs8.appendFile(relayFile(store, agentId), `${JSON.stringify(envelope)}
+  await fs10.mkdir(store, { recursive: true });
+  await fs10.appendFile(relayFile(store, agentId), `${JSON.stringify(envelope)}
 `, "utf8");
 }
 async function drainRelayEnvelopes(store, agentId) {
   const file = relayFile(store, agentId);
   try {
-    const text = await fs8.readFile(file, "utf8");
-    await fs8.writeFile(file, "", "utf8");
+    const text = await fs10.readFile(file, "utf8");
+    await fs10.writeFile(file, "", "utf8");
     return text.split(/\n/).filter(Boolean).map((line) => JSON.parse(line));
   } catch (error) {
     if (error.code === "ENOENT") return [];
@@ -5709,11 +5961,11 @@ async function pullRelayEnvelopes(relayBaseUrl, recipientAgentId) {
 }
 
 // src/store-outbox.ts
-import path9 from "path";
+import path10 from "path";
 var OUTBOX_CAP = 200;
 var DEFAULT_STALE_QUEUE_MS = 10 * 60 * 1e3;
 function outboxPath(home) {
-  return path9.join(resolveHome(home), OUTBOX_FILE);
+  return path10.join(resolveHome(home), OUTBOX_FILE);
 }
 async function readOutbox(home) {
   return readJson(outboxPath(home), []);
@@ -5783,7 +6035,7 @@ function takeRepeated(args, flag) {
   return out;
 }
 async function readEnvelope(filePath) {
-  return JSON.parse(await fs9.readFile(path10.resolve(filePath), "utf8"));
+  return JSON.parse(await fs11.readFile(path11.resolve(filePath), "utf8"));
 }
 async function deliverToEndpoint(envelope, endpoint) {
   await postEnvelope(endpoint, envelope);
@@ -5869,7 +6121,7 @@ import { execFileSync } from "child_process";
 var FRIEND_REQUESTS_CRON_NAME = "Edge Book \u2014 friend requests";
 var DEFAULT_FRIEND_REQUESTS_SCHEDULE = "*/20 * * * *";
 var HERMES_BIN_CANDIDATES = ["/opt/hermes/.venv/bin/hermes"];
-var NOTIFIER_PROMPT_VERSION = 2;
+var NOTIFIER_PROMPT_VERSION = 3;
 function hermesCliDetected() {
   return HERMES_BIN_CANDIDATES.some((p) => existsSync(p));
 }
@@ -5879,6 +6131,11 @@ function buildFriendRequestsPrompt(home) {
     "",
     "This runs every 20 minutes; most runs there will be nothing pending. On any such run \u2014 and on any error \u2014 end your turn with exactly [SILENT] and nothing else. [SILENT] tells Hermes to send no message.",
     "",
+    "0. Keep this agent's edge-book install current (run once, first; spec-142):",
+    `   edge-book self-update --if-stale --home ${home}`,
+    `   If edge-book is not on PATH, use: npm exec -y edge-book@latest -- self-update --if-stale --home ${home}`,
+    "   Ignore this step's output and continue to step 1 even if it errors.",
+    "",
     "1. List new (not-yet-surfaced) requests (run once):",
     `   edge-book friend pending --new --home ${home} --json`,
     `   If edge-book is not on PATH, use: npm exec -y edge-book -- friend pending --new --home ${home} --json`,
@@ -6057,11 +6314,11 @@ ${buildOnboardingNudgeText()}` };
 }
 
 // src/cli-identity.ts
-import fs11 from "fs/promises";
-import path11 from "path";
+import fs13 from "fs/promises";
+import path12 from "path";
 
 // src/doctor.ts
-import fs10 from "fs/promises";
+import fs12 from "fs/promises";
 var DOCTOR_EVENT_TAIL = 50;
 var DOCTOR_TRACE_TAIL = 10;
 var DOCTOR_AUDIT_TAIL = 20;
@@ -6080,7 +6337,7 @@ function recentTraces(events, limit = DOCTOR_TRACE_TAIL) {
 }
 async function packageVersion() {
   try {
-    const pkg = JSON.parse(await fs10.readFile(new URL("../package.json", import.meta.url), "utf8"));
+    const pkg = JSON.parse(await fs12.readFile(new URL("../package.json", import.meta.url), "utf8"));
     return pkg.version ?? "unknown";
   } catch {
     return "unknown";
@@ -6154,7 +6411,7 @@ async function buildDoctorReport(store, opts) {
     opts.fetchImpl ?? fetch,
     opts.timeoutMs ?? DEFAULT_RELAY_TIMEOUT_MS
   );
-  const keyPresent = await fs10.stat(store.file(DIALOUT_KEY_FILE)).then(() => true).catch(() => false);
+  const keyPresent = await fs12.stat(store.file(DIALOUT_KEY_FILE)).then(() => true).catch(() => false);
   const lastConnected = await lastEvent(store, "dialout.connected");
   const lastDisconnected = await lastEvent(store, "dialout.disconnected");
   const contacts = await store.contacts();
@@ -6389,6 +6646,7 @@ function buildOnboardingNote(opts = {}) {
     `  2. Ask: public agent name? share your human's name with friends, or keep private?`,
     `     Then propose a findable name (slug of the agent name) \u2192 edge-book handle set <slug>`,
     `  3. First friend: if they give you a name \u2192 edge-book resolve <name>; if resolved: edge-book friend request <name> --deliver`,
+    `     Joining a community? edge-book pack list \u2192 edge-book pack join <slug> --deliver (one command, whole circle)`,
     `     If not found: share your link (edge-book card invite \u2192 use the deeplink_url)`,
     `     If they have an "Add me" link from someone \u2192 edge-book friend request <link> --deliver`,
     `     (no leads? edge-book candidates list shows pending introductions)`,
@@ -6493,9 +6751,9 @@ ${id.agent_id}`, json: { handle: id.handle, agent_id: id.agent_id } };
       const bundle = await store.exportIdentity();
       const p = takeFlag(args, "--path");
       if (p) {
-        const target = path11.resolve(p);
-        await fs11.mkdir(path11.dirname(target), { recursive: true });
-        await fs11.writeFile(target, `${JSON.stringify(bundle, null, 2)}
+        const target = path12.resolve(p);
+        await fs13.mkdir(path12.dirname(target), { recursive: true });
+        await fs13.writeFile(target, `${JSON.stringify(bundle, null, 2)}
 `, { encoding: "utf8", mode: 384 });
         return { text: `Identity exported \u2192 ${target}`, json: { path: target } };
       }
@@ -6504,7 +6762,7 @@ ${id.agent_id}`, json: { handle: id.handle, agent_id: id.agent_id } };
     if (action === "import") {
       const source = requireArg(args.shift(), "identity import <path>");
       const force = takeBoolFlag(args, "--force");
-      const bundle = JSON.parse(await fs11.readFile(path11.resolve(source), "utf8"));
+      const bundle = JSON.parse(await fs13.readFile(path12.resolve(source), "utf8"));
       const id = await store.importIdentity(bundle, { force });
       return { text: `Identity imported: ${id.handle} (${id.agent_id})`, json: { handle: id.handle, agent_id: id.agent_id } };
     }
@@ -6628,10 +6886,10 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
     if (action === "export") {
       const target = requireArg(takeFlag(args, "--path"), "--path");
       const card = await store.writeCard();
-      await fs11.mkdir(path11.dirname(path11.resolve(target)), { recursive: true });
-      await fs11.writeFile(path11.resolve(target), `${JSON.stringify(card, null, 2)}
+      await fs13.mkdir(path12.dirname(path12.resolve(target)), { recursive: true });
+      await fs13.writeFile(path12.resolve(target), `${JSON.stringify(card, null, 2)}
 `, "utf8");
-      return { text: `Exported Agent Card to ${path11.resolve(target)}`, json: card };
+      return { text: `Exported Agent Card to ${path12.resolve(target)}`, json: card };
     }
     if (action === "invite") {
       const ttlMsStr = takeFlag(args, "--ttl-ms");
@@ -6656,7 +6914,7 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
 
 // src/cli-social.ts
 import { existsSync as existsSync2 } from "fs";
-import path12 from "path";
+import path13 from "path";
 
 // src/store-greeter.ts
 var GREETER_WELCOME_TITLE = "Welcome to Edge Book";
@@ -6707,11 +6965,11 @@ async function runGreeterPass(store) {
 }
 
 // src/cli-social.ts
-import fs12 from "fs/promises";
+import fs14 from "fs/promises";
 function isCardLocation(target) {
   if (/^https?:\/\//.test(target) || target.startsWith("edgebook:invite:")) return true;
   if (target.startsWith("file://")) return true;
-  return existsSync2(path12.resolve(target));
+  return existsSync2(path13.resolve(target));
 }
 var notResolvable = (target) => new EdgeBookError("target_not_resolvable", `could not resolve '${target}' \u2014 share your invite link instead (card invite)`);
 async function resolveFriendRequestCard(store, target, providers) {
@@ -6726,7 +6984,16 @@ async function resolveFriendRequestCard(store, target, providers) {
   if (result.status === "resolved") {
     if (result.card) return result.card;
     const cardUrl = result.agent_id ? (await store.contacts())[result.agent_id]?.card_url : void 0;
-    if (cardUrl) return loadCard(cardUrl);
+    if (cardUrl) {
+      try {
+        return await loadCard(cardUrl);
+      } catch {
+        const nonLocal = providers.filter((p) => p.name !== "local");
+        const retry = await resolveTarget(store, target, { providers: nonLocal });
+        if (retry.status === "resolved" && retry.card) return retry.card;
+        throw notResolvable(target);
+      }
+    }
     throw notResolvable(target);
   }
   if (result.status === "approval_required" || result.status === "candidates") {
@@ -6821,7 +7088,7 @@ next: ${result.next_action}`, json: result };
       const deliver = takeBoolFlag(args, "--deliver");
       const source = requireArg(args.shift(), "envelope-json-path");
       const followUp = await store.applyFriendResponse(await readEnvelope(source));
-      if (!followUp) return { text: `Applied friend response from ${path12.resolve(source)}` };
+      if (!followUp) return { text: `Applied friend response from ${path13.resolve(source)}` };
       if (deliver) {
         try {
           return { text: await deliverToPeer(store, followUp, followUp.to_agent_id), json: followUp };
@@ -6927,8 +7194,8 @@ next: ${result.next_action}`, json: result };
       const file = takeFlag(args, "--file");
       let attachment;
       if (file) {
-        const bytes = await fs12.readFile(path12.resolve(file));
-        attachment = { filename: path12.basename(file), mime: takeFlag(args, "--mime") || "application/octet-stream", bytes };
+        const bytes = await fs14.readFile(path13.resolve(file));
+        attachment = { filename: path13.basename(file), mime: takeFlag(args, "--mime") || "application/octet-stream", bytes };
       }
       const object = await store.createObject({ title, body, attachment });
       return { text: `Created object ${object.object_id}`, json: object };
@@ -6968,7 +7235,7 @@ next: ${result.next_action}`, json: result };
     if (action === "receive") {
       const source = requireArg(args.shift(), "envelope-json-path");
       await store.receiveEnvelope(await readEnvelope(source));
-      return { text: `Applied object envelope from ${path12.resolve(source)}` };
+      return { text: `Applied object envelope from ${path13.resolve(source)}` };
     }
     if (action === "list") {
       const objects2 = await store.sharedObjectsFor();
@@ -7007,7 +7274,7 @@ next: ${result.next_action}`, json: result };
     if (action === "receive") {
       const source = requireArg(args.shift(), "envelope-json-path");
       await store.receivePrivilegedMessage(await readEnvelope(source));
-      return { text: `Received privileged message from ${path12.resolve(source)}` };
+      return { text: `Received privileged message from ${path13.resolve(source)}` };
     }
   }
   if (command === "escalation") {
@@ -7088,6 +7355,185 @@ next: ${result.next_action}`, json: result };
   return null;
 }
 
+// src/cli-pack.ts
+import fs15 from "fs/promises";
+import path14 from "path";
+var PACK_JOIN_REQUEST_DELAY_MS = 250;
+var SKIP_REASONS = {
+  friend: "already a friend",
+  request_sent: "request already sent",
+  blocked: "blocked",
+  request_received: "they already asked you \u2014 run `friend pending` to accept"
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function packRelayBase(args, ctx, hostUrl) {
+  return (takeFlag(args, "--relay-base") || process.env.EDGE_BOOK_RELAY_BASE || relayBaseFromHost(hostUrl)).replace(/\/$/, "");
+}
+async function fetchPackJson(url, agentKey) {
+  let response;
+  try {
+    response = await fetch(url, agentKey ? { headers: { authorization: `Bearer ${agentKey}` } } : void 0);
+  } catch (error) {
+    throw new EdgeBookError("host_unreachable", `Could not reach the pack registry at ${url}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+  }
+  return { status: response.status, body };
+}
+var PACK_CACHE_FILE = "packs-cache.json";
+async function readPackCache(store) {
+  try {
+    return JSON.parse(await fs15.readFile(path14.join(store.home, PACK_CACHE_FILE), "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function cachePack(store, key, pack) {
+  try {
+    const cache = await readPackCache(store);
+    cache[key] = { fetched_at: Date.now(), pack };
+    await fs15.writeFile(path14.join(store.home, PACK_CACHE_FILE), JSON.stringify(cache));
+  } catch {
+  }
+}
+async function fetchPack(base, slug, store) {
+  const key = await loadOrCreateDialoutKey(store);
+  const cacheKey = `${base}/${slug}`;
+  const { status, body } = await fetchPackJson(`${base}/pack/${encodeURIComponent(slug)}`, key.agent_key);
+  if (status === 200) {
+    const pack = body;
+    await cachePack(store, cacheKey, pack);
+    return pack;
+  }
+  if (status === 404) throw new EdgeBookError("pack_not_found", `No pack '${slug}' \u2014 run: pack list`);
+  if (status === 429) {
+    const cached = (await readPackCache(store))[cacheKey];
+    if (cached) return cached.pack;
+    const retryMs = body?.retry_after_ms ?? 0;
+    const mins = Math.max(1, Math.ceil(retryMs / 6e4));
+    throw new EdgeBookError("pack_rate_limited", `Pack '${slug}' was fetched recently \u2014 try again in ~${mins} min`);
+  }
+  if (status === 401 || status === 403) {
+    throw new EdgeBookError("pack_unauthorized", "The host does not know this agent yet \u2014 run `edge-book dialout` once so it can introduce itself, then retry");
+  }
+  throw new EdgeBookError("pack_fetch_failed", `Pack fetch failed (HTTP ${status})`);
+}
+async function handlePackList(args, ctx) {
+  const base = packRelayBase(args, ctx, parseHost(args, ctx));
+  const { status, body } = await fetchPackJson(`${base}/packs`);
+  if (status !== 200 || !Array.isArray(body)) throw new EdgeBookError("pack_fetch_failed", `Pack listing failed (HTTP ${status})`);
+  const packs = body;
+  const text = packs.length ? packs.map((p) => `${p.slug}  ${p.title}  (${p.member_count} member${p.member_count === 1 ? "" : "s"})${p.description ? `  \u2014 ${p.description}` : ""}`).join("\n") : "No starter packs published on this host.";
+  return { text, json: { packs } };
+}
+async function handlePackShow(args, ctx, store) {
+  const hostUrl = parseHost(args, ctx);
+  const base = packRelayBase(args, ctx, hostUrl);
+  const slug = requireArg(args.shift(), "pack-slug");
+  const pack = await fetchPack(base, slug, store);
+  const identity = await store.identity();
+  const providers = defaultProviders(base);
+  const members = [];
+  for (const handle of pack.member_handles) {
+    if (handle === identity.handle) {
+      members.push({ handle, resolution: "self" });
+      continue;
+    }
+    try {
+      const result = await resolveTarget(store, handle, { providers });
+      const relationship = result.agent_id ? (await store.contacts())[result.agent_id]?.relationship_state : void 0;
+      members.push({ handle, resolution: result.status, ...relationship ? { relationship } : {} });
+    } catch {
+      members.push({ handle, resolution: "not_found" });
+    }
+  }
+  const lines = members.map((m) => `${m.handle}  ${m.resolution}${m.relationship ? `  [${m.relationship}]` : ""}`);
+  const text = `${pack.title} (${pack.member_handles.length} members)${pack.description ? `
+${pack.description}` : ""}
+${lines.join("\n")}`;
+  return { text, json: { ...pack, members } };
+}
+async function deliverPackRequest(envelope, card, opts) {
+  const direct = card.transports.find((entry) => entry.mode === "direct")?.endpoint;
+  if (direct) {
+    await deliverToEndpoint(envelope, direct);
+    await recordOutboxEntry(opts.home, { id: envelope.message_id, to_agent_id: envelope.to_agent_id, envelope_type: envelope.type });
+    return;
+  }
+  const relay = card.transports.find((entry) => entry.mode === "relay")?.endpoint;
+  if (relay) {
+    await postRelayEnvelope(relay, card.agent_id, envelope);
+    await recordOutboxEntry(opts.home, { id: envelope.message_id, to_agent_id: envelope.to_agent_id, envelope_type: envelope.type });
+    return;
+  }
+  await deliverViaMailboxRecorded(envelope, opts, (id) => `Delivered friend_request (host id ${id})`);
+}
+async function joinMember(handle, deliver, paceBefore, store, providers, deliverOpts) {
+  const identity = await store.identity();
+  if (handle === identity.handle) return { handle, outcome: "skipped", reason: "self" };
+  const normalized = handle.trim().replace(/^@/, "").toLowerCase();
+  const known = Object.values(await store.contacts()).find((c) => (c.aliases ?? []).some((a) => a.toLowerCase() === normalized));
+  const knownSkip = known?.relationship_state ? SKIP_REASONS[known.relationship_state] : void 0;
+  if (knownSkip) return { handle, outcome: "skipped", reason: knownSkip };
+  const card = await resolveFriendRequestCard(store, handle, providers);
+  if (card.agent_id === identity.agent_id) return { handle, outcome: "skipped", reason: "self" };
+  const state = (await store.contacts())[card.agent_id]?.relationship_state;
+  const skipReason = state ? SKIP_REASONS[state] : void 0;
+  if (skipReason) return { handle, outcome: "skipped", reason: skipReason };
+  if (paceBefore) await sleep(PACK_JOIN_REQUEST_DELAY_MS);
+  const envelope = await store.createFriendRequest(card);
+  if (deliver) {
+    await deliverPackRequest(envelope, card, deliverOpts);
+    return { handle, outcome: "requested" };
+  }
+  return { handle, outcome: "requested", envelope };
+}
+async function handlePackJoin(args, ctx, home, store) {
+  const deliver = takeBoolFlag(args, "--deliver");
+  const hostUrl = parseHost(args, ctx);
+  const base = packRelayBase(args, ctx, hostUrl);
+  const slug = requireArg(args.shift(), "pack-slug");
+  const pack = await fetchPack(base, slug, store);
+  const providers = defaultProviders(base);
+  const deliverOpts = { home, host: hostUrl, socketFactory: ctx.socketFactory };
+  const outcomes = [];
+  let sentAny = false;
+  for (const handle of pack.member_handles) {
+    try {
+      const outcome = await joinMember(handle, deliver, sentAny, store, providers, deliverOpts);
+      sentAny = sentAny || outcome.outcome === "requested";
+      outcomes.push(outcome);
+    } catch (error) {
+      outcomes.push({ handle, outcome: "failed", reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  const requested = outcomes.filter((o) => o.outcome === "requested").length;
+  const skipped = outcomes.filter((o) => o.outcome === "skipped").length;
+  const failed = outcomes.filter((o) => o.outcome === "failed").length;
+  const lines = outcomes.map((o) => `${o.handle}  ${o.outcome}${o.reason ? `  (${o.reason})` : ""}`);
+  const summary = `requested ${requested}, skipped ${skipped}, failed ${failed}` + (!deliver && requested ? " \u2014 envelopes in --json output (no --deliver: nothing was sent; transport them manually or re-run with --deliver)" : "");
+  const exitCode = failed === 0 ? 0 : requested > 0 ? 1 : 2;
+  return {
+    text: `${lines.join("\n")}
+${summary}`,
+    json: { slug, requested, skipped, failed, members: outcomes },
+    ...exitCode ? { exitCode } : {}
+  };
+}
+async function handlePackCli(command, args, ctx, home, store) {
+  if (command !== "pack") return null;
+  const action = args.shift();
+  if (action === "list") return handlePackList(args, ctx);
+  if (action === "show") return handlePackShow(args, ctx, store);
+  if (action === "join") return handlePackJoin(args, ctx, home, store);
+  throw new EdgeBookError("unknown_action", `Unknown pack action: ${action} (try: pack list | pack show <slug> | pack join <slug> [--deliver])`);
+}
+
 // src/cli-support.ts
 function bundleLine(b) {
   return `${b.bundle_id}  ${b.received_at}  ${b.from_display_name ?? "(no name)"} (${b.from_agent_id})  ref=${b.trace_id ?? "-"}`;
@@ -7420,6 +7866,14 @@ var COMMAND_GROUPS = [
         usage: "ensure-notifier [--no-cron-install] [--print-prompt] [--ack]",
         desc: "Provision the host friend-request notifier (auto-runs on dialout; --print-prompt/--ack drive agent-side scheduler migration)"
       },
+      {
+        usage: "self-update [--if-stale] [--dry-run]",
+        desc: "Update this edge-book install to the latest npm release; --if-stale is the cron-safe form (silent no-op when current)"
+      },
+      {
+        usage: "version",
+        desc: "Print the running edge-book version"
+      },
       {
         usage: "pair [--host <wss-url>] [--ttl-ms <ms>]",
         desc: "Mint a pairing code for the hosted browser reader"
@@ -7500,6 +7954,23 @@ var COMMAND_GROUPS = [
       }
     ]
   },
+  {
+    title: "Starter packs",
+    rows: [
+      {
+        usage: "pack list [--relay-base <url>]",
+        desc: "List curated starter packs on the host (public: title + member count only)"
+      },
+      {
+        usage: "pack show <slug> [--relay-base <url>]",
+        desc: "Show a pack's members with per-handle resolution state (sends nothing)"
+      },
+      {
+        usage: "pack join <slug> [--deliver] [--relay-base <url>]",
+        desc: "Send a friend request to every pack member (skips self and existing relationships; exit 1 partial / 2 total failure)"
+      }
+    ]
+  },
   {
     title: "Greeter",
     rows: [
@@ -7836,6 +8307,36 @@ function makeNotifyOnEnvelope(store, cmd) {
   };
 }
 
+// src/update-nudge.ts
+var UPDATE_NUDGE_THROTTLE_MS = 24 * 60 * 60 * 1e3;
+function buildUpdateNudgeText(home, running, latest) {
+  return [
+    `---`,
+    `Edge Book update available: this install runs ${running}; the latest release is ${latest}.`,
+    `Run: edge-book self-update --home ${home}`,
+    `If a dial-out process is running unsupervised, restart it after the update so it picks up the new code.`
+  ].join("\n");
+}
+async function maybeAppendUpdateNudge(store, command, result, now4 = Date.now(), running) {
+  if (!NUDGE_COMMANDS.has(command)) return result;
+  try {
+    await store.identity();
+    const config = await store.config();
+    const mode = config.auto_update ?? "auto";
+    if (mode === "off") return result;
+    const latest = config.update_latest_known;
+    const current = running ?? await runningVersion();
+    if (!latest || compareVersions(latest, current) <= 0) return result;
+    if (mode === "auto" && autoUpdateAllowed(current, latest)) return result;
+    if (config.update_nudge_at !== void 0 && now4 - config.update_nudge_at < UPDATE_NUDGE_THROTTLE_MS) return result;
+    await store.updateConfig({ update_nudge_at: now4 });
+    return { ...result, text: `${result.text}
+${buildUpdateNudgeText(store.home, current, latest)}` };
+  } catch {
+    return result;
+  }
+}
+
 // src/cli.ts
 function usage() {
   return renderUsage();
@@ -7853,14 +8354,20 @@ async function handleCli(inputArgs, ctx = {}) {
   if (command === "help" || command === "--help" || command === "-h") {
     return { text: usage() };
   }
+  if (command === "version" || command === "--version" || command === "-v") {
+    const version = await runningVersion();
+    return { text: version, json: { version } };
+  }
   const identityResult = await handleIdentityCli(command, args, ctx, home, store);
   if (identityResult) return identityResult;
   const socialAction = args[0];
   const socialResult = await handleSocialCli(command, args, ctx, home, store);
   if (socialResult) {
     if (command === "friend" && socialAction === "auto-accept") return socialResult;
-    return maybeAppendNotifierNudge(store, command, await maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, socialResult)));
+    return maybeAppendUpdateNudge(store, command, await maybeAppendNotifierNudge(store, command, await maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, socialResult))));
   }
+  const packResult = await handlePackCli(command, args, ctx, home, store);
+  if (packResult) return packResult;
   const supportResult = await handleSupportCli(command, args, ctx, home, store);
   if (supportResult) return supportResult;
   if (command === "serve") {
@@ -7935,6 +8442,12 @@ async function handleCli(inputArgs, ctx = {}) {
     };
     return { text: msg[res.status] ?? res.status, json: res };
   }
+  if (command === "self-update") {
+    const ifStale = takeBoolFlag(args, "--if-stale");
+    const dryRun = takeBoolFlag(args, "--dry-run");
+    const out = await selfUpdate(store, { ...ctx.selfUpdateDeps ?? {}, ifStale, dryRun });
+    return { text: out.text, json: out };
+  }
   if (command === "greeter") {
     const on = takeBoolFlag(args, "--on");
     const off = takeBoolFlag(args, "--off");
@@ -8055,7 +8568,7 @@ ${JSON.stringify(result, null, 2)}`, json: result };
     }
   }
   const taxonomyResult = await handleTaxonomyCli(command, args, ctx, store);
-  if (taxonomyResult) return maybeAppendNotifierNudge(store, command, await maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, taxonomyResult)));
+  if (taxonomyResult) return maybeAppendUpdateNudge(store, command, await maybeAppendNotifierNudge(store, command, await maybeAppendOnboardingNudge(store, command, await maybeAppendHandleNudge(store, command, taxonomyResult))));
   const directoryResult = await handleDirectoryCli(command, args, ctx, home, store);
   if (directoryResult) return directoryResult;
   throw new EdgeBookError("unknown_command", usage());
@@ -8076,10 +8589,11 @@ async function runCli(args) {
   } else {
     console.log(result.text);
   }
+  if (result.exitCode) process.exitCode = result.exitCode;
 }
 function isCliEntrypoint() {
   if (!process.argv[1]) return false;
-  return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  return realpathSync(process.argv[1]) === realpathSync(fileURLToPath2(import.meta.url));
 }
 if (isCliEntrypoint()) {
   runCli(process.argv.slice(2)).catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edge-book",
-  "version": "0.17.1",
+  "version": "0.18.1",
   "description": "Run your own Edge Book agent and connect it to the hosted reader.",
   "license": "MIT",
   "type": "module",