@tenex-chat/backend 0.9.1

package/src/services/scheduling/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Scheduling service error types
+ */
+
+/**
+ * Error thrown when attempting to start a project that is already running.
+ * This is a non-fatal condition during auto-boot - the project is already available.
+ */
+export class ProjectAlreadyRunningError extends Error {
+    constructor(public readonly projectId: string) {
+        super(`Project already running: ${projectId}`);
+        this.name = "ProjectAlreadyRunningError";
+    }
+}

package/src/services/scheduling/index.ts

@@ -0,0 +1,7 @@
+export { SchedulerService } from "./SchedulerService";
+export type {
+    ScheduledTask,
+    ProjectBootHandler,
+    ProjectStateResolver,
+    TargetPubkeyResolver,
+} from "./SchedulerService";

package/src/services/scheduling/utils.ts

@@ -0,0 +1,77 @@
+/**
+ * Utility functions for scheduling operations.
+ * Shared between the scheduler service and tools.
+ */
+
+/**
+ * Parse a relative time string (e.g., "5m", "2h", "3d") into milliseconds.
+ * Supported formats:
+ * - Xm: X minutes
+ * - Xh: X hours
+ * - Xd: X days
+ *
+ * @param delay - The delay string to parse
+ * @returns The delay in milliseconds, or null if the format is invalid
+ */
+export function parseRelativeDelay(delay: string): number | null {
+    const match = delay.match(/^(\d+(?:\.\d+)?)\s*(m|h|d)$/i);
+    if (!match) {
+        return null;
+    }
+
+    const value = Number.parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+
+    switch (unit) {
+        case "m":
+            return value * 60 * 1000; // minutes to ms
+        case "h":
+            return value * 60 * 60 * 1000; // hours to ms
+        case "d":
+            return value * 24 * 60 * 60 * 1000; // days to ms
+        default:
+            return null;
+    }
+}
+
+/**
+ * Format a delay string in human-readable form.
+ *
+ * @param delay - The delay string (e.g., "5m", "2h", "3d")
+ * @returns A human-readable string (e.g., "5 minutes", "2 hours", "3 days")
+ */
+export function formatDelay(delay: string): string {
+    const match = delay.match(/^(\d+(?:\.\d+)?)\s*(m|h|d)$/i);
+    if (!match) return delay;
+
+    const value = Number.parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+
+    const unitNames: Record<string, string> = {
+        m: value === 1 ? "minute" : "minutes",
+        h: value === 1 ? "hour" : "hours",
+        d: value === 1 ? "day" : "days",
+    };
+
+    return `${value} ${unitNames[unit]}`;
+}
+
+/**
+ * Format an ISO timestamp in a human-readable format with UTC timezone.
+ * Handles invalid dates gracefully.
+ *
+ * @param isoString - The ISO date string to format
+ * @returns A formatted string like "Jan 30, 2024, 10:00 AM UTC" or "Invalid date" for invalid input
+ */
+export function formatExecuteAt(isoString: string): string {
+    const date = new Date(isoString);
+    if (Number.isNaN(date.getTime())) {
+        return "Invalid date";
+    }
+
+    return `${date.toLocaleString("en-US", {
+        dateStyle: "medium",
+        timeStyle: "short",
+        timeZone: "UTC",
+    })} UTC`;
+}

package/src/services/search/SearchProviderRegistry.ts

@@ -0,0 +1,78 @@
+/**
+ * SearchProviderRegistry - Registry for search providers.
+ *
+ * Holds all registered search providers and provides lookup by name.
+ * Providers are registered during application bootstrap.
+ */
+
+import type { SearchProvider } from "./types";
+
+export class SearchProviderRegistry {
+    private static instance: SearchProviderRegistry | null = null;
+    private providers = new Map<string, SearchProvider>();
+
+    private constructor() {}
+
+    public static getInstance(): SearchProviderRegistry {
+        if (!SearchProviderRegistry.instance) {
+            SearchProviderRegistry.instance = new SearchProviderRegistry();
+        }
+        return SearchProviderRegistry.instance;
+    }
+
+    /**
+     * Register a search provider.
+     * @param provider - The search provider to register
+     */
+    public register(provider: SearchProvider): void {
+        this.providers.set(provider.name, provider);
+    }
+
+    /**
+     * Get a provider by name.
+     */
+    public get(name: string): SearchProvider | undefined {
+        return this.providers.get(name);
+    }
+
+    /**
+     * Get all registered providers.
+     */
+    public getAll(): SearchProvider[] {
+        return Array.from(this.providers.values());
+    }
+
+    /**
+     * Get provider names.
+     */
+    public getNames(): string[] {
+        return Array.from(this.providers.keys());
+    }
+
+    /**
+     * Check if a provider is registered.
+     */
+    public has(name: string): boolean {
+        return this.providers.has(name);
+    }
+
+    /**
+     * Get providers filtered by collection names.
+     * If no names provided, returns all providers.
+     */
+    public getByNames(names?: string[]): SearchProvider[] {
+        if (!names || names.length === 0) {
+            return this.getAll();
+        }
+        return names
+            .map((name) => this.providers.get(name))
+            .filter((p): p is SearchProvider => p !== undefined);
+    }
+
+    /**
+     * Reset singleton (for testing).
+     */
+    public static resetInstance(): void {
+        SearchProviderRegistry.instance = null;
+    }
+}

package/src/services/search/UnifiedSearchService.ts

@@ -0,0 +1,218 @@
+/**
+ * UnifiedSearchService - Orchestrates search across all RAG collections.
+ *
+ * Queries all registered search providers in parallel, merges results
+ * by relevance score, and optionally applies LLM extraction when a
+ * prompt is provided.
+ *
+ * Key behaviors:
+ * - Parallel queries across all providers
+ * - Graceful degradation: one collection failure doesn't block others
+ * - Project-scoped isolation via projectId
+ * - Optional LLM extraction with configurable prompt
+ */
+
+import { logger } from "@/utils/logger";
+import { config as configService } from "@/services/ConfigService";
+import { SearchProviderRegistry } from "./SearchProviderRegistry";
+import type { SearchOptions, SearchResult, UnifiedSearchOutput } from "./types";
+
+/** Default search parameters */
+const DEFAULT_LIMIT = 10;
+const DEFAULT_MIN_SCORE = 0.3;
+
+export class UnifiedSearchService {
+    private static instance: UnifiedSearchService | null = null;
+    private registry: SearchProviderRegistry;
+
+    private constructor() {
+        this.registry = SearchProviderRegistry.getInstance();
+    }
+
+    public static getInstance(): UnifiedSearchService {
+        if (!UnifiedSearchService.instance) {
+            UnifiedSearchService.instance = new UnifiedSearchService();
+        }
+        return UnifiedSearchService.instance;
+    }
+
+    /**
+     * Perform a unified search across all (or selected) collections.
+     */
+    public async search(options: SearchOptions): Promise<UnifiedSearchOutput> {
+        const {
+            query,
+            projectId,
+            limit = DEFAULT_LIMIT,
+            minScore = DEFAULT_MIN_SCORE,
+            prompt,
+            collections,
+        } = options;
+
+        logger.info("🔍 [UnifiedSearch] Starting search", {
+            query,
+            projectId,
+            limit,
+            minScore,
+            prompt: prompt ? `${prompt.substring(0, 50)}...` : undefined,
+            collections: collections || "all",
+        });
+
+        // Get providers to search
+        const providers = this.registry.getByNames(collections);
+        if (providers.length === 0) {
+            logger.warn("[UnifiedSearch] No search providers available");
+            return {
+                success: true,
+                results: [],
+                totalResults: 0,
+                query,
+                collectionsSearched: [],
+                warnings: ["No search collections are available. RAG may not be initialized."],
+            };
+        }
+
+        // Query all providers in parallel with graceful degradation
+        const searchPromises = providers.map(async (provider) => {
+            try {
+                const results = await provider.search(query, projectId, limit, minScore);
+                return { name: provider.name, results, error: null };
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.warn(`[UnifiedSearch] Provider '${provider.name}' failed`, {
+                    error: message,
+                });
+                return { name: provider.name, results: [] as SearchResult[], error: message };
+            }
+        });
+
+        const providerResults = await Promise.all(searchPromises);
+
+        // Collect results and track errors
+        const allResults: SearchResult[] = [];
+        const collectionsSearched: string[] = [];
+        const collectionsErrored: string[] = [];
+        const warnings: string[] = [];
+
+        for (const { name, results, error } of providerResults) {
+            if (error) {
+                collectionsErrored.push(name);
+                warnings.push(`Collection '${name}' search failed: ${error}`);
+            } else {
+                collectionsSearched.push(name);
+                allResults.push(...results);
+            }
+        }
+
+        // Sort all results by relevance score (highest first)
+        allResults.sort((a, b) => b.relevanceScore - a.relevanceScore);
+
+        // Apply overall limit
+        const limitedResults = allResults.slice(0, limit);
+
+        // Optional LLM extraction when prompt is provided
+        let extraction: string | undefined;
+        if (prompt && limitedResults.length > 0) {
+            extraction = await this.extractWithLLM(query, prompt, limitedResults);
+        }
+
+        logger.info("✅ [UnifiedSearch] Search complete", {
+            query,
+            totalResults: limitedResults.length,
+            collectionsSearched,
+            collectionsErrored: collectionsErrored.length > 0 ? collectionsErrored : undefined,
+            hasExtraction: !!extraction,
+        });
+
+        return {
+            success: true,
+            results: limitedResults,
+            totalResults: limitedResults.length,
+            query,
+            collectionsSearched,
+            ...(collectionsErrored.length > 0 && { collectionsErrored }),
+            ...(warnings.length > 0 && { warnings }),
+            ...(extraction && { extraction }),
+        };
+    }
+
+    /**
+     * Use a fast/cheap LLM to extract focused information from search results.
+     *
+     * Uses the 'summarization' config if available, falls back to 'search',
+     * then falls back to the default LLM config.
+     */
+    private async extractWithLLM(
+        query: string,
+        prompt: string,
+        results: SearchResult[]
+    ): Promise<string | undefined> {
+        try {
+            // Try to find a fast/cheap model config
+            const configName = this.getExtractionModelConfig();
+            if (!configName) {
+                logger.debug("[UnifiedSearch] No LLM config available for extraction");
+                return undefined;
+            }
+
+            const llmService = configService.createLLMService(configName);
+
+            // Build context from search results
+            const resultContext = results
+                .map((r, i) => {
+                    const parts = [`[${i + 1}] (${r.source}) ${r.title}`];
+                    if (r.summary) parts.push(`   ${r.summary}`);
+                    if (r.tags?.length) parts.push(`   Tags: ${r.tags.join(", ")}`);
+                    return parts.join("\n");
+                })
+                .join("\n\n");
+
+            const systemPrompt =
+                "You are a search result extraction assistant. " +
+                "Given search results and a specific prompt, extract and synthesize " +
+                "the most relevant information. Be concise and focused. " +
+                "Reference results by their number when citing information.";
+
+            const userPrompt =
+                `Search query: "${query}"\n\n` +
+                `Extraction prompt: ${prompt}\n\n` +
+                `Search results:\n${resultContext}\n\n` +
+                "Based on these search results, provide a focused extraction addressing the prompt.";
+
+            const result = await llmService.generateText([
+                { role: "system", content: systemPrompt },
+                { role: "user", content: userPrompt },
+            ]);
+
+            return result.text;
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn("[UnifiedSearch] LLM extraction failed", { error: message });
+            return undefined;
+        }
+    }
+
+    /**
+     * Get the best available LLM config name for extraction.
+     * Priority: search config (typically fast/cheap) > undefined (createLLMService uses default)
+     */
+    private getExtractionModelConfig(): string | undefined {
+        try {
+            // Try search config first (typically configured as a fast/cheap model)
+            const search = configService.getSearchModelName();
+            if (search) return search;
+        } catch {
+            // Not available
+        }
+
+        // Return undefined - createLLMService will use default config with fallback
+        return undefined;
+    }
+
+    /**
+     * Reset singleton (for testing).
+     */
+    public static resetInstance(): void {
+        UnifiedSearchService.instance = null;
+    }
+}

package/src/services/search/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Unified Search Module
+ *
+ * Provides cross-collection semantic search across reports,
+ * conversations, and lessons within project boundaries.
+ */
+
+export { buildProjectFilter } from "./projectFilter";
+export { SearchProviderRegistry } from "./SearchProviderRegistry";
+export { UnifiedSearchService } from "./UnifiedSearchService";
+export type {
+    SearchOptions,
+    SearchProvider,
+    SearchResult,
+    UnifiedSearchOutput,
+} from "./types";
+
+// Providers
+export { ReportSearchProvider } from "./providers/ReportSearchProvider";
+export { ConversationSearchProvider } from "./providers/ConversationSearchProvider";
+export { LessonSearchProvider } from "./providers/LessonSearchProvider";
+
+import { SearchProviderRegistry } from "./SearchProviderRegistry";
+import { ReportSearchProvider } from "./providers/ReportSearchProvider";
+import { ConversationSearchProvider } from "./providers/ConversationSearchProvider";
+import { LessonSearchProvider } from "./providers/LessonSearchProvider";
+
+/**
+ * Bootstrap all search providers.
+ * Call this during application initialization after RAG services are available.
+ * Idempotent - safe to call multiple times.
+ */
+export function bootstrapSearchProviders(): void {
+    const registry = SearchProviderRegistry.getInstance();
+
+    if (!registry.has("reports")) {
+        registry.register(new ReportSearchProvider());
+    }
+
+    if (!registry.has("conversations")) {
+        registry.register(new ConversationSearchProvider());
+    }
+
+    if (!registry.has("lessons")) {
+        registry.register(new LessonSearchProvider());
+    }
+}

package/src/services/search/projectFilter.ts

@@ -0,0 +1,22 @@
+/**
+ * Centralized SQL project filter for RAG queries.
+ *
+ * Shared utility for the `metadata LIKE '%"projectId":"..."'` SQL prefilter pattern
+ * used across all project-scoped RAG collections (reports, conversations, lessons).
+ *
+ * Applied DURING vector search (prefilter) to ensure proper project isolation.
+ */
+
+/**
+ * Build a SQL prefilter string for project isolation in LanceDB queries.
+ *
+ * @param projectId - The project ID to filter by. Pass 'ALL' or undefined to skip filtering.
+ * @returns SQL filter string or undefined if no filtering needed.
+ */
+export function buildProjectFilter(projectId?: string): string | undefined {
+    if (!projectId || projectId.toLowerCase() === "all") {
+        return undefined;
+    }
+    const escapedProjectId = projectId.replace(/'/g, "''");
+    return `metadata LIKE '%"projectId":"${escapedProjectId}"%'`;
+}

package/src/services/search/providers/ConversationSearchProvider.ts

@@ -0,0 +1,48 @@
+/**
+ * ConversationSearchProvider - Search provider for conversations.
+ *
+ * Queries the `conversation_embeddings` RAG collection via ConversationEmbeddingService.
+ */
+
+import { logger } from "@/utils/logger";
+import { getConversationEmbeddingService } from "@/conversations/search/embeddings";
+import type { SearchProvider, SearchResult } from "../types";
+
+export class ConversationSearchProvider implements SearchProvider {
+    readonly name = "conversations";
+    readonly description = "Past conversation threads and discussions";
+
+    async search(
+        query: string,
+        projectId: string,
+        limit: number,
+        minScore: number
+    ): Promise<SearchResult[]> {
+        const conversationEmbeddingService = getConversationEmbeddingService();
+
+        const results = await conversationEmbeddingService.semanticSearch(query, {
+            limit,
+            minScore,
+            projectId,
+        });
+
+        logger.debug("[ConversationSearchProvider] Search complete", {
+            query,
+            projectId,
+            found: results.length,
+        });
+
+        return results.map((result) => ({
+            source: this.name,
+            id: result.conversationId,
+            projectId: result.projectId || projectId,
+            relevanceScore: result.relevanceScore,
+            title: result.title || "",
+            summary: result.summary || "",
+            createdAt: result.createdAt,
+            updatedAt: result.lastActivity,
+            retrievalTool: "conversation_get" as const,
+            retrievalArg: result.conversationId,
+        }));
+    }
+}

package/src/services/search/providers/LessonSearchProvider.ts

@@ -0,0 +1,75 @@
+/**
+ * LessonSearchProvider - Search provider for lessons.
+ *
+ * Queries the `lessons` RAG collection directly via RAGService
+ * since lessons don't have a dedicated embedding service like
+ * reports and conversations do.
+ */
+
+import { logger } from "@/utils/logger";
+import { RAGService, type RAGQueryResult } from "@/services/rag/RAGService";
+import { buildProjectFilter } from "../projectFilter";
+import type { SearchProvider, SearchResult } from "../types";
+
+/** Collection name for lessons (matches what learn.ts uses) */
+const LESSONS_COLLECTION = "lessons";
+
+export class LessonSearchProvider implements SearchProvider {
+    readonly name = "lessons";
+    readonly description = "Agent lessons and insights";
+
+    async search(
+        query: string,
+        projectId: string,
+        limit: number,
+        minScore: number
+    ): Promise<SearchResult[]> {
+        const ragService = RAGService.getInstance();
+
+        // Check if the lessons collection exists
+        const collections = await ragService.listCollections();
+        if (!collections.includes(LESSONS_COLLECTION)) {
+            logger.debug("[LessonSearchProvider] Lessons collection does not exist");
+            return [];
+        }
+
+        const filter = buildProjectFilter(projectId);
+
+        const results = await ragService.queryWithFilter(
+            LESSONS_COLLECTION,
+            query,
+            limit * 2, // Request more to account for minScore filtering
+            filter
+        );
+
+        logger.debug("[LessonSearchProvider] Search complete", {
+            query,
+            projectId,
+            rawResults: results.length,
+        });
+
+        return results
+            .filter((result: RAGQueryResult) => result.score >= minScore)
+            .slice(0, limit)
+            .map((result: RAGQueryResult) => this.transformResult(result, projectId));
+    }
+
+    private transformResult(result: RAGQueryResult, fallbackProjectId: string): SearchResult {
+        const metadata = result.document.metadata || {};
+
+        return {
+            source: this.name,
+            id: result.document.id || "",
+            projectId: String(metadata.projectId || fallbackProjectId),
+            relevanceScore: result.score,
+            title: String(metadata.title || ""),
+            summary: result.document.content?.substring(0, 200) || "",
+            createdAt: metadata.timestamp ? Number(metadata.timestamp) : undefined,
+            author: String(metadata.agentPubkey || ""),
+            authorName: String(metadata.agentName || ""),
+            tags: Array.isArray(metadata.hashtags) ? (metadata.hashtags as string[]) : undefined,
+            retrievalTool: "lesson_get" as const,
+            retrievalArg: result.document.id || "",
+        };
+    }
+}

package/src/services/search/providers/ReportSearchProvider.ts

@@ -0,0 +1,49 @@
+/**
+ * ReportSearchProvider - Search provider for project reports.
+ *
+ * Queries the `project_reports` RAG collection via ReportEmbeddingService.
+ */
+
+import { logger } from "@/utils/logger";
+import { getReportEmbeddingService } from "@/services/reports/ReportEmbeddingService";
+import type { SearchProvider, SearchResult } from "../types";
+
+export class ReportSearchProvider implements SearchProvider {
+    readonly name = "reports";
+    readonly description = "Project reports and documentation";
+
+    async search(
+        query: string,
+        projectId: string,
+        limit: number,
+        minScore: number
+    ): Promise<SearchResult[]> {
+        const reportEmbeddingService = getReportEmbeddingService();
+
+        const results = await reportEmbeddingService.semanticSearch(query, {
+            limit,
+            minScore,
+            projectId,
+        });
+
+        logger.debug("[ReportSearchProvider] Search complete", {
+            query,
+            projectId,
+            found: results.length,
+        });
+
+        return results.map((result) => ({
+            source: this.name,
+            id: result.slug,
+            projectId: result.projectId,
+            relevanceScore: result.relevanceScore,
+            title: result.title,
+            summary: result.summary || "",
+            createdAt: result.publishedAt,
+            author: result.author,
+            tags: result.hashtags,
+            retrievalTool: "report_read" as const,
+            retrievalArg: result.slug,
+        }));
+    }
+}