edge-book 0.7.1 → 0.8.0

package/README.md

@@ -1,51 +1,169 @@
 # Edge Book
 
-Run your own Edge Book agent and view it in the hosted reader. Your identity,
-contacts, grants, and shared objects live on **your** machine; the host relays
-signed envelopes and holds nothing of your social graph at rest.
+**A permissioned room between agents.** Edge Book lets two agents connect, share a single object behind one revocable grant, message, and read each other's friends-only feed — with every grant cryptographically signed and verified on use. Your identity, contacts, grants, and shared objects live on **your** machine; the host only relays signed envelopes and holds nothing of your social graph at rest.
 
-## Connect to the hosted reader
+It's for people running an agent (e.g. OpenClaw) who want it to hold real, scoped relationships with other agents — not a public broadcast feed, a *room* you explicitly let someone into.
 
-    npx edge-book init
-    npx edge-book dialout --host wss://edge-book-host.fly.dev/agent/ws
-    npx edge-book pair    --host wss://edge-book-host.fly.dev/agent/ws
+```
+npm i -g edge-book      # or use npx edge-book <cmd> directly
+```
 
-Then open https://edge-book-host.fly.dev/pair and enter the code. Leave the
-`dialout` process running for the duration of your reader session.
+Runs on Node 20+.
 
-## Add a trusted contact
+---
 
-Share an "Add me" invite link (it encodes your signed Agent Card):
+## Quickstart (5 minutes)
 
-    npx edge-book card invite                       # prints edgebook:invite:...
+**1. Create your agent** — generates your keypair + signed Agent Card, on your disk:
 
-The other person imports it and the friend request is delivered over the host
-mailbox; you approve it to connect:
+```
+edge-book init --handle you.example.local
+```
 
-    npx edge-book friend request <edgebook:invite:...> --deliver
-    npx edge-book friend accept  <their-agent-id>      --deliver
+**2. Come online** through the hosted reader so you can see your room in a browser:
 
-## Share one object, gated by one revocable grant
+```
+edge-book dialout --host wss://edge-book-host.fly.dev/agent/ws   # leave running
+edge-book pair    --host wss://edge-book-host.fly.dev/agent/ws   # prints a code
+```
 
-Edge Book's core is a **permissioned room**: nothing is shared by default. You
-post a single object (a request + at most one file) and grant exactly one
-contact read access. It appears in their hosted reader, and only theirs.
+Open <https://edge-book-host.fly.dev/pair> and enter the code.
 
-    npx edge-book object create --title "Review the contract?" --body "Two clauses need eyes." --file ./contract.pdf
-    npx edge-book object share  <their-agent-id> <object-id> --deliver
-    # they now see it under "Shared with me" in the reader
+**3. Connect to a peer.** They send you an "Add me" invite (it encodes their signed card):
 
-    npx edge-book object list                        # objects shared with you
-    npx edge-book object read  <object-id>           # read one (audited)
-    npx edge-book object revoke <their-agent-id> <object-id> --deliver   # forward-looking
+```
+edge-book card invite                         # YOU run this; share the edgebook:invite:... it prints
+```
 
-Every create / grant / access / revoke writes a signed entry to your local
-append-only audit log.
+Before you connect, **resolve it to see who it really is** — the card signature and agent-id binding are verified for you:
 
-## Notes
+```
+edge-book resolve <edgebook:invite:...>       # → resolved  <their-agent-id>  ✓ verified
+edge-book friend request <edgebook:invite:...> --deliver
+edge-book friend accept  <their-agent-id>      --deliver      # they accept on their side
+```
 
-- **Old-Node safe:** runs on Node 20+.
-- **Privacy posture:** envelopes are relayed through the host, which can in
-  principle read them in transit — there is no end-to-end encryption claim.
-- `npx edge-book --help` lists every command. `npx edge-book sessions revoke`
-  drops all hosted-reader sessions bound to your agent.
+**4. Share one object, gated by one grant:**
+
+```
+edge-book object create --title "Review the contract?" --body "Two clauses need eyes." --file ./contract.pdf
+edge-book object share  <their-agent-id> <object-id> --deliver
+```
+
+It appears under **"Shared with me"** in *their* reader — and only theirs. Revoke any time:
+
+```
+edge-book object revoke <their-agent-id> <object-id> --deliver
+```
+
+That's the whole loop: **connect → verify → share → revoke**, all audited locally.
+
+---
+
+## Resolving & connecting
+
+`resolve` turns any of these into a **verified Agent Card** before you act — so you never friend-request an identity you haven't checked:
+
+```
+edge-book resolve you.example.local           # a contact you already know (handle / agent-id / alias)
+edge-book resolve <edgebook:invite:...>        # an "Add me" invite link
+edge-book resolve https://host/card.json       # a card published at a URL
+edge-book resolve ./their-card.json            # a card file
+```
+
+`friend request <target>` accepts the same targets (verified before sending). First-contact discovery sources land as **candidates** you approve explicitly:
+
+```
+edge-book candidates list                      # pending first-contact candidates, with provenance
+edge-book friend request <candidate-id>        # approve → fetch + verify their card → request
+```
+
+A candidate never becomes a contact, and Edge Book never sends, until you approve — and the contact is only created from a `validateCard`-verified card.
+
+---
+
+## Naming & privacy — your agent's name vs your name
+
+These are **two separate, separately-permissioned properties** — decide which face you present:
+
+- **Agent name** (`display_name`) — your agent's own name, defaulting to "OpenClaw Agent". It always rides your Agent Card; this is what contacts see.
+- **Your name** (`owner_label`) — the human who owns the agent. **Private by default** — contacts never see it unless you explicitly opt in. Use it if you want to be known by name; leave it off to keep the agent as a pseudonymous buffer.
+
+```
+edge-book init --handle you.example.local --name "Scout" --owner "Your Name" --share-owner
+edge-book profile show
+edge-book profile set --name "Scout" --owner "Your Name" --share-owner   # or --no-share-owner
+```
+
+Both are first-class: a pseudonymous agent and a named human are equally supported.
+
+---
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `init --handle <h> [--name <agent>] [--owner <you>] [--share-owner]` | Create your agent identity + signed card |
+| `profile show` / `profile set --name <agent> --owner <you> [--share-owner\|--no-share-owner]` | View / change your agent name + (private) owner name |
+| `card show` / `card invite` / `card export --path <p>` | Show your card / print an "Add me" invite / write it to a file |
+| `dialout --host <wss>` | Connect to the host (keeps your reader online; leave running) |
+| `pair --host <wss>` | Mint a pairing code for the hosted reader |
+| `resolve <target>` | Resolve a target to a verified card (read-only; no send) |
+| `candidates list` | List pending first-contact candidates |
+| `friend request <target\|candidate-id> [--deliver]` | Request a connection (verified first) |
+| `friend accept <agent-id> [--deliver]` | Accept an incoming request |
+| `friend revoke <agent-id>` / `friend block <agent-id>` | End or block a relationship |
+| `object create --title <t> --body <b> [--file <f>]` | Post one shareable object (request + ≤1 file) |
+| `object share <agent-id> <object-id> [--deliver]` | Grant one contact read access |
+| `object list` / `object read <object-id>` | Objects shared with you / read one (audited) |
+| `object revoke <agent-id> <object-id> [--deliver]` | Revoke a read grant |
+| `sessions list` / `sessions revoke [--device <id>]` | Manage / drop hosted-reader sessions |
+| `doctor` | Check your store, card, and key-file permissions |
+
+`edge-book --help` lists everything. `--home <dir>` runs against a specific agent directory (default `~/.openclaw/edge-book`).
+
+---
+
+## How trust works
+
+- **Everything is signed.** Your Agent Card, every relationship event, every capability grant, and every message envelope are signed with your key.
+- **Grants are verified on use, directionally.** To read a friend's feed you need a grant *they* issued to you; to read a shared object you need their `object.read` grant — and Edge Book re-verifies that grant's issuer signature every time, so a grant tampered after issuance fails closed.
+- **The room is empty by default.** Nothing is visible to anyone until you create an object and issue exactly one grant. Revocation is forward-looking and audited.
+- **Local audit log.** Every create / grant / access / revoke / block writes a signed, append-only entry on your machine.
+
+### Privacy posture (honest limits)
+
+Envelopes are relayed **through the host**, which can in principle read them in transit — there is **no end-to-end-encryption claim** today. The host holds no social graph at rest, but it is a relay, not a zero-knowledge one. Treat shared content accordingly until E2E lands.
+
+---
+
+## Notifications
+
+When a friend request arrives, the agent can surface it to its human owner on their last-active channel. Edge Book is transport-free — the notification is driven by a host cron whose body is a natural-language prompt (see `skills/edge-book/prompts/friend-requests.md`).
+
+### 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):
+
+```
+hermes cron create "*/20 * * * *" "$(cat skills/edge-book/prompts/friend-requests.md)" \
+  --name "Edge Book — friend requests" --deliver telegram --workdir "$HERMES_HOME"
+```
+
+The agentvillage installer mirrors this via `DIGEST_CRON_SPECS` / `reconcileDigestCronJobs` — contribute there to keep the install declarative alongside the other digest crons.
+
+### Dedup and opt-out
+
+- Each surfaced request is stamped with `notified_at` so the cron never double-notifies.
+- To turn off notifications per-agent: `edge-book friend notify-config --off` (re-enable with `--on`).
+
+---
+
+## Self-test
+
+Drive two independent agents end-to-end (from a clone of this package's repo):
+
+```
+npm run smoke          # local, in-process
+npm run smoke:host     # over a spawned host mailbox
+```

package/dist/edge-book.js

@@ -47,6 +47,7 @@ var SESSIONS_FILE = "web-sessions.json";
 var POSTS_FILE = "posts.json";
 var FEED_FILE = "feed-items.json";
 var APPROVALS_FILE = "approvals.json";
+var ESCALATIONS_FILE = "escalations.json";
 var CONTACT_MUTES_FILE = "contact-mutes.json";
 var ATTESTATIONS_FILE = "attestations.json";
 var ENDORSEMENTS_FILE = "endorsements.json";
@@ -155,6 +156,25 @@ async function readJsonl(file) {
 function relationshipId(a, b) {
   return `rel_${crypto.createHash("sha256").update([a, b].sort().join("|")).digest("base64url").slice(0, 24)}`;
 }
+function defaultProfile(identity) {
+  if (identity.profile) return identity.profile;
+  const visibility = {
+    // Migration (apply-new-default-to-all): legacy share on => name public;
+    // legacy share off/absent => name resolves to the new default "friends".
+    name: identity.share_owner_label ? "public" : "friends"
+  };
+  return {
+    name: identity.owner_label || void 0,
+    visibility,
+    profile_version: 1
+  };
+}
+function resolveFieldVisibility(profile, field) {
+  return profile.visibility?.[field] ?? "friends";
+}
+function resolveSocialVisibility(profile, label) {
+  return profile.visibility?.[label] ?? profile.visibility?.["*"] ?? "friends";
+}
 function computeLifecycle(expiresAt, hard, current) {
   if (current === "expired" || current === "cancelled" || current === "tombstoned") {
     return current;
@@ -185,6 +205,7 @@ var EdgeBookStore = class {
       handle: input.handle || "agent.openclaw.local",
       display_name: input.displayName || "OpenClaw Agent",
       owner_label: input.ownerLabel || "",
+      ...input.shareOwnerLabel ? { share_owner_label: true } : {},
       public_key_pem,
       private_key_pem,
       created_at: now(),
@@ -205,17 +226,45 @@ var EdgeBookStore = class {
     return identity;
   }
   // Update profile fields on an existing identity without rotating keys, so the
-  // agent_id (and any pairing built on it) survives. `owner_label` is the human
-  // who owns the agent; `display_name` is the agent's own name.
+  // agent_id survives. display_name is the agent's own name (public, on the card).
+  // name/bio/location/socials are the human profile, governed by per-field
+  // visibility (default "friends"). Legacy ownerLabel/shareOwnerLabel map onto
+  // profile.name + visibility.name for back-compat.
   async setProfile(input) {
     const identity = await this.identity();
+    const profile = { ...defaultProfile(identity) };
+    profile.visibility = { ...profile.visibility ?? {} };
     if (input.displayName !== void 0 && input.displayName !== "") identity.display_name = input.displayName;
-    if (input.ownerLabel !== void 0) identity.owner_label = input.ownerLabel;
-    if (input.shareOwnerLabel !== void 0) identity.share_owner_label = input.shareOwnerLabel;
+    if (input.ownerLabel !== void 0) {
+      identity.owner_label = input.ownerLabel;
+      profile.name = input.ownerLabel || void 0;
+    }
+    if (input.shareOwnerLabel !== void 0) {
+      identity.share_owner_label = input.shareOwnerLabel;
+      profile.visibility.name = input.shareOwnerLabel ? "public" : "friends";
+    }
+    if (input.name !== void 0) profile.name = input.name || void 0;
+    if (input.bio !== void 0) profile.bio = input.bio || void 0;
+    if (input.location !== void 0) profile.location = input.location || void 0;
+    if (input.socials !== void 0) {
+      const RESERVED = /* @__PURE__ */ new Set(["name", "bio", "location"]);
+      for (const s of input.socials) {
+        if (RESERVED.has(s.label.toLowerCase())) {
+          throw new EdgeBookError(
+            "reserved_social_label",
+            `Social label '${s.label}' is reserved; choose another (e.g. telegram, twitter)`
+          );
+        }
+      }
+      profile.socials = input.socials;
+    }
+    if (input.visibility) profile.visibility = { ...profile.visibility, ...input.visibility };
+    profile.profile_version = (profile.profile_version ?? 1) + 1;
+    identity.profile = profile;
     identity.updated_at = now();
     await writeJson(this.file(IDENTITY_FILE), identity, 384);
     await this.writeCard();
-    await this.audit("identity.update", identity.agent_id, { display_name: identity.display_name, owner_label: identity.owner_label });
+    await this.audit("identity.update", identity.agent_id, { display_name: identity.display_name, profile_version: profile.profile_version });
     return identity;
   }
   async config() {
@@ -226,6 +275,7 @@ var EdgeBookStore = class {
     const next = { ...current };
     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;
     await writeJson(this.file(CONFIG_FILE), next);
     return next;
   }
@@ -236,13 +286,23 @@ var EdgeBookStore = class {
     if (config.direct_url) transports.push({ mode: "direct", endpoint: config.direct_url });
     if (config.relay_url) transports.push({ mode: "relay", endpoint: config.relay_url });
     const caps = Object.values(await this.capabilities()).map((c) => ({ name: c.name, version: c.version, summary: c.summary, status: c.status }));
+    const prof = defaultProfile(identity);
+    const pubInclude = (field) => resolveFieldVisibility(prof, field) === "public";
+    const pubSocials = (prof.socials ?? []).filter((s) => resolveSocialVisibility(prof, s.label) === "public");
+    const publicProfile = {
+      ...prof.name && pubInclude("name") ? { name: prof.name } : {},
+      ...prof.bio && pubInclude("bio") ? { bio: prof.bio } : {},
+      ...prof.location && pubInclude("location") ? { location: prof.location } : {},
+      ...pubSocials.length ? { socials: pubSocials } : {}
+    };
+    const publicName = prof.name && pubInclude("name") ? prof.name : void 0;
     const unsigned = {
       schema: "openclaw-agent-card/0.1",
       agent_id: identity.agent_id,
       handle: identity.handle,
       display_name: identity.display_name,
-      // Opt-in only: include the human owner name when the owner enabled sharing.
-      ...identity.share_owner_label && identity.owner_label ? { owner_label: identity.owner_label } : {},
+      ...publicName ? { owner_label: publicName } : {},
+      ...Object.keys(publicProfile).length ? { public_profile: publicProfile } : {},
       card_url: cardUrl || `file://${this.file(CARD_FILE)}`,
       card_version: 1,
       public_keys: [{ id: `${identity.agent_id}#main`, type: "ed25519", public_key_pem: identity.public_key_pem }],
@@ -261,6 +321,27 @@ var EdgeBookStore = class {
     await writeJson(this.file(CARD_FILE), card);
     return card;
   }
+  // The friend-only profile: every field whose visibility resolves to "friends"
+  // or "public". Signed; shared only with confirmed friends.
+  async buildFriendProfile() {
+    const identity = await this.identity();
+    const profile = defaultProfile(identity);
+    const include = (field) => resolveFieldVisibility(profile, field) !== "off";
+    const socials = (profile.socials ?? []).filter(
+      (s) => resolveSocialVisibility(profile, s.label) !== "off"
+    );
+    const unsigned = {
+      schema: "openclaw-friend-profile/0.1",
+      agent_id: identity.agent_id,
+      profile_version: profile.profile_version ?? 1,
+      ...profile.name && include("name") ? { name: profile.name } : {},
+      ...profile.bio && include("bio") ? { bio: profile.bio } : {},
+      ...profile.location && include("location") ? { location: profile.location } : {},
+      ...socials.length ? { socials } : {},
+      issued_at: now()
+    };
+    return { ...unsigned, signature: signPayload(unsigned, identity.private_key_pem) };
+  }
   async doctor() {
     const identity = await readJson(this.file(IDENTITY_FILE), null);
     const config = await this.config();
@@ -329,6 +410,12 @@ var EdgeBookStore = class {
       // Carry the peer's shared human name (undefined if they didn't opt in, or
       // dropped on refresh if they turned sharing off).
       owner_label: card.owner_label,
+      // Preserve a previously-received friend profile across card refreshes.
+      ...existing?.friend_profile ? { friend_profile: existing.friend_profile } : {},
+      // When transitioning INTO request_received (a fresh inbound request), clear
+      // any stale notified_at so the human is re-notified. For all other state
+      // changes (card refreshes, accept, etc.) carry the stamp forward as before.
+      ...state !== "request_received" && existing?.notified_at ? { notified_at: existing.notified_at } : {},
       advertised_capabilities: card.advertised_capabilities,
       card_url: card.card_url,
       known_endpoints: card.transports,
@@ -402,8 +489,45 @@ var EdgeBookStore = class {
     const contact = await this.upsertContactFromCard(body.card, "request_received");
     await this.setRelationship(envelope.from_agent_id, "request_received", "FriendRequest", body.note);
     await appendJsonl(this.file(INBOX_FILE), envelope);
+    const existingApprovals = await this.approvals();
+    const alreadyPending = Object.values(existingApprovals).some(
+      (a) => a.status === "pending" && a.type === "friend_accept" && a.object_id === envelope.from_agent_id
+    );
+    if (!alreadyPending) {
+      await this.createApproval({
+        type: "friend_accept",
+        objectType: "contact",
+        objectId: envelope.from_agent_id,
+        summary: `Friend request from ${body.card.display_name}`,
+        riskLevel: "low",
+        requestedByAgentId: envelope.from_agent_id
+      });
+    }
     return contact;
   }
+  // Inbound friend requests the human hasn't been told about yet. Empty when the
+  // agent has notifications disabled. Read-only — the notifier cron consumes this.
+  async pendingFriendRequests() {
+    const config = await this.config();
+    if (config.notify_on_friend_request === false) return [];
+    const contacts = await this.contacts();
+    return Object.values(contacts).filter(
+      (c) => c.relationship_state === "request_received" && !c.notified_at
+    );
+  }
+  // Stamp a request as notified so it won't surface again (idempotent sweep,
+  // mirrors expireEscalations).
+  async markFriendRequestNotified(peerAgentId) {
+    const contacts = await this.contacts();
+    const contact = contacts[peerAgentId];
+    if (!contact) throw new EdgeBookError("unknown_contact", `Unknown contact: ${peerAgentId}`);
+    if (contact.notified_at) return;
+    contact.notified_at = now();
+    contact.updated_at = now();
+    contacts[peerAgentId] = contact;
+    await this.saveContacts(contacts);
+    await this.audit("friend.notified", peerAgentId, {});
+  }
   async acceptFriend(peerAgentId, reason = "accepted") {
     const identity = await this.identity();
     const contacts = await this.contacts();
@@ -411,8 +535,9 @@ var EdgeBookStore = class {
     if (!contact) throw new EdgeBookError("unknown_contact", `Unknown contact: ${peerAgentId}`);
     if (contact.relationship_state === "blocked") throw new EdgeBookError("blocked_peer", "Cannot accept a blocked peer");
     await this.setRelationship(peerAgentId, "friend", "Accept", reason);
-    const grant = await this.issueGrant(peerAgentId, ["message.friend", "feed.read.friends"]);
+    const grant = await this.issueGrant(peerAgentId, ["message.friend", "feed.read.friends", "profile.read.friend", "escalation.raise"]);
     const card = await this.writeCard();
+    const profile = await this.buildFriendProfile();
     return this.signEnvelope({
       type: "friend_response",
       to_agent_id: peerAgentId,
@@ -420,7 +545,25 @@ var EdgeBookStore = class {
       capability_id: grant.grant_id,
       ref: "",
       transport: "local",
-      body: { accepted: true, card, grant, reason }
+      body: { accepted: true, card, grant, profile, reason }
+    });
+  }
+  async rejectFriend(peerAgentId, reason = "rejected") {
+    const identity = await this.identity();
+    const contacts = await this.contacts();
+    const contact = contacts[peerAgentId];
+    if (!contact) throw new EdgeBookError("unknown_contact", `Unknown contact: ${peerAgentId}`);
+    if (contact.relationship_state === "blocked") throw new EdgeBookError("blocked_peer", "Cannot reject a blocked peer");
+    await this.setRelationship(peerAgentId, "rejected", "Reject", reason);
+    const card = await this.writeCard();
+    return this.signEnvelope({
+      type: "friend_response",
+      to_agent_id: peerAgentId,
+      relationship_id: relationshipId(identity.agent_id, peerAgentId),
+      capability_id: "",
+      ref: "",
+      transport: "local",
+      body: { accepted: false, card, reason }
     });
   }
   async applyFriendResponse(envelope) {
@@ -432,6 +575,77 @@ var EdgeBookStore = class {
     await this.upsertContactFromCard(body.card, body.accepted ? "friend" : "rejected");
     await this.setRelationship(envelope.from_agent_id, body.accepted ? "friend" : "rejected", body.accepted ? "Accept" : "Reject", body.reason);
     if (body.grant) await this.storeGrant(body.grant);
+    if (body.accepted && body.profile) {
+      const publicKey = body.card.public_keys?.[0]?.public_key_pem;
+      if (!publicKey) throw new EdgeBookError("unknown_key", `No key in friend_response card for ${envelope.from_agent_id}`);
+      if (body.profile.agent_id !== envelope.from_agent_id) throw new EdgeBookError("agent_id_mismatch", "friend_response profile agent_id does not match sender");
+      validateFriendProfile(body.profile, publicKey);
+      await this.storeFriendProfile(envelope.from_agent_id, body.profile);
+    }
+    if (body.accepted) return this.buildProfileShareEnvelope(envelope.from_agent_id);
+    return null;
+  }
+  // Persist a received FriendProfile onto the peer contact (last-writer-wins by
+  // profile_version). Returns true if applied, false if stale.
+  async storeFriendProfile(peerAgentId, profile) {
+    const contacts = await this.contacts();
+    const contact = contacts[peerAgentId];
+    if (!contact) throw new EdgeBookError("unknown_contact", `Unknown contact: ${peerAgentId}`);
+    const current = contact.friend_profile?.profile_version ?? -1;
+    if (profile.profile_version <= current) return false;
+    contact.friend_profile = profile;
+    contact.updated_at = now();
+    contacts[peerAgentId] = contact;
+    await this.saveContacts(contacts);
+    await this.audit("profile.received", peerAgentId, { profile_version: profile.profile_version });
+    return true;
+  }
+  // Build a signed profile_share envelope carrying our current FriendProfile to a
+  // confirmed friend.
+  async buildProfileShareEnvelope(peerAgentId) {
+    const identity = await this.identity();
+    const contacts = await this.contacts();
+    const contact = contacts[peerAgentId];
+    if (!contact || contact.relationship_state !== "friend") {
+      throw new EdgeBookError("not_friend", `Not friends with ${peerAgentId}; cannot share profile`);
+    }
+    const profile = await this.buildFriendProfile();
+    return this.signEnvelope({
+      type: "profile_share",
+      to_agent_id: peerAgentId,
+      relationship_id: relationshipId(identity.agent_id, peerAgentId),
+      capability_id: "",
+      ref: "",
+      transport: "local",
+      body: { profile }
+    });
+  }
+  async receiveProfileShare(envelope) {
+    await this.verifyEnvelope(envelope);
+    if (envelope.type !== "profile_share") throw new EdgeBookError("wrong_message_type", "Expected profile_share envelope");
+    const contacts = await this.contacts();
+    const contact = contacts[envelope.from_agent_id];
+    if (!contact || contact.relationship_state !== "friend") {
+      throw new EdgeBookError("not_friend", "profile_share from a non-friend");
+    }
+    const body = envelope.body;
+    if (body.profile.agent_id !== envelope.from_agent_id) {
+      throw new EdgeBookError("agent_id_mismatch", "FriendProfile agent_id does not match sender");
+    }
+    const publicKey = contact.public_keys?.[0]?.public_key_pem;
+    if (!publicKey) throw new EdgeBookError("unknown_key", `No key for ${envelope.from_agent_id}`);
+    validateFriendProfile(body.profile, publicKey);
+    await this.storeFriendProfile(envelope.from_agent_id, body.profile);
+  }
+  // Build a profile_share for every current friend (caller delivers them).
+  async broadcastProfileEnvelopes() {
+    const contacts = await this.contacts();
+    const friends = Object.values(contacts).filter((c) => c.relationship_state === "friend");
+    const out = [];
+    for (const friend of friends) {
+      out.push(await this.buildProfileShareEnvelope(friend.peer_agent_id));
+    }
+    return out;
   }
   async revoke(peerAgentId) {
     await this.setRelationship(peerAgentId, "revoked", "Revoke", "revoked");
@@ -1307,6 +1521,12 @@ var EdgeBookStore = class {
       await this.receivePostPublish(envelope);
       return;
     }
+    if (envelope.type === "profile_share") {
+      await this.receiveProfileShare(envelope);
+      return;
+    }
+    if (envelope.type === "escalation") return this.receiveEscalation(envelope);
+    if (envelope.type === "escalation_response") return this.applyEscalationResponse(envelope);
     throw new EdgeBookError("unsupported_envelope", `Unsupported envelope type: ${envelope.type}`);
   }
   async audit(action, peerAgentId, details) {
@@ -1430,6 +1650,187 @@ var EdgeBookStore = class {
     await this.saveApprovals(approvals);
     return approval;
   }
+  // ──────────────────────────────────────────────────────────────────────
+  // Agent → human escalation (ea-claude-094). Raise → surface → answer →
+  // route-back, mirroring the friend-request loop. Remote raises are gated on
+  // friend-state + an `escalation.raise` grant (fail closed), exactly like
+  // sendPrivilegedMessage. Local raises (asking your own human) need no grant.
+  // ──────────────────────────────────────────────────────────────────────
+  async escalations() {
+    return readJson(this.file(ESCALATIONS_FILE), {});
+  }
+  async saveEscalations(escalations) {
+    await writeJson(this.file(ESCALATIONS_FILE), escalations);
+  }
+  async putEscalation(escalation) {
+    const all = await this.escalations();
+    all[escalation.escalation_id] = escalation;
+    await this.saveEscalations(all);
+  }
+  // Raise an escalation. Omit `to` to ask your own human (local — no envelope).
+  // Pass `to` (a friend's agent_id) to ask their human — returns a signed
+  // `escalation` envelope the caller delivers over the mailbox.
+  async raiseEscalation(input) {
+    const identity = await this.identity();
+    const ttlMs = input.ttlMs ?? 7 * 24 * 60 * 60 * 1e3;
+    const escalation = {
+      escalation_id: randomId("esc"),
+      raised_by_agent_id: identity.agent_id,
+      collaborators: input.collaborators ?? [],
+      to_human_owner_id: "",
+      kind: input.kind,
+      subject: input.subject,
+      body: input.body,
+      options: input.options ?? [],
+      context_refs: input.contextRefs ?? [],
+      status: "pending",
+      risk_level: input.riskLevel ?? "medium",
+      created_at: now(),
+      expires_at: new Date(Date.now() + ttlMs).toISOString(),
+      answer_text: "",
+      answer_choice: "",
+      answered_at: "",
+      answered_by: "",
+      audit_refs: []
+    };
+    if (!input.to) {
+      escalation.to_human_owner_id = identity.owner_label || identity.agent_id;
+      escalation.audit_refs.push(await this.audit("escalation.raise", identity.agent_id, { escalation_id: escalation.escalation_id, kind: escalation.kind, local: true }));
+      await this.putEscalation(escalation);
+      return { escalation };
+    }
+    const contacts = await this.contacts();
+    const contact = contacts[input.to];
+    if (!contact) throw new EdgeBookError("unknown_contact", `Unknown contact: ${input.to}`);
+    if (contact.relationship_state === "blocked") throw new EdgeBookError("blocked", `Peer ${input.to} is blocked`);
+    if (contact.relationship_state !== "friend") {
+      throw new EdgeBookError("not_friend", `Cannot escalate to relationship_state=${contact.relationship_state}`);
+    }
+    const grant = await this.findUsableGrant(input.to, "escalation.raise");
+    if (!grant) throw new EdgeBookError("missing_grant", `No active escalation.raise grant for ${input.to}`);
+    await this.assertGrantSignature(grant);
+    const envelope = await this.signEnvelope({
+      type: "escalation",
+      to_agent_id: input.to,
+      relationship_id: relationshipId(identity.agent_id, input.to),
+      capability_id: grant.grant_id,
+      ref: escalation.escalation_id,
+      transport: "local",
+      // Clone into the signed body — the local copy below mutates audit_refs,
+      // which must not retroactively alter the signed payload.
+      body: { escalation: structuredClone(escalation) }
+    });
+    escalation.audit_refs.push(await this.audit("escalation.raise", input.to, { escalation_id: escalation.escalation_id, kind: escalation.kind, message_id: envelope.message_id }));
+    await this.putEscalation(escalation);
+    return { escalation, envelope };
+  }
+  // Receive a remote escalation, materialise it for this agent's human.
+  async receiveEscalation(envelope) {
+    await this.verifyEnvelope(envelope);
+    if (envelope.type !== "escalation") throw new EdgeBookError("wrong_message_type", "Expected escalation envelope");
+    const contacts = await this.contacts();
+    const contact = contacts[envelope.from_agent_id];
+    if (!contact) throw new EdgeBookError("unknown_contact", `Unknown contact: ${envelope.from_agent_id}`);
+    if (contact.relationship_state !== "friend") {
+      throw new EdgeBookError("not_friend", `Cannot receive escalation from relationship_state=${contact.relationship_state}`);
+    }
+    const grants = await this.grants();
+    const grant = grants[envelope.capability_id];
+    if (!grant || grant.status !== "active" || grant.subject_agent_id !== envelope.from_agent_id || !grant.scopes.includes("escalation.raise")) {
+      throw new EdgeBookError("missing_grant", "Escalation does not carry an active escalation.raise grant issued to sender");
+    }
+    await this.assertGrantSignature(grant);
+    const identity = await this.identity();
+    const body = envelope.body;
+    const incoming = body.escalation;
+    if (incoming.raised_by_agent_id !== envelope.from_agent_id) {
+      throw new EdgeBookError("agent_id_mismatch", "Escalation raised_by does not match sender");
+    }
+    const escalation = {
+      ...incoming,
+      to_human_owner_id: identity.owner_label || identity.agent_id,
+      status: "pending",
+      answer_text: "",
+      answer_choice: "",
+      answered_at: "",
+      answered_by: "",
+      audit_refs: []
+    };
+    escalation.audit_refs.push(await this.audit("escalation.receive", envelope.from_agent_id, { escalation_id: escalation.escalation_id, kind: escalation.kind }));
+    await this.putEscalation(escalation);
+    return escalation;
+  }
+  // The human answers. For a remote-origin escalation, returns an
+  // `escalation_response` envelope to route back to the requesting agent.
+  async answerEscalation(escalationId, input) {
+    const identity = await this.identity();
+    const all = await this.escalations();
+    const escalation = all[escalationId];
+    if (!escalation) throw new EdgeBookError("unknown_escalation", `Unknown escalation: ${escalationId}`);
+    if (escalation.status !== "pending") throw new EdgeBookError("escalation_resolved", `Escalation already ${escalation.status}`);
+    if ((escalation.kind === "decision" || escalation.kind === "approval") && escalation.options.length > 0) {
+      if (!input.choice || !escalation.options.includes(input.choice)) {
+        throw new EdgeBookError("invalid_option", `Answer must be one of the offered options: ${escalation.options.join(", ")}`);
+      }
+    }
+    escalation.status = "answered";
+    escalation.answer_text = input.text ?? "";
+    escalation.answer_choice = input.choice ?? "";
+    escalation.answered_at = now();
+    escalation.answered_by = "local-owner";
+    escalation.audit_refs.push(await this.audit("escalation.answer", escalation.raised_by_agent_id, { escalation_id: escalationId }));
+    all[escalationId] = escalation;
+    await this.saveEscalations(all);
+    let envelope;
+    if (escalation.raised_by_agent_id !== identity.agent_id) {
+      envelope = await this.signEnvelope({
+        type: "escalation_response",
+        to_agent_id: escalation.raised_by_agent_id,
+        relationship_id: relationshipId(identity.agent_id, escalation.raised_by_agent_id),
+        capability_id: "",
+        ref: escalationId,
+        transport: "local",
+        body: {
+          escalation_id: escalationId,
+          status: escalation.status,
+          answer_text: escalation.answer_text,
+          answer_choice: escalation.answer_choice,
+          answered_at: escalation.answered_at
+        }
+      });
+    }
+    return { ...escalation, envelope };
+  }
+  // The requesting agent applies a routed-back answer to its own copy.
+  async applyEscalationResponse(envelope) {
+    await this.verifyEnvelope(envelope);
+    if (envelope.type !== "escalation_response") throw new EdgeBookError("wrong_message_type", "Expected escalation_response envelope");
+    const body = envelope.body;
+    const all = await this.escalations();
+    const escalation = all[body.escalation_id];
+    if (!escalation) throw new EdgeBookError("unknown_escalation", `Unknown escalation: ${body.escalation_id}`);
+    escalation.status = body.status;
+    escalation.answer_text = body.answer_text;
+    escalation.answer_choice = body.answer_choice;
+    escalation.answered_at = body.answered_at;
+    escalation.answered_by = "local-owner";
+    escalation.audit_refs.push(await this.audit("escalation.response", envelope.from_agent_id, { escalation_id: body.escalation_id, status: body.status }));
+    all[body.escalation_id] = escalation;
+    await this.saveEscalations(all);
+    return escalation;
+  }
+  // Sweep: pending escalations past their expiry become `expired`.
+  async expireEscalations() {
+    const all = await this.escalations();
+    let changed = false;
+    for (const escalation of Object.values(all)) {
+      if (escalation.status === "pending" && Date.parse(escalation.expires_at) <= Date.now()) {
+        escalation.status = "expired";
+        changed = true;
+      }
+    }
+    if (changed) await this.saveEscalations(all);
+  }
   async createPost(input) {
     const identity = await this.identity();
     const stamp = now();
@@ -1696,6 +2097,18 @@ function validateCard(card) {
     throw new EdgeBookError("invalid_card", "Agent Card signature is invalid");
   }
 }
+function validateFriendProfile(profile, publicKeyPem) {
+  if (profile.schema !== "openclaw-friend-profile/0.1") {
+    throw new EdgeBookError("invalid_friend_profile", "Unsupported FriendProfile schema");
+  }
+  if (!profile.agent_id) throw new EdgeBookError("invalid_friend_profile", "FriendProfile missing agent_id");
+  if (typeof profile.profile_version !== "number") {
+    throw new EdgeBookError("invalid_friend_profile", "FriendProfile missing profile_version");
+  }
+  if (!verifyPayload(withoutSignature(profile), profile.signature, publicKeyPem)) {
+    throw new EdgeBookError("invalid_friend_profile", "FriendProfile signature is invalid");
+  }
+}
 async function loadCard(cardPathOrUrl) {
   if (cardPathOrUrl.startsWith("edgebook:invite:")) {
     const encoded = cardPathOrUrl.slice("edgebook:invite:".length);
@@ -1721,6 +2134,8 @@ async function runTwoAgentHarness(baseDir) {
   const bob = new EdgeBookStore({ home: path.join(root, "bob") });
   await alice.init({ handle: "alice.openclaw.local", displayName: "Alice Agent", ownerLabel: "Alice" });
   await bob.init({ handle: "bob.openclaw.local", displayName: "Bob Agent", ownerLabel: "Bob" });
+  await alice.setProfile({ name: "Alice", bio: "Alice bio", socials: [{ label: "telegram", value: "@alice" }] });
+  await bob.setProfile({ name: "Bob", bio: "Bob bio" });
   const aliceCard = await alice.writeCard();
   const bobCard = await bob.writeCard();
   const request = await alice.createFriendRequest(bobCard, "test harness request");
@@ -1732,7 +2147,8 @@ async function runTwoAgentHarness(baseDir) {
   }
   await bob.receiveFriendRequest(request);
   const accept = await bob.acceptFriend(aliceCard.agent_id);
-  await alice.applyFriendResponse(accept);
+  const aliceFollowUp = await alice.applyFriendResponse(accept);
+  if (aliceFollowUp) await bob.receiveProfileShare(aliceFollowUp);
   const message = await alice.sendPrivilegedMessage(bobCard.agent_id, { text: "hello Bob" });
   await bob.receivePrivilegedMessage(message);
   let replayDenied = false;
@@ -1760,13 +2176,16 @@ async function runTwoAgentHarness(baseDir) {
   await alice.upsertContactFromCard(rotatedBobCard);
   const aliceContacts = await alice.contacts();
   const bobAudit = await bob.auditEvents();
+  const aliceSeesBob = (await alice.contacts())[bobCard.agent_id].friend_profile?.name === "Bob";
+  const bobSeesAlice = (await bob.contacts())[aliceCard.agent_id].friend_profile?.name === "Alice";
   const assertions = {
     deniedBeforeAccept,
     replayDenied,
     revokedDenied,
     blockedDenied,
     aliceHasBobContact: Boolean(aliceContacts[bobCard.agent_id]),
-    bobAuditWritten: bobAudit.length > 0
+    bobAuditWritten: bobAudit.length > 0,
+    profileExchange: aliceSeesBob && bobSeesAlice
   };
   const passed = Object.values(assertions).every(Boolean);
   if (!passed) throw new EdgeBookError("harness_failed", `Harness failed: ${JSON.stringify(assertions)}`);
@@ -2021,7 +2440,40 @@ async function handleOwnerApi(req, res, url, adapters) {
   const approvalResolveMatch = /^\/api\/approvals\/([^/]+)\/resolve$/.exec(url.pathname);
   if (req.method === "POST" && approvalResolveMatch) {
     const body = await readJsonBody(req);
-    sendJson(res, 200, { approval: await store.resolveApproval(decodeURIComponent(approvalResolveMatch[1]), Boolean(body.approved)) });
+    const approved = Boolean(body.approved);
+    const approvalId = decodeURIComponent(approvalResolveMatch[1]);
+    const allApprovals = await store.approvals();
+    const pendingApproval = allApprovals[approvalId];
+    if (pendingApproval?.type === "friend_accept" && pendingApproval.status === "pending") {
+      const contacts = await store.contacts();
+      const targetContact = contacts[pendingApproval.object_id];
+      if (!targetContact) {
+        throw new EdgeBookError("unknown_contact", `Contact not found for approval: ${pendingApproval.object_id}`);
+      }
+      if (approved && targetContact.relationship_state !== "request_received") {
+        throw new EdgeBookError(
+          "invalid_relationship_state",
+          `Cannot approve friend_accept: contact is in state '${targetContact.relationship_state}', expected 'request_received'`
+        );
+      }
+    }
+    const approval = await store.resolveApproval(approvalId, approved);
+    let response_envelope;
+    if (approval.type === "friend_accept") {
+      response_envelope = approved ? await store.acceptFriend(approval.object_id) : await store.rejectFriend(approval.object_id);
+    }
+    sendJson(res, 200, response_envelope ? { approval, response_envelope } : { approval });
+    return true;
+  }
+  if (req.method === "GET" && url.pathname === "/api/escalations") {
+    sendJson(res, 200, { escalations: await store.escalations() });
+    return true;
+  }
+  const escalationAnswerMatch = /^\/api\/escalations\/([^/]+)\/answer$/.exec(url.pathname);
+  if (req.method === "POST" && escalationAnswerMatch) {
+    const body = await readJsonBody(req);
+    const { envelope, ...escalation } = await store.answerEscalation(decodeURIComponent(escalationAnswerMatch[1]), { text: body.text, choice: body.choice });
+    sendJson(res, 200, { escalation, response_envelope: envelope ?? null });
     return true;
   }
   const auditMatch = /^\/api\/audit\/([^/]+)\/([^/]+)$/.exec(url.pathname);
@@ -2681,6 +3133,7 @@ function dashboardHtml() {
       <button data-view="messages">Messages <span id="messageCount">Total 0</span></button>
       <button data-view="posts">Post history <span id="postCount">Drafts 0</span></button>
       <button data-view="approvals">Approvals <span id="approvalCount">Pending 0</span></button>
+      <button data-view="escalations">Escalations <span id="escalationCount">Pending 0</span></button>
       <button data-view="activity">Activity Log <span id="activityCount">Events 0</span></button>
       <button data-view="inspector">Inspector <span>Details</span></button>
     </nav>
@@ -2743,6 +3196,7 @@ function dashboardHtml() {
       posts: {},
       feedItems: {},
       approvals: {},
+      escalations: {},
       messages: [],
       audit: []
     };
@@ -2753,6 +3207,7 @@ function dashboardHtml() {
       messages: "Messages",
       posts: "Post history",
       approvals: "Approvals",
+      escalations: "Escalations",
       activity: "Activity Log",
       inspector: "Inspector"
     };
@@ -2763,6 +3218,7 @@ function dashboardHtml() {
       messages: "Friend-gated envelopes grouped by peer context.",
       posts: "Drafts, approvals, visibility, source basis, and removal state.",
       approvals: "Human gates for agent-authored changes and risk-bearing actions.",
+      escalations: "Questions your agent \u2014 or a collaborating agent \u2014 raised for you to answer.",
       activity: "Owner-only audit trail for local decisions, relationship changes, posts, and messages.",
       inspector: "Readable decision summary plus detailed local evidence."
     };
@@ -2847,6 +3303,7 @@ function dashboardHtml() {
       return date.toLocaleString([], { month: "short", day: "numeric", hour: "numeric", minute: "2-digit" });
     }
     function pendingApprovals() { return values(state.approvals).filter((approval) => approval.status === "pending"); }
+    function pendingEscalations() { return values(state.escalations).filter((escalation) => escalation.status === "pending"); }
     function visibleFeedItems() { return values(state.feedItems).filter((feed) => !feed.hidden); }
     function friendContacts() { return values(state.contacts).filter((contact) => contact.relationship_state === "friend"); }
     function blockedContacts() { return values(state.contacts).filter((contact) => contact.relationship_state === "blocked"); }
@@ -2854,6 +3311,7 @@ function dashboardHtml() {
     function renderAttentionQueue() {
       const rows = [
         ["Approvals", pendingApprovals().length, pendingApprovals().length ? "attention" : "owned"],
+        ["Escalations", pendingEscalations().length, pendingEscalations().length ? "attention" : "owned"],
         ["Unread feed", values(state.feedItems).filter((feed) => feed.read_state !== "read" && !feed.hidden).length, "neutral"],
         ["Blocked peers", blockedContacts().length, blockedContacts().length ? "risk" : "owned"],
         ["Draft/pending posts", draftPosts().length, draftPosts().length ? "attention" : "neutral"]
@@ -2891,6 +3349,7 @@ function dashboardHtml() {
       setText("contactCount", "Friends " + friendContacts().length);
       setText("postCount", "Drafts " + draftPosts().length);
       setText("approvalCount", "Pending " + pendingApprovals().length);
+      setText("escalationCount", "Pending " + pendingEscalations().length);
       setText("activityCount", "Events " + state.audit.length);
       setText("messageCount", "Total " + state.messages.length);
       setText("summaryFeed", visibleFeedItems().length);
@@ -2992,6 +3451,26 @@ function dashboardHtml() {
         ], "Requested " + timeLabel(approval.created_at));
         }).join("") || renderEmpty("No approval requests.");
       }
+      if (state.view === "escalations") {
+        html = values(state.escalations).map((escalation) => {
+          const isOption = (escalation.kind === "decision" || escalation.kind === "approval") && (escalation.options || []).length;
+          const actions = escalation.status === "pending"
+            ? (isOption
+                ? (escalation.options || []).map((option) => action(option, "escalation-choose", escalation.escalation_id + "::" + option)).join("")
+                : action("Answer", "escalation-answer", escalation.escalation_id))
+            : "";
+          const answer = escalation.status === "answered" ? (escalation.answer_choice || escalation.answer_text || "answered") : "";
+          return item(escalation.subject, escalation.body, [
+            "from: " + agentLabel(escalation.raised_by_agent_id),
+            answer ? "answer: " + answer : ""
+          ], escalation, escalation.risk_level === "high" ? "risk" : escalation.risk_level === "medium" ? "warn" : "", actions, [
+          ["kind", labelize(escalation.kind)],
+          ["status", labelize(escalation.status)],
+          ["from", agentLabel(escalation.raised_by_agent_id)],
+          ["options", (escalation.options || []).join(", ") || "free text"]
+        ], "Raised " + timeLabel(escalation.created_at));
+        }).join("") || renderEmpty("No escalations waiting.");
+      }
       if (state.view === "activity") {
         html = [...state.audit].reverse().map((event) => item(labelize(event.type || "audit event"), event.peer_agent_id ? agentLabel(event.peer_agent_id) : "Local owner action", [
           "when: " + timeLabel(event.created_at),
@@ -3059,6 +3538,17 @@ function dashboardHtml() {
         if (name === "post-remove") await postJson("/api/posts/" + encodeURIComponent(id) + "/remove", { reason: prompt("Reason", "removed by owner") || "" });
         if (name === "approval-approve") await postJson("/api/approvals/" + encodeURIComponent(id) + "/resolve", { approved: true });
         if (name === "approval-reject") await postJson("/api/approvals/" + encodeURIComponent(id) + "/resolve", { approved: false });
+        if (name === "escalation-answer") {
+          const text = prompt("Your answer", "");
+          if (text === null) return;
+          await postJson("/api/escalations/" + encodeURIComponent(id) + "/answer", { text });
+        }
+        if (name === "escalation-choose") {
+          const sep = id.lastIndexOf("::");
+          const escalationId = id.slice(0, sep);
+          const choice = id.slice(sep + 2);
+          await postJson("/api/escalations/" + encodeURIComponent(escalationId) + "/answer", { choice });
+        }
         await refresh();
       } catch (error) {
         setInspector({ action: name, id, failure_reason: error.message || String(error) });
@@ -3087,11 +3577,12 @@ function dashboardHtml() {
       setText("owner", publicOwnerLabel() + " | Local session active");
       setText("ownerName", publicOwnerLabel());
       setText("ownerShort", "local owner session");
-      const [contacts, posts, feed, approvals, audit] = await Promise.all([
+      const [contacts, posts, feed, approvals, escalations, audit] = await Promise.all([
         api("/api/contacts"),
         api("/api/posts"),
         api("/api/feed"),
         api("/api/approvals"),
+        api("/api/escalations"),
         api("/api/audit")
       ]);
       state.contacts = contacts.contacts;
@@ -3099,6 +3590,7 @@ function dashboardHtml() {
       state.posts = posts.posts;
       state.feedItems = feed.feed_items;
       state.approvals = approvals.approvals;
+      state.escalations = escalations.escalations || {};
       state.audit = audit.audit || [];
       const messageSets = await Promise.all(values(state.contacts).map((contact) => api("/api/messages/" + encodeURIComponent(contact.peer_agent_id)).catch(() => ({ messages: [] }))));
       state.messages = messageSets.flatMap((set) => set.messages || []);
@@ -3488,8 +3980,11 @@ var EdgeBookDialoutClient = class {
       if (this.mailboxQueue) {
         this.pushMailbox({ id: frame.id, to: envelope.to_agent_id, from: frame.from, blob: frame.blob_b64, ts: frame.ts });
       } else if (this.options.autoApplyEnvelopes) {
-        await this.store.receiveEnvelope(envelope);
+        const followUp = await this.store.receiveEnvelope(envelope);
         applied = true;
+        if (followUp && typeof followUp === "object" && "type" in followUp && followUp.type === "profile_share") {
+          await this.sendEnvelope(followUp).catch(() => void 0);
+        }
       }
     } catch (e) {
       error = e instanceof Error ? e.message : String(e);
@@ -3651,6 +4146,30 @@ var EdgeBookDialoutClient = class {
     this.localApi = void 0;
     await this.options.onStandDown?.(frame);
   }
+  // If an API response carries a routed-back `response_envelope` (e.g. the escalation
+  // answer endpoint for remote escalations, or the approval resolve endpoint for
+  // friend_accept approvals), deliver it over the mailbox. Best-effort: swallow +
+  // audit relay errors so the human's action, which is already persisted, still
+  // returns 200. Audit event names are keyed on the envelope type for honest trails
+  // (e.g. "escalation_response.relay", "friend_response.relay").
+  async maybeRelayResponseEnvelope(status, bodyBuffer) {
+    if (status < 200 || status >= 300) return;
+    let envelope;
+    try {
+      const body = JSON.parse(bodyBuffer.toString("utf8"));
+      if (body && body.response_envelope) envelope = body.response_envelope;
+    } catch {
+      return;
+    }
+    if (!envelope) return;
+    const envType = envelope.type || "unknown";
+    try {
+      await this.sendEnvelope(envelope);
+      await this.store.audit(`${envType}.relay`, envelope.to_agent_id, { message_id: envelope.message_id, ref: envelope.ref });
+    } catch (error) {
+      await this.store.audit(`${envType}.relay_failed`, envelope.to_agent_id, { ref: envelope.ref, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
   async handleApiRequest(frame) {
     try {
       if (!this.localApi) {
@@ -3668,6 +4187,7 @@ var EdgeBookDialoutClient = class {
         body: requestBody(frame, method)
       });
       const bodyBuffer = Buffer.from(await response.arrayBuffer());
+      await this.maybeRelayResponseEnvelope(response.status, bodyBuffer);
       return {
         type: "api_response",
         id: frame.id || frame.request_id || "",
@@ -3880,8 +4400,8 @@ function usage() {
 Usage:
   edge-book init [--home <dir>] [--handle <handle>] [--name <agent name>] [--owner <human owner>]
   edge-book profile show [--home <dir>]
-  edge-book profile set [--name <agent name>] [--owner <human owner>] [--share-owner | --no-share-owner] [--home <dir>]
-                                                            # owner name is private by default; --share-owner exposes it on your card
+  edge-book profile set [--name <you>] [--bio <text>] [--location <text>] [--social label=value ...] [--agent-name <display>] [--home <dir>]
+  edge-book profile visibility <field>=friends|public|off ... [--home <dir>]
 
 Hosted reader:
   edge-book dialout [--host <ws-url>] [--home <dir>]
@@ -3900,6 +4420,9 @@ Local agent:
   edge-book friend apply-response <envelope-json-path> [--home <dir>]
   edge-book friend revoke <peer-agent-id> [--home <dir>]
   edge-book friend block <peer-agent-id> [--home <dir>]
+  edge-book friend pending [--json] [--home <dir>]
+  edge-book friend mark-notified <peer-agent-id> [--home <dir>]
+  edge-book friend notify-config --on|--off [--home <dir>]
   edge-book contacts list [--home <dir>]
   edge-book contacts refresh <card-path-or-url> [--home <dir>]
   edge-book message send <peer-agent-id> --body <text> [--deliver] [--home <dir>]
@@ -3909,6 +4432,11 @@ Local agent:
   edge-book object revoke <peer-agent-id> <object-id> [--deliver] [--host <ws-url>] [--home <dir>]
   edge-book object list [--home <dir>]
   edge-book object read <object-id> [--home <dir>]
+  edge-book escalation raise --kind <question|decision|approval|input> --subject <s> --body <b> [--to <peer-agent-id>] [--option <o>]... [--deliver] [--home <dir>]
+  edge-book escalation list [--home <dir>]
+  edge-book escalation receive <envelope-json-path> [--home <dir>]
+  edge-book escalation answer <escalation-id> [--text <t>] [--choice <o>] [--deliver] [--home <dir>]
+  edge-book escalation respond <envelope-json-path> [--home <dir>]
   edge-book inbox list [--home <dir>]
   edge-book inbox pull --relay <url> [--home <dir>]
   edge-book serve --host <host> --port <port> [--home <dir>]
@@ -3954,6 +4482,27 @@ function takeBoolFlag(args, name) {
   args.splice(idx, 1);
   return true;
 }
+function takeRepeatedKV(args, flag) {
+  const out = [];
+  let idx;
+  while ((idx = args.indexOf(flag)) !== -1) {
+    const raw = args[idx + 1] ?? "";
+    args.splice(idx, 2);
+    const eq = raw.indexOf("=");
+    if (eq === -1) throw new EdgeBookError("bad_social", `--social expects label=value, got "${raw}"`);
+    out.push({ label: raw.slice(0, eq), value: raw.slice(eq + 1) });
+  }
+  return out;
+}
+function takeRepeated(args, flag) {
+  const out = [];
+  let idx;
+  while ((idx = args.indexOf(flag)) !== -1) {
+    out.push(args[idx + 1] ?? "");
+    args.splice(idx, 2);
+  }
+  return out;
+}
 async function readEnvelope(filePath) {
   return JSON.parse(await fs4.readFile(path4.resolve(filePath), "utf8"));
 }
@@ -4001,39 +4550,107 @@ async function handleCli(inputArgs, ctx = {}) {
     const handle = takeFlag(args, "--handle");
     const displayName = takeFlag(args, "--name");
     const ownerLabel = takeFlag(args, "--owner");
+    const shareOwner = takeBoolFlag(args, "--share-owner");
     const directUrl = takeFlag(args, "--direct-url");
     const relayUrl = takeFlag(args, "--relay-url");
-    const identity = await store.init({ handle, displayName, ownerLabel, directUrl, relayUrl });
-    return { text: `Initialized ${identity.agent_id} at ${store.home}`, json: identity };
+    const identity = await store.init({ handle, displayName, ownerLabel, shareOwnerLabel: shareOwner, directUrl, relayUrl });
+    const note = `Initialized ${identity.agent_id} at ${store.home}
+
+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`;
+    return { text: note, json: identity };
   }
   if (command === "profile") {
     const action = args.shift() || "show";
     if (action === "show") {
       const id = await store.identity();
-      const shared = id.share_owner_label ? "shared with contacts" : "private (default)";
+      const p = defaultProfile(id);
       return {
         text: `display_name: ${id.display_name}
-owner_label: ${id.owner_label || "(unset)"}
-share_owner_label: ${id.share_owner_label ? "true" : "false"} (${shared})`,
-        json: { agent_id: id.agent_id, display_name: id.display_name, owner_label: id.owner_label, share_owner_label: Boolean(id.share_owner_label) }
+name: ${p.name || "(unset)"}
+bio: ${p.bio || "(unset)"}
+location: ${p.location || "(unset)"}
+socials: ${(p.socials ?? []).map((s) => `${s.label}=${s.value}`).join(", ") || "(none)"}
+visibility: ${JSON.stringify(p.visibility ?? {})}`,
+        json: { agent_id: id.agent_id, display_name: id.display_name, name: p.name, bio: p.bio, location: p.location, socials: p.socials ?? [], visibility: p.visibility ?? {} }
       };
     }
     if (action === "set") {
-      const displayName = takeFlag(args, "--name");
+      const displayName = takeFlag(args, "--agent-name");
+      const name = takeFlag(args, "--name");
+      const bio = takeFlag(args, "--bio");
+      const location = takeFlag(args, "--location");
+      const socialsKV = takeRepeatedKV(args, "--social");
       const ownerLabel = takeFlag(args, "--owner");
       const shareOwner = takeBoolFlag(args, "--share-owner");
       const noShareOwner = takeBoolFlag(args, "--no-share-owner");
       const shareOwnerLabel = shareOwner ? true : noShareOwner ? false : void 0;
-      if (displayName === void 0 && ownerLabel === void 0 && shareOwnerLabel === void 0) {
-        throw new EdgeBookError("missing_arg", "profile set needs --name (agent name), --owner (human owner), and/or --share-owner|--no-share-owner");
+      if (displayName === void 0 && name === void 0 && bio === void 0 && location === void 0 && socialsKV.length === 0 && ownerLabel === void 0 && shareOwnerLabel === void 0) {
+        throw new EdgeBookError(
+          "missing_arg",
+          "profile set needs at least one of --name/--agent-name/--bio/--location/--social/--owner/--share-owner"
+        );
       }
-      const id = await store.setProfile({ displayName, ownerLabel, shareOwnerLabel });
-      return {
-        text: `Updated profile: display_name=${id.display_name} owner_label=${id.owner_label || "(unset)"} share_owner_label=${id.share_owner_label ? "true" : "false"}`,
-        json: { agent_id: id.agent_id, display_name: id.display_name, owner_label: id.owner_label, share_owner_label: Boolean(id.share_owner_label) }
-      };
+      const id = await store.setProfile({
+        displayName,
+        name,
+        bio,
+        location,
+        socials: socialsKV.length ? socialsKV : void 0,
+        ownerLabel,
+        shareOwnerLabel
+      });
+      const p = defaultProfile(id);
+      return { text: `Updated profile (v${p.profile_version}): name=${p.name || "(unset)"}`, json: { agent_id: id.agent_id, name: p.name, profile_version: p.profile_version } };
+    }
+    if (action === "visibility") {
+      const pairs = args.splice(0).map((tok) => {
+        const eq = tok.indexOf("=");
+        if (eq === -1) throw new EdgeBookError("bad_visibility", `expected field=friends|public|off, got "${tok}"`);
+        const field = tok.slice(0, eq);
+        const vis = tok.slice(eq + 1);
+        if (!["friends", "public", "off"].includes(vis)) throw new EdgeBookError("bad_visibility", `bad visibility "${vis}" for ${field}`);
+        return [field, vis];
+      });
+      if (!pairs.length) throw new EdgeBookError("missing_arg", "profile visibility needs at least one field=friends|public|off");
+      const KNOWN_FIELDS = /* @__PURE__ */ new Set(["name", "bio", "location", "*"]);
+      const currentId = await store.identity();
+      const currentProfile = defaultProfile(currentId);
+      const socialLabels = new Set((currentProfile.socials ?? []).map((s) => s.label));
+      for (const [field] of pairs) {
+        if (!KNOWN_FIELDS.has(field) && !socialLabels.has(field)) {
+          const known = [...KNOWN_FIELDS, ...socialLabels].join(", ");
+          throw new EdgeBookError(
+            "unknown_visibility_field",
+            `Unknown profile field/social '${field}'; known: name, bio, location, *, plus your social labels${socialLabels.size ? ` (${[...socialLabels].join(", ")})` : ""}`
+          );
+        }
+      }
+      const id = await store.setProfile({ visibility: Object.fromEntries(pairs) });
+      const p = defaultProfile(id);
+      return { text: `Updated visibility: ${JSON.stringify(p.visibility ?? {})}`, json: { visibility: p.visibility ?? {} } };
     }
-    throw new EdgeBookError("unknown_action", `Unknown profile action: ${action} (use "show" or "set")`);
+    if (action === "broadcast") {
+      const deliver = takeBoolFlag(args, "--deliver");
+      const envelopes = await store.broadcastProfileEnvelopes();
+      if (deliver) {
+        const hostUrl = parseHost(args, ctx);
+        for (const envelope of envelopes) {
+          try {
+            await deliverToPeer(store, envelope, envelope.to_agent_id);
+          } catch (error) {
+            if (!(error instanceof EdgeBookError) || error.code !== "no_route") throw error;
+            await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
+          }
+        }
+        return { text: `Broadcast profile to ${envelopes.length} friend(s)`, json: { count: envelopes.length } };
+      }
+      return { text: `Built ${envelopes.length} profile_share envelope(s)`, json: { envelopes } };
+    }
+    throw new EdgeBookError("unknown_action", `Unknown profile action: ${action} (use "show", "set", "visibility", or "broadcast")`);
   }
   if (command === "doctor") {
     const result = await store.doctor();
@@ -4122,9 +4739,21 @@ next: ${result.next_action}`, json: result };
       return { text: JSON.stringify(envelope, null, 2), json: envelope };
     }
     if (action === "apply-response") {
+      const deliver = takeBoolFlag(args, "--deliver");
       const source = requireArg(args.shift(), "envelope-json-path");
-      await store.applyFriendResponse(await readEnvelope(source));
-      return { text: `Applied friend response from ${path4.resolve(source)}` };
+      const followUp = await store.applyFriendResponse(await readEnvelope(source));
+      if (!followUp) return { text: `Applied friend response from ${path4.resolve(source)}` };
+      if (deliver) {
+        try {
+          return { text: await deliverToPeer(store, followUp, followUp.to_agent_id), json: followUp };
+        } catch (error) {
+          if (!(error instanceof EdgeBookError) || error.code !== "no_route") throw error;
+          const hostUrl = parseHost(args, ctx);
+          const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope: followUp });
+          return { text: `Applied response; delivered profile_share to ${followUp.to_agent_id} over the mailbox (host id ${ack.id})`, json: followUp };
+        }
+      }
+      return { text: `Applied friend response; deliver this profile_share to ${followUp.to_agent_id}`, json: followUp };
     }
     if (action === "revoke") {
       const peer = requireArg(args.shift(), "peer-agent-id");
@@ -4136,6 +4765,31 @@ next: ${result.next_action}`, json: result };
       await store.block(peer);
       return { text: `Blocked ${peer}` };
     }
+    if (action === "pending") {
+      const pending = await store.pendingFriendRequests();
+      const json = pending.map((c) => ({
+        agent_id: c.peer_agent_id,
+        display_name: c.display_name,
+        note: "",
+        // note isn't persisted on the contact; read from inbox if needed
+        contact_created_at: c.created_at
+      }));
+      const text = json.length ? json.map((p) => `${p.agent_id}  ${p.display_name}`).join("\n") : "No pending friend requests.";
+      return { text, json };
+    }
+    if (action === "mark-notified") {
+      const peer = requireArg(args.shift(), "peer-agent-id");
+      await store.markFriendRequestNotified(peer);
+      return { text: `Marked ${peer} notified` };
+    }
+    if (action === "notify-config") {
+      const on = takeBoolFlag(args, "--on");
+      const off = takeBoolFlag(args, "--off");
+      if (on && off) throw new EdgeBookError("bad_flags", "notify-config takes either --on or --off, not both");
+      if (!on && !off) throw new EdgeBookError("missing_arg", "notify-config needs --on or --off");
+      const cfg = await store.updateConfig({ notify_on_friend_request: on ? true : false });
+      return { text: `notify_on_friend_request = ${cfg.notify_on_friend_request}`, json: cfg };
+    }
   }
   if (command === "object") {
     const action = args.shift();
@@ -4220,6 +4874,59 @@ next: ${result.next_action}`, json: result };
       return { text: `Received privileged message from ${path4.resolve(source)}` };
     }
   }
+  if (command === "escalation") {
+    const action = args.shift();
+    if (action === "raise") {
+      const deliver = takeBoolFlag(args, "--deliver");
+      const hostUrl = parseHost(args, ctx);
+      const kind = requireArg(takeFlag(args, "--kind"), "--kind");
+      const subject = requireArg(takeFlag(args, "--subject"), "--subject");
+      const body = requireArg(takeFlag(args, "--body"), "--body");
+      const to = takeFlag(args, "--to");
+      const options = takeRepeated(args, "--option");
+      const collaborators = takeRepeated(args, "--collaborator");
+      const contextRefs = takeRepeated(args, "--context-ref");
+      const riskLevel = takeFlag(args, "--risk");
+      const { escalation, envelope } = await store.raiseEscalation({ kind, subject, body, to, options, collaborators, contextRefs, riskLevel });
+      if (envelope) {
+        if (deliver) {
+          const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
+          return { text: `Raised escalation ${escalation.escalation_id}; delivered to ${to} over the mailbox (host id ${ack.id})`, json: envelope };
+        }
+        return { text: `Raised escalation ${escalation.escalation_id} for ${to}; deliver this envelope (or pass --deliver)`, json: envelope };
+      }
+      return { text: `Raised escalation ${escalation.escalation_id} (local)`, json: escalation };
+    }
+    if (action === "list") {
+      const escalations = await store.escalations();
+      return { text: JSON.stringify(Object.values(escalations), null, 2), json: Object.values(escalations) };
+    }
+    if (action === "receive") {
+      const source = requireArg(args.shift(), "envelope-json-path");
+      const escalation = await store.receiveEscalation(await readEnvelope(source));
+      return { text: `Received escalation ${escalation.escalation_id} from ${escalation.raised_by_agent_id}`, json: escalation };
+    }
+    if (action === "answer") {
+      const deliver = takeBoolFlag(args, "--deliver");
+      const hostUrl = parseHost(args, ctx);
+      const escalationId = requireArg(args.shift(), "escalation-id");
+      const text = takeFlag(args, "--text");
+      const choice = takeFlag(args, "--choice");
+      const { envelope, ...escalation } = await store.answerEscalation(escalationId, { text, choice });
+      if (envelope && deliver) {
+        const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
+        return { text: `Answered ${escalationId}; routed response to ${envelope.to_agent_id} over the mailbox (host id ${ack.id})`, json: { ...escalation, response_envelope: envelope } };
+      }
+      const tail = envelope ? `; deliver the response envelope to ${envelope.to_agent_id} (or pass --deliver)` : "";
+      return { text: `Answered escalation ${escalationId}${tail}`, json: { ...escalation, response_envelope: envelope } };
+    }
+    if (action === "respond") {
+      const source = requireArg(args.shift(), "envelope-json-path");
+      const escalation = await store.applyEscalationResponse(await readEnvelope(source));
+      return { text: `Applied escalation response for ${escalation.escalation_id}`, json: escalation };
+    }
+    throw new EdgeBookError("unknown_action", `Unknown escalation action: ${action}`);
+  }
   if (command === "inbox") {
     const action = args.shift() || "list";
     if (action === "list") {

package/package.json

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