@openclaw/gateway-client 2026.8.1-beta.2 → 2026.9.1-beta.1

package/dist/{protocol-client-BbN-I582.d.mts → protocol-client-C-viHJgO.d.mts}

@@ -1,6 +1,5 @@
-import { n as GatewayProtocolRequestOptions, t as GatewayProtocolRequestError } from "./protocol-request-D4mVhLxE.mjs";
+import { n as GatewayProtocolRequestOptions, t as GatewayProtocolRequestError } from "./protocol-request-r0jkQ1XE.mjs";
 import { ErrorShape, EventFrame, HelloOk } from "@openclaw/gateway-protocol";
-
 //#region packages/gateway-client/src/pending-request.d.ts
 type GatewayProtocolRequestTiming = {
   id: string;
@@ -86,6 +85,7 @@ type GatewayProtocolClientOptions<TPlan> = {
   notifyStoppedClose?: boolean;
   onConnectError?: (error: Error) => void;
   onSocketFactoryError?: (error: Error) => void;
+  onReconnectStopped?: (error: Error) => void;
   onParseError?: (error: unknown) => void;
   onEvent?: (event: EventFrame) => void;
   onGap?: (info: {

package/dist/{protocol-request-D4mVhLxE.d.mts → protocol-request-r0jkQ1XE.d.mts}

@@ -1,5 +1,4 @@
 import { ErrorShape } from "@openclaw/gateway-protocol";
-
 //#region packages/gateway-client/src/protocol-request.d.ts
 type GatewayProtocolRequestOptions = {
   timeoutMs?: number | null;

package/dist/{readiness--KX7i8Mq.d.mts → readiness-CJ1QsCtR.d.mts}

@@ -1,7 +1,7 @@
-import { n as GatewayProtocolRequestOptions, r as GatewayProtocolRequestTimeoutError, t as GatewayProtocolRequestError } from "./protocol-request-D4mVhLxE.mjs";
+import { n as GatewayProtocolRequestOptions, r as GatewayProtocolRequestTimeoutError, t as GatewayProtocolRequestError } from "./protocol-request-r0jkQ1XE.mjs";
+import "./protocol-client-C-viHJgO.mjs";
 import { ConnectParams, ErrorShape, EventFrame, HelloOk } from "@openclaw/gateway-protocol/frame-guards";
 import { GatewayClientMode, GatewayClientName } from "@openclaw/gateway-protocol/client-info";
-
 //#region packages/gateway-client/src/request-error.d.ts
 declare class GatewayClientRequestError extends GatewayProtocolRequestError {
   constructor(error: Partial<ErrorShape>);
@@ -70,6 +70,8 @@ declare function isGatewayConnectAssemblyError(value: unknown): value is Error;
 type GatewayClientOptions = {
   url?: string;
   origin?: string;
+  /** Already-resolved edge-proxy auth headers (identity-aware proxy in front of the Gateway). */
+  edgeAuthHeaders?: Readonly<Record<string, string>>;
   connectChallengeTimeoutMs?: number;
   /**
    * Server-side pre-auth handshake budget. Config-derived local clients use
@@ -80,7 +82,8 @@ type GatewayClientOptions = {
   tickWatchTimeoutMs?: number;
   requestTimeoutMs?: number;
   token?: string;
-  bootstrapToken?: string; /** Prefer one setup credential for the first successful device-auth exchange. */
+  bootstrapToken?: string;
+  /** Prefer one setup credential for the first successful device-auth exchange. */
   preferBootstrapToken?: boolean;
   deviceToken?: string;
   password?: string;
@@ -99,6 +102,7 @@ type GatewayClientOptions = {
   caps?: string[];
   commands?: string[];
   computerUse?: ConnectParams["computerUse"];
+  /** @deprecated Compatibility for the shipped v1 node-host connect envelope. */
   workerRuns?: ConnectParams["workerRuns"];
   permissions?: Record<string, boolean>;
   pathEnv?: string;
@@ -112,6 +116,8 @@ type GatewayClientOptions = {
   onHelloOk?: (hello: HelloOk) => void;
   onConnectError?: (err: Error) => void;
   onReconnectPaused?: (info: GatewayReconnectPausedInfo) => void;
+  /** Report retryable startup closes for clients that present connection progress. */
+  notifyOnStartupRetry?: boolean;
   onClose?: (code: number, reason: string, info?: GatewayClientCloseInfo) => void;
   onGap?: (info: {
     expected: number;
@@ -150,6 +156,7 @@ declare class GatewayClient {
     caps: string[];
     commands: string[];
     computerUse?: ConnectParams["computerUse"];
+    /** @deprecated Compatibility for the shipped v1 node-host connect envelope. */
     workerRuns?: ConnectParams["workerRuns"];
   }): void;
   start(): void;

package/dist/readiness.d.mts

@@ -1,2 +1,2 @@
-import { a as startGatewayClientWithReadinessWait, i as startGatewayClientWhenEventLoopReady, n as GatewayClientStartReadinessOptions, r as GatewayClientStartable, t as EventLoopReadyWaiter } from "./readiness--KX7i8Mq.mjs";
+import { a as startGatewayClientWithReadinessWait, i as startGatewayClientWhenEventLoopReady, n as GatewayClientStartReadinessOptions, r as GatewayClientStartable, t as EventLoopReadyWaiter } from "./readiness-CJ1QsCtR.mjs";
 export { EventLoopReadyWaiter, GatewayClientStartReadinessOptions, GatewayClientStartable, startGatewayClientWhenEventLoopReady, startGatewayClientWithReadinessWait };

package/dist/scope-upgrade.d.mts

@@ -1,6 +1,5 @@
-import { a as GatewayBrowserDeviceTokenStore } from "./browser-device-auth-Dz6H7eXy.mjs";
-import { n as GatewayProtocolRequestOptions } from "./protocol-request-D4mVhLxE.mjs";
-
+import { a as GatewayBrowserDeviceTokenStore } from "./browser-device-auth-DoPo-sPB.mjs";
+import { n as GatewayProtocolRequestOptions } from "./protocol-request-r0jkQ1XE.mjs";
 //#region packages/gateway-client/src/scope-upgrade.d.ts
 type ScopeUpgradeBinding = {
   clientId: string;

package/dist/{session-subscriptions-BTNpXybo.d.mts → session-subscriptions-DNKXLO-Z.d.mts}

@@ -1,3 +1,4 @@
+import { n as GatewayProtocolRequestOptions } from "./protocol-request-r0jkQ1XE.mjs";
 //#region packages/gateway-client/src/device-auth.d.ts
 declare function normalizeDeviceMetadataForAuth(value?: string | null): string;
 type DeviceAuthPayloadParams = {
@@ -23,8 +24,7 @@ declare function gatewayOriginScope(gatewayUrl: string): string;
 /** Normalizes the gateway URL scope used for browser credential records. */
 declare function gatewayCredentialScope(gatewayUrl: string): string;
 //#endregion
-//#region packages/gateway-client/src/session-projection.d.ts
-/** Browser-safe identity and replay rules shared by Gateway conversation clients. */
+//#region packages/gateway-client/src/session-projection-message-identity.d.ts
 type SessionMessageEnvelope = {
   messageId?: unknown;
   messageSeq?: unknown;
@@ -41,6 +41,14 @@ type SessionMessageIdentity = {
   isImported: boolean;
   externalSource: string | null;
 };
+/** History and status markers carry transcript order even when they have no chat role. */
+declare function readSessionMessageSequence(message: unknown, envelope?: SessionMessageEnvelope): number | null;
+/** Run ownership normalizes a user-turn suffix without changing its persisted send key. */
+declare function normalizeSessionProjectionRunId(value: unknown): string | null;
+/** Persisted row facts win; assistant run ownership comes from its authoritative producer. */
+declare function readSessionMessageIdentity(message: unknown, envelope?: SessionMessageEnvelope): SessionMessageIdentity | null;
+//#endregion
+//#region packages/gateway-client/src/session-projection.d.ts
 type SessionProjectionScope = {
   sessionKey?: string;
   sessionId?: string;
@@ -122,12 +130,6 @@ type SessionProjectionEvent = ScopedSessionProjectionEvent & ({
 } | {
   type: "reconnected";
 });
-/** History and status markers carry transcript order even when they have no chat role. */
-declare function readSessionMessageSequence(message: unknown, envelope?: SessionMessageEnvelope): number | null;
-/** Run ownership normalizes a user-turn suffix without changing its persisted send key. */
-declare function normalizeSessionProjectionRunId(value: unknown): string | null;
-/** Persisted transcript facts win over envelope projections and provider-local import IDs. */
-declare function readSessionMessageIdentity(message: unknown, envelope?: SessionMessageEnvelope): SessionMessageIdentity | null;
 /** Local turns have no durable transcript metadata beyond their own optional send key. */
 declare function isLocallyOptimisticSessionMessage(message: unknown): boolean;
 declare function createSessionProjection(scope?: SessionProjectionScope, messages?: readonly unknown[]): SessionProjectionState;
@@ -143,7 +145,7 @@ declare function reduceSessionProjectionRunEvent(projection: SessionProjectionSt
 //#endregion
 //#region packages/gateway-client/src/session-subscriptions.d.ts
 type GatewaySessionMessageRequestClient = {
-  request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
+  request<T = unknown>(method: string, params: Record<string, unknown>, options?: GatewayProtocolRequestOptions): Promise<T>;
 };
 type GatewaySessionMessageSubscription = {
   key: string;
@@ -175,4 +177,4 @@ declare function getGatewaySessionMessageSubscriptionCoordinator(client: Gateway
 declare function resetGatewaySessionMessageSubscriptionCoordinator(client: GatewaySessionMessageRequestClient): void;
 declare function releaseGatewaySessionMessageSubscription(subscription: GatewaySessionMessageSubscription): Promise<void>;
 //#endregion
-export { gatewayCredentialScope as A, normalizeSessionProjectionRunId as C, reconcileSessionProjectionSnapshot as D, readSessionMessageSequence as E, buildDeviceAuthPayload as M, buildDeviceAuthPayloadV3 as N, reduceSessionProjection as O, normalizeDeviceMetadataForAuth as P, isLocallyOptimisticSessionMessage as S, readSessionMessageIdentity as T, SessionProjectionScope as _, GatewaySessionMessageSubscriptionOptions as a, createSessionProjection as b, resetGatewaySessionMessageSubscriptionCoordinator as c, SessionProjectionEntry as d, SessionProjectionEvent as f, SessionProjectionRunTransition as g, SessionProjectionRunStatus as h, GatewaySessionMessageSubscriptionCoordinatorOptions as i, gatewayOriginScope as j, reduceSessionProjectionRunEvent as k, SessionMessageEnvelope as l, SessionProjectionRun as m, GatewaySessionMessageSubscription as n, getGatewaySessionMessageSubscriptionCoordinator as o, SessionProjectionGatewayRunEvent as p, GatewaySessionMessageSubscriptionCoordinator as r, releaseGatewaySessionMessageSubscription as s, GatewaySessionMessageRequestClient as t, SessionMessageIdentity as u, SessionProjectionSnapshotOptions as v, projectLiveSessionMessage as w, hasSessionProjectionAcceptedFinal as x, SessionProjectionState as y };
+export { gatewayCredentialScope as A, reduceSessionProjection as C, normalizeSessionProjectionRunId as D, SessionMessageIdentity as E, buildDeviceAuthPayload as M, buildDeviceAuthPayloadV3 as N, readSessionMessageIdentity as O, normalizeDeviceMetadataForAuth as P, reconcileSessionProjectionSnapshot as S, SessionMessageEnvelope as T, SessionProjectionState as _, GatewaySessionMessageSubscriptionOptions as a, isLocallyOptimisticSessionMessage as b, resetGatewaySessionMessageSubscriptionCoordinator as c, SessionProjectionGatewayRunEvent as d, SessionProjectionRun as f, SessionProjectionSnapshotOptions as g, SessionProjectionScope as h, GatewaySessionMessageSubscriptionCoordinatorOptions as i, gatewayOriginScope as j, readSessionMessageSequence as k, SessionProjectionEntry as l, SessionProjectionRunTransition as m, GatewaySessionMessageSubscription as n, getGatewaySessionMessageSubscriptionCoordinator as o, SessionProjectionRunStatus as p, GatewaySessionMessageSubscriptionCoordinator as r, releaseGatewaySessionMessageSubscription as s, GatewaySessionMessageRequestClient as t, SessionProjectionEvent as u, createSessionProjection as v, reduceSessionProjectionRunEvent as w, projectLiveSessionMessage as x, hasSessionProjectionAcceptedFinal as y };

package/dist/{session-subscriptions-uKmTyc3P.mjs → session-subscriptions-Uxa34zU5.mjs}

@@ -1,4 +1,4 @@
-import { clearGatewayConnectTimeout, resolveSafeTimeoutDelayMs, startGatewayConnectTimeout } from "./timeouts.mjs";
+import { DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS, clearGatewayConnectTimeout, resolveSafeTimeoutDelayMs, startGatewayConnectTimeout } from "./timeouts.mjs";
 import { ConnectErrorDetailCodes, readConnectErrorDetailCode, readConnectErrorRecoveryAdvice, readPairingConnectErrorDetails } from "@openclaw/gateway-protocol/connect-error-details";
 import { isGatewayEventFrame, isGatewayResponseFrame } from "@openclaw/gateway-protocol/frame-guards";
 //#region packages/gateway-client/src/device-auth.ts
@@ -462,8 +462,7 @@ var GatewayPendingRequests = class {
 	constructor(opts) {
 		this.opts = opts;
 		this.pending = /* @__PURE__ */ new Map();
-		this.retiredIds = /* @__PURE__ */ new Set();
-		this.collisionSuffix = 0;
+		this.requestSequence = 0;
 	}
 	get hasPending() {
 		return this.pending.size > 0;
@@ -500,7 +499,6 @@ var GatewayPendingRequests = class {
 			const retire = (errorCode) => {
 				if (this.pending.get(id) !== pending) return false;
 				this.pending.delete(id);
-				this.retiredIds.add(id);
 				cleanup();
 				this.finishTiming(id, pending, false, errorCode);
 				return true;
@@ -564,36 +562,36 @@ var GatewayPendingRequests = class {
 		pending.reject(this.opts.createRequestError?.(frame.error ?? {}) ?? new GatewayProtocolRequestError(frame.error ?? {}));
 	}
 	flush(error) {
-		for (const [id, pending] of this.pending) {
-			this.finishTiming(id, pending, false, "CLIENT_CLOSED");
+		const retired = [...this.pending];
+		this.pending.clear();
+		this.requestSequence = 0;
+		for (const [id, pending] of retired) {
 			pending.cleanup?.();
+			this.finishTiming(id, pending, false, "CLIENT_CLOSED");
 			pending.reject(error);
 		}
-		this.pending.clear();
-		this.retiredIds.clear();
-		this.collisionSuffix = 0;
 	}
 	allocateRequestId() {
-		const id = this.opts.createRequestId();
-		if (!this.pending.has(id) && !this.retiredIds.has(id)) return id;
-		let uniqueId;
-		do {
-			this.collisionSuffix += 1;
-			uniqueId = `${id}:${this.collisionSuffix}`;
-		} while (this.pending.has(uniqueId) || this.retiredIds.has(uniqueId));
-		return uniqueId;
+		this.requestSequence += 1;
+		return `${this.requestSequence}:${this.opts.createRequestId()}`;
 	}
 	finishTiming(id, pending, ok, errorCode) {
 		const endedAtMs = this.opts.nowMs();
-		this.invoke("request timing", () => this.opts.onTiming?.({
-			id,
-			method: pending.method,
-			ok,
-			durationMs: Math.max(0, endedAtMs - pending.startedAtMs),
-			startedAtMs: pending.startedAtMs,
-			endedAtMs,
-			errorCode
-		}));
+		try {
+			const onTiming = this.opts.onTiming;
+			if (onTiming === void 0 || onTiming === null) return;
+			Reflect.apply(onTiming, this.opts, [{
+				id,
+				method: pending.method,
+				ok,
+				durationMs: Math.max(0, endedAtMs - pending.startedAtMs),
+				startedAtMs: pending.startedAtMs,
+				endedAtMs,
+				errorCode
+			}]);
+		} catch (error) {
+			this.opts.onCallbackError?.("request timing", error);
+		}
 	}
 	invoke(label, callback) {
 		try {
@@ -733,8 +731,12 @@ var GatewayProtocolClient = class {
 			const normalized = error instanceof Error ? error : new Error(String(error));
 			this.opts.onSocketFactoryError?.(normalized);
 			this.opts.onConnectError?.(normalized);
-			if (this.opts.rethrowSocketFactoryError?.(normalized)) throw normalized;
+			if (this.opts.rethrowSocketFactoryError?.(normalized)) {
+				if (this.generation > 0 && !this.stopped && !this.socket && !this.reconnectSignal) this.opts.onReconnectStopped?.(normalized);
+				throw normalized;
+			}
 			if (this.opts.shouldRetrySocketFactoryError?.(normalized) && !this.stopped && !this.socket && !this.reconnectSignal) this.scheduleReconnect();
+			else if (this.generation > 0 && !this.stopped && !this.socket && !this.reconnectSignal) this.opts.onReconnectStopped?.(normalized);
 			return;
 		}
 		this.generation = generation;
@@ -927,7 +929,7 @@ var GatewayProtocolClient = class {
 		const decision = this.opts.resolveClose(context);
 		this.requests.flush(decision.pendingError ?? context.connectFailure?.error ?? /* @__PURE__ */ new Error(`gateway closed (${code}): ${reason}`));
 		this.invoke("close", () => this.opts.onClose?.(context, decision));
-		if (decision.retry && !this.stopped) this.scheduleReconnect(decision.reconnectDelayMs ?? context.connectFailure?.reconnectDelayMs);
+		if (decision.retry && !this.stopped && !this.socket && !this.reconnectSignal) this.scheduleReconnect(decision.reconnectDelayMs ?? context.connectFailure?.reconnectDelayMs);
 	}
 	handleSocketError(socket, generation, error) {
 		if (!this.isActive(socket, generation) || this.connectSent) return;
@@ -942,7 +944,7 @@ var GatewayProtocolClient = class {
 		sleepWithAbort(retry.delayMs, retry.signal).then(() => {
 			if (this.reconnectSignal !== retry.signal) return;
 			this.reconnectSignal = null;
-			this.connect();
+			this.invoke("reconnect", () => this.connect());
 		}, () => {
 			if (this.reconnectSignal === retry.signal) this.reconnectSignal = null;
 		});
@@ -983,6 +985,7 @@ const NON_RECOVERABLE_AUTH_ERRORS = /* @__PURE__ */ new Set([
 	ConnectErrorDetailCodes.AUTH_RATE_LIMITED,
 	ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_MISMATCH,
 	ConnectErrorDetailCodes.AUTH_SCOPE_MISMATCH,
+	ConnectErrorDetailCodes.AUTH_IDENTITY_HEADER_REQUIRED,
 	ConnectErrorDetailCodes.CONTROL_UI_BUILD_MISMATCH,
 	ConnectErrorDetailCodes.PAIRING_REQUIRED,
 	ConnectErrorDetailCodes.CONTROL_UI_DEVICE_IDENTITY_REQUIRED,
@@ -994,15 +997,74 @@ function shouldPauseGatewayReconnect(params) {
 	const pairing = readPairingConnectErrorDetails(params.details);
 	if (code === ConnectErrorDetailCodes.PAIRING_REQUIRED && (pairing?.pauseReconnect === false || pairing?.recommendedNextStep === "wait_then_retry")) return false;
 	if (code === ConnectErrorDetailCodes.AUTH_TOKEN_MISMATCH) return params.tokenMismatchIsTerminal === true && !params.deviceTokenRetryPending;
+	if (code === ConnectErrorDetailCodes.AUTH_IDENTITY_HEADER_REQUIRED) return !params.deviceTokenRetryPending;
 	return NON_RECOVERABLE_AUTH_ERRORS.has(code) || params.protocolMismatchIsTerminal === true && code === ConnectErrorDetailCodes.PROTOCOL_MISMATCH || params.clientVersionMismatchIsTerminal === true && code === ConnectErrorDetailCodes.CLIENT_VERSION_MISMATCH;
 }
 //#endregion
+//#region packages/normalization-core/src/record-coerce.ts
+/** Type guard for non-array object records at browser-safe boundaries. */
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Returns a non-array record or null. */
+function asNullableRecord(value) {
+	return isRecord(value) ? value : null;
+}
+//#endregion
+//#region packages/gateway-client/src/session-projection-message-identity.ts
+function readSessionProjectionString(value) {
+	return typeof value === "string" ? value.trim() || null : null;
+}
+function readPositiveSafeInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+/** History and status markers carry transcript order even when they have no chat role. */
+function readSessionMessageSequence(message, envelope) {
+	return readPositiveSafeInteger(asNullableRecord(asNullableRecord(message)?.["__openclaw"])?.seq) ?? readPositiveSafeInteger(envelope?.messageSeq);
+}
+/** Run ownership normalizes a user-turn suffix without changing its persisted send key. */
+function normalizeSessionProjectionRunId(value) {
+	const runId = readSessionProjectionString(value);
+	return runId?.endsWith(":user") ? runId.slice(0, -5) || null : runId;
+}
+/** Persisted row facts win; assistant run ownership comes from its authoritative producer. */
+function readSessionMessageIdentity(message, envelope) {
+	const record = asNullableRecord(message);
+	const role = readSessionProjectionString(record?.role)?.toLowerCase();
+	if (!record || !role) return null;
+	const metadata = asNullableRecord(record["__openclaw"]);
+	const importedFrom = readSessionProjectionString(metadata?.importedFrom);
+	const cliSessionId = readSessionProjectionString(metadata?.cliSessionId);
+	const externalId = readSessionProjectionString(metadata?.externalId);
+	const idempotencyKey = readSessionProjectionString(metadata?.idempotencyKey) ?? readSessionProjectionString(record.idempotencyKey) ?? readSessionProjectionString(envelope?.idempotencyKey) ?? readSessionProjectionString(envelope?.clientRunId);
+	const persistedRunId = normalizeSessionProjectionRunId(idempotencyKey);
+	const envelopeRunId = normalizeSessionProjectionRunId(envelope?.runId);
+	const metadataRunId = normalizeSessionProjectionRunId(metadata?.runId);
+	const mirroredMessage = readSessionProjectionString(metadata?.mirrorOrigin) !== null;
+	const isCliAssistant = role === "assistant" && readSessionProjectionString(record.api)?.toLowerCase() === "cli";
+	const canonicalPersistedRunId = isCliAssistant && persistedRunId?.startsWith("cli-assistant:") ? readSessionProjectionString(persistedRunId.slice(14)) : persistedRunId;
+	const optimisticRunId = metadata && Object.keys(metadata).every((key) => key === "idempotencyKey") ? canonicalPersistedRunId : null;
+	return {
+		role,
+		id: readSessionProjectionString(metadata?.id) ?? readSessionProjectionString(envelope?.messageId),
+		sequence: readSessionMessageSequence(message, envelope),
+		idempotencyKey,
+		runId: role === "assistant" ? metadataRunId ?? envelopeRunId ?? (isCliAssistant || !mirroredMessage ? canonicalPersistedRunId : null) ?? optimisticRunId : metadataRunId ?? canonicalPersistedRunId ?? envelopeRunId,
+		isImported: Boolean(importedFrom || cliSessionId || externalId),
+		externalSource: importedFrom && cliSessionId && externalId ? JSON.stringify([
+			importedFrom,
+			cliSessionId,
+			externalId
+		]) : null
+	};
+}
+//#endregion
 //#region packages/gateway-client/src/session-projection-run-event.ts
-function readNonemptyString$1(value) {
+function readNonemptyString(value) {
 	return typeof value === "string" ? value.trim() || null : null;
 }
 function reduceSessionProjectionRunEventImpl(projection, event, scope = {}) {
-	const runId = readNonemptyString$1(event.runId);
+	const runId = readNonemptyString(event.runId);
 	if (!runId || typeof event.state !== "string" || ![
 		"delta",
 		"final",
@@ -1010,9 +1072,9 @@ function reduceSessionProjectionRunEventImpl(projection, event, scope = {}) {
 		"aborted"
 	].includes(event.state)) return null;
 	const message = event.message;
-	const messageStopReason = message !== null && typeof message === "object" && !Array.isArray(message) ? readNonemptyString$1(message.stopReason) : null;
-	const stopReason = readNonemptyString$1(event.stopReason) ?? messageStopReason;
-	const errorKind = readNonemptyString$1(event.errorKind);
+	const messageStopReason = isRecord(message) ? readNonemptyString(message.stopReason) : null;
+	const stopReason = readNonemptyString(event.stopReason) ?? messageStopReason;
+	const errorKind = readNonemptyString(event.errorKind);
 	const base = {
 		runId,
 		...message === void 0 ? {} : { message },
@@ -1047,53 +1109,11 @@ const SESSION_PROJECTION_SCOPE_KEYS = [
 	"lifecycleRevision",
 	"activeLeafEntryId"
 ];
-function readRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
-function readNonemptyString(value) {
-	return typeof value === "string" ? value.trim() || null : null;
-}
-function readPositiveSafeInteger(value) {
-	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : null;
-}
-/** History and status markers carry transcript order even when they have no chat role. */
-function readSessionMessageSequence(message, envelope) {
-	return readPositiveSafeInteger(readRecord(readRecord(message)?.["__openclaw"])?.seq) ?? readPositiveSafeInteger(envelope?.messageSeq);
-}
-/** Run ownership normalizes a user-turn suffix without changing its persisted send key. */
-function normalizeSessionProjectionRunId(value) {
-	const runId = readNonemptyString(value);
-	return runId?.endsWith(":user") ? runId.slice(0, -5) || null : runId;
-}
-/** Persisted transcript facts win over envelope projections and provider-local import IDs. */
-function readSessionMessageIdentity(message, envelope) {
-	const record = readRecord(message);
-	const role = readNonemptyString(record?.role)?.toLowerCase();
-	if (!record || !role) return null;
-	const metadata = readRecord(record["__openclaw"]);
-	const importedFrom = readNonemptyString(metadata?.importedFrom);
-	const cliSessionId = readNonemptyString(metadata?.cliSessionId);
-	const externalId = readNonemptyString(metadata?.externalId);
-	const idempotencyKey = readNonemptyString(metadata?.idempotencyKey) ?? readNonemptyString(record.idempotencyKey) ?? readNonemptyString(envelope?.idempotencyKey) ?? readNonemptyString(envelope?.clientRunId);
-	return {
-		role,
-		id: readNonemptyString(metadata?.id) ?? readNonemptyString(envelope?.messageId),
-		sequence: readSessionMessageSequence(message, envelope),
-		idempotencyKey,
-		runId: normalizeSessionProjectionRunId(idempotencyKey) ?? normalizeSessionProjectionRunId(envelope?.runId),
-		isImported: Boolean(importedFrom || cliSessionId || externalId),
-		externalSource: importedFrom && cliSessionId && externalId ? JSON.stringify([
-			importedFrom,
-			cliSessionId,
-			externalId
-		]) : null
-	};
-}
 /** Local turns have no durable transcript metadata beyond their own optional send key. */
 function isLocallyOptimisticSessionMessage(message) {
 	const identity = readSessionMessageIdentity(message);
 	if (!identity || identity.role !== "user" && identity.role !== "assistant") return false;
-	const metadata = readRecord(readRecord(message)?.["__openclaw"]);
+	const metadata = asNullableRecord(asNullableRecord(message)?.["__openclaw"]);
 	return !metadata || Object.keys(metadata).every((key) => key === "idempotencyKey");
 }
 function createEntry(message, options) {
@@ -1153,10 +1173,12 @@ function entryMatches(left, right, allowSnapshotPromotion = false) {
 	if (sameTranscriptIdentity(left.identity, right.identity)) return true;
 	const durableEntry = left.identity?.id ? left : right.identity?.id ? right : null;
 	const provisionalEntry = durableEntry === left ? right : durableEntry === right ? left : null;
-	if (durableEntry?.live && provisionalEntry?.live && durableEntry.identity?.role === "assistant" && provisionalEntry.identity?.role === "assistant" && !durableEntry.identity.isImported && !provisionalEntry.identity.isImported && !provisionalEntry.identity.id && durableEntry.identity.runId && durableEntry.identity.runId === provisionalEntry.identity.runId) return true;
+	const durableMetadata = asNullableRecord(asNullableRecord(durableEntry?.message)?.["__openclaw"]);
+	if (durableEntry?.live && provisionalEntry?.live && durableEntry.identity?.role === "assistant" && provisionalEntry.identity?.role === "assistant" && !durableEntry.identity.isImported && !provisionalEntry.identity.isImported && !provisionalEntry.identity.id && durableEntry.identity.runId && durableEntry.identity.runId === provisionalEntry.identity.runId && (readSessionProjectionString(durableMetadata?.mirrorOrigin) === null || durableMetadata?.runTerminal === true)) return true;
 	const persisted = left.identity;
 	const observed = right.identity;
-	if (allowSnapshotPromotion && right.live && persisted && observed && persisted.role === observed.role && !persisted.isImported && !observed.isImported && persisted.id && !observed.id && (persisted.sequence !== null && persisted.sequence === observed.sequence || persisted.role === "assistant" && observed.sequence === null && persisted.runId !== null && persisted.runId === observed.runId)) return true;
+	const persistedMetadata = asNullableRecord(asNullableRecord(left.message)?.["__openclaw"]);
+	if (allowSnapshotPromotion && right.live && persisted && observed && persisted.role === observed.role && !persisted.isImported && !observed.isImported && persisted.id && !observed.id && (persisted.sequence !== null && persisted.sequence === observed.sequence || persisted.role === "assistant" && observed.sequence === null && persisted.runId !== null && persisted.runId === observed.runId && (readSessionProjectionString(persistedMetadata?.mirrorOrigin) === null || persistedMetadata?.runTerminal === true))) return true;
 	if (left.pending && right.pending) return Boolean(left.identity?.role === right.identity?.role && left.pendingRunId && left.pendingRunId === right.pendingRunId);
 	const pending = left.pending ? left : right.pending ? right : null;
 	const authoritative = pending === left ? right : pending === right ? left : null;
@@ -1197,6 +1219,7 @@ function projectLiveSessionMessage(state, message, envelope, scope = {}) {
 	if (existingIndex < 0) return withEntries(state, insertEntry(state.entries, incoming, state.runs));
 	const existing = state.entries[existingIndex];
 	if (existing && existing.message === message && existing.live && !existing.pending) return state;
+	if (existing && !existing.pending && existing.identity?.id && !incoming.identity.id) return state;
 	if (existing?.pending && incoming.identity.sequence !== null) {
 		const sequence = incoming.identity.sequence;
 		return withEntries(state, state.entries.some(({ identity }, index) => identity?.sequence != null && (index < existingIndex ? identity.sequence > sequence : identity.sequence < sequence)) ? insertEntry(state.entries.filter((_, index) => index !== existingIndex), incoming, state.runs) : state.entries.toSpliced(existingIndex, 1, incoming));
@@ -1227,13 +1250,13 @@ function reconcileSessionProjectionSnapshot(state, messages, scope = {}, options
 }
 function hasDisplayableSessionMessage(message) {
 	if (typeof message === "string") return message.trim().length > 0;
-	const record = readRecord(message);
+	const record = asNullableRecord(message);
 	if (!record) return false;
 	const displayableBlocks = Array.isArray(record.content) && record.content.some((block) => {
-		const entry = readRecord(block);
-		return entry ? entry.type !== "text" || readNonemptyString(entry.text) !== null : typeof block === "string" && block.trim().length > 0;
+		const entry = asNullableRecord(block);
+		return entry ? entry.type !== "text" || readSessionProjectionString(entry.text) !== null : typeof block === "string" && block.trim().length > 0;
 	});
-	const media = readRecord(record["__openclaw"])?.media;
+	const media = asNullableRecord(record["__openclaw"])?.media;
 	return Boolean(typeof record.content === "string" && record.content.trim() || displayableBlocks || Array.isArray(media) && media.length > 0);
 }
 function readSessionProjectionFinalMessageIdentity(message) {
@@ -1242,8 +1265,8 @@ function readSessionProjectionFinalMessageIdentity(message) {
 	if (identity?.externalSource) return `import:${identity.role}:${identity.externalSource}`;
 	if (identity?.id && !identity.isImported) return `id:${identity.role}:${identity.id}`;
 	if (identity?.sequence !== null && identity?.sequence !== void 0) return `seq:${identity.role}:${identity.sequence}`;
-	const record = readRecord(message);
-	const metadata = readRecord(record?.["__openclaw"]);
+	const record = asNullableRecord(message);
+	const metadata = asNullableRecord(record?.["__openclaw"]);
 	try {
 		return `content:${JSON.stringify([
 			identity?.role ?? "assistant",
@@ -1274,7 +1297,7 @@ function retainSessionProjectionRuns(runs) {
 	return Object.fromEntries([...active, ...retainedTerminal]);
 }
 function updateRun(state, incoming) {
-	const incomingErrorMessage = readNonemptyString(incoming.errorMessage);
+	const incomingErrorMessage = readSessionProjectionString(incoming.errorMessage);
 	const normalizedIncoming = { ...incoming };
 	if (incomingErrorMessage) normalizedIncoming.errorMessage = incomingErrorMessage;
 	else delete normalizedIncoming.errorMessage;
@@ -1285,7 +1308,7 @@ function updateRun(state, incoming) {
 		const canRecoverFinal = !hasDisplayableSessionMessage(current.message) || (current.acceptedFinalMessageIdentities?.length ?? 0) > 0;
 		const acceptFinal = incomingIsFinal && (current.status === incoming.status || canRecoverFinal) && incomingFinalIdentity !== null && !hasSessionProjectionAcceptedFinal(current, incoming.message);
 		const recoverMessage = acceptFinal && !hasDisplayableSessionMessage(current.message);
-		const recoverError = readNonemptyString(current.errorMessage) === null && incomingErrorMessage !== null;
+		const recoverError = readSessionProjectionString(current.errorMessage) === null && incomingErrorMessage !== null;
 		if (!acceptFinal && !recoverError) return state;
 		const firstFinalIdentity = readSessionProjectionFinalMessageIdentity(current.message);
 		const previousFinalIdentities = current.acceptedFinalMessageIdentities ?? (firstFinalIdentity ? [firstFinalIdentity] : []);
@@ -1433,7 +1456,7 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 			if (this.#retired) throw new Error("Session message subscription belongs to a replaced Gateway connection");
 			const existing = [...this.#entries].find((candidate) => candidate.agentId === agentId && (this.#areKeysEquivalent(candidate.key, normalizedKey) || [...candidate.requestedKeys].some((requestedKey) => this.#areKeysEquivalent(requestedKey, normalizedKey))));
 			if (!existing) {
-				const provisional = [...this.#entries].find((candidate) => candidate.agentId === agentId && !candidate.canonicalSettled);
+				const provisional = [...this.#entries].find((candidate) => candidate.agentId === agentId && !candidate.canonicalSettled && this.#couldShareCanonicalIdentity(candidate.key, normalizedKey));
 				if (provisional) {
 					await (provisional.plainFallback ?? provisional.ready).catch(() => void 0);
 					continue;
@@ -1489,7 +1512,7 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 			entry.release = tracked;
 			return tracked;
 		}
-		const tracked = this.#client.request("sessions.messages.unsubscribe", sessionSubscriptionParams(entry.key, entry.agentId)).then(() => {
+		const tracked = this.#client.request("sessions.messages.unsubscribe", sessionSubscriptionParams(entry.key, entry.agentId), { timeoutMs: DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS }).then(() => {
 			this.#finishRelease(subscription, owner, true);
 		}).finally(() => {
 			if (entry.release === tracked) entry.release = null;
@@ -1564,9 +1587,18 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 		return upgrade;
 	}
 	async #requestSubscribe(entry, includeApprovals) {
-		const result = await this.#client.request("sessions.messages.subscribe", {
-			...sessionSubscriptionParams(entry.key, entry.agentId),
-			...includeApprovals ? { includeApprovals: true } : {}
+		const params = sessionSubscriptionParams(entry.key, entry.agentId);
+		const result = await this.#client.request("sessions.messages.subscribe", includeApprovals ? {
+			...params,
+			includeApprovals: true
+		} : params, { timeoutMs: DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS }).catch(async (error) => {
+			if (!(error instanceof GatewayProtocolRequestTimeoutError) || !error.requestSent || this.#retired) throw error;
+			try {
+				await this.#client.request(entry.handles.size > 0 ? "sessions.messages.subscribe" : "sessions.messages.unsubscribe", params, { timeoutMs: DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS });
+			} catch (recoveryError) {
+				if (!this.#retired) throw new AggregateError([error, recoveryError], "session message subscription recovery failed", { cause: recoveryError });
+			}
+			throw error;
 		});
 		const response = result && typeof result === "object" ? result : null;
 		const responseKey = response && "key" in response ? response.key : void 0;
@@ -1584,6 +1616,11 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 	#areKeysEquivalent(left, right) {
 		return left === right || this.#keysEquivalent?.(left, right) === true;
 	}
+	#couldShareCanonicalIdentity(left, right) {
+		const leftBody = left.replace(/^agent:[^:]+:/i, "").toLowerCase();
+		const rightBody = right.replace(/^agent:[^:]+:/i, "").toLowerCase();
+		return leftBody === rightBody || leftBody === "main" || rightBody === "main" || leftBody === "global" || rightBody === "global";
+	}
 };
 const sessionMessageSubscriptionOwners = /* @__PURE__ */ new WeakMap();
 const sessionMessageSubscriptionCoordinators = /* @__PURE__ */ new WeakMap();
@@ -1602,4 +1639,4 @@ function releaseGatewaySessionMessageSubscription(subscription) {
 	return sessionMessageSubscriptionOwners.get(subscription)?.coordinator.release(subscription) ?? Promise.resolve();
 }
 //#endregion
-export { resolveGatewayConnectScopes as C, buildDeviceAuthPayloadV3 as D, buildDeviceAuthPayload as E, normalizeDeviceMetadataForAuth as O, buildGatewayConnectAuth as S, shouldRetryGatewayWithDeviceToken as T, GatewayProtocolRequestError as _, createSessionProjection as a, gatewayOriginScope as b, normalizeSessionProjectionRunId as c, readSessionMessageSequence as d, reconcileSessionProjectionSnapshot as f, GatewayProtocolClient as g, shouldPauseGatewayReconnect as h, resetGatewaySessionMessageSubscriptionCoordinator as i, projectLiveSessionMessage as l, reduceSessionProjectionRunEvent as m, getGatewaySessionMessageSubscriptionCoordinator as n, hasSessionProjectionAcceptedFinal as o, reduceSessionProjection as p, releaseGatewaySessionMessageSubscription as r, isLocallyOptimisticSessionMessage as s, GatewaySessionMessageSubscriptionCoordinator as t, readSessionMessageIdentity as u, GatewayProtocolRequestTimeoutError as v, selectGatewayConnectAuth as w, GatewayBrowserDeviceAuthLifecycle as x, gatewayCredentialScope as y };
+export { buildGatewayConnectAuth as C, buildDeviceAuthPayload as D, shouldRetryGatewayWithDeviceToken as E, buildDeviceAuthPayloadV3 as O, GatewayBrowserDeviceAuthLifecycle as S, selectGatewayConnectAuth as T, GatewayProtocolClient as _, createSessionProjection as a, gatewayCredentialScope as b, projectLiveSessionMessage as c, reduceSessionProjectionRunEvent as d, normalizeSessionProjectionRunId as f, shouldPauseGatewayReconnect as g, isRecord as h, resetGatewaySessionMessageSubscriptionCoordinator as i, normalizeDeviceMetadataForAuth as k, reconcileSessionProjectionSnapshot as l, readSessionMessageSequence as m, getGatewaySessionMessageSubscriptionCoordinator as n, hasSessionProjectionAcceptedFinal as o, readSessionMessageIdentity as p, releaseGatewaySessionMessageSubscription as r, isLocallyOptimisticSessionMessage as s, GatewaySessionMessageSubscriptionCoordinator as t, reduceSessionProjection as u, GatewayProtocolRequestError as v, resolveGatewayConnectScopes as w, gatewayOriginScope as x, GatewayProtocolRequestTimeoutError as y };

package/dist/websocket-data.d.mts

@@ -1,5 +1,4 @@
 import { RawData } from "ws";
-
 //#region packages/gateway-client/src/websocket-data.d.ts
 declare function rawDataToString(data: RawData, encoding?: BufferEncoding): string;
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/gateway-client",
-  "version": "2026.8.1-beta.2",
+  "version": "2026.9.1-beta.1",
   "description": "Reference WebSocket client for the OpenClaw Gateway protocol",
   "keywords": [
     "client",
@@ -62,9 +62,12 @@
     }
   },
   "dependencies": {
-    "ipaddr.js": "2.4.0",
-    "ws": "8.21.1",
-    "@openclaw/gateway-protocol": "2026.8.1-beta.2"
+    "ipaddr.js": "2.5.0",
+    "ws": "8.21.3",
+    "@openclaw/gateway-protocol": "2026.9.1-beta.1"
+  },
+  "devDependencies": {
+    "@openclaw/normalization-core": "0.0.0-private"
   },
   "engines": {
     "node": ">=22.19.0"