@openclaw/gateway-client 2026.9.6 → 2026.9.7

package/dist/{session-subscriptions-DUpRfWJb.mjs → session-subscriptions-LtlX9oRQ.mjs}

@@ -1,13 +1,12 @@
 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";
+import { GATEWAY_SUSPEND_IDENTITY_RETRY_AFTER_MS, isGatewaySuspendUnavailableError } from "@openclaw/gateway-protocol/restart-unavailable";
 import { GATEWAY_ASSISTANT_ERROR_FALLBACK_TEXT } from "@openclaw/gateway-protocol/gateway-error-details";
 //#region packages/gateway-client/src/device-auth.ts
 function normalizeDeviceMetadataForAuth(value) {
 	if (typeof value !== "string") return "";
-	const trimmed = value.trim();
-	if (!trimmed) return "";
-	return trimmed.replace(/[A-Z]/g, (char) => String.fromCharCode(char.charCodeAt(0) + 32));
+	return value.trim().replace(/[A-Z]/g, (char) => String.fromCharCode(char.charCodeAt(0) + 32));
 }
 function buildDeviceAuthPayload(params) {
 	const scopes = params.scopes.join(",");
@@ -44,6 +43,63 @@ function buildDeviceAuthPayloadV3(params) {
 	].join("|");
 }
 //#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);
+}
+/** Coerces object-like values to records, falling back to an empty record. */
+function asRecord(value) {
+	return asOptionalObjectRecord(value) ?? {};
+}
+/** Returns a non-array record or null. */
+function asNullableRecord(value) {
+	return isRecord(value) ? value : null;
+}
+/** Returns any object-backed record, including arrays, or undefined. */
+function asOptionalObjectRecord(value) {
+	return value && typeof value === "object" ? value : void 0;
+}
+//#endregion
+//#region packages/gateway-client/src/chat-stream-message.ts
+/** A snapshot includes its delta; append-only frames require an existing baseline. */
+function mergeChatStreamMessage(previous, payload) {
+	if (payload.message !== void 0) return payload.message;
+	const delta = payload.deltaText;
+	if (typeof delta !== "string") return previous;
+	const replace = payload.replace === true;
+	if (!delta && !replace) return previous;
+	if (!isRecord(previous) && !replace) return;
+	const message = isRecord(previous) ? previous : { role: "assistant" };
+	if (typeof message.content === "string") return {
+		...message,
+		content: replace ? delta : message.content + delta
+	};
+	const content = Array.isArray(message.content) ? [...message.content] : [];
+	const isText = (block) => isRecord(block) && block.type === "text";
+	if (replace) return {
+		...message,
+		content: [{
+			type: "text",
+			text: delta
+		}, ...content.filter((block) => !isText(block))]
+	};
+	const index = content.findLastIndex(isText);
+	const block = content[index];
+	if (isText(block)) content[index] = {
+		...block,
+		text: `${typeof block.text === "string" ? block.text : ""}${delta}`
+	};
+	else content.push({
+		type: "text",
+		text: delta
+	});
+	return {
+		...message,
+		content
+	};
+}
+//#endregion
 //#region packages/gateway-client/src/connect-auth.ts
 function normalized(value) {
 	return typeof value === "string" ? value.trim() || void 0 : void 0;
@@ -114,21 +170,19 @@ var GatewayBrowserDeviceAuthLifecycle = class {
 			deviceId: identity.deviceId,
 			role: params.role
 		}) : null;
-		const storedValue = stored?.token;
 		const selectedAuth = selectGatewayConnectAuth({
 			token: params.token,
 			bootstrapToken: params.bootstrapToken,
 			password: params.password,
-			storedToken: storedValue,
+			storedToken: stored?.token,
 			storedScopes: stored?.scopes,
 			pendingDeviceTokenRetry: params.pendingDeviceTokenRetry,
 			trustedDeviceTokenRetry: params.trustedDeviceTokenRetry,
 			preferBootstrapToken: params.preferBootstrapToken
 		});
-		const { usingStoredDeviceToken } = selectedAuth;
 		const scopes = resolveGatewayConnectScopes({
 			requestedScopes: selectedAuth.authBootstrapToken ? params.bootstrapScopes ? [...params.bootstrapScopes] : void 0 : void 0,
-			usingStoredDeviceToken,
+			usingStoredDeviceToken: selectedAuth.usingStoredDeviceToken,
 			storedScopes: selectedAuth.storedScopes,
 			defaultScopes: params.defaultScopes
 		});
@@ -143,10 +197,6 @@ var GatewayBrowserDeviceAuthLifecycle = class {
 		const signedAtMs = params.challengeTs === void 0 ? this.deps.nowMs?.() ?? Date.now() : params.challengeTs;
 		if (typeof signedAtMs !== "number" || !Number.isSafeInteger(signedAtMs) || signedAtMs < 0) throw new Error("gateway connect challenge timestamp invalid");
 		const nonce = params.nonce ?? "";
-		const { authBootstrapToken: primary, signatureToken: signed } = selectedAuth;
-		let token = null;
-		if (primary) token = primary;
-		else if (signed) token = signed;
 		const payload = buildDeviceAuthPayloadV3({
 			deviceId: identity.deviceId,
 			clientId: params.client.id,
@@ -154,7 +204,7 @@ var GatewayBrowserDeviceAuthLifecycle = class {
 			role: params.role,
 			scopes,
 			signedAtMs,
-			token,
+			token: selectedAuth.authBootstrapToken || selectedAuth.signatureToken || null,
 			nonce,
 			platform: params.client.platform,
 			deviceFamily: params.client.deviceFamily
@@ -245,9 +295,12 @@ function computeBackoff(policy, attempt) {
 	const jitter = base * policy.jitter * Math.random();
 	return Math.min(policy.maxMs, Math.round(base + jitter));
 }
+function resolveSleepDelayMs(ms) {
+	return Number.isFinite(ms) && ms > 0 ? Math.min(Math.max(Math.floor(ms), 1), MAX_TIMER_TIMEOUT_MS) : 0;
+}
 async function sleepWithAbort(ms, abortSignal, options = {}) {
-	if (!Number.isFinite(ms) || ms <= 0) return;
-	const delayMs = Math.min(Math.max(Math.floor(ms), 1), MAX_TIMER_TIMEOUT_MS);
+	const delayMs = resolveSleepDelayMs(ms);
+	if (delayMs === 0) return;
 	await new Promise((resolve, reject) => {
 		let settled = false;
 		let timer = null;
@@ -330,21 +383,18 @@ const defaultSleep = async (ms) => {
 	} while (remainingMs > 0);
 };
 function clampNumber(value, fallback, min, max) {
-	const next = Number.isFinite(value) ? value : void 0;
-	if (next === void 0) return fallback;
-	return Math.min(Math.max(next, min ?? Number.NEGATIVE_INFINITY), max ?? Number.POSITIVE_INFINITY);
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	return Math.min(Math.max(value, min ?? Number.NEGATIVE_INFINITY), max ?? Number.POSITIVE_INFINITY);
 }
 function resolveAttemptCount(value, fallback) {
-	return Math.max(1, Math.round(Number.isFinite(value) ? value : fallback));
+	return Math.max(1, Math.round(clampNumber(value, fallback)));
 }
 function resolveRetryDelayMs(value) {
-	const finite = value === Number.POSITIVE_INFINITY ? MAX_TIMER_TIMEOUT_MS : Number.isFinite(value) ? value : 0;
-	return Math.min(Math.max(Math.round(finite), 0), MAX_TIMER_TIMEOUT_MS);
+	return Math.min(Math.max(Math.round(value === Number.POSITIVE_INFINITY ? MAX_TIMER_TIMEOUT_MS : Number.isFinite(value) ? value : 0), 0), MAX_TIMER_TIMEOUT_MS);
 }
 function resolveJitterConfig(value, fallback) {
 	if (value === "full") return "full";
-	const fraction = Number.isFinite(value) ? value : void 0;
-	return fraction === void 0 ? fallback : Math.min(Math.max(fraction, 0), 1);
+	return typeof value === "number" && Number.isFinite(value) ? Math.min(Math.max(value, 0), 1) : fallback;
 }
 function resolveRetryConfig(defaults = DEFAULT_RETRY_CONFIG, overrides) {
 	const attempts = resolveAttemptCount(overrides?.attempts, defaults.attempts);
@@ -499,6 +549,20 @@ var GatewayPendingRequests = class {
 		this.pending = /* @__PURE__ */ new Map();
 		this.requestSequence = 0;
 	}
+	setSuspensionPhase(phase) {
+		if (phase === "accepting") this.resumeIdentityRequests();
+		else if (phase === "preparing" || phase === "draining" || phase === "prepared") this.pauseIdentityRequests();
+	}
+	pauseIdentityRequests(retryAfterMs = GATEWAY_SUSPEND_IDENTITY_RETRY_AFTER_MS) {
+		clearTimeout(this.suspensionTimer);
+		this.suspensionTimer = setTimeout(() => this.resumeIdentityRequests(), resolveSafeTimeoutDelayMs(Number.isFinite(retryAfterMs) && retryAfterMs > 0 ? retryAfterMs : GATEWAY_SUSPEND_IDENTITY_RETRY_AFTER_MS));
+		this.suspensionTimer.unref?.();
+	}
+	resumeIdentityRequests() {
+		clearTimeout(this.suspensionTimer);
+		this.suspensionTimer = void 0;
+		for (const pending of this.pending.values()) if (pending.waitingForResume) pending.resend?.();
+	}
 	get hasPending() {
 		return this.pending.size > 0;
 	}
@@ -562,15 +626,27 @@ var GatewayPendingRequests = class {
 			options?.signal?.addEventListener("abort", onAbort, { once: true });
 			this.pending.set(id, pending);
 			try {
-				sender.send(JSON.stringify({
+				const frame = JSON.stringify({
 					type: "req",
 					id,
 					method,
 					params
-				}));
-				if (this.pending.get(id) !== pending) return;
-				requestSent = true;
-				this.invoke("sent", () => options?.onSent?.(id));
+				});
+				const send = () => {
+					if (this.pending.get(id) !== pending) return;
+					pending.waitingForResume = Boolean(pending.resend && this.suspensionTimer);
+					if (pending.waitingForResume) return;
+					try {
+						sender.send(frame);
+						if (this.pending.get(id) !== pending) return;
+						requestSent = true;
+						this.invoke("sent", () => options?.onSent?.(id));
+					} catch (error) {
+						if (retire("CLIENT_SEND_ERROR")) reject(error instanceof Error ? error : new Error(String(error)));
+					}
+				};
+				if (method === "agent.identity.get") pending.resend = send;
+				send();
 			} catch (error) {
 				if (retire("CLIENT_SEND_ERROR")) reject(error instanceof Error ? error : new Error(String(error)));
 			}
@@ -587,6 +663,11 @@ var GatewayPendingRequests = class {
 			}
 			return;
 		}
+		if (!frame.ok && pending.resend && !pending.acceptedNotified && frame.error?.code === "UNAVAILABLE" && frame.error.retryable === true && isGatewaySuspendUnavailableError(frame.error)) {
+			this.pauseIdentityRequests(frame.error.retryAfterMs);
+			pending.waitingForResume = true;
+			return;
+		}
 		this.pending.delete(frame.id);
 		pending.cleanup?.();
 		if (frame.ok) {
@@ -600,6 +681,8 @@ var GatewayPendingRequests = class {
 		pending.reject(error);
 	}
 	flush(error) {
+		clearTimeout(this.suspensionTimer);
+		this.suspensionTimer = void 0;
 		const retired = this.pending;
 		this.pending = /* @__PURE__ */ new Map();
 		this.requestSequence = 0;
@@ -615,19 +698,15 @@ var GatewayPendingRequests = class {
 	}
 	finishTiming(id, pending, ok, errorCode) {
 		const endedAtMs = this.opts.nowMs();
-		try {
-			this.opts.onTiming?.({
-				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);
-		}
+		this.invoke("request timing", () => this.opts.onTiming?.({
+			id,
+			method: pending.method,
+			ok,
+			durationMs: Math.max(0, endedAtMs - pending.startedAtMs),
+			startedAtMs: pending.startedAtMs,
+			endedAtMs,
+			errorCode
+		}));
 	}
 	invoke(label, callback) {
 		try {
@@ -872,6 +951,7 @@ var GatewayProtocolClient = class {
 		this.request("connect", this.opts.buildConnectParams(plan)).then((hello) => {
 			if (!this.isConnectCurrent(socket, generation)) return;
 			this.helloReceived = true;
+			this.requests.setSuspensionPhase(hello.snapshot?.suspension?.phase);
 			this.clearHandshakeTimer();
 			this.connectFailure = void 0;
 			this.reconnectSupervisor.reset();
@@ -910,7 +990,7 @@ var GatewayProtocolClient = class {
 		});
 	}
 	handleMessage(socket, generation, raw) {
-		if (!this.isActive(socket, generation)) return;
+		if (!this.isActive(socket, generation) || this.connectionAbort?.signal.aborted) return;
 		let parsed;
 		try {
 			parsed = JSON.parse(raw);
@@ -943,26 +1023,34 @@ var GatewayProtocolClient = class {
 			if (seq !== null) {
 				if (this.lastSeq !== null && seq > this.lastSeq + 1) {
 					const expected = this.lastSeq + 1;
+					const state = asRecord(parsed.payload).state;
+					if (parsed.event === "chat" && (state === "final" || state === "error" || state === "aborted")) this.dispatchEvent(socket, generation, parsed);
+					if (!this.isActive(socket, generation) || this.connectionAbort?.signal.aborted) return;
 					this.invoke("gap", () => this.opts.onGap?.({
 						expected,
 						received: seq
 					}));
-					if (!this.isActive(socket, generation)) return;
+					if (this.isActive(socket, generation) && !this.connectionAbort?.signal.aborted) this.closeSocket(4e3, "event sequence gap");
+					return;
 				}
 				this.lastSeq = seq;
 			}
-			const listeners = this.listeners.snapshot();
-			this.invoke("event", () => this.opts.onEvent?.(parsed));
-			for (const [listener, subscription] of listeners) {
-				if (!this.isActive(socket, generation)) return;
-				if (this.listeners.isCurrent(listener, subscription)) this.invoke("event listener", () => listener(parsed));
-			}
+			this.dispatchEvent(socket, generation, parsed);
 			return;
 		}
 		if (!isGatewayResponseFrame(parsed)) return;
 		this.opts.onActivity?.();
 		this.requests.handleResponse(parsed);
 	}
+	dispatchEvent(socket, generation, event) {
+		const listeners = this.listeners.snapshot();
+		if (event.event === "gateway.suspension" && typeof event.payload === "object" && event.payload !== null && "phase" in event.payload) this.requests.setSuspensionPhase(event.payload.phase);
+		this.invoke("event", () => this.opts.onEvent?.(event));
+		for (const [listener, subscription] of listeners) {
+			if (!this.isActive(socket, generation) || this.connectionAbort?.signal.aborted) return;
+			if (this.listeners.isCurrent(listener, subscription)) this.invoke("event listener", () => listener(event));
+		}
+	}
 	handleClose(socket, generation, code, reason) {
 		if (this.socket !== socket) {
 			if (this.stoppedSocket?.socket === socket) {
@@ -1008,13 +1096,23 @@ var GatewayProtocolClient = class {
 		const retry = this.reconnectSupervisor.next();
 		if (!retry) return;
 		this.reconnectSignal = retry.signal;
-		sleepWithAbort(overrideMs ?? Math.max(retry.delayMs, minimumMs), retry.signal).then(() => {
+		let delayMs = overrideMs;
+		if (delayMs === void 0) {
+			const base = Math.max(retry.delayMs, minimumMs);
+			const ceiling = Math.max(this.opts.reconnect.maxMs, Math.min(Number.MAX_VALUE, minimumMs * 1.2));
+			const lower = Math.max(minimumMs, Math.min(base, ceiling / 1.2));
+			const upper = Math.min(base * 1.2, ceiling);
+			delayMs = Math.ceil(lower + Math.random() * (upper - lower));
+		}
+		delayMs = resolveSleepDelayMs(delayMs);
+		sleepWithAbort(delayMs, retry.signal).then(() => {
 			if (this.reconnectSignal !== retry.signal) return;
 			this.reconnectSignal = null;
 			this.invoke("reconnect", () => this.connect());
 		}, () => {
 			if (this.reconnectSignal === retry.signal) this.reconnectSignal = null;
 		});
+		this.invoke("reconnect scheduled", () => this.opts.onReconnectScheduled?.(delayMs, retry.signal));
 	}
 	closeContext() {
 		return {
@@ -1083,16 +1181,6 @@ function shouldPauseGatewayReconnect(params) {
 	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/normalization-core/src/stable-stringify.ts
 const preserveString = (value) => value;
 /** Deterministically stringifies values, optionally normalizing strings before key ordering. */
@@ -1346,12 +1434,7 @@ function isSessionProjectionErrorMessage(message, errorMessage) {
 //#endregion
 //#region packages/gateway-client/src/session-projection-final-identity.ts
 /** Terminal identity rules used to reconcile live and durable assistant projections. */
-/**
-* The class of rows the #148297 relaxation newly admits as finals: persisted
-* with the run's terminal tool stop reason while carrying no tool-call
-* content. Both adoption directions and every position rule scope to this
-* predicate, so pre-existing match semantics stay untouched.
-*/
+/** A run's selected text reply can inherit its terminal tool stop reason. */
 function isToolUsePersistedFinalRow(message) {
 	return asNullableRecord(message)?.["stopReason"] === "toolUse" && !isSessionProjectionToolContinuation(message);
 }
@@ -1448,22 +1531,15 @@ function findUniqueSnapshotTerminalMatch(current, matches, run, snapshot) {
 		});
 		snapshotIndexes = indexes;
 	};
-	const hasCompletedRunSnapshotContext = (entry) => {
-		const runId = current.identity?.runId;
-		if (!runId || entry.identity?.runId !== runId) return false;
-		ensureRunIndexes();
-		const entryIndex = snapshotIndexes?.get(entry);
-		return entryIndex !== void 0 && firstUserIndex >= 0 && firstUserIndex < entryIndex && lastAssistantIndex <= entryIndex;
-	};
-	const isLastSameRunAssistantRow = (entry) => {
+	const hasTerminalSnapshotPosition = (entry, requireUser) => {
 		const runId = current.identity?.runId;
 		if (!runId || entry.identity?.runId !== runId) return false;
 		ensureRunIndexes();
 		const entryIndex = snapshotIndexes?.get(entry);
-		return entryIndex !== void 0 && lastAssistantIndex >= 0 && entryIndex >= lastAssistantIndex;
+		return entryIndex !== void 0 && lastAssistantIndex <= entryIndex && (requireUser ? firstUserIndex >= 0 && firstUserIndex < entryIndex : lastAssistantIndex >= 0);
 	};
 	const durableTerminalMatches = matches.filter((entry) => {
-		return (asNullableRecord(asNullableRecord(entry.message)?.["__openclaw"])?.runTerminal === true || entry.identity?.runId === current.identity?.runId && (hasTerminalStopReason(entry.message) || asNullableRecord(entry.message)?.["stopReason"] === "toolUse" && !isSessionProjectionToolContinuation(entry.message) && isLastSameRunAssistantRow(entry)) || hasCompletedRunSnapshotContext(entry)) && readFinalContentIdentity(entry.message) === terminalContent;
+		return (asNullableRecord(asNullableRecord(entry.message)?.["__openclaw"])?.runTerminal === true || entry.identity?.runId === current.identity?.runId && (hasTerminalStopReason(entry.message) || isToolUsePersistedFinalRow(entry.message) && hasTerminalSnapshotPosition(entry, false)) || hasTerminalSnapshotPosition(entry, true)) && readFinalContentIdentity(entry.message) === terminalContent;
 	});
 	const entry = durableTerminalMatches.length === 1 ? durableTerminalMatches[0] : void 0;
 	if (!entry) return null;
@@ -1493,22 +1569,19 @@ function retainSessionProjectionRuns(runs) {
 }
 //#endregion
 //#region packages/gateway-client/src/session-projection-run-event.ts
-function readNonemptyString(value) {
-	return typeof value === "string" ? value.trim() || null : null;
-}
 /** Normalizes Gateway run envelopes once for every browser and terminal adapter. */
 function reduceSessionProjectionRunEvent(projection, event, scope = {}) {
-	const runId = readNonemptyString(event.runId);
+	const runId = readSessionProjectionString(event.runId);
 	if (!runId || typeof event.state !== "string" || ![
 		"delta",
 		"final",
 		"error",
 		"aborted"
 	].includes(event.state)) return null;
-	const message = event.message;
-	const messageStopReason = isRecord(message) ? readNonemptyString(message.stopReason) : null;
-	const stopReason = readNonemptyString(event.stopReason) ?? messageStopReason;
-	const errorKind = readNonemptyString(event.errorKind);
+	const message = event.state === "delta" ? mergeChatStreamMessage(projection.runs[runId]?.message, event) : event.message;
+	const messageStopReason = isRecord(message) ? readSessionProjectionString(message.stopReason) : null;
+	const stopReason = readSessionProjectionString(event.stopReason) ?? messageStopReason;
+	const errorKind = readSessionProjectionString(event.errorKind);
 	const base = {
 		runId,
 		seq: typeof event.seq === "number" ? event.seq : void 0,
@@ -1861,16 +1934,67 @@ function reduceSessionProjection(state, event) {
 	}
 }
 //#endregion
-//#region packages/gateway-client/src/session-subscriptions.ts
-function sessionSubscriptionParams(key, agentId) {
+//#region packages/normalization-core/src/result.ts
+/** Create a successful {@link Result}. */
+function ok(value) {
 	return {
-		key: key.trim(),
-		...agentId ? { agentId } : {}
+		ok: true,
+		value
 	};
 }
+/** Create a failed {@link Result}. */
+function err(error) {
+	return {
+		ok: false,
+		error
+	};
+}
+//#endregion
+//#region packages/normalization-core/src/agent-id.ts
+const VALID_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+const INVALID_CHARS_RE = /[^a-z0-9_-]+/g;
+const LEADING_DASH_RE = /^-+/;
+const TRAILING_DASH_RE = /-+$/;
+/** Normalizes an explicitly supplied agent id without falling back to the default agent. */
+function normalizeAgentIdStrict(value) {
+	const trimmed = (value ?? "").trim();
+	const normalized = trimmed.toLowerCase();
+	if (VALID_ID_RE.test(trimmed)) return ok(normalized);
+	const agentId = normalized.replace(INVALID_CHARS_RE, "-").replace(LEADING_DASH_RE, "").replace(TRAILING_DASH_RE, "").slice(0, 64);
+	return agentId ? ok(agentId) : err("unrepresentable");
+}
+//#endregion
+//#region packages/normalization-core/src/uuid.ts
+let warnedWeakCrypto = false;
+function warnWeakCryptoOnce() {
+	if (warnedWeakCrypto) return;
+	warnedWeakCrypto = true;
+	console.warn("[uuid] crypto API missing; refusing insecure UUID generation");
+}
+function generateUUID(cryptoLike = globalThis.crypto) {
+	if (cryptoLike && typeof cryptoLike.randomUUID === "function") return cryptoLike.randomUUID();
+	if (cryptoLike && typeof cryptoLike.getRandomValues === "function") {
+		const bytes = /* @__PURE__ */ new Uint8Array(16);
+		cryptoLike.getRandomValues(bytes);
+		const view = new DataView(bytes.buffer);
+		view.setUint8(6, view.getUint8(6) & 15 | 64);
+		view.setUint8(8, view.getUint8(8) & 63 | 128);
+		const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+		return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+	}
+	warnWeakCryptoOnce();
+	throw new Error("Web Crypto is required for UUID generation");
+}
+//#endregion
+//#region packages/gateway-client/src/session-subscriptions.ts
+function normalizedAgentScope(agentId) {
+	if (!agentId) return null;
+	const normalized = normalizeAgentIdStrict(agentId);
+	return normalized.ok ? normalized.value : agentId;
+}
 /**
-* One Gateway connection owns one targeted observer per canonical session.
-* Approval delivery is an upgrade of that observer, never a second observer.
+* Shared leases retain one wire observer ID. The Gateway combines independently
+* addressed observers; approval delivery upgrades the same owner.
 */
 var GatewaySessionMessageSubscriptionCoordinator = class {
 	#client;
@@ -1892,17 +2016,24 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 		const normalizedKey = key.trim();
 		if (!normalizedKey) throw new Error("Session message subscription requires a session key");
 		const agentId = options.agentId?.trim() || null;
+		const scopeAgentId = normalizedAgentScope(agentId);
+		const narration = options.mode === "narration";
+		const includeApprovals = options.includeApprovals === true;
 		let entry;
+		let created = false;
 		while (true) {
 			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))));
+			const existing = [...this.#entries].find((candidate) => {
+				return candidate.scopeAgentId === scopeAgentId && ([...candidate.requestedKeys].some((requestedKey) => this.#areKeysEquivalent(requestedKey, normalizedKey)) || candidate.key !== "global" && this.#areKeysEquivalent(candidate.key, normalizedKey));
+			});
 			if (!existing) {
-				const provisional = [...this.#entries].find((candidate) => candidate.agentId === agentId && !candidate.canonicalSettled && this.#couldShareCanonicalIdentity(candidate.key, normalizedKey));
+				const provisional = [...this.#entries].find((candidate) => candidate.scopeAgentId === scopeAgentId && !candidate.canonicalSettled && this.#couldShareCanonicalIdentity(candidate.key, normalizedKey));
 				if (provisional) {
 					await (provisional.plainFallback ?? provisional.ready).catch(() => void 0);
 					continue;
 				}
-				entry = this.#createEntry(normalizedKey, agentId, options.includeApprovals === true);
+				entry = this.#createEntry(normalizedKey, agentId);
+				created = true;
 				break;
 			}
 			if (!existing.release) {
@@ -1913,13 +2044,31 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 			await existing.release.catch(() => void 0);
 		}
 		entry.pendingOwners += 1;
+		if (!narration) entry.pendingFullOwners += 1;
 		try {
-			const result = await this.#acquireCapability(entry, options.includeApprovals === true);
+			if (created) {
+				entry.ready = this.#requestSubscribe(entry, includeApprovals);
+				if (includeApprovals) entry.ready = this.#trackApprovalRequest(entry, entry.ready);
+				entry.ready.catch(() => void 0);
+			}
+			if (entry.refreshRequired) {
+				entry.refreshRequired = false;
+				entry.plainFallback = null;
+				entry.approvalRequest = null;
+				const retainedApprovals = [...entry.handles].some((handle) => handle.includeApprovals);
+				entry.ready = this.#requestSubscribe(entry, retainedApprovals).catch((error) => {
+					entry.refreshRequired = true;
+					throw error;
+				});
+			}
+			const result = await this.#acquireCapability(entry, includeApprovals);
+			if (!narration && entry.mode === "narration") await this.#requestSubscribe(entry, false, "full");
 			if (this.#retired) throw new Error("Session message subscription completed on a replaced Gateway connection");
 			const subscription = {
 				key: result.key,
 				agentId,
-				...options.includeApprovals === true ? {
+				...narration ? { mode: "narration" } : {},
+				...includeApprovals ? {
 					includeApprovals: true,
 					...result.approvalReplay !== void 0 ? { approvalReplay: result.approvalReplay } : {}
 				} : {}
@@ -1932,6 +2081,7 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 			return subscription;
 		} finally {
 			entry.pendingOwners -= 1;
+			if (!narration) entry.pendingFullOwners -= 1;
 			if (entry.pendingOwners === 0 && entry.handles.size === 0 && !entry.release) this.#entries.delete(entry);
 		}
 	}
@@ -1939,26 +2089,34 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 		const owner = sessionMessageSubscriptionOwners.get(subscription);
 		if (!owner || owner.coordinator !== this) return Promise.resolve();
 		const { entry } = owner;
-		if (this.#retired || entry.handles.size > 1) {
+		if (entry.release) return entry.releasing === subscription ? entry.release : entry.release.catch(() => void 0).then(() => this.release(subscription));
+		const releasesLastFullOwner = subscription.mode !== "narration" && [...entry.handles].every((handle) => handle === subscription || handle.mode === "narration");
+		if (this.#retired || entry.handles.size > 1 && !releasesLastFullOwner) {
 			this.#finishRelease(subscription, owner);
 			return Promise.resolve();
 		}
-		if (entry.release) return entry.release;
 		if (entry.pendingOwners > 0) {
-			const pending = [entry.ready, ...entry.approvalRequest ? [entry.approvalRequest] : []];
-			const tracked = Promise.allSettled(pending).then(() => {
+			const tracked = Promise.allSettled([
+				entry.ready,
+				entry.approvalRequest,
+				entry.wireRequest
+			]).then(() => {
 				if (entry.release === tracked) entry.release = null;
 				return this.release(subscription);
 			});
 			entry.release = tracked;
+			entry.releasing = subscription;
 			return tracked;
 		}
-		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(() => {
+		const removeEntry = entry.handles.size === 1;
+		const tracked = (removeEntry ? this.#requestMessages(entry).catch((error) => {
+			if (error instanceof GatewayProtocolRequestTimeoutError && error.requestSent) entry.refreshRequired = true;
+			throw error;
+		}) : this.#requestSubscribe(entry, false, "narration")).then(() => this.#finishRelease(subscription, owner, removeEntry)).finally(() => {
 			if (entry.release === tracked) entry.release = null;
 		});
 		entry.release = tracked;
+		entry.releasing = subscription;
 		return tracked;
 	}
 	/** A reconnect retires leases without touching the next connection's observers. */
@@ -1970,22 +2128,26 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 		}
 		this.#entries.clear();
 	}
-	#createEntry(key, agentId, includeApprovals) {
+	#createEntry(key, agentId) {
 		const entry = {
+			subscriptionId: generateUUID(),
 			key,
 			requestedKeys: /* @__PURE__ */ new Set([key]),
 			agentId,
+			scopeAgentId: normalizedAgentScope(agentId),
+			ownerAgentId: null,
 			ready: Promise.resolve({ key }),
 			approvalRequest: null,
 			plainFallback: null,
+			wireRequest: null,
+			includeApprovals: false,
 			canonicalSettled: false,
+			refreshRequired: false,
 			handles: /* @__PURE__ */ new Set(),
 			pendingOwners: 0,
+			pendingFullOwners: 0,
 			release: null
 		};
-		entry.ready = this.#requestSubscribe(entry, includeApprovals);
-		if (includeApprovals) entry.ready = this.#trackApprovalRequest(entry, entry.ready);
-		entry.ready.catch(() => void 0);
 		this.#entries.add(entry);
 		return entry;
 	}
@@ -2016,19 +2178,43 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 		entry.approvalRequest = tracked;
 		return tracked;
 	}
-	async #requestSubscribe(entry, includeApprovals) {
-		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) => {
+	#requestSubscribe(entry, includeApprovals, mode) {
+		const send = () => this.#sendSubscribe(entry, includeApprovals, mode);
+		const tracked = (entry.wireRequest ? entry.wireRequest.then(send, send) : send()).finally(() => {
+			if (entry.wireRequest === tracked) entry.wireRequest = null;
+		});
+		entry.wireRequest = tracked;
+		return tracked;
+	}
+	#requestMessages(entry, subscription) {
+		const agentId = entry.key === "global" ? entry.ownerAgentId ?? entry.agentId : entry.agentId;
+		return this.#client.request(subscription ? "sessions.messages.subscribe" : "sessions.messages.unsubscribe", {
+			subscriptionId: entry.subscriptionId,
+			key: entry.key,
+			...agentId ? { agentId } : {},
+			...subscription?.mode ? { mode: subscription.mode } : {},
+			...subscription?.includeApprovals ? { includeApprovals: true } : {}
+		}, { timeoutMs: DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS });
+	}
+	async #sendSubscribe(entry, requestedApprovals, requestedMode) {
+		if (this.#retired) throw new Error("Session message subscription belongs to a replaced Gateway connection");
+		if (requestedMode === "full" && entry.mode !== "narration") return { key: entry.key };
+		const includeApprovals = requestedApprovals || requestedMode !== void 0 && entry.includeApprovals;
+		const mode = requestedMode === "narration" || requestedMode !== "full" && entry.pendingFullOwners === 0 && [...entry.handles].every((handle) => handle.mode === "narration") ? "narration" : void 0;
+		const result = await this.#requestMessages(entry, {
+			mode,
+			includeApprovals
+		}).catch(async (error) => {
 			if (!(error instanceof GatewayProtocolRequestTimeoutError) || !error.requestSent || this.#retired) throw error;
 			try {
 				const retainedApprovals = [...entry.handles].some((handle) => handle.includeApprovals);
-				await this.#client.request(entry.handles.size > 0 ? "sessions.messages.subscribe" : "sessions.messages.unsubscribe", retainedApprovals ? {
-					...params,
-					includeApprovals: true
-				} : params, { timeoutMs: DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS });
+				const retainedMode = entry.handles.size > 0 && [...entry.handles].every((handle) => handle.mode === "narration") ? "narration" : void 0;
+				await this.#requestMessages(entry, entry.handles.size > 0 ? {
+					mode: retainedMode,
+					includeApprovals: retainedApprovals
+				} : void 0);
+				entry.mode = retainedMode;
+				entry.includeApprovals = retainedApprovals;
 			} catch (recoveryError) {
 				if (!this.#retired) throw new AggregateError([error, recoveryError], "session message subscription recovery failed", { cause: recoveryError });
 			}
@@ -2038,6 +2224,10 @@ var GatewaySessionMessageSubscriptionCoordinator = class {
 		const responseKey = response && "key" in response ? response.key : void 0;
 		entry.key = typeof responseKey === "string" && responseKey.trim() ? responseKey.trim() : entry.key;
 		entry.canonicalSettled = true;
+		const responseAgentId = response && "agentId" in response ? response.agentId : void 0;
+		entry.ownerAgentId = normalizedAgentScope((typeof responseAgentId === "string" ? responseAgentId : null) ?? entry.ownerAgentId ?? entry.scopeAgentId);
+		entry.mode = mode;
+		entry.includeApprovals = includeApprovals;
 		return {
 			key: entry.key,
 			...response && "approvalReplay" in response ? { approvalReplay: response.approvalReplay } : {}
@@ -2075,4 +2265,4 @@ function releaseGatewaySessionMessageSubscription(subscription) {
 	return sessionMessageSubscriptionOwners.get(subscription)?.coordinator.release(subscription) ?? Promise.resolve();
 }
 //#endregion
-export { resolveGatewayConnectScopes as A, GatewayProtocolRequestTimeoutError as C, gatewayOriginScope as D, gatewayCredentialScope as E, normalizeDeviceMetadataForAuth as F, shouldRetryGatewayWithDeviceToken as M, buildDeviceAuthPayload as N, GatewayBrowserDeviceAuthLifecycle as O, buildDeviceAuthPayloadV3 as P, GatewayProtocolRequestError as S, resolveModelCatalogConnect as T, readSessionMessageIdentity as _, createSessionProjection as a, shouldPauseGatewayReconnect as b, reduceSessionProjection as c, readSessionProjectionFinalMessageIdentity as d, isSessionProjectionErrorMessage as f, readAssistantStreamSegmentIdentity as g, normalizeSessionProjectionRunId as h, resetGatewaySessionMessageSubscriptionCoordinator as i, selectGatewayConnectAuth as j, buildGatewayConnectAuth as k, reduceSessionProjectionRunEvent as l, isLocallyOptimisticSessionMessage as m, getGatewaySessionMessageSubscriptionCoordinator as n, projectLiveSessionMessage as o, projectSessionTerminalReplyMessage as p, releaseGatewaySessionMessageSubscription as r, reconcileSessionProjectionSnapshot as s, GatewaySessionMessageSubscriptionCoordinator as t, hasSessionProjectionAcceptedFinal as u, readSessionMessageSequence as v, isGatewayProtocolResponseError as w, GatewayProtocolClient as x, isRecord as y };
+export { selectGatewayConnectAuth as A, isGatewayProtocolResponseError as C, GatewayBrowserDeviceAuthLifecycle as D, gatewayOriginScope as E, isRecord as F, buildDeviceAuthPayload as I, buildDeviceAuthPayloadV3 as L, mergeChatStreamMessage as M, asNullableRecord as N, buildGatewayConnectAuth as O, asRecord as P, normalizeDeviceMetadataForAuth as R, GatewayProtocolRequestTimeoutError as S, gatewayCredentialScope as T, readSessionMessageIdentity as _, createSessionProjection as a, GatewayProtocolClient as b, reduceSessionProjection as c, readSessionProjectionFinalMessageIdentity as d, isSessionProjectionErrorMessage as f, readAssistantStreamSegmentIdentity as g, normalizeSessionProjectionRunId as h, resetGatewaySessionMessageSubscriptionCoordinator as i, shouldRetryGatewayWithDeviceToken as j, resolveGatewayConnectScopes as k, reduceSessionProjectionRunEvent as l, isLocallyOptimisticSessionMessage as m, getGatewaySessionMessageSubscriptionCoordinator as n, projectLiveSessionMessage as o, projectSessionTerminalReplyMessage as p, releaseGatewaySessionMessageSubscription as r, reconcileSessionProjectionSnapshot as s, GatewaySessionMessageSubscriptionCoordinator as t, hasSessionProjectionAcceptedFinal as u, readSessionMessageSequence as v, resolveModelCatalogConnect as w, GatewayProtocolRequestError as x, shouldPauseGatewayReconnect as y };