@meshagent/meshagent-react 0.38.1 → 0.38.3

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.38.3]
+- Breaking: TypeScript container image summaries now use `references`/`preferredRef` and metadata fields (timestamps/media type), and `inspectImage` returns manifests/layers/content size; `tags`/`size` are removed.
+- `getUsage` now supports filters for users, room, provider, model, and usage type.
+- Room connection and errors improved: `RoomServerException` now carries `statusCode` and `retryable`, and `RoomClient` can route OAuth/secret requests via handler options.
+- React hooks add robust connection retry/backoff, new authorization helpers, and optional secret/OAuth handlers; document connection now supports schema/initial JSON and improved cleanup.
+- New Livekit support (client + protocol channel) and room participant hook; hosted toolkits are now shared per room to avoid duplicate starts.
+- Breaking: `meshagent-react` no longer exports the legacy chat and file-upload modules.
+- Tailwind chat UI is rebuilt with multi-thread support, new thread creation via agent tools, and file attachment utilities, with new exports for thread and conversation helpers.
+
+## [0.38.2]
+- Stability
+
 ## [0.38.1]
 - Updated the TypeScript HTML schema example to use `SimpleValue.string` for value properties.
 - Removed the JavaScript and TypeScript schema registry example scripts as part of the example refresh.
@@ -6,7 +18,11 @@
 - Stability
 
 ## [0.37.2]
-- Stability
+- Reintroduced `staticAuthorization` for parity with the Flutter room utilities.
+- `useRoomConnection` now retries retryable startup failures, exposes a `retrying` state, and supports `onReady` plus custom client factories.
+- `useDocumentConnection` now supports `schema` and `initialJson`, reacts to room/path changes, and safely closes documents that finish opening after unmount.
+- `useRoomParticipants` now cleans up listeners correctly and updates cleanly when the room instance changes.
+- Added `livekit-client.ts` and `livekit-protocol.ts`, including a `room.livekit` helper and a typed LiveKit data-channel protocol adapter.
 
 ## [0.37.1]
 - Added `useAuth` to the React auth package to handle OAuth redirect/callback, token refresh, and profile loading without React Query, plus a `useEnsureLogin` compatibility wrapper.

package/README.md

@@ -1,43 +1,80 @@
 # [Meshagent](https://www.meshagent.com)
 
-## MeshAgent Typescript SDK
-
-See an example: https://github.com/meshagent/meshagent-tailwind/tree/main/example
-
-MeshAgent is your platform to create, deploy, and manage AI agents collaboratively and at scale, securely and in real time. 
-
-MeshAgent removes the infrastructure headaches of building and shipping AI Agents. It spins up secure, real-time "Rooms" that connect humans, agents, and shared context -- letting you launch, share, and refine agents in hours instead of weeks.
-
----
-
-**Documentation**: [docs.meshagent.com](https://docs.meshagent.com/)
-
-**Website**: [www.meshagent.com](https://www.meshagent.com/)
-
-**MeshAgent Studio**: [studio.meshagent.com](https://studio.meshagent.com/)
-
----
-
-## Why MeshAgent? 
-
-- **Real-time multi-user "Rooms" for true human-AI teamwork**: Secure workspaces, "Rooms", automatically spin-up when someone joins, tracking presence, chat, documents, and agent activity, and disappear when everyone leaves -- so people and agents stay in sync. 
-
-- **Accelerated feedback loop and shortened development cycle**: Invite a colleague or stakeholder into the MeshAgent Studio Room so they can see, hear, and interact with your agent immediately -- letting you demo, gather feedback, and iterate on the agent on the same day.
-
-- **Shareable links that showcase your agent**: After you deploy an agent, MeshAgent provides you a URL so colleagues or customers can jump straight into the Room, try the agent, and give feedback -- no code checkout, IDE, or GPU required. 
-
-- **Reusable and extensibly agent tools**: MeshAgent ships prebuilt, reusable toolkits for common Room interactions (e.g., file and document handling, media generation, dynamic UI interactions) and high-demand tasks (e.g., web search or document-to-Markdown conversion). Support for custom tools and the Model Context Protocol (MCP) enables you to seamlessly integrate any MCP-compatible service into a Room without changes to your applications. Tools are centrally managed like agents, allowing you to deploy them once and reuse them effortlessly.
-
-- **Built-in Observability**: Streaming logs and traces give you real-time insight into every message, agent action, and error. 
-
-- **Secure and elastic by default**: Project-scoped keys, on-demand provisioning, and auto-scaling infrastructure keep Rooms private, secure, and ready for your usage needs.
-
-- **Support across languages**: The same feature set (Rooms, Agents, Tools, Messaging, Queues, Storage, Documents, etc.) is exposed through official Python, Javascript, Typescript, and Dart SDKs, so every team member can work in their preferred language. 
-
-## Getting Setup
-
-Follow our [Getting Started Documentation](https://docs.meshagent.com/introduction/get_started) to setup your MeshAgent account, create your first project, and start building agents!
-
-## Next Steps and Examples
-
-To see examples of agents in action and to start building your own agents check out the MeshAgent docs at [docs.meshagent.com](https://docs.meshagent.com/)
+## MeshAgent React
+
+`@meshagent/meshagent-react` provides React hooks for the room and document utilities built on top of `@meshagent/meshagent`.
+
+The package is the React counterpart to the Flutter utility widgets in `meshagent-flutter`.
+
+## Hooks
+
+- `useRoomConnection(...)`: authorize, connect, retry retryable room startup failures, and dispose a `RoomClient`
+- `useDocumentConnection(...)`: open a room document, retry failed opens, and close it on unmount
+- `useRoomParticipants(...)`: track the current remote participants for a room
+- `useClientToolkits(...)`: host client-side toolkits for the lifetime of a component
+- `useRoomIndicators(...)`: listen for typing and thinking indicators on a chat path
+- `LivekitClient` / `room.livekit`: fetch LiveKit connection info from the room toolkit
+- `LivekitProtocolChannel`: bridge MeshAgent protocol traffic over LiveKit data messages
+
+## Example
+
+```tsx
+import {
+  staticAuthorization,
+  useDocumentConnection,
+  useRoomConnection,
+} from "@meshagent/meshagent-react";
+import type { RoomClient } from "@meshagent/meshagent";
+
+export function RoomScreen(props: {
+  projectId: string;
+  roomName: string;
+  url: string;
+  jwt: string;
+}) {
+  const connection = useRoomConnection({
+    authorization: staticAuthorization({
+      projectId: props.projectId,
+      roomName: props.roomName,
+      url: props.url,
+      jwt: props.jwt,
+    }),
+  });
+
+  if (connection.state === "authorizing" || connection.state === "connecting" || connection.state === "retrying") {
+    return <div>Connecting...</div>;
+  }
+
+  if (!connection.client || connection.state === "done") {
+    return <div>Connection failed: {String(connection.error)}</div>;
+  }
+
+  return <ConnectedRoom room={connection.client} />;
+}
+
+function ConnectedRoom({ room }: { room: RoomClient }) {
+  const documentConnection = useDocumentConnection({
+    room,
+    path: "/notes/thread.thread",
+  });
+
+  if (documentConnection.loading) {
+    return <div>Loading document...</div>;
+  }
+
+  if (documentConnection.error || !documentConnection.document) {
+    return <div>Document error: {String(documentConnection.error)}</div>;
+  }
+
+  return <div>Connected to document {documentConnection.document.id}</div>;
+}
+```
+
+## Authorization Helpers
+
+- `developmentAuthorization(...)`: generate a participant JWT locally for development
+- `staticAuthorization(...)`: reuse a JWT and room URL that your backend already issued
+
+## Documentation
+
+- [docs.meshagent.com](https://docs.meshagent.com/)

package/dist/cjs/client-toolkits.d.ts

@@ -1,8 +1,8 @@
-import { RoomClient, Toolkit } from '@meshagent/meshagent';
+import { RoomClient, Toolkit } from "@meshagent/meshagent";
 interface ClientToolkitsProps {
     room: RoomClient;
     toolkits: Toolkit[];
     public?: boolean;
 }
-export declare const useClientToolkits: ({ room, toolkits, public: isPublic }: ClientToolkitsProps) => void;
+export declare const useClientToolkits: ({ room, toolkits, public: isPublic, }: ClientToolkitsProps) => void;
 export {};

package/dist/cjs/client-toolkits.js

@@ -3,33 +3,166 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useClientToolkits = void 0;
 const react_1 = require("react");
 const meshagent_1 = require("@meshagent/meshagent");
-const useClientToolkits = ({ room, toolkits, public: isPublic = false }) => {
+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: (0, meshagent_1.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),
+        };
+    }
+}
+const useClientToolkits = ({ room, toolkits, public: isPublic = false, }) => {
+    const cleanupRef = (0, react_1.useRef)(Promise.resolve());
     (0, react_1.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 (0, meshagent_1.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/cjs/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/cjs/document-connection-scope.js

@@ -2,111 +2,117 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useDocumentConnection = useDocumentConnection;
 exports.useDocumentChanged = useDocumentChanged;
-exports.useRoomParticipants = useRoomParticipants;
 const react_1 = require("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.
  */
-function useDocumentConnection({ room, path, onConnected, onError }) {
-    const [schemaFileExists, setSchemaFileExists] = (0, react_1.useState)(null);
+function useDocumentConnection({ room, path, schema, initialJson, onConnected, onError, }) {
+    const [schemaFileExists, setSchemaFileExists] = (0, react_1.useState)(schema != null);
     const [document, setDocument] = (0, react_1.useState)(null);
     const [error, setError] = (0, react_1.useState)(null);
-    const openedRef = (0, react_1.useRef)(false);
-    const retryCountRef = (0, react_1.useRef)(0);
-    const timeoutRef = (0, react_1.useRef)(null);
-    const pathExtension = path.split('.').pop()?.toLowerCase();
-    const schemaFile = `.schemas/${pathExtension}.json`;
+    const onConnectedRef = (0, react_1.useRef)(onConnected);
+    const onErrorRef = (0, react_1.useRef)(onError);
+    (0, react_1.useEffect)(() => {
+        onConnectedRef.current = onConnected;
+    }, [onConnected]);
+    (0, react_1.useEffect)(() => {
+        onErrorRef.current = onError;
+    }, [onError]);
     (0, react_1.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,
     };
 }
-function useDocumentChanged({ document, onChanged }) {
+function useDocumentChanged({ document, onChanged, }) {
+    const onChangedRef = (0, react_1.useRef)(onChanged);
     (0, react_1.useEffect)(() => {
-        if (document) {
-            const s = document.listen(() => onChanged(document));
-            onChanged(document);
-            return () => s.unsubscribe();
-        }
-    }, [document]);
-}
-function useRoomParticipants(room) {
-    const [participants, setParticipants] = (0, react_1.useState)(() => []);
+        onChangedRef.current = onChanged;
+    }, [onChanged]);
     (0, react_1.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/cjs/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/cjs/index.js

@@ -14,9 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./chat"), exports);
 __exportStar(require("./client-toolkits"), exports);
 __exportStar(require("./document-connection-scope"), exports);
-__exportStar(require("./file-upload"), exports);
+__exportStar(require("./livekit-client"), exports);
+__exportStar(require("./livekit-protocol"), exports);
 __exportStar(require("./room-connection-scope"), exports);
+__exportStar(require("./room-participants"), exports);
 __exportStar(require("./subscribe-async-gen"), exports);

package/dist/cjs/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;
+    }
+}