@kybernesis/buzz 0.9.4 → 0.9.6

package/README.md

@@ -61,7 +61,8 @@ 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) |
+| `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. |
 | `KYBERNESIS_ISSUER` | The control plane |
 | `KYBERNESIS_AGENT_CREDENTIAL` | This agent's credential |
 

package/dist/bridge.d.ts

@@ -21,6 +21,8 @@ export type BuzzBridgeOptions = {
     pollMs?: number;
     /** Maximum silence during one agent request or event stream; defaults to five minutes. */
     agentSilenceTimeoutMs?: number;
+    /** Ceiling on a turn once acknowledged; the agent is working while its stream is quiet. Default 60 minutes. */
+    agentWorkTimeoutMs?: 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 { agentSilenceReply, answerTurn, composeMessage, DEFAULT_AGENT_SILENCE_TIMEOUT_MS, describeSilentTurn, rejectedTurnReply, silentTurnReply, validateAgentSilenceTimeoutMs, } from "./turn.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 { 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 agentWorkTimeoutMs = validateAgentSilenceTimeoutMs(options.agentWorkTimeoutMs ?? DEFAULT_AGENT_WORK_TIMEOUT_MS);
     const agentSilenceTimeoutMs = validateAgentSilenceTimeoutMs(options.agentSilenceTimeoutMs ?? DEFAULT_AGENT_SILENCE_TIMEOUT_MS);
     /**
      * One conversation per channel — the SESSION ID, not a handle to it.
@@ -341,7 +342,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, agentSilenceTimeoutMs);
+                const result = await answerTurn(clientFor(event.pubkey), sessions, channel, message, from, log, agentSilenceTimeoutMs, agentWorkTimeoutMs);
                 if (result.status === "waiting" && result.inputRequests.length > 0) {
                     sessions.set(from, channel, {
                         id: result.sessionId,

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_WORK_TIMEOUT_MS
+            ? { agentWorkTimeoutMs: Number(process.env.BUZZ_AGENT_WORK_TIMEOUT_MS) }
+            : {}),
         ...(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS
             ? { agentSilenceTimeoutMs: Number(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS) }
             : {}),
@@ -298,7 +301,8 @@ 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)
+    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)
     KYBERNESIS_ISSUER              the control plane
     KYBERNESIS_AGENT_CREDENTIAL    this agent's credential
 `);

package/dist/turn.d.ts

@@ -3,6 +3,27 @@ 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;
+/**
+ * How long a turn may run once the agent has acknowledged it.
+ *
+ * eve's response stream is quiet while the agent works: a long tool call or a
+ * delegated subagent produces no events until it returns. Reading that quiet
+ * as a stall killed every real piece of work over five minutes the day the
+ * silence watchdog shipped (a repository study, a delegation that cloned and
+ * read a codebase), while the stall it was built for happened BEFORE the
+ * first event: no run was ever created. So the short bound stays on the
+ * phases where silence is a fault (unread drain, acknowledgements) and the
+ * response stream gets this ceiling instead. Sixty minutes covers the longest
+ * genuine turn seen on a deployment (44 minutes) with room.
+ */
+export declare const DEFAULT_AGENT_WORK_TIMEOUT_MS: number;
+/** The two bounds a watchdog applies, chosen by phase. */
+export interface AgentTimeouts {
+    /** Silence before the first event of a request: drain, send/create acknowledgement. */
+    readonly silenceMs: number;
+    /** Silence between events once the response stream is open: the agent is working. */
+    readonly workMs: 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 {
@@ -62,8 +83,23 @@ export declare function describeSilentTurn(failures: readonly TurnFailure[]): st
 /** 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>;
+export declare function answerTurn(client: Client, sessions: SessionStore, channel: string, message: TurnMessage, community: string, log?: (message: string) => void, agentSilenceTimeoutMs?: number, agentWorkTimeoutMs?: number): Promise<TurnOutcome>;
 /** What the room is told when eve refuses the turn itself. */
+/**
+ * The two answers from eve that mean the stored session cannot carry another
+ * turn: an unknown session id (404), and a session that ended (409 with
+ * `session_not_active`, "The session is no longer active."). A session ends
+ * when one of its turns fails hard, for instance a model call that 404s at
+ * the gateway; the channel must then start a fresh one.
+ *
+ * Only these replace the mapping. A 400 about the message, a timeout, or a
+ * transport failure says nothing about whether the session is alive, and
+ * discarding it on those is how conversations were lost (KYB-502). The 409
+ * was missed when the timeout work narrowed the rule to 404 alone, and a
+ * channel then failed every message with "The session is no longer active."
+ * until someone edited the store by hand.
+ */
+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. */
 export declare function agentSilenceReply(error: unknown): string | null;

package/dist/turn.js

@@ -2,6 +2,21 @@ 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;
+/**
+ * How long a turn may run once the agent has acknowledged it.
+ *
+ * eve's response stream is quiet while the agent works: a long tool call or a
+ * delegated subagent produces no events until it returns. Reading that quiet
+ * as a stall killed every real piece of work over five minutes the day the
+ * silence watchdog shipped (a repository study, a delegation that cloned and
+ * read a codebase), while the stall it was built for happened BEFORE the
+ * first event: no run was ever created. So the short bound stays on the
+ * phases where silence is a fault (unread drain, acknowledgements) and the
+ * response stream gets this ceiling instead. Sixty minutes covers the longest
+ * genuine turn seen on a deployment (44 minutes) with room.
+ */
+export const DEFAULT_AGENT_WORK_TIMEOUT_MS = 60 * 60_000;
+const isWorkPhase = (phase) => phase.endsWith("response stream");
 /** A caller-owned inactivity timeout. Aborting the transport does not cancel the eve session. */
 export class AgentSilenceTimeoutError extends Error {
     phase;
@@ -121,7 +136,7 @@ export async function composeMessage(text, attachments, fetchAttachment, log = (
     }
     return parts;
 }
-function silenceWatchdog(intervalMs) {
+function silenceWatchdog(timeouts) {
     const controller = new AbortController();
     let timer;
     let timeout;
@@ -130,6 +145,7 @@ function silenceWatchdog(intervalMs) {
         arm(phase) {
             if (timer)
                 clearTimeout(timer);
+            const intervalMs = isWorkPhase(phase) ? timeouts.workMs : timeouts.silenceMs;
             timer = setTimeout(() => {
                 timeout = new AgentSilenceTimeoutError(phase, intervalMs);
                 controller.abort(timeout);
@@ -146,8 +162,8 @@ function silenceWatchdog(intervalMs) {
         },
     };
 }
-async function drainUnread(stream, intervalMs) {
-    const watchdog = silenceWatchdog(intervalMs);
+async function drainUnread(stream, timeouts) {
+    const watchdog = silenceWatchdog(timeouts);
     let unread = 0;
     watchdog.arm("unread drain");
     try {
@@ -169,33 +185,84 @@ async function drainUnread(stream, intervalMs) {
         watchdog.dispose();
     }
 }
-async function collectResponse(response, watchdog, phase, streamIndex) {
+const isTurnBoundary = (type) => type === "session.waiting" || type === "session.completed" || type === "session.failed";
+async function collectResponse(response, watchdog, phase, streamIndex, continueStream, log = () => { }) {
     let message = "";
     let status = "completed";
-    const inputRequests = [];
-    const failures = [];
+    let inputRequests = [];
+    let failures = [];
+    let sawTurnStart = false;
+    let endedAtOwnBoundary = false;
+    let staleBoundaryFirst = false;
+    let seen = 0;
+    /**
+     * One event of this turn, or of the turn before it.
+     *
+     * The client ends a send's stream at the first session boundary after the
+     * cursor. When the send itself ends an earlier, still-running turn (a person
+     * asks again while a twenty-minute delegation is under way), that earlier
+     * turn's `session.waiting` is the first thing on the wire, before this
+     * turn's `turn.started`. Read as ours it made an empty answer, and the
+     * abandoned stream then closed the request, which cancelled the real turn
+     * five minutes into its work. So: nothing counts until this turn has
+     * started, and a boundary only ends the collection once it has.
+     */
+    const consume = (event) => {
+        watchdog.arm(phase);
+        seen += 1;
+        // A boundary as the very first event, before anything of this turn, is the
+        // earlier turn's. Anything else is treated as ours (a stream without
+        // turn.started still answers as before).
+        if (seen === 1 && isTurnBoundary(event.type) && !sawTurnStart)
+            staleBoundaryFirst = true;
+        if (event.type === "turn.started") {
+            sawTurnStart = true;
+            message = "";
+            status = "completed";
+            inputRequests = [];
+            failures = [];
+            return false;
+        }
+        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";
+        }
+        if (isTurnBoundary(event.type) && !staleBoundaryFirst) {
+            endedAtOwnBoundary = true;
+            return true;
+        }
+        if (isTurnBoundary(event.type) && staleBoundaryFirst && sawTurnStart) {
+            endedAtOwnBoundary = true;
+            return true;
+        }
+        return false;
+    };
     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";
+                if (consume(event))
+                    break;
+            }
+            if (staleBoundaryFirst && !endedAtOwnBoundary && continueStream) {
+                log("the stream ended on an earlier turn's boundary before this turn started; following the session until this turn ends");
+                for await (const event of continueStream(watchdog.signal)) {
+                    if (consume(event))
+                        break;
                 }
             }
         }
@@ -217,8 +284,8 @@ async function collectResponse(response, watchdog, phase, streamIndex) {
         watchdog.dispose();
     }
 }
-async function sendExisting(responsePromise, streamIndex, intervalMs) {
-    const watchdog = silenceWatchdog(intervalMs);
+async function sendExisting(responsePromise, streamIndex, timeouts, continueStream, log = () => { }) {
+    const watchdog = silenceWatchdog(timeouts);
     watchdog.arm("send acknowledgement");
     try {
         let response;
@@ -230,15 +297,18 @@ async function sendExisting(responsePromise, streamIndex, intervalMs) {
             throw error;
         }
         watchdog.throwIfTimedOut();
-        return await collectResponse(response, watchdog, "response stream", streamIndex);
+        return await collectResponse(response, watchdog, "response stream", streamIndex, continueStream, log);
     }
     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);
+export async function answerTurn(client, sessions, channel, message, community, log = () => { }, agentSilenceTimeoutMs = DEFAULT_AGENT_SILENCE_TIMEOUT_MS, agentWorkTimeoutMs = DEFAULT_AGENT_WORK_TIMEOUT_MS) {
+    const intervalMs = {
+        silenceMs: validateAgentSilenceTimeoutMs(agentSilenceTimeoutMs),
+        workMs: validateAgentSilenceTimeoutMs(agentWorkTimeoutMs),
+    };
     const existing = sessions.get(community, channel);
     if (existing) {
         try {
@@ -258,7 +328,7 @@ export async function answerTurn(client, sessions, channel, message, community,
             const result = await sendExisting((signal) => session.send(message, {
                 clientContext: { buzzCommunity: community, buzzChannel: channel },
                 signal,
-            }), () => session.state.streamIndex, intervalMs);
+            }), () => session.state.streamIndex, intervalMs, (signal) => session.stream({ follow: true, startIndex: session.state.streamIndex, signal }), log);
             sessions.set(community, channel, {
                 id: existing.id,
                 streamIndex: session.state.streamIndex,
@@ -268,7 +338,7 @@ export async function answerTurn(client, sessions, channel, message, community,
         catch (error) {
             // 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)
+            if (!isSessionGone(error))
                 throw error;
             log(`session for ${channel.slice(0, 8)} could not continue (${error.message}); starting a new one`);
             sessions.delete(community, channel);
@@ -293,7 +363,7 @@ export async function answerTurn(client, sessions, channel, message, community,
             throw error;
         }
         watchdog.throwIfTimedOut();
-        const result = await collectResponse(created.response, watchdog, "create response stream", () => created.session.state.streamIndex);
+        const result = await collectResponse(created.response, watchdog, "create response stream", () => created.session.state.streamIndex, (signal) => created.session.stream({ follow: true, startIndex: created.session.state.streamIndex, signal }), log);
         sessions.set(community, channel, {
             id: created.session.state.sessionId,
             streamIndex: created.session.state.streamIndex,
@@ -305,6 +375,28 @@ export async function answerTurn(client, sessions, channel, message, community,
     }
 }
 /** What the room is told when eve refuses the turn itself. */
+/**
+ * The two answers from eve that mean the stored session cannot carry another
+ * turn: an unknown session id (404), and a session that ended (409 with
+ * `session_not_active`, "The session is no longer active."). A session ends
+ * when one of its turns fails hard, for instance a model call that 404s at
+ * the gateway; the channel must then start a fresh one.
+ *
+ * Only these replace the mapping. A 400 about the message, a timeout, or a
+ * transport failure says nothing about whether the session is alive, and
+ * discarding it on those is how conversations were lost (KYB-502). The 409
+ * was missed when the timeout work narrowed the rule to 404 alone, and a
+ * channel then failed every message with "The session is no longer active."
+ * until someone edited the store by hand.
+ */
+export function isSessionGone(error) {
+    if (!(error instanceof ClientError))
+        return false;
+    if (error.status === 404)
+        return true;
+    return (error.status === 409 &&
+        (error.code === "session_not_active" || /no longer active/i.test(String(error.message ?? ""))));
+}
 export function rejectedTurnReply(error) {
     if (!(error instanceof ClientError) || error.status !== 400)
         return null;

package/package.json

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