@tenex-chat/backend 0.9.1

package/src/tools/implementations/rag_list_collections.ts

@@ -0,0 +1,77 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { RAGService } from "@/services/rag/RAGService";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, executeToolWithErrorHandling } from "@/tools/utils";
+import { tool } from "ai";
+import { z } from "zod";
+
+const ragListCollectionsSchema = z.object({
+    description: z
+        .string()
+        .trim()
+        .min(1, "Description is required and cannot be empty")
+        .describe(
+            "REQUIRED: A clear, concise description of why you're listing collections (5-10 words). Helps provide human-readable context for the operation."
+        ),
+    include_stats: z
+        .boolean()
+        .nullable()
+        .default(false)
+        .describe("Whether to include per-collection statistics (total document count, your document count)"),
+});
+
+/**
+ * Core implementation of listing RAG collections
+ */
+async function executeListCollections(
+    input: z.infer<typeof ragListCollectionsSchema>,
+    context: ToolExecutionContext
+): Promise<ToolResponse> {
+    const { include_stats = false } = input;
+
+    const ragService = RAGService.getInstance();
+
+    if (!include_stats) {
+        const collections = await ragService.listCollections();
+        return {
+            success: true,
+            collections_count: collections.length,
+            collections: collections,
+        };
+    }
+
+    // Fetch stats for all collections with agent attribution
+    // getAllCollectionStats already calls listCollections internally
+    const agentPubkey = context.agent.pubkey;
+    const stats = await ragService.getAllCollectionStats(agentPubkey);
+
+    const collectionsWithStats = stats.map((s) => ({
+        name: s.name,
+        total_documents: s.totalDocCount,
+        agent_documents: s.agentDocCount,
+    }));
+
+    return {
+        success: true,
+        collections_count: stats.length,
+        collections: collectionsWithStats,
+    };
+}
+
+/**
+ * List all available RAG collections
+ */
+export function createRAGListCollectionsTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description: "List all available RAG collections in the system",
+        inputSchema: ragListCollectionsSchema,
+        execute: async (input: unknown) => {
+            return executeToolWithErrorHandling(
+                "rag_list_collections",
+                input as z.infer<typeof ragListCollectionsSchema>,
+                context,
+                executeListCollections
+            );
+        },
+    }) as AISdkTool;
+} 

package/src/tools/implementations/rag_query.ts

@@ -0,0 +1,107 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { type RAGQueryResult, RAGService } from "@/services/rag/RAGService";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, executeToolWithErrorHandling } from "@/tools/utils";
+import { tool } from "ai";
+import { z } from "zod";
+
+const ragQuerySchema = z.object({
+    description: z
+        .string()
+        .trim()
+        .min(1, "Description is required and cannot be empty")
+        .describe(
+            "REQUIRED: A clear, concise description of why you're querying this collection (5-10 words). Helps provide human-readable context for the operation."
+        ),
+    collection: z.string().describe("Name of the collection to query"),
+    query_text: z.string().describe("The text query for semantic search"),
+    top_k: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Number of top results to return (default: 5, range: 1-100)"),
+    include_metadata: z
+        .boolean()
+        .optional()
+        .describe("Whether to include document metadata in results (default: true)"),
+});
+
+/**
+ * Formatted result for tool response
+ */
+interface FormattedQueryResult {
+    rank: number;
+    score: number;
+    content: string;
+    metadata?: Record<string, unknown>;
+    source?: string;
+    id?: string;
+    timestamp?: string;
+}
+
+/**
+ * Format query results for response
+ */
+function formatResults(
+    results: RAGQueryResult[],
+    includeMetadata: boolean
+): FormattedQueryResult[] {
+    return results.map((result, index) => ({
+        rank: index + 1,
+        score: result.score,
+        content:
+            result.document.content.length > 500
+                ? `${result.document.content.substring(0, 500)}...`
+                : result.document.content,
+        ...(includeMetadata && {
+            metadata: result.document.metadata,
+            source: result.document.source,
+            id: result.document.id,
+            timestamp: result.document.timestamp
+                ? new Date(result.document.timestamp).toISOString()
+                : undefined,
+        }),
+    }));
+}
+
+/**
+ * Core implementation of RAG semantic search
+ */
+async function executeQuery(
+    input: z.infer<typeof ragQuerySchema>,
+    _context: ToolExecutionContext
+): Promise<ToolResponse> {
+    const { collection, query_text } = input;
+
+    // Use provided top_k or default to 5
+    // The schema already validates the range (1-100) and integer constraint
+    const topK = input.top_k ?? 5;
+    const includeMetadata = input.include_metadata ?? true;
+
+    const ragService = RAGService.getInstance();
+    const results = await ragService.query(collection, query_text, topK);
+
+    return {
+        success: true,
+        collection: collection,
+        query: query_text,
+        results_count: results.length,
+        results: formatResults(results, includeMetadata),
+    };
+}
+
+/**
+ * Query a RAG collection using semantic search
+ */
+export function createRAGQueryTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "Perform semantic search on a RAG collection. Returns the most relevant documents based on vector similarity to the query.",
+        inputSchema: ragQuerySchema,
+        execute: async (input: unknown) => {
+            return executeToolWithErrorHandling("rag_query", input as z.infer<typeof ragQuerySchema>, context, executeQuery);
+        },
+    }) as AISdkTool;
+} 

package/src/tools/implementations/rag_subscription_create.ts

@@ -0,0 +1,105 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { RagSubscriptionService } from "@/services/rag/RagSubscriptionService";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, executeToolWithErrorHandling } from "@/tools/utils";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Schema for creating a RAG subscription
+ */
+const ragSubscriptionCreateSchema = z.object({
+    subscriptionId: z
+        .string()
+        .describe('Unique identifier for the subscription (e.g., "ndk-updates", "market-data")'),
+    mcpServerId: z
+        .string()
+        .describe(
+            'The ID of the installed MCP tool/server providing the resource (e.g., "nostr-provider")'
+        ),
+    resourceUri: z
+        .string()
+        .describe(
+            'The MCP resource URI to subscribe to (e.g., "nostr://feed/pubkey/kinds", "file:///path/to/file"). ' +
+                "This must be an actual resource URI, NOT a tool name. If using a resource template, " +
+                "you must first expand it with parameters to get the actual URI."
+        ),
+    ragCollection: z.string().describe("Name of the RAG collection where data will be stored"),
+    description: z.string().describe("Human-readable description of what this subscription does"),
+});
+
+/**
+ * Core implementation of creating a RAG subscription
+ */
+async function executeCreateSubscription(
+    input: z.infer<typeof ragSubscriptionCreateSchema>,
+    context: ToolExecutionContext
+): Promise<ToolResponse> {
+    const { subscriptionId, mcpServerId, resourceUri, ragCollection, description } = input;
+
+    // Mandate agent identity - no compromises
+    if (!context.agent?.pubkey) {
+        throw new Error(
+            "Agent identity is required. Cannot create subscription without valid agent pubkey."
+        );
+    }
+    const agentPubkey = context.agent.pubkey;
+
+    // Get the service instance (already initialized at startup)
+    const subscriptionService = RagSubscriptionService.getInstance();
+
+    // Create the subscription
+    const subscription = await subscriptionService.createSubscription(
+        subscriptionId,
+        agentPubkey,
+        mcpServerId,
+        resourceUri,
+        ragCollection,
+        description
+    );
+
+    return {
+        success: true,
+        message: `Successfully created subscription '${subscriptionId}'`,
+        subscription: {
+            id: subscription.subscriptionId,
+            mcpServer: subscription.mcpServerId,
+            resource: subscription.resourceUri,
+            collection: subscription.ragCollection,
+            status: subscription.status,
+            description: subscription.description,
+        },
+    };
+}
+
+/**
+ * Create a persistent RAG subscription to stream data from MCP resources
+ *
+ * This tool creates a persistent subscription that:
+ * - Connects to an installed MCP server/tool
+ * - Subscribes to a specific resource
+ * - Automatically pipes updates to a RAG collection
+ * - Persists across TENEX restarts
+ *
+ * Example use cases:
+ * - Subscribe to a changelog from an NDK server
+ * - Stream market data into a trading knowledge base
+ * - Collect social media updates for analysis
+ *
+ * The subscription will remain active until explicitly deleted.
+ */
+export function createRAGSubscriptionCreateTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "Create a persistent subscription to stream data from an MCP resource into a RAG collection. The subscription will automatically pipe all updates from the specified resource to the RAG collection and persist across restarts.",
+        inputSchema: ragSubscriptionCreateSchema,
+        execute: async (input: unknown) => {
+            return executeToolWithErrorHandling(
+                "rag_subscription_create",
+                input as z.infer<typeof ragSubscriptionCreateSchema>,
+                context,
+                executeCreateSubscription
+            );
+        },
+    }) as AISdkTool;
+} 

package/src/tools/implementations/rag_subscription_delete.ts

@@ -0,0 +1,80 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { RagSubscriptionService } from "@/services/rag/RagSubscriptionService";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, executeToolWithErrorHandling } from "@/tools/utils";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Schema for deleting a RAG subscription
+ */
+const ragSubscriptionDeleteSchema = z.object({
+    subscriptionId: z.string().describe("The ID of the subscription to delete"),
+});
+
+/**
+ * Core implementation of deleting a RAG subscription
+ */
+async function executeDeleteSubscription(
+    input: z.infer<typeof ragSubscriptionDeleteSchema>,
+    context: ToolExecutionContext
+): Promise<ToolResponse> {
+    const { subscriptionId } = input;
+
+    // Mandate agent identity - no compromises
+    if (!context.agent?.pubkey) {
+        throw new Error(
+            "Agent identity is required. Cannot delete subscription without valid agent pubkey."
+        );
+    }
+    const agentPubkey = context.agent.pubkey;
+
+    // Get the service instance (already initialized at startup)
+    const subscriptionService = RagSubscriptionService.getInstance();
+
+    // Delete the subscription
+    const deleted = await subscriptionService.deleteSubscription(subscriptionId, agentPubkey);
+
+    if (!deleted) {
+        return {
+            success: false,
+            message: `Subscription '${subscriptionId}' not found or you don't have permission to delete it`,
+            error: "SUBSCRIPTION_NOT_FOUND",
+        };
+    }
+
+    return {
+        success: true,
+        message: `Successfully deleted subscription '${subscriptionId}'`,
+        subscriptionId: subscriptionId,
+    };
+}
+
+/**
+ * Delete a RAG subscription and stop data streaming
+ *
+ * This will:
+ * - Stop receiving updates from the MCP resource
+ * - Remove the subscription from persistent storage
+ * - Clean up any associated listeners
+ *
+ * Note: Previously ingested documents remain in the RAG collection.
+ * Only the subscription itself is deleted, not the data.
+ *
+ * You can only delete subscriptions that belong to your agent.
+ */
+export function createRAGSubscriptionDeleteTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "Delete a RAG subscription to stop streaming data from an MCP resource. Previously ingested documents will remain in the RAG collection.",
+        inputSchema: ragSubscriptionDeleteSchema,
+        execute: async (input: unknown) => {
+            return executeToolWithErrorHandling(
+                "rag_subscription_delete",
+                input as z.infer<typeof ragSubscriptionDeleteSchema>,
+                context,
+                executeDeleteSubscription
+            );
+        },
+    }) as AISdkTool;
+} 

package/src/tools/implementations/rag_subscription_get.ts

@@ -0,0 +1,123 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { RagSubscriptionService } from "@/services/rag/RagSubscriptionService";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, executeToolWithErrorHandling } from "@/tools/utils";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Schema for getting a specific RAG subscription
+ */
+const ragSubscriptionGetSchema = z.object({
+    subscriptionId: z.string().describe("The ID of the subscription to retrieve"),
+});
+
+/**
+ * Calculate uptime for a subscription
+ */
+function calculateUptime(createdAt: number, status: string): string {
+    if (status !== "RUNNING") {
+        return "N/A";
+    }
+
+    const uptimeMs = Date.now() - createdAt;
+    const days = Math.floor(uptimeMs / (1000 * 60 * 60 * 24));
+    const hours = Math.floor((uptimeMs % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
+    const minutes = Math.floor((uptimeMs % (1000 * 60 * 60)) / (1000 * 60));
+
+    const parts = [];
+    if (days > 0) parts.push(`${days}d`);
+    if (hours > 0) parts.push(`${hours}h`);
+    if (minutes > 0 || parts.length === 0) parts.push(`${minutes}m`);
+
+    return parts.join(" ");
+}
+
+/**
+ * Core implementation of getting a RAG subscription
+ */
+async function executeGetSubscription(
+    input: z.infer<typeof ragSubscriptionGetSchema>,
+    context: ToolExecutionContext
+): Promise<ToolResponse> {
+    const { subscriptionId } = input;
+
+    // Mandate agent identity - no compromises
+    if (!context.agent?.pubkey) {
+        throw new Error(
+            "Agent identity is required. Cannot retrieve subscription without valid agent pubkey."
+        );
+    }
+    const agentPubkey = context.agent.pubkey;
+
+    // Get the service instance (already initialized at startup)
+    const subscriptionService = RagSubscriptionService.getInstance();
+
+    // Get the subscription
+    const subscription = await subscriptionService.getSubscription(subscriptionId, agentPubkey);
+
+    if (!subscription) {
+        return {
+            success: false,
+            message: `Subscription '${subscriptionId}' not found`,
+            error: "SUBSCRIPTION_NOT_FOUND",
+        };
+    }
+
+    // Calculate uptime
+    const uptime = calculateUptime(subscription.createdAt, subscription.status);
+
+    // Format detailed response
+    const details = {
+        id: subscription.subscriptionId,
+        description: subscription.description,
+        status: subscription.status,
+        configuration: {
+            mcpServer: subscription.mcpServerId,
+            resource: subscription.resourceUri,
+            collection: subscription.ragCollection,
+        },
+        metrics: {
+            documentsProcessed: subscription.documentsProcessed,
+            uptime: uptime,
+            createdAt: new Date(subscription.createdAt).toISOString(),
+            updatedAt: new Date(subscription.updatedAt).toISOString(),
+        },
+        lastDocumentSnippet: subscription.lastDocumentIngested || null,
+        lastError: subscription.lastError || null,
+    };
+
+    return {
+        success: true,
+        message: `Retrieved details for subscription '${subscriptionId}'`,
+        subscription: details,
+    };
+}
+
+/**
+ * Get detailed information about a specific RAG subscription
+ *
+ * Returns comprehensive details including:
+ * - Current status and configuration
+ * - Processing metrics (documents processed, uptime)
+ * - Last ingested document snippet
+ * - Error information if any
+ * - Timestamps for creation and last update
+ *
+ * Use this to monitor the health and progress of a specific subscription.
+ */
+export function createRAGSubscriptionGetTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "Get detailed status and metrics for a specific RAG subscription, including processing statistics and the last ingested document snippet.",
+        inputSchema: ragSubscriptionGetSchema,
+        execute: async (input: unknown) => {
+            return executeToolWithErrorHandling(
+                "rag_subscription_get",
+                input as z.infer<typeof ragSubscriptionGetSchema>,
+                context,
+                executeGetSubscription
+            );
+        },
+    }) as AISdkTool;
+} 

package/src/tools/implementations/rag_subscription_list.ts

@@ -0,0 +1,128 @@
+import type { ToolExecutionContext } from "@/tools/types";
+import { RagSubscriptionService } from "@/services/rag/RagSubscriptionService";
+import type { AISdkTool } from "@/tools/types";
+import { type ToolResponse, executeToolWithErrorHandling } from "@/tools/utils";
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Core implementation of listing RAG subscriptions
+ */
+async function executeListSubscriptions(
+    _input: unknown,
+    context: ToolExecutionContext
+): Promise<ToolResponse> {
+    // Mandate agent identity - no compromises
+    if (!context.agent?.pubkey) {
+        throw new Error(
+            "Agent identity is required. Cannot list subscriptions without valid agent pubkey."
+        );
+    }
+    const agentPubkey = context.agent.pubkey;
+
+    // Get the service instance (already initialized at startup)
+    const subscriptionService = RagSubscriptionService.getInstance();
+
+    // List subscriptions for this agent
+    const subscriptions = await subscriptionService.listSubscriptions(agentPubkey);
+
+    // Single-pass statistics calculation with proper efficiency
+    const statistics = subscriptions.reduce(
+        (acc, sub) => {
+            // Format subscription while calculating statistics
+            acc.formattedSubscriptions.push({
+                id: sub.subscriptionId,
+                mcpServer: sub.mcpServerId,
+                resource: sub.resourceUri,
+                collection: sub.ragCollection,
+                status: sub.status,
+                documentsProcessed: sub.documentsProcessed,
+                description: sub.description,
+                createdAt: new Date(sub.createdAt).toISOString(),
+                updatedAt: new Date(sub.updatedAt).toISOString(),
+                lastError: sub.lastError,
+            });
+
+            // Update counters in single pass
+            acc.total++;
+            acc.totalDocumentsProcessed += sub.documentsProcessed;
+
+            switch (sub.status) {
+                case "RUNNING":
+                    acc.running++;
+                    break;
+                case "ERROR":
+                    acc.error++;
+                    break;
+                case "STOPPED":
+                    acc.stopped++;
+                    break;
+            }
+
+            return acc;
+        },
+        {
+            formattedSubscriptions: [] as Array<{
+                id: string;
+                mcpServer: string;
+                resource: string;
+                collection: string;
+                status: string;
+                documentsProcessed: number;
+                description: string;
+                createdAt: string;
+                updatedAt: string;
+                lastError?: string;
+            }>,
+            total: 0,
+            running: 0,
+            error: 0,
+            stopped: 0,
+            totalDocumentsProcessed: 0,
+        }
+    );
+
+    return {
+        success: true,
+        message: `Found ${statistics.total} subscription(s)`,
+        subscriptions: statistics.formattedSubscriptions,
+        statistics: {
+            total: statistics.total,
+            running: statistics.running,
+            error: statistics.error,
+            stopped: statistics.stopped,
+            totalDocumentsProcessed: statistics.totalDocumentsProcessed,
+        },
+    };
+}
+
+/**
+ * List all active RAG subscriptions for the current agent
+ *
+ * Returns a list of all subscriptions including:
+ * - Subscription ID and description
+ * - MCP server and resource information
+ * - Target RAG collection
+ * - Current status (RUNNING, ERROR, STOPPED)
+ * - Number of documents processed
+ * - Timestamps and error information
+ *
+ * Also provides aggregate statistics about all subscriptions.
+ */
+const ragSubscriptionListSchema = z.object({});
+
+export function createRAGSubscriptionListTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description:
+            "List all active RAG subscriptions for the current agent, showing their status, configuration, and statistics.",
+        inputSchema: ragSubscriptionListSchema,
+        execute: async (input: unknown) => {
+            return executeToolWithErrorHandling(
+                "rag_subscription_list",
+                input,
+                context,
+                executeListSubscriptions
+            );
+        },
+    }) as AISdkTool;
+} 

package/src/tools/implementations/report_delete.ts

@@ -0,0 +1,79 @@
+import type { AISdkTool, ToolExecutionContext } from "@/tools/types";
+import { ReportService } from "@/services/reports";
+import { getReportEmbeddingService } from "@/services/reports/ReportEmbeddingService";
+import { getProjectContext } from "@/services/projects";
+import { logger } from "@/utils/logger";
+import { tool } from "ai";
+import { z } from "zod";
+
+const reportDeleteSchema = z.object({
+    slug: z.string().describe("The slug identifier (d-tag) of the report to delete"),
+});
+
+type ReportDeleteInput = z.infer<typeof reportDeleteSchema>;
+
+interface ReportDeleteOutput {
+    success: boolean;
+    articleId: string;
+    slug: string;
+    message: string;
+}
+
+/**
+ * Core implementation of report deletion functionality
+ */
+async function executeReportDelete(
+    input: ReportDeleteInput,
+    context: ToolExecutionContext
+): Promise<ReportDeleteOutput> {
+    const { slug } = input;
+
+    logger.info("🗑️ Deleting report", {
+        slug,
+        agent: context.agent.name,
+    });
+
+    const reportService = new ReportService();
+
+    const articleId = await reportService.deleteReport(slug, context.agent);
+
+    // Remove from RAG index
+    try {
+        const projectCtx = getProjectContext();
+        const projectTagId = projectCtx.project.tagId();
+        const reportEmbeddingService = getReportEmbeddingService();
+        await reportEmbeddingService.removeReport(slug, projectTagId);
+    } catch (ragError) {
+        // Don't fail deletion if RAG cleanup fails
+        const ragMessage = ragError instanceof Error ? ragError.message : String(ragError);
+        logger.warn("Failed to remove report from RAG", { slug, error: ragMessage });
+    }
+
+    logger.info("✅ Report deleted successfully", {
+        slug,
+        articleId,
+        agent: context.agent.name,
+    });
+
+    return {
+        success: true,
+        articleId: `nostr:${articleId}`,
+        slug,
+        message: `Report "${slug}" marked as deleted`,
+    };
+}
+
+/**
+ * Create an AI SDK tool for deleting reports
+ */
+export function createReportDeleteTool(context: ToolExecutionContext): AISdkTool {
+    return tool({
+        description: "Mark an NDKArticle report as deleted",
+
+        inputSchema: reportDeleteSchema,
+
+        execute: async (input: ReportDeleteInput) => {
+            return await executeReportDelete(input, context);
+        },
+    }) as AISdkTool;
+}