@butlerbot/sdk 0.0.47 → 0.0.48

package/dist/modules/conversation.d.ts

@@ -36,6 +36,15 @@ export type DialogueRequestParams = {
      * 500 characters; the server refuses a longer one. Left off when blank.
      */
     wake?: string;
+    /**
+     * Tools switched on for this one turn, by id, that the turn could reach but has off unless
+     * asked for: the Discord bot asks for `react` on a turn the summoning judge started, so
+     * Alfred may answer a message with a reaction rather than words. Activation, never a grant:
+     * the server switches on only what the turn's platform, the user's plan and the user's own
+     * settings already allow, and refuses an id it does not know with the nearest real ones.
+     * Passed per `send()`/`ask()`, since it is true of the one turn; left off when empty.
+     */
+    tools?: string[];
     /**
      * What the platform attaches beside this turn's message, never inside it: what it replies
      * to, who it mentions, where it was sent. See `MessageContextItem` for the shape and the
@@ -55,7 +64,7 @@ export type DialogueRequestParams = {
      *
      * A key the transport already sends (`RESERVED_TURN_FIELDS`: `message`, `chatId`,
      * `api_key`, `model`, `instructions`, `platform`, `address`, `personality`, `wake`,
-     * `context`) is refused: `send()` throws, and `ask()` rejects, before anything is sent.
+     * `tools`, `context`) is refused: `send()` throws, and `ask()` rejects, before anything is sent.
      */
     extra?: Record<string, string>;
 };

package/dist/modules/transport.d.ts

@@ -61,6 +61,8 @@ export type TransportTurnRequest = {
     personality?: string;
     /** Why Alfred is speaking on this one turn: a line for its system prompt, at most 500 characters. */
     wake?: string;
+    /** Tools switched on for this one turn, by id. Sent only when non-empty; see `DialogueRequestParams.tools`. */
+    tools?: string[];
     /** What the platform attaches beside this turn's message. Sent only when non-empty. */
     context?: MessageContextItem[];
     /** Further turn parameters, forwarded to the server verbatim. See `DialogueRequestParams.extra`. */
@@ -81,6 +83,12 @@ export declare const RESERVED_TURN_FIELDS: readonly string[];
 export declare function turnExtra(extra: Record<string, string> | undefined): Record<string, string> | undefined;
 /** A turn's context as it travels, JSON-encoded, or nothing when there is none. */
 export declare function turnContext(context: MessageContextItem[] | undefined): string | undefined;
+/**
+ * A turn's tools as they travel: the ids trimmed, emptied ones dropped, repeats folded, joined
+ * with commas; nothing when none is left. A comma in an id would read as two ids, so one is
+ * refused before anything is sent.
+ */
+export declare function turnTools(tools: string[] | undefined): string | undefined;
 export type TransportHandlers = {
     /** One payload of the stream, already in the shape callers expect. */
     payload(payload: unknown): void;

package/dist/modules/transport.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESERVED_TURN_FIELDS = void 0;
 exports.turnExtra = turnExtra;
 exports.turnContext = turnContext;
+exports.turnTools = turnTools;
 exports.noticePayload = noticePayload;
 exports.convoStartedPayload = convoStartedPayload;
 exports.completedPayload = completedPayload;
@@ -31,6 +32,7 @@ exports.RESERVED_TURN_FIELDS = [
     "address",
     "personality",
     "wake",
+    "tools",
     "context",
 ];
 /**
@@ -60,6 +62,28 @@ function turnExtra(extra) {
 function turnContext(context) {
     return context && context.length > 0 ? JSON.stringify(context) : undefined;
 }
+/**
+ * A turn's tools as they travel: the ids trimmed, emptied ones dropped, repeats folded, joined
+ * with commas; nothing when none is left. A comma in an id would read as two ids, so one is
+ * refused before anything is sent.
+ */
+function turnTools(tools) {
+    if (!tools || tools.length === 0)
+        return undefined;
+    const ids = [];
+    for (const raw of tools) {
+        if (typeof raw !== "string")
+            throw new Error(`A turn's \`tools\` are tool ids; one is ${typeof raw}.`);
+        const id = raw.trim();
+        if (!id)
+            continue;
+        if (id.includes(","))
+            throw new Error(`A turn's \`tools\` entry may not contain a comma: "${id}".`);
+        if (!ids.includes(id))
+            ids.push(id);
+    }
+    return ids.length > 0 ? ids.join(",") : undefined;
+}
 // =============================================
 // PAYLOAD SHAPES
 // =============================================

package/dist/modules/transport_link.js

@@ -179,7 +179,12 @@ class LinkConversationTransport {
         };
         learnChatId(progress.chatId);
         const context = (0, transport_1.turnContext)(request.context);
-        const extra = (0, transport_1.turnExtra)(request.extra);
+        // The turn's tools ride in `extra`, which the Link service spreads into the same query
+        // the SSE transport builds: the server reads `tools` either way, and a caller's own
+        // `extra` can never carry that key, since the transport reserves it.
+        const tools = (0, transport_1.turnTools)(request.tools);
+        const own = (0, transport_1.turnExtra)(request.extra);
+        const extra = tools ? { ...(own ?? {}), tools } : own;
         let done;
         try {
             done = await this.link.exchange("conversation.chat", {

package/dist/modules/transport_sse.js

@@ -124,6 +124,9 @@ function asQuery(request) {
     const wake = request.wake?.trim();
     if (wake)
         query.wake = wake;
+    const tools = (0, transport_1.turnTools)(request.tools);
+    if (tools)
+        query.tools = tools;
     const context = (0, transport_1.turnContext)(request.context);
     if (context)
         query.context = context;

package/package.json

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