@tangle-network/sandbox-ui 0.113.6 → 0.114.0

package/dist/use-sidecar-auth-DkdcufOz.js

@@ -0,0 +1,742 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { createParser } from "eventsource-parser";
+//#region src/hooks/wire-encoding.ts
+/** btoa handles only latin-1; widen each UTF-8 byte into its own char first. */
+function utf8ToLatin1(text) {
+	return encodeURIComponent(text).replace(/%([0-9A-F]{2})/g, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+}
+function encodeTextForWire(text) {
+	if (typeof btoa === "function") return btoa(utf8ToLatin1(text));
+	const bufferCtor = globalThis.Buffer;
+	if (bufferCtor) return bufferCtor.from(text, "utf8").toString("base64");
+	throw new Error("encodeTextForWire: no base64 encoder available (btoa and Buffer both undefined)");
+}
+//#endregion
+//#region src/hooks/use-session-stream.ts
+var SessionStreamError = class extends Error {
+	code;
+	status;
+	constructor(code, message, status) {
+		super(message);
+		this.name = "SessionStreamError";
+		this.code = code;
+		this.status = status;
+	}
+};
+const SESSION_STREAM_RECONNECT_DELAY_MS = 1e3;
+function mapApiMessage(msg, counterRef) {
+	const created = msg.info.timestamp ? new Date(msg.info.timestamp).getTime() : Date.now();
+	return {
+		message: {
+			id: msg.info.id,
+			role: msg.info.role,
+			time: { created },
+			_insertionIndex: counterRef.current++
+		},
+		parts: (msg.parts ?? []).map((p, i) => {
+			if (p.type === "tool" && p.tool) return {
+				type: "tool",
+				id: p.id ?? `${msg.info.id}-tool-${i}`,
+				tool: p.tool,
+				state: {
+					status: p.state?.status ?? "completed",
+					input: p.state?.input,
+					output: p.state?.output,
+					error: p.state?.error,
+					metadata: p.state?.metadata,
+					time: p.time
+				}
+			};
+			if (p.type === "reasoning") return {
+				type: "reasoning",
+				text: p.text ?? "",
+				time: p.time
+			};
+			return {
+				type: "text",
+				text: p.text ?? ""
+			};
+		})
+	};
+}
+function readErrorDetails(value) {
+	if (typeof value === "string") return { message: value };
+	if (!value || typeof value !== "object") return {};
+	const record = value;
+	const nested = readErrorDetails(record.error);
+	return {
+		code: (typeof record.code === "string" ? record.code : void 0) ?? nested.code,
+		message: (typeof record.message === "string" ? record.message : void 0) ?? nested.message
+	};
+}
+function formatError(details, fallback) {
+	const message = details.message ?? fallback;
+	return details.code && !message.includes(details.code) ? `${message} (${details.code})` : message;
+}
+async function responseError(res, prefix) {
+	let details = {};
+	try {
+		details = readErrorDetails(await res.json());
+	} catch {}
+	const code = details.code ?? `HTTP_${res.status}`;
+	const fallback = `${prefix}: HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ""}`;
+	return new SessionStreamError(code, formatError(details, fallback), res.status);
+}
+async function fetchJson(url, token, init) {
+	const headers = { Authorization: `Bearer ${token}` };
+	if (init?.body) headers["Content-Type"] = "application/json";
+	const res = await fetch(url, {
+		...init,
+		headers: {
+			...headers,
+			...init?.headers
+		},
+		credentials: "include"
+	});
+	if (!res.ok) throw await responseError(res, "Request failed");
+	return res.json();
+}
+/**
+* Parse a Hub degradation payload.
+*
+* ONE rule for both halves of the same state: the `hubConnectionsDegraded`
+* field of a session status response, and the properties of a live
+* `hub.connections.degraded` frame. A live notice and the one that survives a
+* reload describe the same thing, so a payload either path rejects must be one
+* the other rejects too — otherwise a status read parses to `null` and erases
+* a notice the frame just raised.
+*
+* `message` is required. It is the only field a user reads, the producer's
+* schema makes it mandatory, and inventing prose for a payload that omits it
+* would assert a cause the sidecar never gave: `reason` is a free string, so a
+* generic "started with no integrations attached" can contradict it. A
+* partially-understood degradation is worse than none.
+*
+* Returns `null` for anything unreadable. What that MEANS is the caller's to
+* decide — an absent status field is health, an unreadable one is no evidence
+* either way.
+*/
+function readDegradation(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const record = raw;
+	if (typeof record.message !== "string") return null;
+	return {
+		kind: "hub-connections",
+		reason: typeof record.reason === "string" ? record.reason : "unknown",
+		message: record.message,
+		requestShape: typeof record.requestShape === "string" ? record.requestShape : "unknown"
+	};
+}
+/** Record that a live Hub frame has been applied for `sessionId`. */
+function bumpHubFrameEpoch(epochs, sessionId) {
+	epochs.set(sessionId, (epochs.get(sessionId) ?? 0) + 1);
+}
+/**
+* Set or clear one session's entry, returning the SAME map when nothing changes.
+*
+* Identity stability matters: this map is read during render, so a new
+* reference on every no-op frame would re-render every consumer of the hook for
+* a session whose state did not move.
+*/
+function withDegradation(prev, sessionId, value) {
+	const current = prev.get(sessionId) ?? null;
+	if (value === null) {
+		if (current === null) return prev;
+		const next = new Map(prev);
+		next.delete(sessionId);
+		return next;
+	}
+	if (current && current.reason === value.reason && current.message === value.message && current.requestShape === value.requestShape) return prev;
+	return new Map(prev).set(sessionId, value);
+}
+/**
+* Streams chat messages from a sidecar session gateway via SSE.
+*
+* Fetches existing message history on mount, then subscribes to SSE for
+* real-time updates. Maps the sidecar's message format to agent-ui's
+* SessionMessage + partMap format.
+*/
+function useSessionStream({ apiUrl, token, sessionId, enabled = true }) {
+	const [messages, setMessages] = useState([]);
+	const [partsState, setPartsState] = useState({
+		values: {},
+		sourceIds: {}
+	});
+	const partMap = partsState.values;
+	const [isStreaming, setIsStreaming] = useState(false);
+	const [error, setError] = useState(null);
+	const [connected, setConnected] = useState(false);
+	const [degradationBySession, setDegradationBySession] = useState(() => /* @__PURE__ */ new Map());
+	const degradation = degradationBySession.get(sessionId) ?? null;
+	const abortRef = useRef(null);
+	const reconnectTimerRef = useRef(null);
+	const activeAssistantMessageIdsRef = useRef(/* @__PURE__ */ new Set());
+	const completedExecutionIdsRef = useRef(/* @__PURE__ */ new Set());
+	const lastEventIdRef = useRef("");
+	const hubFrameEpochRef = useRef(/* @__PURE__ */ new Map());
+	const seedGenerationRef = useRef(/* @__PURE__ */ new Map());
+	const executionScopedStreamRef = useRef(false);
+	const insertionCounterRef = useRef(0);
+	const echoCounterRef = useRef(0);
+	const pendingEchoesRef = useRef(/* @__PURE__ */ new Map());
+	const handleSSEEventRef = useRef(null);
+	useEffect(() => {
+		pendingEchoesRef.current.clear();
+		activeAssistantMessageIdsRef.current.clear();
+		completedExecutionIdsRef.current.clear();
+		lastEventIdRef.current = "";
+	}, [sessionId]);
+	const refetch = useCallback(async () => {
+		if (!token || !sessionId || !apiUrl) return;
+		try {
+			const data = await fetchJson(`${apiUrl}/session/sessions/${encodeURIComponent(sessionId)}/messages?limit=200`, token);
+			const apiMessages = Array.isArray(data) ? data : data.messages ?? [];
+			const newMessages = [];
+			const newPartMap = {};
+			for (const apiMsg of apiMessages) {
+				const { message, parts } = mapApiMessage(apiMsg, insertionCounterRef);
+				newMessages.push(message);
+				newPartMap[message.id] = parts;
+			}
+			const canonicalIds = new Set(newMessages.map((message) => message.id));
+			const echoes = [...pendingEchoesRef.current.entries()].filter(([, echo]) => !echo.canonicalMessageId || !canonicalIds.has(echo.canonicalMessageId)).map(([, echo]) => echo);
+			for (const [echoId, echo] of pendingEchoesRef.current) if (echo.canonicalMessageId && canonicalIds.has(echo.canonicalMessageId)) pendingEchoesRef.current.delete(echoId);
+			setMessages([...newMessages, ...echoes.map((echo) => echo.message)]);
+			setPartsState({
+				values: {
+					...newPartMap,
+					...Object.fromEntries(echoes.map((echo) => [echo.message.id, echo.parts]))
+				},
+				sourceIds: {}
+			});
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : "Failed to fetch messages";
+			setError(msg);
+		}
+	}, [
+		apiUrl,
+		token,
+		sessionId
+	]);
+	/**
+	* Read the session's degradation back from session status.
+	*
+	* The sidecar's event bus is live-only and never replays, so the
+	* `hub.connections.degraded` frame is gone for a client that reloads or
+	* attaches after spawn — while the toolbelt stays empty. Status is the
+	* durable half of the same state, and it is also what retires the notice
+	* after a credential refresh.
+	*
+	* Failures are swallowed: this is supplementary information, and surfacing a
+	* status fetch error as a session error would be worse than not showing the
+	* notice. `refetch` already reports a broken session gateway.
+	*/
+	const seedDegradation = useCallback(async () => {
+		if (!token || !sessionId || !apiUrl) return;
+		const epochAtRequest = hubFrameEpochRef.current.get(sessionId) ?? 0;
+		const generation = (seedGenerationRef.current.get(sessionId) ?? 0) + 1;
+		seedGenerationRef.current.set(sessionId, generation);
+		let seeded;
+		try {
+			const field = (await fetchJson(`${apiUrl}/session/sessions/${encodeURIComponent(sessionId)}`, token)).hubConnectionsDegraded;
+			if (field === void 0 || field === null) seeded = null;
+			else {
+				seeded = readDegradation(field);
+				if (!seeded) return;
+			}
+		} catch {
+			return;
+		}
+		if ((hubFrameEpochRef.current.get(sessionId) ?? 0) !== epochAtRequest) return;
+		if (seedGenerationRef.current.get(sessionId) !== generation) return;
+		setDegradationBySession((prev) => withDegradation(prev, sessionId, seeded));
+	}, [
+		apiUrl,
+		token,
+		sessionId
+	]);
+	const connectSSE = useCallback(async () => {
+		if (!token || !sessionId || !apiUrl || !enabled) return;
+		if (reconnectTimerRef.current) {
+			clearTimeout(reconnectTimerRef.current);
+			reconnectTimerRef.current = null;
+		}
+		abortRef.current?.abort();
+		const controller = new AbortController();
+		abortRef.current = controller;
+		try {
+			const eventQuery = new URLSearchParams({ sessionId });
+			const activeExecutionIds = [...activeAssistantMessageIdsRef.current];
+			executionScopedStreamRef.current = activeExecutionIds.length > 0;
+			if (activeExecutionIds.length === 1) eventQuery.set("executionId", activeExecutionIds[0]);
+			else if (activeExecutionIds.length > 1) eventQuery.set("replayExecutionIds", activeExecutionIds.join(","));
+			if (lastEventIdRef.current) eventQuery.set("since", lastEventIdRef.current);
+			const url = `${apiUrl}/session/events?${eventQuery.toString()}`;
+			const res = await fetch(url, {
+				headers: { Authorization: `Bearer ${token}` },
+				signal: controller.signal,
+				credentials: "include"
+			});
+			if (!res.ok) throw await responseError(res, "Live response connection failed");
+			setConnected(true);
+			setError(null);
+			seedDegradation();
+			const reader = res.body?.getReader();
+			if (!reader) throw new Error("No response body");
+			const decoder = new TextDecoder();
+			let parserFailure = null;
+			const parser = createParser({
+				onEvent(event) {
+					if (event.id) lastEventIdRef.current = event.id;
+					if (!event.data) return;
+					try {
+						const parsed = JSON.parse(event.data);
+						handleSSEEventRef.current?.(event.event ?? "message", parsed);
+					} catch {
+						parserFailure = new SessionStreamError("INVALID_SESSION_EVENT", "The live response stream sent malformed data.");
+					}
+				},
+				onError(parseError) {
+					parserFailure = new SessionStreamError("INVALID_EVENT_STREAM", `The live response stream could not be parsed: ${parseError.message}`);
+				}
+			});
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				parser.feed(decoder.decode(value, { stream: true }));
+				if (parserFailure) throw parserFailure;
+			}
+			const tail = decoder.decode();
+			if (tail) parser.feed(tail);
+			parser.reset({ consume: true });
+			if (parserFailure) throw parserFailure;
+			throw new SessionStreamError("SESSION_STREAM_CLOSED", "The live response stream closed before the session ended. Reconnecting…");
+		} catch (err) {
+			if (err.name === "AbortError") return;
+			const msg = err instanceof Error ? err.message : "SSE connection error";
+			setError(msg);
+			setConnected(false);
+			if (!controller.signal.aborted) reconnectTimerRef.current = setTimeout(() => connectSSE(), SESSION_STREAM_RECONNECT_DELAY_MS);
+		}
+	}, [
+		apiUrl,
+		token,
+		sessionId,
+		enabled
+	]);
+	handleSSEEventRef.current = useCallback((type, raw) => {
+		const envelope = raw?.properties;
+		const props = envelope?.info ?? envelope?.part ?? envelope ?? raw;
+		const associatePendingEcho = (executionId) => {
+			for (const echo of pendingEchoesRef.current.values()) if (!echo.executionId) {
+				echo.executionId = executionId;
+				return;
+			}
+		};
+		const retireExecution = (executionId) => {
+			if (!executionId) {
+				const activeExecutionIds = [...activeAssistantMessageIdsRef.current];
+				if (activeExecutionIds.length === 1) return retireExecution(activeExecutionIds[0]);
+				if (activeExecutionIds.length > 1) return true;
+				pendingEchoesRef.current.clear();
+				return false;
+			}
+			completedExecutionIdsRef.current.add(executionId);
+			activeAssistantMessageIdsRef.current.delete(executionId);
+			for (const [echoId, echo] of pendingEchoesRef.current) if (echo.executionId === executionId || !echo.executionId && pendingEchoesRef.current.size === 1) pendingEchoesRef.current.delete(echoId);
+			return activeAssistantMessageIdsRef.current.size > 0;
+		};
+		if (type === "message.updated") {
+			const id = props.id ?? props.messageId ?? "";
+			const role = props.role ?? "assistant";
+			if (!id) return;
+			setMessages((prev) => {
+				if (prev.some((m) => m.id === id)) return prev;
+				return [...prev, {
+					id,
+					role,
+					time: { created: Date.now() },
+					_insertionIndex: insertionCounterRef.current++
+				}];
+			});
+			if (role === "assistant") {
+				associatePendingEcho(id);
+				if (!completedExecutionIdsRef.current.has(id)) {
+					activeAssistantMessageIdsRef.current.add(id);
+					setIsStreaming(true);
+				}
+			}
+		} else if (type === "message.part.updated") {
+			const msgId = props.messageID ?? props.messageId ?? "";
+			if (!msgId) return;
+			const partType = props.type ?? "text";
+			const sourcePartId = props.id ?? `${partType}-${msgId}`;
+			associatePendingEcho(msgId);
+			if (!completedExecutionIdsRef.current.has(msgId)) {
+				activeAssistantMessageIdsRef.current.add(msgId);
+				setIsStreaming(true);
+			}
+			setMessages((prev) => {
+				if (prev.some((message) => message.id === msgId)) return prev;
+				return [...prev, {
+					id: msgId,
+					role: "assistant",
+					time: { created: Date.now() },
+					_insertionIndex: insertionCounterRef.current++
+				}];
+			});
+			setPartsState((prev) => {
+				const existing = prev.values[msgId] ?? [];
+				const sourceIds = prev.sourceIds[msgId] ?? [];
+				const updated = [...existing];
+				const updatedSourceIds = [...sourceIds];
+				const knownIndex = sourceIds.indexOf(sourcePartId);
+				if (partType === "text") {
+					const textPart = {
+						type: "text",
+						text: props.text ?? props.content ?? ""
+					};
+					if (knownIndex >= 0) updated[knownIndex] = textPart;
+					else {
+						updatedSourceIds.push(sourcePartId);
+						updated.push(textPart);
+					}
+				} else if (partType === "tool") {
+					const toolId = props.id ?? props.toolId ?? sourcePartId;
+					const toolName = props.tool ?? props.name ?? "unknown";
+					const state = props.state ?? { status: "running" };
+					const toolPart = {
+						type: "tool",
+						id: toolId,
+						tool: toolName,
+						state: {
+							status: state.status ?? "running",
+							input: state.input,
+							output: state.output,
+							error: state.error,
+							metadata: state.metadata,
+							time: state.time
+						}
+					};
+					if (knownIndex >= 0) updated[knownIndex] = toolPart;
+					else {
+						updatedSourceIds.push(sourcePartId);
+						updated.push(toolPart);
+					}
+				} else if (partType === "reasoning") {
+					const reasoningPart = {
+						type: "reasoning",
+						text: props.text ?? ""
+					};
+					if (knownIndex >= 0) updated[knownIndex] = reasoningPart;
+					else {
+						updatedSourceIds.push(sourcePartId);
+						updated.push(reasoningPart);
+					}
+				} else return prev;
+				return {
+					values: {
+						...prev.values,
+						[msgId]: updated
+					},
+					sourceIds: {
+						...prev.sourceIds,
+						[msgId]: updatedSourceIds
+					}
+				};
+			});
+		} else if (type === "session.idle") {
+			const stillStreaming = retireExecution(props.executionId ?? props.executionID ?? "");
+			setIsStreaming(stillStreaming);
+			if (!stillStreaming) {
+				refetch();
+				if (executionScopedStreamRef.current) seedDegradation();
+			}
+		} else if (type === "hub.connections.degraded") {
+			const framedSessionId = typeof props.sessionId === "string" ? props.sessionId : null;
+			if (!framedSessionId) return;
+			const value = readDegradation(props);
+			if (!value) return;
+			bumpHubFrameEpoch(hubFrameEpochRef.current, framedSessionId);
+			setDegradationBySession((prev) => withDegradation(prev, framedSessionId, value));
+		} else if (type === "hub.connections.restored") {
+			const framedSessionId = typeof props.sessionId === "string" ? props.sessionId : null;
+			if (!framedSessionId) return;
+			bumpHubFrameEpoch(hubFrameEpochRef.current, framedSessionId);
+			setDegradationBySession((prev) => withDegradation(prev, framedSessionId, null));
+		} else if (type === "session.error") {
+			const stillStreaming = retireExecution(props.executionId ?? props.executionID ?? "");
+			setIsStreaming(stillStreaming);
+			setError(formatError(readErrorDetails(props), "Agent response failed"));
+			if (!stillStreaming) refetch();
+		}
+	}, [refetch, seedDegradation]);
+	/**
+	* Sends the text and echoes it into the transcript immediately.
+	*
+	* The echo is what makes the sender's own message visible during the turn:
+	* the session bus carries `message.updated` only for the assistant's reply,
+	* so the user's message otherwise first surfaces in the `session.idle`
+	* refetch — after the agent has finished answering it. The echo carries a
+	* client-minted id and never has to agree with the backend's, because it is
+	* retired wholesale when the turn ends rather than matched against a
+	* canonical message.
+	*/
+	const send = useCallback(async (text, options) => {
+		if (!token || !sessionId || !apiUrl || !enabled) {
+			const admissionError = new SessionStreamError("CHAT_NOT_READY", "Chat is not ready yet. Wait for the session connection and try again.");
+			setError(admissionError.message);
+			throw admissionError;
+		}
+		if (!connected) {
+			const admissionError = new SessionStreamError("CHAT_DISCONNECTED", "Chat is reconnecting. Your message was not sent.");
+			setError(admissionError.message);
+			throw admissionError;
+		}
+		if (pendingEchoesRef.current.size > 0 || activeAssistantMessageIdsRef.current.size > 0) {
+			const admissionError = new SessionStreamError("CHAT_BUSY", "The agent is still responding. Wait for this turn to finish before sending another message.");
+			setError(admissionError.message);
+			throw admissionError;
+		}
+		setError(null);
+		const echoId = `local-echo-${echoCounterRef.current++}`;
+		const echo = {
+			message: {
+				id: echoId,
+				role: "user",
+				time: { created: Date.now() },
+				_insertionIndex: insertionCounterRef.current++
+			},
+			parts: [{
+				type: "text",
+				text
+			}]
+		};
+		pendingEchoesRef.current.set(echoId, echo);
+		setMessages((prev) => [...prev, echo.message]);
+		setPartsState((prev) => ({
+			values: {
+				...prev.values,
+				[echoId]: echo.parts
+			},
+			sourceIds: prev.sourceIds
+		}));
+		setIsStreaming(true);
+		try {
+			const response = await fetchJson(`${apiUrl}/session/sessions/${encodeURIComponent(sessionId)}/messages`, token, {
+				method: "POST",
+				body: JSON.stringify({
+					parts: [{
+						type: "text",
+						text: encodeTextForWire(text)
+					}],
+					...options?.agent ? { agent: options.agent } : {},
+					...options?.model ? { model: options.model } : {},
+					...options?.system ? { system: options.system } : {},
+					...options?.reasoningEffort ? { reasoningEffort: options.reasoningEffort } : {}
+				})
+			});
+			if (response.userMessageId) {
+				const pending = pendingEchoesRef.current.get(echoId);
+				if (pending) pending.canonicalMessageId = response.userMessageId;
+			}
+			const executionId = response.info?.id;
+			if (executionId) {
+				const pending = pendingEchoesRef.current.get(echoId);
+				if (pending) pending.executionId = executionId;
+				if (!completedExecutionIdsRef.current.has(executionId)) activeAssistantMessageIdsRef.current.add(executionId);
+			}
+		} catch (err) {
+			pendingEchoesRef.current.delete(echoId);
+			setMessages((prev) => prev.filter((message) => message.id !== echoId));
+			setPartsState((prev) => {
+				if (!(echoId in prev.values)) return prev;
+				const values = { ...prev.values };
+				const sourceIds = { ...prev.sourceIds };
+				delete values[echoId];
+				delete sourceIds[echoId];
+				return {
+					values,
+					sourceIds
+				};
+			});
+			if (pendingEchoesRef.current.size === 0 && activeAssistantMessageIdsRef.current.size === 0) setIsStreaming(false);
+			const msg = err instanceof Error ? err.message : "Failed to send message";
+			setError(msg);
+			throw err;
+		}
+	}, [
+		apiUrl,
+		connected,
+		enabled,
+		token,
+		sessionId
+	]);
+	const abort = useCallback(async () => {
+		if (!token || !sessionId || !apiUrl) return;
+		try {
+			await fetchJson(`${apiUrl}/session/sessions/${encodeURIComponent(sessionId)}/abort`, token, { method: "POST" });
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : "Failed to abort";
+			setError(msg);
+		}
+	}, [
+		apiUrl,
+		token,
+		sessionId
+	]);
+	useEffect(() => {
+		if (!enabled || !token || !sessionId) return;
+		refetch();
+		connectSSE();
+		return () => {
+			abortRef.current?.abort();
+			if (reconnectTimerRef.current) clearTimeout(reconnectTimerRef.current);
+			setConnected(false);
+		};
+	}, [
+		enabled,
+		token,
+		sessionId,
+		refetch,
+		connectSSE
+	]);
+	return {
+		messages,
+		partMap,
+		isStreaming,
+		send,
+		abort,
+		refetch,
+		error,
+		connected,
+		degradation
+	};
+}
+//#endregion
+//#region src/hooks/use-sidecar-auth.ts
+function storageKey(resourceId, apiUrl) {
+	return `sidecar_session_${resourceId}__${apiUrl}`;
+}
+function loadSession(resourceId, apiUrl) {
+	if (typeof window === "undefined") return null;
+	try {
+		const raw = localStorage.getItem(storageKey(resourceId, apiUrl));
+		if (!raw) return null;
+		const data = JSON.parse(raw);
+		if (data.expiresAt * 1e3 - Date.now() < 6e4) {
+			localStorage.removeItem(storageKey(resourceId, apiUrl));
+			return null;
+		}
+		return data;
+	} catch {
+		return null;
+	}
+}
+function saveSession(resourceId, apiUrl, token, expiresAt) {
+	if (typeof window === "undefined") return;
+	try {
+		localStorage.setItem(storageKey(resourceId, apiUrl), JSON.stringify({
+			token,
+			expiresAt
+		}));
+	} catch {}
+}
+function clearSession(resourceId, apiUrl) {
+	if (typeof window === "undefined") return;
+	localStorage.removeItem(storageKey(resourceId, apiUrl));
+}
+/**
+* Generic sidecar PASETO challenge/response auth.
+*
+* Flow:
+* 1. POST /api/auth/challenge  → { nonce, message, expires_at }
+* 2. signMessage(message)       → signature (provided by consuming app)
+* 3. POST /api/auth/session     → { token, address, expires_at }
+*
+* Tokens are cached in localStorage and auto-refreshed 5 minutes before expiry.
+*/
+function useSidecarAuth({ resourceId, apiUrl, signMessage }) {
+	const cached = loadSession(resourceId, apiUrl);
+	const [token, setToken] = useState(cached?.token ?? null);
+	const [expiresAt, setExpiresAt] = useState(cached?.expiresAt ?? 0);
+	const [isAuthenticating, setIsAuthenticating] = useState(false);
+	const [error, setError] = useState(null);
+	const refreshTimerRef = useRef(void 0);
+	const clearCachedToken = useCallback(() => {
+		setToken(null);
+		setExpiresAt(0);
+		clearSession(resourceId, apiUrl);
+	}, [resourceId, apiUrl]);
+	const authenticate = useCallback(async () => {
+		if (!apiUrl) return null;
+		setIsAuthenticating(true);
+		setError(null);
+		try {
+			const challengeRes = await fetch(`${apiUrl}/api/auth/challenge`, { method: "POST" });
+			if (!challengeRes.ok) throw new Error(`Challenge failed: ${challengeRes.status}`);
+			const { nonce, message } = await challengeRes.json();
+			const signature = await signMessage(message);
+			const sessionRes = await fetch(`${apiUrl}/api/auth/session`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					nonce,
+					signature
+				})
+			});
+			if (!sessionRes.ok) {
+				const text = await sessionRes.text();
+				throw new Error(text || `Session exchange failed: ${sessionRes.status}`);
+			}
+			const { token: newToken, expires_at } = await sessionRes.json();
+			setToken(newToken);
+			setExpiresAt(expires_at);
+			saveSession(resourceId, apiUrl, newToken, expires_at);
+			return newToken;
+		} catch (err) {
+			setError(err instanceof Error ? err.message : "Authentication failed");
+			clearCachedToken();
+			return null;
+		} finally {
+			setIsAuthenticating(false);
+		}
+	}, [
+		resourceId,
+		apiUrl,
+		signMessage,
+		clearCachedToken
+	]);
+	useEffect(() => {
+		if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
+		if (!token || !expiresAt) return;
+		const msUntilRefresh = (expiresAt - 300) * 1e3 - Date.now();
+		if (msUntilRefresh <= 0) {
+			clearCachedToken();
+			return;
+		}
+		refreshTimerRef.current = setTimeout(() => {
+			authenticate().catch(() => {
+				clearCachedToken();
+			});
+		}, msUntilRefresh);
+		return () => {
+			if (refreshTimerRef.current) clearTimeout(refreshTimerRef.current);
+		};
+	}, [
+		token,
+		expiresAt,
+		authenticate,
+		clearCachedToken
+	]);
+	return {
+		token,
+		isAuthenticated: token !== null,
+		isAuthenticating,
+		authenticate,
+		clearCachedToken,
+		error
+	};
+}
+//#endregion
+export { useSessionStream as i, SESSION_STREAM_RECONNECT_DELAY_MS as n, SessionStreamError as r, useSidecarAuth as t };