@kybernesis/buzz 0.12.2 → 0.14.0

package/README.md

@@ -81,6 +81,38 @@ command on the host. The `.agent` name comes from `ARP_AGENT_DID`, or from
 runs it through `@kybernesis/manage` (`buzz.profile`). `kybernesis-buzz profile --from-agentid`
 still takes the profile from the name alone.
 
+## Cards
+
+When a tool hands back a card (a chart, a table, a checklist, an artifact), the bridge posts it
+after the reply as its own threaded message: the card's text for people to read, and the card
+itself in an HTML comment (`<!-- kyb:card v1 {...} -->`) that Buzz hides. The reply stays an
+ordinary message Buzz draws itself. The Kybernesis cards plugin for the Buzz desktop app
+(`plugin/`) draws those messages as the card; without it people read the text.
+
+An artifact posted into a channel is shared with the channel: the bridge asks the agent for a
+share link as the person who asked (`POST /eve/v1/kyb/artifacts/:id/share`, `@kybernesis/manage`
+0.28), and the card carries it. The plugin draws the page inside the card on the macOS desktop
+app and opens it beside the conversation; everywhere else the link is in the text. The person
+can withdraw the link from the agent. `BUZZ_CARDS=off` stops card messages.
+
+## Questions and approvals
+
+When the agent needs a yes or an answer, the bridge posts the question as a reply to the message
+that asked: an approval as the email, event or message it would send (recipients, subject and
+the whole body, not "Approve tool call"), any other question as its sentence, then the options by
+number. Anyone can answer by replying with a number, an option or their own words. Since 0.14 the
+question also travels hidden (`<!-- kyb:ask v1 {...} -->`), and the plugin draws it as Studio
+does, with Send it, Edit and Don't send on an email, the amount and Approve in Link on a
+purchase, and the fields of a form. A press posts the person's answer as a reply to the
+question: a short line, with the answer hidden after it (`<!-- kyb:answer v1 {...} -->`). The
+bridge accepts a hidden answer only as a direct reply to a prompt it posted, only for a request
+still open, and only with that request's own options. Replies inside a thread count, whichever
+`e` tag names the prompt. A vault request never takes a secret in the channel.
+
+If the work an answer restarts fails (a model refusing the continuation, say), the bridge says so
+in the channel with the stream's own error, rather than leaving the person who answered with
+silence. A declined call is the person's choice and is not reported as a failure.
+
 ## Configuration
 
 | Variable | Meaning |
@@ -91,6 +123,7 @@ still takes the profile from the name alone.
 | `BUZZ_SESSIONS_FILE` | Channel-to-session continuity store (default beside the key file; an existing legacy `.buzz-sessions.json` is reused) |
 | `BUZZ_AGENT_SILENCE_TIMEOUT_MS` | Maximum silence before the agent acknowledges a request: unread drain, send and create acknowledgement (default `300000`, five minutes). This is where a genuine stall shows: no run is ever created. |
 | `BUZZ_AGENT_WORK_TIMEOUT_MS` | Ceiling on silence once the response stream is open (default `3600000`, sixty minutes). The stream is quiet while the agent works, a long tool call or a delegated subagent produces nothing until it returns, so this is a ceiling on work, not a stall detector. |
+| `BUZZ_CARDS` | `off` stops posting cards after replies and hidden questions in prompts (default on) |
 | `BUZZ_PROFILE_SYNC_MS` | How often the profile is re-checked against the name and picture its owner set and its `.agent` name (default `900000`, fifteen minutes; `0` turns it off) |
 | `AGENTID_MIRROR_SUFFIX` | Where names serve their public documents (default `.agentid.dev`); for staging only |
 | `KYBERNESIS_ISSUER` | The control plane |

package/dist/bridge.d.ts

@@ -23,6 +23,14 @@ export type BuzzBridgeOptions = {
     agentSilenceTimeoutMs?: number;
     /** Ceiling on a turn once acknowledged; the agent is working while its stream is quiet. Default 60 minutes. */
     agentWorkTimeoutMs?: number;
+    /**
+     * Post the cards a turn's tools handed back, each as its own message after
+     * the reply: the card's text, with the card hidden in a comment for clients
+     * that draw it. Questions carry themselves the same way (0.14), so the
+     * plugin can draw an approval as its email and answer it with a press.
+     * Default true; false posts the reply and questions as words alone.
+     */
+    cards?: boolean;
     onLog?: (message: string) => void;
 };
 export declare function buzzBridge(options: BuzzBridgeOptions): {

package/dist/bridge.js

@@ -1,10 +1,11 @@
+import { cardMessage, cardText, readHiddenAnswers } from "@kybernesis/cards";
 import { channelIdentity } from "@kybernesis/enterprise";
 import { fetchMedia, parseMedia } from "./media.js";
 import { speakerCredentials } from "./credentials.js";
 import { surfaceWriter } from "./surface.js";
 import { SessionStore } from "./sessions.js";
 import { agentSilenceReply, answerTurn, composeMessage, DEFAULT_AGENT_SILENCE_TIMEOUT_MS, DEFAULT_AGENT_WORK_TIMEOUT_MS, describeSilentTurn, rejectedTurnReply, silentTurnReply, validateAgentSilenceTimeoutMs, } from "./turn.js";
-import { followPendingConversation, followerRetryDelayMs, formatInputRequests, invalidInputReply, needsPendingFollower, resolveInputReply, respondToPendingConversation, resumeStalledReply, } from "./hitl.js";
+import { followPendingConversation, followerRetryDelayMs, formatInputRequests, invalidInputReply, needsPendingFollower, resolveCarriedAnswers, resolveInputReply, respondToPendingConversation, resumeFailedReply, resumeStalledReply, STALE_ANSWER_REPLY, } from "./hitl.js";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { Client } from "eve/client";
@@ -34,6 +35,66 @@ export function buzzBridge(options) {
     const log = options.onLog ?? ((message) => console.log(new Date().toISOString().slice(11, 19), message));
     const agentWorkTimeoutMs = validateAgentSilenceTimeoutMs(options.agentWorkTimeoutMs ?? DEFAULT_AGENT_WORK_TIMEOUT_MS);
     const agentSilenceTimeoutMs = validateAgentSilenceTimeoutMs(options.agentSilenceTimeoutMs ?? DEFAULT_AGENT_SILENCE_TIMEOUT_MS);
+    /**
+     * An artifact card, with a link everyone in the channel can open.
+     *
+     * Posting an artifact into a channel shares it with the channel: that is
+     * what the person asked for by asking here. The link is made by the agent's
+     * own share route, as the person who asked (the artifact's owner), so it is
+     * their act and they can withdraw it from their artifacts. If the link
+     * cannot be made, the card goes out as it was and says where to open it.
+     */
+    const sharedInChannel = async (card, speaker) => {
+        if (card.card !== "artifact" || !card.data || typeof card.data !== "object")
+            return card;
+        const data = card.data;
+        if (typeof data.artifactId !== "string" || typeof data.url === "string")
+            return card;
+        try {
+            const credentials = credentialsFor(speaker);
+            const response = await fetch(`${options.agentUrl.replace(/\/$/, "")}/eve/v1/kyb/artifacts/${encodeURIComponent(data.artifactId)}/share`, {
+                method: "POST",
+                headers: {
+                    ...(await credentials.headers()),
+                    authorization: `Bearer ${await credentials.bearer()}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify(typeof data.version === "number" ? { version: data.version } : {}),
+                signal: AbortSignal.timeout(15_000),
+            });
+            const body = (await response.json().catch(() => null));
+            if (!response.ok || !body?.ok || typeof body.url !== "string") {
+                log(`could not share artifact ${data.artifactId.slice(0, 8)} (${response.status} ${String(body?.error ?? "")})`);
+                return card;
+            }
+            // The words people without the plugin read now carry the link.
+            const shared = { ...card, data: { ...data, url: body.url }, text: undefined };
+            return { ...shared, text: cardText(shared) };
+        }
+        catch (error) {
+            log(`could not share artifact ${data.artifactId.slice(0, 8)} (${error.message})`);
+            return card;
+        }
+    };
+    /**
+     * A turn's cards, one message each, threaded where the reply went.
+     *
+     * The reply stays an ordinary message the client draws itself, links and
+     * mentions included; a card-aware client swaps only these follow-ups for the
+     * card. They do not mention the asker again: the reply already did.
+     */
+    const postCards = async (relay, channel, cards, speaker, replyTo) => {
+        if (options.cards === false || cards.length === 0)
+            return;
+        let posted = 0;
+        for (const card of await Promise.all(cards.map((c) => sharedInChannel(c, speaker)))) {
+            const content = cardMessage(card);
+            if (content && relay.reply(channel, content, replyTo, { mention: false }))
+                posted += 1;
+        }
+        if (posted)
+            log(`posted ${posted} card(s) in ${channel.slice(0, 8)}`);
+    };
     /**
      * One conversation per channel — the SESSION ID, not a handle to it.
      *
@@ -236,7 +297,7 @@ export function buzzBridge(options) {
             onInputRequested: (requests) => serialize(community, channel, async () => {
                 if (followers.get(conversation) !== controller)
                     return;
-                const promptId = relay.reply(channel, formatInputRequests(requests));
+                const promptId = relay.reply(channel, formatInputRequests(requests, { carry: options.cards !== false }));
                 if (!promptId)
                     throw new Error("Buzz relay is not connected");
                 relay.watchReplies([promptId]);
@@ -249,12 +310,24 @@ export function buzzBridge(options) {
                 }
                 log(`posted another input request in ${channel.slice(0, 8)}`);
             }),
-            onMessage: (message) => serialize(community, channel, async () => {
+            onMessage: (message, cards) => serialize(community, channel, async () => {
                 if (followers.get(conversation) !== controller)
                     return;
-                if (!relay.reply(channel, message))
+                if (message.trim() && !relay.reply(channel, message))
                     throw new Error("Buzz relay is not connected");
-                log(`posted resumed reply in ${channel.slice(0, 8)} (${message.length} chars)`);
+                if (message.trim())
+                    log(`posted resumed reply in ${channel.slice(0, 8)} (${message.length} chars)`);
+                await postCards(relay, channel, cards, stored.speakerPublicKey);
+            }),
+            onFailed: (failures) => serialize(community, channel, async () => {
+                if (followers.get(conversation) !== controller)
+                    return;
+                const current = sessions.get(community, channel);
+                if (current?.promptEventIds?.length)
+                    relay.unwatchReplies(current.promptEventIds);
+                if (!relay.reply(channel, resumeFailedReply(failures)))
+                    throw new Error("Buzz relay is not connected");
+                log(`resumed turn failed in ${channel.slice(0, 8)} (${describeSilentTurn(failures)}); told the room`);
             }),
             onLog: log,
         }, controller.signal).catch((error) => {
@@ -315,9 +388,13 @@ export function buzzBridge(options) {
         const addressed = event.tags.some((t) => t[0] === "p" && t[1] === key.publicKey);
         // 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];
+        // Any `e` tag counts: a reply inside a thread names the thread's root first and the prompt
+        // after it (NIP-10 `root` and `reply` markers), so the first tag is often not the prompt.
+        const referenced = event.tags.filter((t) => t[0] === "e" && typeof t[1] === "string").map((t) => t[1]);
+        // The message this one answers directly: the `reply` marker, else the last `e` tag.
+        const parent = event.tags.find((t) => t[0] === "e" && t[3] === "reply")?.[1] ?? referenced.at(-1);
         const open = channel ? sessions.get(from, channel) : undefined;
-        const answersPrompt = Boolean(repliedTo && open?.pendingInputRequests?.length && open.promptEventIds?.includes(repliedTo));
+        const answersPrompt = Boolean(open?.pendingInputRequests?.length && referenced.some((id) => open.promptEventIds?.includes(id)));
         // In a one-to-one DM every message is to the agent, mention or not, as with Buzz's own
         // agents. Not one written by another agent (it carries its owner's `auth` attestation):
         // two agents in a DM would otherwise answer each other forever.
@@ -351,9 +428,27 @@ export function buzzBridge(options) {
             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);
+                    let responses;
+                    const carried = readHiddenAnswers(text);
+                    if (carried.length) {
+                        // A press in the plugin. It counts only as a direct reply to a prompt this bridge
+                        // posted, so a message quoting someone else's question cannot answer this one.
+                        if (!parent || !pending.promptEventIds?.includes(parent)) {
+                            log(`ignored a pressed answer in ${channel.slice(0, 8)} that does not reply to an open prompt`);
+                            return;
+                        }
+                        const resolved = resolveCarriedAnswers(carried, pending.pendingInputRequests);
+                        if (!resolved.responses) {
+                            relay.reply(channel, resolved.stale ? STALE_ANSWER_REPLY : invalidInputReply(pending.pendingInputRequests), event);
+                            return;
+                        }
+                        responses = resolved.responses;
+                    }
+                    else {
+                        // "@Ava approve" is an approve. The mention is how the message reached us, not the answer.
+                        const answer = addressed ? text.replace(/^@\S+\s*/, "") : text;
+                        responses = resolveInputReply(answer, pending.pendingInputRequests);
+                    }
                     if (!responses) {
                         relay.reply(channel, invalidInputReply(pending.pendingInputRequests), event);
                         return;
@@ -369,7 +464,7 @@ export function buzzBridge(options) {
                     const session = clientFor(event.pubkey).sessions.attach(pending.id, {
                         streamIndex: pending.streamIndex,
                     });
-                    await respondToPendingConversation(session, responses, from, channel);
+                    await respondToPendingConversation(session, responses);
                     log(`submitted ${responses.length} input response(s) in ${channel.slice(0, 8)}`);
                     /**
                      * The answer is in, so this conversation is no longer waiting on a
@@ -384,10 +479,13 @@ export function buzzBridge(options) {
                      * a human, so while that flag was set the room could only be told
                      * nothing.
                      */
+                    // A press answers one question; any others stay open until they are answered too.
                     const answered = sessions.get(from, channel);
                     if (answered?.pendingInputRequests?.length) {
+                        const done = new Set(responses.map((response) => response.requestId));
+                        const remaining = answered.pendingInputRequests.filter((request) => !done.has(request.requestId));
                         const { pendingInputRequests: _resolved, ...rest } = answered;
-                        sessions.set(from, channel, { ...rest, resumeInFlight: true });
+                        sessions.set(from, channel, remaining.length ? { ...rest, pendingInputRequests: remaining } : { ...rest, resumeInFlight: true });
                     }
                     return;
                 }
@@ -411,7 +509,7 @@ export function buzzBridge(options) {
                         pendingInputRequests: result.inputRequests,
                         speakerPublicKey: event.pubkey,
                     });
-                    const promptId = relay.reply(channel, formatInputRequests(result.inputRequests), event);
+                    const promptId = relay.reply(channel, formatInputRequests(result.inputRequests, { carry: options.cards !== false }), event);
                     if (promptId) {
                         relay.watchReplies([promptId]);
                         const current = sessions.get(from, channel);
@@ -422,6 +520,10 @@ export function buzzBridge(options) {
                     startFollower(from, channel);
                     return;
                 }
+                if (!result.message && result.cards.length) {
+                    await postCards(relay, channel, result.cards, event.pubkey, event);
+                    return;
+                }
                 if (!result.message) {
                     // Say what the stream said: a failed tool by name and error, a
                     // failed model call by code, or, only when there is truly nothing,
@@ -432,6 +534,7 @@ export function buzzBridge(options) {
                 }
                 relay.reply(channel, result.message, event);
                 log(`replied (${result.message.length} chars)`);
+                await postCards(relay, channel, result.cards, event.pubkey, event);
             });
         }
         catch (error) {

package/dist/cli.js

@@ -230,6 +230,7 @@ function run() {
         ...(process.env.BUZZ_AGENT_WORK_TIMEOUT_MS
             ? { agentWorkTimeoutMs: Number(process.env.BUZZ_AGENT_WORK_TIMEOUT_MS) }
             : {}),
+        ...(process.env.BUZZ_CARDS === "off" ? { cards: false } : {}),
         ...(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS
             ? { agentSilenceTimeoutMs: Number(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS) }
             : {}),
@@ -422,6 +423,7 @@ else {
     BUZZ_SESSIONS_FILE             channel-to-session continuity store
     BUZZ_AGENT_SILENCE_TIMEOUT_MS   maximum silence before a turn is acknowledged (default 300000ms)
     BUZZ_AGENT_WORK_TIMEOUT_MS      ceiling on a turn once acknowledged (default 3600000ms)
+    BUZZ_CARDS=off                  post replies without the cards tools handed back
     BUZZ_PROFILE_SYNC_MS           how often the profile is re-checked against the name and
                                    picture its owner set (default 900000ms, fifteen
                                    minutes; 0 turns it off)

package/dist/hitl.d.ts

@@ -1,18 +1,52 @@
 import { type ClientSession, type InputRequest, type InputResponse } from "eve/client";
+import { type AskAnswer, type Card } from "@kybernesis/cards";
 import type { StoredSession } from "./sessions.js";
+import { type TurnFailure } from "./turn.js";
 /**
- * Render pending Eve input in a text-only Buzz channel.
+ * Render pending Eve input in a Buzz channel.
  *
- * A Kybernesis tool may put a `[kyb:…] {json}` marker on a question's first
- * line for apps that draw it as a card. Buzz shows only the sentence after it.
+ * Everyone reads the words: a question's sentence (a `[kyb:…]` marker line is
+ * dropped), an approval as the email or event it would send, then the options
+ * by number. With `carry`, each question also travels hidden after the words
+ * (`<!-- kyb:ask v1 … -->`), so the Kybernesis plugin can draw it the way
+ * Studio does and answer it with a press. Only a posted prompt carries them:
+ * a press is accepted only as a reply to a prompt the bridge is watching.
  */
-export declare function formatInputRequests(requests: readonly InputRequest[]): string;
+export declare function formatInputRequests(requests: readonly InputRequest[], options?: {
+    carry?: boolean;
+}): string;
+/**
+ * Answers a client pressed, checked against what is actually open.
+ *
+ * Each answer must name an open request. An option must be one of that
+ * request's own; words alone answer only a question that takes words. eve's
+ * strict schema checks the result before it is sent. `stale` is true when no
+ * answer named an open request, which is what a second press on a question
+ * someone already answered looks like.
+ */
+export declare function resolveCarriedAnswers(answers: readonly AskAnswer[], requests: readonly InputRequest[]): {
+    responses: readonly InputResponse[];
+    stale: false;
+} | {
+    responses: null;
+    stale: boolean;
+};
+/** What a press on a question nobody is waiting on any more gets. */
+export declare const STALE_ANSWER_REPLY = "That question was already answered, so nothing changed.";
 /** 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>;
+/**
+ * Submit a matched reply without consuming its response stream.
+ *
+ * No `clientContext`: the turn already carries the channel from when it
+ * started, and eve 0.81 treats context on a respond as new turn input. It then
+ * runs one more model step after the agent's reply, with the agent's message
+ * last, which models that refuse prefill reject. The turn fails and the whole
+ * conversation ends, on an approve, a decline or an answer alike.
+ */
+export declare function respondToPendingConversation(session: Pick<ClientSession, "respond">, responses: readonly InputResponse[]): Promise<void>;
 /**
  * How long a follower waits between reattaching when it saw no progress.
  *
@@ -33,13 +67,26 @@ export declare function followerRetryDelayMs(cycles: number, capMs?: number): nu
  * Say the answer arrived, say the work did not, and say the channel is usable.
  */
 export declare function resumeStalledReply(stallMs: number): string;
+/**
+ * What the room is told when the turn an answer resumed failed.
+ *
+ * @remarks
+ * Found live: a declined approval resumed the turn, the model refused the
+ * continuation, and the run ended. The follower saw the stream end and said
+ * nothing, so the person who pressed Decline got silence. They answered; the
+ * failure is the one thing they must hear about, in the stream's own words.
+ */
+export declare function resumeFailedReply(failures: readonly TurnFailure[]): string;
 /** 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>;
+    /** The resumed turn's words, and the cards its tools handed back. */
+    onMessage(message: string, cards: readonly Card[]): void | Promise<void>;
+    /** The resumed turn failed: what the stream said, for the room. */
+    onFailed?(failures: readonly TurnFailure[]): void | Promise<void>;
     onLog?: (message: string) => void;
 }
 type MutableStoredSession = Omit<StoredSession, "updated">;

package/dist/hitl.js

@@ -1,14 +1,21 @@
-import { resolveTextToResponses, } from "eve/client";
-import { promptText } from "@kybernesis/cards";
+import { parseInputResponses, resolveTextToResponses, } from "eve/client";
+import { askFrom, askText, cardsOf, hiddenAsk, newStepState, readStep } from "@kybernesis/cards";
+import { failureFromEvent, silentTurnReply } from "./turn.js";
 /**
- * Render pending Eve input in a text-only Buzz channel.
+ * Render pending Eve input in a Buzz channel.
  *
- * A Kybernesis tool may put a `[kyb:…] {json}` marker on a question's first
- * line for apps that draw it as a card. Buzz shows only the sentence after it.
+ * Everyone reads the words: a question's sentence (a `[kyb:…]` marker line is
+ * dropped), an approval as the email or event it would send, then the options
+ * by number. With `carry`, each question also travels hidden after the words
+ * (`<!-- kyb:ask v1 … -->`), so the Kybernesis plugin can draw it the way
+ * Studio does and answer it with a press. Only a posted prompt carries them:
+ * a press is accepted only as a reply to a prompt the bridge is watching.
  */
-export function formatInputRequests(requests) {
-    return requests.map((request, requestIndex) => {
-        const prompt = promptText(request.prompt);
+export function formatInputRequests(requests, options = {}) {
+    const asks = requests.map((request) => askFrom(request));
+    const text = asks.map((ask, requestIndex) => {
+        const request = requests[requestIndex];
+        const prompt = askText(ask);
         const lines = [
             requests.length > 1 ? `Question ${requestIndex + 1}: ${prompt}` : prompt,
         ];
@@ -26,7 +33,58 @@ export function formatInputRequests(requests) {
         }
         return lines.join("\n");
     }).join("\n\n");
+    if (!options.carry)
+        return text;
+    const hidden = asks.map((ask) => hiddenAsk(ask)).filter((h) => h !== null);
+    return hidden.length ? `${text}\n\n${hidden.join("\n")}` : text;
 }
+/**
+ * Answers a client pressed, checked against what is actually open.
+ *
+ * Each answer must name an open request. An option must be one of that
+ * request's own; words alone answer only a question that takes words. eve's
+ * strict schema checks the result before it is sent. `stale` is true when no
+ * answer named an open request, which is what a second press on a question
+ * someone already answered looks like.
+ */
+export function resolveCarriedAnswers(answers, requests) {
+    const open = new Map(requests.map((request) => [request.requestId, request]));
+    const picked = new Map();
+    let named = false;
+    for (const answer of answers) {
+        const request = open.get(answer.requestId);
+        if (!request)
+            continue;
+        named = true;
+        if (picked.has(request.requestId))
+            continue;
+        const ids = request.options?.map((option) => option.id) ?? [];
+        if (answer.optionId !== undefined) {
+            if (ids.length > 0 && !ids.includes(answer.optionId))
+                return { responses: null, stale: false };
+            picked.set(request.requestId, {
+                requestId: request.requestId,
+                optionId: answer.optionId,
+                ...(answer.text?.trim() ? { text: answer.text.trim() } : {}),
+            });
+            continue;
+        }
+        const words = answer.text?.trim();
+        if (!words || (ids.length > 0 && request.allowFreeform !== true))
+            return { responses: null, stale: false };
+        picked.set(request.requestId, { requestId: request.requestId, text: words });
+    }
+    if (picked.size === 0)
+        return { responses: null, stale: !named };
+    try {
+        return { responses: parseInputResponses([...picked.values()]), stale: false };
+    }
+    catch {
+        return { responses: null, stale: false };
+    }
+}
+/** What a press on a question nobody is waiting on any more gets. */
+export const STALE_ANSWER_REPLY = "That question was already answered, so nothing changed.";
 /** Resolve a Buzz text reply using Eve's certified matching semantics. */
 export function resolveInputReply(text, requests) {
     if (!text.trim())
@@ -38,10 +96,17 @@ export function resolveInputReply(text, requests) {
 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) {
+/**
+ * Submit a matched reply without consuming its response stream.
+ *
+ * No `clientContext`: the turn already carries the channel from when it
+ * started, and eve 0.81 treats context on a respond as new turn input. It then
+ * runs one more model step after the agent's reply, with the agent's message
+ * last, which models that refuse prefill reject. The turn fails and the whole
+ * conversation ends, on an approve, a decline or an answer alike.
+ */
+export async function respondToPendingConversation(session, responses) {
     await session.respond(responses, {
-        clientContext: { buzzCommunity: community, buzzChannel: channel },
         streamReconnectPolicy: { reconnect: false },
     });
 }
@@ -73,6 +138,19 @@ export function resumeStalledReply(stallMs) {
         `${minutes === 1 ? "" : "s"} without producing anything, so I have stopped waiting on it. ` +
         `Nothing was posted and no work landed from it. This channel is clear — ask me again and I will start fresh.`);
 }
+/**
+ * What the room is told when the turn an answer resumed failed.
+ *
+ * @remarks
+ * Found live: a declined approval resumed the turn, the model refused the
+ * continuation, and the run ended. The follower saw the stream end and said
+ * nothing, so the person who pressed Decline got silence. They answered; the
+ * failure is the one thing they must hear about, in the stream's own words.
+ */
+export function resumeFailedReply(failures) {
+    const said = silentTurnReply(failures);
+    return `Your answer reached me, but the work it restarted stopped. ${said}`;
+}
 /** A session needs its follower while asking or while resumed output is unpublished. */
 export function needsPendingFollower(session) {
     return Boolean(session.pendingInputRequests?.length || session.resumeInFlight);
@@ -105,6 +183,17 @@ export async function followPendingConversation(session, initial, callbacks, sig
     let state = { ...initial };
     let streamIndex = initial.streamIndex;
     let completedMessage = "";
+    let steps = newStepState();
+    /** Failures since the last answer. A declined call is the person's choice, not one. */
+    let failures = [];
+    /** Tell the room, then stop supervising: a failed run will not come back. */
+    const failThenClear = async () => {
+        // Only an answered question resumed this work; a run failing while it waits on a person stays quiet as before.
+        if (state.resumeInFlight)
+            await callbacks.onFailed?.(failures);
+        state = withoutSupervision(state);
+        await persist();
+    };
     const persist = async () => {
         state = { ...state, streamIndex };
         await callbacks.onState(state);
@@ -113,8 +202,9 @@ export async function followPendingConversation(session, initial, callbacks, sig
         // 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);
+        const cards = cardsOf(steps.steps.values());
+        if (completedMessage.trim() || cards.length)
+            await callbacks.onMessage(completedMessage, cards);
         state = withoutSupervision(state);
         await persist();
     };
@@ -130,9 +220,16 @@ export async function followPendingConversation(session, initial, callbacks, sig
         // closes; count yielded durable events so crash recovery can persist while
         // the follower is still open.
         streamIndex += 1;
+        readStep(steps, streamEvent.type, streamEvent.data);
+        const declined = streamEvent.type === "action.result" && streamEvent.data.status === "rejected";
+        const failure = declined ? null : failureFromEvent(streamEvent);
+        if (failure)
+            failures.push(failure);
         switch (streamEvent.type) {
             case "input.requested":
                 completedMessage = "";
+                steps = newStepState();
+                failures = [];
                 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.
@@ -165,9 +262,11 @@ export async function followPendingConversation(session, initial, callbacks, sig
                 }
                 await persist();
                 break;
-            case "turn.cancelled":
             case "turn.failed":
             case "session.failed":
+                await failThenClear();
+                return;
+            case "turn.cancelled":
             case "session.completed":
                 state = withoutSupervision(state);
                 await persist();
@@ -179,5 +278,16 @@ export async function followPendingConversation(session, initial, callbacks, sig
                 break;
         }
     }
+    /**
+     * The stream closed without a boundary. Usually a dropped connection, and
+     * the caller reattaches. But after an answer, a model failure followed by
+     * the end of the stream is the run ending: reattaching finds nothing new,
+     * and the room would be told only after the work ceiling, an hour later.
+     */
+    if (state.resumeInFlight && failures.some((f) => f.kind === "model")) {
+        callbacks.onLog?.("resumed turn failed and its stream ended; telling the room");
+        await failThenClear();
+        return;
+    }
     callbacks.onLog?.("pending Eve stream ended before a resumable boundary");
 }

package/dist/relay.d.ts

@@ -37,6 +37,9 @@ 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;
+/** At most this many messages wait for a reconnect, and none older than this goes out late. */
+export declare const MAX_OUTBOX = 100;
+export declare const OUTBOX_MAX_AGE_MS: number;
 /** How often to re-read which direct conversations this agent is in. */
 export declare const DIRECT_REFRESH_MS = 30000;
 export type NostrEvent = {
@@ -69,6 +72,14 @@ export declare class BuzzRelay {
     private refusal;
     /** Answered already, so a redelivery in two overlapping polls is not answered twice. */
     private readonly seen;
+    /**
+     * Messages and reactions signed while the connection was down or not yet signed in.
+     *
+     * The relay drops in and out every few minutes. A question posted in one of those gaps
+     * used to vanish: the person never saw it, and their next message was taken as a wrong
+     * answer to it. They go out, in order, as soon as the connection is signed in again.
+     */
+    private readonly outbox;
     private cursor;
     /** Prompts this agent posted; replies to them are polled for even when they carry no mention. */
     private readonly replyWatch;
@@ -134,17 +145,24 @@ export declare class BuzzRelay {
     private discoveryDone;
     /** Take the DMs just found; read back any that are new, from when they could last have been missed. */
     private adopt;
-    /** Publish one event; returns its id when it left this process, null when the socket was down. */
+    /**
+     * Publish one event; returns its id when it left this process or waits in the outbox, null
+     * when it was dropped. Presence and typing are dropped while offline: late, they are wrong.
+     */
     publish(event: {
         kind: number;
         tags: string[][];
         content: string;
     }): string | null;
+    private flushOutbox;
     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): string | null;
+    /** `mention: false` threads under `replyTo` without notifying its author again, as a follow-up to a reply does. */
+    reply(channel: string, text: string, replyTo?: NostrEvent, options?: {
+        mention?: boolean;
+    }): 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

@@ -38,6 +38,9 @@ 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;
+/** At most this many messages wait for a reconnect, and none older than this goes out late. */
+export const MAX_OUTBOX = 100;
+export const OUTBOX_MAX_AGE_MS = 15 * 60_000;
 /** How often to re-read which direct conversations this agent is in. */
 export const DIRECT_REFRESH_MS = 30_000;
 /** Ids per `#d`/`#h` filter, and filters per request: the relay caps a request at ten. */
@@ -68,6 +71,14 @@ export class BuzzRelay {
     refusal = null;
     /** Answered already, so a redelivery in two overlapping polls is not answered twice. */
     seen = new Set();
+    /**
+     * Messages and reactions signed while the connection was down or not yet signed in.
+     *
+     * The relay drops in and out every few minutes. A question posted in one of those gaps
+     * used to vanish: the person never saw it, and their next message was taken as a wrong
+     * answer to it. They go out, in order, as soon as the connection is signed in again.
+     */
+    outbox = [];
     cursor = now();
     /** Prompts this agent posted; replies to them are polled for even when they carry no mention. */
     replyWatch = new Set();
@@ -229,6 +240,7 @@ export class BuzzRelay {
             this.backoff = 5_000;
             this.refusal = null;
             this.log(`authenticated as ${this.key.publicKey.slice(0, 12)}…`);
+            this.flushOutbox();
             this.keepPresent();
             this.discoverDirect();
             this.poll();
@@ -404,10 +416,38 @@ export class BuzzRelay {
             this.send(["REQ", `m${Date.now()}c`, ...filters]);
         }
     }
-    /** Publish one event; returns its id when it left this process, null when the socket was down. */
+    /**
+     * Publish one event; returns its id when it left this process or waits in the outbox, null
+     * when it was dropped. Presence and typing are dropped while offline: late, they are wrong.
+     */
     publish(event) {
         const signed = finalizeEvent({ created_at: now(), ...event }, this.key.secretKey);
-        return this.send(["EVENT", signed]) ? signed.id : null;
+        if (this.authenticated && this.send(["EVENT", signed]))
+            return signed.id;
+        // Held only between connections of a running relay; one never started or closed sends nothing.
+        if (this.closed || !this.socket || (event.kind !== KIND_MESSAGE && event.kind !== KIND_REACTION))
+            return null;
+        if (this.outbox.length >= MAX_OUTBOX)
+            this.outbox.shift();
+        this.outbox.push({ event: signed, at: Date.now() });
+        return signed.id;
+    }
+    flushOutbox() {
+        const cutoff = Date.now() - OUTBOX_MAX_AGE_MS;
+        const stale = this.outbox.filter(({ at }) => at < cutoff).length;
+        if (stale)
+            this.log(`dropped ${stale} message(s) held too long while disconnected`);
+        const due = this.outbox.splice(0).filter(({ at }) => at >= cutoff);
+        let sent = 0;
+        for (const held of due) {
+            if (!this.send(["EVENT", held.event]))
+                break;
+            sent += 1;
+        }
+        // The connection dropped again mid-flush: the rest wait for the next sign-in, in order.
+        this.outbox.unshift(...due.slice(sent));
+        if (sent)
+            this.log(`sent ${sent} message(s) held while disconnected`);
     }
     setPresence(status) {
         this.publish({ kind: KIND_PRESENCE, tags: [], content: status });
@@ -425,10 +465,13 @@ export class BuzzRelay {
         const timer = setInterval(tick, TYPING_INTERVAL_MS);
         return () => clearInterval(timer);
     }
-    reply(channel, text, replyTo) {
+    /** `mention: false` threads under `replyTo` without notifying its author again, as a follow-up to a reply does. */
+    reply(channel, text, replyTo, options = {}) {
         const tags = [["h", channel]];
         if (replyTo) {
-            tags.push(["e", replyTo.id], ["p", replyTo.pubkey]);
+            tags.push(["e", replyTo.id]);
+            if (options.mention !== false)
+                tags.push(["p", replyTo.pubkey]);
         }
         return this.publish({ kind: KIND_MESSAGE, tags, content: text });
     }

package/dist/turn.d.ts

@@ -1,4 +1,5 @@
 import { type Client, type InputRequest, type MessageResult, type SendTurnInput } from "eve/client";
+import { type Card } from "@kybernesis/cards";
 import { type FetchedMedia, type MediaRef } from "./media.js";
 import { SessionStore } from "./sessions.js";
 /** Five minutes without an eve event or acknowledgement is treated as a stalled turn. */
@@ -64,6 +65,8 @@ export interface TurnOutcome {
     streamIndex: number;
     /** Failures seen on the stream, in order. Empty on a clean turn. */
     failures: readonly TurnFailure[];
+    /** Cards the turn's tools handed back, read the way the apps read them. */
+    cards: readonly Card[];
 }
 /** Read a failure out of one stream event, or nothing when the event is not one. */
 export declare function failureFromEvent(event: {
@@ -95,9 +98,10 @@ export declare const DEFAULT_UNREAD_DRAIN_TIMEOUT_MS = 20000;
 export declare function answerTurn(client: Client, sessions: SessionStore, channel: string, message: TurnMessage, community: string, log?: (message: string) => void, agentSilenceTimeoutMs?: number, agentWorkTimeoutMs?: number, unreadDrainTimeoutMs?: number): Promise<TurnOutcome>;
 /** What the room is told when eve refuses the turn itself. */
 /**
- * The two answers from eve that mean the stored session cannot carry another
- * turn: an unknown session id (404), and a session that ended (409 with
- * `session_not_active`, "The session is no longer active."). A session ends
+ * The answers from eve that mean the stored session cannot carry another
+ * turn: an unknown session id (404), a session that ended (409 with
+ * `session_not_active`, "The session is no longer active."), and one whose
+ * history expired (410 `session_expired`). A session ends
  * when one of its turns fails hard, for instance a model call that 404s at
  * the gateway; the channel must then start a fresh one.
  *

package/dist/turn.js

@@ -1,4 +1,5 @@
 import { ClientError, createDataUrlFilePart } from "eve/client";
+import { cardsOf, newStepState, readStep } from "@kybernesis/cards";
 import { isImage } from "./media.js";
 /** Five minutes without an eve event or acknowledgement is treated as a stalled turn. */
 export const DEFAULT_AGENT_SILENCE_TIMEOUT_MS = 5 * 60_000;
@@ -210,6 +211,7 @@ async function collectResponse(response, watchdog, phase, streamIndex, continueS
     let status = "completed";
     let inputRequests = [];
     let failures = [];
+    let steps = newStepState();
     let sawTurnStart = false;
     let endedAtOwnBoundary = false;
     let staleBoundaryFirst = false;
@@ -240,8 +242,10 @@ async function collectResponse(response, watchdog, phase, streamIndex, continueS
             status = "completed";
             inputRequests = [];
             failures = [];
+            steps = newStepState();
             return false;
         }
+        readStep(steps, event.type, event.data);
         const failure = failureFromEvent(event);
         if (failure)
             failures.push(failure);
@@ -298,6 +302,7 @@ async function collectResponse(response, watchdog, phase, streamIndex, continueS
             sessionId: response.sessionId,
             streamIndex: streamIndex(),
             failures,
+            cards: cardsOf(steps.steps.values()),
         };
     }
     finally {
@@ -425,9 +430,10 @@ export async function answerTurn(client, sessions, channel, message, community,
 }
 /** What the room is told when eve refuses the turn itself. */
 /**
- * The two answers from eve that mean the stored session cannot carry another
- * turn: an unknown session id (404), and a session that ended (409 with
- * `session_not_active`, "The session is no longer active."). A session ends
+ * The answers from eve that mean the stored session cannot carry another
+ * turn: an unknown session id (404), a session that ended (409 with
+ * `session_not_active`, "The session is no longer active."), and one whose
+ * history expired (410 `session_expired`). A session ends
  * when one of its turns fails hard, for instance a model call that 404s at
  * the gateway; the channel must then start a fresh one.
  *
@@ -441,7 +447,10 @@ export async function answerTurn(client, sessions, channel, message, community,
 export function isSessionGone(error) {
     if (!(error instanceof ClientError))
         return false;
-    if (error.status === 404)
+    // 410 session_expired, "Session history is no longer available.": a run that
+    // ended (a failed turn ends the session) can no longer be read. Seen on
+    // 2026-10-24 when the next message in a channel failed instead of starting over.
+    if (error.status === 404 || error.status === 410)
         return true;
     return (error.status === 409 &&
         (error.code === "session_not_active" || /no longer active/i.test(String(error.message ?? ""))));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Put an eve agent in a Buzz workspace as a member: per-speaker verified identity resolved through the control plane, self-service identity linking, presence, typing and seen signals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -44,7 +44,7 @@
     "test": "node --test \"test/**/*.test.mjs\""
   },
   "dependencies": {
-    "@kybernesis/cards": "^0.1.1",
+    "@kybernesis/cards": "^0.5.0",
     "@kybernesis/enterprise": "^0.10.0",
     "nostr-tools": "^2.10.0",
     "zod": "^4"