@alexkroman1/aai-ui 4.0.0 → 5.0.1

package/dist/default-client/assets/{playback-processor-HeyncQUX.js → playback-processor-C_F19eUJ.js}

@@ -1,4 +1,4 @@
-import{i as e}from"./index-CkZ6t_eJ.js";import{t}from"./_module-url-BX0RuRU2.js";var n=t(`
+import{i as e}from"./index-RQnhfgSS.js";import{t}from"./_module-url-BX0RuRU2.js";var n=t(`
 class PlaybackProcessor extends AudioWorkletProcessor {
   constructor(options) {
     super();

package/dist/default-client/index.html

@@ -6,7 +6,7 @@
     <title>aai</title>
     <link rel="icon" href="./favicon.ico" />
     <style>html, body { background: #FBF8F2; margin: 0; }</style>
-    <script type="module" crossorigin src="./assets/index-CkZ6t_eJ.js"></script>
+    <script type="module" crossorigin src="./assets/index-RQnhfgSS.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-CRfdZPH1.css">
   </head>
   <body>

package/dist/define-client.d.ts

@@ -46,7 +46,18 @@ type ConfigTier = BaseOptions & {
 type ComponentTier = BaseOptions & {
     /** Full custom component to render instead of the default shell. */
     component: ComponentType;
-    name?: never;
+    /**
+     * Agent name. With a custom component there is no shell header to put it
+     * in, so it becomes the page title.
+     *
+     * Allowed here rather than `never` because `client({ name, component })` is
+     * the natural thing to write and two different models wrote it. As `never`
+     * it failed with *"Type 'string' is not assignable to type 'undefined'"*,
+     * which explains nothing, and cost a build round each time. There is a real
+     * use for the value — a custom-UI page otherwise inherits whatever title
+     * the HTML shell shipped with — so it is honoured instead of banned.
+     */
+    name?: string;
     sidebar?: never;
     sidebarWidth?: never;
     tools?: never;

package/dist/define-client.js

@@ -1,5 +1,121 @@
-import { t as client } from "./define-client-DqRs1XPd.js";
-import "./context.js";
-import "./components/sidebar-layout.js";
-import "./components/start-screen.js";
+import { r as fetchClientConfig, t as createSessionCore } from "./session-core-ByBLnLfW.js";
+import { SessionProvider, ThemeProvider } from "./context.js";
+import { t as ChatView } from "./chat-view-CW-tZCMm.js";
+import { n as ToolConfigContext } from "./tool-call-block-DIxpG8GM.js";
+import { SidebarLayout } from "./components/sidebar-layout.js";
+import { StartScreen } from "./components/start-screen.js";
+import { createElement, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+//#region define-client.tsx
+/** @jsxImportSource react */
+function resolveContainer(target = "#app") {
+	if (typeof target !== "string") return target;
+	const el = document.querySelector(target);
+	if (!el) throw new Error(`Element not found: ${target}`);
+	return el;
+}
+/**
+* Default shell rendered in config tier.
+* Wraps StartScreen → (SidebarLayout →) ChatView.
+*/
+function DefaultShell({ name, Sidebar, sidebarWidth }) {
+	const chat = /* @__PURE__ */ jsx(ChatView, { title: name });
+	return /* @__PURE__ */ jsx(StartScreen, {
+		title: name,
+		children: Sidebar ? /* @__PURE__ */ jsx(SidebarLayout, {
+			sidebar: /* @__PURE__ */ jsx(Sidebar, {}),
+			sidebarWidth,
+			children: chat
+		}) : chat
+	});
+}
+/**
+* Config-tier root: fetches the server-declared display name via
+* `GET client-config` and renders the chat shell. The shell renders
+* immediately — optimistically — while the lookup is in flight; servers
+* without the endpoint (every lookup failure resolves to the empty default)
+* work exactly as before.
+*/
+function DefaultRoot({ platformUrl, name, Sidebar, sidebarWidth }) {
+	const [resolved, setResolved] = useState(null);
+	useEffect(() => {
+		let cancelled = false;
+		fetchClientConfig(platformUrl).then((cfg) => {
+			if (!cancelled) setResolved(cfg);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [platformUrl]);
+	return /* @__PURE__ */ jsx(DefaultShell, {
+		name: name ?? resolved?.name,
+		Sidebar,
+		sidebarWidth
+	});
+}
+/**
+* Define and mount a client UI for a voice agent.
+*
+* **Tier 1 (config-only):** Pass options without `component` to get the
+* default shell (StartScreen + ChatView, optional sidebar).
+*
+* **Tier 2 (custom component):** Pass `component` to render a fully custom
+* root component inside the providers.
+*
+* @example Tier 1
+* ```tsx
+* client({
+*   name: "Pizza Ordering",
+*   theme: { bg: "#1a1a1a", primary: "#e55" },
+*   sidebar: OrderPanel,
+*   tools: { add_pizza: { icon: "🍕", label: "Adding pizza" } },
+* });
+* ```
+*
+* @example Tier 2
+* ```tsx
+* client({ component: MyCustomApp });
+* ```
+*
+* @returns A {@link ClientHandle} for cleanup.
+* @throws If the target element is not found in the DOM.
+*
+* @public
+*/
+function client(config) {
+	const container = resolveContainer(config.target);
+	const platformUrl = config.platformUrl ?? globalThis.location.origin + globalThis.location.pathname;
+	const session = createSessionCore({
+		platformUrl,
+		onSessionId: config.onSessionId,
+		resumeSessionId: config.resumeSessionId,
+		WebSocket: config.WebSocket
+	});
+	if (config.name && typeof document !== "undefined") document.title = config.name;
+	const rootNode = config.component ? createElement(config.component) : createElement(DefaultRoot, {
+		platformUrl,
+		name: config.name,
+		Sidebar: config.sidebar,
+		sidebarWidth: config.sidebarWidth
+	});
+	const toolConfig = config.tools ?? {};
+	const root = createRoot(container);
+	flushSync(() => {
+		root.render(createElement(ToolConfigContext.Provider, { value: toolConfig }, createElement(ThemeProvider, { value: config.theme }, createElement(SessionProvider, { value: session }, rootNode))));
+	});
+	const handle = {
+		session,
+		dispose() {
+			root.unmount();
+			session[Symbol.dispose]();
+		},
+		[Symbol.dispose]() {
+			handle.dispose();
+		}
+	};
+	return handle;
+}
+//#endregion
 export { client };

package/dist/hooks.d.ts

@@ -1,6 +1,44 @@
+import type { DefaultToolResult } from "@alexkroman1/aai";
 import type { ToolCallInfo } from "./types.ts";
-export declare function useToolResult<R = unknown>(toolName: string, callback: (result: R, toolCall: ToolCallInfo) => void): void;
-export declare function useToolResult(callback: (name: string, result: unknown, toolCall: ToolCallInfo) => void): void;
+/**
+ * Fire a callback when a tool call settles, with the tool's JSON result.
+ *
+ * @typeParam R - The result shape. Defaults to {@link DefaultToolResult} —
+ *   `any`, for the same reason `ctx.state` is: the value is the author's own
+ *   tool output round-tripped through JSON, so `unknown` (which this was) made
+ *   the ordinary spelling
+ *
+ *   ```tsx
+ *   useToolResult("get_quote", (r) => setPrice(r.price))
+ *   ```
+ *
+ *   a compile error on a client that runs correctly, and `aai build` refuses
+ *   to publish it. Pass the shape — `useToolResult<Quote>(…)` — to get real
+ *   checking, which also documents what the tool returns.
+ */
+export declare function useToolResult<R = DefaultToolResult>(toolName: string, callback: (result: R, toolCall: ToolCallInfo) => void): void;
+export declare function useToolResult<R = DefaultToolResult>(callback: (name: string, result: R, toolCall: ToolCallInfo) => void): void;
+/**
+ * The agent's projected session state, or `null` before the first push.
+ *
+ * The counterpart to `syncState` on the agent: whatever that projection
+ * returns is what arrives here. It replaces the pattern this exists to
+ * remove — returning a state snapshot from every tool, declaring a type for
+ * what those tools happen to return, and mirroring it into `useState` through
+ * `useToolResult`, which was three things to keep in step and which 58% of
+ * measured generated agents built by hand.
+ *
+ * ```tsx
+ * const cart = useAgentState<{ cart: Item[] }>();
+ * return <Cart items={cart?.cart ?? []} />;
+ * ```
+ *
+ * Typed by the caller for the same reason `useToolResult` is: the shape is
+ * the author's own projection, which the framework cannot see. It is
+ * nullable on purpose — nothing has been pushed before the first tool call,
+ * and a UI has to render that moment.
+ */
+export declare function useAgentState<S = DefaultToolResult>(): S | null;
 export declare function useEvent<T = unknown>(event: string, callback: (data: T) => void): void;
 export declare function useToolCallStart(toolName: string, callback: (toolCall: ToolCallInfo) => void): void;
 export declare function useToolCallStart(callback: (toolCall: ToolCallInfo) => void): void;

package/dist/hooks.js

@@ -77,6 +77,29 @@ function useToolResult(...args) {
 		else callback(tc.name, parsed, tc);
 	});
 }
+/**
+* The agent's projected session state, or `null` before the first push.
+*
+* The counterpart to `syncState` on the agent: whatever that projection
+* returns is what arrives here. It replaces the pattern this exists to
+* remove — returning a state snapshot from every tool, declaring a type for
+* what those tools happen to return, and mirroring it into `useState` through
+* `useToolResult`, which was three things to keep in step and which 58% of
+* measured generated agents built by hand.
+*
+* ```tsx
+* const cart = useAgentState<{ cart: Item[] }>();
+* return <Cart items={cart?.cart ?? []} />;
+* ```
+*
+* Typed by the caller for the same reason `useToolResult` is: the shape is
+* the author's own projection, which the framework cannot see. It is
+* nullable on purpose — nothing has been pushed before the first tool call,
+* and a UI has to render that moment.
+*/
+function useAgentState() {
+	return useSessionSelector((snapshot) => snapshot.agentState);
+}
 function useEvent(event, callback) {
 	const customEvents = useSessionSelector((s) => s.customEvents);
 	const watermarkRef = useRef(0);
@@ -102,4 +125,4 @@ function useToolCallStart(...args) {
 	});
 }
 //#endregion
-export { useEvent, useToolCallStart, useToolResult };
+export { useAgentState, useEvent, useToolCallStart, useToolResult };

package/dist/index.d.ts

@@ -13,8 +13,8 @@ export type { Session } from "./context.ts";
 export { SessionProvider, ThemeProvider, useSession, useSessionSelector, useTheme, } from "./context.ts";
 export type { ClientConfig, ClientHandle, } from "./define-client.tsx";
 export { client } from "./define-client.tsx";
-export { useEvent, useToolCallStart, useToolResult } from "./hooks.ts";
+export { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.ts";
 export { createSessionCore } from "./session-core.ts";
 export type { CustomEvent, SessionCore, SessionCoreOptions, SessionSnapshot, } from "./session-core-types.ts";
-export type { AgentState, ChatMessage, ClientTheme, SessionError, SessionErrorCode, ToolCallInfo, VoiceSessionOptions, WebSocketConstructor, } from "./types.ts";
+export type { AgentState, ChatMessage, ClientTheme, SessionError, SessionErrorCode, ToolCallInfo, VoiceSessionOptions, } from "./types.ts";
 export { VOICE_CAPTURE_CONSTRAINTS } from "./types.ts";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as buildAgentUrl, r as fetchClientConfig, t as client } from "./define-client-DqRs1XPd.js";
+import { n as buildAgentUrl, r as fetchClientConfig, t as createSessionCore } from "./session-core-ByBLnLfW.js";
 import { SessionProvider, ThemeProvider, useSession, useSessionSelector, useTheme } from "./context.js";
 import { Button } from "./components/button.js";
 import { t as ChatView } from "./chat-view-CW-tZCMm.js";
@@ -7,7 +7,7 @@ import { n as Markdown, t as MessageList } from "./message-list-q2lTiFhF.js";
 import { n as ToolConfigContext } from "./tool-call-block-DIxpG8GM.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
-import { t as createSessionCore } from "./session-core-CkZ8LyEA.js";
 import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
-import { useEvent, useToolCallStart, useToolResult } from "./hooks.js";
-export { ApiUrlChip, Button, ChatView, Controls, Markdown, MessageList, SessionProvider, SessionUrlChips, SidebarLayout, StartScreen, ThemeProvider, ToolConfigContext, UiUrlChip, VOICE_CAPTURE_CONSTRAINTS, buildAgentUrl, client, createSessionCore, fetchClientConfig, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult };
+import { client } from "./define-client.js";
+import { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.js";
+export { ApiUrlChip, Button, ChatView, Controls, Markdown, MessageList, SessionProvider, SessionUrlChips, SidebarLayout, StartScreen, ThemeProvider, ToolConfigContext, UiUrlChip, VOICE_CAPTURE_CONSTRAINTS, buildAgentUrl, client, createSessionCore, fetchClientConfig, useAgentState, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult };

package/dist/{session-core-CkZ8LyEA.js → session-core-ByBLnLfW.js}

@@ -1,7 +1,56 @@
 import { MIC_SEND_MAX_BUFFERED_BYTES } from "./types.js";
-import { ServerMessageSchema, lenientParse } from "@alexkroman1/aai/protocol";
-import { DEFAULT_MAX_HISTORY, WS_OPEN, errorMessage, safeJsonParse } from "@alexkroman1/aai";
+import { CLIENT_CONFIG_PATH, ClientConfigResponseSchema, ServerMessageSchema, lenientParse } from "@alexkroman1/aai/protocol";
+import { DEFAULT_MAX_HISTORY, WS_OPEN, createEpoch, errorMessage, safeJsonParse } from "@alexkroman1/aai";
 import ReconnectingWebSocket from "partysocket/ws";
+//#region client-config.ts
+/**
+* Pre-connection client-config lookup.
+*
+* `GET client-config` (relative to the agent's base URL — see
+* `sdk/client-config.ts` in `@alexkroman1/aai`) gives the default client the
+* agent's display name and greeting before any connection exists. For that
+* use every failure path — network error, 404 from an older server,
+* malformed body — degrades to the empty default (`fetchClientConfig`), so
+* the lookup can never break an existing agent.
+*
+* The session's broker decision needs the opposite: `loadClientConfig`
+* keeps "the lookup failed" (`null`) distinct from "the server answered and
+* named no sessionUrl" (`{}`). See its doc comment.
+*/
+/** Resolve a relative endpoint path against the agent's base URL. */
+function buildAgentUrl(platformUrl, endpointPath) {
+	return new URL(endpointPath, platformUrl.endsWith("/") ? platformUrl : `${platformUrl}/`);
+}
+const AGENT_DEFAULT = {};
+/**
+* Fetch the agent's client config, reporting `null` when the lookup did not
+* produce an answer (network error, non-2xx, unparsable body).
+*
+* The distinction from `fetchClientConfig` matters for exactly one caller:
+* the session's per-attempt broker decision. A config that ARRIVED and named
+* no `sessionUrl` means "this server is not a broker" (`aai dev`, an older
+* server) — a durable fact worth latching. A lookup that FAILED means
+* nothing about the server, and treating the two alike is how a single 503
+* (a sandbox mid-boot, or one that failed to start) pinned a session to the
+* platform's `/:slug/websocket` — answered `410 Gone` on every retry, with
+* no re-brokering even after the agent recovered.
+*/
+async function loadClientConfig(platformUrl, fetchFn) {
+	const doFetch = fetchFn ?? ((input, init) => globalThis.fetch(input, init));
+	try {
+		const resp = await doFetch(buildAgentUrl(platformUrl, CLIENT_CONFIG_PATH).href);
+		if (!resp.ok) return null;
+		const parsed = ClientConfigResponseSchema.safeParse(await resp.json());
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+/** Fetch the agent's client config; any failure yields the agent default. */
+async function fetchClientConfig(platformUrl, fetchFn) {
+	return await loadClientConfig(platformUrl, fetchFn) ?? AGENT_DEFAULT;
+}
+//#endregion
 //#region session-core-audio-setup.ts
 /**
 * Audio-path initialization for the voice session core.
@@ -29,8 +78,8 @@ import ReconnectingWebSocket from "partysocket/ws";
 async function initAudioCapture(conn, msg, deps) {
 	if (conn.audioSetupInFlight) return;
 	conn.audioSetupInFlight = true;
-	const gen = conn.generation;
-	const stale = () => conn.generation !== gen || !conn.ws || conn.ws.readyState !== WS_OPEN;
+	const gen = conn.generation.current();
+	const stale = () => !(conn.generation.isCurrent(gen) && conn.ws) || conn.ws.readyState !== WS_OPEN;
 	const reportAudioFailure = (message) => {
 		deps.cleanupAudio();
 		deps.updateState({
@@ -68,7 +117,7 @@ async function initAudioCapture(conn, msg, deps) {
 				console.warn("[aai-ui] microphone is delivering only silence — check the selected input device");
 			},
 			onError: (err) => {
-				if (conn.generation !== gen) return;
+				if (!conn.generation.isCurrent(gen)) return;
 				reportAudioFailure(err.message);
 			}
 		});
@@ -92,7 +141,7 @@ async function initAudioCapture(conn, msg, deps) {
 		if (stale()) return;
 		reportAudioFailure(`Microphone access failed: ${errorMessage(err)}`);
 	} finally {
-		if (conn.generation === gen) conn.audioSetupInFlight = false;
+		if (conn.generation.isCurrent(gen)) conn.audioSetupInFlight = false;
 	}
 }
 //#endregion
@@ -124,6 +173,7 @@ const CLEARED_SESSION_STATE = {
 	messages: [],
 	toolCalls: [],
 	customEvents: [],
+	agentState: null,
 	userTranscript: null,
 	agentTranscript: null,
 	error: null
@@ -137,14 +187,14 @@ function appendCapped(list, item, cap) {
 /**
 * Create the server→client message handlers for one session core.
 *
-* Encapsulates the two turn-boundary counters (`handlerGeneration` for
+* Encapsulates the two turn-boundary counters (`turnEpoch` for
 * discarding stale async audio completions, `customEventSeq` for event
 * dedup) that previously lived as closure locals in `createSessionCore`.
 */
 function createMessageHandlers(deps) {
 	const { getSnapshot, updateState, conn, cleanupAudio } = deps;
-	/** Incremented on each turn boundary -- stale async callbacks compare against this. */
-	let handlerGeneration = 0;
+	/** Bumped on each turn boundary -- stale async callbacks check against this. */
+	const turnEpoch = createEpoch();
 	/** Monotonically increasing counter for custom events -- used by useEvent to deduplicate. */
 	let customEventSeq = 0;
 	/** Monotonically increasing counter for chat messages -- stable render keys
@@ -161,7 +211,7 @@ function createMessageHandlers(deps) {
 		}, MAX_CUSTOM_EVENTS) });
 	}
 	function handleUserTranscriptEvent(text) {
-		handlerGeneration++;
+		turnEpoch.bump();
 		updateState({
 			userTranscript: null,
 			messages: appendCapped(getSnapshot().messages, {
@@ -221,7 +271,7 @@ function createMessageHandlers(deps) {
 		} });
 		else {
 			cleanupAudio();
-			conn.generation++;
+			conn.generation.bump();
 			updateState({
 				state: "error",
 				error: {
@@ -280,7 +330,7 @@ function createMessageHandlers(deps) {
 				updateState({ state: "listening" });
 				break;
 			case "cancelled":
-				handlerGeneration++;
+				turnEpoch.bump();
 				conn.voiceIO?.flush();
 				commitAgentTranscript();
 				updateState({
@@ -289,7 +339,7 @@ function createMessageHandlers(deps) {
 				});
 				break;
 			case "reset":
-				handlerGeneration++;
+				turnEpoch.bump();
 				conn.voiceIO?.flush();
 				updateState({
 					...CLEARED_SESSION_STATE,
@@ -299,6 +349,9 @@ function createMessageHandlers(deps) {
 			case "custom_event":
 				appendCustomEvent(e.event, e.data);
 				break;
+			case "agent_state":
+				updateState({ agentState: e.state });
+				break;
 			case "error":
 				handleErrorEvent(e);
 				break;
@@ -314,12 +367,12 @@ function createMessageHandlers(deps) {
 		else if (conn.preInitAudio.length < MAX_PREINIT_AUDIO_CHUNKS) conn.preInitAudio.push(chunk);
 	}
 	/** See {@link MessageHandlers.settleWhenAudioDrained}. Captures
-	*  `handlerGeneration` so a completion (or failure) that lands after a turn
+	*  `turnEpoch` so a completion (or failure) that lands after a turn
 	*  boundary is discarded instead of overwriting the newer turn's state. */
 	function settleWhenAudioDrained(io) {
-		const gen = handlerGeneration;
+		const gen = turnEpoch.current();
 		io.done().then(() => {
-			if (handlerGeneration !== gen) return;
+			if (!turnEpoch.isCurrent(gen)) return;
 			updateState({ state: "listening" });
 		}).catch((err) => {
 			console.warn("Audio playback done failed:", err);
@@ -328,7 +381,7 @@ function createMessageHandlers(deps) {
 	/**
 	* Signal that the server has finished sending audio for this turn.
 	* Waits for the audio queue to drain, then transitions state to `"listening"`.
-	* Uses the `handlerGeneration` counter to discard stale completions from interrupted turns.
+	* Uses the `turnEpoch` epoch to discard stale completions from interrupted turns.
 	*/
 	function playAudioDone() {
 		const io = conn.voiceIO;
@@ -395,8 +448,9 @@ const RECONNECT_OPTIONS = {
 };
 /**
 * Open partysocket's reconnecting WebSocket. The URL is a *provider*,
-* re-evaluated on every attempt, so each retry picks up the current resume
-* URL rather than the one the session started with.
+* re-evaluated on every attempt (async supported), so each retry picks up
+* the current broker-named endpoint and resume URL rather than the ones the
+* session started with.
 */
 function openReconnectingSocket(urlProvider) {
 	return new ReconnectingWebSocket(urlProvider, void 0, RECONNECT_OPTIONS);
@@ -414,8 +468,21 @@ function reconnectPending(socket) {
 //#region session-core-url.ts
 /** Build the session WebSocket URL from the platform URL and resume state. */
 function buildWsUrl(platformUrl, resume, sessionId) {
-	const wsUrl = new URL("websocket", platformUrl.endsWith("/") ? platformUrl : `${platformUrl}/`);
-	wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
+	return applyResumeParams(new URL("websocket", platformUrl.endsWith("/") ? platformUrl : `${platformUrl}/`), resume, sessionId);
+}
+/**
+* Turn a broker-provided session URL (`sessionUrl` from `GET client-config`
+* — the agent's live sandbox endpoint) into this attempt's connect URL.
+*/
+function buildBrokeredWsUrl(sessionUrl, resume, sessionId) {
+	return applyResumeParams(new URL(sessionUrl), resume, sessionId);
+}
+const WS_PROTOCOLS = {
+	"https:": "wss:",
+	"http:": "ws:"
+};
+function applyResumeParams(wsUrl, resume, sessionId) {
+	wsUrl.protocol = WS_PROTOCOLS[wsUrl.protocol] ?? wsUrl.protocol;
 	if (sessionId) wsUrl.searchParams.set("sessionId", sessionId);
 	else if (resume) wsUrl.searchParams.set("resume", "1");
 	return wsUrl;
@@ -491,7 +558,7 @@ function createSessionCore(options) {
 		ws: null,
 		voiceIO: null,
 		audioSetupInFlight: false,
-		generation: 0,
+		generation: createEpoch(),
 		preInitAudio: [],
 		preInitDone: false
 	};
@@ -506,6 +573,15 @@ function createSessionCore(options) {
 	* agent's context, greeting suppression aside.
 	*/
 	let sessionId = options.resumeSessionId;
+	/**
+	* Whether `platformUrl` is a broker (its `client-config` names a
+	* `sessionUrl`). A server is one or it isn't — it never flips mid-session
+	* — so once a non-broker is observed, later reconnects skip the
+	* `client-config` re-fetch that would only fall through to `buildWsUrl`
+	* (every reconnect on `aai dev` / self-hosted otherwise pays a wasted GET).
+	* `undefined` until the first fetch settles.
+	*/
+	let serverIsBroker;
 	function cleanupAudio() {
 		conn.audioSetupInFlight = false;
 		conn.voiceIO?.close().catch(() => {});
@@ -565,19 +641,34 @@ function createSessionCore(options) {
 	}
 	/**
 	* The WebSocket URL for the *next* connection attempt. Evaluated per
-	* attempt (partysocket takes it as a URL provider), so once the first
-	* `config` arrives, every reconnect — automatic or explicit — carries
-	* `?sessionId=<id>` and the server resumes the SAME session (id, tool
-	* state) instead of minting a new one. `resume=1` remains only as the
-	* greeting-suppression fallback for a server whose config carried no id.
+	* attempt (partysocket takes it as an async URL provider):
+	*
+	* - `GET client-config` is re-fetched every attempt. When it names a
+	*   `sessionUrl` — the platform's broker pointing at the agent's live
+	*   sandbox — the session connects DIRECTLY there. The URL changes when
+	*   the sandbox is replaced (idle eviction, redeploy), which is exactly
+	*   when a reconnect happens, so per-attempt brokering is what makes
+	*   reconnects land on the replacement. Without one (`aai dev`, older
+	*   servers), the same-origin `websocket` path is used.
+	* - Once the first `config` arrives, every reconnect carries
+	*   `?sessionId=<id>` and the server resumes the SAME session (id, tool
+	*   state) instead of minting a new one. `resume=1` remains only as the
+	*   greeting-suppression fallback for a server whose config carried no id.
 	*/
-	function currentWsUrl() {
-		return buildWsUrl(options.platformUrl, hasConnected, sessionId).toString();
+	async function currentWsUrl() {
+		const cfg = serverIsBroker === false ? null : await loadClientConfig(options.platformUrl);
+		if (cfg) serverIsBroker = cfg.sessionUrl !== void 0;
+		const url = cfg?.sessionUrl ? buildBrokeredWsUrl(cfg.sessionUrl, hasConnected, sessionId) : buildWsUrl(options.platformUrl, hasConnected, sessionId);
+		const display = new URL(url);
+		display.search = "";
+		if (display.toString() !== currentSnapshot.apiUrl) updateState({ apiUrl: display.toString() });
+		return url.toString();
 	}
-	/** Open a socket: an injected constructor as-is (tests), or partysocket's
-	*  reconnecting WebSocket — same interface, plus reconnect-on-close. */
+	/** Open a socket: an injected constructor as-is (tests — connects to the
+	*  same-origin path, no brokering), or partysocket's reconnecting
+	*  WebSocket — same interface, plus reconnect-on-close. */
 	function openSocket() {
-		if (options.WebSocket) return new options.WebSocket(currentWsUrl());
+		if (options.WebSocket) return new options.WebSocket(buildWsUrl(options.platformUrl, hasConnected, sessionId).toString());
 		return openReconnectingSocket(currentWsUrl);
 	}
 	function connect(opts) {
@@ -590,7 +681,7 @@ function createSessionCore(options) {
 			error: null
 		});
 		teardownConnection();
-		conn.generation++;
+		conn.generation.bump();
 		const controller = new AbortController();
 		connectionController = controller;
 		const { signal: sig } = controller;
@@ -613,7 +704,7 @@ function createSessionCore(options) {
 			if (sig.aborted) return;
 			cleanupAudio();
 			if (reconnectPending(socket)) {
-				conn.generation++;
+				conn.generation.bump();
 				socketErrored = false;
 				updateState({
 					state: "connecting",
@@ -700,4 +791,4 @@ function createSessionCore(options) {
 	};
 }
 //#endregion
-export { createSessionCore as t };
+export { buildAgentUrl as n, fetchClientConfig as r, createSessionCore as t };

package/dist/session-core-messages.d.ts

@@ -9,6 +9,7 @@ export declare const CLEARED_SESSION_STATE: {
     messages: never[];
     toolCalls: never[];
     customEvents: never[];
+    agentState: null;
     userTranscript: null;
     agentTranscript: null;
     error: null;
@@ -50,7 +51,7 @@ type MessageHandlers = {
 /**
  * Create the server→client message handlers for one session core.
  *
- * Encapsulates the two turn-boundary counters (`handlerGeneration` for
+ * Encapsulates the two turn-boundary counters (`turnEpoch` for
  * discarding stale async audio completions, `customEventSeq` for event
  * dedup) that previously lived as closure locals in `createSessionCore`.
  */

package/dist/session-core-reconnect.d.ts

@@ -6,10 +6,11 @@
 import ReconnectingWebSocket from "partysocket/ws";
 /**
  * Open partysocket's reconnecting WebSocket. The URL is a *provider*,
- * re-evaluated on every attempt, so each retry picks up the current resume
- * URL rather than the one the session started with.
+ * re-evaluated on every attempt (async supported), so each retry picks up
+ * the current broker-named endpoint and resume URL rather than the ones the
+ * session started with.
  */
-export declare function openReconnectingSocket(urlProvider: () => string): ReconnectingWebSocket;
+export declare function openReconnectingSocket(urlProvider: () => Promise<string>): ReconnectingWebSocket;
 /**
  * True while `socket` is a reconnecting socket that will retry after the
  * close event currently being handled. partysocket schedules the retry

package/dist/session-core-types.d.ts

@@ -3,6 +3,7 @@
  *
  * Split out of `session-core.ts` to keep that module focused on behaviour.
  */
+import type { Epoch } from "@alexkroman1/aai";
 import type { VoiceIO } from "./audio.ts";
 import type { AgentState, ChatMessage, SessionError, ToolCallInfo, VoiceSessionOptions, WebSocketConstructor } from "./types.ts";
 /**
@@ -43,6 +44,12 @@ export type SessionSnapshot = {
     readonly messages: ChatMessage[];
     readonly toolCalls: ToolCallInfo[];
     readonly customEvents: CustomEvent[];
+    /**
+     * Latest state the agent projected via `syncState`, or `null` before the
+     * first push. A value, not a log — a component that mounts mid-session
+     * reads current state rather than replaying events it missed.
+     */
+    readonly agentState: unknown;
     readonly userTranscript: string | null;
     readonly agentTranscript: string | null;
     readonly error: SessionError | null;
@@ -97,9 +104,10 @@ export type ConnState = {
     ws: InstanceType<WebSocketConstructor> | null;
     voiceIO: VoiceIO | null;
     audioSetupInFlight: boolean;
-    /** Monotonically increasing counter bumped on each connect(). Prevents a stale
-     *  initAudioCapture from assigning its voiceIO to a newer connection. */
-    generation: number;
+    /** Connection epoch, bumped on each connect()/retry (see `createEpoch`).
+     *  Prevents a stale initAudioCapture from assigning its voiceIO to a newer
+     *  connection. */
+    generation: Epoch;
     /** Audio chunks that arrived before `voiceIO` was initialized — drained into
      *  the playback worklet once init completes. Closes the race between the
      *  server starting greeting audio (immediately on S2S connect) and the

package/dist/session-core-url.d.ts

@@ -1,2 +1,7 @@
 /** Build the session WebSocket URL from the platform URL and resume state. */
 export declare function buildWsUrl(platformUrl: string, resume: boolean, sessionId?: string): URL;
+/**
+ * Turn a broker-provided session URL (`sessionUrl` from `GET client-config`
+ * — the agent's live sandbox endpoint) into this attempt's connect URL.
+ */
+export declare function buildBrokeredWsUrl(sessionUrl: string, resume: boolean, sessionId?: string): URL;