exovault-mcp-server 1.0.0

package/dist/db.js

@@ -0,0 +1,866 @@
+import { sanitizeDbError } from "./error-sanitizer.js";
+// ─── Query helpers ────────────────────────────────────────────────────────────
+export async function getVaults(supabase, userId) {
+    const { data, error } = await supabase
+        .from("vaults")
+        .select("*")
+        .eq("user_id", userId)
+        .order("sort_order", { ascending: true });
+    if (error)
+        throw new Error(sanitizeDbError("fetch vaults", error.message));
+    return data ?? [];
+}
+export async function getNotes(supabase, userId, vaultId, limit = 20) {
+    let query = supabase
+        .from("notes")
+        .select("*")
+        .eq("user_id", userId)
+        .eq("is_trashed", false)
+        .order("updated_at", { ascending: false })
+        .limit(limit);
+    if (vaultId) {
+        query = query.eq("vault_id", vaultId);
+    }
+    const { data, error } = await query;
+    if (error)
+        throw new Error(sanitizeDbError("fetch notes", error.message));
+    return data ?? [];
+}
+export async function getNote(supabase, userId, noteId) {
+    const { data, error } = await supabase
+        .from("notes")
+        .select("*")
+        .eq("id", noteId)
+        .eq("user_id", userId)
+        .single();
+    if (error) {
+        if (error.code === "PGRST116")
+            return null; // not found
+        throw new Error(sanitizeDbError("fetch note", error.message));
+    }
+    return data;
+}
+export async function getVault(supabase, userId, vaultId) {
+    const { data, error } = await supabase
+        .from("vaults")
+        .select("*")
+        .eq("id", vaultId)
+        .eq("user_id", userId)
+        .single();
+    if (error) {
+        if (error.code === "PGRST116")
+            return null;
+        throw new Error(sanitizeDbError("fetch vault", error.message));
+    }
+    return data;
+}
+export async function countNotesByVault(supabase, userId) {
+    const { data, error } = await supabase
+        .from("notes")
+        .select("vault_id")
+        .eq("user_id", userId)
+        .eq("is_trashed", false)
+        .limit(10_000);
+    if (error)
+        throw new Error(sanitizeDbError("count notes", error.message));
+    const counts = {};
+    for (const row of data ?? []) {
+        counts[row.vault_id] = (counts[row.vault_id] ?? 0) + 1;
+    }
+    return counts;
+}
+export async function insertNote(supabase, data) {
+    const { data: row, error } = await supabase
+        .from("notes")
+        .insert(data)
+        .select("id")
+        .single();
+    if (error)
+        throw new Error(sanitizeDbError("insert note", error.message));
+    return row;
+}
+export async function updateNote(supabase, noteId, userId, updates) {
+    const { error } = await supabase
+        .from("notes")
+        .update({ ...updates, updated_at: new Date().toISOString() })
+        .eq("id", noteId)
+        .eq("user_id", userId);
+    if (error)
+        throw new Error(sanitizeDbError("update note", error.message));
+}
+export async function deleteNote(supabase, noteId, userId) {
+    const { error } = await supabase
+        .from("notes")
+        .delete()
+        .eq("id", noteId)
+        .eq("user_id", userId);
+    if (error)
+        throw new Error(sanitizeDbError("delete note", error.message));
+}
+// ─── Memory helpers ───────────────────────────────────────────────────────────
+export async function getMemories(supabase, userId, options) {
+    const includeArchived = options?.includeArchived ?? false;
+    const limit = options?.limit ?? 50;
+    const orderBy = options?.orderBy ?? "updated_at";
+    let query = supabase
+        .from("memories")
+        .select("*")
+        .eq("user_id", userId)
+        .order(orderBy, { ascending: false })
+        .limit(limit);
+    if (!includeArchived)
+        query = query.eq("is_archived", false);
+    if (options?.vaultId)
+        query = query.eq("vault_id", options.vaultId);
+    if (options?.memoryType)
+        query = query.eq("memory_type", options.memoryType);
+    if (options?.minImportance)
+        query = query.gte("importance", options.minImportance);
+    const { data, error } = await query;
+    if (error)
+        throw new Error(sanitizeDbError("fetch memories", error.message));
+    return (data ?? []);
+}
+export async function getMemory(supabase, userId, memoryId) {
+    const { data, error } = await supabase
+        .from("memories")
+        .select("*")
+        .eq("id", memoryId)
+        .eq("user_id", userId)
+        .single();
+    if (error) {
+        if (error.code === "PGRST116")
+            return null;
+        throw new Error(sanitizeDbError("fetch memory", error.message));
+    }
+    return data;
+}
+export async function getMemoryByExternalWriteId(supabase, userId, externalWriteId) {
+    const { data, error } = await supabase
+        .from("memories")
+        .select("*")
+        .eq("user_id", userId)
+        .eq("external_write_id", externalWriteId)
+        .limit(1);
+    if (error)
+        throw new Error(sanitizeDbError("fetch memory by externalWriteId", error.message));
+    return (data && data.length > 0 ? data[0] : null);
+}
+export async function insertMemory(supabase, data) {
+    const { data: row, error } = await supabase
+        .from("memories")
+        .insert({
+        ...data,
+        indexing_status: data.indexing_status ?? "pending",
+        importance: data.importance ?? 3,
+        confidence: data.confidence ?? 3,
+    })
+        .select("*")
+        .single();
+    if (error)
+        throw new Error(sanitizeDbError("insert memory", error.message));
+    return row;
+}
+export async function updateMemory(supabase, memoryId, userId, updates) {
+    const { data, error } = await supabase
+        .from("memories")
+        .update({ ...updates, updated_at: new Date().toISOString() })
+        .eq("id", memoryId)
+        .eq("user_id", userId)
+        .select("*")
+        .single();
+    if (error)
+        throw new Error(sanitizeDbError("update memory", error.message));
+    return data;
+}
+/**
+ * Update last_accessed_at for a batch of memory IDs.
+ * Fire-and-forget — errors are silently ignored so this never blocks the caller.
+ *
+ * Tries RPC `increment_memory_access` for atomic counter increment.
+ * Falls back to simple timestamp update if RPC doesn't exist yet.
+ */
+export async function touchMemories(supabase, userId, memoryIds) {
+    if (memoryIds.length === 0)
+        return;
+    try {
+        const now = new Date().toISOString();
+        await Promise.all(memoryIds.map(async (id) => {
+            const { error: rpcError } = await supabase.rpc("increment_memory_access", {
+                p_memory_id: id,
+                p_user_id: userId,
+                p_accessed_at: now,
+            });
+            if (rpcError) {
+                // RPC doesn't exist yet — just update timestamp
+                await supabase
+                    .from("memories")
+                    .update({ last_accessed_at: now })
+                    .eq("id", id)
+                    .eq("user_id", userId);
+            }
+        }));
+    }
+    catch {
+        // Fire-and-forget — never fail the parent operation
+    }
+}
+export async function archiveMemory(supabase, memoryId, userId, archived) {
+    const { error } = await supabase
+        .from("memories")
+        .update({ is_archived: archived, updated_at: new Date().toISOString() })
+        .eq("id", memoryId)
+        .eq("user_id", userId);
+    if (error)
+        throw new Error(sanitizeDbError("archive memory", error.message));
+}
+export async function deleteMemory(supabase, memoryId, userId) {
+    const { error } = await supabase
+        .from("memories")
+        .delete()
+        .eq("id", memoryId)
+        .eq("user_id", userId);
+    if (error)
+        throw new Error(sanitizeDbError("delete memory", error.message));
+}
+export async function replaceMemoryEmbeddings(supabase, input) {
+    const { error: deleteError } = await supabase
+        .from("memory_embeddings")
+        .delete()
+        .eq("memory_id", input.memoryId)
+        .eq("user_id", input.userId);
+    if (deleteError) {
+        throw new Error(sanitizeDbError("delete memory embeddings", deleteError.message));
+    }
+    if (input.rows.length === 0)
+        return;
+    const { error: insertError } = await supabase
+        .from("memory_embeddings")
+        .insert(input.rows.map((row) => ({
+        memory_id: input.memoryId,
+        user_id: input.userId,
+        chunk_index: row.chunkIndex,
+        embedding: row.embedding,
+        content_hash: input.contentHash,
+        embedding_model: input.embeddingModel,
+        token_count: row.tokenCount ?? null,
+    })));
+    if (insertError) {
+        throw new Error(sanitizeDbError("insert memory embeddings", insertError.message));
+    }
+}
+/**
+ * Fetch embeddings for a batch of memory IDs.
+ * Returns one embedding per memory (chunk_index = 0 preferred).
+ */
+export async function getEmbeddingsForMemories(supabase, userId, memoryIds) {
+    if (memoryIds.length === 0)
+        return [];
+    const { data, error } = await supabase
+        .from("memory_embeddings")
+        .select("memory_id, embedding")
+        .eq("user_id", userId)
+        .in("memory_id", memoryIds)
+        .order("chunk_index", { ascending: true });
+    if (error)
+        throw new Error(sanitizeDbError("fetch memory embeddings", error.message));
+    // Keep only the first embedding per memory (chunk_index=0)
+    const seen = new Set();
+    const result = [];
+    for (const row of data ?? []) {
+        if (!seen.has(row.memory_id)) {
+            seen.add(row.memory_id);
+            result.push({ memory_id: row.memory_id, embedding: row.embedding });
+        }
+    }
+    return result;
+}
+export async function matchNoteEmbeddings(supabase, embedding, userId, threshold = 0.5, count = 20) {
+    const { data, error } = await supabase.rpc("match_note_embeddings", {
+        query_embedding: JSON.stringify(embedding),
+        match_threshold: threshold,
+        match_count: count,
+        p_user_id: userId,
+    });
+    if (error)
+        throw new Error(sanitizeDbError("match note embeddings", error.message));
+    return (data ?? []);
+}
+export async function matchMemoryEmbeddings(supabase, embedding, userId, threshold = 0.5, count = 20) {
+    const { data, error } = await supabase.rpc("match_memory_embeddings", {
+        query_embedding: JSON.stringify(embedding),
+        match_threshold: threshold,
+        match_count: count,
+        p_user_id: userId,
+    });
+    if (error)
+        throw new Error(sanitizeDbError("match memory embeddings", error.message));
+    return (data ?? []);
+}
+/**
+ * Searches memories by HMAC-hashed blind tokens (privacy-preserving keyword search).
+ * Returns memory IDs ranked by number of matching tokens.
+ */
+export async function matchMemoriesByBlindTokens(supabase, tokenHashes, userId, vaultId, count = 20, includeArchived = false) {
+    if (tokenHashes.length === 0)
+        return [];
+    const { data, error } = await supabase.rpc("match_memories_by_blind_tokens", {
+        p_user_id: userId,
+        p_token_hashes: tokenHashes,
+        p_vault_id: vaultId ?? null,
+        p_match_count: count,
+        p_include_archived: includeArchived,
+    });
+    if (error)
+        throw new Error(sanitizeDbError("match memories by blind tokens", error.message));
+    return (data ?? []);
+}
+/**
+ * Searches notes by HMAC-hashed blind tokens (privacy-preserving keyword search).
+ * Returns note IDs ranked by number of matching tokens.
+ */
+export async function matchNotesByBlindTokens(supabase, tokenHashes, userId, vaultId, count = 20, includeTrashed = false) {
+    if (tokenHashes.length === 0)
+        return [];
+    const { data, error } = await supabase.rpc("match_notes_by_blind_tokens", {
+        p_user_id: userId,
+        p_token_hashes: tokenHashes,
+        p_vault_id: vaultId ?? null,
+        p_match_count: count,
+        p_include_trashed: includeTrashed,
+    });
+    if (error)
+        throw new Error(sanitizeDbError("match notes by blind tokens", error.message));
+    return (data ?? []);
+}
+// ─── Batch fetch helper ──────────────────────────────────────────────────────
+export async function getNotesByIds(supabase, userId, noteIds) {
+    if (noteIds.length === 0)
+        return [];
+    const { data, error } = await supabase
+        .from("notes")
+        .select("*")
+        .eq("user_id", userId)
+        .eq("is_trashed", false)
+        .in("id", noteIds);
+    if (error)
+        throw new Error(sanitizeDbError("fetch notes by IDs", error.message));
+    return data ?? [];
+}
+export async function getNoteByImportSource(supabase, userId, vaultId, importSource, importSourceId) {
+    const { data, error } = await supabase
+        .from("notes")
+        .select("*")
+        .eq("user_id", userId)
+        .eq("vault_id", vaultId)
+        .eq("import_source", importSource)
+        .eq("import_source_id", importSourceId)
+        .limit(1);
+    if (error)
+        throw new Error(sanitizeDbError("fetch note by import source", error.message));
+    return (data && data.length > 0 ? data[0] : null);
+}
+export async function getMemoriesByIds(supabase, userId, memoryIds) {
+    if (memoryIds.length === 0)
+        return [];
+    const { data, error } = await supabase
+        .from("memories")
+        .select("*")
+        .eq("user_id", userId)
+        .in("id", memoryIds);
+    if (error)
+        throw new Error(sanitizeDbError("fetch memories by IDs", error.message));
+    return (data ?? []);
+}
+export async function getActiveAgents(supabase, userId, sinceDays = 30, limit = 20) {
+    const since = new Date();
+    since.setDate(since.getDate() - sinceDays);
+    const { data, error } = await supabase
+        .from("memories")
+        .select("agent_id, model_id, updated_at")
+        .eq("user_id", userId)
+        .eq("is_archived", false)
+        .gte("updated_at", since.toISOString())
+        .limit(10_000);
+    if (error)
+        throw new Error(sanitizeDbError("fetch active agents", error.message));
+    // Aggregate in JS since Supabase client doesn't support GROUP BY
+    const agentMap = new Map();
+    for (const row of data ?? []) {
+        const key = `${row.agent_id ?? "unknown"}::${row.model_id ?? "unknown"}`;
+        const existing = agentMap.get(key);
+        if (existing) {
+            existing.count++;
+            if (row.updated_at > existing.lastActiveAt) {
+                existing.lastActiveAt = row.updated_at;
+            }
+        }
+        else {
+            agentMap.set(key, {
+                modelId: row.model_id,
+                count: 1,
+                lastActiveAt: row.updated_at,
+            });
+        }
+    }
+    const agents = [];
+    for (const [key, value] of agentMap) {
+        const agentId = key.split("::")[0];
+        agents.push({
+            agentId,
+            modelId: value.modelId,
+            memoryCount: value.count,
+            lastActiveAt: value.lastActiveAt,
+        });
+    }
+    agents.sort((a, b) => b.lastActiveAt.localeCompare(a.lastActiveAt));
+    return agents.slice(0, limit);
+}
+export async function getMemoryHealthStats(supabase, userId, vaultId) {
+    let query = supabase
+        .from("memories")
+        .select("indexing_status, is_archived")
+        .eq("user_id", userId);
+    if (vaultId)
+        query = query.eq("vault_id", vaultId);
+    query = query.limit(10_000);
+    const { data, error } = await query;
+    if (error)
+        throw new Error(sanitizeDbError("fetch memory health", error.message));
+    const rows = (data ?? []);
+    const stats = { total: rows.length, ready: 0, pending: 0, failed: 0, archived: 0 };
+    for (const row of rows) {
+        if (row.is_archived) {
+            stats.archived++;
+        }
+        else if (row.indexing_status === "ready") {
+            stats.ready++;
+        }
+        else if (row.indexing_status === "pending") {
+            stats.pending++;
+        }
+        else if (row.indexing_status === "failed") {
+            stats.failed++;
+        }
+    }
+    return stats;
+}
+// ─── Entity + relationship helpers ──────────────────────────────────────────
+export async function searchMemoriesByEntity(supabase, userId, entity, limit = 20) {
+    const { data, error } = await supabase
+        .from("memories")
+        .select("*")
+        .eq("user_id", userId)
+        .contains("entities", JSON.stringify([entity]))
+        .order("updated_at", { ascending: false })
+        .limit(limit);
+    if (error)
+        throw new Error(sanitizeDbError("search memories by entity", error.message));
+    return (data ?? []);
+}
+export async function getRelatedMemoriesById(supabase, userId, memoryId, limit = 20) {
+    // Fetch the source memory
+    const source = await getMemory(supabase, userId, memoryId);
+    if (!source)
+        return { source: null, related: [], linkedNotes: [], entityMatches: [], supersessionChain: [] };
+    // Query knowledge_links for this memory (both directions)
+    const links = await getLinksForNode(supabase, userId, "memory", memoryId, {
+        direction: "both",
+        limit: limit * 2,
+    });
+    // Separate linked memory IDs and linked note IDs from knowledge_links
+    const linkedMemoryIds = new Set();
+    const linkedNoteIds = new Set();
+    for (const link of links) {
+        const otherId = link.source_id === memoryId ? link.target_id : link.source_id;
+        const otherType = link.source_id === memoryId ? link.target_type : link.source_type;
+        if (otherType === "memory" && otherId !== memoryId) {
+            linkedMemoryIds.add(otherId);
+        }
+        else if (otherType === "note") {
+            linkedNoteIds.add(otherId);
+        }
+    }
+    // Fallback: also check JSONB related_memory_ids (for links not yet migrated)
+    for (const r of source.related_memory_ids ?? []) {
+        linkedMemoryIds.add(r.memoryId);
+    }
+    // Fallback: also check JSONB source_note_ids
+    for (const noteId of source.source_note_ids ?? []) {
+        linkedNoteIds.add(noteId);
+    }
+    const related = linkedMemoryIds.size > 0
+        ? await getMemoriesByIds(supabase, userId, Array.from(linkedMemoryIds))
+        : [];
+    // Fetch linked notes
+    const linkedNotes = linkedNoteIds.size > 0
+        ? await getNotesByIds(supabase, userId, Array.from(linkedNoteIds))
+        : [];
+    // Entity-based matches (excluding self and already-related)
+    const entities = source.entities ?? [];
+    let entityMatches = [];
+    if (entities.length > 0) {
+        const allEntityResults = [];
+        for (const entity of entities.slice(0, 5)) {
+            const matches = await searchMemoriesByEntity(supabase, userId, entity, limit);
+            allEntityResults.push(...matches);
+        }
+        const seen = new Set([memoryId, ...linkedMemoryIds]);
+        entityMatches = allEntityResults
+            .filter((m) => {
+            if (seen.has(m.id))
+                return false;
+            seen.add(m.id);
+            return true;
+        })
+            .slice(0, limit);
+    }
+    // Supersession chain: follow superseded_by_id forward, and look for memories that point to this one
+    const supersessionChain = [];
+    if (source.superseded_by_id) {
+        const successor = await getMemory(supabase, userId, source.superseded_by_id);
+        if (successor)
+            supersessionChain.push(successor);
+    }
+    const { data: predecessors, error: predError } = await supabase
+        .from("memories")
+        .select("*")
+        .eq("user_id", userId)
+        .eq("superseded_by_id", memoryId)
+        .limit(limit);
+    if (!predError && predecessors) {
+        supersessionChain.push(...predecessors);
+    }
+    return { source, related, linkedNotes, entityMatches, supersessionChain };
+}
+export async function insertKnowledgeLink(supabase, data) {
+    const { data: row, error } = await supabase
+        .from("knowledge_links")
+        .insert({
+        user_id: data.user_id,
+        source_type: data.source_type,
+        source_id: data.source_id,
+        target_type: data.target_type,
+        target_id: data.target_id,
+        relation_type: data.relation_type,
+        encrypted_label: data.encrypted_label ?? null,
+        label_iv: data.label_iv ?? null,
+        is_pending: data.is_pending ?? false,
+        pending_target_hash: data.pending_target_hash ?? null,
+        created_by: data.created_by ?? null,
+    })
+        .select()
+        .single();
+    if (error)
+        throw new Error(sanitizeDbError("insert knowledge link", error.message));
+    return row;
+}
+export async function deleteKnowledgeLink(supabase, linkId, userId) {
+    const { error } = await supabase
+        .from("knowledge_links")
+        .delete()
+        .eq("id", linkId)
+        .eq("user_id", userId);
+    if (error)
+        throw new Error(sanitizeDbError("delete knowledge link", error.message));
+}
+export async function getLinksForNode(supabase, userId, nodeType, nodeId, options) {
+    const direction = options?.direction ?? "both";
+    const limit = options?.limit ?? 100;
+    if (direction === "outgoing") {
+        const { data, error } = await supabase
+            .from("knowledge_links")
+            .select()
+            .eq("user_id", userId)
+            .eq("source_type", nodeType)
+            .eq("source_id", nodeId)
+            .order("created_at", { ascending: false })
+            .limit(limit);
+        if (error)
+            throw new Error(sanitizeDbError("fetch outgoing links", error.message));
+        return (data ?? []);
+    }
+    if (direction === "incoming") {
+        const { data, error } = await supabase
+            .from("knowledge_links")
+            .select()
+            .eq("user_id", userId)
+            .eq("target_type", nodeType)
+            .eq("target_id", nodeId)
+            .order("created_at", { ascending: false })
+            .limit(limit);
+        if (error)
+            throw new Error(sanitizeDbError("fetch incoming links", error.message));
+        return (data ?? []);
+    }
+    // Both directions — two queries merged
+    const [outgoing, incoming] = await Promise.all([
+        supabase
+            .from("knowledge_links")
+            .select()
+            .eq("user_id", userId)
+            .eq("source_type", nodeType)
+            .eq("source_id", nodeId)
+            .order("created_at", { ascending: false })
+            .limit(limit),
+        supabase
+            .from("knowledge_links")
+            .select()
+            .eq("user_id", userId)
+            .eq("target_type", nodeType)
+            .eq("target_id", nodeId)
+            .order("created_at", { ascending: false })
+            .limit(limit),
+    ]);
+    if (outgoing.error)
+        throw new Error(sanitizeDbError("fetch outgoing links", outgoing.error.message));
+    if (incoming.error)
+        throw new Error(sanitizeDbError("fetch incoming links", incoming.error.message));
+    // Deduplicate by link ID (a link could appear in both if source and target are same type)
+    const seen = new Set();
+    const merged = [];
+    for (const row of [...(outgoing.data ?? []), ...(incoming.data ?? [])]) {
+        const link = row;
+        if (!seen.has(link.id)) {
+            seen.add(link.id);
+            merged.push(link);
+        }
+    }
+    return merged.slice(0, limit);
+}
+export async function getBacklinks(supabase, userId, nodeType, nodeId, limit = 50) {
+    return getLinksForNode(supabase, userId, nodeType, nodeId, {
+        direction: "incoming",
+        limit,
+    });
+}
+export async function deleteLinksForNode(supabase, userId, nodeType, nodeId) {
+    // Delete outgoing links
+    const { error: outErr } = await supabase
+        .from("knowledge_links")
+        .delete()
+        .eq("user_id", userId)
+        .eq("source_type", nodeType)
+        .eq("source_id", nodeId);
+    if (outErr)
+        throw new Error(sanitizeDbError("delete outgoing links", outErr.message));
+    // Delete incoming links
+    const { error: inErr } = await supabase
+        .from("knowledge_links")
+        .delete()
+        .eq("user_id", userId)
+        .eq("target_type", nodeType)
+        .eq("target_id", nodeId);
+    if (inErr)
+        throw new Error(sanitizeDbError("delete incoming links", inErr.message));
+}
+export async function bulkInsertKnowledgeLinks(supabase, links) {
+    if (links.length === 0)
+        return 0;
+    const rows = links.map((l) => ({
+        user_id: l.user_id,
+        source_type: l.source_type,
+        source_id: l.source_id,
+        target_type: l.target_type,
+        target_id: l.target_id,
+        relation_type: l.relation_type,
+        encrypted_label: l.encrypted_label ?? null,
+        label_iv: l.label_iv ?? null,
+        is_pending: l.is_pending ?? false,
+        pending_target_hash: l.pending_target_hash ?? null,
+        created_by: l.created_by ?? null,
+    }));
+    // Use upsert with ignoreDuplicates to handle unique constraint violations
+    const { data, error } = await supabase
+        .from("knowledge_links")
+        .upsert(rows, { onConflict: "user_id,source_type,source_id,target_type,target_id,relation_type", ignoreDuplicates: true })
+        .select("id");
+    if (error)
+        throw new Error(sanitizeDbError("bulk insert knowledge links", error.message));
+    return data?.length ?? 0;
+}
+/**
+ * Resolves pending wiki-links by matching stored SHA-256 hashes against
+ * candidate note names. Caller provides a map of hash → noteId.
+ * Use `hashPendingTarget()` from crypto.ts to build the map keys.
+ */
+export async function resolvePendingLinks(supabase, userId, hashToNoteId) {
+    if (hashToNoteId.size === 0)
+        return 0;
+    // Fetch all pending links for this user
+    const { data: pending, error } = await supabase
+        .from("knowledge_links")
+        .select()
+        .eq("user_id", userId)
+        .eq("is_pending", true)
+        .limit(10_000);
+    if (error)
+        throw new Error(sanitizeDbError("fetch pending links", error.message));
+    if (!pending || pending.length === 0)
+        return 0;
+    let resolved = 0;
+    for (const link of pending) {
+        if (!link.pending_target_hash)
+            continue;
+        const noteId = hashToNoteId.get(link.pending_target_hash);
+        if (!noteId)
+            continue;
+        const { error: updateErr } = await supabase
+            .from("knowledge_links")
+            .update({
+            target_id: noteId,
+            target_type: "note",
+            is_pending: false,
+            pending_target_hash: null,
+        })
+            .eq("id", link.id)
+            .eq("user_id", userId);
+        if (!updateErr)
+            resolved++;
+    }
+    return resolved;
+}
+export async function getKnowledgeGraph(supabase, userId, nodeType, nodeId, maxHops = 2, maxNodes = 50) {
+    const { data, error } = await supabase.rpc("get_knowledge_graph", {
+        p_user_id: userId,
+        p_node_type: nodeType,
+        p_node_id: nodeId,
+        p_max_hops: maxHops,
+        p_max_nodes: maxNodes,
+    });
+    if (error)
+        throw new Error(sanitizeDbError("traverse knowledge graph", error.message));
+    return (data ?? []);
+}
+export async function insertAgentMessage(supabase, data) {
+    const { data: row, error } = await supabase
+        .from("agent_messages")
+        .insert({
+        user_id: data.user_id,
+        vault_id: data.vault_id ?? null,
+        sender_type: data.sender_type,
+        sender_id: data.sender_id,
+        target_type: data.target_type,
+        target_id: data.target_id,
+        category: data.category ?? "info",
+        priority: data.priority ?? 3,
+        subject: data.subject ?? null,
+        encrypted_content: data.encrypted_content,
+        content_iv: data.content_iv,
+        expires_at: data.expires_at ?? undefined,
+        metadata: data.metadata ?? null,
+        parent_message_id: data.parent_message_id ?? null,
+        thread_id: data.thread_id ?? null,
+    })
+        .select("*")
+        .single();
+    if (error)
+        throw new Error(sanitizeDbError("insert agent message", error.message));
+    return row;
+}
+/**
+ * Fetch pending messages for a target agent (or broadcast).
+ * Returns priority-sorted, non-expired messages.
+ */
+export async function getPendingMessages(supabase, userId, targetId, limit = 5) {
+    const { data, error } = await supabase
+        .from("agent_messages")
+        .select("*")
+        .eq("user_id", userId)
+        .eq("status", "pending")
+        .or(`target_id.eq.${targetId},target_id.eq.*`)
+        .gte("expires_at", new Date().toISOString())
+        .order("priority", { ascending: false })
+        .order("created_at", { ascending: true })
+        .limit(limit);
+    if (error)
+        throw new Error(sanitizeDbError("fetch pending messages", error.message));
+    return (data ?? []);
+}
+/**
+ * Fetch messages with flexible filtering.
+ */
+export async function getAgentMessages(supabase, userId, targetId, options) {
+    const limit = options?.limit ?? 20;
+    const includeBroadcast = options?.includeBroadcast ?? true;
+    let query = supabase
+        .from("agent_messages")
+        .select("*")
+        .eq("user_id", userId)
+        .order("priority", { ascending: false })
+        .order("created_at", { ascending: false })
+        .limit(limit);
+    if (includeBroadcast) {
+        query = query.or(`target_id.eq.${targetId},target_id.eq.*`);
+    }
+    else {
+        query = query.eq("target_id", targetId);
+    }
+    if (options?.status)
+        query = query.eq("status", options.status);
+    if (options?.category)
+        query = query.eq("category", options.category);
+    if (options?.vaultId)
+        query = query.eq("vault_id", options.vaultId);
+    const { data, error } = await query;
+    if (error)
+        throw new Error(sanitizeDbError("fetch agent messages", error.message));
+    return (data ?? []);
+}
+/**
+ * Bulk-update message status and optional extra fields (e.g. delivered_at, acknowledged_at).
+ */
+export async function bulkUpdateMessageStatus(supabase, messageIds, userId, status, extraFields) {
+    if (messageIds.length === 0)
+        return;
+    const { error } = await supabase
+        .from("agent_messages")
+        .update({
+        status,
+        updated_at: new Date().toISOString(),
+        ...extraFields,
+    })
+        .eq("user_id", userId)
+        .in("id", messageIds);
+    if (error)
+        throw new Error(sanitizeDbError("bulk update message status", error.message));
+}
+/**
+ * Resolve thread ID for a reply. If the parent has a thread_id, use it.
+ * If not, the parent becomes the thread root (set parent's thread_id = parent.id).
+ * Returns the resolved thread_id.
+ */
+export async function resolveThreadId(supabase, userId, parentMessageId) {
+    const { data: parent, error } = await supabase
+        .from("agent_messages")
+        .select("id, thread_id")
+        .eq("id", parentMessageId)
+        .eq("user_id", userId)
+        .single();
+    if (error || !parent)
+        throw new Error("Parent message not found");
+    if (parent.thread_id) {
+        return parent.thread_id;
+    }
+    // Parent becomes the thread root
+    await supabase
+        .from("agent_messages")
+        .update({ thread_id: parent.id, updated_at: new Date().toISOString() })
+        .eq("id", parent.id)
+        .eq("user_id", userId);
+    return parent.id;
+}
+/**
+ * Fetch all messages in a thread, ordered chronologically.
+ */
+export async function getThread(supabase, userId, threadId) {
+    const { data, error } = await supabase
+        .from("agent_messages")
+        .select("*")
+        .eq("user_id", userId)
+        .eq("thread_id", threadId)
+        .order("created_at", { ascending: true });
+    if (error)
+        throw new Error(sanitizeDbError("fetch thread", error.message));
+    return (data ?? []);
+}