@kybernesis/buzz 0.1.0 → 0.4.2

package/README.md

@@ -40,11 +40,24 @@ A member that only ever speaks looks offline between sentences, so the bridge al
 what a person's client publishes: presence on a heartbeat, a typing indicator while a turn is
 running, and 👀 on a message the moment it is picked up.
 
+## More than one community
+
+One agent, one identity, many communities. Membership is each workspace's to
+grant, so being in two is two connections rather than two agents — invite the
+same public key to each and list both relays:
+
+```bash
+BUZZ_RELAY="wss://one.communities.buzz.xyz,wss://two.communities.buzz.xyz"
+```
+
+Conversations never mix: a channel belongs to exactly one community, and
+sessions are keyed by channel.
+
 ## Configuration
 
 | Variable | Meaning |
 | --- | --- |
-| `BUZZ_RELAY` | The workspace relay (`wss://…`) |
+| `BUZZ_RELAY` | The workspace relay (`wss://…`) — or several, comma-separated |
 | `BUZZ_AGENT_URL` | Where the agent listens (default `http://127.0.0.1:8000`) |
 | `BUZZ_KEYFILE` | The agent's key (default `~/.kybernesis/buzz-agent.json`) |
 | `KYBERNESIS_ISSUER` | The control plane |

package/dist/bridge.d.ts

@@ -1,6 +1,15 @@
 export type BuzzBridgeOptions = {
-    /** The workspace relay, e.g. `wss://example.communities.buzz.xyz`. */
-    relay: string;
+    /**
+     * The workspace relay, or several of them.
+     *
+     * @remarks
+     * One agent, one identity, many communities. A workspace's membership is the
+     * relay's to grant, so being in two of them is two connections rather than
+     * two agents — and the same public key is invited to each. Sessions stay
+     * keyed by channel, and a channel belongs to exactly one community, so the
+     * conversations never mix.
+     */
+    relay: string | readonly string[];
     /** Where the agent is listening, e.g. `http://127.0.0.1:8000`. */
     agentUrl: string;
     /** The agent's own key file. Its public half is what the workspace invited. */
@@ -16,6 +25,8 @@ export declare function buzzBridge(options: BuzzBridgeOptions): {
     /** The key the workspace has to invite for any of this to happen. */
     npub: string;
     pubkey: string;
+    /** The communities this agent is a member of. */
+    relays: string[];
     start(): void;
     /** Say goodbye rather than letting presence lapse: a stopped agent should not look online. */
     stop(): void;

package/dist/bridge.js

@@ -86,16 +86,29 @@ export function buzzBridge(options) {
             relay.reply(dm, text);
         log(`refused ${npubEncode(sender).slice(0, 16)}…: ${reason}`);
     }
-    const relay = new BuzzRelay({
-        url: options.relay,
-        key,
-        pollMs: options.pollMs,
-        onLog: log,
-        onMessage: (event) => {
-            void handle(event);
-        },
-    });
-    async function handle(event) {
+    const urls = (typeof options.relay === "string" ? [options.relay] : [...options.relay])
+        .map((url) => url.trim())
+        .filter(Boolean);
+    if (urls.length === 0)
+        throw new Error("a workspace relay is required");
+    /** Which connection a message arrived on, so the reply goes back the same way. */
+    const relays = new Map();
+    for (const url of urls) {
+        relays.set(url, new BuzzRelay({
+            url,
+            key,
+            pollMs: options.pollMs,
+            // Which community is speaking matters once there is more than one.
+            onLog: (message) => log(urls.length > 1 ? `${label(url)} ${message}` : message),
+            onMessage: (event) => {
+                void handle(event, url);
+            },
+        }));
+    }
+    async function handle(event, from) {
+        const relay = relays.get(from);
+        if (!relay)
+            return;
         const channel = event.tags.find((t) => t[0] === "h")?.[1];
         // Addressed by TAG, not by text. A name in prose is a string anyone can type; a p tag is what
         // the client emits when someone actually picks this member out of a mention list.
@@ -145,14 +158,32 @@ export function buzzBridge(options) {
         /** The key the workspace has to invite for any of this to happen. */
         npub: key.npub,
         pubkey: key.publicKey,
+        /** The communities this agent is a member of. */
+        relays: urls,
         start() {
-            relay.connect();
-            log("listening — turns run as whoever sent them");
+            for (const relay of relays.values())
+                relay.connect();
+            log(urls.length > 1
+                ? `listening on ${urls.length} communities — turns run as whoever sent them`
+                : "listening — turns run as whoever sent them");
         },
         /** Say goodbye rather than letting presence lapse: a stopped agent should not look online. */
         stop() {
-            relay.setPresence("offline");
-            setTimeout(() => relay.close(), 250);
+            for (const relay of relays.values())
+                relay.setPresence("offline");
+            setTimeout(() => {
+                for (const relay of relays.values())
+                    relay.close();
+            }, 250);
         },
     };
 }
+/** A relay's host, short enough to prefix a log line with. */
+function label(url) {
+    try {
+        return `[${new URL(url).hostname.split(".")[0]}]`;
+    }
+    catch {
+        return "[relay]";
+    }
+}

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { buzzBridge } from "./bridge.js";
-import { asHexPubkey, loadOrCreateKey, npubEncode } from "./keys.js";
+import { asHexPubkey, loadKey, loadOrCreateKey, npubEncode } from "./keys.js";
+import * as profile from "./profile.js";
 /**
  * Setup and operation for an agent that lives in a workspace.
  *
@@ -32,9 +33,105 @@ function init() {
     console.log("  Anyone who talks to it is sent a sign-in link the first time, and after that");
     console.log("  their turns run as them.\n");
 }
+function relayList() {
+    return env("BUZZ_RELAY")
+        .split(",")
+        .map((url) => url.trim())
+        .filter(Boolean);
+}
+/** Take a `--flag value` off the argument list. */
+function flag(name) {
+    const at = process.argv.indexOf(`--${name}`);
+    return at === -1 ? undefined : process.argv[at + 1];
+}
+/**
+ * Say who this agent is, in every community it belongs to.
+ *
+ * A member with no profile shows as a truncated public key. Each community
+ * stores its own copy, so joining a second one means publishing again — which
+ * is what `--copy-from` is for.
+ */
+async function setProfile() {
+    const key = loadKey(KEY_FILE);
+    const urls = relayList();
+    const source = flag("copy-from");
+    if (source) {
+        const copied = await profile.copy(source, urls, key);
+        console.log(`\n  Copied ${copied.display_name ?? copied.name ?? "the profile"} from ${source} to:\n`);
+        for (const url of urls.filter((url) => url !== source))
+            console.log(`    ${url}`);
+        console.log();
+        return;
+    }
+    const name = flag("name");
+    if (!name) {
+        console.error("usage: kybernesis-buzz profile --name <name> [--about …] [--picture <file|url>]");
+        console.error("   or: kybernesis-buzz profile --copy-from <wss://…>");
+        process.exit(1);
+    }
+    // A local file is uploaded to the community and becomes a URL; a URL is used
+    // as given. Nobody should need storage of their own to give an agent a face.
+    let picture = flag("picture");
+    if (picture && !/^https?:\/\//.test(picture)) {
+        const path = picture.startsWith("~/")
+            ? join(homedir(), picture.slice(2))
+            : picture;
+        if (!existsSync(path)) {
+            console.error(`\n  No such image: ${path}\n`);
+            process.exit(1);
+        }
+        const bytes = readFileSync(path);
+        let uploaded;
+        for (const url of urls) {
+            try {
+                uploaded = await profile.uploadImage(url, key, bytes, profile.mediaTypeOf(path));
+                console.log(`  uploaded ${path.split("/").pop()} to ${url}`);
+                break;
+            }
+            catch (error) {
+                console.log(`  · ${url} — ${error.message}`);
+            }
+        }
+        if (!uploaded) {
+            console.error("\n  Could not upload the image to any community.\n");
+            process.exit(1);
+        }
+        picture = uploaded;
+    }
+    const wanted = {
+        name: name.toLowerCase().replace(/\s+/g, "-"),
+        display_name: name,
+        ...(flag("about") ? { about: flag("about") } : {}),
+        ...(picture ? { picture } : {}),
+        // Said plainly rather than left for people to work out.
+        bot: true,
+    };
+    // Each community is asked separately, and one refusal does not stop the
+    // others. Membership is per community, so being in one and not another is
+    // the ordinary case rather than an error worth aborting on.
+    let published = 0;
+    for (const url of urls) {
+        try {
+            await profile.write(url, key, wanted);
+            console.log(`  ✓ ${url}`);
+            published += 1;
+        }
+        catch (error) {
+            const why = error.message;
+            console.log(why.includes("not a relay member")
+                ? `  · ${url} — not a member yet, so nothing to be known as there`
+                : `  ✕ ${url} — ${why}`);
+        }
+    }
+    console.log(published > 0
+        ? `\n  ${name} is ${key.npub.slice(0, 20)}…\n`
+        : "\n  Nothing published — invite this key to a community first.\n");
+}
 function run() {
     const bridge = buzzBridge({
-        relay: env("BUZZ_RELAY"),
+        // Comma-separated: one agent can be a member of several communities, and
+        // each is a connection rather than another process to supervise.
+        relay: relayList(),
         agentUrl: process.env.BUZZ_AGENT_URL ?? "http://127.0.0.1:8000",
         keyFile: KEY_FILE,
         issuer: env("KYBERNESIS_ISSUER", "https://agent.kybernesis.ai"),
@@ -87,7 +184,13 @@ WantedBy=multi-user.target
     process.stdout.write(unit);
 }
 const command = process.argv[2];
-if (command === "init")
+if (command === "profile") {
+    setProfile().catch((error) => {
+        console.error(`\n  ${error.message}\n`);
+        process.exit(1);
+    });
+}
+else if (command === "init")
     init();
 else if (command === "run")
     run();
@@ -107,13 +210,15 @@ else {
   kybernesis-buzz — put an agent in a workspace
 
     init              create or show this agent's identity, and what to invite
+    profile           say who this agent is, in every community it belongs to
     run               run the bridge
     service [path]    print (or write) a systemd unit for it
     id <npub|hex>     show a public key in both forms
 
   Environment:
 
-    BUZZ_RELAY                     the workspace relay (wss://…)
+    BUZZ_RELAY                     the workspace relay (wss://…), or several,
+                                   comma-separated
     BUZZ_AGENT_URL                 where the agent listens (default http://127.0.0.1:8000)
     BUZZ_KEYFILE                   this agent's key (default ~/.kybernesis/buzz-agent.json)
     KYBERNESIS_ISSUER              the control plane

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { buzzBridge, type BuzzBridge, type BuzzBridgeOptions } from "./bridge.js";
 export { BuzzRelay, type NostrEvent, type PresenceStatus, type RelayOptions, KIND_MESSAGE, KIND_REACTION, KIND_PRESENCE, KIND_TYPING, KIND_DM_OPEN, } from "./relay.js";
 export { asHexPubkey, loadKey, loadOrCreateKey, npubEncode, type AgentKey } from "./keys.js";
+export * as profile from "./profile.js";
+export type { Profile } from "./profile.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { buzzBridge } from "./bridge.js";
 export { BuzzRelay, KIND_MESSAGE, KIND_REACTION, KIND_PRESENCE, KIND_TYPING, KIND_DM_OPEN, } from "./relay.js";
 export { asHexPubkey, loadKey, loadOrCreateKey, npubEncode } from "./keys.js";
+export * as profile from "./profile.js";

package/dist/profile.d.ts

@@ -0,0 +1,63 @@
+import type { AgentKey } from "./keys.js";
+/**
+ * How an agent appears to the people in a community.
+ *
+ * @remarks
+ * A member with no profile shows as a truncated public key, which reads as a
+ * stranger rather than as the agent someone was told to talk to. So this is
+ * part of joining a community, not a nicety afterwards.
+ *
+ * Profiles are per relay: each community stores its own copy, and being a
+ * member of two means publishing to both. That is the protocol's doing, not a
+ * choice here — which is why `copy` exists.
+ */
+/** NIP-01 metadata. */
+export declare const KIND_PROFILE = 0;
+export type Profile = {
+    /** The handle, lowercase and without spaces. */
+    name?: string;
+    /** The name as people should read it. */
+    display_name?: string;
+    about?: string;
+    /** A URL. Relays store the address, never the image. */
+    picture?: string;
+    /** Says plainly that this is an agent. Clients use it; so should we. */
+    bot?: boolean;
+};
+/** This agent's profile on one relay, if it has one there. */
+export declare function read(url: string, key: AgentKey): Promise<Profile | null>;
+/** Publish this agent's profile to one relay. */
+export declare function write(url: string, key: AgentKey, profile: Profile): Promise<void>;
+/** Take the profile an agent already has somewhere, and give it the same one here. */
+export declare function copy(from: string, to: readonly string[], key: AgentKey): Promise<Profile>;
+/**
+ * Put an image where the community can serve it, and answer with its URL.
+ *
+ * @remarks
+ * Blossom (BUD-01): the file is addressed by the hash of its own bytes, and the
+ * upload is authorised by an event carrying that hash. So the server can check
+ * that what arrived is what was signed for, and the same image uploaded twice
+ * is the same URL rather than two.
+ *
+ * It goes to the community rather than to storage of ours, which is the point:
+ * an agent's picture should not depend on a bucket belonging to whoever set it
+ * up, and nobody should need a blob token to give their agent a face.
+ */
+export declare function uploadImage(relay: string, key: AgentKey, bytes: Uint8Array, mediaType: string): Promise<string>;
+/**
+ * Remove everything from an image that is not the image.
+ *
+ * @remarks
+ * The community refuses uploads carrying metadata, and it is right to: a photo
+ * taken on a phone carries the phone, the time and often the place, and an
+ * avatar is exactly the kind of file nobody thinks about before sharing. So
+ * this strips rather than asks — the alternative is telling people to run
+ * `exiftool` before they can give their agent a face.
+ *
+ * Both formats are containers of tagged sections, and dropping a section needs
+ * no re-encoding: PNG chunks carry their own CRC, and JPEG segments their own
+ * length. The pixels are untouched.
+ */
+export declare function stripMetadata(bytes: Uint8Array, mediaType: string): Uint8Array;
+/** What kind of image this is, from its name. */
+export declare function mediaTypeOf(path: string): string;

package/dist/profile.js

@@ -0,0 +1,276 @@
+import { finalizeEvent } from "nostr-tools/pure";
+/**
+ * How an agent appears to the people in a community.
+ *
+ * @remarks
+ * A member with no profile shows as a truncated public key, which reads as a
+ * stranger rather than as the agent someone was told to talk to. So this is
+ * part of joining a community, not a nicety afterwards.
+ *
+ * Profiles are per relay: each community stores its own copy, and being a
+ * member of two means publishing to both. That is the protocol's doing, not a
+ * choice here — which is why `copy` exists.
+ */
+/** NIP-01 metadata. */
+export const KIND_PROFILE = 0;
+const now = () => Math.floor(Date.now() / 1000);
+/**
+ * Connect and wait until the relay has ACCEPTED this identity.
+ *
+ * @remarks
+ * Answering the challenge is not the same as being authenticated, and the
+ * difference is one round trip. Resolving on the send races the acceptance, and
+ * anything published in that window is refused with `auth-required: not
+ * authenticated` — which reads as a permissions problem rather than as a
+ * client that spoke too early.
+ */
+function connect(url, key) {
+    return new Promise((resolve, reject) => {
+        const socket = new WebSocket(url);
+        const failed = setTimeout(() => reject(new Error(`${url} did not answer`)), 15_000);
+        let challenged = null;
+        socket.addEventListener("message", (raw) => {
+            const frame = JSON.parse(String(raw.data));
+            if (frame[0] === "AUTH") {
+                const auth = finalizeEvent({
+                    kind: 22242,
+                    created_at: now(),
+                    tags: [
+                        ["relay", url],
+                        ["challenge", String(frame[1])],
+                    ],
+                    content: "",
+                }, key.secretKey);
+                challenged = auth.id;
+                socket.send(JSON.stringify(["AUTH", auth]));
+                return;
+            }
+            if (frame[0] === "OK" && frame[1] === challenged) {
+                clearTimeout(failed);
+                if (frame[2] === true) {
+                    resolve(socket);
+                }
+                else {
+                    reject(new Error(String(frame[3] ?? "this identity was refused")));
+                }
+            }
+        });
+        socket.addEventListener("error", () => {
+            clearTimeout(failed);
+            reject(new Error(`could not reach ${url}`));
+        });
+    });
+}
+/** This agent's profile on one relay, if it has one there. */
+export async function read(url, key) {
+    const socket = await connect(url, key);
+    return new Promise((resolve) => {
+        const done = (value) => {
+            try {
+                socket.close();
+            }
+            catch {
+                /* closing a closed socket is not an error worth raising */
+            }
+            resolve(value);
+        };
+        socket.addEventListener("message", (raw) => {
+            const frame = JSON.parse(String(raw.data));
+            if (frame[0] === "EVENT") {
+                const event = frame[2];
+                try {
+                    done(JSON.parse(String(event.content ?? "{}")));
+                }
+                catch {
+                    done(null);
+                }
+            }
+            if (frame[0] === "EOSE" || frame[0] === "CLOSED")
+                done(null);
+        });
+        socket.send(JSON.stringify(["REQ", "profile", { kinds: [KIND_PROFILE], authors: [key.publicKey] }]));
+        setTimeout(() => done(null), 12_000);
+    });
+}
+/** Publish this agent's profile to one relay. */
+export async function write(url, key, profile) {
+    const socket = await connect(url, key);
+    return new Promise((resolve, reject) => {
+        const event = finalizeEvent({ kind: KIND_PROFILE, created_at: now(), tags: [], content: JSON.stringify(profile) }, key.secretKey);
+        socket.addEventListener("message", (raw) => {
+            const frame = JSON.parse(String(raw.data));
+            if (frame[0] === "OK" && frame[1] === event.id) {
+                try {
+                    socket.close();
+                }
+                catch {
+                    /* already closing */
+                }
+                frame[2] === true ? resolve() : reject(new Error(String(frame[3] ?? "refused")));
+            }
+        });
+        socket.send(JSON.stringify(["EVENT", event]));
+        setTimeout(() => reject(new Error(`${url} did not acknowledge the profile`)), 15_000);
+    });
+}
+/** Take the profile an agent already has somewhere, and give it the same one here. */
+export async function copy(from, to, key) {
+    const profile = await read(from, key);
+    if (!profile)
+        throw new Error(`no profile to copy from ${from}`);
+    for (const url of to) {
+        if (url === from)
+            continue;
+        // A community this agent has not been invited to yet is not a failure of
+        // the copy; it simply has nowhere to put it.
+        try {
+            await write(url, key, profile);
+        }
+        catch (error) {
+            if (!error.message.includes("not a relay member"))
+                throw error;
+        }
+    }
+    return profile;
+}
+/**
+ * Put an image where the community can serve it, and answer with its URL.
+ *
+ * @remarks
+ * Blossom (BUD-01): the file is addressed by the hash of its own bytes, and the
+ * upload is authorised by an event carrying that hash. So the server can check
+ * that what arrived is what was signed for, and the same image uploaded twice
+ * is the same URL rather than two.
+ *
+ * It goes to the community rather than to storage of ours, which is the point:
+ * an agent's picture should not depend on a bucket belonging to whoever set it
+ * up, and nobody should need a blob token to give their agent a face.
+ */
+export async function uploadImage(relay, key, bytes, mediaType) {
+    const { createHash } = await import("node:crypto");
+    const base = relay.replace(/^wss:/, "https:").replace(/^ws:/, "http:").replace(/\/$/, "");
+    // Stripped BEFORE hashing: the hash has to be of what is actually sent, and a
+    // Blossom server checks that for itself.
+    const body = stripMetadata(bytes, mediaType);
+    const sha256 = createHash("sha256").update(body).digest("hex");
+    const expires = now() + 300;
+    const auth = finalizeEvent({
+        kind: 24242,
+        created_at: now(),
+        tags: [
+            ["t", "upload"],
+            ["x", sha256],
+            ["expiration", String(expires)],
+            ["server", new URL(base).host],
+        ],
+        content: "Upload buzz-media",
+    }, key.secretKey);
+    const header = `Nostr ${Buffer.from(JSON.stringify(auth)).toString("base64url")}`;
+    // PUT, not POST: Blossom addresses a blob by the hash of its bytes, so the
+    // upload is idempotent — the same image twice is the same URL, and the verb
+    // says so. POST answers 405 here, which reads as a missing endpoint rather
+    // than as the wrong method.
+    //
+    // Newer servers take /upload; older ones only /media/upload. Trying both is
+    // cheaper than asking an operator which one they are running.
+    let last = "";
+    for (const path of ["/upload", "/media/upload"]) {
+        const response = await fetch(`${base}${path}`, {
+            method: "PUT",
+            headers: { authorization: header, "content-type": mediaType, "x-sha-256": sha256 },
+            body: body,
+        });
+        if (response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            if (typeof body.url === "string")
+                return body.url;
+            return `${base}/${sha256}`;
+        }
+        last = `${response.status} ${(await response.text().catch(() => "")).slice(0, 120)}`;
+    }
+    throw new Error(`the community refused the image: ${last}`);
+}
+/**
+ * Remove everything from an image that is not the image.
+ *
+ * @remarks
+ * The community refuses uploads carrying metadata, and it is right to: a photo
+ * taken on a phone carries the phone, the time and often the place, and an
+ * avatar is exactly the kind of file nobody thinks about before sharing. So
+ * this strips rather than asks — the alternative is telling people to run
+ * `exiftool` before they can give their agent a face.
+ *
+ * Both formats are containers of tagged sections, and dropping a section needs
+ * no re-encoding: PNG chunks carry their own CRC, and JPEG segments their own
+ * length. The pixels are untouched.
+ */
+export function stripMetadata(bytes, mediaType) {
+    if (mediaType === "image/png")
+        return stripPng(bytes);
+    if (mediaType === "image/jpeg")
+        return stripJpeg(bytes);
+    return bytes;
+}
+/** The chunks that ARE the image. Everything else is commentary. */
+const PNG_KEEP = new Set(["IHDR", "PLTE", "IDAT", "IEND", "tRNS"]);
+function stripPng(bytes) {
+    const signature = bytes.subarray(0, 8);
+    if (signature[0] !== 0x89 || signature[1] !== 0x50)
+        return bytes;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const kept = [signature];
+    let at = 8;
+    while (at + 8 <= bytes.length) {
+        const length = view.getUint32(at);
+        const name = String.fromCharCode(...bytes.subarray(at + 4, at + 8));
+        const total = 12 + length; // length + type + data + crc
+        if (PNG_KEEP.has(name))
+            kept.push(bytes.subarray(at, at + total));
+        at += total;
+        if (name === "IEND")
+            break;
+    }
+    const size = kept.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(size);
+    let offset = 0;
+    for (const part of kept) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function stripJpeg(bytes) {
+    if (bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return bytes;
+    const kept = [bytes.subarray(0, 2)];
+    let at = 2;
+    while (at + 4 <= bytes.length) {
+        if (bytes[at] !== 0xff)
+            break;
+        const marker = bytes[at + 1];
+        // Start of scan: everything after it is pixel data.
+        if (marker === 0xda) {
+            kept.push(bytes.subarray(at));
+            break;
+        }
+        const length = (bytes[at + 2] << 8) | bytes[at + 3];
+        const isMetadata = (marker >= 0xe0 && marker <= 0xef) || marker === 0xfe; // APPn, COM
+        if (!isMetadata)
+            kept.push(bytes.subarray(at, at + 2 + length));
+        at += 2 + length;
+    }
+    const size = kept.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(size);
+    let offset = 0;
+    for (const part of kept) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/** What kind of image this is, from its name. */
+export function mediaTypeOf(path) {
+    const ext = path.toLowerCase().split(".").pop() ?? "";
+    return ({ png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp" }[ext] ??
+        "application/octet-stream");
+}

package/dist/relay.d.ts

@@ -55,6 +55,9 @@ export declare class BuzzRelay {
     private presenceTimer;
     private pollTimer;
     private closed;
+    /** How long to wait before the next attempt, and what was last refused. */
+    private backoff;
+    private refusal;
     /** Answered already, so a redelivery in two overlapping polls is not answered twice. */
     private readonly seen;
     private cursor;

package/dist/relay.js

@@ -33,12 +33,27 @@ export const KIND_DM_OPEN = 41010;
 export const TYPING_INTERVAL_MS = 3_000;
 export const PRESENCE_INTERVAL_MS = 60_000;
 const now = () => Math.floor(Date.now() / 1000);
+/**
+ * The payload out of a command acknowledgement.
+ *
+ * @remarks
+ * A command's answer arrives as `response:{…}` rather than as bare JSON, and the prefix is easy
+ * to miss because the request itself succeeds: the server accepts the command, does the work,
+ * and reports it — and a parser that chokes on the prefix reports the whole thing as a failure.
+ * The visible symptom is a feature that silently never happens.
+ */
+function stripAckPrefix(message) {
+    return message.startsWith("response:") ? message.slice("response:".length) : message;
+}
 export class BuzzRelay {
     socket = null;
     authenticated = false;
     presenceTimer = null;
     pollTimer = null;
     closed = false;
+    /** How long to wait before the next attempt, and what was last refused. */
+    backoff = 5_000;
+    refusal = null;
     /** Answered already, so a redelivery in two overlapping polls is not answered twice. */
     seen = new Set();
     cursor = now();
@@ -93,8 +108,14 @@ export class BuzzRelay {
     reconnect() {
         if (this.closed)
             return;
-        this.log("disconnected; reconnecting in 5s");
-        setTimeout(() => this.connect(), 5_000);
+        // Backs off rather than hammering. A membership refusal is the common case
+        // here — an agent whose invite has not happened yet — and it is not
+        // something a retry a second from now can fix, though a retry eventually
+        // can, which is why this slows down instead of giving up.
+        const wait = this.backoff;
+        this.backoff = Math.min(this.backoff * 2, 60_000);
+        this.log(`disconnected; reconnecting in ${Math.round(wait / 1000)}s`);
+        setTimeout(() => this.connect(), wait);
     }
     receive(data) {
         let frame;
@@ -122,10 +143,21 @@ export class BuzzRelay {
         }
         if (type === "OK" && !this.authenticated) {
             if (frame[2] !== true) {
-                this.log(`the relay refused this identity: ${String(frame[3] ?? "")}`);
+                // Said once. Repeating it every few seconds buries everything else in
+                // the log while somebody works out who has to send the invite.
+                const reason = String(frame[3] ?? "");
+                if (this.refusal !== reason) {
+                    this.refusal = reason;
+                    this.log(reason.includes("not a relay member")
+                        ? `not a member of this community yet — invite ${this.key.npub}`
+                        : `the relay refused this identity: ${reason}`);
+                }
                 return;
             }
             this.authenticated = true;
+            // A connection that works resets both.
+            this.backoff = 5_000;
+            this.refusal = null;
             this.log(`authenticated as ${this.key.publicKey.slice(0, 12)}…`);
             this.keepPresent();
             this.poll();
@@ -250,10 +282,11 @@ export class BuzzRelay {
             return null;
         }
         try {
-            const ack = JSON.parse(result.message);
+            const ack = JSON.parse(stripAckPrefix(result.message));
             return typeof ack.channel_id === "string" ? ack.channel_id : null;
         }
         catch {
+            this.log(`could not read the reply to opening a direct message: ${result.message.slice(0, 120)}`);
             return null;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.1.0",
+  "version": "0.4.2",
   "description": "Put an eve agent in a Buzz workspace as a member: per-speaker verified identity resolved through the control plane, self-service identity linking, presence, typing and seen signals.",
   "license": "Apache-2.0",
   "type": "module",