@kybernesis/buzz 0.14.0 → 0.16.0

package/README.md

@@ -95,12 +95,19 @@ share link as the person who asked (`POST /eve/v1/kyb/artifacts/:id/share`, `@ky
 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.
 
+A screenshot the agent shows (`show_screen` in `@kybernesis/computer`) goes out as an ordinary Buzz
+picture, not a card: the bridge fetches it from the agent as the person who asked
+(`GET /eve/v1/kyb/screens/:id`, served only to them) and stores it in the community's own media
+store, which serves members only. Every Buzz app draws it, with or without the plugin. Like an
+artifact, a screenshot asked for in a channel is shared with that channel. If it cannot be
+fetched or stored, the card goes out as before.
+
 ## 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
+number. The person who asked answers 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
@@ -109,6 +116,16 @@ bridge accepts a hidden answer only as a direct reply to a prompt it posted, onl
 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.
 
+Since 0.15 a question is for the person whose message raised it. Anyone else who presses an
+answer, or names the agent while it waits, is told whose answer it needs; a remark in the
+question's thread is left alone. The question carries who asked, so the plugin shows everyone
+else the email with "Waiting on" and no buttons. `BUZZ_ANSWERS=anyone` keeps the older rule.
+When a question ends (answered, declined, sent back with changes, or no longer waited on because
+its work stopped) the bridge edits its own prompt to say how and by whom, with the question
+hidden as `<!-- kyb:settled v1 {...} -->` instead. Only a message's author can edit it, so every
+client, with the plugin or without, shows the same outcome and nobody is offered the buttons
+again. The edit names nobody, so it notifies nobody.
+
 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.
@@ -124,6 +141,7 @@ silence. A declined call is the person's choice and is not reported as a failure
 | `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_ANSWERS` | Who may answer a question in a shared channel: `asker` (default), only the person whose message raised it, or `anyone` the agent knows there |
 | `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

@@ -31,6 +31,15 @@ export type BuzzBridgeOptions = {
      * Default true; false posts the reply and questions as words alone.
      */
     cards?: boolean;
+    /**
+     * Who may answer a question the agent asks in a shared channel. `asker`
+     * (the default): only the person whose message raised it; anyone else is
+     * told so, and the plugin shows them the question without buttons.
+     * `anyone`: anyone the agent knows in the channel, as before 0.15.
+     * Either way, once a question ends the bridge edits it to say how, for
+     * everyone who can see it.
+     */
+    answers?: "asker" | "anyone";
     onLog?: (message: string) => void;
 };
 export declare function buzzBridge(options: BuzzBridgeOptions): {

package/dist/bridge.js

@@ -1,11 +1,12 @@
 import { cardMessage, cardText, readHiddenAnswers } from "@kybernesis/cards";
 import { channelIdentity } from "@kybernesis/enterprise";
 import { fetchMedia, parseMedia } from "./media.js";
+import { isAgentScreenshot, pictureMessage } from "./pictures.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, resolveCarriedAnswers, resolveInputReply, respondToPendingConversation, resumeFailedReply, resumeStalledReply, STALE_ANSWER_REPLY, } from "./hitl.js";
+import { applySettlements, followPendingConversation, followerRetryDelayMs, formatInputRequests, invalidInputReply, isAsker, needsPendingFollower, notTheAskerReply, settlementsFor, settleRemaining, 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";
@@ -35,6 +36,8 @@ 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);
+    const askerOnly = options.answers !== "anyone";
+    const carry = options.cards !== false;
     /**
      * An artifact card, with a link everyone in the channel can open.
      *
@@ -76,6 +79,27 @@ export function buzzBridge(options) {
             return card;
         }
     };
+    /**
+     * A screenshot card as a picture everyone in the channel sees: fetched from
+     * the agent as the person who asked (it is theirs), stored in this
+     * community's media store. See pictures.ts. If that fails, the card goes out
+     * as it was.
+     */
+    const screenshotIn = async (relay, card, speaker) => {
+        try {
+            const credentials = credentialsFor(speaker);
+            return await pictureMessage(card, {
+                agentUrl: options.agentUrl,
+                headers: async () => ({ ...(await credentials.headers()), authorization: `Bearer ${await credentials.bearer()}` }),
+                relay: relay.url,
+                key,
+            });
+        }
+        catch (error) {
+            log(`could not post a screenshot as a picture (${error.message})`);
+            return null;
+        }
+    };
     /**
      * A turn's cards, one message each, threaded where the reply went.
      *
@@ -88,6 +112,12 @@ export function buzzBridge(options) {
             return;
         let posted = 0;
         for (const card of await Promise.all(cards.map((c) => sharedInChannel(c, speaker)))) {
+            const picture = isAgentScreenshot(card) ? await screenshotIn(relay, card, speaker) : null;
+            if (picture) {
+                if (relay.reply(channel, picture.content, replyTo, { mention: false, tags: picture.tags }))
+                    posted += 1;
+                continue;
+            }
             const content = cardMessage(card);
             if (content && relay.reply(channel, content, replyTo, { mention: false }))
                 posted += 1;
@@ -262,6 +292,49 @@ export function buzzBridge(options) {
         followers.get(conversation)?.abort();
         followers.delete(conversation);
     }
+    /**
+     * Edit each posted question whose requests just ended, so everyone who can
+     * see it reads how it ended and nobody is offered its buttons again.
+     *
+     * @remarks
+     * The plugin used to keep a pressed question's outcome only on the device
+     * that pressed it. In a shared channel everyone else, and the same person on
+     * another device, still saw Send it on an email that had gone. The prompt is
+     * the agent's own message and only its author may edit it, so the edit is
+     * the one record every client draws. Runs inside the conversation's queue.
+     */
+    function settlePrompts(relay, community, channel, settlements) {
+        const current = sessions.get(community, channel);
+        if (!current?.prompts?.length || settlements.size === 0)
+            return;
+        const { edits, open } = applySettlements(current.prompts, settlements, { carry, askerOnly });
+        for (const { eventId, content } of edits) {
+            if (relay.edit(channel, eventId, content))
+                log(`marked a question in ${channel.slice(0, 8)} as ${[...new Set(settlements.values())].map((s) => s.outcome).join(", ")}`);
+            else
+                log(`could not mark a question in ${channel.slice(0, 8)} as ended: not connected`);
+        }
+        const { prompts: _prompts, ...rest } = current;
+        sessions.set(community, channel, open.length ? { ...rest, prompts: open } : rest);
+    }
+    /** Every question still open in this conversation ends the same way: answered elsewhere, or no longer waited on. */
+    function settleOpenPrompts(relay, community, channel, outcome) {
+        const current = sessions.get(community, channel);
+        if (!current?.prompts?.length)
+            return;
+        settlePrompts(relay, community, channel, settleRemaining(current.prompts, { outcome, at: Date.now() }));
+    }
+    /** Remember a posted question, so it can be edited when it ends. */
+    function rememberPrompt(community, channel, prompt) {
+        const current = sessions.get(community, channel);
+        if (!current)
+            return;
+        sessions.set(community, channel, {
+            ...current,
+            promptEventIds: [...(current.promptEventIds ?? []), prompt.eventId],
+            prompts: [...(current.prompts ?? []), prompt],
+        });
+    }
     function startFollower(community, channel) {
         if (stopped)
             return;
@@ -286,28 +359,32 @@ export function buzzBridge(options) {
                 if (followers.get(conversation) !== controller)
                     return;
                 const current = sessions.get(community, channel);
+                // The follower began from a copy; who asked and what was posted are the store's.
+                const { prompts: _stale, asker: _staleAsker, ...fresh } = state;
+                const kept = {
+                    ...(current?.asker ? { asker: current.asker } : {}),
+                    ...(current?.prompts?.length ? { prompts: current.prompts } : {}),
+                };
                 if (state.pendingInputRequests?.length) {
-                    sessions.set(community, channel, { ...state, promptEventIds: current?.promptEventIds });
+                    sessions.set(community, channel, { ...fresh, ...kept, promptEventIds: current?.promptEventIds });
                     return;
                 }
                 if (current?.promptEventIds?.length)
                     relay.unwatchReplies(current.promptEventIds);
-                sessions.set(community, channel, state);
+                sessions.set(community, channel, { ...fresh, ...kept });
+                // Nothing is waiting on a person any more. A question the bridge did not see answered
+                // was answered elsewhere if the turn resumed, and is no longer waited on if it ended.
+                settleOpenPrompts(relay, community, channel, state.resumeInFlight ? "answered" : "withdrawn");
             }),
             onInputRequested: (requests) => serialize(community, channel, async () => {
                 if (followers.get(conversation) !== controller)
                     return;
-                const promptId = relay.reply(channel, formatInputRequests(requests, { carry: options.cards !== false }));
+                const asker = sessions.get(community, channel)?.asker;
+                const promptId = relay.reply(channel, formatInputRequests(requests, { carry, asker, askerOnly }));
                 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],
-                    });
-                }
+                rememberPrompt(community, channel, { eventId: promptId, requests, ...(asker ? { asker } : {}) });
                 log(`posted another input request in ${channel.slice(0, 8)}`);
             }),
             onMessage: (message, cards) => serialize(community, channel, async () => {
@@ -364,7 +441,8 @@ export function buzzBridge(options) {
                         return;
                     if (current.promptEventIds?.length)
                         relay.unwatchReplies(current.promptEventIds);
-                    const { pendingInputRequests: _p, resumeInFlight: _r, promptEventIds: _e, ...cleared } = current;
+                    settleOpenPrompts(relay, community, channel, "answered");
+                    const { pendingInputRequests: _p, resumeInFlight: _r, promptEventIds: _e, prompts: _q, ...cleared } = sessions.get(community, channel) ?? current;
                     sessions.set(community, channel, cleared);
                     relay.reply(channel, resumeStalledReply(agentWorkTimeoutMs));
                     log(`gave up on the resumed turn in ${channel.slice(0, 8)}: no progress past index ${retry.index}`);
@@ -430,6 +508,14 @@ export function buzzBridge(options) {
                 if (pending?.pendingInputRequests?.length) {
                     let responses;
                     const carried = readHiddenAnswers(text);
+                    if (askerOnly && pending.asker && !isAsker(pending.asker, event.pubkey, speaker.user.id)) {
+                        // Someone else's question. A remark in its thread is people talking, not an answer:
+                        // only a press, or a message that names the agent, is told whose answer it waits for.
+                        if (carried.length || addressed)
+                            relay.reply(channel, notTheAskerReply(pending.asker), event);
+                        log(`ignored an answer in ${channel.slice(0, 8)} from ${speaker.user.email}: the question is for someone else`);
+                        return;
+                    }
                     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.
@@ -466,6 +552,7 @@ export function buzzBridge(options) {
                     });
                     await respondToPendingConversation(session, responses);
                     log(`submitted ${responses.length} input response(s) in ${channel.slice(0, 8)}`);
+                    const settlements = settlementsFor(responses, pending.pendingInputRequests, speaker.user.displayName?.trim() || undefined);
                     /**
                      * The answer is in, so this conversation is no longer waiting on a
                      * person. It is waiting on the agent, and that is a thing the bridge
@@ -487,6 +574,7 @@ export function buzzBridge(options) {
                         const { pendingInputRequests: _resolved, ...rest } = answered;
                         sessions.set(from, channel, remaining.length ? { ...rest, pendingInputRequests: remaining } : { ...rest, resumeInFlight: true });
                     }
+                    settlePrompts(relay, from, channel, settlements);
                     return;
                 }
                 if (pending?.resumeInFlight) {
@@ -503,18 +591,19 @@ export function buzzBridge(options) {
                 const message = await composeMessage(text, attachments, (ref) => fetchMedia(key, ref), log);
                 const result = await answerTurn(clientFor(event.pubkey), sessions, channel, message, from, log, agentSilenceTimeoutMs, agentWorkTimeoutMs);
                 if (result.status === "waiting" && result.inputRequests.length > 0) {
+                    const name = speaker.user.displayName?.trim();
+                    const asker = { key: event.pubkey, ...(speaker.user.id ? { userId: speaker.user.id } : {}), ...(name ? { name } : {}) };
                     sessions.set(from, channel, {
                         id: result.sessionId,
                         streamIndex: result.streamIndex,
                         pendingInputRequests: result.inputRequests,
                         speakerPublicKey: event.pubkey,
+                        asker,
                     });
-                    const promptId = relay.reply(channel, formatInputRequests(result.inputRequests, { carry: options.cards !== false }), event);
+                    const promptId = relay.reply(channel, formatInputRequests(result.inputRequests, { carry, asker, askerOnly }), event);
                     if (promptId) {
                         relay.watchReplies([promptId]);
-                        const current = sessions.get(from, channel);
-                        if (current)
-                            sessions.set(from, channel, { ...current, promptEventIds: [promptId] });
+                        rememberPrompt(from, channel, { eventId: promptId, requests: result.inputRequests, asker });
                     }
                     log(`posted ${result.inputRequests.length} input request(s) in ${channel.slice(0, 8)}`);
                     startFollower(from, channel);

package/dist/cli.js

@@ -231,6 +231,7 @@ function run() {
             ? { agentWorkTimeoutMs: Number(process.env.BUZZ_AGENT_WORK_TIMEOUT_MS) }
             : {}),
         ...(process.env.BUZZ_CARDS === "off" ? { cards: false } : {}),
+        ...(process.env.BUZZ_ANSWERS === "anyone" ? { answers: "anyone" } : {}),
         ...(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS
             ? { agentSilenceTimeoutMs: Number(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS) }
             : {}),
@@ -424,6 +425,7 @@ else {
     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_ANSWERS=anyone             let anyone in a channel answer a question (default: only who asked)
     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,7 +1,18 @@
 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 AskAnswer, type AskSettled, type Card } from "@kybernesis/cards";
+import type { StoredAsker, StoredPrompt, StoredSession } from "./sessions.js";
 import { type TurnFailure } from "./turn.js";
+/** How a question is posted: who it is for, and which of its requests have ended. */
+export interface PromptOptions {
+    /** Carry each question hidden after the words, for the plugin. */
+    carry?: boolean;
+    /** The person whose message raised it. */
+    asker?: StoredAsker;
+    /** Only the asker may answer it. */
+    askerOnly?: boolean;
+    /** Requests that have ended, by request id: shown as how they ended, with nothing to answer. */
+    settled?: Readonly<Record<string, AskSettled>>;
+}
 /**
  * Render pending Eve input in a Buzz channel.
  *
@@ -11,10 +22,34 @@ import { type TurnFailure } from "./turn.js";
  * (`<!-- 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.
+ *
+ * The same text, with `settled`, is what the prompt is edited to once a
+ * question ends: how it ended and who ended it, then what it asked, and the
+ * question hidden as `kyb:settled` so no client offers to answer it again.
  */
-export declare function formatInputRequests(requests: readonly InputRequest[], options?: {
+export declare function formatInputRequests(requests: readonly InputRequest[], options?: PromptOptions): string;
+/** What someone other than the asker hears when they try to answer. */
+export declare function notTheAskerReply(asker: StoredAsker): string;
+/** Whether `pubkey`, resolved to `userId`, is the person a question is for. */
+export declare function isAsker(asker: StoredAsker, pubkey: string, userId?: string): boolean;
+/** How each response settles its request, said by `by`. */
+export declare function settlementsFor(responses: readonly InputResponse[], requests: readonly InputRequest[], by?: string, at?: number): Map<string, AskSettled>;
+/**
+ * Prompts with `settlements` applied: each one that changed, with the text it
+ * is edited to, and the prompts still waiting on something afterwards.
+ */
+export declare function applySettlements(prompts: readonly StoredPrompt[], settlements: ReadonlyMap<string, AskSettled>, options: {
     carry?: boolean;
-}): string;
+    askerOnly?: boolean;
+}): {
+    edits: {
+        eventId: string;
+        content: string;
+    }[];
+    open: StoredPrompt[];
+};
+/** Every request in `prompts` that has not ended yet, settled the same way. */
+export declare function settleRemaining(prompts: readonly StoredPrompt[], settled: AskSettled): Map<string, AskSettled>;
 /**
  * Answers a client pressed, checked against what is actually open.
  *

package/dist/hitl.js

@@ -1,5 +1,5 @@
 import { parseInputResponses, resolveTextToResponses, } from "eve/client";
-import { askFrom, askText, cardsOf, hiddenAsk, newStepState, readStep } from "@kybernesis/cards";
+import { askFrom, askText, cardsOf, hiddenAsk, hiddenSettled, newStepState, readStep, settledLine, settleWith, } from "@kybernesis/cards";
 import { failureFromEvent, silentTurnReply } from "./turn.js";
 /**
  * Render pending Eve input in a Buzz channel.
@@ -10,34 +10,113 @@ import { failureFromEvent, silentTurnReply } from "./turn.js";
  * (`<!-- 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.
+ *
+ * The same text, with `settled`, is what the prompt is edited to once a
+ * question ends: how it ended and who ended it, then what it asked, and the
+ * question hidden as `kyb:settled` so no client offers to answer it again.
  */
 export function formatInputRequests(requests, options = {}) {
-    const asks = requests.map((request) => askFrom(request));
+    const person = options.asker ? { key: options.asker.key, ...(options.asker.name ? { name: options.asker.name } : {}) } : undefined;
+    const only = Boolean(options.askerOnly && person);
+    const asks = requests.map((request) => ({
+        ...askFrom(request),
+        ...(person ? { asker: person } : {}),
+        ...(only ? { askerOnly: true } : {}),
+    }));
+    const settledOf = (ask) => options.settled?.[ask.requestId];
     const text = asks.map((ask, requestIndex) => {
         const request = requests[requestIndex];
         const prompt = askText(ask);
-        const lines = [
-            requests.length > 1 ? `Question ${requestIndex + 1}: ${prompt}` : prompt,
-        ];
+        const numbered = (line) => (requests.length > 1 ? `Question ${requestIndex + 1}: ${line}` : line);
+        const settled = settledOf(ask);
+        if (settled)
+            return [numbered(settledLine({ ...ask, settled })), "", prompt].join("\n");
+        const lines = [numbered(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}`;
             }));
         }
+        const who = only && person?.name ? `${person.name}, reply` : "Reply";
         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.");
+            lines.push("", `${who} 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.");
+            lines.push("", `${who} to this message with an option number, option ID, or exact label.`);
         }
         return lines.join("\n");
     }).join("\n\n");
     if (!options.carry)
         return text;
-    const hidden = asks.map((ask) => hiddenAsk(ask)).filter((h) => h !== null);
+    const hidden = asks
+        .map((ask) => {
+        const settled = settledOf(ask);
+        return settled ? hiddenSettled({ ...ask, settled }) : hiddenAsk(ask);
+    })
+        .filter((h) => h !== null);
     return hidden.length ? `${text}\n\n${hidden.join("\n")}` : text;
 }
+/** What someone other than the asker hears when they try to answer. */
+export function notTheAskerReply(asker) {
+    return `Only ${asker.name ?? "the person who asked"} can answer this one. I can take something new once it's answered.`;
+}
+/** Whether `pubkey`, resolved to `userId`, is the person a question is for. */
+export function isAsker(asker, pubkey, userId) {
+    return asker.key === pubkey || Boolean(asker.userId && userId && asker.userId === userId);
+}
+/** How each response settles its request, said by `by`. */
+export function settlementsFor(responses, requests, by, at = Date.now()) {
+    const open = new Map(requests.map((request) => [request.requestId, request]));
+    const out = new Map();
+    for (const response of responses) {
+        const request = open.get(response.requestId);
+        if (!request)
+            continue;
+        const answer = {
+            ...(response.optionId !== undefined ? { optionId: response.optionId } : {}),
+            ...(response.text !== undefined ? { text: response.text } : {}),
+        };
+        out.set(response.requestId, settleWith(askFrom(request), answer, by, at));
+    }
+    return out;
+}
+/**
+ * Prompts with `settlements` applied: each one that changed, with the text it
+ * is edited to, and the prompts still waiting on something afterwards.
+ */
+export function applySettlements(prompts, settlements, options) {
+    const edits = [];
+    const open = [];
+    for (const prompt of prompts) {
+        const fresh = prompt.requests.filter((request) => settlements.has(request.requestId) && !prompt.settled?.[request.requestId]);
+        let next = prompt;
+        if (fresh.length) {
+            const settled = { ...prompt.settled };
+            for (const request of fresh)
+                settled[request.requestId] = settlements.get(request.requestId);
+            next = { ...prompt, settled };
+            edits.push({
+                eventId: prompt.eventId,
+                content: formatInputRequests(prompt.requests, { carry: options.carry, asker: prompt.asker, askerOnly: options.askerOnly, settled }),
+            });
+        }
+        if (next.requests.some((request) => !next.settled?.[request.requestId]))
+            open.push(next);
+    }
+    return { edits, open };
+}
+/** Every request in `prompts` that has not ended yet, settled the same way. */
+export function settleRemaining(prompts, settled) {
+    const out = new Map();
+    for (const prompt of prompts) {
+        for (const request of prompt.requests) {
+            if (!prompt.settled?.[request.requestId])
+                out.set(request.requestId, settled);
+        }
+    }
+    return out;
+}
 /**
  * Answers a client pressed, checked against what is actually open.
  *

package/dist/pictures.d.ts

@@ -0,0 +1,26 @@
+import type { Card } from "@kybernesis/cards";
+import type { AgentKey } from "./keys.js";
+import { type UploadedMedia } from "./profile.js";
+export interface PictureMessage {
+    content: string;
+    tags: string[][];
+}
+export interface PictureOptions {
+    /** The agent's base URL, where the screenshot is served. */
+    agentUrl: string;
+    /** The asker's headers for the agent: the screenshot is theirs to read. */
+    headers: () => Promise<Record<string, string>>;
+    /** The community the message goes to: its media store holds the picture. */
+    relay: string;
+    key: AgentKey;
+    fetchImpl?: typeof fetch;
+    upload?: (relay: string, key: AgentKey, bytes: Uint8Array, mediaType: string) => Promise<UploadedMedia>;
+}
+/** Whether this card is a screenshot the bridge can carry as a picture. */
+export declare function isAgentScreenshot(card: Card): boolean;
+/**
+ * The screenshot card as a Buzz picture message, or null when it is not one
+ * the bridge carries. Throws when the picture cannot be fetched or stored; the
+ * caller then posts the card as it was.
+ */
+export declare function pictureMessage(card: Card, options: PictureOptions): Promise<PictureMessage | null>;

package/dist/pictures.js

@@ -0,0 +1,90 @@
+import { uploadMedia } from "./profile.js";
+/**
+ * A screenshot the agent showed someone, as a picture in the conversation.
+ *
+ * @remarks
+ * `show_screen` keeps the image on the agent's machine and names it by a path
+ * on the agent (`/eve/v1/kyb/screens/<id>.png`) that only the person it was
+ * taken for can read. KYBER Studio fetches it with that person's token. Buzz
+ * cannot: the cards plugin has no token, so it drew "This picture is on the
+ * agent and can't be shown here", and Buzz without the plugin showed only the
+ * caption.
+ *
+ * So the bridge fetches it, as the person who asked, and puts it in the
+ * community's own media store, which serves only members of that community.
+ * The message is an ordinary Buzz picture message (the words, a Markdown image
+ * and its `imeta` tag, as Buzz's own composer writes them), so every Buzz app
+ * draws it, with or without the plugin. Asking for a screenshot in a channel
+ * shares it with that channel, the same as an artifact posted there.
+ */
+/** The only address a screenshot card may name for the bridge to fetch: one on the agent, by id. */
+const SCREEN_PATH = /^\/eve\/v1\/kyb\/screens\/[0-9a-f]{32}(?:\.png)?$/;
+/** Larger than any screen; the community's own limit for images is higher still. */
+const MAX_BYTES = 20 * 1024 * 1024;
+/** Whether this card is a screenshot the bridge can carry as a picture. */
+export function isAgentScreenshot(card) {
+    if (card.card !== "screenshot" || !card.data || typeof card.data !== "object")
+        return false;
+    const image = card.data.image;
+    return typeof image === "string" && SCREEN_PATH.test(image);
+}
+/**
+ * The screenshot card as a Buzz picture message, or null when it is not one
+ * the bridge carries. Throws when the picture cannot be fetched or stored; the
+ * caller then posts the card as it was.
+ */
+export async function pictureMessage(card, options) {
+    if (!isAgentScreenshot(card))
+        return null;
+    const data = card.data;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const upload = options.upload ?? uploadMedia;
+    const response = await fetchImpl(`${options.agentUrl.replace(/\/$/, "")}${data.image}`, {
+        headers: await options.headers(),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!response.ok)
+        throw new Error(`${response.status} fetching the screenshot from the agent`);
+    if (Number(response.headers.get("content-length") ?? 0) > MAX_BYTES)
+        throw new Error("the screenshot is too large");
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const size = pngSize(bytes);
+    if (!size || bytes.byteLength > MAX_BYTES)
+        throw new Error("the agent did not answer with a PNG");
+    const stored = await upload(options.relay, options.key, bytes, "image/png");
+    const caption = typeof data.caption === "string" ? oneLine(data.caption) : "";
+    const site = typeof data.site === "string" ? oneLine(data.site) : "";
+    const words = caption && site ? `${caption} (${site})` : caption || site || "A screenshot from the agent's computer.";
+    return {
+        content: `${words}\n\n![${markdownLabel(caption || "Screenshot")}](<${stored.url}>)`,
+        tags: [
+            [
+                "imeta",
+                `url ${stored.url}`,
+                "m image/png",
+                `x ${stored.sha256}`,
+                `size ${stored.size}`,
+                `dim ${size.width}x${size.height}`,
+                "filename screenshot.png",
+            ],
+        ],
+    };
+}
+/** Width and height from a PNG's header, when the bytes are one. */
+function pngSize(bytes) {
+    if (bytes.length < 24 || bytes[0] !== 0x89 || bytes[1] !== 0x50 || bytes[2] !== 0x4e || bytes[3] !== 0x47)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const width = view.getUint32(16);
+    const height = view.getUint32(20);
+    return width > 0 && height > 0 ? { width, height } : null;
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, 200);
+}
+/** A Markdown image label, escaped the way Buzz escapes an attachment's name. */
+function markdownLabel(text) {
+    return Array.from(text, (char) => (char.charCodeAt(0) < 32 ? " " : char))
+        .join("")
+        .replace(/[\\`*_{}[\]()!<>&]/g, "\\$&");
+}

package/dist/profile.d.ts

@@ -46,6 +46,14 @@ export declare function copy(from: string, to: readonly string[], key: AgentKey)
  * up, and nobody should need a blob token to give their agent a face.
  */
 export declare function uploadImage(relay: string, key: AgentKey, bytes: Uint8Array, mediaType: string): Promise<string>;
+/** What a community's media store holds after an upload: what a message's `imeta` tag names. */
+export type UploadedMedia = {
+    url: string;
+    sha256: string;
+    size: number;
+};
+/** {@link uploadImage}, answering with the hash and size of what was stored too. */
+export declare function uploadMedia(relay: string, key: AgentKey, bytes: Uint8Array, mediaType: string): Promise<UploadedMedia>;
 /**
  * Remove everything from an image that is not the image.
  *

package/dist/profile.js

@@ -147,6 +147,10 @@ export async function copy(from, to, key) {
  * up, and nobody should need a blob token to give their agent a face.
  */
 export async function uploadImage(relay, key, bytes, mediaType) {
+    return (await uploadMedia(relay, key, bytes, mediaType)).url;
+}
+/** {@link uploadImage}, answering with the hash and size of what was stored too. */
+export async function uploadMedia(relay, key, bytes, mediaType) {
     const { createHash } = await import("node:crypto");
     const base = relay.replace(/^wss:/, "https:").replace(/^ws:/, "http:").replace(/\/$/, "");
     // Stripped BEFORE hashing: the hash has to be of what is actually sent, and a
@@ -183,10 +187,10 @@ export async function uploadImage(relay, key, bytes, mediaType) {
             body: body,
         });
         if (response.ok) {
-            const body = (await response.json().catch(() => ({})));
-            if (typeof body.url === "string")
-                return body.url;
-            return `${base}/${sha256}`;
+            const answer = (await response.json().catch(() => ({})));
+            // Absolute either way: a message names its picture by full address, and a server may answer with a path.
+            const url = typeof answer.url === "string" ? new URL(answer.url, `${base}/`).toString() : `${base}/${sha256}`;
+            return { url, sha256, size: body.byteLength };
         }
         last = `${response.status} ${(await response.text().catch(() => "")).slice(0, 120)}`;
     }

package/dist/relay.d.ts

@@ -15,6 +15,8 @@ import type { AgentKey } from "./keys.js";
 export declare const KIND_MESSAGE = 9;
 /** NIP-25 reaction. */
 export declare const KIND_REACTION = 7;
+/** A replacement edit of a message, by its author only (the relay enforces it). */
+export declare const KIND_EDIT = 40003;
 /** NIP-42 relay authentication. */
 export declare const KIND_AUTH = 22242;
 /** NIP-98 HTTP authentication. */
@@ -103,7 +105,8 @@ export declare class BuzzRelay {
     private discovery;
     /** Since when a newly found DM is read back, so a message sent before it was found is not lost. */
     private discoveredAt;
-    private readonly url;
+    /** The community's address, as configured. */
+    readonly url: string;
     private readonly rest;
     private readonly key;
     private readonly pollMs;
@@ -162,7 +165,15 @@ export declare class BuzzRelay {
     /** `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;
+        tags?: readonly string[][];
     }): string | null;
+    /**
+     * Replace the words of a message this agent posted. Every client shows the
+     * latest edit by the author, and only the author's edits count, so nobody
+     * else can make a message of the agent's say something else. No mention
+     * tag: an edit is not news, so nobody is notified again.
+     */
+    edit(channel: string, eventId: string, text: string): 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

@@ -16,6 +16,8 @@ import { finalizeEvent } from "nostr-tools/pure";
 export const KIND_MESSAGE = 9;
 /** NIP-25 reaction. */
 export const KIND_REACTION = 7;
+/** A replacement edit of a message, by its author only (the relay enforces it). */
+export const KIND_EDIT = 40003;
 /** NIP-42 relay authentication. */
 export const KIND_AUTH = 22242;
 /** NIP-98 HTTP authentication. */
@@ -102,6 +104,7 @@ export class BuzzRelay {
     discovery = null;
     /** Since when a newly found DM is read back, so a message sent before it was found is not lost. */
     discoveredAt = null;
+    /** The community's address, as configured. */
     url;
     rest;
     key;
@@ -425,7 +428,7 @@ export class BuzzRelay {
         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))
+        if (this.closed || !this.socket || ![KIND_MESSAGE, KIND_REACTION, KIND_EDIT].includes(event.kind))
             return null;
         if (this.outbox.length >= MAX_OUTBOX)
             this.outbox.shift();
@@ -473,8 +476,20 @@ export class BuzzRelay {
             if (options.mention !== false)
                 tags.push(["p", replyTo.pubkey]);
         }
+        // Attachments (`imeta`), which the words name.
+        for (const tag of options.tags ?? [])
+            tags.push([...tag]);
         return this.publish({ kind: KIND_MESSAGE, tags, content: text });
     }
+    /**
+     * Replace the words of a message this agent posted. Every client shows the
+     * latest edit by the author, and only the author's edits count, so nobody
+     * else can make a message of the agent's say something else. No mention
+     * tag: an edit is not news, so nobody is notified again.
+     */
+    edit(channel, eventId, text) {
+        return this.publish({ kind: KIND_EDIT, tags: [["h", channel], ["e", eventId]], content: text });
+    }
     /** Sign one HTTP request as this agent (NIP-98), binding the signature to the body. */
     httpAuth(url, body) {
         const auth = finalizeEvent({

package/dist/sessions.d.ts

@@ -1,4 +1,20 @@
+import type { AskSettled } from "@kybernesis/cards";
 import type { InputRequest } from "eve/client";
+/** The person whose message raised a question: their chat key, account and name. */
+export interface StoredAsker {
+    key: string;
+    /** Their control-plane account, so another device of theirs counts as them. */
+    userId?: string;
+    name?: string;
+}
+/** A question the bridge posted, kept until every request in it has settled, so it can be rewritten. */
+export interface StoredPrompt {
+    eventId: string;
+    requests: readonly InputRequest[];
+    asker?: StoredAsker;
+    /** Requests that have ended, by request id. */
+    settled?: Readonly<Record<string, AskSettled>>;
+}
 /** One conversation: which eve session it is, and how far the bridge has read. */
 export interface StoredSession {
     id: string;
@@ -14,6 +30,10 @@ export interface StoredSession {
      * counts as an answer whether or not it mentions this agent.
      */
     promptEventIds?: readonly string[];
+    /** Who the open questions are for. Absent on conversations from before 0.15: anyone may answer those. */
+    asker?: StoredAsker;
+    /** The posted questions not yet fully settled, so the bridge can rewrite each one when it ends. */
+    prompts?: readonly StoredPrompt[];
     /** When it was last used, so a store that runs for years does not grow forever. */
     updated: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.14.0",
+  "version": "0.16.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.5.0",
+    "@kybernesis/cards": "^0.6.0",
     "@kybernesis/enterprise": "^0.10.0",
     "nostr-tools": "^2.10.0",
     "zod": "^4"