@kybernesis/buzz 0.12.2 → 0.13.0

package/README.md

@@ -81,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 |
@@ -91,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) => {
@@ -422,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,
@@ -432,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

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

package/dist/hitl.d.ts

@@ -1,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/relay.d.ts

@@ -144,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

@@ -425,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 });
     }

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.2",
+  "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"