@kybernesis/buzz 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+@kybernesis/multiplayer
+Copyright 2026 Kybernesis (kybernesis.ai)

package/README.md

@@ -0,0 +1,73 @@
+# @kybernesis/buzz
+
+Put an eve agent in a [Buzz](https://buzz.xyz) workspace as a **member**, not as a shared
+service account: every message is answered as the person who sent it.
+
+```bash
+npx kybernesis-buzz init          # create the agent's identity, print what to invite
+npx kybernesis-buzz run           # run the bridge
+```
+
+## Why a member
+
+A workspace signs every message with the sender's key, so the bridge knows exactly who spoke.
+That is enough to run each turn as *that person* — their memory, their connections, their
+grants — instead of collapsing a whole room onto one identity and giving everyone in it the
+access of whoever set the agent up.
+
+## How someone becomes known
+
+Nobody is configured by hand. The first time a person talks to the agent, they are sent a
+one-time sign-in link **privately**, they sign in to the control plane as themselves, and from
+then on their turns run as them.
+
+The privacy is the security argument, not politeness: holding that link is what proves control
+of the account it names, so it is delivered to a direct conversation and never posted in a room.
+
+Administrators can also link identities directly in the control plane, which is the path for
+bulk provisioning.
+
+## What the host holds
+
+Only the agent's own key and the agent's own credential — neither of which can act as any
+person. Every turn's authority is minted at the moment it is needed and expires shortly after,
+so revoking a link, suspending a user or pulling a grant takes effect within one token lifetime
+without redeploying anything.
+
+## Presence, typing, and seen
+
+A member that only ever speaks looks offline between sentences, so the bridge also publishes
+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.
+
+## Configuration
+
+| Variable | Meaning |
+| --- | --- |
+| `BUZZ_RELAY` | The workspace relay (`wss://…`) |
+| `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 |
+| `KYBERNESIS_AGENT_CREDENTIAL` | This agent's credential |
+
+`kybernesis-buzz service` prints a systemd unit for it. `kybernesis-buzz id <npub|hex>` shows a
+public key in both forms, which is what the control plane's manual linking wants.
+
+## Library
+
+```ts
+import { buzzBridge } from "@kybernesis/buzz";
+
+const bridge = buzzBridge({
+  relay: process.env.BUZZ_RELAY!,
+  agentUrl: "http://127.0.0.1:8000",
+  keyFile: "/etc/agent/buzz.json",
+  issuer: process.env.KYBERNESIS_ISSUER!,
+  credential: process.env.KYBERNESIS_AGENT_CREDENTIAL!,
+});
+
+console.log(`invite ${bridge.npub}`);
+bridge.start();
+```
+
+Apache-2.0.

package/dist/bridge.d.ts

@@ -0,0 +1,23 @@
+export type BuzzBridgeOptions = {
+    /** The workspace relay, e.g. `wss://example.communities.buzz.xyz`. */
+    relay: 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. */
+    keyFile: string;
+    /** The control plane, e.g. `https://control.example.com`. */
+    issuer: string;
+    /** This agent's credential from the control plane. The only durable secret here. */
+    credential: string;
+    pollMs?: number;
+    onLog?: (message: string) => void;
+};
+export declare function buzzBridge(options: BuzzBridgeOptions): {
+    /** The key the workspace has to invite for any of this to happen. */
+    npub: string;
+    pubkey: string;
+    start(): void;
+    /** Say goodbye rather than letting presence lapse: a stopped agent should not look online. */
+    stop(): void;
+};
+export type BuzzBridge = ReturnType<typeof buzzBridge>;

package/dist/bridge.js

@@ -0,0 +1,158 @@
+import { channelIdentity } from "@kybernesis/enterprise";
+import { Client } from "eve/client";
+import { BuzzRelay } from "./relay.js";
+import { loadKey, npubEncode } from "./keys.js";
+/**
+ * An agent as a member of a workspace, answering as whoever spoke to it.
+ *
+ * @remarks
+ * The design decision this file exists to express: a message is answered as the PERSON who sent
+ * it, not as the agent's owner and not as one shared service account. The sender is a verified
+ * public key — the workspace signed it — so it can be resolved to a real identity, and the turn
+ * can run with that person's memory, connections and grants.
+ *
+ * The bridge itself is deliberately powerless. It holds the agent's key and the agent's own
+ * credential, and neither of those can act as any person; every turn's authority is minted at
+ * the moment it is needed and expires shortly after. A stolen copy of this process buys an
+ * attacker the ability to be the agent, which the workspace already knows about, and nothing else.
+ */
+/** How the workspace names people, in the control plane's records. */
+const PROVIDER = "buzz";
+/** Acknowledge receipt before doing any work: silence and thinking look identical otherwise. */
+const SEEN = "👀";
+export function buzzBridge(options) {
+    const key = loadKey(options.keyFile);
+    const identity = channelIdentity({ issuer: options.issuer, credential: options.credential });
+    const log = options.onLog ?? ((message) => console.log(new Date().toISOString().slice(11, 19), message));
+    /** One conversation per channel, which is how a channel already behaves. */
+    const sessions = new Map();
+    /** Who has already been sent a link, so a room full of strangers is not a room full of spam. */
+    const invited = new Map();
+    const clientFor = (token, bundle) => 
+    // `host`, not `baseUrl`: a wrong key is ignored rather than rejected, and the client then
+    // builds a nonsense URL — an error about a malformed URL rather than about a mistyped option.
+    new Client({
+        host: options.agentUrl,
+        auth: { bearer: token },
+        headers: bundle ? { "x-kybernesis-bundle": bundle } : {},
+    });
+    async function ask(channel, text, token, bundle) {
+        const existing = sessions.get(channel);
+        if (existing) {
+            try {
+                const response = await existing.send(text);
+                return (await response.result()).message ?? "";
+            }
+            catch (error) {
+                // A session the agent no longer holds cannot be resumed. Starting a new one loses the
+                // thread but keeps the conversation alive, which is the better of the two failures.
+                log(`session for ${channel.slice(0, 8)} could not continue (${error.message}); starting a new one`);
+                sessions.delete(channel);
+            }
+        }
+        const client = clientFor(token, bundle);
+        const created = await client.sessions.create({ message: text });
+        sessions.set(channel, created.session);
+        return (await created.response.result()).message ?? "";
+    }
+    /**
+     * Send someone the link that makes them known, privately.
+     *
+     * @remarks
+     * Privately is not a nicety. Holding the link is what proves control of the account it names,
+     * so posting it in a room would let anyone in that room claim to be that person. It goes to a
+     * direct conversation or it does not go at all.
+     */
+    async function invite(relay, sender, link) {
+        const last = invited.get(sender) ?? 0;
+        if (Date.now() - last < 10 * 60_000)
+            return;
+        invited.set(sender, Date.now());
+        const dm = await relay.openDirectMessage(sender);
+        if (!dm) {
+            log(`could not reach ${npubEncode(sender).slice(0, 16)}… privately to send a sign-in link`);
+            return;
+        }
+        relay.reply(dm, `Hi — before I can help, I need to know who you are.\n\nSign in here and I will work as you, with your own memory and access:\n${link}\n\nThe link is for this account only, and it expires shortly.`);
+        log(`sent a sign-in link to ${npubEncode(sender).slice(0, 16)}…`);
+    }
+    /** What to say to someone who is known but not allowed. Said privately, for the same reason. */
+    async function refuse(relay, sender, reason) {
+        const dm = await relay.openDirectMessage(sender);
+        const text = reason === "agent_not_granted"
+            ? "You are signed in, but you do not have access to this agent yet. An administrator can grant it."
+            : "Your account is not active, so I cannot act as you.";
+        if (dm)
+            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 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.
+        const addressed = event.tags.some((t) => t[0] === "p" && t[1] === key.publicKey);
+        if (!channel || !addressed)
+            return;
+        const text = String(event.content ?? "").trim();
+        if (!text)
+            return;
+        let speaker;
+        try {
+            speaker = await identity.resolve(PROVIDER, event.pubkey, npubEncode(event.pubkey));
+        }
+        catch (error) {
+            // The control plane being unreachable is not a refusal. Saying nothing and retrying on the
+            // next message is better than telling someone they are not allowed when they are.
+            log(`could not check who sent this (${error.message}); leaving it unanswered`);
+            return;
+        }
+        if (!speaker.linked) {
+            if (speaker.reason === "not_linked")
+                await invite(relay, event.pubkey, speaker.link);
+            else
+                await refuse(relay, event.pubkey, speaker.reason);
+            return;
+        }
+        log(`asked in ${channel.slice(0, 8)} by ${speaker.user.email}: ${text.slice(0, 60)}`);
+        void relay.react(event.id, SEEN);
+        const stopTyping = relay.typingIn(channel);
+        try {
+            const reply = await ask(channel, text, speaker.token, speaker.bundle);
+            if (!reply) {
+                log("the agent produced no text");
+                return;
+            }
+            relay.reply(channel, reply, event);
+            log(`replied (${reply.length} chars)`);
+        }
+        catch (error) {
+            log(`failed to answer: ${error.message}`);
+        }
+        finally {
+            stopTyping();
+        }
+    }
+    return {
+        /** The key the workspace has to invite for any of this to happen. */
+        npub: key.npub,
+        pubkey: key.publicKey,
+        start() {
+            relay.connect();
+            log("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);
+        },
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+import { buzzBridge } from "./bridge.js";
+import { asHexPubkey, loadOrCreateKey, npubEncode } from "./keys.js";
+/**
+ * Setup and operation for an agent that lives in a workspace.
+ *
+ * @remarks
+ * The commands are shaped around the one step that cannot be automated: a person in the
+ * workspace has to invite the agent's public key, because membership is theirs to grant. So
+ * `init` exists to produce exactly the thing they need to be given, and to say what to do with
+ * it — rather than leaving an operator to work out which of several long hex strings is the one.
+ */
+const KEY_FILE = process.env.BUZZ_KEYFILE ?? join(homedir(), ".kybernesis", "buzz-agent.json");
+function env(name, fallback) {
+    const value = process.env[name] ?? fallback;
+    if (!value) {
+        console.error(`${name} is not set.`);
+        process.exit(1);
+    }
+    return value;
+}
+function init() {
+    const { key, created } = loadOrCreateKey(KEY_FILE);
+    console.log(created ? `\n  A new identity was created at ${KEY_FILE}\n` : `\n  Using the identity at ${KEY_FILE}\n`);
+    console.log(`  Invite this to the workspace:\n\n    ${key.npub}\n`);
+    console.log(`  hex: ${key.publicKey}\n`);
+    console.log("  Then, once it has been invited:\n");
+    console.log("    KYBERNESIS_AGENT_CREDENTIAL=…  kybernesis-buzz run\n");
+    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 run() {
+    const bridge = buzzBridge({
+        relay: env("BUZZ_RELAY"),
+        agentUrl: process.env.BUZZ_AGENT_URL ?? "http://127.0.0.1:8000",
+        keyFile: KEY_FILE,
+        issuer: env("KYBERNESIS_ISSUER", "https://agent.kybernesis.ai"),
+        credential: env("KYBERNESIS_AGENT_CREDENTIAL"),
+        ...(process.env.BUZZ_POLL_MS ? { pollMs: Number(process.env.BUZZ_POLL_MS) } : {}),
+    });
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, () => {
+            bridge.stop();
+            setTimeout(() => process.exit(0), 400);
+        });
+    }
+    bridge.start();
+}
+/** A systemd unit, written out rather than described — the description is what gets mistyped. */
+function service() {
+    const user = process.env.SUDO_USER ?? process.env.USER ?? "root";
+    const workingDirectory = process.cwd();
+    const unit = `[Unit]
+Description=agent workspace bridge
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+WorkingDirectory=${workingDirectory}
+ExecStart=/bin/bash -lc 'set -a && . ./.env.local && set +a && exec npx kybernesis-buzz run'
+Restart=always
+RestartSec=10
+# The bridge publishes "offline" on the way out; this gives it time to, rather than
+# being killed mid-publish and leaving a stopped agent showing as online.
+KillSignal=SIGTERM
+TimeoutStopSec=10
+StartLimitBurst=5
+StartLimitIntervalSec=300
+StandardOutput=append:${workingDirectory}/buzz-bridge.log
+StandardError=append:${workingDirectory}/buzz-bridge.log
+
+[Install]
+WantedBy=multi-user.target
+`;
+    const path = process.argv[3];
+    if (path) {
+        writeFileSync(path, unit);
+        console.log(`\n  Written to ${path}\n`);
+        console.log("  sudo systemctl daemon-reload && sudo systemctl enable --now <name>\n");
+        return;
+    }
+    process.stdout.write(unit);
+}
+const command = process.argv[2];
+if (command === "init")
+    init();
+else if (command === "run")
+    run();
+else if (command === "service")
+    service();
+else if (command === "id") {
+    const hex = asHexPubkey(process.argv[3]);
+    if (!hex) {
+        console.error("usage: kybernesis-buzz id <npub… or 64-char hex>");
+        process.exit(1);
+    }
+    console.log(`hex:  ${hex}`);
+    console.log(`npub: ${npubEncode(hex)}`);
+}
+else {
+    console.log(`
+  kybernesis-buzz — put an agent in a workspace
+
+    init              create or show this agent's identity, and what to invite
+    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_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
+    KYBERNESIS_AGENT_CREDENTIAL    this agent's credential
+`);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+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";

package/dist/index.js

@@ -0,0 +1,3 @@
+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";

package/dist/keys.d.ts

@@ -0,0 +1,30 @@
+import { npubEncode } from "nostr-tools/nip19";
+/**
+ * The agent's own key, which is its whole identity in a workspace.
+ *
+ * @remarks
+ * Kept in a file rather than an environment variable because it is generated once and then
+ * referred to forever: the workspace invites a public key, and losing the private half means
+ * being invited again as a stranger with none of the history.
+ */
+export type AgentKey = {
+    secretKey: Uint8Array;
+    publicKey: string;
+    npub: string;
+};
+export declare function loadKey(file: string): AgentKey;
+/** Load the key, or make one on first run. Never overwrites an existing key. */
+export declare function loadOrCreateKey(file: string): {
+    key: AgentKey;
+    created: boolean;
+};
+/**
+ * A public key in either form people actually have one in.
+ *
+ * @remarks
+ * A workspace shows a member as `npub1…`; the protocol underneath uses hex, and so does the
+ * control plane's record of who that member is. Asking a person to convert between them is
+ * asking them to get it wrong, so both are accepted and normalised to one canonical form here.
+ */
+export declare function asHexPubkey(input: string | undefined | null): string | null;
+export { npubEncode };

package/dist/keys.js

@@ -0,0 +1,47 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { generateSecretKey, getPublicKey } from "nostr-tools/pure";
+import { decode as decodeBech32, npubEncode } from "nostr-tools/nip19";
+export function loadKey(file) {
+    const stored = JSON.parse(readFileSync(file, "utf8"));
+    const secretKey = Uint8Array.from(stored.secretKey);
+    const publicKey = getPublicKey(secretKey);
+    return { secretKey, publicKey, npub: npubEncode(publicKey) };
+}
+/** Load the key, or make one on first run. Never overwrites an existing key. */
+export function loadOrCreateKey(file) {
+    try {
+        return { key: loadKey(file), created: false };
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const secretKey = generateSecretKey();
+    mkdirSync(dirname(file), { recursive: true });
+    // 0600: this file is the agent. Anyone who can read it can be the agent.
+    writeFileSync(file, JSON.stringify({ secretKey: Array.from(secretKey) }), { mode: 0o600 });
+    const publicKey = getPublicKey(secretKey);
+    return { key: { secretKey, publicKey, npub: npubEncode(publicKey) }, created: true };
+}
+/**
+ * A public key in either form people actually have one in.
+ *
+ * @remarks
+ * A workspace shows a member as `npub1…`; the protocol underneath uses hex, and so does the
+ * control plane's record of who that member is. Asking a person to convert between them is
+ * asking them to get it wrong, so both are accepted and normalised to one canonical form here.
+ */
+export function asHexPubkey(input) {
+    const value = String(input ?? "").trim();
+    if (/^[0-9a-f]{64}$/i.test(value))
+        return value.toLowerCase();
+    try {
+        const { type, data } = decodeBech32(value);
+        return type === "npub" ? String(data).toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+export { npubEncode };

package/dist/relay.d.ts

@@ -0,0 +1,108 @@
+import type { AgentKey } from "./keys.js";
+/**
+ * The workspace protocol, as far as a member needs it.
+ *
+ * @remarks
+ * Two transports, and which one carries what is not a style choice. Messages and the presence
+ * signals go over the socket, because they are either addressed to a room or ephemeral. Anything
+ * the server has to answer — a reaction it stores, a conversation it has to create and name —
+ * goes over HTTP with a signed request, because the answer is the point.
+ *
+ * Getting that backwards is expensive: a reaction published on the socket is accepted and then
+ * simply does not appear, which reads as a broken feature rather than a wrong door.
+ */
+/** Message in a channel. */
+export declare const KIND_MESSAGE = 9;
+/** NIP-25 reaction. */
+export declare const KIND_REACTION = 7;
+/** NIP-42 relay authentication. */
+export declare const KIND_AUTH = 22242;
+/** NIP-98 HTTP authentication. */
+export declare const KIND_HTTP_AUTH = 27235;
+/** Presence: "online" | "away" | "offline". */
+export declare const KIND_PRESENCE = 20001;
+/** Typing, scoped to a channel. */
+export declare const KIND_TYPING = 20002;
+/** Open (or find) a direct conversation with a set of people. */
+export declare const KIND_DM_OPEN = 41010;
+/**
+ * A receiving client expires a typing indicator shortly after the event's own timestamp, so
+ * anything slower than that has to keep saying so.
+ */
+export declare const TYPING_INTERVAL_MS = 3000;
+export declare const PRESENCE_INTERVAL_MS = 60000;
+export type NostrEvent = {
+    id: string;
+    pubkey: string;
+    created_at: number;
+    kind: number;
+    tags: string[][];
+    content: string;
+    sig: string;
+};
+export type PresenceStatus = "online" | "away" | "offline";
+export type RelayOptions = {
+    url: string;
+    key: AgentKey;
+    /** How often to ask for new messages. The relay answers with what it has and stops. */
+    pollMs?: number;
+    onMessage: (event: NostrEvent) => void;
+    onLog?: (message: string) => void;
+};
+export declare class BuzzRelay {
+    private socket;
+    private authenticated;
+    private presenceTimer;
+    private pollTimer;
+    private closed;
+    /** Answered already, so a redelivery in two overlapping polls is not answered twice. */
+    private readonly seen;
+    private cursor;
+    private readonly url;
+    private readonly rest;
+    private readonly key;
+    private readonly pollMs;
+    private readonly onMessage;
+    private readonly log;
+    constructor(options: RelayOptions);
+    get pubkey(): string;
+    connect(): void;
+    close(): void;
+    private reconnect;
+    private receive;
+    private send;
+    /**
+     * Ask for what is new, rather than waiting to be told.
+     *
+     * @remarks
+     * This relay answers a subscription with the events it has and then stops; it does not hold the
+     * subscription open and push what arrives next. Assuming otherwise produces the worst kind of
+     * failure — a process that connects, authenticates, logs that it is listening, and silently
+     * ignores every message addressed to it.
+     */
+    private poll;
+    publish(event: {
+        kind: number;
+        tags: string[][];
+        content: string;
+    }): void;
+    setPresence(status: PresenceStatus): void;
+    private keepPresent;
+    /** Say "typing" in a channel until the returned function is called. */
+    typingIn(channel: string): () => void;
+    reply(channel: string, text: string, replyTo?: NostrEvent): void;
+    /** Sign one HTTP request as this agent (NIP-98), binding the signature to the body. */
+    private httpAuth;
+    private submit;
+    /** React to a message. Stored by the server, so it goes over HTTP rather than the socket. */
+    react(eventId: string, emoji: string): Promise<void>;
+    /**
+     * Open a private conversation with someone, and answer with its channel id.
+     *
+     * @remarks
+     * Needed for anything that must reach ONE person rather than a room. Opening a conversation
+     * that already exists returns the existing one, so this is safe to call whenever it is needed
+     * instead of tracking which conversations exist.
+     */
+    openDirectMessage(pubkey: string): Promise<string | null>;
+}

package/dist/relay.js

@@ -0,0 +1,260 @@
+import { createHash } from "node:crypto";
+import { finalizeEvent } from "nostr-tools/pure";
+/**
+ * The workspace protocol, as far as a member needs it.
+ *
+ * @remarks
+ * Two transports, and which one carries what is not a style choice. Messages and the presence
+ * signals go over the socket, because they are either addressed to a room or ephemeral. Anything
+ * the server has to answer — a reaction it stores, a conversation it has to create and name —
+ * goes over HTTP with a signed request, because the answer is the point.
+ *
+ * Getting that backwards is expensive: a reaction published on the socket is accepted and then
+ * simply does not appear, which reads as a broken feature rather than a wrong door.
+ */
+/** Message in a channel. */
+export const KIND_MESSAGE = 9;
+/** NIP-25 reaction. */
+export const KIND_REACTION = 7;
+/** NIP-42 relay authentication. */
+export const KIND_AUTH = 22242;
+/** NIP-98 HTTP authentication. */
+export const KIND_HTTP_AUTH = 27235;
+/** Presence: "online" | "away" | "offline". */
+export const KIND_PRESENCE = 20001;
+/** Typing, scoped to a channel. */
+export const KIND_TYPING = 20002;
+/** Open (or find) a direct conversation with a set of people. */
+export const KIND_DM_OPEN = 41010;
+/**
+ * A receiving client expires a typing indicator shortly after the event's own timestamp, so
+ * anything slower than that has to keep saying so.
+ */
+export const TYPING_INTERVAL_MS = 3_000;
+export const PRESENCE_INTERVAL_MS = 60_000;
+const now = () => Math.floor(Date.now() / 1000);
+export class BuzzRelay {
+    socket = null;
+    authenticated = false;
+    presenceTimer = null;
+    pollTimer = null;
+    closed = false;
+    /** Answered already, so a redelivery in two overlapping polls is not answered twice. */
+    seen = new Set();
+    cursor = now();
+    url;
+    rest;
+    key;
+    pollMs;
+    onMessage;
+    log;
+    constructor(options) {
+        this.url = options.url;
+        this.rest = options.url.replace(/^wss:/, "https:").replace(/^ws:/, "http:").replace(/\/$/, "");
+        this.key = options.key;
+        this.pollMs = options.pollMs ?? 4_000;
+        this.onMessage = options.onMessage;
+        this.log = options.onLog ?? (() => { });
+    }
+    get pubkey() {
+        return this.key.publicKey;
+    }
+    connect() {
+        if (this.closed)
+            return;
+        const socket = new WebSocket(this.url);
+        this.socket = socket;
+        this.authenticated = false;
+        socket.addEventListener("open", () => this.log(`connected to ${this.url}`));
+        socket.addEventListener("message", (raw) => this.receive(String(raw.data)));
+        socket.addEventListener("close", () => this.reconnect());
+        socket.addEventListener("error", () => {
+            try {
+                socket.close();
+            }
+            catch {
+                /* the close handler reconnects */
+            }
+        });
+    }
+    close() {
+        this.closed = true;
+        if (this.presenceTimer)
+            clearInterval(this.presenceTimer);
+        if (this.pollTimer)
+            clearTimeout(this.pollTimer);
+        try {
+            this.socket?.close();
+        }
+        catch {
+            /* closing a closed socket is not an error worth raising */
+        }
+    }
+    reconnect() {
+        if (this.closed)
+            return;
+        this.log("disconnected; reconnecting in 5s");
+        setTimeout(() => this.connect(), 5_000);
+    }
+    receive(data) {
+        let frame;
+        try {
+            frame = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        const type = frame[0];
+        if (type === "AUTH") {
+            this.send([
+                "AUTH",
+                finalizeEvent({
+                    kind: KIND_AUTH,
+                    created_at: now(),
+                    tags: [
+                        ["relay", this.url],
+                        ["challenge", String(frame[1])],
+                    ],
+                    content: "",
+                }, this.key.secretKey),
+            ]);
+            return;
+        }
+        if (type === "OK" && !this.authenticated) {
+            if (frame[2] !== true) {
+                this.log(`the relay refused this identity: ${String(frame[3] ?? "")}`);
+                return;
+            }
+            this.authenticated = true;
+            this.log(`authenticated as ${this.key.publicKey.slice(0, 12)}…`);
+            this.keepPresent();
+            this.poll();
+            return;
+        }
+        if (type === "EOSE") {
+            // One poll's worth delivered. Closing it matters: the relay caps how many subscriptions one
+            // connection may hold, and a bridge that never closes them stops receiving within minutes.
+            this.send(["CLOSE", String(frame[1])]);
+            return;
+        }
+        if (type !== "EVENT")
+            return;
+        const event = frame[2];
+        if (!event || event.pubkey === this.key.publicKey)
+            return;
+        if (this.seen.has(event.id))
+            return;
+        this.seen.add(event.id);
+        if (event.created_at >= this.cursor)
+            this.cursor = event.created_at + 1;
+        this.onMessage(event);
+    }
+    send(frame) {
+        if (this.socket?.readyState !== WebSocket.OPEN)
+            return;
+        this.socket.send(JSON.stringify(frame));
+    }
+    /**
+     * Ask for what is new, rather than waiting to be told.
+     *
+     * @remarks
+     * This relay answers a subscription with the events it has and then stops; it does not hold the
+     * subscription open and push what arrives next. Assuming otherwise produces the worst kind of
+     * failure — a process that connects, authenticates, logs that it is listening, and silently
+     * ignores every message addressed to it.
+     */
+    poll() {
+        if (this.closed)
+            return;
+        this.send(["REQ", `m${Date.now()}`, { kinds: [KIND_MESSAGE], "#p": [this.key.publicKey], since: this.cursor }]);
+        this.pollTimer = setTimeout(() => this.poll(), this.pollMs);
+    }
+    publish(event) {
+        this.send(["EVENT", finalizeEvent({ created_at: now(), ...event }, this.key.secretKey)]);
+    }
+    setPresence(status) {
+        this.publish({ kind: KIND_PRESENCE, tags: [], content: status });
+    }
+    keepPresent() {
+        this.setPresence("online");
+        if (this.presenceTimer)
+            clearInterval(this.presenceTimer);
+        this.presenceTimer = setInterval(() => this.setPresence("online"), PRESENCE_INTERVAL_MS);
+    }
+    /** Say "typing" in a channel until the returned function is called. */
+    typingIn(channel) {
+        const tick = () => this.publish({ kind: KIND_TYPING, tags: [["h", channel]], content: "" });
+        tick();
+        const timer = setInterval(tick, TYPING_INTERVAL_MS);
+        return () => clearInterval(timer);
+    }
+    reply(channel, text, replyTo) {
+        const tags = [["h", channel]];
+        if (replyTo) {
+            tags.push(["e", replyTo.id], ["p", replyTo.pubkey]);
+        }
+        this.publish({ kind: KIND_MESSAGE, tags, content: text });
+    }
+    /** Sign one HTTP request as this agent (NIP-98), binding the signature to the body. */
+    httpAuth(url, body) {
+        const auth = finalizeEvent({
+            kind: KIND_HTTP_AUTH,
+            created_at: now(),
+            tags: [
+                ["u", url],
+                ["method", "POST"],
+                ["payload", createHash("sha256").update(body).digest("hex")],
+            ],
+            content: "",
+        }, this.key.secretKey);
+        return `Nostr ${Buffer.from(JSON.stringify(auth)).toString("base64")}`;
+    }
+    async submit(event) {
+        const url = `${this.rest}/events`;
+        const body = JSON.stringify(event);
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { authorization: this.httpAuth(url, body), "content-type": "application/json" },
+            body,
+        });
+        const text = await response.text();
+        let message = text;
+        try {
+            message = String(JSON.parse(text).message ?? text);
+        }
+        catch {
+            /* a non-JSON body is its own message */
+        }
+        return { ok: response.ok, status: response.status, message };
+    }
+    /** React to a message. Stored by the server, so it goes over HTTP rather than the socket. */
+    async react(eventId, emoji) {
+        const event = finalizeEvent({ kind: KIND_REACTION, created_at: now(), tags: [["e", eventId]], content: emoji }, this.key.secretKey);
+        const result = await this.submit(event);
+        if (!result.ok)
+            this.log(`reaction ${emoji} refused: ${result.status} ${result.message.slice(0, 120)}`);
+    }
+    /**
+     * Open a private conversation with someone, and answer with its channel id.
+     *
+     * @remarks
+     * Needed for anything that must reach ONE person rather than a room. Opening a conversation
+     * that already exists returns the existing one, so this is safe to call whenever it is needed
+     * instead of tracking which conversations exist.
+     */
+    async openDirectMessage(pubkey) {
+        const event = finalizeEvent({ kind: KIND_DM_OPEN, created_at: now(), tags: [["p", pubkey]], content: "" }, this.key.secretKey);
+        const result = await this.submit(event);
+        if (!result.ok) {
+            this.log(`could not open a direct message: ${result.status} ${result.message.slice(0, 120)}`);
+            return null;
+        }
+        try {
+            const ack = JSON.parse(result.message);
+            return typeof ack.channel_id === "string" ? ack.channel_id : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@kybernesis/buzz",
+  "version": "0.1.0",
+  "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",
+  "homepage": "https://kybernesis.ai",
+  "keywords": [
+    "eve",
+    "kybernesis",
+    "buzz",
+    "nostr",
+    "agent",
+    "channel",
+    "multiplayer"
+  ],
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "bin": {
+    "kybernesis-buzz": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node ../../scripts/prepublish.mjs",
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "dependencies": {
+    "@kybernesis/enterprise": "^0.7.0",
+    "nostr-tools": "^2.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.x",
+    "eve": "0.38.3",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "eve": ">=0.38.0 <0.39.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KybernesisAI/platform.git",
+    "directory": "packages/buzz"
+  }
+}