@butlerbot/sdk 0.0.28 → 0.0.30

package/dist/config.d.ts

@@ -25,6 +25,16 @@ export declare const CONFIG: {
                 };
             };
         };
+        interrupt: {
+            v4: {
+                stop: string;
+                steer: string;
+            };
+            v5: {
+                stop: string;
+                steer: string;
+            };
+        };
         progress: {
             v4: {
                 base: string;

package/dist/config.js

@@ -18,6 +18,16 @@ exports.CONFIG = {
                 v1: { base: "/api/convo/get/history" }
             }
         },
+        interrupt: {
+            v4: {
+                stop: "/api/alfred/v4/chat/stop",
+                steer: "/api/alfred/v4/chat/steer",
+            },
+            v5: {
+                stop: "/api/alfred/v5/chat/stop",
+                steer: "/api/alfred/v5/chat/steer",
+            },
+        },
         progress: {
             v4: {
                 base: "/api/alfred/v4/chat/progress",

package/dist/index.d.ts

@@ -38,3 +38,4 @@ export type { APIPath };
 export type { ConversationStream, ConversationTransport, TransportTurnRequest, TransportHandlers, } from "./modules/transport";
 export { LinkConversationTransport } from "./modules/transport_link";
 export { SSEConversationTransport } from "./modules/transport_sse";
+export type { SteerResult, TurnStopMode, TurnStopped } from "./modules/transport";

package/dist/link/link.d.ts

@@ -123,6 +123,8 @@ export declare class Link {
      * never needs to ask.
      */
     private lastInboundAt;
+    /** Ids of keepalive pulses, so their pongs can be dropped instead of shown as logs. */
+    private pulses;
     private closedByUs;
     constructor(options: LinkOptions);
     /** Adds a tool Alfred can call. Registered on connect, or immediately if already open. */
@@ -211,12 +213,28 @@ export declare class Link {
      * big enough to take longer than the timeout to drain got its own connection torn
      * down with `4000 heartbeat timeout` — always mid-response, always on the longest
      * answers, which are the ones a user least wants to lose.
+     *
+     * Not asking is not the same as saying nothing, though. The server reaps connections
+     * that have sent it no frames for 100s, because a socket the client walked away from
+     * still answers websocket pings at the network layer and only the client's own frames
+     * prove someone is still there. A link busy receiving a long turn used to go completely
+     * silent for as long as the turn ran and got closed as idle — `1001 idle: no frames
+     * received`, mid-response again. So a busy interval still sends a pulse; it just does
+     * not wait for the reply, which is the half that could not survive a full send queue.
      */
     private startHeartbeat;
     /** Wakes when the connection will have been silent for a full interval, not before. */
     private scheduleHeartbeat;
     /** One liveness round trip. Only ever sent to a connection that has gone quiet. */
     private ping;
+    /**
+     * A ping sent with no deadline and no interest in the answer.
+     *
+     * Its only job is to land on the server so the connection does not look abandoned. A
+     * failure here is not evidence of anything — inbound frames already proved the socket
+     * works — so it stays quiet and lets the real heartbeat make that call.
+     */
+    private pulse;
     /** Never longer than the interval itself: a second ping in flight tells us nothing new. */
     private heartbeatTimeoutMs;
     /** Any frame from the server, of any kind, is proof the connection still works. */

package/dist/link/link.js

@@ -56,6 +56,8 @@ class Link {
          * never needs to ask.
          */
         this.lastInboundAt = 0;
+        /** Ids of keepalive pulses, so their pongs can be dropped instead of shown as logs. */
+        this.pulses = new Set();
         this.closedByUs = false;
         this.options = {
             ...DEFAULTS,
@@ -390,6 +392,14 @@ class Link {
      * big enough to take longer than the timeout to drain got its own connection torn
      * down with `4000 heartbeat timeout` — always mid-response, always on the longest
      * answers, which are the ones a user least wants to lose.
+     *
+     * Not asking is not the same as saying nothing, though. The server reaps connections
+     * that have sent it no frames for 100s, because a socket the client walked away from
+     * still answers websocket pings at the network layer and only the client's own frames
+     * prove someone is still there. A link busy receiving a long turn used to go completely
+     * silent for as long as the turn ran and got closed as idle — `1001 idle: no frames
+     * received`, mid-response again. So a busy interval still sends a pulse; it just does
+     * not wait for the reply, which is the half that could not survive a full send queue.
      */
     startHeartbeat(generation) {
         if (!this.options.heartbeatMs)
@@ -408,8 +418,10 @@ class Link {
             if (generation !== this.generation)
                 return;
             // Something arrived while this was pending: the connection is demonstrably
-            // alive and there is nothing to ask. Wait out the rest of its silence instead.
+            // alive and there is nothing to ask. Tell the server we are still here and
+            // wait out the rest of its silence instead.
             if (Date.now() - this.lastInboundAt < this.options.heartbeatMs) {
+                this.pulse();
                 return this.scheduleHeartbeat(generation);
             }
             this.ping(generation);
@@ -440,6 +452,21 @@ class Link {
             this.dropSocket(generation, 4000, "heartbeat timeout");
         });
     }
+    /**
+     * A ping sent with no deadline and no interest in the answer.
+     *
+     * Its only job is to land on the server so the connection does not look abandoned. A
+     * failure here is not evidence of anything — inbound frames already proved the socket
+     * works — so it stays quiet and lets the real heartbeat make that call.
+     */
+    pulse() {
+        try {
+            this.pulses.add(this.send("ping", {}));
+        }
+        catch {
+            this.debug("could not send the keepalive pulse, leaving it to the next heartbeat");
+        }
+    }
     /** Never longer than the interval itself: a second ping in flight tells us nothing new. */
     heartbeatTimeoutMs() {
         return Math.max(250, Math.min(this.options.requestTimeoutMs, this.options.heartbeatMs));
@@ -452,6 +479,8 @@ class Link {
         if (this.heartbeat)
             clearTimeout(this.heartbeat);
         this.heartbeat = undefined;
+        // Pongs owed by a socket that is going away will never arrive.
+        this.pulses.clear();
     }
     // =============================================
     // WAITING
@@ -652,6 +681,10 @@ class Link {
                 waiting.onFrame?.(frame);
             return;
         }
+        // The pong to a keepalive pulse. Nothing is waiting for it, and it is not a log
+        // anyone asked to see.
+        if (frame.replyTo && this.pulses.delete(frame.replyTo))
+            return;
         switch (frame.type) {
             case "tool.call":
                 this.handleToolCall(frame);

package/dist/link/protocol.d.ts

@@ -120,6 +120,25 @@ export type LinkClientPayloads = {
     "conversation.detach": {
         chatId: string;
     };
+    /**
+     * Stops a running turn.
+     *
+     * `soft` lets the model call in flight finish and takes no further step; `hard` aborts the
+     * stream where it stands. A hard stop against a provider that cannot be cancelled is
+     * applied as a soft one — the answer says which was applied.
+     */
+    "conversation.stop": {
+        chatId: string;
+        mode: "soft" | "hard";
+    };
+    /**
+     * Says something to a turn that is still running. It reaches the model at its next step
+     * boundary; the turn is not interrupted.
+     */
+    "conversation.steer": {
+        chatId: string;
+        message: string;
+    };
 };
 export type LinkClientFrameType = keyof LinkClientPayloads;
 /**
@@ -196,6 +215,17 @@ export type LinkServerPayloads = {
         error?: string;
         message?: string;
     };
+    /** A turn was stopped. `mode` is what was applied, `requestedMode` what was asked for. */
+    "conversation.stopped": {
+        chatId: string;
+        mode: "soft" | "hard";
+        requestedMode: "soft" | "hard";
+        by: "user" | "system";
+    };
+    /** A steered message was accepted and will reach the model at its next step boundary. */
+    "conversation.steered": {
+        chatId: string;
+    };
     "goodbye": {
         reason: string;
         reconnectAfterMs: number;

package/dist/modules/conversation.d.ts

@@ -1,7 +1,7 @@
 import { EventSource } from "eventsource";
 import { APIPath } from "../config";
 import type { Link } from "../link/link";
-import { ConversationStream } from "./transport";
+import { ConversationStream, SteerResult, TurnStopMode, TurnStopped } from "./transport";
 import { RequestResponseV3, RequestResponseV4 } from "../types/type_registry";
 import { RequestResponseV5 } from "../types/response/v5/dialogue_response_v5";
 import { ConversationStateResponse } from "../types/state/convo_state_response";
@@ -181,6 +181,32 @@ export declare class Conversation<V extends APIPath = "v4"> {
     private receiver;
     /** Sends a message into the conversation */
     send(message: string, cb: (chunk: RequestResponseByVersion[V]) => any, options?: DialogueRequestOptions): ConversationStream;
+    /**
+     * Stops the turn running in this conversation.
+     *
+     * `soft` (the default) lets the model finish the call it is in the middle of and takes no
+     * further step: the answer so far is kept, in history and in what the model remembers
+     * saying, and it works on every model. `hard` cuts the stream off mid-sentence and aborts
+     * the tools with it — but only actually stops the bill where the provider supports
+     * cancellation, so against one that does not the server applies a soft stop instead. The
+     * returned `mode` says which you got; `undefined` means there was nothing left to stop.
+     *
+     * Either way the turn's stream ends the way it always does, carrying what was produced
+     * before the stop. There is nothing else to clean up.
+     */
+    stop(mode?: TurnStopMode): Promise<TurnStopped | undefined>;
+    /**
+     * Says something to the turn that is already running.
+     *
+     * The message reaches the model at its next step boundary, so nothing in flight is thrown
+     * away and the model reads it as the user talking mid-task — which is usually what someone
+     * typing while Alfred works actually means.
+     *
+     * Check the result. `too_late` means the message was NOT delivered, because the turn was
+     * already stopping or over, and it should be sent with `send()` instead. Dropping it is
+     * the one thing that is never right.
+     */
+    steer(message: string): Promise<SteerResult>;
     /**
      * Sends a message and resolves with the finished reply.
      *

package/dist/modules/conversation.js

@@ -15,11 +15,14 @@ class Conversation {
         this.chatApiV = (config.chatApiV || DEFAULT_CONVO_API_V);
         const serverUrl = config.serverUrl || config_1.CONFIG.server;
         const progressConfig = config_1.CONFIG.paths.progress[this.chatApiV];
+        const interruptConfig = config_1.CONFIG.paths.interrupt[this.chatApiV];
         this.endpoints = {
             conversation: serverUrl + (config.convoPath || config.path || config_1.CONFIG.paths.conversation[this.chatApiV].base),
             history: serverUrl + (config.historyPath || config_1.CONFIG.paths.history.chat.v1.base),
             progressStream: serverUrl + (config.progressStreamPath || (progressConfig?.stream ?? config_1.CONFIG.paths.progress.v4.stream)),
             progress: serverUrl + (config.progressPath || (progressConfig?.base ?? config_1.CONFIG.paths.progress.v4.base)),
+            stop: serverUrl + (interruptConfig?.stop ?? config_1.CONFIG.paths.interrupt.v4.stop),
+            steer: serverUrl + (interruptConfig?.steer ?? config_1.CONFIG.paths.interrupt.v4.steer),
         };
         this.apiKey = config.apiKey;
         this.debug = config.debug || false;
@@ -36,6 +39,8 @@ class Conversation {
         else {
             this.transport = new transport_sse_1.SSEConversationTransport({
                 endpoint: () => this.endpoints.conversation,
+                stopEndpoint: () => this.endpoints.stop,
+                steerEndpoint: () => this.endpoints.steer,
                 apiKey: this.apiKey,
                 debug: this.debug,
             });
@@ -261,6 +266,44 @@ class Conversation {
             },
         });
     }
+    /**
+     * Stops the turn running in this conversation.
+     *
+     * `soft` (the default) lets the model finish the call it is in the middle of and takes no
+     * further step: the answer so far is kept, in history and in what the model remembers
+     * saying, and it works on every model. `hard` cuts the stream off mid-sentence and aborts
+     * the tools with it — but only actually stops the bill where the provider supports
+     * cancellation, so against one that does not the server applies a soft stop instead. The
+     * returned `mode` says which you got; `undefined` means there was nothing left to stop.
+     *
+     * Either way the turn's stream ends the way it always does, carrying what was produced
+     * before the stop. There is nothing else to clean up.
+     */
+    async stop(mode = "soft") {
+        if (!this.convoId)
+            return undefined;
+        if (!this.transport.stop)
+            return undefined;
+        return this.transport.stop({ chatId: this.convoId, mode });
+    }
+    /**
+     * Says something to the turn that is already running.
+     *
+     * The message reaches the model at its next step boundary, so nothing in flight is thrown
+     * away and the model reads it as the user talking mid-task — which is usually what someone
+     * typing while Alfred works actually means.
+     *
+     * Check the result. `too_late` means the message was NOT delivered, because the turn was
+     * already stopping or over, and it should be sent with `send()` instead. Dropping it is
+     * the one thing that is never right.
+     */
+    async steer(message) {
+        if (!this.convoId)
+            return { ok: false, reason: "no_turn" };
+        if (!this.transport.steer)
+            return { ok: false, reason: "no_turn" };
+        return this.transport.steer({ chatId: this.convoId, message });
+    }
     /**
      * Sends a message and resolves with the finished reply.
      *

package/dist/modules/transport.d.ts

@@ -6,16 +6,48 @@
  * only decides how a turn is sent and how its stream comes back — everything a
  * caller sees, including the payload shape, is identical either way.
  */
-/** A turn in progress. `close()` stops delivery locally. */
+/** A turn in progress. */
 export type ConversationStream = {
     /**
      * Stops listening. The turn itself continues server-side and its reply is still
-     * persisted, on both transports — there is no cancel.
+     * persisted, on both transports — this is not a cancel. To actually stop the turn,
+     * use `Conversation.stop()`.
      */
     close(): void;
     /** The underlying EventSource, when the turn is being carried over SSE. */
     readonly source?: unknown;
 };
+/**
+ * How hard to stop a turn.
+ *
+ * - `soft`: let the model call in flight finish, then stop. Keeps the text, costs what that
+ *   step cost, and works everywhere. The right default for a stop button.
+ * - `hard`: abort the stream mid-sentence and every tool with it. Only stops the bill on
+ *   providers that support cancellation; against one that does not the server applies a soft
+ *   stop instead, rather than throwing away output that is billed either way. Check the
+ *   `mode` you get back to see which happened.
+ */
+export type TurnStopMode = "soft" | "hard";
+/** A stop, as the server applied it. */
+export type TurnStopped = {
+    /** What was applied. */
+    mode: TurnStopMode;
+    /** What was asked for. Differs from `mode` when a hard stop was downgraded. */
+    requestedMode: TurnStopMode;
+    by: "user" | "system";
+};
+/**
+ * What became of a message steered into a running turn.
+ *
+ * `too_late` is the one that matters: the turn was already stopping or finished, the message
+ * was NOT delivered, and it should be sent as an ordinary turn instead. Never drop it.
+ */
+export type SteerResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "no_turn" | "too_late";
+};
 export type TransportTurnRequest = {
     chatId?: string;
     message: string;
@@ -36,8 +68,31 @@ export type TransportAttachRequest = {
     /** Resume point: only what came after this event is replayed. */
     afterEventId?: string;
 };
+/** A request to interrupt a turn that is already running. */
+export type TransportStopRequest = {
+    chatId: string;
+    mode: TurnStopMode;
+};
+export type TransportSteerRequest = {
+    chatId: string;
+    message: string;
+};
 export interface ConversationTransport {
     send(request: TransportTurnRequest, handlers: TransportHandlers): ConversationStream;
+    /**
+     * Stops the turn running in a conversation.
+     *
+     * Resolves `undefined` when there was nothing to stop — the turn finished on its own, or
+     * never started. That is not an error: it is the answer to pressing stop a moment too late.
+     */
+    stop?(request: TransportStopRequest): Promise<TurnStopped | undefined>;
+    /**
+     * Says something to a turn that is still running, to be read at its next step boundary.
+     *
+     * The turn is not interrupted: work in flight finishes and the model reads the message as
+     * the user talking mid-task.
+     */
+    steer?(request: TransportSteerRequest): Promise<SteerResult>;
     /**
      * Watches a turn that is already running, without starting one.
      *

package/dist/modules/transport_link.d.ts

@@ -1,5 +1,5 @@
 import type { Link } from "../link/link";
-import { ConversationStream, ConversationTransport, TransportAttachRequest, TransportHandlers, TransportTurnRequest } from "./transport";
+import { ConversationStream, ConversationTransport, SteerResult, TransportAttachRequest, TransportHandlers, TransportSteerRequest, TransportStopRequest, TransportTurnRequest, TurnStopped } from "./transport";
 export type LinkSessionConfig = {
     model?: string;
     personality?: string;
@@ -20,6 +20,21 @@ export declare class LinkConversationTransport implements ConversationTransport
     private sessionChatId?;
     constructor(link: Link, config: () => LinkSessionConfig);
     send(request: TransportTurnRequest, handlers: TransportHandlers): ConversationStream;
+    /**
+     * Stops a running turn.
+     *
+     * Addressed by conversation rather than by session, so a client that reconnected — losing
+     * its session but not the turn — can still stop what it is watching. The turn's own stream
+     * ends normally afterwards, carrying whatever the model produced before the stop.
+     */
+    stop(request: TransportStopRequest): Promise<TurnStopped | undefined>;
+    /**
+     * Says something to a turn that is still running.
+     *
+     * A refusal is the interesting case: the caller is holding a message the user typed and
+     * has to send it as an ordinary turn instead of dropping it.
+     */
+    steer(request: TransportSteerRequest): Promise<SteerResult>;
     /** Ends the session, if one is open. The conversation can still be resumed later. */
     end(): Promise<void>;
     /**

package/dist/modules/transport_link.js

@@ -33,6 +33,49 @@ class LinkConversationTransport {
         });
         return { close: () => { closed = true; } };
     }
+    /**
+     * Stops a running turn.
+     *
+     * Addressed by conversation rather than by session, so a client that reconnected — losing
+     * its session but not the turn — can still stop what it is watching. The turn's own stream
+     * ends normally afterwards, carrying whatever the model produced before the stop.
+     */
+    async stop(request) {
+        try {
+            const frame = await this.link.exchange("conversation.stop", request, {
+                isDone: (reply) => reply.type === "conversation.stopped" || reply.type === "ack" || reply.type === "error",
+            });
+            if (frame.type !== "conversation.stopped")
+                return undefined;
+            const { mode, requestedMode, by } = frame.payload;
+            return { mode, requestedMode, by };
+        }
+        catch {
+            // Nothing was running, or the link is gone. Either way there is no turn to stop and
+            // nothing useful for the caller to do about it.
+            return undefined;
+        }
+    }
+    /**
+     * Says something to a turn that is still running.
+     *
+     * A refusal is the interesting case: the caller is holding a message the user typed and
+     * has to send it as an ordinary turn instead of dropping it.
+     */
+    async steer(request) {
+        try {
+            const frame = await this.link.exchange("conversation.steer", request, {
+                isDone: (reply) => reply.type === "conversation.steered" || reply.type === "ack" || reply.type === "error",
+            });
+            if (frame.type === "conversation.steered")
+                return { ok: true };
+            return { ok: false, reason: "no_turn" };
+        }
+        catch (error) {
+            const code = error instanceof protocol_1.LinkError ? error.code : undefined;
+            return { ok: false, reason: code === "too_late" ? "too_late" : "no_turn" };
+        }
+    }
     /** Ends the session, if one is open. The conversation can still be resumed later. */
     async end() {
         const sessionId = this.sessionId;

package/dist/modules/transport_sse.d.ts

@@ -1,5 +1,5 @@
 import { EventSource } from "eventsource";
-import { ConversationStream, ConversationTransport, TransportHandlers, TransportTurnRequest } from "./transport";
+import { ConversationStream, ConversationTransport, SteerResult, TransportHandlers, TransportSteerRequest, TransportStopRequest, TransportTurnRequest, TurnStopped } from "./transport";
 type StreamOptions = {
     debug?: boolean;
     onPayload(payload: {
@@ -20,9 +20,21 @@ export declare class SSEConversationTransport implements ConversationTransport {
     private readonly config;
     constructor(config: {
         endpoint(): string;
+        stopEndpoint?(): string;
+        steerEndpoint?(): string;
         apiKey: string;
         debug?: boolean;
     });
     send(request: TransportTurnRequest, handlers: TransportHandlers): ConversationStream;
+    /**
+     * The turn is a GET that streams until it is done, so an interruption cannot travel on the
+     * same request and gets one of its own.
+     *
+     * Closing the stream is deliberately not a stop: a reload, a backgrounded tab or a
+     * reconnect all drop the connection and all expect to pick the answer back up.
+     */
+    stop(request: TransportStopRequest): Promise<TurnStopped | undefined>;
+    steer(request: TransportSteerRequest): Promise<SteerResult>;
+    private post;
 }
 export {};

package/dist/modules/transport_sse.js

@@ -40,6 +40,54 @@ class SSEConversationTransport {
         });
         return { close: () => sse.close(), source: sse };
     }
+    /**
+     * The turn is a GET that streams until it is done, so an interruption cannot travel on the
+     * same request and gets one of its own.
+     *
+     * Closing the stream is deliberately not a stop: a reload, a backgrounded tab or a
+     * reconnect all drop the connection and all expect to pick the answer back up.
+     */
+    async stop(request) {
+        const endpoint = this.config.stopEndpoint?.();
+        if (!endpoint)
+            return undefined;
+        const response = await this.post(endpoint, { chatId: request.chatId, mode: request.mode });
+        // 404 is "nothing was running", which is the ordinary answer to stopping a moment late.
+        if (!response || response.status === 404)
+            return undefined;
+        const body = await response.json().catch(() => undefined);
+        return body?.stop;
+    }
+    async steer(request) {
+        const endpoint = this.config.steerEndpoint?.();
+        if (!endpoint)
+            return { ok: false, reason: "no_turn" };
+        const response = await this.post(endpoint, { chatId: request.chatId, message: request.message });
+        if (!response)
+            return { ok: false, reason: "no_turn" };
+        if (response.ok)
+            return { ok: true };
+        // 409: the turn is no longer accepting messages. The caller still has something the
+        // user typed and must send it as an ordinary turn.
+        return { ok: false, reason: response.status === 409 ? "too_late" : "no_turn" };
+    }
+    async post(endpoint, body) {
+        const url = (0, url_formatter_1.formatURL)(endpoint, undefined, { apiKey: this.config.apiKey, debug: this.config.debug });
+        try {
+            return await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (error) {
+            // A stop that cannot reach the server is not worth throwing over: the turn is
+            // ending on its own soon enough, and the caller has no better move to make.
+            if (this.config.debug)
+                console.warn(`[Interrupt failed: ${endpoint}]`, error);
+            return undefined;
+        }
+    }
 }
 exports.SSEConversationTransport = SSEConversationTransport;
 function asQuery(request) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.28",
+	"version": "0.0.30",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",