edge-book 0.1.3 → 0.2.0

package/dist/edge-book.js

@@ -28,6 +28,8 @@ var EdgeBookError = class extends Error {
 var IDENTITY_FILE = "identity.json";
 var CONTACTS_FILE = "contacts.json";
 var GRANTS_FILE = "grants.json";
+var OBJECTS_FILE = "objects.json";
+var ATTACHMENTS_DIR = "attachments";
 var SEEN_MESSAGES_FILE = "seen-messages.json";
 var CONFIG_FILE = "config.json";
 var RELATIONSHIP_EVENTS_FILE = "relationship-events.jsonl";
@@ -450,6 +452,213 @@ var EdgeBookStore = class {
     await appendJsonl(this.file(INBOX_FILE), envelope);
     await this.audit("message.receive", envelope.from_agent_id, { message_id: envelope.message_id });
   }
+  // ──────────────────────────────────────────────────────────────────────
+  // Edge Book MVP: single shared object + object.read grant (spec-0020 R2/R3)
+  // ea-claude-066. One object type ("request"), ≤1 attachment, fail-closed
+  // access, append-only audit on create/grant/access/revoke. No R4 fields.
+  // ──────────────────────────────────────────────────────────────────────
+  async objects() {
+    return readJson(this.file(OBJECTS_FILE), {});
+  }
+  async saveObjects(objects) {
+    await writeJson(this.file(OBJECTS_FILE), objects);
+  }
+  async getObject(objectId) {
+    return (await this.objects())[objectId];
+  }
+  // Create one shared object (a request + at most one attachment). Signed and
+  // stored locally; writes an `object.create` audit event.
+  async createObject(input) {
+    const identity = await this.identity();
+    const object_id = randomId("obj");
+    let attachment;
+    if (input.attachment) {
+      const ref = path.join(ATTACHMENTS_DIR, `${object_id}-${input.attachment.filename}`);
+      await fs.mkdir(this.file(ATTACHMENTS_DIR), { recursive: true });
+      await fs.writeFile(this.file(ref), input.attachment.bytes);
+      attachment = {
+        filename: input.attachment.filename,
+        mime: input.attachment.mime,
+        size: input.attachment.bytes.length,
+        ref
+      };
+    }
+    const unsigned = {
+      object_id,
+      type: "request",
+      from_agent: identity.agent_id,
+      request: { title: input.title, body: input.body },
+      ...attachment ? { attachment } : {},
+      created_at: now()
+    };
+    const object = { ...unsigned, signature: signPayload(unsigned, identity.private_key_pem) };
+    const objects = await this.objects();
+    objects[object_id] = object;
+    await this.saveObjects(objects);
+    await this.audit("object.create", identity.agent_id, { object_id, has_attachment: Boolean(attachment) });
+    return object;
+  }
+  // Issue an `object.read` grant binding ONE object to ONE subject (revocable).
+  async issueObjectGrant(subjectAgentId, objectId, expiresAt = "") {
+    const identity = await this.identity();
+    if (!await this.getObject(objectId)) throw new EdgeBookError("unknown_object", `Unknown object: ${objectId}`);
+    const unsigned = {
+      grant_id: randomId("grant"),
+      issuer_agent_id: identity.agent_id,
+      subject_agent_id: subjectAgentId,
+      relationship_id: relationshipId(identity.agent_id, subjectAgentId),
+      scopes: ["object.read"],
+      status: "active",
+      issued_at: now(),
+      expires_at: expiresAt,
+      revoked_at: "",
+      audit_refs: [],
+      object_id: objectId
+    };
+    const grant = { ...unsigned, signature: signPayload(unsigned, identity.private_key_pem) };
+    await this.storeGrant(grant);
+    await this.audit("grant.issue", subjectAgentId, { grant_id: grant.grant_id, object_id: objectId, scope: "object.read" });
+    return grant;
+  }
+  // Fail-closed predicate (spec-0020 R3): readable IFF an active, unexpired
+  // `object.read` grant exists for (object_id, subject). Does NOT audit — use
+  // readObject() for an audited access. The object's owner may always read it.
+  async canReadObject(objectId, subjectAgentId, at = Date.now()) {
+    const object = await this.getObject(objectId);
+    if (object && object.from_agent === subjectAgentId) return true;
+    const grants = await this.grants();
+    return Object.values(grants).some(
+      (grant) => grant.object_id === objectId && grant.subject_agent_id === subjectAgentId && grant.scopes.includes("object.read") && grant.status === "active" && (!grant.expires_at || Date.parse(grant.expires_at) > at)
+    );
+  }
+  // Audited read. Returns the object iff canReadObject; else fails closed.
+  async readObject(objectId, subjectAgentId) {
+    const object = await this.getObject(objectId);
+    if (!object || !await this.canReadObject(objectId, subjectAgentId)) {
+      throw new EdgeBookError("access_denied", `No active object.read grant for (${objectId}, ${subjectAgentId})`);
+    }
+    await this.audit("object.access", subjectAgentId, { object_id: objectId });
+    return object;
+  }
+  // Raw bytes of an object's (single) attachment, agent-held under attachments/.
+  // Caller is responsible for the access check (readObject) first.
+  async readAttachmentBytes(objectId) {
+    const object = await this.getObject(objectId);
+    if (!object?.attachment) throw new EdgeBookError("no_attachment", `No attachment for ${objectId}`);
+    return fs.readFile(this.file(object.attachment.ref));
+  }
+  // Objects the given subject (default: me) may currently read — the data behind
+  // the reader's "Shared with me" surface. Read-through is unaudited (listing);
+  // readObject() audits the actual open.
+  async sharedObjectsFor(subjectAgentId) {
+    const subject = subjectAgentId ?? (await this.identity()).agent_id;
+    const objects = await this.objects();
+    const out = [];
+    for (const object of Object.values(objects)) {
+      if (object.from_agent === subject) continue;
+      if (await this.canReadObject(object.object_id, subject)) out.push(object);
+    }
+    return out.sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+  }
+  // Build a signed `object_share` envelope (object + grant + inline attachment)
+  // to deliver to a friend over the mailbox transport (ea-claude-065).
+  async shareObjectEnvelope(peerAgentId, objectId, expiresAt = "") {
+    const identity = await this.identity();
+    const contact = (await this.contacts())[peerAgentId];
+    if (!contact) throw new EdgeBookError("unknown_contact", `Unknown contact: ${peerAgentId}`);
+    if (contact.relationship_state !== "friend") {
+      throw new EdgeBookError("not_friend", `Cannot share to relationship_state=${contact.relationship_state}`);
+    }
+    const object = await this.getObject(objectId);
+    if (!object) throw new EdgeBookError("unknown_object", `Unknown object: ${objectId}`);
+    const grant = await this.issueObjectGrant(peerAgentId, objectId, expiresAt);
+    let attachment_b64;
+    if (object.attachment) {
+      attachment_b64 = (await fs.readFile(this.file(object.attachment.ref))).toString("base64");
+    }
+    return this.signEnvelope({
+      type: "object_share",
+      to_agent_id: peerAgentId,
+      relationship_id: relationshipId(identity.agent_id, peerAgentId),
+      capability_id: grant.grant_id,
+      ref: objectId,
+      transport: "local",
+      body: { object, grant, ...attachment_b64 ? { attachment_b64 } : {} }
+    });
+  }
+  // Apply a received `object_share`: store the object (+ attachment) and grant,
+  // after verifying the envelope signature and that the grant matches.
+  async receiveObjectShare(envelope) {
+    await this.verifyEnvelope(envelope);
+    if (envelope.type !== "object_share") throw new EdgeBookError("wrong_message_type", "Expected object_share envelope");
+    const identity = await this.identity();
+    const body = envelope.body;
+    const { object, grant } = body;
+    if (!object || !grant) throw new EdgeBookError("malformed_object_share", "object_share missing object or grant");
+    if (object.from_agent !== envelope.from_agent_id) throw new EdgeBookError("agent_id_mismatch", "Shared object author does not match sender");
+    if (grant.object_id !== object.object_id || grant.subject_agent_id !== identity.agent_id || !grant.scopes.includes("object.read")) {
+      throw new EdgeBookError("grant_mismatch", "Grant does not bind this object to me with object.read");
+    }
+    if (body.attachment_b64 && object.attachment) {
+      await fs.mkdir(this.file(ATTACHMENTS_DIR), { recursive: true });
+      await fs.writeFile(this.file(object.attachment.ref), Buffer.from(body.attachment_b64, "base64"));
+    }
+    const objects = await this.objects();
+    objects[object.object_id] = object;
+    await this.saveObjects(objects);
+    await this.storeGrant(grant);
+    await this.audit("object.receive", envelope.from_agent_id, { object_id: object.object_id, grant_id: grant.grant_id });
+    return object;
+  }
+  // Revoke an object.read grant (forward-looking; does not claw back delivered
+  // data). Writes a `grant.revoke` audit event. Returns the revoked grant_ids.
+  async revokeObjectGrant(objectId, subjectAgentId) {
+    const grants = await this.grants();
+    const revoked = [];
+    for (const grant of Object.values(grants)) {
+      if (grant.object_id === objectId && grant.subject_agent_id === subjectAgentId && grant.status === "active") {
+        grant.status = "revoked";
+        grant.revoked_at = now();
+        revoked.push(grant.grant_id);
+      }
+    }
+    if (revoked.length) {
+      await this.saveGrants(grants);
+      await this.audit("grant.revoke", subjectAgentId, { object_id: objectId, grant_ids: revoked });
+    }
+    return revoked;
+  }
+  // Build a signed `object_revoke` envelope to forward the revoke to the peer.
+  async revokeObjectEnvelope(peerAgentId, objectId) {
+    const identity = await this.identity();
+    const revoked = await this.revokeObjectGrant(objectId, peerAgentId);
+    return this.signEnvelope({
+      type: "object_revoke",
+      to_agent_id: peerAgentId,
+      relationship_id: relationshipId(identity.agent_id, peerAgentId),
+      capability_id: revoked[0] || "",
+      ref: objectId,
+      transport: "local",
+      body: { object_id: objectId, grant_id: revoked[0] || "" }
+    });
+  }
+  // Apply a received `object_revoke`: mark the matching grant revoked locally.
+  async receiveObjectRevoke(envelope) {
+    await this.verifyEnvelope(envelope);
+    if (envelope.type !== "object_revoke") throw new EdgeBookError("wrong_message_type", "Expected object_revoke envelope");
+    const body = envelope.body;
+    const grants = await this.grants();
+    let changed = false;
+    for (const grant of Object.values(grants)) {
+      if (grant.object_id === body.object_id && grant.issuer_agent_id === envelope.from_agent_id && grant.status === "active") {
+        grant.status = "revoked";
+        grant.revoked_at = now();
+        changed = true;
+      }
+    }
+    if (changed) await this.saveGrants(grants);
+    await this.audit("object.revoke.receive", envelope.from_agent_id, { object_id: body.object_id });
+  }
   async findUsableGrant(peerAgentId, scope) {
     const identity = await this.identity();
     const grants = await this.grants();
@@ -498,6 +707,14 @@ var EdgeBookStore = class {
     if (envelope.type === "friend_request") return this.receiveFriendRequest(envelope);
     if (envelope.type === "friend_response") return this.applyFriendResponse(envelope);
     if (envelope.type === "privileged_message") return this.receivePrivilegedMessage(envelope);
+    if (envelope.type === "object_share") {
+      await this.receiveObjectShare(envelope);
+      return;
+    }
+    if (envelope.type === "object_revoke") {
+      await this.receiveObjectRevoke(envelope);
+      return;
+    }
     throw new EdgeBookError("unsupported_envelope", `Unsupported envelope type: ${envelope.type}`);
   }
   async audit(action, peerAgentId, details) {
@@ -886,6 +1103,12 @@ function validateCard(card) {
   }
 }
 async function loadCard(cardPathOrUrl) {
+  if (cardPathOrUrl.startsWith("edgebook:invite:")) {
+    const encoded = cardPathOrUrl.slice("edgebook:invite:".length);
+    const card2 = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    validateCard(card2);
+    return card2;
+  }
   if (/^https?:\/\//.test(cardPathOrUrl)) {
     const response = await fetch(cardPathOrUrl);
     if (!response.ok) throw new EdgeBookError("card_fetch_failed", `Failed to fetch card: ${response.status}`);
@@ -980,6 +1203,14 @@ function sendHtml(res, value) {
   res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
   res.end(value);
 }
+function sendBinary(res, status, mime, filename, body) {
+  res.writeHead(status, {
+    "content-type": mime || "application/octet-stream",
+    "content-disposition": `inline; filename="${filename.replace(/[^\w.\- ]/g, "_")}"`,
+    "content-length": String(body.length)
+  });
+  res.end(body);
+}
 function sendError(res, error) {
   const status = error instanceof EdgeBookError && error.code === "unauthorized" ? 401 : error instanceof EdgeBookError && error.code === "csrf_required" ? 403 : error instanceof EdgeBookError ? 400 : 500;
   sendJson(res, status, {
@@ -1068,6 +1299,31 @@ async function handleOwnerApi(req, res, url, adapters) {
     sendJson(res, 200, { contacts: await store.contacts(), mutes: await store.contactMutes() });
     return true;
   }
+  if (req.method === "GET" && url.pathname === "/api/shared-objects") {
+    const objects = await store.sharedObjectsFor();
+    sendJson(res, 200, { objects: objects.map((object) => ({ ...object, grant_scope: "object.read" })) });
+    return true;
+  }
+  if (req.method === "GET" && url.pathname === "/api/invite") {
+    const card = await store.writeCard();
+    const identity = await store.identity();
+    const invite_url = `edgebook:invite:${Buffer.from(JSON.stringify(card), "utf8").toString("base64url")}`;
+    sendJson(res, 200, { agent_id: identity.agent_id, display_name: identity.display_name, card_url: card.card_url, card, invite_url });
+    return true;
+  }
+  const attachmentMatch = /^\/api\/shared-objects\/([^/]+)\/attachment$/.exec(url.pathname);
+  if (req.method === "GET" && attachmentMatch) {
+    const objectId = decodeURIComponent(attachmentMatch[1]);
+    const me = (await store.identity()).agent_id;
+    const object = await store.readObject(objectId, me);
+    if (!object.attachment) {
+      sendJson(res, 404, { ok: false, code: "no_attachment", error: "Object has no attachment" });
+      return true;
+    }
+    const bytes = await store.readAttachmentBytes(object.object_id);
+    sendBinary(res, 200, object.attachment.mime, object.attachment.filename, bytes);
+    return true;
+  }
   const contactMuteMatch = /^\/api\/contacts\/([^/]+)\/mute$/.exec(url.pathname);
   if (req.method === "POST" && contactMuteMatch) {
     const body = await readJsonBody(req);
@@ -2501,6 +2757,7 @@ var EdgeBookDialoutClient = class {
   currentBackoff;
   opened;
   pendingSessionRevokes = /* @__PURE__ */ new Map();
+  pendingMailboxSends = /* @__PURE__ */ new Map();
   constructor(options) {
     this.options = {
       heartbeatMs: options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
@@ -2509,6 +2766,8 @@ var EdgeBookDialoutClient = class {
       socketFactory: options.socketFactory ?? socketFactory,
       openLocalApi: options.openLocalApi ?? true,
       onStandDown: options.onStandDown ?? (() => void 0),
+      autoApplyEnvelopes: options.autoApplyEnvelopes ?? true,
+      onEnvelope: options.onEnvelope ?? (() => void 0),
       host: options.host,
       home: options.home
     };
@@ -2549,6 +2808,73 @@ var EdgeBookDialoutClient = class {
     this.send(frame);
     return { frame, ack: await ackPromise };
   }
+  // ── Mailbox transport (Contract 1 / ea-claude-065) ─────────────────────────
+  // Low-level: hand an opaque blob to the host for delivery to `to` (a peer DID
+  // or channel_id). Resolves with the host-assigned message id once enqueued.
+  async sendMailbox(to, blob, timeoutMs = 5e3) {
+    const request_id = crypto2.randomUUID();
+    const blob_b64 = Buffer.from(blob).toString("base64");
+    const ack = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingMailboxSends.delete(request_id);
+        reject(new EdgeBookError("mailbox_send_timeout", "Timed out waiting for mailbox_send_ok"));
+      }, timeoutMs);
+      this.pendingMailboxSends.set(request_id, { resolve, reject, timer });
+    });
+    this.send({ type: "mailbox_send", request_id, to, blob_b64 });
+    return ack;
+  }
+  // High-level: deliver a signed envelope to its recipient (envelope.to_agent_id;
+  // the host resolves the DID to a channel). Used to route friend requests,
+  // object shares, and revokes through the mailbox instead of a manual file hop.
+  async sendEnvelope(envelope) {
+    return this.sendMailbox(envelope.to_agent_id, Buffer.from(JSON.stringify(envelope), "utf8"));
+  }
+  async handleMailboxDeliver(frame) {
+    let envelope;
+    let applied = false;
+    let error;
+    try {
+      envelope = JSON.parse(Buffer.from(frame.blob_b64, "base64").toString("utf8"));
+      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);
+        applied = true;
+      }
+    } catch (e) {
+      error = e instanceof Error ? e.message : String(e);
+    }
+    if (!this.mailboxQueue) this.send({ type: "mailbox_ack", id: frame.id });
+    if (envelope) await this.options.onEnvelope?.(envelope, { applied, error });
+  }
+  // Contract-1 Transport facade. Enabling it switches deliver handling to manual
+  // (queue) mode so the consumer drives apply + ack via receive()/ack().
+  mailboxQueue;
+  mailboxWaiters = [];
+  pushMailbox(m) {
+    this.mailboxQueue?.push(m);
+    this.mailboxWaiters.splice(0).forEach((w) => w());
+  }
+  transport() {
+    this.mailboxQueue ||= [];
+    const self = this;
+    return {
+      send: (recipient, bytes) => self.sendMailbox(recipient, bytes),
+      ack: async (id) => {
+        self.send({ type: "mailbox_ack", id });
+      },
+      receive: async function* () {
+        for (; ; ) {
+          while (self.mailboxQueue && self.mailboxQueue.length === 0) {
+            await new Promise((r) => self.mailboxWaiters.push(r));
+          }
+          const next = self.mailboxQueue?.shift();
+          if (next) yield next;
+        }
+      }
+    };
+  }
   async connect() {
     if (this.stopped) return;
     if (this.options.openLocalApi && !this.localApi) this.localApi = await openLocalApi(this.store);
@@ -2627,7 +2953,32 @@ var EdgeBookDialoutClient = class {
       }
       return;
     }
-    if (frame.type === "error") return;
+    const frameType = frame.type;
+    if (frameType === "mailbox_send_ok") {
+      const ack = frame;
+      const pending = this.pendingMailboxSends.get(ack.request_id || "");
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pendingMailboxSends.delete(ack.request_id || "");
+        pending.resolve({ id: ack.id || "" });
+      }
+      return;
+    }
+    if (frameType === "mailbox_send_err") {
+      const err = frame;
+      const pending = this.pendingMailboxSends.get(err.request_id || "");
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pendingMailboxSends.delete(err.request_id || "");
+        pending.reject(new EdgeBookError("mailbox_send_failed", err.error || "mailbox_send rejected"));
+      }
+      return;
+    }
+    if (frameType === "mailbox_deliver") {
+      await this.handleMailboxDeliver(frame);
+      return;
+    }
+    if (frameType === "error") return;
     if (frame.type !== "host.api.request" && frame.type !== "api_request") return;
     const response = await this.handleApiRequest(frame);
     this.send(response);
@@ -2692,6 +3043,16 @@ async function sendPairRegistration(options) {
   await client.stop();
   return registration;
 }
+async function deliverEnvelopeViaMailbox(options) {
+  const client = new EdgeBookDialoutClient({ ...options, reconnect: false, openLocalApi: false });
+  await client.start();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  try {
+    return await client.sendEnvelope(options.envelope);
+  } finally {
+    await client.stop();
+  }
+}
 async function sendSessionsRevoke(options) {
   const client = new EdgeBookDialoutClient({ ...options, reconnect: false, openLocalApi: false });
   await client.start();
@@ -2717,7 +3078,8 @@ Local agent:
   edge-book doctor [--home <dir>]
   edge-book card show [--home <dir>]
   edge-book card export --path <file> [--home <dir>]
-  edge-book friend request <card-path-or-url> [--deliver] [--home <dir>]
+  edge-book card invite [--home <dir>]                       # "Add me" link (edgebook:invite:...)
+  edge-book friend request <card-path-or-url-or-invite> [--deliver] [--home <dir>]
   edge-book friend receive <envelope-json-path> [--home <dir>]
   edge-book friend accept <peer-agent-id> [--deliver] [--home <dir>]
   edge-book friend apply-response <envelope-json-path> [--home <dir>]
@@ -2727,6 +3089,11 @@ Local agent:
   edge-book contacts refresh <card-path-or-url> [--home <dir>]
   edge-book message send <peer-agent-id> --body <text> [--deliver] [--home <dir>]
   edge-book message receive <envelope-json-path> [--home <dir>]
+  edge-book object create --title <t> --body <b> [--file <path>] [--mime <type>] [--home <dir>]
+  edge-book object share <peer-agent-id> <object-id> [--deliver] [--host <ws-url>] [--home <dir>]
+  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 inbox list [--home <dir>]
   edge-book inbox pull --relay <url> [--home <dir>]
   edge-book serve --host <host> --port <port> [--home <dir>]
@@ -2814,6 +3181,11 @@ async function handleCli(inputArgs, ctx = {}) {
 `, "utf8");
       return { text: `Exported Agent Card to ${path4.resolve(target)}`, json: card };
     }
+    if (action === "invite") {
+      const card = await store.writeCard();
+      const inviteUrl = `edgebook:invite:${Buffer.from(JSON.stringify(card), "utf8").toString("base64url")}`;
+      return { text: inviteUrl, json: { invite_url: inviteUrl, agent_id: card.agent_id } };
+    }
   }
   if (command === "friend") {
     const action = args.shift();
@@ -2830,7 +3202,9 @@ async function handleCli(inputArgs, ctx = {}) {
           await postRelayEnvelope(relay, card.agent_id, envelope);
           return { text: `Queued friend_request via relay ${relay}`, json: envelope };
         }
-        throw new EdgeBookError("no_route", `No direct or relay endpoint for ${card.agent_id}`);
+        const hostUrl = parseHost(args, ctx);
+        const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
+        return { text: `Delivered friend_request to ${card.agent_id} over the mailbox (host id ${ack.id})`, json: envelope };
       }
       return { text: JSON.stringify(envelope, null, 2), json: envelope };
     }
@@ -2843,7 +3217,16 @@ async function handleCli(inputArgs, ctx = {}) {
       const deliver = takeBoolFlag(args, "--deliver");
       const peer = requireArg(args.shift(), "peer-agent-id");
       const envelope = await store.acceptFriend(peer);
-      if (deliver) return { text: await deliverToPeer(store, envelope, peer), json: envelope };
+      if (deliver) {
+        try {
+          return { text: await deliverToPeer(store, envelope, peer), json: envelope };
+        } 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 });
+          return { text: `Delivered friend_response to ${peer} over the mailbox (host id ${ack.id})`, json: envelope };
+        }
+      }
       return { text: JSON.stringify(envelope, null, 2), json: envelope };
     }
     if (action === "apply-response") {
@@ -2862,6 +3245,61 @@ async function handleCli(inputArgs, ctx = {}) {
       return { text: `Blocked ${peer}` };
     }
   }
+  if (command === "object") {
+    const action = args.shift();
+    if (action === "create") {
+      const title = requireArg(takeFlag(args, "--title"), "--title");
+      const body = requireArg(takeFlag(args, "--body"), "--body");
+      const file = takeFlag(args, "--file");
+      let attachment;
+      if (file) {
+        const bytes = await fs4.readFile(path4.resolve(file));
+        attachment = { filename: path4.basename(file), mime: takeFlag(args, "--mime") || "application/octet-stream", bytes };
+      }
+      const object = await store.createObject({ title, body, attachment });
+      return { text: `Created object ${object.object_id}`, json: object };
+    }
+    if (action === "share") {
+      const deliver = takeBoolFlag(args, "--deliver");
+      const hostUrl = parseHost(args, ctx);
+      const peer = requireArg(args.shift(), "peer-agent-id");
+      const objectId = requireArg(args.shift(), "object-id");
+      const envelope = await store.shareObjectEnvelope(peer, objectId);
+      if (deliver) {
+        const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
+        return { text: `Shared object ${objectId} to ${peer} over the mailbox (host id ${ack.id})`, json: envelope };
+      }
+      return { text: JSON.stringify(envelope, null, 2), json: envelope };
+    }
+    if (action === "revoke") {
+      const deliver = takeBoolFlag(args, "--deliver");
+      const hostUrl = parseHost(args, ctx);
+      const peer = requireArg(args.shift(), "peer-agent-id");
+      const objectId = requireArg(args.shift(), "object-id");
+      const envelope = await store.revokeObjectEnvelope(peer, objectId);
+      if (deliver) {
+        const ack = await deliverEnvelopeViaMailbox({ home, host: hostUrl, socketFactory: ctx.socketFactory, envelope });
+        return { text: `Revoked object ${objectId} for ${peer}; forwarded over the mailbox (host id ${ack.id})`, json: envelope };
+      }
+      return { text: JSON.stringify(envelope, null, 2), json: envelope };
+    }
+    if (action === "receive") {
+      const source = requireArg(args.shift(), "envelope-json-path");
+      await store.receiveEnvelope(await readEnvelope(source));
+      return { text: `Applied object envelope from ${path4.resolve(source)}` };
+    }
+    if (action === "list") {
+      const objects = await store.sharedObjectsFor();
+      return { text: JSON.stringify(objects, null, 2), json: objects };
+    }
+    if (action === "read") {
+      const objectId = requireArg(args.shift(), "object-id");
+      const me = (await store.identity()).agent_id;
+      const object = await store.readObject(objectId, me);
+      return { text: JSON.stringify(object, null, 2), json: object };
+    }
+    throw new EdgeBookError("unknown_action", `Unknown object action: ${action}`);
+  }
   if (command === "contacts") {
     const action = args.shift() || "list";
     if (action === "list") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edge-book",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Run your own Edge Book agent and connect it to the hosted reader.",
   "license": "MIT",
   "type": "module",
@@ -11,6 +11,7 @@
     "build": "tsup",
     "test": "node --test test/*.test.ts",
     "harness": "node bin/edge-book.js harness two-agent",
+    "harness:e2e": "node scripts/convergence-e2e.ts",
     "prepublishOnly": "npm run build"
   },
   "openclaw": {