@butlerbot/sdk 0.0.16 → 0.0.18-alpha.0

package/dist/config.d.ts

@@ -9,6 +9,9 @@ export declare const CONFIG: {
             v4: {
                 base: string;
             };
+            v5: {
+                base: string;
+            };
         };
         history: {
             chat: {
@@ -27,6 +30,10 @@ export declare const CONFIG: {
                 base: string;
                 stream: string;
             };
+            v5: {
+                base: string;
+                stream: string;
+            };
         };
         usage: {
             policy: {
@@ -37,3 +44,4 @@ export declare const CONFIG: {
         };
     };
 };
+export type APIPath = keyof typeof CONFIG.paths.conversation;

package/dist/config.js

@@ -8,6 +8,7 @@ exports.CONFIG = {
         conversation: {
             v3: { base: "/api/alfred/v3/chat" },
             v4: { base: "/api/alfred/v4/chat" },
+            v5: { base: "/api/alfred/v5/chat" },
         },
         history: {
             chat: {
@@ -21,7 +22,11 @@ exports.CONFIG = {
             v4: {
                 base: "/api/alfred/v4/chat/progress",
                 stream: "/api/alfred/v4/chat/progress/stream",
-            }
+            },
+            v5: {
+                base: "/api/alfred/v5/chat/progress",
+                stream: "/api/alfred/v5/chat/progress/stream",
+            },
         },
         usage: {
             policy: {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { APIPath } from "./config";
 import { Conversation, ConversationOptions } from "./modules/conversation";
 import { UsagePolicyDataOptions } from "./modules/usage";
 type OptionalApiKey<T> = Omit<T, "apiKey"> & {
@@ -20,9 +21,10 @@ export declare class ButlerBotClient {
     /** Checks the health of the server returning true if server is alive */
     healthCheck(healthCheckPath?: string): Promise<boolean>;
     /** Spawns a new Conversation, inherits api key and server URL */
-    createConversation(config?: OptionalApiKey<ConversationOptions>): Conversation;
+    createConversation<V extends APIPath = "v4">(config?: OptionalApiKey<ConversationOptions<V>>): Conversation<V>;
     /** Get current usage policy data */
     getUsagePolicyData(config: OptionalApiKey<UsagePolicyDataOptions>): Promise<import("./types/usage/policy").UsagePolicyData>;
 }
 export * from "./types/type_registry";
 export { Conversation, ConversationOptions };
+export type { APIPath };

package/dist/modules/conversation.d.ts

@@ -1,8 +1,10 @@
 import { EventSource } from "eventsource";
-import { CONFIG } from "../config";
-import { RequestResponseV4 } from "../types/type_registry";
+import { APIPath } from "../config";
+import { RequestResponseV3, RequestResponseV4 } from "../types/type_registry";
+import { RequestResponseV5 } from "../types/response/v5/dialogue_response_v5";
 import { ConversationStateResponse } from "../types/state/convo_state_response";
 import { TurnProgressEntry } from "../types/response/v4/turn_registry_v4";
+import { TurnProgressEntryV5 } from "../types/response/v5/turn_registry_v5";
 export type DialogueRequestParams = {
     /** Unique identifier for the chat session */
     chatId?: string;
@@ -18,8 +20,17 @@ export type DialogueRequestParams = {
     personality?: string;
 };
 export type DialogueRequestOptions = Omit<Omit<DialogueRequestParams, "message">, "chatId">;
-type APIPath = keyof typeof CONFIG.paths.conversation;
-export type ConversationOptions = {
+export interface RequestResponseByVersion {
+    v3: RequestResponseV3;
+    v4: RequestResponseV4;
+    v5: RequestResponseV5;
+}
+interface TurnProgressEntryByVersion {
+    v4: TurnProgressEntry;
+    v5: TurnProgressEntryV5;
+}
+export type TurnProgressEntryForVersion<V extends APIPath> = V extends keyof TurnProgressEntryByVersion ? TurnProgressEntryByVersion[V] : TurnProgressEntry;
+export type ConversationOptions<V extends APIPath = "v4"> = {
     /** The conversation ID to load the conversation from, server will error if this convo id doesn't exist */
     convoId?: string;
     /** The API key to use */
@@ -42,17 +53,17 @@ export type ConversationOptions = {
     /** Whether to enable debug logs */
     debug?: boolean;
     /** The API version to use */
-    chatApiV?: APIPath;
+    chatApiV?: V;
 };
-export type RequestResponse = RequestResponseV4;
-export declare class Conversation {
+export declare class Conversation<V extends APIPath = "v4"> {
     convoId?: string;
     apiKey: string;
     private debug;
+    private chatApiV;
     private options?;
     private events;
     private endpoints;
-    constructor(config: ConversationOptions);
+    constructor(config: ConversationOptions<V>);
     /**
      * Sets the endpoint where the request is sent to, appended to server URL
      * @deprecated Use setConversationEndpoint() instead
@@ -121,7 +132,7 @@ export declare class Conversation {
     /** Fetches the conversation state from the server, including message history and metadata */
     fetchState(): Promise<ConversationStateResponse>;
     /** Fetches the conversation progress stream from the server */
-    fetchProgressStream(cb: (chunk: RequestResponse) => any): EventSource;
+    fetchProgressStream(cb: (chunk: RequestResponseByVersion[V]) => any): EventSource;
     /**
      * Fetches the conversation progress from the server
      * Returns undefined if no active turn progress
@@ -129,8 +140,8 @@ export declare class Conversation {
     fetchProgress(options?: {
         lastEventId?: string;
         includeCompleted?: boolean;
-    }): Promise<TurnProgressEntry[] | undefined>;
+    }): Promise<TurnProgressEntryForVersion<V>[] | undefined>;
     /** Sends a message into the conversation */
-    send(message: string, cb: (chunk: RequestResponse) => any, options?: DialogueRequestOptions): EventSource;
+    send(message: string, cb: (chunk: RequestResponseByVersion[V]) => any, options?: DialogueRequestOptions): EventSource;
 }
 export {};

package/dist/modules/conversation.js

@@ -16,14 +16,17 @@ const url_formatter_1 = require("../util/url_formatter");
 const DEFAULT_CONVO_API_V = "v4";
 class Conversation {
     constructor(config) {
+        var _a, _b;
         this.events = new Map();
         this.convoId = config.convoId;
+        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];
         this.endpoints = {
-            conversation: serverUrl + (config.convoPath || config.path || config_1.CONFIG.paths.conversation[config.chatApiV || DEFAULT_CONVO_API_V].base),
+            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 || config_1.CONFIG.paths.progress.v4.stream),
-            progress: serverUrl + (config.progressPath || config_1.CONFIG.paths.progress.v4.base),
+            progressStream: serverUrl + (config.progressStreamPath || ((_a = progressConfig === null || progressConfig === void 0 ? void 0 : progressConfig.stream) !== null && _a !== void 0 ? _a : config_1.CONFIG.paths.progress.v4.stream)),
+            progress: serverUrl + (config.progressPath || ((_b = progressConfig === null || progressConfig === void 0 ? void 0 : progressConfig.base) !== null && _b !== void 0 ? _b : config_1.CONFIG.paths.progress.v4.base)),
         };
         this.apiKey = config.apiKey;
         this.debug = config.debug || false;
@@ -236,7 +239,12 @@ class Conversation {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.convoId)
                 throw new Error("Conversation ID is not set");
-            const url = (0, url_formatter_1.formatURL)(this.endpoints.progress, { chatId: this.convoId, includeCompleted: options === null || options === void 0 ? void 0 : options.includeCompleted }, { apiKey: this.apiKey, debug: this.debug });
+            const payload = {
+                chatId: this.convoId,
+            };
+            if ((options === null || options === void 0 ? void 0 : options.includeCompleted) !== undefined)
+                payload["includeCompleted"] = options.includeCompleted;
+            const url = (0, url_formatter_1.formatURL)(this.endpoints.progress, payload, { apiKey: this.apiKey, debug: this.debug });
             const response = yield fetch(url, { headers: (options === null || options === void 0 ? void 0 : options.lastEventId) ? { "last-event-id": options.lastEventId } : undefined });
             if (!response.ok) {
                 const errorText = yield response.text();

package/dist/modules/voice/client_link.d.ts

@@ -0,0 +1,69 @@
+import { Buffer } from "node:buffer";
+import { AudioClosePayload, AudioCodec, AudioOpenPayload, AudioOpenedPayload, AudioWakewordPayload, ClientLinkCapabilities, ClientLinkChannel, ClientLinkFrame, ClientLinkIdentity, ErrorPayload, InboundAudioFrame, WelcomePayload } from "./types";
+type ClientLinkEventMap = {
+    connected: [];
+    authenticated: [WelcomePayload];
+    disconnected: [{
+        code?: number;
+        explicit: boolean;
+    }];
+    error: [Error | ErrorPayload];
+    "audio.opened": [AudioOpenedPayload];
+    "audio.closed": [{
+        roomId?: string;
+        roomExternalRef?: string;
+    }];
+    "audio.frame": [InboundAudioFrame];
+    "audio.wakeword": [AudioWakewordPayload];
+};
+type ClientLinkEvent = keyof ClientLinkEventMap;
+type ClientLinkListener<T extends ClientLinkEvent> = (...args: ClientLinkEventMap[T]) => void;
+export type ClientLinkOptions = {
+    url: string;
+    token: string;
+    identity: ClientLinkIdentity;
+    capabilities?: ClientLinkCapabilities;
+    pingIntervalMs?: number;
+    autoReconnect?: boolean;
+    reconnectInitialDelayMs?: number;
+    debug?: boolean;
+};
+export declare class ClientLink {
+    private readonly options;
+    private ws;
+    private authenticated;
+    private explicitClose;
+    private reconnectAttempts;
+    private pingTimer;
+    private reconnectTimer;
+    private desiredAudioOpen;
+    private currentRoomId;
+    private outboundSeq;
+    private listeners;
+    constructor(options: ClientLinkOptions);
+    on<T extends ClientLinkEvent>(event: T, listener: ClientLinkListener<T>): this;
+    off<T extends ClientLinkEvent>(event: T, listener: ClientLinkListener<T>): this;
+    connect(): Promise<WelcomePayload>;
+    close(): void;
+    isAuthenticated(): boolean;
+    get roomId(): string | null;
+    openAudio(payload: AudioOpenPayload): void;
+    closeAudio(): void;
+    sendAudioFrame(data: Buffer, codec?: AudioCodec, flags?: {
+        activityStart?: boolean;
+        activityEnd?: boolean;
+    }): void;
+    sendWakeword(payload: AudioWakewordPayload): void;
+    private openSocket;
+    private handleText;
+    private handleControlFrame;
+    private handleAudioFrame;
+    private handleBinary;
+    private sendFrame;
+    private startPingLoop;
+    private clearPingTimer;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private emit;
+}
+export type { AudioClosePayload, AudioCodec, AudioOpenPayload, AudioOpenedPayload, AudioWakewordPayload, ClientLinkCapabilities, ClientLinkChannel, ClientLinkFrame, ClientLinkIdentity, ErrorPayload, InboundAudioFrame, WelcomePayload, };

package/dist/modules/voice/client_link.js

@@ -0,0 +1,275 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientLink = void 0;
+const node_buffer_1 = require("node:buffer");
+const ws_1 = __importDefault(require("ws"));
+const types_1 = require("./types");
+class ClientLink {
+    constructor(options) {
+        var _a, _b, _c, _d, _e;
+        this.ws = null;
+        this.authenticated = false;
+        this.explicitClose = false;
+        this.reconnectAttempts = 0;
+        this.pingTimer = null;
+        this.reconnectTimer = null;
+        this.desiredAudioOpen = null;
+        this.currentRoomId = null;
+        this.outboundSeq = 0;
+        this.listeners = {
+            connected: new Set(),
+            authenticated: new Set(),
+            disconnected: new Set(),
+            error: new Set(),
+            "audio.opened": new Set(),
+            "audio.closed": new Set(),
+            "audio.frame": new Set(),
+            "audio.wakeword": new Set(),
+        };
+        this.options = Object.assign(Object.assign({}, options), { capabilities: (_a = options.capabilities) !== null && _a !== void 0 ? _a : { channels: ["control", "audio"], wakeword: "server" }, pingIntervalMs: (_b = options.pingIntervalMs) !== null && _b !== void 0 ? _b : 25000, autoReconnect: (_c = options.autoReconnect) !== null && _c !== void 0 ? _c : true, reconnectInitialDelayMs: (_d = options.reconnectInitialDelayMs) !== null && _d !== void 0 ? _d : 1000, debug: (_e = options.debug) !== null && _e !== void 0 ? _e : false });
+    }
+    on(event, listener) {
+        this.listeners[event].add(listener);
+        return this;
+    }
+    off(event, listener) {
+        this.listeners[event].delete(listener);
+        return this;
+    }
+    connect() {
+        this.explicitClose = false;
+        return new Promise((resolve, reject) => {
+            const handleAuth = (payload) => {
+                this.off("authenticated", handleAuth);
+                this.off("error", handleError);
+                resolve(payload);
+            };
+            const handleError = (error) => {
+                this.off("authenticated", handleAuth);
+                this.off("error", handleError);
+                reject(error instanceof Error ? error : new Error(`${error.code}: ${error.message}`));
+            };
+            this.on("authenticated", handleAuth);
+            this.on("error", handleError);
+            this.openSocket();
+        });
+    }
+    close() {
+        this.explicitClose = true;
+        this.clearReconnectTimer();
+        this.clearPingTimer();
+        if (!this.ws)
+            return;
+        if (this.ws.readyState === ws_1.default.OPEN) {
+            this.sendFrame("control", "bye", {});
+        }
+        this.ws.close();
+        this.ws = null;
+    }
+    isAuthenticated() {
+        return this.authenticated;
+    }
+    get roomId() {
+        return this.currentRoomId;
+    }
+    openAudio(payload) {
+        this.desiredAudioOpen = payload;
+        this.sendFrame("audio", "audio.open", payload);
+    }
+    closeAudio() {
+        if (!this.desiredAudioOpen)
+            return;
+        const payload = {
+            roomExternalRef: this.desiredAudioOpen.roomExternalRef,
+        };
+        this.desiredAudioOpen = null;
+        this.currentRoomId = null;
+        this.sendFrame("audio", "audio.close", payload);
+    }
+    sendAudioFrame(data, codec = "pcm16", flags = {}) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN)
+            return;
+        const header = node_buffer_1.Buffer.allocUnsafe(types_1.AUDIO_HEADER_BYTES);
+        this.outboundSeq = (this.outboundSeq + 1) & 0xffff;
+        let flagByte = 0;
+        if (flags.activityStart)
+            flagByte |= types_1.AUDIO_FLAG.ACTIVITY_START;
+        if (flags.activityEnd)
+            flagByte |= types_1.AUDIO_FLAG.ACTIVITY_END;
+        header.writeUInt16BE(this.outboundSeq, 0);
+        header.writeUInt8(codec === "pcm16" ? types_1.AUDIO_CODEC_BYTE.pcm16 : types_1.AUDIO_CODEC_BYTE.opus, 2);
+        header.writeUInt8(flagByte, 3);
+        this.ws.send(concatBuffers(header, data));
+    }
+    sendWakeword(payload) {
+        this.sendFrame("audio", "audio.wakeword", payload);
+    }
+    openSocket() {
+        this.clearReconnectTimer();
+        this.authenticated = false;
+        this.ws = new ws_1.default(this.options.url);
+        this.ws.on("open", () => {
+            this.emit("connected");
+            const hello = {
+                token: this.options.token,
+                identity: this.options.identity,
+                capabilities: this.options.capabilities,
+            };
+            this.sendFrame("control", "hello", hello);
+        });
+        this.ws.on("message", (data, isBinary) => {
+            if (isBinary) {
+                this.handleBinary(rawDataToBuffer(data));
+                return;
+            }
+            this.handleText(data.toString("utf8"));
+        });
+        this.ws.on("close", (code) => {
+            this.authenticated = false;
+            this.clearPingTimer();
+            this.emit("disconnected", { code, explicit: this.explicitClose });
+            if (!this.explicitClose && this.options.autoReconnect) {
+                this.scheduleReconnect();
+            }
+        });
+        this.ws.on("error", (error) => {
+            this.emit("error", error);
+        });
+    }
+    handleText(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch (_a) {
+            this.emit("error", new Error("Invalid JSON frame received from ClientLink server"));
+            return;
+        }
+        if (frame.channel === "control") {
+            this.handleControlFrame(frame);
+            return;
+        }
+        if (frame.channel === "audio") {
+            this.handleAudioFrame(frame);
+        }
+    }
+    handleControlFrame(frame) {
+        switch (frame.type) {
+            case "welcome": {
+                const payload = frame.payload;
+                this.authenticated = true;
+                this.reconnectAttempts = 0;
+                this.startPingLoop();
+                this.emit("authenticated", payload);
+                if (this.desiredAudioOpen) {
+                    this.sendFrame("audio", "audio.open", this.desiredAudioOpen);
+                }
+                return;
+            }
+            case "pong":
+                return;
+            case "error":
+                this.emit("error", frame.payload);
+                return;
+        }
+    }
+    handleAudioFrame(frame) {
+        switch (frame.type) {
+            case "audio.opened": {
+                const payload = frame.payload;
+                this.currentRoomId = payload.roomId;
+                this.emit("audio.opened", payload);
+                return;
+            }
+            case "audio.closed": {
+                const payload = frame.payload;
+                this.currentRoomId = null;
+                this.emit("audio.closed", payload);
+                return;
+            }
+            case "audio.wakeword":
+                this.emit("audio.wakeword", frame.payload);
+                return;
+        }
+    }
+    handleBinary(data) {
+        if (data.length < types_1.AUDIO_HEADER_BYTES)
+            return;
+        const seqNum = data.readUInt16BE(0);
+        const codecByte = data.readUInt8(2);
+        const flags = data.readUInt8(3);
+        const payload = data.subarray(types_1.AUDIO_HEADER_BYTES);
+        this.emit("audio.frame", {
+            speakerId: "assistant",
+            data: payload,
+            codec: codecByte === types_1.AUDIO_CODEC_BYTE.pcm16 ? "pcm16" : "opus",
+            seqNum,
+            activityStart: (flags & types_1.AUDIO_FLAG.ACTIVITY_START) !== 0,
+            activityEnd: (flags & types_1.AUDIO_FLAG.ACTIVITY_END) !== 0,
+        });
+    }
+    sendFrame(channel, type, payload) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN)
+            return;
+        const frame = { channel, type, payload };
+        this.ws.send(JSON.stringify(frame));
+    }
+    startPingLoop() {
+        this.clearPingTimer();
+        this.pingTimer = setInterval(() => {
+            const payload = { ts: Date.now() };
+            this.sendFrame("control", "ping", payload);
+        }, this.options.pingIntervalMs);
+    }
+    clearPingTimer() {
+        if (!this.pingTimer)
+            return;
+        clearInterval(this.pingTimer);
+        this.pingTimer = null;
+    }
+    scheduleReconnect() {
+        this.clearReconnectTimer();
+        const delay = Math.min(30000, this.options.reconnectInitialDelayMs * Math.pow(2, this.reconnectAttempts));
+        this.reconnectAttempts += 1;
+        this.reconnectTimer = setTimeout(() => this.openSocket(), delay);
+    }
+    clearReconnectTimer() {
+        if (!this.reconnectTimer)
+            return;
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+    }
+    emit(event, ...args) {
+        for (const listener of this.listeners[event]) {
+            try {
+                listener(...args);
+            }
+            catch (error) {
+                if (this.options.debug) {
+                    console.warn(`[ClientLink:${event}] listener failed`, error);
+                }
+            }
+        }
+    }
+}
+exports.ClientLink = ClientLink;
+function concatBuffers(left, right) {
+    const out = node_buffer_1.Buffer.allocUnsafe(left.length + right.length);
+    left.copy(out, 0);
+    right.copy(out, left.length);
+    return out;
+}
+function rawDataToBuffer(data) {
+    if (node_buffer_1.Buffer.isBuffer(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return node_buffer_1.Buffer.from(data);
+    if (Array.isArray(data)) {
+        return node_buffer_1.Buffer.concat(data.map((part) => rawDataToBuffer(part)));
+    }
+    const view = data;
+    return node_buffer_1.Buffer.from(view.buffer, view.byteOffset, view.byteLength);
+}

package/dist/modules/voice/index.d.ts

@@ -0,0 +1,2 @@
+export { ClientLink } from "./client_link";
+export * from "./types";

package/dist/modules/voice/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientLink = void 0;
+var client_link_1 = require("./client_link");
+Object.defineProperty(exports, "ClientLink", { enumerable: true, get: function () { return client_link_1.ClientLink; } });
+__exportStar(require("./types"), exports);

package/dist/modules/voice/types.d.ts

@@ -0,0 +1,80 @@
+import type { Buffer } from "node:buffer";
+export type ClientLinkKind = "discord-bot" | "desktop" | "mobile" | "device" | "browser";
+export type ClientLinkChannel = "control" | "audio" | "tools" | "events";
+export type ClientLinkCapabilities = {
+    channels: ClientLinkChannel[];
+    /** Whether the client handles wakeword detection itself, or wants the server to */
+    wakeword?: "client" | "server";
+};
+export type ClientLinkIdentity = {
+    /** Stable UUID across reconnects for the same logical client */
+    linkId: string;
+    kind: ClientLinkKind;
+    displayName: string;
+};
+/** Text JSON frame envelope */
+export type ClientLinkFrame = {
+    channel: ClientLinkChannel;
+    type: string;
+    payload: unknown;
+};
+export declare const AUDIO_HEADER_BYTES = 4;
+export declare const AUDIO_CODEC_BYTE: {
+    readonly opus: 0;
+    readonly pcm16: 1;
+};
+export declare const AUDIO_FLAG: {
+    readonly ACTIVITY_START: 1;
+    readonly ACTIVITY_END: 2;
+};
+export type AudioCodec = "opus" | "pcm16";
+export type HelloPayload = {
+    /** JWT access token for the user that owns this link */
+    token: string;
+    identity: ClientLinkIdentity;
+    capabilities: ClientLinkCapabilities;
+};
+export type WelcomePayload = {
+    linkId: string;
+    serverVersion: string;
+};
+export type PingPayload = {
+    ts: number;
+};
+export type PongPayload = {
+    ts: number;
+    serverTs: number;
+};
+export type ErrorPayload = {
+    code: string;
+    message: string;
+};
+export type VoiceRoomMode = "off" | "transcribe" | "realtime";
+export type AudioOpenPayload = {
+    roomExternalRef: string;
+    roomKind: "discord" | "phone" | "device";
+    mode?: VoiceRoomMode;
+    wakewordHandledBy?: "client" | "server";
+};
+export type AudioClosePayload = {
+    roomExternalRef: string;
+};
+export type AudioOpenedPayload = {
+    roomId: string;
+    mode: VoiceRoomMode;
+    inputSampleRate: number;
+    outputSampleRate: number;
+};
+export type AudioWakewordPayload = {
+    speakerId: string;
+    confidence: number;
+};
+export type InboundAudioFrame = {
+    /** Server currently emits a fixed "assistant" speakerId for outbound model audio */
+    speakerId: string;
+    data: Buffer;
+    codec: AudioCodec;
+    seqNum: number;
+    activityStart: boolean;
+    activityEnd: boolean;
+};

package/dist/modules/voice/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDIO_FLAG = exports.AUDIO_CODEC_BYTE = exports.AUDIO_HEADER_BYTES = void 0;
+exports.AUDIO_HEADER_BYTES = 4;
+exports.AUDIO_CODEC_BYTE = {
+    opus: 0,
+    pcm16: 1,
+};
+exports.AUDIO_FLAG = {
+    ACTIVITY_START: 0b00000001,
+    ACTIVITY_END: 0b00000010,
+};

package/dist/types/response/v5/ai_response_v5.d.ts

@@ -0,0 +1,250 @@
+/** Display information for a participant */
+export type DisplayEntity = {
+    name?: string;
+    avatarUrl?: string;
+};
+/** Rich content that can be attached to tool status updates.
+ *  Clients can render these if supported, or fall back to just the `label` field on ToolStatus. */
+export type ToolStatusContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "code";
+    language: string;
+    code: string;
+} | {
+    type: "image";
+    url: string;
+    alt?: string;
+} | {
+    type: "progress";
+    current: number;
+    total: number;
+    label?: string;
+} | {
+    type: "data";
+    data: Record<string, unknown>;
+};
+/** Tool execution status. **/
+export type ToolStatus = {
+    /** Unique ID for this tool execution */
+    id: string;
+    /** Parent tool ID (for nested tool calls, e.g., agent sub-tools) */
+    parentId?: string;
+    /** Top-level status label — always available, suitable for minimal UI */
+    label: string;
+    /** Current state of the tool execution */
+    state: "running" | "completed" | "failed";
+    /** Optional rich content for clients that support it */
+    content?: ToolStatusContent[];
+    /** Whether this tool call is ending the conversation */
+    endingConvo?: boolean;
+};
+export type BaseResponseMetadata = {
+    /** Unique response ID */
+    responseId: string;
+    /** Model display name (e.g., "GPT-5") */
+    model: string;
+    /** Actual model ID (e.g., "openai/gpt-5.2") */
+    modelId: string;
+    /** Timestamp of first action (first stream chunk) */
+    firstTimestamp: number;
+    /** Timestamp of last action */
+    timestamp: number;
+    /** The participant who generated this response */
+    participantId?: string;
+};
+export type MessagePayload = {
+    /** The message content */
+    message: string;
+    /** The UUID of this message */
+    messageId: string;
+    /** Whether this message chunk is the final one */
+    completed: boolean;
+};
+export type ReasoningPayload = {
+    /** The reasoning content */
+    reasoning: string;
+    /** The UUID of this reasoning */
+    reasoningId: string;
+    /** Whether this reasoning chunk is the final one */
+    completed: boolean;
+};
+export type FilePayload = {
+    /** The file URL */
+    url?: string;
+    /** The media type of the file */
+    mediaType: string;
+};
+export type ToolPayload = {
+    /** The tool status */
+    status: ToolStatus;
+};
+export type ConvoStatusPayload = {
+    /** The state of the conversation.
+     * - `disabled`: The conversation has been permanently disabled and cannot be restarted.
+     * - `stopped`: The conversation has been stopped but can be restarted.
+     * - `started`: The conversation has been started/restarted.
+     */
+    state?: "disabled" | "stopped" | "started";
+    /** Short summary generated for this conversation */
+    shortSummary?: string;
+};
+export type ResponseStatusPayload = {
+    completed: boolean;
+    /**
+     * The reason why the engine finished the turn
+     *
+     * Can be one of the following:
+     * - `done`: model finished the turn
+     * - `error`: turn stopped because of an error
+     * - `max_steps`: turn finished because it reached the maximum number of steps defined in the conversation policy
+     * - `other`: turn stopped for other reasons
+     */
+    turnFinishReason?: EngineTurnFinishReason;
+    /** Rich response metadata — only present on the final `completed: true` event.
+     *  Populated by the post-processor after the response finishes and usage is available. */
+    metadata?: ResponseMetadata;
+};
+/** Token usage information */
+export type TokenUsage = {
+    /** The total number of input (prompt) tokens used. */
+    inputTokens: number;
+    /** Detailed information about the input tokens. */
+    inputTokensDetails: {
+        /** The number of cached input tokens read. */
+        cachedTokens: number;
+    };
+    /** The total number of output (completion) tokens used. */
+    outputTokens: number;
+    /** Detailed information about the output tokens. */
+    outputTokensDetails: {
+        /** The number of reasoning tokens used. */
+        reasoningTokens: number;
+    };
+    /** The total number of tokens used. */
+    totalTokens: number;
+    /** Total cost of the turn in USD */
+    cost?: number | null;
+    /** Upstream cost breakdown from the provider. */
+    costDetails?: {
+        /** Total upstream inference cost. */
+        upstreamInferenceCost?: number | null;
+        /** Upstream input (prompt) cost. */
+        upstreamInferenceInputCost: number;
+        /** Upstream output (completion) cost. */
+        upstreamInferenceOutputCost: number;
+    };
+};
+export type EngineTurnFinishReason = "error" | "done" | "max_steps" | "other";
+/** A user message event */
+export type UserMessageEvent = {
+    type: "user_message";
+    payload: MessagePayload;
+    metadata: BaseResponseMetadata & {
+        userId: string;
+    };
+};
+export type MessageEvent = {
+    type: "message";
+    payload: MessagePayload;
+    metadata: BaseResponseMetadata & {
+        display?: DisplayEntity;
+    };
+};
+export type ReasoningEvent = {
+    type: "reasoning";
+    payload: ReasoningPayload;
+    metadata: BaseResponseMetadata;
+};
+export type FileEvent = {
+    type: "file";
+    payload: FilePayload & {
+        base64?: string;
+    };
+    metadata: BaseResponseMetadata & {
+        display?: DisplayEntity;
+    };
+};
+export type ToolEvent = {
+    type: "tool";
+    event: "call";
+    payload: ToolPayload;
+    metadata: BaseResponseMetadata;
+} | {
+    type: "tool";
+    event: "input";
+    payload: {
+        toolName: string;
+        toolCallId: string;
+        input: string;
+        completed: boolean;
+    };
+};
+export type ResponseStatusEvent = {
+    type: "response_status";
+    payload: ResponseStatusPayload;
+};
+export type ConvoStatusEvent = {
+    type: "convo_status";
+    payload: ConvoStatusPayload;
+};
+/** A single routing attempt */
+export type RoutingAttempt = {
+    /** The model ID attempted. */
+    model: string;
+    /** The provider slug (e.g., "anthropic", "google"). */
+    provider: string;
+    /** HTTP status code from the attempt. */
+    status: number;
+};
+/** Routing metadata — shows how the request was routed across providers.
+ *  The last entry in `attempts` is the provider that ultimately served the response. */
+export type RoutingMetadata = {
+    /** Routing strategy used (e.g., "auto", "direct", "pareto"). */
+    strategy: string;
+    /** Region the request was routed to. */
+    region: string | null;
+    /** All routing attempts in order — last entry is the successful provider. */
+    attempts: RoutingAttempt[];
+    /** Human-readable routing summary. */
+    summary: string;
+};
+/** Detailed metadata about a completed response. **/
+export type ResponseMetadata = {
+    /** Unique response ID */
+    responseId: string;
+    /** Timestamp of first action (first stream chunk) */
+    firstTimestamp: number;
+    /** Timestamp of final response metadata creation */
+    timestamp: number;
+    /** The participant who generated this response */
+    participantId?: string;
+    /** Human-readable model name (e.g. "Claude-Sonnet") */
+    model: string;
+    /** Provider model identifier (e.g. "openai/gpt-5.2") */
+    modelId: string;
+    /** Model-specific information */
+    modelInfo: {
+        /** Maximum context length for this model */
+        contextLimit?: number;
+    };
+    /** Token usage details including cost from the provider (OpenRouter). */
+    usage: TokenUsage;
+    /** Compact estimated attribution of prompt/tool/message tokens for UI/debugging. */
+    usageBreakdown?: Record<string, unknown>;
+    /** Response timing */
+    timing: {
+        /** Milliseconds from turn start to first streamed event */
+        firstEventMs: number;
+        /** Total turn time in milliseconds */
+        totalMs: number;
+    };
+    /** Routing metadata — which providers were tried and who served the response. */
+    routing?: RoutingMetadata;
+};
+/** All possible events emitted during a conversation turn */
+export type ConversationEvent = UserMessageEvent | MessageEvent | ReasoningEvent | FileEvent | ToolEvent | ResponseStatusEvent | ConvoStatusEvent;
+/** Callback for streaming conversation events */
+export type ConversationEventCallback = (event: ConversationEvent) => void;
+export type AIResponseV5 = ConversationEvent;

package/dist/types/response/v5/ai_response_v5.js

@@ -0,0 +1,5 @@
+"use strict";
+// =============================================
+// DISPLAY
+// =============================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/response/v5/dialogue_response_v5.d.ts

@@ -0,0 +1,20 @@
+import { AIResponseV5 } from "./ai_response_v5";
+import { ErrorCode } from "../../error";
+export type RequestFailResponseV5 = {
+    success: false;
+    data: {
+        code: ErrorCode;
+        error: string;
+        message: string;
+        quitStream?: boolean;
+    };
+};
+export type RequestSuccessResponseV5 = {
+    success: true;
+    data: {
+        response: AIResponseV5;
+        convoId?: string;
+        quitStream?: boolean;
+    };
+};
+export type RequestResponseV5 = RequestFailResponseV5 | RequestSuccessResponseV5;

package/dist/types/response/v5/dialogue_response_v5.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/response/v5/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./dialogue_response_v5";
+export * from "./ai_response_v5";
+export * from "./turn_registry_v5";

package/dist/types/response/v5/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./dialogue_response_v5"), exports);
+__exportStar(require("./ai_response_v5"), exports);
+__exportStar(require("./turn_registry_v5"), exports);

package/dist/types/response/v5/turn_registry_v5.d.ts

@@ -0,0 +1,7 @@
+import { RequestResponseV5 } from "./dialogue_response_v5";
+export type TurnProgressEntryV5 = {
+    /** The ID of the buffered event */
+    eventId: string;
+    /** The actual event payload */
+    event: RequestResponseV5;
+};

package/dist/types/response/v5/turn_registry_v5.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/type_registry.d.ts

@@ -1,3 +1,4 @@
 export * from "./response/v3";
 export * from "./response/v4";
+export * from "./response/v5";
 export * from "./error";

package/dist/types/type_registry.js

@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./response/v3"), exports);
 __exportStar(require("./response/v4"), exports);
+__exportStar(require("./response/v5"), exports);
 __exportStar(require("./error"), exports);

package/package.json

@@ -1,45 +1,45 @@
-{
-	"name": "@butlerbot/sdk",
-	"version": "0.0.16",
-	"description": "The official ButlerBot SDK",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"files": [
-		"dist/**/*"
-	],
-	"scripts": {
-		"build": "tsc",
-		"pack": "npm run build && npm pack --pack-destination=\"G:\\tarballs\"",
-		"update": "npm run build && npm publish --access public",
-		"update:alpha": "npm run build && npm publish --access public --tag alpha",
-		"test": "jest"
-	},
-	"keywords": [
-		"butlerbot",
-		"alfred",
-		"sdk",
-		"chatbot",
-		"ai",
-		"butler"
-	],
-	"author": "Fragly",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/isdevco/alfred5_sdk.git"
-	},
-	"bugs": {
-		"url": "https://github.com/isdevco/alfred5_sdk/issues"
-	},
-	"homepage": "https://butlerbot.net",
-	"engines": {
-		"node": ">=14.0.0"
-	},
-	"devDependencies": {
-		"@types/node": "^22.13.10",
-		"typescript": "^5.8.2"
-	},
-	"dependencies": {
-		"eventsource": "^3.0.5"
-	}
-}
+{
+	"name": "@butlerbot/sdk",
+	"version": "0.0.18-alpha.0",
+	"description": "The official ButlerBot SDK",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist/**/*"
+	],
+	"scripts": {
+		"build": "tsc",
+		"pack": "npm run build && npm pack --pack-destination=\"G:\\tarballs\"",
+		"update": "npm run build && npm publish --access public",
+		"update:alpha": "npm run build && npm publish --access public --tag alpha",
+		"test": "jest"
+	},
+	"keywords": [
+		"butlerbot",
+		"alfred",
+		"sdk",
+		"chatbot",
+		"ai",
+		"butler"
+	],
+	"author": "Fragly",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/isdevco/alfred5_sdk.git"
+	},
+	"bugs": {
+		"url": "https://github.com/isdevco/alfred5_sdk/issues"
+	},
+	"homepage": "https://butlerbot.net",
+	"engines": {
+		"node": ">=14.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.13.10",
+		"typescript": "^5.8.2"
+	},
+	"dependencies": {
+		"eventsource": "^3.0.5"
+	}
+}