@tenex-chat/backend 0.9.1

package/src/conversations/services/ConversationSummarizer.ts

@@ -0,0 +1,234 @@
+import type { ConversationStore } from "@/conversations/ConversationStore";
+import { CategoryManager } from "@/conversations/services";
+import { NDKEventMetadata } from "@/events/NDKEventMetadata";
+import { llmServiceFactory } from "@/llm";
+import { shortenConversationId } from "@/utils/conversation-id";
+import { NDKKind } from "@/nostr/kinds";
+import { getNDK } from "@/nostr/ndkClient";
+import { config } from "@/services/ConfigService";
+import { getPubkeyService } from "@/services/PubkeyService";
+import type { ProjectContext } from "@/services/projects";
+import { ROOT_CONTEXT, SpanStatusCode, context as otelContext, trace } from "@opentelemetry/api";
+import { z } from "zod";
+
+const tracer = trace.getTracer("tenex.summarizer");
+
+export class ConversationSummarizer {
+    private categoryManager: CategoryManager;
+
+    constructor(private context: ProjectContext) {
+        // CategoryManager stores categories in ~/.tenex/data
+        this.categoryManager = new CategoryManager(config.getConfigPath());
+        this.categoryManager.initialize();
+    }
+
+    async summarizeAndPublish(conversation: ConversationStore): Promise<void> {
+        // Create a fresh span using ROOT_CONTEXT to avoid inheriting an ended span
+        // This is necessary because summarization runs debounced/async after the main processing span ends
+        const span = tracer.startSpan("tenex.summarize", {
+            attributes: {
+                "conversation.id": shortenConversationId(conversation.id),
+            },
+        }, ROOT_CONTEXT);
+
+        // Wrap execution in the new span's context so child operations use this span
+        return otelContext.with(trace.setSpan(ROOT_CONTEXT, span), async () => {
+            try {
+                // Get LLM configuration - use summarization config if set, otherwise default
+                const { llms } = await config.loadConfig();
+                const configName = llms.summarization || llms.default;
+
+                if (!configName) {
+                    console.warn("No LLM configuration available for summarization");
+                    return;
+                }
+
+                // Use getLLMConfig to resolve meta models automatically
+                const summarizationConfig = config.getLLMConfig(configName);
+
+                // Create LLM service
+                const llmService = llmServiceFactory.createService(
+                    summarizationConfig,
+                    {
+                        agentName: "summarizer",
+                        sessionId: `summarizer-${conversation.id}`,
+                    }
+                );
+
+                // Prepare conversation content from stored messages
+                const messages = conversation.getAllMessages();
+                const pubkeyService = getPubkeyService();
+
+                // Resolve pubkeys to names for all participants
+                const textMessages = messages.filter((entry) => entry.messageType === "text");
+                const formattedMessages = await Promise.all(
+                    textMessages.map(async (entry) => {
+                        const name = await pubkeyService.getName(entry.pubkey);
+                        return `${name}: ${entry.content}`;
+                    })
+                );
+                const conversationContent = formattedMessages.join("\n\n");
+
+                if (!conversationContent.trim()) {
+                    console.log("No content to summarize for conversation", conversation.id);
+                    return;
+                }
+
+                // Get existing categories for consistency
+                const existingCategories = await this.categoryManager.getCategories();
+                const categoryListText = existingCategories.length > 0
+                    ? `Existing categories (prefer these for consistency): ${existingCategories.join(", ")}`
+                    : "No existing categories yet. Create new ones as needed.";
+
+                // Generate title, summary, and status information
+                const { object: result } = await llmService.generateObject(
+                    [
+                        {
+                            role: "system",
+                            content: `You generate high-signal titles, summaries, status metadata, and category tags for technical conversations.
+
+                CRITICAL: Base output ONLY on what is explicitly stated in the conversation. Do NOT:
+                - Hallucinate success when errors, failures, or problems are mentioned
+                - Assume tasks were completed if the conversation shows they failed or are still in progress
+                - Invent outcomes not clearly stated in the transcript
+
+                DENSITY RULES (ENFORCE)
+                - Summary max 160 characters (hard limit).
+                - No narrative glue: avoid “ensuring”, “including”, “key features”, “focused on”, “review of”, “in order to”, “now complete”, “ready for testing” (unless explicitly stated).
+                - No redundancy: summary and status_current_activity must not restate the same fact in different words.
+
+                TITLE
+                - 3–5 words (hard limit), concrete nouns/verbs, no filler.
+                - Prefer outcome/topic phrasing.
+
+                SUMMARY (1 sentence only)
+                - Changelog style: state facts only (outcome/state, scope, blockers).
+                - For In Progress / Blocked / Waiting: include what is missing or unknown (“Details not provided”).
+                - Do not describe process.
+
+                STATUS
+                - status_label: one of "Researching", "In Progress", "Blocked", "Waiting", "Completed", "Failed", "Planning".
+                - status_current_activity: one dense clause, consistent with status_label.
+                - Do not duplicate the summary.
+
+                CATEGORIES (CANONICAL-FIRST, SEMANTIC)
+                You are given a list of previously used categories below. This list is a CANONICAL SUGGESTION SET, not an allowlist.
+                You must actively judge each candidate (including items from the list) using the rules below.
+
+                Previously used categories:
+                ${categoryListText}
+
+                Selection rules:
+                - Prefer an existing category from the list *only if* it is a good semantic fit.
+                - A valid category must:
+                - Name a stable system concept (component, data model, protocol, UI artifact, subsystem)
+                - Remain meaningful months later without task context
+                - Have high discriminative value (would not apply to most unrelated conversations)
+                - Do NOT select a category just because it exists in the list.
+
+                Creation rules (to avoid fragmentation):
+                - Create a new category ONLY if no existing category fits well.
+                - If creating a new category:
+                - Use a simple, canonical noun form
+                - Avoid re-ordering words that would create near-duplicates
+                - Prefer the most general stable concept (e.g., “agent” over “agent-runtime” unless runtime is explicitly the core topic)
+
+                Rejection rule:
+                - If all plausible categories (including those from the list) are low-signal or process-oriented, output [].
+
+                Before emitting categories, silently verify for each:
+                - It maps to an explicit noun phrase in the transcript
+                - It passes the “6-months later” test
+                - It would not create a near-duplicate of an existing category`,
+                        },
+                        {
+                            role: "user",
+                            content: `Please generate a title, summary, and status information for this conversation:\n\n${conversationContent}`,
+                        },
+                    ],
+                    z.object({
+                        title: z.string().describe("A concise title for the conversation (3-5 words)"),
+                        summary: z
+                            .string()
+                            .describe(
+                                "A 1-sentence, information-dense summary (<=160 chars) of key facts, scope, and blockers"
+                            ),
+                        status_label: z
+                            .string()
+                            .describe(
+                                "A concise status label (e.g., 'In Progress', 'Blocked', 'Waiting', 'Completed', 'Failed')"
+                            ),
+                        status_current_activity: z
+                            .string()
+                            .describe(
+                                "One dense clause consistent with status_label; no duplication or speculation"
+                            ),
+                        categories: z
+                            .array(z.string())
+                            .max(3)
+                            .describe(
+                                "0-3 category tags. Lowercase singular nouns. Prefer canonical list; create new only if necessary; may be empty []."
+                            ),
+                    })
+                );
+
+
+
+                // Publish metadata event
+                const ndk = getNDK();
+                const event = new NDKEventMetadata(ndk);
+                event.kind = NDKKind.EventMetadata;
+                event.setConversationId(conversation.id);
+
+                // Add metadata tags
+                if (result.title) {
+                    event.tags.push(["title", result.title]);
+                }
+                if (result.summary) {
+                    event.tags.push(["summary", result.summary]);
+                }
+                if (result.status_label) {
+                    event.tags.push(["status-label", result.status_label]);
+                }
+                if (result.status_current_activity) {
+                    event.tags.push(["status-current-activity", result.status_current_activity]);
+                }
+                if (result.categories && result.categories.length > 0) {
+                    for (const category of result.categories) {
+                        event.tags.push(["t", category]);
+                    }
+                }
+                event.tags.push(["a", this.context.project.tagId()]); // Project reference
+                event.tags.push(["model", summarizationConfig.model]);
+
+                // Sign and publish with backend signer
+                const backendSigner = await config.getBackendSigner();
+                await event.sign(backendSigner);
+                event.publish();
+                console.log(
+                    `Published metadata for conversation ${conversation.id}: ${result.title}`
+                );
+
+                // Also persist summary to local metadata for prompt fragments
+                // This ensures "Recent Conversations" section can display summaries
+                conversation.updateMetadata({
+                    summary: result.summary,
+                });
+                await conversation.save();
+
+                // Update category tally for future consistency
+                if (result.categories && result.categories.length > 0) {
+                    await this.categoryManager.updateCategories(result.categories);
+                }
+
+                span.setStatus({ code: SpanStatusCode.OK });
+            } catch (error) {
+                span.recordException(error as Error);
+                span.setStatus({ code: SpanStatusCode.ERROR });
+                console.error("Error generating conversation summary:", error);
+            } finally {
+                span.end();
+            }
+        });
+    }
+}

package/src/conversations/services/MetadataDebounceManager.ts

@@ -0,0 +1,188 @@
+import { logger } from "@/utils/logger";
+
+interface DebounceState {
+    timerId: NodeJS.Timeout | null;
+    firstExecutionDone: boolean;
+    maxDeadline: number; // Unix timestamp (ms)
+    pendingPublishFn: (() => Promise<void>) | null;
+}
+
+const DEBOUNCE_MS = 10_000; // 10 seconds
+const MAX_DELAY_MS = 5 * 60_000; // 5 minutes
+
+/**
+ * Manages debounced publishing of kind 513 metadata events at conversation level.
+ *
+ * Strategy:
+ * - First execution (or root event): publish immediately
+ * - Subsequent executions: debounce by 10 seconds
+ * - If another agent starts on same conversation: reset the debounce timer
+ * - Max delay of 5 minutes before forcing publication
+ */
+class MetadataDebounceManager {
+    private debounceStates = new Map<string, DebounceState>();
+
+    /**
+     * Called when an agent STARTS execution on a conversation.
+     * Resets any pending debounce timer (but preserves the publish function).
+     */
+    onAgentStart(conversationId: string): void {
+        const state = this.debounceStates.get(conversationId);
+        if (state?.timerId) {
+            clearTimeout(state.timerId);
+            state.timerId = null;
+            logger.debug("[MetadataDebounce] Timer reset on agent start", {
+                conversationId: conversationId.substring(0, 8),
+            });
+        }
+    }
+
+    /**
+     * Called when an agent COMPLETES execution.
+     * Either publishes immediately (first exec or root event) or schedules debounced publish.
+     */
+    schedulePublish(
+        conversationId: string,
+        isRootEvent: boolean,
+        publishFn: () => Promise<void>
+    ): void {
+        let state = this.debounceStates.get(conversationId);
+
+        // First execution or root event: publish immediately
+        if (!state || !state.firstExecutionDone || isRootEvent) {
+            logger.debug("[MetadataDebounce] Publishing immediately (first/root)", {
+                conversationId: conversationId.substring(0, 8),
+                isRootEvent,
+                isFirstExecution: !state?.firstExecutionDone,
+            });
+
+            // Initialize state
+            if (!state) {
+                state = {
+                    timerId: null,
+                    firstExecutionDone: true,
+                    maxDeadline: Date.now() + MAX_DELAY_MS,
+                    pendingPublishFn: null,
+                };
+                this.debounceStates.set(conversationId, state);
+            } else {
+                state.firstExecutionDone = true;
+                state.maxDeadline = Date.now() + MAX_DELAY_MS;
+            }
+
+            // Publish immediately (fire and forget)
+            publishFn().catch((error) => {
+                logger.error("[MetadataDebounce] Failed to publish metadata", {
+                    conversationId: conversationId.substring(0, 8),
+                    error,
+                });
+            });
+            return;
+        }
+
+        // Subsequent execution: debounce
+        // Clear existing timer if any
+        if (state.timerId) {
+            clearTimeout(state.timerId);
+            state.timerId = null;
+        }
+
+        // Update the pending publish function (use latest)
+        state.pendingPublishFn = publishFn;
+
+        const now = Date.now();
+
+        // Check if we've exceeded max deadline
+        if (now >= state.maxDeadline) {
+            logger.debug("[MetadataDebounce] Max deadline reached, publishing now", {
+                conversationId: conversationId.substring(0, 8),
+            });
+
+            // Reset deadline for next batch
+            state.maxDeadline = now + MAX_DELAY_MS;
+
+            publishFn().catch((error) => {
+                logger.error("[MetadataDebounce] Failed to publish metadata", {
+                    conversationId: conversationId.substring(0, 8),
+                    error,
+                });
+            });
+            return;
+        }
+
+        // Schedule debounced publish
+        const delay = Math.min(DEBOUNCE_MS, state.maxDeadline - now);
+
+        logger.debug("[MetadataDebounce] Scheduling debounced publish", {
+            conversationId: conversationId.substring(0, 8),
+            delayMs: delay,
+        });
+
+        state.timerId = setTimeout(() => {
+            const currentState = this.debounceStates.get(conversationId);
+            if (currentState?.pendingPublishFn) {
+                // Reset deadline for next batch
+                currentState.maxDeadline = Date.now() + MAX_DELAY_MS;
+                currentState.timerId = null;
+
+                currentState.pendingPublishFn().catch((error) => {
+                    logger.error("[MetadataDebounce] Failed to publish metadata (debounced)", {
+                        conversationId: conversationId.substring(0, 8),
+                        error,
+                    });
+                });
+                currentState.pendingPublishFn = null;
+            }
+        }, delay);
+    }
+
+    /**
+     * Mark the first publish as done for a conversation.
+     * This ensures subsequent schedulePublish calls will debounce instead of publishing immediately.
+     * Use this when doing immediate metadata generation outside the debounce manager.
+     */
+    markFirstPublishDone(conversationId: string): void {
+        let state = this.debounceStates.get(conversationId);
+        if (!state) {
+            state = {
+                timerId: null,
+                firstExecutionDone: true,
+                maxDeadline: Date.now() + MAX_DELAY_MS,
+                pendingPublishFn: null,
+            };
+            this.debounceStates.set(conversationId, state);
+        } else {
+            state.firstExecutionDone = true;
+        }
+        logger.debug("[MetadataDebounce] Marked first publish done", {
+            conversationId: conversationId.substring(0, 8),
+        });
+    }
+
+    /**
+     * Cleanup for a specific conversation. Clears timer without publishing.
+     */
+    cleanup(conversationId: string): void {
+        const state = this.debounceStates.get(conversationId);
+        if (state?.timerId) {
+            clearTimeout(state.timerId);
+        }
+        this.debounceStates.delete(conversationId);
+    }
+
+    /**
+     * Cleanup all state. Called on shutdown.
+     */
+    cleanupAll(): void {
+        for (const state of this.debounceStates.values()) {
+            if (state.timerId) {
+                clearTimeout(state.timerId);
+            }
+        }
+        this.debounceStates.clear();
+        logger.debug("[MetadataDebounce] All timers cleared on shutdown");
+    }
+}
+
+// Singleton instance
+export const metadataDebounceManager = new MetadataDebounceManager();

package/src/conversations/services/index.ts

@@ -0,0 +1,2 @@
+export { CategoryManager, type CategoryTally } from "./CategoryManager";
+export { ConversationResolver, type ConversationResolutionResult } from "./ConversationResolver";

package/src/conversations/types.ts

@@ -0,0 +1,148 @@
+import type { ToolCallPart, ToolResultPart } from "ai";
+import type { TodoItem } from "@/services/ral/types";
+
+export type MessageType = "text" | "tool-call" | "tool-result" | "delegation-marker";
+
+/**
+ * Marker stored in conversation history to track delegation lifecycle.
+ * Markers are created immediately when a delegation is initiated (status: "pending"),
+ * and updated when the delegation completes or is aborted.
+ * Instead of embedding the full transcript inline, we store a reference
+ * and lazily expand it when building messages.
+ */
+export interface DelegationMarker {
+    /** The delegation conversation ID (used to retrieve transcript) */
+    delegationConversationId: string;
+    /** The agent pubkey that received the delegation */
+    recipientPubkey: string;
+    /** The conversation ID of the parent (delegator) - for direct-child validation */
+    parentConversationId: string;
+    /** When the delegation was initiated (Unix timestamp in seconds) */
+    initiatedAt?: number;
+    /** When the delegation completed (Unix timestamp in seconds) - only set when completed/aborted */
+    completedAt?: number;
+    /** Delegation status: pending (in progress), completed (successful), or aborted */
+    status: "pending" | "completed" | "aborted";
+    /** If aborted, the reason for the abort */
+    abortReason?: string;
+}
+
+export interface ConversationEntry {
+    pubkey: string;
+    ral?: number; // Only for agent messages
+    content: string; // Text content (for text messages) or empty for tool messages
+    messageType: MessageType;
+    toolData?: ToolCallPart[] | ToolResultPart[]; // Only for tool-call and tool-result
+    eventId?: string; // If published to Nostr
+    timestamp?: number; // Unix timestamp (seconds) - from NDKEvent.created_at or Date.now()/1000
+    targetedPubkeys?: string[]; // Agent pubkeys this message is directed to (from p-tags)
+    /** Original sender pubkey for injected messages (for attribution when sender differs from expected) */
+    senderPubkey?: string;
+    /**
+     * Explicit role override for synthetic entries (e.g., compressed summaries).
+     * When present, this role is used instead of deriving from pubkey.
+     * Used to ensure compressed summaries are rendered as "system" role, not "user".
+     */
+    role?: "user" | "assistant" | "tool" | "system";
+    /**
+     * For delegation-marker messageType: contains the marker data.
+     * This allows lazy expansion of delegation transcripts when building messages.
+     */
+    delegationMarker?: DelegationMarker;
+}
+
+export interface Injection {
+    targetRal: { pubkey: string; ral: number };
+    role: "user" | "system";
+    content: string;
+    queuedAt: number;
+}
+
+/**
+ * Deferred injection - a message to be injected on the agent's NEXT turn.
+ *
+ * Unlike Injection which targets a specific RAL, DeferredInjection is consumed
+ * at the START of any future RAL for the target agent. This is used for
+ * supervision messages that should NOT block the current completion but should
+ * appear in the agent's next conversation turn.
+ */
+export interface DeferredInjection {
+    /** The agent pubkey this injection is for */
+    targetPubkey: string;
+    /** The role of the injected message */
+    role: "system";
+    /** The message content */
+    content: string;
+    /** When this injection was queued (ms since epoch) */
+    queuedAt: number;
+    /** Optional source identifier for debugging (e.g., "supervision:consecutive-tools-without-todo") */
+    source?: string;
+}
+
+/**
+ * Represents a participant in the delegation chain.
+ * Can be either a human user or an agent.
+ */
+export interface DelegationChainEntry {
+    /** The pubkey of the participant */
+    pubkey: string;
+    /** The display name (agent slug or shortened pubkey) */
+    displayName: string;
+    /** Whether this is the project owner/human user */
+    isUser: boolean;
+    /** The conversation ID where this delegation occurred (full ID, truncated only at display time) */
+    conversationId?: string;
+}
+
+export interface ConversationMetadata {
+    title?: string;
+    branch?: string;
+    summary?: string;
+    requirements?: string;
+    plan?: string;
+    projectPath?: string;
+    last_user_message?: string;
+    statusLabel?: string;
+    statusCurrentActivity?: string;
+    referencedArticle?: {
+        title: string;
+        content: string;
+        dTag: string;
+    };
+    /**
+     * The delegation chain showing who initiated this conversation.
+     * First entry is the original initiator (typically User), last entry is the current agent.
+     * Example: [User, pm-wip, execution-coordinator, claude-code]
+     */
+    delegationChain?: DelegationChainEntry[];
+}
+
+export interface RalTracker {
+    id: number;
+}
+
+export interface ExecutionTime {
+    totalSeconds: number;
+    currentSessionStart?: number;
+    isActive: boolean;
+    lastUpdated: number;
+}
+
+export interface ConversationState {
+    activeRal: Record<string, RalTracker[]>;
+    nextRalNumber: Record<string, number>;
+    injections: Injection[];
+    messages: ConversationEntry[];
+    metadata: ConversationMetadata;
+    agentTodos: Record<string, TodoItem[]>;
+    todoNudgedAgents: string[]; // Agents who have been nudged about todo usage
+    blockedAgents: string[];
+    executionTime: ExecutionTime;
+    /** Meta model variant override per agent - when set, uses this variant instead of keyword detection */
+    metaModelVariantOverride?: Record<string, string>; // agentPubkey -> variantName
+    /**
+     * Deferred injections - messages to be injected on an agent's NEXT turn.
+     * Used by supervision for non-blocking nudges that shouldn't prevent completion.
+     */
+    deferredInjections?: DeferredInjection[];
+}

package/src/conversations/utils/content-utils.ts

@@ -0,0 +1,69 @@
+/**
+ * Content utilities for processing conversation messages
+ * Purpose: Strip <thinking>...</thinking> blocks from conversation history; skip messages that are purely thinking blocks.
+ * Also filter out events with reasoning tags.
+ */
+
+import type { NDKEvent } from "@nostr-dev-kit/ndk";
+
+/**
+ * Regex pattern to match thinking blocks (case-insensitive, multi-line)
+ * Matches: <thinking>, <Thinking>, <THINKING> with any attributes and their closing tags
+ */
+const THINKING_BLOCK_REGEX = /<thinking\b[^>]*>[\s\S]*?<\/thinking>/gi;
+
+/**
+ * Remove all thinking blocks from content
+ * @param content - The content to process
+ * @returns The content with all thinking blocks removed and normalized whitespace (multiple blank lines collapsed to single newline)
+ */
+export function stripThinkingBlocks(content: string): string {
+    if (!content) return "";
+
+    // Remove all thinking blocks
+    let stripped = content.replace(THINKING_BLOCK_REGEX, "");
+
+    // Normalize whitespace more carefully:
+    // 1. Only collapse multiple spaces that aren't at the beginning of a line (preserve indentation)
+    // 2. Collapse multiple blank lines to a single newline
+    stripped = stripped
+        .split("\n")
+        .map((line) => {
+            // Only collapse spaces in the middle of lines, not at the start (preserve indentation)
+            if (line.trimStart() !== line) {
+                // Line has leading whitespace - preserve it
+                const leadingWhitespace = line.match(/^\s*/)?.[0] || "";
+                const rest = line.slice(leadingWhitespace.length);
+                return leadingWhitespace + rest.replace(/ {2,}/g, " ");
+            }
+            // No leading whitespace - collapse all multiple spaces
+            return line.replace(/ {2,}/g, " ");
+        })
+        .join("\n")
+        .replace(/\n\s*\n+/g, "\n") // Collapse 2+ newlines to single newline
+        .trim(); // Trim leading/trailing whitespace
+
+    return stripped;
+}
+
+/**
+ * Check if content contains only thinking blocks (no other content)
+ * @param content - The content to check
+ * @returns True if the content is empty after removing thinking blocks
+ */
+export function isOnlyThinkingBlocks(content: string): boolean {
+    if (!content || content.trim().length === 0) return false; // Empty/whitespace content is not "only thinking blocks"
+
+    const stripped = stripThinkingBlocks(content);
+    return stripped.length === 0;
+}
+
+/**
+ * Check if an event has a reasoning tag
+ * @param event - The NDK event to check
+ * @returns True if the event has a ["reasoning"] tag
+ */
+export function hasReasoningTag(event: NDKEvent): boolean {
+    if (!event.tags) return false;
+    return event.tags.some((tag) => tag[0] === "reasoning" && tag.length === 1);
+}