@kybernesis/buzz 0.9.6 → 0.9.9

package/dist/bridge.d.ts

@@ -31,6 +31,8 @@ export declare function buzzBridge(options: BuzzBridgeOptions): {
     pubkey: string;
     /** The communities this agent is a member of. */
     relays: string[];
+    /** Where this bridge declares itself for the management routes to read. */
+    surfaceFile: string;
     start(): void;
     /** Say goodbye rather than letting presence lapse: a stopped agent should not look online. */
     stop(): void;

package/dist/bridge.js

@@ -1,9 +1,10 @@
 import { channelIdentity } from "@kybernesis/enterprise";
 import { fetchMedia, parseMedia } from "./media.js";
 import { speakerCredentials } from "./credentials.js";
+import { surfaceWriter } from "./surface.js";
 import { SessionStore } from "./sessions.js";
 import { agentSilenceReply, answerTurn, composeMessage, DEFAULT_AGENT_SILENCE_TIMEOUT_MS, DEFAULT_AGENT_WORK_TIMEOUT_MS, describeSilentTurn, rejectedTurnReply, silentTurnReply, validateAgentSilenceTimeoutMs, } from "./turn.js";
-import { followPendingConversation, formatInputRequests, invalidInputReply, needsPendingFollower, resolveInputReply, respondToPendingConversation, } from "./hitl.js";
+import { followPendingConversation, followerRetryDelayMs, formatInputRequests, invalidInputReply, needsPendingFollower, resolveInputReply, respondToPendingConversation, resumeStalledReply, } from "./hitl.js";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { Client } from "eve/client";
@@ -178,6 +179,14 @@ export function buzzBridge(options) {
     /** One abortable durable-stream follower owns each parked conversation. */
     const followers = new Map();
     const followerRestartTimers = new Map();
+    /**
+     * Why a follower keeps reattaching, per conversation.
+     *
+     * `index` is the durable cursor it last reattached at. The cursor moving is
+     * the only honest evidence that anything is happening: KYB-545's spin held a
+     * frozen index across 25 minutes of retries while the room was told nothing.
+     */
+    const followerRetries = new Map();
     let stopped = false;
     function clearFollowerRestart(conversation) {
         const timer = followerRestartTimers.get(conversation);
@@ -188,6 +197,7 @@ export function buzzBridge(options) {
     function stopFollower(community, channel) {
         const conversation = SessionStore.key(community, channel);
         clearFollowerRestart(conversation);
+        followerRetries.delete(conversation);
         followers.get(conversation)?.abort();
         followers.delete(conversation);
     }
@@ -257,13 +267,42 @@ export function buzzBridge(options) {
             if (followers.get(conversation) === controller)
                 followers.delete(conversation);
             const recoverable = sessions.get(community, channel);
-            if (!controller.signal.aborted && recoverable && needsPendingFollower(recoverable)) {
-                const timer = setTimeout(() => {
-                    followerRestartTimers.delete(conversation);
-                    startFollower(community, channel);
-                }, 1_000);
-                followerRestartTimers.set(conversation, timer);
+            if (controller.signal.aborted || !recoverable || !needsPendingFollower(recoverable)) {
+                followerRetries.delete(conversation);
+                return;
             }
+            const previous = followerRetries.get(conversation);
+            const progressed = previous === undefined || recoverable.streamIndex > previous.index;
+            const retry = progressed
+                ? { cycles: 0, index: recoverable.streamIndex, since: Date.now() }
+                : { ...previous, cycles: previous.cycles + 1 };
+            followerRetries.set(conversation, retry);
+            /**
+             * A resumed turn is the agent working, so it answers to the same ceiling
+             * a live turn does. A question nobody has answered yet is not: a person
+             * may reply tomorrow, and waiting for them is the entire point. Only the
+             * first case can be a stall, and only it gives up.
+             */
+            if (recoverable.resumeInFlight && Date.now() - retry.since >= agentWorkTimeoutMs) {
+                followerRetries.delete(conversation);
+                void serialize(community, channel, async () => {
+                    const current = sessions.get(community, channel);
+                    if (!current || !needsPendingFollower(current))
+                        return;
+                    if (current.promptEventIds?.length)
+                        relay.unwatchReplies(current.promptEventIds);
+                    const { pendingInputRequests: _p, resumeInFlight: _r, promptEventIds: _e, ...cleared } = 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}`);
+                });
+                return;
+            }
+            const timer = setTimeout(() => {
+                followerRestartTimers.delete(conversation);
+                startFollower(community, channel);
+            }, followerRetryDelayMs(retry.cycles));
+            followerRestartTimers.set(conversation, timer);
         });
     }
     async function handle(event, from) {
@@ -328,6 +367,24 @@ export function buzzBridge(options) {
                     });
                     await respondToPendingConversation(session, responses, from, channel);
                     log(`submitted ${responses.length} input response(s) in ${channel.slice(0, 8)}`);
+                    /**
+                     * The answer is in, so this conversation is no longer waiting on a
+                     * person. It is waiting on the agent, and that is a thing the bridge
+                     * may time out.
+                     *
+                     * Recording it here rather than leaving it to the follower's
+                     * `input.resolved` is what makes a stalled resume detectable at all.
+                     * In KYB-545 the follower could not reach the agent, so it never saw
+                     * that event, and the store still read "one question pending" an hour
+                     * after the person had answered. Nothing may ever time out a wait for
+                     * a human, so while that flag was set the room could only be told
+                     * nothing.
+                     */
+                    const answered = sessions.get(from, channel);
+                    if (answered?.pendingInputRequests?.length) {
+                        const { pendingInputRequests: _resolved, ...rest } = answered;
+                        sessions.set(from, channel, { ...rest, resumeInFlight: true });
+                    }
                     return;
                 }
                 if (pending?.resumeInFlight) {
@@ -401,14 +458,19 @@ export function buzzBridge(options) {
             stopTyping();
         }
     }
+    // What this bridge is, for the consoles: see surface.ts.
+    const surface = surfaceWriter({ relays: urls, npub: key.npub, conversations: () => sessions.size }, log);
     return {
         /** The key the workspace has to invite for any of this to happen. */
         npub: key.npub,
         pubkey: key.publicKey,
         /** The communities this agent is a member of. */
         relays: urls,
+        /** Where this bridge declares itself for the management routes to read. */
+        surfaceFile: surface.file,
         start() {
             stopped = false;
+            surface.start();
             for (const relay of relays.values())
                 relay.connect();
             for (const { community, channel, session } of sessions.entries()) {
@@ -426,6 +488,7 @@ export function buzzBridge(options) {
         /** Say goodbye rather than letting presence lapse: a stopped agent should not look online. */
         stop() {
             stopped = true;
+            surface.stop();
             for (const controller of followers.values())
                 controller.abort();
             followers.clear();

package/dist/hitl.d.ts

@@ -8,6 +8,26 @@ export declare function resolveInputReply(text: string, requests: readonly Input
 export declare function invalidInputReply(requests: readonly InputRequest[]): string;
 /** Submit a matched reply without consuming its response stream. */
 export declare function respondToPendingConversation(session: Pick<ClientSession, "respond">, responses: readonly InputResponse[], community: string, channel: string): Promise<void>;
+/**
+ * How long a follower waits between reattaching when it saw no progress.
+ *
+ * @remarks
+ * The follower used to reattach on a flat one-second timer. With eve's client
+ * spending about 100 s on an idle stream before giving up, that produced the
+ * fixed ~110 s cycle observed in KYB-545: forever, for as long as the process
+ * lived. Backing off turns a spin into a wait, and the cap keeps a genuinely
+ * slow resume from being abandoned for minutes at a time.
+ */
+export declare function followerRetryDelayMs(cycles: number, capMs?: number): number;
+/**
+ * What the room is told when a resumed turn produced nothing for too long.
+ *
+ * @remarks
+ * KYB-529's rule applied to the resumed phase: the person committed attention
+ * to answering a question, so silence is the one outcome they must not get.
+ * Say the answer arrived, say the work did not, and say the channel is usable.
+ */
+export declare function resumeStalledReply(stallMs: number): string;
 /** A session needs its follower while asking or while resumed output is unpublished. */
 export declare function needsPendingFollower(session: Pick<StoredSession, "pendingInputRequests" | "resumeInFlight">): boolean;
 export interface PendingFollowerCallbacks {

package/dist/hitl.js

@@ -38,6 +38,34 @@ export async function respondToPendingConversation(session, responses, community
         streamReconnectPolicy: { reconnect: false },
     });
 }
+/**
+ * How long a follower waits between reattaching when it saw no progress.
+ *
+ * @remarks
+ * The follower used to reattach on a flat one-second timer. With eve's client
+ * spending about 100 s on an idle stream before giving up, that produced the
+ * fixed ~110 s cycle observed in KYB-545: forever, for as long as the process
+ * lived. Backing off turns a spin into a wait, and the cap keeps a genuinely
+ * slow resume from being abandoned for minutes at a time.
+ */
+export function followerRetryDelayMs(cycles, capMs = 60_000) {
+    const safeCycles = Number.isFinite(cycles) ? Math.max(0, Math.trunc(cycles)) : 0;
+    return Math.min(1_000 * 2 ** Math.min(safeCycles, 30), capMs);
+}
+/**
+ * What the room is told when a resumed turn produced nothing for too long.
+ *
+ * @remarks
+ * KYB-529's rule applied to the resumed phase: the person committed attention
+ * to answering a question, so silence is the one outcome they must not get.
+ * Say the answer arrived, say the work did not, and say the channel is usable.
+ */
+export function resumeStalledReply(stallMs) {
+    const minutes = Math.max(1, Math.round(stallMs / 60_000));
+    return (`Your answer reached me, but the turn it restarted then went quiet for over ${minutes} minute` +
+        `${minutes === 1 ? "" : "s"} without producing anything, so I have stopped waiting on it. ` +
+        `Nothing was posted and no work landed from it. This channel is clear — ask me again and I will start fresh.`);
+}
 /** A session needs its follower while asking or while resumed output is unpublished. */
 export function needsPendingFollower(session) {
     return Boolean(session.pendingInputRequests?.length || session.resumeInFlight);

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { BuzzRelay, type NostrEvent, type PresenceStatus, type RelayOptions, KIN
 export { asHexPubkey, loadKey, loadOrCreateKey, npubEncode, type AgentKey } from "./keys.js";
 export * as profile from "./profile.js";
 export type { Profile } from "./profile.js";
+export { readSurfaceManifest, surfaceWriter, surfacesDir, type SurfaceManifest } from "./surface.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export { buzzBridge } from "./bridge.js";
 export { BuzzRelay, KIND_MESSAGE, KIND_REACTION, KIND_PRESENCE, KIND_TYPING, KIND_DM_OPEN, } from "./relay.js";
 export { asHexPubkey, loadKey, loadOrCreateKey, npubEncode } from "./keys.js";
 export * as profile from "./profile.js";
+export { readSurfaceManifest, surfaceWriter, surfacesDir } from "./surface.js";

package/dist/surface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The bridge, declaring itself.
+ *
+ * eve's `/eve/v1/info` lists the channels an agent authored; a workspace bridge
+ * is a separate process the agent knows nothing about, so every console showed
+ * an agent that was plainly answering in a workspace as reachable "only through
+ * this app". Rather than have a console guess from process names, the bridge
+ * writes one small file saying what it is connected to and touches it every
+ * minute. Anything that reads the file — the agent's management routes, and
+ * through them the desktop and the phone — can tell a live bridge from a stale
+ * file by the heartbeat alone.
+ */
+export declare const HEARTBEAT_MS = 60000;
+/** Where every surface on this host writes its manifest; the management routes read the same directory. */
+export declare function surfacesDir(): string;
+export interface SurfaceManifest {
+    kind: "buzz";
+    name: string;
+    /** The workspaces this bridge is connected to. */
+    relays: string[];
+    /** The key the workspace invited. */
+    npub: string;
+    /** Channels with a live conversation. */
+    conversations: number;
+    pid: number;
+    startedAt: string;
+    heartbeatAt: string;
+}
+export interface SurfaceWriter {
+    /** Write the manifest now and keep its heartbeat fresh until `stop()`. */
+    start(): void;
+    /** Refresh what the manifest says, without waiting for the next beat. */
+    update(patch: Partial<Pick<SurfaceManifest, "conversations">>): void;
+    /** Remove the manifest: a stopped bridge should not look like a stale one. */
+    stop(): void;
+    readonly file: string;
+}
+export declare function surfaceWriter(input: {
+    relays: string[];
+    npub: string;
+    conversations(): number;
+    dir?: string;
+}, onError?: (message: string) => void): SurfaceWriter;
+/** Read one manifest back; null when it is not one. */
+export declare function readSurfaceManifest(file: string): SurfaceManifest | null;

package/dist/surface.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * The bridge, declaring itself.
+ *
+ * eve's `/eve/v1/info` lists the channels an agent authored; a workspace bridge
+ * is a separate process the agent knows nothing about, so every console showed
+ * an agent that was plainly answering in a workspace as reachable "only through
+ * this app". Rather than have a console guess from process names, the bridge
+ * writes one small file saying what it is connected to and touches it every
+ * minute. Anything that reads the file — the agent's management routes, and
+ * through them the desktop and the phone — can tell a live bridge from a stale
+ * file by the heartbeat alone.
+ */
+export const HEARTBEAT_MS = 60_000;
+/** Where every surface on this host writes its manifest; the management routes read the same directory. */
+export function surfacesDir() {
+    return process.env.KYB_SURFACES_DIR ?? join(homedir(), ".kybernesis", "surfaces");
+}
+export function surfaceWriter(input, onError = () => undefined) {
+    const dir = input.dir ?? surfacesDir();
+    // One file per connection set, so two bridges on one host for different workspaces do not overwrite each other.
+    const file = join(dir, `buzz-${input.npub.slice(-8)}.json`);
+    const startedAt = new Date().toISOString();
+    let timer;
+    const write = () => {
+        const manifest = {
+            kind: "buzz",
+            name: "Buzz",
+            relays: input.relays,
+            npub: input.npub,
+            conversations: input.conversations(),
+            pid: process.pid,
+            startedAt,
+            heartbeatAt: new Date().toISOString(),
+        };
+        try {
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(file, JSON.stringify(manifest, null, 2) + "\n");
+        }
+        catch (error) {
+            // A manifest that cannot be written costs a row on a console, not a conversation.
+            onError(`could not write surface manifest ${file}: ${error.message}`);
+        }
+    };
+    return {
+        file,
+        start() {
+            write();
+            timer = setInterval(write, HEARTBEAT_MS);
+            timer.unref?.();
+        },
+        update() {
+            write();
+        },
+        stop() {
+            if (timer)
+                clearInterval(timer);
+            timer = undefined;
+            try {
+                if (existsSync(file))
+                    unlinkSync(file);
+            }
+            catch {
+                /* a stale file is told apart by its heartbeat anyway */
+            }
+        },
+    };
+}
+/** Read one manifest back; null when it is not one. */
+export function readSurfaceManifest(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed.kind !== "buzz" || !Array.isArray(parsed.relays) || typeof parsed.heartbeatAt !== "string")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/turn.d.ts

@@ -101,5 +101,15 @@ export declare function answerTurn(client: Client, sessions: SessionStore, chann
  */
 export declare function isSessionGone(error: unknown): boolean;
 export declare function rejectedTurnReply(error: unknown): string | null;
-/** Give the originating channel one accurate recovery message for bridge-owned silence. */
+/**
+ * Give the originating channel one accurate recovery message for bridge-owned silence.
+ *
+ * Two different failures wear the same timeout. Before the send, a stalled
+ * unread drain means the message never reached the agent: "try again here" is
+ * actively wrong, because there is nothing to resume and the agent will answer
+ * whatever it last genuinely received — a confident reply to a question nobody
+ * asked. After the send, the message did reach the agent and the conversation
+ * is kept, so trying again is the right advice. The phase on the error tells
+ * the two apart.
+ */
 export declare function agentSilenceReply(error: unknown): string | null;

package/dist/turn.js

@@ -17,6 +17,16 @@ export const DEFAULT_AGENT_SILENCE_TIMEOUT_MS = 5 * 60_000;
  */
 export const DEFAULT_AGENT_WORK_TIMEOUT_MS = 60 * 60_000;
 const isWorkPhase = (phase) => phase.endsWith("response stream");
+/**
+ * A phase that runs BEFORE the message is sent to the agent.
+ *
+ * The unread drain runs before the send, so a timeout here means the message
+ * never reached the agent and no run was created. Every other phase — the
+ * send/create acknowledgement and the response stream — is after the POST that
+ * delivers it, so by then the agent has the message. This is the difference
+ * between a lost message and a lost turn, and the recovery text turns on it.
+ */
+const isPreSendPhase = (phase) => phase === "unread drain";
 /** A caller-owned inactivity timeout. Aborting the transport does not cancel the eve session. */
 export class AgentSilenceTimeoutError extends Error {
     phase;
@@ -405,9 +415,22 @@ export function rejectedTurnReply(error) {
         ? `I couldn't read that message (${detail}). Try sending it again, or as plain text.`
         : "I couldn't read that message. Try sending it again, or as plain text.";
 }
-/** Give the originating channel one accurate recovery message for bridge-owned silence. */
+/**
+ * Give the originating channel one accurate recovery message for bridge-owned silence.
+ *
+ * Two different failures wear the same timeout. Before the send, a stalled
+ * unread drain means the message never reached the agent: "try again here" is
+ * actively wrong, because there is nothing to resume and the agent will answer
+ * whatever it last genuinely received — a confident reply to a question nobody
+ * asked. After the send, the message did reach the agent and the conversation
+ * is kept, so trying again is the right advice. The phase on the error tells
+ * the two apart.
+ */
 export function agentSilenceReply(error) {
     if (!(error instanceof AgentSilenceTimeoutError))
         return null;
+    if (isPreSendPhase(error.phase)) {
+        return "I couldn't get your message to the agent before it went quiet, so it was not delivered — nothing was sent and no answer is coming. Please send it again.";
+    }
     return "The agent was silent for too long, so I stopped waiting. I kept this conversation, and you can try again here.";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.9.6",
+  "version": "0.9.9",
   "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",