nudge-ui 0.2.0

package/dist/inspector/agent/client.js

@@ -0,0 +1,728 @@
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import { isNudgeUiDev } from "../runtime/devFlag.js";
+import { isDemoRuntime } from "../runtime/runtimeConfig.js";
+import { HttpAgentBridgeTransport } from "./httpTransport.js";
+import { AGENT_PROTOCOL_VERSION, } from "./protocol.js";
+const DISABLED_SNAPSHOT = Object.freeze({
+    state: "disabled",
+    connection: "offline",
+    listenerActive: false,
+    companionReachable: false,
+    paired: false,
+    request: null,
+});
+const DEFAULT_DISCOVERY_INTERVAL_MS = 2_000;
+const SESSION_STORAGE_PREFIX = "nudge-ui-agent-session:";
+function randomId(prefix) {
+    const random = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+        ? crypto.randomUUID()
+        : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    return `${prefix}-${random}`;
+}
+function errorMessage(error, fallback) {
+    return error instanceof Error && error.message ? error.message : fallback;
+}
+function sessionStorageKey(projectId) {
+    return `${SESSION_STORAGE_PREFIX}${encodeURIComponent(projectId)}`;
+}
+function readStoredSession(projectId, origin) {
+    if (typeof localStorage === "undefined")
+        return null;
+    try {
+        const raw = localStorage.getItem(sessionStorageKey(projectId));
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        // SAFETY: The typeof/Array.isArray guard above proves parsed is a non-array object with string keys.
+        const value = parsed;
+        if (value.projectId !== projectId || value.origin !== origin || typeof value.sessionToken !== "string" || value.sessionToken.length === 0) {
+            localStorage.removeItem(sessionStorageKey(projectId));
+            return null;
+        }
+        return value.sessionToken;
+    }
+    catch {
+        return null;
+    }
+}
+function writeStoredSession(session) {
+    if (typeof localStorage === "undefined")
+        return;
+    try {
+        localStorage.setItem(sessionStorageKey(session.projectId), JSON.stringify(session));
+    }
+    catch {
+        // Storage can be disabled by browser privacy settings. The in-memory
+        // pairing remains valid for this document in that case.
+    }
+}
+function clearStoredSession(projectId) {
+    if (typeof localStorage === "undefined")
+        return;
+    try {
+        localStorage.removeItem(sessionStorageKey(projectId));
+    }
+    catch {
+        // Ignore storage failures; disconnect still clears the live connection.
+    }
+}
+function statusForConnection(status) {
+    if (status.connection === "working" || status.request?.status === "working")
+        return "working";
+    if (status.paired)
+        return "paired";
+    if (status.listenerActive)
+        return "listening";
+    return "offline";
+}
+function hashRevision(value) {
+    // FNV-1a is sufficient here: the revision is an opaque, bounded identity
+    // used to prevent a later browser edit from being mistaken for the sent
+    // canonical change set. Keep it in the safe-integer range accepted by the
+    // companion protocol.
+    let hash = 2_166_136_261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16_777_619);
+    }
+    return (hash >>> 0) & 0x7fff_ffff;
+}
+/** Creates a stable numeric revision for one prompt snapshot. */
+export function createPromptRevision(changes, structuralChanges = []) {
+    let serialized;
+    try {
+        serialized = JSON.stringify({ changes, structuralChanges }) ?? "";
+    }
+    catch {
+        serialized = `${changes.length}:${structuralChanges.length}`;
+    }
+    return hashRevision(serialized);
+}
+/**
+ * Browser-side companion client.
+ *
+ * Discovery is deliberately started by `start()`, which is guarded by the
+ * dev-only flag. Constructing this class never opens a socket or performs a
+ * network request, so importing the inspector remains inert in production.
+ */
+export class AgentClient {
+    projectId;
+    origin;
+    transport;
+    discoveryIntervalMs;
+    enabled;
+    canvasCommandHandler;
+    listeners = new Set();
+    snapshot;
+    sessionToken = null;
+    activeRequest = null;
+    discoveryTimer = null;
+    discoveryAbort = null;
+    pairingAbort = null;
+    dispatchAbort = null;
+    eventSubscription = null;
+    started = false;
+    connection = "offline";
+    listenerActive = false;
+    companionReachable = false;
+    paired = false;
+    lastError;
+    constructor(options) {
+        this.projectId = options.projectId;
+        this.origin = options.origin ?? (typeof window !== "undefined" ? window.location.origin : "http://localhost");
+        this.transport = options.transport ?? new HttpAgentBridgeTransport(options.endpoint);
+        this.discoveryIntervalMs = options.discoveryIntervalMs ?? DEFAULT_DISCOVERY_INTERVAL_MS;
+        this.canvasCommandHandler = options.canvasCommandHandler;
+        // The public demo renders the real inspector but intentionally keeps the
+        // local MCP/agent bridge inert.
+        this.enabled = isNudgeUiDev() && !isDemoRuntime();
+        this.snapshot = this.enabled ? this.makeSnapshot() : DISABLED_SNAPSHOT;
+    }
+    /** Installs the controller callback used to acknowledge Canvas commands. */
+    setCanvasCommandHandler(handler) {
+        this.canvasCommandHandler = handler;
+    }
+    getSnapshot = () => this.snapshot;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    /** Starts loopback discovery. Calling it repeatedly is idempotent. */
+    start() {
+        if (!this.enabled || this.started)
+            return;
+        this.started = true;
+        void this.restoreOrDiscover();
+    }
+    /** Stops discovery and closes the browser event stream. */
+    stop() {
+        if (!this.started && !this.eventSubscription)
+            return;
+        this.started = false;
+        if (this.discoveryTimer !== null) {
+            clearTimeout(this.discoveryTimer);
+            this.discoveryTimer = null;
+        }
+        this.discoveryAbort?.abort();
+        this.discoveryAbort = null;
+        this.pairingAbort?.abort();
+        this.pairingAbort = null;
+        this.dispatchAbort?.abort();
+        this.dispatchAbort = null;
+        this.eventSubscription?.close();
+        this.eventSubscription = null;
+        // `stop` is used by React effect cleanup and page remounts. Keep the
+        // request and ephemeral token in memory/storage so a still-running
+        // companion can be resumed; explicit `disconnect()` is the revocation
+        // and interruption path.
+        this.connection = "offline";
+        this.listenerActive = false;
+        this.companionReachable = false;
+        this.paired = false;
+        this.publish();
+    }
+    async restoreOrDiscover() {
+        if (!this.started || !this.enabled || this.pairingAbort)
+            return;
+        const token = this.sessionToken ?? readStoredSession(this.projectId, this.origin);
+        if (token && this.transport.restore) {
+            const abortController = new AbortController();
+            this.discoveryAbort?.abort();
+            this.discoveryAbort = abortController;
+            try {
+                const status = await this.transport.restore({
+                    projectId: this.projectId,
+                    origin: this.origin,
+                    sessionToken: token,
+                }, abortController.signal);
+                if (!this.started || abortController.signal.aborted)
+                    return;
+                if (status?.paired) {
+                    this.sessionToken = token;
+                    this.connection = "paired";
+                    this.paired = true;
+                    this.openEvents(token);
+                    this.applyStatus(status);
+                    return;
+                }
+                clearStoredSession(this.projectId);
+                this.sessionToken = null;
+                this.resetForDiscovery();
+            }
+            catch (error) {
+                if (abortController.signal.aborted || !this.started)
+                    return;
+                // A stale or revoked token is not a connection error. Clearing it
+                // lets the normal listener discovery path offer a fresh pairing.
+                clearStoredSession(this.projectId);
+                this.sessionToken = null;
+                this.resetForDiscovery();
+                void error;
+            }
+            finally {
+                if (this.discoveryAbort === abortController)
+                    this.discoveryAbort = null;
+            }
+        }
+        await this.discover();
+    }
+    /** Runs an immediate authenticated restore or companion discovery probe. */
+    async checkConnection() {
+        if (!this.enabled)
+            return;
+        if (!this.started)
+            this.start();
+        if (!this.started || this.pairingAbort)
+            return;
+        if (this.discoveryTimer !== null) {
+            clearTimeout(this.discoveryTimer);
+            this.discoveryTimer = null;
+        }
+        this.lastError = undefined;
+        this.publish();
+        await this.restoreOrDiscover();
+    }
+    /** Triggers a new discovery probe after a connection loss. */
+    reconnect() {
+        if (!this.enabled)
+            return;
+        if (!this.started) {
+            this.start();
+            return;
+        }
+        this.eventSubscription?.close();
+        this.eventSubscription = null;
+        this.discoveryAbort?.abort();
+        this.pairingAbort?.abort();
+        this.pairingAbort = null;
+        this.connection = "offline";
+        this.listenerActive = false;
+        this.companionReachable = false;
+        this.paired = false;
+        this.lastError = undefined;
+        this.publish();
+        void this.restoreOrDiscover();
+    }
+    /** Pairs the browser with a reachable companion, including an idle agent. */
+    async connect() {
+        if (!this.enabled || !this.started || this.pairingAbort || this.paired || !this.companionReachable)
+            return false;
+        if (this.connection === "working" || this.activeRequest?.status === "working")
+            return false;
+        const idleListenerActive = this.listenerActive;
+        const idleCompanionReachable = this.companionReachable;
+        this.connection = idleListenerActive ? "listening" : "offline";
+        this.lastError = undefined;
+        this.publish("pairing");
+        const request = {
+            projectId: this.projectId,
+            origin: this.origin,
+            ...(typeof window !== "undefined" ? { pageUrl: window.location.href } : {}),
+        };
+        const abortController = new AbortController();
+        this.discoveryAbort?.abort();
+        this.pairingAbort = abortController;
+        try {
+            const pairing = await this.transport.pair(request, abortController.signal);
+            if (!this.started || abortController.signal.aborted)
+                return false;
+            if (pairing.protocolVersion !== undefined && pairing.protocolVersion !== AGENT_PROTOCOL_VERSION) {
+                throw new Error("Agent bridge protocol version is not supported.");
+            }
+            if (pairing.projectId !== this.projectId)
+                throw new Error("Agent bridge returned a different project.");
+            if (pairing.status.projectId !== this.projectId || pairing.status.protocolVersion !== AGENT_PROTOCOL_VERSION || !pairing.status.paired) {
+                throw new Error("Agent bridge returned an invalid pairing status.");
+            }
+            this.sessionToken = pairing.sessionToken;
+            writeStoredSession({ projectId: this.projectId, origin: this.origin, sessionToken: pairing.sessionToken });
+            this.connection = "paired";
+            this.listenerActive = pairing.status.listenerActive;
+            this.paired = true;
+            if (this.discoveryTimer !== null) {
+                clearTimeout(this.discoveryTimer);
+                this.discoveryTimer = null;
+            }
+            this.applyStatus(pairing.status);
+            this.openEvents(pairing.sessionToken);
+            this.publish();
+            return true;
+        }
+        catch (error) {
+            if (abortController.signal.aborted || !this.started)
+                return false;
+            this.lastError = errorMessage(error, "The agent could not be connected.");
+            this.sessionToken = null;
+            this.companionReachable = idleCompanionReachable;
+            this.listenerActive = idleListenerActive;
+            this.connection = idleListenerActive ? "listening" : "offline";
+            this.paired = false;
+            this.publish(idleListenerActive ? "available" : "disconnected");
+            return false;
+        }
+        finally {
+            if (this.pairingAbort === abortController) {
+                this.pairingAbort = null;
+                this.scheduleDiscovery();
+            }
+        }
+    }
+    openEvents(sessionToken) {
+        this.eventSubscription?.close();
+        const eventsRequest = {
+            projectId: this.projectId,
+            origin: this.origin,
+            sessionToken,
+        };
+        try {
+            this.eventSubscription = this.transport.openEvents(eventsRequest, {
+                onEvent: (event) => this.handleEvent(event),
+                onDisconnect: (reason) => this.handleDisconnect(reason),
+            });
+        }
+        catch (error) {
+            this.handleDisconnect(errorMessage(error, "The agent event stream could not be opened."));
+        }
+    }
+    /**
+     * Dispatches one immutable prompt revision. The request enters `working`
+     * synchronously, before the transport promise resolves, so the UI cannot
+     * issue a second prompt while the first one is in flight.
+     */
+    async dispatchPrompt(prompt, changeRevision) {
+        if (!this.enabled || !this.started || !this.paired || !this.listenerActive || !this.sessionToken)
+            return null;
+        if (!prompt || this.activeRequest?.status === "working")
+            return null;
+        const localRequestId = randomId("request");
+        const request = {
+            projectId: this.projectId,
+            sessionToken: this.sessionToken,
+            prompt,
+            ...(changeRevision === undefined ? {} : { changeRevision }),
+        };
+        this.activeRequest = {
+            localRequestId,
+            requestId: localRequestId,
+            prompt,
+            ...(changeRevision === undefined ? {} : { changeRevision }),
+            status: "working",
+        };
+        this.connection = "working";
+        this.lastError = undefined;
+        this.publish();
+        const abortController = new AbortController();
+        this.dispatchAbort = abortController;
+        try {
+            const response = await this.transport.dispatch(request, abortController.signal);
+            if (abortController.signal.aborted)
+                return null;
+            if (response?.request?.requestId) {
+                this.activeRequest = this.activeRequest && this.activeRequest.localRequestId === localRequestId
+                    ? { ...this.activeRequest, requestId: response.request.requestId }
+                    : this.activeRequest;
+            }
+            if (response?.status && response.status !== "working") {
+                this.applyRequestStatus(response.status, response.request.requestId);
+            }
+            return response ?? null;
+        }
+        catch (error) {
+            if (!abortController.signal.aborted && this.activeRequest?.localRequestId === localRequestId) {
+                this.activeRequest = { ...this.activeRequest, status: "failed", error: errorMessage(error, "The agent did not accept the prompt.") };
+                this.connection = this.paired ? "paired" : this.listenerActive ? "listening" : "offline";
+                this.lastError = this.activeRequest.error;
+                this.publish();
+            }
+            return null;
+        }
+        finally {
+            if (this.dispatchAbort === abortController)
+                this.dispatchAbort = null;
+        }
+    }
+    /** Interrupts local request state and asks the companion to revoke pairing. */
+    disconnect(reason = "browser_disconnected") {
+        const token = this.sessionToken;
+        const active = this.activeRequest;
+        if (active?.status === "working") {
+            this.activeRequest = { ...active, status: "interrupted", error: reason };
+        }
+        this.dispatchAbort?.abort();
+        this.discoveryAbort?.abort();
+        this.discoveryAbort = null;
+        this.pairingAbort?.abort();
+        this.pairingAbort = null;
+        this.eventSubscription?.close();
+        this.eventSubscription = null;
+        this.sessionToken = null;
+        clearStoredSession(this.projectId);
+        this.connection = "offline";
+        this.listenerActive = false;
+        this.paired = false;
+        this.lastError = reason === "reconnect" || reason === "browser_disconnected" ? undefined : reason;
+        this.publish();
+        if (token) {
+            const request = {
+                projectId: this.projectId,
+                origin: this.origin,
+                sessionToken: token,
+            };
+            const disconnectResult = this.transport.disconnect?.(request);
+            void disconnectResult?.catch(() => undefined);
+        }
+    }
+    async discover() {
+        if (!this.started || !this.enabled || this.pairingAbort)
+            return;
+        const abortController = new AbortController();
+        this.discoveryAbort?.abort();
+        this.discoveryAbort = abortController;
+        try {
+            const request = { projectId: this.projectId, origin: this.origin };
+            const status = await this.transport.discover(request, abortController.signal);
+            if (!this.started || abortController.signal.aborted)
+                return;
+            if (status) {
+                if (status.protocolVersion !== AGENT_PROTOCOL_VERSION || status.projectId !== this.projectId) {
+                    this.companionReachable = false;
+                    this.lastError = "The agent bridge project or protocol does not match this page.";
+                    this.publish();
+                }
+                else {
+                    this.companionReachable = true;
+                    if (this.connection !== "paired" && this.connection !== "working" && !this.pairingAbort) {
+                        this.applyStatus(status);
+                    }
+                }
+            }
+            else if (this.connection !== "paired" && this.connection !== "working" && !this.pairingAbort) {
+                this.connection = "offline";
+                this.listenerActive = false;
+                this.companionReachable = false;
+                this.paired = false;
+                this.lastError = undefined;
+                this.publish();
+            }
+        }
+        catch (error) {
+            if (!abortController.signal.aborted && this.started && this.connection !== "paired" && this.connection !== "working" && !this.pairingAbort) {
+                this.connection = "offline";
+                this.listenerActive = false;
+                this.companionReachable = false;
+                this.paired = false;
+                // Discovery failures are expected while the companion is not running;
+                // retain a quiet disconnected state rather than flashing an error.
+                this.lastError = undefined;
+                this.publish();
+            }
+            void error;
+        }
+        finally {
+            if (this.discoveryAbort === abortController)
+                this.discoveryAbort = null;
+            this.scheduleDiscovery();
+        }
+    }
+    scheduleDiscovery() {
+        if (!this.started || this.paired || this.pairingAbort || this.discoveryIntervalMs <= 0 || this.discoveryTimer !== null)
+            return;
+        this.discoveryTimer = setTimeout(() => {
+            this.discoveryTimer = null;
+            void this.discover();
+        }, this.discoveryIntervalMs);
+    }
+    scheduleReconnect() {
+        if (!this.started || this.pairingAbort || this.discoveryIntervalMs <= 0 || this.discoveryTimer !== null)
+            return;
+        this.discoveryTimer = setTimeout(() => {
+            this.discoveryTimer = null;
+            void this.restoreOrDiscover();
+        }, this.discoveryIntervalMs);
+    }
+    handleEvent(event) {
+        if (event.type === "status" || event.type === "connected") {
+            if (event.status.projectId !== this.projectId || event.status.protocolVersion !== AGENT_PROTOCOL_VERSION) {
+                this.handleDisconnect("The agent bridge project or protocol does not match this page.");
+                return;
+            }
+            this.applyStatus(event.status);
+            return;
+        }
+        if (event.type === "disconnected") {
+            this.handleDisconnect(event.reason);
+            return;
+        }
+        if (event.type === "canvas-command") {
+            void this.acknowledgeCanvasCommand(event.command);
+        }
+    }
+    async acknowledgeCanvasCommand(command) {
+        const handler = this.canvasCommandHandler;
+        const sessionToken = this.sessionToken;
+        if (!handler || !this.transport.acknowledgeCanvasCommand || !sessionToken)
+            return;
+        let acknowledgement;
+        try {
+            acknowledgement = await handler(command);
+        }
+        catch (error) {
+            acknowledgement = {
+                commandId: command.commandId,
+                ok: false,
+                error: {
+                    code: "controller_error",
+                    message: errorMessage(error, "The Canvas controller could not apply the command."),
+                },
+            };
+        }
+        if (acknowledgement.commandId !== command.commandId) {
+            acknowledgement = {
+                commandId: command.commandId,
+                ok: false,
+                error: { code: "command_mismatch", message: "The Canvas controller acknowledged a different command." },
+            };
+        }
+        const request = {
+            projectId: this.projectId,
+            origin: this.origin,
+            sessionToken,
+            acknowledgement,
+        };
+        try {
+            await this.transport.acknowledgeCanvasCommand(request);
+        }
+        catch {
+            // A command acknowledgement is best effort. The companion owns the
+            // bounded timeout and reports any expired command to its agent host.
+        }
+    }
+    applyStatus(status) {
+        this.companionReachable = true;
+        this.lastError = undefined;
+        this.listenerActive = status.listenerActive;
+        this.paired = status.paired;
+        this.connection = statusForConnection(status);
+        if (status.paired && this.discoveryTimer !== null) {
+            clearTimeout(this.discoveryTimer);
+            this.discoveryTimer = null;
+        }
+        if (status.request) {
+            this.applyRequestStatus(status.request.status, status.request.requestId, status.request.summary, status.request.error, status.request.changeRevision);
+        }
+        else if (status.listenerActive && status.paired && this.activeRequest?.status !== "working") {
+            // A re-armed MCP listen call is the lifecycle boundary for the previous
+            // terminal request. Drop only that terminal status; newer edits remain
+            // in the inspector's canonical change log.
+            this.activeRequest = null;
+        }
+        else if (this.activeRequest?.status === "working" && status.connection !== "working") {
+            // The bridge may omit a request during a brief re-arm transition. Do
+            // not mark a local request interrupted until the stream disconnects.
+            this.connection = "working";
+        }
+        if (!status.paired && this.sessionToken) {
+            this.handleDisconnect("The agent bridge pairing expired.");
+            return;
+        }
+        this.publish();
+    }
+    resetForDiscovery() {
+        this.eventSubscription?.close();
+        this.eventSubscription = null;
+        this.connection = "offline";
+        this.listenerActive = false;
+        this.companionReachable = false;
+        this.paired = false;
+        this.publish();
+    }
+    applyRequestStatus(status, requestId, summary, error, changeRevision) {
+        const active = this.activeRequest;
+        if (active && active.requestId !== requestId && active.localRequestId !== requestId) {
+            // A fresh server id can arrive before the POST response. Associate it
+            // with the one local request that was just marked working.
+            if (active.status !== "working")
+                return;
+            this.activeRequest = { ...active, requestId };
+        }
+        if (!this.activeRequest) {
+            this.activeRequest = {
+                localRequestId: requestId,
+                requestId,
+                prompt: "",
+                ...(changeRevision === undefined ? {} : { changeRevision }),
+                status,
+                ...(summary === undefined ? {} : { summary }),
+                ...(error === undefined ? {} : { error }),
+            };
+        }
+        else {
+            this.activeRequest = {
+                ...this.activeRequest,
+                requestId,
+                status,
+                ...(changeRevision === undefined ? {} : { changeRevision }),
+                ...(summary === undefined ? {} : { summary }),
+                ...(error === undefined ? {} : { error }),
+            };
+        }
+        if (status === "working")
+            this.connection = "working";
+        else if (this.paired)
+            this.connection = "paired";
+    }
+    handleDisconnect(reason = "The agent connection was lost.") {
+        this.eventSubscription?.close();
+        this.eventSubscription = null;
+        // An SSE disconnect is not proof that the coding request stopped. Keep
+        // its last known state until an authenticated status restore says
+        // otherwise. Explicit browser disconnect remains the interruption path.
+        this.connection = "offline";
+        this.listenerActive = false;
+        this.companionReachable = false;
+        this.paired = false;
+        this.lastError = reason;
+        this.publish();
+        this.scheduleReconnect();
+    }
+    makeSnapshot(stateOverride) {
+        const request = this.activeRequest;
+        const state = stateOverride ?? this.deriveState();
+        return {
+            state,
+            connection: this.connection,
+            listenerActive: this.listenerActive,
+            companionReachable: this.companionReachable,
+            paired: this.paired,
+            request: request ? {
+                requestId: request.requestId,
+                ...(request.changeRevision === undefined ? {} : { changeRevision: request.changeRevision }),
+                status: request.status,
+                ...(request.summary === undefined ? {} : { summary: request.summary }),
+                ...(request.error === undefined ? {} : { error: request.error }),
+            } : null,
+            ...(this.lastError === undefined ? {} : { error: this.lastError }),
+        };
+    }
+    deriveState() {
+        if (!this.enabled)
+            return "disabled";
+        if (this.connection === "offline")
+            return "disconnected";
+        if (this.connection === "listening")
+            return "available";
+        if (this.connection === "working" || this.activeRequest?.status === "working")
+            return "working";
+        if (this.activeRequest?.status === "completed")
+            return "completed";
+        if (this.activeRequest?.status === "failed")
+            return "failed";
+        if (this.activeRequest?.status === "interrupted")
+            return "interrupted";
+        return "connected";
+    }
+    publish(stateOverride) {
+        this.snapshot = Object.freeze(this.makeSnapshot(stateOverride));
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+let configuredTransport;
+const clients = new Map();
+/** Sets a host/test transport for subsequently created project clients. */
+export function configureAgentBridgeTransport(transport) {
+    for (const client of clients.values())
+        client.stop();
+    clients.clear();
+    configuredTransport = transport;
+}
+/** Clears cached clients and their active streams. */
+export function resetAgentClients() {
+    for (const client of clients.values())
+        client.stop();
+    clients.clear();
+}
+export function createAgentClient(options) {
+    return new AgentClient({ ...options, transport: options.transport ?? configuredTransport });
+}
+export function getAgentClient(projectId, options = {}) {
+    const origin = options.origin ?? (typeof window !== "undefined" ? window.location.origin : "http://localhost");
+    const key = `${projectId}\u0000${origin}`;
+    let client = clients.get(key);
+    if (!client) {
+        client = createAgentClient({ ...options, projectId, origin });
+        clients.set(key, client);
+    }
+    return client;
+}
+/** React hook used by the inspector handoff control. */
+export function useAgentClient(projectId, suppliedClient) {
+    const client = useMemo(() => suppliedClient ?? getAgentClient(projectId), [projectId, suppliedClient]);
+    useEffect(() => {
+        client.start();
+        return () => client.stop();
+    }, [client]);
+    return useSyncExternalStore(client.subscribe, client.getSnapshot, client.getSnapshot);
+}