@meshagent/meshagent-react 0.38.2 → 0.38.4

package/dist/esm/client-toolkits.js

@@ -1,32 +1,165 @@
-import { useEffect } from 'react';
-import { startHostedToolkit } from '@meshagent/meshagent';
-export const useClientToolkits = ({ room, toolkits, public: isPublic = false }) => {
+import { useEffect, useRef } from "react";
+import { startHostedToolkit } from "@meshagent/meshagent";
+const sharedHostedToolkits = new WeakMap();
+function getToolkitDefinition(toolkit, isPublic) {
+    return JSON.stringify({
+        public: isPublic,
+        name: toolkit.name,
+        title: toolkit.title,
+        description: toolkit.description,
+        thumbnailUrl: toolkit.thumbnailUrl ?? null,
+        rules: [...toolkit.rules],
+        tools: toolkit.tools.map((tool) => ({
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            inputSpec: tool.inputSpec?.toJson() ?? null,
+            outputSpec: tool.outputSpec?.toJson() ?? null,
+            thumbnailUrl: tool.thumbnailUrl ?? null,
+        })),
+    });
+}
+function getOrCreateSharedRoomToolkits(room) {
+    const existing = sharedHostedToolkits.get(room);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = new Map();
+    sharedHostedToolkits.set(room, created);
+    return created;
+}
+async function releaseHostedToolkitLease(room, toolkitName, entry) {
+    const roomToolkits = sharedHostedToolkits.get(room);
+    if (roomToolkits?.get(toolkitName) !== entry || entry.refs === 0) {
+        return;
+    }
+    entry.refs -= 1;
+    if (entry.refs > 0) {
+        return;
+    }
+    if (entry.stopPromise !== null) {
+        await entry.stopPromise;
+        return;
+    }
+    entry.stopPromise = (async () => {
+        try {
+            const hostedToolkit = await entry.startedToolkit;
+            await hostedToolkit.stop();
+        }
+        finally {
+            const latestRoomToolkits = sharedHostedToolkits.get(room);
+            if (latestRoomToolkits?.get(toolkitName) === entry) {
+                latestRoomToolkits.delete(toolkitName);
+                if (latestRoomToolkits.size === 0) {
+                    sharedHostedToolkits.delete(room);
+                }
+            }
+            entry.stopPromise = null;
+        }
+    })();
+    await entry.stopPromise;
+}
+async function acquireHostedToolkitLease({ room, toolkit, public_: isPublic, }) {
+    const definition = getToolkitDefinition(toolkit, isPublic);
+    while (true) {
+        const roomToolkits = getOrCreateSharedRoomToolkits(room);
+        const existing = roomToolkits.get(toolkit.name);
+        if (existing === undefined) {
+            const entry = {
+                definition,
+                refs: 1,
+                startedToolkit: startHostedToolkit({
+                    room,
+                    toolkit,
+                    public_: isPublic,
+                }),
+                stopPromise: null,
+            };
+            roomToolkits.set(toolkit.name, entry);
+            try {
+                await entry.startedToolkit;
+            }
+            catch (error) {
+                if (roomToolkits.get(toolkit.name) === entry) {
+                    roomToolkits.delete(toolkit.name);
+                    if (roomToolkits.size === 0) {
+                        sharedHostedToolkits.delete(room);
+                    }
+                }
+                throw error;
+            }
+            return {
+                release: () => releaseHostedToolkitLease(room, toolkit.name, entry),
+            };
+        }
+        if (existing.stopPromise !== null) {
+            await existing.stopPromise;
+            continue;
+        }
+        if (existing.definition !== definition) {
+            throw new Error(`toolkit '${toolkit.name}' is already hosted for this room with a different definition`);
+        }
+        existing.refs += 1;
+        try {
+            await existing.startedToolkit;
+        }
+        catch (error) {
+            existing.refs -= 1;
+            if (existing.refs === 0 && roomToolkits.get(toolkit.name) === existing) {
+                roomToolkits.delete(toolkit.name);
+                if (roomToolkits.size === 0) {
+                    sharedHostedToolkits.delete(room);
+                }
+            }
+            throw error;
+        }
+        return {
+            release: () => releaseHostedToolkitLease(room, toolkit.name, existing),
+        };
+    }
+}
+export const useClientToolkits = ({ room, toolkits, public: isPublic = false, }) => {
+    const cleanupRef = useRef(Promise.resolve());
     useEffect(() => {
         let disposed = false;
-        const startedToolkits = [];
-        void (async () => {
+        const toolkitLeases = [];
+        const waitForPreviousCleanup = cleanupRef.current;
+        const startPromise = (async () => {
+            await waitForPreviousCleanup;
             try {
                 for (const toolkit of toolkits) {
-                    const hostedToolkit = await startHostedToolkit({
+                    if (disposed) {
+                        return;
+                    }
+                    const lease = await acquireHostedToolkitLease({
                         room,
                         toolkit,
                         public_: isPublic,
                     });
                     if (disposed) {
-                        await hostedToolkit.stop();
-                        continue;
+                        await lease.release();
+                        return;
                     }
-                    startedToolkits.push(hostedToolkit);
+                    toolkitLeases.push(lease);
                 }
             }
             catch (error) {
-                await Promise.all(startedToolkits.map((toolkit) => toolkit.stop()));
-                console.error("unable to start client toolkits", error);
+                const leasesToRelease = toolkitLeases.splice(0);
+                await Promise.all(leasesToRelease.map((lease) => lease.release()));
+                if (!disposed) {
+                    console.error("unable to start client toolkits", error);
+                }
             }
         })();
         return () => {
             disposed = true;
-            void Promise.all(startedToolkits.map((toolkit) => toolkit.stop()));
+            cleanupRef.current = (async () => {
+                await startPromise;
+                const leasesToRelease = toolkitLeases.splice(0);
+                await Promise.all(leasesToRelease.map((lease) => lease.release()));
+            })().catch((error) => {
+                console.error("unable to stop client toolkits", error);
+            });
         };
     }, [room, toolkits, isPublic]);
 };

package/dist/esm/document-connection-scope.d.ts

@@ -1,7 +1,9 @@
-import { MeshDocument, RoomClient, RemoteParticipant } from '@meshagent/meshagent';
+import { MeshDocument, MeshSchema, RoomClient } from '@meshagent/meshagent';
 export interface UseDocumentConnectionProps {
     room: RoomClient;
     path: string;
+    schema?: MeshSchema;
+    initialJson?: Record<string, unknown>;
     onConnected?: (document: MeshDocument) => void;
     onError?: (error: unknown) => void;
 }
@@ -13,18 +15,11 @@ export interface UseDocumentConnectionResult {
 }
 /**
  * Connects to a Mesh document inside an existing RoomClient and keeps it in sync.
- *
- * The function retries with an exponential back‑off (capped at 60 s) until the
- * document becomes available or the component unmounts.
- *
- * @param room  An already‑connected RoomClient.
- * @param path  Path to the document inside the room.
  */
-export declare function useDocumentConnection({ room, path, onConnected, onError }: UseDocumentConnectionProps): UseDocumentConnectionResult;
-type onChangedHandler = (document: MeshDocument) => void;
-export declare function useDocumentChanged({ document, onChanged }: {
+export declare function useDocumentConnection({ room, path, schema, initialJson, onConnected, onError, }: UseDocumentConnectionProps): UseDocumentConnectionResult;
+type OnChangedHandler = (document: MeshDocument) => void;
+export declare function useDocumentChanged({ document, onChanged, }: {
     document: MeshDocument | null;
-    onChanged: onChangedHandler;
+    onChanged: OnChangedHandler;
 }): void;
-export declare function useRoomParticipants(room: RoomClient | null): Iterable<RemoteParticipant>;
 export {};

package/dist/esm/document-connection-scope.js

@@ -1,107 +1,114 @@
 import { useEffect, useRef, useState } from 'react';
+function getRetryDelayMs(retryCount) {
+    return Math.min(60000, 500 * 2 ** retryCount);
+}
+async function closeDocument(room, path) {
+    try {
+        await room.sync.close(path);
+    }
+    catch {
+    }
+}
 /**
  * Connects to a Mesh document inside an existing RoomClient and keeps it in sync.
- *
- * The function retries with an exponential back‑off (capped at 60 s) until the
- * document becomes available or the component unmounts.
- *
- * @param room  An already‑connected RoomClient.
- * @param path  Path to the document inside the room.
  */
-export function useDocumentConnection({ room, path, onConnected, onError }) {
-    const [schemaFileExists, setSchemaFileExists] = useState(null);
+export function useDocumentConnection({ room, path, schema, initialJson, onConnected, onError, }) {
+    const [schemaFileExists, setSchemaFileExists] = useState(schema != null);
     const [document, setDocument] = useState(null);
     const [error, setError] = useState(null);
-    const openedRef = useRef(false);
-    const retryCountRef = useRef(0);
-    const timeoutRef = useRef(null);
-    const pathExtension = path.split('.').pop()?.toLowerCase();
-    const schemaFile = `.schemas/${pathExtension}.json`;
+    const onConnectedRef = useRef(onConnected);
+    const onErrorRef = useRef(onError);
+    useEffect(() => {
+        onConnectedRef.current = onConnected;
+    }, [onConnected]);
+    useEffect(() => {
+        onErrorRef.current = onError;
+    }, [onError]);
     useEffect(() => {
         let cancelled = false;
-        const openDocument = async () => {
-            try {
-                const schemaExists = await room.storage.exists(schemaFile);
-                if (schemaExists) {
-                    setSchemaFileExists(true);
-                }
-                else {
-                    setSchemaFileExists(false);
-                    return;
-                }
-                const doc = await room.sync.open(path);
-                if (cancelled)
-                    return;
-                openedRef.current = true;
-                // sleep for 100 ms to ensure the document is ready
-                await new Promise(resolve => setTimeout(resolve, 100));
-                setDocument(doc);
-                setError(null);
-                if (onConnected) {
-                    onConnected(doc);
-                }
+        let retryTimeout = null;
+        let opened = false;
+        let nextRetryCount = 0;
+        const clearRetryTimeout = () => {
+            if (retryTimeout != null) {
+                clearTimeout(retryTimeout);
+                retryTimeout = null;
             }
-            catch (err) {
-                console.error('Failed to open document:', err);
-                if (cancelled)
+        };
+        const waitForRetry = (delayMs) => new Promise((resolve) => {
+            retryTimeout = setTimeout(() => {
+                retryTimeout = null;
+                resolve();
+            }, delayMs);
+        });
+        setDocument(null);
+        setError(null);
+        setSchemaFileExists(schema != null);
+        void (async () => {
+            while (!cancelled) {
+                try {
+                    if (schema == null) {
+                        const pathExtension = path.split('.').pop()?.toLowerCase();
+                        const schemaFile = `.schemas/${pathExtension}.json`;
+                        const nextSchemaExists = await room.storage.exists(schemaFile);
+                        if (cancelled) {
+                            return;
+                        }
+                        setSchemaFileExists(nextSchemaExists);
+                        if (!nextSchemaExists) {
+                            return;
+                        }
+                    }
+                    const nextDocument = await room.sync.open(path, { initialJson, schema });
+                    if (cancelled) {
+                        await closeDocument(room, path);
+                        return;
+                    }
+                    opened = true;
+                    nextRetryCount = 0;
+                    setDocument(nextDocument);
+                    setError(null);
+                    onConnectedRef.current?.(nextDocument);
                     return;
-                setError(err);
-                if (onError) {
-                    onError(err);
                 }
-                // Exponential back‑off: 500 ms, 1 s, 2 s, … up to 60 s.
-                const delay = Math.min(60000, 500 * 2 ** retryCountRef.current);
-                retryCountRef.current += 1;
-                timeoutRef.current = setTimeout(openDocument, delay);
+                catch (nextError) {
+                    if (cancelled) {
+                        return;
+                    }
+                    setDocument(null);
+                    setError(nextError);
+                    onErrorRef.current?.(nextError);
+                    await waitForRetry(getRetryDelayMs(nextRetryCount));
+                    nextRetryCount += 1;
+                }
             }
-        };
-        openDocument();
+        })();
         return () => {
             cancelled = true;
-            if (timeoutRef.current !== null) {
-                clearTimeout(timeoutRef.current);
-                timeoutRef.current = null;
-            }
-            if (openedRef.current) {
-                room.sync.close(path);
+            clearRetryTimeout();
+            if (opened) {
+                void closeDocument(room, path);
             }
-            setDocument(null);
-            retryCountRef.current = 0;
-            openedRef.current = false;
         };
-    }, [path]);
+    }, [initialJson, path, room, schema]);
     return {
         document,
         error,
-        loading: document === null && error == null,
-        schemaFileExists: schemaFileExists !== null ? schemaFileExists : true,
+        loading: document == null && error == null,
+        schemaFileExists,
     };
 }
-export function useDocumentChanged({ document, onChanged }) {
+export function useDocumentChanged({ document, onChanged, }) {
+    const onChangedRef = useRef(onChanged);
     useEffect(() => {
-        if (document) {
-            const s = document.listen(() => onChanged(document));
-            onChanged(document);
-            return () => s.unsubscribe();
-        }
-    }, [document]);
-}
-export function useRoomParticipants(room) {
-    const [participants, setParticipants] = useState(() => []);
+        onChangedRef.current = onChanged;
+    }, [onChanged]);
     useEffect(() => {
-        if (!room || !room.messaging) {
+        if (document == null) {
             return;
         }
-        const updateParticipants = () => setParticipants(room.messaging.remoteParticipants);
-        room.messaging.on('participant_added', updateParticipants);
-        room.messaging.on('participant_removed', updateParticipants);
-        room.messaging.on('messaging_enabled', updateParticipants);
-        updateParticipants();
-        return () => {
-            room.messaging.off('participant_added', updateParticipants);
-            room.messaging.off('participant_removed', updateParticipants);
-            room.messaging.on('messaging_enabled', updateParticipants);
-        };
-    }, [room]);
-    return participants;
+        const subscription = document.listen(() => onChangedRef.current(document));
+        onChangedRef.current(document);
+        return () => subscription.unsubscribe();
+    }, [document]);
 }

package/dist/esm/index.d.ts

@@ -1,6 +1,7 @@
-export * from './chat';
 export * from './client-toolkits';
 export * from './document-connection-scope';
-export * from './file-upload';
+export * from './livekit-client';
+export * from './livekit-protocol';
 export * from './room-connection-scope';
+export * from './room-participants';
 export * from './subscribe-async-gen';

package/dist/esm/index.js

@@ -1,6 +1,7 @@
-export * from './chat';
 export * from './client-toolkits';
 export * from './document-connection-scope';
-export * from './file-upload';
+export * from './livekit-client';
+export * from './livekit-protocol';
 export * from './room-connection-scope';
+export * from './room-participants';
 export * from './subscribe-async-gen';

package/dist/esm/livekit-client.d.ts

@@ -0,0 +1,23 @@
+import { RoomClient } from '@meshagent/meshagent';
+export declare class LivekitConnectionInfo {
+    readonly url: string;
+    readonly token: string;
+    constructor({ url, token }: {
+        url: string;
+        token: string;
+    });
+}
+export declare class LivekitClient {
+    readonly room: RoomClient;
+    constructor({ room }: {
+        room: RoomClient;
+    });
+    getConnectionInfo({ breakoutRoom, }?: {
+        breakoutRoom?: string;
+    }): Promise<LivekitConnectionInfo>;
+}
+declare module '@meshagent/meshagent' {
+    interface RoomClient {
+        readonly livekit: LivekitClient;
+    }
+}

package/dist/esm/livekit-client.js

@@ -0,0 +1,61 @@
+import { JsonContent, RoomClient, RoomServerException, } from '@meshagent/meshagent';
+export class LivekitConnectionInfo {
+    constructor({ url, token }) {
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "token", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.url = url;
+        this.token = token;
+    }
+}
+export class LivekitClient {
+    constructor({ room }) {
+        Object.defineProperty(this, "room", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.room = room;
+    }
+    async getConnectionInfo({ breakoutRoom, } = {}) {
+        const response = await this.room.invoke({
+            toolkit: 'livekit',
+            tool: 'connect',
+            input: { breakout_room: breakoutRoom ?? null },
+        });
+        if (!(response instanceof JsonContent)) {
+            throw new RoomServerException('unexpected return type from livekit.connect');
+        }
+        const responseJson = response.json;
+        if (typeof responseJson !== 'object'
+            || responseJson == null
+            || Array.isArray(responseJson)) {
+            throw new RoomServerException('unexpected return type from livekit.connect');
+        }
+        const token = responseJson.token;
+        const url = responseJson.url;
+        if (typeof token !== 'string' || typeof url !== 'string') {
+            throw new RoomServerException('unexpected return type from livekit.connect');
+        }
+        return new LivekitConnectionInfo({ token, url });
+    }
+}
+if (!Object.getOwnPropertyDescriptor(RoomClient.prototype, 'livekit')) {
+    Object.defineProperty(RoomClient.prototype, 'livekit', {
+        configurable: true,
+        enumerable: false,
+        get() {
+            return new LivekitClient({ room: this });
+        },
+    });
+}

package/dist/esm/livekit-protocol.d.ts

@@ -0,0 +1,21 @@
+import type { ProtocolChannel } from '@meshagent/meshagent';
+import * as livekit from 'livekit-client';
+export declare class LivekitProtocolChannel implements ProtocolChannel {
+    private readonly room;
+    private readonly remote;
+    private readonly topic;
+    private onDataReceived?;
+    private readonly handleDataReceivedBound;
+    constructor({ room, remote, topic, }: {
+        room: livekit.Room;
+        remote: livekit.RemoteParticipant;
+        topic: string;
+    });
+    start(onDataReceived: (data: Uint8Array) => void, _params: {
+        onDone?: () => void;
+        onError?: (error: unknown) => void;
+    }): void;
+    sendData(data: Uint8Array): Promise<void>;
+    dispose(): void;
+    private handleDataReceived;
+}

package/dist/esm/livekit-protocol.js

@@ -0,0 +1,60 @@
+import * as livekit from 'livekit-client';
+export class LivekitProtocolChannel {
+    constructor({ room, remote, topic, }) {
+        Object.defineProperty(this, "room", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "remote", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "topic", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onDataReceived", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "handleDataReceivedBound", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.room = room;
+        this.remote = remote;
+        this.topic = topic;
+        this.handleDataReceivedBound = this.handleDataReceived.bind(this);
+    }
+    start(onDataReceived, _params) {
+        this.onDataReceived = onDataReceived;
+        this.room.on(livekit.RoomEvent.DataReceived, this.handleDataReceivedBound);
+    }
+    async sendData(data) {
+        await this.room.localParticipant.publishData(data, {
+            reliable: true,
+            topic: this.topic,
+            destinationIdentities: [this.remote.identity],
+        });
+    }
+    dispose() {
+        this.room.off(livekit.RoomEvent.DataReceived, this.handleDataReceivedBound);
+        this.onDataReceived = undefined;
+    }
+    handleDataReceived(payload, participant, _kind, topic, _encryptionType) {
+        const identityMatches = participant?.identity === this.remote.identity;
+        if (identityMatches && topic === this.topic) {
+            this.onDataReceived?.(payload);
+        }
+    }
+}

package/dist/esm/room-connection-scope.d.ts

@@ -1,8 +1,5 @@
-import { RoomClient } from '@meshagent/meshagent';
-export interface RoomConnectionInfo {
-    url: string;
-    jwt: string;
-}
+import { type OAuthTokenRequest, RoomClient, type SecretRequest } from '@meshagent/meshagent';
+import type { RoomConnectionInfo } from '@meshagent/meshagent';
 export declare const developmentAuthorization: ({ url, projectId, apiKeyId, participantName, roomName, secret, }: {
     url: string;
     projectId: string;
@@ -11,27 +8,30 @@ export declare const developmentAuthorization: ({ url, projectId, apiKeyId, part
     roomName: string;
     secret: string;
 }) => (() => Promise<RoomConnectionInfo>);
+export declare const staticAuthorization: ({ projectId, roomName, url, jwt, }: {
+    projectId: string;
+    roomName: string;
+    url: string;
+    jwt: string;
+}) => (() => Promise<RoomConnectionInfo>);
 export interface UseRoomConnectionOptions {
-    /** Async function that returns `{ url, jwt }` for the room. */
-    authorization: () => Promise<{
-        url: string;
-        jwt: string;
-    }>;
-    /** Enable the optional messaging layer (default = `true`). */
+    reconnectKey?: string;
+    authorization: () => Promise<RoomConnectionInfo>;
     enableMessaging?: boolean;
+    onReady?: (room: RoomClient) => void;
+    oauthTokenRequestHandler?: (room: RoomClient, request: OAuthTokenRequest) => Promise<void> | void;
+    secretRequestHandler?: (room: RoomClient, request: SecretRequest) => Promise<void> | void;
+    roomClientFactory?: (connectionInfo: RoomConnectionInfo) => RoomClient;
 }
-/**
- * Shape of the object returned by the hook.
- */
 export interface UseRoomConnectionResult {
     client: RoomClient | null;
-    state: 'authorizing' | 'connecting' | 'ready' | 'done';
+    state: 'authorizing' | 'connecting' | 'retrying' | 'ready' | 'done';
     ready: boolean;
     done: boolean;
     error: unknown;
     dispose: () => void;
 }
-export declare function useRoomConnection(props: UseRoomConnectionOptions): UseRoomConnectionResult;
+export declare function useRoomConnection({ reconnectKey, authorization, enableMessaging, onReady, oauthTokenRequestHandler, secretRequestHandler, roomClientFactory, }: UseRoomConnectionOptions): UseRoomConnectionResult;
 export interface UseRoomIndicatorsResult {
     typing: boolean;
     thinking: boolean;