@kybernesis/buzz 0.7.0 → 0.9.0

package/README.md

@@ -60,6 +60,7 @@ sessions are keyed by channel.
 | `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`) |
+| `BUZZ_SESSIONS_FILE` | Channel-to-session continuity store (default beside the key file; an existing legacy `.buzz-sessions.json` is reused) |
 | `KYBERNESIS_ISSUER` | The control plane |
 | `KYBERNESIS_AGENT_CREDENTIAL` | This agent's credential |
 

package/dist/bridge.js

@@ -1,6 +1,10 @@
 import { channelIdentity } from "@kybernesis/enterprise";
-import { fetchMedia, isImage, parseMedia } from "./media.js";
+import { fetchMedia, parseMedia } from "./media.js";
 import { speakerCredentials } from "./credentials.js";
+import { SessionStore } from "./sessions.js";
+import { answerTurn, composeMessage, rejectedTurnReply } from "./turn.js";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { Client } from "eve/client";
 import { BuzzRelay } from "./relay.js";
 import { loadKey, npubEncode } from "./keys.js";
@@ -48,8 +52,21 @@ export function buzzBridge(options) {
      * previous person's answer. The turn itself runs correctly, as the right
      * person, against the right connections; only the text posted back is
      * somebody else's, which is the most convincing way to look broken.
+     *
+     * Kept on DISK, not in memory. The eve session is durable; the knowledge of
+     * which session belongs to a channel was not, so a restart orphaned every
+     * conversation — the next message opened a new session and the agent said it
+     * had no context, while the old session sat intact holding a reply nobody was
+     * left to read.
      */
-    const sessions = new Map();
+    const legacySessionsFile = ".buzz-sessions.json";
+    const sessionsFile = process.env.BUZZ_SESSIONS_FILE ??
+        (existsSync(legacySessionsFile)
+            ? legacySessionsFile
+            : join(dirname(options.keyFile), "buzz-sessions.json"));
+    const sessions = new SessionStore(sessionsFile, { onError: log });
+    if (sessions.size > 0)
+        log(`resumed ${sessions.size} conversation(s) from the last run`);
     /** Who has already been sent a link, so a room full of strangers is not a room full of spam. */
     const invited = new Map();
     /**
@@ -104,107 +121,6 @@ export function buzzBridge(options) {
      * nothing. The bridge knew the answer the whole time: it is the connection
      * the message arrived on.
      */
-    /**
-     * One inbound message, as the parts a turn can carry.
-     *
-     * @remarks
-     * Returns a plain string when there is nothing but text, so the common case
-     * stays exactly as it was — a change in the shape of every ordinary turn is
-     * not worth paying for the rare one.
-     *
-     * A failed fetch does NOT throw. The person is owed an answer either way, and
-     * an agent told "there was an attachment I could not retrieve" can say so;
-     * an agent told nothing answers the caption and looks like it ignored the
-     * picture, which is the bug being fixed.
-     */
-    async function composeMessage(text, attachments) {
-        if (attachments.length === 0)
-            return text;
-        const parts = [];
-        if (text)
-            parts.push({ type: "text", text });
-        for (const ref of attachments) {
-            try {
-                const media = await fetchMedia(key, ref);
-                if (isImage(media.mediaType)) {
-                    parts.push({ type: "image", image: media.bytes, mediaType: media.mediaType });
-                }
-                else {
-                    parts.push({
-                        type: "text",
-                        text: `[The sender attached a ${media.mediaType} file, which cannot be read as an image. Tell them what you received and ask for it in a readable form if you need it.]`,
-                    });
-                }
-            }
-            catch (error) {
-                log(`could not fetch an attachment: ${error.message}`);
-                parts.push({
-                    type: "text",
-                    text: `[The sender attached a file, and it could not be retrieved (${error.message}). Say so rather than answering as if there were no attachment.]`,
-                });
-            }
-        }
-        return parts;
-    }
-    async function ask(channel, message, pubkey, community) {
-        // Built per turn, for the person whose turn it is — and kept current for as
-        // long as that turn runs.
-        const client = clientFor(pubkey);
-        const existing = sessions.get(channel);
-        if (existing) {
-            try {
-                const session = client.sessions.attach(existing.id, { streamIndex: existing.streamIndex });
-                /**
-                 * Move to the true end of the conversation before speaking.
-                 *
-                 * `send()` opens its response stream at the position the handle already
-                 * holds and stops at the FIRST turn boundary it meets. If anything is
-                 * still unread there — the tail of a turn that outlived its reader, a
-                 * turn that was running when the bridge restarted — that boundary
-                 * belongs to the older turn. The read ends on it, this turn's answer is
-                 * never collected, and the stored position stays one turn behind.
-                 *
-                 * Which makes it permanent: every later turn reads the previous turn's
-                 * tail. The channel answers nothing, then answers a question from ten
-                 * minutes ago, and a fresh conversation elsewhere works perfectly —
-                 * because a fresh conversation has nothing left over to trip on.
-                 *
-                 * Draining first costs one bounded read of only what is unread, and it
-                 * repairs a position that has already drifted rather than requiring
-                 * anyone to notice. Non-following, so it ends at the tail instead of
-                 * waiting for the future.
-                 */
-                let unread = 0;
-                for await (const _ of session.stream({ follow: false, startIndex: existing.streamIndex })) {
-                    unread += 1;
-                }
-                if (unread > 0) {
-                    log(`caught up on ${unread} unread event(s) in ${channel.slice(0, 8)} before answering`);
-                }
-                const response = await session.send(message, { clientContext: { buzzCommunity: community, buzzChannel: channel } });
-                const result = await response.result();
-                // Where this turn left the conversation, so the next one starts after it.
-                sessions.set(channel, { id: existing.id, streamIndex: session.state.streamIndex });
-                return 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 created = await client.sessions.create({
-            message,
-            clientContext: { buzzCommunity: community, buzzChannel: channel },
-        });
-        const reply = (await created.response.result()).message ?? "";
-        sessions.set(channel, {
-            id: created.session.state.sessionId,
-            streamIndex: created.session.state.streamIndex,
-        });
-        return reply;
-    }
     /**
      * Send someone the link that makes them known, privately.
      *
@@ -310,11 +226,11 @@ export function buzzBridge(options) {
          * "I got a file I cannot read" is a worse answer than the truth only if
          * you never wanted the truth.
          */
-        const message = await composeMessage(text, attachments);
+        const message = await composeMessage(text, attachments, (ref) => fetchMedia(key, ref), log);
         void relay.react(event.id, SEEN);
         const stopTyping = relay.typingIn(channel);
         try {
-            const reply = await serialize(channel, () => ask(channel, message, event.pubkey, from));
+            const reply = await serialize(channel, () => answerTurn(clientFor(event.pubkey), sessions, channel, message, from, log));
             if (!reply) {
                 /**
                  * Silence is the worst answer available.
@@ -332,6 +248,18 @@ export function buzzBridge(options) {
             log(`replied (${reply.length} chars)`);
         }
         catch (error) {
+            /**
+             * eve refused the turn as malformed. The conversation is intact — the
+             * session mapping was kept — but silence here is indistinguishable from
+             * being ignored, the same failure the empty-reply branch above exists
+             * for. Say what happened; the log gets the full error.
+             */
+            const rejected = rejectedTurnReply(error);
+            if (rejected) {
+                log(`turn rejected for ${channel.slice(0, 8)}: ${error.message}`);
+                relay.reply(channel, rejected, event);
+                return;
+            }
             log(`failed to answer: ${error.message}`);
         }
         finally {

package/dist/cli.js

@@ -294,6 +294,7 @@ else {
                                    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)
+    BUZZ_SESSIONS_FILE             channel-to-session continuity store
     KYBERNESIS_ISSUER              the control plane
     KYBERNESIS_AGENT_CREDENTIAL    this agent's credential
 `);

package/dist/extension/_manifest.json

@@ -1,10 +1,10 @@
 {
   "kind": "eve-extension",
-  "formatVersion": 1,
-  "builtWithEve": "0.38.3",
+  "formatVersion": 2,
+  "builtWithEve": "0.49.0",
   "requires": {
     "extension": 1,
-    "tool": 13,
+    "tool": 24,
     "instructions": 2
   }
 }

package/dist/relay.d.ts

@@ -31,6 +31,8 @@ export declare const KIND_DM_OPEN = 41010;
  */
 export declare const TYPING_INTERVAL_MS = 3000;
 export declare const PRESENCE_INTERVAL_MS = 60000;
+/** Enough overlap for same-second redelivery without retaining every event forever. */
+export declare const MAX_SEEN_EVENT_IDS = 10000;
 export type NostrEvent = {
     id: string;
     pubkey: string;
@@ -54,6 +56,7 @@ export declare class BuzzRelay {
     private authenticated;
     private presenceTimer;
     private pollTimer;
+    private reconnectTimer;
     private closed;
     /** How long to wait before the next attempt, and what was last refused. */
     private backoff;

package/dist/relay.js

@@ -32,6 +32,8 @@ export const KIND_DM_OPEN = 41010;
  */
 export const TYPING_INTERVAL_MS = 3_000;
 export const PRESENCE_INTERVAL_MS = 60_000;
+/** Enough overlap for same-second redelivery without retaining every event forever. */
+export const MAX_SEEN_EVENT_IDS = 10_000;
 const now = () => Math.floor(Date.now() / 1000);
 /**
  * The payload out of a command acknowledgement.
@@ -50,6 +52,7 @@ export class BuzzRelay {
     authenticated = false;
     presenceTimer = null;
     pollTimer = null;
+    reconnectTimer = null;
     closed = false;
     /** How long to wait before the next attempt, and what was last refused. */
     backoff = 5_000;
@@ -98,6 +101,11 @@ export class BuzzRelay {
             clearInterval(this.presenceTimer);
         if (this.pollTimer)
             clearTimeout(this.pollTimer);
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.presenceTimer = null;
+        this.pollTimer = null;
+        this.reconnectTimer = null;
         try {
             this.socket?.close();
         }
@@ -108,6 +116,14 @@ export class BuzzRelay {
     reconnect() {
         if (this.closed)
             return;
+        if (this.presenceTimer)
+            clearInterval(this.presenceTimer);
+        if (this.pollTimer)
+            clearTimeout(this.pollTimer);
+        this.presenceTimer = null;
+        this.pollTimer = null;
+        if (this.reconnectTimer)
+            return;
         // 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
@@ -115,7 +131,10 @@ export class BuzzRelay {
         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);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, wait);
     }
     receive(data) {
         let frame;
@@ -177,8 +196,16 @@ export class BuzzRelay {
         if (this.seen.has(event.id))
             return;
         this.seen.add(event.id);
-        if (event.created_at >= this.cursor)
-            this.cursor = event.created_at + 1;
+        if (this.seen.size > MAX_SEEN_EVENT_IDS) {
+            const oldest = this.seen.values().next().value;
+            if (oldest)
+                this.seen.delete(oldest);
+        }
+        // Nostr timestamps have one-second precision and `since` is inclusive. Keep
+        // the latest second in the next poll; the seen set removes redelivery while
+        // allowing another event created during that same second to arrive.
+        if (event.created_at > this.cursor)
+            this.cursor = event.created_at;
         this.onMessage(event);
     }
     send(frame) {

package/dist/sessions.d.ts

@@ -0,0 +1,39 @@
+/** One conversation: which eve session it is, and how far the bridge has read. */
+export interface StoredSession {
+    id: string;
+    streamIndex: number;
+    /** When it was last used, so a store that runs for years does not grow forever. */
+    updated: number;
+}
+/**
+ * Which eve session belongs to which channel, across restarts.
+ *
+ * @remarks
+ * The eve session itself is durable — it lives on the agent's disk and survives
+ * anything. What did NOT survive was the bridge's knowledge of WHICH session
+ * belonged to a channel: that was a Map in memory, so a restart silently
+ * orphaned every conversation. The next message opened a new session and the
+ * agent answered "I have no context", while the old session sat on disk intact,
+ * holding a turn whose reply nobody was left to read.
+ *
+ * Reported from a live deployment after a restart mid-conversation, and the
+ * diagnosis there was exactly right: durable on one side, ephemeral on the
+ * other, and the join between them was the part that could not survive.
+ *
+ * Keyed by community AND channel: channel ids are issued per relay, so an agent
+ * in two workspaces cannot assume they never collide.
+ */
+export declare class SessionStore {
+    #private;
+    constructor(file: string, options?: {
+        onError?: (message: string) => void;
+    });
+    static key(community: string, channel: string): string;
+    get(community: string, channel: string): StoredSession | undefined;
+    set(community: string, channel: string, session: {
+        id: string;
+        streamIndex: number;
+    }): void;
+    delete(community: string, channel: string): void;
+    get size(): number;
+}

package/dist/sessions.js

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/** How long an untouched conversation is kept before it is forgotten. */
+const KEEP_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Which eve session belongs to which channel, across restarts.
+ *
+ * @remarks
+ * The eve session itself is durable — it lives on the agent's disk and survives
+ * anything. What did NOT survive was the bridge's knowledge of WHICH session
+ * belonged to a channel: that was a Map in memory, so a restart silently
+ * orphaned every conversation. The next message opened a new session and the
+ * agent answered "I have no context", while the old session sat on disk intact,
+ * holding a turn whose reply nobody was left to read.
+ *
+ * Reported from a live deployment after a restart mid-conversation, and the
+ * diagnosis there was exactly right: durable on one side, ephemeral on the
+ * other, and the join between them was the part that could not survive.
+ *
+ * Keyed by community AND channel: channel ids are issued per relay, so an agent
+ * in two workspaces cannot assume they never collide.
+ */
+export class SessionStore {
+    #file;
+    #entries = new Map();
+    #onError;
+    constructor(file, options = {}) {
+        this.#file = file;
+        this.#onError = options.onError ?? (() => { });
+        this.#load();
+    }
+    static key(community, channel) {
+        return `${community}|${channel}`;
+    }
+    get(community, channel) {
+        return this.#entries.get(SessionStore.key(community, channel));
+    }
+    set(community, channel, session) {
+        this.#entries.set(SessionStore.key(community, channel), { ...session, updated: Date.now() });
+        this.#save();
+    }
+    delete(community, channel) {
+        this.#entries.delete(SessionStore.key(community, channel));
+        this.#save();
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    #load() {
+        if (!existsSync(this.#file))
+            return;
+        try {
+            const raw = JSON.parse(readFileSync(this.#file, "utf8"));
+            const cutoff = Date.now() - KEEP_MS;
+            for (const [key, value] of Object.entries(raw)) {
+                if (typeof value?.id === "string" && (value.updated ?? 0) > cutoff) {
+                    this.#entries.set(key, value);
+                }
+            }
+        }
+        catch (error) {
+            // A corrupt store is not worth refusing to start over. Losing the mapping
+            // costs conversation history; refusing to start costs the whole agent.
+            this.#onError(`could not load Buzz session store ${this.#file}: ${error.message}`);
+        }
+    }
+    #save() {
+        try {
+            mkdirSync(dirname(this.#file), { recursive: true });
+            // Written beside the target and renamed, because the failure being
+            // guarded against is a restart — and a restart during a plain write
+            // leaves a truncated file that reads as "no sessions at all", which is
+            // the exact bug this class exists to prevent.
+            const tmp = `${this.#file}.tmp`;
+            writeFileSync(tmp, JSON.stringify(Object.fromEntries(this.#entries)), { mode: 0o600 });
+            renameSync(tmp, this.#file);
+        }
+        catch (error) {
+            // Best effort: an agent that cannot write its store still answers, it
+            // just forgets across restarts — which is where this started.
+            this.#onError(`could not write Buzz session store ${this.#file}: ${error.message}`);
+        }
+    }
+}

package/dist/turn.d.ts

@@ -0,0 +1,20 @@
+import { type Client, type SendTurnInput } from "eve/client";
+import { type FetchedMedia, type MediaRef } from "./media.js";
+import { SessionStore } from "./sessions.js";
+/** A message shape accepted by the certified eve client's send contract. */
+export type TurnMessage = SendTurnInput["message"];
+/** Convert one inbound Buzz message into an eve-compatible turn. */
+export declare function composeMessage(text: string, attachments: MediaRef[], fetchAttachment: (ref: MediaRef) => Promise<FetchedMedia>, log?: (message: string) => void): Promise<TurnMessage>;
+/** Continue a channel's existing conversation, replacing it only when it is stale. */
+export declare function answerTurn(client: Client, sessions: SessionStore, channel: string, message: TurnMessage, community: string, log?: (message: string) => void): Promise<string>;
+/**
+ * What the room is told when eve refuses the turn itself.
+ *
+ * A 400 means the request was malformed — a part eve does not accept, a body
+ * it could not parse — not that the agent failed to think of an answer. The
+ * session survives it (`answerTurn` keeps the mapping), but the person who
+ * sent the message is still waiting, and a log line nobody is reading is not
+ * an answer. Returns `null` for anything that is not a request rejection, so
+ * the caller's ordinary failure path stays as it was.
+ */
+export declare function rejectedTurnReply(error: unknown): string | null;

package/dist/turn.js

@@ -0,0 +1,117 @@
+import { ClientError, createDataUrlFilePart, } from "eve/client";
+import { isImage } from "./media.js";
+/** Convert one inbound Buzz message into an eve-compatible turn. */
+export async function composeMessage(text, attachments, fetchAttachment, log = () => { }) {
+    if (attachments.length === 0)
+        return text;
+    const parts = [];
+    if (text)
+        parts.push({ type: "text", text });
+    for (const ref of attachments) {
+        try {
+            const media = await fetchAttachment(ref);
+            if (isImage(media.mediaType)) {
+                parts.push(createDataUrlFilePart({
+                    bytes: media.bytes,
+                    mediaType: media.mediaType,
+                }));
+            }
+            else {
+                parts.push({
+                    type: "text",
+                    text: `[The sender attached a ${media.mediaType} file, which cannot be read as an image. Tell them what you received and ask for it in a readable form if you need it.]`,
+                });
+            }
+        }
+        catch (error) {
+            log(`could not fetch an attachment: ${error.message}`);
+            parts.push({
+                type: "text",
+                text: `[The sender attached a file, and it could not be retrieved (${error.message}). Say so rather than answering as if there were no attachment.]`,
+            });
+        }
+    }
+    return parts;
+}
+/** Continue a channel's existing conversation, replacing it only when it is stale. */
+export async function answerTurn(client, sessions, channel, message, community, log = () => { }) {
+    const existing = sessions.get(community, channel);
+    if (existing) {
+        try {
+            const session = client.sessions.attach(existing.id, { streamIndex: existing.streamIndex });
+            /**
+             * Move to the true end of the conversation before speaking.
+             *
+             * `send()` opens its response stream at the position the handle already
+             * holds and stops at the FIRST turn boundary it meets. If anything is
+             * still unread there — the tail of a turn that outlived its reader, a
+             * turn that was running when the bridge restarted — that boundary
+             * belongs to the older turn. The read ends on it, this turn's answer is
+             * never collected, and the stored position stays one turn behind.
+             *
+             * Which makes it permanent: every later turn reads the previous turn's
+             * tail. The channel answers nothing, then answers a question from ten
+             * minutes ago, and a fresh conversation elsewhere works perfectly —
+             * because a fresh conversation has nothing left over to trip on.
+             *
+             * Draining first costs one bounded read of only what is unread, and it
+             * repairs a position that has already drifted rather than requiring
+             * anyone to notice. Non-following, so it ends at the tail instead of
+             * waiting for the future.
+             */
+            let unread = 0;
+            for await (const _ of session.stream({ follow: false, startIndex: existing.streamIndex })) {
+                unread += 1;
+            }
+            if (unread > 0) {
+                log(`caught up on ${unread} unread event(s) in ${channel.slice(0, 8)} before answering`);
+            }
+            const response = await session.send(message, {
+                clientContext: { buzzCommunity: community, buzzChannel: channel },
+            });
+            const result = await response.result();
+            sessions.set(community, channel, {
+                id: existing.id,
+                streamIndex: session.state.streamIndex,
+            });
+            return result.message ?? "";
+        }
+        catch (error) {
+            // A malformed turn does not make its durable session stale. Rethrow so
+            // the bridge can tell the room (see `rejectedTurnReply`), and keep the
+            // mapping so the next valid message continues the same conversation.
+            if (error instanceof ClientError && error.status === 400)
+                throw error;
+            log(`session for ${channel.slice(0, 8)} could not continue (${error.message}); starting a new one`);
+            sessions.delete(community, channel);
+        }
+    }
+    const created = await client.sessions.create({
+        message,
+        clientContext: { buzzCommunity: community, buzzChannel: channel },
+    });
+    const reply = (await created.response.result()).message ?? "";
+    sessions.set(community, channel, {
+        id: created.session.state.sessionId,
+        streamIndex: created.session.state.streamIndex,
+    });
+    return reply;
+}
+/**
+ * What the room is told when eve refuses the turn itself.
+ *
+ * A 400 means the request was malformed — a part eve does not accept, a body
+ * it could not parse — not that the agent failed to think of an answer. The
+ * session survives it (`answerTurn` keeps the mapping), but the person who
+ * sent the message is still waiting, and a log line nobody is reading is not
+ * an answer. Returns `null` for anything that is not a request rejection, so
+ * the caller's ordinary failure path stays as it was.
+ */
+export function rejectedTurnReply(error) {
+    if (!(error instanceof ClientError) || error.status !== 400)
+        return null;
+    const detail = String(error.message ?? "").split("\n")[0].trim().slice(0, 160);
+    return detail
+        ? `I couldn't read that message (${detail}). Try sending it again, or as plain text.`
+        : "I couldn't read that message. Try sending it again, or as plain text.";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.7.0",
+  "version": "0.9.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",
@@ -44,17 +44,17 @@
     "test": "node --test \"test/**/*.test.mjs\""
   },
   "dependencies": {
-    "@kybernesis/enterprise": "^0.7.0",
+    "@kybernesis/enterprise": "^0.8.0",
     "nostr-tools": "^2.10.0",
     "zod": "^4"
   },
   "devDependencies": {
     "@types/node": "24.x",
-    "eve": "0.38.3",
+    "eve": "0.49.0",
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "eve": ">=0.38.0 <0.39.0"
+    "eve": ">=0.49.0 <0.50.0"
   },
   "engines": {
     "node": ">=20"