@butlerbot/sdk 0.0.18-alpha.3 → 0.0.19

package/dist/link/link.js

@@ -0,0 +1,427 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Link = void 0;
+const config_1 = require("../config");
+const emitter_1 = require("../util/emitter");
+const protocol_1 = require("./protocol");
+const socket_1 = require("./socket");
+const DEFAULTS = {
+    minReconnectDelayMs: 500,
+    maxReconnectDelayMs: 30000,
+    heartbeatMs: 30000,
+    requestTimeoutMs: 30000,
+};
+/**
+ * A live connection to Alfred that carries tools, hooks and conversations.
+ *
+ * The server keeps no record of a link between connections: everything is
+ * re-declared on connect, and ids are derived from your `linkId`, so a reconnect
+ * anywhere lands on the same saved settings and subscriptions.
+ */
+class Link {
+    constructor(options) {
+        this.emitter = new emitter_1.Emitter();
+        this.tools = new Map();
+        this.hooks = new Map();
+        this.pending = new Map();
+        this.calls = new Map();
+        this.socket = null;
+        this.frameCounter = 0;
+        this.currentState = "idle";
+        this.reconnectAttempt = 0;
+        this.reconnectAfterMs = 0;
+        this.closedByUs = false;
+        this.options = {
+            ...DEFAULTS,
+            reconnect: true,
+            debug: false,
+            client: "@butlerbot/sdk",
+            serverUrl: config_1.CONFIG.server,
+            socketFactory: socket_1.defaultSocketFactory,
+            ...stripUndefined(options),
+        };
+    }
+    // =============================================
+    // WHAT THE LINK HOLDS
+    // =============================================
+    /** Adds a tool Alfred can call. Registered on connect, or immediately if already open. */
+    addTool(tool) {
+        this.tools.set(tool.id, tool);
+        if (this.currentState === "open")
+            void this.registerTools([tool]);
+        return this;
+    }
+    /** Adds a hook that can wake the user's background agents. */
+    addHook(hook) {
+        this.hooks.set(hook.id, hook);
+        hook.attach(this);
+        if (this.currentState === "open")
+            void this.registerHook(hook);
+        return this;
+    }
+    getTool(id) {
+        return this.tools.get(id);
+    }
+    getHook(id) {
+        return this.hooks.get(id);
+    }
+    // =============================================
+    // STATE
+    // =============================================
+    get state() {
+        return this.currentState;
+    }
+    get linkId() {
+        return this.options.linkId;
+    }
+    /** The ephemeral id of this connection. Changes on every reconnect. */
+    get connectionId() {
+        return this.identity?.connectionId;
+    }
+    /** Whether this link speaks for one user or for the whole service. */
+    get scope() {
+        return this.identity?.scope;
+    }
+    on(event, listener) {
+        return this.emitter.on(event, listener);
+    }
+    off(event, id) {
+        this.emitter.off(event, id);
+    }
+    // =============================================
+    // LIFECYCLE
+    // =============================================
+    /** Connects, resolving once every tool and hook has been registered. */
+    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;
+    }
+    /** Resolves when the link is usable, connecting first if it has not been asked to yet. */
+    async ready() {
+        if (this.currentState === "open")
+            return;
+        if (this.currentState === "closed")
+            throw new Error("This link has been closed.");
+        await this.connect();
+    }
+    /** Closes for good. Registrations are released server-side as the socket drops. */
+    close(reason = "client closed") {
+        this.closedByUs = true;
+        this.currentState = "closed";
+        this.stopHeartbeat();
+        this.failPending(new protocol_1.LinkError("closed", "The link was closed."));
+        this.socket?.close(1000, reason);
+        this.socket = null;
+        this.connecting = undefined;
+        this.readySignal = undefined;
+    }
+    openSocket() {
+        this.currentState = "connecting";
+        const signal = deferred();
+        this.readySignal = signal;
+        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)),
+            });
+        }
+        catch (error) {
+            signal.reject(asError(error));
+        }
+        return signal.promise;
+    }
+    onOpen() {
+        // The handshake declares who we are; nothing else may be sent before it.
+        void this.exchange("hello", {
+            linkId: this.options.linkId,
+            client: this.options.client,
+            protocolVersion: protocol_1.LINK_PROTOCOL_VERSION,
+        }, {
+            awaitReady: false,
+            isDone: (frame) => frame.type === "welcome",
+        }).then(async (frame) => {
+            const welcome = frame.payload;
+            this.identity = { connectionId: welcome.connectionId, scope: welcome.scope };
+            await this.registerAll();
+            this.currentState = "open";
+            this.reconnectAttempt = 0;
+            this.reconnectAfterMs = 0;
+            this.startHeartbeat();
+            this.readySignal?.resolve();
+            this.emitter.emit("connect", this.identity);
+        }).catch((error) => {
+            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");
+        });
+    }
+    onClose(code, reason) {
+        const willReconnect = this.options.reconnect && !this.closedByUs;
+        this.socket = null;
+        this.identity = undefined;
+        this.connecting = undefined;
+        this.currentState = willReconnect ? "connecting" : "closed";
+        this.stopHeartbeat();
+        this.failPending(new protocol_1.LinkError("disconnected", `The link disconnected (${code}${reason ? `: ${reason}` : ""}).`));
+        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();
+    }
+    /**
+     * Reconnects with full jitter on top of any delay the server asked for.
+     *
+     * A fleet told to reconnect must not come back in unison, which is exactly what
+     * a fixed delay produces.
+     */
+    scheduleReconnect() {
+        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)
+                return;
+            this.openSocket().catch(error => this.emitter.emit("error", asError(error)));
+        }, delay);
+        unref(timer);
+    }
+    startHeartbeat() {
+        if (!this.options.heartbeatMs)
+            return;
+        this.heartbeat = setInterval(() => {
+            // The reply is consumed by the exchange, so it never reaches log listeners.
+            this.exchange("ping", {}, { isDone: (frame) => frame.type === "log" })
+                .catch(() => undefined);
+        }, this.options.heartbeatMs);
+        unref(this.heartbeat);
+    }
+    stopHeartbeat() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = undefined;
+    }
+    // =============================================
+    // REGISTRATION
+    // =============================================
+    async registerAll() {
+        await this.registerTools(Array.from(this.tools.values()));
+        for (const hook of this.hooks.values())
+            await this.registerHook(hook);
+    }
+    async registerTools(tools) {
+        if (!tools.length)
+            return;
+        const frame = await this.exchange("tool.register", { tools: tools.map(tool => tool.descriptor()) }, { awaitReady: false });
+        const ids = frame.payload.ids ?? [];
+        // Ids come back in declaration order; taking them from the server rather than
+        // rebuilding them here keeps the id format in one place.
+        tools.forEach((tool, index) => { tool.linkedId = ids[index]; });
+        this.debug(`registered ${tools.length} tool(s)`);
+    }
+    async registerHook(hook) {
+        const frame = await this.exchange("hook.register", hook.declaration(), { awaitReady: false });
+        hook.sourceId = frame.payload.ids?.[0];
+        this.debug(`registered hook ${hook.id}`);
+    }
+    /** Called by `Hook.emit`. */
+    async emitHook(hookId, event, payload, ownerId) {
+        await this.ready();
+        // Resolved after waiting, not before: an emit issued during startup would
+        // otherwise carry the local id, which the server does not know.
+        const sourceId = this.hooks.get(hookId)?.sourceId ?? hookId;
+        this.send("hook.emit", {
+            sourceId,
+            event,
+            ...(payload ? { payload } : {}),
+            ...(ownerId ? { ownerId } : {}),
+        });
+    }
+    // =============================================
+    // FRAMES
+    // =============================================
+    /** Sends a frame without waiting for anything. Returns its id. */
+    send(type, payload, replyTo) {
+        const id = `c${++this.frameCounter}`;
+        const frame = { v: protocol_1.LINK_PROTOCOL_VERSION, id, type, payload, ...(replyTo ? { replyTo } : {}) };
+        if (!this.socket)
+            throw new protocol_1.LinkError("disconnected", "The link is not connected.");
+        this.socket.send(JSON.stringify(frame));
+        return id;
+    }
+    /**
+     * Sends a frame and waits for the reply that ends it.
+     *
+     * Intermediate replies (a turn's events, a status update) go to `onFrame`, and an
+     * `error` frame rejects — so a caller handles one outcome, not a stream of maybes.
+     */
+    async exchange(type, payload, options = {}) {
+        if (options.awaitReady !== false)
+            await this.ready();
+        const isDone = options.isDone ?? ((frame) => frame.type === "ack");
+        const timeoutMs = options.timeoutMs ?? this.options.requestTimeoutMs;
+        return new Promise((resolve, reject) => {
+            let id;
+            try {
+                id = this.send(type, payload);
+            }
+            catch (error) {
+                reject(asError(error));
+                return;
+            }
+            const entry = {
+                isDone,
+                onFrame: options.onFrame,
+                resolve: (frame) => { this.settle(id); resolve(frame); },
+                reject: (error) => { this.settle(id); reject(error); },
+            };
+            if (timeoutMs > 0) {
+                entry.timer = setTimeout(() => {
+                    entry.reject(new protocol_1.LinkError("timeout", `No reply to "${type}" within ${timeoutMs}ms.`));
+                }, timeoutMs);
+                unref(entry.timer);
+            }
+            this.pending.set(id, entry);
+        });
+    }
+    settle(id) {
+        const entry = this.pending.get(id);
+        if (entry?.timer)
+            clearTimeout(entry.timer);
+        this.pending.delete(id);
+    }
+    failPending(error) {
+        for (const entry of Array.from(this.pending.values()))
+            entry.reject(error);
+        this.pending.clear();
+        for (const controller of Array.from(this.calls.values()))
+            controller.abort();
+        this.calls.clear();
+    }
+    onMessage(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            this.emitter.emit("error", new protocol_1.LinkError("bad_frame", `Unparseable frame from the server: ${raw.slice(0, 200)}`));
+            return;
+        }
+        // A reply belongs to whoever is waiting on it, and never reaches the general
+        // handlers below.
+        const waiting = frame.replyTo ? this.pending.get(frame.replyTo) : undefined;
+        if (waiting) {
+            if (frame.type === "error") {
+                const { code, error, fatal } = frame.payload;
+                waiting.reject(new protocol_1.LinkError(code, error, fatal));
+                return;
+            }
+            if (waiting.isDone(frame))
+                waiting.resolve(frame);
+            else
+                waiting.onFrame?.(frame);
+            return;
+        }
+        switch (frame.type) {
+            case "tool.call":
+                this.handleToolCall(frame);
+                return;
+            case "tool.cancel": {
+                const { callId, reason } = frame.payload;
+                this.calls.get(callId)?.abort();
+                this.calls.delete(callId);
+                this.debug(`call ${callId} cancelled: ${reason}`);
+                return;
+            }
+            case "log":
+                this.emitter.emit("log", frame.payload.log);
+                return;
+            case "goodbye": {
+                const payload = frame.payload;
+                this.reconnectAfterMs = payload.reconnectAfterMs;
+                this.emitter.emit("goodbye", payload);
+                return;
+            }
+            case "error": {
+                const payload = frame.payload;
+                const error = new protocol_1.LinkError(payload.code, payload.error, payload.fatal);
+                if (payload.fatal)
+                    this.closedByUs = true;
+                this.emitter.emit("error", error);
+                return;
+            }
+            default:
+                this.debug(`unhandled frame "${frame.type}"`);
+        }
+    }
+    handleToolCall(frame) {
+        const { callId, localId, args, meta } = frame.payload;
+        const tool = this.tools.get(localId);
+        if (!tool) {
+            this.send("tool.result", { ok: false, error: `This link has no tool "${localId}".` }, frame.id);
+            return;
+        }
+        const controller = new AbortController();
+        this.calls.set(callId, controller);
+        const status = {
+            update: (label) => this.send("tool.status", { label, state: "running" }, frame.id),
+            fail: (label) => this.send("tool.status", { label, state: "failed" }, frame.id),
+        };
+        void tool.invoke(args, meta, status, controller.signal).then(result => {
+            this.calls.delete(callId);
+            // The socket may have gone while the tool ran; the server has already
+            // given up on the call, so there is nothing to report to.
+            if (!this.socket)
+                return;
+            this.send("tool.result", result.ok
+                ? { ok: true, output: result.output }
+                : { ok: false, error: result.error }, frame.id);
+        });
+    }
+    debug(message) {
+        if (this.options.debug)
+            console.log(`[link:${this.options.linkId}] ${message}`);
+    }
+}
+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;
+    const message = value?.message;
+    return new Error(message ?? "Unknown link error");
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+/** Keeps timers from holding a Node process open. No-op in browsers. */
+function unref(timer) {
+    timer?.unref?.();
+}

package/dist/link/protocol.d.ts

@@ -0,0 +1,186 @@
+import { ConversationEvent } from "../types/response/v5";
+/**
+ * LINK WIRE PROTOCOL (client side)
+ * ===============================
+ *
+ * The mirror of the server's protocol definition. Every frame is an envelope:
+ * `{ v, id, type, replyTo?, payload }`, where `replyTo` carries the id of the
+ * frame being answered — that is what makes request/response work over a stream.
+ *
+ * Keep this in step with the server. Fields are only ever added, never
+ * repurposed, so an older SDK stays correct against a newer server.
+ */
+export declare const LINK_PROTOCOL_VERSION = 1;
+export type LinkToolDescriptor = {
+    localId: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    display?: {
+        name: string;
+        shortDescription: string;
+        longDescription: string;
+    };
+    defaultEnabled?: boolean;
+    timeoutMs?: number;
+};
+export type LinkHookEventDeclaration = {
+    name: string;
+    description?: string;
+    /** Field name to human description, shown to whoever configures the hook. */
+    payloadShape?: Record<string, string>;
+};
+export type LinkHookDeclaration = {
+    localId: string;
+    name: string;
+    description: string;
+    argsSchema: Record<string, unknown>;
+    events: LinkHookEventDeclaration[];
+};
+export type LinkClientPayloads = {
+    "hello": {
+        linkId: string;
+        client?: string;
+        protocolVersion?: number;
+    };
+    "ping": {
+        message?: string;
+    };
+    "tool.register": {
+        tools: LinkToolDescriptor[];
+    };
+    "tool.result": {
+        ok: true;
+        output: unknown;
+        cost?: number;
+    } | {
+        ok: false;
+        error: string;
+    };
+    "tool.status": {
+        label: string;
+        state?: "running" | "completed" | "failed";
+    };
+    "hook.register": LinkHookDeclaration;
+    "hook.emit": {
+        sourceId: string;
+        event: string;
+        payload?: Record<string, unknown>;
+        ownerId?: string;
+    };
+    "conversation.start": {
+        chatId?: string;
+        model?: string;
+        personality?: string;
+        instructions?: string;
+        platform?: string;
+    };
+    "conversation.chat": {
+        sessionId: string;
+        message: string;
+        model?: string;
+        instructions?: string;
+        personality?: string;
+    };
+    "conversation.end": {
+        sessionId: string;
+    };
+};
+export type LinkClientFrameType = keyof LinkClientPayloads;
+/**
+ * A union of one member per frame type, rather than one type whose `type` and
+ * `payload` are both unions — otherwise checking `frame.type` narrows nothing and
+ * `payload` stays a union of every payload.
+ */
+export type LinkClientFrame = {
+    [T in LinkClientFrameType]: {
+        v: number;
+        id: string;
+        type: T;
+        replyTo?: string;
+        payload: LinkClientPayloads[T];
+    };
+}[LinkClientFrameType];
+/** One specific client frame, e.g. `LinkClientFrameOf<"tool.result">`. */
+export type LinkClientFrameOf<T extends LinkClientFrameType> = Extract<LinkClientFrame, {
+    type: T;
+}>;
+export type LinkScopeKind = "user" | "global";
+export type LinkServerPayloads = {
+    "welcome": {
+        connectionId: string;
+        linkId: string;
+        scope: LinkScopeKind;
+        protocolVersion: number;
+    };
+    "ack": {
+        ids?: string[];
+        message?: string;
+    };
+    "error": {
+        code: string;
+        error: string;
+        fatal?: boolean;
+    };
+    "log": {
+        log: string;
+    };
+    "tool.call": {
+        callId: string;
+        localId: string;
+        args: unknown;
+        meta: {
+            userId: string;
+            chatId?: string;
+            runId: string;
+        };
+        timeoutMs: number;
+    };
+    "tool.cancel": {
+        callId: string;
+        reason: string;
+    };
+    "conversation.open": {
+        sessionId: string;
+        chatId?: string;
+    };
+    "conversation.event": {
+        chatId?: string;
+        event: ConversationEvent;
+    };
+    "conversation.notice": {
+        chatId?: string;
+        message: string;
+    };
+    "conversation.done": {
+        chatId?: string;
+        ok: boolean;
+        code?: string;
+        error?: string;
+        message?: string;
+    };
+    "goodbye": {
+        reason: string;
+        reconnectAfterMs: number;
+    };
+};
+export type LinkServerFrameType = keyof LinkServerPayloads;
+/** A union of one member per frame type, so `frame.type` narrows `frame.payload`. */
+export type LinkServerFrame = {
+    [T in LinkServerFrameType]: {
+        v?: number;
+        id: string;
+        type: T;
+        replyTo?: string;
+        payload: LinkServerPayloads[T];
+    };
+}[LinkServerFrameType];
+/** One specific server frame, e.g. `LinkServerFrameOf<"conversation.done">`. */
+export type LinkServerFrameOf<T extends LinkServerFrameType> = Extract<LinkServerFrame, {
+    type: T;
+}>;
+/** An error reported by the server, carrying the code it used. */
+export declare class LinkError extends Error {
+    readonly code: string;
+    readonly fatal: boolean;
+    constructor(code: string, message: string, fatal?: boolean);
+}

package/dist/link/protocol.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinkError = exports.LINK_PROTOCOL_VERSION = void 0;
+/**
+ * LINK WIRE PROTOCOL (client side)
+ * ===============================
+ *
+ * The mirror of the server's protocol definition. Every frame is an envelope:
+ * `{ v, id, type, replyTo?, payload }`, where `replyTo` carries the id of the
+ * frame being answered — that is what makes request/response work over a stream.
+ *
+ * Keep this in step with the server. Fields are only ever added, never
+ * repurposed, so an older SDK stays correct against a newer server.
+ */
+exports.LINK_PROTOCOL_VERSION = 1;
+/** An error reported by the server, carrying the code it used. */
+class LinkError extends Error {
+    constructor(code, message, fatal = false) {
+        super(message);
+        this.code = code;
+        this.fatal = fatal;
+        this.name = "LinkError";
+    }
+}
+exports.LinkError = LinkError;