@ixo/oracle-runtime 0.0.1

package/dist/manifest/tier1-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier1-renderer.d.ts","sourceRoot":"","sources":["../../src/manifest/tier1-renderer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE9E,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA2CD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAmC1D"}

package/dist/manifest/tier1-renderer.js

@@ -0,0 +1,68 @@
+import { encodingForModel } from 'js-tiktoken';
+const DEFAULT_BUDGET = 5000;
+const HEADER = '## Available Capabilities\n\n';
+const FOOTER = '\n\nFor more capabilities, call `list_capabilities()` to see what else is available,\nthen `load_capability(name)` to make its tools available.';
+let cachedEncoder = null;
+function tiktokenEstimate(text) {
+    cachedEncoder ??= encodingForModel('gpt-4o');
+    return cachedEncoder.encode(text).length;
+}
+function formatExample(ex) {
+    const argSummary = ex.args && Object.keys(ex.args).length > 0
+        ? `${ex.tool}(${JSON.stringify(ex.args)})`
+        : `${ex.tool}()`;
+    return `"${ex.user}" → ${argSummary}`;
+}
+function formatEntry(entry) {
+    const { pluginName, manifest } = entry;
+    const lines = [`- **${pluginName}** — ${manifest.summary}`];
+    const whenToUse = manifest.whenToUse.slice(0, 2);
+    if (whenToUse.length > 0) {
+        lines.push(`  - When to use: ${whenToUse.join('; ')}`);
+    }
+    if (manifest.whenNotToUse && manifest.whenNotToUse.length > 0) {
+        lines.push(`  - Avoid for: ${manifest.whenNotToUse[0]}`);
+    }
+    const firstExample = manifest.examples?.[0];
+    if (firstExample) {
+        lines.push(`  - Example: ${formatExample(firstExample)}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Compose the Tier-1 capability block from a list of plugin manifests.
+ *
+ * Only `visibility: 'always'` manifests are included, sorted alphabetically
+ * for prompt-caching determinism. Over-budget calls produce a warning naming
+ * the largest manifests so operators can mark them `'on-demand'` — degrading
+ * verbosity is an operator decision, not a runtime guess.
+ */
+export function renderTier1(input) {
+    const budget = input.tokenBudget ?? DEFAULT_BUDGET;
+    const estimate = input.estimateTokens ?? tiktokenEstimate;
+    const entries = input.manifests
+        .filter(({ manifest }) => manifest.visibility === 'always')
+        .slice()
+        .sort((a, b) => a.pluginName.localeCompare(b.pluginName));
+    if (entries.length === 0) {
+        return { block: '', tokens: 0, warnings: [] };
+    }
+    const renderedLines = entries.map(formatEntry);
+    const tokens = renderedLines.reduce((sum, line) => sum + estimate(line), 0);
+    const warnings = [];
+    if (tokens > budget) {
+        const largest = entries
+            .map((entry) => ({
+            name: entry.pluginName,
+            t: estimate(formatEntry(entry)),
+        }))
+            .sort((a, b) => b.t - a.t)
+            .slice(0, 3)
+            .map((e) => `${e.name} (~${e.t} tok)`)
+            .join(', ');
+        warnings.push(`Tier-1 prompt is ${tokens} tokens (budget ${budget}). ` +
+            `Consider marking these on-demand: ${largest}.`);
+    }
+    const block = `${HEADER}${renderedLines.join('\n\n')}${FOOTER}`;
+    return { block, tokens, warnings };
+}

package/dist/manifest/validator.d.ts

@@ -0,0 +1,34 @@
+import type { PluginManifest } from '../plugin-api/types.js';
+/** Result of validating a single plugin manifest. */
+export interface ManifestValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate a plugin manifest at boot time.
+ *
+ * Hard rules push to `errors` and set `valid: false`.
+ * Soft rules push to `warnings` only — `valid` stays `true`.
+ *
+ * Cross-tool reference checking lives in `validateExamplesAgainstTools`
+ * because the registered tool list is only known once the plugin's
+ * `getTools()` has run.
+ */
+export declare function validateManifest(manifest: unknown, pluginName: string): ManifestValidationResult;
+/**
+ * Cross-check `examples[].tool` references against the set of tool names
+ * actually registered by this plugin. Run after the plugin's `getTools()`
+ * has been invoked.
+ *
+ * **Lenient for MCP-sourced plugins**: when `registeredToolNames` is empty,
+ * the plugin's tools come from `getRequestTools` (fetched per-request from
+ * an upstream MCP server like sandbox or memory) — boot-time validation
+ * can't see them. We skip the cross-check in that case rather than
+ * false-flag every example. Plugins with boot-time tools still get the
+ * full check, so stale `examples[].tool` references are caught.
+ */
+export declare function validateExamplesAgainstTools(manifest: PluginManifest, registeredToolNames: string[], pluginName: string): {
+    errors: string[];
+};
+//# sourceMappingURL=validator.d.ts.map

package/dist/manifest/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/manifest/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,qDAAqD;AACrD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,GACjB,wBAAwB,CAoF1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,cAAc,EACxB,mBAAmB,EAAE,MAAM,EAAE,EAC7B,UAAU,EAAE,MAAM,GACjB;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAkBtB"}

package/dist/manifest/validator.js

@@ -0,0 +1,111 @@
+import { pluginManifestSchema } from './schema.js';
+/** Soft-cap thresholds — violations only emit warnings. */
+const SOFT_LIMITS = {
+    summaryMaxChars: 120,
+    whenToUseMaxItems: 8,
+    whenToUseItemMaxChars: 100,
+    whenNotToUseMaxItems: 4,
+    whenNotToUseItemMaxChars: 80,
+    examplesMaxItems: 3,
+};
+/** Format a per-plugin, per-field message prefix. */
+function tag(pluginName, fieldPath) {
+    return `[${pluginName}] ${fieldPath}:`;
+}
+/**
+ * Validate a plugin manifest at boot time.
+ *
+ * Hard rules push to `errors` and set `valid: false`.
+ * Soft rules push to `warnings` only — `valid` stays `true`.
+ *
+ * Cross-tool reference checking lives in `validateExamplesAgainstTools`
+ * because the registered tool list is only known once the plugin's
+ * `getTools()` has run.
+ */
+export function validateManifest(manifest, pluginName) {
+    const errors = [];
+    const warnings = [];
+    const parsed = pluginManifestSchema.safeParse(manifest);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+            errors.push(`${tag(pluginName, path)} ${issue.message}`);
+        }
+        return { valid: false, errors, warnings };
+    }
+    const m = parsed.data;
+    // Hard rule: summary must be non-empty.
+    if (m.summary.trim().length === 0) {
+        errors.push(`${tag(pluginName, 'summary')} must be non-empty.`);
+    }
+    // Hard rule: whenToUse must have ≥1 entry unless plugin is silent.
+    const visibility = m.visibility ?? 'on-demand';
+    if (visibility !== 'silent' && m.whenToUse.length < 1) {
+        errors.push(`${tag(pluginName, 'whenToUse')} must contain at least one entry when visibility is '${visibility}'.`);
+    }
+    // Hard rule: tags, if present, must all be lowercase.
+    if (m.tags) {
+        m.tags.forEach((t, i) => {
+            if (t !== t.toLowerCase()) {
+                errors.push(`${tag(pluginName, `tags[${i}]`)} must be lowercase (got "${t}").`);
+            }
+        });
+    }
+    // Soft rule: summary length cap.
+    if (m.summary.length > SOFT_LIMITS.summaryMaxChars) {
+        warnings.push(`${tag(pluginName, 'summary')} is ${m.summary.length} chars (recommended ≤ ${SOFT_LIMITS.summaryMaxChars}).`);
+    }
+    // Soft rule: whenToUse caps.
+    if (m.whenToUse.length > SOFT_LIMITS.whenToUseMaxItems) {
+        warnings.push(`${tag(pluginName, 'whenToUse')} has ${m.whenToUse.length} items (recommended ≤ ${SOFT_LIMITS.whenToUseMaxItems}).`);
+    }
+    m.whenToUse.forEach((line, i) => {
+        if (line.length > SOFT_LIMITS.whenToUseItemMaxChars) {
+            warnings.push(`${tag(pluginName, `whenToUse[${i}]`)} is ${line.length} chars (recommended ≤ ${SOFT_LIMITS.whenToUseItemMaxChars}).`);
+        }
+    });
+    // Soft rule: whenNotToUse caps.
+    if (m.whenNotToUse) {
+        if (m.whenNotToUse.length > SOFT_LIMITS.whenNotToUseMaxItems) {
+            warnings.push(`${tag(pluginName, 'whenNotToUse')} has ${m.whenNotToUse.length} items (recommended ≤ ${SOFT_LIMITS.whenNotToUseMaxItems}).`);
+        }
+        m.whenNotToUse.forEach((line, i) => {
+            if (line.length > SOFT_LIMITS.whenNotToUseItemMaxChars) {
+                warnings.push(`${tag(pluginName, `whenNotToUse[${i}]`)} is ${line.length} chars (recommended ≤ ${SOFT_LIMITS.whenNotToUseItemMaxChars}).`);
+            }
+        });
+    }
+    // Soft rule: examples cap.
+    if (m.examples && m.examples.length > SOFT_LIMITS.examplesMaxItems) {
+        warnings.push(`${tag(pluginName, 'examples')} has ${m.examples.length} items (recommended ≤ ${SOFT_LIMITS.examplesMaxItems}).`);
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/**
+ * Cross-check `examples[].tool` references against the set of tool names
+ * actually registered by this plugin. Run after the plugin's `getTools()`
+ * has been invoked.
+ *
+ * **Lenient for MCP-sourced plugins**: when `registeredToolNames` is empty,
+ * the plugin's tools come from `getRequestTools` (fetched per-request from
+ * an upstream MCP server like sandbox or memory) — boot-time validation
+ * can't see them. We skip the cross-check in that case rather than
+ * false-flag every example. Plugins with boot-time tools still get the
+ * full check, so stale `examples[].tool` references are caught.
+ */
+export function validateExamplesAgainstTools(manifest, registeredToolNames, pluginName) {
+    const errors = [];
+    if (!manifest.examples)
+        return { errors };
+    // No boot-time tools registered for this plugin — tools come from
+    // request-time MCP fetch. We can't validate references at boot.
+    if (registeredToolNames.length === 0)
+        return { errors };
+    const known = new Set(registeredToolNames);
+    manifest.examples.forEach((ex, i) => {
+        if (!known.has(ex.tool)) {
+            errors.push(`${tag(pluginName, `examples[${i}].tool`)} references unknown tool "${ex.tool}".`);
+        }
+    });
+    return { errors };
+}

package/dist/matrix/checkpointer/matrix-upload-utils.d.ts

@@ -0,0 +1,66 @@
+import { type MatrixEvent } from '@ixo/matrix';
+import { type File } from 'node:buffer';
+export type MatrixMediaEvent = MatrixEvent<{
+    msgtype: 'm.file';
+    body: string;
+    filename: string;
+    cid: string;
+    sender: string;
+    info: {
+        mimetype: string;
+        size: number;
+    };
+    file: {
+        url: string;
+        mimetype: string;
+        size: number;
+    };
+}>;
+/**
+ * Uploads media to a Matrix room
+ * @param roomId The room ID to upload the media to
+ * @param file The file to upload
+ * @returns Object containing the event ID and CID of the uploaded media
+ */
+export declare function uploadMediaToRoom(roomId: string, file: File, // This is the sqlite file it's .db file
+storageKey: string): Promise<{
+    eventId: string;
+    storageKey: string;
+    event: MatrixMediaEvent;
+}>;
+export interface GetMediaFromRoomByStorageKeyResult {
+    mediaBuffer: Buffer;
+    contentInfo: {
+        mimetype: string;
+        filename: string;
+        storageKey: string;
+    };
+}
+/**
+ * Gets media from a Matrix room by CID
+ * @param roomId The room ID
+ * @param storageKey The storage key of the media
+ * @returns Object containing the media buffer and content info
+ */
+export declare function getMediaFromRoomByStorageKey(roomId: string, storageKey: string): Promise<GetMediaFromRoomByStorageKeyResult | null>;
+/**
+ * Retrieves media from a Matrix room
+ * @param roomId The room ID where the media is located
+ * @param eventId The event ID of the media
+ * @returns Object containing the media buffer and content info
+ */
+export declare function getMediaFromRoom(roomId?: string, eventId?: string, cachedEvent?: MatrixMediaEvent): Promise<{
+    mediaBuffer: Buffer;
+    contentInfo: {
+        mimetype: string;
+        filename: string;
+    };
+}>;
+/**
+ * Deletes media from a Matrix room by storage key
+ * @param roomId The room ID where the media is located
+ * @param storageKey The storage key of the media to delete
+ * @returns True if deletion was successful, false if not found
+ */
+export declare function deleteMediaFromRoom(roomId: string, storageKey: string): Promise<boolean>;
+//# sourceMappingURL=matrix-upload-utils.d.ts.map

package/dist/matrix/checkpointer/matrix-upload-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix-upload-utils.d.ts","sourceRoot":"","sources":["../../../src/matrix/checkpointer/matrix-upload-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAkBxC,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC;IACzC,OAAO,EAAE,QAAQ,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,IAAI,EAAE;QACJ,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH,CAAC,CAAC;AAEH;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,EAAE,wCAAwC;AACpD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAAC,CA0H3E;AAED,MAAM,WAAW,kCAAkC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,kCAAkC,GAAG,IAAI,CAAC,CA6DpD;AAED;;;;;GAKG;AAEH,wBAAsB,gBAAgB,CACpC,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,gBAAgB,GAC7B,OAAO,CAAC;IACT,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,CAAC,CA0CD;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAqElB"}

package/dist/matrix/checkpointer/matrix-upload-utils.js

@@ -0,0 +1,228 @@
+import { MatrixManager } from '@ixo/matrix';
+import { Logger } from '@nestjs/common';
+const logger = new Logger('MatrixUploadUtils');
+const getClient = () => {
+    const client = MatrixManager.getInstance().getClient();
+    if (!client) {
+        throw new Error('Matrix client not found');
+    }
+    return client;
+};
+const EVENTS = {
+    MEDIA_STATE: 'm.ixo.media_state',
+    MEDIA_UPLOAD: 'm.ixo.media_upload',
+    MEDIA: 'm.ixo.media',
+};
+/**
+ * Uploads media to a Matrix room
+ * @param roomId The room ID to upload the media to
+ * @param file The file to upload
+ * @returns Object containing the event ID and CID of the uploaded media
+ */
+export async function uploadMediaToRoom(roomId, file, // This is the sqlite file it's .db file
+storageKey) {
+    const client = getClient();
+    logger.debug(`Uploading media to room ${roomId} with storageKey ${storageKey}, file size: ${file.size} bytes`);
+    // Look up the old media event ID (if any) so we can redact it AFTER the new upload succeeds.
+    // This avoids data loss if the upload fails — the old checkpoint stays intact until replaced.
+    let oldEventId;
+    try {
+        const existingMedia = await client.mxClient.getRoomStateEvent(roomId, EVENTS.MEDIA_STATE, storageKey);
+        if (existingMedia && existingMedia.eventId) {
+            oldEventId = existingMedia.eventId;
+            logger.debug(`Found existing media event ${oldEventId} for storageKey ${storageKey}, will redact after successful upload`);
+        }
+    }
+    catch (_error) {
+        // State event doesn't exist, proceed with upload
+        logger.debug(`No existing media state event found for storageKey ${storageKey}, proceeding with new upload`);
+    }
+    // Check if room is encrypted and upload media
+    const isRoomEncrypted = await client.mxClient.crypto.isRoomEncrypted(roomId);
+    logger.debug(`Room ${roomId} is ${isRoomEncrypted ? 'encrypted' : 'unencrypted'}, proceeding with ${isRoomEncrypted ? 'encrypted' : 'unencrypted'} upload`);
+    let event;
+    let eventId;
+    if (isRoomEncrypted) {
+        // For encrypted rooms
+        logger.debug(`Encrypting media for storageKey ${storageKey}`);
+        const encrypted = await client.mxClient.crypto.encryptMedia(Buffer.from(await file.arrayBuffer()));
+        logger.debug(`Uploading encrypted content for storageKey ${storageKey}`);
+        const mxc = await client.mxClient.uploadContent(encrypted.buffer);
+        eventId = await client.mxClient.sendEvent(roomId, EVENTS.MEDIA_UPLOAD, {
+            msgtype: 'm.file',
+            body: storageKey,
+            filename: storageKey,
+            cid: storageKey,
+            sender: client.mxClient.getUserId(),
+            info: {
+                mimetype: 'application/x-sqlite3',
+                size: file.size,
+            },
+            file: {
+                url: mxc,
+                ...encrypted.file,
+            },
+        });
+        logger.debug(`Media event created with eventId ${eventId} for storageKey ${storageKey}`);
+        event = await client.mxClient.getEvent(roomId, eventId);
+    }
+    else {
+        // For unencrypted rooms
+        logger.debug(`Uploading unencrypted content for storageKey ${storageKey}`);
+        const mxc = await client.mxClient.uploadContent(Buffer.from(await file.arrayBuffer()));
+        eventId = await client.mxClient.sendEvent(roomId, EVENTS.MEDIA_UPLOAD, {
+            msgtype: 'm.file',
+            body: storageKey,
+            filename: storageKey,
+            cid: storageKey,
+            sender: client.mxClient.getUserId(),
+            info: {
+                mimetype: 'application/x-sqlite3',
+                size: file.size,
+            },
+            url: mxc,
+        });
+        logger.debug(`Media event created with eventId ${eventId} for storageKey ${storageKey}`);
+        event = await client.mxClient.getEvent(roomId, eventId);
+    }
+    // Save the media event ID in the room state with storageKey as the key
+    logger.debug(`Saving media state event for storageKey ${storageKey} with eventId ${eventId}`);
+    await client.mxClient.sendStateEvent(roomId, EVENTS.MEDIA_STATE, storageKey, {
+        eventId,
+    });
+    // Now that the new upload is live and the state pointer is updated,
+    // redact the old media event to reclaim storage. This is safe — if
+    // redaction fails, we just have a dangling old blob (no data loss).
+    if (oldEventId) {
+        try {
+            await client.mxClient.redactEvent(roomId, oldEventId, 'Replacing with updated file');
+            logger.debug(`Successfully redacted old media event ${oldEventId}`);
+        }
+        catch (redactError) {
+            logger.warn(`Failed to redact old media event ${oldEventId}:`, redactError);
+        }
+    }
+    logger.debug(`Successfully uploaded media to room ${roomId} with storageKey ${storageKey}, eventId: ${eventId}`);
+    return { eventId, storageKey, event };
+}
+/**
+ * Gets media from a Matrix room by CID
+ * @param roomId The room ID
+ * @param storageKey The storage key of the media
+ * @returns Object containing the media buffer and content info
+ */
+export async function getMediaFromRoomByStorageKey(roomId, storageKey) {
+    const client = getClient();
+    // Get the event ID from room state
+    try {
+        logger.debug(`Attempting to retrieve media from room ${roomId} with storageKey ${storageKey}`);
+        const stateEvent = await client.mxClient.getRoomStateEvent(roomId, EVENTS.MEDIA_STATE, storageKey);
+        if (!stateEvent || !stateEvent.eventId) {
+            logger.warn(`No media state event found with storageKey: ${storageKey} in room ${roomId}`);
+            return null;
+        }
+        logger.debug(`Found media state event with eventId: ${stateEvent.eventId} for storageKey: ${storageKey}`);
+        // Get the media using the event ID
+        const result = await getMediaFromRoom(roomId, stateEvent.eventId);
+        logger.debug(`Successfully retrieved media for storageKey: ${storageKey}, size: ${result.mediaBuffer.length} bytes`);
+        // Add CID to content info
+        return {
+            mediaBuffer: result.mediaBuffer,
+            contentInfo: {
+                ...result.contentInfo,
+                storageKey,
+            },
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        // Check if it's an M_NOT_FOUND error and ignore it
+        if (errorMessage.includes('M_NOT_FOUND') ||
+            errorMessage.includes('Event not found')) {
+            logger.debug(`Media not found in Matrix for storageKey ${storageKey} (M_NOT_FOUND), this is expected for new checkpoints`);
+            return null;
+        }
+        // For other errors, log and rethrow
+        logger.error(`Error retrieving media with storageKey ${storageKey}: ${errorMessage}`, error instanceof Error ? error.stack : undefined);
+        throw new Error(`Error retrieving media with storageKey ${storageKey}: ${errorMessage}`);
+    }
+}
+/**
+ * Retrieves media from a Matrix room
+ * @param roomId The room ID where the media is located
+ * @param eventId The event ID of the media
+ * @returns Object containing the media buffer and content info
+ */
+export async function getMediaFromRoom(roomId, eventId, cachedEvent) {
+    if ((!roomId || !eventId) && !cachedEvent) {
+        throw new Error('Either roomId and eventId or cachedEvent must be provided');
+    }
+    const client = getClient();
+    const event = cachedEvent || (await client.mxClient.getEvent(roomId, eventId));
+    if (!event.content ||
+        !['m.file', 'm.image'].includes(event.content.msgtype)) {
+        throw new Error('Event is not a media event.');
+    }
+    const isEncrypted = !!event.content.file;
+    if (isEncrypted) {
+        const decryptedData = await client.mxClient.crypto.decryptMedia(event.content.file);
+        return {
+            mediaBuffer: decryptedData,
+            contentInfo: {
+                mimetype: event.content.info?.mimetype || 'application/octet-stream',
+                filename: event.content.filename || 'download',
+            },
+        };
+    }
+    else {
+        const mediaBuffer = await client.mxClient.downloadContent(event.content.url);
+        return {
+            mediaBuffer: mediaBuffer.data,
+            contentInfo: {
+                mimetype: event.content.info?.mimetype || 'application/octet-stream',
+                filename: event.content.filename || 'download',
+            },
+        };
+    }
+}
+/**
+ * Deletes media from a Matrix room by storage key
+ * @param roomId The room ID where the media is located
+ * @param storageKey The storage key of the media to delete
+ * @returns True if deletion was successful, false if not found
+ */
+export async function deleteMediaFromRoom(roomId, storageKey) {
+    const client = getClient();
+    try {
+        logger.debug(`Attempting to delete media from room ${roomId} with storageKey ${storageKey}`);
+        // Get the event ID from room state
+        const stateEvent = await client.mxClient.getRoomStateEvent(roomId, EVENTS.MEDIA_STATE, storageKey);
+        if (!stateEvent || !stateEvent.eventId) {
+            logger.warn(`No media state event found with storageKey: ${storageKey} in room ${roomId}`);
+            return false;
+        }
+        logger.debug(`Found media event ${stateEvent.eventId} for storageKey ${storageKey}, attempting to redact`);
+        // Redact the media event to delete the DB file from the server
+        try {
+            await client.mxClient.redactEvent(roomId, stateEvent.eventId, 'User requested deletion');
+            logger.debug(`Successfully redacted media event ${stateEvent.eventId} for storageKey ${storageKey}`);
+        }
+        catch (redactError) {
+            logger.error(`Failed to redact media event ${stateEvent.eventId}:`, redactError);
+            throw redactError;
+        }
+        return true;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        // Check if it's an M_NOT_FOUND error
+        if (errorMessage.includes('M_NOT_FOUND') ||
+            errorMessage.includes('Event not found')) {
+            logger.debug(`Media not found in Matrix for storageKey ${storageKey} (M_NOT_FOUND)`);
+            return false;
+        }
+        // For other errors, log and rethrow
+        logger.error(`Error deleting media with storageKey ${storageKey}: ${errorMessage}`, error instanceof Error ? error.stack : undefined);
+        throw new Error(`Error deleting media with storageKey ${storageKey}: ${errorMessage}`);
+    }
+}

package/dist/matrix/checkpointer/type.d.ts

@@ -0,0 +1,4 @@
+export interface BaseSyncArgs {
+    userDid: string;
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/matrix/checkpointer/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/matrix/checkpointer/type.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/matrix/checkpointer/type.js

@@ -0,0 +1 @@
+export {};

package/dist/matrix/checkpointer/user-matrix-sqlite-sync-service.module.d.ts

@@ -0,0 +1,3 @@
+export declare class CheckpointStorageSyncModule {
+}
+//# sourceMappingURL=user-matrix-sqlite-sync-service.module.d.ts.map

package/dist/matrix/checkpointer/user-matrix-sqlite-sync-service.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-matrix-sqlite-sync-service.module.d.ts","sourceRoot":"","sources":["../../../src/matrix/checkpointer/user-matrix-sqlite-sync-service.module.ts"],"names":[],"mappings":"AAGA,qBASa,2BAA2B;CAAG"}

package/dist/matrix/checkpointer/user-matrix-sqlite-sync-service.module.js

@@ -0,0 +1,22 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from '@nestjs/common';
+import { UserMatrixSqliteSyncService } from './user-matrix-sqlite-sync-service.service.js';
+let CheckpointStorageSyncModule = class CheckpointStorageSyncModule {
+};
+CheckpointStorageSyncModule = __decorate([
+    Module({
+        providers: [
+            {
+                provide: UserMatrixSqliteSyncService,
+                useFactory: () => UserMatrixSqliteSyncService.getInstance(),
+            },
+        ],
+        exports: [UserMatrixSqliteSyncService],
+    })
+], CheckpointStorageSyncModule);
+export { CheckpointStorageSyncModule };

package/dist/matrix/checkpointer/user-matrix-sqlite-sync-service.service.d.ts

@@ -0,0 +1,93 @@
+import { OnModuleInit } from '@nestjs/common';
+import { type Database as DatabaseType } from 'better-sqlite3';
+import { type BaseSyncArgs } from './type.js';
+export declare class UserMatrixSqliteSyncService implements OnModuleInit {
+    private static instance;
+    readonly fileEventsDatabase: DatabaseType;
+    private constructor();
+    private readonly filePathCache;
+    private readonly dbConnectionCache;
+    /** Reference-counted active users — supports nested markUserActive/markUserInactive calls */
+    private readonly activeUsers;
+    private readonly downloadInProgress;
+    private readonly recoveryInProgress;
+    private readonly lastUploadedChecksum;
+    /**
+     * Users whose SQLite checkpoint has been synced from Matrix at least once
+     * in this process lifetime. We're a single-node deployment: after the
+     * first sync, the local copy IS the source of truth until shutdown (which
+     * uploads back to Matrix). Skipping re-syncs on subsequent requests for
+     * the same user is the dominant TTFB win.
+     */
+    private readonly syncedUsers;
+    /** Prevents overlapping cron executions from interleaving I/O on the same files */
+    private cronRunning;
+    markUserActive(userDid: string): void;
+    markUserInactive(userDid: string): void;
+    private isUserActive;
+    static createUserStorageKey(userDid: string): string;
+    static getUserCheckpointDbPath(userDid: string): string;
+    static checkpointsFolder: string;
+    onModuleInit(): Promise<void>;
+    /**
+     * Get or create database connection for a user.
+     * Ensures database exists and is synced from Matrix on the first request
+     * per user per process; subsequent calls reuse the local file.
+     * Includes automatic corruption recovery.
+     */
+    getUserDatabase(userDid: string): Promise<DatabaseType>;
+    /**
+     * Same as `getUserDatabase` but never triggers a Matrix → SQLite sync.
+     * Used by hot paths that follow an earlier `getUserDatabase` call within
+     * the same request (e.g. the fire-and-forget post-message sync).
+     */
+    getUserDatabaseNoSync(userDid: string): Promise<DatabaseType>;
+    private openUserDatabaseFromDisk;
+    /**
+     * Attempts cascading recovery when a local database is corrupt:
+     *   1. Clear local → re-download from Matrix → validate
+     *   2. If Matrix copy also corrupt → delete from Matrix → create fresh empty DB
+     */
+    private recoverCorruptDatabase;
+    /**
+     * Opens a SQLite database and validates it is not corrupt.
+     * Returns the Database instance if valid, or null if corrupt/missing.
+     */
+    private openAndValidateDatabase;
+    /**
+     * Deletes local checkpoint file and clears all associated caches for a user.
+     */
+    private clearLocalCheckpoint;
+    private initializeSessionsAndCallsTables;
+    localStorageCacheCleanUpTask(): Promise<void>;
+    /**
+     * Get the singleton instance of UserMatrixSqliteSyncService
+     * @param maxCacheSize - Maximum number of cached files (default: 100)
+     * @returns The singleton instance
+     */
+    static getInstance(): UserMatrixSqliteSyncService;
+    /**
+     * Load the checkpoint SQLite file for a user.
+     * First checks the local cache, then matrix storage if not cached.
+     * @param userDid - The user's DID identifier
+     * @returns Promise resolving to the SQLite file buffer
+     */
+    syncLocalStorageFromMatrixStorage(params: BaseSyncArgs): Promise<void>;
+    private _syncLocalStorageFromMatrixStorage;
+    /**
+     * Sync checkpoint file from local cache to S3.
+     * @param userDid - The user's DID identifier
+     * @returns Promise that resolves when sync is complete
+     */
+    uploadCheckpointToMatrixStorage(params: BaseSyncArgs): Promise<void>;
+    uploadCheckpointToMatrixStorageTask(): Promise<void>;
+    /**
+     * Deletes user storage from Matrix and cleans up local cache
+     * @param userDid The user DID
+     * @param storageKey Optional storage key. If not provided, uses the default user storage key
+     * @returns True if deletion was successful, false if not found
+     */
+    deleteUserStorageFromMatrix(userDid: string, storageKey?: string): Promise<boolean>;
+    private saveFileEventToDB;
+}
+//# sourceMappingURL=user-matrix-sqlite-sync-service.service.d.ts.map

package/dist/matrix/checkpointer/user-matrix-sqlite-sync-service.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-matrix-sqlite-sync-service.service.d.ts","sourceRoot":"","sources":["../../../src/matrix/checkpointer/user-matrix-sqlite-sync-service.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,YAAY,EACb,MAAM,gBAAgB,CAAC;AAWxB,OAAiB,EAAE,KAAK,QAAQ,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAUzE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AA+C9C,qBACa,2BAA4B,YAAW,YAAY;IAC9D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA8B;IAErD,QAAQ,CAAC,kBAAkB,EAAE,YAAY,CAAC;IAC1C,OAAO;IAkBP,OAAO,CAAC,QAAQ,CAAC,aAAa,CAM1B;IAEJ,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAM9B;IAEJ,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoC;IACvE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAG/B;IAEJ,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6B;IAElE;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IAEjD,mFAAmF;IACnF,OAAO,CAAC,WAAW,CAAS;IAErB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKrC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAS9C,OAAO,CAAC,YAAY;IAGpB,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAKpD,MAAM,CAAC,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IASvD,MAAM,CAAC,iBAAiB,SAGtB;IAEW,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAuE1C;;;;;OAKG;IACU,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IASpE;;;;OAIG;IACU,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;YAI5D,wBAAwB;IAqDtC;;;;OAIG;YACW,sBAAsB;IA0DpC;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAwC/B;;OAEG;YACW,oBAAoB;IAiDlC,OAAO,CAAC,gCAAgC;IA4B3B,4BAA4B,IAAI,OAAO,CAAC,IAAI,CAAC;IA2F1D;;;;OAIG;WACW,WAAW,IAAI,2BAA2B;IAOxD;;;;;OAKG;IACU,iCAAiC,CAC5C,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC;YAsBF,kCAAkC;IA2LhD;;;;OAIG;IACG,+BAA+B,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAoHpE,mCAAmC,IAAI,OAAO,CAAC,IAAI,CAAC;IAqC1D;;;;;OAKG;IACG,2BAA2B,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC;YAyFL,iBAAiB;CAsBhC"}