@band-ai/band-sdk-core 2.6.0 → 2.8.0

package/README.md

@@ -244,6 +244,39 @@ outcome to `"processed"` or `"failed"`.
 exposed for a host's own call sites that classify a sender without going
 through either function.
 
+### Turn outcome
+
+`TurnLedger` judges one agent turn — design decisions live as rustdoc in
+`crates/core/src/turn.rs`. Create one per turn, `record` the `TurnEffect` of
+each successful tool call (a failed call records nothing), and ask for the
+`verdict()` when the model stops: `"complete"` once the turn replied,
+declined, or did real work, else `"missing_reply"` (fail the turn with
+`missingReplyMessage()`). `settle()` marks a turn the SDK answered itself and
+`noteReported()` one whose failure was already reported; both complete it.
+`replySettled()` is `true` once a recorded call posted to the room or
+declined to, so no fallback text is due. `record` throws a plain `Error` for
+anything but a `TurnEffect` wire name.
+
+`bandToolEffects()` maps every canonical Band tool name to its `TurnEffect`;
+normalize an alias to its canonical name before the lookup. `noReplyTool()`
+returns `band_no_reply`'s definition as a `ToolSpec` (`name`, `description`,
+`parameters`). `turnEffects()` and `turnVerdicts()` list the wire names.
+
+```ts
+import { TurnLedger, bandToolEffects } from "@band-ai/band-sdk-core";
+
+const ledger = new TurnLedger();
+ledger.record(bandToolEffects().band_send_event);
+if (ledger.verdict() !== "missing_reply") {
+  throw new Error("an observe-only turn is a missing reply");
+}
+
+ledger.record("reply");
+if (ledger.verdict() !== "complete" || !ledger.replySettled()) {
+  throw new Error("a reply must complete the turn");
+}
+```
+
 The public declaration is
 [`index.d.ts`](https://github.com/band-ai/band-sdk-core/blob/main/crates/wasm/index.d.ts).
 

package/band_sdk_core.js

@@ -88,6 +88,17 @@ class AgentFailure {
             wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * The canonical failure payload under Core's extension-data key.
+     * @returns {any}
+     */
+    toExtensionData() {
+        const ret = wasm.agentfailure_toExtensionData(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * The failure as a plain JSON-shaped object: unlike the getters above,
      * an absent `code`/`detail` serializes as `null` here, matching the
@@ -1358,6 +1369,68 @@ class SubscriptionTracker {
 if (Symbol.dispose) SubscriptionTracker.prototype[Symbol.dispose] = SubscriptionTracker.prototype.free;
 exports.SubscriptionTracker = SubscriptionTracker;
 
+/**
+ * One agent turn's progress toward a reply. `record` throws a plain
+ * `Error` for anything but a `TurnEffect` wire name.
+ */
+class TurnLedger {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        TurnLedgerFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_turnledger_free(ptr, 0);
+    }
+    constructor() {
+        const ret = wasm.turnledger_new();
+        this.__wbg_ptr = ret;
+        TurnLedgerFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    noteReported() {
+        wasm.turnledger_noteReported(this.__wbg_ptr);
+    }
+    /**
+     * @param {any} effect
+     */
+    record(effect) {
+        const ret = wasm.turnledger_record(this.__wbg_ptr, effect);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
+    /**
+     * @returns {boolean}
+     */
+    replySettled() {
+        const ret = wasm.turnledger_replySettled(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    settle() {
+        wasm.turnledger_settle(this.__wbg_ptr);
+    }
+    /**
+     * @returns {string}
+     */
+    verdict() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.turnledger_verdict(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) TurnLedger.prototype[Symbol.dispose] = TurnLedger.prototype.free;
+exports.TurnLedger = TurnLedger;
+
 /**
  * This platform's Phoenix Channels topic for the `agent_contacts` channel.
  * @param {any} agentId
@@ -1433,6 +1506,20 @@ function agentRoomsTopic(agentId) {
 }
 exports.agentRoomsTopic = agentRoomsTopic;
 
+/**
+ * Every Band tool's canonical name and its `TurnEffect` wire name, as a
+ * plain object in the core table's order.
+ * @returns {any}
+ */
+function bandToolEffects() {
+    const ret = wasm.bandToolEffects();
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.bandToolEffects = bandToolEffects;
+
 /**
  * This platform's Phoenix Channels topic for a room's `chat_room` channel.
  * @param {any} roomId
@@ -1673,6 +1760,37 @@ function memoryTypes() {
 }
 exports.memoryTypes = memoryTypes;
 
+/**
+ * The text shown to the room on a `"missing_reply"` verdict.
+ * @returns {string}
+ */
+function missingReplyMessage() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.missingReplyMessage();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+exports.missingReplyMessage = missingReplyMessage;
+
+/**
+ * `band_no_reply`'s definition as a plain `ToolSpec` object.
+ * @returns {any}
+ */
+function noReplyTool() {
+    const ret = wasm.noReplyTool();
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.noReplyTool = noReplyTool;
+
 /**
  * This platform's Phoenix Channels topic for a room's `room_participants`
  * channel.
@@ -1699,6 +1817,30 @@ function roomParticipantsTopic(roomId) {
 }
 exports.roomParticipantsTopic = roomParticipantsTopic;
 
+/**
+ * r" Every [`TurnEffect`] wire name, in declaration order.
+ * @returns {string[]}
+ */
+function turnEffects() {
+    const ret = wasm.turnEffects();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.turnEffects = turnEffects;
+
+/**
+ * r" Every [`TurnVerdict`] wire name, in declaration order.
+ * @returns {string[]}
+ */
+function turnVerdicts() {
+    const ret = wasm.turnVerdicts();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.turnVerdicts = turnVerdicts;
+
 /**
  * Validate and normalize an inbound platform event payload.
  *
@@ -1742,7 +1884,7 @@ exports.validateMemoryTypeForSystem = validateMemoryTypeForSystem;
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg_Error_67e7344beaa85059: function(arg0, arg1) {
+        __wbg_Error_30c8987f7c2ed4e2: function(arg0, arg1) {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return ret;
         },
@@ -1753,68 +1895,68 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_bigint_get_as_i64_b482365c149396c8: function(arg0, arg1) {
+        __wbg___wbindgen_bigint_get_as_i64_a2383202b9353e4c: function(arg0, arg1) {
             const v = arg1;
             const ret = typeof(v) === 'bigint' ? v : undefined;
             getDataViewMemory0().setBigInt64(arg0 + 8 * 1, isLikeNone(ret) ? BigInt(0) : ret, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
         },
-        __wbg___wbindgen_boolean_get_7a12af2b3f899c5a: function(arg0) {
+        __wbg___wbindgen_boolean_get_5b446f51afd21013: function(arg0) {
             const v = arg0;
             const ret = typeof(v) === 'boolean' ? v : undefined;
             return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
         },
-        __wbg___wbindgen_debug_string_0e68cf47c9cbd9b0: function(arg0, arg1) {
+        __wbg___wbindgen_debug_string_4687d8d8c2017d52: function(arg0, arg1) {
             const ret = debugString(arg1);
             const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
             const len1 = WASM_VECTOR_LEN;
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_in_50072d4d6e45c193: function(arg0, arg1) {
+        __wbg___wbindgen_in_92f62ee1427d9e49: function(arg0, arg1) {
             const ret = arg0 in arg1;
             return ret;
         },
-        __wbg___wbindgen_is_bigint_60fc0336cb14f5d7: function(arg0) {
+        __wbg___wbindgen_is_bigint_b123553bed3bb382: function(arg0) {
             const ret = typeof(arg0) === 'bigint';
             return ret;
         },
-        __wbg___wbindgen_is_function_fcda5e3902d732fe: function(arg0) {
+        __wbg___wbindgen_is_function_1f9d30630b8b1d3d: function(arg0) {
             const ret = typeof(arg0) === 'function';
             return ret;
         },
-        __wbg___wbindgen_is_null_5160b3e381865372: function(arg0) {
+        __wbg___wbindgen_is_null_e343b7d08827ba72: function(arg0) {
             const ret = arg0 === null;
             return ret;
         },
-        __wbg___wbindgen_is_object_edb6b15aa3afe12e: function(arg0) {
+        __wbg___wbindgen_is_object_3c45d4f2dde4e749: function(arg0) {
             const val = arg0;
             const ret = typeof(val) === 'object' && val !== null;
             return ret;
         },
-        __wbg___wbindgen_is_string_c4f7cb494a2a21f1: function(arg0) {
+        __wbg___wbindgen_is_string_90b56bc79aad6f6c: function(arg0) {
             const ret = typeof(arg0) === 'string';
             return ret;
         },
-        __wbg___wbindgen_is_undefined_8c687d0b90d5b524: function(arg0) {
+        __wbg___wbindgen_is_undefined_8865fb403f8fe9d8: function(arg0) {
             const ret = arg0 === undefined;
             return ret;
         },
-        __wbg___wbindgen_jsval_eq_9fdcd3c0a860dd3b: function(arg0, arg1) {
+        __wbg___wbindgen_jsval_eq_02babf21faa37971: function(arg0, arg1) {
             const ret = arg0 === arg1;
             return ret;
         },
-        __wbg___wbindgen_jsval_loose_eq_3c30021c243b64cd: function(arg0, arg1) {
+        __wbg___wbindgen_jsval_loose_eq_677f21e468d6b461: function(arg0, arg1) {
             const ret = arg0 == arg1;
             return ret;
         },
-        __wbg___wbindgen_number_get_1dc732b810cb937c: function(arg0, arg1) {
+        __wbg___wbindgen_number_get_2e0e7dee9f701a71: function(arg0, arg1) {
             const obj = arg1;
             const ret = typeof(obj) === 'number' ? obj : undefined;
             getDataViewMemory0().setFloat64(arg0 + 8 * 1, isLikeNone(ret) ? 0 : ret, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
         },
-        __wbg___wbindgen_string_get_92ab86bb19cbc12f: function(arg0, arg1) {
+        __wbg___wbindgen_string_get_0380ccaa2f57f0d9: function(arg0, arg1) {
             const obj = arg1;
             const ret = typeof(obj) === 'string' ? obj : undefined;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -1822,38 +1964,38 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_throw_5d9e815e6fdf150f: function(arg0, arg1) {
+        __wbg___wbindgen_throw_41e9ee4f547fc59a: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_call_269c5566fbede3eb: function() { return handleError(function (arg0, arg1) {
+        __wbg_call_6137034ef55c9d0f: function() { return handleError(function (arg0, arg1) {
             const ret = arg0.call(arg1);
             return ret;
         }, arguments); },
-        __wbg_done_cffed884d87aa22e: function(arg0) {
+        __wbg_done_b41a1d26cdb37fb6: function(arg0) {
             const ret = arg0.done;
             return ret;
         },
-        __wbg_entries_972a87586902cf87: function(arg0) {
+        __wbg_entries_fb6397112b1de25f: function(arg0) {
             const ret = Object.entries(arg0);
             return ret;
         },
-        __wbg_from_a39669ce566077da: function(arg0) {
+        __wbg_from_296ca31f8d0f1c52: function(arg0) {
             const ret = Array.from(arg0);
             return ret;
         },
-        __wbg_get_6cf5a4d4d8ad3c5a: function() { return handleError(function (arg0, arg1) {
+        __wbg_get_31af05bd4842a84f: function() { return handleError(function (arg0, arg1) {
             const ret = Reflect.get(arg0, arg1);
             return ret;
         }, arguments); },
-        __wbg_get_989d0a1309644f2b: function() { return handleError(function (arg0, arg1) {
+        __wbg_get_658f6698067d9515: function() { return handleError(function (arg0, arg1) {
             const ret = Reflect.get(arg0, arg1);
             return ret;
         }, arguments); },
-        __wbg_get_b1f0ab13c737f856: function(arg0, arg1) {
+        __wbg_get_6c896e0571ddae51: function(arg0, arg1) {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
-        __wbg_get_unchecked_363572bdd397d473: function(arg0, arg1) {
+        __wbg_get_unchecked_288889d017702237: function(arg0, arg1) {
             const ret = arg0[arg1 >>> 0];
             return ret;
         },
@@ -1861,7 +2003,7 @@ function __wbg_get_imports() {
             const ret = arg0[arg1];
             return ret;
         },
-        __wbg_instanceof_ArrayBuffer_d4ff01f8247925ae: function(arg0) {
+        __wbg_instanceof_ArrayBuffer_a99f175873e5d9b8: function(arg0) {
             let result;
             try {
                 result = arg0 instanceof ArrayBuffer;
@@ -1871,7 +2013,7 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
-        __wbg_instanceof_Map_1ff6a2b54c899f0d: function(arg0) {
+        __wbg_instanceof_Map_b2611749102d7ba3: function(arg0) {
             let result;
             try {
                 result = arg0 instanceof Map;
@@ -1881,7 +2023,7 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
-        __wbg_instanceof_Set_daa5e1ad3c6acaeb: function(arg0) {
+        __wbg_instanceof_Set_3b384cb03733893a: function(arg0) {
             let result;
             try {
                 result = arg0 instanceof Set;
@@ -1891,7 +2033,7 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
-        __wbg_instanceof_Uint8Array_598adc0fef426aa8: function(arg0) {
+        __wbg_instanceof_Uint8Array_828cef2aaacafc31: function(arg0) {
             let result;
             try {
                 result = arg0 instanceof Uint8Array;
@@ -1901,84 +2043,84 @@ function __wbg_get_imports() {
             const ret = result;
             return ret;
         },
-        __wbg_isArray_5674713bb7b79043: function(arg0) {
+        __wbg_isArray_e15a2ff68ffdbef2: function(arg0) {
             const ret = Array.isArray(arg0);
             return ret;
         },
-        __wbg_isSafeInteger_8f51c743827d1ec5: function(arg0) {
+        __wbg_isSafeInteger_717808ad6a54bd9e: function(arg0) {
             const ret = Number.isSafeInteger(arg0);
             return ret;
         },
-        __wbg_iterator_22ddeb808cf55a6f: function() {
+        __wbg_iterator_e3c31c892080e444: function() {
             const ret = Symbol.iterator;
             return ret;
         },
-        __wbg_length_31bdaf014f5fbde2: function(arg0) {
+        __wbg_length_7f3c00c40364105e: function(arg0) {
             const ret = arg0.length;
             return ret;
         },
-        __wbg_length_4e1adc0d42e23620: function(arg0) {
+        __wbg_length_d4bdea10311bd9cf: function(arg0) {
             const ret = arg0.length;
             return ret;
         },
-        __wbg_new_1da3429bc3c4541c: function(arg0) {
+        __wbg_new_1dbf7428bba60a42: function(arg0) {
             const ret = new Uint8Array(arg0);
             return ret;
         },
-        __wbg_new_8d36e20aa758e411: function() {
+        __wbg_new_28744009d011f847: function() {
             const ret = new Map();
             return ret;
         },
-        __wbg_new_a32a1ab6c6655abe: function(arg0, arg1) {
+        __wbg_new_343a093a3c2ffb4e: function(arg0, arg1) {
             const ret = new Error(getStringFromWasm0(arg0, arg1));
             return ret;
         },
-        __wbg_new_bebc3f4757acf305: function() {
+        __wbg_new_617a8cdb8bb1130e: function() {
             const ret = new Object();
             return ret;
         },
-        __wbg_new_ffa92086ea89f79c: function() {
+        __wbg_new_ee2291f50781bf1d: function() {
             const ret = new Array();
             return ret;
         },
-        __wbg_next_95053e306b1c3aed: function(arg0) {
+        __wbg_next_33784799010f1bbe: function(arg0) {
             const ret = arg0.next;
             return ret;
         },
-        __wbg_next_f31ecb8646d2c605: function() { return handleError(function (arg0) {
+        __wbg_next_f4aac29c42af995c: function() { return handleError(function (arg0) {
             const ret = arg0.next();
             return ret;
         }, arguments); },
-        __wbg_of_1c173c2ad96e2f7e: function(arg0, arg1) {
+        __wbg_of_20798cb14708764f: function(arg0, arg1) {
             const ret = Array.of(arg0, arg1);
             return ret;
         },
-        __wbg_prototypesetcall_ae9f5e7459250748: function(arg0, arg1, arg2) {
+        __wbg_prototypesetcall_bc27214492979395: function(arg0, arg1, arg2) {
             Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
         },
-        __wbg_push_bfdf956ba476f65b: function(arg0, arg1) {
+        __wbg_push_2baf45db356cf468: function(arg0, arg1) {
             const ret = arg0.push(arg1);
             return ret;
         },
-        __wbg_random_7bce4e9e78e2e0d0: function() {
+        __wbg_random_5a4cafd2f02395ff: function() {
             const ret = Math.random();
             return ret;
         },
-        __wbg_set_13d25b81ab403f5e: function(arg0, arg1, arg2) {
-            arg0[arg1 >>> 0] = arg2;
-        },
-        __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
-            arg0[arg1] = arg2;
-        },
-        __wbg_set_a377297433dfea63: function() { return handleError(function (arg0, arg1, arg2) {
+        __wbg_set_145a351398b48c65: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = Reflect.set(arg0, arg1, arg2);
             return ret;
         }, arguments); },
-        __wbg_set_bf6dde4923b9b059: function(arg0, arg1, arg2) {
+        __wbg_set_6ae97e73113c4f0b: function(arg0, arg1, arg2) {
             const ret = arg0.set(arg1, arg2);
             return ret;
         },
-        __wbg_value_c227f843d21da141: function(arg0) {
+        __wbg_set_6be42768c690e380: function(arg0, arg1, arg2) {
+            arg0[arg1] = arg2;
+        },
+        __wbg_set_bea140a88be9b277: function(arg0, arg1, arg2) {
+            arg0[arg1 >>> 0] = arg2;
+        },
+        __wbg_value_f3c585ee8f5ba40c: function(arg0) {
             const ret = arg0.value;
             return ret;
         },
@@ -2051,6 +2193,9 @@ const SessionPolicyFinalization = (typeof FinalizationRegistry === 'undefined')
 const SubscriptionTrackerFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_subscriptiontracker_free(ptr, 1));
+const TurnLedgerFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_turnledger_free(ptr, 1));
 
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();

package/index.d.ts

@@ -20,6 +20,10 @@ export class AgentFailure {
    * absent `code`/`detail` serializes as `null` here, not `undefined`.
    */
   toObject(): Record<string, unknown>;
+  /**
+   * The `toObject()` payload under Core's `band.ai/failure` extension key.
+   */
+  toExtensionData(): Record<string, unknown>;
 }
 
 /** Canonical inbound wire-event names `validateEventPayload` accepts. */
@@ -613,3 +617,82 @@ export function evaluateAdapterResult(
  * `senderId`/`senderType`/`agentId` is not a string.
  */
 export function isSelfEcho(senderId: string, senderType: string, agentId: string): boolean;
+
+/** What a successful tool call contributes to the turn. */
+export type TurnEffect = "observe" | "act" | "reply" | "decline";
+
+/** How the SDK ends a turn, per {@link TurnLedger.verdict}. */
+export type TurnVerdict = "complete" | "missing_reply";
+
+/** Every Band tool's canonical name. */
+export type BandToolName =
+  | "band_get_participants"
+  | "band_lookup_peers"
+  | "band_list_contacts"
+  | "band_list_contact_requests"
+  | "band_list_memories"
+  | "band_get_memory"
+  | "band_list_room_files"
+  | "band_read_room_file"
+  | "band_list_tasks"
+  | "band_get_task"
+  | "band_get_task_history"
+  | "band_get_board"
+  | "band_send_event"
+  | "band_add_participant"
+  | "band_remove_participant"
+  | "band_create_chatroom"
+  | "band_add_contact"
+  | "band_remove_contact"
+  | "band_respond_contact_request"
+  | "band_store_memory"
+  | "band_supersede_memory"
+  | "band_archive_memory"
+  | "band_create_task"
+  | "band_update_task"
+  | "band_set_board"
+  | "band_send_message"
+  | "band_send_room_file"
+  | "band_no_reply";
+
+/** Every {@link TurnEffect} wire name, in declaration order. */
+export function turnEffects(): TurnEffect[];
+
+/** Every {@link TurnVerdict} wire name, in declaration order. */
+export function turnVerdicts(): TurnVerdict[];
+
+/**
+ * One agent turn's progress toward a reply. Record only successful tool
+ * calls. `record` throws a plain `Error` for anything but a
+ * {@link TurnEffect}.
+ */
+export class TurnLedger {
+  constructor();
+  record(effect: TurnEffect): void;
+  settle(): void;
+  noteReported(): void;
+  replySettled(): boolean;
+  verdict(): TurnVerdict;
+}
+
+/** Every Band tool's canonical name and its {@link TurnEffect}. */
+export function bandToolEffects(): Record<BandToolName, TurnEffect>;
+
+/** One parameter of a {@link ToolSpec}. Each SDK declares its value type. */
+export interface ToolParameterSpec {
+  name: string;
+  description: string;
+  required: boolean;
+}
+/** A tool definition as the model reads it. */
+export interface ToolSpec {
+  name: string;
+  description: string;
+  parameters: ToolParameterSpec[];
+}
+
+/** `band_no_reply`'s definition. */
+export function noReplyTool(): ToolSpec;
+
+/** The text shown to the room on a `"missing_reply"` verdict. */
+export function missingReplyMessage(): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@band-ai/band-sdk-core",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Shared Band event-payload validation",
   "license": "MIT",
   "repository": {