@butlerbot/sdk 0.0.45 → 0.0.47

package/dist/config.d.ts

@@ -69,6 +69,10 @@ export declare const CONFIG: {
             /** The inbox. One delivery's answer is `${base}/${deliveryId}/answer`. */
             base: string;
         };
+        judge: {
+            /** A decision on stated facts, by a decision model. */
+            base: string;
+        };
     };
 };
 export type APIPath = keyof typeof CONFIG.paths.conversation;

package/dist/config.js

@@ -60,7 +60,11 @@ exports.CONFIG = {
         outreach: {
             /** The inbox. One delivery's answer is `${base}/${deliveryId}/answer`. */
             base: "/api/outreach",
-        }
+        },
+        judge: {
+            /** A decision on stated facts, by a decision model. */
+            base: "/api/judge",
+        },
     }
 };
 const withoutTrailingSlash = (url) => url.replace(/\/+$/, "");

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { Conversation, ConversationOptions } from "./modules/conversation";
 import { UsagePolicyDataOptions } from "./modules/usage";
 import { type CancelJobOptions, type GetJobJournalOptions, type GetJobOptions, type SetPhaseModelOptions, type ListJobsOptions, type ResumeJobOptions, type UpdateJobOptions, type UpdateJobSettingsOptions } from "./modules/jobs";
 import { type AnswerDeliveryOptions, type ListDeliveriesOptions } from "./modules/outreach";
+import { type JudgeOptions } from "./modules/judge";
+import type { JudgeQuestions } from "./types/judge";
 type OptionalApiKey<T> = Omit<T, "apiKey"> & {
     /** Optional API key, defaults to API key specified in client */
     apiKey?: string;
@@ -64,6 +66,13 @@ export declare class ButlerBotClient {
     listDeliveries(config?: OptionalApiKey<ListDeliveriesOptions>): Promise<import("./types/type_registry").DeliveryListResponse>;
     /** Answers a delivery. Throws a `ButlerBotAPIError` with `isConflict` when it was already answered */
     answerDelivery(config: OptionalApiKey<AnswerDeliveryOptions>): Promise<import("./types/type_registry").DeliveryAnswerResponse>;
+    /**
+     * Asks the judge: a yes/no, pick-one or score decision on facts you state, by a decision
+     * model, in well under a second for a fraction of a cent. Answers come back keyed by
+     * question id and typed by the question. Throws a `ButlerBotAPIError` with `isBadRequest`
+     * on a question the judge cannot ask, carrying its message
+     */
+    judge<Q extends JudgeQuestions>(config: OptionalApiKey<JudgeOptions<Q>>): Promise<import("./types/judge").JudgeVerdict<Q>>;
     /** The client's own server and key underneath whatever the call named itself. */
     private forRequest;
 }
@@ -78,6 +87,9 @@ export { listJobs, getJob, cancelJob, resumeJob, updateJob, updateJobSettings }
 export type { JobsRequestOptions, ListJobsOptions, GetJobOptions, CancelJobOptions, ResumeJobOptions, UpdateJobOptions, UpdateJobSettingsOptions, } from "./modules/jobs";
 export { listDeliveries, answerDelivery } from "./modules/outreach";
 export type { OutreachRequestOptions, ListDeliveriesOptions, AnswerDeliveryOptions, } from "./modules/outreach";
+export { judge } from "./modules/judge";
+export type { JudgeRequestOptions, JudgeOptions } from "./modules/judge";
 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.judge = 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");
@@ -22,6 +22,7 @@ Object.defineProperty(exports, "Conversation", { enumerable: true, get: function
 const usage_1 = require("./modules/usage");
 const jobs_1 = require("./modules/jobs");
 const outreach_1 = require("./modules/outreach");
+const judge_1 = require("./modules/judge");
 /**
  * The options a caller actually gave, with the keys they left out removed.
  *
@@ -112,6 +113,15 @@ class ButlerBotClient {
     answerDelivery(config) {
         return (0, outreach_1.answerDelivery)(this.forRequest(config));
     }
+    /**
+     * Asks the judge: a yes/no, pick-one or score decision on facts you state, by a decision
+     * model, in well under a second for a fraction of a cent. Answers come back keyed by
+     * question id and typed by the question. Throws a `ButlerBotAPIError` with `isBadRequest`
+     * on a question the judge cannot ask, carrying its message
+     */
+    judge(config) {
+        return (0, judge_1.judge)(this.forRequest(config));
+    }
     /** The client's own server and key underneath whatever the call named itself. */
     forRequest(config) {
         return { serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug, ...given(config) };
@@ -133,7 +143,11 @@ Object.defineProperty(exports, "updateJobSettings", { enumerable: true, get: fun
 var outreach_2 = require("./modules/outreach");
 Object.defineProperty(exports, "listDeliveries", { enumerable: true, get: function () { return outreach_2.listDeliveries; } });
 Object.defineProperty(exports, "answerDelivery", { enumerable: true, get: function () { return outreach_2.answerDelivery; } });
+var judge_2 = require("./modules/judge");
+Object.defineProperty(exports, "judge", { enumerable: true, get: function () { return judge_2.judge; } });
 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/judge.d.ts

@@ -0,0 +1,32 @@
+import type { JudgeQuestions, JudgeState, JudgeVerdict } from "../types/judge";
+/** What a judge call needs: where the server is, and who is asking. */
+export type JudgeRequestOptions = {
+    serverURL?: string;
+    /** The path of the judge route, when it is not the default. */
+    path?: string;
+    apiKey: string;
+    debug?: boolean;
+};
+export type JudgeOptions<Q extends JudgeQuestions = JudgeQuestions> = JudgeRequestOptions & {
+    /**
+     * The facts the questions are answered from: the message, who sent it, the rules, numbers
+     * and dates already worked out in code. Never a transcript or an argument for an answer.
+     */
+    state: JudgeState;
+    /** The questions, by the id the answer is read back under. All are judged against the same state in one call. */
+    questions: Q;
+};
+/**
+ * Asks the judge: a yes/no, pick-one or score decision on the facts given, made by a decision
+ * model in well under a second for a fraction of a cent.
+ *
+ * The answers come back keyed by question id and typed by the question: a boolean's `value` and
+ * `probability`, a choice's `choice` (one of its criteria's keys), `confidence` and
+ * `probabilities`, a score's `level`, `score` and `confidence`. The model writes no text and
+ * gives no reason.
+ *
+ * A question the judge cannot ask (a boolean missing one side, a choice with one label, a score
+ * with more than ten levels) is a 400 carrying the judge's own message, and a judgement not
+ * reached is a 503: the call throws a `ButlerBotAPIError` either way, never a guess.
+ */
+export declare function judge<Q extends JudgeQuestions>(options: JudgeOptions<Q>): Promise<JudgeVerdict<Q>>;

package/dist/modules/judge.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.judge = judge;
+const config_1 = require("../config");
+const url_formatter_1 = require("../util/url_formatter");
+const api_request_1 = require("./api_request");
+/**
+ * Asks the judge: a yes/no, pick-one or score decision on the facts given, made by a decision
+ * model in well under a second for a fraction of a cent.
+ *
+ * The answers come back keyed by question id and typed by the question: a boolean's `value` and
+ * `probability`, a choice's `choice` (one of its criteria's keys), `confidence` and
+ * `probabilities`, a score's `level`, `score` and `confidence`. The model writes no text and
+ * gives no reason.
+ *
+ * A question the judge cannot ask (a boolean missing one side, a choice with one label, a score
+ * with more than ten levels) is a 400 carrying the judge's own message, and a judgement not
+ * reached is a 503: the call throws a `ButlerBotAPIError` either way, never a guess.
+ */
+async function judge(options) {
+    const url = (0, url_formatter_1.formatURL)((options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.judge.base), {}, { apiKey: options.apiKey, debug: options.debug });
+    const response = await (0, api_request_1.requestAPI)({
+        url,
+        method: "POST",
+        body: { state: options.state, questions: options.questions },
+        action: "ask the judge",
+    });
+    return { answers: response.answers, model: response.model, costUsd: response.costUsd };
+}

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/conversation/v3/conversation_v3.d.ts

@@ -52,6 +52,14 @@ export type ToolStatus = {
     content?: ToolStatusContent[];
     /** Whether this tool call is ending the conversation */
     endingConvo?: boolean;
+    /** The tool that ran: its id, or a raw (MCP) tool's key. A fact for clients to present, never a label. */
+    toolId?: string;
+    /** Epoch ms of the first status emitted for this id; the same on every later status for it. */
+    startedAt?: number;
+    /** Epoch ms at which this id reached `completed` or `failed`. */
+    endedAt?: number;
+    /** The id of an earlier failed call of the same tool, in the same turn, that this call retries. */
+    retryOf?: string;
 };
 export type TokenUsage = {
     /**

package/dist/types/judge/index.d.ts

@@ -0,0 +1 @@
+export * from "./judge";

package/dist/types/judge/index.js

@@ -0,0 +1,17 @@
+"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("./judge"), exports);

package/dist/types/judge/judge.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The judge: a yes/no, pick-one or score decision made by a decision model, on facts the caller
+ * states.
+ *
+ * Not a conversation. It writes no text and gives no reason: one call, every question judged
+ * against the same state, and typed answers back with probabilities. The state is facts (the
+ * message, who sent it, the rules, numbers and dates already worked out in code), never a
+ * transcript or an argument for an answer. State and the longest question together fit in about
+ * 32,000 tokens.
+ */
+/**
+ * A yes/no question.
+ *
+ * Both sides are described, because the model weighs the state against each description rather
+ * than against the question alone, and the server refuses a question that leaves one out.
+ */
+export type JudgeBooleanQuestion = {
+    type: "boolean";
+    /** What is being decided about the state, in one or two sentences. */
+    instructions: string;
+    criteria: {
+        /** What a yes looks like in the state. */
+        true: string;
+        /** What a no looks like in the state. */
+        false: string;
+    };
+    /** The probability of yes (between 0 and 1, exclusive) at which `value` is true. 0.5 when unset. */
+    threshold?: number;
+};
+/**
+ * Pick one label.
+ *
+ * Every label the answer may be is a key of `criteria`, described by its value; at least two.
+ * There is no automatic "none": when the state may fit no label, add one ("none": "Nothing above
+ * fits"), or the nearest label is picked however poor the fit.
+ */
+export type JudgeChoiceQuestion<L extends string = string> = {
+    type: "choice";
+    instructions: string;
+    criteria: Record<L, string>;
+};
+/**
+ * A place on an ordered scale.
+ *
+ * `criteria[0]` describes the bottom of the scale and each entry after it one level up; at most
+ * ten levels.
+ */
+export type JudgeScoreQuestion = {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+};
+export type JudgeQuestion = JudgeBooleanQuestion | JudgeChoiceQuestion | JudgeScoreQuestion;
+/** The questions of one call, by an id (1-64 letters, digits, `_` or `-`) the answer is read back under. */
+export type JudgeQuestions = Record<string, JudgeQuestion>;
+/** The facts the questions are answered from: text, or an object the server renders. */
+export type JudgeState = string | Record<string, unknown>;
+export type JudgeBooleanAnswer = {
+    type: "boolean";
+    /** True when `probability` reached the question's threshold. */
+    value: boolean;
+    /** How likely yes is, 0 to 1. */
+    probability: number;
+};
+export type JudgeChoiceAnswer<L extends string = string> = {
+    type: "choice";
+    /** The label picked: one of the question's criteria keys. */
+    choice: L;
+    /** How sure, 0 to 1. */
+    confidence: number;
+    /** Every label's probability, keyed by label. */
+    probabilities?: Partial<Record<L, number>>;
+};
+export type JudgeScoreAnswer = {
+    type: "score";
+    /** The probability-weighted mean of the levels, 0-based; a fraction when the model is torn. */
+    score: number;
+    /** The single most likely level, 0-based: an index into the question's `criteria`. */
+    level: number;
+    /** How sure of `level`, 0 to 1. */
+    confidence: number;
+    /** Each level's probability, keyed by its index as a string. */
+    probabilities?: Record<string, number>;
+};
+export type JudgeAnswer = JudgeBooleanAnswer | JudgeChoiceAnswer | JudgeScoreAnswer;
+/** The answer a question gets, typed by the question: a choice's label is one of its criteria's keys. */
+export type JudgeAnswerFor<Q extends JudgeQuestion> = Q extends JudgeBooleanQuestion ? JudgeBooleanAnswer : Q extends JudgeChoiceQuestion ? JudgeChoiceAnswer<Extract<keyof Q["criteria"], string>> : Q extends JudgeScoreQuestion ? JudgeScoreAnswer : never;
+export type JudgeAnswers<Q extends JudgeQuestions> = {
+    [K in keyof Q]: JudgeAnswerFor<Q[K]>;
+};
+/** What a decision comes back as. */
+export type JudgeVerdict<Q extends JudgeQuestions = JudgeQuestions> = {
+    /** One answer per question, under the question's id. */
+    answers: JudgeAnswers<Q>;
+    /** The decision model that answered. */
+    model: string;
+    /** What the judgement cost, USD. It is already on the account's ledger. */
+    costUsd: number;
+};
+/** The route's whole answer. */
+export type JudgeResponse<Q extends JudgeQuestions = JudgeQuestions> = JudgeVerdict<Q> & {
+    success: true;
+};

package/dist/types/judge/judge.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * The judge: a yes/no, pick-one or score decision made by a decision model, on facts the caller
+ * states.
+ *
+ * Not a conversation. It writes no text and gives no reason: one call, every question judged
+ * against the same state, and typed answers back with probabilities. The state is facts (the
+ * message, who sent it, the rules, numbers and dates already worked out in code), never a
+ * transcript or an argument for an answer. State and the longest question together fit in about
+ * 32,000 tokens.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -39,6 +39,14 @@ export type ToolStatus = {
     content?: ToolStatusContent[];
     /** Whether this tool call is ending the conversation */
     endingConvo?: boolean;
+    /** The tool that ran: its id, or a raw (MCP) tool's key. A fact for clients to present, never a label. */
+    toolId?: string;
+    /** Epoch ms of the first status emitted for this id; the same on every later status for it. */
+    startedAt?: number;
+    /** Epoch ms at which this id reached `completed` or `failed`. */
+    endedAt?: number;
+    /** The id of an earlier failed call of the same tool, in the same turn, that this call retries. */
+    retryOf?: string;
 };
 export type BaseResponseMetadata = {
     /** Unique response ID */

package/dist/types/type_registry.d.ts

@@ -4,6 +4,8 @@ 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 "./judge";
 export * from "./error";

package/dist/types/type_registry.js

@@ -20,6 +20,8 @@ __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("./judge"), exports);
 __exportStar(require("./error"), exports);

package/package.json

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

package/readme.md

@@ -387,10 +387,63 @@ one, and answering it is refused with a 409 just as one already answered is. `so
 wrote a delivery: `shift` for a question a job's shift asked, `runtime` for the job's own
 status tells, `gate` for an approval the autonomy gate asked for.
 
+## Judge
+
+A yes/no, pick-one or score decision on facts you state, made by a decision model: well under
+a second and a fraction of a cent, so an app can ask it per event. It is Alfred's own judge,
+the one his jobs and reflexes decide with, for your code to decide with too.
+
+```typescript
+const { answers, model, costUsd } = await client.judge({
+  state: { message: text, author: "bot: false", channel: "general", rules },
+  questions: {
+    hostile: {
+      type: "boolean",
+      instructions: "Is the message hostile?",
+      criteria: { true: "It attacks or insults someone", false: "It is civil, however blunt" },
+    },
+    rule: {
+      type: "choice",
+      instructions: "Which server rule does the message break?",
+      criteria: { spam: "Promotional or repeated", abuse: "Insults a person", none: "No rule is broken" },
+    },
+    heat: {
+      type: "score",
+      instructions: "How heated is the message?",
+      criteria: ["Calm", "Annoyed", "Furious"],
+    },
+  },
+});
+
+answers.hostile.value;        // boolean: value, probability
+answers.rule.choice;          // "spam" | "abuse" | "none", with confidence and every label's probability
+answers.heat.level;           // 0..2, with score (the weighted mean) and confidence
+```
+
+Every question is judged against the same `state` in one call, and the answers come back keyed
+by question id and typed by the question: a choice's `choice` is one of its own criteria keys.
+It is a decision model, not a chat model: it writes no text and does no reasoning, so
+
+- state facts, never a transcript or an argument for an answer;
+- work out numbers and dates in code and state the result;
+- describe both sides of a boolean, since the model weighs the state against each;
+- add a `none` label to a choice when nothing may fit, or the nearest label is picked however
+  poor the fit;
+- keep a score to ten levels, `criteria[0]` the bottom.
+
+State and the longest question together fit in about 32,000 tokens. A question the judge cannot
+ask is a 400 carrying its message, and a judgement it could not reach is a 503: both throw
+`ButlerBotAPIError`, never a guess. Needs `judge.run`.
+
+The judge is for a decision your app makes itself. For Alfred to react to something, do not
+judge first: report it as a [hook event](#hooks-emit-or-report-what-matched) and the user's
+reflex decides, with the judge inside it when it needs one. That keeps what Alfred reacts to,
+and what it costs, in the user's hands.
+
 ### When a call fails
 
-Every jobs and outreach call throws `ButlerBotAPIError` when the server does not answer with a
-success. The status is on the error, so the cases worth branching on are told apart without
+Every jobs, outreach and judge call throws `ButlerBotAPIError` when the server does not answer
+with a success. The status is on the error, so the cases worth branching on are told apart without
 reading a message, and the parsed body is kept — a rejected cancel still carries the job, a
 rejected answer still carries the delivery: