@band-ai/band-sdk-core 2.7.0 → 2.9.0

package/README.md

@@ -68,6 +68,15 @@ snapshot names the same `id` twice. `RetryTracker`'s `maxTracked` must be
 at least `1`; `0` throws. `ClaimRegistry`'s `maxCompleted` must be at
 least `1` too — `0` also throws.
 
+`ClaimRegistry` keeps one terminal intent per message until
+`rememberCompleted`: `rememberAckPending` records a processed write and
+`rememberFailedAckPending` a failed one carrying its `error`. The first
+intent wins; a different one throws — leaving the entry unchanged, with
+`.issues` and `.traceContext` attached — and an identical repeat is a
+no-op. `pendingAck` returns `{status, error?, parked}` or `undefined`.
+`parkAck` takes a `ParkedReason` wire name, `parkedReasons()` lists them,
+and any other value throws a plain `Error`.
+
 `SubscriptionTracker` provides synchronous, transport-independent decisions for
 agent-topic joins and the two-topic room subscription transaction. Its opaque
 tickets are JavaScript `bigint` values and must be supplied when recording a
@@ -244,6 +253,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

@@ -118,8 +118,8 @@ exports.AgentFailure = AgentFailure;
 
 /**
  * Ownership ledger for the inbound message-delivery lifecycle: in-flight,
- * ack-pending, and completed states, each scoped by `(roomId,
- * messageId)`.
+ * ack-pending (a stored processed/failed intent, optionally parked), and
+ * completed states, each scoped by `(roomId, messageId)`.
  */
 class ClaimRegistry {
     __destroy_into_raw() {
@@ -210,6 +210,21 @@ class ClaimRegistry {
         ClaimRegistryFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
+    /**
+     * Mark a pending entry parked for `reason` (`"not_found"` or
+     * `"rejected"`); `false` when nothing is pending for the message.
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {any} reason
+     * @returns {boolean}
+     */
+    parkAck(room_id, message_id, reason) {
+        const ret = wasm.claimregistry_parkAck(this.__wbg_ptr, room_id, message_id, reason);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
     /**
      * @param {any} room_id
      * @returns {string[]}
@@ -223,6 +238,20 @@ class ClaimRegistry {
         wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
         return v1;
     }
+    /**
+     * The pending entry as `{status: "processed" | "failed", error?:
+     * string, parked: "not_found" | "rejected" | null}`, or `undefined`.
+     * @param {any} room_id
+     * @param {any} message_id
+     * @returns {any}
+     */
+    pendingAck(room_id, message_id) {
+        const ret = wasm.claimregistry_pendingAck(this.__wbg_ptr, room_id, message_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @param {any} room_id
      * @param {any} message_id
@@ -265,6 +294,21 @@ class ClaimRegistry {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * Record a failed turn awaiting a durable failed write carrying
+     * `error`. Throws if a different intent is already pending, with
+     * `.issues` and `.traceContext`.
+     * @param {any} room_id
+     * @param {any} message_id
+     * @param {any} error
+     * @param {any} traceContext
+     */
+    rememberFailedAckPending(room_id, message_id, error, traceContext) {
+        const ret = wasm.claimregistry_rememberFailedAckPending(this.__wbg_ptr, room_id, message_id, error, traceContext);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * @param {any} room_id
      * @param {any} message_id
@@ -277,6 +321,17 @@ class ClaimRegistry {
         }
         return ret[0] !== 0;
     }
+    /**
+     * @param {any} room_id
+     * @returns {number}
+     */
+    unparkAcks(room_id) {
+        const ret = wasm.claimregistry_unparkAcks(this.__wbg_ptr, room_id);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] >>> 0;
+    }
 }
 if (Symbol.dispose) ClaimRegistry.prototype[Symbol.dispose] = ClaimRegistry.prototype.free;
 exports.ClaimRegistry = ClaimRegistry;
@@ -1369,6 +1424,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
@@ -1444,6 +1561,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
@@ -1684,6 +1815,49 @@ 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;
+
+/**
+ * r" Every `ClaimRegistry.parkAck` reason, in declaration order.
+ * @returns {string[]}
+ */
+function parkedReasons() {
+    const ret = wasm.parkedReasons();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.parkedReasons = parkedReasons;
+
 /**
  * This platform's Phoenix Channels topic for a room's `room_participants`
  * channel.
@@ -1710,6 +1884,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.
  *
@@ -1753,7 +1951,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;
         },
@@ -1764,68 +1962,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);
@@ -1833,38 +2031,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;
         },
@@ -1872,7 +2070,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;
@@ -1882,7 +2080,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;
@@ -1892,7 +2090,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;
@@ -1902,7 +2100,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;
@@ -1912,84 +2110,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;
         },
@@ -2062,6 +2260,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

@@ -128,9 +128,25 @@ export interface ParticipantFields {
   description?: string | null;
 }
 
+/**
+ * Why the platform refused a terminal write that stays pending:
+ * `not_found` when the message or room is not visible, `rejected` when it
+ * proved no processing attempt exists to settle.
+ */
+export type ParkedReason = "not_found" | "rejected";
+
+/** Every {@link ParkedReason} wire name, in declaration order. */
+export function parkedReasons(): ParkedReason[];
+
+/** A pending entry: its fixed terminal intent plus whether it is parked. */
+export type PendingAck =
+  | { status: "processed"; parked: ParkedReason | null }
+  | { status: "failed"; error: string; parked: ParkedReason | null };
+
 /**
  * Ownership ledger for the inbound message-delivery lifecycle: in-flight,
- * ack-pending, and completed states, each scoped by `(roomId, messageId)`.
+ * ack-pending (a stored processed/failed intent, optionally parked), and
+ * completed states, each scoped by `(roomId, messageId)`.
  *
  * Throws if `maxCompleted` is not a non-negative integer in range, or is
  * `0` -- a zero capacity would evict every completed entry the instant it
@@ -149,6 +165,20 @@ export class ClaimRegistry {
   rememberCompleted(roomId: string, messageId: string): void;
   isAckPending(roomId: string, messageId: string): boolean;
   rememberAckPending(roomId: string, messageId: string): void;
+  /**
+   * Throws if a different terminal intent is already pending, with `.issues`
+   * and `.traceContext`.
+   */
+  rememberFailedAckPending(
+    roomId: string,
+    messageId: string,
+    error: string,
+    traceContext?: string | null,
+  ): void;
+  pendingAck(roomId: string, messageId: string): PendingAck | undefined;
+  /** `false` when nothing is pending for the message; throws on an unknown reason. */
+  parkAck(roomId: string, messageId: string, reason: ParkedReason): boolean;
+  unparkAcks(roomId: string): number;
   pendingAckIds(roomId: string): string[];
   recordAckRetry(roomId: string, messageId: string): number;
 }
@@ -617,3 +647,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.7.0",
+  "version": "2.9.0",
   "description": "Shared Band event-payload validation",
   "license": "MIT",
   "repository": {