npm - @alexkroman1/aai-ui - Versions diffs - 4.0.0 → 5.0.0 - Mend

@alexkroman1/aai-ui 4.0.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/dist/default-client/assets/{audio-DQseUQnN.js → audio-Bu1LSuiR.js} +1 -1
package/dist/default-client/assets/{capture-processor-DKFNcEhw.js → capture-processor-ssRD81Mo.js} +1 -1
package/dist/default-client/assets/index-0-DXv-S4.js +192 -0
package/dist/default-client/assets/{playback-processor-HeyncQUX.js → playback-processor-CRwbxC1v.js} +1 -1
package/dist/default-client/index.html +1 -1
package/dist/define-client.d.ts +12 -1
package/dist/define-client.js +120 -4
package/dist/hooks.d.ts +40 -2
package/dist/hooks.js +24 -1
package/dist/index.d.ts +2 -2
package/dist/index.js +4 -4
package/dist/{session-core-CkZ8LyEA.js → session-core-Bjkr4PAP.js} +106 -35
package/dist/session-core-messages.d.ts +2 -1
package/dist/session-core-reconnect.d.ts +4 -3
package/dist/session-core-types.d.ts +11 -3
package/dist/session-core-url.d.ts +5 -0
package/dist/session-core.js +1 -1
package/dist/types.d.ts +17 -1
package/package.json +2 -2
package/dist/default-client/assets/index-CkZ6t_eJ.js +0 -417
package/dist/define-client-DqRs1XPd.js +0 -150

package/dist/default-client/assets/{playback-processor-HeyncQUX.js → playback-processor-CRwbxC1v.js} RENAMED Viewed

@@ -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-0-DXv-S4.js";import{t}from"./_module-url-BX0RuRU2.js";var n=t(`
 class PlaybackProcessor extends AudioWorkletProcessor {
   constructor(options) {
     super();

package/dist/default-client/index.html CHANGED Viewed

@@ -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-0-DXv-S4.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-CRfdZPH1.css">
   </head>
   <body>

package/dist/define-client.d.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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-Bjkr4PAP.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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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-Bjkr4PAP.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-Bjkr4PAP.js} RENAMED Viewed

@@ -1,7 +1,36 @@
 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. Every
+* failure path — network error, 404 from an older server, malformed body —
+* degrades to the empty default, so this lookup can never break an existing
+* agent.
+*/
+/** 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; any failure yields the agent default. */
+async function fetchClientConfig(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 AGENT_DEFAULT;
+		const parsed = ClientConfigResponseSchema.safeParse(await resp.json());
+		return parsed.success ? parsed.data : AGENT_DEFAULT;
+	} catch {
+		return AGENT_DEFAULT;
+	}
+}
+//#endregion
 //#region session-core-audio-setup.ts
 /**
 * Audio-path initialization for the voice session core.
@@ -29,8 +58,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 +97,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 +121,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 +153,7 @@ const CLEARED_SESSION_STATE = {
 	messages: [],
 	toolCalls: [],
 	customEvents: [],
+	agentState: null,
 	userTranscript: null,
 	agentTranscript: null,
 	error: null
@@ -137,14 +167,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 +191,7 @@ function createMessageHandlers(deps) {
 		}, MAX_CUSTOM_EVENTS) });
 	}
 	function handleUserTranscriptEvent(text) {
-		handlerGeneration++;
+		turnEpoch.bump();
 		updateState({
 			userTranscript: null,
 			messages: appendCapped(getSnapshot().messages, {
@@ -221,7 +251,7 @@ function createMessageHandlers(deps) {
 		} });
 		else {
 			cleanupAudio();
-			conn.generation++;
+			conn.generation.bump();
 			updateState({
 				state: "error",
 				error: {
@@ -280,7 +310,7 @@ function createMessageHandlers(deps) {
 				updateState({ state: "listening" });
 				break;
 			case "cancelled":
-				handlerGeneration++;
+				turnEpoch.bump();
 				conn.voiceIO?.flush();
 				commitAgentTranscript();
 				updateState({
@@ -289,7 +319,7 @@ function createMessageHandlers(deps) {
 				});
 				break;
 			case "reset":
-				handlerGeneration++;
+				turnEpoch.bump();
 				conn.voiceIO?.flush();
 				updateState({
 					...CLEARED_SESSION_STATE,
@@ -299,6 +329,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 +347,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 +361,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 +428,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 +448,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 +538,7 @@ function createSessionCore(options) {
 		ws: null,
 		voiceIO: null,
 		audioSetupInFlight: false,
-		generation: 0,
+		generation: createEpoch(),
 		preInitAudio: [],
 		preInitDone: false
 	};
@@ -506,6 +553,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 +621,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 ? {} : await fetchClientConfig(options.platformUrl);
+		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 +661,7 @@ function createSessionCore(options) {
 			error: null
 		});
 		teardownConnection();
-		conn.generation++;
+		conn.generation.bump();
 		const controller = new AbortController();
 		connectionController = controller;
 		const { signal: sig } = controller;
@@ -613,7 +684,7 @@ function createSessionCore(options) {
 			if (sig.aborted) return;
 			cleanupAudio();
 			if (reconnectPending(socket)) {
-				conn.generation++;
+				conn.generation.bump();
 				socketErrored = false;
 				updateState({
 					state: "connecting",
@@ -700,4 +771,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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;

package/dist/session-core.js CHANGED Viewed

@@ -1,2 +1,2 @@
-import { t as createSessionCore } from "./session-core-CkZ8LyEA.js";
+import { t as createSessionCore } from "./session-core-Bjkr4PAP.js";
 export { createSessionCore };