@tenex-chat/backend 0.9.1

package/src/services/reports/ReportService.ts

@@ -0,0 +1,440 @@
+import type { AgentInstance } from "@/agents/types";
+import { getNDK } from "@/nostr";
+import { getProjectContext } from "@/services/projects";
+import { logger } from "@/utils/logger";
+import type NDK from "@nostr-dev-kit/ndk";
+import { NDKArticle } from "@nostr-dev-kit/ndk";
+import { nip19 } from "nostr-tools";
+import { articleToReportInfo } from "./articleUtils";
+
+export interface ReportData {
+    slug: string;
+    title: string;
+    summary: string;
+    content: string;
+    hashtags?: string[];
+    memorize?: boolean;
+    memorizeTeam?: boolean;
+}
+
+export interface ReportInfo {
+    id: string;
+    slug: string;
+    title?: string;
+    summary?: string;
+    content?: string;
+    /** Author's hex pubkey (64-character lowercase hex string) */
+    author: string;
+    publishedAt?: number;
+    hashtags?: string[];
+    projectReference?: string;
+    isDeleted?: boolean;
+    isMemorized?: boolean;
+    isMemorizedTeam?: boolean;
+}
+
+export interface ReportSummary {
+    id: string;
+    slug: string;
+    title?: string;
+    summary?: string;
+    author: string;
+    publishedAt?: number;
+    hashtags?: string[];
+}
+
+export interface WriteReportResult {
+    /** The naddr-encoded article ID (e.g., "naddr1...") */
+    encodedId: string;
+    /** The addressable event reference for a-tagging (format: "30023:pubkey:d-tag") */
+    addressableRef: string;
+}
+
+type ReportAuthor = Pick<AgentInstance, "pubkey" | "signer" | "sign">;
+
+/**
+ * Centralized service for managing NDKArticle reports
+ * Handles creation, reading, listing, and deletion of reports
+ */
+export class ReportService {
+    private ndk: NDK;
+
+    constructor(ndk?: NDK) {
+        const ndkInstance = ndk || getNDK();
+        if (!ndkInstance) {
+            throw new Error("NDK instance not available");
+        }
+        this.ndk = ndkInstance;
+    }
+
+    /**
+     * Write or update a report
+     * @returns WriteReportResult containing both the encoded ID and addressable reference
+     */
+    async writeReport(data: ReportData, agent: ReportAuthor): Promise<WriteReportResult> {
+        const projectCtx = getProjectContext();
+        if (!projectCtx?.project) {
+            throw new Error("No project context available");
+        }
+
+        if (!agent.signer) {
+            throw new Error("Agent signer required to publish reports");
+        }
+
+        const article = new NDKArticle(this.ndk);
+
+        // Set the d-tag explicitly to the provided slug
+        article.dTag = data.slug;
+
+        // Set article properties
+        article.title = data.title;
+        article.summary = data.summary;
+        article.content = data.content;
+        article.published_at = Math.floor(Date.now() / 1000);
+
+        // Add hashtags if provided
+        if (data.hashtags && data.hashtags.length > 0) {
+            article.tags.push(...data.hashtags.map((tag) => ["t", tag]));
+        }
+
+        // Add memorize tag if requested - this marks the report for system prompt injection
+        if (data.memorize) {
+            article.tags.push(["t", "memorize"]);
+        }
+
+        // Add memorize_team tag if requested - this marks the report for ALL agents' system prompts
+        if (data.memorizeTeam) {
+            article.tags.push(["t", "memorize_team"]);
+        }
+
+        // Tag the current project using a-tag
+        const projectTagId = projectCtx.project.tagId();
+        article.tags.push(["a", projectTagId]);
+
+        // Note: We don't add a p-tag for the author because the event.pubkey
+        // already identifies who authored/signed the event. P-tags are for
+        // tagging OTHER users (mentions, collaborators, etc.), not yourself.
+
+        // Sign and publish the article
+        await agent.sign(article);
+        await article.publish();
+
+        // Build the addressable reference for a-tagging: "30023:pubkey:d-tag"
+        // NDKArticle is kind 30023
+        const addressableRef = `30023:${agent.pubkey}:${data.slug}`;
+
+        return {
+            encodedId: article.encode(),
+            addressableRef,
+        };
+    }
+
+    /**
+     * Read a report by slug or naddr
+     * First tries the cache, then falls back to NDK fetch if not found.
+     *
+     * Reports are project-scoped: any agent can read any report in the project.
+     * When searching by slug, we filter by project tag (#a) to find reports
+     * belonging to the current project regardless of author.
+     */
+    async readReport(identifier: string): Promise<ReportInfo | null> {
+        const projectCtx = getProjectContext();
+
+        // First, try to find in cache
+        if (identifier.startsWith("naddr1")) {
+            // Decode the naddr to extract slug and author
+            const decoded = nip19.decode(identifier);
+            if (decoded.type === "naddr" && decoded.data.kind === 30023) {
+                const cachedReport = projectCtx.getReport(decoded.data.pubkey, decoded.data.identifier);
+                if (cachedReport) {
+                    logger.debug("📰 Report found in cache (by naddr)", { slug: decoded.data.identifier });
+                    return cachedReport;
+                }
+            }
+        } else {
+            // Try to find by slug across all authors in the project
+            const cachedReport = projectCtx.getReportBySlug(identifier);
+            if (cachedReport) {
+                logger.debug("📰 Report found in cache (by slug)", { slug: identifier });
+                return cachedReport;
+            }
+        }
+
+        // Cache miss - fall back to NDK fetch
+        logger.debug("📰 Report not in cache, fetching from NDK", { identifier });
+
+        let article: NDKArticle | null = null;
+
+        // Check if identifier is an naddr
+        if (identifier.startsWith("naddr1")) {
+            // Decode the naddr to get the event
+            const decoded = nip19.decode(identifier);
+            if (decoded.type === "naddr" && decoded.data.kind === 30023) {
+                // Fetch the specific article
+                const filter = {
+                    kinds: [30023],
+                    authors: [decoded.data.pubkey],
+                    "#d": [decoded.data.identifier],
+                };
+
+                const events = await this.ndk.fetchEvents(filter);
+                if (events.size > 0) {
+                    const event = Array.from(events)[0];
+                    article = NDKArticle.from(event);
+                }
+            }
+        } else {
+            // Treat as a slug - search for articles with this d-tag in the current project
+            // Use project tag (#a) to scope the search to this project
+            const projectTagId = projectCtx.project.tagId();
+            const filter = {
+                kinds: [30023],
+                "#d": [identifier],
+                "#a": [projectTagId],
+            };
+
+            const events = await this.ndk.fetchEvents(filter);
+            if (events.size > 0) {
+                // If multiple reports with same slug exist (different authors),
+                // return the most recently published one
+                const sortedEvents = Array.from(events).sort((a, b) =>
+                    (b.created_at || 0) - (a.created_at || 0)
+                );
+                article = NDKArticle.from(sortedEvents[0]);
+            }
+        }
+
+        if (!article) {
+            return null;
+        }
+
+        const reportInfo = articleToReportInfo(article);
+
+        // Add to cache for future lookups
+        projectCtx.addReport(reportInfo);
+
+        return reportInfo;
+    }
+
+    /**
+     * List reports from project agents
+     * Uses cached reports for fast lookup
+     * @param agentPubkeys Optional array of hex pubkeys to filter by (must be 64-char hex, not npub)
+     */
+    async listReports(agentPubkeys?: string[]): Promise<ReportSummary[]> {
+        const projectCtx = getProjectContext();
+        if (!projectCtx?.project) {
+            throw new Error("No project context available");
+        }
+
+        // Get reports from cache
+        let cachedReports = projectCtx.getAllReports();
+
+        // Filter by agent pubkeys if provided
+        // report.author is already a hex pubkey (see articleUtils.ts)
+        if (agentPubkeys && agentPubkeys.length > 0) {
+            const pubkeySet = new Set(agentPubkeys);
+            cachedReports = cachedReports.filter((report) => pubkeySet.has(report.author));
+        }
+
+        // Filter out deleted reports and convert to ReportSummary
+        const reports: ReportSummary[] = cachedReports
+            .filter((report) => !report.isDeleted)
+            .map((report) => ({
+                id: report.id,
+                slug: report.slug,
+                title: report.title,
+                summary: report.summary,
+                author: report.author,
+                publishedAt: report.publishedAt,
+                hashtags: report.hashtags,
+            }));
+
+        // Sort reports by published date (newest first)
+        reports.sort((a, b) => (b.publishedAt || 0) - (a.publishedAt || 0));
+
+        logger.debug("📰 Listed reports from cache", {
+            total: reports.length,
+            cacheSize: projectCtx.reports.size,
+        });
+
+        return reports;
+    }
+
+    /**
+     * Delete a report by marking it as deleted
+     */
+    async deleteReport(slug: string, agent: ReportAuthor): Promise<string> {
+        const projectCtx = getProjectContext();
+        if (!projectCtx?.project) {
+            throw new Error("No project context available");
+        }
+
+        if (!agent.signer) {
+            throw new Error("Agent signer required to delete reports");
+        }
+
+        // First, find the existing article
+        const filter = {
+            kinds: [30023],
+            authors: [agent.pubkey],
+            "#d": [slug],
+        };
+
+        const events = await this.ndk.fetchEvents(filter);
+        if (events.size === 0) {
+            throw new Error(`No report found with slug: ${slug}`);
+        }
+
+        const event = Array.from(events)[0];
+        const article = NDKArticle.from(event);
+
+        // Create a new version with empty content and deleted tag
+        const deletedArticle = new NDKArticle(this.ndk);
+
+        // Preserve the d-tag
+        deletedArticle.dTag = slug;
+
+        // Set minimal properties
+        deletedArticle.title = article.title || "Deleted Report";
+        deletedArticle.summary = "This report has been deleted";
+        deletedArticle.content = "";
+        deletedArticle.published_at = Math.floor(Date.now() / 1000);
+
+        // Add the deleted tag
+        deletedArticle.tags.push(["deleted"]);
+
+        // Preserve the project tag
+        const projectTagId = projectCtx.project.tagId();
+        deletedArticle.tags.push(["a", projectTagId]);
+
+        // Note: We don't add a p-tag for the author because the event.pubkey
+        // already identifies who authored/signed the event.
+
+        // Sign and publish the updated article
+        await agent.sign(deletedArticle);
+        await deletedArticle.publish();
+
+        logger.info("🗑️ Report marked as deleted", {
+            slug,
+            articleId: deletedArticle.encode(),
+        });
+
+        return deletedArticle.encode();
+    }
+
+    /**
+     * Get all agent pubkeys from the project context
+     */
+    getAllProjectAgentPubkeys(): string[] {
+        const projectCtx = getProjectContext();
+        if (!projectCtx) {
+            return [];
+        }
+
+        const agentPubkeys: string[] = [];
+
+        // Add project manager pubkey
+        if (projectCtx.projectManager) {
+            agentPubkeys.push(projectCtx.projectManager.pubkey);
+        }
+
+        // Add all other agents
+        if (projectCtx.agents) {
+            for (const agent of projectCtx.agents.values()) {
+                if (!agentPubkeys.includes(agent.pubkey)) {
+                    agentPubkeys.push(agent.pubkey);
+                }
+            }
+        }
+
+        return agentPubkeys;
+    }
+
+    /**
+     * Get memorized reports for a specific agent.
+     * Returns reports that have the "memorize" tag authored by that agent.
+     * Uses cached reports for instant lookup.
+     */
+    getMemorizedReportsForAgent(agentPubkey: string): ReportInfo[] {
+        const projectCtx = getProjectContext();
+        if (!projectCtx?.project) {
+            throw new Error("No project context available");
+        }
+
+        // Get memorized reports for this agent from cache
+        const reports = projectCtx.getMemorizedReportsForAgent(agentPubkey);
+
+        // Filter out deleted reports (should already be excluded, but double-check)
+        const activeReports = reports.filter((report) => !report.isDeleted);
+
+        // Sort by published date (oldest first - so they appear in chronological order in the prompt)
+        activeReports.sort((a, b) => (a.publishedAt || 0) - (b.publishedAt || 0));
+
+        logger.debug("📚 Retrieved memorized reports from cache", {
+            agentPubkey: agentPubkey.substring(0, 16),
+            count: activeReports.length,
+            slugs: activeReports.map((r) => r.slug),
+        });
+
+        return activeReports;
+    }
+
+    /**
+     * Get all memorized reports for any agent.
+     * Useful for project-wide memorized knowledge.
+     */
+    getAllMemorizedReports(): ReportInfo[] {
+        const projectCtx = getProjectContext();
+        if (!projectCtx?.project) {
+            throw new Error("No project context available");
+        }
+
+        // Get all memorized reports from cache
+        const reports = projectCtx.getMemorizedReports();
+
+        // Filter out deleted reports
+        const activeReports = reports.filter((report) => !report.isDeleted);
+
+        // Sort by published date (oldest first)
+        activeReports.sort((a, b) => (a.publishedAt || 0) - (b.publishedAt || 0));
+
+        return activeReports;
+    }
+
+    /**
+     * Get team-memorized reports (reports tagged with memorize_team=true).
+     * These reports are injected into ALL agents' system prompts.
+     * Uses cached reports for instant lookup.
+     */
+    getTeamMemorizedReports(): ReportInfo[] {
+        const projectCtx = getProjectContext();
+        if (!projectCtx?.project) {
+            throw new Error("No project context available");
+        }
+
+        // Get team-memorized reports from cache
+        const reports = projectCtx.getTeamMemorizedReports();
+
+        // Filter out deleted reports (should already be excluded, but double-check)
+        const activeReports = reports.filter((report) => !report.isDeleted);
+
+        // Sort by published date (oldest first - so they appear in chronological order in the prompt)
+        activeReports.sort((a, b) => (a.publishedAt || 0) - (b.publishedAt || 0));
+
+        logger.debug("📚 Retrieved team-memorized reports from cache", {
+            count: activeReports.length,
+            slugs: activeReports.map((r) => r.slug),
+        });
+
+        return activeReports;
+    }
+
+    /**
+     * Get report cache statistics for monitoring
+     */
+    getCacheStats(): { total: number; memorized: number; byAuthor: Record<string, number> } {
+        const projectCtx = getProjectContext();
+        return projectCtx.getReportCacheStats();
+    }
+}

package/src/services/reports/articleUtils.ts

@@ -0,0 +1,52 @@
+import type { NDKArticle } from "@nostr-dev-kit/ndk";
+import type { ReportInfo } from "./ReportService";
+
+/**
+ * Centralized utility for converting NDKArticle to ReportInfo.
+ * This is the single source of truth for article-to-report conversion,
+ * used by both ReportService and ProjectContext.
+ */
+export function articleToReportInfo(article: NDKArticle): ReportInfo {
+    // Extract hashtags from tags (excluding the "memorize" and "memorize_team" tags)
+    const hashtags = article.tags
+        .filter((tag: string[]) => tag[0] === "t" && tag[1] !== "memorize" && tag[1] !== "memorize_team")
+        .map((tag: string[]) => tag[1]);
+
+    // Extract project reference if present
+    const projectTag = article.tags.find(
+        (tag: string[]) => tag[0] === "a" && tag[1]?.includes(":31933:")
+    );
+    const projectReference = projectTag ? projectTag[1] : undefined;
+
+    // Check if deleted
+    const isDeleted = article.tags.some((tag: string[]) => tag[0] === "deleted");
+
+    // Check if memorized (for the authoring agent only)
+    const isMemorized = article.tags.some(
+        (tag: string[]) => tag[0] === "t" && tag[1] === "memorize"
+    );
+
+    // Check if team-memorized (for ALL agents in the project)
+    const isMemorizedTeam = article.tags.some(
+        (tag: string[]) => tag[0] === "t" && tag[1] === "memorize_team"
+    );
+
+    // Get author hex pubkey directly from the event
+    // Internal data should always use hex format, not npub
+    const authorPubkey = article.pubkey;
+
+    return {
+        id: `nostr:${article.encode()}`,
+        slug: article.dTag || "",
+        title: article.title,
+        summary: article.summary,
+        content: article.content,
+        author: authorPubkey,
+        publishedAt: article.published_at,
+        hashtags: hashtags.length > 0 ? hashtags : undefined,
+        projectReference,
+        isDeleted,
+        isMemorized,
+        isMemorizedTeam,
+    };
+}

package/src/services/reports/index.ts

@@ -0,0 +1,7 @@
+export type { ReportData, ReportInfo, ReportSummary, WriteReportResult } from "./ReportService";
+export { ReportService } from "./ReportService";
+export { articleToReportInfo } from "./articleUtils";
+export type { LocalReportMetadata } from "./LocalReportStore";
+export { LocalReportStore, getLocalReportStore, createLocalReportStore, InvalidSlugError } from "./LocalReportStore";
+export type { ReportSearchResult, ReportSearchOptions } from "./ReportEmbeddingService";
+export { ReportEmbeddingService, getReportEmbeddingService } from "./ReportEmbeddingService";