@meshagent/meshagent-agents 0.43.0

package/dist/esm/room-storage-toolkit.js

@@ -0,0 +1,509 @@
+import { EmptyContent, JsonContent, LinkContent, RoomClient, RoomServerException, TextContent, Tool, Toolkit, ToolContentSpec, WebSocketClientProtocol, } from "@meshagent/meshagent";
+export const defaultRoomStorageToolkitMaxLength = 20000;
+export class RoomStorageToolkit extends Toolkit {
+    constructor({ client, projectId, rooms, readOnly = false, maxLength = defaultRoomStorageToolkitMaxLength, }) {
+        const config = new RoomStorageToolkitConfig({
+            client,
+            projectId,
+            rooms: normalizeRooms(rooms),
+            maxLength,
+        });
+        super({
+            name: "room_storage",
+            title: "room storage",
+            description: "tools for interacting with explicitly shared room storage",
+            tools: roomStorageTools({ config, readOnly }),
+        });
+    }
+}
+function roomStorageTools({ config, readOnly, }) {
+    const tools = [
+        new ListRoomFilesTool(config),
+        new ReadRoomFileTool(config),
+        new GrepRoomFileTool(config),
+        new GetRoomFileDownloadUrlTool(config),
+    ];
+    if (!readOnly) {
+        tools.push(new WriteRoomFileTool(config), new CopyRoomFileTool(config), new DeleteRoomFileTool(config));
+    }
+    return tools;
+}
+class RoomStorageToolkitConfig {
+    constructor({ client, projectId, rooms, maxLength, }) {
+        if (rooms.length === 0) {
+            throw new TypeError("RoomStorageToolkit requires at least one allowed room.");
+        }
+        if (maxLength <= 0) {
+            throw new TypeError("maxLength must be positive.");
+        }
+        this.client = client;
+        this.projectId = projectId;
+        this.rooms = rooms;
+        this.allowedRooms = new Set(rooms);
+        this.maxLength = maxLength;
+    }
+    requireRoom(value) {
+        return this.requireRoomField(value, "room_name");
+    }
+    requireRoomField(value, field) {
+        if (typeof value !== "string" || value.trim() === "") {
+            throw new RoomServerException(`${field} is required.`);
+        }
+        const roomName = value.trim();
+        if (!this.allowedRooms.has(roomName)) {
+            throw new RoomServerException(`room '${roomName}' is not shared with this toolkit.`);
+        }
+        return roomName;
+    }
+    requirePath(value) {
+        return this.requirePathField(value, "path");
+    }
+    requirePathField(value, field) {
+        if (typeof value !== "string") {
+            throw new RoomServerException(`${field} is required.`);
+        }
+        const path = value.trim();
+        const parts = path.split("/").filter((part) => part !== "");
+        if (parts.some((part) => part === "." || part === "..")) {
+            throw new RoomServerException(`${field} may not contain . or .. segments.`);
+        }
+        return path;
+    }
+    async withRoom(roomName, callback) {
+        const connection = await this.client.connectRoom(this.projectId, roomName);
+        const room = new RoomClient({
+            protocolFactory: WebSocketClientProtocol.createFactory({
+                url: connection.roomUrl,
+                token: connection.jwt,
+            }),
+            reconnectTimeout: 0,
+        });
+        try {
+            await room.start();
+            await room.ready;
+            return await callback(room);
+        }
+        finally {
+            room.dispose();
+        }
+    }
+}
+class RoomStorageTool extends Tool {
+    constructor(config, params) {
+        super({
+            name: params.name,
+            title: params.title,
+            description: params.description,
+            inputSchema: schema(config.rooms, params.properties, params.requiredFields),
+            outputSpec: params.outputSpec,
+        });
+        this.config = config;
+    }
+    roomName(args) {
+        return this.config.requireRoom(args.room_name);
+    }
+    path(args) {
+        return this.config.requirePath(args.path);
+    }
+}
+class ListRoomFilesTool extends RoomStorageTool {
+    constructor(config) {
+        super(config, {
+            name: "list_files_in_room",
+            title: "list files in room",
+            description: "list files in shared room storage",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "The room storage directory path to list.",
+                },
+            },
+            requiredFields: ["path"],
+            outputSpec: new ToolContentSpec({ types: ["json"], stream: false }),
+        });
+    }
+    async execute(args) {
+        const selectedRoom = this.roomName(args);
+        const selectedPath = this.path(args);
+        return await this.config.withRoom(selectedRoom, async (room) => {
+            const entries = await room.storage.list(selectedPath);
+            return new JsonContent({
+                json: { files: entries.map(storageEntryJson) },
+            });
+        });
+    }
+}
+class ReadRoomFileTool extends RoomStorageTool {
+    constructor(config) {
+        super(config, {
+            name: "read_file",
+            title: "read file",
+            description: "read a file from shared room storage",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "The room storage file path to read.",
+                },
+                offset: {
+                    type: ["integer", "null"],
+                    description: "Optional character offset for text files.",
+                },
+            },
+            requiredFields: ["path", "offset"],
+            outputSpec: new ToolContentSpec({
+                types: ["text", "file"],
+                stream: false,
+            }),
+        });
+    }
+    async execute(args) {
+        const selectedRoom = this.roomName(args);
+        const selectedPath = this.path(args);
+        const offset = optionalNonNegativeInt(args.offset, "offset") ?? 0;
+        return await this.config.withRoom(selectedRoom, async (room) => {
+            const content = await room.storage.download(selectedPath);
+            if (!isTextLike(content)) {
+                return content;
+            }
+            const text = new TextDecoder().decode(content.data);
+            return new TextContent({
+                text: sliceText(text, offset, this.config.maxLength),
+            });
+        });
+    }
+}
+class GrepRoomFileTool extends RoomStorageTool {
+    constructor(config) {
+        super(config, {
+            name: "grep_file",
+            title: "grep file",
+            description: "search a text file in shared room storage with a regular expression",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "The room storage file path to search.",
+                },
+                pattern: {
+                    type: "string",
+                    description: "A JavaScript regular expression pattern.",
+                },
+                offset: {
+                    type: ["integer", "null"],
+                    description: "Optional match offset.",
+                },
+                before: {
+                    type: ["integer", "null"],
+                    description: "Optional number of context lines before each match.",
+                },
+                after: {
+                    type: ["integer", "null"],
+                    description: "Optional number of context lines after each match.",
+                },
+            },
+            requiredFields: ["path", "pattern", "offset", "before", "after"],
+            outputSpec: new ToolContentSpec({ types: ["text"], stream: false }),
+        });
+    }
+    async execute(args) {
+        const selectedRoom = this.roomName(args);
+        const selectedPath = this.path(args);
+        if (typeof args.pattern !== "string" || args.pattern === "") {
+            throw new RoomServerException("pattern is required.");
+        }
+        const offset = optionalNonNegativeInt(args.offset, "offset") ?? 0;
+        const before = optionalNonNegativeInt(args.before, "before") ?? 0;
+        const after = optionalNonNegativeInt(args.after, "after") ?? 0;
+        const pattern = new RegExp(args.pattern);
+        return await this.config.withRoom(selectedRoom, async (room) => {
+            const content = await room.storage.download(selectedPath);
+            if (!isTextLike(content)) {
+                return new TextContent({
+                    text: "grep_file only supports text-like files. Use read_file for binary files.",
+                });
+            }
+            const text = new TextDecoder().decode(content.data);
+            return new TextContent({
+                text: grepText(text, pattern, offset, before, after, this.config.maxLength),
+            });
+        });
+    }
+}
+class GetRoomFileDownloadUrlTool extends RoomStorageTool {
+    constructor(config) {
+        super(config, {
+            name: "get_file_download_url",
+            title: "get file download url",
+            description: "get a temporary download URL for a file in shared room storage",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "The room storage file path.",
+                },
+            },
+            requiredFields: ["path"],
+            outputSpec: new ToolContentSpec({ types: ["link"], stream: false }),
+        });
+    }
+    async execute(args) {
+        const selectedRoom = this.roomName(args);
+        const selectedPath = this.path(args);
+        return await this.config.withRoom(selectedRoom, async (room) => {
+            const url = await room.storage.downloadUrl(selectedPath);
+            return new LinkContent({ url, name: basename(selectedPath) });
+        });
+    }
+}
+class WriteRoomFileTool extends RoomStorageTool {
+    constructor(config) {
+        super(config, {
+            name: "write_file",
+            title: "write file",
+            description: "write a text file to shared room storage",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "The room storage file path to write.",
+                },
+                text: { type: "string", description: "The text content to write." },
+                overwrite: {
+                    type: "boolean",
+                    description: "Whether to overwrite an existing file.",
+                },
+            },
+            requiredFields: ["path", "text", "overwrite"],
+            outputSpec: new ToolContentSpec({ types: ["text"], stream: false }),
+        });
+    }
+    async execute(args) {
+        const selectedRoom = this.roomName(args);
+        const selectedPath = this.path(args);
+        if (typeof args.text !== "string") {
+            throw new RoomServerException("text is required.");
+        }
+        return await this.config.withRoom(selectedRoom, async (room) => {
+            await room.storage.upload(selectedPath, new TextEncoder().encode(args.text), {
+                overwrite: args.overwrite === true,
+                name: basename(selectedPath),
+                mimeType: "text/plain",
+            });
+            return new TextContent({ text: "the file was saved" });
+        });
+    }
+}
+class DeleteRoomFileTool extends RoomStorageTool {
+    constructor(config) {
+        super(config, {
+            name: "delete_file",
+            title: "delete file",
+            description: "delete a file or directory from shared room storage",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "The room storage path to delete.",
+                },
+                recursive: {
+                    type: "boolean",
+                    description: "Whether to recursively delete directories.",
+                },
+            },
+            requiredFields: ["path", "recursive"],
+            outputSpec: new ToolContentSpec({ types: ["empty"], stream: false }),
+        });
+    }
+    async execute(args) {
+        const selectedRoom = this.roomName(args);
+        const selectedPath = this.path(args);
+        return await this.config.withRoom(selectedRoom, async (room) => {
+            await room.storage.delete(selectedPath, {
+                recursive: args.recursive === true,
+            });
+            return new EmptyContent();
+        });
+    }
+}
+class CopyRoomFileTool extends Tool {
+    constructor(config) {
+        super({
+            name: "copy_file",
+            title: "copy file",
+            description: "copy a file between explicitly shared room storage",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "source_room_name",
+                    "source_path",
+                    "destination_room_name",
+                    "destination_path",
+                    "overwrite",
+                ],
+                properties: {
+                    source_room_name: {
+                        type: "string",
+                        enum: config.rooms,
+                        description: "The shared room to copy the file from.",
+                    },
+                    source_path: {
+                        type: "string",
+                        description: "The room storage file path to copy from.",
+                    },
+                    destination_room_name: {
+                        type: "string",
+                        enum: config.rooms,
+                        description: "The shared room to copy the file to.",
+                    },
+                    destination_path: {
+                        type: "string",
+                        description: "The room storage file path to copy to.",
+                    },
+                    overwrite: {
+                        type: "boolean",
+                        description: "Whether to overwrite an existing destination file.",
+                    },
+                },
+            },
+            outputSpec: new ToolContentSpec({ types: ["text"], stream: false }),
+        });
+        this.config = config;
+    }
+    async execute(args) {
+        const sourceRoom = this.config.requireRoomField(args.source_room_name, "source_room_name");
+        const sourcePath = this.config.requirePathField(args.source_path, "source_path");
+        const destinationRoom = this.config.requireRoomField(args.destination_room_name, "destination_room_name");
+        const destinationPath = this.config.requirePathField(args.destination_path, "destination_path");
+        const overwrite = args.overwrite === true;
+        if (sourceRoom === destinationRoom) {
+            return await this.config.withRoom(sourceRoom, async (room) => {
+                const content = await room.storage.download(sourcePath);
+                await room.storage.upload(destinationPath, content.data, {
+                    overwrite,
+                    name: basename(destinationPath),
+                    mimeType: content.mimeType,
+                });
+                return new TextContent({ text: "the file was copied" });
+            });
+        }
+        const content = await this.config.withRoom(sourceRoom, (room) => room.storage.download(sourcePath));
+        return await this.config.withRoom(destinationRoom, async (room) => {
+            await room.storage.upload(destinationPath, content.data, {
+                overwrite,
+                name: basename(destinationPath),
+                mimeType: content.mimeType,
+            });
+            return new TextContent({ text: "the file was copied" });
+        });
+    }
+}
+function schema(rooms, properties, requiredFields) {
+    return {
+        type: "object",
+        additionalProperties: false,
+        required: ["room_name", ...requiredFields],
+        properties: {
+            room_name: {
+                type: "string",
+                enum: rooms,
+                description: "The shared room whose storage should be used.",
+            },
+            ...properties,
+        },
+    };
+}
+function normalizeRooms(rooms) {
+    return [
+        ...new Set(rooms.map((room) => room.trim()).filter((room) => room !== "")),
+    ];
+}
+function storageEntryJson(entry) {
+    return {
+        name: entry.name,
+        is_folder: entry.isFolder,
+        ...(entry.size != null ? { size: entry.size } : {}),
+        ...(entry.createdAt != null
+            ? { created_at: entry.createdAt.toISOString() }
+            : {}),
+        ...(entry.updatedAt != null
+            ? { updated_at: entry.updatedAt.toISOString() }
+            : {}),
+    };
+}
+function optionalNonNegativeInt(value, field) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new RoomServerException(`${field} must be a non-negative integer.`);
+    }
+    return value;
+}
+function isTextLike(content) {
+    const mimeType = content.mimeType.toLowerCase();
+    if (mimeType.startsWith("text/") ||
+        mimeType === "application/json" ||
+        mimeType === "application/xml" ||
+        mimeType === "image/svg+xml") {
+        return true;
+    }
+    const name = content.name.toLowerCase();
+    return [
+        ".csv",
+        ".htm",
+        ".html",
+        ".js",
+        ".json",
+        ".md",
+        ".txt",
+        ".ts",
+        ".tsx",
+        ".xml",
+        ".yaml",
+        ".yml",
+    ].some((suffix) => name.endsWith(suffix));
+}
+function sliceText(text, offset, maxLength) {
+    const start = Math.min(offset, text.length);
+    const end = Math.min(start + maxLength, text.length);
+    const sliced = text.slice(start, end);
+    return end >= text.length
+        ? sliced
+        : `${sliced}\n... truncated at ${end} of ${text.length} characters ...`;
+}
+function grepText(text, pattern, offset, before, after, maxLength) {
+    const lines = text.split("\n");
+    const selected = new Set();
+    let matchCount = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        if (!pattern.test(lines[index]))
+            continue;
+        pattern.lastIndex = 0;
+        if (matchCount < offset) {
+            matchCount += 1;
+            continue;
+        }
+        matchCount += 1;
+        for (let line = Math.max(0, index - before); line <= Math.min(lines.length - 1, index + after); line += 1) {
+            selected.add(line);
+        }
+    }
+    if (selected.size === 0)
+        return "No matches found.";
+    const sorted = [...selected].sort((a, b) => a - b);
+    let previous = -2;
+    let output = "";
+    for (const index of sorted) {
+        if (previous >= 0 && index !== previous + 1)
+            output += "--\n";
+        output += `${index + 1}: ${lines[index]}\n`;
+        previous = index;
+        if (output.length > maxLength) {
+            return `${output.slice(0, maxLength)}\n... truncated ...`;
+        }
+    }
+    return output;
+}
+function basename(path) {
+    const parts = path
+        .replace(/\\/g, "/")
+        .split("/")
+        .filter((part) => part !== "");
+    return parts.length === 0 ? "download" : parts[parts.length - 1];
+}

package/dist/esm/thread-storage.d.ts

@@ -0,0 +1,102 @@
+import { Schema } from "apache-arrow";
+import type { Participant, RoomClient } from "@meshagent/meshagent";
+import { ChangeEmitter } from "./change-emitter.js";
+import { BaseChatClient } from "./chat-client.js";
+import { type AgentThreadMessage } from "./agent-messages.js";
+export declare const defaultUntitledThreadName = "New Chat";
+export declare class ThreadListEntry {
+    readonly path: string;
+    readonly name: string;
+    readonly createdAt: string;
+    readonly modifiedAt: string;
+    constructor({ path, name, createdAt, modifiedAt }: {
+        path: string;
+        name: string;
+        createdAt: string;
+        modifiedAt: string;
+    });
+    renamed(name: string, modifiedAt: string): ThreadListEntry;
+    static fromDatasetRow(row: Record<string, unknown>): ThreadListEntry | null;
+}
+export declare abstract class ThreadStorage {
+    abstract get path(): string;
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+    abstract waitUntilReady(): Promise<void>;
+    abstract agentMessages(): AgentThreadMessage[];
+    abstract pushMessage({ message, sender }: {
+        message: AgentThreadMessage;
+        sender?: Participant;
+    }): void;
+}
+export declare abstract class ThreadStorageRepository extends ChangeEmitter {
+    abstract open(): Promise<void>;
+    abstract close(): Promise<void>;
+    abstract entries(): ThreadListEntry[];
+    abstract addOrUpdateThread(entry: ThreadListEntry): Promise<void>;
+    abstract deleteThread(threadPath: string): Promise<void>;
+    abstract renameThread(threadPath: string, name: string): Promise<void>;
+}
+export declare class DatasetThreadListRef {
+    readonly namespace?: string[];
+    readonly table: string;
+    constructor({ namespace, table }: {
+        namespace?: string[];
+        table: string;
+    });
+    static parse(url: string): DatasetThreadListRef;
+}
+export declare class DatasetThreadStorageRepository extends ThreadStorageRepository {
+    static readonly schema: Schema<any>;
+    readonly room: RoomClient;
+    readonly path: string;
+    readonly ref: DatasetThreadListRef;
+    private readonly entriesByPath;
+    private abortController?;
+    private refreshEntriesFuture?;
+    private watchTask?;
+    private initialSnapshotReady;
+    private closed;
+    constructor({ room, path }: {
+        room: RoomClient;
+        path: string;
+    });
+    open(): Promise<void>;
+    private watchLoop;
+    close(): Promise<void>;
+    entries(): ThreadListEntry[];
+    addOrUpdateThread(entry: ThreadListEntry): Promise<void>;
+    deleteThread(threadPath: string): Promise<void>;
+    renameThread(threadPath: string, name: string): Promise<void>;
+    private ensureTable;
+    private handleWatchEvent;
+    private refreshEntries;
+    private batchFor;
+}
+export declare class AgentThreadStorageRepository extends ThreadStorageRepository {
+    readonly chatClient: BaseChatClient;
+    readonly limit: number;
+    private readonly entriesByPath;
+    private subscription?;
+    private pendingOpen?;
+    private pendingListMessageId?;
+    private closed;
+    constructor({ chatClient, limit }: {
+        chatClient: BaseChatClient;
+        limit?: number;
+    });
+    open(): Promise<void>;
+    close(): Promise<void>;
+    entries(): ThreadListEntry[];
+    addOrUpdateThread(_entry: ThreadListEntry): Promise<void>;
+    deleteThread(threadPath: string): Promise<void>;
+    renameThread(threadPath: string, name: string): Promise<void>;
+    private requestList;
+    private handleEvent;
+    private handleThreadsListed;
+    private upsertThread;
+    private entryFromAgentThread;
+}
+export declare class DatasetThreadStorage extends DatasetThreadStorageRepository {
+}
+export declare function defaultThreadDisplayNameFromPath(path: string): string;