@kybernesis/buzz 0.4.4 → 0.5.1

package/dist/bridge.js

@@ -1,4 +1,5 @@
 import { channelIdentity } from "@kybernesis/enterprise";
+import { speakerCredentials } from "./credentials.js";
 import { Client } from "eve/client";
 import { BuzzRelay } from "./relay.js";
 import { loadKey, npubEncode } from "./keys.js";
@@ -50,21 +51,83 @@ export function buzzBridge(options) {
     const sessions = new Map();
     /** Who has already been sent a link, so a room full of strangers is not a room full of spam. */
     const invited = new Map();
-    const clientFor = (token, bundle) => 
-    // `host`, not `baseUrl`: a wrong key is ignored rather than rejected, and the client then
-    // builds a nonsense URL — an error about a malformed URL rather than about a mistyped option.
-    new Client({
-        host: options.agentUrl,
-        auth: { bearer: token },
-        headers: bundle ? { "x-kybernesis-bundle": bundle } : {},
-    });
-    async function ask(channel, text, token, bundle) {
-        // Built per turn, for the person whose turn it is.
-        const client = clientFor(token, bundle);
+    /**
+     * A client whose credentials are resolved per request, not captured once.
+     *
+     * The identity token a turn starts with lives about five minutes. That was
+     * invisible while turns ended early — and became a failure the moment they
+     * were allowed to run to completion: a turn doing real work for six minutes
+     * reconnected its stream with the token it began with, the agent answered
+     * "Authorization is required for this route", and the reply was lost after
+     * all the work had been done. In a channel that reads as the agent typing
+     * for five minutes and then saying nothing.
+     *
+     * Resolving per request costs nothing in the normal case — the resolver
+     * caches and re-mints only near expiry — and it keeps the property the short
+     * lifetime exists for: a person whose access is revoked mid-turn stops being
+     * able to act on the next request rather than at the end of the turn.
+     */
+    const credentialsFor = speakerCredentials((externalId) => identity.resolve(PROVIDER, externalId, npubEncode(externalId)));
+    const clientFor = (pubkey) => {
+        const credentials = credentialsFor(pubkey);
+        // `host`, not `baseUrl`: a wrong key is ignored rather than rejected, and the client then
+        // builds a nonsense URL — an error about a malformed URL rather than about a mistyped option.
+        return new Client({
+            host: options.agentUrl,
+            auth: { bearer: credentials.bearer },
+            headers: credentials.headers,
+        });
+    };
+    /**
+     * One turn at a time per channel.
+     *
+     * Two people asking at once used to interleave: both turns read and wrote the
+     * same stored stream position, so one of them read the other's boundary and
+     * came back with the wrong answer or none. A channel is a conversation; its
+     * turns are ordered whether or not the people in it take turns.
+     */
+    const inFlight = new Map();
+    function serialize(channel, work) {
+        const queued = (inFlight.get(channel) ?? Promise.resolve()).then(work, work);
+        // Kept only while it matters: the chain holds the LAST promise, not a history.
+        inFlight.set(channel, queued.catch(() => { }));
+        return queued;
+    }
+    async function ask(channel, text, pubkey) {
+        // Built per turn, for the person whose turn it is — and kept current for as
+        // long as that turn runs.
+        const client = clientFor(pubkey);
         const existing = sessions.get(channel);
         if (existing) {
             try {
                 const session = client.sessions.attach(existing.id, { streamIndex: existing.streamIndex });
+                /**
+                 * Move to the true end of the conversation before speaking.
+                 *
+                 * `send()` opens its response stream at the position the handle already
+                 * holds and stops at the FIRST turn boundary it meets. If anything is
+                 * still unread there — the tail of a turn that outlived its reader, a
+                 * turn that was running when the bridge restarted — that boundary
+                 * belongs to the older turn. The read ends on it, this turn's answer is
+                 * never collected, and the stored position stays one turn behind.
+                 *
+                 * Which makes it permanent: every later turn reads the previous turn's
+                 * tail. The channel answers nothing, then answers a question from ten
+                 * minutes ago, and a fresh conversation elsewhere works perfectly —
+                 * because a fresh conversation has nothing left over to trip on.
+                 *
+                 * Draining first costs one bounded read of only what is unread, and it
+                 * repairs a position that has already drifted rather than requiring
+                 * anyone to notice. Non-following, so it ends at the tail instead of
+                 * waiting for the future.
+                 */
+                let unread = 0;
+                for await (const _ of session.stream({ follow: false, startIndex: existing.streamIndex })) {
+                    unread += 1;
+                }
+                if (unread > 0) {
+                    log(`caught up on ${unread} unread event(s) in ${channel.slice(0, 8)} before answering`);
+                }
                 const response = await session.send(text);
                 const result = await response.result();
                 // Where this turn left the conversation, so the next one starts after it.
@@ -170,9 +233,18 @@ export function buzzBridge(options) {
         void relay.react(event.id, SEEN);
         const stopTyping = relay.typingIn(channel);
         try {
-            const reply = await ask(channel, text, speaker.token, speaker.bundle);
+            const reply = await serialize(channel, () => ask(channel, text, event.pubkey));
             if (!reply) {
-                log("the agent produced no text");
+                /**
+                 * Silence is the worst answer available.
+                 *
+                 * An empty result used to end here, with a line in a log nobody was
+                 * reading. In a room that is indistinguishable from the agent ignoring
+                 * you — so people ask again, which is how one unanswered question
+                 * became five, none of which looked like a fault to anyone watching.
+                 */
+                log(`no text for ${channel.slice(0, 8)} — telling them rather than going quiet`);
+                relay.reply(channel, "I didn't get an answer back for that one — ask me again and I'll retry.", event);
                 return;
             }
             relay.reply(channel, reply, event);

package/dist/credentials.d.ts

@@ -0,0 +1,25 @@
+import type { SpeakerResolution } from "@kybernesis/enterprise";
+/** What the eve client needs to authenticate one person's turn. */
+export interface SpeakerCredentials {
+    /** Bearer resolver — called by the client before every HTTP request. */
+    bearer: () => Promise<string>;
+    /** Header resolver, for the same reason and on the same schedule. */
+    headers: () => Promise<Readonly<Record<string, string>>>;
+}
+/**
+ * Credentials for a turn, resolved per request rather than captured once.
+ *
+ * @remarks
+ * An identity token lives about five minutes. That was invisible while turns
+ * ended early, and became a failure the moment they ran to completion: a turn
+ * doing six minutes of real work reconnected its stream with the token it began
+ * with, the agent answered "Authorization is required for this route", and the
+ * reply was lost after every tool call had already succeeded. In a channel that
+ * reads as the agent typing for five minutes and then saying nothing at all.
+ *
+ * Resolving per request costs nothing in the normal case, because the resolver
+ * caches and re-mints only near expiry. It also preserves the property the
+ * short lifetime exists for: access withdrawn mid-turn stops the next request
+ * rather than being noticed after the work is done.
+ */
+export declare function speakerCredentials(resolve: (externalId: string) => Promise<SpeakerResolution>): (externalId: string) => SpeakerCredentials;

package/dist/credentials.js

@@ -0,0 +1,36 @@
+/**
+ * Credentials for a turn, resolved per request rather than captured once.
+ *
+ * @remarks
+ * An identity token lives about five minutes. That was invisible while turns
+ * ended early, and became a failure the moment they ran to completion: a turn
+ * doing six minutes of real work reconnected its stream with the token it began
+ * with, the agent answered "Authorization is required for this route", and the
+ * reply was lost after every tool call had already succeeded. In a channel that
+ * reads as the agent typing for five minutes and then saying nothing at all.
+ *
+ * Resolving per request costs nothing in the normal case, because the resolver
+ * caches and re-mints only near expiry. It also preserves the property the
+ * short lifetime exists for: access withdrawn mid-turn stops the next request
+ * rather than being noticed after the work is done.
+ */
+export function speakerCredentials(resolve) {
+    return (externalId) => {
+        const current = async () => {
+            const speaker = await resolve(externalId);
+            if (!speaker.linked) {
+                // Failing here is the point: the alternative is finishing a turn with a
+                // credential the control plane has already withdrawn.
+                throw new Error(`no longer authorized (${speaker.reason})`);
+            }
+            return { token: speaker.token, bundle: speaker.bundle };
+        };
+        return {
+            bearer: async () => (await current()).token,
+            headers: async () => {
+                const { bundle } = await current();
+                return bundle ? { "x-kybernesis-bundle": bundle } : {};
+            },
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.4.4",
+  "version": "0.5.1",
   "description": "Put an eve agent in a Buzz workspace as a member: per-speaker verified identity resolved through the control plane, self-service identity linking, presence, typing and seen signals.",
   "license": "Apache-2.0",
   "type": "module",