@alexkroman1/aai-ui 0.12.3 → 0.13.0

package/dist/session/dial.d.ts

@@ -0,0 +1,65 @@
+/**
+ * How the next connection attempt is DIALLED, and the resume identity it dials
+ * with.
+ *
+ * Split out of `session/browser-session.ts` at the 500-line cap, along the seam that file
+ * already established when it moved socket plumbing into
+ * `session/reconnect.ts`: the state machine there reads as protocol logic,
+ * and this is the address it sends it to. What makes it one module rather than
+ * three extracted functions is that the three pieces of mutable state involved —
+ * the session id, whether this connection has ever completed a handshake, and
+ * whether the server is a broker — are read by nothing else in the core, and
+ * every one of them is only meaningful in the sentence "the URL for the next
+ * attempt".
+ */
+import type { WebSocketConstructor } from "../types.ts";
+import { type SessionTokenOption } from "./ticket.ts";
+/** What the dialer needs from the session's options. */
+export type DialOptions = {
+    platformUrl: string;
+    /** Tests inject one; it connects to the same-origin path and never reconnects. */
+    WebSocket?: WebSocketConstructor | undefined;
+    /** An id the caller manages itself — wins over what a previous load stored. */
+    resumeSessionId?: string | undefined;
+    /** Where the client is — see `VoiceSessionOptions.location`. Read per attempt. */
+    location?: string | (() => string | undefined) | undefined;
+    /** The owner's number — see `VoiceSessionOptions.phone`. Read per attempt. */
+    phone?: string | (() => string | undefined) | undefined;
+    /** This client's device id — see `VoiceSessionOptions.client`. Read per attempt. */
+    client?: string | (() => string | undefined) | undefined;
+    /** The session ticket — see `VoiceSessionOptions.token`. Asked per attempt. */
+    token?: SessionTokenOption;
+};
+export type Dialer = {
+    /** A socket for this attempt. */
+    open(): InstanceType<WebSocketConstructor>;
+    /**
+     * A completed handshake: adopt the server's session id and record that this
+     * connection has been established, so every later attempt resumes.
+     */
+    configured(sid: string): void;
+    /** A ticket for another socket on this server — `SessionIdentity.ticket`. */
+    ticket(): string | undefined | Promise<string | undefined>;
+    /** Drop the resume identity, so the next connect is a NEW session. */
+    forget(): void;
+    /**
+     * The session id a `config` frame CONFIRMED — `session.identity.sessionId()`.
+     * Not the resume identity above: that one is seeded from storage and from
+     * `resume(id)` before any server has said the session exists, and a page
+     * keying its history off an id no server confirmed files it under a guess.
+     */
+    sessionId(): string | undefined;
+    /**
+     * Make `sid` the resume identity — presented as `?sessionId=` by the next
+     * attempt and stored as a `config` frame's would be — so the next connect
+     * resumes THAT session. The caller has validated it.
+     */
+    adopt(sid: string): void;
+};
+/**
+ * @param onSessionId - Told whenever the CONFIRMED id changes (a `config` frame
+ *   with a new id, `forget()`), so the session can notify `useSessionId()`
+ *   even when no snapshot field moved with it.
+ * @internal
+ */
+export declare function createDialer(options: DialOptions, onSessionId?: () => void): Dialer;

package/dist/session/handshake.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The deadline on a socket that opened but never became a session.
+ *
+ * A completed WebSocket handshake is not a session. The server builds the
+ * session synchronously from its own upgrade callback and sends `config` at
+ * zero RTT (`aai/host/ws-handler.ts`), so a socket that has been open for
+ * seconds with nothing on it is not slow — its peer is not a healthy agent
+ * server. That happens: a tunnel or proxy answers the `101` while the guest
+ * behind it is wedged, or the host dies between accepting and building the
+ * session.
+ *
+ * Nothing else catches it. partysocket's `connectionTimeout` covers only the
+ * handshake and is cleared the moment `open` fires, so the session reached
+ * `state: "ready"` — painted with the same live indicator the UI gives
+ * "listening" — and stayed there permanently: no `config` means
+ * `initAudioCapture` never runs, so there is no mic, no error, no retry, and
+ * 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.
+ */
+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;
+};
+/**
+ * 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
+ */
+export declare function createHandshakeGuard(opts: {
+    socket: unknown;
+    signal: AbortSignal;
+    onRetry: () => void;
+    onExhausted: () => void;
+}): HandshakeGuard;

package/dist/session/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The browser session core's import surface for the rest of the package.
+ *
+ * `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
+ * 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.
+ *
+ * @module
+ */
+export { loadAudioModules } from "./audio-setup.ts";
+export { createBrowserSession } from "./browser-session.ts";
+export { CLEARED_SESSION_STATE } from "./messages.ts";
+export { resolveSessionToken, resolveSessionTokenSync, ticketCarriage } from "./ticket.ts";
+export type { AgentCustomEvent, AgentStateFrame, BrowserSession, browserSessionBrand, SendTextOptions, SessionSnapshot, ToolCallOutcome, UserTurnControls, } from "./types.ts";

package/dist/session/index.js

@@ -0,0 +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-CE0Ipsb3.js";
+export { CLEARED_SESSION_STATE, createBrowserSession, loadAudioModules, resolveSessionToken, resolveSessionTokenSync, ticketCarriage };

package/dist/session/messages.d.ts

@@ -0,0 +1,63 @@
+import type { AudioPath } from "./audio-state.ts";
+import type { SessionStateMachine } from "./state.ts";
+import { type ConnState, type SessionSnapshot } from "./types.ts";
+/**
+ * Snapshot fields cleared when a session's conversation state is wiped —
+ * shared by the initial snapshot, `resetState()`, and `session.reset`.
+ * The empty arrays are safe to share: snapshot collections are never mutated
+ * in place, only replaced.
+ */
+export declare const CLEARED_SESSION_STATE: {
+    messages: never[];
+    toolCalls: never[];
+    customEvents: never[];
+    agentState: null;
+    userTranscript: null;
+    agentTranscript: null;
+    error: null;
+};
+/** Config payload extracted from a `config` server message. */
+export type SessionConfigMessage = {
+    sampleRate: number;
+    ttsSampleRate: number;
+    sid: string;
+};
+/** Dependencies the message handlers need from the owning session core. */
+type MessageHandlerDeps = {
+    getSnapshot: () => SessionSnapshot;
+    updateState: (partial: Partial<SessionSnapshot>) => void;
+    conn: ConnState;
+    /** The session's state and error, as one fact — see `session/state.ts`. */
+    agentState: SessionStateMachine;
+    /**
+     * The microphone and the playback queue — see
+     * `session/audio-state.ts`. Frames say what happened (`enqueue`,
+     * `done`, `teardown`); whether the path is up, and what to do with audio
+     * that arrives before it is, are the machine's answers rather than this
+     * module's.
+     */
+    audio: AudioPath;
+};
+type MessageHandlers = {
+    /**
+     * Dispatch an incoming WebSocket message.
+     *
+     * Binary frames carry raw PCM16 audio chunks. Text frames are JSON-encoded
+     * {@link SessionEvent} values validated via Zod.
+     *
+     * Returns the parsed config if the message is a `config` message,
+     * otherwise `undefined`.
+     */
+    handleMessage(data: unknown): SessionConfigMessage | undefined;
+};
+/**
+ * Create the server→client message handlers for one session core.
+ *
+ * Encapsulates the per-session dedup counters (`customEventSeq`,
+ * `messageSeq`, `toolCallSeq`) that previously lived as closure locals in
+ * `createBrowserSession`. The turn-boundary epoch is NOT one of them: it lives
+ * on `conn` because the session core bumps it on teardown too (see
+ * `ConnState.turn`).
+ */
+export declare function createMessageHandlers(deps: MessageHandlerDeps): MessageHandlers;
+export {};

package/dist/session/mic.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The microphone's way onto the wire — backpressure, and the caller's MUTE.
+ *
+ * Split out of `session/browser-session.ts` at the source-length cap, along the seam the
+ * two share: both decide what a captured frame becomes on the socket, and
+ * nothing else in the core reads either.
+ *
+ * ## A muted frame is SILENCE, not an absent frame
+ *
+ * `setMicMuted(true)` keeps sending every frame the capture worklet produces,
+ * at the same length and cadence, zero-filled. Sending nothing would look
+ * cheaper and is wrong on three counts:
+ *
+ * - **Endpointing.** Hold-to-talk over an agent with AUTOMATIC turn detection
+ *   is mute-until-pressed, unmute, speak, mute on release. The transcriber
+ *   ends the turn on a stretch of silence; a stream that simply stops gives it
+ *   no silence to measure, so the last utterance is answered late or not at
+ *   all.
+ * - **The stream clock.** The transcriber timestamps by samples received. The
+ *   runtime's own push-to-talk silences the mic the same way, for the same
+ *   reason (`aai-runtime/src/transports/pipeline/commands.ts`, "sent as SILENCE rather than
+ *   withheld").
+ * - **Idle.** Nothing is gained on the server side by going quiet: the session
+ *   idle deadline deliberately does not count user audio (`ServerSession.onAudio`
+ *   in the runtime), so a muted caller is retired exactly as a silent one is —
+ *   while a provider that closes a socket fed no audio at all would see a gap.
+ *
+ * ## It is UI state, not connection state
+ *
+ * The flag lives on the snapshot (`micMuted`) and nothing that tears a
+ * connection down touches it — not a reconnect, a resume, `disconnect()`,
+ * `reset()` or `end()` — and it can be set before the first `connect()`, so a
+ * UI can open a typed-only session already muted. Muting sends no command and
+ * interrupts nothing; it only changes what the next frame carries.
+ *
+ * It sits AFTER the capture worklet, so the worklet's own digital-silence
+ * probe (`onMicSilent`, `MIC_SILENCE_PROBE_MS` in `audio/voice-io.ts`) still measures
+ * the real input: zeros this module writes can never read as a dead mic.
+ *
+ * @module
+ */
+import type { ConnState, SessionSnapshot } from "./types.ts";
+/** What the mic sender needs from the session around it. @internal */
+export type MicDeps = {
+    conn: ConnState;
+    snapshot: () => SessionSnapshot;
+    updateState: (partial: Partial<SessionSnapshot>) => void;
+};
+/** The mic's wire half — see this module's doc. @internal */
+export type MicSender = {
+    /** Send one captured PCM16 frame — as silence while muted. */
+    sendAudio(bytes: ArrayBuffer): void;
+    /**
+     * Send the pre-connect burst (`session/preconnect.ts`) — muted like
+     * any frame, but past the backpressure drop: those frames are the audio the
+     * burst exists to deliver, bounded by `PRE_CONNECT_MAX_SECONDS`, and a
+     * dropped one would splice the caller's opener mid-word.
+     */
+    sendBuffered(chunks: ArrayBuffer[]): void;
+    /** Mute or unmute the caller. Idempotent, local, and connection-independent. */
+    setMicMuted(muted: boolean): void;
+};
+/** Build one session's mic sender. @internal */
+export declare function createMicSender(deps: MicDeps): MicSender;

package/dist/session/preconnect.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pre-connect audio: the microphone opens when the caller presses start, not
+ * when the server's `config` frame arrives, and what they say in between is
+ * sent ahead of the live stream.
+ *
+ * Without it the mic is requested only once `config` names the audio rates —
+ * a handshake after the press, plus a sandbox boot on the platform — so an
+ * eager "hi, I need to…" spoken while the agent is still joining never reaches
+ * the server. The capture runs at {@link PRE_CONNECT_SAMPLE_RATE}, a guess
+ * `createVoiceIO` adopts whole when right and resamples when not (`audio/preconnect.ts`).
+ *
+ * ## Who owns the microphone
+ *
+ * This holder, from `begin()` until `take()`; the audio path's bring-up after
+ * that (`session/audio-setup.ts`), which releases it if the bring-up is
+ * abandoned. A reconnect BEFORE `config` keeps the capture buffering — that is
+ * exactly the audio this exists for — so only the session's terminal paths
+ * call `release()`.
+ *
+ * @module
+ */
+import type { PreConnectCapture } from "../audio/index.ts";
+/**
+ * The rate the capture guesses: the SDK's default STT rate
+ * (`DEFAULT_STT_SAMPLE_RATE`), which is also the only rate an AssemblyAI S2S
+ * agent accepts. A miss costs a resample of the buffer, not the audio.
+ */
+export declare const PRE_CONNECT_SAMPLE_RATE = 16000;
+/**
+ * The most pre-connect audio held — the LATEST this many seconds. Bounds a
+ * cold sandbox boot or a stalled handshake; at 16 kHz it is 320 KB, well
+ * inside the server's pre-ready buffer (`MAX_WS_PAYLOAD_BYTES`).
+ */
+export declare const PRE_CONNECT_MAX_SECONDS = 10;
+/** The session core's handle on its pre-connect capture. @internal */
+export type PreConnectAudio = {
+    /**
+     * Prefetch the audio modules, then open the mic and start buffering unless
+     * a capture is already held (or the session opted out).
+     */
+    begin(): void;
+    /** Hand the held capture to a bring-up, or `null` when none is held. */
+    take(): Promise<PreConnectCapture | null> | null;
+    /** Release a held capture: the session is over or starting afresh. */
+    release(): void;
+};
+/** Build one session's pre-connect capture holder. @internal */
+export declare function createPreConnectAudio(enabled: boolean): PreConnectAudio;

package/dist/session/reconnect.d.ts

@@ -0,0 +1,25 @@
+import type { WebSocketConstructor } from "../types.ts";
+/**
+ * Open partysocket's reconnecting WebSocket. The URL and the subprotocols are
+ * *providers*, re-evaluated on every attempt (async supported), so each retry
+ * picks up the current broker-named endpoint, resume URL and session ticket
+ * rather than the ones the session started with. partysocket calls the URL
+ * provider first and the protocols provider straight after it, in the same
+ * tick, for each attempt.
+ */
+export declare function openReconnectingSocket(urlProvider: () => Promise<string>, protocolsProvider?: () => Promise<string[] | null>): InstanceType<WebSocketConstructor>;
+/**
+ * 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.
+ * Returns false for an injected `options.WebSocket` (tests), which has no
+ * reconnect machinery — the caller then treats the failure as terminal.
+ */
+export declare function forceReconnect(socket: unknown): boolean;
+/**
+ * True while `socket` is a reconnecting socket that will retry after the
+ * close event currently being handled. partysocket schedules the retry
+ * *before* dispatching `close`, so `retryCount` already names the attempt
+ * just scheduled — at `maxRetries` it has given up.
+ */
+export declare function reconnectPending(socket: unknown): boolean;

package/dist/session/resume-store.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Where a session id survives a page RELOAD.
+ *
+ * The id is what `?sessionId=` presents on reconnect, and it is the key the
+ * agent's slot state and event log live under — so a reload that cannot produce
+ * it starts a brand-new session, and a UI driven by `useAgentState` comes back
+ * empty even though the agent still holds the cart. The server side of the
+ * reconstitution was already built (`pushStateSnapshot` force-pushes the
+ * projection after hydration on every start, `state.updated` lands in
+ * `agentState`); what was missing is that nothing in the browser remembered the
+ * id across a reload. `onSessionId`/`resumeSessionId` let a client wire it by
+ * hand and exactly one of fourteen templates did, which is the shape of a
+ * default in the wrong place.
+ *
+ * **`sessionStorage`, deliberately, and this is the opposite call from the
+ * studio's session token.** A reload and a same-tab navigation survive it; a new
+ * tab and a visit tomorrow do not, which is what we want here rather than a
+ * limitation: presenting a day-old id suppresses the greeting
+ * (`parseWsUpgradeParams` keys that off the id's mere presence) and rejoins a
+ * conversation whose context is long gone. The studio token is a credential
+ * whose value is not being asked to sign out; this is a pointer into a live call.
+ *
+ * Keyed by the agent's own URL, so two agents served from one origin — which is
+ * every deployed agent, at `/:slug/` — cannot inherit each other's session.
+ *
+ * Every access is guarded, and the guard lives in `_web-storage.ts`: a session
+ * that cannot be remembered must degrade to today's behaviour rather than
+ * failing to start.
+ */
+/** The stored session id for this agent, or undefined. @internal */
+export declare function readStoredSessionId(platformUrl: string): string | undefined;
+/** Remember this agent's session id for the next load. @internal */
+export declare function writeStoredSessionId(platformUrl: string, sessionId: string): void;
+/**
+ * Forget it, so the next load is a NEW session.
+ *
+ * Called from `end()`, which is the clear-and-forget the "New Conversation"
+ * button runs: leaving the id behind there would have the next load rejoin the
+ * conversation the user just discarded, greeting suppressed.
+ *
+ * @internal
+ */
+export declare function clearStoredSessionId(platformUrl: string): void;
+/**
+ * The last session ticket this agent's `client-config` issued — beside the id
+ * and for its reason: on the managed platform a ticket is BOUND to its session,
+ * and presenting it (`SESSION_TICKET_HEADER`) is what makes the broker re-mint
+ * for that session rather than a new one, so a reload that lost it cannot
+ * resume. As sensitive as the id it stands beside, and stored the same way.
+ *
+ * @internal
+ */
+export declare function readStoredTicket(platformUrl: string): string | undefined;
+/** Remember the last server-issued ticket. @internal */
+export declare function writeStoredTicket(platformUrl: string, ticket: string): void;
+/** Forget it, with the session it was for. @internal */
+export declare function clearStoredTicket(platformUrl: string): void;

package/dist/session/state.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The browser session's {@link AgentState}, and the error beside it, as a
+ * statechart.
+ *
+ * These two were written independently from thirteen sites across
+ * `session/browser-session.ts`, `session/messages.ts` and
+ * `session/audio-setup.ts`, each one deciding for itself whether its write
+ * was legal by reading the snapshot back first. Three shipped bugs came out of
+ * that, and all three are the same shape — a transition nothing forbade:
+ *
+ * - **A straggler audio chunk flipped an errored session to `"speaking"`.**
+ *   Guarded by hand at the call site
+ *   (`if (snap.state === "error" || (snap.state === "disconnected" && …))`).
+ *   Here `error` simply does not handle `SPEAK`.
+ * - **The frame that announced a session's death also wiped the banner
+ *   reporting it.** Every fatal path in the host tears the transport down, and
+ *   tearing down EMITS — so `reply.cancelled` arrived right behind the error and
+ *   `toListening()` painted a live-mic state over it. A missing provider key is
+ *   the case that made it visible: the one message that says exactly what to fix
+ *   was on screen for a few hundred milliseconds and left a session that looked
+ *   live and was deaf.
+ * - **A later frame RECOVERED the state.** `clearRecoveredError` reads a
+ *   non-error frame as proof the session works, which is right for a
+ *   turn-level failure and wrong for a server error that ended the call.
+ *
+ * The second and third were fixed with a `conn.fatalError` boolean that every
+ * writer had to remember to consult. It is the `fatal` region here, so
+ * forgetting is not available: `LISTEN` and `ACTIVITY` are declined in one
+ * place rather than at each of their five call sites.
+ *
+ * ## Two regions, because the fatal latch OUTLIVES the error state
+ *
+ * `fatal` is not a substate of `error`, tempting as that looks. It is cleared by
+ * exactly one thing — the next `config` frame, i.e. a completed handshake — and
+ * that is per CONNECTION rather than per session, so a reconnect that really
+ * works is not pinned to a dead session's banner. Between the error and that
+ * frame the phase runs `error → connecting → ready` while the latch stays set,
+ * which a substate cannot express.
+ *
+ * ## The published surface is unchanged
+ *
+ * {@link AgentState} is a public type in the versioned `aai-ui:session`
+ * capability, so {@link AgentStateSnapshot.state} is one of its seven names and
+ * nothing here widens it. The internal distinctions live in the second region
+ * and in context, not in the projection.
+ */
+import type { AgentState, SessionError } from "../types.ts";
+/** What the session core folds into its snapshot after each transition. */
+export type AgentStateSnapshot = {
+    state: AgentState;
+    error: SessionError | null;
+};
+/**
+ * Everything that moves the session's state.
+ *
+ * Named for what HAPPENED rather than for the state wanted, which is the point:
+ * `reply.cancelled` sends `LISTEN` and gets `"error"` back when the session is
+ * fatally over, and the caller neither knows nor needs to.
+ */
+export type AgentStateEvent = 
+/** A connect attempt started — including a reconnect or a handshake retry. */
+{
+    type: "CONNECT";
+}
+/** The socket opened; the handshake has not completed yet. */
+ | {
+    type: "SOCKET_OPEN";
+}
+/** A completed handshake: a live session, whatever ended the last one. */
+ | {
+    type: "HANDSHAKE_COMPLETE";
+}
+/** A turn boundary, or the audio path coming up: back to the mic. */
+ | {
+    type: "LISTEN";
+}
+/** A reset: back to the mic AND the conversation cleared. */
+ | {
+    type: "RESET";
+}
+/** The agent is working. */
+ | {
+    type: "THINK";
+}
+/** Audio for this turn reached the client. */
+ | {
+    type: "SPEAK";
+}
+/** A non-error frame arrived, so the session demonstrably works. */
+ | {
+    type: "ACTIVITY";
+}
+/** A turn-level failure: a banner over a session that keeps running. */
+ | {
+    type: "TURN_ERROR";
+    error: SessionError;
+}
+/** The session is over. */
+ | {
+    type: "FATAL";
+    error: SessionError;
+}
+/**
+ * A failure that stops the session but might not be the end of it: the
+ * handshake exhausting its retries, a socket error close, or the audio path
+ * dying. The `fatal` latch stays clear, so a later non-error frame recovers
+ * — which is right for a client-side failure and is exactly what a FATAL
+ * server error must not get.
+ */
+ | {
+    type: "FAILED";
+    error: SessionError;
+}
+/** The socket closed for good. */
+ | {
+    type: "CLOSED";
+}
+/** The caller hung up. */
+ | {
+    type: "DISCONNECT";
+}
+/** The caller ended the session and forgot it. */
+ | {
+    type: "END";
+};
+/** The session core's handle on its own state. */
+export type SessionStateMachine = {
+    /** The published state and the error beside it. */
+    snapshot(): AgentStateSnapshot;
+    /**
+     * Apply `event` and return the resulting projection.
+     *
+     * Returns rather than writes so the caller folds it into ONE `updateState`
+     * call: a snapshot is published on every write, and splitting one transition
+     * into two would let a subscriber render half of it.
+     */
+    apply(event: AgentStateEvent): AgentStateSnapshot;
+    /**
+     * Is the session fatally over? Asked by the one caller that has to clear the
+     * CONVERSATION and not merely the state — a `session.reset` on a dead session
+     * keeps its whole banner.
+     */
+    fatal(): boolean;
+};
+/** Create the state machine for one browser session. */
+export declare function createSessionStateMachine(): SessionStateMachine;

package/dist/session/ticket.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The session ticket one connection attempt presents — `VoiceSessionOptions.token`,
+ * else the `sessionToken` a server's `client-config` issued.
+ *
+ * A browser cannot set headers on a WebSocket, so the ticket rides the
+ * `Sec-WebSocket-Protocol` list as `aai.auth.<ticket>`, offered AFTER the plain
+ * `aai.session` protocol: a browser fails any handshake whose response selects
+ * none of its offers, and the server (`selectSessionProtocol` in
+ * `@alexkroman1/aai-runtime/auth`) selects the plain one so the ticket is never
+ * echoed back. A server older than tickets selects the first offer, which is
+ * the plain one too, so offering a ticket never fails a handshake.
+ *
+ * A value that is not a valid subprotocol token (RFC 6455 §4.1 — an HTTP
+ * token) would make `new WebSocket` throw, so it travels as `?token=` instead,
+ * the server's fallback. A minted ticket is base64url with one dot, and so is a
+ * JWT: neither takes that path.
+ */
+import type { VoiceSessionOptions } from "../types.ts";
+/** The shape of `VoiceSessionOptions.token`. */
+export type SessionTokenOption = VoiceSessionOptions["token"];
+/** What the getter is told about the attempt it serves: the session it resumes. */
+export type SessionTokenAttempt = {
+    readonly sessionId: string | undefined;
+};
+/** How one attempt carries its ticket: subprotocols, or the `?token=` fallback. */
+export type TicketCarriage = {
+    protocols?: string[];
+    queryToken?: string;
+};
+/**
+ * Ask the `token` option for THIS attempt's ticket. A getter that throws or
+ * rejects yields none — the attempt still dials, and a server that requires a
+ * ticket refuses it with a reason the session reports, rather than the attempt
+ * failing before a socket exists (partysocket reports a provider failure as an
+ * `error` with no `close`, which would leave the session on "connecting").
+ */
+export declare function resolveSessionToken(option: SessionTokenOption, attempt: SessionTokenAttempt): Promise<string | undefined>;
+/**
+ * The same, for an injected `WebSocket` constructor: that path opens its socket
+ * synchronously, so an asynchronous getter cannot be awaited there.
+ */
+export declare function resolveSessionTokenSync(option: SessionTokenOption, attempt: SessionTokenAttempt): string | undefined;
+/** How `token` travels on one attempt; nothing at all when there is no ticket. */
+export declare function ticketCarriage(token: string | undefined): TicketCarriage;