@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.333

package/packages/typescript/src/media/fetch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Media fetching utilities with SSRF protection.
+ *
+ * Provides secure remote media fetching with:
+ * - SSRF protection via DNS pinning
+ * - Content-Disposition parsing
+ * - Size limits
+ * - MIME type detection
+ */
+import { type LookupFn, type SsrfPolicy } from "../network/index.js";
+export type FetchMediaResult = {
+    buffer: Buffer;
+    contentType?: string;
+    fileName?: string;
+};
+export type MediaFetchErrorCode = "max_bytes" | "http_error" | "fetch_failed";
+export declare class MediaFetchError extends Error {
+    readonly code: MediaFetchErrorCode;
+    constructor(code: MediaFetchErrorCode, message: string);
+}
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type FetchMediaOptions = {
+    url: string;
+    fetchImpl?: FetchLike;
+    filePathHint?: string;
+    maxBytes?: number;
+    maxRedirects?: number;
+    ssrfPolicy?: SsrfPolicy;
+    lookupFn?: LookupFn;
+};
+/**
+ * Fetch remote media with SSRF protection.
+ *
+ * @param options - Fetch options
+ * @returns Promise resolving to buffer, content type, and filename
+ * @throws MediaFetchError on fetch failures
+ */
+export declare function fetchRemoteMedia(options: FetchMediaOptions): Promise<FetchMediaResult>;
+//# sourceMappingURL=fetch.d.ts.map

package/packages/typescript/src/media/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/media/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEN,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,MAAM,qBAAqB,CAAC;AAG7B,MAAM,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,CAAC;AAE9E,qBAAa,eAAgB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;gBAEvB,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM;CAKtD;AAED,MAAM,MAAM,SAAS,GAAG,CACvB,KAAK,EAAE,WAAW,GAAG,GAAG,EACxB,IAAI,CAAC,EAAE,WAAW,KACd,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB,MAAM,MAAM,iBAAiB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACpB,CAAC;AA4DF;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACrC,OAAO,EAAE,iBAAiB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CA4G3B"}

package/packages/typescript/src/media/fetch.js

@@ -0,0 +1,205 @@
+/**
+ * Media fetching utilities with SSRF protection.
+ *
+ * Provides secure remote media fetching with:
+ * - SSRF protection via DNS pinning
+ * - Content-Disposition parsing
+ * - Size limits
+ * - MIME type detection
+ */
+import { fetchWithSsrfGuard, } from "../network/index.js";
+import { detectMime, extensionForMime } from "./mime.js";
+export class MediaFetchError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "MediaFetchError";
+    }
+}
+function stripQuotes(value) {
+    return value.replace(/^["']|["']$/g, "");
+}
+function getBasename(p) {
+    return p.split(/[\\/]/).pop() || "";
+}
+function getExtname(p) {
+    const base = getBasename(p);
+    const match = base.match(/\.[^.]+$/);
+    return match ? match[0] : "";
+}
+function parseContentDispositionFileName(header) {
+    if (!header) {
+        return undefined;
+    }
+    const starMatch = /filename\*\s*=\s*([^;]+)/i.exec(header);
+    if (starMatch?.[1]) {
+        const cleaned = stripQuotes(starMatch[1].trim());
+        const encoded = cleaned.split("''").slice(1).join("''") || cleaned;
+        try {
+            return getBasename(decodeURIComponent(encoded));
+        }
+        catch {
+            return getBasename(encoded);
+        }
+    }
+    const match = /filename\s*=\s*([^;]+)/i.exec(header);
+    if (match?.[1]) {
+        return getBasename(stripQuotes(match[1].trim()));
+    }
+    return undefined;
+}
+async function readErrorBodySnippet(res, maxChars = 200) {
+    try {
+        const text = await res.text();
+        if (!text) {
+            return undefined;
+        }
+        const collapsed = text.replace(/\s+/g, " ").trim();
+        if (!collapsed) {
+            return undefined;
+        }
+        if (collapsed.length <= maxChars) {
+            return collapsed;
+        }
+        return `${collapsed.slice(0, maxChars)}…`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fetch remote media with SSRF protection.
+ *
+ * @param options - Fetch options
+ * @returns Promise resolving to buffer, content type, and filename
+ * @throws MediaFetchError on fetch failures
+ */
+export async function fetchRemoteMedia(options) {
+    const { url, fetchImpl, filePathHint, maxBytes, maxRedirects, ssrfPolicy, lookupFn, } = options;
+    let res;
+    let finalUrl = url;
+    let release = null;
+    try {
+        const result = await fetchWithSsrfGuard({
+            url,
+            fetchImpl,
+            maxRedirects,
+            policy: ssrfPolicy,
+            lookupFn,
+        });
+        res = result.response;
+        finalUrl = result.finalUrl;
+        release = result.release;
+    }
+    catch (err) {
+        throw new MediaFetchError("fetch_failed", `Failed to fetch media from ${url}: ${String(err)}`);
+    }
+    try {
+        if (!res.ok) {
+            const statusText = res.statusText ? ` ${res.statusText}` : "";
+            const redirected = finalUrl !== url ? ` (redirected to ${finalUrl})` : "";
+            let detail = `HTTP ${res.status}${statusText}`;
+            if (!res.body) {
+                detail = `HTTP ${res.status}${statusText}; empty response body`;
+            }
+            else {
+                const snippet = await readErrorBodySnippet(res);
+                if (snippet) {
+                    detail += `; body: ${snippet}`;
+                }
+            }
+            throw new MediaFetchError("http_error", `Failed to fetch media from ${url}${redirected}: ${detail}`);
+        }
+        const contentLength = res.headers.get("content-length");
+        if (maxBytes && contentLength) {
+            const length = Number(contentLength);
+            if (Number.isFinite(length) && length > maxBytes) {
+                throw new MediaFetchError("max_bytes", `Failed to fetch media from ${url}: content length ${length} exceeds maxBytes ${maxBytes}`);
+            }
+        }
+        const buffer = maxBytes
+            ? await readResponseWithLimit(res, maxBytes)
+            : Buffer.from(await res.arrayBuffer());
+        let fileNameFromUrl;
+        try {
+            const parsed = new URL(finalUrl);
+            const base = getBasename(parsed.pathname);
+            fileNameFromUrl = base || undefined;
+        }
+        catch {
+            // ignore parse errors; leave undefined
+        }
+        const headerFileName = parseContentDispositionFileName(res.headers.get("content-disposition"));
+        let fileName = headerFileName ||
+            fileNameFromUrl ||
+            (filePathHint ? getBasename(filePathHint) : undefined);
+        const filePathForMime = headerFileName && getExtname(headerFileName)
+            ? headerFileName
+            : (filePathHint ?? finalUrl);
+        const contentType = await detectMime({
+            buffer,
+            headerMime: res.headers.get("content-type"),
+            filePath: filePathForMime,
+        });
+        if (fileName && !getExtname(fileName) && contentType) {
+            const ext = extensionForMime(contentType);
+            if (ext) {
+                fileName = `${fileName}${ext}`;
+            }
+        }
+        return {
+            buffer,
+            contentType: contentType ?? undefined,
+            fileName,
+        };
+    }
+    finally {
+        if (release) {
+            await release();
+        }
+    }
+}
+async function readResponseWithLimit(res, maxBytes) {
+    const body = res.body;
+    if (!body || typeof body.getReader !== "function") {
+        const fallback = Buffer.from(await res.arrayBuffer());
+        if (fallback.length > maxBytes) {
+            throw new MediaFetchError("max_bytes", `Failed to fetch media from ${res.url || "response"}: payload exceeds maxBytes ${maxBytes}`);
+        }
+        return fallback;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (value?.length) {
+                total += value.length;
+                if (total > maxBytes) {
+                    try {
+                        await reader.cancel();
+                    }
+                    catch {
+                        // ignore cancel errors
+                    }
+                    throw new MediaFetchError("max_bytes", `Failed to fetch media from ${res.url || "response"}: payload exceeds maxBytes ${maxBytes}`);
+                }
+                chunks.push(value);
+            }
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // ignore release errors
+        }
+    }
+    return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
+}

package/packages/typescript/src/media/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Media utilities for Eliza.
+ *
+ * Provides MIME type detection, media parsing, fetching, and format utilities.
+ */
+export { type FetchLike, type FetchMediaOptions, type FetchMediaResult, fetchRemoteMedia, MediaFetchError, type MediaFetchErrorCode, } from "./fetch.js";
+export { detectMime, extensionForMime, getFileExtension, imageMimeFromFormat, isAudioFileName, isGifMedia, isVoiceCompatibleAudio, type MediaKind, mediaKindFromMime, } from "./mime.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/typescript/src/media/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/media/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACN,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,eAAe,EACf,KAAK,mBAAmB,GACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACN,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,sBAAsB,EACtB,KAAK,SAAS,EACd,iBAAiB,GACjB,MAAM,WAAW,CAAC"}

package/packages/typescript/src/media/index.js

@@ -0,0 +1,7 @@
+/**
+ * Media utilities for Eliza.
+ *
+ * Provides MIME type detection, media parsing, fetching, and format utilities.
+ */
+export { fetchRemoteMedia, MediaFetchError, } from "./fetch.js";
+export { detectMime, extensionForMime, getFileExtension, imageMimeFromFormat, isAudioFileName, isGifMedia, isVoiceCompatibleAudio, mediaKindFromMime, } from "./mime.js";

package/packages/typescript/src/media/mime.d.ts

@@ -0,0 +1,51 @@
+/**
+ * MIME type detection and media utilities for Eliza.
+ *
+ * Provides robust MIME type detection from file buffers, headers, and extensions.
+ */
+/** Media kind categories */
+export type MediaKind = "image" | "audio" | "video" | "document" | "unknown";
+/**
+ * Get the file extension from a path or URL.
+ */
+export declare function getFileExtension(filePath?: string | null): string | undefined;
+/**
+ * Detect MIME type from buffer, headers, and/or file path.
+ * Prioritizes sniffed types over extension-based detection.
+ */
+export declare function detectMime(opts: {
+    buffer?: Buffer | Uint8Array;
+    headerMime?: string | null;
+    filePath?: string;
+}): Promise<string | undefined>;
+/**
+ * Get the file extension for a MIME type.
+ */
+export declare function extensionForMime(mime?: string | null): string | undefined;
+/**
+ * Check if a file appears to be an audio file by extension.
+ */
+export declare function isAudioFileName(fileName?: string | null): boolean;
+/**
+ * Check if media is a GIF.
+ */
+export declare function isGifMedia(opts: {
+    contentType?: string | null;
+    fileName?: string | null;
+}): boolean;
+/**
+ * Check if audio is voice-compatible (Opus/Ogg format).
+ */
+export declare function isVoiceCompatibleAudio(opts: {
+    contentType?: string | null;
+    fileName?: string | null;
+}): boolean;
+/**
+ * Get media kind from MIME type.
+ */
+export declare function mediaKindFromMime(mime?: string | null): MediaKind;
+/**
+ * Get image MIME type from format name.
+ */
+export declare function imageMimeFromFormat(format?: string | null): string | undefined;
+//# sourceMappingURL=mime.d.ts.map

package/packages/typescript/src/media/mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/media/mime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwBH,4BAA4B;AAC5B,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;AAqF7E;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAc7E;AAWD;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiB9B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGjE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,GAAG,OAAO,CAGV;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC5C,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,GAAG,OAAO,CAKV;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAgBjE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACpB,MAAM,GAAG,SAAS,CAmBpB"}

package/packages/typescript/src/media/mime.js

@@ -0,0 +1,225 @@
+/**
+ * MIME type detection and media utilities for Eliza.
+ *
+ * Provides robust MIME type detection from file buffers, headers, and extensions.
+ */
+let fileTypeModule;
+async function getFileTypeFromBuffer() {
+    if (fileTypeModule === undefined) {
+        try {
+            fileTypeModule = await import("file-type");
+        }
+        catch {
+            fileTypeModule = null;
+        }
+    }
+    return fileTypeModule?.fileTypeFromBuffer ?? null;
+}
+/** Map common MIME types to preferred file extensions */
+const EXT_BY_MIME = {
+    "image/heic": ".heic",
+    "image/heif": ".heif",
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "audio/ogg": ".ogg",
+    "audio/mpeg": ".mp3",
+    "audio/x-m4a": ".m4a",
+    "audio/mp4": ".m4a",
+    "video/mp4": ".mp4",
+    "video/quicktime": ".mov",
+    "application/pdf": ".pdf",
+    "application/json": ".json",
+    "application/zip": ".zip",
+    "application/gzip": ".gz",
+    "application/x-tar": ".tar",
+    "application/x-7z-compressed": ".7z",
+    "application/vnd.rar": ".rar",
+    "application/msword": ".doc",
+    "application/vnd.ms-excel": ".xls",
+    "application/vnd.ms-powerpoint": ".ppt",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+    "text/csv": ".csv",
+    "text/plain": ".txt",
+    "text/markdown": ".md",
+};
+/** Reverse map: extension to MIME */
+const MIME_BY_EXT = {
+    ...Object.fromEntries(Object.entries(EXT_BY_MIME).map(([mime, ext]) => [ext, mime])),
+    ".jpeg": "image/jpeg",
+};
+/** Audio file extensions */
+const AUDIO_FILE_EXTENSIONS = new Set([
+    ".aac",
+    ".flac",
+    ".m4a",
+    ".mp3",
+    ".oga",
+    ".ogg",
+    ".opus",
+    ".wav",
+]);
+/** Voice-compatible audio extensions (Opus/Ogg) */
+const VOICE_AUDIO_EXTENSIONS = new Set([".oga", ".ogg", ".opus"]);
+/**
+ * Normalize a MIME type from HTTP headers.
+ */
+function normalizeHeaderMime(mime) {
+    if (!mime)
+        return undefined;
+    const cleaned = mime.split(";")[0]?.trim().toLowerCase();
+    return cleaned || undefined;
+}
+/**
+ * Detect MIME type from a buffer using magic bytes.
+ */
+async function sniffMime(buffer) {
+    if (!buffer)
+        return undefined;
+    try {
+        const fileTypeFromBuffer = await getFileTypeFromBuffer();
+        if (!fileTypeFromBuffer)
+            return undefined;
+        const type = await fileTypeFromBuffer(buffer);
+        return type?.mime ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get the file extension from a path or URL.
+ */
+export function getFileExtension(filePath) {
+    if (!filePath)
+        return undefined;
+    try {
+        if (/^https?:\/\//i.test(filePath)) {
+            const url = new URL(filePath);
+            const ext = url.pathname.split(".").pop()?.toLowerCase();
+            return ext ? `.${ext}` : undefined;
+        }
+    }
+    catch {
+        // fall back to plain path parsing
+    }
+    const parts = filePath.split(".");
+    if (parts.length < 2)
+        return undefined;
+    return `.${parts.pop()?.toLowerCase()}`;
+}
+/**
+ * Check if a MIME type is generic/container type.
+ */
+function isGenericMime(mime) {
+    if (!mime)
+        return true;
+    const m = mime.toLowerCase();
+    return m === "application/octet-stream" || m === "application/zip";
+}
+/**
+ * Detect MIME type from buffer, headers, and/or file path.
+ * Prioritizes sniffed types over extension-based detection.
+ */
+export async function detectMime(opts) {
+    const ext = getFileExtension(opts.filePath);
+    const extMime = ext ? MIME_BY_EXT[ext] : undefined;
+    const headerMime = normalizeHeaderMime(opts.headerMime);
+    const sniffed = await sniffMime(opts.buffer);
+    // Prefer sniffed types, but don't let generic container types override
+    // a more specific extension mapping (e.g. XLSX vs ZIP).
+    if (sniffed && (!isGenericMime(sniffed) || !extMime)) {
+        return sniffed;
+    }
+    if (extMime)
+        return extMime;
+    if (headerMime && !isGenericMime(headerMime))
+        return headerMime;
+    if (sniffed)
+        return sniffed;
+    if (headerMime)
+        return headerMime;
+    return undefined;
+}
+/**
+ * Get the file extension for a MIME type.
+ */
+export function extensionForMime(mime) {
+    if (!mime)
+        return undefined;
+    return EXT_BY_MIME[mime.toLowerCase()];
+}
+/**
+ * Check if a file appears to be an audio file by extension.
+ */
+export function isAudioFileName(fileName) {
+    const ext = getFileExtension(fileName);
+    return ext ? AUDIO_FILE_EXTENSIONS.has(ext) : false;
+}
+/**
+ * Check if media is a GIF.
+ */
+export function isGifMedia(opts) {
+    if (opts.contentType?.toLowerCase() === "image/gif")
+        return true;
+    return getFileExtension(opts.fileName) === ".gif";
+}
+/**
+ * Check if audio is voice-compatible (Opus/Ogg format).
+ */
+export function isVoiceCompatibleAudio(opts) {
+    const mime = opts.contentType?.toLowerCase();
+    if (mime && (mime.includes("ogg") || mime.includes("opus")))
+        return true;
+    const ext = getFileExtension(opts.fileName);
+    return ext ? VOICE_AUDIO_EXTENSIONS.has(ext) : false;
+}
+/**
+ * Get media kind from MIME type.
+ */
+export function mediaKindFromMime(mime) {
+    if (!mime)
+        return "unknown";
+    const m = mime.toLowerCase();
+    if (m.startsWith("image/"))
+        return "image";
+    if (m.startsWith("audio/"))
+        return "audio";
+    if (m.startsWith("video/"))
+        return "video";
+    if (m.startsWith("application/pdf") ||
+        m.startsWith("application/msword") ||
+        m.startsWith("application/vnd.ms-") ||
+        m.startsWith("application/vnd.openxmlformats") ||
+        m.startsWith("text/")) {
+        return "document";
+    }
+    return "unknown";
+}
+/**
+ * Get image MIME type from format name.
+ */
+export function imageMimeFromFormat(format) {
+    if (!format)
+        return undefined;
+    switch (format.toLowerCase()) {
+        case "jpg":
+        case "jpeg":
+            return "image/jpeg";
+        case "heic":
+            return "image/heic";
+        case "heif":
+            return "image/heif";
+        case "png":
+            return "image/png";
+        case "webp":
+            return "image/webp";
+        case "gif":
+            return "image/gif";
+        default:
+            return undefined;
+    }
+}

package/packages/typescript/src/memory.d.ts

@@ -0,0 +1,40 @@
+import { type Content, type CustomMetadata, type DescriptionMetadata, type DocumentMetadata, type FragmentMetadata, type Memory, type MemoryMetadata, type MessageMemory, type MessageMetadata, type UUID } from "./types";
+export declare function createMessageMemory(params: {
+    id?: UUID;
+    entityId: UUID;
+    agentId?: UUID;
+    roomId: UUID;
+    content: Content & {
+        text: string;
+    };
+    embedding?: number[];
+}): MessageMemory;
+export declare function isDocumentMetadata(metadata: MemoryMetadata): metadata is DocumentMetadata;
+/**
+ * Type guard to check if a memory metadata is a FragmentMetadata
+ * @param metadata The metadata to check
+ * @returns True if the metadata is a FragmentMetadata
+ */
+export declare function isFragmentMetadata(metadata: MemoryMetadata): metadata is FragmentMetadata;
+export declare function isMessageMetadata(metadata: MemoryMetadata): metadata is MessageMetadata;
+/**
+ * Type guard to check if a memory metadata is a DescriptionMetadata
+ * @param metadata The metadata to check
+ * @returns True if the metadata is a DescriptionMetadata
+ */
+export declare function isDescriptionMetadata(metadata: MemoryMetadata): metadata is DescriptionMetadata;
+export declare function isCustomMetadata(metadata: MemoryMetadata): metadata is CustomMetadata;
+/**
+ * Memory type guard for document memories
+ */
+export declare function isDocumentMemory(memory: Memory): memory is Memory & {
+    metadata: DocumentMetadata;
+};
+/**
+ * Memory type guard for fragment memories
+ */
+export declare function isFragmentMemory(memory: Memory): memory is Memory & {
+    metadata: FragmentMetadata;
+};
+export declare function getMemoryText(memory: Memory, defaultValue?: string): string;
+//# sourceMappingURL=memory.d.ts.map

package/packages/typescript/src/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../../../typescript/src/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACX,KAAK,cAAc,EAEnB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,IAAI,EACT,MAAM,SAAS,CAAC;AAEjB,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC3C,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,QAAQ,EAAE,IAAI,CAAC;IACf,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,OAAO,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,GAAG,aAAa,CAWhB;AAED,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,cAAc,GACtB,QAAQ,IAAI,gBAAgB,CAE9B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,cAAc,GACtB,QAAQ,IAAI,gBAAgB,CAE9B;AAED,wBAAgB,iBAAiB,CAChC,QAAQ,EAAE,cAAc,GACtB,QAAQ,IAAI,eAAe,CAE7B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,cAAc,GACtB,QAAQ,IAAI,mBAAmB,CAEjC;AAED,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,cAAc,GACtB,QAAQ,IAAI,cAAc,CAO5B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,MAAM,GACZ,MAAM,IAAI,MAAM,GAAG;IAAE,QAAQ,EAAE,gBAAgB,CAAA;CAAE,CAKnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC/B,MAAM,EAAE,MAAM,GACZ,MAAM,IAAI,MAAM,GAAG;IAAE,QAAQ,EAAE,gBAAgB,CAAA;CAAE,CAKnD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,SAAK,GAAG,MAAM,CAEvE"}

package/packages/typescript/src/memory.js

@@ -0,0 +1,58 @@
+import { MemoryType, } from "./types";
+export function createMessageMemory(params) {
+    const now = Date.now();
+    return {
+        ...params,
+        createdAt: now,
+        metadata: {
+            type: MemoryType.MESSAGE,
+            timestamp: now,
+            scope: params.agentId ? "private" : "shared",
+        },
+    };
+}
+export function isDocumentMetadata(metadata) {
+    return metadata.type === MemoryType.DOCUMENT;
+}
+/**
+ * Type guard to check if a memory metadata is a FragmentMetadata
+ * @param metadata The metadata to check
+ * @returns True if the metadata is a FragmentMetadata
+ */
+export function isFragmentMetadata(metadata) {
+    return metadata.type === MemoryType.FRAGMENT;
+}
+export function isMessageMetadata(metadata) {
+    return metadata.type === MemoryType.MESSAGE;
+}
+/**
+ * Type guard to check if a memory metadata is a DescriptionMetadata
+ * @param metadata The metadata to check
+ * @returns True if the metadata is a DescriptionMetadata
+ */
+export function isDescriptionMetadata(metadata) {
+    return metadata.type === MemoryType.DESCRIPTION;
+}
+export function isCustomMetadata(metadata) {
+    return (metadata.type !== MemoryType.DOCUMENT &&
+        metadata.type !== MemoryType.FRAGMENT &&
+        metadata.type !== MemoryType.MESSAGE &&
+        metadata.type !== MemoryType.DESCRIPTION);
+}
+/**
+ * Memory type guard for document memories
+ */
+export function isDocumentMemory(memory) {
+    return (memory.metadata !== undefined &&
+        memory.metadata.type === MemoryType.DOCUMENT);
+}
+/**
+ * Memory type guard for fragment memories
+ */
+export function isFragmentMemory(memory) {
+    return (memory.metadata !== undefined &&
+        memory.metadata.type === MemoryType.FRAGMENT);
+}
+export function getMemoryText(memory, defaultValue = "") {
+    return memory.content.text ?? defaultValue;
+}