@kybernesis/buzz 0.12.1 → 0.13.0

package/README.md

@@ -27,6 +27,16 @@ of the account it names, so it is delivered to a direct conversation and never p
 Administrators can also link identities directly in the control plane, which is the path for
 bulk provisioning.
 
+## When it answers
+
+In a room, when someone @mentions it, or replies to a question it asked. In a one-to-one direct
+message, every message: a DM is addressed to the other member, mention or not, as with Buzz's
+own agents. A group DM still needs the mention. The bridge learns which DMs it is in from the
+relay's signed channel rosters, every thirty seconds, and reads a newly found DM back from the
+last check so nothing sent in between is missed. Messages written by another agent (they carry
+an owner attestation) are answered only when they mention it, so two agents in a DM never
+answer each other forever.
+
 ## What the host holds
 
 Only the agent's own key and the agent's own credential — neither of which can act as any
@@ -61,8 +71,9 @@ NIP-05 handle). The bridge reads the owner's choice from the control plane
 (`GET /api/agent/profile`, with the agent's credential) and the name's public profile document
 (`https://<name>.agentid.dev/.well-known/agent-profile.json`) when it starts and every fifteen
 minutes, and writes the profile only in communities whose copy differs. The control plane holds
-the picture as a small image, so it is uploaded to a community's own media store once per change
-and that address is used everywhere. A new picture or name reaches every community without a
+the picture as a small image, so it is uploaded to each community's own media store once per
+change, and each community's profile points at its own copy: the Buzz app loads a community's
+media only through that community, so a picture held by another one shows as no picture. A new picture or name reaches every community without a
 command on the host. The `.agent` name comes from `ARP_AGENT_DID`, or from
 `.eve/arp-identity.json` in the agent's directory.
 
@@ -70,6 +81,20 @@ 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.
+
 ## Configuration
 
 | Variable | Meaning |
@@ -80,6 +105,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 (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,12 @@ 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. Default true; false posts the reply alone, as before 0.13.
+     */
+    cards?: boolean;
     onLog?: (message: string) => void;
 };
 export declare function buzzBridge(options: BuzzBridgeOptions): {

package/dist/bridge.js

@@ -1,3 +1,4 @@
+import { cardMessage, cardText } from "@kybernesis/cards";
 import { channelIdentity } from "@kybernesis/enterprise";
 import { fetchMedia, parseMedia } from "./media.js";
 import { speakerCredentials } from "./credentials.js";
@@ -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.
      *
@@ -249,12 +310,14 @@ 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);
             }),
             onLog: log,
         }, controller.signal).catch((error) => {
@@ -318,7 +381,11 @@ export function buzzBridge(options) {
         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))
+        // 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.
+        const direct = Boolean(channel && relay.isDirect(channel) && !event.tags.some((t) => t[0] === "auth"));
+        if (!channel || !(addressed || answersPrompt || direct))
             return;
         const text = String(event.content ?? "").trim();
         const attachments = parseMedia(event);
@@ -418,6 +485,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,
@@ -428,6 +499,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

@@ -157,9 +157,11 @@ async function setProfile() {
         console.error("   or: kybernesis-buzz profile --copy-from <wss://…>");
         process.exit(1);
     }
-    // A local file is uploaded to the community and becomes a URL; a URL is used
-    // as given. Nobody should need storage of their own to give an agent a face.
+    // A local file is uploaded to each community and becomes that community's URL; a URL is
+    // used as given. Each community needs its own copy: the Buzz app loads a community's media
+    // only through that community, so another community's address shows no picture at all.
     let picture = flag("picture");
+    const pictures = new Map();
     if (picture && !/^https?:\/\//.test(picture)) {
         const path = picture.startsWith("~/")
             ? join(homedir(), picture.slice(2))
@@ -169,22 +171,20 @@ async function setProfile() {
             process.exit(1);
         }
         const bytes = readFileSync(path);
-        let uploaded;
         for (const url of urls) {
             try {
-                uploaded = await profile.uploadImage(url, key, bytes, profile.mediaTypeOf(path));
+                pictures.set(url, await profile.uploadImage(url, key, bytes, profile.mediaTypeOf(path)));
                 console.log(`  uploaded ${path.split("/").pop()} to ${url}`);
-                break;
             }
             catch (error) {
                 console.log(`  · ${url} — ${error.message}`);
             }
         }
-        if (!uploaded) {
+        if (pictures.size === 0) {
             console.error("\n  Could not upload the image to any community.\n");
             process.exit(1);
         }
-        picture = uploaded;
+        picture = undefined;
     }
     const wanted = {
         name: name.toLowerCase().replace(/\s+/g, "-"),
@@ -200,7 +200,9 @@ async function setProfile() {
     let published = 0;
     for (const url of urls) {
         try {
-            await profile.write(url, key, wanted);
+            // A community that refused the upload still gets a picture, if not one it can show.
+            const own = pictures.get(url) ?? pictures.values().next().value;
+            await profile.write(url, key, own ? { ...wanted, picture: own } : wanted);
             console.log(`  ✓ ${url}`);
             published += 1;
         }
@@ -228,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) }
             : {}),
@@ -420,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/face.d.ts

@@ -57,15 +57,22 @@ export declare function resolveFace(options: {
 }): Promise<Face>;
 /** The profile fields the face decides, given where its picture now lives. */
 export declare function profileFromFace(face: Face, pictureUrl: string | null): Profile;
+/** The hash a community media URL addresses (`…/media/<sha256>[.ext]`), or null for any other URL. */
+export declare function relayMediaHash(url: string): string | null;
 /**
  * Bring this agent's profile in every community in line with its face.
  *
  * @remarks
  * Each community is read first; only one whose copy differs is written, so running this on a
- * timer costs one read per community when nothing has changed. A picture is uploaded at most
- * once per change, to the first community that takes it, and that address is used everywhere,
- * the way `kybernesis-buzz profile --picture` always has. Fields the face does not decide are
- * kept. A community that refuses or cannot be reached is reported, not fatal.
+ * timer costs one read per community when nothing has changed. Fields the face does not decide
+ * are kept. A community that refuses or cannot be reached is reported, not fatal.
+ *
+ * Every community gets its OWN copy of the picture. A community's media store refuses
+ * anonymous reads, so the Buzz app loads a picture through the session of the community it is
+ * showing, and only when the address is that community's. An address on another community is
+ * fetched anonymously and refused, and the agent shows no face there: that is how an agent in
+ * two communities lost its picture in one of them when the app changed. So the picture is
+ * uploaded to each community that does not already hold it, and each profile points at its own.
  */
 export declare function syncProfile(options: {
     face: Face;
@@ -74,5 +81,10 @@ export declare function syncProfile(options: {
     read?: typeof profile.read;
     write?: typeof profile.write;
     upload?: typeof profile.uploadImage;
+    /** Reads a picture held in one community's media store, to copy it to another. */
+    fetchBlob?: (url: string, sha256: string) => Promise<{
+        bytes: Uint8Array;
+        mediaType: string;
+    }>;
 }): Promise<SyncOutcome[]>;
 export {};

package/dist/face.js

@@ -77,21 +77,48 @@ export function profileFromFace(face, pictureUrl) {
         bot: true,
     };
 }
+/** A relay's own HTTP origin, where its media store answers. */
+function originOf(relay) {
+    return relay.replace(/^wss:/, "https:").replace(/^ws:/, "http:").replace(/\/+$/, "");
+}
+/** The hash a community media URL addresses (`…/media/<sha256>[.ext]`), or null for any other URL. */
+export function relayMediaHash(url) {
+    try {
+        return /^\/media\/([0-9a-f]{64})(?:\.[a-z0-9]{1,8})?$/.exec(new URL(url).pathname)?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a URL is this community's own copy of the blob with this hash. */
+function heldBy(relay, url, sha256) {
+    return Boolean(url?.startsWith(`${originOf(relay)}/media/`) && relayMediaHash(url) === sha256);
+}
 /**
  * Bring this agent's profile in every community in line with its face.
  *
  * @remarks
  * Each community is read first; only one whose copy differs is written, so running this on a
- * timer costs one read per community when nothing has changed. A picture is uploaded at most
- * once per change, to the first community that takes it, and that address is used everywhere,
- * the way `kybernesis-buzz profile --picture` always has. Fields the face does not decide are
- * kept. A community that refuses or cannot be reached is reported, not fatal.
+ * timer costs one read per community when nothing has changed. Fields the face does not decide
+ * are kept. A community that refuses or cannot be reached is reported, not fatal.
+ *
+ * Every community gets its OWN copy of the picture. A community's media store refuses
+ * anonymous reads, so the Buzz app loads a picture through the session of the community it is
+ * showing, and only when the address is that community's. An address on another community is
+ * fetched anonymously and refused, and the agent shows no face there: that is how an agent in
+ * two communities lost its picture in one of them when the app changed. So the picture is
+ * uploaded to each community that does not already hold it, and each profile points at its own.
  */
 export async function syncProfile(options) {
     const read = options.read ?? profile.read;
     const write = options.write ?? profile.write;
     const upload = options.upload ?? profile.uploadImage;
     const { face, key } = options;
+    const fetchBlob = options.fetchBlob ??
+        (async (url, sha256) => {
+            const { fetchMedia } = await import("./media.js");
+            return fetchMedia(key, { url, sha256 });
+        });
     const current = new Map();
     const outcomes = new Map();
     for (const relay of options.relays) {
@@ -103,33 +130,52 @@ export async function syncProfile(options) {
             outcomes.set(relay, { relay, outcome: why.includes("not a relay member") ? "not-member" : "failed", detail: why });
         }
     }
-    // Where the picture lives. Null leaves each community's picture as it is.
-    let pictureUrl = null;
+    // What the picture is. An ordinary https address is used as it is, everywhere. A data URL,
+    // or a picture already in some community's media store, is copied into each community.
+    let external = null;
+    let sha256 = null;
+    let source = null;
+    let bytes = null;
     let pictureProblem = null;
-    if (face.picture && /^https:\/\//.test(face.picture)) {
-        pictureUrl = face.picture;
-    }
-    else if (face.picture) {
+    if (face.picture?.startsWith("data:")) {
         const picture = await pictureBytes(face.picture);
-        if (!picture) {
-            pictureProblem = "the picture is not an image this can send";
+        if (picture) {
+            sha256 = picture.sha256;
+            bytes = picture;
         }
         else {
-            pictureUrl = [...current.values()].map((p) => p?.picture).find((url) => url?.includes(picture.sha256)) ?? null;
-            for (const relay of current.keys()) {
-                if (pictureUrl)
-                    break;
-                try {
-                    pictureUrl = await upload(relay, key, picture.bytes, picture.mediaType);
-                }
-                catch (error) {
-                    pictureProblem = error.message;
-                }
-            }
+            pictureProblem = "the picture is not an image this can send";
+        }
+    }
+    else if (face.picture && /^https:\/\//.test(face.picture)) {
+        sha256 = relayMediaHash(face.picture);
+        if (sha256)
+            source = face.picture;
+        else
+            external = face.picture;
+    }
+    /** Where this community's copy of the picture lives; null leaves its picture as it is. */
+    async function pictureFor(relay) {
+        if (external)
+            return { url: external, problem: null };
+        if (!sha256)
+            return { url: null, problem: pictureProblem };
+        const existing = current.get(relay)?.picture;
+        if (heldBy(relay, existing, sha256))
+            return { url: existing, problem: null };
+        if (source && heldBy(relay, source, sha256))
+            return { url: source, problem: null };
+        try {
+            bytes ??= await fetchBlob(source, sha256);
+            return { url: await upload(relay, key, bytes.bytes, bytes.mediaType), problem: null };
+        }
+        catch (error) {
+            return { url: null, problem: error.message };
         }
     }
-    const wanted = profileFromFace(face, pictureUrl);
     for (const [relay, existing] of current) {
+        const picture = await pictureFor(relay);
+        const wanted = profileFromFace(face, picture.url);
         const matches = existing && Object.keys(wanted).every((field) => existing[field] === wanted[field]);
         if (matches) {
             outcomes.set(relay, { relay, outcome: "unchanged" });
@@ -137,7 +183,7 @@ export async function syncProfile(options) {
         }
         try {
             await write(relay, key, { ...(existing ?? {}), ...wanted });
-            outcomes.set(relay, { relay, outcome: "updated", ...(pictureProblem ? { detail: `picture not sent: ${pictureProblem}` } : {}) });
+            outcomes.set(relay, { relay, outcome: "updated", ...(picture.problem ? { detail: `picture not sent: ${picture.problem}` } : {}) });
         }
         catch (error) {
             const why = error.message;

package/dist/hitl.d.ts

@@ -1,4 +1,5 @@
 import { type ClientSession, type InputRequest, type InputResponse } from "eve/client";
+import { type Card } from "@kybernesis/cards";
 import type { StoredSession } from "./sessions.js";
 /**
  * Render pending Eve input in a text-only Buzz channel.
@@ -39,7 +40,8 @@ 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>;
     onLog?: (message: string) => void;
 }
 type MutableStoredSession = Omit<StoredSession, "updated">;

package/dist/hitl.js

@@ -1,5 +1,5 @@
 import { resolveTextToResponses, } from "eve/client";
-import { promptText } from "@kybernesis/cards";
+import { cardsOf, newStepState, promptText, readStep } from "@kybernesis/cards";
 /**
  * Render pending Eve input in a text-only Buzz channel.
  *
@@ -105,6 +105,7 @@ export async function followPendingConversation(session, initial, callbacks, sig
     let state = { ...initial };
     let streamIndex = initial.streamIndex;
     let completedMessage = "";
+    let steps = newStepState();
     const persist = async () => {
         state = { ...state, streamIndex };
         await callbacks.onState(state);
@@ -113,8 +114,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 +132,11 @@ 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);
         switch (streamEvent.type) {
             case "input.requested":
                 completedMessage = "";
+                steps = newStepState();
                 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.

package/dist/media.d.ts

@@ -44,5 +44,7 @@ export declare function parseMedia(event: NostrEvent): MediaRef[];
  * us one, so the authorisation is scoped to reading that specific blob.
  */
 export declare function fetchMedia(key: AgentKey, ref: MediaRef, fetchImpl?: typeof fetch): Promise<FetchedMedia>;
+/** How long a Blossom proof may live under NIP-FI's strict rules. */
+export declare const BLOSSOM_PROOF_SECONDS = 60;
 /** Whether the model can be shown this directly, or only told about it. */
 export declare function isImage(mediaType: string): boolean;

package/dist/media.js

@@ -47,14 +47,17 @@ export function parseMedia(event) {
  * us one, so the authorisation is scoped to reading that specific blob.
  */
 export async function fetchMedia(key, ref, fetchImpl = fetch) {
-    const expires = Math.floor(Date.now() / 1000) + 300;
+    // NIP-FI's strict Blossom rules, which a community may switch on: a proof lives at most a
+    // minute and names the server it is for. Older servers accept the same proof.
+    const issued = Math.floor(Date.now() / 1000);
     const auth = finalizeEvent({
         kind: 24242,
-        created_at: Math.floor(Date.now() / 1000),
+        created_at: issued,
         tags: [
             ["t", "get"],
             ...(ref.sha256 ? [["x", ref.sha256]] : []),
-            ["expiration", String(expires)],
+            ["expiration", String(issued + BLOSSOM_PROOF_SECONDS)],
+            ...serverTag(ref.url),
         ],
         content: "Fetch buzz-media",
     }, key.secretKey);
@@ -79,6 +82,17 @@ export async function fetchMedia(key, ref, fetchImpl = fetch) {
     }
     return { url: ref.url, mediaType, bytes };
 }
+/** How long a Blossom proof may live under NIP-FI's strict rules. */
+export const BLOSSOM_PROOF_SECONDS = 60;
+/** The `server` tag a strict Blossom server requires: the host the proof is for. */
+function serverTag(url) {
+    try {
+        return [["server", new URL(url).host]];
+    }
+    catch {
+        return [];
+    }
+}
 /** Whether the model can be shown this directly, or only told about it. */
 export function isImage(mediaType) {
     return mediaType.startsWith("image/");

package/dist/profile.js

@@ -153,7 +153,9 @@ export async function uploadImage(relay, key, bytes, mediaType) {
     // Blossom server checks that for itself.
     const body = stripMetadata(bytes, mediaType);
     const sha256 = createHash("sha256").update(body).digest("hex");
-    const expires = now() + 300;
+    // At most a minute: NIP-FI's strict Blossom rules, which a community may switch on, refuse
+    // a longer-lived proof. The `server` tag below is the other thing they require.
+    const expires = now() + 60;
     const auth = finalizeEvent({
         kind: 24242,
         created_at: now(),

package/dist/relay.d.ts

@@ -25,6 +25,10 @@ export declare const KIND_PRESENCE = 20001;
 export declare const KIND_TYPING = 20002;
 /** Open (or find) a direct conversation with a set of people. */
 export declare const KIND_DM_OPEN = 41010;
+/** Relay-signed channel metadata (NIP-29); its first `t` tag is the channel type. */
+export declare const KIND_CHANNEL_METADATA = 39000;
+/** Relay-signed channel roster (NIP-29): one `p` tag per member. */
+export declare const KIND_CHANNEL_MEMBERS = 39002;
 /**
  * A receiving client expires a typing indicator shortly after the event's own timestamp, so
  * anything slower than that has to keep saying so.
@@ -33,6 +37,8 @@ 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;
+/** How often to re-read which direct conversations this agent is in. */
+export declare const DIRECT_REFRESH_MS = 30000;
 export type NostrEvent = {
     id: string;
     pubkey: string;
@@ -66,6 +72,26 @@ export declare class BuzzRelay {
     private cursor;
     /** Prompts this agent posted; replies to them are polled for even when they carry no mention. */
     private readonly replyWatch;
+    /**
+     * One-to-one direct conversations this agent is in, by channel id.
+     *
+     * @remarks
+     * A direct message used to reach the bridge because the client tagged every other
+     * participant, so the `#p` poll found it like a mention. The current Buzz app tags only
+     * explicit mentions, so a person typing to the agent in a DM was never seen: the agent
+     * answered in a DM only when named, which is not how anyone talks to one person. Buzz's own
+     * agents decide by the channel instead (a DM of exactly two members is addressed to the
+     * other one), and so does this: the relay's signed rosters say which DMs the agent is in,
+     * and those channels are polled whole.
+     */
+    private direct;
+    /** The relay's own signing key (NIP-11 `self`), which every roster must carry. */
+    private relaySelf;
+    private discoveryTimer;
+    /** One discovery at a time: rosters first, then the metadata for those channels. */
+    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;
     private readonly rest;
     private readonly key;
@@ -78,6 +104,8 @@ export declare class BuzzRelay {
     watchReplies(ids: Iterable<string>): void;
     unwatchReplies(ids: Iterable<string>): void;
     connect(): void;
+    /** Whether this channel is a one-to-one DM with this agent: every message in it is addressed. */
+    isDirect(channel: string): boolean;
     close(): void;
     private reconnect;
     private receive;
@@ -92,6 +120,20 @@ export declare class BuzzRelay {
      * ignores every message addressed to it.
      */
     poll(): void;
+    /**
+     * Find the one-to-one DMs this agent is in: its rosters, then which of those channels are DMs.
+     *
+     * @remarks
+     * Rosters and metadata are relay-signed; anything else claiming to be one is ignored, so a
+     * member cannot publish a roster that makes the agent answer every message in a room.
+     */
+    private discoverDirect;
+    /** NIP-11 `self`: null when the relay names none, undefined when it could not be asked. */
+    private relayKey;
+    private discovered;
+    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(event: {
         kind: number;
@@ -102,7 +144,10 @@ export declare class BuzzRelay {
     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

@@ -26,6 +26,10 @@ export const KIND_PRESENCE = 20001;
 export const KIND_TYPING = 20002;
 /** Open (or find) a direct conversation with a set of people. */
 export const KIND_DM_OPEN = 41010;
+/** Relay-signed channel metadata (NIP-29); its first `t` tag is the channel type. */
+export const KIND_CHANNEL_METADATA = 39000;
+/** Relay-signed channel roster (NIP-29): one `p` tag per member. */
+export const KIND_CHANNEL_MEMBERS = 39002;
 /**
  * A receiving client expires a typing indicator shortly after the event's own timestamp, so
  * anything slower than that has to keep saying so.
@@ -34,6 +38,11 @@ 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;
+/** 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. */
+const IDS_PER_FILTER = 200;
+const MAX_FILTERS = 8;
 const now = () => Math.floor(Date.now() / 1000);
 /**
  * The payload out of a command acknowledgement.
@@ -62,6 +71,26 @@ export class BuzzRelay {
     cursor = now();
     /** Prompts this agent posted; replies to them are polled for even when they carry no mention. */
     replyWatch = new Set();
+    /**
+     * One-to-one direct conversations this agent is in, by channel id.
+     *
+     * @remarks
+     * A direct message used to reach the bridge because the client tagged every other
+     * participant, so the `#p` poll found it like a mention. The current Buzz app tags only
+     * explicit mentions, so a person typing to the agent in a DM was never seen: the agent
+     * answered in a DM only when named, which is not how anyone talks to one person. Buzz's own
+     * agents decide by the channel instead (a DM of exactly two members is addressed to the
+     * other one), and so does this: the relay's signed rosters say which DMs the agent is in,
+     * and those channels are polled whole.
+     */
+    direct = new Set();
+    /** The relay's own signing key (NIP-11 `self`), which every roster must carry. */
+    relaySelf = undefined;
+    discoveryTimer = null;
+    /** One discovery at a time: rosters first, then the metadata for those channels. */
+    discovery = null;
+    /** Since when a newly found DM is read back, so a message sent before it was found is not lost. */
+    discoveredAt = null;
     url;
     rest;
     key;
@@ -106,6 +135,10 @@ export class BuzzRelay {
             }
         });
     }
+    /** Whether this channel is a one-to-one DM with this agent: every message in it is addressed. */
+    isDirect(channel) {
+        return this.direct.has(channel);
+    }
     close() {
         this.closed = true;
         if (this.presenceTimer)
@@ -114,9 +147,12 @@ export class BuzzRelay {
             clearTimeout(this.pollTimer);
         if (this.reconnectTimer)
             clearTimeout(this.reconnectTimer);
+        if (this.discoveryTimer)
+            clearTimeout(this.discoveryTimer);
         this.presenceTimer = null;
         this.pollTimer = null;
         this.reconnectTimer = null;
+        this.discoveryTimer = null;
         try {
             this.socket?.close();
         }
@@ -131,8 +167,12 @@ export class BuzzRelay {
             clearInterval(this.presenceTimer);
         if (this.pollTimer)
             clearTimeout(this.pollTimer);
+        if (this.discoveryTimer)
+            clearTimeout(this.discoveryTimer);
         this.presenceTimer = null;
         this.pollTimer = null;
+        this.discoveryTimer = null;
+        this.discovery = null;
         if (this.reconnectTimer)
             return;
         // Backs off rather than hammering. A membership refusal is the common case
@@ -190,6 +230,7 @@ export class BuzzRelay {
             this.refusal = null;
             this.log(`authenticated as ${this.key.publicKey.slice(0, 12)}…`);
             this.keepPresent();
+            this.discoverDirect();
             this.poll();
             return;
         }
@@ -197,10 +238,20 @@ export class BuzzRelay {
             // One poll's worth delivered. Closing it matters: the relay caps how many subscriptions one
             // connection may hold, and a bridge that never closes them stops receiving within minutes.
             this.send(["CLOSE", String(frame[1])]);
+            this.discoveryDone(String(frame[1]));
+            return;
+        }
+        if (type === "CLOSED") {
+            // A refused discovery must not wedge the next one.
+            this.discoveryDone(String(frame[1]), true);
             return;
         }
         if (type !== "EVENT")
             return;
+        if (this.discovery && (frame[1] === this.discovery.rosterSub || frame[1] === this.discovery.metadataSub)) {
+            this.discovered(frame[2]);
+            return;
+        }
         const event = frame[2];
         if (!event || event.pubkey === this.key.publicKey)
             return;
@@ -243,9 +294,116 @@ export class BuzzRelay {
         if (this.replyWatch.size > 0) {
             filters.push({ kinds: [KIND_MESSAGE], "#e": [...this.replyWatch], since: this.cursor });
         }
+        for (const ids of chunks([...this.direct], MAX_FILTERS - filters.length)) {
+            filters.push({ kinds: [KIND_MESSAGE], "#h": ids, since: this.cursor });
+        }
         this.send(["REQ", `m${Date.now()}`, ...filters]);
         this.pollTimer = setTimeout(() => this.poll(), this.pollMs);
     }
+    /**
+     * Find the one-to-one DMs this agent is in: its rosters, then which of those channels are DMs.
+     *
+     * @remarks
+     * Rosters and metadata are relay-signed; anything else claiming to be one is ignored, so a
+     * member cannot publish a roster that makes the agent answer every message in a room.
+     */
+    discoverDirect() {
+        if (this.closed)
+            return;
+        if (this.discoveryTimer)
+            clearTimeout(this.discoveryTimer);
+        this.discoveryTimer = setTimeout(() => this.discoverDirect(), DIRECT_REFRESH_MS);
+        if (this.discovery && now() - this.discovery.startedAt < 60)
+            return;
+        void this.relayKey().then((self) => {
+            if (this.closed || self === undefined)
+                return;
+            const rosterSub = `r${Date.now()}`;
+            this.discovery = { rosterSub, metadataSub: null, rosters: new Map(), dms: new Set(), startedAt: now() };
+            this.send(["REQ", rosterSub, { kinds: [KIND_CHANNEL_MEMBERS], "#p": [this.key.publicKey], limit: 1000 }]);
+        });
+    }
+    /** NIP-11 `self`: null when the relay names none, undefined when it could not be asked. */
+    async relayKey() {
+        if (this.relaySelf !== undefined)
+            return this.relaySelf;
+        try {
+            const response = await fetch(this.rest, {
+                headers: { accept: "application/nostr+json" },
+                signal: AbortSignal.timeout(10_000),
+            });
+            const info = (await response.json());
+            const self = [info.self, info.pubkey].find((value) => typeof value === "string" && /^[0-9a-f]{64}$/.test(value));
+            this.relaySelf = self ?? null;
+        }
+        catch (error) {
+            this.log(`could not read the relay's information document (${error.message}); direct messages wait for the next try`);
+        }
+        return this.relaySelf;
+    }
+    discovered(event) {
+        const discovery = this.discovery;
+        if (!discovery || !event)
+            return;
+        if (this.relaySelf && event.pubkey !== this.relaySelf)
+            return;
+        const id = event.tags.find((t) => t[0] === "d")?.[1];
+        if (!id)
+            return;
+        if (event.kind === KIND_CHANNEL_MEMBERS) {
+            discovery.rosters.set(id, new Set(event.tags.filter((t) => t[0] === "p" && t[1]).map((t) => t[1])));
+            return;
+        }
+        // NIP-29 as Buzz writes it: the FIRST `t` is the channel's type; later ones are labels.
+        const type = event.tags.find((t) => t[0] === "t")?.[1];
+        const members = discovery.rosters.get(id);
+        if (event.kind === KIND_CHANNEL_METADATA && type === "dm" && members?.size === 2 && members.has(this.key.publicKey)) {
+            discovery.dms.add(id);
+        }
+    }
+    discoveryDone(sub, refused = false) {
+        const discovery = this.discovery;
+        if (!discovery)
+            return;
+        if (refused) {
+            // Only a subscription still in flight can be refused. This relay answers every CLOSE we
+            // send with a CLOSED of its own, so the roster's echo arrives after the metadata request
+            // has gone out; treating it as a refusal dropped every discovery.
+            const inFlight = discovery.metadataSub === null ? discovery.rosterSub : discovery.metadataSub;
+            if (sub === inFlight)
+                this.discovery = null;
+            return;
+        }
+        if (sub === discovery.rosterSub) {
+            const ids = [...discovery.rosters.keys()];
+            if (ids.length === 0)
+                return this.adopt(new Set());
+            discovery.metadataSub = `g${Date.now()}`;
+            this.send([
+                "REQ",
+                discovery.metadataSub,
+                ...chunks(ids, MAX_FILTERS).map((chunk) => ({ kinds: [KIND_CHANNEL_METADATA], "#d": chunk })),
+            ]);
+            return;
+        }
+        if (sub === discovery.metadataSub)
+            this.adopt(discovery.dms);
+    }
+    /** Take the DMs just found; read back any that are new, from when they could last have been missed. */
+    adopt(found) {
+        // Overlap the last discovery by a few seconds; the first one starts where polling did.
+        const since = this.discoveredAt === null ? this.cursor : this.discoveredAt - 5;
+        const fresh = [...found].filter((id) => !this.direct.has(id));
+        this.direct = new Set(found);
+        this.discovery = null;
+        this.discoveredAt = now();
+        if (fresh.length > 0) {
+            this.log(`direct messages: ${found.size} conversation(s), ${fresh.length} new`);
+            // The poll's cursor may already be past a message sent in a DM before it was found.
+            const filters = chunks(fresh, MAX_FILTERS).map((ids) => ({ kinds: [KIND_MESSAGE], "#h": ids, since }));
+            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(event) {
         const signed = finalizeEvent({ created_at: now(), ...event }, this.key.secretKey);
@@ -267,10 +425,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 });
     }
@@ -345,3 +506,11 @@ export class BuzzRelay {
         }
     }
 }
+/** Split ids into at most `max` filters' worth; ids beyond that are dropped, never a filter too many. */
+function chunks(ids, max) {
+    const out = [];
+    for (let at = 0; at < ids.length && out.length < max; at += IDS_PER_FILTER) {
+        out.push(ids.slice(at, at + IDS_PER_FILTER));
+    }
+    return out;
+}

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: {

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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.12.1",
+  "version": "0.13.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.4.0",
     "@kybernesis/enterprise": "^0.10.0",
     "nostr-tools": "^2.10.0",
     "zod": "^4"