@tenex-chat/backend 0.9.1

package/src/daemon/SubscriptionManager.ts

@@ -0,0 +1,305 @@
+import type { EventRoutingLogger } from "@/logging/EventRoutingLogger";
+import { logger } from "@/utils/logger";
+import type { Hexpubkey, NDKEvent, NDKFilter, NDKSubscription } from "@nostr-dev-kit/ndk";
+import type NDK from "@nostr-dev-kit/ndk";
+import { SubscriptionFilterBuilder } from "./filters/SubscriptionFilterBuilder";
+
+/**
+ * Manages independent subscriptions for different event categories.
+ *
+ * Instead of a single monolithic subscription that is torn down and recreated
+ * whenever any tracked set changes, this manager maintains four independent
+ * subscription groups:
+ *
+ * 1. Static — project discovery, config updates, lesson comments (never recreated)
+ * 2. Known-projects — events tagged with project a-tags (recreated on project changes)
+ * 3. Agent-mentions — events p-tagging agents (recreated on agent pubkey changes)
+ * 4. Per-agent lessons — one per agent definition ID (individually managed)
+ */
+export class SubscriptionManager {
+    private ndk: NDK;
+    private eventHandler: (event: NDKEvent) => Promise<void>;
+    private routingLogger: EventRoutingLogger;
+    private whitelistedPubkeys: Set<Hexpubkey>;
+
+    // Dedup: multiple subscriptions can deliver the same event
+    private recentEventIds = new Set<string>();
+    private recentEventTimer: NodeJS.Timeout | null = null;
+
+    // Independent subscription groups
+    private staticSubscription: NDKSubscription | null = null;
+    private projectSubscription: NDKSubscription | null = null;
+    private agentMentionsSubscription: NDKSubscription | null = null;
+    private lessonSubscriptions = new Map<string, NDKSubscription>();
+
+    // Per-subscription since tracking
+    private lastProjectSubCreatedAt: number | null = null;
+    private lastAgentMentionsSubCreatedAt: number | null = null;
+
+    // Debounce for agent mentions updates
+    private agentMentionsTimer: NodeJS.Timeout | null = null;
+    private pendingAgentMentionsPubkeys: Set<Hexpubkey> | null = null;
+
+    constructor(
+        ndk: NDK,
+        eventHandler: (event: NDKEvent) => Promise<void>,
+        whitelistedPubkeys: Hexpubkey[],
+        routingLogger: EventRoutingLogger
+    ) {
+        this.ndk = ndk;
+        this.eventHandler = eventHandler;
+        this.whitelistedPubkeys = new Set(whitelistedPubkeys);
+        this.routingLogger = routingLogger;
+    }
+
+    /**
+     * Start subscriptions. Creates the static subscription immediately.
+     * Project and agent-mentions subscriptions are created later as data arrives.
+     */
+    async start(): Promise<void> {
+        logger.debug("Starting subscription manager", {
+            whitelistedPubkeys: Array.from(this.whitelistedPubkeys).map((p) => p.slice(0, 8)),
+        });
+
+        const filters = SubscriptionFilterBuilder.buildStaticFilters(this.whitelistedPubkeys);
+        if (filters.length > 0) {
+            this.staticSubscription = this.createSub(filters, "static");
+        }
+
+        await this.routingLogger.logSubscriptionFilters({
+            filters,
+            whitelistedAuthors: this.whitelistedPubkeys.size,
+            trackedProjects: 0,
+            trackedAgents: 0,
+        });
+    }
+
+    /**
+     * Update known projects. Recreates the project subscription with new project IDs.
+     * Uses `since` on restarts to prevent historical event re-delivery.
+     */
+    updateKnownProjects(projectIds: string[]): void {
+        const knownProjects = new Set(projectIds);
+
+        // Stop existing project subscription
+        if (this.projectSubscription) {
+            this.projectSubscription.stop();
+            this.projectSubscription = null;
+        }
+
+        if (knownProjects.size === 0) {
+            return;
+        }
+
+        const since = this.lastProjectSubCreatedAt ?? undefined;
+        this.lastProjectSubCreatedAt = Math.floor(Date.now() / 1000);
+
+        const filters: NDKFilter[] = [];
+
+        const taggedFilter = SubscriptionFilterBuilder.buildProjectTaggedFilter(knownProjects, since);
+        if (taggedFilter) filters.push(taggedFilter);
+
+        const reportFilter = SubscriptionFilterBuilder.buildReportFilter(knownProjects);
+        if (reportFilter) filters.push(reportFilter);
+
+        if (filters.length > 0) {
+            this.projectSubscription = this.createSub(filters, "projects");
+            logger.debug("Project subscription updated", {
+                projects: knownProjects.size,
+                since,
+            });
+        }
+    }
+
+    /**
+     * Update agent mentions subscription. Debounced with 2s timer since
+     * agent additions can batch (e.g. during project boot with multiple agents).
+     */
+    updateAgentMentions(pubkeys: Hexpubkey[]): void {
+        this.pendingAgentMentionsPubkeys = new Set(pubkeys);
+
+        if (this.agentMentionsTimer) {
+            clearTimeout(this.agentMentionsTimer);
+        }
+
+        this.agentMentionsTimer = setTimeout(() => {
+            this.agentMentionsTimer = null;
+            this.applyAgentMentionsUpdate();
+        }, 2000);
+    }
+
+    private applyAgentMentionsUpdate(): void {
+        const pubkeys = this.pendingAgentMentionsPubkeys;
+        this.pendingAgentMentionsPubkeys = null;
+
+        if (!pubkeys) return;
+
+        // Stop existing agent mentions subscription
+        if (this.agentMentionsSubscription) {
+            this.agentMentionsSubscription.stop();
+            this.agentMentionsSubscription = null;
+        }
+
+        if (pubkeys.size === 0) {
+            return;
+        }
+
+        const since = this.lastAgentMentionsSubCreatedAt ?? undefined;
+        this.lastAgentMentionsSubCreatedAt = Math.floor(Date.now() / 1000);
+
+        const filter = SubscriptionFilterBuilder.buildAgentMentionsFilter(pubkeys, since);
+        if (filter) {
+            this.agentMentionsSubscription = this.createSub([filter], "agent-mentions");
+            logger.debug("Agent mentions subscription updated", {
+                agents: pubkeys.size,
+                since,
+            });
+        }
+    }
+
+    /**
+     * Add a lesson subscription for a specific agent definition ID.
+     * Uses NDK groupable to merge with other lesson subscriptions.
+     */
+    addLessonSubscription(definitionId: string): void {
+        if (this.lessonSubscriptions.has(definitionId)) {
+            return;
+        }
+
+        const filter = SubscriptionFilterBuilder.buildLessonFilter(definitionId);
+        const sub = this.ndk.subscribe([filter], {
+            closeOnEose: false,
+            groupable: true,
+            onEvent: (event: NDKEvent) => this.handleEvent(event),
+        });
+
+        this.lessonSubscriptions.set(definitionId, sub);
+        logger.debug("Lesson subscription added", {
+            definitionId: definitionId.substring(0, 12),
+            totalLessonSubs: this.lessonSubscriptions.size,
+        });
+    }
+
+    /**
+     * Remove a lesson subscription for a specific agent definition ID.
+     */
+    removeLessonSubscription(definitionId: string): void {
+        const sub = this.lessonSubscriptions.get(definitionId);
+        if (sub) {
+            sub.stop();
+            this.lessonSubscriptions.delete(definitionId);
+            logger.debug("Lesson subscription removed", {
+                definitionId: definitionId.substring(0, 12),
+                totalLessonSubs: this.lessonSubscriptions.size,
+            });
+        }
+    }
+
+    /**
+     * Stop all subscriptions.
+     */
+    stop(): void {
+        if (this.agentMentionsTimer) {
+            clearTimeout(this.agentMentionsTimer);
+            this.agentMentionsTimer = null;
+        }
+
+        if (this.recentEventTimer) {
+            clearTimeout(this.recentEventTimer);
+            this.recentEventTimer = null;
+        }
+        this.recentEventIds.clear();
+
+        if (this.staticSubscription) {
+            this.staticSubscription.stop();
+            this.staticSubscription = null;
+        }
+
+        if (this.projectSubscription) {
+            this.projectSubscription.stop();
+            this.projectSubscription = null;
+        }
+
+        if (this.agentMentionsSubscription) {
+            this.agentMentionsSubscription.stop();
+            this.agentMentionsSubscription = null;
+        }
+
+        for (const [, sub] of this.lessonSubscriptions) {
+            sub.stop();
+        }
+        this.lessonSubscriptions.clear();
+
+        logger.debug("All subscriptions stopped");
+    }
+
+    /**
+     * Get current subscription status.
+     */
+    getStatus(): {
+        active: boolean;
+        whitelistedPubkeys: number;
+        staticActive: boolean;
+        projectActive: boolean;
+        agentMentionsActive: boolean;
+        lessonSubscriptions: number;
+    } {
+        return {
+            active: this.staticSubscription !== null,
+            whitelistedPubkeys: this.whitelistedPubkeys.size,
+            staticActive: this.staticSubscription !== null,
+            projectActive: this.projectSubscription !== null,
+            agentMentionsActive: this.agentMentionsSubscription !== null,
+            lessonSubscriptions: this.lessonSubscriptions.size,
+        };
+    }
+
+    /**
+     * Create an NDK subscription with the shared event handler.
+     */
+    private createSub(filters: NDKFilter[], label: string): NDKSubscription {
+        const sub = this.ndk.subscribe(filters, {
+            closeOnEose: false,
+            groupable: false,
+            onEvent: (event: NDKEvent) => this.handleEvent(event),
+            onEose: () => {
+                logger.debug(`Subscription EOSE received [${label}]`);
+            },
+        });
+
+        return sub;
+    }
+
+    /**
+     * Handle incoming events from any subscription.
+     * Deduplicates across independent subscriptions — the same event can match
+     * both the project (#a) and agent-mentions (#p) filters.
+     */
+    private async handleEvent(event: NDKEvent): Promise<void> {
+        if (this.recentEventIds.has(event.id)) return;
+        this.recentEventIds.add(event.id);
+        this.scheduleEventIdCleanup();
+
+        try {
+            await this.eventHandler(event);
+        } catch (error) {
+            logger.error("Error handling event in subscription", {
+                error: error instanceof Error ? error.message : String(error),
+                eventId: event.id,
+                eventKind: event.kind,
+            });
+        }
+    }
+
+    /**
+     * Periodically flush the seen-event set to prevent unbounded growth.
+     * Batches cleanup into 60s intervals.
+     */
+    private scheduleEventIdCleanup(): void {
+        if (this.recentEventTimer) return;
+        this.recentEventTimer = setTimeout(() => {
+            this.recentEventIds.clear();
+            this.recentEventTimer = null;
+        }, 60_000);
+    }
+}

package/src/daemon/UnixSocketTransport.ts

@@ -0,0 +1,318 @@
+import * as net from "net";
+import * as fs from "fs";
+import * as path from "path";
+import type { StreamTransport } from "@/llm";
+import type { LocalStreamChunk } from "@/llm";
+import { logger } from "@/utils/logger";
+
+const LOG_PREFIX = "[UnixSocketTransport]";
+
+/** Extract a brief caller context from stack trace for debugging (only computed when debug logging enabled) */
+function getCallerContext(): string | undefined {
+    // Only compute stack trace if debug logging is actually enabled
+    // This avoids the expensive stack capture in production
+    if (!logger.isLevelEnabled?.("debug")) {
+        return undefined;
+    }
+    const stack = new Error().stack;
+    if (!stack) return undefined;
+    // Skip first 3 lines: Error, getCallerContext, cleanup/caller
+    const lines = stack.split("\n").slice(3, 6);
+    return lines.map((l) => l.trim()).join(" <- ");
+}
+
+/** Result of checking socket file info */
+type SocketFileInfoResult =
+    | { status: "ok"; exists: true; isSocket: boolean; isFile: boolean; mode: string; mtime: string; age: string }
+    | { status: "ok"; exists: false }
+    | { status: "error"; error: string };
+
+/**
+ * Unix domain socket transport for local streaming
+ * Single client connection model
+ */
+export class UnixSocketTransport implements StreamTransport {
+    private server: net.Server | null = null;
+    private client: net.Socket | null = null;
+    private socketPath: string;
+
+    constructor(socketPath?: string) {
+        this.socketPath = socketPath ?? this.defaultSocketPath();
+    }
+
+    private defaultSocketPath(): string {
+        const runtimeDir = process.env.XDG_RUNTIME_DIR;
+        if (runtimeDir) {
+            return path.join(runtimeDir, "tenex-stream.sock");
+        }
+        return "/tmp/tenex-stream.sock";
+    }
+
+    async start(): Promise<void> {
+        logger.info(`${LOG_PREFIX} start() called`, {
+            socketPath: this.socketPath,
+        });
+
+        // Check for existing socket and log details
+        const existingSocketInfo = this.getSocketFileInfo();
+        if (existingSocketInfo.status === "ok" && existingSocketInfo.exists) {
+            logger.warn(`${LOG_PREFIX} Stale socket found before start`, {
+                socketPath: this.socketPath,
+                isSocket: existingSocketInfo.isSocket,
+                age: existingSocketInfo.age,
+            });
+        } else if (existingSocketInfo.status === "error") {
+            logger.error(`${LOG_PREFIX} Failed to check socket file before start`, {
+                socketPath: this.socketPath,
+                error: existingSocketInfo.error,
+            });
+        }
+
+        // Clean up stale socket, passing the file info we already have
+        this.cleanup("start() - cleaning stale socket before creating new one", existingSocketInfo);
+
+        return new Promise((resolve, reject) => {
+            this.server = net.createServer((socket) => {
+                logger.info(`${LOG_PREFIX} Client connected to streaming socket`, {
+                    socketPath: this.socketPath,
+                });
+
+                // Only one client at a time
+                if (this.client) {
+                    logger.warn(`${LOG_PREFIX} Replacing existing client connection`, {
+                        socketPath: this.socketPath,
+                    });
+                    this.client.destroy();
+                }
+
+                this.client = socket;
+
+                socket.on("close", () => {
+                    logger.info(`${LOG_PREFIX} Client disconnected from streaming socket`, {
+                        socketPath: this.socketPath,
+                    });
+                    if (this.client === socket) {
+                        this.client = null;
+                    }
+                });
+
+                socket.on("error", (err) => {
+                    logger.error(`${LOG_PREFIX} Socket client error`, {
+                        error: err.message,
+                        socketPath: this.socketPath,
+                    });
+                    if (this.client === socket) {
+                        this.client = null;
+                    }
+                });
+            });
+
+            this.server.on("error", (err) => {
+                logger.error(`${LOG_PREFIX} Socket server error`, {
+                    error: err.message,
+                    socketPath: this.socketPath,
+                });
+                reject(err);
+            });
+
+            this.server.listen(this.socketPath, () => {
+                logger.info(`${LOG_PREFIX} Streaming socket started and listening`, {
+                    socketPath: this.socketPath,
+                });
+                resolve();
+            });
+        });
+    }
+
+    write(chunk: LocalStreamChunk): void {
+        if (!this.client) return;
+
+        try {
+            const line = JSON.stringify(chunk) + "\n";
+            this.client.write(line);
+        } catch (err) {
+            logger.error(`${LOG_PREFIX} Failed to write chunk`, {
+                error: err instanceof Error ? err.message : String(err),
+                socketPath: this.socketPath,
+            });
+        }
+    }
+
+    isConnected(): boolean {
+        return this.client !== null && !this.client.destroyed;
+    }
+
+    async stop(): Promise<void> {
+        const callerContext = getCallerContext();
+        logger.info(`${LOG_PREFIX} stop() called`, {
+            socketPath: this.socketPath,
+            hasClient: !!this.client,
+            hasServer: !!this.server,
+            ...(callerContext && { callerContext }),
+        });
+
+        if (this.client) {
+            logger.info(`${LOG_PREFIX} Destroying client connection in stop()`, {
+                socketPath: this.socketPath,
+            });
+            this.client.destroy();
+            this.client = null;
+        }
+
+        return new Promise((resolve) => {
+            if (this.server) {
+                logger.info(`${LOG_PREFIX} Closing server in stop()`, {
+                    socketPath: this.socketPath,
+                });
+                this.server.close(() => {
+                    logger.info(`${LOG_PREFIX} Server closed, now calling cleanup()`, {
+                        socketPath: this.socketPath,
+                    });
+                    this.cleanup("stop() - server closed callback");
+                    logger.info(`${LOG_PREFIX} stop() completed`, {
+                        socketPath: this.socketPath,
+                    });
+                    resolve();
+                });
+            } else {
+                logger.info(`${LOG_PREFIX} stop() called but no server to close`, {
+                    socketPath: this.socketPath,
+                });
+                resolve();
+            }
+        });
+    }
+
+    /**
+     * Get file info for the socket path (for debugging)
+     * Returns discriminated result: ok (exists/not), or error
+     */
+    private getSocketFileInfo(): SocketFileInfoResult {
+        try {
+            const stats = fs.lstatSync(this.socketPath);
+            const ageMs = Date.now() - stats.mtime.getTime();
+            return {
+                status: "ok",
+                exists: true,
+                isSocket: stats.isSocket(),
+                isFile: stats.isFile(),
+                mode: stats.mode.toString(8),
+                mtime: stats.mtime.toISOString(),
+                age: `${Math.floor(ageMs / 1000)}s`,
+            };
+        } catch (err) {
+            // ENOENT means file doesn't exist - that's a valid "missing" result
+            if (err instanceof Error && "code" in err && (err as NodeJS.ErrnoException).code === "ENOENT") {
+                return { status: "ok", exists: false };
+            }
+            // Any other error (permission, IO, etc.) is an actual error
+            return {
+                status: "error",
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+
+    /**
+     * Check if socket exists and is healthy
+     */
+    checkSocketHealth(): {
+        exists: boolean;
+        isSocket: boolean;
+        serverRunning: boolean;
+        clientConnected: boolean;
+    } {
+        const info = this.getSocketFileInfo();
+        const exists = info.status === "ok" && info.exists;
+        const isSocket = info.status === "ok" && info.exists && info.isSocket;
+        const result = {
+            exists,
+            isSocket,
+            serverRunning: this.server !== null && this.server.listening,
+            clientConnected: this.isConnected(),
+        };
+        logger.debug(`${LOG_PREFIX} Health check`, {
+            socketPath: this.socketPath,
+            ...result,
+        });
+        return result;
+    }
+
+    /**
+     * Clean up socket file if it exists and is safe to remove
+     * @param reason - Why cleanup is being called (for logging)
+     * @param fileInfo - Optional pre-fetched file info to avoid redundant FS calls
+     */
+    private cleanup(reason: string, fileInfo?: SocketFileInfoResult): void {
+        const callerContext = getCallerContext();
+
+        logger.info(`${LOG_PREFIX} cleanup() called`, {
+            socketPath: this.socketPath,
+            reason,
+            ...(callerContext && { callerContext }),
+        });
+
+        // Use provided file info or fetch it
+        const info = fileInfo ?? this.getSocketFileInfo();
+
+        // Handle error case
+        if (info.status === "error") {
+            logger.error(`${LOG_PREFIX} cleanup() cannot proceed - failed to check socket file`, {
+                socketPath: this.socketPath,
+                reason,
+                error: info.error,
+            });
+            return;
+        }
+
+        // Nothing to clean up
+        if (!info.exists) {
+            logger.debug(`${LOG_PREFIX} cleanup() - socket does not exist, nothing to unlink`, {
+                socketPath: this.socketPath,
+                reason,
+            });
+            return;
+        }
+
+        // CRITICAL SAFETY CHECK: Only unlink if it's actually a socket
+        if (!info.isSocket) {
+            logger.error(`${LOG_PREFIX} cleanup() REFUSED to unlink - path is not a socket`, {
+                socketPath: this.socketPath,
+                reason,
+                isFile: info.isFile,
+                mode: info.mode,
+            });
+            return;
+        }
+
+        // Safe to unlink - it's a socket
+        try {
+            logger.info(`${LOG_PREFIX} About to unlink socket`, {
+                socketPath: this.socketPath,
+                reason,
+                age: info.age,
+            });
+
+            fs.unlinkSync(this.socketPath);
+
+            logger.info(`${LOG_PREFIX} Socket unlinked successfully`, {
+                socketPath: this.socketPath,
+                reason,
+            });
+        } catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            const errorCode = err instanceof Error && "code" in err ? (err as NodeJS.ErrnoException).code : undefined;
+
+            logger.error(`${LOG_PREFIX} cleanup() failed to unlink socket`, {
+                socketPath: this.socketPath,
+                reason,
+                error: errorMessage,
+                errorCode,
+            });
+        }
+    }
+
+    getSocketPath(): string {
+        return this.socketPath;
+    }
+}