@kybernesis/buzz 0.8.0 → 0.9.1

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,7 +1,11 @@
 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 { followPendingConversation, formatInputRequests, invalidInputReply, needsPendingFollower, resolveInputReply, respondToPendingConversation, } from "./hitl.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";
@@ -56,7 +60,12 @@ export function buzzBridge(options) {
      * had no context, while the old session sat intact holding a reply nobody was
      * left to read.
      */
-    const sessions = new SessionStore(process.env.BUZZ_SESSIONS_FILE ?? ".buzz-sessions.json");
+    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. */
@@ -97,10 +106,11 @@ export function buzzBridge(options) {
      * turns are ordered whether or not the people in it take turns.
      */
     const inFlight = new Map();
-    function serialize(channel, work) {
-        const queued = (inFlight.get(channel) ?? Promise.resolve()).then(work, work);
+    function serialize(community, channel, work) {
+        const key = SessionStore.key(community, channel);
+        const queued = (inFlight.get(key) ?? Promise.resolve()).then(work, work);
         // Kept only while it matters: the chain holds the LAST promise, not a history.
-        inFlight.set(channel, queued.catch(() => { }));
+        inFlight.set(key, queued.catch(() => { }));
         return queued;
     }
     /**
@@ -113,107 +123,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(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();
-                // Where this turn left the conversation, so the next one starts after it.
-                sessions.set(community, 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(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;
-    }
     /**
      * Send someone the link that makes them known, privately.
      *
@@ -264,6 +173,97 @@ export function buzzBridge(options) {
             },
         }));
     }
+    /** One abortable durable-stream follower owns each parked conversation. */
+    const followers = new Map();
+    const followerRestartTimers = new Map();
+    let stopped = false;
+    function clearFollowerRestart(conversation) {
+        const timer = followerRestartTimers.get(conversation);
+        if (timer)
+            clearTimeout(timer);
+        followerRestartTimers.delete(conversation);
+    }
+    function stopFollower(community, channel) {
+        const conversation = SessionStore.key(community, channel);
+        clearFollowerRestart(conversation);
+        followers.get(conversation)?.abort();
+        followers.delete(conversation);
+    }
+    function startFollower(community, channel) {
+        if (stopped)
+            return;
+        const conversation = SessionStore.key(community, channel);
+        clearFollowerRestart(conversation);
+        if (followers.has(conversation))
+            return;
+        const stored = sessions.get(community, channel);
+        const relay = relays.get(community);
+        if (!stored || !needsPendingFollower(stored) || !stored.speakerPublicKey || !relay)
+            return;
+        const controller = new AbortController();
+        followers.set(conversation, controller);
+        const session = clientFor(stored.speakerPublicKey).sessions.attach(stored.id, {
+            streamIndex: stored.streamIndex,
+        });
+        void followPendingConversation(session, stored, {
+            // A stopped/replaced follower may already have queued a callback. Check
+            // its generation inside the same conversation queue used by inbound
+            // messages so stale state cannot overwrite a newer responder or cursor.
+            onState: (state) => serialize(community, channel, async () => {
+                if (followers.get(conversation) !== controller)
+                    return;
+                const current = sessions.get(community, channel);
+                if (state.pendingInputRequests?.length) {
+                    sessions.set(community, channel, { ...state, promptEventIds: current?.promptEventIds });
+                    return;
+                }
+                if (current?.promptEventIds?.length)
+                    relay.unwatchReplies(current.promptEventIds);
+                sessions.set(community, channel, state);
+            }),
+            onInputRequested: (requests) => serialize(community, channel, async () => {
+                if (followers.get(conversation) !== controller)
+                    return;
+                const promptId = relay.reply(channel, formatInputRequests(requests));
+                if (!promptId)
+                    throw new Error("Buzz relay is not connected");
+                relay.watchReplies([promptId]);
+                const current = sessions.get(community, channel);
+                if (current) {
+                    sessions.set(community, channel, {
+                        ...current,
+                        promptEventIds: [...(current.promptEventIds ?? []), promptId],
+                    });
+                }
+                log(`posted another input request in ${channel.slice(0, 8)}`);
+            }),
+            onMessage: (message) => serialize(community, channel, async () => {
+                if (followers.get(conversation) !== controller)
+                    return;
+                if (!relay.reply(channel, message))
+                    throw new Error("Buzz relay is not connected");
+                log(`posted resumed reply in ${channel.slice(0, 8)} (${message.length} chars)`);
+            }),
+            onLog: log,
+        }, controller.signal).catch((error) => {
+            if (!controller.signal.aborted) {
+                // Keep the persisted request, cursor and public identity. A later reply
+                // or process restart can refresh credentials and reattach.
+                log(`pending follower for ${channel.slice(0, 8)} disconnected (${error.message})`);
+            }
+        }).finally(() => {
+            if (followers.get(conversation) === controller)
+                followers.delete(conversation);
+            const recoverable = sessions.get(community, channel);
+            if (!controller.signal.aborted && recoverable && needsPendingFollower(recoverable)) {
+                const timer = setTimeout(() => {
+                    followerRestartTimers.delete(conversation);
+                    startFollower(community, channel);
+                }, 1_000);
+                followerRestartTimers.set(conversation, timer);
+            }
+        });
+    }
     async function handle(event, from) {
         const relay = relays.get(from);
         if (!relay)
@@ -272,24 +272,15 @@ export function buzzBridge(options) {
         // 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)
+        // A reply to a prompt this agent posted is an answer even when it names nobody: people answer
+        // a question by replying to it, not by mentioning the asker. Only while that prompt is open.
+        const repliedTo = event.tags.find((t) => t[0] === "e")?.[1];
+        const open = channel ? sessions.get(from, channel) : undefined;
+        const answersPrompt = Boolean(repliedTo && open?.pendingInputRequests?.length && open.promptEventIds?.includes(repliedTo));
+        if (!channel || !(addressed || answersPrompt))
             return;
         const text = String(event.content ?? "").trim();
         const attachments = parseMedia(event);
-        /**
-         * Drop only a message with NOTHING in it — and say so when we do.
-         *
-         * This guard used to test the text alone, and sat above the log line, so an
-         * image sent without a caption was discarded before anything was written
-         * down. From the outside the agent had simply ignored someone; from the
-         * inside there was no record that a message had ever arrived. The reply
-         * path was hardened against exactly this failure — an empty answer now
-         * says so out loud — and the receiving path was left as it was.
-         */
-        if (!text && attachments.length === 0) {
-            log(`nothing to answer in ${channel.slice(0, 8)} from ${event.pubkey.slice(0, 8)} — no text, no attachments`);
-            return;
-        }
         let speaker;
         try {
             speaker = await identity.resolve(PROVIDER, event.pubkey, npubEncode(event.pubkey));
@@ -309,38 +300,89 @@ export function buzzBridge(options) {
         }
         log(`asked in ${channel.slice(0, 8)} by ${speaker.user.email}: ${text.slice(0, 60)}` +
             (attachments.length ? ` [+${attachments.length} attachment(s)]` : ""));
-        /**
-         * Attachments become parts of the turn, or become words about themselves.
-         *
-         * An image the model can see goes in as bytes. Anything else — a zip, a
-         * PDF the model cannot read, a fetch that failed — goes in as a sentence
-         * saying so, because the alternative is an agent that answers the caption
-         * while the person waits for a reply about the file they sent. Being told
-         * "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);
         void relay.react(event.id, SEEN);
         const stopTyping = relay.typingIn(channel);
         try {
-            const reply = await serialize(channel, () => ask(channel, message, event.pubkey, from));
-            if (!reply) {
-                /**
-                 * Silence is the worst answer available.
-                 *
-                 * An empty result used to end here, with a line in a log nobody was
-                 * reading. In a room that is indistinguishable from the agent ignoring
-                 * you — so people ask again, which is how one unanswered question
-                 * became five, none of which looked like a fault to anyone watching.
-                 */
-                log(`no text for ${channel.slice(0, 8)} — telling them rather than going quiet`);
-                relay.reply(channel, "I didn't get an answer back for that one — ask me again and I'll retry.", event);
-                return;
-            }
-            relay.reply(channel, reply, event);
-            log(`replied (${reply.length} chars)`);
+            await serialize(from, channel, async () => {
+                const pending = sessions.get(from, channel);
+                if (pending?.pendingInputRequests?.length) {
+                    // "@Ava approve" is an approve. The mention is how the message reached us, not the answer.
+                    const answer = addressed ? text.replace(/^@\S+\s*/, "") : text;
+                    const responses = resolveInputReply(answer, pending.pendingInputRequests);
+                    if (!responses) {
+                        relay.reply(channel, invalidInputReply(pending.pendingInputRequests), event);
+                        return;
+                    }
+                    // Reattach both POST and follower with the current responder's freshly
+                    // resolved credentials. The follower remains the sole output reader.
+                    stopFollower(from, channel);
+                    sessions.set(from, channel, {
+                        ...pending,
+                        speakerPublicKey: event.pubkey,
+                    });
+                    startFollower(from, channel);
+                    const session = clientFor(event.pubkey).sessions.attach(pending.id, {
+                        streamIndex: pending.streamIndex,
+                    });
+                    await respondToPendingConversation(session, responses, from, channel);
+                    log(`submitted ${responses.length} input response(s) in ${channel.slice(0, 8)}`);
+                    return;
+                }
+                if (pending?.resumeInFlight) {
+                    startFollower(from, channel);
+                    relay.reply(channel, "I'm still finishing the resumed request. I'll post the answer here when it is ready.", event);
+                    return;
+                }
+                /** Drop only a message with NOTHING in it — pending HITL replies are handled above. */
+                if (!text && attachments.length === 0) {
+                    log(`nothing to answer in ${channel.slice(0, 8)} from ${event.pubkey.slice(0, 8)} — no text, no attachments`);
+                    return;
+                }
+                /** Images become file parts; unreadable files become explicit model context. */
+                const message = await composeMessage(text, attachments, (ref) => fetchMedia(key, ref), log);
+                const result = await answerTurn(clientFor(event.pubkey), sessions, channel, message, from, log);
+                if (result.status === "waiting" && result.inputRequests.length > 0) {
+                    sessions.set(from, channel, {
+                        id: result.sessionId,
+                        streamIndex: result.streamIndex,
+                        pendingInputRequests: result.inputRequests,
+                        speakerPublicKey: event.pubkey,
+                    });
+                    const promptId = relay.reply(channel, formatInputRequests(result.inputRequests), event);
+                    if (promptId) {
+                        relay.watchReplies([promptId]);
+                        const current = sessions.get(from, channel);
+                        if (current)
+                            sessions.set(from, channel, { ...current, promptEventIds: [promptId] });
+                    }
+                    log(`posted ${result.inputRequests.length} input request(s) in ${channel.slice(0, 8)}`);
+                    startFollower(from, channel);
+                    return;
+                }
+                if (!result.message) {
+                    log(`no text for ${channel.slice(0, 8)} — telling them rather than going quiet`);
+                    relay.reply(channel, "I didn't get an answer back for that one — ask me again and I'll retry.", event);
+                    return;
+                }
+                relay.reply(channel, result.message, event);
+                log(`replied (${result.message.length} chars)`);
+            });
         }
         catch (error) {
+            /** A rejected HITL response stays pending; the room gets a concrete retry path. */
+            const stillPending = sessions.get(from, channel)?.pendingInputRequests;
+            if (stillPending?.length) {
+                log(`could not submit pending input for ${channel.slice(0, 8)}: ${error.message}`);
+                relay.reply(channel, invalidInputReply(stillPending), event);
+                startFollower(from, channel);
+                return;
+            }
+            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 {
@@ -354,14 +396,30 @@ export function buzzBridge(options) {
         /** The communities this agent is a member of. */
         relays: urls,
         start() {
+            stopped = false;
             for (const relay of relays.values())
                 relay.connect();
+            for (const { community, channel, session } of sessions.entries()) {
+                if (session.pendingInputRequests?.length && session.promptEventIds?.length) {
+                    relays.get(community)?.watchReplies(session.promptEventIds);
+                }
+                if (needsPendingFollower(session) && session.speakerPublicKey) {
+                    startFollower(community, channel);
+                }
+            }
             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() {
+            stopped = true;
+            for (const controller of followers.values())
+                controller.abort();
+            followers.clear();
+            for (const timer of followerRestartTimers.values())
+                clearTimeout(timer);
+            followerRestartTimers.clear();
             for (const relay of relays.values())
                 relay.setPresence("offline");
             setTimeout(() => {

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/hitl.d.ts

@@ -0,0 +1,34 @@
+import { type ClientSession, type InputRequest, type InputResponse } from "eve/client";
+import type { StoredSession } from "./sessions.js";
+/** Render pending Eve input in a text-only Buzz channel. */
+export declare function formatInputRequests(requests: readonly InputRequest[]): string;
+/** Resolve a Buzz text reply using Eve's certified matching semantics. */
+export declare function resolveInputReply(text: string, requests: readonly InputRequest[]): readonly InputResponse[] | null;
+/** Actionable response for text that cannot satisfy every pending request. */
+export declare function invalidInputReply(requests: readonly InputRequest[]): string;
+/** Submit a matched reply without consuming its response stream. */
+export declare function respondToPendingConversation(session: Pick<ClientSession, "respond">, responses: readonly InputResponse[], community: string, channel: string): Promise<void>;
+/** A session needs its follower while asking or while resumed output is unpublished. */
+export declare function needsPendingFollower(session: Pick<StoredSession, "pendingInputRequests" | "resumeInFlight">): boolean;
+export interface PendingFollowerCallbacks {
+    /** Persist the latest cursor and supervision state before publishing outward. */
+    onState(state: Omit<StoredSession, "updated">): void | Promise<void>;
+    onInputRequested(requests: readonly InputRequest[]): void | Promise<void>;
+    onMessage(message: string): void | Promise<void>;
+    onLog?: (message: string) => void;
+}
+type MutableStoredSession = Omit<StoredSession, "updated">;
+/**
+ * Follow one parked conversation until it resumes, asks another HITL question,
+ * or reaches a terminal/non-HITL boundary. This follower is the sole publisher
+ * of resumed output; callers of `respond()` must not consume or publish its
+ * response stream as well.
+ *
+ * The durable `resumeInFlight` marker deliberately survives `input.resolved`.
+ * It is cleared only after the relay publication callback succeeds, so a crash
+ * or disconnect between Eve accepting input and Buzz publishing output can
+ * reattach from the persisted cursor instead of letting a normal stale drain
+ * swallow the resumed answer.
+ */
+export declare function followPendingConversation(session: Pick<ClientSession, "state" | "stream">, initial: MutableStoredSession, callbacks: PendingFollowerCallbacks, signal: AbortSignal): Promise<void>;
+export {};

package/dist/hitl.js

@@ -0,0 +1,148 @@
+import { resolveTextToResponses, } from "eve/client";
+/** Render pending Eve input in a text-only Buzz channel. */
+export function formatInputRequests(requests) {
+    return requests.map((request, requestIndex) => {
+        const lines = [
+            requests.length > 1 ? `Question ${requestIndex + 1}: ${request.prompt}` : request.prompt,
+        ];
+        if (request.options?.length) {
+            lines.push("", ...request.options.map((option, optionIndex) => {
+                const description = option.description ? ` — ${option.description}` : "";
+                return `${optionIndex + 1}. ${option.label} [${option.id}]${description}`;
+            }));
+        }
+        if (request.allowFreeform === true || !request.options?.length) {
+            lines.push("", "Reply to this message with an option number, option ID, exact label, or your own answer.");
+        }
+        else {
+            lines.push("", "Reply to this message with an option number, option ID, or exact label.");
+        }
+        return lines.join("\n");
+    }).join("\n\n");
+}
+/** Resolve a Buzz text reply using Eve's certified matching semantics. */
+export function resolveInputReply(text, requests) {
+    if (!text.trim())
+        return null;
+    const responses = resolveTextToResponses(text, requests);
+    return responses.length === requests.length ? responses : null;
+}
+/** Actionable response for text that cannot satisfy every pending request. */
+export function invalidInputReply(requests) {
+    return `I still need a valid answer before I can continue.\n\n${formatInputRequests(requests)}`;
+}
+/** Submit a matched reply without consuming its response stream. */
+export async function respondToPendingConversation(session, responses, community, channel) {
+    await session.respond(responses, {
+        clientContext: { buzzCommunity: community, buzzChannel: channel },
+        streamReconnectPolicy: { reconnect: false },
+    });
+}
+/** A session needs its follower while asking or while resumed output is unpublished. */
+export function needsPendingFollower(session) {
+    return Boolean(session.pendingInputRequests?.length || session.resumeInFlight);
+}
+function withPending(state, requests) {
+    const { resumeInFlight: _, ...rest } = state;
+    return { ...rest, pendingInputRequests: requests };
+}
+function withResumeInFlight(state) {
+    const { pendingInputRequests: _, ...rest } = state;
+    return { ...rest, resumeInFlight: true };
+}
+function withoutSupervision(state) {
+    const { pendingInputRequests: _, resumeInFlight: __, ...rest } = state;
+    return rest;
+}
+/**
+ * Follow one parked conversation until it resumes, asks another HITL question,
+ * or reaches a terminal/non-HITL boundary. This follower is the sole publisher
+ * of resumed output; callers of `respond()` must not consume or publish its
+ * response stream as well.
+ *
+ * The durable `resumeInFlight` marker deliberately survives `input.resolved`.
+ * It is cleared only after the relay publication callback succeeds, so a crash
+ * or disconnect between Eve accepting input and Buzz publishing output can
+ * reattach from the persisted cursor instead of letting a normal stale drain
+ * swallow the resumed answer.
+ */
+export async function followPendingConversation(session, initial, callbacks, signal) {
+    let state = { ...initial };
+    let streamIndex = initial.streamIndex;
+    let completedMessage = "";
+    const persist = async () => {
+        state = { ...state, streamIndex };
+        await callbacks.onState(state);
+    };
+    const publishThenClear = async () => {
+        // Do not persist past message.completed/turn.completed until publication
+        // succeeds. If this callback throws or the process dies, recovery replays
+        // the unpublished output from the last safe cursor.
+        if (completedMessage.trim())
+            await callbacks.onMessage(completedMessage);
+        state = withoutSupervision(state);
+        await persist();
+    };
+    for await (const event of session.stream({
+        follow: true,
+        startIndex: initial.streamIndex,
+        signal,
+    })) {
+        if (signal.aborted)
+            return;
+        const streamEvent = event;
+        // ClientSession updates its public cursor only when the async iterator
+        // closes; count yielded durable events so crash recovery can persist while
+        // the follower is still open.
+        streamIndex += 1;
+        switch (streamEvent.type) {
+            case "input.requested":
+                completedMessage = "";
+                state = withPending(state, streamEvent.data.requests);
+                // Keep the durable cursor before the prompt until Buzz accepts it for
+                // relay delivery; a reconnect can then replay and render the request.
+                await callbacks.onInputRequested(streamEvent.data.requests);
+                await persist();
+                break;
+            case "input.resolved": {
+                const resolved = new Set(streamEvent.data.resolutions.map((resolution) => resolution.requestId));
+                const remaining = state.pendingInputRequests?.filter((request) => !resolved.has(request.requestId)) ?? [];
+                state = remaining.length > 0 ? withPending(state, remaining) : withResumeInFlight(state);
+                await persist();
+                break;
+            }
+            case "message.completed":
+                // A resumed turn can end more than one step with prose (the answer, then a wrap-up line).
+                // The room gets the whole turn, not whichever message happened to come last.
+                if (streamEvent.data.finishReason !== "tool-calls" && streamEvent.data.message) {
+                    completedMessage = completedMessage
+                        ? `${completedMessage}\n\n${streamEvent.data.message}`
+                        : streamEvent.data.message;
+                }
+                // The durable cursor remains before unpublished output. A restarted
+                // follower may replay this event safely because it is the sole publisher.
+                break;
+            case "turn.completed":
+            case "session.waiting":
+                if (!state.pendingInputRequests?.length) {
+                    await publishThenClear();
+                    return;
+                }
+                await persist();
+                break;
+            case "turn.cancelled":
+            case "turn.failed":
+            case "session.failed":
+            case "session.completed":
+                state = withoutSupervision(state);
+                await persist();
+                return;
+            default:
+                // Replaying progress events after a crash has no outward side effect.
+                // Persist semantic boundaries rather than writing the session file for
+                // every token delta.
+                break;
+        }
+    }
+    callbacks.onLog?.("pending Eve stream ended before a resumable boundary");
+}

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;
@@ -61,6 +64,8 @@ export declare class BuzzRelay {
     /** Answered already, so a redelivery in two overlapping polls is not answered twice. */
     private readonly seen;
     private cursor;
+    /** Prompts this agent posted; replies to them are polled for even when they carry no mention. */
+    private readonly replyWatch;
     private readonly url;
     private readonly rest;
     private readonly key;
@@ -69,6 +74,9 @@ export declare class BuzzRelay {
     private readonly log;
     constructor(options: RelayOptions);
     get pubkey(): string;
+    /** Also poll for replies to these events — a person answering a prompt rarely mentions the asker. */
+    watchReplies(ids: Iterable<string>): void;
+    unwatchReplies(ids: Iterable<string>): void;
     connect(): void;
     close(): void;
     private reconnect;
@@ -83,17 +91,18 @@ export declare class BuzzRelay {
      * failure — a process that connects, authenticates, logs that it is listening, and silently
      * ignores every message addressed to it.
      */
-    private poll;
+    poll(): void;
+    /** Publish one event; returns its id when it left this process, null when the socket was down. */
     publish(event: {
         kind: number;
         tags: string[][];
         content: string;
-    }): void;
+    }): string | null;
     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;
+    reply(channel: string, text: string, replyTo?: NostrEvent): string | null;
     /** Sign one HTTP request as this agent (NIP-98), binding the signature to the body. */
     private httpAuth;
     private submit;

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;
@@ -57,6 +60,8 @@ export class BuzzRelay {
     /** Answered already, so a redelivery in two overlapping polls is not answered twice. */
     seen = new Set();
     cursor = now();
+    /** Prompts this agent posted; replies to them are polled for even when they carry no mention. */
+    replyWatch = new Set();
     url;
     rest;
     key;
@@ -74,6 +79,15 @@ export class BuzzRelay {
     get pubkey() {
         return this.key.publicKey;
     }
+    /** Also poll for replies to these events — a person answering a prompt rarely mentions the asker. */
+    watchReplies(ids) {
+        for (const id of ids)
+            this.replyWatch.add(id);
+    }
+    unwatchReplies(ids) {
+        for (const id of ids)
+            this.replyWatch.delete(id);
+    }
     connect() {
         if (this.closed)
             return;
@@ -98,6 +112,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 +127,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 +142,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,14 +207,23 @@ 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) {
         if (this.socket?.readyState !== WebSocket.OPEN)
-            return;
+            return false;
         this.socket.send(JSON.stringify(frame));
+        return true;
     }
     /**
      * Ask for what is new, rather than waiting to be told.
@@ -198,11 +237,19 @@ export class BuzzRelay {
     poll() {
         if (this.closed)
             return;
-        this.send(["REQ", `m${Date.now()}`, { kinds: [KIND_MESSAGE], "#p": [this.key.publicKey], since: this.cursor }]);
+        const filters = [
+            { kinds: [KIND_MESSAGE], "#p": [this.key.publicKey], since: this.cursor },
+        ];
+        if (this.replyWatch.size > 0) {
+            filters.push({ kinds: [KIND_MESSAGE], "#e": [...this.replyWatch], since: this.cursor });
+        }
+        this.send(["REQ", `m${Date.now()}`, ...filters]);
         this.pollTimer = setTimeout(() => this.poll(), this.pollMs);
     }
+    /** Publish one event; returns its id when it left this process, null when the socket was down. */
     publish(event) {
-        this.send(["EVENT", finalizeEvent({ created_at: now(), ...event }, this.key.secretKey)]);
+        const signed = finalizeEvent({ created_at: now(), ...event }, this.key.secretKey);
+        return this.send(["EVENT", signed]) ? signed.id : null;
     }
     setPresence(status) {
         this.publish({ kind: KIND_PRESENCE, tags: [], content: status });
@@ -225,7 +272,7 @@ export class BuzzRelay {
         if (replyTo) {
             tags.push(["e", replyTo.id], ["p", replyTo.pubkey]);
         }
-        this.publish({ kind: KIND_MESSAGE, tags, content: text });
+        return 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) {

package/dist/sessions.d.ts

@@ -1,10 +1,27 @@
+import type { InputRequest } from "eve/client";
 /** One conversation: which eve session it is, and how far the bridge has read. */
 export interface StoredSession {
     id: string;
     streamIndex: number;
+    /** Requests that have parked this session, when HITL is awaiting a reply. */
+    pendingInputRequests?: readonly InputRequest[];
+    /** Eve accepted the HITL response and resumed, but Buzz has not published its output yet. */
+    resumeInFlight?: boolean;
+    /** Public identity used to refresh credentials when a follower reattaches. Never a bearer token. */
+    speakerPublicKey?: string;
+    /**
+     * Relay event ids of the prompts posted for the pending requests, so a reply to one of them
+     * counts as an answer whether or not it mentions this agent.
+     */
+    promptEventIds?: readonly string[];
     /** When it was last used, so a store that runs for years does not grow forever. */
     updated: number;
 }
+export interface StoredSessionEntry {
+    community: string;
+    channel: string;
+    session: StoredSession;
+}
 /**
  * Which eve session belongs to which channel, across restarts.
  *
@@ -21,17 +38,18 @@ export interface StoredSession {
  * 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.
+ * in two workspaces cannot assume they never collide. Optional HITL fields keep
+ * records written by older Buzz versions valid.
  */
 export declare class SessionStore {
     #private;
-    constructor(file: string);
+    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;
+    set(community: string, channel: string, session: Omit<StoredSession, "updated">): void;
     delete(community: string, channel: string): void;
+    entries(): StoredSessionEntry[];
     get size(): number;
 }

package/dist/sessions.js

@@ -18,13 +18,16 @@ const KEEP_MS = 30 * 24 * 60 * 60 * 1000;
  * 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.
+ * in two workspaces cannot assume they never collide. Optional HITL fields keep
+ * records written by older Buzz versions valid.
  */
 export class SessionStore {
     #file;
     #entries = new Map();
-    constructor(file) {
+    #onError;
+    constructor(file, options = {}) {
         this.#file = file;
+        this.#onError = options.onError ?? (() => { });
         this.#load();
     }
     static key(community, channel) {
@@ -41,6 +44,20 @@ export class SessionStore {
         this.#entries.delete(SessionStore.key(community, channel));
         this.#save();
     }
+    entries() {
+        const entries = [];
+        for (const [key, session] of this.#entries) {
+            const separator = key.lastIndexOf("|");
+            if (separator < 0)
+                continue;
+            entries.push({
+                community: key.slice(0, separator),
+                channel: key.slice(separator + 1),
+                session,
+            });
+        }
+        return entries;
+    }
     get size() {
         return this.#entries.size;
     }
@@ -51,14 +68,17 @@ export class SessionStore {
             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) {
+                if (typeof value?.id === "string" &&
+                    typeof value?.streamIndex === "number" &&
+                    (value.updated ?? 0) > cutoff) {
                     this.#entries.set(key, value);
                 }
             }
         }
-        catch {
+        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() {
@@ -72,9 +92,10 @@ export class SessionStore {
             writeFileSync(tmp, JSON.stringify(Object.fromEntries(this.#entries)), { mode: 0o600 });
             renameSync(tmp, this.#file);
         }
-        catch {
+        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,28 @@
+import { type Client, type InputRequest, type MessageResult, 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"];
+/** Everything the bridge needs to decide how one eve turn should be rendered. */
+export interface TurnOutcome {
+    message: string;
+    status: MessageResult["status"];
+    inputRequests: readonly InputRequest[];
+    sessionId: string;
+    streamIndex: number;
+}
+/** 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<TurnOutcome>;
+/**
+ * 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,129 @@
+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;
+}
+function outcome(result, streamIndex) {
+    return {
+        message: result.message ?? "",
+        status: result.status,
+        inputRequests: result.inputRequests,
+        sessionId: result.sessionId,
+        streamIndex,
+    };
+}
+/** 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.
+             *
+             * Do not call this path while HITL is pending: the bridge's follower owns
+             * that unread stream until the parked turn reaches its next boundary.
+             */
+            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 outcome(result, session.state.streamIndex);
+        }
+        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 result = await created.response.result();
+    sessions.set(community, channel, {
+        id: created.session.state.sessionId,
+        streamIndex: created.session.state.streamIndex,
+    });
+    return outcome(result, created.session.state.streamIndex);
+}
+/**
+ * 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.8.0",
+  "version": "0.9.1",
   "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"