@turingfocus/chat-gateway-tfrobot 0.4.2 → 0.6.0

package/dist/socket.js

@@ -17,6 +17,123 @@ const KNOWN_EVENTS = new Set([
 ]);
 const MAX_TIMER_DELAY = 2_147_483_647;
 const RECONNECT_AUTH_TIMEOUT_MS = 10_000;
+const RECONNECT_JOIN_TIMEOUT_MS = 10_000;
+const parseJoinAcknowledgement = (value, reconnect) => {
+    if (value === undefined) {
+        return {
+            accepted: reconnect,
+            recoveryComplete: false,
+            ...(reconnect ? {} : { rejectionCode: "validation" }),
+        };
+    }
+    if (value === null) {
+        return {
+            accepted: false,
+            recoveryComplete: false,
+            rejectionCode: "validation",
+        };
+    }
+    if (value === false) {
+        return {
+            accepted: false,
+            recoveryComplete: false,
+            rejectionCode: "validation",
+        };
+    }
+    if (value === true) {
+        return { accepted: true, recoveryComplete: !reconnect };
+    }
+    if (typeof value !== "object") {
+        return {
+            accepted: false,
+            recoveryComplete: false,
+            rejectionCode: "validation",
+        };
+    }
+    const record = value;
+    const booleanAliases = ["ok", "accepted", "success"];
+    const hasInvalidBooleanAlias = booleanAliases.some((alias) => Object.hasOwn(record, alias) && typeof record[alias] !== "boolean");
+    const statusAliases = ["status", "statusCode", "code"];
+    const hasInvalidStatusAlias = statusAliases.some((alias) => Object.hasOwn(record, alias) && record[alias] === undefined);
+    const statuses = [record["status"], record["statusCode"], record["code"]]
+        .filter((status) => status !== undefined)
+        .map((status) => {
+        const numeric = typeof status === "number"
+            ? status
+            : typeof status === "string" && /^\d{3}$/u.test(status)
+                ? Number(status)
+                : undefined;
+        const normalized = typeof status === "string" ? status.trim().toLowerCase() : undefined;
+        const accepted = (numeric !== undefined && numeric >= 200 && numeric < 300) ||
+            normalized === "ok" ||
+            normalized === "success" ||
+            normalized === "accepted" ||
+            normalized === "joined";
+        const rejected = (numeric !== undefined && numeric >= 400) ||
+            normalized === "error" ||
+            normalized === "failed" ||
+            normalized === "forbidden" ||
+            normalized === "unauthorized" ||
+            normalized === "rejected";
+        return { accepted, normalized, numeric, rejected };
+    });
+    const hasUnknownStatus = statuses.some((status) => !status.accepted && !status.rejected);
+    const explicitlyAccepted = record["ok"] === true ||
+        record["accepted"] === true ||
+        record["success"] === true ||
+        statuses.some((status) => status.accepted);
+    const cursorAliases = ["cursor", "recoveryCursor"];
+    const cursorValues = cursorAliases
+        .filter((alias) => Object.hasOwn(record, alias))
+        .map((alias) => record[alias]);
+    const cursorInvalid = cursorValues.some((cursorValue) => typeof cursorValue !== "string");
+    const cursorConflict = cursorValues.length > 1 &&
+        cursorValues.some((cursorValue) => cursorValue !== cursorValues[0]);
+    const recoveryAliases = ["recovered", "recoveryComplete"];
+    const recoveryDeclarations = recoveryAliases
+        .filter((alias) => Object.hasOwn(record, alias))
+        .map((alias) => record[alias]);
+    const recoveryInvalid = recoveryDeclarations.some((declaration) => typeof declaration !== "boolean");
+    const recoveryConflict = recoveryDeclarations.includes(true) && recoveryDeclarations.includes(false);
+    const normalizedError = typeof record["error"] === "string"
+        ? record["error"].trim().toLowerCase()
+        : undefined;
+    const explicitlyRejected = hasInvalidBooleanAlias ||
+        hasInvalidStatusAlias ||
+        record["ok"] === false ||
+        record["accepted"] === false ||
+        record["success"] === false ||
+        record["error"] !== undefined ||
+        cursorInvalid ||
+        cursorConflict ||
+        recoveryInvalid ||
+        recoveryConflict ||
+        (!reconnect && recoveryDeclarations.includes(false)) ||
+        hasUnknownStatus ||
+        statuses.some((status) => status.rejected);
+    const accepted = explicitlyAccepted && !explicitlyRejected;
+    const cursor = cursorValues[0];
+    const recoveryComplete = !reconnect ||
+        (recoveryDeclarations.length > 0 &&
+            recoveryDeclarations.every((declaration) => declaration === true));
+    const authenticationRejected = statuses.some(({ normalized, numeric }) => numeric === 401 || normalized === "unauthorized") || normalizedError === "unauthorized";
+    const authorizationRejected = statuses.some(({ normalized, numeric }) => numeric === 403 || normalized === "forbidden") || normalizedError === "forbidden";
+    return {
+        accepted,
+        ...(authenticationRejected
+            ? { rejectionCode: "authentication" }
+            : authorizationRejected
+                ? { rejectionCode: "authorization" }
+                : accepted
+                    ? {}
+                    : { rejectionCode: "validation" }),
+        recoveryComplete,
+        ...(typeof cursor === "string" ? { cursor } : {}),
+        ...(typeof record["message"] === "string"
+            ? { message: record["message"] }
+            : {}),
+    };
+};
 const sameRun = (first, second) => first === second ||
     (first != null &&
         second != null &&
@@ -102,9 +219,9 @@ export const createSocketIoFactoryWith = (connect) => ({ getAuth, namespaceUrl,
 });
 export const createSocketIoFactory = createSocketIoFactoryWith(io);
 export class TFRobotSocketClient {
-    #active;
     #disposed = false;
     #establishmentAbort;
+    #establishing;
     #factory;
     #namespaceUrl;
     #now;
@@ -112,6 +229,8 @@ export class TFRobotSocketClient {
     #path;
     #reconnectStatusLoader;
     #runs = new Map();
+    #subscriptions = new Set();
+    #subscriptionGeneration = 0;
     constructor(options, reconnectStatusLoader) {
         this.#options = options;
         this.#factory = options.socketFactory ?? createSocketIoFactory;
@@ -134,7 +253,9 @@ export class TFRobotSocketClient {
                 error: createGatewayDeadlineExceededError(),
             };
         }
-        this.#deactivateCurrent();
+        const generation = ++this.#subscriptionGeneration;
+        const subscriptionId = `tfrobot-subscription-${generation}`;
+        this.#cancelEstablishment();
         const establishmentAbort = new AbortController();
         this.#establishmentAbort = establishmentAbort;
         const authOutcome = await awaitBounded(() => this.#getSocketAuth(conversationId, "connect"), {
@@ -142,9 +263,6 @@ export class TFRobotSocketClient {
             now: this.#now,
             signal: establishmentAbort.signal,
         });
-        if (this.#establishmentAbort === establishmentAbort) {
-            this.#establishmentAbort = undefined;
-        }
         switch (authOutcome.kind) {
             case "aborted": {
                 return {
@@ -224,6 +342,20 @@ export class TFRobotSocketClient {
             };
         }
         const listeners = new Map();
+        let joinTimeout;
+        const activeErrorIds = new Map();
+        const replaceableErrorSources = new Set([
+            "authentication",
+            "connection",
+            "recovery",
+            "subscription",
+        ]);
+        let errorSequence = 0;
+        let publishUpdate = () => undefined;
+        const pendingNotifications = [];
+        const pendingRealtimeActions = [];
+        let joinPending = false;
+        let subscriptionEstablished = false;
         let setupFailure;
         const add = (eventName, listener) => {
             if (setupFailure !== undefined)
@@ -244,15 +376,52 @@ export class TFRobotSocketClient {
                 // Diagnostics are observational and cannot break the chat stream.
             }
         };
-        const report = (error) => {
-            if (!active.active)
-                return;
+        const notifyError = (error) => {
             try {
                 observer.error?.(error);
             }
             catch {
                 // Host observers are isolated from the transport listener.
             }
+        };
+        const resolveError = (source) => {
+            const errorId = activeErrorIds.get(source);
+            if (errorId === undefined || !active.active)
+                return;
+            activeErrorIds.delete(source);
+            publishUpdate(chatUpdateSchema.parse({
+                kind: "error.resolved",
+                conversationId: errorConversationId(),
+                errorId,
+            }));
+        };
+        const report = (error, source = "protocol") => {
+            if (!active.active)
+                return;
+            if (replaceableErrorSources.has(source))
+                resolveError(source);
+            const errorId = `${subscriptionId}:error:${++errorSequence}`;
+            if (replaceableErrorSources.has(source)) {
+                activeErrorIds.set(source, errorId);
+            }
+            const occurrenceError = error.conversationId === undefined
+                ? error
+                : { ...error, conversationId: errorConversationId() };
+            publishUpdate(chatUpdateSchema.parse({
+                kind: "error.reported",
+                conversationId: errorConversationId(),
+                error: occurrenceError,
+                errorId,
+                source,
+                scope: source === "domain"
+                    ? { kind: "conversation", id: errorConversationId() }
+                    : { kind: "subscription", id: subscriptionId },
+                generation,
+            }));
+            if (subscriptionEstablished)
+                notifyError(error);
+            else
+                pendingNotifications.push({ kind: "error", error });
             diagnose(error);
         };
         const sanitizePayload = (payload) => {
@@ -276,6 +445,10 @@ export class TFRobotSocketClient {
                 updateConversationId !== errorConversationId()) {
                 return;
             }
+            if (!subscriptionEstablished) {
+                pendingNotifications.push({ kind: "update", update });
+                return;
+            }
             try {
                 observer.next(update);
             }
@@ -283,6 +456,74 @@ export class TFRobotSocketClient {
                 diagnose(this.#error("unknown", "TFRobot Gateway observer rejected an update", false, errorConversationId()));
             }
         };
+        publishUpdate = next;
+        const dispatchRealtime = (action) => {
+            if (active.acceptingEvents)
+                action();
+            else if (joinPending)
+                pendingRealtimeActions.push(action);
+        };
+        const flushRealtime = () => {
+            for (const action of pendingRealtimeActions.splice(0))
+                action();
+        };
+        const lifecycle = (status, recovery, joinLatencyMs) => {
+            if (!active.active)
+                return;
+            const value = {
+                status,
+                generation,
+                reconnectAttempt: active.reconnectAttempt,
+                subscriptionId,
+                ...(recovery === undefined ? {} : { recovery }),
+            };
+            const update = chatUpdateSchema.parse({
+                kind: "lifecycle.changed",
+                conversationId: errorConversationId(),
+                lifecycle: value,
+            });
+            next(update);
+            try {
+                void Promise.resolve(this.#options.onLifecycleDiagnostic?.({
+                    kind: "socket.lifecycle",
+                    conversationId: errorConversationId(),
+                    subscriptionId,
+                    generation,
+                    status,
+                    reconnectAttempt: active.reconnectAttempt,
+                    ...(joinLatencyMs === undefined ? {} : { joinLatencyMs }),
+                    ...(recovery === undefined
+                        ? {}
+                        : {
+                            recoveryComplete: recovery.complete,
+                            ...(recovery.cursor === undefined
+                                ? {}
+                                : { recoveryCursor: recovery.cursor }),
+                            ...(recovery.reason === undefined
+                                ? {}
+                                : { recoveryReason: recovery.reason }),
+                        }),
+                })).catch(() => undefined);
+            }
+            catch {
+                // Lifecycle diagnostics are observational.
+            }
+        };
+        const enterAuthRequired = () => {
+            active.acceptingEvents = false;
+            active.authRequired = true;
+            active.terminal = true;
+            joinPending = false;
+            pendingRealtimeActions.length = 0;
+            active.recoveryRevision += 1;
+            lifecycle("auth-required");
+            try {
+                active.socket.disconnect();
+            }
+            catch {
+                // Authentication is already terminal for this subscription episode.
+            }
+        };
         const mapAndNext = (invalidMessage, map) => {
             let update;
             try {
@@ -295,10 +536,18 @@ export class TFRobotSocketClient {
             next(update);
         };
         let settleEstablishment;
-        let connectedOnce = false;
         add("connect", () => {
             if (!active.active)
                 return;
+            if (active.terminal) {
+                try {
+                    active.socket.disconnect();
+                }
+                catch {
+                    // Terminal subscriptions never rejoin.
+                }
+                return;
+            }
             if (settleEstablishment !== undefined &&
                 isGatewayDeadlineExceeded(options, this.#now())) {
                 settleEstablishment({
@@ -307,13 +556,206 @@ export class TFRobotSocketClient {
                 });
                 return;
             }
-            const reconnect = connectedOnce;
-            connectedOnce = true;
+            if (joinTimeout !== undefined) {
+                clearTimeout(joinTimeout);
+                joinTimeout = undefined;
+            }
+            const reconnect = subscriptionEstablished;
+            if (reconnect)
+                active.reconnectAttempt += 1;
             const recoveryRevision = ++active.recoveryRevision;
-            try {
-                socket.emit("join_conversation", {
-                    conversation_id: conversationId,
+            const runRevision = active.runRevision;
+            const joinStartedAt = this.#now();
+            active.acceptingEvents = false;
+            joinPending = true;
+            pendingRealtimeActions.length = 0;
+            lifecycle("joining");
+            let acknowledgementSettled = false;
+            const settleJoin = (...acknowledgementArguments) => {
+                if (!active.active ||
+                    !this.#subscriptions.has(active) ||
+                    active.recoveryRevision !== recoveryRevision) {
+                    return;
+                }
+                if (acknowledgementSettled)
+                    return;
+                acknowledgementSettled = true;
+                if (joinTimeout !== undefined) {
+                    clearTimeout(joinTimeout);
+                    joinTimeout = undefined;
+                }
+                let acknowledgement;
+                try {
+                    const rawAcknowledgement = acknowledgementArguments[0];
+                    acknowledgement = parseJoinAcknowledgement(rawAcknowledgement === undefined || rawAcknowledgement === true
+                        ? rawAcknowledgement
+                        : sanitizeCredentialRaw(rawAcknowledgement, credentialValues), reconnect);
+                }
+                catch {
+                    acknowledgement = {
+                        accepted: false,
+                        recoveryComplete: false,
+                        rejectionCode: "validation",
+                        message: "Invalid TFRobot conversation subscription acknowledgement",
+                    };
+                }
+                if (!acknowledgement.accepted) {
+                    joinPending = false;
+                    pendingRealtimeActions.length = 0;
+                    const rejectionCode = acknowledgement.rejectionCode ?? "validation";
+                    const error = this.#error(rejectionCode, acknowledgement.message ??
+                        "TFRobot conversation subscription was rejected", false, errorConversationId());
+                    if (settleEstablishment !== undefined) {
+                        lifecycle("subscription-failed");
+                        if (rejectionCode === "authentication" ||
+                            rejectionCode === "authorization") {
+                            void this.#invalidateSession(error, "rejected");
+                        }
+                        settleEstablishment({ ok: false, error });
+                    }
+                    else {
+                        const authenticationRejected = rejectionCode === "authentication" ||
+                            rejectionCode === "authorization";
+                        if (authenticationRejected) {
+                            enterAuthRequired();
+                        }
+                        else {
+                            active.acceptingEvents = false;
+                            active.terminal = true;
+                            active.recoveryRevision += 1;
+                            try {
+                                active.socket.disconnect();
+                            }
+                            catch {
+                                // Subscription failure is already terminal for this episode.
+                            }
+                            lifecycle("subscription-failed");
+                        }
+                        report(error, authenticationRejected ? "authentication" : "subscription");
+                        if (authenticationRejected) {
+                            void this.#invalidateSession(error, "rejected");
+                        }
+                    }
+                    return;
+                }
+                if (!reconnect) {
+                    joinPending = false;
+                    subscriptionEstablished = true;
+                    for (const notification of pendingNotifications.splice(0)) {
+                        if (notification.kind === "update")
+                            next(notification.update);
+                        else
+                            notifyError(notification.error);
+                    }
+                    settleEstablishment?.({
+                        ok: true,
+                        value: {
+                            dispose: () => {
+                                if (!active.active)
+                                    return;
+                                active.active = false;
+                                active.cleanup();
+                                this.#subscriptions.delete(active);
+                            },
+                        },
+                    });
+                    resolveError("connection");
+                    resolveError("authentication");
+                    lifecycle("active", {
+                        complete: true,
+                        ...(acknowledgement.cursor === undefined
+                            ? {}
+                            : { cursor: acknowledgement.cursor }),
+                    }, this.#now() - joinStartedAt);
+                    active.acceptingEvents = true;
+                    flushRealtime();
+                    return;
+                }
+                joinPending = false;
+                const joinLatencyMs = this.#now() - joinStartedAt;
+                lifecycle("recovering", {
+                    complete: false,
+                    ...(acknowledgement.cursor === undefined
+                        ? {}
+                        : { cursor: acknowledgement.cursor }),
+                    ...(acknowledgement.recoveryComplete
+                        ? {}
+                        : { reason: "server-replay-contract-unavailable" }),
+                }, joinLatencyMs);
+                active.acceptingEvents = true;
+                flushRealtime();
+                void this.#reconcileRunAfterReconnect(active, conversationId, credentialValues, recoveryRevision, runRevision, next, report)
+                    .then((outcome) => {
+                    if (outcome === "auth-required") {
+                        enterAuthRequired();
+                        return;
+                    }
+                    if ((outcome !== "success" && outcome !== "superseded-by-realtime") ||
+                        !acknowledgement.recoveryComplete) {
+                        return;
+                    }
+                    resolveError("connection");
+                    resolveError("recovery");
+                    resolveError("authentication");
+                    active.manualReconnectAttempted = false;
+                    active.manualReconnectPending = false;
+                    active.authRequired = false;
+                    active.terminal = false;
+                    lifecycle("active", {
+                        complete: true,
+                        ...(acknowledgement.cursor === undefined
+                            ? {}
+                            : { cursor: acknowledgement.cursor }),
+                    }, joinLatencyMs);
+                })
+                    .catch(() => {
+                    active.acceptingEvents = false;
+                    active.terminal = true;
+                    try {
+                        active.socket.disconnect();
+                    }
+                    catch {
+                        // Offline is already terminal for this subscription episode.
+                    }
+                    lifecycle("offline");
+                    report(this.#error("unknown", "TFRobot reconnect reconciliation failed", true, errorConversationId()), "recovery");
                 });
+            };
+            const joinDeadlineAt = reconnect
+                ? this.#now() + RECONNECT_JOIN_TIMEOUT_MS
+                : options.deadlineAt;
+            joinTimeout = setTimeout(() => {
+                joinTimeout = undefined;
+                if (!active.active || active.recoveryRevision !== recoveryRevision) {
+                    return;
+                }
+                active.recoveryRevision += 1;
+                joinPending = false;
+                pendingRealtimeActions.length = 0;
+                const error = createGatewayDeadlineExceededError(errorConversationId());
+                if (settleEstablishment !== undefined) {
+                    lifecycle("subscription-failed");
+                    settleEstablishment({ ok: false, error });
+                }
+                else {
+                    if (active.manualReconnectPending)
+                        enterAuthRequired();
+                    else {
+                        active.acceptingEvents = false;
+                        active.terminal = true;
+                        lifecycle("subscription-failed");
+                    }
+                    report(error, active.manualReconnectPending ? "connection" : "subscription");
+                    try {
+                        active.socket.disconnect();
+                    }
+                    catch {
+                        // The failed join attempt is already invalidated.
+                    }
+                }
+            }, Math.min(MAX_TIMER_DELAY, Math.max(0, joinDeadlineAt - this.#now())));
+            try {
+                socket.emit("join_conversation", { conversation_id: conversationId }, settleJoin);
             }
             catch (reason) {
                 const error = this.#transportError(reason, "Unable to join the TFRobot conversation", conversationId, credentialValues);
@@ -321,112 +763,97 @@ export class TFRobotSocketClient {
                     settleEstablishment({ ok: false, error });
                 }
                 else {
-                    report(error);
+                    report(error, "subscription");
                     active.active = false;
                     active.cleanup();
-                    if (this.#active === active)
-                        this.#active = undefined;
+                    this.#subscriptions.delete(active);
                 }
                 return;
             }
-            if (settleEstablishment !== undefined &&
-                isGatewayDeadlineExceeded(options, this.#now())) {
-                settleEstablishment({
-                    ok: false,
-                    error: createGatewayDeadlineExceededError(errorConversationId()),
-                });
-                return;
-            }
-            settleEstablishment?.({
-                ok: true,
-                value: {
-                    dispose: () => {
-                        if (!active.active)
-                            return;
-                        active.active = false;
-                        active.cleanup();
-                        if (this.#active === active)
-                            this.#active = undefined;
-                    },
-                },
-            });
-            if (reconnect) {
-                void this.#reconcileRunAfterReconnect(active, conversationId, credentialValues, recoveryRevision, next, report).catch(() => {
-                    report(this.#error("unknown", "TFRobot reconnect reconciliation failed", true, errorConversationId()));
-                });
-            }
         });
         add("chat_message", (payload) => {
-            if (belongsToForeignConversation(payload, conversationId))
-                return;
-            const parsed = messageDtoSchema.safeParse(sanitizePayload(payload));
-            if (!parsed.success) {
-                report(this.#error("validation", "Invalid TFRobot chat_message payload", false, errorConversationId()));
-                return;
-            }
-            mapAndNext("TFRobot chat_message could not be normalized", () => mapMessageUpdate(parsed.data));
+            dispatchRealtime(() => {
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                const parsed = messageDtoSchema.safeParse(sanitizePayload(payload));
+                if (!parsed.success) {
+                    report(this.#error("validation", "Invalid TFRobot chat_message payload", false, errorConversationId()));
+                    return;
+                }
+                mapAndNext("TFRobot chat_message could not be normalized", () => mapMessageUpdate(parsed.data));
+            });
         });
         add("chat_event", (payload) => {
-            if (belongsToForeignConversation(payload, conversationId))
-                return;
-            const parsed = eventDtoSchema.safeParse(sanitizePayload(payload));
-            if (!parsed.success) {
-                report(this.#error("validation", "Invalid TFRobot chat_event payload", false, errorConversationId()));
-                return;
-            }
-            mapAndNext("TFRobot chat_event could not be normalized", () => mapEventUpdate(parsed.data));
+            dispatchRealtime(() => {
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                const parsed = eventDtoSchema.safeParse(sanitizePayload(payload));
+                if (!parsed.success) {
+                    report(this.#error("validation", "Invalid TFRobot chat_event payload", false, errorConversationId()));
+                    return;
+                }
+                mapAndNext("TFRobot chat_event could not be normalized", () => mapEventUpdate(parsed.data));
+            });
         });
         add("conversation_state_changed", (payload) => {
-            if (belongsToForeignConversation(payload, conversationId))
-                return;
-            const parsed = stateChangedDtoSchema.safeParse(sanitizePayload(payload));
-            if (!parsed.success) {
-                report(this.#error("validation", "Invalid TFRobot conversation_state_changed payload", false, errorConversationId()));
-                return;
-            }
-            const targetConversationId = String(parsed.data.conversationId);
-            if (targetConversationId !== conversationId &&
-                targetConversationId !== errorConversationId()) {
-                return;
-            }
-            active.recoveryRevision += 1;
-            mapAndNext("TFRobot run state could not be normalized", () => {
-                const run = mapRun(targetConversationId, {
-                    working: parsed.data.state === "working",
-                    taskId: parsed.data.taskId,
-                });
-                this.#runs.set(targetConversationId, run);
-                return chatUpdateSchema.parse({
-                    kind: "run.replace",
-                    conversationId: targetConversationId,
-                    run,
+            dispatchRealtime(() => {
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                const parsed = stateChangedDtoSchema.safeParse(sanitizePayload(payload));
+                if (!parsed.success) {
+                    report(this.#error("validation", "Invalid TFRobot conversation_state_changed payload", false, errorConversationId()));
+                    return;
+                }
+                const targetConversationId = String(parsed.data.conversationId);
+                if (targetConversationId !== conversationId &&
+                    targetConversationId !== errorConversationId()) {
+                    return;
+                }
+                active.runRevision += 1;
+                mapAndNext("TFRobot run state could not be normalized", () => {
+                    const run = mapRun(targetConversationId, {
+                        working: parsed.data.state === "working",
+                        taskId: parsed.data.taskId,
+                    });
+                    this.#runs.set(targetConversationId, run);
+                    return chatUpdateSchema.parse({
+                        kind: "run.replace",
+                        conversationId: targetConversationId,
+                        run,
+                    });
                 });
             });
         });
         add("chat_error", (payload) => {
-            if (belongsToForeignConversation(payload, conversationId))
-                return;
-            const parsed = chatErrorEventDtoSchema.safeParse(sanitizePayload(payload));
-            if (!parsed.success) {
-                report(this.#error("validation", "Invalid TFRobot chat_error payload", false, errorConversationId()));
-                return;
-            }
-            const targetConversationId = String(parsed.data.conversationId);
-            if (targetConversationId !== conversationId &&
-                targetConversationId !== errorConversationId()) {
-                return;
-            }
-            report(this.#error("server", typeof parsed.data.error === "string"
-                ? parsed.data.error
-                : "TFRobot run failed", false, targetConversationId, parsed.data, credentialValues));
+            dispatchRealtime(() => {
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                const parsed = chatErrorEventDtoSchema.safeParse(sanitizePayload(payload));
+                if (!parsed.success) {
+                    report(this.#error("validation", "Invalid TFRobot chat_error payload", false, errorConversationId()));
+                    return;
+                }
+                const targetConversationId = String(parsed.data.conversationId);
+                if (targetConversationId !== conversationId &&
+                    targetConversationId !== errorConversationId()) {
+                    return;
+                }
+                report(this.#error("server", typeof parsed.data.error === "string"
+                    ? parsed.data.error
+                    : "TFRobot run failed", false, targetConversationId, parsed.data, credentialValues), "domain");
+            });
         });
         add("error", (payload) => {
-            const parsed = socketProtocolErrorDtoSchema.safeParse(sanitizePayload(payload));
-            report(this.#error("validation", parsed.success && typeof parsed.data.message === "string"
-                ? parsed.data.message
-                : "TFRobot Socket protocol error", false, conversationId, undefined, credentialValues));
+            dispatchRealtime(() => {
+                const parsed = socketProtocolErrorDtoSchema.safeParse(sanitizePayload(payload));
+                report(this.#error("validation", parsed.success && typeof parsed.data.message === "string"
+                    ? parsed.data.message
+                    : "TFRobot Socket protocol error", false, conversationId, undefined, credentialValues));
+            });
         });
         add("connect_error", (reason) => {
+            if (!active.active || active.terminal)
+                return;
             const injectedError = chatErrorSchema.safeParse(reason);
             const rejectionCode = socketAuthRejectionCode(reason);
             const error = authenticationFailure !== undefined
@@ -448,23 +875,82 @@ export class TFRobotSocketClient {
                 settleEstablishment({ ok: false, error });
                 return;
             }
-            report(error);
+            if (active.manualReconnectPending) {
+                enterAuthRequired();
+                report(error, error.code === "authentication" || error.code === "authorization"
+                    ? "authentication"
+                    : "connection");
+                return;
+            }
+            if (error.code === "authentication" || error.code === "authorization") {
+                enterAuthRequired();
+            }
+            report(error, error.code === "authentication" || error.code === "authorization"
+                ? "authentication"
+                : "connection");
         });
         add("disconnect", (reason) => {
             if (reason === "io client disconnect")
                 return;
+            if (active.terminal)
+                return;
+            active.acceptingEvents = false;
+            joinPending = false;
+            pendingRealtimeActions.length = 0;
+            if (joinTimeout !== undefined) {
+                clearTimeout(joinTimeout);
+                joinTimeout = undefined;
+            }
             active.recoveryRevision += 1;
+            lifecycle("reconnecting");
             const injectedError = chatErrorSchema.safeParse(reason);
             report(injectedError.success
                 ? sanitizeCredentialError(injectedError.data, credentialValues)
-                : this.#error("network", `TFRobot Socket disconnected: ${String(reason)}`, true, conversationId, undefined, credentialValues));
-        });
-        const anyListener = (eventName, payload) => {
-            if (KNOWN_EVENTS.has(eventName))
+                : this.#error("network", `TFRobot Socket disconnected: ${String(reason)}`, true, conversationId, undefined, credentialValues), "connection");
+            if (reason !== "io server disconnect")
                 return;
-            if (belongsToForeignConversation(payload, conversationId))
+            if (active.manualReconnectAttempted) {
+                enterAuthRequired();
                 return;
-            mapAndNext("Unknown TFRobot Socket event could not be normalized", () => mapUnknownSocketEvent(sanitizeCredentialText(eventName, credentialValues), sanitizePayload(payload), errorConversationId(), this.#now()));
+            }
+            active.manualReconnectAttempted = true;
+            active.manualReconnectPending = true;
+            const invalidationRevision = active.recoveryRevision;
+            const invalidationError = this.#error("authentication", "TFRobot Socket session was invalidated by the server", true, errorConversationId());
+            void awaitBounded(() => this.#invalidateSession(invalidationError, "unknown"), {
+                deadlineAt: this.#now() + RECONNECT_AUTH_TIMEOUT_MS,
+                now: this.#now,
+                signal: connectionAbort.signal,
+            }).then((outcome) => {
+                if (!active.active ||
+                    active.socket.connected ||
+                    active.authRequired ||
+                    !active.manualReconnectPending ||
+                    active.recoveryRevision !== invalidationRevision) {
+                    return;
+                }
+                if (outcome.kind !== "value" || !outcome.value) {
+                    report(this.#error("authentication", "Unable to invalidate the TFRobot Socket session", false, errorConversationId()), "authentication");
+                    enterAuthRequired();
+                    return;
+                }
+                try {
+                    active.socket.connect();
+                }
+                catch (reconnectError) {
+                    report(this.#transportError(reconnectError, "Unable to reconnect the TFRobot Socket transport", conversationId, credentialValues), "authentication");
+                    enterAuthRequired();
+                }
+            });
+        });
+        const anyListener = (eventName, payload) => {
+            dispatchRealtime(() => {
+                if (KNOWN_EVENTS.has(eventName))
+                    return;
+                if (belongsToForeignConversation(payload, conversationId))
+                    return;
+                mapAndNext("Unknown TFRobot Socket event could not be normalized", () => mapUnknownSocketEvent(sanitizeCredentialText(eventName, credentialValues), sanitizePayload(payload), errorConversationId(), this.#now()));
+            });
         };
         if (setupFailure === undefined) {
             try {
@@ -476,6 +962,10 @@ export class TFRobotSocketClient {
         }
         const cleanup = () => {
             connectionAbort.abort();
+            if (joinTimeout !== undefined) {
+                clearTimeout(joinTimeout);
+                joinTimeout = undefined;
+            }
             for (const [eventName, listener] of listeners) {
                 try {
                     socket.off(eventName, listener);
@@ -498,6 +988,8 @@ export class TFRobotSocketClient {
             }
             firstAuth = undefined;
             credentialValues.clear();
+            pendingNotifications.length = 0;
+            pendingRealtimeActions.length = 0;
         };
         if (setupFailure !== undefined) {
             const error = this.#transportError(setupFailure.reason, "Unable to configure the TFRobot Socket transport", conversationId, credentialValues);
@@ -508,7 +1000,9 @@ export class TFRobotSocketClient {
             };
         }
         const active = {
+            acceptingEvents: true,
             active: true,
+            authRequired: false,
             cancelEstablishment: () => {
                 settleEstablishment?.({
                     ok: false,
@@ -517,11 +1011,19 @@ export class TFRobotSocketClient {
             },
             cleanup,
             conversationId,
+            generation,
+            manualReconnectAttempted: false,
+            manualReconnectPending: false,
             observer,
+            reconnectAttempt: 0,
             recoveryRevision: 0,
+            runRevision: 0,
             socket,
+            subscriptionId,
+            terminal: false,
         };
-        this.#active = active;
+        this.#subscriptions.add(active);
+        this.#establishing = active;
         return new Promise((resolve) => {
             let settled = false;
             const settle = (result) => {
@@ -529,12 +1031,16 @@ export class TFRobotSocketClient {
                     return;
                 settled = true;
                 settleEstablishment = undefined;
+                if (this.#establishmentAbort === establishmentAbort) {
+                    this.#establishmentAbort = undefined;
+                }
+                if (this.#establishing === active)
+                    this.#establishing = undefined;
                 clearTimeout(timeout);
                 if (!result.ok) {
                     active.active = false;
                     active.cleanup();
-                    if (this.#active === active)
-                        this.#active = undefined;
+                    this.#subscriptions.delete(active);
                 }
                 resolve(result);
             };
@@ -553,6 +1059,7 @@ export class TFRobotSocketClient {
                 return;
             }
             try {
+                lifecycle("connecting");
                 socket.connect();
             }
             catch (reason) {
@@ -574,7 +1081,12 @@ export class TFRobotSocketClient {
         if (this.#disposed)
             return;
         this.#disposed = true;
-        this.#deactivateCurrent();
+        this.#cancelEstablishment();
+        for (const subscription of this.#subscriptions) {
+            subscription.active = false;
+            subscription.cleanup();
+        }
+        this.#subscriptions.clear();
         this.#runs.clear();
     }
     rememberRun(conversationId, run) {
@@ -582,16 +1094,11 @@ export class TFRobotSocketClient {
             return;
         this.#runs.set(conversationId, run);
     }
-    #deactivateCurrent() {
+    #cancelEstablishment() {
         this.#establishmentAbort?.abort();
         this.#establishmentAbort = undefined;
-        const current = this.#active;
-        if (current === undefined)
-            return;
-        current.cancelEstablishment();
-        current.active = false;
-        current.cleanup();
-        this.#active = undefined;
+        this.#establishing?.cancelEstablishment();
+        this.#establishing = undefined;
     }
     #defaultNamespaceUrl(baseUrl) {
         const url = new URL(baseUrl);
@@ -611,17 +1118,28 @@ export class TFRobotSocketClient {
         }
         return authOf(session);
     }
-    async #reconcileRunAfterReconnect(active, conversationId, credentialValues, recoveryRevision, next, report) {
+    async #reconcileRunAfterReconnect(active, conversationId, credentialValues, recoveryRevision, runRevision, next, report) {
         const result = await this.#reconnectStatusLoader(conversationId);
         if (!active.active ||
-            this.#active !== active ||
+            !this.#subscriptions.has(active) ||
             !active.socket.connected ||
             active.recoveryRevision !== recoveryRevision) {
-            return;
+            return "failure";
         }
         if (!result.ok) {
-            report(sanitizeCredentialError(result.error, credentialValues));
-            return;
+            const error = sanitizeCredentialError(result.error, credentialValues);
+            if (error.code === "authentication" || error.code === "authorization") {
+                report(error, "authentication");
+                return "auth-required";
+            }
+            if (active.runRevision !== runRevision) {
+                return "superseded-by-realtime";
+            }
+            report(error, "recovery");
+            return "failure";
+        }
+        if (active.runRevision !== runRevision) {
+            return "superseded-by-realtime";
         }
         try {
             const updateConversationId = sanitizeCredentialText(conversationId, credentialValues);
@@ -629,16 +1147,18 @@ export class TFRobotSocketClient {
             const run = mapRun(updateConversationId, safeStatus);
             const previous = this.#runs.get(conversationId);
             this.#runs.set(conversationId, run);
-            if (sameRun(previous, run))
-                return;
-            next(chatUpdateSchema.parse({
-                kind: "run.replace",
-                conversationId: updateConversationId,
-                run,
-            }));
+            if (!sameRun(previous, run)) {
+                next(chatUpdateSchema.parse({
+                    kind: "run.replace",
+                    conversationId: updateConversationId,
+                    run,
+                }));
+            }
+            return "success";
         }
         catch {
-            report(this.#error("validation", "Reconnected TFRobot run status could not be normalized", false, conversationId, undefined, credentialValues));
+            report(this.#error("validation", "Reconnected TFRobot run status could not be normalized", false, conversationId, undefined, credentialValues), "recovery");
+            return "failure";
         }
     }
     async #invalidateSession(error, reason) {
@@ -647,9 +1167,10 @@ export class TFRobotSocketClient {
                 reason: reason ?? (error.code === "authorization" ? "forbidden" : "expired"),
                 error,
             });
+            return true;
         }
         catch {
-            // Host refresh/login failures must not replace the Socket error.
+            return false;
         }
     }
     #transportError(reason, fallback, conversationId, credentialValues = []) {