@band-ai/sdk 0.3.3 → 0.4.0

package/dist/core.d.cts

@@ -1,8 +1,12 @@
-export { S as SimpleAdapter } from './simpleAdapter-BpT4XbZC.cjs';
-export { A as AdapterToolsProtocol, a as AgentToolsProtocol, C as ContactTools, F as FrameworkAdapter, b as FrameworkAdapterInput, H as HistoryConverter, M as MemoryTools, c as MessagingTools, P as ParticipantTools, d as PeerLookupTools, e as Preprocessor, R as RoomParticipantTools, T as ToolExecutor, f as ToolSchemaProvider } from './protocols-Bz1rxcUg.cjs';
-export { W as WebSocketConflictPolicy, a as WebSocketDisconnectError, b as WebSocketDisconnectReason } from './disconnectReason-IuADl6TH.cjs';
-export { C as ConsoleLogger, L as Logger, N as NoopLogger } from './logger-CABQOnlR.cjs';
-import './dtos-B8KU_q4d.cjs';
+export { S as SimpleAdapter } from './simpleAdapter-D75rcz9n.cjs';
+import { AgentFailure } from '@band-ai/band-sdk-core';
+export { AgentFailure } from '@band-ai/band-sdk-core';
+import { e as MessagingTools } from './protocols-CabgO52c.cjs';
+export { A as AdapterToolsProtocol, b as AgentToolsProtocol, C as ContactTools, c as FAILURE_EVENT_TYPE, d as FAILURE_METADATA_KEY, F as FrameworkAdapter, a as FrameworkAdapterInput, H as HistoryConverter, M as MemoryTools, f as ParticipantTools, g as PeerLookupTools, h as Preprocessor, R as RoomParticipantTools, T as ToolExecutor, i as ToolSchemaProvider, t as toFailureEvent } from './protocols-CabgO52c.cjs';
+export { W as WebSocketConflictPolicy, a as WebSocketDisconnectError, b as WebSocketDisconnectReason } from './disconnectReason-Cctmg1SN.cjs';
+import { L as Logger } from './logger-CABQOnlR.cjs';
+export { C as ConsoleLogger, N as NoopLogger } from './logger-CABQOnlR.cjs';
+import { h as MentionInput, T as ToolOperationResult } from './dtos-CjQsN1_h.cjs';
 
 declare class BandSdkError extends Error {
     constructor(message: string, cause?: unknown);
@@ -19,5 +23,66 @@ declare class TransportError extends BandSdkError {
 declare class RuntimeStateError extends BandSdkError {
     constructor(message: string);
 }
+/**
+ * A failure confined to the turn that raised it. `Execution` keeps the room's
+ * loop — and every other room — running for these, where any other error
+ * stops the whole runtime.
+ *
+ * The turn still fails: `PlatformRuntime` has already marked the message
+ * failed by the time one of these reaches the queue. What it must not do is
+ * take the agent down with it, which is the right response to a broken
+ * adapter and the wrong one to a single reply that could not be posted.
+ */
+declare class RecoverableTurnError extends BandSdkError {
+    constructor(message: string, cause?: unknown);
+}
+
+/**
+ * Marks a rejection as coming from delivering an already-decided reply, not
+ * from the provider itself.
+ *
+ * `RecoverableTurnError`, because failing to post one reply is a failure of
+ * that turn and nothing more: the runtime marks the message failed and keeps
+ * every room serving. Reporting it as an `AgentFailure` would blame the
+ * provider for a Band-side fault; taking the runtime down would answer a
+ * transient post failure with an outage.
+ */
+declare class DeliveryFailedError extends RecoverableTurnError {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+declare function deliverReply(tools: MessagingTools, content: string, mentions?: MentionInput): Promise<ToolOperationResult>;
+
+/**
+ * A provider failure that has already been reported to the room.
+ *
+ * Thrown, not returned, so the turn still *fails*: `PlatformRuntime` marks a
+ * message failed only when `onEvent` throws, and the platform re-syncs failed
+ * messages rather than processed ones. Returning here would flip a failed turn
+ * to `processed` and drop its retry along with it.
+ *
+ * `RecoverableTurnError` is what changes: the turn fails, the room and every
+ * other room keep running. Reporting a provider error must not take the agent
+ * down, which is what an ordinary throw from here used to do.
+ */
+declare class ProviderTurnFailedError extends RecoverableTurnError {
+    readonly failure: AgentFailure;
+    constructor(failure: AgentFailure);
+}
+/**
+ * Reports a terminal provider failure, then fails the turn that hit it.
+ */
+declare function reportTurnFailure(tools: MessagingTools, failure: AgentFailure, logger?: Logger, logContext?: Record<string, unknown>): Promise<never>;
+/**
+ * Builds an `AgentFailure` whose `detail` cannot make the constructor throw.
+ *
+ * `detail` carries raw provider payloads — an HTTP body, an RPC error object —
+ * and the constructor rejects anything it cannot serialize: a `Buffer`, a
+ * function-valued property, a cycle. It is built on failure paths, often as an
+ * argument outside the enclosing guard, where a throw would replace the very
+ * failure being reported. An unusable detail is dropped instead; the provider,
+ * message and code are typed as strings, so only `detail` can be exotic.
+ */
+declare function agentFailure(provider: string, message: string, code?: string, detail?: unknown): AgentFailure;
 
-export { BandSdkError, RuntimeStateError, TransportError, UnsupportedFeatureError, ValidationError };
+export { BandSdkError, DeliveryFailedError, Logger, MessagingTools, ProviderTurnFailedError, RecoverableTurnError, RuntimeStateError, TransportError, UnsupportedFeatureError, ValidationError, agentFailure, deliverReply, reportTurnFailure };

package/dist/core.d.ts

@@ -1,8 +1,12 @@
-export { S as SimpleAdapter } from './simpleAdapter--wznuoOw.js';
-export { A as AdapterToolsProtocol, a as AgentToolsProtocol, C as ContactTools, F as FrameworkAdapter, b as FrameworkAdapterInput, H as HistoryConverter, M as MemoryTools, c as MessagingTools, P as ParticipantTools, d as PeerLookupTools, e as Preprocessor, R as RoomParticipantTools, T as ToolExecutor, f as ToolSchemaProvider } from './protocols-Bwwcql0h.js';
-export { W as WebSocketConflictPolicy, a as WebSocketDisconnectError, b as WebSocketDisconnectReason } from './disconnectReason-IuADl6TH.js';
-export { C as ConsoleLogger, L as Logger, N as NoopLogger } from './logger-CABQOnlR.js';
-import './dtos-B8KU_q4d.js';
+export { S as SimpleAdapter } from './simpleAdapter-eLvsAQNo.js';
+import { AgentFailure } from '@band-ai/band-sdk-core';
+export { AgentFailure } from '@band-ai/band-sdk-core';
+import { e as MessagingTools } from './protocols-Dpci6uae.js';
+export { A as AdapterToolsProtocol, b as AgentToolsProtocol, C as ContactTools, c as FAILURE_EVENT_TYPE, d as FAILURE_METADATA_KEY, F as FrameworkAdapter, a as FrameworkAdapterInput, H as HistoryConverter, M as MemoryTools, f as ParticipantTools, g as PeerLookupTools, h as Preprocessor, R as RoomParticipantTools, T as ToolExecutor, i as ToolSchemaProvider, t as toFailureEvent } from './protocols-Dpci6uae.js';
+export { W as WebSocketConflictPolicy, a as WebSocketDisconnectError, b as WebSocketDisconnectReason } from './disconnectReason-Cctmg1SN.js';
+import { L as Logger } from './logger-CABQOnlR.js';
+export { C as ConsoleLogger, N as NoopLogger } from './logger-CABQOnlR.js';
+import { h as MentionInput, T as ToolOperationResult } from './dtos-CjQsN1_h.js';
 
 declare class BandSdkError extends Error {
     constructor(message: string, cause?: unknown);
@@ -19,5 +23,66 @@ declare class TransportError extends BandSdkError {
 declare class RuntimeStateError extends BandSdkError {
     constructor(message: string);
 }
+/**
+ * A failure confined to the turn that raised it. `Execution` keeps the room's
+ * loop — and every other room — running for these, where any other error
+ * stops the whole runtime.
+ *
+ * The turn still fails: `PlatformRuntime` has already marked the message
+ * failed by the time one of these reaches the queue. What it must not do is
+ * take the agent down with it, which is the right response to a broken
+ * adapter and the wrong one to a single reply that could not be posted.
+ */
+declare class RecoverableTurnError extends BandSdkError {
+    constructor(message: string, cause?: unknown);
+}
+
+/**
+ * Marks a rejection as coming from delivering an already-decided reply, not
+ * from the provider itself.
+ *
+ * `RecoverableTurnError`, because failing to post one reply is a failure of
+ * that turn and nothing more: the runtime marks the message failed and keeps
+ * every room serving. Reporting it as an `AgentFailure` would blame the
+ * provider for a Band-side fault; taking the runtime down would answer a
+ * transient post failure with an outage.
+ */
+declare class DeliveryFailedError extends RecoverableTurnError {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+declare function deliverReply(tools: MessagingTools, content: string, mentions?: MentionInput): Promise<ToolOperationResult>;
+
+/**
+ * A provider failure that has already been reported to the room.
+ *
+ * Thrown, not returned, so the turn still *fails*: `PlatformRuntime` marks a
+ * message failed only when `onEvent` throws, and the platform re-syncs failed
+ * messages rather than processed ones. Returning here would flip a failed turn
+ * to `processed` and drop its retry along with it.
+ *
+ * `RecoverableTurnError` is what changes: the turn fails, the room and every
+ * other room keep running. Reporting a provider error must not take the agent
+ * down, which is what an ordinary throw from here used to do.
+ */
+declare class ProviderTurnFailedError extends RecoverableTurnError {
+    readonly failure: AgentFailure;
+    constructor(failure: AgentFailure);
+}
+/**
+ * Reports a terminal provider failure, then fails the turn that hit it.
+ */
+declare function reportTurnFailure(tools: MessagingTools, failure: AgentFailure, logger?: Logger, logContext?: Record<string, unknown>): Promise<never>;
+/**
+ * Builds an `AgentFailure` whose `detail` cannot make the constructor throw.
+ *
+ * `detail` carries raw provider payloads — an HTTP body, an RPC error object —
+ * and the constructor rejects anything it cannot serialize: a `Buffer`, a
+ * function-valued property, a cycle. It is built on failure paths, often as an
+ * argument outside the enclosing guard, where a throw would replace the very
+ * failure being reported. An unusable detail is dropped instead; the provider,
+ * message and code are typed as strings, so only `detail` can be exotic.
+ */
+declare function agentFailure(provider: string, message: string, code?: string, detail?: unknown): AgentFailure;
 
-export { BandSdkError, RuntimeStateError, TransportError, UnsupportedFeatureError, ValidationError };
+export { BandSdkError, DeliveryFailedError, Logger, MessagingTools, ProviderTurnFailedError, RecoverableTurnError, RuntimeStateError, TransportError, UnsupportedFeatureError, ValidationError, agentFailure, deliverReply, reportTurnFailure };

package/dist/core.js

@@ -1,28 +1,53 @@
 import {
-  SimpleAdapter
-} from "./chunk-AVVDPXP4.js";
+  AgentFailure
+} from "./chunk-I34SXMTJ.js";
+import {
+  DeliveryFailedError,
+  ProviderTurnFailedError,
+  SimpleAdapter,
+  agentFailure,
+  deliverReply,
+  reportTurnFailure
+} from "./chunk-OGOXY43L.js";
 import {
   WebSocketDisconnectError
-} from "./chunk-US226AS4.js";
+} from "./chunk-UENIC5FJ.js";
+import "./chunk-6BE2EG5P.js";
+import {
+  FAILURE_EVENT_TYPE,
+  FAILURE_METADATA_KEY,
+  toFailureEvent
+} from "./chunk-TGDDFBYS.js";
 import {
   ConsoleLogger,
   NoopLogger
-} from "./chunk-OD2G5LFQ.js";
+} from "./chunk-ZYOXI4JL.js";
 import {
   BandSdkError,
+  RecoverableTurnError,
   RuntimeStateError,
   TransportError,
   UnsupportedFeatureError,
   ValidationError
-} from "./chunk-JY75VSQK.js";
+} from "./chunk-4OVNFDD7.js";
 export {
+  AgentFailure,
   BandSdkError,
   ConsoleLogger,
+  DeliveryFailedError,
+  FAILURE_EVENT_TYPE,
+  FAILURE_METADATA_KEY,
   NoopLogger,
+  ProviderTurnFailedError,
+  RecoverableTurnError,
   RuntimeStateError,
   SimpleAdapter,
   TransportError,
   UnsupportedFeatureError,
   ValidationError,
-  WebSocketDisconnectError
+  WebSocketDisconnectError,
+  agentFailure,
+  deliverReply,
+  reportTurnFailure,
+  toFailureEvent
 };

package/dist/{customTools-BzF0IISO.d.cts → customTools-Bfecd0mJ.d.cts}

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 interface CustomToolDef {
-    schema: z.AnyZodObject;
+    schema: z.ZodObject;
     handler: (args: Record<string, unknown>) => unknown;
     name: string;
     description?: string;

package/dist/{customTools-BzF0IISO.d.ts → customTools-Bfecd0mJ.d.ts}

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 interface CustomToolDef {
-    schema: z.AnyZodObject;
+    schema: z.ZodObject;
     handler: (args: Record<string, unknown>) => unknown;
     name: string;
     description?: string;

package/dist/{disconnectReason-IuADl6TH.d.ts → disconnectReason-Cctmg1SN.d.cts}

@@ -3,7 +3,7 @@ interface AgentControlSupersedeDisconnectReason {
     source: "agent_control";
     code: string;
     message: string;
-    retryable: false;
+    retryable: boolean;
     retryAfter: number | null;
     targetSocketId: string | null;
     correlationId: string | null;

package/dist/{disconnectReason-IuADl6TH.d.cts → disconnectReason-Cctmg1SN.d.ts}

@@ -3,7 +3,7 @@ interface AgentControlSupersedeDisconnectReason {
     source: "agent_control";
     code: string;
     message: string;
-    retryable: false;
+    retryable: boolean;
     retryAfter: number | null;
     targetSocketId: string | null;
     correlationId: string | null;

package/dist/{dtos-B8KU_q4d.d.ts → dtos-CjQsN1_h.d.cts}

@@ -1,18 +1,11 @@
-/** Canonical memory enums; DTOs, tool schemas, and validation derive from these constants. */
-/** Which memory types are valid for each memory tier. */
-declare const MEMORY_SYSTEM_TYPES: {
-    readonly sensory: readonly ["iconic", "echoic", "haptic"];
-    readonly working: readonly ["episodic", "semantic", "procedural"];
-    readonly long_term: readonly ["episodic", "semantic", "procedural"];
-};
-type MemorySystem = keyof typeof MEMORY_SYSTEM_TYPES;
-type MemoryType = (typeof MEMORY_SYSTEM_TYPES)[MemorySystem][number];
+import { MemorySystem, MemoryType } from '@band-ai/band-sdk-core';
+
 /** Logical subject category (user/agent/tool/guideline); not scope `subject` or `subject_id`. */
 declare const MEMORY_SEGMENTS: readonly ["user", "agent", "tool", "guideline"];
 /** Visibility scope for `band_store_memory`. */
-declare const MEMORY_STORE_SCOPES: readonly ["subject", "organization"];
+declare const MEMORY_STORE_SCOPES: readonly ["agent", "subject", "organization"];
 /** Scope filter for `band_list_memories`. */
-declare const MEMORY_LIST_SCOPES: readonly ["subject", "organization", "all"];
+declare const MEMORY_LIST_SCOPES: readonly ["agent", "subject", "organization", "all"];
 /** Lifecycle state; list filter and set by supersede/archive tools. */
 declare const MEMORY_STATUSES: readonly ["active", "superseded", "archived", "all"];
 /** Logical subject category (user/agent/tool/guideline); not scope `subject` or `subject_id`. */
@@ -180,4 +173,4 @@ interface ToolModelSchema {
     [key: string]: unknown;
 }
 
-export type { AddContactArgs as A, ContactRecord as C, ListContactsArgs as L, MetadataMap as M, ParticipantRecord as P, RemoveContactArgs as R, StoreMemoryArgs as S, ToolOperationResult as T, MentionInput as a, ToolSchemaRecord as b, PaginatedList as c, PeerRecord as d, ListContactRequestsArgs as e, ContactRequestsResult as f, RespondContactRequestArgs as g, ListMemoriesArgs as h, MemoryRecord as i, MentionReference as j, ContactRequestAction as k, PaginationMetadataLike as l, ToolModelMessage as m, ToolModelSchema as n };
+export type { AddContactArgs as A, ContactRecord as C, ListContactsArgs as L, MetadataMap as M, PeerRecord as P, RemoveContactArgs as R, StoreMemoryArgs as S, ToolOperationResult as T, MentionReference as a, ListContactRequestsArgs as b, ContactRequestsResult as c, RespondContactRequestArgs as d, ListMemoriesArgs as e, MemoryRecord as f, ParticipantRecord as g, MentionInput as h, PaginatedList as i, ToolSchemaRecord as j, ContactRequestAction as k, PaginationMetadataLike as l, ToolModelMessage as m, ToolModelSchema as n };

package/dist/{dtos-B8KU_q4d.d.cts → dtos-CjQsN1_h.d.ts}

@@ -1,18 +1,11 @@
-/** Canonical memory enums; DTOs, tool schemas, and validation derive from these constants. */
-/** Which memory types are valid for each memory tier. */
-declare const MEMORY_SYSTEM_TYPES: {
-    readonly sensory: readonly ["iconic", "echoic", "haptic"];
-    readonly working: readonly ["episodic", "semantic", "procedural"];
-    readonly long_term: readonly ["episodic", "semantic", "procedural"];
-};
-type MemorySystem = keyof typeof MEMORY_SYSTEM_TYPES;
-type MemoryType = (typeof MEMORY_SYSTEM_TYPES)[MemorySystem][number];
+import { MemorySystem, MemoryType } from '@band-ai/band-sdk-core';
+
 /** Logical subject category (user/agent/tool/guideline); not scope `subject` or `subject_id`. */
 declare const MEMORY_SEGMENTS: readonly ["user", "agent", "tool", "guideline"];
 /** Visibility scope for `band_store_memory`. */
-declare const MEMORY_STORE_SCOPES: readonly ["subject", "organization"];
+declare const MEMORY_STORE_SCOPES: readonly ["agent", "subject", "organization"];
 /** Scope filter for `band_list_memories`. */
-declare const MEMORY_LIST_SCOPES: readonly ["subject", "organization", "all"];
+declare const MEMORY_LIST_SCOPES: readonly ["agent", "subject", "organization", "all"];
 /** Lifecycle state; list filter and set by supersede/archive tools. */
 declare const MEMORY_STATUSES: readonly ["active", "superseded", "archived", "all"];
 /** Logical subject category (user/agent/tool/guideline); not scope `subject` or `subject_id`. */
@@ -180,4 +173,4 @@ interface ToolModelSchema {
     [key: string]: unknown;
 }
 
-export type { AddContactArgs as A, ContactRecord as C, ListContactsArgs as L, MetadataMap as M, ParticipantRecord as P, RemoveContactArgs as R, StoreMemoryArgs as S, ToolOperationResult as T, MentionInput as a, ToolSchemaRecord as b, PaginatedList as c, PeerRecord as d, ListContactRequestsArgs as e, ContactRequestsResult as f, RespondContactRequestArgs as g, ListMemoriesArgs as h, MemoryRecord as i, MentionReference as j, ContactRequestAction as k, PaginationMetadataLike as l, ToolModelMessage as m, ToolModelSchema as n };
+export type { AddContactArgs as A, ContactRecord as C, ListContactsArgs as L, MetadataMap as M, PeerRecord as P, RemoveContactArgs as R, StoreMemoryArgs as S, ToolOperationResult as T, MentionReference as a, ListContactRequestsArgs as b, ContactRequestsResult as c, RespondContactRequestArgs as d, ListMemoriesArgs as e, MemoryRecord as f, ParticipantRecord as g, MentionInput as h, PaginatedList as i, ToolSchemaRecord as j, ContactRequestAction as k, PaginationMetadataLike as l, ToolModelMessage as m, ToolModelSchema as n };