@butlerbot/sdk 0.0.22 → 0.0.24

package/dist/link/link.d.ts

@@ -91,8 +91,22 @@ export declare class Link {
     private frameCounter;
     private currentState;
     private identity?;
-    private connecting?;
-    private readySignal?;
+    /**
+     * Which socket the callbacks below belong to.
+     *
+     * Every handler carries the generation it was made for and does nothing once that is
+     * no longer current. Without it a late `close` from a socket we have already replaced
+     * tears down its successor — one blip turning into a link that flaps for the life of
+     * the process.
+     */
+    private generation;
+    /** True from the moment a socket is created until it is open or gone. */
+    private attempting;
+    private reconnectTimer?;
+    /** Settled per attempt: this is what `connect()` awaits. */
+    private readonly attemptWaiters;
+    /** Settled when the link opens, however many attempts that takes. `ready()` awaits these. */
+    private readonly openWaiters;
     private reconnectAttempt;
     private reconnectAfterMs;
     private heartbeat?;
@@ -112,15 +126,45 @@ export declare class Link {
     get scope(): LinkScopeKind | undefined;
     on<K extends keyof LinkEvents>(event: K, listener: (...args: LinkEvents[K]) => unknown): string;
     off<K extends keyof LinkEvents>(event: K, id: string): void;
-    /** Connects, resolving once every tool and hook has been registered. */
+    /**
+     * Connects, resolving once every tool and hook has been registered.
+     *
+     * Rejects if *this* attempt fails. When `reconnect` is on the link keeps trying in
+     * the background regardless, so a caller can either await this again or just listen
+     * for the `connect` event.
+     */
     connect(): Promise<this>;
-    /** Resolves when the link is usable, connecting first if it has not been asked to yet. */
+    /**
+     * Resolves when the link is usable, connecting first if it has not been asked to yet.
+     *
+     * Bounded by `requestTimeoutMs`, and it never opens a socket of its own while one is
+     * in flight: the callers are hook emits and tool replies, which are worth sending now
+     * or not at all. Waiting out a long outage here used to mean a new connection per
+     * event.
+     */
     ready(): Promise<void>;
     /** Closes for good. Registrations are released server-side as the socket drops. */
     close(reason?: string): void;
+    /**
+     * Starts an attempt, but only when there is nothing to join.
+     *
+     * The single door to opening a socket: an attempt in flight, or a reconnect already
+     * waiting out its backoff, is the attempt.
+     */
+    private ensureAttempting;
     private openSocket;
     private onOpen;
+    /**
+     * Abandons a socket and treats it as closed right now.
+     *
+     * A connection that died without a close frame can take minutes to report it, or
+     * never, so the close is synthesised rather than waited for. Bumping the generation
+     * means the real event, whenever it turns up, is ignored.
+     */
+    private dropSocket;
     private onClose;
+    /** Retries when it is allowed to, and tells everyone waiting when it is not. */
+    private retryOrGiveUp;
     /**
      * Reconnects with full jitter on top of any delay the server asked for.
      *
@@ -128,8 +172,27 @@ export declare class Link {
      * a fixed delay produces.
      */
     private scheduleReconnect;
+    private clearReconnect;
+    /**
+     * Pings on an interval and, the important half, notices when a ping goes unanswered.
+     *
+     * A websocket can die without a close frame — a dropped route, a proxy that forgets
+     * the connection, a suspended machine — leaving both ends convinced they are
+     * connected while every frame sent into it vanishes. An unanswered ping is the only
+     * evidence this end will ever get, so it is treated as a dead connection and
+     * reconnected rather than swallowed.
+     */
     private startHeartbeat;
+    /**
+     * Never longer than the interval itself: a second ping in flight tells us nothing new.
+     *
+     * Floored so that a very short interval cannot declare a merely busy connection dead.
+     */
+    private heartbeatTimeoutMs;
     private stopHeartbeat;
+    /** Parks a caller until someone settles the list it was parked in. 0 waits forever. */
+    private wait;
+    private settleWaiters;
     private registerAll;
     private registerTools;
     private registerHook;

package/dist/link/link.js

@@ -30,6 +30,21 @@ class Link {
         this.socket = null;
         this.frameCounter = 0;
         this.currentState = "idle";
+        /**
+         * Which socket the callbacks below belong to.
+         *
+         * Every handler carries the generation it was made for and does nothing once that is
+         * no longer current. Without it a late `close` from a socket we have already replaced
+         * tears down its successor — one blip turning into a link that flaps for the life of
+         * the process.
+         */
+        this.generation = 0;
+        /** True from the moment a socket is created until it is open or gone. */
+        this.attempting = false;
+        /** Settled per attempt: this is what `connect()` awaits. */
+        this.attemptWaiters = [];
+        /** Settled when the link opens, however many attempts that takes. `ready()` awaits these. */
+        this.openWaiters = [];
         this.reconnectAttempt = 0;
         this.reconnectAfterMs = 0;
         this.closedByUs = false;
@@ -107,58 +122,101 @@ class Link {
     // =============================================
     // LIFECYCLE
     // =============================================
-    /** Connects, resolving once every tool and hook has been registered. */
+    /**
+     * Connects, resolving once every tool and hook has been registered.
+     *
+     * Rejects if *this* attempt fails. When `reconnect` is on the link keeps trying in
+     * the background regardless, so a caller can either await this again or just listen
+     * for the `connect` event.
+     */
     connect() {
         if (this.currentState === "open")
             return Promise.resolve(this);
-        if (this.connecting)
-            return this.connecting;
         this.closedByUs = false;
-        this.connecting = this.openSocket().then(() => this, error => {
-            this.connecting = undefined;
-            throw error;
-        });
-        return this.connecting;
+        if (this.currentState === "closed")
+            this.currentState = "idle";
+        // Joins whatever attempt is already in flight — or already scheduled — rather than
+        // racing a second socket against it.
+        const waited = this.wait(this.attemptWaiters, 0);
+        this.ensureAttempting();
+        return waited.then(() => this);
     }
-    /** Resolves when the link is usable, connecting first if it has not been asked to yet. */
+    /**
+     * Resolves when the link is usable, connecting first if it has not been asked to yet.
+     *
+     * Bounded by `requestTimeoutMs`, and it never opens a socket of its own while one is
+     * in flight: the callers are hook emits and tool replies, which are worth sending now
+     * or not at all. Waiting out a long outage here used to mean a new connection per
+     * event.
+     */
     async ready() {
         if (this.currentState === "open")
             return;
         if (this.currentState === "closed")
-            throw new Error("This link has been closed.");
-        await this.connect();
+            throw new protocol_1.LinkError("closed", "This link has been closed.");
+        const waited = this.wait(this.openWaiters, this.options.requestTimeoutMs);
+        this.ensureAttempting();
+        await waited;
     }
     /** Closes for good. Registrations are released server-side as the socket drops. */
     close(reason = "client closed") {
+        const closed = new protocol_1.LinkError("closed", "The link was closed.");
         this.closedByUs = true;
         this.currentState = "closed";
+        // Orphans the live socket's callbacks, so its close cannot reopen anything.
+        this.generation += 1;
+        this.attempting = false;
         this.stopHeartbeat();
-        this.failPending(new protocol_1.LinkError("closed", "The link was closed."));
+        this.clearReconnect();
+        this.failPending(closed);
+        this.settleWaiters(this.attemptWaiters, closed);
+        this.settleWaiters(this.openWaiters, closed);
         this.socket?.close(1000, reason);
         this.socket = null;
-        this.connecting = undefined;
-        this.readySignal = undefined;
+    }
+    /**
+     * Starts an attempt, but only when there is nothing to join.
+     *
+     * The single door to opening a socket: an attempt in flight, or a reconnect already
+     * waiting out its backoff, is the attempt.
+     */
+    ensureAttempting() {
+        if (this.closedByUs || this.currentState === "open")
+            return;
+        if (this.attempting || this.reconnectTimer)
+            return;
+        this.openSocket();
     }
     openSocket() {
         this.currentState = "connecting";
-        const signal = deferred();
-        this.readySignal = signal;
+        this.attempting = true;
+        const generation = ++this.generation;
         const { url, protocols } = (0, socket_1.buildHandshake)(this.options.serverUrl, "link", this.options.apiKey);
         this.debug(`connecting to ${url.replace(/api_key=[^&]+/, "api_key=***")}`);
         try {
             this.socket = this.options.socketFactory(url, protocols, {
-                onOpen: () => this.onOpen(),
-                onMessage: (data) => this.onMessage(data),
-                onClose: (code, reason) => this.onClose(code, reason),
-                onError: (error) => this.emitter.emit("error", asError(error)),
+                onOpen: () => this.onOpen(generation),
+                onMessage: (data) => { if (generation === this.generation)
+                    this.onMessage(data); },
+                onClose: (code, reason) => this.onClose(generation, code, reason),
+                onError: (error) => { if (generation === this.generation)
+                    this.emitter.emit("error", asError(error)); },
             });
         }
         catch (error) {
-            signal.reject(asError(error));
+            // A factory that throws never produces a close event, so this failure is
+            // reported and retried from here instead.
+            const failure = asError(error);
+            this.socket = null;
+            this.attempting = false;
+            this.emitter.emit("error", failure);
+            this.settleWaiters(this.attemptWaiters, failure);
+            this.retryOrGiveUp(failure);
         }
-        return signal.promise;
     }
-    onOpen() {
+    onOpen(generation) {
+        if (generation !== this.generation)
+            return;
         // The handshake declares who we are; nothing else may be sent before it.
         void this.exchange("hello", {
             linkId: this.options.linkId,
@@ -169,39 +227,88 @@ class Link {
             isDone: (frame) => frame.type === "welcome",
         }).then(async (frame) => {
             const welcome = frame.payload;
-            this.identity = { connectionId: welcome.connectionId, scope: welcome.scope };
+            const identity = { connectionId: welcome.connectionId, scope: welcome.scope };
+            this.identity = identity;
             await this.registerAll();
+            // Registration is several round trips; the socket may have gone during them.
+            if (generation !== this.generation)
+                return;
+            this.attempting = false;
             this.currentState = "open";
             this.reconnectAttempt = 0;
             this.reconnectAfterMs = 0;
-            this.startHeartbeat();
-            this.readySignal?.resolve();
-            this.emitter.emit("connect", this.identity);
+            this.startHeartbeat(generation);
+            this.settleWaiters(this.attemptWaiters);
+            this.settleWaiters(this.openWaiters);
+            this.emitter.emit("connect", identity);
         }).catch((error) => {
+            if (generation !== this.generation)
+                return;
             this.emitter.emit("error", error);
-            // A rejected claim or an unsupported protocol will not fix itself by
-            // trying again, so this stops rather than looping.
-            this.closedByUs = true;
-            this.readySignal?.reject(error);
-            this.socket?.close(1000, "handshake failed");
+            this.settleWaiters(this.attemptWaiters, error);
+            // Only the server saying "do not come back" stops us: a rejected claim or an
+            // unsupported protocol will not fix itself. Everything else that can land here —
+            // a timeout, a socket dropped mid-registration, a transient server error — is
+            // precisely what reconnecting is for. Treating all of it as fatal left the link
+            // dead for the life of the process.
+            if (error instanceof protocol_1.LinkError && error.fatal)
+                this.closedByUs = true;
+            this.dropSocket(generation, 1000, "handshake failed");
         });
     }
-    onClose(code, reason) {
+    /**
+     * Abandons a socket and treats it as closed right now.
+     *
+     * A connection that died without a close frame can take minutes to report it, or
+     * never, so the close is synthesised rather than waited for. Bumping the generation
+     * means the real event, whenever it turns up, is ignored.
+     */
+    dropSocket(generation, code, reason) {
+        if (generation !== this.generation)
+            return;
+        const socket = this.socket;
+        this.onClose(generation, code, reason);
+        try {
+            // 1006 is reserved and rejected by browsers; anything else we raise is a valid
+            // application code.
+            socket?.close(code === 1006 ? 1000 : code, reason);
+        }
+        catch {
+            // Already gone, which is the outcome we wanted anyway.
+        }
+    }
+    onClose(generation, code, reason) {
+        if (generation !== this.generation)
+            return;
+        // Whatever else this socket has to say is now somebody else's news.
+        this.generation += 1;
         const willReconnect = this.options.reconnect && !this.closedByUs;
+        const error = new protocol_1.LinkError("disconnected", `The link disconnected (${code}${reason ? `: ${reason}` : ""}).`);
         this.socket = null;
         this.identity = undefined;
-        this.connecting = undefined;
+        this.attempting = false;
         this.currentState = willReconnect ? "connecting" : "closed";
         // Nothing about subscriptions survives a socket: the server re-sends the set on every
         // connect, so holding the old one would only risk reporting against ids that are gone.
         this.subscriptionStore.reset();
         this.stopHeartbeat();
-        this.failPending(new protocol_1.LinkError("disconnected", `The link disconnected (${code}${reason ? `: ${reason}` : ""}).`));
+        this.failPending(error);
+        this.settleWaiters(this.attemptWaiters, error);
         this.emitter.emit("disconnect", { code, reason, willReconnect });
-        this.readySignal?.reject(new protocol_1.LinkError("disconnected", `The link disconnected (${code}).`));
-        this.readySignal = undefined;
         if (willReconnect)
             this.scheduleReconnect();
+        else
+            this.settleWaiters(this.openWaiters, error);
+    }
+    /** Retries when it is allowed to, and tells everyone waiting when it is not. */
+    retryOrGiveUp(error) {
+        if (this.options.reconnect && !this.closedByUs) {
+            this.currentState = "connecting";
+            this.scheduleReconnect();
+            return;
+        }
+        this.currentState = "closed";
+        this.settleWaiters(this.openWaiters, error);
     }
     /**
      * Reconnects with full jitter on top of any delay the server asked for.
@@ -210,33 +317,97 @@ class Link {
      * a fixed delay produces.
      */
     scheduleReconnect() {
+        this.clearReconnect();
         const ceiling = Math.min(this.options.maxReconnectDelayMs, this.options.minReconnectDelayMs * 2 ** this.reconnectAttempt);
         const delay = this.reconnectAfterMs + Math.random() * ceiling;
         this.reconnectAttempt += 1;
         this.debug(`reconnecting in ${Math.round(delay)}ms (attempt ${this.reconnectAttempt})`);
-        const timer = setTimeout(() => {
-            if (this.closedByUs)
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (this.closedByUs || this.currentState === "open" || this.attempting)
                 return;
-            this.openSocket().catch(error => this.emitter.emit("error", asError(error)));
+            this.openSocket();
         }, delay);
-        unref(timer);
+        unref(this.reconnectTimer);
+    }
+    clearReconnect() {
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
     }
-    startHeartbeat() {
+    /**
+     * Pings on an interval and, the important half, notices when a ping goes unanswered.
+     *
+     * A websocket can die without a close frame — a dropped route, a proxy that forgets
+     * the connection, a suspended machine — leaving both ends convinced they are
+     * connected while every frame sent into it vanishes. An unanswered ping is the only
+     * evidence this end will ever get, so it is treated as a dead connection and
+     * reconnected rather than swallowed.
+     */
+    startHeartbeat(generation) {
         if (!this.options.heartbeatMs)
             return;
+        this.stopHeartbeat();
         this.heartbeat = setInterval(() => {
+            if (generation !== this.generation)
+                return;
             // The reply is consumed by the exchange, so it never reaches log listeners.
-            this.exchange("ping", {}, { isDone: (frame) => frame.type === "log" })
-                .catch(() => undefined);
+            this.exchange("ping", {}, {
+                awaitReady: false,
+                isDone: (frame) => frame.type === "log",
+                timeoutMs: this.heartbeatTimeoutMs(),
+            }).catch(() => {
+                if (generation !== this.generation)
+                    return;
+                this.debug("heartbeat went unanswered, treating the connection as dead");
+                this.dropSocket(generation, 4000, "heartbeat timeout");
+            });
         }, this.options.heartbeatMs);
         unref(this.heartbeat);
     }
+    /**
+     * Never longer than the interval itself: a second ping in flight tells us nothing new.
+     *
+     * Floored so that a very short interval cannot declare a merely busy connection dead.
+     */
+    heartbeatTimeoutMs() {
+        return Math.max(250, Math.min(this.options.requestTimeoutMs, this.options.heartbeatMs));
+    }
     stopHeartbeat() {
         if (this.heartbeat)
             clearInterval(this.heartbeat);
         this.heartbeat = undefined;
     }
     // =============================================
+    // WAITING
+    // =============================================
+    /** Parks a caller until someone settles the list it was parked in. 0 waits forever. */
+    wait(waiters, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject };
+            if (timeoutMs > 0) {
+                waiter.timer = setTimeout(() => {
+                    const index = waiters.indexOf(waiter);
+                    if (index >= 0)
+                        waiters.splice(index, 1);
+                    reject(new protocol_1.LinkError("timeout", `The link was not open within ${timeoutMs}ms.`));
+                }, timeoutMs);
+                unref(waiter.timer);
+            }
+            waiters.push(waiter);
+        });
+    }
+    settleWaiters(waiters, error) {
+        for (const waiter of waiters.splice(0, waiters.length)) {
+            if (waiter.timer)
+                clearTimeout(waiter.timer);
+            if (error)
+                waiter.reject(error);
+            else
+                waiter.resolve();
+        }
+    }
+    // =============================================
     // REGISTRATION
     // =============================================
     async registerAll() {
@@ -269,7 +440,13 @@ class Link {
      * that was valid a moment ago is a race, not a bug worth complaining about.
      */
     async reportHookEvent(hookId, event, payload, chosenIds) {
-        await this.ready();
+        // Not `ready()`: a report is only worth anything now, and while the link is down the
+        // subscription set is empty anyway — so waiting would mean holding a busy guild's
+        // events open to match them against nothing.
+        if (this.currentState !== "open") {
+            this.debug(`dropped ${event}: the link is not connected`);
+            return [];
+        }
         const sourceId = this.hooks.get(hookId)?.sourceId ?? hookId;
         // Explicit ids are still checked against what this link actually holds. Not out of distrust of
         // the caller — the server checks again anyway — but because an id it was never given can only
@@ -490,15 +667,6 @@ exports.Link = Link;
 // =============================================
 // HELPERS
 // =============================================
-function deferred() {
-    let resolve;
-    let reject;
-    const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
-    // Rejections are surfaced through connect() and the error event; an unobserved
-    // one here must not take the process down.
-    promise.catch(() => undefined);
-    return { promise, resolve, reject };
-}
 function asError(value) {
     if (value instanceof Error)
         return value;

package/dist/link/protocol.d.ts

@@ -21,6 +21,7 @@ export type LinkToolDescriptor = {
         longDescription: string;
     };
     defaultEnabled?: boolean;
+    platforms?: string[];
     timeoutMs?: number;
 };
 export type LinkHookEventDeclaration = {

package/dist/link/tool.d.ts

@@ -64,6 +64,19 @@ export type ToolConfig<S extends ToolSchema | undefined> = {
     };
     /** Whether the tool is on before the user has touched it. */
     defaultEnabled?: boolean;
+    /**
+     * Where in Alfred the tool is reachable, as platform ids. Defaults to the user's chat.
+     *
+     * Say this when your client mirrors a whole platform. A Discord bot offering seventy tools does
+     * not want seventy entries in front of somebody having a conversation about their groceries — it
+     * wants them behind Alfred's Discord agent, which is one entry and already knows how to decide
+     * when Discord is relevant.
+     *
+     * Known values are Alfred's platform ids, e.g. `"platform.chat.user"` (the default) and
+     * `"platform.agent.discord"`. An unknown one is rejected at registration rather than ignored,
+     * because a tool reachable from nowhere is indistinguishable from a tool that is broken.
+     */
+    platforms?: string[];
     /** How long the server waits for a result before giving up. */
     timeoutMs?: number;
     /** Runs the tool. Return anything JSON-serialisable, or throw to fail the call. */

package/dist/link/tool.js

@@ -27,6 +27,7 @@ class Tool {
             inputSchema,
             ...(this.config.display ? { display: this.config.display } : {}),
             ...(this.config.defaultEnabled !== undefined ? { defaultEnabled: this.config.defaultEnabled } : {}),
+            ...(this.config.platforms ? { platforms: this.config.platforms } : {}),
             ...(this.config.timeoutMs !== undefined ? { timeoutMs: this.config.timeoutMs } : {}),
         };
     }

package/package.json

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

package/readme.md

@@ -156,6 +156,27 @@ Subscriptions are never persisted by the SDK. They arrive on connect, follow del
 connected, and are dropped on disconnect — so there is nothing to reconcile, and a restart is
 correct by construction.
 
+### Tools can belong to an agent instead of a chat
+
+By default a tool shows up where a user is talking to Alfred. If your client mirrors a whole
+platform, say so instead:
+
+```ts
+new Tool({
+    id: "discord_member_kick",
+    description: "Kick a member from a server.",
+    platforms: ["platform.agent.discord"],
+    run: async ({ args, meta }) => kick(meta.identities?.discord, args),
+});
+```
+
+Seventy tools in front of somebody asking about their groceries is not a feature. Behind Alfred's
+Discord agent they are one entry that already knows when Discord is relevant — and the agent keeps
+whatever tier and permission gating it carries, which tools bolted onto the chat would quietly skip.
+
+An unknown platform is rejected when you register, not ignored: a tool reachable from nowhere looks
+exactly like a tool that is broken.
+
 ### Tools belong to the user, not to a conversation
 
 Once a tool is registered, Alfred can call it anywhere that user talks to it — the web