@tenex-chat/backend 0.9.1

package/src/conversations/formatters/utils/TreeRenderer.ts

@@ -0,0 +1,49 @@
+export class TreeRenderer {
+    /**
+     * Get the connector character(s) for the current node
+     */
+    getConnector(style: "ascii" | "unicode" | "markdown", isLast: boolean): string {
+        switch (style) {
+            case "ascii":
+                return isLast ? "└── " : "├── ";
+            case "unicode":
+                return isLast ? "└── " : "├── ";
+            case "markdown":
+                return "- ";
+            default:
+                return "";
+        }
+    }
+
+    /**
+     * Get the prefix for child nodes
+     */
+    getChildPrefix(style: "ascii" | "unicode" | "markdown", parentIsLast: boolean): string {
+        switch (style) {
+            case "ascii":
+                return parentIsLast ? "    " : "│   ";
+            case "unicode":
+                return parentIsLast ? "    " : "│   ";
+            case "markdown":
+                return "  ";
+            default:
+                return "";
+        }
+    }
+
+    /**
+     * Get a separator line between threads
+     */
+    getSeparator(style: "ascii" | "unicode" | "markdown", width = 60): string {
+        switch (style) {
+            case "ascii":
+                return "-".repeat(width);
+            case "unicode":
+                return "─".repeat(width);
+            case "markdown":
+                return "\n---\n";
+            default:
+                return "";
+        }
+    }
+}

package/src/conversations/index.ts

@@ -0,0 +1,2 @@
+export { ConversationStore } from "./ConversationStore";
+export type { ConversationMetadata, ConversationEntry } from "./types";

package/src/conversations/persistence/ToolMessageStorage.ts

@@ -0,0 +1,143 @@
+import { promises as fs } from "node:fs";
+import { config } from "@/services/ConfigService";
+import * as path from "node:path";
+import { formatAnyError } from "@/lib/error-formatter";
+import { logger } from "@/utils/logger";
+import type { ModelMessage } from "ai";
+
+/**
+ * Storage interface for tool messages
+ * Single Responsibility: Persist and retrieve tool execution messages
+ */
+export class ToolMessageStorage {
+    private readonly storageDir = config.getConfigPath("tool-messages");
+
+    /**
+     * Store tool messages for later reconstruction
+     */
+    async store(
+        eventId: string,
+        toolCall: {
+            toolCallId: string;
+            toolName: string;
+            input: unknown;
+        },
+        toolResult: {
+            toolCallId: string;
+            toolName: string;
+            output: unknown;
+            error?: boolean;
+        },
+        agentPubkey: string
+    ): Promise<void> {
+        try {
+            // Ensure input is always an object (AI SDK schema requires it, and JSON.stringify strips undefined)
+            const safeInput = toolCall.input !== undefined ? toolCall.input : {};
+
+            // Ensure output is always defined
+            const safeOutput = toolResult.output !== undefined
+                ? {
+                    type: "text" as const,
+                    value: typeof toolResult.output === "string"
+                        ? toolResult.output
+                        : JSON.stringify(toolResult.output),
+                }
+                : { type: "text" as const, value: "" };
+
+            const messages: ModelMessage[] = [
+                {
+                    role: "assistant",
+                    content: [
+                        {
+                            type: "tool-call" as const,
+                            toolCallId: toolCall.toolCallId,
+                            toolName: toolCall.toolName,
+                            input: safeInput,
+                        },
+                    ],
+                },
+                {
+                    role: "tool",
+                    content: [
+                        {
+                            type: "tool-result" as const,
+                            toolCallId: toolResult.toolCallId,
+                            toolName: toolResult.toolName,
+                            output: safeOutput,
+                        },
+                    ],
+                },
+            ];
+
+            await fs.mkdir(this.storageDir, { recursive: true });
+
+            const filePath = path.join(this.storageDir, `${eventId}.json`);
+            const data = {
+                eventId,
+                agentPubkey,
+                timestamp: Date.now(),
+                messages,
+            };
+
+            await fs.writeFile(filePath, JSON.stringify(data, null, 2));
+
+            logger.debug("[ToolMessageStorage] Stored tool messages", {
+                eventId: eventId.substring(0, 8),
+                filePath,
+            });
+        } catch (error) {
+            logger.error("[ToolMessageStorage] Failed to store tool messages", {
+                error: formatAnyError(error),
+                eventId,
+            });
+        }
+    }
+
+    /**
+     * Load tool messages from storage by event ID
+     */
+    async load(eventId: string): Promise<ModelMessage[] | null> {
+        try {
+            const filePath = path.join(this.storageDir, `${eventId}.json`);
+            const data = await fs.readFile(filePath, "utf-8");
+            const parsed = JSON.parse(data);
+            // The stored messages are valid ModelMessage[] from the store() method
+            return parsed.messages as ModelMessage[];
+        } catch {
+            // File doesn't exist or can't be read
+            return null;
+        }
+    }
+
+    /**
+     * Clean up old tool messages
+     */
+    async cleanup(olderThanMs: number = 24 * 60 * 60 * 1000): Promise<void> {
+        try {
+            const files = await fs.readdir(this.storageDir);
+            const now = Date.now();
+
+            for (const file of files) {
+                if (!file.endsWith(".json")) continue;
+
+                const filePath = path.join(this.storageDir, file);
+                const stats = await fs.stat(filePath);
+
+                if (now - stats.mtimeMs > olderThanMs) {
+                    await fs.unlink(filePath);
+                    logger.debug("[ToolMessageStorage] Cleaned up old tool message file", {
+                        file,
+                        ageMs: now - stats.mtimeMs,
+                    });
+                }
+            }
+        } catch (error) {
+            logger.error("[ToolMessageStorage] Failed to cleanup", {
+                error: formatAnyError(error),
+            });
+        }
+    }
+}
+
+// Singleton instance
+export const toolMessageStorage = new ToolMessageStorage();

package/src/conversations/search/ConversationIndexManager.ts

@@ -0,0 +1,393 @@
+/**
+ * ConversationIndexManager - Handles JSON index I/O with debounced updates.
+ *
+ * Responsibilities:
+ * - Load index from disk or rebuild if missing
+ * - Rebuild index by scanning all conversation files
+ * - Debounced incremental updates (30 seconds)
+ * - Atomic writes (temp file + rename)
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { logger } from "@/utils/logger";
+import type {
+    ConversationIndex,
+    ConversationIndexEntry,
+    MessageIndexEntry,
+} from "./types";
+import {
+    listConversationIdsFromDiskForProject,
+    readLightweightMetadata,
+    readMessagesFromDisk,
+} from "../ConversationDiskReader";
+import type { ConversationEntry } from "../types";
+
+/** Current index format version */
+const INDEX_VERSION = "1.0";
+
+/** Debounce delay for index updates (30 seconds) */
+const DEBOUNCE_MS = 30_000;
+
+/** Index filename */
+const INDEX_FILENAME = "conversation-search-index.json";
+
+/**
+ * State for debounced updates.
+ */
+interface DebounceState {
+    timerId: NodeJS.Timeout | null;
+    pendingConversationIds: Set<string>;
+}
+
+/**
+ * Manages the conversation search index.
+ */
+export class ConversationIndexManager {
+    private basePath: string;
+    private projectId: string;
+    private cachedIndex: ConversationIndex | null = null;
+    private debounceState: DebounceState = {
+        timerId: null,
+        pendingConversationIds: new Set(),
+    };
+
+    constructor(basePath: string, projectId: string) {
+        this.basePath = basePath;
+        this.projectId = projectId;
+    }
+
+    /**
+     * Get the path to the index file.
+     */
+    private getIndexPath(): string {
+        return join(this.basePath, this.projectId, ".tenex", INDEX_FILENAME);
+    }
+
+    /**
+     * Ensure the .tenex directory exists.
+     */
+    private ensureDirectory(): void {
+        const dir = dirname(this.getIndexPath());
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+
+    /**
+     * Load the index from disk.
+     * Returns null if the index doesn't exist or is invalid.
+     */
+    private loadFromDisk(): ConversationIndex | null {
+        const indexPath = this.getIndexPath();
+        try {
+            if (!existsSync(indexPath)) {
+                return null;
+            }
+            const content = readFileSync(indexPath, "utf-8");
+            const parsed = JSON.parse(content) as ConversationIndex;
+
+            // Version check
+            if (parsed.version !== INDEX_VERSION) {
+                logger.info("[ConversationIndexManager] Index version mismatch, will rebuild", {
+                    found: parsed.version,
+                    expected: INDEX_VERSION,
+                });
+                return null;
+            }
+
+            return parsed;
+        } catch (error) {
+            logger.warn("[ConversationIndexManager] Failed to load index", { error });
+            return null;
+        }
+    }
+
+    /**
+     * Save the index to disk atomically.
+     */
+    private saveToDisk(index: ConversationIndex): void {
+        this.ensureDirectory();
+        const indexPath = this.getIndexPath();
+        const tempPath = indexPath + ".tmp";
+
+        try {
+            // Write to temp file
+            writeFileSync(tempPath, JSON.stringify(index, null, 2));
+
+            // Atomic rename
+            renameSync(tempPath, indexPath);
+
+            logger.debug("[ConversationIndexManager] Index saved", {
+                conversationCount: index.conversations.length,
+            });
+        } catch (error) {
+            logger.error("[ConversationIndexManager] Failed to save index", { error });
+            // Clean up temp file if it exists
+            try {
+                if (existsSync(tempPath)) {
+                    unlinkSync(tempPath);
+                }
+            } catch {
+                // Ignore cleanup errors
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Index a single conversation from disk.
+     */
+    private indexConversation(conversationId: string): ConversationIndexEntry | null {
+        try {
+            const metadata = readLightweightMetadata(this.basePath, this.projectId, conversationId);
+            const messages = readMessagesFromDisk(this.basePath, this.projectId, conversationId);
+
+            if (!messages || messages.length === 0) {
+                return null;
+            }
+
+            // Extract agents (unique pubkeys)
+            const agentSet = new Set<string>();
+            for (const msg of messages) {
+                if (msg.pubkey) {
+                    agentSet.add(msg.pubkey);
+                }
+            }
+
+            // Index messages (only text messages with content)
+            const indexedMessages: MessageIndexEntry[] = [];
+            for (let i = 0; i < messages.length; i++) {
+                const msg = messages[i] as ConversationEntry;
+                if (msg.messageType === "text" && msg.content && msg.content.trim().length > 0) {
+                    indexedMessages.push({
+                        messageId: `msg-${i}`,
+                        content: msg.content,
+                        timestamp: msg.timestamp,
+                        from: msg.pubkey,
+                        to: msg.targetedPubkeys?.[0],
+                    });
+                }
+            }
+
+            // Calculate lastMessageAt from the last message with a timestamp
+            let lastMessageAt: number | undefined;
+            for (let i = messages.length - 1; i >= 0; i--) {
+                if (messages[i].timestamp) {
+                    lastMessageAt = messages[i].timestamp;
+                    break;
+                }
+            }
+
+            return {
+                conversationId,
+                slug: this.projectId,
+                title: metadata?.title,
+                messageCount: messages.length,
+                lastMessageAt,
+                agents: Array.from(agentSet),
+                messages: indexedMessages,
+            };
+        } catch (error) {
+            logger.warn("[ConversationIndexManager] Failed to index conversation", {
+                conversationId: conversationId.substring(0, 8),
+                error,
+            });
+            return null;
+        }
+    }
+
+    /**
+     * Rebuild the entire index from scratch.
+     */
+    rebuildIndex(): ConversationIndex {
+        logger.info("[ConversationIndexManager] Rebuilding index", { projectId: this.projectId });
+
+        const conversationIds = listConversationIdsFromDiskForProject(this.basePath, this.projectId);
+        const conversations: ConversationIndexEntry[] = [];
+
+        for (const convId of conversationIds) {
+            const entry = this.indexConversation(convId);
+            if (entry) {
+                conversations.push(entry);
+            }
+        }
+
+        const index: ConversationIndex = {
+            version: INDEX_VERSION,
+            lastUpdated: new Date().toISOString(),
+            conversations,
+        };
+
+        // Save to disk
+        this.saveToDisk(index);
+        this.cachedIndex = index;
+
+        logger.info("[ConversationIndexManager] Index rebuilt", {
+            conversationCount: conversations.length,
+            projectId: this.projectId,
+        });
+
+        return index;
+    }
+
+    /**
+     * Get the current index, loading from disk or rebuilding if necessary.
+     */
+    getIndex(): ConversationIndex {
+        // Return cached index if available
+        if (this.cachedIndex) {
+            return this.cachedIndex;
+        }
+
+        // Try to load from disk
+        const loaded = this.loadFromDisk();
+        if (loaded) {
+            this.cachedIndex = loaded;
+            return loaded;
+        }
+
+        // Rebuild index
+        return this.rebuildIndex();
+    }
+
+    /**
+     * Trigger a debounced update for a specific conversation.
+     * Updates will be batched and applied after 30 seconds.
+     */
+    triggerUpdate(conversationId: string): void {
+        this.debounceState.pendingConversationIds.add(conversationId);
+
+        // If timer already running, let it handle the update
+        if (this.debounceState.timerId) {
+            return;
+        }
+
+        // Schedule debounced update
+        this.debounceState.timerId = setTimeout(() => {
+            this.flushPendingUpdates();
+        }, DEBOUNCE_MS);
+    }
+
+    /**
+     * Flush all pending updates immediately.
+     */
+    private flushPendingUpdates(): void {
+        if (this.debounceState.timerId) {
+            clearTimeout(this.debounceState.timerId);
+            this.debounceState.timerId = null;
+        }
+
+        const pendingIds = Array.from(this.debounceState.pendingConversationIds);
+        this.debounceState.pendingConversationIds.clear();
+
+        if (pendingIds.length === 0) {
+            return;
+        }
+
+        logger.debug("[ConversationIndexManager] Flushing pending updates", {
+            count: pendingIds.length,
+        });
+
+        // Get current index
+        const index = this.getIndex();
+
+        // Update each conversation
+        for (const convId of pendingIds) {
+            const newEntry = this.indexConversation(convId);
+
+            // Find existing entry index
+            const existingIndex = index.conversations.findIndex(
+                (c) => c.conversationId === convId
+            );
+
+            if (newEntry) {
+                if (existingIndex >= 0) {
+                    // Update existing
+                    index.conversations[existingIndex] = newEntry;
+                } else {
+                    // Add new
+                    index.conversations.push(newEntry);
+                }
+            } else if (existingIndex >= 0) {
+                // Conversation no longer exists, remove it
+                index.conversations.splice(existingIndex, 1);
+            }
+        }
+
+        // Update timestamp and save
+        index.lastUpdated = new Date().toISOString();
+        this.saveToDisk(index);
+        this.cachedIndex = index;
+    }
+
+    /**
+     * Force an immediate update for a conversation (no debouncing).
+     */
+    updateConversationNow(conversationId: string): void {
+        const index = this.getIndex();
+        const newEntry = this.indexConversation(conversationId);
+
+        const existingIndex = index.conversations.findIndex(
+            (c) => c.conversationId === conversationId
+        );
+
+        if (newEntry) {
+            if (existingIndex >= 0) {
+                index.conversations[existingIndex] = newEntry;
+            } else {
+                index.conversations.push(newEntry);
+            }
+        } else if (existingIndex >= 0) {
+            index.conversations.splice(existingIndex, 1);
+        }
+
+        index.lastUpdated = new Date().toISOString();
+        this.saveToDisk(index);
+        this.cachedIndex = index;
+    }
+
+    /**
+     * Invalidate the cached index, forcing a reload on next access.
+     */
+    invalidateCache(): void {
+        this.cachedIndex = null;
+    }
+
+    /**
+     * Clean up resources (timers, etc.).
+     */
+    cleanup(): void {
+        if (this.debounceState.timerId) {
+            clearTimeout(this.debounceState.timerId);
+            this.debounceState.timerId = null;
+        }
+        this.debounceState.pendingConversationIds.clear();
+    }
+}
+
+/** Singleton instances per project */
+const instances = new Map<string, ConversationIndexManager>();
+
+/**
+ * Get or create an index manager for a project.
+ */
+export function getIndexManager(basePath: string, projectId: string): ConversationIndexManager {
+    const key = `${basePath}:${projectId}`;
+    let manager = instances.get(key);
+    if (!manager) {
+        manager = new ConversationIndexManager(basePath, projectId);
+        instances.set(key, manager);
+    }
+    return manager;
+}
+
+/**
+ * Clear all cached instances (for testing).
+ */
+export function clearIndexManagerInstances(): void {
+    for (const manager of instances.values()) {
+        manager.cleanup();
+    }
+    instances.clear();
+}

package/src/conversations/search/QueryParser.ts

@@ -0,0 +1,114 @@
+/**
+ * QueryParser - Pure function for parsing and validating search queries.
+ *
+ * Handles:
+ * - Text query validation (required, non-empty)
+ * - Agent filter parsing (string array)
+ * - Date filter parsing (Unix timestamps or ISO 8601 strings)
+ * - 'after' is a pure alias for 'since' (since takes precedence if both provided)
+ */
+
+import type { SearchFilters, SearchQuery } from "./types";
+
+/**
+ * Input format from the tool schema.
+ */
+export interface RawSearchInput {
+    query: string;
+    filters?: {
+        agents?: string[];
+        since?: string | number;
+        after?: string | number;
+    };
+}
+
+/**
+ * Parse a date input to Unix timestamp in seconds.
+ * Accepts:
+ * - Unix timestamp (number or numeric string) in seconds
+ * - ISO 8601 date strings (e.g., "2026-01-26T10:00:00Z")
+ * - Date-only strings (e.g., "2026-01-26")
+ *
+ * @throws Error if the date cannot be parsed
+ */
+export function parseTimestamp(value: string | number): number {
+    if (typeof value === "number") {
+        // Assume it's already Unix seconds
+        return value;
+    }
+
+    // Try parsing as numeric string (Unix timestamp)
+    const numericValue = Number(value);
+    if (!isNaN(numericValue) && value.trim() === String(numericValue)) {
+        return numericValue;
+    }
+
+    // Try parsing as date string
+    const date = new Date(value);
+    if (isNaN(date.getTime())) {
+        throw new Error(`Invalid date format: "${value}". Expected Unix timestamp or ISO 8601 date.`);
+    }
+
+    // Convert to Unix seconds
+    return Math.floor(date.getTime() / 1000);
+}
+
+/**
+ * Parse and validate a raw search input into a SearchQuery.
+ *
+ * @throws Error if validation fails
+ */
+export function parseQuery(input: RawSearchInput): SearchQuery {
+    // Validate query text
+    if (!input.query || typeof input.query !== "string") {
+        throw new Error("Search query is required and must be a non-empty string.");
+    }
+
+    const trimmedQuery = input.query.trim();
+    if (trimmedQuery.length === 0) {
+        throw new Error("Search query cannot be empty.");
+    }
+
+    // Parse filters
+    const filters: SearchFilters = {};
+
+    if (input.filters) {
+        // Parse agents filter
+        if (input.filters.agents !== undefined) {
+            if (!Array.isArray(input.filters.agents)) {
+                throw new Error("filters.agents must be an array of strings.");
+            }
+            const validAgents = input.filters.agents.filter(
+                (a): a is string => typeof a === "string" && a.trim().length > 0
+            );
+            if (validAgents.length > 0) {
+                filters.agents = validAgents.map((a) => a.trim());
+            }
+        }
+
+        // Parse since filter (primary)
+        if (input.filters.since !== undefined) {
+            filters.since = parseTimestamp(input.filters.since);
+        }
+
+        // Parse after filter as pure alias for since
+        // If since is already set, ignore after (since takes precedence)
+        if (input.filters.after !== undefined && filters.since === undefined) {
+            filters.since = parseTimestamp(input.filters.after);
+        }
+        // Note: We don't store 'after' separately - it's just an alias for 'since'
+    }
+
+    return {
+        text: trimmedQuery,
+        filters,
+    };
+}
+
+/**
+ * Get the "since" timestamp from filters.
+ * Note: 'after' is already resolved to 'since' during parsing.
+ */
+export function getEffectiveSinceTimestamp(filters: SearchFilters): number | undefined {
+    return filters.since;
+}