@butlerbot/sdk 0.0.18-alpha.3 → 0.0.19

package/dist/link/schema.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SCHEMAS
+ * =======
+ *
+ * A tool needs two things from its schema: JSON Schema to describe itself to the
+ * model, and a way to check the arguments that come back. Both are obtained
+ * without depending on any validation library — a Standard Schema (zod 3.24+,
+ * valibot, arktype, ...) provides validation through `~standard`, and a plain
+ * JSON Schema object is accepted as-is.
+ */
+export type JSONSchema = Record<string, unknown>;
+/**
+ * The Standard Schema v1 interface, vendored so this SDK needs no dependency.
+ * @see https://standardschema.dev
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            value: Output;
+            issues?: undefined;
+        } | {
+            issues: ReadonlyArray<{
+                message: string;
+                path?: ReadonlyArray<PropertyKey | {
+                    key: PropertyKey;
+                }>;
+            }>;
+        } | Promise<{
+            value: Output;
+            issues?: undefined;
+        } | {
+            issues: ReadonlyArray<{
+                message: string;
+                path?: ReadonlyArray<PropertyKey | {
+                    key: PropertyKey;
+                }>;
+            }>;
+        }>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+/** Anything accepted as a tool or hook schema. */
+export type ToolSchema = StandardSchemaV1 | {
+    toJSONSchema(): JSONSchema;
+} | JSONSchema;
+/**
+ * The argument type a schema produces, so `run({ args })` is typed from the
+ * schema rather than left as a bag of unknowns. Falls back to a loose record for
+ * a raw JSON Schema, which carries no type information.
+ */
+export type InferSchemaOutput<S> = S extends StandardSchemaV1<unknown, infer Output> ? Output : S extends {
+    _output: infer Output;
+} ? Output : Record<string, unknown>;
+/**
+ * Derives JSON Schema from whatever the caller supplied.
+ *
+ * Order matters: an explicit converter or a raw JSON Schema is used verbatim, and
+ * zod is only reached for when nothing else can answer.
+ */
+export declare function toJSONSchema(schema: ToolSchema, label: string): JSONSchema;
+export type ValidationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validates arguments if the schema can validate at all.
+ *
+ * The server deliberately does not check a client's tool arguments — the client
+ * authored the schema, so it owns the check. This is the only place it can happen,
+ * which is why a Standard Schema is worth passing.
+ */
+export declare function validateArgs<T>(schema: ToolSchema | undefined, args: unknown): Promise<ValidationResult<T>>;

package/dist/link/schema.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * SCHEMAS
+ * =======
+ *
+ * A tool needs two things from its schema: JSON Schema to describe itself to the
+ * model, and a way to check the arguments that come back. Both are obtained
+ * without depending on any validation library — a Standard Schema (zod 3.24+,
+ * valibot, arktype, ...) provides validation through `~standard`, and a plain
+ * JSON Schema object is accepted as-is.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJSONSchema = toJSONSchema;
+exports.validateArgs = validateArgs;
+function isStandardSchema(schema) {
+    return typeof schema === "object" && schema !== null && "~standard" in schema;
+}
+function hasOwnConverter(schema) {
+    return typeof schema?.toJSONSchema === "function";
+}
+function looksLikeJSONSchema(schema) {
+    if (typeof schema !== "object" || schema === null)
+        return false;
+    const keys = ["type", "properties", "$schema", "anyOf", "oneOf", "allOf", "enum", "const", "$ref"];
+    return keys.some(key => key in schema);
+}
+/** Loads zod only if the caller already has it, without upsetting bundlers. */
+function loadZod() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const load = eval("typeof require === 'function' ? require : undefined");
+        return load?.("zod");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Derives JSON Schema from whatever the caller supplied.
+ *
+ * Order matters: an explicit converter or a raw JSON Schema is used verbatim, and
+ * zod is only reached for when nothing else can answer.
+ */
+function toJSONSchema(schema, label) {
+    if (hasOwnConverter(schema))
+        return schema.toJSONSchema();
+    if (isStandardSchema(schema)) {
+        const zod = loadZod();
+        if (typeof zod?.toJSONSchema === "function") {
+            try {
+                return zod.toJSONSchema(schema, { io: "input" });
+            }
+            catch (error) {
+                throw new Error(`Could not convert the schema for "${label}" to JSON Schema: ${error.message}. `
+                    + `Pass \`jsonSchema\` explicitly instead.`);
+            }
+        }
+        throw new Error(`The schema for "${label}" needs zod 4+ to be converted to JSON Schema (zod 3 cannot). `
+            + `Either upgrade zod or pass \`jsonSchema\` alongside \`schema\`.`);
+    }
+    if (looksLikeJSONSchema(schema))
+        return schema;
+    throw new Error(`The schema for "${label}" is neither a JSON Schema nor a Standard Schema. `
+        + `Pass a zod 4 schema, any Standard Schema, or a plain JSON Schema object.`);
+}
+/**
+ * Validates arguments if the schema can validate at all.
+ *
+ * The server deliberately does not check a client's tool arguments — the client
+ * authored the schema, so it owns the check. This is the only place it can happen,
+ * which is why a Standard Schema is worth passing.
+ */
+async function validateArgs(schema, args) {
+    if (!schema || !isStandardSchema(schema))
+        return { ok: true, value: args };
+    const result = await schema["~standard"].validate(args);
+    if (!result.issues)
+        return { ok: true, value: result.value };
+    const described = result.issues
+        .map(issue => {
+        const path = (issue.path ?? [])
+            .map(segment => (typeof segment === "object" && segment !== null ? String(segment.key) : String(segment)))
+            .join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+    return { ok: false, error: `Invalid arguments — ${described}` };
+}

package/dist/link/socket.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SOCKETS
+ * =======
+ *
+ * A websocket handshake cannot carry headers in a browser, so the service and the
+ * credential travel as subprotocols, with the credential falling back to the query
+ * string when it contains characters a subprotocol token cannot hold.
+ *
+ * The global `WebSocket` is used where there is one (browsers, Node 22+). Node
+ * before that gets the `ws` package if it is installed.
+ */
+export type SocketHandlers = {
+    onOpen(): void;
+    onMessage(data: string): void;
+    onClose(code: number, reason: string): void;
+    onError(error: unknown): void;
+};
+export type SocketConnection = {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+};
+export type SocketFactory = (url: string, protocols: string[], handlers: SocketHandlers) => SocketConnection;
+export type HandshakeTarget = {
+    url: string;
+    protocols: string[];
+};
+/**
+ * Builds the websocket URL and subprotocols for a service.
+ *
+ * The credential prefers the subprotocol because a URL ends up in access logs.
+ */
+export declare function buildHandshake(serverUrl: string, service: string, apiKey: string): HandshakeTarget;
+export declare const defaultSocketFactory: SocketFactory;

package/dist/link/socket.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * SOCKETS
+ * =======
+ *
+ * A websocket handshake cannot carry headers in a browser, so the service and the
+ * credential travel as subprotocols, with the credential falling back to the query
+ * string when it contains characters a subprotocol token cannot hold.
+ *
+ * The global `WebSocket` is used where there is one (browsers, Node 22+). Node
+ * before that gets the `ws` package if it is installed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultSocketFactory = void 0;
+exports.buildHandshake = buildHandshake;
+const SERVICE_PROTOCOL_PREFIX = "butler.service.";
+const CREDENTIAL_PROTOCOL_PREFIX = "butler.key.";
+/** HTTP token characters, which is all a subprotocol may contain. */
+const TOKEN_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/**
+ * Builds the websocket URL and subprotocols for a service.
+ *
+ * The credential prefers the subprotocol because a URL ends up in access logs.
+ */
+function buildHandshake(serverUrl, service, apiKey) {
+    const url = new URL(serverUrl);
+    url.protocol = url.protocol === "http:" ? "ws:" : url.protocol === "https:" ? "wss:" : url.protocol;
+    url.searchParams.set("service", service);
+    const protocols = [`${SERVICE_PROTOCOL_PREFIX}${service}`];
+    if (TOKEN_PATTERN.test(apiKey))
+        protocols.push(`${CREDENTIAL_PROTOCOL_PREFIX}${apiKey}`);
+    else
+        url.searchParams.set("api_key", apiKey);
+    return { url: url.toString(), protocols };
+}
+function resolveWebSocket() {
+    const globalWebSocket = globalThis.WebSocket;
+    if (globalWebSocket)
+        return globalWebSocket;
+    try {
+        // Only reached on Node versions without a global WebSocket.
+        const load = eval("typeof require === 'function' ? require : undefined");
+        const ws = load?.("ws");
+        const constructor = ws?.WebSocket ?? ws;
+        if (constructor)
+            return constructor;
+    }
+    catch {
+        // Falls through to the error below.
+    }
+    throw new Error("No WebSocket implementation found. Use Node 22+, or install `ws`, "
+        + "or pass your own `socketFactory` to the Link.");
+}
+const defaultSocketFactory = (url, protocols, handlers) => {
+    const WebSocketImpl = resolveWebSocket();
+    const socket = new WebSocketImpl(url, protocols);
+    socket.addEventListener("open", (() => handlers.onOpen()));
+    socket.addEventListener("message", ((event) => {
+        handlers.onMessage(typeof event.data === "string" ? event.data : String(event.data));
+    }));
+    socket.addEventListener("close", ((event) => {
+        handlers.onClose(event.code ?? 1006, event.reason ?? "");
+    }));
+    socket.addEventListener("error", ((event) => handlers.onError(event)));
+    return {
+        send: (data) => socket.send(data),
+        close: (code, reason) => socket.close(code, reason),
+    };
+};
+exports.defaultSocketFactory = defaultSocketFactory;

package/dist/link/tool.d.ts

@@ -0,0 +1,95 @@
+import { LinkToolDescriptor } from "./protocol";
+import { InferSchemaOutput, JSONSchema, ToolSchema } from "./schema";
+/** Reports progress while a tool runs. Shown live in Alfred's tool status feed. */
+export type ToolStatusReporter = {
+    /** Replaces the current status label. */
+    update(label: string): void;
+    /** Marks the tool as failed in the UI. The thrown error still decides the result. */
+    fail(label: string): void;
+};
+export type ToolCallMeta = {
+    /** The user Alfred is acting for. */
+    userId: string;
+    /** The conversation the call came from, when it came from one. */
+    chatId?: string;
+    /** Unique per call, useful for logs. */
+    runId: string;
+};
+export type ToolRunContext<S extends ToolSchema | undefined> = {
+    /** Typed from `schema` when one was given. */
+    args: S extends ToolSchema ? InferSchemaOutput<S> : Record<string, unknown>;
+    meta: ToolCallMeta;
+    status: ToolStatusReporter;
+    /** Aborted when Alfred cancels the call or it times out server-side. */
+    signal: AbortSignal;
+};
+export type ToolConfig<S extends ToolSchema | undefined> = {
+    /**
+     * This tool's id within the link. The public id becomes `link:<linkId>/<id>`,
+     * which is what the user's saved settings refer to — so treat it as permanent.
+     */
+    id: string;
+    /** What the tool does. This is what the model reads to decide whether to call it. */
+    description: string;
+    /** 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;
+    /** Shown in Alfred's settings UI. Without it the tool is hidden there. */
+    display?: {
+        name: string;
+        shortDescription: string;
+        longDescription: string;
+    };
+    /** Whether the tool is on before the user has touched it. */
+    defaultEnabled?: boolean;
+    /** 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. */
+    run: (context: ToolRunContext<S>) => unknown | Promise<unknown>;
+};
+/**
+ * A tool of any schema, which is what a link holds.
+ *
+ * `Tool<S>` mentions `S` in its config, so a collection of tools with different
+ * schemas has no common `Tool<...>` type. This is the part a link actually uses,
+ * and every `Tool` satisfies it whatever its schema.
+ */
+export interface AnyTool {
+    readonly id: string;
+    linkedId?: string;
+    descriptor(): LinkToolDescriptor;
+    invoke(args: unknown, meta: ToolCallMeta, status: ToolStatusReporter, signal: AbortSignal): Promise<ToolInvocation>;
+}
+/** The outcome of one call, as reported back to the server. */
+export type ToolInvocation = {
+    ok: true;
+    output: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A tool that runs on your machine and that Alfred can call.
+ *
+ * Registered tools belong to the *user*, not to a conversation: once a link is
+ * connected Alfred can call them anywhere that user talks to it, including the web
+ * app and Discord.
+ */
+export declare class Tool<S extends ToolSchema | undefined = undefined> {
+    private readonly config;
+    readonly id: string;
+    /** The public id (`link:<linkId>/<id>`), known once the link has registered it. */
+    linkedId?: string;
+    constructor(config: ToolConfig<S>);
+    get description(): string;
+    /** The declaration sent to the server. */
+    descriptor(): LinkToolDescriptor;
+    /**
+     * Validates the arguments, runs the tool, and turns a throw into a failure.
+     *
+     * Never rejects: a call the server is waiting on must always get an answer, and
+     * a thrown error is a result like any other.
+     */
+    invoke(args: unknown, meta: ToolCallMeta, status: ToolStatusReporter, signal: AbortSignal): Promise<ToolInvocation>;
+}

package/dist/link/tool.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tool = void 0;
+const schema_1 = require("./schema");
+/**
+ * A tool that runs on your machine and that Alfred can call.
+ *
+ * Registered tools belong to the *user*, not to a conversation: once a link is
+ * connected Alfred can call them anywhere that user talks to it, including the web
+ * app and Discord.
+ */
+class Tool {
+    constructor(config) {
+        this.config = config;
+        this.id = config.id;
+    }
+    get description() {
+        return this.config.description;
+    }
+    /** The declaration sent to the server. */
+    descriptor() {
+        const inputSchema = this.config.jsonSchema
+            ?? (this.config.schema ? (0, schema_1.toJSONSchema)(this.config.schema, this.id) : { type: "object", properties: {} });
+        return {
+            localId: this.id,
+            description: this.config.description,
+            inputSchema,
+            ...(this.config.display ? { display: this.config.display } : {}),
+            ...(this.config.defaultEnabled !== undefined ? { defaultEnabled: this.config.defaultEnabled } : {}),
+            ...(this.config.timeoutMs !== undefined ? { timeoutMs: this.config.timeoutMs } : {}),
+        };
+    }
+    /**
+     * Validates the arguments, runs the tool, and turns a throw into a failure.
+     *
+     * Never rejects: a call the server is waiting on must always get an answer, and
+     * a thrown error is a result like any other.
+     */
+    async invoke(args, meta, status, signal) {
+        const validated = await (0, schema_1.validateArgs)(this.config.schema, args);
+        if (!validated.ok)
+            return { ok: false, error: validated.error };
+        try {
+            const output = await this.config.run({ args: validated.value, meta, status, signal });
+            return { ok: true, output };
+        }
+        catch (error) {
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}
+exports.Tool = Tool;

package/dist/modules/conversation.d.ts

@@ -1,5 +1,7 @@
 import { EventSource } from "eventsource";
 import { APIPath } from "../config";
+import type { Link } from "../link/link";
+import { ConversationStream } 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";
@@ -54,6 +56,14 @@ export type ConversationOptions<V extends APIPath = "v4"> = {
     debug?: boolean;
     /** The API version to use */
     chatApiV?: V;
+    /**
+     * How turns are carried.
+     *
+     * `"sse"` (the default) opens an HTTP stream per turn. Passing a connected `Link`
+     * instead carries turns over that websocket, reusing a connection you already
+     * have — everything else, including the payloads you receive, is identical.
+     */
+    transport?: "sse" | Link;
 };
 export declare class Conversation<V extends APIPath = "v4"> {
     convoId?: string;
@@ -62,6 +72,9 @@ export declare class Conversation<V extends APIPath = "v4"> {
     private chatApiV;
     private options?;
     private events;
+    private transport;
+    /** The link carrying this conversation, when it is not on SSE. */
+    readonly link?: Link;
     private endpoints;
     constructor(config: ConversationOptions<V>);
     /**
@@ -110,12 +123,6 @@ export declare class Conversation<V extends APIPath = "v4"> {
     getPlatform(): string | undefined;
     /** Gets the current personality configuration */
     getPersonality(): string | undefined;
-    private hasEmitter;
-    private addEmitter;
-    private removeEmitter;
-    private addListener;
-    private removeListener;
-    private emit;
     /**
      * Fires when the conversation ID is set
      * if convoId is already set when this is called, fires immediately
@@ -127,8 +134,7 @@ export declare class Conversation<V extends APIPath = "v4"> {
      * Fires once when the conversation ID is set, then removes the listener.
      * If convoId is already set, fires immediately
      */
-    onceConvoId(cb: (convoId: string) => any): `${string}-${string}-${string}-${string}-${string}` | undefined;
-    private handleSSE;
+    onceConvoId(cb: (convoId: string) => any): string | undefined;
     /** Fetches the conversation state from the server, including message history and metadata */
     fetchState(): Promise<ConversationStateResponse>;
     /** Fetches the conversation progress stream from the server */
@@ -142,6 +148,19 @@ export declare class Conversation<V extends APIPath = "v4"> {
         includeCompleted?: boolean;
     }): Promise<TurnProgressEntryForVersion<V>[] | undefined>;
     /** Sends a message into the conversation */
-    send(message: string, cb: (chunk: RequestResponseByVersion[V]) => any, options?: DialogueRequestOptions): EventSource;
+    send(message: string, cb: (chunk: RequestResponseByVersion[V]) => any, options?: DialogueRequestOptions): ConversationStream;
+    /**
+     * Sends a message and resolves with the finished reply.
+     *
+     * For when you want the answer rather than the stream. Every event still arrives
+     * through `onEvent` if you pass one.
+     */
+    ask(message: string, options?: DialogueRequestOptions & {
+        onEvent?: (chunk: RequestResponseByVersion[V]) => any;
+    }): Promise<{
+        text: string;
+        convoId?: string;
+        events: RequestResponseByVersion[V][];
+    }>;
 }
 export {};