@tenex-chat/backend 0.9.1

package/src/conversations/executionTime.ts

@@ -0,0 +1,62 @@
+/**
+ * Utility functions for managing conversation execution time
+ * Works directly with ConversationStore objects, following DRY principle
+ */
+
+import type { ConversationStore } from "./ConversationStore";
+
+/**
+ * Start tracking execution time for a conversation
+ */
+export function startExecutionTime(conversation: ConversationStore): void {
+    if (conversation.executionTime.isActive) {
+        // Already active - don't restart
+        return;
+    }
+
+    conversation.executionTime.currentSessionStart = Date.now();
+    conversation.executionTime.isActive = true;
+    conversation.executionTime.lastUpdated = Date.now();
+}
+
+/**
+ * Stop tracking execution time and add duration to total
+ * @returns Duration of this session in milliseconds
+ */
+export function stopExecutionTime(conversation: ConversationStore): number {
+    if (!conversation.executionTime.isActive || !conversation.executionTime.currentSessionStart) {
+        return 0;
+    }
+
+    const sessionDuration = Date.now() - conversation.executionTime.currentSessionStart;
+    const sessionSeconds = Math.round(sessionDuration / 1000);
+
+    conversation.executionTime.totalSeconds += sessionSeconds;
+    conversation.executionTime.currentSessionStart = undefined;
+    conversation.executionTime.isActive = false;
+    conversation.executionTime.lastUpdated = Date.now();
+
+    return sessionDuration;
+}
+
+/**
+ * Get total execution time in seconds including any active session
+ */
+export function getTotalExecutionTimeSeconds(conversation: ConversationStore): number {
+    let total = conversation.executionTime.totalSeconds;
+
+    // Add current active session time if any
+    if (conversation.executionTime.isActive && conversation.executionTime.currentSessionStart) {
+        const activeSeconds = Math.round((Date.now() - conversation.executionTime.currentSessionStart) / 1000);
+        total += activeSeconds;
+    }
+
+    return total;
+}
+
+/**
+ * Check if execution is currently active
+ */
+export function isExecutionActive(conversation: ConversationStore): boolean {
+    return conversation.executionTime?.isActive ?? false;
+}

package/src/conversations/formatters/DelegationXmlFormatter.ts

@@ -0,0 +1,64 @@
+interface DelegationResponse {
+    from: string;
+    content: string;
+    eventId: string;
+    status: "completed" | "error";
+}
+
+interface DelegationInfo {
+    id: string;
+    from: string;
+    recipients: string[];
+    phase?: string;
+    message: string;
+    requestEventId: string;
+    responses: DelegationResponse[];
+}
+
+/**
+ * Formats delegation information as structured XML for LLM comprehension
+ */
+export class DelegationXmlFormatter {
+    /**
+     * Render a delegation with its responses as XML
+     */
+    static render(delegation: DelegationInfo, debug = false): string {
+        const eventPrefix = debug ? `[Event ${delegation.requestEventId.substring(0, 8)}] ` : "";
+        const recipientsAttr = delegation.recipients.join(",");
+        const phaseAttr = delegation.phase ? ` phase="${delegation.phase}"` : "";
+
+        let xml = `${eventPrefix}<delegation from="${delegation.from}" recipients="${recipientsAttr}" id="${delegation.id}"${phaseAttr}>`;
+        xml += `\n    <delegation-request>${DelegationXmlFormatter.escapeXml(delegation.message)}</delegation-request>`;
+
+        // Add responses
+        for (const response of delegation.responses) {
+            const statusAttr = response.status === "error" ? ' error="true"' : "";
+            const eventIdAttr = debug ? ` event-id="${response.eventId.substring(0, 8)}"` : "";
+            xml += `\n    <response from="${response.from}"${statusAttr}${eventIdAttr}>${DelegationXmlFormatter.escapeXml(response.content)}</response>`;
+        }
+
+        // Add pending placeholders for recipients without responses
+        const respondedFrom = new Set(delegation.responses.map((r) => r.from));
+        for (const recipient of delegation.recipients) {
+            if (!respondedFrom.has(recipient)) {
+                xml += `\n    <response from="${recipient}" status="pending" />`;
+            }
+        }
+
+        xml += "\n</delegation>";
+
+        return xml;
+    }
+
+    /**
+     * Escape XML special characters
+     */
+    private static escapeXml(text: string): string {
+        return text
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;")
+            .replace(/'/g, "&apos;");
+    }
+}

package/src/conversations/formatters/ThreadedConversationFormatter.ts

@@ -0,0 +1,303 @@
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import { MessageFormatter } from "./utils/MessageFormatter";
+import { TimestampFormatter } from "./utils/TimestampFormatter";
+import { TreeBuilder } from "./utils/TreeBuilder";
+import { TreeRenderer } from "./utils/TreeRenderer";
+
+export interface ThreadNode {
+    event: NDKEvent;
+    agent?: string; // Agent name/identifier
+    timestamp: Date;
+    content: string;
+    toolCall?: {
+        name: string;
+        args?: string;
+    };
+    children: ThreadNode[];
+    depth: number;
+}
+
+export interface FormatterOptions {
+    includeTimestamps: boolean;
+    timestampFormat: "relative" | "absolute" | "time-only";
+    maxDepth?: number;
+    includeToolCalls: boolean;
+    treeStyle: "ascii" | "unicode" | "markdown";
+    compactMode: boolean; // Single-line per message
+    currentAgentPubkey?: string; // The agent we're formatting for (to show "you")
+}
+
+export class ThreadedConversationFormatter {
+    private treeBuilder: TreeBuilder;
+    private messageFormatter: MessageFormatter;
+    private timestampFormatter: TimestampFormatter;
+    private treeRenderer: TreeRenderer;
+
+    constructor() {
+        this.treeBuilder = new TreeBuilder();
+        this.messageFormatter = new MessageFormatter();
+        this.timestampFormatter = new TimestampFormatter();
+        this.treeRenderer = new TreeRenderer();
+    }
+
+    /**
+     * Build tree structure from flat event list
+     */
+    async buildThreadTree(events: NDKEvent[]): Promise<ThreadNode[]> {
+        return this.treeBuilder.buildFromEvents(events);
+    }
+
+    /**
+     * Format single thread as ASCII/Unicode tree
+     */
+    formatThread(root: ThreadNode, options?: FormatterOptions): string {
+        const opts = this.getDefaultOptions(options);
+        return this.renderNode(root, opts, "", true);
+    }
+
+    /**
+     * Extract agent-specific participation branches
+     */
+    extractAgentBranches(tree: ThreadNode[], agentPubkey: string): ThreadNode[] {
+        const relevantNodes: ThreadNode[] = [];
+
+        for (const root of tree) {
+            const extractedBranch = this.extractRelevantBranch(root, agentPubkey);
+            if (extractedBranch) {
+                relevantNodes.push(extractedBranch);
+            }
+        }
+
+        return relevantNodes;
+    }
+
+    /**
+     * Format branches where the agent participated, excluding the active branch
+     * This is the main entry point for getting "other threads" context
+     */
+    public async formatOtherBranches(
+        allEvents: NDKEvent[],
+        agentPubkey: string,
+        activeBranchIds: Set<string>
+    ): Promise<string | null> {
+        // 1. Build complete conversation tree from all events
+        const completeTree = await this.buildThreadTree(allEvents);
+
+        // 2. Prune the active branch from the tree
+        const prunedTree = this.pruneBranch(completeTree, activeBranchIds);
+
+        // 3. Extract branches where agent participated from the pruned tree
+        const agentBranches = this.extractRelevantBranches(prunedTree, agentPubkey);
+
+        // 4. If no relevant branches found, return null
+        if (agentBranches.length === 0) {
+            return null;
+        }
+
+        // 5. Format the branches into a string
+        const options: FormatterOptions = {
+            includeTimestamps: true,
+            timestampFormat: "time-only",
+            includeToolCalls: true,
+            treeStyle: "ascii",
+            compactMode: true,
+            currentAgentPubkey: agentPubkey, // Pass the agent we're formatting for
+        };
+
+        const result: string[] = [];
+        for (let i = 0; i < agentBranches.length; i++) {
+            if (i > 0) {
+                result.push(`\n${"─".repeat(60)}\n`);
+            }
+            result.push(this.formatThread(agentBranches[i], options));
+        }
+
+        return result.join("\n");
+    }
+
+    /**
+     * Remove all nodes that are part of the active branch
+     * Returns a new tree with the active branch pruned out
+     */
+    private pruneBranch(tree: ThreadNode[], activeBranchIds: Set<string>): ThreadNode[] {
+        const prunedRoots: ThreadNode[] = [];
+
+        for (const root of tree) {
+            const prunedNode = this.pruneNode(root, activeBranchIds);
+            if (prunedNode) {
+                prunedRoots.push(prunedNode);
+            }
+        }
+
+        return prunedRoots;
+    }
+
+    /**
+     * Recursively prune a node and its children
+     * Returns null if the entire subtree should be removed
+     */
+    private pruneNode(node: ThreadNode, activeBranchIds: Set<string>): ThreadNode | null {
+        // If this node is in the active branch
+        if (activeBranchIds.has(node.event.id)) {
+            // Check if ANY child is NOT in the active branch
+            // If so, we need to keep this node but prune only active children
+            const hasNonActiveBranches = node.children.some(
+                (child) => !this.isEntireBranchActive(child, activeBranchIds)
+            );
+
+            if (hasNonActiveBranches) {
+                // Keep this node but prune children selectively
+                const prunedChildren: ThreadNode[] = [];
+                for (const child of node.children) {
+                    const prunedChild = this.pruneNode(child, activeBranchIds);
+                    if (prunedChild) {
+                        prunedChildren.push(prunedChild);
+                    }
+                }
+
+                // Return the node with only non-active children
+                return {
+                    ...node,
+                    children: prunedChildren,
+                };
+            }
+            // This node and ALL its descendants are in the active branch
+            return null;
+        }
+
+        // Node is not in active branch - keep it and recursively prune children
+        const prunedChildren: ThreadNode[] = [];
+        for (const child of node.children) {
+            const prunedChild = this.pruneNode(child, activeBranchIds);
+            if (prunedChild) {
+                prunedChildren.push(prunedChild);
+            }
+        }
+
+        // Return the node with pruned children
+        return {
+            ...node,
+            children: prunedChildren,
+        };
+    }
+
+    /**
+     * Check if an entire branch (node and all descendants) is in the active branch
+     */
+    private isEntireBranchActive(node: ThreadNode, activeBranchIds: Set<string>): boolean {
+        if (!activeBranchIds.has(node.event.id)) {
+            return false;
+        }
+
+        // Check all children recursively
+        for (const child of node.children) {
+            if (!this.isEntireBranchActive(child, activeBranchIds)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Extract branches where the agent participated (similar to extractAgentBranches)
+     * but works on already pruned tree
+     */
+    private extractRelevantBranches(tree: ThreadNode[], agentPubkey: string): ThreadNode[] {
+        const relevantNodes: ThreadNode[] = [];
+
+        for (const root of tree) {
+            const extractedBranch = this.extractRelevantBranch(root, agentPubkey);
+            if (extractedBranch) {
+                relevantNodes.push(extractedBranch);
+            }
+        }
+
+        return relevantNodes;
+    }
+
+    private extractRelevantBranch(node: ThreadNode, agentPubkey: string): ThreadNode | null {
+        // Check if this node or any descendant involves the agent
+        const involvedInBranch = this.isAgentInvolvedInBranch(node, agentPubkey);
+
+        if (!involvedInBranch) {
+            return null;
+        }
+
+        // If agent is involved in this branch, return the ENTIRE branch with all descendants
+        // This preserves full context of conversations the agent participated in
+        return this.cloneNode(node);
+    }
+
+    private cloneNode(node: ThreadNode): ThreadNode {
+        return {
+            ...node,
+            children: node.children.map((child) => this.cloneNode(child)),
+        };
+    }
+
+    private isAgentInvolvedInBranch(node: ThreadNode, agentPubkey: string): boolean {
+        // Check if this node is from the agent
+        if (node.event.pubkey === agentPubkey) {
+            return true;
+        }
+
+        // Check if any child branch has agent involvement
+        for (const child of node.children) {
+            if (this.isAgentInvolvedInBranch(child, agentPubkey)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private renderNode(
+        node: ThreadNode,
+        options: FormatterOptions,
+        prefix: string,
+        isLast: boolean
+    ): string {
+        const lines: string[] = [];
+
+        // Format the current node
+        const message = this.messageFormatter.format(node, options);
+        const timestamp = options.includeTimestamps
+            ? this.timestampFormatter.format(node.timestamp, options.timestampFormat)
+            : "";
+
+        // Add "(you)" if this is the current agent
+        let agentName = node.agent || "Unknown";
+        if (options.currentAgentPubkey && node.event.pubkey === options.currentAgentPubkey) {
+            agentName = `${agentName} (you)`;
+        }
+
+        const connector = this.treeRenderer.getConnector(options.treeStyle, isLast);
+
+        // Handle multi-line messages by joining with ⏎ separator
+        const inlineMessage = message.replace(/\n/g, " ⏎ ");
+        lines.push(`${prefix}${connector}${agentName}${timestamp}: ${inlineMessage}`);
+
+        // Render children with appropriate prefixes
+        const childPrefix = prefix + this.treeRenderer.getChildPrefix(options.treeStyle, isLast);
+        if (node.children.length > 0 && (!options.maxDepth || node.depth < options.maxDepth)) {
+            for (const [index, child] of node.children.entries()) {
+                const isLastChild = index === node.children.length - 1;
+                lines.push(this.renderNode(child, options, childPrefix, isLastChild));
+            }
+        }
+
+        return lines.join("\n");
+    }
+
+    private getDefaultOptions(options?: Partial<FormatterOptions>): FormatterOptions {
+        return {
+            includeTimestamps: true,
+            timestampFormat: "time-only",
+            includeToolCalls: true,
+            treeStyle: "ascii",
+            compactMode: true,
+            ...options,
+        };
+    }
+}

package/src/conversations/formatters/index.ts

@@ -0,0 +1,9 @@
+export {
+    ThreadedConversationFormatter,
+    type ThreadNode,
+    type FormatterOptions,
+} from "./ThreadedConversationFormatter";
+export { TreeBuilder } from "./utils/TreeBuilder";
+export { MessageFormatter } from "./utils/MessageFormatter";
+export { TimestampFormatter } from "./utils/TimestampFormatter";
+export { TreeRenderer } from "./utils/TreeRenderer";

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

@@ -0,0 +1,46 @@
+import type { FormatterOptions, ThreadNode } from "../ThreadedConversationFormatter";
+
+export class MessageFormatter {
+    /**
+     * Format a message node according to options
+     */
+    format(node: ThreadNode, options: FormatterOptions): string {
+        let message = node.content;
+
+        // Truncate if in compact mode
+        if (options.compactMode) {
+            message = this.truncateMessage(message, 100);
+        }
+
+        // Add tool call information if present
+        if (options.includeToolCalls && node.toolCall) {
+            const toolCallStr = node.toolCall.args
+                ? `[calls tool: ${node.toolCall.name}(${this.truncateMessage(node.toolCall.args, 50)})]`
+                : `[calls tool: ${node.toolCall.name}]`;
+            message = `${toolCallStr} ${message}`;
+        }
+
+        // Clean up message for single-line display
+        if (options.compactMode) {
+            message = message.replace(/\n+/g, " ").replace(/\s+/g, " ").trim();
+        }
+
+        return message;
+    }
+
+    private truncateMessage(text: string, maxLength: number): string {
+        if (text.length <= maxLength) {
+            return text;
+        }
+
+        // Try to truncate at a word boundary
+        const truncated = text.substring(0, maxLength);
+        const lastSpace = truncated.lastIndexOf(" ");
+
+        if (lastSpace > maxLength * 0.7) {
+            return `${truncated.substring(0, lastSpace)}...`;
+        }
+
+        return `${truncated}...`;
+    }
+}

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

@@ -0,0 +1,56 @@
+export class TimestampFormatter {
+    /**
+     * Format a timestamp according to the specified format
+     */
+    format(timestamp: Date, format: "relative" | "absolute" | "time-only"): string {
+        switch (format) {
+            case "relative":
+                return this.formatRelative(timestamp);
+            case "absolute":
+                return this.formatAbsolute(timestamp);
+            case "time-only":
+                return this.formatTimeOnly(timestamp);
+            default:
+                return "";
+        }
+    }
+
+    private formatRelative(timestamp: Date): string {
+        const now = new Date();
+        const diffMs = now.getTime() - timestamp.getTime();
+        const diffSec = Math.floor(diffMs / 1000);
+        const diffMin = Math.floor(diffSec / 60);
+        const diffHour = Math.floor(diffMin / 60);
+        const diffDay = Math.floor(diffHour / 24);
+
+        if (diffSec < 60) {
+            return ` [${diffSec}s ago]`;
+        }
+        if (diffMin < 60) {
+            return ` [${diffMin}m ago]`;
+        }
+        if (diffHour < 24) {
+            return ` [${diffHour}h ago]`;
+        }
+        return ` [${diffDay}d ago]`;
+    }
+
+    private formatAbsolute(timestamp: Date): string {
+        const year = timestamp.getFullYear();
+        const month = String(timestamp.getMonth() + 1).padStart(2, "0");
+        const day = String(timestamp.getDate()).padStart(2, "0");
+        const hour = String(timestamp.getHours()).padStart(2, "0");
+        const minute = String(timestamp.getMinutes()).padStart(2, "0");
+        const second = String(timestamp.getSeconds()).padStart(2, "0");
+
+        return ` [${year}-${month}-${day} ${hour}:${minute}:${second}]`;
+    }
+
+    private formatTimeOnly(timestamp: Date): string {
+        const hour = String(timestamp.getHours()).padStart(2, "0");
+        const minute = String(timestamp.getMinutes()).padStart(2, "0");
+        const second = String(timestamp.getSeconds()).padStart(2, "0");
+
+        return ` [${hour}:${minute}:${second}]`;
+    }
+}

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

@@ -0,0 +1,131 @@
+import { getPubkeyService } from "@/services/PubkeyService";
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+import type { ThreadNode } from "../ThreadedConversationFormatter";
+
+export class TreeBuilder {
+    /**
+     * Build tree structure from flat event list
+     */
+    async buildFromEvents(events: NDKEvent[]): Promise<ThreadNode[]> {
+        if (events.length === 0) {
+            return [];
+        }
+
+        // Create node map indexed by event ID
+        const nodeMap = new Map<string, ThreadNode>();
+        const rootNodes: ThreadNode[] = [];
+
+        // First pass: create all nodes
+        for (const event of events) {
+            const node: ThreadNode = {
+                event,
+                agent: await this.extractAgentName(event),
+                timestamp: new Date((event.created_at ?? 0) * 1000),
+                content: event.content,
+                toolCall: this.extractToolCall(event),
+                children: [],
+                depth: 0,
+            };
+            nodeMap.set(event.id, node);
+        }
+
+        // Second pass: establish parent-child relationships
+        for (const event of events) {
+            const node = nodeMap.get(event.id);
+            if (!node) continue;
+
+            const parentId = this.findParentEventId(event);
+
+            if (parentId && nodeMap.has(parentId)) {
+                const parentNode = nodeMap.get(parentId);
+                if (parentNode) {
+                    parentNode.children.push(node);
+                }
+            } else {
+                // No parent found, this is a root node
+                rootNodes.push(node);
+            }
+        }
+
+        // Third pass: calculate depths and sort children
+        for (const root of rootNodes) {
+            this.calculateDepthsAndSort(root, 0);
+        }
+
+        // Sort root nodes by timestamp
+        rootNodes.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+        return rootNodes;
+    }
+
+    private findParentEventId(event: NDKEvent): string | null {
+        // Look for 'e' tags that indicate a reply
+        const eTags = event.tags.filter((tag) => tag[0] === "e");
+
+        // The convention is that the first 'e' tag is the root,
+        // and the last 'e' tag is the direct parent (if multiple e tags)
+        if (eTags.length === 1) {
+            return eTags[0][1]; // Single e tag is the parent
+        }
+        if (eTags.length > 1) {
+            // Check for 'reply' marker
+            const replyTag = eTags.find((tag) => tag[3] === "reply");
+            if (replyTag) {
+                return replyTag[1];
+            }
+            // Otherwise, last e tag is typically the direct parent
+            return eTags[eTags.length - 1][1];
+        }
+
+        return null;
+    }
+
+    private async extractAgentName(event: NDKEvent): Promise<string | undefined> {
+        // Use the PubkeyService to resolve the actual name
+        const nameRepo = getPubkeyService();
+        const name = await nameRepo.getName(event.pubkey);
+        return name;
+    }
+
+    private extractToolCall(event: NDKEvent): { name: string; args?: string } | undefined {
+        // Look for tool call indicators in tags
+        const toolTag = event.tags.find((tag) => tag[0] === "tool");
+        if (toolTag) {
+            return {
+                name: toolTag[1],
+                args: toolTag[2],
+            };
+        }
+
+        // Check if content indicates a tool call - multiple patterns
+        const patterns = [
+            /(?:calls tool|using tool|executing):\s*(\w+)(?:\(([^)]*)\))?/i,
+            /(?:calling tool|call):\s*(\w+)(?:\(([^)]*)\))?/i,
+            /(?:Now|now)\s+calling\s+tool:\s*(\w+)(?:\(([^)]*)\))?/i,
+        ];
+
+        for (const pattern of patterns) {
+            const match = event.content.match(pattern);
+            if (match) {
+                return {
+                    name: match[1],
+                    args: match[2],
+                };
+            }
+        }
+
+        return undefined;
+    }
+
+    private calculateDepthsAndSort(node: ThreadNode, depth: number): void {
+        node.depth = depth;
+
+        // Sort children by timestamp
+        node.children.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+        // Recursively process children
+        for (const child of node.children) {
+            this.calculateDepthsAndSort(child, depth + 1);
+        }
+    }
+}