@kybernesis/buzz 0.9.0 → 0.9.1

package/dist/bridge.js

@@ -3,6 +3,7 @@ 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";
@@ -105,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;
     }
     /**
@@ -171,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)
@@ -179,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));
@@ -216,44 +300,83 @@ 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, (ref) => fetchMedia(key, ref), log);
         void relay.react(event.id, SEEN);
         const stopTyping = relay.typingIn(channel);
         try {
-            const reply = await serialize(channel, () => answerTurn(clientFor(event.pubkey), sessions, channel, message, from, log));
-            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) {
-            /**
-             * 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.
-             */
+            /** 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}`);
@@ -273,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/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

@@ -64,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;
@@ -72,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;
@@ -86,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

@@ -60,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;
@@ -77,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;
@@ -210,8 +221,9 @@ export class BuzzRelay {
     }
     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.
@@ -225,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 });
@@ -252,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,7 +38,8 @@ 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;
@@ -30,10 +48,8 @@ export declare class SessionStore {
     });
     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,7 +18,8 @@ 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;
@@ -43,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;
     }
@@ -53,7 +68,9 @@ 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);
                 }
             }

package/dist/turn.d.ts

@@ -1,12 +1,20 @@
-import { type Client, type SendTurnInput } from "eve/client";
+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<string>;
+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.
  *

package/dist/turn.js

@@ -33,6 +33,15 @@ export async function composeMessage(text, attachments, fetchAttachment, log = (
     }
     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);
@@ -58,6 +67,9 @@ export async function answerTurn(client, sessions, channel, message, community,
              * 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 })) {
@@ -74,7 +86,7 @@ export async function answerTurn(client, sessions, channel, message, community,
                 id: existing.id,
                 streamIndex: session.state.streamIndex,
             });
-            return result.message ?? "";
+            return outcome(result, session.state.streamIndex);
         }
         catch (error) {
             // A malformed turn does not make its durable session stale. Rethrow so
@@ -90,12 +102,12 @@ export async function answerTurn(client, sessions, channel, message, community,
         message,
         clientContext: { buzzCommunity: community, buzzChannel: channel },
     });
-    const reply = (await created.response.result()).message ?? "";
+    const result = await created.response.result();
     sessions.set(community, channel, {
         id: created.session.state.sessionId,
         streamIndex: created.session.state.streamIndex,
     });
-    return reply;
+    return outcome(result, created.session.state.streamIndex);
 }
 /**
  * What the room is told when eve refuses the turn itself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.9.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",