@kybernesis/buzz 0.9.2 → 0.9.3

package/README.md

@@ -61,6 +61,7 @@ sessions are keyed by channel.
 | `BUZZ_AGENT_URL` | Where the agent listens (default `http://127.0.0.1:8000`) |
 | `BUZZ_KEYFILE` | The agent's key (default `~/.kybernesis/buzz-agent.json`) |
 | `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 while opening an agent request or waiting between complete events (default `300000`, five minutes; not a total turn-duration limit) |
 | `KYBERNESIS_ISSUER` | The control plane |
 | `KYBERNESIS_AGENT_CREDENTIAL` | This agent's credential |
 
@@ -78,6 +79,7 @@ const bridge = buzzBridge({
   keyFile: "/etc/agent/buzz.json",
   issuer: process.env.KYBERNESIS_ISSUER!,
   credential: process.env.KYBERNESIS_AGENT_CREDENTIAL!,
+  agentSilenceTimeoutMs: 5 * 60_000,
 });
 
 console.log(`invite ${bridge.npub}`);

package/dist/bridge.d.ts

@@ -19,6 +19,8 @@ export type BuzzBridgeOptions = {
     /** This agent's credential from the control plane. The only durable secret here. */
     credential: string;
     pollMs?: number;
+    /** Maximum silence during one agent request or event stream; defaults to five minutes. */
+    agentSilenceTimeoutMs?: number;
     onLog?: (message: string) => void;
 };
 export declare function buzzBridge(options: BuzzBridgeOptions): {

package/dist/bridge.js

@@ -2,7 +2,7 @@ import { channelIdentity } from "@kybernesis/enterprise";
 import { fetchMedia, parseMedia } from "./media.js";
 import { speakerCredentials } from "./credentials.js";
 import { SessionStore } from "./sessions.js";
-import { answerTurn, composeMessage, rejectedTurnReply } from "./turn.js";
+import { agentSilenceReply, answerTurn, composeMessage, DEFAULT_AGENT_SILENCE_TIMEOUT_MS, describeSilentTurn, rejectedTurnReply, silentTurnReply, validateAgentSilenceTimeoutMs, } from "./turn.js";
 import { followPendingConversation, formatInputRequests, invalidInputReply, needsPendingFollower, resolveInputReply, respondToPendingConversation, } from "./hitl.js";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -31,6 +31,7 @@ export function buzzBridge(options) {
     const key = loadKey(options.keyFile);
     const identity = channelIdentity({ issuer: options.issuer, credential: options.credential });
     const log = options.onLog ?? ((message) => console.log(new Date().toISOString().slice(11, 19), message));
+    const agentSilenceTimeoutMs = validateAgentSilenceTimeoutMs(options.agentSilenceTimeoutMs ?? DEFAULT_AGENT_SILENCE_TIMEOUT_MS);
     /**
      * One conversation per channel — the SESSION ID, not a handle to it.
      *
@@ -340,7 +341,7 @@ export function buzzBridge(options) {
                 }
                 /** Images become file parts; unreadable files become explicit model context. */
                 const message = await composeMessage(text, attachments, (ref) => fetchMedia(key, ref), log);
-                const result = await answerTurn(clientFor(event.pubkey), sessions, channel, message, from, log);
+                const result = await answerTurn(clientFor(event.pubkey), sessions, channel, message, from, log, agentSilenceTimeoutMs);
                 if (result.status === "waiting" && result.inputRequests.length > 0) {
                     sessions.set(from, channel, {
                         id: result.sessionId,
@@ -360,8 +361,11 @@ export function buzzBridge(options) {
                     return;
                 }
                 if (!result.message) {
-                    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);
+                    // 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,
+                    // the plain sentence. Three faults used to read as one (KYB-529).
+                    log(`${describeSilentTurn(result.failures)} for ${channel.slice(0, 8)} — telling them rather than going quiet`);
+                    relay.reply(channel, silentTurnReply(result.failures), event);
                     return;
                 }
                 relay.reply(channel, result.message, event);
@@ -377,6 +381,13 @@ export function buzzBridge(options) {
                 startFollower(from, channel);
                 return;
             }
+            const silence = agentSilenceReply(error);
+            if (silence) {
+                const timeout = error;
+                log(`agent silence timeout for ${channel.slice(0, 8)} during ${timeout.phase} after ${timeout.intervalMs}ms`);
+                relay.reply(channel, silence, event);
+                return;
+            }
             const rejected = rejectedTurnReply(error);
             if (rejected) {
                 log(`turn rejected for ${channel.slice(0, 8)}: ${error.message}`);

package/dist/cli.js

@@ -137,6 +137,9 @@ function run() {
         issuer: env("KYBERNESIS_ISSUER", "https://agent.kybernesis.ai"),
         credential: env("KYBERNESIS_AGENT_CREDENTIAL"),
         ...(process.env.BUZZ_POLL_MS ? { pollMs: Number(process.env.BUZZ_POLL_MS) } : {}),
+        ...(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS
+            ? { agentSilenceTimeoutMs: Number(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS) }
+            : {}),
     });
     for (const signal of ["SIGINT", "SIGTERM"]) {
         process.on(signal, () => {
@@ -295,6 +298,7 @@ else {
     BUZZ_AGENT_URL                 where the agent listens (default http://127.0.0.1:8000)
     BUZZ_KEYFILE                   this agent's key (default ~/.kybernesis/buzz-agent.json)
     BUZZ_SESSIONS_FILE             channel-to-session continuity store
+    BUZZ_AGENT_SILENCE_TIMEOUT_MS   maximum agent silence (default 300000ms)
     KYBERNESIS_ISSUER              the control plane
     KYBERNESIS_AGENT_CREDENTIAL    this agent's credential
 `);

package/dist/turn.d.ts

@@ -1,8 +1,39 @@
 import { type Client, type InputRequest, type MessageResult, type SendTurnInput } from "eve/client";
 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. */
+export declare const DEFAULT_AGENT_SILENCE_TIMEOUT_MS: number;
+export type AgentSilencePhase = "unread drain" | "send acknowledgement" | "response stream" | "create acknowledgement" | "create response stream";
+/** A caller-owned inactivity timeout. Aborting the transport does not cancel the eve session. */
+export declare class AgentSilenceTimeoutError extends Error {
+    readonly phase: AgentSilencePhase;
+    readonly intervalMs: number;
+    constructor(phase: AgentSilencePhase, intervalMs: number);
+}
+/** Refuse invalid values before starting a bridge with an ineffective watchdog. */
+export declare function validateAgentSilenceTimeoutMs(value: number): number;
 /** A message shape accepted by the certified eve client's send contract. */
 export type TurnMessage = SendTurnInput["message"];
+/**
+ * One thing that went wrong inside a turn, as the session stream reported it.
+ *
+ * A turn where every tool call fails ends with no assistant text and no
+ * turn-level error: eve logs `tool execution failed` and finishes. From the
+ * channel that was the same silence as an overloaded model or a dead process,
+ * and on one deployment it took an hour to tell them apart (KYB-529). The
+ * stream does carry the facts (`action.result` with a failed status and the
+ * tool's name and error; `step.failed` / `turn.failed` with a code and
+ * message), so the bridge keeps them and says them.
+ */
+export type TurnFailure = {
+    kind: "tool";
+    toolName: string;
+    message: string;
+} | {
+    kind: "model";
+    code: string;
+    message: string;
+};
 /** Everything the bridge needs to decide how one eve turn should be rendered. */
 export interface TurnOutcome {
     message: string;
@@ -10,19 +41,29 @@ export interface TurnOutcome {
     inputRequests: readonly InputRequest[];
     sessionId: string;
     streamIndex: number;
+    /** Failures seen on the stream, in order. Empty on a clean turn. */
+    failures: readonly TurnFailure[];
 }
-/** Convert one inbound Buzz message into an eve-compatible turn. */
-export declare function composeMessage(text: string, attachments: MediaRef[], fetchAttachment: (ref: MediaRef) => Promise<FetchedMedia>, log?: (message: string) => void): Promise<TurnMessage>;
-/** Continue a channel's existing conversation, replacing it only when it is stale. */
-export declare function answerTurn(client: Client, sessions: SessionStore, channel: string, message: TurnMessage, community: string, log?: (message: string) => void): Promise<TurnOutcome>;
+/** Read a failure out of one stream event, or nothing when the event is not one. */
+export declare function failureFromEvent(event: {
+    type: string;
+    data?: unknown;
+}): TurnFailure | null;
 /**
- * What the room is told when eve refuses the turn itself.
+ * What to post when a turn produced no text.
  *
- * A 400 means the request was malformed — a part eve does not accept, a body
- * it could not parse — not that the agent failed to think of an answer. The
- * session survives it (`answerTurn` keeps the mapping), but the person who
- * sent the message is still waiting, and a log line nobody is reading is not
- * an answer. Returns `null` for anything that is not a request rejection, so
- * the caller's ordinary failure path stays as it was.
+ * Names every distinct failure the stream reported, verbatim; a genuinely
+ * empty completion keeps the old sentence. Nothing here is invented: every
+ * tool name and message comes from an event the bridge saw.
  */
+export declare function silentTurnReply(failures: readonly TurnFailure[]): string;
+/** The bridge's log line for a turn with no text: which of the three cases it was. */
+export declare function describeSilentTurn(failures: readonly TurnFailure[]): string;
+/** Convert one inbound Buzz message into an eve-compatible turn. */
+export declare function composeMessage(text: string, attachments: MediaRef[], fetchAttachment: (ref: MediaRef) => Promise<FetchedMedia>, log?: (message: string) => void): Promise<TurnMessage>;
+/** Continue a channel's existing conversation, replacing it only when it is explicitly stale. */
+export declare function answerTurn(client: Client, sessions: SessionStore, channel: string, message: TurnMessage, community: string, log?: (message: string) => void, agentSilenceTimeoutMs?: number): Promise<TurnOutcome>;
+/** What the room is told when eve refuses the turn itself. */
 export declare function rejectedTurnReply(error: unknown): string | null;
+/** Give the originating channel one accurate recovery message for bridge-owned silence. */
+export declare function agentSilenceReply(error: unknown): string | null;

package/dist/turn.js

@@ -1,5 +1,93 @@
 import { ClientError, createDataUrlFilePart, } from "eve/client";
 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;
+/** A caller-owned inactivity timeout. Aborting the transport does not cancel the eve session. */
+export class AgentSilenceTimeoutError extends Error {
+    phase;
+    intervalMs;
+    constructor(phase, intervalMs) {
+        super(`agent was silent for ${intervalMs}ms during ${phase}`);
+        this.name = "AgentSilenceTimeoutError";
+        this.phase = phase;
+        this.intervalMs = intervalMs;
+    }
+}
+/** Refuse invalid values before starting a bridge with an ineffective watchdog. */
+export function validateAgentSilenceTimeoutMs(value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error("agentSilenceTimeoutMs must be a finite positive number of milliseconds");
+    }
+    return value;
+}
+const clip = (text, max = 200) => String(text ?? "").replace(/\s+/g, " ").trim().slice(0, max);
+/** Read a failure out of one stream event, or nothing when the event is not one. */
+export function failureFromEvent(event) {
+    const data = (event.data ?? {});
+    if (event.type === "action.result") {
+        const result = (data.result ?? {});
+        const failed = data.status === "failed" || data.status === "rejected" || result.isError === true;
+        if (!failed)
+            return null;
+        const error = (data.error ?? {});
+        const output = typeof result.output === "string" ? result.output : result.output !== undefined ? JSON.stringify(result.output) : "";
+        return {
+            kind: "tool",
+            toolName: String(result.toolName ?? "a tool"),
+            message: clip(error.message ?? output ?? data.status),
+        };
+    }
+    if (event.type === "step.failed" || event.type === "turn.failed") {
+        return { kind: "model", code: String(data.code ?? event.type), message: clip(data.message) };
+    }
+    return null;
+}
+/**
+ * What to post when a turn produced no text.
+ *
+ * Names every distinct failure the stream reported, verbatim; a genuinely
+ * empty completion keeps the old sentence. Nothing here is invented: every
+ * tool name and message comes from an event the bridge saw.
+ */
+export function silentTurnReply(failures) {
+    if (failures.length === 0)
+        return "I didn't get an answer back for that one — ask me again and I'll retry.";
+    const tools = new Map();
+    const models = [];
+    for (const f of failures) {
+        if (f.kind === "tool") {
+            const key = `${f.toolName}\u0000${f.message}`;
+            const seen = tools.get(key);
+            if (seen)
+                seen.count += 1;
+            else
+                tools.set(key, { count: 1, message: f.message });
+        }
+        else {
+            models.push(`${f.code}: ${f.message}`);
+        }
+    }
+    const lines = [];
+    for (const [key, { count, message }] of tools) {
+        const toolName = key.split("\u0000")[0];
+        const times = count === 1 ? "" : ` ${count} times`;
+        lines.push(`I tried \`${toolName}\`${times} and it answered "${message}".`);
+    }
+    if (models.length)
+        lines.push(`The model call failed (${[...new Set(models)].join("; ")}).`);
+    lines.push("So I have nothing to give you yet. Say the word and I'll try another way.");
+    return lines.join(" ");
+}
+/** The bridge's log line for a turn with no text: which of the three cases it was. */
+export function describeSilentTurn(failures) {
+    const tools = failures.filter((f) => f.kind === "tool").length;
+    const models = failures.filter((f) => f.kind === "model");
+    if (models.length)
+        return `no text: model error (${models.map((m) => m.code).join(", ")})`;
+    if (tools)
+        return `no text: tool failures (${tools})`;
+    return "no text: empty completion";
+}
 /** Convert one inbound Buzz message into an eve-compatible turn. */
 export async function composeMessage(text, attachments, fetchAttachment, log = () => { }) {
     if (attachments.length === 0)
@@ -33,99 +121,190 @@ export async function composeMessage(text, attachments, fetchAttachment, log = (
     }
     return parts;
 }
-function outcome(result, streamIndex) {
+function silenceWatchdog(intervalMs) {
+    const controller = new AbortController();
+    let timer;
+    let timeout;
     return {
-        message: result.message ?? "",
-        status: result.status,
-        inputRequests: result.inputRequests,
-        sessionId: result.sessionId,
-        streamIndex,
+        signal: controller.signal,
+        arm(phase) {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                timeout = new AgentSilenceTimeoutError(phase, intervalMs);
+                controller.abort(timeout);
+            }, intervalMs);
+        },
+        dispose() {
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+        },
+        throwIfTimedOut() {
+            if (timeout)
+                throw timeout;
+        },
     };
 }
-/** Continue a channel's existing conversation, replacing it only when it is stale. */
-export async function answerTurn(client, sessions, channel, message, community, log = () => { }) {
+async function drainUnread(stream, intervalMs) {
+    const watchdog = silenceWatchdog(intervalMs);
+    let unread = 0;
+    watchdog.arm("unread drain");
+    try {
+        try {
+            for await (const _ of stream(watchdog.signal)) {
+                unread += 1;
+                watchdog.arm("unread drain");
+            }
+        }
+        catch (error) {
+            watchdog.throwIfTimedOut();
+            throw error;
+        }
+        // Eve normally swallows an external stream abort as clean iterator completion.
+        watchdog.throwIfTimedOut();
+        return unread;
+    }
+    finally {
+        watchdog.dispose();
+    }
+}
+async function collectResponse(response, watchdog, phase, streamIndex) {
+    let message = "";
+    let status = "completed";
+    const inputRequests = [];
+    const failures = [];
+    watchdog.arm(phase);
+    try {
+        try {
+            for await (const event of response) {
+                watchdog.arm(phase);
+                const failure = failureFromEvent(event);
+                if (failure)
+                    failures.push(failure);
+                if (event.type === "message.completed" && event.data.finishReason !== "tool-calls") {
+                    message = event.data.message ?? "";
+                }
+                else if (event.type === "input.requested") {
+                    inputRequests.push(...event.data.requests);
+                }
+                else if (event.type === "session.waiting") {
+                    status = "waiting";
+                }
+                else if (event.type === "session.failed") {
+                    status = "failed";
+                }
+                else if (event.type === "session.completed") {
+                    status = "completed";
+                }
+            }
+        }
+        catch (error) {
+            watchdog.throwIfTimedOut();
+            throw error;
+        }
+        watchdog.throwIfTimedOut();
+        return {
+            message,
+            status,
+            inputRequests,
+            sessionId: response.sessionId,
+            streamIndex: streamIndex(),
+            failures,
+        };
+    }
+    finally {
+        watchdog.dispose();
+    }
+}
+async function sendExisting(responsePromise, streamIndex, intervalMs) {
+    const watchdog = silenceWatchdog(intervalMs);
+    watchdog.arm("send acknowledgement");
+    try {
+        let response;
+        try {
+            response = await responsePromise(watchdog.signal);
+        }
+        catch (error) {
+            watchdog.throwIfTimedOut();
+            throw error;
+        }
+        watchdog.throwIfTimedOut();
+        return await collectResponse(response, watchdog, "response stream", streamIndex);
+    }
+    finally {
+        watchdog.dispose();
+    }
+}
+/** Continue a channel's existing conversation, replacing it only when it is explicitly stale. */
+export async function answerTurn(client, sessions, channel, message, community, log = () => { }, agentSilenceTimeoutMs = DEFAULT_AGENT_SILENCE_TIMEOUT_MS) {
+    const intervalMs = validateAgentSilenceTimeoutMs(agentSilenceTimeoutMs);
     const existing = sessions.get(community, channel);
     if (existing) {
         try {
+            // attach() is local in eve 0.49 and performs no network I/O.
             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.
-             *
-             * Do not call this path while HITL is pending: the bridge's follower owns
-             * that unread stream until the parked turn reaches its next boundary.
+             * holds and stops at the FIRST turn boundary it meets. Draining first
+             * repairs any cursor that was left behind by a prior disconnected reader.
              */
-            let unread = 0;
-            for await (const _ of session.stream({ follow: false, startIndex: existing.streamIndex })) {
-                unread += 1;
-            }
+            const unread = await drainUnread((signal) => session.stream({ follow: false, startIndex: existing.streamIndex, signal }), intervalMs);
             if (unread > 0) {
                 log(`caught up on ${unread} unread event(s) in ${channel.slice(0, 8)} before answering`);
             }
-            const response = await session.send(message, {
+            const result = await sendExisting((signal) => session.send(message, {
                 clientContext: { buzzCommunity: community, buzzChannel: channel },
-            });
-            const result = await response.result();
+                signal,
+            }), () => session.state.streamIndex, intervalMs);
             sessions.set(community, channel, {
                 id: existing.id,
                 streamIndex: session.state.streamIndex,
             });
-            return outcome(result, session.state.streamIndex);
+            return result;
         }
         catch (error) {
-            // A malformed turn does not make its durable session stale. Rethrow so
-            // the bridge can tell the room (see `rejectedTurnReply`), and keep the
-            // mapping so the next valid message continues the same conversation.
-            if (error instanceof ClientError && error.status === 400)
+            // Transport uncertainty, request rejection, and our own timeout do not
+            // prove the durable server conversation is stale. Preserve its mapping.
+            if (!(error instanceof ClientError) || error.status !== 404)
                 throw error;
             log(`session for ${channel.slice(0, 8)} could not continue (${error.message}); starting a new one`);
             sessions.delete(community, channel);
         }
     }
-    // Every fresh conversation is logged, whatever the reason. The silent case
-    // used to be the common one: after a bridge restart the map was empty, the
-    // message fell straight through to create(), and eight exchanges of context
-    // vanished without a line anyone could read (KYB-502).
     log(existing
         ? `starting a new conversation in ${channel.slice(0, 8)} (the previous session could not continue)`
         : `starting a new conversation in ${channel.slice(0, 8)} (no session on record for this channel)`);
-    const created = await client.sessions.create({
-        message,
-        clientContext: { buzzCommunity: community, buzzChannel: channel },
-    });
-    const result = await created.response.result();
-    sessions.set(community, channel, {
-        id: created.session.state.sessionId,
-        streamIndex: created.session.state.streamIndex,
-    });
-    return outcome(result, created.session.state.streamIndex);
+    const watchdog = silenceWatchdog(intervalMs);
+    watchdog.arm("create acknowledgement");
+    try {
+        let created;
+        try {
+            created = await client.sessions.create({
+                message,
+                clientContext: { buzzCommunity: community, buzzChannel: channel },
+                signal: watchdog.signal,
+            });
+        }
+        catch (error) {
+            watchdog.throwIfTimedOut();
+            throw error;
+        }
+        watchdog.throwIfTimedOut();
+        const result = await collectResponse(created.response, watchdog, "create response stream", () => created.session.state.streamIndex);
+        sessions.set(community, channel, {
+            id: created.session.state.sessionId,
+            streamIndex: created.session.state.streamIndex,
+        });
+        return result;
+    }
+    finally {
+        watchdog.dispose();
+    }
 }
-/**
- * What the room is told when eve refuses the turn itself.
- *
- * A 400 means the request was malformed — a part eve does not accept, a body
- * it could not parse — not that the agent failed to think of an answer. The
- * session survives it (`answerTurn` keeps the mapping), but the person who
- * sent the message is still waiting, and a log line nobody is reading is not
- * an answer. Returns `null` for anything that is not a request rejection, so
- * the caller's ordinary failure path stays as it was.
- */
+/** What the room is told when eve refuses the turn itself. */
 export function rejectedTurnReply(error) {
     if (!(error instanceof ClientError) || error.status !== 400)
         return null;
@@ -134,3 +313,9 @@ 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. */
+export function agentSilenceReply(error) {
+    if (!(error instanceof AgentSilenceTimeoutError))
+        return null;
+    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.2",
+  "version": "0.9.3",
   "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",