@band-ai/band-sdk-core 2.2.0 → 2.4.0

package/README.md

@@ -146,7 +146,27 @@ enum on this boundary, matching how `EventType` stays a plain string in
 native `Error` with the same `.issues`/`.traceContext` contract as
 `validateEventPayload` — an unrecognized `system` and an unrecognized
 `type` are independent issues, both reported when both strings are
-invalid.
+invalid. See "Enumerating memory-taxonomy values" below for listing each
+enum's members without introducing one.
+
+### Enumerating memory-taxonomy values
+
+`memorySystems()`, `memoryTypes()`, `memorySegments()`, `memoryStoreScopes()`,
+`memoryListScopes()`, and `memoryStatuses()` each return that enum's wire
+names as a `string[]`, in declaration order — runtime enumeration without
+introducing a class, matching `MemorySegment`/`MemoryStoreScope`/
+`MemoryListScope`/`MemoryStatus` as string-literal types in `index.d.ts`.
+
+```ts
+import { memorySystems, memoryStatuses } from "@band-ai/band-sdk-core";
+
+if (!memorySystems().includes("sensory")) {
+  throw new Error("memorySystems() missing sensory");
+}
+if (!memoryStatuses().includes("active")) {
+  throw new Error("memoryStatuses() missing active");
+}
+```
 
 ### One-shot delivery lifecycle
 

package/band_sdk_core.js

@@ -1,5 +1,110 @@
 /* @ts-self-types="./index.d.ts" */
 
+/**
+ * One agent-provider failure, surfaced verbatim rather than classified.
+ */
+class AgentFailure {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        AgentFailureFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_agentfailure_free(ptr, 0);
+    }
+    /**
+     * @returns {string | undefined}
+     */
+    get code() {
+        const ret = wasm.agentfailure_code(this.__wbg_ptr);
+        let v1;
+        if (ret[0] !== 0) {
+            v1 = getStringFromWasm0(ret[0], ret[1]);
+            wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        }
+        return v1;
+    }
+    /**
+     * `undefined` when absent, matching every other optional getter in
+     * this crate (e.g. `SessionOutcome.deadReason`) -- `toObject()` below
+     * represents the same absence as JSON `null` instead, since it mirrors
+     * the wire shape rather than idiomatic JS/TS property access.
+     * @returns {any}
+     */
+    get detail() {
+        const ret = wasm.agentfailure_detail(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * @returns {string}
+     */
+    get message() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.agentfailure_message(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);
+        }
+    }
+    /**
+     * Throws a plain `Error` if `provider`/`message` is not a string, or
+     * `code` is present but not a string or `null`. A `detail` that cannot
+     * be converted from JSON throws a plain `Error` too.
+     * @param {any} provider
+     * @param {any} message
+     * @param {any} code
+     * @param {any} detail
+     */
+    constructor(provider, message, code, detail) {
+        const ret = wasm.agentfailure_new(provider, message, code, detail);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        AgentFailureFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * @returns {string}
+     */
+    get provider() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.agentfailure_provider(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);
+        }
+    }
+    /**
+     * The failure as a plain JSON-shaped object: unlike the getters above,
+     * an absent `code`/`detail` serializes as `null` here, matching the
+     * core type's own `Serialize` output.
+     * @returns {any}
+     */
+    toObject() {
+        const ret = wasm.agentfailure_toObject(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+}
+if (Symbol.dispose) AgentFailure.prototype[Symbol.dispose] = AgentFailure.prototype.free;
+exports.AgentFailure = AgentFailure;
+
 /**
  * Ownership ledger for the inbound message-delivery lifecycle: in-flight,
  * ack-pending, and completed states, each scoped by `(roomId,
@@ -1302,6 +1407,78 @@ function isSelfEcho(senderId, senderType, agentId) {
 }
 exports.isSelfEcho = isSelfEcho;
 
+/**
+ * r" Every [`MemoryListScope`] wire name, in declaration order.
+ * @returns {string[]}
+ */
+function memoryListScopes() {
+    const ret = wasm.memoryListScopes();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.memoryListScopes = memoryListScopes;
+
+/**
+ * r" Every [`MemorySegment`] wire name, in declaration order.
+ * @returns {string[]}
+ */
+function memorySegments() {
+    const ret = wasm.memorySegments();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.memorySegments = memorySegments;
+
+/**
+ * r" Every [`MemoryStatus`] wire name, in declaration order.
+ * @returns {string[]}
+ */
+function memoryStatuses() {
+    const ret = wasm.memoryStatuses();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.memoryStatuses = memoryStatuses;
+
+/**
+ * r" Every [`MemoryStoreScope`] wire name, in declaration order.
+ * @returns {string[]}
+ */
+function memoryStoreScopes() {
+    const ret = wasm.memoryStoreScopes();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.memoryStoreScopes = memoryStoreScopes;
+
+/**
+ * r" Every [`MemorySystem`] wire name, in declaration order.
+ * @returns {string[]}
+ */
+function memorySystems() {
+    const ret = wasm.memorySystems();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.memorySystems = memorySystems;
+
+/**
+ * r" Every [`MemoryType`] wire name, in declaration order.
+ * @returns {string[]}
+ */
+function memoryTypes() {
+    const ret = wasm.memoryTypes();
+    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v1;
+}
+exports.memoryTypes = memoryTypes;
+
 /**
  * This platform's Phoenix Channels topic for a room's `room_participants`
  * channel.
@@ -1629,6 +1806,9 @@ function __wbg_get_imports() {
     };
 }
 
+const AgentFailureFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_agentfailure_free(ptr, 1));
 const ClaimRegistryFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_claimregistry_free(ptr, 1));

package/index.d.ts

@@ -1,3 +1,27 @@
+/**
+ * One agent-provider failure, surfaced verbatim rather than classified.
+ * `detail` is an opaque passthrough of whatever JSON shape the provider (or
+ * the adapter, for a self-declared failure such as `code: "timeout"`)
+ * attaches -- this package never inspects it.
+ *
+ * Throws a plain `Error` if `provider`/`message` is not a string, `code` is
+ * present but not a string or `null`/`undefined`, or `detail` cannot be
+ * converted from JSON.
+ */
+export class AgentFailure {
+  constructor(provider: string, message: string, code?: string | null, detail?: unknown);
+  readonly provider: string;
+  readonly code: string | undefined;
+  readonly message: string;
+  /** `undefined` when absent; {@link toObject} represents the same absence as `null` instead. */
+  readonly detail: unknown | undefined;
+  /**
+   * The failure as a plain JSON-shaped object. Unlike the getters above, an
+   * absent `code`/`detail` serializes as `null` here, not `undefined`.
+   */
+  toObject(): Record<string, unknown>;
+}
+
 /** Canonical inbound wire-event names `validateEventPayload` accepts. */
 export type EventType =
   | "message_created"
@@ -61,6 +85,36 @@ export function validateMemoryTypeForSystem(
   traceContext?: string | null,
 ): void;
 
+/** Logical subject category for a stored memory -- not a store/list scope. */
+export type MemorySegment = "user" | "agent" | "tool" | "guideline";
+
+/** Visibility scope for storing a memory. */
+export type MemoryStoreScope = "subject" | "organization";
+
+/** Scope filter for listing memories. */
+export type MemoryListScope = "subject" | "organization" | "all";
+
+/** Lifecycle state; list filter and set by supersede/archive operations. */
+export type MemoryStatus = "active" | "superseded" | "archived" | "all";
+
+/** Every {@link MemorySystem} wire name, in declaration order. */
+export function memorySystems(): MemorySystem[];
+
+/** Every {@link MemoryType} wire name, in declaration order. */
+export function memoryTypes(): MemoryType[];
+
+/** Every {@link MemorySegment} wire name, in declaration order. */
+export function memorySegments(): MemorySegment[];
+
+/** Every {@link MemoryStoreScope} wire name, in declaration order. */
+export function memoryStoreScopes(): MemoryStoreScope[];
+
+/** Every {@link MemoryListScope} wire name, in declaration order. */
+export function memoryListScopes(): MemoryListScope[];
+
+/** Every {@link MemoryStatus} wire name, in declaration order. */
+export function memoryStatuses(): MemoryStatus[];
+
 /** A roster entry read by `ParticipantRoster`; every other key is ignored. */
 export interface ParticipantFields {
   id: string;

package/package.json

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