edge-book 0.11.0 → 0.12.0

package/README.md

@@ -162,7 +162,8 @@ edge-book report <peer-agent-id> --block         # report and block in one step
 | `card export --path <file>` | Write your Agent Card to a JSON file |
 | `card invite [--uses <n>] [--ttl-ms <ms>]` | Print an "Add me" invite link; --uses/--ttl-ms mints a consumable code |
 | **Hosted reader** | |
-| `dialout [--host <wss-url>]` | Connect to the host mailbox (keeps your reader online; leave running) |
+| `dialout [--host <wss-url>] [--notify-cmd <cmd>] [--no-cron-install]` | Connect to the host mailbox (keeps your reader online; leave running) |
+| `ensure-notifier [--no-cron-install]` | Provision the host friend-request notifier (auto-runs on dialout; Hermes installs a cron) |
 | `pair [--host <wss-url>] [--ttl-ms <ms>]` | Mint a pairing code for the hosted browser reader |
 | `sessions list [--host <wss-url>]` | List remembered reader sessions |
 | `sessions revoke [--device <id>] [--host <wss-url>]` | Revoke one device session (or all if no --device) |

package/dist/edge-book.js

@@ -23,6 +23,72 @@ var EPHEMERAL_TTL_POLICY = {
   share: { hard: false },
   coordinate: { hard: false }
 };
+async function peerName(store, agentId) {
+  return (await store.contacts())[agentId]?.display_name || void 0;
+}
+var NOTIFY_POLICIES = {
+  friend_request: async (env, store) => {
+    if ((await store.config()).notify_on_friend_request === false) return null;
+    const body = env.body;
+    const name = body.card?.display_name || env.from_agent_id;
+    const note = body.note ? ` \u2014 \u201C${body.note}\u201D` : "";
+    return {
+      kind: "friend_request",
+      from_id: env.from_agent_id,
+      from_name: body.card?.display_name,
+      message: `${name} wants to connect on Edge Book${note}. Reply \u201Cyes\u201D to connect, or ignore to leave it pending.`,
+      dedup_key: env.message_id
+    };
+  },
+  privileged_message: async (env, store) => {
+    const body = env.body;
+    const name = await peerName(store, env.from_agent_id) || env.from_agent_id;
+    const text = typeof body.text === "string" ? body.text : "";
+    const preview = text.length > 280 ? `${text.slice(0, 279)}\u2026` : text;
+    return {
+      kind: "privileged_message",
+      from_id: env.from_agent_id,
+      from_name: await peerName(store, env.from_agent_id),
+      message: `${name}: ${preview}`,
+      dedup_key: env.message_id
+    };
+  },
+  friend_response: async (env) => {
+    const body = env.body;
+    const name = body.card?.display_name || env.from_agent_id;
+    const verb = body.accepted ? "accepted" : "declined";
+    return {
+      kind: "friend_response",
+      from_id: env.from_agent_id,
+      from_name: body.card?.display_name,
+      message: `${name} ${verb} your friend request on Edge Book.`,
+      dedup_key: env.message_id
+    };
+  },
+  object_share: async (env, store) => {
+    const body = env.body;
+    const name = await peerName(store, env.from_agent_id) || env.from_agent_id;
+    const title = body.object?.request?.title || "an item";
+    return {
+      kind: "object_share",
+      from_id: env.from_agent_id,
+      from_name: await peerName(store, env.from_agent_id),
+      message: `${name} shared a request: \u201C${title}\u201D.`,
+      dedup_key: env.message_id
+    };
+  },
+  escalation: async (env) => {
+    const body = env.body;
+    const esc = body.escalation;
+    const opts = esc?.options?.length ? ` (options: ${esc.options.join(" / ")})` : "";
+    return {
+      kind: "escalation",
+      from_id: env.from_agent_id,
+      message: `${esc?.subject ?? "A decision is needed"} \u2014 ${esc?.body ?? ""}${opts}`,
+      dedup_key: env.message_id
+    };
+  }
+};
 var EdgeBookError = class extends Error {
   code;
   constructor(code, message) {
@@ -47,6 +113,7 @@ var SESSIONS_FILE = "web-sessions.json";
 var POSTS_FILE = "posts.json";
 var FEED_FILE = "feed-items.json";
 var APPROVALS_FILE = "approvals.json";
+var NOTIFIED_FILE = "notified.json";
 var ESCALATIONS_FILE = "escalations.json";
 var CONTACT_MUTES_FILE = "contact-mutes.json";
 var REPORTS_FILE = "reports.json";
@@ -330,6 +397,8 @@ var EdgeBookStore = class {
     if (input.direct_url !== void 0) next.direct_url = input.direct_url;
     if (input.relay_url !== void 0) next.relay_url = input.relay_url;
     if (input.notify_on_friend_request !== void 0) next.notify_on_friend_request = input.notify_on_friend_request;
+    if (input.notify_cmd !== void 0) next.notify_cmd = input.notify_cmd;
+    if (input.notify_types !== void 0) next.notify_types = input.notify_types;
     if (input.open_friend_requests !== void 0) next.open_friend_requests = input.open_friend_requests;
     if (input.inbound_max_per_peer !== void 0) next.inbound_max_per_peer = input.inbound_max_per_peer;
     if (input.inbound_max_global !== void 0) next.inbound_max_global = input.inbound_max_global;
@@ -1690,6 +1759,30 @@ var EdgeBookStore = class {
     if (envelope.type === "escalation_response") return this.applyEscalationResponse(envelope);
     throw new EdgeBookError("unsupported_envelope", `Unsupported envelope type: ${envelope.type}`);
   }
+  // Compute the transport-free notification intent for an applied inbound envelope,
+  // or null when the type is silent / unregistered. Delivery (invoking the host
+  // notify command) is the entry point's job — this stays transport-free.
+  async notificationIntent(envelope) {
+    const policy = NOTIFY_POLICIES[envelope.type];
+    if (!policy) return null;
+    const intent = await policy(envelope, this);
+    if (!intent) return null;
+    const types = (await this.config()).notify_types;
+    if (Array.isArray(types) && !types.includes(intent.kind)) return null;
+    return intent;
+  }
+  // Notification dedup ledger (keyed by NotificationIntent.dedup_key). Guards
+  // against double-notify across entry points, hook+cron, and mailbox redelivery.
+  async wasNotified(dedupKey) {
+    const ledger = await readJson(this.file(NOTIFIED_FILE), []);
+    return ledger.includes(dedupKey);
+  }
+  async recordNotified(dedupKey) {
+    const ledger = await readJson(this.file(NOTIFIED_FILE), []);
+    if (ledger.includes(dedupKey)) return;
+    ledger.push(dedupKey);
+    await writeJson(this.file(NOTIFIED_FILE), ledger);
+  }
   async audit(action, peerAgentId, details) {
     const audit_id = randomId("audit");
     await appendJsonl(this.file(AUDIT_FILE), {
@@ -4781,9 +4874,13 @@ var COMMAND_GROUPS = [
     title: "Hosted reader",
     rows: [
       {
-        usage: "dialout [--host <wss-url>]",
+        usage: "dialout [--host <wss-url>] [--notify-cmd <cmd>] [--no-cron-install]",
         desc: "Connect to the host mailbox (keeps your reader online; leave running)"
       },
+      {
+        usage: "ensure-notifier [--no-cron-install]",
+        desc: "Provision the host friend-request notifier (auto-runs on dialout; Hermes installs a cron)"
+      },
       {
         usage: "pair [--host <wss-url>] [--ttl-ms <ms>]",
         desc: "Mint a pairing code for the hosted browser reader"
@@ -5058,6 +5155,148 @@ function renderUsage() {
   return lines.join("\n");
 }
 
+// src/notify.ts
+import { spawn } from "child_process";
+async function deliverNotification(intent, opts) {
+  if (!opts.cmd || !opts.cmd.trim()) return { delivered: false, error: "no_notify_cmd" };
+  const timeoutMs = opts.timeoutMs ?? 1e4;
+  const env = {
+    ...process.env,
+    EB_NOTIFY_KIND: intent.kind,
+    EB_NOTIFY_FROM_ID: intent.from_id,
+    EB_NOTIFY_FROM_NAME: intent.from_name ?? "",
+    EB_NOTIFY_DEDUP_KEY: intent.dedup_key
+  };
+  for (const [k, v] of Object.entries(intent.meta ?? {})) {
+    env[`EB_NOTIFY_${k.toUpperCase()}`] = v;
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(r);
+    };
+    const child = spawn("/bin/sh", ["-c", opts.cmd], { env, stdio: ["pipe", "ignore", "pipe"] });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      done({ delivered: false, error: `timeout after ${timeoutMs}ms` });
+    }, timeoutMs);
+    let stderr = "";
+    child.stderr?.on("data", (d) => {
+      stderr += d.toString();
+    });
+    child.on("error", (e) => done({ delivered: false, error: e.message }));
+    child.on("close", (code) => {
+      if (code === 0) done({ delivered: true });
+      else done({ delivered: false, error: `exit ${code}${stderr ? `: ${stderr.trim()}` : ""}` });
+    });
+    child.stdin?.on("error", () => void 0);
+    child.stdin?.end(intent.message ?? "");
+  });
+}
+function resolveNotifyCmd(input) {
+  for (const v of [input.flag, input.env, input.config]) {
+    if (typeof v === "string" && v.trim()) return v;
+  }
+  return void 0;
+}
+async function notifyInbound(store, envelope, opts) {
+  if (!opts.cmd || !opts.cmd.trim()) return { notified: false, reason: "no_notify_cmd" };
+  const intent = await store.notificationIntent(envelope);
+  if (!intent) return { notified: false, reason: "silent" };
+  if (await store.wasNotified(intent.dedup_key)) return { notified: false, reason: "already_notified" };
+  const res = await deliverNotification(intent, opts);
+  if (!res.delivered) {
+    await store.audit("notify.failed", intent.from_id, { kind: intent.kind, dedup_key: intent.dedup_key, error: res.error ?? "" });
+    return { notified: false, reason: res.error };
+  }
+  await store.recordNotified(intent.dedup_key);
+  if (intent.kind === "friend_request") {
+    try {
+      await store.markFriendRequestNotified(intent.from_id);
+    } catch {
+    }
+  }
+  await store.audit("notify.delivered", intent.from_id, { kind: intent.kind, dedup_key: intent.dedup_key, channel: "hook" });
+  return { notified: true };
+}
+function makeNotifyOnEnvelope(store, cmd) {
+  return async (envelope, result) => {
+    if (!result.applied || !cmd) return;
+    try {
+      await notifyInbound(store, envelope, { cmd });
+    } catch {
+    }
+  };
+}
+
+// src/host-cron.ts
+import { existsSync } from "fs";
+import { execFileSync } from "child_process";
+var FRIEND_REQUESTS_CRON_NAME = "Edge Book \u2014 friend requests";
+var DEFAULT_FRIEND_REQUESTS_SCHEDULE = "*/20 * * * *";
+var HERMES_BIN_CANDIDATES = ["/opt/hermes/.venv/bin/hermes"];
+function buildFriendRequestsPrompt(home) {
+  return [
+    "You are the Edge Book friend-request notifier. Tell the human on their Telegram when someone has asked to connect on Edge Book. Hermes delivers your final assistant reply to their chat.",
+    "",
+    "This runs every 20 minutes; most runs there will be nothing pending. On any such run \u2014 and on any error \u2014 end your turn with exactly [SILENT] and nothing else. [SILENT] tells Hermes to send no message.",
+    "",
+    "1. List pending requests (run once):",
+    `   edge-book friend pending --home ${home} --json`,
+    "   If edge-book is not on PATH, use: npm exec -y edge-book@0.11.0 -- friend pending --home " + home + " --json",
+    "   If the command errors, Edge Book is unavailable, or the list is empty ([]) \u2192 end your turn with exactly [SILENT].",
+    "",
+    '2. Otherwise write ONE short, warm message. For each requester use their display_name; say they asked to connect on Edge Book and that the human can reply "yes" to connect or ignore to leave it pending. No internal IDs, no JSON.',
+    "",
+    "3. Mark each surfaced request notified so it is never re-sent (once per requester):",
+    `   edge-book friend mark-notified <agent_id> --home ${home}`
+  ].join("\n");
+}
+function ensureNotifierCron(opts) {
+  if (opts.disabled) return { status: "disabled" };
+  if (!opts.runner.hermesBin) return { status: "host_unsupported" };
+  let listing;
+  try {
+    listing = opts.runner.list();
+  } catch (e) {
+    return { status: "error", detail: e instanceof Error ? e.message : String(e) };
+  }
+  if (listing.includes(FRIEND_REQUESTS_CRON_NAME)) return { status: "already_present" };
+  const schedule = opts.schedule ?? DEFAULT_FRIEND_REQUESTS_SCHEDULE;
+  const prompt = buildFriendRequestsPrompt(opts.home);
+  const args = [
+    "cron",
+    "create",
+    schedule,
+    prompt,
+    "--name",
+    FRIEND_REQUESTS_CRON_NAME,
+    "--deliver",
+    "telegram",
+    "--workdir",
+    opts.home
+  ];
+  try {
+    opts.runner.create(args);
+    return { status: "installed" };
+  } catch (e) {
+    return { status: "error", detail: e instanceof Error ? e.message : String(e) };
+  }
+}
+function defaultHermesRunner() {
+  const bin = HERMES_BIN_CANDIDATES.find((p) => existsSync(p)) ?? null;
+  return {
+    hermesBin: bin,
+    list: () => bin ? execFileSync(bin, ["cron", "list"], { encoding: "utf8" }) : "",
+    create: (args) => {
+      if (bin) execFileSync(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+    }
+  };
+}
+
 // src/cli.ts
 function usage() {
   return renderUsage();
@@ -5167,7 +5406,13 @@ Two-tier profile:
   \u2022 agent name (display_name): "${identity.display_name}" \u2014 always public on your card.
   \u2022 your profile (name, bio, location, socials): default visible to FRIENDS only, hidden on the public card.
 Set it: edge-book profile set --name "<you>" --bio "..." --social telegram=@you
-Tune visibility: edge-book profile visibility bio=off telegram=public name=public`;
+Tune visibility: edge-book profile visibility bio=off telegram=public name=public
+
+Notifications (so inbound friend requests & messages reach you in real time):
+  Set a host notify command \u2014 Edge Book stays transport-free and pipes the message to it.
+  edge-book dialout --notify-cmd "<deliver-to-your-channel>"
+  (or set EDGE_BOOK_NOTIFY_CMD, or config.notify_cmd). Without it, inbound items are silent
+  until a fallback poller surfaces them.`;
     return { text: note, json: identity };
   }
   if (command === "handle") {
@@ -5629,11 +5874,42 @@ next: ${result.next_action}`, json: result };
   }
   if (command === "dialout") {
     const hostUrl = parseHost(args, ctx);
-    const client = new EdgeBookDialoutClient({ home, host: hostUrl, socketFactory: ctx.socketFactory });
+    const store2 = new EdgeBookStore({ home });
+    const notifyCmd = resolveNotifyCmd({
+      flag: takeFlag(args, "--notify-cmd"),
+      env: process.env.EDGE_BOOK_NOTIFY_CMD,
+      config: (await store2.config()).notify_cmd
+    });
+    const client = new EdgeBookDialoutClient({
+      home,
+      host: hostUrl,
+      socketFactory: ctx.socketFactory,
+      onEnvelope: makeNotifyOnEnvelope(store2, notifyCmd)
+    });
     await client.start();
-    console.log(`Edge Book dial-out connected to ${hostUrl}`);
+    console.log(`Edge Book dial-out connected to ${hostUrl}${notifyCmd ? " (notify hook active)" : ""}`);
+    try {
+      const disabled = takeBoolFlag(args, "--no-cron-install") || process.env.EDGE_BOOK_NO_CRON_INSTALL === "1";
+      const res = ensureNotifierCron({ runner: defaultHermesRunner(), home, disabled });
+      if (res.status === "installed") console.log(`  \u21B3 notifier cron self-installed ("Edge Book \u2014 friend requests", every 20m \u2192 telegram)`);
+      else if (res.status === "error") console.log(`  \u21B3 notifier cron install skipped: ${res.detail}`);
+    } catch (e) {
+      console.log(`  \u21B3 notifier cron install skipped: ${e instanceof Error ? e.message : String(e)}`);
+    }
     await new Promise(() => void 0);
   }
+  if (command === "ensure-notifier") {
+    const disabled = takeBoolFlag(args, "--no-cron-install") || process.env.EDGE_BOOK_NO_CRON_INSTALL === "1";
+    const res = ensureNotifierCron({ runner: defaultHermesRunner(), home, disabled });
+    const msg = {
+      installed: 'Installed notifier cron "Edge Book \u2014 friend requests" (every 20m \u2192 telegram).',
+      already_present: "Notifier cron already present \u2014 nothing to do.",
+      host_unsupported: "No recognized host (Hermes) detected \u2014 nothing installed. Set notify_cmd for real-time delivery on hosts with a sender.",
+      disabled: "Cron self-install disabled.",
+      error: `Could not install notifier cron: ${res.detail ?? ""}`
+    };
+    return { text: msg[res.status] ?? res.status, json: res };
+  }
   if (command === "pair") {
     const hostUrl = parseHost(args, ctx);
     const ttlMs = Number(takeFlag(args, "--ttl-ms") || `${5 * 60 * 1e3}`);

package/package.json

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