@oxvo/ai-live-assist 7.3.4 → 7.4.23

package/lib/control.js

@@ -1,20 +1,67 @@
 const INVALID_MESSAGE_CLOSE_CODE = 4003;
 const PROTOCOL_VIOLATION_CLOSE_CODE = 4008;
+const SERVER_SEQUENCE_GAP_CLOSE_CODE = 4009;
+const HANDLER_FAILURE_CLOSE_CODE = 4010;
+const HANDLER_TIMEOUT_MS = 15000;
+const MAX_PENDING_HANDLER_MESSAGES = 64;
+const MAX_PENDING_STATEFUL_OPERATIONS = 64;
+const MAX_SETTLED_OPERATION_HISTORY = 100;
+const CLIENT_MESSAGE_ID_PATTERN = /^[A-Za-z0-9_.:-]{8,128}$/;
+const STATEFUL_CONTROL_TYPES = new Set([
+    "text.message",
+    "confirmation.result",
+    "consent.update",
+    "consent.reset.ack",
+    "session.mode",
+    "session.mode.upgrade",
+    "session.mode.upgrade.cancel",
+    "context.navigation",
+    "action.execution.begin",
+    "action.result",
+    "handoff.open.result",
+    "handoff.connected.ack",
+    "handoff.binding.terminal.ack",
+    "handoff_context.received",
+    "handoff_context.result",
+    "page_assistance.result",
+    "page_assistance.revoke",
+    "visual_context.result",
+    "presentation.result",
+    "session.pause",
+    "session.resume",
+    "experience.end",
+    "session.end",
+]);
+const outcomeKey = (messageId, sequence) => `${messageId}\u0000${sequence}`;
 export class ControlChannel {
-    constructor(result, tabId, clientVersion, onDisconnect, initialClientSequence = 0, onClientSequence = () => undefined) {
+    constructor(result, tabId, clientVersion, onDisconnect, initialClientSequence = 0, onClientSequence = () => undefined, onUnsafeDisconnect = () => undefined) {
         this.result = result;
         this.tabId = tabId;
         this.clientVersion = clientVersion;
         this.onDisconnect = onDisconnect;
         this.onClientSequence = onClientSequence;
+        this.onUnsafeDisconnect = onUnsafeDisconnect;
         this.socket = null;
         this.serverSequence = 0;
+        this.serverBaselineEstablished = false;
+        this.sequenceGapDetected = false;
+        this.recoveryDisconnectNotified = false;
         this.fencingToken = 0;
         this.heartbeat = null;
         this.handlers = new Set();
+        this.ingressHandlers = new Set();
         this.intentionallyClosed = false;
-        this.pendingAcks = new Map();
-        this.recentAcks = new Set();
+        this.pendingOutcomes = new Map();
+        this.recentOutcomes = new Map();
+        this.outboundOperations = new Map();
+        this.latestOutboundSequence = new Map();
+        this.unsettledStatefulOperations = new Set();
+        this.socketGeneration = 0;
+        this.handlerTail = null;
+        this.pendingHandlerMessages = 0;
+        this.pendingConnection = null;
+        this.helloOperation = null;
+        this.fencedAuthorityConfirmed = false;
         this.clientSequence =
             Number.isSafeInteger(initialClientSequence) && initialClientSequence >= 0
                 ? initialClientSequence
@@ -23,95 +70,283 @@ export class ControlChannel {
     get leaseToken() {
         return this.fencingToken;
     }
+    get lastClientSequence() {
+        return this.clientSequence;
+    }
     get isOpen() {
         return this.socket?.readyState === WebSocket.OPEN;
     }
+    get connectionHelloOperation() {
+        return this.helloOperation ? { ...this.helloOperation } : null;
+    }
+    get hasFencedAuthority() {
+        return (this.isOpen && this.fencingToken > 0 && this.fencedAuthorityConfirmed);
+    }
     setFencingToken(value) {
         if (!Number.isSafeInteger(value) || value < 1) {
-            throw new Error('Invalid AI Guide fencing token.');
+            throw new Error("Invalid AI Guide fencing token.");
         }
+        this.fencedAuthorityConfirmed = false;
         this.fencingToken = value;
     }
     subscribe(handler) {
         this.handlers.add(handler);
         return () => this.handlers.delete(handler);
     }
+    subscribeIngress(handler) {
+        this.ingressHandlers.add(handler);
+        return () => this.ingressHandlers.delete(handler);
+    }
     connect(signal, resume) {
+        if (signal.aborted) {
+            return Promise.reject(new DOMException("The operation was aborted.", "AbortError"));
+        }
         return new Promise((resolve, reject) => {
             const url = new URL(this.result.controlUrl);
-            url.searchParams.set('session', this.result.sessionId);
+            url.searchParams.set("session", this.result.sessionId);
             const socket = new WebSocket(url, [
                 `oxvo-ai-live-assist-v${this.result.protocolVersion}`,
                 `oxvo-auth.${this.result.controlCredential}`,
             ]);
+            this.retireSocket("replaced");
+            const generation = ++this.socketGeneration;
             this.socket = socket;
             this.intentionallyClosed = false;
+            this.serverSequence = 0;
+            this.serverBaselineEstablished = false;
+            this.sequenceGapDetected = false;
+            this.recoveryDisconnectNotified = false;
+            this.helloOperation = null;
+            this.fencedAuthorityConfirmed = false;
+            this.handlerTail = null;
+            this.pendingHandlerMessages = 0;
             const abort = () => {
-                socket.close(1000, 'cancelled');
-                reject(new DOMException('The operation was aborted.', 'AbortError'));
+                if (!this.isCurrentSocket(socket, generation))
+                    return;
+                this.rejectPendingConnection(socket, generation, new DOMException("The operation was aborted.", "AbortError"));
+                socket.close(1000, "cancelled");
+            };
+            this.pendingConnection = {
+                socket,
+                generation,
+                signal,
+                abort,
+                reject,
             };
-            signal.addEventListener('abort', abort, { once: true });
-            socket.addEventListener('open', () => {
-                signal.removeEventListener('abort', abort);
-                this.send('hello', {
-                    protocolMin: 1,
-                    protocolMax: this.result.protocolVersion,
-                    clientVersion: this.clientVersion,
-                    resume,
-                });
+            signal.addEventListener("abort", abort, { once: true });
+            socket.addEventListener("open", () => {
+                if (!this.isCurrentSocket(socket, generation))
+                    return;
+                if (signal.aborted) {
+                    abort();
+                    return;
+                }
+                this.clearPendingConnection(socket, generation);
+                try {
+                    const messageId = this.send("hello", {
+                        protocolMin: 1,
+                        protocolMax: this.result.protocolVersion,
+                        clientVersion: this.clientVersion,
+                        resume,
+                    });
+                    this.helloOperation = {
+                        messageId,
+                        sequence: this.clientSequence,
+                        type: "hello",
+                    };
+                }
+                catch (error) {
+                    socket.close(1011, "hello failed");
+                    reject(error);
+                    return;
+                }
                 resolve();
             }, { once: true });
-            socket.addEventListener('message', (event) => {
-                void this.handleMessage(event.data);
+            socket.addEventListener("message", (event) => {
+                if (!this.isCurrentSocket(socket, generation))
+                    return;
+                this.handleMessage(event.data, socket, generation);
             });
-            socket.addEventListener('error', () => {
-                signal.removeEventListener('abort', abort);
+            socket.addEventListener("error", () => {
+                if (!this.isCurrentSocket(socket, generation))
+                    return;
                 if (socket.readyState !== WebSocket.OPEN) {
-                    reject(new Error('The AI Guide control channel could not connect.'));
+                    this.rejectPendingConnection(socket, generation, new Error("The AI Guide control channel could not connect."));
                 }
             }, { once: true });
-            socket.addEventListener('close', () => {
+            socket.addEventListener("close", () => {
+                if (!this.isCurrentSocket(socket, generation))
+                    return;
+                const wasIntentionallyClosed = this.intentionallyClosed;
+                this.socket = null;
+                this.socketGeneration += 1;
                 this.stopHeartbeat();
-                if (!this.intentionallyClosed && !signal.aborted)
-                    this.onDisconnect();
+                this.invalidatePendingOutcomes();
+                this.recentOutcomes.clear();
+                this.outboundOperations.clear();
+                this.latestOutboundSequence.clear();
+                this.helloOperation = null;
+                this.fencedAuthorityConfirmed = false;
+                this.handlerTail = null;
+                this.pendingHandlerMessages = 0;
+                this.rejectPendingConnection(socket, generation, new Error("The AI Guide control channel closed before connecting."));
+                if (!wasIntentionallyClosed && !signal.aborted) {
+                    this.notifyUnsafeDisconnect();
+                }
             });
         });
     }
-    send(type, payload) {
+    send(type, payload, stableMessageId) {
         if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
-            throw new Error('The AI Guide control channel is not connected.');
+            throw new Error("The AI Guide control channel is not connected.");
+        }
+        const messageId = stableMessageId ?? `msg_${crypto.randomUUID()}`;
+        if (!CLIENT_MESSAGE_ID_PATTERN.test(messageId)) {
+            throw new Error("Invalid AI Guide control message ID.");
+        }
+        if (STATEFUL_CONTROL_TYPES.has(type) &&
+            this.unsettledStatefulOperations.size >= MAX_PENDING_STATEFUL_OPERATIONS) {
+            throw new Error("Too many AI Guide control operations are pending.");
+        }
+        this.clientSequence += 1;
+        const operation = {
+            messageId,
+            sequence: this.clientSequence,
+            type,
+        };
+        this.sendReserved(operation, payload);
+        this.onClientSequence(this.clientSequence);
+        return messageId;
+    }
+    reserveOperationIdentity(type, stableMessageId) {
+        const messageId = stableMessageId ?? `msg_${crypto.randomUUID()}`;
+        if (!CLIENT_MESSAGE_ID_PATTERN.test(messageId)) {
+            throw new Error("Invalid AI Guide control message ID.");
+        }
+        if (!type || type.length > 128) {
+            throw new Error("Invalid AI Guide control message type.");
         }
-        const id = `msg_${crypto.randomUUID()}`;
         this.clientSequence += 1;
+        this.onClientSequence(this.clientSequence);
+        return {
+            messageId,
+            sequence: this.clientSequence,
+            type,
+        };
+    }
+    sendReserved(operation, payload) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            throw new Error("The AI Guide control channel is not connected.");
+        }
+        if (!CLIENT_MESSAGE_ID_PATTERN.test(operation.messageId) ||
+            !Number.isSafeInteger(operation.sequence) ||
+            operation.sequence < 1 ||
+            operation.sequence !== this.clientSequence ||
+            !operation.type ||
+            operation.type.length > 128) {
+            throw new Error("Invalid AI Guide reserved control operation.");
+        }
+        if (STATEFUL_CONTROL_TYPES.has(operation.type) &&
+            this.unsettledStatefulOperations.size >= MAX_PENDING_STATEFUL_OPERATIONS) {
+            throw new Error("Too many AI Guide control operations are pending.");
+        }
         this.socket.send(JSON.stringify({
             v: this.result.protocolVersion,
-            id,
-            type,
+            id: operation.messageId,
+            type: operation.type,
             sessionId: this.result.sessionId,
             tabId: this.tabId,
-            sequence: this.clientSequence,
+            sequence: operation.sequence,
             fencingToken: this.fencingToken,
             sentAt: new Date().toISOString(),
             payload,
         }));
-        this.onClientSequence(this.clientSequence);
-        return id;
+        const key = outcomeKey(operation.messageId, operation.sequence);
+        this.outboundOperations.set(key, operation);
+        this.latestOutboundSequence.set(operation.messageId, operation.sequence);
+        if (STATEFUL_CONTROL_TYPES.has(operation.type)) {
+            this.unsettledStatefulOperations.add(key);
+        }
+        this.pruneSettledOperationHistory();
+        return operation.messageId;
     }
-    waitForAck(messageId, timeoutMs = 2500) {
-        if (this.recentAcks.delete(messageId))
-            return Promise.resolve(true);
+    outboundOperation(messageId, sequence = this.latestOutboundSequence.get(messageId) ?? 0) {
+        return this.outboundOperations.get(outcomeKey(messageId, sequence)) ?? null;
+    }
+    waitForOutcome(messageId, timeoutMs = 2500, expectedSequence = this.latestOutboundSequence.get(messageId) ?? 0) {
+        if (!CLIENT_MESSAGE_ID_PATTERN.test(messageId) ||
+            !Number.isSafeInteger(expectedSequence) ||
+            expectedSequence < 1) {
+            return Promise.resolve({
+                status: "invalidated",
+                messageId,
+                sequence: Number.isSafeInteger(expectedSequence) && expectedSequence >= 0
+                    ? expectedSequence
+                    : 0,
+            });
+        }
+        const key = outcomeKey(messageId, expectedSequence);
+        const recent = this.recentOutcomes.get(key);
+        if (recent)
+            return Promise.resolve(recent);
         return new Promise((resolve) => {
-            const timeout = setTimeout(() => {
-                this.pendingAcks.delete(messageId);
-                resolve(false);
-            }, Math.max(250, Math.min(10000, timeoutMs)));
-            this.pendingAcks.set(messageId, (acknowledged) => {
+            let settled = false;
+            let timeout;
+            let pendingOutcome;
+            const settle = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
                 clearTimeout(timeout);
-                this.pendingAcks.delete(messageId);
-                resolve(acknowledged);
-            });
+                const pending = this.pendingOutcomes.get(key);
+                pending?.delete(pendingOutcome);
+                if (pending?.size === 0)
+                    this.pendingOutcomes.delete(key);
+                resolve(outcome);
+            };
+            pendingOutcome = { settle };
+            const pending = this.pendingOutcomes.get(key) ?? new Set();
+            pending.add(pendingOutcome);
+            this.pendingOutcomes.set(key, pending);
+            timeout = setTimeout(() => settle({
+                status: "timeout",
+                messageId,
+                sequence: expectedSequence,
+            }), Math.max(250, Math.min(10000, timeoutMs)));
         });
     }
+    waitForAck(messageId, timeoutMs = 2500) {
+        return this.waitForOutcome(messageId, timeoutMs).then((outcome) => outcome.status === "ack");
+    }
+    waitForHelloOutcome(timeoutMs = 5000) {
+        const hello = this.connectionHelloOperation;
+        if (!hello) {
+            return Promise.resolve({
+                status: "invalidated",
+                messageId: "",
+                sequence: 0,
+            });
+        }
+        return this.waitForOutcome(hello.messageId, timeoutMs, hello.sequence);
+    }
+    async proveFencedAuthority(timeoutMs = 5000) {
+        const socket = this.socket;
+        const generation = this.socketGeneration;
+        const fencingToken = this.fencingToken;
+        this.fencedAuthorityConfirmed = false;
+        if (!socket || socket.readyState !== WebSocket.OPEN || fencingToken < 1) {
+            throw new Error("The AI Guide control authority is not connected.");
+        }
+        const messageId = this.sendHeartbeat(0);
+        const sequence = this.clientSequence;
+        const outcome = await this.waitForOutcome(messageId, timeoutMs, sequence);
+        if (outcome.status === "ack" &&
+            this.isCurrentSocket(socket, generation) &&
+            this.fencingToken === fencingToken) {
+            this.fencedAuthorityConfirmed = true;
+        }
+        return outcome;
+    }
     startHeartbeat(seconds) {
         this.stopHeartbeat();
         const interval = Math.max(5, Math.min(30, seconds)) * 1000;
@@ -119,64 +354,352 @@ export class ControlChannel {
             if (!this.isOpen || this.fencingToken < 1)
                 return;
             try {
-                this.send('heartbeat', { lastServerSequence: this.serverSequence });
+                this.sendHeartbeat(this.serverSequence);
             }
             catch {
-                this.onDisconnect();
+                this.notifyUnsafeDisconnect();
             }
         }, interval);
     }
-    close(code = 1000, reason = 'closed') {
+    close(code = 1000, reason = "closed") {
         this.intentionallyClosed = true;
         this.stopHeartbeat();
-        this.socket?.close(code, reason.slice(0, 120));
+        const socket = this.socket;
+        const generation = this.socketGeneration;
         this.socket = null;
+        this.socketGeneration += 1;
+        this.handlerTail = null;
+        this.pendingHandlerMessages = 0;
+        this.rejectPendingConnection(socket, generation, new DOMException("The operation was aborted.", "AbortError"));
+        socket?.close(code, reason.slice(0, 120));
         this.handlers.clear();
-        for (const resolve of this.pendingAcks.values())
-            resolve(false);
-        this.pendingAcks.clear();
-        this.recentAcks.clear();
+        this.ingressHandlers.clear();
+        this.invalidatePendingOutcomes();
+        this.recentOutcomes.clear();
+        this.outboundOperations.clear();
+        this.latestOutboundSequence.clear();
+        this.helloOperation = null;
+        this.fencedAuthorityConfirmed = false;
+        this.unsettledStatefulOperations.clear();
     }
-    async handleMessage(raw) {
-        if (typeof raw !== 'string' || raw.length > 131072)
+    handleMessage(raw, socket = this.socket, generation = this.socketGeneration) {
+        if (this.sequenceGapDetected)
+            return;
+        if (typeof raw !== "string" || raw.length > 131072)
             return;
         let message;
         try {
             message = JSON.parse(raw);
         }
         catch {
-            this.close(INVALID_MESSAGE_CLOSE_CODE, 'invalid message');
+            this.close(INVALID_MESSAGE_CLOSE_CODE, "invalid message");
             return;
         }
-        const directProtocolError = message.type === 'error' && message.sequence === 0;
+        const directProtocolError = message.type === "error" && message.sequence === 0;
+        const orderedSequence = directProtocolError ||
+            (!this.serverBaselineEstablished
+                ? message.sequence > 0
+                : message.sequence === this.serverSequence + 1);
         if (message.v !== this.result.protocolVersion ||
             message.sessionId !== this.result.sessionId ||
             !Number.isSafeInteger(message.sequence) ||
-            (!directProtocolError && message.sequence <= this.serverSequence) ||
-            typeof message.type !== 'string' ||
+            (!directProtocolError && message.sequence < 1) ||
+            typeof message.type !== "string" ||
             !message.payload ||
-            typeof message.payload !== 'object') {
-            this.close(PROTOCOL_VIOLATION_CLOSE_CODE, 'protocol violation');
+            typeof message.payload !== "object") {
+            this.close(PROTOCOL_VIOLATION_CLOSE_CODE, "protocol violation");
+            return;
+        }
+        if (!orderedSequence) {
+            this.recoverFromSequenceGap(socket, generation);
             return;
         }
-        if (!directProtocolError)
+        if (!directProtocolError) {
             this.serverSequence = message.sequence;
-        if (message.type === 'ack' && typeof message.payload.messageId === 'string') {
+            this.serverBaselineEstablished = true;
+        }
+        if (message.type === "ack" &&
+            typeof message.payload.messageId === "string") {
             const messageId = message.payload.messageId;
-            const pending = this.pendingAcks.get(messageId);
+            const latestSequence = this.latestOutboundSequence.get(messageId) ?? 0;
+            const sequence = Number.isSafeInteger(message.payload.sequence) &&
+                message.payload.sequence >= 1
+                ? message.payload.sequence
+                : latestSequence;
+            if (CLIENT_MESSAGE_ID_PATTERN.test(messageId) && sequence >= 1) {
+                this.settleOutcome({ status: "ack", messageId, sequence });
+            }
+        }
+        if (message.type === "error" &&
+            typeof message.payload.messageId === "string" &&
+            CLIENT_MESSAGE_ID_PATTERN.test(message.payload.messageId) &&
+            Number.isSafeInteger(message.payload.sequence) &&
+            message.payload.sequence >= 1) {
+            const messageId = message.payload.messageId;
+            this.settleOutcome({
+                status: "explicit_error",
+                messageId,
+                sequence: message.payload.sequence,
+                code: typeof message.payload.code === "string"
+                    ? message.payload.code.slice(0, 64)
+                    : "CONTROL_OPERATION_REJECTED",
+                message: typeof message.payload.message === "string"
+                    ? message.payload.message.slice(0, 500)
+                    : "The control operation was rejected.",
+                retryable: message.payload.retryable === true,
+                retryAfterMs: Number.isSafeInteger(message.payload.retryAfterMs) &&
+                    message.payload.retryAfterMs >= 0
+                    ? message.payload.retryAfterMs
+                    : null,
+            });
+        }
+        if (!this.dispatchIngressHandlers(message, socket, generation))
+            return;
+        return this.enqueueHandlers(message, socket, generation);
+    }
+    recoverFromSequenceGap(socket, generation) {
+        if (this.sequenceGapDetected)
+            return;
+        this.sequenceGapDetected = true;
+        this.failCurrentGeneration(socket, generation, SERVER_SEQUENCE_GAP_CLOSE_CODE, "server sequence gap");
+    }
+    notifyUnsafeDisconnect() {
+        if (this.recoveryDisconnectNotified)
+            return;
+        this.recoveryDisconnectNotified = true;
+        try {
+            this.onUnsafeDisconnect();
+        }
+        finally {
+            this.onDisconnect();
+        }
+    }
+    enqueueHandlers(message, socket, generation) {
+        const isCurrent = () => this.isMessageSourceCurrent(socket, generation);
+        if (!isCurrent())
+            return Promise.resolve();
+        if (this.pendingHandlerMessages >= MAX_PENDING_HANDLER_MESSAGES) {
+            this.handleHandlerFailure(socket, generation, isCurrent);
+            return Promise.resolve();
+        }
+        this.pendingHandlerMessages += 1;
+        const handlers = [...this.handlers];
+        const dispatch = () => this.dispatchHandlers(message, handlers, isCurrent);
+        let pending;
+        try {
+            pending = this.handlerTail
+                ? this.handlerTail.then(dispatch, dispatch)
+                : dispatch();
+        }
+        catch {
+            if (isCurrent())
+                this.pendingHandlerMessages -= 1;
+            this.handleHandlerFailure(socket, generation, isCurrent);
+            return Promise.resolve();
+        }
+        if (!isCurrent()) {
             if (pending)
-                pending(true);
-            else {
-                this.recentAcks.add(messageId);
-                if (this.recentAcks.size > 100) {
-                    const oldest = this.recentAcks.values().next().value;
-                    if (typeof oldest === 'string')
-                        this.recentAcks.delete(oldest);
+                void Promise.resolve(pending).catch(() => undefined);
+            return Promise.resolve();
+        }
+        if (!pending) {
+            this.pendingHandlerMessages -= 1;
+            return Promise.resolve();
+        }
+        let tracked;
+        tracked = Promise.resolve(pending)
+            .catch(() => this.handleHandlerFailure(socket, generation, isCurrent))
+            .finally(() => {
+            if (!isCurrent())
+                return;
+            this.pendingHandlerMessages = Math.max(0, this.pendingHandlerMessages - 1);
+            if (this.handlerTail === tracked)
+                this.handlerTail = null;
+        });
+        this.handlerTail = tracked;
+        return tracked;
+    }
+    dispatchHandlers(message, handlers, isCurrent, startIndex = 0) {
+        if (!isCurrent())
+            return;
+        for (let index = startIndex; index < handlers.length; index += 1) {
+            const handler = handlers[index];
+            if (!handler || !this.handlers.has(handler))
+                continue;
+            const pending = handler(message, isCurrent);
+            if (pending && typeof pending.then === "function") {
+                return this.withHandlerDeadline(pending).then(() => this.dispatchHandlers(message, handlers, isCurrent, index + 1));
+            }
+            if (!isCurrent())
+                return;
+        }
+    }
+    handleHandlerFailure(socket, generation, isCurrent) {
+        if (!isCurrent())
+            return;
+        this.failCurrentGeneration(socket, generation, HANDLER_FAILURE_CLOSE_CODE, "handler failure");
+    }
+    dispatchIngressHandlers(message, socket, generation) {
+        const isCurrent = () => this.isMessageSourceCurrent(socket, generation);
+        const handlers = [...this.ingressHandlers];
+        try {
+            for (const handler of handlers) {
+                if (!isCurrent())
+                    return false;
+                if (!this.ingressHandlers.has(handler))
+                    continue;
+                const result = handler(message, isCurrent);
+                if (result &&
+                    (typeof result === "object" || typeof result === "function") &&
+                    "then" in result &&
+                    typeof result.then === "function") {
+                    void Promise.resolve(result).catch(() => undefined);
+                    throw new Error("Ingress handlers must complete synchronously.");
                 }
             }
         }
-        for (const handler of this.handlers)
-            await handler(message);
+        catch {
+            this.handleHandlerFailure(socket, generation, isCurrent);
+            return false;
+        }
+        return isCurrent();
+    }
+    failCurrentGeneration(socket, generation, code, reason) {
+        if (!this.isMessageSourceCurrent(socket, generation))
+            return;
+        this.stopHeartbeat();
+        this.invalidatePendingOutcomes();
+        this.recentOutcomes.clear();
+        this.outboundOperations.clear();
+        this.latestOutboundSequence.clear();
+        this.helloOperation = null;
+        this.fencedAuthorityConfirmed = false;
+        this.handlerTail = null;
+        this.pendingHandlerMessages = 0;
+        this.rejectPendingConnection(socket, generation, new Error(`The AI Guide control channel closed: ${reason}.`));
+        this.socket = null;
+        this.socketGeneration += 1;
+        try {
+            socket?.close(code, reason.slice(0, 120));
+        }
+        finally {
+            this.notifyUnsafeDisconnect();
+        }
+    }
+    isMessageSourceCurrent(socket, generation) {
+        return socket === null
+            ? this.socket === null && this.socketGeneration === generation
+            : this.isCurrentSocket(socket, generation);
+    }
+    isCurrentSocket(socket, generation) {
+        return this.socket === socket && this.socketGeneration === generation;
+    }
+    retireSocket(reason) {
+        const socket = this.socket;
+        const generation = this.socketGeneration;
+        if (!socket)
+            return;
+        this.stopHeartbeat();
+        this.socket = null;
+        this.socketGeneration += 1;
+        this.handlerTail = null;
+        this.pendingHandlerMessages = 0;
+        this.rejectPendingConnection(socket, generation, new DOMException("The operation was aborted.", "AbortError"));
+        this.invalidatePendingOutcomes();
+        this.recentOutcomes.clear();
+        this.outboundOperations.clear();
+        this.latestOutboundSequence.clear();
+        this.helloOperation = null;
+        this.fencedAuthorityConfirmed = false;
+        socket.close(1000, reason.slice(0, 120));
+    }
+    sendHeartbeat(lastServerSequence) {
+        return this.send("heartbeat", { lastServerSequence });
+    }
+    withHandlerDeadline(pending) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => reject(new Error("AI Guide control handler timed out.")), HANDLER_TIMEOUT_MS);
+            pending.then(() => {
+                clearTimeout(timeout);
+                resolve();
+            }, (error) => {
+                clearTimeout(timeout);
+                reject(error);
+            });
+        });
+    }
+    clearPendingConnection(socket, generation) {
+        const pending = this.pendingConnection;
+        if (!pending ||
+            pending.socket !== socket ||
+            pending.generation !== generation) {
+            return;
+        }
+        pending.signal.removeEventListener("abort", pending.abort);
+        this.pendingConnection = null;
+    }
+    rejectPendingConnection(socket, generation, reason) {
+        const pending = this.pendingConnection;
+        if (!socket ||
+            !pending ||
+            pending.socket !== socket ||
+            pending.generation !== generation) {
+            return;
+        }
+        this.clearPendingConnection(socket, generation);
+        pending.reject(reason);
+    }
+    settleOutcome(outcome) {
+        const key = outcomeKey(outcome.messageId, outcome.sequence);
+        this.unsettledStatefulOperations.delete(key);
+        this.recentOutcomes.set(key, outcome);
+        if (this.recentOutcomes.size > 100) {
+            const oldest = this.recentOutcomes.keys().next().value;
+            if (typeof oldest === "string")
+                this.recentOutcomes.delete(oldest);
+        }
+        const pending = this.pendingOutcomes.get(key);
+        if (pending) {
+            this.pendingOutcomes.delete(key);
+            for (const value of [...pending])
+                value.settle(outcome);
+        }
+        // Keep the exact operation metadata through synchronous ingress dispatch.
+        // Operation-specific error handling runs after outcome settlement in the
+        // same socket event; pruning here could erase the oldest stateful identity
+        // after a long telemetry burst before that handler can classify it. The
+        // next send performs the normal bounded-history prune.
+    }
+    invalidatePendingOutcomes() {
+        const pending = [...this.pendingOutcomes.entries()];
+        this.pendingOutcomes.clear();
+        for (const [key, listeners] of pending) {
+            const separator = key.lastIndexOf("\u0000");
+            const messageId = key.slice(0, separator);
+            const sequence = Number(key.slice(separator + 1));
+            const outcome = {
+                status: "invalidated",
+                messageId,
+                sequence,
+            };
+            for (const value of [...listeners])
+                value.settle(outcome);
+        }
+        this.unsettledStatefulOperations.clear();
+    }
+    pruneSettledOperationHistory() {
+        const maximum = this.unsettledStatefulOperations.size + MAX_SETTLED_OPERATION_HISTORY;
+        while (this.outboundOperations.size > maximum) {
+            const candidate = [...this.outboundOperations.keys()].find((key) => !this.unsettledStatefulOperations.has(key));
+            if (!candidate)
+                return;
+            const retired = this.outboundOperations.get(candidate);
+            this.outboundOperations.delete(candidate);
+            if (retired &&
+                this.latestOutboundSequence.get(retired.messageId) === retired.sequence) {
+                this.latestOutboundSequence.delete(retired.messageId);
+            }
+        }
     }
     stopHeartbeat() {
         if (this.heartbeat)