Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

79.6 KB
Raw Blame
"use client"

import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react"
import { useAuth } from "@/contexts/auth-context"
import type { AuthSessionSnapshot } from "@/lib/auth-cache"
import { apiRequest, classifyUploadError, isJsonRecord, parseApiResponse } from "@/lib/api-wrapper"
import { clientErrorFallback, isInputReviewErrorCode, readClientErrorCode, readServerRejectionCode, type ClientErrorCode } from "@/lib/client-errors"
import { normalizeUploadFileIds } from "@/lib/upload-file-ids"
import { isCanonicalUuid } from "@/lib/widget-session-upload"
import { generateClientMessageId, getWsUrl, getUploadApiUrl } from "@/lib/utils"
import { isFinalAnswerStreamEventType } from "@/lib/streaming-final-answer"
import { websocketAuthProtocols } from "@/lib/websocket-auth"

interface RecentMessage {
  message: string
  timestamp: number
  connectionIdentity: string
  descriptorKey: ConnectionDescriptorIdentity
  lifecycleEpoch: number
  attemptEpoch: number
  deliveryGeneration: number
  clientMessageId: string
}

// Dead after this long without any frame, once the server confirmed heartbeats.
// The server's HEARTBEAT_INTERVAL_SECONDS fits into it twice, and widget.js
// SESSION_STABLE_CONNECTION_MS is twice this value.
export const DEAD_AFTER_MS = 30_000

// Reconnects never give up: a release restarts the backend for minutes, and a
// page left open across it must come back without a refresh. The delay grows
// by 1.5x from one second to a five-minute cap, so a page notices the end of
// an outage within about half the outage's length.
export const RECONNECT_BASE_DELAY_MS = 1_000
export const RECONNECT_MAX_DELAY_MS = 300_000
const RECONNECT_BACKOFF_FACTOR = 1.5
const RECONNECT_JITTER = 0.2

// `attempt` is 1-based; `random` is a value in [0, 1). Whole milliseconds.
export const reconnectDelayMs = (attempt: number, random: number): number => {
  const step = Math.max(0, attempt - 1)
  const nominal = Math.min(
    RECONNECT_MAX_DELAY_MS,
    RECONNECT_BASE_DELAY_MS * RECONNECT_BACKOFF_FACTOR ** step,
  )
  return Math.round(nominal * (1 - RECONNECT_JITTER + 2 * RECONNECT_JITTER * random))
}

// A server that is draining closes with 1012 (Service Restart) or with this
// reason, asking the client to come back on another instance.
export const RECONNECT_CLOSE_REASON = "reconnect"

// Closes that a new connection would only repeat: protocol and policy errors.
const PERMANENT_CLOSE_CODES = new Set([1002, 1003, 1007, 1008, 1010, 1015])
// Application codes (4000-4999) are permanent unless listed here. 4008 is the
// public chat's connection rate limit, which the back-off itself respects.
const RETRYABLE_APPLICATION_CLOSE_CODES = new Set([4008])

export type CloseDisposition =
  // The other side meant to close (1000); nothing to recover.
  | "intentional"
  // 4001: refresh the access token, then connect again.
  | "reauthenticate"
  // Access denied, task unavailable, protocol or policy errors.
  | "permanent"
  // Abnormal closure (1006), server restart (1001, 1011-1014) and the rest.
  | "retry"

export const classifyClose = (
  event: Pick<CloseEvent, "code" | "reason">,
): CloseDisposition => {
  if (event.code === 1000) {
    return event.reason === RECONNECT_CLOSE_REASON ? "retry" : "intentional"
  }
  if (event.code === 4001) return "reauthenticate"
  if (PERMANENT_CLOSE_CODES.has(event.code)) return "permanent"
  if (
    event.code >= 4000
    && event.code <= 4999
    && !RETRYABLE_APPLICATION_CLOSE_CODES.has(event.code)
  ) {
    return "permanent"
  }
  return "retry"
}

export type ConnectionPhase = "idle" | "connecting" | "connected" | "reconnecting" | "lost"

export interface ConnectionPhaseFacts {
  hasDescriptor: boolean
  autoConnect: boolean
  stoppedByCaller: boolean
  ownerOpen: boolean
  ownerInFlight: boolean
  retryPending: boolean
  lifecycleEnded: boolean
}

// A pure function of facts the connection manager already owns; first match wins.
export const deriveConnectionPhase = (facts: ConnectionPhaseFacts): ConnectionPhase => {
  const hasConnectionObject = facts.ownerOpen || facts.ownerInFlight
  if (!facts.hasDescriptor || facts.stoppedByCaller || (!facts.autoConnect && !hasConnectionObject)) return "idle"
  if (facts.ownerOpen) return "connected"
  if (facts.retryPending || (facts.ownerInFlight && facts.lifecycleEnded)) return "reconnecting"
  return facts.ownerInFlight || !facts.lifecycleEnded ? "connecting" : "lost"
}

const MESSAGE_DUPLICATE_THRESHOLD = 2000 // Same message within 2 seconds is considered duplicate
const HANDSHAKE_TIMEOUT_MS = 10_000
const MAX_AUTH_REFRESH_RETRIES = 3
const SESSION_BINDING_PROTOCOL = "xagent-session-binding-v1"
const SESSION_TASK_PROTOCOL_PREFIX = "xagent-session-task."

// Connection values may carry credentials. Lifecycle fencing keeps the
// normalized connection object opaque; it is never serialized or hashed.
type ConnectionDescriptorIdentity = WebSocketConnection

interface WebSocketMessage {
  type: string
  data: unknown
  timestamp: string
  task_id?: number
  step_id?: string
  event_id?: string
  event_type?: string
  message_id?: string
  delta?: string
  content?: string
  run_id?: string | null
  stream_run_id?: string | null
  stream_attempt_id?: string | null
  state_version?: number
  control_state?: "idle" | "running" | "pause_requested" | "paused" | "resume_requested" | "waiting_for_user" | "completed" | "failed"
  status?: unknown
  task?: Record<string, unknown>
}

interface MessageDeliveryAck {
  client_message_id: string
  turn_id: string
}

// Files that were already uploaded elsewhere and are attached to a chat frame
// by id. Only connections that omit the task id (the Session transport) accept
// them; the caller passes the server-advertised per-message limit.
export interface ChatMessageFileIds {
  fileIds?: readonly string[]
  maxFileIds?: number
}

export type MessageDeliveryDisposition = "not_sent" | "rejected" | "outcome_unknown"

interface MessageDeliveryErrorOptions {
  retryWithNewId?: boolean
  userFacing?: boolean
  errorCode?: ClientErrorCode | null
  connectionLost?: boolean
}

export class MessageDeliveryError extends Error {
  readonly disposition: MessageDeliveryDisposition
  readonly retryWithNewId: boolean
  /**
   * Whether `message` explains the failure in terms the sender can act on —
   * the server's rejection text. The remaining messages describe connection
   * plumbing ("the connection changed before delivery") and are diagnostics:
   * callers show their own localized string for those rather than putting
   * internal English in front of a visitor.
   */
  readonly userFacing: boolean
  /**
   * Display key for this failure; callers localize it with
   * clientErrorTranslationKey. It may be a client-derived code, so a non-null
   * value is not necessarily what the server sent, and it does not imply that
   * `message` is safe to show (`userFacing` alone says that). For an
   * `outcome_unknown` error, an omitted errorCode and an explicit `null` are
   * equivalent: both become `message_outcome_unknown`, so a send that may have
   * landed is never worded as a plain failure. Such an error stays code-less
   * only when it is constructed with `userFacing: true`. `not_sent` and
   * `rejected` errors get no default code.
   */
  readonly errorCode: ClientErrorCode | null
  /**
   * The connection carrying the message ended (closed, errored, declared dead
   * or replaced by a descriptor change) while it awaited acknowledgement, so
   * the same id may be sent once more on the next connection. False for a
   * caller disconnect, an unmount, a delivery-generation change and an
   * acknowledgement timeout on a connection that is still alive.
   */
  readonly connectionLost: boolean

  constructor(
    message: string,
    disposition: MessageDeliveryDisposition,
    options: MessageDeliveryErrorOptions = {},
  ) {
    super(message)
    this.name = "MessageDeliveryError"
    this.disposition = disposition
    this.retryWithNewId = options.retryWithNewId ?? false
    this.userFacing = options.userFacing ?? false
    this.connectionLost = options.connectionLost ?? false
    this.errorCode = options.errorCode
      ?? (disposition === "outcome_unknown" && !this.userFacing
        ? "message_outcome_unknown"
        : null)
  }
}

export const resolveReportedTimezone = (): string | undefined => {
  if (typeof window !== "undefined") {
    // widget.js copies data-timezone onto the iframe URL; an embedder that knows
    // its user's business zone outranks the machine zone.
    const declared = new URLSearchParams(window.location.search).get("timezone")?.trim()
    if (declared) return declared
  }
  try {
    // Defensive: neither a throwing Intl nor an empty resolved zone may block
    // the send. The caller's truthiness check drops "".
    return Intl.DateTimeFormat().resolvedOptions().timeZone
  } catch {
    return undefined
  }
}

// The largest task id a chat frame's conversation source may carry (a signed
// 32-bit integer).
const MAX_SOURCE_TASK_ID = 2147483647

const deliveryError = (
  message: string,
  disposition: MessageDeliveryDisposition,
  options: MessageDeliveryErrorOptions = {},
) => new MessageDeliveryError(message, disposition, options)

export type WebSocketCredentialOwner =
  | {
    kind: "auth-context"
    accessToken: string
    userId: string | null
    session?: AuthSessionSnapshot
  }
  | { kind: "external" }

const getInternalSessionId = (
  connection: WebSocketConnection | null,
): string | null => {
  const credentialOwner = connection?.credentialOwner
  return credentialOwner?.kind === "auth-context"
    ? credentialOwner.session?.sessionId ?? null
    : null
}

type LoginKind = "auth" | "external" | "widget-session"

// Only the Session window omits the task id; the embedding page owns its reconnects.
const isSessionConnection = (connection: WebSocketConnection) => connection.chatTaskIdMode === "omit"

const loginKindOf = (connection: WebSocketConnection): LoginKind => {
  if (isSessionConnection(connection)) return "widget-session"
  return connection.credentialOwner.kind === "auth-context" ? "auth" : "external"
}

// Compared in memory only: connection values may carry credentials.
const isSameLoginPrincipal = (previous: WebSocketConnection, next: WebSocketConnection) => {
  const kind = loginKindOf(previous)
  if (kind !== loginKindOf(next)) return false
  if (kind === "external") {
    const before = previous.protocols ?? []
    const after = next.protocols ?? []
    return previous.url === next.url
      && previous.loginToken === next.loginToken
      && before.length === after.length
      && before.every((protocol, index) => protocol === after[index])
  }
  const [a, b] = [previous.credentialOwner, next.credentialOwner]
  return kind === "widget-session" || (a.kind === "auth-context" && b.kind === "auth-context"
    && a.userId === b.userId && a.session?.sessionId === b.session?.sessionId)
}

export interface WebSocketConnection {
  identity: string
  url: string
  protocols?: string[]
  /** Validated only when connecting, so a malformed cache cannot crash render. */
  loginToken?: string
  expectedProtocol?: string
  taskId?: number
  chatTaskIdMode: "required" | "omit"
  taskBindingMode?: "session-subprotocol"
  credentialOwner: WebSocketCredentialOwner
}

const getConnectionProtocols = (
  connection: WebSocketConnection,
  currentTaskId: number | undefined,
): string[] | undefined => {
  if (connection.taskBindingMode !== "session-subprotocol") {
    return connection.loginToken ? websocketAuthProtocols(connection.loginToken) : connection.protocols
  }

  const baseProtocols = (connection.protocols ?? []).filter(protocol => (
    protocol !== SESSION_BINDING_PROTOCOL
    && !protocol.startsWith(SESSION_TASK_PROTOCOL_PREFIX)
  ))
  const taskBinding = Number.isInteger(currentTaskId) && Number(currentTaskId) > 0
    ? String(currentTaskId)
    : "unbound"
  return [
    ...baseProtocols,
    SESSION_BINDING_PROTOCOL,
    `${SESSION_TASK_PROTOCOL_PREFIX}${taskBinding}`,
  ]
}

export type WebSocketSendResult = "sent" | "not_sent"

export interface WebSocketConnectionFailure {
  recoverable: boolean
  error: Error
}

interface PendingDelivery {
  resolve: (ack: MessageDeliveryAck) => void
  reject: (error: Error) => void
  timeout: ReturnType<typeof setTimeout>
  connectionIdentity: string
  descriptorKey: ConnectionDescriptorIdentity
  lifecycleEpoch: number
  attemptEpoch: number
  deliveryGeneration: number
  socket: WebSocket
  framesReceivedAtSend: number
}

interface MessagePreparationClaim {
  cancellation: Promise<never>
  cancel: (error: Error) => void
  cancelled: boolean
  connectionIdentity: string
  descriptorKey: ConnectionDescriptorIdentity
  lifecycleEpoch: number
  attemptEpoch: number
  deliveryGeneration: number
  socket: WebSocket
}

interface WebSocketCallbacks {
  onConnectionClose?: (event: CloseEvent) => "handled" | "default"
  onConnectionFailure?: (failure: WebSocketConnectionFailure) => void
  onSessionConnectionClose?: (
    event: CloseEvent,
    connectionIdentity: string,
  ) => "handled" | "default"
  onSessionConnectionFailure?: (
    failure: WebSocketConnectionFailure,
    connectionIdentity: string,
  ) => void
  onConnect?: (openedTaskId: number | undefined) => void
  onConnectionCapabilities?: (capabilities: readonly string[]) => void
  onDisconnect?: () => void
  onError?: (error: Error) => void
  onMessage?: (message: WebSocketMessage) => void
}

const reportConnectionFailure = (
  callbacks: WebSocketCallbacks,
  failure: WebSocketConnectionFailure,
  connectionIdentity?: string,
) => {
  const invokeSafely = <T,>(
    callback: ((value: T) => void) | undefined,
    value: T,
  ) => {
    if (!callback) return
    try {
      callback(value)
    } catch {
      console.error("WebSocket connection failure callback failed")
    }
  }

  if (connectionIdentity && callbacks.onSessionConnectionFailure) {
    invokeSafely(
      (value) => callbacks.onSessionConnectionFailure?.(value, connectionIdentity),
      failure,
    )
  } else {
    invokeSafely(callbacks.onConnectionFailure, failure)
  }
  invokeSafely(callbacks.onError, failure.error)
}

interface SocketOwner {
  socket: WebSocket
  connection: WebSocketConnection
  descriptorKey: ConnectionDescriptorIdentity
  lifecycleEpoch: number
  attemptEpoch: number
  callbacks: WebSocketCallbacks
  refreshAccessToken: (
    expectedSession?: AuthSessionSnapshot,
  ) => Promise<boolean>
  disconnectNotified: boolean
  handshakeTimer: ReturnType<typeof setTimeout> | null
  // `{identity}|{login kind}:{login generation}`; carries no credential.
  connectionKey: string
  openedAt: number | null
  firstFrameAt: number | null
  lastFrameAt: number | null
  framesReceived: number
  heartbeatEnabled: boolean
  deadTimer: ReturnType<typeof setTimeout> | null
  sharedTaskId: number | undefined
}

interface OwnerRetirementOptions {
  pendingError: Error
  preparationError: Error
  close?: { code?: number; reason?: string }
  notifyDisconnect: boolean
  // Descriptor change, unmount and caller disconnect are not connection failures.
  keepsLifecycle?: true
}

interface ScheduledRetry {
  lifecycleEpoch: number
  attemptEpoch: number
  // Runs the retry now; the caller has already cleared the timer.
  fire: () => void
}

export interface UseWebSocketOptions {
  url?: string
  taskId?: number
  token?: string
  /** Builds the socket URL only. Credentials ride the handshake headers
   * (see websocketAuthProtocols), never the URL, so no token is passed in. */
  buildWebSocketUrl?: (params: { baseUrl: string; taskId: number }) => string
  uploadFiles?: (files: File[], params: { taskId?: number | null; taskType: string }) => Promise<Array<{ file_id: string; name?: string; size?: number; type?: string }>>
  connection?: WebSocketConnection | null
  deliveryGeneration?: number
  legacyErrorProse?: "trusted" | "untrusted"
  onConnectionClose?: (event: CloseEvent) => "handled" | "default"
  onConnectionFailure?: (failure: WebSocketConnectionFailure) => void
  onSessionConnectionClose?: (
    event: CloseEvent,
    connectionIdentity: string,
  ) => "handled" | "default"
  onSessionConnectionFailure?: (
    failure: WebSocketConnectionFailure,
    connectionIdentity: string,
  ) => void
  autoConnect?: boolean
  onMessage?: (message: WebSocketMessage) => void
  // Receives the task of the socket that opened, which can differ from the
  // caller's current task while a task switch is still being rendered.
  onConnect?: (openedTaskId: number | undefined) => void
  // Receives the capability list of the socket that sent it; the frame itself
  // is never passed to onMessage.
  onConnectionCapabilities?: (capabilities: readonly string[]) => void
  onDisconnect?: () => void
  onError?: (error: Error) => void
}

const useIsomorphicLayoutEffect = typeof window === "undefined"
  ? useEffect
  : useLayoutEffect

export function useWebSocket(options: UseWebSocketOptions = {}) {
  const {
    url,
    taskId,
    token,
    buildWebSocketUrl,
    uploadFiles,
    connection: connectionOption,
    deliveryGeneration = 0,
    legacyErrorProse = "untrusted",
    onConnectionClose,
    onConnectionFailure,
    onSessionConnectionClose,
    onSessionConnectionFailure,
    autoConnect = true,
    onMessage,
    onConnect,
    onConnectionCapabilities,
    onDisconnect,
    onError,
  } = options

  const {
    token: authToken,
    user: authUser,
    session: authSession,
    refreshAccessToken,
  } = useAuth()

  const normalizedConnection = useMemo<WebSocketConnection | null>(() => {
    if (connectionOption !== undefined) return connectionOption
    if (!taskId) return null

    const baseUrl = url ?? getWsUrl()
    const hasExplicitToken = token !== undefined
    const effectiveToken = hasExplicitToken ? token : authToken || undefined
    return {
      identity: `legacy-task:${taskId}`,
      url: buildWebSocketUrl
        ? buildWebSocketUrl({
          baseUrl,
          taskId,
        })
        : `${baseUrl}/ws/chat/${taskId}?liveness=heartbeat`,
      loginToken: effectiveToken || undefined,
      taskId,
      chatTaskIdMode: "required",
      credentialOwner: !hasExplicitToken && authToken
        ? {
          kind: "auth-context",
          accessToken: authToken,
          userId: authUser?.id ? String(authUser.id) : null,
          session: authSession,
        }
        : { kind: "external" },
    }
  }, [
    authToken,
    authUser?.id,
    authSession,
    buildWebSocketUrl,
    connectionOption,
    taskId,
    token,
    url,
  ])
  const connectionDescriptorIdentity = normalizedConnection

  const [isConnected, setIsConnected] = useState(false)
  const [lastMessage, setLastMessage] = useState<WebSocketMessage | null>(null)
  const [connectionError, setConnectionError] = useState<Error | null>(null)
  const isConnectingRef = useRef(false)

  const socketRef = useRef<WebSocket | null>(null)
  const socketOwnerRef = useRef<SocketOwner | null>(null)
  const connectionRef = useRef<WebSocketConnection | null>(normalizedConnection)
  const taskIdRef = useRef(taskId)
  const descriptorKeyRef = useRef<ConnectionDescriptorIdentity | null>(connectionDescriptorIdentity)
  const retryTimersRef = useRef(new Map<ReturnType<typeof setTimeout>, ScheduledRetry>())
  const reconnectAttemptsRef = useRef(0)
  const authRefreshRetriesRef = useRef(0)
  const authRefreshRetryBudgetSessionIdRef = useRef(getInternalSessionId(normalizedConnection))
  const deliveryGenerationRef = useRef(deliveryGeneration)
  const deliveryIdentityRef = useRef(normalizedConnection?.identity ?? null)
  const lifecycleEpochRef = useRef(0)
  const attemptEpochRef = useRef(0)
  const mountedRef = useRef(false)
  const tokenRef = useRef(token !== undefined ? token : authToken)
  const pendingDeliveriesRef = useRef(new Map<string, PendingDelivery>())
  const legacyErrorProseRef = useRef(legacyErrorProse)
  const preparationsRef = useRef(new Map<string, MessagePreparationClaim>())
  // Keyed by the logical client_message_id, not by physical send. The durable
  // transport compares the whole payload, so a same-id retry that re-resolved
  // the zone would be rejected as different content while the first command may
  // still be executing. Cleared on either terminal ack below.
  const attemptTimezonesRef = useRef(new Map<string, string | undefined>())
  // Same key and lifetime: uploaded files of a same-id retry on the same task
  // and login, so the retry carries the file ids the first attempt already sent.
  const attemptUploadsRef = useRef(new Map<string, {
    taskId: number
    loginIdentity: string
    files: Array<{ file_id: string; name?: string; size?: number; type?: string }>
  }>())
  const recentMessagesRef = useRef<RecentMessage[]>([])
  const callbacksRef = useRef<WebSocketCallbacks>({
    onConnectionClose,
    onConnectionFailure,
    onSessionConnectionClose,
    onSessionConnectionFailure,
    onConnect,
    onConnectionCapabilities,
    onDisconnect,
    onError,
    onMessage,
  })
  const refreshAccessTokenRef = useRef(refreshAccessToken)
  const openedKeysRef = useRef(new Set<string>())
  const lastConnectionKeyRef = useRef<string | null>(null)
  const loginGenerationRef = useRef(0)
  const loginPrincipalRef = useRef<WebSocketConnection | null>(normalizedConnection)
  const lifecycleEndedRef = useRef(false)
  const stoppedByCallerRef = useRef(false)
  const autoConnectRef = useRef(autoConnect)
  const connectRef = useRef<() => void>(() => undefined)
  const [connectionPhase, setConnectionPhase] = useState<ConnectionPhase>(
    normalizedConnection !== null && autoConnect ? "connecting" : "idle",
  )

  // Called at the end of every entry point (the retry timer callback also calls
  // it before its stale-attempt early return), never from internal helpers or
  // layout effects, so a half-applied state is not rendered.
  const syncPhase = useCallback(() => {
    if (!mountedRef.current) return
    const owner = socketOwnerRef.current
    setConnectionPhase(deriveConnectionPhase({
      hasDescriptor: connectionRef.current !== null,
      autoConnect: autoConnectRef.current,
      stoppedByCaller: stoppedByCallerRef.current,
      ownerOpen: owner !== null && owner.openedAt !== null,
      ownerInFlight: owner !== null && owner.openedAt === null,
      retryPending: retryTimersRef.current.size > 0,
      lifecycleEnded: lifecycleEndedRef.current,
    }))
  }, [])

  const withPhaseSync = useCallback(<Args extends unknown[]>(
    entry: (...args: Args) => void,
  ) => (...args: Args) => {
    try {
      entry(...args)
    } finally {
      syncPhase()
    }
  }, [syncPhase])

  const loginIdentityFor = useCallback((connection: WebSocketConnection) => (
    `${loginKindOf(connection)}:${loginGenerationRef.current}`
  ), [])

  // Which login the current connection belongs to; carries no credential.
  const getLoginIdentity = useCallback(() => (
    connectionRef.current ? loginIdentityFor(connectionRef.current) : null
  ), [loginIdentityFor])

  const connectionKeyFor = useCallback((connection: WebSocketConnection) => (
    `${connection.identity}|${loginIdentityFor(connection)}`
  ), [loginIdentityFor])

  const releaseAttemptBindings = useCallback((clientMessageId: string) => {
    attemptTimezonesRef.current.delete(clientMessageId)
    attemptUploadsRef.current.delete(clientMessageId)
  }, [])

  const rejectPendingDeliveries = useCallback((
    error: Error,
    matches: (pending: PendingDelivery) => boolean = () => true,
  ) => {
    for (const [clientMessageId, pending] of pendingDeliveriesRef.current) {
      if (!matches(pending)) continue
      clearTimeout(pending.timeout)
      pending.reject(error)
      pendingDeliveriesRef.current.delete(clientMessageId)
    }
  }, [])

  const rejectPreparations = useCallback((
    error: Error,
    matches: (claim: MessagePreparationClaim) => boolean = () => true,
  ) => {
    for (const [clientMessageId, claim] of preparationsRef.current) {
      if (!matches(claim)) continue
      if (preparationsRef.current.get(clientMessageId) !== claim) continue
      preparationsRef.current.delete(clientMessageId)
      claim.cancel(error)
    }
  }, [])

  const clearRecentMessages = useCallback((
    matches: (recent: RecentMessage) => boolean = () => true,
  ) => {
    recentMessagesRef.current = recentMessagesRef.current.filter(
      recent => !matches(recent),
    )
  }, [])

  const clearRetryTimers = useCallback((
    matches: (retry: ScheduledRetry) => boolean = () => true,
  ) => {
    for (const [timer, retry] of retryTimersRef.current) {
      if (!matches(retry)) continue
      clearTimeout(timer)
      retryTimersRef.current.delete(timer)
    }
  }, [])

  const invalidateLifecycle = useCallback(() => {
    lifecycleEpochRef.current++
    lifecycleEndedRef.current = false
    clearRetryTimers()
  }, [clearRetryTimers])

  const isCurrentLifecycle = useCallback((
    lifecycleEpoch: number,
  ) => (
    mountedRef.current
    && lifecycleEpochRef.current === lifecycleEpoch
  ), [])

  // Socket callbacks require this exact owner. Async refresh/retry work may
  // outlive retirement, so it is fenced by the narrower attempt predicate.
  const isCurrentOwner = useCallback((owner: SocketOwner) => (
    isCurrentLifecycle(owner.lifecycleEpoch)
    && socketOwnerRef.current === owner
    && socketRef.current === owner.socket
  ), [isCurrentLifecycle])

  const isCurrentAttempt = useCallback((owner: SocketOwner) => (
    isCurrentLifecycle(owner.lifecycleEpoch)
    && attemptEpochRef.current === owner.attemptEpoch
  ), [isCurrentLifecycle])

  const canApplyRetiredOwnerPolicy = useCallback((owner: SocketOwner) => (
    isCurrentAttempt(owner)
    && socketOwnerRef.current === null
    && socketRef.current === null
  ), [isCurrentAttempt])

  const isCurrentSocket = useCallback((socket: WebSocket, identity: string) => {
    const owner = socketOwnerRef.current
    return Boolean(
      owner
      && owner.socket === socket
      && owner.connection.identity === identity
      && isCurrentOwner(owner),
    )
  }, [isCurrentOwner])

  const notifyDisconnect = useCallback((owner: SocketOwner) => {
    if (owner.disconnectNotified) return
    owner.disconnectNotified = true
    try {
      owner.callbacks.onDisconnect?.()
    } catch {
      console.error("WebSocket disconnect handler failed")
    }
  }, [])

  const reportPermanentFailure = useCallback((
    owner: SocketOwner,
    error: Error,
  ) => {
    if (!canApplyRetiredOwnerPolicy(owner)) return
    setConnectionError(error)
    reportConnectionFailure(owner.callbacks, {
      recoverable: false,
      error,
    }, owner.connection.identity)
  }, [canApplyRetiredOwnerPolicy])

  const retireOwnerCore = useCallback((
    owner: SocketOwner,
    options: OwnerRetirementOptions,
  ) => {
    if (owner.handshakeTimer) {
      clearTimeout(owner.handshakeTimer)
      owner.handshakeTimer = null
    }
    if (owner.deadTimer) {
      clearTimeout(owner.deadTimer)
      owner.deadTimer = null
    }
    const wasCurrent = (
      socketOwnerRef.current === owner
      && socketRef.current === owner.socket
    )
    if (wasCurrent) {
      clearRetryTimers(retry => (
        retry.lifecycleEpoch === owner.lifecycleEpoch
        && retry.attemptEpoch === owner.attemptEpoch
      ))
      socketRef.current = null
      socketOwnerRef.current = null
      if (mountedRef.current) setIsConnected(false)
      isConnectingRef.current = false
      // Without heartbeats, staying open for a full dead window proves health.
      if (
        !owner.heartbeatEnabled
        && owner.openedAt !== null
        && Date.now() - owner.openedAt >= DEAD_AFTER_MS
      ) {
        reconnectAttemptsRef.current = 0
      }
      if (!options.keepsLifecycle) lifecycleEndedRef.current = true
    }
    rejectPendingDeliveries(
      options.pendingError,
      pending => (
        pending.socket === owner.socket
        && pending.descriptorKey === owner.descriptorKey
        && pending.lifecycleEpoch === owner.lifecycleEpoch
        && pending.attemptEpoch === owner.attemptEpoch
      ),
    )
    rejectPreparations(
      options.preparationError,
      claim => (
        claim.socket === owner.socket
        && claim.descriptorKey === owner.descriptorKey
        && claim.lifecycleEpoch === owner.lifecycleEpoch
        && claim.attemptEpoch === owner.attemptEpoch
      ),
    )
    clearRecentMessages(
      recent => (
        recent.descriptorKey === owner.descriptorKey
        && recent.lifecycleEpoch === owner.lifecycleEpoch
        && recent.attemptEpoch === owner.attemptEpoch
      ),
    )
    return wasCurrent
  }, [
    clearRecentMessages,
    clearRetryTimers,
    rejectPendingDeliveries,
    rejectPreparations,
  ])

  const retireOwner = useCallback((
    owner: SocketOwner,
    options: OwnerRetirementOptions,
  ) => {
    const wasCurrent = retireOwnerCore(owner, options)
    if (!wasCurrent) return false

    if (
      options.close
      && owner.socket.readyState !== WebSocket.CLOSED
    ) {
      try {
        owner.socket.close(options.close.code, options.close.reason)
      } catch {
        console.error("WebSocket close failed")
      }
    }
    if (options.notifyDisconnect) notifyDisconnect(owner)
    return true
  }, [
    notifyDisconnect,
    retireOwnerCore,
  ])

  const scheduleRetry = useCallback((
    callback: () => void,
    delay: number,
    lifecycleEpoch: number,
    attemptEpoch: number,
  ) => {
    const fire = () => {
      retryTimersRef.current.delete(timer)
      syncPhase() // even a stale timer changed the facts by removing itself
      if (
        !isCurrentLifecycle(lifecycleEpoch)
        || attemptEpochRef.current !== attemptEpoch
      ) return
      callback()
      syncPhase()
    }
    const timer = setTimeout(fire, delay)
    retryTimersRef.current.set(timer, { lifecycleEpoch, attemptEpoch, fire })
  }, [isCurrentLifecycle, syncPhase])

  // Every key is retried on a timer, including a first connection that failed
  // in transit, so a chat page loaded while the backend is down connects once
  // it is back. Before the socket opens, a 1006 can also be a rejected
  // handshake, but /ws/chat accepts before denying task access (4003,
  // permanent). What it still rejects before accepting is a missing or
  // rejected credential and an authentication outage (503); retrying the
  // former costs one handshake per back-off step until the page signs in again.
  const scheduleReconnect = useCallback((owner: SocketOwner) => {
    if (isSessionConnection(owner.connection) || !owner.connection.taskId) return
    if (!canApplyRetiredOwnerPolicy(owner)) return
    const attempt = ++reconnectAttemptsRef.current
    scheduleRetry(
      () => connectRef.current(),
      reconnectDelayMs(attempt, Math.random()),
      owner.lifecycleEpoch,
      owner.attemptEpoch,
    )
  }, [canApplyRetiredOwnerPolicy, scheduleRetry])

  const retireDeadOwner = useCallback((owner: SocketOwner, reason: string) => {
    if (!isCurrentOwner(owner)) return
    if (owner.sharedTaskId !== undefined) {
      owner.callbacks.onMessage?.({
        type: "stream_unavailable", task_id: owner.sharedTaskId,
        data: {}, timestamp: new Date().toISOString(),
      })
    }
    const wasCurrent = retireOwner(owner, {
      pendingError: deliveryError("Connection lost before the message was accepted.", "outcome_unknown", { connectionLost: true }),
      preparationError: deliveryError("Connection lost before the message was prepared.", "not_sent"),
      close: { code: 1000, reason: "Connection liveness timeout" },
      notifyDisconnect: true,
    })
    if (!wasCurrent || socketOwnerRef.current || socketRef.current) return
    const livenessError = new Error(reason)
    setConnectionError(livenessError)
    reportConnectionFailure(owner.callbacks, {
      recoverable: true,
      error: livenessError,
    }, owner.connection.identity)
    scheduleReconnect(owner)
  }, [isCurrentOwner, retireOwner, scheduleReconnect])

  // Not re-armed per frame: on firing it sleeps for the rest of the dead window.
  const watchLiveness = useCallback((owner: SocketOwner) => {
    const arm = (delay: number) => {
      owner.deadTimer = setTimeout(withPhaseSync(() => {
        owner.deadTimer = null
        if (!isCurrentOwner(owner)) return
        const remaining = DEAD_AFTER_MS - (Date.now() - (owner.lastFrameAt ?? 0))
        if (remaining > 0) {
          arm(remaining)
          return
        }
        retireDeadOwner(owner, "WebSocket connection stopped delivering frames.")
      }), delay)
    }
    arm(DEAD_AFTER_MS)
  }, [isCurrentOwner, retireDeadOwner, withPhaseSync])

  // A page that becomes visible again or a network that comes back online
  // retries once now instead of waiting out a back-off of up to five minutes.
  // A failure continues the back-off where it was.
  const retryNow = useCallback(() => {
    if (!mountedRef.current) return
    const owner = socketOwnerRef.current
    if (owner) {
      // Background tabs throttle timers, so the dead timer may not have fired.
      const lastFrameAt = owner.lastFrameAt ?? owner.openedAt
      if (
        !owner.heartbeatEnabled
        || lastFrameAt === null
        || Date.now() - lastFrameAt < DEAD_AFTER_MS
      ) return
      retireDeadOwner(owner, "WebSocket connection stopped delivering frames.")
      if (socketOwnerRef.current) return
    }
    const lifecycleEpoch = lifecycleEpochRef.current
    const attemptEpoch = attemptEpochRef.current
    for (const [timer, retry] of retryTimersRef.current) {
      if (
        retry.lifecycleEpoch !== lifecycleEpoch
        || retry.attemptEpoch !== attemptEpoch
      ) continue
      clearTimeout(timer)
      retry.fire()
      return
    }
  }, [retireDeadOwner])

  useEffect(() => {
    if (typeof window === "undefined") return
    const onVisibilityChange = withPhaseSync(() => {
      if (document.visibilityState === "visible") retryNow()
    })
    const onOnline = withPhaseSync(retryNow)
    document.addEventListener("visibilitychange", onVisibilityChange)
    window.addEventListener("online", onOnline)
    return () => {
      document.removeEventListener("visibilitychange", onVisibilityChange)
      window.removeEventListener("online", onOnline)
    }
  }, [retryNow, withPhaseSync])

  useIsomorphicLayoutEffect(() => {
    mountedRef.current = true
    return () => {
      mountedRef.current = false
      invalidateLifecycle()
    }
  }, [invalidateLifecycle])

  useIsomorphicLayoutEffect(() => {
    const previousDescriptorKey = descriptorKeyRef.current
    const previousIdentity = deliveryIdentityRef.current
    const previousGeneration = deliveryGenerationRef.current
    const nextIdentity = normalizedConnection?.identity ?? null
    const nextAuthSessionId = getInternalSessionId(normalizedConnection)

    if (previousDescriptorKey !== connectionDescriptorIdentity) {
      invalidateLifecycle()
      if (normalizedConnection !== null) {
        // The generation moves only here, never during render.
        const previousPrincipal = loginPrincipalRef.current
        if (
          previousPrincipal !== null
          && !isSameLoginPrincipal(previousPrincipal, normalizedConnection)
        ) {
          loginGenerationRef.current++
        }
        loginPrincipalRef.current = normalizedConnection
      }
      if (previousDescriptorKey !== null) {
        rejectPreparations(
          deliveryError("Message not sent: the connection changed before delivery.", "not_sent"),
          claim => claim.descriptorKey === previousDescriptorKey,
        )
      }
    }

    if (
      nextAuthSessionId !== null
      && nextAuthSessionId !== authRefreshRetryBudgetSessionIdRef.current
    ) {
      authRefreshRetriesRef.current = 0
      authRefreshRetryBudgetSessionIdRef.current = nextAuthSessionId
    }

    if (
      previousIdentity !== null
      && previousIdentity === nextIdentity
      && previousGeneration !== deliveryGeneration
    ) {
      rejectPendingDeliveries(
        deliveryError("Message delivery generation changed before acknowledgement.", "outcome_unknown"),
        pending => (
          pending.connectionIdentity === previousIdentity
          && pending.deliveryGeneration === previousGeneration
        ),
      )
      rejectPreparations(
        deliveryError("Message delivery generation changed before preparation completed.", "not_sent"),
        claim => (
          claim.connectionIdentity === previousIdentity
          && claim.deliveryGeneration === previousGeneration
        ),
      )
      clearRecentMessages(
        recent => (
          recent.connectionIdentity === previousIdentity
          && recent.deliveryGeneration === previousGeneration
        ),
      )
    }

    descriptorKeyRef.current = connectionDescriptorIdentity
    connectionRef.current = normalizedConnection
    autoConnectRef.current = autoConnect
    taskIdRef.current = taskId
    deliveryIdentityRef.current = nextIdentity
    deliveryGenerationRef.current = deliveryGeneration
    legacyErrorProseRef.current = legacyErrorProse
    callbacksRef.current = {
      onConnectionClose,
      onConnectionFailure,
      onSessionConnectionClose,
      onSessionConnectionFailure,
      onConnect,
      onConnectionCapabilities,
      onDisconnect,
      onError,
      onMessage,
    }
    refreshAccessTokenRef.current = refreshAccessToken
  })

  // Update token ref when token changes
  useEffect(() => {
    tokenRef.current = token !== undefined ? token : authToken
  }, [token, authToken])

  const connect = useCallback(() => {
    stoppedByCallerRef.current = false
    if (!mountedRef.current) return
    if (
      isConnectingRef.current
      || (
        socketRef.current
        && socketRef.current.readyState < WebSocket.CLOSING
      )
    ) return

    const connection = connectionRef.current
    const descriptorKey = descriptorKeyRef.current
    if (!connection) return
    if (!descriptorKey) return
    if (connection.chatTaskIdMode === "required" && !connection.taskId) return

    const previousOwner = socketOwnerRef.current
    if (previousOwner) {
      retireOwner(previousOwner, {
        pendingError: deliveryError("Connection replaced before the message was accepted.", "outcome_unknown", { connectionLost: true }),
        preparationError: deliveryError("Connection replaced before the message was prepared.", "not_sent"),
        close: {
          code: 1000,
          reason: "Connection replaced",
        },
        notifyDisconnect: true,
      })
      if (socketOwnerRef.current || isConnectingRef.current) return
    } else if (socketRef.current) {
      socketRef.current = null
    }

    isConnectingRef.current = true
    try {
      // Test if the URL is valid before creating WebSocket
      if (!connection.url.startsWith('ws://') && !connection.url.startsWith('wss://')) {
        throw new Error("Invalid WebSocket URL configuration")
      }

      const attemptEpoch = ++attemptEpochRef.current
      const protocols = getConnectionProtocols(connection, taskIdRef.current)
      const socket = protocols
        ? new WebSocket(connection.url, protocols)
        : new WebSocket(connection.url)
      const owner: SocketOwner = {
        callbacks: callbacksRef.current,
        connection,
        descriptorKey,
        disconnectNotified: false,
        handshakeTimer: null,
        lifecycleEpoch: lifecycleEpochRef.current,
        attemptEpoch,
        refreshAccessToken: refreshAccessTokenRef.current,
        socket,
        connectionKey: connectionKeyFor(connection),
        openedAt: null,
        firstFrameAt: null,
        lastFrameAt: null,
        framesReceived: 0,
        heartbeatEnabled: false,
        deadTimer: null,
        sharedTaskId: undefined,
      }
      socketRef.current = socket
      socketOwnerRef.current = owner

      owner.handshakeTimer = setTimeout(withPhaseSync(() => {
        if (!isCurrentOwner(owner)) return
        const handshakeError = new Error("WebSocket connection handshake timed out.")
        const wasCurrent = retireOwner(owner, {
          pendingError: deliveryError("Connection timed out before the message was accepted.", "outcome_unknown", { connectionLost: true }),
          preparationError: deliveryError("Connection timed out before the message was prepared.", "not_sent"),
          close: { code: 1000, reason: "Handshake timeout" },
          notifyDisconnect: true,
        })
        if (!wasCurrent || socketOwnerRef.current || socketRef.current) return
        setConnectionError(handshakeError)
        reportConnectionFailure(owner.callbacks, {
          recoverable: true,
          error: handshakeError,
        }, owner.connection.identity)
        scheduleReconnect(owner)
      }), HANDSHAKE_TIMEOUT_MS)

      socket.onopen = withPhaseSync(() => {
        if (!isCurrentOwner(owner)) return
        if (owner.handshakeTimer) {
          clearTimeout(owner.handshakeTimer)
          owner.handshakeTimer = null
        }
        if (connection.expectedProtocol && socket.protocol !== connection.expectedProtocol) {
          const protocolError = new Error("WebSocket subprotocol negotiation failed.")
          // A protocol mismatch is reported as a terminal connection failure;
          // suppressing disconnect avoids starting a second recovery path.
          const wasCurrent = retireOwner(owner, {
            pendingError: deliveryError("Connection closed before the message was accepted.", "outcome_unknown", { connectionLost: true }),
            preparationError: deliveryError("Connection closed before the message was prepared.", "not_sent"),
            close: { code: 1002, reason: "WebSocket subprotocol mismatch" },
            notifyDisconnect: false,
          })
          if (!wasCurrent) return
          setConnectionError(protocolError)
          reportConnectionFailure(owner.callbacks, {
            recoverable: false,
            error: protocolError,
          }, owner.connection.identity)
          return
        }

        owner.openedAt = Date.now()
        openedKeysRef.current.add(owner.connectionKey)
        setIsConnected(true)
        setConnectionError(null)
        isConnectingRef.current = false
        owner.callbacks.onConnect?.(owner.connection.taskId)
      })

      socket.onclose = withPhaseSync((event: CloseEvent) => {
        if (!isCurrentOwner(owner)) return
        if (owner.sharedTaskId !== undefined) {
          owner.callbacks.onMessage?.({
            type: "stream_unavailable", task_id: owner.sharedTaskId,
            data: {}, timestamp: new Date().toISOString(),
          })
        }

        const wasCurrent = retireOwnerCore(owner, {
          pendingError: deliveryError("Connection closed before the message was accepted.", "outcome_unknown", { connectionLost: true }),
          preparationError: deliveryError("Connection closed before the message was prepared.", "not_sent"),
          notifyDisconnect: false,
        })
        if (!wasCurrent) return

        let closeDisposition: "handled" | "default"
        try {
          closeDisposition = owner.callbacks.onSessionConnectionClose
            ? owner.callbacks.onSessionConnectionClose(event, owner.connection.identity)
            : owner.callbacks.onConnectionClose?.(event) ?? "default"
        } catch {
          if (canApplyRetiredOwnerPolicy(owner)) {
            const handlerError = new Error("WebSocket close handler failed.")
            console.error("WebSocket close handler failed")
            reportPermanentFailure(owner, handlerError)
          }
          return
        }

        if (!canApplyRetiredOwnerPolicy(owner)) return
        if (closeDisposition === "handled") return

        notifyDisconnect(owner)
        if (!canApplyRetiredOwnerPolicy(owner)) return

        const disposition = classifyClose(event)
        if (disposition === "reauthenticate") {
          if (owner.connection.credentialOwner.kind !== "auth-context") {
            reportPermanentFailure(owner, new Error("Authentication failed"))
            return
          }
          if (!owner.connection.credentialOwner.session) {
            reportPermanentFailure(owner, new Error("Authentication lineage is unavailable"))
            return
          }
          if (authRefreshRetriesRef.current >= MAX_AUTH_REFRESH_RETRIES) {
            reportPermanentFailure(
              owner,
              new Error("Authentication failed after token refresh retries"),
            )
            return
          }
          authRefreshRetriesRef.current += 1
          try {
            owner.refreshAccessToken(
              owner.connection.credentialOwner.session,
            )
              .then((refreshSuccess) => {
                if (!canApplyRetiredOwnerPolicy(owner)) return
                if (refreshSuccess) {
                  scheduleRetry(
                    connect,
                    1000,
                    owner.lifecycleEpoch,
                    owner.attemptEpoch,
                  )
                } else {
                  reportPermanentFailure(
                    owner,
                    new Error("Authentication failed and token refresh failed"),
                  )
                }
                syncPhase()
              })
              .catch(() => {
                if (!canApplyRetiredOwnerPolicy(owner)) return
                console.error("Error refreshing auth token for WebSocket")
                reportPermanentFailure(
                  owner,
                  new Error("Authentication failed and token refresh error"),
                )
                syncPhase()
              })
          } catch {
            if (!canApplyRetiredOwnerPolicy(owner)) return
            console.error("Error refreshing auth token for WebSocket")
            reportPermanentFailure(
              owner,
              new Error("Authentication failed and token refresh error"),
            )
          }
          return
        }

        if (disposition === "permanent") {
          reportPermanentFailure(
            owner,
            new Error(
              event.reason
              || (event.code === 4003
                ? "Access denied"
                : `WebSocket closed with code ${event.code}`),
            ),
          )
          return
        }

        if (disposition === "intentional") return

        scheduleReconnect(owner)
      })

      socket.onerror = withPhaseSync(() => {
        if (!isCurrentOwner(owner)) return
        console.error("WebSocket error")
        const connectionError = new Error("WebSocket connection failed. The backend WebSocket endpoint may not be available.")
        const wasCurrent = retireOwner(owner, {
          pendingError: deliveryError("Connection failed before the message was accepted.", "outcome_unknown", { connectionLost: true }),
          preparationError: deliveryError("Connection failed before the message was prepared.", "not_sent"),
          close: { code: 1000, reason: "WebSocket transport error" },
          notifyDisconnect: true,
        })
        if (!wasCurrent || socketOwnerRef.current || socketRef.current) return
        setConnectionError(connectionError)
        reportConnectionFailure(owner.callbacks, {
          recoverable: true,
          error: connectionError,
        }, owner.connection.identity)
        scheduleReconnect(owner)
      })

      socket.onmessage = (event) => {
        if (!isCurrentOwner(owner)) return
        // Every frame is proof of life, even unparsable and liveness frames.
        const receivedAt = Date.now()
        owner.lastFrameAt = receivedAt
        owner.framesReceived += 1
        owner.firstFrameAt ??= receivedAt
        // Traffic spanning a full dead window restarts the back-off.
        if (owner.heartbeatEnabled && receivedAt - owner.firstFrameAt >= DEAD_AFTER_MS) {
          reconnectAttemptsRef.current = 0
        }
        try {
          const data = JSON.parse(event.data)
          if (data.type === "connection_capabilities") {
            if (
              Array.isArray(data.capabilities)
              && data.capabilities.includes("heartbeat")
              && !owner.heartbeatEnabled
            ) {
              owner.heartbeatEnabled = true
              watchLiveness(owner)
            }
            owner.callbacks.onConnectionCapabilities?.(
              Array.isArray(data.capabilities)
                ? data.capabilities.filter((entry: unknown): entry is string => typeof entry === "string")
                : [],
            )
            return
          }
          if (data.type === "heartbeat") return
          if (data.type === "task_stream_snapshot" || data.stream_run_id !== undefined) {
            owner.sharedTaskId = data.task_id
          }

          if (data.type === 'message_accepted' || data.type === 'message_rejected') {
            const clientMessageId = data.client_message_id
            const pending = typeof clientMessageId === 'string'
              ? pendingDeliveriesRef.current.get(clientMessageId)
              : undefined
            if (
              pending
              && pending.socket === socket
              && pending.descriptorKey === owner.descriptorKey
              && pending.lifecycleEpoch === owner.lifecycleEpoch
              && pending.attemptEpoch === owner.attemptEpoch
              && pending.deliveryGeneration === deliveryGenerationRef.current
            ) {
              clearTimeout(pending.timeout)
              pendingDeliveriesRef.current.delete(clientMessageId)
              if (
                data.type === 'message_accepted'
                || data.rejection_outcome === "not_accepted"
              ) {
                // Terminal for this id: accepted, or rejected without a
                // same-id retry. An unknown outcome keeps the binding.
                releaseAttemptBindings(clientMessageId)
              }
              if (data.type === 'message_accepted') {
                pending.resolve({
                  client_message_id: clientMessageId,
                  turn_id: typeof data.turn_id === 'string' ? data.turn_id : clientMessageId,
                })
              } else {
                const hasErrorCode = Object.prototype.hasOwnProperty.call(data, "error_code")
                const errorCode = readServerRejectionCode(data.error_code)
                const hasLegacyRejectionMessage = (
                  typeof data.message === "string"
                  && data.message.trim() !== ""
                )
                const trustLegacyRejectionMessage = (
                  !hasErrorCode
                  && legacyErrorProseRef.current === "trusted"
                  && hasLegacyRejectionMessage
                )
                const rejectionMessage = errorCode
                  ? clientErrorFallback(errorCode)
                  : hasErrorCode
                    ? "Message was rejected."
                    : trustLegacyRejectionMessage
                      ? data.message
                      : "Message was rejected."
                const disposition: MessageDeliveryDisposition = (
                  data.rejection_outcome === "not_accepted"
                    ? "rejected"
                    : "outcome_unknown"
                )
                // A definitive rejection with no usable server code still gets
                // wording of its own; an unknown outcome takes the default
                // code from the error constructor.
                const displayCode = errorCode ?? (
                  !trustLegacyRejectionMessage && disposition === "rejected"
                    ? "message_not_accepted"
                    : null
                )
                pending.reject(deliveryError(
                  rejectionMessage,
                  disposition,
                  {
                    retryWithNewId: data.retry_with_new_id === true,
                    userFacing: errorCode !== null || trustLegacyRejectionMessage,
                    errorCode: displayCode,
                  },
                ))
              }
            } else if (
              typeof clientMessageId === 'string'
              && !pending
              && !preparationsRef.current.has(clientMessageId)
              && (
                data.type === 'message_accepted'
                || data.rejection_outcome === "not_accepted"
              )
            ) {
              // Terminal ack that arrived after the 30s timeout already dropped
              // the pending entry. isCurrentOwner (top of onmessage) fences stale
              // sockets, and no same-id retry is in flight, so the binding can
              // never be reused; release it. outcome_unknown is excluded so a
              // still-allowed same-id retry keeps its first attempt's zone.
              releaseAttemptBindings(clientMessageId)
              // The durable queue acknowledges the send before the worker
              // reviews it. Surface a later refusal as a non-terminal notice.
              if (data.type === "message_rejected" && isInputReviewErrorCode(data.error_code)) {
                data.type = "error"
              }
            }
            if (data.type !== "error") return
          }

          // Handle different message types from the backend
          let message: WebSocketMessage

          if (isFinalAnswerStreamEventType(data.type)) {
            message = {
              type: data.type,
              data,
              timestamp: data.timestamp || new Date().toISOString(),
              task_id: data.task_id,
              event_id: data.event_id,
              message_id: data.message_id,
              delta: data.delta,
              content: data.content,
            }
          } else if (data.type === "trace_event") {
            // Ensure data.data is not an empty string
            const safeData = typeof data.data === 'string' && data.data === ''
              ? {}
              : data.data;

            message = {
              type: "trace_event",
              data: safeData,
              timestamp: data.timestamp,
              task_id: data.task_id,
              step_id: data.step_id,
              event_id: data.event_id,
              event_type: data.event_type,  // Keep event_type field!
            }
          } else if (data.type === "task_completed") {
            message = {
              type: "task_completed",
              data: data,
              timestamp: data.timestamp,
              task_id: data.task?.id || data.task_id,
            }
          } else if (data.type === "dag_execution") {
            // Ensure data.data is not an empty string
            const safeData = typeof data.data === 'string' && data.data === ''
              ? {}
              : data.data;

            message = {
              type: "dag_execution",
              data: safeData,
              timestamp: data.timestamp,
              task_id: data.task_id,
            }
          } else if (data.type === "dag_step_info") {
            // Ensure data.data is not an empty string
            const safeData = typeof data.data === 'string' && data.data === ''
              ? {}
              : data.data;

            message = {
              type: "dag_step_info",
              data: safeData,
              timestamp: data.timestamp,
              task_id: data.task_id,
              step_id: safeData?.id,
            }
          } else if (data.type === "task_paused") {
            message = {
              type: "task_paused",
              data: data,
              timestamp: data.timestamp,
              task_id: data.task_id,
            }
          } else if (data.type === "task_waiting_for_user") {
            message = {
              type: "task_waiting_for_user",
              data: data,
              timestamp: data.timestamp,
              task_id: data.task_id,
            }
          } else if (data.type === "task_resumed") {
            message = {
              type: "task_resumed",
              data: data,
              timestamp: data.timestamp,
              task_id: data.task_id,
            }
          } else if (data.type === "agent_error") {
            message = {
              type: "agent_error",
              data: data,
              timestamp: data.timestamp,
              task_id: data.task_id,
            }
          } else if (data.type === "historical_data_complete") {
            message = {
              type: "historical_data_complete",
              data: data,
              timestamp: data.timestamp,
              task_id: data.task_id,
            }
          } else {
            // Generic message handling
            const messageData = data.data || data;
            // Ensure we don't pass empty strings where objects are expected
            const safeData = typeof messageData === 'string' && messageData === ''
              ? {}
              : messageData;

            message = {
              type: data.type || "message",
              data: safeData,
              timestamp: data.timestamp || new Date().toISOString(),
              task_id: data.task_id,
              step_id: data.step_id,
            }
          }

          // Preserve the canonical task-control envelope even when a message
          // type normalizes its payload into ``data`` above.
          message.run_id = data.run_id
          message.stream_run_id = data.stream_run_id
          message.stream_attempt_id = data.stream_attempt_id
          message.state_version = data.state_version
          message.control_state = data.control_state
          message.status = data.status
          message.task = data.task

          setLastMessage(message)
          owner.callbacks.onMessage?.(message)
        } catch (error) {
          console.error("Error parsing WebSocket message", error)
        }
      }

    } catch {
      console.error("Failed to create WebSocket connection")
      const connectionError = new Error("Failed to create WebSocket connection.")
      isConnectingRef.current = false
      lifecycleEndedRef.current = true
      setConnectionError(connectionError)
      reportConnectionFailure(callbacksRef.current, {
        recoverable: false,
        error: connectionError,
      }, connectionRef.current?.identity)
    }
  }, [
    canApplyRetiredOwnerPolicy,
    connectionKeyFor,
    isCurrentOwner,
    notifyDisconnect,
    releaseAttemptBindings,
    reportPermanentFailure,
    retireOwner,
    retireOwnerCore,
    scheduleReconnect,
    scheduleRetry,
    syncPhase,
    watchLiveness,
    withPhaseSync,
  ])

  useIsomorphicLayoutEffect(() => {
    connectRef.current = connect
  }, [connect])

  // Timers and effects run `connect` and recompute the phase themselves. A
  // caller's connect starts a new cycle, so an earlier failure, or a retry it
  // left waiting, no longer makes the new attempt read as reconnecting.
  const connectFromCaller = useMemo(() => withPhaseSync(() => {
    lifecycleEndedRef.current = false
    clearRetryTimers()
    connect()
  }), [clearRetryTimers, connect, withPhaseSync])

  const disconnect = useCallback(() => {
    const owner = socketOwnerRef.current
    invalidateLifecycle()
    stoppedByCallerRef.current = true
    reconnectAttemptsRef.current = 0
    if (owner) {
      retireOwner(owner, {
        pendingError: deliveryError("Disconnected before the message was accepted.", "outcome_unknown"),
        preparationError: deliveryError("Disconnected before the message was prepared.", "not_sent"),
        close: {},
        notifyDisconnect: true,
        keepsLifecycle: true,
      })
    } else {
      rejectPendingDeliveries(
        deliveryError("Disconnected before the message was accepted.", "outcome_unknown"),
      )
      rejectPreparations(
        deliveryError("Disconnected before the message was prepared.", "not_sent"),
      )
    }
    setIsConnected(false)
    isConnectingRef.current = false
    syncPhase()
  }, [
    invalidateLifecycle,
    rejectPendingDeliveries,
    rejectPreparations,
    retireOwner,
    syncPhase,
  ])

  const sendMessage = useCallback((
    message: Record<string, unknown>,
  ): WebSocketSendResult => {
    const connection = connectionRef.current
    const socket = socketRef.current
    if (
      connection
      && socket?.readyState === WebSocket.OPEN
      && isCurrentSocket(socket, connection.identity)
    ) {
      try {
        socket.send(JSON.stringify(message))
        return "sent"
      } catch {
        return "not_sent"
      }
    }
    return "not_sent"
  }, [isCurrentSocket])

  const sendChatMessage = useCallback(async (
    message: string,
    files?: File[],
    force: boolean = false,
    requestedClientMessageId?: string,
    requestId?: string,
    attachments?: ChatMessageFileIds,
    // The earlier conversation a new one continues from; the same on every
    // attempt of one send.
    sourceTaskId?: number,
  ): Promise<MessageDeliveryAck> => {
    const timestamp = Date.now()
    const owner = socketOwnerRef.current
    const connection = owner?.connection
    const socket = owner?.socket
    if (
      !connection
      || socket?.readyState !== WebSocket.OPEN
      || !owner
      || !isCurrentOwner(owner)
      || (connection.chatTaskIdMode === "required" && !connection.taskId)
    ) {
      throw deliveryError(
        "Message not sent: the connection is not ready.",
        "not_sent",
        { errorCode: "connection_not_ready" },
      )
    }
    // Raw File objects cannot be delivered on this kind of connection; files
    // uploaded beforehand travel as ids through `attachments`.
    if (connection.chatTaskIdMode === "omit" && files && files.length > 0) {
      throw deliveryError("File delivery is not supported for this connection.", "not_sent")
    }
    // The server closes the connection on a frame that carries file ids it
    // cannot accept, so every shape it refuses is refused here first.
    const fileIds = attachments?.fileIds && attachments.fileIds.length > 0
      ? attachments.fileIds
      : null
    if (fileIds) {
      const maxFileIds = attachments?.maxFileIds
      if (connection.chatTaskIdMode !== "omit") {
        throw deliveryError("File ids are not supported for this connection.", "not_sent")
      }
      if (requestId) {
        throw deliveryError("Files cannot accompany an answer to a request.", "not_sent")
      }
      if (maxFileIds === undefined || fileIds.length > maxFileIds) {
        throw deliveryError("Message not sent: too many files attached.", "not_sent")
      }
      if (!fileIds.every(isCanonicalUuid)) {
        throw deliveryError("Message not sent: an attached file id is not valid.", "not_sent")
      }
    }
    // The server closes the connection on a frame whose conversation source is
    // malformed or arrives together with a request id, so those frames are
    // refused here first.
    if (sourceTaskId !== undefined) {
      if (connection.chatTaskIdMode !== "omit") {
        throw deliveryError("A conversation source is not supported for this connection.", "not_sent")
      }
      if (requestId) {
        throw deliveryError("A conversation source cannot accompany an answer to a request.", "not_sent")
      }
      if (
        !Number.isInteger(sourceTaskId)
        || sourceTaskId < 1
        || sourceTaskId > MAX_SOURCE_TASK_ID
      ) {
        throw deliveryError("Message not sent: the conversation source is not valid.", "not_sent")
      }
    }

    const currentTaskId = connection.taskId
    const currentDeliveryGeneration = deliveryGenerationRef.current
    const currentDescriptorKey = owner.descriptorKey
    const currentLifecycleEpoch = owner.lifecycleEpoch
    const currentAttemptEpoch = owner.attemptEpoch
    const clientMessageId = requestedClientMessageId || generateClientMessageId()
    if (
      pendingDeliveriesRef.current.has(clientMessageId)
      || preparationsRef.current.has(clientMessageId)
    ) {
      throw deliveryError("Message not sent: the client message id is already pending.", "not_sent")
    }
    const duplicateMessage = recentMessagesRef.current.find(
      msg => (
        msg.descriptorKey === currentDescriptorKey
        && msg.lifecycleEpoch === currentLifecycleEpoch
        && msg.attemptEpoch === currentAttemptEpoch
        && msg.deliveryGeneration === currentDeliveryGeneration
        && msg.message === message
        && msg.clientMessageId !== clientMessageId
        && (timestamp - msg.timestamp) < MESSAGE_DUPLICATE_THRESHOLD
      )
    )
    const duplicateIsPending = duplicateMessage
      ? pendingDeliveriesRef.current.has(duplicateMessage.clientMessageId)
      : false
    if (!force && duplicateIsPending) {
      throw deliveryError("Duplicate message ignored while the previous send is pending.", "not_sent")
    }

    let rejectCancellation!: (error: Error) => void
    const cancellation = new Promise<never>((_resolve, reject) => {
      rejectCancellation = reject
    })
    const claim: MessagePreparationClaim = {
      cancellation,
      cancel: (error) => {
        if (claim.cancelled) return
        claim.cancelled = true
        rejectCancellation(error)
      },
      cancelled: false,
      connectionIdentity: connection.identity,
      descriptorKey: currentDescriptorKey,
      lifecycleEpoch: currentLifecycleEpoch,
      attemptEpoch: currentAttemptEpoch,
      deliveryGeneration: currentDeliveryGeneration,
      socket,
    }
    preparationsRef.current.set(clientMessageId, claim)

    // A binding made before this attempt belongs to an earlier attempt under
    // this id whose outcome is unknown; a later same-id retry still needs it, so
    // a failure of this attempt keeps it.
    const bindingsPredateAttempt = attemptTimezonesRef.current.has(clientMessageId)
    try {
      if (!bindingsPredateAttempt) {
        attemptTimezonesRef.current.set(clientMessageId, resolveReportedTimezone())
      }
      const reportedTimezone = attemptTimezonesRef.current.get(clientMessageId)
      const messageData: Record<string, unknown> = {
        type: 'chat',
        message,
        client_message_id: clientMessageId,
        ...(requestId ? { request_id: requestId } : {}),
        ...(fileIds ? { file_ids: [...fileIds] } : {}),
        ...(sourceTaskId !== undefined ? { source_task_id: sourceTaskId } : {}),
        ...(reportedTimezone ? { context: { timezone: reportedTimezone } } : {}),
        ...(connection.chatTaskIdMode === "required" ? { task_id: currentTaskId } : {}),
      }

      if (files && files.length > 0) {
        if (!currentTaskId) {
          throw deliveryError("File delivery requires a task-bound connection.", "not_sent")
        }
        type FileWithUploadId = File & { file_id?: string }
        const filesWithUploadIds = files as FileWithUploadId[]
        const filesToUpload = filesWithUploadIds.filter(file => !file.file_id)
        const preUploadedFiles = filesWithUploadIds
          .filter((file): file is FileWithUploadId & { file_id: string } => Boolean(file.file_id))
          .map(file => ({
            file_id: file.file_id,
            name: file.name,
            size: file.size,
            type: file.type || '',
          }))
        let uploadedFiles: Array<{ file_id: string; name?: string; size?: number; type?: string }> = []

        const cachedUpload = attemptUploadsRef.current.get(clientMessageId)
        const loginIdentity = loginIdentityFor(connection)
        if (
          cachedUpload?.taskId === currentTaskId
          && cachedUpload.loginIdentity === loginIdentity
          && filesToUpload.length > 0
        ) {
          uploadedFiles = cachedUpload.files
        } else if (filesToUpload.length > 0 && uploadFiles) {
          uploadedFiles = await Promise.race([
            uploadFiles(filesToUpload, {
              taskId: currentTaskId,
              taskType: 'task',
            }),
            claim.cancellation,
          ])
        } else if (filesToUpload.length > 0) {
          const uploadRequest = (async () => {
            const formData = new FormData()
            filesToUpload.forEach(file => formData.append('files', file))
            formData.append('task_type', 'task')
            formData.append('task_id', currentTaskId.toString())
            const response = await apiRequest(`${getUploadApiUrl()}/api/files/upload`, {
              method: 'POST',
              headers: {
                'Authorization': `Bearer ${tokenRef.current ?? localStorage.getItem('token') ?? ''}`,
              },
              body: formData,
            })
            const parsed = await parseApiResponse(response)
            const data = isJsonRecord(parsed.data) ? parsed.data : null
            if (
              !response.ok
              || data?.success !== true
              || !Array.isArray(data.files)
            ) {
              const uploadError = classifyUploadError(response, parsed)
              throw deliveryError(
                uploadError.message,
                "not_sent",
                {
                  userFacing: true,
                  errorCode: uploadError.errorCode,
                },
              )
            }
            const normalizedFileIds = normalizeUploadFileIds(
              data.files.map(file => isJsonRecord(file) ? file.file_id : undefined),
              filesToUpload.length,
            )
            if (!normalizedFileIds) {
              const uploadError = classifyUploadError(response, parsed)
              throw deliveryError(
                uploadError.message,
                "not_sent",
                { userFacing: true, errorCode: uploadError.errorCode },
              )
            }
            return data.files.map((file, index) => {
              const metadata = isJsonRecord(file) ? file : {}
              return {
                file_id: normalizedFileIds[index],
                name: typeof metadata.filename === 'string' ? metadata.filename : '',
                size: typeof metadata.file_size === 'number' ? metadata.file_size : 0,
                type: typeof metadata.mime_type === 'string' ? metadata.mime_type : '',
              }
            })
          })()
          uploadedFiles = await Promise.race([uploadRequest, claim.cancellation])
        }
        const normalizedUploadedFileIds = normalizeUploadFileIds(
          uploadedFiles.map(file => file.file_id),
          filesToUpload.length,
        )
        if (!normalizedUploadedFileIds) {
          throw deliveryError(
            clientErrorFallback("upload_failed"),
            "not_sent",
            { userFacing: true, errorCode: "upload_failed" },
          )
        }
        const normalizedUploadedFiles = uploadedFiles.map((file, index) => ({
          ...file,
          file_id: normalizedUploadedFileIds[index],
        }))
        if (filesToUpload.length > 0) {
          attemptUploadsRef.current.set(clientMessageId, { taskId: currentTaskId, loginIdentity, files: normalizedUploadedFiles })
        }
        const allFiles = [...preUploadedFiles, ...normalizedUploadedFiles]
        const normalizedFileIds = normalizeUploadFileIds(
          allFiles.map(file => file.file_id),
          filesWithUploadIds.length,
        )
        if (!normalizedFileIds) {
          throw deliveryError(
            clientErrorFallback("upload_failed"),
            "not_sent",
            { userFacing: true, errorCode: "upload_failed" },
          )
        }
        messageData.files = allFiles.map((file, index) => ({
          ...file,
          file_id: normalizedFileIds[index],
        }))
      }

      if (
        preparationsRef.current.get(clientMessageId) !== claim
        || claim.cancelled
        || socket.readyState !== WebSocket.OPEN
        || !isCurrentOwner(owner)
        || deliveryGenerationRef.current !== currentDeliveryGeneration
      ) {
        throw deliveryError("Message not sent: the connection changed before delivery.", "not_sent")
      }
      if (pendingDeliveriesRef.current.has(clientMessageId)) {
        throw deliveryError("Message not sent: the client message id is already pending.", "not_sent")
      }

      const delivery = new Promise<MessageDeliveryAck>((resolve, reject) => {
        const pendingDelivery: PendingDelivery = {
          resolve,
          reject,
          timeout: setTimeout(() => {
            if (pendingDeliveriesRef.current.get(clientMessageId) !== pendingDelivery) return
            if (
              isCurrentOwner(owner)
              && owner.framesReceived === pendingDelivery.framesReceivedAtSend
            ) {
              // No frame at all since the send: the link is dead, not slow.
              retireDeadOwner(owner, "WebSocket connection did not answer a sent message.")
            } else {
              pendingDeliveriesRef.current.delete(clientMessageId)
              reject(deliveryError("Message delivery was not acknowledged. Your draft was kept.", "outcome_unknown"))
            }
            syncPhase()
          }, 30000),
          connectionIdentity: connection.identity,
          descriptorKey: currentDescriptorKey,
          lifecycleEpoch: currentLifecycleEpoch,
          attemptEpoch: currentAttemptEpoch,
          deliveryGeneration: currentDeliveryGeneration,
          socket,
          framesReceivedAtSend: owner.framesReceived,
        }
        pendingDeliveriesRef.current.set(clientMessageId, pendingDelivery)
      })
      if (preparationsRef.current.get(clientMessageId) === claim) {
        preparationsRef.current.delete(clientMessageId)
      }

      try {
        socket.send(JSON.stringify(messageData))
      } catch (error) {
        const pending = pendingDeliveriesRef.current.get(clientMessageId)
        if (
          pending?.socket === socket
          && pending.descriptorKey === currentDescriptorKey
          && pending.lifecycleEpoch === currentLifecycleEpoch
          && pending.attemptEpoch === currentAttemptEpoch
          && pending.deliveryGeneration === currentDeliveryGeneration
        ) {
          clearTimeout(pending.timeout)
          pendingDeliveriesRef.current.delete(clientMessageId)
          // Nothing of this attempt reached the server, so unless an earlier
          // attempt owns the binding, a same-id retry may re-resolve the zone
          // and upload again; drop it rather than leak it.
          if (!bindingsPredateAttempt) releaseAttemptBindings(clientMessageId)
          pending.reject(deliveryError(
            error instanceof Error ? error.message : String(error),
            "not_sent",
          ))
        }
        return delivery
      }

      recentMessagesRef.current.push({
        message,
        timestamp,
        connectionIdentity: connection.identity,
        descriptorKey: currentDescriptorKey,
        lifecycleEpoch: currentLifecycleEpoch,
        attemptEpoch: currentAttemptEpoch,
        deliveryGeneration: currentDeliveryGeneration,
        clientMessageId,
      })
      const cutoffTime = timestamp - 5000
      const firstKeepIndex = recentMessagesRef.current.findIndex(
        item => item.timestamp >= cutoffTime,
      )
      if (firstKeepIndex === -1) {
        recentMessagesRef.current = []
      } else if (firstKeepIndex > 0) {
        recentMessagesRef.current.splice(0, firstKeepIndex)
      }

      return delivery
    } catch (error) {
      // Pre-send failures never reached the server; free the attempt binding so
      // abandoned drafts do not accumulate. An outcome-unknown send of this
      // attempt cannot land here (it settles through the delivery promise), and
      // a binding an earlier outcome-unknown attempt made is kept for its retry.
      const disposition =
        error instanceof MessageDeliveryError ? error.disposition : "not_sent"
      if (disposition !== "outcome_unknown" && !bindingsPredateAttempt) {
        releaseAttemptBindings(clientMessageId)
      }
      if (error instanceof MessageDeliveryError) throw error
      const errorCode = typeof error === "object" && error !== null
        ? readClientErrorCode((error as { errorCode?: unknown }).errorCode)
        : null
      throw deliveryError(
        errorCode
          ? clientErrorFallback(errorCode)
          : error instanceof Error ? error.message : String(error),
        "not_sent",
        {
          userFacing: errorCode !== null,
          errorCode,
        },
      )
    } finally {
      if (preparationsRef.current.get(clientMessageId) === claim) {
        preparationsRef.current.delete(clientMessageId)
      }
    }
  }, [isCurrentOwner, loginIdentityFor, releaseAttemptBindings, retireDeadOwner, syncPhase, uploadFiles])

  const getCurrentTaskConnection = useCallback(() => {
    const connection = connectionRef.current
    const socket = socketRef.current
    if (
      !connection?.taskId
      || socket?.readyState !== WebSocket.OPEN
      || !isCurrentSocket(socket, connection.identity)
    ) {
      return null
    }
    return { socket, taskId: connection.taskId }
  }, [isCurrentSocket])

  const executeTask = useCallback((taskDescription: string, files?: Array<{ name: string; type: string; size: number; content?: string }>) => {
    const current = getCurrentTaskConnection()
    if (current) {
      const message = JSON.stringify({
        type: "execute_task",
        task_id: current.taskId,
        description: taskDescription,
        ...(files && files.length > 0 && { files })
      })
      current.socket.send(message)
    }
  }, [getCurrentTaskConnection])

  const pauseTask = useCallback(() => {
    const current = getCurrentTaskConnection()
    if (current) {
      const message = {
        type: "pause_task",
        task_id: current.taskId,
        command_id: generateClientMessageId(),
      }
      current.socket.send(JSON.stringify(message))
    }
  }, [getCurrentTaskConnection])

  const resumeTask = useCallback(() => {
    const current = getCurrentTaskConnection()
    if (current) {
      current.socket.send(JSON.stringify({
        type: "resume_task",
        task_id: current.taskId,
        command_id: generateClientMessageId(),
      }))
    }
  }, [getCurrentTaskConnection])

  const requestStatus = useCallback(() => {
    const current = getCurrentTaskConnection()
    if (current) {
      current.socket.send(JSON.stringify({
        type: "status_request",
        task_id: current.taskId,
      }))
    }
  }, [getCurrentTaskConnection])

  useEffect(() => {
    const ownedDescriptorKey = connectionDescriptorIdentity
    setConnectionError(null)
    const connectionKey = connectionRef.current
      ? connectionKeyFor(connectionRef.current)
      : null
    // The back-off belongs to the key: a same-key credential refresh keeps it.
    if (connectionKey !== lastConnectionKeyRef.current) {
      reconnectAttemptsRef.current = 0
      lastConnectionKeyRef.current = connectionKey
    }
    if (autoConnect && ownedDescriptorKey !== null && !isConnectingRef.current) {
      if (
        connectionKey !== null
        && openedKeysRef.current.has(connectionKey)
      ) {
        // Replacing a connection on an opened key counts as one attempt.
        reconnectAttemptsRef.current++
      }
      connect()
    }
    syncPhase()

    return () => {
      invalidateLifecycle()
      const owner = socketOwnerRef.current
      const ownsCurrentSocket = Boolean(
        owner
        && owner.descriptorKey === ownedDescriptorKey,
      )
      if (owner && ownsCurrentSocket) {
        retireOwner(owner, {
          pendingError: deliveryError("Connection replaced before the message was accepted.", "outcome_unknown", { connectionLost: mountedRef.current }),
          preparationError: deliveryError("Message not sent: the connection changed before delivery.", "not_sent"),
          close: {
            code: 1000,
            reason: "Component unmounting",
          },
          notifyDisconnect: true,
          keepsLifecycle: true,
        })
      }
      if (ownedDescriptorKey !== null) {
        rejectPendingDeliveries(
          deliveryError("Connection replaced before the message was accepted.", "outcome_unknown", { connectionLost: mountedRef.current }),
          pending => pending.descriptorKey === ownedDescriptorKey,
        )
        rejectPreparations(
          deliveryError("Message not sent: the connection changed before delivery.", "not_sent"),
          claim => claim.descriptorKey === ownedDescriptorKey,
        )
        clearRecentMessages(
          recent => recent.descriptorKey === ownedDescriptorKey,
        )
      }
      if (mountedRef.current) setIsConnected(false)
      isConnectingRef.current = false
      syncPhase()
    }
  }, [
    autoConnect,
    clearRecentMessages,
    connect,
    connectionDescriptorIdentity,
    connectionKeyFor,
    invalidateLifecycle,
    rejectPendingDeliveries,
    rejectPreparations,
    retireOwner,
    syncPhase,
  ])

  return {
    isConnected,
    connectionPhase,
    getLoginIdentity,
    lastMessage,
    connectionError,
    connect: connectFromCaller,
    disconnect,
    sendMessage,
    sendChatMessage,
    executeTask,
    pauseTask,
    resumeTask,
    requestStatus,
  }
}