@tangle-network/sandbox 0.11.1-develop.20260718000408.b3f0f2a → 0.11.1-develop.20260718023623.c7df56e

package/dist/session-gateway/index.js

@@ -1,40 +1,65 @@
-//#region src/session-gateway/types.ts
-/**
-* Default connection metrics.
-*/
-const INITIAL_METRICS = {
-	lastPingLatencyMs: null,
-	avgPingLatencyMs: null,
-	missedPongCount: 0,
-	reconnectCount: 0,
-	lastPongAt: null,
-	lastReconnectAt: null,
-	quality: "disconnected"
-};
-/**
-* Calculate connection quality from metrics.
-*/
-function calculateConnectionQuality(metrics, isConnected) {
-	if (!isConnected) return "disconnected";
-	const { avgPingLatencyMs, missedPongCount, reconnectCount, lastReconnectAt } = metrics;
-	const recentReconnect = lastReconnectAt && Date.now() - lastReconnectAt < 300 * 1e3;
-	if (missedPongCount >= 2 || recentReconnect && reconnectCount > 1) return "poor";
-	if (missedPongCount >= 1 || avgPingLatencyMs !== null && avgPingLatencyMs > 1e3 || recentReconnect) return "degraded";
-	if (avgPingLatencyMs !== null && avgPingLatencyMs < 100 && reconnectCount === 0) return "excellent";
-	if (avgPingLatencyMs !== null && avgPingLatencyMs <= 300) return "good";
-	return "good";
+//#region src/session-gateway/callback.ts
+function invokeClientCallback(name, callback, onError) {
+	try {
+		callback();
+	} catch (error) {
+		if (name === "onError") return;
+		try {
+			onError?.(`${name} callback failed: ${error instanceof Error ? error.message : String(error)}`, "CALLBACK_ERROR");
+		} catch {}
+	}
 }
 //#endregion
-//#region src/session-gateway/client.ts
-/**
-* SessionGatewayClient
-*
-* WebSocket client for Sandbox API session streaming.
-* Browser-safe: no Node.js APIs.
-*/
+//#region src/session-gateway/connection-waiters.ts
+var ConnectionWaiters = class {
+	waiters = /* @__PURE__ */ new Set();
+	establishmentTimeout = null;
+	constructor(timeoutMs) {
+		this.timeoutMs = timeoutMs;
+	}
+	start(onTimeout) {
+		this.clear();
+		this.establishmentTimeout = setTimeout(() => {
+			this.establishmentTimeout = null;
+			const error = /* @__PURE__ */ new Error(`Connection establishment timed out after ${this.timeoutMs}ms`);
+			this.rejectAll(error);
+			onTimeout(error);
+		}, this.timeoutMs);
+	}
+	clear() {
+		if (this.establishmentTimeout !== null) {
+			clearTimeout(this.establishmentTimeout);
+			this.establishmentTimeout = null;
+		}
+	}
+	wait() {
+		return new Promise((resolve, reject) => {
+			this.waiters.add({
+				resolve: () => {
+					resolve();
+				},
+				reject: (error) => {
+					reject(error);
+				}
+			});
+		});
+	}
+	resolveAll() {
+		this.clear();
+		for (const waiter of this.waiters) waiter.resolve();
+		this.waiters.clear();
+	}
+	rejectAll(error) {
+		this.clear();
+		for (const waiter of this.waiters) waiter.reject(error);
+		this.waiters.clear();
+	}
+};
+//#endregion
+//#region src/session-gateway/protocol.ts
 const DEFAULT_CONFIG = {
 	transport: "websocket",
-	channels: ["*"],
+	channels: [],
 	autoReconnect: true,
 	maxReconnectAttempts: 10,
 	initialReconnectDelayMs: 1e3,
@@ -46,29 +71,47 @@ const DEFAULT_CONFIG = {
 	maxDeduplicationSize: 1e3,
 	enableReplayPersistence: false,
 	replayStorageKeyPrefix: "session_gateway_",
-	latencyHistorySize: 10
-};
-const STORAGE_KEYS = {
-	lastEventId: "last_event_id",
-	executionId: "execution_id",
-	sessionId: "session_id"
+	latencyHistorySize: 10,
+	connectionEstablishmentTimeoutMs: 1e4
 };
-/**
-* Legacy wire-protocol message type map. The current server emits the
-* `sidecar.*` message types; the SDK surfaces the canonical `runtime.*`
-* names. Kept at module scope so it isn't re-allocated per inbound
-* WebSocket message.
-*/
+const CONTROL_MESSAGE_TYPES = new Set([
+	"connection.established",
+	"subscribed",
+	"unsubscribed",
+	"pong",
+	"replay.start",
+	"replay.progress",
+	"replay.complete",
+	"error",
+	"token.expiring",
+	"token.expired",
+	"backpressure.warning",
+	"terminal.input.error",
+	"heartbeat"
+]);
 const WIRE_TYPE_MAP = {
 	"sidecar.connected": "runtime.connected",
 	"sidecar.disconnected": "runtime.disconnected",
 	"sidecar.not_found": "runtime.not_found",
-	"sidecar.ready": "runtime.ready"
+	"sidecar.ready": "runtime.ready",
+	"sidecar.reconnecting": "runtime.reconnecting",
+	"sidecar.removed": "runtime.removed"
 };
-/**
-* Memory-based storage fallback when localStorage is not available.
-*/
-var MemoryStorage = class {
+function acceptedSubscriptionChannels(acknowledgement) {
+	if (acknowledgement.denied?.length) {
+		const reasons = acknowledgement.denied.map(({ channel, reason }) => `${channel}: ${reason}`).join(", ");
+		throw new Error(`Subscription denied (${reasons})`);
+	}
+	return acknowledgement.channels;
+}
+//#endregion
+//#region src/session-gateway/replay-storage.ts
+const STORAGE_KEYS = {
+	lastEventId: "last_event_id",
+	executionId: "execution_id",
+	sessionId: "session_id"
+};
+var MemoryReplayStorage = class {
 	store = /* @__PURE__ */ new Map();
 	getItem(key) {
 		return this.store.get(key) ?? null;
@@ -80,15 +123,141 @@ var MemoryStorage = class {
 		this.store.delete(key);
 	}
 };
+function resolveReplayStorage(configured) {
+	if (configured) return configured;
+	if (typeof globalThis !== "undefined" && "localStorage" in globalThis) try {
+		const testKey = "__session_gateway_storage_test__";
+		const previous = localStorage.getItem(testKey);
+		try {
+			localStorage.setItem(testKey, testKey);
+			localStorage.removeItem(testKey);
+		} finally {
+			if (previous !== null) localStorage.setItem(testKey, previous);
+		}
+		return localStorage;
+	} catch {
+		return new MemoryReplayStorage();
+	}
+	return new MemoryReplayStorage();
+}
+function endpointIdentity(rawUrl) {
+	const url = new URL(rawUrl);
+	url.username = "";
+	url.password = "";
+	url.hash = "";
+	for (const key of [...url.searchParams.keys()]) if (/(^|[-_])(api[-_]?key|auth|authorization|credential|key|password|secret|sig|signature|token)($|[-_])/i.test(key)) url.searchParams.delete(key);
+	url.searchParams.sort();
+	return url.toString();
+}
+var ReplayStateStore = class {
+	prefix;
+	constructor(enabled, storage, keyPrefix, endpointUrl, sessionId) {
+		this.enabled = enabled;
+		this.storage = storage;
+		this.prefix = `${keyPrefix}${encodeURIComponent(endpointIdentity(endpointUrl))}:${encodeURIComponent(sessionId)}:`;
+	}
+	load() {
+		if (!this.enabled) return this.emptyState();
+		try {
+			return {
+				lastEventId: this.storage.getItem(this.prefix + STORAGE_KEYS.lastEventId),
+				executionId: this.storage.getItem(this.prefix + STORAGE_KEYS.executionId),
+				sessionId: this.storage.getItem(this.prefix + STORAGE_KEYS.sessionId)
+			};
+		} catch {
+			return this.emptyState();
+		}
+	}
+	save(state) {
+		if (!this.enabled) return;
+		try {
+			if (state.lastEventId) this.storage.setItem(this.prefix + STORAGE_KEYS.lastEventId, state.lastEventId);
+			if (state.executionId) this.storage.setItem(this.prefix + STORAGE_KEYS.executionId, state.executionId);
+			if (state.sessionId) this.storage.setItem(this.prefix + STORAGE_KEYS.sessionId, state.sessionId);
+		} catch {}
+	}
+	clear() {
+		if (!this.enabled) return;
+		try {
+			this.storage.removeItem(this.prefix + STORAGE_KEYS.lastEventId);
+			this.storage.removeItem(this.prefix + STORAGE_KEYS.executionId);
+			this.storage.removeItem(this.prefix + STORAGE_KEYS.sessionId);
+		} catch {}
+	}
+	emptyState() {
+		return {
+			lastEventId: null,
+			executionId: null,
+			sessionId: null
+		};
+	}
+};
+//#endregion
+//#region src/session-gateway/token-refresh.ts
+var TokenRefresher = class {
+	refreshing = false;
+	constructor(refreshToken, applyToken, onError) {
+		this.refreshToken = refreshToken;
+		this.applyToken = applyToken;
+		this.onError = onError;
+	}
+	async refresh() {
+		if (!this.refreshToken || this.refreshing) return;
+		this.refreshing = true;
+		try {
+			const result = await this.refreshToken();
+			if (!result.token.trim()) throw new Error("token refresh returned an empty token");
+			this.applyToken(result.token);
+		} catch (error) {
+			invokeClientCallback("onError", () => this.onError?.(`Token refresh failed: ${error instanceof Error ? error.message : String(error)}`, "TOKEN_REFRESH_FAILED"), this.onError);
+		} finally {
+			this.refreshing = false;
+		}
+	}
+};
+//#endregion
+//#region src/session-gateway/types.ts
+/**
+* Default connection metrics.
+*/
+const INITIAL_METRICS = {
+	lastPingLatencyMs: null,
+	avgPingLatencyMs: null,
+	missedPongCount: 0,
+	reconnectCount: 0,
+	lastPongAt: null,
+	lastReconnectAt: null,
+	quality: "disconnected"
+};
+/**
+* Calculate connection quality from metrics.
+*/
+function calculateConnectionQuality(metrics, isConnected) {
+	if (!isConnected) return "disconnected";
+	const { avgPingLatencyMs, missedPongCount, reconnectCount, lastReconnectAt } = metrics;
+	const recentReconnect = lastReconnectAt && Date.now() - lastReconnectAt < 300 * 1e3;
+	if (missedPongCount >= 2 || recentReconnect && reconnectCount > 1) return "poor";
+	if (missedPongCount >= 1 || avgPingLatencyMs !== null && avgPingLatencyMs > 1e3 || recentReconnect) return "degraded";
+	if (avgPingLatencyMs !== null && avgPingLatencyMs < 100 && reconnectCount === 0) return "excellent";
+	if (avgPingLatencyMs !== null && avgPingLatencyMs <= 300) return "good";
+	return "good";
+}
+//#endregion
+//#region src/session-gateway/client.ts
+const CONNECTION_ESTABLISHMENT_TIMEOUT_CODE = 4008;
+const CONNECTION_ERROR_CODE = 4009;
+const CONNECTION_ERROR_REASON = "WebSocket connection error";
 var SessionGatewayClient = class {
 	ws = null;
 	config;
 	handlers;
+	replayStateStore;
+	tokenRefresher;
 	currentToken;
-	isRefreshingToken = false;
 	state = "disconnected";
 	connectedAt = null;
 	hasConnectedBefore = false;
+	connectionEstablishedForSocket = false;
 	lastPingAt = null;
 	lastPongAt = null;
 	lastPingSentAt = null;
@@ -102,6 +271,7 @@ var SessionGatewayClient = class {
 	pingInterval = null;
 	pongTimeout = null;
 	pendingCallbacks = /* @__PURE__ */ new Map();
+	connectionWaiters;
 	messageIdCounter = 0;
 	processedEventIds = /* @__PURE__ */ new Set();
 	pingLatencyHistory = [];
@@ -115,22 +285,12 @@ var SessionGatewayClient = class {
 		received: 0
 	};
 	constructor(config) {
-		let storage;
-		if (config.replayStorage) storage = config.replayStorage;
-		else if (typeof globalThis !== "undefined" && "localStorage" in globalThis) try {
-			const testKey = "__test__";
-			localStorage.setItem(testKey, testKey);
-			localStorage.removeItem(testKey);
-			storage = localStorage;
-		} catch {
-			storage = new MemoryStorage();
-		}
-		else storage = new MemoryStorage();
+		if (!config.token.trim()) throw new Error("Session gateway token must not be empty");
+		const replayStorage = resolveReplayStorage(config.replayStorage);
 		this.config = {
 			url: config.url,
 			sessionId: config.sessionId,
 			token: config.token,
-			onTokenRefresh: config.onTokenRefresh,
 			transport: config.transport ?? DEFAULT_CONFIG.transport,
 			channels: config.channels ?? DEFAULT_CONFIG.channels,
 			autoReconnect: config.autoReconnect ?? DEFAULT_CONFIG.autoReconnect,
@@ -143,11 +303,14 @@ var SessionGatewayClient = class {
 			enableDeduplication: config.enableDeduplication ?? DEFAULT_CONFIG.enableDeduplication,
 			maxDeduplicationSize: config.maxDeduplicationSize ?? DEFAULT_CONFIG.maxDeduplicationSize,
 			enableReplayPersistence: config.enableReplayPersistence ?? DEFAULT_CONFIG.enableReplayPersistence,
-			replayStorage: storage,
 			replayStorageKeyPrefix: config.replayStorageKeyPrefix ?? DEFAULT_CONFIG.replayStorageKeyPrefix,
-			latencyHistorySize: config.latencyHistorySize ?? DEFAULT_CONFIG.latencyHistorySize
+			latencyHistorySize: config.latencyHistorySize ?? DEFAULT_CONFIG.latencyHistorySize,
+			connectionEstablishmentTimeoutMs: config.connectionEstablishmentTimeoutMs ?? DEFAULT_CONFIG.connectionEstablishmentTimeoutMs
 		};
 		this.handlers = config.handlers ?? {};
+		this.connectionWaiters = new ConnectionWaiters(this.config.connectionEstablishmentTimeoutMs);
+		this.replayStateStore = new ReplayStateStore(this.config.enableReplayPersistence, replayStorage, this.config.replayStorageKeyPrefix, this.config.url, this.config.sessionId);
+		this.tokenRefresher = new TokenRefresher(config.onTokenRefresh, (token) => this.updateToken(token), this.handlers.onError);
 		this.currentToken = config.token;
 		if (this.config.enableReplayPersistence) this.loadReplayState();
 	}
@@ -155,30 +318,37 @@ var SessionGatewayClient = class {
 	* Connect to the session gateway.
 	*/
 	connect() {
-		if (this.state === "connected" || this.state === "connecting") return;
-		const isReconnect = this.hasConnectedBefore;
-		this.setState(isReconnect ? "reconnecting" : "connecting");
+		if (this.state === "connected" || this.state === "connecting" || this.state === "reconnecting") return;
+		const nextState = this.hasConnectedBefore ? "reconnecting" : "connecting";
+		this.setState(nextState);
+		if (this.getState() !== nextState) return;
 		this.connectWebSocket();
 	}
 	connectWebSocket() {
 		const url = new URL(this.config.url);
 		url.searchParams.set("token", this.currentToken);
+		this.connectionEstablishedForSocket = false;
 		const socket = new WebSocket(url.toString());
 		this.ws = socket;
 		socket.onopen = () => {
 			if (this.ws === socket) this.handleOpen();
 		};
 		socket.onclose = (event) => this.handleClose(socket, event.code, event.reason);
-		socket.onerror = (_event) => {};
+		socket.onerror = () => this.handleError(socket);
 		socket.onmessage = (event) => {
 			if (this.ws === socket) this.handleMessage(event.data);
 		};
+		this.connectionWaiters.start((error) => {
+			this.closeBeforeEstablishment(socket, CONNECTION_ESTABLISHMENT_TIMEOUT_CODE, error.message);
+		});
 	}
 	/**
 	* Disconnect from the session gateway.
 	*/
 	disconnect() {
+		this.connectionWaiters.rejectAll(/* @__PURE__ */ new Error("Client disconnected"));
 		this.cleanup();
+		this.connectionEstablishedForSocket = false;
 		const socket = this.ws;
 		this.ws = null;
 		if (socket) socket.close(1e3, "Client disconnect");
@@ -188,10 +358,10 @@ var SessionGatewayClient = class {
 	* Subscribe to additional channels.
 	*/
 	async subscribe(channels) {
-		return (await this.sendWithResponse({
+		return acceptedSubscriptionChannels(await this.sendWithResponse({
 			type: "subscribe",
 			channels
-		})).channels;
+		}));
 	}
 	/**
 	* Unsubscribe from channels.
@@ -213,7 +383,9 @@ var SessionGatewayClient = class {
 	/**
 	* Request replay of events since a timestamp.
 	*/
-	replay(since) {
+	async replay(since) {
+		if (!this.connectionEstablishedForSocket || !this.isConnected()) await this.waitForConnectionEstablished();
+		if (!this.connectionEstablishedForSocket || !this.isConnected()) throw new Error("Connection closed before replay could be requested");
 		this.send({
 			type: "replay",
 			since
@@ -255,14 +427,7 @@ var SessionGatewayClient = class {
 		};
 		this.processedEventIds.clear();
 		this.duplicatesSkipped = 0;
-		if (this.config.enableReplayPersistence) {
-			const prefix = this.config.replayStorageKeyPrefix;
-			try {
-				this.config.replayStorage.removeItem(prefix + STORAGE_KEYS.lastEventId);
-				this.config.replayStorage.removeItem(prefix + STORAGE_KEYS.executionId);
-				this.config.replayStorage.removeItem(prefix + STORAGE_KEYS.sessionId);
-			} catch {}
-		}
+		this.replayStateStore.clear();
 	}
 	/**
 	* Get current replay state for UI indicators.
@@ -306,12 +471,13 @@ var SessionGatewayClient = class {
 	resetMetrics() {
 		this.pingLatencyHistory = [];
 		this.connectionMetrics = { ...INITIAL_METRICS };
-		this.handlers.onMetricsChange?.(this.connectionMetrics);
+		invokeClientCallback("onMetricsChange", () => this.handlers.onMetricsChange?.(this.connectionMetrics), this.handlers.onError);
 	}
 	/**
 	* Update the auth token and reconnect with the new token.
 	*/
 	updateToken(token) {
+		if (!token.trim()) throw new Error("Session gateway token must not be empty");
 		this.currentToken = token;
 		if (this.state === "connected" && this.ws) this.ws.close(1e3, "Token refreshed");
 	}
@@ -325,73 +491,110 @@ var SessionGatewayClient = class {
 		if (this.state !== state) {
 			this.state = state;
 			this.updateConnectionQuality();
-			this.handlers.onStateChange?.(state);
+			invokeClientCallback("onStateChange", () => this.handlers.onStateChange?.(state), this.handlers.onError);
 		}
 	}
 	handleOpen() {
+		this.missedPongCount = 0;
+	}
+	handleConnectionEstablished(sessionId) {
+		if (this.connectionEstablishedForSocket) return;
+		this.connectionWaiters.clear();
 		const isReconnect = this.hasConnectedBefore;
+		this.connectionEstablishedForSocket = true;
 		this.hasConnectedBefore = true;
-		this.setState("connected");
 		this.connectedAt = Date.now();
 		this.reconnectAttempts = 0;
-		this.missedPongCount = 0;
 		this.startPingInterval();
 		this.restoreSubscriptions();
-		if (isReconnect) {
+		this.setState("connected");
+		if (!this.connectionEstablishedForSocket || !this.isConnected()) return;
+		this.connectionWaiters.resolveAll();
+		invokeClientCallback("onConnect", () => this.handlers.onConnect?.(sessionId), this.handlers.onError);
+		if (isReconnect && this.connectionEstablishedForSocket && this.isConnected()) {
 			this.trackReconnection();
-			this.handlers.onReconnect?.();
+			invokeClientCallback("onReconnect", () => this.handlers.onReconnect?.(), this.handlers.onError);
 		}
 	}
 	handleClose(socket, code, reason) {
 		if (this.ws !== socket) return;
+		this.connectionWaiters.clear();
 		this.ws = null;
+		this.connectionEstablishedForSocket = false;
 		this.cleanup();
-		this.handlers.onDisconnect?.(code, reason);
 		if (this.config.autoReconnect && this.reconnectAttempts < this.config.maxReconnectAttempts) {
 			this.setState("reconnecting");
-			this.scheduleReconnect();
-		} else this.setState("disconnected");
+			if (this.state === "reconnecting") this.scheduleReconnect();
+		} else {
+			this.connectionWaiters.rejectAll(/* @__PURE__ */ new Error("Connection closed"));
+			this.setState("disconnected");
+		}
+		invokeClientCallback("onDisconnect", () => this.handlers.onDisconnect?.(code, reason), this.handlers.onError);
+	}
+	handleError(socket) {
+		if (this.ws !== socket) return;
+		this.connectionWaiters.clear();
+		this.closeBeforeEstablishment(socket, CONNECTION_ERROR_CODE, CONNECTION_ERROR_REASON);
+	}
+	closeBeforeEstablishment(socket, code, reason) {
+		if (this.ws !== socket || this.connectionEstablishedForSocket) return;
+		try {
+			socket.close(code, reason);
+		} finally {
+			this.handleClose(socket, code, reason);
+		}
 	}
 	handleMessage(data) {
 		this.messagesReceived++;
 		try {
 			const raw = JSON.parse(data);
 			if (!raw.type && raw.messageType) raw.type = raw.messageType;
-			if (typeof raw.type === "string" && WIRE_TYPE_MAP[raw.type] !== void 0) raw.type = WIRE_TYPE_MAP[raw.type];
+			if (typeof raw.type !== "string") {
+				invokeClientCallback("onError", () => this.handlers.onError?.("Session gateway frame is missing a message type", "INVALID_MESSAGE"), void 0);
+				return;
+			}
+			if (WIRE_TYPE_MAP[raw.type] !== void 0) raw.type = WIRE_TYPE_MAP[raw.type];
 			if (raw.data && typeof raw.data === "object") {
 				const d = raw.data;
 				if (d.sidecarId !== void 0 && d.sandboxId === void 0) d.sandboxId = d.sidecarId;
+				if (raw.type === "error") {
+					if (raw.message === void 0 && typeof d.message === "string") raw.message = d.message;
+					if (raw.code === void 0 && typeof d.code === "string") raw.code = d.code;
+				}
 			}
+			if (raw.seq === void 0 && typeof raw.sequenceId === "number") raw.seq = raw.sequenceId;
 			if (raw.type === "agent.event" && !raw.data && raw.channel) {
-				const { type, messageType, channel, id, sequenceId, timestamp, ...rest } = raw;
+				const { type, messageType, channel, id, seq, sequenceId, timestamp, ...rest } = raw;
 				raw.data = rest;
 			}
 			const message = raw;
-			if (message.type === "pong") {
-				this.handlePong(message.timestamp);
-				this.dispatchMessage(message);
+			if (CONTROL_MESSAGE_TYPES.has(message.type)) {
+				if (message.type === "pong") this.handlePong(message.timestamp);
+				this.deliverMessage(message);
 				return;
 			}
-			if ("id" in message && message.id && this.config.enableDeduplication) {
+			if ("id" in message && message.id) {
 				const eventId = message.id;
-				if (this.processedEventIds.has(eventId)) {
-					this.duplicatesSkipped++;
-					return;
-				}
-				this.processedEventIds.add(eventId);
-				if (this.processedEventIds.size > this.config.maxDeduplicationSize) {
-					const entriesToRemove = Math.floor(this.config.maxDeduplicationSize * .1);
-					let removed = 0;
-					for (const oldId of this.processedEventIds) {
-						if (removed >= entriesToRemove) break;
-						this.processedEventIds.delete(oldId);
-						removed++;
+				if (this.config.enableDeduplication) {
+					if (this.processedEventIds.has(eventId)) {
+						this.duplicatesSkipped++;
+						return;
+					}
+					this.processedEventIds.add(eventId);
+					if (this.processedEventIds.size > this.config.maxDeduplicationSize) {
+						const entriesToRemove = Math.floor(this.config.maxDeduplicationSize * .1);
+						let removed = 0;
+						for (const oldId of this.processedEventIds) {
+							if (removed >= entriesToRemove) break;
+							this.processedEventIds.delete(oldId);
+							removed++;
+						}
 					}
 				}
 				this.lastEventId = eventId;
 				this.saveReplayState();
 			}
-			this.dispatchMessage(message);
+			this.deliverMessage(message);
 		} catch {}
 	}
 	handlePong(timestamp) {
@@ -407,6 +610,7 @@ var SessionGatewayClient = class {
 		}
 	}
 	dispatchMessage(message) {
+		if (message.type === "error" && message.code === "REPLAY_CURSOR_UNAVAILABLE") this.clearReplayState();
 		if ("id" in message && message.id) {
 			const callback = this.pendingCallbacks.get(message.id);
 			if (callback) {
@@ -418,7 +622,7 @@ var SessionGatewayClient = class {
 		}
 		switch (message.type) {
 			case "connection.established":
-				this.handlers.onConnect?.(message.data.sessionId);
+				this.handleConnectionEstablished(message.data.sessionId);
 				break;
 			case "runtime.connected":
 				this.handlers.onRuntimeConnected?.(message.data.sandboxId, message.data.baseUrl);
@@ -448,7 +652,7 @@ var SessionGatewayClient = class {
 			case "agent.event":
 				this.eventsReceived++;
 				this.trackExecutionContext(message.data);
-				this.handlers.onAgentEvent?.(message.channel, message.data, message.sequenceId);
+				this.handlers.onAgentEvent?.(message.channel, message.data, message.seq ?? message.sequenceId);
 				break;
 			case "replay.start":
 				this.isReplaying = true;
@@ -470,8 +674,8 @@ var SessionGatewayClient = class {
 				this.handlers.onError?.(message.message, message.code);
 				break;
 			case "token.expiring":
-				this.handlers.onTokenExpiring?.(message.data.secondsRemaining);
-				this.handleTokenExpiring();
+				invokeClientCallback("onTokenExpiring", () => this.handlers.onTokenExpiring?.(message.data.secondsRemaining), this.handlers.onError);
+				this.tokenRefresher.refresh();
 				break;
 			case "token.expired":
 				this.handlers.onTokenExpired?.();
@@ -481,6 +685,10 @@ var SessionGatewayClient = class {
 				break;
 		}
 	}
+	deliverMessage(message) {
+		invokeClientCallback("message dispatch", () => this.dispatchMessage(message), this.handlers.onError);
+		invokeClientCallback("onMessage", () => this.handlers.onMessage?.(message), this.handlers.onError);
+	}
 	trackExecutionContext(data) {
 		if (typeof data !== "object" || data === null) return;
 		const eventData = data;
@@ -493,25 +701,15 @@ var SessionGatewayClient = class {
 			this.saveReplayState();
 		}
 	}
-	async handleTokenExpiring() {
-		if (!this.config.onTokenRefresh || this.isRefreshingToken) return;
-		this.isRefreshingToken = true;
-		try {
-			const result = await this.config.onTokenRefresh();
-			this.updateToken(result.token);
-		} catch (error) {
-			this.handlers.onError?.(`Token refresh failed: ${error instanceof Error ? error.message : String(error)}`, "TOKEN_REFRESH_FAILED");
-		} finally {
-			this.isRefreshingToken = false;
-		}
-	}
 	send(message) {
 		if (this.ws?.readyState === WebSocket.OPEN) {
 			this.ws.send(JSON.stringify(message));
 			this.messagesSent++;
 		}
 	}
-	sendWithResponse(message) {
+	async sendWithResponse(message) {
+		if (!this.connectionEstablishedForSocket || !this.isConnected()) await this.waitForConnectionEstablished();
+		if (!this.connectionEstablishedForSocket || !this.isConnected()) throw new Error("Connection closed before request could be sent");
 		return new Promise((resolve, reject) => {
 			const id = `msg_${++this.messageIdCounter}`;
 			this.pendingCallbacks.set(id, {
@@ -530,14 +728,20 @@ var SessionGatewayClient = class {
 			});
 		});
 	}
+	waitForConnectionEstablished() {
+		if (this.connectionEstablishedForSocket && this.isConnected()) return Promise.resolve();
+		if (this.state === "disconnected") return Promise.reject(/* @__PURE__ */ new Error("Client is not connected"));
+		return this.connectionWaiters.wait();
+	}
 	restoreSubscriptions() {
 		const channels = this.config.channels;
 		const replayOptions = {};
 		if (this.lastEventId) replayOptions.lastEventId = this.lastEventId;
 		if (this.currentExecutionId) replayOptions.executionId = this.currentExecutionId;
 		if (this.currentSessionId) replayOptions.sessionId = this.currentSessionId;
-		const hasReplayState = Object.keys(replayOptions).length > 0;
-		if (hasReplayState) {
+		const hasReplayCursor = this.lastEventId !== null;
+		if (channels.length === 0 && !hasReplayCursor) return;
+		if (hasReplayCursor) {
 			this.isReplaying = true;
 			this.replayProgress = {
 				total: 0,
@@ -547,7 +751,7 @@ var SessionGatewayClient = class {
 		this.send({
 			type: "subscribe",
 			channels,
-			...hasReplayState ? { replayOptions } : {}
+			...hasReplayCursor ? { replayOptions } : {}
 		});
 	}
 	startPingInterval() {
@@ -603,7 +807,7 @@ var SessionGatewayClient = class {
 		const jitter = delay * .3 * (Math.random() * 2 - 1);
 		this.reconnectTimer = setTimeout(() => {
 			this.reconnectTimer = null;
-			this.connect();
+			if (this.state === "reconnecting" && this.ws === null) this.connectWebSocket();
 		}, delay + jitter);
 	}
 	cleanup() {
@@ -637,7 +841,7 @@ var SessionGatewayClient = class {
 				...this.connectionMetrics,
 				quality
 			};
-			this.handlers.onMetricsChange?.(this.connectionMetrics);
+			invokeClientCallback("onMetricsChange", () => this.handlers.onMetricsChange?.(this.connectionMetrics), this.handlers.onError);
 		}
 	}
 	trackReconnection() {
@@ -651,22 +855,17 @@ var SessionGatewayClient = class {
 		this.updateConnectionQuality();
 	}
 	loadReplayState() {
-		if (!this.config.enableReplayPersistence) return;
-		const prefix = this.config.replayStorageKeyPrefix;
-		try {
-			this.lastEventId = this.config.replayStorage.getItem(prefix + STORAGE_KEYS.lastEventId);
-			this.currentExecutionId = this.config.replayStorage.getItem(prefix + STORAGE_KEYS.executionId);
-			this.currentSessionId = this.config.replayStorage.getItem(prefix + STORAGE_KEYS.sessionId);
-		} catch {}
+		const state = this.replayStateStore.load();
+		this.lastEventId = state.lastEventId;
+		this.currentExecutionId = state.executionId;
+		this.currentSessionId = state.sessionId;
 	}
 	saveReplayState() {
-		if (!this.config.enableReplayPersistence) return;
-		const prefix = this.config.replayStorageKeyPrefix;
-		try {
-			if (this.lastEventId) this.config.replayStorage.setItem(prefix + STORAGE_KEYS.lastEventId, this.lastEventId);
-			if (this.currentExecutionId) this.config.replayStorage.setItem(prefix + STORAGE_KEYS.executionId, this.currentExecutionId);
-			if (this.currentSessionId) this.config.replayStorage.setItem(prefix + STORAGE_KEYS.sessionId, this.currentSessionId);
-		} catch {}
+		this.replayStateStore.save({
+			lastEventId: this.lastEventId,
+			executionId: this.currentExecutionId,
+			sessionId: this.currentSessionId
+		});
 	}
 };
 //#endregion