@alexkroman1/aai-ui 0.14.1 → 0.14.2

package/dist/{session-6tIQSoak.js → session-CYdjRvbl.js}

@@ -646,6 +646,218 @@ function closeFailure(event, socketErrored) {
 	return socketErrored ? "WebSocket connection error" : null;
 }
 //#endregion
+//#region src/session/handshake.ts
+/** What the session reports once the budget below is spent. */
+const HANDSHAKE_ERROR = {
+	code: "connection",
+	message: "Agent did not complete the session handshake",
+	fatal: false
+};
+//#endregion
+//#region src/session/connection.ts
+/**
+* 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`.
+*/
+const connectionMachine = setup({
+	types: {},
+	delays: { HANDSHAKE_TIMEOUT: 1e4 },
+	guards: {
+		/**
+		* partysocket will retry this close, and nothing says it must not: a FATAL
+		* error is not retryable by construction, nor is an idle retirement.
+		*/
+		mayReconnect: and([({ context, event }) => event.type === "DROPPED" && event.reconnecting && !context.effects.fatal(), not(stateIn({ retired: "yes" }))]),
+		/** Budget left, and a socket that can re-dial at all. */
+		mayRedial: ({ context }) => context.timeouts + 1 < 3 && context.effects.canRedial()
+	},
+	actions: {
+		spend: assign({ timeouts: ({ context }) => context.timeouts + 1 }),
+		/** A socket error inside a retry cycle is not terminal. */
+		forgetError: assign({ errored: false }),
+		retrying: ({ context }) => context.effects.retrying(),
+		opened: ({ context }) => context.effects.opened(),
+		dial: ({ context, event }) => context.link.dial(event.type === "DIAL" ? event.signal : void 0),
+		/** The ONE teardown: every way out of `open` runs it, before anything is reported. */
+		teardown: ({ context }) => context.link.teardown(),
+		reportClose: ({ context, event }) => {
+			if (event.type === "DROPPED") context.effects.closed(closeFailure(event.event, context.errored));
+		}
+	}
+}).createMachine({
+	id: "connection",
+	type: "parallel",
+	context: ({ input }) => ({
+		...input,
+		timeouts: 0,
+		errored: false
+	}),
+	states: {
+		link: {
+			initial: "closed",
+			on: {
+				DIAL: {
+					target: ".open",
+					reenter: true
+				},
+				HANG_UP: ".closed"
+			},
+			states: {
+				closed: {},
+				open: {
+					entry: [assign({
+						timeouts: 0,
+						errored: false
+					}), "dial"],
+					exit: "teardown",
+					initial: "dialing",
+					on: {
+						ERRORED: { actions: assign({ errored: true }) },
+						CONFIGURED: {
+							target: ".live",
+							actions: [assign({ timeouts: 0 }), ({ context, event }) => context.effects.configured(event.config)]
+						},
+						DROPPED: [{
+							guard: "mayReconnect",
+							target: ".dialing",
+							actions: ["forgetError", "retrying"]
+						}, {
+							target: "closed",
+							actions: "reportClose"
+						}]
+					},
+					states: {
+						dialing: { on: { OPENED: {
+							target: "awaitingHandshake",
+							actions: "opened"
+						} } },
+						awaitingHandshake: {
+							on: { OPENED: {
+								target: "awaitingHandshake",
+								reenter: true,
+								actions: "opened"
+							} },
+							after: { HANDSHAKE_TIMEOUT: [{
+								guard: "mayRedial",
+								target: "dialing",
+								actions: [
+									"spend",
+									({ context }) => context.effects.redial(),
+									"retrying"
+								]
+							}, {
+								target: "#connection.link.closed",
+								actions: ({ context }) => context.effects.exhausted()
+							}] }
+						},
+						live: { on: { OPENED: {
+							target: "awaitingHandshake",
+							actions: "opened"
+						} } }
+					}
+				}
+			}
+		},
+		retired: {
+			initial: "no",
+			states: {
+				no: { on: { RETIRED: "yes" } },
+				yes: { on: { DIAL: "no" } }
+			}
+		}
+	}
+});
+/** The socket half of {@link Link}: listeners in, teardown out. */
+function createLink(effects, send) {
+	let current = null;
+	return {
+		dial(caller) {
+			const controller = new AbortController();
+			const { signal } = controller;
+			caller?.addEventListener("abort", () => effects.abandon(), { signal });
+			const socket = effects.dial();
+			current = {
+				socket,
+				controller
+			};
+			socket.addEventListener("open", () => send({ type: "OPENED" }), { signal });
+			socket.addEventListener("message", (event) => {
+				const config = effects.receive(event.data);
+				if (config) send({
+					type: "CONFIGURED",
+					config
+				});
+			}, { signal });
+			socket.addEventListener("error", () => send({ type: "ERRORED" }), { signal });
+			socket.addEventListener("close", (event) => send({
+				type: "DROPPED",
+				event,
+				reconnecting: effects.retryPending(socket)
+			}), { signal });
+		},
+		teardown() {
+			if (current === null) return;
+			const { socket, controller } = current;
+			current = null;
+			controller.abort();
+			effects.release(socket);
+		}
+	};
+}
+/** Create the connection machine for one browser session. */
+function createConnection(effects) {
+	const link = createLink(effects, (event) => self.send(event));
+	const self = createActor(connectionMachine, { input: {
+		effects,
+		link
+	} }).start();
+	return {
+		dial: (signal) => {
+			self.send({
+				type: "DIAL",
+				signal
+			});
+		},
+		hangUp: () => {
+			self.send({ type: "HANG_UP" });
+		},
+		retire: () => {
+			self.send({ type: "RETIRED" });
+		},
+		phase: () => {
+			const at = self.getSnapshot().value.link;
+			return typeof at === "string" ? "closed" : at.open;
+		}
+	};
+}
+//#endregion
 //#region src/session/reconnect.ts
 /**
 * Automatic reconnection for the browser session socket, built on
@@ -676,6 +888,13 @@ function openReconnectingSocket(urlProvider, protocolsProvider) {
 	return new ReconnectingWebSocket(urlProvider, protocolsProvider, RECONNECT_OPTIONS);
 }
 /**
+* Does `socket` have reconnect machinery? False for an injected
+* `options.WebSocket` (tests), which a failure then ends for good.
+*/
+function canReconnect(socket) {
+	return socket instanceof ReconnectingWebSocket;
+}
+/**
 * Force a fresh connection attempt on a reconnecting socket, reporting
 * whether it was one. Used for a failure partysocket cannot see: a socket it
 * considers open and healthy, whose peer never completed OUR handshake.
@@ -1018,67 +1237,6 @@ function createDialer(options, onSessionId) {
 	};
 }
 //#endregion
-//#region src/session/handshake.ts
-/** What the session reports once the budget below is spent. */
-const HANDSHAKE_ERROR = {
-	code: "connection",
-	message: "Agent did not complete the session handshake",
-	fatal: false
-};
-/** How long an OPEN socket may go without a `config` frame. */
-const HANDSHAKE_TIMEOUT_MS = 1e4;
-/**
-* How many consecutive handshake timeouts to ride out before giving up.
-*
-* `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.
-*
-* CONSECUTIVE is the whole of it, and only `succeeded()` says so — see its doc.
-*/
-const MAX_HANDSHAKE_TIMEOUTS = 3;
-/**
-* Watch one connection's handshake.
-*
-* `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`).
-*
-* @internal
-*/
-function createHandshakeGuard(opts) {
-	let timer;
-	let timeouts = 0;
-	function disarm() {
-		if (timer === void 0) return;
-		clearTimeout(timer);
-		timer = void 0;
-	}
-	function fire() {
-		timer = void 0;
-		timeouts += 1;
-		if (timeouts < MAX_HANDSHAKE_TIMEOUTS && forceReconnect(opts.socket)) {
-			opts.onRetry();
-			return;
-		}
-		opts.onExhausted();
-	}
-	opts.signal.addEventListener("abort", disarm);
-	return {
-		arm() {
-			disarm();
-			timer = setTimeout(fire, HANDSHAKE_TIMEOUT_MS);
-		},
-		disarm,
-		succeeded() {
-			disarm();
-			timeouts = 0;
-		}
-	};
-}
-//#endregion
 //#region src/session/messages.ts
 /**
 * Incoming-message handling for the voice session core.
@@ -1124,7 +1282,7 @@ function appendCapped(list, item, cap) {
 * `ConnState.turn`).
 */
 function createMessageHandlers(deps) {
-	const { getSnapshot, updateState, conn, agentState, audio } = deps;
+	const { getSnapshot, updateState, conn, agentState, audio, retire } = deps;
 	/** Monotonically increasing counter for custom events -- used by useEvent to deduplicate. */
 	let customEventSeq = 0;
 	/** Monotonically increasing counter for chat messages -- stable render keys
@@ -1332,7 +1490,7 @@ function createMessageHandlers(deps) {
 			case "error.reported":
 				handleErrorEvent(e);
 				break;
-			case "session.timedOut": conn.retiredByServer = true;
+			case "session.timedOut": retire();
 		}
 	}
 	/** Enqueue a PCM16 audio chunk for playback. Transitions state to `"speaking"` on the first chunk. */
@@ -1895,10 +2053,8 @@ function createBrowserSessionWith(options, internals) {
 	const agentState = createSessionStateMachine();
 	const conn = {
 		ws: null,
-		retiredByServer: false,
 		turn: createEpoch()
 	};
-	let connectionController = null;
 	const identity = createSessionIdentity(options, () => dialer);
 	const dialer = createDialer({
 		...options,
@@ -1941,17 +2097,9 @@ function createBrowserSessionWith(options, internals) {
 		updateState,
 		conn,
 		agentState,
-		audio
+		audio,
+		retire: () => connection.retire()
 	});
-	/** Abort the in-flight connection and release audio + WebSocket resources. */
-	function teardownConnection() {
-		connectionController?.abort();
-		connectionController = null;
-		preConnect.release();
-		audio.teardown();
-		conn.ws?.close();
-		conn.ws = null;
-	}
 	/**
 	* React to the server's `session.configured` frame: record it and set up the
 	* session's audio path. **It no longer replays history, and that is the
@@ -1966,78 +2114,43 @@ function createBrowserSessionWith(options, internals) {
 		flushQueued();
 		audio.start(config);
 	}
-	function connect(opts) {
-		if (opts?.signal?.aborted) {
-			disconnect();
-			return;
-		}
-		updateState(agentState.apply({ type: "CONNECT" }));
-		teardownConnection();
-		preConnect.begin();
-		conn.retiredByServer = false;
-		const controller = new AbortController();
-		connectionController = controller;
-		const { signal: sig } = controller;
-		if (opts?.signal) opts.signal.addEventListener("abort", () => disconnect(), { signal: sig });
-		const socket = dialer.open();
-		socket.binaryType = "arraybuffer";
-		conn.ws = socket;
-		let socketErrored = false;
-		const handshake = createHandshakeGuard({
-			socket,
-			signal: sig,
-			onRetry: () => {
-				audio.teardown();
-				updateState({
-					...agentState.apply({ type: "CONNECT" }),
-					recording: false
-				});
-			},
-			onExhausted: () => {
-				preConnect.release();
-				audio.teardown();
-				controller.abort();
-				socket.close();
-				conn.ws = null;
-				updateState({
-					...agentState.apply({
-						type: "FAILED",
-						error: HANDSHAKE_ERROR
-					}),
-					...STOPPED
-				});
-			}
-		});
-		socket.addEventListener("open", () => {
-			updateState(agentState.apply({ type: "SOCKET_OPEN" }));
-			handshake.arm();
-		}, { signal: sig });
-		socket.addEventListener("message", (event) => {
-			const config = handleMessage(event.data);
-			if (!config) return;
-			handshake.succeeded();
-			onServerConfig(config);
-		}, { signal: sig });
-		socket.addEventListener("error", () => {
-			socketErrored = true;
-		}, { signal: sig });
-		socket.addEventListener("close", (event) => {
-			if (sig.aborted) return;
-			handshake.disarm();
-			audio.teardown();
-			if (!(conn.retiredByServer || agentState.fatal()) && reconnectPending(socket)) {
-				socketErrored = false;
-				updateState({
-					...agentState.apply({ type: "CONNECT" }),
-					recording: false
-				});
-				return;
-			}
+	/**
+	* The socket, the handshake deadline over it and the server's idle
+	* retirement, as a statechart — see `session/connection.ts`. `release` is the
+	* exit action of its `open` state, so every way a connection ends shares it.
+	*/
+	const connection = createConnection({
+		dial: () => {
+			preConnect.begin();
+			const socket = dialer.open();
+			socket.binaryType = "arraybuffer";
+			conn.ws = socket;
+			return socket;
+		},
+		release: (socket) => {
 			preConnect.release();
-			controller.abort();
+			audio.teardown();
 			socket.close();
 			conn.ws = null;
-			const failure = closeFailure(event, socketErrored);
+		},
+		abandon: () => disconnect(),
+		receive: handleMessage,
+		opened: () => updateState(agentState.apply({ type: "SOCKET_OPEN" })),
+		configured: onServerConfig,
+		fatal: () => agentState.fatal(),
+		retryPending: reconnectPending,
+		canRedial: () => canReconnect(conn.ws),
+		redial: () => {
+			forceReconnect(conn.ws);
+		},
+		retrying: () => {
+			audio.teardown();
+			updateState({
+				...agentState.apply({ type: "CONNECT" }),
+				recording: false
+			});
+		},
+		closed: (failure) => {
 			updateState({
 				...failure === null ? agentState.apply({ type: "CLOSED" }) : agentState.apply({
 					type: "FAILED",
@@ -2049,7 +2162,24 @@ function createBrowserSessionWith(options, internals) {
 				}),
 				...STOPPED
 			});
-		}, { signal: sig });
+		},
+		exhausted: () => {
+			updateState({
+				...agentState.apply({
+					type: "FAILED",
+					error: HANDSHAKE_ERROR
+				}),
+				...STOPPED
+			});
+		}
+	});
+	function connect(opts) {
+		if (opts?.signal?.aborted) {
+			disconnect();
+			return;
+		}
+		updateState(agentState.apply({ type: "CONNECT" }));
+		connection.dial(opts?.signal);
 	}
 	function cancel() {
 		if (!openSocket()) return;
@@ -2079,7 +2209,7 @@ function createBrowserSessionWith(options, internals) {
 		start();
 	}
 	function disconnect() {
-		teardownConnection();
+		connection.hangUp();
 		updateState({
 			...agentState.apply({ type: "DISCONNECT" }),
 			...STOPPED
@@ -2100,7 +2230,7 @@ function createBrowserSessionWith(options, internals) {
 		}
 	}
 	function end() {
-		teardownConnection();
+		connection.hangUp();
 		dialer.forget();
 		updateState({
 			...CLEARED_SESSION_STATE,

package/dist/upload/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * The workflow hooks' upload machinery, as the rest of the package sees it:
  * claiming an id per file and transferring it (`files.ts`), the pause gate
- * (`session.ts`, `pause.ts`), the reload recall (`recall.ts`) and the report
+ * (`session.ts` — the buttons over it are the form's statechart,
+ * `../_workflow-form-state.ts`), the reload recall (`recall.ts`) and the report
  * coalescing (`report.ts`). Everything not re-exported here is private to
  * `upload/` — guard-invariants rule 37 fails an import from outside it that
  * names any module but this one.
@@ -9,7 +10,6 @@
  * @module
  */
 export { createUploadSession, type UploadSession, uploadFiles } from "./files.ts";
-export { useUploadPause } from "./pause.ts";
 export { recallUploadId, rememberUploadId } from "./recall.ts";
 export { coalesceUploadReports } from "./report.ts";
 export { createUploadGate, randomUploadId, sendThroughGate, type UploadGate, } from "./session.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "use-stick-to-bottom": "^1.1.6",
     "use-sync-external-store": "^1.7.0",
     "xstate": "^5.33.2",
-    "@alexkroman1/aai": "0.14.1"
+    "@alexkroman1/aai": "0.14.2"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",

package/dist/upload/pause.d.ts

@@ -1,31 +0,0 @@
-/**
- * The two buttons a page puts over a live upload, bound to whichever gate the
- * submission is currently holding.
- *
- * `useWorkflowSubmit` and `useWorkflowStream` both own an {@link UploadGate} and
- * both reported the pause the same way: park the gate, then fold `paused` into
- * the status the bar is already drawing. Folded rather than replaced, because
- * everything else about that status — which file, how far, of how many — is
- * still true. Two copies of that rule are two copies that can stop agreeing
- * about what a paused bar says.
- */
-import { type Dispatch, type SetStateAction } from "react";
-import type { UploadStatus } from "../use-workflow-form.ts";
-import type { UploadGate } from "./session.ts";
-/** What {@link useUploadPause} returns — see {@link WorkflowSubmission}. */
-export type UploadPause = {
-    /** Stop the bytes in flight and hold the uploader. */
-    pauseUpload: () => void;
-    /** Send whatever the store is still missing. */
-    resumeUpload: () => void;
-};
-/**
- * Bind pause/resume to the live submission's gate.
- *
- * @param getGate - Reads the gate out of the caller's ref, so the callbacks stay
- *   stable across submissions rather than being re-created per gate.
- * @param setUpload - The status setter the progress bar renders from.
- *
- * @internal
- */
-export declare function useUploadPause(getGate: () => UploadGate | undefined, setUpload: Dispatch<SetStateAction<UploadStatus | undefined>>): UploadPause;