@openclaw/gateway-client 2026.9.3 → 2026.9.5

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as shouldRetryGatewayWithDeviceToken, C as isGatewayProtocolResponseError, D as buildGatewayConnectAuth, E as GatewayBrowserDeviceAuthLifecycle, M as buildDeviceAuthPayloadV3, N as normalizeDeviceMetadataForAuth, O as resolveGatewayConnectScopes, S as GatewayProtocolRequestTimeoutError, T as gatewayOriginScope, _ as readSessionMessageSequence, a as createSessionProjection, b as GatewayProtocolClient, c as projectLiveSessionMessage, d as reduceSessionProjection, f as reduceSessionProjectionRunEvent, g as readSessionMessageIdentity, h as readAssistantStreamSegmentIdentity, i as resetGatewaySessionMessageSubscriptionCoordinator, j as buildDeviceAuthPayload, k as selectGatewayConnectAuth, l as readSessionProjectionFinalMessageIdentity, m as normalizeSessionProjectionRunId, n as getGatewaySessionMessageSubscriptionCoordinator, o as hasSessionProjectionAcceptedFinal, p as isSessionProjectionErrorMessage, r as releaseGatewaySessionMessageSubscription, s as isLocallyOptimisticSessionMessage, t as GatewaySessionMessageSubscriptionCoordinator, u as reconcileSessionProjectionSnapshot, v as isRecord, w as gatewayCredentialScope, x as GatewayProtocolRequestError, y as shouldPauseGatewayReconnect } from "./session-subscriptions-DwU8T0CH.mjs";
+import { A as selectGatewayConnectAuth, C as isGatewayProtocolResponseError, D as GatewayBrowserDeviceAuthLifecycle, E as gatewayOriginScope, M as buildDeviceAuthPayload, N as buildDeviceAuthPayloadV3, O as buildGatewayConnectAuth, P as normalizeDeviceMetadataForAuth, S as GatewayProtocolRequestTimeoutError, T as gatewayCredentialScope, _ as readSessionMessageSequence, a as createSessionProjection, b as GatewayProtocolClient, c as reduceSessionProjection, d as readSessionProjectionFinalMessageIdentity, f as isSessionProjectionErrorMessage, g as readSessionMessageIdentity, h as readAssistantStreamSegmentIdentity, i as resetGatewaySessionMessageSubscriptionCoordinator, j as shouldRetryGatewayWithDeviceToken, k as resolveGatewayConnectScopes, l as reduceSessionProjectionRunEvent, m as normalizeSessionProjectionRunId, n as getGatewaySessionMessageSubscriptionCoordinator, o as projectLiveSessionMessage, p as isLocallyOptimisticSessionMessage, r as releaseGatewaySessionMessageSubscription, s as reconcileSessionProjectionSnapshot, t as GatewaySessionMessageSubscriptionCoordinator, u as hasSessionProjectionAcceptedFinal, v as isRecord, w as resolveModelCatalogConnect, x as GatewayProtocolRequestError, y as shouldPauseGatewayReconnect } from "./session-subscriptions-DrOaOXNR.mjs";
 import { DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS, DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS, MAX_CONNECT_CHALLENGE_TIMEOUT_MS, MAX_SAFE_TIMEOUT_DELAY_MS, MIN_CONNECT_CHALLENGE_TIMEOUT_MS, addSafeTimeoutDelayGraceMs, clampConnectChallengeTimeoutMs, clearGatewayConnectTimeout, getConnectChallengeTimeoutMsFromEnv, resolveConnectChallengeTimeoutMs, resolveFiniteTimeoutDelayMs, resolvePreauthHandshakeTimeoutMs, resolveSafeTimeoutDelayMs, startGatewayConnectTimeout } from "./timeouts.mjs";
 import { rawDataToString } from "./websocket-data.mjs";
 import { n as startGatewayClientWithReadinessWait, r as waitForEventLoopReady, t as startGatewayClientWhenEventLoopReady } from "./readiness-CrWxd4TI.mjs";
@@ -385,6 +385,13 @@ function normalizeGatewayErrorText(value) {
 function isSensitiveUrlQueryParamName(key) {
 	return /(?:token|password|secret|key|auth|credential)/iu.test(key);
 }
+function isGatewayClientStoppedError(err) {
+	const message = err instanceof Error ? err.message : String(err);
+	return message === "gateway client stopped" || message === "Error: gateway client stopped";
+}
+function formatGatewayClientErrorForLog(err) {
+	return String(err).replace(/\/\/([^@/?#\s]+)@/g, "//***:***@").replace(/(Authorization:\s*Bearer\s+)[^\s]+/giu, "$1***").replace(/([?&])([^=&\s]+)=([^&#\s"'<>)]*)/g, (match, prefix, key) => isSensitiveUrlQueryParamName(key) ? `${prefix}${key}=***` : match);
+}
 const SHA256_HEX_FINGERPRINT = /^[a-fA-F0-9]{64}$/u;
 const SHA256_COLON_FINGERPRINT = /^(?:[a-fA-F0-9]{2}:){31}[a-fA-F0-9]{2}$/u;
 function normalizeTlsFingerprint(fingerprint) {
@@ -410,6 +417,115 @@ function parseGatewayIpAddress(host) {
 	return normalized ? parseCanonicalIpAddress(normalized) : void 0;
 }
 //#endregion
+//#region packages/gateway-client/src/client-device-auth.ts
+/** Owns pending host storage work for one client across connection generations. */
+var GatewayClientDeviceAuth = class {
+	constructor(storage) {
+		this.storage = storage;
+		this.operations = /* @__PURE__ */ new Set();
+	}
+	load(params) {
+		const load = () => {
+			params.signal?.throwIfAborted();
+			params.assertCurrent?.();
+			return this.track(this.storage.loadDeviceAuthToken(params));
+		};
+		return this.operations.size > 0 ? this.settle().then(load) : load();
+	}
+	store(params, onStored, onFailed) {
+		const failed = (error) => {
+			const failure = error instanceof Error ? error : new Error(String(error));
+			let reported = false;
+			try {
+				reported = onFailed(failure);
+			} catch {}
+			if (!reported) this.unreportedPersistenceFailure ??= failure;
+			throw failure;
+		};
+		params.signal?.throwIfAborted();
+		params.assertCurrent?.();
+		const stored = this.storage.storeDeviceAuthToken(params);
+		return stored instanceof Promise ? this.track(stored.then(onStored).catch(failed)) : onStored();
+	}
+	clear(params, observation, canClear) {
+		const clear = () => {
+			if (!canClear()) return;
+			const knownTokens = [observation.token, observation.receiptToken].filter((token) => typeof token === "string");
+			const expectedTokens = [...new Set(knownTokens)];
+			if (observation.token === void 0 && expectedTokens.length === 0) expectedTokens.push(void 0);
+			const clearToken = (expectedToken) => {
+				params.signal?.throwIfAborted();
+				params.assertCurrent?.();
+				const cleared = this.storage.clearDeviceAuthToken({
+					...params,
+					...expectedToken === void 0 ? {} : { expectedToken }
+				});
+				return cleared instanceof Promise ? cleared.then(() => {}) : void 0;
+			};
+			let pending;
+			for (const expectedToken of expectedTokens) pending = pending ? pending.then(() => clearToken(expectedToken)) : clearToken(expectedToken);
+			return pending;
+		};
+		return this.track(observation.persistence ? observation.persistence.then(clear, clear) : clear());
+	}
+	async settle() {
+		await Promise.allSettled(this.operations);
+	}
+	async drain() {
+		await this.settle();
+		const failure = this.unreportedPersistenceFailure;
+		this.unreportedPersistenceFailure = void 0;
+		if (failure) throw failure;
+	}
+	track(operation) {
+		if (!(operation instanceof Promise)) return operation;
+		this.operations.add(operation);
+		operation.then(() => this.operations.delete(operation), () => this.operations.delete(operation));
+		return operation;
+	}
+};
+//#endregion
+//#region packages/gateway-client/src/client-upgrade-error.ts
+const MAX_UPGRADE_ERROR_BODY_BYTES = 2048;
+const UPGRADE_ERROR_BODY_TIMEOUT_MS = 1e3;
+async function readUpgradeErrorBody(response) {
+	return await new Promise((resolve) => {
+		const chunks = [];
+		let totalBytes = 0;
+		let settled = false;
+		const finish = () => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			response.off("data", onData);
+			response.off("end", finish);
+			response.off("error", finish);
+			response.off("aborted", finish);
+			resolve(Buffer.concat(chunks, totalBytes).toString("utf8").replace(/\s+/gu, " ").trim());
+		};
+		const stop = () => {
+			finish();
+			response.destroy();
+		};
+		const onData = (chunk) => {
+			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			const remaining = MAX_UPGRADE_ERROR_BODY_BYTES - totalBytes;
+			if (remaining > 0) {
+				const prefix = buffer.subarray(0, remaining);
+				chunks.push(prefix);
+				totalBytes += prefix.byteLength;
+			}
+			if (buffer.byteLength >= remaining) stop();
+		};
+		const timer = setTimeout(stop, UPGRADE_ERROR_BODY_TIMEOUT_MS);
+		timer.unref?.();
+		response.on("data", onData);
+		response.once("end", finish);
+		response.once("error", finish);
+		response.once("aborted", finish);
+	});
+}
+//#endregion
 //#region packages/gateway-client/src/request-error.ts
 var GatewayClientRequestError = class extends GatewayProtocolRequestError {
 	constructor(error) {
@@ -423,6 +539,17 @@ var GatewayClientRequestError = class extends GatewayProtocolRequestError {
 		this.name = "GatewayClientRequestError";
 	}
 };
+const GATEWAY_CONNECT_ASSEMBLY_ERROR = Symbol("gateway.connectAssemblyError");
+function markGatewayConnectAssemblyError(error) {
+	Object.defineProperty(error, GATEWAY_CONNECT_ASSEMBLY_ERROR, {
+		configurable: true,
+		value: true
+	});
+	return error;
+}
+function isGatewayConnectAssemblyError(value) {
+	return value instanceof Error && value[GATEWAY_CONNECT_ASSEMBLY_ERROR] === true;
+}
 //#endregion
 //#region packages/net-policy/src/url-protocol.ts
 function parseUrl(value) {
@@ -538,7 +665,10 @@ function applyGatewayWebSocketTlsPin(options, expectedFingerprint, normalize = n
 //#endregion
 //#region packages/gateway-client/src/websocket.ts
 const require = createRequire(import.meta.url);
-const { WebSocket } = require(path.join(path.dirname(require.resolve("ws/package.json")), "index.js"));
+const wsPackageRoot = path.dirname(require.resolve("ws/package.json"));
+const WebSocket = require(path.join(wsPackageRoot, "lib/websocket.js"));
+require(path.join(wsPackageRoot, "lib/websocket-server.js"));
+require(path.join(wsPackageRoot, "lib/stream.js"));
 //#endregion
 //#region packages/gateway-client/src/client.ts
 const DEFAULT_HOST_DEPS = {
@@ -564,45 +694,6 @@ function resolveHostDeps(overrides) {
 }
 const DEFAULT_GATEWAY_CLIENT_URL = "ws://127.0.0.1:18789";
 const DEFAULT_CLIENT_VERSION = "0.0.0";
-const MAX_UPGRADE_ERROR_BODY_BYTES = 2048;
-const UPGRADE_ERROR_BODY_TIMEOUT_MS = 1e3;
-async function readUpgradeErrorBody(response) {
-	return await new Promise((resolve) => {
-		const chunks = [];
-		let totalBytes = 0;
-		let settled = false;
-		const finish = () => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			response.off("data", onData);
-			response.off("end", finish);
-			response.off("error", finish);
-			response.off("aborted", finish);
-			resolve(Buffer.concat(chunks, totalBytes).toString("utf8").replace(/\s+/gu, " ").trim());
-		};
-		const stop = () => {
-			finish();
-			response.destroy();
-		};
-		const onData = (chunk) => {
-			const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-			const remaining = MAX_UPGRADE_ERROR_BODY_BYTES - totalBytes;
-			if (remaining > 0) {
-				const prefix = buffer.subarray(0, remaining);
-				chunks.push(prefix);
-				totalBytes += prefix.byteLength;
-			}
-			if (buffer.byteLength >= remaining) stop();
-		};
-		const timer = setTimeout(stop, UPGRADE_ERROR_BODY_TIMEOUT_MS);
-		timer.unref?.();
-		response.on("data", onData);
-		response.once("end", finish);
-		response.once("error", finish);
-		response.once("aborted", finish);
-	});
-}
 var GatewayClientRequestTimeoutError = class extends GatewayProtocolRequestTimeoutError {
 	constructor(params) {
 		super(params, `gateway request timeout for ${params.method}`);
@@ -610,24 +701,6 @@ var GatewayClientRequestTimeoutError = class extends GatewayProtocolRequestTimeo
 	}
 };
 var GatewayClientTransportPolicyError = class extends GatewayWebSocketTransportConfigurationError {};
-const GATEWAY_CONNECT_ASSEMBLY_ERROR = Symbol("gateway.connectAssemblyError");
-function markGatewayConnectAssemblyError(error) {
-	Object.defineProperty(error, GATEWAY_CONNECT_ASSEMBLY_ERROR, {
-		configurable: true,
-		value: true
-	});
-	return error;
-}
-function isGatewayConnectAssemblyError(value) {
-	return value instanceof Error && value[GATEWAY_CONNECT_ASSEMBLY_ERROR] === true;
-}
-function isGatewayClientStoppedError(err) {
-	const message = err instanceof Error ? err.message : String(err);
-	return message === "gateway client stopped" || message === "Error: gateway client stopped";
-}
-function formatGatewayClientErrorForLog(err) {
-	return String(err).replace(/\/\/([^@/?#\s]+)@/g, "//***:***@").replace(/(Authorization:\s*Bearer\s+)[^\s]+/giu, "$1***").replace(/([?&])([^=&\s]+)=([^&#\s"'<>)]*)/g, (match, prefix, key) => isSensitiveUrlQueryParamName(key) ? `${prefix}${key}=***` : match);
-}
 const FORCE_STOP_TERMINATE_GRACE_MS = 250;
 const STOP_AND_WAIT_TIMEOUT_MS = 1e3;
 const MAX_SUPPRESSED_TRANSIENT_PRE_HELLO_CLEAN_CLOSES = 1;
@@ -644,7 +717,6 @@ var GatewayClient = class {
 		this.stopped = false;
 		this.useLegacyNodeProtocolEnvelope = false;
 		this.nodeProtocolTransitionPending = false;
-		this.suppressNextHelloCallback = false;
 		this.pendingDeviceTokenRetry = false;
 		this.deviceTokenRetryBudgetUsed = false;
 		this.approvalRuntimeTokenCompatibilityDisabled = false;
@@ -656,6 +728,7 @@ var GatewayClient = class {
 		this.transportValidated = false;
 		this.suppressedTransientPreHelloCleanCloses = 0;
 		this.deps = resolveHostDeps(opts.hostDeps);
+		this.deviceAuth = new GatewayClientDeviceAuth(this.deps);
 		this.opts = {
 			...opts,
 			deviceIdentity: opts.deviceIdentity === null ? void 0 : opts.deviceIdentity ?? this.deps.loadOrCreateDeviceIdentity()
@@ -675,14 +748,32 @@ var GatewayClient = class {
 				requestSent
 			}),
 			createRequestAbortError: createGatewayRequestAbortError,
-			buildConnectPlan: ({ nonce, challengeTs }) => {
+			buildConnectPlan: ({ nonce, challengeTs, serverCapabilities, generation, ...authority }) => {
 				if (!nonce) throw new Error("gateway connect challenge missing nonce");
 				if (this.opts.deviceIdentity && challengeTs == null) throw new Error("gateway connect challenge timestamp invalid");
-				return this.assembleConnectParams({
-					role: this.opts.role ?? "operator",
-					nonce,
-					signedAtMs: challengeTs ?? Date.now()
-				});
+				const role = this.opts.role ?? "operator";
+				const assemble = (storedAuth) => {
+					authority.assertCurrent();
+					const assembled = this.assembleConnectParams({
+						role,
+						nonce,
+						signedAtMs: challengeTs ?? Date.now(),
+						serverCapabilities,
+						storedAuth
+					});
+					this.connectionStoredToken = {
+						generation,
+						token: assembled.storedToken ?? null
+					};
+					return assembled;
+				};
+				const storedAuth = this.opts.deviceIdentity ? this.deviceAuth.load({
+					deviceId: this.opts.deviceIdentity.deviceId,
+					role,
+					env: this.opts.env,
+					...authority
+				}) : null;
+				return storedAuth instanceof Promise ? storedAuth.then(assemble) : assemble(storedAuth);
 			},
 			buildConnectParams: (assembled) => assembled.params,
 			onConnectPlanError: (error) => {
@@ -698,12 +789,8 @@ var GatewayClient = class {
 					error: marked
 				};
 			},
-			onConnectHello: (hello, context) => this.handleConnectHello(hello, context.plan),
+			onConnectHello: (hello, context) => this.handleConnectHello(hello, context.plan, context),
 			onHello: (hello) => {
-				if (this.suppressNextHelloCallback) {
-					this.suppressNextHelloCallback = false;
-					return;
-				}
 				this.opts.onHelloOk?.(hello);
 			},
 			onConnectFailure: (error, context) => this.handleConnectRequestFailure(error, context.plan),
@@ -744,6 +831,11 @@ var GatewayClient = class {
 			rethrowSocketFactoryError: (error) => error instanceof GatewayClientTransportPolicyError
 		});
 	}
+	/** Current transport state, including CLOSING before the close callback fires.
+	* This is not authentication or readiness evidence on its own. */
+	get connected() {
+		return !this.stopped && this.protocol.connected;
+	}
 	getConnectionMetadata() {
 		return {
 			clientName: this.opts.clientName,
@@ -852,6 +944,7 @@ var GatewayClient = class {
 		});
 		ws.on("error", (err) => {
 			if (upgradeError) return;
+			if (err.message === "Opening handshake has timed out") Object.assign(err, { code: "ETIMEDOUT" });
 			this.logDebug(`gateway client error: ${formatGatewayClientErrorForLog(err)}`);
 			handlers.error(err instanceof Error ? err : new Error(String(err)));
 		});
@@ -866,7 +959,6 @@ var GatewayClient = class {
 	}
 	async stopAndWait(opts) {
 		const stopPromise = this.beginStop();
-		if (!stopPromise) return;
 		const timeoutMs = opts?.timeoutMs === void 0 ? STOP_AND_WAIT_TIMEOUT_MS : resolveSafeTimeoutDelayMs(opts.timeoutMs);
 		let timeout = null;
 		try {
@@ -878,6 +970,7 @@ var GatewayClient = class {
 			})]);
 		} finally {
 			if (timeout) clearTimeout(timeout);
+			await this.deviceAuth.drain();
 		}
 	}
 	beginStop() {
@@ -941,7 +1034,7 @@ var GatewayClient = class {
 	}
 	assembleConnectParams(params) {
 		const { role, nonce, signedAtMs } = params;
-		const selectedAuth = this.selectConnectAuth(role);
+		const selectedAuth = this.selectConnectAuth(params.storedAuth);
 		const { authDeviceToken, authApprovalRuntimeToken, authAgentRuntimeIdentityToken, signatureToken, resolvedDeviceToken, storedToken, storedScopes, usingStoredDeviceToken } = selectedAuth;
 		if (this.pendingDeviceTokenRetry && authDeviceToken) this.pendingDeviceTokenRetry = false;
 		const auth = buildGatewayConnectAuth(selectedAuth);
@@ -976,7 +1069,11 @@ var GatewayClient = class {
 					mode: clientMode,
 					instanceId: this.opts.instanceId
 				},
-				caps: Array.isArray(this.opts.caps) ? this.opts.caps : [],
+				...resolveModelCatalogConnect({
+					caps: Array.isArray(this.opts.caps) ? this.opts.caps : [],
+					modelCatalog: useLegacyNodeProtocolEnvelope ? void 0 : this.opts.modelCatalog,
+					serverCapabilities: params.serverCapabilities
+				}),
 				commands: Array.isArray(this.opts.commands) ? this.opts.commands : void 0,
 				computerUse: useLegacyNodeProtocolEnvelope ? void 0 : this.opts.computerUse,
 				workerRuns: useLegacyNodeProtocolEnvelope ? void 0 : this.opts.workerRuns,
@@ -1042,35 +1139,56 @@ var GatewayClient = class {
 			nonce
 		};
 	}
-	handleConnectHello(helloOk, assembled) {
-		const reconnectWithCurrentNodeProtocol = this.useLegacyNodeProtocolEnvelope && this.shouldNegotiateLegacyNodeProtocol() && helloOk.protocol > MIN_NODE_PROTOCOL_VERSION;
-		if (reconnectWithCurrentNodeProtocol) this.useLegacyNodeProtocolEnvelope = false;
-		this.nodeProtocolTransitionPending = false;
-		this.pendingDeviceTokenRetry = false;
-		this.deviceTokenRetryBudgetUsed = false;
-		this.suppressedTransientPreHelloCleanCloses = 0;
+	handleConnectHello(helloOk, assembled, authority) {
+		authority.assertCurrent();
 		const role = this.opts.role ?? "operator";
 		const authInfo = helloOk.auth;
+		const observation = this.connectionStoredToken;
+		const persisted = () => {
+			if (authInfo?.deviceToken && (authInfo.role ?? role) === role && observation) observation.token = authInfo.deviceToken;
+			if (this.opts.preferBootstrapToken) {
+				this.opts.token = void 0;
+				this.opts.bootstrapToken = void 0;
+				this.opts.password = void 0;
+				this.opts.preferBootstrapToken = false;
+			}
+		};
+		let stored = void 0;
 		if (authInfo?.deviceToken && this.opts.deviceIdentity) {
 			const tokenRole = authInfo.role ?? role;
 			const scopes = tokenRole === role && authInfo.deviceToken === assembled.storedToken ? assembled.storedScopes ?? authInfo.scopes ?? [] : authInfo.scopes ?? [];
-			this.deps.storeDeviceAuthToken({
+			if (tokenRole === role && observation) observation.receiptToken = authInfo.deviceToken;
+			stored = this.deviceAuth.store({
 				deviceId: this.opts.deviceIdentity.deviceId,
 				role: tokenRole,
 				token: authInfo.deviceToken,
 				scopes,
-				env: this.opts.env
+				env: this.opts.env,
+				...tokenRole === role ? { expectedToken: assembled.storedToken ?? null } : {}
+			}, persisted, (error) => {
+				assembled.persistenceFailed = true;
+				const reported = this.notifyConnectError(error);
+				this.logError(`gateway device token persistence failed: ${formatGatewayClientErrorForLog(error)}`);
+				return reported;
 			});
-		}
-		if (this.opts.preferBootstrapToken) {
-			this.opts.token = void 0;
-			this.opts.bootstrapToken = void 0;
-			this.opts.password = void 0;
-			this.opts.preferBootstrapToken = false;
-		}
+			if (observation && stored instanceof Promise) observation.persistence = stored;
+		} else persisted();
+		const complete = () => {
+			if (authority.signal.aborted || !this.protocol.connected) return;
+			authority.assertCurrent();
+			this.completeConnectHello(helloOk);
+		};
+		return stored instanceof Promise ? stored.then(complete) : complete();
+	}
+	completeConnectHello(helloOk) {
+		const reconnectWithCurrentNodeProtocol = this.useLegacyNodeProtocolEnvelope && this.shouldNegotiateLegacyNodeProtocol() && helloOk.protocol > MIN_NODE_PROTOCOL_VERSION;
+		if (reconnectWithCurrentNodeProtocol) this.useLegacyNodeProtocolEnvelope = false;
+		this.nodeProtocolTransitionPending = false;
+		this.pendingDeviceTokenRetry = false;
+		this.deviceTokenRetryBudgetUsed = false;
+		this.suppressedTransientPreHelloCleanCloses = 0;
 		this.tickIntervalMs = typeof helloOk.policy?.tickIntervalMs === "number" ? helloOk.policy.tickIntervalMs : 3e4;
 		if (reconnectWithCurrentNodeProtocol) {
-			this.suppressNextHelloCallback = true;
 			this.protocol.resetReconnectBackoff(250);
 			this.protocol.closeSocket(1012, "gateway protocol upgraded");
 			return;
@@ -1079,6 +1197,16 @@ var GatewayClient = class {
 		this.startTickWatch();
 	}
 	handleConnectRequestFailure(error, assembled) {
+		if (assembled.persistenceFailed) return {
+			closeCode: 1008,
+			closeReason: "connect failed"
+		};
+		const detailCode = error instanceof GatewayClientRequestError ? readConnectErrorDetailCode(error.details) : null;
+		const cleared = this.opts.deviceIdentity && assembled.usingStoredDeviceToken && detailCode === ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_MISMATCH ? this.clearDeviceToken(this.opts.deviceIdentity.deviceId, { token: assembled.storedToken }) : void 0;
+		const decision = this.resolveConnectRequestFailure(error, assembled);
+		return cleared instanceof Promise ? cleared.then(() => decision) : decision;
+	}
+	resolveConnectRequestFailure(error, assembled) {
 		if (this.shouldRetryWithCurrentNodeProtocol(error)) {
 			const resetBackoff = !this.nodeProtocolTransitionPending;
 			this.useLegacyNodeProtocolEnvelope = false;
@@ -1102,30 +1230,15 @@ var GatewayClient = class {
 			};
 		}
 		this.nodeProtocolTransitionPending = false;
-		const role = this.opts.role ?? "operator";
 		const detailCode = error instanceof GatewayClientRequestError ? readConnectErrorDetailCode(error.details) : null;
-		const shouldRetryWithDeviceToken = shouldRetryGatewayWithDeviceToken({
+		if (shouldRetryGatewayWithDeviceToken({
 			retryBudgetUsed: this.deviceTokenRetryBudgetUsed,
 			currentDeviceToken: assembled.resolvedDeviceToken,
 			explicitToken: this.opts.token?.trim() || void 0,
 			storedToken: assembled.storedToken,
 			trustedEndpoint: this.isTrustedDeviceRetryEndpoint(),
 			errorDetails: error instanceof GatewayClientRequestError ? error.details : void 0
-		});
-		if (this.opts.deviceIdentity && assembled.usingStoredDeviceToken && detailCode === ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_MISMATCH) {
-			const deviceId = this.opts.deviceIdentity.deviceId;
-			try {
-				this.deps.clearDeviceAuthToken({
-					deviceId,
-					role,
-					env: this.opts.env
-				});
-				this.logDebug(`cleared stale device-auth token for device ${deviceId}`);
-			} catch (clearError) {
-				this.logDebug(`failed clearing stale device-auth token for device ${deviceId}: ${String(clearError)}`);
-			}
-		}
-		if (shouldRetryWithDeviceToken) {
+		})) {
 			this.pendingDeviceTokenRetry = true;
 			this.deviceTokenRetryBudgetUsed = true;
 			this.protocol.resetReconnectBackoff(250);
@@ -1197,7 +1310,7 @@ var GatewayClient = class {
 			this.notifyConnectError(error);
 			this.logError(`gateway connect failed: ${formatGatewayClientErrorForLog(error)}`);
 		}
-		this.clearStaleDeviceTokenForClose(context.code, context.reason);
+		this.clearStaleDeviceTokenForClose(context);
 		if (shouldPauseGatewayReconnect({
 			details,
 			deviceTokenRetryPending: this.pendingDeviceTokenRetry,
@@ -1231,26 +1344,39 @@ var GatewayClient = class {
 			...context.connectFailure?.error ? { connectError: context.connectFailure.error } : {}
 		};
 	}
-	clearStaleDeviceTokenForClose(code, reason) {
-		if (code !== 1008 || !normalizeGatewayErrorText(reason).includes("device token mismatch") || this.opts.token || this.opts.password || !this.opts.deviceIdentity) return;
-		const deviceId = this.opts.deviceIdentity.deviceId;
-		const role = this.opts.role ?? "operator";
+	clearStaleDeviceTokenForClose(context) {
+		const { code, reason, generation } = context;
+		if (code !== 1008 || !normalizeGatewayErrorText(reason).includes("device token mismatch") || !this.opts.deviceIdentity) return;
+		const observation = this.connectionStoredToken?.generation === generation ? this.connectionStoredToken : { token: void 0 };
+		this.clearDeviceToken(this.opts.deviceIdentity.deviceId, observation, () => !this.opts.token && !this.opts.password);
+	}
+	clearDeviceToken(deviceId, observation, canClear = () => true) {
+		const failed = (error) => {
+			this.logDebug(`failed clearing stale device-auth token for device ${deviceId}: ${String(error)}`);
+		};
+		const cleared = () => this.logDebug(`cleared stale device-auth token for device ${deviceId}`);
 		try {
-			this.deps.clearDeviceAuthToken({
+			const result = this.deviceAuth.clear({
 				deviceId,
-				role,
-				env: this.opts.env
-			});
-			this.logDebug(`cleared stale device-auth token for device ${deviceId}`);
+				role: this.opts.role ?? "operator",
+				env: this.opts.env,
+				assertCurrent: () => {
+					if (this.stopped) throw new Error("gateway client stopped");
+				}
+			}, observation, canClear);
+			return result instanceof Promise ? result.then(cleared, failed) : cleared();
 		} catch (error) {
-			this.logDebug(`failed clearing stale device-auth token for device ${deviceId}: ${String(error)}`);
+			failed(error);
 		}
 	}
 	notifyConnectError(error) {
+		if (!this.opts.onConnectError) return false;
 		try {
-			this.opts.onConnectError?.(error);
+			this.opts.onConnectError(error);
+			return true;
 		} catch (err) {
 			this.logDebug(`gateway client connect error handler error: ${formatGatewayClientErrorForLog(err)}`);
+			return false;
 		}
 	}
 	notifyReconnectPaused(info) {
@@ -1286,12 +1412,7 @@ var GatewayClient = class {
 			return false;
 		}
 	}
-	selectConnectAuth(role) {
-		const storedAuth = this.opts.deviceIdentity ? this.deps.loadDeviceAuthToken({
-			deviceId: this.opts.deviceIdentity.deviceId,
-			role,
-			env: this.opts.env
-		}) : null;
+	selectConnectAuth(storedAuth) {
 		return selectGatewayConnectAuth({
 			token: this.opts.token,
 			bootstrapToken: this.opts.bootstrapToken,

package/dist/{protocol-client-DbX7wQED.d.mts → protocol-client-DZ7F1DIs.d.mts}

@@ -23,7 +23,11 @@ type GatewayProtocolSocketHandlers = {
   close: (code: number, reason: string) => void;
   error: (error: Error) => void;
 };
-type GatewayProtocolConnectContext<TPlan> = {
+type GatewayProtocolConnectAuthority = {
+  signal: AbortSignal;
+  assertCurrent: () => void;
+};
+type GatewayProtocolConnectContext<TPlan> = GatewayProtocolConnectAuthority & {
   generation: number;
   nonce: string | null;
   challengeTs: number | null | undefined;
@@ -70,16 +74,17 @@ type GatewayProtocolClientOptions<TPlan> = {
   createRequestError?: (error: Partial<ErrorShape>) => GatewayProtocolRequestError;
   createRequestTimeoutError?: (method: string, timeoutMs: number, requestSent: boolean) => Error;
   createRequestAbortError?: (method: string) => Error;
-  buildConnectPlan: (params: {
+  buildConnectPlan: (params: GatewayProtocolConnectAuthority & {
     nonce: string | null;
     challengeTs: number | null | undefined;
+    serverCapabilities: readonly string[];
     generation: number;
   }) => TPlan | Promise<TPlan>;
   buildConnectParams: (plan: TPlan) => unknown;
   onConnectPlanError?: (error: Error) => GatewayProtocolConnectDecision;
-  onConnectHello?: (hello: HelloOk, context: GatewayProtocolConnectContext<TPlan>) => void;
+  onConnectHello?: (hello: HelloOk, context: GatewayProtocolConnectContext<TPlan>) => unknown;
   onHello?: (hello: HelloOk) => void;
-  onConnectFailure?: (error: GatewayProtocolRequestError, context: GatewayProtocolConnectContext<TPlan>) => GatewayProtocolConnectDecision;
+  onConnectFailure?: (error: GatewayProtocolRequestError, context: GatewayProtocolConnectContext<TPlan>) => GatewayProtocolConnectDecision | Promise<GatewayProtocolConnectDecision>;
   resolveClose: (context: GatewayProtocolCloseContext) => GatewayProtocolCloseDecision;
   onClose?: (context: GatewayProtocolCloseContext, decision: GatewayProtocolCloseDecision) => void;
   notifyStoppedClose?: boolean;
@@ -127,9 +132,11 @@ declare class GatewayProtocolClient<TPlan> {
   private readonly listeners;
   private stopped;
   private generation;
+  private connectionAbort;
   private lastSeq;
   private connectNonce;
   private connectChallengeTs;
+  private serverCapabilities;
   private connectSent;
   private connectRequestSent;
   private handshakeTimer;
@@ -163,10 +170,12 @@ declare class GatewayProtocolClient<TPlan> {
   private handleSocketError;
   private scheduleReconnect;
   private closeContext;
+  private isConnectCurrent;
+  private connectAuthority;
   private isActive;
   private nowMs;
   private clearHandshakeTimer;
   private invoke;
 }
 //#endregion
-export { GatewayProtocolTiming as a, GatewayProtocolSocketHandlers as i, GatewayProtocolCloseContext as n, GatewayProtocolRequestTiming as o, GatewayProtocolSocket as r, GatewayProtocolClient as t };
+export { GatewayProtocolSocketHandlers as a, GatewayProtocolSocket as i, GatewayProtocolCloseContext as n, GatewayProtocolTiming as o, GatewayProtocolConnectAuthority as r, GatewayProtocolRequestTiming as s, GatewayProtocolClient as t };