Enterprise agent platform for building, deploying, and operating AI teammates.
"use client"
import { useCallback, useEffect, useRef, useState } from "react"
import { RESEND_RECONNECT_DEADLINE_MS } from "@/contexts/chat-delivery-resend"
import type { WebSocketConnectionFailure } from "@/hooks/use-websocket"
import { WidgetSessionUploadError } from "@/lib/widget-session-upload"
const TOKEN_REFRESH_THRESHOLD_MS = 60_000
const EXPIRY_WARNING_LEAD_MS = 10 * 60_000
// Keep this predicate aligned with the two retry signals emitted by
// frontend/public/widget.js; every other parent code fails closed.
const isParentRecoverableCode = (code: string): boolean =>
code === "network_unavailable" || code === "rate_limited"
export type WidgetSessionStatus = "waiting" | "active" | "refreshing" | "degraded" | "terminal"
export type WidgetSessionReconnectReason = "ws_closed" | "token_expired"
export interface WidgetSessionAgent {
id: number
name: string
description?: string
logoUrl?: string
suggestedPrompts: string[]
}
export interface WidgetSessionFileUploads {
allowedExtensions: readonly string[]
maxFileBytes: number
maxFilesPerMessage: number
}
// What the session server advertises for this session. A session without a
// usable advertisement has no `capabilities` key, so no capability-gated
// feature is offered.
export interface WidgetSessionCapabilities {
fileUploads?: WidgetSessionFileUploads
// Present when the server lets this session read its earlier conversations
// and continue from one.
conversationHistory?: true
}
export interface WidgetSession {
token: string
tokenExpiresAt: string
absoluteExpiresAt: string
agent: WidgetSessionAgent
capabilities?: WidgetSessionCapabilities
generation: number
}
interface WidgetSessionBridgeState {
status: WidgetSessionStatus
session: WidgetSession | null
agent: WidgetSessionAgent | null
terminalCode: string | null
isAbsoluteExpiryWarningVisible: boolean
}
interface ProtocolMessage extends Record<string, unknown> {
xagent: true
v: 1
type: "session_update" | "session_degraded" | "session_terminal"
}
const initialState: WidgetSessionBridgeState = {
status: "waiting",
session: null,
agent: null,
terminalCode: null,
isAbsoluteExpiryWarningVisible: false,
}
const isRecord = (value: unknown): value is Record<string, unknown> =>
Boolean(value) && typeof value === "object" && !Array.isArray(value)
const parseDate = (value: unknown): number | null => {
if (typeof value !== "string" || !value) return null
const timestamp = Date.parse(value)
return Number.isFinite(timestamp) ? timestamp : null
}
const isNonBlankString = (value: unknown): value is string =>
typeof value === "string" && value.trim().length > 0
const parseAgent = (value: unknown): WidgetSessionAgent | null => {
if (!isRecord(value)) return null
if (!Number.isInteger(value.id) || (value.id as number) <= 0) return null
if (typeof value.name !== "string" || !value.name.trim()) return null
if (value.description !== undefined && value.description !== null && typeof value.description !== "string") return null
if (value.logo_url !== undefined && value.logo_url !== null && typeof value.logo_url !== "string") return null
if (!Array.isArray(value.suggested_prompts) || !value.suggested_prompts.every((item) => typeof item === "string")) {
return null
}
return {
id: value.id as number,
name: value.name,
...(typeof value.description === "string" ? { description: value.description } : {}),
...(typeof value.logo_url === "string" ? { logoUrl: value.logo_url } : {}),
suggestedPrompts: value.suggested_prompts as string[],
}
}
const isPositiveInteger = (value: unknown): value is number =>
typeof value === "number" && Number.isInteger(value) && value > 0
const isAllowedExtension = (value: unknown): value is string =>
typeof value === "string"
&& value.length >= 2
&& value.startsWith(".")
&& value === value.toLowerCase()
const parseFileUploads = (value: unknown): WidgetSessionFileUploads | undefined => {
if (!isRecord(value)) return undefined
const extensions = value.allowed_extensions
if (
!Array.isArray(extensions)
|| extensions.length === 0
|| !extensions.every(isAllowedExtension)
|| !isPositiveInteger(value.max_file_bytes)
|| !isPositiveInteger(value.max_files_per_message)
) return undefined
return {
allowedExtensions: [...extensions],
maxFileBytes: value.max_file_bytes,
maxFilesPerMessage: value.max_files_per_message,
}
}
// The parent forwards the server's capabilities untouched, so everything here
// is untrusted. Each capability is read on its own: one that does not match
// its documented shape is dropped without affecting the other, and a session
// with none left counts as "no capabilities" (undefined) instead of failing.
export const parseCapabilities = (value: unknown): WidgetSessionCapabilities | undefined => {
if (!isRecord(value)) return undefined
const fileUploads = parseFileUploads(value.file_uploads)
const conversationHistory = isRecord(value.conversation_history)
if (!fileUploads && !conversationHistory) return undefined
return {
...(fileUploads ? { fileUploads } : {}),
...(conversationHistory ? { conversationHistory: true as const } : {}),
}
}
const isProtocolMessage = (value: unknown): value is ProtocolMessage => {
if (!isRecord(value)) return false
return value.xagent === true
&& value.v === 1
&& (
value.type === "session_update"
|| value.type === "session_degraded"
|| value.type === "session_terminal"
)
}
export function buildWidgetSessionWebSocketUrl(origin: string): string {
const url = new URL(origin)
if (url.protocol === "https:") {
url.protocol = "wss:"
} else if (url.protocol === "http:") {
url.protocol = "ws:"
} else {
throw new Error("Widget Session requires an HTTP(S) origin")
}
url.pathname = "/v1/external/chat/sessions/ws"
url.search = ""
url.hash = ""
return url.toString()
}
interface Waiter<T> {
resolve: (value: T) => void
reject: (error: Error) => void
timer: ReturnType<typeof setTimeout>
}
export function useWidgetSession() {
const [state, setState] = useState<WidgetSessionBridgeState>(initialState)
const mountedRef = useRef(false)
const targetOriginRef = useRef<string | null>(null)
const recoveryInFlightRef = useRef(false)
const terminalRef = useRef(false)
const generationRef = useRef(0)
const activeSessionGenerationRef = useRef<number | null>(null)
const activeDeliveryIdRef = useRef<string | null>(null)
const warningTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
// The session the current generation was built from; null while there is no
// usable session (waiting, refreshing, degraded, terminal).
const sessionRef = useRef<WidgetSession | null>(null)
const degradedRef = useRef(false)
// The generation whose socket has opened, if any.
const openGenerationRef = useRef<number | null>(null)
const sessionWaitRef = useRef<{ promise: Promise<WidgetSession>, waiters: Waiter<WidgetSession>[] } | null>(null)
const openWaitersRef = useRef<Waiter<void>[]>([])
const rejectSessionWaiters = useCallback((error: Error) => {
const pending = sessionWaitRef.current
sessionWaitRef.current = null
pending?.waiters.forEach((waiter) => {
clearTimeout(waiter.timer)
waiter.reject(error)
})
}, [])
const rejectOpenWaiters = useCallback((error: Error) => {
const waiters = openWaitersRef.current
openWaitersRef.current = []
waiters.forEach((waiter) => {
clearTimeout(waiter.timer)
waiter.reject(error)
})
}, [])
const failPendingWaits = useCallback(() => {
rejectSessionWaiters(new WidgetSessionUploadError("upload_failed"))
rejectOpenWaiters(new WidgetSessionUploadError("connection_not_ready"))
}, [rejectOpenWaiters, rejectSessionWaiters])
const clearWarningTimer = useCallback(() => {
if (warningTimerRef.current) {
clearTimeout(warningTimerRef.current)
warningTimerRef.current = null
}
}, [])
const transitionTerminal = useCallback((code: string) => {
if (terminalRef.current) return
terminalRef.current = true
activeSessionGenerationRef.current = null
activeDeliveryIdRef.current = null
sessionRef.current = null
openGenerationRef.current = null
recoveryInFlightRef.current = false
clearWarningTimer()
failPendingWaits()
setState({
status: "terminal",
session: null,
agent: null,
terminalCode: code,
isAbsoluteExpiryWarningVisible: false,
})
}, [clearWarningTimer, failPendingWaits])
const transitionDegraded = useCallback(() => {
if (terminalRef.current) return
activeSessionGenerationRef.current = null
activeDeliveryIdRef.current = null
sessionRef.current = null
openGenerationRef.current = null
degradedRef.current = true
clearWarningTimer()
failPendingWaits()
setState((current) => ({
status: "degraded",
session: null,
agent: current.agent,
terminalCode: null,
isAbsoluteExpiryWarningVisible: false,
}))
}, [clearWarningTimer, failPendingWaits])
const issueReconnectRequest = useCallback((reason: WidgetSessionReconnectReason) => {
const targetOrigin = targetOriginRef.current
if (!mountedRef.current || !targetOrigin || terminalRef.current) return
if (recoveryInFlightRef.current) return
recoveryInFlightRef.current = true
sessionRef.current = null
openGenerationRef.current = null
clearWarningTimer()
setState((current) => ({
status: "refreshing",
session: null,
agent: current.agent,
terminalCode: null,
isAbsoluteExpiryWarningVisible: false,
}))
window.parent.postMessage({ xagent: true, v: 1, type: "reconnect_request", reason }, targetOrigin)
}, [clearWarningTimer])
const requestReconnect = useCallback((reason: WidgetSessionReconnectReason) => {
if (!mountedRef.current || terminalRef.current || recoveryInFlightRef.current) return
activeSessionGenerationRef.current = null
issueReconnectRequest(reason)
}, [issueReconnectRequest])
const isActiveConnection = useCallback((connectionIdentity?: string) => {
const activeGeneration = activeSessionGenerationRef.current
return connectionIdentity === undefined || (
activeGeneration !== null
&& connectionIdentity === `widget-session:${activeGeneration}`
)
}, [])
const handleConnectionOpen = useCallback((connectionIdentity: string) => {
const activeGeneration = activeSessionGenerationRef.current
// Recorded before any early return below: whether the parent is told about
// this open depends on the delivery id, but whether the socket is open does
// not.
if (activeGeneration !== null && connectionIdentity === `widget-session:${activeGeneration}`) {
openGenerationRef.current = activeGeneration
const waiters = openWaitersRef.current
openWaitersRef.current = []
waiters.forEach((waiter) => {
clearTimeout(waiter.timer)
waiter.resolve()
})
}
const deliveryId = activeDeliveryIdRef.current
const targetOrigin = targetOriginRef.current
if (
!mountedRef.current
|| !targetOrigin
|| terminalRef.current
|| activeGeneration === null
|| !deliveryId
|| connectionIdentity !== `widget-session:${activeGeneration}`
) return
window.parent.postMessage({
xagent: true,
v: 1,
type: "session_connection_open",
session_delivery_id: deliveryId,
}, targetOrigin)
}, [])
const handleConnectionClose = useCallback((
event: CloseEvent,
connectionIdentity?: string,
): "handled" => {
if (!isActiveConnection(connectionIdentity)) return "handled"
if (event.code === 1000 || event.code === 1001) {
transitionTerminal("unexpected_error")
return "handled"
}
if (event.code === 4403) {
transitionTerminal("ws_4403")
return "handled"
}
if (event.code === 4408) {
transitionTerminal("ws_4408")
return "handled"
}
requestReconnect("ws_closed")
return "handled"
}, [isActiveConnection, requestReconnect, transitionTerminal])
const handleConnectionFailure = useCallback((
failure: WebSocketConnectionFailure,
connectionIdentity?: string,
) => {
if (!isActiveConnection(connectionIdentity)) return
if (failure.recoverable) {
requestReconnect("ws_closed")
return
}
transitionTerminal("unexpected_error")
}, [isActiveConnection, requestReconnect, transitionTerminal])
const newWaiter = useCallback(<T,>(
resolve: (value: T) => void,
reject: (error: Error) => void,
onTimeout: () => void,
errorCode: "upload_failed" | "connection_not_ready",
): Waiter<T> => ({
resolve,
reject,
timer: setTimeout(() => {
onTimeout()
reject(new WidgetSessionUploadError(errorCode, "timed out"))
}, RESEND_RECONNECT_DEADLINE_MS),
}), [])
// Waits for the next accepted session. Callers share one wait and one
// deadline: the wait gives up RESEND_RECONNECT_DEADLINE_MS after the first
// caller started it, so a caller that joins later waits only for the time
// left. A wait never issues a second reconnect request.
const waitForNextSession = useCallback((): Promise<WidgetSession> => {
if (sessionWaitRef.current) return sessionWaitRef.current.promise
const waiters: Waiter<WidgetSession>[] = []
const promise = new Promise<WidgetSession>((resolve, reject) => {
const waiter = newWaiter<WidgetSession>(resolve, reject, () => {
if (sessionWaitRef.current?.waiters === waiters) sessionWaitRef.current = null
}, "upload_failed")
waiters.push(waiter)
})
sessionWaitRef.current = { promise, waiters }
return promise
}, [newWaiter])
const unavailableError = useCallback((): WidgetSessionUploadError | null =>
terminalRef.current || degradedRef.current || !mountedRef.current
? new WidgetSessionUploadError("upload_failed", "session unavailable")
: null, [])
// Resolves with a session whose token has at least TOKEN_REFRESH_THRESHOLD_MS
// left, asking the parent for a new one when it does not. Every refresh
// closes the chat socket and opens a new one, and frontend/public/widget.js
// ends the session (session_terminal, network_unavailable) on the fourth
// reconnect -- for any reason, a closed socket included -- unless a
// connection has stayed open for 60 s since the count was last reset.
const ensureFreshSession = useCallback((): Promise<WidgetSession> => {
const unavailable = unavailableError()
if (unavailable) return Promise.reject(unavailable)
const current = sessionRef.current
if (current && Date.parse(current.tokenExpiresAt) - Date.now() >= TOKEN_REFRESH_THRESHOLD_MS) {
return Promise.resolve(current)
}
const wait = waitForNextSession()
if (current) requestReconnect("token_expired")
return wait
}, [requestReconnect, unavailableError, waitForNextSession])
// Recovers from a rejected token. Resolves with the current session when it
// no longer uses `rejectedToken`, because another caller already replaced
// it; otherwise resolves with a newly issued one, sharing the wait of any
// refresh already under way.
const refreshSession = useCallback((rejectedToken: string): Promise<WidgetSession> => {
const unavailable = unavailableError()
if (unavailable) return Promise.reject(unavailable)
const current = sessionRef.current
if (current && current.token !== rejectedToken) return Promise.resolve(current)
const alreadyWaiting = sessionWaitRef.current !== null
const wait = waitForNextSession()
if (!alreadyWaiting && current) requestReconnect("token_expired")
return wait
}, [requestReconnect, unavailableError, waitForNextSession])
// Resolves once the socket of the current generation is open; waits through
// a refresh for the next generation's socket.
const waitForOpenConnection = useCallback((): Promise<void> => {
const unavailable = unavailableError()
if (unavailable) {
return Promise.reject(new WidgetSessionUploadError("connection_not_ready", "session unavailable"))
}
const activeGeneration = activeSessionGenerationRef.current
if (activeGeneration !== null && openGenerationRef.current === activeGeneration) {
return Promise.resolve()
}
return new Promise<void>((resolve, reject) => {
const waiter = newWaiter<void>(resolve, reject, () => {
openWaitersRef.current = openWaitersRef.current.filter((entry) => entry !== waiter)
}, "connection_not_ready")
openWaitersRef.current.push(waiter)
})
}, [newWaiter, unavailableError])
const scheduleExpiryWarning = useCallback((absoluteExpiresAt: number) => {
clearWarningTimer()
const delay = Math.max(0, absoluteExpiresAt - Date.now() - EXPIRY_WARNING_LEAD_MS)
warningTimerRef.current = setTimeout(() => {
warningTimerRef.current = null
setState((current) => current.status === "active"
? { ...current, isAbsoluteExpiryWarningVisible: true }
: current)
}, delay)
}, [clearWarningTimer])
useEffect(() => {
if (window.parent === window) {
transitionTerminal("unexpected_error")
return
}
mountedRef.current = true
const onMessage = (event: MessageEvent<unknown>) => {
if (event.source !== window.parent || !isProtocolMessage(event.data)) return
if (targetOriginRef.current && event.origin !== targetOriginRef.current) return
if (!targetOriginRef.current) {
targetOriginRef.current = event.origin
}
if (terminalRef.current) return
if (event.data.type === "session_terminal") {
transitionTerminal(typeof event.data.code === "string" && event.data.code
? event.data.code
: "unexpected_error")
return
}
if (event.data.type === "session_degraded") {
if (
typeof event.data.code !== "string"
|| !isParentRecoverableCode(event.data.code)
) {
transitionTerminal("unexpected_error")
return
}
transitionDegraded()
return
}
const token = event.data.session_token
const hasDeliveryId = Object.prototype.hasOwnProperty.call(
event.data,
"session_delivery_id",
)
const deliveryId = event.data.session_delivery_id
const tokenExpiresAt = parseDate(event.data.session_token_expires_at)
const absoluteExpiresAt = parseDate(event.data.absolute_expires_at)
const agent = parseAgent(event.data.agent)
if (
(hasDeliveryId && !isNonBlankString(deliveryId))
|| typeof token !== "string"
|| !token.trim()
|| tokenExpiresAt === null
|| absoluteExpiresAt === null
|| !agent
) {
transitionTerminal("unexpected_error")
return
}
const now = Date.now()
if (absoluteExpiresAt <= now || absoluteExpiresAt < tokenExpiresAt) {
transitionTerminal("session_expired")
return
}
if (tokenExpiresAt - now < TOKEN_REFRESH_THRESHOLD_MS) {
requestReconnect("token_expired")
return
}
recoveryInFlightRef.current = false
generationRef.current += 1
const capabilities = parseCapabilities(event.data.capabilities)
const session: WidgetSession = {
token,
tokenExpiresAt: event.data.session_token_expires_at as string,
absoluteExpiresAt: event.data.absolute_expires_at as string,
agent,
...(capabilities ? { capabilities } : {}),
generation: generationRef.current,
}
activeSessionGenerationRef.current = session.generation
activeDeliveryIdRef.current = hasDeliveryId ? deliveryId as string : null
sessionRef.current = session
degradedRef.current = false
openGenerationRef.current = null
setState({
status: "active",
session,
agent,
terminalCode: null,
isAbsoluteExpiryWarningVisible: false,
})
scheduleExpiryWarning(absoluteExpiresAt)
const pending = sessionWaitRef.current
sessionWaitRef.current = null
pending?.waiters.forEach((waiter) => {
clearTimeout(waiter.timer)
waiter.resolve(session)
})
}
window.addEventListener("message", onMessage)
window.parent.postMessage({ xagent: true, v: 1, type: "ready" }, "*")
return () => {
mountedRef.current = false
activeSessionGenerationRef.current = null
activeDeliveryIdRef.current = null
sessionRef.current = null
openGenerationRef.current = null
failPendingWaits()
window.removeEventListener("message", onMessage)
recoveryInFlightRef.current = false
clearWarningTimer()
}
// The bridge owns its parent message subscription for the mounted lifetime.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [])
return {
...state,
requestReconnect,
handleConnectionOpen,
handleConnectionClose,
handleConnectionFailure,
ensureFreshSession,
refreshSession,
waitForOpenConnection,
}
}