exovault-mcp-server 1.0.0

package/dist/auth.d.ts

@@ -0,0 +1,41 @@
+import { type SupabaseClient } from "@supabase/supabase-js";
+export interface McpConfig {
+    supabaseUrl: string;
+    supabaseAnonKey: string;
+    accessToken: string;
+    refreshToken: string;
+    mekHex: string;
+    openaiApiKey?: string;
+    defaultVaultId?: string;
+    allowGlobalMemoryWrite?: boolean;
+    llmApiKey?: string;
+    llmBaseUrl?: string;
+    llmModelId?: string;
+    /** Agent key for gateway mode (exv_...) */
+    agentKey?: string;
+    /** Gateway base URL (default: https://exovault.co) */
+    apiUrl?: string;
+}
+export interface LlmConfig {
+    apiKey: string;
+    baseUrl: string;
+    modelId: string;
+}
+export interface McpContext {
+    supabase: SupabaseClient;
+    userId: string;
+    masterKey: CryptoKey;
+    /** Raw MEK hex for blind index key derivation (HMAC-SHA256). */
+    mekHex: string;
+    openaiApiKey?: string;
+    defaultVaultId?: string;
+    allowGlobalMemoryWrite: boolean;
+    /** Server-side LLM config for entity extraction and other server operations. */
+    llmConfig?: LlmConfig;
+}
+export declare function readConfig(): Promise<McpConfig>;
+/**
+ * Reads stored config, refreshes Supabase session (with cross-process lock),
+ * and imports the MEK. Called once on MCP server startup.
+ */
+export declare function initialize(): Promise<McpContext>;

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAiB1E,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,CAAC;IACrB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,OAAO,CAAC;IAChC,gFAAgF;IAChF,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAgED,wBAAsB,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CAmBrD;AAoHD;;;GAGG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CAkFtD"}

package/dist/auth.js

@@ -0,0 +1,236 @@
+import { createClient } from "@supabase/supabase-js";
+import { readFile, writeFile, rename, open, unlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { hexToBuffer, importMasterKey } from "./crypto.js";
+const CONFIG_DIR = join(homedir(), ".exovault-mcp");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+const LOCK_FILE = join(CONFIG_DIR, "refresh.lock");
+/** Max age (ms) before a lock is considered stale (crashed process). */
+const LOCK_STALE_MS = 10_000;
+/** How long to wait between lock-retry attempts (ms). */
+const LOCK_POLL_MS = 200;
+/** Max total time to wait for a lock before giving up (ms). */
+const LOCK_TIMEOUT_MS = 15_000;
+// ── Lock helpers ──────────────────────────────────────────────────────
+async function acquireLock() {
+    try {
+        // O_EXCL fails atomically if the file already exists
+        const handle = await open(LOCK_FILE, "wx");
+        await handle.writeFile(String(process.pid));
+        await handle.close();
+        return true;
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+            return false;
+        }
+        throw err;
+    }
+}
+async function releaseLock() {
+    try {
+        await unlink(LOCK_FILE);
+    }
+    catch {
+        // Already removed — not a problem
+    }
+}
+async function isLockStale() {
+    try {
+        const info = await stat(LOCK_FILE);
+        return Date.now() - info.mtimeMs > LOCK_STALE_MS;
+    }
+    catch {
+        // Lock file gone — treat as stale so caller can proceed
+        return true;
+    }
+}
+/**
+ * Wait until we either acquire the lock or the other holder finishes.
+ * Returns `"acquired"` if we own the lock (caller must refresh + release),
+ * or `"waited"` if another process already refreshed (caller should re-read config).
+ */
+async function waitForLock() {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await acquireLock())
+            return "acquired";
+        // Check for stale lock from a crashed process
+        if (await isLockStale()) {
+            await releaseLock();
+            if (await acquireLock())
+                return "acquired";
+        }
+        await new Promise((r) => setTimeout(r, LOCK_POLL_MS));
+    }
+    // Timeout — another process held the lock long enough that it likely refreshed
+    // Re-read config to get the new tokens
+    return "waited";
+}
+// ── Read config helper ────────────────────────────────────────────────
+export async function readConfig() {
+    let configRaw;
+    try {
+        configRaw = await readFile(CONFIG_FILE, "utf-8");
+    }
+    catch {
+        throw new Error(`Config not found at ${CONFIG_FILE}. Run 'npx exovault-mcp setup --url <url> --key <key>' first.`);
+    }
+    const config = JSON.parse(configRaw);
+    // Gateway mode only needs agentKey — skip Supabase credential check
+    if (!config.agentKey && (!config.supabaseUrl || !config.supabaseAnonKey)) {
+        throw new Error(`Config is missing Supabase credentials. Re-run 'npx exovault-mcp setup --url <url> --key <key>'.`);
+    }
+    return config;
+}
+function isRefreshTokenAlreadyUsed(message) {
+    if (!message)
+        return false;
+    const normalized = message.toLowerCase();
+    return normalized.includes("refresh token") && normalized.includes("already used");
+}
+async function fallbackWithAccessToken(config) {
+    const supabase = createClient(config.supabaseUrl, config.supabaseAnonKey, {
+        auth: {
+            persistSession: false,
+            autoRefreshToken: false,
+        },
+        global: {
+            headers: {
+                Authorization: `Bearer ${config.accessToken}`,
+            },
+        },
+    });
+    const { data, error } = await supabase.auth.getUser(config.accessToken);
+    if (error || !data.user) {
+        throw new Error(`Session expired or invalid. Re-run 'npx exovault-mcp setup --url <url> --key <key>'. ${error?.message ?? ""}`);
+    }
+    return { supabase, userId: data.user.id };
+}
+async function setSessionWithConfig(supabase, config) {
+    return supabase.auth.setSession({
+        refresh_token: config.refreshToken,
+        access_token: config.accessToken,
+    });
+}
+// ── Token persistence ─────────────────────────────────────────────────
+async function persistTokens(accessToken, refreshToken) {
+    const config = await readConfig();
+    const content = JSON.stringify({ ...config, accessToken, refreshToken }, null, 2);
+    // Atomic write: write to temp file then rename to prevent corruption on crash
+    const tmpFile = `${CONFIG_FILE}.tmp`;
+    await writeFile(tmpFile, content, { encoding: "utf-8", mode: 0o600 });
+    await rename(tmpFile, CONFIG_FILE);
+}
+// ── Refresh session (called only by lock holder) ──────────────────────
+async function refreshSession(config) {
+    const supabase = createClient(config.supabaseUrl, config.supabaseAnonKey);
+    let { data: setData, error: setError } = await setSessionWithConfig(supabase, config);
+    // Another process may have rotated refresh token just before we acquired the lock.
+    // Re-read config once and retry with newest tokens.
+    if ((setError || !setData.session) && isRefreshTokenAlreadyUsed(setError?.message)) {
+        const latest = await readConfig();
+        ({ data: setData, error: setError } = await setSessionWithConfig(supabase, latest));
+        config = latest;
+    }
+    if (setError || !setData.session) {
+        if (isRefreshTokenAlreadyUsed(setError?.message)) {
+            const accessFallback = await fallbackWithAccessToken(config);
+            return {
+                supabase: accessFallback.supabase,
+                session: { user: { id: accessFallback.userId } },
+            };
+        }
+        throw new Error(`Session expired or invalid. Re-run 'npx exovault-mcp setup --url <url> --key <key>'. ${setError?.message ?? ""}`);
+    }
+    // Persist refreshed tokens so subsequent startups (or other agents) use valid tokens
+    await persistTokens(setData.session.access_token, setData.session.refresh_token);
+    return { supabase, session: setData.session };
+}
+// ── Public API ────────────────────────────────────────────────────────
+function buildLlmConfig(config) {
+    const apiKey = config.llmApiKey ?? config.openaiApiKey;
+    if (!apiKey)
+        return undefined;
+    return {
+        apiKey,
+        baseUrl: config.llmBaseUrl ?? "https://api.openai.com/v1",
+        modelId: config.llmModelId ?? "gpt-4o-mini",
+    };
+}
+/**
+ * Reads stored config, refreshes Supabase session (with cross-process lock),
+ * and imports the MEK. Called once on MCP server startup.
+ */
+export async function initialize() {
+    const lockResult = await waitForLock();
+    let config = await readConfig();
+    let supabase;
+    let userId;
+    if (lockResult === "acquired") {
+        try {
+            const result = await refreshSession(config);
+            supabase = result.supabase;
+            userId = result.session.user.id;
+        }
+        finally {
+            await releaseLock();
+        }
+    }
+    else {
+        // Another process already refreshed — re-read config with fresh tokens
+        config = await readConfig();
+        supabase = createClient(config.supabaseUrl, config.supabaseAnonKey);
+        let { data, error } = await setSessionWithConfig(supabase, config);
+        if ((error || !data.session) && isRefreshTokenAlreadyUsed(error?.message)) {
+            await new Promise((r) => setTimeout(r, 300));
+            config = await readConfig();
+            ({ data, error } = await setSessionWithConfig(supabase, config));
+        }
+        if (error || !data.session) {
+            if (isRefreshTokenAlreadyUsed(error?.message)) {
+                const accessFallback = await fallbackWithAccessToken(config);
+                userId = accessFallback.userId;
+                supabase = accessFallback.supabase;
+                // Continue using current access token for this process.
+                // Future startups can still refresh after setup or next token persistence cycle.
+                const mekBytes = hexToBuffer(config.mekHex);
+                const masterKey = await importMasterKey(mekBytes);
+                return {
+                    supabase,
+                    userId,
+                    masterKey,
+                    mekHex: config.mekHex,
+                    openaiApiKey: config.openaiApiKey,
+                    defaultVaultId: config.defaultVaultId,
+                    allowGlobalMemoryWrite: config.allowGlobalMemoryWrite === true,
+                    llmConfig: buildLlmConfig(config),
+                };
+            }
+            throw new Error(`Session expired after waiting for lock. Re-run 'npx exovault-mcp setup --url <url> --key <key>'. ${error?.message ?? ""}`);
+        }
+        userId = data.session.user.id;
+    }
+    // Import MEK
+    const mekBytes = hexToBuffer(config.mekHex);
+    const masterKey = await importMasterKey(mekBytes);
+    // Persist tokens whenever the Supabase client auto-refreshes mid-session.
+    // Without this, config.json goes stale and future restarts / other processes
+    // see expired tokens, causing silent auth failures (RLS returns empty sets).
+    supabase.auth.onAuthStateChange((event, session) => {
+        if (event === "TOKEN_REFRESHED" && session) {
+            persistTokens(session.access_token, session.refresh_token).then(() => process.stderr.write("[exovault-mcp] Token auto-refreshed and persisted\n"), (err) => process.stderr.write(`[exovault-mcp] Failed to persist refreshed token: ${err.message}\n`));
+        }
+    });
+    return {
+        supabase,
+        userId,
+        masterKey,
+        mekHex: config.mekHex,
+        openaiApiKey: config.openaiApiKey,
+        defaultVaultId: config.defaultVaultId,
+        allowGlobalMemoryWrite: config.allowGlobalMemoryWrite === true,
+        llmConfig: buildLlmConfig(config),
+    };
+}

package/dist/auth.js.map

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

package/dist/auto-session.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Auto-session inject: ensures session context is loaded on the first tool call,
+ * even if the agent doesn't explicitly call `session_start`.
+ *
+ * Also tracks tool call count and appends checkpoint reminders at configurable
+ * thresholds, coaching agents toward better memory habits.
+ *
+ * Usage in index.ts:
+ *   const auto = createAutoSession(() => runSessionStart());
+ *   server.registerTool("some_tool", opts, auto.wrap(handler));
+ *   // For session_start itself: call auto.markInjected() inside its handler
+ */
+export type ToolResponse = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: true;
+};
+export type SessionStartFn = () => Promise<string>;
+export type LogFn = (msg: string) => void;
+/**
+ * Callback fired on every tool call for session tracking.
+ * Called fire-and-forget — errors are swallowed.
+ */
+export type TrackFn = (toolName: string) => void;
+export interface AutoSessionOptions {
+    /** Tool call counts at which to append checkpoint reminders. Default: [25, 50, 75]. */
+    reminderThresholds?: number[];
+    /** Called on every tool call for session tracking (fire-and-forget). */
+    onToolCall?: TrackFn;
+}
+export declare function createAutoSession(runSessionStart: SessionStartFn, log?: LogFn, options?: AutoSessionOptions): {
+    markInjected: () => void;
+    isInjected: () => boolean;
+    getPrefix: () => Promise<string | null>;
+    getToolCallCount: () => number;
+    wrap: <T>(handler: (args: T) => Promise<ToolResponse>, toolName?: string) => (args: T) => Promise<ToolResponse>;
+};

package/dist/auto-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-session.d.ts","sourceRoot":"","sources":["../src/auto-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;AACnD,MAAM,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IACjC,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAID,wBAAgB,iBAAiB,CAC/B,eAAe,EAAE,cAAc,EAC/B,GAAG,GAAE,KAAgB,EACrB,OAAO,GAAE,kBAAuB;wBASP,IAAI;sBAKN,OAAO;qBAaF,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;4BARrB,MAAM;WAqDrB,CAAC,WACJ,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,aAChC,MAAM,KAChB,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC;EAsDtC"}

package/dist/auto-session.js

@@ -0,0 +1,128 @@
+/**
+ * Auto-session inject: ensures session context is loaded on the first tool call,
+ * even if the agent doesn't explicitly call `session_start`.
+ *
+ * Also tracks tool call count and appends checkpoint reminders at configurable
+ * thresholds, coaching agents toward better memory habits.
+ *
+ * Usage in index.ts:
+ *   const auto = createAutoSession(() => runSessionStart());
+ *   server.registerTool("some_tool", opts, auto.wrap(handler));
+ *   // For session_start itself: call auto.markInjected() inside its handler
+ */
+const DEFAULT_REMINDER_THRESHOLDS = [10, 25, 50];
+export function createAutoSession(runSessionStart, log = () => { }, options = {}) {
+    let injected = false;
+    let toolCallCount = 0;
+    const thresholds = options.reminderThresholds ?? DEFAULT_REMINDER_THRESHOLDS;
+    const firedThresholds = new Set();
+    const onToolCall = options.onToolCall;
+    /** Mark session context as already loaded (e.g. when session_start is called explicitly). */
+    function markInjected() {
+        injected = true;
+    }
+    /** Check whether session context has been loaded (either auto or explicit). */
+    function isInjected() {
+        return injected;
+    }
+    /** Get the current tool call count (for testing/monitoring). */
+    function getToolCallCount() {
+        return toolCallCount;
+    }
+    /**
+     * Attempt to load session context. Returns the context string on first call,
+     * null on subsequent calls. Errors are swallowed — the original tool must still work.
+     */
+    async function getPrefix() {
+        if (injected)
+            return null;
+        injected = true;
+        try {
+            log("[exovault-mcp] Auto-injecting session context (agent did not call session_start)");
+            const result = await runSessionStart();
+            log("[exovault-mcp] Auto-session context loaded successfully");
+            return result;
+        }
+        catch (e) {
+            log(`[exovault-mcp] Auto-session context failed: ${e.message}`);
+            return null;
+        }
+    }
+    /**
+     * Build a checkpoint reminder suffix if the current tool call count
+     * just crossed a threshold. Returns null if no reminder is due.
+     */
+    function getCheckpointReminder() {
+        for (const threshold of thresholds) {
+            if (toolCallCount >= threshold && !firedThresholds.has(threshold)) {
+                firedThresholds.add(threshold);
+                return (`\n\n---\n**ExoVault Reminder** (${toolCallCount} tool calls this session): ` +
+                    `Have you saved what you've learned? Check these triggers:\n` +
+                    `- Preference/rule stated by user? → \`write_memory\`(preference/constraint)\n` +
+                    `- Non-obvious fact discovered? → \`write_memory\`(fact)\n` +
+                    `- Decision made? → \`write_memory\`(fact, importance 4-5)\n` +
+                    `- Problem solved or procedure learned? → \`write_memory\`(skill)\n` +
+                    `- Previous knowledge wrong? → \`write_memory\`(correction + supersededById)\n` +
+                    `If the session is winding down, call \`context_checkpoint\` to preserve session context.`);
+            }
+        }
+        return null;
+    }
+    /**
+     * Wrap a tool handler so that the first successful tool call in this connection
+     * gets session context prepended to its response. Also tracks tool call count
+     * and appends checkpoint reminders at thresholds.
+     *
+     * @param handler - The original tool handler function.
+     * @param toolName - Optional tool name for session tracking (passed to onToolCall).
+     */
+    function wrap(handler, toolName) {
+        return async (args) => {
+            const prefix = await getPrefix();
+            const result = await handler(args);
+            toolCallCount++;
+            // Fire session tracking callback (fire-and-forget)
+            if (onToolCall && toolName) {
+                try {
+                    onToolCall(toolName);
+                }
+                catch {
+                    // Never fail the tool call because of tracking
+                }
+            }
+            // Only modify successful responses
+            if (result.isError)
+                return result;
+            // Auto-inject takes priority — don't also append a reminder on the same call
+            if (prefix) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `## Session Context (auto-loaded)\n\n` +
+                                `The following context was automatically loaded because \`session_start\` was not called explicitly. ` +
+                                `You should still follow the instructions and documents below.\n\n` +
+                                `${prefix}\n\n` +
+                                `---\n\n` +
+                                `## Tool Result\n\n${result.content[0].text}`,
+                        },
+                    ],
+                };
+            }
+            // Check for checkpoint reminder
+            const reminder = getCheckpointReminder();
+            if (reminder) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: result.content[0].text + reminder,
+                        },
+                    ],
+                };
+            }
+            return result;
+        };
+    }
+    return { markInjected, isInjected, getPrefix, getToolCallCount, wrap };
+}

package/dist/auto-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-session.js","sourceRoot":"","sources":["../src/auto-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,2BAA2B,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;AAEjD,MAAM,UAAU,iBAAiB,CAC/B,eAA+B,EAC/B,MAAa,GAAG,EAAE,GAAE,CAAC,EACrB,UAA8B,EAAE;IAEhC,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,MAAM,UAAU,GAAG,OAAO,CAAC,kBAAkB,IAAI,2BAA2B,CAAC;IAC7E,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAEtC,6FAA6F;IAC7F,SAAS,YAAY;QACnB,QAAQ,GAAG,IAAI,CAAC;IAClB,CAAC;IAED,+EAA+E;IAC/E,SAAS,UAAU;QACjB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,gEAAgE;IAChE,SAAS,gBAAgB;QACvB,OAAO,aAAa,CAAC;IACvB,CAAC;IAED;;;OAGG;IACH,KAAK,UAAU,SAAS;QACtB,IAAI,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC1B,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,CAAC,kFAAkF,CAAC,CAAC;YACxF,MAAM,MAAM,GAAG,MAAM,eAAe,EAAE,CAAC;YACvC,GAAG,CAAC,yDAAyD,CAAC,CAAC;YAC/D,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,GAAG,CAAC,+CAAgD,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;YAC3E,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,SAAS,qBAAqB;QAC5B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,aAAa,IAAI,SAAS,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAClE,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBAC/B,OAAO,CACL,mCAAmC,aAAa,6BAA6B;oBAC7E,6DAA6D;oBAC7D,+EAA+E;oBAC/E,2DAA2D;oBAC3D,6DAA6D;oBAC7D,oEAAoE;oBACpE,+EAA+E;oBAC/E,0FAA0F,CAC3F,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,IAAI,CACX,OAA2C,EAC3C,QAAiB;QAEjB,OAAO,KAAK,EAAE,IAAO,EAAE,EAAE;YACvB,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;YACnC,aAAa,EAAE,CAAC;YAEhB,mDAAmD;YACnD,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;gBAC3B,IAAI,CAAC;oBACH,UAAU,CAAC,QAAQ,CAAC,CAAC;gBACvB,CAAC;gBAAC,MAAM,CAAC;oBACP,+CAA+C;gBACjD,CAAC;YACH,CAAC;YAED,mCAAmC;YACnC,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,MAAM,CAAC;YAElC,6EAA6E;YAC7E,IAAI,MAAM,EAAE,CAAC;gBACX,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EACF,sCAAsC;gCACtC,sGAAsG;gCACtG,mEAAmE;gCACnE,GAAG,MAAM,MAAM;gCACf,SAAS;gCACT,qBAAqB,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;yBAChD;qBACF;iBACF,CAAC;YACJ,CAAC;YAED,gCAAgC;YAChC,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;YACzC,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,QAAQ;yBACxC;qBACF;iBACF,CAAC;YACJ,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;AACzE,CAAC"}

package/dist/buffer-persistence.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Buffer disk persistence — crash recovery for session buffers.
+ *
+ * Writes session buffer data to disk periodically so that if the MCP process
+ * crashes or is killed without a clean flush, the orphaned buffer can be
+ * recovered on the next startup.
+ *
+ * Files: ~/.exovault-mcp/sessions/session-{agentRunId}.json
+ */
+import type { SessionBufferData } from "./session-buffer.js";
+/**
+ * Write session buffer data to disk for crash recovery.
+ * Creates the sessions directory if it doesn't exist.
+ */
+export declare function writeBufferToDisk(data: SessionBufferData): Promise<void>;
+/**
+ * Read a session buffer from disk by agentRunId.
+ * Returns null if file doesn't exist, is corrupt, or is invalid.
+ */
+export declare function readBufferFromDisk(agentRunId: string): Promise<SessionBufferData | null>;
+/**
+ * Delete a session buffer file after successful flush.
+ * Silently ignores ENOENT (file already gone).
+ */
+export declare function deleteBuffer(agentRunId: string): Promise<void>;
+/**
+ * Scan for orphaned session buffers that are stale and unflushed.
+ *
+ * Returns buffers where:
+ *  - lastActivityAt is older than staleMinutes
+ *  - lastFlushedAt is null (never flushed)
+ *
+ * Skips invalid files silently.
+ */
+export declare function scanOrphanedBuffers(staleMinutes?: number): Promise<SessionBufferData[]>;

package/dist/buffer-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-persistence.d.ts","sourceRoot":"","sources":["../src/buffer-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAW7D;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9E;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAY9F;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASpE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,GAAE,MAA8B,GAC3C,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAgD9B"}

package/dist/buffer-persistence.js

@@ -0,0 +1,110 @@
+/**
+ * Buffer disk persistence — crash recovery for session buffers.
+ *
+ * Writes session buffer data to disk periodically so that if the MCP process
+ * crashes or is killed without a clean flush, the orphaned buffer can be
+ * recovered on the next startup.
+ *
+ * Files: ~/.exovault-mcp/sessions/session-{agentRunId}.json
+ */
+import { readFile, writeFile, mkdir, unlink, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const CONFIG_DIR = join(homedir(), ".exovault-mcp");
+const SESSIONS_DIR = join(CONFIG_DIR, "sessions");
+const DEFAULT_STALE_MINUTES = 10;
+function bufferPath(agentRunId) {
+    return join(SESSIONS_DIR, `session-${agentRunId}.json`);
+}
+/**
+ * Write session buffer data to disk for crash recovery.
+ * Creates the sessions directory if it doesn't exist.
+ */
+export async function writeBufferToDisk(data) {
+    await mkdir(SESSIONS_DIR, { recursive: true, mode: 0o700 });
+    await writeFile(bufferPath(data.agentRunId), JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 0o600 });
+}
+/**
+ * Read a session buffer from disk by agentRunId.
+ * Returns null if file doesn't exist, is corrupt, or is invalid.
+ */
+export async function readBufferFromDisk(agentRunId) {
+    try {
+        const raw = await readFile(bufferPath(agentRunId), "utf-8");
+        const parsed = JSON.parse(raw);
+        // Basic validation — must have agentRunId
+        if (!parsed || typeof parsed.agentRunId !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete a session buffer file after successful flush.
+ * Silently ignores ENOENT (file already gone).
+ */
+export async function deleteBuffer(agentRunId) {
+    try {
+        await unlink(bufferPath(agentRunId));
+    }
+    catch (e) {
+        if (e && typeof e === "object" && "code" in e && e.code === "ENOENT") {
+            return; // Already deleted — fine
+        }
+        throw e;
+    }
+}
+/**
+ * Scan for orphaned session buffers that are stale and unflushed.
+ *
+ * Returns buffers where:
+ *  - lastActivityAt is older than staleMinutes
+ *  - lastFlushedAt is null (never flushed)
+ *
+ * Skips invalid files silently.
+ */
+export async function scanOrphanedBuffers(staleMinutes = DEFAULT_STALE_MINUTES) {
+    // Ensure directory exists
+    await mkdir(SESSIONS_DIR, { recursive: true, mode: 0o700 });
+    let files;
+    try {
+        files = (await readdir(SESSIONS_DIR));
+    }
+    catch {
+        return [];
+    }
+    const staleThreshold = Date.now() - staleMinutes * 60_000;
+    const orphans = [];
+    for (const file of files) {
+        // Only process session-*.json files
+        if (!file.startsWith("session-") || !file.endsWith(".json")) {
+            continue;
+        }
+        try {
+            const raw = await readFile(join(SESSIONS_DIR, file), "utf-8");
+            const parsed = JSON.parse(raw);
+            // Validate basic shape
+            if (!parsed || typeof parsed.agentRunId !== "string") {
+                continue;
+            }
+            const data = parsed;
+            // Skip already flushed
+            if (data.lastFlushedAt) {
+                continue;
+            }
+            // Check staleness
+            const lastActivity = new Date(data.lastActivityAt).getTime();
+            if (lastActivity < staleThreshold) {
+                orphans.push(data);
+            }
+        }
+        catch {
+            // Invalid file — skip silently
+            continue;
+        }
+    }
+    return orphans;
+}

package/dist/buffer-persistence.js.map

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