@alexkroman1/aai-ui 0.14.0 → 0.14.2

package/dist/session/connection.d.ts

@@ -0,0 +1,121 @@
+/**
+ * One browser session's CONNECTION — the socket, the handshake deadline over
+ * it, and the server's idle retirement — as a statechart.
+ *
+ * `link` is `closed → open`, and `open` is `dialing → awaitingHandshake → live`:
+ *
+ * - **The socket belongs to `open`.** Its entry dials and attaches the
+ *   listeners; its exit is the ONE teardown (detach, release the pre-connect
+ *   mic, tear the audio path down, close the socket). A hang-up, a terminal
+ *   close, an exhausted handshake and a fresh `connect()` all leave `open`, so
+ *   none of them restates it, and exit actions run before the transition's, so
+ *   the teardown always precedes the snapshot write reporting the end.
+ * - **The handshake deadline is an `after` on `awaitingHandshake`** (see
+ *   `session/handshake.ts` for why there is one). Leaving the state disarms it,
+ *   so a `config` frame, a close or a teardown cannot leave it armed against
+ *   the next attempt — there is no timer to clear by hand on abort.
+ * - **partysocket owns the reconnect backoff.** A close that partysocket will
+ *   retry goes back to `dialing` and waits for its next `open`; this machine
+ *   never schedules an attempt. The deadline forces one only for a socket
+ *   partysocket thinks is healthy (`forceReconnect`).
+ *
+ * `retired` is a second region because it outlives a socket: the server's
+ * `session.timedOut` marks the close that follows as EXPECTED, so it is not
+ * retried. Without it the automatic reconnect would re-open the session the
+ * server just reclaimed — a tab left open would cycle forever and the guest
+ * would never see zero sessions, which is the point of the timeout. Only a
+ * fresh `connect()` (the user asking again) clears it.
+ *
+ * The machine owns WHEN; every HOW — the socket, the snapshot, the audio path —
+ * is an injected {@link ConnectionEffects} call, as in `session/audio-state.ts`.
+ */
+import type { SessionConfigMessage } from "./messages.ts";
+/** The socket shape the session speaks (a partysocket, or an injected `WebSocket`). */
+type Socket = WebSocket;
+/** The session core's side of the machine. */
+export type ConnectionEffects = {
+    /** Open the socket for a fresh `connect()` and make it the session's. */
+    dial(): Socket;
+    /**
+     * Let go of everything one connection holds: the pre-connect mic, the audio
+     * path and `socket`. Its listeners are already detached, so the close this
+     * causes cannot re-enter the machine.
+     */
+    release(socket: Socket): void;
+    /** The caller's `connect({ signal })` aborted: hang up. */
+    abandon(): void;
+    /** Interpret a frame; the `config` payload when it completes the handshake. */
+    receive(data: unknown): SessionConfigMessage | undefined;
+    /** The socket opened; the handshake has not completed yet. */
+    opened(): void;
+    /** The handshake completed. */
+    configured(config: SessionConfigMessage): void;
+    /** Is the session fatally over (`session/state.ts`)? Then no close is retried. */
+    fatal(): boolean;
+    /**
+     * Will partysocket retry the close being dispatched on `socket`? Asked
+     * inside the `close` listener: partysocket schedules its retry before it
+     * dispatches.
+     */
+    retryPending(socket: Socket): boolean;
+    /** Does the socket have reconnect machinery? An injected `WebSocket` does not. */
+    canRedial(): boolean;
+    /** Force a fresh attempt on a socket that opened but never became a session. */
+    redial(): void;
+    /** An attempt failed and another is coming: drop the audio path, show `connecting`. */
+    retrying(): void;
+    /** The socket closed for good — `failure` is what to report, null for a clean end. */
+    closed(failure: string | null): void;
+    /** The handshake budget is spent. */
+    exhausted(): void;
+};
+/** Everything that happens to the connection. */
+export type ConnectionEvent = 
+/** `connect()`: tear down whatever is there and dial afresh. */
+{
+    type: "DIAL";
+    signal?: AbortSignal | undefined;
+}
+/** The caller hung up (`disconnect()`, `end()`). */
+ | {
+    type: "HANG_UP";
+}
+/** The server retired the session for idleness (`session.timedOut`). */
+ | {
+    type: "RETIRED";
+}
+/** The socket opened. */
+ | {
+    type: "OPENED";
+}
+/** The `config` frame arrived. */
+ | {
+    type: "CONFIGURED";
+    config: SessionConfigMessage;
+}
+/** The socket errored; a `close` always follows. */
+ | {
+    type: "ERRORED";
+}
+/** The socket closed; `reconnecting` is whether partysocket will retry it. */
+ | {
+    type: "DROPPED";
+    event: CloseEvent;
+    reconnecting: boolean;
+};
+/** Where the connection is. */
+export type ConnectionPhase = "closed" | "dialing" | "awaitingHandshake" | "live";
+/** The session core's handle on its connection. */
+export type Connection = {
+    /** Tear down whatever is there and dial afresh; `signal` aborting hangs up. */
+    dial(signal?: AbortSignal): void;
+    /** Hang up: the teardown, and no retry. */
+    hangUp(): void;
+    /** The server retired the session: the close that follows is not retried. */
+    retire(): void;
+    /** Where the connection is — for specs. */
+    phase(): ConnectionPhase;
+};
+/** Create the connection machine for one browser session. */
+export declare function createConnection(effects: ConnectionEffects): Connection;
+export {};

package/dist/session/handshake.d.ts

@@ -17,44 +17,31 @@
  * nothing on screen to say so. Measured against a server that accepts and
  * then says nothing: `ready` at 34ms, still `ready` and errorless when the
  * probe gave up.
+ *
+ * The deadline itself is the `awaitingHandshake` state's `after` delay in
+ * `session/connection.ts`, so leaving the state — a `config` frame, a close, a
+ * teardown — is what disarms it. This module holds its numbers and its error.
  */
 import type { SessionError } from "../types.ts";
 /** What the session reports once the budget below is spent. */
 export declare const HANDSHAKE_ERROR: SessionError;
-export type HandshakeGuard = {
-    /** Start the deadline for the attempt that just opened. */
-    arm(): void;
-    /** Stop it — this socket is closing, or the connection is being torn down. */
-    disarm(): void;
-    /**
-     * The `config` frame arrived: stop the deadline AND spend nothing.
-     *
-     * Separate from {@link HandshakeGuard.disarm} because the budget is
-     * CONSECUTIVE, and only a completed handshake proves the peer is healthy. One
-     * guard covers a whole `connect()`, partysocket's retries included, so with a
-     * plain disarm the count survived every successful session in between: an
-     * hour-long call whose socket dropped three times, each drop timing out once
-     * before the next attempt succeeded, surfaced the permanent
-     * "Agent did not complete the session handshake" error against a peer that
-     * had answered every time. A close must NOT reset it — a wedged peer closes
-     * and reopens on its own, and resetting there is the unbounded re-dial loop
-     * the budget exists to bound.
-     */
-    succeeded(): void;
-};
+/** How long an OPEN socket may go without a `config` frame. */
+export declare const HANDSHAKE_TIMEOUT_MS = 10000;
 /**
- * Watch one connection's handshake.
+ * How many consecutive handshake timeouts to ride out before giving up.
  *
- * `onRetry` fires when a timed-out attempt has been re-dialed (the sandbox
- * behind the endpoint may have been replaced, and the URL provider re-brokers
- * on the next attempt); `onExhausted` when the budget is spent, or when the
- * socket has no reconnect machinery at all (an injected `options.WebSocket`).
+ * `forceReconnect` restarts partysocket's own retry budget, so this is the
+ * budget for this failure mode — without one, a permanently wedged peer would
+ * be re-dialed every ~10s forever, which is the unbounded retry loop
+ * `RECONNECT_OPTIONS.maxRetries` exists to prevent.
  *
- * @internal
+ * CONSECUTIVE is the whole of it: only a completed handshake resets the count.
+ * One `connect()` spans partysocket's retries, so a count that survived a
+ * successful session in between turned an hour-long call whose socket dropped
+ * three times — each drop timing out once before the next attempt succeeded —
+ * into the permanent "did not complete the session handshake" error against a
+ * peer that had answered every time. A close must NOT reset it: a wedged peer
+ * closes and reopens on its own, and resetting there is the unbounded re-dial
+ * loop the budget exists to bound.
  */
-export declare function createHandshakeGuard(opts: {
-    socket: unknown;
-    signal: AbortSignal;
-    onRetry: () => void;
-    onExhausted: () => void;
-}): HandshakeGuard;
+export declare const MAX_HANDSHAKE_TIMEOUTS = 3;

package/dist/session/index.d.ts

@@ -3,7 +3,7 @@
  *
  * `createBrowserSession` and the types its handle is described by are what the
  * package builds on; every other module in `session/` (the dialer, the
- * reconnecting socket, the handshake guard, the two statecharts, the message
+ * reconnecting socket, the handshake deadline, the three statecharts, the message
  * handlers, the audio path's bring-up) is private to this directory. Private
  * means NOT re-exported here: guard-invariants rule 37 fails an import from
  * outside `session/` that names any module but this one.

package/dist/session/index.js

@@ -1,2 +1,2 @@
-import { a as ticketCarriage, i as resolveSessionTokenSync, n as CLEARED_SESSION_STATE, o as loadAudioModules, r as resolveSessionToken, t as createBrowserSession } from "../session-D9jM5-TF.js";
+import { a as ticketCarriage, i as resolveSessionTokenSync, n as CLEARED_SESSION_STATE, o as loadAudioModules, r as resolveSessionToken, t as createBrowserSession } from "../session-CYdjRvbl.js";
 export { CLEARED_SESSION_STATE, createBrowserSession, loadAudioModules, resolveSessionToken, resolveSessionTokenSync, ticketCarriage };

package/dist/session/messages.d.ts

@@ -37,6 +37,12 @@ type MessageHandlerDeps = {
      * module's.
      */
     audio: AudioPath;
+    /**
+     * The server retired the session for idleness: the close that follows is
+     * EXPECTED and must not be retried (the `retired` region of
+     * `session/connection.ts`).
+     */
+    retire: () => void;
 };
 type MessageHandlers = {
     /**

package/dist/session/reconnect.d.ts

@@ -8,6 +8,11 @@ import type { WebSocketConstructor } from "../types.ts";
  * tick, for each attempt.
  */
 export declare function openReconnectingSocket(urlProvider: () => Promise<string>, protocolsProvider?: () => Promise<string[] | null>): InstanceType<WebSocketConstructor>;
+/**
+ * Does `socket` have reconnect machinery? False for an injected
+ * `options.WebSocket` (tests), which a failure then ends for good.
+ */
+export declare function canReconnect(socket: unknown): boolean;
 /**
  * Force a fresh connection attempt on a reconnecting socket, reporting
  * whether it was one. Used for a failure partysocket cannot see: a socket it

package/dist/session/types.d.ts

@@ -411,22 +411,12 @@ export type BrowserSession = {
  * from anywhere. They are the audio path's own statechart now — see
  * `session/audio-state.ts`.
  *
- * What is left is what the CONNECTION really owns: the socket, the server's
- * idle retirement, and the turn boundary.
+ * What is left is the socket the senders write to and the turn boundary. The
+ * socket's lifecycle and the server's idle retirement are the connection's own
+ * statechart (`session/connection.ts`), which is the only writer of `ws`.
  */
 export type ConnState = {
     ws: InstanceType<WebSocketConstructor> | null;
-    /**
-     * The server retired this session for idleness (`idle_timeout`), so the
-     * close that follows is EXPECTED and must not be retried.
-     *
-     * Without this the automatic reconnect would immediately re-open the
-     * session the server just reclaimed — a tab left open would cycle forever
-     * and the guest would never see zero sessions, which is the whole point of
-     * the timeout. Reconnecting is the user's call from here (the controls
-     * reconnect on demand).
-     */
-    retiredByServer: boolean;
     /**
      * Turn epoch, bumped at every turn boundary — a committed user turn, a
      * barge-in, a reset, AND every audio-path teardown (`cleanupAudio`).