@butlerbot/sdk 0.0.45 → 0.0.46

package/dist/index.d.ts

@@ -81,3 +81,4 @@ export type { OutreachRequestOptions, ListDeliveriesOptions, AnswerDeliveryOptio
 export { LinkConversationTransport } from "./modules/transport_link";
 export { SSEConversationTransport } from "./modules/transport_sse";
 export type { SteerResult, TurnStopMode, TurnStopped } from "./modules/transport";
+export { RESERVED_TURN_FIELDS } from "./modules/transport";

package/dist/index.js

@@ -14,7 +14,7 @@ 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.SSEConversationTransport = exports.LinkConversationTransport = exports.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.resumeJob = exports.cancelJob = exports.getJob = exports.listJobs = exports.ButlerBotAPIError = exports.Conversation = exports.ButlerBotClient = void 0;
+exports.RESERVED_TURN_FIELDS = exports.SSEConversationTransport = exports.LinkConversationTransport = exports.answerDelivery = exports.listDeliveries = exports.updateJobSettings = exports.updateJob = exports.resumeJob = exports.cancelJob = exports.getJob = exports.listJobs = exports.ButlerBotAPIError = exports.Conversation = exports.ButlerBotClient = void 0;
 const config_1 = require("./config");
 const link_1 = require("./link");
 const conversation_1 = require("./modules/conversation");
@@ -137,3 +137,5 @@ 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; } });
+var transport_1 = require("./modules/transport");
+Object.defineProperty(exports, "RESERVED_TURN_FIELDS", { enumerable: true, get: function () { return transport_1.RESERVED_TURN_FIELDS; } });

package/dist/link/protocol.d.ts

@@ -122,6 +122,16 @@ export type LinkClientPayloads = {
         personality?: string;
         /** Why Alfred is speaking on this one turn: a line for its system prompt, at most 500 characters. */
         wake?: string;
+        /**
+         * What the platform attaches beside this turn's message: a `MessageContextItem[]`,
+         * JSON-encoded, passed to the server as it is. Absent when there are no items.
+         */
+        context?: string;
+        /**
+         * Further turn parameters, which the Link service spreads into the server's query.
+         * Never one of the fields above or the credential; absent when there are none.
+         */
+        extra?: Record<string, string>;
     };
     "conversation.end": {
         sessionId: string;

package/dist/modules/conversation.d.ts

@@ -6,6 +6,7 @@ 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 { ConversationAddress } from "../types/conversation/address";
+import { MessageContextItem } from "../types/conversation/context";
 import { TurnProgressEntry } from "../types/response/v4/turn_registry_v4";
 import { TurnProgressEntryV5 } from "../types/response/v5/turn_registry_v5";
 export type DialogueRequestParams = {
@@ -35,6 +36,28 @@ export type DialogueRequestParams = {
      * 500 characters; the server refuses a longer one. Left off when blank.
      */
     wake?: 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
+     * bounds (8 items, an 80-character title, a 4 000-character text, 12 000 characters in
+     * all), which the server enforces by refusing the turn. Passed per `send()`/`ask()`, since
+     * it belongs to the one message; left off when empty.
+     */
+    context?: MessageContextItem[];
+    /**
+     * Further parameters for this one turn, forwarded to the server verbatim: each entry
+     * becomes a query parameter over SSE, and a field of `extra` on the `conversation.chat`
+     * frame over a Link, which the Link service spreads into the same query. The SDK does not
+     * read them; the server validates whatever arrives, as it does its named parameters.
+     *
+     * This is how a new turn parameter reaches the server without an SDK change: the server
+     * learns to read it and the client sends it here.
+     *
+     * 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.
+     */
+    extra?: Record<string, string>;
 };
 export type DialogueRequestOptions = Omit<Omit<DialogueRequestParams, "message">, "chatId">;
 export interface RequestResponseByVersion {

package/dist/modules/transport.d.ts

@@ -7,6 +7,7 @@
  * caller sees, including the payload shape, is identical either way.
  */
 import type { ConversationAddress } from "../types/conversation/address";
+import type { MessageContextItem } from "../types/conversation/context";
 /** A turn in progress. */
 export type ConversationStream = {
     /**
@@ -60,7 +61,26 @@ 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;
+    /** 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`. */
+    extra?: Record<string, string>;
 };
+/**
+ * The turn parameters the server reads by name, which a transport sends itself. An `extra`
+ * entry may not use one: it would replace what the transport sent, or, for `api_key`, the
+ * credential. Both transports refuse the same list, since over a Link the service spreads
+ * `extra` into the very query the SSE transport builds.
+ */
+export declare const RESERVED_TURN_FIELDS: readonly string[];
+/**
+ * A turn's `extra`, checked, or nothing when there is none to send. Throws on a key that
+ * collides with a field the transport sends, and on a value that is not a string, before
+ * anything reaches the wire.
+ */
+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;
 export type TransportHandlers = {
     /** One payload of the stream, already in the shape callers expect. */
     payload(payload: unknown): void;

package/dist/modules/transport.js

@@ -8,10 +8,58 @@
  * caller sees, including the payload shape, is identical either way.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESERVED_TURN_FIELDS = void 0;
+exports.turnExtra = turnExtra;
+exports.turnContext = turnContext;
 exports.noticePayload = noticePayload;
 exports.convoStartedPayload = convoStartedPayload;
 exports.completedPayload = completedPayload;
 exports.failurePayload = failurePayload;
+/**
+ * The turn parameters the server reads by name, which a transport sends itself. An `extra`
+ * entry may not use one: it would replace what the transport sent, or, for `api_key`, the
+ * credential. Both transports refuse the same list, since over a Link the service spreads
+ * `extra` into the very query the SSE transport builds.
+ */
+exports.RESERVED_TURN_FIELDS = [
+    "api_key",
+    "message",
+    "chatId",
+    "model",
+    "instructions",
+    "platform",
+    "address",
+    "personality",
+    "wake",
+    "context",
+];
+/**
+ * A turn's `extra`, checked, or nothing when there is none to send. Throws on a key that
+ * collides with a field the transport sends, and on a value that is not a string, before
+ * anything reaches the wire.
+ */
+function turnExtra(extra) {
+    if (!extra)
+        return undefined;
+    const entries = Object.entries(extra);
+    if (entries.length === 0)
+        return undefined;
+    for (const [key, value] of entries) {
+        if (!key)
+            throw new Error("A turn's `extra` may not have an empty key.");
+        if (exports.RESERVED_TURN_FIELDS.includes(key)) {
+            throw new Error(`A turn's \`extra\` may not set "${key}": the transport already sends it. Reserved: ${exports.RESERVED_TURN_FIELDS.join(", ")}.`);
+        }
+        if (typeof value !== "string") {
+            throw new Error(`A turn's \`extra\` values must be strings; "${key}" is ${typeof value}.`);
+        }
+    }
+    return Object.fromEntries(entries);
+}
+/** A turn's context as it travels, JSON-encoded, or nothing when there is none. */
+function turnContext(context) {
+    return context && context.length > 0 ? JSON.stringify(context) : undefined;
+}
 // =============================================
 // PAYLOAD SHAPES
 // =============================================

package/dist/modules/transport_link.js

@@ -29,6 +29,8 @@ class LinkConversationTransport {
         link.on("disconnect", () => { this.sessionId = undefined; });
     }
     send(request, handlers) {
+        // Refused here, synchronously, as the SSE transport refuses it: before anything is sent.
+        (0, transport_1.turnExtra)(request.extra);
         const listening = { closed: false };
         const deliver = {
             payload: (payload) => { if (!listening.closed)
@@ -176,6 +178,8 @@ class LinkConversationTransport {
             }
         };
         learnChatId(progress.chatId);
+        const context = (0, transport_1.turnContext)(request.context);
+        const extra = (0, transport_1.turnExtra)(request.extra);
         let done;
         try {
             done = await this.link.exchange("conversation.chat", {
@@ -186,6 +190,8 @@ class LinkConversationTransport {
                 ...(request.personality ? { personality: request.personality } : {}),
                 // Per turn, never on the session: it says why Alfred was woken for this one.
                 ...(request.wake?.trim() ? { wake: request.wake.trim() } : {}),
+                ...(context ? { context } : {}),
+                ...(extra ? { extra } : {}),
             }, {
                 // A turn takes as long as it takes; only the transport dying ends it early.
                 timeoutMs: 0,

package/dist/modules/transport_sse.js

@@ -4,6 +4,7 @@ exports.SSEConversationTransport = void 0;
 exports.streamSSE = streamSSE;
 const eventsource_1 = require("eventsource");
 const url_formatter_1 = require("../util/url_formatter");
+const transport_1 = require("./transport");
 /**
  * Streams a server-sent-events endpoint, closing when the server says the stream is
  * done. Shared by turns and by the progress stream, which is SSE-only.
@@ -123,5 +124,10 @@ function asQuery(request) {
     const wake = request.wake?.trim();
     if (wake)
         query.wake = wake;
-    return query;
+    const context = (0, transport_1.turnContext)(request.context);
+    if (context)
+        query.context = context;
+    // Checked before anything else is added, so an entry can never replace a field above.
+    const extra = (0, transport_1.turnExtra)(request.extra);
+    return extra ? { ...extra, ...query } : query;
 }

package/dist/types/conversation/context.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Something a platform attaches beside a user's message, never inside it: what the message
+ * replies to, who it mentions, where it was sent, the conversation around it.
+ *
+ * The text the user typed stays exactly what they typed. The model reads the items as a
+ * labelled block after it; a person sees them as chips under the message, titled by `title`
+ * and expandable to `text`.
+ *
+ * ```ts
+ * { kind: "reply",    title: "Replying to", text: "Sam: what time does the store close?" }
+ * { kind: "mentions", title: "Mentions",    text: "Sam (@sam) = <@123>, Alfred = <@456> (this is you)" }
+ * ```
+ *
+ * Bounds, enforced by the server, which refuses a request over them with what is wrong rather
+ * than clipping it: at most 8 items on a message, a `title` of at most 80 characters, a `text`
+ * of at most 4 000, and 12 000 characters in all.
+ */
+export type MessageContextItem = {
+    /**
+     * What the item is: `reply`, `mentions`, `place` or `channel` today. The server holds the
+     * list and refuses an unknown kind with the real ones, so a new kind needs no SDK change.
+     */
+    kind: string;
+    /** What a person sees on the chip and the model on the block's line. At most 80 characters. */
+    title: string;
+    /** The content, as plain text. At most 4 000 characters. */
+    text: string;
+};

package/dist/types/conversation/context.js

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

package/dist/types/type_registry.d.ts

@@ -4,6 +4,7 @@ export * from "./response/v5";
 export * from "./state/convo_state_response";
 export * from "./conversation/v4/conversation_v4";
 export * from "./conversation/address";
+export * from "./conversation/context";
 export * from "./jobs";
 export * from "./outreach";
 export * from "./error";

package/dist/types/type_registry.js

@@ -20,6 +20,7 @@ __exportStar(require("./response/v5"), exports);
 __exportStar(require("./state/convo_state_response"), exports);
 __exportStar(require("./conversation/v4/conversation_v4"), exports);
 __exportStar(require("./conversation/address"), exports);
+__exportStar(require("./conversation/context"), exports);
 __exportStar(require("./jobs"), exports);
 __exportStar(require("./outreach"), exports);
 __exportStar(require("./error"), exports);

package/package.json

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