@meshagent/meshagent-agents 0.43.0

package/dist/esm/images-dataset.d.ts

@@ -0,0 +1,83 @@
+import { Schema } from "apache-arrow";
+import { type RoomClient } from "@meshagent/meshagent";
+export declare class SavedImage {
+    readonly id: string;
+    readonly mimeType: string;
+    readonly createdAt: Date;
+    readonly createdBy: string;
+    readonly annotations: Readonly<Record<string, string>>;
+    constructor({ id, mimeType, createdAt, createdBy, annotations, }: {
+        id: string;
+        mimeType: string;
+        createdAt: Date;
+        createdBy: string;
+        annotations: Record<string, string>;
+    });
+}
+export declare class ImageDatasetRecord {
+    readonly data: Uint8Array;
+    readonly mimeType: string;
+    constructor({ data, mimeType }: {
+        data: Uint8Array;
+        mimeType: string;
+    });
+}
+export declare class DatasetUriReference {
+    readonly table: string;
+    readonly namespace?: string[];
+    readonly id: string;
+    constructor({ table, namespace, id }: {
+        table: string;
+        namespace?: string[];
+        id: string;
+    });
+}
+export declare class ImageDatasetClient {
+    readonly room: RoomClient;
+    readonly table: string;
+    constructor({ room, table }: {
+        room: RoomClient;
+        table?: string;
+    });
+    static datasetUriReference(uri: string): DatasetUriReference;
+    readRecord(imageId: string, { table, namespace, fallbackMimeType, }?: {
+        table?: string;
+        namespace?: string[];
+        fallbackMimeType?: string;
+    }): Promise<ImageDatasetRecord | null>;
+    readRecordFromUri(uri: string, { fallbackMimeType }?: {
+        fallbackMimeType?: string;
+    }): Promise<ImageDatasetRecord | null>;
+}
+export declare class ImagesDataset extends ImageDatasetClient {
+    static readonly tableName = "images";
+    static readonly schema: Schema<any>;
+    readonly namespace?: string[];
+    private ready?;
+    constructor({ room, table, namespace }: {
+        room: RoomClient;
+        table?: string;
+        namespace?: string[];
+    });
+    save({ data, mimeType, createdBy, annotations, imageId, createdAt, }: {
+        data: Uint8Array;
+        mimeType: string;
+        createdBy: string;
+        annotations?: Record<string, string>;
+        imageId?: string;
+        createdAt?: Date;
+    }): Promise<SavedImage>;
+    read(imageId: string): Promise<SavedImage | null>;
+    search({ where, limit }?: {
+        where?: unknown;
+        limit?: number;
+    }): Promise<SavedImage[]>;
+    readRecord(imageId: string, { table, namespace, fallbackMimeType, }?: {
+        table?: string;
+        namespace?: string[];
+        fallbackMimeType?: string;
+    }): Promise<ImageDatasetRecord | null>;
+    private ensureReady;
+    private createTable;
+    private batchFor;
+}

package/dist/esm/images-dataset.js

@@ -0,0 +1,274 @@
+import { Field, LargeBinary, List, Schema, Struct, TimestampMicrosecond, Utf8, tableFromArrays, } from "apache-arrow";
+import { RoomServerException, } from "@meshagent/meshagent";
+import { v4 as uuidv4 } from "uuid";
+export class SavedImage {
+    constructor({ id, mimeType, createdAt, createdBy, annotations, }) {
+        this.id = id;
+        this.mimeType = mimeType;
+        this.createdAt = createdAt;
+        this.createdBy = createdBy;
+        this.annotations = Object.freeze({ ...annotations });
+    }
+}
+export class ImageDatasetRecord {
+    constructor({ data, mimeType }) {
+        this.data = data;
+        this.mimeType = mimeType;
+    }
+}
+export class DatasetUriReference {
+    constructor({ table, namespace, id }) {
+        this.table = table;
+        this.namespace = namespace;
+        this.id = id;
+    }
+}
+export class ImageDatasetClient {
+    constructor({ room, table = ImagesDataset.tableName }) {
+        this.room = room;
+        this.table = table;
+    }
+    static datasetUriReference(uri) {
+        const parsed = new URL(uri);
+        if (parsed.protocol !== "dataset:") {
+            throw new TypeError("dataset image URI must use the dataset:// scheme");
+        }
+        const id = parsed.searchParams.get("id")?.trim();
+        if (id == null || id === "") {
+            throw new TypeError("dataset image URI must include an id query parameter");
+        }
+        const segments = [
+            ...(parsed.hostname.trim() !== "" ? [parsed.hostname.trim()] : []),
+            ...parsed.pathname.split("/").map((segment) => segment.trim()).filter((segment) => segment !== ""),
+        ];
+        if (segments.length === 0) {
+            throw new TypeError("dataset image URI must include a table path");
+        }
+        return new DatasetUriReference({
+            table: segments[segments.length - 1],
+            namespace: segments.length === 1 ? undefined : segments.slice(0, -1),
+            id,
+        });
+    }
+    async readRecord(imageId, { table, namespace, fallbackMimeType, } = {}) {
+        const normalizedId = normalizeImageId(imageId);
+        const rows = await this.room.datasets.search({
+            table: table ?? this.table,
+            where: { id: normalizedId },
+            limit: 1,
+            select: ["data", "mime_type"],
+            namespace,
+        });
+        const record = rowsFromTable(rows)[0];
+        if (record == null) {
+            return null;
+        }
+        const data = record.data;
+        const bytes = data instanceof Uint8Array ? data : Array.isArray(data) ? Uint8Array.from(data) : null;
+        if (bytes == null) {
+            return null;
+        }
+        const rawMimeType = record.mime_type;
+        return new ImageDatasetRecord({
+            data: bytes,
+            mimeType: typeof rawMimeType === "string" && rawMimeType.trim() !== "" ? rawMimeType.trim() : fallbackMimeType ?? "image/png",
+        });
+    }
+    readRecordFromUri(uri, { fallbackMimeType } = {}) {
+        const reference = ImageDatasetClient.datasetUriReference(uri);
+        return this.readRecord(reference.id, {
+            table: reference.table,
+            namespace: reference.namespace,
+            fallbackMimeType,
+        });
+    }
+}
+export class ImagesDataset extends ImageDatasetClient {
+    constructor({ room, table = ImagesDataset.tableName, namespace }) {
+        super({ room, table });
+        this.namespace = namespace;
+    }
+    async save({ data, mimeType, createdBy, annotations = {}, imageId, createdAt, }) {
+        const normalizedId = imageId != null && imageId.trim() !== "" ? imageId.trim() : uuidv4();
+        const normalizedMimeType = mimeType.trim();
+        if (normalizedMimeType === "") {
+            throw new TypeError("image MIME type cannot be empty");
+        }
+        const normalizedCreatedBy = createdBy.trim();
+        if (normalizedCreatedBy === "") {
+            throw new TypeError("creator cannot be empty");
+        }
+        const timestamp = createdAt ?? new Date();
+        const saved = new SavedImage({
+            id: normalizedId,
+            mimeType: normalizedMimeType,
+            createdAt: timestamp,
+            createdBy: normalizedCreatedBy,
+            annotations,
+        });
+        await this.ensureReady();
+        await retryCommitConflicts(() => this.room.datasets.insert({
+            table: this.table,
+            records: this.batchFor([{ image: saved, data }]),
+            namespace: this.namespace,
+        }));
+        return saved;
+    }
+    async read(imageId) {
+        await this.ensureReady();
+        const rows = await this.room.datasets.search({
+            table: this.table,
+            where: { id: normalizeImageId(imageId) },
+            limit: 1,
+            select: ["id", "mime_type", "created_at", "created_by"],
+            namespace: this.namespace,
+        });
+        const row = rowsFromTable(rows)[0];
+        return row == null ? null : savedImageFromRow(row);
+    }
+    async search({ where, limit } = {}) {
+        await this.ensureReady();
+        const rows = await this.room.datasets.search({
+            table: this.table,
+            where: where,
+            limit,
+            select: ["id", "mime_type", "created_at", "created_by"],
+            namespace: this.namespace,
+        });
+        return rowsFromTable(rows).map(savedImageFromRow).filter((entry) => entry != null);
+    }
+    async readRecord(imageId, { table, namespace, fallbackMimeType, } = {}) {
+        await this.ensureReady();
+        return super.readRecord(imageId, {
+            table: table ?? this.table,
+            namespace: namespace ?? this.namespace,
+            fallbackMimeType,
+        });
+    }
+    ensureReady() {
+        this.ready ?? (this.ready = this.createTable());
+        return this.ready;
+    }
+    async createTable() {
+        await this.room.datasets.createTableWithSchema({
+            name: this.table,
+            schema: ImagesDataset.schema,
+            mode: "create_if_not_exists",
+            namespace: this.namespace,
+        });
+        try {
+            await this.room.datasets.createIndex({
+                table: this.table,
+                config: { column: "id", index_type: "BTREE" },
+                namespace: this.namespace,
+            });
+        }
+        catch {
+        }
+    }
+    batchFor(rows) {
+        return tableFromArrays({
+            id: rows.map((row) => row.image.id),
+            data: rows.map((row) => row.data),
+            mime_type: rows.map((row) => row.image.mimeType),
+            created_at: rows.map((row) => row.image.createdAt),
+            created_by: rows.map((row) => row.image.createdBy),
+            annotations: rows.map((row) => Object.entries(row.image.annotations).map(([key, value]) => ({ key, value }))),
+        });
+    }
+}
+ImagesDataset.tableName = "images";
+ImagesDataset.schema = new Schema([
+    new Field("id", new Utf8(), false),
+    new Field("data", new LargeBinary(), false, new Map([["content-type", "image/*"]])),
+    new Field("mime_type", new Utf8(), false),
+    new Field("created_at", new TimestampMicrosecond("UTC"), false),
+    new Field("created_by", new Utf8(), false),
+    new Field("annotations", new List(new Field("item", new Struct([
+        new Field("key", new Utf8(), false),
+        new Field("value", new Utf8(), true),
+    ]), true)), true),
+]);
+function normalizeImageId(imageId) {
+    const normalized = imageId.trim();
+    if (normalized === "") {
+        throw new TypeError("image id cannot be empty");
+    }
+    return normalized;
+}
+function savedImageFromRow(row) {
+    const id = stringFromDatasetValue(row.id);
+    const mimeType = stringFromDatasetValue(row.mime_type);
+    const createdBy = stringFromDatasetValue(row.created_by);
+    if (id == null || mimeType == null || createdBy == null) {
+        return null;
+    }
+    return new SavedImage({
+        id,
+        mimeType,
+        createdAt: dateTimeFromDatasetValue(row.created_at) ?? new Date(0),
+        createdBy,
+        annotations: annotationsFromValue(row.annotations),
+    });
+}
+function dateTimeFromDatasetValue(value) {
+    if (value instanceof Date) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
+    if (typeof value === "number") {
+        return new Date(Math.trunc(value / 1000));
+    }
+    if (typeof value === "bigint") {
+        return new Date(Number(value / 1000n));
+    }
+    return null;
+}
+function stringFromDatasetValue(value) {
+    if (value == null) {
+        return null;
+    }
+    return typeof value === "string" ? value : String(value);
+}
+function annotationsFromValue(value) {
+    if (!Array.isArray(value)) {
+        return {};
+    }
+    const annotations = {};
+    for (const item of value) {
+        if (item != null && typeof item === "object" && !Array.isArray(item)) {
+            const raw = item;
+            if (typeof raw.key === "string" && typeof raw.value === "string") {
+                annotations[raw.key] = raw.value;
+            }
+        }
+    }
+    return annotations;
+}
+async function retryCommitConflicts(action) {
+    for (let attempt = 0; attempt < 6; attempt += 1) {
+        try {
+            await action();
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof RoomServerException)) {
+                throw error;
+            }
+            const retryable = error.retryable ||
+                error.message.toLowerCase().includes("commit conflict") ||
+                error.message.toLowerCase().includes("conflicting commit");
+            if (!retryable || attempt === 5) {
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+        }
+    }
+}
+function rowsFromTable(table) {
+    const tables = Array.isArray(table) ? table : [table];
+    return tables.flatMap((entry) => entry.toArray().map((row) => ({ ...row })));
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./agent-messages.js";
+export * from "./chat-client.js";
+export * from "./images-dataset.js";
+export * from "./room-shell-toolkit.js";
+export * from "./room-storage-toolkit.js";
+export * from "./thread-storage.js";

package/dist/esm/index.js

@@ -0,0 +1,6 @@
+export * from "./agent-messages.js";
+export * from "./chat-client.js";
+export * from "./images-dataset.js";
+export * from "./room-shell-toolkit.js";
+export * from "./room-storage-toolkit.js";
+export * from "./thread-storage.js";

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/room-shell-toolkit.d.ts

@@ -0,0 +1,14 @@
+import { Meshagent, Toolkit, type ContainerMountSpec } from "@meshagent/meshagent";
+export declare const defaultRoomShellMaxOutputLength: number;
+export declare const defaultRoomShellMounts: ContainerMountSpec;
+export declare class RoomShellToolkit extends Toolkit {
+    constructor({ client, projectId, rooms, image, workingDir, mounts, env, }: {
+        client: Meshagent;
+        projectId: string;
+        rooms: string[];
+        image?: string;
+        workingDir?: string;
+        mounts?: ContainerMountSpec;
+        env?: Record<string, string>;
+    });
+}

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

@@ -0,0 +1,270 @@
+import { JsonContent, RoomClient, RoomServerException, Tool, Toolkit, ToolContentSpec, WebSocketClientProtocol, } from "@meshagent/meshagent";
+export const defaultRoomShellMaxOutputLength = 50 * 1024;
+export const defaultRoomShellMounts = {
+    room: [{ path: "/data" }],
+};
+export class RoomShellToolkit extends Toolkit {
+    constructor({ client, projectId, rooms, image = "meshagent/python:default", workingDir, mounts = defaultRoomShellMounts, env = {}, }) {
+        super({
+            name: "room_shell",
+            title: "room shell",
+            description: "execute shell commands in containers for explicitly shared rooms",
+            tools: [
+                new RoomShellTool(new RoomShellToolkitConfig({
+                    client,
+                    projectId,
+                    rooms: normalizeRooms(rooms),
+                    image,
+                    workingDir,
+                    mounts,
+                    env,
+                })),
+            ],
+        });
+    }
+}
+class RoomShellToolkitConfig {
+    constructor({ client, projectId, rooms, image, workingDir, mounts, env, }) {
+        this.containerIdsByRoom = new Map();
+        if (rooms.length === 0) {
+            throw new TypeError("RoomShellToolkit requires at least one allowed room.");
+        }
+        if (image.trim() === "") {
+            throw new TypeError("image must not be empty.");
+        }
+        this.client = client;
+        this.projectId = projectId;
+        this.rooms = rooms;
+        this.allowedRooms = new Set(rooms);
+        this.image = image;
+        this.workingDir = workingDir;
+        this.mounts = mounts;
+        this.env = { ...env };
+    }
+    requireRoom(value) {
+        if (typeof value !== "string" || value.trim() === "") {
+            throw new RoomServerException("room_name is required.");
+        }
+        const roomName = value.trim();
+        if (!this.allowedRooms.has(roomName)) {
+            throw new RoomServerException(`room '${roomName}' is not shared with this toolkit.`);
+        }
+        return roomName;
+    }
+    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();
+        }
+    }
+    async getContainerId(room, roomName) {
+        const cached = this.containerIdsByRoom.get(roomName);
+        if (cached != null) {
+            const containers = await room.containers.list({});
+            if (containers.some((container) => container.id === cached)) {
+                return cached;
+            }
+        }
+        const containerId = await room.containers.run({
+            image: this.image,
+            command: "sleep infinity",
+            mounts: this.mounts,
+            writableRootFs: true,
+            env: this.env,
+        });
+        this.containerIdsByRoom.set(roomName, containerId);
+        return containerId;
+    }
+}
+class RoomShellTool extends Tool {
+    constructor(config) {
+        super({
+            name: "container_shell",
+            title: "container shell",
+            description: "execute shell commands in a container for explicitly shared room storage",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "room_name",
+                    "commands",
+                    "max_output_length",
+                    "timeout_ms",
+                ],
+                properties: {
+                    room_name: {
+                        type: "string",
+                        enum: config.rooms,
+                        description: "The shared room where the shell should run.",
+                    },
+                    commands: {
+                        type: "array",
+                        minItems: 1,
+                        items: { type: "string" },
+                        description: "Shell commands to execute.",
+                    },
+                    max_output_length: {
+                        type: ["integer", "null"],
+                        description: "Optional maximum number of characters to return per output stream.",
+                    },
+                    timeout_ms: {
+                        type: ["integer", "null"],
+                        description: "Optional timeout per command in milliseconds.",
+                    },
+                },
+            },
+            outputSpec: new ToolContentSpec({ types: ["json"], stream: false }),
+        });
+        this.config = config;
+    }
+    async execute(args) {
+        const roomName = this.config.requireRoom(args.room_name);
+        const commands = requiredStringList(args.commands, "commands");
+        const maxOutputLength = optionalPositiveInt(args.max_output_length, "max_output_length") ??
+            defaultRoomShellMaxOutputLength;
+        const timeoutMs = optionalPositiveInt(args.timeout_ms, "timeout_ms") ?? 60000;
+        return await this.config.withRoom(roomName, async (room) => {
+            const containerId = await this.config.getContainerId(room, roomName);
+            const results = [];
+            for (const command of commands) {
+                const commandToRun = commandWithWorkingDir(command, this.config.workingDir);
+                const session = room.containers.exec({
+                    containerId,
+                    command: `bash -lc ${shellQuote(commandToRun)}`,
+                });
+                const stdout = new OutputAccumulator(maxOutputLength);
+                const stderr = new OutputAccumulator(maxOutputLength);
+                const stdoutTask = collectOutput(session.output, stdout);
+                const stderrTask = collectOutput(session.stderr, stderr);
+                try {
+                    const exitCode = await timeout(session.result, timeoutMs);
+                    await finishOutputTasks(stdoutTask, stderrTask);
+                    results.push({
+                        outcome: { type: "exit", exit_code: exitCode },
+                        stdout: stdout.finish(),
+                        stderr: stderr.finish(),
+                    });
+                }
+                catch (error) {
+                    if (error instanceof TimeoutError) {
+                        await session.kill();
+                        await finishOutputTasks(stdoutTask, stderrTask);
+                        results.push({
+                            outcome: { type: "timeout" },
+                            stdout: stdout.finish(),
+                            stderr: stderr.finish(),
+                        });
+                    }
+                    else {
+                        await finishOutputTasks(stdoutTask, stderrTask);
+                        results.push({
+                            outcome: { type: "exit", exit_code: 1 },
+                            stdout: stdout.finish(),
+                            stderr: String(error),
+                        });
+                    }
+                    break;
+                }
+            }
+            return new JsonContent({ json: { results } });
+        });
+    }
+}
+async function finishOutputTasks(...tasks) {
+    for (const task of tasks) {
+        try {
+            await task;
+        }
+        catch {
+        }
+    }
+}
+function normalizeRooms(rooms) {
+    return [
+        ...new Set(rooms.map((room) => room.trim()).filter((room) => room !== "")),
+    ];
+}
+function requiredStringList(value, field) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new RoomServerException(`${field} must be a non-empty string array.`);
+    }
+    const output = [];
+    for (const item of value) {
+        if (typeof item !== "string" || item === "") {
+            throw new RoomServerException(`${field} must be a non-empty string array.`);
+        }
+        output.push(item);
+    }
+    return output;
+}
+function optionalPositiveInt(value, field) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new RoomServerException(`${field} must be a positive integer.`);
+    }
+    return value;
+}
+function commandWithWorkingDir(command, workingDir) {
+    return workingDir == null || workingDir.trim() === ""
+        ? command
+        : `cd ${shellQuote(workingDir)} && ${command}`;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+async function collectOutput(stream, accumulator) {
+    for await (const chunk of stream) {
+        accumulator.add(chunk);
+    }
+}
+class OutputAccumulator {
+    constructor(maxLength) {
+        this.maxLength = maxLength;
+        this.buffer = "";
+        this.truncated = false;
+    }
+    add(data) {
+        if (this.buffer.length >= this.maxLength) {
+            this.truncated = true;
+            return;
+        }
+        const text = new TextDecoder().decode(data);
+        const remaining = this.maxLength - this.buffer.length;
+        if (text.length <= remaining) {
+            this.buffer += text;
+            return;
+        }
+        this.buffer += text.slice(0, remaining);
+        this.truncated = true;
+    }
+    finish() {
+        return this.truncated ? `${this.buffer}\n... truncated ...` : this.buffer;
+    }
+}
+class TimeoutError extends Error {
+}
+function timeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimeoutError()), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}

package/dist/esm/room-storage-toolkit.d.ts

@@ -0,0 +1,11 @@
+import { Meshagent, Toolkit } from "@meshagent/meshagent";
+export declare const defaultRoomStorageToolkitMaxLength = 20000;
+export declare class RoomStorageToolkit extends Toolkit {
+    constructor({ client, projectId, rooms, readOnly, maxLength, }: {
+        client: Meshagent;
+        projectId: string;
+        rooms: string[];
+        readOnly?: boolean;
+        maxLength?: number;
+    });
+}