@band-ai/sdk 0.3.4 → 0.4.0

package/dist/{schemas-BgJhlqqO.d.cts → schemas-BKnh4fKR.d.cts}

@@ -1,22 +1,52 @@
-import { h as AgentToolsCapabilities, g as PlatformMessageLike, A as AdapterToolsProtocol, e as Preprocessor, F as FrameworkAdapter, i as PreprocessorContext } from './protocols-Bz1rxcUg.cjs';
-import { f as PlatformEvent, P as PlatformMessage, e as ConversationContext, S as SessionConfig, c as ContactEventConfig, A as AgentConfig, g as MessageEvent, h as ParticipantAddedEvent, i as ParticipantRemovedEvent, C as ContactEvent, a as AgentInput } from './types-BNNtOXu3.cjs';
-import { M as MetadataMap, P as ParticipantRecord } from './dtos-B8KU_q4d.cjs';
+import { j as AgentToolsCapabilities, P as PlatformMessageLike, A as AdapterToolsProtocol, h as Preprocessor, F as FrameworkAdapter, q as PreprocessorContext } from './protocols-CabgO52c.cjs';
+import { f as PlatformEvent, P as PlatformMessage, e as ConversationContext, S as SessionConfig, c as ContactEventConfig, A as AgentConfig, g as MessageEvent, l as ParticipantAddedEvent, m as ParticipantRemovedEvent, R as ReconnectedEvent, C as ContactEvent, a as AgentInput } from './types-DtcOLALn.cjs';
+import { M as MetadataMap, g as ParticipantRecord } from './dtos-CjQsN1_h.cjs';
 import { L as Logger } from './logger-CABQOnlR.cjs';
-import { B as BandLinkRestApi, b as RestRequestOptions, P as PaginatedResponse, e as AgentToolsRestApi } from './types-BgYFd_Yw.cjs';
-import { P as PaginationOptions } from './pagination-DqdkQArT.cjs';
-import { W as WebSocketConflictPolicy, b as WebSocketDisconnectReason } from './disconnectReason-IuADl6TH.cjs';
+import { B as BandLinkRestApi, b as RestRequestOptions, P as PaginatedResponse, e as AgentToolsRestApi } from './types-42-HWeX8.cjs';
+import { P as PaginationOptions } from './pagination-BZDhB_nO.cjs';
+import { W as WebSocketConflictPolicy, b as WebSocketDisconnectReason } from './disconnectReason-Cctmg1SN.cjs';
+import * as _band_ai_band_sdk_core from '@band-ai/band-sdk-core';
 import { RetryTracker, RoomRoster } from '@band-ai/band-sdk-core';
 
 interface TopicHandlers {
     [event: string]: (payload: Record<string, unknown>) => Promise<void> | void;
 }
+interface JoinOptions {
+    /**
+     * Exempts this topic's event delivery from any reconnect-buffering window
+     * a transport may hold events behind. Only a channel whose events must
+     * never wait on reconciliation (e.g. a control channel carrying session
+     * supersede notices) should set this.
+     */
+    exemptFromBuffering?: boolean;
+}
+/**
+ * One settled outcome of an automatic transport-level reconnect: every topic
+ * the transport owned when the socket reopened has since either rejoined or
+ * failed to. `attemptedTopics` fixes that generation's membership boundary;
+ * `joinedTopics` is its successful subset. Carries no transport-specific
+ * objects so every transport implementation can produce one.
+ */
+interface ReconnectSnapshot {
+    generation: number;
+    attemptedTopics: ReadonlySet<string>;
+    joinedTopics: ReadonlySet<string>;
+}
+type ReconnectObserver = (snapshot: ReconnectSnapshot) => Promise<void> | void;
 interface StreamingTransport {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
-    join(topic: string, handlers: TopicHandlers): Promise<void>;
+    join(topic: string, handlers: TopicHandlers, options?: JoinOptions): Promise<void>;
     leave(topic: string): Promise<void>;
     runForever(signal: AbortSignal): Promise<void>;
     isConnected(): boolean;
+    /**
+     * Optional: a transport that can observe its own automatic reconnects
+     * registers here. Omitted by transports (and test doubles) with no
+     * reconnect story of their own, so existing injected transports stay
+     * source-compatible. Returns an unsubscribe function.
+     */
+    onReconnected?(observer: ReconnectObserver): () => void;
 }
 
 interface BandLinkOptions {
@@ -43,17 +73,22 @@ declare class BandLink implements AsyncIterable<PlatformEvent> {
     readonly capabilities: AgentToolsCapabilities;
     private readonly logger;
     private readonly transport;
-    private readonly subscribedRooms;
+    private readonly subscriptionManager;
     private readonly eventQueue;
     private readonly waiters;
     private connected;
     private lastDisconnectReason;
     private terminalDisconnectError;
+    private readonly connectFlight;
+    private readonly disconnectFlight;
+    private readonly session;
     constructor(options: BandLinkOptions);
     isConnected(): boolean;
     getDisconnectReason(): WebSocketDisconnectReason | null;
     connect(): Promise<void>;
+    private connectSession;
     disconnect(): Promise<void>;
+    private disconnectSession;
     runForever(signal: AbortSignal): Promise<void>;
     private recordDisconnectReason;
     private recordDisconnectError;
@@ -61,7 +96,6 @@ declare class BandLink implements AsyncIterable<PlatformEvent> {
     subscribeAgentRooms(): Promise<void>;
     subscribeRoom(roomId: string): Promise<void>;
     unsubscribeRoom(roomId: string): Promise<void>;
-    private joinRoomTopics;
     subscribeAgentContacts(): Promise<void>;
     unsubscribeAgentContacts(): Promise<void>;
     nextEvent(signal?: AbortSignal): Promise<PlatformEvent | null>;
@@ -80,6 +114,13 @@ declare class BandLink implements AsyncIterable<PlatformEvent> {
     private emit;
 }
 
+/**
+ * Per-turn activity indicator for a room's context.
+ *
+ * Not a lifecycle — see `ExecutionLifecycleState` in `runtime/lifecycle.ts` for
+ * whether the room's `Execution` is alive. The two vocabularies deliberately do
+ * not overlap.
+ */
 type ExecutionState = "starting" | "idle" | "processing";
 interface ExecutionContextLink {
     rest: AgentToolsRestApi;
@@ -117,6 +158,17 @@ declare class ExecutionContext {
     private _llmInitialized;
     private readonly _pendingSystemMessages;
     constructor(options: ExecutionContextOptions);
+    /**
+     * What this room's turn handler is currently doing.
+     *
+     * This is the *per-turn activity* axis, not a lifecycle: it flips to
+     * `"processing"` while the adapter handles an event and back to `"idle"`
+     * afterwards. To ask whether the room's `Execution` is still alive at all,
+     * read `Execution.state` instead, which reports
+     * `"running" | "stopping" | "stopped" | "failed"`.
+     *
+     * @see Execution.state
+     */
     get state(): ExecutionState;
     setState(state: ExecutionState): void;
     getRetryTracker(): RetryTracker;
@@ -147,6 +199,66 @@ declare class ExecutionContext {
     private trackDedup;
 }
 
+/**
+ * Lifecycle of a startable/stoppable runtime owner.
+ *
+ * Shared by {@link Agent}, {@link PlatformRuntime} and {@link AgentRuntime}: the
+ * three components that expose an explicit `start()`/`stop()` pair.
+ *
+ * This describes whether the component is *alive*, not what it is currently
+ * doing for a single turn — see `ExecutionState` in `ExecutionContext.ts` for
+ * that other axis.
+ *
+ * Legal transitions:
+ *
+ * ```text
+ * not_started ─▶ starting ─▶ running ─▶ stopping ─▶ stopped ─┐
+ *                    │           │          │                │
+ *                    └───────────┴──────────┴──▶ failed ─────┤
+ *                                                            │
+ *                    starting ◀──────────────────────────────┘
+ * ```
+ *
+ * `stopped` and `failed` are re-startable: a subsequent `start()` moves back to
+ * `starting`, which is what makes a previously failed teardown recoverable.
+ */
+type RuntimeLifecycleState = {
+    readonly status: "not_started";
+} | {
+    readonly status: "starting";
+} | {
+    readonly status: "running";
+} | {
+    readonly status: "stopping";
+} | {
+    readonly status: "stopped";
+} | {
+    readonly status: "failed";
+    readonly error: Error;
+};
+/**
+ * Lifecycle of a single room's {@link Execution}.
+ *
+ * Narrower than {@link RuntimeLifecycleState} on purpose: an `Execution` starts
+ * processing in its constructor, so it can never occupy a `not_started` or
+ * `starting` state, and it is never restarted. Its state names deliberately do
+ * not overlap with `ExecutionState` (`"starting" | "idle" | "processing"`) so a
+ * bare status string is always attributable to one axis or the other.
+ */
+type ExecutionLifecycleState = {
+    readonly status: "running";
+} | {
+    readonly status: "stopping";
+}
+/** `graceful` is `false` when `stop(timeoutMs)` timed out and detached the process loop. */
+ | {
+    readonly status: "stopped";
+    readonly graceful: boolean;
+} | {
+    readonly status: "failed";
+    readonly error: Error;
+};
+
 interface PlatformRuntimeOptions {
     agentId: string;
     apiKey: string;
@@ -184,27 +296,60 @@ declare class PlatformRuntime implements AsyncDisposable {
     private readonly _onParticipantRemoved?;
     private readonly _roomFilter?;
     private readonly _contextFactory?;
+    private readonly lifecycle;
     private linkInstance?;
     private initPromise;
     private runtime?;
     private contactHandler?;
     private activeAdapter?;
-    private stopping;
+    private readonly startGate;
+    private readonly stopGate;
     private _agentName;
     private _agentDescription;
     private contactsSubscribed;
     constructor(options: PlatformRuntimeOptions);
+    /** Current lifecycle state of this runtime. */
+    get state(): RuntimeLifecycleState;
     get link(): BandLink;
     get name(): string;
     get agentId(): string;
     get description(): string;
     get contactConfiguration(): ContactEventConfig | undefined;
+    /**
+     * Whether the contacts channel subscription is currently held.
+     *
+     * @deprecated Read {@link PlatformRuntime.state} for lifecycle questions: this
+     * flag is only ever `true` while the runtime is running and is cleared on
+     * teardown, so it conflates "contacts are subscribed" with "the runtime is
+     * alive".
+     */
     get isContactsSubscribed(): boolean;
     initialize(): Promise<void>;
     private doInitialize;
+    /**
+     * Connect the adapter to the platform.
+     *
+     * Repeated or concurrent calls join the in-flight start. Calling `start()`
+     * while a `stop()` is still in flight rejects with a {@link RuntimeStateError}.
+     * A successful start also re-arms teardown, so a runtime whose previous
+     * `stop()` failed can be shut down properly on the next attempt.
+     */
     start(adapter: FrameworkAdapter): Promise<void>;
+    private runStart;
+    private doStart;
+    /**
+     * Tear the runtime down and release the platform connection.
+     *
+     * A concurrent second call joins the in-flight teardown and mirrors its
+     * outcome — including rejecting with the *same* `Error` instance — rather than
+     * reporting a graceful shutdown it did not perform. A failed teardown does not
+     * disable future ones: a subsequent `start()` re-arms `stop()`.
+     */
     stop(timeoutMs?: number): Promise<boolean>;
+    private beginStop;
+    private runStop;
     [Symbol.asyncDispose](): Promise<void>;
+    private recordStopFailure;
     runForever(): Promise<void>;
     bootstrapRoomMessage(roomId: string, message: PlatformMessage): Promise<void>;
     resetRoomSession(roomId: string, timeoutMs?: number): Promise<boolean>;
@@ -220,7 +365,7 @@ interface RoomPresenceOptions {
 }
 type RoomPresenceJoinHandler = (roomId: string, payload: MetadataMap) => Promise<void>;
 type RoomPresenceLeaveHandler = (roomId: string) => Promise<void>;
-type RoomPresenceEventHandler = (roomId: string, event: MessageEvent | ParticipantAddedEvent | ParticipantRemovedEvent) => Promise<void>;
+type RoomPresenceEventHandler = (roomId: string, event: MessageEvent | ParticipantAddedEvent | ParticipantRemovedEvent | ReconnectedEvent) => Promise<void>;
 type RoomPresenceContactHandler = (event: ContactEvent) => Promise<void>;
 declare class RoomPresence implements AsyncDisposable {
     readonly roster: RoomRoster;
@@ -235,7 +380,7 @@ declare class RoomPresence implements AsyncDisposable {
     private eventController;
     private eventTask;
     private contactsSubscribed;
-    private lifecycle;
+    private readonly lifecycle;
     private readonly admissionInFlight;
     private readonly lastSubscribeError;
     constructor(options: RoomPresenceOptions);
@@ -250,13 +395,24 @@ declare class RoomPresence implements AsyncDisposable {
     private awaitInFlightAdmission;
     private performAdmission;
     private completeAdmission;
-    private serialize;
     private startBody;
+    private contextualWarnMessage;
+    private subscribeAgentRoomsChannel;
     private subscribeContacts;
     private stopBody;
     private consumeEvents;
     private handleRoomAdded;
     private handleRoomRemoved;
+    /** Unsubscribes the transport topic and clears any remembered subscribe failure for `roomId`. */
+    private leaveRoomTracking;
+    /**
+     * A REST fetch failure here must not blank the roster — it forwards the
+     * reconnect to every currently tracked room regardless, so each room's
+     * `Execution` can still re-run its `/next` synchronization even when
+     * membership reconciliation itself has to wait for the next reconnect.
+     */
+    private handleReconnected;
+    private reconcileRoomsWithSnapshot;
     private unsubscribeRoom;
     private subscribeExistingRooms;
 }
@@ -296,15 +452,44 @@ declare class AgentRuntime {
     private readonly executions;
     private readonly executionWatchers;
     private readonly logger;
-    private running;
-    private stopping;
-    private fatalError;
+    private readonly stoppedSignal;
+    private readonly lifecycle;
+    private readonly startGate;
+    private readonly stopGate;
     constructor(options: AgentRuntimeOptions);
+    /** Current lifecycle state of this runtime. */
+    get state(): RuntimeLifecycleState;
+    /**
+     * Connect, subscribe, and begin consuming platform events.
+     *
+     * Repeated or concurrent calls join the in-flight start instead of starting a
+     * second consume loop. Calling `start()` while a `stop()` is still in flight
+     * rejects with a `RuntimeStateError`.
+     */
     start(): Promise<void>;
+    private runStart;
+    private finishFailedStart;
     private handleStartFailure;
+    /**
+     * Tear the runtime down.
+     *
+     * A concurrent second call joins the in-flight teardown and mirrors its
+     * outcome — including rejecting with the *same* `Error` instance — instead of
+     * reporting a shutdown it did not perform.
+     */
     stop(timeoutMs?: number): Promise<boolean>;
+    private runStop;
+    private performStop;
     getContext(roomId: string): ExecutionContext | undefined;
+    /**
+     * Resolve once the runtime has actually stopped, or reject with the fatal
+     * error that ended it.
+     *
+     * A runtime that was never started stays pending until it stops or fails;
+     * starting it does not resolve a pending wait.
+     */
     waitUntilStopped(): Promise<void>;
+    private markFailed;
     getContexts(): ExecutionContext[];
     enqueueEvent(roomId: string, event: PlatformEvent): Promise<void>;
     bootstrapRoomMessage(roomId: string, message: PlatformMessage): Promise<void>;
@@ -508,12 +693,12 @@ declare const TOOL_MODELS: {
             };
             readonly scope: {
                 readonly type: "string";
-                readonly enum: readonly ["subject", "organization", "all"];
-                readonly description: "Filter by scope.";
+                readonly enum: readonly ["agent", "subject", "organization", "all"];
+                readonly description: string;
             };
             readonly system: {
                 readonly type: "string";
-                readonly enum: readonly ("sensory" | "working" | "long_term")[];
+                readonly enum: readonly _band_ai_band_sdk_core.MemorySystem[];
                 readonly description: "Filter by memory system.";
             };
             readonly type: {
@@ -553,7 +738,7 @@ declare const TOOL_MODELS: {
             };
             readonly system: {
                 readonly type: "string";
-                readonly enum: readonly ("sensory" | "working" | "long_term")[];
+                readonly enum: readonly _band_ai_band_sdk_core.MemorySystem[];
                 readonly description: "Memory system tier.";
             };
             readonly type: {
@@ -572,12 +757,12 @@ declare const TOOL_MODELS: {
             };
             readonly scope: {
                 readonly type: "string";
-                readonly enum: readonly ["subject", "organization"];
-                readonly description: "Visibility scope.";
+                readonly enum: readonly ["agent", "subject", "organization"];
+                readonly description: string;
             };
             readonly subject_id: {
                 readonly type: "string";
-                readonly description: "UUID of the subject this memory is about (required for subject scope).";
+                readonly description: "UUID of the subject this memory is about (required for subject scope; omit for agent scope).";
             };
             readonly metadata: {
                 readonly type: "object";
@@ -628,4 +813,4 @@ declare const MCP_SERVER_NAME = "band";
 declare function mcpToolNames(names: Set<string>): string[];
 declare function getToolDescription(name: string): string;
 
-export { AgentRuntime as A, BandLink as B, CHAT_TOOL_NAMES as C, DefaultPreprocessor as D, type ExecutionContextOptions as E, MCP_SERVER_NAME as M, PlatformRuntime as P, RoomPresence as R, TOOL_MODELS as T, type PlatformRuntimeOptions as a, MCP_TOOL_PREFIX as b, ExecutionContext as c, deriveDefaultRestUrl as d, ALL_TOOL_NAMES as e, BASE_TOOL_NAMES as f, CONTACT_TOOL_NAMES as g, type ExecutionState as h, MEMORY_TOOL_NAMES as i, getToolDescription as j, mcpToolNames as m };
+export { AgentRuntime as A, BandLink as B, CHAT_TOOL_NAMES as C, DefaultPreprocessor as D, type ExecutionContextOptions as E, MCP_SERVER_NAME as M, PlatformRuntime as P, type RuntimeLifecycleState as R, TOOL_MODELS as T, type PlatformRuntimeOptions as a, type ExecutionLifecycleState as b, MCP_TOOL_PREFIX as c, deriveDefaultRestUrl as d, ExecutionContext as e, ALL_TOOL_NAMES as f, BASE_TOOL_NAMES as g, CONTACT_TOOL_NAMES as h, type ExecutionState as i, MEMORY_TOOL_NAMES as j, RoomPresence as k, getToolDescription as l, mcpToolNames as m };