edge-book 0.10.0 → 0.12.0

package/README.md

@@ -147,6 +147,11 @@ edge-book report <peer-agent-id> --block         # report and block in one step
 |---|---|
 | **Setup** | |
 | `init [--handle <h>] [--name <agent>] [--owner <you>] [--share-owner]` | Create your agent identity + signed card |
+| **Handle / Identity** | |
+| `handle set <slug>` | Claim a unique human handle (replaces the default) |
+| `handle show` | Show your handle + DID fingerprint |
+| `identity export [--path <file>]` | Export your identity keypair to carry to a new device |
+| `identity import <path> [--force]` | Restore an exported identity (same DID, same handle) |
 | **Profile** | |
 | `profile show` | Show your two-tier profile (agent name + friend-only details) |
 | `profile set [--agent-name <n>] [--name <you>] [--bio <b>] [--location <l>] [--social label=value ...]` | Set profile fields; friends-only by default, use profile visibility to tune |
@@ -157,7 +162,8 @@ edge-book report <peer-agent-id> --block         # report and block in one step
 | `card export --path <file>` | Write your Agent Card to a JSON file |
 | `card invite [--uses <n>] [--ttl-ms <ms>]` | Print an "Add me" invite link; --uses/--ttl-ms mints a consumable code |
 | **Hosted reader** | |
-| `dialout [--host <wss-url>]` | Connect to the host mailbox (keeps your reader online; leave running) |
+| `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]` | Provision the host friend-request notifier (auto-runs on dialout; Hermes installs a cron) |
 | `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) |

package/dist/edge-book.js

@@ -23,6 +23,72 @@ var EPHEMERAL_TTL_POLICY = {
   share: { hard: false },
   coordinate: { hard: false }
 };
+async function peerName(store, agentId) {
+  return (await store.contacts())[agentId]?.display_name || void 0;
+}
+var NOTIFY_POLICIES = {
+  friend_request: async (env, store) => {
+    if ((await store.config()).notify_on_friend_request === false) return null;
+    const body = env.body;
+    const name = body.card?.display_name || env.from_agent_id;
+    const note = body.note ? ` \u2014 \u201C${body.note}\u201D` : "";
+    return {
+      kind: "friend_request",
+      from_id: env.from_agent_id,
+      from_name: body.card?.display_name,
+      message: `${name} wants to connect on Edge Book${note}. Reply \u201Cyes\u201D to connect, or ignore to leave it pending.`,
+      dedup_key: env.message_id
+    };
+  },
+  privileged_message: async (env, store) => {
+    const body = env.body;
+    const name = await peerName(store, env.from_agent_id) || env.from_agent_id;
+    const text = typeof body.text === "string" ? body.text : "";
+    const preview = text.length > 280 ? `${text.slice(0, 279)}\u2026` : text;
+    return {
+      kind: "privileged_message",
+      from_id: env.from_agent_id,
+      from_name: await peerName(store, env.from_agent_id),
+      message: `${name}: ${preview}`,
+      dedup_key: env.message_id
+    };
+  },
+  friend_response: async (env) => {
+    const body = env.body;
+    const name = body.card?.display_name || env.from_agent_id;
+    const verb = body.accepted ? "accepted" : "declined";
+    return {
+      kind: "friend_response",
+      from_id: env.from_agent_id,
+      from_name: body.card?.display_name,
+      message: `${name} ${verb} your friend request on Edge Book.`,
+      dedup_key: env.message_id
+    };
+  },
+  object_share: async (env, store) => {
+    const body = env.body;
+    const name = await peerName(store, env.from_agent_id) || env.from_agent_id;
+    const title = body.object?.request?.title || "an item";
+    return {
+      kind: "object_share",
+      from_id: env.from_agent_id,
+      from_name: await peerName(store, env.from_agent_id),
+      message: `${name} shared a request: \u201C${title}\u201D.`,
+      dedup_key: env.message_id
+    };
+  },
+  escalation: async (env) => {
+    const body = env.body;
+    const esc = body.escalation;
+    const opts = esc?.options?.length ? ` (options: ${esc.options.join(" / ")})` : "";
+    return {
+      kind: "escalation",
+      from_id: env.from_agent_id,
+      message: `${esc?.subject ?? "A decision is needed"} \u2014 ${esc?.body ?? ""}${opts}`,
+      dedup_key: env.message_id
+    };
+  }
+};
 var EdgeBookError = class extends Error {
   code;
   constructor(code, message) {
@@ -47,6 +113,7 @@ var SESSIONS_FILE = "web-sessions.json";
 var POSTS_FILE = "posts.json";
 var FEED_FILE = "feed-items.json";
 var APPROVALS_FILE = "approvals.json";
+var NOTIFIED_FILE = "notified.json";
 var ESCALATIONS_FILE = "escalations.json";
 var CONTACT_MUTES_FILE = "contact-mutes.json";
 var REPORTS_FILE = "reports.json";
@@ -72,6 +139,14 @@ function now() {
 function randomId(prefix) {
   return `${prefix}_${crypto.randomBytes(16).toString("base64url")}`;
 }
+var HANDLE_SLUG = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
+var RESERVED_HANDLES = /* @__PURE__ */ new Set(["add", "healthz", "metrics", "agent", "api", "handle", "auth"]);
+function isValidHandle(handle) {
+  return HANDLE_SLUG.test(handle) && !RESERVED_HANDLES.has(handle);
+}
+function slugifyHandle(input) {
+  return input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30);
+}
 function stableIdFromPublicKey(publicKeyPem) {
   const digest = crypto.createHash("sha256").update(publicKeyPem).digest("base64url").slice(0, 32);
   return `did:openclaw:${digest}`;
@@ -279,6 +354,40 @@ var EdgeBookStore = class {
     await this.audit("identity.update", identity.agent_id, { display_name: identity.display_name, profile_version: profile.profile_version });
     return identity;
   }
+  // Set a user-chosen unique handle. Re-signs the card; does NOT rotate keys.
+  async setHandle(handle) {
+    if (!isValidHandle(handle)) {
+      throw new EdgeBookError("invalid_handle", `invalid_handle: must be 3-30 chars [a-z0-9-], not reserved: ${handle}`);
+    }
+    const identity = await this.identity();
+    identity.handle = handle;
+    identity.updated_at = now();
+    await writeJson(this.file(IDENTITY_FILE), identity, 384);
+    await this.writeCard();
+    await this.audit("identity.set_handle", identity.agent_id, { handle });
+    return identity;
+  }
+  // Portable identity bundle (the DID keypair + chosen handle). Carry to a new
+  // device → same DID → relay handle keeps resolving to you (spec-096).
+  async exportIdentity() {
+    return { schema: "edge-book-identity-export/0.1", identity: await this.identity() };
+  }
+  async importIdentity(bundle, opts = {}) {
+    await ensureHome(this.home);
+    const existing = await readJson(this.file(IDENTITY_FILE), null);
+    if (existing && !opts.force) throw new EdgeBookError("identity_exists", `identity_exists: an identity already exists at ${this.home} (use --force to overwrite)`);
+    const id = bundle.identity;
+    if (!id?.public_key_pem || id.agent_id !== stableIdFromPublicKey(id.public_key_pem)) {
+      throw new EdgeBookError("invalid_import", "Bundle agent_id does not match its public key");
+    }
+    await writeJson(this.file(IDENTITY_FILE), id, 384);
+    if (!await readJson(this.file(CONTACTS_FILE), null)) await writeJson(this.file(CONTACTS_FILE), {});
+    if (!await readJson(this.file(GRANTS_FILE), null)) await writeJson(this.file(GRANTS_FILE), {});
+    if (!await readJson(this.file(SEEN_MESSAGES_FILE), null)) await writeJson(this.file(SEEN_MESSAGES_FILE), []);
+    await this.writeCard();
+    await this.audit("identity.import", id.agent_id, { handle: id.handle });
+    return id;
+  }
   async config() {
     return readJson(this.file(CONFIG_FILE), {});
   }
@@ -288,6 +397,8 @@ var EdgeBookStore = class {
     if (input.direct_url !== void 0) next.direct_url = input.direct_url;
     if (input.relay_url !== void 0) next.relay_url = input.relay_url;
     if (input.notify_on_friend_request !== void 0) next.notify_on_friend_request = input.notify_on_friend_request;
+    if (input.notify_cmd !== void 0) next.notify_cmd = input.notify_cmd;
+    if (input.notify_types !== void 0) next.notify_types = input.notify_types;
     if (input.open_friend_requests !== void 0) next.open_friend_requests = input.open_friend_requests;
     if (input.inbound_max_per_peer !== void 0) next.inbound_max_per_peer = input.inbound_max_per_peer;
     if (input.inbound_max_global !== void 0) next.inbound_max_global = input.inbound_max_global;
@@ -331,6 +442,18 @@ var EdgeBookStore = class {
     await writeJson(this.file(CARD_FILE), card);
     return card;
   }
+  // Build a signed handle claim for the relay registry (spec-096). The relay
+  // verifies claim_sig + the card against the identity key before binding.
+  async buildHandleClaim() {
+    const identity = await this.identity();
+    if (!isValidHandle(identity.handle)) {
+      throw new EdgeBookError("invalid_handle", `invalid_handle: set a handle first (current: ${identity.handle})`);
+    }
+    const card = await loadCard(this.file(CARD_FILE));
+    const claimed_at = Date.now();
+    const claim_sig = signPayload({ handle: identity.handle, agent_did: identity.agent_id, claimed_at }, identity.private_key_pem);
+    return { handle: identity.handle, agent_did: identity.agent_id, card, claimed_at, claim_sig };
+  }
   // The friend-only profile: every field whose visibility resolves to "friends"
   // or "public". Signed; shared only with confirmed friends.
   async buildFriendProfile() {
@@ -1636,6 +1759,30 @@ var EdgeBookStore = class {
     if (envelope.type === "escalation_response") return this.applyEscalationResponse(envelope);
     throw new EdgeBookError("unsupported_envelope", `Unsupported envelope type: ${envelope.type}`);
   }
+  // Compute the transport-free notification intent for an applied inbound envelope,
+  // or null when the type is silent / unregistered. Delivery (invoking the host
+  // notify command) is the entry point's job — this stays transport-free.
+  async notificationIntent(envelope) {
+    const policy = NOTIFY_POLICIES[envelope.type];
+    if (!policy) return null;
+    const intent = await policy(envelope, this);
+    if (!intent) return null;
+    const types = (await this.config()).notify_types;
+    if (Array.isArray(types) && !types.includes(intent.kind)) return null;
+    return intent;
+  }
+  // Notification dedup ledger (keyed by NotificationIntent.dedup_key). Guards
+  // against double-notify across entry points, hook+cron, and mailbox redelivery.
+  async wasNotified(dedupKey) {
+    const ledger = await readJson(this.file(NOTIFIED_FILE), []);
+    return ledger.includes(dedupKey);
+  }
+  async recordNotified(dedupKey) {
+    const ledger = await readJson(this.file(NOTIFIED_FILE), []);
+    if (ledger.includes(dedupKey)) return;
+    ledger.push(dedupKey);
+    await writeJson(this.file(NOTIFIED_FILE), ledger);
+  }
   async audit(action, peerAgentId, details) {
     const audit_id = randomId("audit");
     await appendJsonl(this.file(AUDIT_FILE), {
@@ -2197,6 +2344,12 @@ var EdgeBookStore = class {
 };
 function validateCard(card) {
   if (card.schema !== "openclaw-agent-card/0.1") throw new EdgeBookError("invalid_card", "Unsupported Agent Card schema");
+  if (card.expires_at) {
+    const exp = Date.parse(card.expires_at);
+    if (!Number.isNaN(exp) && exp <= Date.now()) {
+      throw new EdgeBookError("card_expired", "Card/invite expired \u2014 ask the peer for a fresh handle or invite");
+    }
+  }
   if (!card.agent_id || !card.public_keys?.[0]?.public_key_pem) throw new EdgeBookError("invalid_card", "Agent Card is missing identity key");
   const expectedId = stableIdFromPublicKey(card.public_keys[0].public_key_pem);
   if (card.agent_id !== expectedId) throw new EdgeBookError("invalid_card", "Agent Card agent_id does not match public key");
@@ -2390,8 +2543,13 @@ async function writeCandidate(store, input) {
   await store.audit("candidate.write", candidate.agent_id ?? "", { candidate_id: candidate.candidate_id, source: candidate.source });
   return candidate;
 }
-function defaultProviders(registryLookup = async () => null) {
-  return [localContactProvider, inviteProvider, cardUrlProvider, cardFileProvider, makeRegistryProvider(registryLookup)];
+function defaultProviders(relayBase) {
+  const lookup = async (target) => {
+    if (!relayBase) return null;
+    const slug = target.startsWith("registry:") ? target.slice("registry:".length) : target;
+    return `${relayBase.replace(/\/$/, "")}/handle/${encodeURIComponent(slug)}`;
+  };
+  return [localContactProvider, inviteProvider, cardUrlProvider, cardFileProvider, makeRegistryProvider(lookup)];
 }
 async function resolveTarget(store, target, opts) {
   const ordered = [...opts.providers].sort((a, b) => b.priority - a.priority);
@@ -2436,20 +2594,29 @@ async function promoteCandidate(store, candidateId, note = "") {
   await store.audit("candidate.promoted", card.agent_id, { candidate_id: candidateId });
   return envelope;
 }
+var HANDLE_SLUG2 = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
 function makeRegistryProvider(lookup) {
   return {
     name: "registry",
     priority: 50,
     async resolve(_store, target) {
-      if (!target.startsWith("registry:")) return null;
+      const isExplicit = target.startsWith("registry:");
+      const slug = isExplicit ? target.slice("registry:".length) : target;
+      if (!isExplicit && !HANDLE_SLUG2.test(slug)) return null;
       const cardTarget = await lookup(target);
       if (!cardTarget) return null;
-      const card = await loadCard(cardTarget);
+      let card;
+      try {
+        card = await loadCard(cardTarget);
+      } catch (e) {
+        if (e instanceof EdgeBookError && e.code === "card_fetch_failed") return null;
+        throw e;
+      }
       return {
         kind: "card",
         card,
         agent_id: card.agent_id,
-        provenance: { source: "registry", confidence: "medium", display_name: card.handle, reason: "registry handle lookup" }
+        provenance: { source: "registry", confidence: "medium", display_name: card.handle, reason: "handle registry lookup" }
       };
     }
   };
@@ -4096,6 +4263,9 @@ function now2() {
 function keyId(agentKey) {
   return `agent_${crypto2.createHash("sha256").update(agentKey).digest("base64url").slice(0, 32)}`;
 }
+function shouldClaimHandle(handle) {
+  return !!handle && handle !== "agent.openclaw.local" && /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/.test(handle);
+}
 async function chmodBestEffort2(file, mode) {
   if (process.platform === "win32") return;
   try {
@@ -4423,6 +4593,21 @@ var EdgeBookDialoutClient = class {
     if (frame.type === "hello_ok") {
       this.opened?.resolve();
       this.opened = void 0;
+      try {
+        const identity = await this.store.identity();
+        if (shouldClaimHandle(identity.handle)) {
+          const claim = await this.store.buildHandleClaim();
+          this.send({
+            type: "handle_claim",
+            request_id: `hc-${claim.claimed_at}`,
+            handle: claim.handle,
+            card: claim.card,
+            claimed_at: claim.claimed_at,
+            claim_sig: claim.claim_sig
+          });
+        }
+      } catch {
+      }
       return;
     }
     if (frame.type === "hello_err") {
@@ -4485,6 +4670,7 @@ var EdgeBookDialoutClient = class {
       await this.handleMailboxDeliver(frame);
       return;
     }
+    if (frameType === "handle_claim_ok" || frameType === "handle_claim_err") return;
     if (frameType === "error") return;
     if (frame.type !== "host.api.request" && frame.type !== "api_request") return;
     const response = await this.handleApiRequest(frame);
@@ -4625,6 +4811,27 @@ var COMMAND_GROUPS = [
       }
     ]
   },
+  {
+    title: "Handle / Identity",
+    rows: [
+      {
+        usage: "handle set <slug>",
+        desc: "Claim a unique human handle (replaces the default)"
+      },
+      {
+        usage: "handle show",
+        desc: "Show your handle + DID fingerprint"
+      },
+      {
+        usage: "identity export [--path <file>]",
+        desc: "Export your identity keypair to carry to a new device"
+      },
+      {
+        usage: "identity import <path> [--force]",
+        desc: "Restore an exported identity (same DID, same handle)"
+      }
+    ]
+  },
   {
     title: "Profile",
     rows: [
@@ -4667,9 +4874,13 @@ var COMMAND_GROUPS = [
     title: "Hosted reader",
     rows: [
       {
-        usage: "dialout [--host <wss-url>]",
+        usage: "dialout [--host <wss-url>] [--notify-cmd <cmd>] [--no-cron-install]",
         desc: "Connect to the host mailbox (keeps your reader online; leave running)"
       },
+      {
+        usage: "ensure-notifier [--no-cron-install]",
+        desc: "Provision the host friend-request notifier (auto-runs on dialout; Hermes installs a cron)"
+      },
       {
         usage: "pair [--host <wss-url>] [--ttl-ms <ms>]",
         desc: "Mint a pairing code for the hosted browser reader"
@@ -4944,6 +5155,148 @@ function renderUsage() {
   return lines.join("\n");
 }
 
+// src/notify.ts
+import { spawn } from "child_process";
+async function deliverNotification(intent, opts) {
+  if (!opts.cmd || !opts.cmd.trim()) return { delivered: false, error: "no_notify_cmd" };
+  const timeoutMs = opts.timeoutMs ?? 1e4;
+  const env = {
+    ...process.env,
+    EB_NOTIFY_KIND: intent.kind,
+    EB_NOTIFY_FROM_ID: intent.from_id,
+    EB_NOTIFY_FROM_NAME: intent.from_name ?? "",
+    EB_NOTIFY_DEDUP_KEY: intent.dedup_key
+  };
+  for (const [k, v] of Object.entries(intent.meta ?? {})) {
+    env[`EB_NOTIFY_${k.toUpperCase()}`] = v;
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(r);
+    };
+    const child = spawn("/bin/sh", ["-c", opts.cmd], { env, stdio: ["pipe", "ignore", "pipe"] });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      done({ delivered: false, error: `timeout after ${timeoutMs}ms` });
+    }, timeoutMs);
+    let stderr = "";
+    child.stderr?.on("data", (d) => {
+      stderr += d.toString();
+    });
+    child.on("error", (e) => done({ delivered: false, error: e.message }));
+    child.on("close", (code) => {
+      if (code === 0) done({ delivered: true });
+      else done({ delivered: false, error: `exit ${code}${stderr ? `: ${stderr.trim()}` : ""}` });
+    });
+    child.stdin?.on("error", () => void 0);
+    child.stdin?.end(intent.message ?? "");
+  });
+}
+function resolveNotifyCmd(input) {
+  for (const v of [input.flag, input.env, input.config]) {
+    if (typeof v === "string" && v.trim()) return v;
+  }
+  return void 0;
+}
+async function notifyInbound(store, envelope, opts) {
+  if (!opts.cmd || !opts.cmd.trim()) return { notified: false, reason: "no_notify_cmd" };
+  const intent = await store.notificationIntent(envelope);
+  if (!intent) return { notified: false, reason: "silent" };
+  if (await store.wasNotified(intent.dedup_key)) return { notified: false, reason: "already_notified" };
+  const res = await deliverNotification(intent, opts);
+  if (!res.delivered) {
+    await store.audit("notify.failed", intent.from_id, { kind: intent.kind, dedup_key: intent.dedup_key, error: res.error ?? "" });
+    return { notified: false, reason: res.error };
+  }
+  await store.recordNotified(intent.dedup_key);
+  if (intent.kind === "friend_request") {
+    try {
+      await store.markFriendRequestNotified(intent.from_id);
+    } catch {
+    }
+  }
+  await store.audit("notify.delivered", intent.from_id, { kind: intent.kind, dedup_key: intent.dedup_key, channel: "hook" });
+  return { notified: true };
+}
+function makeNotifyOnEnvelope(store, cmd) {
+  return async (envelope, result) => {
+    if (!result.applied || !cmd) return;
+    try {
+      await notifyInbound(store, envelope, { cmd });
+    } catch {
+    }
+  };
+}
+
+// src/host-cron.ts
+import { existsSync } from "fs";
+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"];
+function buildFriendRequestsPrompt(home) {
+  return [
+    "You are the Edge Book friend-request notifier. Tell the human on their Telegram when someone has asked to connect on Edge Book. Hermes delivers your final assistant reply to their chat.",
+    "",
+    "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.",
+    "",
+    "1. List pending requests (run once):",
+    `   edge-book friend pending --home ${home} --json`,
+    "   If edge-book is not on PATH, use: npm exec -y edge-book@0.11.0 -- friend pending --home " + home + " --json",
+    "   If the command errors, Edge Book is unavailable, or the list is empty ([]) \u2192 end your turn with exactly [SILENT].",
+    "",
+    '2. Otherwise write ONE short, warm message. For each requester use their display_name; say they asked to connect on Edge Book and that the human can reply "yes" to connect or ignore to leave it pending. No internal IDs, no JSON.',
+    "",
+    "3. Mark each surfaced request notified so it is never re-sent (once per requester):",
+    `   edge-book friend mark-notified <agent_id> --home ${home}`
+  ].join("\n");
+}
+function ensureNotifierCron(opts) {
+  if (opts.disabled) return { status: "disabled" };
+  if (!opts.runner.hermesBin) return { status: "host_unsupported" };
+  let listing;
+  try {
+    listing = opts.runner.list();
+  } catch (e) {
+    return { status: "error", detail: e instanceof Error ? e.message : String(e) };
+  }
+  if (listing.includes(FRIEND_REQUESTS_CRON_NAME)) return { status: "already_present" };
+  const schedule = opts.schedule ?? DEFAULT_FRIEND_REQUESTS_SCHEDULE;
+  const prompt = buildFriendRequestsPrompt(opts.home);
+  const args = [
+    "cron",
+    "create",
+    schedule,
+    prompt,
+    "--name",
+    FRIEND_REQUESTS_CRON_NAME,
+    "--deliver",
+    "telegram",
+    "--workdir",
+    opts.home
+  ];
+  try {
+    opts.runner.create(args);
+    return { status: "installed" };
+  } catch (e) {
+    return { status: "error", detail: e instanceof Error ? e.message : String(e) };
+  }
+}
+function defaultHermesRunner() {
+  const bin = HERMES_BIN_CANDIDATES.find((p) => existsSync(p)) ?? null;
+  return {
+    hermesBin: bin,
+    list: () => bin ? execFileSync(bin, ["cron", "list"], { encoding: "utf8" }) : "",
+    create: (args) => {
+      if (bin) execFileSync(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+    }
+  };
+}
+
 // src/cli.ts
 function usage() {
   return renderUsage();
@@ -4961,6 +5314,9 @@ function parseHome(args, ctx) {
 function parseHost(args, ctx) {
   return takeFlag(args, "--host") || ctx.defaultHost || process.env.EDGE_BOOK_HOST || DEFAULT_DIALOUT_HOST;
 }
+function relayBaseFromHost(host) {
+  return host.replace(/\/agent\/ws\/?$/, "").replace(/^wss:\/\//, "https://").replace(/^ws:\/\//, "http://");
+}
 function requireArg(value, label) {
   if (!value) throw new EdgeBookError("missing_arg", `Missing ${label}`);
   return value;
@@ -5036,7 +5392,8 @@ async function handleCli(inputArgs, ctx = {}) {
     return { text: usage() };
   }
   if (command === "init") {
-    const handle = takeFlag(args, "--handle");
+    const rawHandle = takeFlag(args, "--handle");
+    const handle = rawHandle !== void 0 ? slugifyHandle(rawHandle) : void 0;
     const displayName = takeFlag(args, "--name");
     const ownerLabel = takeFlag(args, "--owner");
     const shareOwner = takeBoolFlag(args, "--share-owner");
@@ -5049,9 +5406,51 @@ Two-tier profile:
   \u2022 agent name (display_name): "${identity.display_name}" \u2014 always public on your card.
   \u2022 your profile (name, bio, location, socials): default visible to FRIENDS only, hidden on the public card.
 Set it: edge-book profile set --name "<you>" --bio "..." --social telegram=@you
-Tune visibility: edge-book profile visibility bio=off telegram=public name=public`;
+Tune visibility: edge-book profile visibility bio=off telegram=public name=public
+
+Notifications (so inbound friend requests & messages reach you in real time):
+  Set a host notify command \u2014 Edge Book stays transport-free and pipes the message to it.
+  edge-book dialout --notify-cmd "<deliver-to-your-channel>"
+  (or set EDGE_BOOK_NOTIFY_CMD, or config.notify_cmd). Without it, inbound items are silent
+  until a fallback poller surfaces them.`;
     return { text: note, json: identity };
   }
+  if (command === "handle") {
+    const action = args.shift();
+    if (action === "set") {
+      const id = await store.setHandle(slugifyHandle(requireArg(args.shift(), "handle set <slug>")));
+      return { text: `Handle set: ${id.handle} (${id.agent_id})`, json: { handle: id.handle, agent_id: id.agent_id } };
+    }
+    if (action === "show") {
+      const id = await store.identity();
+      return { text: `${id.handle}
+${id.agent_id}`, json: { handle: id.handle, agent_id: id.agent_id } };
+    }
+    throw new EdgeBookError("unknown_action", `Unknown handle action: ${action} (use "set" or "show")`);
+  }
+  if (command === "identity") {
+    const action = args.shift();
+    if (action === "export") {
+      const bundle = await store.exportIdentity();
+      const p = takeFlag(args, "--path");
+      if (p) {
+        const target = path4.resolve(p);
+        await fs4.mkdir(path4.dirname(target), { recursive: true });
+        await fs4.writeFile(target, `${JSON.stringify(bundle, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+        return { text: `Identity exported \u2192 ${target}`, json: { path: target } };
+      }
+      return { text: JSON.stringify(bundle), json: bundle };
+    }
+    if (action === "import") {
+      const source = requireArg(args.shift(), "identity import <path>");
+      const force = takeBoolFlag(args, "--force");
+      const bundle = JSON.parse(await fs4.readFile(path4.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 } };
+    }
+    throw new EdgeBookError("unknown_action", `Unknown identity action: ${action} (use "export" or "import")`);
+  }
   if (command === "profile") {
     const action = args.shift() || "show";
     if (action === "show") {
@@ -5176,7 +5575,8 @@ visibility: ${JSON.stringify(p.visibility ?? {})}`,
   }
   if (command === "resolve") {
     const target = requireArg(args.shift(), "target");
-    const result = await resolveTarget(store, target, { providers: defaultProviders() });
+    const relayBase = relayBaseFromHost(parseHost(args, ctx));
+    const result = await resolveTarget(store, target, { providers: defaultProviders(relayBase) });
     const label = result.agent_id ?? result.candidates?.[0]?.candidate_id ?? "";
     return { text: `${result.status}  ${label}
 next: ${result.next_action}`, json: result };
@@ -5474,11 +5874,42 @@ next: ${result.next_action}`, json: result };
   }
   if (command === "dialout") {
     const hostUrl = parseHost(args, ctx);
-    const client = new EdgeBookDialoutClient({ home, host: hostUrl, socketFactory: ctx.socketFactory });
+    const store2 = new EdgeBookStore({ home });
+    const notifyCmd = resolveNotifyCmd({
+      flag: takeFlag(args, "--notify-cmd"),
+      env: process.env.EDGE_BOOK_NOTIFY_CMD,
+      config: (await store2.config()).notify_cmd
+    });
+    const client = new EdgeBookDialoutClient({
+      home,
+      host: hostUrl,
+      socketFactory: ctx.socketFactory,
+      onEnvelope: makeNotifyOnEnvelope(store2, notifyCmd)
+    });
     await client.start();
-    console.log(`Edge Book dial-out connected to ${hostUrl}`);
+    console.log(`Edge Book dial-out connected to ${hostUrl}${notifyCmd ? " (notify hook active)" : ""}`);
+    try {
+      const disabled = takeBoolFlag(args, "--no-cron-install") || process.env.EDGE_BOOK_NO_CRON_INSTALL === "1";
+      const res = ensureNotifierCron({ runner: defaultHermesRunner(), home, disabled });
+      if (res.status === "installed") console.log(`  \u21B3 notifier cron self-installed ("Edge Book \u2014 friend requests", every 20m \u2192 telegram)`);
+      else if (res.status === "error") console.log(`  \u21B3 notifier cron install skipped: ${res.detail}`);
+    } catch (e) {
+      console.log(`  \u21B3 notifier cron install skipped: ${e instanceof Error ? e.message : String(e)}`);
+    }
     await new Promise(() => void 0);
   }
+  if (command === "ensure-notifier") {
+    const disabled = takeBoolFlag(args, "--no-cron-install") || process.env.EDGE_BOOK_NO_CRON_INSTALL === "1";
+    const res = ensureNotifierCron({ runner: defaultHermesRunner(), home, disabled });
+    const msg = {
+      installed: 'Installed notifier cron "Edge Book \u2014 friend requests" (every 20m \u2192 telegram).',
+      already_present: "Notifier cron already present \u2014 nothing to do.",
+      host_unsupported: "No recognized host (Hermes) detected \u2014 nothing installed. Set notify_cmd for real-time delivery on hosts with a sender.",
+      disabled: "Cron self-install disabled.",
+      error: `Could not install notifier cron: ${res.detail ?? ""}`
+    };
+    return { text: msg[res.status] ?? res.status, json: res };
+  }
   if (command === "pair") {
     const hostUrl = parseHost(args, ctx);
     const ttlMs = Number(takeFlag(args, "--ttl-ms") || `${5 * 60 * 1e3}`);

package/package.json

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