@elizaos/agent 2.0.0-alpha.98 → 2.0.0-beta.2

package/packages/agent/src/services/virtual-filesystem.d.ts

@@ -0,0 +1,88 @@
+export type VirtualFilesystemDiffStatus = "added" | "modified" | "deleted";
+export interface VirtualFilesystemOptions {
+    stateDir?: string;
+    projectId: string;
+    quotaBytes?: number;
+    maxFileBytes?: number;
+    now?: () => Date;
+}
+export interface VirtualFilesystemEntry {
+    path: string;
+    type: "file" | "directory";
+    size: number;
+    mtimeMs: number;
+}
+export interface VirtualFilesystemSnapshot {
+    id: string;
+    projectId: string;
+    createdAt: string;
+    root: string;
+    filesBytes: number;
+    fileCount: number;
+    note?: string;
+}
+export interface VirtualFilesystemRollback {
+    snapshotId: string;
+    projectId: string;
+    rolledBackAt: string;
+    previousSnapshotId?: string;
+}
+export interface VirtualFilesystemDiffEntry {
+    path: string;
+    status: VirtualFilesystemDiffStatus;
+    before?: VirtualFilesystemEntry;
+    after?: VirtualFilesystemEntry;
+}
+export declare class VirtualFilesystemError extends Error {
+    readonly code: "PATH_TRAVERSAL" | "INVALID_PATH" | "NOT_FOUND" | "NOT_FILE" | "NOT_DIRECTORY" | "SYMLINK_DENIED" | "QUOTA_EXCEEDED" | "SNAPSHOT_NOT_FOUND";
+    constructor(message: string, code: "PATH_TRAVERSAL" | "INVALID_PATH" | "NOT_FOUND" | "NOT_FILE" | "NOT_DIRECTORY" | "SYMLINK_DENIED" | "QUOTA_EXCEEDED" | "SNAPSHOT_NOT_FOUND");
+}
+export declare class VirtualFilesystemService {
+    readonly projectId: string;
+    readonly projectRoot: string;
+    readonly filesRoot: string;
+    readonly snapshotsRoot: string;
+    readonly quotaBytes: number;
+    readonly maxFileBytes: number;
+    private readonly now;
+    constructor(options: VirtualFilesystemOptions);
+    initialize(): Promise<void>;
+    writeFile(virtualPath: string, contents: string | Uint8Array): Promise<VirtualFilesystemEntry>;
+    readFile(virtualPath: string, encoding?: BufferEncoding): Promise<string>;
+    readFileBytes(virtualPath: string): Promise<Buffer>;
+    list(virtualPath?: string, options?: {
+        recursive?: boolean;
+    }): Promise<VirtualFilesystemEntry[]>;
+    delete(virtualPath: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    createSnapshot(note?: string): Promise<VirtualFilesystemSnapshot>;
+    getSnapshot(id: string): Promise<VirtualFilesystemSnapshot>;
+    diffSnapshots(beforeSnapshotId: string, afterSnapshotId: string): Promise<VirtualFilesystemDiffEntry[]>;
+    diffCurrent(snapshotId: string): Promise<VirtualFilesystemDiffEntry[]>;
+    rollback(snapshotId: string): Promise<VirtualFilesystemRollback>;
+    resolveVirtualPath(virtualPath: string): string;
+    /**
+     * Resolve a virtual path to its absolute on-disk location, applying the same
+     * traversal/symlink rules used by readFile/writeFile. The returned path is
+     * always inside the project's `filesRoot` and is the path Node/Bun will use
+     * if you `pathToFileURL()` it for a dynamic import. The path is not required
+     * to exist — callers that need existence should `readFile` it first.
+     */
+    resolveDiskPath(virtualPath: string): string;
+    private resolvePath;
+    private ensureSafeParentDirectory;
+    private rejectSymlinkIfExists;
+    private assertFile;
+    private assertDirectory;
+    private entryFor;
+    private listEntries;
+    private measureFiles;
+    private measureTree;
+    private fileSizeIfExists;
+    private readSnapshot;
+    private snapshotFilesRoot;
+    private indexTree;
+}
+export declare function createVirtualFilesystemService(options: VirtualFilesystemOptions): VirtualFilesystemService;
+//# sourceMappingURL=virtual-filesystem.d.ts.map

package/packages/agent/src/services/virtual-filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-filesystem.d.ts","sourceRoot":"","sources":["../../../../../src/services/virtual-filesystem.ts"],"names":[],"mappings":"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"}

package/packages/agent/src/services/virtual-filesystem.js

@@ -0,0 +1,410 @@
+import crypto from "node:crypto";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { writeJsonAtomic } from "../utils/atomic-json.js";
+const DEFAULT_QUOTA_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024;
+export class VirtualFilesystemError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "VirtualFilesystemError";
+    }
+}
+export class VirtualFilesystemService {
+    projectId;
+    projectRoot;
+    filesRoot;
+    snapshotsRoot;
+    quotaBytes;
+    maxFileBytes;
+    now;
+    constructor(options) {
+        this.projectId = sanitizeProjectId(options.projectId);
+        const stateDir = options.stateDir ?? resolveStateDir(process.env, os.homedir);
+        this.projectRoot = path.join(stateDir, "agent-vfs", "projects", this.projectId);
+        this.filesRoot = path.join(this.projectRoot, "files");
+        this.snapshotsRoot = path.join(this.projectRoot, "snapshots");
+        this.quotaBytes = options.quotaBytes ?? DEFAULT_QUOTA_BYTES;
+        this.maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+        this.now = options.now ?? (() => new Date());
+    }
+    async initialize() {
+        await fsp.mkdir(this.filesRoot, { recursive: true, mode: 0o700 });
+        await fsp.mkdir(this.snapshotsRoot, { recursive: true, mode: 0o700 });
+    }
+    async writeFile(virtualPath, contents) {
+        const data = typeof contents === "string"
+            ? Buffer.from(contents)
+            : Buffer.from(contents);
+        if (data.byteLength > this.maxFileBytes) {
+            throw new VirtualFilesystemError(`File exceeds max file size of ${this.maxFileBytes} bytes`, "QUOTA_EXCEEDED");
+        }
+        const target = this.resolvePath(virtualPath);
+        await this.ensureSafeParentDirectory(target);
+        await this.rejectSymlinkIfExists(target);
+        const existingSize = await this.fileSizeIfExists(target);
+        const current = await this.measureFiles();
+        const nextBytes = current.bytes - existingSize + data.byteLength;
+        if (nextBytes > this.quotaBytes) {
+            throw new VirtualFilesystemError(`Project quota exceeded: ${nextBytes}/${this.quotaBytes} bytes`, "QUOTA_EXCEEDED");
+        }
+        await fsp.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+        await fsp.writeFile(target, data, { mode: 0o600 });
+        return this.entryFor(target);
+    }
+    async readFile(virtualPath, encoding = "utf-8") {
+        const target = this.resolvePath(virtualPath);
+        await this.assertFile(target);
+        return fsp.readFile(target, encoding);
+    }
+    async readFileBytes(virtualPath) {
+        const target = this.resolvePath(virtualPath);
+        await this.assertFile(target);
+        return fsp.readFile(target);
+    }
+    async list(virtualPath = ".", options = {}) {
+        const target = this.resolvePath(virtualPath);
+        await this.assertDirectory(target);
+        const entries = await this.listEntries(target, Boolean(options.recursive));
+        return entries.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    async delete(virtualPath, options = {}) {
+        const target = this.resolvePath(virtualPath);
+        await this.ensureSafeParentDirectory(target);
+        await this.rejectSymlinkIfExists(target);
+        await fsp.rm(target, {
+            recursive: Boolean(options.recursive),
+            force: false,
+        });
+    }
+    async createSnapshot(note) {
+        await this.initialize();
+        const id = snapshotId(this.now());
+        const snapshotDir = path.join(this.snapshotsRoot, id);
+        const snapshotFilesRoot = path.join(snapshotDir, "files");
+        await fsp.mkdir(snapshotFilesRoot, { recursive: true, mode: 0o700 });
+        await fsp.cp(this.filesRoot, snapshotFilesRoot, {
+            recursive: true,
+            errorOnExist: false,
+            force: true,
+            dereference: false,
+        });
+        const stats = await this.measureTree(snapshotFilesRoot);
+        const snapshot = {
+            id,
+            projectId: this.projectId,
+            createdAt: this.now().toISOString(),
+            root: snapshotFilesRoot,
+            filesBytes: stats.bytes,
+            fileCount: stats.fileCount,
+            ...(note ? { note } : {}),
+        };
+        await writeJsonAtomic(path.join(snapshotDir, "snapshot.json"), snapshot);
+        return snapshot;
+    }
+    async getSnapshot(id) {
+        const snapshot = await this.readSnapshot(id);
+        if (!snapshot) {
+            throw new VirtualFilesystemError(`Snapshot not found: ${id}`, "SNAPSHOT_NOT_FOUND");
+        }
+        return snapshot;
+    }
+    async diffSnapshots(beforeSnapshotId, afterSnapshotId) {
+        const before = await this.snapshotFilesRoot(beforeSnapshotId);
+        const after = await this.snapshotFilesRoot(afterSnapshotId);
+        const beforeIndex = await this.indexTree(before);
+        const afterIndex = await this.indexTree(after);
+        return diffIndexes(beforeIndex, afterIndex);
+    }
+    async diffCurrent(snapshotId) {
+        const before = await this.snapshotFilesRoot(snapshotId);
+        const beforeIndex = await this.indexTree(before);
+        const afterIndex = await this.indexTree(this.filesRoot);
+        return diffIndexes(beforeIndex, afterIndex);
+    }
+    async rollback(snapshotId) {
+        const snapshotRoot = await this.snapshotFilesRoot(snapshotId);
+        const previous = await this.createSnapshot(`pre-rollback:${snapshotId}`);
+        await fsp.rm(this.filesRoot, { recursive: true, force: true });
+        await fsp.mkdir(this.filesRoot, { recursive: true, mode: 0o700 });
+        await fsp.cp(snapshotRoot, this.filesRoot, {
+            recursive: true,
+            errorOnExist: false,
+            force: true,
+            dereference: false,
+        });
+        const rollback = {
+            snapshotId,
+            projectId: this.projectId,
+            rolledBackAt: this.now().toISOString(),
+            previousSnapshotId: previous.id,
+        };
+        await writeJsonAtomic(path.join(this.projectRoot, "last-rollback.json"), rollback);
+        return rollback;
+    }
+    resolveVirtualPath(virtualPath) {
+        return toVirtualPath(this.resolvePath(virtualPath), this.filesRoot);
+    }
+    /**
+     * Resolve a virtual path to its absolute on-disk location, applying the same
+     * traversal/symlink rules used by readFile/writeFile. The returned path is
+     * always inside the project's `filesRoot` and is the path Node/Bun will use
+     * if you `pathToFileURL()` it for a dynamic import. The path is not required
+     * to exist — callers that need existence should `readFile` it first.
+     */
+    resolveDiskPath(virtualPath) {
+        return this.resolvePath(virtualPath);
+    }
+    resolvePath(virtualPath) {
+        const normalized = normalizeVirtualPath(virtualPath);
+        const resolved = path.resolve(this.filesRoot, normalized);
+        if (!isWithin(this.filesRoot, resolved)) {
+            throw new VirtualFilesystemError("Path escapes virtual filesystem root", "PATH_TRAVERSAL");
+        }
+        return resolved;
+    }
+    async ensureSafeParentDirectory(target) {
+        const relativeParent = path.relative(this.filesRoot, path.dirname(target));
+        if (!relativeParent)
+            return;
+        let current = this.filesRoot;
+        for (const segment of relativeParent.split(path.sep)) {
+            current = path.join(current, segment);
+            const stat = await lstatOrNull(current);
+            if (!stat)
+                continue;
+            if (stat.isSymbolicLink()) {
+                throw new VirtualFilesystemError(`Symlink path component denied: ${toVirtualPath(current, this.filesRoot)}`, "SYMLINK_DENIED");
+            }
+            if (!stat.isDirectory()) {
+                throw new VirtualFilesystemError("Parent path is not a directory", "NOT_DIRECTORY");
+            }
+        }
+    }
+    async rejectSymlinkIfExists(target) {
+        const stat = await lstatOrNull(target);
+        if (stat?.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+    }
+    async assertFile(target) {
+        await this.ensureSafeParentDirectory(target);
+        const stat = await lstatOrNull(target);
+        if (!stat) {
+            throw new VirtualFilesystemError("File not found", "NOT_FOUND");
+        }
+        if (stat.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+        if (!stat.isFile()) {
+            throw new VirtualFilesystemError("Path is not a file", "NOT_FILE");
+        }
+    }
+    async assertDirectory(target) {
+        await this.ensureSafeParentDirectory(target);
+        const stat = await lstatOrNull(target);
+        if (!stat) {
+            throw new VirtualFilesystemError("Directory not found", "NOT_FOUND");
+        }
+        if (stat.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+        if (!stat.isDirectory()) {
+            throw new VirtualFilesystemError("Path is not a directory", "NOT_DIRECTORY");
+        }
+    }
+    async entryFor(realPath) {
+        const stat = await fsp.lstat(realPath);
+        return {
+            path: toVirtualPath(realPath, this.filesRoot),
+            type: stat.isDirectory() ? "directory" : "file",
+            size: stat.isFile() ? stat.size : 0,
+            mtimeMs: stat.mtimeMs,
+        };
+    }
+    async listEntries(realDir, recursive) {
+        const dirents = await fsp.readdir(realDir, { withFileTypes: true });
+        const entries = [];
+        for (const dirent of dirents) {
+            const realPath = path.join(realDir, dirent.name);
+            if (dirent.isSymbolicLink()) {
+                throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+            }
+            const entry = await this.entryFor(realPath);
+            entries.push(entry);
+            if (recursive && dirent.isDirectory()) {
+                entries.push(...(await this.listEntries(realPath, true)));
+            }
+        }
+        return entries;
+    }
+    async measureFiles() {
+        return this.measureTree(this.filesRoot);
+    }
+    async measureTree(root) {
+        const stat = await lstatOrNull(root);
+        if (!stat)
+            return { bytes: 0, fileCount: 0 };
+        if (stat.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+        if (stat.isFile()) {
+            return { bytes: stat.size, fileCount: 1 };
+        }
+        if (!stat.isDirectory()) {
+            return { bytes: 0, fileCount: 0 };
+        }
+        let bytes = 0;
+        let fileCount = 0;
+        for (const entry of await fsp.readdir(root, { withFileTypes: true })) {
+            const child = path.join(root, entry.name);
+            const stats = await this.measureTree(child);
+            bytes += stats.bytes;
+            fileCount += stats.fileCount;
+        }
+        return { bytes, fileCount };
+    }
+    async fileSizeIfExists(realPath) {
+        const stat = await lstatOrNull(realPath);
+        if (!stat)
+            return 0;
+        if (stat.isSymbolicLink()) {
+            throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+        }
+        if (!stat.isFile()) {
+            throw new VirtualFilesystemError("Path is not a file", "NOT_FILE");
+        }
+        return stat.size;
+    }
+    async readSnapshot(id) {
+        const normalizedId = normalizeSnapshotId(id);
+        const metadataPath = path.join(this.snapshotsRoot, normalizedId, "snapshot.json");
+        const raw = await fsp.readFile(metadataPath, "utf-8").catch(() => null);
+        return raw ? JSON.parse(raw) : null;
+    }
+    async snapshotFilesRoot(id) {
+        const snapshot = await this.getSnapshot(id);
+        const root = path.join(this.snapshotsRoot, normalizeSnapshotId(snapshot.id), "files");
+        if (!isWithin(this.snapshotsRoot, root)) {
+            throw new VirtualFilesystemError("Snapshot path escapes snapshot root", "PATH_TRAVERSAL");
+        }
+        return root;
+    }
+    async indexTree(root) {
+        const index = new Map();
+        const walk = async (dir) => {
+            for (const dirent of await fsp.readdir(dir, { withFileTypes: true })) {
+                const realPath = path.join(dir, dirent.name);
+                if (dirent.isSymbolicLink()) {
+                    throw new VirtualFilesystemError("Symlinks are not allowed in the VFS", "SYMLINK_DENIED");
+                }
+                const stat = await fsp.lstat(realPath);
+                const entry = {
+                    path: toVirtualPath(realPath, root),
+                    type: stat.isDirectory() ? "directory" : "file",
+                    size: stat.isFile() ? stat.size : 0,
+                    mtimeMs: stat.mtimeMs,
+                    ...(stat.isFile() ? { hash: await sha256(realPath) } : {}),
+                };
+                index.set(entry.path, entry);
+                if (dirent.isDirectory()) {
+                    await walk(realPath);
+                }
+            }
+        };
+        await walk(root);
+        return index;
+    }
+}
+export function createVirtualFilesystemService(options) {
+    return new VirtualFilesystemService(options);
+}
+function sanitizeProjectId(projectId) {
+    const sanitized = projectId.trim().replace(/[^a-zA-Z0-9._-]/g, "-");
+    if (!sanitized || sanitized === "." || sanitized === "..") {
+        throw new VirtualFilesystemError("Invalid VFS project id", "INVALID_PATH");
+    }
+    return sanitized.slice(0, 120);
+}
+function normalizeVirtualPath(input) {
+    if (typeof input !== "string" || input.includes("\0")) {
+        throw new VirtualFilesystemError("Invalid virtual path", "INVALID_PATH");
+    }
+    const value = input.trim().replace(/\\/g, "/");
+    if (!value || value === "." || value === "/") {
+        return ".";
+    }
+    const segments = value.split("/").filter(Boolean);
+    if (segments.some((segment) => segment === "." || segment === "..")) {
+        throw new VirtualFilesystemError("Path traversal segments are not allowed", "PATH_TRAVERSAL");
+    }
+    return segments.join(path.sep);
+}
+function normalizeSnapshotId(id) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(id)) {
+        throw new VirtualFilesystemError("Invalid snapshot id", "INVALID_PATH");
+    }
+    return id;
+}
+function isWithin(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return (relative === "" ||
+        (!relative.startsWith("..") && !path.isAbsolute(relative)));
+}
+function toVirtualPath(realPath, root) {
+    const relative = path.relative(root, realPath).replace(/\\/g, "/");
+    return relative ? `/${relative}` : "/";
+}
+async function lstatOrNull(realPath) {
+    try {
+        return await fsp.lstat(realPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function snapshotId(now) {
+    const stamp = now.toISOString().replace(/[:.]/g, "-");
+    return `${stamp}-${crypto.randomBytes(4).toString("hex")}`;
+}
+async function sha256(realPath) {
+    const hash = crypto.createHash("sha256");
+    hash.update(await fsp.readFile(realPath));
+    return hash.digest("hex");
+}
+function diffIndexes(before, after) {
+    const paths = new Set([...before.keys(), ...after.keys()]);
+    const diff = [];
+    for (const entryPath of [...paths].sort()) {
+        const beforeEntry = before.get(entryPath);
+        const afterEntry = after.get(entryPath);
+        if (!beforeEntry && afterEntry) {
+            diff.push({ path: entryPath, status: "added", after: afterEntry });
+            continue;
+        }
+        if (beforeEntry && !afterEntry) {
+            diff.push({ path: entryPath, status: "deleted", before: beforeEntry });
+            continue;
+        }
+        if (!beforeEntry || !afterEntry)
+            continue;
+        const same = beforeEntry.type === afterEntry.type &&
+            beforeEntry.size === afterEntry.size &&
+            beforeEntry.hash === afterEntry.hash;
+        if (!same) {
+            diff.push({
+                path: entryPath,
+                status: "modified",
+                before: beforeEntry,
+                after: afterEntry,
+            });
+        }
+    }
+    return diff;
+}

package/packages/agent/src/shared/conversation-format.d.ts

@@ -0,0 +1,11 @@
+import type { IAgentRuntime, Memory, Room } from "@elizaos/core";
+export declare function formatSpeakerLabel(runtime: IAgentRuntime, memory: Memory): string;
+/**
+ * Format a Room into a "[source] name" tag for display in provider output.
+ */
+export declare function roomSourceTag(room: Room | null): string;
+/**
+ * Format a createdAt timestamp as a human-readable relative string.
+ */
+export declare function formatRelativeTimestamp(createdAt?: number): string;
+//# sourceMappingURL=conversation-format.d.ts.map

package/packages/agent/src/shared/conversation-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-format.d.ts","sourceRoot":"","sources":["../../../../../src/shared/conversation-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AA2BjE,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,MAAM,GACb,MAAM,CA2BR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAKvD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAYlE"}

package/packages/agent/src/shared/conversation-format.js

@@ -0,0 +1,69 @@
+import { asNonEmptyString, asRecord } from "@elizaos/shared";
+const readString = asNonEmptyString;
+function normalizeName(value) {
+    return value.trim().toLowerCase();
+}
+function formatExternalSpeakerLabel(displayName, userName, source) {
+    if (displayName &&
+        userName &&
+        normalizeName(displayName) !== normalizeName(userName)) {
+        if (source === "discord") {
+            return `${displayName} (discord username: ${userName})`;
+        }
+        return `${displayName} (username: ${userName})`;
+    }
+    return displayName ?? userName ?? "user";
+}
+export function formatSpeakerLabel(runtime, memory) {
+    if (memory.entityId === runtime.agentId) {
+        return runtime.character?.name ?? "agent";
+    }
+    const metadata = asRecord(memory.metadata);
+    const content = asRecord(memory.content);
+    const defaultMetadata = asRecord(metadata?.default);
+    const source = readString(content?.source);
+    const sourceMetadata = source ? asRecord(metadata?.[source]) : null;
+    const displayName = readString(metadata?.entityName) ??
+        readString(metadata?.displayName) ??
+        readString(sourceMetadata?.displayName) ??
+        readString(sourceMetadata?.name) ??
+        readString(defaultMetadata?.name) ??
+        readString(metadata?.name);
+    const userName = readString(metadata?.entityUserName) ??
+        readString(sourceMetadata?.userName) ??
+        readString(sourceMetadata?.username) ??
+        readString(defaultMetadata?.username) ??
+        readString(metadata?.userName) ??
+        readString(metadata?.username);
+    return formatExternalSpeakerLabel(displayName, userName, source);
+}
+/**
+ * Format a Room into a "[source] name" tag for display in provider output.
+ */
+export function roomSourceTag(room) {
+    if (!room)
+        return "[unknown]";
+    const source = room.source || (room.type ?? "chat");
+    const name = room.name || room.id?.slice(0, 8);
+    return `[${source}] ${name}`;
+}
+/**
+ * Format a createdAt timestamp as a human-readable relative string.
+ */
+export function formatRelativeTimestamp(createdAt) {
+    if (!createdAt)
+        return "";
+    const date = new Date(createdAt);
+    const now = Date.now();
+    const diffMs = now - date.getTime();
+    if (diffMs < 60_000)
+        return "just now";
+    const minutes = Math.floor(diffMs / 60_000);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}

package/packages/agent/src/shared/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./conversation-format.ts";
+export * from "./ui-catalog-prompt.ts";
+export * from "./workspace-resolution.ts";
+//# sourceMappingURL=index.d.ts.map

package/packages/agent/src/shared/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/shared/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC"}

package/packages/agent/src/shared/index.js

@@ -0,0 +1,3 @@
+export * from "./conversation-format.js";
+export * from "./ui-catalog-prompt.js";
+export * from "./workspace-resolution.js";