@butlerbot/sdk 0.0.18-alpha.2 → 0.0.18

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { APIPath } from "./config";
+import { Link, LinkOptions } from "./link";
 import { Conversation, ConversationOptions } from "./modules/conversation";
 import { UsagePolicyDataOptions } from "./modules/usage";
 type OptionalApiKey<T> = Omit<T, "apiKey"> & {
@@ -22,9 +23,18 @@ export declare class ButlerBotClient {
     healthCheck(healthCheckPath?: string): Promise<boolean>;
     /** Spawns a new Conversation, inherits api key and server URL */
     createConversation<V extends APIPath = "v4">(config?: OptionalApiKey<ConversationOptions<V>>): Conversation<V>;
+    /**
+     * Creates a Link: a live connection that can register tools and hooks, and carry
+     * conversations. Inherits the client's API key and server URL.
+     */
+    createLink(config: OptionalApiKey<LinkOptions>): Link;
     /** Get current usage policy data */
     getUsagePolicyData(config: OptionalApiKey<UsagePolicyDataOptions>): Promise<import("./types/usage/policy").UsagePolicyData>;
 }
 export * from "./types/type_registry";
+export * from "./link";
 export { Conversation, ConversationOptions };
 export type { APIPath };
+export type { ConversationStream, ConversationTransport, TransportTurnRequest, TransportHandlers, } from "./modules/transport";
+export { LinkConversationTransport } from "./modules/transport_link";
+export { SSEConversationTransport } from "./modules/transport_sse";

package/dist/index.js

@@ -13,18 +13,10 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Conversation = exports.ButlerBotClient = void 0;
+exports.SSEConversationTransport = exports.LinkConversationTransport = exports.Conversation = exports.ButlerBotClient = void 0;
 const config_1 = require("./config");
+const link_1 = require("./link");
 const conversation_1 = require("./modules/conversation");
 Object.defineProperty(exports, "Conversation", { enumerable: true, get: function () { return conversation_1.Conversation; } });
 const usage_1 = require("./modules/usage");
@@ -35,29 +27,39 @@ class ButlerBotClient {
         this.debug = config.debug || false;
     }
     /** Checks the health of the server returning true if server is alive */
-    healthCheck() {
-        return __awaiter(this, arguments, void 0, function* (healthCheckPath = config_1.CONFIG.healthcheckPath) {
-            const url = `${this.serverUrl}${healthCheckPath}`;
-            try {
-                const response = yield fetch(url);
-                return response.ok;
-            }
-            catch (error) {
-                if (this.debug)
-                    console.warn("[Healthcheck Failure]", error);
-                return false;
-            }
-        });
+    async healthCheck(healthCheckPath = config_1.CONFIG.healthcheckPath) {
+        const url = `${this.serverUrl}${healthCheckPath}`;
+        try {
+            const response = await fetch(url);
+            return response.ok;
+        }
+        catch (error) {
+            if (this.debug)
+                console.warn("[Healthcheck Failure]", error);
+            return false;
+        }
     }
     /** Spawns a new Conversation, inherits api key and server URL */
     createConversation(config = {}) {
-        return new conversation_1.Conversation(Object.assign({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl }, config));
+        return new conversation_1.Conversation({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...config });
+    }
+    /**
+     * Creates a Link: a live connection that can register tools and hooks, and carry
+     * conversations. Inherits the client's API key and server URL.
+     */
+    createLink(config) {
+        return new link_1.Link({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl, ...config });
     }
     /** Get current usage policy data */
     getUsagePolicyData(config) {
-        return (0, usage_1.getUsagePolicyData)(Object.assign({ serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug }, config));
+        return (0, usage_1.getUsagePolicyData)({ serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug, ...config });
     }
 }
 exports.ButlerBotClient = ButlerBotClient;
 // Expose types from subsequent modules
 __exportStar(require("./types/type_registry"), exports);
+__exportStar(require("./link"), exports);
+var transport_link_1 = require("./modules/transport_link");
+Object.defineProperty(exports, "LinkConversationTransport", { enumerable: true, get: function () { return transport_link_1.LinkConversationTransport; } });
+var transport_sse_1 = require("./modules/transport_sse");
+Object.defineProperty(exports, "SSEConversationTransport", { enumerable: true, get: function () { return transport_sse_1.SSEConversationTransport; } });

package/dist/link/hook.d.ts

@@ -0,0 +1,70 @@
+import { LinkHookDeclaration, LinkHookEventDeclaration } from "./protocol";
+import { JSONSchema, ToolSchema } from "./schema";
+export type HookConfig<S extends ToolSchema | undefined> = {
+    /**
+     * This hook's id within the link. The public id becomes `link:<linkId>/<id>`,
+     * which the user's background agents are subscribed to — so treat it as permanent.
+     */
+    id: string;
+    /** Human name, shown wherever hooks are listed. */
+    name: string;
+    /** What makes this hook fire. Read by whoever wires an agent up to it. */
+    description: string;
+    /** The events this hook can emit. Emitting an undeclared event is refused. */
+    events: LinkHookEventDeclaration[];
+    /**
+     * What an agent subscribing to this hook can configure — a filter, a threshold.
+     * A zod 4 schema, any Standard Schema, or a plain JSON Schema object.
+     */
+    schema?: S;
+    /** JSON Schema to send instead of deriving it from `schema`. */
+    jsonSchema?: JSONSchema;
+};
+/**
+ * A hook of any schema, which is what a link holds. See `AnyTool` for why this
+ * exists rather than a `Hook<...>`.
+ */
+export interface AnyHook {
+    readonly id: string;
+    sourceId?: string;
+    declaration(): LinkHookDeclaration;
+    attach(link: HookEmitter): void;
+}
+/** What a hook needs from its link in order to emit. Implemented by `Link`. */
+export type HookEmitter = {
+    /**
+     * Emits on the hook with this local id. The link resolves the public source id,
+     * which only exists once the hook has been registered.
+     */
+    emitHook(hookId: string, event: string, payload?: Record<string, unknown>, ownerId?: string): Promise<void>;
+};
+/**
+ * A source of events that can wake the user's background agents.
+ *
+ * A hook does not run anything itself: it announces that something happened, and
+ * the agents the user has subscribed to it decide what to do about that.
+ */
+export declare class Hook<S extends ToolSchema | undefined = undefined> {
+    private readonly config;
+    readonly id: string;
+    /** The public id (`link:<linkId>/<id>`), known once the link has registered it. */
+    sourceId?: string;
+    private link?;
+    constructor(config: HookConfig<S>);
+    get name(): string;
+    get events(): LinkHookEventDeclaration[];
+    /** The declaration sent to the server. */
+    declaration(): LinkHookDeclaration;
+    /** Called by `Link.addHook`. */
+    attach(link: HookEmitter): void;
+    /**
+     * Announces that one of this hook's events happened.
+     *
+     * Waits for the link to be connected if it is still coming up, so a hook can
+     * fire during startup without the caller sequencing it by hand.
+     *
+     * @param ownerId Global-scope links only: the user this event concerns. A
+     * user-scoped link is always stamped with its own owner and may not name another.
+     */
+    emit(event: string, payload?: Record<string, unknown>, ownerId?: string): Promise<void>;
+}

package/dist/link/hook.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Hook = void 0;
+const schema_1 = require("./schema");
+/**
+ * A source of events that can wake the user's background agents.
+ *
+ * A hook does not run anything itself: it announces that something happened, and
+ * the agents the user has subscribed to it decide what to do about that.
+ */
+class Hook {
+    constructor(config) {
+        this.config = config;
+        this.id = config.id;
+    }
+    get name() {
+        return this.config.name;
+    }
+    get events() {
+        return this.config.events;
+    }
+    /** The declaration sent to the server. */
+    declaration() {
+        return {
+            localId: this.id,
+            name: this.config.name,
+            description: this.config.description,
+            argsSchema: this.config.jsonSchema
+                ?? (this.config.schema ? (0, schema_1.toJSONSchema)(this.config.schema, this.id) : { type: "object", properties: {} }),
+            events: this.config.events,
+        };
+    }
+    /** Called by `Link.addHook`. */
+    attach(link) {
+        this.link = link;
+    }
+    /**
+     * Announces that one of this hook's events happened.
+     *
+     * Waits for the link to be connected if it is still coming up, so a hook can
+     * fire during startup without the caller sequencing it by hand.
+     *
+     * @param ownerId Global-scope links only: the user this event concerns. A
+     * user-scoped link is always stamped with its own owner and may not name another.
+     */
+    async emit(event, payload, ownerId) {
+        if (!this.link) {
+            throw new Error(`Hook "${this.id}" is not on a link yet — call link.addHook(hook) first.`);
+        }
+        // Caught here rather than on the wire: a typo should fail where it was made.
+        if (!this.config.events.some(declared => declared.name === event)) {
+            const declared = this.config.events.map(entry => entry.name).join(", ") || "none";
+            throw new Error(`Hook "${this.id}" does not declare an event named "${event}". Declared: ${declared}.`);
+        }
+        // The local id, not `sourceId`: emitting during startup gets here before
+        // registration has assigned one, and the link fills it in once it knows.
+        await this.link.emitHook(this.id, event, payload, ownerId);
+    }
+}
+exports.Hook = Hook;

package/dist/link/index.d.ts

@@ -0,0 +1,11 @@
+export { Link } from "./link";
+export type { LinkOptions, LinkEvents, LinkState, ExchangeOptions } from "./link";
+export { Tool } from "./tool";
+export type { AnyTool, ToolConfig, ToolRunContext, ToolCallMeta, ToolStatusReporter, ToolInvocation } from "./tool";
+export { Hook } from "./hook";
+export type { AnyHook, HookConfig, HookEmitter } from "./hook";
+export { LINK_PROTOCOL_VERSION, LinkError } from "./protocol";
+export type { LinkClientFrame, LinkClientFrameOf, LinkClientFrameType, LinkServerFrame, LinkServerFrameOf, LinkServerFrameType, LinkScopeKind, LinkToolDescriptor, LinkHookDeclaration, LinkHookEventDeclaration, } from "./protocol";
+export type { JSONSchema, StandardSchemaV1, ToolSchema, InferSchemaOutput } from "./schema";
+export { buildHandshake, defaultSocketFactory } from "./socket";
+export type { SocketFactory, SocketConnection, SocketHandlers } from "./socket";

package/dist/link/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultSocketFactory = exports.buildHandshake = exports.LinkError = exports.LINK_PROTOCOL_VERSION = exports.Hook = exports.Tool = exports.Link = void 0;
+var link_1 = require("./link");
+Object.defineProperty(exports, "Link", { enumerable: true, get: function () { return link_1.Link; } });
+var tool_1 = require("./tool");
+Object.defineProperty(exports, "Tool", { enumerable: true, get: function () { return tool_1.Tool; } });
+var hook_1 = require("./hook");
+Object.defineProperty(exports, "Hook", { enumerable: true, get: function () { return hook_1.Hook; } });
+var protocol_1 = require("./protocol");
+Object.defineProperty(exports, "LINK_PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_1.LINK_PROTOCOL_VERSION; } });
+Object.defineProperty(exports, "LinkError", { enumerable: true, get: function () { return protocol_1.LinkError; } });
+var socket_1 = require("./socket");
+Object.defineProperty(exports, "buildHandshake", { enumerable: true, get: function () { return socket_1.buildHandshake; } });
+Object.defineProperty(exports, "defaultSocketFactory", { enumerable: true, get: function () { return socket_1.defaultSocketFactory; } });

package/dist/link/link.d.ts

@@ -0,0 +1,142 @@
+import { AnyHook } from "./hook";
+import { LinkClientFrameType, LinkClientPayloads, LinkScopeKind, LinkServerFrame } from "./protocol";
+import { SocketFactory } from "./socket";
+import { AnyTool } from "./tool";
+export type LinkState = "idle" | "connecting" | "open" | "closed";
+export type LinkEvents = {
+    /** The link is connected and everything it holds has been registered. */
+    connect: [{
+        connectionId: string;
+        scope: LinkScopeKind;
+    }];
+    disconnect: [{
+        code: number;
+        reason: string;
+        willReconnect: boolean;
+    }];
+    /** A protocol or transport error. Fatal ones also stop reconnection. */
+    error: [Error];
+    /** Server-side chatter, useful when debugging. */
+    log: [string];
+    /** The server is shutting this connection down deliberately. */
+    goodbye: [{
+        reason: string;
+        reconnectAfterMs: number;
+    }];
+};
+export type LinkOptions = {
+    /** A user API key, or the service key for a global link. */
+    apiKey: string;
+    /**
+     * This link's name, chosen by you and stable forever.
+     *
+     * Every id the link creates is derived from it, and those ids are what the
+     * user's tool settings and background agent subscriptions point at — so changing
+     * it silently orphans both. Pick a deliberate constant ("coffee-machine"), never
+     * a hostname, a version, or a value generated at startup.
+     *
+     * Two live connections claiming the same linkId is last-writer-wins: the newer
+     * one takes over and the older one's registrations are released.
+     */
+    linkId: string;
+    serverUrl?: string;
+    /** Informational, shown in server logs. Defaults to the SDK name. */
+    client?: string;
+    debug?: boolean;
+    /** Reconnect automatically with backoff. Default true. */
+    reconnect?: boolean;
+    minReconnectDelayMs?: number;
+    maxReconnectDelayMs?: number;
+    /** Keeps idle connections alive through proxies. 0 disables. Default 30s. */
+    heartbeatMs?: number;
+    /** How long to wait for an acknowledgement. Turns are never timed out here. */
+    requestTimeoutMs?: number;
+    socketFactory?: SocketFactory;
+};
+export type ExchangeOptions = {
+    /** Which reply ends the exchange. Defaults to an `ack`. */
+    isDone?(frame: LinkServerFrame): boolean;
+    /** Called for every other reply, in order. */
+    onFrame?(frame: LinkServerFrame): void;
+    /** 0 waits forever, which is what a conversation turn needs. */
+    timeoutMs?: number;
+    /** Set false only for the handshake itself. */
+    awaitReady?: boolean;
+};
+/**
+ * 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.
+ */
+export declare class Link {
+    private readonly options;
+    private readonly emitter;
+    private readonly tools;
+    private readonly hooks;
+    private readonly pending;
+    private readonly calls;
+    private socket;
+    private frameCounter;
+    private currentState;
+    private identity?;
+    private connecting?;
+    private readySignal?;
+    private reconnectAttempt;
+    private reconnectAfterMs;
+    private heartbeat?;
+    private closedByUs;
+    constructor(options: LinkOptions);
+    /** Adds a tool Alfred can call. Registered on connect, or immediately if already open. */
+    addTool(tool: AnyTool): this;
+    /** Adds a hook that can wake the user's background agents. */
+    addHook(hook: AnyHook): this;
+    getTool(id: string): AnyTool | undefined;
+    getHook(id: string): AnyHook | undefined;
+    get state(): LinkState;
+    get linkId(): string;
+    /** The ephemeral id of this connection. Changes on every reconnect. */
+    get connectionId(): string | undefined;
+    /** Whether this link speaks for one user or for the whole service. */
+    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. */
+    connect(): Promise<this>;
+    /** Resolves when the link is usable, connecting first if it has not been asked to yet. */
+    ready(): Promise<void>;
+    /** Closes for good. Registrations are released server-side as the socket drops. */
+    close(reason?: string): void;
+    private openSocket;
+    private onOpen;
+    private onClose;
+    /**
+     * 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.
+     */
+    private scheduleReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private registerAll;
+    private registerTools;
+    private registerHook;
+    /** Called by `Hook.emit`. */
+    emitHook(hookId: string, event: string, payload?: Record<string, unknown>, ownerId?: string): Promise<void>;
+    /** Sends a frame without waiting for anything. Returns its id. */
+    send<T extends LinkClientFrameType>(type: T, payload: LinkClientPayloads[T], replyTo?: string): string;
+    /**
+     * 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.
+     */
+    exchange<T extends LinkClientFrameType>(type: T, payload: LinkClientPayloads[T], options?: ExchangeOptions): Promise<LinkServerFrame>;
+    private settle;
+    private failPending;
+    private onMessage;
+    private handleToolCall;
+    private debug;
+}